@autonome-research/thread-phase 3.0.0

package/dist/agents/memory.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Pluggable cross-run memory.
+ *
+ * thread-phase ships no implementations; callers wire one in via
+ * `AgentRunOptions.memoryProvider`. The interface intentionally maps to
+ * the lowest common denominator across backends like Honcho, Letta, and
+ * Mem0 — `recall` returns a string (the backend's distilled summary or
+ * raw recall blob), and `remember` ingests an event window from the run
+ * that just completed.
+ *
+ * @internal
+ */
+import type { AgentEvent } from './protocol.js';
+/**
+ * Scope key for a memory provider. `userId` is the partition every
+ * backend expects; `appId` and `sessionId` narrow further when supported.
+ *
+ * @internal
+ */
+export interface MemoryScope {
+    userId: string;
+    appId?: string;
+    sessionId?: string;
+}
+/**
+ * The provider contract.
+ *
+ * Note: implementations are not required to provide read-your-writes
+ * consistency. A `remember()` immediately followed by a `recall()` may
+ * not see the new content if the backend does async indexing (Honcho's
+ * derivers, for example). Callers that need strict ordering should
+ * persist their own representation alongside the provider.
+ *
+ * @internal
+ */
+export interface MemoryProvider {
+    recall(scope: MemoryScope, query?: string): Promise<string>;
+    remember(scope: MemoryScope, events: ReadonlyArray<AgentEvent>): Promise<void>;
+}
+//# sourceMappingURL=memory.d.ts.map

package/dist/agents/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/agents/memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,KAAK,EAAE,WAAW,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5D,QAAQ,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChF"}

package/dist/agents/memory.js

@@ -0,0 +1,14 @@
+/**
+ * Pluggable cross-run memory.
+ *
+ * thread-phase ships no implementations; callers wire one in via
+ * `AgentRunOptions.memoryProvider`. The interface intentionally maps to
+ * the lowest common denominator across backends like Honcho, Letta, and
+ * Mem0 — `recall` returns a string (the backend's distilled summary or
+ * raw recall blob), and `remember` ingests an event window from the run
+ * that just completed.
+ *
+ * @internal
+ */
+export {};
+//# sourceMappingURL=memory.js.map

package/dist/agents/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../../src/agents/memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/agents/protocol.d.ts

@@ -0,0 +1,302 @@
+/**
+ * AgentAdapter protocol — the type surface every adapter speaks.
+ *
+ * Adapters wrap heterogeneous coding-agent runtimes (the in-tree inference
+ * loop, pi, Claude Code, OpenAI Agents SDK, ...) behind a single shape so
+ * thread-phase patterns can compose them uniformly. The protocol is types
+ * and pure utilities; runtime adapters live in sibling packages.
+ *
+ * @internal — surface is in development and not covered by semver until
+ * AgentAdapter v1 ships. See `potential_feature.md` for the design spec.
+ */
+import type { ActivityEntry, FinishReason, UsageInfo } from '../agent/types.js';
+import type { ToolCall } from '../messages.js';
+import type { MemoryProvider, MemoryScope } from './memory.js';
+export type { MemoryProvider, MemoryScope } from './memory.js';
+/**
+ * Hint an adapter can persist to resume a conversation in a later run.
+ *
+ * - `response-id` matches OpenAI's `previous_response_id` continuation.
+ * - `session-file` is the on-disk transcript used by pi and Claude Code.
+ * - `opaque` is the fallback for adapters with proprietary continuation state.
+ *
+ * @internal
+ */
+export type ResumeToken = {
+    kind: 'response-id';
+    id: string;
+    provider: string;
+} | {
+    kind: 'session-file';
+    path: string;
+    messageIndex?: number;
+} | {
+    kind: 'opaque';
+    data: string;
+};
+/**
+ * Cross-process-friendly error shape. Subprocess adapters can only surface
+ * serialized errors anyway, so making it uniform avoids a footgun where
+ * callers conditionally have raw `Error` instances vs. plain objects.
+ *
+ * @internal
+ */
+export interface SerializableError {
+    name: string;
+    message: string;
+    stack?: string;
+    cause?: SerializableError;
+}
+/**
+ * Canonical event vocabulary. Every adapter translates its native event
+ * stream into this discriminated union. The `native` variant is the escape
+ * hatch for adapter-specific signals (pi compaction, OpenAI handoffs, etc.) —
+ * consumers filter by `source` to handle them safely.
+ *
+ * Ordering invariant: `agent_start` is the first non-`native` event,
+ * `agent_end` the last; exactly one of each per run.
+ *
+ * The `thinking` variant is for adapters that surface reasoning content
+ * separately from final text (Anthropic extended thinking, OpenAI Responses
+ * reasoning items, pi inner monologue). The in-tree `inferenceAgent` never
+ * emits it; OpenAI-compatible chat-completions has no reasoning channel.
+ *
+ * The `error.transient` flag distinguishes recoverable failures (rate limits,
+ * upstream 5xx, intermittent network) from terminal ones (invalid auth,
+ * malformed request, schema violation). Adapter authors set `true` only when
+ * a sensible retry policy could succeed without user intervention.
+ *
+ * @internal
+ */
+export type AgentEvent = {
+    type: 'agent_start';
+    source: string;
+    traceId?: string;
+    resumeToken?: ResumeToken;
+} | {
+    type: 'text';
+    source: string;
+    traceId?: string;
+    delta: string;
+} | {
+    type: 'thinking';
+    source: string;
+    traceId?: string;
+    delta: string;
+} | {
+    type: 'tool_call';
+    source: string;
+    traceId?: string;
+    id: string;
+    name: string;
+    input: unknown;
+} | {
+    type: 'tool_result';
+    source: string;
+    traceId?: string;
+    id: string;
+    name: string;
+    output: unknown;
+    isError: boolean;
+} | {
+    type: 'turn_end';
+    source: string;
+    traceId?: string;
+    assistantText: string;
+    usage?: UsageInfo;
+    toolCallCount: number;
+} | {
+    type: 'agent_end';
+    source: string;
+    traceId?: string;
+    reason: AgentFinishReason;
+    resumeToken?: ResumeToken;
+} | {
+    type: 'error';
+    source: string;
+    traceId?: string;
+    error: SerializableError;
+    transient: boolean;
+} | {
+    type: 'native';
+    source: string;
+    traceId?: string;
+    kind: string;
+    payload: unknown;
+};
+/**
+ * Adapter finish reasons. Extends the existing runner `FinishReason` with
+ * `'aborted'` so cancellation has a first-class encoding instead of being
+ * folded into `'error'`.
+ *
+ * @internal
+ */
+export type AgentFinishReason = FinishReason | 'aborted';
+/**
+ * Adapter run result. Structural superset of the runner `AgentRunResult`:
+ * the runner's required fields appear here with the same shapes, and adapter
+ * additions (`activity`, `parsed`, `resumeToken`, `messages`) are optional so
+ * non-runner adapters can omit fields they don't naturally produce.
+ *
+ * The runner's `AgentRunResult` is assignable to this type without change
+ * (required → optional is widening); adapters that don't emit activity entries
+ * simply leave the field undefined.
+ *
+ * @internal
+ */
+export interface AgentRunResult {
+    /** Final text output. May be JSON; callers parseJSON or parseStructured. */
+    text: string;
+    /** Reason the agent stopped, widened with `'aborted'`. */
+    finishReason: AgentFinishReason;
+    /** Token usage summed across rounds. */
+    usage: UsageInfo;
+    /** Every tool call the adapter actually executed, in order. */
+    executedToolCalls: ToolCall[];
+    /** Adapter-native activity log; optional because not every adapter produces one. */
+    activity?: ReadonlyArray<ActivityEntry>;
+    /** Populated when the adapter was given an `outputSchema` and parsing succeeded. */
+    parsed?: unknown;
+    /**
+     * Populated when the adapter was given an `outputSchema` and parsing
+     * FAILED. Mutually exclusive with `parsed` — at most one is set. Callers
+     * detect parse failure via `parsed === undefined && parseError !== undefined`
+     * and decide whether to retry (typically via `followUp()` on a
+     * `SteerableAgentRun`). Parse failures are NOT emitted as `error` events
+     * because the agent did its job — the output simply didn't match the schema.
+     */
+    parseError?: SerializableError;
+    /** Adapter-produced continuation hint, persisted for a later run. */
+    resumeToken?: ResumeToken;
+    /**
+     * Adapter-native message log when available. Typed loosely because each
+     * adapter preserves a different fidelity (Claude Code content arrays,
+     * OpenAI reasoning items, etc.); consumers that need typed access
+     * deserialize per `source`.
+     */
+    messages?: ReadonlyArray<unknown>;
+}
+/**
+ * Static introspection over adapter abilities. Patterns and the JobRunner
+ * call `requireCapability` against this at construction time so pipelines
+ * fail fast before any LLM tokens are spent.
+ *
+ * @internal
+ */
+export interface AgentCapabilities {
+    streaming: 'text' | 'turns' | 'final-only';
+    cancellation: 'cooperative' | 'forceful' | 'none';
+    resumption: 'response-id' | 'session-file' | 'opaque' | 'none';
+    structuredOutput: 'native' | 'prompted' | 'none';
+}
+/**
+ * Cross-cutting event sink. Orchestrators (JobRunner, audit consumers)
+ * create one bus and pass it to every adapter under their scope to observe
+ * heterogeneous adapter events through a single seam.
+ *
+ * Distinct from `AgentRun.events`, which is a single-consumer stream owned
+ * by the caller of an individual adapter run. The bus is the multi-subscriber
+ * fan-out; the run's events iterable is consumed once.
+ *
+ * @internal
+ */
+export interface AgentEventBus {
+    emit(event: AgentEvent): void;
+    on(handler: (event: AgentEvent) => void | Promise<void>): () => void;
+}
+/**
+ * Options passed to every adapter invocation. All fields are optional;
+ * adapters ignore the ones they can't honor (after declaring so via
+ * `AgentCapabilities`).
+ *
+ * @internal
+ */
+export interface AgentRunOptions {
+    signal?: AbortSignal;
+    eventBus?: AgentEventBus;
+    traceId?: string;
+    memoryProvider?: MemoryProvider;
+    memoryScope?: MemoryScope;
+}
+/**
+ * Handle for a single adapter invocation.
+ *
+ * Lifecycle invariants:
+ * - `events` is a single-consumer `AsyncIterable`; iterate it once. Use
+ *   `AgentEventBus` for multi-subscriber fan-out.
+ * - `result` always resolves, never rejects. Errors are encoded as
+ *   `finishReason: 'error'` with a prior `error` event.
+ * - `abort()` is idempotent.
+ *
+ * @internal
+ */
+export interface AgentRun<TResult extends AgentRunResult = AgentRunResult> {
+    readonly events: AsyncIterable<AgentEvent>;
+    readonly result: Promise<TResult>;
+    abort(reason?: string): void;
+}
+/**
+ * Subtype for adapters that support mid-stream steering or post-turn
+ * follow-up. Sibling packages (the `@autonome-research/thread-phase-agents` extension surface)
+ * return this from adapters whose underlying runtime accepts these calls —
+ * e.g. ACP sessions, which can take multiple `session/prompt` requests
+ * before the session is closed.
+ *
+ * `AgentAdapter`'s declared return type stays `AgentRun` for variance
+ * (SteerableAgentRun is a subtype). Consumers narrow at the call site
+ * via `isSteerable(run)`.
+ *
+ * @internal
+ */
+export interface SteerableAgentRun<TResult extends AgentRunResult = AgentRunResult> extends AgentRun<TResult> {
+    /**
+     * Send a steering message mid-stream — only meaningful for runtimes
+     * that accept in-flight input (currently none in the bundled adapter
+     * set; ACP-based adapters reject with a clear capability error).
+     */
+    steer(message: string): Promise<void>;
+    /**
+     * Queue an additional prompt to send after the current prompt response
+     * completes. Multiple follow-ups can stack; the chassis drains the
+     * queue between turns. Throws after the run has reached `agent_end`.
+     */
+    followUp(message: string): Promise<void>;
+}
+/**
+ * Type guard for `SteerableAgentRun`. Use at consumer call sites to
+ * safely narrow an `AgentRun` returned by an adapter that may or may
+ * not be steerable:
+ *
+ *     const run = hermesAgent.adapter(...);
+ *     if (isSteerable(run)) await run.followUp('also do X');
+ *
+ * @internal
+ */
+export declare function isSteerable<TResult extends AgentRunResult>(run: AgentRun<TResult>): run is SteerableAgentRun<TResult>;
+/**
+ * The adapter signature. Must return synchronously — the run starts lazily
+ * when either `events` is iterated or `result` is awaited.
+ *
+ * @internal
+ */
+export type AgentAdapter<TConfig, TResult extends AgentRunResult = AgentRunResult> = (config: TConfig, options?: AgentRunOptions) => AgentRun<TResult>;
+/**
+ * Adapter registration metadata. Bundles a stable `id` (used as `source` on
+ * every emitted event), a declared `capabilities` descriptor, and the
+ * adapter function itself.
+ *
+ * @internal
+ */
+export interface AgentAdapterMeta<TConfig, TResult extends AgentRunResult = AgentRunResult> {
+    readonly id: string;
+    readonly capabilities: AgentCapabilities;
+    readonly adapter: AgentAdapter<TConfig, TResult>;
+}
+/**
+ * Identity at runtime; exists for inference and as a hook for future
+ * telemetry. Modeled on Vitest's `defineConfig`.
+ *
+ * @internal
+ */
+export declare function defineAgentAdapter<TConfig, TResult extends AgentRunResult = AgentRunResult>(meta: AgentAdapterMeta<TConfig, TResult>): AgentAdapterMeta<TConfig, TResult>;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/agents/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/agents/protocol.ts"],"names":[],"mappings":"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"}

package/dist/agents/protocol.js

@@ -0,0 +1,36 @@
+/**
+ * AgentAdapter protocol — the type surface every adapter speaks.
+ *
+ * Adapters wrap heterogeneous coding-agent runtimes (the in-tree inference
+ * loop, pi, Claude Code, OpenAI Agents SDK, ...) behind a single shape so
+ * thread-phase patterns can compose them uniformly. The protocol is types
+ * and pure utilities; runtime adapters live in sibling packages.
+ *
+ * @internal — surface is in development and not covered by semver until
+ * AgentAdapter v1 ships. See `potential_feature.md` for the design spec.
+ */
+/**
+ * Type guard for `SteerableAgentRun`. Use at consumer call sites to
+ * safely narrow an `AgentRun` returned by an adapter that may or may
+ * not be steerable:
+ *
+ *     const run = hermesAgent.adapter(...);
+ *     if (isSteerable(run)) await run.followUp('also do X');
+ *
+ * @internal
+ */
+export function isSteerable(run) {
+    const candidate = run;
+    return (typeof candidate.followUp === 'function' &&
+        typeof candidate.steer === 'function');
+}
+/**
+ * Identity at runtime; exists for inference and as a hook for future
+ * telemetry. Modeled on Vitest's `defineConfig`.
+ *
+ * @internal
+ */
+export function defineAgentAdapter(meta) {
+    return meta;
+}
+//# sourceMappingURL=protocol.js.map

package/dist/agents/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/agents/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAsPH;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CACzB,GAAsB;IAEtB,MAAM,SAAS,GAAG,GAA0C,CAAC;IAC7D,OAAO,CACL,OAAO,SAAS,CAAC,QAAQ,KAAK,UAAU;QACxC,OAAO,SAAS,CAAC,KAAK,KAAK,UAAU,CACtC,CAAC;AACJ,CAAC;AA0BD;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAChC,IAAwC;IAExC,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/agents/run-helpers.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Helpers for adapter authors.
+ *
+ * Every `AgentAdapter` does the same three things at construction:
+ *   1. Compose its abort signal — options.signal plus an internal controller
+ *      driven by the returned `abort()` method.
+ *   2. Set up a queue-backed `AsyncIterable<AgentEvent>` with a producer
+ *      that doesn't block and a consumer that's single-shot (multi-cast
+ *      goes through `AgentEventBus`).
+ *   3. Defer the actual work to a lazy `runOnce()` that starts when either
+ *      `events` is iterated or `result` is awaited, whichever comes first.
+ *
+ * These helpers capture those patterns so per-adapter code only describes
+ * the translation between its underlying runtime and canonical
+ * `AgentEvent`s. The patterns themselves stay invariant.
+ *
+ * @internal
+ */
+import type { AgentEvent, AgentEventBus } from './protocol.js';
+/** @internal */
+export interface CompositeAbort {
+    /** Signal an adapter passes down to its underlying runtime. Aborts when EITHER input does. */
+    readonly signal: AbortSignal;
+    /** The internal controller driven by the adapter's `abort()` method. */
+    readonly controller: AbortController;
+}
+/**
+ * Compose an optional external `AbortSignal` (from `AgentRunOptions.signal`)
+ * with an internal controller into a single signal. Uses `AbortSignal.any`
+ * (Node 20+), so there's no manual listener that would pin a closure if
+ * the external signal outlives the run.
+ *
+ * @internal
+ */
+export declare function composeAbort(external?: AbortSignal): CompositeAbort;
+/** @internal */
+export interface EventQueue {
+    /** Producer — emit an event. Mirrors to the bus if one was supplied. Non-blocking. */
+    push(event: AgentEvent): void;
+    /** Mark the stream complete. Drains parked waiters with `done: true`. Idempotent. */
+    close(): void;
+    /** Whether `close()` has been called. */
+    isClosed(): boolean;
+    /** The consumer-side iterable. Single-shot — vending twice throws. */
+    readonly events: AsyncIterable<AgentEvent>;
+}
+/**
+ * Single-producer / single-consumer queue with optional `AgentEventBus`
+ * mirroring. The producer never blocks; events queue when no consumer is
+ * waiting. The consumer is single-shot — vending the iterator twice
+ * throws (use `AgentEventBus` for multi-subscriber fan-out).
+ *
+ * Bus errors are swallowed: the producer must never fail because of a
+ * misbehaving subscriber. Bus implementations are responsible for
+ * containing their own handler errors.
+ *
+ * @internal
+ */
+export declare function createEventQueue(bus?: AgentEventBus): EventQueue;
+/**
+ * Wrap an inner iterable so that iterating it triggers a lazy-start
+ * callback. Adapter `events` property uses this to ensure that iterating
+ * events alone (without awaiting `result`) still kicks off the run —
+ * otherwise the iterator would park a waiter on an empty queue with no
+ * producer, deadlocking.
+ *
+ * @internal
+ */
+export declare function lazyEvents(inner: AsyncIterable<AgentEvent>, start: () => void): AsyncIterable<AgentEvent>;
+//# sourceMappingURL=run-helpers.d.ts.map

package/dist/agents/run-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-helpers.d.ts","sourceRoot":"","sources":["../../src/agents/run-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAM/D,gBAAgB;AAChB,MAAM,WAAW,cAAc;IAC7B,8FAA8F;IAC9F,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,wEAAwE;IACxE,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;CACtC;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,QAAQ,CAAC,EAAE,WAAW,GAAG,cAAc,CAMnE;AAMD,gBAAgB;AAChB,MAAM,WAAW,UAAU;IACzB,sFAAsF;IACtF,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IAC9B,qFAAqF;IACrF,KAAK,IAAI,IAAI,CAAC;IACd,yCAAyC;IACzC,QAAQ,IAAI,OAAO,CAAC;IACpB,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;CAC5C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,CAAC,EAAE,aAAa,GAAG,UAAU,CAkEhE;AAMD;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,aAAa,CAAC,UAAU,CAAC,EAChC,KAAK,EAAE,MAAM,IAAI,GAChB,aAAa,CAAC,UAAU,CAAC,CAO3B"}

package/dist/agents/run-helpers.js

@@ -0,0 +1,131 @@
+/**
+ * Helpers for adapter authors.
+ *
+ * Every `AgentAdapter` does the same three things at construction:
+ *   1. Compose its abort signal — options.signal plus an internal controller
+ *      driven by the returned `abort()` method.
+ *   2. Set up a queue-backed `AsyncIterable<AgentEvent>` with a producer
+ *      that doesn't block and a consumer that's single-shot (multi-cast
+ *      goes through `AgentEventBus`).
+ *   3. Defer the actual work to a lazy `runOnce()` that starts when either
+ *      `events` is iterated or `result` is awaited, whichever comes first.
+ *
+ * These helpers capture those patterns so per-adapter code only describes
+ * the translation between its underlying runtime and canonical
+ * `AgentEvent`s. The patterns themselves stay invariant.
+ *
+ * @internal
+ */
+/**
+ * Compose an optional external `AbortSignal` (from `AgentRunOptions.signal`)
+ * with an internal controller into a single signal. Uses `AbortSignal.any`
+ * (Node 20+), so there's no manual listener that would pin a closure if
+ * the external signal outlives the run.
+ *
+ * @internal
+ */
+export function composeAbort(external) {
+    const controller = new AbortController();
+    const signal = external
+        ? AbortSignal.any([external, controller.signal])
+        : controller.signal;
+    return { signal, controller };
+}
+/**
+ * Single-producer / single-consumer queue with optional `AgentEventBus`
+ * mirroring. The producer never blocks; events queue when no consumer is
+ * waiting. The consumer is single-shot — vending the iterator twice
+ * throws (use `AgentEventBus` for multi-subscriber fan-out).
+ *
+ * Bus errors are swallowed: the producer must never fail because of a
+ * misbehaving subscriber. Bus implementations are responsible for
+ * containing their own handler errors.
+ *
+ * @internal
+ */
+export function createEventQueue(bus) {
+    const queued = [];
+    const waiters = [];
+    let closed = false;
+    let iteratorVended = false;
+    const push = (event) => {
+        if (closed)
+            return;
+        if (bus) {
+            try {
+                bus.emit(event);
+            }
+            catch {
+                // bus implementation handles its own subscriber errors
+            }
+        }
+        const next = waiters.shift();
+        if (next) {
+            next({ value: event, done: false });
+        }
+        else {
+            queued.push(event);
+        }
+    };
+    const close = () => {
+        if (closed)
+            return;
+        closed = true;
+        while (waiters.length > 0) {
+            const w = waiters.shift();
+            w({ value: undefined, done: true });
+        }
+    };
+    const events = {
+        [Symbol.asyncIterator]() {
+            if (iteratorVended) {
+                throw new Error('AgentRun.events is single-consumer; iterate it once. Use AgentEventBus (options.eventBus) for multi-subscriber fan-out.');
+            }
+            iteratorVended = true;
+            return {
+                next() {
+                    if (queued.length > 0) {
+                        return Promise.resolve({ value: queued.shift(), done: false });
+                    }
+                    if (closed) {
+                        return Promise.resolve({ value: undefined, done: true });
+                    }
+                    return new Promise((resolve) => {
+                        waiters.push(resolve);
+                    });
+                },
+                return() {
+                    close();
+                    return Promise.resolve({ value: undefined, done: true });
+                },
+            };
+        },
+    };
+    return {
+        push,
+        close,
+        isClosed: () => closed,
+        events,
+    };
+}
+// ---------------------------------------------------------------------------
+// lazyEvents
+// ---------------------------------------------------------------------------
+/**
+ * Wrap an inner iterable so that iterating it triggers a lazy-start
+ * callback. Adapter `events` property uses this to ensure that iterating
+ * events alone (without awaiting `result`) still kicks off the run —
+ * otherwise the iterator would park a waiter on an empty queue with no
+ * producer, deadlocking.
+ *
+ * @internal
+ */
+export function lazyEvents(inner, start) {
+    return {
+        [Symbol.asyncIterator]() {
+            start();
+            return inner[Symbol.asyncIterator]();
+        },
+    };
+}
+//# sourceMappingURL=run-helpers.js.map

package/dist/agents/run-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-helpers.js","sourceRoot":"","sources":["../../src/agents/run-helpers.ts"],"names":[],"mappings":"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"}

package/dist/agents/serialize-error.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Convert a thrown value into the wire-friendly `SerializableError` shape
+ * that adapters emit on `error` events. Walks the `cause` chain so wrapped
+ * errors don't lose context across the subprocess boundary.
+ *
+ * @internal
+ */
+import type { SerializableError } from './protocol.js';
+/**
+ * Normalize any thrown value to a `SerializableError`. Non-`Error` throws
+ * become `{ name: 'NonError', message: String(err) }` so the field shape
+ * stays uniform — consumers can rely on `name` and `message` always being
+ * present.
+ *
+ * @internal
+ */
+export declare function serializeError(err: unknown): SerializableError;
+//# sourceMappingURL=serialize-error.d.ts.map

package/dist/agents/serialize-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize-error.d.ts","sourceRoot":"","sources":["../../src/agents/serialize-error.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEvD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,iBAAiB,CAU9D"}