Acp Debug

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

test -x apps/backend/bin/acpdbg || make -C apps/backend build-acpdbg

Sub-commands

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).

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:

Entries are strictly chronological. Each line is a single JSON object terminated by \n.

Useful jq recipes:

# 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:

**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