@cubicecho/agent-core 2.1.2 → 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/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.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",