@muxoai/platform 1.2.3 → 1.3.1

package/dist/engine.d.ts

@@ -1,4 +1,5 @@
 import type { MuxoConfig } from "./config.js";
+import { type NaturalLanguageResolution } from "./nl.js";
 import { ComposioInstantAdapter } from "./providers/composio-instant.js";
 import { ComposioSdkAdapter } from "./providers/composio-sdk.js";
 import { MicrosoftGovernanceAdapter } from "./providers/microsoft-governance.js";
@@ -34,6 +35,7 @@ export declare class MuxoEngine {
         tools: MuxoTool[];
         total: number;
     }>;
+    listAllCatalogTools(): Promise<MuxoTool[]>;
     inspectTool(slug: string): Promise<MuxoTool>;
     connectionStatus(ctx: ExecutionContext, params?: {
         provider?: string;
@@ -93,6 +95,7 @@ export declare class MuxoEngine {
     }>;
     getPlan(ctx: ExecutionContext, planId: string): ActionPlan;
     approvePlan(ctx: ExecutionContext, planId: string, decision?: "approved" | "rejected"): ActionPlan;
+    private enrichMemoryContext;
     getRunContext(ctx: ExecutionContext, query?: string): Promise<Record<string, unknown>>;
     getMemoryOverview(ctx: ExecutionContext, query?: string): Promise<{
         enabled: boolean;
@@ -125,4 +128,30 @@ export declare class MuxoEngine {
         signatureValid: boolean;
         governanceSignatureValid: boolean;
     };
+    doNaturalLanguage(ctx: ExecutionContext, params: {
+        prompt: string;
+        input?: Record<string, unknown>;
+        autoApprove?: boolean;
+        dryRun?: boolean;
+        planOnly?: boolean;
+        fundingMode?: "muxo_funded" | "byok";
+    }): Promise<{
+        ok: boolean;
+        executed: boolean;
+        status: "executed" | "planned_dry_run" | "awaiting_approval" | "awaiting_oauth_connection" | "missing_inputs" | "unresolved";
+        intent: NaturalLanguageResolution;
+        resolution: NaturalLanguageResolution;
+        plan?: ActionPlan;
+        run?: ExecutionRun;
+        receipt?: ExecutionReceipt;
+        authHandoff?: Record<string, unknown>;
+        byokPrompt?: {
+            needed: boolean;
+            provider: string;
+            envVarName: string;
+            cliCommand: string;
+            message: string;
+        };
+        humanMessage: string;
+    }>;
 }

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";
@@ -25,10 +26,14 @@ export class MuxoEngine {
     }
     // 1. get_profile
     getProfile(ctx) {
+        const nickname = (ctx.user.email || "").split("@")[0] ||
+            ctx.user.name.toLowerCase().replace(/\s+/g, ".") ||
+            ctx.user.id;
         return {
             id: ctx.user.id,
             name: ctx.user.name,
             email: ctx.user.email,
+            nickname,
             user: ctx.user,
             actorId: ctx.actorId,
             authType: ctx.authType,
@@ -79,6 +84,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)
@@ -88,9 +101,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;
@@ -346,15 +372,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
@@ -362,15 +413,15 @@ 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 memoryContext = await this.supermemory.getContextForWorkspace(ws.id, memoryQuery);
+        const memoryQuery = `${tool.slug} ${tool.name} ${resolvedReason}`.trim();
+        const memoryContext = await this.enrichMemoryContext(ws.id, await this.supermemory.getContextForWorkspace(ws.id, memoryQuery));
         const requiresHumanApproval = decisionRecord.verdict === "escalate" ||
             (ws.policy.mode === "enforce" &&
                 ws.policy.requireApprovalFor.includes(tool.riskLevel));
@@ -384,9 +435,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,
@@ -459,6 +510,38 @@ export class MuxoEngine {
             approvedBy: ctx.user.email,
         });
     }
+    async enrichMemoryContext(workspaceId, ctx) {
+        if (ctx.recalledMemories.length > 0 && ctx.staticFacts.length > 0) {
+            return ctx;
+        }
+        const localRecords = this.store.listMemoryRecords(workspaceId, 8);
+        if (localRecords.length === 0)
+            return ctx;
+        const recalled = ctx.recalledMemories.length > 0
+            ? ctx.recalledMemories
+            : localRecords.slice(0, 5).map((r) => ({
+                documentId: r.documentId,
+                title: r.title,
+                snippet: r.content.slice(0, 240),
+                similarity: 1,
+            }));
+        const staticFacts = ctx.staticFacts.length > 0
+            ? ctx.staticFacts
+            : localRecords
+                .filter((r) => r.kind === "fact" || r.kind === "preference")
+                .slice(0, 5)
+                .map((r) => `${r.title}: ${r.content.slice(0, 140)}`);
+        return {
+            ...ctx,
+            staticFacts,
+            recalledMemories: recalled,
+            relevantMemories: recalled,
+            profile: {
+                ...ctx.profile,
+                static: staticFacts,
+            },
+        };
+    }
     // 9. get_run_context
     async getRunContext(ctx, query) {
         const ws = this.store.getWorkspace(ctx.workspace.id);
@@ -469,7 +552,7 @@ export class MuxoEngine {
             redactedEnv[k] =
                 v.length > 8 ? `${v.slice(0, 4)}••••${v.slice(-3)}` : "••••••••";
         }
-        const memoryContext = await this.supermemory.getContextForWorkspace(ws.id, query);
+        const memoryContext = await this.enrichMemoryContext(ws.id, await this.supermemory.getContextForWorkspace(ws.id, query));
         return {
             workspaceId: ws.id,
             workspaceSlug: ws.slug,
@@ -486,7 +569,7 @@ export class MuxoEngine {
     }
     // Supermemory Workspace Brain Operations
     async getMemoryOverview(ctx, query) {
-        const context = await this.supermemory.getContextForWorkspace(ctx.workspace.id, query);
+        const context = await this.enrichMemoryContext(ctx.workspace.id, await this.supermemory.getContextForWorkspace(ctx.workspace.id, query));
         const recentMemories = this.store.listMemoryRecords(ctx.workspace.id, 25);
         return {
             enabled: context.enabled,
@@ -549,6 +632,14 @@ export class MuxoEngine {
         }
         const ws = this.store.getWorkspace(ctx.workspace.id);
         const tool = await this.inspectTool(plan.toolSlug);
+        const byokActive = this.store.hasByokForLane(ws.id, tool.lane, tool.slug);
+        const effectiveCreditCost = byokActive ? 0 : plan.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 to execute plan '${plan.id}' for ${tool.slug} (requires ${effectiveCreditCost}, available ${ws.creditsBalance}). Top up credits or configure a BYOK key.`);
+        }
         const execDecisionRecord = this.governance.evaluateExecution({
             workspace: ws,
             actorId: ctx.actorId,
@@ -583,19 +674,31 @@ export class MuxoEngine {
         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") {
+                const composioByok = this.store.getByokKey(ctx.workspace.id, "composio");
                 output = await this.composioInstant.executeTool({
                     workspaceId: ctx.workspace.id,
                     tool,
                     input: plan.input,
+                    composioApiKey: composioByok,
                 });
             }
             else if (plan.lane === "composio_sdk") {
+                const composioByok = this.store.getByokKey(ctx.workspace.id, "composio");
                 output = await this.composioSdk.executeTool({
                     workspaceId: ctx.workspace.id,
                     tool,
                     input: plan.input,
                     connectedAccountId: activeConnId,
+                    composioApiKey: composioByok,
                 });
             }
             else if (plan.lane === "stripe_projects") {
@@ -622,7 +725,7 @@ export class MuxoEngine {
                 status: "succeeded",
                 output,
                 actionsMetered: 1,
-                creditsMetered: plan.creditCost,
+                creditsMetered: effectiveCreditCost,
                 durationMs,
                 decisionRecord: execDecisionRecord,
             });
@@ -716,4 +819,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

@@ -4,12 +4,17 @@ export interface McpToolAnnotations {
     destructiveHint: boolean;
     openWorldHint: boolean;
 }
+export interface McpToolSecurityScheme {
+    type: "noauth" | "oauth2";
+    scopes?: string[];
+}
 export interface McpToolDefinition {
     name: string;
     title: string;
     description: string;
     inputSchema: Record<string, unknown>;
     outputSchema?: Record<string, unknown>;
+    securitySchemes?: McpToolSecurityScheme[];
     annotations: McpToolAnnotations;
     _meta?: Record<string, unknown>;
 }
@@ -17,7 +22,7 @@ export interface McpToolDefinition {
  * 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_SERVER_INSTRUCTIONS = "Muxo governs SaaS actions (Connected Apps: app.*), Instant tools (instant.*), Cloud Infrastructure (resource.*), Workspace Memory recall, and verifiable audit records. 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