GridTwin

A WebMCP civic microgrid sandbox where AI explores deterministic energy scenarios while humans retain final authority.

Comment

GridTwin

One-line Summary

GridTwin is a WebMCP civic microgrid sandbox where an AI agent visibly explores deterministic energy scenarios while the human retains authority over constraints, final plan selection, and export.

Problem

Climate and resilience officers at small councils and housing associations often need to choose one indicative solar-and-battery configuration before they can pursue a grant or commission a professional feasibility study. The decision spans budget, emissions, and outage resilience, but existing energy tools are usually designed for specialists and generic AI interfaces can hide what an agent changed or why it recommended an option.

That is a poor fit for a consequential early-stage decision. A useful agent must make the decision space easier to navigate without obscuring assumptions, silently relaxing constraints, or taking final authority from the person accountable for the outcome.

Solution

GridTwin turns the fictional Riverside Estate into a shared, visible planning workspace. The human approves a £400,000 capital budget, a 40% emissions-reduction target, eight hours of critical-load coverage, and a resilience-first priority order. A real browser agent then uses seven page-defined WebMCP tools to read the baseline, run bounded solar-and-battery scenarios, compare transparent metrics, diagnose infeasibility, and shortlist a feasible candidate.

Every scenario uses the same deterministic hourly dispatch model. Every tool action appears in the activity rail and visibly changes scenario cards, comparisons, or report state. Infeasible candidates show every violation in natural units. Agent advice remains reversible. Only the human can approve criteria, select the final plan, or open the browser print flow.

The signature result is the fixed 18:00–02:00 outage: grid contribution falls to zero, the balanced 275 kWp solar / 500 kWh battery plan supplies critical load for all eight hours, and the final action belongs to the human approving the plan.

Why This Matters

GridTwin demonstrates a WebMCP pattern for consequential human-agent work—not just an energy calculator. Before WebMCP, a generic assistant could describe possible configurations, but it could not reliably operate the same visible, structured planning state as the human or leave an auditable trail of each action.

With WebMCP, the agent can navigate a non-trivial decision space through narrow tools while the application remains the source of truth for calculations, feasibility, lifecycle state, and authority. The result is a better user experience because the human sees the work happen, can inspect assumptions and violations at the point of use, and retains explicit control over every consequential transition.

The civic-energy example makes that collaboration concrete: abstract capacities become continued critical services during an outage. GridTwin does not claim to produce an engineering design. It helps a real target user make a transparent decision about what deserves professional evaluation next.

How We Used AI

GridTwin contains no embedded chatbot and calls no model API. AI enters through an external agent in ChatGPT's in-app browser, which discovers and invokes the page-defined WebMCP tools.

The agent can:

  • read the synthetic Riverside Estate baseline and fixed assumptions;
  • stage constraint suggestions for human review without applying them;
  • choose bounded solar and battery inputs and run real deterministic scenarios;
  • compare two or three current scenarios without an opaque score;
  • diagnose the nearest candidate when every option is infeasible;
  • create a reversible shortlist for a feasible plan; and
  • prepare an immutable decision-brief preview after human approval.

The agent cannot approve constraints, approve or reconsider a plan, reset the comparison, print, download, or publish. Those actions have no WebMCP schema. After human approval, advisory mutations are frozen until the human explicitly reconsiders the decision.

All authoritative metrics come from GridTwin's pure client-side model, not from model-generated arithmetic. WebMCP makes the agent's structured actions visible, testable, and subordinate to the application's lifecycle rules.

How We Used Codex

Codex was the primary development agent across the 30-hour solo build. It helped turn the initial idea into the scope, PRD, technical specification, and sequenced checklist; implemented the deterministic dispatch engine, reserve policy, lifecycle reducer, persistence, WebMCP adapter, civic interface, outage visual, and A4 report; added regression and browser tests; diagnosed integration failures; rehearsed the real in-app-browser workflow; deployed to Vercel; and prepared the handoff documentation.

The builder actively directed the work rather than accepting a generated solution wholesale. Three mandatory review pauses produced concrete corrections, including refresh-safe activity identity, stricter restored-state validation, full post-approval agent freeze, HTTPS in-app-browser verification, and a settled chart capture. The builder also rejected an embedded-chat fallback, an opaque composite score, hidden constraint relaxation, and dramatic but dishonest tariff assumptions.

That collaboration mirrors GridTwin itself: Codex explored and implemented within an explicit plan, while the human reviewed the consequential product, authority, credibility, and scope decisions.

Key Features

  • Exactly seven direct WebMCP tools registered through document.modelContext.registerTool().
  • One shared deterministic engine for every bounded solar/battery combination—no optimizer, randomness, precomputed scenario cards, or special-case balanced branch.
  • Visible tool activity, a fixed 600 ms abortable pending interval, atomic scenario commits, and safe interruption handling.
  • Versioned human-approved constraints with current/stale scenario lineage.
  • Direct cost, emissions, reserve, resilience, feasibility, and natural-unit violation metrics with no composite score.
  • Transparent all-infeasible diagnosis and staged—but never automatic—constraint suggestions.
  • Distinct reversible agent shortlist and direct human-approved selection.
  • Signature 18:00–02:00 outage view with grid at 0 kW and eight uninterrupted critical hours for the balanced plan.
  • Immutable A4 decision-brief snapshot and human-controlled Print → Save as PDF flow.
  • Session refresh recovery that restores committed work but never converts partial operations into completed results.
  • Persistent synthetic-data, model-version, constraint-version, and indicative-planning caveats.

Architecture

GridTwin is a static React 19, TypeScript, and Vite application deployed on Vercel.

Human UI or WebMCP callback
            ↓
shared validated command boundary
            ↓
pure deterministic domain calculation
            ↓
complete atomic reducer transition
            ↓
session snapshot and visible workspace/report
  • src/domain/: fixed synthetic inputs, validation, hourly dispatch, convergence, annualization, outage stress test, feasibility, and non-composite nearest ordering. It imports no React or browser code.
  • src/state/: context/reducer, versioned lifecycle, authority gates, interruption recovery, and sessionStorage compatibility.
  • src/webmcp/: seven JSON schemas, direct imperative registration, all-or-nothing discovery, cleanup, cancellation, readiness, and stable result envelopes.
  • src/components/: purpose-built civic planning interface, Recharts analysis, and a small fixed-node energy-flow SVG.
  • Report path: an immutable snapshot of matching approved state; no recalculation, automatic download, or publication.

The annual operating estimate and outage stress test share one dispatch function but remain separate calculation paths. Battery state converges across repeated representative days, a noon-to-outage reserve policy applies consistently, and the outage test clones the actual prepared 18:00 state.

Testing Instructions

No credentials are required.

Judge-facing live path

  1. Open https://gridtwin.vercel.app in ChatGPT's WebMCP-enabled in-app browser or Google Chrome with WebMCP enabled.
  2. Confirm the header reads WebMCP ready · 7 agent tools available.
  3. Approve the default £400,000 / 40% / 8-hour criteria through the direct human button.
  4. Ask the browser agent:

Inspect Riverside Estate and respect the approved budget, emissions, and eight-hour resilience criteria. Explore distinct solar-heavy, battery-heavy, and balanced configurations within the allowed increments. Run each scenario, compare the candidates, diagnose infeasibility honestly, and shortlist a feasible plan according to resilience, emissions, then cost. Do not change the approved constraints or approve a plan for me.

  1. For the calibrated deterministic path, the agent may use 350 kWp / 200 kWh, 100 kWp / 700 kWh, and 275 kWp / 500 kWh.
  2. Verify the activity rail and three scenario cards update from tool calls, with two infeasible candidates and one feasible balanced candidate.
  3. Verify the shortlisted outage state shows Grid unavailable · 0 kW, Battery supplying critical load, and 8 of 8 critical hours served through 02:00.
  4. Use Approve this plan and Confirm human selection directly in the UI.
  5. Ask the agent to prepare the brief, then use Open decision brief and the human-controlled print action.
  6. Refresh and confirm the criteria, scenarios, approval, and prepared brief remain available.

Local verification

npm ci
npm run typecheck
npm run test -- --run
npm run build
npm run test:e2e -- --reporter=line
PLAYWRIGHT_BASE_URL=https://gridtwin.vercel.app npm run test:e2e -- --reporter=line

Verified on August 30, 2026:

  • strict TypeScript check passed;
  • 64/64 Vitest tests passed across 11 files;
  • Vite production build passed;
  • 3/3 Playwright paths passed locally and against production;
  • all seven tools completed the live ChatGPT in-app-browser workflow;
  • refresh recovery preserved committed work;
  • the A4 report had no horizontal or vertical overflow; and
  • the live browser console contained no warnings or errors.

Public Demo Link

https://gridtwin.vercel.app

Status: ready and publicly accessible; no credentials required.

Public Repository Link

https://github.com/rumi7911/gridtwin

The public repository contains the complete source, assets, setup and testing instructions, WebMCP implementation, committed build evidence, contribution and security guidance, and an MIT license.

Demo Video

Public demo: When the Grid Goes Dark: GridTwin — A Human-Controlled WebMCP Energy Agent

The verified 2:34 public YouTube video includes clear Kokoro narration, burned-in captions, genuine in-app-browser footage of the WebMCP workflow, the outage stress test, and direct human approval.

Production package: timestamped video script, approved narration, and reproducible Remotion workspace.

Published 2:34 outline

  • 0:00–0:12 — Consequence: Riverside Estate faces an eight-hour grid outage.
  • 0:12–0:26 — Decision: A resilience officer must balance cost, emissions, and critical service.
  • 0:26–0:41 — Trust: Synthetic-data caveats, seven WebMCP tools, and human-approved criteria are explicit.
  • 0:41–1:11 — Exploration: Genuine browser footage shows the agent reading, running, comparing, and shortlisting.
  • 1:11–1:35 — Trade-offs: Two infeasible candidates expose their violations; the balanced plan remains feasible.
  • 1:35–1:58 — Outage: Grid contribution falls to zero while the battery serves all eight critical hours.
  • 1:58–2:15 — Authority: The agent advises; the human explicitly approves the plan.
  • 2:15–2:34 — Result: The approved one-page briefing closes the human-agent collaboration story.

Screenshot Shot List

  1. Settled first viewport — docs/hackathon-build/screenshots/pause3-dashboard.png Caption: Riverside Estate baseline, fixed outage, human-owned criteria, all-or-nothing WebMCP readiness, and waiting agent workspace.
  2. Visible agent workflow — docs/hackathon-build/screenshots/pause3-agent-workflow.png Caption: Three deterministic scenarios, direct metric comparison, infeasibility labels, and tool activity in the shared workspace.
  3. Signature outage moment — docs/hackathon-build/screenshots/pause3-outage-moment.png Caption: Grid unavailable at 18:00, battery supplying critical load, and eight served hours through 02:00 before human approval.
  4. Decision brief — docs/hackathon-build/screenshots/pause3-decision-brief.png Caption: Human-approved 275 kWp / 500 kWh plan, headline metrics, alternatives, reserve, outage timeline, assumptions, and indicative-model caveat.

Recommended thumbnail: GridTwin YouTube thumbnail, built around the genuine outage energy-flow result and the human-authority story.

Submission Readiness Notes

Ready

  • Working public Vercel URL with no credentials.
  • Public GitHub source repository with setup instructions and an MIT license.
  • Complete text narrative aligned to WebMCP Leverage, Execution, Potential Impact, and Creativity & Ambition.
  • Seven-tool live WebMCP proof plus deterministic automated coverage.
  • Four polished screenshots, a timed demo-video script, and a verified public 2:34 YouTube demo.
  • Reproducible setup and testing instructions.
  • Honest model scope, provenance, authority, and failure handling.

Built With

Share this project:

Updates

Submission history