@jangts/agent-core 0.1.0 → 0.2.0

package/dist/esm/model/runner.d.ts

@@ -2,12 +2,23 @@ import type { ModelResult } from '../structs/invocation.js';
 import { ContextJournal } from '../context/journal.js';
 import type { ModelCallTrace, ModelTransportDefinition, ModelRunnerOptions, ModelCallRequest } from '../structs/model/runtime.js';
 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 declare class ModelRunner<TransportId extends string = string, const Transports extends readonly ModelTransportDefinition[] = readonly ModelTransportDefinition[]> {
+    /** Record of parsed results for this runner; descendants keep their own journals. */
     readonly journal: ContextJournal;
     private completedCallCount;
     private activeCall?;
+    /** Completed calls observed by this runner only. */
     get callCount(): number;
+    /** Detached copy of the most recent call trace, or undefined before the first call. */
     get lastCall(): Readonly<ModelCallTrace> | undefined;
     private readonly priorInputs;
     private readonly tokenBudget?;
@@ -26,40 +37,153 @@ export declare class ModelRunner<TransportId extends string = string, const Tran
     private depth;
     private inFlight;
     private requestGate;
+    /** Limits shared by every runner of one request; children only read them. */
     get childLimits(): Readonly<Required<import('../structs/model/runtime.js').ModelChildPolicy>>;
     /** Includes descendant attempts; local callCount and journal remain isolated. */
     get totalCallCount(): number;
-    /** A fresh runner, never a fork of conversation/journal/sinks. All ancestors retain their budgets. */
+    /**
+     * 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: import('../structs/model/runtime.js').ModelChildOptions): ModelRunner;
+    /**
+     * 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: ModelRunnerOptions<Transports>);
+    /** Calls still available to this runner after the parent's reserve is applied. */
     get remainingCalls(): number;
+    /**
+     * 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.
+     */
     private inputLimit;
     /** Backpressure is awaited, but a stalled consumer cannot disable model cancellation/deadlines. */
     private emitOutput;
+    /**
+     * 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.
+     */
     private publishOutput;
+    /**
+     * Prepare a call and measure it before invocation.
+     *
+     * A prepared call is single-use and bound to the stage, output tokens and transport it
+     * was measured with; `invoke` rejects any attempt to replace those settings.
+     *
+     * @param request - Stage, transport and output token overrides.
+     * @returns A frozen prepared call with a `measure` helper.
+     * @throws TypeError When the stage, tokens or transport selection is invalid.
+     */
     prepare(request?: import('../structs/model/runtime.js').ModelPrepareRequest<never>): import('../structs/model/runtime.js').PreparedModelCall<string>;
+    /** Prepare a call for a transport instance supplied at the call site. */
     prepare<Result>(request: import('../structs/model/runtime.js').ModelPrepareRequest<ModelTransportDefinition<Result>> & {
         readonly transport: ModelTransportDefinition<Result>;
     }): import('../structs/model/runtime.js').PreparedModelCall<Result>;
+    /** Prepare a call for a transport id, typed by the runner's registered transports. */
     prepare<const Id extends string>(request: import('../structs/model/runtime.js').ModelPrepareRequest<Id> & {
         readonly transport: Id;
     }): import('../structs/model/runtime.js').PreparedModelCall<import('../structs/model/runtime.js').RegisteredTransportOutput<Transports, Id>>;
+    /** Prepare a call without narrowing the transport type. */
     prepare(request: import('../structs/model/runtime.js').ModelPrepareRequest<string | ModelTransportDefinition>): import('../structs/model/runtime.js').PreparedModelCall;
-    /** Named and shorthand input share the same invocation lifecycle. */
+    /**
+     * Invoke one model call.
+     *
+     * Named and shorthand input share the same lifecycle: validation, measurement, budget
+     * charge, streaming, commit. A caller-supplied signal only shortens the call lifetime.
+     *
+     * @param request - A prompt string, or a request naming input, stage, transport and signal.
+     * @returns The parsed result with its invocation metadata.
+     * @throws TypeError When the request, stage, tokens or transport is invalid.
+     * @throws ValidationError When the input or output exceeds its budget.
+     * @throws BudgetError When no model call remains for this request.
+     * @throws The signal reason on cancellation or timeout.
+     */
     invoke(request: string): Promise<ModelResult<string>>;
+    /** Invoke a prepared call whose settings cannot be replaced. */
     invoke<Result>(request: ModelCallRequest<never> & {
         readonly prepared: import('../structs/model/runtime.js').PreparedModelCall<Result>;
     }): Promise<ModelResult<Result>>;
+    /** Invoke with the default transport and a plain-text result. */
     invoke(request: ModelCallRequest<never>): Promise<ModelResult<string>>;
+    /** Invoke with a transport instance supplied at the call site. */
     invoke<Result>(request: ModelCallRequest<ModelTransportDefinition<Result>> & {
         transport: ModelTransportDefinition<Result>;
     }): Promise<ModelResult<Result>>;
+    /** Invoke with a transport id registered on this runner. */
     invoke<const Id extends string>(request: ModelCallRequest<Id> & {
         readonly transport: Id;
     }): Promise<ModelResult<import('../structs/model/runtime.js').RegisteredTransportOutput<Transports, Id>>>;
+    /** Invoke without narrowing the transport type. */
     invoke(request: ModelCallRequest<TransportId | ModelTransportDefinition>): Promise<ModelResult<unknown>>;
+    /**
+     * 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.
+     */
     private invokePrepared;
+    /**
+     * 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.
+     */
     private execute;
 }
-export type { ModelOutputEvent, ModelRuntimeConfig, ModelTransportDefinition, ModelCallTrace, ModelRunnerPorts, ModelTokenBudget, ModelRunnerOptions, ModelCallRequest, ModelRunnerSettings, ModelChildOptions, ModelChildPolicy } from '../structs/model/runtime.js';
-export type { PreparedModelCall, ModelInputMeasurement, ModelPrepareRequest } from '../structs/model/runtime.js';
+export type { ModelOutputEvent, ModelRuntimeConfig, ModelTransportDefinition, ModelCallTrace, ModelRunnerPorts, ModelTokenBudget, ModelRunnerOptions, ModelCallRequest, ModelRunnerSettings, ModelChildOptions, ModelChildPolicy, } from '../structs/model/runtime.js';
+export type { PreparedModelCall, ModelInputMeasurement, ModelPrepareRequest, } from '../structs/model/runtime.js';