@cubicecho/agent-core 2.4.0 → 2.6.0

package/dist/agent-loop.js

@@ -0,0 +1,355 @@
+import { capabilitiesFor } from "./capabilities.js";
+import { getClient, NO_KEY, timeoutMs } from "./client.js";
+import { errorMessage } from "./errors.js";
+import { gather, notify, turnIndex, turnMessages, withContext, } from "./hooks.js";
+import { runTurn } from "./run-turn.js";
+import { relaxTools, sanitizeTools } from "./schema-compat.js";
+import { askJson, tryAsk } from "./side-task.js";
+import { parseToolArguments, recoverToolCalls } from "./tool-calls.js";
+import { catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadResult, MAX_PER_LOAD, PRESELECT_SCHEMA, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.js";
+/**
+ * The loop above a turn: send, run the tools the model asked for, send again, until it stops
+ * asking.
+ *
+ * Three servers wrote this loop separately after `runTurn` had already been pulled in here, and
+ * the copies drifted the way the turn's own had — one noticed a turn cut off at the ceiling and
+ * two did not, one tested the ceiling's spelling the other way round, one sent a reasoning effort
+ * and two never did. What is here is the part that does not know what the run is for; the
+ * prompts, the tools and what a run means stay with the caller.
+ */
+/** The fields `extraBody` may not override, because the loop's request is built around them. */
+const RESERVED = new Set(["model", "messages", "stream", "tools"]);
+/**
+ * The one place a streamed request's body is decided from a config and what the endpoint and
+ * the model have refused.
+ *
+ * Every field that negotiates lives here: the ceiling's two spellings, a temperature only a
+ * model that takes ours is sent, a reasoning effort only one that takes it is, `stream_options`
+ * only where the server has heard of it, relaxed schemas only where it could not build a grammar,
+ * and `extraBody` last, less whatever the model refused by name. The ceiling is tested
+ * `=== false` — `modelCapabilitiesFor` starts a model at `legacyTokenLimit: true` and an absent
+ * one has to read the same — which is the test one of the three copies had inverted.
+ *
+ * @param config What to ask for. `maxTokens` of zero or less sends no ceiling; `reasoningEffort`
+ * absent or `"off"` sends no effort.
+ * @param supports What the endpoint has refused, as `negotiate` hands it to `send`.
+ * @param refused What the model has refused, as `negotiate` hands it over. Absent is a model
+ * that has refused nothing.
+ * @param messages The request's messages, system prompt included, sent as they are.
+ * @param tools The tool definitions. Sanitised here — a lookup for a definition seen before —
+ * and relaxed where the endpoint needs it. Empty sends no `tools` field at all.
+ */
+export function buildBody(config, supports, refused, messages, tools = []) {
+    const declared = supports.strictSchemas ? sanitizeTools(tools) : relaxTools(sanitizeTools(tools));
+    const effort = config.reasoningEffort;
+    const extra = Object.entries(config.extraBody ?? {}).filter(([field]) => !RESERVED.has(field) && !refused?.refusedFields.has(field));
+    return {
+        ...(config.maxTokens > 0
+            ? refused?.legacyTokenLimit === false
+                ? { max_completion_tokens: config.maxTokens }
+                : { max_tokens: config.maxTokens }
+            : {}),
+        ...(refused?.chosenTemperature === false ? {} : { temperature: config.temperature }),
+        ...(effort && effort !== "off" && refused?.reasoningEffort !== false
+            ? { reasoning_effort: effort }
+            : {}),
+        ...(supports.usageInStream ? { stream_options: { include_usage: true } } : {}),
+        ...Object.fromEntries(extra),
+        model: config.model,
+        messages,
+        stream: true,
+        ...(declared.length ? { tools: declared } : {}),
+    };
+}
+/**
+ * A long tool argument or result cut to what a watcher needs, with the full length said.
+ *
+ * For events, never for the transcript: the model reads the whole of what a tool returned.
+ *
+ * @param text What to show.
+ * @param limit Characters kept, 2000 by default. Text at or under it comes back as it was.
+ */
+export const preview = (text, limit = 2000) => text.length > limit ? `${text.slice(0, limit)}… (${text.length} chars)` : text;
+/** A base URL as two settings rows would agree on it: trimmed, without the trailing slash. */
+const sameUrl = (a, b) => a.trim().replace(/\/+$/, "") === b.trim().replace(/\/+$/, "");
+/**
+ * The key to send, where an endpoint may inherit one from the settings it overrides.
+ *
+ * A credential issued for one endpoint has no business being posted to another. A profile that
+ * names its own `baseUrl` and no key of its own is sent `NO_KEY` — not the operator's key, and
+ * not `$OPENAI_API_KEY` — because "I pointed an agent at a friend's server and it sent my OpenAI
+ * key" is not a mistake worth being able to make, and a local server wants no key anyway. One on
+ * the same endpoint inherits the key as it inherits everything else, and the environment is the
+ * last word on the endpoint that was configured rather than overridden.
+ *
+ * @param own The endpoint as the agent or profile states it. Its own key always wins. An empty or
+ * absent `baseUrl` is one that inherits the endpoint too.
+ * @param inherited The settings it overrides. Absent treats `own` as the configured endpoint, so
+ * only its key and the environment's are in play.
+ * @param env Where `OPENAI_API_KEY` is read from, `process.env` by default.
+ */
+export function resolveApiKey(own, inherited, env = process.env) {
+    if (own.apiKey)
+        return own.apiKey;
+    const baseUrl = own.baseUrl?.trim();
+    if (inherited && baseUrl && !sameUrl(baseUrl, inherited.baseUrl))
+        return NO_KEY;
+    return inherited?.apiKey || env.OPENAI_API_KEY || NO_KEY;
+}
+/**
+ * The tools a request is likely to need, picked by a small model before the run starts, or none.
+ *
+ * On-demand loading otherwise spends a round trip on reading the catalogue and calling
+ * `load_tools`; a small model reading the same catalogue usually names the right tools, and the
+ * task model opens with them in hand. A wrong guess costs a few hundred tokens for one run, and
+ * a failed one costs nothing — it is reported through `onNotice` and answered with an empty list,
+ * since a side task is never worth failing the run. A stop still throws.
+ *
+ * @param config The endpoint the preselector is reached through.
+ * @param model The preselector. An empty name picks nothing, which is what `toolSelectModel`
+ * means by empty.
+ * @param catalog The servers to choose from.
+ * @param prompt The request being planned for. Only its head is read; see `preselectInput`.
+ * @param options Cancellation, notices, the reply ceiling (256) and the cap the choice is held to
+ * (`MAX_PER_LOAD`).
+ */
+export async function preselect(config, model, catalog, prompt, { signal, onNotice, maxTokens = 256, maxPerLoad = MAX_PER_LOAD, } = {}) {
+    if (!model || !catalog.some((server) => server.tools.length > 0))
+        return [];
+    const reply = await tryAsk("preselect", () => askJson(config, model, preselectSystem(maxPerLoad), preselectInput(catalog, prompt), PRESELECT_SCHEMA, { name: "preselection", maxTokens, signal, onNotice }), { onNotice });
+    return preselection(reply, catalog, maxPerLoad);
+}
+/** Every numeric field of one usage added into another. */
+const accumulate = (total, turn) => {
+    for (const key of Object.keys(turn))
+        total[key] += turn[key] ?? 0;
+};
+/**
+ * Runs a question to its answer: one `runTurn` per step, the tools it asks for between them,
+ * until a turn asks for none. Throws when `maxToolIterations` is spent, when stopped, and on
+ * whatever `runTurn` throws — `ContextOverflow` among them, however it was found out.
+ *
+ * On-demand loading is handled here, `load_tools` and all: the catalogue rides on the system
+ * prompt and marks what is loaded, a catalogued tool called without being loaded is loaded and
+ * run rather than refused, and a preselection shapes the first step. A turn cut off at
+ * `maxTokens` is said so as a notice, because it otherwise reads exactly like a finished one.
+ *
+ * @param options The config, transcript, tools and dispatcher, plus the optional hooks, events
+ * and cancellation. See `AgentLoopOptions`.
+ */
+export async function runAgentLoop(options) {
+    const { config, system = "", tools = [], catalog = [], dispatch, hooks, signal } = options;
+    const { onEvent, onTurn, beforeStep, parallel = false, recoverToolCalls: recover = true, } = options;
+    const client = getClient(config);
+    const supports = capabilitiesFor(config.baseUrl, config.apiKey);
+    const maxRetries = Math.max(0, Number(config.maxRetries) || 0);
+    const notice = (text) => onEvent?.({ kind: "notice", text });
+    const onDemand = config.toolDiscovery === "ondemand" && catalog.length > 0;
+    const loaded = new Set(onDemand ? (options.loaded ?? []) : []);
+    const preselected = onDemand ? [...(options.preselected ?? [])] : [];
+    for (const name of preselected)
+        loaded.add(name);
+    const used = new Set();
+    const byName = (names) => tools.filter((tool) => tool.type === "function" && names.has(tool.function.name));
+    let messages = [...options.messages];
+    // Held by reference rather than by index, so a `beforeStep` that folds the head into a summary
+    // moves the question without losing it — and one that summarises the question away takes the
+    // hooks' context with it, which is right.
+    const question = messages.findLast((message) => message.role === "user");
+    const gathered = hooks
+        ? await gather(hooks.run, hooks.events ?? ["beforeTurn"], hooks.context, {
+            signal,
+            onNote: hooks.onNote,
+            maxTokens: hooks.maxTokens,
+        })
+        : { context: "", notes: [] };
+    const usage = { prompt: 0, completion: 0, total: 0, cached: 0 };
+    const toolCalls = [];
+    const answered = new Map();
+    for (let step = 0; step < config.maxToolIterations; step++) {
+        // A stop aborts the request in flight, but a tool call already handed off runs to its own
+        // end — so the signal is read between steps as well.
+        signal?.throwIfAborted();
+        messages = (await beforeStep?.(messages, step)) ?? messages;
+        onEvent?.({ kind: "turn", text: `turn ${step + 1}` });
+        const routed = preselected.length > 0 && step === 0;
+        const declared = routed
+            ? byName(new Set(preselected))
+            : onDemand
+                ? [LOAD_TOOLS_DEFINITION, ...byName(loaded)]
+                : tools;
+        const prompt = onDemand && !routed ? `${system}\n\n${catalogPrompt(catalog, loaded)}`.trim() : system;
+        const request = [
+            ...(prompt ? [{ role: "system", content: prompt }] : []),
+            ...withContext(messages, question ? messages.indexOf(question) : -1, gathered.context, hooks?.preface),
+        ];
+        const turn = await runTurn(client, supports, (supported, refused) => buildBody(config, supported, refused, request, declared), {
+            model: config.model,
+            droppable: Object.keys(config.extraBody ?? {}),
+            maxRetries,
+            contextLimit: config.contextLength ?? 0,
+            signal,
+            idleMs: timeoutMs(config),
+            onNotice: notice,
+            onThinking: (text) => onEvent?.({ kind: "thinking", text }),
+            onOutput: (text) => onEvent?.({ kind: "output", text }),
+        });
+        accumulate(usage, turn.usage);
+        if (turn.usage.total > 0 || turn.usage.prompt > 0 || turn.usage.completion > 0) {
+            onEvent?.({
+                kind: "usage",
+                usage: {
+                    promptTokens: usage.prompt,
+                    completionTokens: usage.completion,
+                    totalTokens: usage.total,
+                },
+            });
+        }
+        if (turn.finishReason === "length") {
+            notice(`the model stopped at maxTokens (${config.maxTokens}); this turn is cut short`);
+        }
+        // A call with no name is a fragment the server never finished sending: nothing to run, and
+        // an assistant message naming it would be answered by nothing.
+        let calls = turn.toolCalls.filter((call) => call.function.name);
+        let content = turn.content;
+        if (recover && !calls.length && content && (tools.length > 0 || onDemand)) {
+            const names = tools.flatMap((tool) => (tool.type === "function" ? [tool.function.name] : []));
+            const recovered = recoverToolCalls(content, {
+                names: onDemand ? [...names, LOAD_TOOLS] : names,
+            });
+            if (recovered.toolCalls.length) {
+                calls = recovered.toolCalls;
+                content = recovered.content;
+                notice(`recovered ${calls.length} tool call${calls.length === 1 ? "" : "s"} the model wrote as text; the server's tool-call parser does not match this model's template`);
+            }
+        }
+        const shown = { ...turn, content, toolCalls: calls };
+        onTurn?.(shown, step);
+        // Read before the assistant message is written, so what is replayed on every later request
+        // is the repaired JSON: a server that parses replayed arguments refuses the almost-JSON, and
+        // one that could not be read at all is replayed as no arguments.
+        const parsed = calls.map((call) => {
+            try {
+                const args = parseToolArguments(call.function.arguments, {
+                    finishReason: turn.finishReason,
+                });
+                return { call, args, normal: JSON.stringify(args) };
+            }
+            catch (error) {
+                return { call, error, normal: "{}" };
+            }
+        });
+        messages.push({
+            role: "assistant",
+            content: content || null,
+            ...(parsed.length
+                ? {
+                    tool_calls: parsed.map(({ call, normal }) => ({
+                        ...call,
+                        function: { ...call.function, arguments: normal },
+                    })),
+                }
+                : {}),
+        });
+        if (!calls.length) {
+            if (hooks) {
+                const at = question ? messages.indexOf(question) : -1;
+                // Not awaited: the answer is ready, and remembering it is not something to hold it for.
+                // `notify` never rejects.
+                void notify(hooks.run, "afterTurn", {
+                    ...hooks.context,
+                    reply: turn.content,
+                    ...(at >= 0
+                        ? {
+                            turn: {
+                                index: turnIndex(messages, at),
+                                messages: turnMessages(hooks.context.session.id, messages, at),
+                            },
+                        }
+                        : {}),
+                }, hooks.onNote);
+            }
+            return {
+                turn: shown,
+                messages,
+                usage,
+                toolCalls,
+                loaded: [...loaded],
+                used: [...used],
+                notes: gathered.notes,
+            };
+        }
+        const run = async ({ call, args, error: unreadable, normal }) => {
+            const { name, arguments: raw } = call.function;
+            onEvent?.({ kind: "tool-call", name, text: preview(raw) });
+            let content;
+            let ok = true;
+            try {
+                if (!args)
+                    throw unreadable;
+                if (onDemand && name === LOAD_TOOLS) {
+                    const resolved = expandNames(requestedNames(args), catalog);
+                    for (const hit of resolved.matched)
+                        loaded.add(hit);
+                    content = loadResult(resolved, catalog);
+                    ok = resolved.matched.length > 0;
+                }
+                else {
+                    // A model that skips `load_tools` and calls a catalogued tool by name is right about
+                    // what it wants; load it and run it rather than refusing.
+                    if (onDemand && inCatalog(catalog, name))
+                        loaded.add(name);
+                    used.add(name);
+                    const request = { id: call.id, name, args, raw };
+                    content = parallel
+                        ? await once(answered, `${name}${normal}`, () => dispatch(request, signal))
+                        : await dispatch(request, signal);
+                }
+            }
+            catch (error) {
+                if (signal?.aborted)
+                    throw error;
+                content = errorMessage(error);
+                ok = false;
+            }
+            onEvent?.({ kind: "tool-result", name, ok, text: preview(content) });
+            return { id: call.id, name, ok, content };
+        };
+        const outcomes = [];
+        if (parallel) {
+            signal?.throwIfAborted();
+            outcomes.push(...(await Promise.all(parsed.map(run))));
+        }
+        else {
+            for (const call of parsed) {
+                signal?.throwIfAborted();
+                outcomes.push(await run(call));
+            }
+        }
+        for (const { id, name, ok, content } of outcomes) {
+            toolCalls.push({ name, ok });
+            messages.push({ role: "tool", tool_call_id: id, content });
+        }
+    }
+    throw new Error(`Stopped after ${config.maxToolIterations} tool iterations.`);
+}
+/**
+ * Makes a call at most once per key, sharing the in-flight promise so two identical calls in one
+ * step make one request between them. A call that rejected is forgotten, so asking again is a
+ * real retry rather than a replayed failure.
+ */
+async function once(answered, key, make) {
+    const previous = answered.get(key);
+    if (previous)
+        return previous;
+    const pending = make();
+    answered.set(key, pending);
+    try {
+        return await pending;
+    }
+    catch (error) {
+        if (answered.get(key) === pending)
+            answered.delete(key);
+        throw error;
+    }
+}

package/dist/capabilities.d.ts

@@ -65,6 +65,23 @@ export interface ModelCapabilities {
      * refuses any other value, including the one a settings row has been showing all along.
      */
     chosenTemperature: boolean;
+    /**
+     * Request fields the model's endpoint refused by name — `min_p` to OpenAI, say — which a body
+     * builder leaves out of what `extraBody` asks for. Only ever grows, which is this set's way of
+     * latching off.
+     *
+     * Only the fields a caller offered as droppable reach it (see `NegotiateOptions.droppable`),
+     * because a name read out of an error string is not otherwise something to stop sending: a
+     * refusal naming `messages` is a broken request, not a field the model can do without.
+     */
+    refusedFields: Set<string>;
+    /**
+     * Takes a `response_format` of type `json_schema`, which `askJson` sends. An older model, or a
+     * proxy in front of one, refuses the field outright; the answer is to ask in words and parse the
+     * reply, which is what every structured answer did before. The model's rather than the
+     * endpoint's because one key reaches models that differ here, the way they differ on effort.
+     */
+    structuredOutput: boolean;
 }
 /**
  * What this endpoint is known not to support. The same object every time, so what `negotiate`
@@ -92,9 +109,16 @@ export declare function capabilitiesFor(baseUrl: string, apiKey?: string): Capab
  * since that is the only name the refusal is about.
  */
 export declare function modelCapabilitiesFor(supports: Capabilities, model: string): ModelCapabilities;
+/** Every endpoint's capabilities by `endpointId`, the live objects, for `exportCapabilities`. */
+export declare const knownCapabilities: () => ReadonlyMap<string, Capabilities>;
+/**
+ * The capabilities of the endpoint with this `endpointId`, created optimistic if unseen — the way
+ * `importCapabilities` reaches an endpoint it has only a digest for.
+ */
+export declare function capabilitiesById(id: string): Capabilities;
 /** Forgets every endpoint's capabilities. For tests, and for a settings change under test. */
 export declare function resetCapabilities(): void;
-/** What `negotiate` takes besides the request. Both optional, both about telling someone. */
+/** What `negotiate` takes besides the request. All optional. */
 export interface NegotiateOptions {
     /**
      * The flag `send` will be given, for a caller that has to read it after `negotiate` returns.
@@ -125,6 +149,16 @@ export interface NegotiateOptions {
      * model per endpoint, or one that only ever meets the endpoint's own refusals, needs no edit.
      */
     model?: string;
+    /**
+     * The request fields a refusal may take away when the endpoint says it has never heard of
+     * them — what `extraBody` added, ordinarily. Such a name is latched into the model's
+     * `refusedFields` and the request is sent again, which `send` is expected to build without it.
+     *
+     * Opt-in by name, because the answer is to stop sending the field, and a name out of an error
+     * string that `send` does not know how to leave out would only be refused again. Needs `model`,
+     * since the latch is the model's.
+     */
+    droppable?: Iterable<string>;
 }
 /**
  * Sends a request, re-sending it each time the answer is this endpoint refusing something the
@@ -160,4 +194,4 @@ export interface NegotiateOptions {
  * @param options `produced` for a caller with its own retry budget, `onNotice` for a watcher,
  * `model` to negotiate the model's refusals alongside the endpoint's.
  */
-export declare function negotiate<T>(supports: Capabilities, send: (supports: Capabilities, produced: Produced, model: ModelCapabilities | undefined) => Promise<T>, { produced, onNotice, model: name }?: NegotiateOptions): Promise<T>;
+export declare function negotiate<T>(supports: Capabilities, send: (supports: Capabilities, produced: Produced, model: ModelCapabilities | undefined) => Promise<T>, { produced, onNotice, model: name, droppable }?: NegotiateOptions): Promise<T>;

package/dist/capabilities.js

@@ -1,16 +1,16 @@
-import { endpointKey } from "./client.js";
+import { endpointId } from "./client.js";
 import { errorMessage } from "./errors.js";
 import { isGrammarError } from "./schema-compat.js";
 /**
  * What each endpoint cannot do, remembered for the life of the process.
  *
- * Keyed by `endpointKey`, because these are facts about the server on the other end and not
- * about this one. A llama.cpp box that cannot compile a grammar and a cloud API that can are
- * both reachable from one settings row over its lifetime — an operator retargets it from Ollama
- * this afternoon to OpenAI this evening — and the first one's refusal must not quietly strip
- * pattern/format from the second one's requests, or silently cost it its token counts, for the
- * rest of the process. Bounded by the number of endpoints ever configured, which is a settings
- * row's worth.
+ * Keyed by `endpointId` — `endpointKey` hashed, so a snapshot holds no key — because these are
+ * facts about the server on the other end and not about this one. A llama.cpp box that cannot
+ * compile a grammar and a cloud API that can are both reachable from one settings row over its
+ * lifetime — an operator retargets it from Ollama this afternoon to OpenAI this evening — and the
+ * first one's refusal must not quietly strip pattern/format from the second one's requests, or
+ * silently cost it its token counts, for the rest of the process. Bounded by the number of
+ * endpoints ever configured, which is a settings row's worth.
  *
  * The API key is part of that identity, the same as it is for the client pool and the model
  * listings. A router — LiteLLM, OpenRouter, a gateway with several boxes behind it — is free to
@@ -32,13 +32,7 @@ const capabilities = new Map();
  * one that passes `undefined` share an entry rather than holding two.
  */
 export function capabilitiesFor(baseUrl, apiKey) {
-    const key = endpointKey({ baseUrl, apiKey });
-    let known = capabilities.get(key);
-    if (!known) {
-        known = { strictSchemas: true, usageInStream: true, models: new Map() };
-        capabilities.set(key, known);
-    }
-    return known;
+    return capabilitiesById(endpointId({ baseUrl, apiKey }));
 }
 /**
  * What this model on this endpoint is known not to support. The same object every time, so what
@@ -56,11 +50,31 @@ export function capabilitiesFor(baseUrl, apiKey) {
 export function modelCapabilitiesFor(supports, model) {
     let known = supports.models.get(model);
     if (!known) {
-        known = { reasoningEffort: true, legacyTokenLimit: true, chosenTemperature: true };
+        known = {
+            reasoningEffort: true,
+            legacyTokenLimit: true,
+            chosenTemperature: true,
+            refusedFields: new Set(),
+            structuredOutput: true,
+        };
         supports.models.set(model, known);
     }
     return known;
 }
+/** Every endpoint's capabilities by `endpointId`, the live objects, for `exportCapabilities`. */
+export const knownCapabilities = () => capabilities;
+/**
+ * The capabilities of the endpoint with this `endpointId`, created optimistic if unseen — the way
+ * `importCapabilities` reaches an endpoint it has only a digest for.
+ */
+export function capabilitiesById(id) {
+    let known = capabilities.get(id);
+    if (!known) {
+        known = { strictSchemas: true, usageInStream: true, models: new Map() };
+        capabilities.set(id, known);
+    }
+    return known;
+}
 /** Forgets every endpoint's capabilities. For tests, and for a settings change under test. */
 export function resetCapabilities() {
     capabilities.clear();
@@ -70,14 +84,23 @@ export function resetCapabilities() {
  * Read positionally and only against another reading of the same two objects: what it answers is
  * whether anything moved while the request was out, and a flag added to either interface later is
  * compared without an edit here. `models` is not one of them — it is the second level, not a
- * flag, and the map is the same object throughout.
+ * flag, and the map is the same object throughout. `refusedFields` is read by its size, since the
+ * set is the same object on both readings and only ever grows.
  */
 const flagsOf = (supports, model) => [
     ...Object.values(supports).filter((value) => typeof value === "boolean"),
-    ...(model ? Object.values(model) : []),
+    ...(model
+        ? Object.values(model).map((value) => (value instanceof Set ? value.size : value))
+        : []),
 ];
 /** `stream_options` is named in the refusal by every server that has not heard of it. */
 const REJECTS_USAGE = /stream_options/i;
+/**
+ * `response_format` or its `json_schema` type refused, rather than the schema in it. A server
+ * that validates the schema and finds it wanting — `Invalid schema for response_format` — is
+ * telling the caller about their schema, and falling back to words for good would hide that.
+ */
+const rejectsResponseFormat = (detail) => /response_format|json_schema/i.test(detail) && !/invalid schema/i.test(detail);
 /**
  * A refusal of the *value* rather than of the field, which names the field either way.
  *
@@ -138,6 +161,26 @@ const NAMES_TEMPERATURE = /(['"`])temperature\1|\btemperature\s+(?:is|does|must|
  * costs one visible error, and a false positive quietly changes what every later request means.
  */
 const refusesChosenTemperature = (detail) => NAMES_TEMPERATURE.test(detail) && /only the default/i.test(detail);
+/**
+ * The fields a refusal names as ones the endpoint has never heard of, in the two wordings OpenAI
+ * has used: `Unrecognized request argument supplied: min_p` (or `arguments`, listing several) and
+ * `Unknown parameter: 'min_p'.` A nested name — `'chat_template_kwargs.enable_thinking'` — is
+ * answered at its top-level field, which is the only level a body builder leaves things out at.
+ */
+function unknownFields(detail) {
+    const listed = detail.match(/unrecognized request arguments? supplied:\s*([^\n]+)/i)?.[1];
+    const quoted = detail.match(/unknown parameter:\s*(['"`])([^'"`]+)\1/i)?.[2];
+    const names = listed ? listed.split(",") : quoted ? [quoted] : [];
+    return names
+        .map((name) => name
+        .trim()
+        .replace(/^['"`]|['"`.]+$/g, "")
+        .split(/[.[]/)[0])
+        .filter(Boolean);
+}
+/** Whether a refusal names a droppable field this model has not already refused. */
+const refusesDroppable = (detail, droppable, refused) => droppable.size > 0 &&
+    unknownFields(detail).some((field) => droppable.has(field) && !refused.refusedFields.has(field));
 /**
  * Sends a request, re-sending it each time the answer is this endpoint refusing something the
  * request can do without. Returns once the endpoint has answered, or throws if the refusal is
@@ -172,7 +215,8 @@ const refusesChosenTemperature = (detail) => NAMES_TEMPERATURE.test(detail) && /
  * @param options `produced` for a caller with its own retry budget, `onNotice` for a watcher,
  * `model` to negotiate the model's refusals alongside the endpoint's.
  */
-export async function negotiate(supports, send, { produced = { any: false }, onNotice, model: name } = {}) {
+export async function negotiate(supports, send, { produced = { any: false }, onNotice, model: name, droppable } = {}) {
+    const optional = new Set(droppable);
     // The name and what it has refused, bound together because the notices below need both. They
     // exist or are absent as one — the second is resolved from the first — but that is a fact
     // about two locals, and narrowing one of those tells TypeScript nothing about the other.
@@ -211,6 +255,16 @@ export async function negotiate(supports, send, { produced = { any: false }, onN
                 named.refused.chosenTemperature = false;
                 onNotice?.(`${named.name} takes only its own temperature; retrying without ours`);
             }
+            else if (named?.refused.structuredOutput && rejectsResponseFormat(detail)) {
+                named.refused.structuredOutput = false;
+                onNotice?.(`${named.name} does not take response_format; asking for JSON in words instead`);
+            }
+            else if (named && refusesDroppable(detail, optional, named.refused)) {
+                const fields = unknownFields(detail).filter((field) => optional.has(field) && !named.refused.refusedFields.has(field));
+                for (const field of fields)
+                    named.refused.refusedFields.add(field);
+                onNotice?.(`${named.name} does not take ${fields.join(", ")}; retrying without ${fields.length > 1 ? "them" : "it"}`);
+            }
             else if (flagsOf(supports, model).every((flag, index) => flag === sent[index])) {
                 throw error;
             }

package/dist/client.d.ts

@@ -54,6 +54,19 @@ export declare const endpointKey: (config: {
     baseUrl: string;
     apiKey?: string;
 }) => string;
+/**
+ * `endpointKey` hashed, for the remembered facts that can leave the process.
+ *
+ * What an endpoint refused is exported by `exportCapabilities` to be written into a settings row
+ * or a file, and a key inside that blob is a credential copied somewhere nobody meant to keep one.
+ * A digest identifies the same endpoint on the next boot without saying what the key was.
+ *
+ * @param config Read for `baseUrl` and `apiKey` alone, as `endpointKey` reads it.
+ */
+export declare const endpointId: (config: {
+    baseUrl: string;
+    apiKey?: string;
+}) => string;
 /**
  * Asks an endpoint what it serves, and remembers the answer.
  *

package/dist/client.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import OpenAI from "openai";
 /**
  * The SDK insists on a non-empty key even where the server will not look at it. This is what it
@@ -161,6 +162,16 @@ const LISTING_MISS_MS = 30_000;
  * it; see `listings`.
  */
 export const endpointKey = (config) => JSON.stringify([config.baseUrl, config.apiKey || NO_KEY]);
+/**
+ * `endpointKey` hashed, for the remembered facts that can leave the process.
+ *
+ * What an endpoint refused is exported by `exportCapabilities` to be written into a settings row
+ * or a file, and a key inside that blob is a credential copied somewhere nobody meant to keep one.
+ * A digest identifies the same endpoint on the next boot without saying what the key was.
+ *
+ * @param config Read for `baseUrl` and `apiKey` alone, as `endpointKey` reads it.
+ */
+export const endpointId = (config) => createHash("sha256").update(endpointKey(config)).digest("hex");
 /**
  * Asks an endpoint what it serves, and remembers the answer.
  *