agent-control-plane 0.2.0 → 0.4.9

package/references/commands.md

@@ -1,128 +0,0 @@
-# Command Map
-
-Run commands from the current isolated checkout for the task.
-
-Profile-specific repo roots and repo-local dev/test commands belong in
-`~/.agent-runtime/control-plane/profiles/<id>/README.md`. Resolve the active
-profile first, then use the selected profile's notes for product-repo commands.
-
-## Profile Resolution
-
-```bash
-bash tools/bin/workflow-catalog.sh profiles
-tools/bin/workflow-catalog.sh context
-bash tools/bin/profile-activate.sh --profile-id <id>
-ACP_PROJECT_ID=<id> bash tools/bin/render-flow-config.sh
-```
-
-Use `render-flow-config.sh` when you need the effective repo root, worktree
-root, runtime root, worker backend, or profile-specific script bindings.
-When multiple available profiles exist, set `ACP_PROJECT_ID=<id>` first or use
-`profile-activate.sh --profile-id <id>` before running manual operator
-commands.
-
-## Dependency bootstrap
-
-Run dependency bootstrap only from the clean automation baseline for the
-selected profile when you explicitly need to refresh shared dependencies. Do not
-repair shared `node_modules` from inside a worker worktree.
-
-For control-plane changes in this repo, prefer focused shell tests over broad
-bootstrap unless the task actually changes dependency behavior.
-
-## Control-Plane Verification
-
-```bash
-bash tools/bin/check-skill-contracts.sh
-bash tools/bin/flow-runtime-doctor.sh
-bash tools/bin/profile-smoke.sh
-bash tools/bin/test-smoke.sh
-bash tools/tests/test-project-init.sh
-bash tools/tests/test-project-init-force-and-skip-sync.sh
-bash tools/tests/test-project-remove.sh
-bash tools/tests/test-project-runtimectl.sh
-bash tools/tests/test-project-runtimectl-missing-profile.sh
-bash tools/tests/test-project-runtimectl-stop-cancels-pending-kick.sh
-bash tools/tests/test-project-runtimectl-start-falls-back-to-bootstrap.sh
-bash tools/tests/test-project-runtimectl-status-supervisor-running.sh
-bash tools/tests/test-project-launchd-bootstrap.sh
-bash tools/tests/test-install-project-launchd.sh
-bash tools/tests/test-uninstall-project-launchd.sh
-bash tools/tests/test-project-runtimectl-launchd.sh
-bash tools/tests/test-dashboard-launchd-bootstrap.sh
-bash tools/tests/test-install-dashboard-launchd.sh
-bash tools/tests/test-render-dashboard-snapshot.sh
-bash tools/tests/test-serve-dashboard.sh
-bash tools/tests/test-control-plane-dashboard-runtime-smoke.sh
-bash tools/tests/test-workflow-catalog.sh
-bash tools/tests/test-render-flow-config.sh
-```
-
-Add or run targeted tests in `tools/tests/` for the changed surface.
-
-## Flow maintenance
-
-```bash
-tools/bin/flow-runtime-doctor.sh
-tools/bin/workflow-catalog.sh list
-tools/bin/workflow-catalog.sh show pr-review
-tools/bin/workflow-catalog.sh profiles
-tools/bin/workflow-catalog.sh context
-tools/bin/profile-activate.sh --profile-id <id>
-tools/bin/project-init.sh --profile-id <id> --repo-slug <owner/repo>
-tools/bin/render-flow-config.sh
-tools/bin/scaffold-profile.sh --profile-id <id> --repo-slug <owner/repo>
-tools/bin/profile-smoke.sh
-tools/bin/test-smoke.sh
-tools/bin/profile-adopt.sh --profile-id <id>
-tools/bin/project-runtimectl.sh status --profile-id <id>
-tools/bin/project-runtimectl.sh sync --profile-id <id>
-tools/bin/project-runtimectl.sh stop --profile-id <id>
-tools/bin/project-runtimectl.sh start --profile-id <id>
-tools/bin/project-runtimectl.sh restart --profile-id <id>
-tools/bin/install-project-launchd.sh --profile-id <id>
-tools/bin/uninstall-project-launchd.sh --profile-id <id>
-tools/bin/project-remove.sh --profile-id <id>
-tools/bin/project-remove.sh --profile-id <id> --purge-paths
-tools/bin/sync-shared-agent-home.sh
-python3 tools/dashboard/dashboard_snapshot.py --pretty
-bash tools/bin/serve-dashboard.sh --host 127.0.0.1 --port 8765
-bash tools/bin/install-dashboard-launchd.sh --host 127.0.0.1 --port 8765
-```
-
-Installed profile prompts should live under
-`~/.agent-runtime/control-plane/profiles/<id>/templates/`; generic fallback
-prompts live under `tools/templates/`.
-
-## Dashboard
-
-```bash
-python3 tools/dashboard/dashboard_snapshot.py --pretty
-bash tools/bin/serve-dashboard.sh --host 127.0.0.1 --port 8765
-bash tools/bin/install-dashboard-launchd.sh --host 127.0.0.1 --port 8765
-```
-
-Use the snapshot command for CLI/debug output and the HTTP server for the live
-dashboard at `http://127.0.0.1:8765`. Use the LaunchAgent installer when you
-want the dashboard to come back automatically after macOS restart/login.
-
-## Project Autostart
-
-```bash
-bash tools/bin/install-project-launchd.sh --profile-id <id>
-bash tools/bin/uninstall-project-launchd.sh --profile-id <id>
-```
-
-Use the project installer when one profile should come back automatically after
-macOS restart/login. `project-runtimectl.sh start|stop|status` will detect that
-per-project LaunchAgent automatically once it is installed.
-
-## Repo-Specific Commands
-
-After choosing a profile, read `~/.agent-runtime/control-plane/profiles/<id>/README.md` for:
-
-- clean automation baseline and retained checkout roots
-- repo-local startup docs such as `AGENTS.md` and OpenSpec paths
-- app/package-specific dev commands
-- isolated smoke and release-rehearsal commands
-- project-specific operator runbooks

package/references/control-plane-map.md

@@ -1,124 +0,0 @@
-# Agent Control Plane Map
-
-This repository is the shared `agent-control-plane` package. It provides a
-generic engine that can host multiple installed profiles, each with its own repo
-roots, labels, worker preferences, prompts, and project-specific guardrails.
-
-## What Lives Here
-
-- `SKILL.md`
-  Canonical operating manual for the shared control plane.
-- `~/.agent-runtime/control-plane/profiles/<id>/control-plane.yaml`
-  Canonical installed project profile for repo paths, queue labels, limits,
-  and script bindings.
-- `~/.agent-runtime/control-plane/profiles/<id>/README.md`
-  Repo-specific operator notes, startup docs, and command references for the
-  selected profile.
-- `~/.agent-runtime/control-plane/profiles/<id>/templates/`
-  Optional installed profile-specific prompt overrides.
-- `assets/workflow-catalog.json`
-  Declarative catalog of the workflow lanes this control plane exposes.
-- `bin/`
-  Queue, label, and risk logic shared by installed profiles.
-- `hooks/`
-  Heartbeat and reconcile hooks shared by installed profiles.
-- `tools/bin/flow-runtime-doctor.sh`
-  Reports whether the published source copy and runtime-home copy are in sync.
-- `tools/bin/workflow-catalog.sh`
-  Lists workflows, shows workflow details, or prints available profile ids.
-- `tools/bin/render-flow-config.sh`
-  Prints the effective operator/runtime config after environment overrides.
-- `tools/bin/run-codex-task.sh`
-  Routes the shared worker contract into the backend-specific session wrapper.
-- `tools/bin/agent-project-run-codex-session`
-  Launches Codex-backed worker sessions.
-- `tools/bin/agent-project-run-claude-session`
-  Launches Claude-backed worker sessions.
-- `tools/bin/agent-project-run-openclaw-session`
-  Launches OpenClaw-backed worker sessions.
-- `tools/bin/agent-project-run-ollama-session`
-  Launches Ollama-backed worker sessions with a Node.js agentic loop.
-- `tools/bin/agent-project-run-pi-session`
-  Launches Pi-backed worker sessions in `--print --no-session` mode.
-- `tools/bin/agent-project-run-opencode-session`
-  Launches Crush (formerly OpenCode) worker sessions via `crush run`.
-- `tools/bin/agent-project-run-kilo-session`
-  Launches Kilo Code worker sessions via `kilo run --auto --format json`.
-- `tools/bin/project-init.sh`
-  Runs scaffold + smoke + adopt + runtime sync for one installed profile.
-- `tools/bin/scaffold-profile.sh`
-  Scaffolds a new installed profile, profile notes, and prompt templates in the
-  local profile registry.
-- `tools/bin/project-runtimectl.sh`
-  Provides `status`, `start`, `stop`, and `restart` for one installed profile.
-- `tools/bin/project-launchd-bootstrap.sh`
-  Syncs the runtime copy and runs one profile-scoped heartbeat pass in a
-  launchd-safe foreground process for the runtime supervisor.
-- `tools/bin/install-project-launchd.sh`
-  Installs a per-user LaunchAgent for one installed profile so its runtime can
-  come back automatically after reboot/login.
-- `tools/bin/uninstall-project-launchd.sh`
-  Removes the per-project LaunchAgent wrapper and plist for one installed
-  profile.
-- `tools/bin/project-remove.sh`
-  Removes one installed profile plus ACP-owned runtime state, with optional
-  purge of ACP-managed repo/worktree/workspace paths.
-- `tools/bin/profile-smoke.sh`
-  Validates available profiles and catches session/branch prefix collisions
-  before scheduler use.
-- `tools/bin/test-smoke.sh`
-  Runs the main shared-package smoke gates in one operator-facing command.
-- `tools/dashboard/dashboard_snapshot.py`
-  Emits a JSON snapshot of active runs, resident controllers, cooldown state,
-  queue depth, and scheduled issues across installed profiles.
-- `tools/bin/serve-dashboard.sh`
-  Serves the live worker dashboard and `/api/snapshot.json` endpoint for local
-  browser-based monitoring.
-- `tools/bin/dashboard-launchd-bootstrap.sh`
-  Syncs the runtime copy and launches the dashboard server in a launchd-safe
-  foreground process.
-- `tools/bin/install-dashboard-launchd.sh`
-  Installs and bootstraps a per-user LaunchAgent so the dashboard returns after
-  reboot/login.
-- `tools/bin/profile-adopt.sh`
-  Creates runtime roots, installs the selected profile into the local profile
-  registry when needed, and syncs the anchor repo plus VS Code workspace for
-  live scheduler adoption.
-- `references/`
-  Control-plane docs, operator commands, and repository maps.
-
-## What Does Not Live Here
-
-- Repo-specific product code.
-- Local scheduler bootstrap and operator docs that belong to a particular
-  workstation. Those now live under:
-  `~/.agent-runtime/control-plane/workspace`
-
-## Vendored Runtime
-
-- Runtime engines are resolved from the current skill root first, then the
-  shared/runtime canonical copies when present, while active project profiles
-  are resolved from `~/.agent-runtime/control-plane/profiles/`.
-- Project-specific instructions should be loaded from the active profile's
-  `README.md` and templates instead of being hardcoded into the shared engine.
-
-## Published Artifacts
-
-- Source canonical package copy:
-  `$SHARED_AGENT_HOME/skills/openclaw/agent-control-plane`
-- Runtime canonical package copy:
-  `~/.agent-runtime/runtime-home/skills/openclaw/agent-control-plane`
-
-Published artifacts are rebuilt by `tools/bin/sync-shared-agent-home.sh` as
-concrete copied files, not symlink aliases. Canonical profile configs now live
-outside the repo in `~/.agent-runtime/control-plane/profiles/<id>/control-plane.yaml`.
-
-## Operational Rule
-
-When updating the control plane:
-
-1. Change the generic engine in this repo or the selected installed profile in the external registry.
-2. Keep workstation wrappers thin.
-3. Repair shared/runtime published copies with `tools/bin/sync-shared-agent-home.sh`.
-4. Prefer explicit profile docs and copied artifacts over hidden defaults and
-   symlink aliases.

package/references/docs-map.md

@@ -1,73 +0,0 @@
-# Docs Map
-
-Canonical documentation sources inside `agent-control-plane`:
-
-## Shared Control-Plane Docs
-
-- `SKILL.md`
-  Shared operating rules and startup sequence.
-- `README.md`
-  Public-facing install, usage, funding, contributing, and security entrypoint.
-- `CHANGELOG.md`
-  Public release history for the package and repository.
-- `ROADMAP.md`
-  Public product and backend-support roadmap, including current and planned
-  worker integrations.
-- `references/architecture.md`
-  Architecture walkthrough with system, runtime, worker, and dashboard diagrams.
-- `CONTRIBUTING.md`
-  Contributor workflow, legal model, and maintainer expectations.
-- `CLA.md`
-  Contributor license agreement used for incoming changes.
-- `CODE_OF_CONDUCT.md`
-  Community behavior and moderation expectations.
-- `SECURITY.md`
-  Security reporting path and disclosure expectations.
-- `references/control-plane-map.md`
-  Ownership map for profiles, scripts, publication copies, and operator tools.
-- `references/commands.md`
-  Control-plane operator commands and profile-management entrypoints.
-- `references/release-checklist.md`
-  Maintainer release checklist for public package publishing.
-- `.github/release-template.md`
-  Reusable markdown template for GitHub release notes.
-- `.github/workflows/ci.yml`
-  Public CI workflow used for the README status badge.
-- `.github/workflows/publish.yml`
-  Trusted npm publishing workflow used for tag-driven releases with provenance.
-- `references/repo-map.md`
-  Layout of the control-plane repository itself.
-
-## Profile-Scoped Docs
-
-- `~/.agent-runtime/control-plane/profiles/<id>/README.md`
-  Canonical repo-specific startup docs, repo roots, command map, and
-  high-risk notes.
-- `~/.agent-runtime/control-plane/profiles/<id>/control-plane.yaml`
-  Canonical machine-readable installed profile config.
-- `~/.agent-runtime/control-plane/profiles/<id>/templates/*.md`
-  Canonical prompt overrides for issue, PR fix, PR review, or scheduled issue flows.
-
-## Runtime and Publication Docs
-
-- `tools/bin/flow-runtime-doctor.sh`
-  Sync health for source and runtime copies.
-- `tools/bin/profile-smoke.sh`
-  Installed-profile validation before scheduler use.
-- `tools/bin/profile-adopt.sh`
-  Local workstation adoption helper.
-- `tools/bin/sync-shared-agent-home.sh`
-  Publication repair for shared/runtime copies.
-- `tools/bin/render-dashboard-demo-media.sh`
-  Regenerates the README dashboard screenshot and animated walkthrough from a
-  real local demo fixture.
-- `tools/bin/render-architecture-infographics.sh`
-  Regenerates the architecture infographic PNGs and PDF deck from the local
-  HTML source in `tools/architecture/`.
-
-## Rule of Thumb
-
-If a piece of guidance is specific to one repo, keep it in
-`~/.agent-runtime/control-plane/profiles/<id>/README.md` or
-`~/.agent-runtime/control-plane/profiles/<id>/templates/` instead of the shared
-control-plane docs.

package/references/release-checklist.md

@@ -1,65 +0,0 @@
-# Release Checklist
-
-Maintainer checklist for shipping a new public package release of
-`agent-control-plane`.
-
-## Pre-Release
-
-- confirm `git status` is clean
-- confirm `package.json` version is intentional
-- review `CHANGELOG.md` and prepare release notes from
-  `.github/release-template.md`
-- review `README.md`, `SECURITY.md`, `CONTRIBUTING.md`, and `CLA.md` for stale
-  links or policy text
-- if a public GitHub repo now exists, set or verify the `homepage`,
-  `repository`, and `bugs` URLs in `package.json`
-- make sure sponsor links still point to the intended maintainer identity
-- confirm the intended license is still `MIT`
-
-## Verification
-
-Run the core checks:
-
-```bash
-bash tools/tests/test-package-public-metadata.sh
-bash tools/tests/test-package-funding-metadata.sh
-bash tools/tests/test-contribution-docs.sh
-bash tools/tests/test-agent-control-plane-npm-cli.sh
-bash tools/bin/test-smoke.sh
-npm pack --dry-run
-```
-
-## Publish
-
-Recommended release flow uses npm trusted publishing from GitHub Actions, so you
-do not have to enter an OTP during every local publish.
-
-One-time setup:
-
-- configure `agent-control-plane` for npm trusted publishing from
-  `ducminhnguyen0319/agent-control-plane`
-- verify the publish workflow file is `.github/workflows/publish.yml`
-- keep npm package publishing policy on the stricter setting you want after
-  trusted publishing is working
-
-Per-release command flow:
-
-```bash
-npm version <patch|minor|major>
-git push origin main --follow-tags
-```
-
-Then:
-
-- watch `.github/workflows/publish.yml` for the npm publish run
-- create or update a GitHub release using `.github/release-template.md`
-- update `CHANGELOG.md` if the final shipped notes differ from the draft
-
-## Post-Release
-
-- verify `npx agent-control-plane@latest help` works from a clean shell
-- verify the npm package shows provenance for the new version
-- verify `npm fund` shows the expected sponsor link
-- verify the repo README, sponsor button, and package metadata all point to the
-  same maintainer identity
-- announce the release where relevant

package/references/repo-map.md

@@ -1,36 +0,0 @@
-# Repository Map
-
-This file maps the `agent-control-plane` repository itself.
-
-## Core Layout
-
-- `SKILL.md`
-  Shared operating manual for the control plane.
-- `assets/`
-  Workflow catalog and static non-profile assets.
-- `bin/`
-  Queue, label, and risk scripts shared by installed profiles.
-- `hooks/`
-  Heartbeat and reconcile hooks shared by installed profiles.
-- `tools/bin/`
-  Runtime wrappers, onboarding helpers, publication utilities, and doctor tools.
-- `tools/templates/`
-  Generic fallback prompts used when a profile does not override a template.
-- `tools/tests/`
-  Shell regression coverage for control-plane behavior.
-- `references/`
-  Control-plane docs, operator commands, and repository maps.
-
-## Operator Surfaces
-
-- `tools/bin/render-flow-config.sh`
-  Effective config viewer for the selected profile.
-- `tools/bin/profile-smoke.sh`
-  Installed-profile validation and collision detection.
-- `tools/bin/profile-adopt.sh`
-  Local runtime/bootstrap helper for onboarding a profile onto a workstation.
-- `tools/bin/sync-shared-agent-home.sh`
-  Publication repair for shared/runtime copies.
-
-Installed profiles live outside this repo under
-`~/.agent-runtime/control-plane/profiles/<id>/`.

package/tools/bin/split-retained-slice.sh

@@ -1,124 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-SOURCE_ROOT=""
-TARGET_ROOT=""
-PATHS_FILE=""
-BACKUP_ROOT=""
-MOVE_MODE="false"
-
-usage() {
-  cat <<'EOF'
-Usage:
-  split-retained-slice.sh --source <path> --target <path> --paths-file <file> [options]
-
-Copies a curated slice of uncommitted changes from one retained worktree to
-another. Optionally removes that slice from the source after verifying the copy.
-
-Options:
-  --source <path>       Source retained worktree
-  --target <path>       Target retained worktree
-  --paths-file <file>   Newline-delimited relative paths to copy
-  --backup-root <path>  Where to store a safety backup copy (default: mktemp)
-  --move                Remove the copied paths from the source after verify
-  --help                Show this help
-EOF
-}
-
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --source) SOURCE_ROOT="${2:-}"; shift 2 ;;
-    --target) TARGET_ROOT="${2:-}"; shift 2 ;;
-    --paths-file) PATHS_FILE="${2:-}"; shift 2 ;;
-    --backup-root) BACKUP_ROOT="${2:-}"; shift 2 ;;
-    --move) MOVE_MODE="true"; shift ;;
-    --help|-h) usage; exit 0 ;;
-    *) echo "Unknown argument: $1" >&2; usage >&2; exit 1 ;;
-  esac
-done
-
-if [[ -z "$SOURCE_ROOT" || -z "$TARGET_ROOT" || -z "$PATHS_FILE" ]]; then
-  usage >&2
-  exit 1
-fi
-
-for required_path in "$SOURCE_ROOT" "$TARGET_ROOT" "$PATHS_FILE"; do
-  [[ -e "$required_path" ]] || { echo "missing path: $required_path" >&2; exit 1; }
-done
-
-if [[ ! -d "$SOURCE_ROOT/.git" && ! -f "$SOURCE_ROOT/.git" ]]; then
-  echo "source is not a git checkout: $SOURCE_ROOT" >&2
-  exit 1
-fi
-if [[ ! -d "$TARGET_ROOT/.git" && ! -f "$TARGET_ROOT/.git" ]]; then
-  echo "target is not a git checkout: $TARGET_ROOT" >&2
-  exit 1
-fi
-
-if [[ -n "$(git -C "$TARGET_ROOT" status --short)" ]]; then
-  echo "target worktree must be clean before splitting: $TARGET_ROOT" >&2
-  exit 1
-fi
-
-if [[ -z "$BACKUP_ROOT" ]]; then
-  BACKUP_ROOT="$(mktemp -d "${TMPDIR:-/tmp}/retained-slice-backup.XXXXXX")"
-else
-  mkdir -p "$BACKUP_ROOT"
-fi
-
-copy_path() {
-  local source_path="${1:?source path required}"
-  local dest_root="${2:?destination root required}"
-  local rel_path="${3:?relative path required}"
-
-  if [[ -d "$source_path" ]]; then
-    mkdir -p "$(dirname "${dest_root}/${rel_path}")"
-    rm -rf "${dest_root}/${rel_path}"
-    cp -R "$source_path" "${dest_root}/${rel_path}"
-  else
-    mkdir -p "$(dirname "${dest_root}/${rel_path}")"
-    cp -p "$source_path" "${dest_root}/${rel_path}"
-  fi
-}
-
-tracked_path_exists() {
-  local repo_root="${1:?repo root required}"
-  local rel_path="${2:?relative path required}"
-  git -C "$repo_root" ls-files --error-unmatch -- "$rel_path" >/dev/null 2>&1
-}
-
-while IFS= read -r rel_path || [[ -n "$rel_path" ]]; do
-  [[ -n "$rel_path" ]] || continue
-  [[ "$rel_path" != \#* ]] || continue
-
-  source_path="${SOURCE_ROOT}/${rel_path}"
-    [[ -e "$source_path" ]] || { echo "source path missing: $rel_path" >&2; exit 1; }
-
-    copy_path "$source_path" "$BACKUP_ROOT" "$rel_path"
-    copy_path "$source_path" "$TARGET_ROOT" "$rel_path"
-
-  diff -qr "$source_path" "${TARGET_ROOT}/${rel_path}" >/dev/null
-done <"$PATHS_FILE"
-
-if [[ "$MOVE_MODE" == "true" ]]; then
-  while IFS= read -r rel_path || [[ -n "$rel_path" ]]; do
-    [[ -n "$rel_path" ]] || continue
-    [[ "$rel_path" != \#* ]] || continue
-
-    was_tracked="false"
-    if tracked_path_exists "$SOURCE_ROOT" "$rel_path"; then
-      was_tracked="true"
-      git -C "$SOURCE_ROOT" restore --worktree --source=HEAD -- "$rel_path"
-    fi
-
-    if [[ "$was_tracked" != "true" && -e "${SOURCE_ROOT}/${rel_path}" ]]; then
-      rm -rf "${SOURCE_ROOT:?}/${rel_path}"
-    fi
-  done <"$PATHS_FILE"
-fi
-
-printf 'SOURCE_ROOT=%s\n' "$SOURCE_ROOT"
-printf 'TARGET_ROOT=%s\n' "$TARGET_ROOT"
-printf 'PATHS_FILE=%s\n' "$PATHS_FILE"
-printf 'BACKUP_ROOT=%s\n' "$BACKUP_ROOT"
-printf 'MOVE_MODE=%s\n' "$MOVE_MODE"