@cubicecho/agent-core 2.23.0 → 2.24.0

package/dist/hooks.d.ts

@@ -1,4 +1,5 @@
 import type OpenAI from "openai";
+import { type HookEvent } from "./hook-events.ts";
 /**
  * Lifecycle hooks, from the host's side: what a session looks like to them, where their context
  * lands in a request, and what is said about each one.
@@ -9,20 +10,6 @@ import type OpenAI from "openai";
  * `runHooks` is a runner as it stands and its outcomes pass straight through, without this
  * package depending on it.
  */
-/**
- * A point in a session a hook can be bound to. Named after Claude Code's hooks of the same shape
- * — `sessionStart` (SessionStart), `beforeTurn` (UserPromptSubmit), `afterTurn` (Stop),
- * `beforeCompact` (PreCompact), `sessionEnd` (SessionEnd) — plus `sessionDelete`, for when the host
- * deletes a session's record.
- */
-export type HookEvent = "sessionStart" | "beforeTurn" | "afterTurn" | "beforeCompact" | "sessionEnd" | "sessionDelete";
-/** Every event a hook can be bound to, in the order a session meets them. */
-export declare const HOOK_EVENTS: readonly HookEvent[];
-/**
- * The events whose hooks run before a request, and so the only ones whose output can reach it.
- * Anything later runs once the model has already answered.
- */
-export declare const INJECT_EVENTS: ReadonlySet<HookEvent>;
 /**
  * One message of a session as a hook is handed it. The shape a memory server's `remember` takes,
  * so a template can pass a turn straight through.
@@ -248,6 +235,18 @@ export declare const UNTRUSTED_PREFACE: string;
 export declare function untrusted(text: string, { source }?: {
     source?: string;
 }): string;
+/**
+ * A message's text, whether its content is a string or a list of parts.
+ *
+ * Parts are joined with nothing between them, because they are one text an API split rather than
+ * several: a space put in is a character the sender never wrote, and `turnMessages` hashes this
+ * into the uuid a memory server dedups on. Compaction reads the same function, so the summariser
+ * and the hook told about a fold see one message the same way. A refusal part is left out.
+ *
+ * @param content A message's `content`, in any of the shapes the API allows. One that is neither
+ * a string nor a list reads as empty.
+ */
+export declare const textOf: (content: unknown) => string;
 /**
  * A stretch of a transcript as a hook reads it: what the user and the assistant said, and nothing
  * else.

package/dist/hooks.js

@@ -1,21 +1,9 @@
 import { createHash } from "node:crypto";
 import { errorMessage } from "./errors.js";
+import { isPositive } from "./guards.js";
+import { INJECT_EVENTS } from "./hook-events.js";
 import { scoped } from "./scope.js";
-import { estimateTokens } from "./tokens.js";
-/** Every event a hook can be bound to, in the order a session meets them. */
-export const HOOK_EVENTS = [
-    "sessionStart",
-    "beforeTurn",
-    "afterTurn",
-    "beforeCompact",
-    "sessionEnd",
-    "sessionDelete",
-];
-/**
- * The events whose hooks run before a request, and so the only ones whose output can reach it.
- * Anything later runs once the model has already answered.
- */
-export const INJECT_EVENTS = new Set(["sessionStart", "beforeTurn"]);
+import { CHARS_PER_TOKEN, estimateTokens } from "./tokens.js";
 /**
  * The most context all of a request's hooks add between them by default, in estimated tokens.
  *
@@ -55,9 +43,8 @@ const hookSettings = scoped(() => ({ ...HOOK_DEFAULTS }));
  */
 export function configureHooks(options = {}) {
     const { contextTokens, preface } = options;
-    if (typeof contextTokens === "number" && contextTokens > 0) {
+    if (isPositive(contextTokens))
         hookSettings().contextTokens = contextTokens;
-    }
     if (typeof preface === "string")
         hookSettings().preface = preface;
     return { ...hookSettings() };
@@ -75,8 +62,19 @@ export const resetHooks = () => {
  * same rule `configureHooks` applies, so a `0` threaded through for "no opinion" does not quietly
  * turn every hook's context off.
  */
-const budget = (given) => typeof given === "number" && given > 0 ? given : hookSettings().contextTokens;
+const budget = (given) => (isPositive(given) ? given : hookSettings().contextTokens);
 const attribute = (text) => text.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;");
+/** What every note about an outcome opens with: which hook it was, and on which event. */
+const noteOf = (outcome) => ({
+    event: outcome.event,
+    source: outcome.label,
+    hookId: outcome.hookId,
+});
+/** The note a failed outcome leaves, the same whichever of the three callers reports it. */
+const failureNote = (outcome) => ({
+    ...noteOf(outcome),
+    error: outcome.error ?? "failed",
+});
 /**
  * Builds the context a set of outcomes adds and the notes that go with it.
  *
@@ -100,9 +98,8 @@ export function assembleContext(outcomes, maxTokens) {
     const notes = [];
     let remaining = budget(maxTokens);
     for (const outcome of outcomes) {
-        const base = { event: outcome.event, source: outcome.label, hookId: outcome.hookId };
         if (!outcome.ok) {
-            notes.push({ ...base, error: outcome.error ?? "failed" });
+            notes.push(failureNote(outcome));
             continue;
         }
         if (!outcome.inject || !INJECT_EVENTS.has(outcome.event))
@@ -114,11 +111,11 @@ export function assembleContext(outcomes, maxTokens) {
         if (cap <= 0)
             continue;
         if (estimateTokens(text) > cap)
-            text = `${text.slice(0, cap * 4 - 1).trimEnd()}…`;
+            text = `${text.slice(0, cap * CHARS_PER_TOKEN - 1).trimEnd()}…`;
         const tokens = estimateTokens(text);
         remaining -= tokens;
         blocks.push(`<context source="${attribute(outcome.label)}">\n${text}\n</context>`);
-        notes.push({ ...base, tokens, text });
+        notes.push({ ...noteOf(outcome), tokens, text });
     }
     return { context: blocks.join("\n\n"), notes };
 }
@@ -187,8 +184,18 @@ export function untrusted(text, { source } = {}) {
     const attrs = source === undefined ? "" : ` source="${attribute(source)}"`;
     return `<untrusted${attrs}>\n${text.replace(UNTRUSTED_TAG, "&lt;$1")}\n</untrusted>`;
 }
-/** A message's text, whether its content is a string or a list of parts. */
-const textOf = (content) => {
+/**
+ * A message's text, whether its content is a string or a list of parts.
+ *
+ * Parts are joined with nothing between them, because they are one text an API split rather than
+ * several: a space put in is a character the sender never wrote, and `turnMessages` hashes this
+ * into the uuid a memory server dedups on. Compaction reads the same function, so the summariser
+ * and the hook told about a fold see one message the same way. A refusal part is left out.
+ *
+ * @param content A message's `content`, in any of the shapes the API allows. One that is neither
+ * a string nor a list reads as empty.
+ */
+export const textOf = (content) => {
     if (typeof content === "string")
         return content;
     if (!Array.isArray(content))
@@ -318,9 +325,7 @@ export async function gather(run, events, context, { signal, onNote, maxTokens,
  */
 export async function notify(run, event, context, onNote) {
     const outcomes = await runSafely(run, event, context);
-    const notes = outcomes
-        .filter((outcome) => !outcome.ok)
-        .map((outcome) => assembleContext([outcome]).notes[0]);
+    const notes = outcomes.filter((outcome) => !outcome.ok).map(failureNote);
     for (const note of notes)
         onNote?.(note);
     return notes;
@@ -345,15 +350,9 @@ export async function consult(run, event, context, onNote) {
     const notes = [];
     for (const outcome of outcomes) {
         if (!outcome.ok)
-            notes.push(assembleContext([outcome]).notes[0]);
-        else if (outcome.veto === true) {
-            notes.push({
-                event: outcome.event,
-                source: outcome.label,
-                hookId: outcome.hookId,
-                veto: true,
-            });
-        }
+            notes.push(failureNote(outcome));
+        else if (outcome.veto === true)
+            notes.push({ ...noteOf(outcome), veto: true });
     }
     for (const note of notes)
         onNote?.(note);

package/dist/index.d.ts

@@ -19,18 +19,19 @@ export type { AgentConfig, Endpoint, ModelParams, RetryPolicy, ToolPolicy, } fro
 export { type ContinueTurnOptions, continueTurn, isContinuable, } from "./continuation.ts";
 export { AgentLoopError, type AgentLoopFailure, AgentLoopOverflow, errorMessage, failedRun, ToolIterationLimit, } from "./errors.ts";
 export { configureEvents, type EventBusOptions, emit, endRun, fold, history, type RunEvent, type RunEventInput, type RunEventKind, type RunMetrics, type RunMetricsOptions, type RunUsage, resetEvents, runMetrics, type TurnReport, watch, } from "./events.ts";
-export { assembleContext, configureHooks, consult, type Gathered, gather, HOOK_CONTEXT_TOKENS, HOOK_EVENTS, HOOK_PREFACE, type HookContext, type HookEvent, type HookMessage, type HookNote, type HookOptions, type HookOutcome, type HookRunner, INJECT_EVENTS, notify, resetHooks, turnIndex, turnMessages, UNTRUSTED_PREFACE, untrusted, withContext, } from "./hooks.ts";
+export { HOOK_EVENTS, type HookEvent, INJECT_EVENTS } from "./hook-events.ts";
+export { assembleContext, configureHooks, consult, type Gathered, gather, HOOK_CONTEXT_TOKENS, HOOK_PREFACE, type HookContext, type HookMessage, type HookNote, type HookOptions, type HookOutcome, type HookRunner, notify, resetHooks, turnIndex, turnMessages, UNTRUSTED_PREFACE, untrusted, withContext, } from "./hooks.ts";
 export { estimateFrom, type LedgerEntry, type LedgerEstimateOptions, type LedgerRequest, rebaseLedger, recordRequest, type TokenLedger, tokensBetween, } from "./ledger.ts";
 export { resetAll } from "./reset.ts";
-export { backoffMs, CHARS_PER_TOKEN, type ContextBreakdown, type ContextBreakdownOptions, ContextOverflow, compact, contextChars, contextTokens, EndpointSilent, isModelLoading, isOverflow, isTransient, LOADING_POLL_MS, LOADING_TIMEOUT_MS, messageTokens, requestChars, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, type TokenEstimateOptions, toolsChars, } from "./retry.ts";
+export { backoffMs, type ContextBreakdown, type ContextBreakdownOptions, ContextOverflow, compact, contextChars, contextTokens, EndpointSilent, isModelLoading, isOverflow, isTransient, LOADING_POLL_MS, LOADING_TIMEOUT_MS, messageTokens, requestChars, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, type TokenEstimateOptions, toolsChars, } from "./retry.ts";
 export { type RunTurnOptions, runTurn } from "./run-turn.ts";
 export { createRuntime, defaultRuntime, type Runtime, type RuntimeOptions } from "./runtime.ts";
-export { isGrammarError, relaxTools, sanitizeTools } from "./schema-compat.ts";
+export { isGrammarError, relaxSchema, relaxTools, sanitizeSchema, sanitizeTools, } from "./schema-compat.ts";
 export { type AskJsonOptions, ask, askJson, clean, listLines, parseJson, resetHints, type SideTask, type SideTaskInput, type SideTaskOptions, tryAsk, } from "./side-task.ts";
 export { CAPABILITY_SNAPSHOT_VERSION, type CapabilitySnapshot, type EndpointSnapshot, exportCapabilities, importCapabilities, type ModelSnapshot, } from "./snapshot.ts";
 export { AGENT_SPEC, AGENT_SPEC_VERSION, AGENT_TASKS, type AgentHook, type AgentSpec, type EndpointSpec, type ExportSpecOptions, exportSpec, type ModelSpec, type ParsedSpec, type ParseSpecOptions, type PromptPart, parseSpec, RESOLVED_DEFAULTS, type ResolvedAgent, type ResolvedTask, type RetrySpec, resolveAgentSpec, SPEC_EVENTS, type SpecBundle, type SpecServer, type TaskSpec, type ToolsSpec, } from "./spec.ts";
 export { type Produced, type StreamTurnOptions, streamTurn, type Turn, type TurnUsage, } from "./stream.ts";
 export { ALL_FENCES, DEFAULT_FENCES, type Fence, FenceSplitter, type FenceSplitterOptions, type Split, stripThinking, THINK_FENCE, } from "./thinking.ts";
-export { estimateTokens } from "./tokens.ts";
+export { CHARS_PER_TOKEN, estimateTokens } from "./tokens.ts";
 export { parseToolArguments, recoverToolCalls, ToolArgumentsError, type ToolCall, } from "./tool-calls.ts";
 export { CALL_TOOL, carryOver, catalogList, catalogPrompt, expandNames, holdsDefinitions, inCatalog, KEYWORD_DROPOFF, KEYWORD_MIN_SCORE, type KeywordPreselection, type KeywordPreselectOptions, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_CARRIED, MAX_PER_LOAD, orderTools, PRESELECT_SCHEMA, PRESELECT_SYSTEM, PROXY_TOOLS, preselectByKeywords, preselectInput, preselection, preselectSystem, proxiedCall, proxyCatalogPrompt, proxyLoadResult, requestedNames, shownCall, type ToolMatch, type ToolOrder, } from "./tool-loading.ts";

package/dist/index.js

@@ -17,18 +17,19 @@ export { applyCompaction, COMPACT_AT, compactTranscript, KEEP_RATIO, planCompact
 export { continueTurn, isContinuable, } from "./continuation.js";
 export { AgentLoopError, AgentLoopOverflow, errorMessage, failedRun, ToolIterationLimit, } from "./errors.js";
 export { configureEvents, emit, endRun, fold, history, resetEvents, runMetrics, watch, } from "./events.js";
-export { assembleContext, configureHooks, consult, gather, HOOK_CONTEXT_TOKENS, HOOK_EVENTS, HOOK_PREFACE, INJECT_EVENTS, notify, resetHooks, turnIndex, turnMessages, UNTRUSTED_PREFACE, untrusted, withContext, } from "./hooks.js";
+export { HOOK_EVENTS, INJECT_EVENTS } from "./hook-events.js";
+export { assembleContext, configureHooks, consult, gather, HOOK_CONTEXT_TOKENS, HOOK_PREFACE, notify, resetHooks, turnIndex, turnMessages, UNTRUSTED_PREFACE, untrusted, withContext, } from "./hooks.js";
 export { estimateFrom, rebaseLedger, recordRequest, tokensBetween, } from "./ledger.js";
 export { resetAll } from "./reset.js";
-export { backoffMs, CHARS_PER_TOKEN, ContextOverflow, compact, contextChars, contextTokens, EndpointSilent, isModelLoading, isOverflow, isTransient, LOADING_POLL_MS, LOADING_TIMEOUT_MS, messageTokens, requestChars, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, toolsChars, } from "./retry.js";
+export { backoffMs, ContextOverflow, compact, contextChars, contextTokens, EndpointSilent, isModelLoading, isOverflow, isTransient, LOADING_POLL_MS, LOADING_TIMEOUT_MS, messageTokens, requestChars, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, toolsChars, } from "./retry.js";
 export { runTurn } from "./run-turn.js";
 export { createRuntime, defaultRuntime } from "./runtime.js";
-export { isGrammarError, relaxTools, sanitizeTools } from "./schema-compat.js";
+export { isGrammarError, relaxSchema, relaxTools, sanitizeSchema, sanitizeTools, } from "./schema-compat.js";
 export { ask, askJson, clean, listLines, parseJson, resetHints, tryAsk, } from "./side-task.js";
 export { CAPABILITY_SNAPSHOT_VERSION, exportCapabilities, importCapabilities, } from "./snapshot.js";
 export { AGENT_SPEC, AGENT_SPEC_VERSION, AGENT_TASKS, exportSpec, parseSpec, RESOLVED_DEFAULTS, resolveAgentSpec, SPEC_EVENTS, } from "./spec.js";
 export { streamTurn, } from "./stream.js";
 export { ALL_FENCES, DEFAULT_FENCES, FenceSplitter, stripThinking, THINK_FENCE, } from "./thinking.js";
-export { estimateTokens } from "./tokens.js";
+export { CHARS_PER_TOKEN, estimateTokens } from "./tokens.js";
 export { parseToolArguments, recoverToolCalls, ToolArgumentsError, } from "./tool-calls.js";
 export { CALL_TOOL, carryOver, catalogList, catalogPrompt, expandNames, holdsDefinitions, inCatalog, KEYWORD_DROPOFF, KEYWORD_MIN_SCORE, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_CARRIED, MAX_PER_LOAD, orderTools, PRESELECT_SCHEMA, PRESELECT_SYSTEM, PROXY_TOOLS, preselectByKeywords, preselectInput, preselection, preselectSystem, proxiedCall, proxyCatalogPrompt, proxyLoadResult, requestedNames, shownCall, } from "./tool-loading.js";

package/dist/retry.d.ts

@@ -29,13 +29,6 @@ export declare class ContextOverflow extends Error {
  * @param tokens The count to render.
  */
 export declare const compact: (tokens: number) => string;
-/**
- * The divisor behind `estimateTokens`, applied here to a character count rather than a string.
- *
- * The fallback, not the rule: once a turn has come back with a reported prompt count, `runTurn`
- * divides by what that endpoint's model was measured at instead. See `charsPerTokenFor`.
- */
-export declare const CHARS_PER_TOKEN = 4;
 /** What the two token estimates below take besides what they measure. */
 export interface TokenEstimateOptions {
     /**
@@ -192,6 +185,19 @@ export declare const SMALLEST_LIKELY_WINDOW = 8192;
  * @param error The rejection, as caught. What is not an SDK error is not transient.
  */
 export declare function isTransient(error: unknown): boolean;
+/**
+ * Whether a failure is the endpoint refusing the request as written, rather than losing it.
+ *
+ * 400 and 422 are what a server says when it read the body and disliked it, which makes them the
+ * only statuses worth answering by sending something different. Any 4xx is too wide: 401, 404 and
+ * 429 are 4xx and none of them is about the fields, and a 429 is one `isTransient` accepts — a
+ * caller that re-sent on it at once doubled the rate against a server that had just asked for less.
+ * Catching everything is wider still, since an abort or a connection that never landed then
+ * latches off whatever the re-send left out.
+ *
+ * @param error The rejection, as caught. What is not an SDK error refuses nothing.
+ */
+export declare const refusesRequest: (error: unknown) => boolean;
 /**
  * Whether a failure is a local server still loading the model, rather than one failing to serve.
  *

package/dist/retry.js

@@ -1,4 +1,5 @@
 import OpenAI from "openai";
+import { CHARS_PER_TOKEN } from "./tokens.js";
 /**
  * Everything about a request failing that is not about what the request said.
  *
@@ -62,13 +63,6 @@ const REFUSAL_PART = 32;
 const REASONING_KEY = 23;
 /** The same for `"reasoning":"",`, OpenRouter's spelling of it. */
 const REASONING_ALT_KEY = 15;
-/**
- * The divisor behind `estimateTokens`, applied here to a character count rather than a string.
- *
- * The fallback, not the rule: once a turn has come back with a reported prompt count, `runTurn`
- * divides by what that endpoint's model was measured at instead. See `charsPerTokenFor`.
- */
-export const CHARS_PER_TOKEN = 4;
 /** The divisor an option asked for, or the fallback when it asked for nothing usable. */
 const divisor = (charsPerToken) => charsPerToken !== undefined && charsPerToken > 0 ? charsPerToken : CHARS_PER_TOKEN;
 /**
@@ -349,6 +343,19 @@ export function isTransient(error) {
     const { status } = error;
     return status === 408 || status === 409 || status === 429 || (status ?? 0) >= 500;
 }
+/**
+ * Whether a failure is the endpoint refusing the request as written, rather than losing it.
+ *
+ * 400 and 422 are what a server says when it read the body and disliked it, which makes them the
+ * only statuses worth answering by sending something different. Any 4xx is too wide: 401, 404 and
+ * 429 are 4xx and none of them is about the fields, and a 429 is one `isTransient` accepts — a
+ * caller that re-sent on it at once doubled the rate against a server that had just asked for less.
+ * Catching everything is wider still, since an abort or a connection that never landed then
+ * latches off whatever the re-send left out.
+ *
+ * @param error The rejection, as caught. What is not an SDK error refuses nothing.
+ */
+export const refusesRequest = (error) => error instanceof OpenAI.APIError && (error.status === 400 || error.status === 422);
 /**
  * Whether a failure is a local server still loading the model, rather than one failing to serve.
  *

package/dist/run-turn.d.ts

@@ -77,6 +77,13 @@ export interface RunTurnOptions extends Omit<StreamTurnOptions, "produced"> {
      */
     loadingTimeoutMs?: number;
 }
+/**
+ * Builds a turn's request body from what the endpoint and the model have refused so far.
+ *
+ * A function rather than a body because a downgrade changes what is sent, so it is called again
+ * per attempt. Its second argument is absent where no model was named.
+ */
+export type RequestBuilder = (supports: Capabilities, model: ModelCapabilities | undefined) => OpenAI.ChatCompletionCreateParamsStreaming;
 /**
  * `request` is a callback rather than a body because the body has to be rebuilt from whatever
  * the last attempt latched off: the tools it sends depend on `strictSchemas`, and `relaxTools`
@@ -90,4 +97,4 @@ export interface RunTurnOptions extends Omit<StreamTurnOptions, "produced"> {
  * @param options Retry budget, context limit, the model to negotiate for, notices, and the
  * stream's own callbacks.
  */
-export declare function runTurn(client: OpenAI, supports: Capabilities, request: (supports: Capabilities, model: ModelCapabilities | undefined) => OpenAI.ChatCompletionCreateParamsStreaming, { maxRetries, onNotice, contextLimit, model, droppable, loadingTimeoutMs, ...stream }?: RunTurnOptions): Promise<Turn>;
+export declare function runTurn(client: OpenAI, supports: Capabilities, request: RequestBuilder, { maxRetries, onNotice, contextLimit, model, droppable, loadingTimeoutMs, ...stream }?: RunTurnOptions): Promise<Turn>;

package/dist/schema-compat.d.ts

@@ -1,4 +1,17 @@
 import type OpenAI from "openai";
+/**
+ * One JSON Schema as a strict server will accept it, for a schema that is not a tool's parameters.
+ *
+ * What `sanitizeTools` does to each tool, without the tool: a `response_format` schema goes through
+ * the same grammar converter a tool's parameters do, and a caller holding only the schema had to
+ * wrap it in a definition to get here. Nothing is remembered — the cache is keyed on a tool
+ * definition's identity, and a bare schema has no object that stands for it across requests.
+ *
+ * @param schema The schema as written. Never mutated. Its root is held to an object, as a tool's
+ * parameters are, and anything that is not a schema at all comes back as an object with no
+ * properties.
+ */
+export declare function sanitizeSchema(schema: unknown): Record<string, unknown>;
 /**
  * Tool definitions a strict server will accept, remembered per definition object.
  *
@@ -9,6 +22,16 @@ import type OpenAI from "openai";
  * changed, a new definition is returned in its place.
  */
 export declare const sanitizeTools: (tools: OpenAI.ChatCompletionTool[]) => OpenAI.ChatCompletionTool[];
+/**
+ * One schema without its `pattern` and `format` keywords, for a schema that is not a tool's.
+ *
+ * The retry `relaxTools` makes, on a bare schema. Only the keywords go: a property that happens to
+ * be called `format` is an argument name and stays.
+ *
+ * @param schema Already sanitised. Relaxing is the retry, not a substitute for `sanitizeSchema`.
+ * Never mutated; anything that is not a schema comes back as an object with no properties.
+ */
+export declare function relaxSchema(schema: unknown): Record<string, unknown>;
 /**
  * The retry shape: llama.cpp's converter rejects regex escape classes (`\d`, `\w`, `\s`) in
  * `pattern` and most `format` values, both of which only ever narrowed a string the tool

package/dist/schema-compat.js

@@ -1,4 +1,4 @@
-const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+import { isRecord } from "./guards.js";
 /** Lookahead and lookbehind: `(?=`, `(?!`, `(?<=`, `(?<!`. */
 const LOOKAROUND = /\(\?<?[=!]/;
 const PRIMITIVES = new Set(["object", "string", "number", "integer", "boolean", "array", "null"]);
@@ -20,6 +20,24 @@ const SCHEMA_KEYS = new Set([
 ]);
 /** Keys whose value is a name -> schema map. */
 const SCHEMA_MAPS = new Set(["properties", "patternProperties", "$defs", "definitions"]);
+/** The two spellings of a schema's own pool of named definitions. */
+const POOL_KEYS = ["definitions", "$defs"];
+/**
+ * One keyword's value with `fn` applied wherever it holds a schema, and untouched where it holds
+ * data — which is what keeps a walk out of `default`, `enum` and `const`.
+ */
+const mapChildren = (key, value, fn) => {
+    if (SCHEMA_KEYS.has(key))
+        return Array.isArray(value) ? value.map((sub) => fn(sub)) : fn(value);
+    // The keys here are argument names; only the values are schemas.
+    if (SCHEMA_MAPS.has(key) && isRecord(value))
+        return Object.fromEntries(Object.entries(value).map(([name, sub]) => [name, fn(sub)]));
+    return value;
+};
+/** The names a schema's `required` lists, without whatever in it is not a name. */
+const requiredOf = (node) => Array.isArray(node.required)
+    ? node.required.filter((name) => typeof name === "string")
+    : [];
 /**
  * Coerces one schema position. Malformed MCP output sometimes puts a bare type name where a
  * whole schema belongs, which the grammar converter reports as `Unrecognized schema: "object"`.
@@ -29,7 +47,7 @@ function asSchema(node) {
         return PRIMITIVES.has(node) && node !== "object" ? { type: node } : EMPTY_OBJECT();
     if (typeof node === "boolean")
         return node;
-    if (!isObject(node))
+    if (!isRecord(node))
         return EMPTY_OBJECT();
     return normalize(node);
 }
@@ -50,14 +68,8 @@ function normalize(node) {
             else
                 out.type = "null";
         }
-        else if (SCHEMA_KEYS.has(key)) {
-            out[key] = Array.isArray(value) ? value.map(asSchema) : asSchema(value);
-        }
-        else if (SCHEMA_MAPS.has(key) && isObject(value)) {
-            out[key] = Object.fromEntries(Object.entries(value).map(([name, sub]) => [name, asSchema(sub)]));
-        }
         else {
-            out[key] = value;
+            out[key] = mapChildren(key, value, asSchema);
         }
     }
     collapseNullableUnion(out);
@@ -66,7 +78,7 @@ function normalize(node) {
     if (typeof out.pattern === "string" && LOOKAROUND.test(out.pattern))
         delete out.pattern;
     // `{"type": "object"}` with no properties produces invalid GBNF.
-    if (out.type === "object" && !isObject(out.properties))
+    if (out.type === "object" && !isRecord(out.properties))
         out.properties = {};
     // Strict validators reject any sibling of `$ref`, and draft-07 ignores them, so a reference
     // stands alone or not at all. This is not hypothetical tidying: collapsing `anyOf: [{$ref},
@@ -88,11 +100,11 @@ function collapseNullableUnion(node) {
         const variants = node[key];
         if (!Array.isArray(variants))
             continue;
-        const concrete = variants.filter((item) => !(isObject(item) && item.type === "null"));
+        const concrete = variants.filter((item) => !(isRecord(item) && item.type === "null"));
         if (concrete.length !== 1 || concrete.length === variants.length)
             continue;
         delete node[key];
-        Object.assign(node, { nullable: true, ...(isObject(concrete[0]) ? concrete[0] : {}) });
+        Object.assign(node, { nullable: true, ...(isRecord(concrete[0]) ? concrete[0] : {}) });
     }
 }
 /** Combinators at the top level of a parameters schema; strict backends reject them outright. */
@@ -102,8 +114,8 @@ const LOCAL_POINTER = /^#\/(definitions|\$defs)\/([^/]+)$/;
 /** The `definitions` and `$defs` that a local pointer in this schema resolves against. */
 function poolsOf(parameters) {
     const defs = {};
-    for (const key of ["definitions", "$defs"])
-        if (isObject(parameters[key]))
+    for (const key of POOL_KEYS)
+        if (isRecord(parameters[key]))
             defs[key] = parameters[key];
     return defs;
 }
@@ -119,16 +131,16 @@ function poolsOf(parameters) {
 function resolveRef(node, defs) {
     const seen = new Set();
     let current = node;
-    while (isObject(current) && typeof current.$ref === "string") {
+    while (isRecord(current) && typeof current.$ref === "string") {
         const pointer = current.$ref;
         const target = LOCAL_POINTER.exec(pointer);
         if (!target || seen.has(pointer))
             return undefined;
         seen.add(pointer);
         const pool = defs[target[1]];
-        current = isObject(pool) ? pool[target[2]] : undefined;
+        current = isRecord(pool) ? pool[target[2]] : undefined;
     }
-    return isObject(current) ? current : undefined;
+    return isRecord(current) ? current : undefined;
 }
 /**
  * Replaces a root-level `$ref` with what it points at.
@@ -164,18 +176,16 @@ function mergeRootAllOf(out) {
     if (!Array.isArray(branches))
         return;
     const defs = poolsOf(out);
-    const properties = isObject(out.properties) ? { ...out.properties } : {};
-    const required = new Set(Array.isArray(out.required) ? out.required.filter((name) => typeof name === "string") : []);
+    const properties = isRecord(out.properties) ? { ...out.properties } : {};
+    const required = new Set(requiredOf(out));
     for (const raw of branches) {
         const branch = resolveRef(raw, defs);
         if (!branch)
             continue;
-        if (isObject(branch.properties))
+        if (isRecord(branch.properties))
             Object.assign(properties, branch.properties);
-        if (Array.isArray(branch.required))
-            for (const name of branch.required)
-                if (typeof name === "string")
-                    required.add(name);
+        for (const name of requiredOf(branch))
+            required.add(name);
     }
     if (!Object.keys(properties).length)
         return;
@@ -214,22 +224,16 @@ function mergeRootUnion(out) {
                 shared = new Set();
                 continue;
             }
-            if (isObject(branch.properties))
+            if (isRecord(branch.properties))
                 Object.assign(properties, branch.properties);
-            const names = Array.isArray(branch.required)
-                ? branch.required.filter((name) => typeof name === "string")
-                : [];
+            const names = requiredOf(branch);
             shared = previous === null ? new Set(names) : new Set(names.filter((n) => previous.has(n)));
         }
         if (!Object.keys(properties).length)
             continue;
-        out.properties = { ...(isObject(out.properties) ? out.properties : {}), ...properties };
-        if (shared?.size) {
-            const already = Array.isArray(out.required)
-                ? out.required.filter((name) => typeof name === "string")
-                : [];
-            out.required = [...new Set([...already, ...shared])];
-        }
+        out.properties = { ...(isRecord(out.properties) ? out.properties : {}), ...properties };
+        if (shared?.size)
+            out.required = [...new Set([...requiredOf(out), ...shared])];
     }
 }
 /**
@@ -246,7 +250,7 @@ function collectRefs(node, into) {
             collectRefs(item, into);
         return;
     }
-    if (!isObject(node))
+    if (!isRecord(node))
         return;
     for (const [key, value] of Object.entries(node)) {
         if (key === "$ref" && typeof value === "string")
@@ -269,7 +273,7 @@ function collectRefs(node, into) {
  * outside it still refers in.
  */
 function pruneDefs(out) {
-    const pools = ["definitions", "$defs"].filter((key) => isObject(out[key]));
+    const pools = POOL_KEYS.filter((key) => isRecord(out[key]));
     if (!pools.length)
         return;
     const live = {};
@@ -282,7 +286,7 @@ function pruneDefs(out) {
                 continue;
             const [, poolKey, name] = target;
             const pool = out[poolKey];
-            if (!isObject(pool) || !(name in pool))
+            if (!isRecord(pool) || !(name in pool))
                 continue;
             live[poolKey] ??= new Set();
             const names = live[poolKey];
@@ -317,24 +321,36 @@ function pruneDefs(out) {
 function pruneRequired(out) {
     if (!Array.isArray(out.required))
         return;
-    const properties = isObject(out.properties) ? out.properties : {};
+    const properties = isRecord(out.properties) ? out.properties : {};
     const kept = out.required.filter((name) => typeof name === "string" && name in properties);
     if (kept.length)
         out.required = kept;
     else
         delete out.required;
 }
-function sanitizeParameters(parameters) {
-    if (!isObject(parameters))
+/**
+ * One JSON Schema as a strict server will accept it, for a schema that is not a tool's parameters.
+ *
+ * What `sanitizeTools` does to each tool, without the tool: a `response_format` schema goes through
+ * the same grammar converter a tool's parameters do, and a caller holding only the schema had to
+ * wrap it in a definition to get here. Nothing is remembered — the cache is keyed on a tool
+ * definition's identity, and a bare schema has no object that stands for it across requests.
+ *
+ * @param schema The schema as written. Never mutated. Its root is held to an object, as a tool's
+ * parameters are, and anything that is not a schema at all comes back as an object with no
+ * properties.
+ */
+export function sanitizeSchema(schema) {
+    if (!isRecord(schema))
         return EMPTY_OBJECT();
-    const out = normalize(inlineRootRef(parameters));
+    const out = normalize(inlineRootRef(schema));
     mergeRootAllOf(out);
     mergeRootUnion(out);
     for (const key of TOP_LEVEL_COMBINATORS)
         delete out[key];
     if (out.type !== "object")
         out.type = "object";
-    if (!isObject(out.properties))
+    if (!isRecord(out.properties))
         out.properties = {};
     pruneRequired(out);
     pruneDefs(out);
@@ -386,7 +402,7 @@ const through = (cache, tools, fn) => tools.map((tool) => {
  * @param tools The definitions as the pool hands them over. Never mutated — where a schema
  * changed, a new definition is returned in its place.
  */
-export const sanitizeTools = (tools) => through(sanitized, tools, sanitizeParameters);
+export const sanitizeTools = (tools) => through(sanitized, tools, sanitizeSchema);
 /**
  * Walked as a schema rather than as arbitrary JSON, because `pattern` and `format` are keyword
  * names and perfectly ordinary argument names at once. Matching on the key alone deleted a
@@ -394,29 +410,33 @@ export const sanitizeTools = (tools) => through(sanitized, tools, sanitizeParame
  * argument that no longer existed — which every strict validator rejects, so the retry produced
  * the failure it was reaching for. The same distinction keeps the walk out of `default`, `enum`
  * and `const`, whose contents are data, not schema.
- *
- * At module scope rather than inside `relaxTools`, so the closure is made once rather than per
- * call — which, on the path this is on, is per request.
  */
 const strip = (node) => {
     if (Array.isArray(node))
         return node.map(strip);
-    if (!isObject(node))
+    if (!isRecord(node))
         return node;
     const out = {};
     for (const [key, value] of Object.entries(node)) {
         if (key === "pattern" || key === "format")
             continue;
-        if (SCHEMA_KEYS.has(key))
-            out[key] = Array.isArray(value) ? value.map(strip) : strip(value);
-        else if (SCHEMA_MAPS.has(key) && isObject(value))
-            // The keys here are argument names; only the values are schemas.
-            out[key] = Object.fromEntries(Object.entries(value).map(([name, sub]) => [name, strip(sub)]));
-        else
-            out[key] = value;
+        out[key] = mapChildren(key, value, strip);
     }
     return out;
 };
+/**
+ * One schema without its `pattern` and `format` keywords, for a schema that is not a tool's.
+ *
+ * The retry `relaxTools` makes, on a bare schema. Only the keywords go: a property that happens to
+ * be called `format` is an argument name and stays.
+ *
+ * @param schema Already sanitised. Relaxing is the retry, not a substitute for `sanitizeSchema`.
+ * Never mutated; anything that is not a schema comes back as an object with no properties.
+ */
+export function relaxSchema(schema) {
+    const stripped = strip(schema);
+    return isRecord(stripped) ? stripped : EMPTY_OBJECT();
+}
 /**
  * The retry shape: llama.cpp's converter rejects regex escape classes (`\d`, `\w`, `\s`) in
  * `pattern` and most `format` values, both of which only ever narrowed a string the tool
@@ -424,10 +444,7 @@ const strip = (node) => {
  *
  * @param tools Already sanitised. Relaxing is the retry, not a substitute for `sanitizeTools`.
  */
-export const relaxTools = (tools) => through(relaxed, tools, (parameters) => {
-    const stripped = strip(parameters);
-    return isObject(stripped) ? stripped : EMPTY_OBJECT();
-});
+export const relaxTools = (tools) => through(relaxed, tools, relaxSchema);
 /**
  * Qwen chat templates raise this when the transcript has no user turn. Some servers wrap it
  * in the same "unable to generate parser" wording as a real schema failure, and stripping