{"_id":"@ahpd/sdk","_rev":"3-5c81d83f1020f4dbe23a28d1e589bb4e","name":"@ahpd/sdk","dist-tags":{"latest":"0.4.0"},"versions":{"0.2.0":{"name":"@ahpd/sdk","version":"0.2.0","keywords":["ahp","agent-host-protocol","agent-host","agent","ai","protocol","json-rpc","websocket","server","host","daemon"],"author":"Luiz Fernando Softov <lfs@softov.dev>","license":"MIT","_id":"@ahpd/sdk@0.2.0","maintainers":[{"name":"softov","email":"lfs@softov.dev"}],"homepage":"https://github.com/softov/ahpd#readme","bugs":{"url":"https://github.com/softov/ahpd/issues"},"dist":{"shasum":"efb968ebd5223c9fdcadd947aceeb701962d1eab","tarball":"https://registry.npmjs.org/@ahpd/sdk/-/sdk-0.2.0.tgz","fileCount":163,"integrity":"sha512-ZeKQ3fVw6a7eH3iqw0H6uVk6PegSIre1qSfHbjf6d+URVQ+wa+ggmfjIt7to3kPYR+fO6u/qNZPDpy2OLNKqsg==","signatures":[{"sig":"MEUCIQD+PGDmjY8eTkFFAUK6g1jYa+KOECMGwTc4slBRBsgg0gIgYpIRz/RnfKAopVsYcigfFKYg5fKgl89O/jZS+US9Kt4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1373230},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=22"},"exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js","development":"./src/index.ts"}},"scripts":{},"_npmUser":{"name":"softov","email":"lfs@softov.dev"},"repository":{"url":"git+https://github.com/softov/ahpd.git","type":"git","directory":"packages/sdk"},"description":"A server library for the Agent Host Protocol. No agent inside, you pass one in","directories":{},"_nodeVersion":"26.0.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@microsoft/agent-host-protocol":"^0.9.0"},"peerDependencies":{"@microsoft/agent-host-protocol":"^0.9.0"},"optionalDependencies":{"ws":"^8.18.0","node-pty":"^1.1.0-beta40"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.2.0_1788691974164_0.6039727855465287","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@ahpd/sdk","version":"0.3.0","keywords":["ahp","agent-host-protocol","agent-host","agent","ai","protocol","json-rpc","websocket","server","host","daemon"],"author":"Luiz Fernando Softov <lfs@softov.dev>","license":"MIT","_id":"@ahpd/sdk@0.3.0","maintainers":[{"name":"softov","email":"lfs@softov.dev"}],"homepage":"https://github.com/softov/ahpd#readme","bugs":{"url":"https://github.com/softov/ahpd/issues"},"dist":{"shasum":"7827d8f363f43cd1cf657d0fae2c700c43a87054","tarball":"https://registry.npmjs.org/@ahpd/sdk/-/sdk-0.3.0.tgz","fileCount":163,"integrity":"sha512-4x4OCg4oHk2H3fqiz2B2d4qfFB6KUyy9NlBJswHlCvBARrhPEH2RE56cLiL2jJAujaA6XqayDQG5nYiG7RE2+Q==","signatures":[{"sig":"MEUCIQDj5C8mppPK1y+4LK7nJMlq8Yt6toGhIm11pTU/bbKlIAIgDvPf0or7LX7xsvbnJ7OvvchW+m7xxGjcgZu19bWOFXY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIQDRJnm4c+V1EnTn27tUI4XEoUwTvpswcO63Z2MsCYjh8gIgG87tr/lC4ErirhkeWOn9y/RuZUixrofBfjdXnV8sE1s=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1383990},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=22"},"exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js","development":"./src/index.ts"}},"scripts":{},"_npmUser":{"name":"softov","email":"lfs@softov.dev"},"repository":{"url":"git+https://github.com/softov/ahpd.git","type":"git","directory":"packages/sdk"},"description":"A server library for the Agent Host Protocol. No agent inside, you pass one in","directories":{},"_nodeVersion":"26.0.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@microsoft/agent-host-protocol":"^0.9.0"},"peerDependencies":{"@microsoft/agent-host-protocol":"^0.9.0"},"optionalDependencies":{"ws":"^8.18.0","node-pty":"^1.1.0-beta40"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.3.0_1788710117810_0.6143207928013352","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"_id":"@ahpd/sdk@0.4.0","bugs":{"url":"https://github.com/softov/ahpd/issues"},"dist":{"shasum":"a13292f6131a6acee213938b1c9f2bf63e87481f","tarball":"https://registry.npmjs.org/@ahpd/sdk/-/sdk-0.4.0.tgz","integrity":"sha512-5SIPWJBeeWDIi7t2fxtxQdTux3G2ZxouCeN6v2F74B+TmlXAN5Xk5vZ81CMK9YgCjkoP1wOMsdLv2SD+Qp8DTw==","fileCount":173,"unpackedSize":1409900,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@ahpd%2fsdk@0.4.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCRbFHcjcnuHR825s6bpplVWUY6nZrw2a3i/KlmFlxGgwIgDNC04f8FoAmHrmkbMB2Z23zjEyg3z5B3PvN0MtAypVw="}]},"main":"./dist/index.js","name":"@ahpd/sdk","type":"module","_from":"file:/home/runner/work/_temp/ahpd-sdk-0.4.0.tgz","types":"./dist/index.d.ts","author":{"name":"Luiz Fernando Softov","email":"lfs@softov.dev"},"engines":{"node":">=22"},"exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js","development":"./src/index.ts"}},"license":"MIT","scripts":{},"version":"0.4.0","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:cde32375-68de-43a5-987e-8ad2a49ad7de"},"approver":{"name":"softov","email":"lfs@softov.dev"}},"homepage":"https://github.com/softov/ahpd#readme","keywords":["ahp","agent-host-protocol","agent-host","agent","ai","protocol","json-rpc","websocket","server","host","daemon"],"_resolved":"/home/runner/work/_temp/ahpd-sdk-0.4.0.tgz","_integrity":"sha512-5SIPWJBeeWDIi7t2fxtxQdTux3G2ZxouCeN6v2F74B+TmlXAN5Xk5vZ81CMK9YgCjkoP1wOMsdLv2SD+Qp8DTw==","repository":{"url":"git+https://github.com/softov/ahpd.git","type":"git","directory":"packages/sdk"},"_npmVersion":"12.0.2","description":"A server library for the Agent Host Protocol. No agent inside, you pass one in","directories":{},"maintainers":[{"name":"softov","email":"lfs@softov.dev"}],"_nodeVersion":"22.23.2","publishConfig":{"access":"public"},"devDependencies":{"@microsoft/agent-host-protocol":"^0.9.0"},"peerDependencies":{"@microsoft/agent-host-protocol":"^0.9.0"},"optionalDependencies":{"ws":"^8.18.0","node-pty":"^1.1.0-beta40"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.4.0_1788731236857_0.9754590937963898"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-06T10:52:53.976Z","modified":"2026-09-06T21:47:17.329Z","0.2.0":"2026-09-06T10:52:54.322Z","0.3.0":"2026-09-06T15:55:17.908Z","0.4.0":"2026-09-06T21:47:16.967Z"},"bugs":{"url":"https://github.com/softov/ahpd/issues"},"author":{"name":"Luiz Fernando Softov","email":"lfs@softov.dev"},"license":"MIT","homepage":"https://github.com/softov/ahpd#readme","keywords":["ahp","agent-host-protocol","agent-host","agent","ai","protocol","json-rpc","websocket","server","host","daemon"],"repository":{"url":"git+https://github.com/softov/ahpd.git","type":"git","directory":"packages/sdk"},"description":"A server library for the Agent Host Protocol. No agent inside, you pass one in","maintainers":[{"name":"softov","email":"lfs@softov.dev"}],"readme":"# @ahpd/sdk\n\n[![npm](https://img.shields.io/npm/v/%40ahpd%2Fsdk)](https://www.npmjs.com/package/@ahpd/sdk)\n[![CI](https://github.com/softov/ahpd/actions/workflows/ci.yml/badge.svg)](https://github.com/softov/ahpd/actions/workflows/ci.yml)\n![license MIT](https://img.shields.io/badge/license-MIT-blue)\n![node >=22](https://img.shields.io/badge/node-%3E%3D22-5fa04e)\n![Agent Host Protocol 0.9.0](https://img.shields.io/badge/AHP-0.9.0-0b7285)\n\nA server library for the [Agent Host Protocol](https://github.com/microsoft/agent-host-protocol).\n\nIt has no agent in it. You pass one in when you create the host.\n\n## Install\n\n```bash\npnpm add @ahpd/sdk @microsoft/agent-host-protocol\n```\n\nThe protocol package is a peer dependency. This package uses runtime values from it, so there should only be one copy in the dependency tree.\n\n## Use\n\nA small host using the Claude backend looks like this:\n\n```ts\nimport { createHost, listen } from '@ahpd/sdk';\nimport { claude } from '@ahpd/agent-claude';\n\nconst host = createHost({\n  path: process.cwd(),\n  agents: [claude({ paths: [process.cwd()] })],\n});\n\nconst listener = await listen({ port: 9187 }, (peer) => host.accept(peer));\nconsole.log(`on ws://${listener.host}:${listener.port} (${listener.runtime})`);\n```\n\n`createHost()` creates the AHP host.\n\n`listen()` is the WebSocket listener included for Node, Bun and Deno. The host itself is not tied to WebSockets.\n\nOnce a client is connected, the host takes care of version negotiation, snapshots, subscriptions, sequence numbers, transcript paging, completions, queued messages, shared drafts, read and archived flags, multiple chats per session, and turns.\n\n`accept(peer)` takes anything that can `send`, `notify` and `close`, and returns a handler. `listen` is a WebSocket implementation for Node, Bun and Deno. Tests supply their own, which is why the test suite runs without a network.\n\n## Options\n\n`path` and `agents` are required. The rest are optional. If you leave one out, the host returns an error for the commands it cannot serve instead of an empty result.\n\n\n```ts\nimport { \n  createHost, \n  fileResources, \n  shellTerminals, \n  gitChanges, \n  gitBranches, \n  gitWorktrees, \n  hostTools, \n  scheduledAutomations,\n} from '@ahpd/sdk'; \n\nconst host = createHost({ \n  path, \n  agents, \n  resources: fileResources(), \n  terminals: shellTerminals(), \n  changes: gitChanges(), \n  directories: gitBranches(), \n  worktrees: gitWorktrees(), \n  tools: hostTools(), \n  automations: scheduledAutomations({ file: './automations.json', }),\n});\n\n```\n\n| option | |\n| --- | --- |\n| `path` | the directory whose sessions this host serves |\n| `agents` | the backends to serve, as `Agent` implementations |\n| `resources` | file reads, writes, and `@` completion. Use `fileResources()` |\n| `terminals` | a shell as a terminal channel. Use `shellTerminals()` |\n| `changes` | uncommitted changes as a changeset. Use `gitChanges()` |\n| `directories` | the current branch of each served directory. Use `gitBranches()` |\n| `automations` | triggered agents. Use `memoryAutomations()`, or `scheduledAutomations({ file })` for cron |\n| `worktrees` | sessions in their own git worktree. Use `gitWorktrees()` |\n| `tools` | tools the host adds to every session. Use `hostTools()` |\n| `onEvent` | called with one line per notable event, for logging |\n\nNone of these are imported by the host itself. `fileResources` reads files, `shellTerminals` spawns shells, and `gitBranches` runs `git`, and you pass them in.\n\n## Writing a backend\n\n`Agent` has five required members: `provider`, `displayName`, `schema`, `defaults` and `create`.\n\n```ts\nimport type { Agent, Session, Start } from '@ahpd/sdk';\n\nexport function parrot(): Agent {\n  return {\n    provider: 'parrot',\n    displayName: 'Parrot',\n    schema: () => ({ properties: {} }),\n    defaults: () => ({}),\n    create: (start: Start): Session => converse(start),\n  };\n}\n```\n\n`provider` is the id a client names in `createSession`. It has to be unique among the agents one host was given.\n\n`schema()` says what a session of this kind can be configured with, and `defaults()` says where those keys start. Both can be empty.\n\n`create()` returns the session. The session holds the state of the session and chat channels, and calls `start.emit('chat', ...)` as things happen.\n\nPass it to the host like any other backend: `createHost({ path, agents: [parrot()] })`. Your backend and [`@ahpd/agent-claude`](https://www.npmjs.com/package/@ahpd/agent-claude) register identically and can run side by side.\n\nSee [docs/AGENT.md](https://github.com/softov/ahpd/blob/main/docs/AGENT.md) for the contract, and [examples/echo](https://github.com/softov/ahpd/tree/main/examples/echo) for a working backend in about two hundred lines.\n\n## Types\n\nAll types are exported. Nothing under `types/` imports a runtime value, so you can read the contract without loading the implementation.\n\n## Documentation\n\n| | |\n| --- | --- |\n| [LIBRARY.md](https://github.com/softov/ahpd/blob/main/docs/LIBRARY.md) | `createHost` and the ports in full |\n| [AGENT.md](https://github.com/softov/ahpd/blob/main/docs/AGENT.md) | The `Agent` and `Session` contracts |\n| [AHP.md](https://github.com/softov/ahpd/blob/main/docs/AHP.md) | Protocol coverage action by action |\n\n## License\n\nMIT © Softov\n\n","readmeFilename":"README.md"}