@jangts/agent-core 0.1.0 → 0.2.0

package/dist/esm/model/selection-transport.d.ts

@@ -1,6 +1,19 @@
 import type { ModelTransportRegistration } from '../structs/model/interactions.js';
 import type { ModelTransportDefinition } from '../structs/model/runtime.js';
-/** The transport translates a wire selection into the single Core response protocol. */
+/**
+ * Compose a registered selection transport.
+ *
+ * The capability source may be a static catalog or a function of the stage id; the
+ * resulting definitions are captured when `prepare` runs and are used both to build
+ * the instruction and to reject unknown capability ids at finish time.
+ *
+ * `requireStrictArguments` is a registration-time assertion: a transport cannot demand
+ * strict arguments from an adapter that does not support them.
+ *
+ * @param registration - Adapter, capability source, options and the transport id.
+ * @returns A frozen transport definition whose result is the resolved capability output.
+ * @throws TypeError When strict arguments are unsupported or preparation is invalid.
+ */
 export declare function createModelTransport<Result, const Id extends string = string>(registration: ModelTransportRegistration<Result> & {
     readonly id: Id;
 }): ModelTransportDefinition<Result> & {

package/dist/esm/model/selection-transport.js

@@ -1,34 +1,74 @@
+/**
+ * Adapt an interaction adapter plus capability catalog into a transport.
+ *
+ * This is the seam between "how a provider expresses a call" and "what the core
+ * accepts": whatever the wire format, the transport must yield one capability id and
+ * one argument object. Capability availability is checked against the catalog captured
+ * at preparation time, so a late registration cannot be called.
+ *
+ * Exports: `createModelTransport`.
+ */
 import { synchronous } from '../utils/synchronous.js';
 import { nativeFunctionInteraction } from './interactions/native-functions.js';
 import { snapshotModelOptions } from './options.js';
 import { modelProtocolError } from '../utils/model-protocol.js';
-/** The transport translates a wire selection into the single Core response protocol. */
+/**
+ * Compose a registered selection transport.
+ *
+ * The capability source may be a static catalog or a function of the stage id; the
+ * resulting definitions are captured when `prepare` runs and are used both to build
+ * the instruction and to reject unknown capability ids at finish time.
+ *
+ * `requireStrictArguments` is a registration-time assertion: a transport cannot demand
+ * strict arguments from an adapter that does not support them.
+ *
+ * @param registration - Adapter, capability source, options and the transport id.
+ * @returns A frozen transport definition whose result is the resolved capability output.
+ * @throws TypeError When strict arguments are unsupported or preparation is invalid.
+ */
 export function createModelTransport(registration) {
     const adapter = registration.adapter ?? nativeFunctionInteraction;
     if (registration.requireStrictArguments && !adapter.features.strictArguments)
         throw new TypeError(`Model interaction does not support strict arguments: ${adapter.id}`);
     const source = registration.capabilities, createSource = typeof source === 'function' ? source.bind(registration) : undefined;
     const prepare = adapter.prepare.bind(adapter), options = Object.freeze(snapshotModelOptions(registration.options));
-    return Object.freeze({ id: registration.id, prepare(stageId) {
-            const catalog = createSource ? synchronous(createSource(stageId), 'Model capability sources must be synchronous') : source;
+    return Object.freeze({
+        id: registration.id,
+        prepare(stageId) {
+            const catalog = createSource
+                ? synchronous(createSource(stageId), 'Model capability sources must be synchronous')
+                : source;
             const definitions = [...catalog.values()];
             if (!definitions.length)
                 throw new TypeError('Model stage requires registered capabilities');
-            const capabilityIds = new Set(definitions.map(capability => capability.id));
+            const capabilityIds = new Set(definitions.map((capability) => capability.id));
             const prepared = synchronous(prepare(definitions), 'Model interaction preparation must be synchronous');
             const createResponse = prepared.createResponse.bind(prepared), resolve = catalog.resolve.bind(catalog);
-            return { options: { ...options, ...snapshotModelOptions(prepared.options) }, schemaChars: prepared.schemaChars, instruction: prepared.instruction,
+            return {
+                options: { ...options, ...snapshotModelOptions(prepared.options) },
+                schemaChars: prepared.schemaChars,
+                instruction: prepared.instruction,
                 createResponse() {
                     const buffer = createResponse();
                     let call;
-                    return { get outputChars() { return buffer.outputChars; }, get call() { return call; }, push: buffer.push.bind(buffer), finish() {
+                    return {
+                        get outputChars() {
+                            return buffer.outputChars;
+                        },
+                        get call() {
+                            return call;
+                        },
+                        push: buffer.push.bind(buffer),
+                        finish() {
                             const selection = synchronous(buffer.finish(), 'Model selection parsers must be synchronous');
                             call = selection.call;
                             if (!capabilityIds.has(selection.capabilityId))
                                 modelProtocolError('Model capability is unavailable in this prepared call');
                             return synchronous(resolve(selection, { stageId }), 'Model result parsers must be synchronous');
-                        } };
+                        },
+                    };
                 },
             };
-        } });
+        },
+    });
 }

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

@@ -1,5 +1,16 @@
 import type { ModelRunnerOptions, ModelRunnerPorts, ModelRuntimeConfig } from '../structs/model/runtime.js';
 import type { ChatProvider } from '../structs/model/chat-provider.js';
+/**
+ * Validate options and fill in baseline defaults.
+ *
+ * Legacy names (`config`, `ports`, `observe`, `signal`, `contextPolicy` and friends) are
+ * rejected rather than ignored, because silently dropping them would change behavior.
+ * Returned limits are frozen; ports keep live App callbacks with their receivers bound.
+ *
+ * @param options - Runner options as supplied by the App.
+ * @returns The bound provider, frozen runtime config, input limit, ports and token limit.
+ * @throws TypeError When any option is invalid, removed or out of range.
+ */
 export declare function resolveModelSettings(options: ModelRunnerOptions): {
     provider: ChatProvider;
     config: ModelRuntimeConfig;

package/dist/esm/model/settings.js

@@ -1,6 +1,26 @@
+/**
+ * Validation and defaulting of model runner settings.
+ *
+ * This is the single place where App-supplied settings become trusted: removed option
+ * names are rejected with a migration hint, defaults are applied, and every numeric
+ * limit is range-checked before the runner binds its provider.
+ *
+ * Exports: `resolveModelSettings`.
+ */
 import { modelRunnerDefaults } from './defaults.js';
 import { breakWhile } from '../utils/rules.js';
 import { recordErrorContext } from '../errors.js';
+/**
+ * Validate options and fill in baseline defaults.
+ *
+ * Legacy names (`config`, `ports`, `observe`, `signal`, `contextPolicy` and friends) are
+ * rejected rather than ignored, because silently dropping them would change behavior.
+ * Returned limits are frozen; ports keep live App callbacks with their receivers bound.
+ *
+ * @param options - Runner options as supplied by the App.
+ * @returns The bound provider, frozen runtime config, input limit, ports and token limit.
+ * @throws TypeError When any option is invalid, removed or out of range.
+ */
 export function resolveModelSettings(options) {
     const provider = options.provider;
     const stream = provider?.stream;
@@ -11,8 +31,16 @@ export function resolveModelSettings(options) {
     };
     breakWhile([
         { occur: typeof stream !== 'function', error: () => invalid('provider.stream is required') },
-        { occur: 'contextPolicy' in options || 'contextCompressors' in options || 'contextSelectors' in options, error: () => invalid('Configure context processing with explicit Workflow nodes') },
-        { occur: 'config' in options || 'ports' in options || 'observe' in options, error: () => invalid('Use named model settings and execution, sink, observe or errors') },
+        {
+            occur: 'contextPolicy' in options ||
+                'contextCompressors' in options ||
+                'contextSelectors' in options,
+            error: () => invalid('Configure context processing with explicit Workflow nodes'),
+        },
+        {
+            occur: 'config' in options || 'ports' in options || 'observe' in options,
+            error: () => invalid('Use named model settings and execution, sink, observe or errors'),
+        },
     ]);
     const defaulted = (value, fallback) => value === undefined ? fallback : value;
     const config = {
@@ -22,8 +50,10 @@ export function resolveModelSettings(options) {
         usage: options.usage,
     };
     const ports = {
-        transports: options.transports, diagnostics: options.execution?.diagnostics,
-        maxSchemaChars: options.maxSchemaChars, tokenBudget: options.tokenBudget,
+        transports: options.transports,
+        diagnostics: options.execution?.diagnostics,
+        maxSchemaChars: options.maxSchemaChars,
+        tokenBudget: options.tokenBudget,
         onOutput: options.sink?.output?.bind(options.sink),
         inputBudgetError: options.errors?.inputBudget?.bind(options.errors),
         outputBudgetError: options.errors?.outputBudget?.bind(options.errors),
@@ -32,15 +62,39 @@ export function resolveModelSettings(options) {
     ports.maxSchemaChars = defaulted(ports.maxSchemaChars, modelRunnerDefaults.maxSchemaChars);
     const maxInputChars = defaulted(options.maxInputChars, modelRunnerDefaults.maxInputChars);
     const maxOutputTokens = defaulted(options.maxOutputTokens, modelRunnerDefaults.maxOutputTokens);
-    const integer = (value, minimum, infinity = false) => infinity && value === Infinity
-        || typeof value === 'number' && Number.isSafeInteger(value) && value >= minimum;
+    const integer = (value, minimum, infinity = false) => (infinity && value === Infinity) ||
+        (typeof value === 'number' && Number.isSafeInteger(value) && value >= minimum);
     breakWhile([
-        { occur: !integer(config.maxCalls, 0), error: () => invalid('maxCalls must be a nonnegative safe integer') },
-        { occur: !integer(config.callTimeoutMs, 1) || config.callTimeoutMs > 2147483647, error: () => invalid('callTimeoutMs must be a positive supported timeout') },
-        { occur: !integer(maxInputChars, 0, true), error: () => invalid('maxInputChars must be a nonnegative safe integer or Infinity') },
-        { occur: config.maxOutputChars !== undefined && !integer(config.maxOutputChars, 0, true), error: () => invalid('maxOutputChars must be a nonnegative safe integer or Infinity') },
-        { occur: ports.maxSchemaChars !== undefined && !integer(ports.maxSchemaChars, 1), error: () => invalid('maxSchemaChars must be a positive safe integer') },
-        { occur: !integer(maxOutputTokens, 1), error: () => invalid('maxOutputTokens must be a positive safe integer') },
+        {
+            occur: !integer(config.maxCalls, 0),
+            error: () => invalid('maxCalls must be a nonnegative safe integer'),
+        },
+        {
+            occur: !integer(config.callTimeoutMs, 1) || config.callTimeoutMs > 2147483647,
+            error: () => invalid('callTimeoutMs must be a positive supported timeout'),
+        },
+        {
+            occur: !integer(maxInputChars, 0, true),
+            error: () => invalid('maxInputChars must be a nonnegative safe integer or Infinity'),
+        },
+        {
+            occur: config.maxOutputChars !== undefined && !integer(config.maxOutputChars, 0, true),
+            error: () => invalid('maxOutputChars must be a nonnegative safe integer or Infinity'),
+        },
+        {
+            occur: ports.maxSchemaChars !== undefined && !integer(ports.maxSchemaChars, 1),
+            error: () => invalid('maxSchemaChars must be a positive safe integer'),
+        },
+        {
+            occur: !integer(maxOutputTokens, 1),
+            error: () => invalid('maxOutputTokens must be a positive safe integer'),
+        },
     ]);
-    return { provider: Object.freeze({ stream: stream.bind(provider) }), maxOutputTokens, config: Object.freeze(config), maxInputChars, ports };
+    return {
+        provider: Object.freeze({ stream: stream.bind(provider) }),
+        maxOutputTokens,
+        config: Object.freeze(config),
+        maxInputChars,
+        ports,
+    };
 }

package/dist/esm/model/token-budget.d.ts

@@ -1,8 +1,66 @@
+/**
+ * Token accounting for inputs that must fit a context window.
+ *
+ * Character limits alone cannot protect a provider call, so a host that supplies a
+ * token counter also declares the context window and a safety margin. The limit
+ * reserves room for the requested output before any input is counted.
+ *
+ * Exports: `validateModelTokenBudget`, `modelInputTokenLimit`, `countModelInput`,
+ * `enforceModelInputTokens` and `modelInputMessages`.
+ */
 import type { ModelTokenBudget } from '../structs/model/runtime.js';
 import type { ModelMessage, ModelOptions } from '../structs/model/messages.js';
+/**
+ * Validate a host-supplied token budget contract.
+ *
+ * @param budget - Budget to check: counter id, context window, optional safety margin, counter.
+ * @throws ValidationError When any field is missing or out of range.
+ */
 export declare function validateModelTokenBudget(budget: ModelTokenBudget): void;
+/**
+ * Compute how many input tokens remain for one call.
+ *
+ * The requested output tokens and the safety margin are subtracted from the context
+ * window, so a call that reserves more than the window is rejected before counting.
+ *
+ * @param budget - Declared context window and safety margin.
+ * @param outputTokens - Tokens reserved for the completion.
+ * @returns The positive input token allowance.
+ * @throws ValidationError When the reservation is invalid or leaves no input capacity.
+ */
 export declare function modelInputTokenLimit(budget: ModelTokenBudget, outputTokens: number): number;
+/**
+ * Count the tokens of a prepared request.
+ *
+ * The counter observes a request, so both messages and declarations are cloned before
+ * being handed over: accidental mutations by the counter must not rewrite the provider
+ * input. The returned count must itself be a nonnegative safe integer.
+ *
+ * @param budget - Budget supplying the counter.
+ * @param messages - Effective messages, including the merged instruction.
+ * @param options - Function declarations and JSON mode as they will be sent.
+ * @returns The token count reported by the host counter.
+ * @throws ValidationError When the counter returns an unusable number.
+ */
 export declare function countModelInput(budget: ModelTokenBudget, messages: readonly ModelMessage[], options: Pick<ModelOptions, 'functions' | 'json'>): number;
+/**
+ * Enforce the measured input against its token allowance.
+ *
+ * @param count - Measured input tokens.
+ * @param limit - Allowance from `modelInputTokenLimit`.
+ * @throws ValidationError When the input exceeds the allowance.
+ */
 export declare function enforceModelInputTokens(count: number, limit: number): void;
-/** Reused by preflight measurement and the provider call so instructions are counted exactly once. */
+/**
+ * Merge a transport instruction into the message list.
+ *
+ * An existing system message keeps its position and receives the instruction as a new
+ * paragraph; otherwise a system message is prepended. Reusing the same function for
+ * preflight measurement and the provider call is what makes instructions count exactly
+ * once.
+ *
+ * @param base - Caller messages; not mutated.
+ * @param instruction - Optional instruction to merge.
+ * @returns A new message array.
+ */
 export declare function modelInputMessages(base: readonly ModelMessage[], instruction?: string): ModelMessage[];

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

@@ -1,34 +1,92 @@
 import { ValidationError } from '../structs/errors.js';
 import { breakWhile } from '../utils/rules.js';
 const invalid = (message) => new ValidationError([{ code: 'MODEL_TOKEN_BUDGET', message }]);
+/**
+ * Validate a host-supplied token budget contract.
+ *
+ * @param budget - Budget to check: counter id, context window, optional safety margin, counter.
+ * @throws ValidationError When any field is missing or out of range.
+ */
 export function validateModelTokenBudget(budget) {
-    breakWhile(!budget.counterId || !Number.isSafeInteger(budget.contextWindowTokens) || budget.contextWindowTokens < 1
-        || !Number.isSafeInteger(budget.safetyMarginTokens ?? 0) || (budget.safetyMarginTokens ?? 0) < 0
-        || typeof budget.countTokens !== 'function', invalid('Invalid model token budget'));
+    breakWhile(!budget.counterId ||
+        !Number.isSafeInteger(budget.contextWindowTokens) ||
+        budget.contextWindowTokens < 1 ||
+        !Number.isSafeInteger(budget.safetyMarginTokens ?? 0) ||
+        (budget.safetyMarginTokens ?? 0) < 0 ||
+        typeof budget.countTokens !== 'function', invalid('Invalid model token budget'));
 }
+/**
+ * Compute how many input tokens remain for one call.
+ *
+ * The requested output tokens and the safety margin are subtracted from the context
+ * window, so a call that reserves more than the window is rejected before counting.
+ *
+ * @param budget - Declared context window and safety margin.
+ * @param outputTokens - Tokens reserved for the completion.
+ * @returns The positive input token allowance.
+ * @throws ValidationError When the reservation is invalid or leaves no input capacity.
+ */
 export function modelInputTokenLimit(budget, outputTokens) {
     const limit = budget.contextWindowTokens - outputTokens - (budget.safetyMarginTokens ?? 0);
     breakWhile(!Number.isSafeInteger(outputTokens) || outputTokens < 1 || limit < 1, invalid('No input capacity after reserving output and safety margin'));
     return limit;
 }
+/**
+ * Count the tokens of a prepared request.
+ *
+ * The counter observes a request, so both messages and declarations are cloned before
+ * being handed over: accidental mutations by the counter must not rewrite the provider
+ * input. The returned count must itself be a nonnegative safe integer.
+ *
+ * @param budget - Budget supplying the counter.
+ * @param messages - Effective messages, including the merged instruction.
+ * @param options - Function declarations and JSON mode as they will be sent.
+ * @returns The token count reported by the host counter.
+ * @throws ValidationError When the counter returns an unusable number.
+ */
 export function countModelInput(budget, messages, options) {
     // A counter observes a request; accidental mutations must not rewrite the provider input.
-    const snapshot = messages.map(message => ({ ...message,
-        ...(message.images ? { images: message.images.map(image => ({ ...image })) } : {}),
+    const snapshot = messages.map((message) => ({
+        ...message,
+        ...(message.images ? { images: message.images.map((image) => ({ ...image })) } : {}),
     }));
-    const count = budget.countTokens({ messages: snapshot,
-        functions: options.functions ? structuredClone(options.functions) : undefined, json: options.json });
+    const count = budget.countTokens({
+        messages: snapshot,
+        functions: options.functions ? structuredClone(options.functions) : undefined,
+        json: options.json,
+    });
     breakWhile(!Number.isSafeInteger(count) || count < 0, invalid('Token counter must return a nonnegative integer'));
     return count;
 }
+/**
+ * Enforce the measured input against its token allowance.
+ *
+ * @param count - Measured input tokens.
+ * @param limit - Allowance from `modelInputTokenLimit`.
+ * @throws ValidationError When the input exceeds the allowance.
+ */
 export function enforceModelInputTokens(count, limit) {
     breakWhile(count > limit, invalid(`Model input uses ${count} tokens; available input budget is ${limit}`));
 }
-/** Reused by preflight measurement and the provider call so instructions are counted exactly once. */
+/**
+ * Merge a transport instruction into the message list.
+ *
+ * An existing system message keeps its position and receives the instruction as a new
+ * paragraph; otherwise a system message is prepended. Reusing the same function for
+ * preflight measurement and the provider call is what makes instructions count exactly
+ * once.
+ *
+ * @param base - Caller messages; not mutated.
+ * @param instruction - Optional instruction to merge.
+ * @returns A new message array.
+ */
 export function modelInputMessages(base, instruction) {
     if (!instruction)
         return [...base];
-    const index = base.findIndex(message => message.role === 'system');
-    return index < 0 ? [{ role: 'system', content: instruction }, ...base]
-        : base.map((message, position) => position === index ? { ...message, content: `${message.content}\n\n${instruction}` } : message);
+    const index = base.findIndex((message) => message.role === 'system');
+    return index < 0
+        ? [{ role: 'system', content: instruction }, ...base]
+        : base.map((message, position) => position === index
+            ? { ...message, content: `${message.content}\n\n${instruction}` }
+            : message);
 }

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

@@ -1,8 +1,26 @@
 import type { ModelOptions } from '../structs/model/messages.js';
 import type { ModelTransportDefinition } from '../structs/model/runtime.js';
-/** Shared Core mechanism, also used by the optional App-side text creator. */
+/**
+ * Build a transport that expects a single plain-text completion.
+ *
+ * JSON mode is forced off because a text stage has no envelope to parse, and the final
+ * text is trimmed so transport-specific whitespace never reaches the caller.
+ *
+ * @param id - Unique transport id, also used as the typed handle in `ModelRunner`.
+ * @param options - Optional request options; only `temperature` is honored.
+ * @returns A frozen transport definition.
+ */
 export declare function createPlainTextTransport<const Id extends string>(id: Id, options?: Pick<ModelOptions, 'temperature'>): ModelTransportDefinition<string> & {
     readonly id: Id;
 };
-/** Pin the supplied implementation and preserve its receiver at registration. */
+/**
+ * Freeze a transport and pin its preparation receiver.
+ *
+ * Binding at registration means a later caller cannot swap the definition's identity
+ * or detach `prepare` from the object that specializes it.
+ *
+ * @param definition - Transport supplied by the App or by a factory.
+ * @returns A frozen definition with a bound `prepare`.
+ * @throws TypeError When the id is blank or `prepare` is missing.
+ */
 export declare function normalizeModelTransport<Result>(definition: ModelTransportDefinition<Result>): ModelTransportDefinition<Result>;

package/dist/esm/model/transports.js

@@ -1,20 +1,73 @@
+/**
+ * Transport definitions and the built-in plain-text transport.
+ *
+ * A transport owns the wire-level request shape (options, declarations, instruction)
+ * and the collector that decodes streamed parts into one result. The runner never
+ * interprets provider output itself, so adding a protocol means adding a transport
+ * rather than branching in the core.
+ *
+ * Exports: `createPlainTextTransport` and `normalizeModelTransport`.
+ */
 import { synchronous } from '../utils/synchronous.js';
 import { ValidationError } from '../structs/errors.js';
 import { snapshotModelOptions } from './options.js';
+/**
+ * Collector that concatenates plain text into one decoded value.
+ *
+ * A non-string part means the provider emitted a native call event, which a plain-text
+ * stage cannot represent; that is reported as a protocol violation instead of being
+ * stringified.
+ *
+ * @param decode - Final conversion from accumulated raw text to the result.
+ * @returns A collector reporting the buffered character count.
+ */
 function textResponse(decode) {
     let raw = '';
-    return { get outputChars() { return raw.length; }, push(part) {
+    return {
+        get outputChars() {
+            return raw.length;
+        },
+        push(part) {
             if (typeof part !== 'string')
-                throw new ValidationError([{ code: 'MODEL_PROTOCOL', message: 'Text transport does not accept model calls' }]);
+                throw new ValidationError([
+                    { code: 'MODEL_PROTOCOL', message: 'Text transport does not accept model calls' },
+                ]);
             raw += part;
-        }, finish: () => synchronous(decode(raw), 'Model result parsers must be synchronous') };
+        },
+        finish: () => synchronous(decode(raw), 'Model result parsers must be synchronous'),
+    };
 }
-/** Shared Core mechanism, also used by the optional App-side text creator. */
+/**
+ * Build a transport that expects a single plain-text completion.
+ *
+ * JSON mode is forced off because a text stage has no envelope to parse, and the final
+ * text is trimmed so transport-specific whitespace never reaches the caller.
+ *
+ * @param id - Unique transport id, also used as the typed handle in `ModelRunner`.
+ * @param options - Optional request options; only `temperature` is honored.
+ * @returns A frozen transport definition.
+ */
 export function createPlainTextTransport(id, options = {}) {
     const settings = Object.freeze({ ...snapshotModelOptions(options), json: false });
-    return Object.freeze({ id, prepare: (_stageId) => ({ options: settings, schemaChars: 0, createResponse: () => textResponse(raw => raw.trim()) }) });
+    return Object.freeze({
+        id,
+        prepare: (_stageId) => ({
+            options: settings,
+            schemaChars: 0,
+            createResponse: () => textResponse((raw) => raw.trim()),
+        }),
+    });
 }
-/** Pin the supplied implementation and preserve its receiver at registration. */
+/**
+ * Freeze a transport and pin its preparation receiver.
+ *
+ * Binding at registration means a later caller cannot swap the definition's identity
+ * or detach `prepare` from the object that specializes it.
+ *
+ * @param definition - Transport supplied by the App or by a factory.
+ * @returns A frozen definition with a bound `prepare`.
+ * @throws TypeError When the id is blank or `prepare` is missing.
+ */
 export function normalizeModelTransport(definition) {
     if (!definition.id?.trim() || typeof definition.prepare !== 'function')
         throw new TypeError('Invalid model transport');

package/dist/esm/structs/capabilities/invocation.d.ts

@@ -1,28 +1,64 @@
+/**
+ * Tool invocation lifecycle contracts: request-local journal, handler shape and host ports.
+ *
+ * These declarations let an App compose tool handlers from a journal and optional ports without
+ * Core learning any domain concept. The journal records execution receipts; the host decides what
+ * a receipt means for its own domain.
+ *
+ * Exports: `ToolJournalStart`, `ToolJournalFinish`, `ToolJournal`, `InvocationHandler`,
+ * `ToolInvocationPorts`.
+ */
 import type { InvocationMetadata } from '../invocation.js';
+/** Opening record for one tool call, written before the handler runs. */
 export interface ToolJournalStart {
+    /** Tool being invoked. */
     toolId: string;
+    /** Parsed input; stored as-is so the host can build its own domain record. */
     input: unknown;
+    /** What the caller already knows. The journal fills gaps and generates an id when absent. */
     invocation?: Partial<InvocationMetadata>;
 }
+/** Closing record for one tool call, written once with the terminal outcome. */
 export interface ToolJournalFinish {
+    /** Invocation opened by `beginTool`. */
     invocationId: string;
+    /** Terminal status; `cancelled` is distinct from `error`. */
     status: 'success' | 'error' | 'cancelled';
+    /** Produced value on success; failure detail on error; ignored for cancellation. */
     value: unknown;
 }
 /** Request-local execution receipts; the host decides their domain content. */
 export interface ToolJournal {
+    /** Opens a receipt and returns the invocation id later passed to `finishTool`. */
     beginTool(request: ToolJournalStart): string;
+    /** Closes the receipt; must be called exactly once per opened invocation. */
     finishTool(request: ToolJournalFinish): void;
 }
+/** A named handler invoked by a tool lifecycle step. */
 export interface InvocationHandler<Input, Context> {
     readonly id: string;
+    /**
+     * Runs the handler.
+     *
+     * The return value is ignored, so handlers report outcomes through the tool value or journal.
+     * @param input - Step input supplied by the lifecycle.
+     * @param context - Host context of the request.
+     * @param execution - Execution facts of this invocation.
+     */
     call(input: Input, context: Context, execution: import('./tools.js').ToolExecutionContext): void;
 }
+/** Optional capabilities the lifecycle resolves from the host context for one invocation. */
 export interface ToolInvocationPorts<Context> {
+    /** Diagnostic scope; omitted disables recording for this tool. */
     readonly diagnostics?: (context: Context) => import('../diagnostics.js').DiagnosticContext | undefined;
+    /** Extra cancellation; must not replace the tool execution signal. */
     readonly signal?: (context: Context) => AbortSignal | undefined;
+    /** Journal receiving begin/finish receipts. */
     readonly journal?: (context: Context) => ToolJournal | undefined;
+    /** Extracts the domain checkpoint recorded with the receipt. */
     readonly checkpoint?: (context: Context) => unknown;
+    /** Builds the domain receipt from a checkpoint after execution. */
     readonly receipt?: (context: Context, checkpoint: unknown) => unknown;
+    /** Converts an error into the receipt's replacement value. */
     readonly receiptError?: (error: unknown) => unknown;
 }

package/dist/esm/structs/capabilities/model.d.ts

@@ -1,25 +1,52 @@
+/**
+ * Model capability contract: the business operations a model may select during a call.
+ *
+ * A capability pairs one JSON schema with a resolver that turns model-supplied arguments into a
+ * host value. Registration snapshots the schema and pins the resolver, so a request can project a
+ * sealed subset without cloning handlers.
+ *
+ * Exports: `ModelCapability`, `ModelCapabilityRegistration`, `RegisteredModelCapability`,
+ * `ModelSelection`, `ModelCapabilitySource`, `ModelCapabilityCatalog`.
+ */
 import type { SchemaAdapter, ReadonlyCatalog } from '../common.js';
+/** One selectable model operation. */
 export interface ModelCapability<Input = unknown, Output = Input> {
+    /** Unique id within its registry; never blank. */
     readonly id: string;
+    /** Model-visible description explaining when the capability applies. */
     readonly description: string;
+    /** Schema describing the arguments; must be an object schema. */
     readonly inputSchema: SchemaAdapter<Input>;
+    /**
+     * Converts validated arguments into the value handed back to the caller.
+     *
+     * Runs inside the model call, so it must return synchronously; throwing rejects the selection.
+     */
     resolve(input: Input, context: Readonly<{
         stageId: string;
     }>): Output;
 }
+/** Registration form: input typing is erased, output typing is preserved. */
 export type ModelCapabilityRegistration<Output = unknown> = ModelCapability<any, Output>;
+/** Frozen snapshot stored by a registry after schema validation. */
 export type RegisteredModelCapability<Output = unknown> = Readonly<ModelCapability<unknown, Output>>;
+/** A model's chosen capability together with its parsed arguments. */
 export type ModelSelection = {
+    /** Arguments exactly as produced by the model, before schema parsing. */
     readonly input: Record<string, unknown>;
+    /** Native function call that carried the selection, when the provider used one. */
     readonly call?: {
         id: string;
         name: string;
         argumentChars: number;
     };
+    /** Capability the selection resolved to. */
     readonly capabilityId: string;
 };
+/** Minimal source a stage needs: enumerate capabilities and resolve one selection. */
 export interface ModelCapabilitySource<Output = unknown> {
     values(): IterableIterator<RegisteredModelCapability<Output>>;
+    /** Resolves one selection; throws when the capability is absent from this source. */
     resolve(selection: ModelSelection, context: Readonly<{
         stageId: string;
     }>): Output;