ModelOutputEvent

CORE · type · Type contract

Delivery sink, awaited in order. Parts are unvalidated proposals, never execution receipts.

Import

TypeScript

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

JavaScript

/** @typedef {import('@jangts/agent-core/model').ModelOutputEvent} ModelOutputEvent */

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

Definition

Type: ModelOutputEvent

Type expression

type ModelOutputEvent = Extract<
  import('../execution/events.js').CoreEvent,
  { type: 'model.start' | 'model.output' | 'model.parsed' | 'model.end' }
>;

Union branch structure

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

Branch 1

Field	Type	Required	Description
runId	string	Required	Read-only. Root run id shared by every fact of one logical run.
spanId	string	Required	Read-only. Span that produced the fact.
parentSpanId	string | undefined	Optional	Read-only. Enclosing span; absent for a root span.
invocationId	string | undefined	Optional	Read-only. Invocation that produced the fact, when the fact belongs to one.
parentInvocationId	string | undefined	Optional	Read-only. Enclosing invocation, when one invocation triggers another.
nodeRole	"invocation" | "workflow-node" | "workflow-boundary" | "loop-step" | undefined	Optional	Read-only. Role the emitting span plays in the execution graph.
agentId	string | undefined	Optional	Read-only. App-owned agent identity.
branchId	string | undefined	Optional	Read-only. App-owned branch identity.
agentVersionId	string | undefined	Optional	Read-only. App-owned immutable version identity of the agent definition.
parentBranchId	string | undefined	Optional	Read-only. Branch this branch was forked from, when applicable.
parentAgentVersionId	string | undefined	Optional	Read-only. Version of the parent branch at the fork point.
forkPointId	string | undefined	Optional	Read-only. App-owned fork marker shared by the forked branch and its origin.
workflowInvocationId	string | undefined	Optional	Read-only. Workflow invocation the fact belongs to.
workflowNodeId	string | undefined	Optional	Read-only. Workflow node invocation the fact belongs to.
definitionKind	string | undefined	Optional	Read-only. Kind of the workflow/agent definition that dispatched the node.
definitionId	string | undefined	Optional	Read-only. Id of that definition.
definitionRevision	string | undefined	Optional	Read-only. Revision of that definition; distinguishes executions of different definition states.
nodeId	string | undefined	Optional	Read-only. Node id inside the workflow.
nodeName	string | undefined	Optional	Read-only. Human-readable node name.
nodeKind	string | undefined	Optional	Read-only. Node kind as declared by the App.
nodeDescription	string | undefined	Optional	Read-only. Optional node description for diagnostics display.
stageId	string | undefined	Optional	Read-only. Model stage that produced the fact.
modelId	string | undefined	Optional	Read-only. Model binding used, when the fact concerns a model call.
version	2	Required	Envelope version; consumers must reject anything else.
eventId	string	Required	Unique id of this fact, stable across observers and log writers.
type	"model.output"	Required	Discriminator matching payload.
producerSequence	number	Required	Monotonic counter owned by the producing scope; starts at 1 for each producer.
occurredAtMs	number	Required	Instant the fact occurred, in epoch milliseconds.
payload	{ stageId: string; callSequence: number; partIndex: number; part: import("./model/messages.js").ModelPart; }	Required	Event-specific facts.
usedModel	boolean | undefined	Optional	Whether the reported step used a model; omitted when the producer did not state it.
subSteps	readonly RecordedSubStep[]	Required	Reported sub-steps attached to this fact, bounded and already validated.
subStepsDropped	number	Required	Number of reported sub-steps omitted by the recorder's bounds.
subStepsTruncated	boolean	Required	True when reported sub-steps were truncated, so the attached list is incomplete.

Branch 2

Field	Type	Required	Description
runId	string	Required	Read-only. Root run id shared by every fact of one logical run.
spanId	string	Required	Read-only. Span that produced the fact.
parentSpanId	string | undefined	Optional	Read-only. Enclosing span; absent for a root span.
invocationId	string | undefined	Optional	Read-only. Invocation that produced the fact, when the fact belongs to one.
parentInvocationId	string | undefined	Optional	Read-only. Enclosing invocation, when one invocation triggers another.
nodeRole	"invocation" | "workflow-node" | "workflow-boundary" | "loop-step" | undefined	Optional	Read-only. Role the emitting span plays in the execution graph.
agentId	string | undefined	Optional	Read-only. App-owned agent identity.
branchId	string | undefined	Optional	Read-only. App-owned branch identity.
agentVersionId	string | undefined	Optional	Read-only. App-owned immutable version identity of the agent definition.
parentBranchId	string | undefined	Optional	Read-only. Branch this branch was forked from, when applicable.
parentAgentVersionId	string | undefined	Optional	Read-only. Version of the parent branch at the fork point.
forkPointId	string | undefined	Optional	Read-only. App-owned fork marker shared by the forked branch and its origin.
workflowInvocationId	string | undefined	Optional	Read-only. Workflow invocation the fact belongs to.
workflowNodeId	string | undefined	Optional	Read-only. Workflow node invocation the fact belongs to.
definitionKind	string | undefined	Optional	Read-only. Kind of the workflow/agent definition that dispatched the node.
definitionId	string | undefined	Optional	Read-only. Id of that definition.
definitionRevision	string | undefined	Optional	Read-only. Revision of that definition; distinguishes executions of different definition states.
nodeId	string | undefined	Optional	Read-only. Node id inside the workflow.
nodeName	string | undefined	Optional	Read-only. Human-readable node name.
nodeKind	string | undefined	Optional	Read-only. Node kind as declared by the App.
nodeDescription	string | undefined	Optional	Read-only. Optional node description for diagnostics display.
stageId	string | undefined	Optional	Read-only. Model stage that produced the fact.
modelId	string | undefined	Optional	Read-only. Model binding used, when the fact concerns a model call.
version	2	Required	Envelope version; consumers must reject anything else.
eventId	string	Required	Unique id of this fact, stable across observers and log writers.
type	"model.parsed"	Required	Discriminator matching payload.
producerSequence	number	Required	Monotonic counter owned by the producing scope; starts at 1 for each producer.
occurredAtMs	number	Required	Instant the fact occurred, in epoch milliseconds.
payload	{ stageId: string; callSequence: number; value?: unknown; }	Required	Event-specific facts.
usedModel	boolean | undefined	Optional	Whether the reported step used a model; omitted when the producer did not state it.
subSteps	readonly RecordedSubStep[]	Required	Reported sub-steps attached to this fact, bounded and already validated.
subStepsDropped	number	Required	Number of reported sub-steps omitted by the recorder's bounds.
subStepsTruncated	boolean	Required	True when reported sub-steps were truncated, so the attached list is incomplete.

Branch 3

Field	Type	Required	Description
runId	string	Required	Read-only. Root run id shared by every fact of one logical run.
spanId	string	Required	Read-only. Span that produced the fact.
parentSpanId	string | undefined	Optional	Read-only. Enclosing span; absent for a root span.
invocationId	string | undefined	Optional	Read-only. Invocation that produced the fact, when the fact belongs to one.
parentInvocationId	string | undefined	Optional	Read-only. Enclosing invocation, when one invocation triggers another.
nodeRole	"invocation" | "workflow-node" | "workflow-boundary" | "loop-step" | undefined	Optional	Read-only. Role the emitting span plays in the execution graph.
agentId	string | undefined	Optional	Read-only. App-owned agent identity.
branchId	string | undefined	Optional	Read-only. App-owned branch identity.
agentVersionId	string | undefined	Optional	Read-only. App-owned immutable version identity of the agent definition.
parentBranchId	string | undefined	Optional	Read-only. Branch this branch was forked from, when applicable.
parentAgentVersionId	string | undefined	Optional	Read-only. Version of the parent branch at the fork point.
forkPointId	string | undefined	Optional	Read-only. App-owned fork marker shared by the forked branch and its origin.
workflowInvocationId	string | undefined	Optional	Read-only. Workflow invocation the fact belongs to.
workflowNodeId	string | undefined	Optional	Read-only. Workflow node invocation the fact belongs to.
definitionKind	string | undefined	Optional	Read-only. Kind of the workflow/agent definition that dispatched the node.
definitionId	string | undefined	Optional	Read-only. Id of that definition.
definitionRevision	string | undefined	Optional	Read-only. Revision of that definition; distinguishes executions of different definition states.
nodeId	string | undefined	Optional	Read-only. Node id inside the workflow.
nodeName	string | undefined	Optional	Read-only. Human-readable node name.
nodeKind	string | undefined	Optional	Read-only. Node kind as declared by the App.
nodeDescription	string | undefined	Optional	Read-only. Optional node description for diagnostics display.
stageId	string | undefined	Optional	Read-only. Model stage that produced the fact.
modelId	string | undefined	Optional	Read-only. Model binding used, when the fact concerns a model call.
version	2	Required	Envelope version; consumers must reject anything else.
eventId	string	Required	Unique id of this fact, stable across observers and log writers.
type	"model.end"	Required	Discriminator matching payload.
producerSequence	number	Required	Monotonic counter owned by the producing scope; starts at 1 for each producer.
occurredAtMs	number	Required	Instant the fact occurred, in epoch milliseconds.
payload	{ stageId: string; state: Readonly<ModelCallTrace>; error?: unknown; receivedParts: number; }	Required	Event-specific facts.
usedModel	boolean | undefined	Optional	Whether the reported step used a model; omitted when the producer did not state it.
subSteps	readonly RecordedSubStep[]	Required	Reported sub-steps attached to this fact, bounded and already validated.
subStepsDropped	number	Required	Number of reported sub-steps omitted by the recorder's bounds.
subStepsTruncated	boolean	Required	True when reported sub-steps were truncated, so the attached list is incomplete.

Branch 4

Field	Type	Required	Description
runId	string	Required	Read-only. Root run id shared by every fact of one logical run.
spanId	string	Required	Read-only. Span that produced the fact.
parentSpanId	string | undefined	Optional	Read-only. Enclosing span; absent for a root span.
invocationId	string | undefined	Optional	Read-only. Invocation that produced the fact, when the fact belongs to one.
parentInvocationId	string | undefined	Optional	Read-only. Enclosing invocation, when one invocation triggers another.
nodeRole	"invocation" | "workflow-node" | "workflow-boundary" | "loop-step" | undefined	Optional	Read-only. Role the emitting span plays in the execution graph.
agentId	string | undefined	Optional	Read-only. App-owned agent identity.
branchId	string | undefined	Optional	Read-only. App-owned branch identity.
agentVersionId	string | undefined	Optional	Read-only. App-owned immutable version identity of the agent definition.
parentBranchId	string | undefined	Optional	Read-only. Branch this branch was forked from, when applicable.
parentAgentVersionId	string | undefined	Optional	Read-only. Version of the parent branch at the fork point.
forkPointId	string | undefined	Optional	Read-only. App-owned fork marker shared by the forked branch and its origin.
workflowInvocationId	string | undefined	Optional	Read-only. Workflow invocation the fact belongs to.
workflowNodeId	string | undefined	Optional	Read-only. Workflow node invocation the fact belongs to.
definitionKind	string | undefined	Optional	Read-only. Kind of the workflow/agent definition that dispatched the node.
definitionId	string | undefined	Optional	Read-only. Id of that definition.
definitionRevision	string | undefined	Optional	Read-only. Revision of that definition; distinguishes executions of different definition states.
nodeId	string | undefined	Optional	Read-only. Node id inside the workflow.
nodeName	string | undefined	Optional	Read-only. Human-readable node name.
nodeKind	string | undefined	Optional	Read-only. Node kind as declared by the App.
nodeDescription	string | undefined	Optional	Read-only. Optional node description for diagnostics display.
stageId	string | undefined	Optional	Read-only. Model stage that produced the fact.
modelId	string | undefined	Optional	Read-only. Model binding used, when the fact concerns a model call.
version	2	Required	Envelope version; consumers must reject anything else.
eventId	string	Required	Unique id of this fact, stable across observers and log writers.
type	"model.start"	Required	Discriminator matching payload.
producerSequence	number	Required	Monotonic counter owned by the producing scope; starts at 1 for each producer.
occurredAtMs	number	Required	Instant the fact occurred, in epoch milliseconds.
payload	{ stageId: string; callSequence: number; transportId: string; }	Required	Event-specific facts.
usedModel	boolean | undefined	Optional	Whether the reported step used a model; omitted when the producer did not state it.
subSteps	readonly RecordedSubStep[]	Required	Reported sub-steps attached to this fact, bounded and already validated.
subStepsDropped	number	Required	Number of reported sub-steps omitted by the recorder's bounds.
subStepsTruncated	boolean	Required	True when reported sub-steps were truncated, so the attached list is incomplete.

Examples

• Body preview: ordered output is not final acceptance: Extract displayable body text by registered stage/tool/field path, and refuse to treat control proposals as executed results.

Add a preview for a plain-text stage

Beginner · Node.js

TypeScript

import { ModelRunner, Support } from '@jangts/agent-core';
const preview = Support.createReplyPreview({ rules: [{ stageId: 'reply' }],
  sink: bubbles => { console.log('preview', bubbles); },
});
const runner = new ModelRunner({ provider: { async *stream() { yield '你好'; yield '，Core'; } }, sink: { output: preview } });
console.log((await runner.invoke({ input: '你好', stageId: 'reply' })).value);

JavaScript

import { ModelRunner, Support } from '@jangts/agent-core';
const preview = Support.createReplyPreview({ rules: [{ stageId: 'reply' }],
    sink: bubbles => { console.log('preview', bubbles); },
});
const runner = new ModelRunner({ provider: { async *stream() { yield '你好'; yield '，Core'; } }, sink: { output: preview } });
console.log((await runner.invoke({ input: '你好', stageId: 'reply' })).value);

Allow only displayable fields of an explicit body protocol

Configuration · Node.js

Rules must correspond to the reply tool and Schema the App actually registers; configuring a preview does not create a model tool.

TypeScript

import { Support } from '@jangts/agent-core';
const preview = Support.createReplyPreview({
  rules: [{ stageId: 'reply', toolId: 'reply', paths: [['answer'], ['bubbles', '*']],
    when: { path: ['kind'], values: ['reply'] } }],
  sink: async bubbles => { console.log('当前暂态正文', bubbles); },
  maxChars: 4000,
});
console.log(typeof preview);

JavaScript

import { Support } from '@jangts/agent-core';
const preview = Support.createReplyPreview({
    rules: [{ stageId: 'reply', toolId: 'reply', paths: [['answer'], ['bubbles', '*']],
            when: { path: ['kind'], values: ['reply'] } }],
    sink: async (bubbles) => { console.log('当前暂态正文', bubbles); },
    maxChars: 4000,
});
console.log(typeof preview);

Related definitions

• DiagnosticIdentity
• RecordedSubStep