@cubicecho/agent-core 2.23.0 → 2.25.0

package/dist/snapshot.js

@@ -1,5 +1,7 @@
-import { capabilitiesById, knownCapabilities, modelCapabilitiesFor } from "./capabilities.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.
  *
@@ -10,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 = () => ({
-    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 ||
+/**
+ * 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.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.
+ *
+ * @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)) {
+        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.
  *
+ * @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
@@ -41,33 +68,34 @@ 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;
     };
     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] } : {}),
-            };
-            if (refusedAnything(model))
+            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;
+            }
         }
         if (!supports.strictSchemas || !supports.usageInStream || Object.keys(models).length) {
             Object.assign(entry(id), {
@@ -85,76 +113,70 @@ 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.
  *
+ * @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);
-            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)) {
-                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;
-            }
-            if (Array.isArray(model.refusedFields)) {
-                for (const field of model.refusedFields) {
-                    if (typeof field === "string")
-                        refused.refusedFields.add(field);
                 }
             }
-            if (model.thinkingHints === false)
-                refusedHints().add(hintKey(id, name));
+            latchInto(refused.refusedFields, model.refusedFields);
+            if (model.thinkingHints === false) {
+                refusedHints().add(modelKey(id, name));
+            }
         }
     }
     return true;

package/dist/spec.d.ts

@@ -1,5 +1,5 @@
-import type { AgentConfig, Endpoint } from "./config.ts";
-import type { HookEvent } from "./hooks.ts";
+import { type AgentConfig, type Endpoint } from './config.ts';
+import { 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";
@@ -24,17 +25,18 @@ export declare const AGENT_SPEC_VERSION = 1;
  * The side tasks this package has code for: documentation and a sensible UI order, not a
  * validator.
  *
+ * @remarks
  * `tasks` is an open record on purpose — a host may run tasks this package has never heard of,
  * and an unknown key is carried through untouched rather than warned about.
  */
-export declare const AGENT_TASKS: readonly ["compaction", "toolSelect", "title", "followups"];
+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.
+ * @remarks
+ * 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. */
@@ -91,6 +93,10 @@ export interface ModelSpec {
     /** Request fields the interface cannot spell. `model`, `messages`, `stream`, `tools` are dropped. */
     extraBody?: Record<string, unknown>;
 }
+/** The `ref.type` of a prompt part whose text is in a file. */
+export declare const REF_FILE: 'file';
+/** The `ref.type` of a prompt part whose text is behind a URL. */
+export declare const REF_URL: 'url';
 /** One layer of system prompt, named so a layer above can stack beside it or replace it. */
 export interface PromptPart {
     /** Names this layer: `project`, `identity`, `role`, `lane`. Merging happens on it. */
@@ -99,7 +105,7 @@ export interface PromptPart {
     text?: string;
     /** Where the text lives instead. The shape is validated; the reference is never resolved. */
     ref?: {
-        type: "file" | "url";
+        type: typeof REF_FILE | typeof REF_URL;
         value: string;
     };
 }
@@ -109,7 +115,7 @@ export interface ToolsSpec {
      * How tool definitions reach the model: all of them on every request, a name-only catalogue
      * the model loads from, or that catalogue behind a fixed `load_tools` and `call_tool`.
      */
-    discovery?: "eager" | "ondemand" | "proxy";
+    discovery?: 'eager' | 'ondemand' | 'proxy';
     /** The hard stop on a tool loop. At least one. */
     maxIterations?: number;
     /**
@@ -134,7 +140,11 @@ export interface TaskSpec {
     endpoint?: EndpointSpec;
     /** The reply's ceiling. Absent is the side task's own default, not the agent's `maxTokens`. */
     maxTokens?: number;
-    /** Absent is the side task's own default, 0.3, whatever the agent's temperature is. */
+    /**
+     * Sampling temperature, whatever the agent's own is.
+     *
+     * @defaultValue `0.3`
+     */
     temperature?: number;
     /**
      * A level has the task deliberate. Absent and `"off"` leave it with the no-thinking hints a
@@ -163,7 +173,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;
@@ -176,6 +185,7 @@ export interface SpecBundle {
      * Full MCP server definitions. Validated only as far as a round trip needs — an object, a
      * non-empty `id` or `slug`, no duplicate slugs — with every other key passed through untouched.
      *
+     * @remarks
      * This package deliberately does not restate the pool's `McpServerConfig`. Restating a union it
      * never reads is a version-skew generator: the pool carries `coerceArguments`, `maxResultChars`
      * and three separate timeouts, and a strict parse here would silently delete a server's
@@ -187,6 +197,7 @@ export interface SpecBundle {
 /**
  * One side task, resolved: a model, and the endpoint it is reached through.
  *
+ * @remarks
  * The three settings are present only where a layer stated them, and nothing is filled in from
  * the agent's own model — `taskCall` turns one into a call, and what is absent there is left to
  * the side task's default.
@@ -203,6 +214,7 @@ export interface ResolvedTask {
  * What layered documents resolve to: the flat shape the loop already takes, plus the parts of an
  * agent that are the host's to act on.
  *
+ * @remarks
  * `extends AgentConfig` is the whole point — `getClient(resolved)` and
  * `runAgentLoop({ config: resolved })` take this unchanged, and no adapter is needed.
  */
@@ -230,6 +242,7 @@ export interface ResolvedAgent extends AgentConfig {
 /**
  * What a field falls back to when no layer said anything at all.
  *
+ * @remarks
  * Not sentinels, and not invented: `toolDiscovery`, `maxRetries` and `contextLength` are the
  * "absent everywhere" column of the document's own table, and `temperature` and `maxToolIterations`
  * are what all three consumers store as their defaults today. A field left out here is left out of
@@ -255,13 +268,19 @@ export interface ParsedSpec {
 /** What `parseSpec` takes besides the document. */
 export interface ParseSpecOptions {
     /**
-     * Parse `bundle` rather than dropping it. Off by default, because a bundled server carries a
-     * command line and an environment map: loading one is equivalent to running a program, exactly
-     * as dangerous as pasting somebody's `.mcp.json`, and a host has to make that decision rather
-     * than inherit it from a default.
+     * Parse `bundle` rather than dropping it. Opt-in, because a bundled server carries a command
+     * line and an environment map: loading one is equivalent to running a program, exactly as
+     * dangerous as pasting somebody's `.mcp.json`, and a host has to make that decision rather than
+     * inherit it from a default.
+     *
+     * @defaultValue `false`
      */
     bundle?: boolean;
-    /** The events this host actually fires, defaulting to all of them. A hook bound elsewhere warns. */
+    /**
+     * The events this host actually fires. A hook bound elsewhere warns.
+     *
+     * @defaultValue `SPEC_EVENTS`, which is all of them
+     */
     events?: readonly string[];
     /** The `extensions` keys this host understands. A `requires` entry outside it refuses the load. */
     understands?: readonly string[];
@@ -269,6 +288,14 @@ export interface ParseSpecOptions {
 /**
  * Reads a document, dropping what it cannot use and refusing only what it cannot identify.
  *
+ * @param document - Anything at all — this is the front door, and it is given parsed JSON from a
+ * form, a file or another host.
+ * @param [options] - Whether to parse a bundle, which events this host fires, and which extension
+ * keys it understands.
+ * @returns The document that survived — a new object, never the one handed in — or `spec: null`
+ * where `errors` holds anything. `warnings` is filled either way.
+ *
+ * @remarks
  * Every problem is reported at once, in the `path: what is wrong` shape `validateHooks` already
  * uses, because a host showing an operator one error at a time makes them fix a document one
  * round trip at a time.
@@ -284,16 +311,16 @@ export interface ParseSpecOptions {
  * version and returns false: degrade where the loss is performance, refuse where the loss is
  * identity. A snapshot of the wrong version costs a few refused requests; an agent of the wrong
  * version is not the agent its author described.
- *
- * @param document Anything at all — this is the front door, and it is given parsed JSON from a
- * form, a file or another host.
- * @param options Whether to parse a bundle, which events this host fires, and which extension
- * keys it understands.
  */
 export declare function parseSpec(document: unknown, options?: ParseSpecOptions): ParsedSpec;
 /**
  * Layers documents into the flat object the loop takes, weakest first.
  *
+ * @param layers - The documents, weakest first: settings, then the agent, then a task, then a step.
+ * @returns The resolved agent, built new. Always whole: an empty list gives empty strings and
+ * `RESOLVED_DEFAULTS` rather than an error, and `apiKey` is `""` whatever the layers said.
+ *
+ * @remarks
  * Absent inherits, and nothing else does: `0`, `-1`, `""` and `[]` are values that mean what they
  * say, which is the whole reason the format exists — `maxTokens: 0` means three different things
  * across the three applications this was extracted from, and `temperature: 0` is unsayable in one
@@ -308,28 +335,31 @@ export declare function parseSpec(document: unknown, options?: ParseSpecOptions)
  * empty for the same reason: a document naming somebody else's endpoint must not be able to make
  * this host send its own provider key there. A host that wants inheritance applies `resolveApiKey`
  * afterwards.
- *
- * @param layers The documents, weakest first: settings, then the agent, then a task, then a step.
  */
 export declare function resolveAgentSpec(layers: readonly AgentSpec[]): ResolvedAgent;
 /** What `exportSpec` takes besides the document. */
 export interface ExportSpecOptions {
     /**
-     * Keep the environment and headers of bundled servers. Off by default, mirroring the pool's
+     * Keep the environment and headers of bundled servers. Opt-in, mirroring the pool's
      * `state({ secrets })`, because those are where a bundled server's credentials live.
+     *
+     * @defaultValue `false`
      */
     secrets?: boolean;
 }
 /**
  * A document fit to leave the host: the same agent, with the secrets of its bundled servers gone.
  *
+ * @param spec - A document, ordinarily one `parseSpec` returned.
+ * @param [options] - Whether to keep the secrets.
+ * @returns A copy one level deep, never `spec` itself: what is not redacted is shared with the
+ * original.
+ *
+ * @remarks
  * The property worth keeping is that **a redacted spec is still a valid spec** — it parses, it
  * resolves, and what comes back is the same agent pointed at the same servers, needing only the
- * credentials the importing host supplies itself. So this removes values rather than keys, and
- * nothing outside `bundle` is touched: the format has no credential field at any depth, which is
- * the reason there is nothing else to strip.
- *
- * @param spec A document, ordinarily one `parseSpec` returned.
- * @param options Whether to keep the secrets. The default is not to.
+ * credentials the importing host supplies itself. So a bundled server loses its `env` and its
+ * `headers` and nothing else, and nothing outside `bundle` is touched: the format has no
+ * credential field at any depth, which is the reason there is nothing else to strip.
  */
 export declare function exportSpec(spec: AgentSpec, { secrets }?: ExportSpecOptions): AgentSpec;