@cubicecho/agent-core 2.24.0 → 2.25.1

package/dist/side-task.js

@@ -1,12 +1,12 @@
-import OpenAI from "openai";
-import { capabilitiesFor, ceilingAndTemperature, effortFor, modelCapabilitiesFor, negotiate, } from "./capabilities.js";
-import { endpointId, getClient } from "./client.js";
-import { errorMessage } from "./errors.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";
+import { capabilitiesFor, ceilingAndTemperature, EFFORT_NONE, effortFor, modelCapabilitiesFor, negotiate, } from './capabilities.js';
+import { endpointId, getClient, modelKey, resolveApiKey, sameUrl } from './client.js';
+import { errorMessage } from './errors.js';
+import { isAbort, refusesRequest } from './retry.js';
+import { relaxSchema, sanitizeSchema } from './schema-compat.js';
+import { scoped } from './scope.js';
+import { stripThinking } from './thinking.js';
+import { CODE_FENCE, looseJson } from './tool-calls.js';
+import { JSON_SCHEMA_FORMAT, Role } from './wire.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
@@ -19,6 +19,7 @@ import { looseJson } from "./tool-calls.js";
  * 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.
  *
+ * @remarks
  * 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
@@ -28,6 +29,7 @@ const NO_THINKING = { chat_template_kwargs: { enable_thinking: false } };
 /**
  * The models that turned out not to take the hints, by endpoint and model.
  *
+ * @remarks
  * Keyed rather than global for the reason the client cache is keyed, and on the same
  * endpoint it is, by `endpointId`: a refusal is a fact about what is on the other end, not about this
  * process. A llama.cpp box and a cloud API are both reachable from one consumer over its
@@ -39,23 +41,36 @@ const NO_THINKING = { chat_template_kwargs: { enable_thinking: false } };
  * 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.
+ * the same (endpoint, model) pair, where a run on that model can read it too. A pair is held as
+ * `modelKey(endpointId, model)`, which is what `importCapabilities` adds to it by.
  */
 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`. */
+/**
+ * The pairs that refused the hints, the live set, for `exportCapabilities` and
+ * `importCapabilities`.
+ *
+ * @returns The current scope's set itself and not a copy, each pair a
+ * `modelKey(endpointId, model)`. Adding to it stops the hints being sent to that pair from the
+ * next call.
+ */
 export const refusedHints = () => noHints();
-/** Test seam, alongside `resetClients` and `resetAll`: forget which models refused the hints. */
+/**
+ * Test seam, alongside `resetClients` and `resetAll`: forget which models refused the hints.
+ *
+ * @remarks
+ * The current scope's set is emptied in place, so a holder of it sees it empty.
+ */
 export const resetHints = () => noHints().clear();
 /**
  * Runs a side task and returns the reply text, thinking stripped. Throws like any request.
  *
- * @param config Where to send it and how long to wait.
- * @param model The model to ask, usually smaller than the one running the work.
- * @param system The instruction.
- * @param user The input it applies to. Content parts where the model is being shown an image.
- * @param options Reply ceiling, temperature, a reasoning effort, cancellation, notices.
+ * @param config - Where to send it and how long to wait.
+ * @param model - The model to ask, usually smaller than the one running the work.
+ * @param system - The instruction.
+ * @param user - The input it applies to. Content parts where the model is being shown an image.
+ * @param [options] - Reply ceiling, temperature, a reasoning effort, cancellation, notices.
+ * @returns The reply's content, trimmed. Where that is empty once the thinking is stripped, a
+ * `reasoning_content` the server sent beside it, stripped the same way, or an empty string.
  */
 export function ask(config, model, system, user, options = {}) {
     return complete(config, model, system, user, options);
@@ -63,6 +78,19 @@ export function ask(config, model, system, user, options = {}) {
 /**
  * The request `ask` and `askJson` share, with `format` deciding the extra body fields from what
  * the model and the endpoint have refused, rebuilt on every re-send.
+ *
+ * @param config - Where to send it. Its `baseUrl` and key also pick the capabilities the request is
+ * negotiated against, and with `model` the pair a refusal of the hints is latched on.
+ * @param model - The model to ask.
+ * @param system - The instruction, sent as the system message.
+ * @param user - The input, sent as the user message as it was given.
+ * @param options - A side task's options. A `reasoningEffort` that is a level leaves the
+ * no-thinking hints out; absent, `""` or `"off"` sends them unless this pair has refused them.
+ * @param [format] - Builds the extra body fields from the endpoint's capabilities and the model's.
+ * Called on every send, so a re-send is built from what has been latched since. Absent adds none.
+ * @returns The first choice's message as `answerOf` reads it, empty when there was no answer.
+ * Throws what the request throws, except that a 400 or 422 `negotiate` did not answer, on a
+ * request that carried the hints or an effort, is retried once without either.
  */
 async function complete(config, model, system, user, { maxTokens = 512, temperature = 0.3, reasoningEffort, signal, onNotice }, format) {
     // The effort the caller chose, or empty where it chose none: `""` and `"off"` read as absent,
@@ -75,8 +103,8 @@ async function complete(config, model, system, user, { maxTokens = 512, temperat
         // 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.
         // A level the caller chose goes through the same ladder, which only ever steps up from it.
-        const asked = effort ? effortFor(refused, level || "none") : "";
-        sentEffort = asked !== "";
+        const asked = effort ? effortFor(refused, level || EFFORT_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
@@ -85,8 +113,8 @@ async function complete(config, model, system, user, { maxTokens = 512, temperat
             // model is as close as it gets.
             ...ceilingAndTemperature(refused, maxTokens, temperature),
             messages: [
-                { role: "system", content: system },
-                { role: "user", content: user },
+                { role: Role.System, content: system },
+                { role: Role.User, content: user },
             ],
             ...(hints ? NO_THINKING : {}),
             // Not gated on `hints`: a model that refuses `chat_template_kwargs` may still read the
@@ -104,7 +132,7 @@ async function complete(config, model, system, user, { maxTokens = 512, temperat
         model,
         onNotice,
     });
-    const key = hintKey(endpointId(config), model);
+    const key = modelKey(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);
@@ -118,8 +146,9 @@ 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) || !refusesRequest(error))
+        if (!(hints || effort) || !refusesRequest(error)) {
             throw error;
+        }
         onNotice?.(level
             ? `${model} rejected a request carrying a reasoning effort; retrying without it`
             : `${model} rejected a request carrying the no-thinking hints; retrying without them`);
@@ -129,48 +158,66 @@ async function complete(config, model, system, user, { maxTokens = 512, temperat
         // hints again. When both went out the refusal cannot say which, so the one `negotiate`
         // 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)
+        if (hints) {
             noHints().add(key);
-        else
+        }
+        else {
             modelCapabilitiesFor(supports, model).reasoningEffort = false;
+        }
+    }
+    return answerOf(response.choices[0]?.message);
+}
+/**
+ * A reply's answer, thinking stripped, or its scratchpad where the answer is nothing else.
+ *
+ * @param message - The first choice's message. Absent, as when the reply held no choices, reads as
+ * an empty one.
+ * @returns The content, trimmed, with its thinking fences stripped. Where that leaves nothing, a
+ * string `reasoning_content` read the same way, and an empty string where there is none.
+ *
+ * @remarks
+ * Reasoning models that ignore the hints still fence their scratchpad. A side task answers under
+ * a small ceiling, so the fence often never closes, and a template that opened it in the prompt
+ * leaves only the close; either way the deliberation used to come back as the answer.
+ */
+function answerOf(message) {
+    const answer = stripThinking(message?.content ?? '').trim();
+    if (answer) {
+        return answer;
     }
-    const message = response.choices[0]?.message;
-    // Reasoning models that ignore the hints still fence their scratchpad. A side task answers
-    // under a small ceiling, so the fence often never closes, and a template that opened it in
-    // the prompt leaves only the close; either way the deliberation used to come back as the answer.
-    const answer = stripThinking(message?.content ?? "").trim();
     // Nothing but scratchpad. Some servers put the deliberation in its own field and leave the
     // content genuinely empty, in which case there is no answer to find anywhere else.
-    if (answer)
-        return answer;
     const reasoning = message?.reasoning_content;
-    return typeof reasoning === "string" ? stripThinking(reasoning).trim() : "";
+    return typeof reasoning === 'string' ? stripThinking(reasoning).trim() : '';
 }
 /**
  * A side task whose answer is JSON matching a schema, parsed. Undefined when no JSON came back.
  * Throws like any request.
  *
+ * @param config - Where to send it and how long to wait.
+ * @param model - The model to ask.
+ * @param system - The instruction. The schema is appended to it.
+ * @param user - The input it applies to. Content parts where the model is being shown an image.
+ * @param schema - The JSON Schema of the answer. Its root is held to an object, as a tool's is.
+ * @param [options] - A side task's options, plus the schema's `name` and whether it is `strict`.
+ * @returns What the reply parsed to, unchecked against the schema: `T` is the caller's claim.
+ * `undefined` when `parseJson` found nothing in it.
+ *
+ * @remarks
  * Sends `response_format` with the schema, which a llama.cpp server compiles into a grammar and
  * vLLM, LM Studio, Ollama and OpenAI each hold the reply to, so a small model that wraps JSON in
  * prose cannot. The schema is normalised as a tool's parameters are, and relaxed where the endpoint
  * could not build a grammar, since the same converter reads both. A model that refuses the field
  * latches it off and is asked in words: the schema rides on the system prompt either way, and
  * the reply goes through `parseJson`, which finds the JSON in whatever came back.
- *
- * @param config Where to send it and how long to wait.
- * @param model The model to ask.
- * @param system The instruction. The schema is appended to it.
- * @param user The input it applies to. Content parts where the model is being shown an image.
- * @param schema The JSON Schema of the answer. Its root is held to an object, as a tool's is.
- * @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 } = {}) {
+export async function askJson(config, model, system, user, schema, { name = 'answer', strict = true, ...options } = {}) {
     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: {
-                type: "json_schema",
+                type: JSON_SCHEMA_FORMAT,
                 json_schema: {
                     name,
                     strict,
@@ -182,69 +229,142 @@ export async function askJson(config, model, system, user, schema, { name = "ans
     return parseJson(reply);
 }
 /**
+ * Runs a side task and answers `undefined` where it fails, so the work it supports carries on.
+ *
+ * @param label - Names the task in the notice when it fails.
+ * @param run - The call to attempt. Anything it throws becomes `undefined`, an abort excepted.
+ * @param [options] - `onNotice`, told what was given up on, and the `signal` that `run` is
+ * cancelled by.
+ * @returns What `run` resolved with, or `undefined` when it threw. Whatever it threw once the
+ * signal had aborted is thrown on and raises no notice, as is an error that is itself an abort.
+ *
+ * @remarks
  * A side task is never worth failing the work it supports. Callers that can carry on without
  * an answer use this and get `undefined` instead of an exception.
- *
- * @param label Names the task in the notice when it fails.
- * @param run The call to attempt. Anything it throws becomes `undefined`, an abort excepted.
- * @param options `onNotice`, told what was given up on.
  */
-export async function tryAsk(label, run, { onNotice } = {}) {
+export async function tryAsk(label, run, { onNotice, signal } = {}) {
     try {
         return await run();
     }
     catch (error) {
         // A cancelled run is not a failed side task. Swallowing the abort made the two
-        // indistinguishable and left the cancellation with nowhere to go.
-        if (error instanceof OpenAI.APIUserAbortError)
+        // indistinguishable and left the cancellation with nowhere to go. The signal is asked first:
+        // an abort with a reason of the caller's own rejects with that reason, which no class names.
+        const wasCancelled = signal?.aborted === true || isAbort(error);
+        if (wasCancelled) {
             throw error;
+        }
         onNotice?.(`${label}: ${errorMessage(error)}`);
         return undefined;
     }
 }
 /**
- * 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.
+ * The first array or object in a model's reply, parsed, whatever prose or fence surrounds it.
+ *
+ * @param text - The reply, fences and prose included. Nothing parseable gives `undefined`.
+ * @returns What lies between the first `[` or `{` and the last `]` or `}`, parsed — inside the
+ * first fenced block where there is one. Unchecked: `T` is the caller's claim. `undefined` when
+ * there is no such stretch or it will not parse even repaired.
+ *
+ * @remarks
+ * Models are asked for JSON and often answer with prose around it, or a fenced block, and a
+ * wrapper is not worth failing the task over.
  *
  * 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) {
-    const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+    const [fenced] = text.matchAll(CODE_FENCE);
     const body = (fenced?.[1] ?? text).trim();
     const start = body.search(/[[{]/);
-    if (start < 0)
+    if (start < 0) {
         return undefined;
-    const end = Math.max(body.lastIndexOf("]"), body.lastIndexOf("}"));
-    if (end <= start)
+    }
+    const end = Math.max(body.lastIndexOf(']'), body.lastIndexOf('}'));
+    if (end <= start) {
         return undefined;
+    }
     return looseJson(body.slice(start, end + 1));
 }
 /**
  * Strips the quoting and list punctuation models decorate short answers with.
  *
- * @param line One line of a reply.
+ * @param line - One line of a reply.
+ * @returns The line trimmed, without one leading bullet or number, any quotes or backticks at
+ * either end, or trailing full stops. Empty when nothing else was there.
  */
 export const clean = (line) => line
     .trim()
-    .replace(/^(?:[-*•]|\d+[.)])\s*/, "")
-    .replace(/^["'`]+|["'`.]+$/g, "")
+    .replace(/^(?:[-*•]|\d+[.)])\s*/, '')
+    .replace(/^["'`]+|["'`.]+$/g, '')
     .trim();
 /**
  * A list-shaped reply, one item per line, cleaned of the bullets and quotes models decorate
  * them with. Overlong items are dropped rather than truncated — a suggestion that has to be
  * squinted at is worse than one fewer suggestion.
  *
- * @param text The reply, one item per line.
- * @param max How many items to keep.
- * @param maxChars Longest item kept. Longer ones are dropped, not truncated.
+ * @param text - The reply, one item per line.
+ * @param max - How many items to keep.
+ * @param maxChars - Longest item kept. Longer ones are dropped, not truncated.
+ * @returns The first `max` items that survive, in reply order. Lines that clean to nothing are not
+ * items, and an overlong one does not count towards `max`.
  */
 export const listLines = (text, max, maxChars) => text
-    .split("\n")
+    .split('\n')
     .map(clean)
     .filter((line) => line.length > 0 && line.length <= maxChars)
     .slice(0, max);
+/**
+ * A side task's settings as the call that honours them: its endpoint, its model, and the options
+ * `ask`, `askJson`, `summariser` and `preselect` take last.
+ *
+ * @param task - The task, ordinarily `resolved.tasks.<key>`.
+ * @param [options] - What the host adds — cancellation, notices, `keywords` — and its own defaults
+ * for the settings a task may leave out.
+ * @param [agent] - The endpoint the main turn uses, key included. Absent sends the task's endpoint
+ * as it stands.
+ * @returns The three arguments a side-task entry point takes. `options` is a new object, and
+ * `endpoint` is the task's own object when no `agent` was given, a copy otherwise.
+ *
+ * @remarks
+ * A helper rather than a second signature on each of the four, so a setting added to a task later
+ * arrives through `options` without a host's call changing. What the task states wins over the
+ * same field in `options`: the host's code is written once and the task is what an operator
+ * configured over it, so a host passes its own ceiling as the value for a task that names none.
+ * A setting the task leaves out and `options` does too is absent from the result, which is what
+ * leaves it to the entry point's own default — 0.3, not the agent's temperature.
+ *
+ * A resolved spec carries no key, so a task on the agent's own endpoint would otherwise go out
+ * unkeyed, and be remembered under a second capability entry beside the agent's. Given `agent`,
+ * such a task is sent the agent's `baseUrl` as the agent spells it and, having no key of its own,
+ * the agent's key, so `capabilitiesFor` answers both with one object; a task on another endpoint
+ * is sent only a key of its own, as `resolveApiKey` has it. The environment is not read: the
+ * agent's key is whatever the main turn is sent.
+ */
+export function taskCall(task, options, agent) {
+    const own = task.endpoint;
+    const shared = agent && (!own.baseUrl.trim() || sameUrl(own.baseUrl, agent.baseUrl));
+    const stated = {};
+    if (task.maxTokens !== undefined) {
+        stated.maxTokens = task.maxTokens;
+    }
+    if (task.temperature !== undefined) {
+        stated.temperature = task.temperature;
+    }
+    if (task.reasoningEffort !== undefined) {
+        stated.reasoningEffort = task.reasoningEffort;
+    }
+    return {
+        endpoint: agent
+            ? {
+                ...own,
+                ...(shared ? { baseUrl: agent.baseUrl } : {}),
+                apiKey: resolveApiKey(own, agent, {}),
+            }
+            : own,
+        model: task.model,
+        options: { ...options, ...stated },
+    };
+}

package/dist/snapshot.d.ts

@@ -28,7 +28,7 @@ export interface ModelSnapshot {
      * none refused.
      */
     refusedEfforts?: string[];
-    /** The efforts a refusal published as this model's, in ladder order. Absent is none published. */
+    /** The efforts a refusal published as this model's, in the order it gave them. Absent is none published. */
     supportedEfforts?: string[];
 }
 /** What one endpoint refused, and under it what each of its models did. */
@@ -55,6 +55,10 @@ export interface CapabilitySnapshot {
 /**
  * Every refusal this process has latched, as a JSON-safe blob to store and hand back on boot.
  *
+ * @returns A fresh object that shares nothing with the live latches, its lists copied and the two
+ * refused ones sorted.
+ *
+ * @remarks
  * Covers what `negotiate` latches on endpoints and models and the models `ask` found refusing the
  * no-thinking hints. Only what was actually refused is in it, so a snapshot of a process that met
  * no refusals has no endpoints. Endpoints are named by digest rather than URL and key, since the
@@ -65,15 +69,16 @@ export declare function exportCapabilities(): CapabilitySnapshot;
 /**
  * Latches what a stored snapshot says was refused, on top of whatever this process has learned.
  *
+ * @param snapshot - What `exportCapabilities` returned, as stored. Read defensively: a field of the
+ * wrong type is skipped rather than trusted.
+ * @returns Whether the snapshot was of this version and applied.
+ *
+ * @remarks
  * Refusals only ever latch off, so importing merges rather than replaces: a flag already off stays
  * off whatever the snapshot says, and one the snapshot has off is turned off. A snapshot of another
  * version, or anything that is not one, is ignored — a stale shape costs the refused requests it
  * would have saved, which is what a restart cost before. How old is too old is the consumer's call,
  * made on `savedAt` before importing, or afterwards per endpoint with `expireCapabilities`, since a
  * server behind a URL can be upgraded between boots.
- *
- * @param snapshot What `exportCapabilities` returned, as stored. Read defensively: a field of the
- * wrong type is skipped rather than trusted.
- * @returns Whether the snapshot was of this version and applied.
  */
 export declare function importCapabilities(snapshot: unknown): boolean;

package/dist/snapshot.js

@@ -1,6 +1,7 @@
-import { capabilitiesById, knownCapabilities, MODEL_FLAGS, modelCapabilitiesFor, OPTIMISTIC_MODEL, } from "./capabilities.js";
-import { isRecord } from "./guards.js";
-import { hintKey, refusedHints } from "./side-task.js";
+import { capabilitiesById, knownCapabilities, MODEL_FLAGS, modelCapabilitiesFor, OPTIMISTIC_MODEL, } from './capabilities.js';
+import { modelKey } from './client.js';
+import { isRecord } from './guards.js';
+import { refusedHints } from './side-task.js';
 /**
  * What endpoints and models refused, carried across a restart.
  *
@@ -11,27 +12,52 @@ import { hintKey, refusedHints } from "./side-task.js";
  */
 /** The version `importCapabilities` accepts. Raised when what is latched changes shape. */
 export const CAPABILITY_SNAPSHOT_VERSION = 1;
+/**
+ * A model's snapshot as it starts out: every flag on, and both refused lists empty.
+ *
+ * @returns A fresh object each time, since `exportCapabilities` writes onto what it is given.
+ */
 const optimisticModel = () => ({
     ...OPTIMISTIC_MODEL,
     thinkingHints: true,
     refusedFields: [],
     refusedEfforts: [],
 });
+/**
+ * Whether a model's snapshot holds a refusal, which is what earns it a place in the blob.
+ *
+ * @param model - The snapshot. Its `supportedEfforts` is not read: a published list latches
+ * nothing.
+ * @returns `true` where a flag is off, the hints were refused, or either refused list has an entry.
+ */
 const refusedAnything = (model) => MODEL_FLAGS.some((flag) => !model[flag]) ||
     !model.thinkingHints ||
     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. */
+/**
+ * Latches every string in a stored list into a live set, skipping what is not a list of them.
+ *
+ * @param held - The live set. Written to, and only ever added to.
+ * @param stored - The list as the snapshot holds it. Anything but an array is skipped whole, and
+ * an entry that is not a string is skipped on its own.
+ */
 const latchInto = (held, stored) => {
-    if (!Array.isArray(stored))
+    if (!Array.isArray(stored)) {
         return;
-    for (const value of stored)
-        if (typeof value === "string")
+    }
+    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.
  *
+ * @returns A fresh object that shares nothing with the live latches, its lists copied and the two
+ * refused ones sorted.
+ *
+ * @remarks
  * Covers what `negotiate` latches on endpoints and models and the models `ask` found refusing the
  * no-thinking hints. Only what was actually refused is in it, so a snapshot of a process that met
  * no refusals has no endpoints. Endpoints are named by digest rather than URL and key, since the
@@ -42,12 +68,14 @@ export function exportCapabilities() {
     const endpoints = {};
     const entry = (id) => {
         const held = endpoints[id];
-        if (held)
+        if (held) {
             return held;
+        }
         const fresh = { strictSchemas: true, usageInStream: true, models: {} };
         const since = knownCapabilities().get(id)?.since;
-        if (since !== undefined)
+        if (since !== undefined) {
             fresh.since = since;
+        }
         endpoints[id] = fresh;
         return fresh;
     };
@@ -55,16 +83,19 @@ export function exportCapabilities() {
         const models = {};
         for (const [name, refused] of supports.models) {
             const model = optimisticModel();
-            for (const flag of MODEL_FLAGS)
+            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)
+            if (refused.supportedEfforts) {
                 model.supportedEfforts = [...refused.supportedEfforts];
-            if (refusedAnything(model))
+            }
+            if (refusedAnything(model)) {
                 models[name] = model;
+            }
         }
         if (!supports.strictSchemas || !supports.usageInStream || Object.keys(models).length) {
             Object.assign(entry(id), {
@@ -85,55 +116,67 @@ export function exportCapabilities() {
 /**
  * Latches what a stored snapshot says was refused, on top of whatever this process has learned.
  *
+ * @param snapshot - What `exportCapabilities` returned, as stored. Read defensively: a field of the
+ * wrong type is skipped rather than trusted.
+ * @returns Whether the snapshot was of this version and applied.
+ *
+ * @remarks
  * Refusals only ever latch off, so importing merges rather than replaces: a flag already off stays
  * off whatever the snapshot says, and one the snapshot has off is turned off. A snapshot of another
  * version, or anything that is not one, is ignored — a stale shape costs the refused requests it
  * would have saved, which is what a restart cost before. How old is too old is the consumer's call,
  * made on `savedAt` before importing, or afterwards per endpoint with `expireCapabilities`, since a
  * server behind a URL can be upgraded between boots.
- *
- * @param snapshot What `exportCapabilities` returned, as stored. Read defensively: a field of the
- * wrong type is skipped rather than trusted.
- * @returns Whether the snapshot was of this version and applied.
  */
 export function importCapabilities(snapshot) {
-    if (!isRecord(snapshot) || snapshot.version !== CAPABILITY_SNAPSHOT_VERSION)
+    if (!isRecord(snapshot) || snapshot.version !== CAPABILITY_SNAPSHOT_VERSION) {
         return false;
-    if (!isRecord(snapshot.endpoints))
+    }
+    if (!isRecord(snapshot.endpoints)) {
         return false;
+    }
     for (const [id, endpoint] of Object.entries(snapshot.endpoints)) {
-        if (!isRecord(endpoint))
+        if (!isRecord(endpoint)) {
             continue;
+        }
         const supports = capabilitiesById(id);
-        if (endpoint.strictSchemas === false)
+        if (endpoint.strictSchemas === false) {
             supports.strictSchemas = false;
-        if (endpoint.usageInStream === false)
+        }
+        if (endpoint.usageInStream === false) {
             supports.usageInStream = false;
+        }
         // Older of the two, so a snapshot ages an entry and never rejuvenates one: importing must not
         // be a way to keep a latch from ever reaching `expireCapabilities`.
-        if (typeof endpoint.since === "number" && endpoint.since < supports.since) {
+        if (typeof endpoint.since === 'number' && endpoint.since < supports.since) {
             supports.since = endpoint.since;
         }
-        if (!isRecord(endpoint.models))
+        if (!isRecord(endpoint.models)) {
             continue;
+        }
         for (const [name, model] of Object.entries(endpoint.models)) {
-            if (!isRecord(model))
+            if (!isRecord(model)) {
                 continue;
+            }
             const refused = modelCapabilitiesFor(supports, name);
-            for (const flag of MODEL_FLAGS)
-                if (model[flag] === false)
+            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)) {
-                const listed = model.supportedEfforts.filter((value) => typeof value === "string");
-                if (listed.length)
+                const listed = model.supportedEfforts.filter((value) => typeof value === 'string');
+                if (listed.length) {
                     refused.supportedEfforts = listed;
+                }
             }
             latchInto(refused.refusedFields, model.refusedFields);
-            if (model.thinkingHints === false)
-                refusedHints().add(hintKey(id, name));
+            if (model.thinkingHints === false) {
+                refusedHints().add(modelKey(id, name));
+            }
         }
     }
     return true;