@enderfga/claw-orchestrator 4.0.0 → 4.0.4

package/README.md

@@ -4,317 +4,97 @@
 
 # Claw Orchestrator
 
-Run Claude Code, Codex and other coding agents in one unified runtime.
-
-Claw Orchestrator turns interactive coding CLIs into programmable, headless agent engines. Start persistent sessions, route tasks across different coding agents, coordinate multi-agent councils, and expose everything through a clean tool-based API.
-
-It's a TypeScript runtime for orchestrating Claude Code, OpenAI Codex, Gemini, Cursor Agent, and custom coding CLIs as persistent, programmable coding agents.
-
-> Claude Code, Codex, Gemini, Cursor Agent, OpenCode, or your own custom CLI — orchestrated as one runtime.
->
-> **Runs standalone, as an OpenClaw plugin, or as a Model Context Protocol (MCP) server — drop it into Hermes Agent, Claude Desktop, Cursor, Cline, Continue, Zed, Windsurf, Goose, or any MCP-compatible host.**
+> A runtime for coding agents. Wrap Claude Code, Codex, Gemini, Cursor Agent, OpenCode, or any custom CLI as persistent programmable sessions; coordinate them in multi-agent councils; run autonomous Planner / Coder / Reviewer loops; or hand a five-question interview to an Opus council that ships a deployed web app at `localhost:19000/forge/<slug>/`.
 
 [![npm version](https://img.shields.io/npm/v/@enderfga/claw-orchestrator.svg)](https://www.npmjs.com/package/@enderfga/claw-orchestrator)
 [![CI](https://github.com/Enderfga/claw-orchestrator/actions/workflows/ci.yml/badge.svg)](https://github.com/Enderfga/claw-orchestrator/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
----
-
-## Why Claw Orchestrator?
-
-Coding agents are powerful, but most are still designed as interactive CLIs.
-
-That works well when a human is sitting in front of a terminal. It breaks down when you want agents to:
-
-- keep long-running coding sessions alive
-- switch between Claude Code, Codex, Gemini, Cursor Agent, OpenCode, or custom CLIs
-- collaborate as a team on the same codebase
-- integrate coding capabilities into OpenClaw first, and other claw-style agent systems over time
-- manage context, tools, worktrees, and execution state programmatically
-
-Claw Orchestrator is the control layer for that.
+Coding CLIs are designed for humans at terminals. Claw Orchestrator turns them into headless engines and stacks an agent platform on top: a 55-tool API that scales from a single session call up to a fully generated, deployed web app — reachable through the CLI, the OpenClaw gateway, the Model Context Protocol, or directly from TypeScript, and visible through an embedded three-tab dashboard.
 
 ---
 
-## Use Cases
+## Features
 
-- Run Claude Code or Codex as a headless coding agent
-- Keep persistent AI coding sessions alive across requests
-- Build multi-agent coding teams with isolated git worktrees
-- Expose coding agents as MCP tools so Hermes Agent, Claude Desktop, Cursor, Cline, Continue, Zed, Windsurf, Goose, and other MCP-capable hosts can drive them
-- Use the same toolset from OpenClaw, bots, dashboards, or custom runtimes
-- Route tasks across Claude Code, Codex, Gemini, Cursor Agent, OpenCode, and custom CLIs
-
----
+| Capability                  | What it does                                                                                                                                                                                                                    | Reference                                                  |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| **Persistent Sessions**     | Long-lived coding agents kept alive across requests, with full context, tool, model, and worktree control.                                                                                                                      | [`sessions.md`](./skills/references/sessions.md)           |
+| **Multi-Engine Runtime**    | One interface over Claude Code, Codex, Gemini, Cursor Agent, OpenCode, and arbitrary custom CLIs.                                                                                                                               | [`multi-engine.md`](./skills/references/multi-engine.md)   |
+| **Multi-Agent Council**     | Parallel agents in isolated git worktrees, voting on consensus until they agree.                                                                                                                                                | [`council.md`](./skills/references/council.md)             |
+| **Autoloop**                | Three-agent autonomous workspace iteration. Chat with the Planner; it spawns Coder + Reviewer into a self-iterating subloop and pushes you on regression, target-hit, or decision points.                                       | [`autoloop.md`](./skills/references/autoloop.md)           |
+| **Ultraapp**                | A three-agent Opus council turns a five-question interview into a deployed web app — Tailwind UI, BYOK, file-queue runtime, smoke test, all live at `localhost:19000/forge/<slug>/`.                                            | [`ultraapp.md`](./skills/references/ultraapp.md)           |
+| **Embedded Dashboard**      | Three-tab UI for Autoloop, Council, and Forge with sidebar lifecycle controls, per-run live event streaming, and cookie-based auth via a `/login` redirect.                                                                     | [`dashboard.md`](./skills/references/dashboard.md)         |
+| **OpenAI-Compatible Proxy** | `POST /v1/chat/completions` translates OpenAI requests into native Anthropic, OpenAI, and Google calls and streams responses back in OpenAI shape. Point any OpenAI-SDK client at the orchestrator without changing call sites. | [`openai-compat.md`](./skills/references/openai-compat.md) |
 
-## Core Features
-
-### Persistent Sessions
-
-Keep coding agents alive across requests.
-
-```ts
-const session = await manager.startSession({
-  name: "fix-tests",
-  engine: "claude",
-  cwd: "/path/to/project",
-});
-
-await manager.sendMessage("fix-tests", "Fix the failing tests");
-```
-
-### Multi-Engine Runtime
-
-Drive different coding agents through one unified interface.
-
-```ts
-await manager.startSession({ name: "claude-task", engine: "claude" });
-await manager.startSession({ name: "codex-task",  engine: "codex"  });
-await manager.startSession({ name: "gemini-task", engine: "gemini" });
-await manager.startSession({ name: "cursor-task", engine: "cursor" });
-```
-
-### Multi-Agent Council
-
-Run multiple agents in parallel with isolated git worktrees, independent reasoning, and review-based collaboration.
-
-```ts
-await manager.councilStart("Design and implement an auth system", {
-  agents: [
-    { name: "Planner",  engine: "claude" },
-    { name: "Builder",  engine: "codex"  },
-    { name: "Reviewer", engine: "claude" },
-  ],
-});
-```
-
-### Autoloop (three-agent autonomous workspace iteration)
-
-You converse with a long-lived **Planner** (Opus) to design `plan.md` and `goal.json`; on your "go" the Planner spawns a **Coder** (Sonnet) and a **Reviewer** (Sonnet, sandboxed cwd) into a self-iterating subloop. Coder applies changes + runs eval, Reviewer audits independently, ledger writes after every iter. The Planner pushes you (wechat → whatsapp → email fallback chain) on regression, target-hit, decision points, or a 30-min stall — silent otherwise.
-
-```ts
-await manager.autoloopStart({ runId: "my-run", workspace: "/path/to/repo" });
-await manager.autoloopChat("my-run", "Read the workspace and design a plan to fix X");
-// Planner reads files, drafts plan.md/goal.json, asks "ready to spawn?"
-await manager.autoloopChat("my-run", "go");
-// → Planner spawns Coder + Reviewer, subloop runs to target / max_iters / your terminate.
-```
-
-SSE stream at `GET /autoloop/<id>/events` (the upcoming 3-pane UI subscribes here). See [`skills/references/autoloop.md`](./skills/references/autoloop.md) for the full operator reference: tool list, push policy, ledger layout, smoke test.
-
-### ultraapp (Forge tab)
-
-A 3-agent Opus council turns a 5-question interview into a deployed web app — Tailwind UI, BYOK, file-queue runtime, smoke test, all live at `localhost:19000/forge/<slug>/`. Iterate via chat: cosmetic ("make button green") runs an Opus patcher; spec-delta ("also output a thumbnail") flips back to a focused interview and rebuilds. See [`skills/references/ultraapp.md`](./skills/references/ultraapp.md).
-
-### Tool Orchestration
-
-Expose coding sessions as tools so other agents and systems can control them. The runtime registers 55 tools, including:
-
-```txt
-session_start         session_send         coding_session_status
-session_grep          session_compact      session_inbox
-team_send             team_list            coding_agents_list
-council_start         council_review       council_accept
-ultraplan_start       ultrareview_start
-autoloop_start        autoloop_chat        autoloop_reset_agent
-ultraapp_new          ultraapp_answer      ultraapp_build_start
-ultraapp_feedback     ultraapp_promote_version
-```
+The full 55-tool surface is enumerated in [`tools.md`](./skills/references/tools.md).
 
 ---
 
 ## Quick Start
 
-### Standalone (no OpenClaw)
-
 ```bash
 npm install -g @enderfga/claw-orchestrator
-clawo serve
-```
-
-```bash
-clawo session-start fix-tests --engine claude --cwd .
-clawo session-send fix-tests "Fix the failing tests"
+clawo serve   # dashboard at http://127.0.0.1:18796/dash
 ```
 
-### Programmatic
-
 ```ts
-import { SessionManager } from "@enderfga/claw-orchestrator";
+import { SessionManager } from '@enderfga/claw-orchestrator';
 
 const manager = new SessionManager();
-await manager.startSession({ name: "task", cwd: "/project" });
-const result = await manager.sendMessage("task", "Fix the failing tests");
+await manager.startSession({ name: 'fix-tests', engine: 'claude', cwd: '/project' });
+const result = await manager.sendMessage('fix-tests', 'Fix the failing tests');
 ```
 
-### Run a multi-agent council
+---
 
-```bash
-clawo council start "Refactor the API layer and add tests"
-```
+## Integrations
 
-### Quick Start: ultraapp
+### Standalone CLI
 
 ```bash
-clawo serve   # dashboard at :18796, router at :19000
+clawo serve                                            # dashboard + HTTP server on :18796
+clawo session-start fix-tests --engine claude --cwd .  # start a session
+clawo session-send fix-tests "Fix the failing tests"   # send into it
 ```
 
-Open the dashboard, pick **Forge → + New**, walk the interview (≈5–8 questions, each with a recommended option), click **Start Build**. The share card lands in chat with the live URL. Iterate via chat for cosmetic / spec-delta changes; **Make Public…** gives Cloudflare Tunnel / ngrok / Tailscale / Caddy snippets.
+Every command is documented in [`cli.md`](./skills/references/cli.md).
 
-Driveable headlessly via 14 MCP tools (`ultraapp_new` / `_answer` / `_build_start` / `_feedback` / `_promote_version` / …) or the matching HTTP routes — see [`skills/references/ultraapp.md`](./skills/references/ultraapp.md).
-
-### As an OpenClaw plugin
-
-If you run OpenClaw, Claw Orchestrator installs as a managed plugin. The same tools (`session_start`, `team_send`, `council_start`, ...) become available to every OpenClaw agent.
+### OpenClaw Plugin
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/Enderfga/claw-orchestrator/main/install.sh | bash
 ```
 
-This installs via npm, registers the plugin in `~/.openclaw/openclaw.json`, and restarts the gateway. See [`skills/references/getting-started.md`](./skills/references/getting-started.md) for the full setup.
-
-### As an MCP server (Hermes Agent, Claude Desktop, Cursor, Cline, Continue, Zed, Windsurf, Goose)
+Installs via npm, registers the plugin in `~/.openclaw/openclaw.json`, restarts the gateway. All 55 tools become available to every OpenClaw agent.
 
-Every host that speaks the [Model Context Protocol](https://modelcontextprotocol.io) can pick up the orchestrator's full toolset (55 tools — sessions, council, ultraplan, ultrareview, autoloop, ultraapp, codex, inbox) over stdio.
+### Model Context Protocol Server
 
 ```bash
-npm install -g @enderfga/claw-orchestrator
-# now `clawo-mcp` is on PATH
+npm install -g @enderfga/claw-orchestrator   # clawo-mcp is now on PATH
 ```
 
-Register it with your host:
-
-<details>
-<summary><strong>Hermes Agent</strong> — <code>~/.hermes/config.yaml</code></summary>
-
-```yaml
-mcp_servers:
-  clawo:
-    command: clawo-mcp
-    env:
-      ANTHROPIC_API_KEY: "..."
-      OPENAI_API_KEY: "..."
-      GEMINI_API_KEY: "..."
-    # Optional: keep the model focused — Hermes will surface only these
-    tools:
-      include: [mcp_clawo_session_start, mcp_clawo_session_send, mcp_clawo_council_start]
-```
-</details>
-
-<details>
-<summary><strong>Claude Desktop / Claude Code</strong> — <code>claude_desktop_config.json</code></summary>
-
-```json
-{
-  "mcpServers": {
-    "clawo": {
-      "command": "clawo-mcp",
-      "env": {
-        "ANTHROPIC_API_KEY": "...",
-        "OPENAI_API_KEY": "...",
-        "CLAWO_MCP_TOOLS": "session_start,session_send,council_start,council_status,ultrareview_start"
-      }
-    }
-  }
-}
-```
-</details>
-
-<details>
-<summary><strong>Cursor / Cline / Continue / Zed / Windsurf / Goose</strong></summary>
-
-Every one of these hosts speaks the standard MCP stdio config. Add `clawo-mcp` as a server with the same `command + args + env` shape — refer to your host's MCP documentation for the exact file path.
-</details>
-
-**Notes**
-
-- Hosts prefix MCP tool names with the server slug (e.g. `mcp_clawo_session_start` in Hermes). The model sees the prefixed name; you don't need to call it manually.
-- `CLAWO_MCP_TOOLS` (comma-separated allowlist) keeps the exposed surface tight when the host has a tight tool budget. Without it, all 55 tools are advertised.
-- Hosts do not forward arbitrary shell env vars to MCP servers — list every API key your engines need (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, etc.) explicitly under `env`.
-
-Full reference: [`skills/references/mcp.md`](./skills/references/mcp.md).
+Register `clawo-mcp` with any MCP-compatible host: Hermes Agent, Claude Desktop, Cursor, Cline, Continue, Zed, Windsurf, Goose, and others. Per-host stdio-config snippets and the `CLAWO_MCP_TOOLS` allowlist for tight tool budgets are in [`mcp.md`](./skills/references/mcp.md).
 
 ---
 
 ## Engine Compatibility
 
-| Engine | CLI | Tested Version | Status |
-|--------|-----|----------------|--------|
-| Claude Code   | `claude` | 2.1.126     | Supported |
-| Codex         | `codex`  | 0.128.0     | Supported |
-| Gemini        | `gemini` | 0.36.0      | Supported |
-| Cursor Agent  | `agent`  | 2026.03.30  | Supported |
-| OpenCode      | `opencode` | 1.1.40    | Supported |
-| Custom CLI    | any      | —           | Supported |
+| Engine       | CLI        | Tested Version |
+| ------------ | ---------- | -------------- |
+| Claude Code  | `claude`   | 2.1.126        |
+| Codex        | `codex`    | 0.128.0        |
+| Gemini       | `gemini`   | 0.36.0         |
+| Cursor Agent | `agent`    | 2026.03.30     |
+| OpenCode     | `opencode` | 1.1.40         |
+| Custom CLI   | any        | —              |
 
-Any coding CLI that can run as a subprocess can be integrated as a custom engine.
-
----
-
-## Architecture
-
-```txt
-                 ┌─────────────────────┐
-                 │  Claw Orchestrator  │
-                 └──────────┬──────────┘
-                            │
-        ┌───────────────────┼───────────────────┐
-        │                   │                   │
- ┌──────▼──────┐     ┌──────▼──────┐     ┌──────▼──────┐
- │ Claude Code │     │    Codex    │     │ Custom CLI  │
- └──────┬──────┘     └──────┬──────┘     └──────┬──────┘
-        │                   │                   │
-        └───────────┬───────┴───────────┬───────┘
-                    │                   │
-             Persistent Sessions   Tool API
-                    │                   │
-                    └──── Multi-Agent Council
-```
-
-For source-level architecture, see [`CLAUDE.md`](./CLAUDE.md). For deeper reference docs, see [`skills/references/`](./skills/references/).
-
----
-
-## Migrating from v2.x
-
-v3.x uses the Claw Orchestrator package, `clawo` CLI, and engine-neutral tool API. The v3.0 compatibility aliases were removed in v3.1.0.
-
-| What | v2.x | Current |
-|---|---|---|
-| npm package | `@enderfga/openclaw-claude-code` | `@enderfga/claw-orchestrator` |
-| CLI binary | `claude-code-skill` | `clawo` |
-| Tool names | `claude_session_start`, `claude_session_send`, ... | `session_start`, `session_send`, ... |
-| OpenClaw plugin id | `openclaw-claude-code` | `claw-orchestrator` |
-
-To upgrade:
-
-```bash
-npm uninstall -g @enderfga/openclaw-claude-code
-npm install -g @enderfga/claw-orchestrator
-curl -fsSL https://raw.githubusercontent.com/Enderfga/claw-orchestrator/main/install.sh | bash
-```
-
-If your OpenClaw config still has an old plugin entry, remove it and register `claw-orchestrator`. Update scripts and tool callers before moving to v3.1.0 or newer.
-
----
-
-## Project Status
-
-Active development. Current focus areas:
-
-- stable multi-engine session management
-- richer council workflows
-- custom engine configuration ergonomics
-- runtime control APIs
-- cleaner CLI and OpenClaw integration
+Any coding CLI that runs as a subprocess can be wired up as a custom engine — see [`multi-engine.md`](./skills/references/multi-engine.md#custom-engine-enginecustom).
 
 ---
 
 ## Contributing
 
-See [`CONTRIBUTING.md`](./CONTRIBUTING.md). PR prefixes (`feat:`, `fix:`, `docs:`, `chore:`, `test:`) are required. Run `npm run build && npm run lint && npm run format:check && npm run test` before submitting.
-
----
+See [`CONTRIBUTING.md`](./CONTRIBUTING.md). Run `npm run build && npm run lint && npm run format:check && npm run test` before submitting.
 
 ## License
 

package/configs/autoloop-coder-prompt.md

@@ -4,56 +4,93 @@ You are the **Coder** in a three-agent autoloop. You make code changes
 toward the goal stated in `plan.md` and `goal.json`. You do **not** talk to
 the user; the Planner is your only interlocutor.
 
-## Identity
+---
 
-- You own the **workspace code**. The Planner owns strategy; you own
-  execution.
-- You receive one directive per iteration. Apply it, run the evaluator, and
-  signal completion.
-- You persist across iterations — your understanding of the codebase
-  accumulates. Use that. When something is non-obvious, write it down in
-  `coder_notes.md` so future iters benefit.
+## ABSOLUTE RULES (read before doing anything)
+
+These rules are non-negotiable. They exist because past iterations of this
+system broke when Coders bent them.
+
+### Rule 1 — Stay inside your scope
+
+The Planner owns `plan.md`, `goal.json`, and anything under `tasks/`. You
+must never modify those files. They are the contract you work against;
+rewriting them is cheating.
+
+If you believe the plan is wrong, do not "fix" it. Emit
+`request_clarification` and let the Planner decide.
+
+### Rule 2 — Do not commit, do not push
+
+The orchestrator git-commits your work after every iteration. Manual
+`git commit` or `git push` from your end pollutes the diff log and
+breaks the Reviewer's ability to see exactly what changed this iter.
+
+If you find yourself reaching for `git commit`, stop. Your work is
+captured by the orchestrator.
+
+### Rule 3 — Never skip the evaluator
+
+If the eval is broken or you can't reach it, emit `request_clarification`
+with a precise description. Do **not** invent a metric value. Do **not**
+report `iter_complete` without a real `eval_output`. The Reviewer will
+catch fabrication, and a `rollback` verdict erases the iter.
+
+### Rule 4 — One focused change per iter
+
+If a directive seems to need touching more than ~5 files or unrelated
+subsystems, stop and emit `request_clarification`. Multi-concern iters
+make Reviewer audits unreliable.
+
+---
 
 ## Your tools
 
 You are a Claude Code session with the workspace as cwd. You have the full
-tool palette: Read, Write, Edit, Glob, Grep, Bash. The orchestrator git-commits
-your work after every iteration; do **not** manually `git commit` — that
-clouds the diff log.
+file-editing palette: Read, Write, Edit, Glob, Grep, Bash. Use them freely
+on workspace code — that's your job. The role boundary is Rule 1: do not
+touch `plan.md`, `goal.json`, or `tasks/`.
 
 You also have **autoloop control tools** via fenced JSON blocks:
 
+````
 ```autoloop
 {"tool": "iter_complete", "args": { ... }}
 ```
+````
 
 | Tool | Args | When to use |
 |---|---|---|
-| `iter_complete` | `summary` (one-line), `eval_output` (object — usually `{ metric: number, gates: [...], extra: {...} }`), `files_changed` (string[], optional — orchestrator computes if omitted) | After you've made changes AND run the evaluator. This signals the iteration is done. |
-| `request_clarification` | `question` (string) | If the directive is too ambiguous to act on. Planner gets this back and replies. Use sparingly — prefer to ship best-guess and let Reviewer flag. |
+| `iter_complete` | `summary` (one-line), `eval_output` (object — usually `{ metric: number, gates: [...], extra: {...} }`), `files_changed` (string[], optional — orchestrator computes if omitted) | After you've made changes AND run the evaluator. This signals the iteration is done. **At most one per turn.** |
+| `request_clarification` | `question` (string) | If the directive is too ambiguous to act on, or if Rule 1/3/4 trip. Planner gets this back and replies. Use sparingly — prefer to ship best-guess and let Reviewer flag, unless ambiguity is load-bearing. |
 | `coder_log` | `message` (string) | Free-form log entry appended to `<ledger>/coder_log.jsonl`. Use for "I tried X and it failed, here's why" so future iters don't repeat. |
 
+---
+
 ## Workflow per iteration
 
 1. **Read the directive.** It is provided as the user-message in this turn.
-2. **Read context** — `plan.md`, `goal.json`, last iter's `iter/<n-1>/verdict.json` if present, `coder_notes.md`.
-3. **Make the change.** One focused change per iter. Avoid bundling unrelated cleanup.
-4. **Run the evaluator** as specified by `goal.json`'s `scalar.extract_cmd` (and any per-gate eval) using Bash.
-5. **Capture eval output** structured. Pull the metric value out of stdout per `goal.json`'s `extract_pattern` if present.
+2. **Read context** — `plan.md`, `goal.json`, last iter's
+   `iter/<n-1>/verdict.json` if present, `coder_notes.md`.
+3. **Make the change.** One focused change per iter (Rule 4). Avoid
+   bundling unrelated cleanup.
+4. **Run the evaluator** as specified by `goal.json`'s `scalar.extract_cmd`
+   (and any per-gate eval) using Bash.
+5. **Capture eval output** structured. Pull the metric value out of stdout
+   per `goal.json`'s `extract_pattern` if present.
 6. **Emit `iter_complete`** with the metric + per-gate pass/fail + any extras.
 
-## Hard rules
-
-- ❌ **Do not modify** `plan.md`, `goal.json`, or anything under `tasks/`. Planner owns those.
-- ❌ **Do not** manually run `git commit` or `git push`. The orchestrator commits after every iter; manual commits break the diff log.
-- ❌ **Do not skip the evaluator.** If the eval is broken, emit `request_clarification` instead of guessing the metric.
-- ❌ **Do not over-edit.** If you find yourself touching >5 files for a "small" directive, stop and emit `request_clarification`.
-- ✅ **Do leave a note** for things you discover that future iters need (`coder_notes.md`). Future-you will thank you.
+---
 
-## Output discipline
+## Style
 
-Your turn output is split:
-- **Prose** — concise narration of what you tried (no banners, no greetings, no apologies).
-- **At most one `iter_complete` block per turn.** Multiple = orchestrator picks the last and warns.
+- **No banners, no greetings, no apologies.** Concise narration of what
+  you tried.
+- **Cite files at `path:line`** so Reviewer / Planner can verify.
+- **Leave notes for your future self.** Append to `coder_notes.md` when
+  you discover something non-obvious (Rule 1 does not apply to
+  `coder_notes.md` — it's yours).
+- **Output discipline.** Prose outside the autoloop fence is shown
+  upstream verbatim. At most one `iter_complete` block per turn.
 
 Begin by reading the directive and acting.