@juno-ai/bind 13.0.0 → 15.0.0

package/README.md

@@ -35,6 +35,15 @@ constraints that will fail CI if you break them.
 
 **Added**
 
+- **Three loop ports for a host whose transcript is durable** —
+  `ToolLoopTurn.acceptMessage`, `ToolLoopParams.beforeToolMessageAccepted` and
+  `ToolLoopParams.onStepSettled` (plus `StepSettlement`,
+  `DiscardedTurnWithToolCallsError` and `InputBlockedBySuspendError`).
+  Together they let a host record each accepted message as the loop accepts
+  it, in the order it accepts it, and hand back messages it has committed.
+  All three are optional and unwired behaviour is unchanged. See "How to
+  commit a transcript as the loop builds it".
+
 - **`@juno-ai/bind/skills`** — progressive disclosure for *instructions*, the
   mirror of `@juno-ai/bind/plugins`. `createSkillRegistry` for what your source
   ships, `partitionSkillCatalog` for the Tier-1 catalog and its token budget,
@@ -56,6 +65,27 @@ constraints that will fail CI if you break them.
 
 **Breaking**
 
+- **`sanitizeToolSchema` now emits a union for a nullable property** instead of
+  collapsing it. `{type:["string","null"], minLength:1}` comes out as
+  `{anyOf:[{type:"string",minLength:1},{type:"null"}]}`, with the node's
+  type-bearing keywords on the typed branch and its annotations left outside;
+  the old output was `{type:"string", minLength:1}` plus an "Accepts string or
+  null." note on the description. Nothing in the API changed, but the emitted
+  schema did — a consumer asserting on sanitizer output, or reading `.type` off
+  a sanitized node, needs updating.
+
+  The collapse was lossy in a way that broke callers. A model handed a
+  type-satisfying schema and a description that says "or send null" cannot
+  express "none" in the half of the declaration it treats as binding, so it
+  invents a value: one tool parameter authored `type:["string","null"],
+  minLength:1` received `"/"`, `". "` and `".000001"` for thousands of calls,
+  each refused by the downstream API and each retried. The union shape is
+  measured accepted on grok-4.3/4.5/4.6, gemini-3.5/3.6/3.7-flash and
+  gpt-5.6-terra/sol/luna. A genuine multi-type union
+  (`["string","number","boolean"]`) still collapses — no single shape is
+  accepted by every provider — and so does a nullable type at the parameters root, in
+  a branch of a root `anyOf`/`oneOf`, or in a composition branch whose
+  `required` resolves against the enclosing node.
 - `runToolLoop` now returns `ToolLoopResult` (`{ stopReason, stats }`) instead
   of `void`. A caller that ignores the return value is unchanged, but a
   wrapper *annotated* `Promise<void>` no longer typechecks — widen it to
@@ -810,6 +840,84 @@ represent faithfully — a `Map`, a `Set`, a class instance, `NaN`, a cycle —
 because a silent collision here reads as "same call" and skips a write that
 never happened.
 
+### How to commit a transcript as the loop builds it
+
+`state.messages` is an in-memory array. If your host persists each message as it
+lands — a Durable Object writing transitions, an event-sourced run that replays
+after eviction — you need three things the array alone cannot give you: the
+exact message at the moment it is accepted, its position among the results the
+batch actually produced, and a point where you can hand back input your users
+committed while the agent was working.
+
+```ts
+await runToolLoop({
+  // …
+  callModel: async (messages, tools) => {
+    const completion = await transport(messages, tools);
+    const empty = !completion.content.trim() && completion.toolCalls.length === 0;
+    if (empty) await settleReservation(turnId, "failed");
+    else await commit({ kind: "assistant_accepted", turnId, message: completion.message });
+    return { ...completion, acceptMessage: !empty };
+  },
+  beforeToolMessageAccepted: async (message, resultOrdinal) => {
+    // Throws → the message is NOT appended and the run fails.
+    await commit({ kind: "tool_result_accepted", message, resultOrdinal });
+  },
+  onStepSettled: async ({ wouldEnd }) => {
+    const pending = await claimCommittedInput({ wouldEnd });
+    return { messages: pending.messages, stop: pending.runWasCancelled };
+  },
+});
+```
+
+**`acceptMessage: false` keeps a turn out of the transcript without hiding what
+it cost.** The case is a tolerated empty completion: the provider returned
+nothing, your host has already settled the slot it reserved, and appending an
+empty assistant message would persist a turn that said nothing and re-send it on
+every later call. Tokens and cost are still folded into `stats` and `state`. The
+loop **refuses** the discard for a turn that requested tools — those results are
+about to be appended and would have no request to pair with — and reports the
+misuse through `onToolCallRejected` as a `DiscardedTurnWithToolCallsError`.
+
+**`resultOrdinal` is dense over accepted results.** It is not the call's index
+in `tool_calls`: an `answer`-suspend withholds its result, so the calls after it
+close the gap, and the answer takes the ordinal it is accepted at when it
+arrives. Reconstructing that order from `state.messages` afterwards is the one
+thing that goes wrong for exactly the batch that suspended.
+
+**`beforeToolMessageAccepted` covers results this loop produced, not messages
+you hand back.** A `tool` message you return from `onStepSettled` skips the
+port and takes no ordinal — you committed it before handing it over, so
+reporting it back would ask you to record the same thing twice.
+
+**A settled step is where input can join.** `onStepSettled` fires **at most
+once per iteration**, and `wouldEnd` says which of the two shapes that
+iteration took: `true` when the model asked for no tools (the run is about to
+end), `false` when the batch's results are all in the transcript. Anywhere
+else, an appended message lands between an assistant message and the results
+it is waiting on, which is a transcript providers reject. Returned messages
+are appended in order and the run continues; `stop` ends it as `aborted` with
+them already appended, and a throw propagates out of `runToolLoop`
+unconverted.
+
+Two behaviours worth knowing before you wire it:
+
+- At `wouldEnd: true`, `onStepSettled` runs **before** `onTurnWouldEnd`. Real
+  input outranks a nudge — a turn with more to answer was never stalled.
+- A returned `role:"tool"` message carrying an **open suspend's `tool_call_id`
+  clears the suspension**, so a host that already has the answer keeps going
+  instead of pausing for a reply it has been handed. A `wake`-suspend from
+  another call in the same batch still ends the run: the answer says nothing
+  about it.
+- **While a suspend is open, only `tool` messages are accepted.** A `user`
+  message delivered ahead of the answer is refused and reported as an
+  `InputBlockedBySuspendError`: appending it is how a resumed run ends up
+  sending `assistant(tool_calls) → user → tool`, which providers reject. Put
+  the answering result first in the array and the rest is accepted after it.
+- **`shouldStop` outranks delivered input.** The messages are kept — your host
+  committed them — and the run ends as `aborted` rather than making another
+  model call.
+
 ### How to stream tokens to a user without breaking fallback
 
 Three granularities reach you, and the third is the one with a retry problem.
@@ -1048,6 +1156,15 @@ property; a boolean `additionalProperties: false` on a nested object; and a
 parameter literally named `properties`. Run it on third-party (e.g. MCP) tool
 schemas too — those are where the violations usually come from.
 
+One transform is worth knowing about even if no provider forced it. A **nullable
+property** — `{type:["string","null"], minLength:1}` — is rewritten to
+`{anyOf:[{type:"string",minLength:1},{type:"null"}]}` rather than reduced to its
+non-null type with a note on the description. Reducing it is what a strict
+provider needs, but it leaves the model unable to say "none" in the part of the
+declaration it treats as binding, so it invents a value that satisfies the type:
+`"/"`, `" "`, `"null"`, `"undefined"`. If you author nullable parameters, you do
+not need to hand-write the union — the sanitizer produces it.
+
 ### How to repair a transcript before sending it
 
 ```ts
@@ -1434,6 +1551,12 @@ what happens to the tool message:
 `request` is an opaque render/route payload, validated by the consumer and never
 inspected by the loop.
 
+An open `"answer"` suspend can also be resolved **within the same step**: a
+`role:"tool"` message returned from `onStepSettled` that carries the open call's
+`tool_call_id` clears the suspension and the run continues, for a host that
+already holds the reply. A `"wake"` suspend from another call in the same batch
+still ends the run — see "How to commit a transcript as the loop builds it".
+
 ---
 
 ## Usage scenarios

package/loop/index.d.ts

@@ -1,2 +1,2 @@
 export type { StopReason, RunStats } from "../contracts/turn.js";
-export { runToolLoop, MissingActivationPortError, type ToolLoopParams, type ToolLoopResult, type ToolLoopState, type ToolLoopTurn, type ToolCallOutcome, type CompactionApplied, type RunStatus, } from "./tool-loop.js";
+export { runToolLoop, MissingActivationPortError, DiscardedTurnWithToolCallsError, InputBlockedBySuspendError, type ToolLoopParams, type ToolLoopResult, type ToolLoopState, type ToolLoopTurn, type ToolCallOutcome, type StepSettlement, type CompactionApplied, type RunStatus, } from "./tool-loop.js";

package/loop/index.js

@@ -1 +1 @@
-export { runToolLoop, MissingActivationPortError, } from "./tool-loop.js";
+export { runToolLoop, MissingActivationPortError, DiscardedTurnWithToolCallsError, InputBlockedBySuspendError, } from "./tool-loop.js";

package/loop/tool-loop.d.ts

@@ -40,6 +40,30 @@ export interface ToolLoopTurn {
      * simply does not count this turn, rather than counting it as a zero.
      */
     cachedInputTokens?: number | null;
+    /**
+     * Set `false` to keep this completion OUT of the transcript while still
+     * accounting for what it cost. The turn happened — it is folded into
+     * `stats` and `state` either way — but `state.messages` never grows an
+     * assistant entry for it.
+     *
+     * The case it exists for is a **tolerated empty completion**: a provider
+     * answered with no text and no tool calls, the host decided that is a
+     * nothing rather than a failure, and the host had already reserved a
+     * transcript slot for the message it never got. Appending the empty
+     * assistant message would persist a turn saying nothing and re-send it on
+     * every later call; dropping it leaves the transcript exactly as the model
+     * found it, so the next turn is a clean retry of the same question.
+     *
+     * **Only a turn with no tool calls may be dropped.** Withholding a
+     * tool-calling assistant message orphans every `tool` result the batch is
+     * about to append, which is an invalid transcript the next model call
+     * rejects. The loop refuses that rather than building it — it reports the
+     * misuse through `onToolCallRejected` (one report per orphaned call, the
+     * same channel a missing activation port uses) and keeps the message.
+     *
+     * Defaults to accepting: omit it, or pass `true`, and nothing changes.
+     */
+    acceptMessage?: boolean;
 }
 /**
  * Outcome of running one tool call inside an assistant `tool_calls` batch.
@@ -155,6 +179,44 @@ export declare class MissingActivationPortError extends Error {
     readonly name = "MissingActivationPortError";
     constructor(port: "activatePlugins" | "activateSkills");
 }
+/**
+ * A turn returned `acceptMessage: false` while also requesting tools.
+ *
+ * Reported through `onToolCallRejected` rather than thrown, and the discard is
+ * refused rather than honoured: the tool calls are about to run, and a
+ * transcript carrying their results without the assistant message that asked
+ * for them is one the next provider call rejects outright. Keeping the message
+ * costs an assistant entry the host did not want; dropping it costs the run.
+ *
+ * Match on `error.name === "DiscardedTurnWithToolCallsError"` rather than
+ * `instanceof` — see {@link MissingActivationPortError} for why.
+ */
+export declare class DiscardedTurnWithToolCallsError extends Error {
+    readonly toolCallCount: number;
+    readonly name = "DiscardedTurnWithToolCallsError";
+    constructor(toolCallCount: number);
+}
+/**
+ * A settled step delivered a message that cannot be appended yet: a call is
+ * still awaiting its answer, and the provider rule is that nothing comes
+ * between an assistant message and the `tool` results it is waiting on.
+ *
+ * Appending it anyway builds `assistant(tool_calls) → user → tool` the moment
+ * the answer is threaded back on resume, which providers reject outright — so
+ * the message is refused and reported (through `onToolCallRejected`, against
+ * the open call) rather than silently corrupting the transcript. Deliver the
+ * answering `tool` result first, in the same settlement, and everything after
+ * it is accepted normally.
+ *
+ * Match on `error.name === "InputBlockedBySuspendError"` rather than
+ * `instanceof` — see {@link MissingActivationPortError} for why.
+ */
+export declare class InputBlockedBySuspendError extends Error {
+    readonly openToolCallId: string;
+    readonly refusedRole: string;
+    readonly name = "InputBlockedBySuspendError";
+    constructor(openToolCallId: string, refusedRole: string);
+}
 /**
  * What a completed loop reports back.
  *
@@ -198,6 +260,17 @@ export interface ToolLoopResult {
      */
     readonly stats: RunStats;
 }
+/**
+ * What a host hands back from {@link ToolLoopParams.onStepSettled}: the
+ * messages to append at this settled step, and whether the run should end
+ * after appending them.
+ */
+export interface StepSettlement {
+    /** Appended to the transcript in this order. Empty means "nothing queued". */
+    messages: OpenAI.ChatCompletionMessageParam[];
+    /** End the run as `aborted` once the messages above are appended. */
+    stop: boolean;
+}
 export interface ToolLoopParams {
     state: ToolLoopState;
     /**
@@ -217,6 +290,90 @@ export interface ToolLoopParams {
     buildTools: () => OpenAI.ChatCompletionTool[];
     /** Execute one tool call → the `tool` message + control signals. */
     runToolCall: (toolCall: OpenAI.ChatCompletionMessageToolCall) => Promise<ToolCallOutcome>;
+    /**
+     * Record the exact `tool` message the loop is about to append, immediately
+     * before it appends it. For a host that persists the transcript as it is
+     * built, this is the only point where "what was accepted" and "what was
+     * recorded" cannot drift: a batch's outcomes are produced concurrently and
+     * an `answer`-suspend withholds one of them, so a host reconstructing the
+     * accepted set afterwards has to re-derive a decision the loop already made.
+     *
+     * `resultOrdinal` counts **accepted results in this batch, densely from 0**
+     * — not the call's index in `tool_calls`. A withheld suspend leaves no
+     * ordinal behind, so the results that follow it close the gap, and the
+     * answer that arrives later takes the ordinal it is accepted at rather than
+     * the one its call was issued at. Ordering within the batch is otherwise
+     * the model's original call order.
+     *
+     * **A throw aborts acceptance**: the message is not appended and the error
+     * propagates out of `runToolLoop`, unconverted. That is deliberate — this
+     * port exists for hosts that must record a result durably before the model
+     * may see it, and a host that cannot record one must not be handed a
+     * transcript claiming it did. Wire `isFatalToolError` the same way for the
+     * dispatch half of that rule.
+     *
+     * **Scope: results this loop produced.** A `tool` message the host itself
+     * returns from `onStepSettled` does not fire this port and takes no ordinal
+     * — the host committed that message before handing it over, so reporting it
+     * back would ask for a second record of the same thing. `resultOrdinal` is
+     * therefore a position within the batch, and a host that journals both
+     * sources keys them by where they came from rather than by one counter.
+     */
+    beforeToolMessageAccepted?: (message: OpenAI.ChatCompletionToolMessageParam, resultOrdinal: number) => Promise<void> | void;
+    /**
+     * Deliver host-committed messages at a **settled step** — a point where the
+     * model turn and its whole tool batch are complete and the transcript is
+     * coherent, so appending a `user` (or a withheld `tool`) message cannot
+     * split an assistant message from the results it is waiting on.
+     *
+     * Called **at most once per iteration** — the two points below are the two
+     * shapes an iteration can take, not two calls in one — and `wouldEnd` says
+     * which one this is:
+     *
+     *  - **`wouldEnd: true`** — the model asked for no tools and the loop is
+     *    about to finish. Returning messages CONTINUES the run with them
+     *    appended, ahead of `onTurnWouldEnd` (a host that has real input queued
+     *    delivers it rather than nudging a turn that was not actually stalled).
+     *  - **`wouldEnd: false`** — the batch ran and its results are in the
+     *    transcript. Returning messages appends them before the next model call.
+     *
+     * Return `stop: true` to end the run as `aborted`, with whatever messages
+     * came back already appended. Returning `{ messages: [], stop: false }` —
+     * or leaving the port unwired — changes nothing.
+     *
+     * **A delivered `tool` message answers an open suspend.** If the run is
+     * waiting on an `answer`-suspend and a returned message carries that call's
+     * `tool_call_id`, the loop clears the suspension and keeps going rather than
+     * pausing for a reply it has just been handed. It still ends the run if some
+     * *other* call in the same batch asked for a `wake`-suspend, which is a
+     * separate request that a delivered answer says nothing about.
+     *
+     * **While a suspend is open, only `tool` messages are accepted.** Nothing
+     * may come between an assistant message and the results it is waiting on, so
+     * a `user` message delivered ahead of the answer is refused and reported as
+     * an {@link InputBlockedBySuspendError} — appending it is how a resumed run
+     * ends up sending `assistant(tool_calls) → user → tool`, which providers
+     * reject. Return the answering result first and the rest is accepted after
+     * it, in order.
+     *
+     * **A host that asked to stop still stops.** Delivered input says the turn
+     * is not over; `shouldStop` says the run is, and the run wins — the messages
+     * are kept and the loop ends as `aborted` rather than paying for another
+     * model call.
+     *
+     * Messages are otherwise appended in the order returned, and the loop does
+     * not validate them further: this is the host's transcript, committed on the
+     * host's side, arriving at the one place the loop can take it.
+     *
+     * **A throw propagates out of `runToolLoop` unconverted**, like
+     * `beforeToolMessageAccepted` and for the same reason: a host that cannot
+     * say what it has committed cannot be told the run went on without it.
+     */
+    onStepSettled?: (step: {
+        assistantMessage: OpenAI.ChatCompletionMessage;
+        cumulativeToolCalls: number;
+        wouldEnd: boolean;
+    }) => StepSettlement | Promise<StepSettlement>;
     /**
      * Activate newly loaded plugins (mutate the catalog/active set). Optional:
      * a host with a fixed tool surface has nothing to activate, and requiring an

package/loop/tool-loop.js

@@ -29,6 +29,56 @@ export class MissingActivationPortError extends Error {
         this.port = port;
     }
 }
+/**
+ * A turn returned `acceptMessage: false` while also requesting tools.
+ *
+ * Reported through `onToolCallRejected` rather than thrown, and the discard is
+ * refused rather than honoured: the tool calls are about to run, and a
+ * transcript carrying their results without the assistant message that asked
+ * for them is one the next provider call rejects outright. Keeping the message
+ * costs an assistant entry the host did not want; dropping it costs the run.
+ *
+ * Match on `error.name === "DiscardedTurnWithToolCallsError"` rather than
+ * `instanceof` — see {@link MissingActivationPortError} for why.
+ */
+export class DiscardedTurnWithToolCallsError extends Error {
+    toolCallCount;
+    name = "DiscardedTurnWithToolCallsError";
+    constructor(toolCallCount) {
+        super(`A turn asked the loop to drop its assistant message, but the message ` +
+            `requests ${toolCallCount} tool call(s) whose results would be left ` +
+            `unpaired. The message was kept. Only a tool-less turn may be dropped.`);
+        this.toolCallCount = toolCallCount;
+    }
+}
+/**
+ * A settled step delivered a message that cannot be appended yet: a call is
+ * still awaiting its answer, and the provider rule is that nothing comes
+ * between an assistant message and the `tool` results it is waiting on.
+ *
+ * Appending it anyway builds `assistant(tool_calls) → user → tool` the moment
+ * the answer is threaded back on resume, which providers reject outright — so
+ * the message is refused and reported (through `onToolCallRejected`, against
+ * the open call) rather than silently corrupting the transcript. Deliver the
+ * answering `tool` result first, in the same settlement, and everything after
+ * it is accepted normally.
+ *
+ * Match on `error.name === "InputBlockedBySuspendError"` rather than
+ * `instanceof` — see {@link MissingActivationPortError} for why.
+ */
+export class InputBlockedBySuspendError extends Error {
+    openToolCallId;
+    refusedRole;
+    name = "InputBlockedBySuspendError";
+    constructor(openToolCallId, refusedRole) {
+        super(`A settled step delivered a \`${refusedRole}\` message while tool call ` +
+            `${openToolCallId} is still awaiting its answer. It was refused: the ` +
+            `answer has to reach the transcript first, or the resumed run sends ` +
+            `a \`tool\` result the message has already split from its call.`);
+        this.openToolCallId = openToolCallId;
+        this.refusedRole = refusedRole;
+    }
+}
 /**
  * The key a tool call is measured under in {@link RunStats.toolTimeBreakdownMs}.
  *
@@ -67,7 +117,7 @@ function toolCallStatsKey(tc) {
  * run's conclusion, which only exists once the loop is over.
  */
 export async function runToolLoop(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;
+    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, beforeToolMessageAccepted, onStepSettled, } = 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
@@ -116,6 +166,55 @@ export async function runToolLoop(params) {
             // Nothing useful to do — the reporting channel is the thing that broke.
         }
     };
+    // Ask the host what it has committed for this settled step. Unwired, the
+    // answer is "nothing, keep going" — the one shape every call site below
+    // reads, so neither of them branches on whether the port exists.
+    const settleStep = async (assistantMessage, wouldEnd) => {
+        const settlement = await onStepSettled?.({
+            assistantMessage,
+            cumulativeToolCalls: state.toolCalls,
+            wouldEnd,
+        });
+        // Read field by field rather than trusting the object whole: the types say
+        // both are present, and a JavaScript host (this package is published, and
+        // was reimplemented once already as a patch) that returns `{ stop: true }`
+        // would otherwise crash the run inside the loop rather than stop it.
+        return {
+            messages: settlement?.messages ?? [],
+            stop: settlement?.stop === true,
+        };
+    };
+    // Append a settlement's messages, honouring the one ordering rule an open
+    // `answer`-suspend imposes: until that call has its result, nothing else may
+    // come between it and the assistant message that asked for it. A delivered
+    // result for the open call clears the pause (the answer arrived in the same
+    // breath as the question); anything that is not a `tool` message is refused
+    // while the pause is open, because appending it is how a resumed run ends up
+    // sending `assistant(tool_calls) → user → tool`.
+    //
+    // Shared by both settle sites rather than living in the batch arm alone: a
+    // caller may seed `state.suspended` when it resumes a run, and the rule is
+    // about the transcript, not about which branch produced it.
+    const applySettledMessages = (messages) => {
+        let appended = 0;
+        let answeredSuspend = false;
+        for (const message of messages) {
+            const openSuspension = state.suspended;
+            if (openSuspension) {
+                if (message.role !== "tool") {
+                    reportRejection(openSuspension.toolCallId, new InputBlockedBySuspendError(openSuspension.toolCallId, message.role));
+                    continue;
+                }
+                if (message.tool_call_id === openSuspension.toolCallId) {
+                    state.suspended = undefined;
+                    answeredSuspend = true;
+                }
+            }
+            state.messages.push(message);
+            appended += 1;
+        }
+        return { appended, answeredSuspend };
+    };
     // Swap in a freshly-compacted transcript and reset the live counts. The
     // provider count no longer reflects the compacted array, so drop it — the
     // auto-compaction check skips while it's 0 (preventing an immediate
@@ -209,7 +308,20 @@ export async function runToolLoop(params) {
         state.lastOutputTokens = result.outputTokens;
         state.hasFreshTokenCount = true;
         const assistantMessage = result.message;
-        state.messages.push(assistantMessage);
+        // `acceptMessage: false` keeps a tolerated empty completion out of the
+        // transcript — the turn is still accounted for above. Refused for a
+        // tool-calling turn: the batch below appends results, and results whose
+        // request is missing are a transcript the next provider call rejects.
+        const requestedToolCalls = assistantMessage.tool_calls ?? [];
+        if (result.acceptMessage === false && requestedToolCalls.length > 0) {
+            const misuse = new DiscardedTurnWithToolCallsError(requestedToolCalls.length);
+            for (const tc of requestedToolCalls) {
+                reportRejection(tc.id, misuse);
+            }
+        }
+        if (result.acceptMessage !== false || requestedToolCalls.length > 0) {
+            state.messages.push(assistantMessage);
+        }
         if (assistantMessage.content && assistantMessage.tool_calls?.length) {
             onThinking?.(assistantMessage.content);
         }
@@ -244,6 +356,32 @@ export async function runToolLoop(params) {
             state.toolCalls += toolCalls.length;
         onProgressUpdate?.(state.outputTokens, state.toolCalls);
         if (!toolCalls || toolCalls.length === 0) {
+            // The step is settled: no batch to run, so the transcript is coherent
+            // right here. Ask the host for anything it has committed since the turn
+            // began — real input outranks a nudge, so this runs BEFORE
+            // `onTurnWouldEnd`. A host that delivers a message is saying the turn is
+            // not over, so the loop continues with it appended rather than asking
+            // whether a turn that has more to answer looked stalled.
+            const settlement = await settleStep(assistantMessage, true);
+            const settledInput = applySettledMessages(settlement.messages);
+            if (settlement.stop) {
+                stopReason = "aborted";
+                break;
+            }
+            if (settledInput.appended > 0) {
+                // Delivered input says the turn is not over; a host that asked to stop
+                // says the RUN is. The stop wins, exactly as it does over a nudge
+                // below — otherwise `shouldStop` ("stop after the current turn") pays
+                // for another model call and answers after it was cancelled. The
+                // messages stay: the host committed them, and dropping them here would
+                // leave its ledger and this transcript disagreeing.
+                if (stopRequested) {
+                    onProgressUpdate?.(state.outputTokens, state.toolCalls);
+                    stopReason = "aborted";
+                    break;
+                }
+                continue;
+            }
             // The model stopped calling tools — normally the turn is done. Give a
             // caller a chance to push it forward instead: if `onTurnWouldEnd` returns
             // text, inject it as a synthetic user message and keep looping. The hook
@@ -398,6 +536,17 @@ export async function runToolLoop(params) {
         }
         let compactionRequested = false;
         let suspendRequested = false;
+        // Dense over ACCEPTED results, so a withheld suspend leaves no gap — see
+        // `beforeToolMessageAccepted`. Reset per batch: it is a position within
+        // this step, not a running total.
+        let acceptedResultOrdinal = 0;
+        const acceptToolMessage = async (message) => {
+            // A throw propagates: a host that could not record the result must not
+            // be handed a transcript that says the model already saw it.
+            await beforeToolMessageAccepted?.(message, acceptedResultOrdinal);
+            state.messages.push(message);
+            acceptedResultOrdinal += 1;
+        };
         for (const outcome of outcomes) {
             // An `answer`-suspend WITHHOLDS its tool message — the result is the
             // future answer, threaded back on resume. At most one may be open: the
@@ -412,6 +561,14 @@ export async function runToolLoop(params) {
                         // Rebuild with the literal "answer" kind so the assignment matches
                         // `ToolLoopState.suspended` (always answer — see its type).
                         state.suspended = { ...outcome.suspend, resumeKind: "answer" };
+                        // The message is withheld; the call's OTHER signals are not. A
+                        // compaction asked for by the same outcome is skipped while the
+                        // pause is open (the arm below checks `state.suspended`) and runs
+                        // if a same-step answer clears it — whereas dropping the flag here
+                        // loses it for good, which is only invisible while an answered
+                        // suspend could not continue the run.
+                        if (outcome.requestCompaction)
+                            compactionRequested = true;
                         continue; // withhold this call's tool message
                     }
                     // Through the shared encoder, and carrying a `kind`, like every
@@ -420,7 +577,7 @@ export async function runToolLoop(params) {
                     // 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, {
+                    await acceptToolMessage(toolResultMessage(outcome.suspend.toolCallId, {
                         success: false,
                         kind: "conflict",
                         error: "This question was not asked — you already have one waiting " +
@@ -433,7 +590,7 @@ export async function runToolLoop(params) {
                 // `wake` (e.g. sleep_until): fall through and push the tool message, then
                 // end the run — it re-enters via a prompt, not a threaded answer.
             }
-            state.messages.push(outcome.toolMessage);
+            await acceptToolMessage(outcome.toolMessage);
             if (outcome.requestCompaction)
                 compactionRequested = true;
         }
@@ -469,6 +626,23 @@ export async function runToolLoop(params) {
             stopReason = "aborted";
             break;
         }
+        // The step is settled: every result the batch produced is in the
+        // transcript and nothing is half-applied, so this is where host-committed
+        // input can join without splitting a call from its result.
+        const settlement = await settleStep(assistantMessage, false);
+        const settledInput = applySettledMessages(settlement.messages);
+        // The answer arrived in the same breath as the question, so the run is no
+        // longer waiting on a person. A `wake`-suspend from another call in the
+        // same batch is a separate request the answer says nothing about, so it
+        // still ends the run — recomputed from the outcomes rather than left set,
+        // because `suspendRequested` is true for the answered call too.
+        if (settledInput.answeredSuspend) {
+            suspendRequested = outcomes.some((outcome) => outcome.suspend?.resumeKind === "wake");
+        }
+        if (settlement.stop) {
+            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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juno-ai/bind",
-  "version": "13.0.0",
+  "version": "15.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, the plugin/tool vocabulary, and the skill vocabulary (`./skills`) for progressive knowledge disclosure. MIT-licensed; published to npm from the canonical repo via scripts/publish-bind.ts (docs/bind.md).",
   "license": "MIT",
   "type": "module",

package/tools/sanitize-schema.d.ts

@@ -32,13 +32,64 @@
  * The transforms only remove or normalize constructs that carry no real
  * constraint for a model's tool call. Each was verified against live Gemini:
  *
- *   1. Collapse a `type` ARRAY to a single `type`. Gemini requires a scalar
- *      `type` and rejects a union array. We keep the first non-`"null"`
- *      member (e.g. `["string","number","boolean"]` → `"string"`,
- *      `["string","null"]` → `"string"`); an array of only `"null"` drops
- *      the `type`. The lost alternatives are advisory — arguments are still
- *      validated at dispatch against the tool's zod schema and by the remote
- *      MCP server.
+ *   1. Resolve a `type` ARRAY, which Gemini rejects outright (it requires a
+ *      scalar `type`). Two cases, and they are not the same kind of loss:
+ *
+ *      a. NULLABLE single type — exactly one non-`"null"` member plus `"null"`,
+ *         in either order, duplicates tolerated. Rewritten to
+ *         `anyOf: [ <T branch>, {type:"null"} ]`, where the T branch carries
+ *         the node's type-bearing keywords (`minLength`, `enum`, `properties`,
+ *         `items`, bounds, …) under `type: T` and the node keeps its
+ *         annotations. The branch is re-entered through this same walk, so
+ *         every per-node transform applies to it — #12 retypes it to `"object"`
+ *         when it carries `properties`, #13 drops an unsupported `pattern` into
+ *         prose ON the branch, #2 filters its `enum`, #3 resolves its
+ *         `required` against its own `properties`.
+ *
+ *         Collapsing this case instead was lossy in a way that broke callers in
+ *         production. A model handed `{type:"string", minLength:1,
+ *         description:"… or send null …"}` cannot express "none" in the half of
+ *         the declaration it treats as binding, so it INVENTS a value that
+ *         satisfies the type: `slack_send_message.thread_ts` (authored
+ *         `type:["string","null"], minLength:1`) received `"/"`, `". "`,
+ *         `".000001"` and the like for thousands of calls, each refused by
+ *         Slack and each retried; a Drive pagination cursor had already been
+ *         seen taking `"x"`, `" "`, `"undefined"`, `"null"` and `"/"`. Prose
+ *         loses to the schema every time. The `anyOf` shape is not a guess: it
+ *         passes under `properties` on grok-4.3/4.5/4.6,
+ *         gemini-3.5/3.6/3.7-flash and gpt-5.6-terra/sol/luna, and it ships
+ *         today on every pagination cursor of six connectors. No "Accepts T or
+ *         null." note is added — the schema now says it — and an `enum` that
+ *         listed `null` contributes only its non-null members to the branch,
+ *         with no "May also be null." note, since the null branch carries that.
+ *         A sibling `enum`/`const` that EXCLUDES one arm keeps case (b)
+ *         instead: those keywords are AND-ed with `type`, so
+ *         `{type:["string","null"], enum:["x"]}` means "must be \"x\"", and a
+ *         union whose null branch the enum never reaches would admit a value
+ *         the node forbade.
+ *
+ *         Four shapes opt out. The parameters ROOT, which has to be an object
+ *         for every provider (transform #9 owns it). A branch of a ROOT
+ *         `anyOf`/`oneOf`, because a root union branch carrying its OWN `anyOf`
+ *         is 0/3 on Grok — rewriting there would turn a usable branch into one
+ *         rule (a) drops, taking the whole keyword and every shape it
+ *         advertised with it. And a COMPOSITION BRANCH whose `required` reaches
+ *         the ENCLOSING node's `properties` — the extra scope transform #8
+ *         gives it — because nesting such a name inside an `anyOf` puts it two
+ *         levels from that scope, where transform #3 prunes it away entirely
+ *         (a branch whose `required` its own `properties` cover needs no
+ *         exception). All three keep case (b). (One residue is known and accepted: a `$defs` target
+ *         rewritten this way, then inlined into a root union branch by
+ *         transform #14, is unusable for the same 0/3 reason and still drops
+ *         the keyword — the same narrow class #14 already documents.)
+ *
+ *      b. Everything else — a genuine MULTI-type union, which has no shape
+ *         every provider accepts. Collapsed to the first non-`"null"` member
+ *         (`["string","number","boolean"]` → `"string"`) with the alternatives
+ *         folded into `description`; an array of only `"null"` drops the
+ *         `type`. The lost alternatives are advisory — arguments are still
+ *         validated at dispatch against the tool's zod schema and by the remote
+ *         MCP server.
  *   2. Constrain `enum` to Gemini's rule: it is accepted ONLY as a list of
  *      strings on a string-typed (or type-less) property. So drop `enum`
  *      entirely when the node has an explicit non-string type (boolean,
@@ -202,9 +253,11 @@
  *
  *      A root union of `$ref` branches is no longer a loss — transform #14 below
  *      inlines the targets so the union survives. What remains is the narrow
- *      residue it cannot inline: a target that is not a plain object schema, one
- *      whose expanded size exceeds the copy-down ceiling, and a self-referential
- *      root pointer. Those branches stay unusable and still drop the keyword.
+ *      residue it cannot inline: a target that is not a plain object schema
+ *      (a union of its own included, which is what a `$defs` entry transform
+ *      #1a rewrote becomes), one whose expanded size exceeds the copy-down
+ *      ceiling, and a self-referential root pointer. Those branches stay
+ *      unusable and still drop the keyword.
  *
  *      Rule (b) covers EVERY root, not only composition roots. A property sweep
  *      over recursive shapes (`__tests__/tool-schema/property/`) found the
@@ -291,11 +344,13 @@
  *      one. A branch whose target is not a plain object schema stays unusable
  *      and still falls through to the drop.
  *
- * When (1) or (2) discards information the model could use — a collapsed
- * union type, or a wholly-dropped `enum` — that constraint is folded into the
- * node's `description` as prose ("Accepts string, number, or boolean.",
+ * When (1b) or (2) discards information the model could use — a collapsed
+ * multi-type union, or a wholly-dropped `enum` — that constraint is folded into
+ * the node's `description` as prose ("Accepts string, number, or boolean.",
  * "Allowed values: true.") so the model still sees it. `description` is a free
- * string every provider accepts, so this is always safe.
+ * string every provider accepts, so this is always safe. Prose is the fallback,
+ * never the first choice: where a shape every provider accepts exists, the
+ * schema says it instead — which is the whole of (1a).
  *
  * It deliberately leaves meaningful validation keywords (`format`,
  * `pattern`, object- or `true`-valued `additionalProperties`, `const`, string

package/tools/sanitize-schema.js

@@ -32,13 +32,64 @@
  * The transforms only remove or normalize constructs that carry no real
  * constraint for a model's tool call. Each was verified against live Gemini:
  *
- *   1. Collapse a `type` ARRAY to a single `type`. Gemini requires a scalar
- *      `type` and rejects a union array. We keep the first non-`"null"`
- *      member (e.g. `["string","number","boolean"]` → `"string"`,
- *      `["string","null"]` → `"string"`); an array of only `"null"` drops
- *      the `type`. The lost alternatives are advisory — arguments are still
- *      validated at dispatch against the tool's zod schema and by the remote
- *      MCP server.
+ *   1. Resolve a `type` ARRAY, which Gemini rejects outright (it requires a
+ *      scalar `type`). Two cases, and they are not the same kind of loss:
+ *
+ *      a. NULLABLE single type — exactly one non-`"null"` member plus `"null"`,
+ *         in either order, duplicates tolerated. Rewritten to
+ *         `anyOf: [ <T branch>, {type:"null"} ]`, where the T branch carries
+ *         the node's type-bearing keywords (`minLength`, `enum`, `properties`,
+ *         `items`, bounds, …) under `type: T` and the node keeps its
+ *         annotations. The branch is re-entered through this same walk, so
+ *         every per-node transform applies to it — #12 retypes it to `"object"`
+ *         when it carries `properties`, #13 drops an unsupported `pattern` into
+ *         prose ON the branch, #2 filters its `enum`, #3 resolves its
+ *         `required` against its own `properties`.
+ *
+ *         Collapsing this case instead was lossy in a way that broke callers in
+ *         production. A model handed `{type:"string", minLength:1,
+ *         description:"… or send null …"}` cannot express "none" in the half of
+ *         the declaration it treats as binding, so it INVENTS a value that
+ *         satisfies the type: `slack_send_message.thread_ts` (authored
+ *         `type:["string","null"], minLength:1`) received `"/"`, `". "`,
+ *         `".000001"` and the like for thousands of calls, each refused by
+ *         Slack and each retried; a Drive pagination cursor had already been
+ *         seen taking `"x"`, `" "`, `"undefined"`, `"null"` and `"/"`. Prose
+ *         loses to the schema every time. The `anyOf` shape is not a guess: it
+ *         passes under `properties` on grok-4.3/4.5/4.6,
+ *         gemini-3.5/3.6/3.7-flash and gpt-5.6-terra/sol/luna, and it ships
+ *         today on every pagination cursor of six connectors. No "Accepts T or
+ *         null." note is added — the schema now says it — and an `enum` that
+ *         listed `null` contributes only its non-null members to the branch,
+ *         with no "May also be null." note, since the null branch carries that.
+ *         A sibling `enum`/`const` that EXCLUDES one arm keeps case (b)
+ *         instead: those keywords are AND-ed with `type`, so
+ *         `{type:["string","null"], enum:["x"]}` means "must be \"x\"", and a
+ *         union whose null branch the enum never reaches would admit a value
+ *         the node forbade.
+ *
+ *         Four shapes opt out. The parameters ROOT, which has to be an object
+ *         for every provider (transform #9 owns it). A branch of a ROOT
+ *         `anyOf`/`oneOf`, because a root union branch carrying its OWN `anyOf`
+ *         is 0/3 on Grok — rewriting there would turn a usable branch into one
+ *         rule (a) drops, taking the whole keyword and every shape it
+ *         advertised with it. And a COMPOSITION BRANCH whose `required` reaches
+ *         the ENCLOSING node's `properties` — the extra scope transform #8
+ *         gives it — because nesting such a name inside an `anyOf` puts it two
+ *         levels from that scope, where transform #3 prunes it away entirely
+ *         (a branch whose `required` its own `properties` cover needs no
+ *         exception). All three keep case (b). (One residue is known and accepted: a `$defs` target
+ *         rewritten this way, then inlined into a root union branch by
+ *         transform #14, is unusable for the same 0/3 reason and still drops
+ *         the keyword — the same narrow class #14 already documents.)
+ *
+ *      b. Everything else — a genuine MULTI-type union, which has no shape
+ *         every provider accepts. Collapsed to the first non-`"null"` member
+ *         (`["string","number","boolean"]` → `"string"`) with the alternatives
+ *         folded into `description`; an array of only `"null"` drops the
+ *         `type`. The lost alternatives are advisory — arguments are still
+ *         validated at dispatch against the tool's zod schema and by the remote
+ *         MCP server.
  *   2. Constrain `enum` to Gemini's rule: it is accepted ONLY as a list of
  *      strings on a string-typed (or type-less) property. So drop `enum`
  *      entirely when the node has an explicit non-string type (boolean,
@@ -202,9 +253,11 @@
  *
  *      A root union of `$ref` branches is no longer a loss — transform #14 below
  *      inlines the targets so the union survives. What remains is the narrow
- *      residue it cannot inline: a target that is not a plain object schema, one
- *      whose expanded size exceeds the copy-down ceiling, and a self-referential
- *      root pointer. Those branches stay unusable and still drop the keyword.
+ *      residue it cannot inline: a target that is not a plain object schema
+ *      (a union of its own included, which is what a `$defs` entry transform
+ *      #1a rewrote becomes), one whose expanded size exceeds the copy-down
+ *      ceiling, and a self-referential root pointer. Those branches stay
+ *      unusable and still drop the keyword.
  *
  *      Rule (b) covers EVERY root, not only composition roots. A property sweep
  *      over recursive shapes (`__tests__/tool-schema/property/`) found the
@@ -291,11 +344,13 @@
  *      one. A branch whose target is not a plain object schema stays unusable
  *      and still falls through to the drop.
  *
- * When (1) or (2) discards information the model could use — a collapsed
- * union type, or a wholly-dropped `enum` — that constraint is folded into the
- * node's `description` as prose ("Accepts string, number, or boolean.",
+ * When (1b) or (2) discards information the model could use — a collapsed
+ * multi-type union, or a wholly-dropped `enum` — that constraint is folded into
+ * the node's `description` as prose ("Accepts string, number, or boolean.",
  * "Allowed values: true.") so the model still sees it. `description` is a free
- * string every provider accepts, so this is always safe.
+ * string every provider accepts, so this is always safe. Prose is the fallback,
+ * never the first choice: where a shape every provider accepts exists, the
+ * schema says it instead — which is the whole of (1a).
  *
  * It deliberately leaves meaningful validation keywords (`format`,
  * `pattern`, object- or `true`-valued `additionalProperties`, `const`, string
@@ -370,6 +425,93 @@ const SUBSCHEMA_ARRAY_KEYS = new Set([
  * `prefixItems` is in `SUBSCHEMA_ARRAY_KEYS` but NOT here: its elements are the
  * item schemas of a tuple, a fresh scope, not branches of the enclosing object. */
 const COMPOSITION_KEYS = new Set(["allOf", "anyOf", "oneOf"]);
+/**
+ * Transform #1, nullable case: the JSON Schema type names that may stand
+ * opposite `"null"` in a `type` array for the `anyOf` rewrite to fire. An
+ * unrecognized name is left to the collapse — rewriting `{type:["foo","null"]}`
+ * into a two-branch union would emit an unmeasured shape built around a type no
+ * provider knows, where the collapse at least degrades to prose.
+ */
+const NULLABLE_UNION_TYPES = new Set([
+    "string",
+    "number",
+    "integer",
+    "boolean",
+    "object",
+    "array",
+]);
+/**
+ * Keywords whose presence on a node disqualifies it from the nullable rewrite.
+ * Each is a construct the emitted `anyOf` would have to be evaluated ALONGSIDE
+ * (an `anyOf` sibling to an `oneOf`, an `if`/`then` keyed off the node's type,
+ * …), and no such combination has been measured against a provider. A node
+ * carrying one keeps transform #1's collapse.
+ */
+const NULLABLE_REWRITE_BLOCKERS = [
+    "anyOf",
+    "oneOf",
+    "allOf",
+    "not",
+    "if",
+    "then",
+    "else",
+];
+/**
+ * The type-bearing keywords that move from a nullable node onto its typed
+ * branch, where they constrain the non-null value they were written for. Every
+ * one of them is meaningless against `null`, so leaving them on the outer node
+ * beside the union would say something the author never meant.
+ *
+ * The object-structure keywords move as a GROUP, and that is load-bearing
+ * rather than tidy. `additionalProperties` is defined against the keys that
+ * `properties` and `patternProperties` did NOT match *in the same schema
+ * object*, so moving two of the three and stranding the third silently changes
+ * what the schema says: for `{properties:{a}, patternProperties:{"^x":…},
+ * additionalProperties:{…}}`, a key `x1` was exempt from
+ * `additionalProperties` and, split across the union boundary, stops being
+ * exempt. `dependencies` / `dependentRequired` / `dependentSchemas` travel with
+ * them because they describe the same object form.
+ *
+ * Two groups deliberately stay OUTSIDE. Annotations (`description`, `title`,
+ * `default`, `examples`, `deprecated`, `readOnly`, `writeOnly`, `$comment`)
+ * describe the property as a whole, including its null case, and duplicating a
+ * description into the branch would show the model the same sentence twice. And
+ * `unevaluatedProperties` / `unevaluatedItems` are defined over the annotations
+ * every applicable schema produced — the `anyOf` branches included — so the
+ * outer node is exactly where they belong; moving one inside would narrow it to
+ * the branch's own keywords. Anything else the node carries (`$defs`, `$id`, an
+ * unknown keyword) stays outside too, keeping the treatment it has today.
+ */
+const NULLABLE_BRANCH_KEYS = new Set([
+    "minLength",
+    "maxLength",
+    "pattern",
+    "format",
+    "enum",
+    "const",
+    "minimum",
+    "maximum",
+    "exclusiveMinimum",
+    "exclusiveMaximum",
+    "multipleOf",
+    "items",
+    "prefixItems",
+    "minItems",
+    "maxItems",
+    "uniqueItems",
+    "properties",
+    "patternProperties",
+    "required",
+    "additionalProperties",
+    "propertyNames",
+    "minProperties",
+    "maxProperties",
+    "dependencies",
+    "dependentRequired",
+    "dependentSchemas",
+    "contentMediaType",
+    "contentEncoding",
+]);
 /**
  * Ceiling on how many property subschemas transform #8 may copy down across ALL
  * branches of one root composition.
@@ -786,20 +928,154 @@ function sanitizeCompositionBranch(branch, depth, parentProperties, budget) {
     // Arrays and boolean/primitive schemas carry no `required` to resolve.
     if (!isPlainObject(branch))
         return sanitizeSubschema(branch, depth);
-    const sanitized = sanitizeSchemaNode(branch, depth, parentProperties);
     // A non-null budget marks a ROOT composition — the only place the
-    // self-sufficiency repair applies (see the module header).
+    // self-sufficiency repair applies, and the only place transform #1's nullable
+    // rewrite stands down (see the module header).
+    const sanitized = sanitizeSchemaNode(branch, depth, parentProperties, budget !== null);
     return budget
         ? makeBranchSelfSufficient(sanitized, parentProperties, budget)
         : sanitized;
 }
+/**
+ * Transform #1, nullable case: decide whether this node is a nullable single
+ * type — `["string","null"]` and friends — that should be REWRITTEN to an
+ * `anyOf` union instead of collapsed. Returns the non-null type name, or `null`
+ * when the node keeps today's collapse.
+ *
+ * Order of the members does not matter and duplicates are tolerated
+ * (`["null","string"]`, `["string","null","null"]`); what must hold is that
+ * exactly one distinct non-`"null"` type is present, alongside at least one
+ * `"null"`.
+ *
+ * Four shapes opt out, each for a measured or structural reason:
+ *   - The ROOT and a branch of a ROOT composition (`isRootCompositionBranch`).
+ *     The root must be an object for every provider, and a root union branch
+ *     carrying its OWN `anyOf` is 0/3 on Grok — so rewriting there would turn a
+ *     usable branch into one transform #9 rule (a) drops, taking the whole
+ *     keyword (and with it every shape the union advertised) with it.
+ *   - A sibling `enum`/`const` that excludes one of the two arms. These are
+ *     AND-ed with `type`, so `{type:["string","null"], enum:["x"]}` means "must
+ *     be \"x\"" and `{…, enum:[null]}` means "must be null". The rewrite moves
+ *     the keyword onto the TYPED branch, leaving `{type:"null"}` unconstrained
+ *     by it — so emitting the union would admit a value the node forbade. Both
+ *     directions keep the collapse; `const: null` is the exception that still
+ *     rewrites, because there the typed branch is unsatisfiable and the union
+ *     reduces to "must be null", which is what the node says (collapsing it
+ *     would give the unsatisfiable `{type:"string", const:null}` instead).
+ *   - A COMPOSITION BRANCH whose `required` reaches the ENCLOSING node's
+ *     `properties` — the extra scope transform #8 gives it. Moving such a name
+ *     inside a nested `anyOf` puts it two levels from that scope, which is
+ *     exactly the dangling `required` transform #3 exists to prevent on Gemini.
+ *     A branch whose `required` is covered by its OWN `properties` needs no
+ *     exception and is rewritten normally.
+ */
+function nullableUnionType(node, parentProperties, isRootCompositionBranch) {
+    if (isRootCompositionBranch)
+        return null;
+    const declared = node.type;
+    if (!Array.isArray(declared))
+        return null;
+    let typed = null;
+    let sawNull = false;
+    for (const member of declared) {
+        if (typeof member !== "string")
+            return null;
+        if (member === "null") {
+            sawNull = true;
+            continue;
+        }
+        if (!NULLABLE_UNION_TYPES.has(member))
+            return null;
+        if (typed !== null && typed !== member)
+            return null;
+        typed = member;
+    }
+    if (!sawNull || typed === null)
+        return null;
+    if (NULLABLE_REWRITE_BLOCKERS.some((key) => hasOwn(node, key)))
+        return null;
+    // A sibling `enum`/`const` is AND-ed with `type`, so it decides whether the
+    // two arms the `type` array advertises are BOTH actually reachable — and the
+    // rewrite may only emit an arm the input really allows. Moving the keyword
+    // onto the typed branch leaves the `{type:"null"}` branch unconstrained by
+    // it, so emitting that branch when the enum excludes `null` would admit a
+    // value the author forbade (`{type:["string","null"], enum:["x"]}` means
+    // "must be \"x\""), and emitting the typed branch when only `null` is allowed
+    // would admit every string. Either way the union would say more than the node
+    // did, so both keep the collapse.
+    //
+    // `const: null` is the one shape that still rewrites: the typed branch is
+    // then unsatisfiable and the union reduces to "must be null", exactly what
+    // the node means — where collapsing it would produce the unsatisfiable
+    // `{type:"string", const:null}` instead, which is strictly worse.
+    if (hasOwn(node, "const") && node.const !== null)
+        return null;
+    if (hasOwn(node, "enum")) {
+        if (!Array.isArray(node.enum))
+            return null;
+        const permitsNull = node.enum.some((member) => member === null);
+        const permitsNonNull = node.enum.some((member) => member !== null);
+        if (!permitsNull || !permitsNonNull)
+            return null;
+    }
+    // Only a `required` name that actually REACHES the parent scope forces the
+    // collapse. A branch whose `required` is satisfied by its own `properties`
+    // loses nothing by being rewritten, and declining there would keep the
+    // invented-value failure for a node that has no need of the exception. Key
+    // names survive sanitization unchanged, so the raw map answers this.
+    if (parentProperties != null && Array.isArray(node.required)) {
+        const own = isPlainObject(node.properties) ? node.properties : null;
+        const reachesParentScope = node.required.some((name) => typeof name === "string" && !(own !== null && hasOwn(own, name)));
+        if (reachesParentScope)
+            return null;
+    }
+    return typed;
+}
+/**
+ * Build the typed branch of a nullable rewrite: the node's own type-bearing
+ * keywords (`NULLABLE_BRANCH_KEYS`) under a scalar `type`, with `null` removed
+ * from an `enum` because the sibling `{type:"null"}` branch already carries
+ * that fact — and leaving it would make transform #2 emit a "May also be null."
+ * note the schema no longer needs.
+ *
+ * The branch is run back through `sanitizeSchemaNode` rather than assembled by
+ * hand so every per-node transform applies to it exactly as it would to any
+ * scalar-typed node: transform #12 retypes it to `"object"` when it carries
+ * `properties`, transform #13 drops an unsupported `pattern` into prose on the
+ * branch, transform #3 resolves its `required` against its own `properties`,
+ * and transform #2 filters its `enum`.
+ *
+ * Sanitized at THIS node's depth, not one deeper. The branch is a
+ * re-expression of the node, so its children sit exactly where they sat before
+ * the rewrite, and the depth budget they are charged is unchanged. No
+ * `parentProperties` is passed: the only branch that could have used one — a
+ * composition branch carrying `required` — is excluded by `nullableUnionType`.
+ */
+function buildNullableBranch(node, typeName, depth) {
+    const branch = { type: typeName };
+    for (const [key, value] of Object.entries(node)) {
+        if (!NULLABLE_BRANCH_KEYS.has(key))
+            continue;
+        if (key === "enum" && Array.isArray(value)) {
+            branch.enum = value.filter((member) => member !== null);
+            continue;
+        }
+        safeSet(branch, key, value);
+    }
+    return sanitizeSchemaNode(branch, depth);
+}
 /**
  * @param parentProperties When this node is a composition branch, the enclosing
  *   node's SANITIZED `properties` map — the extra scope its `required` may name
  *   (transform #8). `undefined`/`null` for every other node, which keeps
  *   transform #3's own-properties-only rule exactly as it was.
+ * @param isRootCompositionBranch True when this node is an element of a
+ *   composition on the parameters ROOT. Only transform #1's nullable rewrite
+ *   reads it, and only to decline: such a branch is judged individually by
+ *   transform #9 rule (a), which rejects any branch carrying its own
+ *   `anyOf`/`oneOf`.
  */
-function sanitizeSchemaNode(node, depth, parentProperties) {
+function sanitizeSchemaNode(node, depth, parentProperties, isRootCompositionBranch = false) {
     // Depth guard: stop walking absurdly nested input rather than overflowing
     // the stack. Real tool schemas are a few levels deep; anything past
     // MAX_DEPTH is adversarial, so the subtree is replaced with the
@@ -809,10 +1085,27 @@ function sanitizeSchemaNode(node, depth, parentProperties) {
     if (depth > MAX_DEPTH)
         return {};
     const childDepth = depth + 1;
+    // Transform #1, nullable case. A NON-root `{type:["T","null"], …}` is emitted
+    // as `anyOf: [<T branch>, {type:"null"}]` rather than collapsed to `T` with a
+    // prose note, because prose loses to the schema: a model reading
+    // `{type:"string", minLength:1}` cannot express "none" in the half of the
+    // declaration it treats as binding, so it invents a value that satisfies the
+    // type instead (see the module header). Decided first because everything
+    // below — the `properties` pre-pass, the type resolution, the enum rule, the
+    // notes — belongs to the BRANCH when the rewrite fires, not to the node that
+    // now carries only the union and its annotations.
+    const nullableType = depth > 0
+        ? nullableUnionType(node, parentProperties, isRootCompositionBranch)
+        : null;
+    const nullableBranch = nullableType === null
+        ? null
+        : buildNullableBranch(node, nullableType, depth);
     // Sanitized `properties`, computed ahead of the key walk because transform #8
     // needs it before the walk reaches whichever of `properties` / `oneOf` comes
     // first in key order. Emitted verbatim when the walk reaches `properties`.
-    const sanitizedProperties = hasOwn(node, "properties")
+    // Skipped entirely under a nullable rewrite, where `properties` has moved
+    // onto the typed branch and was sanitized there.
+    const sanitizedProperties = nullableType === null && hasOwn(node, "properties")
         ? sanitizePropertiesKeyword(node.properties, childDepth)
         : undefined;
     const ownProperties = isPlainObject(sanitizedProperties)
@@ -836,16 +1129,25 @@ function sanitizeSchemaNode(node, depth, parentProperties) {
     const declaresProperty = (name) => (ownProperties !== null && hasOwn(ownProperties, name)) ||
         (parentProperties != null && hasOwn(parentProperties, name));
     // Resolve the node's effective single `type`, collapsing a JSON Schema
-    // `type` ARRAY (a union, e.g. `["string","number","boolean"]` or a nullable
-    // `["string","null"]`) to the first non-"null" member. Gemini's
-    // function-declaration schema requires a single `type` and hard-rejects a
-    // type array, which manifests as a misleading downstream error. Computed up
-    // front (not in key order) because the `enum` decision below depends on it.
+    // `type` ARRAY (a MULTI-type union, e.g. `["string","number","boolean"]`) to
+    // the first non-"null" member. Gemini's function-declaration schema requires
+    // a single `type` and hard-rejects a type array, which manifests as a
+    // misleading downstream error. Computed up front (not in key order) because
+    // the `enum` decision below depends on it. The nullable case
+    // (`["string","null"]`) took the `anyOf` rewrite above and never gets here —
+    // except at the root and the two branch positions that decline it, which
+    // collapse like any other union.
     const notesFromRetype = [];
     let typeToEmit = node.type;
     let emitType = "type" in node;
     let singleType;
-    if (Array.isArray(node.type)) {
+    if (nullableType !== null) {
+        // The `type` key's slot is taken by the `anyOf` emitted in the walk below,
+        // so nothing resolves a scalar type here and no note is manufactured: the
+        // union states the nullability the note used to approximate.
+        emitType = false;
+    }
+    else if (Array.isArray(node.type)) {
         const nonNull = node.type.filter((t) => t !== "null");
         if (nonNull.length > 0) {
             typeToEmit = nonNull[0];
@@ -894,7 +1196,7 @@ function sanitizeSchemaNode(node, depth, parentProperties) {
     // which every provider accepts) so the model still sees it. Computed up
     // front so it can be appended wherever `description` appears in key order.
     const notes = [...notesFromRetype];
-    if (Array.isArray(node.type)) {
+    if (nullableType === null && Array.isArray(node.type)) {
         const typeNames = node.type.filter((t) => typeof t === "string");
         if (typeNames.length > 1) {
             notes.push(`Accepts ${humanJoin(typeNames)}.`);
@@ -904,7 +1206,7 @@ function sanitizeSchemaNode(node, depth, parentProperties) {
             notes.push("Must be null.");
         }
     }
-    if (Array.isArray(node.enum)) {
+    if (nullableType === null && Array.isArray(node.enum)) {
         const stringMembers = node.enum.filter((v) => typeof v === "string");
         if (dropEnum || stringMembers.length === 0) {
             // The whole enum is dropped (non-string type, or no string members
@@ -920,7 +1222,8 @@ function sanitizeSchemaNode(node, depth, parentProperties) {
     }
     // Transform #13, decided up front so its note joins the others before
     // `descNote` is frozen and the loop below can simply skip the keyword.
-    const dropPattern = typeof node.pattern === "string" &&
+    const dropPattern = nullableType === null &&
+        typeof node.pattern === "string" &&
         usesUnsupportedRegexConstruct(node.pattern);
     if (dropPattern) {
         const pattern = node.pattern;
@@ -940,7 +1243,19 @@ function sanitizeSchemaNode(node, depth, parentProperties) {
         // by those names are handled safely inside `sanitizeSchemaMap`.)
         if (PROTO_KEYS.has(key))
             continue;
+        // Transform #1, nullable case: every type-bearing keyword has moved onto
+        // the typed branch, which was sanitized as a node in its own right. Only
+        // the node's annotations (and any keyword outside both sets) stay here.
+        if (nullableType !== null && NULLABLE_BRANCH_KEYS.has(key))
+            continue;
         if (key === "type") {
+            if (nullableBranch !== null) {
+                // Emitted in the `type` key's own position so key order stays
+                // deterministic — which is what lets a second pass, finding an `anyOf`
+                // it leaves alone, reproduce this object exactly.
+                out.anyOf = [nullableBranch, { type: "null" }];
+                continue;
+            }
             if (emitType)
                 out.type = typeToEmit;
             continue;