> ## Documentation Index
> Fetch the complete documentation index at: https://comis-fix-skill-import-vetting-gate.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# ACP Server

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

Comis includes experimental, library-level
[Agent Client Protocol](https://agentclientprotocol.com) building blocks in
`@comis/gateway`. ACP connects an editor or other client process to an agent
over a standard protocol.

<Warning>
  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.
</Warning>

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

```typescript theme={}
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.