agent-relay 3.2.14 → 3.2.16

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],

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.14"
+version = "3.2.16"
 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/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 [])]

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

@@ -9,10 +9,10 @@ if TYPE_CHECKING:
 
 
 def _format_instructions_with_inbox(messages: list[Any], base_instructions: str) -> str:
-    content = "\n\nNew messages from other agents:\n"
+    content = "New messages from other agents:\n"
     for message in messages:
         content += f"  {message.sender}: {message.text}\n"
-    return f"{content}\n{base_instructions}" if base_instructions else content
+    return f"{base_instructions}\n\n{content}" if base_instructions else content
 
 
 def on_relay(agent: Any, relay: "Relay | None" = None) -> Any:
@@ -45,11 +45,8 @@ def on_relay(agent: Any, relay: "Relay | None" = None) -> Any:
 
     agent.tools.extend([relay_send, relay_inbox, relay_post, relay_agents])
 
-    # 2. Wrap instructions with a local buffer so we don't starve relay_inbox tool
+    # 2. Wrap instructions
     orig_instructions = agent.instructions
-    pending_messages: list[Any] = []
-
-    relay.on_message(lambda msg: pending_messages.append(msg))
 
     async def instructions_wrapper(*args: Any, **kwargs: Any) -> str:
         if callable(orig_instructions):
@@ -63,11 +60,10 @@ def on_relay(agent: Any, relay: "Relay | None" = None) -> Any:
             base = orig_instructions
 
         base = base or ""
-        if not pending_messages:
+        messages = await relay.inbox()
+        if not messages:
             return base
 
-        messages = list(pending_messages)
-        pending_messages.clear()
         return _format_instructions_with_inbox(messages, base)
 
     agent.instructions = instructions_wrapper

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

@@ -9,7 +9,7 @@ if TYPE_CHECKING:
     from ..core import Relay
 
 
-def on_relay(name: str, options: Any, relay: "Relay | None" = None) -> Any:
+def on_relay(options: Any, relay: "Relay | None" = None, *, name: str | None = None) -> Any:
     """Wrap Claude Agent SDK query options to connect them to the relay."""
     try:
         from claude_agent_sdk.types import HookResult
@@ -24,10 +24,8 @@ def on_relay(name: str, options: Any, relay: "Relay | None" = None) -> Any:
         from ..core import Relay
         relay = Relay(agent_name)
 
-    hooks = getattr(options, "hooks", None)
-    if hooks is None:
-        hooks = SimpleNamespace(post_tool_use=None, stop=None)
-        options.hooks = hooks
+    if getattr(options, "hooks", None) is None:
+        options.hooks = SimpleNamespace(post_tool_use=None, stop=None)
 
     # 1. Inject Relaycast MCP server
     mcp_config = {"name": "relaycast", "command": "agent-relay", "args": ["mcp"]}
@@ -46,8 +44,8 @@ def on_relay(name: str, options: Any, relay: "Relay | None" = None) -> Any:
         return content
 
     # 3. Hook wrappers
-    orig_post = getattr(hooks, "post_tool_use", None)
-    orig_stop = getattr(hooks, "stop", None)
+    orig_post = options.hooks.post_tool_use if hasattr(options.hooks, "post_tool_use") else None
+    orig_stop = options.hooks.stop if hasattr(options.hooks, "stop") else None
 
     async def post_tool_use_hook(*args, **kwargs):
         res = None

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

@@ -47,18 +47,9 @@ class _RelayBackstory:
     def _resolve_sync(self) -> str:
         messages = self._drain_buffer()
         try:
-            loop = asyncio.get_running_loop()
-        except RuntimeError:
-            loop = None
-
-        if loop is None:
             messages.extend(self._relay.inbox_sync())
-        else:
-            # Running inside an event loop — use a thread to avoid blocking
-            import concurrent.futures
-            with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
-                polled = pool.submit(asyncio.run, self._relay.inbox()).result()
-                messages.extend(polled)
+        except Exception:
+            pass  # Buffer messages are still available
         return _format_backstory(self._dedupe(messages), self._base_backstory)
 
     async def _resolve_async(self) -> str:
@@ -136,8 +127,7 @@ def on_relay(agent: Any, relay: "Relay | None" = None) -> Any:
     def _buffer_message(message: Any) -> None:
         backstory_buffer.append(message)
 
-    unsubscribe = relay.on_message(_buffer_message)
+    relay.on_message(_buffer_message)
     agent.backstory = _RelayBackstory(relay, agent.backstory or "", backstory_buffer)
-    agent._relay_unsubscribe = unsubscribe  # type: ignore[attr-defined]
 
     return agent

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

@@ -47,7 +47,10 @@ def on_relay(agent: Any, relay: "Relay | None" = None) -> Any:
             if inspect.isawaitable(orig_result):
                 orig_result = await orig_result
 
-        # Always inject relay messages, even if the original callback returned a result
+        # If original callback short-circuited (returned Content), respect that
+        if orig_result is not None:
+            return orig_result
+
         messages = await relay.inbox()
         if messages:
             from google.genai.types import Content, Part
@@ -63,7 +66,7 @@ def on_relay(agent: Any, relay: "Relay | None" = None) -> Any:
                     )
                 )
 
-        return orig_result
+        return None
 
     agent.before_model_callback = relay_callback
     return agent

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

@@ -10,10 +10,10 @@ if TYPE_CHECKING:
 
 
 def _format_instructions_with_inbox(messages: list[Any], base_instructions: str) -> str:
-    content = "\n\nNew messages from other agents:\n"
+    content = "New messages from other agents:\n"
     for message in messages:
         content += f"  {message.sender}: {message.text}\n"
-    return f"{content}\n{base_instructions}" if base_instructions else content
+    return f"{base_instructions}\n\n{content}" if base_instructions else content
 
 
 def on_relay(agent: Any, relay: "Relay | None" = None) -> Any:
@@ -57,11 +57,8 @@ def on_relay(agent: Any, relay: "Relay | None" = None) -> Any:
         function_tool(relay_agents)
     ])
 
-    # 2. Wrap instructions with a local buffer so we don't starve relay_inbox tool
+    # 2. Wrap instructions
     orig_instructions = agent.instructions
-    pending_messages: list[Any] = []
-
-    relay.on_message(lambda msg: pending_messages.append(msg))
 
     async def instructions_wrapper(*args: Any, **kwargs: Any) -> str:
         if callable(orig_instructions):
@@ -75,11 +72,10 @@ def on_relay(agent: Any, relay: "Relay | None" = None) -> Any:
             base = orig_instructions
 
         base = base or ""
-        if not pending_messages:
+        messages = await relay.inbox()
+        if not messages:
             return base
 
-        messages = list(pending_messages)
-        pending_messages.clear()
         return _format_instructions_with_inbox(messages, base)
 
     agent.instructions = instructions_wrapper