@agent-assembly/sdk 0.0.1-alpha.3

package/dist/cjs/audit/encode.js

@@ -0,0 +1,176 @@
+"use strict";
+// JSON wire-format bridge for the `AuditEvent` / `CallStackNode` interfaces
+// declared in `../types/audit.ts`. Mirrors the gateway's snake_case JSON
+// convention (consistent with the existing `sendEvent(handle, eventJSON)`
+// path used by `native/aa-ffi-node`) — see AAASM-1450 for context.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeCallStackNode = encodeCallStackNode;
+exports.encodeAuditEvent = encodeAuditEvent;
+exports.decodeCallStackNode = decodeCallStackNode;
+exports.decodeAuditEvent = decodeAuditEvent;
+/**
+ * Translate a {@link CallStackNode} into its wire JSON object form.
+ *
+ * Recurses through `children`. Optional fields (`latencyMs`,
+ * `children`) are dropped when undefined or — for `children` — empty,
+ * so the resulting object is the minimal payload the gateway accepts.
+ */
+function encodeCallStackNode(node) {
+    const wire = {
+        id: node.id,
+        kind: node.kind,
+        label: node.label,
+    };
+    if (node.latencyMs !== undefined) {
+        wire.latency_ms = node.latencyMs;
+    }
+    if (node.children !== undefined && node.children.length > 0) {
+        wire.children = node.children.map(encodeCallStackNode);
+    }
+    return wire;
+}
+/**
+ * Serialize an {@link AuditEvent} to its JSON wire string.
+ *
+ * Translates the camelCase interface field names into the gateway's
+ * snake_case keys (`eventId` → `event_id`, `callStack` → `call_stack`,
+ * etc.), recursively encoding the call-stack tree via
+ * {@link encodeCallStackNode}. Optional fields whose value is
+ * `undefined`, an empty string, or an empty array are omitted so a
+ * legacy decoder that has never seen those fields reads the payload
+ * unchanged.
+ */
+function encodeAuditEvent(event) {
+    const wire = {
+        event_id: event.eventId,
+        agent_id: event.agentId,
+        action_type: event.actionType,
+        decision: event.decision,
+    };
+    if (event.traceId !== undefined && event.traceId !== "") {
+        wire.trace_id = event.traceId;
+    }
+    if (event.spanId !== undefined && event.spanId !== "") {
+        wire.span_id = event.spanId;
+    }
+    if (event.parentSpanId !== undefined && event.parentSpanId !== "") {
+        wire.parent_span_id = event.parentSpanId;
+    }
+    if (event.labels !== undefined && Object.keys(event.labels).length > 0) {
+        wire.labels = event.labels;
+    }
+    if (event.callStack !== undefined && event.callStack.length > 0) {
+        wire.call_stack = event.callStack.map(encodeCallStackNode);
+    }
+    return JSON.stringify(wire);
+}
+function asRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new TypeError("expected JSON object on the wire");
+    }
+    return value;
+}
+/**
+ * Translate a wire JSON object back into a {@link CallStackNode}.
+ *
+ * Symmetric inverse of {@link encodeCallStackNode}: walks `children`
+ * recursively, restores `latencyMs` from `latency_ms`, and treats a
+ * missing or empty `children` field as `undefined` on the interface
+ * side (matches AAASM-1436's default).
+ */
+function decodeCallStackNode(payload) {
+    const wire = asRecord(payload);
+    const id = wire.id;
+    const kindRaw = wire.kind;
+    const label = wire.label;
+    if (typeof id !== "string") {
+        throw new TypeError("CallStackNode.id missing or not a string");
+    }
+    if (typeof kindRaw !== "string") {
+        throw new TypeError("CallStackNode.kind missing or not a string");
+    }
+    if (typeof label !== "string") {
+        throw new TypeError("CallStackNode.label missing or not a string");
+    }
+    const node = {
+        id,
+        kind: kindRaw,
+        label,
+    };
+    if (typeof wire.latency_ms === "number") {
+        node.latencyMs = wire.latency_ms;
+    }
+    if (Array.isArray(wire.children) && wire.children.length > 0) {
+        node.children = wire.children.map(decodeCallStackNode);
+    }
+    return node;
+}
+function asNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function asStringMap(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return undefined;
+    }
+    const entries = Object.entries(value).filter((entry) => typeof entry[1] === "string");
+    return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
+/**
+ * Deserialize a JSON wire payload into a typed {@link AuditEvent}.
+ *
+ * Accepts either the raw JSON string (the gateway's standard
+ * transport) or an already-parsed object (handy for tests and for
+ * callers that received a JSON object via another path). Symmetric
+ * inverse of {@link encodeAuditEvent}: snake_case keys map back to
+ * camelCase fields, and missing / empty optionals decode to
+ * `undefined` so an `AuditEvent` produced from a legacy payload (no
+ * `call_stack`, empty `trace_id`, …) matches what AAASM-1436's
+ * existing consumer-side tests expect.
+ */
+function decodeAuditEvent(payload) {
+    const wire = typeof payload === "string"
+        ? asRecord(JSON.parse(payload))
+        : asRecord(payload);
+    const eventId = wire.event_id;
+    const agentId = wire.agent_id;
+    const actionType = wire.action_type;
+    const decision = wire.decision;
+    if (typeof eventId !== "string") {
+        throw new TypeError("AuditEvent.event_id missing or not a string");
+    }
+    if (typeof agentId !== "string") {
+        throw new TypeError("AuditEvent.agent_id missing or not a string");
+    }
+    if (typeof actionType !== "string") {
+        throw new TypeError("AuditEvent.action_type missing or not a string");
+    }
+    if (typeof decision !== "string") {
+        throw new TypeError("AuditEvent.decision missing or not a string");
+    }
+    const event = {
+        eventId,
+        agentId,
+        actionType,
+        decision,
+    };
+    const traceId = asNonEmptyString(wire.trace_id);
+    if (traceId !== undefined) {
+        event.traceId = traceId;
+    }
+    const spanId = asNonEmptyString(wire.span_id);
+    if (spanId !== undefined) {
+        event.spanId = spanId;
+    }
+    const parentSpanId = asNonEmptyString(wire.parent_span_id);
+    if (parentSpanId !== undefined) {
+        event.parentSpanId = parentSpanId;
+    }
+    const labels = asStringMap(wire.labels);
+    if (labels !== undefined) {
+        event.labels = labels;
+    }
+    if (Array.isArray(wire.call_stack) && wire.call_stack.length > 0) {
+        event.callStack = wire.call_stack.map(decodeCallStackNode);
+    }
+    return event;
+}

package/dist/cjs/audit/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeCallStackNode = exports.encodeAuditEvent = exports.decodeCallStackNode = exports.decodeAuditEvent = void 0;
+var encode_js_1 = require("./encode.js");
+Object.defineProperty(exports, "decodeAuditEvent", { enumerable: true, get: function () { return encode_js_1.decodeAuditEvent; } });
+Object.defineProperty(exports, "decodeCallStackNode", { enumerable: true, get: function () { return encode_js_1.decodeCallStackNode; } });
+Object.defineProperty(exports, "encodeAuditEvent", { enumerable: true, get: function () { return encode_js_1.encodeAuditEvent; } });
+Object.defineProperty(exports, "encodeCallStackNode", { enumerable: true, get: function () { return encode_js_1.encodeCallStackNode; } });

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

@@ -0,0 +1,254 @@
+"use strict";
+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.__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.probeHealthz = probeHealthz;
+exports.waitForHealthz = waitForHealthz;
+exports.loadConfigFile = loadConfigFile;
+exports.autoStartGateway = autoStartGateway;
+exports.resolveGatewayUrl = resolveGatewayUrl;
+exports.resolveApiKey = resolveApiKey;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const index_js_1 = require("../errors/index.js");
+/**
+ * Resolve the gateway URL and API key for ``initAssembly``.
+ *
+ * Implements the zero-config developer-experience contract from Epic 17 (S-G):
+ * ``initAssembly({})`` with no fields and no environment variables should
+ * discover a local gateway at ``http://localhost:7391`` — probing it, and
+ * auto-starting ``aasm start --mode local --foreground`` when not running.
+ *
+ * Resolution precedence (highest first):
+ *
+ *   1. Explicit field on the AssemblyConfig
+ *   2. Environment variable (AAASM_GATEWAY_URL / AAASM_API_KEY)
+ *   3. Config file (~/.aasm/config.yaml, optional js-yaml soft dep)
+ *   4. Local default: probe http://localhost:7391, auto-start if absent
+ */
+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.AASM_AUTO_START_ARGV = ["start", "--mode", "local", "--foreground"];
+/**
+ * Return true if a gateway responds with a 2xx status at ``{baseUrl}/healthz``.
+ *
+ * Uses the global ``fetch`` (Node 18+) with an AbortController-driven
+ * timeout. Any network / timeout / parse error is swallowed and reported
+ * as ``false`` — the resolver treats unreachable as "absent" rather than
+ * fatal.
+ */
+async function probeHealthz(baseUrl, timeoutMs = exports.DEFAULT_PROBE_TIMEOUT_MS) {
+    const url = baseUrl.replace(/\/+$/, "") + exports.DEFAULT_HEALTHZ_PATH;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url, { signal: controller.signal });
+        return response.status >= 200 && response.status < 300;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Poll the gateway healthz endpoint until success or timeout.
+ *
+ * Resolves ``true`` as soon as ``probeHealthz`` succeeds, ``false`` if
+ * the gateway has not become ready within ``timeoutMs``. The poll
+ * interval is short (default 100ms) so the auto-start path feels
+ * instant when the local CP comes up quickly.
+ */
+async function waitForHealthz(baseUrl, timeoutMs = exports.DEFAULT_AUTO_START_TIMEOUT_MS, pollIntervalMs = 100) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (await probeHealthz(baseUrl)) {
+            return true;
+        }
+        await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+    }
+    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;
+}
+/**
+ * Load ``~/.aasm/config.yaml`` if present.
+ *
+ * Returns an empty record when the file is missing, when ``js-yaml`` is
+ * not installed (it is a soft dependency for SDK consumers), or when
+ * the file's contents are not an object. This keeps the resolver chain
+ * purely advisory at step 3 — never throws.
+ */
+async function loadConfigFile(configPath = exports.DEFAULT_CONFIG_FILE_PATH) {
+    // Indirect specifier defeats static module resolution so missing js-yaml
+    // surfaces at runtime (caught below) rather than as a TS compile error.
+    const yamlSpec = "js-yaml";
+    let yamlMod;
+    try {
+        yamlMod = (await Promise.resolve(`${yamlSpec}`).then(s => __importStar(require(s))));
+    }
+    catch {
+        return {};
+    }
+    const expanded = expandHome(configPath);
+    if (!(0, node_fs_1.existsSync)(expanded)) {
+        return {};
+    }
+    try {
+        const parsed = yamlMod.load((0, node_fs_1.readFileSync)(expanded, "utf8"));
+        return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+function defaultFindAasmOnPath() {
+    const PATH = process.env.PATH ?? "";
+    const sep = process.platform === "win32" ? ";" : ":";
+    const exts = process.platform === "win32" ? [".exe", ".cmd", ""] : [""];
+    for (const dir of PATH.split(sep)) {
+        if (!dir)
+            continue;
+        for (const ext of exts) {
+            const candidate = (0, node_path_1.join)(dir, `aasm${ext}`);
+            if ((0, node_fs_1.existsSync)(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+function defaultSpawnAasm(aasmPath) {
+    const child = (0, node_child_process_1.spawn)(aasmPath, [...exports.AASM_AUTO_START_ARGV], {
+        detached: true,
+        stdio: "ignore",
+    });
+    child.unref();
+}
+/**
+ * Mutable seams used by ``autoStartGateway`` — exposed via ``__testing``
+ * so tests can stub the PATH lookup and subprocess spawn without using
+ * ESM module mocking. Production callers should treat this as private.
+ */
+const _seams = {
+    findAasmOnPath: defaultFindAasmOnPath,
+    spawnAasm: defaultSpawnAasm,
+    probeHealthz: probeHealthz,
+    loadConfigFile: loadConfigFile,
+    autoStartGateway: autoStartGateway,
+};
+exports.__testing = { _seams };
+/**
+ * Spawn ``aasm start --mode local --foreground`` and wait until ``/healthz``
+ * responds.
+ *
+ * Throws ``ConfigurationError`` when the ``aasm`` binary is missing from
+ * PATH — the SDK cannot meaningfully auto-start without it. Throws
+ * ``GatewayError`` when the spawned gateway does not become ready within
+ * ``timeoutMs``. The subprocess is launched detached + stdio:"ignore" so
+ * it survives the parent Node process — the docker-style daemon hand-off
+ * described in Epic 17 S-G.
+ */
+async function autoStartGateway(baseUrl = exports.DEFAULT_GATEWAY_URL, timeoutMs = exports.DEFAULT_AUTO_START_TIMEOUT_MS) {
+    const aasmPath = _seams.findAasmOnPath();
+    if (aasmPath === null) {
+        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)");
+    }
+    _seams.spawnAasm(aasmPath);
+    if (!(await waitForHealthz(baseUrl, timeoutMs))) {
+        throw new index_js_1.GatewayError(`Auto-started gateway at ${baseUrl} did not become ready ` +
+            `within ${(timeoutMs / 1000).toFixed(0)} seconds`);
+    }
+}
+/**
+ * Resolve the gateway URL using the 4-step precedence chain.
+ *
+ * Returns the resolved URL. May spawn a local ``aasm`` subprocess
+ * (step 4 only). Propagates ``ConfigurationError`` / ``GatewayError``
+ * from ``autoStartGateway`` when the local default is needed but
+ * cannot be brought up.
+ */
+async function resolveGatewayUrl(explicit) {
+    if (explicit)
+        return explicit;
+    const fromEnv = process.env[exports.ENV_GATEWAY_URL];
+    if (fromEnv)
+        return fromEnv;
+    const config = await _seams.loadConfigFile();
+    const agent = config["agent"];
+    if (agent !== null && typeof agent === "object") {
+        const url = agent["gateway_url"];
+        if (typeof url === "string" && url.length > 0)
+            return url;
+    }
+    if (await _seams.probeHealthz(exports.DEFAULT_GATEWAY_URL)) {
+        return exports.DEFAULT_GATEWAY_URL;
+    }
+    await _seams.autoStartGateway(exports.DEFAULT_GATEWAY_URL);
+    return exports.DEFAULT_GATEWAY_URL;
+}
+/**
+ * Resolve the API key using the same 4-step precedence as the URL.
+ *
+ * Returns the resolved key (possibly empty for local mode, which
+ * accepts unauthenticated agents). Never rejects — an empty API key
+ * is the documented "local dev" default per Epic 17.
+ */
+async function resolveApiKey(explicit) {
+    if (explicit)
+        return explicit;
+    const fromEnv = process.env[exports.ENV_API_KEY];
+    if (fromEnv)
+        return fromEnv;
+    const config = await _seams.loadConfigFile();
+    const agent = config["agent"];
+    if (agent !== null && typeof agent === "object") {
+        const apiKey = agent["api_key"];
+        if (typeof apiKey === "string" && apiKey.length > 0)
+            return apiKey;
+    }
+    return "";
+}

package/dist/cjs/core/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startNetworkLayerIfNeeded = exports.registerAdapters = exports.initAssembly = exports.detectFrameworks = exports.createClient = void 0;
+var init_assembly_js_1 = require("./init-assembly.js");
+Object.defineProperty(exports, "createClient", { enumerable: true, get: function () { return init_assembly_js_1.createClient; } });
+Object.defineProperty(exports, "detectFrameworks", { enumerable: true, get: function () { return init_assembly_js_1.detectFrameworks; } });
+Object.defineProperty(exports, "initAssembly", { enumerable: true, get: function () { return init_assembly_js_1.initAssembly; } });
+Object.defineProperty(exports, "registerAdapters", { enumerable: true, get: function () { return init_assembly_js_1.registerAdapters; } });
+Object.defineProperty(exports, "startNetworkLayerIfNeeded", { enumerable: true, get: function () { return init_assembly_js_1.startNetworkLayerIfNeeded; } });

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

@@ -0,0 +1,224 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createClient = createClient;
+exports.detectFrameworks = detectFrameworks;
+exports.registerAdapters = registerAdapters;
+exports.startNetworkLayerIfNeeded = startNetworkLayerIfNeeded;
+exports.initAssembly = initAssembly;
+const node_module_1 = require("node:module");
+const index_js_1 = require("../adapters/langchain/index.js");
+const client_js_1 = require("../gateway/client.js");
+const client_js_2 = require("../native/client.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");
+const langgraph_detection_js_1 = require("../hooks/langgraph-detection.js");
+const langgraph_js_1 = require("../hooks/langgraph.js");
+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_2 = require("../lineage/index.js");
+const gateway_resolver_js_1 = require("./gateway-resolver.js");
+const requireFromCwd = (0, node_module_1.createRequire)(`${process.cwd()}/`);
+function buildRegistrationEvent(config) {
+    const event = { event_type: "register" };
+    if (config.parentAgentId !== undefined)
+        event.parent_agent_id = config.parentAgentId;
+    if (config.teamId !== undefined)
+        event.team_id = config.teamId;
+    if (config.delegationReason !== undefined)
+        event.delegation_reason = config.delegationReason;
+    if (config.spawnedByTool !== undefined)
+        event.spawned_by_tool = config.spawnedByTool;
+    // AAASM-1561: per-agent enforcement_mode override. Sent only when the
+    // caller set it explicitly so a pre-feature SDK call produces a pre-feature
+    // wire shape. The gateway's REST → gRPC bridge maps the snake_case token
+    // onto RegisterRequest.enforcement_mode (proto enum) per AAASM-1555.
+    if (config.enforcementMode !== undefined)
+        event.enforcement_mode = config.enforcementMode;
+    return event;
+}
+function createClient(config) {
+    const mode = config.mode ?? "auto";
+    if (config.gatewayClient) {
+        return config.gatewayClient;
+    }
+    return (0, client_js_1.createNoopGatewayClient)(mode);
+}
+function isPackageInstalled(packageName) {
+    try {
+        requireFromCwd.resolve(packageName);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function detectFrameworks() {
+    const detected = [];
+    if (isPackageInstalled("@langchain/core")) {
+        detected.push("langchain-js");
+    }
+    if ((0, ai_sdk_detection_js_1.hasVercelAiSdk)()) {
+        detected.push("vercel-ai-sdk");
+    }
+    if ((0, openai_agents_detection_js_1.hasOpenAIAgentsSDK)()) {
+        detected.push("openai-agents");
+    }
+    if ((0, langgraph_detection_js_1.hasLangGraph)()) {
+        detected.push("langgraph-js");
+    }
+    if ((0, mastra_detection_js_1.hasMastra)()) {
+        detected.push("mastra");
+    }
+    return detected;
+}
+function createAdapter(id) {
+    return {
+        id,
+        apply: async () => undefined
+    };
+}
+async function registerAdapters(frameworks) {
+    const adapters = frameworks.map((framework) => createAdapter(framework));
+    for (const adapter of adapters) {
+        await adapter.apply();
+    }
+    return adapters;
+}
+async function startNetworkLayerIfNeeded(client, config) {
+    if (config.mode === "sdk-only") {
+        return;
+    }
+    await client.start();
+}
+function ensureLangChainCallbacks(config) {
+    config.langchain ??= {};
+    config.langchain.callbacks ??= [];
+    return config.langchain.callbacks;
+}
+function ensureLangChainTools(config) {
+    config.langchain ??= {};
+    config.langchain.tools ??= {};
+    return config.langchain.tools;
+}
+function registerLangChainHandler(config, client, frameworks) {
+    if (!frameworks.includes("langchain-js") && !config.langchain) {
+        return undefined;
+    }
+    const callbacks = ensureLangChainCallbacks(config);
+    const handler = new index_js_1.AssemblyCallbackHandler(client);
+    callbacks.push(handler);
+    return handler;
+}
+function wrapLangChainTools(config, client, frameworks) {
+    if (!frameworks.includes("langchain-js") && !config.langchain) {
+        return [];
+    }
+    const tools = ensureLangChainTools(config);
+    const wrapperOptions = {
+        ...(config.langchain?.approvalTimeoutMs
+            ? { approvalTimeoutMs: config.langchain.approvalTimeoutMs }
+            : {})
+    };
+    for (const tool of Object.values(tools)) {
+        (0, index_js_1.wrapToolWithAssembly)(tool, client, wrapperOptions);
+    }
+    return Object.keys(tools);
+}
+async function patchDetectedVercelAiSdk(client, frameworks, agentId) {
+    if (!frameworks.includes("vercel-ai-sdk")) {
+        return false;
+    }
+    return (0, ai_sdk_js_1.patchVercelAiSdk)({
+        gatewayClient: client,
+        ...(agentId !== undefined ? { agentId } : {})
+    });
+}
+async function patchDetectedLangGraph(frameworks, agentId) {
+    if (!frameworks.includes("langgraph-js") || !agentId) {
+        return false;
+    }
+    return (0, langgraph_js_1.patchLangGraph)({ agentId });
+}
+async function patchDetectedMastra(frameworks, agentId) {
+    if (!frameworks.includes("mastra") || !agentId) {
+        return false;
+    }
+    return (0, mastra_js_1.patchMastra)({ agentId });
+}
+async function patchDetectedOpenAIAgents(client, frameworks) {
+    if (!frameworks.includes("openai-agents")) {
+        return false;
+    }
+    return (0, openai_agents_js_1.patchOpenAIAgents)({ gatewayClient: client });
+}
+async function initAssembly(config = {}) {
+    if (config.delegationReason !== undefined && config.delegationReason.length > 256) {
+        throw new RangeError("delegationReason must be <= 256 characters");
+    }
+    // AAASM-1561: catch invalid enforcementMode strings from non-TS callers
+    // (plain JS, JSON config, dynamic input) so the agent doesn't silently
+    // register under live enforcement when the operator meant observe.
+    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)})`);
+    }
+    // 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_2.currentAgentId)();
+    const resolvedGatewayUrl = await (0, gateway_resolver_js_1.resolveGatewayUrl)(config.gatewayUrl);
+    const resolvedApiKey = await (0, gateway_resolver_js_1.resolveApiKey)(config.apiKey);
+    const resolvedConfig = {
+        ...config,
+        gatewayUrl: resolvedGatewayUrl,
+        apiKey: resolvedApiKey,
+        ...(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).
+    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",
+        });
+        nativeClient.sendEvent(buildRegistrationEvent(resolvedConfig));
+    }
+    const langChainHandler = registerLangChainHandler(resolvedConfig, client, frameworks);
+    const wrappedLangChainTools = 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);
+    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 }),
+        ...(resolvedConfig.teamId !== undefined && { teamId: resolvedConfig.teamId }),
+        ...(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?.();
+            }
+            await nativeClient?.close();
+            await client.close();
+        }
+    };
+}