LifeHack 2026

Woven

Everything works together.

An agentic-commerce app inside ChatGPT and Codex, backed by bounded mission orchestration and deterministic checkout controls. One request becomes a complete cart; only the user can approve the exact purchase.

Ask once. Review once. Confirm once.

Open Woven · Run the live demo · WebMCP challenge kit · Install Woven · Run locally · Product requirements · Technical architecture · Devpost submission kit · 3-minute pitch · Live demo · Report an issue

> [!IMPORTANT] > Woven is a hackathon prototype. Merchants, inventory, prices, and Visa > authorization responses are seeded or simulated. It collects no card > credentials and cannot make a live charge.

Table of contents

About the project Why ChatGPT and why a plugin? How it works The three-minute story Product gallery Architecture Built with Getting started Usage Trust and safety Testing Roadmap Contributing License Contact Acknowledgments

About the project

Search gives you links. Buying still takes work.

Imagine taking two first-time campers away for a rainy weekend. You still have to size the shelter, duplicate the sleep gear, check weather ratings, keep the packed kit inside one car boot, find one store with everything in stock, and rebuild the cart at checkout.

Woven finishes that job inside the AI workflow the user already uses. Ask ChatGPT or Codex once and Woven returns complete carts from one pickup location, opens a Choice Center to compare five options, shows why every item works together, rechecks the price and stock, and waits for a separate human confirmation before authorization.

The in-chat MCP App and browser-native WebMCP tools are interaction layers, not the whole backend. Woven's Node.js service owns mission routing, a bounded orchestration workflow for non-camping requests, deterministic cart verification, SQLite state, and the checkout trust boundary.

The canonical mission is deliberately concrete:

> I need a complete rainy-weekend camping kit for 2 first-time campers. Keep it > under S$300, fit it in one car boot, and make it pickup-ready today.

Why it is different

| Product search | Woven | | --- | --- | | Ranks individual items | Ranks complete, compatible carts | | Leaves stock and pickup implicit | Uses current demo stock and pickup timing | | May mix merchants | Returns one pickup location per cart | | Makes the user reconstruct compatibility | Shows a proof for every component | | Forces a single recommendation | Compares five complete choices and lets the user rerank them | | Blurs recommendation and purchase | Requires an exact, expiring confirmation |

(back to top)

Why ChatGPT? Why a plugin?

The shopping request already exists in the conversation. A standalone app would make the user repeat it, while Woven can turn that same request into bounded merchant actions and return a structured checkout for review.

The primary product is a real MCP App/plugin inside ChatGPT or Codex. The model can ask Woven to build carts, but app-only tools and a direct user click protect checkout. The /demo browser route is a stage-safe rehearsal of that experience: a clearly labeled simulated chat host that types the canonical request, shows every MCP tool call live, and drives the same backend. It is marked “Simulated” on screen and is not a second product.

The /webmcp route adds seven imperative, top-level WebMCP site tools to the same page. An agent can start or inspect a mission, open the shared comparison UI, select a cart, apply a merchant-approved swap, refresh current offers, and verify a receipt. Identity, checkout preview, and purchase confirmation are deliberately absent: those remain direct human actions in the visible page.

MCP supplies the host connection, tool contract, private widget metadata, and embedded UI. After start_mission reaches Woven, the server—not the host model—routes the request, runs any required orchestration, classifies evidence, and decides whether a cart is checkout-eligible.

(back to top)

How it works

1. Ask once. An MCP host or the WebMCP-enabled site calls start_mission

with the user's mission and any structured constraints.

1. Route and orchestrate. The canonical camping request uses the deterministic

engine. Other categories enter a fixed LangGraph.js workflow that interprets a MissionSpec, discovers connected offers and cited research, normalizes, composes, verifies, and retries at most once.

1. Build complete carts. Deterministic server rules reject incompatible,

unverifiable, or unavailable offers, stay under budget, and return up to five one-location options. Web findings remain research-only.

1. Compare and choose. The Choice Center reranks by value, pickup speed,

rain protection, or preferred area; optional saved preferences stay local.

1. Show the proof. The MCP App widget explains tent capacity and rain rating,

two sleeping bags, two mats, lantern protection, first-aid coverage, packed volume, live demo stock, total, pickup plan, and approved substitutions.

1. Verify the demo identity. A provider-style page returns a single-use

code; Woven validates state + PKCE and creates a short-lived server session.

1. Review once. The server rechecks price and stock and creates a ten-minute

mandate bound to the identity session, merchant, cart version, and amount.

1. Confirm once. A private nonce, mandate hash, and idempotency key are

verified before the simulated authorization, merchant order, and signed server-verifiable receipt.

The AI recommends. The user chooses. Woven binds the exact terms.

Bounded orchestration backend

The canonical camping demo above is still deterministic and unchanged. Woven also includes a credential-dormant TypeScript orchestration POC for non-camping missions. This is a backend layer behind the same start_mission tool, not a second MCP server or a host-model prompt convention:

• a fixed LangGraph.js flow interprets a validated MissionSpec, discovers

connected and web offers in parallel, normalizes, composes, verifies, retries at most once, ranks, and persists;

• connected catalog offers can form checkout carts only after the server verifies

every hard requirement, compatibility link, quantity, stock, budget, merchant, and pickup location;

• web results remain cited research leads with checkout disabled; and
• preview and confirmation rebuild connected carts from current SQLite catalog

rows, preserving the existing identity, nonce, mandate, idempotency, and atomic inventory protections.

The POC uses the OpenAI Responses API with schema-constrained output, gpt-5.6-terra, medium reasoning, built-in web search, and store: false. No API credential is required for the camping demo or CI. Without OPENAI_API_KEY, a non-camping mission returns retryable AGENT_UNAVAILABLE rather than fabricated results. Developers who already have a key can run the opt-in live matrix with npm run eval:agent.

(back to top)

The three-minute story

Ask once
   ↓
Receive complete one-merchant carts
   ↓
Compare five choices and tune priorities
   ↓
See why everything works together
   ↓
Verify the simulated demo identity
   ↓
Review the exact merchant, items, pickup, and total
   ↓
Confirm once
   ↓
Receive a simulated Visa result and pickup receipt

The working prototype includes a simulated connector-style identity check before checkout. It is server-enforced but is not a Visa login, KYC, or a real identity-provider integration. It remains separate from final purchase confirmation and never collects Visa credentials or card data.

See [script.md](script.md) for the exact narration, stage actions, fallback path, and the working identity handoff.

Render the judge video

The repository includes a three-minute Remotion composition that follows the authoritative script, uses the verified Woven product frames, and labels both identity and Visa authorization as simulated.

npm run video:studio   # preview and scrub the composition
npm run video:render   # output/Woven-Judge-Video.mp4

The sidecar captions are in video/Woven-Judge-Video.srt. The bundled voice is AI-generated with ElevenLabs and can be replaced by swapping the files in public/woven-video/voiceover/ without changing the timeline.

(back to top)

Product gallery

Born inside the chat.One message becomes a live MCP app — visible tool calls, then five complete carts in the Choice Center. A visible authorization boundary.The exact merchant, pickup, items, and total are bound before confirmation.

A separate identity gate.The provider-style simulator creates a short-lived server session without collecting Visa, card, or payment credentials.

A pickup-ready result.The user receives a simulated authorization result and receipt. A controllable live demo.Inventory, pricing, declines, order failures, and the audit trail are visible on stage.

(back to top)

Architecture

Woven is one deployable Node.js service with five explicit layers: MCP/HTTP interaction, mission routing and bounded orchestration, deterministic commerce verification, SQLite checkout state, and the payment adapter. The browser fallback and merchant desk enter the same backend as the MCP App. The real payment integration boundary is isolated in src/payment.ts; the current adapter intentionally fails closed unless PAYMENT_MODE=simulated.

LangGraph.js coordinates the non-camping workflow; OpenAI supplies structured interpretation and cited web research; deterministic TypeScript rules decide whether connected offers satisfy the mission; and the SQLite store revalidates them before checkout. MCP carries inputs and results but does not own those backend decisions.

Detailed tool contracts, state transitions, cart rules, and trust boundaries are documented in [the architecture guide](docs/architecture.md). The live target-architecture explainer visualizes those boundaries without implying a current Visa integration.

(back to top)

Built with

• TypeScript and Node.js
• React and Vite
• Tailwind CSS and shadcn/ui
• Model Context Protocol SDK
• MCP Apps
• Express
• Node's built-in SQLite
• Zod
• LangGraph.js for the bounded open-world workflow
• OpenAI Responses API for optional structured interpretation and cited web research
• Remotion for the three-minute judge video

(back to top)

Getting started

Prerequisites

• Node.js 22.5 or newer
• npm

Installation

For the exact Codex desktop, Codex CLI, and ChatGPT Developer Mode steps—with expected output and troubleshooting—use the [installation and verification guide](docs/INSTALLATION.md).

git clone https://github.com/Ducksss/LifeHack-2026.git
cd LifeHack-2026
npm ci
npm run check
npm start

Open the local surfaces:

| Surface | URL | | --- | --- | | Landing page | | | Buyer fallback | | | WebMCP workspace | | | Demo identity connector | | | Merchant desk | | | Install guide | | | MCP endpoint | | | Health check | |

The verified public deployment is available at visa-woven.vercel.app, with the buyer demo at /demo and merchant desk at /merchant. Its SQLite database lives in Vercel's temporary filesystem, so demo state may reset after a cold start or redeployment.

Add ?loop=true to /demo for an unattended visual walkthrough. It compares and reranks carts, returns to the selected kit, shows the compatibility proof and approved swap, completes the server-enforced simulated identity handoff, shows the verified state and host reply, then fades back to the start. It never creates a checkout mandate or confirms a purchase.

Open /webmcp in a current WebMCP-capable ChatGPT or Codex browser session to discover the seven page tools. The readiness card and shared activity rail make agent actions visible; the browser and MCP transports enter the same server-owned mission router.

Connect the ChatGPT app

Follow the [ChatGPT connection guide](docs/INSTALLATION.md#3-connect-woven-to-chatgpt). It covers the required public HTTPS endpoint, Developer Mode setup, discovered tools, and expected widget result. ChatGPT cannot connect to localhost.

Current OpenAI references: [plugin quickstart][openai-quickstart], [MCP server guide][openai-mcp], [ChatGPT UI guide][openai-ui], and [connection guide][openai-connect].

Connect the Codex plugin

Follow the [local Codex installation guide](docs/INSTALLATION.md#2-recommended-install-in-codex-desktop). The repository includes a Woven Local marketplace entry; its bundled stdio server returns a self-contained Choice Center; port 8788 remains available only for the simulated identity handoff.

(back to top)

Usage

Happy-path demo

Use the complete [three-minute stage script](script.md). The working happy path is:

1. Open /demo — the simulated chat host types the canonical request, plays the

start_mission activity, and opens the Choice Center with five ranked carts.

1. Compare carts, tune a priority or pickup area, then select a kit and inspect

its compatibility proof and pickup plan.

1. Click Review checkout, then Verify demo identity.
2. On /identity, click Continue as Chai; return and check the result. If

authorization is still pending, the same status action reopens the handoff.

1. Review the exact, expiring mandate and click Confirm S$231.00.
2. Show the simulated Visa result and signed receipt.

Trust/failure demo

Use /merchant to select a scenario, then replay checkout:

• Stockout or Price change invalidates an old preview.
• Auth decline creates no merchant order.
• Order failure enters reversal after simulated authorization.
• Reset demo data restores stock and clears the local run.

Catalog updates

The merchant desk exports and imports a deliberately small CSV contract:

offer_id,price_sgd,stock
trailhaus-funan-th-storm2,89.00,4

Imports update only known offers and reject malformed prices, negative values, and fractional stock. A demo upload cannot silently create incompatible SKUs.

Commands

npm run dev          # Vite UI development server
npm run dev:server   # API/MCP server with restart-on-change
npm run build        # production bundle + TypeScript validation
npm test             # domain, security, idempotency, failure, and CSV checks
npm run check        # full test and build gate
npm run mcp          # stdio MCP transport used by the Codex plugin
npm run video:studio # preview the three-minute judge video
npm run video:render # render output/Woven-Judge-Video.mp4

Configuration

| Variable | Default | Purpose | | --- | --- | --- | | PORT | 8787 | HTTP server port | | BASE_URL | http://localhost:8787 | Public widget asset/CSP origin | | WOVEN_DB | ./data/woven.db | SQLite demo state | | PAYMENT_MODE | simulated | Guardrail; every other value fails closed | | OPENAI_API_KEY | unset | Optional; enables non-camping orchestration. Camping, build, and CI remain credential-fr

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Ducksss
• Source: Ducksss/LifeHack-2026
• License: MIT
• Homepage: https://visa-woven.vercel.app/

Install and usage instructions live in the source repository linked above.