WorkflowStore
Defined in: packages/core/src/stores/workflow-store.ts:77
Workflow run persistence: materialized run/step I/O plus append-only RunEvents.
Observers (WorkflowObserver) are push-only — no reads. WorkflowStore supports
queries (listRuns, listEvents, getStepOutput) for UI and step skip on retry.
RunRecorder writes to both when configured. Separate from MessageStore.
Default implementation: inMemoryWorkflowStore.
Methods
Section titled “Methods”createSuspend()
Section titled “createSuspend()”createSuspend(
args):Promise<void>
Defined in: packages/core/src/stores/workflow-store.ts:155
Persist a pending suspend for a live run. Does not emit events: the parked
run’s recorder emits workflow_suspended / workflow_resumed, so runSeq
has one allocator. A run may hold several pending suspends (parallel steps);
a duplicate handle id throws.
Parameters
Section titled “Parameters”handle
Section titled “handle”intent
Section titled “intent”Returns
Section titled “Returns”Promise<void>
deleteRun()
Section titled “deleteRun()”deleteRun(
workflowRunId):Promise<void>
Defined in: packages/core/src/stores/workflow-store.ts:124
Remove a run and its events / step records.
Parameters
Section titled “Parameters”workflowRunId
Section titled “workflowRunId”string
Returns
Section titled “Returns”Promise<void>
getLatestEvent()
Section titled “getLatestEvent()”getLatestEvent<
T>(scope,type):Promise<RunEventOfType<T> |null>
Defined in: packages/core/src/stores/workflow-store.ts:87
Type Parameters
Section titled “Type Parameters”T extends "custom" | "workflow_started" | "workflow_finished" | "workflow_failed" | "workflow_cancelled" | "workflow_suspended" | "workflow_resumed" | "step_started" | "step_finished" | "step_skipped" | "step_failed" | "workflow_title_set" | "effect_intent" | "effect_settled" | "agent_started" | "agent_finished" | "agent_failed" | "agent_warning" | "agent_tool_call" | "agent_tool_result" | "agent_text_delta" | "agent_messages_committed" | "agent_title_set" | "conversation_forked"
Parameters
Section titled “Parameters”T
Returns
Section titled “Returns”Promise<RunEventOfType<T> | null>
getRun()
Section titled “getRun()”getRun(
workflowRunId):Promise<WorkflowRunSummary|null>
Defined in: packages/core/src/stores/workflow-store.ts:92
Parameters
Section titled “Parameters”workflowRunId
Section titled “workflowRunId”string
Returns
Section titled “Returns”Promise<WorkflowRunSummary | null>
getRunInput()
Section titled “getRunInput()”getRunInput(
workflowRunId):Promise<unknown>
Defined in: packages/core/src/stores/workflow-store.ts:112
Parameters
Section titled “Parameters”workflowRunId
Section titled “workflowRunId”string
Returns
Section titled “Returns”Promise<unknown>
getRunOutput()
Section titled “getRunOutput()”getRunOutput(
workflowRunId):Promise<unknown>
Defined in: packages/core/src/stores/workflow-store.ts:113
Parameters
Section titled “Parameters”workflowRunId
Section titled “workflowRunId”string
Returns
Section titled “Returns”Promise<unknown>
getStepById()
Section titled “getStepById()”getStepById(
workflowRunId,stepId):Promise<StepRecord|null>
Defined in: packages/core/src/stores/workflow-store.ts:115
Parameters
Section titled “Parameters”workflowRunId
Section titled “workflowRunId”string
stepId
Section titled “stepId”string
Returns
Section titled “Returns”Promise<StepRecord | null>
getStepOutput()
Section titled “getStepOutput()”getStepOutput(
workflowRunId,slot):Promise<unknown>
Defined in: packages/core/src/stores/workflow-store.ts:114
Parameters
Section titled “Parameters”workflowRunId
Section titled “workflowRunId”string
Returns
Section titled “Returns”Promise<unknown>
getSuspend()
Section titled “getSuspend()”getSuspend(
handleId):Promise<SuspendRecord|null>
Defined in: packages/core/src/stores/workflow-store.ts:157
Parameters
Section titled “Parameters”handleId
Section titled “handleId”string
Returns
Section titled “Returns”Promise<SuspendRecord | null>
listAgentEpisodes()
Section titled “listAgentEpisodes()”listAgentEpisodes(
filter?):Promise<AgentEpisodeSummary[]>
Defined in: packages/core/src/stores/workflow-store.ts:127
Standalone and in-workflow agent episodes, newest first.
Parameters
Section titled “Parameters”filter?
Section titled “filter?”agentId?
Section titled “agentId?”string
limit?
Section titled “limit?”number
Returns
Section titled “Returns”Promise<AgentEpisodeSummary[]>
listDescendantRuns()
Section titled “listDescendantRuns()”listDescendantRuns(
workflowRunId):Promise<WorkflowRunSummary[]>
Defined in: packages/core/src/stores/workflow-store.ts:111
All nested runs under workflowRunId at any depth (BFS over
WorkflowRunSummary.parentWorkflowRunId). Does not include the
starting run. Works when workflowRunId is a mid-tree node.
Parameters
Section titled “Parameters”workflowRunId
Section titled “workflowRunId”string
Returns
Section titled “Returns”Promise<WorkflowRunSummary[]>
listEvents()
Section titled “listEvents()”listEvents(
scope,filter?):Promise<RunEvent[]>
Defined in: packages/core/src/stores/workflow-store.ts:85
Read events for a workflow run or a standalone agent episode.
Workflow-scoped queries return workflow + step + custom events for that workflowRunId.
Agent-scoped queries return agent events for that agentCallId.
Parameters
Section titled “Parameters”filter?
Section titled “filter?”Returns
Section titled “Returns”Promise<RunEvent[]>
listPendingSuspends()
Section titled “listPendingSuspends()”listPendingSuspends(
filter?):Promise<SuspendRecord[]>
Defined in: packages/core/src/stores/workflow-store.ts:160
Pending (unresolved) suspends, optionally for one run.
Parameters
Section titled “Parameters”filter?
Section titled “filter?”workflowRunId?
Section titled “workflowRunId?”string
Returns
Section titled “Returns”Promise<SuspendRecord[]>
listRuns()
Section titled “listRuns()”listRuns(
filter?):Promise<WorkflowRunSummary[]>
Defined in: packages/core/src/stores/workflow-store.ts:99
List workflow runs, oldest first (contrast listAgentEpisodes, newest first).
tags matches runs carrying any of the given tags (OR semantics).
parentWorkflowRunId filters to immediate children of that run.
rootsOnly keeps only runs with no parent (top-level and isolated).
Parameters
Section titled “Parameters”filter?
Section titled “filter?”limit?
Section titled “limit?”number
parentWorkflowRunId?
Section titled “parentWorkflowRunId?”string
rootsOnly?
Section titled “rootsOnly?”boolean
string[]
workflowId?
Section titled “workflowId?”string
Returns
Section titled “Returns”Promise<WorkflowRunSummary[]>
listStepRecords()
Section titled “listStepRecords()”listStepRecords(
workflowRunId):Promise<StepRecord[]>
Defined in: packages/core/src/stores/workflow-store.ts:117
Seeded / replayed step projections for a run (excludes in-flight steps without records).
Parameters
Section titled “Parameters”workflowRunId
Section titled “workflowRunId”string
Returns
Section titled “Returns”Promise<StepRecord[]>
materializeAttemptRun()
Section titled “materializeAttemptRun()”materializeAttemptRun(
run):Promise<void>
Defined in: packages/core/src/stores/workflow-store.ts:144
Write a seeded run projection (no event-log duplication).
Parameters
Section titled “Parameters”Returns
Section titled “Returns”Promise<void>
materializeAttemptStep()
Section titled “materializeAttemptStep()”materializeAttemptStep(
step):Promise<void>
Defined in: packages/core/src/stores/workflow-store.ts:147
Write a seeded step projection + path-stable output slot.
Parameters
Section titled “Parameters”Returns
Section titled “Returns”Promise<void>
recordEvent()
Section titled “recordEvent()”recordEvent(
event):Promise<void>
Defined in: packages/core/src/stores/workflow-store.ts:78
Parameters
Section titled “Parameters”Returns
Section titled “Returns”Promise<void>
resolveSuspend()
Section titled “resolveSuspend()”resolveSuspend(
handleId,decision):Promise<void>
Defined in: packages/core/src/stores/workflow-store.ts:166
Resume with allow / deny / rewrite and wake the waiter. Missing or already-resolved handles fail closed — the effect is not allowed.
Parameters
Section titled “Parameters”handleId
Section titled “handleId”string
decision
Section titled “decision”Returns
Section titled “Returns”Promise<void>
seedRetryAttempt()
Section titled “seedRetryAttempt()”seedRetryAttempt(
args):Promise<RetryAttempt>
Defined in: packages/core/src/stores/workflow-store.ts:141
Compatibility: seed from (fromWorkflowRunId, fromStepId) via a step-boundary cursor.
Throws if fromStepId is unknown. Does not mutate the prior attempt.
Parameters
Section titled “Parameters”Returns
Section titled “Returns”Promise<RetryAttempt>
seedRetryFromCursor()
Section titled “seedRetryFromCursor()”seedRetryFromCursor(
args):Promise<RetryAttempt>
Defined in: packages/core/src/stores/workflow-store.ts:135
Seed a new attempt forest from a import(”../effect/types”).TraceCursor.
effectId resolves via effect_intent on the run log to the enclosing step
(step-atomic). stepId is the UI alias. Unknown / root-level effectId and
runSeq throw. Does not mutate the prior attempt.
Parameters
Section titled “Parameters”Returns
Section titled “Returns”Promise<RetryAttempt>
setRunTags()
Section titled “setRunTags()”setRunTags(
workflowRunId,tags):Promise<void>
Defined in: packages/core/src/stores/workflow-store.ts:122
Replace a run’s WorkflowRunSummary.tags.
Parameters
Section titled “Parameters”workflowRunId
Section titled “workflowRunId”string
string[]
Returns
Section titled “Returns”Promise<void>
setRunTitle()
Section titled “setRunTitle()”setRunTitle(
workflowRunId,title):Promise<void>
Defined in: packages/core/src/stores/workflow-store.ts:120
Set a display title without changing WorkflowRunSummary.workflowRunId.
Parameters
Section titled “Parameters”workflowRunId
Section titled “workflowRunId”string
string
Returns
Section titled “Returns”Promise<void>
waitForSuspendResolution()
Section titled “waitForSuspendResolution()”waitForSuspendResolution(
handleId):Promise<SuspendResolveDecision>
Defined in: packages/core/src/stores/workflow-store.ts:173
Wait until resolveSuspend. Already-resolved handles return the stored
decision. Waiters are process-local — a new process must not assume the
original workflow.run closure is still parked.
Parameters
Section titled “Parameters”handleId
Section titled “handleId”string
Returns
Section titled “Returns”Promise<SuspendResolveDecision>