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.

Demo video (2:37): https://youtu.be/QvWt17Li7U8

Hackathon entry (Devpost): https://devpost.com/software/spendlatch - Built, Ship, Shape: Amazon Developer Hackathon, Alexa+ track + Open Source mini challenge.

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 it refuses. There is no stated price, so there is nothing to cap, and a cap is the entire point — the refusal is rendered as a card and written to the ledger like any other decision. Say "prove the saving" instead and it shows you the idle EC2 instance, what it costs per month, and the exact action that would stop it — then stops itself, 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: the mic button appears where SpeechRecognition exists (Chromium-family today), and reply speech is a toggle that starts off.

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: Agent Renewal Guard

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().

Read that narrowly, because it is easy to over-read: the five attack mutants are refused by their corresponding guards and written to the ledger — the claim is about the refusal, not about the endpoint behaving well from any state. Two qualifications belong beside it. The fixture's own session is minted by the server (actions.open_session() inside mcp_server/attacks.py), because a fixture has to reach the approval path to produce a mandate worth attacking; that is the L1 capability gap, exercised on purpose. And until proposals were given a 15-minute lifetime, an anonymous POST /api/attack/* could pick up a stale proposal whose proof no longer reproduced, have the drift guard correctly refuse it, and see _mint() raise — HTTP 500 on four of the five routes, with the partial state already written. Both are fixed and tested; it is why the sentence above is about mutants, not about endpoints.

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.

• Where the enforceable scope ends (single process): "single-use" holds inside one process, which is what the demo is (_EXECUTE_LOCK, plus the web app's own _STATE_LOCK). State is a whole-file JSON read-modify-write with no cross-process lock, so two OS processes writing the same workspace can lose an update — measured at ~9.4 ms per read-modify-write, 50% of concurrent updates lost in a two-process test. A mandate is spent in state["consumed"], so a lost update is the shape a cross-process double spend would take. The deployment runs two services over one state directory (spendlatch-web, spendlatch-mcp); closing that is a lock-file or a real store, and it is not claimed as done.

• 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, 239 pytest tests, a sealed benchmark.

  The four numbers, stated so they cannot be confused: 239 pytest tests collected — of which the gate's pytest step runs 237 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. The mutation operators delete a guard and require its tests to go red inside one process — that is a statement about coverage, not about cross-process behaviour (see the single-process scope note under "What 'single-use' does and does not mean").

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; cases rebuilt by
                      tools/make_derived.py and not shipped; labels kept local)
docs/                 CLAIMS.md · SCOPE-FREEZE.md · JUDGE-REPRODUCTION.md · EVIDENCE.md
                      THREAT-MODEL.md (T1-T14 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 ".[dev]"     # pytest lives in the dev extra; "pip install -e ." alone cannot run the gate
python run_checks.py        # tests + sealed benchmark + MCP wire roundtrip + integrity

# 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

Everything in the table below is re-run by python run_checks.py (~2 minutes, CI included) unless it says otherwise. Two checks are manual by necessity and are marked so rather than quietly counted as gated: the host-conformance probe against the deployed endpoint (it needs the deployment to be up) and the AWS smoke run (it needs a billed account).

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

One real-data run

The detectors are also runnable against a real usage export: tools/analyze_usage.py reads a daily-by-model CSV (date, model, calls, credits) and applies the same credits-per-call canary. The run captured in docs/evidence/real-usage-run.txt covers 10,901 requests across 137 days and 5 months from a WorkBuddy usage export. Of the 23 anonymized model ids, seven carry at least three months of history, and every one of those seven shows credits-per-call drift somewhere in the window. The export itself stays local - what ships is the tool and its output, because the aggregate is the owner's usage.

The Amazon track: what is real, and what is simulated

The track accepts two paths, and this project takes the first one and builds the second:

1. A self-hosted MCP server over Streamable HTTP - the real integration, and it runs. python -m mcp_server.server serves /mcp; the initialize handshake negotiates 2025-11-25; thirteen typed tools are exposed with the safety hints a host needs (readOnlyHint, destructiveHint, idempotentHint, openWorldHint); the approval card is a real ui:// MCP Apps resource. A host that is not ours can mount it from the public endpoint, and that is what tools/host_conformance.py --url https://spendlatch.owain32380.cn/mcp checks - protocol, tool contracts, hints, the UI resource, and that refusals arrive as content a host can render rather than transport errors. The run is captured twice: against a freshly spawned server (docs/evidence/host-conformance.txt) and against the deployed endpoint (docs/evidence/host-conformance-public.txt) - a client on the public internet, talking to the live server through TLS.

2. A simulated Alexa+ experience, which the rules allow as the alternate path, and which is what the web surface is.

What is not real, and cannot be from here: an Agent Skill mounted inside Alexa+ itself. The Alexa+ toolkits are not exposed to participants - that is precisely why the track offers the simulated-experience path - so no entrant can attach one. The AWS adapter is simulated by design as well; no provider account is touched. tools/aws_smoke.py is the one-command path to a real Bedrock call the moment credentials exist: today it exits 3 with UNAVAILABLE and writes no evidence file, because a run that never reached Bedrock must not leave an artifact that could be read as proof.

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.