@agent-assembly/sdk 0.0.1-beta.4 → 0.0.1-rc.1

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/init-assembly.js

@@ -54,6 +54,7 @@ const openai_agents_detection_js_1 = require("../hooks/openai-agents-detection.j
 const openai_agents_js_1 = require("../hooks/openai-agents.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";
@@ -358,7 +359,10 @@ async function initAssembly(config = {}) {
             await nativeClient.register(buildRegisterOptions(resolvedConfig, frameworks));
         }
         catch (error) {
-            console.warn(`[agent-assembly] agent registration failed; proceeding unregistered: ${String(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.

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/hooks/ai-sdk.js

@@ -45,7 +45,8 @@ 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;
@@ -112,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";
@@ -135,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 })
     });
+    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() {
@@ -154,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/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

@@ -4,9 +4,30 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 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";
@@ -122,9 +143,12 @@ function createNativeClient(options) {
     let handlePromise;
     let activeHandle;
     let pendingSendError;
+    const sdkVersion = resolveSdkVersion();
     const getHandle = async () => {
         handlePromise ??= binding
-            .connect(socketPath)
+            // 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;

package/dist/cjs/op-control.js

@@ -20,13 +20,57 @@
  *   - 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;
 exports.gatewayHostOf = gatewayHostOf;
 exports.resolveOpControlCredentials = resolveOpControlCredentials;
-const grpc_js_1 = require("@grpc/grpc-js");
 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
@@ -68,45 +112,86 @@ function isLoopbackTarget(gatewayUrl) {
  * 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) {
+function resolveOpControlCredentials(gatewayUrl, opts, grpcCredentials) {
     if (opts.credentials)
         return opts.credentials;
     if (isLoopbackTarget(gatewayUrl))
-        return grpc_js_1.credentials.createInsecure();
+        return grpcCredentials.createInsecure();
     if (opts.allowInsecure)
-        return grpc_js_1.credentials.createInsecure();
-    return grpc_js_1.credentials.createSsl();
+        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, resolveOpControlCredentials(gatewayUrl, opts));
-        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());
@@ -115,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;
@@ -194,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();
     }
 }