@armoriq/sdk-dev 0.4.3 → 0.6.1

package/dist/integrations/langchain.js

@@ -0,0 +1,296 @@
+"use strict";
+/**
+ * ArmorIQ SDK — LangChain integration (TypeScript).
+ *
+ * Mirrors the Python langchain bundle and the Strands/ADK integrations: one
+ * factory per process, one callback handler per (user, agent). It wires two
+ * LangChain callbacks:
+ *
+ *   handleLLMEnd    -> capture the tool calls the model actually chose this turn
+ *                      as the intent plan and mint the ArmorIQ intent token.
+ *   handleToolStart -> enforce per-user policy before each tool runs; block/hold
+ *                      by throwing, which LangChain surfaces as a tool error and
+ *                      skips execution (the handler sets raiseError so the throw
+ *                      is not swallowed).
+ *
+ * Fail-closed: a tool runs only on an explicit ArmorIQ allow. A block, an
+ * un-approved hold, or any enforcement error throws. On HOLD the handler emits
+ * onEvent("hold", ...), then awaits the delegation decision asynchronously
+ * (session.awaitApproval) — approved lets the tool run; rejected/timeout throws.
+ *
+ * @langchain/core is an optional peer dep, loaded lazily so importing this module
+ * never requires langchain to be installed.
+ *
+ * Usage:
+ *   const armoriq = new ArmorIQLangChain({ client, mode: 'sdk' });
+ *   const handler = await armoriq.forUser('alice@acme.com', { goal: 'reconcile' });
+ *   await agentExecutor.invoke({ input: 'Pay invoice 1234' }, { callbacks: [handler] });
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ArmorIQLangChainEnforcer = exports.ArmorIQLangChain = void 0;
+exports.toolCallsFromLLMResult = toolCallsFromLLMResult;
+exports.coerceArgs = coerceArgs;
+const exceptions_1 = require("../exceptions");
+class ArmorIQLangChain {
+    client;
+    mode;
+    validitySeconds;
+    defaultMcpName;
+    approvalWaitSeconds;
+    approvalPollInterval;
+    customParser;
+    _bootstrap;
+    constructor(opts) {
+        this.client = opts.client;
+        this.mode = opts.mode ?? 'sdk';
+        this.validitySeconds = opts.validitySeconds ?? 3600;
+        this.defaultMcpName = opts.defaultMcpName;
+        this.customParser = opts.toolNameParser;
+        this.approvalWaitSeconds =
+            opts.approvalWaitSeconds ??
+                Number(process.env.ARMORIQ_APPROVAL_WAIT_SECONDS ?? '300');
+        this.approvalPollInterval = opts.approvalPollInterval ?? 5;
+    }
+    async bootstrap() {
+        if (!this._bootstrap)
+            this._bootstrap = await this.client.bootstrap();
+        return this._bootstrap;
+    }
+    async toolNameParser() {
+        if (this.customParser)
+            return this.customParser;
+        const toolMap = (await this.bootstrap()).toolMap ?? {};
+        const defaultMcp = this.defaultMcpName ?? 'unknown';
+        return (toolName) => {
+            const mcp = toolMap[toolName];
+            if (mcp)
+                return { mcp, action: toolName };
+            if (toolName.includes('__')) {
+                const [prefix, ...rest] = toolName.split('__');
+                return { mcp: prefix, action: rest.join('__') };
+            }
+            return { mcp: defaultMcp, action: toolName };
+        };
+    }
+    invalidateUser(userEmail) {
+        this.client.invalidateUser(userEmail);
+    }
+    /** Return a LangChain callback handler that enforces every tool call for this
+     * user. Pass it via config { callbacks: [handler] }. */
+    async forUser(userEmail, opts) {
+        const scope = this.client.forUser(userEmail);
+        const enforcer = new ArmorIQLangChainEnforcer({
+            factory: this,
+            scope,
+            userEmail: userEmail.trim().toLowerCase(),
+            goal: opts?.goal,
+            onEvent: opts?.onEvent,
+            parser: await this.toolNameParser(),
+        });
+        return buildCallback(enforcer);
+    }
+}
+exports.ArmorIQLangChain = ArmorIQLangChain;
+/** Framework-agnostic enforcement core (no langchain import), so the allow/hold/
+ * block logic is unit-testable without the langchain package. */
+class ArmorIQLangChainEnforcer {
+    factory;
+    scope;
+    userEmail;
+    goal;
+    onEvent;
+    parser;
+    session;
+    planStarted = false;
+    constructor(args) {
+        this.factory = args.factory;
+        this.scope = args.scope;
+        this.userEmail = args.userEmail;
+        this.goal = args.goal;
+        this.onEvent = args.onEvent;
+        this.parser = args.parser;
+    }
+    emit(kind, payload) {
+        if (!this.onEvent)
+            return;
+        try {
+            this.onEvent(kind, payload);
+        }
+        catch (exc) {
+            console.warn(`[armoriq] onEvent(${kind}) callback failed: ${exc.message}`);
+        }
+    }
+    ensureSession() {
+        if (!this.session) {
+            this.session = this.scope.startSession({
+                mode: this.factory.mode,
+                validitySeconds: this.factory.validitySeconds,
+                toolNameParser: this.parser,
+                defaultMcpName: this.factory.defaultMcpName,
+            });
+        }
+        return this.session;
+    }
+    async capturePlan(toolCalls) {
+        if (!toolCalls.length)
+            return;
+        await this.ensureSession().startPlan(toolCalls, this.goal);
+        this.planStarted = true;
+    }
+    async captureFromLlm(toolCalls) {
+        try {
+            await this.capturePlan(toolCalls);
+        }
+        catch (exc) {
+            console.warn(`[armoriq] langchain plan capture (handleLLMEnd) failed: ${exc.message}`);
+        }
+    }
+    /** Allow -> return; block/hold-denied -> throw (LangChain stops the tool). */
+    async enforceTool(toolName, args) {
+        args = args || {};
+        try {
+            if (!this.planStarted) {
+                // Fail-safe: handleLLMEnd normally mints the plan from the model's chosen
+                // tool calls first. If it didn't, mint from the tool actually being called.
+                await this.capturePlan([{ name: toolName, args }]);
+            }
+            const session = this.ensureSession();
+            const decision = await session.check(toolName, args, this.userEmail);
+            if (decision.allowed)
+                return; // explicit allow -> tool runs
+            if (decision.action === 'hold') {
+                this.emit('hold', {
+                    tool: toolName,
+                    delegationId: decision.delegationId,
+                    reason: decision.reason,
+                });
+                const outcome = await session.awaitApproval(decision.delegationId, {
+                    timeout: this.factory.approvalWaitSeconds,
+                    interval: this.factory.approvalPollInterval,
+                    userEmail: this.userEmail,
+                });
+                if (outcome === 'approved') {
+                    this.emit('approved', { tool: toolName, delegationId: decision.delegationId });
+                    return; // approved -> tool runs
+                }
+                this.emit(outcome, {
+                    tool: toolName,
+                    delegationId: decision.delegationId,
+                    reason: decision.reason,
+                });
+                throw new exceptions_1.PolicyHoldException(`ArmorIQ hold ${outcome}: ${decision.reason ?? 'approval required'}`);
+            }
+            const reason = decision.reason ?? 'blocked by policy';
+            this.emit('block', { tool: toolName, reason });
+            throw new exceptions_1.PolicyBlockedException(`ArmorIQ ${decision.action}: ${reason}`);
+        }
+        catch (exc) {
+            if (exc instanceof exceptions_1.PolicyBlockedException || exc instanceof exceptions_1.PolicyHoldException) {
+                throw exc;
+            }
+            // Fail closed: never let a tool run if enforcement errored.
+            const msg = exc.message ?? String(exc);
+            this.emit('error', { tool: toolName, error: msg });
+            throw new exceptions_1.PolicyBlockedException(`ArmorIQ enforcement error (fail-closed): ${msg}`);
+        }
+    }
+    /** Report an executed tool to ArmorIQ so the plan lifecycle closes (advances to
+     * 'completed' once all declared steps have run). Only called after a tool actually
+     * ran — enforcement-cancelled tools never reach here. Best-effort: audit failures
+     * are logged, never allowed to break the run (mirrors the strands AfterToolCall). */
+    async reportExecution(toolName, args, result, error) {
+        if (!this.session || !this.planStarted)
+            return;
+        try {
+            await this.session.report(toolName, args ?? {}, result, {
+                status: error ? 'error' : 'success',
+                errorMessage: error,
+            });
+        }
+        catch (exc) {
+            console.warn(`[armoriq] langchain execution report failed for ${toolName}: ${exc.message}`);
+        }
+    }
+}
+exports.ArmorIQLangChainEnforcer = ArmorIQLangChainEnforcer;
+function toolCallsFromLLMResult(output) {
+    const calls = [];
+    for (const row of output?.generations ?? []) {
+        for (const gen of row ?? []) {
+            const msg = gen?.message;
+            for (const tc of (msg?.tool_calls ?? [])) {
+                const name = tc?.name;
+                if (name)
+                    calls.push({ name, args: tc.args ?? {} });
+            }
+        }
+    }
+    return calls;
+}
+function coerceArgs(input) {
+    if (input && typeof input === 'object')
+        return input;
+    if (typeof input === 'string' && input) {
+        try {
+            const parsed = JSON.parse(input);
+            return parsed && typeof parsed === 'object' ? parsed : { input: parsed };
+        }
+        catch {
+            return { input };
+        }
+    }
+    return {};
+}
+function buildCallback(enforcer) {
+    let BaseCallbackHandler;
+    try {
+        // Optional peer dep — loaded lazily so importing this module never needs langchain.
+        BaseCallbackHandler = require('@langchain/core/callbacks/base').BaseCallbackHandler;
+    }
+    catch {
+        throw new Error('@langchain/core is not installed.\nInstall it with: npm install @langchain/core');
+    }
+    class ArmorIQLangChainCallback extends BaseCallbackHandler {
+        name = 'armoriq';
+        // Propagate our block/hold throws so LangChain actually stops the tool.
+        raiseError = true;
+        awaitHandlers = true;
+        // runId -> {name, args} for tools that passed enforcement and ran, so
+        // handleToolEnd/handleToolError can report the execution (close the plan).
+        pending = {};
+        async handleLLMEnd(output) {
+            const calls = toolCallsFromLLMResult(output);
+            if (calls.length)
+                await enforcer.captureFromLlm(calls);
+        }
+        async handleToolStart(tool, input, runId, _parentRunId, _tags, _metadata, runName) {
+            const toolName = runName ||
+                tool?.name ||
+                (Array.isArray(tool?.id) ? tool.id[tool.id.length - 1] : '') ||
+                '';
+            const args = coerceArgs(input);
+            await enforcer.enforceTool(toolName, args); // throws to block/hold-deny
+            // Only reached when allowed -> the tool will run; remember it so
+            // handleToolEnd can report the execution and close the plan lifecycle.
+            if (runId)
+                this.pending[runId] = { name: toolName, args };
+        }
+        async handleToolEnd(output, runId) {
+            const info = runId ? this.pending[runId] : undefined;
+            if (info) {
+                delete this.pending[runId];
+                await enforcer.reportExecution(info.name, info.args, output);
+            }
+        }
+        async handleToolError(err, runId) {
+            const info = runId ? this.pending[runId] : undefined;
+            if (info) {
+                delete this.pending[runId];
+                const msg = err?.message ?? String(err);
+                await enforcer.reportExecution(info.name, info.args, msg, msg);
+            }
+        }
+    }
+    return new ArmorIQLangChainCallback();
+}
+//# sourceMappingURL=langchain.js.map

package/dist/integrations/langchain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"langchain.js","sourceRoot":"","sources":["../../src/integrations/langchain.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;;;AAgOH,wDAYC;AAED,gCAWC;AAtPD,8CAA4E;AAgB5E,MAAa,gBAAgB;IAClB,MAAM,CAAgB;IACtB,IAAI,CAAyB;IAC7B,eAAe,CAAS;IACxB,cAAc,CAAU;IACxB,mBAAmB,CAAS;IAC5B,oBAAoB,CAAS;IAC9B,YAAY,CAAkB;IAC9B,UAAU,CAAuB;IAEzC,YAAY,IAA6B;QACvC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,KAAK,CAAC;QAC/B,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,eAAe,IAAI,IAAI,CAAC;QACpD,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,cAAc,CAAC;QAC1C,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,cAAc,CAAC;QACxC,IAAI,CAAC,mBAAmB;YACtB,IAAI,CAAC,mBAAmB;gBACxB,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,6BAA6B,IAAI,KAAK,CAAC,CAAC;QAC7D,IAAI,CAAC,oBAAoB,GAAG,IAAI,CAAC,oBAAoB,IAAI,CAAC,CAAC;IAC7D,CAAC;IAED,KAAK,CAAC,SAAS;QACb,IAAI,CAAC,IAAI,CAAC,UAAU;YAAE,IAAI,CAAC,UAAU,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;QACtE,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,cAAc;QAClB,IAAI,IAAI,CAAC,YAAY;YAAE,OAAO,IAAI,CAAC,YAAY,CAAC;QAChD,MAAM,OAAO,GAA2B,CAAC,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC;QAC/E,MAAM,UAAU,GAAG,IAAI,CAAC,cAAc,IAAI,SAAS,CAAC;QACpD,OAAO,CAAC,QAAgB,EAAE,EAAE;YAC1B,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;YAC9B,IAAI,GAAG;gBAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;YAC1C,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC5B,MAAM,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;gBAC/C,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAClD,CAAC;YACD,OAAO,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;QAC/C,CAAC,CAAC;IACJ,CAAC;IAED,cAAc,CAAC,SAAiB;QAC9B,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC;IACxC,CAAC;IAED;4DACwD;IACxD,KAAK,CAAC,OAAO,CACX,SAAiB,EACjB,IAA2C;QAE3C,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAC7C,MAAM,QAAQ,GAAG,IAAI,wBAAwB,CAAC;YAC5C,OAAO,EAAE,IAAI;YACb,KAAK;YACL,SAAS,EAAE,SAAS,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE;YACzC,IAAI,EAAE,IAAI,EAAE,IAAI;YAChB,OAAO,EAAE,IAAI,EAAE,OAAO;YACtB,MAAM,EAAE,MAAM,IAAI,CAAC,cAAc,EAAE;SACpC,CAAC,CAAC;QACH,OAAO,aAAa,CAAC,QAAQ,CAAC,CAAC;IACjC,CAAC;CACF;AA/DD,4CA+DC;AAED;iEACiE;AACjE,MAAa,wBAAwB;IAC3B,OAAO,CAAmB;IAC1B,KAAK,CAAmB;IACxB,SAAS,CAAS;IAClB,IAAI,CAAU;IACd,OAAO,CAAW;IAClB,MAAM,CAAiB;IAC/B,OAAO,CAAkB;IACzB,WAAW,GAAG,KAAK,CAAC;IAEpB,YAAY,IAOX;QACC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAC5B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACxB,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAC5B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IAC5B,CAAC;IAEO,IAAI,CAAC,IAAY,EAAE,OAA4B;QACrD,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO;QAC1B,IAAI,CAAC;YACH,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC9B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,IAAI,CAAC,qBAAqB,IAAI,sBAAuB,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QACxF,CAAC;IACH,CAAC;IAEO,aAAa;QACnB,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAClB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC;gBACrC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI;gBACvB,eAAe,EAAE,IAAI,CAAC,OAAO,CAAC,eAAe;gBAC7C,cAAc,EAAE,IAAI,CAAC,MAAM;gBAC3B,cAAc,EAAE,IAAI,CAAC,OAAO,CAAC,cAAc;aAC5C,CAAC,CAAC;QACL,CAAC;QACD,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAEO,KAAK,CAAC,WAAW,CAAC,SAA6C;QACrE,IAAI,CAAC,SAAS,CAAC,MAAM;YAAE,OAAO;QAC9B,MAAM,IAAI,CAAC,aAAa,EAAE,CAAC,SAAS,CAAC,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3D,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;IAC1B,CAAC;IAED,KAAK,CAAC,cAAc,CAAC,SAA6C;QAChE,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;QACpC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,IAAI,CAAC,2DAA4D,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QACpG,CAAC;IACH,CAAC;IAED,8EAA8E;IAC9E,KAAK,CAAC,WAAW,CAAC,QAAgB,EAAE,IAAyB;QAC3D,IAAI,GAAG,IAAI,IAAI,EAAE,CAAC;QAClB,IAAI,CAAC;YACH,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;gBACtB,0EAA0E;gBAC1E,4EAA4E;gBAC5E,MAAM,IAAI,CAAC,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;YACrD,CAAC;YACD,MAAM,OAAO,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;YACrC,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;YAErE,IAAI,QAAQ,CAAC,OAAO;gBAAE,OAAO,CAAC,8BAA8B;YAE5D,IAAI,QAAQ,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;gBAC/B,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE;oBAChB,IAAI,EAAE,QAAQ;oBACd,YAAY,EAAE,QAAQ,CAAC,YAAY;oBACnC,MAAM,EAAE,QAAQ,CAAC,MAAM;iBACxB,CAAC,CAAC;gBACH,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,aAAa,CAAC,QAAQ,CAAC,YAAa,EAAE;oBAClE,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,mBAAmB;oBACzC,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,oBAAoB;oBAC3C,SAAS,EAAE,IAAI,CAAC,SAAS;iBAC1B,CAAC,CAAC;gBACH,IAAI,OAAO,KAAK,UAAU,EAAE,CAAC;oBAC3B,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,CAAC,YAAY,EAAE,CAAC,CAAC;oBAC/E,OAAO,CAAC,wBAAwB;gBAClC,CAAC;gBACD,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE;oBACjB,IAAI,EAAE,QAAQ;oBACd,YAAY,EAAE,QAAQ,CAAC,YAAY;oBACnC,MAAM,EAAE,QAAQ,CAAC,MAAM;iBACxB,CAAC,CAAC;gBACH,MAAM,IAAI,gCAAmB,CAC3B,gBAAgB,OAAO,KAAK,QAAQ,CAAC,MAAM,IAAI,mBAAmB,EAAE,CACrE,CAAC;YACJ,CAAC;YAED,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,IAAI,mBAAmB,CAAC;YACtD,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;YAC/C,MAAM,IAAI,mCAAsB,CAAC,WAAW,QAAQ,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC,CAAC;QAC5E,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,mCAAsB,IAAI,GAAG,YAAY,gCAAmB,EAAE,CAAC;gBAChF,MAAM,GAAG,CAAC;YACZ,CAAC;YACD,4DAA4D;YAC5D,MAAM,GAAG,GAAI,GAAa,CAAC,OAAO,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC;YAClD,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;YACnD,MAAM,IAAI,mCAAsB,CAAC,4CAA4C,GAAG,EAAE,CAAC,CAAC;QACtF,CAAC;IACH,CAAC;IAED;;;yFAGqF;IACrF,KAAK,CAAC,eAAe,CACnB,QAAgB,EAChB,IAAyB,EACzB,MAAe,EACf,KAAc;QAEd,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW;YAAE,OAAO;QAC/C,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,IAAI,IAAI,EAAE,EAAE,MAAM,EAAE;gBACtD,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS;gBACnC,YAAY,EAAE,KAAK;aACpB,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,IAAI,CACV,mDAAmD,QAAQ,KAAM,GAAa,CAAC,OAAO,EAAE,CACzF,CAAC;QACJ,CAAC;IACH,CAAC;CACF;AAxID,4DAwIC;AAED,SAAgB,sBAAsB,CAAC,MAAW;IAChD,MAAM,KAAK,GAAuC,EAAE,CAAC;IACrD,KAAK,MAAM,GAAG,IAAI,MAAM,EAAE,WAAW,IAAI,EAAE,EAAE,CAAC;QAC5C,KAAK,MAAM,GAAG,IAAI,GAAG,IAAI,EAAE,EAAE,CAAC;YAC5B,MAAM,GAAG,GAAG,GAAG,EAAE,OAAO,CAAC;YACzB,KAAK,MAAM,EAAE,IAAI,CAAC,GAAG,EAAE,UAAU,IAAI,EAAE,CAAU,EAAE,CAAC;gBAClD,MAAM,IAAI,GAAG,EAAE,EAAE,IAAI,CAAC;gBACtB,IAAI,IAAI;oBAAE,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC,CAAC;YACtD,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAgB,UAAU,CAAC,KAAU;IACnC,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACrD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,EAAE,CAAC;QACvC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YACjC,OAAO,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAC3E,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,KAAK,EAAE,CAAC;QACnB,CAAC;IACH,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,SAAS,aAAa,CAAC,QAAkC;IACvD,IAAI,mBAAwB,CAAC;IAC7B,IAAI,CAAC;QACH,oFAAoF;QACpF,mBAAmB,GAAI,OAAe,CAAC,gCAAgC,CAAC,CAAC,mBAAmB,CAAC;IAC/F,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CACb,iFAAiF,CAClF,CAAC;IACJ,CAAC;IAED,MAAM,wBAAyB,SAAQ,mBAAmB;QACxD,IAAI,GAAG,SAAS,CAAC;QACjB,wEAAwE;QACxE,UAAU,GAAG,IAAI,CAAC;QAClB,aAAa,GAAG,IAAI,CAAC;QACrB,sEAAsE;QACtE,2EAA2E;QAC3E,OAAO,GAAgE,EAAE,CAAC;QAE1E,KAAK,CAAC,YAAY,CAAC,MAAW;YAC5B,MAAM,KAAK,GAAG,sBAAsB,CAAC,MAAM,CAAC,CAAC;YAC7C,IAAI,KAAK,CAAC,MAAM;gBAAE,MAAM,QAAQ,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;QACzD,CAAC;QAED,KAAK,CAAC,eAAe,CACnB,IAAS,EACT,KAAa,EACb,KAAc,EACd,YAAqB,EACrB,KAAgB,EAChB,SAAmC,EACnC,OAAgB;YAEhB,MAAM,QAAQ,GACZ,OAAO;gBACP,IAAI,EAAE,IAAI;gBACV,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC5D,EAAE,CAAC;YACL,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;YAC/B,MAAM,QAAQ,CAAC,WAAW,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,4BAA4B;YACxE,iEAAiE;YACjE,uEAAuE;YACvE,IAAI,KAAK;gBAAE,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;QAC5D,CAAC;QAED,KAAK,CAAC,aAAa,CAAC,MAAW,EAAE,KAAc;YAC7C,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YACrD,IAAI,IAAI,EAAE,CAAC;gBACT,OAAO,IAAI,CAAC,OAAO,CAAC,KAAe,CAAC,CAAC;gBACrC,MAAM,QAAQ,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YAC/D,CAAC;QACH,CAAC;QAED,KAAK,CAAC,eAAe,CAAC,GAAQ,EAAE,KAAc;YAC5C,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YACrD,IAAI,IAAI,EAAE,CAAC;gBACT,OAAO,IAAI,CAAC,OAAO,CAAC,KAAe,CAAC,CAAC;gBACrC,MAAM,GAAG,GAAI,GAAa,EAAE,OAAO,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC;gBACnD,MAAM,QAAQ,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;YACjE,CAAC;QACH,CAAC;KACF;IAED,OAAO,IAAI,wBAAwB,EAAE,CAAC;AACxC,CAAC"}

package/dist/integrations/strands.d.ts

@@ -1,42 +1,53 @@
 /**
  * ArmorIQ SDK — AWS Strands Agents integration (TypeScript).
  *
- * Mirrors the Python integration and the Google ADK bundle. One factory per
- * process, one plugin per (user, agent). It wires two Strands lifecycle hooks:
+ * Mirrors the Python strands bundle. One factory per process, one plugin per
+ * (user, agent). It wires three Strands lifecycle hooks:
  *
- *   AgentInitializedEvent  → capture the agent's tools as the intent plan + mint token
- *   BeforeToolCallEvent    → enforce per-user policy before each tool runs;
- *                            block/hold by setting event.cancel
+ *   AfterModelCallEvent  → capture the tool calls the model actually chose this
+ *                          turn as the intent plan and mint the ArmorIQ intent
+ *                          token (declaring only the tools the turn intends to
+ *                          run — not the agent's whole tool set — so a read-only
+ *                          turn is not flagged 'held' at issuance).
+ *   BeforeToolCallEvent  → enforce per-user policy before each tool runs;
+ *                          block/hold by setting event.cancel_tool.
+ *   AfterToolCallEvent   → report each executed tool to ArmorIQ so the plan
+ *                          lifecycle closes (advances to 'completed' once all
+ *                          declared steps have run) instead of sitting 'active'
+ *                          forever. Enforcement-cancelled tools never ran, so
+ *                          they are not reported.
  *
  * Fail-closed: a tool runs only on an explicit ArmorIQ allow. A block, a hold
- * that is not approved in time, or any enforcement error cancels the tool. The
- * hold path is handled inside session.check() (sdk mode → handleHold → delegation
- * request + approval poll), so HOLD becomes a real approval gate.
+ * that is not approved in time, or any enforcement error cancels the tool. On
+ * HOLD the (async) hook emits onEvent("hold", ...), then awaits the delegation
+ * decision asynchronously (session.awaitApproval) — approved lets the tool run;
+ * rejected or timeout cancels it. The wait is non-blocking, so the host app can
+ * stream live UI updates (held → approved → success) while it waits.
  *
  * Strands' TS SDK is duck-typed here (`any`) so this module has no hard
  * dependency on the strands package; attach the plugin via Agent({ plugins: [p] })
  * or p.register(agent).
- *
- * Usage:
- *   const armoriq = new ArmorIQStrands({ client, mode: 'sdk' });
- *   const plugin = await armoriq.forUser('alice@acme.com', { goal: 'reconcile' });
- *   const agent = new Agent({ model, tools, plugins: [plugin] });
  */
 import { ArmorIQClient, ArmorIQUserScope } from '../client';
 import { SessionOptions } from '../session';
 import { ToolNameParser } from '../plan_builder';
+export type OnEvent = (kind: string, payload: Record<string, any>) => void;
 export interface ArmorIQStrandsOptions {
     client: ArmorIQClient;
     mode?: SessionOptions['mode'];
     validitySeconds?: number;
     defaultMcpName?: string;
     toolNameParser?: ToolNameParser;
+    approvalWaitSeconds?: number;
+    approvalPollInterval?: number;
 }
 export declare class ArmorIQStrands {
     readonly client: ArmorIQClient;
     readonly mode: SessionOptions['mode'];
     readonly validitySeconds: number;
     readonly defaultMcpName?: string;
+    readonly approvalWaitSeconds: number;
+    readonly approvalPollInterval: number;
     private customParser?;
     private _bootstrap?;
     constructor(opts: ArmorIQStrandsOptions);
@@ -45,6 +56,7 @@ export declare class ArmorIQStrands {
     invalidateUser(userEmail: string): void;
     forUser(userEmail: string, opts?: {
         goal?: string;
+        onEvent?: OnEvent;
     }): Promise<ArmorIQStrandsPlugin>;
 }
 export declare class ArmorIQStrandsPlugin {
@@ -52,6 +64,7 @@ export declare class ArmorIQStrandsPlugin {
     private scope;
     private userEmail;
     private goal?;
+    private onEvent?;
     private parser;
     private session?;
     private planStarted;
@@ -60,15 +73,32 @@ export declare class ArmorIQStrandsPlugin {
         scope: ArmorIQUserScope;
         userEmail: string;
         goal?: string;
+        onEvent?: OnEvent;
         parser: ToolNameParser;
     });
     /** Strands Plugin entrypoint: register our hooks on the agent. */
     initAgent(agent: any): void;
-    /** Wire the BeforeToolCall + AgentInitialized hooks onto a Strands agent. */
+    /** Wire the AfterModelCall + BeforeToolCall hooks onto a Strands agent. */
     register(agent: any): void;
+    private emit;
     private ensureSession;
-    private startPlan;
-    private onAgentInitialized;
+    private capturePlan;
+    /** Extract {name, args} for each toolUse block in a Strands model message. */
+    static toolCallsFromMessage(message: any): Array<{
+        name: string;
+        args: any;
+    }>;
+    private onAfterModelCall;
     private beforeToolCall;
+    /**
+     * Report a tool execution to ArmorIQ once it has actually run, so the plan
+     * lifecycle closes: reporting each executed step lets the backend advance the
+     * plan to 'completed' when all declared steps have run, instead of leaving it
+     * stuck 'active' (shown as a perpetual "Running"). Tools we cancelled for
+     * enforcement (block / rejected / timeout / error) never ran, so they are
+     * skipped — a blocked tool must not be logged as executed. Best-effort: audit
+     * failures are logged, never allowed to break the run.
+     */
+    private onAfterToolCall;
 }
 //# sourceMappingURL=strands.d.ts.map

package/dist/integrations/strands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"strands.d.ts","sourceRoot":"","sources":["../../src/integrations/strands.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,EAAkB,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,aAAa,CAAC;IACtB,IAAI,CAAC,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IAC9B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED,qBAAa,cAAc;IACzB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACtC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,OAAO,CAAC,YAAY,CAAC,CAAiB;IACtC,OAAO,CAAC,UAAU,CAAC,CAAsB;gBAE7B,IAAI,EAAE,qBAAqB;IAQjC,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAKzC,cAAc,IAAI,OAAO,CAAC,cAAc,CAAC;IAe/C,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAIjC,OAAO,CACX,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GACvB,OAAO,CAAC,oBAAoB,CAAC;CAUjC;AAED,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,KAAK,CAAmB;IAChC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,IAAI,CAAC,CAAS;IACtB,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,OAAO,CAAC,CAAiB;IACjC,OAAO,CAAC,WAAW,CAAS;gBAEhB,IAAI,EAAE;QAChB,OAAO,EAAE,cAAc,CAAC;QACxB,KAAK,EAAE,gBAAgB,CAAC;QACxB,SAAS,EAAE,MAAM,CAAC;QAClB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,cAAc,CAAC;KACxB;IAQD,kEAAkE;IAClE,SAAS,CAAC,KAAK,EAAE,GAAG,GAAG,IAAI;IAI3B,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,EAAE,GAAG,GAAG,IAAI;IAW1B,OAAO,CAAC,aAAa;YAYP,SAAS;YAST,kBAAkB;YAQlB,cAAc;CAgB7B"}
+{"version":3,"file":"strands.d.ts","sourceRoot":"","sources":["../../src/integrations/strands.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,EAAkB,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAIjD,MAAM,MAAM,OAAO,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,IAAI,CAAC;AAE3E,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,aAAa,CAAC;IACtB,IAAI,CAAC,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IAC9B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,qBAAa,cAAc;IACzB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACtC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,OAAO,CAAC,YAAY,CAAC,CAAiB;IACtC,OAAO,CAAC,UAAU,CAAC,CAAsB;gBAE7B,IAAI,EAAE,qBAAqB;IAYjC,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAKzC,cAAc,IAAI,OAAO,CAAC,cAAc,CAAC;IAe/C,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAIjC,OAAO,CACX,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAC1C,OAAO,CAAC,oBAAoB,CAAC;CAWjC;AAED,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,KAAK,CAAmB;IAChC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,IAAI,CAAC,CAAS;IACtB,OAAO,CAAC,OAAO,CAAC,CAAU;IAC1B,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,OAAO,CAAC,CAAiB;IACjC,OAAO,CAAC,WAAW,CAAS;gBAEhB,IAAI,EAAE;QAChB,OAAO,EAAE,cAAc,CAAC;QACxB,KAAK,EAAE,gBAAgB,CAAC;QACxB,SAAS,EAAE,MAAM,CAAC;QAClB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,MAAM,EAAE,cAAc,CAAC;KACxB;IASD,kEAAkE;IAClE,SAAS,CAAC,KAAK,EAAE,GAAG,GAAG,IAAI;IAI3B,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,GAAG,GAAG,IAAI;IAY1B,OAAO,CAAC,IAAI;IASZ,OAAO,CAAC,aAAa;YAYP,WAAW;IAMzB,8EAA8E;IAC9E,MAAM,CAAC,oBAAoB,CAAC,OAAO,EAAE,GAAG,GAAG,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,GAAG,CAAA;KAAE,CAAC;YAa/D,gBAAgB;YAWhB,cAAc;IAyD5B;;;;;;;;OAQG;YACW,eAAe;CAuB9B"}