@jangts/agent-core 0.1.1 → 0.2.0

package/dist/cjs/kits/vector-search.js

@@ -3,52 +3,88 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.VectorSearch = void 0;
 const synchronous_js_1 = require("../utils/synchronous.js");
 const rules_js_1 = require("../utils/rules.js");
+/**
+ * Validate a vector and normalize it to unit length.
+ *
+ * Scaling by the largest component first keeps the squared sum inside the float range for
+ * long vectors, so normalization cannot overflow to Infinity.
+ */
 function normalize(vector, dimensions) {
     (0, rules_js_1.breakWhile)(!Array.isArray(vector) ||
         vector.length !== dimensions ||
-        Array.from(vector).some((n) => typeof n !== "number" || !Number.isFinite(n)), "Invalid vector dimensions or values");
+        Array.from(vector).some((n) => typeof n !== 'number' || !Number.isFinite(n)), 'Invalid vector dimensions or values');
     const scale = Math.max(...vector.map(Math.abs));
-    (0, rules_js_1.breakWhile)(scale === 0, "Zero vector cannot be searched");
+    (0, rules_js_1.breakWhile)(scale === 0, 'Zero vector cannot be searched');
     const norm = Math.sqrt(vector.reduce((sum, n) => sum + (n / scale) ** 2, 0));
     return Float32Array.from(vector, (n) => n / scale / norm);
 }
-/** Exact cosine search for a bounded embedded corpus. Identity and metadata are App-owned. */
+/**
+ * Exact cosine search for a bounded embedded corpus. Identity and metadata are App-owned.
+ *
+ * Vectors arrive as plain arrays and are stored normalized in `Float32Array` form, so query
+ * time only needs a dot product per candidate.
+ */
 class VectorSearch {
     entries = new Map();
+    /** The declared space; compare it before mixing vectors from another source. */
     space;
+    /**
+     * @param space - Non-blank identity and dimensions (1..16384) of the corpus.
+     * @throws TypeError When the space declaration is invalid.
+     */
     constructor(space) {
         (0, rules_js_1.breakWhile)(!space.identity?.trim() ||
             !Number.isSafeInteger(space.dimensions) ||
             space.dimensions < 1 ||
-            space.dimensions > 16384, "Invalid vector space");
+            space.dimensions > 16384, 'Invalid vector space');
         this.space = Object.freeze({ identity: space.identity, dimensions: space.dimensions });
     }
+    /**
+     * Insert or replace one document and its embedding.
+     *
+     * @param document - Document with a non-blank string `id`; it is cloned before being stored.
+     * @param vector - Raw vector for this space.
+     * @throws TypeError For a blank/missing id, a vector of the wrong width, a non-finite
+     *   component, or an all-zero vector (cosine is undefined for it).
+     */
     upsert({ document, vector }) {
-        (0, rules_js_1.breakWhile)(!document?.id?.trim(), "Invalid vector document id");
+        (0, rules_js_1.breakWhile)(!document?.id?.trim(), 'Invalid vector document id');
         this.entries.set(document.id, {
             document: structuredClone(document),
             vector: normalize(vector, this.space.dimensions),
         });
     }
+    /** Remove one document; returns whether it was present. */
     remove(id) {
         return this.entries.delete(id);
     }
+    /** Drop the whole corpus while keeping the declared space. */
     clear() {
         this.entries.clear();
     }
+    /**
+     * Score every candidate and return the best hits.
+     *
+     * @param options - Query vector plus limit, filter, minimum score and optional grouping.
+     * @returns At most `limit` hits, best score first, ties broken by id.
+     * @throws TypeError For an invalid limit, a missing filter, an out-of-range `minScore`, a
+     *   vector the space rejects, a non-synchronous filter or grouper, or a non-string group.
+     */
     search(options) {
         const { vector } = options;
         (0, rules_js_1.breakWhile)(!Number.isSafeInteger(options.limit) ||
             options.limit < 1 ||
             options.limit > 1000 ||
-            typeof options.filter !== "function" ||
+            typeof options.filter !== 'function' ||
             (options.minScore !== undefined &&
-                (!Number.isFinite(options.minScore) ||
-                    options.minScore < -1 ||
-                    options.minScore > 1)), "Invalid vector query");
+                (!Number.isFinite(options.minScore) || options.minScore < -1 || options.minScore > 1)), 'Invalid vector query');
         const query = normalize(vector, this.space.dimensions), groups = new Map();
         for (const [id, { document, vector: value }] of this.entries) {
-            const allowed = (0, synchronous_js_1.booleanResult)(options.filter(structuredClone(document)), 'Vector filters must be synchronous', 'Vector filters must return boolean');
+            // One isolated snapshot per candidate serves filter, grouping and the
+            // returned hit; filters and groupers are typed readonly, so sharing it
+            // removes the redundant clones without exposing the index.
+            const candidate = structuredClone(document);
+            const allowed = (0, synchronous_js_1.booleanResult)(options.filter(candidate), 'Vector filters must be synchronous', 'Vector filters must return boolean');
             if (!allowed)
                 continue;
             let score = 0;
@@ -57,18 +93,16 @@ class VectorSearch {
             score = Math.max(-1, Math.min(1, score));
             if (score < (options.minScore ?? -1))
                 continue;
-            const group = (0, synchronous_js_1.synchronous)(options.groupBy?.(structuredClone(document)), 'Vector grouping must be synchronous') ?? id;
+            const group = (0, synchronous_js_1.synchronous)(options.groupBy?.(candidate), 'Vector grouping must be synchronous') ?? id;
             if (typeof group !== 'string')
                 throw new TypeError('Vector groups must be strings');
             const prior = groups.get(group);
-            if (!prior ||
-                score > prior.score ||
-                (score === prior.score && id < prior.id))
-                groups.set(group, { id, score, document });
+            if (!prior || score > prior.score || (score === prior.score && id < prior.id))
+                groups.set(group, { id, score, document: candidate });
         }
         return [...groups.values()]
             .sort((a, b) => b.score - a.score || a.id.localeCompare(b.id))
-            .slice(0, options.limit).map(hit => ({ ...hit, document: structuredClone(hit.document) }));
+            .slice(0, options.limit);
     }
 }
 exports.VectorSearch = VectorSearch;

package/dist/cjs/mock/node.js

@@ -14,5 +14,11 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-// Node HTTP adapter for the optional Mock Kit.
+/**
+ * Node adapter of the optional Mock Kit (`@jangts/agent-core/mock/node`).
+ *
+ * Re-exports the mock-gpt Node surface only: server and request-handler creators plus their
+ * option types. It starts real HTTP servers and therefore requires a Node runtime. Core
+ * execution does not import it.
+ */
 __exportStar(require("@jangts/mock-gpt/node"), exports);

package/dist/cjs/mock/web.js

@@ -14,5 +14,11 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-// Web content sources for the optional Mock Kit.
+/**
+ * Web adapter of the optional Mock Kit (`@jangts/agent-core/mock/web`).
+ *
+ * Re-exports the mock-gpt web-content surface only: page sources, the public-address check and
+ * their option types. Fetching external pages needs a Node runtime with network access; Core
+ * execution does not import it.
+ */
 __exportStar(require("@jangts/mock-gpt/web"), exports);

package/dist/cjs/mock.js

@@ -14,5 +14,11 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-// Optional Mock Kit. Core execution does not import this entry.
+/**
+ * Optional Mock Kit entry: a configurable mock response SDK with optional API adapters.
+ *
+ * This file is a pass-through to `@jangts/mock-gpt`; Core execution never imports it, and it
+ * carries no production defaults. Platform-specific adapters live in `./mock/node.js` and
+ * `./mock/web.js`, which are separate subpath entries (`/mock/node`, `/mock/web`).
+ */
 __exportStar(require("@jangts/mock-gpt"), exports);

package/dist/cjs/model/binding.js

@@ -2,47 +2,98 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.compiledModelBinding = exports.modelBindingId = void 0;
 exports.snapshotModelBinding = snapshotModelBinding;
+/**
+ * Compile validated model settings into an immutable binding.
+ *
+ * The runner must not observe configuration changes after construction, so every
+ * option, callback and transport is snapshotted here — once per engine or runner.
+ * Lifecycle state (call counters, journals, budgets) stays outside the binding.
+ *
+ * Exports: the `ModelBinding` interface, the internal `modelBindingId` and
+ * `compiledModelBinding` symbols, and `snapshotModelBinding`.
+ */
 const defaults_js_1 = require("./defaults.js");
 const settings_js_1 = require("./settings.js");
 const transports_js_1 = require("./transports.js");
 const token_budget_js_1 = require("./token-budget.js");
-/** Only Core passes compiled definitions; not a public configuration alternative. */
+/**
+ * Brand carrying the configured model id through copy operations.
+ *
+ * Only Core passes compiled definitions; it is not a public configuration alternative.
+ */
 exports.modelBindingId = Symbol('model-binding-id');
+/** Escape hatch that lets the engine hand an already compiled binding to a runner. */
 exports.compiledModelBinding = Symbol('compiled-model-binding');
-/** Pin fixed configuration and canonical callbacks without cloning or freezing App services. */
+/**
+ * Compile runner options into a frozen binding.
+ *
+ * Fixed configuration and callbacks are pinned without cloning or freezing App services:
+ * providers and sinks stay live objects, only their method receivers are bound. Optional
+ * child limits are filled from the defaults before validation, and transports are
+ * normalized and checked for duplicate ids, including the built-in text transport.
+ *
+ * @param options - Runner options as supplied by the App or by the engine.
+ * @returns A frozen binding shared by every runner created from these options.
+ * @throws TypeError When child limits, the token budget or a transport is invalid.
+ * @throws ValidationError When the token budget contract is incomplete.
+ */
 function snapshotModelBinding(options) {
     const resolved = (0, settings_js_1.resolveModelSettings)(options);
-    if (options.children !== undefined && (!options.children || typeof options.children !== 'object' || Array.isArray(options.children)))
+    if (options.children !== undefined &&
+        (!options.children || typeof options.children !== 'object' || Array.isArray(options.children)))
         throw new TypeError('Invalid child execution policy');
     const sourceChildren = options.children;
     const children = Object.freeze({
-        maxDepth: sourceChildren?.maxDepth === undefined ? defaults_js_1.modelRunnerDefaults.children.maxDepth : sourceChildren.maxDepth,
-        maxConcurrentCalls: sourceChildren?.maxConcurrentCalls === undefined ? defaults_js_1.modelRunnerDefaults.children.maxConcurrentCalls : sourceChildren.maxConcurrentCalls,
-        maxChildren: sourceChildren?.maxChildren === undefined ? defaults_js_1.modelRunnerDefaults.children.maxChildren : sourceChildren.maxChildren,
+        maxDepth: sourceChildren?.maxDepth === undefined
+            ? defaults_js_1.modelRunnerDefaults.children.maxDepth
+            : sourceChildren.maxDepth,
+        maxConcurrentCalls: sourceChildren?.maxConcurrentCalls === undefined
+            ? defaults_js_1.modelRunnerDefaults.children.maxConcurrentCalls
+            : sourceChildren.maxConcurrentCalls,
+        maxChildren: sourceChildren?.maxChildren === undefined
+            ? defaults_js_1.modelRunnerDefaults.children.maxChildren
+            : sourceChildren.maxChildren,
     });
-    if (!Number.isSafeInteger(children.maxDepth) || children.maxDepth < 0
-        || !Number.isSafeInteger(children.maxConcurrentCalls) || children.maxConcurrentCalls < 1
-        || !Number.isSafeInteger(children.maxChildren) || children.maxChildren < 1)
+    if (!Number.isSafeInteger(children.maxDepth) ||
+        children.maxDepth < 0 ||
+        !Number.isSafeInteger(children.maxConcurrentCalls) ||
+        children.maxConcurrentCalls < 1 ||
+        !Number.isSafeInteger(children.maxChildren) ||
+        children.maxChildren < 1)
         throw new TypeError('Invalid child execution policy');
     const ports = resolved.ports;
     const sourceBudget = ports.tokenBudget;
     const countTokens = sourceBudget?.countTokens;
-    const tokenBudget = sourceBudget && Object.freeze({ counterId: sourceBudget.counterId,
-        contextWindowTokens: sourceBudget.contextWindowTokens, safetyMarginTokens: sourceBudget.safetyMarginTokens,
-        countTokens: typeof countTokens === 'function' ? countTokens.bind(sourceBudget) : countTokens });
+    const tokenBudget = sourceBudget &&
+        Object.freeze({
+            counterId: sourceBudget.counterId,
+            contextWindowTokens: sourceBudget.contextWindowTokens,
+            safetyMarginTokens: sourceBudget.safetyMarginTokens,
+            countTokens: typeof countTokens === 'function' ? countTokens.bind(sourceBudget) : countTokens,
+        });
     if (tokenBudget)
         (0, token_budget_js_1.validateModelTokenBudget)(tokenBudget);
     const ids = new Set([defaults_js_1.defaultTextTransport.id]);
-    const transports = Object.freeze((ports.transports ?? []).map(source => {
+    const transports = Object.freeze((ports.transports ?? []).map((source) => {
         const definition = (0, transports_js_1.normalizeModelTransport)(source);
         if (ids.has(definition.id))
             throw new TypeError('Invalid or duplicate model transport');
         ids.add(definition.id);
         return Object.freeze({ source, definition });
     }));
-    return Object.freeze({ provider: resolved.provider, config: resolved.config, children, maxInputChars: resolved.maxInputChars,
-        maxOutputTokens: resolved.maxOutputTokens, tokenBudget, transports,
-        ports: Object.freeze({ maxSchemaChars: ports.maxSchemaChars, onOutput: ports.onOutput,
-            inputBudgetError: ports.inputBudgetError, outputBudgetError: ports.outputBudgetError }),
+    return Object.freeze({
+        provider: resolved.provider,
+        config: resolved.config,
+        children,
+        maxInputChars: resolved.maxInputChars,
+        maxOutputTokens: resolved.maxOutputTokens,
+        tokenBudget,
+        transports,
+        ports: Object.freeze({
+            maxSchemaChars: ports.maxSchemaChars,
+            onOutput: ports.onOutput,
+            inputBudgetError: ports.inputBudgetError,
+            outputBudgetError: ports.outputBudgetError,
+        }),
     });
 }

package/dist/cjs/model/call-budget.js

@@ -1,26 +1,66 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parentModelBudget = exports.ModelCallBudget = void 0;
+/**
+ * Request-local model call accounting.
+ *
+ * A budget can have a parent, which makes sibling children compete for the same
+ * ancestor allowance. Charging is synchronous: there is no await between the check and
+ * the counter update, so two concurrent consumers cannot both spend the last call.
+ *
+ * Exports: `ModelCallBudget` and the `parentModelBudget` hand-off symbol.
+ */
 const errors_js_1 = require("../structs/errors.js");
 const rules_js_1 = require("../utils/rules.js");
-/** Request-local attempt ledger. Reservations leave capacity for ancestor delivery.
- * No await between checking and charging: sibling consumers cannot overspend. */
+/**
+ * Request-local attempt ledger.
+ *
+ * `reserve` is capacity kept available to the parent: a child with a reserve cannot
+ * consume the calls its ancestor still needs for its own turn.
+ */
 class ModelCallBudget {
     limit;
     parent;
     reserve;
     consumed = 0;
+    /**
+     * @param limit - Calls this ledger may consume; nonnegative safe integer.
+     * @param parent - Ancestor ledger charged alongside every local take.
+     * @param reserve - Calls of the parent's remaining capacity this ledger must leave untouched.
+     * @throws Error When `limit` or `reserve` is not a nonnegative safe integer.
+     */
     constructor(limit, parent, reserve = 0) {
         this.limit = limit;
         this.parent = parent;
         this.reserve = reserve;
         (0, rules_js_1.breakWhile)(!Number.isSafeInteger(limit) || limit < 0 || !Number.isSafeInteger(reserve) || reserve < 0, 'Invalid model call budget');
     }
-    get used() { return this.consumed; }
+    /** Calls already charged to this ledger only. */
+    get used() {
+        return this.consumed;
+    }
+    /** Calls still available after the local limit and the parent's reserve are applied. */
     get remaining() {
         return Math.max(0, Math.min(this.limit - this.consumed, this.parent ? this.parent.remaining - this.reserve : Infinity));
     }
-    child(limit, reserve) { return new ModelCallBudget(limit, this, reserve); }
+    /**
+     * Derive a child ledger that also charges this one.
+     *
+     * @param limit - Calls the child may consume.
+     * @param reserve - Calls of this ledger's remaining capacity the child must leave free.
+     * @returns A new ledger linked to this instance.
+     */
+    child(limit, reserve) {
+        return new ModelCallBudget(limit, this, reserve);
+    }
+    /**
+     * Charge one call to this ledger and every ancestor.
+     *
+     * The parent is charged first so a failure cannot leave the child counter advanced
+     * while the ancestor rejected the charge.
+     *
+     * @throws BudgetError When no call is available on this ledger or an ancestor.
+     */
     take() {
         (0, rules_js_1.breakWhile)(this.remaining < 1, () => new errors_js_1.BudgetError());
         this.parent?.take();
@@ -28,4 +68,5 @@ class ModelCallBudget {
     }
 }
 exports.ModelCallBudget = ModelCallBudget;
+/** Carries an inherited budget into a child runner that was not created by `child`. */
 exports.parentModelBudget = Symbol('parentModelBudget');

package/dist/cjs/model/decision-retry.js

@@ -1,8 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.retryMultipleModelCalls = retryMultipleModelCalls;
+/**
+ * Single retry point for rejected parallel model proposals.
+ *
+ * A provider may answer with more than one tool call. The protocol rejects that answer
+ * before any tool runs, so retrying is safe and must happen here — after a tool had
+ * executed, a retry could duplicate side effects.
+ *
+ * Exports: `retryMultipleModelCalls`.
+ */
 const errors_js_1 = require("../errors.js");
-/** Retry a rejected parallel proposal before any tool executes. The caller owns the fallback and its budget. */
+/**
+ * Retry once when the failure is a rejected multi-call proposal.
+ *
+ * Only the `MODEL_MULTIPLE_CALLS` code is retried; every other failure is rethrown
+ * unchanged. The caller owns the fallback prompt and the budget it consumes.
+ *
+ * @param request - `invoke` performs the first attempt; `retry` performs the fallback.
+ * @returns The first successful value.
+ * @throws The original error when it is not a multi-call rejection, or the fallback error.
+ */
 async function retryMultipleModelCalls(request) {
     try {
         return await request.invoke();

package/dist/cjs/model/defaults.js

@@ -1,13 +1,36 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.defaultTextTransport = exports.modelRunnerDefaults = void 0;
+/**
+ * Baseline model runtime limits.
+ *
+ * These are conservative runtime defaults, not a claim about any provider's context
+ * window; a host that knows its model must override them explicitly.
+ *
+ * Exports: `modelRunnerDefaults` and `defaultTextTransport`.
+ */
 const transports_js_1 = require("./transports.js");
-/** Baseline runtime limits, not a claim about any provider's context window. */
+/**
+ * Frozen default limits.
+ *
+ * `maxCalls` bounds one request's model calls, `callTimeoutMs` stays below the
+ * 32-bit timer limit, and the child limits cap fan-out per request. `stage` is the
+ * fallback stage id used when a call does not name one.
+ */
 exports.modelRunnerDefaults = Object.freeze({
-    maxCalls: 8, callTimeoutMs: 30000, maxInputChars: 32000,
-    maxOutputChars: 16000, maxSchemaChars: 16000, maxOutputTokens: 1024,
+    maxCalls: 8,
+    callTimeoutMs: 30000,
+    maxInputChars: 32000,
+    maxOutputChars: 16000,
+    maxSchemaChars: 16000,
+    maxOutputTokens: 1024,
     stage: 'model',
     children: Object.freeze({ maxDepth: 1, maxConcurrentCalls: 1, maxChildren: 32 }),
 });
-/** Core owns ordinary text execution; no App-side adapter is required. */
+/**
+ * Built-in plain-text transport.
+ *
+ * Core owns ordinary text execution, so no App-side adapter is required for the
+ * default single-prompt call shape.
+ */
 exports.defaultTextTransport = (0, transports_js_1.createPlainTextTransport)('core:plain-text');

package/dist/cjs/model/index.js

@@ -15,6 +15,13 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.modelRunnerDefaults = void 0;
+/**
+ * Public surface of the model protocol layer.
+ *
+ * Re-exports the runner, the provider and transport contracts, the interaction
+ * adapters and the defaults. Everything that interprets model output passes through
+ * this module, so consumers should not import the individual files.
+ */
 __exportStar(require("./runner.js"), exports);
 __exportStar(require("../structs/model/chat-provider.js"), exports);
 __exportStar(require("../support/model/compatible-provider.js"), exports);

package/dist/cjs/model/interactions/arguments.js

@@ -3,12 +3,38 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.object = object;
 exports.parse = parse;
 exports.wireName = wireName;
+/**
+ * Shared argument decoding for interaction adapters.
+ *
+ * Every adapter ultimately produces the same pair — capability id and argument
+ * object — so parsing, validation and wire naming live here instead of being repeated
+ * per wire format.
+ *
+ * Exports: `object`, `parse` and `wireName`.
+ */
 const model_protocol_js_1 = require("../../utils/model-protocol.js");
+/**
+ * Require a plain argument object.
+ *
+ * @param value - Candidate value.
+ * @returns The value typed as a string-keyed record.
+ * @throws ValidationError When the value is not a non-array object.
+ */
 function object(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         (0, model_protocol_js_1.modelProtocolError)('Model arguments must be an object');
     return value;
 }
+/**
+ * Parse a complete JSON argument payload.
+ *
+ * Incomplete JSON is rejected rather than repaired, because a truncated stream must not
+ * be executed as a plausible partial call.
+ *
+ * @param raw - Complete JSON text.
+ * @returns The parsed argument object.
+ * @throws ValidationError When the text is not complete JSON or not an object.
+ */
 function parse(raw) {
     let value;
     try {
@@ -19,7 +45,16 @@ function parse(raw) {
     }
     return object(value);
 }
-// Business IDs are not constrained by the wire protocol's naming alphabet/length.
+/**
+ * Map a business capability id onto a wire-safe function name.
+ *
+ * Business ids are not constrained by the wire protocol's naming alphabet or length, so
+ * an already valid id is returned unchanged and any other id is sanitized and suffixed
+ * with an FNV-1a hash. The hash keeps distinct ids distinct after sanitizing.
+ *
+ * @param id - Registered capability id.
+ * @returns A name matching the protocol's expected pattern.
+ */
 function wireName(id) {
     if (/^[a-zA-Z0-9_-]{1,64}$/.test(id))
         return id;

package/dist/cjs/model/interactions/json-object.js

@@ -1,32 +1,68 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.jsonObjectInteraction = void 0;
+/**
+ * Interaction adapter for providers without native tool calling.
+ *
+ * Instead of function declarations, the capability list is embedded in the instruction
+ * and the model must answer with one JSON envelope. The envelope belongs to this
+ * adapter, not to application messages, so switching adapters never changes App code.
+ *
+ * Exports: `jsonObjectInteraction`.
+ */
 const model_protocol_js_1 = require("../../utils/model-protocol.js");
 const arguments_js_1 = require("./arguments.js");
-/** Explicit alternative for providers without native calling. Its envelope belongs to this adapter, not to application messages. */
+/**
+ * Adapter that reads a single capability call out of a JSON object response.
+ *
+ * `strictArguments` is false because the wire format carries no schema enforcement; the
+ * adapter validates the envelope shape itself and leaves argument validation to the
+ * capability's own schema.
+ */
 exports.jsonObjectInteraction = Object.freeze({
     id: 'json-object',
     features: Object.freeze({ strictArguments: false }),
+    /**
+     * Build the instruction and response collector for one stage.
+     *
+     * @param capabilities - Capabilities registered for this stage; must be non-empty.
+     * @returns JSON mode options, the measured instruction and the collector factory.
+     */
     prepare(capabilities) {
-        const declarations = capabilities.map(({ id, description, inputSchema }) => ({ id, description, input: inputSchema.jsonSchema }));
+        const declarations = capabilities.map(({ id, description, inputSchema }) => ({
+            id,
+            description,
+            input: inputSchema.jsonSchema,
+        }));
         // Keep the wire shape after potentially long schemas so it cannot be mistaken
         // for a schema definition or a bare capability argument object.
-        const instruction = 'Registered capabilities: ' + JSON.stringify(declarations)
-            + '\nReturn exactly one JSON object with exactly these two fields: {"capability":"registered id","input":{...}}. '
-            + 'Choose capability from ' + JSON.stringify(capabilities.map(capability => capability.id))
-            + '; input is the chosen capability\'s actual argument object matching its input schema. '
-            + 'Do not return the schema, response_format, an array, multiple calls, prose or fences. The outer object must contain capability and input.';
+        const instruction = 'Registered capabilities: ' +
+            JSON.stringify(declarations) +
+            '\nReturn exactly one JSON object with exactly these two fields: {"capability":"registered id","input":{...}}. ' +
+            'Choose capability from ' +
+            JSON.stringify(capabilities.map((capability) => capability.id)) +
+            "; input is the chosen capability's actual argument object matching its input schema. " +
+            'Do not return the schema, response_format, an array, multiple calls, prose or fences. The outer object must contain capability and input.';
         return {
-            options: { json: true }, schemaChars: instruction.length, instruction,
+            options: { json: true },
+            schemaChars: instruction.length,
+            instruction,
             createResponse() {
                 let raw = '';
                 return {
-                    get outputChars() { return raw.length; },
-                    push(part) { if (typeof part !== 'string')
-                        (0, model_protocol_js_1.modelProtocolError)('JSON interaction does not accept native call events'); raw += part; },
+                    get outputChars() {
+                        return raw.length;
+                    },
+                    push(part) {
+                        if (typeof part !== 'string')
+                            (0, model_protocol_js_1.modelProtocolError)('JSON interaction does not accept native call events');
+                        raw += part;
+                    },
                     finish() {
                         const value = (0, arguments_js_1.parse)(raw);
-                        if (Object.keys(value).length !== 2 || typeof value.capability !== 'string' || !Object.hasOwn(value, 'input'))
+                        if (Object.keys(value).length !== 2 ||
+                            typeof value.capability !== 'string' ||
+                            !Object.hasOwn(value, 'input'))
                             (0, model_protocol_js_1.modelProtocolError)('Invalid model selection envelope');
                         return { capabilityId: value.capability, input: (0, arguments_js_1.object)(value.input) };
                     },