Ribband

Source-backed personal decisions for shopping, gifts, dates, vacations, and project staffing.

Comment

Ribband: About

Inspiration

Most recommendation tools begin with a category and a search box. People rarely make decisions that way. A good vacation can echo a childhood memory. A good gift depends on who it is for, what they already love, and the occasion. A good date balances two people and avoids repeating what they have already done. A project crew needs the right roles, credentials, equipment, location, and schedule.

At the same time, most of the web is designed to be seen, not understood by an agent. Important facts are buried inside presentation markup, forcing agents to infer controls and reconstruct evidence out of sight of the person who asked for help.

Ribband explores a clearer contract for the next era of surfing the web: let an agent understand the personal context a person deliberately shares, move quickly across explicitly authorized sources, preserve the evidence, and keep consequential actions with the person. The name nods to the Blue Riband, the historic distinction associated with speed records on Atlantic passenger crossings.

What it does

Ribband is an open-source, source-backed personal decision agent for five everyday needs:

  1. Shopping: compare products for yourself using goals, preferences, exclusions, existing items, and a budget.
  2. Gifts: recommend options using the recipient's age, interests, occasion, deadline, dislikes, and whatever else the shopper chooses to provide.
  3. Dates: balance two people's interests, constraints, prior activities, and desired mood across low-cost, balanced, and special-occasion ideas.
  4. Vacations: turn visited places, fond memories, desired novelty, dates, party size, and budget into value, balanced, and signature packages containing lodging, transportation, dining, and activities.
  5. Project staffing: assemble eligible laborers, technicians, and creatives by role, credential, equipment, geography, schedule, and quote mode while surfacing coverage gaps instead of inventing a match.

A person can begin with a sparse goal and budget or share richer context. One read-only plan_decision WebMCP tool routes an explicit vertical through a fixed deterministic strategy and returns a DecisionEnvelope containing the selected strategy, exact context projection, evidence state, ranked options, tradeoffs, price range, revision linkage, and available next actions. General shopping is self-directed; gifts add recipient and occasion context rather than disguising every purchase as a gift.

Ribband also preserves its original evidence workspace. Ten WebMCP tools let an agent list and select allowlisted origins, search and rank Offers, inspect product pages as stripped Markdown plus structured data, compare products, build a grounded brief, assemble a planning-only activity itinerary, and stage a purchase review. Both surfaces use the same normalized Offer protocol and the same visible workspace as the person.

The agent can prepare, explain, and revise a decision. It cannot silently buy, book, contact a provider, request a quote, sign a contract, or save personal memory. Purchase handoff, provider-source opening, and memory approval remain separate visible human controls.

How I built it

Ribband is a TypeScript application running on Cloudflare Workers. The primary Worker serves the human workspace, same-origin APIs, security controls, diagnostics, and WebMCP handlers. A separate controlled public Worker serves original goods and service fixtures over live HTTPS.

Every source adapter compiles into one Offer graph. Product feeds and page JSON-LD reconcile price, availability, condition, shipping, and returns. Service Offers add provider, location, duration, price basis, party limits, published windows, cancellation terms, credentials, service radius, and itinerary or staffing eligibility. Decision fields preserve canonical source links and are labeled verified, single-source, or conflict.

The unified orchestrator projects only the context needed by the chosen vertical. Hard exclusions are applied before scoring. Deterministic strategies then expose their factors, reasons, tradeoffs, unknown costs, and source state rather than hiding the ranking inside an opaque model response. Revisions resubmit the complete visible context and link to the prior page-memory decision id; the Worker stores neither request.

Vacation packages combine lodging, transportation, dining, and activities with category totals, contingency, and explicit unknown costs. Staffing plans combine controlled provider Offers, fail closed on missing roles or unverified geography, and require a second human review showing the destination and transmitted information before a provider source can open.

Trust boundary

Ribband never accepts an arbitrary upstream URL. Every upstream request must use HTTPS, match an exact authorized hostname and path, remain within byte and time limits, and reject off-origin or out-of-scope redirects. Each origin has a validated authorization manifest describing capabilities, response limits, freshness policy, and review date. Expired origins fail closed before an upstream request is made.

The current controlled catalog intentionally demonstrates guitars rather than claiming arbitrary retail coverage. The controlled service directory contains 20 original fixtures: 5 activities, 1 wellness service, 1 home service, 3 lodging Offers, 2 dining Offers, 2 transportation Offers, and 6 professional services. These fixtures prove the data contract, provenance, planning, and action boundaries; they do not claim live inventory, measured travel time, reservations, messages, contracts, orders, or payments.

Date and vacation outcomes can create a tentative memory proposal, but only a visible human approval can save the exact reviewed fact in that browser. Saved facts remain unselected until the person chooses them for a later decision, and the person can correct or delete them. There are no cookies, analytics identifiers, hidden profile reads, or hidden approval paths.

Challenges and learning

The central challenge was making personalization genuinely useful without turning personal context into invisible surveillance or giving the agent irreversible authority. Extending one Offer protocol from products into dates, vacations, and staffing also required separating facts that can be normalized from actions that remain specific to a vertical.

The strongest lesson was that an agent interface should expose more than tools. Trust improves when the person can see the context used, authorization, source state, ranking factors, uncertainty, conflicts, activity, and the exact point where automation stops. A safe refusal is part of the product: Ribband should stop when evidence is stale, contradictory, out of scope, or insufficient.

Current verification

The deployed release passes strict TypeScript checking, 217 automated tests across 28 test files, eight running-Worker release checks, deployment dry runs for both Cloudflare Workers, and 30 production checks. Browser acceptance exercises all five strategies through WebMCP, the complete outcome-memory consent cycle, eligible and ineligible staffing source review, the homepage entry point, and a 390-pixel mobile layout with no horizontal overflow or console errors. The public /health response exposes the exact deployed Git commit and Worker version.

Built With

Share this project:

Updates

Submission history