@autonome-research/thread-phase 3.0.0

package/dist/agents/turn-accumulator.js

@@ -0,0 +1,150 @@
+/**
+ * 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
+ */
+/** @internal */
+export class TurnAccumulator {
+    emit;
+    source;
+    traceId;
+    turnText = '';
+    currentTurnToolCalls = 0;
+    pending = null;
+    constructor(emit, source, traceId) {
+        this.emit = emit;
+        this.source = source;
+        this.traceId = traceId;
+    }
+    /**
+     * 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) {
+        if (this.pending)
+            this.flush();
+        this.turnText += delta;
+        this.emit({ type: 'text', source: this.source, traceId: this.traceId, delta });
+    }
+    /**
+     * Emit a thinking (reasoning) delta. Does NOT flush a pending turn —
+     * reasoning is intra-turn content, not a turn boundary signal.
+     */
+    thinking(delta) {
+        this.emit({ type: 'thinking', source: this.source, traceId: this.traceId, delta });
+    }
+    /**
+     * 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, name, input) {
+        this.currentTurnToolCalls += 1;
+        this.emit({ type: 'tool_call', source: this.source, traceId: this.traceId, id, name, input });
+    }
+    /** Emit a tool result. Does not affect pending-turn state. */
+    toolResult(id, name, output, isError) {
+        this.emit({
+            type: 'tool_result',
+            source: this.source,
+            traceId: this.traceId,
+            id,
+            name,
+            output,
+            isError,
+        });
+    }
+    /**
+     * 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, payload) {
+        this.emit({ type: 'native', source: this.source, traceId: this.traceId, kind, payload });
+    }
+    /**
+     * 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) {
+        this.pending = { text: this.turnText, openingToolCallCount: this.currentTurnToolCalls, usage };
+        this.turnText = '';
+    }
+    /**
+     * 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) {
+        if (this.pending)
+            this.flush();
+        this.emit({
+            type: 'turn_end',
+            source: this.source,
+            traceId: this.traceId,
+            assistantText: this.turnText,
+            usage,
+            toolCallCount: this.currentTurnToolCalls,
+        });
+        this.turnText = '';
+        this.currentTurnToolCalls = 0;
+    }
+    /**
+     * 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() {
+        this.flush();
+    }
+    flush() {
+        if (!this.pending)
+            return;
+        const turnToolCalls = this.currentTurnToolCalls - this.pending.openingToolCallCount;
+        this.emit({
+            type: 'turn_end',
+            source: this.source,
+            traceId: this.traceId,
+            assistantText: this.pending.text,
+            usage: this.pending.usage,
+            toolCallCount: turnToolCalls,
+        });
+        this.pending = null;
+        this.currentTurnToolCalls = 0;
+    }
+}
+//# sourceMappingURL=turn-accumulator.js.map

package/dist/agents/turn-accumulator.js.map

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

package/dist/agents/with-memory.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Decorate an `AgentAdapter` with automatic memory recall + remember
+ * via a caller-supplied `MemoryProvider`.
+ *
+ * The wrapper:
+ *
+ *   1. Reads `runOptions.memoryProvider` at call time. If none is in
+ *      scope, the wrapper is a no-op pass-through — caller can decorate
+ *      an adapter once and decide per-call whether memory applies.
+ *   2. Before invoking the inner adapter, calls `provider.recall(scope, query?)`
+ *      and splices the recalled string into the config via the
+ *      `inject` callback. The inject signature is adapter-specific
+ *      because each adapter shapes its prompt field differently
+ *      (config.systemPrompt vs config.instructions vs config.prompt vs
+ *      runnerOptions etc.).
+ *   3. Tees every emitted event into a capture buffer (for the later
+ *      `remember` call) AND into the caller's `options.eventBus` if
+ *      present. Pass-through; no events added or dropped.
+ *   4. After the inner run's `agent_end`, calls `provider.remember(scope, captured)`
+ *      before resolving the wrapped run's `result`. Failures of either
+ *      `recall` or `remember` surface as `native` events on the bus
+ *      (`memory:recall_failed` / `memory:remember_failed`); the run
+ *      itself never fails because of memory.
+ *
+ * @internal
+ */
+import type { AgentAdapterMeta, MemoryScope } from './protocol.js';
+/** @internal */
+export interface WithMemoryOptions<TConfig> {
+    /** Identity scope (`userId` required; `appId` / `sessionId` optional). */
+    scope: MemoryScope;
+    /**
+     * Splice the recalled memory string into the inner adapter's config.
+     * Each adapter shapes its prompt field differently; the caller knows
+     * the adapter type and where the memory belongs.
+     */
+    inject: (config: TConfig, memory: string) => TConfig;
+    /**
+     * Optional: derive a query string from the config to refine recall.
+     * Useful when the recall backend supports semantic search (Honcho's
+     * `.chat()` interprets the query as the question being asked).
+     * Default: no query (provider gets `undefined`).
+     */
+    query?: (config: TConfig) => string | undefined;
+}
+/**
+ * Wrap an adapter so each invocation auto-recalls memory before the run
+ * and auto-remembers events after. Behavior is gated on the presence
+ * of `options.memoryProvider` at call time — no provider, no memory
+ * activity.
+ *
+ * @internal
+ */
+export declare function withMemory<TConfig>(meta: AgentAdapterMeta<TConfig>, opts: WithMemoryOptions<TConfig>): AgentAdapterMeta<TConfig>;
+//# sourceMappingURL=with-memory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"with-memory.d.ts","sourceRoot":"","sources":["../../src/agents/with-memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,KAAK,EACV,gBAAgB,EAKhB,WAAW,EACZ,MAAM,eAAe,CAAC;AAGvB,gBAAgB;AAChB,MAAM,WAAW,iBAAiB,CAAC,OAAO;IACxC,0EAA0E;IAC1E,KAAK,EAAE,WAAW,CAAC;IACnB;;;;OAIG;IACH,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;IACrD;;;;;OAKG;IACH,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,CAAC;CACjD;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAChC,IAAI,EAAE,gBAAgB,CAAC,OAAO,CAAC,EAC/B,IAAI,EAAE,iBAAiB,CAAC,OAAO,CAAC,GAC/B,gBAAgB,CAAC,OAAO,CAAC,CAyH3B"}

package/dist/agents/with-memory.js

@@ -0,0 +1,155 @@
+/**
+ * Decorate an `AgentAdapter` with automatic memory recall + remember
+ * via a caller-supplied `MemoryProvider`.
+ *
+ * The wrapper:
+ *
+ *   1. Reads `runOptions.memoryProvider` at call time. If none is in
+ *      scope, the wrapper is a no-op pass-through — caller can decorate
+ *      an adapter once and decide per-call whether memory applies.
+ *   2. Before invoking the inner adapter, calls `provider.recall(scope, query?)`
+ *      and splices the recalled string into the config via the
+ *      `inject` callback. The inject signature is adapter-specific
+ *      because each adapter shapes its prompt field differently
+ *      (config.systemPrompt vs config.instructions vs config.prompt vs
+ *      runnerOptions etc.).
+ *   3. Tees every emitted event into a capture buffer (for the later
+ *      `remember` call) AND into the caller's `options.eventBus` if
+ *      present. Pass-through; no events added or dropped.
+ *   4. After the inner run's `agent_end`, calls `provider.remember(scope, captured)`
+ *      before resolving the wrapped run's `result`. Failures of either
+ *      `recall` or `remember` surface as `native` events on the bus
+ *      (`memory:recall_failed` / `memory:remember_failed`); the run
+ *      itself never fails because of memory.
+ *
+ * @internal
+ */
+import { createEventBus } from './event-bus.js';
+import { serializeError } from './serialize-error.js';
+/**
+ * Wrap an adapter so each invocation auto-recalls memory before the run
+ * and auto-remembers events after. Behavior is gated on the presence
+ * of `options.memoryProvider` at call time — no provider, no memory
+ * activity.
+ *
+ * @internal
+ */
+export function withMemory(meta, opts) {
+    return {
+        id: meta.id,
+        capabilities: meta.capabilities,
+        adapter: (config, runOptions) => {
+            const provider = runOptions?.memoryProvider;
+            if (!provider) {
+                // No provider in scope — transparent passthrough.
+                return meta.adapter(config, runOptions);
+            }
+            // Inner bus captures every event for the eventual remember() call
+            // AND mirrors to the caller's bus (if any). Pass-through bus, not
+            // a replacement.
+            const innerBus = createEventBus();
+            const captured = [];
+            const userBus = runOptions?.eventBus;
+            innerBus.on((event) => {
+                captured.push(event);
+                if (userBus) {
+                    try {
+                        userBus.emit(event);
+                    }
+                    catch {
+                        // bus implementation is responsible for its own subscriber errors
+                    }
+                }
+            });
+            // Lazy start: recall + inject must complete before the inner adapter
+            // is invoked. We can't await here (adapter must return synchronously)
+            // so the inner run resolves on first events-iteration or result-await
+            // via the standard memoized-promise pattern.
+            let innerRunPromise = null;
+            const innerOptions = {
+                ...(runOptions ?? {}),
+                eventBus: innerBus,
+            };
+            const getInnerRun = () => {
+                if (innerRunPromise)
+                    return innerRunPromise;
+                innerRunPromise = (async () => {
+                    let recalled = '';
+                    try {
+                        const query = opts.query?.(config);
+                        recalled = await provider.recall(opts.scope, query);
+                    }
+                    catch (err) {
+                        innerBus.emit({
+                            type: 'native',
+                            source: meta.id,
+                            kind: 'memory:recall_failed',
+                            payload: { error: serializeError(err) },
+                        });
+                    }
+                    const effective = opts.inject(config, recalled);
+                    return meta.adapter(effective, innerOptions);
+                })();
+                return innerRunPromise;
+            };
+            // Single-consumer guard on the wrapped events iterable. The inner
+            // run also guards its own events; the wrapper's guard catches the
+            // case where the wrapped run is iterated twice before inner exists.
+            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;
+                    let innerIterator = null;
+                    const ensureIterator = async () => {
+                        if (innerIterator)
+                            return innerIterator;
+                        const run = await getInnerRun();
+                        innerIterator = run.events[Symbol.asyncIterator]();
+                        return innerIterator;
+                    };
+                    return {
+                        async next() {
+                            const it = await ensureIterator();
+                            return it.next();
+                        },
+                        async return() {
+                            if (innerIterator?.return) {
+                                return innerIterator.return();
+                            }
+                            return { value: undefined, done: true };
+                        },
+                    };
+                },
+            };
+            const result = (async () => {
+                const run = await getInnerRun();
+                const inner = await run.result;
+                try {
+                    await provider.remember(opts.scope, captured);
+                }
+                catch (err) {
+                    innerBus.emit({
+                        type: 'native',
+                        source: meta.id,
+                        kind: 'memory:remember_failed',
+                        payload: { error: serializeError(err) },
+                    });
+                }
+                return inner;
+            })();
+            return {
+                events,
+                result,
+                abort(reason) {
+                    // Propagate abort once the inner run exists. If recall is still
+                    // in flight, the abort takes effect right after recall resolves.
+                    void getInnerRun().then((r) => r.abort(reason));
+                },
+            };
+        },
+    };
+}
+//# sourceMappingURL=with-memory.js.map

package/dist/agents/with-memory.js.map

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

package/dist/agents/with-thread.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Decorate an `AgentAdapter` with automatic `Thread` wiring:
+ *
+ *   1. Reads `thread.resumeTokens[meta.id]` and splices it into the
+ *      inner config via the `applyResume` callback. Adapters whose
+ *      resumption field name differs (anthropic has none, codex uses
+ *      `previousResponseId`, ACP-based uses `resumeSessionId`, etc.)
+ *      provide their own splice.
+ *   2. Tees every event into `thread.events`. The thread becomes a
+ *      durable log of the conversation that flows between phases.
+ *   3. When a fresh `resumeToken` appears on `agent_start` or `agent_end`,
+ *      writes it back to `thread.resumeTokens[meta.id]` so subsequent
+ *      calls with the same thread auto-resume.
+ *
+ * Unlike `withMemory`, the thread is passed explicitly to the wrapper
+ * factory — `Thread` is a per-pipeline primitive, `MemoryProvider` is
+ * a cross-pipeline backend. Thread mutation happens through the same
+ * `appendEvent` / `setResumeToken` helpers callers would use manually.
+ *
+ * @internal
+ */
+import type { AgentAdapterMeta, ResumeToken } from './protocol.js';
+import { type Thread } from './thread.js';
+/** @internal */
+export interface WithThreadOptions<TConfig> {
+    /**
+     * Splice the thread's per-adapter resume token into the inner config.
+     * Called only when `thread.resumeTokens[meta.id]` is present. Adapters
+     * without resumption (anthropicAgent) omit this — the wrapper still
+     * mirrors events into the thread, just doesn't try to inject a resume.
+     */
+    applyResume?: (config: TConfig, resumeToken: ResumeToken) => TConfig;
+}
+/**
+ * Wrap an adapter so every invocation reads/writes a shared `Thread`.
+ * Events get appended; new resume tokens get persisted; existing tokens
+ * get spliced into the next run's config.
+ *
+ * Mutation is in-place on the supplied thread. The wrapper does not
+ * defensively clone — caller controls the thread's lifetime.
+ *
+ * @internal
+ */
+export declare function withThread<TConfig>(meta: AgentAdapterMeta<TConfig>, thread: Thread, opts?: WithThreadOptions<TConfig>): AgentAdapterMeta<TConfig>;
+//# sourceMappingURL=with-thread.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"with-thread.d.ts","sourceRoot":"","sources":["../../src/agents/with-thread.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EACV,gBAAgB,EAGhB,WAAW,EACZ,MAAM,eAAe,CAAC;AACvB,OAAO,EAIL,KAAK,MAAM,EACZ,MAAM,aAAa,CAAC;AAErB,gBAAgB;AAChB,MAAM,WAAW,iBAAiB,CAAC,OAAO;IACxC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,WAAW,KAAK,OAAO,CAAC;CACtE;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAChC,IAAI,EAAE,gBAAgB,CAAC,OAAO,CAAC,EAC/B,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,iBAAiB,CAAC,OAAO,CAAM,GACpC,gBAAgB,CAAC,OAAO,CAAC,CAuC3B"}

package/dist/agents/with-thread.js

@@ -0,0 +1,70 @@
+/**
+ * Decorate an `AgentAdapter` with automatic `Thread` wiring:
+ *
+ *   1. Reads `thread.resumeTokens[meta.id]` and splices it into the
+ *      inner config via the `applyResume` callback. Adapters whose
+ *      resumption field name differs (anthropic has none, codex uses
+ *      `previousResponseId`, ACP-based uses `resumeSessionId`, etc.)
+ *      provide their own splice.
+ *   2. Tees every event into `thread.events`. The thread becomes a
+ *      durable log of the conversation that flows between phases.
+ *   3. When a fresh `resumeToken` appears on `agent_start` or `agent_end`,
+ *      writes it back to `thread.resumeTokens[meta.id]` so subsequent
+ *      calls with the same thread auto-resume.
+ *
+ * Unlike `withMemory`, the thread is passed explicitly to the wrapper
+ * factory — `Thread` is a per-pipeline primitive, `MemoryProvider` is
+ * a cross-pipeline backend. Thread mutation happens through the same
+ * `appendEvent` / `setResumeToken` helpers callers would use manually.
+ *
+ * @internal
+ */
+import { createEventBus } from './event-bus.js';
+import { appendEvent, resumeTokenFor, setResumeToken, } from './thread.js';
+/**
+ * Wrap an adapter so every invocation reads/writes a shared `Thread`.
+ * Events get appended; new resume tokens get persisted; existing tokens
+ * get spliced into the next run's config.
+ *
+ * Mutation is in-place on the supplied thread. The wrapper does not
+ * defensively clone — caller controls the thread's lifetime.
+ *
+ * @internal
+ */
+export function withThread(meta, thread, opts = {}) {
+    return {
+        id: meta.id,
+        capabilities: meta.capabilities,
+        adapter: (config, runOptions) => {
+            const existing = resumeTokenFor(thread, meta.id);
+            const effective = existing && opts.applyResume
+                ? opts.applyResume(config, existing)
+                : config;
+            // Tee events: append to thread, capture lifecycle resume tokens,
+            // then mirror to the caller's bus if one was supplied.
+            const innerBus = createEventBus();
+            const userBus = runOptions?.eventBus;
+            innerBus.on((event) => {
+                appendEvent(thread, event);
+                if ((event.type === 'agent_start' || event.type === 'agent_end') &&
+                    event.resumeToken) {
+                    setResumeToken(thread, meta.id, event.resumeToken);
+                }
+                if (userBus) {
+                    try {
+                        userBus.emit(event);
+                    }
+                    catch {
+                        // bus implementation handles its own subscriber errors
+                    }
+                }
+            });
+            const innerOptions = {
+                ...(runOptions ?? {}),
+                eventBus: innerBus,
+            };
+            return meta.adapter(effective, innerOptions);
+        },
+    };
+}
+//# sourceMappingURL=with-thread.js.map

package/dist/agents/with-thread.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-thread.js","sourceRoot":"","sources":["../../src/agents/with-thread.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAOhD,OAAO,EACL,WAAW,EACX,cAAc,EACd,cAAc,GAEf,MAAM,aAAa,CAAC;AAarB;;;;;;;;;GASG;AACH,MAAM,UAAU,UAAU,CACxB,IAA+B,EAC/B,MAAc,EACd,OAAmC,EAAE;IAErC,OAAO;QACL,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,OAAO,EAAE,CAAC,MAAM,EAAE,UAAU,EAAY,EAAE;YACxC,MAAM,QAAQ,GAAG,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;YACjD,MAAM,SAAS,GAAG,QAAQ,IAAI,IAAI,CAAC,WAAW;gBAC5C,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC;gBACpC,CAAC,CAAC,MAAM,CAAC;YAEX,iEAAiE;YACjE,uDAAuD;YACvD,MAAM,QAAQ,GAAG,cAAc,EAAE,CAAC;YAClC,MAAM,OAAO,GAAG,UAAU,EAAE,QAAQ,CAAC;YACrC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,EAAE;gBACpB,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;gBAC3B,IACE,CAAC,KAAK,CAAC,IAAI,KAAK,aAAa,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW,CAAC;oBAC5D,KAAK,CAAC,WAAW,EACjB,CAAC;oBACD,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;gBACrD,CAAC;gBACD,IAAI,OAAO,EAAE,CAAC;oBACZ,IAAI,CAAC;wBACH,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;oBACtB,CAAC;oBAAC,MAAM,CAAC;wBACP,uDAAuD;oBACzD,CAAC;gBACH,CAAC;YACH,CAAC,CAAC,CAAC;YAEH,MAAM,YAAY,GAAoB;gBACpC,GAAG,CAAC,UAAU,IAAI,EAAE,CAAC;gBACrB,QAAQ,EAAE,QAAQ;aACnB,CAAC;YAEF,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;QAC/C,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/cache.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Pipeline-scoped cache — shared across phases and tool calls within a single
+ * pipeline run. Avoids redundant work when multiple phases (or multiple
+ * parallel agents within a phase) read the same data.
+ *
+ * Created per-pipeline, cleared on completion.
+ *
+ * Namespacing: `cache.namespace('foo')` returns a sub-cache that prefixes all
+ * keys with `foo:`. Use this when two unrelated callers might pick the same
+ * key (e.g. `chunk:0`) to keep their entries isolated. Sub-caches share the
+ * underlying store, so `clear()` and `size` see all entries; `clear()` on a
+ * sub-cache only drops keys in that namespace.
+ */
+export declare class PipelineCache {
+    private readonly store;
+    private readonly prefix;
+    constructor(store?: Map<string, unknown>, prefix?: string);
+    private k;
+    get<T>(key: string): T | undefined;
+    set(key: string, value: unknown): void;
+    has(key: string): boolean;
+    /** Cache-or-fetch. */
+    getOrFetch<T>(key: string, fetcher: () => Promise<T>): Promise<T>;
+    /**
+     * Clear cache entries.
+     *
+     * On the root cache: drops every entry.
+     * On a namespaced sub-cache: drops only entries whose keys start with this
+     * namespace's prefix; entries belonging to the root cache or other
+     * namespaces are untouched.
+     */
+    clear(): void;
+    /**
+     * Total entries in the underlying store, across all namespaces. This is
+     * shared state; a sub-cache reports the same number as the root.
+     */
+    get size(): number;
+    /**
+     * Return a sub-cache that prefixes all keys with `${name}:`. Sub-caches
+     * are cheap (no copy) and share the underlying store.
+     *
+     * Nesting is supported: `cache.namespace('a').namespace('b')` prefixes
+     * with `a:b:`. Empty names are rejected.
+     */
+    namespace(name: string): PipelineCache;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuB;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAE,MAAW;IAK7D,OAAO,CAAC,CAAC;IAIT,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAIlC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAItC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIzB,sBAAsB;IAChB,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAUvE;;;;;;;OAOG;IACH,KAAK,IAAI,IAAI;IAUb;;;OAGG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;;OAMG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa;CAIvC"}

package/dist/cache.js

@@ -0,0 +1,81 @@
+/**
+ * Pipeline-scoped cache — shared across phases and tool calls within a single
+ * pipeline run. Avoids redundant work when multiple phases (or multiple
+ * parallel agents within a phase) read the same data.
+ *
+ * Created per-pipeline, cleared on completion.
+ *
+ * Namespacing: `cache.namespace('foo')` returns a sub-cache that prefixes all
+ * keys with `foo:`. Use this when two unrelated callers might pick the same
+ * key (e.g. `chunk:0`) to keep their entries isolated. Sub-caches share the
+ * underlying store, so `clear()` and `size` see all entries; `clear()` on a
+ * sub-cache only drops keys in that namespace.
+ */
+export class PipelineCache {
+    store;
+    prefix;
+    constructor(store, prefix = '') {
+        this.store = store ?? new Map();
+        this.prefix = prefix;
+    }
+    k(key) {
+        return this.prefix ? `${this.prefix}${key}` : key;
+    }
+    get(key) {
+        return this.store.get(this.k(key));
+    }
+    set(key, value) {
+        this.store.set(this.k(key), value);
+    }
+    has(key) {
+        return this.store.has(this.k(key));
+    }
+    /** Cache-or-fetch. */
+    async getOrFetch(key, fetcher) {
+        const fullKey = this.k(key);
+        if (this.store.has(fullKey)) {
+            return this.store.get(fullKey);
+        }
+        const value = await fetcher();
+        this.store.set(fullKey, value);
+        return value;
+    }
+    /**
+     * Clear cache entries.
+     *
+     * On the root cache: drops every entry.
+     * On a namespaced sub-cache: drops only entries whose keys start with this
+     * namespace's prefix; entries belonging to the root cache or other
+     * namespaces are untouched.
+     */
+    clear() {
+        if (!this.prefix) {
+            this.store.clear();
+            return;
+        }
+        for (const k of [...this.store.keys()]) {
+            if (k.startsWith(this.prefix))
+                this.store.delete(k);
+        }
+    }
+    /**
+     * Total entries in the underlying store, across all namespaces. This is
+     * shared state; a sub-cache reports the same number as the root.
+     */
+    get size() {
+        return this.store.size;
+    }
+    /**
+     * Return a sub-cache that prefixes all keys with `${name}:`. Sub-caches
+     * are cheap (no copy) and share the underlying store.
+     *
+     * Nesting is supported: `cache.namespace('a').namespace('b')` prefixes
+     * with `a:b:`. Empty names are rejected.
+     */
+    namespace(name) {
+        if (!name)
+            throw new Error('PipelineCache.namespace: name must be non-empty');
+        return new PipelineCache(this.store, `${this.prefix}${name}:`);
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,OAAO,aAAa;IACP,KAAK,CAAuB;IAC5B,MAAM,CAAS;IAEhC,YAAY,KAA4B,EAAE,SAAiB,EAAE;QAC3D,IAAI,CAAC,KAAK,GAAG,KAAK,IAAI,IAAI,GAAG,EAAE,CAAC;QAChC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAEO,CAAC,CAAC,GAAW;QACnB,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;IACpD,CAAC;IAED,GAAG,CAAI,GAAW;QAChB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAkB,CAAC;IACtD,CAAC;IAED,GAAG,CAAC,GAAW,EAAE,KAAc;QAC7B,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;IACrC,CAAC;IAED,GAAG,CAAC,GAAW;QACb,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACrC,CAAC;IAED,sBAAsB;IACtB,KAAK,CAAC,UAAU,CAAI,GAAW,EAAE,OAAyB;QACxD,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YAC5B,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAM,CAAC;QACtC,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,OAAO,EAAE,CAAC;QAC9B,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAC/B,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;;;OAOG;IACH,KAAK;QACH,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YACjB,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;YACnB,OAAO;QACT,CAAC;QACD,KAAK,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;YACvC,IAAI,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC;gBAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACtD,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;IAED;;;;;;OAMG;IACH,SAAS,CAAC,IAAY;QACpB,IAAI,CAAC,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;QAC9E,OAAO,IAAI,aAAa,CAAC,IAAI,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,MAAM,GAAG,IAAI,GAAG,CAAC,CAAC;IACjE,CAAC;CACF"}