@revisium/orchestrator 0.1.0-alpha.9 → 0.2.0-alpha.0

package/README.md

@@ -1,202 +1,266 @@
-# agent-orchestrator
+<div align="center">
 
-Local orchestrator for software-development tasks driven by short-lived AI agents (architect → developer →
-reviewer → integrator), hosted in **NestJS**. **DBOS** owns durable progress — execution is crash-safe and resumes
-from the first unfinished step — while **Revisium** owns meaning: roles, policy, inbox, events. Workflow-as-data is
-a post-MVP goal; see [`docs/architecture-overview.md`](./docs/architecture-overview.md).
+# @revisium/orchestrator
 
-> 🚧 **Early alpha.** The end-to-end MVP works — create a run → plan gate → implement → review → PR → merge
-> gate — see [`docs/roadmap.md`](./docs/roadmap.md).
+Local-first orchestration for software-development work driven by short-lived agents.
 
-## Start here
+**Turn a task into a playbook-driven state machine.**
 
-- Repo context for agents: [`AGENTS.md`](./AGENTS.md)
-- Vision: [`docs/vision.md`](./docs/vision.md)
-- Architecture & invariants: [`docs/architecture-overview.md`](./docs/architecture-overview.md)
-- Docs index & roadmap: [`docs/README.md`](./docs/README.md) · [`docs/roadmap.md`](./docs/roadmap.md)
+[![License](https://img.shields.io/github/license/revisium/orchestrator?color=blue)](LICENSE)
+[![CI](https://github.com/revisium/orchestrator/actions/workflows/ci.yml/badge.svg)](https://github.com/revisium/orchestrator/actions/workflows/ci.yml)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=revisium_agent-orchestrator&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=revisium_agent-orchestrator)
+[![npm](https://img.shields.io/npm/v/@revisium/orchestrator?color=red)](https://www.npmjs.com/package/@revisium/orchestrator)
 
-## Local Development
+Part of the [Revisium](https://github.com/revisium/revisium) ecosystem.
+
+</div>
+
+```mermaid
+flowchart LR
+  task[Task]
+  playbook[Playbook]
+  machine[State machine]
+  outcome[Outcome]
+
+  task --> playbook --> machine --> outcome
+
+  subgraph nodes[State machine nodes]
+    agent[Agent step] --> script[Script step] --> gate[Human gate] --> branch{Branch}
+    branch --> loop((Loop))
+    loop -. retry .-> agent
+    loop -. reroute .-> script
+  end
+
+  machine -. expands into .-> nodes
+  outcome --> pr[Pull request]
+  outcome --> evidence[Evidence]
+  outcome --> decisions[Decisions]
+  outcome --> history[Run history]
+```
+
+> Revo is in active development. The package is suitable for evaluation and local experimentation; do not treat
+> the public contract as stable yet.
 
-`revo` is one daemonized product. **`revo start`** brings up the whole stack — the standalone
-Revisium daemon plus the Revo host daemon that owns DBOS and serves the GraphQL + MCP front doors —
-and bootstraps the control-plane so it is ready to use. The CLI is lifecycle-only
-(`start` / `stop` / `status` / `restart` / `doctor` / `logs`); orchestration (runs, inbox, …) is
-reached over **MCP** (agents) or **GraphQL** (UI/scripts), both served by the daemon.
+## Overview
 
-Run a source checkout alongside an installed package without collisions via a named **profile**
-(`--profile dev`, or `REVO_PROFILE=dev`): the `dev` profile shifts the whole port band off the
-`default` profile, so the two never share a port, data dir, or `dbos` database.
+Revo is a local control plane for agentic work. A caller creates a run, Revo selects a playbook, and the playbook
+executes as a state machine made of agent steps, script steps, human gates, branches, and loops.
+
+The goal is not to replace coding agents. Revo coordinates them: it keeps state, records evidence, enforces gates,
+and gives humans a stable place to approve plans, resolve questions, inspect feedback, and decide when work is ready
+to ship.
+
+## How It Works
+
+- **Playbooks define flow.** Roles, scripts, gates, verdicts, branches, and loop limits are data, not hidden prompt
+  convention.
+- **Agent steps are short-lived.** Each agent process receives current state and exits after one step.
+- **Script steps do deterministic work.** Automation such as integration, polling, and response actions stays outside
+  agent prompts.
+- **Human gates are state changes.** A plan approval, question answer, or merge approval resolves an inbox item and
+  resumes the run.
+- **Outputs are traceable.** Artifacts, evidence, decisions, attempts, cost, and run history are recorded for later
+  inspection.
+
+## Concepts
+
+| Term | Meaning |
+| --- | --- |
+| **Revo** | The local orchestrator and control plane for software-development runs. |
+| **Playbook** | A versioned bundle of roles, pipelines, policies, and routing rules. |
+| **Pipeline** | A state-machine template that defines the steps, gates, branches, loops, and terminal outcomes. |
+| **Role** | A named agent definition: prompt, model level, scope, runner, and allowed behavior. |
+| **Agent step** | A pipeline node that starts a short-lived coding agent through a role. |
+| **Script step** | A deterministic automation node used for integration, polling, readiness, or response actions. |
+| **Human gate** | A required decision or answer; the run parks until an inbox item is resolved. |
+| **Run** | One task moving through a selected playbook and pipeline. |
+| **Attempt** | One execution of one step; the unit for logs, verdicts, tokens, and cost. |
+| **MCP** | The local agent-facing tool bridge exposed by `revo mcp`. |
+| **GraphQL API** | The local API surface for UI and script integrations. |
+
+## Alpha Install
+
+The `@alpha` package is a prerelease for evaluating Revo locally. It uses the `default` profile:
+
+```sh
+npm install -g @revisium/orchestrator@alpha
+revo start
+revo status
+revo doctor
+revo logs
+revo stop
+```
+
+Connect an MCP-capable agent to the installed binary:
+
+```sh
+codex mcp add revo -- revo mcp
+claude mcp add revo -- revo mcp
+```
+
+Default local ports:
+
+| Service | Port |
+| --- | --- |
+| Revisium standalone HTTP | `19222` |
+| embedded Postgres | `15440` |
+| Revo GraphQL | `19223` |
+
+GraphQL is available at `http://127.0.0.1:19223/graphql` in the default profile. The target contract is documented in
+[docs/specs/graphql-admin-api-v1.spec.md](./docs/specs/graphql-admin-api-v1.spec.md), and the committed SDL is
+[src/api/graphql-api/schema.graphql](./src/api/graphql-api/schema.graphql).
+
+## Roadmap
+
+Revo is in active development. The public roadmap lives in GitHub Milestones and umbrella issues; this README only points to the current tracks.
+
+| Track | Start here |
+| --- | --- |
+| Default playbook stabilization | [Milestone #1](https://github.com/revisium/orchestrator/milestone/1), [umbrella #146](https://github.com/revisium/orchestrator/issues/146) |
+| GraphQL admin API v1 migration | [Milestone #4](https://github.com/revisium/orchestrator/milestone/4), [umbrella #167](https://github.com/revisium/orchestrator/issues/167) |
+| Execution profiles and runner/model binding | [Milestone #5](https://github.com/revisium/orchestrator/milestone/5), [umbrella #168](https://github.com/revisium/orchestrator/issues/168) |
+| Loop engineering layer | [Milestone #2](https://github.com/revisium/orchestrator/milestone/2), [umbrella #148](https://github.com/revisium/orchestrator/issues/148) |
+| Role and pipeline authoring | [Milestone #3](https://github.com/revisium/orchestrator/milestone/3), [umbrella #157](https://github.com/revisium/orchestrator/issues/157) |
+
+Use umbrella issues for initiative context and child issues for reviewable delivery slices. Work orders do not live in docs.
+
+## Local Development
+
+Use the `dev` profile when running a source checkout next to an installed package. The profile has isolated ports,
+data directory, and DBOS database.
 
 ```sh
 pnpm install
-pnpm run revo -- start --profile dev    # standalone + host daemon, bootstrapped & ready
-pnpm run revo -- status --profile dev   # stack health summary
-pnpm run revo -- doctor --profile dev   # diagnose process / port / profile issues
-pnpm run revo -- logs --profile dev     # tail host + standalone logs; add -f to follow
-pnpm run revo -- restart --profile dev  # stop, then start
+pnpm run build
+pnpm run revo -- start --profile dev
+pnpm run revo -- status --profile dev
+pnpm run revo -- doctor --profile dev
+pnpm run revo -- logs --profile dev
 pnpm run revo -- stop --profile dev
 ```
 
-| Knob | `default` (installed package) | `dev` (source checkout) |
+| Knob | `default` | `dev` |
 | --- | --- | --- |
 | data dir | `~/.revisium-orchestrator` | `~/.revisium-orchestrator-dev` |
 | standalone HTTP / Postgres | `19222` / `15440` | `19622` / `15840` |
 | Revo GraphQL | `19223` | `19623` |
 | DBOS database | `dbos` | `dbos_dev` |
 
-Any single knob can be overridden explicitly — `REVO_DATA_DIR` / `REVO_PORT` / `REVO_PG_PORT` /
-`REVO_GRAPHQL_PORT` / `REVO_DBOS_DB` — and an explicit env var always wins over the profile band.
+Explicit environment variables override the profile: `REVO_DATA_DIR`, `REVO_PORT`, `REVO_PG_PORT`,
+`REVO_GRAPHQL_PORT`, and `REVO_DBOS_DB`.
 
-Connect an agent over MCP (`revo mcp` is a thin stdio bridge — it does not launch its own DBOS;
-if the daemon isn't already running, the bridge auto-starts it on first use; the profile comes
-from the process environment, not per-call args):
+### Build and globally install a local Revo
 
-**Claude Code**
+This workflow is for local development/testing of the CLI and MCP server, **not** for publishing a release.
 
-```sh
-# global install
-claude mcp add revo -- revo mcp
+**Build from the orchestrator checkout:**
 
-# dev checkout
-claude mcp add revo -- pnpm --dir "$PWD" run revo -- mcp
+```sh
+pnpm install --frozen-lockfile
+pnpm run build
 ```
 
-**Codex CLI** (`codex mcp add` or edit `~/.codex/config.toml` directly)
+**Pack a tarball** (preferred over a directory-symlink install):
 
 ```sh
-# global install
-codex mcp add revo -- revo mcp
-
-# dev checkout (use an absolute path — $PWD does not expand in TOML args)
-codex mcp add revo-dev -- pnpm --dir /abs/path/to/agent-orchestrator run revo -- mcp
+npm pack --pack-destination /private/tmp
 ```
 
-To use a non-`default` profile with Codex, append `--env REVO_PROFILE=dev` (and the other
-dev-band vars; see the JSON block under **Live Run Observability Smoke**) to `codex mcp add`,
-or export the vars in the shell before launching Codex — stdio servers inherit the parent
-environment. Equivalent TOML for the global install form:
+This emits `/private/tmp/revisium-orchestrator-0.0.0.tgz` (filename tracks `package.json` `version`).
 
-```toml
-# ~/.codex/config.toml
-[mcp_servers.revo]
-command = "revo"     # or the absolute path from `which revo` if revo is not on Codex's PATH
-args = ["mcp"]
+**Identify the active Node prefix that owns the `revo` binary:**
+
+```sh
+which revo
 ```
 
-**Verify the connection** — run `claude mcp list` or `codex mcp list` to confirm the server
-appears, then have the agent call `get_status` for a healthy JSON status reply. `list_pipelines`
-is a good read-only alternative.
+Resolve the symlink and pick the prefix that contains both `bin/revo` and
+`lib/node_modules/@revisium/orchestrator`. `npm prefix -g` may point to a *different* prefix than the active
+`revo` binary (common under nvm), so derive the prefix from `which revo`, not from `npm prefix -g`.
 
-Run the local verification gates:
+**Install the tarball globally into that prefix:**
 
 ```sh
-pnpm run typecheck
-pnpm run lint:ci
-pnpm run test:cov
-pnpm run verify
+npm install -g --prefix <active-node-prefix> /private/tmp/revisium-orchestrator-0.0.0.tgz
 ```
 
-The smoke scripts are guarded: they require a non-default `REVO_DATA_DIR`,
-`REVO_PORT`, `REVO_PG_PORT`, and `REVO_DBOS_DB`; GraphQL smoke paths also require
-`REVO_GRAPHQL_PORT`.
+For nvm installs, the active prefix is usually the parent directory that contains both `bin/revo` and
+`lib/node_modules/@revisium/orchestrator`. Use that prefix consistently for both `npm` and `revo`.
+
+> **Warning:** do not use `npm install -g <local-dir>` from a temporary worktree. npm may install a symlink to
+> that directory; if the worktree is later removed, the global `revo` binary breaks. The tarball install copies
+> files and avoids this.
+
+**Restart and verify health:**
 
 ```sh
-pnpm run smoke:control-plane
-pnpm run smoke:create-run
-pnpm run smoke:inspect-run
+revo restart
+revo status
+revo doctor
 ```
 
-### Live Run Observability Smoke
+**Verify the MCP tool surface after a global tool/schema change:**
+
+Restart the Codex session so MCP tool schemas are reloaded. `get_capabilities` should list:
+`get_run_attention`, `get_run_status`, `get_run_digest`, `get_run_events`, `get_agent_activity`,
+`get_agent_log`, `watch_run_changes`. Legacy observation tools are absent from the current contract.
+
+If Codex cannot expose `mcp__revo` tools after restart, check `~/.codex/config.toml`: use an absolute path to
+the active `revo` binary, for example `command = "<active-node-prefix>/bin/revo"`, rather than
+`command = "revo"` — the Codex process PATH may not include nvm.
+
+## Front Doors
 
-This smoke runs a real agent. It can call provider CLIs and incur cost. Use it
-only when that is intentional.
+`revo mcp` is the agent front door. It is a local stdio bridge to the daemon and exposes product-level tools for
+runs, gates, repository diagnostics, method discovery, and PR readiness.
+
+For source-iteration MCP testing, point the MCP client at the `pnpm run revo` script:
 
 ```sh
-export REVO_SMOKE_REPO=/path/to/local/sandbox-repo
-pnpm run revo -- start --profile dev   # standalone + host daemon (serves GraphQL + MCP), ready
+codex mcp add --env REVO_PROFILE=dev revo-dev -- pnpm --dir /abs/path/to/orchestrator run revo -- mcp
+claude mcp add -e REVO_PROFILE=dev revo-dev -- pnpm --dir /abs/path/to/orchestrator run revo -- mcp
 ```
 
-Drive and observe a run through the daemon's front doors — there are no `run`/`serve` CLI commands.
-From an agent, use the MCP tools (`create_run`, `start_run`, then `get_agent_activity` /
-`get_agent_log`). From a UI or script, use the GraphQL front door the daemon already serves at
-`http://127.0.0.1:$REVO_GRAPHQL_PORT/graphql` — create a run:
-
-```graphql
-mutation Create($data: CreateRunInput!) {
-  createRun(data: $data) {
-    runId
-  }
-}
-```
+For testing the same built entrypoint that the package uses, point the MCP client at `bin/revo.js`:
 
-Then observe it over the same endpoint:
-
-```graphql
-query Activity($runId: ID!) {
-  runAgentActivity(runId: $runId) {
-    runId
-    aggregateStatus
-    latestOutputAt
-    attempts {
-      attemptId
-      runner
-      status
-      stdoutBytes
-      stderrBytes
-      artifactRef
-    }
-  }
-}
-
-query Log($data: GetAgentLogInput!) {
-  runAgentLog(data: $data) {
-    runId
-    attemptId
-    stream
-    offsetBytes
-    nextOffsetBytes
-    totalBytes
-    truncated
-    content
-  }
-}
+```sh
+pnpm run build
+REVO_PROFILE=dev ./bin/revo.js restart --profile dev
+REVO_PROFILE=dev ./bin/revo.js doctor --profile dev
+codex mcp add --env REVO_PROFILE=dev revo-dev -- /abs/path/to/orchestrator/bin/revo.js mcp
+claude mcp add -e REVO_PROFILE=dev revo-dev -- /abs/path/to/orchestrator/bin/revo.js mcp
 ```
 
-For MCP, configure the MCP client to launch this checkout's local binary with the
-same environment. The MCP tools do not accept per-call profile arguments; the
-profile comes from the process environment.
-
-```json
-{
-  "mcpServers": {
-    "revo-dev": {
-      "command": "/path/to/agent-orchestrator/bin/revo.js",
-      "args": ["mcp"],
-      "env": {
-        "REVO_DATA_DIR": "/path/to/.revisium-orchestrator-dev",
-        "REVO_PORT": "19622",
-        "REVO_PG_PORT": "15840",
-        "REVO_GRAPHQL_PORT": "19623",
-        "REVO_DBOS_DB": "dbos_dev"
-      }
-    }
-  }
-}
+`bin/revo.js` imports `dist/cli/index.js`, so it does not see source edits until `pnpm run build` runs. After
+changing MCP tools or capabilities, rebuild, restart the `dev` stack, and reconnect or restart the MCP client session
+so the client refreshes its tool list. A built MCP smoke should confirm `get_capabilities.tools` contains
+`get_run_attention`, `get_run_status`, and `watch_run_changes`, with no legacy observation tools.
+
+For the `dev` profile, GraphQL is available at `http://127.0.0.1:19623/graphql`.
+
+## Verification
+
+```sh
+pnpm run typecheck
+pnpm run lint:ci
+pnpm run test:cov
+pnpm run verify
 ```
 
-Useful MCP observability tools for the same run:
+Smoke and e2e scripts that start local daemons may need an unsandboxed terminal and isolated non-default ports.
 
-- `get_agent_activity`
-- `get_agent_attempts`
-- `get_agent_log`
-- `read_agent_output_events`
-- `tail_agent_log`
+## Documentation
 
-If running from a sandboxed automation environment, local server checks may fail
-with `listen EPERM` or a misleading `No free port found from <port>`. Re-run the
-daemon, GraphQL, and MCP smoke commands from a normal terminal or an approved
-unsandboxed execution context.
+| Start here | Purpose |
+| --- | --- |
+| [docs/README.md](./docs/README.md) | Documentation map and ownership rules |
+| [docs/vision.md](./docs/vision.md) | Product direction, glossary, and capability map |
+| [docs/architecture-overview.md](./docs/architecture-overview.md) | Runtime layers, invariants, and lifecycle |
+| [docs/developer-guide.md](./docs/developer-guide.md) | Source map and contributor onboarding |
+| [docs/specs/](./docs/specs/) | Exact product contracts |
+| [docs/adr/](./docs/adr/) | Durable architecture decisions |
+| [AGENTS.md](./AGENTS.md) | Repo-local instructions for coding agents |
 
 ## License
 
-See [LICENSE](./LICENSE).
+MIT - see [LICENSE](./LICENSE).

package/control-plane/bootstrap.config.json

@@ -703,7 +703,7 @@
           "level": {
             "type": "string",
             "default": "",
-            "description": "cheap|standard|deep"
+            "description": "cheap|standard|deep|codex-cheap|codex-standard|codex-deep"
           },
           "provider": {
             "type": "string",
@@ -1017,6 +1017,48 @@
         "updated_at": "2026-06-03T00:00:00.000Z"
       }
     },
+    {
+      "tableId": "model_profiles",
+      "rowId": "codex-standard",
+      "data": {
+        "id": "codex-standard",
+        "level": "codex-standard",
+        "provider": "openai",
+        "model_id": "gpt-5.5",
+        "params": "{}",
+        "cost_per_input": 2.0,
+        "cost_per_output": 8.0,
+        "updated_at": "2026-06-03T00:00:00.000Z"
+      }
+    },
+    {
+      "tableId": "model_profiles",
+      "rowId": "codex-cheap",
+      "data": {
+        "id": "codex-cheap",
+        "level": "codex-cheap",
+        "provider": "openai",
+        "model_id": "gpt-5.5",
+        "params": "{}",
+        "cost_per_input": 2.0,
+        "cost_per_output": 8.0,
+        "updated_at": "2026-06-03T00:00:00.000Z"
+      }
+    },
+    {
+      "tableId": "model_profiles",
+      "rowId": "codex-deep",
+      "data": {
+        "id": "codex-deep",
+        "level": "codex-deep",
+        "provider": "openai",
+        "model_id": "gpt-5.5",
+        "params": "{}",
+        "cost_per_input": 2.0,
+        "cost_per_output": 8.0,
+        "updated_at": "2026-06-03T00:00:00.000Z"
+      }
+    },
     {
       "tableId": "routing_policy",
       "rowId": "pipeline",