ExecutionObserver
CORE · interface · Type contract
Live consumer of Core facts.
Import
ts
import type { ExecutionObserver } from '@jangts/agent-core';js
/** @typedef {import('@jangts/agent-core').ExecutionObserver} ExecutionObserver */Other public entry points:@jangts/agent-core, @jangts/agent-core/types, @jangts/agent-core/structs.
Definition
ts
interface ExecutionObserverField structure
| Field | Type | Required | Description |
|---|---|---|---|
accepts | ((descriptor: Readonly<ExecutionEventDescriptor>) => boolean) | undefined | Optional | Metadata-only by default. Content requires an explicit accepts decision. |
event | (event: Readonly<CoreEvent>) => void | Promise<void> | Required | Handles one fact; a rejected promise propagates to the emitting call. |
Member index
| Member | Purpose |
|---|---|
event | Handles one fact; a rejected promise propagates to the emitting call. |
Member details
event
Handles one fact; a rejected promise propagates to the emitting call.
ts
ExecutionObserver.event(event: Readonly<CoreEvent>): void | Promise<void>Handles one fact; a rejected promise propagates to the emitting call.
| Parameter | Type | Passing | Description |
|---|---|---|---|
event | Readonly<CoreEvent> | Required | — |
Optional shapes of Parameter event: 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 | "loop.event" | 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 | LoopEvent | 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.binding" | 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 | { modelId: string; invocationId: string; status: "running" | "success" | "error" | "cancelled"; phase: "input" | "invoke" | "output"; durationMs?: number; errorCode?: 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. |
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.prepare" | 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; transportId: string; messages: readonly ModelMessage[]; options: unknown; context?: 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 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.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 5
| 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 6
| 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 7
| 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 | "runtime.rejected" | 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; error: 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 8
| 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 | "node.progress" | 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 | { payload?: unknown; subStep?: import("./debug.js").SubStepProgress; reportError?: "INVALID_NODE_REPORT"; } | 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 9
| 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. |
Branch 10
| 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 | "workflow.event" | 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 | { event: WorkflowEvent; payload?: 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 11
| 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 | "tool.call" | 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 | { toolId: string; invocationId: string; input?: 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 12
| 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 | "tool.result" | 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 | { toolId: string; invocationId: string; value?: unknown; error?: unknown; errorCode?: string; status: import("./common.js").InvocationStatus; durationMs: 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 13
| 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 | "rule.result" | 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 | { tags: readonly string[]; error: 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. |
Returns: void \| Promise<void>.
Awaited value: void.
Examples
- Process observation and node reports: The App subscribes to Core execution facts; nodes report their own usedModel and use an instance sub-logger to record intent first and then results, while the Loop owns identity and logging.
Observe the nodes and model events a task passes through
Beginner · Node.js
ts
import { AgentCoreEngine, defineWorkflow, route } from '@jangts/agent-core/engine';
type State = { name: string; answer?: string };
const workflow = defineWorkflow<State, string>({
id: 'greeting',
nodes: [{
id: 'greet', description: '根据本次姓名生成问候', startsRound: true,
run: state => ({ answer: '你好，' + state.name }),
routes: [route.deliver('answer')],
}],
});
const agent = new AgentCoreEngine({ workflow, execution: {
observe: { event(event) { console.log(event.type, event.eventId); } },
} });
console.log(await agent.run({ name: 'Ivan' }));js
import { AgentCoreEngine, defineWorkflow, route } from '@jangts/agent-core/engine';
const workflow = defineWorkflow({
id: 'greeting',
nodes: [{
id: 'greet', description: '根据本次姓名生成问候', startsRound: true,
run: state => ({ answer: '你好，' + state.name }),
routes: [route.deliver('answer')],
}],
});
const agent = new AgentCoreEngine({ workflow, execution: {
observe: { event(event) { console.log(event.type, event.eventId); } },
} });
console.log(await agent.run({ name: 'Ivan' }));Report a business stage while the node executes
Configuration · Node.js
The node only reports facts it knows; Core owns node identity and execution association.
ts
import { AgentCoreEngine, defineWorkflow, route } from '@jangts/agent-core/engine';
type State = { name: string; answer?: string };
const workflow = defineWorkflow<State, string>({ id: 'greeting', nodes: [{
id: 'greet', description: '生成问候', startsRound: true,
run(state, context) {
context.report({ payload: { phase: 'formatting' } });
return { answer: '你好，' + state.name };
}, routes: [route.deliver('answer')],
}] });
const agent = new AgentCoreEngine({ workflow, execution: {
observe: { event(event) { console.log(event.type); } },
} });
console.log(await agent.run({ name: 'Ivan' }));js
import { AgentCoreEngine, defineWorkflow, route } from '@jangts/agent-core/engine';
const workflow = defineWorkflow({ id: 'greeting', nodes: [{
id: 'greet', description: '生成问候', startsRound: true,
run(state, context) {
context.report({ payload: { phase: 'formatting' } });
return { answer: '你好，' + state.name };
}, routes: [route.deliver('answer')],
}] });
const agent = new AgentCoreEngine({ workflow, execution: {
observe: { event(event) { console.log(event.type); } },
} });
console.log(await agent.run({ name: 'Ivan' }));