@autonome-research/thread-phase 3.0.0

package/dist/agents/test-utils/mock-agent.js

@@ -0,0 +1,244 @@
+/**
+ * Scripted `AgentAdapter` for tests.
+ *
+ * `createMockAgent` returns a `AgentAdapterMeta` whose adapter replays a
+ * configured sequence of `AgentEvent`s and resolves with a configured
+ * `AgentRunResult`. The mock honors the protocol's lifecycle invariants:
+ * exactly one `agent_start`, exactly one trailing `agent_end`, `result`
+ * always resolves, `abort()` is idempotent, `options.signal` is observed.
+ *
+ * Used by in-tree tests targeting the AgentAdapter surface and by the
+ * conformance suite as the self-test adapter.
+ *
+ * @internal
+ */
+import { defineAgentAdapter, } from '../protocol.js';
+/**
+ * Default capabilities used when none are overridden.
+ *
+ * @internal
+ */
+export const MOCK_DEFAULT_CAPABILITIES = {
+    streaming: 'text',
+    cancellation: 'cooperative',
+    resumption: 'none',
+    structuredOutput: 'none',
+};
+/**
+ * Build a mock adapter suitable for testing pattern code and any consumer
+ * targeting the AgentAdapter protocol.
+ *
+ * @internal
+ */
+export function createMockAgent(opts = {}) {
+    const id = opts.id ?? 'mock';
+    const capabilities = {
+        ...MOCK_DEFAULT_CAPABILITIES,
+        ...opts.capabilities,
+    };
+    return defineAgentAdapter({
+        id,
+        capabilities,
+        adapter: (config, options) => {
+            if (config.throwOnConstruct) {
+                throw config.throwOnConstruct;
+            }
+            const traceId = options?.traceId;
+            const bus = options?.eventBus;
+            const externalSignal = options?.signal;
+            const localController = new AbortController();
+            // AbortSignal.any (Node 20+) composes without manual listeners that
+            // would pin our closure if the external signal outlives the run.
+            const composite = externalSignal
+                ? AbortSignal.any([externalSignal, localController.signal])
+                : localController.signal;
+            const emit = (event) => {
+                if (bus)
+                    bus.emit(event);
+            };
+            // Single-producer queue feeding the AsyncIterable. We push every event
+            // (start, scripted, end) into `queue` and the iterator drains it.
+            const queue = [];
+            const waiters = [];
+            let producerDone = false;
+            const push = (event) => {
+                const waiter = waiters.shift();
+                if (waiter) {
+                    waiter({ value: event, done: false });
+                }
+                else {
+                    queue.push(event);
+                }
+            };
+            const finishIterator = () => {
+                producerDone = true;
+                while (waiters.length > 0) {
+                    const w = waiters.shift();
+                    w({ value: undefined, done: true });
+                }
+            };
+            let resolveResult;
+            const resultPromise = new Promise((resolve) => {
+                resolveResult = resolve;
+            });
+            const stamp = (event) => {
+                // Adapters set `source` to their id; preserve any traceId from options.
+                const next = { ...event, source: id };
+                if (traceId !== undefined && next.traceId === undefined) {
+                    next.traceId = traceId;
+                }
+                return next;
+            };
+            const run = async () => {
+                const start = stamp({ type: 'agent_start', source: id });
+                push(start);
+                emit(start);
+                let aborted = composite.aborted;
+                for (const raw of config.events) {
+                    if (composite.aborted) {
+                        aborted = true;
+                        break;
+                    }
+                    if (config.perEventDelayMs && config.perEventDelayMs > 0) {
+                        await delay(config.perEventDelayMs, composite);
+                    }
+                    else {
+                        // Microtask hop so consumers get a chance to interleave.
+                        await Promise.resolve();
+                    }
+                    if (composite.aborted) {
+                        aborted = true;
+                        break;
+                    }
+                    const ev = stamp(raw);
+                    push(ev);
+                    emit(ev);
+                }
+                const finishReason = aborted ? 'aborted' : config.result.finishReason;
+                const end = stamp({
+                    type: 'agent_end',
+                    source: id,
+                    reason: finishReason,
+                    resumeToken: config.result.resumeToken,
+                });
+                push(end);
+                emit(end);
+                finishIterator();
+                resolveResult(aborted ? { ...config.result, finishReason: 'aborted' } : config.result);
+            };
+            // Kick off lazily — start when either events is iterated or result
+            // is awaited. The protocol requires synchronous return, so we defer
+            // the loop to a microtask.
+            let started = false;
+            const start = () => {
+                if (started)
+                    return;
+                started = true;
+                // Detach from the caller's stack; errors here must not surface as
+                // a synchronous throw from `adapter()`. Any unexpected failure is
+                // funneled into an error event + finishReason: 'error'.
+                void run().catch((err) => {
+                    const errEvent = stamp({
+                        type: 'error',
+                        source: id,
+                        error: serializeMockError(err),
+                        transient: false,
+                    });
+                    push(errEvent);
+                    emit(errEvent);
+                    const end = stamp({
+                        type: 'agent_end',
+                        source: id,
+                        reason: 'error',
+                    });
+                    push(end);
+                    emit(end);
+                    finishIterator();
+                    resolveResult({ ...config.result, finishReason: 'error' });
+                });
+            };
+            // Single-consumer guard — matches inferenceAgent's behavior. A second
+            // iterator would silently split events between consumers.
+            let iteratorVended = false;
+            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;
+                    start();
+                    return {
+                        next() {
+                            if (queue.length > 0) {
+                                const value = queue.shift();
+                                return Promise.resolve({ value, done: false });
+                            }
+                            if (producerDone) {
+                                return Promise.resolve({ value: undefined, done: true });
+                            }
+                            return new Promise((resolve) => {
+                                waiters.push(resolve);
+                            });
+                        },
+                        return() {
+                            // Early termination — cancel and drain.
+                            localController.abort();
+                            finishIterator();
+                            return Promise.resolve({ value: undefined, done: true });
+                        },
+                    };
+                },
+            };
+            const result = {
+                then(onFulfilled, onRejected) {
+                    start();
+                    return resultPromise.then(onFulfilled, onRejected);
+                },
+                catch(onRejected) {
+                    start();
+                    return resultPromise.catch(onRejected);
+                },
+                finally(onFinally) {
+                    start();
+                    return resultPromise.finally(onFinally);
+                },
+                [Symbol.toStringTag]: 'Promise',
+            };
+            return {
+                events,
+                result,
+                abort(_reason) {
+                    // Idempotent — AbortController.abort is itself idempotent.
+                    localController.abort();
+                },
+            };
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+function delay(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted) {
+            resolve();
+            return;
+        }
+        const t = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(t);
+            resolve();
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+function serializeMockError(err) {
+    if (err instanceof Error) {
+        return { name: err.name, message: err.message, stack: err.stack };
+    }
+    return { name: 'NonError', message: String(err) };
+}
+//# sourceMappingURL=mock-agent.js.map

package/dist/agents/test-utils/mock-agent.js.map

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

package/dist/agents/thread.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Thread — the conversational object that flows through pipeline phases.
+ *
+ * The canonical `AgentEvent` log is the source of truth; `resumeTokens`
+ * point at adapter-native continuation state held externally by each
+ * adapter (session files on disk, response ids in a vendor's store). When
+ * the next phase happens to use the same adapter, it passes the matching
+ * resume token and continues natively. When the next phase is a different
+ * adapter, it renders the canonical events into a permissive message log
+ * via `threadToMessages` and starts a fresh session.
+ *
+ * @internal
+ */
+import type { AgentEvent, ResumeToken } from './protocol.js';
+import type { Message } from '../messages.js';
+/**
+ * Conversational state across phases.
+ *
+ * - `events`: append-only canonical log. Survives cross-adapter handoffs.
+ * - `resumeTokens`: per-adapter (keyed by `AgentAdapterMeta.id`) pointers
+ *   to adapter-native state. Adapters set their own token, never another
+ *   adapter's.
+ *
+ * @internal
+ */
+export interface Thread {
+    events: AgentEvent[];
+    resumeTokens: Record<string, ResumeToken>;
+}
+/** @internal */
+export declare function createThread(): Thread;
+/** @internal */
+export declare function appendEvent(thread: Thread, event: AgentEvent): void;
+/** @internal */
+export declare function resumeTokenFor(thread: Thread, adapterId: string): ResumeToken | undefined;
+/** @internal */
+export declare function setResumeToken(thread: Thread, adapterId: string, token: ResumeToken): void;
+/**
+ * Render canonical events into thread-phase's internal `Message[]` for
+ * cross-adapter handoff when no per-adapter resume token is available.
+ *
+ * Lossy by design:
+ * - `native` events are skipped — they have no canonical message equivalent.
+ * - `tool_result.output` is coerced to a string. Adapters that need the
+ *   native shape should consume the canonical event log directly.
+ * - `error` and `agent_start`/`agent_end` events do not produce messages;
+ *   they are run-lifecycle signals, not conversation content.
+ * - Multiple assistant turns within one run become one assistant message
+ *   per turn boundary (`turn_end`); a trailing text run without a
+ *   `turn_end` is flushed at `agent_end`.
+ *
+ * Treat the output as conversation history, not as an authoritative log.
+ *
+ * @internal
+ */
+export declare function threadToMessages(thread: Thread): Message[];
+//# sourceMappingURL=thread.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"thread.d.ts","sourceRoot":"","sources":["../../src/agents/thread.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,KAAK,EAAE,OAAO,EAAY,MAAM,gBAAgB,CAAC;AAExD;;;;;;;;;GASG;AACH,MAAM,WAAW,MAAM;IACrB,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;CAC3C;AAED,gBAAgB;AAChB,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,gBAAgB;AAChB,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI,CAEnE;AAED,gBAAgB;AAChB,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAEzF;AAED,gBAAgB;AAChB,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,CAE1F;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,EAAE,CAmE1D"}

package/dist/agents/thread.js

@@ -0,0 +1,128 @@
+/**
+ * Thread — the conversational object that flows through pipeline phases.
+ *
+ * The canonical `AgentEvent` log is the source of truth; `resumeTokens`
+ * point at adapter-native continuation state held externally by each
+ * adapter (session files on disk, response ids in a vendor's store). When
+ * the next phase happens to use the same adapter, it passes the matching
+ * resume token and continues natively. When the next phase is a different
+ * adapter, it renders the canonical events into a permissive message log
+ * via `threadToMessages` and starts a fresh session.
+ *
+ * @internal
+ */
+/** @internal */
+export function createThread() {
+    return { events: [], resumeTokens: {} };
+}
+/** @internal */
+export function appendEvent(thread, event) {
+    thread.events.push(event);
+}
+/** @internal */
+export function resumeTokenFor(thread, adapterId) {
+    return thread.resumeTokens[adapterId];
+}
+/** @internal */
+export function setResumeToken(thread, adapterId, token) {
+    thread.resumeTokens[adapterId] = token;
+}
+/**
+ * Render canonical events into thread-phase's internal `Message[]` for
+ * cross-adapter handoff when no per-adapter resume token is available.
+ *
+ * Lossy by design:
+ * - `native` events are skipped — they have no canonical message equivalent.
+ * - `tool_result.output` is coerced to a string. Adapters that need the
+ *   native shape should consume the canonical event log directly.
+ * - `error` and `agent_start`/`agent_end` events do not produce messages;
+ *   they are run-lifecycle signals, not conversation content.
+ * - Multiple assistant turns within one run become one assistant message
+ *   per turn boundary (`turn_end`); a trailing text run without a
+ *   `turn_end` is flushed at `agent_end`.
+ *
+ * Treat the output as conversation history, not as an authoritative log.
+ *
+ * @internal
+ */
+export function threadToMessages(thread) {
+    const out = [];
+    let pendingText = '';
+    let pendingToolCalls = [];
+    let hasAssistantContent = false;
+    const flushAssistant = () => {
+        if (!hasAssistantContent)
+            return;
+        out.push({
+            role: 'assistant',
+            content: pendingText,
+            toolCalls: pendingToolCalls,
+        });
+        pendingText = '';
+        pendingToolCalls = [];
+        hasAssistantContent = false;
+    };
+    for (const event of thread.events) {
+        switch (event.type) {
+            case 'text':
+                pendingText += event.delta;
+                hasAssistantContent = true;
+                break;
+            case 'tool_call':
+                pendingToolCalls.push({
+                    id: event.id,
+                    name: event.name,
+                    input: coerceToolInput(event.input),
+                });
+                hasAssistantContent = true;
+                break;
+            case 'turn_end':
+                // Prefer the adapter-assembled assistant text when present; deltas
+                // may not have streamed (turns-only adapters).
+                if (event.assistantText && !pendingText) {
+                    pendingText = event.assistantText;
+                    hasAssistantContent = true;
+                }
+                flushAssistant();
+                break;
+            case 'tool_result':
+                flushAssistant();
+                out.push({
+                    role: 'tool',
+                    toolCallId: event.id,
+                    content: coerceToolOutput(event.output),
+                });
+                break;
+            case 'agent_end':
+                flushAssistant();
+                break;
+            case 'agent_start':
+            case 'error':
+            case 'native':
+            case 'thinking':
+                // Reasoning content is not part of conversation history; downstream
+                // adapters should see the agent's text output, not its inner monologue.
+                break;
+        }
+    }
+    // A run that ends without a terminal turn_end/agent_end still flushes.
+    flushAssistant();
+    return out;
+}
+function coerceToolInput(input) {
+    if (input !== null && typeof input === 'object' && !Array.isArray(input)) {
+        return input;
+    }
+    return { value: input };
+}
+function coerceToolOutput(output) {
+    if (typeof output === 'string')
+        return output;
+    try {
+        return JSON.stringify(output);
+    }
+    catch {
+        return String(output);
+    }
+}
+//# sourceMappingURL=thread.js.map

package/dist/agents/thread.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"thread.js","sourceRoot":"","sources":["../../src/agents/thread.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAoBH,gBAAgB;AAChB,MAAM,UAAU,YAAY;IAC1B,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,YAAY,EAAE,EAAE,EAAE,CAAC;AAC1C,CAAC;AAED,gBAAgB;AAChB,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,KAAiB;IAC3D,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC5B,CAAC;AAED,gBAAgB;AAChB,MAAM,UAAU,cAAc,CAAC,MAAc,EAAE,SAAiB;IAC9D,OAAO,MAAM,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC;AACxC,CAAC;AAED,gBAAgB;AAChB,MAAM,UAAU,cAAc,CAAC,MAAc,EAAE,SAAiB,EAAE,KAAkB;IAClF,MAAM,CAAC,YAAY,CAAC,SAAS,CAAC,GAAG,KAAK,CAAC;AACzC,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,MAAM,GAAG,GAAc,EAAE,CAAC;IAE1B,IAAI,WAAW,GAAG,EAAE,CAAC;IACrB,IAAI,gBAAgB,GAAe,EAAE,CAAC;IACtC,IAAI,mBAAmB,GAAG,KAAK,CAAC;IAEhC,MAAM,cAAc,GAAG,GAAS,EAAE;QAChC,IAAI,CAAC,mBAAmB;YAAE,OAAO;QACjC,GAAG,CAAC,IAAI,CAAC;YACP,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,WAAW;YACpB,SAAS,EAAE,gBAAgB;SAC5B,CAAC,CAAC;QACH,WAAW,GAAG,EAAE,CAAC;QACjB,gBAAgB,GAAG,EAAE,CAAC;QACtB,mBAAmB,GAAG,KAAK,CAAC;IAC9B,CAAC,CAAC;IAEF,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAClC,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;YACnB,KAAK,MAAM;gBACT,WAAW,IAAI,KAAK,CAAC,KAAK,CAAC;gBAC3B,mBAAmB,GAAG,IAAI,CAAC;gBAC3B,MAAM;YACR,KAAK,WAAW;gBACd,gBAAgB,CAAC,IAAI,CAAC;oBACpB,EAAE,EAAE,KAAK,CAAC,EAAE;oBACZ,IAAI,EAAE,KAAK,CAAC,IAAI;oBAChB,KAAK,EAAE,eAAe,CAAC,KAAK,CAAC,KAAK,CAAC;iBACpC,CAAC,CAAC;gBACH,mBAAmB,GAAG,IAAI,CAAC;gBAC3B,MAAM;YACR,KAAK,UAAU;gBACb,mEAAmE;gBACnE,+CAA+C;gBAC/C,IAAI,KAAK,CAAC,aAAa,IAAI,CAAC,WAAW,EAAE,CAAC;oBACxC,WAAW,GAAG,KAAK,CAAC,aAAa,CAAC;oBAClC,mBAAmB,GAAG,IAAI,CAAC;gBAC7B,CAAC;gBACD,cAAc,EAAE,CAAC;gBACjB,MAAM;YACR,KAAK,aAAa;gBAChB,cAAc,EAAE,CAAC;gBACjB,GAAG,CAAC,IAAI,CAAC;oBACP,IAAI,EAAE,MAAM;oBACZ,UAAU,EAAE,KAAK,CAAC,EAAE;oBACpB,OAAO,EAAE,gBAAgB,CAAC,KAAK,CAAC,MAAM,CAAC;iBACxC,CAAC,CAAC;gBACH,MAAM;YACR,KAAK,WAAW;gBACd,cAAc,EAAE,CAAC;gBACjB,MAAM;YACR,KAAK,aAAa,CAAC;YACnB,KAAK,OAAO,CAAC;YACb,KAAK,QAAQ,CAAC;YACd,KAAK,UAAU;gBACb,oEAAoE;gBACpE,wEAAwE;gBACxE,MAAM;QACV,CAAC;IACH,CAAC;IAED,uEAAuE;IACvE,cAAc,EAAE,CAAC;IAEjB,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,eAAe,CAAC,KAAc;IACrC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzE,OAAO,KAAgC,CAAC;IAC1C,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAC1B,CAAC;AAED,SAAS,gBAAgB,CAAC,MAAe;IACvC,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC;IAC9C,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC;IACxB,CAAC;AACH,CAAC"}

package/dist/agents/turn-accumulator.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Helper for translating primitive adapter-level callbacks into canonical
+ * `AgentEvent`s with correct turn-boundary semantics.
+ *
+ * The non-obvious problem this solves: some underlying runtimes (the in-tree
+ * OpenAI runner is one) emit their end-of-turn marker BEFORE the tool calls
+ * of that turn — the model decodes content, the runtime fires `round_complete`,
+ * then the tool calls follow as separate events. In canonical semantics, a
+ * `turn_end` belongs AFTER its turn's tool calls so `toolCallCount` reflects
+ * what actually happened in that turn.
+ *
+ * The accumulator handles this by deferring `turn_end` emission. Call
+ * `markTurnEnd()` when the underlying runtime says the turn ended; the event
+ * is held until the NEXT text delta (= new turn starts) or `close()` (= run
+ * ends). Tool calls in between count against the pending turn.
+ *
+ * Adapters whose runtime emits turn boundaries naturally (after all tool
+ * calls of the same turn) can still use this helper — `markTurnEnd()` +
+ * `close()` with no intervening events flushes immediately.
+ *
+ * Also handles the boilerplate of stamping `source` and `traceId` on every
+ * canonical event the adapter emits, which every adapter has to do.
+ *
+ * @internal
+ */
+import type { UsageInfo } from '../agent/types.js';
+import type { AgentEvent } from './protocol.js';
+/** @internal */
+export declare class TurnAccumulator {
+    private readonly emit;
+    private readonly source;
+    private readonly traceId?;
+    private turnText;
+    private currentTurnToolCalls;
+    private pending;
+    constructor(emit: (event: AgentEvent) => void, source: string, traceId?: string | undefined);
+    /**
+     * Emit a text delta. Flushes any pending `turn_end` first — a text delta
+     * after `markTurnEnd()` is the canonical signal that a new turn has begun.
+     */
+    text(delta: string): void;
+    /**
+     * Emit a thinking (reasoning) delta. Does NOT flush a pending turn —
+     * reasoning is intra-turn content, not a turn boundary signal.
+     */
+    thinking(delta: string): void;
+    /**
+     * Emit a tool call. Counts toward the current turn regardless of which
+     * turn-end style the adapter uses — deferred (`markTurnEnd`) or
+     * immediate (`endTurn`).
+     */
+    toolCall(id: string, name: string, input: unknown): void;
+    /** Emit a tool result. Does not affect pending-turn state. */
+    toolResult(id: string, name: string, output: unknown, isError: boolean): void;
+    /**
+     * Emit a native (adapter-specific) event verbatim. Stamps `source` and
+     * `traceId` so adapters don't have to repeat the boilerplate. Does not
+     * affect pending-turn state.
+     */
+    native(kind: string, payload: unknown): void;
+    /**
+     * Mark the end of a turn — deferred-emission variant. Use when the
+     * underlying runtime emits its end-of-turn marker BEFORE the tool calls
+     * that belong to that turn (the in-tree OpenAI runner is one such case).
+     * The `turn_end` event is NOT emitted yet; it stays pending until either
+     * the next text delta (next turn starts) or `close()` (run ends). Tool
+     * calls that arrive between now and the flush count toward this turn.
+     *
+     * For runtimes with natural turn ordering (tool calls inside the turn,
+     * then turn boundary), use `endTurn()` instead.
+     *
+     * Optional `usage` is attached to the eventual `turn_end` event.
+     */
+    markTurnEnd(usage?: UsageInfo): void;
+    /**
+     * Emit a `turn_end` event NOW with the current turn's text and tool-call
+     * count, then reset the counters. Use when the underlying runtime
+     * already had all of this turn's tool calls before the boundary signal
+     * (the ACP `session/prompt` response is one such case — agent_message_chunks
+     * and tool_calls precede the stopReason).
+     *
+     * If a `markTurnEnd()` deferred turn is still pending, it's flushed first.
+     *
+     * Optional `usage` is attached to the emitted `turn_end` event.
+     */
+    endTurn(usage?: UsageInfo): void;
+    /**
+     * Flush any pending `turn_end`. Call once at run end, before emitting
+     * `agent_end`. Idempotent — calling twice with nothing pending is a no-op.
+     */
+    close(): void;
+    private flush;
+}
+//# sourceMappingURL=turn-accumulator.d.ts.map

package/dist/agents/turn-accumulator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-accumulator.d.ts","sourceRoot":"","sources":["../../src/agents/turn-accumulator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,gBAAgB;AAChB,qBAAa,eAAe;IAMxB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IAP3B,OAAO,CAAC,QAAQ,CAAM;IACtB,OAAO,CAAC,oBAAoB,CAAK;IACjC,OAAO,CAAC,OAAO,CAAkF;gBAG9E,IAAI,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,EACjC,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,YAAA;IAGnC;;;OAGG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAMzB;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAI7B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAKxD,8DAA8D;IAC9D,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI;IAY7E;;;;OAIG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI;IAI5C;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,KAAK,CAAC,EAAE,SAAS,GAAG,IAAI;IAKpC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,KAAK,CAAC,EAAE,SAAS,GAAG,IAAI;IAchC;;;OAGG;IACH,KAAK,IAAI,IAAI;IAIb,OAAO,CAAC,KAAK;CAcd"}