{"_id":"@agent-assembly/sdk","name":"@agent-assembly/sdk","dist-tags":{"alpha":"0.0.1-alpha.3","latest":"0.0.1-alpha.3"},"versions":{"0.0.1-alpha.3":{"name":"@agent-assembly/sdk","version":"0.0.1-alpha.3","description":"TypeScript SDK for Agent Assembly","license":"Apache-2.0","type":"module","engines":{"node":">=18.18.0","pnpm":">=10"},"repository":{"type":"git","url":"git+https://github.com/AI-agent-assembly/node-sdk.git"},"bugs":{"url":"https://github.com/AI-agent-assembly/node-sdk/issues"},"homepage":"https://github.com/AI-agent-assembly/node-sdk#readme","exports":{".":{"import":"./dist/esm/index.js","require":"./dist/cjs/index.js","types":"./dist/types/index.d.ts"}},"peerDependencies":{"@langchain/core":">=0.3.0","@openai/agents":">=0.1.0"},"peerDependenciesMeta":{"@langchain/core":{"optional":true},"@openai/agents":{"optional":true}},"devDependencies":{"@eslint/js":"^10.0.1","@napi-rs/cli":"3.7.0","@types/js-yaml":"^4.0.9","@types/node":"^25.9.1","@vitest/coverage-v8":"^2.1.8","blocked-at":"^1.2.0","eslint":"^10.4.1","grpc-tools":"^1.13.1","js-yaml":"^4.1.1","langchain":"^1.4.0","prettier":"^3.5.3","ts-proto":"^2.11.8","typescript":"^6.0.3","typescript-eslint":"^8.60.0","vitest":"^2.1.8"},"keywords":["agent-assembly","sdk","typescript","nodejs"],"optionalDependencies":{"@agent-assembly/runtime-darwin-arm64":"0.0.1-alpha.3","@agent-assembly/runtime-darwin-x64":"0.0.1-alpha.3","@agent-assembly/runtime-linux-x64":"0.0.1-alpha.3","@agent-assembly/runtime-linux-arm64":"0.0.1-alpha.3"},"types":"./dist/types/index.d.ts","dependencies":{"@bufbuild/protobuf":"^2.12.0","@grpc/grpc-js":"^1.14.4"},"scripts":{"build":"pnpm run build:esm && pnpm run build:cjs","typecheck":"tsc -p tsconfig.test.json --noEmit","native:build":"pnpm exec napi build --manifest-path native/aa-ffi-node/Cargo.toml --output-dir native/aa-ffi-node --no-js --dts index.d.ts --js-package-name @agent-assembly/sdk","native:build:release":"pnpm exec napi build --manifest-path native/aa-ffi-node/Cargo.toml --output-dir native/aa-ffi-node --release --platform --no-js --dts index.d.ts --js-package-name @agent-assembly/sdk","native:check-types":"tsc --strict --noEmit --ignoreConfig native/aa-ffi-node/index.d.ts","lint":"eslint .","format":"prettier --write .","gen:proto":"node ./scripts/gen-proto.mjs","test":"vitest run","test:coverage":"vitest run --coverage --coverage.reporter=lcov --coverage.reporter=text","build:esm":"tsc -p tsconfig.build.json","build:cjs":"tsc -p tsconfig.cjs.json && node ./scripts/write-cjs-package-json.mjs","postinstall":"node ./scripts/postinstall.mjs"},"_id":"@agent-assembly/sdk@0.0.1-alpha.3","_integrity":"sha512-UyFTgtIomhEVWyy2XAEz+KzXNJkmcaAPjbeKuAZusQnYzjE2gqjuZsgzDHysSzv6qb5Sgp45o6+MxolCEoAfNw==","_resolved":"/tmp/8f10a958b1301316def8e1553b1c927d/agent-assembly-sdk-0.0.1-alpha.3.tgz","_from":"file:agent-assembly-sdk-0.0.1-alpha.3.tgz","_nodeVersion":"24.16.0","_npmVersion":"11.13.0","dist":{"integrity":"sha512-UyFTgtIomhEVWyy2XAEz+KzXNJkmcaAPjbeKuAZusQnYzjE2gqjuZsgzDHysSzv6qb5Sgp45o6+MxolCEoAfNw==","shasum":"a9cc12a87d568fee3b84a0dd07209a2968fc936f","tarball":"https://registry.npmjs.org/@agent-assembly/sdk/-/sdk-0.0.1-alpha.3.tgz","fileCount":256,"unpackedSize":523814,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBX36B6DjUNVWyLe65pmeyplGcTv52L6nrrcJdGoYNRqAiAly8+4YWKCxXVsdSabgYUBPY2qR7zCIgabMnAF5ll21w=="}]},"_npmUser":{"name":"bryant08","email":"chi10211201@cycu.org.tw"},"directories":{},"maintainers":[{"name":"bryant08","email":"chi10211201@cycu.org.tw"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.0.1-alpha.3_1780293795066_0.7895605775250989"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-01T06:03:14.872Z","0.0.1-alpha.3":"2026-06-01T06:03:15.254Z","modified":"2026-06-01T06:03:15.495Z"},"maintainers":[{"name":"bryant08","email":"chi10211201@cycu.org.tw"}],"description":"TypeScript SDK for Agent Assembly","homepage":"https://github.com/AI-agent-assembly/node-sdk#readme","keywords":["agent-assembly","sdk","typescript","nodejs"],"repository":{"type":"git","url":"git+https://github.com/AI-agent-assembly/node-sdk.git"},"bugs":{"url":"https://github.com/AI-agent-assembly/node-sdk/issues"},"license":"Apache-2.0","readme":"# @agent-assembly/sdk\n\n[![npm version](https://img.shields.io/npm/v/@agent-assembly/sdk.svg)](https://www.npmjs.com/package/@agent-assembly/sdk)\n[![CI](https://github.com/AI-agent-assembly/node-sdk/actions/workflows/test-matrix.yml/badge.svg?branch=master)](https://github.com/AI-agent-assembly/node-sdk/actions/workflows/test-matrix.yml)\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=AI-agent-assembly_node-sdk&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=AI-agent-assembly_node-sdk)\n[![codecov](https://codecov.io/gh/AI-agent-assembly/node-sdk/branch/master/graph/badge.svg)](https://codecov.io/gh/AI-agent-assembly/node-sdk)\n\nTypeScript/Node.js SDK for Agent Assembly, licensed under Apache 2.0.\n\n## Prerequisites\n\nBefore installing or contributing, ensure your environment has:\n\n- **Node.js** ≥ 18.18.0 (LTS). The active LTS lines (18, 20, 22, 24) are exercised in CI.\n- **pnpm** ≥ 10. The repository enforces pnpm via `engines` and ships a `pnpm-lock.yaml`.\n- **Rust toolchain** (only required when rebuilding the native `aa-ffi-node` binding from\n  source — most consumers receive a prebuilt platform binary via `optionalDependencies`).\n\n## Installation\n\n```bash\npnpm add @agent-assembly/sdk\n# or\nnpm install @agent-assembly/sdk\n# or\nyarn add @agent-assembly/sdk\n```\n\nThe SDK ships dual ESM/CJS entries and selects a prebuilt native binding for your platform\nduring `postinstall`. No additional build step is required for typical consumers.\n\n## Quickstart\n\n### ESM (`import`)\n\n```ts\nimport { initAssembly, withAssembly } from \"@agent-assembly/sdk\";\nimport { ChatOpenAI } from \"@langchain/openai\";\n\nconst ctx = await initAssembly({ gatewayUrl: \"http://localhost:8080\", agentId: \"demo\" });\nconst governedTools = withAssembly(myTools, { context: ctx });\nconst model = new ChatOpenAI({ model: \"gpt-4o-mini\" }).bindTools(governedTools);\n```\n\n### CJS (`require`)\n\n```js\nconst { initAssembly, withAssembly } = require(\"@agent-assembly/sdk\");\nconst { ChatOpenAI } = require(\"@langchain/openai\");\n\nconst ctx = await initAssembly({ gatewayUrl: \"http://localhost:8080\", agentId: \"demo\" });\nconst governedTools = withAssembly(myTools, { context: ctx });\nconst model = new ChatOpenAI({ model: \"gpt-4o-mini\" }).bindTools(governedTools);\n```\n\nBoth entrypoints resolve to the same governance pipeline; the package's `exports` field\nselects ESM or CJS automatically based on how the consumer imports it.\n\n`initAssembly()` registers the LangChain callback handler and the AdapterRegistry, so any\ntool wrapped by `withAssembly()` is checked against gateway policy before invocation.\n\n## Supported Node.js versions\n\nThe SDK is tested against every active Node.js LTS line on every supported operating\nsystem. The matrix is enforced by `.github/workflows/test-matrix.yml`:\n\n| Node.js | Linux (ubuntu-latest) | macOS (macos-latest) | Windows (windows-latest) |\n| ------- | --------------------- | -------------------- | ------------------------ |\n| 18      | ✅                    | ✅                   | ✅                       |\n| 20      | ✅                    | ✅                   | ✅                       |\n| 22      | ✅                    | ✅                   | ✅                       |\n| 24      | ✅                    | ✅                   | ✅                       |\n\nOlder Node.js lines (≤ 16) are unsupported because the napi-rs ABI used by the native\nbinding requires Node 18.18 or newer.\n\n## Goal\n\nProvide a thin wrapper around the Agent Assembly Rust runtime through:\n\n- gRPC sidecar client (default)\n- native in-process binding (napi-rs)\n\nThe primary entrypoint is `initAssembly()`, which prepares runtime governance and\nregisters framework hooks for supported tool ecosystems.\n\n## Public Entrypoints\n\n- `initAssembly(config)`\n- `withAssembly(tools, options)`\n\n## Policy Matching Constraint\n\nVercel AI SDK tools do not expose a `.name` field. Governance policies must match\nby tool description content (or tool map key in wrapper context), not by strict\nframework-level tool name.\n\n## LangChain Blocking Model\n\nLangChain callback `handleToolStart` cannot preempt execution by return value, so\nthis SDK applies a two-layer model:\n\n- callback layer (`AssemblyCallbackHandler`) tracks deferred denials and redacts at `handleToolEnd`\n- wrapper layer (`wrapToolWithAssembly`) enforces true pre-execution deny/pending checks\n\n`initAssembly()` auto-registers the callback handler and auto-wraps configured\nLangChain tools.\n\n## Current Architecture Layout\n\n```text\nsrc/\n  index.ts\n  core/\n    init-assembly.ts\n  adapters/\n    adapter.ts\n    adapter-registry.ts\n    langchain/\n      assembly-callback-handler.ts\n      wrap-tool-with-assembly.ts\n  gateway/\n    client.ts\n  wrappers/\n    with-assembly.ts\n  errors/\n    policy-violation-error.ts\n  types/\n    assembly-mode.ts\n    assembly-config.ts\n    assembly-context.ts\n    gateway-governance.ts\n    langchain-adapter.ts\n    tool-map.ts\ntests/\n  architecture/\n.github/workflows/\n```\n\n## Native napi-rs Binding (AAASM-60)\n\nThe `aa-ffi-node` Rust crate is located at `native/aa-ffi-node`.\n\nBuild commands:\n\n- `pnpm native:build` (debug/local)\n- `pnpm native:build:release` (release + platform artifact)\n- `pnpm native:check-types` (strict check for generated napi `.d.ts`)\n\nNative integration acceptance test:\n\n- `AA_NATIVE_TEST=1 pnpm vitest run tests/native-napi-integration.test.ts`\n\nThe `build-addon` GitHub workflow produces prebuilt `index.node` artifacts\nfor Node 18/20/22 on Linux/macOS/Windows.\n\n## Packaging Layout (AAASM-61)\n\nThe package now publishes dual module outputs with explicit conditional exports:\n\n- ESM entry: `./dist/esm/index.js`\n- CJS entry: `./dist/cjs/index.js`\n- Type declarations: `./dist/types/index.d.ts`\n\nPlatform-native binaries are declared via `optionalDependencies` and selected\nduring `postinstall` based on `process.platform` and `process.arch`.\n\nPackage verification checks include:\n\n- ESM and CJS entry smoke tests\n- export `types` mapping assertion\n- `npm pack` content and package size guard tests\n\n## Documentation\n\nFull guides, architecture deep-dives, and the complete API reference are published at:\n\n**https://ai-agent-assembly.github.io/node-sdk/**\n\nThe site is built from the `docs/` (content) and `website/` (Docusaurus app) directories\nand is re-published on every push to `master` via the `publish-docs.yml` workflow.\n","readmeFilename":"README.md","_rev":"1-d81e1850c923e6fe3ee449fa1d27180d"}