hilos-agent 0.11.3 → 0.11.4

package/README.md

@@ -392,12 +392,23 @@ npx hilos-agent@latest hooks print
   `hilos-agent` is running. Ambient messages, older thread history, and agent
   replies do not wake it. Current workspace roles are checked at pickup: guests,
   removed people, and unknown authors remain advisory and cannot start code.
+- Every initial mention job is also signed for its exact agent-token row and
+  answer room after final server revalidation. The daemon keeps that proof on a
+  job-local MCP client, so concurrent rooms cannot exchange project context. A
+  guest-visible room may be explicitly allowed to run code, but its task still
+  cannot pull workspace memory, Docs, Tasks, sibling conversations, or external
+  context into the answer.
 - The resumed turn receives bounded thread, room, and member context. Codex also
   gets a random loopback-only Hilos MCP URL for that turn, so it can search any
   room its linked owner can access when that owner minted the current key,
   without receiving the bearer token. Regenerate an older key from Connect to
   enable that inheritance. Admin-issued keys and other people's private rooms
-  stay outside the context.
+  stay outside the context. Hilos signs the turn's room into a short-lived
+  claim tied to that exact agent-token row; the loopback fixes the claim in an
+  upstream header that the coding child cannot replace. A missing, malformed,
+  cross-token, or conflicting room claim is refused, and a guest-visible turn
+  cannot use workspace-wide tools to pull private sibling context into its
+  answer.
 - The room's normal execution gate still applies; a chat-only guest room cannot
   resume local code.
 - Steps are coalesced into ~2s batches to keep traffic light.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hilos-agent",
-  "version": "0.11.3",
+  "version": "0.11.4",
   "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": {

package/src/mcp-loopback.mjs

@@ -28,6 +28,22 @@ const FORWARDED_REQUEST_HEADERS = [
 ];
 const MAX_HEADER_LENGTH = 4096;
 
+/** A v2 claim is the only format the server may use as ambient authority. This
+ * local shape check is not verification — the upstream server still checks the
+ * HMAC and exact token id — but it keeps 48-hour v1 state from advertising a
+ * loopback whose every call would be rejected after the rollout. */
+export function isV2AmbientBindingClaim(claim) {
+  if (typeof claim !== "string" || !claim || claim.length > MAX_HEADER_LENGTH) return false;
+  const [payload, signature, extra] = claim.split(".");
+  if (!payload || !signature || extra) return false;
+  try {
+    const parsed = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+    return parsed?.v === 2 && typeof parsed?.tokenId === "string" && Boolean(parsed.tokenId);
+  } catch {
+    return false;
+  }
+}
+
 function readBody(request) {
   return new Promise((resolve, reject) => {
     let size = 0;
@@ -52,21 +68,19 @@ function readBody(request) {
  * @param {{
  *   url?: string,
  *   token?: string,
- *   channelId?: string,
+ *   bindingClaim?: string,
  *   fetchImpl?: typeof fetch,
  * }} [options]
  * @returns {Promise<{url: string, close: () => Promise<void>} | null>}
  */
-export async function startHilosMcpLoopback({ url, token, channelId = "", fetchImpl = fetch } = {}) {
-  if (!url || !token) return null;
+export async function startHilosMcpLoopback({ url, token, bindingClaim = "", fetchImpl = fetch } = {}) {
+  const ambientBinding = typeof bindingClaim === "string" ? bindingClaim.trim() : "";
+  // A continuation without its server-signed binding must not get a workspace
+  // MCP bridge whose guest-sensitive reads have no authoritative room context.
+  if (!url || !token || !isV2AmbientBindingClaim(ambientBinding)) return null;
   const nonce = randomBytes(24).toString("hex");
   const path = `/mcp/${nonce}`;
   const upstream = new URL(url);
-  // Preserve the room that caused this turn as MCP's effective context. This
-  // does not widen or narrow token access, but it keeps guest-room memory gates
-  // and other context-sensitive server policy active even when the model calls
-  // a workspace-scoped tool without a channelId argument.
-  if (channelId) upstream.searchParams.set("channelId", channelId);
   const upstreamRequests = new Set();
 
   const server = createServer(async (request, response) => {
@@ -83,6 +97,9 @@ export async function startHilosMcpLoopback({ url, token, channelId = "", fetchI
       const body = request.method === "POST" ? await readBody(request) : undefined;
       const headers = {
         authorization: `Bearer ${token}`,
+        // 1215 — fixed daemon-owned authority. This header is intentionally not
+        // in FORWARDED_REQUEST_HEADERS, so a coding child cannot replace it.
+        "x-hilos-ambient-binding": ambientBinding,
         // This short-lived proxy is part of the persistent daemon's return
         // path. Marking it on-demand would temporarily relabel a live daemon
         // and could suppress the offline/wakeup behavior after the turn.

package/src/mcp.mjs

@@ -11,6 +11,7 @@ const META_CLIENT_INFO = "io.modelcontextprotocol/clientInfo";
 const DEFAULT_TIMEOUT_MS = 35_000;
 const DISCOVERY_TIMEOUT_MS = 10_000;
 const RETRY_DELAY_MS = 250;
+const MAX_AMBIENT_BINDING_LENGTH = 4_096;
 
 function installedVersion() {
   try {
@@ -51,6 +52,13 @@ export class McpAuthStopError extends McpRequestError {
   }
 }
 
+export class McpAmbientBindingError extends McpRequestError {
+  constructor(message, details = {}) {
+    super(message, { ...details, ambientBindingRejected: true });
+    this.name = "McpAmbientBindingError";
+  }
+}
+
 function headerValue(value) {
   const text = String(value);
   return /^[\x20-\x7e]+$/.test(text)
@@ -233,6 +241,9 @@ export function makeClient({
       authorization: `Bearer ${token}`,
       "x-hilos-connection-mode": "daemon",
       ...(DAEMON_CLIENT ? { "x-hilos-client": DAEMON_CLIENT } : {}),
+      ...(options.ambientBinding
+        ? { "x-hilos-ambient-binding": options.ambientBinding }
+        : {}),
       ...(modern
         ? {
             "mcp-protocol-version": MCP_PROTOCOL_VERSION,
@@ -256,9 +267,23 @@ export function makeClient({
     let res;
     let json = null;
     let transportError = null;
+    let requestUrl = url;
+    if (options.ambientChannelId) {
+      try {
+        const scopedUrl = new URL(url);
+        scopedUrl.searchParams.set("channelId", options.ambientChannelId);
+        requestUrl = scopedUrl.toString();
+      } catch (error) {
+        bounded.cleanup();
+        throw new McpRequestError("hilos has an invalid MCP URL", {
+          cause: error,
+          malformedResponse: true,
+        });
+      }
+    }
     try {
       try {
-        res = await fetchImpl(url, {
+        res = await fetchImpl(requestUrl, {
           method: "POST",
           headers,
           body: JSON.stringify({ jsonrpc: "2.0", id: requestId, method, params: requestParams }),
@@ -347,7 +372,7 @@ export function makeClient({
     for (let attempt = 0; attempt < 2; attempt += 1) {
       try {
         const result = await request("server/discover", undefined, {
-          signal: options.signal,
+          ...options,
           timeoutMs: Math.min(timeoutMs, DISCOVERY_TIMEOUT_MS),
           protocolVersion: MCP_PROTOCOL_VERSION,
         });
@@ -411,6 +436,49 @@ export function makeClient({
     }
   }
 
+  /**
+   * Pin every call made by one queued daemon job to the room claim returned
+   * with that job. This is a closure, not mutable client state: concurrent
+   * work from different rooms can never overwrite or inherit another job's
+   * ambient privacy boundary.
+   */
+  function bindTool(bindingClaim, channelId) {
+    const bindingClaimAbsent = bindingClaim === undefined;
+    const ambientBinding =
+      typeof bindingClaim === "string" ? bindingClaim.trim() : "";
+    const ambientChannelId = typeof channelId === "string" ? channelId.trim() : "";
+    return async (name, args = {}, options = {}) => {
+      if (
+        !ambientChannelId ||
+        (!bindingClaimAbsent &&
+          (!ambientBinding || ambientBinding.length > MAX_AMBIENT_BINDING_LENGTH))
+      ) {
+        throw new McpAmbientBindingError("hilos returned an invalid ambient room binding", {
+          malformedResponse: true,
+        });
+      }
+      try {
+        return await tool(name, args, {
+          ...options,
+          ambientChannelId,
+          ...(ambientBinding ? { ambientBinding } : {}),
+        });
+      } catch (error) {
+        // A scoped 401 without the terminal-token bit means the bearer token
+        // still exists but this queued job's room proof was rejected (expired,
+        // rotated, or mismatched). Surface a distinct failure so the daemon can
+        // restart from its durable cursor instead of acknowledging lost work.
+        if (error?.status === 401 && error?.stop !== true) {
+          throw new McpAmbientBindingError(error.message, {
+            ...error,
+            cause: error,
+          });
+        }
+        throw error;
+      }
+    };
+  }
+
   // Full tool objects, schemas included. Never turn discovery errors into an
   // empty registry: that would silently downgrade a current daemon until its
   // next restart. One bounded retry handles a transient read failure.
@@ -440,5 +508,12 @@ export function makeClient({
     return (await listTools(options)).map((tool) => tool.name);
   }
 
-  return { rpc, tool, listTools, listToolNames, stopSignal: stopController.signal };
+  return {
+    rpc,
+    tool,
+    bindTool,
+    listTools,
+    listToolNames,
+    stopSignal: stopController.signal,
+  };
 }

package/src/reply-bridge.mjs

@@ -17,7 +17,10 @@ import { makeStreamParser } from "./agent-events.mjs";
 import { detectVendor, codeStreamArgs, createProgressEmitter } from "./progress-emitter.mjs";
 import { buildResumeArgs } from "./resume.mjs";
 import { commandArgv } from "./argv.mjs";
-import { startHilosMcpLoopback } from "./mcp-loopback.mjs";
+import {
+  isV2AmbientBindingClaim,
+  startHilosMcpLoopback,
+} from "./mcp-loopback.mjs";
 import {
   HOOK_STATE_DIR,
   hookConnectionKey,
@@ -255,11 +258,15 @@ function matchingSessions(sessions, { connectionKey = "" } = {}) {
   );
 }
 
-/** Persist a one-way credential scope only after the real hilos server accepts
- * the hook's signed binding claim. Re-read after the best-effort write so an IO
- * failure stays fail-closed. */
-function claimVerifiedSession(binding, connectionKey, stateDir) {
-  if (!binding?.sessionId || !binding?.bindingClaim || !connectionKey) return false;
+/** Persist a freshly server-verified v2 claim, optionally claiming a tokenless
+ * hook session for this credential at the same time. Re-read after the write so
+ * an IO failure or concurrent replacement stays fail-closed. */
+function persistVerifiedBinding(binding, nextClaim, stateDir, connectionKey = "") {
+  if (
+    !binding?.sessionId ||
+    !binding?.bindingClaim ||
+    !isV2AmbientBindingClaim(nextClaim)
+  ) return false;
   const state = readState(binding.sessionId, stateDir);
   if (!state || (state.connectionKey && state.connectionKey !== connectionKey)) return false;
   const current = (Array.isArray(state.bindings) ? state.bindings : []).find(
@@ -270,9 +277,27 @@ function claimVerifiedSession(binding, connectionKey, stateDir) {
       item?.agentId === binding.agentId,
   );
   if (!current) return false;
-  state.connectionKey = connectionKey;
+  current.bindingClaim = nextClaim;
+  if (connectionKey) state.connectionKey = connectionKey;
   writeState(binding.sessionId, state, stateDir);
-  return readState(binding.sessionId, stateDir)?.connectionKey === connectionKey;
+  const saved = readState(binding.sessionId, stateDir);
+  const savedBinding = saved?.bindings?.find(
+    (item) =>
+      item?.threadRootId === binding.threadRootId &&
+      item?.anchorMessageId === binding.anchorMessageId &&
+      item?.agentId === binding.agentId,
+  );
+  return savedBinding?.bindingClaim === nextClaim &&
+    (!connectionKey || saved?.connectionKey === connectionKey);
+}
+
+function bindingVerificationArgs(binding) {
+  return {
+    claim: binding.bindingClaim,
+    channelId: binding.channelId,
+    threadRootId: binding.threadRootId,
+    messageId: binding.anchorMessageId,
+  };
 }
 
 async function verifyBindingAuthority(binding, authority, tool, stateDir) {
@@ -284,14 +309,14 @@ async function verifyBindingAuthority(binding, authority, tool, stateDir) {
     !authority.agentId ||
     binding.agentId !== authority.agentId
   ) return false;
-  const verified = await tool("verify_session_binding", {
-    claim: binding.bindingClaim,
-    channelId: binding.channelId,
-    threadRootId: binding.threadRootId,
-    messageId: binding.anchorMessageId,
-  });
+  const verified = await tool("verify_session_binding", bindingVerificationArgs(binding));
   return verified?.valid === true &&
-    claimVerifiedSession(binding, authority.connectionKey, stateDir);
+    persistVerifiedBinding(
+      binding,
+      verified.bindingClaim,
+      stateDir,
+      authority.connectionKey,
+    );
 }
 
 function clearPendingDelivery(sessionId, deliveryId, stateDir = HOOK_STATE_DIR) {
@@ -675,12 +700,21 @@ function vendorLabel(vendor) {
  *   now?: () => number,
  *   log?: { log: (...args: any[]) => void },
  *   signal?: AbortSignal,
+ *   startLoopback?: typeof startHilosMcpLoopback,
  * }} deps
  */
 export async function handleReplyBridgeJob(
   { binding, replies: queuedReplies, context },
   cfg,
-  { tool, run = runCli, stateDir = HOOK_STATE_DIR, now = Date.now, log = console, signal },
+  {
+    tool,
+    run = runCli,
+    stateDir = HOOK_STATE_DIR,
+    now = Date.now,
+    log = console,
+    signal,
+    startLoopback = startHilosMcpLoopback,
+  },
 ) {
   // A second batch may have queued while the first continuation was running.
   // Re-read the durable processed set at execution time so the overlap is
@@ -692,7 +726,13 @@ export async function handleReplyBridgeJob(
   const processed = new Set(
     Array.isArray(currentBinding?.processedReplyIds) ? currentBinding.processedReplyIds : [],
   );
-  const liveBinding = currentBinding ? { ...binding, ...currentBinding } : binding;
+  const liveBinding = {
+    ...binding,
+    ...(currentBinding ?? {}),
+    // scanReplyBridge may have just claimed a tokenless hook session by writing
+    // the top-level key; carry that fresh authority into this already-built job.
+    connectionKey: currentState?.connectionKey || binding.connectionKey || "",
+  };
   const queuedIds = new Set(
     (queuedReplies || []).map((reply) => reply?.id).filter((id) => id && !processed.has(id)),
   );
@@ -733,11 +773,31 @@ export async function handleReplyBridgeJob(
     return { status: "skipped" };
   }
 
-  const loopback = liveBinding.vendor === "codex"
-    ? await startHilosMcpLoopback({
+  // Verify and rotate the claim against the current server immediately before
+  // exposing MCP. This upgrades persisted v1 state, prevents a new daemon from
+  // trusting an older server, and keeps active bindings ahead of the 48-hour
+  // claim expiry that successful continuations also renew locally.
+  const ambientVerification =
+    liveBinding.vendor === "codex" && liveBinding.bindingClaim
+      ? await tool("verify_session_binding", bindingVerificationArgs(liveBinding))
+          .catch(() => null)
+      : null;
+  const refreshedAmbientClaim =
+    ambientVerification?.valid === true &&
+    isV2AmbientBindingClaim(ambientVerification.bindingClaim) &&
+    persistVerifiedBinding(
+      liveBinding,
+      ambientVerification.bindingClaim,
+      stateDir,
+      liveBinding.connectionKey,
+    )
+      ? ambientVerification.bindingClaim
+      : "";
+  const loopback = refreshedAmbientClaim
+    ? await startLoopback({
         url: cfg?.url,
         token: cfg?.token,
-        channelId: liveBinding.channelId,
+        bindingClaim: refreshedAmbientClaim,
       }).catch(() => null)
     : null;
   const prompt = bridgePrompt(replies, context, { hilosMcp: Boolean(loopback) });

package/src/run.mjs

@@ -104,6 +104,9 @@ export async function run(
   // Match the typed client error by its stable cross-realm name. This also
   // works for embedding hosts and test doubles that do not share a constructor.
   const isAuthStop = (error) => error?.name === "McpAuthStopError";
+  const isAmbientBindingRejection = (error) =>
+    error?.name === "McpAmbientBindingError" ||
+    error?.ambientBindingRejected === true;
   const reportAuthStop = (error) => {
     if (!isAuthStop(error)) return false;
     emitStopping();
@@ -113,7 +116,7 @@ export async function run(
   const client = makeClient({ url: cfg.url, token: cfg.token });
   // Keep injected/older test clients compatible; the real makeClient always
   // provides this lifecycle signal and terminal auth still latches through it.
-  const { tool, listTools, listToolNames } = client;
+  const { tool, bindTool, listTools, listToolNames } = client;
   const stopSignal = client.stopSignal ?? new AbortController().signal;
   const abortFromAuthStop = () => runController.abort(stopSignal.reason);
   stopSignal.addEventListener("abort", abortFromAuthStop, { once: true });
@@ -145,6 +148,7 @@ export async function run(
   let iterateClaimRecoveryStore = null;
   let queue = null;
   let wake = null;
+  let fatalJobError = null;
   let reconcileClaimsOnce = async () => true;
   const withinShutdownReconcileBound = async (promise) => {
     let timer;
@@ -522,6 +526,10 @@ export async function run(
 
   async function safeHandle(message, channelId, jobSignal) {
     emit({ type: "task-start", channelId, messageId: message.id, text: (message.body || "").slice(0, 200) });
+    const taskTool =
+      typeof bindTool === "function"
+        ? bindTool(message.bindingClaim, channelId)
+        : tool;
     // 0779 — pull this mention's images to disk HERE, as the job starts, not
     // when it was enqueued. Downloading at enqueue meant a burst of image
     // mentions held every job's bytes (up to 4 x 10MB each) on the user's disk
@@ -548,7 +556,7 @@ export async function run(
       if (stopNoticed) return;
       stopNoticed = true;
       const who = typeof by === "string" && by.trim() ? by.trim() : null;
-      void tool("post_message", {
+      void taskTool("post_message", {
         channelId,
         parentId: message.parentId ?? null,
         body: who ? `Stopped by ${who} from the room.` : "Stopped from the room.",
@@ -559,7 +567,14 @@ export async function run(
       log.log(`→ task in ${channelId}: "${(message.body || "").slice(0, 80)}"`);
       // liveCfg so a job uses the latest model/permission/codingCmd at run time.
       const result = await handler(
-        { message: withImages, channelId, tool, me, caps, iterateClaimRecoveryStore },
+        {
+          message: withImages,
+          channelId,
+          tool: taskTool,
+          me,
+          caps,
+          iterateClaimRecoveryStore,
+        },
         liveCfg,
         undefined,
         { signal: jobSignal, onStopRequested },
@@ -568,7 +583,18 @@ export async function run(
     } catch (e) {
       emit({ type: "task-error", channelId, error: e?.message || String(e) });
       log.error(`handler error: ${e.message}`);
-      await tool("post_message", {
+      if (isAmbientBindingRejection(e)) {
+        // The job's room proof is no longer usable. Close intake synchronously
+        // before runJob unwinds so createQueue skips afterJob (and therefore
+        // cannot persist this mention's cursor), then restart from the durable
+        // cursor. Posting with the same rejected proof would only hide the
+        // failure behind a second 401.
+        fatalJobError ??= e;
+        runController.abort(e);
+        void queue.shutdown("ambient room binding rejected");
+        throw e;
+      }
+      await taskTool("post_message", {
         channelId,
         body: `Hit an error working on that: ${e.message}`,
       }).catch(() => {});
@@ -877,6 +903,8 @@ export async function run(
     await interruptibleSleep(pollAgainMs != null ? Math.min(base, pollAgainMs) : base);
   } while (!runSignal.aborted);
 
+  if (fatalJobError) throw fatalJobError;
+
   // A terminal response may first surface inside a concurrently running
   // handler while the poll loop is sleeping. The client latch aborts the run
   // immediately; preserve the original typed error after the loop has fenced