@juno-ai/bind 8.0.0 → 10.0.0

package/loop/tool-loop.js

@@ -1,4 +1,56 @@
-import { runToolCallsPooledByTool } from "../run/tool-batch.js";
+import { runToolCallsPooledByTool, AbortedToolCallError, } from "../run/tool-batch.js";
+import { accumulateAuxiliarySpend, accumulateToolCall, accumulateTurn, emptyRunStats, } from "../contracts/turn.js";
+import { toolResultMessage } from "../plugins/tool-message.js";
+// Imported from the module, not the `tools` barrel: this subpath's runtime
+// graph is deliberately free of `zod`, which the barrel's siblings pull in.
+import { stripControlChars } from "../tools/control-chars.js";
+/**
+ * A tool asked the loop to activate a plugin or an instruction module, and the
+ * port that would do it was not wired.
+ *
+ * Reported through `onToolCallRejected` rather than thrown: the call itself
+ * succeeded and its tool message is already correct, so failing the run would
+ * be worse than the missing activation. But it must not be silent — before
+ * these ports were optional this was a compile error, and the runtime symptom
+ * (an agent that keeps loading a plugin it never receives) points nowhere near
+ * the cause.
+ *
+ * Match on `error.name === "MissingActivationPortError"` rather than
+ * `instanceof` if you consume this package from a projected or re-bundled copy
+ * — two copies of a class in one module graph make `instanceof` silently
+ * false, and this package is Copybara-projected and republished.
+ */
+export class MissingActivationPortError extends Error {
+    port;
+    name = "MissingActivationPortError";
+    constructor(port) {
+        super(`A tool outcome asked the loop to activate, but no \`${port}\` was supplied. ` +
+            `Wire the port, or stop returning activation fields from \`runToolCall\`.`);
+        this.port = port;
+    }
+}
+/**
+ * The key a tool call is measured under in {@link RunStats.toolTimeBreakdownMs}.
+ *
+ * Mirrors the batch's pooling key rather than reading `tc.function.name`: the
+ * wire union has a `custom` member with its name on a different field, and a
+ * host may assemble a call with no `function` at all. Synthetic keys are
+ * fenced with `__` so they cannot collide with a real tool called `custom`.
+ */
+function toolCallStatsKey(tc) {
+    switch (tc.type) {
+        case "function":
+            return tc.function?.name ?? "__unnamed__";
+        case "custom":
+            return `__custom__:${tc.custom?.name ?? "unnamed"}`;
+        default: {
+            // Not `never`: this union is a third party's, and a member it grows
+            // later must not become a type error in a consumer that never sees one.
+            const unknownCall = tc;
+            return `__${unknownCall.type ?? "unknown"}__`;
+        }
+    }
+}
 /**
  * Repeatedly call the model and execute the tools it requests, until it stops
  * requesting them, a caller stops the loop, a tool suspends the run, or
@@ -11,9 +63,48 @@ import { runToolCallsPooledByTool } from "../run/tool-batch.js";
  * Mutates `state` (messages + token accumulators) in place. That is deliberate
  * rather than a return value: a caller's heartbeat reads live totals off it
  * mid-loop, which a returned result could not provide until the run ended.
+ * The {@link ToolLoopResult} it *returns* is the complementary half — the
+ * run's conclusion, which only exists once the loop is over.
  */
 export async function runToolLoop(params) {
-    const { state, maxIterations, callModel, buildTools, runToolCall, activatePlugins, activateSkills, ensureNotCancelled, throwIfTimedOut, onStatus, onThinking, onAssistantMessage, flushProgress, onProgressUpdate, shouldStop, onTurnWouldEnd, drainInterrupts, onInterruptReceived, needsCompaction, applyCompaction, runsSerially, isFatalToolError, onToolCallRejected, } = params;
+    const { state, maxIterations, callModel, buildTools, runToolCall, activatePlugins, activateSkills, now = Date.now, ensureNotCancelled, throwIfTimedOut, onStatus, signal, onThinking, onAssistantMessage, flushProgress, onProgressUpdate, shouldStop, onTurnWouldEnd, drainInterrupts, onInterruptReceived, needsCompaction, applyCompaction, runsSerially, isFatalToolError, onToolCallRejected, } = params;
+    let stats = emptyRunStats();
+    // The default is the outcome of falling out of the `for` — every other exit
+    // assigns before it breaks. Seeding it here rather than at each `break` means
+    // a future exit path that forgets to set one reports "we ran out of
+    // iterations", which is the conservative lie: it says the run did NOT finish.
+    let stopReason = "iteration_limit";
+    /**
+     * Run one tool call, recording its duration against its tool name.
+     *
+     * Wrapped rather than measured at the two call sites because the serial and
+     * pooled phases both dispatch, and a call that *throws* still consumed the
+     * time — a `finally` is the only way to catch both halves of that in one
+     * place. Refused calls never reach here (the pool rejects them at claim
+     * time), which is exactly why `stats.toolCalls` counts dispatches.
+     */
+    const dispatchToolCall = async (tc) => {
+        const startedAt = now();
+        try {
+            return await runToolCall(tc);
+        }
+        finally {
+            // A throw in a `finally` REPLACES the value the `try` produced, so
+            // measuring a call must never be able to fail. It once could: reading
+            // `tc.function.name` unguarded turned a tool that ran — side effect and
+            // all — into a synthesized "it failed" the model then acted on. The
+            // wire type says `function` is always there; this repo knows better
+            // (`completion/tool-calls.ts` types it optional, and the host's own
+            // dispatcher reads it with an `in` check for exactly this reason).
+            try {
+                stats = accumulateToolCall(stats, toolCallStatsKey(tc), now() - startedAt);
+            }
+            catch {
+                // Accounting is observability. Losing a measurement is survivable;
+                // losing the call's outcome is not.
+            }
+        }
+    };
     // An observer must not be able to change control flow: a host logger that
     // throws while reporting a tool failure would otherwise turn a *reported*
     // failure into a fatal one, which is the opposite of what the report is for.
@@ -29,15 +120,36 @@ export async function runToolLoop(params) {
     // provider count no longer reflects the compacted array, so drop it — the
     // auto-compaction check skips while it's 0 (preventing an immediate
     // re-trigger), and the next turn records a fresh real count.
-    const applyCompactionResult = (result) => {
+    const applyCompactionResult = (result, modelTimeMs) => {
         state.inputTokens += result.inputTokens;
         state.outputTokens += result.outputTokens;
         state.costCents += result.costCents;
+        // Real spend, but not an agent turn — a compaction is the harness talking
+        // to itself. Counting it in `stats.turns` would make that number
+        // incomparable with `maxIterations`.
+        stats = accumulateAuxiliarySpend(stats, {
+            inputTokens: result.inputTokens,
+            outputTokens: result.outputTokens,
+            costCents: result.costCents,
+            cachedInputTokens: result.cachedInputTokens ?? null,
+            modelTimeMs,
+        });
         state.messages.length = 0;
         state.messages.push(...result.messages);
         state.lastPromptTokens = 0;
         state.lastOutputTokens = 0;
     };
+    // Compact, account, then persist — in that order, and timing only the model
+    // pass. `persist` is host I/O; folding it into `modelTimeMs` would inflate
+    // the one number that exists to isolate the provider's contribution.
+    // `compact` is passed in rather than read from the closure so each call site
+    // narrows the optional itself and no non-null assertion is needed.
+    const compactNow = async (compact, trigger) => {
+        const startedAt = now();
+        const compacted = await compact(trigger, state.messages);
+        applyCompactionResult(compacted, now() - startedAt);
+        await compacted.persist();
+    };
     for (let iteration = 0; iteration < maxIterations; iteration++) {
         throwIfTimedOut?.();
         await ensureNotCancelled?.();
@@ -57,6 +169,7 @@ export async function runToolLoop(params) {
         // the real total below is free to correct downward.
         const baseOutputTokens = state.outputTokens;
         let progressHighWater = baseOutputTokens;
+        const turnStartedAt = now();
         const result = await callModel(state.messages, tools.length > 0 ? tools : undefined, 
         // Carry the cumulative tool count alongside the streamed token estimate so
         // the pill shows both; no tools run *during* a model call, so the count is
@@ -67,6 +180,28 @@ export async function runToolLoop(params) {
                 onProgressUpdate(progressHighWater, state.toolCalls);
             }
             : undefined);
+        // Folded through the shared `accumulateTurn` rather than incremented
+        // field-by-field, so `stats` and every other producer of `RunStats` (child
+        // runs, a host's own transport) agree on what a turn contributes — notably
+        // the derived `outputTokensPerSecond`, which is recomputed from totals
+        // rather than averaged.
+        stats = accumulateTurn(stats, {
+            message: result.message,
+            usage: {
+                inputTokens: result.inputTokens,
+                outputTokens: result.outputTokens,
+                // `null` when the transport did not report one — `accumulateTurn`
+                // then contributes nothing for this turn rather than counting a zero,
+                // which is why the total reads as a floor.
+                cachedInputTokens: result.cachedInputTokens ?? null,
+                costCents: result.costCents,
+            },
+            timings: {
+                // Only the transport sees the first byte. The loop sees the call.
+                ttftMs: null,
+                generationMs: now() - turnStartedAt,
+            },
+        });
         state.inputTokens += result.inputTokens;
         state.outputTokens += result.outputTokens;
         state.costCents += result.costCents;
@@ -87,10 +222,16 @@ export async function runToolLoop(params) {
         }
         // Force-flush progress so each iteration bumps the heartbeat at least once.
         await flushProgress?.();
-        // Mid-run stop (e.g. the agent was disabled while running). Emit the
-        // iteration's final progress (the real cumulative token total) before bailing.
-        if (await shouldStop?.()) {
+        // Mid-run stop (e.g. the agent was disabled while running). Asked once and
+        // held, because *whether* to stop and *what to call it* are answered at two
+        // different points below, and asking a host predicate twice could get two
+        // answers.
+        const stopRequested = (await shouldStop?.()) ?? false;
+        if (stopRequested && assistantMessage.tool_calls?.length) {
+            // Still mid-task, and the batch has not run. Emit the iteration's final
+            // progress (the real cumulative token total) before bailing.
             onProgressUpdate?.(state.outputTokens, state.toolCalls);
+            stopReason = "aborted";
             break;
         }
         // Count this iteration's tool batch (a single iteration can request several
@@ -110,9 +251,26 @@ export async function runToolLoop(params) {
             // spin forever.
             const nudge = await onTurnWouldEnd?.(assistantMessage, state.toolCalls);
             if (nudge && nudge.trim()) {
+                // The host's own hook says this turn was NOT a finished answer — it
+                // was a stall worth pushing past. If the host also asked to stop, that
+                // wins, but the outcome is an abort: calling it `done` would report a
+                // run the host itself judged unfinished as a successful answer.
+                if (stopRequested) {
+                    onProgressUpdate?.(state.outputTokens, state.toolCalls);
+                    stopReason = "aborted";
+                    break;
+                }
                 state.messages.push({ role: "user", content: nudge });
                 continue;
             }
+            // A tool-less turn no hook wanted to push past is a finished answer: it
+            // is already in `state.messages` and has already gone out through
+            // `onAssistantMessage`. `done` even when the host asked to stop in the
+            // same breath — reporting `aborted` would have a host badge a delivered
+            // answer as cancelled, or suppress it.
+            if (stopRequested)
+                onProgressUpdate?.(state.outputTokens, state.toolCalls);
+            stopReason = "done";
             break;
         }
         onStatus?.("executing_tools");
@@ -128,22 +286,64 @@ export async function runToolLoop(params) {
         for (let i = 0; i < toolCalls.length; i++) {
             const tc = toolCalls[i];
             if (runsSerially?.(tc)) {
+                // The serial phase runs before the pool and is a loop of its own, so it
+                // needs the same claim-time check — otherwise an aborted batch still
+                // executes every activation call ahead of the pool that refuses to.
+                if (signal?.aborted === true) {
+                    const aborted = new AbortedToolCallError(tc.id);
+                    // Routed through the same three seams as a pooled refusal — fatal
+                    // classification, the rejection observer, and the synthesized answer.
+                    // The serial phase used to do none of them, so one condition produced
+                    // two behaviours depending on which half of the batch a call landed in.
+                    if (isFatalToolError?.(aborted))
+                        throw aborted;
+                    reportRejection(tc.id, aborted);
+                    outcomes[i] = {
+                        toolMessage: toolResultMessage(tc.id, {
+                            success: false,
+                            kind: "not_run",
+                            error: aborted.message,
+                        }),
+                    };
+                    continue;
+                }
                 // Mirror the concurrent batch's graceful error synthesis so a failing
                 // activation call (transient network/DB/timeout) doesn't crash the
                 // run — but let a fatal error propagate for an immediate abort.
                 try {
-                    const outcome = await runToolCall(tc);
+                    const outcome = await dispatchToolCall(tc);
                     outcomes[i] = outcome;
                     if (outcome.loadedPluginName) {
-                        activatePlugins([outcome.loadedPluginName]);
+                        if (activatePlugins) {
+                            activatePlugins([outcome.loadedPluginName]);
+                        }
+                        else {
+                            // The port is optional, but silence here is not. An outcome
+                            // carrying `loadedPluginName` is proof this host's tools DO
+                            // reshape the tool surface, so the port's absence is a wiring
+                            // bug, not a host that doesn't need it. Dropped quietly, the
+                            // model gets a success for `load_plugin`, never sees the tools,
+                            // and re-calls it every iteration until the budget is gone.
+                            reportRejection(tc.id, new MissingActivationPortError("activatePlugins"));
+                        }
                     }
                     if (outcome.loadedSkillRef) {
                         // Auto-load the module's owner plugin first so its tools are active
                         // by the time the agent follows the freshly-injected instructions.
                         if (outcome.autoLoadedPlugins?.length) {
-                            activatePlugins(outcome.autoLoadedPlugins);
+                            if (activatePlugins) {
+                                activatePlugins(outcome.autoLoadedPlugins);
+                            }
+                            else {
+                                reportRejection(tc.id, new MissingActivationPortError("activatePlugins"));
+                            }
+                        }
+                        if (activateSkills) {
+                            await activateSkills([outcome.loadedSkillRef]);
+                        }
+                        else {
+                            reportRejection(tc.id, new MissingActivationPortError("activateSkills"));
                         }
-                        await activateSkills([outcome.loadedSkillRef]);
                     }
                 }
                 catch (err) {
@@ -151,14 +351,10 @@ export async function runToolLoop(params) {
                         throw err;
                     reportRejection(tc.id, err);
                     outcomes[i] = {
-                        toolMessage: {
-                            role: "tool",
-                            tool_call_id: tc.id,
-                            content: JSON.stringify({
-                                success: false,
-                                error: err instanceof Error ? err.message : String(err),
-                            }),
-                        },
+                        toolMessage: toolResultMessage(tc.id, {
+                            success: false,
+                            error: err instanceof Error ? err.message : String(err),
+                        }),
                     };
                 }
                 continue;
@@ -166,7 +362,7 @@ export async function runToolLoop(params) {
             deferredIndices.push(i);
             deferredCalls.push(tc);
         }
-        const settled = await runToolCallsPooledByTool(deferredCalls, runToolCall);
+        const settled = await runToolCallsPooledByTool(deferredCalls, dispatchToolCall, { signal });
         for (let j = 0; j < deferredCalls.length; j++) {
             const origIndex = deferredIndices[j];
             const call = deferredCalls[j];
@@ -183,16 +379,20 @@ export async function runToolLoop(params) {
                     throw settledResult.reason;
                 reportRejection(call.id, settledResult.reason);
                 outcomes[origIndex] = {
-                    toolMessage: {
-                        role: "tool",
-                        tool_call_id: call.id,
-                        content: JSON.stringify({
-                            success: false,
-                            error: settledResult.reason instanceof Error
-                                ? settledResult.reason.message
-                                : String(settledResult.reason),
-                        }),
-                    },
+                    toolMessage: toolResultMessage(call.id, {
+                        success: false,
+                        // A refused call is not a failed one, and the envelope alone
+                        // cannot say so — `success: false` plus a sentence is exactly what
+                        // a tool that ran and failed produces. The discriminant is what
+                        // lets a model (or a host) tell them apart without matching on
+                        // prose. See `ToolFailureKind`.
+                        ...(settledResult.reason instanceof AbortedToolCallError
+                            ? { kind: "not_run" }
+                            : {}),
+                        error: settledResult.reason instanceof Error
+                            ? settledResult.reason.message
+                            : String(settledResult.reason),
+                    }),
                 };
             }
         }
@@ -214,16 +414,20 @@ export async function runToolLoop(params) {
                         state.suspended = { ...outcome.suspend, resumeKind: "answer" };
                         continue; // withhold this call's tool message
                     }
-                    state.messages.push({
-                        role: "tool",
-                        tool_call_id: outcome.suspend.toolCallId,
-                        content: JSON.stringify({
-                            success: false,
-                            error: "You already have one question waiting for an answer, so this " +
-                                "one was not asked. Wait for the pending answer and then ask " +
-                                "this, or finish the turn with what you have.",
-                        }),
-                    });
+                    // Through the shared encoder, and carrying a `kind`, like every
+                    // other synthesized failure. It was the last hand-rolled envelope in
+                    // this file, which meant the harness itself emitted two error shapes
+                    // in one transcript — the exact thing `toolResultMessage` exists to
+                    // prevent. `conflict` because it is a concurrency loss: the call was
+                    // refused only because another question is already open.
+                    state.messages.push(toolResultMessage(outcome.suspend.toolCallId, {
+                        success: false,
+                        kind: "conflict",
+                        error: "This question was not asked — you already have one waiting " +
+                            "for an answer, and only one can be open at a time. When that " +
+                            "answer arrives, ask this one then, or finish the turn with " +
+                            "what you have.",
+                    }));
                     continue;
                 }
                 // `wake` (e.g. sleep_until): fall through and push the tool message, then
@@ -233,6 +437,38 @@ export async function runToolLoop(params) {
             if (outcome.requestCompaction)
                 compactionRequested = true;
         }
+        // An aborted batch ends the run HERE — after every refused call has been
+        // answered in the transcript (so nothing dangles), and before the suspend,
+        // compaction and persist arms below. Two reasons, and the second is the sharp one:
+        //
+        //  - The transcript now contains a synthesized result for every refused
+        //    call. Reaching `saveSession` durably records "these tools failed" for
+        //    work that was never dispatched, and a resumed run reads that as fact —
+        //    the same lie `isFatalToolError` already refuses to tell for a write it
+        //    could not record. The suspend arm `break`s BEFORE the cancellation
+        //    boundary below, so without this check that path persists it.
+        //  - A host whose `signal` is not also reflected by `throwIfTimedOut` /
+        //    `ensureNotCancelled` would otherwise refuse the batch, loop, and pay
+        //    for another model call — every iteration to `maxIterations`.
+        //
+        // Delegating to the throw ports rather than throwing directly keeps the
+        // terminal error the host's to name (a timeout and a cancellation are
+        // different outcomes, and only the host knows which fired).
+        if (signal?.aborted === true) {
+            throwIfTimedOut?.();
+            await ensureNotCancelled?.();
+            // Neither port is required, and a host that wired only `signal` would
+            // otherwise refuse every batch and pay for a fresh model call each
+            // iteration until `maxIterations`. Break so the abort ends the run on its
+            // own, rather than only when some other port happens to agree.
+            //
+            // `aborted`, not `deadline`, even when the signal IS a deadline: by the
+            // time a wall-clock budget and a cancellation are combined into one
+            // `AbortSignal` the loop cannot tell them apart, and `throwIfTimedOut`
+            // above has already had its chance to name a timeout by throwing.
+            stopReason = "aborted";
+            break;
+        }
         // A tool asked to end the run (it scheduled its own resume, or recorded an
         // open call awaiting an answer). The tool results are already in
         // state.messages above; stop now so the run doesn't keep going. Mark it as
@@ -243,11 +479,14 @@ export async function runToolLoop(params) {
         // suspended call, and that pair must survive verbatim to be resumable.
         if (suspendRequested) {
             if (compactionRequested && applyCompaction && !state.suspended) {
-                const compacted = await applyCompaction("manual", state.messages);
-                applyCompactionResult(compacted);
-                await compacted.persist();
+                await compactNow(applyCompaction, "manual");
             }
             state.endedTurnViaTool = true;
+            // `state.suspended` is set only by the `answer` branch, so its presence
+            // IS the discriminant between "a person has to reply" and "this comes
+            // back on its own". Reading it here, once, is what saves every host
+            // from reading it themselves.
+            stopReason = state.suspended ? "waiting_for_reply" : "resuming_later";
             break;
         }
         await ensureNotCancelled?.();
@@ -256,9 +495,7 @@ export async function runToolLoop(params) {
         // compaction usage BEFORE persisting so a persist failure can't drop the
         // tokens it already consumed.
         if (compactionRequested && applyCompaction) {
-            const compacted = await applyCompaction("manual", state.messages);
-            applyCompactionResult(compacted);
-            await compacted.persist();
+            await compactNow(applyCompaction, "manual");
         }
         // Drain human interrupts queued while the agent was working.
         for (const interrupt of drainInterrupts?.() ?? []) {
@@ -266,7 +503,7 @@ export async function runToolLoop(params) {
             // `[Interrupt from user …]` header line and inject transcript structure.
             // (Internal-only sources today, but a future external caller could surface
             // user-supplied ids.)
-            const safeUserId = interrupt.userId.replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g, "");
+            const safeUserId = stripControlChars(interrupt.userId);
             state.messages.push({
                 role: "user",
                 content: `[Interrupt from user ${safeUserId}]\n${interrupt.content}`,
@@ -280,9 +517,8 @@ export async function runToolLoop(params) {
         if (state.lastPromptTokens > 0 &&
             needsCompaction?.(currentTokens) &&
             applyCompaction) {
-            const compacted = await applyCompaction("auto", state.messages);
-            applyCompactionResult(compacted);
-            await compacted.persist();
+            await compactNow(applyCompaction, "auto");
         }
     }
+    return { stopReason, stats };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juno-ai/bind",
-  "version": "8.0.0",
+  "version": "10.0.0",
   "description": "Agent harness: the tool-calling turn kernel, deterministic LLM provider routing with transport-error classification, the streaming-completion watchdog, run mechanics, sub-agent lineage and admission, transcript healing, tool-schema sanitization, and the plugin/tool vocabulary. MIT-licensed; published to npm from the canonical repo via scripts/publish-bind.ts (docs/bind.md).",
   "license": "MIT",
   "type": "module",
@@ -42,6 +42,10 @@
     "./plugins": {
       "types": "./plugins/index.d.ts",
       "import": "./plugins/index.js"
+    },
+    "./testing": {
+      "types": "./testing/index.d.ts",
+      "import": "./testing/index.js"
     }
   },
   "peerDependencies": {

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;