agent-relay 3.2.0 → 3.2.2

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

@@ -105,7 +105,7 @@ export function validateWorkflow(config: RelayYamlConfig): ValidationIssue[] {
       // Check 4: non-interactive agent that references relay messaging tools in task
       if (
         def.interactive === false &&
-        (task.includes('mcp__relaycast__dm_send') || task.includes('mcp__relaycast__message_post') || task.includes('mcp__relaycast__inbox_check'))
+        (task.includes('mcp__relaycast__message_dm_send') || task.includes('mcp__relaycast__message_post') || task.includes('mcp__relaycast__message_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.2.0"
+version = "3.2.2"
 description = "Python SDK for Agent Relay workflows"
 readme = "README.md"
 license = "Apache-2.0"

package/packages/telemetry/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/telemetry",
-  "version": "3.2.0",
+  "version": "3.2.2",
   "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.2.0",
+  "version": "3.2.2",
   "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.2.0"
+    "@agent-relay/config": "3.2.2"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/user-directory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/user-directory",
-  "version": "3.2.0",
+  "version": "3.2.2",
   "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.2.0"
+    "@agent-relay/utils": "3.2.2"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/utils/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/utils",
-  "version": "3.2.0",
+  "version": "3.2.2",
   "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.2.0",
+    "@agent-relay/config": "3.2.2",
     "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 `mcp__relaycast__send_dm` with a continuity message to save state for session recovery:
+Use `mcp__relaycast__message_dm_send` with a continuity message to save state for session recovery:
 
 ```
-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")
+mcp__relaycast__message_dm_send(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 `mcp__relaycast__send_dm`:
+In bridge mode, use `project:agent` format with `mcp__relaycast__message_dm_send`:
 
 ```
-mcp__relaycast__send_dm(to: "frontend:Designer", text: "Please update the login UI.")
+mcp__relaycast__message_dm_send(to: "frontend:Designer", text: "Please update the login UI.")
 ```
 
 Special targets:

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

@@ -9,9 +9,9 @@ Tool names use dot-notation: Claude uses `mcp__relaycast__<category>_<action>`,
 
 | Tool                              | Description                           |
 | --------------------------------- | ------------------------------------- |
-| `dm_send(to, text)`               | Send a DM to an agent                 |
+| `message.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     |
+| `message.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           |
@@ -21,7 +21,7 @@ Tool names use dot-notation: Claude uses `mcp__relaycast__<category>_<action>`,
 ### Direct Messages
 
 ```
-mcp__relaycast__dm_send(to: "Bob", text: "Can you review my code changes?")
+mcp__relaycast__message_dm_send(to: "Bob", text: "Can you review my code changes?")
 ```
 
 ### Channel Messages
@@ -76,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 `mcp__relaycast__dm_send` to reply to your spawner
+2. Use `mcp__relaycast__message_dm_send` to reply to your spawner
 3. Report status to your spawner (your lead), not broadcast
 
 ```
-mcp__relaycast__dm_send(to: "Lead", text: "ACK: Starting on the task.")
+mcp__relaycast__message_dm_send(to: "Lead", text: "ACK: Starting on the task.")
 ```
 
 ## Protocol
@@ -95,8 +95,8 @@ mcp__relaycast__dm_send(to: "Lead", text: "ACK: Starting on the task.")
 
 | 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                                                    |
+| Local (same project)   | `mcp__relaycast__message_dm_send(to: "Lead", ...)`          | `mcp__relaycast__message_dm_send(to: "project:lead", ...)`     |
+| Bridge (cross-project) | `mcp__relaycast__message_dm_send(to: "frontend:Designer", ...)` | N/A                                                    |
 
 ## Multi-Workspace
 
@@ -112,6 +112,6 @@ Relay message from Alice [my-team / abc123]: Hello!
 ## Checking Status
 
 ```
-mcp__relaycast__agent_list()    # List online agents
-mcp__relaycast__inbox_check()   # Check for unread messages
+mcp__relaycast__agent_list()          # List online agents
+mcp__relaycast__message_inbox_check() # Check for unread messages
 ```