Cowork Protocol

A reusable WebMCP collaboration layer for bounded attention, real human authorization, explicit presence, and scoped solo work.

Comment

Inspiration

Web agents often receive either too much page context or too little structure to understand what a person intends. A tool catalog alone also does not answer the collaboration questions: What matters now? Who is present? Who may change what? Did a real person authorize it? Did the page actually change?

Cowork Protocol explores a calmer model: collaborate when both sides are present, hand off bounded work when one side steps away, and make every transition visible.

What it does

Cowork Protocol is a reusable collaboration layer for WebMCP applications.

It adds:

bounded attention through Follow me (pointer, click, keyboard focus, and text selection), Click focus, Text marker only, change/causality, and one-time context expansion; token-aware escalation from a 350-character focus packet to at most 1,200 related characters, requesting more only when justified; visible action offers that remain inert until a trusted human click authorizes the exact displayed value; verified receipts plus latest-only causal changes and human feedback; explicit Cowork, Agent Solo, Human Solo, and Idle presence modes; scoped solo leases limited by goal, target, capability, page version, expiry, and call count; typed or spoken conversation with silence suppression, bounded turns, clickable suggestions, and optional spoken replies; explicit capability levels so reduced bridge guarantees are never presented as native guarantees.

The flagship FormBuilder showcase lets a person and an agent build and review a form together. Only the attributed MIT-licensed web validation/export engine is reused from a pre-existing FormBuilder; the Cowork protocol, WebMCP layer, bridges, interaction model, tests, Browser Companion, and showcase experience are new challenge work.

Why WebMCP

WebMCP supplies the structured action layer. Instead of guessing every possible action from screenshots or DOM noise, an agent receives site-declared tools with schemas.

Cowork Protocol adds the missing collaboration contract around those tools: what is in focus, what may only be proposed, what requires a real human click, when delegated work expires, and how success is verified.

This makes the interaction clearer: point, receive a small suggestion, click to authorize, inspect the receipt, and deliberately hand work over when stepping away.

Native WebMCP implementation

The live FormBuilder registers nine tools through document.modelContext.registerTool():

cowork_read_focus cowork_request_context cowork_read_changes cowork_offer_action cowork_read_presence cowork_execute_solo cowork_read_feedback cowork_read_turn cowork_reply_turn

The native adapter uses stable field targets and application-level verification. Proposal tools never smuggle authorization: mutations stay offer-only until the visible value is accepted by a real click.

A provider-neutral conversation layer emits no turn for silence or while the agent is paused. It sends only the compact utterance, current focus, and presence. An in-page WebMCP agent can pull only the latest pending turn and must reply against its exact unique ID; stale and replayed replies fail closed.

Three connector paths

Native Cowork + WebMCP — stable targets, click-gated mutations, receipts, presence, and scoped solo work. Existing WebMCP bridge — a host-provided tool catalog is summarized within strict budgets; read-only-hinted tools may execute, while mutations remain offer-only. No-WebMCP Browser Companion — an optional, default-off Manifest V3 extension supplies bounded DOM/accessibility callbacks. It escalates through exact 350/1,200-character semantic tiers and finally a pointer-centered crop capped at 400×400 pixels. Visual bytes remain a one-shot extension reference, and value changes still require a trusted click.

The Browser Companion is a working bridge while WebMCP adoption grows. Its bright Dialogue Relay cockpit makes human presence, model engagement, connector route, bounded focus, offers, and handoff state visible without becoming a generic chat sidebar. Native Cowork, WebMCP, and the bounded bridge remain structured action paths; a separate labeled model pointer is reserved for a future genuine Computer Use executor and is never simulated by the current fallback.

The independently movable Desktop Companion uses the same visual language, shows the configured model ID without exposing endpoint or key data, and preserves the user's selected cockpit background across reloads. It does not claim universal discovery on unrelated websites or a connected extension model client.

Preferred-model host

The page can discover a same-origin model host that validates the exact bounded turn while keeping endpoint, model ID, and API key in the server process. The deterministic browser gate sends 468 characters and proves that credentials never enter the page.

A separate provider-backed acceptance used local Ollama 0.32.15 with qwen3:4b: a 502-character bounded turn returned the exact “Grace Hopper” offer, which changed the field only after a trusted click and produced a Verified Receipt. This is a connected local preferred-model claim, not an external or ChatGPT-agent claim.

How I built it

Cowork Protocol is a dependency-light JavaScript workspace using HTML, CSS, Node.js, Manifest V3, and the current WebMCP imperative API.

packages/core: focus packets, causal changes, feedback, offers, authorization, receipts, presence, and leases. packages/conversation: bounded turns, latest-only inbox/reply, silence suppression, and validated offers. packages/model-transport: same-origin browser discovery and server-side OpenAI-compatible gateway. packages/native-webmcp: registration and cleanup through document.modelContext. packages/formbuilder-connector: stable field mapping and verified mutation plans. packages/bridge: bounded WebMCP-host and legacy semantic adapters. apps/formbuilder-showcase: public FormBuilder proof. packages/reference-ui: shared human/model/relay state language across surfaces. apps/browser-companion: optional Native-first Side Panel and bounded no-WebMCP fallback. apps/desktop-companion: movable loopback/tray surface with shared session authority, model identity, audio controls, and persistent appearance.

Development followed strict red-green testing: each behavior began with a failing contract or browser-evidence test, then the smallest passing implementation, followed by the complete regression gate.

Challenges

The hardest problem was not exposing more tools; it was making human-agent handoff legible and enforceable.

A model cannot be allowed to manufacture a human_confirmation argument. Offers are therefore separate from authorization, and a trusted click must still match the offer, target, arguments, page version, and expiry.

Browser evidence also found real issues. A reduced-motion transition briefly moved the skip link outside the viewport at true 200% zoom. Browser-startup races could keep the extension fixture from receiving its isolated context or make a page-owned WebMCP registration appear absent before it was ready. These were closed test-first and are now reproducible acceptance gates.

Evidence

The released commit is f61160e24019d7b8123a3bc816211db873ea19d9.

Current release evidence:

238/238 automated tests; 12/12 character and visual-budget evaluations; 8/8 deterministic juror-proof steps; Chrome 152 discovery of all nine native tools and eight native calls; two click-gated offers, verified changes, latest-only feedback, and exact-ID WebMCP conversation reply; Browser Companion default-off/toggle behavior, Native-first discovery, exact 350/1,200 semantic tiers, real one-shot 160,000-pixel crop, trusted click, and verified mutation; four responsive Side Panel collaboration states with a complete nine-control keyboard path and truthful hidden Computer Use indicator on every current structured route; one shared session across embedded, detached Picture-in-Picture, and movable Desktop surfaces, including model identity and a persistent cockpit background; 25/25 named accessibility controls, Tab stops, and true-200%-zoom controls; ten rendered collaboration states, 902 audited text items, zero failures, minimum contrast 4.5656:1; 23-file Pages artifact and 18-file extension artifact; zero high-confidence secret findings, zero npm vulnerabilities; successful GitHub Pages verification/deployment workflow.

The public Pages HTML and application JavaScript were read back after deployment and match the built release after newline normalization.

What I learned

Attention, authority, presence, and causality need to be separate protocol state.

Small context packets improve more than token use: they make suggestions easier to understand and force the system to explain why it needs more. A verified receipt is more useful than a generic success message because it binds proposal, authorization, observed change, and human evaluation into one bounded chain.

What's next

Next steps are to test the live tools with additional WebMCP clients, connect a genuine Computer Use executor to the already distinct execution-mode signal, and replace the current public video only after the stronger narrated cut passes human sight and hearing approval.

The public repository, working live URL, current video, reproducible commands, architecture diagram, license, attribution, and limitations are all linked from this submission.

Built With

Share this project:

Updates