@enderfga/claw-orchestrator 3.7.0 → 4.0.0

package/dist/src/ultraapp/versions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"versions.js","sourceRoot":"","sources":["../../../src/ultraapp/versions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAiBlC,MAAM,UAAU,YAAY,CAAC,WAAmB;IAC9C,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC;QAAE,OAAO,EAAE,CAAC;IAC3C,MAAM,GAAG,GAAmB,EAAE,CAAC;IAC/B,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,WAAW,CAAC,WAAW,CAAC,EAAE,CAAC;QAC5C,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,EAAE,eAAe,CAAC,EAAE,MAAM,CAAC,CAGvF,CAAC;YACF,GAAG,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;QACjC,CAAC;QAAC,MAAM,CAAC;YACP,2BAA2B;QAC7B,CAAC;IACH,CAAC;IACD,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,kBAAkB,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,kBAAkB,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IAClF,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,kBAAkB,CAAC,OAAe;IACzC,MAAM,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACnC,OAAO,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,gBAAgB,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,WAAmB,EAAE,IAA8C;IACjG,EAAE,CAAC,SAAS,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC/C,MAAM,QAAQ,GAAG,YAAY,CAAC,WAAW,CAAC,CAAC;IAC3C,MAAM,IAAI,GAAG,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;IACvC,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;IACzC,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACvC,EAAE,CAAC,aAAa,CACd,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,eAAe,CAAC,EAC/B,IAAI,CAAC,SAAS,CACZ;QACE,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACjC,MAAM,EAAE,IAAI,CAAC,MAAM;KACpB,EACD,IAAI,EACJ,CAAC,CACF,CACF,CAAC;IACF,OAAO,IAAI,CAAC;AACd,CAAC;AAYD,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAc;IAC9C,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAChD,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,IAAI,CAAC,WAAW,CAAC,CAAC;IAClE,MAAM,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,IAAI,CAAC,SAAS,CAAC,CAAC;IAC9D,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC;QAChB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,kBAAkB,IAAI,CAAC,SAAS,qBAAqB,EAAE,CAAC;IACrF,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClC,IAAI,IAAI,EAAE,MAAM,EAAE,CAAC;QACjB,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;YAC7D,iBAAiB;QACnB,CAAC,CAAC,CAAC;IACL,CAAC;IACD,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,EAAE,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;IAC7D,IAAI,CAAC,CAAC,CAAC,EAAE;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC;IAChD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAChD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACtB,CAAC"}

package/dist/src/validation.d.ts

@@ -14,11 +14,11 @@
  */
 export declare function sanitizeCwd(cwd: string | undefined): string | undefined;
 /**
- * Validate that a string is a syntactically valid regular expression.
+ * Compile a user-supplied pattern into an RE2 regex.
  *
- * Returns the compiled RegExp if valid, throws on invalid syntax.
- * Note: this validates syntax only — it does not detect catastrophic
- * backtracking (ReDoS) patterns.
+ * RE2 runs in linear time and never backtracks, so it is immune to ReDoS
+ * patterns like `(a+)+$`. Some PCRE features (lookbehind, backreferences)
+ * are not supported and will throw at compile time.
  */
 export declare function validateRegex(pattern: string): RegExp;
 /**

package/dist/src/validation.js

@@ -8,6 +8,7 @@
 import * as path from 'node:path';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
+import RE2 from 're2';
 // ─── Blocked Path Prefixes ─────────────────────────────────────────────────
 /** System-critical directories that must never be used as a working directory */
 const BLOCKED_PREFIXES = ['/etc', '/proc', '/sys', '/var/run', '/var/log', '/boot', '/sbin'];
@@ -72,15 +73,15 @@ export function sanitizeCwd(cwd) {
 }
 // ─── validateRegex ──────────────────────────────────────────────────────────
 /**
- * Validate that a string is a syntactically valid regular expression.
+ * Compile a user-supplied pattern into an RE2 regex.
  *
- * Returns the compiled RegExp if valid, throws on invalid syntax.
- * Note: this validates syntax only — it does not detect catastrophic
- * backtracking (ReDoS) patterns.
+ * RE2 runs in linear time and never backtracks, so it is immune to ReDoS
+ * patterns like `(a+)+$`. Some PCRE features (lookbehind, backreferences)
+ * are not supported and will throw at compile time.
  */
 export function validateRegex(pattern) {
     try {
-        return new RegExp(pattern, 'i');
+        return new RE2(pattern, 'i');
     }
     catch (err) {
         throw new Error(`Invalid regex pattern: ${err.message}`);

package/dist/src/validation.js.map

@@ -1 +1 @@
-{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/validation.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/validation.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,GAAG,MAAM,KAAK,CAAC;AAEtB,8EAA8E;AAE9E,iFAAiF;AACjF,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AAE7F,iFAAiF;AACjF,MAAM,oBAAoB,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC;AAE1E,+EAA+E;AAE/E;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,GAAuB;IACjD,IAAI,CAAC,GAAG;QAAE,OAAO,SAAS,CAAC;IAE3B,gEAAgE;IAChE,2EAA2E;IAC3E,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAElC,mEAAmE;IACnE,yEAAyE;IACzE,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,IAAI,GAAG,OAAO,CAAC;IACjB,CAAC;IAED,oEAAoE;IACpE,qEAAqE;IACrE,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;IAC9C,KAAK,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,CAAC;QAChC,IAAI,CAAC,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;YAC9B,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;IAED,wBAAwB;IACxB,KAAK,MAAM,KAAK,IAAI,YAAY,EAAE,CAAC;QACjC,IAAI,KAAK,KAAK,GAAG,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CAAC,6BAA6B,OAAO,EAAE,CAAC,CAAC;QAC1D,CAAC;IACH,CAAC;IAED,iCAAiC;IACjC,KAAK,MAAM,KAAK,IAAI,YAAY,EAAE,CAAC;QACjC,KAAK,MAAM,MAAM,IAAI,gBAAgB,EAAE,CAAC;YACtC,IAAI,KAAK,KAAK,MAAM,IAAI,KAAK,CAAC,UAAU,CAAC,MAAM,GAAG,GAAG,CAAC,EAAE,CAAC;gBACvD,MAAM,IAAI,KAAK,CAAC,6BAA6B,OAAO,EAAE,CAAC,CAAC;YAC1D,CAAC;QACH,CAAC;IACH,CAAC;IAED,sCAAsC;IACtC,MAAM,IAAI,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC;IAC1B,KAAK,MAAM,KAAK,IAAI,YAAY,EAAE,CAAC;QACjC,KAAK,MAAM,MAAM,IAAI,oBAAoB,EAAE,CAAC;YAC1C,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YAC1C,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,UAAU,CAAC,SAAS,GAAG,GAAG,CAAC,EAAE,CAAC;gBAC7D,MAAM,IAAI,KAAK,CAAC,6BAA6B,OAAO,EAAE,CAAC,CAAC;YAC1D,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,+EAA+E;AAE/E;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe;IAC3C,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IAC/B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,0BAA2B,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;IACtE,CAAC;AACH,CAAC;AAED,+EAA+E;AAE/E,MAAM,UAAU,GAAG,kBAAkB,CAAC;AAEtC;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,IAAI,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,iBAAiB,IAAI,mDAAmD,CAAC,CAAC;IAC5F,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/openclaw.plugin.json

@@ -98,7 +98,21 @@
       "ultraplan_start",
       "ultraplan_status",
       "ultrareview_start",
-      "ultrareview_status"
+      "ultrareview_status",
+      "ultraapp_list",
+      "ultraapp_get",
+      "ultraapp_status",
+      "ultraapp_new",
+      "ultraapp_answer",
+      "ultraapp_add_file",
+      "ultraapp_spec_edit",
+      "ultraapp_build_start",
+      "ultraapp_build_cancel",
+      "ultraapp_feedback",
+      "ultraapp_promote_version",
+      "ultraapp_start_container",
+      "ultraapp_stop_container",
+      "ultraapp_delete"
     ]
   },
   "skills": ["skills/SKILL.md"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enderfga/claw-orchestrator",
-  "version": "3.7.0",
+  "version": "4.0.0",
   "description": "Claw Orchestrator — run Claude Code, Codex, Gemini, Cursor Agent, OpenCode and custom coding CLIs as one unified runtime. Drop into Hermes Agent, Claude Desktop, Cursor, Cline, Continue, Zed, Windsurf, Goose or any Model Context Protocol (MCP) host, install as an OpenClaw plugin, or run standalone. Persistent sessions, multi-agent council, ultraplan, ultrareview, autoloop, tool orchestration.",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -91,13 +91,16 @@
   "license": "MIT",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "commander": "^12.1.0"
+    "commander": "^12.1.0",
+    "diff": "^9.0.0",
+    "re2": "^1.24.0"
   },
   "peerDependencies": {
     "openclaw": ">=2026.3.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.15.0",
+    "@types/diff": "^7.0.2",
     "@types/node": "^22.10.0",
     "@vitest/coverage-v8": "^3.1.0",
     "eslint": "^9.15.0",

package/skills/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: claw-orchestrator
-description: Manage persistent coding sessions across Claude Code, Codex, Gemini, Cursor, and OpenCode engines. Use when orchestrating multi-engine coding agents, starting/sending/stopping sessions, running multi-agent council collaborations, cross-session messaging, ultraplan deep planning, ultrareview parallel code review, autoloop autonomous workspace iteration, switching models/tools at runtime, or exposing the orchestrator's 41 tools as an MCP server to Hermes Agent / Claude Desktop / Cursor / Cline / Continue / Zed / Windsurf / Goose. Triggers on "start a session", "send to session", "run council", "ultraplan", "ultrareview", "autoloop", "autonomous iteration", "iterate until goal", "deep paper review", "auto research", "switch model", "multi-agent", "coding session", "session inbox", "cursor agent", "opencode", "mcp server", "clawo-mcp", "hermes mcp", "model context protocol".
+description: Manage persistent coding sessions across Claude Code, Codex, Gemini, Cursor, and OpenCode engines. Use when orchestrating multi-engine coding agents, starting/sending/stopping sessions, running multi-agent council collaborations, cross-session messaging, ultraplan deep planning, ultrareview parallel code review, autoloop autonomous workspace iteration, ultraapp building deployable web apps from a structured Q&A interview, switching models/tools at runtime, or exposing the orchestrator's 55 tools as an MCP server to Hermes Agent / Claude Desktop / Cursor / Cline / Continue / Zed / Windsurf / Goose. Triggers on "start a session", "send to session", "run council", "ultraplan", "ultrareview", "autoloop", "ultraapp", "Forge tab", "build a web app", "one-click app", "AppSpec", "autonomous iteration", "iterate until goal", "deep paper review", "auto research", "switch model", "multi-agent", "coding session", "session inbox", "cursor agent", "opencode", "mcp server", "clawo-mcp", "hermes mcp", "model context protocol".
 metadata:
   {
     "openclaw":
@@ -43,7 +43,7 @@ metadata:
 
 # Claw Orchestrator Skill
 
-Claw Orchestrator — persistent multi-engine coding session manager for claw-style agent systems. Runs as a standalone CLI/server, with first-class OpenClaw plugin support. Wraps Claude Code, Codex, Gemini, Cursor Agent, OpenCode, and custom CLIs into headless agentic engines with 35 tools.
+Claw Orchestrator — persistent multi-engine coding session manager for claw-style agent systems. Runs as a standalone CLI/server, with first-class OpenClaw plugin support. Wraps Claude Code, Codex, Gemini, Cursor Agent, OpenCode, and custom CLIs into headless agentic engines with 55 tools.
 
 ## Engine Quick Reference
 

package/skills/references/autoloop.md

@@ -5,7 +5,7 @@ the **Planner** to design a plan; on your approval, the Planner spawns the
 **Coder** + **Reviewer** subloop, monitors it, and pushes you (wechat →
 whatsapp → email fallback chain) only when something needs your attention.
 
-Design rationale: `tasks/autoloop.md`. This page is the operator reference.
+This page is the operator reference.
 
 ## When to use
 

package/skills/references/mcp.md

@@ -1,6 +1,6 @@
 # MCP integration
 
-Claw Orchestrator ships a Model Context Protocol (MCP) server (`clawo-mcp`) so any MCP-compatible host can drive its 41 tools.
+Claw Orchestrator ships a Model Context Protocol (MCP) server (`clawo-mcp`) so any MCP-compatible host can drive its 55 tools.
 
 This document covers:
 
@@ -229,7 +229,7 @@ The engines themselves (`claude`, `codex`, `gemini`, `agent`, `opencode`) must a
 
 ## Tool filtering
 
-41 tools is a lot for a small context window. Reduce noise either at the host level (most hosts have an `include` / `exclude` filter — see Hermes example above) or at the server level via `CLAWO_MCP_TOOLS`:
+55 tools is a lot for a small context window. Reduce noise either at the host level (most hosts have an `include` / `exclude` filter — see Hermes example above) or at the server level via `CLAWO_MCP_TOOLS`:
 
 ```bash
 CLAWO_MCP_TOOLS="session_start,session_send,session_stop,council_start,council_status" clawo-mcp

package/skills/references/tools.md

@@ -414,3 +414,186 @@ Get status and findings when completed.
 | Parameter | Type | Required |
 |-----------|------|----------|
 | `id` | string | yes |
+
+---
+
+## Autoloop (6)
+
+Three-agent autonomous iteration loop (Planner / Coder / Reviewer) over a git workspace. See [`autoloop.md`](./autoloop.md) for the operator reference (push policy, ledger layout, smoke test).
+
+### `autoloop_start`
+
+Start an autoloop run. Planner is created persistent; Coder + Reviewer are spawned by the Planner once `plan.md` is ready.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `cwd` | string | yes | Workspace (must be a git repo) |
+| `goal` | string | yes | High-level user goal in natural language |
+| `model` | string | | Planner model (default Opus) |
+| `coderModel` | string | | Coder subagent model |
+| `reviewerModel` | string | | Reviewer subagent model |
+| `maxIters` | number | | Cap on Coder/Reviewer rounds (default 50) |
+| `pushChannels` | string[] | | Notification channels (`wechat`, `whatsapp`, `email`) |
+
+### `autoloop_chat`
+
+Send a message into the Planner conversation (e.g. answer a clarifying question, refine the plan, kick off the subloop).
+
+| Parameter | Type | Required |
+|-----------|------|----------|
+| `id` | string | yes |
+| `message` | string | yes |
+
+### `autoloop_status`
+
+Get current state, phase, recent inbox messages, and ledger summary.
+
+| Parameter | Type | Required |
+|-----------|------|----------|
+| `id` | string | yes |
+
+### `autoloop_list`
+
+List active and recent autoloop runs (in-memory + on-disk registry, deduped by run_id).
+
+(no params)
+
+### `autoloop_reset_agent`
+
+Reset one of the subagent sessions (Coder or Reviewer) without losing Planner state — useful when a subagent loops on a stale belief.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | yes | Run id |
+| `agent` | `'coder'` \| `'reviewer'` | yes | Which subagent to reset |
+
+### `autoloop_stop`
+
+Terminate the run. All sessions are stopped and ledger state is finalised.
+
+| Parameter | Type | Required |
+|-----------|------|----------|
+| `id` | string | yes |
+
+---
+
+## Ultraapp (14)
+
+Forge tab — turn a structured Q&A interview into a deployed web app reachable at `localhost:19000/forge/<slug>/`. See [`ultraapp.md`](./ultraapp.md) for the operator reference (lifecycle, conventions §1–§7, runtime modes, file layout, HTTP routes).
+
+### `ultraapp_list`
+
+List all ultraapp runs.
+
+(no params)
+
+### `ultraapp_get`
+
+Full snapshot of a run: spec + chat + state.
+
+| Parameter | Type | Required |
+|-----------|------|----------|
+| `id` | string | yes |
+
+### `ultraapp_status`
+
+Lightweight status (mode + timestamps).
+
+| Parameter | Type | Required |
+|-----------|------|----------|
+| `id` | string | yes |
+
+### `ultraapp_new`
+
+Create a fresh run. Optionally seeds the interview with the user's first message.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `firstMessage` | string | | Free-form opening line; the interview Opus reads it before its first question |
+
+### `ultraapp_answer`
+
+Submit an answer to the current interview question.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | yes | Run id |
+| `value` | string | yes | One of the question's `options[].value`, or `''` when using freeform |
+| `freeform` | string | | Free-form text when none of the options fit |
+
+### `ultraapp_add_file`
+
+Upload a sample file to `examples/` (the interview engine will `extract_metadata` it).
+
+| Parameter | Type | Required |
+|-----------|------|----------|
+| `id` | string | yes |
+| `path` | string | yes |
+| `content` | string \| Buffer | yes |
+
+### `ultraapp_spec_edit`
+
+Apply RFC 6902 JSON Patch ops to the AppSpec mid-interview.
+
+| Parameter | Type | Required |
+|-----------|------|----------|
+| `id` | string | yes |
+| `patch` | object[] | yes |
+
+### `ultraapp_build_start`
+
+Validate the spec strictly (shape + cross-refs + DAG) and enqueue the build. Council picks it up FIFO.
+
+| Parameter | Type | Required |
+|-----------|------|----------|
+| `id` | string | yes |
+
+### `ultraapp_build_cancel`
+
+Abort an active build. Council sessions are stopped and the worktrees are left as-is for inspection.
+
+| Parameter | Type | Required |
+|-----------|------|----------|
+| `id` | string | yes |
+
+### `ultraapp_feedback`
+
+Done-mode feedback. Haiku classifier routes into `cosmetic` (Opus patcher), `spec-delta` (focused interview + auto-rerun), or `structural` (suggest fresh run).
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | yes | Run id |
+| `text` | string | yes | The feedback (1+ chars) |
+
+### `ultraapp_promote_version`
+
+Atomically swap the deployed version. Stops the current container/process, starts the target's, updates the router map.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | yes | Run id |
+| `version` | string | yes | Target version label (`v1`, `v2`, …) |
+
+### `ultraapp_start_container`
+
+Start the container/process for the active version (no-op if already running).
+
+| Parameter | Type | Required |
+|-----------|------|----------|
+| `id` | string | yes |
+
+### `ultraapp_stop_container`
+
+Stop the container/process without deleting any state.
+
+| Parameter | Type | Required |
+|-----------|------|----------|
+| `id` | string | yes |
+
+### `ultraapp_delete`
+
+Stop + remove the run completely (sessions, container, on-disk state, router entry).
+
+| Parameter | Type | Required |
+|-----------|------|----------|
+| `id` | string | yes |

package/skills/references/ultraapp.md

@@ -0,0 +1,203 @@
+# ultraapp — Reference
+
+Turn a structured Q&A interview into a deployed web app reachable at
+`localhost:19000/forge/<slug>/`. The dashboard's **Forge** tab and a
+14-tool MCP surface drive the end-to-end loop: interview → 3-agent
+council → fix-on-failure → deploy → done-mode feedback.
+
+This page is the operator reference. The interview behavioural contract
+lives in [`skills/ultraapp/SKILL.md`](../ultraapp/SKILL.md). The
+council architectural conventions every generated app must satisfy live
+in [`src/ultraapp/conventions.ts`](../../src/ultraapp/conventions.ts).
+
+## When to use
+
+- You have a workflow in your head (or a sample input file) and want a
+  shareable web app for it without writing code.
+- You want to iterate cosmetically on a deployed app via chat ("make
+  the button green", "shrink the hero h1") without touching the
+  codebase yourself.
+- You want to evolve the AppSpec ("also output a thumbnail") and
+  rebuild without restarting the interview.
+
+## Lifecycle
+
+```text
+interview ─► queued ─► building ─► build-complete ─► deploying ─► done
+                                                                    │
+                                                                    ▼
+                                                              done-mode chat
+                                                              (cosmetic /
+                                                               spec-delta /
+                                                               structural)
+```
+
+| Mode | Meaning |
+|------|---------|
+| `interview` | AppSpec being filled by Q&A. Chat input goes to the interview Opus. |
+| `queued` | Build accepted, waiting for a slot in the FIFO build queue. |
+| `building` | Council writing code, fix-on-failure driving install/build/test. |
+| `build-complete` | Codebase ready, awaiting `deploy` step. |
+| `deploying` | Container/process being started, router map being updated. |
+| `done` | App live at `/forge/<slug>/`. Chat input now goes to the done-mode classifier. |
+| `failed` | Council didn't reach consensus, or fix-on-failure couldn't get the build green. |
+
+## Architectural conventions (§1–§7)
+
+Every generated app MUST satisfy these. They're embedded in the council
+super-task prompt verbatim from `src/ultraapp/conventions.ts`.
+
+| § | Topic | Headline rule |
+|---|-------|---------------|
+| 1 | Path-based deploy | Mount at `BASE_PATH=/forge/<slug>/`; in-app links MUST be relative. |
+| 2 | Async file-queue runtime | Exact endpoints: `GET /`, `POST /run`, `GET /status/:jobId`, `GET /result/:jobId`, `GET /health`. File-based job queue under `$DATA_DIR/jobs/<jobId>/`. NO database. Data path from `process.env.DATA_DIR ?? '/data'`. |
+| 3 | BYOK | If `runtime.needsLLM`, API keys live in browser localStorage and are sent direct to the provider. The server MUST NEVER receive the key (enforced by `eslint-plugin-no-server-keys`). |
+| 4 | Dockerfile + smoke test | Single multi-stage Dockerfile, `npm run smoke` drives one full job in < 90s using `examples[0].ref`. |
+| 5 | Council voting protocol | 3 agents in git worktrees, all-YES vote required, max 8 rounds. |
+| 6 | Tech stack | Modern TypeScript / JavaScript framework (Next.js, Vite + Hono, SvelteKit). NO Python, NO pure SSGs. |
+| 7 | **Frontend quality** | **Real styling system + real type hierarchy + four-state coverage on every async surface + drag-and-drop forms + appropriate result presentation + one deliberate theme.** §7g requires every agent to capture Chrome-headless screenshots at 1440×900 AND 375×812 and visually inspect the PNGs before voting YES — source-code review is explicitly insufficient evidence. |
+
+## Runtime modes
+
+```bash
+clawo serve --ultraapp-runtime host    # default
+clawo serve --ultraapp-runtime docker  # opt-in
+```
+
+| Mode | Build | Run | Pros | Cons |
+|------|-------|-----|------|------|
+| `host` | `npm install && npm run build` | `npm start` (detached, `setsid`-equivalent) | Zero extra deps; works anywhere Node works; faster start. | No process isolation; deps installed under the user. |
+| `docker` | `docker build .` | `docker run -d --restart unless-stopped` | Per-app isolation, restart policy, image is the artefact. | Requires a running Docker daemon. |
+
+Both modes allocate a backend port in `[19100, 19999]`. The reverse-
+proxy router runs at port `19000` (auto-fallback up to `19099` if
+taken) and maps `/forge/<slug>/*` to the right backend. Slug→port map
+persists to `~/.claw-orchestrator/_router.json`. Host-mode pid metadata
+persists to `~/.claw-orchestrator/host-procs.json`.
+
+## File layout (per run)
+
+```text
+~/.claw-orchestrator/ultraapps/<runId>/
+├── spec.json                  # current AppSpec (latest)
+├── spec.history.jsonl         # every accepted update_spec patch
+├── chat.jsonl                 # all chat turns (interview + done-mode)
+├── state.json                 # { runId, mode, createdAt, updatedAt }
+├── examples/                  # uploaded sample files
+├── data/                      # passed to host-mode app as DATA_DIR
+├── council-project/           # fresh git repo the council collaborates in
+│   ├── .worktrees/{agent-A,agent-B,agent-C}/
+│   └── (council code, merged to main on consensus)
+└── versions/
+    ├── v1/
+    │   ├── codebase/          # snapshot of council main HEAD
+    │   └── artifact.json      # { worktreePath, builtAt, deploy: { url, port, … } }
+    └── v2/                    # patcher / spec-delta produces v2, v3, …
+```
+
+## HTTP routes (drive headlessly)
+
+All routes are served by the embedded server (default `:18796`), under
+`Authorization: Bearer <token>` from `~/.openclaw/server-token`.
+
+| Method + path | Purpose |
+|----|----|
+| `GET /ultraapp/list` | All runs with mode + createdAt. |
+| `POST /ultraapp/new` | Body: `{ firstMessage?: string }`. Returns `{ runId }`. |
+| `GET /ultraapp/<id>` | Full snapshot: spec + chat + state. |
+| `POST /ultraapp/<id>/answer` | Body: `{ value, freeform? }`. Submit interview answer. |
+| `POST /ultraapp/<id>/spec-edit` | Body: RFC 6902 patch ops. Edit the spec mid-interview. |
+| `POST /ultraapp/<id>/files` | Multipart upload to `examples/`. |
+| `GET /ultraapp/<id>/events` | SSE stream of build/chat events (mode pill, narrator, council activity). |
+| `POST /ultraapp/<id>/build` | Validate spec strictly + enqueue. |
+| `POST /ultraapp/<id>/build/cancel` | Abort the active build. |
+| `GET /ultraapp/<id>/artifacts` | List `versions/vN/`. |
+| `POST /ultraapp/<id>/start` | Start the deployed container/process for the active version. |
+| `POST /ultraapp/<id>/stop` | Stop without deleting. |
+| `POST /ultraapp/<id>/delete` | Stop + remove all per-run state. |
+| `POST /ultraapp/<id>/feedback` | Body: `{ text }`. Done-mode classifier routes cosmetic / spec-delta / structural. |
+| `POST /ultraapp/<id>/promote-version` | Body: `{ version: "vN" }`. Atomically swap deployed version. |
+
+## MCP tools (14)
+
+Same surface as HTTP, callable from any Model Context Protocol host
+(Claude Desktop, Hermes Agent, Cursor, Cline, Continue, Zed,
+Windsurf, Goose). Param schemas in [`tools.md`](./tools.md#ultraapp).
+
+```text
+ultraapp_list           ultraapp_get             ultraapp_status
+ultraapp_new            ultraapp_answer          ultraapp_add_file
+ultraapp_spec_edit      ultraapp_build_start     ultraapp_build_cancel
+ultraapp_feedback       ultraapp_promote_version
+ultraapp_start_container ultraapp_stop_container ultraapp_delete
+```
+
+## Done-mode feedback classification
+
+After the run reaches `done`, chat input goes to a per-run Haiku
+classifier. Three classes:
+
+| Class | Routes to | Behaviour |
+|-------|-----------|-----------|
+| `cosmetic` | Patcher | Opus generates a unified diff against the deployed worktree → `applyUnifiedDiff` → validate via fix-on-failure → on success snapshot to `versions/vN+1/`, on any failure restore the snapshot atomically and post the reason to chat. |
+| `spec-delta` | Focused interview | Flips mode back to `interview` with a bootstrap message that names the field(s) being changed. Completion auto-triggers a fresh `startBuild`. |
+| `structural` | Suggestion only | Posts a narrator note: "this sounds like a different app — click + New". |
+
+To swap which version is live, use `promote-version` (HTTP) or
+`ultraapp_promote_version` (MCP) — the router map and host-procs map
+update atomically.
+
+## Reference traces + replay
+
+5 captured JSONL traces of real interviews ground-truth the interview
+engine against drift:
+
+```text
+src/__tests__/fixtures/ultraapp-traces/
+├── text-summariser.jsonl      (synthetic, simple text in/out)
+├── image-batch-resize.jsonl   (batch upload + Pillow + zip)
+├── vlog-cut.jsonl             (ffmpeg + whisper + branching DAG)
+├── llm-agent-pipeline.jsonl   (BYOK, multi-step LLM)
+├── branching-dag.jsonl        (parallel paths converging)
+├── _format.md                 (trace JSONL schema)
+└── expected/<name>.appspec.json   (frozen target)
+```
+
+```bash
+tsx test-ultraapp-integration.ts --trace=image-batch-resize
+tsx test-ultraapp-integration.ts --trace=all
+```
+
+The `spec-extraction-quality.test.ts` test replays each trace through
+the interview engine and asserts the resulting `AppSpec` matches the
+frozen snapshot — any future engine or skill drift fails this test.
+
+## Operator quick start
+
+```bash
+# 1. Boot
+clawo serve   # dashboard at :18796, ultraapp router at :19000
+open "http://127.0.0.1:18796/dashboard?token=$(cat ~/.openclaw/server-token)"
+
+# 2. Forge tab → + New → walk through the interview
+
+# 3. After [Start Build] (or POST /ultraapp/<id>/build), watch:
+#      mode pill: queued → building → done
+#      narrator: short conversational chat updates
+#      Versions panel: v1, v2, … with Promote per row
+
+# 4. Live URL appears in the share card. The deployed app is reachable at:
+curl http://127.0.0.1:19000/forge/<slug>/health
+```
+
+## Known limitations (v4.0.0)
+
+- The done-mode patcher loop occasionally hangs between
+  feedback-classification and the patcher Opus session creation;
+  cosmetic changes can be applied manually until the underlying race
+  is fixed.
+- The §7g frontend gate currently relies on per-agent honesty about
+  running the screenshot capture; agents that skip the inspection can
+  still pass the smoke gate. A follow-up will plumb a server-side
+  screenshot validator into the council verifier so the gate becomes
+  structurally enforced rather than persona-enforced.