Skip to content

AGENTS.md

Latest commit

 

History

History
79 lines (51 loc) · 3.01 KB

AGENTS.md

File metadata and controls

79 lines (51 loc) · 3.01 KB
Raw

pi-acp (ACP adapter for pi-coding-agent)

This repository implements an Agent Client Protocol (ACP) adapter for pi (@earendil-works/pi-coding-agent) without modifying pi.

  • ACP side: JSON-RPC 2.0 over stdio using @agentclientprotocol/sdk (TypeScript)
  • Pi side: spawn pi --mode rpc and communicate via newline-delimited JSON over stdio

Architecture (MVP)

1 ACP session ↔ 1 pi subprocess

Pi RPC mode is effectively single-session, so the adapter maps:

  • session/new → spawn a dedicated pi --mode rpc process
  • session/prompt → send {type:"prompt"} to that process and stream events back as session/update
  • session/cancel → send {type:"abort"}

ACP server wiring (modeled after opencode)

Use @agentclientprotocol/sdk:

  • ndJsonStream(input, output) to speak ACP over stdio
  • new AgentSideConnection((conn) => new PiAcpAgent(conn, config), stream)

Implementation constraints / decisions

  • Do not implement ACP client-side FS/terminal delegation in MVP. Pi already reads/writes and executes locally.
  • Ignore mcpServers for MVP (accept in params, store in session state).
  • Stream all pi assistant output as ACP agent_message_chunk initially.
  • Tool events: map pi tool execution events to ACP tool_call / tool_call_update (as text content).

Dev workflow (to be filled once scaffold exists)

  • Install deps: npm install
  • Run in dev: npm run dev
  • Build: npm run build
  • Smoke test (stdio): npm run smoke
  • Lint: npm run lint
  • Test: npm run test

Manual testing notes

Once the adapter runs, it should behave like an ACP agent on stdio.

Quick sanity test (example):

# Send initialize request via stdin (exact fields depend on ACP SDK version)
# echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":1}}' | node dist/index.js

For real validation, test with an ACP client (e.g. Zed external agent).

Coding guidelines

  • Keep ACP protocol handling in src/acp/*.
  • Keep pi RPC subprocess logic in src/pi-rpc/*.
  • Prefer small translation functions (pi event → ACP session/update) with unit tests.
  • Be strict about streaming and process cleanup (handle exit, drain stdout/stderr, timeouts).
  • Avoid producing unnecessary comments! Use comments sparingly to explain non-obvious decisions, not to narrate code.
  • Avoid using any in TypeScript; prefer explicit types and interfaces. Only use any when absolutely necessary (e.g. for untyped external data).

Validation

  • After making code edits, run formatting before finishing the task. Use npm run format when it is safe to format the whole worktree; otherwise use the narrowest safe formatter command for the files you touched.
  • If formatting is skipped or fails, say so explicitly in the final response.

Source control

  • DO NOT commit unless explicitly asked!

Client information

  • Current ACP client is Zed

References

  • Local ACP repo with protocol documentation and specs: ~/Dev/learning/agent-client-protocol
  • Local Zed repo ~/Dev/learning/zed/zed