@jangts/agent-core 0.1.1 → 0.2.1

package/dist/esm/structs/kits/tools.d.ts

@@ -1,3 +1,15 @@
+/**
+ * Tool lifecycle contract for the Tools Kit.
+ *
+ * Place in the package: an optional App-side library for tools that need more than a plain
+ * definition — availability, per-step protocols, output ownership, model-context fields, task rules
+ * and delivery hooks. Actual invocation is delegated to Core (`ToolRegistry`, `executeInvocation`);
+ * domain predicates, phase names and vocabulary stay App configuration.
+ *
+ * Exports: `ToolRuntimeTypes`, `ToolModelField`, `LifecycleProtocol`, `ToolInvocation`,
+ * `ToolContribution`, `LifecycleTool`, `RegisteredLifecycleTool`, `Policy`, `ToolProtocol`,
+ * `ToolNormalizer`, `ToolFinalizer`, `ToolLifecycleOptions`, `ToolJournal` (type re-export).
+ */
 import type { ContextFragment, ContextLifetime } from '../context/fragments.js';
 import type { BreakReason } from '../utils/rules.js';
 import type { ExecutableTool, ToolRegistryPorts } from '../capabilities/tools.js';
@@ -6,59 +18,108 @@ import type { ToolInvocationPorts } from '../capabilities/invocation.js';
 import type { RegistrationProjection } from '../../utils/registration.js';
 /** One schema binds lifecycle handler types without introducing platform fields into core. */
 export interface ToolRuntimeTypes {
+    /** App decision object carried through invocation steps. */
     decision: unknown;
+    /** App handler context for one request. */
     context: unknown;
+    /** Value produced by a tool's `composition` hook. */
     composition: unknown;
+    /** App phase names used by `finalize`. */
     phase: string;
+    /** App placement names used to group model-context fields. */
     placement: string;
+    /** Extra arguments accepted by a tool normalizer. */
     normalizerArgs: unknown[];
+    /** Value produced by a tool finalizer. */
     result: unknown;
+    /** Value handed to the finalizer, supplied by the lifecycle receiver. */
     receiver: unknown;
 }
+/** One model-context field contributed by a tool. */
 export interface ToolModelField<Placement extends string = string> {
+    /** Validity window of the produced fragment. */
     lifetime?: ContextLifetime;
+    /** Character budget of the produced fragment. */
     maxChars?: number;
+    /** Placement group this field belongs to; only that placement consumes it. */
     placement: Placement;
+    /** Ordering key; lower values are emitted first within a placement. */
     order: number;
+    /** Key inside the merged model field record; later entries win. */
     key: string;
+    /** Field value, rendered by the registry's fragment factory. */
     value: unknown;
 }
+/** Output protocol carried by a lifecycle step. */
 export interface LifecycleProtocol extends ProtocolShape {
+    /** Protocol version; compared with the configured `protocolVersion` when present. */
     readonly version?: number;
+    /** Marks an output that ends the interaction. */
     readonly terminal?: boolean;
 }
+/** One lifecycle step of a tool. */
 export interface ToolInvocation<Types extends ToolRuntimeTypes, Protocol extends LifecycleProtocol = LifecycleProtocol> {
+    /** Step id this invocation handles; must be unique across registered tools. */
     step: string;
+    /** Output protocol of the step. */
     protocol: Protocol;
+    /** Executes the step. Must be synchronous and return nothing. */
     call(value: unknown, context: Types['context'], execution: import('../capabilities/tools.js').ToolExecutionContext): void;
+    /** Inspects a decision before any step runs. */
     inspect?(decision: Types['decision'], context: Types['context']): void;
+    /** Permission check for the decision; runs before execution. */
     authorize?(decision: Types['decision'], context: Types['context']): void;
+    /** Returns true when this step is a valid continuation of the decision. */
     resume?(decision: Types['decision'], context: Types['context']): boolean;
+    /** Normalizes the decision after the step; returning undefined keeps it unchanged. */
     complete?(decision: Types['decision'], context: Types['context']): Types['decision'] | undefined;
 }
+/**
+ * Non-execution hooks a tool may contribute to a request.
+ *
+ * Every hook is optional; one returns nothing to express "no opinion".
+ */
 export interface ToolContribution<Types extends ToolRuntimeTypes> {
+    /** Builds the tool's composition value for the current context. */
     composition?(context: Types['context']): Types['composition'] | undefined;
+    /** Observes the decision during the inspect phase. */
     inspect?(decision: Types['decision'], context: Types['context']): void;
+    /** Extra context used when recovering a previous attempt. */
     recoveryContext?(context: Types['context']): unknown;
+    /** Projects the stored context before it is shown or persisted. */
     projectContext?(context: unknown): unknown;
+    /** Rewrites visible text produced by this tool. */
     visibleText?(text: string, context: Types['context']): string;
+    /** Reviews a draft before delivery. */
     reviewDraft?(draft: unknown, context: Types['context']): unknown;
+    /** Runs finalization for one phase. */
     finalize?(decision: Types['decision'], context: Types['context'], phase: Types['phase']): void;
+    /** Returns true when an absent interaction is acceptable in this phase. */
     missingInteractionAllowed?(decision: Types['decision'], context: Types['context']): boolean;
+    /** Extra rules contributed to the model context, ordered by `order`. */
     rules?(context: Types['context']): {
         order: number;
         text: string;
     }[];
+    /** Model-context fields for one placement, ordered by `order`. */
     modelFields?(context: Types['context'], placement: Types['placement']): ToolModelField<Types['placement']>[];
+    /** Vetoes an intent by returning false; silence (undefined) means support. */
     supportsIntent?(intentId: string, context: Types['context']): boolean | undefined;
 }
+/** A tool with lifecycle steps and delivery contributions. */
 export interface LifecycleTool<Types extends ToolRuntimeTypes> extends ExecutableTool {
+    /** Intent ids this tool serves, or `'all'` when it is always available. */
     readonly intentIds: 'all' | readonly string[];
     readonly description: string;
+    /** Audience this tool is described to; validated against the registry policy. */
     readonly audience: string;
+    /** Declared effect class, for example read-only or mutating. */
     readonly effect: string;
+    /** Per-step invocation contract. */
     readonly invocation?: ToolInvocation<Types>;
+    /** Non-execution hooks. */
     readonly contribution?: ToolContribution<Types>;
+    /** Returns whether the tool may run for this context; absent means always available. */
     available?(context: Types['context']): boolean;
 }
 type RegisteredInvocation<Types extends ToolRuntimeTypes, Value> = Value extends ToolInvocation<Types> ? RegistrationProjection<Value, ToolInvocation<Types>> : Value;
@@ -66,38 +127,64 @@ type RegisteredContribution<Types extends ToolRuntimeTypes, Value> = Value exten
 type RegisteredLifecycleHooks<Types extends ToolRuntimeTypes, Tool extends LifecycleTool<Types>> = {
     [Key in keyof Pick<Tool, Extract<keyof Tool, 'invocation' | 'contribution'>>]: Key extends 'invocation' ? RegisteredInvocation<Types, Tool[Key]> : RegisteredContribution<Types, Tool[Key]>;
 };
+/** Registered snapshot with frozen intent ids and projected hooks. */
 export type RegisteredLifecycleTool<Types extends ToolRuntimeTypes, Tool extends LifecycleTool<Types> = LifecycleTool<Types>> = Readonly<Omit<RegistrationProjection<Tool, LifecycleTool<Types>>, 'invocation' | 'contribution' | 'intentIds'> & RegisteredLifecycleHooks<Types, Tool> & {
     intentIds: Readonly<Tool['intentIds']>;
 }>;
+/** Registration policy shared by every tool in the registry. */
 export interface Policy<Tool> {
+    /** Accepted values of a tool's `kind`. */
     readonly kinds: readonly string[];
+    /** Identity and shape predicate; must be synchronous boolean. */
     readonly isValidId: (tool: Tool) => boolean;
+    /** Accepted `audience` values. */
     readonly audiences: readonly string[];
+    /** Accepted `effect` values. */
     readonly effects: readonly string[];
+    /** Reports whether an intent id exists, for validating `intentIds` references. */
     readonly intentExists: (goal: string) => boolean;
+    /** When set, every step protocol must declare this version. */
     readonly protocolVersion?: number;
+    /** Diagnostic tags attached to registration rejections. */
     readonly tags?: readonly string[];
+    /** Rejection wording for an invalid tool definition. */
     readonly invalidTool?: BreakReason;
+    /** Rejection wording for an invalid or duplicate invocation step. */
     readonly invalidInvocation?: BreakReason;
 }
+/** Protocol type of a tool's invocation step. */
 export type ToolProtocol<Tool extends {
     invocation?: {
         protocol: LifecycleProtocol;
     };
 }> = NonNullable<Tool['invocation']>['protocol'];
+/** Converts untrusted input into a decision; must be synchronous. */
 export type ToolNormalizer<Types extends ToolRuntimeTypes> = (value: unknown, ...args: Types['normalizerArgs']) => unknown;
+/** Converts an executed decision into the tool result; must be synchronous. */
 export type ToolFinalizer<Types extends ToolRuntimeTypes> = (receiver: Types['receiver'], decision: Types['decision'], context: Types['context']) => Types['result'];
+/** Construction options for a lifecycle tool registry. */
 export interface ToolLifecycleOptions<Types extends ToolRuntimeTypes, Tool extends LifecycleTool<Types>> extends ToolInvocationPorts<Types['context']> {
+    /** Supplies the receiver handed to the finalizer. */
     readonly receiver?: () => Types['receiver'];
+    /** Execution defaults (signal and diagnostics) applied to invocations. */
     readonly execution?: import('../common.js').ExecutionOptions;
+    /** Error factories shared by the registry. */
     readonly errors?: Pick<ToolRegistryPorts, 'unavailable' | 'errorCode'>;
+    /** Registration policy for every tool. */
     readonly registration: Policy<Tool>;
+    /** Maps a decision to its lifecycle step id. */
     readonly step: (decision: Types['decision']) => string;
+    /** Output protocols by id, used to validate step outputs. */
     readonly outputs: () => Iterable<readonly [string, ToolProtocol<Tool>]>;
+    /** Optional context-dependent output protocols, exposed alongside `outputs`. */
     readonly modelOutputs?: (context: Types['context']) => Iterable<readonly [string, ToolProtocol<Tool>]>;
+    /** Builds the error for a step with no registered tool. */
     readonly unavailableStep?: (step: string) => Error;
+    /** Builds the error for a tool that is currently unavailable. */
     readonly forbidden?: () => Error;
+    /** Renders a model field into a context fragment. */
     readonly contextFragment: (tool: Tool, field: ToolModelField<Types['placement']>) => ContextFragment;
+    /** Current intent ids, used to validate `intentIds: 'all'` availability. */
     readonly intentIds: () => readonly string[];
 }
 export type { ToolJournal } from '../capabilities/invocation.js';

package/dist/esm/structs/model/chat-provider.d.ts

@@ -1,9 +1,32 @@
+/**
+ * Provider boundary contract.
+ *
+ * A chat provider streams neutral parts for a prepared message list; everything provider-specific
+ * lives behind this abstraction. The module also re-exports the message primitives so adapters can
+ * depend on one entry.
+ *
+ * Exports: `ModelProviderContext`, `ChatProvider`, and type re-exports of `ModelMessage`,
+ * `ModelImage`, `ModelUsage`, `ModelFunction`, `FunctionCallDelta`, `ModelPart`, `ModelOptions`.
+ */
 import type { ExecutionContext } from '../common.js';
 import type { ModelMessage, ModelOptions, ModelPart } from './messages.js';
+/** Per-call facts a provider receives besides the messages themselves. */
 export interface ModelProviderContext extends ExecutionContext {
+    /** Options prepared for this call, including function schemas and JSON mode. */
     readonly options?: Readonly<ModelOptions>;
 }
+/**
+ * Streaming model provider.
+ *
+ * Implementations must stop producing when `context.signal` aborts and should surface transport
+ * failures by rejecting the iteration rather than ending it silently.
+ */
 export declare abstract class ChatProvider {
+    /**
+     * @param messages - Final message list, already budget-checked by the caller.
+     * @param context - Cancellation and per-call options.
+     * @returns Parts in arrival order; function-call fragments keep their provider index.
+     */
     abstract stream(messages: readonly ModelMessage[], context: ModelProviderContext): AsyncIterable<ModelPart>;
 }
-export type { ModelMessage, ModelImage, ModelUsage, ModelFunction, FunctionCallDelta, ModelPart, ModelOptions } from './messages.js';
+export type { ModelMessage, ModelImage, ModelUsage, ModelFunction, FunctionCallDelta, ModelPart, ModelOptions, } from './messages.js';

package/dist/esm/structs/model/chat-provider.js

@@ -1,2 +1,8 @@
+/**
+ * Streaming model provider.
+ *
+ * Implementations must stop producing when `context.signal` aborts and should surface transport
+ * failures by rejecting the iteration rather than ending it silently.
+ */
 export class ChatProvider {
 }

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

@@ -1,18 +1,40 @@
+/**
+ * Model interaction contracts: how model output is turned into a business selection.
+ *
+ * An adapter compiles registered capabilities into provider options plus an instruction, and
+ * decodes the streamed response into a `ModelSelection`. A transport registration binds one adapter
+ * to a capability source, so the same business registry can be served by different wire formats.
+ *
+ * Exports: `ModelResponseCollector`, `PreparedModelInteraction`, `PreparedModelTransport`,
+ * `ModelInteractionAdapter`, `ModelTransportRegistration`, `NativeFunctionCall`.
+ */
 import type { ModelOptions, ModelPart } from './messages.js';
 import type { ModelSelection, ModelCapabilitySource, RegisteredModelCapability } from '../capabilities/model.js';
+/** Accumulates streamed parts for one call and resolves them into the transport's result. */
 export interface ModelResponseCollector<Result = ModelSelection> {
+    /** Native function call that carried the selection, when the response used one. */
     readonly call?: ModelSelection['call'];
+    /** Output characters accumulated so far, for output-budget accounting. */
     readonly outputChars: number;
+    /** Appends one streamed part; parts arrive in provider order. */
     push(part: ModelPart): void;
+    /** Finalizes the response. Throws when the accumulated content is not a valid selection. */
     finish(): Result;
 }
+/** Adapter output for one stage, before the caller binds capability resolution. */
 export interface PreparedModelInteraction<Result = unknown> {
+    /** Provider options produced from the stage's capabilities. */
     readonly options: Pick<ModelOptions, 'functions' | 'json'>;
+    /** Characters the compiled schemas add to the input, counted against the schema budget. */
     readonly schemaChars: number;
+    /** Instruction text that teaches the model how to answer; absent when the format is native. */
     readonly instruction?: string;
+    /** Creates a fresh collector for one call; never reuse a collector across calls. */
     createResponse(): ModelResponseCollector;
+    /** Resolves a validated selection into the stage result. */
     resolve(selection: ModelSelection, stage: string): Result;
 }
+/** Prepared transport handed to the runner, including sampling defaults. */
 export interface PreparedModelTransport<Result = unknown> {
     readonly options: Pick<ModelOptions, 'functions' | 'json' | 'temperature'>;
     readonly schemaChars: number;
@@ -21,22 +43,38 @@ export interface PreparedModelTransport<Result = unknown> {
 }
 /** Pluggable implementations all consume the same business registry. No automatic fallback. */
 export interface ModelInteractionAdapter {
+    /** Adapter id, reported when a transport is validated or rejected. */
     readonly id: string;
     readonly features: {
         readonly strictArguments: boolean;
     };
+    /**
+     * Compiles one stage's capabilities.
+     *
+     * @param capabilities - Capabilities available in this stage; must be non-empty.
+     * @returns Options, instruction and collector factory; the transport adds `resolve`.
+     */
     prepare(capabilities: readonly RegisteredModelCapability[]): Omit<PreparedModelInteraction, 'resolve'>;
 }
+/** Binds an adapter to the capabilities one transport serves. */
 export interface ModelTransportRegistration<Result = unknown> {
+    /** Transport id used by call requests and reported in diagnostic events. */
     id: string;
+    /** Static capability source, or a factory that selects capabilities per stage. */
     capabilities: ModelCapabilitySource<Result> | ((stage: string) => ModelCapabilitySource<Result>);
+    /** Wire-format adapter; defaults to native function calling. */
     adapter?: ModelInteractionAdapter;
+    /** Sampling defaults this transport contributes to every call. */
     options?: Pick<ModelOptions, 'temperature'>;
+    /** Reject the registration when the chosen adapter cannot enforce strict arguments. */
     requireStrictArguments?: boolean;
 }
 /** Request-local native call buffer; never an execution receipt. */
 export interface NativeFunctionCall {
+    /** Provider call id; only unique within the response. */
     id: string;
+    /** Function name exactly as returned by the model. */
     name: string;
+    /** Raw JSON argument text, validated only when the selection is parsed. */
     arguments: string;
 }

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

@@ -1,38 +1,72 @@
+/**
+ * Model message primitives shared by every provider adapter.
+ *
+ * These shapes are deliberately provider-neutral: they describe text, optional images, streamed
+ * parts and the options a call may carry. Provider-specific wire formats stay in `support/model`.
+ *
+ * Exports: `ModelImage`, `ModelMessage`, `ModelUsage`, `ModelFunction`, `FunctionCallDelta`,
+ * `ModelPart`, `ModelOptions`.
+ */
 export interface ModelImage {
+    /** Absolute or data URL the provider can fetch; never a local file path. */
     url: string;
+    /** Provider resolution hint; `original` asks for no downscaling where supported. */
     detail?: 'auto' | 'low' | 'high' | 'original';
 }
+/** One provider-neutral turn; `images` are user visual input and are not part of the text budget. */
 export interface ModelMessage {
     role: 'system' | 'user' | 'assistant';
+    /** Rendered text content sent to the model. */
     content: string;
     /** User-supplied visual input. Binary payload is separate from the text character budget. */
     images?: readonly ModelImage[];
 }
+/** Provider-reported token counts for one call; used for accounting, never for admission. */
 export interface ModelUsage {
+    /** Input tokens billed for the call. */
     promptTokens: number;
+    /** Output tokens billed for the call. */
     completionTokens: number;
+    /** Provider-reported total; may include tokens not covered by the two fields above. */
     totalTokens: number;
 }
 /** Provider-neutral function definition. Execution and authorization stay with the host. */
 export interface ModelFunction {
+    /** Function name the model must use when selecting the capability. */
     name: string;
+    /** Model-visible description of when the function applies. */
     description: string;
+    /** JSON Schema of the arguments; must be an object schema. */
     parameters: Record<string, unknown>;
+    /** Request strict argument validation from providers that support it. */
     strict?: boolean;
 }
+/** One streamed fragment of a function call; fragments with the same `index` must be joined. */
 export interface FunctionCallDelta {
     type: 'function-call-delta';
+    /** Index of the call within the response; deltas with the same index belong together. */
     index: number;
+    /** Provider call id, usually delivered once with the first delta. */
     id?: string;
+    /** Function name, usually delivered once with the first delta. */
     name?: string;
+    /** Raw JSON argument fragment; concatenating all fragments yields the full arguments. */
     arguments?: string;
 }
+/** One streamed response part: assistant text or a function-call fragment. */
 export type ModelPart = string | FunctionCallDelta;
+/** Per-call provider options; Core passes them through and does not normalize provider ranges. */
 export interface ModelOptions {
+    /** Request a JSON-object response from providers that support it. */
     json?: boolean;
+    /** Sampling temperature; provider range is not normalized by Core. */
     temperature?: number;
+    /** Output ceiling for the call; the effective value is the smaller of this and the budget. */
     maxOutputTokens?: number;
+    /** Ask the provider to report usage for streamed responses. */
     includeUsage?: boolean;
+    /** Receives usage the provider reports; may be called once per call. */
     onUsage?: (usage: ModelUsage) => void;
+    /** Functions offered to the model for this call. */
     functions?: readonly ModelFunction[];
 }

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

@@ -1,3 +1,17 @@
+/**
+ * Model runtime contract: budgets, transports, call traces and prepared calls.
+ *
+ * A runner owns one request's call budget, deadlines and input/output limits. It prepares a
+ * transport (schemas, instruction, collector), measures the input, charges one call and reports a
+ * trace. Child runners share the request-wide limits, so a nested stage can only consume what the
+ * parent already reserved.
+ *
+ * Exports: `ModelTokenBudget`, `ModelRuntimeConfig`, `ModelChildPolicy`,
+ * `ModelTransportDefinition`,
+ * `ModelCallTrace`, `ModelOutputEvent`, `ModelRunnerPorts`, `ModelChildOptions`,
+ * `ModelRunnerSettings`, `RegisteredTransportOutput`, `ModelRunnerOptions`, `ModelCallRequest`,
+ * `ModelInputMeasurement`, `PreparedModelCall`, `ModelPrepareRequest`.
+ */
 import type { PreparedModelTransport } from './interactions.js';
 import type { InvocationMetadata } from '../invocation.js';
 import type { ExecutionOptions } from '../common.js';
@@ -7,52 +21,83 @@ import type { ChatProvider } from './chat-provider.js';
 import type { BuiltContext } from '../context/fragments.js';
 import type { ContextPlan } from '../context/processing.js';
 import type { ContextFragmentUsage } from '../context/fragments.js';
-/** Provider-specific counting is injected; Core never guesses a characters/token conversion. */
+/**
+ * Provider-injected token accounting.
+ *
+ * Core never guesses a character-to-token conversion, so token budgets exist only when a host
+ * supplies a real counter.
+ */
 export interface ModelTokenBudget {
+    /** Identifies the tokenizer and its version; recorded in every measurement. */
     counterId: string;
+    /** Total context window of the model, in tokens. */
     contextWindowTokens: number;
+    /** Additional reserve subtracted together with the output reservation. */
     safetyMarginTokens?: number;
+    /** Counts input tokens for the exact request shape that will be sent. */
     countTokens(input: {
         messages: readonly ModelMessage[];
         functions?: ModelOptions['functions'];
         json?: boolean;
     }): number;
 }
+/** Per-request model runtime limits. */
 export interface ModelRuntimeConfig {
+    /** Calls allowed for the whole request, including descendant runners' reservations. */
     maxCalls: number;
+    /** Deadline for one provider call, in milliseconds. */
     callTimeoutMs: number;
+    /** Cap on streamed output characters; exceeding it fails the call. */
     maxOutputChars?: number;
+    /** Request and record provider usage for each call. */
     usage?: boolean;
 }
 /** Request-wide limits, shared by every descendant. They cannot be enlarged by a child. */
 export interface ModelChildPolicy {
+    /** Maximum nesting depth of child runners; `0` forbids children. */
     readonly maxDepth?: number;
+    /** Maximum calls running at the same time across the request. */
     readonly maxConcurrentCalls?: number;
+    /** Maximum child runners created across the request. */
     readonly maxChildren?: number;
 }
+/** One registered transport: a wire format prepared for a stage. */
 export interface ModelTransportDefinition<Result = unknown> {
+    /** Transport id used by call requests and reported in diagnostics. */
     readonly id: string;
+    /** Builds the prepared transport for `stageId`; must not spend a call by itself. */
     prepare(stageId: string): import('./interactions.js').PreparedModelTransport<Result>;
 }
+/** Accumulated facts of one model call, reported on success and on failure. */
 export interface ModelCallTrace extends InvocationMetadata {
+    /** One-based position of the call within its runner's lifetime. */
     callSequence: number;
     stageId: string;
+    /** Model binding used for the call, when one was configured. */
     modelId?: string;
-    durationMs: number;
+    /** Counted input characters (messages, instruction and schemas). */
     inputChars: number;
+    /** Measured input tokens; present only with an explicit token counter. */
     inputTokens?: number;
+    /** Token ceiling the measurement was compared against. */
     inputTokenLimit?: number;
+    /** Characters received from the provider. */
     outputChars: number;
+    /** Time to first streamed part in milliseconds; `null` until a part arrived. */
     firstOutputMs?: number | null;
+    /** Milliseconds from the first part to the end of the stream. */
     outputDurationMs?: number;
     status: import('../common.js').InvocationStatus;
+    /** Error or protocol codes observed during the call, in occurrence order. */
     codes: string[];
     usage?: ModelUsage;
+    /** Selected function call, when the response produced one. */
     functionCall?: {
         id: string;
         name: string;
         argumentChars: number;
     };
+    /** Context accounting: per-fragment usage and characters shared with the previous call. */
     context?: {
         fragmentUsage: ContextFragmentUsage[];
         stablePrefixChars: number;
@@ -62,40 +107,60 @@ export interface ModelCallTrace extends InvocationMetadata {
 export type ModelOutputEvent = Extract<import('../execution/events.js').CoreEvent, {
     type: 'model.start' | 'model.output' | 'model.parsed' | 'model.end';
 }>;
+/** Host ports a model runner needs in addition to its provider and transports. */
 export interface ModelRunnerPorts {
+    /** Ordered delivery of model events; awaits each call before continuing. */
     onOutput?(event: ModelOutputEvent): void | Promise<void>;
+    /** Transports available by id and instance. */
     transports?: readonly ModelTransportDefinition[];
     diagnostics?: DiagnosticContext;
-    /** Separate explicit allowance for registered schemas; existing context budgets retain their meaning. */
+    /** Separate allowance for registered schemas; existing context budgets keep their meaning. */
     maxSchemaChars?: number;
     tokenBudget?: ModelTokenBudget;
+    /** Builds the error for an input that exceeds the character or token limit. */
     inputBudgetError?(limit: number): Error;
+    /** Builds the error for output that exceeds the character limit. */
     outputBudgetError?(): Error;
 }
 /** Request-bound isolated runner settings; provider and ancestor budgets cannot be replaced. */
 export interface ModelChildOptions {
+    /** Child stage id, reported in traces and events. */
     readonly id: string;
+    /** Calls the child may use from the shared request budget. */
     readonly maxCalls: number;
+    /** Calls kept for the parent; the child cannot spend them. */
     readonly reserveCalls: number;
+    /** Deadline for the child's own calls, in milliseconds. */
     readonly timeoutMs: number;
+    /** Additional transports visible to the child. */
     readonly transports?: readonly ModelTransportDefinition[];
     readonly diagnostics?: DiagnosticContext;
+    /** Extra cancellation; can only shorten the parent's lifetime. */
     readonly signal?: AbortSignal;
 }
 /** Named settings keep all model limits together; output token reservation stays per call. */
 export interface ModelRunnerSettings extends Partial<ModelRuntimeConfig> {
     readonly children?: ModelChildPolicy;
+    /** Character budget for the assembled input. */
     maxInputChars?: number;
+    /** Character allowance for registered capability schemas. */
     maxSchemaChars?: number;
     tokenBudget?: ModelTokenBudget;
     /** Default output reservation; invoke can override it for one call. */
     maxOutputTokens?: number;
 }
+/**
+ * Result type of a transport selected by id.
+ *
+ * `core:plain-text` yields `string`, a registered id yields its declared result, and an id the
+ * runner does not know yields `unknown` rather than a guessed type.
+ */
 export type RegisteredTransportOutput<Transports extends readonly ModelTransportDefinition[], Id extends string> = string extends Id ? unknown : Id extends 'core:plain-text' ? string : [Extract<Transports[number], {
     readonly id: Id;
 }>] extends [never] ? unknown : Extract<Transports[number], {
     readonly id: Id;
 }> extends ModelTransportDefinition<infer Value> ? Value : unknown;
+/** Full runner construction options: provider, transports, sinks and named limits. */
 export type ModelRunnerOptions<Transports extends readonly ModelTransportDefinition[] = readonly ModelTransportDefinition[]> = {
     provider: ChatProvider;
     execution?: ExecutionOptions;
@@ -108,46 +173,79 @@ export type ModelRunnerOptions<Transports extends readonly ModelTransportDefinit
         outputBudget?: ModelRunnerPorts['outputBudgetError'];
     };
 } & ModelRunnerSettings;
+/** One model call request. The input shape selects prompt mode or message mode. */
 export type ModelCallRequest<Transport = string> = {
     /** Additional cancellation can shorten, never replace, the Runner lifetime. */
     readonly signal?: AbortSignal;
     /** Parent observation scope for this invocation; never changes execution budget or signal. */
     readonly diagnostics?: DiagnosticContext;
+    /** Reuse a prepared call; its stage, transport and output reservation then take precedence. */
     readonly prepared?: PreparedModelCall;
     readonly maxOutputTokens?: number;
     readonly stageId?: string;
     readonly transport?: Transport;
-} & ({
+} & 
+/** Prompt mode: one user message plus optional instructions. */
+({
     input: string;
     instructions?: string;
-} | {
+}
+/** Message mode: messages or a context plan; instructions are already inside the input. */
+ | {
     input: readonly ModelMessage[] | BuiltContext | ContextPlan;
     instructions?: never;
 });
 /** Exact prepared-request accounting; token values exist only with an explicit model counter. */
 export interface ModelInputMeasurement {
+    /** Characters of the message content. */
     readonly messageChars: number;
+    /** Characters of the instruction text. */
     readonly instructionChars: number;
+    /** Characters of the compiled capability schemas. */
     readonly schemaChars: number;
+    /** Characters the transport itself contributes (for example framing). */
     readonly transportChars: number;
+    /** Sum of the character components above. */
     readonly inputChars: number;
+    /** Character budget the input was compared against. */
     readonly maxInputChars: number;
+    /** Schema budget the input was compared against. */
     readonly maxSchemaChars: number;
+    /** Output tokens reserved for this call, which reduces the token input ceiling. */
     readonly maxOutputTokens: number;
+    /** Tokenizer identity; present only when a token budget applies. */
     readonly counterId?: string;
+    /** Measured input tokens. */
     readonly inputTokens?: number;
+    /** Token ceiling after reserving output and the safety margin. */
     readonly inputTokenLimit?: number;
+    /** True when every applicable character and token budget accepted the input. */
     readonly withinBudget: boolean;
 }
-/** Request-bound, single-use transport snapshot. Repeated measurements do not prepare or spend calls. */
+/**
+ * Request-bound, single-use transport snapshot.
+ *
+ * Repeated measurements do not prepare or spend calls.
+ */
 export interface PreparedModelCall<Result = unknown> extends PreparedModelTransport<Result> {
+    /** Model binding the call was prepared with. */
     readonly modelId?: string;
     readonly stageId: string;
     readonly transportId: string;
     readonly maxOutputTokens: number;
+    /** Calls still available; a live value, so later spends are visible. */
     readonly remainingCalls: number;
+    /**
+     * Preflight measurement of one input shape.
+     *
+     * Never marks the call used and never charges the budget.
+     *
+     * @param input - Prompt string, message array or built context to measure.
+     * @returns Character and token sizes plus a `withinBudget` verdict.
+     */
     measure(input: string | readonly ModelMessage[] | BuiltContext): ModelInputMeasurement;
 }
+/** Transport selection for `prepare`; omitted fields take the runner defaults. */
 export interface ModelPrepareRequest<Transport = string> {
     readonly stageId?: string;
     readonly transport?: Transport;