acp-debug
/acp-debug
Debug an ACP agent CLI by spawning it, speaking raw JSON-RPC, and capturing every frame to a JSONL file. Use when the user asks to probe an agent's capabilities, compare agents, test a prompt against an agent, inspect raw ACP wire frames, or investigate why an agent fails to initialize.
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
AGPL-3.0, copyleft: przeróbki udostępniane innym muszą mieć tę samą licencję.
What it does and when to use it
Debug an ACP agent CLI by spawning it, speaking raw JSON-RPC, and capturing every frame to a JSONL file. Use when the user asks to probe an agent's capabilities, compare agents, test a prompt against an agent, inspect raw ACP wire frames, or investigate why an agent fails to initialize.
Original author description
Debug an ACP agent CLI by spawning it, speaking raw JSON-RPC, and capturing every frame to a JSONL file. Use when the user asks to probe an agent's capabilities, compare agents, test a prompt against an agent, inspect raw ACP wire frames, or investigate why an agent fails to initialize.
How it works
- When to use this skill
- Before anything else: build the binary if missing
- Sub-commands
- Steps
- What this skill does NOT do
SKILL.md preview
--- name: acp-debug description: Debug an ACP agent CLI by spawning it, speaking raw JSON-RPC, and capturing every frame to a JSONL file. Use when the user asks to probe an agent's capabilities, compare agents, test a prompt against an agent, inspect raw ACP wire frames, or investigate why an agent fails to initialize. --- # ACP Debug Run a headless ACP JSON-RPC session against any registered kandev agent (or an arbitrary command), record every wire frame to a JSONL file, and summarize the handshake. Backed by the `acpdbg` binary at `apps/backend/bin/acpdbg`. ## When to use this skill - "what models does auggie advertise" - "probe claude-acp" / "probe all agents" / "run the matrix" - "debug why copilot-acp isn't starting" - "what does a `session/new` response actually look like for X" - "try this prompt against auggie with mode=ask" - "reproduce session/load for session <id> against claude-acp" - User mentions inspecting raw ACP wire payloads or a JSONL file from an earlier run ## Before anything else: build the binary if missing ```bash test -x apps/backend/bin/acpdbg || make -C apps/backend build-acpdbg ``` ## Sub-commands ```text acpdbg list # enumerate registered ACP agents acpdbg probe <agent> # initialize + session/new + close acpdbg probe --exec "<cmd> [args...]" # probe an arbitrary binary not in the registry acpdbg mcp-probe <agent> # inject a temporary MCP sentinel into session/new acpdbg prompt --prompt "..." [--model M] [--mode M] <agent> acpdbg session-load --session-id <id> <agent> acpdbg matrix # probe every ACP agent in parallel ``` > **Flags MUST come before the positional `<agent>`.** The CLI uses Go's stdlib > `flag` parser, which stops at the first non-flag token — so any flag placed > *after* `<agent>` is silently ignored (`probe`/`matrix`, e.g. a dropped > `--timeout`) or errors (`prompt` → `--prompt is required`). Always write > `acpdbg prompt --prompt "..." --timeout 240s <agent>`, not `acpdbg prompt <agent> --prompt ...`. **Shared flags** (apply to every sub-command): - `--out DIR` — JSONL output directory (default `./acp-debug/`) - `--file PATH` — exact JSONL path, overrides `--out` - `--timeout DUR` — overall run timeout (default `30s`) - `--workdir PATH` — child cwd (default: fresh `/tmp/kandev-acpdbg-<pid>-*`) - `--verbose` — mirror frames to stderr - `--stderr` — capture child stderr into the JSONL ## Steps **Create a task for each step below and mark them as completed as you go.** ### 1. Pick the sub-command that matches the user's intent - "what models does X have" / "does X support modes" → `acpdbg probe X` - "test a prompt against X" → `acpdbg prompt --prompt "..." X` - "compare all agents" / "run the matrix" → `acpdbg matrix` - "resume session <id>" → `acpdbg session-load --session-id <id> X` - "did this agent attach the injected MCP server" → `acpdbg mcp-probe X` - "try this random binary" → `acpdbg probe --exec "path/to/bin --acp"` ### 2. Run the command Always capture stdout — it contains the JSONL file path (and for `matrix`, the summary table and `matrix-summary.json` path). ```bash apps/backend/bin/acpdbg probe --timeout 45s auggie ``` For `matrix`, prefer `--timeout 60s` so `npx`-spawned agents have time to cold-start. For Claude ACP, the generated default workdir is an absolute temporary directory and is sent as the ACP `cwd`; no `--workdir` flag is required. If you override it, supply an existing absolute directory (for example, run `mkdir -p /tmp/kandev-acpdbg-claude` before passing that path to `--workdir`). An empty `cwd` can cause Claude to reject `session/new`; confirm the `cwd` in the recorded request frame before diagnosing a provider failure. ### 3. Read the JSONL file The JSONL schema is: | `direction` | Meaning | Extra fields | |---|---|---| | `meta` | acpdbg-generated marker | `event` (`start` / `close`), `meta` (map with `agent`, `command`, `workdir` for start; `exit_code`, `reason` for close) | | `sent` | Frame written to child's stdin | `frame` (JSON-RPC request or reply) | | `received` | Frame read from child's stdout | `frame` (JSON-RPC request, response, or notification) | | `stderr` | Child stderr line (only when `--stderr`) | `line` | Entries are strictly chronological. Each line is a single JSON object terminated by `\n`. Useful `jq` recipes: ```bash # Full initialize response jq -c 'select(.direction == "received" and .frame.id == 1)' acp-debug/<file>.jsonl # Full session/new response (models, modes, auth) jq '.frame.result' acp-debug/<file>.jsonl | head -50 # Just the models advertised jq -r 'select(.direction == "received") | .frame.result.models.availableModels[]?.modelId' acp-debug/<file>.jsonl # Close event (exit code + reason) jq -c 'select(.direction == "meta" and .event == "close")' acp-debug/<file>.jsonl # All agent-initiated requests we auto-replied to jq -c 'select(.direction == "received" and .frame.method and .frame.id)' acp-debug/<file>.jsonl ``` ### 4. Summarize for the user Give a concise markdown summary: agent, protocol version, models found (with currentModelId), modes found (with currentModeId), auth methods, any errors, and the JSONL path for deeper inspection. Example: ```text **auggie** (protocol v1, auggie 0.20.1) Models (11): claude-sonnet-4-6 (current), claude-opus-4-6, gpt-5-4, … Modes (2): default (current), ask Auth methods: (none advertised) JSONL: acp-debug/auggie-probe-20260409-183104.jsonl ``` ### 5. If something looks wrong, walk the frames Common failure modes: | Symptom | Likely cause | Next step | |---|---|---| | meta close `exit_code: 127` immediately | child binary not installed | Check `which <cmd>`; suggest install command | | meta close before any `received` frame | child crashed on startup | Re-run with `--stderr` to capture the error | | `initialize` response has populated `authMethods` but session/new fails | auth required | Surface the auth method ids; suggest setting env var / running CLI login | | `session/new` hangs (context deadline exceeded) | agent waiting on an unanswered agent-initiated request | Check JSONL for `received` frames with `method` + `id` that we auto-replied to with `method not found` — the agent may be retrying | | Response has no `models` / `modes` fields | agent doesn't expose them over ACP | Not a bug — document the gap | Re-run with `--stderr` whenever the child exits before the handshake completes; the stderr lines land in the JSONL and usually contain the root cause. For `mcp-probe`, distinguish `sentinel_delivered` (the agent accepted the `session/new` configuration) from `initialize_observed` and `tools_list_observed` (the temporary endpoint received MCP traffic). An `unobserved` result is intentionally not a generic agent failure: a provider can attach lazily or ignore the supplied transport. Sentinel metadata has only opaque connection IDs and timestamps; the explicit acpdbg JSONL still contains raw ACP frames and must stay a developer-only artifact. ### 6. For `matrix`, read `matrix-summary.json` too ```bash jq '.' acp-debug/matrix-summary.json ``` One entry per agent with `status`, `models_count`, `current_model_id`, `auth_methods_count`, `duration_ms`, and `jsonl` (the full per-agent JSONL file). Useful for answering "which agents succeeded / failed / need auth" without re-reading every JSONL. ## What this skill does NOT do - No interactive UI. For ad-hoc side-by-side comparison, read the `matrix-summary.json` output or build a separate visualization tool on top of the JSONL. - No permission-request handling beyond canned replies. Agent-initiated requests (`fs/read_text_file`, `session/request_permission`, etc.) are answered with `-32601 method not found` so the session doesn't hang. If you need to exercise a real permission flow, use the full kandev backend. - No automatic credential bootstrap. The child inherits the parent shell's env; if an auth check fails the skill reports which methods were advertised and lets the user fix their local credentials. - No Docker / remote executor support. Standalone subprocess only — same as a manual `auggie --acp` invocation.
Versions
The database has no other skills named acp-debug.
Database snapshot: 13.11.2026 · package version 873e6080355a (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90acp-product-feed
Build product feed generation and submission for ACP. Use when implementing product catalog export, feed formatting (CSV/JSON/XML/TSV), feed validation, and push-based catalog sync to the agent platform. - 100acpremote
Use for `acpremote` tasks: exposing ACP agents or stdio ACP commands over WebSocket, mirroring remote ACP endpoints locally, host ownership semantics, metadata/auth routes, and remote transport examples. - 100acp-setup
Scaffold an ACP merchant server project — install dependencies, import OpenAPI specs and JSON schemas, configure environment, and create initial endpoint stubs. Use when starting a new ACP implementation from scratch. - 100acp
Use when implementing the Agent Communication Protocol (ACP) for REST-based agent-to-agent communication, task delegation, and multimodal message exchange. USE FOR: ACP agent servers, ACP client integration, agent discovery via manifests, run lifecycle management, session-based… - 100acp-service
使用 @1agents/acp-service 管理 ACP 会话与 DSH 插件,通过 A2A 调用固定角色、派发临时任务、查询父子任务和执行轮次、记录业务验收及处理通知,并回投 Codex/DSH 原会话。也用于项目/角色候选探查、目标登记、网络技能缓存和更新接口接入;不用于无关的系统巡检或模型配置。 - 95pydantic-acp
Use for `pydantic-acp` tasks: exposing `pydantic_ai.Agent` through ACP, adapter config/runtime ownership, extension routing, authentication, prompt capabilities, slash commands, approvals, plans, hooks, projections, host-backed tools, and Pydantic-specific examples.