@muxoai/sdk 1.4.3 → 1.4.4

package/dist/policy.js

@@ -1436,6 +1436,65 @@ export function buildLlmPolicyAndGovernanceBrief(policy = DEFAULT_WORKSPACE_POLI
                     prompt: "Remember our default GitHub repo is muxo-ai/muxo",
                 },
             },
+            {
+                intent: "Run a turnkey or custom Temporal Saga playbook (or pass plain English in prompt)",
+                mcpTool: "get_run_context",
+                arguments: {
+                    action: "run_playbook",
+                    slug: "fullstack-cloud-bootstrap",
+                    prompt: "Run the fullstack cloud bootstrap playbook for acme",
+                },
+            },
+            {
+                intent: "Create a custom multi-step Saga playbook in plain English",
+                mcpTool: "get_run_context",
+                arguments: {
+                    action: "create_playbook",
+                    prompt: "Create playbook daily-growth-check that runs instant.seo.audit and app.slack.send_message",
+                },
+            },
+            {
+                intent: "Rollback or signal a Temporal workflow Saga in plain English",
+                mcpTool: "get_run_context",
+                arguments: {
+                    action: "rollback_workflow",
+                    workflow_id: "latest",
+                    prompt: "Rollback the latest workflow because staging healthcheck failed",
+                },
+            },
+            {
+                intent: "Time-travel or k-hop BFS traverse the Graphiti Bi-Temporal Knowledge Graph",
+                mcpTool: "get_run_context",
+                arguments: {
+                    action: "memory_graph",
+                    as_of: "2026-10-20T00:00:00Z",
+                    focal_entity: "workspace",
+                    max_hops: 2,
+                },
+            },
+            {
+                intent: "Compile or evaluate AWS Cedar 4.0 & OPA Rego v1 Policy-as-Code",
+                mcpTool: "get_run_context",
+                arguments: {
+                    action: "cedar_policy",
+                    tool_slug: "resource.turso.database",
+                    input: { query: "SELECT 1" },
+                },
+            },
+            {
+                intent: "Export OpenTelemetry GenAI 1.29.0 spans, Langfuse batch, or FinOps ROI",
+                mcpTool: "get_run_context",
+                arguments: { action: "roi_analytics" },
+            },
+            {
+                intent: "One-shot configure a turnkey harness preset (startup-builder, strict-production, read-only-auditor, finops-byok-zero-cost)",
+                mcpTool: "get_run_context",
+                arguments: {
+                    action: "configure_harness",
+                    preset: "strict-production",
+                    harness: "claude-code",
+                },
+            },
         ],
     };
 }

package/dist/providers/composio-instant.js

@@ -1,5 +1,6 @@
 import vm from "node:vm";
 import { Composio } from "@composio/core";
+import { callComposioMcpGatewayRpc } from "../composio-catalog.js";
 const INSTANT_TOOLS = [
     {
         slug: "instant.web.search",
@@ -1024,44 +1025,61 @@ export class ComposioInstantAdapter {
                 };
                 let evalResult = null;
                 let executionEngine = "cloudflare_sandbox_vm_isolate";
-                try {
-                    const sandboxContext = vm.createContext({
-                        Math,
-                        Date,
-                        JSON,
-                        Array,
-                        Object,
-                        String,
-                        Number,
-                        Boolean,
-                        RegExp,
-                        Map,
-                        Set,
-                        Buffer: {
-                            from: (str, enc) => Buffer.from(str, enc),
-                        },
-                        env: Object.freeze({ ...vaultBindings }),
-                        console: {
-                            log: (...args) => logs.push(redactSecrets(args.map((a) => String(a)).join(" "))),
-                            info: (...args) => logs.push(redactSecrets(args.map((a) => String(a)).join(" "))),
-                        },
-                    });
-                    const wrappedCode = code.includes("return ") && !code.trim().startsWith("(")
-                        ? `(() => { ${code} })()`
-                        : code;
-                    const rawOut = vm.runInContext(wrappedCode, sandboxContext, {
-                        timeout: 1500,
+                if (input.useRemoteWorkbench === true && this.config.composioApiKey) {
+                    const gwRes = await callComposioMcpGatewayRpc("COMPOSIO_REMOTE_WORKBENCH", {
+                        code_to_execute: code,
+                        thought: String(input.thought || "Muxo governed workbench execution"),
+                    }, {
+                        apiKey: this.config.composioApiKey,
+                        gatewayUrl: this.config.composioMcpGatewayUrl,
+                        isReadOnly: false,
+                        timeoutMs: 8000,
                     });
-                    evalResult =
-                        typeof rawOut === "string"
-                            ? redactSecrets(rawOut)
-                            : rawOut !== undefined
-                                ? JSON.parse(redactSecrets(JSON.stringify(rawOut)))
-                                : null;
+                    if (gwRes.ok && gwRes.data) {
+                        executionEngine = "composio_remote_workbench";
+                        evalResult = JSON.parse(redactSecrets(JSON.stringify(gwRes.data)));
+                    }
                 }
-                catch (err) {
-                    executionEngine = "isolated_workbench_ast_guard";
-                    evalResult = redactSecrets(String(err?.message || "Completed expression analysis"));
+                if (evalResult === null) {
+                    try {
+                        const sandboxContext = vm.createContext({
+                            Math,
+                            Date,
+                            JSON,
+                            Array,
+                            Object,
+                            String,
+                            Number,
+                            Boolean,
+                            RegExp,
+                            Map,
+                            Set,
+                            Buffer: {
+                                from: (str, enc) => Buffer.from(str, enc),
+                            },
+                            env: Object.freeze({ ...vaultBindings }),
+                            console: {
+                                log: (...args) => logs.push(redactSecrets(args.map((a) => String(a)).join(" "))),
+                                info: (...args) => logs.push(redactSecrets(args.map((a) => String(a)).join(" "))),
+                            },
+                        });
+                        const wrappedCode = code.includes("return ") && !code.trim().startsWith("(")
+                            ? `(() => { ${code} })()`
+                            : code;
+                        const rawOut = vm.runInContext(wrappedCode, sandboxContext, {
+                            timeout: 1500,
+                        });
+                        evalResult =
+                            typeof rawOut === "string"
+                                ? redactSecrets(rawOut)
+                                : rawOut !== undefined
+                                    ? JSON.parse(redactSecrets(JSON.stringify(rawOut)))
+                                    : null;
+                    }
+                    catch (err) {
+                        executionEngine = "isolated_workbench_ast_guard";
+                        evalResult = redactSecrets(String(err?.message || "Completed expression analysis"));
+                    }
                 }
                 return {
                     provider: "composio_instant",

package/dist/providers/composio-sdk.d.ts

@@ -1,7 +1,7 @@
 import { Composio } from "@composio/core";
 import type { MuxoConfig } from "../config.js";
 import type { MuxoTool, RiskLevel } from "../types.js";
-import { parseComposioWebhookEnvelope, type ComposioToolkitMetadata, type ComposioTriggerEventRecord, type ComposioTriggerSubscription, type ComposioTriggerType, type ComposioWebhookEventType } from "../composio-catalog.js";
+import { parseComposioWebhookEnvelope, type ComposioMcpGatewayMetaTool, type ComposioMcpGatewayResult, type ComposioToolkitMetadata, type ComposioTriggerEventRecord, type ComposioTriggerSubscription, type ComposioTriggerType, type ComposioWebhookEventType } from "../composio-catalog.js";
 export type { ComposioToolkitMetadata, ComposioTriggerEventRecord, ComposioTriggerSubscription, ComposioTriggerType, ComposioWebhookEventType, };
 export declare class ComposioSdkAdapter {
     private readonly config;
@@ -16,12 +16,20 @@ export declare class ComposioSdkAdapter {
     private get headers();
     private getHeaders;
     getComposioClient(composioApiKey?: string | null): Composio | null;
+    callComposioMcpGateway(metaTool: ComposioMcpGatewayMetaTool | string, toolArgs: Record<string, unknown>, options?: {
+        workspaceId?: string;
+        composioApiKey?: string | null;
+        gatewayUrl?: string | null;
+        isReadOnly?: boolean;
+        timeoutMs?: number;
+    }): Promise<ComposioMcpGatewayResult>;
     getSdkInfo(composioApiKey?: string | null): {
         sdkPackage: "@composio/core";
         sdkVersion: string;
         configured: boolean;
         usingCustomerByok: boolean;
         baseUrl: string;
+        mcpGatewayUrl: string;
         curatedToolCount: number;
         cachedToolCount: number;
         capabilities: string[];
@@ -158,5 +166,6 @@ export declare class ComposioSdkAdapter {
         input: Record<string, unknown>;
         connectedAccountId?: string | null;
         composioApiKey?: string | null;
+        mcpGatewayUrl?: string | null;
     }): Promise<Record<string, unknown>>;
 }

package/dist/providers/composio-sdk.js

@@ -1,6 +1,6 @@
 import { Composio } from "@composio/core";
 import { matchAppToolSlug } from "../mcp-schema.js";
-import { composioAuthConfigScopes, COMPOSIO_V3_WEBHOOK_EVENTS, ensureOAuthCallbackParams, ENTERPRISE_TOOLKITS_CATALOG, filterComposioToolkits, getComposioTriggerType, getSampleActionSchema, isStripeProjectsExclusiveProvider, listComposioTriggerTypes, parseComposioWebhookEnvelope, verifyComposioWebhookSignature, wrapMuxoConnectUrl, } from "../composio-catalog.js";
+import { callComposioMcpGatewayRpc, canUseComposioMcpGatewayForExecution, composioAuthConfigScopes, COMPOSIO_V3_WEBHOOK_EVENTS, ensureOAuthCallbackParams, ENTERPRISE_TOOLKITS_CATALOG, filterComposioToolkits, getComposioTriggerType, getSampleActionSchema, isStripeProjectsExclusiveProvider, listComposioTriggerTypes, parseComposioWebhookEnvelope, verifyComposioWebhookSignature, wrapMuxoConnectUrl, } from "../composio-catalog.js";
 const CURATED_APP_TOOLS = [
     {
         slug: "app.github.list_repos",
@@ -468,6 +468,20 @@ export class ComposioSdkAdapter {
             return null;
         }
     }
+    async callComposioMcpGateway(metaTool, toolArgs, options) {
+        const apiKey = this.resolveApiKey(options?.composioApiKey);
+        const gatewayUrl = options?.gatewayUrl ||
+            this.config.composioMcpGatewayUrl ||
+            "https://connect.composio.dev/mcp";
+        return callComposioMcpGatewayRpc(metaTool, toolArgs, {
+            apiKey,
+            gatewayUrl,
+            workspaceId: options?.workspaceId,
+            usingCustomerByok: Boolean(options?.composioApiKey && options.composioApiKey.trim()),
+            isReadOnly: options?.isReadOnly,
+            timeoutMs: options?.timeoutMs,
+        });
+    }
     getSdkInfo(composioApiKey) {
         const apiKey = this.resolveApiKey(composioApiKey);
         return {
@@ -476,6 +490,7 @@ export class ComposioSdkAdapter {
             configured: Boolean(apiKey),
             usingCustomerByok: Boolean(composioApiKey && composioApiKey.trim()),
             baseUrl: this.config.composioBaseUrl,
+            mcpGatewayUrl: this.config.composioMcpGatewayUrl || "https://connect.composio.dev/mcp",
             curatedToolCount: CURATED_APP_TOOLS.length,
             cachedToolCount: this.liveToolsCache.size,
             capabilities: [
@@ -491,6 +506,11 @@ export class ComposioSdkAdapter {
                 "triggers.create",
                 "triggers.subscribe",
                 "triggers.verifyWebhook",
+                "mcpGateway.COMPOSIO_SEARCH_TOOLS",
+                "mcpGateway.COMPOSIO_GET_TOOL_SCHEMAS",
+                "mcpGateway.COMPOSIO_MANAGE_CONNECTIONS",
+                "mcpGateway.COMPOSIO_MULTI_EXECUTE_TOOL",
+                "mcpGateway.COMPOSIO_REMOTE_WORKBENCH",
             ],
         };
     }
@@ -901,6 +921,33 @@ export class ComposioSdkAdapter {
                     merged.set(tool.slug, tool);
                 }
             }
+            if (merged.size === 0 &&
+                q &&
+                canUseComposioMcpGatewayForExecution({
+                    apiKey,
+                    gatewayUrl: this.config.composioMcpGatewayUrl,
+                    usingCustomerByok: Boolean(composioApiKey),
+                    isReadOnly: false,
+                })) {
+                const gwSearch = await this.callComposioMcpGateway("COMPOSIO_SEARCH_TOOLS", {
+                    queries: [
+                        {
+                            use_case: tk ? `${tk}: ${q}` : q,
+                            ...(tk ? { known_fields: `toolkit:${tk}` } : {}),
+                        },
+                    ],
+                    session: { generate_id: true },
+                }, { composioApiKey, isReadOnly: true, timeoutMs: 3500 });
+                const gwTools = Array.isArray(gwSearch.data?.tools)
+                    ? gwSearch.data?.tools
+                    : [];
+                for (const gwItem of gwTools) {
+                    const tool = this.mapRawComposioItemToMuxoTool(gwItem);
+                    if (tool && !merged.has(tool.slug)) {
+                        merged.set(tool.slug, tool);
+                    }
+                }
+            }
             return Array.from(merged.values()).slice(0, limit);
         }
         catch {
@@ -935,7 +982,23 @@ export class ComposioSdkAdapter {
                     }
                 }
                 catch {
-                    // Fall through to searchTools
+                    // Fall through to MCP Gateway schema lookup / searchTools
+                }
+            }
+            if (canUseComposioMcpGatewayForExecution({
+                apiKey,
+                gatewayUrl: this.config.composioMcpGatewayUrl,
+                usingCustomerByok: Boolean(composioApiKey),
+                isReadOnly: false,
+            })) {
+                const gwSchema = await this.callComposioMcpGateway("COMPOSIO_GET_TOOL_SCHEMAS", { tool_slugs: [upstreamCandidate] }, { composioApiKey, isReadOnly: true, timeoutMs: 3000 });
+                const schemaList = Array.isArray(gwSchema.data?.tools)
+                    ? gwSchema.data?.tools
+                    : [];
+                if (schemaList[0]) {
+                    const mapped = this.mapRawComposioItemToMuxoTool(schemaList[0]);
+                    if (mapped)
+                        return mapped;
                 }
             }
         }
@@ -1331,10 +1394,57 @@ export class ComposioSdkAdapter {
         if (!effectiveApiKey) {
             return buildConnectedAccountFallback();
         }
-        // 1. Official @composio/core SDK tool execution
-        const sdk = this.getComposioClient(params.composioApiKey);
+        const isReadOnly = params.tool.riskLevel === "read";
+        const gatewayUrl = params.mcpGatewayUrl ||
+            this.config.composioMcpGatewayUrl ||
+            "https://connect.composio.dev/mcp";
+        const preferMcpGateway = Boolean(params.mcpGatewayUrl) ||
+            effectiveApiKey.startsWith("ck_") ||
+            gatewayUrl.includes("mcp.composio.dev/t/");
+        let writeTierAttempted = false;
+        // Tier 1: Upstream Composio MCP Gateway (when BYOK consumer/team gateway is configured, or read-only)
+        if (preferMcpGateway &&
+            canUseComposioMcpGatewayForExecution({
+                apiKey: effectiveApiKey,
+                gatewayUrl,
+                usingCustomerByok: Boolean(params.composioApiKey),
+                isReadOnly,
+            })) {
+            if (!isReadOnly)
+                writeTierAttempted = true;
+            const gwExec = await this.callComposioMcpGateway("COMPOSIO_MULTI_EXECUTE_TOOL", {
+                tools: [
+                    {
+                        tool_slug: params.tool.upstreamSlug,
+                        arguments: params.input,
+                    },
+                ],
+                sync_response_to_workbench: false,
+            }, {
+                workspaceId: params.workspaceId,
+                composioApiKey: params.composioApiKey,
+                gatewayUrl,
+                isReadOnly,
+                timeoutMs: 20000,
+            });
+            if (gwExec.ok && gwExec.data) {
+                return {
+                    provider: "composio_sdk",
+                    sdk: "composio_mcp_gateway",
+                    gatewayUrl: gwExec.gatewayUrl,
+                    tool: params.tool.slug,
+                    upstreamTool: params.tool.upstreamSlug,
+                    connectedAccountId: params.connectedAccountId,
+                    data: gwExec.data,
+                };
+            }
+        }
+        // Tier 2: Official @composio/core SDK tool execution (skip if a non-idempotent write was already attempted)
+        const sdk = !writeTierAttempted ? this.getComposioClient(params.composioApiKey) : null;
         if (sdk) {
             try {
+                if (!isReadOnly)
+                    writeTierAttempted = true;
                 const sdkExec = await Promise.race([
                     sdk.tools.execute(params.tool.upstreamSlug, {
                         userId: params.workspaceId,
@@ -1359,36 +1469,39 @@ export class ComposioSdkAdapter {
                 }
             }
             catch {
-                // Fall through to direct v3 REST execute
+                // Only fall through to REST v3 for read-only calls; never double-submit writes
             }
         }
-        const body = {
-            user_id: params.workspaceId,
-            arguments: params.input,
-        };
-        if (params.connectedAccountId && params.connectedAccountId.startsWith("ca_")) {
-            body.connected_account_id = params.connectedAccountId;
-        }
-        try {
-            const res = await fetch(`${this.config.composioBaseUrl}/tools/execute/${encodeURIComponent(params.tool.upstreamSlug)}`, {
-                method: "POST",
-                headers: this.getHeaders(params.composioApiKey),
-                body: JSON.stringify(body),
-                signal: AbortSignal.timeout(25000),
-            });
-            const payload = (await res.json().catch(() => ({})));
-            if (res.ok && !payload.error && payload.successful !== false) {
-                return {
-                    provider: "composio_sdk",
-                    tool: params.tool.slug,
-                    upstreamTool: params.tool.upstreamSlug,
-                    connectedAccountId: params.connectedAccountId,
-                    data: payload.data ?? payload,
-                };
+        // Tier 3: Composio v3 REST API (skip if a non-idempotent write was already attempted in Tier 1/2)
+        if (!writeTierAttempted) {
+            const body = {
+                user_id: params.workspaceId,
+                arguments: params.input,
+            };
+            if (params.connectedAccountId && params.connectedAccountId.startsWith("ca_")) {
+                body.connected_account_id = params.connectedAccountId;
+            }
+            try {
+                const res = await fetch(`${this.config.composioBaseUrl}/tools/execute/${encodeURIComponent(params.tool.upstreamSlug)}`, {
+                    method: "POST",
+                    headers: this.getHeaders(params.composioApiKey),
+                    body: JSON.stringify(body),
+                    signal: AbortSignal.timeout(25000),
+                });
+                const payload = (await res.json().catch(() => ({})));
+                if (res.ok && !payload.error && payload.successful !== false) {
+                    return {
+                        provider: "composio_sdk",
+                        tool: params.tool.slug,
+                        upstreamTool: params.tool.upstreamSlug,
+                        connectedAccountId: params.connectedAccountId,
+                        data: payload.data ?? payload,
+                    };
+                }
+            }
+            catch {
+                // Fall through to connected account execution result when callback handoff was completed via Muxo /oauth/callback
             }
-        }
-        catch {
-            // Fall through to connected account execution result when callback handoff was completed via Muxo /oauth/callback
         }
         return buildConnectedAccountFallback();
     }

package/dist/sdk.d.ts

@@ -246,6 +246,7 @@ export declare class MuxoClient {
         run: ExecutionRun;
         receipt: ExecutionReceipt;
     }>;
+    reconcileRun(runOrPlanId: string): Promise<Record<string, unknown>>;
     exec(toolSlug: string, input?: Record<string, unknown>, options?: {
         reason?: string;
         approve?: boolean;
@@ -969,6 +970,24 @@ export declare class MuxoClient {
     }): Promise<Record<string, unknown>>;
     getOtelTraces(limit?: number): Promise<Record<string, unknown>>;
     listPlaybooks(): Promise<Record<string, unknown>>;
+    createPlaybook(params: {
+        prompt?: string;
+        slug?: string;
+        name?: string;
+        steps?: Array<string | Record<string, unknown>>;
+        [key: string]: unknown;
+    }): Promise<Record<string, unknown>>;
     runPlaybook(slug: string, input?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    configureHarness(params?: {
+        preset?: string;
+        harness?: string;
+        prompt?: string;
+    }): Promise<Record<string, unknown>>;
     getRoiAnalytics(): Promise<Record<string, unknown>>;
+    listSkills(filter?: {
+        category?: string;
+        provider?: string;
+        query?: string;
+    }): Promise<Record<string, unknown>>;
+    getSkill(slug: string): Promise<Record<string, unknown>>;
 }

package/dist/sdk.js

@@ -189,6 +189,9 @@ export class MuxoClient {
             body: reason ? { reason } : {},
         });
     }
+    async reconcileRun(runOrPlanId) {
+        return this.request(`/api/v1/runs/${encodeURIComponent(runOrPlanId)}/reconcile`);
+    }
     async exec(toolSlug, input = {}, options = {}) {
         const planned = await this.planAction({
             toolSlug,
@@ -787,13 +790,42 @@ export class MuxoClient {
     async listPlaybooks() {
         return this.request("/api/v1/playbooks");
     }
+    async createPlaybook(params) {
+        return this.request("/api/v1/playbooks", {
+            method: "POST",
+            body: params,
+        });
+    }
     async runPlaybook(slug, input) {
         return this.request(`/api/v1/playbooks/${encodeURIComponent(slug)}/run`, {
             method: "POST",
             body: { input: input || {} },
         });
     }
+    async configureHarness(params) {
+        if (!params || Object.keys(params).length === 0) {
+            return this.request("/api/v1/harness/configure");
+        }
+        return this.request("/api/v1/harness/configure", {
+            method: "POST",
+            body: params,
+        });
+    }
     async getRoiAnalytics() {
         return this.request("/api/v1/analytics/roi");
     }
+    async listSkills(filter) {
+        const qs = new URLSearchParams();
+        if (filter?.category)
+            qs.set("category", filter.category);
+        if (filter?.provider)
+            qs.set("provider", filter.provider);
+        if (filter?.query)
+            qs.set("q", filter.query);
+        const suffix = qs.toString() ? `?${qs.toString()}` : "";
+        return this.request(`/api/v1/skills${suffix}`);
+    }
+    async getSkill(slug) {
+        return this.request(`/api/v1/skills/${encodeURIComponent(slug)}`);
+    }
 }