hilos-agent 0.11.16 → 0.11.18

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.18",
   "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/config.mjs

@@ -181,8 +181,9 @@ const DEFAULTS = {
   // on timeout we post an honest "taking longer than expected" line.
   chatTimeoutMs: 90000,
   // Work queue: mentions run one at a time — parallel CLI runs on one checkout
-  // would collide on git state. queueAcks posts "queued behind the current task"
-  // when a mention lands during a run; set false to keep it quiet.
+  // would collide on git state. queueAcks posts a short receipt when a mention
+  // lands during a run (replaced by the reply once it starts, 1354); set false
+  // to keep it quiet.
   queueAcks: true,
   runTimeoutMs: 600000,
   decisionTimeoutMs: 1800000,

package/src/handler.mjs

@@ -1509,7 +1509,7 @@ function agentPreamble(workspaceMemory, cfg) {
  * (threads are where conversations live), else the channel tail. Returns the raw
  * rows (for intent routing) and a transcript string (for the prompt).
  */
-async function fetchContext({ channelId, tool, parentId }) {
+async function fetchContext({ channelId, tool, parentId, excludeIds = [] }) {
   let rows = [];
   if (parentId) {
     const t = await tool("get_thread", { parentId }).catch(() => null);
@@ -1520,6 +1520,10 @@ async function fetchContext({ channelId, tool, parentId }) {
     }));
     rows = messages;
   }
+  // 1354 — this agent's own queue receipt for THIS mention is plumbing, not
+  // conversation: read back as context it became "I'm waiting on a current
+  // task", and the model repeated it as fact.
+  if (excludeIds.length) rows = rows.filter((m) => !excludeIds.includes(m?.id));
   // 0779: the rows carry resolved `attachments`, and the body carries the
   // unresolvable `![name](attachment:<uuid>)` pill token. Flatten the token and
   // name the file, so the daemon's chat replies and routing decisions stop
@@ -1617,7 +1621,8 @@ async function respondConversationally({
   pathExistsFn = existsSync,
 }) {
   const implicitDm = message?.implicit === "dm";
-  const { transcript } = context || (await fetchContext({ channelId, tool, parentId }));
+  const { transcript } =
+    context || (await fetchContext({ channelId, tool, parentId, excludeIds: contextExclusions(message) }));
   // 1249 — the room can ask agents to answer in a thread instead of in the
   // room. The server owns the setting and marks the mention; the daemon only
   // has to post under the message it names. Other mentions retain their
@@ -1685,7 +1690,13 @@ async function respondConversationally({
   // If the reply is slow, post ONE "still thinking…" ping and then edit it into
   // the answer (single message, no dead air). Needs edit_message; otherwise we
   // just post the reply when it's ready. A fast reply never trips the timer.
-  let thinkingId = null;
+  // 1354 — a mention that waited in the queue already has such a line: the
+  // queue receipt, posted where the reply goes. Reuse it, so the reply lands
+  // in place of "picking this up now" instead of under it.
+  let thinkingId =
+    testCapabilities.editMessage && message?.queueAckId && replyParentId === (parentId ?? null)
+      ? message.queueAckId
+      : null;
   let beatStopped = false;
   let beatBusy = false;
   const beatMs = Math.min(cfg.chatTimeoutMs || 90000, 30000);
@@ -1768,6 +1779,11 @@ async function respondConversationally({
   await deliver(body);
 }
 
+/** Rows a mention's context must not carry: its own queue receipt (1354). */
+function contextExclusions(message) {
+  return message?.queueAckId ? [message.queueAckId] : [];
+}
+
 /** True when this mention is a request for THIS agent to review a PR (0286/0288). */
 export function isReviewRequest(message) {
   return (
@@ -2779,7 +2795,7 @@ export async function handleTask({ message, channelId, tool, me, testCapabilitie
   // route AND (for a code run) handed to the coding prompt. Context is always
   // crucial: a reply like "yeah, do it" only means something against what was
   // just said.
-  const context = await fetchContext({ channelId, tool, parentId });
+  const context = await fetchContext({ channelId, tool, parentId, excludeIds: contextExclusions(message) });
   const mode = agentMode(message);
 
   // REVIEW EXECUTION (0288): a review-request routes to the read-only reviewer

package/src/run.mjs

@@ -24,6 +24,11 @@ import {
 
 const MAX_IMMEDIATE_SEQUENCE_PAGES = 8;
 
+/** The queue receipt a mention gets while another job runs (1354). */
+export const QUEUE_ACK_BODY = "Got it — I'll pick this up as soon as I finish what I'm on.";
+/** What that receipt becomes the moment its job starts (1354). */
+export const QUEUE_ACK_STARTED_BODY = "Picking this up now.";
+
 // 1290: the hilos.sh contract. Missing-tool paths exist only for injected tests;
 // tools/list remains the token's prompt inventory and the recall scope check.
 const HILOS_DAEMON_TOOLS = Object.freeze({
@@ -519,6 +524,15 @@ export async function run(
     const withImages = images.files.length
       ? { ...message, imageDir: images.dir, images: images.files }
       : message;
+    // 1354 — retire the queue receipt as the job starts. The chat path then
+    // edits this same message into the reply (one line, in place); a code
+    // run leaves it as this truthful "starting" line under its own cards.
+    if (message.queueAckId && testCapabilities.editMessage) {
+      await taskTool("edit_message", {
+        messageId: message.queueAckId,
+        body: QUEUE_ACK_STARTED_BODY,
+      }).catch(() => {});
+    }
     // 0782 — a person pressed Stop on this run's live card. The server already
     // settled the run row (status canceled); this end says so in the room and
     // tears the work down through the SAME cancel path a chat "stop" uses, so a
@@ -660,11 +674,20 @@ export async function run(
     // agent, so "Got it — queued" over a line that may deserve no reply at all
     // is exactly the noise the implicit lane promises not to make.
     if (liveCfg.queueAcks && !r.startedImmediately && !m.deployRequest && !m.implicit) {
-      await tool("post_message", {
+      // 1354 — the ack is a queue receipt, not a status. It used to read
+      // "queued behind the current task", and every model in the room (this
+      // agent's own included, since the ack sits in its transcript) took the
+      // "current task" literally: Ada told Hilo she was "waiting for current
+      // task to clear" for an hour over a queue that had drained in seconds,
+      // and the work never started. The receipt now says what is true, its id
+      // rides on the job, and safeHandle replaces it the moment the job
+      // starts, so nothing stale is left for anyone to reason about.
+      const ack = await tool("post_message", {
         channelId,
         parentId: m.parentId ?? null,
-        body: "Got it — queued behind the current task.",
-      }).catch(() => {});
+        body: QUEUE_ACK_BODY,
+      }).catch(() => null);
+      if (ack?.messageId) m.queueAckId = ack.messageId;
     }
     return { accepted: true, settled: false };
   }
@@ -837,7 +860,7 @@ export async function run(
         await tool("post_message", {
           channelId: bridge.binding.channelId,
           parentId: bridge.binding.threadRootId,
-          body: "Got it — this will continue in the same local session after the current task.",
+          body: "Got it — this continues in the same local session as soon as I finish what I'm on.",
         }).catch(() => {});
       }
     }

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);
       }