@muxoai/platform 1.2.2 → 1.3.0

package/dist/engine.js

@@ -1,3 +1,4 @@
+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";
@@ -26,6 +27,9 @@ export class MuxoEngine {
     // 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,
@@ -76,6 +80,14 @@ export class MuxoEngine {
         }
         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)
@@ -85,9 +97,22 @@ export class MuxoEngine {
             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;
@@ -343,15 +368,40 @@ export class MuxoEngine {
     // 7. plan_action
     async planAction(ctx, params) {
         const ws = this.store.getWorkspace(ctx.workspace.id);
-        const tool = await this.inspectTool(params.toolSlug);
+        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 (tool.creditCost > ws.creditsBalance) {
-            throw new Error(`Insufficient workspace credits for ${tool.slug} (requires ${tool.creditCost}, available ${ws.creditsBalance}). Top up credits or upgrade plan.`);
+        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 (tool.creditCost > ws.policy.maxCreditsPerRun) {
-            throw new Error(`Tool credit cost (${tool.creditCost}) exceeds workspace policy maxCreditsPerRun (${ws.policy.maxCreditsPerRun}).`);
+        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
@@ -359,14 +409,14 @@ export class MuxoEngine {
             workspace: ws,
             actorId: ctx.actorId,
             tool,
-            input: params.input || {},
-            reason: params.reason || `Planned execution of ${tool.slug}`,
+            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} ${params.reason || ""}`.trim();
+        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" &&
@@ -381,9 +431,9 @@ export class MuxoEngine {
             upstreamSlug: tool.upstreamSlug,
             lane: tool.lane,
             riskLevel: tool.riskLevel,
-            input: params.input || {},
-            reason: params.reason || `Planned execution of ${tool.slug}`,
-            creditCost: tool.creditCost,
+            input: resolvedInput,
+            reason: resolvedReason,
+            creditCost: effectiveCreditCost,
             approvalStatus,
             decisionRecord,
             memoryContext,
@@ -555,11 +605,40 @@ export class MuxoEngine {
         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.lane === "composio_instant") {
+            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,
@@ -567,25 +646,11 @@ export class MuxoEngine {
                 });
             }
             else if (plan.lane === "composio_sdk") {
-                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");
-                }
                 output = await this.composioSdk.executeTool({
                     workspaceId: ctx.workspace.id,
                     tool,
                     input: plan.input,
-                    connectedAccountId: activeConn?.externalAccountId || null,
+                    connectedAccountId: activeConnId,
                 });
             }
             else if (plan.lane === "stripe_projects") {
@@ -706,4 +771,106 @@ export class MuxoEngine {
             : 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"}`,
+        };
+    }
 }

package/dist/mcp.d.ts

@@ -1,9 +1,45 @@
 import type { ExecutionContext, MuxoEngine } from "./engine.js";
+export interface McpToolAnnotations {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    openWorldHint: boolean;
+}
 export interface McpToolDefinition {
     name: string;
+    title: string;
     description: string;
     inputSchema: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    annotations: McpToolAnnotations;
+    _meta?: Record<string, unknown>;
 }
+/**
+ * Concise server instructions (<512 chars) per OpenAI Plugin MCP Server specification:
+ * https://developers.openai.com/plugins/build/mcp-server
+ */
+export declare const MUXO_MCP_SERVER_INSTRUCTIONS = "Muxo governs SaaS actions (Composio app.*), Instant tools (instant.*), Cloud Infrastructure (Stripe Projects resource.*), Supermemory v5 recall, and Microsoft Agent Governance Ed25519 receipts. Workflow: 1) search_tools & inspect_tool. 2) plan_action to get a plan_*. 3) If authHandoff.required is true, show redirectUrl and call wait_for_connection. 4) Execute via the matching risk tool (execute_read/write/admin/financial/provisioning/destructive). 5) Verify via get_receipt.";
 export declare const MUXO_MCP_TOOLS: McpToolDefinition[];
+/**
+ * OpenAI Company Knowledge standard `search` and `fetch` tool definitions
+ * per https://developers.openai.com/plugins/build/mcp-server#company-knowledge-compatibility
+ */
+export declare const OPENAI_COMPANY_KNOWLEDGE_TOOLS: McpToolDefinition[];
+export interface McpSkillFileEntry {
+    path: string;
+    uri: string;
+    size: number;
+    digest: string;
+    mimeType: string;
+    content: string;
+}
+export interface McpSkillBundle {
+    name: string;
+    description: string;
+    uri: string;
+    version: string;
+    frontmatter: Record<string, string>;
+    files: McpSkillFileEntry[];
+}
+export declare function getMuxoMcpSkills(): McpSkillBundle[];
 export declare function dispatchMcpToolCall(engine: MuxoEngine, ctx: ExecutionContext, toolName: string, args?: Record<string, unknown>): Promise<unknown>;
 export declare function handleJsonRpcMcpRequest(engine: MuxoEngine, ctx: ExecutionContext, rpc: Record<string, unknown>): Promise<Record<string, unknown> | null>;