@agent-assembly/sdk 0.0.1-beta.2 → 0.0.1-beta.4

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.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;
@@ -56,17 +57,109 @@ const index_js_1 = require("../errors/index.js");
  * Resolution precedence (highest first):
  *
  *   1. Explicit field on the AssemblyConfig
- *   2. Environment variable (AAASM_GATEWAY_URL / AAASM_API_KEY)
+ *   2. Environment variable — canonical ``AA_GATEWAY_URL`` / ``AA_API_KEY``,
+ *      with the legacy ``AAASM_GATEWAY_URL`` / ``AAASM_API_KEY`` names accepted
+ *      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";
 exports.DEFAULT_PROBE_TIMEOUT_MS = 500;
 exports.DEFAULT_AUTO_START_TIMEOUT_MS = 5000;
 exports.DEFAULT_CONFIG_FILE_PATH = "~/.aasm/config.yaml";
-exports.ENV_GATEWAY_URL = "AAASM_GATEWAY_URL";
-exports.ENV_API_KEY = "AAASM_API_KEY";
+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.
+ *
+ * When one of these supplies a value (and the canonical ``AA_*`` name is unset)
+ * a one-time deprecation warning is emitted via ``readEnvWithDeprecation``.
+ */
+exports.LEGACY_ENV_GATEWAY_URL = "AAASM_GATEWAY_URL";
+exports.LEGACY_ENV_API_KEY = "AAASM_API_KEY";
+/**
+ * Tracks which legacy env-var names have already produced a deprecation
+ * warning so the message is logged at most once per name per process.
+ */
+const _warnedLegacyEnv = new Set();
+/**
+ * Read an environment variable preferring the canonical ``AA_*`` name and
+ * falling back to a deprecated ``AAASM_*`` alias.
+ *
+ * Returns ``undefined`` when neither name is set. When the value comes from
+ * the legacy alias, a deprecation warning is logged exactly once per legacy
+ * name (guarded by ``_warnedLegacyEnv``) directing the user to the canonical
+ * name.
+ */
+function readEnvWithDeprecation(canonicalName, legacyName) {
+    const canonical = process.env[canonicalName];
+    if (canonical)
+        return canonical;
+    const legacy = process.env[legacyName];
+    if (legacy) {
+        if (!_warnedLegacyEnv.has(legacyName)) {
+            _warnedLegacyEnv.add(legacyName);
+            console.warn(`[agent-assembly] ${legacyName} is deprecated and will be removed in a ` +
+                `future release. Use ${canonicalName} instead.`);
+        }
+        return legacy;
+    }
+    return undefined;
+}
 exports.AASM_AUTO_START_ARGV = ["start", "--mode", "local", "--foreground"];
 /**
  * Return true if a gateway responds with a 2xx status at ``{baseUrl}/healthz``.
@@ -114,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.
@@ -183,7 +280,12 @@ const _seams = {
     loadConfigFile: loadConfigFile,
     autoStartGateway: autoStartGateway,
 };
-exports.__testing = { _seams };
+exports.__testing = {
+    _seams,
+    resetLegacyEnvWarnings: () => {
+        _warnedLegacyEnv.clear();
+    },
+};
 /**
  * Spawn ``aasm start --mode local --foreground`` and wait until ``/healthz``
  * responds.
@@ -201,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 ` +
@@ -218,7 +325,7 @@ async function autoStartGateway(baseUrl = exports.DEFAULT_GATEWAY_URL, timeoutMs
 async function resolveGatewayUrl(explicit) {
     if (explicit)
         return explicit;
-    const fromEnv = process.env[exports.ENV_GATEWAY_URL];
+    const fromEnv = readEnvWithDeprecation(exports.ENV_GATEWAY_URL, exports.LEGACY_ENV_GATEWAY_URL);
     if (fromEnv)
         return fromEnv;
     const config = await _seams.loadConfigFile();
@@ -231,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;
 }
@@ -244,7 +359,7 @@ async function resolveGatewayUrl(explicit) {
 async function resolveApiKey(explicit) {
     if (explicit)
         return explicit;
-    const fromEnv = process.env[exports.ENV_API_KEY];
+    const fromEnv = readEnvWithDeprecation(exports.ENV_API_KEY, exports.LEGACY_ENV_API_KEY);
     if (fromEnv)
         return fromEnv;
     const config = await _seams.loadConfigFile();

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

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ENV_CONTROL_PLANE_URL = exports.ENV_GATEWAY_URL = void 0;
 exports.createClient = createClient;
 exports.detectFrameworks = detectFrameworks;
 exports.registerAdapters = registerAdapters;
@@ -41,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");
@@ -50,9 +52,13 @@ 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 requireFromCwd = (0, node_module_1.createRequire)(`${process.cwd()}/`);
+/** Env-var fallback for ``gatewayUrl`` read at ``initAssembly`` entry. */
+exports.ENV_GATEWAY_URL = "AA_GATEWAY_URL";
+/** Env-var fallback for ``controlPlaneUrl`` read at ``initAssembly`` entry. */
+exports.ENV_CONTROL_PLANE_URL = "AA_CONTROL_PLANE_URL";
 function buildRegistrationEvent(config) {
     const event = { event_type: "register" };
     if (config.parentAgentId !== undefined)
@@ -71,12 +77,74 @@ 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;
     }
-    return (0, client_js_1.createNoopGatewayClient)(mode);
+    // 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) {
     try {
@@ -169,7 +237,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) {
@@ -190,7 +258,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");
     }
@@ -200,55 +274,112 @@ 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 resolvedGatewayUrl = await (0, gateway_resolver_js_1.resolveGatewayUrl)(config.gatewayUrl);
+    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];
+    const controlPlaneUrlInput = config.controlPlaneUrl ?? process.env[exports.ENV_CONTROL_PLANE_URL];
+    const resolvedGatewayUrl = await (0, gateway_resolver_js_1.resolveGatewayUrl)(gatewayUrlInput);
     const resolvedApiKey = await (0, gateway_resolver_js_1.resolveApiKey)(config.apiKey);
     const resolvedConfig = {
         ...config,
         gatewayUrl: resolvedGatewayUrl,
         apiKey: resolvedApiKey,
+        ...(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) {
+            console.warn(`[agent-assembly] agent registration failed; proceeding unregistered: ${String(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/gateway/client.js

@@ -1,9 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createNoopGatewayClient = createNoopGatewayClient;
-function createNoopGatewayClient(mode) {
+exports.createNativeGatewayClient = createNativeGatewayClient;
+function createNoopGatewayClient(mode, httpBaseUrl) {
     return {
         mode,
+        ...(httpBaseUrl === undefined ? {} : { httpBaseUrl }),
         start: async () => undefined,
         close: async () => undefined,
         check: async () => ({ denied: false, pending: false }),
@@ -13,3 +15,64 @@ function createNoopGatewayClient(mode) {
         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; } });

package/dist/cjs/hooks/ai-sdk.js

@@ -52,9 +52,7 @@ function captureOriginalToolFactory(module) {
     if (typeof candidate !== "function") {
         return undefined;
     }
-    if (!exports.vercelAiSdkPatchState.originalToolFactory) {
-        exports.vercelAiSdkPatchState.originalToolFactory = candidate;
-    }
+    exports.vercelAiSdkPatchState.originalToolFactory ??= candidate;
     return exports.vercelAiSdkPatchState.originalToolFactory;
 }
 function recordToolResultNonBlocking(gatewayClient, runId, output) {
@@ -76,7 +74,7 @@ function createWrappedExecute(originalExecute, description, gatewayClient, optio
             decision = await gatewayClient.check({
                 action: "tool_call",
                 toolName: description,
-                args: args,
+                args,
                 runId
             });
         }
@@ -140,7 +138,7 @@ async function patchVercelAiSdk(options) {
     module.tool = createPatchedToolFactory(originalToolFactory, options.gatewayClient, {
         approvalTimeoutMs: options.approvalTimeoutMs ?? 30_000,
         fallbackRunId: options.fallbackRunId ?? "vercel-ai-sdk",
-        ...(options.agentId !== undefined ? { agentId: options.agentId } : {})
+        ...(options.agentId === undefined ? {} : { agentId: options.agentId })
     });
     exports.vercelAiSdkPatchState.isPatched = true;
     exports.vercelAiSdkPatchState.patchedModule = module;

package/dist/cjs/hooks/langchain.js

@@ -1,9 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.patchLangChain = patchLangChain;
+/**
+ * Intentional no-op stub: native-transport LangChain patching is not
+ * implemented. LangChain enforcement is performed in the SDK's callback layer
+ * (post-execution redaction) and wrapper layer (pre-execution deny) wired by
+ * `initAssembly`, not through this native hook — so there is nothing to patch
+ * here yet. Returns `false` (nothing patched) for every mode.
+ *
+ * The `client` parameter is retained to keep the adapter-registry hook
+ * signature (and the public `patchLangChain` export) uniform with the other
+ * `patch*` hooks; it is deliberately unused until native patching lands.
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- stub param kept for signature stability; see TSDoc above
 async function patchLangChain(client) {
-    if (client.mode === "grpc-sidecar" || client.mode === "napi-inprocess") {
-        return false;
-    }
     return false;
 }

package/dist/cjs/hooks/mastra.js

@@ -75,15 +75,18 @@ async function patchMastra(options) {
     exports.mastraPatchState.originalGenerate = originalGenerate;
     exports.mastraPatchState.patchedAgentClass = module.Agent;
     module.Agent.prototype.generate = function patchedGenerate(...args) {
-        let result;
+        // The try guards only the *synchronous* setup (entering the async-context
+        // store and invoking the original); the returned promise is handed to the
+        // caller, which awaits it, so its rejection is the caller's to handle.
+        // Returning it directly (rather than via a local inside the try) avoids an
+        // unhandled-rejection footgun without changing timing or call count.
         try {
-            result = (0, agent_context_store_js_1.runWithAgentId)(agentId, () => originalGenerate.apply(this, args));
+            return (0, agent_context_store_js_1.runWithAgentId)(agentId, () => originalGenerate.apply(this, args));
         }
         catch (e) {
             console.warn("[assembly] Mastra lineage patch error on generate; falling back:", e);
             return originalGenerate.apply(this, args);
         }
-        return result;
     };
     // Wrap Workflow.prototype.execute if present
     if (module.Workflow?.prototype?.execute) {
@@ -91,15 +94,16 @@ async function patchMastra(options) {
         exports.mastraPatchState.originalExecute = originalExecute;
         exports.mastraPatchState.patchedWorkflowClass = module.Workflow;
         module.Workflow.prototype.execute = function patchedExecute(...args) {
-            let result;
+            // See patchedGenerate above: the try guards only the synchronous setup;
+            // the returned promise is awaited by the caller, so returning it directly
+            // (not via a local) handles its rejection without altering behaviour.
             try {
-                result = (0, agent_context_store_js_1.runWithAgentId)(agentId, () => originalExecute.apply(this, args));
+                return (0, agent_context_store_js_1.runWithAgentId)(agentId, () => originalExecute.apply(this, args));
             }
             catch (e) {
                 console.warn("[assembly] Mastra lineage patch error on execute; falling back:", e);
                 return originalExecute.apply(this, args);
             }
-            return result;
         };
     }
     exports.mastraPatchState.isPatched = true;

package/dist/cjs/hooks/openai-agents.js

@@ -54,9 +54,7 @@ function captureOriginalRunTool(agentClass) {
     if (!candidate) {
         return undefined;
     }
-    if (!exports.openAIAgentsPatchState.originalRunTool) {
-        exports.openAIAgentsPatchState.originalRunTool = candidate;
-    }
+    exports.openAIAgentsPatchState.originalRunTool ??= candidate;
     return exports.openAIAgentsPatchState.originalRunTool;
 }
 function parseToolCallArguments(toolCall) {