@cubicecho/agent-core 2.24.0 → 2.25.0

package/dist/spec.d.ts

@@ -1,5 +1,5 @@
-import type { AgentConfig, Endpoint } from "./config.ts";
-import { type HookEvent } from "./hook-events.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.
  *
@@ -25,13 +25,15 @@ 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: `HOOK_EVENTS`, under the name a document's reader knows.
  *
+ * @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.
@@ -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
@@ -175,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
@@ -186,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.
@@ -202,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.
  */
@@ -229,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
@@ -254,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[];
@@ -268,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.
@@ -283,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
@@ -307,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;