@agent-assembly/sdk 0.0.1-beta.3 → 0.0.1-beta.5

package/README.md

@@ -122,6 +122,20 @@ system. The matrix is enforced by `.github/workflows/test-matrix.yml`:
 Older Node.js lines (≤ 16) are unsupported because the napi-rs ABI used by the native
 binding requires Node 18.18 or newer.
 
+## Framework compatibility
+
+`initAssembly()` auto-detects and governs five optional framework integrations
+(LangChain.js, LangGraph.js, Vercel AI SDK, Mastra, OpenAI Agents). The full table —
+each framework's optional peer dependency, supported version range, and current status
+(including the [known Vercel AI SDK caveat](https://lightning-dust-mite.atlassian.net/browse/AAASM-3532)) —
+is the **authoritative** reference and lives on the docs site:
+[Framework compatibility](https://ai-agent-assembly.github.io/node-sdk/compatibility-versioning/compatibility).
+
+For the product-wide, cross-SDK index/hub that links every language SDK's matrix, see the
+core documentation:
+[Framework compatibility index](https://ai-agent-assembly.github.io/agent-assembly/stable/reference/framework-compatibility.html)
+(the `/stable/` link goes live at GA).
+
 ## How it works
 
 The SDK is a thin TypeScript wrapper around the Agent Assembly Rust runtime. It reaches
@@ -136,16 +150,16 @@ call is checked against policy before it runs.
 
 ## What the package exports
 
-| Export | Purpose |
-| ------ | ------- |
-| `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. |
+| Export                                                                  | Purpose                                                                                 |
+| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| `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`, `GatewayClient`, the `Gateway*` governance types, and friends) are documented in
@@ -157,11 +171,7 @@ the [API reference](https://ai-agent-assembly.github.io/node-sdk/api-reference).
 in-process policies you can build one yourself — no running gateway required:
 
 ```ts
-import {
-  createNoopGatewayClient,
-  withAssembly,
-  type GatewayClient
-} from "@agent-assembly/sdk";
+import { createNoopGatewayClient, withAssembly, type GatewayClient } from "@agent-assembly/sdk";
 
 // Allow-all client — handy for offline smoke tests:
 withAssembly(
@@ -285,15 +295,15 @@ and is re-published on every push to `master` via the `publish-docs.yml` workflo
 decisions it enforces are made by the core Rust runtime; the protocol it speaks is shared
 across all SDKs.
 
-| Project                                                                        | What it is                                                                                                    |
-| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
-| [agent-assembly](https://github.com/ai-agent-assembly/agent-assembly)          | Core Rust runtime — gateway, policy engine, proxy, eBPF, CLI (`aasm`). The protocol specification lives here. |
-| [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.                                                                                           |
+| Project                                                                                 | What it is                                                                                                                                                                        |
+| --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [agent-assembly](https://github.com/ai-agent-assembly/agent-assembly)                   | Core Rust runtime — gateway, policy engine, proxy, eBPF, CLI (`aasm`). The protocol specification lives here.                                                                     |
+| [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.                                                      |
+| [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.                                                                                                                          |
 
 ## Support & security
 
@@ -304,5 +314,8 @@ across all SDKs.
   via the repository's
   [security advisories](https://github.com/ai-agent-assembly/node-sdk/security/advisories)
   page so a fix can be coordinated before disclosure.
+- **Canonical package names + verifying your install** — see [SECURITY.md](./SECURITY.md)
+  for the authoritative `@agent-assembly/*` package list (to spot typosquats) and how to
+  verify npm provenance (`npm audit signatures`) and the per-release CycloneDX SBOM.
 - **Contributing** — see [CONTRIBUTING.md](./CONTRIBUTING.md) for environment setup, the
   adapter-authoring guide, and the test/commit conventions.

package/dist/cjs/core/gateway-resolver.js

@@ -33,7 +33,8 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.__testing = exports.AASM_AUTO_START_ARGV = exports.LEGACY_ENV_API_KEY = exports.LEGACY_ENV_GATEWAY_URL = exports.ENV_API_KEY = exports.ENV_GATEWAY_URL = exports.DEFAULT_CONFIG_FILE_PATH = exports.DEFAULT_AUTO_START_TIMEOUT_MS = exports.DEFAULT_PROBE_TIMEOUT_MS = exports.DEFAULT_HEALTHZ_PATH = exports.DEFAULT_GATEWAY_URL = void 0;
+exports.__testing = exports.AASM_AUTO_START_ARGV = exports.LEGACY_ENV_API_KEY = exports.LEGACY_ENV_GATEWAY_URL = exports.ENV_AUTO_START = exports.ENV_API_KEY = exports.ENV_GATEWAY_URL = exports.DEFAULT_CONFIG_FILE_PATH = exports.DEFAULT_AUTO_START_TIMEOUT_MS = exports.DEFAULT_PROBE_TIMEOUT_MS = exports.DEFAULT_HEALTHZ_PATH = exports.DEFAULT_GATEWAY_URL = void 0;
+exports.assertAllowedAasmPath = assertAllowedAasmPath;
 exports.probeHealthz = probeHealthz;
 exports.waitForHealthz = waitForHealthz;
 exports.loadConfigFile = loadConfigFile;
@@ -61,7 +62,9 @@ const index_js_1 = require("../errors/index.js");
  *      as deprecated aliases (a one-time warning is logged when a legacy name
  *      supplies the value)
  *   3. Config file (~/.aasm/config.yaml, optional js-yaml soft dep)
- *   4. Local default: probe http://localhost:7391, auto-start if absent
+ *   4. Local default: probe http://localhost:7391; when absent, auto-start the
+ *      local `aasm` gateway ONLY if `AA_AUTO_START` is opted in and the binary
+ *      resolves to an allow-listed install dir — otherwise raise an error.
  */
 exports.DEFAULT_GATEWAY_URL = "http://localhost:7391";
 exports.DEFAULT_HEALTHZ_PATH = "/healthz";
@@ -70,6 +73,56 @@ exports.DEFAULT_AUTO_START_TIMEOUT_MS = 5000;
 exports.DEFAULT_CONFIG_FILE_PATH = "~/.aasm/config.yaml";
 exports.ENV_GATEWAY_URL = "AA_GATEWAY_URL";
 exports.ENV_API_KEY = "AA_API_KEY";
+/**
+ * Opt-in gate for auto-starting a local gateway. Auto-start spawns the `aasm`
+ * binary resolved from `$PATH`, so it is gated behind an explicit opt-in rather
+ * than running silently: a `$PATH` entry an attacker can write to would
+ * otherwise be executed by any process that calls `initAssembly()`. Set to
+ * `1`/`true`/`yes` to permit auto-start.
+ */
+exports.ENV_AUTO_START = "AA_AUTO_START";
+/** Truthy values that enable {@link ENV_AUTO_START}. */
+function autoStartEnabled() {
+    const raw = process.env[exports.ENV_AUTO_START]?.trim().toLowerCase();
+    return raw === "1" || raw === "true" || raw === "yes";
+}
+/**
+ * Directories an auto-started `aasm` binary is permitted to live in. The
+ * resolved path must be absolute and sit inside one of these install roots,
+ * which blocks a `$PATH`-injected `./aasm` (cwd) or a binary planted in an
+ * arbitrary writable directory from being spawned. Mirrors the documented
+ * install locations (Homebrew, system, user-local, cargo).
+ */
+function allowedInstallDirs() {
+    const home = (0, node_os_1.homedir)();
+    return [
+        "/usr/local/bin",
+        "/usr/bin",
+        "/opt/homebrew/bin",
+        (0, node_path_1.join)(home, ".local", "bin"),
+        (0, node_path_1.join)(home, ".cargo", "bin"),
+        "/usr/local/cargo/bin",
+    ];
+}
+/**
+ * Throw {@link ConfigurationError} unless `aasmPath` is an absolute path inside
+ * an allow-listed install directory (see {@link allowedInstallDirs}). This is
+ * the integrity gate for the auto-start subprocess — without it the SDK would
+ * execute whatever `aasm` happened to be first on `$PATH`.
+ */
+function assertAllowedAasmPath(aasmPath) {
+    if (!(0, node_path_1.isAbsolute)(aasmPath)) {
+        throw new index_js_1.ConfigurationError(`Refusing to auto-start a non-absolute 'aasm' path: ${aasmPath}. ` +
+            `Set ${exports.ENV_GATEWAY_URL} to an already-running gateway instead.`);
+    }
+    const resolved = (0, node_path_1.resolve)(aasmPath);
+    const ok = allowedInstallDirs().some((dir) => resolved.startsWith(dir + "/"));
+    if (!ok) {
+        throw new index_js_1.ConfigurationError(`Refusing to auto-start 'aasm' from an untrusted location: ${resolved}. ` +
+            `Install it under one of: ${allowedInstallDirs().join(", ")}, ` +
+            `or set ${exports.ENV_GATEWAY_URL} to an already-running gateway.`);
+    }
+}
 /**
  * Deprecated environment-variable names, kept as backwards-compatible aliases.
  *
@@ -154,7 +207,11 @@ async function waitForHealthz(baseUrl, timeoutMs = exports.DEFAULT_AUTO_START_TI
     return probeHealthz(baseUrl);
 }
 function expandHome(p) {
-    return p.startsWith("~") ? (0, node_path_1.resolve)((0, node_os_1.homedir)(), p.slice(p.startsWith("~/") ? 2 : 1)) : p;
+    if (!p.startsWith("~")) {
+        return p;
+    }
+    const prefixLength = p.startsWith("~/") ? 2 : 1;
+    return (0, node_path_1.resolve)((0, node_os_1.homedir)(), p.slice(prefixLength));
 }
 /**
  * Load ``~/.aasm/config.yaml`` if present.
@@ -246,6 +303,11 @@ async function autoStartGateway(baseUrl = exports.DEFAULT_GATEWAY_URL, timeoutMs
         throw new index_js_1.ConfigurationError(`No gateway found at ${baseUrl} and 'aasm' is not on PATH. ` +
             "Install it with: npm install -g @agent-assembly/cli (or pnpm add -g)");
     }
+    // Integrity gate: only spawn an absolute path from an allow-listed install
+    // dir, and surface the resolved path so the operator can see exactly which
+    // binary the SDK is about to execute.
+    assertAllowedAasmPath(aasmPath);
+    console.info(`[agent-assembly] auto-starting gateway from ${aasmPath}`);
     _seams.spawnAasm(aasmPath);
     if (!(await waitForHealthz(baseUrl, timeoutMs))) {
         throw new index_js_1.GatewayError(`Auto-started gateway at ${baseUrl} did not become ready ` +
@@ -276,6 +338,14 @@ async function resolveGatewayUrl(explicit) {
     if (await _seams.probeHealthz(exports.DEFAULT_GATEWAY_URL)) {
         return exports.DEFAULT_GATEWAY_URL;
     }
+    // Auto-start is opt-in: spawning the local `aasm` binary is a privileged
+    // side effect, so a missing gateway is a hard error unless the operator has
+    // explicitly enabled AA_AUTO_START.
+    if (!autoStartEnabled()) {
+        throw new index_js_1.ConfigurationError(`No gateway found at ${exports.DEFAULT_GATEWAY_URL}. Start one with 'aasm start ` +
+            `--mode local', set ${exports.ENV_GATEWAY_URL} to a running gateway, or set ` +
+            `${exports.ENV_AUTO_START}=1 to allow the SDK to auto-start a local gateway.`);
+    }
     await _seams.autoStartGateway(exports.DEFAULT_GATEWAY_URL);
     return exports.DEFAULT_GATEWAY_URL;
 }

package/dist/cjs/core/init-assembly.js

@@ -42,6 +42,7 @@ exports.initAssembly = initAssembly;
 const node_module_1 = require("node:module");
 const client_js_1 = require("../gateway/client.js");
 const client_js_2 = require("../native/client.js");
+const index_js_1 = require("../errors/index.js");
 const enforcement_mode_js_1 = require("../types/enforcement-mode.js");
 const ai_sdk_detection_js_1 = require("../hooks/ai-sdk-detection.js");
 const ai_sdk_js_1 = require("../hooks/ai-sdk.js");
@@ -51,8 +52,9 @@ const mastra_detection_js_1 = require("../hooks/mastra-detection.js");
 const mastra_js_1 = require("../hooks/mastra.js");
 const openai_agents_detection_js_1 = require("../hooks/openai-agents-detection.js");
 const openai_agents_js_1 = require("../hooks/openai-agents.js");
-const index_js_1 = require("../lineage/index.js");
+const index_js_2 = require("../lineage/index.js");
 const gateway_resolver_js_1 = require("./gateway-resolver.js");
+const redact_js_1 = require("./redact.js");
 const requireFromCwd = (0, node_module_1.createRequire)(`${process.cwd()}/`);
 /** Env-var fallback for ``gatewayUrl`` read at ``initAssembly`` entry. */
 exports.ENV_GATEWAY_URL = "AA_GATEWAY_URL";
@@ -76,14 +78,73 @@ function buildRegistrationEvent(config) {
         event.enforcement_mode = config.enforcementMode;
     return event;
 }
-function createClient(config) {
+/**
+ * Build the {@link RegisterOptions} for the native `register` gRPC call
+ * (AAASM-3400) from the resolved config and the detected frameworks. `name`
+ * falls back to `agentId`; `framework` is the first detected framework (or
+ * `"none"` when running without an adapter); `gatewayEndpoint` is set only when
+ * a gateway URL was resolved so the native default endpoint resolution is
+ * preserved when it was not. `teamId` / `parentAgentId` carry the agent's
+ * team-budget scoping and topology lineage to the gateway (AAASM-3415); each is
+ * set only when present so an unset field stays absent.
+ */
+function buildRegisterOptions(config, frameworks) {
+    const agentId = config.agentId ?? "";
+    return {
+        agentId,
+        name: config.name ?? agentId,
+        framework: frameworks[0] ?? "none",
+        ...(config.gatewayUrl ? { gatewayEndpoint: config.gatewayUrl } : {}),
+        ...(config.teamId ? { teamId: config.teamId } : {}),
+        ...(config.parentAgentId ? { parentAgentId: config.parentAgentId } : {})
+    };
+}
+/**
+ * The only built-in {@link AssemblyMode} for which {@link createClient}
+ * constructs a gateway client whose `check()` consults a real authoritative
+ * verdict (the native `queryPolicy` against a reachable `aa-runtime`). Every
+ * other mode falls back to the allow-all no-op client.
+ */
+const CHECK_CAPABLE_MODE = "napi-inprocess";
+function createClient(config, nativeClientOverride) {
     const mode = config.mode ?? "auto";
     if (config.gatewayClient) {
         return config.gatewayClient;
     }
+    // AAASM-3105 (fail closed): the no-op gateway client's `check()` is allow-all,
+    // so registering under live `"enforce"` while routing through it would let a
+    // policy-denied action proceed unchecked — a silent fail-open. When the caller
+    // explicitly asks for `"enforce"` but supplies no check-capable mode (and no
+    // own `gatewayClient`), refuse loudly instead of pretending to enforce. An
+    // omitted `enforcementMode` keeps the pre-feature behavior (server-side
+    // default), and `"observe"` / `"disabled"` intentionally let actions through.
+    if (config.enforcementMode === "enforce" && mode !== CHECK_CAPABLE_MODE) {
+        throw new index_js_1.ConfigurationError(`enforcementMode "enforce" requires a check-capable client, but mode "${mode}" ` +
+            `routes through the allow-all no-op gateway client, which cannot block a ` +
+            `denied action. Use mode "${CHECK_CAPABLE_MODE}", supply your own ` +
+            `gatewayClient, or set enforcementMode to "observe"/"disabled".`);
+    }
     // HTTP routes use controlPlaneUrl when set, otherwise fall back to the
     // resolved gatewayUrl so pre-feature callers keep their existing base URL.
     const httpBaseUrl = config.controlPlaneUrl ?? config.gatewayUrl;
+    // AAASM-3050: in napi-inprocess mode, route `check()` through the native
+    // runtime so a reachable aa-runtime's DENY actually blocks a tool. The
+    // native primitive fails open when the runtime is absent or slow, and the
+    // gateway client swallows local faults, so this never blocks without a
+    // runtime — preserving the pre-feature fail-open behavior.
+    if (mode === "napi-inprocess") {
+        // Reuse the caller-supplied native client when present so the registered
+        // session (the one `register()` stored the gateway token on) is the same
+        // session `queryPolicy` runs against. Standalone callers (and the routing
+        // tests) get a freshly-built client instead.
+        const nativeClient = nativeClientOverride ??
+            (0, client_js_2.createNativeClient)({
+                gateway: config.gatewayUrl ?? "",
+                apiKey: config.apiKey ?? "",
+                mode: "napi-inprocess"
+            });
+        return (0, client_js_1.createNativeGatewayClient)(mode, nativeClient, config.agentId, httpBaseUrl);
+    }
     return (0, client_js_1.createNoopGatewayClient)(mode, httpBaseUrl);
 }
 function isPackageInstalled(packageName) {
@@ -177,7 +238,7 @@ async function patchDetectedVercelAiSdk(client, frameworks, agentId) {
     }
     return (0, ai_sdk_js_1.patchVercelAiSdk)({
         gatewayClient: client,
-        ...(agentId !== undefined ? { agentId } : {})
+        ...(agentId === undefined ? {} : { agentId })
     });
 }
 async function patchDetectedLangGraph(frameworks, agentId) {
@@ -198,7 +259,13 @@ async function patchDetectedOpenAIAgents(client, frameworks) {
     }
     return (0, openai_agents_js_1.patchOpenAIAgents)({ gatewayClient: client });
 }
-async function initAssembly(config = {}) {
+/**
+ * Validate caller-supplied `initAssembly` config, throwing `RangeError` on the
+ * two fields that can arrive malformed from non-TS callers (plain JS, JSON
+ * config, dynamic input). Extracted to keep `initAssembly` below the cognitive
+ * complexity threshold; behaviour-preserving.
+ */
+function validateConfig(config) {
     if (config.delegationReason !== undefined && config.delegationReason.length > 256) {
         throw new RangeError("delegationReason must be <= 256 characters");
     }
@@ -208,9 +275,51 @@ async function initAssembly(config = {}) {
     if (config.enforcementMode !== undefined && !enforcement_mode_js_1.ENFORCEMENT_MODES.includes(config.enforcementMode)) {
         throw new RangeError(`enforcementMode must be one of: ${enforcement_mode_js_1.ENFORCEMENT_MODES.join(", ")} (got: ${String(config.enforcementMode)})`);
     }
+}
+/**
+ * Run every framework detect-and-patch path for the resolved config. Extracted
+ * from `initAssembly` to keep its cognitive complexity below threshold;
+ * behaviour-preserving (same calls, same order).
+ */
+async function applyFrameworkPatches(config, client, frameworks) {
+    const langChainHandler = await registerLangChainHandler(config, client, frameworks);
+    const wrappedLangChainTools = await wrapLangChainTools(config, client, frameworks);
+    const vercelAiSdkPatched = await patchDetectedVercelAiSdk(client, frameworks, config.agentId);
+    const openAIAgentsPatched = await patchDetectedOpenAIAgents(client, frameworks);
+    const langGraphPatched = await patchDetectedLangGraph(frameworks, config.agentId);
+    const mastraPatched = await patchDetectedMastra(frameworks, config.agentId);
+    return {
+        langChainHandler,
+        wrappedLangChainTools,
+        vercelAiSdkPatched,
+        openAIAgentsPatched,
+        langGraphPatched,
+        mastraPatched
+    };
+}
+/**
+ * Build the deduped list of active adapter ids from the registered adapters plus
+ * whichever framework patches actually took effect. Extracted from
+ * `initAssembly` to keep its cognitive complexity below threshold.
+ */
+function buildActiveAdapters(adapters, patches) {
+    return [
+        ...new Set([
+            ...adapters.map((adapter) => adapter.id),
+            ...(patches.langChainHandler ? ["langchain-js"] : []),
+            ...(patches.wrappedLangChainTools.length > 0 ? ["langchain-js"] : []),
+            ...(patches.vercelAiSdkPatched ? ["vercel-ai-sdk"] : []),
+            ...(patches.openAIAgentsPatched ? ["openai-agents"] : []),
+            ...(patches.langGraphPatched ? ["langgraph-js"] : []),
+            ...(patches.mastraPatched ? ["mastra"] : [])
+        ])
+    ];
+}
+async function initAssembly(config = {}) {
+    validateConfig(config);
     // Auto-populate parentAgentId from the async context store when not explicitly provided.
     // This allows child agents spawned inside framework hooks to inherit lineage automatically.
-    const resolvedParentAgentId = config.parentAgentId ?? (0, index_js_1.currentAgentId)();
+    const resolvedParentAgentId = config.parentAgentId ?? (0, index_js_2.currentAgentId)();
     // Env-var fallbacks read at entry: explicit config field > env-var > the
     // downstream resolver chain (which may itself error if required and absent).
     const gatewayUrlInput = config.gatewayUrl ?? process.env[exports.ENV_GATEWAY_URL];
@@ -221,47 +330,60 @@ async function initAssembly(config = {}) {
         ...config,
         gatewayUrl: resolvedGatewayUrl,
         apiKey: resolvedApiKey,
-        ...(controlPlaneUrlInput !== undefined ? { controlPlaneUrl: controlPlaneUrlInput } : {}),
+        ...(controlPlaneUrlInput === undefined ? {} : { controlPlaneUrl: controlPlaneUrlInput }),
         ...(resolvedParentAgentId ? { parentAgentId: resolvedParentAgentId } : {})
     };
-    const client = createClient(resolvedConfig);
     const frameworks = detectFrameworks();
-    const adapters = await registerAdapters(frameworks);
-    await startNetworkLayerIfNeeded(client, resolvedConfig);
-    // Send topology registration event through the native transport on every boot
-    // except sdk-only mode (which has no sidecar to register with).
+    // Build the native transport up front (every mode except sdk-only, which has
+    // no sidecar) so the same session backs both the gateway client's `check()`
+    // and the agent registration — the gateway token `register()` stores on the
+    // session is then attached to every subsequent `queryPolicy` request.
     let nativeClient;
     if (resolvedConfig.mode !== "sdk-only") {
         nativeClient = (0, client_js_2.createNativeClient)({
             gateway: resolvedGatewayUrl,
             apiKey: resolvedApiKey,
-            mode: resolvedConfig.mode === "napi-inprocess" ? "napi-inprocess" : "grpc-sidecar",
+            mode: resolvedConfig.mode === "napi-inprocess" ? "napi-inprocess" : "grpc-sidecar"
         });
+    }
+    const client = createClient(resolvedConfig, nativeClient);
+    const adapters = await registerAdapters(frameworks);
+    await startNetworkLayerIfNeeded(client, resolvedConfig);
+    if (nativeClient !== undefined) {
+        // AAASM-3403: register the agent over the native SDK→gateway gRPC call so
+        // the gateway issues a credential token (stored on this session) that
+        // unblocks subsequent policy queries. Advisory: a failed registration must
+        // not abort init — the agent proceeds unregistered and the proxy / eBPF
+        // layers remain authoritative.
+        try {
+            await nativeClient.register(buildRegisterOptions(resolvedConfig, frameworks));
+        }
+        catch (error) {
+            // Redact any Bearer/auth credential the error message might carry before
+            // it reaches the console — the apiKey/credentialToken must never be logged
+            // (AAASM-3645).
+            console.warn(`[agent-assembly] agent registration failed; proceeding unregistered: ${(0, redact_js_1.redactErrorMessage)(error)}`);
+        }
+        // Topology lineage metadata still flows as an audit event (parent / team /
+        // delegation), which `register` does not carry.
         nativeClient.sendEvent(buildRegistrationEvent(resolvedConfig));
     }
-    const langChainHandler = await registerLangChainHandler(resolvedConfig, client, frameworks);
-    const wrappedLangChainTools = await wrapLangChainTools(resolvedConfig, client, frameworks);
-    const vercelAiSdkPatched = await patchDetectedVercelAiSdk(client, frameworks, resolvedConfig.agentId);
-    const openAIAgentsPatched = await patchDetectedOpenAIAgents(client, frameworks);
-    const langGraphPatched = await patchDetectedLangGraph(frameworks, resolvedConfig.agentId);
-    const mastraPatched = await patchDetectedMastra(frameworks, resolvedConfig.agentId);
+    const patches = await applyFrameworkPatches(resolvedConfig, client, frameworks);
     return {
-        activeAdapters: [
-            ...new Set([
-                ...adapters.map((adapter) => adapter.id),
-                ...(langChainHandler ? ["langchain-js"] : []),
-                ...(wrappedLangChainTools.length > 0 ? ["langchain-js"] : []),
-                ...(vercelAiSdkPatched ? ["vercel-ai-sdk"] : []),
-                ...(openAIAgentsPatched ? ["openai-agents"] : []),
-                ...(langGraphPatched ? ["langgraph-js"] : []),
-                ...(mastraPatched ? ["mastra"] : [])
-            ])
-        ],
-        ...(resolvedConfig.parentAgentId !== undefined && { parentAgentId: resolvedConfig.parentAgentId }),
+        activeAdapters: buildActiveAdapters(adapters, patches),
+        ...(resolvedConfig.parentAgentId !== undefined && {
+            parentAgentId: resolvedConfig.parentAgentId
+        }),
         ...(resolvedConfig.teamId !== undefined && { teamId: resolvedConfig.teamId }),
-        ...(resolvedConfig.delegationReason !== undefined && { delegationReason: resolvedConfig.delegationReason }),
-        ...(resolvedConfig.spawnedByTool !== undefined && { spawnedByTool: resolvedConfig.spawnedByTool }),
-        ...(resolvedConfig.enforcementMode !== undefined && { enforcementMode: resolvedConfig.enforcementMode }),
+        ...(resolvedConfig.delegationReason !== undefined && {
+            delegationReason: resolvedConfig.delegationReason
+        }),
+        ...(resolvedConfig.spawnedByTool !== undefined && {
+            spawnedByTool: resolvedConfig.spawnedByTool
+        }),
+        ...(resolvedConfig.enforcementMode !== undefined && {
+            enforcementMode: resolvedConfig.enforcementMode
+        }),
         shutdown: async () => {
             for (const adapter of adapters) {
                 await adapter.shutdown?.();

package/dist/cjs/core/redact.js

@@ -0,0 +1,63 @@
+"use strict";
+/**
+ * Secret-redaction helpers for diagnostic / log output (AAASM-3645).
+ *
+ * The resolved `apiKey` and the proto `credentialToken` must never reach
+ * `console.*` or an accidental `JSON.stringify` dump. These helpers give the
+ * SDK a single, audited way to render config/diagnostics for logging with the
+ * credential fields stripped.
+ *
+ * NOTE: the generated `CheckActionRequest.toJSON()` (src/proto/generated) is
+ * wire-only — it serializes `credentialToken` for transport and must never be
+ * passed to a logger. Use {@link redactSecrets} on any object you intend to log.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REDACTED = void 0;
+exports.redactSecrets = redactSecrets;
+exports.redactErrorMessage = redactErrorMessage;
+/**
+ * Object keys (lower-cased) whose values are credentials and must never be
+ * logged. Matching is case-insensitive, so list the lower-case form only —
+ * `apiKey`, `apikey`, `API_KEY` all match `"apikey"`.
+ */
+const SECRET_KEYS = new Set([
+    "apikey",
+    "api_key",
+    "credentialtoken",
+    "credential_token",
+    "authorization",
+    "token"
+]);
+/** Placeholder substituted for any redacted credential value. */
+exports.REDACTED = "<redacted>";
+/**
+ * Return a deep copy of `value` with every credential-bearing field replaced by
+ * {@link REDACTED}, safe to pass to `console.*` / `JSON.stringify`. Matching is
+ * case-insensitive on the key name. Non-object inputs are returned unchanged.
+ */
+function redactSecrets(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => redactSecrets(item));
+    }
+    if (value !== null && typeof value === "object") {
+        const out = {};
+        for (const [key, val] of Object.entries(value)) {
+            out[key] = SECRET_KEYS.has(key.toLowerCase()) ? exports.REDACTED : redactSecrets(val);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Render an unknown error for a log message with any `Bearer <token>` / API-key
+ * substring scrubbed. Defends the registration-failure warning path: a wrapped
+ * transport error could in principle carry an auth header in its message, so we
+ * strip the bearer credential before it reaches `console.*` (AAASM-3645).
+ */
+function redactErrorMessage(error) {
+    const raw = String(error);
+    // Replace the credential that follows a `Bearer ` / `Authorization:` marker.
+    return raw
+        .replace(/(Bearer\s+)[\w.\-+/=]+/gi, `$1${exports.REDACTED}`)
+        .replace(/(Authorization\s*[:=]\s*)\S+/gi, `$1${exports.REDACTED}`);
+}

package/dist/cjs/gateway/client.js

@@ -1,10 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createNoopGatewayClient = createNoopGatewayClient;
+exports.createNativeGatewayClient = createNativeGatewayClient;
 function createNoopGatewayClient(mode, httpBaseUrl) {
     return {
         mode,
-        ...(httpBaseUrl !== undefined ? { httpBaseUrl } : {}),
+        ...(httpBaseUrl === undefined ? {} : { httpBaseUrl }),
         start: async () => undefined,
         close: async () => undefined,
         check: async () => ({ denied: false, pending: false }),
@@ -14,3 +15,64 @@ function createNoopGatewayClient(mode, httpBaseUrl) {
         scanPrompts: async () => undefined
     };
 }
+/**
+ * Translate a governance check request into the native `queryPolicy` query
+ * shape (AAASM-3047). The runtime reads `agent_id`, `action_type`, and — for
+ * tool calls — `tool_name` / `args`.
+ */
+function toNativeQuery(request, agentId) {
+    const query = {
+        agent_id: agentId ?? "",
+        action_type: request.action
+    };
+    if (request.toolName !== undefined) {
+        query.tool_name = request.toolName;
+    }
+    if (request.args !== undefined) {
+        query.args = request.args;
+    }
+    return query;
+}
+/**
+ * Gateway client backed by the in-process native runtime (AAASM-3050).
+ *
+ * `check()` asks a reachable `aa-runtime` for an authoritative verdict via the
+ * native `queryPolicy` primitive and maps it onto a `GatewayDecision`:
+ *   - `deny`    → `{ denied: true }`  (the wrapper throws `PolicyViolationError`)
+ *   - `pending` → `{ pending: true }` (routes to the approval path)
+ *   - allow / redact / unspecified → `{ denied: false }`
+ *
+ * **Fail-open (security-critical):** the SDK is advisory, not a security
+ * boundary. The native primitive already returns `allow` when the runtime is
+ * unreachable or too slow; on top of that, any local fault while querying is
+ * swallowed here and resolves neutral, so a missing or degraded runtime never
+ * blocks the agent. The proxy / eBPF layers remain authoritative.
+ */
+function createNativeGatewayClient(mode, nativeClient, agentId, httpBaseUrl) {
+    return {
+        mode,
+        ...(httpBaseUrl === undefined ? {} : { httpBaseUrl }),
+        start: async () => undefined,
+        close: async () => {
+            await nativeClient.close();
+        },
+        check: async (request) => {
+            try {
+                const verdict = await nativeClient.queryPolicy(toNativeQuery(request, agentId));
+                return {
+                    denied: verdict.denied ?? false,
+                    pending: verdict.pending ?? false,
+                    ...(verdict.reason === undefined ? {} : { reason: verdict.reason })
+                };
+            }
+            catch {
+                // Fail open: a local fault talking to the runtime must never block.
+                return { denied: false, pending: false };
+            }
+        },
+        waitForApproval: async () => ({ denied: false }),
+        record: async () => undefined,
+        recordResult: async () => undefined,
+        scanPrompts: async () => undefined
+    };
+}

package/dist/cjs/gateway/index.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createNoopGatewayClient = void 0;
+exports.createNoopGatewayClient = exports.createNativeGatewayClient = void 0;
 var client_js_1 = require("./client.js");
+Object.defineProperty(exports, "createNativeGatewayClient", { enumerable: true, get: function () { return client_js_1.createNativeGatewayClient; } });
 Object.defineProperty(exports, "createNoopGatewayClient", { enumerable: true, get: function () { return client_js_1.createNoopGatewayClient; } });