agent-relay 3.1.23 → 3.2.1

package/packages/sdk/src/workflows/schema.json

@@ -126,6 +126,12 @@ Added workdir to WorktreeWorkflowStep
         },
         "idleNudge": {
           "$ref": "#/definitions/IdleNudgeConfig"
+        },
+        "completionGracePeriodMs": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 5000,
+          "description": "Grace period (ms) after an agent exits with code 0 but without posting the expected coordination signal. During this window the runner checks verification gates and evidence before failing. Set to 0 to disable."
         }
       }
     },

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

@@ -16,7 +16,7 @@ import { existsSync } from 'node:fs';
 import { mkdir, writeFile, rename } from 'node:fs/promises';
 import path from 'node:path';
 
-import type { TrajectoryConfig, WorkflowStep } from './types.js';
+import type { StepCompletionDecision, TrajectoryConfig, WorkflowStep } from './types.js';
 
 // ── Trajectory file format (compatible with trail CLI) ───────────────────────
 
@@ -84,6 +84,8 @@ export interface StepOutcome {
   nonInteractive?: boolean;
   /** Duration in ms. */
   durationMs?: number;
+  /** How the step completion was determined. */
+  completionMode?: StepCompletionDecision['mode'];
 }
 
 // ── Failure root-cause categories ───────────────────────────────────────────
@@ -339,8 +341,35 @@ export class WorkflowTrajectory {
     await this.flush();
   }
 
+  async stepCompletionDecision(stepName: string, decision: StepCompletionDecision): Promise<void> {
+    if (!this.enabled || !this.trajectory) return;
+
+    const modeLabel = decision.mode === 'marker' ? 'marker-based' : `${decision.mode}-based`;
+    const reason = decision.reason ? ` — ${decision.reason}` : '';
+    const evidence = this.formatCompletionEvidenceSummary(decision.evidence);
+    const evidenceSuffix = evidence ? ` (${evidence})` : '';
+
+    this.addEvent(
+      decision.mode === 'marker' ? 'completion-marker' : 'completion-evidence',
+      `"${stepName}" ${modeLabel} completion${reason}${evidenceSuffix}`,
+      'medium',
+      {
+        stepName,
+        completionMode: decision.mode,
+        reason: decision.reason,
+        evidence: decision.evidence,
+      }
+    );
+    await this.flush();
+  }
+
   /** Record step completed — captures what was accomplished. */
-  async stepCompleted(step: WorkflowStep, output: string, attempt: number): Promise<void> {
+  async stepCompleted(
+    step: WorkflowStep,
+    output: string,
+    attempt: number,
+    decision?: StepCompletionDecision
+  ): Promise<void> {
     if (!this.enabled || !this.trajectory) return;
 
     const suffix = attempt > 1 ? ` (after ${attempt} attempts)` : '';
@@ -357,7 +386,12 @@ export class WorkflowTrajectory {
         ? lastMeaningful
         : output.trim().slice(0, 120) || '(no output)';
 
-    this.addEvent('finding', `"${step.name}" completed${suffix} → ${completion}`, 'medium');
+    if (decision) {
+      await this.stepCompletionDecision(step.name, decision);
+    }
+
+    const modeSuffix = decision ? ` [${decision.mode}]` : '';
+    this.addEvent('finding', `"${step.name}" completed${suffix}${modeSuffix} → ${completion}`, 'medium');
     await this.flush();
   }
 
@@ -697,6 +731,21 @@ export class WorkflowTrajectory {
     chapter.events.push(event);
   }
 
+  private formatCompletionEvidenceSummary(
+    evidence: StepCompletionDecision['evidence'] | undefined
+  ): string | undefined {
+    if (!evidence) return undefined;
+
+    const parts: string[] = [];
+    if (evidence.summary) parts.push(evidence.summary);
+    if (evidence.signals?.length) parts.push(`signals=${evidence.signals.join(', ')}`);
+    if (evidence.channelPosts?.length) parts.push(`channel=${evidence.channelPosts.join(' | ')}`);
+    if (evidence.files?.length) parts.push(`files=${evidence.files.join(', ')}`);
+    if (evidence.exitCode !== undefined) parts.push(`exit=${evidence.exitCode}`);
+
+    return parts.length > 0 ? parts.join('; ') : undefined;
+  }
+
   private async flush(): Promise<void> {
     if (!this.trajectory) return;
 

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

@@ -76,6 +76,13 @@ export interface SwarmConfig {
   channel?: string;
   /** Idle agent detection and nudging configuration for interactive agents. */
   idleNudge?: IdleNudgeConfig;
+  /**
+   * Grace period (ms) after an agent exits with code 0 but without posting
+   * the expected coordination signal. During this window the runner checks
+   * verification gates and evidence before failing the step.
+   * Default: 5000 (5 seconds). Set to 0 to disable.
+   */
+  completionGracePeriodMs?: number;
 }
 
 export type SwarmPattern =
@@ -310,6 +317,128 @@ export interface VerificationCheck {
   description?: string;
 }
 
+// ── Completion evidence ─────────────────────────────────────────────────────
+
+export type CompletionEvidenceSignalSource =
+  | 'channel'
+  | 'stdout'
+  | 'stderr'
+  | 'process'
+  | 'filesystem'
+  | 'tool'
+  | 'verification';
+
+export type CompletionEvidenceSignalKind =
+  | 'worker_done'
+  | 'lead_done'
+  | 'step_complete'
+  | 'owner_decision'
+  | 'review_decision'
+  | 'task_summary'
+  | 'verification_passed'
+  | 'verification_failed'
+  | 'process_exit'
+  | 'custom';
+
+export interface CompletionEvidenceSignal {
+  kind: CompletionEvidenceSignalKind;
+  source: CompletionEvidenceSignalSource;
+  text: string;
+  observedAt: string;
+  sender?: string;
+  actor?: string;
+  role?: string;
+  value?: string;
+}
+
+export type CompletionEvidenceChannelOrigin = 'runner_post' | 'forwarded_chunk' | 'relay_message';
+
+export interface CompletionEvidenceChannelPost {
+  stepName: string;
+  text: string;
+  postedAt: string;
+  origin: CompletionEvidenceChannelOrigin;
+  completionRelevant: boolean;
+  sender?: string;
+  actor?: string;
+  role?: string;
+  target?: string;
+  signals: CompletionEvidenceSignal[];
+}
+
+export type CompletionEvidenceFileChangeKind = 'created' | 'modified' | 'deleted';
+
+export interface CompletionEvidenceFileChange {
+  path: string;
+  kind: CompletionEvidenceFileChangeKind;
+  observedAt: string;
+  root?: string;
+}
+
+export type CompletionEvidenceToolSideEffectType =
+  | 'persist_step_output'
+  | 'post_channel_message'
+  | 'verification_observed'
+  | 'worktree_created'
+  | 'owner_monitoring'
+  | 'review_started'
+  | 'review_completed'
+  | 'worker_exit'
+  | 'worker_error'
+  | 'retry'
+  | 'custom';
+
+export interface CompletionEvidenceToolSideEffect {
+  type: CompletionEvidenceToolSideEffectType;
+  detail: string;
+  observedAt: string;
+  raw?: Record<string, unknown>;
+}
+
+export interface StepCompletionEvidence {
+  stepName: string;
+  status?: WorkflowStepStatus;
+  startedAt?: string;
+  completedAt?: string;
+  lastUpdatedAt: string;
+  roots: string[];
+  output: {
+    stdout: string;
+    stderr: string;
+    combined: string;
+  };
+  channelPosts: CompletionEvidenceChannelPost[];
+  files: CompletionEvidenceFileChange[];
+  process: {
+    exitCode?: number;
+    exitSignal?: string;
+  };
+  toolSideEffects: CompletionEvidenceToolSideEffect[];
+  coordinationSignals: CompletionEvidenceSignal[];
+}
+
+export type StepCompletionMode =
+  | 'marker'
+  | 'evidence'
+  | 'verification'
+  | 'owner_decision'
+  | 'review'
+  | 'heuristic';
+
+export interface StepCompletionDecisionEvidence {
+  summary?: string;
+  signals?: string[];
+  channelPosts?: string[];
+  files?: string[];
+  exitCode?: number;
+}
+
+export interface StepCompletionDecision {
+  mode: StepCompletionMode;
+  reason?: string;
+  evidence?: StepCompletionDecisionEvidence;
+}
+
 // ── Coordination ────────────────────────────────────────────────────────────
 
 /** Coordination settings for multi-agent synchronization. */
@@ -394,6 +523,25 @@ export interface WorkflowRunRow {
 }
 
 export type WorkflowStepStatus = 'pending' | 'running' | 'completed' | 'failed' | 'skipped';
+export type WorkflowOwnerDecision =
+  | 'COMPLETE'
+  | 'INCOMPLETE_RETRY'
+  | 'INCOMPLETE_FAIL'
+  | 'NEEDS_CLARIFICATION';
+/**
+ * Completion reasons are recorded for both successful and failed steps.
+ * `retry_requested_by_owner` is a retry-control signal, not a success state:
+ * the runner retries while budget remains and fails the step once retries are exhausted.
+ */
+export type WorkflowStepCompletionReason =
+  | 'completed_verified'
+  | 'completed_by_owner_decision'
+  | 'completed_by_evidence'
+  | 'completed_by_process_exit'
+  | 'retry_requested_by_owner'
+  | 'failed_verification'
+  | 'failed_owner_decision'
+  | 'failed_no_evidence';
 
 /** Database row representing a single workflow step execution. */
 export interface WorkflowStepRow {
@@ -410,6 +558,7 @@ export interface WorkflowStepRow {
   dependsOn: string[];
   output?: string;
   error?: string;
+  completionReason?: WorkflowStepCompletionReason;
   startedAt?: string;
   completedAt?: string;
   retryCount: number;

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

@@ -90,22 +90,22 @@ export function validateWorkflow(config: RelayYamlConfig): ValidationIssue[] {
         task.length > 500 &&
         !task.includes('do not') &&
         !task.includes('Do NOT') &&
-        !task.includes('relay_spawn') &&
+        !task.includes('mcp__relaycast__agent_add') &&
         !task.includes('add_agent')
       ) {
         issues.push({
           severity: 'info',
           code: 'CLAUDE_NO_SPAWN_GUARD',
           message: `Step "${step.name}" uses interactive claude with a long task. Claude may spontaneously spawn sub-agents via relay MCP tools.`,
-          fix: `Add "Do NOT use relay_spawn or add_agent to spawn sub-agents." to the task, or use \`interactive: false\`.`,
+          fix: `Add "Do NOT use mcp__relaycast__agent_add or add_agent to spawn sub-agents." to the task, or use \`interactive: false\`.`,
           location: `step:${step.name}`,
         });
       }
 
-      // Check 4: non-interactive agent that references relay_send in task
+      // Check 4: non-interactive agent that references relay messaging tools in task
       if (
         def.interactive === false &&
-        (task.includes('relay_send') || task.includes('post_message') || task.includes('check_inbox'))
+        (task.includes('mcp__relaycast__dm_send') || task.includes('mcp__relaycast__message_post') || task.includes('mcp__relaycast__inbox_check'))
       ) {
         issues.push({
           severity: 'warning',

package/packages/sdk-py/pyproject.toml

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

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

@@ -25,3 +25,14 @@ class Models:
         GEMINI_2_5_PRO = "gemini-2.5-pro"
         GEMINI_2_5_FLASH = "gemini-2.5-flash"
         GEMINI_2_5_FLASH_LITE = "gemini-2.5-flash-lite"
+
+    class Opencode:
+        OPENCODE_BIG_PICKLE = "opencode/big-pickle"
+        OPENCODE_GPT_5_NANO = "opencode/gpt-5-nano"
+        OPENCODE_MIMO_V2_FLASH_FREE = "opencode/mimo-v2-flash-free"
+        OPENCODE_MINIMAX_M2_5_FREE = "opencode/minimax-m2.5-free"
+        OPENAI_CODEX_MINI_LATEST = "openai/codex-mini-latest"
+        OPENAI_GPT_5_2 = "openai/gpt-5.2"
+        OPENAI_O3_MINI = "openai/o3-mini"
+        OPENAI_O3_PRO = "openai/o3-pro"
+        OPENAI_O4_MINI = "openai/o4-mini"

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

@@ -291,10 +291,11 @@ class HumanHandle:
 class AgentSpawner:
     """Shorthand spawner for a specific CLI (e.g., relay.claude.spawn(...))."""
 
-    def __init__(self, cli: str, default_name: str, relay: AgentRelay):
+    def __init__(self, cli: str, default_name: str, relay: AgentRelay, transport: str = "pty"):
         self._cli = cli
         self._default_name = default_name
         self._relay = relay
+        self._transport = transport
 
     async def spawn(
         self,
@@ -326,9 +327,10 @@ class AgentSpawner:
         )
 
         try:
-            result = await client.spawn_pty(
+            result = await client.spawn_provider(
                 name=agent_name,
-                cli=self._cli,
+                provider=self._cli,
+                transport=self._transport,
                 args=args or [],
                 channels=agent_channels,
                 task=task,
@@ -434,9 +436,10 @@ class AgentRelay:
         self._idle_resolvers: dict[str, list[asyncio.Future[str]]] = {}
 
         # Shorthand spawners
-        self.codex = AgentSpawner("codex", "Codex", self)
-        self.claude = AgentSpawner("claude", "Claude", self)
-        self.gemini = AgentSpawner("gemini", "Gemini", self)
+        self.codex = AgentSpawner("codex", "Codex", self, transport="pty")
+        self.claude = AgentSpawner("claude", "Claude", self, transport="pty")
+        self.gemini = AgentSpawner("gemini", "Gemini", self, transport="pty")
+        self.opencode = AgentSpawner("opencode", "OpenCode", self, transport="headless")
 
     @property
     def workspace_key(self) -> Optional[str]:

package/packages/sdk-py/tests/test_relay_lifecycle_hooks.py

@@ -23,6 +23,12 @@ class _FakeRelayClient:
             raise self.spawn_error
         return {"name": kwargs["name"], "runtime": "pty"}
 
+    async def spawn_provider(self, **kwargs):
+        self.spawn_calls.append(kwargs)
+        if self.spawn_error:
+            raise self.spawn_error
+        return {"name": kwargs["name"], "runtime": "pty"}
+
     async def release(self, name: str, reason: str | None = None):
         self.release_calls.append((name, reason))
         if self.release_error:
@@ -142,6 +148,23 @@ async def test_shorthand_spawn_lifecycle_hooks_success():
 
     assert agent.name == "ShorthandWorker"
     assert events == ["start", "success"]
+    assert client.spawn_calls[-1]["transport"] == "pty"
+
+
+@pytest.mark.asyncio
+async def test_opencode_shorthand_spawn_success():
+    relay = AgentRelay()
+    client = _FakeRelayClient()
+    relay._ensure_started = AsyncMock(return_value=client)
+
+    agent = await relay.opencode.spawn(
+        name="OpencodeWorker",
+        channels=["general"],
+    )
+
+    assert agent.name == "OpencodeWorker"
+    assert client.spawn_calls[-1]["provider"] == "opencode"
+    assert client.spawn_calls[-1]["transport"] == "headless"
 
 
 @pytest.mark.asyncio

package/packages/telemetry/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/telemetry",
-  "version": "3.1.23",
+  "version": "3.2.1",
   "description": "Anonymous telemetry for Agent Relay usage analytics",
   "type": "module",
   "main": "dist/index.js",

package/packages/trajectory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/trajectory",
-  "version": "3.1.23",
+  "version": "3.2.1",
   "description": "Trajectory integration utilities (trail/PDERO) for Relay",
   "type": "module",
   "main": "dist/index.js",
@@ -22,7 +22,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@agent-relay/config": "3.1.23"
+    "@agent-relay/config": "3.2.1"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/user-directory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/user-directory",
-  "version": "3.1.23",
+  "version": "3.2.1",
   "description": "User directory service for agent-relay (per-user credential storage)",
   "type": "module",
   "main": "dist/index.js",
@@ -22,7 +22,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@agent-relay/utils": "3.1.23"
+    "@agent-relay/utils": "3.2.1"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/utils/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/utils",
-  "version": "3.1.23",
+  "version": "3.2.1",
   "description": "Shared utilities for agent-relay: logging, name generation, command resolution, update checking",
   "type": "module",
   "main": "dist/cjs/index.js",
@@ -112,7 +112,7 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@agent-relay/config": "3.1.23",
+    "@agent-relay/config": "3.2.1",
     "compare-versions": "^6.1.1"
   },
   "publishConfig": {

package/relay-snippets/agent-relay-protocol.md

@@ -4,10 +4,10 @@ Advanced features for session continuity and trajectory tracking.
 
 ## Session Continuity
 
-Use `relay_send` with a continuity message to save state for session recovery:
+Use `mcp__relaycast__send_dm` with a continuity message to save state for session recovery:
 
 ```
-relay_send(to: "system", message: "KIND: continuity\nACTION: save\n\nCurrent task: Implementing user authentication\nCompleted: User model, JWT utils\nIn progress: Login endpoint")
+mcp__relaycast__send_dm(to: "system", text: "KIND: continuity\nACTION: save\n\nCurrent task: Implementing user authentication\nCompleted: User model, JWT utils\nIn progress: Login endpoint")
 ```
 
 ### When to Save
@@ -51,10 +51,10 @@ trail abandon --reason "Blocked by missing credentials"
 
 ## Cross-Project Messaging
 
-In bridge mode, use `project:agent` format with `relay_send`:
+In bridge mode, use `project:agent` format with `mcp__relaycast__send_dm`:
 
 ```
-relay_send(to: "frontend:Designer", message: "Please update the login UI.")
+mcp__relaycast__send_dm(to: "frontend:Designer", text: "Please update the login UI.")
 ```
 
 Special targets:

package/relay-snippets/agent-relay-snippet.md

@@ -4,41 +4,30 @@ Real-time agent-to-agent messaging via MCP tools.
 
 ## MCP Tools
 
-All agent communication uses MCP tools provided by the Relaycast MCP server:
-
-| Tool                           | Description                           |
-| ------------------------------ | ------------------------------------- |
-| `relay_send(to, message)`      | Send a message to an agent or channel |
-| `relay_inbox()`                | Check your inbox for new messages     |
-| `relay_who()`                  | List online agents                    |
-| `relay_spawn(name, cli, task)` | Spawn a new worker agent              |
-| `relay_release(name)`          | Release/stop a worker agent           |
-| `relay_status()`               | Check relay connection status         |
+All agent communication uses MCP tools provided by the Relaycast MCP server.
+Tool names use dot-notation: Claude uses `mcp__relaycast__<category>_<action>`, other CLIs use `relaycast.<category>.<action>`.
+
+| Tool                              | Description                           |
+| --------------------------------- | ------------------------------------- |
+| `dm_send(to, text)`               | Send a DM to an agent                 |
+| `message_post(channel, text)`     | Post a message to a channel           |
+| `inbox_check()`                   | Check your inbox for new messages     |
+| `agent_list()`                    | List online agents                    |
+| `agent_add(name, cli, task)`      | Spawn a new worker agent              |
+| `agent_remove(name)`              | Release/stop a worker agent           |
 
 ## Sending Messages
 
-Use the `relay_send` MCP tool:
-
-```
-relay_send(to: "AgentName", message: "Your message here")
-```
-
 ### Direct Messages
 
 ```
-relay_send(to: "Bob", message: "Can you review my code changes?")
-```
-
-### Broadcast to All
-
-```
-relay_send(to: "*", message: "I've finished the auth module")
+mcp__relaycast__dm_send(to: "Bob", text: "Can you review my code changes?")
 ```
 
 ### Channel Messages
 
 ```
-relay_send(to: "#frontend", message: "The API endpoints are ready")
+mcp__relaycast__message_post(channel: "general", text: "The API endpoints are ready")
 ```
 
 ## Spawning & Releasing Agents
@@ -46,23 +35,24 @@ relay_send(to: "#frontend", message: "The API endpoints are ready")
 ### Spawn a Worker
 
 ```
-relay_spawn(name: "WorkerName", cli: "claude", task: "Task description here")
+mcp__relaycast__agent_add(name: "WorkerName", cli: "claude", task: "Task description here")
 ```
 
 ### CLI Options
 
-| CLI Value | Description             |
-| --------- | ----------------------- |
-| `claude`  | Claude Code (Anthropic) |
-| `codex`   | Codex CLI (OpenAI)      |
-| `gemini`  | Gemini CLI (Google)     |
-| `aider`   | Aider coding assistant  |
-| `goose`   | Goose AI assistant      |
+| CLI Value   | Description                  |
+| ----------- | ---------------------------- |
+| `claude`    | Claude Code (Anthropic)      |
+| `codex`     | Codex CLI (OpenAI)           |
+| `gemini`    | Gemini CLI (Google)          |
+| `opencode`  | OpenCode CLI (multi-model)   |
+| `aider`     | Aider coding assistant       |
+| `goose`     | Goose AI assistant           |
 
 ### Release a Worker
 
 ```
-relay_release(name: "WorkerName")
+mcp__relaycast__agent_remove(name: "WorkerName")
 ```
 
 ## Receiving Messages
@@ -86,11 +76,11 @@ Reply to the channel shown, not the sender.
 If you were spawned by another agent:
 
 1. Your first message is your task from your spawner
-2. Use `relay_send` to reply to your spawner
+2. Use `mcp__relaycast__dm_send` to reply to your spawner
 3. Report status to your spawner (your lead), not broadcast
 
 ```
-relay_send(to: "Lead", message: "ACK: Starting on the task.")
+mcp__relaycast__dm_send(to: "Lead", text: "ACK: Starting on the task.")
 ```
 
 ## Protocol
@@ -103,10 +93,10 @@ relay_send(to: "Lead", message: "ACK: Starting on the task.")
 
 **Local communication** uses plain agent names. The `project:` prefix is **ONLY** for cross-project bridge mode.
 
-| Context                | Correct                                    | Incorrect                             |
-| ---------------------- | ------------------------------------------ | ------------------------------------- |
-| Local (same project)   | `relay_send(to: "Lead", ...)`              | `relay_send(to: "project:lead", ...)` |
-| Bridge (cross-project) | `relay_send(to: "frontend:Designer", ...)` | N/A                                   |
+| Context                | Correct                                                     | Incorrect                                              |
+| ---------------------- | ----------------------------------------------------------- | ------------------------------------------------------ |
+| Local (same project)   | `mcp__relaycast__dm_send(to: "Lead", ...)`                  | `mcp__relaycast__dm_send(to: "project:lead", ...)`     |
+| Bridge (cross-project) | `mcp__relaycast__dm_send(to: "frontend:Designer", ...)`     | N/A                                                    |
 
 ## Multi-Workspace
 
@@ -118,12 +108,10 @@ Relay message from Alice [my-team / abc123]: Hello!
 
 - Messages are scoped to the originating workspace
 - Reply within the same workspace context shown in the message header
-- Use `relay_status()` to see which workspaces are connected
 
 ## Checking Status
 
 ```
-relay_who()      # List online agents
-relay_inbox()    # Check for unread messages
-relay_status()   # Check connection status
+mcp__relaycast__agent_list()    # List online agents
+mcp__relaycast__inbox_check()   # Check for unread messages
 ```