@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/dist/activities/execute-deep-agent/__test-utils__/paused-session-fixture.d.ts

@@ -0,0 +1,76 @@
+/**
+ * A paused native session, frozen as the checkpoint rows the engine of its day
+ * wrote, and the means to write those rows back into a session's checkpoint
+ * file. The resume nets share it: a session saved before a change to the
+ * engine must resume after it, and the only honest saved session is one the
+ * old engine really wrote, recorded before the change and never regenerated.
+ *
+ * A fixture carries the sqlite rows (`checkpoints`, `writes`) with each blob
+ * as UTF-8 text when it is JSON (the serializer's `json` tag) and base64
+ * otherwise, the paused turn's rows and the status it persisted (one `toJson`
+ * object, {@link pausedTurnJson}), and the engine versions that wrote it.
+ *
+ * Its users:
+ *  - `__tests__/hermetic/resume-across-engine-upgrade.test.ts`: sessions
+ *    recorded on an older deepagents line;
+ *  - `__tests__/hermetic/resume-across-think-retirement.test.ts` and its live
+ *    twin: a session whose history holds a call to a tool the engine no
+ *    longer binds.
+ */
+import { type JsonValue } from "@bufbuild/protobuf";
+import { type RunStatus } from "@stigmer/apis/ai/stigmer/agentic/run/v1/api_pb";
+import { type TurnRows } from "../../../gen/turn/ai/stigmer/runner/turn/v1/rows_pb.js";
+/** A blob as the fixture stores it: readable when the serializer wrote JSON. */
+export interface StoredBlob {
+    readonly encoding: "utf8" | "base64";
+    readonly data: string;
+}
+export interface CheckpointRow {
+    readonly thread_id: string;
+    readonly checkpoint_ns: string;
+    readonly checkpoint_id: string;
+    readonly parent_checkpoint_id: string | null;
+    readonly type: string | null;
+    readonly checkpoint: StoredBlob;
+    readonly metadata: StoredBlob;
+}
+export interface WriteRow {
+    readonly thread_id: string;
+    readonly checkpoint_ns: string;
+    readonly checkpoint_id: string;
+    readonly task_id: string;
+    readonly idx: number;
+    readonly channel: string;
+    readonly type: string | null;
+    readonly value: StoredBlob;
+}
+export interface PausedSessionFixture {
+    /** The engine that wrote the rows. */
+    readonly recordedWith: Readonly<Record<string, string>>;
+    readonly threadId: string;
+    readonly checkpoints: readonly CheckpointRow[];
+    readonly writes: readonly WriteRow[];
+    /**
+     * The paused turn's rows and the status it persisted, as one `toJson`
+     * object ({@link pausedTurnJson}): the shape fixtures recorded while the
+     * rows rode the status already have, so a fixture is never rewritten.
+     */
+    readonly status: JsonValue;
+}
+/** A paused turn's rows and status as one `toJson` object (the fixture's `status`). */
+export declare function pausedTurnJson(rows: TurnRows, status: RunStatus): JsonValue;
+/** A fixture's `status` taken apart into the turn's rows and the status it persisted. */
+export declare function pausedTurnOf(json: JsonValue): {
+    readonly rows: TurnRows;
+    readonly status: RunStatus;
+};
+/** The version of `pkg` this process resolves, read from its own package.json. */
+export declare function installedVersion(pkg: string): string;
+/** The engine versions a fixture records itself as written by. */
+export declare function engineVersions(): Record<string, string>;
+export declare function storeBlob(type: string | null, bytes: Uint8Array): StoredBlob;
+export declare function loadBlob(blob: StoredBlob): Uint8Array;
+/** Every row of a session's checkpoint file, in a stable order. */
+export declare function readRows(dbPath: string): Pick<PausedSessionFixture, "checkpoints" | "writes">;
+/** Write a fixture's rows into a checkpoint file whose schema the saver itself created. */
+export declare function loadRows(dbPath: string, fixture: PausedSessionFixture): Promise<void>;

package/dist/activities/execute-deep-agent/__test-utils__/paused-session-fixture.js

@@ -0,0 +1,112 @@
+/**
+ * A paused native session, frozen as the checkpoint rows the engine of its day
+ * wrote, and the means to write those rows back into a session's checkpoint
+ * file. The resume nets share it: a session saved before a change to the
+ * engine must resume after it, and the only honest saved session is one the
+ * old engine really wrote, recorded before the change and never regenerated.
+ *
+ * A fixture carries the sqlite rows (`checkpoints`, `writes`) with each blob
+ * as UTF-8 text when it is JSON (the serializer's `json` tag) and base64
+ * otherwise, the paused turn's rows and the status it persisted (one `toJson`
+ * object, {@link pausedTurnJson}), and the engine versions that wrote it.
+ *
+ * Its users:
+ *  - `__tests__/hermetic/resume-across-engine-upgrade.test.ts`: sessions
+ *    recorded on an older deepagents line;
+ *  - `__tests__/hermetic/resume-across-think-retirement.test.ts` and its live
+ *    twin: a session whose history holds a call to a tool the engine no
+ *    longer binds.
+ */
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { expect } from "vitest";
+import { fromJson, toJson } from "@bufbuild/protobuf";
+import { RunStatusSchema } from "@stigmer/apis/ai/stigmer/agentic/run/v1/api_pb";
+import { SqliteCheckpointSaver } from "../../../shared/checkpointer/sqlite-saver.js";
+import { TurnRowsSchema } from "../../../gen/turn/ai/stigmer/runner/turn/v1/rows_pb.js";
+/** A paused turn's rows and status as one `toJson` object (the fixture's `status`). */
+export function pausedTurnJson(rows, status) {
+    return { ...toJson(RunStatusSchema, status), ...toJson(TurnRowsSchema, rows) };
+}
+/** A fixture's `status` taken apart into the turn's rows and the status it persisted. */
+export function pausedTurnOf(json) {
+    return {
+        rows: fromJson(TurnRowsSchema, json, { ignoreUnknownFields: true }),
+        status: fromJson(RunStatusSchema, json, { ignoreUnknownFields: true }),
+    };
+}
+/** The version of `pkg` this process resolves, read from its own package.json. */
+export function installedVersion(pkg) {
+    const require = createRequire(import.meta.url);
+    let dir = dirname(require.resolve(pkg));
+    while (!existsSync(join(dir, "package.json")) || readPackageName(dir) !== pkg) {
+        const parent = dirname(dir);
+        if (parent === dir)
+            throw new Error(`no package.json found for ${pkg}`);
+        dir = parent;
+    }
+    return JSON.parse(readFileSync(join(dir, "package.json"), "utf8")).version;
+}
+function readPackageName(dir) {
+    return JSON.parse(readFileSync(join(dir, "package.json"), "utf8")).name;
+}
+/** The engine versions a fixture records itself as written by. */
+export function engineVersions() {
+    return {
+        deepagents: installedVersion("deepagents"),
+        "@langchain/langgraph": installedVersion("@langchain/langgraph"),
+        "@langchain/langgraph-checkpoint": installedVersion("@langchain/langgraph-checkpoint"),
+        "@langchain/core": installedVersion("@langchain/core"),
+    };
+}
+export function storeBlob(type, bytes) {
+    return type === "json"
+        ? { encoding: "utf8", data: Buffer.from(bytes).toString("utf8") }
+        : { encoding: "base64", data: Buffer.from(bytes).toString("base64") };
+}
+export function loadBlob(blob) {
+    return new Uint8Array(Buffer.from(blob.data, blob.encoding));
+}
+/** Every row of a session's checkpoint file, in a stable order. */
+export function readRows(dbPath) {
+    const db = new DatabaseSync(dbPath, { readOnly: true });
+    try {
+        const checkpoints = db
+            .prepare(`SELECT thread_id, checkpoint_ns, checkpoint_id, parent_checkpoint_id, type, checkpoint, metadata
+           FROM checkpoints ORDER BY checkpoint_ns, checkpoint_id`)
+            .all().map((r) => ({ ...r, checkpoint: storeBlob(r.type, r.checkpoint), metadata: storeBlob(r.type, r.metadata) }));
+        const writes = db
+            .prepare(`SELECT thread_id, checkpoint_ns, checkpoint_id, task_id, idx, channel, type, value
+           FROM writes ORDER BY checkpoint_ns, checkpoint_id, task_id, idx`)
+            .all().map((r) => ({ ...r, value: storeBlob(r.type, r.value) }));
+        return { checkpoints, writes };
+    }
+    finally {
+        db.close();
+    }
+}
+/** Write a fixture's rows into a checkpoint file whose schema the saver itself created. */
+export async function loadRows(dbPath, fixture) {
+    mkdirSync(dirname(dbPath), { recursive: true });
+    const saver = new SqliteCheckpointSaver(dbPath);
+    expect(await saver.getTuple({ configurable: { thread_id: fixture.threadId } }), "a fresh file").toBeUndefined();
+    const db = new DatabaseSync(dbPath);
+    try {
+        const cp = db.prepare(`INSERT INTO checkpoints (thread_id, checkpoint_ns, checkpoint_id, parent_checkpoint_id, type, checkpoint, metadata)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`);
+        for (const r of fixture.checkpoints) {
+            cp.run(r.thread_id, r.checkpoint_ns, r.checkpoint_id, r.parent_checkpoint_id, r.type, loadBlob(r.checkpoint), loadBlob(r.metadata));
+        }
+        const w = db.prepare(`INSERT INTO writes (thread_id, checkpoint_ns, checkpoint_id, task_id, idx, channel, type, value)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
+        for (const r of fixture.writes) {
+            w.run(r.thread_id, r.checkpoint_ns, r.checkpoint_id, r.task_id, r.idx, r.channel, r.type, loadBlob(r.value));
+        }
+    }
+    finally {
+        db.close();
+    }
+}
+//# sourceMappingURL=paused-session-fixture.js.map

package/dist/activities/execute-deep-agent/__test-utils__/paused-session-fixture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paused-session-fixture.js","sourceRoot":"","sources":["../../../../src/activities/execute-deep-agent/__test-utils__/paused-session-fixture.ts"],"names":[],"mappings":"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"}

package/dist/activities/execute-deep-agent/__test-utils__/scripted-model-module.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The module-boundary double for `shared/model-client.ts` — how a
+ * `ScriptedModel` reaches the REAL native engine build.
+ *
+ * `buildChatModel` is the runner's single construction point for LangChain
+ * chat models, and a native turn reaches it three ways: the primary model
+ * (`turn-setup.ts` `buildEngine`), every sub-agent's `modelFactory` (the same
+ * `buildModelFor`), and the runtime's tier-2 structured-output extractor
+ * (`shared/extract-structured-output.ts`). None of them takes a model as an
+ * argument, so the one seam a hermetic run has is this module — the native analog of the Cursor
+ * driver's `vi.mock("@cursor/sdk")`: the vendor engine doubled where the
+ * runner imports it, and nothing else.
+ *
+ * `vi.mock` is hoisted and must live in the test file; the factory can
+ * `await import()` this module:
+ *
+ * ```ts
+ * vi.mock("../../../../shared/model-client.js", async () =>
+ *   (await import("../../__test-utils__/scripted-model-module.js")).scriptedModelClientModule(),
+ * );
+ * ```
+ *
+ * Every build the activity requests is recorded (`builds`) so a scenario can
+ * assert WHAT production asked for — the registry id, the service tier, the
+ * proxy posture — while the model handed back is the scenario's script. The
+ * provider is inferred from the requested name exactly as the real module
+ * does, so a golden's provider-labelled copy reads as in production.
+ *
+ * A scenario binds ONE model (every build of every execution gets it) or a
+ * RESOLVER over the build's options: production scopes every build to its
+ * execution through `headerScope.executionId` (the proxy's attribution
+ * header), so a test that runs several executions at once — the harness
+ * contract kit's concurrency invariant — routes each build to that
+ * execution's own engine through the id production already sends, and
+ * through nothing added for the test.
+ */
+import type { BuildChatModelOptions, BuiltChatModel } from "../../../shared/model-client.js";
+import type { ScriptedModel } from "./scripted-model.js";
+/** Which `ScriptedModel` answers one `buildChatModel` call. */
+export type ScriptedModelResolver = (opts: BuildChatModelOptions) => ScriptedModel;
+/**
+ * Bind the model every `buildChatModel` call hands back for the current
+ * scenario — or a resolver that picks one per call — and forget the previous
+ * scenario's build log. Called by the driver at `beginDeepAgentScenario`,
+ * before the activity factory runs.
+ */
+export declare function bindScriptedModel(model: ScriptedModel | ScriptedModelResolver): void;
+/** The `buildChatModel` requests the activity made in this scenario, in order. */
+export declare function recordedModelBuilds(): readonly BuildChatModelOptions[];
+/** The factory a test passes to `vi.mock(".../shared/model-client.js", ...)`. */
+export declare function scriptedModelClientModule(): {
+    buildChatModel: (opts: BuildChatModelOptions) => Promise<BuiltChatModel>;
+};

package/dist/activities/execute-deep-agent/__test-utils__/scripted-model-module.js

@@ -0,0 +1,71 @@
+/**
+ * The module-boundary double for `shared/model-client.ts` — how a
+ * `ScriptedModel` reaches the REAL native engine build.
+ *
+ * `buildChatModel` is the runner's single construction point for LangChain
+ * chat models, and a native turn reaches it three ways: the primary model
+ * (`turn-setup.ts` `buildEngine`), every sub-agent's `modelFactory` (the same
+ * `buildModelFor`), and the runtime's tier-2 structured-output extractor
+ * (`shared/extract-structured-output.ts`). None of them takes a model as an
+ * argument, so the one seam a hermetic run has is this module — the native analog of the Cursor
+ * driver's `vi.mock("@cursor/sdk")`: the vendor engine doubled where the
+ * runner imports it, and nothing else.
+ *
+ * `vi.mock` is hoisted and must live in the test file; the factory can
+ * `await import()` this module:
+ *
+ * ```ts
+ * vi.mock("../../../../shared/model-client.js", async () =>
+ *   (await import("../../__test-utils__/scripted-model-module.js")).scriptedModelClientModule(),
+ * );
+ * ```
+ *
+ * Every build the activity requests is recorded (`builds`) so a scenario can
+ * assert WHAT production asked for — the registry id, the service tier, the
+ * proxy posture — while the model handed back is the scenario's script. The
+ * provider is inferred from the requested name exactly as the real module
+ * does, so a golden's provider-labelled copy reads as in production.
+ *
+ * A scenario binds ONE model (every build of every execution gets it) or a
+ * RESOLVER over the build's options: production scopes every build to its
+ * execution through `headerScope.executionId` (the proxy's attribution
+ * header), so a test that runs several executions at once — the harness
+ * contract kit's concurrency invariant — routes each build to that
+ * execution's own engine through the id production already sends, and
+ * through nothing added for the test.
+ */
+import { stripProviderPrefix, tryInferProvider } from "../../../shared/llm-proxy.js";
+let resolve;
+const builds = [];
+/**
+ * Bind the model every `buildChatModel` call hands back for the current
+ * scenario — or a resolver that picks one per call — and forget the previous
+ * scenario's build log. Called by the driver at `beginDeepAgentScenario`,
+ * before the activity factory runs.
+ */
+export function bindScriptedModel(model) {
+    resolve = typeof model === "function" ? model : () => model;
+    builds.length = 0;
+}
+/** The `buildChatModel` requests the activity made in this scenario, in order. */
+export function recordedModelBuilds() {
+    return builds;
+}
+/** The factory a test passes to `vi.mock(".../shared/model-client.js", ...)`. */
+export function scriptedModelClientModule() {
+    return {
+        buildChatModel: async (opts) => {
+            if (!resolve) {
+                throw new Error("scripted-model-module: no ScriptedModel bound — call bindScriptedModel(model) " +
+                    "before constructing the activities");
+            }
+            builds.push(opts);
+            return {
+                model: resolve(opts),
+                provider: tryInferProvider(opts.modelName) ?? "anthropic",
+                apiModelId: stripProviderPrefix(opts.modelName),
+            };
+        },
+    };
+}
+//# sourceMappingURL=scripted-model-module.js.map

package/dist/activities/execute-deep-agent/__test-utils__/scripted-model-module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scripted-model-module.js","sourceRoot":"","sources":["../../../../src/activities/execute-deep-agent/__test-utils__/scripted-model-module.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAGH,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAMrF,IAAI,OAA0C,CAAC;AAC/C,MAAM,MAAM,GAA4B,EAAE,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAA4C;IAC5E,OAAO,GAAG,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC;IAC5D,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;AACpB,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,mBAAmB;IACjC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,yBAAyB;IAGvC,OAAO;QACL,cAAc,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;YAC7B,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,MAAM,IAAI,KAAK,CACb,gFAAgF;oBAC9E,oCAAoC,CACvC,CAAC;YACJ,CAAC;YACD,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAClB,OAAO;gBACL,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC;gBACpB,QAAQ,EAAE,gBAAgB,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,WAAW;gBACzD,UAAU,EAAE,mBAAmB,CAAC,IAAI,CAAC,SAAS,CAAC;aAChD,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/activities/execute-deep-agent/__test-utils__/scripted-model.d.ts

@@ -0,0 +1,305 @@
+/**
+ * Scripted deep-agent test harness: a deterministic chat model plus the
+ * parent-checkpoint interrupt reader.
+ *
+ * These two helpers are what every "drive a real deepagents/LangGraph graph
+ * through the approval gate" test needs. They are shared by the graph-level
+ * tests (`__tests__/subagent-approval-propagation.test.ts`,
+ * `shell-execute-gate.test.ts`, …), the gateway Contract Test Kit adapter
+ * (`gateway-substrate.ts`), and the hermetic activity driver
+ * (`hermetic-deep-agent.ts`), which runs the REAL `ExecuteDeepAgent` activity
+ * with this model as the only LLM. Keeping one copy means a change to how the
+ * runner reads pending interrupts (or how a scripted run is driven) updates
+ * every consumer at once.
+ *
+ * The one rule the model keeps: it is a PURE FUNCTION of (bound tools,
+ * transcript). A script is a sequence of turns per role, and the turn to play
+ * is chosen by how many tool rounds the transcript already holds (AI messages
+ * carrying `tool_calls`), never by a call counter. That is what lets one
+ * script serve both checkpointers the runner ships: under `memory` a HITL
+ * reinvocation REPLAYS the graph from the first message (the saver is
+ * recreated empty per invocation), so the same transcript indices produce the
+ * same proposals; under `sqlite` the graph RESUMES after the interrupt and the
+ * next call sees one more completed round. A call-counted script would emit
+ * the wrong turn on replay.
+ *
+ * The double also refuses what a real provider refuses
+ * ({@link assertProviderTranscript}): a system message anywhere but first,
+ * or a tool call not answered directly by its tool message. Every transcript
+ * it is handed is checked before a turn is chosen, so a middleware that
+ * builds a request no provider would accept fails here, in every hermetic
+ * and graph-level test, instead of at Anthropic. Without it a double that
+ * never converts its input passed a mid-conversation advisory that every
+ * Anthropic run then failed on (stigmer/stigmer#1354).
+ *
+ * A script may also be a {@link TurnPlayer}: a function of the whole
+ * transcript that returns the one turn to play now. The same rule, with the
+ * indexing left to the caller — for a consumer whose plan is not "turn k on
+ * round k" but "the first step the conversation does not yet show" (the
+ * harness contract kit's native subject, whose one execution spans many
+ * kit turns on one sqlite thread).
+ *
+ * A turn may END the model call instead of finishing the message
+ * ({@link TurnEnding}): `fail` throws after its chunks (a provider error
+ * mid-stream); `hang` parks on the call's abort signal after its chunks and
+ * throws the abort when it fires (a provider stream that stalls and is then
+ * cancelled). A hang never parks on a timer: `@langchain/core` hands the
+ * graph run's signal to `_streamResponseChunks` as `options.signal`
+ * (`_separateRunnableConfigFromCallOptionsCompat`), and LangGraph threads
+ * its composite abort signal into every task's config, so the runtime's one
+ * stop is what unparks it. The `onPark` hook is how a test learns the engine
+ * is silent before it stops the turn from the outside.
+ *
+ * The model STREAMS. With LangGraph's v3 messages handler attached, LangChain
+ * Core streams a model internally when it implements `_streamResponseChunks`
+ * and otherwise falls back to a synthesized final-message event sequence
+ * (`@langchain/langgraph` `pregel/messages-v2.js` `emitFinalMessage`). The
+ * fallback spreads a `tool_call` block's `args` OBJECT into the
+ * `tool_call_chunk` fields the runner's translator reads as a JSON STRING
+ * (`translator.ts` `argsChunk`), which no real provider does.
+ * Streaming keeps the double on the production event path: `@langchain/core`
+ * `language_models/compat.js` `convertChunksToEvents` turns the chunks below
+ * into `message-start`, per-block `content-block-start` / `-delta` /
+ * `-finish`, and `message-finish` with usage — the same events `ChatAnthropic`
+ * produces. The chunk shapes are chosen from that converter: a string chunk
+ * opens block 0 and emits a text delta in one step; an array-content part
+ * opens its block with NO delta on first sight, so a reasoning block is sent
+ * as an empty opener followed by the text; a `tool_call_chunk` always emits a
+ * delta carrying the accumulated JSON args; `usage_metadata` rides the LAST
+ * chunk so it lands on `message-finish` (the one place the runner reads it),
+ * not on `message-start`.
+ */
+import { BaseChatModel } from "@langchain/core/language_models/chat_models";
+import type { BaseChatModelCallOptions } from "@langchain/core/language_models/chat_models";
+import type { CallbackManagerForLLMRun } from "@langchain/core/callbacks/manager";
+import { type BaseMessage } from "@langchain/core/messages";
+import { ChatGenerationChunk, type ChatResult } from "@langchain/core/outputs";
+/** A single tool call the scripted model proposes on a turn. */
+export interface ScriptedToolCall {
+    name: string;
+    args: Record<string, unknown>;
+    id: string;
+}
+/**
+ * Token usage a turn reports; fixed round numbers keep `streamingUsage`
+ * legible in a golden. The cache buckets ride `input_token_details` the way
+ * the Anthropic adapter reports them (`cache_read`, `cache_creation`);
+ * `inputTokens` is the total the provider states, cache included.
+ */
+export interface ScriptedUsage {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly cacheReadTokens?: number;
+    readonly cacheWriteTokens?: number;
+}
+/**
+ * How a turn ends the model call instead of finishing its message.
+ *  - `fail`: throw `error` after the turn's chunks — a provider error
+ *    mid-stream; the graph propagates it and the adapter classifies it.
+ *  - `hang`: after the turn's chunks, park on the call's abort signal and
+ *    throw the abort when it fires — a stalled provider stream, cancelled by
+ *    the run's one stop. Refused (thrown, diagnosing) when the call carries
+ *    no signal: a hang outside an abortable run would park forever.
+ */
+export type TurnEnding = {
+    readonly kind: "fail";
+    readonly error: Error;
+} | {
+    readonly kind: "hang";
+};
+/**
+ * One assistant turn, rendered in the standard content-block shape a
+ * streaming provider produces: an optional leading reasoning block, an
+ * optional text block, and one `tool_call` per entry of `toolCalls` (which is
+ * also what the graph executes). A turn with neither text nor tool calls is
+ * an empty assistant message — legal, and what a script that has said all it
+ * has to say looks like. A turn with `ends` never finishes its message: its
+ * chunks are streamed, then the ending takes the call.
+ */
+export interface ScriptedTurn {
+    readonly reasoning?: string;
+    readonly text?: string;
+    readonly toolCalls?: readonly ScriptedToolCall[];
+    readonly usage?: ScriptedUsage;
+    readonly ends?: TurnEnding;
+}
+/**
+ * A role's script: `turns[k]` is played when the transcript already holds `k`
+ * completed tool rounds. Running past the end throws (a script that runs out
+ * is a test bug) unless `repeatLast` is set, in which case the final turn
+ * plays again — the shape of a model that keeps calling a tool until the
+ * graph's recursion limit stops it.
+ */
+export interface RoleScript {
+    readonly turns: readonly ScriptedTurn[];
+    readonly repeatLast?: boolean;
+}
+/**
+ * The two-turn sugar most graph-level tests use: propose `toolCalls` on the
+ * first round, then say `done` on every round after. Exactly
+ * `{ turns: [{ toolCalls }, { text: done }], repeatLast: true }`.
+ */
+export interface ScriptStep {
+    toolCalls: ScriptedToolCall[];
+    done: string;
+}
+/**
+ * What a selector can tell one role from another by. `createDeepAgent` gives
+ * a declared sub-agent the SAME tool set as its parent (`task` included), so
+ * tool names alone cannot separate them; the system prompt can — it carries
+ * the role's own instructions.
+ */
+export interface ScriptRoleContext {
+    /** The transcript's leading system message, or "" when there is none. */
+    readonly systemPrompt: string;
+}
+/**
+ * A script as a function of the whole transcript: called on every model turn
+ * with the messages the model was asked with, returns the turn to play. The
+ * round-indexed `RoleScript` is the common case; this is for a plan whose
+ * progress is read off the conversation itself (see the header).
+ */
+export type TurnPlayer = (transcript: readonly BaseMessage[]) => ScriptedTurn;
+/** The three shapes a selector may answer with. */
+export type Script = ScriptStep | RoleScript | TurnPlayer;
+/**
+ * Picks the script for the role being asked. A single-agent test ignores both
+ * arguments; a parent/sub-agent test keys the role on a tool unique to one
+ * role when there is one (a custom counting tool), or on the role's
+ * instructions in `context.systemPrompt` when both roles bind the same tools
+ * (the hermetic delegation arm). Called at `_generate` time, never at bind
+ * time, so a role that is compiled but never invoked (the default
+ * general-purpose sub-agent) needs no script.
+ */
+export type ScriptSelector = (boundToolNames: string[], context: ScriptRoleContext) => Script;
+/** What the driver learns before a turn is rendered: which role, which round. */
+export interface ScriptedTurnInfo {
+    readonly boundToolNames: readonly string[];
+    readonly round: number;
+    /**
+     * The ids of the tool calls the transcript's last AI message made — the
+     * calls whose results this turn answers. Empty on a role's first turn and
+     * after a text-only turn. Read from the transcript the engine hands the
+     * model, never from the script, so it is what the engine actually ran.
+     */
+    readonly priorToolCallIds: readonly string[];
+    /**
+     * The ids of every tool call this model issued on an earlier turn, in any
+     * role: on a sub-agent's first turn, its parent's still-running call is
+     * among them though the sub-agent's own transcript never shows it.
+     */
+    readonly issuedToolCallIds: readonly string[];
+}
+export interface ScriptedModelOptions {
+    /**
+     * Called once per model turn, before it is rendered. The hermetic driver
+     * ticks its clock here and runs a scenario's scheduled effect (a user pause,
+     * a worker shutdown) — from a model turn, never from a timer, so the
+     * interruption lands at the same instant every run.
+     */
+    readonly onTurn?: (info: ScriptedTurnInfo) => void | Promise<void>;
+    /**
+     * Where the model records each tool call it issues, shared by every
+     * instance `bindTools` derives (one per role), so {@link ScriptedTurnInfo.issuedToolCallIds}
+     * spans roles. Created by the driver; absent, nothing is recorded.
+     */
+    readonly issued?: Set<string>;
+    /**
+     * Called the moment a `hang` turn parks on its abort signal — the engine
+     * is silent from here until the signal fires. A test that must stop the
+     * turn from the outside (the contract kit's `whenHanging`) listens here,
+     * so the stop lands in the hang and never in the adapter's setup.
+     */
+    readonly onPark?: () => void;
+}
+/**
+ * A deterministic chat model driven by a per-role script. No LLM, no network.
+ * The role is keyed on the bound tool names so the same instance drives a
+ * parent and its sub-agents.
+ */
+export declare class ScriptedModel extends BaseChatModel {
+    toolNames: string[];
+    /**
+     * The tool objects from the most recent `bindTools` call, exactly as the
+     * agent bound them (post-middleware). Lets tests assert on the bound
+     * SCHEMAS — e.g. the tool-intent middleware's bind-time shell clone — not
+     * just the names. The array is shared across the clones `bindTools`
+     * returns, so the instance the test holds always sees the latest bind.
+     */
+    readonly boundTools: unknown[];
+    private readonly select;
+    private readonly options;
+    constructor(select: ScriptSelector, boundTools?: unknown[], options?: ScriptedModelOptions);
+    _llmType(): string;
+    bindTools(tools: unknown[]): this;
+    /** The turn for this transcript, after the driver hook has run. */
+    private turnFor;
+    /**
+     * The non-streaming path (`invoke` outside a graph — the runtime's tier-2
+     * structured-output extractor is the one caller): the SAME chunks the
+     * streaming path yields, merged, which is the `AIMessageChunk` a streaming
+     * provider's `invoke` returns. `@langchain/core`'s base `withStructuredOutput`
+     * pipeline reads exactly that shape (`AIMessageChunk.isInstance`, then
+     * `tool_calls`); a plain `AIMessage` here would fail it with "Input is not
+     * an AIMessageChunk" where the real provider succeeds. An ending turn ends
+     * this call the same way it ends the stream.
+     */
+    _generate(messages: BaseMessage[], options: this["ParsedCallOptions"]): Promise<ChatResult>;
+    _streamResponseChunks(messages: BaseMessage[], options: this["ParsedCallOptions"] & BaseChatModelCallOptions, _runManager?: CallbackManagerForLLMRun): AsyncGenerator<ChatGenerationChunk>;
+    /** Never returns: throws the ending's error, or parks on the signal and throws its abort. */
+    private takeEnding;
+}
+/**
+ * The two rules both providers the runner builds a model for enforce on the
+ * messages a request carries, so the double enforces them too:
+ *  - only the first message may be a system message: `@langchain/anthropic`
+ *    throws on any other ("System messages are only permitted as the first
+ *    passed message"), since the system prompt is the request's own field;
+ *  - an AI message that proposes tool calls is followed directly by one tool
+ *    message per call id, in any order, before any other message: Anthropic
+ *    requires every `tool_use` answered in the next user turn, and OpenAI a
+ *    `tool` message per `tool_call_id` right after the assistant message.
+ * Throws a diagnosing error naming the offending index; returns otherwise.
+ */
+export declare function assertProviderTranscript(messages: readonly BaseMessage[]): void;
+/** Tool rounds the transcript already holds: AI messages that proposed at least one tool call. */
+export declare function completedToolRounds(messages: readonly BaseMessage[]): number;
+/** The tool-call ids on the transcript's last AI message; `[]` when there is none or it made no calls. */
+export declare function priorToolCallIds(messages: readonly BaseMessage[]): string[];
+/** A pending approval interrupt surfaced at the parent checkpoint. */
+export interface PendingInterrupt {
+    taskId: string;
+    interruptId: string;
+    toolCallId: string;
+    toolName: string;
+    message: string;
+    /**
+     * Authorization provenance the gate attached to the interrupt
+     * (approval-gate.ts `policy_source`) — the PolicySource union string, or "" for
+     * legacy. Lets the gateway contract assert every gated side effect is
+     * provenance-tagged.
+     */
+    policySource: string;
+    /** The plugin whose hook asked (approval-gate.ts `policy_hook`); undefined when no hook asked. */
+    policyHook: string | undefined;
+}
+/**
+ * Read the pending approval interrupts from a graph state, exactly as the
+ * production resume path does (`hitl.ts` / `index.ts`): scan the parent's
+ * top-level `tasks[].interrupts`, skipping any already carrying a resume value.
+ *
+ * Crucially `interruptId` is the interrupt's OWN id (`interrupts[].id`), not the
+ * owning `task.id` — for a nested sub-agent interrupt the two differ, and only
+ * the interrupt id routes a `Command(resume=...)` value back into the nested
+ * `interrupt()`.
+ */
+export declare function readPendingInterrupts(state: {
+    tasks?: ReadonlyArray<{
+        id: string;
+        interrupts?: ReadonlyArray<{
+            id?: string;
+            value?: unknown;
+            resumeValue?: unknown;
+        }>;
+    }>;
+}): PendingInterrupt[];