Workflows
Rho workflows run a fixed directed acyclic graph of agent and command nodes. You write the graph in Starlark. Rho evaluates the source and explicit inputs only when you validate or plan. A plan stores a normalized frozen program with one root scope containing typed parameters and the node graph. Run and resume use that program and do not evaluate Starlark or reload agent definitions.
The current runtime executes only a static root scope, identified as s0. Root task instances are qualified by that scope, such as s0.review, in events, status, hooks, and artifact paths. The root closes with a typed result containing its outcome and named exports. Runtime map and iterate controllers and dynamic expansion are not supported.
Plans and runs saved by Rho before 2.15 are not supported. list and the workflow hub still show them, so you can delete them from the hub, but status, run, resume, and cancel fail with an error that names the record. Inspect them with Rho 2.x, or replan from source to run the workflow again.
Use a workflow when a task needs fixed steps, parallel work, typed conditions, durable status, or manual resume. Use rho run for one model task that does not need a graph.
Lifecycle
A workflow moves through a fixed path: source to plan, plan to run, then a terminal outcome. Cancel and recovery only reopen the same frozen run.
Main steps
- Write one or more
.starfiles under the workspace or project root. When a workflow owns helper scripts, local modules, or local agents, put the entry file and those companions in one folder such as.rho/workflows/review/instead of leaving scripts loose under.rho/workflows/. Local agents live in<workflow_dir>/agents/*.md. - Validate the source and inputs.
- Create a frozen plan and inspect its program digest and authority list.
- Start a run by plan ID. The CLI asks for confirmation (or
--yes); the model tool uses normal tool permissions without an extra questionnaire. - Read status and artifact references by run ID.
- Cancel or resume the same frozen run when needed.
Interactive hub
In the chat TUI, run /workflow to start workflows and inspect runs. Saved plans live in a separate browser so old planning receipts do not crowd the list.
Sections
- START -
Start <name>starts a new run in the background, appends the run id to chat context, and returns to chat without starting a model turn. - RUNS -
Watch <state> · <id>opens the DAG watch screen (live or finished). - PLANS -
Saved plansopens the reusable frozen-plan list. Select a plan by name and ID to start it, or pressdto delete it.
Start a workflow by name
Each workspace workflow also gets its own command, named after its folder or file: .rho/workflows/review/workflow.star and .rho/workflows/review.star both start with /workflow:review. Pass inputs as one JSON object after the name:
/workflow:review
/workflow:review {"target": "src", "depth": 2}Omitted inputs use their declared defaults. The run starts in the background, like Start in the hub. The command is in the TUI command palette and in ACP command menus, where /workflow itself is unavailable. In ACP the command ends the prompt without a model reply, and the result reaches the model at your next prompt. When both review.star and review/workflow.star exist, the command refuses to guess; rename one.
Background workflows appear in the activity rail with their name, lifecycle, completed/total task count, active task, and elapsed time. Click a workflow row to open its watch screen while chat is idle; /workflow provides the keyboard path. Rail clicks do not interrupt a turn or dismiss an open form. Finished rows leave the rail when their result is delivered. Tool cards summarize the action, state, and progress; expand a card for IDs and node details.
DAG watch screen
Keep chatting while a run continues. Reopen /workflow and press Enter on a run to watch it without taking ownership of the driver. The left pane draws the complete frozen dependency graph from top to bottom. An arrow runs from each dependency to the node that needs it, and independent nodes share a rank.
| Key | Action |
|---|---|
j or Down | Select the next frozen node |
k or Up | Select the previous frozen node |
h or Left | Select the node to the left on the same rank |
l or Right | Select the node to the right on the same rank |
c | Request stop on a live run |
q | Leave the watch screen without stopping the run |
The graph viewport follows the selected node when the complete graph is larger than its pane. Node labels use · for waiting, ○ for ready, ● for running, ✓ for success, – for skipped, and ✗ for other terminal outcomes. A running node also shows its current activity when available.
The right pane shows details for the selected node. Finished agent answers render as Markdown, while command streams render as text. Use PgUp/PgDn, Home/End, the mouse wheel, or the scrollbar to scroll long output. Drag across the details to copy text. In the graph pane, drag or use the wheel to pan; horizontal scrolling pans sideways.
Cleanup
Press d on a run or on a plan inside Saved plans to delete it after confirmation. Local .star source files are not deleted from disk.
Starting from source removes its launch-only plan after the run has its own frozen graph. Explicit plan operations still save reusable plans. Existing saved plans are preserved; there is no automatic deletion of older plans.
When the run finishes, Rho delivers a completion message to the parent session. The model workflow tool uses the same background contract. See Model tool.
CLI reference
Every stage uses a separate command. Prefer list and status for inspection; use validate and plan before any run.
rho workflow list [--plans|--runs] [--limit N] [--json]
rho workflow validate <FILE> [--input KEY=JSON]...
rho workflow plan <FILE> [--input KEY=JSON]... [--output text|json]
rho workflow run <PLAN_ID> [--yes] [--output text|jsonl]
rho workflow status <RUN_ID> [--output text|json]
rho workflow cancel <RUN_ID>
rho workflow resume <RUN_ID> [--yes] [--recover-uncertain] [--dry-run] [--output text|jsonl]CLI help is the source of truth for supported flags and recovery actions.
List
list prints saved plans and runs for the current workspace. Use --plans or --runs to show one section. --limit caps each section. --json prints one JSON document. Records saved by Rho before 2.15 are reported as warnings on stderr instead of rows.
rho workflow list
rho workflow list --runs --limit 10
rho workflow list --jsonValidate
validate collects the entry source and loaded modules, validates explicit inputs, evaluates build once, and checks the full graph. It checks agent references, schemas, conditions, access declarations, cycles, and planning limits. It does not create a plan or run. It does not start a model provider or load provider credentials. Rho evaluates Starlark in a separate worker with a private framed channel, a wall-time limit, and OS process limits.
rho workflow validate .rho/workflows/review.star \
--input 'target="src"' \
--input 'full=true'Each input after --input has the form KEY=JSON. The outer shell quotes protect the argument. The inner quotes are JSON syntax, so --input 'target="src"' produces the string value src.
Plan
plan performs validation, resolves agents and command executables, normalizes the program, and stores an immutable plan. Its output includes the plan ID, full authority list, source digests, inputs, scheduler limits, and program digest.
rho workflow plan .rho/workflows/review.star \
--input 'target="src"' --output jsonKeep the returned plan ID. A run accepts a plan ID, not a source path.
Run
run checks the stored plan, source digests, current workspace identity, current trust, and current security policy. It does not evaluate Starlark. It copies the frozen program into the run store so later plan removal cannot break resume.
rho workflow run 018f... --output text
rho workflow run 018f... --yes --output jsonlRho asks for confirmation when a terminal can answer. Non-interactive use must pass --yes. Consent applies only to the exact program digest and new run. It is not capability approval.
Status
status reads one durable snapshot. It does not take execution ownership.
rho workflow status 0190... --output jsonYou may use a full run UUID or a unique UUID prefix. Status reports typed node states, current attempts, outcomes, and artifact references. It does not print complete artifacts. JSON status is {"run": ..., "outcome": ...}, where run holds the stored manifest, frozen graph (with program and program_digest), and state with per-scope task maps under scopes.
Cancel
cancel records a cancellation request and notifies the active owner when it can. The owner stops active agents and process trees before it marks them cancelled.
rho workflow cancel 0190...The command waits up to the cancellation acknowledgement limit for the exact request ID. An acknowledged result means the owner stopped active work before it wrote that request's acknowledgement. A pending result includes the request ID and means the bound expired. It does not claim that active work has stopped. Cancelling a completed run returns already_completed without reusing an acknowledgement from an older request.
{"run_id":"...","request_id":"...","cancellation_state":"pending","lifecycle":"running"}If no process owns the run, the durable request stays pending. Rho changes only states that have a safe transition when an owner next opens the run.
Resume
resume accepts only a run ID. It uses the program copied into the run store. It does not accept a new source or new inputs, reload modules or agents, or rerun successful nodes.
rho workflow resume 0190... --yes --output jsonl
rho workflow resume 0190... --recover-uncertain --yes --output jsonl
rho workflow resume 0190... --dry-runRho can start a new attempt for a node that was cleanly cancelled. If an old process ended without a clean ownership record, the run enters needs_recovery. Inspect status, confirm that no prior process remains, and pass --recover-uncertain. Rho does not guess whether uncertain work completed.
A Rho agent node saves its session at every step. After confirmation, such a node continues the same attempt by reopening its saved session, or finishes with the final reply the session already holds. Read-only built-in tool calls that were in flight run again. Every other in-flight call, such as an edit, shell command, network call, or MCP tool, is reported to the agent as interrupted and is not run again. Only Rho agents can continue: command nodes, agents on other runtimes, attempts whose session was never recorded (such as one a crash interrupted before its agent started, or one an earlier Rho started), and runs with a pending cancellation start a new attempt instead.
--dry-run reports what resume would do with each uncertain attempt and changes nothing. With --output jsonl it prints one JSON document.
The top-level rho --resume flag is for chat sessions. It does not resume a workflow.
Authoring reference
Starlark source format, node types, output schemas, templates, and conditions:
Runtime reference
State machine details, digests and resume, permissions, cancellation, artifacts, planning limits, and first-release limits: