@theokit/acp

Agent Client Protocol (ACP) server adapter for @theokit/sdk.

Exposes a SDKAgent over stdio JSON-RPC so any ACP-compatible host can drive it as a coding agent — without writing any glue code.

npm i @theokit/acp @theokit/sdk @agentclientprotocol/sdk

Quick start

// my-agent.ts (the file your ACP host will spawn)
import { Agent } from "@theokit/sdk";

export default async (sessionId: string) => {
  return Agent.create({
    apiKey: process.env.OPENROUTER_API_KEY,
    model: { id: "openai/gpt-4o-mini" },
    local: { cwd: process.cwd() },
    name: `acp-${sessionId}`,
  });
};

# Launch the server (an ACP host will do this for you)
npx theokit-acp --entry ./my-agent.ts

Permission modes

• --permission ask (default) — every tool call prompts the host UI.
• --permission auto — pass-through; no UI.
• --permission deny — reject every tool call (headless CI).
• --trusted-tools read_file,list_dir — names bypassed in ask mode.
• --permission-timeout-ms 60000 — auto-deny after timeout (EC-2 / D355).

Use in code

import { Agent } from "@theokit/sdk";
import { serveAcp } from "@theokit/acp";

await serveAcp({
  agent: async (sessionId) => Agent.create({ /* ... */ }),
  info: { name: "my-agent", version: "1.0.0" },
  permissionDefault: "ask",
  trustedTools: ["read_file", "list_dir"],
});

Architecture

| ACP concept | SDK mapping | | ----------------- | -------------------------------------------------------------- | | new_session | Agent.create({ local: { cwd } }) | | load_session | Agent.resume(sessionId) (D352) | | cancel | session AbortController.abort() (D354) | | prompt | agent.send(text, { signal }).stream() (D353) | | tool permission | pre_tool_call veto hook (D355) | | session/fork | deferred to v0.2 (D350) |

Versioning

Pre-1.0 (0.x). Breaking changes are allowed within 0.x (D181 pattern) until upstream ACP stabilizes.

API reference

Every symbol this package exports, with the exact specifier to import it from, is in the generated capability map that ships inside @theokit/sdk:

node_modules/@theokit/sdk/docs/harness-capability-map.md   # symbol -> import specifier
node_modules/@theokit/sdk/docs/error-codes.md              # every `code` an error can carry

Both are generated from the built type declarations, so they describe the version you installed rather than the version someone wrote a page about.

License

Apache-2.0