Workflows and Run records

A Workflow defines permitted steps and transitions. A Run saves the input, state, actions, waits, and evidence for one execution. One workflow can have multiple independent Runs.

Core objects

Object	Host responsibility
Workflow	Define identity, version, entry, steps, and allowed transitions.
Run	Retain the same Run ID when resuming.
Action	Claim the current action, invoke real host capabilities, and report its result.
Wait	Show the proposal and submit the actual decision or required evidence.
Store	Save atomically so concurrent results do not overwrite one another.

Use a new version when changing a definition, and retain definitions referenced by active Runs. Editing prose, state JSON, or a completion label cannot replace a valid transition.

Define the allowed path

import { defineWorkflow, skill, approval, tool } from '@rpamis/comet/runtime';

const workflow = defineWorkflow({
  id: 'report',
  version: '1',
  entry: 'draft',
  steps: {
    draft: skill({ ref: 'draft' }),
    approve: approval({ proposalFrom: 'draft' }),
    publish: tool({ ref: 'publish' }),
  },
  transitions: [
    { from: 'draft', to: 'approve' },
    { from: 'approve', to: 'publish', on: 'approved' },
  ],
});

entry identifies initially ready steps. Keys in steps name graph steps; ref names a host handler. transitions declares permitted paths. Several steps may use one handler while retaining separate execution records. Register workflow with createRuntime and start a Run using its fixed id/version. See the quickstart for a complete runnable example.

Read progress results

After runUntilBlocked, read reason first, then the relevant actions, waits, and business outputs.

reason	Next operation
completed	Inspect business output and the selected path.
`approval-required`	Show the current proposal and collect the user’s decision.
`evidence-required`	Collect and submit the requested evidence.
`executor-required`	Register a host executor that supports the action.
`action-in-flight`	Query the original executor and wait for its result.
`execution-unknown`	Reconcile the original operation before resuming.
failed	Inspect the original Action and error, then handle the known failure.
`action-limit`	The invocation exhausted its action budget; inspect progress before continuing.
cancelled	Stop progression and verify prior operations and stop evidence.
idle	Inspect ready steps, join conditions, and child Runs to understand why no action is available.

inspect reads records without calling models or tools. A business UI should show the current Run, pending Actions/Waits, and the last error so users can choose whether to continue, approve, or reconcile.

Define steps

Import defineWorkflow from @rpamis/comet/runtime, or use a definition object as in the quickstart.

Helper	Work declared
skill	Have the host load and execute a Skill.
tool	Call a host tool or local business function.
approval	Wait for a user decision on the current proposal.
evidence	Wait for declared evidence.
childWorkflow	Start and link a child workflow.

Dependencies determine when actions become ready. Parallel steps may finish in different orders, with explicit join conditions. Loops and branches follow declared transitions; handlers cannot jump outside the graph.

Executors and outcomes

createRuntimeExecutor registers named handlers by step ref. defineRuntimeHandler parses input before execution, avoiding one large function that dispatches on step names. Hosts that claim and report independently can use claim, recordOutcome, and retry. Retain the original Action identity, attempt, input hash, and claim credentials; report results for that execution. Successful outputs also pass Schema and business validation. Report known failures as failures. Exceptions after dispatch or interrupted reporting can mean the operation happened; treat them as unknown. See recovery.

User waits

Decisions bind to the Wait ID and current proposal hash. Changed proposals require a new display and confirmation. Old approvals, approvals from another activation, and invented host approvals cannot authorize the current action. For evidence waits, submit actual evidence; Runtime validates ownership and declared conditions. A finished step, accepted evidence, and a successful external service operation are separate facts and should be shown separately.

Storage and host responsibilities

createMemoryRuntimeStore is suitable for experiments that do not need process recovery. createFileRuntimeStore saves Runs in your chosen directory; a new process registers the same definitions and executors to continue. Runtime does not call models, configure MCP, inject plugin context, or obtain permission for your host. Use Workflow Application for pinned Skills, installation entries, protected business files, and distribution. Continue with executors, parallel steps, child workflows, and business state.

Get started

Build workflows

Approval and validation

Persistence and recovery

Compose and deliver applications

Plugins

Workflows and Run records

Core objects

Define the allowed path

Read progress results

Define steps

Executors and outcomes

User waits

Storage and host responsibilities

​Core objects

​Define the allowed path

​Read progress results

​Define steps

​Executors and outcomes

​User waits

​Storage and host responsibilities

Core objects

Define the allowed path

Read progress results

Define steps

Executors and outcomes

User waits

Storage and host responsibilities