@jangts/agent-core 0.1.1 → 0.2.0

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

@@ -1,17 +1,34 @@
-/** Tool references are registration facts, never permission or execution requirements. */
+/**
+ * Capability module catalog contract.
+ *
+ * Place in the package: Support-side composition only. Applications declare modules and the tools
+ * they contribute; the catalog validates those declarations once so Core can receive a stable
+ * description. It creates no Core execution entity and owns no domain lifecycle.
+ *
+ * Exports: `CapabilityToolReferences`, `CapabilityModule`, `CapabilityCatalogOptions`.
+ */
+/** Tool references declared by one owner module. */
 export interface CapabilityToolReferences {
+    /** Owner id; must be non-blank and is used in rejection messages. */
     readonly id: string;
+    /** Tools the module cannot work without; every id must be registered somewhere. */
     readonly requiredToolIds: readonly string[];
+    /** Tools the module uses when available; every id must be registered somewhere. */
     readonly optionalToolIds?: readonly string[];
 }
-/** Minimal composition contract; application lifecycle and domain fields remain application-owned. */
+/** Minimal composition contract; lifecycle and domain fields remain application-owned. */
 export interface CapabilityModule {
+    /** Unique module id; also the catalog key. */
     readonly id: string;
+    /** Non-blank description of what the module contributes. */
     readonly description: string;
+    /** Tools contributed by this module; ids must be unique across all modules. */
     readonly tools: readonly {
         readonly id: string;
     }[];
 }
+/** Catalog construction options. */
 export interface CapabilityCatalogOptions<Module extends CapabilityModule> {
+    /** Projects a module's tool references; must be synchronous and is checked at construction. */
     readonly toolReferences?: (module: Readonly<Module>) => readonly CapabilityToolReferences[];
 }

package/dist/esm/structs/support/context-processing.d.ts

@@ -1,22 +1,46 @@
+/**
+ * Context processing contract used by Support's context engine.
+ *
+ * Core keeps the trust, budget and structural-audit guarantees; these declarations describe the
+ * App-supplied policies, reductions, compressors and selectors that the engine applies in a fixed
+ * order. Each mode, kind and handler is a registered entry, so validation and execution read the
+ * same declaration.
+ *
+ * Exports: `ContextHistoryGrouping`, `ContextRecentHistory`, `ContextHandlerReference`,
+ * `ContextReduction`, `ContextSelection`, `ContextSelectionCandidate`, `ContextTokenMeasurement`,
+ * `ContextSelectionCall`, `ContextSelector`, `ContextPolicy`, `ContextCompressionCall`,
+ * `ContextCompressor`, `ContextProcessingReport`, `ContextModelRequest`, `ContextModelCall`,
+ * `ContextProcessingOptions`.
+ */
 import type { ContextFragment, BuiltContext } from '../context/fragments.js';
 import type { ExecutionContext } from '../common.js';
 import type { ModelResult } from '../invocation.js';
 import type { ModelMessage } from '../model/messages.js';
+/** How a message history is split into groups for trimming. */
 export type ContextHistoryGrouping = {
     kind: 'fixed';
     size: number;
 } | {
     kind: 'user-turn';
 };
+/** Recent history that compression must keep verbatim. */
 export interface ContextRecentHistory {
+    /** Field holding the history value inside the fragment. */
     field: string;
+    /** Number of trailing groups to keep. */
     keepGroups: number;
+    /** Grouping rule; `user-turn` keeps whole conversational turns together. */
     grouping: ContextHistoryGrouping;
 }
+/** Reference to a registered compressor or selector handler. */
 export interface ContextHandlerReference {
+    /** Registered handler id; an unknown id is rejected before execution. */
     readonly handlerId: string;
 }
-export type ContextReduction = {
+/** One declared reduction step. */
+export type ContextReduction = 
+/** Trims a history field to `targetChars`, dropping whole groups beyond `keepGroups`. */
+{
     id: string;
     kind: 'trim';
     fragmentId: string;
@@ -24,17 +48,24 @@ export type ContextReduction = {
     targetChars: number;
     grouping: ContextHistoryGrouping;
     keepGroups: number;
-} | ({
+}
+/** Rewrites one fragment through a registered compressor down to `targetChars`. */
+ | ({
     id: string;
     kind: 'compress';
     fragmentId: string;
     targetChars: number;
+    /** Recent history the compressor must preserve verbatim. */
     preserve?: ContextRecentHistory;
 } & ContextHandlerReference);
 /** Selection is independent of ownership; omitted selection preserves ordered execution. */
-export type ContextSelection = {
+export type ContextSelection = 
+/** Apply every declared step in order. */
+{
     mode: 'sequence';
-} | {
+}
+/** Apply only steps of the given kind. */
+ | {
     mode: 'fixed';
     kind: ContextReduction['kind'];
 }
@@ -43,47 +74,75 @@ export type ContextSelection = {
     mode: 'auto';
     maxTrimLossRatio?: number;
     reserveCalls?: number;
-} | ({
+}
+/** Ask a registered model selector; `reserveCalls` keeps calls for later stages. */
+ | ({
     mode: 'model';
     reserveCalls?: number;
 } & ContextHandlerReference);
+/** Candidate step considered by selection, with its measured cost. */
 export interface ContextSelectionCandidate {
     id: string;
     kind: ContextReduction['kind'];
     fragmentId: string;
+    /** Current size of the candidate fragment, in JSON characters. */
     chars: number;
+    /** Size the step would reduce the fragment to. */
     targetChars: number;
+    /** Model calls required to apply the step; 0 for local steps. */
     requiredCalls: number;
     /** Exact dry-run result for trim. Compression size is not predicted. */
     projectedChars?: number;
+    /** Fraction of characters removed by a trim step; meaningless for compression. */
     trimLossRatio?: number;
 }
+/** Injected token measurement for token-triggered policies. */
 export interface ContextTokenMeasurement {
+    /** Tokenizer identity, reported in the processing report. */
     counterId: string;
+    /** Input token ceiling the measurement is compared against. */
     inputLimit: number;
     measure(messages: readonly ModelMessage[]): number;
 }
+/** Everything a selector may inspect for one decision. */
 export interface ContextSelectionCall {
     readonly stageId: string;
+    /** Reducible candidates, already filtered and measured. */
     candidates: readonly ContextSelectionCandidate[];
     /** Only reducible fragments; never protected request or system fragments. */
     fragments: readonly ContextFragment[];
+    /** Current input tokens, when a token budget applies. */
     currentTokens?: number;
+    /** Tokens that must be removed to satisfy the token budget. */
     requiredReductionTokens?: number;
     currentChars: number;
+    /** Characters that must be removed to satisfy the character budget. */
     requiredReductionChars: number;
+    /** Calls the selector may still spend through `callModel`. */
     remainingCalls: number;
     callModel: ContextModelCall;
 }
+/** Model or local selector that chooses which reductions to apply. */
 export interface ContextSelector {
     id: string;
     /** Maximum model calls made through callModel, default 1; 0 permits a local selector. */
     maxCalls?: number;
+    /** Returns selected reduction ids; unknown ids are rejected. */
     select(call: ContextSelectionCall, context: ExecutionContext): Promise<readonly string[]>;
 }
-export type ContextPolicy = {
+/** Declared context policy for one stage. */
+export type ContextPolicy = 
+/** Validate trust and budgets without changing content. */
+{
     mode: 'validate';
-} | {
+}
+/**
+ * Reduce content when a trigger is exceeded.
+ *
+ * Character and token triggers/targets may be combined; `targetInputChars`/`targetInputTokens`
+ * define the size the reduction must reach.
+ */
+ | {
     mode: 'reduce';
     triggerChars?: number;
     targetInputChars?: number;
@@ -91,39 +150,52 @@ export type ContextPolicy = {
     targetInputTokens?: number;
     selection?: ContextSelection;
     steps: readonly ContextReduction[];
-} | {
+}
+/** Verify that only the listed fragments changed value, without reducing anything. */
+ | {
     mode: 'audit';
     mutableFragmentIds: readonly string[];
 };
+/** One compression request. */
 export interface ContextCompressionCall {
     readonly stageId: string;
+    /** Fragment to compress; its `targetChars` bound is enforced by the engine. */
     fragment: ContextFragment;
     targetChars: number;
-    /** Uses the same runner's call budget, timeout, transports and diagnostics. No recursive processing. */
+    /** Same runner's budget, timeout, transports and diagnostics. No recursive processing. */
     callModel: ContextModelCall;
 }
+/** Registered compressor handler. */
 export interface ContextCompressor {
     id: string;
     /** Maximum model calls through callModel, default 1; declare 0 for local compression. */
     maxCalls?: number;
+    /** Produces a replacement value no larger than the requested target where possible. */
     compress(call: ContextCompressionCall, context: ExecutionContext): Promise<ContextFragment['value']>;
 }
+/** Facts recorded for one processing run. */
 export interface ContextProcessingReport {
+    /** Policy mode that ran. */
     mode: ContextPolicy['mode'];
+    /** Selection mode applied, when the policy reduced content. */
     selection?: ContextSelection['mode'];
+    /** Per-step selection decisions, kept for auditing `auto` and `model` choices. */
     decisions?: {
         mode: ContextSelection['mode'];
         stepIds: string[];
         reason: string;
     }[];
+    /** Total characters before and after processing. */
     beforeChars: number;
     afterChars: number;
+    /** Token measurement, present only when a token budget was supplied. */
     tokens?: {
         counterId: string;
         before: number;
         after: number;
         inputLimit: number;
     };
+    /** Applied changes in execution order; `app` marks an App-supplied mutation. */
     changes: {
         id: string;
         kind: 'trim' | 'compress' | 'app';
@@ -132,6 +204,7 @@ export interface ContextProcessingReport {
         afterChars: number;
     }[];
 }
+/** One model call made on behalf of a selector or compressor. */
 export interface ContextModelRequest {
     readonly modelId?: string;
     readonly stageId: string;
@@ -143,11 +216,17 @@ export interface ContextModelRequest {
 export interface ContextModelCall {
     (request: ContextModelRequest): Promise<ModelResult<unknown>>;
 }
+/** Runtime inputs for one processing run. */
 export interface ContextProcessingOptions extends ExecutionContext {
+    /** Stage the processing belongs to; reported in diagnostics and selection calls. */
     readonly stageId: string;
+    /** Compressors available by handler id. */
     readonly compressors: readonly ContextCompressor[];
+    /** Selectors available by handler id; required only for model selection. */
     readonly selectors?: readonly ContextSelector[];
     readonly callModel: ContextModelCall;
+    /** Remaining model calls; used to reject unaffordable selections. */
     readonly remainingCalls?: () => number;
+    /** Token measurement; without it, token triggers and targets cannot apply. */
     readonly tokenBudget?: ContextTokenMeasurement;
 }

package/dist/esm/structs/support/context.d.ts

@@ -1,31 +1,59 @@
+/**
+ * Context builder contract.
+ *
+ * Place in the package: Support-side assembly helpers. A builder turns App fragment declarations
+ * into a `ContextPlan` or an assembled `BuiltContext`; ordering and metadata are compiled once,
+ * while values are produced per request. Reduction, selection and model execution stay with Core.
+ *
+ * Exports: `ContextProjection`, `ContextBuilderOptions`, `ContextAssemblyOptions`,
+ * `ContextFragmentConfig`, `ContextBuilder`.
+ */
 import type { ContextPlan } from '../context/processing.js';
 import type { ContextFragment, BuiltContext } from '../context/fragments.js';
+/** One declared projection: a single fragment or a placement expanded into fragments. */
 export type ContextProjection<Input, Id extends string = string, Placement extends string = string> = {
     readonly kind: 'fragment';
+    /** Fragment id; must be unique across all projections. */
     readonly id: Id;
+    /** Produces the fragment value; must be synchronous. */
     readonly format: (input: Input) => ContextFragment['value'];
-} | {
+}
+/** Expands to the fragments supplied for this placement; ids use a separate prefix. */
+ | {
     readonly kind: 'contributions';
     readonly placement: Placement;
 };
+/** Shared builder options. */
 export interface ContextBuilderOptions<Input> {
+    /** Character budget, constant or derived from the request; at least one of these is required. */
     readonly maxInputChars?: number | ((input: Input) => number);
+    /** Applied to every produced fragment before assembly; must be synchronous. */
     readonly transform?: (fragment: ContextFragment, input: Input) => ContextFragment;
 }
+/** Assembly options for placement-based projections. */
 export interface ContextAssemblyOptions<Input, Id extends string, Placement extends string> extends ContextBuilderOptions<Input> {
+    /** Builds a fragment for a single-fragment projection. */
     readonly fragment: (id: Id, value: ContextFragment['value']) => ContextFragment;
+    /** Contribution handlers keyed by placement; each expands to zero or more fragments. */
     readonly contributions?: Readonly<Record<Placement, (input: Input) => readonly ContextFragment[]>>;
 }
+/** Self-describing fragment declaration: metadata plus a formatter. */
 export interface ContextFragmentConfig<Input> extends Omit<ContextFragment, 'value'> {
+    /** Documentation only; not sent to the model. */
     readonly description?: string;
+    /** Produces the value; must be synchronous. */
     readonly format: (input: Input) => ContextFragment['value'];
 }
+/** Compiled builder. It holds no request state and may be shared across invocations. */
 export interface ContextBuilder<Input> {
+    /** Produces the fragments for one input, after transforms. */
     fragments(input: Input): ContextFragment[];
+    /** Assembles and validates the plan into messages with usage accounting. */
     build(request: {
         input: Input;
         maxInputChars?: number;
     } & Omit<ContextPlan, 'fragments' | 'maxInputChars'>): BuiltContext;
+    /** Produces the unassembled plan without running the budget boundary. */
     plan(request: {
         input: Input;
         maxInputChars?: number;

package/dist/esm/structs/support/model/completion.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Completion policy contract for the compatible provider.
+ *
+ * Place in the package: Support-side protocol decision. A policy decides whether one finished
+ * stream satisfies the request it answered. It owns no HTTP, cancellation, request building or
+ * tool execution, and a session exists per request so concurrent calls never share state.
+ *
+ * Exports: `CompletionRequestFacts`, `CompletionFailure`, `CompletionSession`, `CompletionPolicy`.
+ */
+import type { ModelPart } from '../../model/messages.js';
+import type { ModelProviderErrorCode } from './provider.js';
+/**
+ * Facts the provider reads from the request it actually sends.
+ *
+ * `functions` reports the Core call options and keeps the default policy equivalent to the
+ * behavior that existed before policies were configurable. `toolChoice` is the effective field of
+ * the serialized body, so a host override, or a field dropped for being `undefined`, is visible
+ * exactly as the upstream receives it.
+ */
+export interface CompletionRequestFacts {
+    /** Whether the call declared native functions through Core options. */
+    readonly functions: boolean;
+    /** Effective `tool_choice` of the request body; an absent field reads as `undefined`. */
+    readonly toolChoice?: unknown;
+    /** Whether an empty response is allowed because JSON mode permits it. */
+    readonly allowEmptyText: boolean;
+}
+/** Build the classified failure a policy throws; the provider records it like its own failures. */
+export type CompletionFailure = (code: ModelProviderErrorCode) => Error;
+/** Per-request completion state observed by one policy. */
+export interface CompletionSession {
+    /** Observe one part immediately before the provider yields it. */
+    part(part: ModelPart): void;
+    /** Observe the stream's single `finish_reason`. */
+    finish(reason: string): void;
+    /** Complete the response when the end-of-stream marker arrives. */
+    end(): void;
+}
+/** Decision whether a finished stream satisfies the request. */
+export interface CompletionPolicy {
+    /** Registered identifier; the catalog key must match it. */
+    readonly id: string;
+    /**
+     * Start one request.
+     *
+     * Throwing here rejects the request before it is sent, which is how a policy refuses a request
+     * shape it cannot judge after the fact.
+     */
+    begin(facts: CompletionRequestFacts, fail: CompletionFailure): CompletionSession;
+}

package/dist/esm/structs/support/model/completion.js

@@ -0,0 +1 @@
+export {};

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

@@ -1,7 +1,19 @@
+/**
+ * Stage-scoped model transport contract.
+ *
+ * Place in the package: Support-side registration for transports that expose only the capabilities
+ * declared for each stage. Static sources are projected once; dynamic sources are re-projected at
+ * the model boundary. Either way, an undeclared stage or capability is rejected rather than
+ * silently omitted.
+ *
+ * Exports: `ModelInteractionAdapter`, `ModelTransportRegistration`, `NativeFunctionCall` (type
+ * re-exports) and `ModelStageTransportRegistration`.
+ */
 import type { ModelTransportRegistration } from '../../model/interactions.js';
-export type { ModelInteractionAdapter, ModelTransportRegistration, NativeFunctionCall } from '../../model/interactions.js';
+export type { ModelInteractionAdapter, ModelTransportRegistration, NativeFunctionCall, } from '../../model/interactions.js';
 /** Stage IDs and capability references are App-owned; this adapter only compiles their relation. */
 export interface ModelStageTransportRegistration<Result = unknown> extends ModelTransportRegistration<Result> {
+    /** Declared stages; each id is unique and lists non-empty, unique capability ids. */
     readonly stages: readonly {
         readonly id: string;
         readonly capabilityIds: readonly string[];

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

@@ -0,0 +1,52 @@
+/**
+ * Provider-level message shapes for direct compatible-provider use.
+ *
+ * Place in the package: Support-side input for hosts that keep their own tool thread. `ModelMessage`
+ * stays the Core contract and is unchanged; these shapes add the assistant tool declaration and the
+ * tool result, with role and field association enforced by the union and re-checked at runtime.
+ *
+ * Exports: `ProviderToolCall`, `ProviderSystemMessage`, `ProviderUserMessage`,
+ * `ProviderAssistantMessage`, `ProviderToolMessage`, `ProviderMessage`.
+ */
+import type { ModelImage } from '../../model/messages.js';
+/** One tool call the assistant declared, in wire order. */
+export interface ProviderToolCall {
+    /** Provider call ID, echoed by the matching tool result. */
+    readonly id: string;
+    /** Declared function name. */
+    readonly name: string;
+    /** Raw JSON arguments exactly as the provider produced them. */
+    readonly arguments: string;
+}
+export interface ProviderSystemMessage {
+    readonly role: 'system';
+    readonly content: string;
+    readonly images?: never;
+    readonly toolCallId?: never;
+    readonly toolCalls?: never;
+}
+export interface ProviderUserMessage {
+    readonly role: 'user';
+    readonly content: string;
+    readonly images?: readonly ModelImage[];
+    readonly toolCallId?: never;
+    readonly toolCalls?: never;
+}
+/** Assistant turn; `content` may be empty when the turn is only a tool declaration. */
+export interface ProviderAssistantMessage {
+    readonly role: 'assistant';
+    readonly content: string;
+    readonly images?: never;
+    readonly toolCallId?: never;
+    readonly toolCalls?: readonly ProviderToolCall[];
+}
+/** Tool result answering one declared call. */
+export interface ProviderToolMessage {
+    readonly role: 'tool';
+    readonly content: string;
+    readonly toolCallId: string;
+    readonly images?: never;
+    readonly toolCalls?: never;
+}
+/** Message list a host may pass to the compatible provider directly. */
+export type ProviderMessage = ProviderSystemMessage | ProviderUserMessage | ProviderAssistantMessage | ProviderToolMessage;

package/dist/esm/structs/support/model/messages.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/structs/support/model/provider-observer.d.ts

@@ -1,33 +1,51 @@
+/**
+ * Provider observation contract.
+ *
+ * Place in the package: optional, caller-owned logging around provider calls. Observations are
+ * best effort and never change provider results, cancellation or retry behaviour; payloads are
+ * built lazily and body capture happens only for explicitly accepted events.
+ *
+ * Exports: `ProviderEventPayloads`, `ProviderEventName`, `ProviderEventDescriptor`,
+ * `ProviderObservation`, `ProviderObserver`, `ProviderErrorCapture`.
+ */
 import type { ModelProviderContext } from '../../model/chat-provider.js';
-/** Support-owned wire observations. They are never emitted into Core diagnostics. */
+/** Payload of each provider event. Content-bearing events are accepted explicitly. */
 export interface ProviderEventPayloads {
+    /** Outbound request; contains prompt content. */
     'provider.request': {
         url: string;
         body: unknown;
     };
+    /** Response head; metadata only. */
     'provider.response': {
         status: number;
         requestId: string | null;
         contentType: string | null;
     };
+    /** One raw streamed frame; contains response content. */
     'provider.frame': {
         data: string;
     };
+    /** Upstream error body, captured only when accepted. */
     'provider.error-body': {
         status: number;
         body: string;
         truncated?: boolean;
     };
+    /** End of the call; `complete` is false when the stream ended without a payload. */
     'provider.end': {
         complete: boolean;
         error?: unknown;
     };
 }
+/** Union of provider event names. */
 export type ProviderEventName = keyof ProviderEventPayloads;
+/** Provider event name plus its content class. */
 export interface ProviderEventDescriptor {
     readonly event: ProviderEventName;
     readonly content: 'metadata' | 'content';
 }
+/** One observation: event name with its payload. */
 export type ProviderObservation = {
     [K in ProviderEventName]: {
         readonly event: K;
@@ -36,9 +54,12 @@ export type ProviderObservation = {
 }[ProviderEventName];
 /** The caller can correlate each observation using the original, request-local model options. */
 export interface ProviderObserver {
+    /** Returns false to skip an event; absent means accept every event. */
     accepts?(descriptor: ProviderEventDescriptor, options: Readonly<ModelProviderContext>): boolean;
+    /** Handles one observation. Throwing or rejecting never affects the provider call. */
     write(event: ProviderObservation, options: Readonly<ModelProviderContext>): void | Promise<void>;
 }
+/** Captured upstream error body and whether it had to be truncated. */
 export interface ProviderErrorCapture {
     body: string;
     truncated: boolean;

package/dist/esm/structs/support/model/provider.d.ts

@@ -1,34 +1,86 @@
+/**
+ * OpenAI-compatible provider contract.
+ *
+ * Place in the package: Support-side adapter configuration. Request identity, input, streaming and
+ * budgets belong to the adapter; these types only declare what the App may configure and which
+ * failures the adapter reports. Nothing here performs I/O.
+ *
+ * Exports: `ModelProviderErrorCode`, `ModelProviderFailure`, `ProviderReasoningLevel`,
+ * `ProviderReasoningStrategy`, `CompatibleModelConfig`, `CompatibleModelPorts`, `ModelChoiceIndex`,
+ * `CompatibleModelProviderOptions`, plus the provider observation type re-exports.
+ */
+import type { CompletionPolicy } from './completion.js';
 import type { ProviderObserver } from './provider-observer.js';
-export type ModelProviderErrorCode = 'MODEL_NOT_CONFIGURED' | 'MODEL_AUTH' | 'MODEL_BALANCE' | 'MODEL_BUSY' | 'MODEL_CONFIG' | 'MODEL_UPSTREAM' | 'MODEL_FORMAT' | 'MODEL_PROTOCOL' | 'MODEL_OUTPUT_LIMIT' | 'MODEL_INCOMPLETE';
+/** Stable failure classification reported by the compatible provider adapter. */
+export type ModelProviderErrorCode = 
+/** Required configuration is missing, for example an empty API key. */
+'MODEL_NOT_CONFIGURED'
+/** Upstream rejected the credentials (HTTP 401/403). */
+ | 'MODEL_AUTH'
+/** Upstream reported exhausted balance or quota (HTTP 402). */
+ | 'MODEL_BALANCE'
+/** Upstream is rate limiting or overloaded (HTTP 429). */
+ | 'MODEL_BUSY'
+/** The request itself is invalid (HTTP 400/404 or configuration validation). */
+ | 'MODEL_CONFIG'
+/** Unclassified upstream failure. */
+ | 'MODEL_UPSTREAM'
+/** Response body could not be parsed as the expected wire format. */
+ | 'MODEL_FORMAT'
+/** The stream violated the protocol, for example data after the finish marker. */
+ | 'MODEL_PROTOCOL'
+/** The provider stopped because the output token limit was reached. */
+ | 'MODEL_OUTPUT_LIMIT'
+/** The stream ended without a usable payload. */
+ | 'MODEL_INCOMPLETE';
+/** Failure detail passed to the App's error factory. */
 export interface ModelProviderFailure {
     code: ModelProviderErrorCode;
+    /** HTTP status when the failure came from a response. */
     status?: number;
+    /** `eof` marks a stream that ended before the finish marker. */
     reason?: 'eof';
 }
 /** Supplier wire shape is explicit; levels express requested effort, not measured quality. */
 export type ProviderReasoningLevel = 'off' | 'low' | 'medium' | 'high';
+/**
+ * How a reasoning level is translated into request fields.
+ *
+ * `requestBody` entries override generated fields, so a host can correct a provider that expects
+ * a different shape.
+ */
 export type ProviderReasoningStrategy = {
     readonly level: ProviderReasoningLevel;
-} & ({
+} & 
+/** Uses the fixed field shape of the named format, with no extra mapping or budgets. */
+({
     readonly format: 'reasoning-effort' | 'thinking' | 'enable-thinking';
     readonly map?: never;
     readonly budgets?: never;
-} | {
+}
+/** Sends `thinking.budget_tokens`; defaults are 1024/4096/8192 for low/medium/high. */
+ | {
     readonly format: 'thinking-budget';
     readonly budgets?: Readonly<Partial<Record<Exclude<ProviderReasoningLevel, 'off'>, number>>>;
     readonly map?: never;
-} | {
+}
+/** Delegates field generation to the App mapper; must be synchronous. */
+ | {
     readonly format: 'custom';
     map(level: ProviderReasoningLevel): Readonly<Record<string, unknown>>;
     readonly budgets?: never;
 });
+/** Configuration of one OpenAI-compatible endpoint. */
 export interface CompatibleModelConfig {
+    /** Endpoint base URL, for example the chat-completions root. */
     baseUrl: string;
+    /** Credential sent as a bearer token; must be non-empty at request time. */
     apiKey: string;
+    /** Model name sent with the request. */
     model: string;
     /** Optional provider ceiling; otherwise use the call's limit or the Core default. */
     maxOutputTokens?: number;
-    /** Provider-specific extensions. Request identity, input, streaming and budget belong to the adapter. */
+    /** Provider extensions. Identity, input, streaming and budget stay in the adapter. */
     requestBody?: Readonly<Record<string, unknown>> & {
         readonly model?: never;
         readonly messages?: never;
@@ -37,15 +89,23 @@ export interface CompatibleModelConfig {
         readonly max_completion_tokens?: never;
         readonly toJSON?: never;
     };
+    /** Sampling temperature forwarded to the provider. */
     temperature?: number;
     /** Generated reasoning fields are overridden by explicit requestBody fields. */
     reasoning?: ProviderReasoningStrategy;
 }
+/** Adapter ports the App may override without replacing the provider. */
 export interface CompatibleModelPorts {
+    /** Fetch implementation; defaults to the global `fetch`. */
     request?: typeof fetch;
+    /** Builds the thrown error for a classified failure. */
     error?(failure: ModelProviderFailure): Error;
+    /** Prefix a JSON instruction when the prompt does not already mention JSON. */
     ensureJsonInstruction?: boolean;
+    /** Accept an empty JSON response instead of reporting `MODEL_INCOMPLETE`. */
     allowEmptyJson?: boolean;
+    /** Decide whether a finished stream satisfies the request; defaults to the legacy rules. */
+    completionPolicy?: CompletionPolicy;
     /** Optional Support observations, collected by the caller independently of Core diagnostics. */
     observer?: ProviderObserver;
 }
@@ -53,13 +113,18 @@ export interface CompatibleModelPorts {
 export interface ModelChoiceIndex {
     index: number;
 }
-export type { ProviderObserver, ProviderObservation, ProviderEventName, ProviderEventPayloads, ProviderEventDescriptor, ProviderErrorCapture } from './provider-observer.js';
+export type { ProviderObserver, ProviderObservation, ProviderEventName, ProviderEventPayloads, ProviderEventDescriptor, ProviderErrorCapture, } from './provider-observer.js';
+/** Construction options for a compatible provider. */
 export interface CompatibleModelProviderOptions {
+    /** Static configuration, or a factory evaluated at each request boundary. */
     readonly config: CompatibleModelConfig | (() => CompatibleModelConfig);
+    /** Port overrides other than observation and error mapping, which have their own keys. */
     readonly ports?: Omit<CompatibleModelPorts, 'observer' | 'error'>;
+    /** Provider observation sink. */
     readonly observe?: {
         readonly provider?: ProviderObserver;
     };
+    /** Error factory for classified failures. */
     readonly errors?: {
         readonly failure?: (failure: ModelProviderFailure) => Error;
     };