Aura — re-plans, remembers, and asks before it spends

A stateless MCP 2025-11-25 server for Alexa+: one spoken sentence becomes a re-planned household routine with cards, cross-session memory and a purchase guardrail.

Comment

Why this entry — mapped to the rules' own Alexa+ wording

The official rules instruct Alexa+ judges to separate creative from obvious, and they name the six things that count as creative. Aura against that list, with the file that proves each line:

  • "agentic workflow that orchestrates across services autonomously" — one utterance fans out across five key-free APIs (weather, media catalogue, headlines, encyclopedia, exchange rates) inside a single plan; when a tool result contradicts the plan, the plan changes mid-run and the new step is labelled added-by-agent. src/agent.js runs classify → plan → act → observe → re-plan → speak.
  • "context-aware add-on that maintains state across sessions" — per-member preferences, pantry stock and the last routine live in one store and survive a restart, so turn N+1 still knows that Amma hates that podcast. src/memory.js.
  • "purchasing capabilities" — place_order sits behind a household ceiling. The planner has no code path that can mark a purchase confirmed; only a spoken yes from the user does that, and every order, veto and confirmation is retrievable from household_audit.
  • "media support (cards, carousels, etc)" — the ui://aura/cards carousel and ui://aura/plan timeline, with the agent's own pick outlined. src/ui/templates.js.
  • "MCP Apps" — ui:// resources served as text/html;profile=mcp-app, and the demo client reads them back through MCP rather than from my web server. The bridge I had to hand-roll is now a separate Apache-2.0 package, mcp-app-cards — which is also my Open Source mini-challenge entry.
  • "Agent Skills" — a standard SKILL.md with references/ progressive disclosure, installable as a skill and also served over MCP through load_agent_skill.

The rules also name two obvious patterns and Aura is neither: not a "single-turn Q&A bot" (it re-plans and holds state across sessions), and not a "basic MCP wrapper around an existing API" (the 14 tools expose a policy engine, a cross-session memory model and a spending guardrail that no single API provides).

Fastest verification, no keys / no AWS / no model required: git clone → npm install → npm run verify (19 offline acceptance checks, about 3 seconds). docs/JUDGING_MAP.md maps every criterion to the file and the check number that evidences it.

Inspiration

Every voice device in my house shares one account and remembers nothing. It re-learns that my mother dislikes the podcast I play, it will happily read breaking news out loud at 23:40, and if you ask it to reorder groceries it has no idea there is a nut allergy in the house. Adding an agent made this more interesting, not less: the same assistant can now take an action nobody authorised. I wanted to know how much autonomy a household agent can actually be handed, and what it has to do to earn it. So Aura is built around three promises — it re-plans when reality contradicts the plan, it remembers across sessions, and it asks before it spends.

What it does

Say “movie night with the kids, keep it under five dollars” and one utterance becomes a plan: load the household, check the weather, search the catalogue, apply the family-safe filter, respect the screen-time curfew, rank by what each person actually likes, then speak a sentence while a carousel appears on screen.

It then changes its mind, visibly. Rain forecast → the patio movie becomes an audio story in bed. 22:05 and a video request → audio, because the household rule says so. Quiet hours → the headline step is dropped and a calm fact card is substituted. Basket over budget → the priciest item is removed before it is ever offered. Peanut butter in the pantry and a nut allergy in memory → the item is vetoed and the reason is logged. Each of those appears in the plan timeline as a step marked added-by-agent, so the re-planning is something you can see, not something I claim.

Anything above the household ceiling returns needs_confirmation and is spoken back as a question. There is no code path by which the planner can mark a purchase confirmed — only the user's spoken yes can. Every order, veto and confirmation is retrievable through household_audit.

How I built it

  • A real McpServer from @modelcontextprotocol/sdk 1.32.1 on Streamable HTTP, spec 2025-11-25, deliberately stateless (sessionIdGenerator: undefined): the conversation belongs to the voice assistant, not my process, so any instance can serve any turn and a restart costs nothing.
  • 14 tools with zod schemas, each returning the full triple — content[] (what is spoken), structuredContent (what a data-only host renders) and _meta.ui.resourceUri (which MCP Apps template to show). Plus 6 resources and 3 prompts.
  • MCP Apps UI: ui://aura/cards, ui://aura/plan and ui://aura/decision served as text/html;profile=mcp-app — self-contained documents with no remote assets.
  • An Agent Skill in the standard SKILL.md format with references/ progressive disclosure, so the same behaviour installs as a skill or runs as a server.
  • A simulated Alexa+ device (the track allows this) that is a genuine MCP client: Client + StreamableHTTPClientTransport over HTTP, which then reads the ui:// templates back through MCP to render them. Nothing between the two halves is stubbed.
  • A deterministic policy engine, so the demo needs no API keys and no model. classify and replan are the two named swap points where an LLM planner would go.
  • Key-free public APIs (Open-Meteo, iTunes Search, HN Algolia, Wikipedia, open.er-api) with local fixtures behind AURA_OFFLINE=1, so results are reproducible for a judge at any hour.

Challenges

  • @modelcontextprotocol/sdk 1.32.1 ships no helpers for the MCP Apps UI profile. I hand-rolled the ui/ready → ui/render → ui/size-changed bridge, then extracted it into a separate Apache-2.0 package, mcp-app-cards, because the mechanism has nothing to do with households.
  • The spec's initialize/session negotiation assumes a stateful server; getting a stateless one to behave took reading the transport, not the docs. Related: a bare POST /mcp returns 406 with no hint that it is the Accept header contract (logged as friction F3).
  • iTunes media=movie returns zero results; the working query needs media=all&entity=movie,tvSeason,musicVideo.
  • Re-cloning my own repo to check the judge experience caught a real bug: a Windows checkout gave SKILL.md CRLF line endings, which broke YAML frontmatter parsing. Fixed with .gitattributes.
  • Making autonomy legible was harder than making it work: the timeline needed a distinct added-by-agent state or it just looked like a longer plan.

What I learned

The interesting engineering question was never “can a speaker fetch the weather”. It is how much authority you give a device that can spend money and change someone else's settings, and how you make that authority auditable after the fact. Writing the guardrail as a policy the planner cannot override — rather than a prompt that asks it nicely — changed how I think about agent safety. I also learned to test the thing a judge actually does: git clone, npm install, npm run verify, on a machine that is not mine.

Try it

git clone https://github.com/abhinavshukla152005-beep/aura-household-agent
cd aura-household-agent && npm install
npm run verify   # 19 acceptance checks, offline, ~3s
npm run validate:skills   # SKILL.md frontmatter vs what the server registers
npm run demo     # headless: 4 turns, trace, cards, audit log
npm start        # http://localhost:8787 — the simulated device

Point any MCP client (or the MCP Inspector) at http://localhost:8787/mcp. docs/JUDGING_MAP.md maps every judging criterion to the file and the check that evidences it; FRICTION_LOG.md, FEATURE_REQUESTS.md and PRODUCT_FEEDBACK.md are the feedback deliverables. Built solo, from an empty directory, entirely inside the hackathon window. Apache-2.0.

Reproducible re-planning, and a recorded clean-clone run log

Two things were added after the first submission, both verified on a fresh clone:

  • The simulated device has a household clock selector (live / 23:05 after curfew / 07:05). The rain-triggered re-plan needs a rainy observation, which depends on the weather at wherever the judge runs it, so that selector only sets the hour the planner reasons about - the same field /api/agent already accepted. At 23:05 the curfew re-plan and the SKIPPED place_order render on demand in any city and any timezone. Start with AURA_OFFLINE=1 to reproduce the rain re-plan from the demo video using the bundled wet-evening fixture.
  • docs/RUN_LOG_2026-10-22.md records a clean git clone of commit 37c3104 run through exactly what a judge does: npm install (95 packages, 42s, no keys, no AWS account, no hardware), then npm run verify (19/19), then npm run demo (two allergen vetoes by household memory), then the curfew curl, plus the browser surface state. The real output of every command is pasted into it.
  • Two newer logs run the same procedure on newer commits: docs/RUN_LOG_2026-10-23.md (commit 99ea087, 17 checks, including a real MCP callTool of describe_last_decision) and docs/RUN_LOG_2026-10-23B.md (commit 6cb7293, 18/18, plus the advertised surface measured off the running server: 14 tools, 6 resources, 3 prompts) and docs/RUN_LOG_2026-10-23C.md (commit d346586, 19/19, with the explain voice path driven over HTTP and ui://aura/decision filled in a browser).

One difference this entry states instead of hiding: the demo video says 15/15 checks passed and shows 13 tools. It was recorded before the last three additions (describe_last_decision, the skill-contract check, and the why did that change? explain path) and has not been re-recorded, so it understates the current build; the run logs show what the suite actually prints today.

Built with Kiro (AWS agentic-tooling mini-challenge)

The explainability layer was written with Kiro (CLI 2.33.1, Free tier - no credit card, no AWS account created). Three real agent sessions; every prompt and every outcome is recorded verbatim in docs/KIRO_TASK.md.

  1. Kiro added describe_last_decision as the 14th tool plus a ui://aura/decision MCP Apps resource, so a judge can ask why did the plan change and get the answer from the server instead of from my prose.
  2. Its first attempt was rejected: it regex-matched the previous summary for words like "rain" or "curfew" to infer which step the agent had added - a guess dressed as an explanation. The second session replaced that with a trace persisted at commit_routine time ({tool, status, why} per step), so addedByAgent and skippedSteps come from recorded execution, not post-hoc heuristics.

  3. That session also caught a bug I had missed: the commit_routine Zod schema omitted trace, so the MCP SDK was silently stripping it. Covering it added acceptance check 17, which asserts the real curfew "why" text and a non-empty skipped reason.

  4. Session 3 took feature request #8: the Agent Skill had no validator, so a frontmatter typo made the agent silently ignore the skill. Kiro read src/server.js, derived the contract from the code that registers the skill:// resource rather than inventing rules, wrote a dependency-free frontmatter parser, and added acceptance check 18 - which points the validator at a deliberately broken skill in a temp directory and asserts it exits 1 naming the exact key. That is a positive control, not a smoke test. It left ~50 lines of duplicated dead parser code behind, and its own report said it could not run npm run on this machine; I deleted the dead code and ran npm run validate:skills myself (7 checks pass, exit 0).

Kiro ran no git commands and pushed nothing - every diff was reviewed line-by-line and re-verified locally, including a clean clone of the current commit logged in docs/RUN_LOG_2026-10-23C.md: 19/19 checks passed, npm run demo exit 0, and the advertised counts read off the running server (14 tools, 6 resources, 3 prompts). (Kiro session 3 was itself verified at 18/18 in docs/RUN_LOG_2026-10-23B.md; the 19th check is mine - see the next point.)

  1. The explain voice path is mine, not Kiro's. Kiro built the describe_last_decision tool, but nothing routed a spoken question to it, and ui://aura/decision was served over MCP yet never rendered in the demo - so the flagship "explainable decision" claim was real in the API and unreachable on the device. I added an explain intent (why did that change?) that plans a describe_last_decision step, a spoken summary branch, a third decision frame in the web UI, and acceptance check 19 that proves the whole path over MCP. The suite is now 19/19, re-verified on a fresh clone of d346586 in docs/RUN_LOG_2026-10-23C.md.

Built With

Share this project:

Updates

Submission history