@muxoai/platform 0.0.0-stage → 1.2.1

package/ARCHITECTURE.md

@@ -0,0 +1,111 @@
+# Muxo Internal Architecture & Open-Source Ecosystem Blueprint
+
+> **Purpose:** Definitive internal engineering guide on how to build Muxo cleanly, what external/open-source infrastructure to leverage, what legacy complexity from `muxoai` and `muxo2` to permanently drop, and how our four pillars (**Composio**, **Stripe Projects**, **Microsoft Agent Governance Toolkit**, and **Supermemory v5**) fit together.
+
+---
+
+## 1. Core Thesis: What Muxo Actually Is
+
+Developers already have an agent harness (**Claude Code, Cursor, Factory Droid, OpenCode, Pi, Mastra, Vercel AI SDK, or Google ADK**). They do **not** want another mandatory chat window or proprietary agent framework.
+
+**Muxo is the Unified Execution, Infrastructure, Memory, and Governance Boundary for existing agents.**
+
+A customer connects their agent to **one Muxo MCP endpoint (`/mcp`)** with **one Muxo key (`mk_live_...`)**, and Muxo handles:
+
+```text
+Agent (Claude / Cursor / Droid / Mastra / Pi / AI SDK)
+  │
+  ▼
+Muxo Gateway (app.muxo.ai / api.muxo.ai)
+  ├─► 1. Microsoft Agent Governance Toolkit (@microsoft/agent-governance-sdk)
+  │      McpSecurityScanner ──► PolicyEngine ──► AgentIdentity (Ed25519 DID) ──► AuditLogger ──► DecisionRecord
+  │
+  ├─► 2. Supermemory v5 Contextual Brain (supermemory SDK v5)
+  │      Workspace Profile (/ns/{ws}/profile) + Hybrid Recall (/ns/{ws}/search) + Post-Run Memory (/ns/{ws}/document)
+  │
+  ├─► 3. Execution & Provisioning Lanes
+  │      ├─► Lane A: Composio Instant (instant.*)  ──► Zero-OAuth tools (search, scrape, repo intel, HN, DNS)
+  │      ├─► Lane B: Composio SDK (app.*)          ──► 500+ Managed OAuth SaaS tools (GitHub, Slack, Gmail, Linear...)
+  │      └─► Lane C: Stripe Projects (resource.*)  ──► Live Cloud Infrastructure Provisioning + AES-256-GCM Secret Vault
+  │
+  └─► 4. Cryptographic Receipt & Prepaid Ledger
+         HMAC-SHA256 + Ed25519 Signed Receipt Chain + Stripe Checkout Credit Fulfillment
+```
+
+---
+
+## 2. Ecosystem Evaluation: What to Use vs. What to Drop
+
+Across `muxoai` (gen 1) and `muxo2` (gen 2, 203,443 LOC), the biggest mistake was rebuilding infrastructure that best-in-class open-source packages and managed APIs already solve. Here is our strict **Keep / Adopt / Drop** decision matrix:
+
+| Layer / Candidate | Verdict | Why & How Muxo Uses It | What It Replaces from `muxoai` / `muxo2` |
+| :--- | :--- | :--- | :--- |
+| **Composio SDK & Tool Router** (`backend.composio.dev/api/v3`) | **ADOPT (Core Lane)** | Provides 500+ managed OAuth integrations (`app.*`), user-scoped Connect Links, and schema discovery without Muxo maintaining custom OAuth apps for every SaaS provider. | Replaces custom per-provider OAuth brokers and bespoke SaaS connectors. |
+| **Composio Instant & `agents.composio.dev` Pattern** | **ADOPT (Core Lane + Onboarding)** | 1) Zero-setup `instant.*` tools work immediately on workspace creation.<br>2) We adopt the **`agents.composio.dev` 2-call autonomous signup pattern** (`POST /api/v1/agents/signup` + `POST /api/v1/agents/claim`) so an agent can self-provision a Muxo workspace in one HTTP call and later hand ownership over to its human via a claim slug. | Replaces complex multi-step human-only bootstrap ceremonies for CLI/agent onboarding. |
+| **Stripe Projects CLI** (`stripe projects` v0.50.0) | **ADOPT (Core Lane — Node Runtime)** | Provisions real databases, caches, and cloud services (`neon/postgres`, `upstash/redis`, `turso`, `supabase`, `supermemory/memory`, etc.) and pulls credentials (`stripe projects env --pull`) into Muxo's AES-256-GCM vault. | Replaces `muxo2`'s broken 4-worker Cloudflare Container + mTLS bridge (`projects-gateway` + `projects-executor`). See Section 3 below. |
+| **Microsoft Agent Governance Toolkit** (`@microsoft/agent-governance-sdk` v5.0.0) | **ADOPT (Core Governance)** | A 40 KB, zero-dependency, MIT-licensed SDK providing `McpSecurityScanner` (prompt-injection & exfiltration detection), `PolicyEngine` (YAML/JSON rules + risk gates), `AgentIdentity` (Ed25519 DIDs), and `AuditLogger` (SHA-256 tamper-evident hash chain). | Replaces **~18,000 LOC** of custom authority seals, custom policy DSLs, and hand-rolled audit chains in `muxo2`. |
+| **Supermemory v5** (`supermemory` `^5.0.1`) | **ADOPT (Fail-Open Contextual Brain)** | Gives every Muxo workspace an isolated `/ns/muxo-v5-{hash}` brain with automatic `static` + `dynamic` profiles (`client.profile`), sub-50ms hybrid search (`client.search`), and governed post-run memory (`client.add`). Also natively deployable via Stripe Projects (`supermemory/memory`)! | Replaces **~25,000 LOC** of `muxoai/packages/brain` + Python `context-engine` (Graphiti + Neo4j + Vectorize + D1). |
+| **Mastra (`@mastra/mcp`), Pi (`pi`), Vercel AI SDK (`ai`), Google ADK** | **CLIENT ECOSYSTEM (Do Not Bundle Inside Server)** | These are **agent harnesses** that *consume* Muxo over `/mcp` and `/skill.md`. Bundling an agent framework inside the Muxo server violates "Existing-Agent First" and bloats the runtime. Instead, `app.muxo.ai` and `muxo mcp-config` generate instant copy-paste connectors for Mastra, Pi, Vercel AI SDK, Claude Code, Cursor, and Factory Droid. | Drops `muxoai/packages/harness` (`@cloudflare/think` + custom chat UI) from the core execution server. |
+| **Open-Source Monid** (`monid-upstream`) | **OPTIONAL / DEFER** | `muxoai` imported 413 Monid definitions, but 408 were unquoted and 69 had broken request/output hooks (`LEARNING.md` F10/F11). Composio Instant + Composio SDK + Stripe Projects already cover >95% of real developer tasks with live execution. | Drops 400+ unverified/quarantined static connector stubs and the Deno fixture bridge. |
+| **Web Surfaces (`muxo.ai`, `docs.muxo.ai`, `app.muxo.ai`)** | **KEEP & UNIFY** | • **`muxo.ai`**: Existing Astro interactive provider-grid canvas (`web/`).<br>• **`docs.muxo.ai`**: Existing Mintlify deployment (`subdomain: muxo-ai`).<br>• **`app.muxo.ai`**: Built-in operator console in `muxo3` sharing the exact `muxo.ai` design tokens and navigation links. | Replaces 60,000+ LOC of duplicate SSR rendering in `muxo2/apps/console` and `muxo2/apps/web`. |
+
+---
+
+## 3. Why Stripe Projects Provisioning Failed in `muxo2` — And Why It Works Live in `muxo3`
+
+### Why `muxo2` Disabled Stripe Projects Provisioning
+In `muxo2` (`projects-production-completion-plan.md`), the runtime was built on **Cloudflare Workers (V8 isolates)**. Because V8 isolates cannot spawn OS processes or run the native Go `stripe` CLI and `~/.stripe/plugins/apps/projects/0.50.0/stripe-projects-cli` binary:
+1. `muxo2` tried to wrap the Stripe CLI inside a separate **Cloudflare Container (`apps/projects-executor`)** behind a second **Cloudflare Worker (`apps/projects-gateway`)** with custom CA fingerprint pinning, UID=0 root directory checks, and 55-second container cold-start budgets.
+2. Inside the container, the `stripe-projects-cli` plugin was invoked directly without `PROJECTS_STANDALONE=1` or exceeded container memory/startup deadlines, resulting in `SIGKILL` and 9 consumed diagnostic attempts.
+
+### Why It Works 100% Live in `muxo3`
+In `muxo3` (`src/providers/stripe-projects.ts`):
+1. **Native Node.js 22 Runtime:** `muxo3` runs as a standard Node.js 22 process (locally or in a standard persistent Linux container on Railway/Fly.io/Render) and invokes `/Users/test/.local/bin/stripe projects ... --json` directly via `node:child_process`.
+2. **Automatic Companion Plan Resolution:** When a deployable service (like `neon/postgres`) returns `PLAN_REQUIRED`, `StripeProjectsAdapter.provisionResource()` automatically inspects the provider catalog, provisions the free/default plan (`neon/free`), and completes `neon/postgres` provisioning in one seamless transaction.
+3. **Encrypted Vault Custody:** Immediately after provisioning, `StripeProjectsAdapter` runs `stripe projects env --pull`, captures the real credentials (e.g., `NEON_POSTGRES_CONNECTION_STRING`), encrypts them with **AES-256-GCM** using a per-workspace HKDF-derived key in `MuxoStore` (`src/store.ts`), and exposes them only via explicit owner-authenticated `muxo env pull` or `GET /api/v1/resources/env`.
+
+---
+
+## 4. Detailed Architecture of the 4 Core Pillars in `muxo3`
+
+### Pillar 1: Microsoft Agent Governance Toolkit (`src/providers/microsoft-governance.ts`)
+
+Every call to `plan_action` and `execute_<risk>` passes through the Microsoft Agent Governance pipeline:
+
+```mermaid
+flowchart LR
+    A[Agent Tool Call] --> B[McpSecurityScanner]
+    B --> C[PolicyEngine]
+    C --> D[AgentIdentity Ed25519]
+    D --> E[AuditLogger Hash Chain]
+    E --> F[Signed DecisionRecord]
+```
+
+1. **`McpSecurityScanner`:** Scans tool inputs and schemas for prompt injection (`ignore previous instructions`), shell injection, path traversal (`../`), and credential leaks before a plan is created.
+2. **`PolicyEngine`:** Loads workspace governance rules (`allow` / `deny`, blocked tool patterns, risk-level approval gates, and `monitor` vs. `enforce` mode).
+3. **`AgentIdentity`:** Mints a persistent Ed25519 cryptographic Decentralized Identifier (`did:agent:muxo:<workspaceSlug>`) per workspace and signs the canonical decision payload.
+4. **`AuditLogger`:** Appends the decision to a SHA-256 hash chain (`previousHash ──► hash`), verifies chain integrity (`audit.verify()`), and embeds the resulting **`DecisionRecord`** inside the `ActionPlan` and `ExecutionReceipt`.
+
+### Pillar 2: Supermemory v5 Contextual Brain (`src/providers/supermemory.ts`)
+
+Supermemory v5 provides context-aware tool execution without turning Muxo into a heavyweight LLM host:
+1. **Strict Namespace Isolation:** Every workspace maps to `muxo-v5-<sha256(workspaceId).slice(0, 24)>` (matching Supermemory v5's `^[a-zA-Z0-9_:-]+$` regex).
+2. **Secret Redaction Guard:** Before any content is sent to `client.add()`, `SupermemoryAdapter.sanitizeContent()` strips bearer tokens, API keys (`sk_live_`, `mk_live_`, `sm_`, `ak_`), connection strings (`postgres://`, `redis://`), and `.env` assignments so secrets **never** leave the local AES-256-GCM vault.
+3. **Context-Aware `plan_action` & `get_run_context`:**
+   - When an agent calls `get_run_context`, Muxo fetches `client.profile(namespace)` (returning `static` workspace facts and `dynamic` recent context) alongside active Stripe Projects resources.
+   - When an agent calls `plan_action({ toolSlug, input, reason })`, Muxo runs `client.search(namespace, { query: "${toolSlug} ${reason}", searchMode: "hybrid" })` and attaches top relevant workspace memories (`memoryContext`) to the plan response.
+4. **Automatic Post-Execution Learning:** When a governed run finishes (`execute_<risk>`), Muxo records a sanitized execution summary (`taskType: "memory"`, `dreaming: true`) into the workspace's Supermemory namespace so future runs remember what infrastructure was provisioned and what actions succeeded.
+
+### Pillar 3: Agent-First Autonomous Onboarding (`POST /api/v1/agents/signup`)
+
+Inspired directly by `https://agents.composio.dev/`:
+- **Call 1 (`POST /api/v1/agents/signup`):** An autonomous agent calls `/api/v1/agents/signup` with zero human interaction required. Muxo mints an isolated workspace (`amber-cedar-otter`), an Ed25519 Agent DID (`did:agent:muxo:amber-cedar-otter`), a scoped API key (`mk_live_...`), and a Supermemory v5 namespace, returning ready-to-use MCP configuration immediately.
+- **Call 2 (`POST /api/v1/agents/claim` — Optional):** When the agent wants a human owner to take over the workspace (to approve `provisioning` / `financial` actions or top up Stripe credits), it calls `/api/v1/agents/claim` with `{ email }` and receives a single-use `claim_slug` URL for the human operator.
+
+### Pillar 4: Unified Web Surfaces (`muxo.ai`, `docs.muxo.ai`, `app.muxo.ai`)
+
+| Surface | Domain | Source Location | Role |
+| :--- | :--- | :--- | :--- |
+| **Marketing & Interactive Provider Canvas** | `muxo.ai` | `/Users/test/muxo3/web` (Astro) & built-in `GET /landing` | Interactive draggable grid of 60+ app & cloud providers with keyboard/search navigation (`Catalog.astro`). |
+| **Documentation** | `docs.muxo.ai` | Mintlify (`subdomain: muxo-ai`) | Guides, 18 MCP operation reference, CLI & SDK quickstarts, and governance documentation. |
+| **Operator Console & Runtime** | `app.muxo.ai` | `/Users/test/muxo3/src/ui/console-html.ts` (`GET /`) | Live workspace console for Catalog & Instant Try, Connected Apps, Stripe Projects Vault, Approvals & Receipts, **Supermemory Brain**, **Microsoft Agent Governance**, and **Stripe Billing**. |

package/README.md

@@ -1,3 +1,54 @@
-# Temporary Holding Version
+# Muxo (`@muxoai/platform`)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+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
+```
+
+## Architecture & Source Layout
+
+| 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/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};