agent-relay 3.0.1 → 3.1.0

package/packages/sdk/src/client.ts

@@ -1,5 +1,5 @@
 import { once } from 'node:events';
-import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process';
+import { execSync, spawn, type ChildProcessWithoutNullStreams } from 'node:child_process';
 import { createInterface, type Interface as ReadlineInterface } from 'node:readline';
 import fs from 'node:fs';
 import os from 'node:os';
@@ -14,6 +14,7 @@ import {
   type BrokerStats,
   type BrokerStatus,
   type CrashInsightsResponse,
+  type HeadlessProvider,
   type ProtocolEnvelope,
   type ProtocolError,
   type RestartPolicy,
@@ -51,13 +52,33 @@ export interface SpawnPtyInput {
   continueFrom?: string;
 }
 
-export interface SpawnHeadlessClaudeInput {
+export interface SpawnHeadlessInput {
   name: string;
+  provider: HeadlessProvider;
   args?: string[];
   channels?: string[];
   task?: string;
 }
 
+export type AgentTransport = 'pty' | 'headless';
+
+export interface SpawnProviderInput {
+  name: string;
+  provider: string;
+  transport?: AgentTransport;
+  args?: string[];
+  channels?: string[];
+  task?: string;
+  model?: string;
+  cwd?: string;
+  team?: string;
+  shadowOf?: string;
+  shadowMode?: string;
+  idleThresholdSecs?: number;
+  restartPolicy?: RestartPolicy;
+  continueFrom?: string;
+}
+
 export interface SendMessageInput {
   to: string;
   text: string;
@@ -70,6 +91,7 @@ export interface SendMessageInput {
 export interface ListAgent {
   name: string;
   runtime: AgentRuntime;
+  provider?: HeadlessProvider;
   cli?: string;
   model?: string;
   team?: string;
@@ -113,6 +135,10 @@ export class AgentRelayProcessError extends Error {
   }
 }
 
+function isHeadlessProvider(value: string): value is HeadlessProvider {
+  return value === 'claude' || value === 'opencode';
+}
+
 export class AgentRelayClient {
   private readonly options: Required<AgentRelayClientOptions>;
   private child?: ChildProcessWithoutNullStreams;
@@ -127,6 +153,8 @@ export class AgentRelayClient {
   private eventBuffer: BrokerEvent[] = [];
   private maxBufferSize = 1000;
   private exitPromise?: Promise<void>;
+  /** The workspace key returned by the broker in its hello_ack response. */
+  workspaceKey?: string;
 
   constructor(options: AgentRelayClientOptions = {}) {
     this.options = {
@@ -248,13 +276,12 @@ export class AgentRelayClient {
     return result;
   }
 
-  async spawnHeadlessClaude(
-    input: SpawnHeadlessClaudeInput
-  ): Promise<{ name: string; runtime: AgentRuntime }> {
+  async spawnHeadless(input: SpawnHeadlessInput): Promise<{ name: string; runtime: AgentRuntime }> {
     await this.start();
     const agent: AgentSpec = {
       name: input.name,
-      runtime: 'headless_claude',
+      runtime: 'headless',
+      provider: input.provider,
       args: input.args ?? [],
       channels: input.channels ?? [],
     };
@@ -265,6 +292,52 @@ export class AgentRelayClient {
     return result;
   }
 
+  async spawnProvider(input: SpawnProviderInput): Promise<{ name: string; runtime: AgentRuntime }> {
+    const transport = input.transport ?? (input.provider === 'opencode' ? 'headless' : 'pty');
+    if (transport === 'headless') {
+      if (!isHeadlessProvider(input.provider)) {
+        throw new AgentRelayProcessError(
+          `provider '${input.provider}' does not support headless transport (supported: claude, opencode)`
+        );
+      }
+      return this.spawnHeadless({
+        name: input.name,
+        provider: input.provider,
+        args: input.args,
+        channels: input.channels,
+        task: input.task,
+      });
+    }
+
+    return this.spawnPty({
+      name: input.name,
+      cli: input.provider,
+      args: input.args,
+      channels: input.channels,
+      task: input.task,
+      model: input.model,
+      cwd: input.cwd,
+      team: input.team,
+      shadowOf: input.shadowOf,
+      shadowMode: input.shadowMode,
+      idleThresholdSecs: input.idleThresholdSecs,
+      restartPolicy: input.restartPolicy,
+      continueFrom: input.continueFrom,
+    });
+  }
+
+  async spawnClaude(
+    input: Omit<SpawnProviderInput, 'provider'>
+  ): Promise<{ name: string; runtime: AgentRuntime }> {
+    return this.spawnProvider({ ...input, provider: 'claude' });
+  }
+
+  async spawnOpencode(
+    input: Omit<SpawnProviderInput, 'provider'>
+  ): Promise<{ name: string; runtime: AgentRuntime }> {
+    return this.spawnProvider({ ...input, provider: 'opencode' });
+  }
+
   async release(name: string, reason?: string): Promise<{ name: string }> {
     await this.start();
     return this.requestOk<{ name: string }>('release_agent', { name, reason });
@@ -439,8 +512,11 @@ export class AgentRelayClient {
       });
     });
 
-    await this.requestHello();
+    const helloAck = await this.requestHello();
     console.log('[broker] Broker ready (hello handshake complete)');
+    if (helloAck.workspace_key) {
+      this.workspaceKey = helloAck.workspace_key;
+    }
   }
 
   private disposeProcessHandles(): void {
@@ -528,13 +604,17 @@ export class AgentRelayClient {
     pending.resolve(envelope);
   }
 
-  private async requestHello(): Promise<{ broker_version: string; protocol_version: number }> {
+  private async requestHello(): Promise<{
+    broker_version: string;
+    protocol_version: number;
+    workspace_key?: string;
+  }> {
     const payload = {
       client_name: this.options.clientName,
       client_version: this.options.clientVersion,
     };
     const frame = await this.sendRequest('hello', payload, 'hello_ack');
-    return frame.payload as { broker_version: string; protocol_version: number };
+    return frame.payload as { broker_version: string; protocol_version: number; workspace_key?: string };
   }
 
   private async requestOk<T = unknown>(type: string, payload: unknown): Promise<T> {
@@ -589,12 +669,17 @@ export class AgentRelayClient {
 
 const CLI_MODEL_FLAG_CLIS = new Set(['claude', 'codex', 'gemini', 'goose', 'aider']);
 
+const CLI_DEFAULT_ARGS: Record<string, string[]> = {
+  codex: ['-c', 'check_for_update_on_startup=false'],
+};
+
 function buildPtyArgsWithModel(cli: string, args: string[], model?: string): string[] {
-  const baseArgs = [...args];
+  const cliName = cli.split(':')[0].trim().toLowerCase();
+  const defaultArgs = CLI_DEFAULT_ARGS[cliName] ?? [];
+  const baseArgs = [...defaultArgs, ...args];
   if (!model) {
     return baseArgs;
   }
-  const cliName = cli.split(':')[0].trim().toLowerCase();
   if (!CLI_MODEL_FLAG_CLIS.has(cliName)) {
     return baseArgs;
   }
@@ -634,6 +719,92 @@ function isExplicitPath(binaryPath: string): boolean {
   );
 }
 
+function detectPlatformSuffix(): string | null {
+  const platformMap: Record<string, Record<string, string>> = {
+    darwin: { arm64: 'darwin-arm64', x64: 'darwin-x64' },
+    linux: { arm64: 'linux-arm64', x64: 'linux-x64' },
+  };
+  return platformMap[process.platform]?.[process.arch] ?? null;
+}
+
+function getLatestVersionSync(): string | null {
+  try {
+    const result = execSync('curl -fsSL https://api.github.com/repos/AgentWorkforce/relay/releases/latest', {
+      timeout: 15_000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).toString();
+    const match = result.match(/"tag_name"\s*:\s*"v?([^"]+)"/);
+    return match?.[1] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function installBrokerBinary(): string {
+  const suffix = detectPlatformSuffix();
+  if (!suffix) {
+    throw new AgentRelayProcessError(`Unsupported platform: ${process.platform}-${process.arch}`);
+  }
+
+  const homeDir = process.env.HOME || process.env.USERPROFILE || '';
+  const installDir = path.join(homeDir, '.agent-relay', 'bin');
+  const brokerExe = process.platform === 'win32' ? 'agent-relay-broker.exe' : 'agent-relay-broker';
+  const targetPath = path.join(installDir, brokerExe);
+
+  console.log(`[agent-relay] Broker binary not found, installing for ${suffix}...`);
+
+  const version = getLatestVersionSync();
+  if (!version) {
+    throw new AgentRelayProcessError(
+      'Failed to fetch latest agent-relay version from GitHub.\n' +
+        'Install manually: curl -fsSL https://raw.githubusercontent.com/AgentWorkforce/relay/main/install.sh | bash'
+    );
+  }
+
+  const binaryName = `agent-relay-broker-${suffix}`;
+  const downloadUrl = `https://github.com/AgentWorkforce/relay/releases/download/v${version}/${binaryName}`;
+
+  console.log(`[agent-relay] Downloading v${version} from ${downloadUrl}`);
+
+  try {
+    fs.mkdirSync(installDir, { recursive: true });
+    execSync(`curl -fsSL "${downloadUrl}" -o "${targetPath}"`, {
+      timeout: 60_000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    fs.chmodSync(targetPath, 0o755);
+
+    // macOS: re-sign to avoid Gatekeeper issues
+    if (process.platform === 'darwin') {
+      try {
+        execSync(`codesign --force --sign - "${targetPath}"`, {
+          timeout: 10_000,
+          stdio: ['pipe', 'pipe', 'pipe'],
+        });
+      } catch {
+        // Non-fatal
+      }
+    }
+
+    // Verify
+    execSync(`"${targetPath}" --help`, { timeout: 10_000, stdio: ['pipe', 'pipe', 'pipe'] });
+  } catch (err) {
+    try {
+      fs.unlinkSync(targetPath);
+    } catch {
+      /* ignore */
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    throw new AgentRelayProcessError(
+      `Failed to install broker binary: ${message}\n` +
+        'Install manually: curl -fsSL https://raw.githubusercontent.com/AgentWorkforce/relay/main/install.sh | bash'
+    );
+  }
+
+  console.log(`[agent-relay] Broker installed to ${targetPath}`);
+  return targetPath;
+}
+
 function resolveDefaultBinaryPath(): string {
   const brokerExe = process.platform === 'win32' ? 'agent-relay-broker.exe' : 'agent-relay-broker';
   const moduleDir = path.dirname(fileURLToPath(import.meta.url));
@@ -646,7 +817,17 @@ function resolveDefaultBinaryPath(): string {
   }
 
   // 2. Check for bundled broker binary in SDK package (npm install)
-  const bundled = path.resolve(moduleDir, '..', 'bin', brokerExe);
+  //    Try platform-specific name first (CI publishes per-platform binaries),
+  //    then fall back to the generic name (local dev / postinstall copy).
+  const binDir = path.resolve(moduleDir, '..', 'bin');
+  const suffix = detectPlatformSuffix();
+  if (suffix) {
+    const platformBinary = path.join(binDir, `agent-relay-broker-${suffix}`);
+    if (fs.existsSync(platformBinary)) {
+      return platformBinary;
+    }
+  }
+  const bundled = path.join(binDir, brokerExe);
   if (fs.existsSync(bundled)) {
     return bundled;
   }
@@ -658,6 +839,6 @@ function resolveDefaultBinaryPath(): string {
     return standaloneBroker;
   }
 
-  // 4. Fall back to agent-relay on PATH (may be Node CLI — will fail for broker ops)
-  return 'agent-relay';
+  // 4. Auto-install from GitHub releases
+  return installBrokerBinary();
 }

package/packages/sdk/src/examples/workflows/runner-idle-refactor.yaml

@@ -0,0 +1,306 @@
+version: '1.0'
+name: runner-idle-refactor
+description: >
+  Refactors WorkflowRunner with two changes:
+    1. Remove agent pre-registration (preflightAgents) — agents spawn only when their step runs.
+    2. Idle = done — when no idleNudge config is set, race waitForExit vs waitForIdle;
+       if idle fires first the step completes immediately.
+
+  Workflow: read context → implement → update tests → type-check → run tests
+  → fix if broken → final test run → review.
+
+swarm:
+  pattern: pipeline
+  maxConcurrency: 3
+  timeoutMs: 1800000 # 30 min
+  channel: wf-runner-refactor
+
+# No idleNudge — each agent is spawned per step and exits when done.
+# Non-interactive preset for all agents (pure code changes, no relay tools needed).
+
+agents:
+  - name: implementer
+    cli: codex
+    preset: worker
+    role: 'Makes the two targeted edits to packages/sdk/src/workflows/runner.ts.'
+    constraints:
+      model: gpt-5.3-codex
+
+  - name: test-writer
+    cli: codex
+    preset: worker
+    role: 'Adds new test cases to idle-nudge.test.ts covering the idle=done behavior.'
+    constraints:
+      model: gpt-5.3-codex
+
+  - name: fixer
+    cli: codex
+    preset: worker
+    role: 'Fixes TypeScript errors or failing tests found in the test run.'
+    constraints:
+      model: gpt-5.3-codex
+
+  - name: reviewer
+    cli: claude
+    preset: reviewer
+    role: 'Reviews the diff for correctness, edge cases, and backwards compatibility.'
+    constraints:
+      model: sonnet
+
+workflows:
+  - name: default
+    onError: continue
+
+    steps:
+      # ── Phase 1: Capture context for agents ───────────────────────────────
+
+      - name: read-prespawn-block
+        type: deterministic
+        command: >
+          grep -n "Pre-register all interactive\|preflightAgents\|Agent pre-registration"
+          packages/sdk/src/workflows/runner.ts | head -10 &&
+          echo "---" &&
+          awk '/Pre-register all interactive agent steps/,/Agent pre-registration complete/{print NR": "$0}'
+          packages/sdk/src/workflows/runner.ts
+        captureOutput: true
+        failOnError: false
+
+      - name: read-spawn-comment
+        type: deterministic
+        command: >
+          grep -n "cache.*hit\|preflightAgents\|token cache"
+          packages/sdk/src/workflows/runner.ts | head -10
+        captureOutput: true
+        failOnError: false
+
+      - name: read-idle-method
+        type: deterministic
+        command: >
+          awk '/private async waitForExitWithIdleNudging/,/^  \}$/{print NR": "$0}'
+          packages/sdk/src/workflows/runner.ts | head -80
+        captureOutput: true
+        failOnError: false
+
+      - name: read-test-file
+        type: deterministic
+        dependsOn: [read-prespawn-block]
+        command: cat packages/sdk/src/__tests__/idle-nudge.test.ts
+        captureOutput: true
+        failOnError: false
+
+      # ── Phase 2: Implement runner.ts changes ──────────────────────────────
+
+      - name: implement
+        type: agent
+        agent: implementer
+        dependsOn: [read-prespawn-block, read-spawn-comment, read-idle-method]
+        task: |
+          Make exactly two changes to `packages/sdk/src/workflows/runner.ts`:
+
+          ── Change 1: Remove agent pre-registration block ──
+
+          Find the block that starts with this comment and delete it entirely:
+            // Pre-register all interactive agent steps with Relaycast before execution.
+
+          The block ends with:
+            this.log('Agent pre-registration complete');
+          followed by the closing `}` of the if statement.
+
+          Here is what the block looks like (with line numbers for reference):
+          {{steps.read-prespawn-block.output}}
+
+          Also find and update the stale comment inside `spawnAndWait` that says something
+          about "token cache" / "cache hits" / "preflightAgents" — those references are now
+          stale. Keep just: "Deterministic name: step name + first 8 chars of run ID."
+
+          Stale comment location:
+          {{steps.read-spawn-comment.output}}
+
+          ── Change 2: Idle = done in waitForExitWithIdleNudging ──
+
+          Find the `waitForExitWithIdleNudging` method. In the branch where `nudgeConfig` is
+          absent, replace the simple `return agent.waitForExit(timeoutMs)` with a race between
+          `waitForExit` and `waitForIdle`. If idle wins, release the agent and return 'released'.
+
+          Current method (with line numbers):
+          {{steps.read-idle-method.output}}
+
+          Replace the no-nudge-config branch with:
+          ```typescript
+          if (!nudgeConfig) {
+            // Idle = done: race exit against idle. Whichever fires first completes the step.
+            const result = await Promise.race([
+              agent.waitForExit(timeoutMs).then((r) => ({ kind: 'exit' as const, result: r })),
+              agent.waitForIdle(timeoutMs).then((r) => ({ kind: 'idle' as const, result: r })),
+            ]);
+            if (result.kind === 'idle' && result.result === 'idle') {
+              this.log(`[${step.name}] Agent "${agent.name}" went idle — treating as complete`);
+              this.postToChannel(`**[${step.name}]** Agent \`${agent.name}\` idle — treating as complete`);
+              await agent.release();
+              return 'released';
+            }
+            // Exit won the race, or idle returned 'exited'/'timeout' — pass through.
+            return result.result as 'exited' | 'timeout' | 'released';
+          }
+          ```
+
+          Only modify these two things. Do not change anything else.
+        verification:
+          type: exit_code
+
+      # ── Phase 3: Update tests ──────────────────────────────────────────────
+
+      - name: update-tests
+        type: agent
+        agent: test-writer
+        dependsOn: [implement, read-test-file]
+        task: |
+          Add new test cases to `packages/sdk/src/__tests__/idle-nudge.test.ts` for the
+          new idle=done behavior. Do NOT modify any existing tests — only append new ones.
+
+          Current test file:
+          {{steps.read-test-file.output}}
+
+          Background on the change:
+          - When `idleNudge` config is absent in the swarm config, `waitForExitWithIdleNudging`
+            now races `waitForExit` vs `waitForIdle`.
+          - If `waitForIdle` resolves with `'idle'` first → `agent.release()` is called and
+            the method returns `'released'`.
+          - If `waitForExit` resolves first → that result is returned as-is.
+          - If `waitForIdle` resolves with `'exited'` or `'timeout'` → exit result wins.
+
+          The mock infrastructure already has `waitForExitFn` and `waitForIdleFn` that you
+          can control. Add a new describe block: `'Idle = done (no idleNudge config)'` with:
+
+          Test 1 — idle fires first:
+            waitForIdleFn resolves 'idle' immediately
+            waitForExitFn never resolves (returns a never-settling promise or very long timeout)
+            → workflow run should complete (step succeeds, agent.release() is called)
+
+          Test 2 — exit fires first:
+            waitForExitFn resolves 'exited' immediately
+            waitForIdleFn resolves 'timeout' (or never fires before exit)
+            → workflow run should complete, agent.release() NOT called by idle logic
+
+          Test 3 — both timeout:
+            waitForExitFn resolves 'timeout'
+            waitForIdleFn resolves 'timeout'
+            → step should fail with a timeout error
+
+          Use the existing `makeConfig()` and `makeDb()` helpers. Use the existing
+          `WorkflowRunner` import pattern already in the file.
+        verification:
+          type: exit_code
+
+      # ── Phase 4: Type-check ────────────────────────────────────────────────
+
+      - name: type-check
+        type: deterministic
+        dependsOn: [implement, update-tests]
+        command: >
+          cd packages/sdk &&
+          npx tsc --noEmit 2>&1 | tail -30 &&
+          echo "TYPE_CHECK_PASSED" || echo "TYPE_CHECK_FAILED"
+        captureOutput: true
+        failOnError: false
+
+      # ── Phase 5: Run vitest ────────────────────────────────────────────────
+
+      - name: run-tests
+        type: deterministic
+        dependsOn: [type-check]
+        command: >-
+          cd packages/sdk && { npx vitest run 2>&1; echo "EXIT:$?"; } | tail -80
+        captureOutput: true
+        failOnError: false
+
+      # ── Phase 6: Fix failures ──────────────────────────────────────────────
+
+      - name: fix-if-broken
+        type: agent
+        agent: fixer
+        dependsOn: [run-tests, type-check]
+        task: |
+          Review the type-check and test results. Fix any failures.
+
+          Type-check:
+          {{steps.type-check.output}}
+
+          Test run:
+          {{steps.run-tests.output}}
+
+          If both show PASSED / ALL_TESTS_PASSED, output: FIX_DONE:none
+
+          Otherwise:
+          - For TypeScript errors: fix packages/sdk/src/workflows/runner.ts
+          - For failing tests: fix packages/sdk/src/__tests__/idle-nudge.test.ts
+          - Do NOT change the intended behavior — only fix syntax/type/mock issues
+
+        verification:
+          type: exit_code
+        maxIterations: 2
+
+      # ── Phase 7: Final test run ────────────────────────────────────────────
+
+      - name: final-tests
+        type: deterministic
+        dependsOn: [fix-if-broken]
+        command: >-
+          cd packages/sdk && { npx vitest run 2>&1; echo "EXIT:$?"; } | tail -60
+        captureOutput: true
+        failOnError: false
+
+      # ── Phase 8: Capture diff for review ──────────────────────────────────
+
+      - name: capture-diff
+        type: deterministic
+        dependsOn: [final-tests]
+        command: >
+          git diff packages/sdk/src/workflows/runner.ts
+          packages/sdk/src/__tests__/idle-nudge.test.ts
+        captureOutput: true
+        failOnError: false
+
+      # ── Phase 9: Code review ───────────────────────────────────────────────
+
+      - name: review
+        type: agent
+        agent: reviewer
+        dependsOn: [capture-diff, final-tests]
+        task: |
+          Review these changes to WorkflowRunner. Be precise and thorough.
+
+          Final test result:
+          {{steps.final-tests.output}}
+
+          Diff:
+          {{steps.capture-diff.output}}
+
+          Review checklist:
+          1. Pre-registration block is fully gone — no leftover `preflightAgents` calls or
+             stale comments referencing "token cache" / "cache hits"
+          2. Race logic in `waitForExitWithIdleNudging`: both promises created before awaiting?
+             No floating promise leak if exit wins before idle settles?
+          3. Edge case: `waitForIdle` returns 'exited' (agent already gone) — does the cast
+             `result.result as 'exited' | 'timeout' | 'released'` hold? Check the union types.
+          4. Edge case: `waitForIdle` returns 'timeout' and exit won — correct fallthrough?
+          5. New tests: do they actually cover all three cases with proper mock wiring?
+          6. No unintended changes to the nudge path (idleNudge config present) — that code
+             should be unchanged.
+
+        verification:
+          type: exit_code
+
+errorHandling:
+  strategy: continue # best-effort — don't abort if an optional step fails
+  maxRetries: 1
+  retryDelayMs: 3000
+  notifyChannel: wf-runner-refactor
+
+state:
+  backend: memory
+  ttlMs: 7200000 # 2 hours
+
+trajectories:
+  enabled: true
+  autoDecisions: true

package/packages/sdk/src/protocol.ts

@@ -1,6 +1,7 @@
 export const PROTOCOL_VERSION = 1 as const;
 
-export type AgentRuntime = 'pty' | 'headless_claude';
+export type AgentRuntime = 'pty' | 'headless';
+export type HeadlessProvider = 'claude' | 'opencode';
 
 export interface RestartPolicy {
   enabled?: boolean;
@@ -12,6 +13,7 @@ export interface RestartPolicy {
 export interface AgentSpec {
   name: string;
   runtime: AgentRuntime;
+  provider?: HeadlessProvider;
   cli?: string;
   args?: string[];
   channels?: string[];
@@ -112,6 +114,7 @@ export interface BrokerStatus {
   agents: Array<{
     name: string;
     runtime: AgentRuntime;
+    provider?: HeadlessProvider;
     cli?: string;
     model?: string;
     team?: string;
@@ -180,6 +183,7 @@ export type BrokerEvent =
       kind: 'agent_spawned';
       name: string;
       runtime: AgentRuntime;
+      provider?: HeadlessProvider;
       cli?: string;
       model?: string;
       parent?: string;
@@ -271,6 +275,7 @@ export type BrokerEvent =
       kind: 'worker_ready';
       name: string;
       runtime: AgentRuntime;
+      provider?: HeadlessProvider;
       cli?: string;
       model?: string;
     }
@@ -361,7 +366,7 @@ export type BrokerToWorker =
 export type WorkerToBroker =
   | {
       type: 'worker_ready';
-      payload: { name: string; runtime: AgentRuntime };
+      payload: { name: string; runtime: AgentRuntime; provider?: HeadlessProvider };
     }
   | {
       type: 'delivery_ack';