SpendLatch

Live demo: https://spendlatch.owain32380.cn — the web experience and the MCP endpoint (/mcp, Streamable HTTP) are both served publicly. All providers are simulated; no credentials exist anywhere.

MCP protocol & compatibility

The authorization boundary between an AI agent and a consequential action.

An agentic spend-remediation copilot for AI and cloud teams — it watches your bills across providers, proves the next move before proposing it, and executes only inside a mandate the server issues after a human session approves. Every decision, including every refusal, is recorded.

It doesn't wait for you to ask. It proves before it proposes. And it never moves a cent without your signed authorization.

The one-line version

"You are giving an AI permission to spend your money."

Say "buy me a replacement charger" and the agent will find one, prove the price is what it says, and then stop — because the decision is yours. What you sign is not "yes". It is this much, for this, once, until this time, recorded where neither of us can quietly edit it afterwards.

You let it decide for you. You did not hand it an unlimited amount of your money. That gap — between "I trust you" and "here is an unbounded line of credit" — is the product. Everything below is how we make the gap mechanically real.

Built for the Amazon Build, Ship, Shape Hackathon (Alexa+ track). The tool layer is a self-hosted MCP server over Streamable HTTP (spec 2025-11-25) with an MCP Apps approval surface (SEP-1865); the web app is a simulated Alexa+ experience — structured cards, spoken replies, voice input where the browser exposes SpeechRecognition, and state that survives across sessions. Voice is progressive enhancement as of this commit, not yet the primary path: the mic button only appears where SpeechRecognition exists (Chromium-family today), and reply speech is a toggle that starts off. Making it voice-first is tracked work, not a shipped claim.

Why 2026 needs this

Token prices fell ~280x in two years, yet AI bills kept climbing — agents fan out into 10-200 metered calls per task. The bill problem is no longer per-token price; it is usage patterns and unit economics. SpendLatch watches cost per task (the canary), not just total spend (the smoke alarm) — and it does the same for the rest of the team's stack: cloud, SaaS seats, trials, subscriptions.

And in 2026 the bar for agents moved again: agentic-payment protocols (AP2, ACP, x402) all converged on the same shape — an agent that touches money must carry proof of human authorization, bounded in scope and time, with an audit trail. SpendLatch implements that shape end to end.

Related MCP server: wwall

The action loop — the part most demos skip

detect -> prove -> propose -> [human approves] -> signed mandate -> execute -> receipt

• propose — the agent attaches its proof to a concrete, bounded action (one provider, one operation, a dollar cap).

• approve — approval lives on a separate surface from execution. The browser mints a session token, and ONLY a request carrying it can approve; the MCP surface refuses approval by design (a caller self-reporting "approver=human" proves nothing), and the refusal is logged. The mandate — HMAC-SHA256, single-use, scope-capped, 15-minute expiry — records the approving session fingerprint and the proof hash of exactly what was approved. What this is today: a capability boundary (which surface may approve), not an identity boundary — the demo's session endpoint issues tokens without credential verification, so anyone who can reach the web surface can open a session and approve. What it becomes with a real identity provider: the same mandate, signed by an Alexa+ account-linked session (OAuth 2.1 + PKCE) or an AP2 verifiable credential, with the session token bound to a verified principal. The mandate format, the single-use nonce, the scope cap and the ledger are unchanged by that upgrade — only the proof of who approved becomes non-repudiable.

• execute — the provider adapter runs ONLY if the mandate verifies: signature, expiry, single-use under concurrency (process lock), proof hash still matching the approved evidence, and scope drift (if reality moved past the cap, execution is refused and re-approval is required).

• receipt — the adapter's report lands in the decision ledger.

• every refusal is logged — unknown, forged, expired, replayed, or drifted mandates all produce structured refusals with ledger entries. Nothing executes on trust.

Authorization invariants

Seven properties the system must never lose, each with the code that holds it and the test that fails if it stops holding. They are written down because "we take security seriously" is not a claim anyone can check.

The demo obeys one rule that follows from I7:

Demo attack paths may be synthetic. Authorization decisions may not be.

An attack scenario may be staged (we can choose which attack to walk through, and pre-generate its fixture). The refusal it produces is never staged: it is computed by the same function the product runs in production, and it is recorded in the same ledger. A truly expired mandate is one whose expires_at is genuinely in the past — never a if demo_mode: pretend_expired().

What "single-use" does and does not mean

The precise claim is single-use authorization with idempotent execution semantics — not "exactly once external spending".

• What is enforced: at most one execution per mandate, under sequential replay, status rollback, and 10-way concurrency; the claim is written before the provider runs, keyed by a nonce-derived idempotency_key, and a crash between claim and receipt leaves the mandate spent rather than silently re-armed.

• What is not claimed: the provider adapters are simulated. Against a real payment API, state and the external charge are not one atomic transaction — that needs the idempotency key to be honoured downstream (the receipt already carries it, which is the seam where it belongs).

• Scope of the atomicity, stated so it is never over-read: the serialization lock is per process. The deployed topology runs one process per service and mandates are workspace-scoped, so no two processes can execute the same mandate today. A multi-worker deployment would need a store-level lock; that is tracked work, not a shipped guarantee.

Why it is not another expense tracker

• Proactive, not reactive — open the app and the agent speaks first: it has already swept your providers and found what needs attention.

• Proof before proposals — every saving suggestion ships with a before/after scenario estimate, a computed confidence level, a risk note, and the evidence chain. Estimates are never presented as realized savings.

• Judgment, including refusal — when spend growth tracks real value (API costs scaling with a launch), the agent says do not cut this and shows why.

• Silence is auditable — low-confidence findings are held, repeats are suppressed, and every decision is logged with a reason in the decision ledger. Ask "why didn't you tell me?" and get a real answer. Overrule any entry (challenge #3) and your overrule becomes context.

• Cross-session memory — budgets, acknowledgements, challenges, mandates, receipts, and the ledger persist server-side. Close the page, come back tomorrow: it remembers.

• MCP Apps native — propose_action links an interactive approval card (ui://spendlatch/approval-card, text/html;profile=mcp-app) that hosts render inline; the same HTML speaks the postMessage JSON-RPC bridge.

• The MCP server is the product — 13 typed tools, 201 pytest tests, a sealed benchmark; not a thin wrapper around an existing API.

  The four numbers, stated so they cannot be confused: 201 pytest tests collected — of which the gate's pytest step runs 199 and the remaining 2 (tests/test_mcp_roundtrip.py) run as the separate MCP step, because they spawn a real server subprocess. On top of that: 12/12 sealed benchmark cases, 8/8 MCP wire-probe steps, and 12/12 mutation guards killed. Those three are not pytest tests, and are never counted as such.

Architecture

web/ (simulated Alexa+ experience)
  │  chat UI (typed + voice where supported) · evidence-chain cards · mandate/receipt cards · ledger panel
  ▼
agent/backend.py (FastAPI)  +  agent/brain.py (deterministic intent routing;
  │                                        LLM loop is an optional layer)
  ▼
mcp_server/server.py — MCP over Streamable HTTP (spec 2025-11-25, 13 tools)
  │                   + MCP Apps resource ui://spendlatch/approval-card (SEP-1865)
  ▼
mcp_server/tools.py (pure analysis — single source of truth)
  ├── sample_data.py  synthetic multi-provider bills, 6 months + task volumes
  ├── store.py        local JSON persistence = cross-session state
  ├── ledger.py       decision event stream (alert / suppress / hold / refuse / ...)
  ├── actions.py      mandate-gated loop: propose -> approve -> execute
  └── adapters.py     simulated provider adapters (aws / figma / zoom / openai)

benchmarks/           two-phase evaluation (predictions sealed before gold
                      labels are opened), three honestly-labeled tiers:
                      12 public regression fixtures + 14 independent
                      hand-written cases + a 24-case derived invariance
                      suite (mechanical transformations, labels gitignored)
docs/                 CLAIMS.md · SCOPE-FREEZE.md · JUDGE-REPRODUCTION.md · EVIDENCE.md
                      THREAT-MODEL.md (T1-T10 threats, defense, proof pointers)
                      PATTERNS.md (reusable modules for the next project)
                      LLM-PLANNER.md (optional Bedrock planner, off by default)
                      skills/ — one page per MCP tool: activation, flow, refusals
SHA256SUMS.txt        whole-repo integrity manifest

tools.py is implemented once and exposed three ways: over MCP, in-process for the web agent, and inside the sealed benchmark. One implementation, three surfaces.

Annotated walkthrough with figures: docs/ARCHITECTURE.md (system diagram, the mandate loop, and the claims-to-evidence map).

Interface notes

• Icons: Lucide (ISC license), inlined as SVG — no icon font, no build step, no npm. The app itself is three static files.

• Voice input is deliberately not surfaced in the UI: Web Speech API support varies by browser, and a control that only works sometimes is worse than no control. The keyboard is the primary path (the demo video shows voice running in Chrome).

Quickstart

Requires Python ≥ 3.11. Zero credentials needed.

pip install -e .            # or: pip install mcp fastapi uvicorn pytest
python run_checks.py        # tests + sealed benchmark + MCP wire roundtrip + integrity + language

# Surface 1: the MCP server (Streamable HTTP)
python -m mcp_server.server          # http://127.0.0.1:8101/mcp
python tools/mcp_roundtrip.py        # or let a real MCP client prove it end to end

# Surface 2: the simulated Alexa+ web experience
python -m agent.backend              # http://127.0.0.1:8200
python tools/e2e_flow.py             # or let the probe drive the full flow

Open http://127.0.0.1:8200 — the agent opens the conversation. Try:

• anything unusual?

• prove the saving — then approve — then execute

• execute again — watch the replay get refused and logged

• cost per task

• set a $300 budget for home

• close the tab, reopen it — your budget is still there

• why didn't you tell me?

Judges: see docs/JUDGE-REPRODUCTION.md for the 5-minute, zero-credential reproduction protocol with pass criteria.

Verification status

Full claim-to-evidence binding: docs/CLAIMS.md. Graded evidence register (what is NOT verified is marked so): docs/EVIDENCE.md.

What "simulated" covers - and what it does not

The word "simulated" on this page is a scope statement, and it is narrower than it looks. It covers exactly two things:

• the front experience: this is a simulated Alexa+ surface (the official submission path does not expose the Alexa+ toolkits to participants);

• the provider adapters and billing data: every bill is synthetic, no provider call ever leaves the machine, and receipts say so.

It does not cover the authorization machinery, which is real and runs locally: mandates are signed with HMAC-SHA256 under a per-installation key that never leaves the server; the decision ledger is a SHA-256 hash chain that detects any edit; exported proof bundles verify offline with tools/verify_proof.py, without trusting the running system. The attack page is the proof: the forged-scope attack is refused by the signature check itself - a frontend string cannot fail that way.

Security & privacy

• All billing data is synthetic sample data; no real accounts, credentials, or network calls to providers. Adapters are labeled simulated: true.

• State lives in one local JSON file (data/state.json, overridable via the SPENDLATCH_STATE env var). Nothing leaves your machine.

• The agent proposes; the human decides. Execution requires a signed, single-use, scope-capped, expiring mandate — and every refusal is logged.

Roadmap (post-hackathon)

• Standing mandates: time-boxed, capped, revocable authorization for recurring low-risk operations - the deliberate-friction model stays for consequential actions, but "re-approve every few cents" is not the shape for a hundred calls a day.

• Batch approval with risk-based thresholds: one explicit yes covers a batch of mandates whose risk scores fall under a stated line; everything above it still asks.

• Audit export to SIEM formats (the ledger already is a hash chain; the export is a formatter, not a redesign).

• Optional LLM loop Landed, off by default: an LLM planner (Strands + Bedrock, SPENDLATCH_LLM=bedrock) converts free-form language into a structured SpendIntent — the deterministic brain routes it, policy still decides, and new spend is default-deny. See docs/LLM-PLANNER.md. Next: richer planner coverage and AgentCore deployment.

• Import real usage snapshots (CSV / provider exports) behind an explicit, local-only ingest path

• Production mandate signing bound to device keys / AP2 verifiable credentials, and real provider adapters behind the same mandate gate

License

MIT — see LICENSE.