# 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](https://agent-workflow-lab-consult-bf3cd622be26.herokuapp.com/)
· [redux-webmcp on npm](https://www.npmjs.com/package/redux-webmcp)
· [Package source](https://github.com/breeznik/redux-webmcp)

## 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.

## 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`](https://www.npmjs.com/package/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.

```text
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.

```text
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:

```bash
pnpm add redux-webmcp
```

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

```ts
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`](https://github.com/breeznik/redux-webmcp/blob/main/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](https://agent-workflow-lab-consult-bf3cd622be26.herokuapp.com/).
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.

```bash
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](docs/BACKEND_ADOPTION.md).

## Verify

```bash
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

```text
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](LICENSE)