SameState

One frontend. Human and agent clients. Shared state.

SameState is an open source developer reference for building agent-native frontends with Redux Toolkit and WebMCP. It shows that an agent can do more than operate a website. It can understand the frontend architecture, exercise real workflows, inspect state transitions, verify rendered data, and communicate with a private website service agent through a safe gateway.

Live application · redux-webmcp on npm · Package source

The developer problem

Browser agents usually see the presentation layer. They can inspect pixels, text, and DOM elements, but they do not automatically understand the application state machine behind the interface.

That creates several problems for frontend developers:

• The agent guesses which controls and sequences are valid.

• A successful click does not prove the expected state transition happened.

• Responsive or visual changes can break selector-based automation.

• The agent cannot easily explain why a flow stopped or which state values changed.

• Redux DevTools is designed for a human developer, not a browser agent.

Related MCP server: tanstack-start-devtools

What SameState adds to WebMCP

WebMCP gives websites a structured way to expose tools to agents. SameState expands that idea into a reusable frontend development architecture.

The redux-webmcp package connects to a Redux Toolkit store and gives the agent four capabilities:

1. Understand

   Read the website purpose, current screen, fields, navigation graph, workflows, available actions, safety rules, and recommended next tools.

2. Act

   Execute declared semantic actions through the same Redux command path used by the visible human interface.

3. Inspect

   Read a sanitized state snapshot and bounded transition history to see what each accepted or rejected action changed.

4. Verify

   Run deterministic scenarios, assert expected state, and compare values rendered by the UI with their Redux state paths.

This turns WebMCP into a practical interface for agent-assisted frontend testing, debugging, regression diagnosis, support workflows, and product automation.

One application path

SameState does not maintain a second agent-only store and does not expose an arbitrary state setter. Humans and agents use the same validation, preconditions, reducers, derived values, and transition recorder.

Human interface ─────┐
                     ├─ semantic action service ─ Redux dispatch ─ application state
WebMCP agent ────────┘                                      ├─ sanitized transitions
                                                           └─ UI and state checks

The reference storefront makes this architecture visible. A person can search, select products, manage a cart, and complete a simulated checkout. An agent can run the same workflow with structured tools and then prove the resulting state.

Agent-to-agent communication

SameState also demonstrates a second WebMCP use case: an external customer agent can communicate with the website's private service agent without exposing private backend tools in the browser.

Customer agent
      │
      │ request_consultation
      ▼
Public WebMCP gateway ─ durable conversation thread
      │
      ▼
Private service agent ─ authorized catalog and delivery capabilities
      ▲
      │
Human customer through Breeze

The public agent receives only three bounded tools:

• request_consultation

• get_consultation_status

• continue_consultation

The private service agent can use protected catalog capabilities on the backend. The browser agent never receives those private tools, schemas, credentials, or internal prompts. Conversation history belongs to the application, so the customer agent, service agent, and human can continue the same thread without losing context.

Messages preserve their actor identity as human, customer_agent, or service_agent. This allows a human to enter the conversation without being confused with either agent.

What people and agents can do together

• A developer can ask an agent to discover and test a complete frontend workflow.

• A human can begin a task visually and let an agent continue through semantic tools.

• The agent can explain each state transition instead of reporting only that it clicked.

• The agent can verify totals, workflow state, and UI alignment after acting.

• A customer agent can ask the website's service agent for protected expertise.

• A human can read and continue the same durable agent-to-agent conversation in Breeze.

• Consequential actions can remain behind explicit human confirmation.

How WebMCP is implemented

The frontend installs the published package directly from npm:

pnpm add redux-webmcp

The application creates one bridge, adds its Redux middleware, and attaches the store. This shortened example shows the integration boundary:

import { configureStore } from '@reduxjs/toolkit';
import { connectReduxWebMCP } from 'redux-webmcp';

const bridge = connectReduxWebMCP({
  appName: 'SameState',
  mode: shouldEnableWebMCP ? 'developer' : 'off',
  actions: semanticActions,
  applicationMap,
  observeUI: observeSemanticUI,
  selectSnapshot: selectAgentSafeState,
  redactPaths: ['checkout.email', 'checkout.address'],
});

const store = configureStore({
  reducer: applicationReducer,
  middleware: (getDefaultMiddleware) =>
    getDefaultMiddleware().concat(bridge.middleware),
});

void bridge.attach(store);

redux-webmcp registers its tools through document.modelContext.registerTool(). The authoritative registration implementation is in src/webmcp.ts.

The release candidate is verified against exact version redux-webmcp@0.1.1. The package source is intentionally maintained in its own public repository rather than duplicated in this project. The dependency will move from the locally verified 0.1.1 tarball to the exact npm artifact only after the package release is approved.

Safety boundaries

• There is no arbitrary state setter.

• Every semantic action has a bounded input schema.

• Screen context and preconditions can reject unavailable actions.

• Sensitive state paths are redacted before tool output is created.

• Transition history and tool responses are length bounded.

• Replay validates the complete scenario before reset, and cursor pages move forward without skipping intervening transitions.

• Confirmation-required actions stop until a human approves them.

• Agent cancellation propagates to consultation fetches and restores a non-error UI state.

• Private backend capabilities remain behind the service agent gateway.

• Customer content and agent responses are treated as untrusted application data.

Judge walkthrough

Use ChatGPT's in-app browser, or Chrome 149+ with WebMCP testing enabled.

1. Open the live application.

2. Call redux_initialize_agent to receive the product purpose, application map, capabilities, current context, rules, and recommended tools.

3. Call redux_run_scenario with search, selection, cart, and navigation actions.

4. Call redux_assert_state to verify the current screen, cart item, quantity, and total.

5. Open Agent view to see the same transitions and architecture report visually.

6. Call request_consultation to start a thread with the private website service agent.

7. Reuse its thread_id with continue_consultation to prove context is retained.

8. Open Breeze to inspect or continue the same application-owned conversation.

No account, payment, or real order fulfillment is required.

Firefox and ordinary browsers can use the human interface, but they report WebMCP as unavailable when they do not expose document.modelContext.

Challenge-period work

The WebMCP Challenge submission period began on August 25, 2026. The public histories for both SameState and redux-webmcp begin on August 30, 2026.

Work completed during the challenge includes:

• The reusable Redux and WebMCP package.

• Semantic action registration and raw Redux action support.

• The application structure map and first-contact agent context.

• Sanitized transition recording and UI-state verification.

• Deterministic scenario replay and state assertions.

• The SameState reference frontend and responsive Agent view.

• The durable agent-to-agent consultation gateway.

• The private service agent, capability broker, and conversation history.

• The published npm package integration used by this application.

The dated commit histories provide the implementation record.

Run locally

Requirements: Node.js 20 or newer and pnpm 10 or newer.

pnpm install
pnpm dev

Open http://localhost:4173. Vite will print another local port if it is occupied.

The storefront and Redux WebMCP flow work without the consultation service. Breeze requires the consultation API and PostgreSQL configuration described in the backend adoption guide.

Verify

pnpm test
pnpm typecheck
pnpm build
pnpm build:challenge
pnpm test:browser
pnpm audit:production

The standard production build disables WebMCP. The challenge build intentionally enables the bounded agent surface for the hosted demonstration. The browser test injects a document.modelContext adapter and verifies all 34 tools, safe replay, forward transition pagination, Redux and UI parity, Agent View, and Breeze.

Repository structure

apps/
  agent-workflow-lab/      React, Redux Toolkit, and WebMCP reference frontend
  consultation-api/       Fastify service agent and durable consultation backend
packages/
  consultation-contracts/ Shared public conversation contracts

License

MIT