@autonome-research/thread-phase 3.0.0

package/dist/agents/serialize-error.js

@@ -0,0 +1,27 @@
+/**
+ * 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
+ */
+/**
+ * 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 function serializeError(err) {
+    if (err instanceof Error) {
+        return {
+            name: err.name,
+            message: err.message,
+            stack: err.stack,
+            cause: err.cause !== undefined ? serializeError(err.cause) : undefined,
+        };
+    }
+    return { name: 'NonError', message: String(err) };
+}
+//# sourceMappingURL=serialize-error.js.map

package/dist/agents/serialize-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize-error.js","sourceRoot":"","sources":["../../src/agents/serialize-error.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,GAAY;IACzC,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;QACzB,OAAO;YACL,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,OAAO,EAAE,GAAG,CAAC,OAAO;YACpB,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,KAAK,EAAE,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS;SACvE,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;AACpD,CAAC"}

package/dist/agents/structured-output.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Prompted structured-output helpers.
+ *
+ * Adapters that declare `structuredOutput: 'prompted'` cannot ask the
+ * underlying runtime for a JSON-schema-constrained response, so they instead
+ * inject an instruction into the system prompt and parse the agent's final
+ * text afterward. This module owns both halves: `applyStructuredOutputPrompt`
+ * augments the prompt; `parseStructuredFromText` (and the convenience
+ * `parseStructured`) extract and validate the payload.
+ *
+ * The contract: the agent emits its final answer inside a single
+ * `<response>...</response>` block. Free-form reasoning may precede it.
+ * Retries on parse failure are not executed here — that is an adapter-level
+ * concern (the adapter calls `followUp()` with the parse error and retries).
+ *
+ * @internal
+ */
+import type { AgentRunResult } from './protocol.js';
+/**
+ * Configuration for the prompted structured-output path.
+ *
+ * @internal
+ */
+export interface StructuredOutputConfig {
+    /**
+     * JSON Schema describing the expected payload, or a free-form description
+     * string. Used to render the instruction; not validated by this module —
+     * callers supply `validate` if they want a check.
+     */
+    schema: Record<string, unknown> | string;
+    /**
+     * Optional caller-supplied validator. When provided, `parseStructured`
+     * runs it on the extracted JSON and throws `StructuredOutputParseError`
+     * if it returns false. Default is identity (no validation).
+     */
+    validate?: (data: unknown) => boolean;
+    /**
+     * Retries are NOT executed by this module — they are an adapter-level
+     * concern. Documented here so adapters can read the intended count.
+     * Default: 1.
+     */
+    retries?: number;
+}
+/**
+ * Distinct error for the prompted-output path. Carries the offending text
+ * window so callers can decide whether to retry.
+ *
+ * @internal
+ */
+export declare class StructuredOutputParseError extends Error {
+    window: string;
+    constructor(message: string, window: string);
+}
+/**
+ * Append the prompted-output instruction to a system prompt. The instruction
+ * tells the agent to emit a single `<response>...</response>` block whose
+ * contents are JSON conforming to the schema, after any free-form text.
+ *
+ * String schemas are embedded verbatim; object schemas are JSON-stringified
+ * with 2-space indent. The instruction is separated from the existing prompt
+ * by a blank line.
+ *
+ * @internal
+ */
+export declare function applyStructuredOutputPrompt(systemPrompt: string, spec: StructuredOutputConfig): string;
+/**
+ * Extract the last `<response>...</response>` block from arbitrary text.
+ * Returns the inner content (trimmed) on match, or `null` when no block is
+ * present. Taking the LAST match makes the parser robust to wrapped thinking
+ * and accidental example tags earlier in the output.
+ *
+ * @internal
+ */
+export declare function extractResponseBlock(text: string): string | null;
+/**
+ * Extract, parse, and optionally validate a structured payload from arbitrary
+ * agent text. Throws `StructuredOutputParseError` on extraction failure, JSON
+ * parse failure, or validator rejection.
+ *
+ * @internal
+ */
+export declare function parseStructuredFromText(text: string, spec: StructuredOutputConfig): unknown;
+/**
+ * Convenience wrapper: same as `parseStructuredFromText` but reads the text
+ * from a completed `AgentRunResult`.
+ *
+ * @internal
+ */
+export declare function parseStructured(result: AgentRunResult, spec: StructuredOutputConfig): unknown;
+//# sourceMappingURL=structured-output.d.ts.map

package/dist/agents/structured-output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured-output.d.ts","sourceRoot":"","sources":["../../src/agents/structured-output.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC;IACzC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC;IACtC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;IACf,MAAM,EAAE,MAAM;gBAAtC,OAAO,EAAE,MAAM,EAAS,MAAM,EAAE,MAAM;CAInD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CACzC,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,sBAAsB,GAC3B,MAAM,CAUR;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOhE;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,sBAAsB,GAC3B,OAAO,CAeT;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,sBAAsB,GAC3B,OAAO,CAET"}

package/dist/agents/structured-output.js

@@ -0,0 +1,101 @@
+/**
+ * Prompted structured-output helpers.
+ *
+ * Adapters that declare `structuredOutput: 'prompted'` cannot ask the
+ * underlying runtime for a JSON-schema-constrained response, so they instead
+ * inject an instruction into the system prompt and parse the agent's final
+ * text afterward. This module owns both halves: `applyStructuredOutputPrompt`
+ * augments the prompt; `parseStructuredFromText` (and the convenience
+ * `parseStructured`) extract and validate the payload.
+ *
+ * The contract: the agent emits its final answer inside a single
+ * `<response>...</response>` block. Free-form reasoning may precede it.
+ * Retries on parse failure are not executed here — that is an adapter-level
+ * concern (the adapter calls `followUp()` with the parse error and retries).
+ *
+ * @internal
+ */
+/**
+ * Distinct error for the prompted-output path. Carries the offending text
+ * window so callers can decide whether to retry.
+ *
+ * @internal
+ */
+export class StructuredOutputParseError extends Error {
+    window;
+    constructor(message, window) {
+        super(message);
+        this.window = window;
+        this.name = 'StructuredOutputParseError';
+    }
+}
+/**
+ * Append the prompted-output instruction to a system prompt. The instruction
+ * tells the agent to emit a single `<response>...</response>` block whose
+ * contents are JSON conforming to the schema, after any free-form text.
+ *
+ * String schemas are embedded verbatim; object schemas are JSON-stringified
+ * with 2-space indent. The instruction is separated from the existing prompt
+ * by a blank line.
+ *
+ * @internal
+ */
+export function applyStructuredOutputPrompt(systemPrompt, spec) {
+    const schemaText = typeof spec.schema === 'string' ? spec.schema : JSON.stringify(spec.schema, null, 2);
+    const instruction = 'When finished, emit your final answer as a single <response>...</response> block ' +
+        'whose contents are valid JSON conforming to:\n' +
+        schemaText +
+        '\nDo not include any text after the closing tag.';
+    const base = systemPrompt.trimEnd();
+    return base.length > 0 ? `${base}\n\n${instruction}` : instruction;
+}
+/**
+ * Extract the last `<response>...</response>` block from arbitrary text.
+ * Returns the inner content (trimmed) on match, or `null` when no block is
+ * present. Taking the LAST match makes the parser robust to wrapped thinking
+ * and accidental example tags earlier in the output.
+ *
+ * @internal
+ */
+export function extractResponseBlock(text) {
+    const re = /<response>([\s\S]*?)<\/response>/g;
+    let last = null;
+    for (const match of text.matchAll(re)) {
+        last = match[1] ?? '';
+    }
+    return last === null ? null : last.trim();
+}
+/**
+ * Extract, parse, and optionally validate a structured payload from arbitrary
+ * agent text. Throws `StructuredOutputParseError` on extraction failure, JSON
+ * parse failure, or validator rejection.
+ *
+ * @internal
+ */
+export function parseStructuredFromText(text, spec) {
+    const block = extractResponseBlock(text);
+    if (block === null) {
+        throw new StructuredOutputParseError('no <response> block in output', text.slice(-500));
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(block);
+    }
+    catch {
+        throw new StructuredOutputParseError('invalid JSON in <response>', block);
+    }
+    if (spec.validate && !spec.validate(parsed)) {
+        throw new StructuredOutputParseError('payload rejected by validator', block);
+    }
+    return parsed;
+}
+/**
+ * Convenience wrapper: same as `parseStructuredFromText` but reads the text
+ * from a completed `AgentRunResult`.
+ *
+ * @internal
+ */
+export function parseStructured(result, spec) {
+    return parseStructuredFromText(result.text, spec);
+}
+//# sourceMappingURL=structured-output.js.map

package/dist/agents/structured-output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured-output.js","sourceRoot":"","sources":["../../src/agents/structured-output.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AA8BH;;;;;GAKG;AACH,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IACf;IAApC,YAAY,OAAe,EAAS,MAAc;QAChD,KAAK,CAAC,OAAO,CAAC,CAAC;QADmB,WAAM,GAAN,MAAM,CAAQ;QAEhD,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC3C,CAAC;CACF;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,2BAA2B,CACzC,YAAoB,EACpB,IAA4B;IAE5B,MAAM,UAAU,GACd,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IACvF,MAAM,WAAW,GACf,mFAAmF;QACnF,gDAAgD;QAChD,UAAU;QACV,kDAAkD,CAAC;IACrD,MAAM,IAAI,GAAG,YAAY,CAAC,OAAO,EAAE,CAAC;IACpC,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,OAAO,WAAW,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC;AACrE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC/C,MAAM,EAAE,GAAG,mCAAmC,CAAC;IAC/C,IAAI,IAAI,GAAkB,IAAI,CAAC;IAC/B,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;QACtC,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACxB,CAAC;IACD,OAAO,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;AAC5C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CACrC,IAAY,EACZ,IAA4B;IAE5B,MAAM,KAAK,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAAC;IACzC,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,MAAM,IAAI,0BAA0B,CAAC,+BAA+B,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1F,CAAC;IACD,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,0BAA0B,CAAC,4BAA4B,EAAE,KAAK,CAAC,CAAC;IAC5E,CAAC;IACD,IAAI,IAAI,CAAC,QAAQ,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,0BAA0B,CAAC,+BAA+B,EAAE,KAAK,CAAC,CAAC;IAC/E,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAsB,EACtB,IAA4B;IAE5B,OAAO,uBAAuB,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AACpD,CAAC"}

package/dist/agents/test-utils/conformance.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Parameterized vitest suite that asserts an `AgentAdapter` honors the
+ * protocol's lifecycle invariants. Both in-tree tests and the sibling
+ * `@autonome-research/thread-phase-agents` package import this and call it from a `describe`
+ * or top-level test file.
+ *
+ * Invariants asserted (see `protocol.ts` for the canonical statements):
+ *   - exactly one `agent_start` at the head of the stream,
+ *   - exactly one `agent_end` at the tail of the stream,
+ *   - `result` resolves and never rejects,
+ *   - `result.finishReason` matches `agent_end.reason`,
+ *   - `abort()` is idempotent and yields `finishReason: 'aborted'`,
+ *   - `options.signal` is observed,
+ *   - `options.eventBus` mirrors the full event stream,
+ *   - every event carries `source === meta.id`,
+ *   - the `events` AsyncIterable terminates,
+ *   - `events` is single-consumer (second iteration attempt throws),
+ *   - `events` iterator `return()` cleanly closes the stream,
+ *   - `result` resolves even when `events` is never iterated.
+ *
+ * Adapters that can synthesize internal-error runs supply `buildErrorConfig`
+ * to additionally assert the resolve-not-reject invariant on the error path.
+ *
+ * @internal
+ */
+import type { AgentAdapterMeta } from '../protocol.js';
+/**
+ * Per-adapter config-builder. Each invocation must return a fresh config
+ * suitable for one run. Caller controls how prompts/messages are shaped.
+ *
+ * @internal
+ */
+export type ConformanceConfigBuilder<TConfig> = () => TConfig;
+/**
+ * Options for running the conformance suite against an adapter.
+ *
+ * @internal
+ */
+export interface RunConformanceSuiteOptions<TConfig> {
+    meta: AgentAdapterMeta<TConfig>;
+    buildConfig: ConformanceConfigBuilder<TConfig>;
+    /**
+     * Optional: build a config that should produce a runner-internal error.
+     * Used to test the "result resolves rather than rejects on error" invariant.
+     * If omitted, that test is skipped. Sibling adapters that can't reliably
+     * trigger an internal error may omit this safely.
+     */
+    buildErrorConfig?: ConformanceConfigBuilder<TConfig>;
+    /** Per-test timeout in ms. Default 10_000. */
+    timeoutMs?: number;
+}
+/**
+ * Run the full conformance suite against an adapter. Registers its own
+ * `describe` block.
+ *
+ * @internal
+ */
+export declare function runAdapterConformance<TConfig>(opts: RunConformanceSuiteOptions<TConfig>): void;
+//# sourceMappingURL=conformance.d.ts.map

package/dist/agents/test-utils/conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.d.ts","sourceRoot":"","sources":["../../../src/agents/test-utils/conformance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,KAAK,EACV,gBAAgB,EAIjB,MAAM,gBAAgB,CAAC;AAGxB;;;;;GAKG;AACH,MAAM,MAAM,wBAAwB,CAAC,OAAO,IAAI,MAAM,OAAO,CAAC;AAE9D;;;;GAIG;AACH,MAAM,WAAW,0BAA0B,CAAC,OAAO;IACjD,IAAI,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAChC,WAAW,EAAE,wBAAwB,CAAC,OAAO,CAAC,CAAC;IAC/C;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,wBAAwB,CAAC,OAAO,CAAC,CAAC;IACrD,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAC3C,IAAI,EAAE,0BAA0B,CAAC,OAAO,CAAC,GACxC,IAAI,CA6ON"}

package/dist/agents/test-utils/conformance.js

@@ -0,0 +1,207 @@
+/**
+ * Parameterized vitest suite that asserts an `AgentAdapter` honors the
+ * protocol's lifecycle invariants. Both in-tree tests and the sibling
+ * `@autonome-research/thread-phase-agents` package import this and call it from a `describe`
+ * or top-level test file.
+ *
+ * Invariants asserted (see `protocol.ts` for the canonical statements):
+ *   - exactly one `agent_start` at the head of the stream,
+ *   - exactly one `agent_end` at the tail of the stream,
+ *   - `result` resolves and never rejects,
+ *   - `result.finishReason` matches `agent_end.reason`,
+ *   - `abort()` is idempotent and yields `finishReason: 'aborted'`,
+ *   - `options.signal` is observed,
+ *   - `options.eventBus` mirrors the full event stream,
+ *   - every event carries `source === meta.id`,
+ *   - the `events` AsyncIterable terminates,
+ *   - `events` is single-consumer (second iteration attempt throws),
+ *   - `events` iterator `return()` cleanly closes the stream,
+ *   - `result` resolves even when `events` is never iterated.
+ *
+ * Adapters that can synthesize internal-error runs supply `buildErrorConfig`
+ * to additionally assert the resolve-not-reject invariant on the error path.
+ *
+ * @internal
+ */
+import { describe, it, expect } from 'vitest';
+import { createEventBus } from '../event-bus.js';
+/**
+ * Run the full conformance suite against an adapter. Registers its own
+ * `describe` block.
+ *
+ * @internal
+ */
+export function runAdapterConformance(opts) {
+    const { meta, buildConfig, buildErrorConfig } = opts;
+    const timeout = opts.timeoutMs ?? 10_000;
+    describe(`AgentAdapter conformance: ${meta.id}`, () => {
+        it('emits agent_start as the first event with source === meta.id', async () => {
+            const run = meta.adapter(buildConfig());
+            const events = await collectEvents(run);
+            expect(events.length).toBeGreaterThan(0);
+            expect(events[0].type).toBe('agent_start');
+            expect(events[0].source).toBe(meta.id);
+            await run.result;
+        }, timeout);
+        it('emits exactly one agent_end and it is the last event', async () => {
+            const run = meta.adapter(buildConfig());
+            const events = await collectEvents(run);
+            const ends = events.filter((e) => e.type === 'agent_end');
+            expect(ends).toHaveLength(1);
+            expect(events[events.length - 1].type).toBe('agent_end');
+            await run.result;
+        }, timeout);
+        it('result resolves and never rejects', async () => {
+            const run = meta.adapter(buildConfig());
+            // Drain events in parallel so result can settle.
+            const [, result] = await Promise.all([collectEvents(run), run.result]);
+            expect(result).toBeDefined();
+            // Sanity: finishReason is one of the known values.
+            expect(typeof result.finishReason).toBe('string');
+        }, timeout);
+        it('result.finishReason matches agent_end.reason', async () => {
+            const run = meta.adapter(buildConfig());
+            const [events, result] = await Promise.all([collectEvents(run), run.result]);
+            const end = events.find((e) => e.type === 'agent_end');
+            expect(end).toBeDefined();
+            if (end && end.type === 'agent_end') {
+                expect(end.reason).toBe(result.finishReason);
+            }
+        }, timeout);
+        it('abort() is idempotent and produces finishReason: "aborted"', async () => {
+            const run = meta.adapter(buildConfig());
+            // Abort synchronously so adapters of any speed observe it before
+            // they finish. Real consumers that abort mid-run hit a slower path;
+            // the invariant we care about here is "abort wins, twice is fine".
+            run.abort();
+            run.abort(); // second call must not throw
+            const [, result] = await Promise.all([collectEvents(run), run.result]);
+            expect(result.finishReason).toBe('aborted');
+        }, timeout);
+        it('honors AbortSignal from options', async () => {
+            const controller = new AbortController();
+            controller.abort();
+            const options = { signal: controller.signal };
+            const run = meta.adapter(buildConfig(), options);
+            const [, result] = await Promise.all([collectEvents(run), run.result]);
+            expect(result.finishReason).toBe('aborted');
+        }, timeout);
+        it('mirrors every event to options.eventBus', async () => {
+            const bus = createEventBus();
+            const seen = [];
+            bus.on((event) => {
+                seen.push(event);
+            });
+            const run = meta.adapter(buildConfig(), { eventBus: bus });
+            const [streamed] = await Promise.all([collectEvents(run), run.result]);
+            // Bus must observe at least every type the stream did. The contract
+            // is "all events mirrored" — assert equal counts per type to avoid
+            // ordering subtleties between sync emit and async iteration.
+            expect(seen.length).toBe(streamed.length);
+            const streamTypes = streamed.map((e) => e.type).sort();
+            const busTypes = seen.map((e) => e.type).sort();
+            expect(busTypes).toEqual(streamTypes);
+        }, timeout);
+        it('every event has source === meta.id', async () => {
+            const run = meta.adapter(buildConfig());
+            const [events] = await Promise.all([collectEvents(run), run.result]);
+            for (const event of events) {
+                expect(event.source).toBe(meta.id);
+            }
+        }, timeout);
+        it('events AsyncIterable terminates', async () => {
+            const run = meta.adapter(buildConfig());
+            // collectEvents itself iterates to done — if it returns, the
+            // iterable terminated. Add an explicit timeout as a guard.
+            const events = await withTimeout(collectEvents(run), timeout, 'events iterable did not terminate');
+            expect(Array.isArray(events)).toBe(true);
+            await run.result;
+        }, timeout);
+        it('events is single-consumer — second iteration attempt throws', async () => {
+            const run = meta.adapter(buildConfig());
+            // First call must succeed.
+            run.events[Symbol.asyncIterator]();
+            // Second call must throw synchronously — splitting the stream
+            // across two consumers is a silent bug, so the protocol fails
+            // loudly. Callers wanting multi-cast wire AgentEventBus instead.
+            expect(() => run.events[Symbol.asyncIterator]()).toThrow();
+            // Drain so the run completes before the test ends.
+            await run.result.catch(() => undefined);
+        }, timeout);
+        it('events iterator return() cleanly closes the stream', async () => {
+            const run = meta.adapter(buildConfig());
+            const iter = run.events[Symbol.asyncIterator]();
+            // Pull at least one event so the run is in flight, then abandon.
+            await withTimeout(iter.next(), timeout, 'first next() did not resolve');
+            await iter.return?.();
+            // Invariant: result still resolves. Whether the run was aborted
+            // by the early return is an adapter-design choice (mockAgent
+            // aborts; inferenceAgent lets the run complete) — but `result`
+            // must not deadlock either way.
+            const result = await withTimeout(run.result, timeout, 'result did not resolve after iterator.return()');
+            expect(result).toBeDefined();
+        }, timeout);
+        it('result resolves even when events is never iterated', async () => {
+            const run = meta.adapter(buildConfig());
+            // No collectEvents call — adapters that block on consumption
+            // would deadlock here. The protocol requires events to queue
+            // (or drop) without blocking the producer.
+            const result = await withTimeout(run.result, timeout, 'result did not resolve without events iteration');
+            expect(result).toBeDefined();
+        }, timeout);
+        if (buildErrorConfig) {
+            it('result resolves rather than rejects on adapter-internal error', async () => {
+                const run = meta.adapter(buildErrorConfig());
+                let threw = false;
+                let result;
+                try {
+                    const [collected, r] = await Promise.all([collectEvents(run), run.result]);
+                    result = r;
+                    const errorBeforeEnd = collected.some((e, i) => e.type === 'error' &&
+                        collected.findIndex((x) => x.type === 'agent_end') > i);
+                    expect(errorBeforeEnd).toBe(true);
+                }
+                catch {
+                    threw = true;
+                }
+                expect(threw).toBe(false);
+                expect(result?.finishReason).toBe('error');
+            }, timeout);
+        }
+        if (meta.capabilities.resumption !== 'none') {
+            it('agent_start or agent_end carries a resumeToken whose kind matches the declared resumption', async () => {
+                const run = meta.adapter(buildConfig());
+                const [events] = await Promise.all([collectEvents(run), run.result]);
+                const lifecycle = events.filter((e) => e.type === 'agent_start' || e.type === 'agent_end');
+                const token = lifecycle.map((e) => e.resumeToken).find((t) => t !== undefined);
+                expect(token).toBeDefined();
+                if (token) {
+                    expect(token.kind).toBe(meta.capabilities.resumption);
+                }
+            }, timeout);
+        }
+    });
+}
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+async function collectEvents(run) {
+    const out = [];
+    for await (const event of run.events) {
+        out.push(event);
+    }
+    return out;
+}
+function withTimeout(p, ms, label) {
+    return new Promise((resolve, reject) => {
+        const t = setTimeout(() => reject(new Error(`timeout: ${label} after ${ms}ms`)), ms);
+        p.then((v) => {
+            clearTimeout(t);
+            resolve(v);
+        }, (e) => {
+            clearTimeout(t);
+            reject(e);
+        });
+    });
+}
+//# sourceMappingURL=conformance.js.map

package/dist/agents/test-utils/conformance.js.map

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

package/dist/agents/test-utils/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Test utilities for the AgentAdapter protocol.
+ *
+ * Importers (in-tree tests and the sibling `@autonome-research/thread-phase-agents` package)
+ * pull `createMockAgent` for scripted adapter behavior and
+ * `runAdapterConformance` for protocol-contract assertions.
+ *
+ * @internal
+ */
+export { createMockAgent, MOCK_DEFAULT_CAPABILITIES, type CreateMockAgentOptions, type MockAgentConfig, } from './mock-agent.js';
+export { runAdapterConformance, type ConformanceConfigBuilder, type RunConformanceSuiteOptions, } from './conformance.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/agents/test-utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/agents/test-utils/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,eAAe,EACf,yBAAyB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,eAAe,GACrB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,qBAAqB,EACrB,KAAK,wBAAwB,EAC7B,KAAK,0BAA0B,GAChC,MAAM,kBAAkB,CAAC"}

package/dist/agents/test-utils/index.js

@@ -0,0 +1,12 @@
+/**
+ * Test utilities for the AgentAdapter protocol.
+ *
+ * Importers (in-tree tests and the sibling `@autonome-research/thread-phase-agents` package)
+ * pull `createMockAgent` for scripted adapter behavior and
+ * `runAdapterConformance` for protocol-contract assertions.
+ *
+ * @internal
+ */
+export { createMockAgent, MOCK_DEFAULT_CAPABILITIES, } from './mock-agent.js';
+export { runAdapterConformance, } from './conformance.js';
+//# sourceMappingURL=index.js.map

package/dist/agents/test-utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/agents/test-utils/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,eAAe,EACf,yBAAyB,GAG1B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,qBAAqB,GAGtB,MAAM,kBAAkB,CAAC"}

package/dist/agents/test-utils/mock-agent.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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 { type AgentAdapterMeta, type AgentCapabilities, type AgentEvent, type AgentRunResult } from '../protocol.js';
+/**
+ * Scripted invocation of the mock adapter. The adapter emits exactly the
+ * events in `events`, in order, then resolves `result` with the scripted
+ * value. Lifecycle events (`agent_start`, `agent_end`) are added by the
+ * adapter — do not include them in `events`.
+ *
+ * @internal
+ */
+export interface MockAgentConfig {
+    /** Events to emit, in order. Should NOT include agent_start or agent_end. */
+    events: ReadonlyArray<AgentEvent>;
+    /** Final result. agent_end.reason will mirror result.finishReason. */
+    result: AgentRunResult;
+    /**
+     * Delay in ms between scripted events. 0 = a microtask hop per event.
+     * Default 0. Use a positive value to exercise consumers that need to
+     * interleave with async work.
+     */
+    perEventDelayMs?: number;
+    /**
+     * If set, the adapter throws this when called. Used to test how callers
+     * handle adapter-construction-time failures (vs run-time errors which
+     * should still resolve `result`).
+     */
+    throwOnConstruct?: Error;
+}
+/**
+ * Override knobs for the mock adapter's metadata. Defaults match a minimal
+ * adapter: `streaming: 'text'`, `cancellation: 'cooperative'`,
+ * `resumption: 'none'`, `structuredOutput: 'none'`.
+ *
+ * @internal
+ */
+export interface CreateMockAgentOptions {
+    id?: string;
+    capabilities?: Partial<AgentCapabilities>;
+}
+/**
+ * Default capabilities used when none are overridden.
+ *
+ * @internal
+ */
+export declare const MOCK_DEFAULT_CAPABILITIES: AgentCapabilities;
+/**
+ * Build a mock adapter suitable for testing pattern code and any consumer
+ * targeting the AgentAdapter protocol.
+ *
+ * @internal
+ */
+export declare function createMockAgent(opts?: CreateMockAgentOptions): AgentAdapterMeta<MockAgentConfig>;
+//# sourceMappingURL=mock-agent.d.ts.map

package/dist/agents/test-utils/mock-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-agent.d.ts","sourceRoot":"","sources":["../../../src/agents/test-utils/mock-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,UAAU,EAGf,KAAK,cAAc,EACpB,MAAM,gBAAgB,CAAC;AAExB;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,MAAM,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IAClC,sEAAsE;IACtE,MAAM,EAAE,cAAc,CAAC;IACvB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,KAAK,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAC3C;AAED;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,EAAE,iBAKvC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,IAAI,GAAE,sBAA2B,GAChC,gBAAgB,CAAC,eAAe,CAAC,CAuMnC"}