# HomeRelay

### A changing morning, one clear handoff — and no silent commitments.

**Prototype 0.3 · Release candidate V4 · 23 October 2026, UTC · MIT**

> Alexa+ experience simulation · Synthetic household data · No live connection

HomeRelay turns a fictional morning checklist into a **who / what / when / what cannot fit** handoff. It drafts and replans around availability and dependencies, then requires a separate decision before confirming the exact current plan.

This is a **local, deterministic, rule-based web simulation**, not an LLM or a live Alexa integration. It implements a real MCP 2025-11-25 server over Streamable HTTP. The Alexa+ experience is simulated; no Amazon device, account or service is connected.

## Recorded results

- Earlier V2 baseline: **32 Python domain/HTTP/API-boundary tests passed**, including a real 60-second unanswered review. This baseline is reused only for unchanged source, not presented as a new run.
- Actual updated environment: **18 relevant Python tests passed** in 64.956 seconds, including all HTTP cases, V3 interleavings and two MCP 1.30.0 adapter cancellation/lifecycle cases. **Six actual-source JavaScript ordering checks passed.** These overlap the earlier baseline; do not add the counts together.
- **Actual sandbox-enabled browser capture passed.** The included [77-second MP4](media/HOMERELAY_ACTUAL_LOCAL_DEMO_V1.mp4) is sampled local browser footage, with readable English captions and no audio. Recorded requests stayed on the owned loopback origin; no page errors were recorded. Supplemental actual desktop and 390-pixel mobile screenshots were inspected. This is bounded demo/layout acceptance, not a complete accessibility, browser-compatibility or security audit.
- Every automated confirmation in tests/video is an **automated synthetic fixture, not approval by a real person**. No real household action occurred.
- No production, live Alexa/AWS/model integration, contest eligibility, public-video hosting or submitted-entry status is established by this package.

See [verification scope and hashes](VERIFICATION.md), [demo](docs/DEMO.md), [desktop](media/ui_desktop.png) and [mobile](media/ui_mobile.png).

## Native local setup

The updated candidate was exercised with **CPython 3.14.8 on Linux x86_64**. Earlier baseline tests used CPython 3.12.14. Other Python versions and operating systems are not verified. Use your own native interpreter and dependencies; no private host path, copied virtual environment, binary or browser profile is required.

From the extracted repository root, on Linux/macOS with Python 3.14 available:

```sh
python3.14 -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements.txt -c requirements.snapshot.txt
python -B -m homerelay.app
```

Equivalent PowerShell commands, if native Python 3.14 is installed:

```powershell
py -3.14 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt -c requirements.snapshot.txt
.\.venv\Scripts\python.exe -B -m homerelay.app
```

These are setup instructions, **not a claim that fresh installs on every platform were tested**. Dependency installation contacts the package index. The application itself requires no account, API key, AWS resource, model or cloud service. If native packages are unavailable, stop and investigate compatibility; do not force foreign wheels or weaken browser sandboxing.

Open **http://127.0.0.1:8765/** on that same machine. Stop with Ctrl+C. An alternate unprivileged port is supported: `python -B -m homerelay.app --port 8766`. The host remains literal `127.0.0.1`; public hosting is unsupported.

### Dependency records

- `requirements.txt`: pinned runtime entry points.
- `requirements.snapshot.txt`: the complete **32-package version closure** observed in the updated environment, including optional demo tools and the `cryptography`/`cffi`/`pycparser` closure. It supplies native version constraints; it is not a universal wheel lock.
- `requirements-verified-linux-cp314.txt`: exact SHA-256 wheel identities used by the recorded Linux x86_64 / CPython 3.14 environment. These hashes cover one platform's artifacts and are **not portable to other wheels**. No wheels are bundled.
- MCP is pinned to **1.30.0**, certifi to **2026.10.19** and PyJWT to **2.15.0** in the complete closure. The dispatch adapter uses a protected SDK method; future SDK upgrades require source review and relevant regressions.

## Try the fictional morning

Ada is free at 08:00; Ben at 08:06. Time is fixed simulation data, not today's clock. Five tasks include bottle-before-bag, keys, windows and optional recycling.

1. **Leave by 08:12:** all five tasks fit. Revision stays 0; no confirmed board.
2. **Ben cannot help:** required tasks fit with Ada; optional recycling is explicitly deferred. This is still only a draft.
3. **Review before confirming:** opens the exact-plan prompt through MCP form elicitation. This button alone does not confirm anything.
4. **Cancel / Decline / silence:** no application. Review expires after 60 seconds. Only **Confirm synthetic plan only** can apply a fresh displayed feasible plan.
5. **Try 08:05:** the planner reports infeasible timing and earliest required finish 08:09 with both adults; the prior confirmed board remains.
6. **Send Ben the plan:** returns “Not sent.” There is no messaging integration.
7. **Reset:** discards that in-memory synthetic session. Refresh preserves the active session rather than secretly resetting it.

Supported grammar: `plan HH:MM [without Ada|Ben|both]`, within 08:00–09:00. Unknown text is not evaluated as code or sent to another service.

## Architecture and confirmation

```text
same-origin browser UI → local host /api/*
                       → official MCP client
                       → real loopback Streamable HTTP /mcp
                       → isolated household + deterministic planner
                       ← exact-plan form elicitation
separate browser decision → response → freshness check → synthetic commit
```

Three tools: `household_snapshot`, `create_handoff_plan`, `apply_handoff_plan`. Each MCP session gets a separate household. The tiny planner enumerates valid task orders and adult assignments; it is not a scalable general-purpose optimizer.

A synchronous review reservation owns its task, prompt and answer. Operation/plan/digest correlation rejects delayed foreign prompts; confirmation rechecks digest and revision. New drafts invalidate old drafts. Pending duplicates fail; terminal operation replay is idempotent. Browser generation/order tickets reject stale state and CSRF after reset or confirmation.

The small original adapter dispatches long elicitation callbacks in an owned sibling task while leaving the installed official MCP SDK unmodified. It preserves the SDK responder, validation and cancellation path. See [architecture](docs/ARCHITECTURE.md).

## Local safety and limits

Exact Host/Origin/loopback-client checks, SDK DNS-rebinding protection, same-origin CSRF on unsafe browser routes, HttpOnly SameSite=Strict cookie, same-origin CSP and text-node rendering are implemented. JSON bodies are limited to 16 KiB, browser sessions to eight with ten-minute idle expiry, and operation history to 64 records per household. The runtime audit hook rejects external connections/DNS, non-loopback binds and process/shell calls in the exercised cases. It is defense in depth, **not an OS sandbox**.

The unauthenticated MCP endpoint is synthetic loopback demo infrastructure. A local process can make its own client/callback; this is not proof of a real human's identity or protection from a compromised host. No TLS, production authentication, durable persistence, cross-device service or denial-of-service guarantee is provided. Cookie Secure is not set for local HTTP. Do not use real household data, secrets or real-world commitments. See [limitations](docs/LIMITATIONS.md).

## Tests and optional recapture

With the runtime dependencies installed:

```sh
python -B -m unittest discover -s tests -v
node tests/test_ui_order.js
```

Node.js is needed only for the JavaScript check. Python tests start and stop owned temporary loopback app children. One HTTP case deliberately waits a real 60 seconds. The JS checks execute actual `web/app.js` against controlled DOM/fetch adapters; they are not browser-rendering tests. This release preparation did **not** rerun application tests or recapture media.

The accepted video is already included. Optional fresh native Playwright setup and capture instructions are in [DEMO.md](docs/DEMO.md); browser installation is separate from Python package installation.

## Contents and license

Application in `homerelay/`; original interface in `web/`; fictional dataset in `fixtures/`; checks in `tests/`; selected nonprivate recorded outputs in `verification/`; user documentation in `docs/`; actual video/screenshots in `media/`. `evidence/` is reserved for new local test/capture outputs and ignored by Git.

This clean package contains original product materials, not the private delivery/review archive: account/Drive IDs, host-private paths, private execution receipts, environments, wheels, profiles and failed-attempt frames are excluded. Source bytes are retained from the accepted candidate, including its historical “PRIVATE PROTOTYPE” UI label and package-version marker; V4 is the clean packaging/documentation revision, not a new runtime behavior version.

Original code, tests, UI, documentation and demo materials were prepared with AI assistance. No real household data, unrelated private project code, music, external artwork or Amazon logo is included. [MIT license](LICENSE); non-vendored dependencies retain their own licenses in [THIRD_PARTY.md](THIRD_PARTY.md). Not affiliated with, endorsed or certified by Amazon.