Cascade

From a message to a governed purchase, with the smallest safe agent topology.

Cascade is a governed commerce kernel for agentic buying. A natural-language request becomes an immutable purchase contract; Cascade verifies one offer against approved sources, obtains bounded passkey authority through Prava, completes checkout on a tested merchant path, and returns an auditable receipt to the originating conversation or client.

Models propose. Deterministic code owns money and state. No search agent holds a wallet. No AI advances a financial state alone.

The same kernel is reachable through the web companion, authenticated MCP tools, and optional messaging adapters. The distinguishing system is not retrieval — it is the purchase contract, evidence-backed offer normalization, capability narrowing, passkey-bound authority, exact checkout reconciliation, revocation, and audit trail.

Full product and architecture specification: context.md

Cascade exposes governed commerce as MCP v2 Streamable HTTP. External agents create missions, inspect offers, request spend, and read audit events without receiving Prava secrets, merchant credentials, or payment instruments.

The server stores SHA-256 hashes only (MCP_AUTH_TOKENS_JSON). Each token’s audience must exactly match MCP_AUDIENCE (e.g. https://cascade-3mec.onrender.com/mcp). Generate a hash without putting the raw token in config:

export CASCADE_RAW_TOKEN='replace-with-a-long-random-token'
node -e "console.log(require('node:crypto').createHash('sha256').update(process.env.CASCADE_RAW_TOKEN).digest('hex'))"
unset CASCADE_RAW_TOKEN

Local Compose uses bearer cascade-local-dev-token (localhost only). Confirm health before connecting clients: GET /health/mcp.

~/.cursor/mcp.json (or Cursor MCP settings):

{
  "mcpServers": {
    "cascade": {
      "url": "https://cascade-3mec.onrender.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

For local development, point url at http://127.0.0.1:3001/mcp and use your local bearer. Reload MCP after saving.

Point a custom connector at https://<host>/mcp with:

Authorization: Bearer <your-token>

spend.request deliberately does not accept amount, currency, merchant, or product identity from the caller — those fields are rebound from the stored offer and active contract.

export CASCADE_MCP_ENDPOINT=https://cascade-3mec.onrender.com/mcp
export CASCADE_MCP_TOKEN=<your-token>

pnpm --filter @cascade/mcp-demo workflow:test -- \
  "Find red running shoes size 9 under INR 14000"

@cascade/mcp-demo wraps @modelcontextprotocol/client (Streamable HTTP) with typed helpers for the tools above.

Online commerce is easy to browse and hard to decide. Buyers translate vague intent into search queries, compare incomplete totals, judge seller trust, re-enter constraints across sites, coordinate money with other people, and still leave the conversation to complete checkout — often without knowing what an AI assistant is actually allowed to spend.

Shopping agents optimize retrieval. Payment products optimize transfer. Group planners optimize discussion. Cascade connects all three with explicit authority boundaries:

1. Intent becomes a contract.
2. Research becomes evidence-backed offers.
3. Authority becomes a bounded, revocable capability.
4. The purchase becomes a deterministic state machine.
5. The receipt returns to where the intent originated.

Cascade does not run a fixed multi-agent swarm. A deterministic router selects one of four execution modes:

A component is a separate agent only when it has a different owner, private context, independent authority, a trust boundary, fault containment needs, or speaks through MCP. “Price agent” and “review agent” are usually functions — not principals.

Topology routing, contract versioning, policy, reservations, idempotency, Prava gateway, checkout state machine, revocation, and the audit log are services, never models. Models may extract intent, search, summarize evidence, or propose a ranking. Typed code validates every financial transition.

• Final price is confirmed at checkout, not inferred from search.
• Live price and availability come from the merchant path — not from knowledge grounding.
• A Prava payment session grants bounded purchase authority; it is not an order.
• “Works at any merchant” is forbidden; only tested adapters and verified Prava/UCP paths.
• Authorization is never silently overspent when a quote drifts.

Signature path:

Find these red ASICS Gel-Kayano in size 9 under ₹14,000. Prefer delivery before Friday.

Cascade returns one best valid offer, explains why it won, discloses material trade-offs, and presents BUY. Passkey approval scopes merchant and amount. Checkout runs through a tested path; the receipt and audit trail close the mission.

A demo entry point that lets a shopper browse Cascade's sandbox catalog visually, capture a product card, and create a mission from it instead of typing a prompt. Nothing new is invented here: the marketplace reads the same MOCK_INDIA_LISTINGS registry that text-originated missions already search, and a captured product flows through the exact same kernel → mission search → mock-vendor quote → requestSpend → Prava REST sandbox → checkout pipeline as any other mission — there is no capture-specific quote, payment, or checkout code path.

apps/web/src/marketplace/*        Product grid, capture shortcut (⌘/Ctrl+Shift+K), review dialog
apps/server/src/marketplace-*.ts  Catalog read, capture API, screenshot storage, vision analysis job
packages/db/migrations/0016-0017  marketplace_captures table
packages/contracts                Marketplace/capture Zod schemas, capture.create_marketplace_mission MCP tool

Capture flow: select a product card → capture (behind explicit confirmation in a local review dialog; Cancel makes no network call) → server reloads the product/vendor/variant from the registry (client-claimed price/vendor/stock is never trusted) → vision model extracts facts for display only, never for identity — a conflict blocks mission creation rather than overriding the registry → Purchase Contract compiled with source: "visual_capture" and a budget grounded in the trusted price, capped at any explicit ceiling the shopper stated in free text → CascadeKernel.createMission → the shared mission pipeline takes over.

Every screen carries a sandbox notice; no real payment or merchant order is ever created. Screenshots are stored privately and deleted after MARKETPLACE_CAPTURE_RETENTION_MS (default 24h) regardless of mission outcome. The feature is inert unless both WEB_SESSION_SECRET and OPENAI_API_KEY are set.

pnpm --filter @cascade/server exec vitest run src/marketplace-capture.test.ts
pnpm --filter @cascade/server exec vitest run src/marketplace-capture.integration.test.ts
pnpm --filter @cascade/web test

Web companion · MCP clients · messaging adapters
                    │
                    ▼
         ┌─────────────────────┐
         │  Cascade kernel     │
         │  contracts · policy │
         │  ledger · topology  │
         │  LangGraph orches.  │
         └─────────┬───────────┘
                   │
     ┌─────────────┼─────────────┐
     ▼             ▼             ▼
  Merchants      Senso         Prava
  (quotes)    (evidence)   (passkey auth)

One TypeScript monorepo: Fastify API + worker, PostgreSQL ledger, LangGraph for durable orchestration, companion web for approval/audit/demo. Channels are adapters around the same domain services — MCP is the platform boundary, not a slide-only integration.

apps/server      API, Cascade MCP, worker
apps/web         Landing, chat, demo, payment return
apps/mcp-demo    External MCP client + workflow runners
packages/
  contracts      Shared schemas and MCP tool catalog
  domain         Deterministic purchase / ledger kernel
  agents         Orchestration and intent extraction
  db             Migrations and Postgres access
  integrations/  prava · senso · merchants · linq

Cascade’s outbound client to Prava shopping MCP is separate from the Cascade MCP server agents connect to. REST sk_test_* keys do not authorize Prava MCP.

pnpm --filter @cascade/prava mcp:login    # one-time OAuth; paste PRAVA_MCP_* into env
pnpm --filter @cascade/prava mcp:refresh  # access tokens expire ~10 minutes

Quote path: shop_search → shop_product → shop_quote. Keep PRAVA_MCP_CHECKOUT_ENABLED=false until an approved sandbox MCP hostname exists; hosted production MCP hosts are rejected for checkout.

• SHA-256 of MCP bearer tokens only — never raw tokens in config or git.
• Provider secrets never appear in browser VITE_* vars or MCP responses.
• Authorization ≠ order; checkout and receipt are separate states.
• “Verified by Senso” means grounded in approved ingested sources — not a live-price oracle.
• Mandate auto-charge remains fail-closed until a tested provider contract exists.

Yeah bro team omshantyom owns this. All rights reserved unless otherwise noted.