# Sumplus Task Desk

**Review a model purchase plan before approving it.** Task Desk compares model-and-service-line offers for an explicit task and token ceilings, produces an expiring quote, and records a duplicate-safe simulated approval.

**Alexa+ track: independent web simulation with real MCP tools.** The interface uses structured inputs and deterministic planning. It does not use an LLM at runtime, recognize speech, connect to Alexa, execute model calls, or make payments. No Amazon affiliation or official Alexa deployment is claimed.

## Run locally, free of charge

Node.js 20 or later and npm are required. No API key, account, payment method, AWS service, or model-provider credential is needed.

```sh
npm ci
npm run build
npm start
```

Open **http://127.0.0.1:19243**. The same server exposes the actual MCP endpoint at **http://127.0.0.1:19243/mcp**. `npm start` uses the included, traceable catalogue snapshot and makes no external request. The generated browser bundle is included; `npm run build` reproduces it from source.

For testing on any date, select **Historical snapshot replay**, then review the task. This explicitly uses the original recorded prices and labels quotes and receipts as historical. It does not make a current-price claim. Standard snapshot mode refuses approval if the capture is more than 24 hours old. The comparison can still be inspected. To explicitly fetch a new public, read-only directory, run `npm run catalogue:refresh` and restart the service. If the public directory is unavailable, historical replay remains fully functional offline.

## A two-minute judge walkthrough

1. Keep the report-summary example: 12,000 input tokens, 1,500 output tokens, $0.05 expected-cost budget. Token ceilings are explicit sample assumptions, not estimates generated by AI. Select Historical snapshot replay if testing beyond the capture date.
2. Click **Review task & compare offers**. The shipped snapshot contains 94 model/line offers. With this example, 60 fit and 34 have inspectable rejection reasons. The lowest token-cost ceiling is $0.0018 in this snapshot. This compares capacity and listed price, not model quality.
3. Click **Quote the lowest-cost fit**. Review model, service line, revision, token ceilings, budget, snapshot, price mode and expiry.
4. Change the budget to `0.000001`. The browser immediately withdraws the pending quote on the server and disables confirmation. Review the new task: no offer fits. Under **Inspect MCP & approval checks**, **Attempt previous quote** returns `INPUT_CHANGED`.
5. Restore `0.05`, review, enable **Use 5-second expiry for a demo**, and quote. Wait five seconds; confirmation is disabled. **Attempt previous quote** returns `QUOTE_EXPIRED` from the server.
6. Disable fast expiry, create a fresh quote, then **Confirm simulated approval**. The receipt records expected cost and **$0.00 charged**, with the exact request and source snapshot. Export the receipt JSON.
7. **Replay last approval** returns the exact original receipt with `replayed: true`, without creating a second receipt. Reload restores the workspace and historical receipts, but withdraws an unapproved quote.

## Verification

```sh
npm test
# With npm start running in another terminal:
npm run verify:mcp
```

The business tests cover exact fractional-rate rounding (including the 1.2345674 USD/million regression), capacity constraints, positive rejection signals, zero-price exclusion, exact budget boundaries, task/model/line/budget mutation, quote expiry, snapshot changes, recalculation, cross-workspace isolation, idempotency, persistence and explicit historical replay.

The independent verifier uses the **official SDK Client and StreamableHTTPClientTransport**, not a handcrafted protocol client. It checks initialize negotiation to `2025-11-25`, tools/list, actual tools/call, a simulated approval and replay, changed-task rejection, over-budget refusal, real-time expiry, empty HTTP 202 notification handling, HTTP 405 GET, HTTP 403 bad Origin, HTTP 400 invalid protocol header, and HTTP 403 invalid Host. The Host probe uses Node's native HTTP client because Node 20 fetch ignores a supplied Host override.

## Architecture

- `src/browser.mjs`: official SDK browser client, structured task review, comparison cards, immediate quote withdrawal on edits, source inspection, receipt export.
- `src/mcp.mjs`: six registered tools using official `McpServer` and `StreamableHTTPServerTransport`; JSON responses over Streamable HTTP. No standalone SSE stream; GET returns 405.
- `src/desk.mjs`: server-owned task revisions, catalogue checks, exact decimal rational pricing, quote creation, confirmation recalculation, idempotent receipts.
- `src/persistence.mjs`: atomic local-file state writes. Receipts survive restart; pending quotes are invalidated on restart. Default `data/workspaces.json` is ignored and must never be published.
- `src/catalogue.mjs`, `snapshots/catalogue.json`: content-addressed model/line directory, original capture timestamp and source. Snapshot integrity is checked at startup.
- `server.mjs`: localhost-only Express service, Host and Origin allowlists, explicit protocol-version validation, static frontend and MCP endpoint.

Tools: `start_workspace`, `review_task`, `withdraw_quote`, `inspect_workspace`, `create_quote`, `confirm_approval`.

MCP transport sessions are stateless. Durable **application** workspaces are independent of a transport connection. Workspace IDs are random bearer capabilities, not production authentication. All tool effects are limited to this simulation's local state. Actual purchasing would require authenticated users, explicit fee-inclusive billing, provider-enforced limits, payment authorization, execution and settlement accounting.

## Price and state boundaries

Prices are token-cost **estimates for the specified workload**, not a live invoice or enforced runtime spending cap. Input and output costs are rounded up independently using exact decimal rational arithmetic. Zero prices, non-token offers, unavailable/preview offers, and insufficient capacity cannot be approved. No tax, platform-fee, discount, cache, or real execution simulation is performed. The catalogue's model identity and availability statements are upstream claims; Task Desk does not independently attest them.

SHA-256 identifies a catalogue and quote content; it is not a signature or a proof of business identity. The trusted boundary in this prototype is the server process and its local state file. An operator who can alter that server or file can alter this simulation.

Do not enter real customer prompts, personal information or credentials. A workspace ID is saved in this browser's localStorage and acts as its capability. Local server state is plaintext with restrictive file permissions. There is no account recovery, cross-device account, cloud backup, production audit guarantee or permanent retention promise. Up to 500 workspaces are retained; the oldest may be evicted. Export receipts you want to retain.

## Existing work and this sprint

The Sumplus brand and **Model Desk**, a prior catalogue/pricing project, predate this sprint. Model Desk supplied the integer-pricing approach, per-model/per-line identity and context/output-capacity checks under MIT. They are reused and adapted here; we do not claim the entire pricing system was created for Amazon's event.

New in this sprint: a complete customer-facing procurement review loop; server-owned revision-bound and expiring quotes; input-edit withdrawal; explicit simulated approval; idempotent receipts; atomic persistent workspaces; the official SDK's 2025-11-25 Streamable HTTP server and browser client; explicit historical replay for offline testing; regression and wire-level checks; and the demonstration and English documentation. No prior award or adoption is claimed as evidence of Alexa integration.

## Deployment

For local judging, the commands above are sufficient. A production operator can reverse-proxy this localhost service over HTTPS. Explicitly configure `ALLOWED_HOSTS` (hostnames without ports) and `ALLOWED_ORIGINS` (exact origins) to that deployment's hostname, and set `STATE_PATH` to persistent private storage. Do not expose `data/`, use wildcard origins, or put secrets in frontend code. Running a public demo is a separate deployment action; this repository alone does not prove a live hosted endpoint.

For the hackathon's free testing period through November 20, 2026, historical replay requires no upstream availability or paid resource. The entry's published repository and video remain the durable reproduction route; any hosted URL must be separately verified.

## Developer feedback and AI assistance

See [FRICTION.md](FRICTION.md) for observed issues, workarounds and tool-specific feedback. OpenAI Codex assisted with implementation, testing, documentation and preparation of the demo. No LLM inference powers the runtime and no AWS mini-challenge use is claimed.

MIT © 2026 Sumplus. Third-party package licenses are listed in `package-lock.json`; install their source through the pinned npm dependencies. No third-party music or Amazon logo is used.