feat(harness-driver): add lifecycle-aware SpawnedAgentHandle (#1050)

* ci(publish): publish @agent-relay/harnesses on release

@agent-relay/harnesses was set up as a public package (no private flag,
publishConfig.access public, versioned in lockstep) but was never wired
into the publish workflow, so it never reached npm. External SDK
consumers (e.g. relayflows) need it for the prebuilt PTY harnesses and
the definePtyHarness/createHuman author helpers.

Add a publish-harnesses job to the package=all path. It runs after
publish-packages — where its exact-version workspace deps
(@agent-relay/sdk, @agent-relay/harness-driver) land on the registry —
so an external `npm install @agent-relay/harnesses@<v>` can always
resolve its dependencies. Mirrors the existing provenance +
skip-if-exists publish pattern.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* ci(publish): gate release on publish-harnesses; trim changelog

Address PR review: publish-harnesses ran outside the release gate, so a
tag/release could be cut even if harness publishing failed.

- create-release now needs publish-harnesses and its `if` requires the
  job to not have failed. It tolerates `skipped` so package=main
  releases (where publish-harnesses does not run) are not blocked.
- summary job lists the harness publish result.
- Trim the changelog bullet to impact-first per the repo changelog rule.

Leaving the new job's actions on @v4 tags to match the rest of the
workflow (the repo uses tag refs throughout; SHA-pinning would be
inconsistent and is not the enforced policy here).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(harness-driver): add lifecycle-aware SpawnedAgentHandle

`spawnPty`/`spawnCli`/`spawnHeadless` now return a `SpawnedAgentHandle`
instead of a bare `SpawnAgentResult`. The handle is a structural superset
(still carries name/runtime/sessionId/pid) so existing callers are
unaffected, and it adds the promise-based lifecycle operations consumers
previously had to reconstruct from the raw broker event stream:

- waitForExit() -> { reason, code, signal }
- waitForIdle() -> { reason, idleSecs }
- exit / exitCode / exitSignal (synchronous view of a prior exit)
- release()

All operations are backed by the client's broker event stream and its
event history, so they are replay-correct: awaiting after the agent has
already exited resolves immediately from history rather than hanging.

Typechecks clean; harness-driver tests pass; dependents (harnesses, sdk)
unaffected.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(harness-driver): source waitForIdle from broker event stream

The client `eventBus` only carries call-site hook events; broker events
like `agentIdle` are never emitted onto it in direct-client usage, so
`addListener('agentIdle', ...)` never fired and `waitForIdle()` could
hang. Match the `agent_idle` BrokerEvent on the transport stream via
`onEvent` instead — consistent with how `waitForExit()` already works.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(harness-driver): ensure broker event stream is live in handle waits

`transport.onEvent()` only registers a listener; events arrive only once
the stream is connected. Call the idempotent `connectEvents()` at the
start of `waitForExit`/`waitForIdle` so they receive events even if the
consumer never connected the stream, instead of hanging until timeout.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: willwashburn

packages/harness-driver/src/agent-handle.ts

@@ -0,0 +1,160 @@
+/**
+ * Lifecycle-aware handle for a spawned agent.
+ *
+ * `HarnessDriverClient.spawnPty()` / `spawnCli()` / `spawnHeadless()` return one
+ * of these instead of a bare {@link SpawnAgentResult}. It is a structural
+ * superset of `SpawnAgentResult` (it still carries `name` / `runtime` /
+ * `sessionId` / `pid`), so existing callers are unaffected, and it adds the
+ * promise-based lifecycle operations consumers previously had to reconstruct
+ * from the raw broker event stream:
+ *
+ *   - `waitForExit()` — resolve when the agent exits, with `code` / `signal`.
+ *   - `waitForIdle()` — resolve on the next idle signal (or on exit).
+ *   - `exit` / `exitCode` / `exitSignal` — synchronous view of a prior exit.
+ *   - `release()` — release the agent via the broker.
+ *
+ * All operations are backed by the client's broker event stream and its event
+ * history, so they are replay-correct: calling `waitForExit()` after the agent
+ * has already exited resolves immediately from history rather than hanging.
+ */
+import type { HarnessDriverClient } from './client.js';
+import type { AgentRuntime, BrokerEvent } from './protocol.js';
+import type { SpawnAgentResult } from './types.js';
+
+export interface AgentExitInfo {
+  /** `'exited'` when the agent exited; `'timeout'` when the wait elapsed first. */
+  reason: 'exited' | 'timeout';
+  /** Process exit code, when the broker reported one. */
+  code?: number;
+  /** Terminating signal, when the agent was killed by one. */
+  signal?: string;
+}
+
+export interface AgentIdleInfo {
+  /** `'idle'` on an idle signal, `'exited'` if the agent exited first, `'timeout'` otherwise. */
+  reason: 'idle' | 'exited' | 'timeout';
+  /** Seconds the agent has been idle, when `reason === 'idle'`. */
+  idleSecs?: number;
+  /** Exit details, when `reason === 'exited'`. */
+  exit?: AgentExitInfo;
+}
+
+export class SpawnedAgentHandle implements SpawnAgentResult {
+  readonly name: string;
+  readonly runtime: AgentRuntime;
+  readonly sessionId?: string;
+  readonly pid?: number;
+
+  constructor(
+    result: SpawnAgentResult,
+    private readonly client: HarnessDriverClient
+  ) {
+    this.name = result.name;
+    this.runtime = result.runtime;
+    this.sessionId = result.sessionId;
+    this.pid = result.pid;
+  }
+
+  /** Exit info if the agent has already exited (from broker event history), else `undefined`. */
+  get exit(): AgentExitInfo | undefined {
+    const exited = this.client.getLastEvent('agent_exited', this.name);
+    if (exited && exited.kind === 'agent_exited') {
+      return { reason: 'exited', code: exited.code, signal: exited.signal };
+    }
+    const exit = this.client.getLastEvent('agent_exit', this.name);
+    if (exit && exit.kind === 'agent_exit') {
+      return { reason: 'exited' };
+    }
+    return undefined;
+  }
+
+  get exitCode(): number | undefined {
+    return this.exit?.code;
+  }
+
+  get exitSignal(): string | undefined {
+    return this.exit?.signal;
+  }
+
+  /**
+   * Resolve when the agent exits (with `code` / `signal` when the broker reports
+   * them), or with `{ reason: 'timeout' }` if `timeoutMs` elapses first. Replays
+   * a prior exit from broker history, so it is safe to call after the fact.
+   */
+  waitForExit(timeoutMs?: number): Promise<AgentExitInfo> {
+    // Ensure the broker event stream is live — `onEvent` only registers a
+    // listener; without an active connection no events ever arrive. Idempotent.
+    this.client.connectEvents();
+
+    const already = this.exit;
+    if (already) return Promise.resolve(already);
+
+    return new Promise<AgentExitInfo>((resolve) => {
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const settle = (info: AgentExitInfo) => {
+        if (timer) clearTimeout(timer);
+        unsub();
+        resolve(info);
+      };
+      const unsub = this.client.onEvent((event: BrokerEvent) => {
+        const exit = matchExit(event, this.name);
+        if (exit) settle(exit);
+      });
+      if (timeoutMs !== undefined) {
+        timer = setTimeout(() => settle({ reason: 'timeout' }), timeoutMs);
+      }
+    });
+  }
+
+  /**
+   * Resolve on the next idle signal for this agent (edge-triggered: a fresh
+   * signal after the call, matching how runners poll-then-nudge). Also resolves
+   * if the agent exits first, or with `{ reason: 'timeout' }` after `timeoutMs`.
+   */
+  waitForIdle(timeoutMs?: number): Promise<AgentIdleInfo> {
+    // Ensure the broker event stream is live (see waitForExit). Idempotent.
+    this.client.connectEvents();
+
+    const already = this.exit;
+    if (already) return Promise.resolve({ reason: 'exited', exit: already });
+
+    return new Promise<AgentIdleInfo>((resolve) => {
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const settle = (info: AgentIdleInfo) => {
+        if (timer) clearTimeout(timer);
+        unsub();
+        resolve(info);
+      };
+      // Idle and exit both arrive on the broker event stream. The named
+      // `agentIdle` event bus is only populated by call-site hooks (not broker
+      // events) in direct-client usage, so it must not be used here.
+      const unsub = this.client.onEvent((event: BrokerEvent) => {
+        if (event.kind === 'agent_idle' && event.name === this.name) {
+          settle({ reason: 'idle', idleSecs: event.idle_secs });
+          return;
+        }
+        const exit = matchExit(event, this.name);
+        if (exit) settle({ reason: 'exited', exit });
+      });
+      if (timeoutMs !== undefined) {
+        timer = setTimeout(() => settle({ reason: 'timeout' }), timeoutMs);
+      }
+    });
+  }
+
+  /** Release the agent via the broker. */
+  release(reason?: string): Promise<{ name: string }> {
+    return this.client.release(this.name, reason);
+  }
+}
+
+/** Match an exit `BrokerEvent` for `name`, normalising the two exit kinds. */
+function matchExit(event: BrokerEvent, name: string): AgentExitInfo | undefined {
+  if (event.kind === 'agent_exited' && event.name === name) {
+    return { reason: 'exited', code: event.code, signal: event.signal };
+  }
+  if (event.kind === 'agent_exit' && event.name === name) {
+    return { reason: 'exited' };
+  }
+  return undefined;
+}

packages/harness-driver/src/client.ts

@@ -43,6 +43,7 @@ import type {
   ListAgent,
 } from './types.js';
 import { EventBus } from './event-bus.js';
+import { SpawnedAgentHandle } from './agent-handle.js';
 import type {
   AfterAgentReleaseContext,
   AfterAgentSpawnContext,
@@ -621,7 +622,7 @@ export class HarnessDriverClient {
 
   // ── Agent lifecycle ────────────────────────────────────────────────
 
-  async spawnPty(input: SpawnPtyInput): Promise<SpawnAgentResult> {
+  async spawnPty(input: SpawnPtyInput): Promise<SpawnedAgentHandle> {
     const beforeCtx: BeforeAgentSpawnContext<SpawnPtyInput> = {
       kind: 'pty',
       input,
@@ -638,14 +639,14 @@ export class HarnessDriverClient {
       });
       const result = SpawnAgentResultSchema.parse(rawResult);
       await this.emitAfterSpawn(beforeCtx, resolvedInput, t0, result, undefined);
-      return result;
+      return new SpawnedAgentHandle(result, this);
     } catch (err) {
       await this.emitAfterSpawn(beforeCtx, resolvedInput, t0, undefined, err);
       throw err;
     }
   }
 
-  async spawnCli(input: SpawnCliInput): Promise<SpawnAgentResult> {
+  async spawnCli(input: SpawnCliInput): Promise<SpawnedAgentHandle> {
     const beforeCtx: BeforeAgentSpawnContext<SpawnCliInput> = {
       kind: 'cli',
       input,
@@ -659,7 +660,7 @@ export class HarnessDriverClient {
   private async spawnCliWithContext(
     beforeCtx: BeforeAgentSpawnContext<SpawnCliInput>,
     input: SpawnCliInput
-  ): Promise<SpawnAgentResult> {
+  ): Promise<SpawnedAgentHandle> {
     const t0 = Date.now();
     const resolvedInput = await this.runBeforeSpawn(beforeCtx);
     const transport = resolveSpawnTransport(resolvedInput);
@@ -680,14 +681,14 @@ export class HarnessDriverClient {
       });
       const result = SpawnAgentResultSchema.parse(rawResult);
       await this.emitAfterSpawn(beforeCtx, resolvedInput, t0, result, undefined);
-      return result;
+      return new SpawnedAgentHandle(result, this);
     } catch (err) {
       await this.emitAfterSpawn(beforeCtx, resolvedInput, t0, undefined, err);
       throw err;
     }
   }
 
-  async spawnHeadless(input: SpawnHeadlessInput): Promise<SpawnAgentResult> {
+  async spawnHeadless(input: SpawnHeadlessInput): Promise<SpawnedAgentHandle> {
     const cliInput: SpawnCliInput = { ...input, transport: 'headless' };
     const beforeCtx: BeforeAgentSpawnContext<SpawnCliInput> = {
       kind: 'headless',
@@ -699,11 +700,11 @@ export class HarnessDriverClient {
     return this.spawnCliWithContext(beforeCtx, cliInput);
   }
 
-  async spawnClaude(input: Omit<SpawnCliInput, 'cli'>): Promise<SpawnAgentResult> {
+  async spawnClaude(input: Omit<SpawnCliInput, 'cli'>): Promise<SpawnedAgentHandle> {
     return this.spawnCli({ ...input, cli: 'claude' });
   }
 
-  async spawnOpencode(input: Omit<SpawnCliInput, 'cli'>): Promise<SpawnAgentResult> {
+  async spawnOpencode(input: Omit<SpawnCliInput, 'cli'>): Promise<SpawnedAgentHandle> {
     return this.spawnCli({ ...input, cli: 'opencode' });
   }
 

packages/harness-driver/src/index.ts

@@ -1,4 +1,5 @@
 export * from './driver-types.js';
+export * from './agent-handle.js';
 export * from './broker-driver.js';
 export * from './actions.js';
 export * from './client.js';