atlas-orchestrate

Atlas workflow orchestration

Atlas 0.1.0 is a local, source-only Windows release. ${ATLAS_HOME} means the user's absolute source root; this document contains no machine-specific path. The observer runs at http://127.0.0.1:8321 after the user starts it.

Use a single model call for simple one-step work. Use Atlas for explicit graph structure, bounded review loops, independent model perspectives, coding-agent worktree changes, or human approval.

Required sequence

1. Design YAML with explicit inputs, outputs, routes, and guards.
2. Call atlas_validate_workflow (zero provider calls).
3. Call atlas_save_workflow only when persistence is requested.
4. Call atlas_run_workflow with dry_run: true (zero provider calls and no run directory).
5. Show unresolved model choices, graph shape, guard limits, agent security boundaries, privacy, and cost implications.
6. Call atlas_run_workflow with dry_run: false only after explicit execution intent. Default is synchronous (wait=true); for long graphs pass wait=false to get a run_id immediately after preflight instead of blocking the session (mutually exclusive with persist_as).
7. Call atlas_get_run to inspect a created run, atlas_list_runs to page through runs. If and only if its dynamic status is interrupted, use atlas_resume_run; paused human decisions remain in the local Web UI (which also offers the cancel button for running/waiting runs). To stop a run, atlas_cancel_run requests cooperative cancellation — the request cannot be revoked; paused/interrupted runs become cancelled directly, and a local_cli agent execution in flight is terminated with its whole process tree, while SDK-backed model calls finish their current attempt before the next consumption point ends the run.

While a dispatch is in flight, the controller appends node_progress heartbeat events to the run ledger (node/iteration/attempt/model/elapsed_ms/phase; default 30s, run-level via ATLAS_NODE_HEARTBEAT_INTERVAL_S). They prove only that the controller is still waiting — never model-internal progress — and stop before any terminal event, so a long silence after the last heartbeat means the call is still running, not that the stream died.