@jangts/agent-core 0.1.1 → 0.2.0

package/dist/esm/kits/vector-search.d.ts

@@ -1,29 +1,75 @@
+/**
+ * Vector Search Kit: exact cosine search over a small, App-owned embedded corpus.
+ *
+ * Place in the package: an optional App-side library. The Kit stores vectors and computes
+ * scores; embeddings, document identity, metadata and persistence stay with the App. The
+ * corpus is held in memory and scanned exhaustively, so it suits bounded sets only.
+ *
+ * Exports: `VectorSearch`, `VectorSearchSpace`, `VectorSearchQuery`, `VectorSearchHit`.
+ */
 import type { SearchHit } from '../structs/common.js';
+/** Embedding space identity and width; vectors from another space must never be mixed in. */
 export interface VectorSearchSpace {
+    /** Non-blank space name, for example `model@revision`; reported back by `VectorSearch`. */
     readonly identity: string;
+    /** Expected vector length, 1..16384. */
     readonly dimensions: number;
 }
+/** One search hit; the document is a cloned snapshot, not the indexed instance. */
 export interface VectorSearchHit<Document> extends SearchHit<Document> {
 }
+/** Search options excluding the query vector, which `search` takes alongside them. */
 export interface VectorSearchQuery<Document> {
+    /** Maximum hits returned, 1..1000. */
     readonly limit: number;
+    /** Synchronous predicate over a document snapshot; false excludes the candidate. */
     readonly filter: (document: Readonly<Document>) => boolean;
+    /** Minimum cosine score in [-1, 1]; defaults to -1, which keeps every candidate. */
     readonly minScore?: number;
+    /** Optional group key; only the best hit per group is kept, defaulting to the document id. */
     readonly groupBy?: (document: Readonly<Document>) => string;
 }
-/** 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.
+ */
 export declare class VectorSearch<Document extends {
     id: string;
 }> {
     private readonly entries;
+    /** The declared space; compare it before mixing vectors from another source. */
     readonly space: VectorSearchSpace;
+    /**
+     * @param space - Non-blank identity and dimensions (1..16384) of the corpus.
+     * @throws TypeError When the space declaration is invalid.
+     */
     constructor(space: VectorSearchSpace);
+    /**
+     * 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 }: {
         document: Document;
         vector: readonly number[];
     }): void;
+    /** Remove one document; returns whether it was present. */
     remove(id: string): boolean;
+    /** Drop the whole corpus while keeping the declared space. */
     clear(): void;
+    /**
+     * 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: VectorSearchQuery<Document> & {
         vector: readonly number[];
     }): VectorSearchHit<Document>[];

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

@@ -1,51 +1,87 @@
 import { synchronous, booleanResult } from '../utils/synchronous.js';
-import { breakWhile } from "../utils/rules.js";
+import { breakWhile } from '../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) {
     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));
-    breakWhile(scale === 0, "Zero vector cannot be searched");
+    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.
+ */
 export 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) {
         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 }) {
-        breakWhile(!document?.id?.trim(), "Invalid vector document id");
+        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;
         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 = 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 = booleanResult(options.filter(candidate), 'Vector filters must be synchronous', 'Vector filters must return boolean');
             if (!allowed)
                 continue;
             let score = 0;
@@ -54,17 +90,15 @@ export class VectorSearch {
             score = Math.max(-1, Math.min(1, score));
             if (score < (options.minScore ?? -1))
                 continue;
-            const group = synchronous(options.groupBy?.(structuredClone(document)), 'Vector grouping must be synchronous') ?? id;
+            const group = 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);
     }
 }

package/dist/esm/mock/node.d.ts

@@ -1 +1,8 @@
+/**
+ * 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.
+ */
 export * from '@jangts/mock-gpt/node';

package/dist/esm/mock/node.js

@@ -1,2 +1,8 @@
-// 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.
+ */
 export * from '@jangts/mock-gpt/node';

package/dist/esm/mock/web.d.ts

@@ -1 +1,8 @@
+/**
+ * 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.
+ */
 export * from '@jangts/mock-gpt/web';

package/dist/esm/mock/web.js

@@ -1,2 +1,8 @@
-// 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.
+ */
 export * from '@jangts/mock-gpt/web';

package/dist/esm/mock.d.ts

@@ -1 +1,8 @@
+/**
+ * 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`).
+ */
 export * from '@jangts/mock-gpt';

package/dist/esm/mock.js

@@ -1,2 +1,8 @@
-// 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`).
+ */
 export * from '@jangts/mock-gpt';

package/dist/esm/model/binding.d.ts

@@ -1,21 +1,50 @@
 import type { ModelRunnerOptions, ModelRunnerPorts, ModelRuntimeConfig, ModelTransportDefinition, ModelTokenBudget, ModelChildPolicy } from '../structs/model/runtime.js';
 import type { ChatProvider } from '../structs/model/chat-provider.js';
-/** Internal compiled definition; execution scope and mutable call state belong to each runner. */
+/**
+ * Internal compiled definition; execution scope and mutable call state belong to each runner.
+ */
 export interface ModelBinding {
+    /** Provider with its `stream` method already bound to the original receiver. */
     readonly provider: ChatProvider;
+    /** Frozen call limits and usage reporting switch. */
     readonly config: ModelRuntimeConfig;
+    /** Maximum characters of user/assistant message content per call. */
     readonly maxInputChars: number;
+    /** Default completion token request per call; overridable per call within limits. */
     readonly maxOutputTokens: number;
+    /** Output sink, diagnostics and budget-error hooks, with receivers bound. */
     readonly ports: ModelRunnerPorts;
+    /** Optional token accounting contract; absent when the host does not count tokens. */
     readonly tokenBudget?: ModelTokenBudget;
+    /** Registered transports paired with their original source definitions. */
     readonly transports: readonly {
+        /** Definition as supplied by the App; used as the identity key for typed lookups. */
         readonly source: ModelTransportDefinition;
+        /** Normalized, frozen definition actually executed. */
         readonly definition: ModelTransportDefinition;
     }[];
+    /** Child execution limits already merged with defaults and validated. */
     readonly children: Readonly<Required<ModelChildPolicy>>;
 }
-/** 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.
+ */
 export declare const modelBindingId: unique symbol;
+/** Escape hatch that lets the engine hand an already compiled binding to a runner. */
 export declare const compiledModelBinding: unique symbol;
-/** 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.
+ */
 export declare function snapshotModelBinding(options: ModelRunnerOptions): ModelBinding;

package/dist/esm/model/binding.js

@@ -1,44 +1,95 @@
+/**
+ * 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`.
+ */
 import { defaultTextTransport, modelRunnerDefaults } from './defaults.js';
 import { resolveModelSettings } from './settings.js';
 import { normalizeModelTransport } from './transports.js';
 import { validateModelTokenBudget } from './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.
+ */
 export const modelBindingId = Symbol('model-binding-id');
+/** Escape hatch that lets the engine hand an already compiled binding to a runner. */
 export const 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.
+ */
 export function snapshotModelBinding(options) {
     const resolved = 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 ? modelRunnerDefaults.children.maxDepth : sourceChildren.maxDepth,
-        maxConcurrentCalls: sourceChildren?.maxConcurrentCalls === undefined ? modelRunnerDefaults.children.maxConcurrentCalls : sourceChildren.maxConcurrentCalls,
-        maxChildren: sourceChildren?.maxChildren === undefined ? modelRunnerDefaults.children.maxChildren : sourceChildren.maxChildren,
+        maxDepth: sourceChildren?.maxDepth === undefined
+            ? modelRunnerDefaults.children.maxDepth
+            : sourceChildren.maxDepth,
+        maxConcurrentCalls: sourceChildren?.maxConcurrentCalls === undefined
+            ? modelRunnerDefaults.children.maxConcurrentCalls
+            : sourceChildren.maxConcurrentCalls,
+        maxChildren: sourceChildren?.maxChildren === undefined
+            ? 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)
         validateModelTokenBudget(tokenBudget);
     const ids = new Set([defaultTextTransport.id]);
-    const transports = Object.freeze((ports.transports ?? []).map(source => {
+    const transports = Object.freeze((ports.transports ?? []).map((source) => {
         const definition = 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/esm/model/call-budget.d.ts

@@ -1,14 +1,42 @@
-/** 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.
+ */
 export declare class ModelCallBudget {
     readonly limit: number;
     private readonly parent?;
     private readonly reserve;
     private consumed;
+    /**
+     * @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: number, parent?: ModelCallBudget | undefined, reserve?: number);
+    /** Calls already charged to this ledger only. */
     get used(): number;
+    /** Calls still available after the local limit and the parent's reserve are applied. */
     get remaining(): number;
+    /**
+     * 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: number, reserve: number): ModelCallBudget;
+    /**
+     * 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(): void;
 }
+/** Carries an inherited budget into a child runner that was not created by `child`. */
 export declare const parentModelBudget: unique symbol;

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

@@ -1,27 +1,68 @@
+/**
+ * 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.
+ */
 import { BudgetError } from '../structs/errors.js';
 import { breakWhile } from '../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.
+ */
 export 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;
         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() {
         breakWhile(this.remaining < 1, () => new BudgetError());
         this.parent?.take();
         this.consumed++;
     }
 }
+/** Carries an inherited budget into a child runner that was not created by `child`. */
 export const parentModelBudget = Symbol('parentModelBudget');

package/dist/esm/model/decision-retry.d.ts

@@ -1,4 +1,13 @@
-/** 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.
+ */
 export declare function retryMultipleModelCalls<Value>(request: {
     readonly invoke: () => Promise<Value>;
     readonly retry: (error: unknown) => Promise<Value>;

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

@@ -1,5 +1,23 @@
+/**
+ * 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`.
+ */
 import { getErrorInfo } from '../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.
+ */
 export async function retryMultipleModelCalls(request) {
     try {
         return await request.invoke();

package/dist/esm/model/defaults.d.ts

@@ -1,4 +1,10 @@
-/** 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.
+ */
 export declare const modelRunnerDefaults: Readonly<{
     maxCalls: 8;
     callTimeoutMs: 30000;
@@ -13,7 +19,12 @@ export declare const modelRunnerDefaults: Readonly<{
         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.
+ */
 export declare const defaultTextTransport: import("./runner.js").ModelTransportDefinition<string> & {
     readonly id: "core:plain-text";
 };

package/dist/esm/model/defaults.js

@@ -1,10 +1,33 @@
+/**
+ * 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`.
+ */
 import { createPlainTextTransport } from './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.
+ */
 export const 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.
+ */
 export const defaultTextTransport = createPlainTextTransport('core:plain-text');