@esankhan3/anvil-agent-core 0.3.0 → 0.4.0

package/dist/turn-recorder/index.js

@@ -0,0 +1,326 @@
+/**
+ * TurnRecorder — splits one LLM invocation into per-turn sub-effects so
+ * the durable engine can replay tool results and resume mid-stream after
+ * a chain-fallback model swap.
+ *
+ * Effect-name vocabulary (per the v2 ADR §2.1):
+ *   - `turn:<N>:assistant-start`     — request payload (recorded, NOT input-hash-guarded: see startTurn)
+ *   - `turn:<N>:tool_use:<M>`        — intent (name + parsed args)
+ *   - `turn:<N>:tool_result:<M>`     — neutral result; replay short-circuits the executor
+ *   - `turn:<N>:assistant-end`       — completed assistant text + provenance
+ *
+ * Surface note vs ADR §2.5: the ADR sketches recordToolUse / recordToolResult
+ * as two separate calls. That split has no clean replay-vs-execute boundary
+ * through the `effect(name, fn)` interface — once the runtime accepts a fn
+ * for `tool_result:N`, fn already either ran (live) or didn't (replay), and
+ * the caller can't tell from outside. So the implementation collapses to a
+ * single `runTool(turn, name, args, key, exec)` that owns the
+ * intent-record → execute-or-replay → result-record sequence atomically.
+ * Same on-disk shape; cleaner adapter code; ADR §2.5 to be amended in
+ * follow-up.
+ *
+ * NullTurnRecorder factory: pass a `createNullRuntime()`-built runtime to
+ * make every call a no-op pass-through with live execution. Adapters that
+ * haven't been ported through their own H-phase use this default, so the
+ * recorder calls compile and run today without behavior change.
+ */
+const DEFAULT_TOOL_RESULT_CAP_BYTES = 65_536;
+/**
+ * Resolve the persisted-tool-result cap. `ANVIL_DURABLE_MAX_TOOL_RESULT_BYTES`
+ * overrides the 64 KiB default; `0` disables the cap (persist the full result).
+ */
+function toolResultPersistCapBytes() {
+    const raw = process.env.ANVIL_DURABLE_MAX_TOOL_RESULT_BYTES;
+    if (raw === undefined)
+        return DEFAULT_TOOL_RESULT_CAP_BYTES;
+    const n = Number(raw);
+    if (n === 0)
+        return Infinity; // explicit opt-out — persist full payloads
+    return Number.isFinite(n) && n > 0 ? n : DEFAULT_TOOL_RESULT_CAP_BYTES;
+}
+/**
+ * Cap the `content` of a NeutralToolResult for durable storage. Only string
+ * content past the cap is truncated (with a marker); the result keeps a valid
+ * NeutralToolResult shape so resume's message reconstruction still works. The
+ * live caller is unaffected — this runs only on the persisted copy via
+ * `EffectOptions.persistTransform`.
+ */
+function capToolResultForPersist(result) {
+    const cap = toolResultPersistCapBytes();
+    if (cap === Infinity || !result || typeof result !== 'object')
+        return result;
+    const r = result;
+    if (typeof r.content === 'string' && r.content.length > cap) {
+        const omitted = r.content.length - cap;
+        return {
+            ...r,
+            content: r.content.slice(0, cap) +
+                `\n…[${omitted} bytes truncated for durable storage; full output was sent to the model live]`,
+        };
+    }
+    return result;
+}
+const DEFAULT_UUID = () => (globalThis.crypto?.randomUUID?.() ?? fallbackUuid());
+function fallbackUuid() {
+    // Minimal v4 fallback for runtimes without globalThis.crypto.
+    const hex = (n) => n.toString(16).padStart(2, '0');
+    const bytes = new Uint8Array(16);
+    for (let i = 0; i < 16; i++)
+        bytes[i] = Math.floor(Math.random() * 256);
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const h = Array.from(bytes, hex);
+    return `${h.slice(0, 4).join('')}-${h.slice(4, 6).join('')}-${h.slice(6, 8).join('')}-${h.slice(8, 10).join('')}-${h.slice(10, 16).join('')}`;
+}
+export class TurnRecorder {
+    deps;
+    /** Monotonic turn counter, scoped to this recorder (one per adapter.run).
+     *  Seeded from deps.initialTurn so a sendInput-resume recorder continues
+     *  past the prior adapter's turns (§2.5.1). */
+    turnCounter;
+    /** Per-turn tool_use index counter — bumped serially per call. */
+    toolIdxByTurn = new Map();
+    /** Per-turn uuid stash so flushPartial can echo the right one. */
+    turnUuids = new Map();
+    /** Per-turn (model, provider) stash from startTurn so endTurn can
+     *  stamp the assistant-end payload — the H3 cost rollup prices each
+     *  turn by its authoring model. */
+    turnMeta = new Map();
+    /** Per-repo effect-name scope (e.g. `service-a:`); '' for single-stage. */
+    prefix;
+    constructor(deps) {
+        this.deps = deps;
+        this.turnCounter = deps.initialTurn ?? 0;
+        this.prefix = deps.effectPrefix ?? '';
+    }
+    /** Scoped effect name for a turn sub-effect. */
+    key(name) {
+        return `${this.prefix}${name}`;
+    }
+    /**
+     * Open a new assistant turn. Records the request payload as an
+     * `assistant-start` effect; on replay, returns the recorded turn's
+     * full transcript so the adapter can skip the upstream call entirely.
+     */
+    async startTurn(req) {
+        const turn = this.turnCounter++;
+        const turnUuid = this.uuid();
+        this.turnUuids.set(turn, turnUuid);
+        this.toolIdxByTurn.set(turn, 0);
+        this.turnMeta.set(turn, { model: req.model, provider: req.provider });
+        // Record the start. On replay this is a no-op that returns the
+        // recorded payload — we don't use the return value here because
+        // the meaningful replay signal is whether `assistant-end` exists.
+        //
+        // Deliberately NO `idempotencyKey` (input-hash) guard on this effect.
+        // The turn's input (system prompt + messages) embeds live-queried,
+        // process-local context: the Knowledge Base graph and memory block are
+        // re-queried in a fresh process on resume (the "stable" prompt getters
+        // only memoise WITHIN one run, not across a restart), and a cross-vendor
+        // continuation legitimately swaps the model/prefill. So the input is NOT
+        // byte-stable across resume — and it doesn't need to be: when
+        // `assistant-end` exists the recorded transcript is replayed verbatim
+        // (the upstream call is skipped, so the rebuilt prompt is never sent);
+        // when it doesn't, the turn re-runs live (the whole point of resume).
+        // Hashing the input into a FATAL determinism guard turned that benign
+        // drift into a `DeterminismViolationError` and broke resume entirely.
+        // The effect-SEQUENCE guard (name + idx) still catches genuine step-logic
+        // divergence; `runTool` still pins tool args via its own idempotencyKey.
+        await this.deps.runtime.effect(this.key(`turn:${turn}:assistant-start`), async () => ({
+            turnUuid,
+            model: req.model,
+            provider: req.provider,
+            prefillTurnUuid: req.prefill?.turnUuid ?? null,
+            // §Tier 2: persist the phase's user prompt so a stateful resume can
+            // reconstruct prior turns WITH their prompts. Additive only — never
+            // re-read by replay-skip (which reads assistant-end).
+            userPrompt: req.userPrompt ?? null,
+        }), { smallResult: true });
+        // H3 replay-skip: if this turn's `assistant-end` is already in the
+        // durable log, the whole turn ran on a prior process. Reconstruct
+        // it so the adapter skips the upstream call and re-appends the
+        // recorded native history verbatim. `peekRecorded` is a pure read
+        // (no cursor/idx mutation) — the adapter still calls runTool/endTurn
+        // in order to advance the replay cursor over the recorded sub-effects.
+        const replayed = this.tryReconstructTurn(turn, turnUuid);
+        if (replayed)
+            return { turn, turnUuid, replayed };
+        return { turn, turnUuid };
+    }
+    /**
+     * Peek the durable log for a fully-recorded turn N. Returns the
+     * reconstructed `AssistantTurn` iff `turn:N:assistant-end` exists;
+     * undefined on the live path (peek unsupported, or end not yet
+     * recorded). Pure reads only — no effect cursor is advanced here.
+     */
+    tryReconstructTurn(turn, turnUuid) {
+        const peek = this.deps.runtime.peekRecorded?.bind(this.deps.runtime);
+        if (!peek)
+            return undefined;
+        const end = peek(this.key(`turn:${turn}:assistant-end`));
+        if (!end)
+            return undefined;
+        const toolUses = [];
+        const toolResults = [];
+        for (let m = 0;; m += 1) {
+            const tu = peek(this.key(`turn:${turn}:tool_use:${m}`));
+            if (!tu)
+                break;
+            const tr = peek(this.key(`turn:${turn}:tool_result:${m}`));
+            toolUses.push({
+                // `id` isn't in the tool_use payload; the matching tool_result
+                // carries `toolUseId` (the provider id). Used only for cosmetic
+                // re-emit on replay — runTool keys off (name, idx, idempotencyKey).
+                id: tr?.toolUseId ?? '',
+                name: tu.name ?? '',
+                arguments: tu.arguments ?? {},
+                idempotencyKey: tu.idempotencyKey ?? '',
+            });
+            if (tr)
+                toolResults.push(tr);
+        }
+        return {
+            turnUuid,
+            turn,
+            text: end.text ?? '',
+            stopReason: end.stopReason ?? 'end_turn',
+            usage: end.usage ?? { inputTokens: 0, outputTokens: 0 },
+            provenance: end.provenance ?? { segments: [] },
+            toolUses,
+            toolResults,
+            historyDelta: end.historyDelta ?? [],
+        };
+    }
+    /**
+     * Record a tool intent + execute (or replay) the tool. Combines what
+     * the ADR drafted as two calls into one atomic sequence. The
+     * `idempotencyKey` is hashed by the caller (or fed in pre-computed)
+     * and guards against args drift on replay.
+     *
+     * Replay behavior: the inner `tool_result:M` effect is replayed
+     * verbatim — `exec()` is NOT invoked. Side effects (file writes, bash
+     * runs) stay as the prior model left them.
+     */
+    async runTool(turn, name, args, idempotencyKey, exec) {
+        const idx = this.bumpToolIdx(turn);
+        await this.deps.runtime.effect(this.key(`turn:${turn}:tool_use:${idx}`), async () => ({ name, arguments: args, idempotencyKey }), { idempotencyKey, smallResult: true });
+        const result = await this.deps.runtime.effect(this.key(`turn:${turn}:tool_result:${idx}`), exec, {
+            // Cap the PERSISTED copy of large tool results (file dumps, bash
+            // stdout). A single agentic turn can fire many tool calls; persisting
+            // multi-MB payloads synchronously into SQLite blocks the event loop
+            // and is the dominant "LLM feels slow" cost. The live model still
+            // receives the full result — only the durable copy (replayed on
+            // resume) is truncated. Default cap 64 KiB; set
+            // ANVIL_DURABLE_MAX_TOOL_RESULT_BYTES=0 to disable.
+            persistTransform: (r) => capToolResultForPersist(r),
+        });
+        return result;
+    }
+    /**
+     * Close an assistant turn with the completed text, stop reason, usage,
+     * and provenance. Records `assistant-end`; on replay this is a no-op.
+     */
+    async endTurn(turn, text, stopReason, usage, provenance, 
+    /**
+     * Provider-native messages appended to history this turn (assistant
+     * + tool-result messages). Recorded so crash-resume re-appends them
+     * byte-for-byte (§ AssistantTurn.historyDelta). Default [] for the
+     * terminal no-tool turn (nothing appended). Opaque to the recorder.
+     */
+    historyDelta = []) {
+        const meta = this.turnMeta.get(turn);
+        await this.deps.runtime.effect(this.key(`turn:${turn}:assistant-end`), async () => ({
+            text,
+            stopReason,
+            usage,
+            provenance,
+            historyDelta,
+            // model + provider stamp lets the H3 per-model cost rollup price
+            // this turn's tokens by its authoring model.
+            model: meta?.model,
+            provider: meta?.provider,
+        }), { smallResult: text.length < 4_000 });
+    }
+    /**
+     * Flush an in-progress assistant text to the partial sink. Called from
+     * an adapter's catch block BEFORE re-throwing UpstreamError. Does NOT
+     * go through `effect()` — partial events are not subject to the
+     * (name, idx) counter; they're durable signals scoped by turnUuid.
+     *
+     * Safe to call when text is empty (sink decides whether to bother).
+     * Safe to call multiple times for the same turn — the sink handles
+     * dedup via turnUuid + recordedAt.
+     */
+    flushPartial(turn, text, toolUsesEmitted, reason) {
+        const turnUuid = this.turnUuids.get(turn);
+        if (!turnUuid)
+            return; // startTurn was never called — nothing to flush.
+        const partial = {
+            runId: this.deps.runId,
+            stepId: this.deps.stepId,
+            turnUuid,
+            turn,
+            text,
+            toolUsesEmitted,
+            reason,
+            recordedAt: this.nowIso(),
+        };
+        try {
+            this.deps.partialSink(partial);
+        }
+        catch (err) {
+            // Sink should be a fire-and-forget; if it throws we still re-throw
+            // the upstream error — log to stderr so the failure is visible.
+            process.stderr.write(`[turn-recorder] partialSink threw: ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Internals
+    // ─────────────────────────────────────────────────────────────────
+    bumpToolIdx(turn) {
+        const next = this.toolIdxByTurn.get(turn) ?? 0;
+        this.toolIdxByTurn.set(turn, next + 1);
+        return next;
+    }
+    uuid() {
+        return this.deps.uuid?.() ?? DEFAULT_UUID();
+    }
+    nowIso() {
+        return this.deps.nowIso?.() ?? new Date().toISOString();
+    }
+}
+// ─────────────────────────────────────────────────────────────────────
+// Null runtime — for adapters that haven't yet been wired to a real
+// EffectRuntime. Calls execute live; nothing is recorded; replay is a
+// no-op (since nothing is on disk). Lets us land the H1 recorder calls
+// without forcing every adapter or every call-site to thread a real
+// EffectRuntime through agent-core's bridge today.
+// ─────────────────────────────────────────────────────────────────────
+export function createNullEffectRuntime() {
+    return {
+        async effect(_name, fn) {
+            return await fn();
+        },
+    };
+}
+export function createNullPartialSink() {
+    return () => { };
+}
+/**
+ * Convenience factory: a TurnRecorder that does the right structural
+ * thing (records → executes → emits) but persists nothing. Adapters use
+ * this when their caller hasn't supplied a real runtime + sink. Identical
+ * observable behavior to today's adapters; opens the door for the H2+
+ * wiring to inject the real instances without touching adapter code
+ * again.
+ */
+export function createNullTurnRecorder(opts) {
+    return new TurnRecorder({
+        runtime: createNullEffectRuntime(),
+        partialSink: createNullPartialSink(),
+        runId: opts?.runId ?? 'null-run',
+        stepId: opts?.stepId ?? 'null-step',
+    });
+}
+export * from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/turn-recorder/index.js.map

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

package/dist/turn-recorder/types.d.ts

@@ -0,0 +1,227 @@
+/**
+ * TurnRecorder types — public shapes consumed by adapters that drive a
+ * multi-turn LLM tool loop and want their turns split into sub-effects
+ * so chain-fallback can resume mid-stream.
+ *
+ * Design notes:
+ *   - agent-core does NOT depend on `@anvil/core-pipeline`. The
+ *     `EffectRuntimeLike` interface here is the structural shape an
+ *     adapter needs — core-pipeline's concrete `EffectRuntime` satisfies
+ *     it, but agent-core never imports the class. This avoids a
+ *     circular dep direction.
+ *   - The recorder is constructed per `adapter.run()` call. It holds a
+ *     monotonic `turn` counter scoped to the (stepId, sessionId) pair.
+ *   - `flushPartial` is intentionally non-async and not routed through
+ *     `effect()` — it MUST be safe to fire from a `catch` block that is
+ *     about to re-throw an `UpstreamError`. The sink may queue the
+ *     write durably under the hood; the recorder doesn't wait.
+ */
+import type { ProviderName } from '../types.js';
+/**
+ * Minimal effect-runtime shape the recorder relies on. Mirrors the
+ * `effect(name, fn, opts?)` method on core-pipeline's `EffectRuntime`.
+ * Anything else on the real class (now/uuid/random/sleep/waitForSignal)
+ * is irrelevant to the recorder.
+ *
+ * Replay semantics: when an effect with `(name, idx)` is already in the
+ * durable log, `fn` is NOT invoked — the recorded payload is returned.
+ * Recording side effects (`record*` methods) thus become no-ops on
+ * replay, which is exactly what we want.
+ */
+export interface EffectRuntimeLike {
+    effect<T>(name: string, fn: () => Promise<T>, opts?: EffectInvokeOptions): Promise<T>;
+    /**
+     * H3 replay-skip seam: peek the recorded payload of a COMPLETED effect
+     * by name WITHOUT advancing the replay cursor or the per-step idx
+     * counter. Returns the recorded `effect:completed` payload if one
+     * exists in this step's log, else undefined. Lets `startTurn` detect
+     * that a turn was already fully recorded (its `assistant-end` exists)
+     * so the adapter can skip the upstream call entirely on crash-resume.
+     *
+     * Optional: the NullEffectRuntime omits it, so non-durable callers
+     * (single-shot / no DurableStore) always run live (peek → undefined →
+     * no replay). The concrete core-pipeline `EffectRuntime` implements it
+     * as a pure read over the pre-loaded recorded-effect set.
+     */
+    peekRecorded?<T = unknown>(name: string): T | undefined;
+}
+export interface EffectInvokeOptions {
+    /** Stable input hash; mismatches on replay throw a determinism error. */
+    idempotencyKey?: string;
+    /** Hint that the payload is small enough to inline; runtime may skip blobs. */
+    smallResult?: boolean;
+    /**
+     * Transform applied to the result before it is persisted to the durable
+     * log; the live caller still gets the full result. Used to cap large
+     * tool-result payloads so a turn doesn't block the loop serialising them.
+     * Mirrors `EffectOptions.persistTransform` in core-pipeline.
+     */
+    persistTransform?: (result: unknown) => unknown;
+}
+export interface RecordedToolUse {
+    /** Provider-supplied tool_use id (e.g. OpenAI's `tool_call_id`). */
+    id: string;
+    name: string;
+    /** Parsed JSON arguments. UNPARSED args MUST NOT be recorded (§2.1.1). */
+    arguments: Record<string, unknown>;
+    /** sha256(name || JSON.stringify(arguments)). */
+    idempotencyKey: string;
+}
+export interface NeutralToolResult {
+    toolUseId: string;
+    toolName: string;
+    ok: boolean;
+    content: string | unknown;
+    durationMs?: number;
+}
+export interface ProvenanceSegment {
+    model: string;
+    provider: ProviderName;
+    range: [number, number];
+    source: 'live' | 'prefill';
+}
+export interface Provenance {
+    segments: ProvenanceSegment[];
+}
+export interface TurnTokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    /** Subset of inputTokens carved out for §2.6 prefill-reinjection. */
+    prefilledInputTokens?: number;
+}
+export interface PrefillToolUse {
+    id: string;
+    name: string;
+    input: unknown;
+    result: NeutralToolResult;
+    producedBy: ProviderName;
+}
+export interface Prefill {
+    turnUuid: string;
+    text: string;
+    toolUses: PrefillToolUse[];
+    sourceProvider: ProviderName;
+    /** Model id that authored the partial — drives §2.7 provenance
+     *  segment[0].model on the resuming turn. Optional: omitted by
+     *  pre-H3 callers / when the source model is unknown. */
+    sourceModel?: string;
+    /** Tokens (as billed by sourceProvider) for `text`; H3 cost accounting. */
+    sourceTokens: number;
+}
+/**
+ * §Tier 2 — one COMPLETED prior turn of a stateful session, reconstructed
+ * from the durable log so a cross-model (or merely non-claude) resume can
+ * re-present the full conversation in the target provider's wire format.
+ * Unlike `Prefill` (the in-progress burned turn), these are finished turns.
+ *
+ * `userPrompt` is present on the FIRST turn of each phase (the new user
+ * message that opened that phase); it's undefined on tool-loop continuation
+ * turns within a phase, and on pre-Tier-2 logs that never recorded it.
+ */
+export interface PrefillTurn {
+    userPrompt?: string;
+    text: string;
+    toolUses: PrefillToolUse[];
+    /**
+     * Authoring provider of this completed turn — informational / provenance.
+     * `materializePriorTurns` flattens all turns to the resuming target's wire
+     * format and does NOT run per-turn `stripForTarget`: completed turns are
+     * rebuilt from neutral fields (text + `NeutralToolResult`) that carry no
+     * vendor keys (no `reasoning_details` / `cache_control` / `prompt_cache_key`),
+     * so there is nothing to strip. (Contrast the `prefill` path, which does
+     * `stripForTarget` because it can re-present source-shaped messages.)
+     */
+    producedBy: ProviderName;
+}
+export type PartialReason = 'upstream' | 'abort' | 'timeout';
+export interface AssistantPartial {
+    runId: string;
+    stepId: string;
+    turnUuid: string;
+    turn: number;
+    text: string;
+    /** Count of FULLY-PARSED tool_use blocks emitted before the throw. */
+    toolUsesEmitted: number;
+    reason: PartialReason;
+    recordedAt: string;
+}
+export type PartialSink = (partial: AssistantPartial) => void;
+export interface AssistantStartRequest {
+    model: string;
+    provider: ProviderName;
+    system?: string;
+    /** Raw conversation messages sent to the upstream. Recorded for provenance. */
+    messages: unknown;
+    prefill?: Prefill;
+    /**
+     * §Tier 2 — the new user message that opened this phase. Recorded in the
+     * assistant-start payload so `reconstructSessionHistory` can re-present
+     * prior turns with their prompts on a stateful (non-claude) session resume.
+     */
+    userPrompt?: string;
+}
+export interface AssistantTurn {
+    turnUuid: string;
+    turn: number;
+    text: string;
+    stopReason: string;
+    usage: TurnTokenUsage;
+    provenance: Provenance;
+    toolUses: RecordedToolUse[];
+    toolResults: NeutralToolResult[];
+    /**
+     * H3 replay determinism: the EXACT provider-native messages the
+     * adapter appended to its conversation history during this turn
+     * (assistant message + tool-result messages), as opaque objects. On
+     * crash-resume the adapter re-appends these verbatim instead of
+     * reconstructing them from the neutral `toolUses`/`text` — raw vs
+     * canonical `tool_calls` arguments and vendor `reasoning_details` echoes
+     * would otherwise drift, leaving the FIRST live turn past the replay
+     * frontier with a malformed upstream request (e.g. unpaired tool_calls,
+     * or "reasoning_content is missing"). Empty for a terminal (no-tool)
+     * turn that appended nothing before breaking.
+     */
+    historyDelta: unknown[];
+}
+export interface TurnRecorderDeps {
+    /** EffectRuntime to record sub-effects against. */
+    runtime: EffectRuntimeLike;
+    /** Fire-and-forget partial sink; called from adapter catch blocks. */
+    partialSink: PartialSink;
+    /** Stable runId — propagated into AssistantPartial rows. */
+    runId: string;
+    /** Stable stepId — scopes the recorder to one pipeline Step. */
+    stepId: string;
+    /** v4 uuid factory — overridable for tests. Defaults to crypto.randomUUID. */
+    uuid?: () => string;
+    /** Wall-clock helper — overridable for tests. Defaults to () => new Date().toISOString(). */
+    nowIso?: () => string;
+    /**
+     * Effect-name prefix (v2 ADR §2.4 per-repo scoping). When a step fans
+     * out across repos in parallel, every repo's recorder writes effects
+     * under the SAME durable step id, so a bare `turn:0:assistant-start`
+     * from two repos would collide. The caller passes a per-repo prefix
+     * (e.g. `service-a:`) so the recorded keys become
+     * `service-a:turn:0:assistant-start` — unique per repo AND matched by
+     * the durable engine's per-repo effect filter (which keys on delimited
+     * scope tokens). Empty ('') for single-stage paths. Applied uniformly
+     * to every effect name AND to the `peekRecorded` replay lookup.
+     */
+    effectPrefix?: string;
+    /**
+     * Seed for the per-recorder turn counter (v2 ADR §2.5.1). When an
+     * `AgentProcess.sendInput()` resume spawns a NEW adapter (hence a new
+     * recorder) for a session whose prior adapter already recorded turns
+     * 0..N, the new recorder MUST continue at N+1 so `(stepId, turnUuid)`
+     * stays globally unique and replay's effect-idx matching doesn't
+     * collide. The recorder itself cannot read the durable log (it only
+     * holds a structural `EffectRuntimeLike`), so the CALLER computes the
+     * highest completed turn for (runId, stepId) and passes it here; the
+     * recorder seeds `turnCounter = initialTurn`. Defaults to 0 (fresh
+     * session / no prior turns).
+     */
+    initialTurn?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/turn-recorder/types.d.ts.map

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

package/dist/turn-recorder/types.js

@@ -0,0 +1,20 @@
+/**
+ * TurnRecorder types — public shapes consumed by adapters that drive a
+ * multi-turn LLM tool loop and want their turns split into sub-effects
+ * so chain-fallback can resume mid-stream.
+ *
+ * Design notes:
+ *   - agent-core does NOT depend on `@anvil/core-pipeline`. The
+ *     `EffectRuntimeLike` interface here is the structural shape an
+ *     adapter needs — core-pipeline's concrete `EffectRuntime` satisfies
+ *     it, but agent-core never imports the class. This avoids a
+ *     circular dep direction.
+ *   - The recorder is constructed per `adapter.run()` call. It holds a
+ *     monotonic `turn` counter scoped to the (stepId, sessionId) pair.
+ *   - `flushPartial` is intentionally non-async and not routed through
+ *     `effect()` — it MUST be safe to fire from a `catch` block that is
+ *     about to re-throw an `UpstreamError`. The sink may queue the
+ *     write durably under the hood; the recorder doesn't wait.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/turn-recorder/types.js.map

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

package/dist/types.d.ts

@@ -129,8 +129,13 @@ export interface LanguageModel {
         version?: string;
         error?: string;
     }>;
-    /** Streaming surface — yields events as the provider produces them. */
-    invokeStream(opts: LanguageModelInvokeOptions): AsyncIterable<StreamEvent>;
+    /**
+     * Streaming surface — yields events as the provider produces them and
+     * RETURNS the assembled `InvokeResult` (cost/usage/finish) on completion,
+     * so a streaming consumer (the router's chain walk) gets the same outcome
+     * data a single-shot `invoke()` would, without re-running the call.
+     */
+    invokeStream(opts: LanguageModelInvokeOptions): AsyncGenerator<StreamEvent, InvokeResult>;
     /** Single-shot surface — drains the stream and returns the final block. */
     invoke(opts: LanguageModelInvokeOptions): Promise<InvokeResult>;
 }
@@ -189,6 +194,34 @@ export interface ModelAdapterConfig {
      * ADR §C5.
      */
     mcpConfigPath?: string;
+    /**
+     * Turn-level durable recorder (v2 ADR §2.5). When supplied by the
+     * caller, the adapter splits its LLM invocation into per-turn
+     * sub-effects (`assistant-start` / `tool_use:N` / `tool_result:N` /
+     * `assistant-end`) recorded against the caller's `EffectRuntime`.
+     * When absent, adapters construct a `NullTurnRecorder` internally —
+     * structural calls still happen so the code path is the same, but
+     * nothing is persisted. Recording is implemented for every adapter
+     * except `gemini-cli` (a CLI subprocess with no token-level stream),
+     * which always no-ops the recorder.
+     */
+    turnRecorder?: import('./turn-recorder/index.js').TurnRecorder;
+    /**
+     * Prefill from a prior model that burned mid-stream (v2 ADR §2.3).
+     * When present, the adapter materializes the trailing-assistant +
+     * recorded tool-result history into its provider's wire format and
+     * continues from the exact character where the prior model stopped.
+     */
+    prefill?: import('./turn-recorder/index.js').Prefill;
+    /**
+     * §Tier 2 — COMPLETED prior turns of a stateful session, reconstructed
+     * from the durable log. Spliced (materialized into this provider's wire
+     * format) BEFORE the new user message so a non-claude session resume
+     * re-presents the full conversation instead of starting fresh. Claude
+     * uses native `--resume` and is gated out at the bridge. Empty/undefined
+     * → unchanged single-turn behavior.
+     */
+    priorMessages?: import('./turn-recorder/index.js').PrefillTurn[];
 }
 export interface ToolExecutorLike {
     listSchemas(): ToolSchema[];