ACP Server

Experimental Agent Client Protocol building blocks for connecting ACP clients to Comis

Comis includes experimental, library-level Agent Client Protocol building blocks in @comis/gateway. ACP connects an editor or other client process to an agent over a standard protocol.

Comis does not yet ship a daemon command or configuration entrypoint for ACP. The current implementation is partial and intended for integrators. Do not present it as a turnkey editor integration or complete ACP implementation.

What is implemented

The gateway package uses @agentclientprotocol/sdk 0.22.1 and exports createAcpAgent and startAcpServer.

Operation	Current behavior
initialize	Echoes the requested protocol version and returns Comis agent metadata with an empty capability object.
newSession	Creates an in-memory ACP session mapped to a Comis session key.
prompt	Joins text content blocks and delegates them to an injected executeAgent callback. Non-text blocks are ignored.
authenticate	No-op for the local stdio process.
cancel	Removes the session and retained connection. It does not currently abort an in-flight agent execution.

The package also contains redacted activity, plan, and permission-request bridge components. Permission outcomes are currently emitted and logged but are not routed back into a server-side approval decision sink. Full approval round-trip behavior is therefore not complete.

Transport

startAcpServer communicates through newline-delimited JSON on stdin and stdout. The ACP client starts the process and owns the stdio connection.

All application logging must go to stderr. Writing logs or other text to stdout corrupts the protocol stream.

Session model

Each newSession call creates a UUID and maps it to:

• channelId: "acp"
• userId: "ide-user"
• peerId set to the ACP session UUID

The in-memory session map keeps up to 1,000 entries by default and evicts the oldest entry at capacity. This is transport session state, not a claim of full editor-session persistence or protocol lifecycle coverage.

Integrator example

The current API requires a small Node.js entrypoint that supplies a real Comis agent executor:

import { startAcpServer } from "@comis/gateway";
import pino from "pino";

const logger = pino({ level: "info" }, pino.destination(2));

await startAcpServer({
  version: "1.0.0",
  logger,
  async executeAgent({ message, sessionKey }) {
    return myAgentExecutor.execute({ message, sessionKey });
  },
});

Build the repository or published package before running the entrypoint, then configure an ACP-compatible client to launch it with node. Client configuration varies, so verify the exact command and protocol capabilities against that client’s current documentation.

Security boundaries

• Stdio avoids a listening network port, but the spawned process still runs with the operating-system authority of its account.
• authenticate is a no-op. The local spawn relationship is the current trust assumption.
• All callers currently share the fixed ide-user identity and rely on the ACP session UUID for peer scoping.
• ACP prompt text is still untrusted input. The injected executor must preserve Comis request context, policy, tool, secret, and output-guard boundaries.
• Activity and plan bridges are designed to send redacted frames. Permission prompts do not yet complete a Comis approval decision round trip.

Current gaps

• no daemon-level entrypoint or config.yaml section;
• no advertised non-text prompt support;
• empty capability negotiation;
• cancel does not abort active execution;
• incomplete approval-response routing;
• no general claim of tested compatibility across editors or ACP clients.

Track ACP as early interoperability work until these gaps are closed and verified end to end.