@autonome-research/thread-phase 3.0.0

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EACL,WAAW,EACX,oBAAoB,EACpB,KAAK,eAAe,GACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,UAAU,EACV,KAAK,KAAK,EACV,KAAK,mBAAmB,EACxB,KAAK,aAAa,GACnB,MAAM,YAAY,CAAC;AAKpB,OAAO,EACL,KAAK,OAAO,EACZ,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,YAAY,GAClB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,KAAK,eAAe,GACrB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,iBAAiB,EACjB,SAAS,EACT,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,SAAS,GACf,MAAM,kBAAkB,CAAC;AAM1B,OAAO,EACL,KAAK,QAAQ,EACb,cAAc,EACd,SAAS,EACT,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,KAAK,SAAS,GACf,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EACL,YAAY,EACZ,KAAK,WAAW,EAChB,KAAK,mBAAmB,GACzB,MAAM,kBAAkB,CAAC;AAK1B,OAAO,EACL,OAAO,EACP,QAAQ,EACR,IAAI,EACJ,WAAW,EACX,WAAW,EACX,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,cAAc,GACpB,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,37 @@
+/**
+ * Public API — the v1 stable surface.
+ *
+ * Everything exported from this file is covered by semver:
+ *   - patch (1.0.x): bug fixes, no API changes
+ *   - minor (1.x.0): additive only — new exports, new optional fields
+ *   - major (x.0.0): breaking changes
+ *
+ * Items marked @internal in their own files (e.g. `consumeStream`,
+ * `toOpenAIMessages`) are reachable via deep import for advanced callers
+ * but are NOT part of this stable surface and may change in minor releases.
+ *
+ * Subpath exports (./patterns, ./context, ./session, ./tools) live in their
+ * own index files and are exposed via package.json `exports`. They follow
+ * the same stability policy.
+ */
+// Phase framework
+export { PipelineCache } from './cache.js';
+export { runPipeline, runPipelineToSummary, } from './orchestrator.js';
+export { requireCtx, } from './phase.js';
+// Inference — convenience builders for an OpenAI-compatible client.
+export { loadInferenceConfig, createInferenceClient, } from './inference.js';
+// Agent runner — the iterated tool-use loop primitive.
+export { runAgentWithTools, parseJSON, } from './agent/index.js';
+// Session — persisted event log + job runner. SqliteJobStore is the
+// bundled default; JobStore is the interface — bring your own backend if
+// needed. The interface is sync by deliberate choice for v1 (sqlite hot
+// path); see ROADMAP for the rationale.
+export { SqliteJobStore, JobRunner, } from './session/index.js';
+// Tools — registry with optional ajv arg validation. Implements
+// ToolExecutor so it can be passed directly to runAgentWithTools.
+export { ToolRegistry, } from './tools/index.js';
+// Helpers — one-call wrappers for the common Trigger + Pipeline shapes.
+// Each returns an `ExtensionRegisterFn` `(api) => void` consumable by the
+// CLI auto-loader.
+export { oneShot, schedule, hook, CronTrigger, HttpTrigger, } from './helpers/index.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,kBAAkB;AAClB,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EACL,WAAW,EACX,oBAAoB,GAErB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,UAAU,GAIX,MAAM,YAAY,CAAC;AAiBpB,oEAAoE;AACpE,OAAO,EACL,mBAAmB,EACnB,qBAAqB,GAEtB,MAAM,gBAAgB,CAAC;AAExB,uDAAuD;AACvD,OAAO,EACL,iBAAiB,EACjB,SAAS,GAQV,MAAM,kBAAkB,CAAC;AAE1B,oEAAoE;AACpE,yEAAyE;AACzE,wEAAwE;AACxE,wCAAwC;AACxC,OAAO,EAEL,cAAc,EACd,SAAS,GAMV,MAAM,oBAAoB,CAAC;AAE5B,gEAAgE;AAChE,kEAAkE;AAClE,OAAO,EACL,YAAY,GAGb,MAAM,kBAAkB,CAAC;AAE1B,wEAAwE;AACxE,0EAA0E;AAC1E,mBAAmB;AACnB,OAAO,EACL,OAAO,EACP,QAAQ,EACR,IAAI,EACJ,WAAW,EACX,WAAW,GAUZ,MAAM,oBAAoB,CAAC"}

package/dist/inference.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Inference provider configuration.
+ *
+ * Single source of truth for which OpenAI-compatible endpoint we hit. Reads
+ * from env by default; downstream apps can pass overrides for testing or to
+ * point a single process at multiple providers.
+ */
+import OpenAI from 'openai';
+export interface InferenceConfig {
+    /** Base URL of the OpenAI-compatible endpoint. Defaults to local vLLM. */
+    baseUrl: string;
+    /** API key. Local vLLM accepts any non-empty string. */
+    apiKey: string;
+    /** Default model name for heavy reasoning. */
+    defaultModel: string;
+    /** Lighter model for cheap/fast phases (planner, classifier, intent gate). */
+    lightModel: string;
+    /** Context window in tokens. Drives the budget tracker's default. */
+    contextLength: number;
+}
+export declare function loadInferenceConfig(overrides?: Partial<InferenceConfig>): InferenceConfig;
+/**
+ * Build an OpenAI client pointed at the configured endpoint.
+ * Uses the standard `openai` SDK; works against any /v1/chat/completions service.
+ */
+export declare function createInferenceClient(overrides?: Partial<InferenceConfig>): OpenAI;
+//# sourceMappingURL=inference.d.ts.map

package/dist/inference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inference.d.ts","sourceRoot":"","sources":["../src/inference.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,MAAM,MAAM,QAAQ,CAAC;AAE5B,MAAM,WAAW,eAAe;IAC9B,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,YAAY,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,UAAU,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,aAAa,EAAE,MAAM,CAAC;CACvB;AAMD,wBAAgB,mBAAmB,CAAC,SAAS,GAAE,OAAO,CAAC,eAAe,CAAM,GAAG,eAAe,CAU7F;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,GAAE,OAAO,CAAC,eAAe,CAAM,GAAG,MAAM,CAMtF"}

package/dist/inference.js

@@ -0,0 +1,34 @@
+/**
+ * Inference provider configuration.
+ *
+ * Single source of truth for which OpenAI-compatible endpoint we hit. Reads
+ * from env by default; downstream apps can pass overrides for testing or to
+ * point a single process at multiple providers.
+ */
+import OpenAI from 'openai';
+const DEFAULT_BASE_URL = 'http://localhost:8000/v1';
+const DEFAULT_MODEL = 'qwen3.6-27b';
+const DEFAULT_CONTEXT_LENGTH = 131_072;
+export function loadInferenceConfig(overrides = {}) {
+    const defaultModel = process.env.INFERENCE_MODEL ?? DEFAULT_MODEL;
+    return {
+        baseUrl: process.env.INFERENCE_BASE_URL ?? DEFAULT_BASE_URL,
+        apiKey: process.env.INFERENCE_API_KEY ?? 'not-needed-for-local-vllm',
+        defaultModel,
+        lightModel: process.env.INFERENCE_MODEL_LIGHT ?? defaultModel,
+        contextLength: Number(process.env.INFERENCE_CONTEXT_LENGTH ?? DEFAULT_CONTEXT_LENGTH),
+        ...overrides,
+    };
+}
+/**
+ * Build an OpenAI client pointed at the configured endpoint.
+ * Uses the standard `openai` SDK; works against any /v1/chat/completions service.
+ */
+export function createInferenceClient(overrides = {}) {
+    const config = loadInferenceConfig(overrides);
+    return new OpenAI({
+        baseURL: config.baseUrl,
+        apiKey: config.apiKey,
+    });
+}
+//# sourceMappingURL=inference.js.map

package/dist/inference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inference.js","sourceRoot":"","sources":["../src/inference.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,MAAM,MAAM,QAAQ,CAAC;AAe5B,MAAM,gBAAgB,GAAG,0BAA0B,CAAC;AACpD,MAAM,aAAa,GAAG,aAAa,CAAC;AACpC,MAAM,sBAAsB,GAAG,OAAO,CAAC;AAEvC,MAAM,UAAU,mBAAmB,CAAC,YAAsC,EAAE;IAC1E,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,aAAa,CAAC;IAClE,OAAO;QACL,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,gBAAgB;QAC3D,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,2BAA2B;QACpE,YAAY;QACZ,UAAU,EAAE,OAAO,CAAC,GAAG,CAAC,qBAAqB,IAAI,YAAY;QAC7D,aAAa,EAAE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,wBAAwB,IAAI,sBAAsB,CAAC;QACrF,GAAG,SAAS;KACb,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,YAAsC,EAAE;IAC5E,MAAM,MAAM,GAAG,mBAAmB,CAAC,SAAS,CAAC,CAAC;IAC9C,OAAO,IAAI,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,MAAM,EAAE,MAAM,CAAC,MAAM;KACtB,CAAC,CAAC;AACL,CAAC"}

package/dist/messages.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Internal message representation.
+ *
+ * thread-phase uses its own Message shape so the framework isn't coupled to
+ * either Anthropic's content-block model or OpenAI's tool-call model.
+ * Translation to/from the wire format happens at the inference boundary
+ * (see agent-runner.ts).
+ *
+ * Shape choice: closer to OpenAI than Anthropic, because:
+ * - tool_calls live on the assistant message as a separate field, not as
+ *   embedded content blocks.
+ * - tool results are their own role:'tool' messages with a tool_call_id link.
+ * This matches vLLM / Ollama / llama.cpp / OpenAI all natively, and the
+ * Anthropic SDK can be adapted at the boundary if ever needed.
+ */
+export interface ToolCall {
+    /** Unique id for this call. Used to match tool result messages back to the call. */
+    id: string;
+    /** Tool name from the registered ToolDefinition. */
+    name: string;
+    /** Parsed arguments. The framework parses JSON from the wire and passes structured args. */
+    input: Record<string, unknown>;
+}
+export interface SystemMessage {
+    role: 'system';
+    content: string;
+}
+export interface UserMessage {
+    role: 'user';
+    content: string;
+}
+export interface AssistantMessage {
+    role: 'assistant';
+    /** May be empty string when the assistant only emitted tool calls. */
+    content: string;
+    /** Empty array when no tool calls were made. */
+    toolCalls: ToolCall[];
+}
+export interface ToolResultMessage {
+    role: 'tool';
+    /** Must match a ToolCall.id from a prior assistant message. */
+    toolCallId: string;
+    content: string;
+}
+export type Message = SystemMessage | UserMessage | AssistantMessage | ToolResultMessage;
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    /** JSON Schema (object). Translated to OpenAI's `function.parameters` at the boundary. */
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+        additionalProperties?: boolean;
+    };
+}
+export interface ToolResult {
+    toolCallId: string;
+    content: string;
+}
+export interface ToolExecutor {
+    execute(name: string, toolCallId: string, args: Record<string, unknown>): Promise<ToolResult>;
+}
+//# sourceMappingURL=messages.d.ts.map

package/dist/messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH,MAAM,WAAW,QAAQ;IACvB,oFAAoF;IACpF,EAAE,EAAE,MAAM,CAAC;IACX,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,4FAA4F;IAC5F,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAMD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,QAAQ,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,WAAW,CAAC;IAClB,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,SAAS,EAAE,QAAQ,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,OAAO,GAAG,aAAa,GAAG,WAAW,GAAG,gBAAgB,GAAG,iBAAiB,CAAC;AAMzF,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,0FAA0F;IAC1F,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;QACpB,oBAAoB,CAAC,EAAE,OAAO,CAAC;KAChC,CAAC;CACH;AAMD,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CAC/F"}

package/dist/messages.js

@@ -0,0 +1,17 @@
+/**
+ * Internal message representation.
+ *
+ * thread-phase uses its own Message shape so the framework isn't coupled to
+ * either Anthropic's content-block model or OpenAI's tool-call model.
+ * Translation to/from the wire format happens at the inference boundary
+ * (see agent-runner.ts).
+ *
+ * Shape choice: closer to OpenAI than Anthropic, because:
+ * - tool_calls live on the assistant message as a separate field, not as
+ *   embedded content blocks.
+ * - tool results are their own role:'tool' messages with a tool_call_id link.
+ * This matches vLLM / Ollama / llama.cpp / OpenAI all natively, and the
+ * Anthropic SDK can be adapted at the boundary if ever needed.
+ */
+export {};
+//# sourceMappingURL=messages.js.map

package/dist/messages.js.map

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

package/dist/orchestrator.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Pipeline orchestrator — runs a list of phases over a shared context.
+ *
+ * Owns the canonical terminal events (`done` / `error`) so phases never have
+ * to emit them themselves. Halts the pipeline cleanly when any phase sets
+ * `ctx.stop`.
+ *
+ * Composition is just an array of phases. Reorder by reordering the array.
+ * Add a phase by including a new entry. No DAG framework, no plugin system.
+ *
+ * Generic over the phases' event type. Downstream apps that parameterize
+ * Phase with a custom TEvent get the same TEvent surfaced through the
+ * orchestrator's stream — but TEvent must be assignable from the
+ * framework's `done`/`error` shapes (see PipelineEvent), so the simplest
+ * downstream pattern is `type MyEvent = PipelineEvent | { type: 'mine' };`.
+ */
+import type { BasePipelineContext, Phase, PipelineEvent } from './phase.js';
+/**
+ * The terminal state of a pipeline run.
+ *
+ * - `completed` — all phases ran to completion.
+ * - `stopped` — a phase set `ctx.stop`; pipeline halted cleanly with that reason.
+ *
+ * Phase exceptions do not produce a summary; they propagate to the caller.
+ * Use `runPipelineToSummary` to wrap the generator and convert throws into
+ * promise rejections (with the original error preserved).
+ */
+export interface PipelineSummary {
+    readonly status: 'completed' | 'stopped';
+    /** Present iff `status === 'stopped'`. The `ctx.stop.reason` value. */
+    readonly reason?: string;
+    /** Total events yielded, including the terminal `done` event. */
+    readonly eventCount: number;
+}
+export interface RunPipelineOptions {
+    /**
+     * AbortSignal observed between phases. If the signal aborts at any point,
+     * `runPipeline` throws an `AbortError` (`name === 'AbortError'`) before
+     * the next phase runs. Phases that want mid-phase cancellation should
+     * observe the signal themselves and unwind cleanly.
+     */
+    signal?: AbortSignal;
+}
+export declare function runPipeline<TCtx extends BasePipelineContext, TEvent = PipelineEvent>(phases: ReadonlyArray<Phase<TCtx, TEvent>>, ctx: TCtx, options?: RunPipelineOptions): AsyncGenerator<TEvent, void>;
+/**
+ * Consume `runPipeline` to completion and return a typed summary.
+ *
+ * On success, resolves with `{ status, reason?, eventCount }`. Phase
+ * exceptions reject the promise with the original error (the cache is
+ * still cleared via the generator's `finally`).
+ *
+ * Use this when you want a single `await` for the whole pipeline rather
+ * than iterating events yourself.
+ */
+export declare function runPipelineToSummary<TCtx extends BasePipelineContext, TEvent extends PipelineEvent = PipelineEvent>(phases: ReadonlyArray<Phase<TCtx, TEvent>>, ctx: TCtx, options?: RunPipelineOptions): Promise<PipelineSummary>;
+//# sourceMappingURL=orchestrator.d.ts.map

package/dist/orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../src/orchestrator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE5E;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;IACzC,uEAAuE;IACvE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,wBAAuB,WAAW,CAChC,IAAI,SAAS,mBAAmB,EAChC,MAAM,GAAG,aAAa,EAEtB,MAAM,EAAE,aAAa,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,EAC1C,GAAG,EAAE,IAAI,EACT,OAAO,CAAC,EAAE,kBAAkB,GAC3B,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,CAqB9B;AAED;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,SAAS,mBAAmB,EAChC,MAAM,SAAS,aAAa,GAAG,aAAa,EAE5C,MAAM,EAAE,aAAa,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,EAC1C,GAAG,EAAE,IAAI,EACT,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,eAAe,CAAC,CAY1B"}

package/dist/orchestrator.js

@@ -0,0 +1,62 @@
+/**
+ * Pipeline orchestrator — runs a list of phases over a shared context.
+ *
+ * Owns the canonical terminal events (`done` / `error`) so phases never have
+ * to emit them themselves. Halts the pipeline cleanly when any phase sets
+ * `ctx.stop`.
+ *
+ * Composition is just an array of phases. Reorder by reordering the array.
+ * Add a phase by including a new entry. No DAG framework, no plugin system.
+ *
+ * Generic over the phases' event type. Downstream apps that parameterize
+ * Phase with a custom TEvent get the same TEvent surfaced through the
+ * orchestrator's stream — but TEvent must be assignable from the
+ * framework's `done`/`error` shapes (see PipelineEvent), so the simplest
+ * downstream pattern is `type MyEvent = PipelineEvent | { type: 'mine' };`.
+ */
+export async function* runPipeline(phases, ctx, options) {
+    const signal = options?.signal;
+    try {
+        for (const phase of phases) {
+            if (signal?.aborted) {
+                const reason = signal.reason ?? 'aborted';
+                const err = new Error(`runPipeline aborted: ${reason}`);
+                err.name = 'AbortError';
+                throw err;
+            }
+            yield* phase.run(ctx);
+            if (ctx.stop) {
+                yield { type: 'done', reason: ctx.stop.reason };
+                return;
+            }
+        }
+        yield { type: 'done' };
+    }
+    finally {
+        ctx.cache.clear();
+    }
+}
+/**
+ * Consume `runPipeline` to completion and return a typed summary.
+ *
+ * On success, resolves with `{ status, reason?, eventCount }`. Phase
+ * exceptions reject the promise with the original error (the cache is
+ * still cleared via the generator's `finally`).
+ *
+ * Use this when you want a single `await` for the whole pipeline rather
+ * than iterating events yourself.
+ */
+export async function runPipelineToSummary(phases, ctx, options) {
+    let eventCount = 0;
+    let stopReason;
+    for await (const event of runPipeline(phases, ctx, options)) {
+        eventCount++;
+        if (event.type === 'done') {
+            stopReason = event.reason;
+        }
+    }
+    return stopReason !== undefined
+        ? { status: 'stopped', reason: stopReason, eventCount }
+        : { status: 'completed', eventCount };
+}
+//# sourceMappingURL=orchestrator.js.map

package/dist/orchestrator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator.js","sourceRoot":"","sources":["../src/orchestrator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAgCH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,WAAW,CAIhC,MAA0C,EAC1C,GAAS,EACT,OAA4B;IAE5B,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,CAAC;IAC/B,IAAI,CAAC;QACH,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;gBACpB,MAAM,MAAM,GACT,MAAM,CAAC,MAA6B,IAAI,SAAS,CAAC;gBACrD,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,wBAAwB,MAAM,EAAE,CAAC,CAAC;gBACxD,GAAG,CAAC,IAAI,GAAG,YAAY,CAAC;gBACxB,MAAM,GAAG,CAAC;YACZ,CAAC;YACD,KAAK,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACtB,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;gBACb,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,MAAM,EAAuB,CAAC;gBACrE,OAAO;YACT,CAAC;QACH,CAAC;QACD,MAAM,EAAE,IAAI,EAAE,MAAM,EAAuB,CAAC;IAC9C,CAAC;YAAS,CAAC;QACT,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACpB,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAIxC,MAA0C,EAC1C,GAAS,EACT,OAA4B;IAE5B,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,UAA8B,CAAC;IACnC,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,WAAW,CAAe,MAAM,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,CAAC;QAC1E,UAAU,EAAE,CAAC;QACb,IAAK,KAAuB,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YAC7C,UAAU,GAAI,KAA6B,CAAC,MAAM,CAAC;QACrD,CAAC;IACH,CAAC;IACD,OAAO,UAAU,KAAK,SAAS;QAC7B,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE;QACvD,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC;AAC1C,CAAC"}

package/dist/patterns/bounded-fanout-of.d.ts

@@ -0,0 +1,61 @@
+/**
+ * `boundedFanoutOf` — fan an `AgentAdapter` over N items with capped
+ * concurrency, with automatic event-bus propagation so every parallel
+ * adapter run lands events on one shared bus.
+ *
+ * Shape captured: same as `boundedFanout`, but the per-item runner is an
+ * adapter + buildConfig pair instead of a free function. The adapter's
+ * canonical AgentEvents — including events from all N parallel runs —
+ * fan into one `options.eventBus` for downstream consumers (JobStore,
+ * SSE, audit log). Cancellation propagates from `options.signal` to
+ * every in-flight adapter call.
+ *
+ * When to reach for this: you have a list of items, you want to run a
+ * pre-built agent (claude code, hermes, anthropic) on each, with capped
+ * concurrency, and you want a single event stream for the whole batch.
+ *
+ * When NOT to use: when you control the per-item runner directly (no
+ * adapter abstraction in play), reach for `boundedFanout` — its callback
+ * form is more direct. When you have one item, just call the adapter
+ * directly.
+ *
+ * @internal — exported via thread-phase/patterns
+ */
+import type { AgentAdapterMeta, AgentEventBus, AgentRunResult } from '../agents/protocol.js';
+/** Per-item failure handling. Mirrors boundedFanout's mode. @internal */
+export type BoundedFanoutOfMode = 'fail-fast' | 'collect';
+/** @internal */
+export interface BoundedFanoutOfOptions<TItem, TConfig> {
+    items: ReadonlyArray<TItem>;
+    concurrency: number;
+    adapter: AgentAdapterMeta<TConfig>;
+    buildConfig: (item: TItem, index: number) => TConfig;
+    signal?: AbortSignal;
+    /** Shared event bus — every per-item adapter run mirrors events here. */
+    eventBus?: AgentEventBus;
+    /** Optional traceId propagated into each adapter's options.traceId. */
+    traceId?: string;
+    /** Default 'fail-fast'. */
+    mode?: BoundedFanoutOfMode;
+    /** Called when an item's adapter result is in. Synchronous-only. */
+    onItemEnd?: (item: TItem, index: number, result: AgentRunResult) => void;
+    /** Called when fail-fast is triggered. The first failing index/result is passed. */
+    onItemError?: (item: TItem, index: number, result: AgentRunResult) => void;
+}
+/**
+ * Run an adapter over N items with capped concurrency. Returns results in
+ * input order. In `collect` mode, individual failures are stored as
+ * error results (finishReason: 'error') and the batch completes. In
+ * `fail-fast` (default), the first failure cancels in-flight runs and
+ * the function rejects with an Error wrapping the failed item.
+ *
+ * @internal
+ */
+export declare function boundedFanoutOf<TItem, TConfig>(opts: BoundedFanoutOfOptions<TItem, TConfig>): Promise<AgentRunResult[]>;
+/** @internal */
+export declare class BoundedFanoutOfError extends Error {
+    itemIndex: number;
+    result: AgentRunResult;
+    constructor(itemIndex: number, result: AgentRunResult);
+}
+//# sourceMappingURL=bounded-fanout-of.d.ts.map

package/dist/patterns/bounded-fanout-of.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bounded-fanout-of.d.ts","sourceRoot":"","sources":["../../src/patterns/bounded-fanout-of.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,aAAa,EAEb,cAAc,EACf,MAAM,uBAAuB,CAAC;AAE/B,yEAAyE;AACzE,MAAM,MAAM,mBAAmB,GAAG,WAAW,GAAG,SAAS,CAAC;AAE1D,gBAAgB;AAChB,MAAM,WAAW,sBAAsB,CAAC,KAAK,EAAE,OAAO;IACpD,KAAK,EAAE,aAAa,CAAC,KAAK,CAAC,CAAC;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAC;IACnC,WAAW,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;IACrD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2BAA2B;IAC3B,IAAI,CAAC,EAAE,mBAAmB,CAAC;IAC3B,oEAAoE;IACpE,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,KAAK,IAAI,CAAC;IACzE,oFAAoF;IACpF,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,KAAK,IAAI,CAAC;CAC5E;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,OAAO,EAClD,IAAI,EAAE,sBAAsB,CAAC,KAAK,EAAE,OAAO,CAAC,GAC3C,OAAO,CAAC,cAAc,EAAE,CAAC,CA4G3B;AAED,gBAAgB;AAChB,qBAAa,oBAAqB,SAAQ,KAAK;IAEpC,SAAS,EAAE,MAAM;IACjB,MAAM,EAAE,cAAc;gBADtB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,cAAc;CAKhC"}

package/dist/patterns/bounded-fanout-of.js

@@ -0,0 +1,142 @@
+/**
+ * `boundedFanoutOf` — fan an `AgentAdapter` over N items with capped
+ * concurrency, with automatic event-bus propagation so every parallel
+ * adapter run lands events on one shared bus.
+ *
+ * Shape captured: same as `boundedFanout`, but the per-item runner is an
+ * adapter + buildConfig pair instead of a free function. The adapter's
+ * canonical AgentEvents — including events from all N parallel runs —
+ * fan into one `options.eventBus` for downstream consumers (JobStore,
+ * SSE, audit log). Cancellation propagates from `options.signal` to
+ * every in-flight adapter call.
+ *
+ * When to reach for this: you have a list of items, you want to run a
+ * pre-built agent (claude code, hermes, anthropic) on each, with capped
+ * concurrency, and you want a single event stream for the whole batch.
+ *
+ * When NOT to use: when you control the per-item runner directly (no
+ * adapter abstraction in play), reach for `boundedFanout` — its callback
+ * form is more direct. When you have one item, just call the adapter
+ * directly.
+ *
+ * @internal — exported via thread-phase/patterns
+ */
+/**
+ * Run an adapter over N items with capped concurrency. Returns results in
+ * input order. In `collect` mode, individual failures are stored as
+ * error results (finishReason: 'error') and the batch completes. In
+ * `fail-fast` (default), the first failure cancels in-flight runs and
+ * the function rejects with an Error wrapping the failed item.
+ *
+ * @internal
+ */
+export async function boundedFanoutOf(opts) {
+    const items = opts.items;
+    if (items.length === 0)
+        return [];
+    const concurrency = Math.max(1, Math.min(opts.concurrency, items.length));
+    const mode = opts.mode ?? 'fail-fast';
+    const results = new Array(items.length);
+    const inFlight = new Set();
+    let failed = null;
+    let cursor = 0;
+    const abortAllInFlight = () => {
+        for (const entry of inFlight) {
+            entry.controller.abort();
+            entry.run.abort('boundedFanoutOf fail-fast');
+        }
+    };
+    const worker = async () => {
+        while (true) {
+            if (failed)
+                return;
+            if (opts.signal?.aborted)
+                return;
+            const i = cursor++;
+            if (i >= items.length)
+                return;
+            const item = items[i];
+            const itemController = new AbortController();
+            const compositeSignal = opts.signal
+                ? AbortSignal.any([opts.signal, itemController.signal])
+                : itemController.signal;
+            const config = opts.buildConfig(item, i);
+            const run = opts.adapter.adapter(config, {
+                signal: compositeSignal,
+                eventBus: opts.eventBus,
+                traceId: opts.traceId,
+            });
+            const entry = { controller: itemController, run };
+            inFlight.add(entry);
+            // The adapter's events iterable is intentionally NOT consumed here.
+            // The event bus is the multi-subscriber seam; double-iteration would
+            // break the single-consumer invariant. Awaiting `result` is sufficient
+            // to start lazy adapters.
+            let result;
+            try {
+                result = await run.result;
+            }
+            finally {
+                inFlight.delete(entry);
+            }
+            if (result.finishReason === 'error') {
+                if (mode === 'fail-fast') {
+                    if (!failed) {
+                        failed = { index: i, result };
+                        opts.onItemError?.(item, i, result);
+                        abortAllInFlight();
+                    }
+                    return;
+                }
+                // collect: store and keep going.
+                results[i] = result;
+                opts.onItemEnd?.(item, i, result);
+                continue;
+            }
+            results[i] = result;
+            opts.onItemEnd?.(item, i, result);
+        }
+    };
+    const workers = [];
+    for (let w = 0; w < concurrency; w++)
+        workers.push(worker());
+    await Promise.all(workers);
+    if (failed) {
+        const f = failed;
+        throw new BoundedFanoutOfError(f.index, f.result);
+    }
+    // collect mode may still have undefined slots if the outer signal aborted
+    // before some items were dispatched. Adapters honoring `compositeSignal`
+    // produce `finishReason: 'aborted'` results for items that started post-
+    // abort; items that never started leave the slot undefined. Fill those
+    // with a synthetic aborted result so the returned array stays position-
+    // stable with the input items array.
+    if (opts.signal?.aborted) {
+        for (let i = 0; i < items.length; i++) {
+            if (results[i] === undefined) {
+                results[i] = syntheticAbortedResult();
+            }
+        }
+    }
+    return results;
+}
+/** @internal */
+export class BoundedFanoutOfError extends Error {
+    itemIndex;
+    result;
+    constructor(itemIndex, result) {
+        super(`boundedFanoutOf failed at item ${itemIndex}: ${result.finishReason}`);
+        this.itemIndex = itemIndex;
+        this.result = result;
+        this.name = 'BoundedFanoutOfError';
+    }
+}
+function syntheticAbortedResult() {
+    return {
+        text: '',
+        finishReason: 'aborted',
+        usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+        executedToolCalls: [],
+    };
+}
+//# sourceMappingURL=bounded-fanout-of.js.map

package/dist/patterns/bounded-fanout-of.js.map

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