Skip to content
LLM Workbench
Sign in

Reference · API

API reference, generated from source

Public exports from all five packages, regenerated from their JSDoc comments every time the web app builds.

Getting startedArchitectureProtocol referenceSource on GitHub

Runtime

#Classes

#HttpRunRepository

Defined in: packages/runtime/src/persistence/http.ts:59

Minimal REST adapter expecting:

  • PUT ${baseUrl}/runs/:runId body: JSON serialized RunStoreState
  • GET ${baseUrl}/runs/:runId
  • GET ${baseUrl}/runs?limit=...
  • DELETE ${baseUrl}/runs/:runId

The host server must enforce authZ/authN.

#Implements

  • RunRepository

#Constructors

#Constructor

new HttpRunRepository(opts): HttpRunRepository

Defined in: packages/runtime/src/persistence/http.ts:62

#Parameters

#opts

HttpRunRepositoryOptions

#Returns

HttpRunRepository

#Methods

#delete()

delete(runId, opts?): Promise<void>

Defined in: packages/runtime/src/persistence/http.ts:236

#Parameters

#runId

string

#opts?

#signal?

AbortSignal

#Returns

Promise<void>

#Implementation of

RunRepository.delete

#list()

list(opts?): Promise<SavedRunMeta[]>

Defined in: packages/runtime/src/persistence/http.ts:207

#Parameters

#opts?

#limit?

number

#signal?

AbortSignal

#Returns

Promise<SavedRunMeta[]>

#Implementation of

RunRepository.list

#load()

load(runId, opts?): Promise<RunStoreState | null>

Defined in: packages/runtime/src/persistence/http.ts:183

#Parameters

#runId

string

#opts?

#signal?

AbortSignal

#Returns

Promise<RunStoreState | null>

#Implementation of

RunRepository.load

#save()

save(state, opts?): Promise<void>

Defined in: packages/runtime/src/persistence/http.ts:162

#Parameters

#state

RunStoreState

#opts?

#signal?

AbortSignal

#Returns

Promise<void>

#Implementation of

RunRepository.save

#IndexedDbRunRepository

Defined in: packages/runtime/src/persistence/indexeddb.ts:60

Browser persistence. Host apps should scope sensitive data to authenticated users (separate DB per user profile, or encrypt payloads before storing).

Use IndexedDbRunRepository.isSupported() before instantiating in code that may also run on the server (Next.js, Remix, etc.) to avoid throwing at construction.

#Implements

  • RunRepository

#Constructors

#Constructor

new IndexedDbRunRepository(): IndexedDbRunRepository

#Returns

IndexedDbRunRepository

#Methods

#delete()

delete(runId): Promise<void>

Defined in: packages/runtime/src/persistence/indexeddb.ts:120

#Parameters

#runId

string

#Returns

Promise<void>

#Implementation of

RunRepository.delete

#list()

list(opts?): Promise<SavedRunMeta[]>

Defined in: packages/runtime/src/persistence/indexeddb.ts:89

#Parameters

#opts?

#limit?

number

#Returns

Promise<SavedRunMeta[]>

#Implementation of

RunRepository.list

#load()

load(runId): Promise<RunStoreState | null>

Defined in: packages/runtime/src/persistence/indexeddb.ts:76

#Parameters

#runId

string

#Returns

Promise<RunStoreState | null>

#Implementation of

RunRepository.load

#save()

save(state): Promise<void>

Defined in: packages/runtime/src/persistence/indexeddb.ts:66

#Parameters

#state

RunStoreState

#Returns

Promise<void>

#Implementation of

RunRepository.save

#isSupported()

static isSupported(): boolean

Defined in: packages/runtime/src/persistence/indexeddb.ts:62

True when the current global has a usable indexedDB implementation.

#Returns

boolean

#MemoryArtifactStore

Defined in: packages/runtime/src/persistence/artifactStore.ts:66

In-memory ArtifactStore reference implementation. Intended for tests, local development, and as a copy-paste starting point for production adapters. Not safe across processes.

#Implements

  • ArtifactStore

#Constructors

#Constructor

new MemoryArtifactStore(): MemoryArtifactStore

#Returns

MemoryArtifactStore

#Methods

#delete()

delete(input): Promise<void>

Defined in: packages/runtime/src/persistence/artifactStore.ts:94

#Parameters

#input

#ref

string

#runId

string

#Returns

Promise<void>

#Implementation of

ArtifactStore.delete

#get()

get(input): Promise<ArtifactStoreGetResult>

Defined in: packages/runtime/src/persistence/artifactStore.ts:83

#Parameters

#input

#ref

string

#runId

string

#Returns

Promise<ArtifactStoreGetResult>

#Implementation of

ArtifactStore.get

#put()

put(input): Promise<ArtifactStorePutResult>

Defined in: packages/runtime/src/persistence/artifactStore.ts:73

#Parameters

#input

ArtifactStorePutInput

#Returns

Promise<ArtifactStorePutResult>

#Implementation of

ArtifactStore.put

#size()

size(): number

Defined in: packages/runtime/src/persistence/artifactStore.ts:99

Test/inspection helper. Not part of the ArtifactStore contract.

#Returns

number

#MemoryRunRepository

Defined in: packages/runtime/src/persistence/memory.ts:5

Persistence port. Authentication/authorization is always the host app's responsibility (attach cookies, bearer tokens, signed URLs, etc. in HttpRunRepository options).

The optional signal argument lets callers cancel in-flight operations (e.g. on component unmount). Implementations that cannot cancel should still accept the option and ignore it.

#Implements

  • RunRepository

#Constructors

#Constructor

new MemoryRunRepository(): MemoryRunRepository

#Returns

MemoryRunRepository

#Methods

#delete()

delete(runId): Promise<void>

Defined in: packages/runtime/src/persistence/memory.ts:26

#Parameters

#runId

string

#Returns

Promise<void>

#Implementation of

RunRepository.delete

#list()

list(opts?): Promise<SavedRunMeta[]>

Defined in: packages/runtime/src/persistence/memory.ts:18

#Parameters

#opts?

#limit?

number

#Returns

Promise<SavedRunMeta[]>

#Implementation of

RunRepository.list

#load()

load(runId): Promise<RunStoreState | null>

Defined in: packages/runtime/src/persistence/memory.ts:13

#Parameters

#runId

string

#Returns

Promise<RunStoreState | null>

#Implementation of

RunRepository.load

#save()

save(state): Promise<void>

Defined in: packages/runtime/src/persistence/memory.ts:8

#Parameters

#state

RunStoreState

#Returns

Promise<void>

#Implementation of

RunRepository.save

#SchemaRegistry

Defined in: packages/runtime/src/schema/registry.ts:39

#Constructors

#Constructor

new SchemaRegistry(): SchemaRegistry

#Returns

SchemaRegistry

#Methods

#applyValidatedPatch()

applyValidatedPatch(input): { data: unknown; ok: true; } | { errors: ErrorObject<string, Record<string, any>, unknown>[]; ok: false; }

Defined in: packages/runtime/src/schema/registry.ts:99

#Parameters

#input

#base

unknown

#patch

Operation[]

#typeId

string

#Returns

{ data: unknown; ok: true; } | { errors: ErrorObject<string, Record<string, any>, unknown>[]; ok: false; }

#getExportRedactPaths()

getExportRedactPaths(typeId): string[]

Defined in: packages/runtime/src/schema/registry.ts:59

#Parameters

#typeId

string

#Returns

string[]

#registerArtifactType()

registerArtifactType(input): void

Defined in: packages/runtime/src/schema/registry.ts:49

#Parameters

#input

RegisterArtifactTypeInput

#Returns

void

#registerRulePayloadSchema()

registerRulePayloadSchema(input): void

Defined in: packages/runtime/src/schema/registry.ts:63

#Parameters

#input

RegisterRulePayloadSchemaInput

#Returns

void

#validateArtifact()

validateArtifact(typeId, data): { ok: true; } | { errors: ErrorObject<string, Record<string, any>, unknown>[]; ok: false; }

Defined in: packages/runtime/src/schema/registry.ts:68

#Parameters

#typeId

string

#data

unknown

#Returns

{ ok: true; } | { errors: ErrorObject<string, Record<string, any>, unknown>[]; ok: false; }

#validateRulePayload()

validateRulePayload(ruleSchemaId, payload): { ok: true; } | { errors: ErrorObject<string, Record<string, any>, unknown>[]; ok: false; }

Defined in: packages/runtime/src/schema/registry.ts:76

#Parameters

#ruleSchemaId

string

#payload

unknown

#Returns

{ ok: true; } | { errors: ErrorObject<string, Record<string, any>, unknown>[]; ok: false; }

#validateRuleSet()

validateRuleSet(input): { ok: true; } | { errors: object[]; ok: false; }

Defined in: packages/runtime/src/schema/registry.ts:84

#Parameters

#input

#rules

object[]

#ruleSchemaId

string

#Returns

{ ok: true; } | { errors: object[]; ok: false; }

#WorkbenchError

Defined in: packages/runtime/src/errors.ts:34

#Extends

  • Error

#Constructors

#Constructor

new WorkbenchError(code, message, cause?): WorkbenchError

Defined in: packages/runtime/src/errors.ts:38

#Parameters

#code

WorkbenchErrorCode

#message

string

#cause?

unknown

#Returns

WorkbenchError

#Overrides

Error.constructor

#Properties

#cause?

optional cause?: unknown

Defined in: node_modules/typescript/lib/lib.es2022.error.d.ts:26

#Inherited from

Error.cause

#code

readonly code: WorkbenchErrorCode

Defined in: packages/runtime/src/errors.ts:36

#message

message: string

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1077

#Inherited from

Error.message

#name

readonly name: "WorkbenchError" = "WorkbenchError"

Defined in: packages/runtime/src/errors.ts:35

#Overrides

Error.name

#stack?

optional stack?: string

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1078

#Inherited from

Error.stack

#stackTraceLimit

static stackTraceLimit: number

Defined in: node_modules/@types/node/globals.d.ts:68

The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).

The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

#Inherited from

Error.stackTraceLimit

#Methods

#toJSON()

toJSON(): WorkbenchErrorJson

Defined in: packages/runtime/src/errors.ts:48

#Returns

WorkbenchErrorJson

#captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void

Defined in: node_modules/@types/node/globals.d.ts:52

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();

#Parameters

#targetObject

object

#constructorOpt?

Function

#Returns

void

#Inherited from

Error.captureStackTrace

#is()

static is(e): e is WorkbenchError

Defined in: packages/runtime/src/errors.ts:52

#Parameters

#e

unknown

#Returns

e is WorkbenchError

#prepareStackTrace()

static prepareStackTrace(err, stackTraces): any

Defined in: node_modules/@types/node/globals.d.ts:56

#Parameters

#err

Error

#stackTraces

CallSite[]

#Returns

any

#See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

#Inherited from

Error.prepareStackTrace

#WorkbenchRuntime

Defined in: packages/runtime/src/runtime/workbench.ts:54

#Constructors

#Constructor

new WorkbenchRuntime(options?): WorkbenchRuntime

Defined in: packages/runtime/src/runtime/workbench.ts:61

#Parameters

#options?

WorkbenchRuntimeOptions

#Returns

WorkbenchRuntime

#Methods

#cancelRunCascade()

cancelRunCascade(rootRunId, opts?): string[]

Defined in: packages/runtime/src/runtime/workbench.ts:288

Cancel a run and, transitively, every descendant run held by this runtime. Each cancellation goes through WorkbenchSession.cancelRun so the standard run_status_changed trace event is emitted on every run. Already-terminal runs (completed, failed, cancelled) are skipped.

Returns the ids that were actually transitioned to cancelled, in the order they were processed (root first, then breadth-first descendants).

#Parameters

#rootRunId

string

#opts?

#reason?

string

#Returns

string[]

#deleteRun()

deleteRun(runId): boolean

Defined in: packages/runtime/src/runtime/workbench.ts:246

Returns true if the run was present and removed.

#Parameters

#runId

string

#Returns

boolean

#getState()

getState(runId): RunStoreState | undefined

Defined in: packages/runtime/src/runtime/workbench.ts:215

#Parameters

#runId

string

#Returns

RunStoreState | undefined

#importRunBundle()

importRunBundle(input): Promise<{ runId: string; }>

Defined in: packages/runtime/src/runtime/workbench.ts:321

Imports a RunBundle into this runtime (overwrites if run.id already exists). When engine is missing, gate/step state is inferred from the trace (best-effort).

#Parameters

#input

{ json: string; verifyIntegrity?: boolean; } | { bundle: { artifacts: object[]; engine?: { gateState: [string, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints: Record<string, "pending" | "approved">; }][]; idempotency: [string, { artifactKey: string; version: number; }][]; revision: number; stepStatus: [string, "pending" | "running" | "completed" | "failed"][]; }; integrity?: { sha256: string; }; protocolVersion: "1.0.0"; ruleSets: object[]; run: { annotations?: object[]; context?: { forkedFromStepId?: string; parentRunId?: string; parentRunIds?: string[]; pinnedArtifacts?: object[]; }; endedAt?: string; id: string; metadata?: Record<string, JsonValue>; startedAt: string; status: "running" | "completed" | "failed" | "cancelled"; subject?: { accountId?: string; planId?: string; tenantId?: string; userId?: string; }; tags?: string[]; workflowId: string; workflowSnapshot: { edges: object[]; id: string; steps: object[]; title?: string; version: number; }; workflowVersion: number; }; trace: ({ correlationId?: string; id: string; runId: string; stepId: string; ts: string; type: "step_started"; } | { correlationId?: string; error?: { code?: string; message: string; }; id: string; ok: boolean; runId: string; stepId: string; ts: string; type: "step_completed"; } | { artifact: { artifactKey: string; createdAt: string; data?: unknown; pointer?: { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }; typeId: string; version: number; }; correlationId?: string; id: string; idempotencyKey?: string; runId: string; stepId?: string; ts: string; type: "artifact_written"; } | { artifactKey: string; correlationId?: string; fromVersion: number; id: string; idempotencyKey?: string; patch: ({ op: "add"; path: string; value?: unknown; } | { op: "remove"; path: string; } | { op: "replace"; path: string; value?: unknown; } | { from: string; op: "move"; path: string; } | { from: string; op: "copy"; path: string; } | { op: "test"; path: string; value?: unknown; })[]; runId: string; stepId?: string; toVersion: number; ts: string; type: "artifact_patch"; } | { correlationId?: string; cost?: { amount: number; currency: string; }; direction: "request" | "response" | "stream_chunk"; durationMs?: number; id: string; model?: string; payload?: unknown; provider?: string; runId: string; stepId?: string; summary?: string; ts: string; type: "model_io"; usage?: { cachedInputTokens?: number; inputTokens?: number; outputTokens?: number; reasoningTokens?: number; totalTokens?: number; }; } | { args?: unknown; correlationId?: string; id: string; name: string; result?: unknown; runId: string; stepId?: string; ts: string; type: "tool_call"; } | { correlationId?: string; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; reason?: string; runId: string; stepId: string; ts: string; type: "human_gate_requested"; } | { correlationId?: string; decision: "approved" | "rejected" | "edited"; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; note?: string; runId: string; stepId: string; ts: string; type: "human_gate_resolved"; } | { correlationId?: string; id: string; ruleSetId: string; runId: string; snapshot: { id: string; rules: object[]; ruleSchemaId: string; }; stepId?: string; ts: string; type: "rule_changed"; } | { correlationId?: string; id: string; policy: "AUTO" | "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; runId: string; stepId: string; ts: string; type: "policy_changed"; } | { code?: string; correlationId?: string; fatal?: boolean; id: string; message: string; runId: string; stepId?: string; ts: string; type: "error"; } | { correlationId?: string; forkedFromStepId?: string; id: string; parentRunId: string; parentRunIds?: string[]; runId: string; stepId?: string; ts: string; type: "run_forked"; } | { correlationId?: string; id: string; runId: string; stepId?: string; tags?: string[]; text: string; ts: string; type: "annotation"; } | { correlationId?: string; id: string; reason?: string; runId: string; status: "running" | "completed" | "failed" | "cancelled"; stepId?: string; ts: string; type: "run_status_changed"; } | { attributes?: Record<string, unknown>; correlationId?: string; id: string; kind?: "internal" | "client" | "server" | "producer" | "consumer"; name: string; parentSpanId?: string; runId: string; spanId: string; stepId?: string; ts: string; type: "span_started"; } | { attributes?: Record<string, unknown>; correlationId?: string; durationMs?: number; error?: { code?: string; message: string; }; id: string; runId: string; spanId: string; status?: "ok" | "error"; stepId?: string; ts: string; type: "span_ended"; })[]; }; verifyIntegrity?: boolean; }

#Returns

Promise<{ runId: string; }>

#importState()

importState(state): void

Defined in: packages/runtime/src/runtime/workbench.ts:240

#Parameters

#state

RunStoreState

#Returns

void

#listRuns()

listRuns(): string[]

Defined in: packages/runtime/src/runtime/workbench.ts:253

Stable iterator over run ids currently held by this runtime.

#Returns

string[]

#runChildrenOf()

runChildrenOf(parentRunId): string[]

Defined in: packages/runtime/src/runtime/workbench.ts:266

Returns ids of runs in this runtime whose RunContextRef records the given run as a parent (singular parentRunId or any entry in plural parentRunIds). Useful for agent-of-agents cancellation, debugging supervisor trees, and rendering child-of relationships in UIs.

Iteration order is insertion order (the same order as listRuns), making the result stable for a given runtime state.

#Parameters

#parentRunId

string

#Returns

string[]

#session()

session(runId): WorkbenchSession

Defined in: packages/runtime/src/runtime/workbench.ts:219

#Parameters

#runId

string

#Returns

WorkbenchSession

#setOnTraceListenerError()

setOnTraceListenerError(handler): void

Defined in: packages/runtime/src/runtime/workbench.ts:73

Replace the global trace listener error handler (e.g. wire to Sentry after app bootstrap). Pass undefined to fall back to the default console.error logging only.

#Parameters

#handler

TraceListenerErrorHandler | undefined

#Returns

void

#startRun()

startRun(input): object

Defined in: packages/runtime/src/runtime/workbench.ts:125

#Parameters

#input

StartRunInput

#Returns

object

#runId

runId: string

#subscribe()

subscribe(runId, listener): () => void

Defined in: packages/runtime/src/runtime/workbench.ts:77

#Parameters

#runId

string

#listener

Listener

#Returns

() => void

#WorkbenchSession

Defined in: packages/runtime/src/runtime/session.ts:34

#Accessors

#runId

#Get Signature

get runId(): string

Defined in: packages/runtime/src/runtime/session.ts:62

Identifies the run whose state this session manages.

#Returns

string

The immutable run identifier from the current store state.

#Methods

#annotate()

annotate(input): void

Defined in: packages/runtime/src/runtime/session.ts:424

Appends a free-form annotation and optional tags to the run trace.

#Parameters

#input

Annotation details.

#tags?

string[]

Optional classification tags for the annotation.

#text

string

Annotation text to record.

#Returns

void

#Throws

INVALID_STATE_TRANSITION if the run is not active.

#assertCanStartStep()

assertCanStartStep(stepId): void

Defined in: packages/runtime/src/runtime/session.ts:174

Verifies that workflow and gate state allow a step to start.

#Parameters

#stepId

string

Identifier of the step to validate.

#Returns

void

#Throws

INVALID_STATE_TRANSITION if dependencies, gates, or step state block the start.

#Throws

UNKNOWN_STEP if the workflow does not contain the step.

#beginSpan()

beginSpan(input): SpanHandle

Defined in: packages/runtime/src/runtime/session.ts:336

Starts a trace span and returns an idempotent handle that records its end.

#Parameters

#input

Span metadata.

#attributes?

Record<string, unknown>

Optional attributes recorded with the span start.

#correlationId?

string

Optional identifier linking related trace events.

#kind?

"internal" | "client" | "server" | "producer" | "consumer"

Optional OpenTelemetry-style span kind.

#name

string

Display name for the span.

#parentSpanId?

string

Optional parent span identifier for nesting.

#stepId?

string

Optional associated workflow step.

#Returns

SpanHandle

A handle whose end method appends one corresponding span-ended event.

#Throws

INVALID_STATE_TRANSITION if the run is not active.

#beginStep()

beginStep(stepId): { ok: false; reason: BlockReason; } | { ok: true; }

Defined in: packages/runtime/src/runtime/session.ts:186

Starts an eligible step and records a step_started trace event.

#Parameters

#stepId

string

Identifier of the step to start.

#Returns

{ ok: false; reason: BlockReason; } | { ok: true; }

A successful result after starting, or the blocking reason when the step cannot start yet.

#Throws

INVALID_STATE_TRANSITION if the run is not active.

#Throws

UNKNOWN_STEP if the workflow does not contain the step.

#cancelRun()

cancelRun(input?): void

Defined in: packages/runtime/src/runtime/session.ts:106

Marks an active run cancelled and records its terminal status in the trace.

#Parameters

#input?

Optional cancellation details.

#reason?

string

Human-readable reason for cancelling the run.

#Returns

void

#Throws

INVALID_STATE_TRANSITION if the run is not active or still has running steps.

#completeRun()

completeRun(input?): void

Defined in: packages/runtime/src/runtime/session.ts:83

Marks an active run completed and records its terminal status in the trace.

#Parameters

#input?

Optional completion details.

#reason?

string

Human-readable reason for completing the run.

#Returns

void

#Throws

INVALID_STATE_TRANSITION if the run is not active or still has running steps.

#completeStep()

completeStep(stepId): void

Defined in: packages/runtime/src/runtime/session.ts:197

Marks a running step complete, optionally requests its post-step review gate, and records completion.

#Parameters

#stepId

string

Identifier of the running step to complete.

#Returns

void

#Throws

INVALID_STATE_TRANSITION if the run is inactive or the step is not running.

#Throws

UNKNOWN_STEP if the workflow does not contain the step.

#exportRunBundle()

exportRunBundle(opts?): Promise<{ artifacts: object[]; engine?: { gateState: [string, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints: Record<string, "pending" | "approved">; }][]; idempotency: [string, { artifactKey: string; version: number; }][]; revision: number; stepStatus: [string, "pending" | "running" | "completed" | "failed"][]; }; integrity?: { sha256: string; }; protocolVersion: "1.0.0"; ruleSets: object[]; run: { annotations?: object[]; context?: { forkedFromStepId?: string; parentRunId?: string; parentRunIds?: string[]; pinnedArtifacts?: object[]; }; endedAt?: string; id: string; metadata?: Record<string, JsonValue>; startedAt: string; status: "running" | "completed" | "failed" | "cancelled"; subject?: { accountId?: string; planId?: string; tenantId?: string; userId?: string; }; tags?: string[]; workflowId: string; workflowSnapshot: { edges: object[]; id: string; steps: object[]; title?: string; version: number; }; workflowVersion: number; }; trace: ({ correlationId?: string; id: string; runId: string; stepId: string; ts: string; type: "step_started"; } | { correlationId?: string; error?: { code?: string; message: string; }; id: string; ok: boolean; runId: string; stepId: string; ts: string; type: "step_completed"; } | { artifact: { artifactKey: string; createdAt: string; data?: unknown; pointer?: { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }; typeId: string; version: number; }; correlationId?: string; id: string; idempotencyKey?: string; runId: string; stepId?: string; ts: string; type: "artifact_written"; } | { artifactKey: string; correlationId?: string; fromVersion: number; id: string; idempotencyKey?: string; patch: ({ op: "add"; path: string; value?: unknown; } | { op: "remove"; path: string; } | { op: "replace"; path: string; value?: unknown; } | { from: string; op: "move"; path: string; } | { from: string; op: "copy"; path: string; } | { op: "test"; path: string; value?: unknown; })[]; runId: string; stepId?: string; toVersion: number; ts: string; type: "artifact_patch"; } | { correlationId?: string; cost?: { amount: number; currency: string; }; direction: "request" | "response" | "stream_chunk"; durationMs?: number; id: string; model?: string; payload?: unknown; provider?: string; runId: string; stepId?: string; summary?: string; ts: string; type: "model_io"; usage?: { cachedInputTokens?: number; inputTokens?: number; outputTokens?: number; reasoningTokens?: number; totalTokens?: number; }; } | { args?: unknown; correlationId?: string; id: string; name: string; result?: unknown; runId: string; stepId?: string; ts: string; type: "tool_call"; } | { correlationId?: string; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; reason?: string; runId: string; stepId: string; ts: string; type: "human_gate_requested"; } | { correlationId?: string; decision: "approved" | "rejected" | "edited"; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; note?: string; runId: string; stepId: string; ts: string; type: "human_gate_resolved"; } | { correlationId?: string; id: string; ruleSetId: string; runId: string; snapshot: { id: string; rules: object[]; ruleSchemaId: string; }; stepId?: string; ts: string; type: "rule_changed"; } | { correlationId?: string; id: string; policy: "AUTO" | "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; runId: string; stepId: string; ts: string; type: "policy_changed"; } | { code?: string; correlationId?: string; fatal?: boolean; id: string; message: string; runId: string; stepId?: string; ts: string; type: "error"; } | { correlationId?: string; forkedFromStepId?: string; id: string; parentRunId: string; parentRunIds?: string[]; runId: string; stepId?: string; ts: string; type: "run_forked"; } | { correlationId?: string; id: string; runId: string; stepId?: string; tags?: string[]; text: string; ts: string; type: "annotation"; } | { correlationId?: string; id: string; reason?: string; runId: string; status: "running" | "completed" | "failed" | "cancelled"; stepId?: string; ts: string; type: "run_status_changed"; } | { attributes?: Record<string, unknown>; correlationId?: string; id: string; kind?: "internal" | "client" | "server" | "producer" | "consumer"; name: string; parentSpanId?: string; runId: string; spanId: string; stepId?: string; ts: string; type: "span_started"; } | { attributes?: Record<string, unknown>; correlationId?: string; durationMs?: number; error?: { code?: string; message: string; }; id: string; runId: string; spanId: string; status?: "ok" | "error"; stepId?: string; ts: string; type: "span_ended"; })[]; }>

Defined in: packages/runtime/src/runtime/session.ts:121

Builds a validated, integrity-protected export of the current run state.

#Parameters

#opts?

ExportRunBundleOptions

Export configuration.

#Returns

Promise<{ artifacts: object[]; engine?: { gateState: [string, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints: Record<string, "pending" | "approved">; }][]; idempotency: [string, { artifactKey: string; version: number; }][]; revision: number; stepStatus: [string, "pending" | "running" | "completed" | "failed"][]; }; integrity?: { sha256: string; }; protocolVersion: "1.0.0"; ruleSets: object[]; run: { annotations?: object[]; context?: { forkedFromStepId?: string; parentRunId?: string; parentRunIds?: string[]; pinnedArtifacts?: object[]; }; endedAt?: string; id: string; metadata?: Record<string, JsonValue>; startedAt: string; status: "running" | "completed" | "failed" | "cancelled"; subject?: { accountId?: string; planId?: string; tenantId?: string; userId?: string; }; tags?: string[]; workflowId: string; workflowSnapshot: { edges: object[]; id: string; steps: object[]; title?: string; version: number; }; workflowVersion: number; }; trace: ({ correlationId?: string; id: string; runId: string; stepId: string; ts: string; type: "step_started"; } | { correlationId?: string; error?: { code?: string; message: string; }; id: string; ok: boolean; runId: string; stepId: string; ts: string; type: "step_completed"; } | { artifact: { artifactKey: string; createdAt: string; data?: unknown; pointer?: { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }; typeId: string; version: number; }; correlationId?: string; id: string; idempotencyKey?: string; runId: string; stepId?: string; ts: string; type: "artifact_written"; } | { artifactKey: string; correlationId?: string; fromVersion: number; id: string; idempotencyKey?: string; patch: ({ op: "add"; path: string; value?: unknown; } | { op: "remove"; path: string; } | { op: "replace"; path: string; value?: unknown; } | { from: string; op: "move"; path: string; } | { from: string; op: "copy"; path: string; } | { op: "test"; path: string; value?: unknown; })[]; runId: string; stepId?: string; toVersion: number; ts: string; type: "artifact_patch"; } | { correlationId?: string; cost?: { amount: number; currency: string; }; direction: "request" | "response" | "stream_chunk"; durationMs?: number; id: string; model?: string; payload?: unknown; provider?: string; runId: string; stepId?: string; summary?: string; ts: string; type: "model_io"; usage?: { cachedInputTokens?: number; inputTokens?: number; outputTokens?: number; reasoningTokens?: number; totalTokens?: number; }; } | { args?: unknown; correlationId?: string; id: string; name: string; result?: unknown; runId: string; stepId?: string; ts: string; type: "tool_call"; } | { correlationId?: string; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; reason?: string; runId: string; stepId: string; ts: string; type: "human_gate_requested"; } | { correlationId?: string; decision: "approved" | "rejected" | "edited"; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; note?: string; runId: string; stepId: string; ts: string; type: "human_gate_resolved"; } | { correlationId?: string; id: string; ruleSetId: string; runId: string; snapshot: { id: string; rules: object[]; ruleSchemaId: string; }; stepId?: string; ts: string; type: "rule_changed"; } | { correlationId?: string; id: string; policy: "AUTO" | "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; runId: string; stepId: string; ts: string; type: "policy_changed"; } | { code?: string; correlationId?: string; fatal?: boolean; id: string; message: string; runId: string; stepId?: string; ts: string; type: "error"; } | { correlationId?: string; forkedFromStepId?: string; id: string; parentRunId: string; parentRunIds?: string[]; runId: string; stepId?: string; ts: string; type: "run_forked"; } | { correlationId?: string; id: string; runId: string; stepId?: string; tags?: string[]; text: string; ts: string; type: "annotation"; } | { correlationId?: string; id: string; reason?: string; runId: string; status: "running" | "completed" | "failed" | "cancelled"; stepId?: string; ts: string; type: "run_status_changed"; } | { attributes?: Record<string, unknown>; correlationId?: string; id: string; kind?: "internal" | "client" | "server" | "producer" | "consumer"; name: string; parentSpanId?: string; runId: string; spanId: string; stepId?: string; ts: string; type: "span_started"; } | { attributes?: Record<string, unknown>; correlationId?: string; durationMs?: number; error?: { code?: string; message: string; }; id: string; runId: string; spanId: string; status?: "ok" | "error"; stepId?: string; ts: string; type: "span_ended"; })[]; }>

The validated run bundle with an integrity attachment.

#Throws

INVALID_INPUT if a user export is requested without a registry.

#Throws

MISSING_WEBCRYPTO if the runtime cannot generate the bundle integrity hash.

#failRun()

failRun(error): void

Defined in: packages/runtime/src/runtime/session.ts:95

Marks an active run failed and records both its terminal status and fatal error.

#Parameters

#error

Failure details to record.

#code?

string

Optional application-specific failure code.

#message

string

Human-readable failure message.

#Returns

void

#Throws

INVALID_STATE_TRANSITION if the run is not active or still has running steps.

#failStep()

failStep(stepId, error, options?): void

Defined in: packages/runtime/src/runtime/session.ts:212

Marks a step failed, records the error, and can fail the entire run immediately.

#Parameters

#stepId

string

Identifier of the step to fail.

#error

Failure details to record.

#code?

string

Optional application-specific failure code.

#message

string

Human-readable failure message.

#options?

Failure behavior.

#failFast?

boolean

Whether to transition the run to failed after recording the step failure.

#Returns

void

#Throws

INVALID_STATE_TRANSITION if the run is inactive, the step is terminal, or fail-fast leaves running steps.

#forkNotice()

forkNotice(parentRunId, forkedFromStepId?): void

Defined in: packages/runtime/src/runtime/session.ts:435

Records that this run was forked from another run, optionally at a source step.

#Parameters

#parentRunId

string

Identifier of the source run.

#forkedFromStepId?

string

Optional source step at which the fork occurred.

#Returns

void

#Throws

INVALID_STATE_TRANSITION if the run is not active.

#logModelIO()

logModelIO(input): void

Defined in: packages/runtime/src/runtime/session.ts:307

Appends model request, response, or stream-chunk telemetry to the run trace.

#Parameters

#input

Model I/O telemetry.

#correlationId?

string

Optional identifier linking related trace events.

#cost?

{ amount: number; currency: string; }

Optional cost measurements.

#cost.amount

number = ...

#cost.currency

string = ...

#detail?

"summary" | "full"

Retains the payload only when set to full; defaults to summary.

#direction

"request" | "response" | "stream_chunk"

Whether this records a request, response, or stream chunk.

#durationMs?

number

Optional elapsed operation time in milliseconds.

#model?

string

Optional model identifier.

#payload?

unknown

Optional full request or response payload.

#provider?

string

Optional model-provider identifier.

#stepId?

string

Optional step associated with the model operation.

#summary?

string

Optional safe summary of the model I/O.

#usage?

{ cachedInputTokens?: number; inputTokens?: number; outputTokens?: number; reasoningTokens?: number; totalTokens?: number; }

Optional token or usage measurements.

#usage.cachedInputTokens?

number = ...

#usage.inputTokens?

number = ...

#usage.outputTokens?

number = ...

#usage.reasoningTokens?

number = ...

#usage.totalTokens?

number = ...

#Returns

void

#Throws

INVALID_STATE_TRANSITION if the run is not active.

#logToolCall()

logToolCall(input): void

Defined in: packages/runtime/src/runtime/session.ts:388

Appends a tool invocation, including optional arguments and result, to the run trace.

#Parameters

#input

Tool-call telemetry.

#args?

unknown

Optional arguments sent to the tool.

#correlationId?

string

Optional identifier linking related trace events.

#name

string

Non-empty name of the invoked tool.

#result?

unknown

Optional result returned by the tool.

#stepId?

string

Optional step associated with the tool call.

#Returns

void

#Throws

INVALID_STATE_TRANSITION if the run is not active.

#Throws

INVALID_INPUT if the tool name is empty.

#materializeArtifact()

materializeArtifact(artifactKey, opts?): Promise<unknown>

Defined in: packages/runtime/src/runtime/session.ts:268

Returns an artifact's inline payload or fetches, verifies, and parses its external payload.

#Parameters

#artifactKey

string

Key of the artifact to retrieve.

#opts?

Fetch options.

#signal?

AbortSignal

Abort signal passed to the external artifact store.

#Returns

Promise<unknown>

The inline value or JSON value loaded from external storage.

#Throws

UNKNOWN_ARTIFACT if the artifact key is absent.

#Throws

INVALID_STATE_TRANSITION if an external artifact has no configured store.

#Throws

INVALID_RUN_STATE if an external artifact has no storage reference.

#Throws

INTEGRITY_MISMATCH if fetched bytes do not match the stored payload hash.

#Throws

INVALID_JSON if fetched external bytes cannot be parsed as JSON.

#patchArtifact()

patchArtifact(input): object

Defined in: packages/runtime/src/runtime/session.ts:286

Applies an RFC 6902 patch to an existing inline artifact and records an artifact_patch event.

#Parameters

#input

Patch request and optional idempotency metadata.

#artifactKey

string

Key of the artifact to patch.

#idempotencyKey?

string

Optional key that makes a matching repeated patch return the existing version.

#patch

Operation[]

JSON Patch operations to apply to the artifact data.

#Returns

The new artifact version, or the original version for a matching idempotent patch.

#artifactKey

artifactKey: string

#createdAt

createdAt: string

#data?

optional data?: unknown

Inline snapshot for small artifacts; omit when using pointer

#pointer?

optional pointer?: object

#pointer.byteLength?

optional byteLength?: number

#pointer.kind

kind: "inline" | "external"

#pointer.payloadHash?

optional payloadHash?: string

SHA-256 (lowercase hex) of the canonical JSON encoding of the artifact payload. Preferred name for new pointers. When both payloadHash and sha256 are set, they MUST match.

#pointer.ref?

optional ref?: string

For inline: not used. For external: opaque storage key returned by ArtifactStore.put.

#pointer.sha256?

optional sha256?: string

#Deprecated

Prefer payloadHash. Kept as an alias so older bundles round-trip without migration. When both are set they MUST be equal.

#typeId

typeId: string

#version

version: number

#Throws

INVALID_STATE_TRANSITION if the run is not active.

#Throws

INVALID_INPUT if the artifact key is empty.

#Throws

IDEMPOTENCY_CONFLICT if the idempotency key belongs to another or stale artifact version.

#Throws

UNKNOWN_ARTIFACT if the artifact key is absent.

#Throws

PATCH_FAILED if a JSON Patch operation cannot be applied.

#reorderRules()

reorderRules(input): void

Defined in: packages/runtime/src/runtime/session.ts:412

Reprioritizes every rule in a rule set and records the resulting snapshot.

#Parameters

#input

Rule-order request.

#orderedRuleIds

string[]

Every rule identifier in the desired priority order.

#ruleSetId

string

Identifier of the existing rule set.

#Returns

void

#Throws

INVALID_STATE_TRANSITION if the run is not active.

#Throws

UNKNOWN_RULESET if the rule set does not exist.

#Throws

INVALID_INPUT if identifiers are duplicated, incomplete, or unknown to the rule set.

#replaceRuleSet()

replaceRuleSet(ruleSet): void

Defined in: packages/runtime/src/runtime/session.ts:398

Replaces a rule set and records its full replacement snapshot in the run trace.

#Parameters

#ruleSet

Complete rule set to store under its identifier.

#id

string = ...

#rules

object[] = ...

#ruleSchemaId

string = ...

Registry key for JSON Schema used to validate each rule payload

#Returns

void

#Throws

INVALID_STATE_TRANSITION if the run is not active.

#requestGate()

requestGate(input): void

Defined in: packages/runtime/src/runtime/session.ts:134

Records a human-review gate request for a step without changing its gate state.

#Parameters

#input

Gate request details.

#gate

"PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"

Gate phase to request.

#reason?

string

Optional explanation shown to the reviewer.

#stepId

string

Identifier of the step awaiting review.

#Returns

void

#Throws

INVALID_STATE_TRANSITION if the run is not active.

#resolveCheckpoint()

resolveCheckpoint(input): void

Defined in: packages/runtime/src/runtime/session.ts:163

Records a checkpoint decision and updates that checkpoint's approval state for a step.

#Parameters

#input

Checkpoint-resolution details.

#checkpointId

string

Identifier of the checkpoint to resolve.

#decision

"approved" | "rejected"

Whether the checkpoint was approved or rejected.

#stepId

string

Identifier of the step containing the checkpoint.

#Returns

void

#Throws

INVALID_STATE_TRANSITION if the run is not active.

#Throws

UNKNOWN_STEP if the step has no gate state.

#resolveGate()

resolveGate(input): void

Defined in: packages/runtime/src/runtime/session.ts:149

Records a reviewer decision and updates the matching pause or checkpoint gate state.

#Parameters

#input

Gate-resolution details.

#decision

"approved" | "rejected" | "edited"

Whether the reviewer approved, rejected, or edited the gate.

#gate

"PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"

Gate phase being resolved.

#note?

string

Optional reviewer note to attach to the trace event.

#stepId

string

Identifier of the step with the requested gate.

#Returns

void

#Throws

INVALID_STATE_TRANSITION if the run is not active.

#Throws

UNKNOWN_STEP if the step has no gate state.

#snapshot()

snapshot(): RunStoreState

Defined in: packages/runtime/src/runtime/session.ts:72

Returns an isolated copy of the complete mutable run store state.

#Returns

RunStoreState

A deep clone suitable for inspection without changing the session.

#Throws

INVALID_RUN_STATE if the underlying state cannot be deep-cloned.

#span()

span<T>(name, fn, opts?): Promise<T>

Defined in: packages/runtime/src/runtime/session.ts:362

Runs a function inside a trace span, automatically recording an ended span with success or error status.

#Type Parameters

#T

T

#Parameters

#name

string

Display name for the span.

#fn

(handle) => T | Promise<T>

Synchronous or asynchronous work that receives the span handle.

#opts?

Optional span metadata.

#attributes?

Record<string, unknown>

Optional attributes recorded with the span start.

#correlationId?

string

Optional identifier linking related trace events.

#kind?

"internal" | "client" | "server" | "producer" | "consumer"

Optional OpenTelemetry-style span kind.

#parentSpanId?

string

Optional parent span identifier for nesting.

#stepId?

string

Optional associated workflow step.

#Returns

Promise<T>

A promise for the callback's result.

#Throws

INVALID_STATE_TRANSITION if the run is not active before the span begins.

#Throws

Re-throws any error raised by fn after recording it on the span.

#writeArtifact()

writeArtifact(input): object

Defined in: packages/runtime/src/runtime/session.ts:230

Stores an inline artifact version and records an artifact_written trace event.

#Parameters

#input

Artifact contents and optional idempotency metadata.

#artifactKey

string

Stable key identifying the artifact.

#data

unknown

Inline payload to store.

#idempotencyKey?

string

Optional key that makes a matching repeated write return the existing version.

#pointer?

{ byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }

Optional pointer metadata to associate with the artifact.

#pointer.byteLength?

number = ...

#pointer.kind

"inline" | "external" = ...

#pointer.payloadHash?

string = ...

SHA-256 (lowercase hex) of the canonical JSON encoding of the artifact payload. Preferred name for new pointers. When both payloadHash and sha256 are set, they MUST match.

#pointer.ref?

string = ...

For inline: not used. For external: opaque storage key returned by ArtifactStore.put.

#pointer.sha256?

string = ...

Deprecated

Prefer payloadHash. Kept as an alias so older bundles round-trip without migration. When both are set they MUST be equal.

#typeId

string

Application-defined type identifier for the artifact data.

#Returns

The new artifact version, or the original version for a matching idempotent write.

#artifactKey

artifactKey: string

#createdAt

createdAt: string

#data?

optional data?: unknown

Inline snapshot for small artifacts; omit when using pointer

#pointer?

optional pointer?: object

#pointer.byteLength?

optional byteLength?: number

#pointer.kind

kind: "inline" | "external"

#pointer.payloadHash?

optional payloadHash?: string

SHA-256 (lowercase hex) of the canonical JSON encoding of the artifact payload. Preferred name for new pointers. When both payloadHash and sha256 are set, they MUST match.

#pointer.ref?

optional ref?: string

For inline: not used. For external: opaque storage key returned by ArtifactStore.put.

#pointer.sha256?

optional sha256?: string

#Deprecated

Prefer payloadHash. Kept as an alias so older bundles round-trip without migration. When both are set they MUST be equal.

#typeId

typeId: string

#version

version: number

#Throws

INVALID_STATE_TRANSITION if the run is not active.

#Throws

INVALID_INPUT if the artifact key or type identifier is empty.

#Throws

IDEMPOTENCY_CONFLICT if the idempotency key belongs to another or stale artifact version.

#writeArtifactAsync()

writeArtifactAsync(input): Promise<{ artifactKey: string; createdAt: string; data?: unknown; pointer?: { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }; typeId: string; version: number; }>

Defined in: packages/runtime/src/runtime/session.ts:251

Stores an artifact inline or externally, attaches payload metadata, and records an artifact_written event.

#Parameters

#input

Artifact contents, storage routing, and optional idempotency metadata.

#artifactKey

string

Stable key identifying the artifact.

#contentType?

string

Optional media type supplied to an external artifact store.

#data

unknown

Payload to encode and store.

#idempotencyKey?

string

Optional key that makes a matching repeated write return the existing version.

#routing?

"inline" | "external" | "auto"

Selects automatic, inline, or external storage routing.

#typeId

string

Application-defined type identifier for the artifact data.

#Returns

Promise<{ artifactKey: string; createdAt: string; data?: unknown; pointer?: { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }; typeId: string; version: number; }>

The new artifact version, or the original version for a matching idempotent write.

#Throws

INVALID_STATE_TRANSITION if the run is not active.

#Throws

INVALID_INPUT if identifiers are empty, data cannot be encoded, or external routing has no configured artifact store.

#Throws

IDEMPOTENCY_CONFLICT if the idempotency key belongs to another or stale artifact version.

#Throws

INTEGRITY_MISMATCH if an external store reports a different payload hash.

#Throws

MISSING_WEBCRYPTO if the runtime cannot hash the artifact payload.

#Interfaces

#ArtifactStore

Defined in: packages/runtime/src/persistence/artifactStore.ts:55

External byte store for artifact payloads. Optional dependency of WorkbenchRuntime and RunRepository. Implementations are expected to:

  • return a ref from put that the runtime can later pass to get
  • persist payload bytes verbatim so the precomputed payloadHash still

matches when the bytes are read back

  • tolerate concurrent writes for the same (runId, artifactKey, version)

either by being idempotent or by serializing through the host

The runtime itself never calls delete automatically; that is left to the host's retention / GC policy. A reference MemoryArtifactStore is provided for tests and local development; production hosts should plug in S3 / Vercel Blob / Supabase Storage / R2 / etc.

#Methods

#delete()

delete(input, opts?): Promise<void>

Defined in: packages/runtime/src/persistence/artifactStore.ts:58

#Parameters

#input

#ref

string

#runId

string

#opts?

#signal?

AbortSignal

#Returns

Promise<void>

#get()

get(input, opts?): Promise<ArtifactStoreGetResult>

Defined in: packages/runtime/src/persistence/artifactStore.ts:57

#Parameters

#input

#ref

string

#runId

string

#opts?

#signal?

AbortSignal

#Returns

Promise<ArtifactStoreGetResult>

#put()

put(input, opts?): Promise<ArtifactStorePutResult>

Defined in: packages/runtime/src/persistence/artifactStore.ts:56

#Parameters

#input

ArtifactStorePutInput

#opts?

#signal?

AbortSignal

#Returns

Promise<ArtifactStorePutResult>

#RunRepository

Defined in: packages/runtime/src/persistence/types.ts:20

Persistence port. Authentication/authorization is always the host app's responsibility (attach cookies, bearer tokens, signed URLs, etc. in HttpRunRepository options).

The optional signal argument lets callers cancel in-flight operations (e.g. on component unmount). Implementations that cannot cancel should still accept the option and ignore it.

#Methods

#delete()

delete(runId, opts?): Promise<void>

Defined in: packages/runtime/src/persistence/types.ts:24

#Parameters

#runId

string

#opts?

#signal?

AbortSignal

#Returns

Promise<void>

#list()

list(opts?): Promise<SavedRunMeta[]>

Defined in: packages/runtime/src/persistence/types.ts:23

#Parameters

#opts?

#limit?

number

#signal?

AbortSignal

#Returns

Promise<SavedRunMeta[]>

#load()

load(runId, opts?): Promise<RunStoreState | null>

Defined in: packages/runtime/src/persistence/types.ts:22

#Parameters

#runId

string

#opts?

#signal?

AbortSignal

#Returns

Promise<RunStoreState | null>

#save()

save(state, opts?): Promise<void>

Defined in: packages/runtime/src/persistence/types.ts:21

#Parameters

#state

RunStoreState

#opts?

#signal?

AbortSignal

#Returns

Promise<void>

#Type Aliases

#ArtifactPointer

ArtifactPointer = z.infer<*typeof* ArtifactPointerSchema>

Defined in: packages/runtime/src/protocol/artifacts.ts:58

#ArtifactStoreGetResult

ArtifactStoreGetResult = object

Defined in: packages/runtime/src/persistence/artifactStore.ts:34

#Properties

#contentType?

optional contentType?: string

Defined in: packages/runtime/src/persistence/artifactStore.ts:37

#payload

payload: Uint8Array

Defined in: packages/runtime/src/persistence/artifactStore.ts:35

#payloadHash

payloadHash: string

Defined in: packages/runtime/src/persistence/artifactStore.ts:36

#ArtifactStorePutInput

ArtifactStorePutInput = object

Defined in: packages/runtime/src/persistence/artifactStore.ts:15

#Properties

#artifactKey

artifactKey: string

Defined in: packages/runtime/src/persistence/artifactStore.ts:17

#contentType?

optional contentType?: string

Defined in: packages/runtime/src/persistence/artifactStore.ts:23

#payload

payload: Uint8Array

Defined in: packages/runtime/src/persistence/artifactStore.ts:20

Canonical-JSON encoded payload bytes.

#payloadHash

payloadHash: string

Defined in: packages/runtime/src/persistence/artifactStore.ts:22

Lowercase-hex SHA-256 of payload precomputed by the runtime.

#runId

runId: string

Defined in: packages/runtime/src/persistence/artifactStore.ts:16

#version

version: number

Defined in: packages/runtime/src/persistence/artifactStore.ts:18

#ArtifactStorePutResult

ArtifactStorePutResult = object

Defined in: packages/runtime/src/persistence/artifactStore.ts:26

#Properties

#byteLength

byteLength: number

Defined in: packages/runtime/src/persistence/artifactStore.ts:31

#payloadHash

payloadHash: string

Defined in: packages/runtime/src/persistence/artifactStore.ts:30

Mirror of input payloadHash so the host can verify the store accepted what it claimed.

#ref

ref: string

Defined in: packages/runtime/src/persistence/artifactStore.ts:28

Opaque storage key the store returns; persisted on ArtifactPointer.ref.

#ArtifactVersion

ArtifactVersion = z.infer<*typeof* ArtifactVersionSchema>

Defined in: packages/runtime/src/protocol/artifacts.ts:80

#BlockReason

BlockReason = { gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; stepId: string; type: "gate"; } | { stepId: string; type: "predecessor"; waitingOn: string[]; } | { stepId: string; type: "predecessor_after_gate"; waitingOn: string; } | { status: StepRuntimeStatus; stepId: string; type: "not_pending"; }

Defined in: packages/runtime/src/runtime/types.ts:38

#ExportRunBundleOptions

ExportRunBundleOptions = object

Defined in: packages/runtime/src/runtime/session.ts:26

#Properties

#includeEngine?

optional includeEngine?: boolean

Defined in: packages/runtime/src/runtime/session.ts:29

#profile?

optional profile?: "full" | "user"

Defined in: packages/runtime/src/runtime/session.ts:27

#registry?

optional registry?: SchemaRegistry

Defined in: packages/runtime/src/runtime/session.ts:28

#HttpRetryOptions

HttpRetryOptions = object

Defined in: packages/runtime/src/persistence/http.ts:6

#Properties

#baseDelayMs?

optional baseDelayMs?: number

Defined in: packages/runtime/src/persistence/http.ts:10

Base delay in ms between retries (exponential backoff: base * 2^attempt). Default: 250.

#maxAttempts?

optional maxAttempts?: number

Defined in: packages/runtime/src/persistence/http.ts:8

Maximum total attempts including the first try. Default: 3. Set to 1 to disable retries.

#maxDelayMs?

optional maxDelayMs?: number

Defined in: packages/runtime/src/persistence/http.ts:12

Cap on backoff delay in ms. Default: 4_000.

#HttpRunRepositoryOptions

HttpRunRepositoryOptions = object

Defined in: packages/runtime/src/persistence/http.ts:15

#Properties

#baseUrl

baseUrl: string

Defined in: packages/runtime/src/persistence/http.ts:16

#fetchImpl?

optional fetchImpl?: typeof fetch

Defined in: packages/runtime/src/persistence/http.ts:22

#getHeaders?

optional getHeaders?: () => Record<string, string> | Promise<Record<string, string>>

Defined in: packages/runtime/src/persistence/http.ts:21

Return headers for each request. Use this to attach Authorization, cookies via credentials, or signed headers. The workbench runtime does not interpret these values.

#Returns

Record<string, string> | Promise<Record<string, string>>

#retry?

optional retry?: HttpRetryOptions

Defined in: packages/runtime/src/persistence/http.ts:26

Retry config for transient failures (network errors, 5xx, 429). Disable with { maxAttempts: 1 }.

#sleep?

optional sleep?: (ms) => Promise<void>

Defined in: packages/runtime/src/persistence/http.ts:28

Sleeper hook. Useful for tests; defaults to setTimeout-based delay.

#Parameters

#ms

number

#Returns

Promise<void>

#timeoutMs?

optional timeoutMs?: number

Defined in: packages/runtime/src/persistence/http.ts:24

Per-request timeout in milliseconds. 0 or undefined disables the timeout.

#JsonPatchOp

JsonPatchOp = z.infer<*typeof* JsonPatchOpSchema>

Defined in: packages/runtime/src/protocol/trace.ts:20

#JsonSchema

JsonSchema = Record<string, unknown>

Defined in: packages/runtime/src/schema/registry.ts:10

#JsonValue

JsonValue = null | boolean | number | string | JsonValue[] | {[key: string]: JsonValue; }

Defined in: packages/runtime/src/protocol/run.ts:9

#Listener

Listener = (event) => void

Defined in: packages/runtime/src/runtime/types.ts:36

#Parameters

#event

TraceEvent

#Returns

void

#ModelCost

ModelCost = z.infer<*typeof* ModelCostSchema>

Defined in: packages/runtime/src/protocol/trace.ts:64

#ModelTelemetryBucket

ModelTelemetryBucket = z.infer<*typeof* ModelTelemetryBucketSchema>

Defined in: packages/runtime/src/telemetry/modelTelemetry.ts:53

#ModelTelemetryDirection

ModelTelemetryDirection = z.infer<*typeof* ModelTelemetryDirectionSchema>

Defined in: packages/runtime/src/telemetry/modelTelemetry.ts:9

#ModelTelemetryEntry

ModelTelemetryEntry = z.infer<*typeof* ModelTelemetryEntrySchema>

Defined in: packages/runtime/src/telemetry/modelTelemetry.ts:43

#ModelTelemetryOptions

ModelTelemetryOptions = object

Defined in: packages/runtime/src/telemetry/modelTelemetry.ts:78

#Properties

#directions?

optional directions?: readonly ModelTelemetryDirection[]

Defined in: packages/runtime/src/telemetry/modelTelemetry.ts:84

Defaults to response events so request+response pairs do not double-count token usage. Include stream_chunk when your provider reports final usage on a terminal stream chunk.

#now?

optional now?: () => string

Defined in: packages/runtime/src/telemetry/modelTelemetry.ts:86

Test hook for deterministic reports.

#Returns

string

#ModelTelemetrySource

ModelTelemetrySource = Pick<RunBundle, "run" | "trace"> | Pick<RunStoreState, "run" | "trace"> | { run: RunInstance; trace: TraceEvent[]; }

Defined in: packages/runtime/src/telemetry/modelTelemetry.ts:73

#ModelTelemetrySummary

ModelTelemetrySummary = z.infer<*typeof* ModelTelemetrySummarySchema>

Defined in: packages/runtime/src/telemetry/modelTelemetry.ts:71

#ModelTelemetryTotals

ModelTelemetryTotals = z.infer<*typeof* ModelTelemetryTotalsSchema>

Defined in: packages/runtime/src/telemetry/modelTelemetry.ts:24

#ModelUsage

ModelUsage = z.infer<*typeof* ModelUsageSchema>

Defined in: packages/runtime/src/protocol/trace.ts:40

#OtelGenAiSpan

OtelGenAiSpan = object

Defined in: packages/runtime/src/telemetry/otel.ts:12

Minimal OTLP-shaped span record with OpenTelemetry GenAI semantic conventions applied. We deliberately don't depend on @opentelemetry/api so this module stays usable in any host (server, edge, browser) — emit these objects from an exporter of your choice.

Fields follow https://opentelemetry.io/docs/specs/semconv/gen-ai/ and the OTLP/JSON Span shape (subset).

#Properties

#attributes

attributes: Record<string, string | number | boolean>

Defined in: packages/runtime/src/telemetry/otel.ts:26

Flattened attributes including OTel GenAI semantic-conv keys.

#durationMs?

optional durationMs?: number

Defined in: packages/runtime/src/telemetry/otel.ts:22

Milliseconds.

#endTimeIso

endTimeIso: string

Defined in: packages/runtime/src/telemetry/otel.ts:20

ISO-8601 timestamp of span end. May equal start if no span_ended was seen.

#events

events: object[]

Defined in: packages/runtime/src/telemetry/otel.ts:27

#attributes?

optional attributes?: Record<string, string | number | boolean>

#name

name: string

#timeIso

timeIso: string

#kind

kind: "internal" | "client" | "server" | "producer" | "consumer"

Defined in: packages/runtime/src/telemetry/otel.ts:24

#name

name: string

Defined in: packages/runtime/src/telemetry/otel.ts:16

#parentSpanId?

optional parentSpanId?: string

Defined in: packages/runtime/src/telemetry/otel.ts:15

#spanId

spanId: string

Defined in: packages/runtime/src/telemetry/otel.ts:14

#startTimeIso

startTimeIso: string

Defined in: packages/runtime/src/telemetry/otel.ts:18

ISO-8601 timestamp of span start.

#status

status: "ok" | "error" | "unset"

Defined in: packages/runtime/src/telemetry/otel.ts:23

#traceId

traceId: string

Defined in: packages/runtime/src/telemetry/otel.ts:13

#ParseRunBundleOptions

ParseRunBundleOptions = object

Defined in: packages/runtime/src/protocol/bundle.ts:113

#Properties

#migrate?

optional migrate?: boolean

Defined in: packages/runtime/src/protocol/bundle.ts:120

When true (the default), bundles whose protocolVersion differs from the current one are passed through registered RunBundleMigrations before validation. Set to false for strict imports that must already be on the current version.

#ProtocolVersion

ProtocolVersion = typeof WORKBENCH_PROTOCOL_VERSION

Defined in: packages/runtime/src/protocol/version.ts:3

#RedactionPath

RedactionPath = object

Defined in: packages/runtime/src/schema/redact.ts:1

#Properties

#path

path: string

Defined in: packages/runtime/src/schema/redact.ts:1

#replacement?

optional replacement?: unknown

Defined in: packages/runtime/src/schema/redact.ts:1

#RegisterArtifactTypeInput

RegisterArtifactTypeInput = object

Defined in: packages/runtime/src/schema/registry.ts:26

#Properties

#exportRedactPaths?

optional exportRedactPaths?: string[]

Defined in: packages/runtime/src/schema/registry.ts:30

#id

id: string

Defined in: packages/runtime/src/schema/registry.ts:27

#schema

schema: JsonSchema

Defined in: packages/runtime/src/schema/registry.ts:28

#validate?

optional validate?: ValidateFunction<unknown>

Defined in: packages/runtime/src/schema/registry.ts:29

#RegisteredArtifactType

RegisteredArtifactType = object

Defined in: packages/runtime/src/schema/registry.ts:12

#Properties

#exportRedactPaths

exportRedactPaths: string[]

Defined in: packages/runtime/src/schema/registry.ts:17

JSON Pointer paths (RFC 6901) redacted in profile: "user" exports.

#id

id: string

Defined in: packages/runtime/src/schema/registry.ts:13

#schema

schema: JsonSchema

Defined in: packages/runtime/src/schema/registry.ts:14

#validate

validate: ValidateFunction<unknown>

Defined in: packages/runtime/src/schema/registry.ts:15

#RegisteredRuleSchema

RegisteredRuleSchema = object

Defined in: packages/runtime/src/schema/registry.ts:20

#Properties

#id

id: string

Defined in: packages/runtime/src/schema/registry.ts:21

#schema

schema: JsonSchema

Defined in: packages/runtime/src/schema/registry.ts:22

#validate

validate: ValidateFunction<unknown>

Defined in: packages/runtime/src/schema/registry.ts:23

#RegisterRulePayloadSchemaInput

RegisterRulePayloadSchemaInput = object

Defined in: packages/runtime/src/schema/registry.ts:33

#Properties

#id

id: string

Defined in: packages/runtime/src/schema/registry.ts:34

#schema

schema: JsonSchema

Defined in: packages/runtime/src/schema/registry.ts:35

#validate?

optional validate?: ValidateFunction<unknown>

Defined in: packages/runtime/src/schema/registry.ts:36

#RuleRecord

RuleRecord = z.infer<*typeof* RuleRecordSchema>

Defined in: packages/runtime/src/protocol/rules.ts:12

#RuleSet

RuleSet = z.infer<*typeof* RuleSetSchema>

Defined in: packages/runtime/src/protocol/rules.ts:21

#RunBundle

RunBundle = z.infer<*typeof* RunBundleSchema>

Defined in: packages/runtime/src/protocol/run.ts:147

#RunBundleEngine

RunBundleEngine = z.infer<*typeof* RunBundleEngineSchema>

Defined in: packages/runtime/src/protocol/engine.ts:22

#RunBundleMigration

RunBundleMigration = object

Defined in: packages/runtime/src/protocol/migrate.ts:15

A migration upgrades a run bundle from one protocol version to the next.

Migrations operate on raw unknown JSON because the previous-version Zod schema may differ from the current one. They must: 1. Verify they are looking at the version they claim to handle. 2. Return a value that parses cleanly under the next version's schema. 3. Be pure: no I/O, no Date.now, no global state.

#Properties

#from

from: string

Defined in: packages/runtime/src/protocol/migrate.ts:16

#to

to: string

Defined in: packages/runtime/src/protocol/migrate.ts:17

#Methods

#migrate()

migrate(input): unknown

Defined in: packages/runtime/src/protocol/migrate.ts:18

#Parameters

#input

unknown

#Returns

unknown

#RunContextRef

RunContextRef = z.infer<*typeof* RunContextRefSchema>

Defined in: packages/runtime/src/protocol/run.ts:79

#RunInstance

RunInstance = z.infer<*typeof* RunInstanceSchema>

Defined in: packages/runtime/src/protocol/run.ts:129

#RunStoreState

RunStoreState = object

Defined in: packages/runtime/src/runtime/types.ts:10

#Properties

#artifactsByKey

artifactsByKey: Map<string, ArtifactVersion>

Defined in: packages/runtime/src/runtime/types.ts:15

#gateState

gateState: Map<string, StepGateState>

Defined in: packages/runtime/src/runtime/types.ts:18

#idempotency

idempotency: Map<string, { artifactKey: string; version: number; }>

Defined in: packages/runtime/src/runtime/types.ts:19

#revision

revision: number

Defined in: packages/runtime/src/runtime/types.ts:12

Monotonic counter bumped on every trace append (for external store subscriptions).

#ruleSetsById

ruleSetsById: Map<string, RuleSet>

Defined in: packages/runtime/src/runtime/types.ts:16

#run

run: RunInstance

Defined in: packages/runtime/src/runtime/types.ts:13

#stepStatus

stepStatus: Map<string, StepRuntimeStatus>

Defined in: packages/runtime/src/runtime/types.ts:17

#trace

trace: TraceEvent[]

Defined in: packages/runtime/src/runtime/types.ts:14

#RunSubjectRef

RunSubjectRef = z.infer<*typeof* RunSubjectRefSchema>

Defined in: packages/runtime/src/protocol/run.ts:101

#RunTerminalStatus

RunTerminalStatus = "completed" | "failed" | "cancelled"

Defined in: packages/runtime/src/runtime/session.ts:32

#SavedRunMeta

SavedRunMeta = object

Defined in: packages/runtime/src/persistence/types.ts:3

#Properties

#endedAt?

optional endedAt?: string

Defined in: packages/runtime/src/persistence/types.ts:7

#id

id: string

Defined in: packages/runtime/src/persistence/types.ts:4

#startedAt

startedAt: string

Defined in: packages/runtime/src/persistence/types.ts:6

#status

status: string

Defined in: packages/runtime/src/persistence/types.ts:8

#tags?

optional tags?: string[]

Defined in: packages/runtime/src/persistence/types.ts:9

#workflowId

workflowId: string

Defined in: packages/runtime/src/persistence/types.ts:5

#SpanHandle

SpanHandle = object

Defined in: packages/runtime/src/runtime/session.ts:17

#Properties

#spanId

readonly spanId: string

Defined in: packages/runtime/src/runtime/session.ts:18

#Methods

#end()

end(opts?): void

Defined in: packages/runtime/src/runtime/session.ts:19

#Parameters

#opts?

#attributes?

Record<string, unknown>

#error?

{ code?: string; message: string; }

#error.code?

string

#error.message

string

#status?

"ok" | "error"

#Returns

void

#StartRunInput

StartRunInput = object

Defined in: packages/runtime/src/runtime/types.ts:22

#Properties

#context?

optional context?: RunContextRef

Defined in: packages/runtime/src/runtime/types.ts:28

#initialArtifacts?

optional initialArtifacts?: object[]

Defined in: packages/runtime/src/runtime/types.ts:27

Initial artifacts (version 1)

#artifact

artifact: Omit<ArtifactVersion, "version" | "createdAt">

#metadata?

optional metadata?: Record<string, JsonValue>

Defined in: packages/runtime/src/runtime/types.ts:32

JSON-only host metadata kept with the run snapshot. Avoid secrets.

#ruleSets?

optional ruleSets?: RuleSet[]

Defined in: packages/runtime/src/runtime/types.ts:25

Initial rule sets keyed by id

#subject?

optional subject?: RunSubjectRef

Defined in: packages/runtime/src/runtime/types.ts:30

Host-provided subject/account attribution for telemetry, quotas, and billing.

#tags?

optional tags?: string[]

Defined in: packages/runtime/src/runtime/types.ts:33

#workflow

workflow: WorkflowSpec

Defined in: packages/runtime/src/runtime/types.ts:23

#StepGatePolicy

StepGatePolicy = z.infer<*typeof* StepGatePolicySchema>

Defined in: packages/runtime/src/protocol/workflow.ts:10

#StepId

StepId = string

Defined in: packages/runtime/src/runtime/graph.ts:3

#StepRuntimeStatus

StepRuntimeStatus = "pending" | "running" | "completed" | "failed"

Defined in: packages/runtime/src/runtime/types.ts:8

#TraceEvent

TraceEvent = z.infer<*typeof* TraceEventSchema>

Defined in: packages/runtime/src/protocol/trace.ts:190

#TraceListenerErrorContext

TraceListenerErrorContext = object

Defined in: packages/runtime/src/runtime/workbench.ts:25

#Properties

#event

event: TraceEvent

Defined in: packages/runtime/src/runtime/workbench.ts:27

#runId

runId: string

Defined in: packages/runtime/src/runtime/workbench.ts:26

#TraceListenerErrorHandler

TraceListenerErrorHandler = (error, ctx) => void

Defined in: packages/runtime/src/runtime/workbench.ts:31

Called when a trace subscriber throws. Should not rethrow; errors from the hook are logged to console.error.

#Parameters

#error

unknown

#ctx

TraceListenerErrorContext

#Returns

void

#WorkbenchErrorCode

WorkbenchErrorCode = "INVALID_JSON" | "INVALID_RUN_BUNDLE" | "INVALID_RUN_STATE" | "INVALID_TRACE_EVENT" | "INTEGRITY_MISMATCH" | "MISSING_INTEGRITY" | "UNKNOWN_RUN" | "UNKNOWN_STEP" | "UNKNOWN_ARTIFACT" | "UNKNOWN_RULESET" | "INVALID_WORKFLOW" | "INVALID_INPUT" | "INVALID_STATE_TRANSITION" | "IDEMPOTENCY_CONFLICT" | "PATCH_FAILED" | "MISSING_WEBCRYPTO" | "RUN_ID_COLLISION" | "HTTP_ERROR" | "HTTP_INVALID_JSON" | "HTTP_TIMEOUT" | "HTTP_ABORTED" | "STORAGE_UNAVAILABLE" | "UNSUPPORTED_PROTOCOL_VERSION"

Defined in: packages/runtime/src/errors.ts:3

#WorkbenchErrorJson

WorkbenchErrorJson = object

Defined in: packages/runtime/src/errors.ts:28

#Properties

#code

code: WorkbenchErrorCode

Defined in: packages/runtime/src/errors.ts:30

#message

message: string

Defined in: packages/runtime/src/errors.ts:31

#name

name: "WorkbenchError"

Defined in: packages/runtime/src/errors.ts:29

#WorkbenchRuntimeOptions

WorkbenchRuntimeOptions = object

Defined in: packages/runtime/src/runtime/workbench.ts:33

#Properties

#artifactExternalizationThresholdBytes?

optional artifactExternalizationThresholdBytes?: number

Defined in: packages/runtime/src/runtime/workbench.ts:47

Threshold in bytes for externalizing artifact payloads via artifactStore. Defaults to DEFAULT_ARTIFACT_EXTERNALIZATION_THRESHOLD_BYTES. Has no effect unless artifactStore is also configured.

#artifactStore?

optional artifactStore?: ArtifactStore

Defined in: packages/runtime/src/runtime/workbench.ts:41

Optional external byte store for large artifact payloads. When set, WorkbenchSession.writeArtifactAsync will externalize payloads whose encoded byte length is >= artifactExternalizationThresholdBytes. When omitted, every payload stays inline regardless of size.

#onTraceListenerError?

optional onTraceListenerError?: TraceListenerErrorHandler

Defined in: packages/runtime/src/runtime/workbench.ts:34

#WorkflowEdge

WorkflowEdge = z.infer<*typeof* WorkflowEdgeSchema>

Defined in: packages/runtime/src/protocol/workflow.ts:18

#WorkflowSpec

WorkflowSpec = z.infer<*typeof* WorkflowSpecSchema>

Defined in: packages/runtime/src/protocol/workflow.ts:41

#WorkflowStep

WorkflowStep = z.infer<*typeof* WorkflowStepSchema>

Defined in: packages/runtime/src/protocol/workflow.ts:31

#Variables

#ArtifactPointerSchema

const ArtifactPointerSchema: ZodEffects<ZodObject<{ byteLength: ZodOptional<ZodNumber>; kind: ZodEnum<["inline", "external"]>; payloadHash: ZodOptional<ZodString>; ref: ZodOptional<ZodString>; sha256: ZodOptional<ZodString>; }, "strip", ZodTypeAny, { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }, { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }>, { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }, { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }>

Defined in: packages/runtime/src/protocol/artifacts.ts:22

Pointer to artifact bytes. The same shape covers small inline artifacts and large externally-stored artifacts:

  • kind: "inline" — bytes live on ArtifactVersion.data. payloadHash

and byteLength, if set, MUST describe the canonical JSON encoding of that data so they can be verified after replay or redaction.

  • kind: "external" — bytes are stored by an ArtifactStore

implementation (S3/Blob/Postgres-large-object/etc.). ref is the opaque storage key returned by ArtifactStore.put. payloadHash and byteLength describe the bytes that the store will return on get, not any wrapper or envelope, so integrity can be verified end-to-end without trusting the store.

payloadHash is preferred over the legacy sha256 field. When both are set they MUST be equal (lowercase hex). New code should write payloadHash; reading code should prefer the helper getArtifactPayloadHash.

#ArtifactVersionSchema

const ArtifactVersionSchema: ZodObject<{ artifactKey: ZodString; createdAt: ZodString; data: ZodOptional<ZodUnknown>; pointer: ZodOptional<ZodEffects<ZodObject<{ byteLength: ZodOptional<ZodNumber>; kind: ZodEnum<["inline", "external"]>; payloadHash: ZodOptional<ZodString>; ref: ZodOptional<ZodString>; sha256: ZodOptional<ZodString>; }, "strip", ZodTypeAny, { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }, { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }>, { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }, { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }>>; typeId: ZodString; version: ZodNumber; }, "strip", ZodTypeAny, { artifactKey: string; createdAt: string; data?: unknown; pointer?: { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }; typeId: string; version: number; }, { artifactKey: string; createdAt: string; data?: unknown; pointer?: { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }; typeId: string; version: number; }>

Defined in: packages/runtime/src/protocol/artifacts.ts:70

#DEFAULT_ARTIFACT_EXTERNALIZATION_THRESHOLD_BYTES

const DEFAULT_ARTIFACT_EXTERNALIZATION_THRESHOLD_BYTES: number

Defined in: packages/runtime/src/persistence/artifactStore.ts:13

Default threshold above which the runtime will externalize artifact payloads to an ArtifactStore. Chosen to keep ordinary form-shaped artifacts (≤ 64 KB JSON) inline, large structured outputs (paragraphs, resumes, search results) inline, and to externalize bigger payloads (long documents, transcripts, dumps) so the run state stays cheap to round-trip through RunRepository.

Override per host via WorkbenchRuntimeOptions.artifactExternalizationThresholdBytes.

#demoArtifactTypes

const demoArtifactTypes: object[]

Defined in: packages/runtime/src/host/demoSchemas.ts:6

Reference JSON Schemas for the job-search style demo. Real apps should register their own.

#Type Declaration

#exportRedactPaths?

optional exportRedactPaths?: string[]

#id

id: string

#schema

schema: JsonSchema

#demoRuleSchemas

const demoRuleSchemas: object[]

Defined in: packages/runtime/src/host/demoSchemas.ts:85

#Type Declaration

#id

id: string

#schema

schema: JsonSchema

#GateStatusSchema

const GateStatusSchema: ZodEnum<["approved", "pending"]>

Defined in: packages/runtime/src/protocol/engine.ts:5

#JsonPatchOpSchema

const JsonPatchOpSchema: ZodDiscriminatedUnion<"op", [ZodObject<{ op: ZodLiteral<"add">; path: ZodString; value: ZodUnknown; }, "strict", ZodTypeAny, { op: "add"; path: string; value?: unknown; }, { op: "add"; path: string; value?: unknown; }>, ZodObject<{ op: ZodLiteral<"remove">; path: ZodString; }, "strict", ZodTypeAny, { op: "remove"; path: string; }, { op: "remove"; path: string; }>, ZodObject<{ op: ZodLiteral<"replace">; path: ZodString; value: ZodUnknown; }, "strict", ZodTypeAny, { op: "replace"; path: string; value?: unknown; }, { op: "replace"; path: string; value?: unknown; }>]>

Defined in: packages/runtime/src/protocol/trace.ts:11

Minimal RFC 6902 (JSON Patch) operation schema. We validate shape, not pointer-target reachability — that is the runtime's job at apply time. The Zod refinement guarantees the discriminator field set matches the spec so imported bundles cannot smuggle unparseable patches into the trace.

#JsonValueSchema

const JsonValueSchema: z.ZodType<JsonValue>

Defined in: packages/runtime/src/protocol/run.ts:11

#ModelCostSchema

const ModelCostSchema: ZodObject<{ amount: ZodNumber; currency: ZodString; }, "strict", ZodTypeAny, { amount: number; currency: string; }, { amount: number; currency: string; }>

Defined in: packages/runtime/src/protocol/trace.ts:57

Per-call cost reported by an LLM gateway/provider.

NOTE on precision: amount is a JavaScript number. This is fine for surfacing per-call cost in UI, exporting as approximate totals, and for any "is this run within budget?" check. It is not suitable as a billing ledger. If you need cent-accurate billing, pull the cost from your gateway's invoice / usage API server-side (or store amounts as integer micro-cents) — do not roll up model_io.cost.amount from traces for accounting purposes.

Currency should normally be an ISO 4217 code; the schema only enforces non-empty so that gateways with custom denominations (e.g. provider tokens) can still surface cost.

#ModelTelemetryBucketSchema

const ModelTelemetryBucketSchema: ZodObject<{ key: ZodString; label: ZodString; totals: ZodObject<{ cachedInputTokens: ZodNumber; costByCurrency: ZodRecord<ZodString, ZodNumber>; durationMs: ZodNumber; eventCount: ZodNumber; inputTokens: ZodNumber; outputTokens: ZodNumber; reasoningTokens: ZodNumber; totalTokens: ZodNumber; }, "strict", ZodTypeAny, { cachedInputTokens: number; costByCurrency: Record<string, number>; durationMs: number; eventCount: number; inputTokens: number; outputTokens: number; reasoningTokens: number; totalTokens: number; }, { cachedInputTokens: number; costByCurrency: Record<string, number>; durationMs: number; eventCount: number; inputTokens: number; outputTokens: number; reasoningTokens: number; totalTokens: number; }>; }, "strict", ZodTypeAny, { key: string; label: string; totals: { cachedInputTokens: number; costByCurrency: Record<string, number>; durationMs: number; eventCount: number; inputTokens: number; outputTokens: number; reasoningTokens: number; totalTokens: number; }; }, { key: string; label: string; totals: { cachedInputTokens: number; costByCurrency: Record<string, number>; durationMs: number; eventCount: number; inputTokens: number; outputTokens: number; reasoningTokens: number; totalTokens: number; }; }>

Defined in: packages/runtime/src/telemetry/modelTelemetry.ts:45

#ModelTelemetryDirectionSchema

const ModelTelemetryDirectionSchema: ZodEnum<["request", "response", "stream_chunk"]>

Defined in: packages/runtime/src/telemetry/modelTelemetry.ts:8

#ModelTelemetryEntrySchema

const ModelTelemetryEntrySchema: ZodObject<{ correlationId: ZodOptional<ZodString>; cost: ZodOptional<ZodObject<{ amount: ZodNumber; currency: ZodString; }, "strict", ZodTypeAny, { amount: number; currency: string; }, { amount: number; currency: string; }>>; direction: ZodEnum<["request", "response", "stream_chunk"]>; durationMs: ZodOptional<ZodNumber>; eventId: ZodString; model: ZodOptional<ZodString>; provider: ZodOptional<ZodString>; runId: ZodString; stepId: ZodOptional<ZodString>; subject: ZodOptional<ZodObject<{ accountId: ZodOptional<ZodString>; planId: ZodOptional<ZodString>; tenantId: ZodOptional<ZodString>; userId: ZodOptional<ZodString>; }, "strict", ZodTypeAny, { accountId?: string; planId?: string; tenantId?: string; userId?: string; }, { accountId?: string; planId?: string; tenantId?: string; userId?: string; }>>; ts: ZodString; usage: ZodOptional<ZodObject<{ cachedInputTokens: ZodOptional<ZodNumber>; inputTokens: ZodOptional<ZodNumber>; outputTokens: ZodOptional<ZodNumber>; reasoningTokens: ZodOptional<ZodNumber>; totalTokens: ZodOptional<ZodNumber>; }, "strict", ZodTypeAny, { cachedInputTokens?: number; inputTokens?: number; outputTokens?: number; reasoningTokens?: number; totalTokens?: number; }, { cachedInputTokens?: number; inputTokens?: number; outputTokens?: number; reasoningTokens?: number; totalTokens?: number; }>>; }, "strict", ZodTypeAny, { correlationId?: string; cost?: { amount: number; currency: string; }; direction: "request" | "response" | "stream_chunk"; durationMs?: number; eventId: string; model?: string; provider?: string; runId: string; stepId?: string; subject?: { accountId?: string; planId?: string; tenantId?: string; userId?: string; }; ts: string; usage?: { cachedInputTokens?: number; inputTokens?: number; outputTokens?: number; reasoningTokens?: number; totalTokens?: number; }; }, { correlationId?: string; cost?: { amount: number; currency: string; }; direction: "request" | "response" | "stream_chunk"; durationMs?: number; eventId: string; model?: string; provider?: string; runId: string; stepId?: string; subject?: { accountId?: string; planId?: string; tenantId?: string; userId?: string; }; ts: string; usage?: { cachedInputTokens?: number; inputTokens?: number; outputTokens?: number; reasoningTokens?: number; totalTokens?: number; }; }>

Defined in: packages/runtime/src/telemetry/modelTelemetry.ts:26

#ModelTelemetrySummarySchema

const ModelTelemetrySummarySchema: ZodObject<{ byModel: ZodArray<ZodObject<{ key: ZodString; label: ZodString; totals: ZodObject<{ cachedInputTokens: ZodNumber; costByCurrency: ZodRecord<ZodString, ZodNumber>; durationMs: ZodNumber; eventCount: ZodNumber; inputTokens: ZodNumber; outputTokens: ZodNumber; reasoningTokens: ZodNumber; totalTokens: ZodNumber; }, "strict", ZodTypeAny, { cachedInputTokens: number; costByCurrency: Record<string, number>; durationMs: number; eventCount: number; inputTokens: number; outputTokens: number; reasoningTokens: number; totalTokens: number; }, { cachedInputTokens: number; costByCurrency: Record<string, number>; durationMs: number; eventCount: number; inputTokens: number; outputTokens: number; reasoningTokens: number; totalTokens: number; }>; }, "strict", ZodTypeAny, { key: string; label: string; totals: { cachedInputTokens: number; costByCurrency: Record<string, number>; durationMs: number; eventCount: number; inputTokens: number; outputTokens: number; reasoningTokens: number; totalTokens: number; }; }, { key: string; label: string; totals: { cachedInputTokens: number; costByCurrency: Record<string, number>; durationMs: number; eventCount: number; inputTokens: number; outputTokens: number; reasoningTokens: number; totalTokens: number; }; }>, "many">; byPlan: ZodArray<ZodObject<{ key: ZodString; label: ZodString; totals: ZodObject<{ cachedInputTokens: ZodNumber; costByCurrency: ZodRecord<ZodString, ZodNumber>; durationMs: ZodNumber; eventCount: ZodNumber; inputTokens: ZodNumber; outputTokens: ZodNumber; reasoningTokens: ZodNumber; totalTokens: ZodNumber; }, "strict", ZodTypeAny, { cachedInputTokens: number; costByCurrency: Record<string, number>; durationMs: number; eventCount: number; inputTokens: number; outputTokens: number; reasoningTokens: number; totalTokens: number; }, { cachedInputTokens: number; costByCurrency: Record<string, number>; durationMs: number; eventCount: number; inputTokens: number; outputTokens: number; reasoningTokens: number; totalTokens: number; }>; }, "strict", ZodTypeAny, { key: string; label: string; totals: { cachedInputTokens: number; costByCurrency: Record<string, number>; durationMs: number; eventCount: number; inputTokens: number; outputTokens: number; reasoningTokens: number; totalTokens: number; }; }, { key: string; label: string; totals: { cachedInputTokens: number; costByCurrency: Record<string, number>; durationMs: number; eventCount: number; inputTokens: number; outputTokens: number; reasoningTokens: number; totalTokens: number; }; }>, "many">; byProvider: ZodArray<ZodObject<{ key: ZodString; label: ZodString; totals: ZodObject<{ cachedInputTokens: ZodNumber; costByCurrency: ZodRecord<ZodString, ZodNumber>; durationMs: ZodNumber; eventCount: ZodNumber; inputTokens: ZodNumber; outputTokens: ZodNumber; reasoningTokens: ZodNumber; totalTokens: ZodNumber; }, "strict", ZodTypeAny, { cachedInputTokens: number; costByCurrency: Record<string, number>; durationMs: number; eventCount: number; inputTokens: number; outputTokens: number; reasoningTokens: number; totalTokens: number; }, { cachedInputTokens: number; costByCurrency: Record<string, number>; durationMs: number; eventCount: number; inputTokens: number; outputTokens: number; reasoningTokens: number; totalTokens: number; }>; }, "strict", ZodTypeAny, { key: string; label: string; totals: { cachedInputTokens: number; costByCurrency: Record<string, number>; durationMs: number; eventCount: number; inputTokens: number; outputTokens: number; reasoningTokens: number; totalTokens: number; }; }, { key: string; label: string; totals: { cachedInputTokens: number; costByCurrency: Record<string, number>; durationMs: number; eventCount: number; inputTokens: number; outputTokens: number; reasoningTokens: number; totalTokens: number; }; }>, "many">; byProviderModel: ZodArray<ZodObject<{ key: ZodString; label: ZodString; totals: ZodObject<{ cachedInputTokens: ZodNumber; costByCurrency: ZodRecord<ZodString, ZodNumber>; durationMs: ZodNumber; eventCount: ZodNumber; inputTokens: ZodNumber; outputTokens: ZodNumber; reasoningTokens: ZodNumber; totalTokens: ZodNumber; }, "strict", ZodTypeAny, { cachedInputTokens: number; costByCurrency: Record<string, number>; durationMs: number; eventCount: number; inputTokens: number; outputTokens: number; reasoningTokens: number; totalTokens: number; }, { cachedInputTokens: number; costByCurrency: Record<string, number>; durationMs: number; eventCount: number; inputTokens: number; outputTokens: number; reasoningTokens: number; totalTokens: number; }>; }, "strict", ZodTypeAny, { key: string; label: string; totals: { cachedInputTokens: number; costByCurrency: Record<string, number>; durationMs: number; eventCount: number; inputTokens: number; outputTokens: number; reasoningTokens: number; totalTokens: number; }; }, { key: string; label: string; totals: { cachedInputTokens: number; costByCurrency: Record<string, number>; durationMs: number; eventCount: number; inputTokens: number; outputTokens: number; reasoningTokens: number; totalTokens: number; }; }>, "many">; byStep: ZodArray<ZodObject<{ key: ZodString; label: ZodString; totals: ZodObject<{ cachedInputTokens: ZodNumber; costByCurrency: ZodRecord<ZodString, ZodNumber>; durationMs: ZodNumber; eventCount: ZodNumber; inputTokens: ZodNumber; outputTokens: ZodNumber; reasoningTokens: ZodNumber; totalTokens: ZodNumber; }, "strict", ZodTypeAny, { cachedInputTokens: number; costByCurrency: Record<string, number>; durationMs: number; eventCount: number; inputTokens: number; outputTokens: number; reasoningTokens: number; totalTokens: number; }, { cachedInputTokens: number; costByCurrency: Record<string, number>; durationMs: number; eventCount: number; inputTokens: number; outputTokens: number; reasoningTokens: number; totalTokens: number; }>; }, "strict", ZodTypeAny, { key: string; label: string; totals: { cachedInputTokens: number; costByCurrency: Record<string, number>; durationMs: number; eventCount: number; inputTokens: number; outputTokens: number; reasoningTokens: number; totalTokens: number; }; }, { key: string; label: string; totals: { cachedInputTokens: number; costByCurrency: Record<string, number>; durationMs: number; eventCount: number; inputTokens: number; outputTokens: number; reasoningTokens: number; totalTokens: number; }; }>, "many">; byTenant: ZodArray<ZodObject<{ key: ZodString; label: ZodString; totals: ZodObject<{ cachedInputTokens: ZodNumber; costByCurrency: ZodRecord<ZodString, ZodNumber>; durationMs: ZodNumber; eventCount: ZodNumber; inputTokens: ZodNumber; outputTokens: ZodNumber; reasoningTokens: ZodNumber; totalTokens: ZodNumber; }, "strict", ZodTypeAny, { cachedInputTokens: number; costByCurrency: Record<string, number>; durationMs: number; eventCount: number; inputTokens: number; outputTokens: number; reasoningTokens: number; totalTokens: number; }, { cachedInputTokens: number; costByCurrency: Record<string, number>; durationMs: number; eventCount: number; inputTokens: number; outputTokens: number; reasoningTokens: number; totalTokens: number; }>; }, "strict", ZodTypeAny, { key: string; label: string; totals: { cachedInputTokens: number; costByCurrency: Record<string, number>; durationMs: number; eventCount: number; inputTokens: number; outputTokens: number; reasoningTokens: number; totalTokens: number; }; }, { key: string; label: string; totals: { cachedInputTokens: number; costByCurrency: Record<string, number>; durationMs: number; eventCount: number; inputTokens: number; outputTokens: number; reasoningTokens: number; totalTokens: number; }; }>, "many">; byUser: ZodArray<ZodObject<{ key: ZodString; label: ZodString; totals: ZodObject<{ cachedInputTokens: ZodNumber; costByCurrency: ZodRecord<ZodString, ZodNumber>; durationMs: ZodNumber; eventCount: ZodNumber; inputTokens: ZodNumber; outputTokens: ZodNumber; reasoningTokens: ZodNumber; totalTokens: ZodNumber; }, "strict", ZodTypeAny, { cachedInputTokens: number; costByCurrency: Record<string, number>; durationMs: number; eventCount: number; inputTokens: number; outputTokens: number; reasoningTokens: number; totalTokens: number; }, { cachedInputTokens: number; costByCurrency: Record<string, number>; durationMs: number; eventCount: number; inputTokens: number; outputTokens: number; reasoningTokens: number; totalTokens: number; }>; }, "strict", ZodTypeAny, { key: string; label: string; totals: { cachedInputTokens: number; costByCurrency: Record<string, number>; durationMs: number; eventCount: number; inputTokens: number; outputTokens: number; reasoningTokens: number; totalTokens: number; }; }, { key: string; label: string; totals: { cachedInputTokens: number; costByCurrency: Record<string, number>; durationMs: number; eventCount: number; inputTokens: number; outputTokens: number; reasoningTokens: number; totalTokens: number; }; }>, "many">; entries: ZodArray<ZodObject<{ correlationId: ZodOptional<ZodString>; cost: ZodOptional<ZodObject<{ amount: ZodNumber; currency: ZodString; }, "strict", ZodTypeAny, { amount: number; currency: string; }, { amount: number; currency: string; }>>; direction: ZodEnum<["request", "response", "stream_chunk"]>; durationMs: ZodOptional<ZodNumber>; eventId: ZodString; model: ZodOptional<ZodString>; provider: ZodOptional<ZodString>; runId: ZodString; stepId: ZodOptional<ZodString>; subject: ZodOptional<ZodObject<{ accountId: ZodOptional<ZodString>; planId: ZodOptional<ZodString>; tenantId: ZodOptional<ZodString>; userId: ZodOptional<ZodString>; }, "strict", ZodTypeAny, { accountId?: string; planId?: string; tenantId?: string; userId?: string; }, { accountId?: string; planId?: string; tenantId?: string; userId?: string; }>>; ts: ZodString; usage: ZodOptional<ZodObject<{ cachedInputTokens: ZodOptional<ZodNumber>; inputTokens: ZodOptional<ZodNumber>; outputTokens: ZodOptional<ZodNumber>; reasoningTokens: ZodOptional<ZodNumber>; totalTokens: ZodOptional<ZodNumber>; }, "strict", ZodTypeAny, { cachedInputTokens?: number; inputTokens?: number; outputTokens?: number; reasoningTokens?: number; totalTokens?: number; }, { cachedInputTokens?: number; inputTokens?: number; outputTokens?: number; reasoningTokens?: number; totalTokens?: number; }>>; }, "strict", ZodTypeAny, { correlationId?: string; cost?: { amount: number; currency: string; }; direction: "request" | "response" | "stream_chunk"; durationMs?: number; eventId: string; model?: string; provider?: string; runId: string; stepId?: string; subject?: { accountId?: string; planId?: string; tenantId?: string; userId?: string; }; ts: string; usage?: { cachedInputTokens?: number; inputTokens?: number; outputTokens?: number; reasoningTokens?: number; totalTokens?: number; }; }, { correlationId?: string; cost?: { amount: number; currency: string; }; direction: "request" | "response" | "stream_chunk"; durationMs?: number; eventId: string; model?: string; provider?: string; runId: string; stepId?: string; subject?: { accountId?: string; planId?: string; tenantId?: string; userId?: string; }; ts: string; usage?: { cachedInputTokens?: number; inputTokens?: number; outputTokens?: number; reasoningTokens?: number; totalTokens?: number; }; }>, "many">; generatedAt: ZodString; runIds: ZodArray<ZodString, "many">; totals: ZodObject<{ cachedInputTokens: ZodNumber; costByCurrency: ZodRecord<ZodString, ZodNumber>; durationMs: ZodNumber; eventCount: ZodNumber; inputTokens: ZodNumber; outputTokens: ZodNumber; reasoningTokens: ZodNumber; totalTokens: ZodNumber; }, "strict", ZodTypeAny, { cachedInputTokens: number; costByCurrency: Record<string, number>; durationMs: number; eventCount: number; inputTokens: number; outputTokens: number; reasoningTokens: number; totalTokens: number; }, { cachedInputTokens: number; costByCurrency: Record<string, number>; durationMs: number; eventCount: number; inputTokens: number; outputTokens: number; reasoningTokens: number; totalTokens: number; }>; }, "strict", ZodTypeAny, { byModel: object[]; byPlan: object[]; byProvider: object[]; byProviderModel: object[]; byStep: object[]; byTenant: object[]; byUser: object[]; entries: object[]; generatedAt: string; runIds: string[]; totals: { cachedInputTokens: number; costByCurrency: Record<string, number>; durationMs: number; eventCount: number; inputTokens: number; outputTokens: number; reasoningTokens: number; totalTokens: number; }; }, { byModel: object[]; byPlan: object[]; byProvider: object[]; byProviderModel: object[]; byStep: object[]; byTenant: object[]; byUser: object[]; entries: object[]; generatedAt: string; runIds: string[]; totals: { cachedInputTokens: number; costByCurrency: Record<string, number>; durationMs: number; eventCount: number; inputTokens: number; outputTokens: number; reasoningTokens: number; totalTokens: number; }; }>

Defined in: packages/runtime/src/telemetry/modelTelemetry.ts:55

#ModelTelemetryTotalsSchema

const ModelTelemetryTotalsSchema: ZodObject<{ cachedInputTokens: ZodNumber; costByCurrency: ZodRecord<ZodString, ZodNumber>; durationMs: ZodNumber; eventCount: ZodNumber; inputTokens: ZodNumber; outputTokens: ZodNumber; reasoningTokens: ZodNumber; totalTokens: ZodNumber; }, "strict", ZodTypeAny, { cachedInputTokens: number; costByCurrency: Record<string, number>; durationMs: number; eventCount: number; inputTokens: number; outputTokens: number; reasoningTokens: number; totalTokens: number; }, { cachedInputTokens: number; costByCurrency: Record<string, number>; durationMs: number; eventCount: number; inputTokens: number; outputTokens: number; reasoningTokens: number; totalTokens: number; }>

Defined in: packages/runtime/src/telemetry/modelTelemetry.ts:11

#ModelUsageSchema

const ModelUsageSchema: ZodObject<{ cachedInputTokens: ZodOptional<ZodNumber>; inputTokens: ZodOptional<ZodNumber>; outputTokens: ZodOptional<ZodNumber>; reasoningTokens: ZodOptional<ZodNumber>; totalTokens: ZodOptional<ZodNumber>; }, "strict", ZodTypeAny, { cachedInputTokens?: number; inputTokens?: number; outputTokens?: number; reasoningTokens?: number; totalTokens?: number; }, { cachedInputTokens?: number; inputTokens?: number; outputTokens?: number; reasoningTokens?: number; totalTokens?: number; }>

Defined in: packages/runtime/src/protocol/trace.ts:30

#RuleRecordSchema

const RuleRecordSchema: ZodObject<{ enabled: ZodBoolean; id: ZodString; label: ZodOptional<ZodString>; payload: ZodUnknown; priority: ZodNumber; }, "strip", ZodTypeAny, { enabled: boolean; id: string; label?: string; payload?: unknown; priority: number; }, { enabled: boolean; id: string; label?: string; payload?: unknown; priority: number; }>

Defined in: packages/runtime/src/protocol/rules.ts:3

#RuleSetSchema

const RuleSetSchema: ZodObject<{ id: ZodString; rules: ZodArray<ZodObject<{ enabled: ZodBoolean; id: ZodString; label: ZodOptional<ZodString>; payload: ZodUnknown; priority: ZodNumber; }, "strip", ZodTypeAny, { enabled: boolean; id: string; label?: string; payload?: unknown; priority: number; }, { enabled: boolean; id: string; label?: string; payload?: unknown; priority: number; }>, "many">; ruleSchemaId: ZodString; }, "strip", ZodTypeAny, { id: string; rules: object[]; ruleSchemaId: string; }, { id: string; rules: object[]; ruleSchemaId: string; }>

Defined in: packages/runtime/src/protocol/rules.ts:14

#RunBundleEngineSchema

const RunBundleEngineSchema: ZodObject<{ gateState: ZodArray<ZodTuple<[ZodString, ZodEffects<ZodObject<{ after: ZodEnum<["approved", "pending"]>; before: ZodEnum<["approved", "pending"]>; checkpoints: ZodOptional<ZodRecord<ZodString, ZodEnum<...>>>; }, "strip", ZodTypeAny, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints?: Record<string, ... | ...>; }, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints?: Record<string, ... | ...>; }>, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints: Record<string, "pending" | "approved">; }, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints?: Record<string, "pending" | "approved">; }>], null>, "many">; idempotency: ZodArray<ZodTuple<[ZodString, ZodObject<{ artifactKey: ZodString; version: ZodNumber; }, "strip", ZodTypeAny, { artifactKey: string; version: number; }, { artifactKey: string; version: number; }>], null>, "many">; revision: ZodNumber; stepStatus: ZodArray<ZodTuple<[ZodString, ZodEnum<["pending", "running", "completed", "failed"]>], null>, "many">; }, "strip", ZodTypeAny, { gateState: [string, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints: Record<string, "pending" | "approved">; }][]; idempotency: [string, { artifactKey: string; version: number; }][]; revision: number; stepStatus: [string, "pending" | "running" | "completed" | "failed"][]; }, { gateState: [string, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints?: Record<string, "pending" | "approved">; }][]; idempotency: [string, { artifactKey: string; version: number; }][]; revision: number; stepStatus: [string, "pending" | "running" | "completed" | "failed"][]; }>

Defined in: packages/runtime/src/protocol/engine.ts:15

#RunBundleSchema

const RunBundleSchema: ZodObject<{ artifacts: ZodArray<ZodObject<{ artifactKey: ZodString; createdAt: ZodString; data: ZodOptional<ZodUnknown>; pointer: ZodOptional<ZodEffects<ZodObject<{ byteLength: ZodOptional<ZodNumber>; kind: ZodEnum<[..., ...]>; payloadHash: ZodOptional<ZodString>; ref: ZodOptional<ZodString>; sha256: ZodOptional<ZodString>; }, "strip", ZodTypeAny, { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }, { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }>, { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }, { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }>>; typeId: ZodString; version: ZodNumber; }, "strip", ZodTypeAny, { artifactKey: string; createdAt: string; data?: unknown; pointer?: { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }; typeId: string; version: number; }, { artifactKey: string; createdAt: string; data?: unknown; pointer?: { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }; typeId: string; version: number; }>, "many">; engine: ZodOptional<ZodObject<{ gateState: ZodArray<ZodTuple<[ZodString, ZodEffects<ZodObject<{ after: ...; before: ...; checkpoints: ...; }, "strip", ZodTypeAny, { after: ...; before: ...; checkpoints?: ...; }, { after: ...; before: ...; checkpoints?: ...; }>, { after: ... | ...; before: ... | ...; checkpoints: Record<..., ...>; }, { after: ... | ...; before: ... | ...; checkpoints?: ... | ...; }>], null>, "many">; idempotency: ZodArray<ZodTuple<[ZodString, ZodObject<{ artifactKey: ZodString; version: ZodNumber; }, "strip", ZodTypeAny, { artifactKey: string; version: number; }, { artifactKey: string; version: number; }>], null>, "many">; revision: ZodNumber; stepStatus: ZodArray<ZodTuple<[ZodString, ZodEnum<["pending", "running", "completed", "failed"]>], null>, "many">; }, "strip", ZodTypeAny, { gateState: [string, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints: Record<string, "pending" | "approved">; }][]; idempotency: [string, { artifactKey: string; version: number; }][]; revision: number; stepStatus: [string, "pending" | "running" | "completed" | "failed"][]; }, { gateState: [string, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints?: Record<string, ... | ...>; }][]; idempotency: [string, { artifactKey: string; version: number; }][]; revision: number; stepStatus: [string, "pending" | "running" | "completed" | "failed"][]; }>>; integrity: ZodOptional<ZodObject<{ sha256: ZodString; }, "strip", ZodTypeAny, { sha256: string; }, { sha256: string; }>>; protocolVersion: ZodLiteral<"1.0.0">; ruleSets: ZodArray<ZodObject<{ id: ZodString; rules: ZodArray<ZodObject<{ enabled: ZodBoolean; id: ZodString; label: ZodOptional<ZodString>; payload: ZodUnknown; priority: ZodNumber; }, "strip", ZodTypeAny, { enabled: boolean; id: string; label?: string; payload?: unknown; priority: number; }, { enabled: boolean; id: string; label?: string; payload?: unknown; priority: number; }>, "many">; ruleSchemaId: ZodString; }, "strip", ZodTypeAny, { id: string; rules: object[]; ruleSchemaId: string; }, { id: string; rules: object[]; ruleSchemaId: string; }>, "many">; run: ZodObject<{ annotations: ZodOptional<ZodArray<ZodObject<{ at: ZodString; text: ZodString; }, "strip", ZodTypeAny, { at: string; text: string; }, { at: string; text: string; }>, "many">>; context: ZodOptional<ZodEffects<ZodObject<{ forkedFromStepId: ZodOptional<ZodString>; parentRunId: ZodOptional<ZodString>; parentRunIds: ZodOptional<ZodArray<ZodString, "many">>; pinnedArtifacts: ZodOptional<ZodArray<ZodObject<..., ..., ..., ..., ...>, "many">>; }, "strip", ZodTypeAny, { forkedFromStepId?: string; parentRunId?: string; parentRunIds?: string[]; pinnedArtifacts?: object[]; }, { forkedFromStepId?: string; parentRunId?: string; parentRunIds?: string[]; pinnedArtifacts?: object[]; }>, { forkedFromStepId?: string; parentRunId?: string; parentRunIds?: string[]; pinnedArtifacts?: object[]; }, { forkedFromStepId?: string; parentRunId?: string; parentRunIds?: string[]; pinnedArtifacts?: object[]; }>>; endedAt: ZodOptional<ZodString>; id: ZodString; metadata: ZodOptional<ZodRecord<ZodString, ZodType<JsonValue, ZodTypeDef, JsonValue>>>; startedAt: ZodString; status: ZodEnum<["running", "completed", "failed", "cancelled"]>; subject: ZodOptional<ZodObject<{ accountId: ZodOptional<ZodString>; planId: ZodOptional<ZodString>; tenantId: ZodOptional<ZodString>; userId: ZodOptional<ZodString>; }, "strict", ZodTypeAny, { accountId?: string; planId?: string; tenantId?: string; userId?: string; }, { accountId?: string; planId?: string; tenantId?: string; userId?: string; }>>; tags: ZodOptional<ZodArray<ZodString, "many">>; workflowId: ZodString; workflowSnapshot: ZodObject<{ edges: ZodDefault<ZodArray<ZodObject<{ from: ZodString; id: ZodString; to: ZodString; }, "strip", ZodTypeAny, { from: string; id: string; to: string; }, { from: string; id: string; to: string; }>, "many">>; id: ZodString; steps: ZodArray<ZodObject<{ description: ZodOptional<ZodString>; gatePolicy: ZodDefault<ZodEnum<...>>; id: ZodString; inputs: ZodDefault<ZodArray<..., ...>>; outputs: ZodDefault<ZodArray<..., ...>>; title: ZodOptional<ZodString>; }, "strip", ZodTypeAny, { description?: string; gatePolicy: "AUTO" | "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; inputs: string[]; outputs: string[]; title?: string; }, { description?: string; gatePolicy?: "AUTO" | "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; inputs?: ...[]; outputs?: ...[]; title?: string; }>, "many">; title: ZodOptional<ZodString>; version: ZodNumber; }, "strip", ZodTypeAny, { edges: object[]; id: string; steps: object[]; title?: string; version: number; }, { edges?: object[]; id: string; steps: object[]; title?: string; version: number; }>; workflowVersion: ZodNumber; }, "strip", ZodTypeAny, { annotations?: object[]; context?: { forkedFromStepId?: string; parentRunId?: string; parentRunIds?: string[]; pinnedArtifacts?: object[]; }; endedAt?: string; id: string; metadata?: Record<string, JsonValue>; startedAt: string; status: "running" | "completed" | "failed" | "cancelled"; subject?: { accountId?: string; planId?: string; tenantId?: string; userId?: string; }; tags?: string[]; workflowId: string; workflowSnapshot: { edges: object[]; id: string; steps: object[]; title?: string; version: number; }; workflowVersion: number; }, { annotations?: object[]; context?: { forkedFromStepId?: string; parentRunId?: string; parentRunIds?: string[]; pinnedArtifacts?: object[]; }; endedAt?: string; id: string; metadata?: Record<string, JsonValue>; startedAt: string; status: "running" | "completed" | "failed" | "cancelled"; subject?: { accountId?: string; planId?: string; tenantId?: string; userId?: string; }; tags?: string[]; workflowId: string; workflowSnapshot: { edges?: object[]; id: string; steps: object[]; title?: string; version: number; }; workflowVersion: number; }>; trace: ZodArray<ZodDiscriminatedUnion<"type", [ZodObject<object & object, "strip", ZodTypeAny, { correlationId?: string; id: string; runId: string; stepId: string; ts: string; type: "step_started"; }, { correlationId?: string; id: string; runId: string; stepId: string; ts: string; type: "step_started"; }>, ZodObject<object & object, "strip", ZodTypeAny, { correlationId?: string; error?: { code?: string; message: string; }; id: string; ok: boolean; runId: string; stepId: string; ts: string; type: "step_completed"; }, { correlationId?: string; error?: { code?: string; message: string; }; id: string; ok: boolean; runId: string; stepId: string; ts: string; type: "step_completed"; }>, ZodObject<object & object, "strip", ZodTypeAny, { artifact: { artifactKey: string; createdAt: string; data?: unknown; pointer?: { byteLength?: ... | ...; kind: ... | ...; payloadHash?: ... | ...; ref?: ... | ...; sha256?: ... | ...; }; typeId: string; version: number; }; correlationId?: string; id: string; idempotencyKey?: string; runId: string; stepId?: string; ts: string; type: "artifact_written"; }, { artifact: { artifactKey: string; createdAt: string; data?: unknown; pointer?: { byteLength?: ... | ...; kind: ... | ...; payloadHash?: ... | ...; ref?: ... | ...; sha256?: ... | ...; }; typeId: string; version: number; }; correlationId?: string; id: string; idempotencyKey?: string; runId: string; stepId?: string; ts: string; type: "artifact_written"; }>]>, "many">; }, "strip", ZodTypeAny, { artifacts: object[]; engine?: { gateState: [string, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints: Record<string, "pending" | "approved">; }][]; idempotency: [string, { artifactKey: string; version: number; }][]; revision: number; stepStatus: [string, "pending" | "running" | "completed" | "failed"][]; }; integrity?: { sha256: string; }; protocolVersion: "1.0.0"; ruleSets: object[]; run: { annotations?: object[]; context?: { forkedFromStepId?: string; parentRunId?: string; parentRunIds?: string[]; pinnedArtifacts?: object[]; }; endedAt?: string; id: string; metadata?: Record<string, JsonValue>; startedAt: string; status: "running" | "completed" | "failed" | "cancelled"; subject?: { accountId?: string; planId?: string; tenantId?: string; userId?: string; }; tags?: string[]; workflowId: string; workflowSnapshot: { edges: object[]; id: string; steps: object[]; title?: string; version: number; }; workflowVersion: number; }; trace: ({ correlationId?: string; id: string; runId: string; stepId: string; ts: string; type: "step_started"; } | { correlationId?: string; error?: { code?: string; message: string; }; id: string; ok: boolean; runId: string; stepId: string; ts: string; type: "step_completed"; } | { artifact: { artifactKey: string; createdAt: string; data?: unknown; pointer?: { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }; typeId: string; version: number; }; correlationId?: string; id: string; idempotencyKey?: string; runId: string; stepId?: string; ts: string; type: "artifact_written"; } | { artifactKey: string; correlationId?: string; fromVersion: number; id: string; idempotencyKey?: string; patch: ({ op: "add"; path: string; value?: unknown; } | { op: "remove"; path: string; } | { op: "replace"; path: string; value?: unknown; } | { from: string; op: "move"; path: string; } | { from: string; op: "copy"; path: string; } | { op: "test"; path: string; value?: unknown; })[]; runId: string; stepId?: string; toVersion: number; ts: string; type: "artifact_patch"; } | { correlationId?: string; cost?: { amount: number; currency: string; }; direction: "request" | "response" | "stream_chunk"; durationMs?: number; id: string; model?: string; payload?: unknown; provider?: string; runId: string; stepId?: string; summary?: string; ts: string; type: "model_io"; usage?: { cachedInputTokens?: number; inputTokens?: number; outputTokens?: number; reasoningTokens?: number; totalTokens?: number; }; } | { args?: unknown; correlationId?: string; id: string; name: string; result?: unknown; runId: string; stepId?: string; ts: string; type: "tool_call"; } | { correlationId?: string; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; reason?: string; runId: string; stepId: string; ts: string; type: "human_gate_requested"; } | { correlationId?: string; decision: "approved" | "rejected" | "edited"; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; note?: string; runId: string; stepId: string; ts: string; type: "human_gate_resolved"; } | { correlationId?: string; id: string; ruleSetId: string; runId: string; snapshot: { id: string; rules: object[]; ruleSchemaId: string; }; stepId?: string; ts: string; type: "rule_changed"; } | { correlationId?: string; id: string; policy: "AUTO" | "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; runId: string; stepId: string; ts: string; type: "policy_changed"; } | { code?: string; correlationId?: string; fatal?: boolean; id: string; message: string; runId: string; stepId?: string; ts: string; type: "error"; } | { correlationId?: string; forkedFromStepId?: string; id: string; parentRunId: string; parentRunIds?: string[]; runId: string; stepId?: string; ts: string; type: "run_forked"; } | { correlationId?: string; id: string; runId: string; stepId?: string; tags?: string[]; text: string; ts: string; type: "annotation"; } | { correlationId?: string; id: string; reason?: string; runId: string; status: "running" | "completed" | "failed" | "cancelled"; stepId?: string; ts: string; type: "run_status_changed"; } | { attributes?: Record<string, unknown>; correlationId?: string; id: string; kind?: "internal" | "client" | "server" | "producer" | "consumer"; name: string; parentSpanId?: string; runId: string; spanId: string; stepId?: string; ts: string; type: "span_started"; } | { attributes?: Record<string, unknown>; correlationId?: string; durationMs?: number; error?: { code?: string; message: string; }; id: string; runId: string; spanId: string; status?: "ok" | "error"; stepId?: string; ts: string; type: "span_ended"; })[]; }, { artifacts: object[]; engine?: { gateState: [string, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints?: Record<string, "pending" | "approved">; }][]; idempotency: [string, { artifactKey: string; version: number; }][]; revision: number; stepStatus: [string, "pending" | "running" | "completed" | "failed"][]; }; integrity?: { sha256: string; }; protocolVersion: "1.0.0"; ruleSets: object[]; run: { annotations?: object[]; context?: { forkedFromStepId?: string; parentRunId?: string; parentRunIds?: string[]; pinnedArtifacts?: object[]; }; endedAt?: string; id: string; metadata?: Record<string, JsonValue>; startedAt: string; status: "running" | "completed" | "failed" | "cancelled"; subject?: { accountId?: string; planId?: string; tenantId?: string; userId?: string; }; tags?: string[]; workflowId: string; workflowSnapshot: { edges?: object[]; id: string; steps: object[]; title?: string; version: number; }; workflowVersion: number; }; trace: ({ correlationId?: string; id: string; runId: string; stepId: string; ts: string; type: "step_started"; } | { correlationId?: string; error?: { code?: string; message: string; }; id: string; ok: boolean; runId: string; stepId: string; ts: string; type: "step_completed"; } | { artifact: { artifactKey: string; createdAt: string; data?: unknown; pointer?: { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }; typeId: string; version: number; }; correlationId?: string; id: string; idempotencyKey?: string; runId: string; stepId?: string; ts: string; type: "artifact_written"; } | { artifactKey: string; correlationId?: string; fromVersion: number; id: string; idempotencyKey?: string; patch: ({ op: "add"; path: string; value?: unknown; } | { op: "remove"; path: string; } | { op: "replace"; path: string; value?: unknown; } | { from: string; op: "move"; path: string; } | { from: string; op: "copy"; path: string; } | { op: "test"; path: string; value?: unknown; })[]; runId: string; stepId?: string; toVersion: number; ts: string; type: "artifact_patch"; } | { correlationId?: string; cost?: { amount: number; currency: string; }; direction: "request" | "response" | "stream_chunk"; durationMs?: number; id: string; model?: string; payload?: unknown; provider?: string; runId: string; stepId?: string; summary?: string; ts: string; type: "model_io"; usage?: { cachedInputTokens?: number; inputTokens?: number; outputTokens?: number; reasoningTokens?: number; totalTokens?: number; }; } | { args?: unknown; correlationId?: string; id: string; name: string; result?: unknown; runId: string; stepId?: string; ts: string; type: "tool_call"; } | { correlationId?: string; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; reason?: string; runId: string; stepId: string; ts: string; type: "human_gate_requested"; } | { correlationId?: string; decision: "approved" | "rejected" | "edited"; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; note?: string; runId: string; stepId: string; ts: string; type: "human_gate_resolved"; } | { correlationId?: string; id: string; ruleSetId: string; runId: string; snapshot: { id: string; rules: object[]; ruleSchemaId: string; }; stepId?: string; ts: string; type: "rule_changed"; } | { correlationId?: string; id: string; policy: "AUTO" | "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; runId: string; stepId: string; ts: string; type: "policy_changed"; } | { code?: string; correlationId?: string; fatal?: boolean; id: string; message: string; runId: string; stepId?: string; ts: string; type: "error"; } | { correlationId?: string; forkedFromStepId?: string; id: string; parentRunId: string; parentRunIds?: string[]; runId: string; stepId?: string; ts: string; type: "run_forked"; } | { correlationId?: string; id: string; runId: string; stepId?: string; tags?: string[]; text: string; ts: string; type: "annotation"; } | { correlationId?: string; id: string; reason?: string; runId: string; status: "running" | "completed" | "failed" | "cancelled"; stepId?: string; ts: string; type: "run_status_changed"; } | { attributes?: Record<string, unknown>; correlationId?: string; id: string; kind?: "internal" | "client" | "server" | "producer" | "consumer"; name: string; parentSpanId?: string; runId: string; spanId: string; stepId?: string; ts: string; type: "span_started"; } | { attributes?: Record<string, unknown>; correlationId?: string; durationMs?: number; error?: { code?: string; message: string; }; id: string; runId: string; spanId: string; status?: "ok" | "error"; stepId?: string; ts: string; type: "span_ended"; })[]; }>

Defined in: packages/runtime/src/protocol/run.ts:131

#RunContextRefSchema

const RunContextRefSchema: ZodEffects<ZodObject<{ forkedFromStepId: ZodOptional<ZodString>; parentRunId: ZodOptional<ZodString>; parentRunIds: ZodOptional<ZodArray<ZodString, "many">>; pinnedArtifacts: ZodOptional<ZodArray<ZodObject<{ artifactKey: ZodString; version: ZodNumber; }, "strip", ZodTypeAny, { artifactKey: string; version: number; }, { artifactKey: string; version: number; }>, "many">>; }, "strip", ZodTypeAny, { forkedFromStepId?: string; parentRunId?: string; parentRunIds?: string[]; pinnedArtifacts?: object[]; }, { forkedFromStepId?: string; parentRunId?: string; parentRunIds?: string[]; pinnedArtifacts?: object[]; }>, { forkedFromStepId?: string; parentRunId?: string; parentRunIds?: string[]; pinnedArtifacts?: object[]; }, { forkedFromStepId?: string; parentRunId?: string; parentRunIds?: string[]; pinnedArtifacts?: object[]; }>

Defined in: packages/runtime/src/protocol/run.ts:38

Parent linkage for a run that is descended from one or more other runs.

  • Single parent (fork): set parentRunId (legacy, still supported and

still written by buildForkStartInput).

  • Multi-parent (agent-of-agents / supervision): set parentRunIds to a

non-empty array. When both are set, parentRunIds[0] MUST equal parentRunId. New code should prefer parentRunIds; reading code should prefer the helper getParentRunIds.

Adding parentRunIds as plural is the schema's escape hatch for supervisor → child / coordinator → workers patterns where a child may have multiple supervising parents (e.g. a research agent invoked by both a planner run and a tool-call run that share state). The single parentRunId form remains the canonical shape for explicit human forks.

#RunInstanceSchema

const RunInstanceSchema: ZodObject<{ annotations: ZodOptional<ZodArray<ZodObject<{ at: ZodString; text: ZodString; }, "strip", ZodTypeAny, { at: string; text: string; }, { at: string; text: string; }>, "many">>; context: ZodOptional<ZodEffects<ZodObject<{ forkedFromStepId: ZodOptional<ZodString>; parentRunId: ZodOptional<ZodString>; parentRunIds: ZodOptional<ZodArray<ZodString, "many">>; pinnedArtifacts: ZodOptional<ZodArray<ZodObject<{ artifactKey: ZodString; version: ZodNumber; }, "strip", ZodTypeAny, { artifactKey: string; version: number; }, { artifactKey: string; version: number; }>, "many">>; }, "strip", ZodTypeAny, { forkedFromStepId?: string; parentRunId?: string; parentRunIds?: string[]; pinnedArtifacts?: object[]; }, { forkedFromStepId?: string; parentRunId?: string; parentRunIds?: string[]; pinnedArtifacts?: object[]; }>, { forkedFromStepId?: string; parentRunId?: string; parentRunIds?: string[]; pinnedArtifacts?: object[]; }, { forkedFromStepId?: string; parentRunId?: string; parentRunIds?: string[]; pinnedArtifacts?: object[]; }>>; endedAt: ZodOptional<ZodString>; id: ZodString; metadata: ZodOptional<ZodRecord<ZodString, ZodType<JsonValue, ZodTypeDef, JsonValue>>>; startedAt: ZodString; status: ZodEnum<["running", "completed", "failed", "cancelled"]>; subject: ZodOptional<ZodObject<{ accountId: ZodOptional<ZodString>; planId: ZodOptional<ZodString>; tenantId: ZodOptional<ZodString>; userId: ZodOptional<ZodString>; }, "strict", ZodTypeAny, { accountId?: string; planId?: string; tenantId?: string; userId?: string; }, { accountId?: string; planId?: string; tenantId?: string; userId?: string; }>>; tags: ZodOptional<ZodArray<ZodString, "many">>; workflowId: ZodString; workflowSnapshot: ZodObject<{ edges: ZodDefault<ZodArray<ZodObject<{ from: ZodString; id: ZodString; to: ZodString; }, "strip", ZodTypeAny, { from: string; id: string; to: string; }, { from: string; id: string; to: string; }>, "many">>; id: ZodString; steps: ZodArray<ZodObject<{ description: ZodOptional<ZodString>; gatePolicy: ZodDefault<ZodEnum<["AUTO", "PAUSE_BEFORE", "PAUSE_AFTER", "CHECKPOINT"]>>; id: ZodString; inputs: ZodDefault<ZodArray<ZodString, "many">>; outputs: ZodDefault<ZodArray<ZodString, "many">>; title: ZodOptional<ZodString>; }, "strip", ZodTypeAny, { description?: string; gatePolicy: "AUTO" | "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; inputs: string[]; outputs: string[]; title?: string; }, { description?: string; gatePolicy?: "AUTO" | "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; inputs?: string[]; outputs?: string[]; title?: string; }>, "many">; title: ZodOptional<ZodString>; version: ZodNumber; }, "strip", ZodTypeAny, { edges: object[]; id: string; steps: object[]; title?: string; version: number; }, { edges?: object[]; id: string; steps: object[]; title?: string; version: number; }>; workflowVersion: ZodNumber; }, "strip", ZodTypeAny, { annotations?: object[]; context?: { forkedFromStepId?: string; parentRunId?: string; parentRunIds?: string[]; pinnedArtifacts?: object[]; }; endedAt?: string; id: string; metadata?: Record<string, JsonValue>; startedAt: string; status: "running" | "completed" | "failed" | "cancelled"; subject?: { accountId?: string; planId?: string; tenantId?: string; userId?: string; }; tags?: string[]; workflowId: string; workflowSnapshot: { edges: object[]; id: string; steps: object[]; title?: string; version: number; }; workflowVersion: number; }, { annotations?: object[]; context?: { forkedFromStepId?: string; parentRunId?: string; parentRunIds?: string[]; pinnedArtifacts?: object[]; }; endedAt?: string; id: string; metadata?: Record<string, JsonValue>; startedAt: string; status: "running" | "completed" | "failed" | "cancelled"; subject?: { accountId?: string; planId?: string; tenantId?: string; userId?: string; }; tags?: string[]; workflowId: string; workflowSnapshot: { edges?: object[]; id: string; steps: object[]; title?: string; version: number; }; workflowVersion: number; }>

Defined in: packages/runtime/src/protocol/run.ts:103

#RunSubjectRefSchema

const RunSubjectRefSchema: ZodObject<{ accountId: ZodOptional<ZodString>; planId: ZodOptional<ZodString>; tenantId: ZodOptional<ZodString>; userId: ZodOptional<ZodString>; }, "strict", ZodTypeAny, { accountId?: string; planId?: string; tenantId?: string; userId?: string; }, { accountId?: string; planId?: string; tenantId?: string; userId?: string; }>

Defined in: packages/runtime/src/protocol/run.ts:92

#StepGatePolicySchema

const StepGatePolicySchema: ZodEnum<["AUTO", "PAUSE_BEFORE", "PAUSE_AFTER", "CHECKPOINT"]>

Defined in: packages/runtime/src/protocol/workflow.ts:3

#StepGateStateSerializedSchema

const StepGateStateSerializedSchema: ZodEffects<ZodObject<{ after: ZodEnum<["approved", "pending"]>; before: ZodEnum<["approved", "pending"]>; checkpoints: ZodOptional<ZodRecord<ZodString, ZodEnum<["approved", "pending"]>>>; }, "strip", ZodTypeAny, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints?: Record<string, "pending" | "approved">; }, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints?: Record<string, "pending" | "approved">; }>, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints: Record<string, "pending" | "approved">; }, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints?: Record<string, "pending" | "approved">; }>

Defined in: packages/runtime/src/protocol/engine.ts:7

#StepRuntimeStatusSchema

const StepRuntimeStatusSchema: ZodEnum<["pending", "running", "completed", "failed"]>

Defined in: packages/runtime/src/protocol/engine.ts:3

#TraceEventSchema

const TraceEventSchema: ZodDiscriminatedUnion<"type", [ZodObject<object & object, "strip", ZodTypeAny, { correlationId?: string; id: string; runId: string; stepId: string; ts: string; type: "step_started"; }, { correlationId?: string; id: string; runId: string; stepId: string; ts: string; type: "step_started"; }>, ZodObject<object & object, "strip", ZodTypeAny, { correlationId?: string; error?: { code?: string; message: string; }; id: string; ok: boolean; runId: string; stepId: string; ts: string; type: "step_completed"; }, { correlationId?: string; error?: { code?: string; message: string; }; id: string; ok: boolean; runId: string; stepId: string; ts: string; type: "step_completed"; }>, ZodObject<object & object, "strip", ZodTypeAny, { artifact: { artifactKey: string; createdAt: string; data?: unknown; pointer?: { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }; typeId: string; version: number; }; correlationId?: string; id: string; idempotencyKey?: string; runId: string; stepId?: string; ts: string; type: "artifact_written"; }, { artifact: { artifactKey: string; createdAt: string; data?: unknown; pointer?: { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }; typeId: string; version: number; }; correlationId?: string; id: string; idempotencyKey?: string; runId: string; stepId?: string; ts: string; type: "artifact_written"; }>]>

Defined in: packages/runtime/src/protocol/trace.ts:66

#WORKBENCH_PROTOCOL_VERSION

const WORKBENCH_PROTOCOL_VERSION: "1.0.0"

Defined in: packages/runtime/src/protocol/version.ts:1

#WorkflowEdgeSchema

const WorkflowEdgeSchema: ZodObject<{ from: ZodString; id: ZodString; to: ZodString; }, "strip", ZodTypeAny, { from: string; id: string; to: string; }, { from: string; id: string; to: string; }>

Defined in: packages/runtime/src/protocol/workflow.ts:12

#WorkflowSpecSchema

const WorkflowSpecSchema: ZodObject<{ edges: ZodDefault<ZodArray<ZodObject<{ from: ZodString; id: ZodString; to: ZodString; }, "strip", ZodTypeAny, { from: string; id: string; to: string; }, { from: string; id: string; to: string; }>, "many">>; id: ZodString; steps: ZodArray<ZodObject<{ description: ZodOptional<ZodString>; gatePolicy: ZodDefault<ZodEnum<["AUTO", "PAUSE_BEFORE", "PAUSE_AFTER", "CHECKPOINT"]>>; id: ZodString; inputs: ZodDefault<ZodArray<ZodString, "many">>; outputs: ZodDefault<ZodArray<ZodString, "many">>; title: ZodOptional<ZodString>; }, "strip", ZodTypeAny, { description?: string; gatePolicy: "AUTO" | "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; inputs: string[]; outputs: string[]; title?: string; }, { description?: string; gatePolicy?: "AUTO" | "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; inputs?: string[]; outputs?: string[]; title?: string; }>, "many">; title: ZodOptional<ZodString>; version: ZodNumber; }, "strip", ZodTypeAny, { edges: object[]; id: string; steps: object[]; title?: string; version: number; }, { edges?: object[]; id: string; steps: object[]; title?: string; version: number; }>

Defined in: packages/runtime/src/protocol/workflow.ts:33

#WorkflowStepSchema

const WorkflowStepSchema: ZodObject<{ description: ZodOptional<ZodString>; gatePolicy: ZodDefault<ZodEnum<["AUTO", "PAUSE_BEFORE", "PAUSE_AFTER", "CHECKPOINT"]>>; id: ZodString; inputs: ZodDefault<ZodArray<ZodString, "many">>; outputs: ZodDefault<ZodArray<ZodString, "many">>; title: ZodOptional<ZodString>; }, "strip", ZodTypeAny, { description?: string; gatePolicy: "AUTO" | "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; inputs: string[]; outputs: string[]; title?: string; }, { description?: string; gatePolicy?: "AUTO" | "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; inputs?: string[]; outputs?: string[]; title?: string; }>

Defined in: packages/runtime/src/protocol/workflow.ts:20

#Functions

#assertRunBundleStructuralInvariants()

assertRunBundleStructuralInvariants(bundle): void

Defined in: packages/runtime/src/protocol/runValidate.ts:34

Validates bundle invariants that JSON schema alone cannot express.

This protects import paths from accepting bundles that would hydrate into impossible runtime state, for example cyclic workflows, trace events from a different run, or engine snapshots keyed by unknown workflow steps.

#Parameters

#bundle

#artifacts

object[] = ...

#engine?

{ gateState: [string, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints: Record<string, "pending" | "approved">; }][]; idempotency: [string, { artifactKey: string; version: number; }][]; revision: number; stepStatus: [string, "pending" | "running" | "completed" | "failed"][]; } = ...

Optional engine snapshot for faithful rehydration (gates, step status, idempotency).

#engine.gateState

[string, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints: Record<string, "pending" | "approved">; }][] = ...

#engine.idempotency

[string, { artifactKey: string; version: number; }][] = ...

#engine.revision

number = ...

#engine.stepStatus

[string, "pending" | "running" | "completed" | "failed"][] = ...

#integrity?

{ sha256: string; } = ...

Integrity: sha256 of canonical JSON of {run,trace,artifacts,ruleSets,engine?} without this field

#integrity.sha256

string = ...

#protocolVersion

"1.0.0" = ...

#ruleSets

object[] = ...

#run

{ annotations?: object[]; context?: { forkedFromStepId?: string; parentRunId?: string; parentRunIds?: string[]; pinnedArtifacts?: object[]; }; endedAt?: string; id: string; metadata?: Record<string, JsonValue>; startedAt: string; status: "running" | "completed" | "failed" | "cancelled"; subject?: { accountId?: string; planId?: string; tenantId?: string; userId?: string; }; tags?: string[]; workflowId: string; workflowSnapshot: { edges: object[]; id: string; steps: object[]; title?: string; version: number; }; workflowVersion: number; } = RunInstanceSchema

#run.annotations?

object[] = ...

#run.context?

{ forkedFromStepId?: string; parentRunId?: string; parentRunIds?: string[]; pinnedArtifacts?: object[]; } = ...

#run.context.forkedFromStepId?

string = ...

#run.context.parentRunId?

string = ...

Deprecated

Prefer parentRunIds. Kept for back-compat and for the common "fork from a single parent" case. When parentRunIds is set, this MUST equal parentRunIds[0].

#run.context.parentRunIds?

string[] = ...

#run.context.pinnedArtifacts?

object[] = ...

Pinned artifact versions treated as read-only context

#run.endedAt?

string = ...

#run.id

string = ...

#run.metadata?

Record<string, JsonValue> = ...

JSON-only host metadata kept with the run snapshot. Avoid secrets.

#run.startedAt

string = ...

#run.status

"running" | "completed" | "failed" | "cancelled" = ...

#run.subject?

{ accountId?: string; planId?: string; tenantId?: string; userId?: string; } = ...

Host-provided subject/account attribution for telemetry, quotas, and billing.

#run.subject.accountId?

string = ...

#run.subject.planId?

string = ...

#run.subject.tenantId?

string = ...

#run.subject.userId?

string = ...

#run.tags?

string[] = ...

Tags for organizing learning iterations

#run.workflowId

string = ...

#run.workflowSnapshot

{ edges: object[]; id: string; steps: object[]; title?: string; version: number; } = WorkflowSpecSchema

Snapshot of workflow at run start

#run.workflowSnapshot.edges

object[] = ...

#run.workflowSnapshot.id

string = ...

#run.workflowSnapshot.steps

object[] = ...

#run.workflowSnapshot.title?

string = ...

#run.workflowSnapshot.version

number = ...

#run.workflowVersion

number = ...

#trace

({ correlationId?: string; id: string; runId: string; stepId: string; ts: string; type: "step_started"; } | { correlationId?: string; error?: { code?: string; message: string; }; id: string; ok: boolean; runId: string; stepId: string; ts: string; type: "step_completed"; } | { artifact: { artifactKey: string; createdAt: string; data?: unknown; pointer?: { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }; typeId: string; version: number; }; correlationId?: string; id: string; idempotencyKey?: string; runId: string; stepId?: string; ts: string; type: "artifact_written"; } | { artifactKey: string; correlationId?: string; fromVersion: number; id: string; idempotencyKey?: string; patch: ({ op: "add"; path: string; value?: unknown; } | { op: "remove"; path: string; } | { op: "replace"; path: string; value?: unknown; } | { from: string; op: "move"; path: string; } | { from: string; op: "copy"; path: string; } | { op: "test"; path: string; value?: unknown; })[]; runId: string; stepId?: string; toVersion: number; ts: string; type: "artifact_patch"; } | { correlationId?: string; cost?: { amount: number; currency: string; }; direction: "request" | "response" | "stream_chunk"; durationMs?: number; id: string; model?: string; payload?: unknown; provider?: string; runId: string; stepId?: string; summary?: string; ts: string; type: "model_io"; usage?: { cachedInputTokens?: number; inputTokens?: number; outputTokens?: number; reasoningTokens?: number; totalTokens?: number; }; } | { args?: unknown; correlationId?: string; id: string; name: string; result?: unknown; runId: string; stepId?: string; ts: string; type: "tool_call"; } | { correlationId?: string; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; reason?: string; runId: string; stepId: string; ts: string; type: "human_gate_requested"; } | { correlationId?: string; decision: "approved" | "rejected" | "edited"; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; note?: string; runId: string; stepId: string; ts: string; type: "human_gate_resolved"; } | { correlationId?: string; id: string; ruleSetId: string; runId: string; snapshot: { id: string; rules: object[]; ruleSchemaId: string; }; stepId?: string; ts: string; type: "rule_changed"; } | { correlationId?: string; id: string; policy: "AUTO" | "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; runId: string; stepId: string; ts: string; type: "policy_changed"; } | { code?: string; correlationId?: string; fatal?: boolean; id: string; message: string; runId: string; stepId?: string; ts: string; type: "error"; } | { correlationId?: string; forkedFromStepId?: string; id: string; parentRunId: string; parentRunIds?: string[]; runId: string; stepId?: string; ts: string; type: "run_forked"; } | { correlationId?: string; id: string; runId: string; stepId?: string; tags?: string[]; text: string; ts: string; type: "annotation"; } | { correlationId?: string; id: string; reason?: string; runId: string; status: "running" | "completed" | "failed" | "cancelled"; stepId?: string; ts: string; type: "run_status_changed"; } | { attributes?: Record<string, unknown>; correlationId?: string; id: string; kind?: "internal" | "client" | "server" | "producer" | "consumer"; name: string; parentSpanId?: string; runId: string; spanId: string; stepId?: string; ts: string; type: "span_started"; } | { attributes?: Record<string, unknown>; correlationId?: string; durationMs?: number; error?: { code?: string; message: string; }; id: string; runId: string; spanId: string; status?: "ok" | "error"; stepId?: string; ts: string; type: "span_ended"; })[] = ...

#Returns

void

#assertRunStoreStateStructuralInvariants()

assertRunStoreStateStructuralInvariants(state): void

Defined in: packages/runtime/src/runtime/state.ts:43

#Parameters

#state

RunStoreState

#Returns

void

#assertWorkflowStructuralInvariants()

assertWorkflowStructuralInvariants(spec): void

Defined in: packages/runtime/src/protocol/workflowValidate.ts:7

Validates graph invariants beyond JSON-schema shape (edge endpoints, duplicate ids).

#Parameters

#spec

#edges

object[] = ...

#id

string = ...

#steps

object[] = ...

#title?

string = ...

#version

number = ...

#Returns

void

#attachRunBundleIntegrity()

attachRunBundleIntegrity(bundle): Promise<{ artifacts: object[]; engine?: { gateState: [string, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints: Record<string, "pending" | "approved">; }][]; idempotency: [string, { artifactKey: string; version: number; }][]; revision: number; stepStatus: [string, "pending" | "running" | "completed" | "failed"][]; }; integrity?: { sha256: string; }; protocolVersion: "1.0.0"; ruleSets: object[]; run: { annotations?: object[]; context?: { forkedFromStepId?: string; parentRunId?: string; parentRunIds?: string[]; pinnedArtifacts?: object[]; }; endedAt?: string; id: string; metadata?: Record<string, JsonValue>; startedAt: string; status: "running" | "completed" | "failed" | "cancelled"; subject?: { accountId?: string; planId?: string; tenantId?: string; userId?: string; }; tags?: string[]; workflowId: string; workflowSnapshot: { edges: object[]; id: string; steps: object[]; title?: string; version: number; }; workflowVersion: number; }; trace: ({ correlationId?: string; id: string; runId: string; stepId: string; ts: string; type: "step_started"; } | { correlationId?: string; error?: { code?: string; message: string; }; id: string; ok: boolean; runId: string; stepId: string; ts: string; type: "step_completed"; } | { artifact: { artifactKey: string; createdAt: string; data?: unknown; pointer?: { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }; typeId: string; version: number; }; correlationId?: string; id: string; idempotencyKey?: string; runId: string; stepId?: string; ts: string; type: "artifact_written"; } | { artifactKey: string; correlationId?: string; fromVersion: number; id: string; idempotencyKey?: string; patch: ({ op: "add"; path: string; value?: unknown; } | { op: "remove"; path: string; } | { op: "replace"; path: string; value?: unknown; } | { from: string; op: "move"; path: string; } | { from: string; op: "copy"; path: string; } | { op: "test"; path: string; value?: unknown; })[]; runId: string; stepId?: string; toVersion: number; ts: string; type: "artifact_patch"; } | { correlationId?: string; cost?: { amount: number; currency: string; }; direction: "request" | "response" | "stream_chunk"; durationMs?: number; id: string; model?: string; payload?: unknown; provider?: string; runId: string; stepId?: string; summary?: string; ts: string; type: "model_io"; usage?: { cachedInputTokens?: number; inputTokens?: number; outputTokens?: number; reasoningTokens?: number; totalTokens?: number; }; } | { args?: unknown; correlationId?: string; id: string; name: string; result?: unknown; runId: string; stepId?: string; ts: string; type: "tool_call"; } | { correlationId?: string; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; reason?: string; runId: string; stepId: string; ts: string; type: "human_gate_requested"; } | { correlationId?: string; decision: "approved" | "rejected" | "edited"; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; note?: string; runId: string; stepId: string; ts: string; type: "human_gate_resolved"; } | { correlationId?: string; id: string; ruleSetId: string; runId: string; snapshot: { id: string; rules: object[]; ruleSchemaId: string; }; stepId?: string; ts: string; type: "rule_changed"; } | { correlationId?: string; id: string; policy: "AUTO" | "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; runId: string; stepId: string; ts: string; type: "policy_changed"; } | { code?: string; correlationId?: string; fatal?: boolean; id: string; message: string; runId: string; stepId?: string; ts: string; type: "error"; } | { correlationId?: string; forkedFromStepId?: string; id: string; parentRunId: string; parentRunIds?: string[]; runId: string; stepId?: string; ts: string; type: "run_forked"; } | { correlationId?: string; id: string; runId: string; stepId?: string; tags?: string[]; text: string; ts: string; type: "annotation"; } | { correlationId?: string; id: string; reason?: string; runId: string; status: "running" | "completed" | "failed" | "cancelled"; stepId?: string; ts: string; type: "run_status_changed"; } | { attributes?: Record<string, unknown>; correlationId?: string; id: string; kind?: "internal" | "client" | "server" | "producer" | "consumer"; name: string; parentSpanId?: string; runId: string; spanId: string; stepId?: string; ts: string; type: "span_started"; } | { attributes?: Record<string, unknown>; correlationId?: string; durationMs?: number; error?: { code?: string; message: string; }; id: string; runId: string; spanId: string; status?: "ok" | "error"; stepId?: string; ts: string; type: "span_ended"; })[]; }>

Defined in: packages/runtime/src/protocol/bundle.ts:86

#Parameters

#bundle

#artifacts

object[] = ...

#engine?

{ gateState: [string, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints: Record<string, "pending" | "approved">; }][]; idempotency: [string, { artifactKey: string; version: number; }][]; revision: number; stepStatus: [string, "pending" | "running" | "completed" | "failed"][]; } = ...

Optional engine snapshot for faithful rehydration (gates, step status, idempotency).

#engine.gateState

[string, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints: Record<string, "pending" | "approved">; }][] = ...

#engine.idempotency

[string, { artifactKey: string; version: number; }][] = ...

#engine.revision

number = ...

#engine.stepStatus

[string, "pending" | "running" | "completed" | "failed"][] = ...

#integrity?

{ sha256: string; } = ...

Integrity: sha256 of canonical JSON of {run,trace,artifacts,ruleSets,engine?} without this field

#integrity.sha256

string = ...

#protocolVersion

"1.0.0" = ...

#ruleSets

object[] = ...

#run

{ annotations?: object[]; context?: { forkedFromStepId?: string; parentRunId?: string; parentRunIds?: string[]; pinnedArtifacts?: object[]; }; endedAt?: string; id: string; metadata?: Record<string, JsonValue>; startedAt: string; status: "running" | "completed" | "failed" | "cancelled"; subject?: { accountId?: string; planId?: string; tenantId?: string; userId?: string; }; tags?: string[]; workflowId: string; workflowSnapshot: { edges: object[]; id: string; steps: object[]; title?: string; version: number; }; workflowVersion: number; } = RunInstanceSchema

#run.annotations?

object[] = ...

#run.context?

{ forkedFromStepId?: string; parentRunId?: string; parentRunIds?: string[]; pinnedArtifacts?: object[]; } = ...

#run.context.forkedFromStepId?

string = ...

#run.context.parentRunId?

string = ...

Deprecated

Prefer parentRunIds. Kept for back-compat and for the common "fork from a single parent" case. When parentRunIds is set, this MUST equal parentRunIds[0].

#run.context.parentRunIds?

string[] = ...

#run.context.pinnedArtifacts?

object[] = ...

Pinned artifact versions treated as read-only context

#run.endedAt?

string = ...

#run.id

string = ...

#run.metadata?

Record<string, JsonValue> = ...

JSON-only host metadata kept with the run snapshot. Avoid secrets.

#run.startedAt

string = ...

#run.status

"running" | "completed" | "failed" | "cancelled" = ...

#run.subject?

{ accountId?: string; planId?: string; tenantId?: string; userId?: string; } = ...

Host-provided subject/account attribution for telemetry, quotas, and billing.

#run.subject.accountId?

string = ...

#run.subject.planId?

string = ...

#run.subject.tenantId?

string = ...

#run.subject.userId?

string = ...

#run.tags?

string[] = ...

Tags for organizing learning iterations

#run.workflowId

string = ...

#run.workflowSnapshot

{ edges: object[]; id: string; steps: object[]; title?: string; version: number; } = WorkflowSpecSchema

Snapshot of workflow at run start

#run.workflowSnapshot.edges

object[] = ...

#run.workflowSnapshot.id

string = ...

#run.workflowSnapshot.steps

object[] = ...

#run.workflowSnapshot.title?

string = ...

#run.workflowSnapshot.version

number = ...

#run.workflowVersion

number = ...

#trace

({ correlationId?: string; id: string; runId: string; stepId: string; ts: string; type: "step_started"; } | { correlationId?: string; error?: { code?: string; message: string; }; id: string; ok: boolean; runId: string; stepId: string; ts: string; type: "step_completed"; } | { artifact: { artifactKey: string; createdAt: string; data?: unknown; pointer?: { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }; typeId: string; version: number; }; correlationId?: string; id: string; idempotencyKey?: string; runId: string; stepId?: string; ts: string; type: "artifact_written"; } | { artifactKey: string; correlationId?: string; fromVersion: number; id: string; idempotencyKey?: string; patch: ({ op: "add"; path: string; value?: unknown; } | { op: "remove"; path: string; } | { op: "replace"; path: string; value?: unknown; } | { from: string; op: "move"; path: string; } | { from: string; op: "copy"; path: string; } | { op: "test"; path: string; value?: unknown; })[]; runId: string; stepId?: string; toVersion: number; ts: string; type: "artifact_patch"; } | { correlationId?: string; cost?: { amount: number; currency: string; }; direction: "request" | "response" | "stream_chunk"; durationMs?: number; id: string; model?: string; payload?: unknown; provider?: string; runId: string; stepId?: string; summary?: string; ts: string; type: "model_io"; usage?: { cachedInputTokens?: number; inputTokens?: number; outputTokens?: number; reasoningTokens?: number; totalTokens?: number; }; } | { args?: unknown; correlationId?: string; id: string; name: string; result?: unknown; runId: string; stepId?: string; ts: string; type: "tool_call"; } | { correlationId?: string; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; reason?: string; runId: string; stepId: string; ts: string; type: "human_gate_requested"; } | { correlationId?: string; decision: "approved" | "rejected" | "edited"; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; note?: string; runId: string; stepId: string; ts: string; type: "human_gate_resolved"; } | { correlationId?: string; id: string; ruleSetId: string; runId: string; snapshot: { id: string; rules: object[]; ruleSchemaId: string; }; stepId?: string; ts: string; type: "rule_changed"; } | { correlationId?: string; id: string; policy: "AUTO" | "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; runId: string; stepId: string; ts: string; type: "policy_changed"; } | { code?: string; correlationId?: string; fatal?: boolean; id: string; message: string; runId: string; stepId?: string; ts: string; type: "error"; } | { correlationId?: string; forkedFromStepId?: string; id: string; parentRunId: string; parentRunIds?: string[]; runId: string; stepId?: string; ts: string; type: "run_forked"; } | { correlationId?: string; id: string; runId: string; stepId?: string; tags?: string[]; text: string; ts: string; type: "annotation"; } | { correlationId?: string; id: string; reason?: string; runId: string; status: "running" | "completed" | "failed" | "cancelled"; stepId?: string; ts: string; type: "run_status_changed"; } | { attributes?: Record<string, unknown>; correlationId?: string; id: string; kind?: "internal" | "client" | "server" | "producer" | "consumer"; name: string; parentSpanId?: string; runId: string; spanId: string; stepId?: string; ts: string; type: "span_started"; } | { attributes?: Record<string, unknown>; correlationId?: string; durationMs?: number; error?: { code?: string; message: string; }; id: string; runId: string; spanId: string; status?: "ok" | "error"; stepId?: string; ts: string; type: "span_ended"; })[] = ...

#Returns

Promise<{ artifacts: object[]; engine?: { gateState: [string, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints: Record<string, "pending" | "approved">; }][]; idempotency: [string, { artifactKey: string; version: number; }][]; revision: number; stepStatus: [string, "pending" | "running" | "completed" | "failed"][]; }; integrity?: { sha256: string; }; protocolVersion: "1.0.0"; ruleSets: object[]; run: { annotations?: object[]; context?: { forkedFromStepId?: string; parentRunId?: string; parentRunIds?: string[]; pinnedArtifacts?: object[]; }; endedAt?: string; id: string; metadata?: Record<string, JsonValue>; startedAt: string; status: "running" | "completed" | "failed" | "cancelled"; subject?: { accountId?: string; planId?: string; tenantId?: string; userId?: string; }; tags?: string[]; workflowId: string; workflowSnapshot: { edges: object[]; id: string; steps: object[]; title?: string; version: number; }; workflowVersion: number; }; trace: ({ correlationId?: string; id: string; runId: string; stepId: string; ts: string; type: "step_started"; } | { correlationId?: string; error?: { code?: string; message: string; }; id: string; ok: boolean; runId: string; stepId: string; ts: string; type: "step_completed"; } | { artifact: { artifactKey: string; createdAt: string; data?: unknown; pointer?: { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }; typeId: string; version: number; }; correlationId?: string; id: string; idempotencyKey?: string; runId: string; stepId?: string; ts: string; type: "artifact_written"; } | { artifactKey: string; correlationId?: string; fromVersion: number; id: string; idempotencyKey?: string; patch: ({ op: "add"; path: string; value?: unknown; } | { op: "remove"; path: string; } | { op: "replace"; path: string; value?: unknown; } | { from: string; op: "move"; path: string; } | { from: string; op: "copy"; path: string; } | { op: "test"; path: string; value?: unknown; })[]; runId: string; stepId?: string; toVersion: number; ts: string; type: "artifact_patch"; } | { correlationId?: string; cost?: { amount: number; currency: string; }; direction: "request" | "response" | "stream_chunk"; durationMs?: number; id: string; model?: string; payload?: unknown; provider?: string; runId: string; stepId?: string; summary?: string; ts: string; type: "model_io"; usage?: { cachedInputTokens?: number; inputTokens?: number; outputTokens?: number; reasoningTokens?: number; totalTokens?: number; }; } | { args?: unknown; correlationId?: string; id: string; name: string; result?: unknown; runId: string; stepId?: string; ts: string; type: "tool_call"; } | { correlationId?: string; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; reason?: string; runId: string; stepId: string; ts: string; type: "human_gate_requested"; } | { correlationId?: string; decision: "approved" | "rejected" | "edited"; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; note?: string; runId: string; stepId: string; ts: string; type: "human_gate_resolved"; } | { correlationId?: string; id: string; ruleSetId: string; runId: string; snapshot: { id: string; rules: object[]; ruleSchemaId: string; }; stepId?: string; ts: string; type: "rule_changed"; } | { correlationId?: string; id: string; policy: "AUTO" | "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; runId: string; stepId: string; ts: string; type: "policy_changed"; } | { code?: string; correlationId?: string; fatal?: boolean; id: string; message: string; runId: string; stepId?: string; ts: string; type: "error"; } | { correlationId?: string; forkedFromStepId?: string; id: string; parentRunId: string; parentRunIds?: string[]; runId: string; stepId?: string; ts: string; type: "run_forked"; } | { correlationId?: string; id: string; runId: string; stepId?: string; tags?: string[]; text: string; ts: string; type: "annotation"; } | { correlationId?: string; id: string; reason?: string; runId: string; status: "running" | "completed" | "failed" | "cancelled"; stepId?: string; ts: string; type: "run_status_changed"; } | { attributes?: Record<string, unknown>; correlationId?: string; id: string; kind?: "internal" | "client" | "server" | "producer" | "consumer"; name: string; parentSpanId?: string; runId: string; spanId: string; stepId?: string; ts: string; type: "span_started"; } | { attributes?: Record<string, unknown>; correlationId?: string; durationMs?: number; error?: { code?: string; message: string; }; id: string; runId: string; spanId: string; status?: "ok" | "error"; stepId?: string; ts: string; type: "span_ended"; })[]; }>

#buildAdjacency()

buildAdjacency(spec): object

Defined in: packages/runtime/src/runtime/graph.ts:5

#Parameters

#spec

#edges

object[] = ...

#id

string = ...

#steps

object[] = ...

#title?

string = ...

#version

number = ...

#Returns

object

#predecessors

predecessors: Map<string, string[]>

#successors

successors: Map<string, string[]>

#buildAgentChildStartInput()

buildAgentChildStartInput(input): StartRunInput

Defined in: packages/runtime/src/host/fork.ts:58

Build a StartRunInput for an agent-of-agents / supervisor child run that has multiple supervising parents. Unlike buildForkStartInput this does not copy parent artifacts or rules — supervisors usually want to compose context explicitly. Pass inheritArtifactsFrom to optionally pull initial artifacts from one chosen parent.

Designed for the agent-of-agents pattern (planner + research worker coordinating on shared state) where the child needs to record more than one supervising parent for cancellation cascades and trace cross-linking.

The resulting RunContextRef.parentRunId is set to parents[0].run.id for legacy readers; parentRunIds carries the full ordered list.

#Parameters

#input

#inheritArtifactsFrom?

RunStoreState

#inheritRulesFrom?

RunStoreState

#metadata?

Record<string, JsonValue>

#parents

readonly RunStoreState[]

#subject?

{ accountId?: string; planId?: string; tenantId?: string; userId?: string; }

#subject.accountId?

string = ...

#subject.planId?

string = ...

#subject.tenantId?

string = ...

#subject.userId?

string = ...

#tags?

string[]

#workflow

{ edges: object[]; id: string; steps: object[]; title?: string; version: number; }

#workflow.edges

object[] = ...

#workflow.id

string = ...

#workflow.steps

object[] = ...

#workflow.title?

string = ...

#workflow.version

number = ...

#Returns

StartRunInput

#buildForkStartInput()

buildForkStartInput(parent, opts?): StartRunInput

Defined in: packages/runtime/src/host/fork.ts:13

Build a StartRunInput that forks from a single parent run, copying the parent's workflow snapshot, artifacts, and rule sets, and stamping a RunContextRef that records the parent linkage in both legacy singular (parentRunId) and plural (parentRunIds) form so downstream tooling can treat the result uniformly with multi-parent agent runs.

#Parameters

#parent

RunStoreState

#opts?

#forkedFromStepId?

string

#tags?

string[]

#Returns

StartRunInput

#buildUserExportBundle()

buildUserExportBundle(bundle, registry, options?): object

Defined in: packages/runtime/src/export/userBundle.ts:37

Produces a shareable bundle: strips engine/idempotency fidelity, removes sensitive payloads from trace, applies per-artifact JSON Pointer redactions registered on SchemaRegistry, and drops run.metadata by default (the host can opt in via keepMetadata: true).

run.metadata is host-controlled JSON. It is not covered by Ajv schemas or exportRedactPaths, so we err on the side of dropping it from user-facing exports to avoid leaking debugging hints, internal ids, or feature flags.

#Parameters

#bundle

#artifacts

object[] = ...

#engine?

{ gateState: [string, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints: Record<string, "pending" | "approved">; }][]; idempotency: [string, { artifactKey: string; version: number; }][]; revision: number; stepStatus: [string, "pending" | "running" | "completed" | "failed"][]; } = ...

Optional engine snapshot for faithful rehydration (gates, step status, idempotency).

#engine.gateState

[string, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints: Record<string, "pending" | "approved">; }][] = ...

#engine.idempotency

[string, { artifactKey: string; version: number; }][] = ...

#engine.revision

number = ...

#engine.stepStatus

[string, "pending" | "running" | "completed" | "failed"][] = ...

#integrity?

{ sha256: string; } = ...

Integrity: sha256 of canonical JSON of {run,trace,artifacts,ruleSets,engine?} without this field

#integrity.sha256

string = ...

#protocolVersion

"1.0.0" = ...

#ruleSets

object[] = ...

#run

{ annotations?: object[]; context?: { forkedFromStepId?: string; parentRunId?: string; parentRunIds?: string[]; pinnedArtifacts?: object[]; }; endedAt?: string; id: string; metadata?: Record<string, JsonValue>; startedAt: string; status: "running" | "completed" | "failed" | "cancelled"; subject?: { accountId?: string; planId?: string; tenantId?: string; userId?: string; }; tags?: string[]; workflowId: string; workflowSnapshot: { edges: object[]; id: string; steps: object[]; title?: string; version: number; }; workflowVersion: number; } = RunInstanceSchema

#run.annotations?

object[] = ...

#run.context?

{ forkedFromStepId?: string; parentRunId?: string; parentRunIds?: string[]; pinnedArtifacts?: object[]; } = ...

#run.context.forkedFromStepId?

string = ...

#run.context.parentRunId?

string = ...

Deprecated

Prefer parentRunIds. Kept for back-compat and for the common "fork from a single parent" case. When parentRunIds is set, this MUST equal parentRunIds[0].

#run.context.parentRunIds?

string[] = ...

#run.context.pinnedArtifacts?

object[] = ...

Pinned artifact versions treated as read-only context

#run.endedAt?

string = ...

#run.id

string = ...

#run.metadata?

Record<string, JsonValue> = ...

JSON-only host metadata kept with the run snapshot. Avoid secrets.

#run.startedAt

string = ...

#run.status

"running" | "completed" | "failed" | "cancelled" = ...

#run.subject?

{ accountId?: string; planId?: string; tenantId?: string; userId?: string; } = ...

Host-provided subject/account attribution for telemetry, quotas, and billing.

#run.subject.accountId?

string = ...

#run.subject.planId?

string = ...

#run.subject.tenantId?

string = ...

#run.subject.userId?

string = ...

#run.tags?

string[] = ...

Tags for organizing learning iterations

#run.workflowId

string = ...

#run.workflowSnapshot

{ edges: object[]; id: string; steps: object[]; title?: string; version: number; } = WorkflowSpecSchema

Snapshot of workflow at run start

#run.workflowSnapshot.edges

object[] = ...

#run.workflowSnapshot.id

string = ...

#run.workflowSnapshot.steps

object[] = ...

#run.workflowSnapshot.title?

string = ...

#run.workflowSnapshot.version

number = ...

#run.workflowVersion

number = ...

#trace

({ correlationId?: string; id: string; runId: string; stepId: string; ts: string; type: "step_started"; } | { correlationId?: string; error?: { code?: string; message: string; }; id: string; ok: boolean; runId: string; stepId: string; ts: string; type: "step_completed"; } | { artifact: { artifactKey: string; createdAt: string; data?: unknown; pointer?: { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }; typeId: string; version: number; }; correlationId?: string; id: string; idempotencyKey?: string; runId: string; stepId?: string; ts: string; type: "artifact_written"; } | { artifactKey: string; correlationId?: string; fromVersion: number; id: string; idempotencyKey?: string; patch: ({ op: "add"; path: string; value?: unknown; } | { op: "remove"; path: string; } | { op: "replace"; path: string; value?: unknown; } | { from: string; op: "move"; path: string; } | { from: string; op: "copy"; path: string; } | { op: "test"; path: string; value?: unknown; })[]; runId: string; stepId?: string; toVersion: number; ts: string; type: "artifact_patch"; } | { correlationId?: string; cost?: { amount: number; currency: string; }; direction: "request" | "response" | "stream_chunk"; durationMs?: number; id: string; model?: string; payload?: unknown; provider?: string; runId: string; stepId?: string; summary?: string; ts: string; type: "model_io"; usage?: { cachedInputTokens?: number; inputTokens?: number; outputTokens?: number; reasoningTokens?: number; totalTokens?: number; }; } | { args?: unknown; correlationId?: string; id: string; name: string; result?: unknown; runId: string; stepId?: string; ts: string; type: "tool_call"; } | { correlationId?: string; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; reason?: string; runId: string; stepId: string; ts: string; type: "human_gate_requested"; } | { correlationId?: string; decision: "approved" | "rejected" | "edited"; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; note?: string; runId: string; stepId: string; ts: string; type: "human_gate_resolved"; } | { correlationId?: string; id: string; ruleSetId: string; runId: string; snapshot: { id: string; rules: object[]; ruleSchemaId: string; }; stepId?: string; ts: string; type: "rule_changed"; } | { correlationId?: string; id: string; policy: "AUTO" | "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; runId: string; stepId: string; ts: string; type: "policy_changed"; } | { code?: string; correlationId?: string; fatal?: boolean; id: string; message: string; runId: string; stepId?: string; ts: string; type: "error"; } | { correlationId?: string; forkedFromStepId?: string; id: string; parentRunId: string; parentRunIds?: string[]; runId: string; stepId?: string; ts: string; type: "run_forked"; } | { correlationId?: string; id: string; runId: string; stepId?: string; tags?: string[]; text: string; ts: string; type: "annotation"; } | { correlationId?: string; id: string; reason?: string; runId: string; status: "running" | "completed" | "failed" | "cancelled"; stepId?: string; ts: string; type: "run_status_changed"; } | { attributes?: Record<string, unknown>; correlationId?: string; id: string; kind?: "internal" | "client" | "server" | "producer" | "consumer"; name: string; parentSpanId?: string; runId: string; spanId: string; stepId?: string; ts: string; type: "span_started"; } | { attributes?: Record<string, unknown>; correlationId?: string; durationMs?: number; error?: { code?: string; message: string; }; id: string; runId: string; spanId: string; status?: "ok" | "error"; stepId?: string; ts: string; type: "span_ended"; })[] = ...

#registry

SchemaRegistry

#options?

#keepMetadata?

boolean

#Returns

#artifacts

artifacts: object[]

#engine?

optional engine?: object

Optional engine snapshot for faithful rehydration (gates, step status, idempotency).

#engine.gateState

gateState: [string, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints: Record<string, "pending" | "approved">; }][]

#engine.idempotency

idempotency: [string, { artifactKey: string; version: number; }][]

#engine.revision

revision: number

#engine.stepStatus

stepStatus: [string, "pending" | "running" | "completed" | "failed"][]

#integrity?

optional integrity?: object

Integrity: sha256 of canonical JSON of {run,trace,artifacts,ruleSets,engine?} without this field

#integrity.sha256

sha256: string

#protocolVersion

protocolVersion: "1.0.0"

#ruleSets

ruleSets: object[]

#run

run: object = RunInstanceSchema

#run.annotations?

optional annotations?: object[]

#run.context?

optional context?: object

#run.context.forkedFromStepId?

optional forkedFromStepId?: string

#run.context.parentRunId?

optional parentRunId?: string

#Deprecated

Prefer parentRunIds. Kept for back-compat and for the common "fork from a single parent" case. When parentRunIds is set, this MUST equal parentRunIds[0].

#run.context.parentRunIds?

optional parentRunIds?: string[]

#run.context.pinnedArtifacts?

optional pinnedArtifacts?: object[]

Pinned artifact versions treated as read-only context

#run.endedAt?

optional endedAt?: string

#run.id

id: string

#run.metadata?

optional metadata?: Record<string, JsonValue>

JSON-only host metadata kept with the run snapshot. Avoid secrets.

#run.startedAt

startedAt: string

#run.status

status: "running" | "completed" | "failed" | "cancelled"

#run.subject?

optional subject?: object

Host-provided subject/account attribution for telemetry, quotas, and billing.

#run.subject.accountId?

optional accountId?: string

#run.subject.planId?

optional planId?: string

#run.subject.tenantId?

optional tenantId?: string

#run.subject.userId?

optional userId?: string

#run.tags?

optional tags?: string[]

Tags for organizing learning iterations

#run.workflowId

workflowId: string

#run.workflowSnapshot

workflowSnapshot: object = WorkflowSpecSchema

Snapshot of workflow at run start

#run.workflowSnapshot.edges

edges: object[]

#run.workflowSnapshot.id

id: string

#run.workflowSnapshot.steps

steps: object[]

#run.workflowSnapshot.title?

optional title?: string

#run.workflowSnapshot.version

version: number

#run.workflowVersion

workflowVersion: number

#trace

trace: ({ correlationId?: string; id: string; runId: string; stepId: string; ts: string; type: "step_started"; } | { correlationId?: string; error?: { code?: string; message: string; }; id: string; ok: boolean; runId: string; stepId: string; ts: string; type: "step_completed"; } | { artifact: { artifactKey: string; createdAt: string; data?: unknown; pointer?: { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }; typeId: string; version: number; }; correlationId?: string; id: string; idempotencyKey?: string; runId: string; stepId?: string; ts: string; type: "artifact_written"; } | { artifactKey: string; correlationId?: string; fromVersion: number; id: string; idempotencyKey?: string; patch: ({ op: "add"; path: string; value?: unknown; } | { op: "remove"; path: string; } | { op: "replace"; path: string; value?: unknown; } | { from: string; op: "move"; path: string; } | { from: string; op: "copy"; path: string; } | { op: "test"; path: string; value?: unknown; })[]; runId: string; stepId?: string; toVersion: number; ts: string; type: "artifact_patch"; } | { correlationId?: string; cost?: { amount: number; currency: string; }; direction: "request" | "response" | "stream_chunk"; durationMs?: number; id: string; model?: string; payload?: unknown; provider?: string; runId: string; stepId?: string; summary?: string; ts: string; type: "model_io"; usage?: { cachedInputTokens?: number; inputTokens?: number; outputTokens?: number; reasoningTokens?: number; totalTokens?: number; }; } | { args?: unknown; correlationId?: string; id: string; name: string; result?: unknown; runId: string; stepId?: string; ts: string; type: "tool_call"; } | { correlationId?: string; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; reason?: string; runId: string; stepId: string; ts: string; type: "human_gate_requested"; } | { correlationId?: string; decision: "approved" | "rejected" | "edited"; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; note?: string; runId: string; stepId: string; ts: string; type: "human_gate_resolved"; } | { correlationId?: string; id: string; ruleSetId: string; runId: string; snapshot: { id: string; rules: object[]; ruleSchemaId: string; }; stepId?: string; ts: string; type: "rule_changed"; } | { correlationId?: string; id: string; policy: "AUTO" | "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; runId: string; stepId: string; ts: string; type: "policy_changed"; } | { code?: string; correlationId?: string; fatal?: boolean; id: string; message: string; runId: string; stepId?: string; ts: string; type: "error"; } | { correlationId?: string; forkedFromStepId?: string; id: string; parentRunId: string; parentRunIds?: string[]; runId: string; stepId?: string; ts: string; type: "run_forked"; } | { correlationId?: string; id: string; runId: string; stepId?: string; tags?: string[]; text: string; ts: string; type: "annotation"; } | { correlationId?: string; id: string; reason?: string; runId: string; status: "running" | "completed" | "failed" | "cancelled"; stepId?: string; ts: string; type: "run_status_changed"; } | { attributes?: Record<string, unknown>; correlationId?: string; id: string; kind?: "internal" | "client" | "server" | "producer" | "consumer"; name: string; parentSpanId?: string; runId: string; spanId: string; stepId?: string; ts: string; type: "span_started"; } | { attributes?: Record<string, unknown>; correlationId?: string; durationMs?: number; error?: { code?: string; message: string; }; id: string; runId: string; spanId: string; status?: "ok" | "error"; stepId?: string; ts: string; type: "span_ended"; })[]

#canStartStep()

canStartStep(input): { ok: true; } | { ok: false; reason: BlockReason; }

Defined in: packages/runtime/src/runtime/readiness.ts:14

#Parameters

#input

#gateState

Map<string, StepGateState>

#spec

{ edges: object[]; id: string; steps: object[]; title?: string; version: number; }

#spec.edges

object[] = ...

#spec.id

string = ...

#spec.steps

object[] = ...

#spec.title?

string = ...

#spec.version

number = ...

#stepId

string

#stepStatus

Map<string, StepRuntimeStatus>

#Returns

{ ok: true; } | { ok: false; reason: BlockReason; }

#cloneRunStoreState()

cloneRunStoreState(state): RunStoreState

Defined in: packages/runtime/src/runtime/state.ts:22

#Parameters

#state

RunStoreState

#Returns

RunStoreState

#computeRunBundleIntegrity()

computeRunBundleIntegrity(payload): Promise<string>

Defined in: packages/runtime/src/protocol/bundle.ts:64

#Parameters

#payload

#artifacts

object[]

#engine?

{ gateState: [string, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints: Record<string, "pending" | "approved">; }][]; idempotency: [string, { artifactKey: string; version: number; }][]; revision: number; stepStatus: [string, "pending" | "running" | "completed" | "failed"][]; }

#engine.gateState

[string, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints: Record<string, "pending" | "approved">; }][] = ...

#engine.idempotency

[string, { artifactKey: string; version: number; }][] = ...

#engine.revision

number = ...

#engine.stepStatus

[string, "pending" | "running" | "completed" | "failed"][] = ...

#ruleSets

object[]

#run

{ annotations?: object[]; context?: { forkedFromStepId?: string; parentRunId?: string; parentRunIds?: string[]; pinnedArtifacts?: object[]; }; endedAt?: string; id: string; metadata?: Record<string, JsonValue>; startedAt: string; status: "running" | "completed" | "failed" | "cancelled"; subject?: { accountId?: string; planId?: string; tenantId?: string; userId?: string; }; tags?: string[]; workflowId: string; workflowSnapshot: { edges: object[]; id: string; steps: object[]; title?: string; version: number; }; workflowVersion: number; }

#run.annotations?

object[] = ...

#run.context?

{ forkedFromStepId?: string; parentRunId?: string; parentRunIds?: string[]; pinnedArtifacts?: object[]; } = ...

#run.context.forkedFromStepId?

string = ...

#run.context.parentRunId?

string = ...

Deprecated

Prefer parentRunIds. Kept for back-compat and for the common "fork from a single parent" case. When parentRunIds is set, this MUST equal parentRunIds[0].

#run.context.parentRunIds?

string[] = ...

#run.context.pinnedArtifacts?

object[] = ...

Pinned artifact versions treated as read-only context

#run.endedAt?

string = ...

#run.id

string = ...

#run.metadata?

Record<string, JsonValue> = ...

JSON-only host metadata kept with the run snapshot. Avoid secrets.

#run.startedAt

string = ...

#run.status

"running" | "completed" | "failed" | "cancelled" = ...

#run.subject?

{ accountId?: string; planId?: string; tenantId?: string; userId?: string; } = ...

Host-provided subject/account attribution for telemetry, quotas, and billing.

#run.subject.accountId?

string = ...

#run.subject.planId?

string = ...

#run.subject.tenantId?

string = ...

#run.subject.userId?

string = ...

#run.tags?

string[] = ...

Tags for organizing learning iterations

#run.workflowId

string = ...

#run.workflowSnapshot

{ edges: object[]; id: string; steps: object[]; title?: string; version: number; } = WorkflowSpecSchema

Snapshot of workflow at run start

#run.workflowSnapshot.edges

object[] = ...

#run.workflowSnapshot.id

string = ...

#run.workflowSnapshot.steps

object[] = ...

#run.workflowSnapshot.title?

string = ...

#run.workflowSnapshot.version

number = ...

#run.workflowVersion

number = ...

#trace

({ correlationId?: string; id: string; runId: string; stepId: string; ts: string; type: "step_started"; } | { correlationId?: string; error?: { code?: string; message: string; }; id: string; ok: boolean; runId: string; stepId: string; ts: string; type: "step_completed"; } | { artifact: { artifactKey: string; createdAt: string; data?: unknown; pointer?: { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }; typeId: string; version: number; }; correlationId?: string; id: string; idempotencyKey?: string; runId: string; stepId?: string; ts: string; type: "artifact_written"; } | { artifactKey: string; correlationId?: string; fromVersion: number; id: string; idempotencyKey?: string; patch: ({ op: "add"; path: string; value?: unknown; } | { op: "remove"; path: string; } | { op: "replace"; path: string; value?: unknown; } | { from: string; op: "move"; path: string; } | { from: string; op: "copy"; path: string; } | { op: "test"; path: string; value?: unknown; })[]; runId: string; stepId?: string; toVersion: number; ts: string; type: "artifact_patch"; } | { correlationId?: string; cost?: { amount: number; currency: string; }; direction: "request" | "response" | "stream_chunk"; durationMs?: number; id: string; model?: string; payload?: unknown; provider?: string; runId: string; stepId?: string; summary?: string; ts: string; type: "model_io"; usage?: { cachedInputTokens?: number; inputTokens?: number; outputTokens?: number; reasoningTokens?: number; totalTokens?: number; }; } | { args?: unknown; correlationId?: string; id: string; name: string; result?: unknown; runId: string; stepId?: string; ts: string; type: "tool_call"; } | { correlationId?: string; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; reason?: string; runId: string; stepId: string; ts: string; type: "human_gate_requested"; } | { correlationId?: string; decision: "approved" | "rejected" | "edited"; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; note?: string; runId: string; stepId: string; ts: string; type: "human_gate_resolved"; } | { correlationId?: string; id: string; ruleSetId: string; runId: string; snapshot: { id: string; rules: object[]; ruleSchemaId: string; }; stepId?: string; ts: string; type: "rule_changed"; } | { correlationId?: string; id: string; policy: "AUTO" | "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; runId: string; stepId: string; ts: string; type: "policy_changed"; } | { code?: string; correlationId?: string; fatal?: boolean; id: string; message: string; runId: string; stepId?: string; ts: string; type: "error"; } | { correlationId?: string; forkedFromStepId?: string; id: string; parentRunId: string; parentRunIds?: string[]; runId: string; stepId?: string; ts: string; type: "run_forked"; } | { correlationId?: string; id: string; runId: string; stepId?: string; tags?: string[]; text: string; ts: string; type: "annotation"; } | { correlationId?: string; id: string; reason?: string; runId: string; status: "running" | "completed" | "failed" | "cancelled"; stepId?: string; ts: string; type: "run_status_changed"; } | { attributes?: Record<string, unknown>; correlationId?: string; id: string; kind?: "internal" | "client" | "server" | "producer" | "consumer"; name: string; parentSpanId?: string; runId: string; spanId: string; stepId?: string; ts: string; type: "span_started"; } | { attributes?: Record<string, unknown>; correlationId?: string; durationMs?: number; error?: { code?: string; message: string; }; id: string; runId: string; spanId: string; status?: "ok" | "error"; stepId?: string; ts: string; type: "span_ended"; })[]

#Returns

Promise<string>

#deserializeEngineToMaps()

deserializeEngineToMaps(engine): object

Defined in: packages/runtime/src/runtime/hydrate.ts:26

#Parameters

#engine

#gateState

[string, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints: Record<string, "pending" | "approved">; }][] = ...

#idempotency

[string, { artifactKey: string; version: number; }][] = ...

#revision

number = ...

#stepStatus

[string, "pending" | "running" | "completed" | "failed"][] = ...

#Returns

object

#gateState

gateState: Map<string, StepGateState>

#idempotency

idempotency: Map<string, { artifactKey: string; version: number; }>

#revision

revision: number

#stepStatus

stepStatus: Map<string, StepRuntimeStatus>

#deserializeRunBundle()

deserializeRunBundle(json, options?): object

Defined in: packages/runtime/src/protocol/bundle.ts:154

#Parameters

#json

string

#options?

ParseRunBundleOptions

#Returns

#artifacts

artifacts: object[]

#engine?

optional engine?: object

Optional engine snapshot for faithful rehydration (gates, step status, idempotency).

#engine.gateState

gateState: [string, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints: Record<string, "pending" | "approved">; }][]

#engine.idempotency

idempotency: [string, { artifactKey: string; version: number; }][]

#engine.revision

revision: number

#engine.stepStatus

stepStatus: [string, "pending" | "running" | "completed" | "failed"][]

#integrity?

optional integrity?: object

Integrity: sha256 of canonical JSON of {run,trace,artifacts,ruleSets,engine?} without this field

#integrity.sha256

sha256: string

#protocolVersion

protocolVersion: "1.0.0"

#ruleSets

ruleSets: object[]

#run

run: object = RunInstanceSchema

#run.annotations?

optional annotations?: object[]

#run.context?

optional context?: object

#run.context.forkedFromStepId?

optional forkedFromStepId?: string

#run.context.parentRunId?

optional parentRunId?: string

#Deprecated

Prefer parentRunIds. Kept for back-compat and for the common "fork from a single parent" case. When parentRunIds is set, this MUST equal parentRunIds[0].

#run.context.parentRunIds?

optional parentRunIds?: string[]

#run.context.pinnedArtifacts?

optional pinnedArtifacts?: object[]

Pinned artifact versions treated as read-only context

#run.endedAt?

optional endedAt?: string

#run.id

id: string

#run.metadata?

optional metadata?: Record<string, JsonValue>

JSON-only host metadata kept with the run snapshot. Avoid secrets.

#run.startedAt

startedAt: string

#run.status

status: "running" | "completed" | "failed" | "cancelled"

#run.subject?

optional subject?: object

Host-provided subject/account attribution for telemetry, quotas, and billing.

#run.subject.accountId?

optional accountId?: string

#run.subject.planId?

optional planId?: string

#run.subject.tenantId?

optional tenantId?: string

#run.subject.userId?

optional userId?: string

#run.tags?

optional tags?: string[]

Tags for organizing learning iterations

#run.workflowId

workflowId: string

#run.workflowSnapshot

workflowSnapshot: object = WorkflowSpecSchema

Snapshot of workflow at run start

#run.workflowSnapshot.edges

edges: object[]

#run.workflowSnapshot.id

id: string

#run.workflowSnapshot.steps

steps: object[]

#run.workflowSnapshot.title?

optional title?: string

#run.workflowSnapshot.version

version: number

#run.workflowVersion

workflowVersion: number

#trace

trace: ({ correlationId?: string; id: string; runId: string; stepId: string; ts: string; type: "step_started"; } | { correlationId?: string; error?: { code?: string; message: string; }; id: string; ok: boolean; runId: string; stepId: string; ts: string; type: "step_completed"; } | { artifact: { artifactKey: string; createdAt: string; data?: unknown; pointer?: { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }; typeId: string; version: number; }; correlationId?: string; id: string; idempotencyKey?: string; runId: string; stepId?: string; ts: string; type: "artifact_written"; } | { artifactKey: string; correlationId?: string; fromVersion: number; id: string; idempotencyKey?: string; patch: ({ op: "add"; path: string; value?: unknown; } | { op: "remove"; path: string; } | { op: "replace"; path: string; value?: unknown; } | { from: string; op: "move"; path: string; } | { from: string; op: "copy"; path: string; } | { op: "test"; path: string; value?: unknown; })[]; runId: string; stepId?: string; toVersion: number; ts: string; type: "artifact_patch"; } | { correlationId?: string; cost?: { amount: number; currency: string; }; direction: "request" | "response" | "stream_chunk"; durationMs?: number; id: string; model?: string; payload?: unknown; provider?: string; runId: string; stepId?: string; summary?: string; ts: string; type: "model_io"; usage?: { cachedInputTokens?: number; inputTokens?: number; outputTokens?: number; reasoningTokens?: number; totalTokens?: number; }; } | { args?: unknown; correlationId?: string; id: string; name: string; result?: unknown; runId: string; stepId?: string; ts: string; type: "tool_call"; } | { correlationId?: string; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; reason?: string; runId: string; stepId: string; ts: string; type: "human_gate_requested"; } | { correlationId?: string; decision: "approved" | "rejected" | "edited"; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; note?: string; runId: string; stepId: string; ts: string; type: "human_gate_resolved"; } | { correlationId?: string; id: string; ruleSetId: string; runId: string; snapshot: { id: string; rules: object[]; ruleSchemaId: string; }; stepId?: string; ts: string; type: "rule_changed"; } | { correlationId?: string; id: string; policy: "AUTO" | "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; runId: string; stepId: string; ts: string; type: "policy_changed"; } | { code?: string; correlationId?: string; fatal?: boolean; id: string; message: string; runId: string; stepId?: string; ts: string; type: "error"; } | { correlationId?: string; forkedFromStepId?: string; id: string; parentRunId: string; parentRunIds?: string[]; runId: string; stepId?: string; ts: string; type: "run_forked"; } | { correlationId?: string; id: string; runId: string; stepId?: string; tags?: string[]; text: string; ts: string; type: "annotation"; } | { correlationId?: string; id: string; reason?: string; runId: string; status: "running" | "completed" | "failed" | "cancelled"; stepId?: string; ts: string; type: "run_status_changed"; } | { attributes?: Record<string, unknown>; correlationId?: string; id: string; kind?: "internal" | "client" | "server" | "producer" | "consumer"; name: string; parentSpanId?: string; runId: string; spanId: string; stepId?: string; ts: string; type: "span_started"; } | { attributes?: Record<string, unknown>; correlationId?: string; durationMs?: number; error?: { code?: string; message: string; }; id: string; runId: string; spanId: string; status?: "ok" | "error"; stepId?: string; ts: string; type: "span_ended"; })[]

#encodeArtifactPayloadBytes()

encodeArtifactPayloadBytes(value): Uint8Array

Defined in: packages/runtime/src/persistence/artifactStore.ts:113

Encode a JSON-serializable value to canonical UTF-8 bytes for hashing and external storage. Uses key-sorted stringification so the resulting byte stream is stable across runtimes and equal payloads always hash to the same value.

Throws WorkbenchError("INVALID_INPUT") if the value cannot be encoded (functions, symbols, cycles, undefined in arrays).

#Parameters

#value

unknown

#Returns

Uint8Array

#formatAjvErrors()

formatAjvErrors(errors): string

Defined in: packages/runtime/src/schema/registry.ts:118

#Parameters

#errors

ErrorObject<string, Record<string, any>, unknown>[]

#Returns

string

#formatZodError()

formatZodError(err): string

Defined in: packages/runtime/src/errors.ts:57

#Parameters

#err

ZodError

#Returns

string

#getArtifactPayloadHash()

getArtifactPayloadHash(p): string | undefined

Defined in: packages/runtime/src/protocol/artifacts.ts:65

Normalize ArtifactPointer to a single payload hash, preferring payloadHash and falling back to the deprecated sha256 alias. Returns undefined when neither is set (older inline pointers).

#Parameters

#p

{ byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; } | undefined

#Type Literal

{ byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }

#byteLength?

number = ...

#kind

"inline" | "external" = ...

#payloadHash?

string = ...

SHA-256 (lowercase hex) of the canonical JSON encoding of the artifact payload. Preferred name for new pointers. When both payloadHash and sha256 are set, they MUST match.

#ref?

string = ...

For inline: not used. For external: opaque storage key returned by ArtifactStore.put.

#sha256?

string = ...

Deprecated

Prefer payloadHash. Kept as an alias so older bundles round-trip without migration. When both are set they MUST be equal.

undefined

#Returns

string | undefined

#getParentRunIds()

getParentRunIds(ctx): string[]

Defined in: packages/runtime/src/protocol/run.ts:86

Normalize RunContextRef parent linkage into an ordered array of parent run ids. Always returns at least one entry for any value that has passed schema validation.

#Parameters

#ctx

#forkedFromStepId?

string = ...

#parentRunId?

string = ...

Deprecated

Prefer parentRunIds. Kept for back-compat and for the common "fork from a single parent" case. When parentRunIds is set, this MUST equal parentRunIds[0].

#parentRunIds?

string[] = ...

#pinnedArtifacts?

object[] = ...

Pinned artifact versions treated as read-only context

#Returns

string[]

#inferEngineFromTrace()

inferEngineFromTrace(workflow, trace): object

Defined in: packages/runtime/src/runtime/hydrate.ts:45

#Parameters

#workflow

#edges

object[] = ...

#id

string = ...

#steps

object[] = ...

#title?

string = ...

#version

number = ...

#trace

({ correlationId?: string; id: string; runId: string; stepId: string; ts: string; type: "step_started"; } | { correlationId?: string; error?: { code?: string; message: string; }; id: string; ok: boolean; runId: string; stepId: string; ts: string; type: "step_completed"; } | { artifact: { artifactKey: string; createdAt: string; data?: unknown; pointer?: { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }; typeId: string; version: number; }; correlationId?: string; id: string; idempotencyKey?: string; runId: string; stepId?: string; ts: string; type: "artifact_written"; } | { artifactKey: string; correlationId?: string; fromVersion: number; id: string; idempotencyKey?: string; patch: ({ op: "add"; path: string; value?: unknown; } | { op: "remove"; path: string; } | { op: "replace"; path: string; value?: unknown; } | { from: string; op: "move"; path: string; } | { from: string; op: "copy"; path: string; } | { op: "test"; path: string; value?: unknown; })[]; runId: string; stepId?: string; toVersion: number; ts: string; type: "artifact_patch"; } | { correlationId?: string; cost?: { amount: number; currency: string; }; direction: "request" | "response" | "stream_chunk"; durationMs?: number; id: string; model?: string; payload?: unknown; provider?: string; runId: string; stepId?: string; summary?: string; ts: string; type: "model_io"; usage?: { cachedInputTokens?: number; inputTokens?: number; outputTokens?: number; reasoningTokens?: number; totalTokens?: number; }; } | { args?: unknown; correlationId?: string; id: string; name: string; result?: unknown; runId: string; stepId?: string; ts: string; type: "tool_call"; } | { correlationId?: string; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; reason?: string; runId: string; stepId: string; ts: string; type: "human_gate_requested"; } | { correlationId?: string; decision: "approved" | "rejected" | "edited"; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; note?: string; runId: string; stepId: string; ts: string; type: "human_gate_resolved"; } | { correlationId?: string; id: string; ruleSetId: string; runId: string; snapshot: { id: string; rules: object[]; ruleSchemaId: string; }; stepId?: string; ts: string; type: "rule_changed"; } | { correlationId?: string; id: string; policy: "AUTO" | "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; runId: string; stepId: string; ts: string; type: "policy_changed"; } | { code?: string; correlationId?: string; fatal?: boolean; id: string; message: string; runId: string; stepId?: string; ts: string; type: "error"; } | { correlationId?: string; forkedFromStepId?: string; id: string; parentRunId: string; parentRunIds?: string[]; runId: string; stepId?: string; ts: string; type: "run_forked"; } | { correlationId?: string; id: string; runId: string; stepId?: string; tags?: string[]; text: string; ts: string; type: "annotation"; } | { correlationId?: string; id: string; reason?: string; runId: string; status: "running" | "completed" | "failed" | "cancelled"; stepId?: string; ts: string; type: "run_status_changed"; } | { attributes?: Record<string, unknown>; correlationId?: string; id: string; kind?: "internal" | "client" | "server" | "producer" | "consumer"; name: string; parentSpanId?: string; runId: string; spanId: string; stepId?: string; ts: string; type: "span_started"; } | { attributes?: Record<string, unknown>; correlationId?: string; durationMs?: number; error?: { code?: string; message: string; }; id: string; runId: string; spanId: string; status?: "ok" | "error"; stepId?: string; ts: string; type: "span_ended"; })[]

#Returns

object

#gateState

gateState: [string, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints: Record<string, "pending" | "approved">; }][]

#idempotency

idempotency: [string, { artifactKey: string; version: number; }][]

#revision

revision: number

#stepStatus

stepStatus: [string, "pending" | "running" | "completed" | "failed"][]

#listRunBundleMigrations()

listRunBundleMigrations(): readonly RunBundleMigration[]

Defined in: packages/runtime/src/protocol/migrate.ts:104

Test/inspection helper.

#Returns

readonly RunBundleMigration[]

#migrateRunBundle()

migrateRunBundle(input): object

Defined in: packages/runtime/src/protocol/migrate.ts:54

Apply registered migrations until the bundle reaches the current protocol version, then validate it against RunBundleSchema.

Throws WorkbenchError with code UNSUPPORTED_PROTOCOL_VERSION when no migration path exists from the input version, or INVALID_RUN_BUNDLE when the migrated value still fails schema validation.

#Parameters

#input

unknown

#Returns

#artifacts

artifacts: object[]

#engine?

optional engine?: object

Optional engine snapshot for faithful rehydration (gates, step status, idempotency).

#engine.gateState

gateState: [string, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints: Record<string, "pending" | "approved">; }][]

#engine.idempotency

idempotency: [string, { artifactKey: string; version: number; }][]

#engine.revision

revision: number

#engine.stepStatus

stepStatus: [string, "pending" | "running" | "completed" | "failed"][]

#integrity?

optional integrity?: object

Integrity: sha256 of canonical JSON of {run,trace,artifacts,ruleSets,engine?} without this field

#integrity.sha256

sha256: string

#protocolVersion

protocolVersion: "1.0.0"

#ruleSets

ruleSets: object[]

#run

run: object = RunInstanceSchema

#run.annotations?

optional annotations?: object[]

#run.context?

optional context?: object

#run.context.forkedFromStepId?

optional forkedFromStepId?: string

#run.context.parentRunId?

optional parentRunId?: string

#Deprecated

Prefer parentRunIds. Kept for back-compat and for the common "fork from a single parent" case. When parentRunIds is set, this MUST equal parentRunIds[0].

#run.context.parentRunIds?

optional parentRunIds?: string[]

#run.context.pinnedArtifacts?

optional pinnedArtifacts?: object[]

Pinned artifact versions treated as read-only context

#run.endedAt?

optional endedAt?: string

#run.id

id: string

#run.metadata?

optional metadata?: Record<string, JsonValue>

JSON-only host metadata kept with the run snapshot. Avoid secrets.

#run.startedAt

startedAt: string

#run.status

status: "running" | "completed" | "failed" | "cancelled"

#run.subject?

optional subject?: object

Host-provided subject/account attribution for telemetry, quotas, and billing.

#run.subject.accountId?

optional accountId?: string

#run.subject.planId?

optional planId?: string

#run.subject.tenantId?

optional tenantId?: string

#run.subject.userId?

optional userId?: string

#run.tags?

optional tags?: string[]

Tags for organizing learning iterations

#run.workflowId

workflowId: string

#run.workflowSnapshot

workflowSnapshot: object = WorkflowSpecSchema

Snapshot of workflow at run start

#run.workflowSnapshot.edges

edges: object[]

#run.workflowSnapshot.id

id: string

#run.workflowSnapshot.steps

steps: object[]

#run.workflowSnapshot.title?

optional title?: string

#run.workflowSnapshot.version

version: number

#run.workflowVersion

workflowVersion: number

#trace

trace: ({ correlationId?: string; id: string; runId: string; stepId: string; ts: string; type: "step_started"; } | { correlationId?: string; error?: { code?: string; message: string; }; id: string; ok: boolean; runId: string; stepId: string; ts: string; type: "step_completed"; } | { artifact: { artifactKey: string; createdAt: string; data?: unknown; pointer?: { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }; typeId: string; version: number; }; correlationId?: string; id: string; idempotencyKey?: string; runId: string; stepId?: string; ts: string; type: "artifact_written"; } | { artifactKey: string; correlationId?: string; fromVersion: number; id: string; idempotencyKey?: string; patch: ({ op: "add"; path: string; value?: unknown; } | { op: "remove"; path: string; } | { op: "replace"; path: string; value?: unknown; } | { from: string; op: "move"; path: string; } | { from: string; op: "copy"; path: string; } | { op: "test"; path: string; value?: unknown; })[]; runId: string; stepId?: string; toVersion: number; ts: string; type: "artifact_patch"; } | { correlationId?: string; cost?: { amount: number; currency: string; }; direction: "request" | "response" | "stream_chunk"; durationMs?: number; id: string; model?: string; payload?: unknown; provider?: string; runId: string; stepId?: string; summary?: string; ts: string; type: "model_io"; usage?: { cachedInputTokens?: number; inputTokens?: number; outputTokens?: number; reasoningTokens?: number; totalTokens?: number; }; } | { args?: unknown; correlationId?: string; id: string; name: string; result?: unknown; runId: string; stepId?: string; ts: string; type: "tool_call"; } | { correlationId?: string; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; reason?: string; runId: string; stepId: string; ts: string; type: "human_gate_requested"; } | { correlationId?: string; decision: "approved" | "rejected" | "edited"; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; note?: string; runId: string; stepId: string; ts: string; type: "human_gate_resolved"; } | { correlationId?: string; id: string; ruleSetId: string; runId: string; snapshot: { id: string; rules: object[]; ruleSchemaId: string; }; stepId?: string; ts: string; type: "rule_changed"; } | { correlationId?: string; id: string; policy: "AUTO" | "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; runId: string; stepId: string; ts: string; type: "policy_changed"; } | { code?: string; correlationId?: string; fatal?: boolean; id: string; message: string; runId: string; stepId?: string; ts: string; type: "error"; } | { correlationId?: string; forkedFromStepId?: string; id: string; parentRunId: string; parentRunIds?: string[]; runId: string; stepId?: string; ts: string; type: "run_forked"; } | { correlationId?: string; id: string; runId: string; stepId?: string; tags?: string[]; text: string; ts: string; type: "annotation"; } | { correlationId?: string; id: string; reason?: string; runId: string; status: "running" | "completed" | "failed" | "cancelled"; stepId?: string; ts: string; type: "run_status_changed"; } | { attributes?: Record<string, unknown>; correlationId?: string; id: string; kind?: "internal" | "client" | "server" | "producer" | "consumer"; name: string; parentSpanId?: string; runId: string; spanId: string; stepId?: string; ts: string; type: "span_started"; } | { attributes?: Record<string, unknown>; correlationId?: string; durationMs?: number; error?: { code?: string; message: string; }; id: string; runId: string; spanId: string; status?: "ok" | "error"; stepId?: string; ts: string; type: "span_ended"; })[]

#parseRunBundle()

parseRunBundle(input): object

Defined in: packages/runtime/src/protocol/run.ts:149

#Parameters

#input

unknown

#Returns

#artifacts

artifacts: object[]

#engine?

optional engine?: object

Optional engine snapshot for faithful rehydration (gates, step status, idempotency).

#engine.gateState

gateState: [string, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints: Record<string, "pending" | "approved">; }][]

#engine.idempotency

idempotency: [string, { artifactKey: string; version: number; }][]

#engine.revision

revision: number

#engine.stepStatus

stepStatus: [string, "pending" | "running" | "completed" | "failed"][]

#integrity?

optional integrity?: object

Integrity: sha256 of canonical JSON of {run,trace,artifacts,ruleSets,engine?} without this field

#integrity.sha256

sha256: string

#protocolVersion

protocolVersion: "1.0.0"

#ruleSets

ruleSets: object[]

#run

run: object = RunInstanceSchema

#run.annotations?

optional annotations?: object[]

#run.context?

optional context?: object

#run.context.forkedFromStepId?

optional forkedFromStepId?: string

#run.context.parentRunId?

optional parentRunId?: string

#Deprecated

Prefer parentRunIds. Kept for back-compat and for the common "fork from a single parent" case. When parentRunIds is set, this MUST equal parentRunIds[0].

#run.context.parentRunIds?

optional parentRunIds?: string[]

#run.context.pinnedArtifacts?

optional pinnedArtifacts?: object[]

Pinned artifact versions treated as read-only context

#run.endedAt?

optional endedAt?: string

#run.id

id: string

#run.metadata?

optional metadata?: Record<string, JsonValue>

JSON-only host metadata kept with the run snapshot. Avoid secrets.

#run.startedAt

startedAt: string

#run.status

status: "running" | "completed" | "failed" | "cancelled"

#run.subject?

optional subject?: object

Host-provided subject/account attribution for telemetry, quotas, and billing.

#run.subject.accountId?

optional accountId?: string

#run.subject.planId?

optional planId?: string

#run.subject.tenantId?

optional tenantId?: string

#run.subject.userId?

optional userId?: string

#run.tags?

optional tags?: string[]

Tags for organizing learning iterations

#run.workflowId

workflowId: string

#run.workflowSnapshot

workflowSnapshot: object = WorkflowSpecSchema

Snapshot of workflow at run start

#run.workflowSnapshot.edges

edges: object[]

#run.workflowSnapshot.id

id: string

#run.workflowSnapshot.steps

steps: object[]

#run.workflowSnapshot.title?

optional title?: string

#run.workflowSnapshot.version

version: number

#run.workflowVersion

workflowVersion: number

#trace

trace: ({ correlationId?: string; id: string; runId: string; stepId: string; ts: string; type: "step_started"; } | { correlationId?: string; error?: { code?: string; message: string; }; id: string; ok: boolean; runId: string; stepId: string; ts: string; type: "step_completed"; } | { artifact: { artifactKey: string; createdAt: string; data?: unknown; pointer?: { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }; typeId: string; version: number; }; correlationId?: string; id: string; idempotencyKey?: string; runId: string; stepId?: string; ts: string; type: "artifact_written"; } | { artifactKey: string; correlationId?: string; fromVersion: number; id: string; idempotencyKey?: string; patch: ({ op: "add"; path: string; value?: unknown; } | { op: "remove"; path: string; } | { op: "replace"; path: string; value?: unknown; } | { from: string; op: "move"; path: string; } | { from: string; op: "copy"; path: string; } | { op: "test"; path: string; value?: unknown; })[]; runId: string; stepId?: string; toVersion: number; ts: string; type: "artifact_patch"; } | { correlationId?: string; cost?: { amount: number; currency: string; }; direction: "request" | "response" | "stream_chunk"; durationMs?: number; id: string; model?: string; payload?: unknown; provider?: string; runId: string; stepId?: string; summary?: string; ts: string; type: "model_io"; usage?: { cachedInputTokens?: number; inputTokens?: number; outputTokens?: number; reasoningTokens?: number; totalTokens?: number; }; } | { args?: unknown; correlationId?: string; id: string; name: string; result?: unknown; runId: string; stepId?: string; ts: string; type: "tool_call"; } | { correlationId?: string; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; reason?: string; runId: string; stepId: string; ts: string; type: "human_gate_requested"; } | { correlationId?: string; decision: "approved" | "rejected" | "edited"; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; note?: string; runId: string; stepId: string; ts: string; type: "human_gate_resolved"; } | { correlationId?: string; id: string; ruleSetId: string; runId: string; snapshot: { id: string; rules: object[]; ruleSchemaId: string; }; stepId?: string; ts: string; type: "rule_changed"; } | { correlationId?: string; id: string; policy: "AUTO" | "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; runId: string; stepId: string; ts: string; type: "policy_changed"; } | { code?: string; correlationId?: string; fatal?: boolean; id: string; message: string; runId: string; stepId?: string; ts: string; type: "error"; } | { correlationId?: string; forkedFromStepId?: string; id: string; parentRunId: string; parentRunIds?: string[]; runId: string; stepId?: string; ts: string; type: "run_forked"; } | { correlationId?: string; id: string; runId: string; stepId?: string; tags?: string[]; text: string; ts: string; type: "annotation"; } | { correlationId?: string; id: string; reason?: string; runId: string; status: "running" | "completed" | "failed" | "cancelled"; stepId?: string; ts: string; type: "run_status_changed"; } | { attributes?: Record<string, unknown>; correlationId?: string; id: string; kind?: "internal" | "client" | "server" | "producer" | "consumer"; name: string; parentSpanId?: string; runId: string; spanId: string; stepId?: string; ts: string; type: "span_started"; } | { attributes?: Record<string, unknown>; correlationId?: string; durationMs?: number; error?: { code?: string; message: string; }; id: string; runId: string; spanId: string; status?: "ok" | "error"; stepId?: string; ts: string; type: "span_ended"; })[]

#parseRunBundleJson()

parseRunBundleJson(jsonText, options?): object

Defined in: packages/runtime/src/protocol/bundle.ts:130

Parse and validate a run bundle JSON string. Throws WorkbenchError on invalid JSON or schema.

By default, older protocol versions are migrated forward via the registered migrations (see registerRunBundleMigration). Disable with { migrate: false } for strict imports.

#Parameters

#jsonText

string

#options?

ParseRunBundleOptions

#Returns

#artifacts

artifacts: object[]

#engine?

optional engine?: object

Optional engine snapshot for faithful rehydration (gates, step status, idempotency).

#engine.gateState

gateState: [string, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints: Record<string, "pending" | "approved">; }][]

#engine.idempotency

idempotency: [string, { artifactKey: string; version: number; }][]

#engine.revision

revision: number

#engine.stepStatus

stepStatus: [string, "pending" | "running" | "completed" | "failed"][]

#integrity?

optional integrity?: object

Integrity: sha256 of canonical JSON of {run,trace,artifacts,ruleSets,engine?} without this field

#integrity.sha256

sha256: string

#protocolVersion

protocolVersion: "1.0.0"

#ruleSets

ruleSets: object[]

#run

run: object = RunInstanceSchema

#run.annotations?

optional annotations?: object[]

#run.context?

optional context?: object

#run.context.forkedFromStepId?

optional forkedFromStepId?: string

#run.context.parentRunId?

optional parentRunId?: string

#Deprecated

Prefer parentRunIds. Kept for back-compat and for the common "fork from a single parent" case. When parentRunIds is set, this MUST equal parentRunIds[0].

#run.context.parentRunIds?

optional parentRunIds?: string[]

#run.context.pinnedArtifacts?

optional pinnedArtifacts?: object[]

Pinned artifact versions treated as read-only context

#run.endedAt?

optional endedAt?: string

#run.id

id: string

#run.metadata?

optional metadata?: Record<string, JsonValue>

JSON-only host metadata kept with the run snapshot. Avoid secrets.

#run.startedAt

startedAt: string

#run.status

status: "running" | "completed" | "failed" | "cancelled"

#run.subject?

optional subject?: object

Host-provided subject/account attribution for telemetry, quotas, and billing.

#run.subject.accountId?

optional accountId?: string

#run.subject.planId?

optional planId?: string

#run.subject.tenantId?

optional tenantId?: string

#run.subject.userId?

optional userId?: string

#run.tags?

optional tags?: string[]

Tags for organizing learning iterations

#run.workflowId

workflowId: string

#run.workflowSnapshot

workflowSnapshot: object = WorkflowSpecSchema

Snapshot of workflow at run start

#run.workflowSnapshot.edges

edges: object[]

#run.workflowSnapshot.id

id: string

#run.workflowSnapshot.steps

steps: object[]

#run.workflowSnapshot.title?

optional title?: string

#run.workflowSnapshot.version

version: number

#run.workflowVersion

workflowVersion: number

#trace

trace: ({ correlationId?: string; id: string; runId: string; stepId: string; ts: string; type: "step_started"; } | { correlationId?: string; error?: { code?: string; message: string; }; id: string; ok: boolean; runId: string; stepId: string; ts: string; type: "step_completed"; } | { artifact: { artifactKey: string; createdAt: string; data?: unknown; pointer?: { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }; typeId: string; version: number; }; correlationId?: string; id: string; idempotencyKey?: string; runId: string; stepId?: string; ts: string; type: "artifact_written"; } | { artifactKey: string; correlationId?: string; fromVersion: number; id: string; idempotencyKey?: string; patch: ({ op: "add"; path: string; value?: unknown; } | { op: "remove"; path: string; } | { op: "replace"; path: string; value?: unknown; } | { from: string; op: "move"; path: string; } | { from: string; op: "copy"; path: string; } | { op: "test"; path: string; value?: unknown; })[]; runId: string; stepId?: string; toVersion: number; ts: string; type: "artifact_patch"; } | { correlationId?: string; cost?: { amount: number; currency: string; }; direction: "request" | "response" | "stream_chunk"; durationMs?: number; id: string; model?: string; payload?: unknown; provider?: string; runId: string; stepId?: string; summary?: string; ts: string; type: "model_io"; usage?: { cachedInputTokens?: number; inputTokens?: number; outputTokens?: number; reasoningTokens?: number; totalTokens?: number; }; } | { args?: unknown; correlationId?: string; id: string; name: string; result?: unknown; runId: string; stepId?: string; ts: string; type: "tool_call"; } | { correlationId?: string; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; reason?: string; runId: string; stepId: string; ts: string; type: "human_gate_requested"; } | { correlationId?: string; decision: "approved" | "rejected" | "edited"; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; note?: string; runId: string; stepId: string; ts: string; type: "human_gate_resolved"; } | { correlationId?: string; id: string; ruleSetId: string; runId: string; snapshot: { id: string; rules: object[]; ruleSchemaId: string; }; stepId?: string; ts: string; type: "rule_changed"; } | { correlationId?: string; id: string; policy: "AUTO" | "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; runId: string; stepId: string; ts: string; type: "policy_changed"; } | { code?: string; correlationId?: string; fatal?: boolean; id: string; message: string; runId: string; stepId?: string; ts: string; type: "error"; } | { correlationId?: string; forkedFromStepId?: string; id: string; parentRunId: string; parentRunIds?: string[]; runId: string; stepId?: string; ts: string; type: "run_forked"; } | { correlationId?: string; id: string; runId: string; stepId?: string; tags?: string[]; text: string; ts: string; type: "annotation"; } | { correlationId?: string; id: string; reason?: string; runId: string; status: "running" | "completed" | "failed" | "cancelled"; stepId?: string; ts: string; type: "run_status_changed"; } | { attributes?: Record<string, unknown>; correlationId?: string; id: string; kind?: "internal" | "client" | "server" | "producer" | "consumer"; name: string; parentSpanId?: string; runId: string; spanId: string; stepId?: string; ts: string; type: "span_started"; } | { attributes?: Record<string, unknown>; correlationId?: string; durationMs?: number; error?: { code?: string; message: string; }; id: string; runId: string; spanId: string; status?: "ok" | "error"; stepId?: string; ts: string; type: "span_ended"; })[]

#parseTraceEvent()

parseTraceEvent(input): { correlationId?: string; id: string; runId: string; stepId: string; ts: string; type: "step_started"; } | { correlationId?: string; error?: { code?: string; message: string; }; id: string; ok: boolean; runId: string; stepId: string; ts: string; type: "step_completed"; } | { artifact: { artifactKey: string; createdAt: string; data?: unknown; pointer?: { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }; typeId: string; version: number; }; correlationId?: string; id: string; idempotencyKey?: string; runId: string; stepId?: string; ts: string; type: "artifact_written"; } | { artifactKey: string; correlationId?: string; fromVersion: number; id: string; idempotencyKey?: string; patch: ({ op: "add"; path: string; value?: unknown; } | { op: "remove"; path: string; } | { op: "replace"; path: string; value?: unknown; } | { from: string; op: "move"; path: string; } | { from: string; op: "copy"; path: string; } | { op: "test"; path: string; value?: unknown; })[]; runId: string; stepId?: string; toVersion: number; ts: string; type: "artifact_patch"; } | { correlationId?: string; cost?: { amount: number; currency: string; }; direction: "request" | "response" | "stream_chunk"; durationMs?: number; id: string; model?: string; payload?: unknown; provider?: string; runId: string; stepId?: string; summary?: string; ts: string; type: "model_io"; usage?: { cachedInputTokens?: number; inputTokens?: number; outputTokens?: number; reasoningTokens?: number; totalTokens?: number; }; } | { args?: unknown; correlationId?: string; id: string; name: string; result?: unknown; runId: string; stepId?: string; ts: string; type: "tool_call"; } | { correlationId?: string; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; reason?: string; runId: string; stepId: string; ts: string; type: "human_gate_requested"; } | { correlationId?: string; decision: "approved" | "rejected" | "edited"; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; note?: string; runId: string; stepId: string; ts: string; type: "human_gate_resolved"; } | { correlationId?: string; id: string; ruleSetId: string; runId: string; snapshot: { id: string; rules: object[]; ruleSchemaId: string; }; stepId?: string; ts: string; type: "rule_changed"; } | { correlationId?: string; id: string; policy: "AUTO" | "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; runId: string; stepId: string; ts: string; type: "policy_changed"; } | { code?: string; correlationId?: string; fatal?: boolean; id: string; message: string; runId: string; stepId?: string; ts: string; type: "error"; } | { correlationId?: string; forkedFromStepId?: string; id: string; parentRunId: string; parentRunIds?: string[]; runId: string; stepId?: string; ts: string; type: "run_forked"; } | { correlationId?: string; id: string; runId: string; stepId?: string; tags?: string[]; text: string; ts: string; type: "annotation"; } | { correlationId?: string; id: string; reason?: string; runId: string; status: "running" | "completed" | "failed" | "cancelled"; stepId?: string; ts: string; type: "run_status_changed"; } | { attributes?: Record<string, unknown>; correlationId?: string; id: string; kind?: "internal" | "client" | "server" | "producer" | "consumer"; name: string; parentSpanId?: string; runId: string; spanId: string; stepId?: string; ts: string; type: "span_started"; } | { attributes?: Record<string, unknown>; correlationId?: string; durationMs?: number; error?: { code?: string; message: string; }; id: string; runId: string; spanId: string; status?: "ok" | "error"; stepId?: string; ts: string; type: "span_ended"; }

Defined in: packages/runtime/src/protocol/trace.ts:192

#Parameters

#input

unknown

#Returns

#Type Literal

{ correlationId?: string; id: string; runId: string; stepId: string; ts: string; type: "step_started"; }

#Type Literal

{ correlationId?: string; error?: { code?: string; message: string; }; id: string; ok: boolean; runId: string; stepId: string; ts: string; type: "step_completed"; }

#Type Literal

{ artifact: { artifactKey: string; createdAt: string; data?: unknown; pointer?: { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }; typeId: string; version: number; }; correlationId?: string; id: string; idempotencyKey?: string; runId: string; stepId?: string; ts: string; type: "artifact_written"; }

#Type Literal

{ artifactKey: string; correlationId?: string; fromVersion: number; id: string; idempotencyKey?: string; patch: ({ op: "add"; path: string; value?: unknown; } | { op: "remove"; path: string; } | { op: "replace"; path: string; value?: unknown; } | { from: string; op: "move"; path: string; } | { from: string; op: "copy"; path: string; } | { op: "test"; path: string; value?: unknown; })[]; runId: string; stepId?: string; toVersion: number; ts: string; type: "artifact_patch"; }

#Type Literal

{ correlationId?: string; cost?: { amount: number; currency: string; }; direction: "request" | "response" | "stream_chunk"; durationMs?: number; id: string; model?: string; payload?: unknown; provider?: string; runId: string; stepId?: string; summary?: string; ts: string; type: "model_io"; usage?: { cachedInputTokens?: number; inputTokens?: number; outputTokens?: number; reasoningTokens?: number; totalTokens?: number; }; }

#correlationId?

optional correlationId?: string

#cost?

optional cost?: object

#cost.amount

amount: number

#cost.currency

currency: string

#direction

direction: "request" | "response" | "stream_chunk"

#durationMs?

optional durationMs?: number

#id

id: string

#model?

optional model?: string

#payload?

optional payload?: unknown

Redacted or truncated payload

#provider?

optional provider?: string

#runId

runId: string

#stepId?

optional stepId?: string

#summary?

optional summary?: string

#ts

ts: string

#type

type: "model_io"

#usage?

optional usage?: object

#usage.cachedInputTokens?

optional cachedInputTokens?: number

#usage.inputTokens?

optional inputTokens?: number

#usage.outputTokens?

optional outputTokens?: number

#usage.reasoningTokens?

optional reasoningTokens?: number

#usage.totalTokens?

optional totalTokens?: number

#Type Literal

{ args?: unknown; correlationId?: string; id: string; name: string; result?: unknown; runId: string; stepId?: string; ts: string; type: "tool_call"; }

#Type Literal

{ correlationId?: string; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; reason?: string; runId: string; stepId: string; ts: string; type: "human_gate_requested"; }

#Type Literal

{ correlationId?: string; decision: "approved" | "rejected" | "edited"; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; note?: string; runId: string; stepId: string; ts: string; type: "human_gate_resolved"; }

#Type Literal

{ correlationId?: string; id: string; ruleSetId: string; runId: string; snapshot: { id: string; rules: object[]; ruleSchemaId: string; }; stepId?: string; ts: string; type: "rule_changed"; }

#Type Literal

{ correlationId?: string; id: string; policy: "AUTO" | "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; runId: string; stepId: string; ts: string; type: "policy_changed"; }

#Type Literal

{ code?: string; correlationId?: string; fatal?: boolean; id: string; message: string; runId: string; stepId?: string; ts: string; type: "error"; }

#Type Literal

{ correlationId?: string; forkedFromStepId?: string; id: string; parentRunId: string; parentRunIds?: string[]; runId: string; stepId?: string; ts: string; type: "run_forked"; }

#correlationId?

optional correlationId?: string

#forkedFromStepId?

optional forkedFromStepId?: string

#id

id: string

#parentRunId

parentRunId: string

The single parent run id this run forked from. Present for legacy forks. When the child has multiple supervising parents, also set parentRunIds and ensure parentRunIds[0] === parentRunId.

#parentRunIds?

optional parentRunIds?: string[]

Optional plural list of parent run ids for agent-of-agents / multi-supervisor scenarios. When set, MUST be non-empty and parentRunIds[0] MUST equal parentRunId.

#runId

runId: string

#stepId?

optional stepId?: string

#ts

ts: string

#type

type: "run_forked"

#Type Literal

{ correlationId?: string; id: string; runId: string; stepId?: string; tags?: string[]; text: string; ts: string; type: "annotation"; }

#Type Literal

{ correlationId?: string; id: string; reason?: string; runId: string; status: "running" | "completed" | "failed" | "cancelled"; stepId?: string; ts: string; type: "run_status_changed"; }

#Type Literal

{ attributes?: Record<string, unknown>; correlationId?: string; id: string; kind?: "internal" | "client" | "server" | "producer" | "consumer"; name: string; parentSpanId?: string; runId: string; spanId: string; stepId?: string; ts: string; type: "span_started"; }

#Type Literal

{ attributes?: Record<string, unknown>; correlationId?: string; durationMs?: number; error?: { code?: string; message: string; }; id: string; runId: string; spanId: string; status?: "ok" | "error"; stepId?: string; ts: string; type: "span_ended"; }

#parseWorkflowSpec()

parseWorkflowSpec(input): object

Defined in: packages/runtime/src/protocol/workflow.ts:43

#Parameters

#input

unknown

#Returns

object

#edges

edges: object[]

#id

id: string

#steps

steps: object[]

#title?

optional title?: string

#version

version: number

#redactJson()

redactJson(input): unknown

Defined in: packages/runtime/src/schema/redact.ts:7

Very small redactor for export/logging: replaces values at JSON Pointer paths. Paths use JSON Pointer tokens, e.g. ["/apiKey", "/user/email"].

#Parameters

#input

#paths

string[]

#replacement?

unknown

#value

unknown

#Returns

unknown

#registerDemoSchemas()

registerDemoSchemas(registry): void

Defined in: packages/runtime/src/host/demoSchemas.ts:100

#Parameters

#registry

SchemaRegistry

#Returns

void

#registerRunBundleMigration()

registerRunBundleMigration(migration): void

Defined in: packages/runtime/src/protocol/migrate.ts:28

Register a migration. Call once at module load time. The runtime applies registered migrations in dependency order until the bundle reaches WORKBENCH_PROTOCOL_VERSION.

#Parameters

#migration

RunBundleMigration

#Returns

void

#roots()

roots(spec): string[]

Defined in: packages/runtime/src/runtime/graph.ts:22

#Parameters

#spec

#edges

object[] = ...

#id

string = ...

#steps

object[] = ...

#title?

string = ...

#version

number = ...

#Returns

string[]

#runStoreStateFromBundle()

runStoreStateFromBundle(bundle): RunStoreState

Defined in: packages/runtime/src/runtime/hydrate.ts:118

#Parameters

#bundle

#artifacts

object[] = ...

#engine?

{ gateState: [string, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints: Record<string, "pending" | "approved">; }][]; idempotency: [string, { artifactKey: string; version: number; }][]; revision: number; stepStatus: [string, "pending" | "running" | "completed" | "failed"][]; } = ...

Optional engine snapshot for faithful rehydration (gates, step status, idempotency).

#engine.gateState

[string, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints: Record<string, "pending" | "approved">; }][] = ...

#engine.idempotency

[string, { artifactKey: string; version: number; }][] = ...

#engine.revision

number = ...

#engine.stepStatus

[string, "pending" | "running" | "completed" | "failed"][] = ...

#integrity?

{ sha256: string; } = ...

Integrity: sha256 of canonical JSON of {run,trace,artifacts,ruleSets,engine?} without this field

#integrity.sha256

string = ...

#protocolVersion

"1.0.0" = ...

#ruleSets

object[] = ...

#run

{ annotations?: object[]; context?: { forkedFromStepId?: string; parentRunId?: string; parentRunIds?: string[]; pinnedArtifacts?: object[]; }; endedAt?: string; id: string; metadata?: Record<string, JsonValue>; startedAt: string; status: "running" | "completed" | "failed" | "cancelled"; subject?: { accountId?: string; planId?: string; tenantId?: string; userId?: string; }; tags?: string[]; workflowId: string; workflowSnapshot: { edges: object[]; id: string; steps: object[]; title?: string; version: number; }; workflowVersion: number; } = RunInstanceSchema

#run.annotations?

object[] = ...

#run.context?

{ forkedFromStepId?: string; parentRunId?: string; parentRunIds?: string[]; pinnedArtifacts?: object[]; } = ...

#run.context.forkedFromStepId?

string = ...

#run.context.parentRunId?

string = ...

Deprecated

Prefer parentRunIds. Kept for back-compat and for the common "fork from a single parent" case. When parentRunIds is set, this MUST equal parentRunIds[0].

#run.context.parentRunIds?

string[] = ...

#run.context.pinnedArtifacts?

object[] = ...

Pinned artifact versions treated as read-only context

#run.endedAt?

string = ...

#run.id

string = ...

#run.metadata?

Record<string, JsonValue> = ...

JSON-only host metadata kept with the run snapshot. Avoid secrets.

#run.startedAt

string = ...

#run.status

"running" | "completed" | "failed" | "cancelled" = ...

#run.subject?

{ accountId?: string; planId?: string; tenantId?: string; userId?: string; } = ...

Host-provided subject/account attribution for telemetry, quotas, and billing.

#run.subject.accountId?

string = ...

#run.subject.planId?

string = ...

#run.subject.tenantId?

string = ...

#run.subject.userId?

string = ...

#run.tags?

string[] = ...

Tags for organizing learning iterations

#run.workflowId

string = ...

#run.workflowSnapshot

{ edges: object[]; id: string; steps: object[]; title?: string; version: number; } = WorkflowSpecSchema

Snapshot of workflow at run start

#run.workflowSnapshot.edges

object[] = ...

#run.workflowSnapshot.id

string = ...

#run.workflowSnapshot.steps

object[] = ...

#run.workflowSnapshot.title?

string = ...

#run.workflowSnapshot.version

number = ...

#run.workflowVersion

number = ...

#trace

({ correlationId?: string; id: string; runId: string; stepId: string; ts: string; type: "step_started"; } | { correlationId?: string; error?: { code?: string; message: string; }; id: string; ok: boolean; runId: string; stepId: string; ts: string; type: "step_completed"; } | { artifact: { artifactKey: string; createdAt: string; data?: unknown; pointer?: { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }; typeId: string; version: number; }; correlationId?: string; id: string; idempotencyKey?: string; runId: string; stepId?: string; ts: string; type: "artifact_written"; } | { artifactKey: string; correlationId?: string; fromVersion: number; id: string; idempotencyKey?: string; patch: ({ op: "add"; path: string; value?: unknown; } | { op: "remove"; path: string; } | { op: "replace"; path: string; value?: unknown; } | { from: string; op: "move"; path: string; } | { from: string; op: "copy"; path: string; } | { op: "test"; path: string; value?: unknown; })[]; runId: string; stepId?: string; toVersion: number; ts: string; type: "artifact_patch"; } | { correlationId?: string; cost?: { amount: number; currency: string; }; direction: "request" | "response" | "stream_chunk"; durationMs?: number; id: string; model?: string; payload?: unknown; provider?: string; runId: string; stepId?: string; summary?: string; ts: string; type: "model_io"; usage?: { cachedInputTokens?: number; inputTokens?: number; outputTokens?: number; reasoningTokens?: number; totalTokens?: number; }; } | { args?: unknown; correlationId?: string; id: string; name: string; result?: unknown; runId: string; stepId?: string; ts: string; type: "tool_call"; } | { correlationId?: string; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; reason?: string; runId: string; stepId: string; ts: string; type: "human_gate_requested"; } | { correlationId?: string; decision: "approved" | "rejected" | "edited"; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; note?: string; runId: string; stepId: string; ts: string; type: "human_gate_resolved"; } | { correlationId?: string; id: string; ruleSetId: string; runId: string; snapshot: { id: string; rules: object[]; ruleSchemaId: string; }; stepId?: string; ts: string; type: "rule_changed"; } | { correlationId?: string; id: string; policy: "AUTO" | "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; runId: string; stepId: string; ts: string; type: "policy_changed"; } | { code?: string; correlationId?: string; fatal?: boolean; id: string; message: string; runId: string; stepId?: string; ts: string; type: "error"; } | { correlationId?: string; forkedFromStepId?: string; id: string; parentRunId: string; parentRunIds?: string[]; runId: string; stepId?: string; ts: string; type: "run_forked"; } | { correlationId?: string; id: string; runId: string; stepId?: string; tags?: string[]; text: string; ts: string; type: "annotation"; } | { correlationId?: string; id: string; reason?: string; runId: string; status: "running" | "completed" | "failed" | "cancelled"; stepId?: string; ts: string; type: "run_status_changed"; } | { attributes?: Record<string, unknown>; correlationId?: string; id: string; kind?: "internal" | "client" | "server" | "producer" | "consumer"; name: string; parentSpanId?: string; runId: string; spanId: string; stepId?: string; ts: string; type: "span_started"; } | { attributes?: Record<string, unknown>; correlationId?: string; durationMs?: number; error?: { code?: string; message: string; }; id: string; runId: string; spanId: string; status?: "ok" | "error"; stepId?: string; ts: string; type: "span_ended"; })[] = ...

#Returns

RunStoreState

#serializeEngineFromState()

serializeEngineFromState(state): object

Defined in: packages/runtime/src/runtime/hydrate.ts:14

#Parameters

#state

RunStoreState

#Returns

object

#gateState

gateState: [string, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints: Record<string, "pending" | "approved">; }][]

#idempotency

idempotency: [string, { artifactKey: string; version: number; }][]

#revision

revision: number

#stepStatus

stepStatus: [string, "pending" | "running" | "completed" | "failed"][]

#serializeRunBundle()

serializeRunBundle(bundle): string

Defined in: packages/runtime/src/protocol/bundle.ts:109

#Parameters

#bundle

#artifacts

object[] = ...

#engine?

{ gateState: [string, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints: Record<string, "pending" | "approved">; }][]; idempotency: [string, { artifactKey: string; version: number; }][]; revision: number; stepStatus: [string, "pending" | "running" | "completed" | "failed"][]; } = ...

Optional engine snapshot for faithful rehydration (gates, step status, idempotency).

#engine.gateState

[string, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints: Record<string, "pending" | "approved">; }][] = ...

#engine.idempotency

[string, { artifactKey: string; version: number; }][] = ...

#engine.revision

number = ...

#engine.stepStatus

[string, "pending" | "running" | "completed" | "failed"][] = ...

#integrity?

{ sha256: string; } = ...

Integrity: sha256 of canonical JSON of {run,trace,artifacts,ruleSets,engine?} without this field

#integrity.sha256

string = ...

#protocolVersion

"1.0.0" = ...

#ruleSets

object[] = ...

#run

{ annotations?: object[]; context?: { forkedFromStepId?: string; parentRunId?: string; parentRunIds?: string[]; pinnedArtifacts?: object[]; }; endedAt?: string; id: string; metadata?: Record<string, JsonValue>; startedAt: string; status: "running" | "completed" | "failed" | "cancelled"; subject?: { accountId?: string; planId?: string; tenantId?: string; userId?: string; }; tags?: string[]; workflowId: string; workflowSnapshot: { edges: object[]; id: string; steps: object[]; title?: string; version: number; }; workflowVersion: number; } = RunInstanceSchema

#run.annotations?

object[] = ...

#run.context?

{ forkedFromStepId?: string; parentRunId?: string; parentRunIds?: string[]; pinnedArtifacts?: object[]; } = ...

#run.context.forkedFromStepId?

string = ...

#run.context.parentRunId?

string = ...

Deprecated

Prefer parentRunIds. Kept for back-compat and for the common "fork from a single parent" case. When parentRunIds is set, this MUST equal parentRunIds[0].

#run.context.parentRunIds?

string[] = ...

#run.context.pinnedArtifacts?

object[] = ...

Pinned artifact versions treated as read-only context

#run.endedAt?

string = ...

#run.id

string = ...

#run.metadata?

Record<string, JsonValue> = ...

JSON-only host metadata kept with the run snapshot. Avoid secrets.

#run.startedAt

string = ...

#run.status

"running" | "completed" | "failed" | "cancelled" = ...

#run.subject?

{ accountId?: string; planId?: string; tenantId?: string; userId?: string; } = ...

Host-provided subject/account attribution for telemetry, quotas, and billing.

#run.subject.accountId?

string = ...

#run.subject.planId?

string = ...

#run.subject.tenantId?

string = ...

#run.subject.userId?

string = ...

#run.tags?

string[] = ...

Tags for organizing learning iterations

#run.workflowId

string = ...

#run.workflowSnapshot

{ edges: object[]; id: string; steps: object[]; title?: string; version: number; } = WorkflowSpecSchema

Snapshot of workflow at run start

#run.workflowSnapshot.edges

object[] = ...

#run.workflowSnapshot.id

string = ...

#run.workflowSnapshot.steps

object[] = ...

#run.workflowSnapshot.title?

string = ...

#run.workflowSnapshot.version

number = ...

#run.workflowVersion

number = ...

#trace

({ correlationId?: string; id: string; runId: string; stepId: string; ts: string; type: "step_started"; } | { correlationId?: string; error?: { code?: string; message: string; }; id: string; ok: boolean; runId: string; stepId: string; ts: string; type: "step_completed"; } | { artifact: { artifactKey: string; createdAt: string; data?: unknown; pointer?: { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }; typeId: string; version: number; }; correlationId?: string; id: string; idempotencyKey?: string; runId: string; stepId?: string; ts: string; type: "artifact_written"; } | { artifactKey: string; correlationId?: string; fromVersion: number; id: string; idempotencyKey?: string; patch: ({ op: "add"; path: string; value?: unknown; } | { op: "remove"; path: string; } | { op: "replace"; path: string; value?: unknown; } | { from: string; op: "move"; path: string; } | { from: string; op: "copy"; path: string; } | { op: "test"; path: string; value?: unknown; })[]; runId: string; stepId?: string; toVersion: number; ts: string; type: "artifact_patch"; } | { correlationId?: string; cost?: { amount: number; currency: string; }; direction: "request" | "response" | "stream_chunk"; durationMs?: number; id: string; model?: string; payload?: unknown; provider?: string; runId: string; stepId?: string; summary?: string; ts: string; type: "model_io"; usage?: { cachedInputTokens?: number; inputTokens?: number; outputTokens?: number; reasoningTokens?: number; totalTokens?: number; }; } | { args?: unknown; correlationId?: string; id: string; name: string; result?: unknown; runId: string; stepId?: string; ts: string; type: "tool_call"; } | { correlationId?: string; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; reason?: string; runId: string; stepId: string; ts: string; type: "human_gate_requested"; } | { correlationId?: string; decision: "approved" | "rejected" | "edited"; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; note?: string; runId: string; stepId: string; ts: string; type: "human_gate_resolved"; } | { correlationId?: string; id: string; ruleSetId: string; runId: string; snapshot: { id: string; rules: object[]; ruleSchemaId: string; }; stepId?: string; ts: string; type: "rule_changed"; } | { correlationId?: string; id: string; policy: "AUTO" | "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; runId: string; stepId: string; ts: string; type: "policy_changed"; } | { code?: string; correlationId?: string; fatal?: boolean; id: string; message: string; runId: string; stepId?: string; ts: string; type: "error"; } | { correlationId?: string; forkedFromStepId?: string; id: string; parentRunId: string; parentRunIds?: string[]; runId: string; stepId?: string; ts: string; type: "run_forked"; } | { correlationId?: string; id: string; runId: string; stepId?: string; tags?: string[]; text: string; ts: string; type: "annotation"; } | { correlationId?: string; id: string; reason?: string; runId: string; status: "running" | "completed" | "failed" | "cancelled"; stepId?: string; ts: string; type: "run_status_changed"; } | { attributes?: Record<string, unknown>; correlationId?: string; id: string; kind?: "internal" | "client" | "server" | "producer" | "consumer"; name: string; parentSpanId?: string; runId: string; spanId: string; stepId?: string; ts: string; type: "span_started"; } | { attributes?: Record<string, unknown>; correlationId?: string; durationMs?: number; error?: { code?: string; message: string; }; id: string; runId: string; spanId: string; status?: "ok" | "error"; stepId?: string; ts: string; type: "span_ended"; })[] = ...

#Returns

string

#sha256Hex()

sha256Hex(bytes): Promise<string>

Defined in: packages/runtime/src/persistence/artifactStore.ts:124

Compute a lowercase-hex SHA-256 hash of arbitrary bytes using the platform's WebCrypto implementation (Node 20+, browsers, edge runtimes, Bun). Avoids pulling in a Node-only dependency so the runtime stays environment-agnostic.

#Parameters

#bytes

Uint8Array

#Returns

Promise<string>

#summarizeModelTelemetry()

summarizeModelTelemetry(source, options?): object

Defined in: packages/runtime/src/telemetry/modelTelemetry.ts:230

#Parameters

#source

ModelTelemetrySource | readonly ModelTelemetrySource[]

#options?

ModelTelemetryOptions

#Returns

object

#byModel

byModel: object[]

#byPlan

byPlan: object[]

#byProvider

byProvider: object[]

#byProviderModel

byProviderModel: object[]

#byStep

byStep: object[]

#byTenant

byTenant: object[]

#byUser

byUser: object[]

#entries

entries: object[]

#generatedAt

generatedAt: string

#runIds

runIds: string[]

#totals

totals: object = ModelTelemetryTotalsSchema

#totals.cachedInputTokens

cachedInputTokens: number

#totals.costByCurrency

costByCurrency: Record<string, number>

#totals.durationMs

durationMs: number

#totals.eventCount

eventCount: number

#totals.inputTokens

inputTokens: number

#totals.outputTokens

outputTokens: number

#totals.reasoningTokens

reasoningTokens: number

#totals.totalTokens

totalTokens: number

#traceEventsToOtelSpans()

traceEventsToOtelSpans(events, options?): OtelGenAiSpan[]

Defined in: packages/runtime/src/telemetry/otel.ts:70

Convert a run's trace events into an array of GenAI-flavored OTel spans.

  • span_started opens a span. span_ended closes it. Out-of-order or

unmatched events are tolerated: an unmatched span_started becomes a span with status: "unset" and endTimeIso equal to the latest event timestamp seen in its scope.

  • model_io events with direction === "response" produce a gen_ai.*

child span anchored under the current open span (or under no parent if none is open). Usage and cost map to OTel GenAI semantic conventions.

  • tool_call events become child spans with gen_ai.tool.name.
  • All other events are recorded as span events on the closest open span,

preserving order.

#Parameters

#events

readonly ({ correlationId?: string; id: string; runId: string; stepId: string; ts: string; type: "step_started"; } | { correlationId?: string; error?: { code?: string; message: string; }; id: string; ok: boolean; runId: string; stepId: string; ts: string; type: "step_completed"; } | { artifact: { artifactKey: string; createdAt: string; data?: unknown; pointer?: { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }; typeId: string; version: number; }; correlationId?: string; id: string; idempotencyKey?: string; runId: string; stepId?: string; ts: string; type: "artifact_written"; } | { artifactKey: string; correlationId?: string; fromVersion: number; id: string; idempotencyKey?: string; patch: ({ op: "add"; path: string; value?: unknown; } | { op: "remove"; path: string; } | { op: "replace"; path: string; value?: unknown; } | { from: string; op: "move"; path: string; } | { from: string; op: "copy"; path: string; } | { op: "test"; path: string; value?: unknown; })[]; runId: string; stepId?: string; toVersion: number; ts: string; type: "artifact_patch"; } | { correlationId?: string; cost?: { amount: number; currency: string; }; direction: "request" | "response" | "stream_chunk"; durationMs?: number; id: string; model?: string; payload?: unknown; provider?: string; runId: string; stepId?: string; summary?: string; ts: string; type: "model_io"; usage?: { cachedInputTokens?: number; inputTokens?: number; outputTokens?: number; reasoningTokens?: number; totalTokens?: number; }; } | { args?: unknown; correlationId?: string; id: string; name: string; result?: unknown; runId: string; stepId?: string; ts: string; type: "tool_call"; } | { correlationId?: string; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; reason?: string; runId: string; stepId: string; ts: string; type: "human_gate_requested"; } | { correlationId?: string; decision: "approved" | "rejected" | "edited"; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; note?: string; runId: string; stepId: string; ts: string; type: "human_gate_resolved"; } | { correlationId?: string; id: string; ruleSetId: string; runId: string; snapshot: { id: string; rules: object[]; ruleSchemaId: string; }; stepId?: string; ts: string; type: "rule_changed"; } | { correlationId?: string; id: string; policy: "AUTO" | "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; runId: string; stepId: string; ts: string; type: "policy_changed"; } | { code?: string; correlationId?: string; fatal?: boolean; id: string; message: string; runId: string; stepId?: string; ts: string; type: "error"; } | { correlationId?: string; forkedFromStepId?: string; id: string; parentRunId: string; parentRunIds?: string[]; runId: string; stepId?: string; ts: string; type: "run_forked"; } | { correlationId?: string; id: string; runId: string; stepId?: string; tags?: string[]; text: string; ts: string; type: "annotation"; } | { correlationId?: string; id: string; reason?: string; runId: string; status: "running" | "completed" | "failed" | "cancelled"; stepId?: string; ts: string; type: "run_status_changed"; } | { attributes?: Record<string, unknown>; correlationId?: string; id: string; kind?: "internal" | "client" | "server" | "producer" | "consumer"; name: string; parentSpanId?: string; runId: string; spanId: string; stepId?: string; ts: string; type: "span_started"; } | { attributes?: Record<string, unknown>; correlationId?: string; durationMs?: number; error?: { code?: string; message: string; }; id: string; runId: string; spanId: string; status?: "ok" | "error"; stepId?: string; ts: string; type: "span_ended"; })[]

#options?

#runId?

string

#traceId?

string

#Returns

OtelGenAiSpan[]

#validatedReplaceRuleSet()

validatedReplaceRuleSet(registry, session, ruleSet): void

Defined in: packages/runtime/src/host/validated.ts:22

#Parameters

#registry

SchemaRegistry

#session

WorkbenchSession

#ruleSet

#id

string = ...

#rules

object[] = ...

#ruleSchemaId

string = ...

Registry key for JSON Schema used to validate each rule payload

#Returns

void

#validatedWriteArtifact()

validatedWriteArtifact(registry, session, input): object

Defined in: packages/runtime/src/host/validated.ts:7

#Parameters

#registry

SchemaRegistry

#session

WorkbenchSession

#input

#artifactKey

string

#data

unknown

#idempotencyKey?

string

#typeId

string

#Returns

#artifactKey

artifactKey: string

#createdAt

createdAt: string

#data?

optional data?: unknown

Inline snapshot for small artifacts; omit when using pointer

#pointer?

optional pointer?: object

#pointer.byteLength?

optional byteLength?: number

#pointer.kind

kind: "inline" | "external"

#pointer.payloadHash?

optional payloadHash?: string

SHA-256 (lowercase hex) of the canonical JSON encoding of the artifact payload. Preferred name for new pointers. When both payloadHash and sha256 are set, they MUST match.

#pointer.ref?

optional ref?: string

For inline: not used. For external: opaque storage key returned by ArtifactStore.put.

#pointer.sha256?

optional sha256?: string

#Deprecated

Prefer payloadHash. Kept as an alias so older bundles round-trip without migration. When both are set they MUST be equal.

#typeId

typeId: string

#version

version: number

#verifyRunBundleIntegrity()

verifyRunBundleIntegrity(bundle): Promise<boolean>

Defined in: packages/runtime/src/protocol/bundle.ts:97

#Parameters

#bundle

#artifacts

object[] = ...

#engine?

{ gateState: [string, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints: Record<string, "pending" | "approved">; }][]; idempotency: [string, { artifactKey: string; version: number; }][]; revision: number; stepStatus: [string, "pending" | "running" | "completed" | "failed"][]; } = ...

Optional engine snapshot for faithful rehydration (gates, step status, idempotency).

#engine.gateState

[string, { after: "pending" | "approved"; before: "pending" | "approved"; checkpoints: Record<string, "pending" | "approved">; }][] = ...

#engine.idempotency

[string, { artifactKey: string; version: number; }][] = ...

#engine.revision

number = ...

#engine.stepStatus

[string, "pending" | "running" | "completed" | "failed"][] = ...

#integrity?

{ sha256: string; } = ...

Integrity: sha256 of canonical JSON of {run,trace,artifacts,ruleSets,engine?} without this field

#integrity.sha256

string = ...

#protocolVersion

"1.0.0" = ...

#ruleSets

object[] = ...

#run

{ annotations?: object[]; context?: { forkedFromStepId?: string; parentRunId?: string; parentRunIds?: string[]; pinnedArtifacts?: object[]; }; endedAt?: string; id: string; metadata?: Record<string, JsonValue>; startedAt: string; status: "running" | "completed" | "failed" | "cancelled"; subject?: { accountId?: string; planId?: string; tenantId?: string; userId?: string; }; tags?: string[]; workflowId: string; workflowSnapshot: { edges: object[]; id: string; steps: object[]; title?: string; version: number; }; workflowVersion: number; } = RunInstanceSchema

#run.annotations?

object[] = ...

#run.context?

{ forkedFromStepId?: string; parentRunId?: string; parentRunIds?: string[]; pinnedArtifacts?: object[]; } = ...

#run.context.forkedFromStepId?

string = ...

#run.context.parentRunId?

string = ...

Deprecated

Prefer parentRunIds. Kept for back-compat and for the common "fork from a single parent" case. When parentRunIds is set, this MUST equal parentRunIds[0].

#run.context.parentRunIds?

string[] = ...

#run.context.pinnedArtifacts?

object[] = ...

Pinned artifact versions treated as read-only context

#run.endedAt?

string = ...

#run.id

string = ...

#run.metadata?

Record<string, JsonValue> = ...

JSON-only host metadata kept with the run snapshot. Avoid secrets.

#run.startedAt

string = ...

#run.status

"running" | "completed" | "failed" | "cancelled" = ...

#run.subject?

{ accountId?: string; planId?: string; tenantId?: string; userId?: string; } = ...

Host-provided subject/account attribution for telemetry, quotas, and billing.

#run.subject.accountId?

string = ...

#run.subject.planId?

string = ...

#run.subject.tenantId?

string = ...

#run.subject.userId?

string = ...

#run.tags?

string[] = ...

Tags for organizing learning iterations

#run.workflowId

string = ...

#run.workflowSnapshot

{ edges: object[]; id: string; steps: object[]; title?: string; version: number; } = WorkflowSpecSchema

Snapshot of workflow at run start

#run.workflowSnapshot.edges

object[] = ...

#run.workflowSnapshot.id

string = ...

#run.workflowSnapshot.steps

object[] = ...

#run.workflowSnapshot.title?

string = ...

#run.workflowSnapshot.version

number = ...

#run.workflowVersion

number = ...

#trace

({ correlationId?: string; id: string; runId: string; stepId: string; ts: string; type: "step_started"; } | { correlationId?: string; error?: { code?: string; message: string; }; id: string; ok: boolean; runId: string; stepId: string; ts: string; type: "step_completed"; } | { artifact: { artifactKey: string; createdAt: string; data?: unknown; pointer?: { byteLength?: number; kind: "inline" | "external"; payloadHash?: string; ref?: string; sha256?: string; }; typeId: string; version: number; }; correlationId?: string; id: string; idempotencyKey?: string; runId: string; stepId?: string; ts: string; type: "artifact_written"; } | { artifactKey: string; correlationId?: string; fromVersion: number; id: string; idempotencyKey?: string; patch: ({ op: "add"; path: string; value?: unknown; } | { op: "remove"; path: string; } | { op: "replace"; path: string; value?: unknown; } | { from: string; op: "move"; path: string; } | { from: string; op: "copy"; path: string; } | { op: "test"; path: string; value?: unknown; })[]; runId: string; stepId?: string; toVersion: number; ts: string; type: "artifact_patch"; } | { correlationId?: string; cost?: { amount: number; currency: string; }; direction: "request" | "response" | "stream_chunk"; durationMs?: number; id: string; model?: string; payload?: unknown; provider?: string; runId: string; stepId?: string; summary?: string; ts: string; type: "model_io"; usage?: { cachedInputTokens?: number; inputTokens?: number; outputTokens?: number; reasoningTokens?: number; totalTokens?: number; }; } | { args?: unknown; correlationId?: string; id: string; name: string; result?: unknown; runId: string; stepId?: string; ts: string; type: "tool_call"; } | { correlationId?: string; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; reason?: string; runId: string; stepId: string; ts: string; type: "human_gate_requested"; } | { correlationId?: string; decision: "approved" | "rejected" | "edited"; gate: "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; id: string; note?: string; runId: string; stepId: string; ts: string; type: "human_gate_resolved"; } | { correlationId?: string; id: string; ruleSetId: string; runId: string; snapshot: { id: string; rules: object[]; ruleSchemaId: string; }; stepId?: string; ts: string; type: "rule_changed"; } | { correlationId?: string; id: string; policy: "AUTO" | "PAUSE_BEFORE" | "PAUSE_AFTER" | "CHECKPOINT"; runId: string; stepId: string; ts: string; type: "policy_changed"; } | { code?: string; correlationId?: string; fatal?: boolean; id: string; message: string; runId: string; stepId?: string; ts: string; type: "error"; } | { correlationId?: string; forkedFromStepId?: string; id: string; parentRunId: string; parentRunIds?: string[]; runId: string; stepId?: string; ts: string; type: "run_forked"; } | { correlationId?: string; id: string; runId: string; stepId?: string; tags?: string[]; text: string; ts: string; type: "annotation"; } | { correlationId?: string; id: string; reason?: string; runId: string; status: "running" | "completed" | "failed" | "cancelled"; stepId?: string; ts: string; type: "run_status_changed"; } | { attributes?: Record<string, unknown>; correlationId?: string; id: string; kind?: "internal" | "client" | "server" | "producer" | "consumer"; name: string; parentSpanId?: string; runId: string; spanId: string; stepId?: string; ts: string; type: "span_started"; } | { attributes?: Record<string, unknown>; correlationId?: string; durationMs?: number; error?: { code?: string; message: string; }; id: string; runId: string; spanId: string; status?: "ok" | "error"; stepId?: string; ts: string; type: "span_ended"; })[] = ...

#Returns

Promise<boolean>

UI

@llm-workbench/ui — React components for inspecting and operating an LLM Workbench run.

Most consumers only need WorkbenchShell, the complete control surface for a run. WorkflowGraph, MonacoArtifactEditor, and the rule-reorder helpers are also exported for applications composing their own surfaces.

#Type Aliases

#MonacoArtifactEditorProps

MonacoArtifactEditorProps = object

Defined in: packages/ui/src/MonacoArtifactEditor.tsx:4

#Properties

#ariaLabel?

optional ariaLabel?: string

Defined in: packages/ui/src/MonacoArtifactEditor.tsx:10

Optional accessible label forwarded to the editor host.

#onChange

onChange: (next) => void

Defined in: packages/ui/src/MonacoArtifactEditor.tsx:8

Called whenever the editor contents change.

#Parameters

#next

string

#Returns

void

#onSave?

optional onSave?: (next) => void

Defined in: packages/ui/src/MonacoArtifactEditor.tsx:15

Called when the user invokes the editor's formatDocument action (e.g. Cmd/Ctrl+S binds to format-and-save). Defaults to a no-op.

#Parameters

#next

string

#Returns

void

#value

value: string

Defined in: packages/ui/src/MonacoArtifactEditor.tsx:6

Current JSON document being edited.

#WorkbenchShellProps

WorkbenchShellProps = object

Defined in: packages/ui/src/WorkbenchShell.tsx:30

#Properties

#artifactKeys?

optional artifactKeys?: string[]

Defined in: packages/ui/src/WorkbenchShell.tsx:40

Which artifacts appear in the editor dropdown

#onActiveRunChange?

optional onActiveRunChange?: (runId) => void

Defined in: packages/ui/src/WorkbenchShell.tsx:44

Called after a successful bundle import selects a new active run id

#Parameters

#runId

string

#Returns

void

#registry

registry: SchemaRegistry

Defined in: packages/ui/src/WorkbenchShell.tsx:36

Schemas used to validate edited artifact and rule payload JSON.

#repo?

optional repo?: RunRepository

Defined in: packages/ui/src/WorkbenchShell.tsx:38

Optional persistence hook for "Save run"

#ruleSetId?

optional ruleSetId?: string

Defined in: packages/ui/src/WorkbenchShell.tsx:42

Which rule set id to edit

#runId

runId: string

Defined in: packages/ui/src/WorkbenchShell.tsx:34

Run to display; a falsy id leaves state undefined and session null.

#runtime

runtime: WorkbenchRuntime

Defined in: packages/ui/src/WorkbenchShell.tsx:32

Runtime used to read the selected run's state and session.

#useMonacoEditor?

optional useMonacoEditor?: boolean

Defined in: packages/ui/src/WorkbenchShell.tsx:50

Opt-in: render the artifact JSON editor with Monaco instead of a plain textarea. Defaults to false so that consumers who don't need Monaco don't pay the bundle / runtime cost.

#WorkflowGraphProps

WorkflowGraphProps = object

Defined in: packages/ui/src/WorkflowGraph.tsx:22

#Properties

#className?

optional className?: string

Defined in: packages/ui/src/WorkflowGraph.tsx:30

Additional CSS class applied to the graph root element.

#embed?

optional embed?: boolean

Defined in: packages/ui/src/WorkflowGraph.tsx:35

Compact in-page preview (e.g. marketing hero): omit minimap and controls so the React Flow chrome cannot overlap a side-by-side trace column on narrow widths.

#onSelectStep?

optional onSelectStep?: (stepId) => void

Defined in: packages/ui/src/WorkflowGraph.tsx:28

Called with a workflow step id when its React Flow node is selected.

#Parameters

#stepId

string

#Returns

void

#runId

runId: string | null

Defined in: packages/ui/src/WorkflowGraph.tsx:26

Run to visualize; null renders the empty no-run state.

#runtime

runtime: WorkbenchRuntime

Defined in: packages/ui/src/WorkflowGraph.tsx:24

Runtime used to read the selected run's workflow and step statuses.

#Functions

#buildRuleReorderHandler()

buildRuleReorderHandler(opts): (event) => void

Defined in: packages/ui/src/WorkbenchRules.tsx:46

Build the callback wired into <DndContext onDragEnd> for the rule list. Exposed so tests can pass a mock session and confirm reorderRules is called with the expected orderedRuleIds.

#Parameters

#opts

#ruleSet

Pick<{ id: string; rules: object[]; ruleSchemaId: string; }, "id" | "rules"> | undefined

#session

Pick<WorkbenchSession, "reorderRules"> | null

#Returns

(event) => void

#computeReorderedRuleIds()

computeReorderedRuleIds(currentIds, activeId, overId): string[] | null

Defined in: packages/ui/src/WorkbenchRules.tsx:29

Pure helper used by the rule reorder handler. Exported so unit tests can verify the new ordering produced from a drag interaction without driving @dnd-kit's keyboard sensor end-to-end (which is flaky in jsdom).

#Parameters

#currentIds

readonly string[]

#activeId

string

#overId

string

#Returns

string[] | null

#layoutWorkflow()

layoutWorkflow(workflow, statuses): object

Defined in: packages/ui/src/WorkflowGraph.tsx:54

Compute node positions for a workflow using dagre's hierarchical layout. Exported so unit tests can assert deterministic positioning behaviour without rendering React.

#Parameters

#workflow

Pick<WorkflowSpec, "steps" | "edges">

#statuses

ReadonlyMap<string, StepRuntimeStatus>

#Returns

object

#edges

edges: WorkflowEdge[]

#nodes

nodes: WorkflowNode[]

#MonacoArtifactEditor()

MonacoArtifactEditor(props): Element

Defined in: packages/ui/src/MonacoArtifactEditor.tsx:28

Monaco-backed JSON editor with format-on-save and JSON validation enabled.

Lazy-loaded by WorkbenchShell via React.lazy so consumers that don't opt into Monaco never pay its bundle cost. SSR is not supported by @monaco-editor/react out of the box; consumers rendering this component on the server should wrap it in their own client-only boundary (the useMonacoEditor prop on WorkbenchShell already handles this through <Suspense>, but the parent route must still be a client component).

#Parameters

#props

MonacoArtifactEditorProps

#Returns

Element

#WorkbenchShell()

WorkbenchShell(props): Element

Defined in: packages/ui/src/WorkbenchShell.tsx:58

Render the full run control surface: artifact editing, rule management, and the live trace timeline. Set WorkbenchShellProps.useMonacoEditor to opt into the Monaco-based artifact editor.

#Parameters

#props

WorkbenchShellProps

#Returns

Element

#WorkflowGraph()

WorkflowGraph(props): Element

Defined in: packages/ui/src/WorkflowGraph.tsx:127

Render a React Flow visualization of a run's workflow, auto-laid out by layoutWorkflow with dagre and refreshed as the run revision changes.

#Parameters

#props

WorkflowGraphProps

#Returns

Element

Adapters-React

@llm-workbench/adapters-react — React hooks for subscribing components to live LLM Workbench runtime state.

Currently exports useWorkbenchRunRevision, the low-level primitive that @llm-workbench/ui's WorkbenchShell and WorkflowGraph use to re-render when a run's state changes.

#Functions

#useWorkbenchRunRevision()

useWorkbenchRunRevision(runtime, runId): number

Defined in: packages/adapters-react/src/useWorkbenchRunRevision.ts:12

Tiny adapter: subscribe to a run’s monotonic revision counter for React rendering.

#Parameters

#runtime

WorkbenchRuntime

The runtime instance owning the run's state.

#runId

string | null

The run to watch, or null to stay unsubscribed.

#Returns

number

The run's current revision counter, or -1 when runId is null, the run is unknown, or during server-side rendering.

AI SDK

@llm-workbench/ai-sdk — Vercel AI SDK v5 adapters that emit LLM Workbench trace events automatically.

Each traced* helper is a drop-in replacement for the corresponding AI SDK function (generateText, streamText, generateObject, streamObject) and produces correlation-linked model_io request/response/stream_chunk events plus tool_call events on the supplied WorkbenchSession. The AI SDK return value is passed through unchanged.

The runtime keeps no compile-time dependency on ai; this package depends on ai and zod as peer dependencies so apps own which AI SDK version they ship.

#Interfaces

#TraceToolsOptions

Defined in: packages/ai-sdk/src/tools.ts:7

Configuration for traceTools.

#Properties

#correlationId?

optional correlationId?: string

Defined in: packages/ai-sdk/src/tools.ts:15

Shared correlation id. When omitted, each tool execution gets its own generated correlation id. Pass an existing id to link tool calls to a surrounding model_io exchange.

#stepId?

optional stepId?: string

Defined in: packages/ai-sdk/src/tools.ts:9

Workflow step id forwarded with every emitted tool_call trace.

#WorkbenchTraceContext

Defined in: packages/ai-sdk/src/types.ts:33

Cross-cutting tracing context applied to every traced call.

#Properties

#correlationId?

optional correlationId?: string

Defined in: packages/ai-sdk/src/types.ts:40

Explicit correlation id linking request/response/tool/stream_chunk events. One is generated automatically when omitted.

#detail?

optional detail?: "summary" | "full"

Defined in: packages/ai-sdk/src/types.ts:46

"summary" (default) writes the short prompt summary into traces and omits raw payloads. "full" persists prompt/response payloads in traces for engineering/replay exports.

#stepId?

optional stepId?: string

Defined in: packages/ai-sdk/src/types.ts:35

Workflow step id to associate trace events with.

#WriteArtifactOptions

Defined in: packages/ai-sdk/src/types.ts:10

Optional artifact-write hook applied after a successful generation.

When provided, the wrapped traced* helpers will validate the model output against the registry (if registry is passed) and persist it via session.writeArtifact before returning the AI SDK result to the caller.

#Type Parameters

#TResult

TResult = unknown

#Properties

#artifactKey

artifactKey: string

Defined in: packages/ai-sdk/src/types.ts:12

Stable artifact key, e.g. "compiledProfile".

#idempotencyKey?

optional idempotencyKey?: string

Defined in: packages/ai-sdk/src/types.ts:27

Optional idempotency key forwarded to session.writeArtifact.

#registry?

optional registry?: SchemaRegistry

Defined in: packages/ai-sdk/src/types.ts:19

Schema registry used to validate data before writing. When omitted the helper still calls session.writeArtifact but skips validation.

#toData?

optional toData?: (result) => unknown

Defined in: packages/ai-sdk/src/types.ts:25

Project the AI SDK result into the artifact data payload. Defaults to: - result.object for *Object helpers - result.text for *Text helpers

#Parameters

#result

TResult

#Returns

unknown

#typeId

typeId: string

Defined in: packages/ai-sdk/src/types.ts:14

Registered artifact typeId used for schema validation.

#Type Aliases

#TracedGenerateObjectOptions

TracedGenerateObjectOptions = GenerateObjectFirstArg & WorkbenchTraceContext & object

Defined in: packages/ai-sdk/src/generateObject.ts:22

Options for tracedGenerateObject: every option supported by the AI SDK generateObject (including schema, mode, etc.), plus tracing and artifact hooks.

#Type Declaration

#writeArtifact?

optional writeArtifact?: WriteArtifactOptions<GenerateObjectResult>

Validate (when registry is set) and persist result.object as an artifact via session.writeArtifact once the call succeeds.

#TracedGenerateTextOptions

TracedGenerateTextOptions = GenerateTextFirstArg & WorkbenchTraceContext & object

Defined in: packages/ai-sdk/src/generateText.ts:20

Options for tracedGenerateText: every option supported by the AI SDK generateText, plus tracing/artifact hooks.

#Type Declaration

#writeArtifact?

optional writeArtifact?: WriteArtifactOptions<GenerateTextResult>

Optionally validate (when registry is set) and persist the response text as an artifact via session.writeArtifact once the call succeeds.

#TracedStreamObjectOptions

TracedStreamObjectOptions = StreamObjectFirstArg & WorkbenchTraceContext & object

Defined in: packages/ai-sdk/src/streamObject.ts:22

Options for tracedStreamObject: every option supported by the AI SDK streamObject, plus tracing/artifact hooks. Caller-supplied onFinish and onError callbacks are still invoked.

#Type Declaration

#writeArtifact?

optional writeArtifact?: WriteArtifactOptions<{ object: unknown; result: unknown; }>

Validate (when registry is set) and persist the final object as an artifact via session.writeArtifact once the stream finishes.

#TracedStreamTextOptions

TracedStreamTextOptions = StreamTextFirstArg & WorkbenchTraceContext & object

Defined in: packages/ai-sdk/src/streamText.ts:28

Options for tracedStreamText: every option supported by the AI SDK streamText, plus tracing/artifact hooks. Caller-supplied onChunk, onFinish, and onError callbacks are still invoked — we only compose additional behaviour around them.

#Type Declaration

#writeArtifact?

optional writeArtifact?: WriteArtifactOptions<{ result: unknown; text: string; }>

Persist the final concatenated text as an artifact once the stream finishes.

#Functions

#costFromGatewayMetadata()

costFromGatewayMetadata(providerMetadata): { amount: number; currency: string; } | undefined

Defined in: packages/ai-sdk/src/internal.ts:147

Extract a ModelCost from result.providerMetadata. Recognises the Vercel AI Gateway shape (providerMetadata.gateway.cost) where cost may be either { amount, currency }, a number, or a numeric string.

#Parameters

#providerMetadata

unknown

The AI SDK result's providerMetadata field.

#Returns

{ amount: number; currency: string; } | undefined

The extracted cost, or undefined if the shape isn't recognized or the amount isn't a valid non-negative number.

#tracedGenerateObject()

tracedGenerateObject(session, opts): Promise<GenerateObjectResult<unknown>>

Defined in: packages/ai-sdk/src/generateObject.ts:43

Drop-in wrapper around AI SDK generateObject that emits LLM Workbench model_io request/response trace events and optionally validates and persists the structured result.object as a workbench artifact.

#Parameters

#session

WorkbenchSession

The active WorkbenchSession recording trace events.

#opts

TracedGenerateObjectOptions

AI SDK generateObject options plus optional tracing/artifact metadata.

#Returns

Promise<GenerateObjectResult<unknown>>

The original AI SDK generateObject result, unchanged.

#Throws

Rethrows any error from the underlying generateObject call, after recording it as an error-summary model_io response event.

#tracedGenerateText()

tracedGenerateText(session, opts): Promise<GenerateTextResult<ToolSet, unknown>>

Defined in: packages/ai-sdk/src/generateText.ts:50

Drop-in wrapper around AI SDK generateText that emits LLM Workbench trace events automatically:

  • model_io direction: "request" before the call (with prompt summary)
  • model_io direction: "response" after the call (with usage, cost,

provider/model, and durationMs)

  • one tool_call per result.toolCalls (matched against toolResults)
  • one error trace + rethrow if the underlying call rejects

Request and response events share a generated correlationId. The original AI SDK result is returned unchanged.

#Parameters

#session

WorkbenchSession

The active WorkbenchSession recording trace events.

#opts

TracedGenerateTextOptions

AI SDK generateText options plus optional tracing/artifact metadata. stepId, correlationId, detail, and writeArtifact are stripped from the options forwarded to the AI SDK.

#Returns

Promise<GenerateTextResult<ToolSet, unknown>>

The original AI SDK generateText result, unchanged.

#Throws

Rethrows any error from the underlying generateText call, after recording it as an error-summary model_io response event.

#tracedStreamObject()

tracedStreamObject(session, opts): StreamObjectResult

Defined in: packages/ai-sdk/src/streamObject.ts:47

Drop-in wrapper around AI SDK streamObject that emits LLM Workbench traces for the request and the final response (with usage, cost, and durationMs), plus an optional artifact write once the stream resolves.

Returns the original streamObject result so callers iterate partialObjectStream, await object/usage, etc., as if they had called streamObject directly.

#Parameters

#session

WorkbenchSession

The active WorkbenchSession recording trace events.

#opts

TracedStreamObjectOptions

AI SDK streamObject options plus optional tracing/artifact metadata.

#Returns

StreamObjectResult

The original AI SDK streamObject result, unchanged — iterate partialObjectStream or await object/usage exactly as you would from a direct streamObject call.

#tracedStreamText()

tracedStreamText(session, opts): StreamTextResult

Defined in: packages/ai-sdk/src/streamText.ts:51

Drop-in wrapper around AI SDK streamText that emits LLM Workbench traces for the request, debounced stream_chunk events (at most one every ~250 ms), the final response with usage/cost/duration, tool calls, and any error.

Returns the original streamText result so callers iterate textStream, fullStream, or read usage exactly as if they had called streamText directly.

#Parameters

#session

WorkbenchSession

The active WorkbenchSession recording trace events.

#opts

TracedStreamTextOptions

AI SDK streamText options plus optional tracing/artifact metadata. stepId, correlationId, detail, and writeArtifact are stripped from the options forwarded to the AI SDK.

#Returns

StreamTextResult

The original AI SDK streamText result, unchanged — iterate textStream/fullStream or read usage exactly as you would from a direct streamText call.

#traceTools()

traceTools<TTools>(session, tools, options?): TTools

Defined in: packages/ai-sdk/src/tools.ts:45

Wrap an AI SDK tool map so that each tool's execute emits a tool_call trace event on success and an additional error trace + rethrow on failure.

Tools without an execute function are returned unchanged (the AI SDK uses those for client-side tool calls). The wrapped map preserves every other tool property — descriptions, schemas, etc. — so the AI SDK still receives the original tool definition.

#Type Parameters

#TTools

TTools extends Record<string, unknown>

#Parameters

#session

WorkbenchSession

The active WorkbenchSession recording tool_call events.

#tools

TTools

The AI SDK tool map to wrap.

#options?

TraceToolsOptions

Optional stepId/correlationId applied to every emitted trace.

#Returns

TTools

A new tool map with the same shape, each execute wrapped to trace.

#Example

const tools = traceTools(session, {
  getWeather: tool({
    description: "Look up weather",
    inputSchema: z.object({ city: z.string() }),
    execute: async ({ city }) => fetchWeather(city),
  }),
}, { stepId: "research" });

await tracedGenerateText(session, { model, prompt, tools });

MCP

@llm-workbench/mcp — a transport-agnostic Model Context Protocol server that exposes the LLM Workbench runtime over MCP.

Wire any RunRepository (Memory, HTTP, Supabase, …) to createWorkbenchMcpServer and bind the resulting McpServer to a transport. For HTTP runtimes (Next.js Route Handlers, Hono, edge functions) use createWorkbenchMcpHttpHandler for a ready-made (req: Request) => Promise<Response> adapter.

Authentication is the host's responsibility — pass a RunRepository that's already scoped to the caller's tenant.

#Type Aliases

#CreateWorkbenchMcpHttpHandlerOptions

CreateWorkbenchMcpHttpHandlerOptions = object

Defined in: packages/mcp/src/http.ts:4

#Properties

#enableJsonResponse?

optional enableJsonResponse?: boolean

Defined in: packages/mcp/src/http.ts:16

Whether the transport should respond with application/json instead of starting an SSE stream. Defaults to true because LLM Workbench tools are short-lived request/response operations that don't need streaming.

#server

server: McpServer

Defined in: packages/mcp/src/http.ts:9

The MCP server to expose. Typically the value returned by createWorkbenchMcpServer, but any McpServer will work.

#CreateWorkbenchMcpServerOptions

CreateWorkbenchMcpServerOptions = object

Defined in: packages/mcp/src/types.ts:10

Options accepted by createWorkbenchMcpServer.

The package is intentionally transport-agnostic: callers wire any RunRepository implementation (Memory, HTTP, Supabase, …) and the server exposes a fixed surface of LLM Workbench tools and resources over MCP.

#Properties

#listRunIds?

optional listRunIds?: () => Promise<string[]>

Defined in: packages/mcp/src/types.ts:28

Optional override for resource listing. When omitted, the server lists resources by calling runRepository.list() and emitting one runs://{runId} URI per saved run.

Useful when the host can produce ids cheaper than a full list() (e.g. a Postgres view that only fetches id).

#Returns

Promise<string[]>

#name?

optional name?: string

Defined in: packages/mcp/src/types.ts:33

MCP server name advertised on initialize. Defaults to "llm-workbench".

#runRepository

runRepository: RunRepository

Defined in: packages/mcp/src/types.ts:18

Persistence port the server reads from. Calls to list_runs, get_run, and the runs:// resources are dispatched here.

Auth/tenant scoping is the host's responsibility — pass a repository that is already scoped to the caller's tenant.

#version?

optional version?: string

Defined in: packages/mcp/src/types.ts:39

MCP server version advertised on initialize. Defaults to the runtime's WORKBENCH_PROTOCOL_VERSION.

#Functions

#createWorkbenchMcpHttpHandler()

createWorkbenchMcpHttpHandler(options): (req) => Promise<Response>

Defined in: packages/mcp/src/http.ts:34

Build a Web-standard (req: Request) => Promise<Response> handler that speaks MCP over Streamable HTTP. Suitable for Next.js Route Handlers, Hono, Cloudflare Workers, Deno, Bun, or any other runtime that consumes Web standard Request/Response objects.

Each call instantiates a fresh stateless transport so the handler is safe to use in serverless / edge deployments where module state may not persist between invocations. The caller's McpServer is reused across requests (it is stateless) — close it manually if your runtime supports shutdown hooks.

#Parameters

#options

CreateWorkbenchMcpHttpHandlerOptions

The McpServer to expose, plus optional transport settings.

#Returns

A Web-standard (req: Request) => Promise<Response> handler.

(req) => Promise<Response>

#createWorkbenchMcpServer()

createWorkbenchMcpServer(options): McpServer

Defined in: packages/mcp/src/server.ts:88

Build a transport-agnostic LLM Workbench MCP server.

The returned McpServer exposes a fixed surface:

Tools

  • list_runs({ limit? }) — SavedRunMeta[] from the supplied repository.
  • get_run({ runId }) — the serialized RunStoreState for runId.
  • verify_run_integrity({ bundle }) — { ok } indicating whether the

bundle's integrity.sha256 matches its canonical content.

  • validate_run_bundle({ bundle }) — { ok } (with error when invalid)

from running the runtime's structural + schema validators.

Resources

  • runs: listing — every saved run as a runs://{runId} URI.
  • runs://{runId} — the run's full RunBundle JSON (with attached

integrity), suitable for replay or verification.

The server is purely a request-response surface; it does not own a transport. Wire it to a transport via McpServer.connect, or use createWorkbenchMcpHttpHandler for an HTTP adapter.

#Parameters

#options

CreateWorkbenchMcpServerOptions

Repository and optional metadata for the server.

#Returns

McpServer

A transport-agnostic McpServer exposing the fixed tool/resource surface described above.