Workflow enhacements

[khaliqgant]

Summary

This PR introduces significant enhancements to the relay broker-sdk workflow system, making it more robust for multi-agent orchestration.

Key Changes

• PTY-based output capture: Workflow runner now collects agent terminal output directly instead of relying on file-based summaries, enabling real-time step output chaining via {{steps.X.output}}
• Dedicated workflow channels: Auto-generates wf-{name}-{id} channels for workflow isolation instead of using shared general channel
• Agent self-termination: Changed from remove_agent MCP call to /exit PTY output to avoid workspace misalignment issues
• Credential handling: RELAY_API_KEY is now optional - runner auto-provisions via Relaycast and validates API keys before trusting cached credentials
• MCP server migration: Switched from @agent-relay/mcp to @relaycast/mcp with credential file-based authentication
• Rust broker enhancements: Added run_init handler for agent.release_requested WebSocket events and listen --all flag
• Resource management: Fixed PTY resource leaks with proper cleanup in finally blocks and PTY map re-keying when broker assigns different agent names

New Features

• Workflow skill documentation: Comprehensive guide for building multi-agent workflows with the WorkflowBuilder API
• Step output persistence: Outputs saved to disk and Relaycast channel messages
• Example workflow: 1,486-line workflow-superiority.ts demonstrating a 9-agent, 23-step DAG campaign

Files Changed

File	Changes
.claude/skills/writing-agent-relay-workflows/SKILL.md	New skill documentation for workflow building
packages/broker-sdk/src/workflows/runner.ts	Major revamp with PTY capture, dedicated channels, cleanup
packages/broker-sdk/src/examples/workflow-superiority.ts	New comprehensive multi-agent workflow example
src/main.rs	WebSocket event handlers and --all flag
.mcp.json	MCP server migration to @relaycast/mcp
packages/broker-sdk/src/relaycast.ts	API key validation

Test plan

• Verify workflow runner correctly captures PTY output from agents
• Confirm dedicated channels are created with wf-{name}-{id} format
• Test agent self-termination via /exit PTY output
• Validate Relaycast credential caching and validation
• Run existing broker-sdk tests to ensure no regressions
• Test listen --all flag subscribes to all workspace channels

---

🤖 Generated with Claude Code

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 13 additional findings in Devin Review.

[devin-ai-integration]

🔴 YAML indentation error causes review outputs to be parsed as step-level keys instead of task content

In the code-review.yaml builtin template, the newly added lines referencing step outputs (Architecture review:, Correctness review:, Security review:) are indented at the same level as the task: key (10 spaces), not inside the YAML block scalar (12 spaces). This means YAML will parse them as new mapping keys at the step object level rather than as part of the task string.

Root Cause and Impact

The task: | block scalar at packages/broker-sdk/src/workflows/builtin-templates/code-review.yaml:66 requires its content to be indented more than the key itself. The original content line Produce merged findings... is correctly at 12 spaces, but the three new lines are at 10 spaces — the same level as task:, agent:, dependsOn:, etc.

YAML parsing will treat the added lines as separate keys in the step mapping:

# What YAML actually sees:
- name: consolidate
  task: |              # block scalar content is ONLY "Produce merged..."
    Produce merged findings, severity levels, and final recommendation.
  Architecture review: "{{steps.architecture-pass.output}}"  # ← new key!
  Correctness review: "{{steps.correctness-pass.output}}"    # ← new key!
  Security review: "{{steps.security-pass.output}}"          # ← new key!

Impact: The consolidation step's task will NOT include the review outputs from prior steps. Since the WorkflowStep schema has additionalProperties: false, this would also fail JSON Schema validation. Even without strict validation, the agent performing the consolidation step receives no review context, making the entire code-review workflow's final step useless.

Suggested change

	Architecture review: {{steps.architecture-pass.output}}
	Correctness review: {{steps.correctness-pass.output}}
	Security review: {{steps.security-pass.output}}
	Architecture review: {{steps.architecture-pass.output}}
	Correctness review: {{steps.correctness-pass.output}}
	Security review: {{steps.security-pass.output}}

---

Was this helpful? React with 👍 or 👎 to provide feedback.