@juno-ai/bind 9.0.0 → 10.0.0

package/plugins/dispatch.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Authoring and dispatching a tool: the mechanical half of writing one, which
+ * every host had been reimplementing.
+ *
+ * A `ToolPlugin` is a bundle whose `execute` dispatches by tool name, because
+ * that is the shape a plugin with shared setup wants. It is not the shape a
+ * *single* tool wants, and a host with a flat list of tools ends up writing the
+ * same four steps for each: switch on the name, parse the arguments, map a
+ * parse failure onto a result the model can read, and encode the result as a
+ * `role:"tool"` message. All four are mechanical, all four are easy to get
+ * subtly wrong (the usual bug is a parse failure thrown rather than returned,
+ * which turns a recoverable "you passed the wrong argument" into a dead run),
+ * and none of them are where a host's judgement belongs.
+ *
+ * {@link defineTool} and {@link pluginFromTools} do those steps. They are a
+ * convenience over the vocabulary in `./tool`, not a replacement for it: a
+ * plugin that needs shared setup across its tools, or whose dispatch is genuinely
+ * one decision, still writes `ToolPlugin` by hand and loses nothing.
+ */
+import { z } from "zod";
+import type OpenAI from "openai";
+import type { ToolAnnotations, ToolDef, ToolPlugin, ToolResult } from "./tool.js";
+/**
+ * A tool that carries its own implementation.
+ *
+ * `execute` takes `unknown` and does the parsing itself, which is what lets a
+ * heterogeneous array of tools — each with a different argument type — sit in
+ * one `tools: DefinedTool[]` without a cast anywhere. It also makes a defined
+ * tool independently useful: dispatch it directly and you still get argument
+ * validation, without going through {@link pluginFromTools}.
+ */
+export interface DefinedTool<TCtx, TContentPart = unknown> extends ToolDef {
+    /**
+     * Run this tool against unvalidated arguments, parsing with `parameters`
+     * first. A parse failure comes back as a `validation` result rather than a
+     * throw, because the model can fix it on the next turn and a throw would end
+     * the run instead.
+     *
+     * Does **not** apply `normalizeArgs` — that is the dispatcher's step, run
+     * before the idempotency hash. Applying it here too would apply it twice.
+     */
+    execute(args: unknown, ctx: TCtx): Promise<ToolResult<TContentPart>> | ToolResult<TContentPart>;
+}
+/**
+ * The declaration side of {@link defineTool}. `schema` is the single source of
+ * truth: it is what the model is shown (converted to JSON Schema) and what the
+ * model's arguments are validated against, so the two can never drift.
+ */
+export interface ToolSpec<TSchema extends z.ZodType, TCtx, TContentPart> {
+    readonly name: string;
+    readonly description: string;
+    readonly schema: TSchema;
+    execute(args: z.output<TSchema>, ctx: TCtx): Promise<ToolResult<TContentPart>> | ToolResult<TContentPart>;
+    readonly annotations?: ToolAnnotations;
+    readonly hidden?: boolean;
+    readonly supportsProgress?: boolean;
+    /**
+     * Pre-computed JSON Schema, for a tool authored as raw JSON Schema rather
+     * than zod. `schema` still validates the arguments.
+     *
+     * It is also the one way to author a tool whose `schema` is not
+     * parse-idempotent (a `.transform()`, which `z.toJSONSchema` refuses to
+     * convert). Doing so makes the schema's idempotence your responsibility:
+     * `execute` parses defensively, so a dispatcher that already parsed hands
+     * this a value the schema must still accept.
+     */
+    readonly rawJsonSchema?: Record<string, unknown>;
+    /**
+     * Pure canonicalization of already-validated arguments — sorting a set-like
+     * array, lower-casing a key. Runs **after** the schema parse, per
+     * `ToolDef.normalizeArgs`, so it receives defaults already applied and a
+     * shape it can rely on; a normalizer handed raw model output would have to
+     * re-check everything the schema just checked.
+     *
+     * Applied by the **dispatcher**, before the idempotency hash — not by
+     * `execute`. It must be idempotent anyway (`f(f(x)) === f(x)`), because
+     * nothing can stop a host applying it more than once.
+     */
+    readonly normalizeArgs?: (args: z.output<TSchema>) => z.output<TSchema>;
+    readonly summarizeActivity?: (args: unknown) => string | null;
+}
+/**
+ * Define one tool from its schema and implementation.
+ *
+ * The returned value is an ordinary {@link ToolDef} with an `execute` attached,
+ * so it drops into anything that already consumes `ToolDef` — a catalog
+ * renderer, a schema regression test — without an adapter.
+ */
+export declare function defineTool<TSchema extends z.ZodType, TCtx = unknown, TContentPart = unknown>(spec: ToolSpec<TSchema, TCtx, TContentPart>): DefinedTool<TCtx, TContentPart>;
+export interface PluginSpec<TCtx, TContentPart> {
+    readonly name: string;
+    readonly description: string;
+    readonly tools: readonly DefinedTool<TCtx, TContentPart>[];
+    readonly systemMessage?: string;
+    readonly icon?: string;
+    readonly isAvailable?: () => boolean;
+}
+/**
+ * Bundle self-contained tools into a {@link ToolPlugin}.
+ *
+ * The generated `execute` is only a name resolver — each tool already validates
+ * its own arguments (see {@link DefinedTool}). An unknown name is a *returned*
+ * `not_found` failure rather than a throw: it happens whenever a resumed
+ * session's history references a tool that has since been retired, and a run
+ * should survive that.
+ */
+export declare function pluginFromTools<TCtx = unknown, TContentPart = unknown>(spec: PluginSpec<TCtx, TContentPart>): ToolPlugin<TCtx, TContentPart>;
+/**
+ * Convert a tool to the wire definition a provider is shown.
+ *
+ * `rawJsonSchema` wins when present (an MCP tool forwards its server's schema
+ * verbatim); otherwise the zod schema is converted. Either way the result goes
+ * through {@link sanitizeToolSchema}, because a strict validator rejects the
+ * *entire* request on the first unsupported construct — one bad tool takes
+ * every other tool down with it.
+ *
+ * `wireName` exists because tool naming is host policy: Monad encodes
+ * `plugin__tool` so it can route a call back to its plugin, and a host with a
+ * flat namespace does not need to. Defaults to the tool's own name.
+ *
+ * Returns the narrow `ChatCompletionFunctionTool` rather than the
+ * `ChatCompletionTool` union — a tool built from a parameter schema is always
+ * the function variant, and returning the union would make every caller narrow
+ * past a `custom` case that cannot occur. It still assigns to the union.
+ *
+ * Converts whatever it is handed. **Skip `hidden` tools in the caller's catalog
+ * loop** — a hidden tool stays runnable so a resumed session's history still
+ * resolves, but advertising it puts a retired tool back in front of the model.
+ */
+export declare function toolWireDefinition(tool: ToolDef, wireName?: string): OpenAI.ChatCompletionFunctionTool;

package/plugins/dispatch.js

@@ -0,0 +1,241 @@
+/**
+ * Authoring and dispatching a tool: the mechanical half of writing one, which
+ * every host had been reimplementing.
+ *
+ * A `ToolPlugin` is a bundle whose `execute` dispatches by tool name, because
+ * that is the shape a plugin with shared setup wants. It is not the shape a
+ * *single* tool wants, and a host with a flat list of tools ends up writing the
+ * same four steps for each: switch on the name, parse the arguments, map a
+ * parse failure onto a result the model can read, and encode the result as a
+ * `role:"tool"` message. All four are mechanical, all four are easy to get
+ * subtly wrong (the usual bug is a parse failure thrown rather than returned,
+ * which turns a recoverable "you passed the wrong argument" into a dead run),
+ * and none of them are where a host's judgement belongs.
+ *
+ * {@link defineTool} and {@link pluginFromTools} do those steps. They are a
+ * convenience over the vocabulary in `./tool`, not a replacement for it: a
+ * plugin that needs shared setup across its tools, or whose dispatch is genuinely
+ * one decision, still writes `ToolPlugin` by hand and loses nothing.
+ */
+import { z } from "zod";
+import { sanitizeToolSchema } from "../tools/sanitize-schema.js";
+import { stripControlChars } from "../tools/control-chars.js";
+/**
+ * Define one tool from its schema and implementation.
+ *
+ * The returned value is an ordinary {@link ToolDef} with an `execute` attached,
+ * so it drops into anything that already consumes `ToolDef` — a catalog
+ * renderer, a schema regression test — without an adapter.
+ */
+export function defineTool(spec) {
+    // Hoisted so the closures below narrow it once; reading `spec.normalizeArgs`
+    // inside each would re-widen it to possibly-undefined on every call.
+    const normalize = spec.normalizeArgs;
+    return {
+        name: spec.name,
+        description: spec.description,
+        parameters: spec.schema,
+        ...(spec.annotations === undefined ? {} : { annotations: spec.annotations }),
+        ...(spec.hidden === undefined ? {} : { hidden: spec.hidden }),
+        ...(spec.supportsProgress === undefined
+            ? {}
+            : { supportsProgress: spec.supportsProgress }),
+        ...(spec.rawJsonSchema === undefined
+            ? {}
+            : { rawJsonSchema: spec.rawJsonSchema }),
+        ...(normalize === undefined
+            ? {}
+            : {
+                // Handed straight through, NOT re-parsed. `ToolDef.normalizeArgs` is
+                // documented as post-parse canonicalization and every dispatcher
+                // calls it that way, so re-parsing here was pure harm: it ran the
+                // schema a second time, and on any input the schema could not
+                // re-accept it silently returned the *un-normalized* value — which
+                // is the idempotency hash, so two equivalent calls stopped agreeing
+                // exactly when canonicalization mattered most.
+                //
+                // The cast is confined to this line. It is safe by the same contract:
+                // the value is post-parse, so it is a `z.output<TSchema>`.
+                normalizeArgs: normalize,
+            }),
+        ...(spec.summarizeActivity === undefined
+            ? {}
+            : { summarizeActivity: spec.summarizeActivity }),
+        // Parses, and deliberately does NOT normalize.
+        //
+        // Normalization is the dispatcher's step — it has to happen before the
+        // idempotency hash, which the harness never sees — and a dispatcher that
+        // applies `normalizeArgs` and then calls this would otherwise apply it
+        // twice. Once is a no-op for an idempotent canonicalizer and wrong for
+        // anything else (`n => n + 1` reached `execute` as `n + 2`).
+        //
+        // The parse stays because this is also the entry point for a host with no
+        // dispatcher of its own, and re-parsing an already-parsed value is a
+        // no-op for any schema that can legally be a tool schema — `.transform()`
+        // cannot (`z.toJSONSchema` rejects it, so the tool could never be
+        // advertised), and `.default()` / `z.coerce` are both parse-idempotent.
+        // A tool that supplies `rawJsonSchema` to bypass that conversion owns the
+        // requirement itself; see `ToolSpec.rawJsonSchema`.
+        execute: (args, ctx) => {
+            const parsed = spec.schema.safeParse(args);
+            if (!parsed.success) {
+                return validationFailure(spec.name, args, parsed.error);
+            }
+            return spec.execute(parsed.data, ctx);
+        },
+    };
+}
+/**
+ * Cap on the issues quoted back. A tool taking an array validates every
+ * element, so one malformed argument can produce thousands — and the result
+ * message is not transient: it is appended to the transcript and re-sent to
+ * the provider on every remaining turn of the run. Ten is enough for a model
+ * to act on; the rest are counted, not quoted.
+ */
+const MAX_QUOTED_ISSUES = 10;
+/**
+ * Quote model-supplied text back at it safely. A zod issue path can contain
+ * input *keys* (via `z.record`), and this string reaches a host's logs and, in
+ * Monad, a member-visible activity row — so control characters are replaced
+ * with a space rather than deleted, keeping adjacent words apart, and the
+ * result is bounded.
+ */
+function safeQuote(text) {
+    // `Array.from` iterates code points, so the bound cannot slice an astral
+    // character in half and put a lone surrogate in the transcript.
+    return Array.from(stripControlChars(text, " ")).slice(0, 200).join("");
+}
+/** How a tool's arguments failed to parse, phrased for the model. */
+function validationFailure(toolName, args, error) {
+    const quoted = error.issues.slice(0, MAX_QUOTED_ISSUES).map((issue) => {
+        const path = issue.path.map((segment) => String(segment)).join(".");
+        const where = path ? safeQuote(path) : "(top level)";
+        // zod renders an omitted key as "expected string, received undefined",
+        // which reads as a *type* error — and a model that reads it that way
+        // retries with the literal string "undefined" instead of supplying the
+        // field. Resolving the path against the input is what tells the two apart.
+        const omitted = issue.code === "invalid_type" && pathIsAbsent(args, issue.path);
+        return `- ${where}: ${omitted ? "required, but missing" : safeQuote(issue.message)}`;
+    });
+    const hidden = error.issues.length - quoted.length;
+    return {
+        success: false,
+        kind: "validation",
+        // Leads with the outcome, itemizes what to change, and ends with the
+        // action — the shape `ABORTED_TOOL_CALL_MESSAGE` established. A message
+        // that only diagnoses leaves the model to guess whether to retry.
+        error: `Invalid arguments for ${toolName} — the call did not run and nothing changed.\n` +
+            quoted.join("\n") +
+            (hidden > 0 ? `\n- (and ${hidden} more problems)` : "") +
+            `\nFix these fields and call ${toolName} again with the same intent. ` +
+            `Do not resend the same arguments.`,
+    };
+}
+/**
+ * Is the key a zod issue points at genuinely absent?
+ *
+ * Checked with `in` rather than by comparing the value to `undefined`, so a
+ * field explicitly present as `undefined` is reported as the wrong type rather
+ * than as missing. `JSON.parse` never produces `undefined`, so this only
+ * matters for a host dispatching pre-parsed arguments — which is exactly the
+ * caller `defineTool` supports.
+ */
+function pathIsAbsent(value, path) {
+    let current = value;
+    for (const segment of path) {
+        if (current === null || typeof current !== "object")
+            return true;
+        if (!(segment in current))
+            return true;
+        current = current[segment];
+    }
+    return false;
+}
+/**
+ * Bundle self-contained tools into a {@link ToolPlugin}.
+ *
+ * The generated `execute` is only a name resolver — each tool already validates
+ * its own arguments (see {@link DefinedTool}). An unknown name is a *returned*
+ * `not_found` failure rather than a throw: it happens whenever a resumed
+ * session's history references a tool that has since been retired, and a run
+ * should survive that.
+ */
+export function pluginFromTools(spec) {
+    const byName = new Map();
+    for (const tool of spec.tools) {
+        if (byName.has(tool.name)) {
+            // Thrown, not returned: two tools sharing a name is an authoring mistake
+            // that makes one of them permanently unreachable, and it should fail at
+            // construction rather than at whichever call happens to resolve first.
+            throw new Error(`pluginFromTools: plugin "${spec.name}" declares two tools named "${tool.name}".`);
+        }
+        byName.set(tool.name, tool);
+    }
+    return {
+        name: spec.name,
+        description: spec.description,
+        ...(spec.systemMessage === undefined
+            ? {}
+            : { systemMessage: spec.systemMessage }),
+        ...(spec.icon === undefined ? {} : { icon: spec.icon }),
+        ...(spec.isAvailable === undefined
+            ? {}
+            : { isAvailable: spec.isAvailable }),
+        tools: [...spec.tools],
+        async execute(toolName, args, ctx) {
+            const tool = byName.get(toolName);
+            if (!tool) {
+                return {
+                    success: false,
+                    kind: "not_found",
+                    // Leads with the outcome and ends with an action. A bare "unknown
+                    // tool" is indistinguishable from a transient miss, and a model
+                    // reading it that way re-issues the same call every iteration until
+                    // the budget runs out — which is exactly the state this arm exists
+                    // to survive (a resumed session referencing a retired tool).
+                    error: `No tool named "${safeQuote(toolName)}" exists on plugin "${spec.name}" — ` +
+                        `nothing ran and nothing changed, and calling it again will fail the ` +
+                        `same way. Use one of the tools currently listed for "${spec.name}", ` +
+                        `or finish the task without it.`,
+                };
+            }
+            return await tool.execute(args, ctx);
+        },
+    };
+}
+/**
+ * Convert a tool to the wire definition a provider is shown.
+ *
+ * `rawJsonSchema` wins when present (an MCP tool forwards its server's schema
+ * verbatim); otherwise the zod schema is converted. Either way the result goes
+ * through {@link sanitizeToolSchema}, because a strict validator rejects the
+ * *entire* request on the first unsupported construct — one bad tool takes
+ * every other tool down with it.
+ *
+ * `wireName` exists because tool naming is host policy: Monad encodes
+ * `plugin__tool` so it can route a call back to its plugin, and a host with a
+ * flat namespace does not need to. Defaults to the tool's own name.
+ *
+ * Returns the narrow `ChatCompletionFunctionTool` rather than the
+ * `ChatCompletionTool` union — a tool built from a parameter schema is always
+ * the function variant, and returning the union would make every caller narrow
+ * past a `custom` case that cannot occur. It still assigns to the union.
+ *
+ * Converts whatever it is handed. **Skip `hidden` tools in the caller's catalog
+ * loop** — a hidden tool stays runnable so a resumed session's history still
+ * resolves, but advertising it puts a retired tool back in front of the model.
+ */
+export function toolWireDefinition(tool, wireName = tool.name) {
+    const jsonSchema = tool.rawJsonSchema ??
+        // zod's converter is typed as its own JSON Schema shape; the wire wants a
+        // plain object, which is what it structurally is.
+        z.toJSONSchema(tool.parameters);
+    return {
+        type: "function",
+        function: {
+            name: wireName,
+            description: tool.description,
+            parameters: sanitizeToolSchema(jsonSchema),
+        },
+    };
+}

package/plugins/index.d.ts

@@ -1,3 +1,5 @@
 export { hasContentParts, type ToolAnnotations, type ToolDef, type ToolFailureKind, type ToolPlugin, type ToolResult, type RegistrablePlugin, type SuspendDirective, } from "./tool.js";
+export { defineTool, pluginFromTools, toolWireDefinition, type DefinedTool, type ToolSpec, type PluginSpec, } from "./dispatch.js";
+export { toolResultMessage } from "./tool-message.js";
 export { createToolRegistry, type PluginSummary, type ToolRegistry, type ToolRegistryOptions, } from "./registry.js";
 export { rehydrateActivation, initialActivePlugins, partitionPluginCatalog, type ActivationDropReason, type CatalogPartition, type DroppedActivation, type RehydrateOptions, type RehydrateResult, } from "./activation.js";

package/plugins/index.js

@@ -1,3 +1,5 @@
 export { hasContentParts, } from "./tool.js";
+export { defineTool, pluginFromTools, toolWireDefinition, } from "./dispatch.js";
+export { toolResultMessage } from "./tool-message.js";
 export { createToolRegistry, } from "./registry.js";
 export { rehydrateActivation, initialActivePlugins, partitionPluginCatalog, } from "./activation.js";

package/plugins/tool-message.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Encoding a tool result as the message that answers its call.
+ *
+ * Deliberately its own module with **type-only** imports: the tool loop uses
+ * this encoder, and `./dispatch` imports zod at runtime for schema conversion.
+ * Folding the two together would pull zod into the module graph of every host
+ * that imports only `@juno-ai/bind/loop`, which today needs none of it.
+ */
+import type OpenAI from "openai";
+import type { ToolResult } from "./tool.js";
+/**
+ * Encode a {@link ToolResult} as the `role:"tool"` message that answers a call.
+ *
+ * This is the encoding the loop itself synthesizes for a failed or refused
+ * call, exported so a host's own results are shaped identically — a model that
+ * sees `{"success":false,"kind":…,"error":…}` from the harness and something
+ * else from the host has to learn two error formats in one transcript.
+ *
+ * `contentParts` and `suspend` are deliberately omitted: both are control
+ * signals for the host, not text for the model. A host relaying multimodal
+ * parts attaches them alongside this message.
+ */
+export declare function toolResultMessage(toolCallId: string, result: ToolResult<unknown>): OpenAI.ChatCompletionToolMessageParam;

package/plugins/tool-message.js

@@ -0,0 +1,31 @@
+/**
+ * Encode a {@link ToolResult} as the `role:"tool"` message that answers a call.
+ *
+ * This is the encoding the loop itself synthesizes for a failed or refused
+ * call, exported so a host's own results are shaped identically — a model that
+ * sees `{"success":false,"kind":…,"error":…}` from the harness and something
+ * else from the host has to learn two error formats in one transcript.
+ *
+ * `contentParts` and `suspend` are deliberately omitted: both are control
+ * signals for the host, not text for the model. A host relaying multimodal
+ * parts attaches them alongside this message.
+ */
+export function toolResultMessage(toolCallId, result) {
+    const body = result.success
+        ? { success: true, data: result.data }
+        : {
+            success: false,
+            // `success` and `kind` lead so a model skimming a batch of results
+            // reads the verdict before the prose, and the order is fixed —
+            // `success`, `kind`, `error`, then `data` when present — so the same
+            // result always serializes to the same bytes.
+            ...(result.kind === undefined ? {} : { kind: result.kind }),
+            error: result.error,
+            ...(result.data === undefined ? {} : { data: result.data }),
+        };
+    return {
+        role: "tool",
+        tool_call_id: toolCallId,
+        content: JSON.stringify(body),
+    };
+}

package/testing/index.d.ts

@@ -0,0 +1,153 @@
+/**
+ * `@juno-ai/bind/testing` — fixtures for testing an agent against the harness
+ * without a provider, a network, or a credential.
+ *
+ * The loop's hardest behaviour to get right is also the hardest to test: what
+ * happens across several turns, with several tools, when one of them fails or
+ * the run is cut short. Reaching that state normally means mocking a streaming
+ * chat-completions client, which is a lot of scaffolding to write before the
+ * first assertion — so most consumers write it once, badly, and then only test
+ * the happy path.
+ *
+ * These are the fixtures this package's own cross-module suites use, published
+ * so a consumer does not rewrite them. They are ordinary values with no magic:
+ * a scripted model is a queue of prepared turns, and a harness is a
+ * {@link ToolLoopParams} you can override any field of.
+ *
+ * ```ts
+ * import { loopHarness, toolCall, toolCallTurn, finalAnswer } from "@juno-ai/bind/testing";
+ * import { runToolLoop } from "@juno-ai/bind/loop";
+ *
+ * const h = loopHarness([
+ *   toolCallTurn([toolCall("search", { q: "bind" })]),
+ *   finalAnswer("Found it."),
+ * ]);
+ * const { stopReason, stats } = await runToolLoop(h.params);
+ * expect(stopReason).toBe("done");
+ * expect(h.ran).toEqual(["search"]);
+ * ```
+ *
+ * This module ships in the published package rather than living beside the
+ * tests, so it is held to the same portability fences as `src/`: no Node
+ * builtins, no `process`, no framework, peer dependencies only.
+ */
+import type OpenAI from "openai";
+import type { ToolCallOutcome, ToolLoopParams, ToolLoopState } from "../loop/tool-loop.js";
+import type { TurnStreamEvent, TurnStreamSink } from "../completion/text-stream.js";
+/**
+ * A sink that records what it was handed. `retractable` is the whole decision
+ * the text stream turns on, so it is the one required argument.
+ */
+export declare function recordingSink(retractable: boolean): TurnStreamSink & {
+    readonly events: TurnStreamEvent[];
+};
+export declare function freshState(overrides?: Partial<ToolLoopState>): ToolLoopState;
+/** An assistant message, with tool calls when given names. */
+export declare function assistant(content: string | null, toolCalls?: ReadonlyArray<{
+    id: string;
+    name: string;
+    args?: string;
+}>): OpenAI.ChatCompletionMessage;
+/**
+ * A successful tool result, encoded exactly as production encodes one.
+ *
+ * Routed through `toolResultMessage` rather than a bare `JSON.stringify` so a
+ * fixture-built transcript has the same shape a real run produces. A fixture
+ * that invents its own envelope reintroduces the "two formats in one
+ * transcript" problem that encoder exists to remove, and any test asserting on
+ * transcript shape would be pinning something production never emits.
+ * (`tool-message` is type-only internally, so this pulls no zod into
+ * `@juno-ai/bind/testing`.)
+ */
+export declare function toolOutcome(id: string, data?: unknown): ToolCallOutcome;
+/** One tool call in a scripted turn. */
+export interface ScriptedToolCall {
+    /** Defaults to the tool name — unique across the whole script, see
+     *  {@link scriptedModel}, which rejects a duplicate rather than letting it
+     *  produce a baffling transcript failure ten frames deep in the loop. */
+    readonly id: string;
+    readonly name: string;
+    readonly args: string;
+}
+/**
+ * Declare one tool call. `args` is serialized for you; pass a string to
+ * script malformed JSON on purpose (which is a case worth testing — models
+ * emit it).
+ */
+export declare function toolCall(name: string, args?: unknown, id?: string): ScriptedToolCall;
+/** Per-turn accounting overrides. Defaults are small non-zero numbers so a
+ *  test asserting "usage was recorded" cannot pass on an all-zero fixture. */
+export interface TurnCost {
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+    readonly costCents?: number;
+    /**
+     * Provider-reported cached input tokens. Omit it to script a transport that
+     * cannot report one — the run's total then skips this turn rather than
+     * counting a zero, which is the distinction `RunStats.cachedInputTokens`
+     * turns on. Pass `null` for the same effect explicitly.
+     */
+    readonly cachedInputTokens?: number | null;
+}
+/** One scripted model turn: the message to return, plus its usage. */
+export interface ModelResponse extends TurnCost {
+    readonly message: OpenAI.ChatCompletionMessage;
+}
+/** A turn where the model asks for tools, optionally alongside some text. */
+export declare function toolCallTurn(calls: readonly ScriptedToolCall[], opts?: TurnCost & {
+    readonly content?: string;
+}): ModelResponse;
+/**
+ * A turn with text and no tool calls — which is how the loop *ends*. A script
+ * that omits it runs to `maxIterations` (or exhausts the queue), so this is
+ * the difference between testing `stopReason: "done"` and testing
+ * `"iteration_limit"`.
+ */
+export declare function finalAnswer(content: string, opts?: TurnCost): ModelResponse;
+/**
+ * Turn a script into a `callModel` implementation.
+ *
+ * Exhausting the queue throws rather than looping forever or returning an
+ * empty turn: a script that ran out is a test that did not describe what it
+ * meant to, and the loop's own `maxIterations` cutoff would otherwise absorb
+ * the mistake and report a plausible-looking `iteration_limit`.
+ */
+export declare function scriptedModel(turns: readonly ModelResponse[]): NonNullable<ToolLoopParams["callModel"]>;
+export interface LoopHarness {
+    params: ToolLoopParams;
+    state: ToolLoopState;
+    /** Ids the loop dispatched, in order. Recorded for you even if you override
+     *  `runToolCall`. */
+    ran: string[];
+    /** Ids whose tool actually reached its side effect. The default
+     *  `runToolCall` records one here on completion, so `ran` and `sideEffects`
+     *  match until an override makes them diverge — a tool that throws, hangs
+     *  past a deadline, or is torn down mid-flight. That divergence is the
+     *  question every cancellation test is really asking. */
+    sideEffects: string[];
+}
+/**
+ * A loop wired to a scripted model queue. `runToolCall` records dispatch and
+ * completion separately, so a test can tell "the loop asked for this call" from
+ * "this call's side effect happened" — the distinction every deadline and
+ * cancellation question turns on.
+ *
+ * Everything is overridable: pass `{ runToolCall }` to make a tool fail,
+ * `{ signal }` to abort mid-batch, `{ now }` to make timings deterministic.
+ */
+export declare function loopHarness(responses: readonly ModelResponse[], overrides?: Partial<ToolLoopParams>): LoopHarness;
+/**
+ * A clock that advances a fixed amount on every read. Makes the model-time and
+ * tool-time figures in `ToolLoopResult.stats` exactly predictable, which
+ * `Date.now` cannot be.
+ */
+export declare function steppingClock(stepMs?: number, startMs?: number): () => number;
+/**
+ * Resolve after `ms` of real time. Kept tiny so suites stay fast.
+ *
+ * Deliberately not cancellable — it is for driving the loop's own micro-timers
+ * inside a test, not for long-lived waiting. Reach for your own scheduler if
+ * you need a wait that outlives the run, so a torn-down run cannot leave a
+ * timer resolving into nothing.
+ */
+export declare function sleep(ms: number): Promise<void>;