orc-ai 0.1.25 → 0.1.26

package/README.md

@@ -30,13 +30,14 @@ ORC fixes this. Shared memory across every session. A task board where agents su
 | **Human-in-the-loop**     | Agents submit work for your approval via CLI, Telegram, or Slack before anything lands                                             |
 | **Shared memory**         | Decisions, rules, and discoveries stored once, searchable by any session via ranked full-text search                               |
 | **Task board**            | `todo → queued → doing → review → done` with dependency tracking, priority, and automatic unblocking                               |
-| **Multi-backend routing** | Route to Claude Code, ACPX (Agent Communication Protocol, 14+ agents), or remote A2A endpoints; unknown names fall through to ACPX |
+| **Multi-backend routing** | Route to Claude (in-process, nothing to install), ACPX (14+ agents), agentapi, or remote A2A endpoints — with `orc doctor` reporting which are usable |
 | **Job runner**            | Cron, file-watch, webhook, or manual triggers with full run history                                                                |
-| **MCP server**            | 28 tools connect any [Model Context Protocol](https://modelcontextprotocol.io) (MCP) compatible agent — stdio or Streamable HTTP   |
+| **MCP server**            | 34 tools connect any [Model Context Protocol](https://modelcontextprotocol.io) (MCP) compatible agent — stdio or Streamable HTTP   |
 | **Session continuity**    | Snapshots survive context compaction so agents resume where they left off                                                          |
 | **Gateway**               | Approve work, search memory, and chat with live agents from Telegram or Slack                                                      |
 | **Knowledge search**      | Index document collections (markdown, notes, wikis) and search them via BM25 or hybrid (vector + reranking)                        |
 | **Skill library**         | Discoverable workflow templates (coder, reviewer, planner, bugfix) that encode your standards                                      |
+| **Task flows**            | Per-task graphs: conditional edges, bounded loops, parallel fan-out with joins, and human gates — with hard termination rails      |
 
 ## Getting started
 
@@ -102,22 +103,23 @@ orc status
 orc task list
 ```
 
-Open `http://localhost:7700` to use the web dashboard - task board, kanban, jobs, memories, sessions, knowledge, and a live chat panel. The same server hosts both the REST API and the prebuilt React SPA, so there is no separate command to run for the UI.
+Open `http://localhost:7700` to use the web dashboard - task board, kanban, flow runs, jobs, memories, sessions, knowledge, and a live chat panel. The same server hosts both the REST API and the prebuilt React SPA, so there is no separate command to run for the UI.
 
 > [!TIP]
 > The database is created automatically at `~/.orc/orc.db` on first run. No setup needed.
 
 ### Web dashboard
 
-The web dashboard ships inside the `orc` binary and is served by the API process at the root path. Endpoints are still reachable at both `/<route>` (legacy SDK/CLI/MCP) and `/api/<route>` (used by the dashboard's browser client).
+The web dashboard ships inside the `orc` binary and is served by the API process at the root path. REST routes live under `/api/<route>` - the SDK, CLI and MCP clients add that prefix themselves - which leaves the root path free for the SPA.
 
-| Route                            | Served from                                                         |
-| -------------------------------- | ------------------------------------------------------------------- |
-| `GET /`                          | `index.html` (web SPA shell)                                        |
-| `GET /assets/*`                  | Built JS/CSS bundles                                                |
-| `GET /api/*`                     | All REST routes (mirrors the root mount)                            |
-| `GET /openapi.json`, `GET /docs` | Swagger UI                                                          |
-| `GET /tasks`, `/memories`, …     | Same handler as `/api/<...>`, kept for SDK/CLI/MCP backwards compat |
+| Route                              | Served from                                                                                                                    |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `GET /`                            | `index.html` (web SPA shell)                                                                                                   |
+| `GET /assets/*`                    | Built JS/CSS bundles                                                                                                           |
+| `GET /api/*`                       | All REST routes                                                                                                                |
+| `GET /openapi.json`, `GET /docs`   | Swagger UI                                                                                                                     |
+| `GET /mcp`                         | MCP server (streamable HTTP)                                                                                                   |
+| `GET /tasks/<id>`, `/flows/<name>`, … | `index.html` again - a navigation request matching no static file falls back to the SPA shell, so dashboard links are shareable |
 
 Override the served dist directory with `ORC_WEB_DIST=/path/to/web/dist` if you want to host a custom build (e.g. a fork). If no dist is found, the server runs in pure-API mode.
 
@@ -280,15 +282,28 @@ task_batch_create({ tasks: [
 
 The loop handles concurrency, session resume on feedback, review round limits, stale claim cleanup, and backend routing.
 
+Every task runs a **flow graph** (see [Task flows](#task-flows)); `orc-default` is the build → review → done pipeline described above.
+
 #### Agent backends
 
-| Backend         | Description                                                                                                  |
+| Backend         | Needs                                                                                                        |
 | --------------- | ------------------------------------------------------------------------------------------------------------ |
-| `claude`        | Anthropic Claude via [@anthropic-ai/claude-agent-sdk](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) — no host CLI needed. Requires `ANTHROPIC_API_KEY`. |
-| `agentapi`      | Delegates to a [coder/agentapi](https://github.com/coder/agentapi) server on the host (HTTP+SSE) — wraps any local coding agent (`claude`, `codex`, `aider`, …). Auth is whatever the host agent uses. |
-| `acpx`          | 14+ agents via [ACP CLI](https://github.com/AgenTool/acpx) - Codex, Gemini, Copilot, Kiro, Cursor, and more. |
-| `a2a`           | Remote agents via [Google A2A protocol](https://github.com/google/A2A) (JSON-RPC over HTTP).                 |
-| _anything else_ | Routes through ACPX with the name as `--agent` flag.                                                         |
+| `claude`        | Nothing to install: runs **in-process** via [@anthropic-ai/claude-agent-sdk](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk), which ships with orc. Uses the Claude Code CLI's stored credentials, or `ANTHROPIC_API_KEY`. The default. |
+| `acpx`          | The [ACP CLI](https://github.com/openclaw/acpx) — 14+ agents (Codex, Gemini, Copilot, Kiro, Cursor, …). Installed as an optional dependency, so a normal `npm i -g orc-ai` gets it; orc finds it there even when it is not on your `PATH`. Point `ORC_ACPX_PATH` at a specific copy to override. |
+| `agentapi`      | A [coder/agentapi](https://github.com/coder/agentapi) server on the host (HTTP+SSE), wrapping any local coding agent. `AGENTAPI_URL` if it is not on the default port. |
+| `a2a`           | A remote [A2A](https://github.com/google/A2A) endpoint, supplied per task/session — nothing local.            |
+| `claude-cli`    | The `claude` binary on `PATH`. The pre-SDK path, kept for when driving the real CLI matters.                  |
+| `codex-cli`     | The `codex` binary on `PATH`, driven natively instead of through acpx.                                        |
+| _anything else_ | Passed to acpx as its agent name, so `--agent-backend gemini` means "acpx driving gemini".                    |
+
+Which of these actually work on a given machine depends on what is installed, so orc probes them rather than making you guess:
+
+```bash
+orc doctor          # per backend: usable or not, what it resolved to, what a missing one needs
+orc doctor --json   # same, machine-readable
+```
+
+The dashboard shows the same probe: the agent-backend field on a task is a picker that marks each backend ready or unavailable, and names the one a task with no backend of its own will use. `GET /api/backends` is the endpoint behind both.
 
 Enable the task loop in `~/.orc/config.json`:
 
@@ -300,7 +315,9 @@ Enable the task loop in `~/.orc/config.json`:
     "max_workers": 1,
     "default_backend": "claude",
     "session_idle_timeout_minutes": 20,
-    "worker_auto_approve": true
+    "worker_auto_approve": true,
+    "default_flow": "orc-default",
+    "review_flow": "orc-review-only"
   }
 }
 ```
@@ -379,8 +396,57 @@ todo → queued → doing → review → done
 
 Tasks with `required_review: true` (default) need your approval before moving to `done`. Set `max_review_rounds` to auto-pause tasks that cycle through too many revision rounds.
 
+`queued` means a node is waiting for a worker slot — the task is claimed but nothing is running on it yet, so it counts as pending rather than in progress (the dashboard's board shows it under Todo, labelled `queued`). It becomes `doing` when a session actually starts, which is what keeps the board from showing more work in flight than `agent_loop.max_workers` allows.
+
 <img src="assets/TaskFlow.gif" alt="Task Flow" width="600" />
 
+### Task flows
+
+That pipeline is not hardcoded — it is a **flow graph** named `orc-default`. A flow is nodes joined by conditional edges that may cycle, so a task can run whatever shape its work actually needs: a plan → build → verify loop, a bug-fix-then-confirm loop, an executor with an independent supervisor, or three reviewers in parallel joined before a decision.
+
+The graph itself is deterministic; only the nodes are agents. That means loops, branches, and fan-out behave predictably and are fully unit-testable, while the agents just do the work and report a verdict.
+
+```bash
+orc flow list                                    # what graphs are available
+orc flow show orc-plan-build-verify              # nodes, edges, limits
+orc task add "Fix the flaky test" --flow orc-fix-verify
+orc flow status <taskId>                         # active nodes + the ledger of outcomes
+orc flow resume <taskId> --outcome approved      # resolve a human gate
+orc flow halt <taskId>                           # stop it and kill live nodes
+```
+
+| Built-in flow           | Shape                                                                        |
+| ----------------------- | ---------------------------------------------------------------------------- |
+| `orc-default`           | build → review → done, looping back while `max_review_rounds` allows         |
+| `orc-review-only`       | A single review pass for a task you moved straight to `review`               |
+| `orc-plan-build-verify` | planner → coder → reviewer, looping until acceptance criteria pass           |
+| `orc-fix-verify`        | bugfix → independent confirmation the fix holds and a regression test exists  |
+| `orc-supervisor`        | Executor keeping its context, plus a supervisor re-verifying from a clean one |
+| `orc-parallel-review`   | Fan out to correctness / security / tests reviewers, join on all three       |
+
+**Nodes** are `agent` (runs a session with a skill), `gate` (deterministic branching, fan-out, join points), `human` (waits for you), or `terminal` (ends the run and sets the task's final status). **Edges** carry declarative conditions — `outcome`, `visits`, `var`, `elapsed_secs`, composed with `all`/`any`/`not` — which are data, never evaluated code.
+
+Loops always terminate. Per-node `max_visits`, a per-run node-execution budget, a wall clock, plus deadlock and stall detection each halt the run and hand the task back to you with an explanation of which rail tripped.
+
+#### Custom graphs per task
+
+For work no named flow fits, attach a bespoke graph to a single task:
+
+```bash
+orc flow validate --file ./my-graph.json          # catch mistakes before running anything
+orc flow attach <taskId> --file ./my-graph.json --start
+```
+
+Definitions are JSON, validated on load: unknown edge targets, unreachable nodes, a graph that can never finish, or an edge shadowed by an earlier catch-all are all rejected up front rather than discovered mid-run. Reusable flows go in `~/.orc/flows/<name>/flow.json` (or `./.orc/flows/` to pin one per repo), and a user flow shadows a built-in of the same name — that is how you customise `orc-default` without patching orc.
+
+Agents can do all of this themselves via the `flow_list`, `flow_read`, `flow_create`, `flow_attach`, `flow_status`, and `flow_report` MCP tools, so a planner can design the pipeline for the work it just decomposed.
+
+#### In the web dashboard
+
+A task's **Flow** section draws the graph the run froze at start next to its ledger: which node is active, the verdict each visit produced, how many visits a node has spent of its budget, per-node timings and errors, a link to each node's agent transcript, and — when a rail tripped — which one and why. Loopbacks are drawn as edges that go backwards, so a rework cycle looks like one.
+
+When a run parks on a human gate, that panel is where you answer it: pick one of the outcomes the node's own edges can route, add a comment, and the flow continues. `Halt` stops a run and kills its live sessions. The **Flows** page lists every graph available with its source, marks the one a task with no flow of its own will run, shows any definition, and reports flows that failed validation along with the errors — so a broken graph is visible before a task tries to run it.
+
 ### Jobs
 
 ```bash
@@ -476,7 +542,7 @@ Add custom skills by creating a `SKILL.md` in `~/.orc/skills/my-workflow/SKILL.m
 
 ## MCP tools
 
-**28 tools** available to any connected agent. Start every session with `context`.
+**34 tools** available to any connected agent. Start every session with `context`.
 
 | Category      | Tools                                                                                                                                       |
 | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -484,6 +550,7 @@ Add custom skills by creating a `SKILL.md` in `~/.orc/skills/my-workflow/SKILL.m
 | **Memory**    | `context`, `memory_search`, `memory_get`, `memory_store`, `memory_update`                                                                   |
 | **Task**      | `task_list`, `task_get`, `task_create`, `task_update`, `task_batch_create`                                                                  |
 | **Skill**     | `skill_list`, `skill_read`, `skill_create`                                                                                                  |
+| **Flow**      | `flow_report`, `flow_status`, `flow_list`, `flow_read`, `flow_create`, `flow_attach`                                                        |
 | **Knowledge** | `knowledge_search`, `knowledge_get`, `knowledge_collections`, `knowledge_collection_add`, `knowledge_collection_remove`, `knowledge_update` |
 | **Search**    | `search`                                                                                                                                    |
 | **Job**       | `job_list`, `job_run`, `job_status`                                                                                                         |
@@ -520,6 +587,13 @@ Runs on port 7700 with auto-generated OpenAPI spec.
 | `GET`                   | `/jobs/{id}/runs`              | Run history                    |
 | `GET`                   | `/jobs/{id}/runs/{runId}/logs` | Run logs                       |
 | `GET`                   | `/skills`                      | Skill templates                |
+| `GET`                   | `/backends`                    | Agent backends + usability     |
+| `GET/POST`              | `/flows`                       | List/create flow graphs        |
+| `GET`                   | `/flows/{name}`                | Read a flow definition         |
+| `POST`                  | `/flows/validate`              | Validate without saving        |
+| `GET/POST`              | `/tasks/{id}/flow`             | Get a task's run / attach one  |
+| `POST`                  | `/tasks/{id}/flow/resume`      | Resolve a human node           |
+| `POST`                  | `/tasks/{id}/flow/halt`        | Stop a running flow            |
 | `GET`                   | `/sessions`                    | Agent session logs             |
 | `POST`                  | `/mcp/tool`                    | Execute any MCP tool via HTTP  |
 
@@ -534,6 +608,7 @@ orc api                          Start the API server only
 orc mcp                          Start the MCP server (stdio)
 orc home                         Show ~/.orc directory and config
 orc status                       Show API health and counts
+orc doctor                       Check which agent backends are usable here
 
 orc project list|add|show|use|update|archive
 orc task list|add|show|update|done|review|approve|reject|delete
@@ -541,6 +616,7 @@ orc mem list|add|search
 orc job list|add|run|runs
 orc session list|show|log
 orc skill list|show
+orc flow list|show|validate|create|attach|status|resume|halt
 orc kb search|get|collections|add|remove|update|status
 ```
 
@@ -663,3 +739,4 @@ See [AGENTS.md](./AGENTS.md) for the full development guide and coding conventio
 - [Vision](./docs/vision.md) - why ORC exists and the problem it solves
 - [Roadmap](./docs/roadmap.md) - what shipped and what's next
 - [Agent Orchestration Design](./docs/agent-orchestration-design.md) - architecture spec for the task loop and multi-agent workflow
+- [Task Flows](./docs/task-flows.md) - flow graphs: nodes, conditional edges, bounded loops, fan-out and joins, and how to author your own