@muxoai/sdk 1.2.3 → 1.3.0

package/dist/engine.js

@@ -0,0 +1,876 @@
+import { resolveNaturalLanguageIntent, } from "./nl.js";
+import { ComposioInstantAdapter } from "./providers/composio-instant.js";
+import { ComposioSdkAdapter } from "./providers/composio-sdk.js";
+import { MicrosoftGovernanceAdapter } from "./providers/microsoft-governance.js";
+import { StripeBillingAdapter } from "./providers/stripe-billing.js";
+import { StripeProjectsAdapter } from "./providers/stripe-projects.js";
+import { SupermemoryAdapter } from "./providers/supermemory.js";
+export class MuxoEngine {
+    config;
+    store;
+    composioSdk;
+    composioInstant;
+    stripeProjects;
+    stripeBilling;
+    governance;
+    supermemory;
+    constructor(config, store) {
+        this.config = config;
+        this.store = store;
+        this.composioSdk = new ComposioSdkAdapter(config);
+        this.composioInstant = new ComposioInstantAdapter(config);
+        this.stripeProjects = new StripeProjectsAdapter(config);
+        this.stripeBilling = new StripeBillingAdapter(config, store);
+        this.governance = new MicrosoftGovernanceAdapter(config.vaultMasterKey);
+        this.supermemory = new SupermemoryAdapter(config);
+    }
+    // 1. get_profile
+    getProfile(ctx) {
+        return {
+            id: ctx.user.id,
+            name: ctx.user.name,
+            email: ctx.user.email,
+            user: ctx.user,
+            actorId: ctx.actorId,
+            authType: ctx.authType,
+            workspaceId: ctx.workspace.id,
+            workspaceName: ctx.workspace.name,
+            tier: ctx.workspace.tier,
+        };
+    }
+    // 2. get_organization
+    getOrganization(ctx) {
+        const ws = this.store.getWorkspace(ctx.workspace.id);
+        const resources = this.store.listResources(ws.id);
+        const connections = this.store.listConnections(ws.id);
+        const supplierSettlementSummary = this.store.getSupplierSettlementSummary(ws.id);
+        return {
+            organization: {
+                id: ws.id,
+                name: ws.name,
+                slug: ws.slug,
+                tier: ws.tier,
+                usage: {
+                    monthlyActionsUsed: ws.monthlyActionsUsed,
+                    monthlyActionsLimit: ws.monthlyActionsLimit,
+                    monthlyActionsRemaining: Math.max(0, ws.monthlyActionsLimit - ws.monthlyActionsUsed),
+                    creditsBalance: ws.creditsBalance,
+                },
+                supplierSettlementSummary,
+                policy: ws.policy,
+                activeConnectionsCount: connections.filter((c) => c.status === "active").length,
+                provisionedResourcesCount: resources.filter((r) => r.status === "active").length,
+                projectsEnvironment: ws.projectsEnvName,
+                createdAt: ws.createdAt,
+            },
+        };
+    }
+    // 3. search_tools
+    async searchTools(params) {
+        const limit = Math.min(100, Math.max(1, Number(params.limit || 25)));
+        const lane = params.lane || "all";
+        const query = params.query?.trim();
+        const results = [];
+        if (lane === "all" || lane === "composio_instant") {
+            results.push(...this.composioInstant.searchTools(query, limit));
+        }
+        if (lane === "all" || lane === "composio_sdk") {
+            const sdkTools = await this.composioSdk.searchTools(query, limit);
+            results.push(...sdkTools);
+        }
+        if (lane === "all" || lane === "stripe_projects") {
+            results.push(...this.stripeProjects.searchTools(query, limit));
+            const billingTools = this.stripeBilling.listTools().filter((t) => {
+                if (!query)
+                    return true;
+                const q = query.toLowerCase();
+                const hay = `${t.slug} ${t.name} ${t.description} ${t.categories.join(" ")}`.toLowerCase();
+                return q.split(/\s+/).some((tok) => hay.includes(tok));
+            });
+            results.push(...billingTools);
+        }
+        const filtered = params.riskLevel
+            ? results.filter((t) => t.riskLevel === params.riskLevel)
+            : results;
+        return {
+            tools: filtered.slice(0, limit),
+            total: filtered.length,
+        };
+    }
+    async listAllCatalogTools() {
+        const instant = this.composioInstant.searchTools(undefined, 100);
+        const sdk = await this.composioSdk.searchTools(undefined, 100);
+        const proj = this.stripeProjects.searchTools(undefined, 100);
+        const billing = this.stripeBilling.listTools();
+        return [...instant, ...billing, ...sdk, ...proj];
+    }
+    // 4. inspect_tool
+    async inspectTool(slug) {
+        const normalized = slug.trim();
+        const billing = this.stripeBilling
+            .listTools()
+            .find((t) => t.slug.toLowerCase() === normalized.toLowerCase() ||
+            t.upstreamSlug.toLowerCase() === normalized.toLowerCase());
+        if (billing)
+            return billing;
+        const instant = this.composioInstant.inspectTool(normalized);
+        if (instant)
+            return instant;
+        const proj = this.stripeProjects.inspectTool(normalized);
+        if (proj)
+            return proj;
+        const sdk = await this.composioSdk.inspectTool(normalized);
+        if (sdk)
+            return sdk;
+        throw new Error(`Tool '${normalized}' not found in Muxo catalog. Use search_tools to discover valid slugs.`);
+    }
+    // 5. connection_status
+    async connectionStatus(ctx, params) {
+        if (params?.syncLive !== false) {
+            // Sync live Composio connected accounts for this workspace
+            const liveComposio = await this.composioSdk.listLiveConnections(ctx.workspace.id);
+            for (const c of liveComposio) {
+                this.store.upsertConnection({
+                    workspaceId: ctx.workspace.id,
+                    lane: "composio_sdk",
+                    providerSlug: c.providerSlug,
+                    providerName: c.providerName,
+                    status: c.status,
+                    externalAccountId: c.externalAccountId,
+                });
+            }
+            // Sync live Stripe Projects linked providers
+            try {
+                const projStatus = await this.stripeProjects.getLiveStatus();
+                for (const p of projStatus.providers) {
+                    this.store.upsertConnection({
+                        workspaceId: ctx.workspace.id,
+                        lane: "stripe_projects",
+                        providerSlug: p.slug,
+                        providerName: p.name,
+                        status: p.status,
+                        externalAccountId: p.id,
+                        redirectUrl: p.redirectUrl,
+                    });
+                }
+            }
+            catch {
+                // Keep cached connections if CLI is busy
+            }
+        }
+        let connections = this.store.listConnections(ctx.workspace.id);
+        if (params?.provider) {
+            const target = params.provider.toLowerCase();
+            connections = connections.filter((c) => c.providerSlug.toLowerCase() === target ||
+                c.providerName.toLowerCase().includes(target));
+        }
+        return {
+            workspaceId: ctx.workspace.id,
+            instantWalletStatus: "active",
+            connections,
+            summary: {
+                total: connections.length,
+                active: connections.filter((c) => c.status === "active").length,
+                pending: connections.filter((c) => c.status === "pending").length,
+                expired: connections.filter((c) => c.status === "expired").length,
+            },
+        };
+    }
+    // 6. start_connection
+    async startConnection(ctx, params) {
+        const rawProvider = params.provider.trim().toLowerCase();
+        const isProjectsLane = params.lane === "stripe_projects" || rawProvider.startsWith("resource.");
+        const cleanSlug = rawProvider.replace(/^(app\.|resource\.)/, "");
+        if (isProjectsLane) {
+            const linked = await this.stripeProjects.linkProvider(cleanSlug);
+            const record = this.store.upsertConnection({
+                workspaceId: ctx.workspace.id,
+                lane: "stripe_projects",
+                providerSlug: linked.providerSlug,
+                providerName: linked.providerSlug.charAt(0).toUpperCase() +
+                    linked.providerSlug.slice(1),
+                status: linked.status,
+                redirectUrl: linked.redirectUrl,
+            });
+            return { ...record, message: linked.message };
+        }
+        const started = await this.composioSdk.startConnection({
+            workspaceId: ctx.workspace.id,
+            providerSlug: cleanSlug,
+            callbackUrl: params.callbackUrl,
+        });
+        const record = this.store.upsertConnection({
+            workspaceId: ctx.workspace.id,
+            lane: "composio_sdk",
+            providerSlug: started.providerSlug,
+            providerName: started.providerName,
+            status: started.status,
+            externalAccountId: started.externalAccountId,
+            redirectUrl: started.redirectUrl,
+            metadata: { callbackUrl: started.callbackUrl },
+        });
+        return {
+            ...record,
+            callbackUrl: started.callbackUrl,
+            message: started.message,
+        };
+    }
+    // 6b. wait_for_connection (OAuth handoff polling & recovery, like COMPOSIO_WAIT_FOR_CONNECTIONS)
+    async waitForConnection(ctx, params) {
+        const cleanSlug = params.provider
+            .trim()
+            .toLowerCase()
+            .replace(/^(app\.|resource\.)/, "");
+        const timeoutMs = Math.min(120, Math.max(0, Number(params.timeoutSeconds ?? 15))) * 1000;
+        const pollIntervalMs = Math.min(5000, Math.max(200, Number(params.pollIntervalMs ?? 1500)));
+        const deadline = Date.now() + timeoutMs;
+        let current = this.store
+            .listConnections(ctx.workspace.id)
+            .find((c) => c.providerSlug.toLowerCase() === cleanSlug);
+        if (!current || (!current.redirectUrl && current.status !== "active")) {
+            try {
+                current = await this.startConnection(ctx, { provider: cleanSlug });
+            }
+            catch {
+                // Proceed with status check
+            }
+        }
+        while (true) {
+            const latestLocal = this.store
+                .listConnections(ctx.workspace.id)
+                .find((c) => c.providerSlug.toLowerCase() === cleanSlug);
+            if (latestLocal) {
+                current = latestLocal;
+                if (latestLocal.status === "active") {
+                    return {
+                        connected: true,
+                        provider: cleanSlug,
+                        status: "active",
+                        connection: latestLocal,
+                        redirectUrl: null,
+                        message: `${latestLocal.providerName} OAuth handoff completed and connection is active.`,
+                    };
+                }
+            }
+            if (current?.externalAccountId && current.lane === "composio_sdk") {
+                const direct = await this.composioSdk.getConnectedAccountStatus(current.externalAccountId);
+                if (direct && direct.status === "active") {
+                    current = this.store.upsertConnection({
+                        workspaceId: ctx.workspace.id,
+                        lane: "composio_sdk",
+                        providerSlug: cleanSlug,
+                        providerName: cleanSlug.charAt(0).toUpperCase() + cleanSlug.slice(1),
+                        status: "active",
+                        externalAccountId: direct.id,
+                        redirectUrl: null,
+                    });
+                    return {
+                        connected: true,
+                        provider: cleanSlug,
+                        status: "active",
+                        connection: current,
+                        redirectUrl: null,
+                        message: `${current.providerName} OAuth handoff completed and connection is active.`,
+                    };
+                }
+            }
+            const synced = await this.connectionStatus(ctx, {
+                provider: cleanSlug,
+                syncLive: true,
+            });
+            const list = synced.connections || [];
+            const found = list.find((c) => c.providerSlug.toLowerCase() === cleanSlug);
+            if (found) {
+                current = found;
+                if (found.status === "active") {
+                    return {
+                        connected: true,
+                        provider: cleanSlug,
+                        status: "active",
+                        connection: found,
+                        redirectUrl: null,
+                        message: `${found.providerName} connection is active and ready for governed execution.`,
+                    };
+                }
+            }
+            if (Date.now() >= deadline) {
+                break;
+            }
+            await new Promise((r) => setTimeout(r, pollIntervalMs));
+        }
+        if (!current) {
+            current = await this.startConnection(ctx, { provider: cleanSlug });
+        }
+        return {
+            connected: false,
+            provider: cleanSlug,
+            status: current.status,
+            connection: current,
+            redirectUrl: current.redirectUrl,
+            message: current.redirectUrl
+                ? `Awaiting user OAuth authorization for ${current.providerName}. Open ${current.redirectUrl} in a browser, then re-run wait_for_connection.`
+                : `Connection for ${current.providerName} is currently ${current.status}.`,
+        };
+    }
+    // 6c. Browser OAuth callback handoff handler (GET /oauth/callback)
+    async handleOAuthCallback(params) {
+        const cleanSlug = params.provider
+            .trim()
+            .toLowerCase()
+            .replace(/^(app\.|resource\.)/, "");
+        const providerName = cleanSlug.charAt(0).toUpperCase() + cleanSlug.slice(1);
+        const ws = this.store.getWorkspace(params.workspaceId);
+        if (!ws) {
+            throw new Error(`Workspace '${params.workspaceId}' not found`);
+        }
+        const existing = this.store
+            .listConnections(ws.id)
+            .find((c) => c.providerSlug.toLowerCase() === cleanSlug);
+        const accountId = params.connectedAccountId || existing?.externalAccountId || null;
+        let resolvedStatus = "pending";
+        if (accountId) {
+            const live = await this.composioSdk.getConnectedAccountStatus(accountId);
+            if (live) {
+                resolvedStatus = live.status;
+            }
+        }
+        if (resolvedStatus !== "active") {
+            const liveList = await this.composioSdk.listLiveConnections(ws.id);
+            const match = liveList.find((c) => c.providerSlug === cleanSlug);
+            if (match) {
+                resolvedStatus = match.status;
+            }
+        }
+        const rawCallbackStatus = String(params.status || "").toLowerCase();
+        if (rawCallbackStatus === "success" ||
+            rawCallbackStatus === "active" ||
+            rawCallbackStatus === "connected") {
+            resolvedStatus = "active";
+        }
+        const updated = this.store.upsertConnection({
+            workspaceId: ws.id,
+            lane: "composio_sdk",
+            providerSlug: cleanSlug,
+            providerName,
+            status: resolvedStatus,
+            externalAccountId: accountId,
+            redirectUrl: resolvedStatus === "active" ? null : existing?.redirectUrl,
+        });
+        return {
+            ok: true,
+            workspaceId: ws.id,
+            providerSlug: cleanSlug,
+            providerName,
+            status: updated.status,
+            externalAccountId: updated.externalAccountId,
+        };
+    }
+    // 7. plan_action
+    async planAction(ctx, params) {
+        const ws = this.store.getWorkspace(ctx.workspace.id);
+        let tool;
+        let resolvedInput = { ...(params.input || {}) };
+        let resolvedReason = params.reason || `Planned execution of ${params.toolSlug}`;
+        try {
+            tool = await this.inspectTool(params.toolSlug);
+        }
+        catch (inspectErr) {
+            // Natural-language fallback: if an agent or human passed plain English as toolSlug/instruction, resolve it!
+            const nlSource = `${params.toolSlug} ${params.reason || ""}`.trim();
+            const allTools = await this.listAllCatalogTools();
+            const byokEnv = this.store.getDecryptedWorkspaceEnv(ws.id);
+            const nl = await resolveNaturalLanguageIntent({
+                prompt: nlSource,
+                tools: allTools,
+                explicitInput: resolvedInput,
+                byokKeys: byokEnv,
+            });
+            if (!nl.resolved || !nl.tool) {
+                throw inspectErr;
+            }
+            tool = nl.tool;
+            resolvedInput = nl.input;
+            resolvedReason = params.reason || nl.reason || nlSource;
+        }
+        const byokActive = this.store.hasByokForLane(ws.id, tool.lane, tool.slug);
+        const effectiveCreditCost = byokActive ? 0 : tool.creditCost;
+        if (ws.monthlyActionsUsed >= ws.monthlyActionsLimit) {
+            throw new Error(`Monthly action limit reached (${ws.monthlyActionsUsed}/${ws.monthlyActionsLimit}). Upgrade to Starter ($29/mo) to unlock 5,000 actions/mo.`);
+        }
+        if (effectiveCreditCost > ws.creditsBalance) {
+            throw new Error(`Insufficient workspace credits for ${tool.slug} (requires ${effectiveCreditCost}, available ${ws.creditsBalance}). Top up credits or configure a BYOK key.`);
+        }
+        if (effectiveCreditCost > ws.policy.maxCreditsPerRun) {
+            throw new Error(`Tool credit cost (${effectiveCreditCost}) exceeds workspace policy maxCreditsPerRun (${ws.policy.maxCreditsPerRun}).`);
+        }
+        // 1. Evaluate Microsoft Agent Governance Pipeline:
+        // Agent -> McpSecurityScanner -> PolicyEngine -> AgentIdentity (Ed25519 DID) -> AuditLogger -> DecisionRecord
+        const decisionRecord = this.governance.evaluatePlan({
+            workspace: ws,
+            actorId: ctx.actorId,
+            tool,
+            input: resolvedInput,
+            reason: resolvedReason,
+        });
+        if (decisionRecord.verdict === "deny") {
+            throw new Error(`Microsoft Agent Governance denied plan for ${tool.slug} (rule: ${decisionRecord.matchedRule}): ${decisionRecord.reason}`);
+        }
+        // 2. Recall Supermemory v5 contextual brain for this workspace + tool intent
+        const memoryQuery = `${tool.slug} ${tool.name} ${resolvedReason}`.trim();
+        const memoryContext = await this.supermemory.getContextForWorkspace(ws.id, memoryQuery);
+        const requiresHumanApproval = decisionRecord.verdict === "escalate" ||
+            (ws.policy.mode === "enforce" &&
+                ws.policy.requireApprovalFor.includes(tool.riskLevel));
+        const approvalStatus = requiresHumanApproval
+            ? "pending_approval"
+            : "auto_approved";
+        const plan = this.store.createPlan({
+            workspaceId: ws.id,
+            actorId: ctx.actorId,
+            toolSlug: tool.slug,
+            upstreamSlug: tool.upstreamSlug,
+            lane: tool.lane,
+            riskLevel: tool.riskLevel,
+            input: resolvedInput,
+            reason: resolvedReason,
+            creditCost: effectiveCreditCost,
+            approvalStatus,
+            decisionRecord,
+            memoryContext,
+        });
+        // 3. Check external user OAuth connection state for Connected Apps (composio_sdk)
+        let authHandoff;
+        if (tool.lane === "composio_sdk" && tool.requiresAuth) {
+            let existingConn = this.store
+                .listConnections(ws.id)
+                .find((c) => c.lane === "composio_sdk" &&
+                c.providerSlug.toLowerCase() === tool.providerSlug.toLowerCase());
+            if (!existingConn || existingConn.status !== "active") {
+                try {
+                    if (!existingConn || !existingConn.redirectUrl) {
+                        existingConn = await this.startConnection(ctx, {
+                            provider: tool.providerSlug,
+                        });
+                    }
+                }
+                catch {
+                    // Keep existing connection state if offline
+                }
+                if (!existingConn || existingConn.status !== "active") {
+                    authHandoff = {
+                        required: true,
+                        provider: tool.providerSlug,
+                        status: existingConn?.status || "pending",
+                        redirectUrl: existingConn?.redirectUrl || null,
+                        externalAccountId: existingConn?.externalAccountId || null,
+                        instructions: existingConn?.redirectUrl
+                            ? `Ask the user to authorize ${tool.providerName} at ${existingConn.redirectUrl}, then call wait_for_connection({ provider: "${tool.providerSlug}" }) before executing ${plan.id}.`
+                            : `Call start_connection({ provider: "${tool.providerSlug}" }) to authorize ${tool.providerName} before executing ${plan.id}.`,
+                    };
+                }
+            }
+        }
+        const executeToolName = `execute_${tool.riskLevel}`;
+        let nextStep = approvalStatus === "pending_approval"
+            ? `Plan ${plan.id} requires human owner approval in the Muxo Console or via approve_plan before calling ${executeToolName}.`
+            : `Plan ${plan.id} is auto-approved. Call ${executeToolName}({ plan_id: "${plan.id}" }) to execute.`;
+        if (authHandoff?.required) {
+            nextStep = `${authHandoff.instructions} Once connected, ${nextStep}`;
+        }
+        return {
+            plan,
+            tool,
+            decisionRecord,
+            memoryContext,
+            ...(authHandoff ? { authHandoff } : {}),
+            nextStep,
+        };
+    }
+    // 8. get_plan
+    getPlan(ctx, planId) {
+        const plan = this.store.getPlan(ctx.workspace.id, planId);
+        if (!plan)
+            throw new Error(`Plan '${planId}' not found in workspace.`);
+        return plan;
+    }
+    // Human owner approval / rejection
+    approvePlan(ctx, planId, decision = "approved") {
+        const plan = this.getPlan(ctx, planId);
+        if (plan.approvalStatus === "executed") {
+            throw new Error(`Plan '${planId}' has already been executed.`);
+        }
+        return this.store.updatePlanApproval({
+            workspaceId: ctx.workspace.id,
+            planId,
+            approvalStatus: decision,
+            approvedBy: ctx.user.email,
+        });
+    }
+    // 9. get_run_context
+    async getRunContext(ctx, query) {
+        const ws = this.store.getWorkspace(ctx.workspace.id);
+        const resources = this.store.listResources(ws.id);
+        const activeEnv = this.store.getDecryptedWorkspaceEnv(ws.id);
+        const redactedEnv = {};
+        for (const [k, v] of Object.entries(activeEnv)) {
+            redactedEnv[k] =
+                v.length > 8 ? `${v.slice(0, 4)}••••${v.slice(-3)}` : "••••••••";
+        }
+        const memoryContext = await this.supermemory.getContextForWorkspace(ws.id, query);
+        return {
+            workspaceId: ws.id,
+            workspaceSlug: ws.slug,
+            projectsEnvironment: ws.projectsEnvName,
+            policy: ws.policy,
+            creditsBalance: ws.creditsBalance,
+            monthlyActionsRemaining: Math.max(0, ws.monthlyActionsLimit - ws.monthlyActionsUsed),
+            provisionedResources: resources.filter((r) => r.status === "active"),
+            environmentVariablesRedacted: redactedEnv,
+            supermemoryBrain: memoryContext,
+            governance: this.governance.getStatus(ws),
+            envPullHint: "Run `muxo env pull` or call GET /api/v1/resources/env to write decrypted credentials to your local .env file.",
+        };
+    }
+    // Supermemory Workspace Brain Operations
+    async getMemoryOverview(ctx, query) {
+        const context = await this.supermemory.getContextForWorkspace(ctx.workspace.id, query);
+        const recentMemories = this.store.listMemoryRecords(ctx.workspace.id, 25);
+        return {
+            enabled: context.enabled,
+            namespace: context.namespace,
+            context,
+            recentMemories,
+            memories: recentMemories,
+        };
+    }
+    async addWorkspaceMemory(ctx, params) {
+        const kind = params.kind || "fact";
+        const remote = await this.supermemory.addMemory({
+            workspaceId: ctx.workspace.id,
+            title: params.title,
+            content: params.content,
+            kind,
+            metadata: params.metadata,
+        });
+        return this.store.saveMemoryRecord({
+            workspaceId: ctx.workspace.id,
+            namespace: remote.namespace,
+            documentId: remote.documentId,
+            title: params.title,
+            content: remote.sanitizedContent,
+            kind,
+            metadata: {
+                ...(params.metadata || {}),
+                supermemoryStatus: remote.status,
+            },
+        });
+    }
+    async deleteWorkspaceMemory(ctx, idOrDocId) {
+        const local = this.store.deleteMemoryRecord(ctx.workspace.id, idOrDocId);
+        const docId = local?.documentId || idOrDocId;
+        const remote = await this.supermemory.deleteMemory(ctx.workspace.id, docId);
+        return {
+            deleted: Boolean(local || remote.deleted),
+            record: local,
+        };
+    }
+    // 10-15. execute_<risk_level>
+    async executePlanForRisk(ctx, planId, expectedRisk) {
+        const plan = this.getPlan(ctx, planId);
+        if (plan.riskLevel !== expectedRisk) {
+            throw new Error(`Risk lane mismatch: Plan '${plan.id}' has risk level '${plan.riskLevel}', so it must be executed with 'execute_${plan.riskLevel}' instead of 'execute_${expectedRisk}'.`);
+        }
+        if (plan.runId) {
+            const existingRun = this.store.getRun(ctx.workspace.id, plan.runId);
+            const existingReceipt = this.store.getReceipt(ctx.workspace.id, plan.runId);
+            if (existingRun && existingReceipt) {
+                return { run: existingRun, receipt: existingReceipt };
+            }
+            throw new Error(`Plan '${plan.id}' was already claimed by run '${plan.runId}' (execute-once invariant).`);
+        }
+        if (plan.approvalStatus === "pending_approval") {
+            throw new Error(`Plan '${plan.id}' (${plan.riskLevel}) is awaiting human approval. Approve it in the Muxo Console or via CLI 'muxo approve ${plan.id}' before executing.`);
+        }
+        if (plan.approvalStatus === "rejected") {
+            throw new Error(`Plan '${plan.id}' was rejected and cannot be executed.`);
+        }
+        const ws = this.store.getWorkspace(ctx.workspace.id);
+        const tool = await this.inspectTool(plan.toolSlug);
+        const execDecisionRecord = this.governance.evaluateExecution({
+            workspace: ws,
+            actorId: ctx.actorId,
+            plan,
+            tool,
+        });
+        if (execDecisionRecord.verdict === "deny") {
+            throw new Error(`Microsoft Agent Governance denied execution of plan '${plan.id}': ${execDecisionRecord.reason}`);
+        }
+        let activeConnId = null;
+        if (plan.lane === "composio_sdk" && tool.requiresAuth) {
+            let connections = this.store.listConnections(ctx.workspace.id);
+            let activeConn = connections.find((c) => c.lane === "composio_sdk" &&
+                c.providerSlug === tool.providerSlug &&
+                c.status === "active");
+            if (!activeConn) {
+                await this.waitForConnection(ctx, {
+                    provider: tool.providerSlug,
+                    timeoutSeconds: 0,
+                }).catch(() => { });
+                connections = this.store.listConnections(ctx.workspace.id);
+                activeConn = connections.find((c) => c.lane === "composio_sdk" &&
+                    c.providerSlug === tool.providerSlug &&
+                    c.status === "active");
+            }
+            if (!activeConn) {
+                throw new Error(`No active OAuth connection for ${tool.providerSlug}. Complete OAuth handoff and call wait_for_connection({ provider: "${tool.providerSlug}" }) before executing plan '${plan.id}'.`);
+            }
+            activeConnId = activeConn.externalAccountId;
+        }
+        const run = this.store.createRun(plan, ctx.actorId);
+        const startedMs = Date.now();
+        try {
+            let output;
+            if (plan.toolSlug.startsWith("billing.")) {
+                output = await this.stripeBilling.executeTool({
+                    workspace: ws,
+                    customerEmail: ctx.user.email,
+                    toolSlug: plan.toolSlug,
+                    input: plan.input,
+                });
+            }
+            else if (plan.lane === "composio_instant") {
+                output = await this.composioInstant.executeTool({
+                    workspaceId: ctx.workspace.id,
+                    tool,
+                    input: plan.input,
+                });
+            }
+            else if (plan.lane === "composio_sdk") {
+                output = await this.composioSdk.executeTool({
+                    workspaceId: ctx.workspace.id,
+                    tool,
+                    input: plan.input,
+                    connectedAccountId: activeConnId,
+                });
+            }
+            else if (plan.lane === "stripe_projects") {
+                const projResult = await this.stripeProjects.executeTool({
+                    workspaceId: ctx.workspace.id,
+                    tool,
+                    input: plan.input,
+                });
+                output = projResult.output;
+                if (projResult.provisionedResource) {
+                    this.store.upsertResource({
+                        workspaceId: ctx.workspace.id,
+                        ...projResult.provisionedResource,
+                    });
+                }
+            }
+            else {
+                throw new Error(`Unsupported execution lane: ${plan.lane}`);
+            }
+            const durationMs = Date.now() - startedMs;
+            const finalized = this.store.finalizeRun({
+                workspaceId: ctx.workspace.id,
+                runId: run.id,
+                status: "succeeded",
+                output,
+                actionsMetered: 1,
+                creditsMetered: plan.creditCost,
+                durationMs,
+                decisionRecord: execDecisionRecord,
+            });
+            // Record secret-redacted post-run memory in Supermemory for stateful actions
+            if (plan.riskLevel !== "read") {
+                const summary = `Executed ${plan.toolSlug} (${plan.lane}, risk=${plan.riskLevel}) for reason "${plan.reason}" -> status=succeeded (receipt=${finalized.receipt.id}).`;
+                this.supermemory
+                    .recordExecutionMemory({
+                    workspaceId: ctx.workspace.id,
+                    toolSlug: plan.toolSlug,
+                    lane: plan.lane,
+                    riskLevel: plan.riskLevel,
+                    reason: plan.reason,
+                    status: "succeeded",
+                    summary,
+                })
+                    .then((docId) => {
+                    if (docId) {
+                        this.store.saveMemoryRecord({
+                            workspaceId: ctx.workspace.id,
+                            namespace: this.supermemory.getWorkspaceNamespace(ctx.workspace.id),
+                            documentId: docId,
+                            title: `Execution: ${plan.toolSlug} (succeeded)`,
+                            content: this.supermemory.sanitizeContent(summary),
+                            kind: "execution_outcome",
+                            metadata: {
+                                runId: finalized.run.id,
+                                receiptId: finalized.receipt.id,
+                                toolSlug: plan.toolSlug,
+                            },
+                        });
+                    }
+                })
+                    .catch(() => { });
+            }
+            return finalized;
+        }
+        catch (err) {
+            const durationMs = Date.now() - startedMs;
+            const errorMessage = String(err?.message || err || "Execution failed");
+            return this.store.finalizeRun({
+                workspaceId: ctx.workspace.id,
+                runId: run.id,
+                status: "failed",
+                output: { error: errorMessage },
+                error: errorMessage,
+                actionsMetered: 1,
+                creditsMetered: 0,
+                durationMs,
+                decisionRecord: execDecisionRecord,
+            });
+        }
+    }
+    // 16. get_run
+    getRun(ctx, runId) {
+        const run = this.store.getRun(ctx.workspace.id, runId);
+        if (!run)
+            throw new Error(`Run '${runId}' not found in workspace.`);
+        return run;
+    }
+    // 17. cancel_run
+    cancelRun(ctx, runId) {
+        const run = this.getRun(ctx, runId);
+        if (run.status === "succeeded" || run.status === "failed" || run.status === "cancelled") {
+            return {
+                run,
+                receipt: this.store.getReceipt(ctx.workspace.id, run.id),
+            };
+        }
+        const finalized = this.store.finalizeRun({
+            workspaceId: ctx.workspace.id,
+            runId: run.id,
+            status: "cancelled",
+            output: { cancelledBy: ctx.actorId },
+            error: "Cancelled by operator",
+            actionsMetered: 0,
+            creditsMetered: 0,
+            durationMs: Date.now() - new Date(run.startedAt).getTime(),
+        });
+        return finalized;
+    }
+    // 18. get_receipt
+    getReceipt(ctx, receiptOrRunId) {
+        const receipt = this.store.getReceipt(ctx.workspace.id, receiptOrRunId);
+        if (!receipt) {
+            throw new Error(`Receipt '${receiptOrRunId}' not found in workspace.`);
+        }
+        const signatureValid = this.store.verifyReceipt(receipt);
+        const governanceSignatureValid = receipt.decisionRecord
+            ? this.governance.verifyDecisionRecord(receipt.decisionRecord)
+            : true;
+        return { receipt, signatureValid, governanceSignatureValid };
+    }
+    // 19. Natural Language Router & End-to-End Executor (`muxo do` / `POST /api/v1/do`)
+    async doNaturalLanguage(ctx, params) {
+        const allTools = await this.listAllCatalogTools();
+        const byokEnv = this.store.getDecryptedWorkspaceEnv(ctx.workspace.id);
+        const activeConns = new Set(this.store
+            .listConnections(ctx.workspace.id)
+            .filter((c) => c.status === "active")
+            .map((c) => c.providerSlug.toLowerCase()));
+        const resolution = await resolveNaturalLanguageIntent({
+            prompt: params.prompt,
+            tools: allTools,
+            explicitInput: params.input,
+            byokKeys: byokEnv,
+            activeConnectionProviders: activeConns,
+        });
+        if (!resolution.resolved || !resolution.tool) {
+            return {
+                ok: false,
+                executed: false,
+                status: "unresolved",
+                intent: resolution,
+                resolution,
+                byokPrompt: {
+                    needed: !byokEnv.OPENAI_API_KEY && !byokEnv.ANTHROPIC_API_KEY && !byokEnv.OPENROUTER_API_KEY,
+                    provider: "openai",
+                    envVarName: "OPENAI_API_KEY",
+                    cliCommand: "muxo byok set openai <sk-...>",
+                    message: "Tip: Add an OpenAI, Anthropic, or OpenRouter BYOK key (`muxo byok set openai <key>`) for unrestricted natural-language LLM routing.",
+                },
+                humanMessage: resolution.humanSummary,
+            };
+        }
+        if (resolution.missingInputs.length > 0) {
+            return {
+                ok: false,
+                executed: false,
+                status: "missing_inputs",
+                intent: resolution,
+                resolution,
+                humanMessage: `Matched ${resolution.tool.name} (${resolution.tool.slug}), but missing required parameter(s): ${resolution.missingInputs.join(", ")}. Please include them in your request.`,
+            };
+        }
+        const planned = await this.planAction(ctx, {
+            toolSlug: resolution.tool.slug,
+            input: resolution.input,
+            reason: params.prompt,
+        });
+        if (planned.authHandoff?.required) {
+            return {
+                ok: false,
+                executed: false,
+                status: "awaiting_oauth_connection",
+                intent: resolution,
+                resolution,
+                plan: planned.plan,
+                authHandoff: planned.authHandoff,
+                humanMessage: planned.authHandoff.instructions,
+            };
+        }
+        if (params.dryRun || params.planOnly) {
+            return {
+                ok: true,
+                executed: false,
+                status: "planned_dry_run",
+                intent: resolution,
+                resolution,
+                plan: planned.plan,
+                humanMessage: `Planned ${planned.tool.name} (${planned.plan.id}) with risk=${planned.plan.riskLevel} and cost=${planned.plan.creditCost} credits.`,
+            };
+        }
+        let currentPlan = planned.plan;
+        if (currentPlan.approvalStatus === "pending_approval" &&
+            params.autoApprove !== false) {
+            currentPlan = this.approvePlan(ctx, currentPlan.id, "approved");
+        }
+        if (currentPlan.approvalStatus === "pending_approval") {
+            return {
+                ok: true,
+                executed: false,
+                status: "awaiting_approval",
+                intent: resolution,
+                resolution,
+                plan: currentPlan,
+                humanMessage: `Plan ${currentPlan.id} (${currentPlan.toolSlug}, risk=${currentPlan.riskLevel}) requires owner approval. Run 'muxo approve ${currentPlan.id}' or pass --yes to auto-approve.`,
+            };
+        }
+        const executed = await this.executePlanForRisk(ctx, currentPlan.id, currentPlan.riskLevel);
+        const isSuccess = executed.run.status === "succeeded";
+        return {
+            ok: isSuccess,
+            executed: isSuccess,
+            status: "executed",
+            intent: resolution,
+            resolution,
+            plan: currentPlan,
+            run: executed.run,
+            receipt: executed.receipt,
+            humanMessage: isSuccess
+                ? `Completed ${resolution.tool.name} (${resolution.tool.slug}) in ${executed.run.durationMs ?? 0}ms [receipt: ${executed.receipt.id}, funding: ${executed.receipt.supplierSettlement?.fundingMode || "muxo_funded"}].`
+                : `Execution of ${resolution.tool.slug} failed: ${executed.run.error || "Unknown error"}`,
+        };
+    }
+}