SOUND Buoy

Human-Anchored Context Governance and Repair for Autonomous Web Agents via WebMCP

Comment

SOUND Buoy

Human-Anchored Context Governance and Repair for Autonomous Web Agents via WebMCP

Live Demo: https://sound-buoy.vercel.app
GitHub Repository: https://github.com/elnicoborja/sound-buoy

Inspiration

Autonomous web agents are becoming active digital workers. They can read a page, navigate an interface, call browser tools, and execute workflows inside web applications. The problem is that most agents still enter complex work environments without enough grounded context.

In creative, operational, and commercial work, this creates a recurring failure mode: the agent acts before it understands the world. It guesses priorities, misreads brand identity, ignores human constraints, and turns partial context into confident plans.

SOUND Buoy was built for that gap.

A buoy marks position, listens to the environment, and gives people a reference point in moving water. SOUND Buoy applies that principle to agent-native web apps. It gives humans a browser-native way to teach an agent the operating reality of a project, review what the agent understood, approve or correct the facts, and only then generate a repair plan.

The goal is simple: before an agent acts, it should know where it is, what is true, what is missing, and what a human has actually approved.

What It Does

SOUND Buoy is a WebMCP-native application for creating, verifying, and exporting actionable operating context.

It runs a structured 5-step protocol:

  1. Intake and source selection
    The user enters raw teaching notes or uploads a Markdown brief that represents the current reality of a project, business, artist, venue, or campaign.

  2. Context reflection
    WebMCP tools parse the input against a 9-slot Benchmark Spine covering income streams, products or releases, audience, distribution channels, content assets, evidence, operations, partnerships, and team capacity.

  3. Human verification gate
    The application shows candidate facts, gaps, and operating principles. The human must approve, refine, or correct the context before the system can continue. No repair plan can be generated until this approval step is complete.

  4. First repair computation
    Once the context is approved, the agent identifies the first useful operational repair. This can be something like creating a world-to-release brief, building an owned-audience bridge, clarifying the next commercial decision, or resolving a documentation gap.

  5. Portable agent world export
    The approved truth, repair action, and 90-day milestone roadmap are exported as agent-world.md. This gives downstream agents, collaborators, and future sessions a clean operating file instead of another loose prompt.

The demo uses independent music as the lead case, with Sonido Vector as the example environment. The same structure also supports seven sector profiles:

  • Independent Music
  • Restaurants and Bars
  • Alcohol Brands
  • Live Events and Festivals
  • Digital Media and Publications
  • Agencies and Professional Services
  • Hospitality and Venues

Each sector uses the same 9-slot topology, but the language adapts to the operating model. For example, music uses releases, fans, and sync. Restaurants use menu moments, guests, and local reach. Agencies use engagements, clients, acquisition, authority, and delivery.

How We Built It

SOUND Buoy is a lightweight static web application with no server dependency.

We registered six browser-level WebMCP tools through navigator.modelContext and document.modelContext:

  • get_learning_modules: exposes the active learning modules and sector specifications.
  • get_artist_cases: provides pre-configured benchmark fixtures and domain examples.
  • reflect_candidate_context: turns human notes into a structured 9-slot candidate reflection.
  • approve_or_correct_context: enforces the human verification gate and stores approved facts.
  • generate_first_repair: creates a targeted repair action from approved context only.
  • export_agent_world: compiles the verified truth into a portable agent-world.md export.

The app uses a dual-mode interaction model. A human can complete the flow manually through the interface, and an autonomous agent can complete the same flow through WebMCP tool calls. Both paths share the same application state, which keeps the experience consistent across human use, browser inspection, and agent execution.

We also implemented a deterministic privacy and redaction layer. Before reflection, the app strips script tags, executable payloads, local machine paths, emails, and credential-like strings. The full parsing, verification, repair, and export lifecycle runs client-side in the browser.

The visual system uses a compact SOUND OS 3-tone palette: deep canvas, card surface, aqua signal accents, and neon lime approval states. A Dark and Light mode switcher is included.

Finally, we added a contract test suite in tests/webmcp-contract.test.js to verify tool schemas, state transitions, approval gating, and export integrity.

Challenges We Ran Into

The hardest problem was enforcing human approval inside an agentic flow. It is easy to let an agent generate a plan immediately after reading input. It is harder to make the state machine refuse that step until a human has approved or corrected the candidate facts.

We also had to balance sector specificity with a shared architecture. Music, hospitality, restaurants, events, media, and agencies use different operating language. We solved that by keeping the same 9-slot spine while allowing each sector to adapt the slot labels and examples.

The third challenge was WebMCP discovery and compatibility. We wanted the app to remain useful as a normal web interface while also exposing structured tools for WebMCP inspectors and agent runtimes. That required the human UI and WebMCP tool layer to operate on the same state, not as separate demos.

Accomplishments That We Are Proud Of

SOUND Buoy is fully client-side. The user can paste or upload sensitive operating context without sending it to an external server.

The application enforces true human governance. It separates raw notes, candidate interpretation, approved truth, and generated repair into distinct stages.

The export is portable. agent-world.md gives future agents a verified operating file they can reuse instead of starting from an ungrounded prompt.

The system is not limited to one demo case. The same 9-slot spine works across seven sectors while preserving sector-specific language.

The WebMCP implementation is testable. The contract suite verifies the core tool calls and state transitions.

What We Learned

Building SOUND Buoy with WebMCP showed us that the next step for web apps is not just better UI for humans. It is better shared workspaces for humans and agents.

When an application exposes structured tools, an agent does not have to guess how the app works by scraping the screen. It can use the app through clear capabilities, schemas, and state boundaries.

The most important lesson was that agent capability needs context governance. A powerful agent without approved context can move quickly in the wrong direction. A grounded agent with human-approved operating truth can become a reliable collaborator.

What Is Next for SOUND Buoy

The next version of SOUND Buoy will add live read-only adapters for platforms like Spotify for Artists, Google Analytics 4, Stripe, Humanitix, and CRM systems. The goal is to let users combine raw human notes with verified platform signals.

We also want to support multi-agent review inside the approved boundary. For example, a financial agent and a creative director agent could inspect the same agent-world.md and recommend different repairs without overwriting the approved truth.

Longer term, SOUND Buoy can become an opt-in benchmarking layer. Creators, venues, publications, and agencies could compare operational health against anonymized sector patterns while keeping their private context under human control.

Built With

  • agent-governance
  • ai-agents
  • artificial-intelligence
  • autonomous-agents
  • browser-apis
  • context-engineering
  • css3
  • cumbia-futurista
  • developer-tools
  • frontend
  • governance
  • html5
  • human-in-the-loop
  • javascript
  • json-schema
  • model-context-protocol
  • multi-agent-systems
  • music-tech
  • node.js
  • open-source
  • prompt-engineering
  • static-web
  • webmcp
  • workflow-automation
Share this project:

Updates

Submission history