{"_id":"@a9650615/claude-acp-kit","_rev":"2-d82957a5d04903d3a91b5e3ff5638f13","name":"@a9650615/claude-acp-kit","dist-tags":{"latest":"0.2.1"},"versions":{"0.2.0":{"name":"@a9650615/claude-acp-kit","version":"0.2.0","keywords":["acp","agent-client-protocol","claude","claude-code","anthropic","zed","agent","json-rpc","mcp"],"author":{"name":"a9650615"},"license":"MIT","_id":"@a9650615/claude-acp-kit@0.2.0","maintainers":[{"name":"a9650615","email":"a9650615@gmail.com"}],"homepage":"https://github.com/a9650615/claude-acp-kit#readme","bugs":{"url":"https://github.com/a9650615/claude-acp-kit/issues"},"bin":{"acp":"dist/cli/index.js"},"dist":{"shasum":"38fc1a01db9e56bead08a277c327341d02758687","tarball":"https://registry.npmjs.org/@a9650615/claude-acp-kit/-/claude-acp-kit-0.2.0.tgz","fileCount":43,"integrity":"sha512-m6MXmFwK92TUaz/FFLLfl52SRFMgmeKIyVc1CUQA93PzVLGI0TQrPKdHSW6KJqmMn1TeKW7xfes8uGJytLVoCw==","signatures":[{"sig":"MEUCIQC0x1R0bYpn9gIfSbZzvEZThS7Bp037u4jakNurCbl2HwIgFJk6c+o69k7AkjF8dyj29Php6/WYWfyYdTZclIy6n70=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1019045},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20.10.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./cli":{"types":"./dist/cli/index.d.ts","import":"./dist/cli/index.js"},"./auth":{"types":"./dist/auth/index.d.ts","import":"./dist/auth/index.js"},"./tools":{"types":"./dist/tools/index.d.ts","import":"./dist/tools/index.js"},"./usage":{"types":"./dist/usage/index.d.ts","import":"./dist/usage/index.js"},"./server":{"types":"./dist/server.d.ts","import":"./dist/server.js"},"./skills":{"types":"./dist/skills/index.d.ts","import":"./dist/skills/index.js"},"./protocol":{"types":"./dist/protocol/index.d.ts","import":"./dist/protocol/index.js"},"./transport":{"types":"./dist/transport/index.d.ts","import":"./dist/transport/index.js"},"./permissions":{"types":"./dist/permissions/index.d.ts","import":"./dist/permissions/index.js"}},"gitHead":"5112050cdd7417b534727acd0129ce7fca38ddb5","scripts":{"dev":"tsup --watch","lint":"biome check . && node scripts/check-imports.mjs","test":"vitest run","build":"tsup","clean":"rm -rf dist coverage .turbo","format":"biome format --write .","release":"changeset publish","version":"changeset version","lint:fix":"biome check --write . && node scripts/check-imports.mjs","changeset":"changeset","typecheck":"tsc --noEmit","test:watch":"vitest","check:imports":"node scripts/check-imports.mjs","test:coverage":"vitest run --coverage","prepublishOnly":"npm run clean && npm run typecheck && npm run lint && npm run test && npm run build","example:minimal":"tsx examples/minimal-agent/index.ts","test:integration":"vitest run --config vitest.integration.config.ts","typecheck:examples":"tsc --noEmit -p tsconfig.examples.json"},"_npmUser":{"name":"a9650615","email":"a9650615@gmail.com"},"repository":{"url":"git+https://github.com/a9650615/claude-acp-kit.git","type":"git"},"_npmVersion":"10.8.2","description":"Generic Claude ACP (Agent Client Protocol) library — build agents fast with batteries included: auth, usage, permissions, tools, MCP supervision.","directories":{},"_nodeVersion":"20.20.2","dependencies":{"zod":"^3.23.8","pino":"^9.5.0"},"publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","tsup":"^8.3.0","vitest":"^2.1.0","typescript":"^5.6.0","@types/node":"^22.10.0","@biomejs/biome":"^1.9.0","@changesets/cli":"^2.27.0","@vitest/coverage-v8":"^2.1.0"},"peerDependencies":{"ccusage":"*"},"peerDependenciesMeta":{"ccusage":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/claude-acp-kit_0.2.0_1778750897702_0.07477830371196426","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@a9650615/claude-acp-kit","version":"0.2.1","description":"Generic Claude ACP (Agent Client Protocol) library — build agents fast with batteries included: auth, usage, permissions, tools, MCP supervision.","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./server":{"types":"./dist/server.d.ts","import":"./dist/server.js"},"./auth":{"types":"./dist/auth/index.d.ts","import":"./dist/auth/index.js"},"./usage":{"types":"./dist/usage/index.d.ts","import":"./dist/usage/index.js"},"./tools":{"types":"./dist/tools/index.d.ts","import":"./dist/tools/index.js"},"./permissions":{"types":"./dist/permissions/index.d.ts","import":"./dist/permissions/index.js"},"./protocol":{"types":"./dist/protocol/index.d.ts","import":"./dist/protocol/index.js"},"./skills":{"types":"./dist/skills/index.d.ts","import":"./dist/skills/index.js"},"./transport":{"types":"./dist/transport/index.d.ts","import":"./dist/transport/index.js"},"./cli":{"types":"./dist/cli/index.d.ts","import":"./dist/cli/index.js"}},"bin":{"acp":"dist/cli/index.js"},"scripts":{"build":"tsup","dev":"tsup --watch","typecheck":"tsc --noEmit","typecheck:examples":"tsc --noEmit -p tsconfig.examples.json","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","test:integration":"vitest run --config vitest.integration.config.ts","lint":"biome check . && node scripts/check-imports.mjs","lint:fix":"biome check --write . && node scripts/check-imports.mjs","check:imports":"node scripts/check-imports.mjs","format":"biome format --write .","clean":"rm -rf dist coverage .turbo","prepublishOnly":"npm run clean && npm run typecheck && npm run lint && npm run test && npm run build","release":"changeset publish","changeset":"changeset","version":"changeset version","example:minimal":"tsx examples/minimal-agent/index.ts"},"engines":{"node":">=20.10.0"},"dependencies":{"pino":"^9.5.0","zod":"^3.23.8"},"devDependencies":{"@biomejs/biome":"^1.9.0","@changesets/cli":"^2.27.0","@types/node":"^22.10.0","@vitest/coverage-v8":"^2.1.0","tsup":"^8.3.0","tsx":"^4.19.0","typescript":"^5.6.0","vitest":"^2.1.0"},"peerDependencies":{"ccusage":"*"},"peerDependenciesMeta":{"ccusage":{"optional":true}},"keywords":["acp","agent-client-protocol","claude","claude-code","anthropic","zed","agent","json-rpc","mcp"],"author":{"name":"a9650615"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/a9650615/claude-acp-kit.git"},"bugs":{"url":"https://github.com/a9650615/claude-acp-kit/issues"},"homepage":"https://github.com/a9650615/claude-acp-kit#readme","publishConfig":{"access":"public"},"_id":"@a9650615/claude-acp-kit@0.2.1","gitHead":"fc6e9d0f29fd7590b08f5a68f3ab133f584e34d1","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-Z9n++E70tnQ2MB6uFeQ4/RYneNmo2NMG67eU49BC/8ZzlVGh5y1B7reMxBFdak2J6ELn1v8SJSXaBj4DwmCjsQ==","shasum":"7e5a4e0bcb037591370952f702a297669e2264ab","tarball":"https://registry.npmjs.org/@a9650615/claude-acp-kit/-/claude-acp-kit-0.2.1.tgz","fileCount":43,"unpackedSize":1019606,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCDVHv1XcbGHaNGm91TrWSTHMQSejgTVJMAdjo91X15LwIhAI+joXtPGIM3r/NKyXYc6NrcWQmtU8JBAGmsRpu76S3w"}]},"_npmUser":{"name":"a9650615","email":"a9650615@gmail.com"},"directories":{},"maintainers":[{"name":"a9650615","email":"a9650615@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/claude-acp-kit_0.2.1_1778751925339_0.7318466055671884"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-14T09:28:17.638Z","modified":"2026-05-14T09:45:25.640Z","0.2.0":"2026-05-14T09:28:17.888Z","0.2.1":"2026-05-14T09:45:25.525Z"},"bugs":{"url":"https://github.com/a9650615/claude-acp-kit/issues"},"author":{"name":"a9650615"},"license":"MIT","homepage":"https://github.com/a9650615/claude-acp-kit#readme","keywords":["acp","agent-client-protocol","claude","claude-code","anthropic","zed","agent","json-rpc","mcp"],"repository":{"type":"git","url":"git+https://github.com/a9650615/claude-acp-kit.git"},"description":"Generic Claude ACP (Agent Client Protocol) library — build agents fast with batteries included: auth, usage, permissions, tools, MCP supervision.","maintainers":[{"name":"a9650615","email":"a9650615@gmail.com"}],"readme":"# @a9650615/claude-acp-kit\n\nGeneric Claude **ACP (Agent Client Protocol)** library — batteries-included primitives so a new agent project can ship in minutes instead of weeks.\n\n> Status: **0.1.0 – pre-release.** API surface is stabilizing; expect minor breakages until 1.0.\n\n## Why\n\nEvery Claude agent needs the same plumbing: JSON-RPC framing over stdio, session lifecycle, permission flow, credential detection, usage tracking, MCP supervision, structured logging. This library packages all of that with strict types and zero magic, so your project only writes the parts that are actually unique.\n\n## Features\n\n| Feature                   | What it does                                                          |\n| ------------------------- | --------------------------------------------------------------------- |\n| **AcpServer**             | NDJSON JSON-RPC dispatch loop with typed handlers                     |\n| **Sessions**              | Lifecycle, persistence, mode switching, cancellation                  |\n| **Auth detector**         | Reads `~/.claude/.credentials.json`, watches mtime, sniffs 401s       |\n| **Login helper**          | Shells to `claude /login` and waits for refreshed creds               |\n| **Usage tracker**         | Wraps `ccusage` for session/daily/monthly; in-process token counter   |\n| **Budget gate**           | Per-session caps + alert hooks                                        |\n| **Permissions**           | `allow_once / allow_always / reject_*` policy + audit log             |\n| **Tools registry**        | Zod-validated tool definitions, typed executor                        |\n| **MCP supervisor**        | Spawn, restart, health-check stdio MCP servers                        |\n| **Backoff/retry**         | Exponential w/ jitter for 429/529                                     |\n| **Cancellation**          | Propagates `session/cancel` to in-flight work                         |\n| **Logger**                | pino-based, session_id correlation                                    |\n| **Heartbeat**             | Health checks + auto-reconnect                                        |\n\n## Install\n\n```bash\nnpm install @a9650615/claude-acp-kit\n# optional: enable ccusage integration\nnpm install ccusage\n```\n\n## Try it without installing\n\n```bash\nnpx @a9650615/claude-acp-kit doctor                                    # environment check\nnpx @a9650615/claude-acp-kit init my-agent && cd my-agent && npm i     # scaffold an agent\nnpx @a9650615/claude-acp-kit usage daily --since 2026-01-01            # ccusage report\nnpx @a9650615/claude-acp-kit skills list                               # discover ~/.claude/skills\nnpx @a9650615/claude-acp-kit serve ./agent.ts                          # run an agent file\n```\n\nSubcommands documented in [`src/cli/README.md`](./src/cli/README.md).\n\n## Quickstart\n\n```ts\nimport { AcpServer, Transport, createLogger } from \"@a9650615/claude-acp-kit\";\n\nconst { StdioTransport } = Transport;\n\nconst logger = createLogger({ level: \"info\" });\nconst transport = new StdioTransport({ logger });\n\nconst server = new AcpServer({\n  transport,\n  logger,\n  agent: {\n    async prompt(ctx, params) {\n      ctx.emit({\n        sessionUpdate: \"agent_message_chunk\",\n        content: { type: \"text\", text: \"hello!\" },\n      });\n      return { stopReason: \"end_turn\" };\n    },\n  },\n});\n\nawait server.start();\n```\n\nThis matches [`examples/minimal-agent`](./examples/minimal-agent) verbatim\n(modulo the relative imports we use to build pre-publish). See\n[`examples/`](./examples) for the full set, including a richer agent wired\nwith usage tracking, budget gating, permissions, and a tool registry.\n\n## Documentation\n\n| For | Read |\n| --- | --- |\n| First-time setup | [docs/GETTING_STARTED.md](./docs/GETTING_STARTED.md) |\n| Per-feature usage | [docs/USAGE.md](./docs/USAGE.md) |\n| Copy-paste patterns | [docs/RECIPES.md](./docs/RECIPES.md) |\n| Common gotchas | [docs/FAQ.md](./docs/FAQ.md) |\n| Git flow + agent handoff | [docs/GIT_FLOW.md](./docs/GIT_FLOW.md) |\n| Module architecture | [ARCHITECTURE.md](./ARCHITECTURE.md) |\n| Each module's API | `src/<module>/README.md` |\n\n## Architecture\n\nSee [ARCHITECTURE.md](./ARCHITECTURE.md) for module boundaries, interface contracts, and ADRs.\n\n## For agents (human or AI) working on this repo\n\nRead [**AGENTS.md**](./AGENTS.md) first. It is the canonical rule sheet for module ownership, the non-contamination contract, the git/npm boundaries, and the documentation duties. A pre-commit import guard (`scripts/check-imports.mjs`) enforces module boundaries mechanically.\n\n## Project layout\n\n```\nacp_base_lib/\n├── src/\n│   ├── server.ts             # AcpServer dispatch\n│   ├── transport/            # stdio NDJSON JSON-RPC\n│   ├── protocol/             # wire types + zod schemas\n│   ├── session/              # session lifecycle\n│   ├── auth/                 # cred detect + login\n│   ├── usage/                # ccusage + tracker\n│   ├── tools/                # registry + executor\n│   ├── permissions/          # gate + policy\n│   ├── mcp/                  # MCP child-process supervisor\n│   ├── logging/              # pino logger\n│   ├── errors/               # normalized JSON-RPC errors\n│   ├── utils/                # backoff, cancellation, events\n│   └── config/               # env + file loader\n├── examples/\n├── docs/\n│   ├── adr/                  # architectural decision records\n│   └── work-log/             # per-module dev journals\n└── .github/workflows/        # CI + release\n```\n\n## Development\n\n```bash\nnpm install\nnpm run typecheck\nnpm run lint\nnpm run test\nnpm run build\n```\n\n### Per-module work logs\n\nEvery module owner appends to `docs/work-log/<module>.md` when shipping work. Captures intent, tradeoffs, and follow-ups. Don't skip — that log is how a future contributor (or you in six months) understands a non-obvious choice.\n\n### Contributing\n\nRead [CONTRIBUTING.md](./CONTRIBUTING.md). Conventional commits enforced via `lefthook`. Releases via [changesets](https://github.com/changesets/changesets).\n\n## License\n\n[MIT](./LICENSE)\n","readmeFilename":"README.md"}