018: ACP Transparent Agent Server via JSON-RPC 2.0 stdio Subprocess

Status: Accepted Date: 2026-05-30 Issue: F102 Supersedes: N/A Superseded by: ADR 020 (implementation detail, not decision)

Context#

AWF orchestrates AI agents through YAML workflows. Editors and IDE extensions (Zed, acp.nvim) that already drive those same agents want to use AWF as a transparent backend: the editor sends prompts, AWF dispatches them through configured workflows, and structured events flow back in real time — without the user switching to a terminal.

F102 must solve four problems that together constitute an external-facing API contract:

1. Session lifecycle: Editors need to open, prompt, and cancel named sessions that persist across multiple turns of a conversation, with AWF routing each prompt through an appropriate workflow.
2. Event streaming: Step lifecycle events (started, completed, failed), agent message chunks, tool calls, and thought chunks must reach the editor as structured notifications as they occur — not as a single bulk response at completion.
3. Approval gates: When a workflow step requires user confirmation (e.g., shell command execution), AWF must call back into the editor to request permission before proceeding.
4. MCP server overlay: Editors may provide their own MCP server configuration that must be merged with the workflow’s per-step MCP proxy configuration, with editor entries taking precedence on key collision.

Two protocol-level questions are load-bearing beyond this feature:

• Which protocol governs the editor–AWF session contract? The answer locks in an external-facing API that editor plugin authors will compile against.
• How is bidirectionality handled? AWF must originate requests to the editor (for approval gates), not only respond to editor-originated requests. This is a structural departure from MCP’s purely server-driven request/response model.

Candidates#

Protocol#

Bidirectionality Mechanism#

Process Topology#

Decision#

Protocol: Adopt ACP over JSON-RPC 2.0 (stdio transport). Implement the required subset for v1: initialize, initialized, session/new, session/prompt, session/cancel, session/request_permission (server-originated), and shutdown. Prompts, resources, fs/ tools, and terminal/ methods are out of scope and deferred.

Process topology: Option A — per-session subprocess awf acp-serve. One awf acp-serve process is spawned by the editor per session. The subprocess serves ACP over stdin/stdout. Lifecycle is signal-aware: signal.NotifyContext with SIGTERM→SIGKILL grace matching newMCPServeCommand.

Bidirectionality: Server.CallClient(ctx, method, params) — a single outbound primitive on acpserver.Server. It serialises the request through a sync.Mutex-protected json.Encoder (same encoder used for responses, preventing interleave), parks the goroutine on a buffered channel stored in a sync.Map keyed by a server-generated integer ID, and returns when the matching inbound response is dispatched by the serve loop’s probe path. The probe unmarshals only the method and id fields; frames with method == "" and a matching pending ID are treated as responses; all others as requests.

Public package: ACP engine lives in pkg/acpserver/ (not internal/), with zero internal/ imports enforced by an AST-based architecture test (architecture_test.go). This mirrors the pkg/mcpserver/ invariant from ADR-017 and gives future external consumers a stable embeddable ACP engine.

MCP merge-precedence rule (FR-011): When an editor provides session/new.mcpServers, those entries are merged with the workflow’s per-step MCP proxy configuration inside ACPSessionService.handleSessionNew. On key collision, the editor-provided entry wins. The merge result is stored on the ACPSession and overlaid at step-start time. This rule is implemented in the application layer; ExecutionService is not modified.

Key rules established:

• pkg/acpserver depends on Go stdlib only — no internal/ imports, no framework deps. Verified at every CI run by architecture_test.go.
• ACPClient port (domain) has exactly one method for v1: RequestPermission(ctx, toolCall, options) (bool, error). fs/ and terminal/ methods are deferred; pre-declaring stubs would leak out-of-scope features into the domain.
• ACPRenderer is instantiated per workflow step, not per session — tool-call ID deduplication (first occurrence → tool_call, subsequent → tool_call_update) must not bleed across steps.
• USER.ACP.* error codes extend the existing taxonomy at exit code 1: INVALID_PROMPT, UNSUPPORTED_BLOCK, PROMPT_IN_FLIGHT, UNKNOWN_SESSION, PROTOCOL_VERSION_UNSUPPORTED. No new exit-code category is introduced.
• awf acp-serve is Hidden: true — not user-facing; no independent stability guarantees; registered in root.go adjacent to newMCPServeCommand.
• ACP protocol version is a single integer constant in pkg/acpserver/protocol.go. Mismatches surface as USER.ACP.PROTOCOL_VERSION_UNSUPPORTED with a textual message rather than a silent failure.
• FanoutPublisher wraps the existing ports.EventPublisher — ExecutionService is not modified to support N publishers. The fan-out wiring happens at the interfaces layer.

Consequences#

What becomes easier:

• Editors (Zed, acp.nvim) can use AWF as a transparent workflow backend without shelling out to awf run and parsing stdout.
• Multi-turn conversational sessions are first-class: ConversationManager parking across session/prompt cycles is supported by the ACPInputReader channel bridge.
• Approval gates are synchronous from the workflow’s perspective: ACPClient.RequestPermission blocks the step until the editor responds or the session context is cancelled.
• All step and workflow lifecycle events reach the editor as structured notifications via WorkflowEventProjector — no polling, no log scraping.
• Future fs/terminal methods can be added by extending the ACPClient port and implementing a new infrastructure adapter, with no changes to ACPSessionService or the engine.
• External consumers can embed pkg/acpserver to build custom ACP-enabled tooling; the stdlib-only invariant makes it a zero-overhead dependency.

What becomes harder:

• Adding new ACP methods (e.g., fs/read, terminal/exec) is a semver-visible change to pkg/acpserver and requires a coordinated release with editor plugin updates.
• Each awf acp-serve process consumes ~10 MB RSS. Long-lived editor sessions that never close their ACP process will hold that memory until the editor exits or explicitly closes the session.
• The sync.Map-tracked response channels in Server.CallClient require callers to always pass a context.Context with a deadline; an unbounded context would park the goroutine indefinitely if the editor never responds to a session/request_permission.
• Two near-identical Cobra serve scaffolds (mcp_serve.go + acp_serve.go) coexist; the ServeInitializer DRY extraction is intentionally deferred until a third serve variant stabilises.
• Windows support is deferred: Setpgid + syscall.Kill(-pgid, ...) for process-group teardown is POSIX-only. ACP integration tests gate on //go:build integration && !windows.

Constitution Compliance#