@muxoai/platform 1.3.2 → 1.4.0

package/README.md

@@ -1,6 +1,6 @@
 # Muxo (`@muxoai/platform` / `@muxoai/cli` / `@muxoai/sdk`)
 
-Muxo (`v1.3.2`) 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`).
+Muxo (`v1.4.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.
 
@@ -37,10 +37,12 @@ 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)
+# 6. Manage Billing, Credits & Plans (Starter $29/mo, Pro $99/mo, yearly 2 months free)
 muxo billing status
+muxo billing plans
 muxo billing topup 1000
-muxo billing upgrade
+muxo billing upgrade --plan pro --yearly
+muxo billing portal
 
 # 7. Connect an OAuth SaaS App (browser consent handoff) & Provision Live Cloud Infrastructure
 muxo link gmail --wait
@@ -115,7 +117,7 @@ Muxo ships a portable OpenAI Plugin (`plugins/muxo/plugin.json` & `plugins/muxo/
 | `src/providers/composio-sdk.ts` | Live Composio v3 Connected Apps adapter (catalog search, OAuth sessions/links, tool execution) |
 | `src/providers/composio-instant.ts` | Live Composio Instant adapter (`search`, `scrape`, `crawl`, `seo.audit`, `hackernews`, `github.repo_intel`, `dns.lookup`, `workbench`) |
 | `src/providers/stripe-projects.ts` | Live Stripe Projects CLI bridge (`status`, `catalog`, `add`, `rotate`, `remove`, `env --pull`) |
-| `src/providers/stripe-billing.ts` | Live Stripe Checkout billing (`$29/mo Starter Plan` & `$10 / +1,000 Credits Pack`) |
+| `src/providers/stripe-billing.ts` | Live Stripe Checkout billing (Starter `$29/mo`, Pro `$99/mo`, yearly billing & credit packs with volume discounts) |
 | `src/providers/microsoft-governance.ts` | Microsoft Agent Governance Toolkit v5.0.0 (`McpSecurityScanner`, `PolicyEngine`, `AgentIdentity` Ed25519 DID, `AuditLogger`) |
 | `src/providers/supermemory.ts` | Supermemory v5 Contextual Brain (`profile`, hybrid `search`, secret-redacted `add`, `delete`) |
 | `src/engine.ts` | Unified Governance, Memory & Execution Engine implementing all 19 canonical MCP operations |

package/dist/clerk.d.ts

@@ -15,6 +15,8 @@ export interface ClerkProfile {
     email: string | null;
     emailVerified: boolean;
     name: string | null;
+    /** Every verified address on the account, lowercased, primary included. */
+    verifiedEmails: string[];
 }
 export interface ClerkEnv {
     CLERK_PUBLISHABLE_KEY?: string;

package/dist/clerk.js

@@ -187,6 +187,9 @@ export async function fetchClerkProfile(userId, secretKey) {
             email: primary?.email_address ? primary.email_address.toLowerCase() : null,
             emailVerified: primary?.verification?.status === "verified",
             name,
+            verifiedEmails: addresses
+                .filter((e) => e.email_address && e.verification?.status === "verified")
+                .map((e) => e.email_address.toLowerCase()),
         };
     }
     catch {

package/dist/cli.js

@@ -110,6 +110,12 @@ async function runCli() {
             body: opts?.body !== undefined ? JSON.stringify(opts.body) : undefined,
         });
         const data = (await res.json().catch(() => ({})));
+        if (opts?.acceptPaymentRequired && res.status === 402 && data.checkoutUrl) {
+            return data;
+        }
+        if (opts?.acceptHumanRequired && res.status === 403 && data.code === "human_required") {
+            return data;
+        }
         if (!res.ok && data.error) {
             throw new Error(String(data.error));
         }
@@ -171,6 +177,44 @@ async function runCli() {
             };
         return { store, engine: getEngine(), ctx, tokenAuth };
     };
+    const maskKey = (key) => `${key.slice(0, 14)}…`;
+    // Hosted Muxo answers purchases with 402 + a Stripe Checkout URL; a self-hosted dev server may grant credits directly.
+    const printBillingResult = (data) => {
+        if (data.code === "human_required" || data.status === "human_required") {
+            console.log(JSON.stringify({
+                ok: false,
+                humanRequired: true,
+                url: data.url,
+                error: data.error,
+                next: "Open the url in a browser and sign in to the Muxo console to finish this step. Agent API keys cannot manage billing or approvals.",
+            }, null, 2));
+            return;
+        }
+        if (data.portalUrl) {
+            console.log(JSON.stringify({
+                ok: true,
+                actionRequired: true,
+                tier: data.tier,
+                interval: data.interval,
+                portalUrl: data.portalUrl,
+                next: data.nextStep || "Open portalUrl in a browser; a signed-in person confirms the plan change in the Stripe billing portal.",
+            }, null, 2));
+            return;
+        }
+        if (!data.checkoutUrl) {
+            console.log(JSON.stringify(data, null, 2));
+            return;
+        }
+        console.log(JSON.stringify({
+            ok: true,
+            paymentRequired: true,
+            kind: data.kind,
+            credits: data.credits,
+            checkoutUrl: data.checkoutUrl,
+            sessionId: data.sessionId,
+            next: `Open checkoutUrl to pay with Stripe. Muxo adds the credits once Stripe confirms the payment. Check with: muxo billing verify ${data.sessionId}`,
+        }, null, 2));
+    };
     // CLI Login / Autonomous External Signup (`muxo login`)
     if (cmd === "login" || cmd === "signup") {
         const explicitKey = typeof flags["api-key"] === "string"
@@ -203,6 +247,7 @@ async function runCli() {
                     configPath: cfgPath,
                     workspace: ws,
                     ...authPayload,
+                    apiKey: maskKey(explicitKey),
                 }, null, 2));
                 return;
             }
@@ -227,6 +272,7 @@ async function runCli() {
                 mode: "api_key",
                 configPath: cfgPath,
                 ...authPayload,
+                apiKey: maskKey(explicitKey),
             }, null, 2));
             return;
         }
@@ -402,7 +448,7 @@ async function runCli() {
         else {
             console.log(`\n✓ Muxo is ready!`);
             console.log(`  Workspace : ${ensuredConfig.workspaceName} (${ensuredConfig.workspaceId})`);
-            console.log(`  API Key   : ${ensuredConfig.apiKey}`);
+            console.log(`  API Key   : ${maskKey(ensuredConfig.apiKey)} (saved in ${getCliConfigPath()})`);
             console.log(`  MCP URL   : ${mcpServerUrl}`);
             console.log(`  MCP Config: ${writtenFiles.join(", ")}`);
             console.log(`\nTry it now:`);
@@ -976,7 +1022,18 @@ async function runCli() {
         if (!planId)
             throw new Error("Usage: muxo approve <plan_id>");
         if (remoteUrl) {
-            const approved = await remoteFetch(`/api/v1/plans/${encodeURIComponent(planId)}/approve`, { method: "POST", body: {} });
+            const approved = await remoteFetch(`/api/v1/plans/${encodeURIComponent(planId)}/approve`, { method: "POST", body: {}, acceptHumanRequired: true });
+            if (approved.code === "human_required") {
+                console.log(JSON.stringify({
+                    ok: false,
+                    humanRequired: true,
+                    planId,
+                    approvalUrl: approved.url,
+                    error: approved.error,
+                    hint: "Open approvalUrl in a browser; a signed-in person approves the plan in the Muxo console. Agent API keys cannot approve plans.",
+                }, null, 2));
+                return;
+            }
             console.log(JSON.stringify(approved.plan || approved, null, 2));
             return;
         }
@@ -1028,7 +1085,18 @@ async function runCli() {
             const plan = planned.plan || planned;
             if (plan.approvalStatus === "pending_approval") {
                 if (flags.approve || cmd === "provision") {
-                    await remoteFetch(`/api/v1/plans/${encodeURIComponent(plan.id)}/approve`, { method: "POST", body: {} });
+                    const approved = await remoteFetch(`/api/v1/plans/${encodeURIComponent(plan.id)}/approve`, { method: "POST", body: {}, acceptHumanRequired: true });
+                    if (approved.code === "human_required") {
+                        console.log(JSON.stringify({
+                            ok: false,
+                            status: "pending_approval",
+                            humanRequired: true,
+                            plan,
+                            approvalUrl: approved.url,
+                            hint: "This plan needs approval from a signed-in person. Open approvalUrl in a browser to approve it in the Muxo console; agent API keys cannot approve plans.",
+                        }, null, 2));
+                        return;
+                    }
                 }
                 else {
                     console.log(JSON.stringify({
@@ -1183,8 +1251,9 @@ async function runCli() {
                 const data = await remoteFetch("/api/v1/billing/topup", {
                     method: "POST",
                     body: { credits },
+                    acceptPaymentRequired: true,
                 });
-                console.log(JSON.stringify(data, null, 2));
+                printBillingResult(data);
                 return;
             }
             const { store, ctx } = getLocalContext();
@@ -1207,12 +1276,19 @@ async function runCli() {
             return;
         }
         if (sub === "upgrade") {
+            const planArg = String(flags.plan || positional[2] || "starter").toLowerCase();
+            const tier = planArg === "pro" ? "pro" : "starter";
+            const interval = flags.yearly || flags.year || String(flags.interval || "").startsWith("y")
+                ? "year"
+                : "month";
             if (remoteUrl) {
                 const data = await remoteFetch("/api/v1/billing/upgrade", {
                     method: "POST",
-                    body: { tier: "starter", bonusCredits: 1000 },
+                    body: { tier, interval },
+                    acceptPaymentRequired: true,
+                    acceptHumanRequired: true,
                 });
-                console.log(JSON.stringify(data, null, 2));
+                printBillingResult(data);
                 return;
             }
             const { store, ctx } = getLocalContext();
@@ -1258,6 +1334,27 @@ async function runCli() {
             console.log(JSON.stringify({ ok: true, kind, ...session }, null, 2));
             return;
         }
+        if (sub === "plans") {
+            const plansUrl = remoteUrl || config.baseUrl;
+            const res = await fetch(`${plansUrl}/api/v1/billing/plans`, {
+                headers: { Accept: "application/json" },
+            });
+            const data = (await res.json().catch(() => ({})));
+            console.log(JSON.stringify(data, null, 2));
+            return;
+        }
+        if (sub === "portal") {
+            if (remoteUrl) {
+                const data = await remoteFetch("/api/v1/billing/portal", {
+                    method: "POST",
+                    body: {},
+                    acceptHumanRequired: true,
+                });
+                printBillingResult(data);
+                return;
+            }
+            throw new Error("muxo billing portal is only available for the hosted Muxo service (set --remote or log in first).");
+        }
         if (sub === "verify") {
             const sessionId = positional[2] || String(flags.session || "");
             if (!sessionId)
@@ -1483,21 +1580,18 @@ async function runCli() {
             }
             if (choice === "3") {
                 const action = (await promptUserLine("Type 'upgrade' for Starter Plan or credit amount (default 1000): ")).toLowerCase();
-                if (action === "upgrade") {
-                    const up = await remoteFetch("/api/v1/billing/upgrade", {
+                const up = action === "upgrade"
+                    ? await remoteFetch("/api/v1/billing/upgrade", {
                         method: "POST",
                         body: { tier: "starter", bonusCredits: 1000 },
-                    });
-                    console.log(JSON.stringify(up, null, 2));
-                }
-                else {
-                    const cr = Math.max(100, Number(action) || 1000);
-                    const up = await remoteFetch("/api/v1/billing/topup", {
+                        acceptPaymentRequired: true,
+                    })
+                    : await remoteFetch("/api/v1/billing/topup", {
                         method: "POST",
-                        body: { credits: cr },
+                        body: { credits: Math.max(100, Number(action) || 1000) },
+                        acceptPaymentRequired: true,
                     });
-                    console.log(JSON.stringify(up, null, 2));
-                }
+                printBillingResult(up);
                 return;
             }
             if (choice === "4") {

package/dist/sdk.d.ts

@@ -11,6 +11,77 @@ export interface MuxoClientOptions {
     fetch?: typeof fetch;
     timeoutMs?: number;
 }
+/** Error thrown for any non-OK Muxo API response. Carries the machine-readable code and payload. */
+export declare class MuxoApiError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    readonly url?: string;
+    readonly checkoutUrl?: string;
+    readonly data: Record<string, unknown>;
+    constructor(status: number, payload: Record<string, unknown>);
+}
+export interface BillingPlanInfo {
+    tier: "free" | "starter" | "pro";
+    name: string;
+    tagline: string;
+    monthlyActions: number;
+    monthlyCredits: number;
+    prices: {
+        month: {
+            cents: number;
+            label: string;
+        };
+        year: {
+            cents: number;
+            label: string;
+            perMonthLabel: string;
+        };
+    };
+    features: string[];
+}
+export interface PlanCatalog {
+    plans: BillingPlanInfo[];
+    yearlyDiscount: string;
+    creditPriceCents: number;
+    creditPacks: Array<{
+        credits: number;
+        cents: number;
+        label: string;
+    }>;
+    minCheckoutCredits: number;
+}
+export type UpgradePlanResult = {
+    ok: true;
+    unchanged: true;
+    tier: string;
+    message: string;
+    workspace?: Workspace;
+} | {
+    ok: true;
+    mode: "portal";
+    action: "billing_portal";
+    tier: string;
+    interval: string;
+    portalUrl: string;
+    url: string;
+    nextStep: string;
+} | {
+    ok: false;
+    code: "payment_required";
+    paymentRequired: true;
+    checkoutUrl: string;
+    sessionId: string;
+    kind: string;
+    tier: string;
+    interval: string;
+    credits: number;
+    error: string;
+} | {
+    ok: false;
+    code: "human_required";
+    url: string;
+    error: string;
+};
 export declare class MuxoClient {
     readonly baseUrl: string;
     private readonly apiKeyResolver?;
@@ -398,17 +469,41 @@ export declare class MuxoClient {
         provider: string;
         keys: ByokKeyRecord[];
     }>;
-    upgradePlan(): Promise<{
+    /** Lists plans, prices, and credit packs. No auth required. */
+    getPlans(): Promise<{
+        ok: true;
+    } & PlanCatalog>;
+    /**
+     * Moves the workspace to a plan. A first subscription returns a Stripe checkout URL
+     * (`payment_required`); changing an existing subscription returns a billing-portal URL.
+     * Plan changes are confirmed by a signed-in person; API keys get `human_required`.
+     */
+    upgradePlan(options?: {
+        tier?: "starter" | "pro";
+        interval?: "month" | "year";
+    }): Promise<UpgradePlanResult>;
+    /**
+     * Opens the Stripe billing portal to manage payment details, switch plans, or cancel.
+     * Signed-in people only; API keys get a `human_required` MuxoApiError.
+     */
+    openBillingPortal(): Promise<{
         ok: true;
-        tier: string;
-        workspace: Workspace;
-        settlementSummary: SupplierSettlementSummary;
+        url: string;
+        portalUrl: string;
     }>;
-    createCheckoutSession(kind?: "starter_subscription" | "credit_topup"): Promise<{
+    createCheckoutSession(kind?: "subscription" | "starter_subscription" | "credit_topup", optionsOrCredits?: number | {
+        credits?: number;
+        tier?: "starter" | "pro";
+        interval?: "month" | "year";
+    }): Promise<{
         ok: true;
         sessionId: string;
         url: string;
         mode?: string;
+        kind?: string;
+        credits?: number;
+        tier?: string;
+        interval?: string;
     }>;
     verifyCheckoutSession(sessionId: string): Promise<{
         ok: true;

package/dist/sdk.js

@@ -1,3 +1,21 @@
+/** Error thrown for any non-OK Muxo API response. Carries the machine-readable code and payload. */
+export class MuxoApiError extends Error {
+    status;
+    code;
+    url;
+    checkoutUrl;
+    data;
+    constructor(status, payload) {
+        super(String(payload.error || `Muxo request failed with HTTP ${status}`));
+        this.name = "MuxoApiError";
+        this.status = status;
+        this.code = typeof payload.code === "string" ? payload.code : undefined;
+        this.url = typeof payload.url === "string" ? payload.url : undefined;
+        this.checkoutUrl =
+            typeof payload.checkoutUrl === "string" ? payload.checkoutUrl : undefined;
+        this.data = payload;
+    }
+}
 export class MuxoClient {
     baseUrl;
     apiKeyResolver;
@@ -41,7 +59,7 @@ export class MuxoClient {
         });
         const payload = (await res.json());
         if (!res.ok || payload.ok === false) {
-            throw new Error(String(payload.error || `Muxo request failed with HTTP ${res.status}`));
+            throw new MuxoApiError(res.status, payload);
         }
         return payload;
     }
@@ -166,8 +184,21 @@ export class MuxoClient {
         });
         let plan = planned.plan;
         if (plan.approvalStatus === "pending_approval" && options.approve) {
-            const approved = await this.approvePlan(plan.id);
-            plan = approved.plan;
+            try {
+                const approved = await this.approvePlan(plan.id);
+                plan = approved.plan;
+            }
+            catch (err) {
+                if (err instanceof MuxoApiError && err.code === "human_required") {
+                    throw new MuxoApiError(err.status, {
+                        ...err.data,
+                        planId: plan.id,
+                        approvalUrl: err.url,
+                        error: `Plan ${plan.id} needs approval from a signed-in person at ${err.url || "the Muxo console"}; API keys cannot approve plans.`,
+                    });
+                }
+                throw err;
+            }
         }
         const executed = await this.executePlan(plan.id);
         return {
@@ -360,16 +391,50 @@ export class MuxoClient {
             method: "DELETE",
         });
     }
-    async upgradePlan() {
-        return this.request("/api/v1/billing/upgrade", {
+    /** Lists plans, prices, and credit packs. No auth required. */
+    async getPlans() {
+        return this.request("/api/v1/billing/plans");
+    }
+    /**
+     * Moves the workspace to a plan. A first subscription returns a Stripe checkout URL
+     * (`payment_required`); changing an existing subscription returns a billing-portal URL.
+     * Plan changes are confirmed by a signed-in person; API keys get `human_required`.
+     */
+    async upgradePlan(options = {}) {
+        try {
+            return await this.request("/api/v1/billing/upgrade", {
+                method: "POST",
+                body: {
+                    tier: options.tier || "starter",
+                    interval: options.interval || "month",
+                },
+            });
+        }
+        catch (err) {
+            if (err instanceof MuxoApiError &&
+                (err.code === "payment_required" || err.code === "human_required")) {
+                return err.data;
+            }
+            throw err;
+        }
+    }
+    /**
+     * Opens the Stripe billing portal to manage payment details, switch plans, or cancel.
+     * Signed-in people only; API keys get a `human_required` MuxoApiError.
+     */
+    async openBillingPortal() {
+        return this.request("/api/v1/billing/portal", {
             method: "POST",
             body: {},
         });
     }
-    async createCheckoutSession(kind = "credit_topup") {
+    async createCheckoutSession(kind = "credit_topup", optionsOrCredits) {
+        const opts = typeof optionsOrCredits === "number"
+            ? { credits: optionsOrCredits }
+            : optionsOrCredits || {};
         return this.request("/api/v1/billing/checkout", {
             method: "POST",
-            body: { kind },
+            body: { kind, ...opts },
         });
     }
     async verifyCheckoutSession(sessionId) {

package/dist/server.js

@@ -693,7 +693,8 @@ Users purchase Muxo Credits (\`POST /api/v1/billing/topup\` or \`muxo billing to
     <div class="badge">Ownership Bound</div>
     <h1>Workspace Claimed</h1>
     <p>Workspace <code>${redeemed.workspace.name}</code> (${redeemed.workspace.id}) claimed by <strong>${redeemed.targetEmail}</strong>.</p>
-    <a class="btn" href="/?claimed=${encodeURIComponent(redeemed.workspace.slug)}&api_key=${encodeURIComponent(claimConsoleKey)}">Open Muxo Console →</a>
+    <p>Console key: <code>${claimConsoleKey}</code><br />Choose “Use an API key instead” in the console and paste it.</p>
+    <a class="btn" href="/?claimed=${encodeURIComponent(redeemed.workspace.slug)}">Open Muxo Console →</a>
   </div>
 </body>
 </html>`);

package/dist/types.d.ts

@@ -1,6 +1,23 @@
 export type RiskLevel = "read" | "write" | "admin" | "financial" | "provisioning" | "destructive";
 export type ProviderLane = "composio_sdk" | "composio_instant" | "stripe_projects";
-export type SubscriptionTier = "free" | "starter";
+export type SubscriptionTier = "free" | "starter" | "pro";
+export type SubscriptionStatus = "none" | "active" | "trialing" | "past_due" | "unpaid" | "canceled" | "incomplete" | "comped";
+export interface WorkspaceBilling {
+    interval: "month" | "year" | null;
+    status: SubscriptionStatus;
+    cancelAtPeriodEnd: boolean;
+    /** When Stripe next renews or ends the subscription. */
+    currentPeriodEnd: string | null;
+    /** Monthly usage periods are counted from this moment. */
+    usagePeriodAnchor: string;
+    usagePeriodStart: string;
+    usagePeriodEnd: string;
+    /** usagePeriodStart of the last period whose plan credits were granted. */
+    creditsGrantedFor: string | null;
+    paymentFailedAt?: string | null;
+    /** Subscription whose start (fresh usage period and first credits) was already applied. */
+    startedSubscriptionId?: string | null;
+}
 export interface GovernancePolicy {
     mode: "monitor" | "enforce";
     requireApprovalFor: RiskLevel[];
@@ -32,6 +49,7 @@ export interface Workspace {
     creditsBalance: number;
     stripeCustomerId: string | null;
     stripeSubscriptionId: string | null;
+    billing?: WorkspaceBilling;
     projectsEnvName: string;
     policy: GovernancePolicy;
     createdAt: string;
@@ -360,7 +378,7 @@ export interface ExecutionReceipt {
 export interface LedgerEntry {
     id: string;
     workspaceId: string;
-    kind: "plan_grant" | "credit_topup" | "run_deduction" | "subscription_upgrade" | "manual_adjustment";
+    kind: "plan_grant" | "credit_topup" | "run_deduction" | "subscription_upgrade" | "plan_change" | "refund" | "manual_adjustment";
     actionsDelta: number;
     creditsDelta: number;
     balanceAfter: number;

package/dist/ui/console-html.d.ts

@@ -13,6 +13,13 @@ export interface OAuthConsentOptions {
         frontendApi: string;
     } | null;
     request?: Record<string, string>;
+    /** Renders the workspace-claim variant, which posts to `action` instead of /oauth/authorize. */
+    claim?: {
+        workspaceName: string;
+        targetEmail: string;
+        action: string;
+        cancelUrl: string;
+    };
 }
 /** Consent screen for MCP clients (ChatGPT, Claude, CLIs) asking to use a Muxo workspace. */
 export declare function renderOAuthConsentHtml(opts: OAuthConsentOptions): string;

package/dist/ui/console-html.js

@@ -238,6 +238,10 @@ body:has(dialog[open]){overflow:hidden}
 .auth-alt{margin-top:12px}
 .row-actions{display:inline-flex;align-items:center;gap:8px;flex:none}
 .clerk-auth{display:flex;justify-content:center;min-height:120px;margin-top:20px;text-align:left}
+.clerk-loading{display:flex;align-items:center;gap:10px;align-self:center;margin:0;color:var(--color-muted);font-size:15px}
+.spinner{flex:none;width:18px;height:18px;border:2px solid var(--color-border);border-top-color:var(--color-text);border-radius:50%;animation:muxo-spin .8s linear infinite}
+@keyframes muxo-spin{to{transform:rotate(360deg)}}
+@media (prefers-reduced-motion:reduce){.spinner{animation:none}}
 .auth-switch{margin-top:4px}
 .auth-switch:has([hidden]){display:none}
 .auth-foot{margin-top:16px;color:var(--color-muted);font-size:12px}
@@ -263,7 +267,7 @@ var LANE_LABELS = { composio_instant: 'Instant tool', composio_sdk: 'Connected a
 var TOKEN_KEY = 'muxo_external_api_key';
 var ESC = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
 
-var state = { view: 'overview', boot: null, harness: 'plugin', lane: 'all', factsMode: 'current', facts: null, authMode: 'login' };
+var state = { view: 'overview', boot: null, harness: 'plugin', lane: 'all', factsMode: 'current', facts: null, authMode: 'login', billingInterval: 'month', planCatalog: null };
 var currentTool = null;
 var activeKeyHint = 'mk_live_...';
 var externalApiKey = readToken();
@@ -468,6 +472,7 @@ async function api(path, opts) {
   if (!res.ok || data.ok === false) {
     var err = new Error(data.error || data.message || ('HTTP ' + res.status));
     err.status = res.status;
+    err.data = data;
     if (res.status === 401 && !opts.anonymous) handleUnauthorized();
     throw err;
   }
@@ -535,14 +540,20 @@ async function loadAuth() {
     });
   } catch (err) {
     clerk = null;
+    removeClerkLoading();
     setText('auth-error', err.message);
   }
 }
+function removeClerkLoading() {
+  var loading = byId('clerk-loading');
+  if (loading) loading.remove();
+}
 function mountClerkAuth(view) {
   if (!clerk || !clerk.loaded || clerkSignedIn()) return;
   var key = view === 'signup' ? 'signup' : 'login';
   if (clerkMounted === key) return;
   unmountClerkAuth();
+  removeClerkLoading();
   var target = location.origin + '/';
   var opts = { routing: 'hash', forceRedirectUrl: target, signInForceRedirectUrl: target, signUpForceRedirectUrl: target, appearance: clerkAppearance() };
   if (key === 'signup') clerk.mountSignUp(byId('clerk-auth'), opts); else clerk.mountSignIn(byId('clerk-auth'), opts);
@@ -1238,10 +1249,19 @@ async function loadPlans() {
       : (p.approvalStatus === 'approved' || p.approvalStatus === 'auto_approved')
         ? '<button class="btn btn-sm" data-action="execute-plan" data-id="' + id + '">Run</button>'
         : '<span class="mono small muted">' + esc(p.runId ? shortId(p.runId) : 'Done') + '</span>';
-    return '<tr><td class="mono small">' + esc(shortId(p.id)) + '</td><td class="mono small">' + esc(p.toolSlug) + '</td>' +
+    return '<tr id="plan-row-' + id + '"><td class="mono small">' + esc(shortId(p.id)) + '</td><td class="mono small">' + esc(p.toolSlug) + '</td>' +
       '<td>' + riskBadge(p.riskLevel) + ' ' + pill(verdict, verdict === 'deny' ? 'danger' : '') + '</td>' +
       '<td>' + statusBadge(p.approvalStatus) + '</td><td class="cell-actions">' + action + '</td></tr>';
   }).join('') : emptyRow(5, 'Nothing waiting. Plans appear here when an agent asks to run a tool.');
+  var focusPlan = new URLSearchParams(window.location.search).get('plan');
+  if (focusPlan && /^[A-Za-z0-9_-]+$/.test(focusPlan)) {
+    var row = byId('plan-row-' + focusPlan);
+    if (row) {
+      row.style.background = 'rgba(99, 102, 241, 0.14)';
+      row.scrollIntoView({ behavior: 'smooth', block: 'center' });
+      showToast('This plan is waiting for your approval.');
+    }
+  }
 }
 async function approveAndRun(planId) {
   await post('/api/v1/plans/' + planId + '/approve');
@@ -1339,6 +1359,7 @@ async function loadLedger() {
       '<td class="mono" style="color:' + (delta >= 0 ? 'var(--color-ok)' : 'var(--color-text)') + '">' + (delta >= 0 ? '+' : '') + esc(fmt(delta)) + '</td>' +
       '<td class="mono">' + esc(fmt(e.balanceAfter)) + '</td></tr>';
   }).join('') : emptyRow(4, 'No billing activity yet.');
+  await renderPlanCards();
   await loadByokKeys();
 }
 async function loadByokKeys() {
@@ -1409,19 +1430,6 @@ async function runNaturalLanguagePrompt() {
     throw err;
   }
 }
-async function instantUpgradeStarter() {
-  var res = await post('/api/v1/billing/upgrade', { tier: 'starter' });
-  showToast(res.message || 'Upgraded to the Starter plan');
-  await refreshOverview();
-  await loadLedger();
-}
-async function instantTopupCustom() {
-  var credits = Math.max(1, Number(byId('topup-credits-input').value || 1000));
-  var res = await post('/api/v1/billing/topup', { credits: credits });
-  showToast('Added ' + fmt(res.creditsAdded) + ' credits' + (res.usdPaid != null ? ' ($' + Number(res.usdPaid).toFixed(2) + ')' : ''));
-  await refreshOverview();
-  await loadLedger();
-}
 async function startCheckout(kind) {
   showToast('Opening Stripe Checkout…');
   var credits = Math.max(100, Number(byId('topup-credits-input').value || 1000));
@@ -1429,19 +1437,105 @@ async function startCheckout(kind) {
   if (res.url) window.location.href = res.url;
 }
 
+var FALLBACK_PLANS = [
+  { tier: 'free', name: 'Free', tagline: 'Try Muxo with your first agent.', monthlyActions: 500, monthlyCredits: 0, prices: { month: { cents: 0, label: '$0' }, year: { cents: 0, label: '$0', perMonthLabel: '$0' } }, features: ['500 governed actions a month', '250 trial credits', 'Approvals, audit log, and workspace memory', 'Bring your own provider keys'] },
+  { tier: 'starter', name: 'Starter', tagline: 'For builders running agents every day.', monthlyActions: 5000, monthlyCredits: 1000, prices: { month: { cents: 2900, label: '$29' }, year: { cents: 29000, label: '$290', perMonthLabel: '$24' } }, features: ['5,000 governed actions a month', '1,000 credits every month', 'Everything in Free', 'Email support'] },
+  { tier: 'pro', name: 'Pro', tagline: 'For teams with agents in production.', monthlyActions: 25000, monthlyCredits: 5000, prices: { month: { cents: 9900, label: '$99' }, year: { cents: 99000, label: '$990', perMonthLabel: '$82.50' } }, features: ['25,000 governed actions a month', '5,000 credits every month', 'Everything in Starter', 'Priority support'] }
+];
+var TIER_ORDER = { free: 0, starter: 1, pro: 2 };
+
+async function planCatalog() {
+  if (!state.planCatalog) {
+    try { state.planCatalog = await api('/api/v1/billing/plans', { anonymous: true }); } catch (e) { state.planCatalog = { plans: FALLBACK_PLANS }; }
+  }
+  return state.planCatalog;
+}
+
+async function renderPlanCards() {
+  var box = byId('plan-cards');
+  if (!box) return;
+  var catalog = await planCatalog();
+  var org = (state.boot && state.boot.organization) || {};
+  var billing = (state.boot && state.boot.billing) || {};
+  var tier = String(org.tier || 'free');
+  var interval = state.billingInterval;
+  box.innerHTML = (catalog.plans || FALLBACK_PLANS).map(function (p) {
+    var current = tier === p.tier;
+    var price = p.prices[interval] || p.prices.month;
+    var priceLine = p.tier === 'free'
+      ? '<p class="price">$0 <span>forever</span></p>'
+      : '<p class="price">' + esc(price.label) + ' <span>' + (interval === 'year' ? 'per year · ' + esc(price.perMonthLabel) + '/mo' : 'per month') + '</span></p>';
+    var action;
+    if (current) action = pill('Current plan', 'ok');
+    else if (TIER_ORDER[p.tier] > TIER_ORDER[tier]) action = '<button class="btn btn-primary" type="button" data-action="change-plan" data-tier="' + esc(p.tier) + '">Upgrade to ' + esc(p.name) + '</button>';
+    else action = '<button class="btn" type="button" data-action="change-plan" data-tier="' + esc(p.tier) + '">Switch to ' + esc(p.name) + '</button>';
+    return '<div class="panel"><div class="panel-header"><div><h2>' + esc(p.name) + '</h2><p>' + esc(p.tagline || '') + '</p></div></div>' +
+      priceLine +
+      '<ul class="plan-list">' + (p.features || []).map(function (f) { return '<li>' + esc(f) + '</li>'; }).join('') + '</ul>' +
+      '<div class="page-actions">' + action + '</div></div>';
+  }).join('');
+  var manage = byId('manage-billing-btn');
+  if (manage) manage.hidden = !billing.canManageBilling;
+  var note = [];
+  if (billing.status === 'comped') note.push('Complimentary plan');
+  else if (billing.status && billing.status !== 'none') note.push('Subscription ' + String(billing.status).replace(/_/g, ' '));
+  if (billing.cancelAtPeriodEnd && billing.renewsAt) note.push('ends ' + String(billing.renewsAt).slice(0, 10));
+  else if (billing.renewsAt && billing.status !== 'comped') note.push('renews ' + String(billing.renewsAt).slice(0, 10));
+  if (billing.paymentFailed) note.push('Payment failed — update your card in Manage billing');
+  if (billing.usage && billing.usage.resetsAt) note.push('Usage resets ' + String(billing.usage.resetsAt).slice(0, 10));
+  setText('billing-status-note', note.join(' · '));
+}
+
+function setBillingInterval(interval) {
+  state.billingInterval = interval === 'year' ? 'year' : 'month';
+  document.querySelectorAll('[data-action="billing-interval"]').forEach(function (b) {
+    b.setAttribute('aria-pressed', String(b.dataset.interval === state.billingInterval));
+  });
+  renderPlanCards().catch(showError);
+}
+
+async function changePlan(tier) {
+  showToast('Talking to Stripe…');
+  try {
+    var res = await post('/api/v1/billing/upgrade', { tier: tier, interval: state.billingInterval });
+    if (res.portalUrl || (res.action === 'billing_portal' && res.url)) { window.location.href = res.portalUrl || res.url; return; }
+    if (res.url) { window.location.href = res.url; return; }
+    showToast(res.message || 'Plan is unchanged.');
+    await refreshOverview();
+    await renderPlanCards();
+  } catch (err) {
+    var data = err && err.data;
+    if (data && (data.checkoutUrl || data.url)) { window.location.href = data.checkoutUrl || data.url; return; }
+    showError(err);
+  }
+}
+
+async function manageBilling() {
+  showToast('Opening the Stripe billing portal…');
+  var res = await post('/api/v1/billing/portal', {});
+  if (res.url) window.location.href = res.url;
+}
+
 async function checkCheckoutReturn() {
   var params = new URLSearchParams(window.location.search);
   var clean = false;
   var sessionId = params.get('session_id');
   if (params.get('checkout') === 'success' && sessionId) {
     clean = true;
-    try {
-      var res = await post('/api/v1/billing/verify-session', { sessionId: sessionId });
-      if (res.fulfilled) showToast('Payment confirmed. Your workspace has been updated.');
-    } catch (err) { console.error(err); }
+    if (isSignedIn()) {
+      try {
+        var res = await post('/api/v1/billing/verify-session', { sessionId: sessionId });
+        showToast(res.fulfilled ? 'Payment confirmed. Your workspace has been updated.' : 'Payment is processing. Credits appear as soon as Stripe confirms it.');
+      } catch (err) { showToast(err.message, 'danger'); }
+    } else {
+      showToast('Payment received. Sign in to see your updated balance.');
+    }
   }
+  if (params.get('checkout') === 'cancelled') { clean = true; showToast('Checkout cancelled. You were not charged.'); }
+  if (params.get('plan') === 'updated') { clean = true; showToast('Your plan change is confirmed.'); }
   if (params.get('connected')) { clean = true; showToast(params.get('connected') + ' is connected'); }
-  if (params.get('api_key')) { clean = true; externalApiKey = params.get('api_key'); writeToken(externalApiKey); }
+  // Keys are never accepted from the URL: a crafted link could sign a person into someone else's workspace.
+  if (params.get('api_key')) clean = true;
   if (params.get('claimed')) { clean = true; showToast('You now own this workspace (' + params.get('claimed') + ')'); }
   if (clean) window.history.replaceState({}, '', window.location.pathname);
 }
@@ -1473,14 +1567,15 @@ var ACTIONS = {
   'delete-memory': function (el) { return deleteMemoryItem(el.dataset.id); },
   'facts-mode': function (el) { setFactsMode(el.dataset.mode); },
   'approve-plan': function (el) { return approveAndRun(el.dataset.id); },
+  'billing-interval': function (el) { setBillingInterval(el.dataset.interval); },
+  'change-plan': function (el) { return changePlan(el.dataset.tier); },
+  'manage-billing': function () { return manageBilling(); },
   'execute-plan': function (el) { return executeExistingPlan(el.dataset.id); },
   'kill-resume': resumeKillSwitch,
   'refresh-governance': loadPlans,
   'refresh-runs': loadRuns,
   'inspect-receipt': function (el) { return inspectReceipt(el.dataset.id); },
   'checkout': function (el) { return startCheckout(el.dataset.kind); },
-  'instant-upgrade': instantUpgradeStarter,
-  'instant-topup': instantTopupCustom,
   'delete-byok': function (el) { return deleteByokKeyFromUi(el.dataset.provider); },
   'plan-only': submitPlanOnly,
   'plan-run': submitPlanAndExecute,
@@ -2057,17 +2152,18 @@ export function renderConsoleHtml() {
             <div class="metric"><p class="metric-label">Paid to providers</p><p class="metric-value" id="billing-wholesale">$0.00</p><p class="metric-sub">Settled by Muxo for you</p></div>
           </div>
           <div class="split even">
-            <div class="panel">
-              <div class="panel-header"><div><h2>Starter plan</h2><p>For teams running agents every day.</p></div></div>
-              <p class="price">$29 <span>per month</span></p>
-              <ul class="plan-list">
-                <li>10,000 governed actions a month</li>
-                <li>1,000 credits included</li>
-                <li>Approvals, audit log, and workspace memory</li>
-              </ul>
-              <div class="page-actions">
-                <button class="btn btn-primary" type="button" data-action="checkout" data-kind="starter_subscription">Upgrade with Stripe</button>
-                <button class="btn" type="button" data-action="instant-upgrade">Upgrade now (test mode)</button>
+            <div class="panel" style="grid-column:1/-1">
+              <div class="panel-header">
+                <div><h2>Plans</h2><p>Every plan includes approvals, the audit log, and workspace memory. Yearly billing gives you 2 months free.</p></div>
+                <div class="row-actions" role="group" aria-label="Billing period">
+                  <button class="chip" type="button" data-action="billing-interval" data-interval="month" aria-pressed="true">Monthly</button>
+                  <button class="chip" type="button" data-action="billing-interval" data-interval="year" aria-pressed="false">Yearly · 2 months free</button>
+                </div>
+              </div>
+              <div id="plan-cards" style="display:grid;grid-template-columns:repeat(auto-fit,minmax(220px,1fr));gap:16px"><p class="empty-note">Loading plans…</p></div>
+              <div class="page-actions" style="margin-top:16px;align-items:center">
+                <button class="btn" type="button" data-action="manage-billing" id="manage-billing-btn" hidden>Manage billing in Stripe</button>
+                <small class="muted" id="billing-status-note"></small>
               </div>
             </div>
             <div class="panel">
@@ -2075,7 +2171,6 @@ export function renderConsoleHtml() {
               <label class="field"><span>Credits</span><input id="topup-credits-input" type="number" value="1000" min="100" step="100" inputmode="numeric" /><small class="field-help">1,000 credits cost $10.</small></label>
               <div class="page-actions" style="margin-top:16px">
                 <button class="btn btn-primary" type="button" data-action="checkout" data-kind="credit_topup">Pay with Stripe</button>
-                <button class="btn" type="button" data-action="instant-topup">Add now (test mode)</button>
               </div>
             </div>
           </div>
@@ -2139,7 +2234,7 @@ export function renderConsoleHtml() {
         <p id="auth-error" class="field-error" role="alert"></p>
         <button id="auth-submit" class="btn btn-primary btn-lg btn-block" type="submit">Sign in</button>
       </form>
-      <div id="clerk-auth" class="clerk-auth" hidden></div>
+      <div id="clerk-auth" class="clerk-auth" hidden><p id="clerk-loading" class="clerk-loading" role="status"><span class="spinner" aria-hidden="true"></span>Loading sign-in…</p></div>
       <p class="auth-switch"><button id="auth-switch-link" class="btn btn-quiet btn-sm" type="button" data-action="auth-mode" data-mode="signup" hidden>New to Muxo? Create an account</button></p>
       <div class="auth-alt"><button class="btn btn-quiet" type="button" data-action="switch-workspace">${uiIcon("key")}Use an API key instead</button></div>
       <p class="auth-foot">Setting up an agent? Run <code>npx -y @muxoai/cli@latest login --signup</code></p>
@@ -2450,20 +2545,21 @@ const consentScript = String.raw `
   }
   async function decide(decision) {
     if (busy) return;
+    if (decision === 'deny' && C.cancelUrl) { location.assign(C.cancelUrl); return; }
     busy = true;
     fail('');
     byId('consent-allow').disabled = true;
     byId('consent-deny').disabled = true;
     try {
       var token = await clerk.session.getToken();
-      var res = await fetch('/oauth/authorize', {
+      var res = await fetch(C.action || '/oauth/authorize', {
         method: 'POST',
         headers: { 'Content-Type': 'application/json', Authorization: 'Bearer ' + token },
         body: JSON.stringify(Object.assign({}, C.request, { decision: decision }))
       });
       var data = await res.json().catch(function () { return {}; });
       if (!res.ok || !data.redirect) throw new Error(data.error || 'Muxo could not finish this request. Try again.');
-      byId(decision === 'allow' ? 'consent-allow' : 'consent-deny').textContent = decision === 'allow' ? 'Returning…' : 'Cancelling…';
+      byId(decision === 'allow' ? 'consent-allow' : 'consent-deny').textContent = decision === 'allow' ? (C.action ? 'Opening…' : 'Returning…') : 'Cancelling…';
       location.assign(data.redirect);
     } catch (err) {
       fail(err.message);
@@ -2501,7 +2597,7 @@ export function renderOAuthConsentHtml(opts) {
 <head>
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
-  <title>${opts.error ? "Connection problem" : `Connect ${clientNameMidSentence}`} · Muxo</title>
+  <title>${opts.error ? (opts.claim ? "Claim problem" : "Connection problem") : opts.claim ? `Claim ${escapeHtml(opts.claim.workspaceName)}` : `Connect ${clientNameMidSentence}`} · Muxo</title>
   <meta name="theme-color" content="${muxoThemes.light.bg}" />
   <meta name="color-scheme" content="light dark" />
   <meta name="robots" content="noindex" />
@@ -2515,30 +2611,43 @@ export function renderOAuthConsentHtml(opts) {
   <main class="auth-view">
     <div class="auth-card">
       <div class="auth-mark">${muxoMark}</div>
-      <h1>This connection link isn't valid</h1>
+      <h1>${opts.claim ? "This claim link isn't valid" : "This connection link isn't valid"}</h1>
       <p class="lede">${escapeHtml(opts.error)}</p>
-      <p class="auth-foot">Start the connection again from your app, or <a href="${DOCS_URL}">read the setup guide</a>.</p>
+      <p class="auth-foot">${opts.claim ? "Ask the agent for a new claim link" : "Start the connection again from your app"}, or <a href="${DOCS_URL}">read the setup guide</a>.</p>
     </div>
   </main>
 </body>
 </html>`;
     }
+    const claim = opts.claim;
     const config = {
         clerk: opts.clerk || null,
         request: opts.request || {},
+        action: claim?.action,
+        cancelUrl: claim?.cancelUrl,
     };
-    return `${head}
-  <main class="auth-view">
-    <div class="auth-card">
-      <div class="auth-mark">${muxoMark}</div>
-      <h1>Connect ${clientNameMidSentence} to Muxo</h1>
+    const intro = claim
+        ? `<h1>Claim ${escapeHtml(claim.workspaceName)}</h1>
+      <p class="lede">An agent created this Muxo workspace and invited you to own it.</p>
+      <ul class="consent-list">
+        <li>You become the owner of this workspace and its credits</li>
+        <li>You manage its keys, safety rules, memory, and billing</li>
+        <li>The agent keeps working with its key until you revoke it</li>
+      </ul>
+      <p class="consent-redirect">Sign in as <strong>${escapeHtml(claim.targetEmail)}</strong> to accept.</p>`
+        : `<h1>Connect ${clientNameMidSentence} to Muxo</h1>
       <p class="lede">${clientName} wants to use your Muxo workspace.</p>
       <ul class="consent-list">
         <li>Find tools and plan actions in your workspace</li>
         <li>Run tools under your workspace's safety rules and approvals</li>
         <li>Read the status of connections, plans, and runs</li>
       </ul>
-      <p class="consent-redirect">After you decide, you'll return to <strong>${escapeHtml(opts.redirectOrigin || "")}</strong></p>
+      <p class="consent-redirect">After you decide, you'll return to <strong>${escapeHtml(opts.redirectOrigin || "")}</strong></p>`;
+    return `${head}
+  <main class="auth-view">
+    <div class="auth-card">
+      <div class="auth-mark">${muxoMark}</div>
+      ${intro}
       <div class="consent-state">
         <p id="consent-loading" class="muted">Checking your sign-in…</p>
         <div id="consent-signin" hidden>
@@ -2548,14 +2657,14 @@ export function renderOAuthConsentHtml(opts) {
         <div id="consent-approve" hidden>
           <p class="consent-account">Signed in as <strong id="consent-email"></strong></p>
           <div class="consent-actions">
-            <button id="consent-deny" class="btn btn-lg" type="button">Cancel</button>
-            <button id="consent-allow" class="btn btn-primary btn-lg" type="button">Allow</button>
+            <button id="consent-deny" class="btn btn-lg" type="button">${claim ? "Not now" : "Cancel"}</button>
+            <button id="consent-allow" class="btn btn-primary btn-lg" type="button">${claim ? "Claim workspace" : "Allow"}</button>
           </div>
           <p class="consent-switch"><button id="consent-switch" class="btn btn-quiet btn-sm" type="button">Use a different account</button></p>
         </div>
         <p id="consent-error" class="field-error" role="alert"></p>
       </div>
-      <p class="auth-foot">You can remove this connection anytime by deleting its key in the Muxo console.</p>
+      <p class="auth-foot">${claim ? "Only the invited email can claim this workspace, and the link works once." : "You can remove this connection anytime by deleting its key in the Muxo console."}</p>
     </div>
   </main>
   <script>window.MUXO_CONSENT = ${inlineJson(config)};${consentScript}</script>

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const MUXO_VERSION = "1.3.2";
+export declare const MUXO_VERSION = "1.4.0";

package/dist/version.js

@@ -1 +1 @@
-export const MUXO_VERSION = "1.3.2";
+export const MUXO_VERSION = "1.4.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@muxoai/platform",
-  "version": "1.3.2",
+  "version": "1.4.0",
   "description": "Muxo — Unified Execution, Provisioning & Governance Platform over Composio, Stripe Projects, Microsoft Agent Governance & Supermemory",
   "private": false,
   "license": "MIT",