agent-control-plane 0.4.9 → 0.6.0

package/README.md

@@ -12,6 +12,8 @@
 `agent-control-plane` (ACP) keeps your coding agents running reliably without
 you having to stare at them all day.
 
+**✅ 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
 going completely off the rails.
@@ -141,7 +143,7 @@ familiar:
 ## 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
+and one dashboard for many coding-agent backends, across macOS, Linux, and Windows (WSL2)
 Windows.
 
 ### Backend Status
@@ -150,14 +152,41 @@ Windows.
 | --- | --- | --- |
 | `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 +551,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.6.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 ==="

package/tools/bin/flow-runtime-doctor-linux.sh

@@ -0,0 +1,136 @@
+#!/usr/bin/env bash
+# flow-runtime-doctor-linux.sh - Linux-specific runtime validation for ACP
+# Checks systemd services, Linux paths, and runtime health
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+source "${SCRIPT_DIR}/flow-config-lib.sh"
+
+FLOW_SKILL_DIR="$(resolve_flow_skill_dir "${BASH_SOURCE[0]}")"
+CONTROL_PLANE_NAME="$(flow_canonical_skill_name)"
+RUNTIME_HOME="$(resolve_runtime_home)"
+
+echo "=== ACP Linux Runtime Doctor ==="
+echo ""
+
+# --- Systemd Checks ---
+echo "--- Systemd Service Status ---"
+if command -v systemctl &>/dev/null; then
+    echo "systemctl: available"
+    
+    # Check user services (systemd --user)
+    if systemctl --user is-active --quiet "${CONTROL_PLANE_NAME}.service" 2>/dev/null; then
+        echo "service ${CONTROL_PLANE_NAME}: active (user)"
+    elif systemctl --user is-enabled --quiet "${CONTROL_PLANE_NAME}.service" 2>/dev/null; then
+        echo "service ${CONTROL_PLANE_NAME}: installed but not running (user)"
+    else
+        echo "service ${CONTROL_PLANE_NAME}: not installed (user)"
+    fi
+    
+    # Check system services (if installed system-wide)
+    if systemctl is-active --quiet "${CONTROL_PLANE_NAME}.service" 2>/dev/null; then
+        echo "service ${CONTROL_PLANE_NAME}: active (system)"
+    fi
+else
+    echo "systemctl: NOT available (not a systemd-based system?)"
+fi
+echo ""
+
+# --- Linux Path Checks ---
+echo "--- Linux Path Validation ---"
+echo "RUNTIME_HOME=${RUNTIME_HOME}"
+echo "FLOW_SKILL_DIR=${FLOW_SKILL_DIR}"
+
+# Check XDG paths (Linux standard)
+XDG_CONFIG_HOME="${XDG_CONFIG_HOME:-$HOME/.config}"
+XDG_RUNTIME_DIR="${XDG_RUNTIME_DIR:-/run/user/$(id -u)}"
+
+echo "XDG_CONFIG_HOME=${XDG_CONFIG_HOME}"
+echo "XDG_RUNTIME_DIR=${XDG_RUNTIME_DIR}"
+
+if [[ -d "${XDG_RUNTIME_DIR}" ]]; then
+    echo "XDG_RUNTIME_DIR: exists"
+else
+    echo "XDG_RUNTIME_DIR: NOT FOUND (may cause issues with user services)"
+fi
+echo ""
+
+# --- Process Checks ---
+echo "--- Process Checks ---"
+if command -v pgrep &>/dev/null; then
+    AGENT_PIDS=$(pgrep -f "agent-control-plane" 2>/dev/null || true)
+    if [[ -n "${AGENT_PIDS}" ]]; then
+        echo "agent-control-plane processes running: yes (PIDs: ${AGENT_PIDS})"
+        ps -p "${AGENT_PIDS}" -o pid,ppid,cmd 2>/dev/null || true
+    else
+        echo "agent-control-plane processes running: no"
+    fi
+else
+    echo "pgrep: NOT available"
+fi
+echo ""
+
+# --- tmux Checks ---
+echo "--- tmux Session Checks ---"
+if command -v tmux &>/dev/null; then
+    echo "tmux: available ($(tmux -V))"
+    TMUX_SESSIONS=$(tmux ls 2>/dev/null | grep -c "agent-" || true)
+    echo "agent- tmux sessions: ${TMUX_SESSIONS}"
+    if [[ ${TMUX_SESSIONS} -gt 0 ]]; then
+        tmux ls 2>/dev/null | grep "agent-" || true
+    fi
+else
+    echo "tmux: NOT installed (required for ACP worker sessions)"
+fi
+echo ""
+
+# --- Socket/Port Checks ---
+echo "--- Socket/Port Checks ---"
+if command -v ss &>/dev/null; then
+    echo "Checking for dashboard port (3180)..."
+    ss -tlnp 2>/dev/null | grep ":3180 " || echo "Port 3180: not in use"
+elif command -v netstat &>/dev/null; then
+    netstat -tlnp 2>/dev/null | grep ":3180 " || echo "Port 3180: not in use"
+else
+    echo "ss/netstat: NOT available, skipping port check"
+fi
+echo ""
+
+# --- Log File Checks ---
+echo "--- Log File Checks ---"
+LOG_DIR="${RUNTIME_HOME}/logs"
+if [[ -d "${LOG_DIR}" ]]; then
+    echo "LOG_DIR=${LOG_DIR}: exists"
+    LOG_COUNT=$(find "${LOG_DIR}" -name "*.log" 2>/dev/null | wc -l)
+    echo "Log files: ${LOG_COUNT}"
+else
+    echo "LOG_DIR=${LOG_DIR}: NOT FOUND"
+fi
+echo ""
+
+# --- Run Generic Doctor ---
+echo "=== Generic Runtime Doctor ==="
+if [[ -f "${SCRIPT_DIR}/flow-runtime-doctor.sh" ]]; then
+    bash "${SCRIPT_DIR}/flow-runtime-doctor.sh"
+else
+    echo "flow-runtime-doctor.sh: NOT FOUND"
+fi
+
+echo ""
+echo "=== Linux Doctor Complete ==="
+echo ""
+echo "=== NEXT STEPS ==="
+if ! command -v systemctl &>/dev/null; then
+    echo "NOT on systemd: Use macOS launchd or manual tmux for runtime."
+elif ! systemctl --user is-active --quiet "${CONTROL_PLANE_NAME}.service" 2>/dev/null; then
+    echo "Service not running. Start with:"
+    echo "  systemctl --user start ${CONTROL_PLANE_NAME}.service"
+    echo "  systemctl --user enable ${CONTROL_PLANE_NAME}.service  # autostart"
+fi
+
+if ! command -v tmux &>/dev/null; then
+    echo "MISSING: tmux is required. Install:"
+    echo "  Ubuntu/Debian: sudo apt install tmux"
+    echo "  Alpine: apk add tmux"
+fi

package/tools/bin/flow-runtime-doctor.sh

@@ -93,5 +93,9 @@ if [[ -n "${PROFILE_SELECTION_HINT}" ]]; then
 fi
 
 if [[ "${status}" != "ok" ]]; then
-  printf 'NEXT_STEP=bash %q %q %q\n' "${SYNC_SCRIPT}" "${SHARED_AGENT_HOME}" "${RUNTIME_HOME}"
+  printf '\n=== ACTION REQUIRED ===\n'
+  printf 'Status: %s\n' "${status}"
+  printf 'Next step: Run sync to fix issues:\n'
+  printf '  bash %q %q %q\n' "${SYNC_SCRIPT}" "${SHARED_AGENT_HOME}" "${RUNTIME_HOME}"
+  printf '\nOr run: bash %s/tools/bin/setup.sh --resume\n' "${FLOW_SKILL_DIR}"
 fi