WorkflowRunStartOptions

WorkflowRunStartOptions = object

Defined in: packages/core/src/workflow/types.ts:169

Optional start parameters for Workflow.run. Hosts (e.g. inspection UI) may attach per-run observers for in-process event tails; persisted history still goes through WorkflowStore on the runtime.

Properties

extraObservers?

optional extraObservers?: object

Defined in: packages/core/src/workflow/types.ts:183

Merged with runtime observers for this invocation only.

agents?

optional agents?: AgentObservers

workflows?

optional workflows?: WorkflowObservers

---

isolated?

optional isolated?: boolean

Defined in: packages/core/src/workflow/types.ts:203

When true, start an unlinked workflow run (no parent pointer).

Default (omitted / false): inside a workflow body or step, run() nests under the active parent via ALS (or parentCtx when passed): new workflowRunId, parentWorkflowRunId set, abort linked to the parent.

{ isolated: true }:

• Ignores ALS and parentCtx; allocates a new workflowRunId
• parentWorkflowRunId is null (not in another run’s child list)
• Still recorded on WorkflowStore (own run row, events, step cache)

Inspection UI lists runs only for workflows in the project’s workflows array. Leave a helper out of that array to persist it without listing it as a startable workflow (conversation titleWorkflow helpers use this).

---

parentCtx?

optional parentCtx?: WorkflowContext

Defined in: packages/core/src/workflow/types.ts:181

Nest under an existing workflow run. When omitted inside a workflow body or step, the active WorkflowContext is read from the runtime’s scoped ALS — same pattern as agent.run workflow linkage.

Nested runs allocate their own workflowRunId, record parentWorkflowRunId on the child, and link abort to the parent. Steps and agents bind to the child run (separate step cache and event stream).

---

retryAttempt?

optional retryAttempt?: RetryAttempt

Defined in: packages/core/src/workflow/types.ts:222

Seeded attempt from WorkflowStore.seedRetryAttempt. Pass the attempt (and usually workflowRunId: attempt.newRootRunId) so nested child.run resolves mapped child ids and skip cache applies to replayed prefixes.

---

tags?

optional tags?: string[]

Defined in: packages/core/src/workflow/types.ts:216

Labels recorded on the run (e.g. ["dataset:qa-v1"]). The inspection UI shows them in a Tags footer; there is no run-list filter yet. Set once at start; see WorkflowStore.setRunTags to change them after the fact.

Every workflow.run() also records which project code produced it, unless a caller tag already uses the same prefix: version:<value> when AdlRuntimeConfig.version is a string, otherwise commit:<id> from jj @ first and git HEAD second, with +dirty when the tree has uncommitted work. Pass version: false on the runtime to skip that lookup.

---

workflowRunId?

optional workflowRunId?: string

Defined in: packages/core/src/workflow/types.ts:171

Pre-allocate a run id so subscribers can connect before execution finishes.