@cubicecho/agent-core 2.16.0 → 2.18.0

package/README.md

@@ -21,7 +21,7 @@ only, Node >=22.
 | Module | What it does |
 | --- | --- |
 | `schema-compat` | Makes an MCP tool schema something a strict or grammar-constrained server will accept. `sanitizeTools`, `relaxTools`, `isGrammarError`. |
-| `tool-loading` | On-demand tool discovery: a name-only catalogue plus a `load_tools` meta-tool, so a run pays for the schemas it asks for instead of all of them. |
+| `tool-loading` | On-demand tool discovery: a name-only catalogue plus a `load_tools` meta-tool, so a run pays for the schemas it asks for instead of all of them. Plus `preselectByKeywords`, which picks from it without a model. |
 | `stream` | Reads one streamed turn back into a message: token callbacks, tool-call reassembly, fenced reasoning taken out of the answer, and the idle watchdog that turns a silent endpoint into `EndpointSilent`. |
 | `capabilities` | What an endpoint turned out not to support — and, under it, what one model on that endpoint did not — plus the loop that answers either when it says so. `capabilitiesFor`, `modelCapabilitiesFor`, `negotiate`. |
 | `thinking` | Tells a scratchpad fenced inside `content` from the answer: `FenceSplitter` for a stream, `stripThinking` for a whole reply, and the fence tables both read. |
@@ -38,6 +38,7 @@ only, Node >=22.
 | `tool-calls` | Reading what a model meant by a tool call it did not write cleanly: `parseToolArguments` repairs almost-JSON arguments and says when they were cut off, `recoverToolCalls` finds calls written into the reply as text. |
 | `compaction` | Keeping a long run inside its window: `pruneToolResults` clears stale tool results, `planCompaction` and `compactTranscript` fold the oldest stretch into a summary. |
 | `snapshot` | `exportCapabilities` and `importCapabilities`: the latched refusals as a JSON blob a consumer stores, so a restart need not learn them again. |
+| `spec` | `parseSpec`, `resolveAgentSpec` and `exportSpec`: an agent as a versioned JSON document, layered into the flat config the loop takes. Imports nothing but types, and is published separately at `@cubicecho/agent-core/spec`. |
 | `reset` | `resetAll`: drops every cache and latch in one call, so a teardown cannot forget one. |
 | `tokens` | `estimateTokens`: characters over four, deliberately low, for everything here that has to guess at a window. |
 | `errors` | `errorMessage`: a caught `unknown` turned into something a run row can hold. |
@@ -441,6 +442,33 @@ run. A preselection shapes the first step alone: those tools, no catalogue, no `
 a model with the menu still in front of it shops, reloading what it has or picking a sibling —
 and everything is back from the second step on.
 
+That preselection costs a round trip to a model, which on a local box is a few seconds before the
+run has started, spent on a model doing term matching. `preselect(..., { keywords: true })` does
+the matching directly and spends the model only on what the words cannot settle:
+
+```ts
+const preselected = await preselect(config, config.toolSelectModel, catalog, prompt, {
+  keywords: true, // or { minScore, dropoff } to move the bar
+  onNotice,
+});
+```
+
+`preselectByKeywords` is the matcher on its own, ranking every tool against the request by BM25
+over its name, its server's label and its one-line description. BM25 rather than counting shared
+words, because a catalogue is full of words every tool uses — "list", "get", "file" — and an
+overlap count hands the top of the ranking to whichever tool has the longest description. English
+function words are dropped outright: the inverse document frequency is meant to handle them, and
+over a real corpus it would, but twenty one-line descriptions are few enough that "for" lands in
+one of them and scores as the most distinctive word in the request.
+
+What a caller acts on is `confident`, which is deliberately hard to earn: something more
+distinctive than a word the catalogue shares has to have matched, and the tools the cap left out
+have to score well below the ones it kept — a hit just under the line scoring nearly as much as
+one just over it means the ranking chose arbitrarily, which is the case a model is worth spending
+on. Matching nothing is not confident either, since the words cannot tell a request that needs no
+tools from one whose words are not in the catalogue. An empty `toolSelectModel` still means no
+preselection at all, words included.
+
 A turn cut off at `maxTokens` is said so as a notice, and with `maxContinuations` above zero it is
 continued first. `continueTurn` is the same thing for a caller with its own loop:
 
@@ -795,6 +823,57 @@ The seam is not finished. `timeoutMs` narrows to the one field it reads, but `ge
 asks for the whole of `Endpoint`. `requestTimeoutSeconds` became optional in v2, so a consumer
 with no timeout to give now leaves it out rather than inventing a `0`.
 
+## An agent as a document
+
+The seam above says what a *running* agent is. `@cubicecho/agent-core/spec` says what a **stored**
+one is: a versioned JSON document that any host on this package can read, layer and hand to the
+loop. It exists because the applications here spell "an agent" three incompatible ways — `maxTokens: 0`
+means *no ceiling* in one, *inherit* in the next and *a real ceiling of zero* in the third, and an
+empty server list means *no tools* in one and *every tool* in another. `docs/agent-spec.md` argues
+the whole thing out.
+
+```ts
+import { parseSpec, resolveAgentSpec } from "@cubicecho/agent-core/spec";
+
+const { spec, errors, warnings } = parseSpec(JSON.parse(text));
+if (!spec) throw new Error(errors.join("\n"));
+
+const config = resolveAgentSpec([settingsSpec, spec]); // weakest layer first
+const result = await runAgentLoop({ config, ... });    // already the shape the loop takes
+```
+
+**Absent inherits, and nothing else does.** There is no inherit sentinel at any depth: `0`, `-1`,
+`""` and `[]` are values that mean what they say, and `null` reads as absent because a nullable
+column round-trips through JSON that way. `tools.servers` keeps its tri-state — absent is every
+server the host offers, `[]` is none, a list is exactly those — and layering replaces it whole
+rather than unioning, since a union of "these two" and "none" is "these two", which silently widens
+a scoped agent. `prompt`, `hooks` and `tasks` merge by id, which is one rule expressing two
+behaviours: different ids stack, the same id replaces.
+
+`parseSpec` reports every problem at once and refuses only four things, all of them about the
+document rather than a value: it is not an object, the `spec` token is missing or of another major,
+a `requires` entry this host does not understand, or a container is of the wrong kind. Everything
+else is dropped with a warning — including an out-of-range number, which is **dropped rather than
+clamped**, because a clamp invents a value the author did not write while dropping falls back to one
+somebody did.
+
+The document carries **no credential at any depth**, and a `${VAR}`-shaped string is kept as the
+literal it is rather than expanded — a format with no interpolation needs no credential denylist.
+Resolution yields `apiKey: ""`, which `getClient` turns into `NO_KEY`; a host that wants inheritance
+applies `resolveApiKey` afterwards, so a document naming somebody else's endpoint cannot make this
+host send its own provider key there. `exportSpec(spec)` strips a bundled server's `env` and
+`headers`, and a redacted document is still a valid one.
+
+`bundle.mcpServers` is parsed only under `parseSpec(document, { bundle: true })`. A bundled server
+is a command line and an environment map, so importing one is equivalent to running a program, and
+that is a decision a host makes rather than inherits from a default.
+
+The subpath is separate from the main entry for one reason: `client.ts` and `hooks.ts` import
+`node:crypto`, and `spec.ts` imports nothing but types, so a browser validating a pasted document in
+a form can load it. Nothing in `src/` imports it — the same direction the config seam runs, which is
+what lets a document travel between hosts without the loop growing an opinion about where an agent
+comes from.
+
 ## What is kept for the life of the process
 
 Four caches outlive any one run: the `OpenAI` clients, the model listings, the latched

package/dist/agent-loop.d.ts

@@ -5,7 +5,7 @@ import type { Endpoint, ModelParams, RetryPolicy, ToolPolicy } from "./config.ts
 import { type RunEventInput, type RunMetrics } from "./events.ts";
 import { type HookContext, type HookEvent, type HookNote, type HookRunner } from "./hooks.ts";
 import type { Turn, TurnUsage } from "./stream.ts";
-import { type ToolOrder } from "./tool-loading.ts";
+import { type KeywordPreselectOptions, type ToolOrder } from "./tool-loading.ts";
 /**
  * The one place a streamed request's body is decided from a config and what the endpoint and
  * the model have refused.
@@ -72,19 +72,30 @@ export declare function resolveApiKey(own: {
  * a failed one costs nothing — it is reported through `onNotice` and answered with an empty list,
  * since a side task is never worth failing the run. A stop still throws.
  *
+ * With `keywords`, the request's own words are matched against the catalogue first and the model
+ * is spent only on what they cannot settle, which on a local box is the difference between a run
+ * starting now and starting in a few seconds. The words have to be clear about it; see
+ * `preselectByKeywords` for what that means.
+ *
  * @param config The endpoint the preselector is reached through.
  * @param model The preselector. An empty name picks nothing, which is what `toolSelectModel`
  * means by empty.
  * @param catalog The servers to choose from.
  * @param prompt The request being planned for. Only its head is read; see `preselectInput`.
- * @param options Cancellation, notices, the reply ceiling (256) and the cap the choice is held to
- * (`MAX_PER_LOAD`).
+ * @param options Cancellation, notices, the reply ceiling (256), the cap the choice is held to
+ * (`MAX_PER_LOAD`), and whether to try the words first.
  */
-export declare function preselect(config: Endpoint, model: string, catalog: CatalogServer[], prompt: string, { signal, onNotice, maxTokens, maxPerLoad, }?: {
+export declare function preselect(config: Endpoint, model: string, catalog: CatalogServer[], prompt: string, { signal, onNotice, maxTokens, maxPerLoad, keywords, }?: {
     signal?: AbortSignal;
     onNotice?: (message: string) => void;
     maxTokens?: number;
     maxPerLoad?: number;
+    /**
+     * Try `preselectByKeywords` first and spend the model only on what it cannot settle. `true`
+     * takes its defaults; an object tunes the thresholds. An empty `model` still means no
+     * preselection at all, words included — that is what `toolSelectModel: ""` asks for.
+     */
+    keywords?: boolean | KeywordPreselectOptions;
 }): Promise<string[]>;
 /** One call the model made, as `dispatch` is handed it. */
 export interface ToolCallRequest {

package/dist/agent-loop.js

@@ -10,7 +10,7 @@ import { runTurn } from "./run-turn.js";
 import { relaxTools, sanitizeTools } from "./schema-compat.js";
 import { askJson, tryAsk } from "./side-task.js";
 import { parseToolArguments, recoverToolCalls } from "./tool-calls.js";
-import { catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_PER_LOAD, orderTools, PRESELECT_SCHEMA, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.js";
+import { catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_PER_LOAD, orderTools, PRESELECT_SCHEMA, preselectByKeywords, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.js";
 /**
  * The loop above a turn: send, run the tools the model asked for, send again, until it stops
  * asking.
@@ -114,17 +114,32 @@ export function resolveApiKey(own, inherited, env = process.env) {
  * a failed one costs nothing — it is reported through `onNotice` and answered with an empty list,
  * since a side task is never worth failing the run. A stop still throws.
  *
+ * With `keywords`, the request's own words are matched against the catalogue first and the model
+ * is spent only on what they cannot settle, which on a local box is the difference between a run
+ * starting now and starting in a few seconds. The words have to be clear about it; see
+ * `preselectByKeywords` for what that means.
+ *
  * @param config The endpoint the preselector is reached through.
  * @param model The preselector. An empty name picks nothing, which is what `toolSelectModel`
  * means by empty.
  * @param catalog The servers to choose from.
  * @param prompt The request being planned for. Only its head is read; see `preselectInput`.
- * @param options Cancellation, notices, the reply ceiling (256) and the cap the choice is held to
- * (`MAX_PER_LOAD`).
+ * @param options Cancellation, notices, the reply ceiling (256), the cap the choice is held to
+ * (`MAX_PER_LOAD`), and whether to try the words first.
  */
-export async function preselect(config, model, catalog, prompt, { signal, onNotice, maxTokens = 256, maxPerLoad = MAX_PER_LOAD, } = {}) {
+export async function preselect(config, model, catalog, prompt, { signal, onNotice, maxTokens = 256, maxPerLoad = MAX_PER_LOAD, keywords, } = {}) {
     if (!model || !catalog.some((server) => server.tools.length > 0))
         return [];
+    if (keywords) {
+        const guess = preselectByKeywords(catalog, prompt, {
+            maxPerLoad,
+            ...(keywords === true ? {} : keywords),
+        });
+        if (guess.confident) {
+            onNotice?.(`chose ${guess.names.length} tool${guess.names.length === 1 ? "" : "s"} by name`);
+            return guess.names;
+        }
+    }
     const reply = await tryAsk("preselect", () => askJson(config, model, preselectSystem(maxPerLoad), preselectInput(catalog, prompt), PRESELECT_SCHEMA, { name: "preselection", maxTokens, signal, onNotice }), { onNotice });
     return preselection(reply, catalog, maxPerLoad);
 }

package/dist/index.d.ts

@@ -26,8 +26,9 @@ export { type RunTurnOptions, runTurn } from "./run-turn.ts";
 export { isGrammarError, relaxTools, sanitizeTools } from "./schema-compat.ts";
 export { type AskJsonOptions, ask, askJson, clean, listLines, parseJson, resetHints, type SideTaskInput, type SideTaskOptions, tryAsk, } from "./side-task.ts";
 export { CAPABILITY_SNAPSHOT_VERSION, type CapabilitySnapshot, type EndpointSnapshot, exportCapabilities, importCapabilities, type ModelSnapshot, } from "./snapshot.ts";
+export { AGENT_SPEC, AGENT_SPEC_VERSION, AGENT_TASKS, type AgentHook, type AgentSpec, type EndpointSpec, type ExportSpecOptions, exportSpec, type ModelSpec, type ParsedSpec, type ParseSpecOptions, type PromptPart, parseSpec, RESOLVED_DEFAULTS, type ResolvedAgent, type ResolvedTask, type RetrySpec, resolveAgentSpec, SPEC_EVENTS, type SpecBundle, type SpecServer, type TaskSpec, type ToolsSpec, } from "./spec.ts";
 export { type Produced, type StreamTurnOptions, streamTurn, type Turn, type TurnUsage, } from "./stream.ts";
 export { ALL_FENCES, DEFAULT_FENCES, type Fence, FenceSplitter, type FenceSplitterOptions, type Split, stripThinking, THINK_FENCE, } from "./thinking.ts";
 export { estimateTokens } from "./tokens.ts";
 export { parseToolArguments, recoverToolCalls, ToolArgumentsError, type ToolCall, } from "./tool-calls.ts";
-export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_CARRIED, MAX_PER_LOAD, orderTools, PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselectInput, preselection, preselectSystem, requestedNames, type ToolOrder, } from "./tool-loading.ts";
+export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, KEYWORD_DROPOFF, KEYWORD_MIN_SCORE, type KeywordPreselection, type KeywordPreselectOptions, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_CARRIED, MAX_PER_LOAD, orderTools, PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselectByKeywords, preselectInput, preselection, preselectSystem, requestedNames, type ToolMatch, type ToolOrder, } from "./tool-loading.ts";

package/dist/index.js

@@ -24,8 +24,9 @@ export { runTurn } from "./run-turn.js";
 export { isGrammarError, relaxTools, sanitizeTools } from "./schema-compat.js";
 export { ask, askJson, clean, listLines, parseJson, resetHints, tryAsk, } from "./side-task.js";
 export { CAPABILITY_SNAPSHOT_VERSION, exportCapabilities, importCapabilities, } from "./snapshot.js";
+export { AGENT_SPEC, AGENT_SPEC_VERSION, AGENT_TASKS, exportSpec, parseSpec, RESOLVED_DEFAULTS, resolveAgentSpec, SPEC_EVENTS, } from "./spec.js";
 export { streamTurn, } from "./stream.js";
 export { ALL_FENCES, DEFAULT_FENCES, FenceSplitter, stripThinking, THINK_FENCE, } from "./thinking.js";
 export { estimateTokens } from "./tokens.js";
 export { parseToolArguments, recoverToolCalls, ToolArgumentsError, } from "./tool-calls.js";
-export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_CARRIED, MAX_PER_LOAD, orderTools, PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.js";
+export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, KEYWORD_DROPOFF, KEYWORD_MIN_SCORE, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_CARRIED, MAX_PER_LOAD, orderTools, PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselectByKeywords, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.js";

package/dist/spec.d.ts

@@ -0,0 +1,319 @@
+import type { AgentConfig, Endpoint } from "./config.ts";
+import type { HookEvent } from "./hooks.ts";
+/**
+ * A JSON document that defines an agent, and the rules for reading one.
+ *
+ * Four applications sit on this package and each one spells "an agent" differently: a singleton
+ * settings row, a deliberately jobless agent table whose job comes from three other rows, an
+ * override profile that resolves into a whole synthesised settings object. None of them can read
+ * another's agents, and `maxTokens: 0` means *no ceiling* in one, *inherit* in the next and *a
+ * 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`.
+ */
+/** The token a document declares itself with. A loader refuses anything else. */
+export declare const AGENT_SPEC = "cubicecho.agent/1";
+/** The major version `AGENT_SPEC` pins. Raised only when a field changes meaning. */
+export declare const AGENT_SPEC_VERSION = 1;
+/**
+ * The side tasks this package has code for: documentation and a sensible UI order, not a
+ * validator.
+ *
+ * `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"];
+/**
+ * Every event a hook may be bound to, restated so this module stays free of `node:crypto`.
+ *
+ * `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.
+ */
+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. */
+export interface AgentSpec {
+    /** Exactly `AGENT_SPEC`. Missing, mistyped or another major is refused. */
+    spec: typeof AGENT_SPEC;
+    /** A URL for an editor's autocompletion. Never fetched, never read, never validated against. */
+    $schema?: string;
+    /** A stable handle within a host: `reviewer`, `local-qwen`. Absent in a layer of pure defaults. */
+    id?: string;
+    /** What a person calls it. Absent falls back to `id`. */
+    name?: string;
+    /** One line for an operator choosing between agents. Never sent to a model — that is `prompt`. */
+    description?: string;
+    endpoint?: EndpointSpec;
+    model?: ModelSpec;
+    /** Ordered layers of system prompt, merged by `id` and joined with blank lines on resolve. */
+    prompt?: PromptPart[];
+    tools?: ToolsSpec;
+    retry?: RetrySpec;
+    /** Side tasks run on a model other than the agent's. Open by design; see `AGENT_TASKS`. */
+    tasks?: Record<string, TaskSpec>;
+    hooks?: AgentHook[];
+    /** Definitions carried so an agent travels whole. Executable by proxy; see `parseSpec`. */
+    bundle?: SpecBundle;
+    /** Host payloads keyed by reverse domain. Carries no semantics and is never validated. */
+    extensions?: Record<string, unknown>;
+    /** Extension keys a host must understand, or it refuses to run this agent. */
+    requires?: string[];
+    /** Keys from a later 1.x, kept so an edit-and-export cycle does not erase them. */
+    [key: string]: unknown;
+}
+/** Where a model is reached, and how long to wait for it. There is no credential field, by design. */
+export interface EndpointSpec {
+    /** Any OpenAI-compatible base URL. Absent inherits; absent everywhere means it cannot run. */
+    baseUrl?: string;
+    /** Seconds of silence allowed between chunks. Zero is no limit. */
+    requestTimeoutSeconds?: number;
+    /** Seconds allowed for the first chunk. Zero is no limit; absent is five times the above. */
+    firstTokenSeconds?: number;
+}
+/** Which model answers and how, including the request fields this interface cannot spell. */
+export interface ModelSpec {
+    /** Absent inherits. Empty names no model, which cannot run. */
+    model?: string;
+    /** The reply's ceiling. Zero sends none and lets the server decide — a value, not a sentinel. */
+    maxTokens?: number;
+    /** Zero to two. Zero means zero. */
+    temperature?: number;
+    /** `reasoning_effort`. `"off"` and `""` send nothing; any other string passes through. */
+    reasoningEffort?: string;
+    /** What the operator says this model reads, in tokens. Zero asks the endpoint. */
+    contextLength?: number;
+    /** Request fields the interface cannot spell. `model`, `messages`, `stream`, `tools` are dropped. */
+    extraBody?: Record<string, unknown>;
+}
+/** 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. */
+    id: string;
+    /** The text. Empty deletes the part a layer below contributed. Absent only when `ref` is given. */
+    text?: string;
+    /** Where the text lives instead. The shape is validated; the reference is never resolved. */
+    ref?: {
+        type: "file" | "url";
+        value: string;
+    };
+}
+/** How tools reach the model, and which servers this agent may reach at all. */
+export interface ToolsSpec {
+    discovery?: "eager" | "ondemand";
+    /** The hard stop on a tool loop. At least one. */
+    maxIterations?: number;
+    /**
+     * The MCP servers this agent may reach, by effective slug (`row.slug ?? row.id`).
+     * Absent is every server the host offers, `[]` is none, and a list is exactly those.
+     * Three different answers, and a loader must never collapse one into another.
+     */
+    servers?: string[];
+}
+/** What to do about a request lost before the model produced anything. */
+export interface RetrySpec {
+    /** Re-sends of a request lost before the model produced anything. Zero is none — a value. */
+    maxRetries?: number;
+    /** Seconds to wait out a server loading its model. Zero is not at all; absent is two minutes. */
+    loadingTimeoutSeconds?: number;
+}
+/** One side task, which may run on a different model — and a different machine — than the agent. */
+export interface TaskSpec {
+    /** The model for this task. Empty turns it off, which is how a layer declines one below it. */
+    model?: string;
+    /** Where that model lives, when it is not on the agent's endpoint. */
+    endpoint?: EndpointSpec;
+    maxTokens?: number;
+    temperature?: number;
+    reasoningEffort?: string;
+}
+/** A tool call bound to a lifecycle event, run by the host rather than the model. */
+export interface AgentHook {
+    /** Unique within the agent. Merging happens on it. */
+    id: string;
+    /** One of `SPEC_EVENTS`. An event this host never fires is a warning, not an error. */
+    on: HookEvent;
+    /** The server whose tool this is, by effective slug. */
+    server: string;
+    /** The server's own name for the tool, not the qualified one the model sees. */
+    tool: string;
+    /** Arguments as JSON, with `{{path}}` placeholders filled from the event's context. */
+    args?: unknown;
+    /** Hand what the tool returns to the model. Only the events that run before one may. */
+    inject?: boolean;
+    /** Let this hook decline what its event announces. `beforeCompact` only. */
+    veto?: boolean;
+    maxTokens?: number;
+    timeoutMs?: number;
+    /** `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;
+    slug?: string;
+    [key: string]: unknown;
+}
+/** What an agent carries so it can travel whole: the definitions of the servers it names. */
+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.
+     *
+     * 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
+     * ninety-second call timeout on a round trip. Importing the type is not an option either, since
+     * the pool pulls the MCP SDK and `openai` is this package's only peer dependency.
+     */
+    mcpServers?: SpecServer[];
+}
+/** One side task, resolved: a model, and the endpoint it is reached through. */
+export interface ResolvedTask {
+    model: string;
+    /** This task's endpoint, which is the agent's unless a layer named another. */
+    endpoint: Endpoint;
+    maxTokens?: number;
+    temperature?: number;
+    reasoningEffort?: string;
+}
+/**
+ * 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.
+ *
+ * `extends AgentConfig` is the whole point — `getClient(resolved)` and
+ * `runAgentLoop({ config: resolved })` take this unchanged, and no adapter is needed.
+ */
+export interface ResolvedAgent extends AgentConfig {
+    id: string;
+    name: string;
+    description: string;
+    /** The tri-state preserved: absent is every server the host offers, empty is none. */
+    servers?: readonly string[];
+    /**
+     * The merged prompt parts, in order. `systemPrompt` is the join of their texts, so a part that
+     * is only a `ref` contributes nothing to it — the host resolves the reference and re-resolves,
+     * or reads it from here and does what it likes.
+     */
+    prompt: readonly PromptPart[];
+    /** Only the tasks a layer configured and none declined. `toolSelect` also flattens to `toolSelectModel`. */
+    tasks: Readonly<Record<string, ResolvedTask>>;
+    hooks: readonly AgentHook[];
+    /** Bundled server definitions, merged by effective slug. Empty unless a bundle was parsed. */
+    mcpServers: readonly SpecServer[];
+    extensions: Readonly<Record<string, unknown>>;
+    /** Every layer's requirements, unioned, so a layer above cannot quietly drop one below it. */
+    requires: readonly string[];
+}
+/**
+ * What a field falls back to when no layer said anything at all.
+ *
+ * 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
+ * the resolved object too, which is how `requestTimeoutSeconds` keeps meaning "no opinion".
+ */
+export declare const RESOLVED_DEFAULTS: {
+    readonly temperature: 0.7;
+    readonly maxTokens: 0;
+    readonly contextLength: 0;
+    readonly toolDiscovery: "eager";
+    readonly maxToolIterations: 20;
+    readonly maxRetries: 0;
+};
+/** What `parseSpec` hands back. A refused document is `spec: null` with the reasons in `errors`. */
+export interface ParsedSpec {
+    /** The document with everything that did not survive dropped, or null if it was refused. */
+    spec: AgentSpec | null;
+    /** Why it was refused. Empty when it was not. */
+    errors: string[];
+    /** What was dropped, and what is worth an operator's attention. Never a reason to refuse. */
+    warnings: string[];
+}
+/** 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.
+     */
+    bundle?: boolean;
+    /** The events this host actually fires, defaulting to all of them. A hook bound elsewhere warns. */
+    events?: readonly string[];
+    /** The `extensions` keys this host understands. A `requires` entry outside it refuses the load. */
+    understands?: readonly string[];
+}
+/**
+ * Reads a document, dropping what it cannot use and refusing only what it cannot identify.
+ *
+ * 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.
+ *
+ * There are exactly four hard errors, all of them about the document rather than a value: it is
+ * not an object; the `spec` token is missing or of another major; a `requires` entry this host
+ * does not understand; a container of the wrong kind. Everything else drops the offending field
+ * and warns — the lesson a consumer learned the hard way when one stored out-of-range value
+ * stopped its server booting. Out-of-range values are dropped rather than clamped, because a
+ * clamp invents a number the author did not write while dropping falls back to one somebody did.
+ *
+ * Version handling is the deliberate opposite of `importCapabilities`, which shrugs at a foreign
+ * 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.
+ *
+ * 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
+ * of them. Scalars take the last layer that has the key. `extraBody` and `extensions` merge by
+ * top-level key. `prompt`, `hooks` and `tasks` merge by id, ordered by first appearance, which is
+ * one rule expressing two behaviours that look unrelated: different ids stack, and the same id
+ * replaces. `tools.servers` replaces whole, because a tri-state cannot be unioned. `requires`
+ * unions, so a layer above cannot quietly drop a requirement below it.
+ *
+ * No layer is ever fetched. There is no `extends` field and no URL resolution; which documents
+ * layer is the host's call, the same answer `resolveApiKey` gives about keys. `apiKey` comes back
+ * 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
+     * `state({ secrets })`, because those are where a bundled server's credentials live.
+     */
+    secrets?: boolean;
+}
+/**
+ * A document fit to leave the host: the same agent, with the secrets of its bundled servers gone.
+ *
+ * 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.
+ */
+export declare function exportSpec(spec: AgentSpec, { secrets }?: ExportSpecOptions): AgentSpec;