# Relay — room for the unexpected

A household replanning prototype for the Amazon Developer Hackathon 2026. A delayed parent should produce an explainable, reviewable afternoon plan, not a confident promise that ignores a pickup deadline.

**[Try the browser simulation](https://codeforcode111.github.io/relay-household/)** · [Submission draft](docs/submission.md) · [Technical evidence](mcp-verification.json)

![Relay running with an isolated local MCP session](docs/relay-preview.png)

## Try it

Use Node 22.12+ (Node 24 recommended).

```sh
npm ci
npm run dev
```

Open http://127.0.0.1:5187. Select **Nora is 25 minutes late**. The solver reassigns pickup to Eli at 3:42–3:52 and moves his library visit to 4:04–4:14. Review before applying. Try **Pickup takes 30 minutes** to see a proven conflict rather than an invented schedule. Approved simulation state stays in this browser; Start over resets only this example.

For actual MCP requests, run a second terminal:

```sh
npm run server
```

Open http://127.0.0.1:5187/?transport=mcp. The browser uses the official MCP client, a Vite proxy and the server at http://127.0.0.1:5190/mcp. Its label says **Live MCP · local server**. Each connection receives an isolated, synthetic household. Server state is temporary memory; reload creates a fresh example session. The hosted GitHub Pages demo runs the browser simulation, not this server.

## What is real

- A constraint solver checks availability, deadlines, dependencies, travel and setup buffers, completed work, and optional errands.
- Integer-minute exhaustive search is bounded. Results distinguish feasible, infeasible, unknown and invalid. A solution found before cutoff is feasible; it is not claimed optimal unless the search proves it.
- Streamable HTTP MCP, tested with protocol **2025-11-25**, exposes `get_household`, `propose_change`, `commit_plan` and `undo_last_plan`.
- Proposals do not apply changes. Commits require approval, the displayed revision and an idempotency key. Stale proposals fail. Undo increments the revision. Repeated commit keys return the original receipt; read again to obtain current state.
- The browser interface uses a deliberately narrow phrase parser. Browser speech synthesis can read its response. No language model, Amazon account, real Alexa device, calendar integration or outbound message is claimed.

## Architecture

```text
Browser phrase parser → worker solver → review → local example state
Browser MCP client → Streamable HTTP → HouseholdSession → same solver
Any compatible MCP client ────────────→ four structured tools
```

`src/engine` contains the independent scheduler. `src/domain` contains the example and transactional state. `server` exposes it through the official MCP SDK. `src/ui` renders proposals and actual request timing.

The local demonstration server binds to loopback, rejects non-local origins, limits sessions to 100 and expires idle sessions after 30 minutes. It is not a production multi-user deployment: remote hosting would need authentication, durable state and operational hardening.

## Verification

```sh
npm run build
npm test
```

27 tests cover engine behavior, an independent small exhaustive feasibility oracle, transaction semantics, input validation and actual HTTP protocol roundtrips. The separate original [MCP Tool Check](https://github.com/codeforcode111/mcp-tool-check) project ran twelve ordered assertions against Relay; all passed. [Report](mcp-verification.json).

To reproduce that additional check with the server running:

```sh
cd ../mcp-tool-check
npm ci
npm run build
node dist/cli.js --config examples/relay.json --json ../relay-household/mcp-verification.json
```

`?studio=1` adds explicit developer controls to export the currently rendered app for demonstration assets. It does not fabricate external integrations or results.

## Demonstration

[Watch or download the 2 minute 12 second English walkthrough](https://github.com/codeforcode111/relay-household/releases/tag/v0.1.1). Includes narration, captions and original runtime frames. [Transcript](docs/demo-transcript.md). These are labeled snapshots from the running local MCP interface; the public website runs the browser simulation.

## Entry materials and scope

[Submission](docs/submission.md), [product feedback](docs/product-feedback.md), [demo script](docs/demo-script.md), [eligibility matrix](docs/eligibility-matrix.md). These are preparation materials. This repository alone is not proof of contest entry, eligibility, an award or payment.

The household and all task data are fictional. Source and documentation were developed with substantial AI assistance using OpenAI Codex. Dependencies retain their own licenses. Original project code is licensed under MIT.

Bundled fonts, icons and code retain their exact upstream copyright and license texts in [THIRD_PARTY_NOTICES.txt](THIRD_PARTY_NOTICES.txt). This includes Geist/Geist Mono under SIL OFL 1.1, Phosphor Icons under MIT, and the other inventoried browser components. The identical [public notice file](public/third-party-notices.txt) is copied into site builds at `third-party-notices.txt`, alongside the distributed assets.