@cubicecho/agent-core 2.1.2 → 2.2.1

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

@@ -33,8 +33,10 @@ export declare const compact: (tokens: number) => string;
  * built the entire transcript into a string on every call and threw it away having read nothing
  * but its `.length` — against a transcript that grows by a turn each turn, and one the SDK is
  * about to serialise again to send. What the walk misses is JSON's own punctuation and the keys,
- * which `ENVELOPE` puts back approximately; the difference is a rounding error against an
- * estimate that is already characters over four.
+ * which the envelope constants put back — one per key rather than one per message, since the
+ * three keys only some shapes carry are most of what a tool-using transcript is made of. What
+ * is left is a message's escaping, which is not a constant and is small against an estimate
+ * that is already characters over four.
  *
  * @param body The request as it will be sent, tools included.
  */
@@ -49,18 +51,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,10 +28,21 @@ 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;
+// `ENVELOPE` is the two keys every message has. These are the three that only some do, and each
+// is the key with its punctuation and the comma after the value it holds — the value's own
+// length is counted where the value is read. Applying `ENVELOPE` alone to these shapes left the
+// keys out, which cost 4.5 tokens on every tool result: the message a tool-using run has most
+// of, and short in the direction that lets an overflow through the guard meant to catch it.
+/** What `"name":"",` costs around a message's name. */
+const NAME_KEY = 10;
+/** The same for `"tool_call_id":"",` around a tool result's call id. */
+const TOOL_CALL_ID_KEY = 18;
+/** The same for `"tool_calls":[]` around the calls; each call's own comma is in `CALL_ENVELOPE`. */
+const TOOL_CALLS_KEY = 15;
 /** 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. */
+/** How many characters one message is worth: its keys, and its content in whichever shape. */
 function messageChars(message) {
     let chars = message.role.length + ENVELOPE;
     const { content } = message;
@@ -47,15 +58,17 @@ function messageChars(message) {
                 chars += part.refusal.length;
         }
     if ("name" in message && typeof message.name === "string")
-        chars += message.name.length;
+        chars += NAME_KEY + message.name.length;
     if ("tool_call_id" in message && typeof message.tool_call_id === "string")
-        chars += message.tool_call_id.length;
-    if ("tool_calls" in message && Array.isArray(message.tool_calls))
+        chars += TOOL_CALL_ID_KEY + message.tool_call_id.length;
+    if ("tool_calls" in message && Array.isArray(message.tool_calls)) {
+        chars += TOOL_CALLS_KEY;
         for (const call of message.tool_calls) {
             chars += CALL_ENVELOPE + call.id.length;
             if (call.type === "function")
                 chars += call.function.name.length + call.function.arguments.length;
         }
+    }
     return chars;
 }
 /**
@@ -92,8 +105,10 @@ function toolsCost(tools) {
  * built the entire transcript into a string on every call and threw it away having read nothing
  * but its `.length` — against a transcript that grows by a turn each turn, and one the SDK is
  * about to serialise again to send. What the walk misses is JSON's own punctuation and the keys,
- * which `ENVELOPE` puts back approximately; the difference is a rounding error against an
- * estimate that is already characters over four.
+ * which the envelope constants put back — one per key rather than one per message, since the
+ * three keys only some shapes carry are most of what a tool-using transcript is made of. What
+ * is left is a message's escaping, which is not a constant and is small against an estimate
+ * that is already characters over four.
  *
  * @param body The request as it will be sent, tools included.
  */
@@ -138,18 +153,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.d.ts

@@ -12,6 +12,11 @@ export interface SideTaskOptions {
     /**
      * Told what was given up on, the same way `runTurn` and `negotiate` tell a caller.
      *
+     * The one notice `ask` raises itself opens with the model's name, as `negotiate`'s do for the
+     * refusals that are the model's: what it announces is latched on the (endpoint, model) pair,
+     * so on a consumer reaching several models through one base URL the name is the only thing
+     * separating one announcement from the next.
+     *
      * There is no default, and nothing is printed without one. A library that writes to the
      * console decides for its consumer where operator text goes — which a server embedding this
      * cannot then route to its own logger, attach to the run it belongs to, or silence in tests.

package/dist/side-task.js

@@ -125,7 +125,7 @@ export async function ask(config, model, system, user, { maxTokens = 512, temper
         // does not offer as `none`.
         if (!hints || !rejectedTheRequest(error))
             throw error;
-        onNotice?.("server rejected the no-thinking hints; retrying without them");
+        onNotice?.(`${model} rejected the no-thinking hints; retrying without them`);
         noHints.add(key);
         response = await attempt(false);
     }

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.2",
+  "version": "2.2.1",
   "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",