hilos-agent 0.11.16 → 0.11.17

package/README.md

@@ -544,3 +544,19 @@ real tagged release proves OIDC end to end. After that proof, remove the
 workflow fallback, revoke the npm token, and delete the GitHub secret (1094,
 1211, 1228). Because the source repository is private, npm will not attach a
 public provenance attestation even when the publish itself uses OIDC.
+
+## Browser agents and WebMCP
+
+A WebMCP-enabled browser can use the signed-in hilos workspace directly.
+Open Settings → Connections to check page-tool registration. Start with
+`get_hilos_context`, then `navigate_hilos`; Docs, Tasks, rooms, activity and
+onboarding register their own commands. No personal token or plugin is needed
+for that browser session. See [WebMCP setup](https://hilos.sh/docs/webmcp).
+
+The plugin and coding-client skills use remote MCP. They do not make Claude
+Code, Codex, or Cursor into browser WebMCP consumers. For background work, keep
+the personal or named-agent MCP connection. The local daemon's optional
+`hilos-agent webmcp` bridge uses an isolated signed-in profile and exact
+person-approved read tools. Its `tools` response distinguishes native from
+limited imperative compatibility mode. Rediscover after navigation; calls bind
+to the inspected page and never retry on site-provided error text.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hilos-agent",
-  "version": "0.11.16",
+  "version": "0.11.17",
   "description": "Run your own coding agent (Claude Code, Codex, Cursor, OpenCode, Hermes, or any command) as a teammate in a hilos room. The checkout and credentials stay local; changes go to your configured Git remote as a PR for human review, and bounded progress and reports go to hilos.",
   "type": "module",
   "bin": {
@@ -27,6 +27,7 @@
   "keywords": [
     "hilos",
     "mcp",
+    "webmcp",
     "agent",
     "claude-code",
     "codex",

package/skills/hilos-connect/SKILL.md

@@ -5,6 +5,13 @@ description: Connect a named agent to a hilos room with the local daemon. Use wh
 
 # Connect
 
+If the person wants a browser agent to use the hilos page already open, use
+[WebMCP setup](https://hilos.sh/docs/webmcp): sign in in a supported browser,
+check Settings → Connections, then discover `get_hilos_context` and
+`navigate_hilos`. No token or daemon is needed for that page session. Do not
+claim this plugin adds browser WebMCP to a coding client. Personal remote MCP
+uses Settings → Connections; a named local agent uses the steps below.
+
 1. Get the private join code from the person or the agent's connection dialog.
    Treat it as a credential. Never paste it into chat, reports, or logs.
 2. From the folder the daemon will work in, run

package/src/webmcp-bridge.mjs

@@ -18,8 +18,8 @@ const AGENT_BROWSER_BIN = "agent-browser/bin/agent-browser.js";
 const AGENT_BROWSER_MISSING =
   "WebMCP needs Node.js 24 or newer and agent-browser. Upgrade Node.js, reinstall hilos-agent, then run `agent-browser install`.";
 const MAX_CAPTURE_CHARS = 256 * 1024;
-const MAX_INPUT_CHARS = 16 * 1024;
-const MAX_RESULT_CHARS = 64 * 1024;
+const MAX_INPUT_BYTES = 16 * 1024;
+const MAX_RESULT_BYTES = 64 * 1024;
 const MAX_ORIGINS = 32;
 const MAX_READ_TOOLS_PER_ORIGIN = 64;
 const TOOL_NAME = /^[A-Za-z0-9_.-]{1,128}$/;
@@ -130,7 +130,8 @@ const SCHEMA_KEYS = new Set([
 
 /** Strip prose-bearing schema fields so tool poisoning never becomes instructions. */
 export function sanitizeWebMcpSchema(value, depth = 0) {
-  if (depth > 12 || value == null || typeof value !== "object") return value;
+  if (depth > 12) return undefined;
+  if (value == null || typeof value !== "object") return value;
   if (Array.isArray(value)) return value.slice(0, 64).map((item) => sanitizeWebMcpSchema(item, depth + 1));
   const out = {};
   for (const [key, child] of Object.entries(value).slice(0, 256)) {
@@ -144,6 +145,7 @@ export function sanitizeWebMcpSchema(value, depth = 0) {
       continue;
     }
     if (!SCHEMA_KEYS.has(key)) continue;
+    if (key === "$ref" && (typeof child !== "string" || !child.startsWith("#"))) continue;
     out[key] = sanitizeWebMcpSchema(child, depth + 1);
   }
   return out;
@@ -293,9 +295,9 @@ function evalResult(run) {
   return run?.json?.data?.result;
 }
 
-function encodedCall(name, input) {
-  const payload = Buffer.from(JSON.stringify({ name, input }), "utf8").toString("base64");
-  return `(() => { const p = JSON.parse(atob("${payload}")); return window.__hilosWebMcpBridge.call(p.name, p.input); })()`;
+function encodedCall(name, input, expected) {
+  const payload = Buffer.from(JSON.stringify({ name, input, expected }), "utf8").toString("base64");
+  return `(() => { const bytes = Uint8Array.from(atob("${payload}"), c => c.charCodeAt(0)); const p = JSON.parse(new TextDecoder().decode(bytes)); return window.__hilosWebMcpBridge.call(p.name, p.input, p.expected); })()`;
 }
 
 async function listTools(policy, runner) {
@@ -315,16 +317,18 @@ async function listTools(policy, runner) {
     : "/";
   const registered = Array.isArray(raw?.tools) ? raw.tools : [];
   const allowed = registered
-    .filter((tool) => originPolicy.readTools.has(tool?.name))
+    .filter((tool) => originPolicy.readTools.has(tool?.name) && !tool.schemaOmitted && tool.annotations?.consequentialHint !== true)
     .map((tool) => ({
       name: tool.name,
-      inputSchema: tool.schemaOmitted ? undefined : sanitizeWebMcpSchema(tool.inputSchema || {}),
+      inputSchema: sanitizeWebMcpSchema(tool.inputSchema || {}),
       personApprovedRisk: "read",
       siteReadOnlyHint: tool.annotations?.readOnlyHint === true,
     }));
   return {
     ok: true,
     source: { origin, pagePath },
+    discoveryId: typeof raw?.discoveryId === "string" ? raw.discoveryId : null,
+    mode: raw?.mode === "native" ? "native" : "compatibility",
     tools: allowed,
     blockedToolCount: Math.max(0, registered.length - allowed.length),
     untrusted: true,
@@ -377,7 +381,7 @@ export async function runWebMcpCommand(cfg, operation, args = [], options = {})
     let input;
     try {
       const text = args[1] == null ? "{}" : String(args[1]);
-      if (text.length > MAX_INPUT_CHARS) throw new Error("too large");
+      if (Buffer.byteLength(text, "utf8") > MAX_INPUT_BYTES) throw new Error("too large");
       input = JSON.parse(text);
       if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error("not an object");
     } catch {
@@ -395,9 +399,10 @@ export async function runWebMcpCommand(cfg, operation, args = [], options = {})
         tool: name,
       };
     }
+    if (!available.discoveryId) return { ok: false, code: "stale_bridge", error: "Close and reopen the WebMCP browser to load the current bridge." };
     const run = await runner(
       policy.browserCommand,
-      browserArgs(policy, ["eval", encodedCall(name, input)]),
+      browserArgs(policy, ["eval", encodedCall(name, input, { ...available.source, discoveryId: available.discoveryId })]),
     );
     if (!run.ok) {
       return {
@@ -414,12 +419,12 @@ export async function runWebMcpCommand(cfg, operation, args = [], options = {})
     if (
       origin !== available.source.origin ||
       resultPagePath !== available.source.pagePath ||
-      raw?.tool !== name
+      raw?.tool !== name || raw?.discoveryId !== available.discoveryId
     ) {
       return { ok: false, code: "provenance_mismatch", error: "The page changed while the WebMCP tool was running; its result was discarded." };
     }
     const resultJson = typeof raw?.resultJson === "string" ? raw.resultJson : "null";
-    if (resultJson.length > MAX_RESULT_CHARS) {
+    if (Buffer.byteLength(resultJson, "utf8") > MAX_RESULT_BYTES) {
       return { ok: false, code: "result_too_large", error: "The WebMCP tool result exceeded the 64 KB limit." };
     }
     let result;

package/src/webmcp-init.js

@@ -10,8 +10,8 @@
 
   const TOOL_NAME = /^[A-Za-z0-9_.-]{1,128}$/;
   const MAX_TOOLS = 64;
-  const MAX_SCHEMA_CHARS = 32 * 1024;
-  const MAX_RESULT_CHARS = 64 * 1024;
+  const MAX_SCHEMA_BYTES = 32 * 1024;
+  const MAX_RESULT_BYTES = 64 * 1024;
 
   const copyJson = (value) => {
     if (value === undefined) return undefined;
@@ -29,12 +29,7 @@
   };
 
   function installFallbackModelContext() {
-    if (
-      document.modelContext &&
-      typeof document.modelContext.registerTool === "function" &&
-      typeof document.modelContext.getTools === "function" &&
-      typeof document.modelContext.executeTool === "function"
-    ) {
+    if (document.modelContext && typeof document.modelContext.registerTool === "function") {
       return document.modelContext;
     }
 
@@ -78,9 +73,13 @@
             throw options.signal.reason || domError("Registration aborted", "AbortError");
           }
 
+          if (tools.size >= MAX_TOOLS) throw new RangeError("Too many WebMCP tools");
           const inputSchema = copyJson(tool.inputSchema);
+          if (inputSchema !== undefined && (!inputSchema || typeof inputSchema !== "object" || Array.isArray(inputSchema) || (inputSchema.type && inputSchema.type !== "object"))) {
+            throw new TypeError("WebMCP input schema must describe an object");
+          }
           const schemaText = JSON.stringify(inputSchema ?? {});
-          if (schemaText.length > MAX_SCHEMA_CHARS) {
+          if (new TextEncoder().encode(schemaText).length > MAX_SCHEMA_BYTES) {
             throw new TypeError("WebMCP input schema is too large");
           }
           const entry = {
@@ -92,6 +91,7 @@
               ? {
                   readOnlyHint: tool.annotations.readOnlyHint === true,
                   untrustedContentHint: tool.annotations.untrustedContentHint === true,
+                  consequentialHint: tool.annotations.consequentialHint === true,
                 }
               : undefined,
             execute: tool.execute,
@@ -117,7 +117,10 @@
         }
       },
 
-      async getTools() {
+      async getTools(options = {}) {
+        if (options.fromOrigins?.some((origin) => origin !== location.origin)) {
+          throw domError("The hilos compatibility bridge supports this document only", "NotSupportedError");
+        }
         return [...tools.values()]
           .sort((a, b) => a.name.localeCompare(b.name))
           .map((tool) => ({
@@ -142,12 +145,26 @@
         const tool = tools.get(name);
         if (!tool) throw domError(`WebMCP tool ${name} is not registered`, "NotFoundError");
 
+        if (registeredTool.origin !== location.origin || registeredTool.window !== window) {
+          throw domError("WebMCP tool belongs to another document", "SecurityError");
+        }
         const controller = new AbortController();
-        const onAbort = () => controller.abort(options.signal?.reason);
+        let rejectAbort;
+        const aborted = new Promise((_, reject) => { rejectAbort = reject; });
+        const onAbort = () => {
+          controller.abort(options.signal?.reason);
+          rejectAbort(controller.signal.reason);
+        };
         options.signal?.addEventListener("abort", onAbort, { once: true });
         try {
-          const value = await tool.execute(copyJson(inputObject), { signal: controller.signal });
-          return JSON.stringify(value);
+          const value = await Promise.race([
+            Promise.resolve().then(() => {
+              controller.signal.throwIfAborted();
+              return tool.execute(copyJson(inputObject), { signal: controller.signal });
+            }),
+            aborted,
+          ]);
+          return JSON.stringify(value) ?? "null";
         } finally {
           options.signal?.removeEventListener("abort", onAbort);
         }
@@ -179,7 +196,11 @@
     return context;
   }
 
+  const native = Boolean(document.modelContext?.registerTool);
   const modelContext = installFallbackModelContext();
+  let epoch = 0;
+  let discovery = null;
+  modelContext.addEventListener?.("toolchange", () => { epoch++; });
 
   const source = () => ({
     origin: location.origin,
@@ -187,24 +208,30 @@
   });
 
   async function registeredTools() {
+    if (typeof modelContext.getTools !== "function" || typeof modelContext.executeTool !== "function") {
+      throw domError("This native WebMCP build has no in-page consumer API. Update the browser; hilos will not replace its native provider.", "NotSupportedError");
+    }
     const tools = await modelContext.getTools();
     return (Array.isArray(tools) ? tools : [])
-      .filter((tool) => tool && tool.origin === location.origin)
+      .filter((tool) => tool && tool.origin === location.origin && tool.window === window)
       .slice(0, MAX_TOOLS);
   }
 
   const bridge = Object.freeze({
     version: 1,
-    mode:
-      document.modelContext === modelContext &&
-      Object.prototype.hasOwnProperty.call(document, "modelContext")
-        ? "polyfill"
-        : "native",
+    mode: native ? "native" : "compatibility",
 
     async list() {
+      const before = { href: location.href, epoch };
       const tools = await registeredTools();
+      if (before.href !== location.href || before.epoch !== epoch) {
+        throw domError("The page changed during discovery. List its tools again.", "InvalidStateError");
+      }
+      discovery = { id: crypto.randomUUID(), href: before.href, epoch: before.epoch, tools };
       return {
         ...source(),
+        discoveryId: discovery.id,
+        mode: native ? "native" : "compatibility",
         tools: tools.map((tool) => {
           let inputSchema = tool.inputSchema;
           let schemaOmitted = false;
@@ -213,7 +240,7 @@
             // schema as the draft's serialized JSON string; the current report
             // exposes an object. Normalize both without passing site prose on.
             if (typeof inputSchema === "string") inputSchema = JSON.parse(inputSchema);
-            if (JSON.stringify(inputSchema ?? {}).length > MAX_SCHEMA_CHARS) {
+            if (new TextEncoder().encode(JSON.stringify(inputSchema ?? {})).length > MAX_SCHEMA_BYTES) {
               inputSchema = undefined;
               schemaOmitted = true;
             }
@@ -229,6 +256,7 @@
               ? {
                   readOnlyHint: tool.annotations.readOnlyHint === true,
                   untrustedContentHint: tool.annotations.untrustedContentHint === true,
+                  consequentialHint: tool.annotations.consequentialHint === true,
                 }
               : undefined,
           };
@@ -236,9 +264,11 @@
       };
     },
 
-    async call(name, inputObject, timeoutMs = 30_000) {
-      const tools = await registeredTools();
-      const tool = tools.find((candidate) => candidate.name === name);
+    async call(name, inputObject, expected, timeoutMs = 30_000) {
+      if (!expected || expected.origin !== location.origin || expected.pagePath !== location.pathname || !discovery || expected.discoveryId !== discovery.id || discovery.href !== location.href || discovery.epoch !== epoch) {
+        throw domError("The page or tool inventory changed. Discover tools again before calling.", "InvalidStateError");
+      }
+      const tool = discovery.tools.find((candidate) => candidate.name === name);
       if (!tool) throw domError(`WebMCP tool ${name} is not registered`, "NotFoundError");
 
       const controller = new AbortController();
@@ -247,25 +277,16 @@
         Math.max(1_000, Math.min(Number(timeoutMs) || 30_000, 60_000)),
       );
       try {
-        let result;
-        try {
-          result = await modelContext.executeTool(tool, inputObject, {
-            signal: controller.signal,
-          });
-        } catch (error) {
-          // Chromium's early draft expected a serialized input string. Only
-          // retry the pre-execution parse failure; an arbitrary tool failure
-          // might follow a side effect and must never be executed twice.
-          if (!/failed to parse input arguments/i.test(String(error?.message || error))) throw error;
-          result = await modelContext.executeTool(tool, JSON.stringify(inputObject), {
-            signal: controller.signal,
-          });
-        }
-        const resultJson = typeof result === "string" ? result : JSON.stringify(result);
-        if (resultJson.length > MAX_RESULT_CHARS) {
+        // Never infer a protocol version from a site's error message and retry:
+        // that error may have followed a side effect.
+        const result = await modelContext.executeTool(tool, inputObject, {
+          signal: controller.signal,
+        });
+        const resultJson = (typeof result === "string" ? result : JSON.stringify(result)) ?? "null";
+        if (new TextEncoder().encode(resultJson).length > MAX_RESULT_BYTES) {
           throw new RangeError("WebMCP tool result exceeds the 64 KB bridge limit");
         }
-        return { ...source(), tool: name, resultJson };
+        return { ...source(), discoveryId: expected.discoveryId, tool: name, resultJson };
       } finally {
         clearTimeout(timer);
       }