@muxoai/platform 1.2.3 → 1.3.0

package/README.md

@@ -1,19 +1,19 @@
 # Muxo (`@muxoai/platform` / `@muxoai/cli` / `@muxoai/sdk`)
 
-Muxo (`v1.2.3`) is the unified execution, cloud infrastructure provisioning, contextual memory, and cryptographic governance platform for AI agents and applications. Customers and their agents interact exclusively with **Muxo** — never with underlying tool or cloud infrastructure providers directly.
+Muxo (`v1.3.0`) is the unified execution, cloud infrastructure provisioning, contextual memory, and cryptographic governance platform for AI agents and applications. Customers and their agents interact exclusively with **Muxo** — either via structured tool slugs or free-form **Natural Language** (`muxo do`, `POST /api/v1/do`, `client.do()`, and MCP `plan_action`).
 
 See [`ARCHITECTURE.md`](./ARCHITECTURE.md) for the complete internal engineering blueprint, open-source ecosystem Keep/Adopt/Drop matrix, and 4-pillar architecture.
 
-Under the hood, Muxo unifies **four core pillars** behind one **19-operation MCP contract**, OpenAI Plugin (`agent-plugins.org/1.0.0`), REST API, CLI (`@muxoai/cli`), TypeScript SDK (`@muxoai/sdk`), and Web Console (`https://app.muxo.ai`):
+Under the hood, Muxo unifies **four core pillars** plus **Natural Language Routing** and **BYOK (Bring Your Own Key) 0-Credit Execution** behind one **19-operation MCP contract**, OpenAI Plugin (`agent-plugins.org/1.0.0`), REST API, Interactive CLI/TUI (`@muxoai/cli`), TypeScript SDK (`@muxoai/sdk`), and Web Console (`https://app.muxo.ai`):
 
 1. **Composio Connected Apps (`app.*`) & Instant (`instant.*`)** — Managed OAuth SaaS integrations (`app.github.*`, `app.gmail.*`, `app.slack.*`, `app.notion.*`, `app.linear.*`) with live browser OAuth handoff (`wait_for_connection`), zero-OAuth instant capabilities (`instant.web.search`, `instant.web.scrape`, `instant.web.crawl`, `instant.seo.audit`, `instant.hackernews.top_stories`, `instant.github.repo_intel`, `instant.dns.lookup`, `instant.composio.workbench`), plus **Autonomous 2-Call Agent Signup & Claim** (`POST /api/v1/agents/signup` + `POST /api/v1/agents/claim`).
-2. **Stripe Projects Cloud Infrastructure (`resource.*`) + Merchant-of-Record Billing (`muxo_funded`)** — Governed cloud resource provisioning across 60+ providers (`Turso`, `Neon`, `Supabase`, `Cloudflare`, `Vercel`, `Upstash`, `Resend`, `Railway`, `Render`, etc.) with automatic companion plan resolution, AES-256-GCM encrypted secret custody (`muxo env pull`), and unified credit settlement where users purchase Muxo credits and Muxo settles supplier costs from its master accounts.
+2. **Stripe Projects Cloud Infrastructure (`resource.*`) + Merchant-of-Record Billing (`muxo_funded`) & BYOK (`byok`)** — Governed cloud resource provisioning across 60+ providers (`Turso`, `Neon`, `Supabase`, `Cloudflare`, `Vercel`, `Upstash`, `Resend`, `Railway`, `Render`, etc.) with automatic companion plan resolution, AES-256-GCM encrypted secret custody (`muxo env pull`), unified credit settlement (`muxo_funded`), and **0-credit BYOK mode** (`muxo byok set <provider>`) when you bring your own supplier or LLM API keys.
 3. **Supermemory v5 Contextual Brain (`/ns/muxo-v5-*`)** — Isolated per-workspace long-term static facts, dynamic session context, and hybrid semantic search recalled before every tool plan (`plan_action` & `get_run_context`), with strict secret redaction before memory ingestion.
 4. **Microsoft Agent Governance Toolkit (`@microsoft/agent-governance-sdk` v5.0.0)** — Every planned and executed operation passes through `Agent ──► McpSecurityScanner ──► PolicyEngine ──► AgentIdentity (Ed25519 DID) ──► AuditLogger (SHA-256 chain) ──► DecisionRecord` and produces an HMAC-SHA256 verifiable receipt.
 
 ---
 
-## Install & Quickstart (External Users & Agents)
+## Install & Quickstart (Humans, Harnesses & Agents)
 
 ```bash
 # 1. Install the Muxo CLI or run directly via npx
@@ -22,17 +22,26 @@ npm install -g @muxoai/cli@latest
 # 2. Zero-browser autonomous signup (creates ~/.muxo/config.json with mk_live_* key + 250 starter credits)
 muxo login --signup --name "my-agent"
 
-# 3. Verify workspace, governance DID, and credit balance
-muxo whoami
+# 3. Launch the Interactive Terminal TUI (Natural Language bar, BYOK Vault, Billing & Status)
+muxo tui
 
-# 4. Run zero-OAuth Instant Tools (Crawl, SEO Audit, DNS, Web Search)
-muxo exec instant.seo.audit --input '{"url":"https://muxo.ai","keywords":["muxo","agent","governance"]}'
-muxo exec instant.web.crawl --input '{"url":"https://muxo.ai","maxPages":3}'
+# 4. Run tools in plain English via the Natural Language Router
+muxo do "check dns A records for muxo.ai"
+muxo do "get top 5 hacker news stories"
+muxo do "audit seo for https://muxo.ai"
 
-# 5. Connect an OAuth SaaS App (Gmail, GitHub, Slack, Notion, Linear)
-muxo link gmail --wait
+# 5. Bring Your Own Key (BYOK) for LLM routing or 0-credit supplier execution
+muxo byok set openai      # Interactive hidden/line prompt if key omitted
+muxo byok set composio    # Executes app.* and instant.* tools at 0 Muxo credit cost
+muxo byok list
+
+# 6. Manage Billing, Credits & Starter Plan ($29/mo)
+muxo billing status
+muxo billing topup 1000
+muxo billing upgrade
 
-# 6. Provision Live Cloud Infrastructure (Turso, Neon, Supabase, Upstash) & Pull Encrypted Secrets
+# 7. Connect an OAuth SaaS App & Provision Live Cloud Infrastructure
+muxo link gmail --wait
 muxo provision turso --input '{"database_name":"my-agent-db"}' --approve
 muxo env pull --out .env.muxo
 ```

package/dist/cli.js

@@ -6,7 +6,20 @@ import readline from "node:readline";
 import { getConfig } from "./config.js";
 import { MuxoEngine } from "./engine.js";
 import { handleJsonRpcMcpRequest } from "./mcp.js";
-import { MuxoStore } from "./store.js";
+import { BYOK_PROVIDER_CATALOG, MuxoStore } from "./store.js";
+function promptUserLine(question) {
+    return new Promise((resolve) => {
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stderr,
+        });
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+        rl.on("close", () => resolve(""));
+    });
+}
 function getCliConfigPath() {
     if (process.env.MUXO_CONFIG_PATH) {
         return path.resolve(process.env.MUXO_CONFIG_PATH);
@@ -64,8 +77,8 @@ async function runCli() {
     const cmd = positional[0] || "help";
     if (flags.version || flags.v || cmd === "version") {
         console.log(flags.json
-            ? JSON.stringify({ ok: true, name: "@muxoai/cli", version: "1.2.3" }, null, 2)
-            : "1.2.3");
+            ? JSON.stringify({ ok: true, name: "@muxoai/cli", version: "1.3.0" }, null, 2)
+            : "1.3.0");
         return;
     }
     const savedCliConfig = readCliAuthConfig();
@@ -209,7 +222,7 @@ async function runCli() {
     if (cmd === "harness") {
         console.log(JSON.stringify({
             ok: true,
-            version: "1.2.3",
+            version: "1.3.0",
             passed: 7,
             total: 7,
             workspaceId: ctx.workspace.id,
@@ -462,26 +475,309 @@ async function runCli() {
             }, null, 2));
             return;
         }
+        if (sub === "upgrade") {
+            const updated = store.upgradeWorkspaceToStarter({
+                workspaceId: ctx.workspace.id,
+                referenceId: `cli_upgrade_${Date.now()}`,
+                bonusCredits: 1000,
+            });
+            console.log(JSON.stringify({
+                ok: true,
+                upgraded: true,
+                tier: updated.tier,
+                monthlyActionsLimit: updated.monthlyActionsLimit,
+                creditsAdded: 1000,
+                creditsBalance: updated.creditsBalance,
+                creditBalance: updated.creditsBalance,
+                workspace: updated,
+                settlementSummary: store.getSupplierSettlementSummary(ctx.workspace.id),
+            }, null, 2));
+            return;
+        }
         if (sub === "checkout") {
             const kind = flags.kind === "starter_subscription" || positional[2] === "starter"
                 ? "starter_subscription"
                 : "credit_topup";
+            const credits = flags.credits ? Number(flags.credits) : 1000;
             const session = await engine.stripeBilling.createCheckoutSession({
                 workspace: ctx.workspace,
                 customerEmail: ctx.user.email,
                 kind,
+                credits,
                 returnBaseUrl: config.baseUrl,
             });
             console.log(JSON.stringify({ ok: true, kind, ...session }, null, 2));
             return;
         }
+        if (sub === "verify") {
+            const sessionId = positional[2] || String(flags.session || "");
+            if (!sessionId)
+                throw new Error("Usage: muxo billing verify <session_id>");
+            const verified = await engine.stripeBilling.verifyAndFulfillCheckoutSession(sessionId);
+            console.log(JSON.stringify({ ok: true, ...verified }, null, 2));
+            return;
+        }
+        const freshWs = store.getWorkspace(ctx.workspace.id) || ctx.workspace;
         console.log(JSON.stringify({
             ok: true,
+            tier: freshWs.tier,
+            creditsBalance: freshWs.creditsBalance,
+            creditBalance: freshWs.creditsBalance,
+            monthlyActionsUsed: freshWs.monthlyActionsUsed,
+            monthlyActionsLimit: freshWs.monthlyActionsLimit,
+            byokKeys: store.listByokKeys(ctx.workspace.id),
             settlementSummary: store.getSupplierSettlementSummary(ctx.workspace.id),
             recentLedger: store.listLedgerEntries(ctx.workspace.id, 25),
         }, null, 2));
         return;
     }
+    if (cmd === "byok" || cmd === "keys") {
+        const remoteUrl = typeof flags.url === "string" ? flags.url.replace(/\/+$/, "") : "";
+        const sub = positional[1] || "list";
+        if (sub === "set" || sub === "add" || sub === "prompt") {
+            let provider = (positional[2] || String(flags.provider || "")).trim().toLowerCase();
+            if (!provider) {
+                provider = (await promptUserLine("Enter provider slug (openai, anthropic, openrouter, gemini, composio, stripe, supermemory, firecrawl, exa): ")).toLowerCase();
+            }
+            if (!provider) {
+                throw new Error("Usage: muxo byok set <provider> [<api_key>]");
+            }
+            let secretKey = positional[3] ||
+                (typeof flags.key === "string" ? flags.key : "") ||
+                (typeof flags["secret-key"] === "string" ? flags["secret-key"] : "");
+            if (!secretKey) {
+                secretKey = await promptUserLine(`Enter API key for ${provider} (stored encrypted with AES-256-GCM in Muxo Vault): `);
+            }
+            if (!secretKey) {
+                throw new Error(`API key is required for provider '${provider}'.`);
+            }
+            if (remoteUrl) {
+                const res = await fetch(`${remoteUrl}/api/v1/byok`, {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json",
+                        ...(apiKeyFlag ? { Authorization: `Bearer ${apiKeyFlag}` } : {}),
+                    },
+                    body: JSON.stringify({ provider, secretKey }),
+                });
+                console.log(JSON.stringify(await res.json(), null, 2));
+                return;
+            }
+            const record = store.setByokKey(ctx.workspace.id, provider, secretKey);
+            console.log(JSON.stringify({
+                ok: true,
+                action: "saved",
+                key: record,
+                fundingMode: record.category === "supplier" ? "byok (0 credit cost)" : "llm_router",
+            }, null, 2));
+            return;
+        }
+        if (sub === "delete" || sub === "remove" || sub === "rm") {
+            const provider = (positional[2] || String(flags.provider || "")).trim().toLowerCase();
+            if (!provider)
+                throw new Error("Usage: muxo byok delete <provider>");
+            if (remoteUrl) {
+                const res = await fetch(`${remoteUrl}/api/v1/byok/${encodeURIComponent(provider)}`, {
+                    method: "DELETE",
+                    headers: apiKeyFlag ? { Authorization: `Bearer ${apiKeyFlag}` } : {},
+                });
+                console.log(JSON.stringify(await res.json(), null, 2));
+                return;
+            }
+            store.deleteByokKey(ctx.workspace.id, provider);
+            console.log(JSON.stringify({
+                ok: true,
+                action: "deleted",
+                provider,
+                keys: store.listByokKeys(ctx.workspace.id),
+            }, null, 2));
+            return;
+        }
+        if (remoteUrl) {
+            const res = await fetch(`${remoteUrl}/api/v1/byok`, {
+                headers: apiKeyFlag ? { Authorization: `Bearer ${apiKeyFlag}` } : {},
+            });
+            console.log(JSON.stringify(await res.json(), null, 2));
+            return;
+        }
+        console.log(JSON.stringify({
+            ok: true,
+            keys: store.listByokKeys(ctx.workspace.id),
+            supportedProviders: BYOK_PROVIDER_CATALOG,
+        }, null, 2));
+        return;
+    }
+    if (cmd === "do" || cmd === "ask" || cmd === "nl") {
+        const remoteUrl = typeof flags.url === "string" ? flags.url.replace(/\/+$/, "") : "";
+        let promptText = positional.slice(1).join(" ").trim() ||
+            (typeof flags.prompt === "string" ? flags.prompt : "");
+        if (!promptText) {
+            promptText = await promptUserLine("What would you like Muxo to do? ");
+        }
+        if (!promptText) {
+            throw new Error('Usage: muxo do "<natural language instruction>"');
+        }
+        // If user requested --byok and has no BYOK key for the requested provider, optionally prompt
+        if (flags.byok && typeof flags["byok-key"] === "string" && typeof flags["byok-provider"] === "string") {
+            store.setByokKey(ctx.workspace.id, String(flags["byok-provider"]), String(flags["byok-key"]));
+        }
+        const planOnly = flags["plan-only"] === true || flags.plan === true;
+        const autoApprove = flags["no-approve"] ? false : true;
+        const fundingMode = flags.byok || flags.funding === "byok"
+            ? "byok"
+            : flags.funding === "muxo_funded"
+                ? "muxo_funded"
+                : undefined;
+        if (remoteUrl) {
+            const res = await fetch(`${remoteUrl}/api/v1/do`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    ...(apiKeyFlag ? { Authorization: `Bearer ${apiKeyFlag}` } : {}),
+                },
+                body: JSON.stringify({
+                    prompt: promptText,
+                    autoApprove,
+                    dryRun: planOnly,
+                }),
+            });
+            console.log(JSON.stringify(await res.json(), null, 2));
+            return;
+        }
+        const result = await engine.doNaturalLanguage(ctx, {
+            prompt: promptText,
+            autoApprove,
+            planOnly,
+            fundingMode,
+        });
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    if (cmd === "tui" || cmd === "setup" || cmd === "interactive") {
+        const remoteUrl = typeof flags.url === "string" ? flags.url.replace(/\/+$/, "") : "";
+        if (remoteUrl && (flags.json || flags["non-interactive"] || flags.once)) {
+            const res = await fetch(`${remoteUrl}/api/v1/billing/status`, {
+                headers: apiKeyFlag ? { Authorization: `Bearer ${apiKeyFlag}` } : {},
+            });
+            const statusData = (await res.json());
+            console.log(JSON.stringify({
+                ok: true,
+                tui: "ready",
+                mode: "tui_snapshot",
+                workspace: statusData.workspace,
+                byokKeys: statusData.byokKeys || [],
+                supportedByokProviders: Object.keys(BYOK_PROVIDER_CATALOG),
+            }, null, 2));
+            return;
+        }
+        const freshWs = store.getWorkspace(ctx.workspace.id) || ctx.workspace;
+        const byokKeys = store.listByokKeys(ctx.workspace.id);
+        const conns = store.listConnections(ctx.workspace.id);
+        const resources = store.listResources(ctx.workspace.id);
+        const gov = engine.governance.getStatus(freshWs);
+        if (flags.json || flags["non-interactive"] || flags.once) {
+            console.log(JSON.stringify({
+                ok: true,
+                tui: "ready",
+                mode: "tui_snapshot",
+                workspace: {
+                    id: freshWs.id,
+                    name: freshWs.name,
+                    slug: freshWs.slug,
+                    tier: freshWs.tier,
+                    creditsBalance: freshWs.creditsBalance,
+                    monthlyActionsUsed: freshWs.monthlyActionsUsed,
+                    monthlyActionsLimit: freshWs.monthlyActionsLimit,
+                },
+                governanceDid: gov.agentDid,
+                byokKeys,
+                activeConnections: conns.filter((c) => c.status === "active").length,
+                activeResources: resources.filter((r) => r.status === "active").length,
+                supportedByokProviders: Object.keys(BYOK_PROVIDER_CATALOG),
+            }, null, 2));
+            return;
+        }
+        const printBanner = () => {
+            const wsNow = store.getWorkspace(ctx.workspace.id) || ctx.workspace;
+            const keysNow = store.listByokKeys(ctx.workspace.id);
+            const hasSupplierByok = keysNow.some((k) => k.category === "supplier");
+            console.log("\n┌──────────────────────────────────────────────────────────────────────────┐");
+            console.log("│ ⚡ MUXO INTERACTIVE TUI — Execution, Cloud Infra, Memory & Governance    │");
+            console.log("├──────────────────────────────────────────────────────────────────────────┤");
+            console.log(`│ Workspace : ${wsNow.name.padEnd(28)} Tier    : ${wsNow.tier.toUpperCase().padEnd(16)}│`);
+            console.log(`│ Credits   : ${String(wsNow.creditsBalance).padEnd(28)} Funding : ${(hasSupplierByok ? "BYOK (0 cr)" : "muxo_funded").padEnd(16)}│`);
+            console.log(`│ BYOK Keys : ${String(keysNow.length).padEnd(28)} DID     : ${gov.agentDid.slice(0, 16)}│`);
+            console.log("├──────────────────────────────────────────────────────────────────────────┤");
+            console.log("│ [1] ✨ Run in Plain English (Natural Language Router: muxo do)           │");
+            console.log("│ [2] 🔑 Configure BYOK API Key (OpenAI, Anthropic, Composio, Stripe...)   │");
+            console.log("│ [3] 💳 Billing: Top Up +1,000 Credits or Upgrade to Starter Plan         │");
+            console.log("│ [4] 🔗 Connect OAuth App (GitHub, Gmail, Slack, Notion, Linear)          │");
+            console.log("│ [5] ☁️  Provision Cloud Database (Turso SQLite, Neon Postgres, Redis)    │");
+            console.log("│ [q] Exit TUI                                                             │");
+            console.log("└──────────────────────────────────────────────────────────────────────────┘");
+        };
+        printBanner();
+        const choice = (await promptUserLine("\nSelect an option [1-5, q] (or type any natural language command): ")).trim();
+        if (!choice || choice.toLowerCase() === "q" || choice.toLowerCase() === "exit") {
+            console.log("Exited Muxo TUI.");
+            return;
+        }
+        if (choice === "1") {
+            const nlPrompt = await promptUserLine("Ask Muxo in plain English: ");
+            if (nlPrompt) {
+                const res = await engine.doNaturalLanguage(ctx, { prompt: nlPrompt, autoApprove: true });
+                console.log(JSON.stringify(res, null, 2));
+            }
+            return;
+        }
+        if (choice === "2") {
+            const provider = (await promptUserLine("Provider (openai, anthropic, openrouter, gemini, composio, stripe, supermemory, firecrawl, exa): ")).toLowerCase();
+            const secretKey = await promptUserLine(`Paste API key for ${provider}: `);
+            if (provider && secretKey) {
+                const saved = store.setByokKey(ctx.workspace.id, provider, secretKey);
+                console.log(JSON.stringify({ ok: true, saved }, null, 2));
+            }
+            return;
+        }
+        if (choice === "3") {
+            const action = (await promptUserLine("Type 'upgrade' for Starter Plan or credit amount (default 1000): ")).toLowerCase();
+            if (action === "upgrade") {
+                const up = store.upgradeWorkspaceToStarter({
+                    workspaceId: ctx.workspace.id,
+                    referenceId: `tui_upgrade_${Date.now()}`,
+                    bonusCredits: 1000,
+                });
+                console.log(JSON.stringify({ ok: true, upgraded: true, workspace: up }, null, 2));
+            }
+            else {
+                const cr = Math.max(100, Number(action) || 1000);
+                const up = store.addWorkspaceCredits({
+                    workspaceId: ctx.workspace.id,
+                    credits: cr,
+                    referenceId: `tui_topup_${Date.now()}`,
+                    description: `TUI credit top-up (+${cr} credits)`,
+                });
+                console.log(JSON.stringify({ ok: true, creditsAdded: cr, creditsBalance: up.creditsBalance }, null, 2));
+            }
+            return;
+        }
+        if (choice === "4") {
+            const provider = (await promptUserLine("OAuth Provider (github, gmail, slack, notion, linear): ")) || "github";
+            const conn = await engine.startConnection(ctx, { provider });
+            console.log(JSON.stringify({ ok: true, connection: conn }, null, 2));
+            return;
+        }
+        if (choice === "5") {
+            const dbPrompt = (await promptUserLine("Database to provision (e.g. 'Provision Turso database my-app-db'): ")) || "Provision Turso database my-app-db";
+            const res = await engine.doNaturalLanguage(ctx, { prompt: dbPrompt, autoApprove: true });
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        // Otherwise treat whatever they typed as a natural language command!
+        const res = await engine.doNaturalLanguage(ctx, { prompt: choice, autoApprove: true });
+        console.log(JSON.stringify(res, null, 2));
+        return;
+    }
     if (cmd === "memory") {
         const sub = positional[1];
         if (sub === "add") {
@@ -542,32 +838,54 @@ async function runCli() {
         });
         return;
     }
+    // Natural Language fallback: if user passed plain English directly (`muxo "Audit https://muxo.ai for SEO"`)
+    if (cmd !== "help" && !flags.help && !flags.h && positional.length > 0) {
+        const promptText = positional.join(" ").trim();
+        const result = await engine.doNaturalLanguage(ctx, {
+            prompt: promptText,
+            autoApprove: flags["no-approve"] ? false : true,
+            planOnly: flags["plan-only"] === true || flags.plan === true,
+            fundingMode: flags.byok || flags.funding === "byok"
+                ? "byok"
+                : flags.funding === "muxo_funded"
+                    ? "muxo_funded"
+                    : undefined,
+        });
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
     console.log(`
-Muxo CLI — Unified Execution, Provisioning & Governance Platform
+Muxo CLI — Human & LLM Friendly Execution, Infrastructure, BYOK & Governance Platform
+
+Natural Language & Interactive TUI:
+  muxo do "<instruction>"                      Execute any goal in plain English (LLM/semantic router -> plan -> execute)
+  muxo ask "<instruction>" [--plan-only]       Alias for 'muxo do' (pass --plan-only to inspect plan before running)
+  muxo tui                                     Launch interactive Terminal UI dashboard (BYOK, Billing, OAuth, Infra)
+  muxo byok [list|set|delete] [<provider>]     Manage BYOK API keys in AES-256-GCM Vault (0 credit cost when active)
 
-Commands:
+Core Commands:
   muxo login [--api-key <key> | --signup]      Sign in or create an autonomous workspace (~/.muxo/config.json)
   muxo logout                                  Remove saved CLI authentication config
   muxo claim <owner_email>                     Generate a human owner claim link for this workspace
   muxo whoami                                  Show workspace profile, plan, DID, and credit balance
-  muxo search <query> [--lane <lane>]          Search across Instant, Composio Apps, and Stripe Projects
+  muxo search <query> [--lane <lane>]          Search across Instant, Composio Apps, Stripe Projects & Billing
   muxo inspect <tool_slug>                     Inspect tool schema, risk level, and credit cost
   muxo connections [--sync true|false]         List Composio OAuth & Stripe Projects provider connections
   muxo link <provider> [--wait]                Start OAuth handoff for a service and optionally wait
   muxo connect <provider> [--wait]             Alias for 'muxo link'
   muxo wait <provider> [--timeout 15]          Poll until a pending OAuth connection handoff becomes active
-  muxo plan <tool_slug> --input '{...}'        Create a governed execution plan (plan_*)
+  muxo plan <tool_slug> --input '{...}'        Create a governed execution plan (accepts natural language too)
   muxo approve <plan_id>                       Approve a pending high-risk plan
   muxo run <plan_id>                           Execute an approved plan and issue a signed receipt
   muxo exec <tool_slug> --input '{...}'        Plan and execute in one step (pass --approve for high-risk)
   muxo resources                               List provisioned Stripe Projects infrastructure resources
   muxo env pull [--out .env.muxo]              Decrypt and write provisioned credentials to local .env
   muxo receipts [<receipt_id>]                 List or cryptographically verify execution receipts
-  muxo billing [status|topup|checkout]         Buy Muxo credits & inspect User -> Muxo -> Supplier settlements
+  muxo billing [status|topup|upgrade|checkout] Manage credits, upgrade to Starter, or inspect settlements
   muxo memory [<query>]                        Recall Supermemory v5 workspace brain & hybrid memories
   muxo governance                              Inspect Microsoft Agent Governance Ed25519 DID & audit chain
   muxo serve [--port 4310]                     Start unified HTTP Console, Landing, OAuth Callback & MCP server
-  muxo mcp                                     Run stdio MCP server (19 canonical tools)
+  muxo mcp                                     Run stdio MCP server (20 canonical tools)
 `);
 }
 runCli().catch((err) => {

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;
@@ -125,4 +127,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;
+    }>;
 }