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

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

@@ -45,16 +45,15 @@ const agent_context_store_js_1 = require("../lineage/agent-context-store.js");
 exports.vercelAiSdkPatchState = {
     isPatched: false,
     originalToolFactory: undefined,
-    patchedModule: undefined
+    patchedModule: undefined,
+    mutatedOriginal: false
 };
 function captureOriginalToolFactory(module) {
     const candidate = module.tool;
     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 +75,7 @@ function createWrappedExecute(originalExecute, description, gatewayClient, optio
             decision = await gatewayClient.check({
                 action: "tool_call",
                 toolName: description,
-                args: args,
+                args,
                 runId
             });
         }
@@ -114,6 +113,35 @@ function createPatchedToolFactory(originalToolFactory, gatewayClient, options) {
         };
     };
 }
+/**
+ * Install `governed` as the module's `tool` factory without ever assigning to a
+ * frozen ESM namespace.
+ *
+ * A real `ai` package loaded via `import()` is an ES module: its namespace is an
+ * exotic object whose named exports are non-writable, so `module.tool = …` throws
+ * `Cannot assign to read only property 'tool'` (AAASM-3532). We therefore attempt
+ * the in-place assignment only as a fast path for writable plain objects (the
+ * shape used by the unit suite's `loadModule` fakes) and fall back to a mutable
+ * **shim copy** for the frozen-namespace case — the same `{ tool: aiModule.tool }`
+ * shim the AAASM-3525 integration driver proved works. The returned module is what
+ * downstream consumers read the governed factory from (`patchedModule.tool`).
+ */
+function applyGovernedToolFactory(module, governed) {
+    if (Object.isExtensible(module)) {
+        try {
+            module.tool = governed;
+            return { patchedModule: module, mutatedOriginal: true };
+        }
+        catch {
+            // Some non-extensible-but-reported-extensible exotic objects still reject
+            // the write; fall through to the shim copy below.
+        }
+    }
+    return {
+        patchedModule: { ...module, tool: governed },
+        mutatedOriginal: false
+    };
+}
 async function loadVercelAiSdkModule() {
     try {
         const moduleName = "ai";
@@ -137,13 +165,15 @@ async function patchVercelAiSdk(options) {
     if (!originalToolFactory) {
         return false;
     }
-    module.tool = createPatchedToolFactory(originalToolFactory, options.gatewayClient, {
+    const governed = 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 })
     });
+    const { patchedModule, mutatedOriginal } = applyGovernedToolFactory(module, governed);
     exports.vercelAiSdkPatchState.isPatched = true;
-    exports.vercelAiSdkPatchState.patchedModule = module;
+    exports.vercelAiSdkPatchState.patchedModule = patchedModule;
+    exports.vercelAiSdkPatchState.mutatedOriginal = mutatedOriginal;
     return true;
 }
 function unpatchVercelAiSdk() {
@@ -156,9 +186,15 @@ function unpatchVercelAiSdk() {
     if (!exports.vercelAiSdkPatchState.originalToolFactory) {
         return false;
     }
-    exports.vercelAiSdkPatchState.patchedModule.tool =
-        exports.vercelAiSdkPatchState.originalToolFactory;
+    // Only restore when we mutated a writable module in place. For the frozen-ESM
+    // shim path the original `ai` namespace was never touched, so there is nothing
+    // to write back — and attempting it would re-throw the AAASM-3532 crash.
+    if (exports.vercelAiSdkPatchState.mutatedOriginal) {
+        exports.vercelAiSdkPatchState.patchedModule.tool =
+            exports.vercelAiSdkPatchState.originalToolFactory;
+    }
     exports.vercelAiSdkPatchState.isPatched = false;
     exports.vercelAiSdkPatchState.patchedModule = undefined;
+    exports.vercelAiSdkPatchState.mutatedOriginal = false;
     return true;
 }

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) {

package/dist/cjs/index.js

@@ -14,11 +14,19 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-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;
+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.OpTerminatedError = exports.OpControlSubscriber = 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");
 Object.defineProperty(exports, "withAssembly", { enumerable: true, get: function () { return index_js_1.withAssembly; } });
+// Live op-control consumer (AAASM-3491). Subscribes to the gateway's
+// OpControlStream and exposes per-op cooperative-pause / fast-fail-terminate;
+// pass the subscriber as `withAssembly(..., { opControl })` so an operator
+// terminate/pause reaches a running tool through the SDK tool path.
+var op_control_js_1 = require("./op-control.js");
+Object.defineProperty(exports, "OpControlSubscriber", { enumerable: true, get: function () { return op_control_js_1.OpControlSubscriber; } });
+var op_terminated_error_js_1 = require("./errors/op-terminated-error.js");
+Object.defineProperty(exports, "OpTerminatedError", { enumerable: true, get: function () { return op_terminated_error_js_1.OpTerminatedError; } });
 var index_js_2 = require("./types/index.js");
 Object.defineProperty(exports, "ENFORCEMENT_MODES", { enumerable: true, get: function () { return index_js_2.ENFORCEMENT_MODES; } });
 var index_js_3 = require("./audit/index.js");

package/dist/cjs/native/client.js

@@ -3,14 +3,36 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NativeDisconnectError = exports.NativeQueryPolicyError = exports.NativeSendEventError = exports.NativeConnectError = void 0;
+exports.NativeDisconnectError = exports.NativeRegisterError = exports.NativeQueryPolicyError = exports.NativeSendEventError = exports.NativeConnectError = void 0;
+exports.resolveSdkVersion = resolveSdkVersion;
 exports.createNativeClient = createNativeClient;
 const node_module_1 = require("node:module");
 const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Resolve the installed `@agent-assembly/sdk` package version, or `undefined`.
+ *
+ * Forwarded into the native `connect` so the user-facing npm package version —
+ * not the shared `aa-sdk-client` crate version — is what gets signed into the
+ * runtime handshake, giving accurate downgrade detection (AAASM-3683).
+ * `undefined` lets the native shim fall back to the crate version (no
+ * regression vs AAASM-3666). Uses `createRequire(<cwd>/package.json)`, the same
+ * ESM/CJS-safe pattern as the native-binding and runtime-binary resolvers.
+ */
+function resolveSdkVersion() {
+    try {
+        const requireFromHere = (0, node_module_1.createRequire)(node_path_1.default.resolve(process.cwd(), "package.json"));
+        const pkg = requireFromHere("@agent-assembly/sdk/package.json");
+        return typeof pkg.version === "string" && pkg.version.length > 0 ? pkg.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 const NATIVE_BINDING_SINGLETON_KEY = Symbol.for("@agent-assembly/sdk/native-binding");
 const ERROR_CONNECT = "AA_ERR_CONNECT";
 const ERROR_SEND_EVENT = "AA_ERR_SEND_EVENT";
 const ERROR_QUERY_POLICY = "AA_ERR_QUERY_POLICY";
+const ERROR_REGISTER = "AA_ERR_REGISTER";
 const ERROR_DISCONNECT = "AA_ERR_DISCONNECT";
 class NativeConnectError extends Error {
     code = ERROR_CONNECT;
@@ -24,10 +46,33 @@ class NativeQueryPolicyError extends Error {
     code = ERROR_QUERY_POLICY;
 }
 exports.NativeQueryPolicyError = NativeQueryPolicyError;
+class NativeRegisterError extends Error {
+    code = ERROR_REGISTER;
+}
+exports.NativeRegisterError = NativeRegisterError;
 class NativeDisconnectError extends Error {
     code = ERROR_DISCONNECT;
 }
 exports.NativeDisconnectError = NativeDisconnectError;
+/**
+ * Translate the native `{decision, reason}` verdict into the SDK's
+ * `PolicyResult`. Only `"deny"` blocks; `"pending"` routes to the approval
+ * path; `"allow"` / `"redact"` / any unrecognized value proceed. This mirrors
+ * the shared enforcement contract across the Python / Go / Node SDKs.
+ *
+ * The native primitive already fails open (returns `"allow"`) when the runtime
+ * is unreachable or too slow, so a missing or degraded runtime never blocks.
+ */
+function mapDecisionToPolicyResult(verdict) {
+    switch (verdict.decision) {
+        case "deny":
+            return { denied: true, pending: false, reason: verdict.reason };
+        case "pending":
+            return { denied: false, pending: true, reason: verdict.reason };
+        default:
+            return { denied: false, pending: false };
+    }
+}
 function mapNativeError(error) {
     if (!(error instanceof Error)) {
         return new Error(String(error));
@@ -43,6 +88,9 @@ function mapNativeError(error) {
     if (code === ERROR_QUERY_POLICY) {
         return new NativeQueryPolicyError(detail);
     }
+    if (code === ERROR_REGISTER) {
+        return new NativeRegisterError(detail);
+    }
     if (code === ERROR_DISCONNECT) {
         return new NativeDisconnectError(detail);
     }
@@ -51,9 +99,7 @@ function mapNativeError(error) {
 function loadNativeBinding() {
     const shouldUseCache = process.env.VITEST !== "true";
     const globalObject = globalThis;
-    const cachedBinding = shouldUseCache
-        ? globalObject[NATIVE_BINDING_SINGLETON_KEY]
-        : undefined;
+    const cachedBinding = shouldUseCache ? globalObject[NATIVE_BINDING_SINGLETON_KEY] : undefined;
     if (cachedBinding) {
         return cachedBinding;
     }
@@ -85,7 +131,11 @@ function createNativeClient(options) {
             mode,
             close: async () => undefined,
             sendEvent: () => undefined,
-            queryPolicy: async () => ({ denied: false, pending: false })
+            queryPolicy: async () => ({ denied: false, pending: false }),
+            // No native session to register against off the in-process path; the
+            // gRPC sidecar registers the agent in its own process. Resolve neutrally
+            // so init never blocks on a transport that does not own a handle.
+            register: async () => ""
         };
     }
     const binding = loadNativeBinding();
@@ -93,20 +143,21 @@ function createNativeClient(options) {
     let handlePromise;
     let activeHandle;
     let pendingSendError;
+    const sdkVersion = resolveSdkVersion();
     const getHandle = async () => {
-        if (!handlePromise) {
-            handlePromise = binding
-                .connect(socketPath)
-                .then((handle) => {
-                activeHandle = handle;
-                return handle;
-            })
-                .catch((error) => {
-                handlePromise = undefined;
-                activeHandle = undefined;
-                throw mapNativeError(error);
-            });
-        }
+        handlePromise ??= binding
+            // Forward the npm package version so it is signed into the handshake
+            // (AAASM-3683); agent id is wired at register time, not connect.
+            .connect(socketPath, undefined, sdkVersion)
+            .then((handle) => {
+            activeHandle = handle;
+            return handle;
+        })
+            .catch((error) => {
+            handlePromise = undefined;
+            activeHandle = undefined;
+            throw mapNativeError(error);
+        });
         return handlePromise;
     };
     return {
@@ -145,18 +196,36 @@ function createNativeClient(options) {
                 pendingSendError = mapNativeError(error);
             });
         },
-        queryPolicy: async () => {
+        queryPolicy: async (action) => {
             if (pendingSendError) {
                 const error = pendingSendError;
                 pendingSendError = undefined;
                 throw error;
             }
-            // The SDK is not a policy authority. Ensure the session is connected
-            // (surfacing any connect error), then defer: authoritative policy and
-            // approval are enforced server-side (gateway / runtime). The native shim
-            // no longer synthesizes a decision, so this always resolves neutral.
-            await getHandle();
-            return { denied: false, pending: false };
+            // Connect (surfacing any connect error as a genuine local fault), then
+            // ask the runtime for an authoritative verdict via the native primitive.
+            // The native `queryPolicy` is async — it offloads its blocking wait to a
+            // worker thread, so awaiting it never blocks the Node event loop — and it
+            // already fails open (returns `"allow"`) when the runtime is unreachable
+            // or too slow, so a missing or degraded runtime never blocks the agent.
+            const handle = await getHandle();
+            const verdict = await binding.queryPolicy(handle, action);
+            return mapDecisionToPolicyResult(verdict);
+        },
+        register: async (options) => {
+            // Register on the same session the queryPolicy path uses, so the token
+            // the gateway issues is stored on this handle and attached to every
+            // subsequent query. This is the only direct SDK→gateway gRPC call
+            // (ADR 0004); CheckAction still flows through aa-runtime.
+            if (binding.register === undefined) {
+                // A binding without `register` predates AAASM-3400; the agent simply
+                // runs unregistered rather than failing init.
+                return "";
+            }
+            const handle = await getHandle();
+            return binding.register(handle, options).catch((error) => {
+                throw mapNativeError(error);
+            });
         }
     };
 }

package/dist/cjs/op-control.js

@@ -20,39 +20,178 @@
  *   - Auto-wiring into the existing `GatewayClient` / adapter hooks
  *     (separate sub-task when the adapter surface is stable).
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OpControlSubscriber = void 0;
-const grpc_js_1 = require("@grpc/grpc-js");
+exports.gatewayHostOf = gatewayHostOf;
+exports.resolveOpControlCredentials = resolveOpControlCredentials;
 const op_terminated_error_js_1 = require("./errors/op-terminated-error.js");
-const policy_js_1 = require("./proto/generated/policy.js");
+/**
+ * Numeric `OpControlSignal` values, inlined to keep this module grpc-free at load.
+ *
+ * `OpControlSignal` lives in `./proto/generated/policy.js`, which imports
+ * `@grpc/grpc-js` at module scope; importing the enum as a *value* would defeat
+ * the lazy-load. These are the stable protobuf wire numbers (UNSPECIFIED=0,
+ * PAUSE=1, RESUME=2, TERMINATE=3) — `msg.signal` is compared against them
+ * numerically in {@link OpControlSubscriber.dispatch}. The `OpControlSignal`
+ * type is still imported (type-only) for signatures.
+ */
+const SIGNAL_PAUSE = 1;
+const SIGNAL_RESUME = 2;
+const SIGNAL_TERMINATE = 3;
+/**
+ * Hosts treated as loopback for the secure-by-default transport decision.
+ * A loopback gateway is the local dev-mode CP, where plaintext gRPC is the
+ * documented default; anything else is presumed remote and must be encrypted.
+ */
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
+/**
+ * Extract the bare host from a gRPC target (`host:port`, a bare host, or a
+ * URL-style `scheme://host:port`). Returns the lowercased host with any
+ * surrounding IPv6 brackets preserved so it can be matched against
+ * {@link LOOPBACK_HOSTS}.
+ */
+function gatewayHostOf(gatewayUrl) {
+    let target = gatewayUrl.trim();
+    const schemeIdx = target.indexOf("://");
+    if (schemeIdx !== -1)
+        target = target.slice(schemeIdx + 3);
+    // Drop a path/query suffix if a URL form was passed.
+    const slashIdx = target.indexOf("/");
+    if (slashIdx !== -1)
+        target = target.slice(0, slashIdx);
+    if (target.startsWith("[")) {
+        // Bracketed IPv6: keep the bracketed form, strip only the trailing :port.
+        const close = target.indexOf("]");
+        return close === -1 ? target.toLowerCase() : target.slice(0, close + 1).toLowerCase();
+    }
+    const colonIdx = target.indexOf(":");
+    if (colonIdx !== -1)
+        target = target.slice(0, colonIdx);
+    return target.toLowerCase();
+}
+function isLoopbackTarget(gatewayUrl) {
+    return LOOPBACK_HOSTS.has(gatewayHostOf(gatewayUrl));
+}
+/**
+ * Pick channel credentials for the op-control stream, secure by default.
+ *
+ * Precedence: an explicit `credentials` override wins; otherwise a loopback
+ * target gets plaintext (local dev gateway), a remote target gets TLS, and a
+ * remote target is only allowed plaintext when the caller sets `allowInsecure`.
+ *
+ * `grpcCredentials` is injected (rather than imported at module scope) so this
+ * module does not eagerly load `@grpc/grpc-js` — see the module header. The
+ * real-connect path passes the lazily-imported `credentials` namespace.
+ *
+ * @throws never — returns the chosen {@link ChannelCredentials}.
+ */
+function resolveOpControlCredentials(gatewayUrl, opts, grpcCredentials) {
+    if (opts.credentials)
+        return opts.credentials;
+    if (isLoopbackTarget(gatewayUrl))
+        return grpcCredentials.createInsecure();
+    if (opts.allowInsecure)
+        return grpcCredentials.createInsecure();
+    return grpcCredentials.createSsl();
+}
 class OpControlSubscriber {
-    client;
+    /**
+     * `null` until the channel is opened. On the test-seam (`clientFactory`) path
+     * it is set synchronously in {@link connect}; on the real-connect path it is
+     * set asynchronously once `@grpc/grpc-js` + `PolicyServiceClient` have been
+     * lazily imported (see {@link openRealChannel}).
+     */
+    client = null;
     agent;
     ops = new Map();
     call = null;
     alive = true;
-    constructor(client, agent) {
-        this.client = client;
+    /** Set once {@link close} is called before the async channel finishes opening. */
+    closed = false;
+    constructor(agent) {
         this.agent = agent;
     }
-    /** Open the gRPC channel + subscription stream and start the reader. */
+    /**
+     * Open the gRPC channel + subscription stream and start the reader.
+     *
+     * Returns synchronously. On the real-connect path the channel is opened
+     * asynchronously — `@grpc/grpc-js` and `PolicyServiceClient` are loaded lazily
+     * (`await import`) so that importing this module never eagerly pulls grpc (see
+     * the module header). The test seam (`clientFactory`) opens synchronously and
+     * never touches grpc.
+     */
     static connect(gatewayUrl, opts) {
         const agent = {
             orgId: opts.orgId,
             teamId: opts.teamId,
-            agentId: opts.agentId,
+            agentId: opts.agentId
         };
-        const client = opts.clientFactory
-            ? opts.clientFactory()
-            : new policy_js_1.PolicyServiceClient(gatewayUrl, opts.credentials ?? grpc_js_1.credentials.createInsecure());
-        const subscriber = new OpControlSubscriber(client, agent);
-        subscriber.start();
+        const subscriber = new OpControlSubscriber(agent);
+        if (opts.clientFactory) {
+            subscriber.client = opts.clientFactory();
+            subscriber.start();
+        }
+        else {
+            // Real channel: defer grpc loading to the dynamic-import path. Errors
+            // surface as a dead stream so callers see `streamAlive() === false`.
+            void subscriber.openRealChannel(gatewayUrl, opts).catch(() => {
+                subscriber.markStreamDead();
+            });
+        }
         return subscriber;
     }
+    /**
+     * Lazily import grpc + the policy client, build the real client, and start the
+     * reader. Kept off the module's import graph so `import '@agent-assembly/sdk'`
+     * stays grpc-free until a subscriber actually opens a live channel.
+     */
+    async openRealChannel(gatewayUrl, opts) {
+        const { credentials } = await Promise.resolve().then(() => __importStar(require("@grpc/grpc-js")));
+        const { PolicyServiceClient } = await Promise.resolve().then(() => __importStar(require("./proto/generated/policy.js")));
+        if (this.closed)
+            return; // close() raced ahead of the async open.
+        this.client = new PolicyServiceClient(gatewayUrl, resolveOpControlCredentials(gatewayUrl, opts, credentials));
+        this.start();
+    }
     /** Open the stream and wire reader handlers. Public so tests can call
      * directly after constructing with a hand-rolled client.
      */
     start() {
+        if (!this.client)
+            return;
         this.call = this.client.opControlStream({ agentId: this.agent });
         this.call.on("data", (msg) => this.dispatch(msg));
         this.call.on("error", () => this.markStreamDead());
@@ -61,14 +200,14 @@ class OpControlSubscriber {
     dispatch(msg) {
         const state = this.slot(msg.opId);
         switch (msg.signal) {
-            case policy_js_1.OpControlSignal.OP_CONTROL_SIGNAL_PAUSE:
+            case SIGNAL_PAUSE:
                 state.paused = true;
                 break;
-            case policy_js_1.OpControlSignal.OP_CONTROL_SIGNAL_RESUME:
+            case SIGNAL_RESUME:
                 state.paused = false;
                 this.flushResolvers(state);
                 break;
-            case policy_js_1.OpControlSignal.OP_CONTROL_SIGNAL_TERMINATE:
+            case SIGNAL_TERMINATE:
                 state.terminated = true;
                 this.flushResolvers(state);
                 break;
@@ -140,10 +279,13 @@ class OpControlSubscriber {
     streamAlive() {
         return this.alive;
     }
-    /** Cancel the stream and clean up. */
+    /** Cancel the stream and clean up. Safe to call before the async real-channel
+     * open has completed — it flags `closed` so the pending open bails out.
+     */
     close() {
+        this.closed = true;
         this.call?.cancel();
-        this.client.close?.();
+        this.client?.close?.();
         this.markStreamDead();
     }
 }