@jangts/agent-core 0.1.1 → 0.2.1

package/dist/esm/support/model/reply-preview.js

@@ -1,3 +1,12 @@
+/**
+ * Incremental reply preview: project partial model output into presentable bubbles.
+ *
+ * The projection is a lexical scan, deliberately separate from authoritative JSON or schema
+ * validation, and it only reads explicitly registered prose fields. It is presentation only: it
+ * must never authorize, persist or execute a proposal.
+ *
+ * Main export: `createReplyPreview` and its rule/settings types.
+ */
 import { synchronous } from '../../utils/synchronous.js';
 /** Incremental lexical projection, deliberately separate from authoritative JSON/schema validation. */
 class StringProjection {
@@ -41,7 +50,16 @@ class StringProjection {
                     if (ch === 'u')
                         token.unicode = '';
                     else {
-                        const escapes = { '"': '"', '\\': '\\', '/': '/', b: '\b', f: '\f', n: '\n', r: '\r', t: '\t' };
+                        const escapes = {
+                            '"': '"',
+                            '\\': '\\',
+                            '/': '/',
+                            b: '\b',
+                            f: '\f',
+                            n: '\n',
+                            r: '\r',
+                            t: '\t',
+                        };
                         if (!(ch in escapes))
                             throw new Error('Invalid escape');
                         token.text += escapes[ch];
@@ -86,7 +104,9 @@ class StringProjection {
             }
             const frame = this.stack.at(-1);
             if (ch === '}' || ch === ']') {
-                if (!frame || (ch === '}' ? frame.kind !== '{' : frame.kind !== '[') || !['key', 'value', 'comma'].includes(frame.state))
+                if (!frame ||
+                    (ch === '}' ? frame.kind !== '{' : frame.kind !== '[') ||
+                    !['key', 'value', 'comma'].includes(frame.state))
                     throw new Error('Invalid close');
                 this.stack.pop();
                 this.complete();
@@ -108,8 +128,16 @@ class StringProjection {
                 if (!frame || !['key', 'value'].includes(frame.state))
                     throw new Error('Invalid string position');
                 const key = frame.state === 'key', path = this.path();
-                const projected = !key && this.paths.some(pattern => path.length === pattern.length && pattern.every((key, i) => key === '*' ? /^\d+$/.test(path[i]) : key === path[i]));
-                this.token = { key, path, text: '', projectionKey: projected ? JSON.stringify(path) : undefined, escape: false };
+                const projected = !key &&
+                    this.paths.some((pattern) => path.length === pattern.length &&
+                        pattern.every((key, i) => (key === '*' ? /^\d+$/.test(path[i]) : key === path[i])));
+                this.token = {
+                    key,
+                    path,
+                    text: '',
+                    projectionKey: projected ? JSON.stringify(path) : undefined,
+                    escape: false,
+                };
                 continue;
             }
             if (frame && frame.state !== 'value')
@@ -120,23 +148,46 @@ class StringProjection {
             if (ch === '{' || ch === '[') {
                 if (this.stack.length >= 32)
                     throw new Error('Too deep');
-                this.stack.push({ path: this.path(), kind: ch, state: ch === '{' ? 'key' : 'value', index: 0, keys: new Set() });
+                this.stack.push({
+                    path: this.path(),
+                    kind: ch,
+                    state: ch === '{' ? 'key' : 'value',
+                    index: 0,
+                    keys: new Set(),
+                });
             }
             else
                 this.primitive = true;
         }
     }
-    string(path) { const key = JSON.stringify(path); return this.completedStrings.has(key) ? this.values.get(key)?.text : undefined; }
+    string(path) {
+        const key = JSON.stringify(path);
+        return this.completedStrings.has(key) ? this.values.get(key)?.text : undefined;
+    }
     texts(paths = this.paths) {
         // Later bubbles can arrive first in JSON; keep their indices stable until the leading prose exists.
         const first = paths[0];
         if (first && !first.includes('*') && !this.values.has(JSON.stringify(first)))
             return [];
-        return paths.flatMap(pattern => [...this.values.values()].filter(({ path }) => path.length === pattern.length && pattern.every((key, i) => key === '*' ? /^\d+$/.test(path[i]) : key === path[i]))
-            .sort((a, b) => Number(a.path.at(-1)) - Number(b.path.at(-1)))).map(value => value.text);
+        return paths
+            .flatMap((pattern) => [...this.values.values()]
+            .filter(({ path }) => path.length === pattern.length &&
+            pattern.every((key, i) => (key === '*' ? /^\d+$/.test(path[i]) : key === path[i])))
+            .sort((a, b) => Number(a.path.at(-1)) - Number(b.path.at(-1))))
+            .map((value) => value.text);
     }
 }
-/** Only explicitly registered prose fields are projected. Tools/reviews are never selected implicitly. */
+/**
+ * Create a model-output event handler that publishes preview bubbles.
+ *
+ * The handler resets on `model.start`, ignores other invocations, disables itself on unexpected
+ * output, and clears the preview when a call ends unsuccessfully. Rules are snapshotted at
+ * creation, and only explicitly registered prose fields are projected.
+ *
+ * @param options Rules, optional renderer, character budget and the bubble sink.
+ * @returns An async handler for `ModelOutputEvent`.
+ * @throws {TypeError} When the sink is missing or `maxChars` is not a positive integer.
+ */
 export function createReplyPreview(options) {
     if (typeof options.sink !== 'function')
         throw new TypeError('A reply preview sink is required');
@@ -144,7 +195,7 @@ export function createReplyPreview(options) {
     const maxChars = options.maxChars ?? 16000;
     if (!Number.isSafeInteger(maxChars) || maxChars < 1)
         throw new TypeError('Invalid reply preview budget');
-    const rules = options.rules.map(rule => Object.freeze({
+    const rules = options.rules.map((rule) => Object.freeze({
         capabilityId: rule.capabilityId,
         stageId: rule.stageId,
         paths: rule.paths === undefined ? undefined : structuredClone(rule.paths),
@@ -155,10 +206,13 @@ export function createReplyPreview(options) {
     let selected;
     let activeCall;
     const publish = async (texts) => {
-        // Hold incomplete surrogate pairs and never show internal control characters.
+        // Hold incomplete surrogate pairs and never show internal control characters. The bubble cap
+        // is independent of `maxChars`: at most five bubbles and 16000 characters reach the sink.
         let remaining = 16000;
-        const bubbles = texts.slice(0, 5).map(text => {
-            const value = (render ? synchronous(render(text), 'Reply preview renderers must be synchronous') : text).slice(0, remaining).replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]|[\ud800-\udbff]$/gu, '');
+        const bubbles = texts.slice(0, 5).map((text) => {
+            const value = (render ? synchronous(render(text), 'Reply preview renderers must be synchronous') : text)
+                .slice(0, remaining)
+                .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]|[\ud800-\udbff]$/gu, '');
             remaining -= value.length;
             return value;
         });
@@ -194,14 +248,17 @@ export function createReplyPreview(options) {
         if (disabled)
             return;
         const part = event.payload.part;
-        chars += typeof part === 'string' ? part.length : (part.name?.length ?? 0) + (part.arguments?.length ?? 0);
+        chars +=
+            typeof part === 'string'
+                ? part.length
+                : (part.name?.length ?? 0) + (part.arguments?.length ?? 0);
         if (chars > maxChars) {
             disabled = true;
             await publish([]);
             return;
         }
         if (typeof part === 'string') {
-            const rule = rules.find(rule => !rule.capabilityId && rule.stageId === event.payload.stageId);
+            const rule = rules.find((rule) => !rule.capabilityId && rule.stageId === event.payload.stageId);
             if (!rule) {
                 if (part.trim()) {
                     disabled = true;
@@ -219,7 +276,7 @@ export function createReplyPreview(options) {
             return;
         }
         name += part.name ?? '';
-        const rule = rules.find(rule => rule.capabilityId === name && (!rule.stageId || rule.stageId === event.payload.stageId));
+        const rule = rules.find((rule) => rule.capabilityId === name && (!rule.stageId || rule.stageId === event.payload.stageId));
         if (!rule) {
             if (selected) {
                 disabled = true;
@@ -232,7 +289,10 @@ export function createReplyPreview(options) {
         try {
             if (!selected) {
                 selected = rule;
-                parser = new StringProjection([...(rule.paths ?? [['text'], ['bubbles', '*']]), ...(rule.when ? [rule.when.path] : [])]);
+                parser = new StringProjection([
+                    ...(rule.paths ?? [['text'], ['bubbles', '*']]),
+                    ...(rule.when ? [rule.when.path] : []),
+                ]);
                 parser.push(argumentsText);
                 argumentsText = '';
             }

package/dist/esm/support/model/stage-transport.d.ts

@@ -1,5 +1,13 @@
 import type { ModelStageTransportRegistration } from '../../structs/support/model/interactions.js';
-/** Compile static references now; dynamic sources are checked afresh at the model boundary. */
+/**
+ * Build a transport that projects a capability source through declared stage references.
+ *
+ * @param registration Transport declaration: unique ID, stage-to-capability references, interaction
+ *   adapter, options and a static or per-stage capability source.
+ * @returns A Core model transport with `capabilities(stage)`.
+ * @throws {Error} When a stage ID repeats, has no capability IDs, the declaration has no stages, a
+ *   stage or capability is not registered, or a dynamic capability source is asynchronous.
+ */
 export declare function createStageModelTransport<Result, const Id extends string = string>(registration: ModelStageTransportRegistration<Result> & {
     readonly id: Id;
 }): import("../../index.js").ModelTransportDefinition<Result> & {

package/dist/esm/support/model/stage-transport.js

@@ -1,14 +1,34 @@
+/**
+ * Stage-scoped model transport: expose only the capabilities declared for each stage.
+ *
+ * Static capability sources are projected once at construction; dynamic sources are re-projected
+ * at the model boundary. Either way, an undeclared stage or capability is rejected rather than
+ * silently omitted.
+ *
+ * Main export: `createStageModelTransport`.
+ */
 import { synchronous } from '../../utils/synchronous.js';
 import { ModelCapabilityRegistry } from '../../capabilities/model.js';
 import { breakWhile } from '../../utils/rules.js';
 import { createModelTransport } from './transports.js';
-/** Compile static references now; dynamic sources are checked afresh at the model boundary. */
+/**
+ * Build a transport that projects a capability source through declared stage references.
+ *
+ * @param registration Transport declaration: unique ID, stage-to-capability references, interaction
+ *   adapter, options and a static or per-stage capability source.
+ * @returns A Core model transport with `capabilities(stage)`.
+ * @throws {Error} When a stage ID repeats, has no capability IDs, the declaration has no stages, a
+ *   stage or capability is not registered, or a dynamic capability source is asynchronous.
+ */
 export function createStageModelTransport(registration) {
     const stages = new Map();
     for (const stage of registration.stages) {
         const ids = stage.capabilityIds;
-        breakWhile(!stage.id?.trim() || stages.has(stage.id) || !Array.isArray(ids) || !ids.length
-            || new Set(ids).size !== ids.length, `Invalid model stage: ${stage.id}`);
+        breakWhile(!stage.id?.trim() ||
+            stages.has(stage.id) ||
+            !Array.isArray(ids) ||
+            !ids.length ||
+            new Set(ids).size !== ids.length, `Invalid model stage: ${stage.id}`);
         stages.set(stage.id, Object.freeze([...ids]));
     }
     breakWhile(!stages.size, 'Model transport requires declared stages');
@@ -30,13 +50,19 @@ export function createStageModelTransport(registration) {
             },
         });
     };
-    const fixed = typeof source === 'function' ? undefined
-        : new Map([...stages.keys()].map(stage => [stage, project(stage, source)]));
+    const fixed = typeof source === 'function'
+        ? undefined
+        : new Map([...stages.keys()].map((stage) => [stage, project(stage, source)]));
     return createModelTransport({
-        id, adapter, options, requireStrictArguments,
+        id,
+        adapter,
+        options,
+        requireStrictArguments,
         capabilities(stage) {
             breakWhile(!stages.has(stage), `Unregistered model stage: ${id} -> ${stage}`);
-            return fixed ? fixed.get(stage) : project(stage, synchronous(source.call(registration, stage), 'Model capability sources must be synchronous'));
+            return fixed
+                ? fixed.get(stage)
+                : project(stage, synchronous(source.call(registration, stage), 'Model capability sources must be synchronous'));
         },
     });
 }

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

@@ -1,6 +1,13 @@
 import type { ExecutionOptions } from '../../structs/common.js';
 import type { ModelRunnerOptions, ModelRunnerSettings, ModelTransportDefinition } from '../../structs/model/runtime.js';
-/** Local admission and output allowances, never a claim about provider capacity or performance. */
+/**
+ * Budget presets by expected workload size.
+ *
+ * `maxCalls` counts model calls per run; `maxInputChars`/`maxOutputChars` are character budgets;
+ * `maxOutputTokens` is the per-call output reservation; `callTimeoutMs` bounds one call in
+ * milliseconds. These are local admission and output allowances, never a claim about provider
+ * capacity or performance.
+ */
 export declare const modelBudgetStrategies: Readonly<{
     small: Readonly<{
         maxCalls: 2;
@@ -24,17 +31,25 @@ export declare const modelBudgetStrategies: Readonly<{
         callTimeoutMs: 60000;
     }>;
 }>;
+/** Preset name, or an explicit partial set of Core runner settings. */
 export type ModelBudgetStrategy = keyof typeof modelBudgetStrategies | Partial<ModelRunnerSettings>;
 type StrategyModel<Transports extends readonly ModelTransportDefinition[], Execution> = Omit<ModelRunnerOptions<Transports>, 'execution'> & {
     execution?: Execution;
 };
+/**
+ * Input of `createModelStrategy`: model selection, optional reasoning and budget plus explicit
+ * Core overrides. Explicit Core fields win over every generated value.
+ */
 export type ModelStrategyOptions<Transports extends readonly ModelTransportDefinition[] = readonly ModelTransportDefinition[], Execution = ExecutionOptions> = Partial<StrategyModel<Transports, Execution>> & {
     /** An existing definition, or an ID in the explicitly supplied model catalog. */
     readonly model: StrategyModel<Transports, Execution> | string;
+    /** Named model definitions; required when `model` is a string ID. */
     readonly models?: Readonly<Record<string, StrategyModel<Transports, Execution>>>;
     /** Names and supplier-specific implementations are declared by the App, never guessed. */
     readonly reasoning?: string;
+    /** Per-reasoning overrides; entries are applied only when `reasoning` names them. */
     readonly reasoningOptions?: Readonly<Record<string, Partial<StrategyModel<Transports, Execution>>>>;
+    /** Preset name, or an explicit partial budget; defaults to `medium`. */
     readonly budget?: ModelBudgetStrategy;
 };
 type NamedDefinition<Catalog, Id> = Id extends string ? string extends Id ? Catalog[keyof Catalog] : Id extends keyof Catalog ? Catalog[Id] : never : never;
@@ -45,6 +60,17 @@ type ExecutionFrom<Source, Fallback> = Source extends unknown ? 'execution' exte
 type StrategyResult<Options extends ModelStrategyOptions> = Omit<ModelRunnerOptions<TransportsFrom<Options, TransportsFrom<SelectedReasoning<Options>, TransportsFrom<SelectedModel<Options>, readonly []>>>>, 'execution'> & {
     execution?: ExecutionFrom<Options, ExecutionFrom<SelectedReasoning<Options>, ExecutionFrom<SelectedModel<Options>, undefined>>>;
 };
-/** Preset < selected model < declared reasoning < exact budget < explicit Core fields. */
+/**
+ * Compose runner options in precedence order: budget preset, selected model, declared reasoning,
+ * exact budget, then explicit Core fields.
+ *
+ * The result is validated through the same Core binding rules but creates no runner and spends no
+ * calls.
+ *
+ * @param options Model selection, optional reasoning and budget, and explicit Core overrides.
+ * @returns A frozen, validated `ModelRunnerOptions` with inferred transport/execution types.
+ * @throws {TypeError} When a model ID is unknown, a string model is combined with inline
+ *   definitions, a reasoning name is unknown, or a budget field or preset is invalid.
+ */
 export declare function createModelStrategy<const Options extends ModelStrategyOptions>(options: Options): StrategyResult<Options>;
 export {};

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

@@ -1,18 +1,67 @@
+/**
+ * Model strategy presets: compose a Core `ModelRunnerOptions` from named sources.
+ *
+ * A strategy selects a model definition (inline or by catalog ID), optional reasoning variant and
+ * a budget preset, then layers any explicit Core fields last. Values are local admission
+ * allowances, not claims about provider capacity or performance.
+ *
+ * Main exports: `modelBudgetStrategies`, `createModelStrategy` and the strategy option types.
+ */
 import { snapshotModelBinding } from '../../model/binding.js';
-/** Local admission and output allowances, never a claim about provider capacity or performance. */
+/**
+ * Budget presets by expected workload size.
+ *
+ * `maxCalls` counts model calls per run; `maxInputChars`/`maxOutputChars` are character budgets;
+ * `maxOutputTokens` is the per-call output reservation; `callTimeoutMs` bounds one call in
+ * milliseconds. These are local admission and output allowances, never a claim about provider
+ * capacity or performance.
+ */
 export const modelBudgetStrategies = Object.freeze({
-    small: Object.freeze({ maxCalls: 2, maxInputChars: 8000, maxOutputChars: 4000, maxOutputTokens: 512, callTimeoutMs: 15000 }),
-    medium: Object.freeze({ maxCalls: 8, maxInputChars: 32000, maxOutputChars: 16000, maxOutputTokens: 1024, callTimeoutMs: 30000 }),
-    large: Object.freeze({ maxCalls: 16, maxInputChars: 64000, maxOutputChars: 32000, maxOutputTokens: 4096, callTimeoutMs: 60000 }),
+    small: Object.freeze({
+        maxCalls: 2,
+        maxInputChars: 8000,
+        maxOutputChars: 4000,
+        maxOutputTokens: 512,
+        callTimeoutMs: 15000,
+    }),
+    medium: Object.freeze({
+        maxCalls: 8,
+        maxInputChars: 32000,
+        maxOutputChars: 16000,
+        maxOutputTokens: 1024,
+        callTimeoutMs: 30000,
+    }),
+    large: Object.freeze({
+        maxCalls: 16,
+        maxInputChars: 64000,
+        maxOutputChars: 32000,
+        maxOutputTokens: 4096,
+        callTimeoutMs: 60000,
+    }),
 });
-// Exhaustiveness ensures new Core settings cannot silently disappear at this boundary.
+// Exhaustiveness ensures new Core settings cannot silently disappear at this boundary: adding a
+// setting to `ModelRunnerSettings` without listing it here fails type checking.
 const budgetSettingKeys = {
-    maxCalls: true, callTimeoutMs: true, maxOutputChars: true, usage: true,
-    children: true, maxInputChars: true, maxSchemaChars: true, tokenBudget: true, maxOutputTokens: true,
+    maxCalls: true,
+    callTimeoutMs: true,
+    maxOutputChars: true,
+    usage: true,
+    children: true,
+    maxInputChars: true,
+    maxSchemaChars: true,
+    tokenBudget: true,
+    maxOutputTokens: true,
 };
 const settingKeys = {
-    ...budgetSettingKeys, provider: true, execution: true, transports: true, sink: true, errors: true,
+    ...budgetSettingKeys,
+    provider: true,
+    execution: true,
+    transports: true,
+    sink: true,
+    errors: true,
 };
+// Copy only known Core keys, so helper fields such as `model`, `models` or `budget` in a selected
+// definition are not forwarded as runner options.
 function settings(source) {
     const result = {};
     for (const key of Object.keys(settingKeys))
@@ -38,20 +87,32 @@ export function createModelStrategy(options) {
     if (typeof model !== 'string' && models !== undefined)
         throw new TypeError('Use a model ID with configured models');
     const selected = typeof model === 'string'
-        ? models && Object.hasOwn(models, model) ? models[model] : undefined : model;
+        ? models && Object.hasOwn(models, model)
+            ? models[model]
+            : undefined
+        : model;
     if (!selected || typeof selected !== 'object')
         throw new TypeError(`Unknown model strategy: ${String(model)}`);
-    const reasoningSettings = reasoning === undefined ? undefined
-        : reasoningOptions && Object.hasOwn(reasoningOptions, reasoning) ? reasoningOptions[reasoning] : undefined;
+    const reasoningSettings = reasoning === undefined
+        ? undefined
+        : reasoningOptions && Object.hasOwn(reasoningOptions, reasoning)
+            ? reasoningOptions[reasoning]
+            : undefined;
     if (reasoning !== undefined && !reasoningSettings)
         throw new TypeError(`Unknown reasoning strategy: ${reasoning}`);
     if (typeof budget === 'string' && !Object.hasOwn(modelBudgetStrategies, budget))
         throw new TypeError(`Unknown model budget: ${budget}`);
-    if (!budget || (typeof budget !== 'string' && (typeof budget !== 'object' || Array.isArray(budget))))
+    if (!budget ||
+        (typeof budget !== 'string' && (typeof budget !== 'object' || Array.isArray(budget))))
         throw new TypeError('Invalid model budget strategy');
     const preset = typeof budget === 'string' ? modelBudgetStrategies[budget] : modelBudgetStrategies.medium;
-    const result = { ...preset, ...settings(selected), ...(reasoningSettings && settings(reasoningSettings)),
-        ...(typeof budget === 'object' && budgetSettings(budget)), ...settings(options) };
+    const result = {
+        ...preset,
+        ...settings(selected),
+        ...(reasoningSettings && settings(reasoningSettings)),
+        ...(typeof budget === 'object' && budgetSettings(budget)),
+        ...settings(options),
+    };
     // Validate through the same Core rules without creating a request runner or spending calls.
     snapshotModelBinding(result);
     return Object.freeze(result);

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

@@ -1,6 +1,12 @@
 import type { ModelOptions } from '../../structs/model/messages.js';
 import type { ModelTransportDefinition } from '../../structs/model/runtime.js';
 export { createModelTransport } from '../../model/selection-transport.js';
+/**
+ * Create a plain-text transport that trims the assembled response.
+ *
+ * @param definition Transport ID and optional temperature.
+ * @returns A frozen Core transport definition typed as string output.
+ */
 export declare function createTextTransport<const Id extends string>(definition: {
     readonly id: Id;
     readonly options?: Pick<ModelOptions, 'temperature'>;
@@ -8,7 +14,17 @@ export declare function createTextTransport<const Id extends string>(definition:
     readonly id: Id;
 };
 export type { ModelTransportRegistration } from '../../structs/support/model/interactions.js';
-/** Typed JSON values without a capability-selection envelope. */
+/**
+ * Create a typed JSON transport without a capability-selection envelope.
+ *
+ * The transport embeds the JSON Schema in the instruction and requires the response to be one
+ * complete JSON value. The returned response parser rejects native call events and invalid JSON,
+ * then validates the value through the supplied schema.
+ *
+ * @param definition Transport ID, output schema and optional temperature/json settings.
+ * @returns A frozen Core transport definition typed as `Output`.
+ * @throws {TypeError} When the ID is blank or the schema adapter cannot be snapshotted.
+ */
 export declare function createJsonTransport<Output, const Id extends string = string>(definition: {
     readonly id: Id;
     readonly outputSchema: import('../../structs/common.js').SchemaAdapter<Output>;

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

@@ -1,28 +1,67 @@
+/**
+ * Model transport creators for plain text and typed JSON values.
+ *
+ * Both produce Core `ModelTransportDefinition` objects with an ID, so a runner can select them by
+ * name. Neither invokes a model: preparation, response assembly and parsing stay in Core.
+ *
+ * Main exports: `createTextTransport`, `createJsonTransport`, `createModelTransport` and the
+ * transport registration type.
+ */
 import { snapshotSchemaAdapter } from '../../utils/schema-adapter.js';
 import { snapshotModelOptions } from '../../model/options.js';
 import { modelProtocolError } from '../../utils/model-protocol.js';
 import { createPlainTextTransport } from '../../model/transports.js';
 export { createModelTransport } from '../../model/selection-transport.js';
+/**
+ * Create a plain-text transport that trims the assembled response.
+ *
+ * @param definition Transport ID and optional temperature.
+ * @returns A frozen Core transport definition typed as string output.
+ */
 export function createTextTransport(definition) {
     return createPlainTextTransport(definition.id, definition.options);
 }
-/** Typed JSON values without a capability-selection envelope. */
+/**
+ * Create a typed JSON transport without a capability-selection envelope.
+ *
+ * The transport embeds the JSON Schema in the instruction and requires the response to be one
+ * complete JSON value. The returned response parser rejects native call events and invalid JSON,
+ * then validates the value through the supplied schema.
+ *
+ * @param definition Transport ID, output schema and optional temperature/json settings.
+ * @returns A frozen Core transport definition typed as `Output`.
+ * @throws {TypeError} When the ID is blank or the schema adapter cannot be snapshotted.
+ */
 export function createJsonTransport(definition) {
     const { id, outputSchema, options } = definition;
     if (typeof id !== 'string' || !id.trim())
         throw new TypeError('JSON transport requires an ID');
     const schema = snapshotSchemaAdapter(outputSchema);
-    const settings = Object.freeze({ ...snapshotModelOptions({ temperature: options?.temperature, json: options?.json ?? true }) });
-    const instruction = 'Return exactly one complete JSON value matching this JSON Schema: '
-        + JSON.stringify(schema.jsonSchema) + '\nReturn the value itself, without prose, fences, a schema document or a capability-selection envelope.';
-    return Object.freeze({ id, prepare() {
-            return { options: settings, instruction, schemaChars: instruction.length, createResponse() {
+    const settings = Object.freeze({
+        ...snapshotModelOptions({ temperature: options?.temperature, json: options?.json ?? true }),
+    });
+    const instruction = 'Return exactly one complete JSON value matching this JSON Schema: ' +
+        JSON.stringify(schema.jsonSchema) +
+        '\nReturn the value itself, without prose, fences, a schema document or a capability-selection envelope.';
+    return Object.freeze({
+        id,
+        prepare() {
+            return {
+                options: settings,
+                instruction,
+                schemaChars: instruction.length,
+                createResponse() {
                     let raw = '';
-                    return { get outputChars() { return raw.length; }, push(part) {
+                    return {
+                        get outputChars() {
+                            return raw.length;
+                        },
+                        push(part) {
                             if (typeof part !== 'string')
                                 modelProtocolError('JSON value transport does not accept native call events');
                             raw += part;
-                        }, finish() {
+                        },
+                        finish() {
                             let value;
                             try {
                                 value = JSON.parse(raw);
@@ -31,7 +70,10 @@ export function createJsonTransport(definition) {
                                 modelProtocolError('JSON value transport requires complete JSON');
                             }
                             return schema.parse(value);
-                        } };
-                } };
-        } });
+                        },
+                    };
+                },
+            };
+        },
+    });
 }

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

@@ -1,6 +1,25 @@
 import type { RegistrationDefinition } from '../structs/support/registration.js';
-/** Compile an installation plan once; predicates observe preceding installations at request time. */
+/**
+ * Compile an ordered installation plan.
+ *
+ * Predicates observe the effects of preceding installations at request time; a predicate that
+ * throws rejects the install instead of being treated as `false`. Callbacks are bound to their
+ * declaring definition so implementations may rely on `this`.
+ *
+ * @param definitions Registration steps in execution order.
+ * @returns A frozen catalog plus `install(context)`, which runs enabled steps sequentially.
+ * @throws {Error} When a `register` handler is missing or a `when` predicate is not a function.
+ */
 export declare function defineRegistrationCatalog<Context>(definitions: readonly RegistrationDefinition<Context>[]): Readonly<{
+    /**
+     * Run every enabled step in declaration order against `context`.
+     *
+     * Stops at the first failing predicate or handler; earlier installations are not rolled back.
+     *
+     * @param context Value passed to each predicate and registration handler.
+     * @throws {TypeError} When a predicate is asynchronous or does not return a boolean, or when
+     *   a handler is asynchronous.
+     */
     install(context: Context): void;
     definitions: readonly Readonly<{
         id: string;

package/dist/esm/support/registration.js

@@ -1,21 +1,63 @@
+/**
+ * Conditional registration support: compile an ordered list of install steps for an application.
+ *
+ * Steps are validated and bound once, then installed per invocation. Predicates run at install
+ * time and only see what previous steps already installed, so ordering is part of the contract.
+ * This is app-side composition for Core-facing handlers; it defines no new scheduling protocol.
+ *
+ * Main export: `defineRegistrationCatalog`.
+ */
 import { readonlyCatalog } from '../utils/catalog.js';
 import { synchronous, booleanResult } from '../utils/synchronous.js';
 import { breakWhile } from '../utils/rules.js';
-/** Compile an installation plan once; predicates observe preceding installations at request time. */
+/**
+ * Compile an ordered installation plan.
+ *
+ * Predicates observe the effects of preceding installations at request time; a predicate that
+ * throws rejects the install instead of being treated as `false`. Callbacks are bound to their
+ * declaring definition so implementations may rely on `this`.
+ *
+ * @param definitions Registration steps in execution order.
+ * @returns A frozen catalog plus `install(context)`, which runs enabled steps sequentially.
+ * @throws {Error} When a `register` handler is missing or a `when` predicate is not a function.
+ */
 export function defineRegistrationCatalog(definitions) {
-    const catalog = readonlyCatalog(definitions.map(definition => {
+    const catalog = readonlyCatalog(definitions.map((definition) => {
         const { id, when, register } = definition;
         breakWhile([
-            { occur: typeof register !== 'function', error: 'Missing registration handler', tags: ['handler'] },
-            { occur: when !== undefined && typeof when !== 'function', error: 'Invalid registration predicate', tags: ['predicate'] },
+            {
+                occur: typeof register !== 'function',
+                error: 'Missing registration handler',
+                tags: ['handler'],
+            },
+            {
+                occur: when !== undefined && typeof when !== 'function',
+                error: 'Invalid registration predicate',
+                tags: ['predicate'],
+            },
         ], ['agent-core', 'registration']);
-        return Object.freeze({ id, when: when?.bind(definition), register: register.bind(definition) });
-    }), id => new TypeError(`Unknown registration: ${id}`));
+        return Object.freeze({
+            id,
+            when: when?.bind(definition),
+            register: register.bind(definition),
+        });
+    }), (id) => new TypeError(`Unknown registration: ${id}`));
     return Object.freeze({
         ...catalog,
+        /**
+         * Run every enabled step in declaration order against `context`.
+         *
+         * Stops at the first failing predicate or handler; earlier installations are not rolled back.
+         *
+         * @param context Value passed to each predicate and registration handler.
+         * @throws {TypeError} When a predicate is asynchronous or does not return a boolean, or when
+         *   a handler is asynchronous.
+         */
         install(context) {
             for (const entry of catalog.definitions) {
-                const enabled = entry.when ? booleanResult(entry.when(context), 'Registration predicates must be synchronous', 'Registration predicates must return boolean') : true;
+                const enabled = entry.when
+                    ? booleanResult(entry.when(context), 'Registration predicates must be synchronous', 'Registration predicates must return boolean')
+                    : true;
                 if (enabled) {
                     synchronous(entry.register(context), 'Registration handlers must be synchronous');
                 }