@jangts/agent-core 0.1.1 → 0.2.0

package/dist/esm/model/runner.js

@@ -1,3 +1,15 @@
+/**
+ * Model runner: the single path from prepared input to a validated result.
+ *
+ * This module is the model-facing protocol boundary. It owns, in strict order:
+ * cancellation, registration and budget checks, input measurement (characters, schema
+ * and tokens), budget charging, streaming through the transport's collector, then the
+ * journal entry, call trace and terminal event. Nothing here knows business prompts,
+ * stages or provider SDKs; those are registered by the App.
+ *
+ * Exports: `ModelRunner`, the re-exported `BudgetError`, and the runtime/config type
+ * re-exports at the bottom of the file.
+ */
 import { executionEvents } from '../execution/events.js';
 import { ModelCallBudget, parentModelBudget } from './call-budget.js';
 import { synchronous } from '../utils/synchronous.js';
@@ -5,7 +17,7 @@ import { awaitWithSignal, combineSignals, isTimeoutReason } from '../utils/cance
 import { invocationId, invocationResult } from '../utils/invocation.js';
 import { defaultTextTransport, modelRunnerDefaults } from './defaults.js';
 import { breakWhile } from '../utils/rules.js';
-import { compiledModelBinding, modelBindingId, snapshotModelBinding } from './binding.js';
+import { compiledModelBinding, modelBindingId, snapshotModelBinding, } from './binding.js';
 import { prepareModelTransport, preparedInputSize } from './preparation.js';
 import { getErrorInfo, recordErrorContext } from '../errors.js';
 import { modelInputTokenLimit, countModelInput, enforceModelInputTokens } from './token-budget.js';
@@ -18,19 +30,46 @@ import { ContextJournal } from '../context/journal.js';
 import { commonPrefixLength } from '../utils/text.js';
 import { modelProtocolError } from '../utils/model-protocol.js';
 import { abortableStream } from '@jangts/streaming/abortable-stream';
+// A context plan has no `messages` key yet; a built context carries already assembled ones.
 const isContextPlan = (input) => !Array.isArray(input) && !('messages' in input);
 const isMessageArray = (input) => Array.isArray(input);
+/**
+ * Validate a requested completion size.
+ *
+ * @param tokens - Requested output tokens.
+ * @param stageId - Stage used for error context.
+ * @throws TypeError When `tokens` is not a positive safe integer.
+ */
 function validateOutputTokens(tokens, stageId) {
-    breakWhile(!Number.isSafeInteger(tokens) || tokens < 1, () => recordErrorContext(new TypeError('maxOutputTokens must be a positive safe integer'), { stageId, codes: ['MODEL_CONFIG'], isRetryable: false }));
+    breakWhile(!Number.isSafeInteger(tokens) || tokens < 1, () => recordErrorContext(new TypeError('maxOutputTokens must be a positive safe integer'), {
+        stageId,
+        codes: ['MODEL_CONFIG'],
+        isRetryable: false,
+    }));
 }
 export { BudgetError } from '../structs/errors.js';
-/** No business prompts, domain stages or provider SDKs are built into this runner. */
+/**
+ * Execute registered model stages under one request's budgets and lifetime.
+ *
+ * Invariants: at most one call is in flight per runner; `callCount` and `journal` are
+ * local to the runner while `totalCallCount` includes descendants; every call is charged
+ * to the shared budget before I/O and every failure is annotated with its stage before it
+ * propagates. No business prompts, domain stages or provider SDKs are built into this
+ * runner.
+ */
 export class ModelRunner {
+    /** Record of parsed results for this runner; descendants keep their own journals. */
     journal = new ContextJournal();
     completedCallCount = 0;
     activeCall;
-    get callCount() { return this.completedCallCount; }
-    get lastCall() { return this.activeCall ? Object.freeze(structuredClone(this.activeCall)) : undefined; }
+    /** Completed calls observed by this runner only. */
+    get callCount() {
+        return this.completedCallCount;
+    }
+    /** Detached copy of the most recent call trace, or undefined before the first call. */
+    get lastCall() {
+        return this.activeCall ? Object.freeze(structuredClone(this.activeCall)) : undefined;
+    }
     priorInputs = new Map();
     tokenBudget;
     registeredTransports = new Map();
@@ -48,26 +87,60 @@ export class ModelRunner {
     depth = 0;
     inFlight = false;
     requestGate;
-    get childLimits() { return this.requestGate.limits; }
+    /** Limits shared by every runner of one request; children only read them. */
+    get childLimits() {
+        return this.requestGate.limits;
+    }
     /** Includes descendant attempts; local callCount and journal remain isolated. */
-    get totalCallCount() { return this.budget.used; }
-    /** A fresh runner, never a fork of conversation/journal/sinks. All ancestors retain their budgets. */
+    get totalCallCount() {
+        return this.budget.used;
+    }
+    /**
+     * Create a fresh runner for a nested stage.
+     *
+     * The child never inherits conversation, journal or sinks: only the provider, fixed
+     * limits, the parent budget and the child's own lifetime. All ancestors keep their
+     * budgets, and the child is charged through them, so nested work cannot overspend.
+     *
+     * @param options - Child id, call allowance, reserved calls, timeout and optional signals.
+     * @returns A runner sharing the request gate, with a budget derived from this one.
+     * @throws Error When the depth or child capacity is exhausted, a call is in flight,
+     * the settings are invalid, or the observer belongs to another run.
+     */
     createChild(options) {
         breakWhile(this.depth >= this.requestGate.limits.maxDepth, 'Nested model children exceed the request depth limit');
         breakWhile(this.inFlight, 'Cannot create a child while this model call is active');
         breakWhile(this.requestGate.children >= this.requestGate.limits.maxChildren, 'Model child capacity exhausted');
-        breakWhile(typeof options.id !== 'string' || !options.id.trim() || !Number.isSafeInteger(options.timeoutMs) || options.timeoutMs < 1 || options.timeoutMs > 2147483647, 'Invalid child execution settings');
+        breakWhile(typeof options.id !== 'string' ||
+            !options.id.trim() ||
+            !Number.isSafeInteger(options.timeoutMs) ||
+            options.timeoutMs < 1 ||
+            options.timeoutMs > 2147483647, 'Invalid child execution settings');
         const budget = this.budget.child(options.maxCalls, options.reserveCalls);
         const diagnostics = options.diagnostics ?? this.ports.diagnostics;
-        breakWhile(!!this.ports.diagnostics?.identity?.runId && !!diagnostics?.identity?.runId
-            && this.ports.diagnostics.identity.runId !== diagnostics.identity.runId, 'Child observation belongs to another run');
-        const childOptions = { provider: this.provider, [modelBindingId]: this.modelId, maxCalls: options.maxCalls,
-            callTimeoutMs: this.config.callTimeoutMs, maxInputChars: this.maxInputChars, maxOutputChars: this.config.maxOutputChars,
-            maxSchemaChars: this.ports.maxSchemaChars, maxOutputTokens: this.maxOutputTokens, tokenBudget: this.tokenBudget,
-            usage: this.config.usage, transports: options.transports,
+        breakWhile(!!this.ports.diagnostics?.identity?.runId &&
+            !!diagnostics?.identity?.runId &&
+            this.ports.diagnostics.identity.runId !== diagnostics.identity.runId, 'Child observation belongs to another run');
+        const childOptions = {
+            provider: this.provider,
+            [modelBindingId]: this.modelId,
+            maxCalls: options.maxCalls,
+            callTimeoutMs: this.config.callTimeoutMs,
+            maxInputChars: this.maxInputChars,
+            maxOutputChars: this.config.maxOutputChars,
+            maxSchemaChars: this.ports.maxSchemaChars,
+            maxOutputTokens: this.maxOutputTokens,
+            tokenBudget: this.tokenBudget,
+            usage: this.config.usage,
+            transports: options.transports,
             children: this.requestGate.limits,
-            execution: { signal: combineSignals(this.signal, AbortSignal.timeout(options.timeoutMs), options.signal),
-                diagnostics: diagnostics?.child(invocationId(), { definitionKind: 'agent', definitionId: options.id }) },
+            execution: {
+                signal: combineSignals(this.signal, AbortSignal.timeout(options.timeoutMs), options.signal),
+                diagnostics: diagnostics?.child(invocationId(), {
+                    definitionKind: 'agent',
+                    definitionId: options.id,
+                }),
+            },
         };
         const child = new ModelRunner(childOptions);
         child.budget = budget;
@@ -76,9 +149,19 @@ export class ModelRunner {
         child.requestGate = this.requestGate;
         return child;
     }
+    /**
+     * Build a runner from App options, or adopt an already compiled binding.
+     *
+     * Compiling here rather than per call is what makes configuration immutable for the
+     * runner's lifetime. The text transport is always registered first, then App
+     * transports in declaration order.
+     *
+     * @param options - Runner options; may carry a compiled binding and an inherited budget.
+     * @throws TypeError When settings, child limits or a transport are invalid.
+     * @throws ValidationError When the token budget contract is incomplete.
+     */
     constructor(options) {
-        const resolved = options[compiledModelBinding]
-            ?? snapshotModelBinding(options);
+        const resolved = options[compiledModelBinding] ?? snapshotModelBinding(options);
         this.budget = new ModelCallBudget(resolved.config.maxCalls, options[parentModelBudget]);
         this.requestGate = { active: 0, children: 0, limits: resolved.children };
         this.provider = resolved.provider;
@@ -87,7 +170,11 @@ export class ModelRunner {
         this.signal = options.execution?.signal ?? new AbortController().signal;
         this.maxOutputTokens = resolved.maxOutputTokens;
         this.maxInputChars = resolved.maxInputChars;
-        this.ports = Object.freeze({ ...resolved.ports, diagnostics: executionEvents(options.execution) ?? (resolved.ports.onOutput ? createDiagnostics() : undefined) });
+        this.ports = Object.freeze({
+            ...resolved.ports,
+            diagnostics: executionEvents(options.execution) ??
+                (resolved.ports.onOutput ? createDiagnostics() : undefined),
+        });
         this.execution = Object.freeze({ signal: this.signal, diagnostics: this.ports.diagnostics });
         this.tokenBudget = resolved.tokenBudget;
         this.transports.set(defaultTextTransport.id, defaultTextTransport);
@@ -96,7 +183,19 @@ export class ModelRunner {
             this.transports.set(definition.id, definition);
         }
     }
-    get remainingCalls() { return this.budget.remaining; }
+    /** Calls still available to this runner after the parent's reserve is applied. */
+    get remainingCalls() {
+        return this.budget.remaining;
+    }
+    /**
+     * Resolve the character limit for one input shape.
+     *
+     * A message array uses the runner limit; a built context or plan may declare a lower
+     * limit, and the stricter of the two wins so neither contract can be exceeded.
+     *
+     * @param input - Messages, built context or context plan.
+     * @returns The effective input character limit.
+     */
     inputLimit(input) {
         if (isMessageArray(input))
             return this.maxInputChars;
@@ -108,12 +207,32 @@ export class ModelRunner {
     async emitOutput(event, signal) {
         const sink = this.ports.onOutput;
         signal.throwIfAborted();
-        await awaitWithSignal(Promise.resolve().then(() => { signal.throwIfAborted(); return sink(event); }), signal);
+        await awaitWithSignal(Promise.resolve().then(() => {
+            signal.throwIfAborted();
+            return sink(event);
+        }), signal);
     }
+    /**
+     * Publish and, when a sink is installed, deliver one lifecycle event.
+     *
+     * Delivery goes through the scope so observers see the event before the sink does;
+     * `consume` runs inside the delivery callback, after the abort check, so a cancelled
+     * call cannot mutate the collector.
+     *
+     * @param type - Lifecycle event name.
+     * @param payload - Lazily built payload; only evaluated when someone consumes it.
+     * @param signal - Signal that bounds publication and delivery.
+     * @param scope - Diagnostic scope owning the event and its consumers.
+     * @param consume - Optional collector update performed before delivery.
+     */
     async publishOutput(type, payload, signal, scope, consume) {
         signal.throwIfAborted();
         if (this.ports.onOutput)
-            await scope?.deliver(type, payload, event => { signal.throwIfAborted(); consume?.(); return this.emitOutput(event, signal); });
+            await scope?.deliver(type, payload, (event) => {
+                signal.throwIfAborted();
+                consume?.();
+                return this.emitOutput(event, signal);
+            });
         else {
             scope?.emit(type, payload);
             signal.throwIfAborted();
@@ -127,32 +246,69 @@ export class ModelRunner {
         if (typeof stageId !== 'string' || !stageId.trim())
             throw new TypeError('stageId must be a nonempty string');
         validateOutputTokens(maxOutputTokens, stageId);
-        const transportId = request.transport === undefined ? defaultTextTransport.id : typeof request.transport === 'string'
-            ? request.transport : this.registeredTransports.get(request.transport);
+        const transportId = request.transport === undefined
+            ? defaultTextTransport.id
+            : typeof request.transport === 'string'
+                ? request.transport
+                : this.registeredTransports.get(request.transport);
         const transport = transportId === undefined ? undefined : this.transports.get(transportId);
         if (!transport)
             throw new TypeError('Prepare requires a registered model transport');
         const prepared = prepareModelTransport(transport, stageId);
         let state;
         const runner = this;
-        const snapshot = Object.freeze({ ...prepared,
-            stageId, modelId: this.modelId, transportId: transport.id, maxOutputTokens,
-            get remainingCalls() { return runner.remainingCalls; },
+        const snapshot = Object.freeze({
+            ...prepared,
+            stageId,
+            modelId: this.modelId,
+            transportId: transport.id,
+            maxOutputTokens,
+            get remainingCalls() {
+                return runner.remainingCalls;
+            },
+            /**
+             * Preflight measurement of one input shape.
+             *
+             * Measuring does not consume the prepared call and does not charge the budget; it
+             * only reports the sizes and whether all three budgets would accept the input.
+             *
+             * @param input - Prompt string, message array or built context.
+             * @returns Frozen character and token measurements with a `withinBudget` verdict.
+             * @throws TypeError When the input shape is invalid or the call is already used.
+             */
             measure(input) {
                 runner.signal.throwIfAborted();
                 if (state.used)
                     throw new TypeError('Prepared model call has already been used');
-                const base = typeof input === 'string' ? [{ role: 'user', content: input }] : isMessageArray(input) ? input : input.messages;
+                const base = typeof input === 'string'
+                    ? [{ role: 'user', content: input }]
+                    : isMessageArray(input)
+                        ? input
+                        : input.messages;
                 const size = preparedInputSize(base, prepared);
                 const inputLimit = typeof input === 'string' ? runner.maxInputChars : runner.inputLimit(input);
-                const inputTokenLimit = runner.tokenBudget ? modelInputTokenLimit(runner.tokenBudget, maxOutputTokens) : undefined;
-                const inputTokens = runner.tokenBudget ? countModelInput(runner.tokenBudget, size.messages, prepared.options) : undefined;
+                const inputTokenLimit = runner.tokenBudget
+                    ? modelInputTokenLimit(runner.tokenBudget, maxOutputTokens)
+                    : undefined;
+                const inputTokens = runner.tokenBudget
+                    ? countModelInput(runner.tokenBudget, size.messages, prepared.options)
+                    : undefined;
                 const maxSchemaChars = runner.ports.maxSchemaChars;
-                return Object.freeze({ messageChars: size.messageChars, instructionChars: size.instructionChars, schemaChars: size.schemaChars, transportChars: size.transportChars,
-                    inputChars: size.inputChars, maxInputChars: inputLimit, maxSchemaChars, maxOutputTokens,
-                    ...(runner.tokenBudget ? { counterId: runner.tokenBudget.counterId, inputTokens, inputTokenLimit } : {}),
-                    withinBudget: size.messageChars <= inputLimit && size.transportChars <= maxSchemaChars
-                        && (inputTokens === undefined || inputTokens <= inputTokenLimit),
+                return Object.freeze({
+                    messageChars: size.messageChars,
+                    instructionChars: size.instructionChars,
+                    schemaChars: size.schemaChars,
+                    transportChars: size.transportChars,
+                    inputChars: size.inputChars,
+                    maxInputChars: inputLimit,
+                    maxSchemaChars,
+                    maxOutputTokens,
+                    ...(runner.tokenBudget
+                        ? { counterId: runner.tokenBudget.counterId, inputTokens, inputTokenLimit }
+                        : {}),
+                    withinBudget: size.messageChars <= inputLimit &&
+                        size.transportChars <= maxSchemaChars &&
+                        (inputTokens === undefined || inputTokens <= inputTokenLimit),
                 });
             },
         });
@@ -168,33 +324,81 @@ export class ModelRunner {
         const prepared = state?.snapshot;
         const stage = call.stageId ?? prepared?.stageId ?? modelRunnerDefaults.stage;
         const tokens = call.maxOutputTokens ?? prepared?.maxOutputTokens ?? this.maxOutputTokens;
-        const invalid = (message) => recordErrorContext(new TypeError(message), { stageId: stage, codes: ['MODEL_CONFIG'], isRetryable: false });
+        const invalid = (message) => recordErrorContext(new TypeError(message), {
+            stageId: stage,
+            codes: ['MODEL_CONFIG'],
+            isRetryable: false,
+        });
         breakWhile([
             { occur: 'stage' in call, error: () => invalid('Use stageId to select a model stage') },
-            { occur: typeof stage !== 'string' || !stage.trim(), error: () => invalid('stageId must be a nonempty string') },
-            { occur: 'transportId' in call, error: () => invalid('Use transport to select a registered model transport') },
-            { occur: typeof call.transport === 'string' && !call.transport.trim(), error: () => invalid('Transport ID must be a nonempty string') },
+            {
+                occur: typeof stage !== 'string' || !stage.trim(),
+                error: () => invalid('stageId must be a nonempty string'),
+            },
+            {
+                occur: 'transportId' in call,
+                error: () => invalid('Use transport to select a registered model transport'),
+            },
+            {
+                occur: typeof call.transport === 'string' && !call.transport.trim(),
+                error: () => invalid('Transport ID must be a nonempty string'),
+            },
             { occur: 'prompt' in call, error: () => invalid('Use input to provide model input') },
             { occur: call.input == null, error: () => invalid('Model input is required') },
-            { occur: call.input !== undefined && typeof call.input !== 'string' && call.instructions !== undefined, error: () => invalid('instructions require string input; message inputs already declare their roles') },
-            { occur: call.instructions !== undefined && typeof call.instructions !== 'string', error: () => invalid('instructions must be text') },
+            {
+                occur: call.input !== undefined &&
+                    typeof call.input !== 'string' &&
+                    call.instructions !== undefined,
+                error: () => invalid('instructions require string input; message inputs already declare their roles'),
+            },
+            {
+                occur: call.instructions !== undefined && typeof call.instructions !== 'string',
+                error: () => invalid('instructions must be text'),
+            },
         ]);
         validateOutputTokens(tokens, stage);
         const source = call.input;
-        const input = typeof source === 'string' ? [
-            ...(call.instructions === undefined ? [] : [{ role: 'system', content: call.instructions }]),
-            { role: 'user', content: source },
-        ] : source;
+        const input = typeof source === 'string'
+            ? [
+                ...(call.instructions === undefined
+                    ? []
+                    : [{ role: 'system', content: call.instructions }]),
+                { role: 'user', content: source },
+            ]
+            : source;
         const transport = call.transport;
-        const transportId = transport === undefined ? prepared?.transportId ?? defaultTextTransport.id
-            : typeof transport === 'string' ? transport : this.registeredTransports.get(transport);
+        const transportId = transport === undefined
+            ? (prepared?.transportId ?? defaultTextTransport.id)
+            : typeof transport === 'string'
+                ? transport
+                : this.registeredTransports.get(transport);
         breakWhile(transportId === undefined, () => invalid('Typed transport must be the registered transport instance'));
-        if (prepared && (stage !== prepared.stageId || tokens !== prepared.maxOutputTokens || transportId !== prepared.transportId))
+        if (prepared &&
+            (stage !== prepared.stageId ||
+                tokens !== prepared.maxOutputTokens ||
+                transportId !== prepared.transportId))
             throw invalid('Prepared model request settings cannot be replaced');
         if (state)
             state.used = true;
         return this.invokePrepared(stage, input, tokens, transportId, call.diagnostics, prepared, call.signal);
     }
+    /**
+     * Acquire the per-runner call slot and execute one call.
+     *
+     * The concurrency guard is taken and released around `execute`; the error context is
+     * decorated with the stage before the failure leaves this method, so later layers do
+     * not need to re-derive it.
+     *
+     * @param stage - Stage id for diagnostics and error context.
+     * @param input - Messages, built context or context plan.
+     * @param tokens - Requested output tokens.
+     * @param transportId - Registered transport to execute.
+     * @param diagnostics - Observation scope for this call.
+     * @param prepared - Prepared call whose snapshot must be reused.
+     * @param requestSignal - Caller signal, combined with the runner signal.
+     * @returns The parsed result with invocation metadata.
+     * @throws Error When a call is already in flight or the request capacity is exhausted.
+     */
     async invokePrepared(stage, input, tokens, transportId, diagnostics = this.ports.diagnostics, prepared, requestSignal) {
         const configuredRun = this.ports.diagnostics?.identity?.runId, selectedRun = diagnostics?.identity?.runId;
         if (configuredRun && selectedRun && configuredRun !== selectedRun)
@@ -216,16 +420,59 @@ export class ModelRunner {
         }
         throw failure;
     }
+    /**
+     * Execute the prepared call: measure, charge, stream, commit.
+     *
+     * Phase order is a correctness requirement, not an implementation detail. Every
+     * rejection path goes through `reject`, which annotates codes and emits
+     * `runtime.rejected`. Budget charging happens only after all input checks pass, so a
+     * rejected request never consumes a call. The terminal `model.end` event is published
+     * in `finally` with its own timeout, because the call signal is already aborted when a
+     * call is cancelled and terminal delivery must still retract previews.
+     *
+     * @param stage - Stage id for diagnostics.
+     * @param input - Messages, built context or context plan.
+     * @param tokens - Requested output tokens.
+     * @param transportId - Registered transport id.
+     * @param signal - Combined execution and request signal.
+     * @param parentDiagnostics - Parent observation scope, defaulting to the runner scope.
+     * @param prepared - Prepared call whose snapshot must be reused.
+     * @returns The parsed result with invocation metadata.
+     * @throws Error or ValidationError from any phase, decorated with stage context.
+     */
     async execute(stage, input, tokens, transportId, signal, parentDiagnostics = this.ports.diagnostics, prepared) {
         const id = invocationId(), startedAtMs = Date.now();
         this.activeCall = undefined;
-        const invocationDiagnostics = parentDiagnostics?.child(id, { invocationId: id, modelId: this.modelId, nodeRole: 'invocation', definitionKind: 'model-transport', definitionId: transportId, nodeId: stage, nodeName: stage, nodeKind: 'model', nodeDescription: 'Registered model invocation', definitionRevision: undefined, stageId: stage });
+        const invocationDiagnostics = parentDiagnostics?.child(id, {
+            invocationId: id,
+            modelId: this.modelId,
+            nodeRole: 'invocation',
+            definitionKind: 'model-transport',
+            definitionId: transportId,
+            nodeId: stage,
+            nodeName: stage,
+            nodeKind: 'model',
+            nodeDescription: 'Registered model invocation',
+            definitionRevision: undefined,
+            stageId: stage,
+        });
         let diagnostics = invocationDiagnostics;
         const reject = (error) => {
-            recordErrorContext(error, { stageId: stage, ...(signal.aborted
-                    ? { codes: [isTimeoutReason(signal.reason) ? 'ROUND_TIMEOUT' : 'CANCELLED'], isRetryable: false }
-                    : error instanceof BudgetError ? { codes: ['BUDGET'], isRetryable: false } : {}) });
-            diagnostics?.emit('runtime.rejected', () => ({ stageId: stage, error: diagnosticError(error) }));
+            recordErrorContext(error, {
+                stageId: stage,
+                ...(signal.aborted
+                    ? {
+                        codes: [isTimeoutReason(signal.reason) ? 'ROUND_TIMEOUT' : 'CANCELLED'],
+                        isRetryable: false,
+                    }
+                    : error instanceof BudgetError
+                        ? { codes: ['BUDGET'], isRetryable: false }
+                        : {}),
+            });
+            diagnostics?.emit('runtime.rejected', () => ({
+                stageId: stage,
+                error: diagnosticError(error),
+            }));
             throw error;
         };
         const transport = this.transports.get(transportId);
@@ -286,11 +533,15 @@ export class ModelRunner {
         const functionChars = size.transportChars;
         // The binding snapshots and validates this fixed allowance at construction.
         if (functionChars > this.ports.maxSchemaChars)
-            return reject(new ValidationError([{ code: 'MODEL_SCHEMA_BUDGET', message: 'Model declarations exceed their schema budget' }]));
+            return reject(new ValidationError([
+                { code: 'MODEL_SCHEMA_BUDGET', message: 'Model declarations exceed their schema budget' },
+            ]));
         const inputChars = size.inputChars;
         try {
-            validateContextBudget(messageChars, this.inputLimit(input), limit => this.ports.inputBudgetError?.(limit)
-                ?? new ValidationError([{ code: 'CONTEXT_BUDGET', message: `Model input exceeds ${limit} characters` }]));
+            validateContextBudget(messageChars, this.inputLimit(input), (limit) => this.ports.inputBudgetError?.(limit) ??
+                new ValidationError([
+                    { code: 'CONTEXT_BUDGET', message: `Model input exceeds ${limit} characters` },
+                ]));
         }
         catch (error) {
             return reject(error);
@@ -309,13 +560,32 @@ export class ModelRunner {
         this.budget.take();
         this.completedCallCount++;
         const call = this.callCount;
-        const step = { ...invocationDiagnostics?.identity, modelId: this.modelId, invocationId: id, startedAtMs, callSequence: call, stageId: stage, durationMs: 0, inputChars, outputChars: 0,
-            firstOutputMs: null, outputDurationMs: 0, status: 'error', codes: [],
-            ...(inputTokens === undefined ? {} : { inputTokens, inputTokenLimit: tokenLimit }) };
+        const step = {
+            ...invocationDiagnostics?.identity,
+            modelId: this.modelId,
+            invocationId: id,
+            startedAtMs,
+            callSequence: call,
+            stageId: stage,
+            durationMs: 0,
+            inputChars,
+            outputChars: 0,
+            firstOutputMs: null,
+            outputDurationMs: 0,
+            status: 'error',
+            codes: [],
+            ...(inputTokens === undefined ? {} : { inputTokens, inputTokenLimit: tokenLimit }),
+        };
         if (!isMessageArray(input) && diagnostics?.enabled('model.prepare')) {
             try {
-                const serialized = JSON.stringify({ messages: modelMessageDiagnostics(messages), interaction: interactionOptions });
-                step.context = { fragmentUsage: input.fragmentUsage, stablePrefixChars: commonPrefixLength(serialized, this.priorInputs.get(stage) ?? '') };
+                const serialized = JSON.stringify({
+                    messages: modelMessageDiagnostics(messages),
+                    interaction: interactionOptions,
+                });
+                step.context = {
+                    fragmentUsage: input.fragmentUsage,
+                    stablePrefixChars: commonPrefixLength(serialized, this.priorInputs.get(stage) ?? ''),
+                };
                 this.priorInputs.set(stage, serialized);
             }
             catch {
@@ -340,7 +610,9 @@ export class ModelRunner {
                 if (call)
                     step.functionCall = call;
             }
-            catch { /* best-effort metadata */ }
+            catch {
+                /* best-effort metadata */
+            }
         };
         const accountOutput = () => {
             const outputChars = response.outputChars;
@@ -350,9 +622,18 @@ export class ModelRunner {
             // largest observed size without requiring its internal buffer to grow.
             step.outputChars = Math.max(step.outputChars, outputChars);
             if (this.config.maxOutputChars !== undefined && outputChars > this.config.maxOutputChars)
-                throw this.ports.outputBudgetError?.() ?? new ValidationError([{ code: 'OUTPUT_LIMIT', message: 'Model output exceeds its character budget' }]);
+                throw (this.ports.outputBudgetError?.() ??
+                    new ValidationError([
+                        { code: 'OUTPUT_LIMIT', message: 'Model output exceeds its character budget' },
+                    ]));
         };
-        diagnostics?.emit('model.prepare', () => ({ stageId: stage, transportId, messages: modelMessageDiagnostics(messages), options: { ...interactionOptions, maxOutputTokens: tokens }, context: isMessageArray(input) ? undefined : input.fragmentUsage }));
+        diagnostics?.emit('model.prepare', () => ({
+            stageId: stage,
+            transportId,
+            messages: modelMessageDiagnostics(messages),
+            options: { ...interactionOptions, maxOutputTokens: tokens },
+            context: isMessageArray(input) ? undefined : input.fragmentUsage,
+        }));
         try {
             await this.publishOutput('model.start', () => ({ stageId: stage, callSequence: call, transportId }), callSignal, diagnostics);
             callSignal.throwIfAborted();
@@ -361,10 +642,18 @@ export class ModelRunner {
                 throw new TypeError('Invalid model response collector');
             accountOutput();
             callSignal.throwIfAborted();
-            for await (const part of abortableStream(this.provider.stream(messages, { signal: callSignal, diagnostics, options: {
+            for await (const part of abortableStream(this.provider.stream(messages, {
+                signal: callSignal,
+                diagnostics,
+                options: {
                     ...interactionOptions,
-                    maxOutputTokens: tokens, includeUsage: this.config.usage, onUsage: usage => { step.usage = usage; },
-                } }), callSignal)) {
+                    maxOutputTokens: tokens,
+                    includeUsage: this.config.usage,
+                    onUsage: (usage) => {
+                        step.usage = usage;
+                    },
+                },
+            }), callSignal)) {
                 const partIndex = receivedParts;
                 receivedParts++;
                 callSignal.throwIfAborted();
@@ -382,29 +671,67 @@ export class ModelRunner {
             captureCallMetadata();
             await this.publishOutput('model.parsed', () => ({ stageId: stage, callSequence: call, value }), callSignal, diagnostics);
             callSignal.throwIfAborted();
-            this.journal.model({ stageId: stage, value, invocation: { ...invocationDiagnostics?.identity, invocationId: id, startedAtMs, durationMs: Date.now() - startedAtMs } });
+            this.journal.model({
+                stageId: stage,
+                value,
+                invocation: {
+                    ...invocationDiagnostics?.identity,
+                    invocationId: id,
+                    startedAtMs,
+                    durationMs: Date.now() - startedAtMs,
+                },
+            });
             step.status = 'success';
-            return invocationResult(value, { ...invocationDiagnostics?.identity, invocationId: id, modelId: this.modelId, stageId: stage, startedAtMs,
-                durationMs: Date.now() - startedAtMs, callSequence: call, status: 'success',
-                ...(step.usage ? { usage: Object.freeze({ ...step.usage }) } : {}) });
+            return invocationResult(value, {
+                ...invocationDiagnostics?.identity,
+                invocationId: id,
+                modelId: this.modelId,
+                stageId: stage,
+                startedAtMs,
+                durationMs: Date.now() - startedAtMs,
+                callSequence: call,
+                status: 'success',
+                ...(step.usage ? { usage: Object.freeze({ ...step.usage }) } : {}),
+            });
         }
         catch (error) {
             callError = { error };
             step.status = signal.aborted || callDeadline.aborted ? 'cancelled' : 'error';
             try {
                 const info = getErrorInfo(error);
-                const codes = error instanceof ValidationError ? error.issues.map(item => item.code)
-                    : [signal.aborted ? (isTimeoutReason(signal.reason) ? 'ROUND_TIMEOUT' : 'CANCELLED')
-                            : callDeadline.aborted ? 'CALL_TIMEOUT' : info.code === 'UNKNOWN_ERROR' ? 'UPSTREAM_ERROR' : info.code];
-                recordErrorContext(error, { stageId: stage, codes,
-                    ...(signal.aborted ? { isRetryable: false } : callDeadline.aborted ? { isRetryable: true } : {}) });
+                const codes = error instanceof ValidationError
+                    ? error.issues.map((item) => item.code)
+                    : [
+                        signal.aborted
+                            ? isTimeoutReason(signal.reason)
+                                ? 'ROUND_TIMEOUT'
+                                : 'CANCELLED'
+                            : callDeadline.aborted
+                                ? 'CALL_TIMEOUT'
+                                : info.code === 'UNKNOWN_ERROR'
+                                    ? 'UPSTREAM_ERROR'
+                                    : info.code,
+                    ];
+                recordErrorContext(error, {
+                    stageId: stage,
+                    codes,
+                    ...(signal.aborted
+                        ? { isRetryable: false }
+                        : callDeadline.aborted
+                            ? { isRetryable: true }
+                            : {}),
+                });
                 step.codes = [...getErrorInfo(error).codes];
             }
             catch {
                 // Even instanceof or an Error subclass's fields can throw. Decoration
                 // must not replace the original value or skip terminal delivery.
                 const cancelled = step.status === 'cancelled', codes = [cancelled ? 'CANCELLED' : 'UPSTREAM_ERROR'];
-                recordErrorContext(error, { stageId: stage, codes, ...(cancelled ? { isRetryable: false } : {}) });
+                recordErrorContext(error, {
+                    stageId: stage,
+                    codes,
+                    ...(cancelled ? { isRetryable: false } : {}),
+                });
                 step.codes = codes;
             }
         }
@@ -412,13 +739,20 @@ export class ModelRunner {
             captureCallMetadata();
             step.durationMs = Date.now() - startedAtMs;
             step.outputDurationMs = step.firstOutputMs == null ? 0 : step.durationMs - step.firstOutputMs;
-            const end = () => ({ stageId: stage, state: { ...step }, receivedParts, ...(callError ? { error: diagnosticError(callError.error) } : {}) });
+            const end = () => ({
+                stageId: stage,
+                state: { ...step },
+                receivedParts,
+                ...(callError ? { error: diagnosticError(callError.error) } : {}),
+            });
             // Terminal delivery also retracts cancelled previews. It needs its own
             // bounded lifetime: the call signal is already aborted on cancellation.
             try {
                 await this.publishOutput('model.end', end, AbortSignal.timeout(250), diagnostics);
             }
-            catch { /* Terminal notification cannot replace a committed result or its original failure. */ }
+            catch {
+                /* Terminal notification cannot replace a committed result or its original failure. */
+            }
         }
         throw callError.error;
     }