@agent-assembly/sdk 0.0.1-alpha.3

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

@@ -0,0 +1,189 @@
+"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.openAIAgentsPatchState = void 0;
+exports.captureOriginalRunTool = captureOriginalRunTool;
+exports.parseToolCallArguments = parseToolCallArguments;
+exports.extractToolCallContextMetadata = extractToolCallContextMetadata;
+exports.formatDeniedToolCallOutput = formatDeniedToolCallOutput;
+exports.handlePendingApproval = handlePendingApproval;
+exports.recordToolResultNonBlocking = recordToolResultNonBlocking;
+exports.createPatchedRunTool = createPatchedRunTool;
+exports.patchOpenAIAgents = patchOpenAIAgents;
+exports.unpatchOpenAIAgents = unpatchOpenAIAgents;
+const openai_agents_detection_js_1 = require("./openai-agents-detection.js");
+exports.openAIAgentsPatchState = {
+    isPatched: false,
+    originalRunTool: undefined,
+    patchedAgentClass: undefined
+};
+function captureOriginalRunTool(agentClass) {
+    const candidate = agentClass.prototype._runTool;
+    if (!candidate) {
+        return undefined;
+    }
+    if (!exports.openAIAgentsPatchState.originalRunTool) {
+        exports.openAIAgentsPatchState.originalRunTool = candidate;
+    }
+    return exports.openAIAgentsPatchState.originalRunTool;
+}
+function parseToolCallArguments(toolCall) {
+    try {
+        return JSON.parse(toolCall.function.arguments);
+    }
+    catch {
+        return toolCall.function.arguments;
+    }
+}
+function extractToolCallContextMetadata(context) {
+    return {
+        agentId: context?.agentId ?? undefined,
+        runId: context?.runId ?? undefined
+    };
+}
+function formatDeniedToolCallOutput(reason, prefix) {
+    const detail = reason?.trim() ? reason : "denied";
+    return { error: `${prefix}: ${detail}` };
+}
+async function handlePendingApproval(gatewayClient, options) {
+    const approval = await gatewayClient.waitForApproval(options.toolName, options.runId, options.timeoutMs);
+    if (!approval.denied) {
+        return undefined;
+    }
+    return formatDeniedToolCallOutput(approval.reason, "Approval denied");
+}
+function recordToolResultNonBlocking(gatewayClient, runId, output) {
+    void gatewayClient.recordResult({ runId, output }).catch(() => undefined);
+}
+function createPatchedRunTool(originalRunTool, gatewayClient, options) {
+    return async function patchedRunTool(toolCall, context) {
+        const toolName = toolCall.function.name;
+        const args = parseToolCallArguments(toolCall);
+        const metadata = extractToolCallContextMetadata(context);
+        const runId = metadata.runId ?? options.fallbackRunId;
+        const executeOriginal = async () => {
+            const result = await originalRunTool.call(this, toolCall, context);
+            recordToolResultNonBlocking(gatewayClient, runId, {
+                toolName,
+                args,
+                result,
+                agentId: metadata.agentId
+            });
+            return result;
+        };
+        let decision;
+        try {
+            decision = await gatewayClient.check({
+                action: "tool_call",
+                toolName,
+                args,
+                runId
+            });
+        }
+        catch {
+            return executeOriginal();
+        }
+        if (decision.denied) {
+            return formatDeniedToolCallOutput(decision.reason, "Blocked by governance policy");
+        }
+        if (decision.pending) {
+            let pendingOutput;
+            try {
+                pendingOutput = await handlePendingApproval(gatewayClient, {
+                    toolName,
+                    runId,
+                    timeoutMs: options.approvalTimeoutMs
+                });
+            }
+            catch {
+                return executeOriginal();
+            }
+            if (pendingOutput) {
+                return pendingOutput;
+            }
+        }
+        return executeOriginal();
+    };
+}
+async function loadAgentClassFromSdk() {
+    if (!(0, openai_agents_detection_js_1.hasOpenAIAgentsSDK)()) {
+        return undefined;
+    }
+    try {
+        const moduleName = "@openai/agents";
+        const module = (await Promise.resolve(`${moduleName}`).then(s => __importStar(require(s))));
+        return module.Agent;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function patchOpenAIAgents(options) {
+    if (exports.openAIAgentsPatchState.isPatched) {
+        return true;
+    }
+    const loadAgentClass = options.loadAgentClass ?? loadAgentClassFromSdk;
+    const agentClass = await loadAgentClass();
+    if (!agentClass) {
+        return false;
+    }
+    const originalRunTool = captureOriginalRunTool(agentClass);
+    if (!originalRunTool) {
+        return false;
+    }
+    agentClass.prototype._runTool = createPatchedRunTool(originalRunTool, options.gatewayClient, {
+        approvalTimeoutMs: options.approvalTimeoutMs ?? 30_000,
+        fallbackRunId: options.fallbackRunId ?? "openai-agents"
+    });
+    exports.openAIAgentsPatchState.isPatched = true;
+    exports.openAIAgentsPatchState.patchedAgentClass = agentClass;
+    return true;
+}
+function unpatchOpenAIAgents() {
+    if (!exports.openAIAgentsPatchState.isPatched) {
+        return false;
+    }
+    if (!exports.openAIAgentsPatchState.patchedAgentClass) {
+        return false;
+    }
+    if (!exports.openAIAgentsPatchState.originalRunTool) {
+        return false;
+    }
+    exports.openAIAgentsPatchState.patchedAgentClass.prototype._runTool =
+        exports.openAIAgentsPatchState.originalRunTool;
+    exports.openAIAgentsPatchState.isPatched = false;
+    exports.openAIAgentsPatchState.patchedAgentClass = undefined;
+    return true;
+}

package/dist/cjs/index.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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;
+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; } });
+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");
+Object.defineProperty(exports, "decodeAuditEvent", { enumerable: true, get: function () { return index_js_3.decodeAuditEvent; } });
+Object.defineProperty(exports, "decodeCallStackNode", { enumerable: true, get: function () { return index_js_3.decodeCallStackNode; } });
+Object.defineProperty(exports, "encodeAuditEvent", { enumerable: true, get: function () { return index_js_3.encodeAuditEvent; } });
+Object.defineProperty(exports, "encodeCallStackNode", { enumerable: true, get: function () { return index_js_3.encodeCallStackNode; } });
+var index_js_4 = require("./lineage/index.js");
+Object.defineProperty(exports, "currentAgentId", { enumerable: true, get: function () { return index_js_4.currentAgentId; } });
+Object.defineProperty(exports, "runWithAgentId", { enumerable: true, get: function () { return index_js_4.runWithAgentId; } });
+// Runtime binary resolution helpers (F113 / AAASM-1221). Re-export the
+// discovery + error-message surfaces from src/runtime.ts; the lifecycle
+// `initAssembly` from runtime.ts intentionally stays scoped to the
+// `@agent-assembly/sdk/runtime` subpath export to avoid colliding with
+// the gateway-based `initAssembly` re-exported above.
+var runtime_js_1 = require("./runtime.js");
+Object.defineProperty(exports, "INSTALL_HINT", { enumerable: true, get: function () { return runtime_js_1.INSTALL_HINT; } });
+Object.defineProperty(exports, "findAasmBinary", { enumerable: true, get: function () { return runtime_js_1.findAasmBinary; } });

package/dist/cjs/lineage/agent-context-store.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentContextStore = void 0;
+exports.runWithAgentId = runWithAgentId;
+exports.currentAgentId = currentAgentId;
+const node_async_hooks_1 = require("node:async_hooks");
+/**
+ * Holds the current agent's ID for automatic lineage propagation.
+ * When a framework spawns a child agent, the child's initAssembly reads
+ * this store to auto-populate parentAgentId without manual threading.
+ */
+exports.agentContextStore = new node_async_hooks_1.AsyncLocalStorage();
+/** Run fn within a context where the current agent ID is set. */
+function runWithAgentId(agentId, fn) {
+    return exports.agentContextStore.run(agentId, fn);
+}
+/** Return the current agent ID from the async context, or undefined if absent. */
+function currentAgentId() {
+    return exports.agentContextStore.getStore();
+}

package/dist/cjs/lineage/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runWithAgentId = exports.currentAgentId = exports.agentContextStore = void 0;
+var agent_context_store_js_1 = require("./agent-context-store.js");
+Object.defineProperty(exports, "agentContextStore", { enumerable: true, get: function () { return agent_context_store_js_1.agentContextStore; } });
+Object.defineProperty(exports, "currentAgentId", { enumerable: true, get: function () { return agent_context_store_js_1.currentAgentId; } });
+Object.defineProperty(exports, "runWithAgentId", { enumerable: true, get: function () { return agent_context_store_js_1.runWithAgentId; } });

package/dist/cjs/native/client.js

@@ -0,0 +1,160 @@
+"use strict";
+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.createNativeClient = createNativeClient;
+const node_module_1 = require("node:module");
+const node_path_1 = __importDefault(require("node:path"));
+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_DISCONNECT = "AA_ERR_DISCONNECT";
+class NativeConnectError extends Error {
+    code = ERROR_CONNECT;
+}
+exports.NativeConnectError = NativeConnectError;
+class NativeSendEventError extends Error {
+    code = ERROR_SEND_EVENT;
+}
+exports.NativeSendEventError = NativeSendEventError;
+class NativeQueryPolicyError extends Error {
+    code = ERROR_QUERY_POLICY;
+}
+exports.NativeQueryPolicyError = NativeQueryPolicyError;
+class NativeDisconnectError extends Error {
+    code = ERROR_DISCONNECT;
+}
+exports.NativeDisconnectError = NativeDisconnectError;
+function mapNativeError(error) {
+    if (!(error instanceof Error)) {
+        return new Error(String(error));
+    }
+    const [code, ...rest] = error.message.split(":");
+    const detail = rest.join(":").trim() || error.message;
+    if (code === ERROR_CONNECT) {
+        return new NativeConnectError(detail);
+    }
+    if (code === ERROR_SEND_EVENT) {
+        return new NativeSendEventError(detail);
+    }
+    if (code === ERROR_QUERY_POLICY) {
+        return new NativeQueryPolicyError(detail);
+    }
+    if (code === ERROR_DISCONNECT) {
+        return new NativeDisconnectError(detail);
+    }
+    return error;
+}
+function loadNativeBinding() {
+    const shouldUseCache = process.env.VITEST !== "true";
+    const globalObject = globalThis;
+    const cachedBinding = shouldUseCache
+        ? globalObject[NATIVE_BINDING_SINGLETON_KEY]
+        : undefined;
+    if (cachedBinding) {
+        return cachedBinding;
+    }
+    const requireFromHere = (0, node_module_1.createRequire)(node_path_1.default.resolve(process.cwd(), "package.json"));
+    const candidates = [
+        "../../native/aa-ffi-node/index.cjs",
+        "../../../native/aa-ffi-node/index.cjs",
+        `${process.cwd()}/native/aa-ffi-node/index.cjs`
+    ];
+    let lastError;
+    for (const candidate of candidates) {
+        try {
+            const binding = requireFromHere(candidate);
+            if (shouldUseCache) {
+                globalObject[NATIVE_BINDING_SINGLETON_KEY] = binding;
+            }
+            return binding;
+        }
+        catch (error) {
+            lastError = error;
+        }
+    }
+    throw new NativeConnectError(`Failed to load native binding from known paths: ${String(lastError)}`);
+}
+function createNativeClient(options) {
+    const mode = options.mode ?? "grpc-sidecar";
+    if (mode !== "napi-inprocess") {
+        return {
+            mode,
+            close: async () => undefined,
+            sendEvent: () => undefined,
+            queryPolicy: async () => ({ denied: false, pending: false })
+        };
+    }
+    const binding = loadNativeBinding();
+    const socketPath = options.gateway;
+    let handlePromise;
+    let activeHandle;
+    let pendingSendError;
+    const getHandle = async () => {
+        if (!handlePromise) {
+            handlePromise = binding
+                .connect(socketPath)
+                .then((handle) => {
+                activeHandle = handle;
+                return handle;
+            })
+                .catch((error) => {
+                handlePromise = undefined;
+                activeHandle = undefined;
+                throw mapNativeError(error);
+            });
+        }
+        return handlePromise;
+    };
+    return {
+        mode,
+        close: async () => {
+            if (pendingSendError) {
+                const error = pendingSendError;
+                pendingSendError = undefined;
+                throw error;
+            }
+            if (!handlePromise) {
+                return;
+            }
+            const handle = await getHandle();
+            await binding.disconnect(handle).catch((error) => {
+                throw mapNativeError(error);
+            });
+            handlePromise = undefined;
+            activeHandle = undefined;
+        },
+        sendEvent: (event) => {
+            if (activeHandle) {
+                try {
+                    binding.sendEvent(activeHandle, event);
+                }
+                catch (error) {
+                    pendingSendError = mapNativeError(error);
+                }
+                return;
+            }
+            void getHandle()
+                .then((handle) => {
+                binding.sendEvent(handle, event);
+            })
+                .catch((error) => {
+                pendingSendError = mapNativeError(error);
+            });
+        },
+        queryPolicy: async (action) => {
+            if (pendingSendError) {
+                const error = pendingSendError;
+                pendingSendError = undefined;
+                throw error;
+            }
+            const handle = await getHandle();
+            return binding.queryPolicy(handle, action).catch((error) => {
+                throw mapNativeError(error);
+            });
+        }
+    };
+}

package/dist/cjs/op-control.js

@@ -0,0 +1,150 @@
+"use strict";
+/**
+ * Gateway → SDK op-control consumer (AAASM-1422 PR-F / AAASM-1655).
+ *
+ * Subscribes to `PolicyService.OpControlStream` and exposes a per-`op_id`
+ * cooperative-pause / fast-fail-terminate state machine through
+ * {@link OpControlSubscriber.waitForOp}.
+ *
+ * State machine per op_id:
+ * - `OP_CONTROL_SIGNAL_PAUSE`     → `waitForOp` blocks until RESUME arrives.
+ * - `OP_CONTROL_SIGNAL_RESUME`    → `waitForOp` resolves immediately.
+ * - `OP_CONTROL_SIGNAL_TERMINATE` → `waitForOp` rejects with `OpTerminatedError`.
+ *
+ * Signals that arrive for an `op_id` no one is currently awaiting are
+ * buffered into the per-op slot so the next `waitForOp` sees them.
+ *
+ * Out of scope for PR-F (deferred):
+ *   - Reconnection / heartbeat on stream close (caller observes
+ *     `streamAlive` and re-instantiates if desired).
+ *   - Auto-wiring into the existing `GatewayClient` / adapter hooks
+ *     (separate sub-task when the adapter surface is stable).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpControlSubscriber = void 0;
+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");
+class OpControlSubscriber {
+    client;
+    agent;
+    ops = new Map();
+    call = null;
+    alive = true;
+    constructor(client, agent) {
+        this.client = client;
+        this.agent = agent;
+    }
+    /** Open the gRPC channel + subscription stream and start the reader. */
+    static connect(gatewayUrl, opts) {
+        const agent = {
+            orgId: opts.orgId,
+            teamId: opts.teamId,
+            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();
+        return subscriber;
+    }
+    /** Open the stream and wire reader handlers. Public so tests can call
+     * directly after constructing with a hand-rolled client.
+     */
+    start() {
+        this.call = this.client.opControlStream({ agentId: this.agent });
+        this.call.on("data", (msg) => this.dispatch(msg));
+        this.call.on("error", () => this.markStreamDead());
+        this.call.on("end", () => this.markStreamDead());
+    }
+    dispatch(msg) {
+        const state = this.slot(msg.opId);
+        switch (msg.signal) {
+            case policy_js_1.OpControlSignal.OP_CONTROL_SIGNAL_PAUSE:
+                state.paused = true;
+                break;
+            case policy_js_1.OpControlSignal.OP_CONTROL_SIGNAL_RESUME:
+                state.paused = false;
+                this.flushResolvers(state);
+                break;
+            case policy_js_1.OpControlSignal.OP_CONTROL_SIGNAL_TERMINATE:
+                state.terminated = true;
+                this.flushResolvers(state);
+                break;
+            default:
+                // UNSPECIFIED / UNRECOGNIZED — drop on the floor.
+                break;
+        }
+    }
+    slot(opId) {
+        let state = this.ops.get(opId);
+        if (!state) {
+            state = { paused: false, terminated: false, resolvers: [] };
+            this.ops.set(opId, state);
+        }
+        return state;
+    }
+    flushResolvers(state) {
+        const pending = state.resolvers;
+        state.resolvers = [];
+        for (const resolve of pending)
+            resolve();
+    }
+    markStreamDead() {
+        this.alive = false;
+        // Wake any blocked waiters so they can re-check state.
+        for (const state of this.ops.values())
+            this.flushResolvers(state);
+    }
+    /**
+     * Block until `opId` is runnable, or reject on terminate.
+     *
+     * Resolves immediately when the op is not currently paused. When paused,
+     * waits up to `timeoutMs` for a resume signal. Rejects with
+     * {@link OpTerminatedError} if the op has been (or becomes) terminated.
+     *
+     * A timeout resolves normally — the caller can inspect {@link isPaused}
+     * or retry. Matches the cooperative-pause expectation in the architecture
+     * doc (the SDK yields, it doesn't deadline-enforce).
+     */
+    async waitForOp(opId, opts = {}) {
+        const state = this.slot(opId);
+        if (state.terminated) {
+            throw new op_terminated_error_js_1.OpTerminatedError(`op ${opId} was terminated by the gateway`, opId);
+        }
+        if (!state.paused)
+            return;
+        await new Promise((resolve) => {
+            state.resolvers.push(resolve);
+            if (opts.timeoutMs !== undefined) {
+                setTimeout(() => {
+                    // Remove this resolver from the queue + resolve so the await unblocks.
+                    const idx = state.resolvers.indexOf(resolve);
+                    if (idx !== -1)
+                        state.resolvers.splice(idx, 1);
+                    resolve();
+                }, opts.timeoutMs);
+            }
+        });
+        if (state.terminated) {
+            throw new op_terminated_error_js_1.OpTerminatedError(`op ${opId} was terminated by the gateway`, opId);
+        }
+    }
+    isPaused(opId) {
+        return this.ops.get(opId)?.paused ?? false;
+    }
+    isTerminated(opId) {
+        return this.ops.get(opId)?.terminated ?? false;
+    }
+    streamAlive() {
+        return this.alive;
+    }
+    /** Cancel the stream and clean up. */
+    close() {
+        this.call?.cancel();
+        this.client.close?.();
+        this.markStreamDead();
+    }
+}
+exports.OpControlSubscriber = OpControlSubscriber;

package/dist/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}