@agent-assembly/sdk 0.0.1-alpha.8 → 0.0.1-alpha.9

package/README.md

@@ -3,6 +3,9 @@
 [![CI](https://github.com/ai-agent-assembly/node-sdk/actions/workflows/test-matrix.yml/badge.svg?branch=master&logo=githubactions)](https://github.com/ai-agent-assembly/node-sdk/actions/workflows/test-matrix.yml)
 [![Docs](https://github.com/ai-agent-assembly/node-sdk/actions/workflows/publish-docs.yml/badge.svg?branch=master&logo=githubactions)](https://github.com/ai-agent-assembly/node-sdk/actions/workflows/publish-docs.yml)
 [![npm version](https://img.shields.io/npm/v/@agent-assembly/sdk/alpha?logo=npm)](https://www.npmjs.com/package/@agent-assembly/sdk/v/alpha)
+[![TypeScript types](https://img.shields.io/npm/types/@agent-assembly/sdk?logo=typescript)](https://www.npmjs.com/package/@agent-assembly/sdk)
+[![Bundle size](https://img.shields.io/bundlephobia/min/@agent-assembly/sdk?logo=webpack&label=min)](https://bundlephobia.com/package/@agent-assembly/sdk)
+[![Downloads](https://img.shields.io/npm/dm/@agent-assembly/sdk?logo=npm&label=downloads%2Fmo)](https://www.npmjs.com/package/@agent-assembly/sdk)
 [![Coverage](https://img.shields.io/codecov/c/github/ai-agent-assembly/node-sdk?logo=codecov)](https://codecov.io/gh/ai-agent-assembly/node-sdk)
 [![Quality Gate](https://img.shields.io/sonar/quality_gate/AI-agent-assembly_node-sdk?server=https%3A%2F%2Fsonarcloud.io&logo=sonarcloud)](https://sonarcloud.io/summary/new_code?id=AI-agent-assembly_node-sdk)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue?logo=apache)](./LICENSE)
@@ -21,8 +24,9 @@ TypeScript/Node.js SDK for Agent Assembly, licensed under Apache 2.0.
 > Production deployments should track the first `0.1.0` release.
 
 ```bash
-pnpm add @agent-assembly/sdk@alpha   # latest alpha
-pnpm add @agent-assembly/sdk@0.0.1-alpha.3   # pin exact
+pnpm add @agent-assembly/sdk@alpha             # latest alpha (tracks @alpha dist-tag)
+pnpm add @agent-assembly/sdk@<X.Y.Z-alpha.N>   # pin exact — replace the placeholder with the
+                                               # desired version from npmjs.com/package/@agent-assembly/sdk
 ```
 
 ## Prerequisites
@@ -134,14 +138,51 @@ call is checked against policy before it runs.
 | ------ | ------- |
 | `initAssembly(config)` | Set up governance and auto-wire detected frameworks. The main entrypoint. |
 | `withAssembly(tools, options)` | Lower-level wrapper to govern a tool map when you manage the gateway client yourself. |
+| `createNoopGatewayClient(mode)` | Build an allow-all `GatewayClient` for offline demos and tests, or as a base to wrap. |
+| `PolicyViolationError` | Thrown by a governed tool when the gateway client denies the call. |
 | `currentAgentId()`, `runWithAgentId()` | Read and set the active agent id in the async-context lineage store. |
 | `encodeAuditEvent()` / `decodeAuditEvent()` (and the call-stack codecs) | Encode and decode audit events to and from their wire shape. |
 | `findAasmBinary()`, `INSTALL_HINT` | Locate the bundled `aasm` runtime binary and the install hint shown when it is missing. |
 | `ENFORCEMENT_MODES` | The allowed `enforcementMode` values. |
 
 Type-only exports (`AssemblyConfig`, `AssemblyContext`, `AssemblyMode`, `EnforcementMode`,
-`ToolMap`, and friends) are documented in the
-[API reference](https://ai-agent-assembly.github.io/node-sdk/api-reference).
+`ToolMap`, `GatewayClient`, the `Gateway*` governance types, and friends) are documented in
+the [API reference](https://ai-agent-assembly.github.io/node-sdk/api-reference).
+
+## Governing tools offline
+
+`withAssembly(tools, options)` needs a `GatewayClient`. For offline demos, tests, or custom
+in-process policies you can build one yourself — no running gateway required:
+
+```ts
+import {
+  createNoopGatewayClient,
+  withAssembly,
+  type GatewayClient
+} from "@agent-assembly/sdk";
+
+// Allow-all client — handy for offline smoke tests:
+withAssembly(
+  { search: { description: "Search", execute: async (q: string) => `result:${q}` } },
+  { gatewayClient: createNoopGatewayClient("sdk-only") }
+);
+
+// Or enforce your own in-process policy by implementing the GatewayClient interface:
+const policyClient: GatewayClient = {
+  mode: "sdk-only",
+  start: async () => undefined,
+  close: async () => undefined,
+  check: async (request) =>
+    request.toolName === "delete_file"
+      ? { denied: true, reason: "blocked by local policy" }
+      : { denied: false },
+  waitForApproval: async () => ({ denied: false }),
+  record: async () => undefined,
+  recordResult: async () => undefined,
+  scanPrompts: async () => undefined
+};
+// A governed tool throws `PolicyViolationError` when `check` denies it.
+```
 
 ## How LangChain tools are blocked
 
@@ -248,6 +289,7 @@ across all SDKs.
 | [Documentation site](https://ai-agent-assembly.github.io/agent-assembly-docs/) | Canonical, cross-repo documentation for the whole platform.                                                   |
 | [python-sdk](https://github.com/ai-agent-assembly/python-sdk)                  | Sibling SDK for Python.                                                                                       |
 | [go-sdk](https://github.com/ai-agent-assembly/go-sdk)                          | Sibling SDK for Go.                                                                                           |
+| [agent-assembly-examples](https://github.com/ai-agent-assembly/agent-assembly-examples) | Runnable examples — learn by running small, framework-specific Node.js/TypeScript (and Python/Go) samples for policy enforcement, approvals, audit, trace, and runtime workflows. |
 | [Release notes](https://github.com/ai-agent-assembly/node-sdk/releases)        | Per-version changelog for this package.                                                                       |
 | [Organization profile](https://github.com/ai-agent-assembly)                   | Index of every Agent Assembly repository and its status.                                                      |
 

package/dist/cjs/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.findAasmBinary = exports.INSTALL_HINT = exports.runWithAgentId = exports.currentAgentId = exports.encodeCallStackNode = exports.encodeAuditEvent = exports.decodeCallStackNode = exports.decodeAuditEvent = exports.ENFORCEMENT_MODES = exports.withAssembly = exports.initAssembly = void 0;
+exports.PolicyViolationError = exports.createNoopGatewayClient = exports.findAasmBinary = exports.INSTALL_HINT = exports.runWithAgentId = exports.currentAgentId = exports.encodeCallStackNode = exports.encodeAuditEvent = exports.decodeCallStackNode = exports.decodeAuditEvent = exports.ENFORCEMENT_MODES = exports.withAssembly = exports.initAssembly = void 0;
 var init_assembly_js_1 = require("./core/init-assembly.js");
 Object.defineProperty(exports, "initAssembly", { enumerable: true, get: function () { return init_assembly_js_1.initAssembly; } });
 var index_js_1 = require("./wrappers/index.js");
@@ -23,3 +23,7 @@ Object.defineProperty(exports, "runWithAgentId", { enumerable: true, get: functi
 var runtime_js_1 = require("./runtime.js");
 Object.defineProperty(exports, "INSTALL_HINT", { enumerable: true, get: function () { return runtime_js_1.INSTALL_HINT; } });
 Object.defineProperty(exports, "findAasmBinary", { enumerable: true, get: function () { return runtime_js_1.findAasmBinary; } });
+var index_js_5 = require("./gateway/index.js");
+Object.defineProperty(exports, "createNoopGatewayClient", { enumerable: true, get: function () { return index_js_5.createNoopGatewayClient; } });
+var index_js_6 = require("./errors/index.js");
+Object.defineProperty(exports, "PolicyViolationError", { enumerable: true, get: function () { return index_js_6.PolicyViolationError; } });

package/dist/esm/index.js

@@ -9,4 +9,6 @@ export { currentAgentId, runWithAgentId } from "./lineage/index.js";
 // `@agent-assembly/sdk/runtime` subpath export to avoid colliding with
 // the gateway-based `initAssembly` re-exported above.
 export { INSTALL_HINT, findAasmBinary } from "./runtime.js";
+export { createNoopGatewayClient } from "./gateway/index.js";
+export { PolicyViolationError } from "./errors/index.js";
 //# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAYnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,EACpB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpE,uEAAuE;AACvE,wEAAwE;AACxE,mEAAmE;AACnE,uEAAuE;AACvE,sDAAsD;AACtD,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAYnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,EACpB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpE,uEAAuE;AACvE,wEAAwE;AACxE,mEAAmE;AACnE,uEAAuE;AACvE,sDAAsD;AACtD,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAU5D,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/types/index.d.ts

@@ -7,4 +7,8 @@ export { decodeAuditEvent, decodeCallStackNode, encodeAuditEvent, encodeCallStac
 export type { WireAuditEvent, WireCallStackNode } from "./audit/index.js";
 export { currentAgentId, runWithAgentId } from "./lineage/index.js";
 export { INSTALL_HINT, findAasmBinary } from "./runtime.js";
+export type { GatewayClient } from "./gateway/index.js";
+export type { GatewayApprovalResult, GatewayCheckRequest, GatewayDecision, GatewayPromptScan, GatewayRecordEvent, GatewayResultRecord } from "./types/index.js";
+export { createNoopGatewayClient } from "./gateway/index.js";
+export { PolicyViolationError } from "./errors/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,YAAY,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,YAAY,EACV,cAAc,EACd,eAAe,EACf,YAAY,EACZ,UAAU,EACV,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,OAAO,EACR,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,EACpB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAMpE,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,YAAY,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,YAAY,EACV,cAAc,EACd,eAAe,EACf,YAAY,EACZ,UAAU,EACV,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,OAAO,EACR,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,EACpB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAMpE,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC5D,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,YAAY,EACV,qBAAqB,EACrB,mBAAmB,EACnB,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-assembly/sdk",
-  "version": "0.0.1-alpha.8",
+  "version": "0.0.1-alpha.9",
   "description": "TypeScript SDK for Agent Assembly",
   "license": "Apache-2.0",
   "type": "module",
@@ -59,10 +59,10 @@
     "nodejs"
   ],
   "optionalDependencies": {
-    "@agent-assembly/runtime-darwin-arm64": "0.0.1-alpha.8",
-    "@agent-assembly/runtime-darwin-x64": "0.0.1-alpha.8",
-    "@agent-assembly/runtime-linux-arm64": "0.0.1-alpha.8",
-    "@agent-assembly/runtime-linux-x64": "0.0.1-alpha.8"
+    "@agent-assembly/runtime-darwin-arm64": "0.0.1-alpha.9",
+    "@agent-assembly/runtime-darwin-x64": "0.0.1-alpha.9",
+    "@agent-assembly/runtime-linux-arm64": "0.0.1-alpha.9",
+    "@agent-assembly/runtime-linux-x64": "0.0.1-alpha.9"
   },
   "files": [
     "dist/",