{"_id":"@burner-io/hermes","_rev":"2-3fe179c46cbdea1dd76e1389091eb728","name":"@burner-io/hermes","dist-tags":{"latest":"0.6.0"},"versions":{"0.5.0":{"name":"@burner-io/hermes","version":"0.5.0","keywords":["hermes","sdk","typescript","mcp","ai","react-query","vercel-ai-sdk"],"author":{"name":"Tarek Bachir"},"license":"MIT","_id":"@burner-io/hermes@0.5.0","maintainers":[{"name":"strasberry","email":"bachir.tarek.pro@gmail.com"}],"homepage":"https://github.com/burner-io/hermes#readme","bugs":{"url":"https://github.com/burner-io/hermes/issues"},"dist":{"shasum":"b0c743c8db1d14ce131e907b39304bc38823d9f0","tarball":"https://registry.npmjs.org/@burner-io/hermes/-/hermes-0.5.0.tgz","fileCount":186,"integrity":"sha512-nBEax8IP1QXKJrUFJrc2tIAfHTgcYoKCyHPh+qU/r6Q1xJLbbAmb1PQMzZTW+QYhAh8VFUPHJO7wkW/acAav4w==","signatures":[{"sig":"MEUCIHTSty+KFUD42wDG/15z14kg+5k0JwnrmoQ7txhWnGjTAiEA/g2HYumWS8gC4LUd5H9sj3FaydSlV8mMhkH9sHZHT7g=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":468586},"type":"module","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"./ai-sdk":{"types":"./dist/integrations/ai-sdk.d.ts","default":"./dist/integrations/ai-sdk.js"},"./runtime":{"types":"./dist/runtime/index.d.ts","default":"./dist/runtime/index.js"},"./contracts":{"types":"./dist/contracts/index.d.ts","default":"./dist/contracts/index.js"},"./react-query":{"types":"./dist/integrations/react-query.d.ts","default":"./dist/integrations/react-query.js"}},"gitHead":"6469659d10666c28a84a0357d1ccf8e28e2811ee","private":false,"scripts":{"test":"node --test tests/*.test.mjs","build":"tsc -p tsconfig.json","check":"tsc -p tsconfig.json --noEmit && tsc -p tsconfig.json && node --test tests/*.test.mjs","typecheck":"tsc -p tsconfig.json --noEmit","prepublishOnly":"npm run check"},"_npmUser":{"name":"strasberry","email":"bachir.tarek.pro@gmail.com"},"repository":{"url":"git+https://github.com/burner-io/hermes.git","type":"git"},"_npmVersion":"10.9.8","description":"Hermes-native TypeScript SDK with faithful management contracts, programmatic execution protocols, transport, React Query-compatible factories, and optional Vercel AI SDK tools.","directories":{},"sideEffects":false,"_nodeVersion":"22.23.2","_hasShrinkwrap":false,"devDependencies":{"ai":"^6.0.253","typescript":"^5.8.3","@tanstack/react-query":"^5.101.4"},"peerDependencies":{"ai":">=6.0.0 <7","@tanstack/react-query":">=5.90.0 <6"},"peerDependenciesMeta":{"ai":{"optional":true},"@tanstack/react-query":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/hermes_0.5.0_1786654989184_0.9693231986076822","host":"s3://npm-registry-packages-npm-production"}},"0.6.0":{"name":"@burner-io/hermes","version":"0.6.0","private":false,"description":"Hermes-native TypeScript SDK with one-origin private connection helpers, faithful control-plane contracts, native Runs/TUI transports, and optional React Query / AI SDK integrations.","type":"module","sideEffects":false,"license":"MIT","author":{"name":"Tarek Bachir"},"repository":{"type":"git","url":"git+https://github.com/burner-io/hermes.git"},"bugs":{"url":"https://github.com/burner-io/hermes/issues"},"homepage":"https://github.com/burner-io/hermes#readme","keywords":["hermes","sdk","typescript","mcp","ai","react-query","vercel-ai-sdk"],"exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"./contracts":{"types":"./dist/contracts/index.d.ts","default":"./dist/contracts/index.js"},"./runtime":{"types":"./dist/runtime/index.d.ts","default":"./dist/runtime/index.js"},"./react-query":{"types":"./dist/integrations/react-query.d.ts","default":"./dist/integrations/react-query.js"},"./ai-sdk":{"types":"./dist/integrations/ai-sdk.d.ts","default":"./dist/integrations/ai-sdk.js"}},"scripts":{"build":"tsc -p tsconfig.json","typecheck":"tsc -p tsconfig.json --noEmit","check":"tsc -p tsconfig.json --noEmit && tsc -p tsconfig.json && node --test tests/*.test.mjs","test":"node --test tests/*.test.mjs","prepublishOnly":"npm run check","release":"node scripts/release.mjs"},"engines":{"node":">=20"},"devDependencies":{"@tanstack/react-query":"^5.101.4","ai":"^6.0.253","typescript":"^5.8.3"},"peerDependencies":{"@tanstack/react-query":">=5.90.0 <6","ai":">=6.0.0 <7"},"peerDependenciesMeta":{"@tanstack/react-query":{"optional":true},"ai":{"optional":true}},"_id":"@burner-io/hermes@0.6.0","gitHead":"319e71b34b31d9dab9165617a2e8e7123f31bac0","_nodeVersion":"22.23.2","_npmVersion":"10.9.8","dist":{"integrity":"sha512-u22FtHZ7PX4KvePdEfOEFxBLZAxlBe+iG+Z+Q/WWKBJtnuy7EJmShkJ58C9dyN92wO+dpCp4Pi+O7P6z8Y4s1A==","shasum":"abd2595547eaa177527bf1f1cc07742af0287662","tarball":"https://registry.npmjs.org/@burner-io/hermes/-/hermes-0.6.0.tgz","fileCount":191,"unpackedSize":479641,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCF0lhnD1PXzQsUhWt3bnGU01Zt7X9qdcCwWMGZBNy1AAIgPTV0LQzTub28+nMvnAHUpuZYCthzps2Vi2OxUbTn4Xg="}]},"_npmUser":{"name":"strasberry","email":"bachir.tarek.pro@gmail.com"},"directories":{},"maintainers":[{"name":"strasberry","email":"bachir.tarek.pro@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/hermes_0.6.0_1786709267820_0.7536697836746966"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-13T21:03:08.997Z","modified":"2026-08-14T12:07:48.962Z","0.5.0":"2026-08-13T21:03:09.372Z","0.6.0":"2026-08-14T12:07:47.979Z"},"bugs":{"url":"https://github.com/burner-io/hermes/issues"},"author":{"name":"Tarek Bachir"},"license":"MIT","homepage":"https://github.com/burner-io/hermes#readme","keywords":["hermes","sdk","typescript","mcp","ai","react-query","vercel-ai-sdk"],"repository":{"type":"git","url":"git+https://github.com/burner-io/hermes.git"},"description":"Hermes-native TypeScript SDK with one-origin private connection helpers, faithful control-plane contracts, native Runs/TUI transports, and optional React Query / AI SDK integrations.","maintainers":[{"name":"strasberry","email":"bachir.tarek.pro@gmail.com"}],"readme":"# @burner-io/hermes\n\nHermes-native TypeScript SDK modeled from Hermes itself.\n\n**V0.6.0 adds a one-origin private machine connection as the recommended application seam:** one `baseUrl`, one `API_SERVER_KEY`-derived `apiKey`, and typed control + API Server/Run facades over that same trusted Hermes origin.\n\nThe low-level transports remain available because Hermes still has native auth/routing variants that some deployments use directly. V0.6 does not erase those native differences; it stops forcing applications to model them as separate upstreams when their private Hermes ingress exposes them behind one origin and one Bearer credential.\n\n## Non-negotiable rule\n\nIf a resource, field, state, operation, or relationship cannot be traced to Hermes itself, it does not belong in this package's Hermes domain contracts.\n\nThe package therefore keeps Hermes vocabulary and wire spelling intact:\n\n- `Profile` stays `Profile`.\n- `Skill` stays `Skill`.\n- `Session` stays `Session`.\n- `Toolset` stays `Toolset`.\n- `MCP` stays `MCP`.\n- Kanban `Board`, `Task`, `Run`, `Worker`, `Event`, `Diagnostic` keep their Hermes meanings.\n- Native payload fields keep `snake_case`.\n\nApplication-owned concepts must adapt to this package, never the reverse.\n\n## Install\n\n```bash\nnpm install @burner-io/hermes\n```\n\nThe core SDK has no runtime dependency. Optional subpaths declare optional peers: `@tanstack/react-query >=5.90 <6` and `ai >=6 <7`. The core targets Node.js 20+ and browser runtimes with `fetch`, `FormData`, `Blob`, and optionally `WebSocket`.\n\n## Recommended: one private Hermes connection\n\nFor a trusted backend/private ingress where the same Hermes origin accepts the same machine Bearer credential across the Hermes route families your application uses:\n\n```ts\nimport { createHermesConnection } from \"@burner-io/hermes\";\n\nconst hermes = await createHermesConnection({\n  baseUrl: process.env.HERMES_URL!,\n  apiKey: process.env.HERMES_API_KEY!,\n});\n\nconst status = await hermes.control.system.status();\nconst profiles = await hermes.control.profiles.list();\nconst sessions = await hermes.control.sessions.list({ order: \"recent\" });\n\nconst capabilities = await hermes.capabilities();\nconst run = await hermes.runs.create({ input: \"Review this release\" });\nconst final = await hermes.runs.wait(run.run_id);\n```\n\n`createHermesConnectionUnchecked()` creates the same connection without startup surface probing, which is useful for SSR/bootstrap/tests.\n\nThe connection deliberately exposes two typed facades:\n\n```text\nHermesConnection\n├── control   -> Hermes-native /api/* + plugin/control namespaces\n└── apiServer -> native API Server /v1/*, selected /api/*, health and SSE\n```\n\nThey receive the **same `baseUrl` and the same `apiKey`**. They are SDK views over one trusted origin, not an instruction to configure two application URLs or two secrets.\n\nConveniences:\n\n- `connection.runs` -> `connection.apiServer.runs`\n- `connection.capabilities()` -> API Server capabilities\n- `connection.models()` -> API Server model aliases\n- `connection.health()` -> API Server health/readiness\n\nNative profile scoping remains faithful per facade: control methods use the control endpoint's native profile semantics, while API Server calls use Hermes' `/p/<profile>/...` multiplex prefix.\n\n## Low-level control client\n\nUse `createHermesClient()` directly when you intentionally need Hermes' lower-level control transport configuration, such as legacy/session-token or gated Dashboard deployments:\n\n```ts\nimport { createHermesClient } from \"@burner-io/hermes\";\n\nconst hermes = await createHermesClient({\n  baseUrl: \"http://127.0.0.1:9119\",\n  sessionToken: process.env.HERMES_SESSION_TOKEN,\n  profile: \"designer\",\n});\n```\n\nLow-level auth options remain native and explicit:\n\n- `sessionToken` -> `X-Hermes-Session-Token`.\n- cookies through `credentials: \"include\"` by default.\n- `bearerToken` -> `Authorization: Bearer ...`.\n- WebSocket ticket/session/internal auth modes.\n\nThese options are intentionally not part of `createHermesConnection()`, whose contract is the private machine Bearer model.\n\n## Low-level API Server client\n\nUse `createApiServerApi()` when you only need the API Server surface:\n\n```ts\nimport { createApiServerApi } from \"@burner-io/hermes\";\n\nconst api = createApiServerApi({\n  baseUrl: process.env.HERMES_URL!,\n  apiKey: process.env.HERMES_API_KEY!,\n  profile: \"reviewer\",\n});\n\nconst run = await api.runs.create({ input: \"Review the release plan\" });\nconst unsubscribe = await api.runs.events(run.run_id, console.log);\nconst final = await api.runs.wait(run.run_id);\nunsubscribe();\n```\n\nThe typed Runs surface includes native create/get/events/approval/stop plus client-side `wait()` polling. `raw()` remains available for API Server endpoints not yet typed.\n\n## Native profile scoping\n\n`profile` is **not** globally appended to every control request. The runtime applies the configured profile only to native Hermes families that actually support it, and keeps machine-global/self-scoped operations unmodified.\n\nFor the API Server facade, a configured profile uses Hermes' native `/p/<profile>/...` multiplex prefix.\n\n## Raw, binary and multipart access\n\nTyped namespaces cover the reviewed Hermes surfaces. Escape hatches prevent the SDK from blocking new Hermes releases:\n\n```ts\nawait hermes.control.raw.request({\n  method: \"GET\",\n  path: \"/api/some-new-hermes-surface\",\n});\n\nconst response = await hermes.control.response(\n  \"GET\",\n  \"/api/some-binary-endpoint\",\n);\n\nconst apiValue = await hermes.apiServer.raw(\"GET\", \"/api/sessions\");\n```\n\nMultipart helpers create `FormData` and never set `Content-Type` manually; fetch/runtime supplies the boundary.\n\n## Kanban live events\n\nWhen the native Kanban plugin is reachable:\n\n```ts\nconst unsubscribe = await hermes.control.kanban?.events(\n  (frame) => {\n    for (const event of frame.events) console.log(event.kind, event.task_id);\n  },\n  { board: \"default\" },\n);\n```\n\nThe SDK preserves Hermes' `{ events, cursor }` frame shape.\n\n## TUI Gateway JSON-RPC\n\nFor interactive clients, `connection.control.tuiGateway` speaks Hermes' native JSON-RPC protocol on `/api/ws`:\n\n```ts\nconst gateway = await hermes.control.tuiGateway.connect();\nconst { session_id } = await gateway.createSession({\n  source: \"tool\",\n  close_on_disconnect: true,\n});\n\nconst off = gateway.on(\"message.delta\", (event) => console.log(event.payload));\nawait gateway.submitPrompt({ session_id, text: \"Analyze this repository\" });\n```\n\nThe SDK preserves native JSON-RPC method/event names. See `docs/PROGRAMMATIC.md`.\n\n## React Query integration\n\n```ts\nimport { createHermesReactQuery } from \"@burner-io/hermes/react-query\";\n\nconst hq = createHermesReactQuery(hermes.control, {\n  scopeKey: \"prod:designer\",\n  queryClient,\n});\n```\n\n## AI SDK integration\n\n```ts\nimport { createHermesAiTools } from \"@burner-io/hermes/ai-sdk\";\n\nconst tools = createHermesAiTools(hermes.control, {\n  mode: \"workflow\",\n  board: \"product\",\n});\n```\n\nThe AI SDK adapter delegates to Hermes-native operations; it does not create a second agent/orchestrator.\n\n## Native surface inventory\n\nControl namespaces include:\n\n`auth`, `system`, `config`, `env`, `dashboard`, `profiles`, `skills`, `sessions`, `tools`, `mcp`, `models`, `providers`, `audio`, `messaging`, `webhooks`, `credentials`, `memory`, `learning`, `curator`, `analytics`, `filesystem`, `git`, `cron`, `operations`, `plugins`, `gateway`, `updates`, `logs`, `portal`, plus optional native Kanban.\n\nNative Hermes `Project` value types remain exported because Hermes contains that concept. There is deliberately **no core `hermes.projects` management namespace** until a traced Hermes core route supports it; Kanban may expose its own project summaries.\n\nSee `docs/INVENTORY.md`, `docs/RUNTIME.md`, `docs/PROGRAMMATIC.md`, and `docs/SOURCE-MAP.md`.\n\n## Validation\n\n```bash\nnpm run check\n```\n\nV0.6 adds one-origin/Bearer transport tests while keeping the V0.5 control, Runs, TUI, Kanban and integration coverage. See `VALIDATION.md`.\n","readmeFilename":"README.md"}