@muxoai/sdk 0.4.0-preview.20261015.1 → 1.2.0

package/README.md

@@ -1,22 +1,54 @@
-# Muxo SDK preview
+# Muxo (`@muxoai/platform`)
 
-Install with `npm install @muxoai/sdk@preview`. Node.js 22.18 or newer is required.
+Muxo is a 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.
 
-```js
-import { MuxoClient } from '@muxoai/sdk';
-const client = new MuxoClient({
-  baseUrl: 'https://app.muxo.ai',
-  credential: () => process.env.MUXO_API_KEY,
-});
-const profile = await client.call('get_profile', {});
+See [`ARCHITECTURE.md`](./ARCHITECTURE.md) for the complete internal engineering blueprint, open-source ecosystem Keep/Adopt/Drop matrix, and root-cause analysis of how `muxo3` resolves `muxo2`'s Cloudflare isolate/container failure modes.
+
+Under the hood, Muxo unifies **four core pillars** behind one 18-operation MCP contract, REST API, CLI, and Web Console:
+
+1. **Composio Connected Apps (`app.*`) & Instant (`instant.*`)** — Managed OAuth SaaS integrations (`app.github.*`, `app.gmail.*`, `app.slack.*`, `app.notion.*`, `app.linear.*`), zero-OAuth instant capabilities (`instant.web.search`, `instant.web.scrape`, `instant.hackernews.top_stories`, `instant.github.repo_intel`, `instant.dns.lookup`), plus **Autonomous 2-Call Agent Signup & Claim** (`POST /api/v1/agents/signup` + `POST /api/v1/agents/claim`).
+2. **Stripe Projects Cloud Infrastructure (`resource.*`) + Stripe Billing** — Governed cloud resource provisioning across 60+ providers (`Neon`, `Supabase`, `Turso`, `Cloudflare`, `Vercel`, `Railway`, `Render`, `Prisma`, `PostHog`, etc.) with automatic `PLAN_REQUIRED` companion plan resolution, AES-256-GCM encrypted secret custody (`muxo env pull`), and live Stripe Checkout (`$29/mo Starter` & `$10 / +1,000 Credits`).
+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`.
+
+---
+
+## Quickstart
+
+```bash
+# 1. Build TypeScript
+npm run build
+
+# 2. Run the 9-Suite Live E2E Verification
+npm test
+
+# 3. Start the Muxo Server + app.muxo.ai Console (/) + muxo.ai Canvas (/landing) + MCP (/mcp)
+npm start
+
+# 4. Use the Muxo CLI
+npm run cli -- whoami
+npm run cli -- search postgres
+npm run cli -- exec instant.hackernews.top_stories --input '{"limit":3}'
+npm run cli -- env pull --out .env.muxo
 ```
 
-Explicit native company context uses `client.call('get_organization', { company_context: {} })`.
-Use `client.workspaceCurrent({ operation: 'memory_profile', arguments: { input: {} } })` for bounded accepted memory in the authenticated workspace/project.
-`resolveWorkspace()` returns routing metadata, not membership or authority. A different project refuses, and no workspace is initialized or silently substituted.
+## Architecture & Source Layout
 
-Use a protected scoped credential. Never embed credentials in browser bundles.
-Discover and inspect exact available tools before planning. Human approval remains separate.
-No automatic retry, supplier signup, payment or approval is performed by the client.
-The latest tag remains the incompatible legacy SDK. Cloudflare inbox/artifact capabilities remain local-only until separately qualified and activated.
-See https://docs.muxo.ai for current endpoint contracts and availability.
+| File / Directory | Responsibility |
+| --- | --- |
+| `ARCHITECTURE.md` | Internal engineering blueprint, Keep/Adopt/Drop ecosystem matrix, and Stripe Projects analysis |
+| `src/config.ts` | Environment & AES-256-GCM vault key derivation |
+| `src/types.ts` | Core domain, Governance `DecisionRecord`, Supermemory `MemoryContextSummary`, & 18-tool MCP types |
+| `src/store.ts` | SQLite (`node:sqlite`) store, AES-256-GCM secret vault, credit ledger, memories, agent claims, and HMAC-SHA256 receipt chain |
+| `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 zero-setup adapter |
+| `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/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 18 canonical MCP operations |
+| `src/mcp.ts` | JSON-RPC 2.0 MCP Server (Streamable HTTP `/mcp` + stdio `muxo mcp`) |
+| `src/server.ts` | HTTP Gateway (`/api/v1/*`, `/mcp`, `/skill.md`, `/llms.txt`, `/landing`, `/claim/:slug`, `/health`, and `/`) |
+| `src/ui/console-html.ts` | `app.muxo.ai` Operator Console UI + `/landing` (`muxo.ai` Provider Canvas) |
+| `web/` | Standalone `muxo.ai` Astro marketing & interactive provider catalog site |
+| `vendor/microsoft-governance/` | Vendored `@microsoft/agent-governance-sdk` v5.0.0 |

package/dist/sdk.d.ts

@@ -0,0 +1,115 @@
+import type { ActionPlan, ConnectionRecord, ExecutionReceipt, ExecutionRun, MuxoTool, ProviderLane, ProvisionedResource, RiskLevel, SupplierSettlementSummary, Workspace, WorkspaceMemoryRecord } from "./types.js";
+export interface MuxoClientOptions {
+    baseUrl?: string;
+    apiKey?: string | (() => string | Promise<string>);
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+}
+export declare class MuxoClient {
+    readonly baseUrl: string;
+    private readonly apiKeyResolver?;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    constructor(options?: MuxoClientOptions);
+    private request;
+    signupAgent(params: {
+        agentName?: string;
+        harness?: string;
+    }): Promise<{
+        ok: true;
+        agentId: string;
+        workspace: Pick<Workspace, "id" | "name" | "slug" | "tier" | "creditsBalance">;
+        apiKey: string;
+        mcpEndpoint: string;
+        skillUrl: string;
+        claimEndpoint: string;
+        governanceDid: string;
+        supermemoryNamespace: string;
+    }>;
+    searchTools(params?: {
+        query?: string;
+        lane?: ProviderLane | "all";
+        riskLevel?: RiskLevel;
+        limit?: number;
+    }): Promise<{
+        ok: true;
+        count: number;
+        tools: MuxoTool[];
+    }>;
+    inspectTool(slug: string): Promise<MuxoTool>;
+    planAction(params: {
+        toolSlug: string;
+        input: Record<string, unknown>;
+        reason?: string;
+    }): Promise<{
+        ok: true;
+        plan: ActionPlan;
+        nextStep: string;
+        authHandoff?: {
+            required: boolean;
+            providerSlug: string;
+            providerName: string;
+            status: string;
+            redirectUrl: string | null;
+            waitTool: string;
+            instructions: string;
+        };
+    }>;
+    approvePlan(planId: string): Promise<{
+        ok: true;
+        plan: ActionPlan;
+    }>;
+    executePlan(planId: string): Promise<{
+        ok: true;
+        run: ExecutionRun;
+        receipt: ExecutionReceipt;
+    }>;
+    startConnection(params: {
+        provider: string;
+        lane?: ProviderLane;
+        callbackUrl?: string;
+    }): Promise<{
+        ok: true;
+        connection: ConnectionRecord;
+    }>;
+    waitForConnection(params: {
+        provider: string;
+        timeoutSeconds?: number;
+    }): Promise<{
+        ok: true;
+        connection: ConnectionRecord;
+        ready: boolean;
+        polledAttempts: number;
+        elapsedMs: number;
+        message: string;
+    }>;
+    listResources(): Promise<{
+        ok: true;
+        resources: ProvisionedResource[];
+    }>;
+    pullEnv(): Promise<{
+        ok: true;
+        workspaceId: string;
+        variables: Record<string, string>;
+        dotenv: string;
+    }>;
+    topupCredits(params: {
+        credits: number;
+        description?: string;
+    }): Promise<{
+        ok: true;
+        creditsAdded: number;
+        usdPaid: number;
+        workspace: Workspace;
+        settlementSummary: SupplierSettlementSummary;
+    }>;
+    getSettlements(): Promise<{
+        ok: true;
+        settlementSummary: SupplierSettlementSummary;
+    }>;
+    recallMemory(query?: string): Promise<{
+        ok: true;
+        namespace: string;
+        records: WorkspaceMemoryRecord[];
+    }>;
+}

package/dist/sdk.js

@@ -0,0 +1,117 @@
+export class MuxoClient {
+    baseUrl;
+    apiKeyResolver;
+    fetchImpl;
+    timeoutMs;
+    constructor(options = {}) {
+        this.baseUrl = (options.baseUrl ||
+            process.env.MUXO_BASE_URL ||
+            "https://app.muxo.ai").replace(/\/+$/, "");
+        if (typeof options.apiKey === "function") {
+            this.apiKeyResolver = options.apiKey;
+        }
+        else if (typeof options.apiKey === "string") {
+            const key = options.apiKey;
+            this.apiKeyResolver = () => key;
+        }
+        else if (process.env.MUXO_API_KEY) {
+            const key = process.env.MUXO_API_KEY;
+            this.apiKeyResolver = () => key;
+        }
+        this.fetchImpl = options.fetch || fetch;
+        this.timeoutMs = options.timeoutMs ?? 30000;
+    }
+    async request(path, init = {}) {
+        const headers = {
+            Accept: "application/json",
+        };
+        if (this.apiKeyResolver) {
+            const token = await this.apiKeyResolver();
+            if (token)
+                headers.Authorization = `Bearer ${token}`;
+        }
+        if (init.body !== undefined) {
+            headers["Content-Type"] = "application/json";
+        }
+        const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+            method: init.method || "GET",
+            headers,
+            body: init.body !== undefined ? JSON.stringify(init.body) : undefined,
+            signal: AbortSignal.timeout(this.timeoutMs),
+        });
+        const payload = (await res.json());
+        if (!res.ok || payload.ok === false) {
+            throw new Error(String(payload.error || `Muxo request failed with HTTP ${res.status}`));
+        }
+        return payload;
+    }
+    async signupAgent(params) {
+        return this.request("/api/v1/agents/signup", {
+            method: "POST",
+            body: params,
+        });
+    }
+    async searchTools(params) {
+        const qs = new URLSearchParams();
+        if (params?.query)
+            qs.set("query", params.query);
+        if (params?.lane)
+            qs.set("lane", params.lane);
+        if (params?.riskLevel)
+            qs.set("risk_level", params.riskLevel);
+        if (params?.limit)
+            qs.set("limit", String(params.limit));
+        const suffix = qs.toString() ? `?${qs.toString()}` : "";
+        return this.request(`/api/v1/tools${suffix}`);
+    }
+    async inspectTool(slug) {
+        return this.request(`/api/v1/tools/${encodeURIComponent(slug)}`);
+    }
+    async planAction(params) {
+        return this.request("/api/v1/plans", {
+            method: "POST",
+            body: params,
+        });
+    }
+    async approvePlan(planId) {
+        return this.request(`/api/v1/plans/${encodeURIComponent(planId)}/approve`, {
+            method: "POST",
+        });
+    }
+    async executePlan(planId) {
+        return this.request(`/api/v1/plans/${encodeURIComponent(planId)}/execute`, {
+            method: "POST",
+        });
+    }
+    async startConnection(params) {
+        return this.request("/api/v1/connections", {
+            method: "POST",
+            body: params,
+        });
+    }
+    async waitForConnection(params) {
+        return this.request("/api/v1/connections/wait", {
+            method: "POST",
+            body: params,
+        });
+    }
+    async listResources() {
+        return this.request("/api/v1/resources");
+    }
+    async pullEnv() {
+        return this.request("/api/v1/resources/env");
+    }
+    async topupCredits(params) {
+        return this.request("/api/v1/billing/topup", {
+            method: "POST",
+            body: params,
+        });
+    }
+    async getSettlements() {
+        return this.request("/api/v1/billing/settlements");
+    }
+    async recallMemory(query) {
+        const suffix = query ? `?query=${encodeURIComponent(query)}` : "";
+        return this.request(`/api/v1/memory${suffix}`);
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,273 @@
+export type RiskLevel = "read" | "write" | "admin" | "financial" | "provisioning" | "destructive";
+export type ProviderLane = "composio_sdk" | "composio_instant" | "stripe_projects";
+export type SubscriptionTier = "free" | "starter";
+export interface GovernancePolicy {
+    mode: "monitor" | "enforce";
+    requireApprovalFor: RiskLevel[];
+    allowInstantWallet: boolean;
+    allowProvisioning: boolean;
+    maxCreditsPerRun: number;
+    blockedToolSlugs?: string[];
+}
+export interface User {
+    id: string;
+    email: string;
+    name: string;
+    workspaceId: string;
+    role: "owner" | "admin" | "member";
+    createdAt: string;
+}
+export interface Workspace {
+    id: string;
+    name: string;
+    slug: string;
+    ownerUserId: string;
+    tier: SubscriptionTier;
+    monthlyActionsLimit: number;
+    monthlyActionsUsed: number;
+    creditsBalance: number;
+    stripeCustomerId: string | null;
+    stripeSubscriptionId: string | null;
+    projectsEnvName: string;
+    policy: GovernancePolicy;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ApiKeyRecord {
+    id: string;
+    workspaceId: string;
+    name: string;
+    keyPrefix: string;
+    environment: "live" | "test";
+    scopes: string[];
+    lastUsedAt: string | null;
+    revokedAt: string | null;
+    createdAt: string;
+}
+export interface MuxoTool {
+    slug: string;
+    upstreamSlug: string;
+    name: string;
+    description: string;
+    lane: ProviderLane;
+    providerSlug: string;
+    providerName: string;
+    categories: string[];
+    riskLevel: RiskLevel;
+    requiresAuth: boolean;
+    creditCost: number;
+    billingMode: "customer_oauth" | "provider_wallet" | "resource_provisioning";
+    inputSchema: Record<string, unknown>;
+    llmContextUrl?: string;
+    providerUrl?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface ConnectionRecord {
+    id: string;
+    workspaceId: string;
+    lane: ProviderLane;
+    providerSlug: string;
+    providerName: string;
+    status: "active" | "pending" | "expired" | "disconnected";
+    externalAccountId: string | null;
+    redirectUrl: string | null;
+    metadata: Record<string, unknown>;
+    updatedAt: string;
+    createdAt: string;
+}
+export interface ProvisionedResource {
+    id: string;
+    workspaceId: string;
+    resourceName: string;
+    providerSlug: string;
+    providerName: string;
+    serviceSlug: string;
+    planSlug: string | null;
+    status: "active" | "provisioning" | "failed" | "removed";
+    envVarKeys: string[];
+    externalResourceId: string | null;
+    metadata: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface GovernanceDecisionRecord {
+    id: string;
+    sdk: "@microsoft/agent-governance-sdk";
+    sdkVersion: string;
+    policyId: string;
+    mode: "monitor" | "enforce";
+    agentDid: string;
+    agentPublicKey: string;
+    actorId: string;
+    workspaceId: string;
+    action: string;
+    riskLevel: RiskLevel;
+    decision: "allow" | "deny" | "require_approval";
+    verdict: "allow" | "deny" | "escalate";
+    reason: string;
+    matchedRule: string | null;
+    securityScan: {
+        safe: boolean;
+        riskLevel: string;
+        findingsCount: number;
+        findings: Array<{
+            category: string;
+            severity: string;
+            description: string;
+        }>;
+    };
+    auditEntry: {
+        timestamp: string;
+        agentId: string;
+        action: string;
+        decision: "allow" | "deny";
+        hash: string;
+        previousHash: string;
+        chainVerified: boolean;
+    };
+    ed25519Signature: string;
+    signature: string;
+    bindingHash: string;
+    decidedAt: string;
+}
+export type MemoryRecordKind = "fact" | "preference" | "resource_note" | "operator_note" | "execution_outcome" | "resource_topology" | "policy_decision";
+export interface MemoryContextSummary {
+    enabled: boolean;
+    namespace: string;
+    staticFacts: string[];
+    dynamicContext: string[];
+    recalledMemories: Array<{
+        documentId: string;
+        title: string;
+        snippet: string;
+        similarity: number;
+        createdAt?: string;
+    }>;
+    formattedPromptContext: string;
+    profile: {
+        static: string[];
+        dynamic: string[];
+        preferences: string[];
+    };
+    relevantMemories: Array<{
+        documentId: string;
+        title: string;
+        snippet: string;
+        similarity: number;
+        createdAt?: string;
+    }>;
+}
+export interface WorkspaceMemoryRecord {
+    id: string;
+    workspaceId: string;
+    namespace: string;
+    documentId: string;
+    title: string;
+    content: string;
+    kind: MemoryRecordKind;
+    metadata: Record<string, unknown>;
+    createdAt: string;
+}
+export interface SupplierSettlement {
+    fundingMode: "muxo_funded";
+    supplier: ProviderLane;
+    supplierName: string;
+    upstreamProvider: string;
+    userChargeCredits: number;
+    userRetailChargeCents: number;
+    supplierWholesalePayableCents: number;
+    muxoNetMarginCents: number;
+    settlementStatus: "settled_by_muxo_master_wallet" | "planned_muxo_master_wallet";
+    masterAccountRef: string;
+}
+export interface SupplierSettlementSummary {
+    workspaceId: string;
+    fundingModel: "user_pays_muxo_muxo_pays_suppliers";
+    creditPriceCents: number;
+    totalCreditsPurchasedOrGranted: number;
+    totalCreditsConsumed: number;
+    currentCreditsBalance: number;
+    totalUserRetailSpendCents: number;
+    totalSupplierWholesalePaidCents: number;
+    totalMuxoNetMarginCents: number;
+    bySupplier: Record<ProviderLane, {
+        runsCount: number;
+        creditsConsumed: number;
+        userRetailSpendCents: number;
+        supplierWholesalePaidCents: number;
+        muxoNetMarginCents: number;
+    }>;
+}
+export interface ActionPlan {
+    id: string;
+    workspaceId: string;
+    actorId: string;
+    toolSlug: string;
+    upstreamSlug: string;
+    lane: ProviderLane;
+    riskLevel: RiskLevel;
+    input: Record<string, unknown>;
+    reason: string;
+    creditCost: number;
+    approvalStatus: "auto_approved" | "pending_approval" | "approved" | "rejected" | "executed";
+    approvedBy: string | null;
+    approvedAt: string | null;
+    runId: string | null;
+    decisionRecord?: GovernanceDecisionRecord | null;
+    memoryContext?: MemoryContextSummary | null;
+    supplierSettlement?: SupplierSettlement | null;
+    createdAt: string;
+    expiresAt: string;
+}
+export interface ExecutionRun {
+    id: string;
+    planId: string;
+    workspaceId: string;
+    actorId: string;
+    toolSlug: string;
+    lane: ProviderLane;
+    riskLevel: RiskLevel;
+    status: "queued" | "running" | "succeeded" | "failed" | "cancelled";
+    input: Record<string, unknown>;
+    output: Record<string, unknown> | null;
+    error: string | null;
+    actionsMetered: number;
+    creditsMetered: number;
+    durationMs: number | null;
+    receiptId: string | null;
+    startedAt: string;
+    completedAt: string | null;
+}
+export interface ExecutionReceipt {
+    id: string;
+    runId: string;
+    planId: string;
+    workspaceId: string;
+    actorId: string;
+    toolSlug: string;
+    lane: ProviderLane;
+    riskLevel: RiskLevel;
+    status: "succeeded" | "failed" | "cancelled";
+    actionsMetered: number;
+    creditsMetered: number;
+    inputHash: string;
+    outputHash: string;
+    prevReceiptHash: string;
+    receiptHash: string;
+    signature: string;
+    decisionRecord?: GovernanceDecisionRecord | null;
+    supplierSettlement?: SupplierSettlement | null;
+    issuedAt: string;
+}
+export interface LedgerEntry {
+    id: string;
+    workspaceId: string;
+    kind: "plan_grant" | "credit_topup" | "run_deduction" | "subscription_upgrade" | "manual_adjustment";
+    actionsDelta: number;
+    creditsDelta: number;
+    balanceAfter: number;
+    referenceId: string | null;
+    description: string;
+    supplierSettlement?: SupplierSettlement | null;
+    createdAt: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,33 +1,40 @@
 {
   "name": "@muxoai/sdk",
-  "version": "0.4.0-preview.20261015.1",
-  "description": "Typed Muxo client for governed actions at app.muxo.ai.",
-  "type": "module",
+  "version": "1.2.0",
+  "description": "Muxo TypeScript/JavaScript SDK — Typed client for governed agent actions, OAuth handoffs, infrastructure provisioning, and receipts",
   "license": "MIT",
+  "homepage": "https://muxo.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/muxoai/muxo.git"
+  },
+  "keywords": [
+    "muxo",
+    "sdk",
+    "agents",
+    "mcp",
+    "composio",
+    "stripe",
+    "governance",
+    "supermemory"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/sdk.js",
+  "types": "./dist/sdk.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "types": "./dist/sdk.d.ts",
+      "default": "./dist/sdk.js"
     }
   },
-  "types": "./dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "engines": {
-    "node": ">=22.18.0"
-  },
-  "homepage": "https://docs.muxo.ai",
-  "keywords": [
-    "muxo",
-    "sdk",
-    "agents"
-  ],
-  "dependencies": {
-    "zod": "4.6.5"
-  },
-  "publishConfig": {
-    "access": "public",
-    "tag": "preview"
+    "node": ">=18.0.0"
   }
 }