@cubicecho/agent-core 4.12.0 → 4.14.0

package/README.md

@@ -44,7 +44,7 @@ only, Node >=22.
 | `compaction` | Keeping a long run inside its window: `pruneToolResults` clears stale tool results, `planCompaction` and `compactTranscript` fold the oldest stretch into a summary. |
 | `ledger` | What stretches of a transcript cost, read off the prompt counts the server reported rather than estimated: `recordRequest`, `tokensBetween`, `estimateFrom`, `rebaseLedger`. |
 | `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`. |
+| `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`. `defineSpecColumns` maps a stored row onto a layer and back, at `@cubicecho/agent-core/spec/columns`. |
 | `reset` | `resetAll`: drops every cache and latch in one call, so a teardown cannot forget one. |
 | `runtime` | `createRuntime`: a second set of those caches, with the functions that use them as methods — for a host whose tenants must not share a client pool, a latch or an event bus. `defaultRuntime` is the one the top-level functions use. |
 | `tokens` | How big a request is, estimated: `estimateTokens` — characters over four, deliberately low — and what is built on it for everything here that has to guess at a window: `messageTokens`, `requestTokens`, `contextTokens`. |
@@ -768,8 +768,8 @@ distinctive than a word the catalogue shares has to have matched, and the tools
 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. `preselect` also takes a `temperature` and a
+tools from one whose words are not in the catalogue. An empty model still means no preselection
+at all, words included. `preselect` also takes a `temperature` and a
 `reasoningEffort` and an `extraBody`, read as `ask` reads them, and `runAgentLoop({ preselect: true })` makes the call
 itself — see "Its side tasks" below.
 
@@ -884,10 +884,12 @@ as the host passed them, this one as typed — which is why the snippet stores o
 without waiting; a host that stores those notes with the turn, or would otherwise exit before the
 turn is remembered, awaits it once the answer is out.
 
-The loop gathers before its first request, and nothing of the host's can run beside that. A host
-with pre-turn work to overlap with the hooks — compaction, a preselection — calls `gather` itself,
-applies `withContext` to the current question as well, calls `notify` after, and passes no `hooks`
-(see [Hooks](#hooks)).
+The loop gathers before its first request, beside its own preselection when `preselect` asked for
+one, and nothing else of the host's can run beside those. A host with pre-turn work to overlap with
+the hooks — a compaction — calls `gather` itself, applies `withContext` to the current question as
+well, calls `notify` after, and passes no `hooks` (see [Hooks](#hooks)). Such a host passes the
+question as it was typed as `preselectQuery` too, or the preselector is shown the context in front
+of it and picks tools for what was recalled rather than what was asked.
 
 A host that stores its transcript — a row per message, so a crash or a stop mid-run still leaves
 readable history — gets each message as the loop appends it, and the run as it stood when the loop
@@ -1400,6 +1402,50 @@ a form can load it. Nothing in `src/` imports it — the same direction the conf
 what lets a document travel between hosts without the loop growing an opinion about where an agent
 comes from.
 
+### From a row, and back
+
+A document has one spelling of "inherit" — the field is absent — and a database row cannot leave a
+column out, so every host stores a marker instead: `""` for a text column, `-1` where zero is a real
+answer, the word `inherit` in an enum, `null` in a nullable one. `defineSpecColumns` is the table
+from those columns to the fields they feed, with each column's marker a parameter, so the projection
+is declared once rather than written out in both directions:
+
+```ts
+import { defineSpecColumns } from "@cubicecho/agent-core/spec/columns";
+
+const profile = defineSpecColumns<Agent>(
+  {
+    model: { path: "model.model", inherit: "" },
+    maxTokens: { path: "model.maxTokens", inherit: -1 },
+    temperature: { path: "model.temperature", inherit: null },
+    toolDiscovery: { path: "tools.discovery", inherit: "inherit" },
+    systemPrompt: { path: "prompt.system", inherit: "" },
+    compactionModel: { path: "tasks.compaction.model", inherit: "" },
+    toolExecution: { path: ["extensions", "com.example.host", "toolExecution"], inherit: "inherit" },
+  },
+  { handled: ["bundle", "tools.servers"] },
+);
+
+resolveAgentSpec([settings.toLayer(settingsRow), profile.toLayer(agentRow)]); // markers say nothing
+const row = profile.fromLayer(spec);   // an absent field comes back as its column's marker
+const lost = profile.dropped(spec);    // [{ path: "model.extraBody", value: {...} }, ...]
+```
+
+The table is keyed by column, so a column the row does not have, a marker of the wrong type and a
+path the format has no field at are all type errors. A column with no `inherit` says every value it
+holds, which is a host's bottom layer; `null` and `undefined` are absent whatever the marker. A
+column that stores something other than its field — a switch for a discovery mode — converts with
+`toSpec` and `fromSpec`, and either returning `undefined` says nothing: that is how a marker that
+is a range (a trimmed blank, any negative) is spelled, and how a column refuses a value it cannot
+hold. `prompt.<id>` is one part's text; an extension's reverse-domain key has dots of its own, so
+its path is written as segments.
+
+`dropped` is the import preview's list: what a document says that `fromLayer` will not keep, in the
+document's order, and never silently. A field with no column is reported at its path, a task or
+extension with nothing mapped in it whole, and a value a column's `fromSpec` refused carries that
+column's name. What the host reads by hand — a bundle, `tools.servers` resolved to its own row ids —
+goes in `handled` and is left out.
+
 ### Its side tasks
 
 `tasks.<key>` configures a side task apart from the main model — its own model, endpoint, ceiling,
@@ -1444,16 +1490,31 @@ with `tasks.compaction` writing the summary and no falling back to the main mode
 are off by default: a host that already calls `preselect` or compacts in `beforeStep` is not sent
 a second request.
 
+The preselector falls back to the main model. With neither `tasks.toolSelect` nor
+`toolSelectModel` naming one, `preselect: true` asks `config.model` on the agent's own endpoint at
+`preselect`'s defaults: a host that opted in has asked for a preselection, and an empty name is a
+setting nobody filled in. Compaction has no such fallback. A host that wants no preselection passes
+no `preselect`. A spec layer that declines the task with `model: ""` leaves it absent from the
+resolved agent, as one nobody configured is, so under `preselect: true` the main model is asked
+there too.
+
+What it asks about is the question as written: the last user message of `messages`, which the hooks'
+context never reaches because the loop puts that on the request. A host that put context on the
+question itself passes `preselectQuery`. The preselection and the hooks' `gather` run side by side,
+since neither reads the other, so asking for both costs the first request one round trip rather
+than two.
+
 What the loop picked it says twice. A `notice` event names the tools before the first `turn` event
 — `PRESELECTED_NOTICE` and then the names, comma-separated — and the result's `preselected` is the
 shortlist the run opened with, the host's own where it gave one and empty where nothing was picked.
 A run that fails carries it too, beside `loaded` and `used`.
 
-An empty `toolSelectModel` means no preselection, and says nothing about it. A host whose settings
-read `""` as "use the run's model" has to say so in the config it builds:
+Called directly, `preselect` reads an empty model as no preselection and says nothing about it; it
+is only the loop that falls back. A host calling it itself whose settings read `""` as "use the
+run's model" says so in the call:
 
 ```ts
-const config = { ...settings, toolSelectModel: settings.toolSelectModel || settings.model };
+await preselect(config, settings.toolSelectModel || settings.model, catalog, prompt, options);
 ```
 
 ```ts

package/dist/core/config.d.ts

@@ -148,7 +148,10 @@ export type ToolDiscovery = (typeof ToolDiscovery)[keyof typeof ToolDiscovery];
 export interface ToolPolicy {
     /** How tool definitions reach the model. */
     toolDiscovery: ToolDiscovery;
-    /** The model that does the preselection pass. Empty means don't preselect. */
+    /**
+     * The model that does the preselection pass. Empty means don't preselect, to `preselect` itself;
+     * `runAgentLoop`, asked to preselect, reads empty as the run's own `model`.
+     */
     toolSelectModel: string;
     /** Hard stop on runaway tool loops. */
     maxToolIterations: number;

package/dist/index.d.ts

@@ -26,6 +26,7 @@ export { preview, type ToolDispatch } from './run/run-calls.ts';
 export { resetAll } from './runtime/reset.ts';
 export { createRuntime, defaultRuntime, type Runtime, type RuntimeOptions } from './runtime/runtime.ts';
 export { CAPABILITY_SNAPSHOT_VERSION, type CapabilitySnapshot, type EndpointSnapshot, exportCapabilities, importCapabilities, type ModelSnapshot, } from './runtime/snapshot.ts';
+export { defineSpecColumns, type ExtensionPath, type SpecColumn, type SpecColumnMapping, type SpecColumns, type SpecColumnsOptions, type SpecDrop, type SpecPath, type SpecSection, } from './spec/columns.ts';
 export { AGENT_SPEC, AGENT_SPEC_VERSION, AGENT_TASKS, type AgentHook, type AgentSpec, type EndpointSpec, type ExportSpecOptions, exportSpec, findSpecSecrets, type ModelSpec, type ParsedSpec, type ParseSpecOptions, type PromptPart, parseSpec, REF_FILE, REF_URL, RESOLVED_DEFAULTS, type ResolvedAgent, type ResolvedTask, type RetrySpec, resolveAgentSpec, type SecretHint, SecretSign, SPEC_EVENTS, type SpecBundle, type SpecServer, type TaskSpec, type ToolsSpec, } from './spec/spec.ts';
 export type { CatalogServer } from './tools/catalog.ts';
 export { SERVER_INSTRUCTION_TOKENS, type ServerInstructionsOptions, serverInstructionsPrompt, } from './tools/instructions.ts';

package/dist/index.js

@@ -26,6 +26,7 @@ export { preview } from './run/run-calls.js';
 export { resetAll } from './runtime/reset.js';
 export { createRuntime, defaultRuntime } from './runtime/runtime.js';
 export { CAPABILITY_SNAPSHOT_VERSION, exportCapabilities, importCapabilities, } from './runtime/snapshot.js';
+export { defineSpecColumns, } from './spec/columns.js';
 export { AGENT_SPEC, AGENT_SPEC_VERSION, AGENT_TASKS, exportSpec, findSpecSecrets, parseSpec, REF_FILE, REF_URL, RESOLVED_DEFAULTS, resolveAgentSpec, SecretSign, SPEC_EVENTS, } from './spec/spec.js';
 export { SERVER_INSTRUCTION_TOKENS, serverInstructionsPrompt, } from './tools/instructions.js';
 export { PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselect, preselectByKeywords, preselectInput, preselection, preselectSystem, } from './tools/preselect.js';

package/dist/run/agent-loop.d.ts

@@ -43,9 +43,10 @@ export interface AgentLoopRequest {
  * The hooks a loop runs around one question. See `hooks.ts`.
  *
  * @remarks
- * The loop gathers before its first request and nothing else can run beside that, so a host with
- * pre-turn work of its own to overlap with the hooks — compaction, a preselection — calls `gather`
- * itself, puts the context on with `withContext`, calls `notify` after, and passes no `hooks`.
+ * The loop gathers before its first request, beside its own preselection where it was asked for
+ * one, and nothing else runs beside the two. A host with pre-turn work of its own to overlap with
+ * the hooks — a compaction — calls `gather` itself, puts the context on with `withContext`, calls
+ * `notify` after, passes no `hooks`, and hands `preselectQuery` the question as it was written.
  */
 export interface AgentLoopHooks {
     run: HookRunner;
@@ -109,7 +110,8 @@ export interface AgentLoopOptions {
      * @remarks
      * `tasks` is a resolved agent's, and is read only for the side tasks the loop was asked to run:
      * `tasks.toolSelect` under `preselect` and `tasks.compaction` under `compact`. `toolSelectModel`
-     * is the flattened spelling of the first, for a host that is not on the spec.
+     * is the flattened spelling of the first, for a host that is not on the spec. With neither
+     * naming a model, `preselect` asks `model` itself; `compact` never does.
      */
     config: Endpoint & ModelParams & Pick<ToolPolicy, 'maxToolIterations'> & Partial<Pick<ToolPolicy, 'toolDiscovery' | 'toolSelectModel'>> & Partial<RetryPolicy> & {
         contextLength?: number;
@@ -200,20 +202,37 @@ export interface AgentLoopOptions {
      * The preselector is `config.tasks.toolSelect` with everything it states — its endpoint, model,
      * ceiling, temperature and reasoning effort, keyed as `taskCall` keys a task against `config` —
      * and otherwise `config.toolSelectModel` on the config's own endpoint at `preselect`'s defaults.
-     * What it is asked about is the text of the last user message. Nothing is asked in eager mode,
-     * with neither preselector named, with no user message, or when `preselected` is given — an
-     * empty one included, which is how a host says it has already decided.
+     * With neither naming a model it is `config.model` itself, on the same terms as
+     * `toolSelectModel`: a host that opted in has asked for a preselection, and an empty name is a
+     * setting nobody filled in rather than a refusal. A host that wants none passes no `preselect`.
+     *
+     * What it is asked about is `preselectQuery`, and otherwise the text of the last user message as
+     * the host gave it — the hooks' context is put on the request, never on `messages`, so the
+     * tools are picked on what was asked rather than on what was recalled. Nothing is asked in eager
+     * mode, with no question, or when `preselected` is given — an empty one included, which is how
+     * a host says it has already decided.
      *
      * `true` takes `preselect`'s defaults; an object passes `keywords` and `maxPerLoad` through.
      * Its notices arrive as `notice` events, and a preselection that fails picks nothing rather
      * than ending the run. What it picked is a notice too, `PRESELECTED_NOTICE` and the names,
-     * before the first `turn` event, and is the result's `preselected`. It runs before the hooks
-     * gather, not beside them.
+     * before the first `turn` event, and is the result's `preselected`. It runs beside the hooks'
+     * `gather` rather than before it, since neither reads what the other returns, and the first
+     * request waits for both.
      */
     preselect?: boolean | {
         keywords?: boolean | KeywordPreselectOptions;
         maxPerLoad?: number;
     };
+    /**
+     * What the loop's own preselection is asked about, in place of the last user message's text.
+     * Read only under `preselect`.
+     *
+     * @remarks
+     * For a host that gathered its hooks itself and sent the question with `withContext` already on
+     * it: the loop cannot tell the context from the question, and a preselector shown both picks
+     * tools for whatever memory recalled. Blank asks nothing, as a blank question does.
+     */
+    preselectQuery?: string;
     /**
      * Has the loop fold the transcript itself before a step, once `planCompaction` says the window
      * is filling, with the summary written by `config.tasks.compaction` on its own settings. Off by

package/dist/run/agent-loop.js

@@ -218,17 +218,18 @@ const userText = (message) => {
  * name on its own endpoint where it does not.
  *
  * @param options - The run's options. Read for the config, the catalogue, the signal, what
- * `preselect` passes through, and the last user message, whose text is what is asked about.
+ * `preselect` passes through, and `preselectQuery` or else the last user message, whose text is
+ * what is asked about.
  * @param notice - Hears the preselector's notices, a failure among them.
- * @returns The names picked. Empty where there is no user message or its text is blank — nothing
+ * @returns The names picked. Empty where the query is blank or there is no user message — nothing
  * is asked — and where the preselection picked nothing or failed. An aborted request still rejects.
  *
  * @remarks
- * `preselect` answers an empty model with nothing, so a config that names neither asks nothing.
+ * With no preselector named the main model is asked, on the config's own endpoint.
  */
 async function chooseTools(options, notice) {
     const { config, catalog = [], signal } = options;
-    const prompt = userText(options.messages.findLast((message) => message.role === Role.User));
+    const prompt = options.preselectQuery ?? userText(options.messages.findLast((message) => message.role === Role.User));
     if (!prompt.trim()) {
         return [];
     }
@@ -239,7 +240,7 @@ async function chooseTools(options, notice) {
     };
     const selector = config.tasks?.toolSelect;
     if (!selector?.model) {
-        return preselect(config, config.toolSelectModel ?? '', catalog, prompt, asked);
+        return preselect(config, config.toolSelectModel || config.model, catalog, prompt, asked);
     }
     const call = taskCall(selector, asked, config);
     return preselect(call.endpoint, call.model, catalog, prompt, call.options);
@@ -494,6 +495,18 @@ async function runSteps(options, standing, pin) {
     // The host's own fields win over the pin's, so an explicit `cache_prompt: false` stays false.
     const extraBody = pin ? { ...pin.fields, ...config.extraBody } : config.extraBody;
     const sending = { ...config, extraBody };
+    // Started before the preselection rather than after it: neither reads the other, and in a row
+    // they cost the first request two round trips where one will do. A failing runner is a note, but
+    // a host's `onNote` that throws rejects the gather, perhaps while the preselection is still out:
+    // handled at once so that is no unhandled rejection, and still thrown below, where it always was.
+    const gathering = hooks
+        ? gather(hooks.run, hooks.events ?? [HookEvent.BeforeTurn], hooks.context, {
+            signal,
+            onNote: hooks.onNote,
+            maxTokens: hooks.maxTokens,
+        })
+        : Promise.resolve({ context: '', notes: [] });
+    gathering.catch(() => undefined);
     const { proxied, onDemand, loaded, preselected } = await discovery(options, notice);
     const instructions = serverInstructions === false
         ? ''
@@ -531,13 +544,7 @@ async function runSteps(options, standing, pin) {
     // hooks' context with it, which is right.
     const question = messages.findLast((message) => message.role === Role.User);
     const questionAt = () => (question ? messages.indexOf(question) : -1);
-    const gathered = hooks
-        ? await gather(hooks.run, hooks.events ?? [HookEvent.BeforeTurn], hooks.context, {
-            signal,
-            onNote: hooks.onNote,
-            maxTokens: hooks.maxTokens,
-        })
-        : { context: '', notes: [] };
+    const gathered = await gathering;
     // Read once, so what the result hands back is what every step of this run said.
     const preface = hooks?.preface ?? configureHooks().preface;
     const loads = { toolsLoaded: 0, redundantLoads: 0, unknownToolNames: 0 };

package/dist/spec/columns.d.ts

@@ -0,0 +1,162 @@
+import { type AgentSpec, type EndpointSpec, type ModelSpec, type RetrySpec, type TaskSpec, type ToolsSpec } from './spec.ts';
+/**
+ * A host's stored agent, read as a spec layer and written back: one table of columns, and the
+ * marker each column stores for "inherit".
+ *
+ * Every host with profiles had written this projection by hand, three times with three markers —
+ * `""` and `-1` and the word `inherit` in one, `null` in the next, none at all in the third — and
+ * the import half of it once more, with a list of what a row could not keep. The merge was already
+ * `resolveAgentSpec`; what each repeated was which column feeds which field, and how a column at
+ * its marker becomes a field the layer does not have, which is the only spelling of "inherit" a
+ * spec knows.
+ *
+ * Browser-safe for the reason `spec.ts` is: it imports that module and a guard, and nothing that
+ * needs Node, so a form can preview an import with it.
+ */
+/**
+ * Where in a spec a column lives, as a dotted path. A path the format has no field for does not
+ * typecheck.
+ *
+ * @remarks
+ * `prompt.<id>` is the text of the prompt part with that id, since a row holds a prompt as one
+ * string and a spec holds it as named layers. A task name is everything between `tasks.` and the
+ * next dot, so a task whose name has a dot in it cannot be addressed — nor can an extension's
+ * reverse-domain key, which is what `ExtensionPath` is for.
+ */
+export type SpecPath = 'id' | 'name' | 'description' | `endpoint.${keyof EndpointSpec}` | `model.${keyof ModelSpec}` | `prompt.${string}` | `tools.${keyof ToolsSpec}` | `retry.${keyof RetrySpec}` | `tasks.${string}.endpoint.${keyof EndpointSpec}` | `tasks.${string}.${Exclude<keyof TaskSpec, 'endpoint'>}`;
+/**
+ * A path into a host's own extension, as segments, because its key is a reverse domain and has
+ * dots of its own.
+ */
+export type ExtensionPath = readonly ['extensions', string, ...string[]];
+/** The top-level keys of a spec, for naming a whole section a host reads by hand. */
+export type SpecSection = '$schema' | 'id' | 'name' | 'description' | 'endpoint' | 'model' | 'prompt' | 'tools' | 'retry' | 'tasks' | 'hooks' | 'bundle' | 'extensions' | 'requires';
+/**
+ * One column: where its value lives in a spec, what it stores for "inherit", and how its value
+ * crosses when the column and the field do not hold the same thing.
+ *
+ * @typeParam Value - The column's own type, which `inherit` and both conversions are checked
+ * against.
+ */
+export interface SpecColumn<Value> {
+    path: SpecPath | ExtensionPath;
+    /**
+     * What the column stores for "say nothing here": a value at it is a field the layer leaves out,
+     * and a field the layer leaves out reads back as it. Compared with `===`. Left out, the column
+     * has no marker — every value it holds is said, which is a host's bottom layer — and an absent
+     * field leaves the column out of what `fromLayer` returns.
+     *
+     * @remarks
+     * `null` and `undefined` are absent whatever the marker is, as they are to `parseSpec`, so a
+     * nullable column needs no marker to inherit and `inherit: null` only adds the read-back.
+     */
+    inherit?: Value;
+    /**
+     * The column's value as the field holds it, for a column that stores something else — a switch
+     * for a mode, say. Called for a value that is neither absent nor the marker, and `undefined`
+     * back says nothing, which is how a marker that is a range rather than one value (a trimmed
+     * blank, any negative) is spelled. Left out, the value crosses as it is.
+     */
+    toSpec?: (value: Exclude<Value, null | undefined>) => unknown;
+    /**
+     * The field's value as the column would store it, or `undefined` where the column cannot hold
+     * it — which `fromLayer` writes as the marker and `dropped` reports against this column. Left
+     * out, the value crosses as `parseSpec` left it, and the path is what says its type.
+     */
+    fromSpec?: (value: unknown) => Value | undefined;
+}
+/**
+ * A row's columns, each mapped to a field: keyed by column, so a name the row does not have is an
+ * excess property and a marker of the wrong type does not typecheck.
+ *
+ * @typeParam Row - The stored row. Only the columns named here are read or written.
+ */
+export type SpecColumns<Row> = {
+    [Column in keyof Row]?: SpecColumn<Row[Column]>;
+};
+/** What `defineSpecColumns` takes besides the columns. */
+export interface SpecColumnsOptions {
+    /**
+     * What the host reads by hand, so `dropped` does not report it: a section (`bundle`), a path
+     * (`tools.servers`, where a list of slugs becomes a list of row ids) or an extension. `spec` is
+     * never reported, and needs no entry here.
+     */
+    handled?: readonly (SpecSection | SpecPath | `tasks.${string}` | ExtensionPath)[];
+}
+/** One thing a document says that a row will not keep. */
+export interface SpecDrop<Row> {
+    /** Where it is, in `parseSpec`'s spelling: `model.extraBody`, `prompt[1]`, `hooks[0]`. */
+    path: string;
+    /** What the document held there. */
+    value: unknown;
+    /**
+     * The column that refused it: present when there is a column for the field and its `fromSpec`
+     * could not store this value, absent when there is no column for the field at all.
+     */
+    column?: keyof Row;
+}
+/**
+ * A row's column table, both ways.
+ *
+ * @typeParam Row - The stored row.
+ */
+export interface SpecColumnMapping<Row> {
+    /**
+     * The row as a spec layer, saying only what the row says.
+     *
+     * @param row - The row, or any part of it: a column the row does not carry says nothing.
+     * @returns A layer holding every column that is neither absent nor at its marker. A section
+     * nothing was said in is left out, and the layer is not yet parsed.
+     */
+    toLayer(row: Partial<Row>): AgentSpec;
+    /**
+     * A spec layer as the row would store it.
+     *
+     * @param layer - A layer `parseSpec` has read, so each field is of its path's type.
+     * @returns Every mapped column: its field's value, or its marker where the field is absent or
+     * `fromSpec` refused it. A column with no marker is left out where its field is absent.
+     */
+    fromLayer(layer: AgentSpec): Partial<Row>;
+    /**
+     * What a spec says that `fromLayer` would not keep: a field with no column, and a value a column
+     * refused.
+     *
+     * @param spec - A layer `parseSpec` has read.
+     * @returns Each loss once, in the document's order. Empty when the row keeps everything.
+     *
+     * @remarks
+     * A field this format names is reported at its own path, a section with nothing mapped in it
+     * whole beneath that: an `extraBody` no column takes is one entry, not one per key. A prompt
+     * part is a column's when its id is, and its `ref` is reported, since a column holds a text.
+     */
+    dropped(spec: AgentSpec): SpecDrop<Row>[];
+}
+/**
+ * A column table from a stored row to a spec layer and back, with each column's "inherit" marker
+ * a parameter.
+ *
+ * @typeParam Row - The stored row: a settings row, a profile, an override layer.
+ * @param columns - Each mapped column, keyed by its name on the row.
+ * @param [options] - What the host reads by hand, outside the table.
+ * @returns `toLayer`, `fromLayer` and `dropped` over that one table.
+ * @throws When two columns write the same field, or one writes a section another writes inside.
+ *
+ * @example
+ * ```ts
+ * const profile = defineSpecColumns<Agent>({
+ *   model: { path: 'model.model', inherit: '' },
+ *   maxTokens: { path: 'model.maxTokens', inherit: -1 },
+ *   toolDiscovery: { path: 'tools.discovery', inherit: 'inherit' },
+ *   compactionModel: { path: 'tasks.compaction.model', inherit: '' },
+ *   toolExecution: { path: ['extensions', 'com.example.host', 'toolExecution'], inherit: 'inherit' },
+ * });
+ * resolveAgentSpec([settings.toLayer(row), profile.toLayer(agent)]);
+ * ```
+ *
+ * @remarks
+ * Keyed by column rather than by field, so the marker and the conversions are typed against that
+ * column's own type and a column cannot be mapped twice. A column feeds one field: a row that
+ * spreads one field over several columns, or a record column over many fields, reads that part by
+ * hand and names it in `handled`.
+ */
+export declare function defineSpecColumns<Row>(columns: SpecColumns<Row>, { handled }?: SpecColumnsOptions): SpecColumnMapping<Row>;

package/dist/spec/columns.js

@@ -0,0 +1,275 @@
+import { isRecord } from '../core/guards.js';
+import { AGENT_SPEC, } from './spec.js';
+/**
+ * The sections `dropped` always walks into, so a field the format names is reported at its own
+ * path. Anything deeper — one task, one extension — is walked into only where a column is mapped
+ * beneath it, and is otherwise reported whole: a side task this host does not run is one loss.
+ */
+const STRUCTURAL = ['endpoint', 'model', 'tools', 'retry', 'tasks', 'extensions'];
+/** The section whose entries are named layers of text, addressed by `prompt.<id>`. */
+const PROMPT = 'prompt';
+/** The section whose entries are hooks, which `dropped` reports one by one. */
+const HOOKS = 'hooks';
+/** The key every layer declares itself under, which belongs to no column. */
+const TOKEN = 'spec';
+/**
+ * Absent and null are the same thing, as they are to `parseSpec`.
+ *
+ * @param value - A column's or a field's value.
+ * @returns `true` for `undefined` and `null` only.
+ */
+const absent = (value) => value === undefined || value === null;
+/**
+ * A path as segments.
+ *
+ * @param path - A dotted path or an extension's segments.
+ * @returns The segments: a prompt id is one segment whatever it holds, and a task name the text up
+ * to the next dot.
+ */
+function segmentsOf(path) {
+    if (typeof path !== 'string') {
+        return path;
+    }
+    const prefix = `${PROMPT}.`;
+    if (path.startsWith(prefix)) {
+        return [PROMPT, path.slice(prefix.length)];
+    }
+    return path.split('.');
+}
+/**
+ * Whether one path is the other or lies beneath it.
+ *
+ * @param prefix - The shorter path.
+ * @param path - The path that may lie beneath it.
+ * @returns `true` when every segment of `prefix` begins `path`.
+ */
+const startsWith = (prefix, path) => prefix.length <= path.length && prefix.every((segment, index) => segment === path[index]);
+/**
+ * Whether two paths are the same segments.
+ *
+ * @param a - One path.
+ * @param b - The other.
+ * @returns `true` when they are the same length and agree throughout.
+ */
+const samePath = (a, b) => a.length === b.length && startsWith(a, b);
+/**
+ * The value at a path in a layer.
+ *
+ * @param layer - The layer.
+ * @param segments - Where to look. `['prompt', id]` reads that part's text.
+ * @returns What is there, or `undefined`.
+ */
+function read(layer, segments) {
+    if (segments[0] === PROMPT) {
+        return layer.prompt?.find((part) => part.id === segments[1])?.text;
+    }
+    let held = layer;
+    for (const segment of segments) {
+        if (isRecord(held) === false) {
+            return undefined;
+        }
+        held = held[segment];
+    }
+    return held;
+}
+/**
+ * Puts a value at a path in a layer being built, making the sections on the way.
+ *
+ * @param layer - The layer, as a plain object.
+ * @param segments - Where it goes. `['prompt', id]` appends a part.
+ * @param value - What goes there.
+ */
+function write(layer, segments, value) {
+    if (segments[0] === PROMPT) {
+        const parts = Array.isArray(layer.prompt) ? layer.prompt : [];
+        layer.prompt = [...parts, { id: segments[1], text: value }];
+        return;
+    }
+    let section = layer;
+    for (const segment of segments.slice(0, -1)) {
+        const next = section[segment];
+        section[segment] = isRecord(next) ? next : {};
+        section = section[segment];
+    }
+    section[segments[segments.length - 1]] = value;
+}
+/**
+ * Refuses a table that cannot be read both ways.
+ *
+ * @param entries - The table's columns.
+ * @throws When a path has an empty segment, or one column's path is another's or lies beneath it —
+ * two columns writing one field, or one writing a section another writes inside.
+ */
+function checkTable(entries) {
+    for (const [index, entry] of entries.entries()) {
+        if (entry.segments.some((segment) => segment === '')) {
+            throw new Error(`defineSpecColumns: ${String(entry.column)} has an empty segment in its path`);
+        }
+        for (const other of entries.slice(index + 1)) {
+            if (startsWith(entry.segments, other.segments) || startsWith(other.segments, entry.segments)) {
+                throw new Error(`defineSpecColumns: ${String(entry.column)} and ${String(other.column)} write the same field`);
+            }
+        }
+    }
+}
+/**
+ * A column table from a stored row to a spec layer and back, with each column's "inherit" marker
+ * a parameter.
+ *
+ * @typeParam Row - The stored row: a settings row, a profile, an override layer.
+ * @param columns - Each mapped column, keyed by its name on the row.
+ * @param [options] - What the host reads by hand, outside the table.
+ * @returns `toLayer`, `fromLayer` and `dropped` over that one table.
+ * @throws When two columns write the same field, or one writes a section another writes inside.
+ *
+ * @example
+ * ```ts
+ * const profile = defineSpecColumns<Agent>({
+ *   model: { path: 'model.model', inherit: '' },
+ *   maxTokens: { path: 'model.maxTokens', inherit: -1 },
+ *   toolDiscovery: { path: 'tools.discovery', inherit: 'inherit' },
+ *   compactionModel: { path: 'tasks.compaction.model', inherit: '' },
+ *   toolExecution: { path: ['extensions', 'com.example.host', 'toolExecution'], inherit: 'inherit' },
+ * });
+ * resolveAgentSpec([settings.toLayer(row), profile.toLayer(agent)]);
+ * ```
+ *
+ * @remarks
+ * Keyed by column rather than by field, so the marker and the conversions are typed against that
+ * column's own type and a column cannot be mapped twice. A column feeds one field: a row that
+ * spreads one field over several columns, or a record column over many fields, reads that part by
+ * hand and names it in `handled`.
+ */
+export function defineSpecColumns(columns, { handled = [] } = {}) {
+    const entries = [];
+    for (const column of Object.keys(columns)) {
+        const definition = columns[column];
+        if (definition) {
+            entries.push({ column, segments: segmentsOf(definition.path), hasMarker: 'inherit' in definition, definition });
+        }
+    }
+    checkTable(entries);
+    const handledPaths = handled.map(segmentsOf);
+    /**
+     * What a column stores for a field's value.
+     *
+     * @param entry - The column.
+     * @param value - The field's value, present.
+     * @returns The column's value, or `undefined` where it refused it.
+     */
+    const stored = (entry, value) => entry.definition.fromSpec ? entry.definition.fromSpec(value) : value;
+    return {
+        toLayer(row) {
+            const layer = { spec: AGENT_SPEC };
+            for (const { column, segments, hasMarker, definition } of entries) {
+                const value = row[column];
+                const inherits = absent(value) || (hasMarker && value === definition.inherit);
+                if (inherits) {
+                    continue;
+                }
+                const said = definition.toSpec ? definition.toSpec(value) : value;
+                if (absent(said) === false) {
+                    write(layer, segments, said);
+                }
+            }
+            // Built as a plain object because the paths are data; each field is the column's value, of
+            // its path's type when the host's `toSpec` says so, and `parseSpec` is the check on that.
+            return layer;
+        },
+        fromLayer(layer) {
+            const row = {};
+            for (const entry of entries) {
+                const value = read(layer, entry.segments);
+                const kept = absent(value) ? undefined : stored(entry, value);
+                if (kept !== undefined) {
+                    row[entry.column] = kept;
+                }
+                else if (entry.hasMarker) {
+                    row[entry.column] = entry.definition.inherit;
+                }
+            }
+            return row;
+        },
+        dropped(spec) {
+            const drops = [];
+            const isHandled = (path) => handledPaths.some((prefix) => startsWith(prefix, path));
+            const columnAt = (path) => entries.find((entry) => samePath(entry.segments, path));
+            const mappedBeneath = (path) => entries.some((entry) => entry.segments.length > path.length && startsWith(path, entry.segments));
+            const isStructural = (path) => path.length === 0 || (path.length === 1 && STRUCTURAL.includes(path[0]));
+            /**
+             * Reports a column's refusal of a value, if it refuses it.
+             *
+             * @param entry - The column at this path.
+             * @param path - The path as `parseSpec` spells it.
+             * @param value - The field's value, present.
+             */
+            const offer = (entry, path, value) => {
+                if (stored(entry, value) === undefined) {
+                    drops.push({ path, value, column: entry.column });
+                }
+            };
+            /**
+             * Reports every part of a prompt no column takes, and every reference one does.
+             *
+             * @param parts - The layer's prompt.
+             */
+            const walkPrompt = (parts) => {
+                for (const [index, part] of parts.entries()) {
+                    const path = [PROMPT, part.id];
+                    if (isHandled(path)) {
+                        continue;
+                    }
+                    const entry = columnAt(path);
+                    if (entry === undefined) {
+                        drops.push({ path: `${PROMPT}[${index}]`, value: part });
+                        continue;
+                    }
+                    if (absent(part.text) === false) {
+                        offer(entry, `${PROMPT}[${index}].text`, part.text);
+                    }
+                    if (part.ref) {
+                        drops.push({ path: `${PROMPT}[${index}].ref`, value: part.ref });
+                    }
+                }
+            };
+            /**
+             * Reports what lies at a path and is not kept, descending where something beneath is mapped.
+             *
+             * @param value - What the document holds at the path.
+             * @param path - Where it is, as segments.
+             */
+            const walk = (value, path) => {
+                if (absent(value) || isHandled(path)) {
+                    return;
+                }
+                const entry = columnAt(path);
+                if (entry) {
+                    offer(entry, path.join('.'), value);
+                    return;
+                }
+                if (path.length === 1 && path[0] === PROMPT && Array.isArray(value)) {
+                    walkPrompt(value);
+                    return;
+                }
+                if (path.length === 1 && path[0] === HOOKS && Array.isArray(value)) {
+                    for (const [index, hook] of value.entries()) {
+                        drops.push({ path: `${HOOKS}[${index}]`, value: hook });
+                    }
+                    return;
+                }
+                if (isRecord(value) && (isStructural(path) || mappedBeneath(path))) {
+                    for (const [key, held] of Object.entries(value)) {
+                        const isToken = path.length === 0 && key === TOKEN;
+                        if (isToken === false) {
+                            walk(held, [...path, key]);
+                        }
+                    }
+                    return;
+                }
+                drops.push({ path: path.join('.'), value });
+            };
+            walk(spec, []);
+            return drops;
+        },
+    };
+}

package/llms.txt

@@ -226,6 +226,20 @@ What endpoints and models refused, carried across a restart.
 - `importCapabilities` — Latches what a stored snapshot says was refused, on top of whatever this process has learned.
 - `ModelSnapshot` (type) — What one model on an endpoint refused.
 
+### columns
+
+A host's stored agent, read as a spec layer and written back: one table of columns, and the marker each column stores for "inherit".
+
+- `defineSpecColumns` — A column table from a stored row to a spec layer and back, with each column's "inherit" marker a parameter.
+- `ExtensionPath` (type) — A path into a host's own extension, as segments, because its key is a reverse domain and has dots of its own.
+- `SpecColumn` (type) — One column: where its value lives in a spec, what it stores for "inherit", and how its value crosses when the column and the field do not hold the same thing.
+- `SpecColumnMapping` (type) — A row's column table, both ways.
+- `SpecColumns` (type) — A row's columns, each mapped to a field: keyed by column, so a name the row does not have is an excess property and a marker of the wrong type does not typecheck.
+- `SpecColumnsOptions` (type) — What `defineSpecColumns` takes besides the columns.
+- `SpecDrop` (type) — One thing a document says that a row will not keep.
+- `SpecPath` (type) — Where in a spec a column lives, as a dotted path.
+- `SpecSection` (type) — The top-level keys of a spec, for naming a whole section a host reads by hand.
+
 ### spec
 
 A JSON document that defines an agent, and the rules for reading one.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubicecho/agent-core",
-  "version": "4.12.0",
+  "version": "4.14.0",
   "description": "The endpoint-agnostic half of an OpenAI-compatible agent loop: tool-schema compatibility, on-demand tool loading, one-shot side tasks, run events, and a pooled client.",
   "keywords": [
     "openai",
@@ -35,6 +35,10 @@
     "./spec": {
       "types": "./dist/spec/spec.d.ts",
       "import": "./dist/spec/spec.js"
+    },
+    "./spec/columns": {
+      "types": "./dist/spec/columns.d.ts",
+      "import": "./dist/spec/columns.js"
     }
   },
   "files": [