Workflow lifecycle
Model explicit runs, steps, hierarchy, attempts, and workflow ownership without inferring identity from labels or timing.
Maintained by Bhavesh Chowdhury
Workflow identity
runId and stepId identify logical work. runInstanceId and
stepInstanceId identify one attempt. A step always belongs to a run, and an
attempt ID cannot be supplied without its logical ID.
| Field | Meaning | Constraint |
|---|---|---|
| runId | Logical run | Required for every run and step event |
| runInstanceId | Run attempt | Optional; requires runId |
| stepId | Logical step | Optional only when the source lacks stable step identity |
| stepInstanceId | Step attempt | Optional; requires stepId and runId |
Run and step events
Run and identified step lifecycles start once and end once. A run cannot complete while it has active identified child runs or steps. Terminal and retry events cancel announcements owned by the ended or replaced attempt.
Prop
Type
WorkflowContext
Responses, tools, interactions, and approvals can carry workflow context. This connects existing lifecycle events to the run or step that owns them without turning those entities into steps.
runtime.dispatch({
type: "tool.started",
toolId: "search",
toolInstanceId: "search-2",
runId: "report",
runInstanceId: "report-1",
stepId: "sources",
stepInstanceId: "sources-2",
label: "Search sources",
});Partial identity
When a framework exposes only a step name, omit stepId. Core emits a
partial-identity diagnostic but does not create a step snapshot, announcement,
or run summary count from that evidence. It never converts labels, array
positions, or timing into identity.