@jangts/agent-core 0.1.1 → 0.2.0

package/development/skills/agent-core-app/scripts/prepare-source.mjs

@@ -1,3 +1,14 @@
+/*
+ * Prepare a knowledge candidate from a supplied source file.
+ *
+ * The script belongs to the App's development skills (开发技能). It never touches the
+ * active knowledge files: it validates the new document against the current catalog
+ * and writes a self-contained candidate directory that a later publication step can
+ * approve. The candidate records the base configuration hash and the revisions of the
+ * documents it was prepared against, so the publication can detect a stale base.
+ *
+ * Main exports: none. The file runs as a command and prints one JSON receipt.
+ */
 import { mkdir, writeFile } from 'node:fs/promises';
 import { resolve, join, sep } from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -8,17 +19,57 @@ import { readApplicationKnowledge, compileApplicationKnowledge } from './lib/kno
 const args = process.argv.slice(2);
 if (args.length !== 5 || args[1] !== '--source' || args[3] !== '--id')
   throw new Error('Usage: node prepare-source.mjs PROJECT --source UTF8_FILE --id DOCUMENT_ID');
-const project = resolve(args[0]), directory = pathToFileURL(project + sep);
+const project = resolve(args[0]),
+  // A trailing separator makes the directory a base URL, so relative entries
+  // resolve inside the project instead of against the file system root.
+  directory = pathToFileURL(project + sep);
 const { documents, policy, baseConfigSha256 } = await readApplicationKnowledge(directory);
-const previous = documents.find(item => item.id === args[4]);
-const source = await readSuppliedSource(resolve(args[2]), args[4], policy.maxDocumentBytes, previous?.locale);
-compileApplicationKnowledge([...documents.filter(item => item.id !== args[4]), source.document], policy);
-const target = join(project, '.local', 'knowledge-candidates', args[4].replace(/[^a-z0-9_.-]/g, '_') + '-' + randomUUID());
+// A document with the same id is replaced rather than added.
+const previous = documents.find((item) => item.id === args[4]);
+const source = await readSuppliedSource(
+  resolve(args[2]),
+  args[4],
+  policy.maxDocumentBytes,
+  // The locale of the replaced document is carried over, so the revision stays
+  // comparable across the replacement.
+  previous?.locale,
+);
+// The candidate must fit the catalog together with the other documents, so the
+// whole set is compiled before anything is written.
+compileApplicationKnowledge(
+  [...documents.filter((item) => item.id !== args[4]), source.document],
+  policy,
+);
+const target = join(
+  project,
+  '.local',
+  'knowledge-candidates',
+  // The random suffix keeps two candidates for the same document apart.
+  args[4].replace(/[^a-z0-9_.-]/g, '_') + '-' + randomUUID(),
+);
 await mkdir(target, { recursive: true });
+// `wx` fails instead of overwriting an existing file.
 await writeFile(join(target, 'source.knowledge.md'), source.bytes, { flag: 'wx' });
-await writeFile(join(target, 'proposal.json'), JSON.stringify({ schemaVersion: 1, status: 'candidate', document: args[4],
-  action: previous ? 'replace' : 'add', originalName: source.name, locale: source.document.locale,
-  contentSha256: source.digest, revision: source.document.revision, baseConfigSha256,
-  baseDocuments: documents.map(item => ({ id: item.id, revision: item.revision })), published: false,
-}, null, 2) + '\n', { flag: 'wx' });
+await writeFile(
+  join(target, 'proposal.json'),
+  JSON.stringify(
+    {
+      schemaVersion: 1,
+      status: 'candidate',
+      document: args[4],
+      action: previous ? 'replace' : 'add',
+      originalName: source.name,
+      locale: source.document.locale,
+      contentSha256: source.digest,
+      revision: source.document.revision,
+      baseConfigSha256,
+      baseDocuments: documents.map((item) => ({ id: item.id, revision: item.revision })),
+      published: false,
+    },
+    null,
+    2,
+  ) + '\n',
+  { flag: 'wx' },
+);
+// The receipt states that nothing was published and no active file was changed.
 console.log(JSON.stringify({ candidate: target, published: false, activeFilesChanged: false }));

package/development/skills/agent-core-app/scripts/resources.mjs

@@ -11,12 +11,17 @@ const assets = {
     'prepare-source': 'skills/agent-core-app/scripts/prepare-source.mjs',
   },
   docs: {
-    guide: 'docs/README.md', api: 'docs/api/README.md',
-    maintenance: 'docs/maintenance.md', flow: 'docs/flows/knowledge-maintenance.md',
-    gettingStarted: 'docs/getting-started.md', knowledge: 'docs/knowledge.md',
+    guide: 'docs/README.md',
+    api: 'docs/api/README.md',
+    maintenance: 'docs/maintenance.md',
+    flow: 'docs/flows/knowledge-maintenance.md',
+    gettingStarted: 'docs/getting-started.md',
+    knowledge: 'docs/knowledge.md',
     createApp: 'docs/create-app.md',
-    materials: 'docs/materials.md', memory: 'docs/memory-and-learning.md',
-    answering: 'docs/api/knowledge-answering.md', acceptance: 'docs/acceptance.md',
+    materials: 'docs/materials.md',
+    memory: 'docs/memory-and-learning.md',
+    answering: 'docs/api/knowledge-answering.md',
+    acceptance: 'docs/acceptance.md',
   },
 };
 
@@ -24,28 +29,37 @@ async function packageAt(directory) {
   try {
     const manifest = JSON.parse(await readFile(join(directory, 'package.json'), 'utf8'));
     return manifest.name === packageName ? manifest : undefined;
-  } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
 }
 
 async function installedPackage(project) {
   // Node resolves the public entry without loading it or evaluating App code.
   const require = createRequire(pathToFileURL(join(project, '__agent_core_resolution__.cjs')));
   let entry;
-  try { entry = require.resolve(packageName); }
-  catch (error) {
+  try {
+    entry = require.resolve(packageName);
+  } catch (error) {
     if (error.code !== 'MODULE_NOT_FOUND') throw error;
     // A broken installed entry must not silently select a different SDK version.
     for (const directory of require.resolve.paths(packageName) ?? []) {
-      try { await stat(join(directory, packageName)); }
-      catch (missing) { if (missing.code === 'ENOENT') continue; throw missing; }
+      try {
+        await stat(join(directory, packageName));
+      } catch (missing) {
+        if (missing.code === 'ENOENT') continue;
+        throw missing;
+      }
       throw error;
     }
     return;
   }
   for (let directory = dirname(entry); ; directory = dirname(directory)) {
     const manifest = await packageAt(directory);
-    if (manifest) return { root: directory, version: manifest.version, source: 'project-dependency' };
-    if (dirname(directory) === directory) throw new Error(`Cannot locate ${packageName} manifest for resolved entry ${entry}`);
+    if (manifest)
+      return { root: directory, version: manifest.version, source: 'project-dependency' };
+    if (dirname(directory) === directory)
+      throw new Error(`Cannot locate ${packageName} manifest for resolved entry ${entry}`);
   }
 }
 
@@ -60,16 +74,30 @@ export async function resolveSdkResources(project) {
   if (!sdk) {
     // Only the Skill distributed inside the SDK can use sibling assets.
     const root = fileURLToPath(new URL('../../../../', import.meta.url));
-    const bundled = resolve(fileURLToPath(import.meta.url)) === resolve(root, 'development/skills/agent-core-app/scripts/resources.mjs');
+    const bundled =
+      resolve(fileURLToPath(import.meta.url)) ===
+      resolve(root, 'development/skills/agent-core-app/scripts/resources.mjs');
     const manifest = bundled ? await packageAt(root) : undefined;
-    if (!manifest) throw new Error(`Cannot resolve ${packageName} from ${project}. Install the SDK and its real dependencies in the existing App, or use the Skill inside the distributed SDK.`);
+    if (!manifest)
+      throw new Error(
+        `Cannot resolve ${packageName} from ${project}. Install the SDK and its real dependencies in the existing App, or use the Skill inside the distributed SDK.`,
+      );
     sdk = { root, version: manifest.version, source: 'bundled-sdk' };
   }
   const resources = {};
   for (const [group, entries] of Object.entries(assets)) {
-    resources[group] = Object.fromEntries(await Promise.all(Object.entries(entries)
-      .map(async ([name, relative]) => [name, await requiredFile(sdk.root, relative)])));
+    resources[group] = Object.fromEntries(
+      await Promise.all(
+        Object.entries(entries).map(async ([name, relative]) => [
+          name,
+          await requiredFile(sdk.root, relative),
+        ]),
+      ),
+    );
   }
-  const knowledgeLoader = await requiredFile(sdk.root, 'skills/agent-core-app/scripts/lib/knowledge.mjs');
+  const knowledgeLoader = await requiredFile(
+    sdk.root,
+    'skills/agent-core-app/scripts/lib/knowledge.mjs',
+  );
   return { sdk, ...resources, knowledgeLoader };
 }

package/development/skills/agent-core-app/scripts/validate-knowledge.mjs

@@ -1,8 +1,25 @@
+/*
+ * Validate the active knowledge catalog of one project.
+ *
+ * The script belongs to the App's development skills (开发技能). It loads the App-owned
+ * configuration and document files, compiles them into a Knowledge catalog and reports
+ * the resulting document ids. An empty catalog is reported as a distinct status, so a
+ * project that has not received its first source is not confused with a broken one.
+ *
+ * Main exports: none. The file runs as a command and prints one JSON receipt.
+ */
 import { pathToFileURL } from 'node:url';
 import { resolve, sep } from 'node:path';
 import { loadApplicationKnowledge } from './lib/knowledge.mjs';
 
 if (process.argv.length !== 3) throw new Error('Usage: node validate-knowledge.mjs PROJECT');
+// A trailing separator turns the project path into a base URL, so the document
+// entries resolve inside the project directory.
 const directory = pathToFileURL(resolve(process.argv[2]) + sep);
 const catalog = await loadApplicationKnowledge(directory);
-console.log(JSON.stringify({ status: catalog.ids().length ? 'valid' : 'empty-awaiting-source', documents: catalog.ids() }));
+console.log(
+  JSON.stringify({
+    status: catalog.ids().length ? 'valid' : 'empty-awaiting-source',
+    documents: catalog.ids(),
+  }),
+);

package/development/skills/agent-core-app/templates/catalog.json

@@ -1,25 +1,39 @@
 {
   "schemaVersion": 1,
-  "templates": [{
-    "id": "node-ts",
-    "revision": "1",
-    "directory": "node-ts",
-    "files": [
-      { "origin": "template", "source": "package.json.tpl", "target": "package.json" },
-      { "origin": "template", "source": "tsconfig.json.tpl", "target": "tsconfig.json" },
-      { "origin": "template", "source": "gitignore.tpl", "target": ".gitignore" },
-      { "origin": "template", "source": "env.example.tpl", "target": ".env.example" },
-      { "origin": "template", "source": "README.md.tpl", "target": "README.md" },
-      { "origin": "template", "source": "src/config.ts.tpl", "target": "src/config.ts" },
-      { "origin": "template", "source": "src/app.ts.tpl", "target": "src/app.ts" },
-      { "origin": "template", "source": "src/catalog.ts.tpl", "target": "src/catalog.ts" },
-      { "origin": "template", "source": "src/handlers.ts.tpl", "target": "src/handlers.ts" },
-      { "origin": "template", "source": "src/model.ts.tpl", "target": "src/model.ts" },
-      { "origin": "template", "source": "scripts/knowledge.mjs.tpl", "target": "scripts/knowledge.mjs" },
-      { "origin": "skill", "source": "scripts/resources.mjs", "target": "scripts/sdk-resources.mjs" },
-      { "origin": "template", "source": "examples/ask.mjs.tpl", "target": "examples/ask.mjs" },
-      { "origin": "template", "source": "test/app.test.mjs.tpl", "target": "test/app.test.mjs" },
-      { "origin": "template", "source": "knowledge/knowledge.config.json.tpl", "target": "knowledge/knowledge.config.json" }
-    ]
-  }]
+  "templates": [
+    {
+      "id": "node-ts",
+      "revision": "1",
+      "directory": "node-ts",
+      "files": [
+        { "origin": "template", "source": "package.json.tpl", "target": "package.json" },
+        { "origin": "template", "source": "tsconfig.json.tpl", "target": "tsconfig.json" },
+        { "origin": "template", "source": "gitignore.tpl", "target": ".gitignore" },
+        { "origin": "template", "source": "env.example.tpl", "target": ".env.example" },
+        { "origin": "template", "source": "README.md.tpl", "target": "README.md" },
+        { "origin": "template", "source": "src/config.ts.tpl", "target": "src/config.ts" },
+        { "origin": "template", "source": "src/app.ts.tpl", "target": "src/app.ts" },
+        { "origin": "template", "source": "src/catalog.ts.tpl", "target": "src/catalog.ts" },
+        { "origin": "template", "source": "src/handlers.ts.tpl", "target": "src/handlers.ts" },
+        { "origin": "template", "source": "src/model.ts.tpl", "target": "src/model.ts" },
+        {
+          "origin": "template",
+          "source": "scripts/knowledge.mjs.tpl",
+          "target": "scripts/knowledge.mjs"
+        },
+        {
+          "origin": "skill",
+          "source": "scripts/resources.mjs",
+          "target": "scripts/sdk-resources.mjs"
+        },
+        { "origin": "template", "source": "examples/ask.mjs.tpl", "target": "examples/ask.mjs" },
+        { "origin": "template", "source": "test/app.test.mjs.tpl", "target": "test/app.test.mjs" },
+        {
+          "origin": "template",
+          "source": "knowledge/knowledge.config.json.tpl",
+          "target": "knowledge/knowledge.config.json"
+        }
+      ]
+    }
+  ]
 }

package/dist/cjs/capabilities/index.js

@@ -15,6 +15,19 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.commandSchema = exports.defineCommand = void 0;
+/**
+ * Capability registration surface: model capabilities, executable tools and host-selected
+ * invocations.
+ *
+ * These registries hold declarations only. Which capabilities a stage may use, whether a
+ * call is authorized, and what a payload means remain App decisions; this barrel provides
+ * the mechanisms that validate, seal and execute those declarations.
+ *
+ * Exports: the model capability registry (`model`), the executable tool registry and its
+ * sync/async invocation entry points (`tools`), host-selected invocation execution
+ * (`invocation`), and the Interaction Kit's protocol, command and handler definitions that
+ * shape and validate model-produced interactions.
+ */
 __exportStar(require("./model.js"), exports);
 __exportStar(require("./tools.js"), exports);
 __exportStar(require("./invocation.js"), exports);

package/dist/cjs/capabilities/invocation.js

@@ -1,31 +1,84 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.executeInvocation = executeInvocation;
+/**
+ * Execution of one host-selected synchronous invocation.
+ *
+ * An invocation is the smallest Core-owned unit of work: the App decides which handler to
+ * call and supplies payload and authorization facts, while this module runs the handler once,
+ * threads cancellation and diagnostics, and pairs an optional journal start with a receipt.
+ * Selection, authorization and retries stay outside.
+ *
+ * Exports: `executeInvocation` and the invocation contracts re-exported at the bottom.
+ */
 const invocation_js_1 = require("../utils/invocation.js");
 const synchronous_js_1 = require("../utils/synchronous.js");
 const index_js_1 = require("../diagnostics/index.js");
 const reporting_js_1 = require("../execution/reporting.js");
-/** Execute a host-selected synchronous call. Selection, authorization facts and payload shape stay outside. */
+/**
+ * Run one synchronous invocation and record its effects.
+ *
+ * @param invocation Handler whose `call` performs the work; its `id` becomes the tool id in
+ *   diagnostics and journal records.
+ * @param input Payload handed to the handler unchanged.
+ * @param context App context passed to the ports below; it is never inspected here.
+ * @param ports Per-context callbacks for diagnostics, cancellation, journalling and receipt
+ *   capture. All are optional: without them the handler still runs, just unrecorded.
+ * @returns Nothing. The outcome is conveyed through the journal receipt, when one is bound.
+ * @throws TypeError when the handler identity is missing, or when the handler returns a
+ *   promise despite the synchronous contract.
+ * @throws Whatever the handler throws, unchanged, including the abort error raised by the
+ *   signal checks.
+ */
 function executeInvocation(invocation, input, context, ports = {}) {
     const toolId = invocation.id;
+    // Identify the call before touching the ports: journal and diagnostics records cannot be
+    // reconciled with an anonymous handler.
     if (!toolId?.trim())
         throw new TypeError('Invalid invocation handler identity');
     const journal = ports.journal?.(context), id = (0, invocation_js_1.invocationId)(), startedAtMs = Date.now();
-    const diagnostics = ports.diagnostics?.(context)?.child(id, { invocationId: id, nodeRole: 'invocation', definitionKind: 'tool-invocation', definitionId: toolId, nodeId: toolId, nodeName: toolId, nodeKind: 'tool-invocation' });
-    const callId = journal?.beginTool({ toolId, input, invocation: { ...diagnostics?.identity, invocationId: id, startedAtMs } });
-    diagnostics?.emit('tool.call', () => ({ toolId, invocationId: id, ...(diagnostics?.enabled('tool.call', 'content') ? { input } : {}) }));
+    const diagnostics = ports.diagnostics?.(context)?.child(id, {
+        invocationId: id,
+        nodeRole: 'invocation',
+        definitionKind: 'tool-invocation',
+        definitionId: toolId,
+        nodeId: toolId,
+        nodeName: toolId,
+        nodeKind: 'tool-invocation',
+    });
+    const callId = journal?.beginTool({
+        toolId,
+        input,
+        invocation: { ...diagnostics?.identity, invocationId: id, startedAtMs },
+    });
+    diagnostics?.emit('tool.call', () => ({
+        toolId,
+        invocationId: id,
+        ...(diagnostics?.enabled('tool.call', 'content') ? { input } : {}),
+    }));
+    // Held outside the try block so the failure path can still tell cancellation from an error.
     let activeSignal;
     let reports;
     try {
         const checkpoint = ports.checkpoint?.(context);
-        const signal = activeSignal = ports.signal?.(context);
+        const signal = (activeSignal = ports.signal?.(context));
         signal?.throwIfAborted();
         reports = new reporting_js_1.NodeReports(diagnostics, signal, 'tool.result');
-        (0, synchronous_js_1.synchronous)(invocation.call(input, context, { mode: 'sync', invocationId: id, signal: signal ?? new AbortController().signal, diagnostics,
-            report: reports.report.bind(reports), createSubFlowLogger: reports.createSubFlowLogger.bind(reports) }), 'Invocation handlers must be synchronous');
+        // The helper rejects a promise and drains its rejection: a handler that turns async must
+        // fail here instead of escaping as an unhandled rejection.
+        (0, synchronous_js_1.synchronous)(invocation.call(input, context, {
+            mode: 'sync',
+            invocationId: id,
+            signal: signal ?? new AbortController().signal,
+            diagnostics,
+            report: reports.report.bind(reports),
+            createSubFlowLogger: reports.createSubFlowLogger.bind(reports),
+        }), 'Invocation handlers must be synchronous');
         ports.signal?.(context)?.throwIfAborted();
         if (callId) {
             const receipt = ports.receipt?.(context, checkpoint);
+            // Cancellation may have arrived while the handler or receipt ran; a successful record
+            // must not be committed for a request the host has already abandoned.
             ports.signal?.(context)?.throwIfAborted();
             journal.finishTool({ invocationId: callId, status: 'success', value: receipt });
         }
@@ -34,15 +87,32 @@ function executeInvocation(invocation, input, context, ports = {}) {
     }
     catch (error) {
         reports?.close();
-        diagnostics?.emit('tool.result', () => ({ toolId, invocationId: id, status: activeSignal?.aborted ? 'cancelled' : 'error', durationMs: Date.now() - startedAtMs, ...(diagnostics?.enabled('tool.result', 'content') ? { error: (0, index_js_1.diagnosticError)(error) } : {}) }), reports?.debug());
+        diagnostics?.emit('tool.result', () => ({
+            toolId,
+            invocationId: id,
+            status: activeSignal?.aborted ? 'cancelled' : 'error',
+            durationMs: Date.now() - startedAtMs,
+            ...(diagnostics?.enabled('tool.result', 'content')
+                ? { error: (0, index_js_1.diagnosticError)(error) }
+                : {}),
+        }), reports?.debug());
         try {
             if (callId)
-                journal.finishTool({ invocationId: callId, status: ports.signal?.(context)?.aborted ? 'cancelled' : 'error', value: ports.receiptError?.(error) });
+                journal.finishTool({
+                    invocationId: callId,
+                    // The signal, not the error shape, decides whether this counts as cancellation.
+                    status: ports.signal?.(context)?.aborted ? 'cancelled' : 'error',
+                    value: ports.receiptError?.(error),
+                });
+        }
+        catch {
+            /* Preserve the invocation failure if receipt recording also fails. */
         }
-        catch { /* Preserve the invocation failure if receipt recording also fails. */ }
         throw error;
     }
     finally {
+        // Closing is idempotent, so a port that throws on the success path still releases the
+        // reporting scope.
         reports?.close();
     }
 }

package/dist/cjs/capabilities/model.js

@@ -1,6 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ModelCapabilityRegistry = exports.modelProtocolError = void 0;
+/**
+ * Declarative catalog of model capabilities for a request or one stage projection.
+ *
+ * A capability pairs an id and description with an input schema and a synchronous resolver,
+ * letting stage code parse model-supplied arguments and produce a typed value. Registration
+ * snapshots the schema and pins the parser and resolver to their defining object, so later
+ * mutation on the host side cannot change what a stage advertises.
+ *
+ * The registry is mutable until `seal()`. `select()` derives a sealed subset for a stage and
+ * shares the already-frozen entries rather than re-validating or re-wrapping them.
+ *
+ * Exports: `ModelCapabilityRegistry`, `modelProtocolError`, and the capability types.
+ */
 const synchronous_js_1 = require("../utils/synchronous.js");
 const model_protocol_js_1 = require("../utils/model-protocol.js");
 const schema_adapter_js_1 = require("../utils/schema-adapter.js");
@@ -8,40 +21,127 @@ var model_protocol_js_2 = require("../utils/model-protocol.js");
 Object.defineProperty(exports, "modelProtocolError", { enumerable: true, get: function () { return model_protocol_js_2.modelProtocolError; } });
 /** A request/stage projection is a sealed registry. Hosts filter availability before projection. */
 class ModelCapabilityRegistry {
+    /** Insertion-ordered entries; iteration order is the declaration order of the catalog. */
     definitionsById = new Map();
+    /** Sealing is one-way: stage-time code must never extend the catalog it is executing. */
     sealed = false;
+    /**
+     * @param definitions Capabilities to register immediately, in iteration order.
+     * @throws TypeError when a definition is invalid or its id is duplicated (raised by
+     *   `register`).
+     */
     constructor(definitions = []) {
         for (const definition of definitions)
             this.register(definition);
     }
+    /**
+     * Register one capability.
+     *
+     * @param capability Declaration with a non-empty unique id, non-empty description, an
+     *   object-rooted JSON schema and a resolver.
+     * @returns This registry, for chaining.
+     * @throws Error when the registry is already sealed.
+     * @throws TypeError when the declaration is invalid or its id is already registered.
+     */
     register(capability) {
         if (this.sealed)
             throw new Error('Model capability registry is sealed');
+        // Model arguments are always a JSON object, so a non-object root can never validate.
         const schema = capability.inputSchema?.jsonSchema;
-        if (!capability.id?.trim() || !capability.description?.trim() || schema?.type !== 'object'
-            || typeof capability.resolve !== 'function' || this.definitionsById.has(capability.id))
+        if (!capability.id?.trim() ||
+            !capability.description?.trim() ||
+            schema?.type !== 'object' ||
+            typeof capability.resolve !== 'function' ||
+            this.definitionsById.has(capability.id))
             throw new TypeError('Invalid or duplicate model capability');
+        // Clone and freeze the schema, and pin `parse`, so the stored entry is independent of
+        // the definition object the host may keep mutating.
         const inputSchema = (0, schema_adapter_js_1.snapshotSchemaAdapter)(capability.inputSchema, 'Model input parsers must be synchronous');
         const resolver = capability.resolve.bind(capability);
+        // Bind once here: a later caller cannot substitute its own receiver for the resolver.
         const resolve = (value, context) => (0, synchronous_js_1.synchronous)(resolver(value, context), 'Model capability resolvers must be synchronous');
-        this.definitionsById.set(capability.id, Object.freeze({ id: capability.id, description: capability.description, inputSchema, resolve }));
+        this.definitionsById.set(capability.id, Object.freeze({
+            id: capability.id,
+            description: capability.description,
+            inputSchema,
+            resolve,
+        }));
         return this;
     }
-    get definitions() { return Object.freeze([...this.definitionsById.values()]); }
-    ids() { return Object.freeze([...this.definitionsById.keys()]); }
-    entries() { return this.definitionsById.entries(); }
-    registerAll(definitions) { for (const definition of definitions)
-        this.register(definition); return this; }
+    /** Frozen snapshot of the registered definitions, in insertion order. */
+    get definitions() {
+        return Object.freeze([...this.definitionsById.values()]);
+    }
+    /** Registered ids in declaration order. */
+    ids() {
+        return Object.freeze([...this.definitionsById.keys()]);
+    }
+    /** Live iterator over `[id, definition]` pairs; it reflects only entries added before sealing. */
+    entries() {
+        return this.definitionsById.entries();
+    }
+    /**
+     * Register several capabilities.
+     *
+     * @param definitions Declarations applied in iteration order.
+     * @returns This registry, for chaining.
+     * @throws Error or TypeError under the same conditions as `register`.
+     */
+    registerAll(definitions) {
+        for (const definition of definitions)
+            this.register(definition);
+        return this;
+    }
+    /**
+     * @param id Capability id.
+     * @returns The registered definition.
+     * @throws TypeError when the id is not registered, which usually means a stage projection
+     *   omitted it.
+     */
     require(id) {
         const capability = this.get(id);
         if (!capability)
             throw new TypeError(`Unknown model capability: ${id}`);
         return capability;
     }
-    has(id) { return this.definitionsById.has(id); }
-    get(id) { return this.definitionsById.get(id); }
-    values() { return this.definitionsById.values(); }
-    seal() { this.sealed = true; return this; }
+    /**
+     * @param id Capability id.
+     * @returns Whether the id is registered in this registry.
+     */
+    has(id) {
+        return this.definitionsById.has(id);
+    }
+    /**
+     * @param id Capability id.
+     * @returns The registered definition, or undefined when absent.
+     */
+    get(id) {
+        return this.definitionsById.get(id);
+    }
+    /** Live iterator over the registered definitions. */
+    values() {
+        return this.definitionsById.values();
+    }
+    /**
+     * Close the registry to further registration.
+     *
+     * Sealing is idempotent and does not affect existing entries.
+     *
+     * @returns This registry.
+     */
+    seal() {
+        this.sealed = true;
+        return this;
+    }
+    /**
+     * Derive a sealed sub-catalog for one stage.
+     *
+     * @param ids Capability ids available in the stage, in projection order. Must be non-empty
+     *   and free of duplicates.
+     * @returns A new sealed registry that reuses the immutable entries of this registry.
+     * @throws TypeError when the selection is empty or contains a duplicate id.
+     * @throws Error when an id was never registered.
+     */
     select(ids) {
         if (!ids.length || new Set(ids).size !== ids.length)
             throw new TypeError('Invalid capability selection');
@@ -57,9 +157,22 @@ class ModelCapabilityRegistry {
         }
         return selected.seal();
     }
+    /**
+     * Parse model-supplied arguments and run the selected capability.
+     *
+     * @param selection Capability id plus the raw `input` object produced by the model. Other
+     *   fields, such as the originating call, are not interpreted here.
+     * @param context Stage identity handed to the resolver.
+     * @returns The resolver output.
+     * @throws ValidationError when the capability is unavailable in this registry or the input
+     *   is not a plain object; parser and resolver failures propagate unchanged.
+     */
     resolve(selection, context) {
         const { stageId } = context;
-        const capability = this.definitionsById.get(selection.capabilityId) ?? (0, model_protocol_js_1.modelProtocolError)('Model capability is unavailable in this stage');
+        // Model output is untrusted: unknown ids and non-object arguments are protocol failures,
+        // not ordinary `undefined` results.
+        const capability = this.definitionsById.get(selection.capabilityId) ??
+            (0, model_protocol_js_1.modelProtocolError)('Model capability is unavailable in this stage');
         if (!selection.input || typeof selection.input !== 'object' || Array.isArray(selection.input))
             (0, model_protocol_js_1.modelProtocolError)('Model capability input must be an object');
         return (0, synchronous_js_1.synchronous)(capability.resolve(capability.inputSchema.parse(selection.input), { stageId }), 'Model capability parsers must be synchronous');