@cubicecho/agent-core 2.14.0 → 2.16.0

package/README.md

@@ -132,28 +132,49 @@ again, with the setting still reading `high` and nothing anywhere saying it had
 So they hang off the endpoint under the name the endpoint knows the model by. Pass `model` and
 the same loop answers both levels; leave it out and nothing changes.
 
-A refusal of the *value* is not one of these, however alike the two read: an effort off a list
-this package does not know, a `max_tokens` larger than the model's ceiling, a temperature out of
-range. Dropping the field answers those too — at the model's own default, latched for the rest of
-the process, with the settings row still reading what was typed and nothing saying it had stopped
-meaning it. They are passed to the caller instead, where whoever typed the number can see it.
+A refusal of the *value* is not one of these, however alike the two read: a `max_tokens` larger
+than the model's ceiling, a temperature out of range. Dropping the field answers those too — at
+the model's own default, latched for the rest of the process, with the settings row still reading
+what was typed and nothing saying it had stopped meaning it. They are passed to the caller
+instead, where whoever typed the number can see it.
+
+The effort is the exception, because there the model has said what it *would* take:
+`Unsupported value: 'reasoning_effort' does not support 'none' with this model. Supported values
+are: 'minimal', 'low', 'medium', and 'high'.` `negotiate` latches the rung that was refused and
+re-sends at the cheapest one above it, which is a request rather than a failure. Where the refusal
+lists nothing it walks `EFFORT_LADDER` — `none`, `minimal`, `low`, `medium`, `high` — a rung per
+refusal. Both latch per `(endpoint, model)` and ride in the snapshot, so a restart does not walk
+the ladder again.
+
+Only ever upward, and only from a value on the ladder. Answering a refused `xhigh` with `high`
+would quietly reason less than whoever typed it asked for; stepping up from `none` only costs
+tokens, and says so in a notice. When the ladder runs out, or the value is not on it, the refusal
+goes to the caller as it did before.
+
+`effortFor(model, asked)` is what a body builder calls to get the value to send — `buildBody` and
+the side tasks both do — and it answers the empty string for a model that takes no effort at all,
+for `"off"` and for an absent setting.
 
 ```ts
-const turn = await negotiate(supports, (supports, produced, model) =>
-  streamTurn(
-    getClient(config),
-    {
-      model: name, messages, stream: true,
-      // Each rebuilt per attempt from what this model has already refused.
-      ...(model?.reasoningEffort ? { reasoning_effort: effort } : {}),
-      ...(model?.legacyTokenLimit === false
-        ? { max_completion_tokens: limit }
-        : { max_tokens: limit }),
-      ...(model?.chosenTemperature ? { temperature } : {}),
-      tools: supports.strictSchemas ? declared : relaxTools(declared),
-    },
-    { produced, signal },
-  ),
+const turn = await negotiate(
+  supports,
+  (supports, produced, model) => {
+    // Each rebuilt per attempt from what this model has already refused.
+    const asked = effortFor(model, effort);
+    return streamTurn(
+      getClient(config),
+      {
+        model: name, messages, stream: true,
+        ...(asked ? { reasoning_effort: asked } : {}),
+        ...(model?.legacyTokenLimit === false
+          ? { max_completion_tokens: limit }
+          : { max_tokens: limit }),
+        ...(model?.chosenTemperature ? { temperature } : {}),
+        tools: supports.strictSchemas ? declared : relaxTools(declared),
+      },
+      { produced, signal },
+    );
+  },
   { model: name },
 );
 ```
@@ -370,10 +391,17 @@ const { turn, messages, usage, loaded } = await runAgentLoop({
 
 Each step is one `runTurn` with the body from `buildBody`, so everything `negotiate` answers is
 answered here too, and a request that is too big throws `ContextOverflow` whichever side found
-out. Between steps the loop runs the calls: sequentially by default, or together with
-`parallel: true`, which also makes an identical call — the same name and arguments, byte for byte
-— once for the run. A call that threw is forgotten rather than cached, so asking again is a real
-retry. What a tool throws is what the model reads, and so are arguments that did not parse.
+out. Between steps the loop runs the calls: sequentially by default, or together with `parallel: true`.
+Either way an identical call — the same name and arguments, byte for byte — is made once and its
+answer handed to the repeat, and two still in flight share the request. A call that threw is
+forgotten rather than cached, so asking again is a real retry. What a tool throws is what the model
+reads, and so are arguments that did not parse.
+
+The scope is the step, not the run: between steps other tools have run, and the file the model read
+may be the file it has since written. `dedupeToolCalls: false` dispatches everything, and a
+predicate is asked per call — which is how `send_email` opts out, since twice is two emails and
+nothing in an OpenAI tool definition says which tools those are. A pool that reads the MCP
+`readOnlyHint` and `idempotentHint` annotations can answer it; this package cannot.
 
 Arguments go through `parseToolArguments`, which is lenient where the model's meaning is plain:
 JSON held in a string is opened, and the almost-JSON local models write — single quotes, Python's
@@ -382,7 +410,7 @@ string. What still is not an object throws a `ToolArgumentsError` whose `kind` i
 the turn stopped at the ceiling, with a message telling the model so, and `malformed` otherwise.
 The repaired JSON is what the transcript keeps, and an unreadable call is replayed as `{}`, because
 a server that parses replayed arguments refuses the originals on every later request. `dispatch`
-is still handed the model's own text as `raw`, and the parallel dedupe compares repaired arguments,
+is still handed the model's own text as `raw`, and the dedupe compares repaired arguments,
 so `{'a': 1}` and `{"a": 1}` are one call.
 
 A server whose tool-call parser was written for another template streams the model's call as

package/dist/agent-loop.d.ts

@@ -18,7 +18,8 @@ import { type ToolOrder } from "./tool-loading.ts";
  * 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.
+ * absent or `"off"` sends no effort, and one the model has refused by value is stepped up to the
+ * cheapest it takes by `effortFor`.
  * @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.
@@ -152,12 +153,26 @@ export interface AgentLoopOptions {
     /** Runs one tool call and returns what the model reads. What it throws, the model reads too. */
     dispatch: (call: ToolCallRequest, signal?: AbortSignal) => Promise<string>;
     /**
-     * Runs a step's calls together rather than one after another, and makes an identical call —
-     * the same name and arguments, word for word — once for the run, handing a repeat the first
-     * answer. A call that threw is not an answer and is made again. Results still go into the
-     * transcript in the order the model asked.
+     * Runs a step's calls together rather than one after another. Results still go into the
+     * transcript in the order the model asked. See `dedupeToolCalls`, which applies either way.
      */
     parallel?: boolean;
+    /**
+     * Answers an identical repeat of a call — the same name and the same arguments, word for word —
+     * within one step from the first one, rather than dispatching it again.
+     *
+     * On by default, and on whether or not the calls run in `parallel`: a model that asks the same
+     * question twice in one reply gets one answer, and two that are still in flight share the
+     * request. A call that threw is not an answer and is made again. The scope is the step and not
+     * the run, because between steps other tools have run and the file the model read may be the
+     * file it has since written.
+     *
+     * `false` dispatches every call. A predicate is asked per call and is how a tool that does
+     * something rather than reads something opts out — `send_email` twice is two emails, and this
+     * package cannot tell which tools those are. A pool that reads the MCP `readOnlyHint` and
+     * `idempotentHint` annotations can answer it; nothing in an OpenAI tool definition can.
+     */
+    dedupeToolCalls?: boolean | ((call: ToolCallRequest) => boolean);
     /** Hooks gathered onto the question before the first request, and told the reply after. */
     hooks?: AgentLoopHooks;
     /**

package/dist/agent-loop.js

@@ -1,5 +1,5 @@
 import { charsPerTokenFor } from "./calibration.js";
-import { capabilitiesFor } from "./capabilities.js";
+import { capabilitiesFor, effortFor, } from "./capabilities.js";
 import { firstTokenMs, getClient, NO_KEY, timeoutMs } from "./client.js";
 import { continueTurn } from "./continuation.js";
 import { errorMessage } from "./errors.js";
@@ -35,7 +35,8 @@ const RESERVED = new Set(["model", "messages", "stream", "tools"]);
  * 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.
+ * absent or `"off"` sends no effort, and one the model has refused by value is stepped up to the
+ * cheapest it takes by `effortFor`.
  * @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.
@@ -51,7 +52,7 @@ export function buildBody(config, supports, refused, messages, tools = [], order
     const declared = supports.strictSchemas
         ? sanitizeTools(sorted)
         : relaxTools(sanitizeTools(sorted));
-    const effort = config.reasoningEffort;
+    const effort = effortFor(refused, config.reasoningEffort);
     const extra = Object.entries(config.extraBody ?? {}).filter(([field]) => !RESERVED.has(field) && !refused?.refusedFields.has(field));
     return {
         ...(config.maxTokens > 0
@@ -60,9 +61,7 @@ export function buildBody(config, supports, refused, messages, tools = [], order
                 : { max_tokens: config.maxTokens }
             : {}),
         ...(refused?.chosenTemperature === false ? {} : { temperature: config.temperature }),
-        ...(effort && effort !== "off" && refused?.reasoningEffort !== false
-            ? { reasoning_effort: effort }
-            : {}),
+        ...(effort ? { reasoning_effort: effort } : {}),
         ...(supports.usageInStream ? { stream_options: { include_usage: true } } : {}),
         ...Object.fromEntries(extra),
         model: config.model,
@@ -202,7 +201,8 @@ function cacheDiagnosis(previous, messages, tools, usage) {
  */
 export async function runAgentLoop(options) {
     const { config, system = "", tools = [], catalog = [], dispatch, hooks, signal } = options;
-    const { onTurn, beforeStep, parallel = false, recoverToolCalls: recover = true, maxContinuations = 0, toolOrder = true, } = options;
+    const { onTurn, beforeStep, parallel = false, recoverToolCalls: recover = true, maxContinuations = 0, toolOrder = true, dedupeToolCalls = true, } = options;
+    const dedupable = typeof dedupeToolCalls === "function" ? dedupeToolCalls : () => dedupeToolCalls;
     const started = Date.now();
     // What the loop emitted, less the token deltas, for `runMetrics` at the end. Stamped here rather
     // than by the bus, which the loop does not know about.
@@ -259,7 +259,6 @@ export async function runAgentLoop(options) {
         : { context: "", notes: [] };
     const usage = { prompt: 0, completion: 0, total: 0, cached: 0 };
     const toolCalls = [];
-    const answered = new Map();
     const loads = { toolsLoaded: 0, redundantLoads: 0, unknownToolNames: 0 };
     let previous;
     for (let step = 0; step < config.maxToolIterations; step++) {
@@ -411,6 +410,9 @@ export async function runAgentLoop(options) {
                 },
             };
         }
+        // Per step, not per run: the answer to a call made two steps ago was true before the tools in
+        // between ran, and the file the model read may be the file it has since written.
+        const answered = new Map();
         const run = async ({ call, args, error: unreadable, normal }) => {
             const { name, arguments: raw } = call.function;
             onEvent({ kind: "tool-call", name, text: preview(raw) });
@@ -436,7 +438,7 @@ export async function runAgentLoop(options) {
                         loaded.add(name);
                     used.add(name);
                     const request = { id: call.id, name, args, raw };
-                    content = parallel
+                    content = dedupable(request)
                         ? await once(answered, `${name}\0${normal}`, () => dispatch(request, signal))
                         : await dispatch(request, signal);
                 }
@@ -470,8 +472,8 @@ export async function runAgentLoop(options) {
 }
 /**
  * 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.
+ * step make one request between them whether they run together or one after the other. 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);

package/dist/capabilities.d.ts

@@ -93,6 +93,22 @@ export interface ModelCapabilities {
      * endpoint's because one key reaches models that differ here, the way they differ on effort.
      */
     structuredOutput: boolean;
+    /**
+     * Efforts this model refused by value rather than by field — a request that named `none` on a
+     * model whose list starts at `minimal`. Only ever grows, which is this set's way of latching.
+     *
+     * Separate from `reasoningEffort` because the two refusals mean opposite things: that one says
+     * the model cannot reason and the field must go, this one says it reasons and was handed an
+     * effort off a list this package does not know. Dropping the field there would run at the
+     * model's own default, which is neither what the caller asked for nor something it can see.
+     */
+    refusedEfforts: Set<string>;
+    /**
+     * The efforts a refusal published as this model's, in ladder order, filtered to the ones
+     * `EFFORT_LADDER` can place. Absent until a refusal lists them, and a model that lists nothing
+     * is walked up the ladder a rung per refusal instead.
+     */
+    supportedEfforts?: string[];
     /**
      * Continues a trailing assistant message rather than answering afresh, which `continueTurn`
      * relies on. llama.cpp renders one as a prefill and picks up mid-word; hosted OpenAI takes the
@@ -170,6 +186,30 @@ export declare function resetCapabilities(endpoint?: {
  * @returns How many endpoints were forgotten.
  */
 export declare function expireCapabilities(maxAgeMs: number, now?: number): number;
+/**
+ * The efforts this package can place, cheapest first. A substitution only ever walks *up* it.
+ *
+ * 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
+ * placed, and an unplaceable value is left alone rather than guessed at: stepping down from a
+ * 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 declare const EFFORT_LADDER: readonly ["none", "minimal", "low", "medium", "high"];
+/**
+ * What to actually put in `reasoning_effort` for a model that has refused the value asked for.
+ *
+ * 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 declare function effortFor(refused: ModelCapabilities | undefined, asked: string | undefined): string;
 /** What `negotiate` takes besides the request. All optional. */
 export interface NegotiateOptions {
     /**

package/dist/capabilities.js

@@ -56,6 +56,7 @@ export function modelCapabilitiesFor(supports, model) {
             chosenTemperature: true,
             refusedFields: new Set(),
             structuredOutput: true,
+            refusedEfforts: new Set(),
             assistantPrefill: true,
         };
         supports.models.set(model, known);
@@ -154,7 +155,8 @@ const rejectsResponseFormat = (detail) => /response_format|json_schema/i.test(de
  * perfectly well; it was handed an effort off a list this package does not know. Dropping the
  * field succeeds, at the model's own default effort, which is neither what the caller asked for
  * nor something it can see — and the drop latches, so every later turn on that model reasons at
- * the default with the setting still reading what the operator typed.
+ * the default with the setting still reading what the operator typed. `stepEffort` answers this
+ * one instead, by naming an effort the model does take.
  */
 const REFUSED_VALUE = /unsupported value|invalid value|supported values/i;
 /**
@@ -165,6 +167,127 @@ const REFUSED_VALUE = /unsupported value|invalid value|supported values/i;
  * latching.
  */
 const rejectsEffort = (detail) => /reasoning_effort/i.test(detail) && !REFUSED_VALUE.test(detail);
+/**
+ * The efforts this package can place, cheapest first. A substitution only ever walks *up* it.
+ *
+ * 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
+ * placed, and an unplaceable value is left alone rather than guessed at: stepping down from a
+ * 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());
+/**
+ * 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`.
+ */
+function listedEfforts(detail) {
+    const listed = detail.match(/supported values(?:\s+\w+)?\s*(?:are|is|include)?\s*:?\s*([^\n.]+)/i)?.[1];
+    if (!listed)
+        return undefined;
+    const values = listed
+        .split(/,|\band\b|\bor\b/)
+        .map((value) => value
+        .trim()
+        .replace(/^['"`]+|['"`]+$/g, "")
+        .toLowerCase())
+        .filter((value) => rankOf(value) >= 0);
+    return values.length ? values : undefined;
+}
+/**
+ * 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`.
+ *
+ * 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];
+    const value = found?.toLowerCase();
+    return value && !supported.includes(value) ? value : undefined;
+}
+/**
+ * The cheapest effort above this one that the model has not refused, or `undefined` when the
+ * ladder is out of rungs.
+ *
+ * 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)
+        return undefined;
+    let best;
+    for (const value of refused.supportedEfforts ?? EFFORT_LADDER) {
+        const at = rankOf(value);
+        if (at <= rank || refused.refusedEfforts.has(value))
+            continue;
+        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.
+ *
+ * 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)
+        return asked;
+    if (!refused.reasoningEffort)
+        return "";
+    const known = refused.supportedEfforts;
+    const listed = known ? known.includes(asked.toLowerCase()) : true;
+    if (listed && !refused.refusedEfforts.has(asked.toLowerCase()))
+        return asked;
+    return nextEffort(refused, asked) ?? asked;
+}
+/**
+ * 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.
+ *
+ * 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)
+        return undefined;
+    if (!/reasoning_effort/i.test(detail) || !REFUSED_VALUE.test(detail))
+        return undefined;
+    const supported = listedEfforts(detail);
+    const value = refusedEffortValue(detail, supported);
+    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)
+        return undefined;
+    const next = nextEffort({
+        ...refused,
+        refusedEfforts: new Set(refused.refusedEfforts).add(value),
+        supportedEfforts: supported ?? refused.supportedEfforts,
+    }, value);
+    return next === undefined ? undefined : { value, next, ...(supported ? { supported } : {}) };
+}
 /**
  * Read only alongside the name it is asking for: `'max_tokens' is not supported with this model.
  * Use 'max_completion_tokens' instead.`
@@ -280,6 +403,7 @@ export async function negotiate(supports, send, { produced = { any: false }, onN
             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");
@@ -292,6 +416,12 @@ export async function negotiate(supports, send, { produced = { any: false }, onN
                 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`);

package/dist/index.d.ts

@@ -11,7 +11,7 @@
  */
 export { type AgentLoopHooks, type AgentLoopOptions, type AgentLoopResult, buildBody, preselect, preview, resolveApiKey, runAgentLoop, type ToolCallOutcome, type ToolCallRequest, } from "./agent-loop.ts";
 export { calibrate, charsPerTokenFor, resetCalibration } from "./calibration.ts";
-export { type Capabilities, capabilitiesFor, expireCapabilities, type ModelCapabilities, modelCapabilitiesFor, type NegotiateOptions, negotiate, resetCapabilities, } from "./capabilities.ts";
+export { type Capabilities, capabilitiesFor, EFFORT_LADDER, effortFor, expireCapabilities, type ModelCapabilities, modelCapabilitiesFor, type NegotiateOptions, negotiate, resetCapabilities, } from "./capabilities.ts";
 export type { CatalogServer } from "./catalog.ts";
 export { type ClientPoolOptions, configureClients, contextLimitFor, endpointId, endpointKey, FIRST_TOKEN_FACTOR, firstTokenMs, getClient, listModels, type ModelInfo, NO_KEY, resetClients, servedWindow, timeoutMs, } from "./client.ts";
 export { applyCompaction, COMPACT_AT, type CompactionOptions, type CompactionPlan, type CompactionRecord, type CompactionRunOptions, compactTranscript, KEEP_RATIO, type PruneOptions, planCompaction, pruneToolResults, requestIndex, runCompaction, SUMMARY_LEAD, SUMMARY_PROMPT, summariser, summaryInput, } from "./compaction.ts";

package/dist/index.js

@@ -11,7 +11,7 @@
  */
 export { buildBody, preselect, preview, resolveApiKey, runAgentLoop, } from "./agent-loop.js";
 export { calibrate, charsPerTokenFor, resetCalibration } from "./calibration.js";
-export { capabilitiesFor, expireCapabilities, modelCapabilitiesFor, negotiate, resetCapabilities, } from "./capabilities.js";
+export { capabilitiesFor, EFFORT_LADDER, effortFor, expireCapabilities, modelCapabilitiesFor, negotiate, resetCapabilities, } from "./capabilities.js";
 export { configureClients, contextLimitFor, endpointId, endpointKey, FIRST_TOKEN_FACTOR, firstTokenMs, getClient, listModels, NO_KEY, resetClients, servedWindow, timeoutMs, } from "./client.js";
 export { applyCompaction, COMPACT_AT, compactTranscript, KEEP_RATIO, planCompaction, pruneToolResults, requestIndex, runCompaction, SUMMARY_LEAD, SUMMARY_PROMPT, summariser, summaryInput, } from "./compaction.js";
 export { continueTurn, isContinuable, } from "./continuation.js";

package/dist/side-task.js

@@ -1,5 +1,5 @@
 import OpenAI from "openai";
-import { capabilitiesFor, modelCapabilitiesFor, negotiate, } from "./capabilities.js";
+import { capabilitiesFor, effortFor, modelCapabilitiesFor, negotiate, } from "./capabilities.js";
 import { endpointId, getClient } from "./client.js";
 import { errorMessage } from "./errors.js";
 import { isTransient } from "./retry.js";
@@ -85,7 +85,11 @@ async function complete(config, model, system, user, { maxTokens = 512, temperat
     // Whether the last request carried an effort, which `negotiate` decides and not this function.
     let sentEffort = false;
     const send = (hints, effort, supports, refused) => {
-        sentEffort = effort && refused?.reasoningEffort !== false;
+        // `none` is what a side task wants and not always what the model offers: OpenAI's reasoning
+        // models refuse it by value and list `minimal` as their floor. `effortFor` answers with the
+        // cheapest rung this one takes, which `negotiate` has been stepping up as it was refused.
+        const asked = effort ? effortFor(refused, "none") : "";
+        sentEffort = asked !== "";
         return getClient(config).chat.completions.create({
             model,
             // The reasoning models want the ceiling spelled the other way, and they are exactly the
@@ -103,7 +107,7 @@ async function complete(config, model, system, user, { maxTokens = 512, temperat
             ...(hints ? NO_THINKING : {}),
             // Not gated on `hints`: a model that refuses `chat_template_kwargs` may still read the
             // effort, and the two latches would otherwise contradict each other.
-            ...(sentEffort ? { reasoning_effort: "none" } : {}),
+            ...(sentEffort ? { reasoning_effort: asked } : {}),
             ...(format && refused ? format(supports, refused) : {}),
         }, { signal });
     };

package/dist/snapshot.d.ts

@@ -22,6 +22,14 @@ export interface ModelSnapshot {
     assistantPrefill: boolean;
     /** Takes the no-thinking hints `ask` sends. */
     thinkingHints: boolean;
+    /**
+     * Efforts refused by value rather than by field, so a restart does not spend a request per rung
+     * walking the ladder again. Absent in a snapshot taken before they were latched, which reads as
+     * none refused.
+     */
+    refusedEfforts?: string[];
+    /** The efforts a refusal published as this model's, in ladder order. Absent is none published. */
+    supportedEfforts?: string[];
 }
 /** What one endpoint refused, and under it what each of its models did. */
 export interface EndpointSnapshot {

package/dist/snapshot.js

@@ -18,6 +18,7 @@ const optimisticModel = () => ({
     structuredOutput: true,
     assistantPrefill: true,
     thinkingHints: true,
+    refusedEfforts: [],
 });
 const refusedAnything = (model) => !model.reasoningEffort ||
     !model.legacyTokenLimit ||
@@ -25,7 +26,8 @@ const refusedAnything = (model) => !model.reasoningEffort ||
     !model.thinkingHints ||
     !model.structuredOutput ||
     !model.assistantPrefill ||
-    model.refusedFields.length > 0;
+    model.refusedFields.length > 0 ||
+    (model.refusedEfforts?.length ?? 0) > 0;
 /**
  * Every refusal this process has latched, as a JSON-safe blob to store and hand back on boot.
  *
@@ -59,6 +61,10 @@ export function exportCapabilities() {
                 refusedFields: [...refused.refusedFields].sort(),
                 structuredOutput: refused.structuredOutput,
                 assistantPrefill: refused.assistantPrefill,
+                refusedEfforts: [...refused.refusedEfforts].sort(),
+                // Only alongside a refusal, since on its own a published list latches nothing: the model
+                // named it while refusing a rung, and that rung is in `refusedEfforts`.
+                ...(refused.supportedEfforts ? { supportedEfforts: [...refused.supportedEfforts] } : {}),
             };
             if (refusedAnything(model))
                 models[name] = model;
@@ -128,6 +134,19 @@ export function importCapabilities(snapshot) {
                 refused.structuredOutput = false;
             if (model.assistantPrefill === false)
                 refused.assistantPrefill = false;
+            if (Array.isArray(model.refusedEfforts)) {
+                for (const effort of model.refusedEfforts) {
+                    if (typeof effort === "string")
+                        refused.refusedEfforts.add(effort);
+                }
+            }
+            // Replaced rather than merged: two lists of what one model takes are two readings of the
+            // same fact, and the stored one is at least as recent as an empty absent.
+            if (Array.isArray(model.supportedEfforts)) {
+                const listed = model.supportedEfforts.filter((value) => typeof value === "string");
+                if (listed.length)
+                    refused.supportedEfforts = listed;
+            }
             if (Array.isArray(model.refusedFields)) {
                 for (const field of model.refusedFields) {
                     if (typeof field === "string")

package/llms.txt

@@ -38,6 +38,8 @@ What an endpoint turned out not to support, and answering it when it says so.
 
 - `Capabilities` (type) — What one endpoint turned out not to support.
 - `capabilitiesFor` — What this endpoint is known not to support.
+- `EFFORT_LADDER` — The efforts this package can place, cheapest first.
+- `effortFor` — What to actually put in `reasoning_effort` for a model that has refused the value asked for.
 - `expireCapabilities` — Forgets every endpoint whose entry is older than this, so the next request finds out again.
 - `ModelCapabilities` (type) — What one model on that endpoint turned out not to support.
 - `modelCapabilitiesFor` — What this model on this endpoint is known not to support.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubicecho/agent-core",
-  "version": "2.14.0",
+  "version": "2.16.0",
   "description": "The endpoint-agnostic half of an OpenAI-compatible agent loop: tool-schema compatibility, on-demand tool loading, one-shot side tasks, run events, and a pooled client.",
   "keywords": [
     "openai",