acp-subagent-orchestrator

ACP (Agent Client Protocol) subagent orchestration skill for Codex-style workflows.

This project helps you:

• run explicit delegated tasks to ACP-compatible agents (Claude / Codex / Copilot),
• enforce task ownership boundaries,
• model task dependencies and critical-path scheduling,
• produce a structured JSON report for integration and review.

License

MIT

Requirements

• Python 3.10+
• One or more ACP runners available locally (or installed via setup flow)

Quick Start

1. Generate/setup runner config:

python3 scripts/setup.py --help

Show supported runners (25 ACP tools in current catalog):

python3 scripts/setup.py --list-catalog

Example:

# Configure only Claude (recommended to match explicit user choice)
# default is quick setup: no dynamic discovery, keep runner default mode
python3 scripts/setup.py --agents claude

# Configure by alias (e.g. github-copilot / qwen-code / factory-droid)
python3 scripts/setup.py --agents github-copilot,qwen-code,factory-droid

# Configure all runners explicitly
python3 scripts/setup.py --agents all

# Advanced: enable dynamic discovery and set mode/options explicitly
python3 scripts/setup.py --agents codex --discover --codex-mode full-access

2. Prepare a plan JSON (see references/plan.example.json).

3. Run the orchestrator:

python3 scripts/acp_orchestrator.py \
  --plan /path/to/plan.json \
  --setup ./setup.json \
  --output /tmp/acp-report.json

Note: The plan JSON can also include a "setup" field (path relative to the plan file) as an alternative to the --setup CLI flag. The CLI flag takes precedence if both are provided.

4. Resume after partial failure:

python3 scripts/acp_orchestrator.py \
  --plan /path/to/plan.json \
  --resume /tmp/acp-report.json \
  --skip-tasks task-a,task-b \
  --output /tmp/acp-report-resumed.json

--resume skips tasks that already succeeded. --skip-tasks force-marks specific task IDs as succeeded (useful when a task produced its artifact but timed out during finalization).

Strict Model Handling

When a task requests a model via session_config_options, model application is treated as strict:

• if the requested model is unavailable, the task fails immediately;
• the error includes currently available model choices (when exposed by the runner);
• the error message provides two fix paths:
  • update global default model in setup.json (agents.<agent>.default_config_options.model);
  • or set task.session_config_options.model explicitly for that task only.

Heartbeat (Long Tasks)

By default, waiting on a long session/prompt emits a low-noise heartbeat line every 60s:

[task-id] running 120s, updates=5, idle=42s

This heartbeat is intentionally non-semantic and only signals liveness.

• override interval: --heartbeat-interval-sec 30
• disable heartbeat: --no-heartbeat
• config via plan/setup: heartbeat_enabled, heartbeat_interval_sec

Runner Health Check (On Demand)

Use this only when you need a status snapshot. It is not required before every run.

python3 scripts/runner_health.py --setup ./setup.json

Checks include:

• whether each runner can connect via ACP;
• whether the configured default model is still in the runner's available model list.

Optional:

• check subset: --agents codex,copilot
• JSON report: --output /tmp/acp-runner-health.json

Repository Layout

• SKILL.md: skill instructions and guardrails
• scripts/setup.py: setup config generation (discovery optional)
• scripts/runner_health.py: on-demand runner/model health check
• references/agent_catalog.json: ACP runner catalog (aliases + install metadata)
• scripts/acp_orchestrator.py: ACP JSON-RPC orchestration runtime
• references/: examples and rule references