ModelRunner

CORE · class · Runtime value

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.

Import

TypeScript

import { ModelRunner } from '@jangts/agent-core/model';

JavaScript

import { ModelRunner } from '@jangts/agent-core/model';

Other public entry points:@jangts/agent-core, @jangts/agent-core/model, @jangts/agent-core/types.

Definition

class ModelRunner<TransportId, Transports>

Type parameters

Type parameter	Constraint	Default type
TransportId	string	string
Transports	readonly ModelTransportDefinition[]	readonly ModelTransportDefinition[]

Constructor

new ModelRunner<TransportId extends string = string, const Transports extends readonly ModelTransportDefinition[] = readonly ModelTransportDefinition<unknown>[]>(options: ModelRunnerOptions<Transports>): ModelRunner<TransportId, Transports>

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.

Parameter	Type	Passing	Description
options	ModelRunnerOptions<Transports>	Required	—

Fields of options

Field	Type	Required	Description
provider	ChatProvider	Required	See the type definition and usage context.
execution	ExecutionOptions | undefined	Optional	See the type definition and usage context.
transports	Transports | undefined	Optional	See the type definition and usage context.
sink	{ output?: ModelRunnerPorts["onOutput"]; } | undefined	Optional	See the type definition and usage context.
errors	{ inputBudget?: ModelRunnerPorts["inputBudgetError"]; outputBudget?: ModelRunnerPorts["outputBudgetError"]; } | undefined	Optional	See the type definition and usage context.
children	ModelChildPolicy | undefined	Optional	Read-only. See the type definition and usage context.
maxInputChars	number | undefined	Optional	Character budget for the assembled input.
maxSchemaChars	number | undefined	Optional	Character allowance for registered capability schemas.
tokenBudget	ModelTokenBudget | undefined	Optional	See the type definition and usage context.
maxOutputTokens	number | undefined	Optional	Default output reservation; invoke can override it for one call.
maxCalls	number | undefined	Optional	Calls allowed for the whole request, including descendant runners' reservations.
callTimeoutMs	number | undefined	Optional	Deadline for one provider call, in milliseconds.
maxOutputChars	number | undefined	Optional	Cap on streamed output characters; exceeding it fails the call.
usage	boolean | undefined	Optional	Request and record provider usage for each call.

Returns: ModelRunner<TransportId, Transports>.

Instance properties

Field	Type	Required	Description
journal	ContextJournal	Required	Read-only. Record of parsed results for this runner; descendants keep their own journals.
callCount	number	Required	Read-only. Completed calls observed by this runner only.
lastCall	Readonly<ModelCallTrace> | undefined	Required	Read-only. Detached copy of the most recent call trace, or undefined before the first call.
signal	AbortSignal	Required	Read-only. See the type definition and usage context.
execution	ExecutionContext	Required	Read-only. See the type definition and usage context.
childLimits	Readonly<Required<ModelChildPolicy>>	Required	Read-only. Limits shared by every runner of one request; children only read them.
totalCallCount	number	Required	Read-only. Includes descendant attempts; local callCount and journal remain isolated.
remainingCalls	number	Required	Read-only. Calls still available to this runner after the parent's reserve is applied.

Member index

Member	Purpose
createChild	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.
prepare	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. Prepare a call for a transport instance supplied at the call site. Prepare a call for a transport id, typed by the runner's registered transports. Prepare a call without narrowing the transport type.
invoke	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. Invoke a prepared call whose settings cannot be replaced. Invoke with the default transport and a plain-text result. Invoke with a transport instance supplied at the call site. Invoke with a transport id registered on this runner. Invoke without narrowing the transport type.

Member details

createChild

Instance method.

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.

createChild(options: import("../structs/model/runtime.js").ModelChildOptions): ModelRunner

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.

Parameter	Type	Passing	Description
options	ModelChildOptions	Required	—

Fields of options

Field	Type	Required	Description
id	string	Required	Read-only. Child stage id, reported in traces and events.
maxCalls	number	Required	Read-only. Calls the child may use from the shared request budget.
reserveCalls	number	Required	Read-only. Calls kept for the parent; the child cannot spend them.
timeoutMs	number	Required	Read-only. Deadline for the child's own calls, in milliseconds.
transports	readonly ModelTransportDefinition<unknown>[] | undefined	Optional	Read-only. Additional transports visible to the child.
diagnostics	DiagnosticContext | undefined	Optional	Read-only. See the type definition and usage context.
signal	AbortSignal | undefined	Optional	Read-only. Extra cancellation; can only shorten the parent's lifetime.

Returns: ModelRunner<string, readonly ModelTransportDefinition<unknown>[]>.

prepare

Instance method.

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. Prepare a call for a transport instance supplied at the call site. Prepare a call for a transport id, typed by the runner's registered transports. Prepare a call without narrowing the transport type.

prepare(request?: import("../structs/model/runtime.js").ModelPrepareRequest<never>): import("../structs/model/runtime.js").PreparedModelCall<string>

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.

Parameter	Type	Passing	Description
request	ModelPrepareRequest<never> | undefined	Optional	—

Optional shapes of Parameter request: choose one shape; required fields for each branch are listed separately.

Branch 1

undefined

Branch 2

Field	Type	Required	Description
stageId	string | undefined	Optional	Read-only. See the type definition and usage context.
transport	undefined	Optional	Read-only. See the type definition and usage context.
maxOutputTokens	number | undefined	Optional	Read-only. See the type definition and usage context.

Returns: PreparedModelCall<string>.

Return value structure

Field	Type	Required	Description
modelId	string | undefined	Optional	Read-only. Model binding the call was prepared with.
stageId	string	Required	Read-only. See the type definition and usage context.
transportId	string	Required	Read-only. See the type definition and usage context.
maxOutputTokens	number	Required	Read-only. See the type definition and usage context.
remainingCalls	number	Required	Read-only. Calls still available; a live value, so later spends are visible.
measure	(input: string | readonly ModelMessage[] | BuiltContext) => ModelInputMeasurement	Required	Preflight measurement of one input shape. Never marks the call used and never charges the budget.
options	Pick<ModelOptions, "functions" | "json" | "toolChoice" | "parallelToolCalls" | "temperature">	Required	Read-only. See the type definition and usage context.
schemaChars	number	Required	Read-only. See the type definition and usage context.
instruction	string | undefined	Optional	Read-only. See the type definition and usage context.
createResponse	() => ModelResponseCollector<string>	Required	See the type definition and usage context.

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 instance supplied at the call site.

Type parameter	Constraint	Default type
Result	—	—

Parameter	Type	Passing	Description
request	ModelPrepareRequest<ModelTransportDefinition<Result>> & { readonly transport: ModelTransportDefinition<Result>; }	Required	—

Fields of request

Field	Type	Required	Description
stageId	string | undefined	Optional	Read-only. See the type definition and usage context.
transport	ModelTransportDefinition<Result>	Required	Read-only. See the type definition and usage context.
maxOutputTokens	number | undefined	Optional	Read-only. See the type definition and usage context.

Returns: PreparedModelCall<Result>.

Return value structure

Field	Type	Required	Description
modelId	string | undefined	Optional	Read-only. Model binding the call was prepared with.
stageId	string	Required	Read-only. See the type definition and usage context.
transportId	string	Required	Read-only. See the type definition and usage context.
maxOutputTokens	number	Required	Read-only. See the type definition and usage context.
remainingCalls	number	Required	Read-only. Calls still available; a live value, so later spends are visible.
measure	(input: string | readonly ModelMessage[] | BuiltContext) => ModelInputMeasurement	Required	Preflight measurement of one input shape. Never marks the call used and never charges the budget.
options	Pick<ModelOptions, "functions" | "json" | "toolChoice" | "parallelToolCalls" | "temperature">	Required	Read-only. See the type definition and usage context.
schemaChars	number	Required	Read-only. See the type definition and usage context.
instruction	string | undefined	Optional	Read-only. See the type definition and usage context.
createResponse	() => ModelResponseCollector<Result>	Required	See the type definition and usage context.

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 for a transport id, typed by the runner's registered transports.

Type parameter	Constraint	Default type
Id	string	—

Parameter	Type	Passing	Description
request	ModelPrepareRequest<Id> & { readonly transport: Id; }	Required	—

Fields of request

Field	Type	Required	Description
stageId	string | undefined	Optional	Read-only. See the type definition and usage context.
transport	Id	Required	Read-only. See the type definition and usage context.
maxOutputTokens	number | undefined	Optional	Read-only. See the type definition and usage context.

Returns: PreparedModelCall<RegisteredTransportOutput<Transports, Id>>.

Return value structure

Field	Type	Required	Description
modelId	string | undefined	Optional	Read-only. Model binding the call was prepared with.
stageId	string	Required	Read-only. See the type definition and usage context.
transportId	string	Required	Read-only. See the type definition and usage context.
maxOutputTokens	number	Required	Read-only. See the type definition and usage context.
remainingCalls	number	Required	Read-only. Calls still available; a live value, so later spends are visible.
measure	(input: string | readonly ModelMessage[] | BuiltContext) => ModelInputMeasurement	Required	Preflight measurement of one input shape. Never marks the call used and never charges the budget.
options	Pick<ModelOptions, "functions" | "json" | "toolChoice" | "parallelToolCalls" | "temperature">	Required	Read-only. See the type definition and usage context.
schemaChars	number	Required	Read-only. See the type definition and usage context.
instruction	string | undefined	Optional	Read-only. See the type definition and usage context.
createResponse	() => ModelResponseCollector<RegisteredTransportOutput<Transports, Id>>	Required	See the type definition and usage context.

prepare(request: import("../structs/model/runtime.js").ModelPrepareRequest<string | ModelTransportDefinition>): import("../structs/model/runtime.js").PreparedModelCall

Prepare a call without narrowing the transport type.

Parameter	Type	Passing	Description
request	ModelPrepareRequest<string | ModelTransportDefinition<unknown>>	Required	—

Fields of request

Field	Type	Required	Description
stageId	string | undefined	Optional	Read-only. See the type definition and usage context.
transport	string | ModelTransportDefinition<unknown> | undefined	Optional	Read-only. See the type definition and usage context.
maxOutputTokens	number | undefined	Optional	Read-only. See the type definition and usage context.

Returns: PreparedModelCall<unknown>.

Return value structure

Field	Type	Required	Description
modelId	string | undefined	Optional	Read-only. Model binding the call was prepared with.
stageId	string	Required	Read-only. See the type definition and usage context.
transportId	string	Required	Read-only. See the type definition and usage context.
maxOutputTokens	number	Required	Read-only. See the type definition and usage context.
remainingCalls	number	Required	Read-only. Calls still available; a live value, so later spends are visible.
measure	(input: string | readonly ModelMessage[] | BuiltContext) => ModelInputMeasurement	Required	Preflight measurement of one input shape. Never marks the call used and never charges the budget.
options	Pick<ModelOptions, "functions" | "json" | "toolChoice" | "parallelToolCalls" | "temperature">	Required	Read-only. See the type definition and usage context.
schemaChars	number	Required	Read-only. See the type definition and usage context.
instruction	string | undefined	Optional	Read-only. See the type definition and usage context.
createResponse	() => ModelResponseCollector<unknown>	Required	See the type definition and usage context.

invoke

Instance method.

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. Invoke a prepared call whose settings cannot be replaced. Invoke with the default transport and a plain-text result. Invoke with a transport instance supplied at the call site. Invoke with a transport id registered on this runner. Invoke without narrowing the transport type.

invoke(request: string): Promise<ModelResult<string>>

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.

Parameter	Type	Passing	Description
request	string	Required	—

Returns: Promise<ModelResult<string>>.

Awaited value: ModelResult<string>.

Return value structure

Field	Type	Required	Description
value	string	Required	Read-only. See the type definition and usage context.
invocation	Readonly<ModelCallRecord>	Required	Read-only. See the type definition and usage context.

invoke<Result>(request: ModelCallRequest<never> & { readonly prepared: import("../structs/model/runtime.js").PreparedModelCall<Result>; }): Promise<ModelResult<Result>>

Invoke a prepared call whose settings cannot be replaced.

Type parameter	Constraint	Default type
Result	—	—

Parameter	Type	Passing	Description
request	ModelCallRequest<never> & { readonly prepared: import("../structs/model/runtime.js").PreparedModelCall<Result>; }	Required	—

Optional shapes of Parameter request: choose one shape; required fields for each branch are listed separately.

Branch 1

Field	Type	Required	Description
logger	SubFlowLogger | undefined	Optional	Read-only. Record this call in the supplied logger; omission adds no sub-flow record.
signal	AbortSignal | undefined	Optional	Read-only. Additional cancellation can shorten, never replace, the Runner lifetime.
diagnostics	DiagnosticContext | undefined	Optional	Read-only. Parent observation scope for this invocation; never changes execution budget or signal.
prepared	PreparedModelCall<unknown> & PreparedModelCall<Result>	Required	Read-only. Reuse a prepared call; its stage, transport and output reservation then take precedence.
maxOutputTokens	number | undefined	Optional	Read-only. See the type definition and usage context.
stageId	string | undefined	Optional	Read-only. See the type definition and usage context.
transport	undefined	Optional	Read-only. See the type definition and usage context.
input	string	Required	See the type definition and usage context.
instructions	string | undefined	Optional	See the type definition and usage context.

Branch 2

Field	Type	Required	Description
logger	SubFlowLogger | undefined	Optional	Read-only. Record this call in the supplied logger; omission adds no sub-flow record.
signal	AbortSignal | undefined	Optional	Read-only. Additional cancellation can shorten, never replace, the Runner lifetime.
diagnostics	DiagnosticContext | undefined	Optional	Read-only. Parent observation scope for this invocation; never changes execution budget or signal.
prepared	PreparedModelCall<unknown> & PreparedModelCall<Result>	Required	Read-only. Reuse a prepared call; its stage, transport and output reservation then take precedence.
maxOutputTokens	number | undefined	Optional	Read-only. See the type definition and usage context.
stageId	string | undefined	Optional	Read-only. See the type definition and usage context.
transport	undefined	Optional	Read-only. See the type definition and usage context.
input	readonly ModelMessage[] | BuiltContext | ContextPlan	Required	See the type definition and usage context.
instructions	undefined	Optional	See the type definition and usage context.

Returns: Promise<ModelResult<Result>>.

Awaited value: ModelResult<Result>.

Return value structure

Field	Type	Required	Description
value	Result	Required	Read-only. See the type definition and usage context.
invocation	Readonly<ModelCallRecord>	Required	Read-only. See the type definition and usage context.

invoke(request: ModelCallRequest<never>): Promise<ModelResult<string>>

Invoke with the default transport and a plain-text result.

Parameter	Type	Passing	Description
request	ModelCallRequest<never>	Required	—

Optional shapes of Parameter request: choose one shape; required fields for each branch are listed separately.

Branch 1

Field	Type	Required	Description
logger	SubFlowLogger | undefined	Optional	Read-only. Record this call in the supplied logger; omission adds no sub-flow record.
signal	AbortSignal | undefined	Optional	Read-only. Additional cancellation can shorten, never replace, the Runner lifetime.
diagnostics	DiagnosticContext | undefined	Optional	Read-only. Parent observation scope for this invocation; never changes execution budget or signal.
prepared	PreparedModelCall<unknown> | undefined	Optional	Read-only. Reuse a prepared call; its stage, transport and output reservation then take precedence.
maxOutputTokens	number | undefined	Optional	Read-only. See the type definition and usage context.
stageId	string | undefined	Optional	Read-only. See the type definition and usage context.
transport	undefined	Optional	Read-only. See the type definition and usage context.
input	string	Required	See the type definition and usage context.
instructions	string | undefined	Optional	See the type definition and usage context.

Branch 2

Field	Type	Required	Description
logger	SubFlowLogger | undefined	Optional	Read-only. Record this call in the supplied logger; omission adds no sub-flow record.
signal	AbortSignal | undefined	Optional	Read-only. Additional cancellation can shorten, never replace, the Runner lifetime.
diagnostics	DiagnosticContext | undefined	Optional	Read-only. Parent observation scope for this invocation; never changes execution budget or signal.
prepared	PreparedModelCall<unknown> | undefined	Optional	Read-only. Reuse a prepared call; its stage, transport and output reservation then take precedence.
maxOutputTokens	number | undefined	Optional	Read-only. See the type definition and usage context.
stageId	string | undefined	Optional	Read-only. See the type definition and usage context.
transport	undefined	Optional	Read-only. See the type definition and usage context.
input	readonly ModelMessage[] | BuiltContext | ContextPlan	Required	See the type definition and usage context.
instructions	undefined	Optional	See the type definition and usage context.

Returns: Promise<ModelResult<string>>.

Awaited value: ModelResult<string>.

Return value structure

Field	Type	Required	Description
value	string	Required	Read-only. See the type definition and usage context.
invocation	Readonly<ModelCallRecord>	Required	Read-only. See the type definition and usage context.

invoke<Result>(request: ModelCallRequest<ModelTransportDefinition<Result>> & { transport: ModelTransportDefinition<Result>; }): Promise<ModelResult<Result>>

Invoke with a transport instance supplied at the call site.

Type parameter	Constraint	Default type
Result	—	—

Parameter	Type	Passing	Description
request	ModelCallRequest<ModelTransportDefinition<Result>> & { transport: ModelTransportDefinition<Result>; }	Required	—

Optional shapes of Parameter request: choose one shape; required fields for each branch are listed separately.

Branch 1

Field	Type	Required	Description
logger	SubFlowLogger | undefined	Optional	Read-only. Record this call in the supplied logger; omission adds no sub-flow record.
signal	AbortSignal | undefined	Optional	Read-only. Additional cancellation can shorten, never replace, the Runner lifetime.
diagnostics	DiagnosticContext | undefined	Optional	Read-only. Parent observation scope for this invocation; never changes execution budget or signal.
prepared	PreparedModelCall<unknown> | undefined	Optional	Read-only. Reuse a prepared call; its stage, transport and output reservation then take precedence.
maxOutputTokens	number | undefined	Optional	Read-only. See the type definition and usage context.
stageId	string | undefined	Optional	Read-only. See the type definition and usage context.
transport	ModelTransportDefinition<Result>	Required	Read-only. See the type definition and usage context.
input	string	Required	See the type definition and usage context.
instructions	string | undefined	Optional	See the type definition and usage context.

Branch 2

Field	Type	Required	Description
logger	SubFlowLogger | undefined	Optional	Read-only. Record this call in the supplied logger; omission adds no sub-flow record.
signal	AbortSignal | undefined	Optional	Read-only. Additional cancellation can shorten, never replace, the Runner lifetime.
diagnostics	DiagnosticContext | undefined	Optional	Read-only. Parent observation scope for this invocation; never changes execution budget or signal.
prepared	PreparedModelCall<unknown> | undefined	Optional	Read-only. Reuse a prepared call; its stage, transport and output reservation then take precedence.
maxOutputTokens	number | undefined	Optional	Read-only. See the type definition and usage context.
stageId	string | undefined	Optional	Read-only. See the type definition and usage context.
transport	ModelTransportDefinition<Result>	Required	Read-only. See the type definition and usage context.
input	readonly ModelMessage[] | BuiltContext | ContextPlan	Required	See the type definition and usage context.
instructions	undefined	Optional	See the type definition and usage context.

Returns: Promise<ModelResult<Result>>.

Awaited value: ModelResult<Result>.

Return value structure

Field	Type	Required	Description
value	Result	Required	Read-only. See the type definition and usage context.
invocation	Readonly<ModelCallRecord>	Required	Read-only. See the type definition and usage context.

invoke<const Id extends string>(request: ModelCallRequest<Id> & { readonly transport: Id; }): Promise<ModelResult<import("../structs/model/runtime.js").RegisteredTransportOutput<Transports, Id>>>

Invoke with a transport id registered on this runner.

Type parameter	Constraint	Default type
Id	string	—

Parameter	Type	Passing	Description
request	ModelCallRequest<Id> & { readonly transport: Id; }	Required	—

Optional shapes of Parameter request: choose one shape; required fields for each branch are listed separately.

Branch 1

Field	Type	Required	Description
logger	SubFlowLogger | undefined	Optional	Read-only. Record this call in the supplied logger; omission adds no sub-flow record.
signal	AbortSignal | undefined	Optional	Read-only. Additional cancellation can shorten, never replace, the Runner lifetime.
diagnostics	DiagnosticContext | undefined	Optional	Read-only. Parent observation scope for this invocation; never changes execution budget or signal.
prepared	PreparedModelCall<unknown> | undefined	Optional	Read-only. Reuse a prepared call; its stage, transport and output reservation then take precedence.
maxOutputTokens	number | undefined	Optional	Read-only. See the type definition and usage context.
stageId	string | undefined	Optional	Read-only. See the type definition and usage context.
transport	Id	Required	Read-only. See the type definition and usage context.
input	string	Required	See the type definition and usage context.
instructions	string | undefined	Optional	See the type definition and usage context.

Branch 2

Field	Type	Required	Description
logger	SubFlowLogger | undefined	Optional	Read-only. Record this call in the supplied logger; omission adds no sub-flow record.
signal	AbortSignal | undefined	Optional	Read-only. Additional cancellation can shorten, never replace, the Runner lifetime.
diagnostics	DiagnosticContext | undefined	Optional	Read-only. Parent observation scope for this invocation; never changes execution budget or signal.
prepared	PreparedModelCall<unknown> | undefined	Optional	Read-only. Reuse a prepared call; its stage, transport and output reservation then take precedence.
maxOutputTokens	number | undefined	Optional	Read-only. See the type definition and usage context.
stageId	string | undefined	Optional	Read-only. See the type definition and usage context.
transport	Id	Required	Read-only. See the type definition and usage context.
input	readonly ModelMessage[] | BuiltContext | ContextPlan	Required	See the type definition and usage context.
instructions	undefined	Optional	See the type definition and usage context.

Returns: Promise<ModelResult<RegisteredTransportOutput<Transports, Id>>>.

Awaited value: ModelResult<RegisteredTransportOutput<Transports, Id>>.

Return value structure

Field	Type	Required	Description
value	RegisteredTransportOutput<Transports, Id>	Required	Read-only. See the type definition and usage context.
invocation	Readonly<ModelCallRecord>	Required	Read-only. See the type definition and usage context.

invoke(request: ModelCallRequest<TransportId | ModelTransportDefinition>): Promise<ModelResult<unknown>>

Invoke without narrowing the transport type.

Parameter	Type	Passing	Description
request	ModelCallRequest<ModelTransportDefinition<unknown> | TransportId>	Required	—

Optional shapes of Parameter request: choose one shape; required fields for each branch are listed separately.

Branch 1

Field	Type	Required	Description
logger	SubFlowLogger | undefined	Optional	Read-only. Record this call in the supplied logger; omission adds no sub-flow record.
signal	AbortSignal | undefined	Optional	Read-only. Additional cancellation can shorten, never replace, the Runner lifetime.
diagnostics	DiagnosticContext | undefined	Optional	Read-only. Parent observation scope for this invocation; never changes execution budget or signal.
prepared	PreparedModelCall<unknown> | undefined	Optional	Read-only. Reuse a prepared call; its stage, transport and output reservation then take precedence.
maxOutputTokens	number | undefined	Optional	Read-only. See the type definition and usage context.
stageId	string | undefined	Optional	Read-only. See the type definition and usage context.
transport	ModelTransportDefinition<unknown> | TransportId | undefined	Optional	Read-only. See the type definition and usage context.
input	string	Required	See the type definition and usage context.
instructions	string | undefined	Optional	See the type definition and usage context.

Branch 2

Field	Type	Required	Description
logger	SubFlowLogger | undefined	Optional	Read-only. Record this call in the supplied logger; omission adds no sub-flow record.
signal	AbortSignal | undefined	Optional	Read-only. Additional cancellation can shorten, never replace, the Runner lifetime.
diagnostics	DiagnosticContext | undefined	Optional	Read-only. Parent observation scope for this invocation; never changes execution budget or signal.
prepared	PreparedModelCall<unknown> | undefined	Optional	Read-only. Reuse a prepared call; its stage, transport and output reservation then take precedence.
maxOutputTokens	number | undefined	Optional	Read-only. See the type definition and usage context.
stageId	string | undefined	Optional	Read-only. See the type definition and usage context.
transport	ModelTransportDefinition<unknown> | TransportId | undefined	Optional	Read-only. See the type definition and usage context.
input	readonly ModelMessage[] | BuiltContext | ContextPlan	Required	See the type definition and usage context.
instructions	undefined	Optional	See the type definition and usage context.

Returns: Promise<ModelResult<unknown>>.

Awaited value: ModelResult<unknown>.

Return value structure

Field	Type	Required	Description
value	unknown	Required	Read-only. See the type definition and usage context.
invocation	Readonly<ModelCallRecord>	Required	Read-only. See the type definition and usage context.

Examples

• ModelRunner: input can be shortened while the output contract stays the same: Execute one model interaction through the real Provider port and return a value plus the invocation for this call.
• Actual request measurement and same-call preparation snapshot: Use prepare only when context must be handled ahead of time; multiple measurements and the final send reuse the same transport preparation.
• Child execution: isolated records, shared ancestor quota: A child Runner does not inherit conversation or the output receiver, but cannot bypass parent budget, cancellation, or deadlines.

Two inputs for the same output

Beginner · Node.js

TypeScript

import { ModelRunner } from '@jangts/agent-core/model';
const provider = {
  async *stream(messages: readonly { content: string }[]) {
    yield '收到：' + messages.at(-1)!.content;
  },
};
const runner = new ModelRunner({ provider });
const first = await runner.invoke('你好');
const second = await runner.invoke({ input: '你好' });
console.log(first.value, second.value);
console.log(first.invocation.invocationId);

JavaScript

import { ModelRunner } from '@jangts/agent-core/model';
const provider = {
    async *stream(messages) {
        yield '收到：' + messages.at(-1).content;
    },
};
const runner = new ModelRunner({ provider });
const first = await runner.invoke('你好');
const second = await runner.invoke({ input: '你好' });
console.log(first.value, second.value);
console.log(first.invocation.invocationId);

Add budget and request cancellation

Configuration · Node.js

TypeScript

import { ModelRunner } from '@jangts/agent-core/model';
const provider = {
  async *stream(messages: readonly { content: string }[]) {
    yield '收到：' + messages.at(-1)!.content;
  },
};
const runner = new ModelRunner({ provider, maxCalls: 2, maxInputChars: 4000,
  maxOutputChars: 2000, callTimeoutMs: 15000,
  execution: { signal: AbortSignal.timeout(20000) },
});
const result = await runner.invoke({ input: '你好', stageId: 'reply', maxOutputTokens: 600 });
console.log(result.value, runner.remainingCalls);

JavaScript

import { ModelRunner } from '@jangts/agent-core/model';
const provider = {
    async *stream(messages) {
        yield '收到：' + messages.at(-1).content;
    },
};
const runner = new ModelRunner({ provider, maxCalls: 2, maxInputChars: 4000,
    maxOutputChars: 2000, callTimeoutMs: 15000,
    execution: { signal: AbortSignal.timeout(20000) },
});
const result = await runner.invoke({ input: '你好', stageId: 'reply', maxOutputTokens: 600 });
console.log(result.value, runner.remainingCalls);

Add an independent ordered output receiver

Extension · Node.js

sink.output is awaited in order. model.output is a proposal that has not been fully validated, so tool operations proposed by the model must not be executed here.

TypeScript

import { ModelRunner } from '@jangts/agent-core/model';
const provider = {
  async *stream(messages: readonly { content: string }[]) {
    yield '收到：' + messages.at(-1)!.content;
  },
};
const events: string[] = [];
const runner = new ModelRunner({ provider, sink: {
  async output(event) { events.push(event.type); },
} });
const result = await runner.invoke('你好');
console.log(result.value, events);

JavaScript

import { ModelRunner } from '@jangts/agent-core/model';
const provider = {
    async *stream(messages) {
        yield '收到：' + messages.at(-1).content;
    },
};
const events = [];
const runner = new ModelRunner({ provider, sink: {
        async output(event) { events.push(event.type); },
    } });
const result = await runner.invoke('你好');
console.log(result.value, events);

Related policy source

• Core default budget values
• Same-call preparation and real input measurement

Related definitions

• ContextJournal
• ExecutionContext
• ModelCallRecord
• ModelCallRequest
• ModelCallTrace
• ModelChildOptions
• ModelChildPolicy
• ModelPrepareRequest
• ModelResult
• ModelRunnerOptions
• ModelRunnerSettings
• ModelTransportDefinition
• PreparedModelCall
• RegisteredTransportOutput