agent-relay 3.2.15 → 3.2.17

package/packages/sdk/src/workflows/runner.ts

@@ -36,6 +36,7 @@ import {
   CustomStepResolutionError,
 } from './custom-steps.js';
 import { collectCliSession, type CliSessionReport } from './cli-session-collector.js';
+import { executeApiStep } from './api-executor.js';
 import { InMemoryWorkflowDb } from './memory-db.js';
 import { formatRunSummaryTable } from './run-summary-table.js';
 import type {
@@ -180,6 +181,7 @@ export interface WorkflowRunnerOptions {
   cwd?: string;
   summaryDir?: string;
   executor?: StepExecutor;
+  envSecrets?: Record<string, string>;
 }
 
 // ── Step executor interface ──────────────────────────────────────────────────
@@ -202,6 +204,12 @@ export interface StepExecutor {
     resolvedCommand: string,
     cwd: string
   ): Promise<{ output: string; exitCode: number }>;
+
+  executeIntegrationStep?(
+    step: WorkflowStep,
+    resolvedParams: Record<string, string>,
+    context: { workspaceId?: string }
+  ): Promise<{ output: string; success: boolean }>;
 }
 
 // ── Variable context for template resolution ────────────────────────────────
@@ -297,6 +305,7 @@ export class WorkflowRunner {
   private readonly cwd: string;
   private readonly summaryDir: string;
   private readonly executor?: StepExecutor;
+  private readonly envSecrets?: Record<string, string>;
 
   /** @internal exposed for CLI signal-handler shutdown only */
   relay?: AgentRelay;
@@ -364,6 +373,7 @@ export class WorkflowRunner {
     this.summaryDir = options.summaryDir ?? path.join(this.cwd, '.relay', 'summaries');
     this.workersPath = path.join(this.cwd, '.agent-relay', 'team', 'workers.json');
     this.executor = options.executor;
+    this.envSecrets = options.envSecrets;
   }
 
   // ── Path resolution ─────────────────────────────────────────────────────
@@ -1502,7 +1512,7 @@ export class WorkflowRunner {
     // 6. Resource estimation
     const peakConcurrency = Math.max(...waves.map((w) => w.steps.length), 0);
     const totalAgentSteps = resolvedSteps.filter(
-      (s) => s.type !== 'deterministic' && s.type !== 'worktree'
+      (s) => s.type !== 'deterministic' && s.type !== 'worktree' && s.type !== 'integration'
     ).length;
 
     // 7. Check maxConcurrency against wave widths
@@ -1559,6 +1569,14 @@ export class WorkflowRunner {
         if (typeof s.command !== 'string') {
           throw new Error(`${source}: deterministic step "${s.name}" must have a "command" field`);
         }
+      } else if (s.type === 'integration') {
+        // Integration steps require integration and action
+        if (typeof s.integration !== 'string') {
+          throw new Error(`${source}: integration step "${s.name}" must have an "integration" string field`);
+        }
+        if (typeof s.action !== 'string') {
+          throw new Error(`${source}: integration step "${s.name}" must have an "action" string field`);
+        }
       } else {
         // Agent steps (type undefined or 'agent') require agent and task
         if (typeof s.agent !== 'string' || typeof s.task !== 'string') {
@@ -1583,7 +1601,7 @@ export class WorkflowRunner {
 
     // Warn if non-interactive agent task is excessively large before interpolation
     for (const step of w.steps as WorkflowStep[]) {
-      if (step.type === 'deterministic' || step.type === 'worktree') continue;
+      if (step.type === 'deterministic' || step.type === 'worktree' || step.type === 'integration') continue;
       const agentDef = agents.find((a) => a.name === step.agent);
       const isNonInteractive =
         agentDef?.interactive === false || ['worker', 'reviewer', 'analyst'].includes(agentDef?.preset ?? '');
@@ -1642,7 +1660,7 @@ export class WorkflowRunner {
 
     for (const step of steps) {
       // Only check interactive agent steps (leads)
-      if (step.type === 'deterministic' || step.type === 'worktree') continue;
+      if (step.type === 'deterministic' || step.type === 'worktree' || step.type === 'integration') continue;
       const agentDef = agents.find((a) => a.name === step.agent);
       // Skip non-interactive agents — they can't wait for channel signals
       if (
@@ -1697,6 +1715,15 @@ export class WorkflowRunner {
           if (step.command) {
             step.command = this.interpolate(step.command, vars);
           }
+          // Resolve variables in integration step params
+          if (step.params && typeof step.params === 'object') {
+            for (const key of Object.keys(step.params)) {
+              const val = (step.params as Record<string, unknown>)[key];
+              if (typeof val === 'string') {
+                (step.params as Record<string, string>)[key] = this.interpolate(val, vars);
+              }
+            }
+          }
         }
       }
     }
@@ -1841,22 +1868,24 @@ export class WorkflowRunner {
     // Build step rows
     const stepStates = new Map<string, StepState>();
     for (const step of resolvedWorkflow.steps) {
-      // Handle agent, deterministic, and worktree steps
-      const isNonAgent = step.type === 'deterministic' || step.type === 'worktree';
+      // Handle agent, deterministic, worktree, and integration steps
+      const isNonAgent = step.type === 'deterministic' || step.type === 'worktree' || step.type === 'integration';
 
       const stepRow: WorkflowStepRow = {
         id: this.generateId(),
         runId,
         stepName: step.name,
         agentName: isNonAgent ? null : (step.agent ?? null),
-        stepType: isNonAgent ? (step.type as 'deterministic' | 'worktree') : 'agent',
+        stepType: isNonAgent ? (step.type as 'deterministic' | 'worktree' | 'integration') : 'agent',
         status: 'pending',
         task:
           step.type === 'deterministic'
             ? (step.command ?? '')
             : step.type === 'worktree'
               ? (step.branch ?? '')
-              : (step.task ?? ''),
+              : step.type === 'integration'
+                ? (`${step.integration}.${step.action}`)
+                : (step.task ?? ''),
         dependsOn: step.dependsOn ?? [],
         retryCount: 0,
         createdAt: now,
@@ -2041,7 +2070,7 @@ export class WorkflowRunner {
         this.relayOptions.env?.AGENT_RELAY_WORKFLOW_DISABLE_RELAYCAST === '1';
       const requiresBroker =
         !this.executor &&
-        workflow.steps.some((step) => step.type !== 'deterministic' && step.type !== 'worktree');
+        workflow.steps.some((step) => step.type !== 'deterministic' && step.type !== 'worktree' && step.type !== 'integration');
       // Skip broker/relay init when an external executor handles agent spawning
       if (requiresBroker) {
         if (!relaycastDisabled) {
@@ -2236,8 +2265,14 @@ export class WorkflowRunner {
         this.relaycast = undefined;
         this.relaycastAgent = undefined;
 
-        // Wire broker stderr to console for observability
+        // Wire broker stderr to console for observability — skip empty and
+        // JSON event lines (already surfaced via the broker:event emitter).
         this.unsubBrokerStderr = this.relay.onBrokerStderr((line: string) => {
+          const trimmed = line.trim();
+          if (!trimmed) return;
+          // JSON event lines from the Rust EventEmitter are already parsed
+          // and emitted as broker:event — no need to double-log them.
+          if (trimmed.startsWith('{') && trimmed.endsWith('}')) return;
           console.log(`${chalk.dim.yellow('[broker]')} ${line}`);
         });
 
@@ -2684,6 +2719,11 @@ export class WorkflowRunner {
     return step.type === 'worktree';
   }
 
+  /** Check if a step is an integration (external service) step. */
+  private isIntegrationStep(step: WorkflowStep): boolean {
+    return step.type === 'integration';
+  }
+
   private async executeStep(
     step: WorkflowStep,
     stepStates: Map<string, StepState>,
@@ -2701,6 +2741,11 @@ export class WorkflowRunner {
       return this.executeWorktreeStep(step, stepStates, runId);
     }
 
+    // Branch: integration steps interact with external services
+    if (this.isIntegrationStep(step)) {
+      return this.executeIntegrationStep(step, stepStates, runId);
+    }
+
     // Agent step execution
     return this.executeAgentStep(step, stepStates, agentMap, errorHandling, runId);
   }
@@ -3194,6 +3239,76 @@ export class WorkflowRunner {
     }
   }
 
+  /**
+   * Execute an integration step (external service interaction via executor).
+   */
+  private async executeIntegrationStep(
+    step: WorkflowStep,
+    stepStates: Map<string, StepState>,
+    runId: string
+  ): Promise<void> {
+    const state = stepStates.get(step.name);
+    if (!state) throw new Error(`Step state not found: ${step.name}`);
+
+    this.checkAborted();
+
+    // Mark step as running
+    state.row.status = 'running';
+    state.row.error = undefined;
+    state.row.completionReason = undefined;
+    state.row.startedAt = new Date().toISOString();
+    await this.db.updateStep(state.row.id, {
+      status: 'running',
+      error: undefined,
+      completionReason: undefined,
+      startedAt: state.row.startedAt,
+      updatedAt: new Date().toISOString(),
+    });
+    this.emit({ type: 'step:started', runId, stepName: step.name });
+    this.postToChannel(`**[${step.name}]** Started (integration: ${step.integration}.${step.action})`);
+
+    // Resolve {{steps.X.output}} in params
+    const stepOutputContext = this.buildStepOutputContext(stepStates, runId);
+    const resolvedParams: Record<string, string> = {};
+    for (const [key, value] of Object.entries(step.params ?? {})) {
+      resolvedParams[key] = this.interpolateStepTask(value, stepOutputContext);
+    }
+
+    try {
+      if (!this.executor?.executeIntegrationStep) {
+        throw new Error(
+          `Integration steps require a cloud executor. Step "${step.name}" cannot run locally. ` +
+          `Use "cloud run" to execute workflows with integration steps.`
+        );
+      }
+
+      const result = await this.executor.executeIntegrationStep(step, resolvedParams, { workspaceId: this.workspaceId });
+
+      if (!result.success) {
+        throw new Error(`Integration step "${step.name}" failed: ${result.output}`);
+      }
+
+      // Mark completed
+      state.row.status = 'completed';
+      state.row.output = result.output;
+      state.row.completedAt = new Date().toISOString();
+      await this.db.updateStep(state.row.id, {
+        status: 'completed',
+        output: result.output,
+        completedAt: state.row.completedAt,
+        updatedAt: new Date().toISOString(),
+      });
+      await this.persistStepOutput(runId, step.name, result.output);
+      this.emit({ type: 'step:completed', runId, stepName: step.name, output: result.output });
+      this.postToChannel(`**[${step.name}]** Completed (integration: ${step.integration}.${step.action})`);
+    } catch (err) {
+      const errorMsg = err instanceof Error ? err.message : String(err);
+      this.postToChannel(`**[${step.name}]** Failed: ${errorMsg}`);
+      await this.markStepFailed(state, errorMsg, runId);
+      throw new Error(`Step "${step.name}" failed: ${errorMsg}`);
+    }
+  }
+
   /**
    * Execute an agent step (LLM-powered).
    */
@@ -3216,6 +3331,58 @@ export class WorkflowRunner {
       throw new Error(`Agent "${agentName}" not found in config`);
     }
     const specialistDef = WorkflowRunner.resolveAgentDef(rawAgentDef);
+
+    // API-mode agents: execute via direct API call instead of spawning a PTY/subprocess.
+    if (specialistDef.cli === 'api') {
+      const stepOutputContext = this.buildStepOutputContext(stepStates, runId);
+      const resolvedTask = this.interpolateStepTask(step.task ?? '', stepOutputContext);
+
+      state.row.status = 'running';
+      state.row.startedAt = new Date().toISOString();
+      await this.db.updateStep(state.row.id, {
+        status: 'running',
+        startedAt: state.row.startedAt,
+        updatedAt: new Date().toISOString(),
+      });
+      this.emit({ type: 'step:started', runId, stepName: step.name });
+      this.postToChannel(`**[${step.name}]** Started (api)`);
+
+      try {
+        const output = await executeApiStep(
+          specialistDef.constraints?.model ?? 'claude-sonnet-4-20250514',
+          resolvedTask,
+          { envSecrets: this.envSecrets, skills: specialistDef.skills, defaultMaxTokens: specialistDef.constraints?.maxTokens },
+        );
+
+        state.row.status = 'completed';
+        state.row.output = output;
+        state.row.completedAt = new Date().toISOString();
+        await this.db.updateStep(state.row.id, {
+          status: 'completed',
+          output,
+          completedAt: state.row.completedAt,
+          updatedAt: new Date().toISOString(),
+        });
+        await this.persistStepOutput(runId, step.name, output);
+        this.emit({ type: 'step:completed', runId, stepName: step.name, output });
+      } catch (apiError) {
+        const errorMessage = apiError instanceof Error ? apiError.message : String(apiError);
+        state.row.status = 'failed';
+        state.row.error = errorMessage;
+        state.row.completedAt = new Date().toISOString();
+        await this.db.updateStep(state.row.id, {
+          status: 'failed',
+          error: errorMessage,
+          completedAt: state.row.completedAt,
+          updatedAt: new Date().toISOString(),
+        });
+        this.emit({ type: 'step:failed', runId, stepName: step.name, error: errorMessage });
+        this.postToChannel(`**[${step.name}]** Failed (api): ${errorMessage}`);
+        throw apiError;
+      }
+      return;
+    }
+
     const usesOwnerFlow = specialistDef.interactive !== false;
     const currentPattern = this.currentConfig?.swarm?.pattern ?? '';
     const isHubPattern = WorkflowRunner.HUB_PATTERNS.has(currentPattern);
@@ -4734,10 +4901,13 @@ export class WorkflowRunner {
     task: string,
     extraArgs: string[] = []
   ): { cmd: string; args: string[] } {
+    if (cli === 'api') {
+      throw new Error('cli "api" uses direct API calls, not a subprocess command');
+    }
     const resolvedCli: AgentCli = cli === 'cursor' ? resolveCursorCli() : cli;
     const def = getCliDefinition(resolvedCli);
-    if (!def) {
-      throw new Error(`Unknown CLI: ${resolvedCli}`);
+    if (!def || def.binaries.length === 0) {
+      throw new Error(`Unknown or non-executable CLI: ${resolvedCli}`);
     }
     return {
       cmd: def.binaries[0],
@@ -6053,26 +6223,23 @@ export class WorkflowRunner {
     );
     console.log(chalk.dim('━'.repeat(70)));
 
-    if (this.agentReports.size > 0) {
-      console.log(formatRunSummaryTable(outcomes, this.agentReports));
-    } else {
-      for (const outcome of outcomes) {
-        const icon =
-          outcome.status === 'completed' ? chalk.green('✓') : outcome.status === 'failed' ? chalk.red('✗') : chalk.dim('⊘');
-        const retryNote = outcome.attempts > 1 ? ` (${outcome.attempts} attempts)` : '';
-        console.log(`  ${icon} ${outcome.name} [${outcome.agent}]${retryNote}`);
-
-        if (outcome.error) {
-          console.log(`    Error: ${outcome.error}`);
-        }
+    // Always show the summary table — with agent reports when available,
+    // with just step/status/duration when not (non-interactive agents).
+    console.log(formatRunSummaryTable(outcomes, this.agentReports));
 
-        // Extract last meaningful lines from raw PTY output
-        if (outcome.output) {
-          const excerpt = this.extractOutputExcerpt(outcome.output);
-          if (excerpt) {
-            for (const line of excerpt.split('\n')) {
-              console.log(`    ${line}`);
-            }
+    // Show errors and output excerpts for failed steps below the table
+    for (const outcome of outcomes) {
+      if (outcome.status !== 'failed') continue;
+
+      if (outcome.error) {
+        console.log(chalk.red(`  ${outcome.name}: ${outcome.error}`));
+      }
+
+      if (outcome.output) {
+        const excerpt = this.extractOutputExcerpt(outcome.output);
+        if (excerpt) {
+          for (const line of excerpt.split('\n')) {
+            console.log(`    ${line}`);
           }
         }
       }

package/packages/sdk/src/workflows/types.ts

@@ -145,9 +145,11 @@ export interface AgentDefinition {
    *   analyst  → interactive: false, reads code/files, writes findings, no sub-agents
    */
   preset?: AgentPreset;
+  /** System prompt / skills for API-mode agents (cli: 'api'). */
+  skills?: string;
 }
 
-export type AgentCli = 'claude' | 'codex' | 'gemini' | 'aider' | 'goose' | 'opencode' | 'droid' | 'cursor' | 'cursor-agent' | 'agent';
+export type AgentCli = 'claude' | 'codex' | 'gemini' | 'aider' | 'goose' | 'opencode' | 'droid' | 'cursor' | 'cursor-agent' | 'agent' | 'api';
 
 /** Resource and behavioral constraints for an agent. */
 export interface AgentConstraints {
@@ -183,8 +185,8 @@ export interface WorkflowDefinition {
   onError?: 'fail' | 'skip' | 'retry';
 }
 
-/** Step type: agent (LLM-powered), deterministic (shell command), or worktree (git worktree setup). */
-export type WorkflowStepType = 'agent' | 'deterministic' | 'worktree';
+/** Step type: agent (LLM-powered), deterministic (shell command), worktree (git worktree setup), or integration (external service). */
+export type WorkflowStepType = 'agent' | 'deterministic' | 'worktree' | 'integration';
 
 // ── Custom step definitions ─────────────────────────────────────────────────
 
@@ -277,6 +279,14 @@ export interface WorkflowStep {
   /** Capture stdout as step output for downstream steps. Default: true. */
   captureOutput?: boolean;
 
+  // ── Integration step fields ────────────────────────────────────────────────
+  /** Integration name: 'github', 'linear', 'slack' (required for integration steps). */
+  integration?: string;
+  /** Action within the integration, e.g. 'create-pr', 'create-branch' (required for integration steps). */
+  action?: string;
+  /** Action parameters, supports {{steps.X.output}} interpolation. */
+  params?: Record<string, string>;
+
   // ── Worktree step fields ──────────────────────────────────────────────────
   /** Branch name for the worktree (required for worktree steps). */
   branch?: string;
@@ -298,6 +308,11 @@ export function isWorktreeStep(step: WorkflowStep): boolean {
   return step.type === 'worktree';
 }
 
+/** Type guard: Check if a step is an integration (external service) step. */
+export function isIntegrationStep(step: WorkflowStep): boolean {
+  return step.type === 'integration';
+}
+
 /** Type guard: Check if a step uses a custom step definition. */
 export function isCustomStep(step: WorkflowStep): boolean {
   return step.use !== undefined;
@@ -305,7 +320,7 @@ export function isCustomStep(step: WorkflowStep): boolean {
 
 /** Type guard: Check if a step is an agent (LLM-powered) step. */
 export function isAgentStep(step: WorkflowStep): boolean {
-  return step.type !== 'deterministic' && step.type !== 'worktree';
+  return step.type !== 'deterministic' && step.type !== 'worktree' && step.type !== 'integration';
 }
 
 // Legacy type aliases for backward compatibility

package/packages/sdk/src/workflows/validator.ts

@@ -8,8 +8,23 @@ export interface ValidationIssue {
   location?: string; // e.g. "step:analyze" or "agent:analyst"
 }
 
+const CHANNEL_NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
+
 export function validateWorkflow(config: RelayYamlConfig): ValidationIssue[] {
   const issues: ValidationIssue[] = [];
+
+  // Validate channel name format (must be lowercase alphanumeric + hyphens)
+  const channel = (config as any).swarm?.channel ?? (config as any).channel;
+  if (channel && !CHANNEL_NAME_RE.test(channel)) {
+    issues.push({
+      severity: 'error',
+      code: 'INVALID_CHANNEL_NAME',
+      message: `Channel name "${channel}" is invalid. Must be lowercase alphanumeric and hyphens, starting with a letter or number.`,
+      fix: `Use .toLowerCase().replace(/[^a-z0-9-]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '') on the channel name.`,
+      location: 'swarm:channel',
+    });
+  }
+
   const agentMap = new Map(config.agents.map((a) => [a.name, a]));
   const hasReviewerAgent = config.agents.some((a) => {
     const role = a.role?.toLowerCase() ?? '';

package/packages/sdk-py/README.md

@@ -127,6 +127,13 @@ relay = Relay("Researcher")
 await relay.send("Lead", "Status update")
 await relay.post("docs", "Wave 5.1 complete")
 messages = await relay.inbox()
+
+human = relay.system()
+await human.send_message(
+    to="Agent1",
+    text="Please start the analysis",
+    mode="wait",   # or "steer"
+)
 ```
 
 ### `on_relay()`

package/packages/sdk-py/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agent-relay-sdk"
-version = "3.2.15"
+version = "3.2.17"
 description = "Python SDK for Agent Relay workflows"
 readme = "README.md"
 license = "Apache-2.0"

package/packages/sdk-py/src/agent_relay/__init__.py

@@ -17,6 +17,7 @@ from .protocol import (
     AgentRuntime,
     AgentSpec,
     BrokerEvent,
+    MessageInjectionMode,
     ProtocolEnvelope,
     RestartPolicy as ProtocolRestartPolicy,
 )
@@ -92,6 +93,7 @@ __all__ = [
     "AgentRuntime",
     "AgentSpec",
     "BrokerEvent",
+    "MessageInjectionMode",
     "ProtocolEnvelope",
     "ProtocolRestartPolicy",
     # Workflow builder (backward compat)

package/packages/sdk-py/src/agent_relay/builder.py

@@ -18,9 +18,11 @@ Example::
 from __future__ import annotations
 
 import copy
+import os
 import re
 import shutil
 import subprocess
+import sys
 import tempfile
 from pathlib import Path
 from typing import Any
@@ -388,9 +390,36 @@ class WorkflowBuilder:
         """Serialize the config to a YAML string."""
         return yaml.dump(self.to_config(), default_flow_style=False, sort_keys=False)
 
+    def dry_run(self, options: RunOptions | None = None) -> WorkflowResult:
+        """Validate the workflow and show execution plan without running."""
+        opts = RunOptions(
+            workflow=(options.workflow if options else None),
+            cwd=(options.cwd if options else None),
+            vars=(options.vars if options else None),
+            trajectories=(options.trajectories if options else None),
+            on_event=(options.on_event if options else None),
+            dry_run=True,
+        )
+        return self.run(opts)
+
     def run(self, options: RunOptions | None = None) -> WorkflowResult:
-        """Build the config and execute it via ``agent-relay run <tempfile>``."""
-        opts = options or RunOptions()
+        """Build the config and execute it via ``agent-relay run <tempfile>``.
+
+        Dry-run is enabled when:
+        - ``options.dry_run`` is ``True``, or
+        - the ``DRY_RUN`` environment variable is set to ``"true"``
+          (set automatically by ``agent-relay run script.py --dry-run``).
+        """
+        opts = RunOptions(
+            workflow=(options.workflow if options else None),
+            cwd=(options.cwd if options else None),
+            vars=(options.vars if options else None),
+            trajectories=(options.trajectories if options else None),
+            on_event=(options.on_event if options else None),
+            dry_run=(options.dry_run if options else None),
+        )
+        if opts.dry_run is None and os.environ.get("DRY_RUN") == "true":
+            opts.dry_run = True
         config = _apply_runtime_overrides(self.to_config(), opts)
         return _run_config(config, opts)
 
@@ -402,7 +431,16 @@ def workflow(name: str) -> WorkflowBuilder:
 
 def run_yaml(yaml_path: str, options: RunOptions | None = None) -> WorkflowResult:
     """Run an existing relay YAML workflow file."""
-    opts = options or RunOptions()
+    opts = RunOptions(
+        workflow=(options.workflow if options else None),
+        cwd=(options.cwd if options else None),
+        vars=(options.vars if options else None),
+        trajectories=(options.trajectories if options else None),
+        on_event=(options.on_event if options else None),
+        dry_run=(options.dry_run if options else None),
+    )
+    if opts.dry_run is None and os.environ.get("DRY_RUN") == "true":
+        opts.dry_run = True
 
     if opts.trajectories is None and not opts.vars:
         return _run_yaml_path(yaml_path, opts)
@@ -436,6 +474,8 @@ def _run_yaml_path(yaml_path: str, options: RunOptions) -> WorkflowResult:
         )
 
     cmd = [*cmd_prefix, "run", yaml_path]
+    if options.dry_run:
+        cmd.append("--dry-run")
     if options.workflow:
         cmd.extend(["--workflow", options.workflow])
 
@@ -462,7 +502,26 @@ def _execute_cli(
     cwd: str | None,
     on_event: WorkflowEventCallback | None,
 ) -> WorkflowResult:
-    """Execute CLI command and parse emitted workflow events."""
+    """Execute CLI command and parse emitted workflow events.
+
+    When no event callback is registered, stdio is passed straight through so
+    the TypeScript runner's listr progress and summary table render directly
+    to the terminal — identical output to YAML and TypeScript workflows.
+    """
+    # Passthrough mode: no callback → let the TS runner render directly
+    if on_event is None:
+        process = subprocess.Popen(cmd, cwd=cwd)
+        process.wait()
+
+        return WorkflowResult(
+            status="completed" if process.returncode == 0 else "failed",
+            run_id="",
+            error=None if process.returncode == 0 else "Workflow failed",
+            steps=[],
+            events=[],
+        )
+
+    # Capture mode: callback registered → parse events line by line
     process = subprocess.Popen(
         cmd,
         cwd=cwd,
@@ -487,9 +546,7 @@ def _execute_cli(
 
             events.append(event)
             _sync_step_result(steps, event)
-
-            if on_event is not None:
-                on_event(event)
+            on_event(event)
 
     return_code = process.wait()
     output = "\n".join(lines).strip()

package/packages/sdk-py/src/agent_relay/client.py

@@ -25,6 +25,7 @@ from .protocol import (
     AgentSpec,
     BrokerEvent,
     HeadlessProvider,
+    MessageInjectionMode,
     ProtocolEnvelope,
 )
 
@@ -715,6 +716,7 @@ class AgentRelayClient:
         thread_id: Optional[str] = None,
         priority: Optional[int] = None,
         data: Optional[dict[str, Any]] = None,
+        mode: Optional[MessageInjectionMode] = None,
     ) -> dict[str, Any]:
         await self.start_client()
         payload: dict[str, Any] = {"to": to, "text": text}
@@ -726,6 +728,8 @@ class AgentRelayClient:
             payload["priority"] = priority
         if data is not None:
             payload["data"] = data
+        if mode is not None:
+            payload["mode"] = mode
         try:
             return await self._request_ok("send_message", payload)
         except AgentRelayProtocolError as e:

package/packages/sdk-py/src/agent_relay/communicate/adapters/__init__.py

@@ -1,10 +1 @@
 """Framework-specific adapters for on_relay()."""
-
-_has_pi = False
-try:
-    from .pi import on_relay as on_pi_relay
-    _has_pi = True
-except ImportError:
-    pass
-
-__all__ = [*(["on_pi_relay"] if _has_pi else [])]