agent-relay 3.0.1 → 3.1.0

package/packages/sdk/src/relay.ts

@@ -33,7 +33,7 @@ import {
   type SendMessageInput,
   type SpawnPtyInput,
 } from './client.js';
-import type { AgentRuntime, BrokerEvent, BrokerStatus, RestartPolicy } from './protocol.js';
+import type { AgentRuntime, BrokerEvent, BrokerStatus, HeadlessProvider, RestartPolicy } from './protocol.js';
 import {
   followLogs as followLogsFromFile,
   getLogs as getLogsFromFile,
@@ -87,7 +87,47 @@ export interface DeliveryState {
   updatedAt: number;
 }
 
-export interface SpawnOptions {
+export interface SpawnLifecycleContext {
+  name: string;
+  cli: string;
+  channels: string[];
+  task?: string;
+}
+
+export interface SpawnLifecycleSuccessContext extends SpawnLifecycleContext {
+  runtime: AgentRuntime;
+}
+
+export interface SpawnLifecycleErrorContext extends SpawnLifecycleContext {
+  error: unknown;
+}
+
+export interface SpawnLifecycleHooks {
+  onStart?: (context: SpawnLifecycleContext) => void | Promise<void>;
+  onSuccess?: (context: SpawnLifecycleSuccessContext) => void | Promise<void>;
+  onError?: (context: SpawnLifecycleErrorContext) => void | Promise<void>;
+}
+
+export interface ReleaseLifecycleContext {
+  name: string;
+  reason?: string;
+}
+
+export interface ReleaseLifecycleErrorContext extends ReleaseLifecycleContext {
+  error: unknown;
+}
+
+export interface ReleaseLifecycleHooks {
+  onStart?: (context: ReleaseLifecycleContext) => void | Promise<void>;
+  onSuccess?: (context: ReleaseLifecycleContext) => void | Promise<void>;
+  onError?: (context: ReleaseLifecycleErrorContext) => void | Promise<void>;
+}
+
+export interface ReleaseOptions extends ReleaseLifecycleHooks {
+  reason?: string;
+}
+
+export interface SpawnOptions extends SpawnLifecycleHooks {
   args?: string[];
   channels?: string[];
   model?: string;
@@ -119,7 +159,7 @@ export interface Agent {
   exitSignal?: string;
   /** Set when the agent requests exit via /exit. Available after `onAgentExitRequested` fires. */
   exitReason?: string;
-  release(reason?: string): Promise<void>;
+  release(reasonOrOptions?: string | ReleaseOptions): Promise<void>;
   waitForReady(timeoutMs?: number): Promise<void>;
   /** Wait for the agent process to exit on its own.
    *  @param timeoutMs — optional timeout in ms. Resolves with `"timeout"` if exceeded,
@@ -152,14 +192,16 @@ export interface HumanHandle {
 }
 
 export interface AgentSpawner {
-  spawn(options?: {
-    name?: string;
-    args?: string[];
-    channels?: string[];
-    task?: string;
-    model?: string;
-    cwd?: string;
-  }): Promise<Agent>;
+  spawn(options?: SpawnerSpawnOptions): Promise<Agent>;
+}
+
+export interface SpawnerSpawnOptions extends SpawnLifecycleHooks {
+  name?: string;
+  args?: string[];
+  channels?: string[];
+  task?: string;
+  model?: string;
+  cwd?: string;
 }
 
 export type EventHook<T> = ((value: T) => void) | null;
@@ -173,6 +215,17 @@ export interface AgentRelayOptions {
   env?: NodeJS.ProcessEnv;
   requestTimeoutMs?: number;
   shutdownTimeoutMs?: number;
+  /**
+   * Name for the auto-created Relaycast workspace.
+   * If omitted, a random name is generated.
+   * Ignored when RELAY_API_KEY is already set in env or process.env.
+   */
+  workspaceName?: string;
+  /**
+   * Base URL for the Relaycast API.
+   * Defaults to RELAYCAST_BASE_URL env var or https://api.relaycast.dev.
+   */
+  relaycastBaseUrl?: string;
 }
 
 type OutputListener = {
@@ -195,6 +248,19 @@ export class AgentRelay {
   onAgentExitRequested: EventHook<{ name: string; reason: string }> = null;
   onAgentIdle: EventHook<{ name: string; idleSecs: number }> = null;
 
+  // ── Public accessors ────────────────────────────────────────────────────
+
+  /** The resolved Relaycast workspace API key (available after first spawn). */
+  get workspaceKey(): string | undefined {
+    return this.relayApiKey;
+  }
+
+  /** Observer URL for the auto-created workspace (available after first spawn). */
+  get observerUrl(): string | undefined {
+    if (!this.relayApiKey) return undefined;
+    return `https://observer.relaycast.dev/?key=${this.relayApiKey}`;
+  }
+
   // Shorthand spawners
   readonly codex: AgentSpawner;
   readonly claude: AgentSpawner;
@@ -202,6 +268,9 @@ export class AgentRelay {
 
   private readonly clientOptions: AgentRelayClientOptions;
   private readonly defaultChannels: string[];
+  private readonly workspaceName?: string;
+  private readonly relaycastBaseUrl?: string;
+  private relayApiKey?: string;
   private client?: AgentRelayClient;
   private startPromise?: Promise<AgentRelayClient>;
   private unsubEvent?: () => void;
@@ -225,6 +294,8 @@ export class AgentRelay {
 
   constructor(options: AgentRelayOptions = {}) {
     this.defaultChannels = options.channels ?? ['general'];
+    this.workspaceName = options.workspaceName;
+    this.relaycastBaseUrl = options.relaycastBaseUrl;
     this.clientOptions = {
       binaryPath: options.binaryPath,
       binaryArgs: options.binaryArgs,
@@ -267,7 +338,7 @@ export class AgentRelay {
 
   // ── Spawning ────────────────────────────────────────────────────────────
 
-  async spawnPty(input: SpawnPtyInput): Promise<Agent> {
+  async spawnPty(input: SpawnPtyInput & SpawnLifecycleHooks): Promise<Agent> {
     const client = await this.ensureStarted();
     if (!input.channels || input.channels.length === 0) {
       console.warn(
@@ -276,26 +347,52 @@ export class AgentRelay {
       );
     }
     const channels = input.channels ?? ['general'];
-    const result = await client.spawnPty({
+    const lifecycleContext: SpawnLifecycleContext = {
       name: input.name,
       cli: input.cli,
-      args: input.args,
       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,
-    });
-    this.readyAgents.delete(result.name);
-    this.messageReadyAgents.delete(result.name);
-    this.exitedAgents.delete(result.name);
-    this.idleAgents.delete(result.name);
+    };
+    await this.invokeLifecycleHook(input.onStart, lifecycleContext, `spawnPty("${input.name}") onStart`);
+    let result: { name: string; runtime: AgentRuntime };
+    try {
+      result = await client.spawnPty({
+        name: input.name,
+        cli: input.cli,
+        args: input.args,
+        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,
+      });
+    } catch (error) {
+      await this.invokeLifecycleHook(
+        input.onError,
+        {
+          ...lifecycleContext,
+          error,
+        },
+        `spawnPty("${input.name}") onError`
+      );
+      throw error;
+    }
+    this.resetAgentLifecycleState(result.name);
     const agent = this.makeAgent(result.name, result.runtime, channels);
     this.knownAgents.set(agent.name, agent);
+    await this.invokeLifecycleHook(
+      input.onSuccess,
+      {
+        ...lifecycleContext,
+        name: result.name,
+        runtime: result.runtime,
+      },
+      `spawnPty("${input.name}") onSuccess`
+    );
     return agent;
   }
 
@@ -313,6 +410,9 @@ export class AgentRelay {
       shadowMode: options?.shadowMode,
       idleThresholdSecs: options?.idleThresholdSecs,
       restartPolicy: options?.restartPolicy,
+      onStart: options?.onStart,
+      onSuccess: options?.onSuccess,
+      onError: options?.onError,
     });
   }
 
@@ -322,7 +422,7 @@ export class AgentRelay {
     if (waitForMessage) {
       return this.waitForAgentMessage(name, timeoutMs ?? 60_000);
     }
-    return this.waitForAgentReady(name, timeoutMs ?? 30_000);
+    return this.waitForAgentReady(name, timeoutMs ?? 60_000);
   }
 
   // ── Human source ────────────────────────────────────────────────────────
@@ -551,7 +651,7 @@ export class AgentRelay {
    * The agent's CLI may not yet be ready to receive messages.
    * Use `waitForAgentMessage()` for full readiness.
    */
-  async waitForAgentReady(name: string, timeoutMs = 30_000): Promise<Agent> {
+  async waitForAgentReady(name: string, timeoutMs = 60_000): Promise<Agent> {
     const client = await this.ensureStarted();
     const existing = this.knownAgents.get(name);
     if (existing && this.readyAgents.has(name)) {
@@ -750,14 +850,56 @@ export class AgentRelay {
     }
   }
 
+  /**
+   * Ensure a Relaycast workspace API key is available.
+   * Resolution order:
+   *   1. Already resolved (cached from a previous call)
+   *   2. RELAY_API_KEY in options.env
+   *   3. RELAY_API_KEY in process.env
+   *   4. Auto-create a fresh workspace via the Relaycast REST API
+   */
+  private async ensureRelaycastApiKey(): Promise<void> {
+    if (this.relayApiKey) return;
+
+    const envKey = this.clientOptions.env?.RELAY_API_KEY ?? process.env.RELAY_API_KEY;
+    if (envKey) {
+      this.relayApiKey = envKey;
+      // Ensure the broker subprocess inherits the full process env + the key.
+      // Without this, spawning with an explicit binaryPath but no env option
+      // would cause the broker to start with an empty environment (no PATH,
+      // no RELAY_API_KEY), making connect_relay() hang and triggering the
+      // hello-handshake timeout.
+      if (!this.clientOptions.env) {
+        this.clientOptions.env = { ...process.env, RELAY_API_KEY: envKey };
+      } else if (!this.clientOptions.env.RELAY_API_KEY) {
+        this.clientOptions.env.RELAY_API_KEY = envKey;
+      }
+      return;
+    }
+
+    // No API key in env — broker will create/select its own workspace.
+    // Ensure the broker process inherits the full environment (PATH, etc.)
+    // so it can connect to Relaycast. The actual workspace key will be
+    // read from the broker's hello_ack response in ensureStarted().
+    if (!this.clientOptions.env) {
+      this.clientOptions.env = { ...process.env };
+    }
+  }
+
   private async ensureStarted(): Promise<AgentRelayClient> {
     if (this.client) return this.client;
     if (this.startPromise) return this.startPromise;
 
-    this.startPromise = AgentRelayClient.start(this.clientOptions)
+    this.startPromise = this.ensureRelaycastApiKey()
+      .then(() => AgentRelayClient.start(this.clientOptions))
       .then((c) => {
         this.client = c;
         this.startPromise = undefined;
+        // Use the workspace key the broker actually connected with.
+        // This ensures SDK and workers are always on the same workspace.
+        if (c.workspaceKey) {
+          this.relayApiKey = c.workspaceKey;
+        }
         this.wireEvents(c);
         return c;
       })
@@ -919,11 +1061,34 @@ export class AgentRelay {
       },
       exitCode: undefined,
       exitSignal: undefined,
-      async release(reason?: string) {
+      async release(reasonOrOptions?: string | ReleaseOptions) {
+        const releaseOptions = relay.normalizeReleaseOptions(reasonOrOptions);
+        const releaseContext: ReleaseLifecycleContext = {
+          name,
+          reason: releaseOptions.reason,
+        };
         const client = await relay.ensureStarted();
-        await client.release(name, reason);
+        await relay.invokeLifecycleHook(releaseOptions.onStart, releaseContext, `release("${name}") onStart`);
+        try {
+          await client.release(name, releaseOptions.reason);
+          await relay.invokeLifecycleHook(
+            releaseOptions.onSuccess,
+            releaseContext,
+            `release("${name}") onSuccess`
+          );
+        } catch (error) {
+          await relay.invokeLifecycleHook(
+            releaseOptions.onError,
+            {
+              ...releaseContext,
+              error,
+            },
+            `release("${name}") onError`
+          );
+          throw error;
+        }
       },
-      async waitForReady(timeoutMs = 30_000) {
+      async waitForReady(timeoutMs = 60_000) {
         await relay.waitForAgentReady(name, timeoutMs);
       },
       waitForExit(timeoutMs?: number) {
@@ -1046,17 +1211,13 @@ export class AgentRelay {
   private createSpawner(cli: string, defaultName: string, runtime: AgentRuntime): AgentSpawner {
     return {
       spawn: async (options?) => {
-        const client = await this.ensureStarted();
         const name = options?.name ?? defaultName;
         const channels = options?.channels ?? ['general'];
         const args = options?.args ?? [];
 
         const task = options?.task;
-        let result: { name: string; runtime: AgentRuntime };
-        if (runtime === 'headless_claude') {
-          result = await client.spawnHeadlessClaude({ name, args, channels, task });
-        } else {
-          result = await client.spawnPty({
+        if (runtime === 'pty') {
+          return this.spawnPty({
             name,
             cli,
             args,
@@ -1064,13 +1225,85 @@ export class AgentRelay {
             task,
             model: options?.model,
             cwd: options?.cwd,
+            onStart: options?.onStart,
+            onSuccess: options?.onSuccess,
+            onError: options?.onError,
           });
         }
 
+        const client = await this.ensureStarted();
+        const lifecycleContext: SpawnLifecycleContext = {
+          name,
+          cli,
+          channels,
+          task,
+        };
+        await this.invokeLifecycleHook(options?.onStart, lifecycleContext, `spawn("${name}") onStart`);
+        let result: { name: string; runtime: AgentRuntime };
+        try {
+          result = await client.spawnProvider({
+            name,
+            provider: cli as HeadlessProvider,
+            transport: 'headless',
+            args,
+            channels,
+            task,
+          });
+        } catch (error) {
+          await this.invokeLifecycleHook(
+            options?.onError,
+            {
+              ...lifecycleContext,
+              error,
+            },
+            `spawn("${name}") onError`
+          );
+          throw error;
+        }
+
+        this.resetAgentLifecycleState(result.name);
         const agent = this.makeAgent(result.name, result.runtime, channels);
         this.knownAgents.set(agent.name, agent);
+        await this.invokeLifecycleHook(
+          options?.onSuccess,
+          {
+            ...lifecycleContext,
+            name: result.name,
+            runtime: result.runtime,
+          },
+          `spawn("${name}") onSuccess`
+        );
         return agent;
       },
     };
   }
+
+  private async invokeLifecycleHook<T>(
+    hook: ((context: T) => void | Promise<void>) | undefined,
+    context: T,
+    label: string
+  ): Promise<void> {
+    if (!hook) {
+      return;
+    }
+    try {
+      await hook(context);
+    } catch (error) {
+      console.warn(`[AgentRelay] ${label} hook threw`, error);
+    }
+  }
+
+  private resetAgentLifecycleState(name: string): void {
+    this.readyAgents.delete(name);
+    this.messageReadyAgents.delete(name);
+    this.exitedAgents.delete(name);
+    this.idleAgents.delete(name);
+  }
+
+  private normalizeReleaseOptions(reasonOrOptions?: string | ReleaseOptions): ReleaseOptions {
+    if (typeof reasonOrOptions === 'string' || reasonOrOptions === undefined) {
+      return { reason: reasonOrOptions };
+    }
+    return reasonOrOptions;
+  }
 }

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

@@ -4,7 +4,7 @@
  * persists state to DB, and supports pause/resume/abort with retries.
  */
 
-import { spawn as cpSpawn } from 'node:child_process';
+import { spawn as cpSpawn, execFileSync } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
 import { createWriteStream, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import type { WriteStream } from 'node:fs';
@@ -103,6 +103,31 @@ interface StepState {
   agent?: Agent;
 }
 
+// ── CLI resolution ───────────────────────────────────────────────────────────
+
+/**
+ * Resolve `cursor` to the concrete cursor agent binary available in PATH.
+ * Prefers `cursor-agent` over `agent`. Falls back to `agent` if neither
+ * `cursor-agent` nor a real cursor IDE CLI is found.
+ * Result is memoized after the first call to avoid repeated sync PATH lookups.
+ */
+let _resolvedCursorCli: 'cursor-agent' | 'agent' | undefined;
+function resolveCursorCli(): 'cursor-agent' | 'agent' {
+  if (_resolvedCursorCli !== undefined) return _resolvedCursorCli;
+  const candidates: Array<'cursor-agent' | 'agent'> = ['cursor-agent', 'agent'];
+  for (const candidate of candidates) {
+    try {
+      execFileSync('which', [candidate], { stdio: 'ignore' });
+      _resolvedCursorCli = candidate;
+      return candidate;
+    } catch {
+      // not in PATH, try next
+    }
+  }
+  _resolvedCursorCli = 'agent'; // last-resort default
+  return _resolvedCursorCli;
+}
+
 // ── WorkflowRunner ──────────────────────────────────────────────────────────
 
 export class WorkflowRunner {
@@ -223,6 +248,21 @@ export class WorkflowRunner {
 
     this.relayApiKey = apiKey;
     this.relayApiKeyAutoCreated = true;
+
+    // Best-effort: push the key to a co-running dashboard (agent-relay up) so it
+    // can make Relaycast API calls without any file or manual env var setup.
+    const dashboardPort = process.env.AGENT_RELAY_DASHBOARD_PORT || '3888';
+    fetch(`http://127.0.0.1:${dashboardPort}/api/relay-config`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ apiKey }),
+    }).then((res) => {
+      if (!res.ok) {
+        console.warn(`[WorkflowRunner] dashboard key push failed: HTTP ${res.status}`);
+      }
+    }).catch(() => {
+      // Dashboard not running — silently ignore.
+    });
   }
 
   private getRelayEnv(): NodeJS.ProcessEnv | undefined {
@@ -1102,8 +1142,7 @@ export class WorkflowRunner {
       this.log('API key resolved');
       if (this.relayApiKeyAutoCreated && this.relayApiKey) {
         this.log(`Workspace created — follow this run in Relaycast:`);
-        this.log(`  RELAY_API_KEY=${this.relayApiKey}`);
-        this.log(`  Observer: https://observer.relaycast.dev (paste key above)`);
+        this.log(`  Observer: https://observer.relaycast.dev/?key=${this.relayApiKey}`);
         this.log(`  Channel: ${channel}`);
       }
 
@@ -1237,30 +1276,6 @@ export class WorkflowRunner {
         await this.runPreflightChecks(workflow.preflight, runId);
       }
 
-      // Pre-register all interactive agent steps with Relaycast before execution.
-      // This warms the broker's token cache so spawn_agent calls are instant cache
-      // hits rather than blocking on individual HTTP registrations per spawn.
-      // Agent names use the run ID prefix (deterministic) so we can predict them.
-      if (this.relay && !isResume) {
-        const agentPreflight = workflow.steps
-          .filter((s) => s.type !== 'deterministic' && s.type !== 'worktree' && s.agent)
-          .map((s) => {
-            const agentDef = agentMap.get(s.agent!);
-            return agentDef && agentDef.interactive !== false
-              ? { name: `${s.name}-${runId.slice(0, 8)}`, cli: agentDef.cli }
-              : null;
-          })
-          .filter((e): e is { name: string; cli: AgentCli } => e !== null);
-
-        if (agentPreflight.length > 0) {
-          this.log(`Pre-registering ${agentPreflight.length} agents with Relaycast...`);
-          await this.relay.preflightAgents(agentPreflight).catch((err: Error) => {
-            this.log(`[preflight-agents] warning: ${err.message} — continuing without pre-registration`);
-          });
-          this.log('Agent pre-registration complete');
-        }
-      }
-
       this.log(`Executing ${workflow.steps.length} steps (pattern: ${config.swarm.pattern})`);
       await this.executeSteps(workflow, stepStates, agentMap, config.errorHandling, runId);
 
@@ -1785,9 +1800,6 @@ export class WorkflowRunner {
       await this.persistStepOutput(runId, step.name, output);
 
       this.emit({ type: 'step:completed', runId, stepName: step.name, output });
-      this.postToChannel(
-        `**[${step.name}]** Completed (deterministic)\n${output.slice(0, 500)}${output.length > 500 ? '\n...(truncated)' : ''}`
-      );
     } catch (err) {
       const errorMsg = err instanceof Error ? err.message : String(err);
       this.postToChannel(`**[${step.name}]** Failed: ${errorMsg}`);
@@ -2081,9 +2093,6 @@ export class WorkflowRunner {
         await this.persistStepOutput(runId, step.name, output);
 
         this.emit({ type: 'step:completed', runId, stepName: step.name, output });
-        this.postToChannel(
-          `**[${step.name}]** Completed\n${output.slice(0, 500)}${output.length > 500 ? '\n...(truncated)' : ''}`
-        );
         await this.trajectory?.stepCompleted(step, output, attempt + 1);
         return;
       } catch (err) {
@@ -2136,6 +2145,13 @@ export class WorkflowRunner {
         return { cmd: 'aider', args: ['--message', task, '--yes-always', '--no-git', ...extraArgs] };
       case 'goose':
         return { cmd: 'goose', args: ['run', '--text', task, '--no-session', ...extraArgs] };
+      case 'cursor-agent':
+      case 'agent':
+        return { cmd: cli, args: ['--force', '-p', task, ...extraArgs] };
+      case 'cursor':
+        // Should not reach here after resolveAgentDef resolves to agent/cursor-agent,
+        // but handle as fallback.
+        return { cmd: resolveCursorCli(), args: ['--force', '-p', task, ...extraArgs] };
     }
   }
 
@@ -2144,13 +2160,16 @@ export class WorkflowRunner {
    * Explicit fields on the definition always win over preset-inferred defaults.
    */
   private static resolveAgentDef(def: AgentDefinition): AgentDefinition {
-    if (!def.preset) return def;
+    // Resolve "cursor" alias to whichever cursor agent binary is in PATH
+    const resolvedCli: AgentCli = def.cli === 'cursor' ? resolveCursorCli() : def.cli;
+
+    if (!def.preset) return resolvedCli !== def.cli ? { ...def, cli: resolvedCli } : def;
     const nonInteractivePresets: AgentPreset[] = ['worker', 'reviewer', 'analyst'];
     const defaults: Partial<AgentDefinition> = nonInteractivePresets.includes(def.preset)
       ? { interactive: false }
       : {};
     // Explicit fields on the def always win
-    return { ...defaults, ...def } as AgentDefinition;
+    return { ...defaults, ...def, cli: resolvedCli } as AgentDefinition;
   }
 
   /**
@@ -2386,10 +2405,6 @@ export class WorkflowRunner {
     }
 
     // Deterministic name: step name + first 8 chars of run ID.
-    // This matches the names pre-registered in preflightAgents(), so the broker
-    // hits its token cache instantly instead of making a fresh Relaycast HTTP call.
-    // On retry the broker may suffix a UUID (409 conflict) — that's fine, the agent
-    // still works, just without the cache benefit.
     let agentName = `${step.name}-${(this.currentRunId ?? this.generateShortId()).slice(0, 8)}`;
 
     // Only inject delegation guidance for lead/coordinator agents, not spokes/workers.
@@ -2628,8 +2643,19 @@ export class WorkflowRunner {
   ): Promise<'exited' | 'timeout' | 'released'> {
     const nudgeConfig = this.currentConfig?.swarm.idleNudge;
     if (!nudgeConfig) {
-      // No nudge config — backward compatible simple wait
-      return agent.waitForExit(timeoutMs);
+      // 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';
     }
 
     const nudgeAfterMs = nudgeConfig.nudgeAfterMs ?? 120_000;
@@ -3209,7 +3235,8 @@ export class WorkflowRunner {
     // Includes block-element chars (▗▖▘▝) used in the Claude Code header bar.
     const SPINNER =
       '\\u2756\\u2738\\u2739\\u273a\\u273b\\u273c\\u273d\\u2731\\u2732\\u2733\\u2734\\u2735\\u2736\\u2737\\u2743\\u2745\\u2746\\u25d6\\u25d7\\u25d8\\u25d9\\u2022\\u25cf\\u25cb\\u25a0\\u25a1\\u25b6\\u25c0\\u23f5\\u23f6\\u23f7\\u23f8\\u23f9\\u25e2\\u25e3\\u25e4\\u25e5\\u2597\\u2596\\u2598\\u259d\\u2bc8\\u2bc7\\u2bc5\\u2bc6\\u00b7' +
-      '\\u2590\\u258c\\u2588\\u2584\\u2580\\u259a\\u259e'; // additional block elements
+      '\\u2590\\u258c\\u2588\\u2584\\u2580\\u259a\\u259e' + // additional block elements
+      '\\u2b21\\u2b22'; // hex-hollow ⬡ and hex-filled ⬢ (Cursor "Generating" spinner)
     const spinnerRe = new RegExp(`[${SPINNER}]`, 'gu');
     const spinnerClassRe = new RegExp(`^[\\s${SPINNER}]*$`, 'u');
 
@@ -3227,6 +3254,9 @@ export class WorkflowRunner {
     // regardless of the specific word used (Thinking, Cascading, Flibbertigibbeting, etc.)
     const thinkingLineRe = new RegExp(`^[\\s${SPINNER}]*\\s*\\w[\\w\\s]*\\u2026\\s*$`, 'u');
     const cursorOnlyRe = /^[\s❯⎿›»◀▶←→↑↓⟨⟩⟪⟫·]+$/u;
+    // Cursor Agent TUI lines: generating animations, pasted text indicators, UI chrome
+    const cursorAgentRe =
+      /^(?:Cursor Agent|[\s⬡⬢]*Generating[.\s]|\[Pasted text|Auto-run all|Add a follow-up|ctrl\+c to stop|shift\+tab|Auto$|\/\s*commands|@\s*files|!\s*shell|follow-ups?\s|The user ha)/iu;
     const slashCommandRe = /^\/\w+\s*$/u;
     const mcpJsonKvRe =
       /^\s*"(?:type|method|params|result|id|jsonrpc|tool|name|arguments|content|role|metadata)"\s*:/u;
@@ -3270,6 +3300,7 @@ export class WorkflowRunner {
       if (uiHintRe.test(trimmed)) continue;
       if (thinkingLineRe.test(trimmed)) continue;
       if (cursorOnlyRe.test(trimmed)) continue;
+      if (cursorAgentRe.test(trimmed)) continue;
       if (slashCommandRe.test(trimmed)) continue;
       if (!meaningfulContentRe.test(trimmed)) continue;
 

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

@@ -176,7 +176,7 @@
     },
     "AgentCli": {
       "type": "string",
-      "enum": ["claude", "codex", "gemini", "aider", "goose", "opencode", "droid"]
+      "enum": ["claude", "codex", "gemini", "aider", "goose", "opencode", "droid", "cursor", "cursor-agent", "agent"]
     },
     "AgentConstraints": {
       "type": "object",

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

@@ -115,7 +115,7 @@ export interface AgentDefinition {
   preset?: AgentPreset;
 }
 
-export type AgentCli = 'claude' | 'codex' | 'gemini' | 'aider' | 'goose' | 'opencode' | 'droid';
+export type AgentCli = 'claude' | 'codex' | 'gemini' | 'aider' | 'goose' | 'opencode' | 'droid' | 'cursor' | 'cursor-agent' | 'agent';
 
 /** Resource and behavioral constraints for an agent. */
 export interface AgentConstraints {