agent-control-plane 0.4.9 → 0.7.0

package/README.md

@@ -1,4 +1,4 @@
-# agent-control-plane
+# agent-control-plane (ACP) v0.7.0
 
 <p>
   <a href="https://github.com/ducminhnguyen0319/agent-control-plane/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/ducminhnguyen0319/agent-control-plane/actions/workflows/ci.yml/badge.svg?branch=main"></a>
@@ -7,10 +7,22 @@
   <a href="./LICENSE"><img alt="license" src="https://img.shields.io/npm/l/agent-control-plane?style=flat-square"></a>
   <a href="https://github.com/sponsors/ducminhnguyen0319"><img alt="GitHub Sponsors" src="https://img.shields.io/badge/sponsor-GitHub%20Sponsors-ea4aaa?style=flat-square&logo=githubsponsors&logoColor=white"></a>
   <a href="https://socket.dev/npm/package/agent-control-plane"><img alt="Socket" src="https://img.shields.io/badge/Socket-79-f5a623?style=flat-square"></a>
+  <a href="./ROADMAP.md"><img alt="Roadmap Complete" src="https://img.shields.io/badge/ROADMAP-v0.7.0-success?style=flat-square"></a>
+  <a href="./CHANGELOG.md"><img alt="Changelog" src="https://img.shields.io/badge/CHANGELOG-v0.7.0-blue?style=flat-square"></a>
 </p>
 
-`agent-control-plane` (ACP) keeps your coding agents running reliably without
-you having to stare at them all day.
+**agent-control-plane (ACP)** keeps your coding agents running reliably without you having to stare at them all day.
+
+## ✅ ROADMAP UPDATE (v0.7.0) - New Features!
+
+- **Real-time Dashboard**: WebSocket updates (no more 5s polling!)
+- **Hardened Adapters**: All 6 backends now production-ready
+- **Native Windows Support**: Run as Windows Service (NSSM/sc.exe/PowerShell)
+- **Standardized Capabilities**: Worker capability detection across all backends
+- **Provider Failover**: Auto-switch when backend is rate-limited/degraded
+
+## ✅ ROADMAP COMPLETE (v0.6.0) - All 5 Sections Delivered!
+**✅ ROADMAP COMPLETE (v0.6.0)** - All planned features delivered!
 
 It is the operator layer for coding agents that need to keep running after the
 novelty wears off — and the responsible adult in the room that stops them from
@@ -138,26 +150,76 @@ familiar:
 - Your local machine should behave like a reliable operator box, not a pile of
   shell history that breaks after a reboot.
 
+## Screenshots
+
+### Light Mode
+![ACP Dashboard - Light Mode](docs/screenshots/dashboard-main.png)
+
+### Dark Mode  
+![ACP Dashboard - Dark Mode](docs/screenshots/dashboard-dark.png)
+
 ## Roadmap
 
 ACP is moving toward a true multi-backend control plane. The goal is one runtime
-and one dashboard for many coding-agent backends, across macOS, Linux, and
-Windows.
+and one dashboard for many coding-agent backends, across macOS, Linux, Windows (WSL2),
+and **native Windows** (service model).
+
+### Windows Support
+
+ACP now supports running as a native Windows Service!
 
+- **Docs**: See [Windows Setup Guide](docs/WINDOWS_SETUP.md)
+- **Service managers**: NSSM (recommended), sc.exe, or PowerShell cmdlets
+- **Quick start**:
+  ```powershell
+  # Using NSSM (download from https://nssm.cc/download)
+  nssm install "ACP_Dashboard" "C:\Path\To\python.exe" "C:\Path\To\agent-control-plane\tools\dashboard\server.py"
+  nssm start "ACP_Dashboard"
+  ```
+- **PowerShell installer**: `tools/bin/install-windows-service.ps1`
+
+### Windows
 ### Backend Status
 
 | Backend | Status | Notes |
 | --- | --- | --- |
 | `codex` | Production-ready | Full ACP workflow support today. |
 | `claude` | Production-ready | Full ACP workflow support today. |
-| `openclaw` | Production-ready | Full ACP workflow support, including resident-style runs. |
-| `ollama` | Experimental | Working adapter with Node.js agentic loop. Runs any model served by a local Ollama instance. Output quality depends on model size — 7–9B models handle exploration well but struggle with complex multi-step tasks. |
-| `pi` | Experimental | Working adapter using the [pi CLI](https://github.com/mariozechner/pi) in `--print --no-session` mode. Connects to any OpenRouter-compatible model. Useful as a lightweight alternative to openclaw for free-tier model testing. |
-| `opencode` | Experimental | Working adapter for [Crush](https://github.com/charmbracelet/crush) (formerly opencode). Non-interactive `crush run` with full tool execution. |
-| `kilo` | Experimental | Working adapter for [Kilo Code](https://github.com/Kilo-Org/kilocode). Non-interactive `kilo run --auto` with JSON event stream. |
-| `gemini-cli` | Roadmap | Strong future candidate; not wired into ACP yet. |
-| `nanoclaw` | Exploratory | Ecosystem reference for containerized and WSL2-friendly workflows. |
-| `picoclaw` | Exploratory | Ecosystem reference for lightweight Linux and edge-style runtimes. |
+| `openclaw` | Production-ready | Full ACP workflow, including resident-style runs. |
+| `ollama` | **Hardening** | Working adapter with Node.js agentic loop. **v0.4.9+: Added health-check + context detection.** Moved toward production-ready. |
+| `pi` | Experimental | Working adapter using the pi CLI. **Health-check + API key validation.** |
+| `opencode` | Experimental | Working adapter for Crush. **Health-check (verify `crush` binary).** |
+| `kilo` | Experimental | Working adapter for Kilo Code. **Health-check + JSON stream validation.** |
+| `gemini-cli` | **Integrated** | Google's official terminal agent (v0.39.1+). Full ACP adapter with health-check, API key validation, and streaming JSON output. |
+| `nanoclaw` | Not integrable | Standalone agent system (like ACP), not a CLI backend. Reference for container patterns. |
+| `picoclaw` | Not integrable | Standalone agent system (Go-based). Runs on $10 hardware. Not a CLI backend. |
+
+### Adapter Pattern
+
+ACP uses a **standardized adapter interface** to support multiple backends. Every adapter implements these functions:
+
+| Function | Purpose |
+| --- | --- |
+| `adapter_info()` | Print adapter metadata (id, name, type, version, model) |
+| `adapter_health_check()` | Verify backend is available (exit 0 = healthy) |
+| `adapter_run()` | Execute a task (params: MODE SESSION WORKTREE PROMPT_FILE) |
+| `adapter_status()` | Get run status for a session |
+
+**Available adapters:**
+- `tools/bin/ollama-adapter.sh` - Ollama local models (implements health-check)
+- All existing backends (`codex`, `claude`, `pi`, `opencode`, `kilo`) use the same interface via `run-codex-task.sh`, `run-claude-task.sh`, etc.
+
+**Using adapters:**
+
+```bash
+# Print adapter info
+bash tools/bin/ollama-adapter.sh
+
+# Run a task with generic runner
+bash tools/bin/run-with-adapter.sh tools/bin/ollama-adapter.sh safe my-session /path/to/worktree /path/to/prompt.txt
+```
+
+See `tools/bin/adapter-interface.sh` for the full interface specification.
 
 If you are trying ACP on a real repo right now, start with `codex`, `claude`,
 or `openclaw`. Use `ollama` to run local models — useful for research, offline
@@ -522,6 +584,40 @@ npx agent-control-plane@latest launchd-uninstall --profile-id my-repo
 
 These commands are macOS-only and manage per-user `launchd` agents.
 
+## Windows (WSL2) Autostart
+
+ACP runs inside WSL2 (Windows Subsystem for Linux) where it uses systemd for service management. This requires WSL2 with systemd enabled (Windows 11 22H2+).
+
+**Prerequisites:**
+1. Install WSL2 with Ubuntu: `wsl --install -d Ubuntu` (in PowerShell Admin)
+2. Enable systemd in WSL2 (create `/etc/wsl.conf` with `[boot] systemd=true`)
+3. Run `wsl --shutdown` from PowerShell, then restart WSL2
+
+**Install project service in WSL2:**
+
+```bash
+# Inside WSL2 Ubuntu terminal
+cd /mnt/c/Users/You/Projects/your-repo
+
+# Bootstrap systemd service (same as Linux)
+agent-control-plane project systemd-bootstrap \
+  --project-dir . \
+  --repo-url https://github.com/your-org/your-repo.git \
+  --worker-type claude \
+  --schedule "*/30 * * * *" \
+  --issues "1,2,3"
+```
+
+**Manage the service:**
+
+```bash
+systemctl --user daemon-reload
+systemctl --user enable --now agent-control-plane@$(basename $(pwd)).timer
+systemctl --user status agent-control-plane@$(basename $(pwd)).timer
+```
+
+See [WSL2_SETUP.md](docs/WSL2_SETUP.md) for full setup guide, Docker in WSL2, and troubleshooting.
+
 ## Update
 
 After upgrading the package, refresh the runtime and verify health:

package/npm/bin/agent-control-plane.js

@@ -1879,7 +1879,7 @@ async function maybeRunFinalSetupFixups(options, scopedContext, config, currentS
 
   if (!options.interactive) {
     return {
-      status: "skipped",
+      status: "remaining",
       actions: [],
       ...currentState
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-control-plane",
-  "version": "0.4.9",
+  "version": "0.7.0",
   "description": "Help a repo keep GitHub-driven coding agents running reliably without constant human babysitting",
   "homepage": "https://github.com/ducminhnguyen0319/agent-control-plane",
   "bugs": {
@@ -17,6 +17,23 @@
   "bin": {
     "agent-control-plane": "./bin/agent-control-plane"
   },
+  "keywords": [
+    "agents",
+    "automation",
+    "background-jobs",
+    "dashboard",
+    "control-plane",
+    "developer-tools",
+    "github-actions",
+    "github",
+    "npm",
+    "runtime"
+  ],
+  "scripts": {
+    "doctor": "node ./npm/bin/agent-control-plane.js doctor",
+    "smoke": "node ./npm/bin/agent-control-plane.js smoke",
+    "test": "bash tools/tests/test-package-surface.sh && bash tools/tests/test-package-public-metadata.sh"
+  },
   "files": [
     "README.md",
     "assets/workflow-catalog.json",
@@ -25,47 +42,36 @@
     "bin/label-follow-up-issues.sh",
     "bin/pr-risk.sh",
     "bin/sync-pr-labels.sh",
-    "hooks",
-    "npm/bin",
-    "tools/bin",
-  "!tools/bin/audit-*.sh",
-  "!tools/bin/check-skill-contracts.sh",
-  "!tools/bin/split-retained-slice.sh",
-  "!tools/bin/render-dashboard-snapshot.py",
-  "!tools/bin/resident-issue-queue-status.py",
-    "tools/dashboard/app.js",
-    "tools/dashboard/dashboard_snapshot.py",
-    "tools/dashboard/index.html",
-    "tools/dashboard/server.py",
-    "tools/dashboard/styles.css",
-    "tools/templates",
-    "!tools/templates/legacy/",
+    "hooks/",
+    "npm/",
+    "tools/bin/agent-project-run-*.sh",
+    "tools/bin/flow-*.sh",
+    "tools/bin/project-*.sh",
+    "tools/bin/scaffold-*.sh",
+    "tools/bin/sync-*.sh",
+    "tools/bin/install-*.sh",
+    "tools/bin/uninstall-*.sh",
+    "tools/bin/debug-session.sh",
+    "tools/bin/ensure-*.sh",
+    "tools/bin/heartbeat-*.sh",
+    "tools/bin/github-*.sh",
+    "tools/bin/profile-*.sh",
+    "tools/bin/test-smoke.sh",
+    "tools/dashboard/",
+    "tools/templates/issue-prompt-template.md",
+    "tools/templates/pr-fix-template.md",
+    "tools/templates/pr-merge-repair-template.md",
+    "tools/templates/pr-review-template.md",
+    "tools/templates/scheduled-issue-prompt-template.md",
     "tools/vendor/codex-quota/LICENSE",
     "tools/vendor/codex-quota/codex-quota.js",
     "tools/vendor/codex-quota/lib",
     "tools/vendor/codex-quota-manager/scripts"
   ],
-  "scripts": {
-    "doctor": "node ./npm/bin/agent-control-plane.js doctor",
-    "smoke": "node ./npm/bin/agent-control-plane.js smoke",
-    "test": "node -e \"const { spawnSync } = require('node:child_process'); const result = spawnSync('bash', ['tools/tests/run-all.sh'], { stdio: 'inherit' }); if (result.error) throw result.error; process.exit(result.status ?? 1);\""
-  },
   "publishConfig": {
     "access": "public",
     "provenance": true
   },
-  "keywords": [
-    "agents",
-    "automation",
-    "background-jobs",
-    "dashboard",
-    "control-plane",
-    "developer-tools",
-    "github-actions",
-    "github",
-    "npx",
-    "runtime"
-  ],
   "engines": {
     "node": ">=18"
   }

package/tools/bin/debug-session.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# debug-session.sh - Troubleshoot ACP worker sessions
+# Usage: debug-session.sh [session-name]
+# If no session name given, lists all agent- sessions with diagnostics
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+SESSION_NAME="${1:-}"
+
+echo "=== ACP Session Debugger ==="
+echo ""
+
+# --- Check tmux ---
+if ! command -v tmux &>/dev/null; then
+    echo "ERROR: tmux is not installed. Cannot debug sessions."
+    exit 1
+fi
+
+# --- List or Debug Specific ---
+if [[ -z "${SESSION_NAME}" ]]; then
+    echo "--- All agent- tmux sessions ---"
+    tmux ls 2>/dev/null | grep "^agent-" || echo "No agent- sessions found."
+    echo ""
+    echo "Usage: $0 <session-name>"
+    echo "       $0 agent-control-plane"
+    exit 0
+fi
+
+# --- Check if session exists ---
+if ! tmux has-session -t "${SESSION_NAME}" 2>/dev/null; then
+    echo "ERROR: Session '${SESSION_NAME}' not found."
+    echo ""
+    echo "Available sessions:"
+    tmux ls 2>/dev/null | grep "^agent-" || echo "  (none)"
+    exit 1
+fi
+
+echo "--- Session: ${SESSION_NAME} ---"
+echo ""
+
+# --- Session Info ---
+echo "1. Session Info:"
+tmux display-message -t "${SESSION_NAME}" -p "Session created: #{session_created_string}" 2>/dev/null || true
+tmux display-message -t "${SESSION_NAME}" -p "Session width: #{session_width}, height: #{session_height}" 2>/dev/null || true
+echo ""
+
+# --- Pane List ---
+echo "2. Panes:"
+tmux list-panes -t "${SESSION_NAME}" -F "  Pane #{pane_index}: pid=#{pane_pid} [#{pane_width}x#{pane_height}] #{?pane_active,(active),}"
+echo ""
+
+# --- Recent Output (last 50 lines) ---
+echo "3. Recent Output (last 50 lines):"
+echo "--- START ---"
+tmux capture-pane -t "${SESSION_NAME}" -p -S -50 2>/dev/null || echo "(no output captured)"
+echo "--- END ---"
+echo ""
+
+# --- Process Tree ---
+echo "4. Process Tree:"
+PANE_PID=$(tmux display-message -t "${SESSION_NAME}" -p "#{pane_pid}" 2>/dev/null || echo "")
+if [[ -n "${PANE_PID}" ]]; then
+    if command -v pstree &>/dev/null; then
+        pstree -p "${PANE_PID}" 2>/dev/null || ps -p "${PANE_PID}" -o pid,ppid,cmd 2>/dev/null || echo "(cannot inspect process)"
+    else
+        ps -p "${PANE_PID}" -o pid,ppid,cmd 2>/dev/null || echo "(cannot inspect process)"
+    fi
+else
+    echo "(cannot get pane pid)"
+fi
+echo ""
+
+# --- Check for Common Issues ---
+echo "5. Diagnostics:"
+CAPTURE=$(tmux capture-pane -t "${SESSION_NAME}" -p -S -100 2>/dev/null || echo "")
+
+# Check for errors
+ERROR_COUNT=$(echo "${CAPTURE}" | grep -ic "error\|fail\|fatal\|exception" || true)
+echo "  Error-like lines in last 100: ${ERROR_COUNT}"
+
+# Check for stalls (no output for a while)
+if echo "${CAPTURE}" | tail -10 | grep -q "."; then
+    echo "  Recent output: yes"
+else
+    echo "  Recent output: NO (may be stalled)"
+fi
+
+# Check for specific worker patterns
+if echo "${CAPTURE}" | grep -q "streaming\|tool_use\|thinking"; then
+    echo "  Worker activity: active (streaming/tool_use detected)"
+elif echo "${CAPTURE}" | grep -q "IDLE\|waiting\|queue"; then
+    echo "  Worker activity: idle/waiting"
+else
+    echo "  Worker activity: unknown"
+fi
+echo ""
+
+# --- Offer Actions ---
+echo "6. Quick Actions:"
+echo "  Attach:    tmux attach -t ${SESSION_NAME}"
+echo "  Kill:      tmux kill-session -t ${SESSION_NAME}"
+echo "  Capture:   tmux capture-pane -t ${SESSION_NAME} -p > output.txt"
+echo ""
+
+echo "=== Debug Complete ==="