@cubicecho/agent-core 2.23.0 → 2.25.0

package/dist/capabilities.js

@@ -1,36 +1,40 @@
-import { endpointId } from "./client.js";
-import { errorMessage } from "./errors.js";
-import { isGrammarError } from "./schema-compat.js";
-import { scoped } from "./scope.js";
+import { endpointId } from './client.js';
+import { errorMessage } from './errors.js';
+import { getOrCreate } from './guards.js';
+import { isGrammarError } from './schema-compat.js';
+import { scoped } from './scope.js';
 /**
- * What each endpoint cannot do, remembered for the life of the process.
- *
- * 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
- * send two keys to two different backends, and then what one of them refused is not a fact about
- * the other. Keyed on the URL alone the first caller through the gateway latched for everyone
- * behind it, including the `models` map underneath, which is the level where two keys through
- * one host are most likely to differ at all.
+ * A model's on/off flags as it starts out, every one optimistic.
+ *
+ * @remarks
+ * A record over every boolean on `ModelCapabilities`, so a flag added there does not compile until
+ * it is listed here — and this is the list a snapshot is exported, imported and judged empty by,
+ * where each of those used to name the flags again and one could be missed.
  */
+export const OPTIMISTIC_MODEL = {
+    reasoningEffort: true,
+    legacyTokenLimit: true,
+    chosenTemperature: true,
+    structuredOutput: true,
+    assistantPrefill: true,
+};
+/** The names of those flags, for a caller that reads or latches each in turn. */
+export const MODEL_FLAGS = Object.keys(OPTIMISTIC_MODEL);
 const capabilities = scoped(() => new Map());
 /**
- * What this endpoint is known not to support. The same object every time, so what `negotiate`
- * latches off stays off.
+ * What this endpoint is known not to support.
  *
- * @param baseUrl Where the endpoint is. The two flags on it are per-server; what is per-model
+ * @param baseUrl - Where the endpoint is. The two flags on it are per-server; what is per-model
  * hangs off `models`, which `modelCapabilitiesFor` reads.
- * @param apiKey The rest of the endpoint's identity. Optional, because it changes nothing for
+ * @param [apiKey] - The rest of the endpoint's identity. Optional, because it changes nothing for
  * the ordinary case of one key per base URL and a caller with one need not thread it through;
  * absent reads as `NO_KEY`, exactly as it does in `getClient`, so an endpoint with no key and
  * one that passes `undefined` share an entry rather than holding two.
+ * @returns The endpoint's live entry, made with both flags on and no models the first time it is
+ * asked for.
+ *
+ * @remarks
+ * The same object every time, so what `negotiate` latches off stays off.
  */
 export function capabilitiesFor(baseUrl, apiKey) {
     return capabilitiesById(endpointId({ baseUrl, apiKey }));
@@ -39,57 +43,60 @@ export function capabilitiesFor(baseUrl, apiKey) {
  * What this model on this endpoint is known not to support. The same object every time, so what
  * `negotiate` latches off stays off.
  *
+ * @param supports - The endpoint's own, as `capabilitiesFor` hands it over.
+ * @param model - The name the endpoint knows the model as — whatever goes in the request body,
+ * since that is the only name the refusal is about.
+ * @returns The model's live entry under `supports.models`, made with every flag on and nothing
+ * refused the first time it is asked for.
+ *
+ * @remarks
  * Nested under the endpoint rather than keyed by name alone, because `gpt-4o` at OpenAI and
  * `gpt-4o` behind a proxy need not be the same weights — and a proxy is free to answer to a name
  * it does not really serve. One that refused a reasoning effort must not speak for the other.
  * Bounded by the models actually asked for on that endpoint, which is what a dropdown holds.
- *
- * @param supports The endpoint's own, as `capabilitiesFor` hands it over.
- * @param model The name the endpoint knows the model as — whatever goes in the request body,
- * since that is the only name the refusal is about.
  */
 export function modelCapabilitiesFor(supports, model) {
-    let known = supports.models.get(model);
-    if (!known) {
-        known = {
-            reasoningEffort: true,
-            legacyTokenLimit: true,
-            chosenTemperature: true,
-            refusedFields: new Set(),
-            structuredOutput: true,
-            refusedEfforts: new Set(),
-            assistantPrefill: true,
-        };
-        supports.models.set(model, known);
-    }
-    return known;
+    return getOrCreate(supports.models, model, () => ({
+        ...OPTIMISTIC_MODEL,
+        refusedFields: new Set(),
+        refusedEfforts: new Set(),
+    }));
 }
-/** Every endpoint's capabilities by `endpointId`, the live objects, for `exportCapabilities`. */
+/**
+ * Every endpoint's capabilities by `endpointId`, the live objects, for `exportCapabilities`.
+ *
+ * @returns The map itself rather than a copy, read-only by type alone: what is latched or forgotten
+ * afterwards shows through it.
+ */
 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.
+ *
+ * @param id - The digest `endpointId` gives. Not checked: any string opens an entry under itself.
+ * @returns The live entry, the same object `capabilitiesFor` hands over for that endpoint.
  */
 export function capabilitiesById(id) {
-    let known = capabilities().get(id);
-    if (!known) {
-        known = { strictSchemas: true, usageInStream: true, models: new Map(), since: Date.now() };
-        capabilities().set(id, known);
-    }
-    return known;
+    return getOrCreate(capabilities(), id, () => ({
+        strictSchemas: true,
+        usageInStream: true,
+        models: new Map(),
+        since: Date.now(),
+    }));
 }
 /**
  * Forgets what one endpoint refused, or every endpoint's when told none.
  *
+ * @param [endpoint] - Whose to forget, by the same identity `capabilitiesFor` takes. Absent clears
+ * every endpoint, which is what tests and `resetAll` mean by it.
+ * @returns Whether there was anything to forget.
+ *
+ * @remarks
  * A latch never unlatches on its own, so a server upgraded behind the same URL — a newer
  * llama.cpp that compiles the grammar, a proxy that has learned `stream_options` — keeps being
  * sent the downgraded request for the life of the process. This is the seam for a consumer that
  * *knows* it changed: a settings row saved, a health check that reads a new build string, an
  * operator pressing a button. See `expireCapabilities` for the case where nobody knows.
- *
- * @param endpoint Whose to forget, by the same identity `capabilitiesFor` takes. Absent clears
- * every endpoint, which is what tests and `resetAll` mean by it.
- * @returns Whether there was anything to forget.
  */
 export function resetCapabilities(endpoint) {
     if (!endpoint) {
@@ -102,6 +109,11 @@ export function resetCapabilities(endpoint) {
 /**
  * Forgets every endpoint whose entry is older than this, so the next request finds out again.
  *
+ * @param maxAgeMs - How old an entry may be. Zero or less expires everything.
+ * @param [now] - The clock, for tests.
+ * @returns How many endpoints were forgotten.
+ *
+ * @remarks
  * The other half of the problem `resetCapabilities` solves: a server upgraded behind the same URL
  * with nobody to notice. What an expiry costs is one round trip per endpoint and model — the next
  * request carries the field again, and a server that still refuses it refuses it once and
@@ -111,16 +123,13 @@ export function resetCapabilities(endpoint) {
  *
  * Nothing calls this on a timer. When to sweep is the consumer's, the same way how stale a
  * snapshot is too stale is, and a sweep costs a walk of one settings row's worth of entries.
- *
- * @param maxAgeMs How old an entry may be. Zero or less expires everything.
- * @param now The clock, for tests.
- * @returns How many endpoints were forgotten.
  */
 export function expireCapabilities(maxAgeMs, now = Date.now()) {
     let dropped = 0;
     for (const [id, known] of capabilities()) {
-        if (now - known.since < maxAgeMs)
+        if (now - known.since < maxAgeMs) {
             continue;
+        }
         capabilities().delete(id);
         dropped++;
     }
@@ -128,6 +137,15 @@ export function expireCapabilities(maxAgeMs, now = Date.now()) {
 }
 /**
  * Every latching flag in play on one attempt, endpoint and model together, in a stable order.
+ *
+ * @param supports - The endpoint's. Only its booleans are read, which leaves `models` and `since`
+ * out of the reading.
+ * @param model - The named model's. Absent, for a request that named none, the reading is the
+ * endpoint's alone.
+ * @returns A fresh array: the endpoint's booleans, then every value on the model, a set standing
+ * as its size.
+ *
+ * @remarks
  * 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
@@ -135,22 +153,26 @@ export function expireCapabilities(maxAgeMs, now = Date.now()) {
  * 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).map((value) => (value instanceof Set ? value.size : value))
-        : []),
+    ...Object.values(supports).filter((value) => typeof value === 'boolean'),
+    ...(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.
+ * `response_format` or its `json_schema` type refused, rather than the schema in it.
+ *
+ * @param detail - The server's error text.
+ * @returns `true` where the text names either; `false` where it also says `invalid schema`.
+ *
+ * @remarks
+ * 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.
  *
+ * @remarks
  * `Unsupported value: 'reasoning_effort' does not support 'none' with this model. Supported
  * values are: 'minimal', 'low', 'medium', and 'high'.` A model that answers this reasons
  * perfectly well; it was handed an effort off a list this package does not know. Dropping the
@@ -161,16 +183,26 @@ const rejectsResponseFormat = (detail) => /response_format|json_schema/i.test(de
  */
 const REFUSED_VALUE = /unsupported value|invalid value|supported values/i;
 /**
- * A model that cannot reason refuses the field by name — and only the field. See `REFUSED_VALUE`
- * for the refusal that names it too and means the opposite, which is the caller's to see rather
- * than ours to work around. `does not support` is deliberately not the marker: a proxy that
- * words a real field refusal as `this model does not support reasoning_effort` has to keep
- * latching.
+ * A model that cannot reason refuses the field by name — and only the field.
+ *
+ * @param detail - The server's error text.
+ * @returns `true` where the text names `reasoning_effort` and is not a refusal of its value.
+ *
+ * @remarks
+ * See `REFUSED_VALUE` for the refusal that names it too and means the opposite, which is the
+ * caller's to see rather than ours to work around. `does not support` is deliberately not the
+ * marker: a proxy that words a real field refusal as `this model does not support
+ * reasoning_effort` has to keep latching.
  */
 const rejectsEffort = (detail) => /reasoning_effort/i.test(detail) && !REFUSED_VALUE.test(detail);
+/** The setting that asks for no `reasoning_effort` field at all. Ours, and never sent. */
+export const EFFORT_OFF = 'off';
+/** The lowest effort the wire has a word for, which is what a side task asks for. */
+export const EFFORT_NONE = 'none';
 /**
  * The efforts this package can place, cheapest first. A substitution only ever walks *up* it.
  *
+ * @remarks
  * Not a list of what any model takes — `medium` is refused by a model whose list is
  * `minimal, low, high`, and `xhigh` is real and deliberately absent. It is the order the values
  * OpenAI has shipped stand in, which is all a step needs to know. A value not on it cannot be
@@ -178,21 +210,37 @@ const rejectsEffort = (detail) => /reasoning_effort/i.test(detail) && !REFUSED_V
  * refused `xhigh` to `high` would quietly answer a question with less deliberation than whoever
  * typed it asked for, where stepping up from `none` to `minimal` only costs tokens and says so.
  */
-export const EFFORT_LADDER = ["none", "minimal", "low", "medium", "high"];
-const rankOf = (effort) => EFFORT_LADDER.indexOf(effort.toLowerCase());
+export const EFFORT_LADDER = [EFFORT_NONE, 'minimal', 'low', 'medium', 'high'];
+/** The ladder as plain strings, so a value that is not on it can be looked for. */
+const LADDER = EFFORT_LADDER;
+/**
+ * Where an effort stands on the ladder, whatever case it was written in.
+ *
+ * @param effort - The effort as a config or a refusal spelled it.
+ * @returns Its index in `EFFORT_LADDER`, or -1 for one the ladder cannot place.
+ */
+const rankOf = (effort) => LADDER.indexOf(effort.toLowerCase());
 /**
  * The efforts a refusal lists as this model's: `Supported values are: 'minimal', 'low', 'medium',
- * and 'high'.` Quoted or bare, separated by commas and a trailing `and` or `or`.
+ * and 'high'.`
+ *
+ * @param detail - The server's error text.
+ * @returns The listed efforts the ladder can place, lowercased and in the order the refusal gave
+ * them; `undefined` where it lists none, or none that can be placed.
+ *
+ * @remarks
+ * Quoted or bare, separated by commas and a trailing `and` or `or`.
  */
 function listedEfforts(detail) {
     const listed = detail.match(/supported values(?:\s+\w+)?\s*(?:are|is|include)?\s*:?\s*([^\n.]+)/i)?.[1];
-    if (!listed)
+    if (!listed) {
         return undefined;
+    }
     const values = listed
         .split(/,|\band\b|\bor\b/)
         .map((value) => value
         .trim()
-        .replace(/^['"`]+|['"`]+$/g, "")
+        .replace(/^['"`]+|['"`]+$/g, '')
         .toLowerCase())
         .filter((value) => rankOf(value) >= 0);
     return values.length ? values : undefined;
@@ -201,13 +249,16 @@ function listedEfforts(detail) {
  * Which effort a refusal says was refused, in the two shapes the wording takes: the field quoted
  * then `does not support 'none'`, and `reasoning_effort: none`.
  *
+ * @param detail - The refusal.
+ * @param [supported] - What the same refusal listed, which the value cannot be one of.
+ * @returns The value, lowercased; `undefined` where the refusal names none in either shape, or
+ * names one that `supported` holds.
+ *
+ * @remarks
  * Read rather than remembered, because `negotiate` builds no request and so does not know what
  * went out — and a proxy that rewrites the value before passing it on is refusing the one it sent
  * rather than the one it was given. A refusal that names no value steps nothing: guessing which
  * rung was refused is how a ladder walks past the value that would have worked.
- *
- * @param detail The refusal.
- * @param supported What the same refusal listed, which the value cannot be one of.
  */
 function refusedEffortValue(detail, supported = []) {
     const found = detail.match(/reasoning_effort['"`]?\s*(?:does not support|is not supported with|:)\s*['"`]?([\w-]+)/i)?.[1];
@@ -218,70 +269,122 @@ function refusedEffortValue(detail, supported = []) {
  * The cheapest effort above this one that the model has not refused, or `undefined` when the
  * ladder is out of rungs.
  *
+ * @param refused - What the model has refused and, where a refusal published one, its list. Not
+ * written to.
+ * @param asked - The effort to step up from, in any case. One the ladder cannot place steps
+ * nowhere.
+ * @returns The effort to send instead, lowercased as the list or the ladder holds it; `undefined`
+ * too where `asked` is not on the ladder.
+ *
+ * @remarks
  * Above, never below: see `EFFORT_LADDER`. Where a refusal published a list that is the whole of
  * what is tried, so the step lands in one request; where it published none the ladder is walked a
  * rung at a time, each refusal latching the rung it named.
  */
 function nextEffort(refused, asked) {
     const rank = rankOf(asked);
-    if (rank < 0)
+    if (rank < 0) {
         return undefined;
+    }
     let best;
     for (const value of refused.supportedEfforts ?? EFFORT_LADDER) {
         const at = rankOf(value);
-        if (at <= rank || refused.refusedEfforts.has(value))
+        if (at <= rank || refused.refusedEfforts.has(value)) {
             continue;
-        if (best === undefined || at < rankOf(best))
+        }
+        if (best === undefined || at < rankOf(best)) {
             best = value;
+        }
     }
     return best;
 }
 /**
  * What to actually put in `reasoning_effort` for a model that has refused the value asked for.
  *
+ * @param refused - What the model has refused, as `negotiate` hands it over. Absent is a model that
+ * has refused nothing.
+ * @param asked - What the config asks for. `"off"` and absent mean no effort.
+ * @returns The value for the field, or the empty string for no field. `asked` itself, as written,
+ * where the model has not refused it — and where it has but there is no rung left to step to.
+ *
+ * @remarks
  * The caller's own value, until this model has said that value is not one of its own; then the
  * cheapest it will take that is at least as much deliberation. A model that takes no effort at
  * all, and an absent or `"off"` setting, both answer the empty string, which is the body
  * builders' signal to send no field.
- *
- * @param refused What the model has refused, as `negotiate` hands it over. Absent is a model that
- * has refused nothing.
- * @param asked What the config asks for. `"off"` and absent mean no effort.
  */
 export function effortFor(refused, asked) {
-    if (!asked || asked === "off")
-        return "";
-    if (!refused)
+    if (!asked || asked === EFFORT_OFF) {
+        return '';
+    }
+    if (!refused) {
         return asked;
-    if (!refused.reasoningEffort)
-        return "";
+    }
+    if (!refused.reasoningEffort) {
+        return '';
+    }
     const known = refused.supportedEfforts;
     const listed = known ? known.includes(asked.toLowerCase()) : true;
-    if (listed && !refused.refusedEfforts.has(asked.toLowerCase()))
+    if (listed && !refused.refusedEfforts.has(asked.toLowerCase())) {
         return asked;
+    }
     return nextEffort(refused, asked) ?? asked;
 }
+/**
+ * The reply ceiling and the temperature as this model takes them, to spread into a request body.
+ *
+ * @param refused - What the model has refused, as `negotiate` hands it over. Absent is a model that
+ * has refused nothing.
+ * @param maxTokens - The ceiling. Zero or less sends none and leaves it to the server: a zero sent
+ * as `max_tokens: 0` asks for an empty reply.
+ * @param temperature - What to sample at, where the model takes one that was picked for it.
+ * @returns A fresh object holding the ceiling under one of its two names, or under neither, and
+ * `temperature` unless the model refused ours.
+ *
+ * @remarks
+ * The reasoning models want the ceiling spelled the other way, and one that will only run at the
+ * temperature it was built with is sent none. Both are tested `=== false`, so a caller that named
+ * no model sends what one that has refused nothing is sent; see `ModelCapabilities.legacyTokenLimit`.
+ */
+export const ceilingAndTemperature = (refused, maxTokens, temperature) => {
+    const ceiling = refused?.legacyTokenLimit === false ? { max_completion_tokens: maxTokens } : { max_tokens: maxTokens };
+    return {
+        ...(maxTokens > 0 ? ceiling : {}),
+        ...(refused?.chosenTemperature === false ? {} : { temperature }),
+    };
+};
 /**
  * How to answer a refused effort *value*, or `undefined` when there is nothing new to learn or
  * nowhere left to go — in which case the refusal is the caller's, as it was before this existed.
  *
+ * @param detail - The server's error text.
+ * @param refused - What the model has refused so far. Read and never written to: the next rung is
+ * worked out against a copy.
+ * @returns The value to latch, what would be sent once it is, and the list the refusal published
+ * where it published one.
+ *
+ * @remarks
  * Pure, so `negotiate` can work out whether this refusal is one of its own before deciding to
  * answer it, and latch only in the branch it takes.
  */
 function planEffortStep(detail, refused) {
-    if (!refused.reasoningEffort)
+    if (!refused.reasoningEffort) {
         return undefined;
-    if (!/reasoning_effort/i.test(detail) || !REFUSED_VALUE.test(detail))
+    }
+    if (!/reasoning_effort/i.test(detail) || !REFUSED_VALUE.test(detail)) {
         return undefined;
+    }
     const supported = listedEfforts(detail);
     const value = refusedEffortValue(detail, supported);
-    if (value === undefined)
+    if (value === undefined) {
         return undefined;
+    }
     // Something has to be new, or a server that answers every request by naming an effort nobody
     // sent would have `negotiate` re-send for as long as it kept saying it.
     const fresh = supported?.join() !== refused.supportedEfforts?.join();
-    if (refused.refusedEfforts.has(value) && !fresh)
+    if (refused.refusedEfforts.has(value) && !fresh) {
         return undefined;
+    }
     const next = nextEffort({
         ...refused,
         refusedEfforts: new Set(refused.refusedEfforts).add(value),
@@ -293,6 +396,10 @@ function planEffortStep(detail, refused) {
  * Read only alongside the name it is asking for: `'max_tokens' is not supported with this model.
  * Use 'max_completion_tokens' instead.`
  *
+ * @param detail - The server's error text.
+ * @returns `true` where the text names both spellings; `max_tokens` on its own is not enough.
+ *
+ * @remarks
  * A bare `max_tokens` complaint is also how a server says the *number* was too large —
  * `max_tokens is too large: 200000. This model supports at most 16384.` — and the answer to that
  * is not to send the same number under a different name. It is to let the error out, where
@@ -302,6 +409,7 @@ const wantsCompletionLimit = (detail) => /max_tokens/i.test(detail) && /max_comp
 /**
  * Temperature named as the field being refused, rather than mentioned in passing.
  *
+ * @remarks
  * A bare search of the message is not that question. `Unsupported value: 'top_p' does not
  * support 3 with this model. Adjust temperature instead.` refuses another field and merely says
  * the word, and it disabled ours — the word is ordinary English about a model, so any advice,
@@ -312,6 +420,11 @@ const NAMES_TEMPERATURE = /(['"`])temperature\1|\btemperature\s+(?:is|does|must|
 /**
  * `'temperature' does not support 0.7 with this model. Only the default (1) is supported.`
  *
+ * @param detail - The server's error text.
+ * @returns `true` where the text names temperature as the field refused and says `only the
+ * default`; either without the other is `false`.
+ *
+ * @remarks
  * The qualifier is load-bearing, and `does not support` is not the qualifier: that is how a
  * server words a refusal of the *value* — `Invalid value: 'temperature' does not support 5.
  * Supported values are between 0 and 2.` — which is the caller's mistake to see rather than
@@ -333,28 +446,139 @@ const refusesChosenTemperature = (detail) => NAMES_TEMPERATURE.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.
+ * `Unknown parameter: 'min_p'.`
+ *
+ * @param detail - The server's error text.
+ * @returns The top-level names, in the refusal's order and not deduplicated; empty where it is in
+ * neither wording.
+ *
+ * @remarks
+ * 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] : [];
+    const [, listed] = detail.match(/unrecognized request arguments? supplied:\s*([^\n]+)/i) ?? [];
+    const [, , quoted] = detail.match(/unknown parameter:\s*(['"`])([^'"`]+)\1/i) ?? [];
+    let names = [];
+    if (listed) {
+        names = listed.split(',');
+    }
+    else if (quoted) {
+        names = [quoted];
+    }
     return names
         .map((name) => name
         .trim()
-        .replace(/^['"`]|['"`.]+$/g, "")
+        .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));
+/**
+ * The answer to a refusal that is the endpoint's: a flag still set, and a wording that clears it.
+ *
+ * @param flag - Which of the endpoint's flags the answer latches off.
+ * @param matches - Whether an error text is this refusal. Not asked once the flag is off.
+ * @param notice - What a watcher is told when it latches.
+ * @returns An `Answer` that clears the flag on `supports` and returns the notice, or returns
+ * `undefined` having touched nothing.
+ */
+const endpointAnswer = (flag, matches, notice) => ({ detail, supports }) => {
+    if (!supports[flag] || !matches(detail)) {
+        return undefined;
+    }
+    supports[flag] = false;
+    return notice;
+};
+/**
+ * The same for a refusal that is the model's, which only a request that named one can meet.
+ *
+ * @param flag - Which of the model's flags the answer latches off.
+ * @param matches - Whether an error text is this refusal. Not asked once the flag is off, or where
+ * no model was named.
+ * @param notice - Builds what a watcher is told, from the model's name as the request gave it.
+ * @returns An `Answer` that clears the flag on the named model and returns the notice, or returns
+ * `undefined` having touched nothing.
+ */
+const modelAnswer = (flag, matches, notice) => ({ detail, named }) => {
+    if (!named?.refused[flag] || !matches(detail)) {
+        return undefined;
+    }
+    named.refused[flag] = false;
+    return notice(named.name);
+};
+/**
+ * An effort refused by value: latched, so `effortFor` sends the next rung up.
+ *
+ * @param refusal - The refusal. Its named model is written to: the value joins `refusedEfforts`,
+ * and a list the refusal published replaces `supportedEfforts`.
+ * @returns The notice, naming the effort refused and the one tried next; `undefined`, having
+ * latched nothing, where no model was named or `planEffortStep` has no step to take.
+ */
+const effortStepAnswer = ({ detail, named }) => {
+    const stepped = named && planEffortStep(detail, named.refused);
+    if (!named || !stepped) {
+        return undefined;
+    }
+    named.refused.refusedEfforts.add(stepped.value);
+    if (stepped.supported) {
+        named.refused.supportedEfforts = stepped.supported;
+    }
+    return `${named.name} does not reason at ${stepped.value}; retrying at ${stepped.next}`;
+};
+/**
+ * Fields the endpoint has never heard of, where they are droppable and not refused already.
+ *
+ * @param refusal - The refusal. Each such field it names joins the named model's `refusedFields`.
+ * @returns The notice, listing those fields; `undefined`, having latched nothing, where no model
+ * was named, nothing is droppable, or the refusal names no field that is both droppable and new.
+ */
+const droppedFieldsAnswer = ({ detail, named, droppable }) => {
+    if (!named || droppable.size === 0) {
+        return undefined;
+    }
+    const fields = unknownFields(detail).filter((field) => droppable.has(field) && !named.refused.refusedFields.has(field));
+    if (!fields.length) {
+        return undefined;
+    }
+    for (const field of fields) {
+        named.refused.refusedFields.add(field);
+    }
+    return `${named.name} does not take ${fields.join(', ')}; retrying without ${fields.length > 1 ? 'them' : 'it'}`;
+};
+/**
+ * Every refusal `negotiate` answers, in the order it asks. The first to answer is the only one.
+ *
+ * @remarks
+ * The order is behaviour rather than layout: one error text can satisfy two of these — a message
+ * about `reasoning_effort` is a refused field to one and a refused value to the next — and the
+ * earlier row is the reading that wins.
+ */
+const ANSWERS = [
+    endpointAnswer('strictSchemas', isGrammarError, 'server could not build a grammar; retrying without pattern/format'),
+    endpointAnswer('usageInStream', (detail) => REJECTS_USAGE.test(detail), 'server rejected stream_options; token counts unavailable'),
+    modelAnswer('reasoningEffort', rejectsEffort, (name) => `${name} does not take a reasoning effort; retrying without one`),
+    effortStepAnswer,
+    modelAnswer('legacyTokenLimit', wantsCompletionLimit, (name) => `${name} wants max_completion_tokens; retrying with the limit spelled that way`),
+    modelAnswer('chosenTemperature', refusesChosenTemperature, (name) => `${name} takes only its own temperature; retrying without ours`),
+    modelAnswer('structuredOutput', rejectsResponseFormat, (name) => `${name} does not take response_format; asking for JSON in words instead`),
+    droppedFieldsAnswer,
+];
 /**
  * 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
  * not one of ours.
  *
+ * @typeParam T - What `send` resolves, which is handed back as it came.
+ * @param supports - What this endpoint has already refused. Latched off further as it refuses more.
+ * @param send - Builds and sends the request. Called again per downgrade, never once tokens
+ * have arrived. Its third argument is what the named model has refused, absent when no model
+ * was named.
+ * @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.
+ * @returns What the first `send` to succeed resolved. A rejection is `send`'s own error, rethrown
+ * as it was caught.
+ *
+ * @remarks
  * A loop rather than one retry. A server that has heard of neither `stream_options` nor a
  * grammar keyword complains about them one at a time, and answering only the first leaves the
  * second to fail the request — so the first run against such an endpoint is spent discovering
@@ -376,70 +600,39 @@ const refusesDroppable = (detail, droppable, refused) => droppable.size > 0 &&
  * ever one flag in a turn — the same box `streamTurn` sets and the re-send below reads — and a
  * caller that passed it to only one of the two got a turn that had already streamed tokens sent
  * again, silently, with the watcher seeing every one of them twice.
- *
- * @param supports What this endpoint has already refused. Latched off further as it refuses more.
- * @param send Builds and sends the request. Called again per downgrade, never once tokens
- * have arrived. Its third argument is what the named model has refused, absent when no model
- * was named.
- * @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, 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.
     const named = name === undefined ? undefined : { name, refused: modelCapabilitiesFor(supports, name) };
     const model = named?.refused;
     for (;;) {
         // What this attempt was built with. `capabilitiesFor` and `modelCapabilitiesFor` hand one
         // object per endpoint and per model to everyone on them, so a run starting alongside this
-        // one may latch a flag off while this call is in flight — and the branches below are guarded
-        // on the flag still being set.
+        // one may latch a flag off while this call is in flight — and every answer in `ANSWERS` is
+        // guarded on its flag still being set.
         const sent = flagsOf(supports, model);
         try {
             return await send(supports, produced, model);
         }
         catch (error) {
-            if (produced.any)
+            if (produced.any) {
                 throw error;
-            const detail = errorMessage(error);
-            const stepped = named && planEffortStep(detail, named.refused);
-            if (supports.strictSchemas && isGrammarError(detail)) {
-                supports.strictSchemas = false;
-                onNotice?.("server could not build a grammar; retrying without pattern/format");
-            }
-            else if (supports.usageInStream && REJECTS_USAGE.test(detail)) {
-                supports.usageInStream = false;
-                onNotice?.("server rejected stream_options; token counts unavailable");
-            }
-            else if (named?.refused.reasoningEffort && rejectsEffort(detail)) {
-                named.refused.reasoningEffort = false;
-                onNotice?.(`${named.name} does not take a reasoning effort; retrying without one`);
-            }
-            else if (named && stepped) {
-                named.refused.refusedEfforts.add(stepped.value);
-                if (stepped.supported)
-                    named.refused.supportedEfforts = stepped.supported;
-                onNotice?.(`${named.name} does not reason at ${stepped.value}; retrying at ${stepped.next}`);
-            }
-            else if (named?.refused.legacyTokenLimit && wantsCompletionLimit(detail)) {
-                named.refused.legacyTokenLimit = false;
-                onNotice?.(`${named.name} wants max_completion_tokens; retrying with the limit spelled that way`);
-            }
-            else if (named?.refused.chosenTemperature && refusesChosenTemperature(detail)) {
-                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`);
+            const refusal = {
+                detail: errorMessage(error),
+                supports,
+                named,
+                droppable: optional,
+            };
+            let notice;
+            for (const answer of ANSWERS) {
+                notice = answer(refusal);
+                if (notice !== undefined) {
+                    break;
+                }
             }
-            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"}`);
+            if (notice !== undefined) {
+                onNotice?.(notice);
             }
             else if (flagsOf(supports, model).every((flag, index) => flag === sent[index])) {
                 throw error;