@juno-ai/bind 8.0.0 → 10.0.0

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/plugins/tool.d.ts

@@ -80,7 +80,7 @@ export interface ToolDef {
  * status, a retry decision — without matching on the error string, which is
  * brittle and locale-dependent. Plugins should set it explicitly.
  */
-export type ToolFailureKind = "authz" | "validation" | "not_found" | "conflict" | "external" | "system";
+export type ToolFailureKind = "authz" | "validation" | "not_found" | "conflict" | "external" | "not_run" | "system";
 /**
  * Human-in-the-loop suspend directive. A first-party tool returns this on a
  * successful result to **end the run** and record its open tool-call as

package/run/index.d.ts

@@ -1,4 +1,4 @@
 export { RunTimeoutError, createRunDeadline, classifyRunFailure, createCoalescedHeartbeat, unrefTimer, type RunDeadline, type CoalescedHeartbeat, } from "./harness.js";
-export { runToolCallsPooledByTool } from "./tool-batch.js";
+export { runToolCallsPooledByTool, AbortedToolCallError, ABORTED_TOOL_CALL_MESSAGE, type ToolBatchOptions, } from "./tool-batch.js";
 export { rootChain, descendChain, admitChildRun, createPollSchedule, type ChainRef, type ChainRule, type ChildAdmission, type PollStep, type PollSchedule, type PollScheduleOptions, } from "./children.js";
 export { toolCallReceiptKeyString, canonicalJson, toolCallArgsHash, decideToolCallReceipt, type ToolCallReceiptKey, type DigestFn, type ReceiptState, type EffectResumability, type ReceiptDecision, } from "./receipts.js";

package/run/index.js

@@ -1,4 +1,4 @@
 export { RunTimeoutError, createRunDeadline, classifyRunFailure, createCoalescedHeartbeat, unrefTimer, } from "./harness.js";
-export { runToolCallsPooledByTool } from "./tool-batch.js";
+export { runToolCallsPooledByTool, AbortedToolCallError, ABORTED_TOOL_CALL_MESSAGE, } from "./tool-batch.js";
 export { rootChain, descendChain, admitChildRun, createPollSchedule, } from "./children.js";
 export { toolCallReceiptKeyString, canonicalJson, toolCallArgsHash, decideToolCallReceipt, } from "./receipts.js";

package/run/tool-batch.d.ts

@@ -12,5 +12,55 @@ import type OpenAI from "openai";
  * harness-owned, while the shape a host derives from a completed call (which
  * plugin activated, whether the run should compact, a suspend directive, …)
  * stays with the host.
+ *
+ * **`signal` bounds the batch, and bounding it is the point.** A batch of many
+ * calls to one tool runs five at a time, so the rest sit queued — and without a
+ * signal the pool claims every one of them however long ago the run's deadline
+ * fired or the user pressed stop. Each queued call is a side effect nobody
+ * wants any more: a write, an email, a third-party POST. Once the signal
+ * aborts, workers stop claiming new work.
+ *
+ * Calls that never ran still come back — as `rejected` with an
+ * {@link AbortedToolCallError} — because every `tool_call_id` in the assistant
+ * message needs a response either way, and a caller that received a shorter
+ * array than it passed would silently mispair the rest. A call already in
+ * flight is left alone: this cannot reach inside a host's tool, and cancelling
+ * one mid-write is the host's problem to solve with the same signal.
+ */
+/**
+ * The message a refused call carries into the transcript, and therefore **into
+ * the model's next turn**. Shared by both refusal sites — the pool and the
+ * loop's serial phase — because to the only reader they are the same fact, and
+ * two literals for one fact drift.
+ *
+ * Three things it deliberately does *not* do. It does not name the batch, the
+ * worker, or the claim: those are this module's internals, the model cannot act
+ * on them, and they appear nowhere else in its context. It does not interpolate
+ * the call id, which the `tool` message's own `tool_call_id` already carries —
+ * restating it spends the sentence's most-attended position on something the
+ * reader has. And it does not lead with the cause: the actionable fact is that
+ * *nothing happened*, and a model skimming a batch of results reads the first
+ * clause.
+ */
+export declare const ABORTED_TOOL_CALL_MESSAGE: string;
+/**
+ * A call the batch refused because it was aborted before any worker claimed it.
+ *
+ * Carries the id as a **field** rather than in the message, so a host's
+ * rejection observer and operator log can filter on it (`CLAUDE.md`: identifying
+ * context is a field, not string interpolation).
  */
-export declare function runToolCallsPooledByTool<TOutcome>(calls: OpenAI.ChatCompletionMessageToolCall[], run: (tc: OpenAI.ChatCompletionMessageToolCall) => Promise<TOutcome>): Promise<PromiseSettledResult<TOutcome>[]>;
+export declare class AbortedToolCallError extends Error {
+    readonly toolCallId: string;
+    readonly name = "AbortedToolCallError";
+    constructor(toolCallId: string);
+}
+export interface ToolBatchOptions {
+    /**
+     * Stop claiming queued calls once this aborts. Combine a run deadline with a
+     * cancellation signal (`AbortSignal.any`) before passing it — the pool does
+     * not care which one fired, only that no further work should start.
+     */
+    readonly signal?: AbortSignal | undefined;
+}
+export declare function runToolCallsPooledByTool<TOutcome>(calls: OpenAI.ChatCompletionMessageToolCall[], run: (tc: OpenAI.ChatCompletionMessageToolCall) => Promise<TOutcome>, options?: ToolBatchOptions): Promise<PromiseSettledResult<TOutcome>[]>;

package/run/tool-batch.js

@@ -36,10 +36,57 @@ function poolKey(call) {
  * harness-owned, while the shape a host derives from a completed call (which
  * plugin activated, whether the run should compact, a suspend directive, …)
  * stays with the host.
+ *
+ * **`signal` bounds the batch, and bounding it is the point.** A batch of many
+ * calls to one tool runs five at a time, so the rest sit queued — and without a
+ * signal the pool claims every one of them however long ago the run's deadline
+ * fired or the user pressed stop. Each queued call is a side effect nobody
+ * wants any more: a write, an email, a third-party POST. Once the signal
+ * aborts, workers stop claiming new work.
+ *
+ * Calls that never ran still come back — as `rejected` with an
+ * {@link AbortedToolCallError} — because every `tool_call_id` in the assistant
+ * message needs a response either way, and a caller that received a shorter
+ * array than it passed would silently mispair the rest. A call already in
+ * flight is left alone: this cannot reach inside a host's tool, and cancelling
+ * one mid-write is the host's problem to solve with the same signal.
+ */
+/**
+ * The message a refused call carries into the transcript, and therefore **into
+ * the model's next turn**. Shared by both refusal sites — the pool and the
+ * loop's serial phase — because to the only reader they are the same fact, and
+ * two literals for one fact drift.
+ *
+ * Three things it deliberately does *not* do. It does not name the batch, the
+ * worker, or the claim: those are this module's internals, the model cannot act
+ * on them, and they appear nowhere else in its context. It does not interpolate
+ * the call id, which the `tool` message's own `tool_call_id` already carries —
+ * restating it spends the sentence's most-attended position on something the
+ * reader has. And it does not lead with the cause: the actionable fact is that
+ * *nothing happened*, and a model skimming a batch of results reads the first
+ * clause.
  */
-export async function runToolCallsPooledByTool(calls, run) {
+export const ABORTED_TOOL_CALL_MESSAGE = "This call was never started, so nothing happened and nothing changed. " +
+    "The run is ending — do not retry it and do not report it as a failure.";
+/**
+ * A call the batch refused because it was aborted before any worker claimed it.
+ *
+ * Carries the id as a **field** rather than in the message, so a host's
+ * rejection observer and operator log can filter on it (`CLAUDE.md`: identifying
+ * context is a field, not string interpolation).
+ */
+export class AbortedToolCallError extends Error {
+    toolCallId;
+    name = "AbortedToolCallError";
+    constructor(toolCallId) {
+        super(ABORTED_TOOL_CALL_MESSAGE);
+        this.toolCallId = toolCallId;
+    }
+}
+export async function runToolCallsPooledByTool(calls, run, options = {}) {
     if (calls.length === 0)
         return [];
+    const signal = options.signal;
     const results = new Array(calls.length);
     const groups = new Map();
     for (let i = 0; i < calls.length; i++) {
@@ -69,6 +116,17 @@ export async function runToolCallsPooledByTool(calls, run) {
                 if (pos >= indices.length)
                     return;
                 const callIdx = indices[pos];
+                // Checked at claim time rather than before the loop: a batch that
+                // was fine when it started can be aborted while its first workers
+                // are in flight, and that is the ordinary case — the deadline fires
+                // or the user hits stop DURING the batch, not before it.
+                if (signal?.aborted === true) {
+                    results[callIdx] = {
+                        status: "rejected",
+                        reason: new AbortedToolCallError(calls[callIdx].id),
+                    };
+                    continue;
+                }
                 try {
                     const value = await run(calls[callIdx]);
                     results[callIdx] = { status: "fulfilled", value };

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>;