@cubicecho/agent-core 2.22.0 → 2.24.0

package/dist/side-task.js

@@ -1,10 +1,12 @@
 import OpenAI from "openai";
-import { capabilitiesFor, effortFor, modelCapabilitiesFor, negotiate, } from "./capabilities.js";
+import { capabilitiesFor, ceilingAndTemperature, effortFor, modelCapabilitiesFor, negotiate, } from "./capabilities.js";
 import { endpointId, getClient } from "./client.js";
 import { errorMessage } from "./errors.js";
-import { isTransient } from "./retry.js";
-import { relaxTools, sanitizeTools } from "./schema-compat.js";
+import { refusesRequest } from "./retry.js";
+import { relaxSchema, sanitizeSchema } from "./schema-compat.js";
+import { scoped } from "./scope.js";
 import { stripThinking } from "./thinking.js";
+import { looseJson } from "./tool-calls.js";
 /**
  * One-shot calls that support a run without being one: picking tools, naming a session,
  * summarising a transcript, proposing follow-ups. They share a shape — small prompt, short
@@ -39,32 +41,13 @@ const NO_THINKING = { chat_template_kwargs: { enable_thinking: false } };
  * 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 noHints = scoped(() => new Set());
 /** An (endpoint, model) pair as `noHints` holds it: `[endpointId, model]`, stringified. */
 export const hintKey = (endpoint, model) => JSON.stringify([endpoint, model]);
 /** The pairs that refused the hints, the live set, for `exportCapabilities` and `importCapabilities`. */
-export const refusedHints = () => noHints;
+export const refusedHints = () => noHints();
 /** Test seam, alongside `resetClients` and `resetAll`: forget which models refused the hints. */
-export const resetHints = () => noHints.clear();
-/**
- * Whether a failure is the server complaining about the request, rather than failing to answer.
- *
- * The retry below used to catch everything, so an aborted first call — or a connection that
- * never landed — latched the hints off for the life of the process and every later side task
- * paid for it by burning a whole budget on deliberation. Narrowing that to any 4xx was still
- * too wide: 401, 404 and 429 are all 4xx and none of them is about the fields. A 429 was the
- * worst of them, because the retry then re-sent the whole request immediately — doubling the
- * rate against a server that had just asked for less of it — and `isTransient` accepts exactly
- * that status, so the two halves of this package disagreed about one error.
- *
- * 400 and 422 are what a server says when it read the body and disliked it. Everything else
- * is left to the caller's own retry.
- */
-function rejectedTheRequest(error) {
-    if (!(error instanceof OpenAI.APIError) || isTransient(error))
-        return false;
-    return error.status === 400 || error.status === 422;
-}
+export const resetHints = () => noHints().clear();
 /**
  * Runs a side task and returns the reply text, thinking stripped. Throws like any request.
  *
@@ -97,16 +80,10 @@ async function complete(config, model, system, user, { maxTokens = 512, temperat
         return getClient(config).chat.completions.create({
             model,
             // The reasoning models want the ceiling spelled the other way, and they are exactly the
-            // models a side task most wants to stop deliberating. Zero is no ceiling, as it is on the
-            // main model: a spec's `maxTokens: 0` sent as `max_tokens: 0` asks for an empty reply.
-            ...(maxTokens > 0
-                ? 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 }),
+            // models a side task most wants to stop deliberating. One that will only run at its own
+            // temperature is sent none: a side task wants the same answer twice, and 1.0 from that
+            // model is as close as it gets.
+            ...ceilingAndTemperature(refused, maxTokens, temperature),
             messages: [
                 { role: "system", content: system },
                 { role: "user", content: user },
@@ -130,7 +107,7 @@ async function complete(config, model, system, user, { maxTokens = 512, temperat
     const key = hintKey(endpointId(config), model);
     // A chosen effort replaces the template hint rather than riding beside it: `enable_thinking:
     // false` next to `reasoning_effort: "high"` is a request that contradicts itself.
-    const hints = !level && !noHints.has(key);
+    const hints = !level && !noHints().has(key);
     let response;
     try {
         response = await attempt(hints, true);
@@ -141,7 +118,7 @@ async function complete(config, model, system, user, { maxTokens = 512, temperat
         // does not offer as `none`. Or a 400 about something else entirely, which is why the
         // notice says what was tried rather than what was wrong.
         const effort = sentEffort;
-        if (!(hints || effort) || !rejectedTheRequest(error))
+        if (!(hints || effort) || !refusesRequest(error))
             throw error;
         onNotice?.(level
             ? `${model} rejected a request carrying a reasoning effort; retrying without it`
@@ -153,7 +130,7 @@ async function complete(config, model, system, user, { maxTokens = 512, temperat
         // cannot latch is blamed; if it was the effort after all, the next call is left with only
         // the effort to drop and latches that instead.
         if (hints)
-            noHints.add(key);
+            noHints().add(key);
         else
             modelCapabilitiesFor(supports, model).reasoningEffort = false;
     }
@@ -188,13 +165,8 @@ async function complete(config, model, system, user, { maxTokens = 512, temperat
  * @param options A side task's options, plus the schema's `name` and whether it is `strict`.
  */
 export async function askJson(config, model, system, user, schema, { name = "answer", strict = true, ...options } = {}) {
-    const tool = (parameters) => ({
-        type: "function",
-        function: { name, parameters },
-    });
-    const [sanitized] = sanitizeTools([tool(schema)]);
-    const shapeOf = (definition) => definition?.type === "function" ? (definition.function.parameters ?? {}) : {};
-    const instruction = `${system}\n\nReply with JSON alone, matching this JSON Schema:\n${JSON.stringify(shapeOf(sanitized))}`;
+    const sanitized = sanitizeSchema(schema);
+    const instruction = `${system}\n\nReply with JSON alone, matching this JSON Schema:\n${JSON.stringify(sanitized)}`;
     const reply = await complete(config, model, instruction, user, options, (supports, refused) => refused.structuredOutput
         ? {
             response_format: {
@@ -202,7 +174,7 @@ export async function askJson(config, model, system, user, schema, { name = "ans
                 json_schema: {
                     name,
                     strict,
-                    schema: shapeOf(supports.strictSchemas ? sanitized : relaxTools([sanitized])[0]),
+                    schema: supports.strictSchemas ? sanitized : relaxSchema(sanitized),
                 },
             },
         }
@@ -234,6 +206,11 @@ export async function tryAsk(label, run, { onNotice } = {}) {
  * Models are asked for JSON and often answer with prose around it, or a fenced block. Pull out
  * the first array or object rather than failing the task over a wrapper.
  *
+ * What is pulled out is read the way a tool call's arguments are: as written where that parses,
+ * and otherwise with the almost-JSON a local model writes repaired — single quotes, `True` and
+ * `None`, bare keys, a trailing comma. A small model asked for a list gets these wrong as often in
+ * a reply as in a call, and a side task that fails over one costs the run a second request.
+ *
  * @param text The reply, fences and prose included. Nothing parseable gives `undefined`.
  */
 export function parseJson(text) {
@@ -245,12 +222,7 @@ export function parseJson(text) {
     const end = Math.max(body.lastIndexOf("]"), body.lastIndexOf("}"));
     if (end <= start)
         return undefined;
-    try {
-        return JSON.parse(body.slice(start, end + 1));
-    }
-    catch {
-        return undefined;
-    }
+    return looseJson(body.slice(start, end + 1));
 }
 /**
  * Strips the quoting and list punctuation models decorate short answers with.

package/dist/snapshot.d.ts

@@ -16,8 +16,8 @@ export interface ModelSnapshot {
     refusedFields: string[];
     structuredOutput: boolean;
     /**
-     * Continues a trailing assistant message. Absent in a snapshot taken before it was latched, which
-     * reads as not refused.
+     * Continues a trailing assistant message. Always written; a stored snapshot from before it was
+     * latched lacks it, which `importCapabilities` reads as not refused.
      */
     assistantPrefill: boolean;
     /** Takes the no-thinking hints `ask` sends. */

package/dist/snapshot.js

@@ -1,4 +1,5 @@
-import { capabilitiesById, knownCapabilities, modelCapabilitiesFor } from "./capabilities.js";
+import { capabilitiesById, knownCapabilities, MODEL_FLAGS, modelCapabilitiesFor, OPTIMISTIC_MODEL, } from "./capabilities.js";
+import { isRecord } from "./guards.js";
 import { hintKey, refusedHints } from "./side-task.js";
 /**
  * What endpoints and models refused, carried across a restart.
@@ -11,23 +12,23 @@ import { hintKey, refusedHints } from "./side-task.js";
 /** The version `importCapabilities` accepts. Raised when what is latched changes shape. */
 export const CAPABILITY_SNAPSHOT_VERSION = 1;
 const optimisticModel = () => ({
-    reasoningEffort: true,
-    legacyTokenLimit: true,
-    chosenTemperature: true,
-    refusedFields: [],
-    structuredOutput: true,
-    assistantPrefill: true,
+    ...OPTIMISTIC_MODEL,
     thinkingHints: true,
+    refusedFields: [],
     refusedEfforts: [],
 });
-const refusedAnything = (model) => !model.reasoningEffort ||
-    !model.legacyTokenLimit ||
-    !model.chosenTemperature ||
+const refusedAnything = (model) => MODEL_FLAGS.some((flag) => !model[flag]) ||
     !model.thinkingHints ||
-    !model.structuredOutput ||
-    !model.assistantPrefill ||
     model.refusedFields.length > 0 ||
     (model.refusedEfforts?.length ?? 0) > 0;
+/** Latches every string in a stored list into a live set, skipping what is not a list of them. */
+const latchInto = (held, stored) => {
+    if (!Array.isArray(stored))
+        return;
+    for (const value of stored)
+        if (typeof value === "string")
+            held.add(value);
+};
 /**
  * Every refusal this process has latched, as a JSON-safe blob to store and hand back on boot.
  *
@@ -53,19 +54,15 @@ export function exportCapabilities() {
     for (const [id, supports] of knownCapabilities()) {
         const models = {};
         for (const [name, refused] of supports.models) {
-            const model = {
-                ...optimisticModel(),
-                reasoningEffort: refused.reasoningEffort,
-                legacyTokenLimit: refused.legacyTokenLimit,
-                chosenTemperature: refused.chosenTemperature,
-                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] } : {}),
-            };
+            const model = optimisticModel();
+            for (const flag of MODEL_FLAGS)
+                model[flag] = refused[flag];
+            model.refusedFields = [...refused.refusedFields].sort();
+            model.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`.
+            if (refused.supportedEfforts)
+                model.supportedEfforts = [...refused.supportedEfforts];
             if (refusedAnything(model))
                 models[name] = model;
         }
@@ -85,7 +82,6 @@ export function exportCapabilities() {
     }
     return { version: CAPABILITY_SNAPSHOT_VERSION, savedAt: new Date().toISOString(), endpoints };
 }
-const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /**
  * Latches what a stored snapshot says was refused, on top of whatever this process has learned.
  *
@@ -124,22 +120,10 @@ export function importCapabilities(snapshot) {
             if (!isRecord(model))
                 continue;
             const refused = modelCapabilitiesFor(supports, name);
-            if (model.reasoningEffort === false)
-                refused.reasoningEffort = false;
-            if (model.legacyTokenLimit === false)
-                refused.legacyTokenLimit = false;
-            if (model.chosenTemperature === false)
-                refused.chosenTemperature = false;
-            if (model.structuredOutput === false)
-                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);
-                }
-            }
+            for (const flag of MODEL_FLAGS)
+                if (model[flag] === false)
+                    refused[flag] = false;
+            latchInto(refused.refusedEfforts, model.refusedEfforts);
             // 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)) {
@@ -147,12 +131,7 @@ export function importCapabilities(snapshot) {
                 if (listed.length)
                     refused.supportedEfforts = listed;
             }
-            if (Array.isArray(model.refusedFields)) {
-                for (const field of model.refusedFields) {
-                    if (typeof field === "string")
-                        refused.refusedFields.add(field);
-                }
-            }
+            latchInto(refused.refusedFields, model.refusedFields);
             if (model.thinkingHints === false)
                 refusedHints().add(hintKey(id, name));
         }

package/dist/spec.d.ts

@@ -1,5 +1,5 @@
 import type { AgentConfig, Endpoint } from "./config.ts";
-import type { HookEvent } from "./hooks.ts";
+import { type HookEvent } from "./hook-events.ts";
 /**
  * A JSON document that defines an agent, and the rules for reading one.
  *
@@ -10,11 +10,12 @@ import type { HookEvent } from "./hooks.ts";
  * real ceiling of zero* in the third. This is the shape they can all write and all read, argued
  * out in `docs/agent-spec.md` before any of it was code.
  *
- * Nothing else in `src/` imports this module, and this module imports nothing but types. That is
- * the same seam `config.ts` draws — the loop takes the parts it reads, not a config object — and
- * it is what lets the document travel between hosts without the loop growing an opinion about
- * where an agent comes from. It is also why this is importable in a browser, where `client.ts`
- * and `hooks.ts` are not: a host validating a pasted document in a form needs no `node:crypto`.
+ * Nothing else in `src/` imports this module, and this module imports nothing that needs Node:
+ * types, and leaves with no imports of their own. That is the same seam `config.ts` draws — the
+ * loop takes the parts it reads, not a config object — and it is what lets the document travel
+ * between hosts without the loop growing an opinion about where an agent comes from. It is also
+ * why this is importable in a browser, where `client.ts` and `hooks.ts` are not: a host validating
+ * a pasted document in a form needs no `node:crypto`.
  */
 /** The token a document declares itself with. A loader refuses anything else. */
 export declare const AGENT_SPEC = "cubicecho.agent/1";
@@ -29,12 +30,11 @@ export declare const AGENT_SPEC_VERSION = 1;
  */
 export declare const AGENT_TASKS: readonly ["compaction", "toolSelect", "title", "followups"];
 /**
- * Every event a hook may be bound to, restated so this module stays free of `node:crypto`.
+ * Every event a hook may be bound to: `HOOK_EVENTS`, under the name a document's reader knows.
  *
- * `hooks.ts` owns the list; importing its `HOOK_EVENTS` would pull the whole module, and its
- * `createHash` with it, into a file whose whole point is that a browser can load it. The `HookEvent`
- * type is imported and erased, so a removed event fails to compile here, and a test asserts this
- * list and `HOOK_EVENTS` are the same list so an added one cannot drift quietly.
+ * The same array, not a copy. It comes from `hook-events.ts` rather than `hooks.ts` because that
+ * module's `createHash` would otherwise come with it, into a file whose whole point is that a
+ * browser can load it.
  */
 export declare const SPEC_EVENTS: readonly HookEvent[];
 /** One agent, as a document. Every field but `spec` is optional, because a layer says only what it changes. */
@@ -163,7 +163,6 @@ export interface AgentHook {
     /** `false` keeps the hook in the document without running it. */
     enabled?: boolean;
 }
-/** One bundled MCP server, as far as this package reads it. */
 /** A bundled MCP server, validated only as far as a round trip needs and otherwise passed through. */
 export interface SpecServer {
     id?: string;

package/dist/spec.js

@@ -1,3 +1,5 @@
+import { isRecord } from "./guards.js";
+import { HOOK_EVENTS, INJECT_EVENTS } from "./hook-events.js";
 /**
  * A JSON document that defines an agent, and the rules for reading one.
  *
@@ -8,11 +10,12 @@
  * real ceiling of zero* in the third. This is the shape they can all write and all read, argued
  * out in `docs/agent-spec.md` before any of it was code.
  *
- * Nothing else in `src/` imports this module, and this module imports nothing but types. That is
- * the same seam `config.ts` draws — the loop takes the parts it reads, not a config object — and
- * it is what lets the document travel between hosts without the loop growing an opinion about
- * where an agent comes from. It is also why this is importable in a browser, where `client.ts`
- * and `hooks.ts` are not: a host validating a pasted document in a form needs no `node:crypto`.
+ * Nothing else in `src/` imports this module, and this module imports nothing that needs Node:
+ * types, and leaves with no imports of their own. That is the same seam `config.ts` draws — the
+ * loop takes the parts it reads, not a config object — and it is what lets the document travel
+ * between hosts without the loop growing an opinion about where an agent comes from. It is also
+ * why this is importable in a browser, where `client.ts` and `hooks.ts` are not: a host validating
+ * a pasted document in a form needs no `node:crypto`.
  */
 /** The token a document declares itself with. A loader refuses anything else. */
 export const AGENT_SPEC = "cubicecho.agent/1";
@@ -27,23 +30,13 @@ export const AGENT_SPEC_VERSION = 1;
  */
 export const AGENT_TASKS = ["compaction", "toolSelect", "title", "followups"];
 /**
- * Every event a hook may be bound to, restated so this module stays free of `node:crypto`.
+ * Every event a hook may be bound to: `HOOK_EVENTS`, under the name a document's reader knows.
  *
- * `hooks.ts` owns the list; importing its `HOOK_EVENTS` would pull the whole module, and its
- * `createHash` with it, into a file whose whole point is that a browser can load it. The `HookEvent`
- * type is imported and erased, so a removed event fails to compile here, and a test asserts this
- * list and `HOOK_EVENTS` are the same list so an added one cannot drift quietly.
+ * The same array, not a copy. It comes from `hook-events.ts` rather than `hooks.ts` because that
+ * module's `createHash` would otherwise come with it, into a file whose whole point is that a
+ * browser can load it.
  */
-export const SPEC_EVENTS = [
-    "sessionStart",
-    "beforeTurn",
-    "afterTurn",
-    "beforeCompact",
-    "sessionEnd",
-    "sessionDelete",
-];
-/** The events whose output can still reach a request, so the only ones `inject` means anything on. */
-const SPEC_INJECT = new Set(["sessionStart", "beforeTurn"]);
+export const SPEC_EVENTS = HOOK_EVENTS;
 /** Body fields the loop owns. `buildBody` would overwrite them anyway; better to say so on import. */
 const RESERVED_BODY = ["model", "messages", "stream", "tools"];
 /**
@@ -62,7 +55,6 @@ export const RESOLVED_DEFAULTS = {
     maxToolIterations: 20,
     maxRetries: 0,
 };
-const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /** Absent and null are the same thing: a nullable column round-trips through JSON as `null`. */
 const absent = (value) => value === undefined || value === null;
 /** A `${VAR}`-shaped string, which is kept as the literal it is rather than expanded. */
@@ -138,6 +130,12 @@ function parseEndpoint(report, path, value) {
         report.drop(`${path}.apiKey`, "is not part of this format — a document carries no credentials");
     return said(endpoint) ? endpoint : undefined;
 }
+/** The three fields a model and a side task both carry, held to the same bounds in each. */
+const parseSampling = (report, path, value) => ({
+    maxTokens: report.number(`${path}.maxTokens`, value.maxTokens, 0),
+    temperature: report.number(`${path}.temperature`, value.temperature, 0, 2),
+    reasoningEffort: report.string(`${path}.reasoningEffort`, value.reasoningEffort),
+});
 function parseModel(report, value) {
     if (absent(value))
         return undefined;
@@ -159,9 +157,7 @@ function parseModel(report, value) {
     }
     return kept({
         model: report.string("model.model", value.model),
-        maxTokens: report.number("model.maxTokens", value.maxTokens, 0),
-        temperature: report.number("model.temperature", value.temperature, 0, 2),
-        reasoningEffort: report.string("model.reasoningEffort", value.reasoningEffort),
+        ...parseSampling(report, "model", value),
         contextLength: report.number("model.contextLength", value.contextLength, 0),
         extraBody,
     });
@@ -262,9 +258,7 @@ function parseTasks(report, value) {
         tasks[key] = kept({
             model: report.string(`${path}.model`, held.model),
             endpoint: parseEndpoint(report, `${path}.endpoint`, held.endpoint),
-            maxTokens: report.number(`${path}.maxTokens`, held.maxTokens, 0),
-            temperature: report.number(`${path}.temperature`, held.temperature, 0, 2),
-            reasoningEffort: report.string(`${path}.reasoningEffort`, held.reasoningEffort),
+            ...parseSampling(report, path, held),
         });
     }
     return tasks;
@@ -294,7 +288,7 @@ function parseHooks(report, value, events) {
         if (!events.includes(on))
             report.note(`${path}.on`, `"${on}" is never fired by this host`);
         let inject = report.boolean(`${path}.inject`, held.inject);
-        if (inject && !SPEC_INJECT.has(on)) {
+        if (inject && !INJECT_EVENTS.has(on)) {
             report.drop(`${path}.inject`, `"${on}" runs after the model has already answered`);
             inject = undefined;
         }
@@ -480,20 +474,7 @@ export function parseSpec(document, options = {}) {
     };
 }
 /** Merges the layers that named a key, last one winning, and leaves it absent if none did. */
-function mergeEndpoints(layers) {
-    const out = {};
-    for (const layer of layers) {
-        if (!layer)
-            continue;
-        if (layer.baseUrl !== undefined)
-            out.baseUrl = layer.baseUrl;
-        if (layer.requestTimeoutSeconds !== undefined)
-            out.requestTimeoutSeconds = layer.requestTimeoutSeconds;
-        if (layer.firstTokenSeconds !== undefined)
-            out.firstTokenSeconds = layer.firstTokenSeconds;
-    }
-    return out;
-}
+const mergeLayers = (layers) => Object.assign({}, ...layers.map((layer) => kept(layer ?? {})));
 /** An `Endpoint` as the loop takes one. `apiKey` is always empty; see `resolveAgentSpec`. */
 const asEndpoint = (spec) => ({
     baseUrl: spec.baseUrl ?? "",
@@ -524,7 +505,7 @@ const asEndpoint = (spec) => ({
  * @param layers The documents, weakest first: settings, then the agent, then a task, then a step.
  */
 export function resolveAgentSpec(layers) {
-    const endpoint = mergeEndpoints(layers.map((layer) => layer.endpoint));
+    const endpoint = mergeLayers(layers.map((layer) => layer.endpoint));
     const model = {};
     const extraBody = {};
     for (const layer of layers) {
@@ -541,31 +522,20 @@ export function resolveAgentSpec(layers) {
     for (const layer of layers)
         for (const part of layer.prompt ?? [])
             parts.set(part.id, { ...(parts.get(part.id) ?? { id: part.id }), ...part });
-    const tools = {};
-    for (const layer of layers) {
-        if (layer.tools?.discovery !== undefined)
-            tools.discovery = layer.tools.discovery;
-        if (layer.tools?.maxIterations !== undefined)
-            tools.maxIterations = layer.tools.maxIterations;
-        // Replaced whole rather than unioned: a list, an empty list and no list are three answers,
-        // and a union of the first two is the first, which loses the scoping the operator asked for.
-        if (layer.tools?.servers !== undefined)
-            tools.servers = [...layer.tools.servers];
-    }
-    const retry = {};
-    for (const layer of layers) {
-        if (layer.retry?.maxRetries !== undefined)
-            retry.maxRetries = layer.retry.maxRetries;
-        if (layer.retry?.loadingTimeoutSeconds !== undefined)
-            retry.loadingTimeoutSeconds = layer.retry.loadingTimeoutSeconds;
-    }
+    // `servers` is replaced whole rather than unioned: a list, an empty list and no list are three
+    // answers, and a union of the first two is the first, which loses the scoping the operator
+    // asked for. Copied, so the resolved agent does not share an array with the layer it came from.
+    const tools = mergeLayers(layers.map((layer) => layer.tools));
+    if (tools.servers)
+        tools.servers = [...tools.servers];
+    const retry = mergeLayers(layers.map((layer) => layer.retry));
     const merged = new Map();
     for (const layer of layers)
         for (const [key, task] of Object.entries(layer.tasks ?? {}))
             merged.set(key, {
                 ...(merged.get(key) ?? {}),
                 ...task,
-                endpoint: mergeEndpoints([merged.get(key)?.endpoint, task.endpoint]),
+                endpoint: mergeLayers([merged.get(key)?.endpoint, task.endpoint]),
             });
     const tasks = {};
     for (const [key, task] of merged) {
@@ -575,7 +545,7 @@ export function resolveAgentSpec(layers) {
             continue;
         tasks[key] = kept({
             model: task.model,
-            endpoint: asEndpoint(mergeEndpoints([endpoint, task.endpoint])),
+            endpoint: asEndpoint(mergeLayers([endpoint, task.endpoint])),
             maxTokens: task.maxTokens,
             temperature: task.temperature,
             reasoningEffort: task.reasoningEffort,
@@ -599,9 +569,9 @@ export function resolveAgentSpec(layers) {
     for (const layer of layers)
         for (const key of layer.requires ?? [])
             requires.add(key);
-    const id = [...layers].reverse().find((layer) => layer.id)?.id ?? "";
-    const name = [...layers].reverse().find((layer) => layer.name)?.name;
-    const description = [...layers].reverse().find((layer) => layer.description)?.description;
+    const id = layers.findLast((layer) => layer.id)?.id ?? "";
+    const name = layers.findLast((layer) => layer.name)?.name;
+    const description = layers.findLast((layer) => layer.description)?.description;
     const prompt = [...parts.values()];
     return {
         id,

package/dist/stream.d.ts

@@ -107,6 +107,13 @@ export interface TurnUsage {
      */
     context?: ContextBreakdown;
 }
+/**
+ * A usage with nothing counted yet, a fresh object each call since every caller adds into it.
+ *
+ * Only the four counts every turn has: the optional fields stay absent, which is what says
+ * nothing reported them.
+ */
+export declare const noUsage: () => TurnUsage;
 /** One streamed turn, put back together into the shape a loop and a transcript work with. */
 export interface Turn {
     content: string;

package/dist/stream.js

@@ -1,5 +1,12 @@
 import { EndpointSilent } from "./retry.js";
 import { DEFAULT_FENCES, FenceSplitter } from "./thinking.js";
+/**
+ * A usage with nothing counted yet, a fresh object each call since every caller adds into it.
+ *
+ * Only the four counts every turn has: the optional fields stay absent, which is what says
+ * nothing reported them.
+ */
+export const noUsage = () => ({ prompt: 0, completion: 0, total: 0, cached: 0 });
 /**
  * The fields of `timings` a turn reports, under the names `TurnUsage` gives them. A value that is
  * not a finite number is left out rather than guessed at.
@@ -91,7 +98,7 @@ export async function streamTurn(client, body, { signal, idleMs, firstChunkMs, p
         // In arrival order, sorted by index at the end; a call from a server that sent none keeps
         // its place in the order they arrived.
         const calls = [];
-        const usage = { prompt: 0, completion: 0, total: 0, cached: 0 };
+        const usage = noUsage();
         // The usage block's own cache count wins over llama.cpp's, which is the same number in the
         // servers that send both; kept apart so the order the two arrive in does not decide.
         let cacheReport;

package/dist/thinking.js

@@ -110,11 +110,14 @@ export class FenceSplitter {
         this.#held = "";
         return parts;
     }
+    /** The markers worth looking for: only the close inside a fence, every one outside it. */
+    #candidates() {
+        return this.#inside ? [this.#inside.close] : this.#markers;
+    }
     /** The earliest marker that means something in the current state. */
     #next(text) {
-        const candidates = this.#inside ? [this.#inside.close] : this.#markers;
         let best;
-        for (const marker of candidates) {
+        for (const marker of this.#candidates()) {
             const at = text.indexOf(marker);
             if (at === -1)
                 continue;
@@ -125,9 +128,8 @@ export class FenceSplitter {
     }
     /** How much of the end of `text` could be the beginning of a marker. */
     #partialTail(text) {
-        const candidates = this.#inside ? [this.#inside.close] : this.#markers;
         let keep = 0;
-        for (const marker of candidates)
+        for (const marker of this.#candidates())
             for (let length = Math.min(marker.length - 1, text.length); length > keep; length--)
                 if (text.endsWith(marker.slice(0, length))) {
                     keep = length;

package/dist/tokens.d.ts

@@ -1,3 +1,10 @@
+/**
+ * The characters one token is taken to be, where nothing has measured it.
+ *
+ * The fallback, not the rule: once a turn has come back with a reported prompt count, `runTurn`
+ * divides by what that endpoint's model was measured at instead. See `charsPerTokenFor`.
+ */
+export declare const CHARS_PER_TOKEN = 4;
 /**
  * Rough token count. Characters over four, because there is no tokenizer here and there is not
  * going to be one: a server that will not say how big its window is will not lend us its
@@ -10,8 +17,8 @@
  *
  * Its own module because it is the one number several of these agree on, and the module that
  * owns it should not be one that also does something. It was extracted from `side-task` to
- * break a cycle with `retry`; `side-task` no longer reads it, but `retry` and any consumer
- * sizing its own prompt still do, and a leaf with no imports is the right home for it.
+ * break a cycle with `retry`; neither reads it now, but `hooks` does to cap a context block, as
+ * does any consumer sizing its own prompt, and a leaf with no imports is the right home for it.
  *
  * @param text Prose or serialised JSON — both counted the same way, which is why JSON reads low.
  */

package/dist/tokens.js

@@ -1,3 +1,10 @@
+/**
+ * The characters one token is taken to be, where nothing has measured it.
+ *
+ * The fallback, not the rule: once a turn has come back with a reported prompt count, `runTurn`
+ * divides by what that endpoint's model was measured at instead. See `charsPerTokenFor`.
+ */
+export const CHARS_PER_TOKEN = 4;
 /**
  * Rough token count. Characters over four, because there is no tokenizer here and there is not
  * going to be one: a server that will not say how big its window is will not lend us its
@@ -10,9 +17,9 @@
  *
  * Its own module because it is the one number several of these agree on, and the module that
  * owns it should not be one that also does something. It was extracted from `side-task` to
- * break a cycle with `retry`; `side-task` no longer reads it, but `retry` and any consumer
- * sizing its own prompt still do, and a leaf with no imports is the right home for it.
+ * break a cycle with `retry`; neither reads it now, but `hooks` does to cap a context block, as
+ * does any consumer sizing its own prompt, and a leaf with no imports is the right home for it.
  *
  * @param text Prose or serialised JSON — both counted the same way, which is why JSON reads low.
  */
-export const estimateTokens = (text) => Math.ceil(text.length / 4);
+export const estimateTokens = (text) => Math.ceil(text.length / CHARS_PER_TOKEN);