@cubicecho/agent-core 2.1.1 → 2.2.0

package/README.md

@@ -90,7 +90,9 @@ const turn = await negotiate(supports, (supports, produced, model) =>
       model: name, messages, stream: true,
       // Each rebuilt per attempt from what this model has already refused.
       ...(model?.reasoningEffort ? { reasoning_effort: effort } : {}),
-      ...(model?.legacyTokenLimit ? { max_tokens: limit } : { max_completion_tokens: limit }),
+      ...(model?.legacyTokenLimit === false
+        ? { max_completion_tokens: limit }
+        : { max_tokens: limit }),
       ...(model?.chosenTemperature ? { temperature } : {}),
       tools: supports.strictSchemas ? declared : relaxTools(declared),
     },
@@ -100,6 +102,14 @@ const turn = await negotiate(supports, (supports, produced, model) =>
 );
 ```
 
+The ceiling is the one of the three guarded on `=== false` rather than on truthiness, and it is
+the only one that has to be. The other two *omit* a field where the flag is absent, so a caller
+that leaves `model` out sends a smaller request and nothing else; both branches of this one are a
+field, so truthiness picks the newer spelling for a caller who was told nothing would change —
+and the newer spelling is exactly the one an older model or a llama.cpp-shaped endpoint rejects.
+`modelCapabilitiesFor` starts a model at `legacyTokenLimit: true`, and an absent model has to read
+the same way it does.
+
 `runTurn` takes the same option and hands `request` the same second argument. Keying on
 `(endpoint, model)` rather than the model name alone is the part worth keeping: `gpt-4o` at
 OpenAI and `gpt-4o` behind a proxy need not be the same weights, and one that refused a reasoning

package/dist/capabilities.d.ts

@@ -53,6 +53,11 @@ export interface ModelCapabilities {
     /**
      * Spells its ceiling `max_tokens`. The reasoning models want `max_completion_tokens` instead,
      * and they are exactly the models anyone sets an effort on.
+     *
+     * Read it as `=== false` rather than for truthiness. This is the one flag whose two answers are
+     * both a field to send, so a caller that named no model — and was told that changes nothing —
+     * gets `undefined` here and, on a truthiness test, sends `max_completion_tokens` to a server
+     * that never refused anything. The flag starts `true`; absent has to mean the same.
      */
     legacyTokenLimit: boolean;
     /**
@@ -95,7 +100,17 @@ export interface NegotiateOptions {
      * this out and take the flag from `send`'s second argument, which is the same object.
      */
     produced?: Produced;
-    /** Told what was given up on, for a watcher who would otherwise see an unexplained pause. */
+    /**
+     * Told what was given up on, for a watcher who would otherwise see an unexplained pause.
+     *
+     * Each message opens with the thing that refused, so a reader tells the two levels apart
+     * without parsing: `server` for the endpoint's own, and the model's own name — as `model` was
+     * given it — for the three that are the model's. That matters because these latch for the
+     * life of the process and this line is the only announcement that one did: on a consumer
+     * where the model is a per-turn setting, "model does not take a reasoning effort" is the same
+     * line for every model on the endpoint, and the operator who later asks why the setting still
+     * reads `high` has no way to tell which one it was about.
+     */
     onNotice?: (message: string) => void;
     /**
      * Which model this request is for, by the name the endpoint knows it as.

package/dist/capabilities.js

@@ -136,7 +136,11 @@ const refusesChosenTemperature = (detail) => /temperature/i.test(detail) && /onl
  * `model` to negotiate the model's refusals alongside the endpoint's.
  */
 export async function negotiate(supports, send, { produced = { any: false }, onNotice, model: name } = {}) {
-    const model = name === undefined ? undefined : modelCapabilitiesFor(supports, name);
+    // 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
@@ -158,17 +162,17 @@ export async function negotiate(supports, send, { produced = { any: false }, onN
                 supports.usageInStream = false;
                 onNotice?.("server rejected stream_options; token counts unavailable");
             }
-            else if (model?.reasoningEffort && rejectsEffort(detail)) {
-                model.reasoningEffort = false;
-                onNotice?.("model does not take a reasoning effort; retrying without one");
+            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 (model?.legacyTokenLimit && wantsCompletionLimit(detail)) {
-                model.legacyTokenLimit = false;
-                onNotice?.("model wants max_completion_tokens; retrying with the limit spelled that way");
+            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 (model?.chosenTemperature && refusesChosenTemperature(detail)) {
-                model.chosenTemperature = false;
-                onNotice?.("model takes only its own temperature; retrying without ours");
+            else if (named?.refused.chosenTemperature && refusesChosenTemperature(detail)) {
+                named.refused.chosenTemperature = false;
+                onNotice?.(`${named.name} takes only its own temperature; retrying without ours`);
             }
             else if (flagsOf(supports, model).every((flag, index) => flag === sent[index])) {
                 throw error;

package/dist/client.js

@@ -76,10 +76,16 @@ function contextLengthOf(model) {
 /**
  * The last listing from each endpoint, so a run can size its window without a round trip.
  *
- * Keyed the same way the clients are, because two endpoints are two different sets of models
- * and one of them having answered says nothing about the other. It is only ever a cache of
- * something asked for anyway, and a listing that fails leaves whatever was there rather than
- * emptying it.
+ * Keyed by base URL and key, because two endpoints are two different sets of models and one of
+ * them having answered says nothing about the other — and because a key can be the difference
+ * between what a router will show one caller and another.
+ *
+ * The timeout is deliberately not in it, which is where this key parts company with the
+ * clients'. Which models a server offers has nothing to do with how long we are willing to wait
+ * for it, so two settings rows differing only there ask once between them rather than twice.
+ *
+ * It is only ever a cache of something asked for anyway, and a listing that fails leaves
+ * whatever was there rather than emptying it.
  */
 const listings = new Map();
 const endpointKey = (config) => JSON.stringify([config.baseUrl, config.apiKey || NO_KEY]);

package/dist/retry.d.ts

@@ -49,18 +49,19 @@ export declare const requestTokens: (body: OpenAI.ChatCompletionCreateParamsStre
  */
 export declare const isOverflow: (detail: string) => boolean;
 /**
- * The smallest window worth believing in, and the floor under both of its uses.
+ * The smallest window worth believing in, and the floor under `runTurn`'s guard.
  *
  * `runTurn`'s `contextLimit` reads it as a sanity check on a number it was handed: below this,
  * the limit is taken for a placeholder — an unset column, a listing that said nothing — rather
- * than a window worth refusing a run over. `contextLimitFor` reads it as the point below which
- * the window is nobody's business and is not asked for.
+ * than a window worth refusing a run over. That is the whole of what reads it; `contextLimitFor`
+ * asks the endpoint whatever the number, and `client.ts` does not import this file.
  *
- * Finding out what a model reads costs a listing against its endpoint, and a run whose whole
- * request is a few thousand tokens fits anything anyone serves — spending a round trip to
- * confirm that, on every run of every card, would be the cost of the guard falling on the
- * runs that never needed it. A model in a window smaller than this exists, and a request that
- * overruns one is left to the endpoint's own complaint, which reads properly now either way.
+ * A model in a window smaller than this exists, and the reason not to refuse a run over one is
+ * that the number far more often came from a caller threading a placeholder through than from
+ * such a model. A request that really does overrun a tiny window is left to the endpoint's own
+ * complaint, which `isOverflow` reads properly either way — so what the floor costs is a round
+ * trip on the runs it declines to guard, and what it saves is refusing the ones it would have
+ * guarded wrongly.
  */
 export declare const SMALLEST_LIKELY_WINDOW = 8192;
 /**

package/dist/retry.js

@@ -28,7 +28,7 @@ export const compact = (tokens) => tokens >= 1000 ? `${(tokens / 1000).toFixed(1
 /** What `{"role":"","content":""},` costs around a message's own text, in characters. */
 const ENVELOPE = 25;
 /** The same for `{"id":"","type":"function","function":{"name":"","arguments":""}},` in a call. */
-const CALL_ENVELOPE = 62;
+const CALL_ENVELOPE = 66;
 /** The divisor behind `estimateTokens`, applied here to a character count rather than a string. */
 const CHARS_PER_TOKEN = 4;
 /** How many characters one message is worth, whichever of the shapes its content is in. */
@@ -138,18 +138,19 @@ export const isOverflow = (detail) => !RATE_LIMITED.test(detail) &&
     OVERFLOW.some((pattern) => pattern.test(detail)) &&
     /token|context/i.test(detail);
 /**
- * The smallest window worth believing in, and the floor under both of its uses.
+ * The smallest window worth believing in, and the floor under `runTurn`'s guard.
  *
  * `runTurn`'s `contextLimit` reads it as a sanity check on a number it was handed: below this,
  * the limit is taken for a placeholder — an unset column, a listing that said nothing — rather
- * than a window worth refusing a run over. `contextLimitFor` reads it as the point below which
- * the window is nobody's business and is not asked for.
- *
- * Finding out what a model reads costs a listing against its endpoint, and a run whose whole
- * request is a few thousand tokens fits anything anyone serves — spending a round trip to
- * confirm that, on every run of every card, would be the cost of the guard falling on the
- * runs that never needed it. A model in a window smaller than this exists, and a request that
- * overruns one is left to the endpoint's own complaint, which reads properly now either way.
+ * than a window worth refusing a run over. That is the whole of what reads it; `contextLimitFor`
+ * asks the endpoint whatever the number, and `client.ts` does not import this file.
+ *
+ * A model in a window smaller than this exists, and the reason not to refuse a run over one is
+ * that the number far more often came from a caller threading a placeholder through than from
+ * such a model. A request that really does overrun a tiny window is left to the endpoint's own
+ * complaint, which `isOverflow` reads properly either way — so what the floor costs is a round
+ * trip on the runs it declines to guard, and what it saves is refusing the ones it would have
+ * guarded wrongly.
  */
 export const SMALLEST_LIKELY_WINDOW = 8192;
 /**

package/dist/side-task.js

@@ -1,4 +1,5 @@
 import OpenAI from "openai";
+import { capabilitiesFor, negotiate } from "./capabilities.js";
 import { getClient } from "./client.js";
 import { errorMessage } from "./errors.js";
 import { isTransient } from "./retry.js";
@@ -13,11 +14,13 @@ import { isTransient } from "./retry.js";
  * the OpenAI-compatible spelling and `chat_template_kwargs` the llama.cpp/vLLM one; servers
  * disagree about which they take, so send both. One that rejects the unknown fields gets a
  * single retry without them, and is not offered them again.
+ *
+ * Only the second half is latched here. `reasoning_effort` is a field `negotiate` already knows
+ * how to be refused, so it is sent under `ModelCapabilities.reasoningEffort` instead — which
+ * both narrows the fallback below to the field it is really about, and shares the answer with
+ * the runs on that model rather than keeping a second opinion about it.
  */
-const NO_THINKING = {
-    reasoning_effort: "none",
-    chat_template_kwargs: { enable_thinking: false },
-};
+const NO_THINKING = { chat_template_kwargs: { enable_thinking: false } };
 /**
  * The models that turned out not to take the hints, by endpoint and model.
  *
@@ -27,9 +30,12 @@ const NO_THINKING = {
  * second from ever being asked.
  *
  * The model belongs in the key for the same reason. One base URL is routinely many models —
- * OpenRouter, LiteLLM, vLLM serving several at once — and whether `reasoning_effort` is
- * understood is a property of the model behind the route, not of the route. Keyed on the host
- * alone, the first model to refuse spoke for every model on it.
+ * OpenRouter, LiteLLM, vLLM serving several at once — and whether `chat_template_kwargs` reaches
+ * a chat template that reads it is a property of the model behind the route, not of the route.
+ * Keyed on the host alone, the first model to refuse spoke for every model on it.
+ *
+ * Only the `chat_template_kwargs` half is here. `reasoning_effort` is `negotiate`'s to latch, on
+ * the same (endpoint, model) pair, where a run on that model can read it too.
  */
 const noHints = new Set();
 const hintKey = (baseUrl, model) => JSON.stringify([baseUrl, model]);
@@ -81,28 +87,47 @@ const stripThinking = (text) => text
  * @param options Reply ceiling, temperature, cancellation, notices.
  */
 export async function ask(config, model, system, user, { maxTokens = 512, temperature = 0.3, signal, onNotice } = {}) {
-    const send = (hints) => getClient(config).chat.completions.create({
+    const send = (hints, refused) => getClient(config).chat.completions.create({
         model,
-        max_tokens: maxTokens,
-        temperature,
+        // The reasoning models want the ceiling spelled the other way, and they are exactly the
+        // models a side task most wants to stop deliberating.
+        ...(refused && !refused.legacyTokenLimit
+            ? { max_completion_tokens: maxTokens }
+            : { max_tokens: maxTokens }),
+        // One that will only run at the temperature it was built with is sent none: a side task
+        // wants the same answer twice, and 1.0 from that model is as close as it gets.
+        ...(refused && !refused.chosenTemperature ? {} : { temperature }),
         messages: [
             { role: "system", content: system },
             { role: "user", content: user },
         ],
         ...(hints ? NO_THINKING : {}),
+        ...(hints && refused?.reasoningEffort !== false ? { reasoning_effort: "none" } : {}),
     }, { signal });
+    // The endpoint's own object, not one of this module's: what a model refuses is the same fact
+    // whether a run or a side task found it out, and the point of latching it is that only one of
+    // them has to pay for it. Nothing here sends tools or `stream_options`, so the two
+    // endpoint-level flags are not in play — the model's three are the whole of what this meets.
+    const supports = capabilitiesFor(config.baseUrl);
+    const attempt = (hints) => negotiate(supports, (_supports, _produced, refused) => send(hints, refused), {
+        model,
+        onNotice,
+    });
     const key = hintKey(config.baseUrl, model);
     const hints = !noHints.has(key);
     let response;
     try {
-        response = await send(hints);
+        response = await attempt(hints);
     }
     catch (error) {
+        // Whatever is left after `negotiate` has answered everything it knows: on this path that is
+        // the hints it does not, which is `chat_template_kwargs` and an effort the model has but
+        // does not offer as `none`.
         if (!hints || !rejectedTheRequest(error))
             throw error;
         onNotice?.("server rejected the no-thinking hints; retrying without them");
         noHints.add(key);
-        response = await send(false);
+        response = await attempt(false);
     }
     const message = response.choices[0]?.message;
     const answer = stripThinking(message?.content ?? "").trim();

package/llms.txt

@@ -81,7 +81,7 @@ Everything about a request failing that is not about what the request said.
 - `isOverflow` — Whether a refusal means the request was too big, rather than merely refused.
 - `isTransient` — Whether a failed request is worth trying again.
 - `requestTokens` — What this request will cost the window, in tokens, near enough.
-- `SMALLEST_LIKELY_WINDOW` — The smallest window worth believing in, and the floor under both of its uses.
+- `SMALLEST_LIKELY_WINDOW` — The smallest window worth believing in, and the floor under `runTurn`'s guard.
 - `sleep` — A delay an abort cuts short, rejecting rather than resolving early.
 
 ### run-turn

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubicecho/agent-core",
-  "version": "2.1.1",
+  "version": "2.2.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",