@jangts/agent-core 0.1.1 → 0.2.0

package/dist/esm/support/context/strategies.js

@@ -1,67 +1,159 @@
+/**
+ * Context strategy presets: derive a validated reduction policy from history declarations.
+ *
+ * A strategy describes one historical fragment (its ID, JSON field and how much to keep) and
+ * generates either a trim step (`recent`) or a compression step (`continuity`). Generated steps and
+ * any explicit overrides are validated together, so the result can be passed straight to the
+ * context processing nodes.
+ *
+ * Main exports: `contextHistoryStrategies`, `createContextStrategy` and the strategy types.
+ */
 import { validateContextPolicy } from './processing.js';
 import { breakWhile } from '../../utils/rules.js';
-/** Character targets are local admission heuristics, not semantic retention guarantees. */
+/**
+ * Named history presets.
+ *
+ * `targetRatio` is the fraction of the fragment's own `maxChars` used as the reduction target;
+ * `keepGroups` is how many most-recent groups always stay verbatim. Both are local admission
+ * heuristics, not claims about semantic retention.
+ */
 export const contextHistoryStrategies = Object.freeze({
     compact: Object.freeze({ targetRatio: 0.25, keepGroups: 1 }),
     balanced: Object.freeze({ targetRatio: 0.5, keepGroups: 3 }),
     extended: Object.freeze({ targetRatio: 0.75, keepGroups: 6 }),
 });
 function recent({ id, targetChars, preserve }) {
-    return { step: { id: `${id}.window`, kind: 'trim', fragmentId: id, targetChars, ...preserve }, compressors: [] };
+    return {
+        step: { id: `${id}.window`, kind: 'trim', fragmentId: id, targetChars, ...preserve },
+        compressors: [],
+    };
 }
 function continuity({ options, id, targetChars, preserve }) {
     const compressor = options.compressor;
     breakWhile(!compressor, 'Continuity strategy requires a compressor');
-    return { step: { id: `${id}.summary`, kind: 'compress', fragmentId: id, targetChars, handlerId: compressor.id, preserve }, compressors: [compressor] };
+    return {
+        step: {
+            id: `${id}.summary`,
+            kind: 'compress',
+            fragmentId: id,
+            targetChars,
+            handlerId: compressor.id,
+            preserve,
+        },
+        compressors: [compressor],
+    };
 }
 /** The declared alternatives drive default selection and the generated operations together. */
 const contextStrategyCatalog = {
     recent: { operation: 'trim', build: recent },
     continuity: { operation: 'compress', build: continuity },
 };
-/** Local whole-turn window, or an old-turn summary with recent originals. Neither claims semantic quality. */
+/**
+ * Build a reduction policy from one or more history declarations.
+ *
+ * `recent` keeps a window of recent groups; `continuity` summarizes older groups while preserving
+ * the most recent originals. Neither preset claims semantic quality, only bounded input size.
+ *
+ * @param options One history declaration or an array of them. With an array, shared processing
+ *   settings must be passed in `settings`, not on individual items.
+ * @param settings Shared policy settings, overridden by single-item fields when one item is given.
+ * @returns A frozen strategy with the policy, its compressors and selectors.
+ * @throws {Error} When no history is declared, shared settings appear on array items, a preset or
+ *   allowance is invalid, or the generated selection has no matching step.
+ * @throws {ValidationError} When the resulting policy fails Core validation.
+ */
 export function createContextStrategy(options, settings = {}) {
-    const definitions = Array.isArray(options) ? options : [options];
+    const definitions = Array.isArray(options)
+        ? options
+        : [options];
     breakWhile(!definitions.length, 'Context strategy requires at least one history');
     const single = definitions.length === 1 ? definitions[0] : undefined;
     // Array items generate operations; global processing settings belong to the second argument.
-    if (!single && definitions.some(item => ['selection', 'steps', 'selectors', 'compressors', 'triggerChars', 'targetInputChars', 'triggerTokens', 'targetInputTokens'].some(key => key in item))) {
+    if (!single &&
+        definitions.some((item) => [
+            'selection',
+            'steps',
+            'selectors',
+            'compressors',
+            'triggerChars',
+            'targetInputChars',
+            'triggerTokens',
+            'targetInputTokens',
+        ].some((key) => key in item))) {
         throw new TypeError('Configure shared context strategy settings in the second argument');
     }
     const config = {};
-    const keys = ['selection', 'steps', 'selectors', 'compressors', 'triggerChars', 'targetInputChars', 'triggerTokens', 'targetInputTokens'];
+    const keys = [
+        'selection',
+        'steps',
+        'selectors',
+        'compressors',
+        'triggerChars',
+        'targetInputChars',
+        'triggerTokens',
+        'targetInputTokens',
+    ];
     for (const source of [single, settings])
         if (source)
             for (const key of keys)
                 if (key in source)
                     config[key] = source[key];
     const configured = config;
-    const generated = configured.steps !== undefined ? [] : definitions.map(options => {
-        const { kind, fragment, field } = options;
-        const preset = options.preset;
-        breakWhile(preset !== undefined && !Object.hasOwn(contextHistoryStrategies, preset), 'Unknown history strategy preset');
-        breakWhile(!Number.isSafeInteger(fragment.maxChars) || fragment.maxChars < 1, 'History strategy requires a positive fragment allowance');
-        const defaults = preset === undefined ? undefined : contextHistoryStrategies[preset];
-        const id = fragment.id, targetChars = options.targetChars ?? (defaults ? Math.max(1, Math.floor(fragment.maxChars * defaults.targetRatio)) : fragment.maxChars);
-        const grouping = options.grouping ?? { kind: 'user-turn' };
-        const preserve = { field, keepGroups: options.keepGroups ?? defaults?.keepGroups ?? 1,
-            grouping: grouping.kind === 'fixed' ? { kind: grouping.kind, size: grouping.size } : { kind: grouping.kind } };
-        breakWhile(!Object.hasOwn(contextStrategyCatalog, kind), 'Unknown context strategy');
-        return contextStrategyCatalog[kind].build({ options, id, targetChars, preserve });
-    });
-    const steps = configured.steps ?? generated.map(item => item.step);
-    const selection = configured.selection ?? (steps.length === 1 ? { mode: 'fixed', kind: steps[0].kind } : { mode: 'sequence' });
-    const compressors = [...generated.flatMap(item => item.compressors), ...(configured.compressors ?? [])];
+    const generated = configured.steps !== undefined
+        ? []
+        : definitions.map((options) => {
+            const { kind, fragment, field } = options;
+            const preset = options.preset;
+            breakWhile(preset !== undefined && !Object.hasOwn(contextHistoryStrategies, preset), 'Unknown history strategy preset');
+            breakWhile(!Number.isSafeInteger(fragment.maxChars) || fragment.maxChars < 1, 'History strategy requires a positive fragment allowance');
+            const defaults = preset === undefined ? undefined : contextHistoryStrategies[preset];
+            const id = fragment.id, targetChars = options.targetChars ??
+                (defaults
+                    ? Math.max(1, Math.floor(fragment.maxChars * defaults.targetRatio))
+                    : fragment.maxChars);
+            const grouping = options.grouping ?? { kind: 'user-turn' };
+            const preserve = {
+                field,
+                keepGroups: options.keepGroups ?? defaults?.keepGroups ?? 1,
+                grouping: grouping.kind === 'fixed'
+                    ? { kind: grouping.kind, size: grouping.size }
+                    : { kind: grouping.kind },
+            };
+            breakWhile(!Object.hasOwn(contextStrategyCatalog, kind), 'Unknown context strategy');
+            return contextStrategyCatalog[kind].build({ options, id, targetChars, preserve });
+        });
+    const steps = configured.steps ?? generated.map((item) => item.step);
+    // A single step needs no selection decision; several steps keep declared order.
+    const selection = configured.selection ??
+        (steps.length === 1
+            ? { mode: 'fixed', kind: steps[0].kind }
+            : { mode: 'sequence' });
+    const compressors = [
+        ...generated.flatMap((item) => item.compressors),
+        ...(configured.compressors ?? []),
+    ];
     const unique = new Map();
     for (const compressor of compressors) {
+        // The same handler may be referenced by several steps; a different object under one ID is
+        // ambiguous for the policy, so it is rejected instead of silently replaced.
         breakWhile(unique.has(compressor.id) && unique.get(compressor.id) !== compressor, `Conflicting context compressor: ${compressor.id}`);
         unique.set(compressor.id, compressor);
     }
     const selectors = [...(configured.selectors ?? [])];
-    const policy = { mode: 'reduce', steps: [...steps], selection,
-        triggerChars: configured.triggerChars, targetInputChars: configured.targetInputChars,
-        triggerTokens: configured.triggerTokens, targetInputTokens: configured.targetInputTokens };
-    breakWhile(selection.mode === 'fixed' && !steps.some(step => step.kind === selection.kind), 'Context strategy selection has no matching operation');
+    const policy = {
+        mode: 'reduce',
+        steps: [...steps],
+        selection,
+        triggerChars: configured.triggerChars,
+        targetInputChars: configured.targetInputChars,
+        triggerTokens: configured.triggerTokens,
+        targetInputTokens: configured.targetInputTokens,
+    };
+    breakWhile(selection.mode === 'fixed' && !steps.some((step) => step.kind === selection.kind), 'Context strategy selection has no matching operation');
     validateContextPolicy(policy, [...unique.values()], selectors);
-    return Object.freeze({ policy, compressors: Object.freeze([...unique.values()]), selectors: Object.freeze(selectors) });
+    return Object.freeze({
+        policy,
+        compressors: Object.freeze([...unique.values()]),
+        selectors: Object.freeze(selectors),
+    });
 }

package/dist/esm/support/index.d.ts

@@ -1,4 +1,12 @@
-/** Recommended implementations of Core contracts for application code. */
+/**
+ * Support entry point: app-side helpers that build Core-compatible configuration and handlers.
+ *
+ * Applications import from here and pass the results to Core. Core never imports this module;
+ * the helpers follow Core contracts and do not introduce a second scheduling protocol.
+ *
+ * Main exports: model transports and providers, context assembly and processing policies,
+ * registration and capability catalogs, tool definition helpers, schema adapters and transports.
+ */
 export * from './model/index.js';
 export * from './context/index.js';
 export * from './registration.js';

package/dist/esm/support/index.js

@@ -1,4 +1,12 @@
-/** Recommended implementations of Core contracts for application code. */
+/**
+ * Support entry point: app-side helpers that build Core-compatible configuration and handlers.
+ *
+ * Applications import from here and pass the results to Core. Core never imports this module;
+ * the helpers follow Core contracts and do not introduce a second scheduling protocol.
+ *
+ * Main exports: model transports and providers, context assembly and processing policies,
+ * registration and capability catalogs, tool definition helpers, schema adapters and transports.
+ */
 export * from './model/index.js';
 export * from './context/index.js';
 export * from './registration.js';

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

@@ -3,5 +3,15 @@ import type { ModelCapabilityRegistration, ModelCapabilityCatalog } from '../../
 type CapabilityOutput<Definition> = Definition extends {
     resolve(...args: any[]): infer Output;
 } ? Output : never;
+/**
+ * Build a sealed capability catalog from typed declarations.
+ *
+ * @param definitions Capabilities in declaration order; each needs a unique ID, a description and
+ *   an object-rooted input schema.
+ * @returns A frozen catalog exposing the registered definitions, lookup by ID and `resolve`.
+ * @throws {TypeError} When a declaration is invalid or duplicated, or when `require` receives an
+ *   unknown ID.
+ * @throws {Error} When a resolver is asynchronous.
+ */
 export declare function defineModelCapabilities<const Definitions extends readonly ModelCapabilityRegistration[]>(definitions: Definitions): ModelCapabilityCatalog<CapabilityOutput<Definitions[number]>>;
 export {};

package/dist/esm/support/model/capabilities.js

@@ -1,9 +1,28 @@
+/**
+ * Model capability catalog: seal a typed declaration list into a reusable catalog.
+ *
+ * The catalog is a frozen snapshot, so mutating the original declaration list cannot widen the
+ * result type or add capabilities at runtime. Resolution stays inside Core's registry; Support only
+ * projects the declarations and their output type.
+ *
+ * Main export: `defineModelCapabilities`.
+ */
 import { readonlyCatalog } from '../../utils/catalog.js';
 import { ModelCapabilityRegistry } from '../../capabilities/model.js';
+/**
+ * Build a sealed capability catalog from typed declarations.
+ *
+ * @param definitions Capabilities in declaration order; each needs a unique ID, a description and
+ *   an object-rooted input schema.
+ * @returns A frozen catalog exposing the registered definitions, lookup by ID and `resolve`.
+ * @throws {TypeError} When a declaration is invalid or duplicated, or when `require` receives an
+ *   unknown ID.
+ * @throws {Error} When a resolver is asynchronous.
+ */
 export function defineModelCapabilities(definitions) {
     const registry = new ModelCapabilityRegistry(definitions).seal();
     return Object.freeze({
-        ...readonlyCatalog(registry.definitions, id => new TypeError(`Unknown model capability: ${id}`)),
+        ...readonlyCatalog(registry.definitions, (id) => new TypeError(`Unknown model capability: ${id}`)),
         resolve: (selection, stage) => registry.resolve(selection, stage),
     });
 }

package/dist/esm/support/model/chat-completions.d.ts

@@ -1,18 +1,47 @@
+/**
+ * OpenAI-compatible chat-completions wire mapping.
+ *
+ * Pure format conversion: request fields, streamed deltas and message payloads. Credentials, HTTP,
+ * retries and business policy stay with the host; nothing here reads configuration or performs I/O.
+ *
+ * Main exports: `chatCompletionFunctionOptions`, `chatCompletionParts` and
+ * `chatCompletionMessages`.
+ */
 import type { ModelMessage, ModelOptions, ModelPart } from '../../structs/model/messages.js';
-/** OpenAI-compatible wire adapter only; credentials, HTTP and business policy belong to hosts. */
+import type { ProviderMessage } from '../../structs/support/model/messages.js';
+/**
+ * Build the tool-selection request fields for a function-calling stage.
+ *
+ * The adapter expects exactly one function call per response, so tool use is required and parallel
+ * calls are disabled.
+ *
+ * @param options Model options; absent `functions` means the stage has no tools.
+ * @returns Tool fields to merge into the request body, or an empty object.
+ * @throws {TypeError} When `functions` is present but empty.
+ */
 export declare function chatCompletionFunctionOptions(options: ModelOptions): Record<string, unknown>;
+/**
+ * Convert one streamed `choice.delta` into Core model parts.
+ *
+ * Text is emitted only when non-empty; each tool-call fragment carries its index so Core can
+ * reassemble arguments that arrive across chunks.
+ *
+ * @param delta Raw `delta` value from a chat-completions chunk.
+ * @returns Text and function-call-delta parts; an unrelated shape yields an empty array.
+ * @throws {ValidationError} When `tool_calls` or one of its entries has an invalid shape.
+ */
 export declare function chatCompletionParts(delta: unknown): ModelPart[];
-/** Preserve plain text requests; visual blocks are valid only on user messages. */
-export declare function chatCompletionMessages(messages: readonly ModelMessage[]): ({
-    role: "system" | "user" | "assistant";
-    content: string;
-} | {
-    content: ({
-        type: string;
-        image_url: import("../../index.js").ModelImage;
-    } | {
-        type: string;
-        text: string;
-    })[];
-    role: "system" | "user" | "assistant";
-})[];
+/**
+ * Map Core and provider messages to chat-completions message payloads.
+ *
+ * Only declared message fields are sent. Assistant tool declarations become nested
+ * `tool_calls`, and tool results become `tool_call_id`; both are rewritten explicitly rather than
+ * forwarded as-is. Messages with images become a content-block array; images are accepted only on
+ * user messages and only as `http(s)` or `data:image` URLs.
+ *
+ * @param messages Messages in prompt order, either Core messages or provider tool-thread messages.
+ * @returns Wire messages with `images` removed and content blocks where needed.
+ * @throws {TypeError} When a role and field do not belong together, or an image URL or detail level
+ *   is invalid.
+ */
+export declare function chatCompletionMessages(messages: readonly (ModelMessage | ProviderMessage)[]): Record<string, unknown>[];

package/dist/esm/support/model/chat-completions.js

@@ -1,17 +1,41 @@
 import { ValidationError } from '../../structs/errors.js';
-/** OpenAI-compatible wire adapter only; credentials, HTTP and business policy belong to hosts. */
+/**
+ * Build the tool-selection request fields for a function-calling stage.
+ *
+ * The adapter expects exactly one function call per response, so tool use is required and parallel
+ * calls are disabled.
+ *
+ * @param options Model options; absent `functions` means the stage has no tools.
+ * @returns Tool fields to merge into the request body, or an empty object.
+ * @throws {TypeError} When `functions` is present but empty.
+ */
 export function chatCompletionFunctionOptions(options) {
     if (!options.functions)
         return {};
     if (!options.functions.length)
         throw new TypeError('Empty model function catalog');
     return {
-        tools: options.functions.map(fn => ({ type: 'function', function: fn })),
-        tool_choice: 'required', parallel_tool_calls: false,
+        tools: options.functions.map((fn) => ({ type: 'function', function: fn })),
+        tool_choice: 'required',
+        parallel_tool_calls: false,
     };
 }
+/**
+ * Convert one streamed `choice.delta` into Core model parts.
+ *
+ * Text is emitted only when non-empty; each tool-call fragment carries its index so Core can
+ * reassemble arguments that arrive across chunks.
+ *
+ * @param delta Raw `delta` value from a chat-completions chunk.
+ * @returns Text and function-call-delta parts; an unrelated shape yields an empty array.
+ * @throws {ValidationError} When `tool_calls` or one of its entries has an invalid shape.
+ */
 export function chatCompletionParts(delta) {
-    const fail = () => { throw new ValidationError([{ code: 'MODEL_PROTOCOL', message: 'Invalid function call stream' }]); };
+    const fail = () => {
+        throw new ValidationError([
+            { code: 'MODEL_PROTOCOL', message: 'Invalid function call stream' },
+        ]);
+    };
     if (!delta || typeof delta !== 'object' || Array.isArray(delta))
         return [];
     const value = delta;
@@ -25,16 +49,21 @@ export function chatCompletionParts(delta) {
             if (!item || typeof item !== 'object' || Array.isArray(item))
                 fail();
             const call = item;
-            if (!Number.isInteger(call.index) || call.index < 0
-                || (call.id !== undefined && (typeof call.id !== 'string' || !call.id))
-                || (call.type !== undefined && call.type !== 'function'))
+            if (!Number.isInteger(call.index) ||
+                call.index < 0 ||
+                (call.id !== undefined && (typeof call.id !== 'string' || !call.id)) ||
+                (call.type !== undefined && call.type !== 'function'))
                 fail();
-            if (call.function !== undefined && (!call.function || typeof call.function !== 'object' || Array.isArray(call.function)))
+            if (call.function !== undefined &&
+                (!call.function || typeof call.function !== 'object' || Array.isArray(call.function)))
                 fail();
             const fn = (call.function ?? {});
-            if ((fn.name !== undefined && typeof fn.name !== 'string') || (fn.arguments !== undefined && typeof fn.arguments !== 'string'))
+            if ((fn.name !== undefined && typeof fn.name !== 'string') ||
+                (fn.arguments !== undefined && typeof fn.arguments !== 'string'))
                 fail();
-            parts.push({ type: 'function-call-delta', index: call.index,
+            parts.push({
+                type: 'function-call-delta',
+                index: call.index,
                 ...(call.id !== undefined ? { id: call.id } : {}),
                 ...(fn.name !== undefined ? { name: fn.name } : {}),
                 ...(fn.arguments !== undefined ? { arguments: fn.arguments } : {}),
@@ -43,21 +72,64 @@ export function chatCompletionParts(delta) {
     }
     return parts;
 }
-/** Preserve plain text requests; visual blocks are valid only on user messages. */
+/**
+ * Map Core and provider messages to chat-completions message payloads.
+ *
+ * Only declared message fields are sent. Assistant tool declarations become nested
+ * `tool_calls`, and tool results become `tool_call_id`; both are rewritten explicitly rather than
+ * forwarded as-is. Messages with images become a content-block array; images are accepted only on
+ * user messages and only as `http(s)` or `data:image` URLs.
+ *
+ * @param messages Messages in prompt order, either Core messages or provider tool-thread messages.
+ * @returns Wire messages with `images` removed and content blocks where needed.
+ * @throws {TypeError} When a role and field do not belong together, or an image URL or detail level
+ *   is invalid.
+ */
 export function chatCompletionMessages(messages) {
-    return messages.map(({ images, ...message }) => {
+    return messages.map((message) => {
+        const { role, content, images, toolCalls, toolCallId } = message;
+        if (!['system', 'user', 'assistant', 'tool'].includes(role) || typeof content !== 'string')
+            throw new TypeError('Invalid provider message role or content');
+        if (toolCallId !== undefined && role !== 'tool')
+            throw new TypeError('Tool results require the tool role');
+        if (role === 'tool' && (typeof toolCallId !== 'string' || !toolCallId))
+            throw new TypeError('Tool results require a tool call id');
+        if (toolCalls !== undefined && role !== 'assistant')
+            throw new TypeError('Tool calls require an assistant message');
+        const wire = { role, content };
+        if (toolCallId !== undefined)
+            wire.tool_call_id = toolCallId;
+        if (toolCalls !== undefined)
+            wire.tool_calls = toolCalls.map((call) => {
+                if (!call ||
+                    typeof call.id !== 'string' ||
+                    !call.id ||
+                    typeof call.name !== 'string' ||
+                    !call.name ||
+                    typeof call.arguments !== 'string')
+                    throw new TypeError('Invalid tool call');
+                return {
+                    id: call.id,
+                    type: 'function',
+                    function: { name: call.name, arguments: call.arguments },
+                };
+            });
         if (!images?.length)
-            return message;
-        if (message.role !== 'user')
+            return wire;
+        if (role !== 'user')
             throw new TypeError('Images require a user message');
         for (const image of images) {
-            if (!image.url || !/^(https?:\/\/|data:image\/)/i.test(image.url)
-                || (image.detail !== undefined && !['auto', 'low', 'high', 'original'].includes(image.detail)))
+            if (!image.url ||
+                !/^(https?:\/\/|data:image\/)/i.test(image.url) ||
+                (image.detail !== undefined && !['auto', 'low', 'high', 'original'].includes(image.detail)))
                 throw new TypeError('Invalid model image');
         }
-        return { ...message, content: [
-                { type: 'text', text: message.content },
-                ...images.map(image => ({ type: 'image_url', image_url: image })),
-            ] };
+        return {
+            ...wire,
+            content: [
+                { type: 'text', text: content },
+                ...images.map((image) => ({ type: 'image_url', image_url: image })),
+            ],
+        };
     });
 }

package/dist/esm/support/model/children.d.ts

@@ -1,15 +1,45 @@
+/**
+ * Child model-task group: run several Core child calls with bounded concurrency.
+ *
+ * Each task receives a Core child runner created from the parent's limits, so budgets, timeouts,
+ * transports and cancellation remain Core behavior. This module only schedules the group and
+ * orders acceptance and commit; it is optional app-side composition, not another scheduler
+ * protocol.
+ *
+ * Main exports: `runChildren` and its task/option types.
+ */
 import type { ModelRunner } from '../../model/runner.js';
 import type { ModelChildOptions } from '../../structs/model/runtime.js';
 import type { MaybePromise } from '../../structs/common.js';
 export interface ModelChildTask<Value> extends ModelChildOptions {
+    /**
+     * Work executed with the child runner bound to this task's limits.
+     *
+     * The supplied signal also aborts when a sibling fails, so long work should observe it.
+     */
     run(model: ModelRunner, signal: AbortSignal): MaybePromise<Value>;
 }
 export interface ModelChildrenOptions<Value> {
+    /** Parallel workers; defaults to, and may not exceed, the parent's concurrency limit. */
     readonly concurrency?: number;
+    /** Optional caller cancellation, combined with the parent signal and group failure. */
     readonly signal?: AbortSignal;
+    /** Called as each task finishes, before commit; must settle with `void`. */
     accept?(value: Value, id: string): MaybePromise<void>;
-    /** Called in declaration order after every result is accepted. App owns atomicity and receipts. */
+    /** Called in declaration order after every result is accepted; App owns atomicity/receipts. */
     commit?(value: Value, id: string): MaybePromise<void>;
 }
-/** Optional App-side composition of the existing child contract, not another scheduler protocol. */
+/**
+ * Run child tasks concurrently and return their values in declaration order.
+ *
+ * The first failure aborts the remaining group, but an already in-flight commit is still awaited
+ * because cancellation does not mean the write was rolled back.
+ *
+ * @param parent Parent runner supplying child creation, limits and cancellation.
+ * @param tasks Tasks to run; IDs must be unique and non-blank.
+ * @param options Concurrency, extra cancellation and accept/commit hooks.
+ * @returns Frozen values in declaration order.
+ * @throws {Error} When the concurrency, a task declaration or a duplicate ID is invalid.
+ * @throws The first task's error, or the combined signal's abort reason.
+ */
 export declare function runChildren<Value>(parent: Pick<ModelRunner, 'createChild' | 'childLimits' | 'signal'>, tasks: readonly ModelChildTask<Value>[], options?: ModelChildrenOptions<Value>): Promise<readonly Value[]>;

package/dist/esm/support/model/children.js

@@ -1,17 +1,41 @@
 import { awaitWithSignal, awaitAssertion, combineSignals } from '../../utils/cancellation.js';
 import { assertion } from '../../utils/synchronous.js';
 import { breakWhile } from '../../utils/rules.js';
-/** Optional App-side composition of the existing child contract, not another scheduler protocol. */
+/**
+ * Run child tasks concurrently and return their values in declaration order.
+ *
+ * The first failure aborts the remaining group, but an already in-flight commit is still awaited
+ * because cancellation does not mean the write was rolled back.
+ *
+ * @param parent Parent runner supplying child creation, limits and cancellation.
+ * @param tasks Tasks to run; IDs must be unique and non-blank.
+ * @param options Concurrency, extra cancellation and accept/commit hooks.
+ * @returns Frozen values in declaration order.
+ * @throws {Error} When the concurrency, a task declaration or a duplicate ID is invalid.
+ * @throws The first task's error, or the combined signal's abort reason.
+ */
 export async function runChildren(parent, tasks, options = {}) {
     const concurrency = options.concurrency ?? parent.childLimits.maxConcurrentCalls;
-    breakWhile(!Number.isSafeInteger(concurrency) || concurrency < 1 || concurrency > parent.childLimits.maxConcurrentCalls, 'Child group concurrency exceeds the parent policy');
+    breakWhile(!Number.isSafeInteger(concurrency) ||
+        concurrency < 1 ||
+        concurrency > parent.childLimits.maxConcurrentCalls, 'Child group concurrency exceeds the parent policy');
     const accept = options.accept?.bind(options), commit = options.commit?.bind(options);
-    const definitions = tasks.map(task => {
+    const definitions = tasks.map((task) => {
         const { id, maxCalls, reserveCalls, timeoutMs, transports, diagnostics, signal, run } = task;
         breakWhile(typeof id !== 'string' || !id.trim() || typeof run !== 'function', 'Invalid child task');
-        return { id, maxCalls, reserveCalls, timeoutMs, transports: transports === undefined ? undefined : [...transports], diagnostics, signal, run: run.bind(task) };
+        return {
+            id,
+            maxCalls,
+            reserveCalls,
+            timeoutMs,
+            transports: transports === undefined ? undefined : [...transports],
+            diagnostics,
+            signal,
+            run: run.bind(task),
+        };
     });
-    breakWhile(new Set(definitions.map(task => task.id)).size !== definitions.length, 'Duplicate child task id');
+    breakWhile(new Set(definitions.map((task) => task.id)).size !== definitions.length, 'Duplicate child task id');
+    // One group controller so the first failure cancels every sibling worker at once.
     const cancellation = new AbortController();
     const signal = combineSignals(parent.signal, cancellation.signal, options.signal);
     signal.throwIfAborted();
@@ -22,12 +46,16 @@ export async function runChildren(parent, tasks, options = {}) {
             const index = next++, definition = definitions[index];
             try {
                 signal.throwIfAborted();
-                const child = parent.createChild({ ...definition, signal: combineSignals(signal, definition.signal) });
+                const child = parent.createChild({
+                    ...definition,
+                    signal: combineSignals(signal, definition.signal),
+                });
                 const value = await awaitWithSignal(definition.run(child, child.signal), child.signal);
                 child.signal.throwIfAborted();
                 if (accept)
                     await awaitAssertion(() => accept(value, definition.id), child.signal, 'Child acceptance must return void');
                 child.signal.throwIfAborted();
+                // Index by declaration position so completion order never changes the result order.
                 values[index] = value;
             }
             catch (error) {

package/dist/esm/support/model/compatible-provider.d.ts

@@ -1,12 +1,38 @@
 import type { CompatibleModelProviderOptions } from '../../structs/support/model/provider.js';
 import { ChatProvider, type ModelProviderContext } from '../../structs/model/chat-provider.js';
 import type { ModelMessage, ModelPart } from '../../structs/model/messages.js';
-/** HTTP/SSE lifecycle shared by hosts. Apps supply config and user-visible error mapping only. */
+import type { ProviderMessage } from '../../structs/support/model/messages.js';
+/**
+ * HTTP/SSE lifecycle shared by hosts. Apps supply config and user-visible error mapping only.
+ *
+ * A static configuration is validated and frozen in the constructor. A configuration function is
+ * called once per request instead, so credentials and models may rotate between calls.
+ */
 export declare class CompatibleModelProvider extends ChatProvider {
     private readonly configuration;
     private readonly ports;
+    /**
+     * Create a provider.
+     *
+     * @param options Static or per-request configuration, optional ports and observation/error hooks.
+     * @throws {TypeError} When a static configuration is invalid (for example `maxTokens`,
+     *   reserved request-body fields, unsupported reasoning format or invalid budgets).
+     */
     constructor(options: CompatibleModelProviderOptions);
     private failure;
-    stream(messages: readonly ModelMessage[], context: ModelProviderContext): AsyncIterable<ModelPart>;
+    /**
+     * Stream one chat-completions response as Core model parts.
+     *
+     * The method validates the effective request and yields parts as they arrive. Whether the
+     * finished stream is acceptable is decided by the configured completion policy, which defaults
+     * to the legacy rules. A stream that ends without the end-of-stream marker is incomplete, not a
+     * partial success.
+     *
+     * @param messages Prompt messages in order, including provider tool-thread messages.
+     * @param context Provider context with signal, call options and diagnostics/observer ports.
+     * @yields Text chunks and function-call deltas as they arrive.
+     * @throws The classified provider error (see `MODEL_*` codes) or the signal's abort reason.
+     */
+    stream(messages: readonly (ModelMessage | ProviderMessage)[], context: ModelProviderContext): AsyncIterable<ModelPart>;
 }
-export type { ModelProviderErrorCode, ModelProviderFailure, CompatibleModelConfig, CompatibleModelPorts, CompatibleModelProviderOptions, ProviderReasoningLevel, ProviderReasoningStrategy } from '../../structs/support/model/provider.js';
+export type { ModelProviderErrorCode, ModelProviderFailure, CompatibleModelConfig, CompatibleModelPorts, CompatibleModelProviderOptions, ProviderReasoningLevel, ProviderReasoningStrategy, } from '../../structs/support/model/provider.js';