{"_id":"@aegismesh/sdk","name":"@aegismesh/sdk","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@aegismesh/sdk","version":"0.1.0","description":"Aegis Mesh SDK for Node.js — per-task correlation IDs that thread through every audit-ledger row your agent's HTTP calls produce.","type":"module","main":"./src/index.mjs","exports":{".":{"import":"./src/index.mjs","default":"./src/index.mjs"}},"engines":{"node":">=18.0.0"},"scripts":{"test":"node --test 'test/**/*.test.mjs'"},"keywords":["aegis","aegismesh","agent-security","ai-agent","observability","audit","task-correlation","tracing"],"author":{"name":"AegisMesh"},"license":"Apache-2.0","homepage":"https://aegismesh.dev","repository":{"type":"git","url":"git+https://github.com/akashvisshal-web/aegis-mesh.git","directory":"sdk/node"},"bugs":{"url":"https://github.com/akashvisshal-web/aegis-mesh/issues"},"peerDependencies":{"undici":">=5.0.0"},"peerDependenciesMeta":{"undici":{"optional":true}},"publishConfig":{"access":"public"},"gitHead":"1e57146faa8f02962c53371992fb8b8e5aec3b4b","_id":"@aegismesh/sdk@0.1.0","_nodeVersion":"26.0.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-GZHQH/krLOrtJqKWinAwRE0d8auwCVGVGCfy96IKPCTpmVoTD7Ks+BLwTuQarIggpSKQRCxthDr3L/wS91Nb9w==","shasum":"aaa05d16ce1d533e71aa77544ab85de2aa729872","tarball":"https://registry.npmjs.org/@aegismesh/sdk/-/sdk-0.1.0.tgz","fileCount":5,"unpackedSize":28877,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCID1uc42ZJDmrA2wXMyP3dwfnNkCyLGG2HxlVV6hp+yjpAiEAxeYHIbpGWl/qXQuuhYi+JvPmX8UMLyJgQN+iTDV1u9E="}]},"_npmUser":{"name":"aegismesh","email":"hello@aegismesh.dev"},"directories":{},"maintainers":[{"name":"aegismesh","email":"hello@aegismesh.dev"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.1.0_1779808116280_0.7701779400077078"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-26T15:08:36.112Z","0.1.0":"2026-05-26T15:08:36.430Z","modified":"2026-05-26T15:08:36.638Z"},"maintainers":[{"name":"aegismesh","email":"hello@aegismesh.dev"}],"description":"Aegis Mesh SDK for Node.js — per-task correlation IDs that thread through every audit-ledger row your agent's HTTP calls produce.","homepage":"https://aegismesh.dev","keywords":["aegis","aegismesh","agent-security","ai-agent","observability","audit","task-correlation","tracing"],"repository":{"type":"git","url":"git+https://github.com/akashvisshal-web/aegis-mesh.git","directory":"sdk/node"},"author":{"name":"AegisMesh"},"bugs":{"url":"https://github.com/akashvisshal-web/aegis-mesh/issues"},"license":"Apache-2.0","readme":"# `@aegismesh/sdk`\n\nAegis Mesh SDK for Node.js. Threads a per-task correlation ID through every\naudit-ledger row produced by your agent's HTTP and HTTPS calls.\n\n> Aegis Mesh is kernel-level governance for AI agents. The SDK is the\n> Node-side bridge between your agent code and the Aegis audit pipeline.\n> See https://aegismesh.dev for the platform.\n\n## Install\n\n```bash\nnpm install @aegismesh/sdk\n```\n\n## Usage\n\nWrap any unit of work (a prompt, a tool call, a request handler) in `task()`:\n\n```js\nimport { task } from '@aegismesh/sdk';\n\nawait task('process-refund', async () => {\n  // Every fetch / http.request inside this scope auto-injects\n  // X-Aegis-Agent-Task-Id with a fresh UUID. The proxy stamps the\n  // UUID onto every audit-ledger row produced by this work unit.\n  const r = await fetch('https://api.stripe.com/v1/refunds', {\n    method: 'POST',\n    body: '...',\n  });\n  return r.json();\n});\n```\n\nIn the Aegis dashboard, every kernel-LSM, capability-gate, and DNS row from\nthat scope rolls up under one task UUID. Without the SDK, rows still flow but\nfall back to a coarse per-process correlation.\n\n### Reading the current task ID\n\n```js\nimport { getCurrentTaskId, getCurrentTaskName } from '@aegismesh/sdk';\n\nconsole.log(getCurrentTaskId());   // \"fd78ac5b-76bd-4320-6cbd-a1ce9d360ae5\"\nconsole.log(getCurrentTaskName()); // \"process-refund\" (empty outside a scope)\n```\n\nOutside any `task()` scope, `getCurrentTaskId()` returns a stable\nprocess-default UUID (minted lazily on first read).\n\n### Manual header stamping\n\nFor HTTP clients that don't share `undici`'s global dispatcher (e.g. `got`,\n`axios` with a custom `httpAgent`), stamp the header yourself:\n\n```js\nimport { getCurrentTaskId } from '@aegismesh/sdk';\n\nawait fetch(url, {\n  headers: { 'x-aegis-agent-task-id': getCurrentTaskId() },\n});\n```\n\n## How it works\n\nThe SDK is two pieces:\n\n1. **AsyncLocalStorage scope** — `task(name, fn)` pushes a UUID onto Node's\n   AsyncLocalStorage. Any awaited descendants inherit it across async\n   boundaries.\n\n2. **undici dispatcher patch** — on import, the SDK composes an interceptor\n   onto `undici.getGlobalDispatcher()` that reads the current task ID from\n   AsyncLocalStorage and stamps `X-Aegis-Agent-Task-Id` on every outbound\n   HTTP request. If `HTTPS_PROXY` is set (the Aegis sidecar topology), the\n   SDK also installs a custom CONNECT-issuing agent that stamps the header\n   on the CONNECT request itself — so cap-gate denies at the CONNECT layer\n   also carry the task ID.\n\nThe SDK is auto-installed on import. For explicit control, call\n`installFetchHook()`.\n\n## Compatibility\n\n- Node.js 18 or newer (uses `node:async_hooks` AsyncLocalStorage + native fetch).\n- `undici` is a peer dependency. Node 18+ ships an internal undici copy that\n  works for `globalThis.fetch`. If you import `undici` directly in your app\n  code, install it explicitly:\n\n  ```bash\n  npm install undici@^7\n  ```\n\n## Aegis-side configuration\n\nThe SDK only emits headers. The Aegis proxy (deployed by your operator via\n`aegis platform up`) does the rest:\n\n- Reads `X-Aegis-Agent-Task-Id` off every request that traverses it.\n- Stamps the UUID onto every `audit_ledger` row produced by the request's\n  kernel-LSM hits, capability-gate decisions, and DNS lookups.\n- Surfaces \"View all rows for this task\" CTAs in the Aegis dashboard.\n\nIf your operator hasn't deployed Aegis on the node yet, the SDK still runs\nharmlessly — the header just goes unread.\n\n## License\n\nApache-2.0. See `LICENSE`.\n\n## Links\n\n- Homepage: https://aegismesh.dev\n- Source: https://github.com/akashvisshal-web/aegis-mesh/tree/main/sdk/node\n- Issues: https://github.com/akashvisshal-web/aegis-mesh/issues\n","readmeFilename":"README.md","_rev":"1-663dcfa484aeaff719a60abd90c25200"}