@enderfga/claw-orchestrator 3.0.0

package/dist/src/validation.js

@@ -0,0 +1,104 @@
+/**
+ * Shared validation utilities for input sanitization.
+ *
+ * Used by both the plugin tool handlers (index.ts) and the embedded HTTP
+ * server (embedded-server.ts) to ensure consistent protection regardless
+ * of entry point.
+ */
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+// ─── 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'];
+/** Sensitive directories under the user's home that must never be used as cwd */
+const BLOCKED_HOME_SUBDIRS = ['.ssh', '.gnupg', '.aws', '.config/gcloud'];
+// ─── sanitizeCwd ────────────────────────────────────────────────────────────
+/**
+ * Resolve and validate a working directory path.
+ *
+ * Prevents path traversal and blocks access to system-critical and
+ * sensitive directories. Resolves symlinks where possible to defeat
+ * symlink-based bypasses.
+ */
+export function sanitizeCwd(cwd) {
+    if (!cwd)
+        return undefined;
+    // Logical path: resolves .. and . but does NOT follow symlinks.
+    // This catches the obvious cases (/etc, /var/run, /sbin) on all platforms.
+    const logical = path.resolve(cwd);
+    // Real path: follows symlinks. This catches symlink-based bypasses
+    // (e.g. /tmp/safe → /etc). Falls back to logical for non-existent paths.
+    let real;
+    try {
+        real = fs.realpathSync(cwd);
+    }
+    catch {
+        real = logical;
+    }
+    // Collect all paths to check — logical, real, and their de-prefixed
+    // variants for macOS where /etc → /private/etc, /var → /private/var.
+    const pathsToCheck = new Set([logical, real]);
+    for (const p of [logical, real]) {
+        if (p.startsWith('/private/')) {
+            pathsToCheck.add(p.slice('/private'.length));
+        }
+    }
+    // Block filesystem root
+    for (const check of pathsToCheck) {
+        if (check === '/') {
+            throw new Error(`Unsafe working directory: ${logical}`);
+        }
+    }
+    // Block system-critical prefixes
+    for (const check of pathsToCheck) {
+        for (const prefix of BLOCKED_PREFIXES) {
+            if (check === prefix || check.startsWith(prefix + '/')) {
+                throw new Error(`Unsafe working directory: ${logical}`);
+            }
+        }
+    }
+    // Block sensitive home subdirectories
+    const home = os.homedir();
+    for (const check of pathsToCheck) {
+        for (const subdir of BLOCKED_HOME_SUBDIRS) {
+            const sensitive = path.join(home, subdir);
+            if (check === sensitive || check.startsWith(sensitive + '/')) {
+                throw new Error(`Unsafe working directory: ${logical}`);
+            }
+        }
+    }
+    return real;
+}
+// ─── validateRegex ──────────────────────────────────────────────────────────
+/**
+ * Validate that a string is a syntactically valid regular expression.
+ *
+ * Returns the compiled RegExp if valid, throws on invalid syntax.
+ * Note: this validates syntax only — it does not detect catastrophic
+ * backtracking (ReDoS) patterns.
+ */
+export function validateRegex(pattern) {
+    try {
+        return new RegExp(pattern, 'i');
+    }
+    catch (err) {
+        throw new Error(`Invalid regex pattern: ${err.message}`);
+    }
+}
+// ─── validateName ───────────────────────────────────────────────────────────
+const VALID_NAME = /^[a-zA-Z0-9_-]+$/;
+/**
+ * Validate a resource name (agent, skill, rule) to prevent path injection.
+ *
+ * Only allows alphanumeric characters, hyphens, and underscores.
+ * Rejects empty strings, dots, slashes, spaces, and any other characters
+ * that could be used for path traversal.
+ */
+export function validateName(name) {
+    if (!name || !VALID_NAME.test(name)) {
+        throw new Error(`Invalid name '${name}': must be non-empty and match /^[a-zA-Z0-9_-]+$/`);
+    }
+    return name;
+}
+//# sourceMappingURL=validation.js.map

package/dist/src/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/validation.ts"],"names":[],"mappings":"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"}

package/openclaw.plugin.json

@@ -0,0 +1,122 @@
+{
+  "id": "claw-orchestrator",
+  "name": "Claw Orchestrator",
+  "description": "Run Claude Code, Codex, Gemini, Cursor Agent and custom coding CLIs as one unified runtime. Persistent sessions, multi-engine orchestration, multi-agent council, worktree isolation, multi-model proxy, structured output, plan mode workflows.",
+  "enabledByDefault": false,
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "claudeBin": {
+        "type": "string",
+        "default": "claude",
+        "description": "Path to Claude Code CLI binary"
+      },
+      "defaultModel": {
+        "type": "string",
+        "description": "Default model for new sessions"
+      },
+      "defaultPermissionMode": {
+        "type": "string",
+        "enum": ["acceptEdits", "bypassPermissions", "default", "delegate", "dontAsk", "plan", "auto"],
+        "default": "acceptEdits"
+      },
+      "defaultEffort": {
+        "type": "string",
+        "enum": ["low", "medium", "high", "max", "auto"],
+        "default": "auto"
+      },
+      "maxConcurrentSessions": {
+        "type": "number",
+        "default": 5,
+        "description": "Maximum concurrent Claude Code sessions"
+      },
+      "sessionTtlMinutes": {
+        "type": "number",
+        "default": 120,
+        "description": "Auto-cleanup idle sessions after N minutes"
+      },
+      "proxy": {
+        "type": "object",
+        "description": "Multi-model proxy settings for Gemini/GPT/other model support via Anthropic format translation",
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "Enable built-in multi-model proxy"
+          },
+          "bigModel": {
+            "type": "string",
+            "default": "gemini-2.5-pro",
+            "description": "Default model for complex requests"
+          },
+          "smallModel": {
+            "type": "string",
+            "default": "gemini-2.5-flash",
+            "description": "Default model for fast requests"
+          }
+        }
+      }
+    }
+  },
+  "capabilities": {
+    "childProcess": true,
+    "networkAccess": ["127.0.0.1"]
+  },
+  "contracts": {
+    "tools": [
+      "session_start",
+      "session_send",
+      "session_stop",
+      "session_list",
+      "sessions_overview",
+      "session_status",
+      "session_grep",
+      "session_compact",
+      "agents_list",
+      "team_list",
+      "team_send",
+      "session_update_tools",
+      "session_switch_model",
+      "project_purge",
+      "codex_resume",
+      "codex_review",
+      "codex_goal_set",
+      "codex_goal_get",
+      "codex_goal_pause",
+      "codex_goal_resume",
+      "codex_goal_clear",
+      "council_start",
+      "council_status",
+      "council_abort",
+      "council_inject",
+      "council_review",
+      "council_accept",
+      "council_reject",
+      "session_send_to",
+      "session_inbox",
+      "session_deliver_inbox",
+      "ultraplan_start",
+      "ultraplan_status",
+      "ultrareview_start",
+      "ultrareview_status",
+      "claude_session_start",
+      "claude_session_send",
+      "claude_session_stop",
+      "claude_session_list",
+      "claude_sessions_overview",
+      "claude_session_status",
+      "claude_session_grep",
+      "claude_session_compact",
+      "claude_agents_list",
+      "claude_team_list",
+      "claude_team_send",
+      "claude_session_update_tools",
+      "claude_session_switch_model",
+      "claude_project_purge",
+      "claude_session_send_to",
+      "claude_session_inbox",
+      "claude_session_deliver_inbox"
+    ]
+  },
+  "skills": ["skills/SKILL.md"]
+}

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@enderfga/claw-orchestrator",
+  "version": "3.0.0",
+  "description": "Claw Orchestrator — run Claude Code, Codex, Gemini, Cursor Agent and custom coding CLIs as one unified runtime for claw-style agent systems. Runs standalone, with first-class OpenClaw plugin support. Persistent sessions, multi-agent council, tool orchestration.",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "bin": {
+    "clawo": "./dist/bin/cli.js",
+    "claude-code-skill": "./dist/bin/cli.js"
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/src/index.js"
+    ],
+    "hooks": {}
+  },
+  "files": [
+    "dist/",
+    "configs/",
+    "skills/",
+    "openclaw.plugin.json",
+    "README.md",
+    "LICENSE",
+    "assets/banner.jpg"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src/ bin/",
+    "lint:fix": "eslint src/ bin/ --fix",
+    "format": "prettier --write 'src/**/*.ts' 'bin/**/*.ts'",
+    "format:check": "prettier --check 'src/**/*.ts' 'bin/**/*.ts'",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "keywords": [
+    "claw-orchestrator",
+    "coding-agent",
+    "agent-orchestration",
+    "claude-code",
+    "codex",
+    "gemini",
+    "cursor",
+    "multi-agent",
+    "agent-council",
+    "session-management",
+    "openclaw",
+    "mcp"
+  ],
+  "author": "enderfga",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Enderfga/claw-orchestrator.git"
+  },
+  "homepage": "https://github.com/Enderfga/claw-orchestrator#readme",
+  "bugs": {
+    "url": "https://github.com/Enderfga/claw-orchestrator/issues"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.3.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.15.0",
+    "@types/node": "^22.10.0",
+    "@vitest/coverage-v8": "^3.1.0",
+    "eslint": "^9.15.0",
+    "eslint-config-prettier": "^10.1.0",
+    "prettier": "^3.5.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.20.0",
+    "vitest": "^3.1.0"
+  }
+}

package/skills/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: claw-orchestrator
+description: Manage persistent coding sessions across Claude Code, Codex, Gemini, and Cursor 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, or switching models/tools at runtime. Triggers on "start a session", "send to session", "run council", "ultraplan", "ultrareview", "switch model", "multi-agent", "coding session", "session inbox", "cursor agent".
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "🤖",
+        "requires": { "anyBins": ["claude", "codex", "gemini", "agent"] },
+        "install":
+          [
+            {
+              "id": "npm-plugin",
+              "kind": "node",
+              "package": "@enderfga/claw-orchestrator",
+              "label": "Install plugin (npm)"
+            },
+            {
+              "id": "node-claude",
+              "kind": "node",
+              "package": "@anthropic-ai/claude-code",
+              "bins": ["claude"],
+              "label": "Install Claude Code CLI"
+            },
+            {
+              "id": "node-codex",
+              "kind": "node",
+              "package": "@openai/codex",
+              "bins": ["codex"],
+              "label": "Install Codex CLI"
+            },
+            {
+              "id": "node-gemini",
+              "kind": "node",
+              "package": "@google/gemini-cli",
+              "bins": ["gemini"],
+              "label": "Install Gemini CLI"
+            }
+          ]
+      }
+  }
+---
+
+# 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, and custom CLIs into headless agentic engines with 35 tools.
+
+## Engine Quick Reference
+
+| Engine | CLI | Session Type | Best For |
+|--------|-----|-------------|----------|
+| `claude` | `claude` | Persistent subprocess | Multi-turn, complex tasks |
+| `codex` | `codex exec` | Per-message spawn | One-shot execution |
+| `gemini` | `gemini -p` | Per-message spawn | One-shot execution |
+| `cursor` | `agent -p` | Per-message spawn | One-shot execution |
+
+## Core Workflow
+
+```javascript
+// 1. Start session (any engine)
+claude_session_start({ name: "myproject", cwd: "/path/to/project", engine: "claude" })
+claude_session_start({ name: "codex-task", cwd: "/path/to/project", engine: "codex" })
+claude_session_start({ name: "gemini-task", cwd: "/path/to/project", engine: "gemini" })
+claude_session_start({ name: "cursor-task", cwd: "/path/to/project", engine: "cursor" })
+
+// 2. Send messages
+claude_session_send({ name: "myproject", message: "Fix the auth bug" })
+
+// 3. Check status / search history
+claude_session_status({ name: "myproject" })
+claude_session_grep({ name: "myproject", pattern: "error" })
+
+// 4. Stop when done
+claude_session_stop({ name: "myproject" })
+```
+
+## Session Options
+
+| Parameter | Description |
+|-----------|-------------|
+| `engine` | `claude` (default), `codex`, `gemini`, `cursor` |
+| `model` | Model name or alias (`opus`, `sonnet`, `haiku`, `gpt-5.4`, `gemini-pro`, `composer-2`) |
+| `permissionMode` | `acceptEdits`, `auto`, `plan`, `bypassPermissions`, `default` |
+| `effort` | `low`, `medium`, `high`, `xhigh`, `max`, `auto` (`xhigh` is Opus 4.7-only, between `high` and `max`) |
+| `maxBudgetUsd` | Cost limit in USD |
+| `allowedTools` | List of allowed tool names |
+
+### CLI 2.1.111 options
+
+| Parameter | Description |
+|-----------|-------------|
+| `bare` | Minimal mode — no CLAUDE.md, hooks, LSP, auto-memory. Auto-enables prompt cache optimizations (see below). |
+| `includeHookEvents` | Stream hook lifecycle events (PreToolUse/PostToolUse). |
+| `permissionPromptTool` | Delegate permission prompts to an MCP tool for non-interactive use. |
+| `excludeDynamicSystemPromptSections` | Move cwd/env/git from system prompt to user message for better prompt cache hits. Auto-enabled with `bare: true`. |
+| `enablePromptCaching1H` | Enable 1-hour prompt cache TTL (vs default 5-min). Auto-enabled with `bare: true`. |
+| `debug` / `debugFile` | Targeted debug output by category (e.g. `"api,mcp"`) and optional file path. |
+| `fromPr` | Resume a session linked to a GitHub PR number or URL. |
+| `channels` / `dangerouslyLoadDevelopmentChannels` | MCP channel subscriptions (research preview). |
+
+### CLI 2.1.121 options
+
+| Parameter | Description |
+|-----------|-------------|
+| `forkSubagent` | Fork subagent for non-interactive sessions (sets `CLAUDE_CODE_FORK_SUBAGENT=1`). |
+| `enableToolSearch` | Enable Vertex AI tool search (sets `ENABLE_TOOL_SEARCH=1`). |
+| `otelLogUserPrompts` | OpenTelemetry: include user prompts in logs (sets `OTEL_LOG_USER_PROMPTS=1`). |
+| `otelLogRawApiBodies` | OpenTelemetry: include raw API bodies in logs (sets `OTEL_LOG_RAW_API_BODIES=1`). Debug only. |
+
+`stats.pluginErrors` is now populated from the `system/init` event when CLI plugins fail to load due to unmet dependencies.
+
+`TRACEPARENT` / `TRACESTATE` (W3C distributed tracing) are automatically forwarded from parent process env — set them before starting the session and they propagate to the child Claude CLI.
+
+**Smart defaults:** When `bare: true`, the plugin auto-enables `--exclude-dynamic-system-prompt-sections` and `ENABLE_PROMPT_CACHING_1H=1` unless explicitly set to `false`.
+
+## Multi-Agent Council
+
+Parallel agent collaboration with git worktree isolation and consensus voting. Agents can use different engines.
+
+```javascript
+// Start a council
+council_start({
+  task: 'Build a REST API',
+  agents: [
+    { name: 'Architect', emoji: '🏗️', persona: 'System design', engine: 'claude' },
+    { name: 'Engineer', emoji: '⚙️', persona: 'Implementation', engine: 'codex' },
+  ],
+  maxRounds: 5,
+  projectDir: '/path/to/project',
+});
+```
+
+Council lifecycle: `council_start` → poll `council_status` → `council_review` → `council_accept` or `council_reject`.
+
+For details: see [references/council.md](references/council.md)
+
+## Cross-Session Messaging
+
+Sessions can communicate. Idle sessions receive immediately; busy sessions queue.
+
+```javascript
+claude_session_send_to({ from: "sender", to: "receiver", message: "Auth module needs rate limiting" })
+claude_session_send_to({ from: "monitor", to: "*", message: "Build failed!" })  // broadcast
+claude_session_inbox({ name: "receiver" })
+claude_session_deliver_inbox({ name: "receiver" })
+```
+
+## Team Tools (All Engines)
+
+All engines use the same virtual-team layer: cross-session inbox routing across active SessionManager sessions. (Claude Code's native experimental Agent Teams is in-process TUI only and not reachable from a subprocess wrapper.)
+
+```javascript
+claude_team_list({ name: "myproject" })
+claude_team_send({ name: "myproject", teammate: "teammate", message: "Review this" })
+```
+
+## Ultraplan & Ultrareview
+
+- **Ultraplan**: Opus deep planning session (up to 30 min), produces detailed implementation plan
+- **Ultrareview**: Fleet of 5-20 bug-hunting agents reviewing in parallel (security, logic, perf, types, etc.)
+
+Both are async — start then poll status.
+
+## 27 Tools Overview
+
+| Category | Tools |
+|----------|-------|
+| Session Lifecycle | `claude_session_start`, `claude_session_send`, `claude_session_stop`, `claude_session_list`, `claude_sessions_overview` |
+| Session Ops | `claude_session_status`, `claude_session_grep`, `claude_session_compact`, `claude_session_update_tools`, `claude_session_switch_model` |
+| Inbox | `claude_session_send_to`, `claude_session_inbox`, `claude_session_deliver_inbox` |
+| Teams | `claude_agents_list`, `claude_team_list`, `claude_team_send` |
+| Council | `council_start`, `council_status`, `council_abort`, `council_inject`, `council_review`, `council_accept`, `council_reject` |
+| Ultra | `ultraplan_start`, `ultraplan_status`, `ultrareview_start`, `ultrareview_status` |
+
+For full parameter reference: see [references/tools.md](references/tools.md)
+
+## Authentication Prerequisites
+
+Each engine requires its own auth before use:
+
+- **Claude**: `claude /login` or `ANTHROPIC_API_KEY`
+- **Codex**: `codex login` or `OPENAI_API_KEY`
+- **Gemini**: `gemini login` or `GEMINI_API_KEY`
+- **Cursor**: `agent login` or `CURSOR_API_KEY`

package/skills/references/claude-cli-tracking.md

@@ -0,0 +1,25 @@
+# Claude Code CLI Feature Tracking
+
+This document tracks which Claude Code CLI version Claw Orchestrator is currently synced to, and which features have been integrated.
+
+## Currently tracked: **Claude Code CLI 2.1.126** (as of 2026-05-04, plugin v2.14.2)
+
+## Sync history
+
+| Plugin Version | Claude CLI Version | Date | Notable integrations |
+|---|---|---|---|
+| v2.14.2 | 2.1.126 | 2026-05-04 | `bedrockServiceTier` (Bedrock service-tier env, 2.1.122), `claude_project_purge` tool (wraps `claude project purge`, 2.1.126); skipped passive-only items (OTel numeric attr, `invocation_trigger`, `/v1/models` gateway discovery, PowerShell shell changes) |
+| v2.14.0 | 2.1.121 | 2026-04-28 | `forkSubagent` (fork subagent env), `enableToolSearch` (Vertex AI tool search env), `otelLogUserPrompts` / `otelLogRawApiBodies` (OTEL logging toggles), `xhigh` effort level (Opus 4.7), `stats.pluginErrors` capture from `system/init` |
+| v2.13.0 | 2.1.111 | 2026-04-16 | Hook events, permission delegation, prompt cache optimization (exclude-dynamic-sections + 1H cache), debug control, `--from-pr`, MCP channels, `system/api_retry` event tracking |
+| v2.12.2 and earlier | 2.1.91 | — | Bare mode, worktree, json-schema, mcp-config, betas, fallback-model, effort, agent teams |
+
+## How to update this
+
+When syncing to a new Claude Code CLI version:
+
+1. Run `claude --version` to confirm target version
+2. Check Claude Code changelog / release notes for new flags, events, env vars since the last tracked version
+3. Decide which features are valuable for programmatic/agent use (vs human-interactive only) — see the Tier 1/2/3 framework in `docs/superpowers/specs/`
+4. Implement worthwhile features (add to `SessionConfig` → wire into `persistent-session.ts` → expose in tool schema → document)
+5. Update this file with the new version + notable integrations
+6. Update `CLAUDE.md` and `README.md` engine compatibility tables