@revisium/orchestrator 0.1.0-alpha.1 → 0.1.0-alpha.11

package/README.md

@@ -5,7 +5,7 @@ reviewer → integrator), hosted in **NestJS**. **DBOS** owns durable progress
 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).
 
-> 🚧 **Early alpha.** The end-to-end MVP works — `run create` → plan gate → implement → review → PR → merge
+> 🚧 **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).
 
 ## Start here
@@ -15,6 +15,207 @@ a post-MVP goal; see [`docs/architecture-overview.md`](./docs/architecture-overv
 - 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)
 
+## Local Development
+
+`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.
+
+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.
+
+```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 revo -- stop --profile dev
+```
+
+| Knob | `default` (installed package) | `dev` (source checkout) |
+| --- | --- | --- |
+| 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.
+
+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):
+
+**Claude Code**
+
+```sh
+# global install
+claude mcp add revo -- revo mcp
+
+# dev checkout
+claude mcp add revo -- pnpm --dir "$PWD" run revo -- mcp
+```
+
+**Codex CLI** (`codex mcp add` or edit `~/.codex/config.toml` directly)
+
+```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
+```
+
+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:
+
+```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"]
+```
+
+**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.
+
+Run the local verification gates:
+
+```sh
+pnpm run typecheck
+pnpm run lint:ci
+pnpm run test:cov
+pnpm run verify
+```
+
+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`.
+
+```sh
+pnpm run smoke:control-plane
+pnpm run smoke:create-run
+pnpm run smoke:inspect-run
+```
+
+### Live Run Observability Smoke
+
+This smoke runs a real agent. It can call provider CLIs and incur cost. Use it
+only when that is intentional.
+
+```sh
+export REVO_SMOKE_REPO=/path/to/local/sandbox-repo
+pnpm run revo -- start --profile dev   # standalone + host daemon (serves GraphQL + MCP), ready
+```
+
+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
+  }
+}
+```
+
+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
+  }
+}
+```
+
+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"
+      }
+    }
+  }
+}
+```
+
+Useful MCP observability tools for the same run:
+
+- `get_agent_activity`
+- `get_agent_attempts`
+- `get_agent_log`
+- `read_agent_output_events`
+- `tail_agent_log`
+
+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.
+
+## Upgrading
+
+After installing a new version, run the full ritual — the daemon refreshes itself,
+but the MCP client caches its tool list and only the operator can refresh it:
+
+```sh
+npm i -g @revisium/orchestrator@<version>
+revo restart   # re-seeds the bundled playbook + a fresh read-scope, server-side
+```
+
+Then, in your MCP client (e.g. Claude Code), reconnect to pick up new tools:
+
+```text
+/mcp   # reconnect — the tool list is cached client-side; the daemon cannot push a refresh
+```
+
+Skipping the `/mcp` reconnect leaves new tools (e.g. `wait_for_any_gate`,
+`watch_runs`) invisible to the client even though the upgraded daemon already serves them.
+
 ## License
 
 See [LICENSE](./LICENSE).

package/control-plane/bootstrap.config.json

@@ -47,6 +47,31 @@
             "type": "number",
             "default": 0
           },
+          "playbook_id": {
+            "type": "string",
+            "default": "",
+            "description": "Installed playbook selected for this run"
+          },
+          "pipeline_id": {
+            "type": "string",
+            "default": "",
+            "description": "Installed pipeline row id selected for this run"
+          },
+          "params": {
+            "type": "string",
+            "default": "",
+            "description": "Serialized JSON run params"
+          },
+          "route_decision": {
+            "type": "string",
+            "default": "",
+            "description": "Serialized JSON structured route decision"
+          },
+          "execution_profile": {
+            "type": "string",
+            "default": "",
+            "description": "Serialized JSON resolved execution profile"
+          },
           "created_by": {
             "type": "string",
             "default": ""
@@ -124,6 +149,7 @@
       "id": "steps",
       "schema": {
         "type": "object",
+        "description": "DEPRECATED/unused — runtime path retired (audit §3.1, #86); no live path writes or reads a steps row (DBOS owns progress). Table drop deferred — a schema drop on existing control-planes is riskier than retiring the writes; tracked in docs/roadmap.md → Post-MVP cleanup.",
         "additionalProperties": false,
         "properties": {
           "id": {
@@ -285,6 +311,21 @@
             "default": "",
             "description": "Serialized JSON, secret-redacted, capped"
           },
+          "artifact_ref": {
+            "type": "string",
+            "default": "",
+            "description": "Stable run artifact reference, e.g. run_id/attempt_id"
+          },
+          "stdout_tail": {
+            "type": "string",
+            "default": "",
+            "description": "Secret-redacted process stdout tail, capped"
+          },
+          "stderr_tail": {
+            "type": "string",
+            "default": "",
+            "description": "Secret-redacted process stderr tail, capped"
+          },
           "lesson": {
             "type": "string",
             "default": ""
@@ -452,7 +493,12 @@
           "runner": {
             "type": "string",
             "default": "claude-code",
-            "description": "claude-code|codex|script"
+            "description": "Deprecated alias for runner_id"
+          },
+          "runner_id": {
+            "type": "string",
+            "default": "",
+            "description": "Portable playbook runner binding, for example claude-code or revo-integrator"
           },
           "allowed_tools": {
             "type": "array",
@@ -768,6 +814,62 @@
         },
         "required": []
       }
+    },
+    {
+      "id": "run_outputs",
+      "schema": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "default": "",
+            "description": "Deterministic: out_<fnv1a64Hex(runId|nodeId|ordinal)>"
+          },
+          "run_id": {
+            "type": "string",
+            "default": ""
+          },
+          "node_id": {
+            "type": "string",
+            "default": ""
+          },
+          "ordinal": {
+            "type": "number",
+            "default": 0,
+            "description": "Adapter-owned per-(run,node) execution ordinal; 1,2,3 across loop iterations (0016 §4.1)"
+          },
+          "name": {
+            "type": "string",
+            "default": "",
+            "description": "Artifact name from the node's produces.name, e.g. plan"
+          },
+          "schema_ref": {
+            "type": "string",
+            "default": "",
+            "description": "resultSchema the payload was shape-checked against, e.g. schema:plan"
+          },
+          "payload": {
+            "type": "string",
+            "default": "",
+            "description": "Serialized JSON content, secret-redacted + size-capped at the adapter boundary"
+          },
+          "payload_ref": {
+            "type": "string",
+            "default": "",
+            "description": "Set instead of payload when the content exceeds the inline cap (0016 §8)"
+          },
+          "attempt_id": {
+            "type": "string",
+            "default": ""
+          },
+          "produced_at": {
+            "type": "string",
+            "default": ""
+          }
+        },
+        "required": []
+      }
     }
   ],
   "rows": [
@@ -828,7 +930,7 @@
       "data": {
         "id": "integrator",
         "name": "integrator",
-        "system_prompt": "[DEPRECATED] Integration is now deterministic code in src/runners/integrator.ts; this role is retired from the executed chain and is not dispatched. Kept only so `run create --role integrator` validates against KNOWN_ROLES.",
+        "system_prompt": "[DEPRECATED] Integration is now deterministic code in src/runners/integrator.ts; this role is retired from the executed chain and is not dispatched. Kept only so `run create --role integrator` resolves to a seeded role row.",
         "model_level": "standard",
         "effort": "high",
         "runner": "script",