hilos-agent 0.9.1 → 0.9.3

package/src/run.mjs

@@ -10,6 +10,7 @@ import { handleTask } from "./handler.mjs";
 import { createQueue, looksLikeCancel, dedupeKey } from "./queue.mjs";
 import { cleanupImages, fetchMentionImages } from "./attachments.mjs";
 import { reloadConfig } from "./config.mjs";
+import { startWake, createWakeGate } from "./wake.mjs";
 import { scanReplyBridge, handleReplyBridgeJob } from "./reply-bridge.mjs";
 
 /**
@@ -44,21 +45,13 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
       /* a bad event listener must never break the daemon */
     }
   };
-  // A sleep that resolves immediately when the signal aborts, so "stop" doesn't
-  // wait out the whole poll interval.
-  const interruptibleSleep = (ms) =>
-    new Promise((resolve) => {
-      if (signal?.aborted) return resolve();
-      const timer = setTimeout(() => {
-        signal?.removeEventListener?.("abort", onAbort);
-        resolve();
-      }, ms);
-      function onAbort() {
-        clearTimeout(timer);
-        resolve();
-      }
-      signal?.addEventListener?.("abort", onAbort, { once: true });
-    });
+  // The wake doorbell (0824): a Realtime ping resolves the pending inter-poll
+  // sleep so the next list_mentions poll happens NOW. A ping that lands while a
+  // poll is still running is remembered, so the following sleep returns
+  // immediately instead of the ping being lost to the race. That race lives in
+  // createWakeGate (wake.mjs) so it can be unit-tested; the sleep it hands back
+  // also resolves on abort, so "stop" never waits out the poll interval.
+  const { ping: onWakePing, sleep: interruptibleSleep } = createWakeGate({ signal });
 
   // Already asked to stop before we even connect → return cleanly, do nothing.
   if (signal?.aborted) {
@@ -115,8 +108,45 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
     // server has to offer the tool, and the operator has to have turned
     // `uploadTranscripts` on. Older servers simply never see the call.
     uploadTranscript: toolNames.includes("upload_run_transcript"),
+    // Emoji reactions (0860): the lightest answer to an untagged DM message
+    // that needs no words. Absent on older servers → the agent stays quiet
+    // instead, exactly as if it had no hand to wave.
+    react: toolNames.includes("add_reaction"),
   };
 
+  // The wake doorbell (0824): capability-checked like every optional surface.
+  // On an older server the tool is absent and the daemon polls exactly as
+  // before; with it, a new message in the workspace rings a content-free
+  // Realtime broadcast that cuts mention pickup from pollMs to instant.
+  let wake = null;
+  if (toolNames.includes("get_wake_channel")) {
+    try {
+      const chan = await tool("get_wake_channel");
+      if (chan?.url && chan?.topic) {
+        // Pass a RESOLVER, not the fetched value: wake.mjs re-asks on every
+        // reconnect and on a slow refresh timer, so if the workspace rotates
+        // its doorbell topic (rotate_wake_topic, after a leak) this daemon
+        // picks the new one up on its own instead of going quietly deaf until
+        // someone restarts it. First call reuses what we already have.
+        let first = chan;
+        wake = startWake(
+          async () => {
+            if (first) {
+              const f = first;
+              first = null;
+              return f;
+            }
+            return await tool("get_wake_channel");
+          },
+          { onWake: onWakePing, log },
+        );
+        log.log("wake: realtime doorbell enabled (polling stays as fallback)");
+      }
+    } catch (e) {
+      log.log(`wake: unavailable (${e.message}) — polling only`);
+    }
+  }
+
   // Register local folders (0324/0325): a folder-mode daemon announces each
   // channel→folder mapping to the server so the channel shows a folder chip
   // without any manual step. Capability-gated on the server advertising
@@ -161,6 +191,10 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
 
   const seen = new Set();
   const cursor = { value: since ? new Date(since).toISOString() : null };
+  // 0860 — a DM message inside its settle window: the server withheld it and
+  // said when it matures. One shortened sleep picks it up right then, instead
+  // of the person waiting out the full poll interval mid-conversation.
+  let pollAgainMs = null;
 
   // Live config: re-read between polls so model/permission/codingCmd edits to
   // hilos-agent.json take effect without a restart. Identity stays pinned.
@@ -297,7 +331,10 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
     // A report-card deploy decision is already visible in place. list_mentions
     // projects the pending decision into this structured event, so don't add a
     // misleading "queued" chat line while the active run settles it.
-    if (liveCfg.queueAcks && !r.startedImmediately && !m.deployRequest) {
+    // An untagged DM message (0860) skips the ack too: nobody summoned the
+    // 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", {
         channelId,
         parentId: m.parentId ?? null,
@@ -312,6 +349,11 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
       ...(cfg.channelId ? { channelId: cfg.channelId } : {}),
     };
     const out = await tool("list_mentions", mentionArgs);
+    // Floor the server's settle hint so a clock skew can never hot-loop the poll.
+    pollAgainMs =
+      typeof out?.retryAfterMs === "number" && out.retryAfterMs > 0
+        ? Math.max(500, out.retryAfterMs)
+        : null;
     const mentions = (out?.mentions ?? []).slice().reverse();
     for (const m of mentions) {
       if (seen.has(m.id)) continue;
@@ -404,13 +446,17 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
     }
     if (signal?.aborted) break;
     // Interruptible so an abort during the sleep returns promptly instead of
-    // waiting out the full poll interval.
-    await interruptibleSleep(liveCfg.pollMs);
+    // waiting out the full poll interval. A settling DM (0860) shortens one
+    // sleep to the server's hint; the doorbell still cuts either short.
+    await interruptibleSleep(
+      pollAgainMs != null ? Math.min(liveCfg.pollMs, pollAgainMs) : liveCfg.pollMs,
+    );
   } while (!signal?.aborted);
 
-  // Clean stop: make sure any active job is cancelled (the abort listener already
-  // fired for the common case, but this covers a break for other reasons) and let
-  // in-flight teardown settle before returning.
+  // Clean stop: close the doorbell socket, make sure any active job is cancelled
+  // (the abort listener already fired for the common case, but this covers a
+  // break for other reasons) and let in-flight teardown settle before returning.
+  wake?.stop();
   if (signal?.aborted) {
     queue.cancelActive("run() aborted");
   }

package/src/wake.mjs

@@ -0,0 +1,288 @@
+// The Realtime wake doorbell (0824). Subscribes to the workspace's broadcast
+// topic (from the get_wake_channel tool) so a new message wakes the poll loop
+// instantly instead of waiting out pollMs. Dependency-free by design, like
+// mcp.mjs: this speaks the small slice of the Supabase Realtime (Phoenix)
+// protocol the doorbell needs over the global WebSocket (Node >= 22).
+//
+// What the credentials here are worth, so nobody mistakes one for the other:
+//   * `anonKey` is the project's PUBLIC key — the same string every page of the
+//     web app ships in its bundle. It grants nothing on its own: every table a
+//     daemon cares about is RLS-gated and the anon role has no membership, so
+//     it reads zero rows (asserted in scripts/verify-agent-wake.mjs).
+//   * `topic` is the actual secret. The broadcast is public (private=false), so
+//     the topic string is what gates the doorbell. All it buys is one repeated
+//     bit — "a message was posted somewhere in this workspace" — never content.
+//     If it leaks, an owner rotates it (rotate_wake_topic) and this client
+//     re-resolves on its own; see the `source` resolver below.
+//
+// Fail-soft everywhere: the doorbell is an accelerator, never a dependency.
+// No WebSocket global, a bad URL, a rejected join, a dropped socket — all of it
+// degrades to exactly the polling behavior the daemon has always had.
+
+const HEARTBEAT_MS = 25_000;
+const RECONNECT_MIN_MS = 1_000;
+const RECONNECT_MAX_MS = 60_000;
+// A join that never gets its ok reply is a dead doorbell that LOOKS alive.
+// Give it a bounded window, then recycle the socket.
+const JOIN_TIMEOUT_MS = 15_000;
+// How often to re-ask the server for the topic when it did not tell us. Bounds
+// how long a rotated topic can leave a daemon on plain polling.
+const DEFAULT_REFRESH_MS = 15 * 60_000;
+
+/**
+ * Open (and keep open) the doorbell subscription.
+ *
+ * @param {{ url: string, anonKey: string, topic: string, refreshMs?: number }
+ *        | (() => Promise<{ url: string, anonKey: string, topic: string, refreshMs?: number }>)} source
+ *   Either a fixed get_wake_channel result, or an async resolver that fetches a
+ *   fresh one. Pass the resolver: it is re-run on every reconnect and on a slow
+ *   refresh timer, which is what makes a topic rotation heal itself instead of
+ *   silently dropping the daemon back to pollMs until someone restarts it.
+ * @param {{ onWake: () => void, log?: { log: Function, error: Function } }} opts
+ * @returns {{ stop: () => void }}
+ */
+export function startWake(source, { onWake, log = console }) {
+  const WS = globalThis.WebSocket;
+  if (typeof WS !== "function") {
+    log.log("wake: no WebSocket in this Node (need >= 22) — staying on polling only");
+    return { stop() {} };
+  }
+  const resolve =
+    typeof source === "function" ? source : async () => source;
+
+  let ws = null;
+  let stopped = false;
+  let heartbeat = null;
+  let joinTimer = null;
+  let reconnectTimer = null;
+  let refreshTimer = null;
+  let backoff = RECONNECT_MIN_MS;
+  let ref = 0;
+  let phxTopic = null;
+  let currentTopic = null;
+  let refreshMs = DEFAULT_REFRESH_MS;
+  let refreshArmed = false;
+
+  const send = (msg) => {
+    try {
+      if (ws?.readyState === WS.OPEN) ws.send(JSON.stringify(msg));
+    } catch {
+      /* a failed frame is the socket's problem; close/error handles it */
+    }
+  };
+
+  const teardown = () => {
+    if (heartbeat) clearInterval(heartbeat);
+    heartbeat = null;
+    if (joinTimer) clearTimeout(joinTimer);
+    joinTimer = null;
+    if (ws) {
+      ws.onopen = ws.onmessage = ws.onclose = ws.onerror = null;
+      try {
+        ws.close();
+      } catch {
+        /* already gone */
+      }
+      ws = null;
+    }
+  };
+
+  const scheduleReconnect = () => {
+    if (stopped || reconnectTimer) return;
+    reconnectTimer = setTimeout(() => {
+      reconnectTimer = null;
+      connect();
+    }, backoff);
+    // Capped, and only ever grows between successful joins — an endpoint that
+    // is down costs one attempt a minute, not a hot retry loop.
+    backoff = Math.min(backoff * 2, RECONNECT_MAX_MS);
+  };
+
+  // Recycle the socket: used for a rejected join, a join that never answered,
+  // and a server-side channel error. Each one leaves a socket that would
+  // otherwise sit there open and permanently deaf.
+  const recycle = (why) => {
+    if (stopped) return;
+    log.log(`wake: ${why} — retrying, polling continues`);
+    teardown();
+    scheduleReconnect();
+  };
+
+  async function connect() {
+    if (stopped) return;
+    teardown();
+
+    // Re-resolved every attempt, so a rotated topic is picked up here.
+    let chan;
+    try {
+      chan = await resolve();
+    } catch (e) {
+      log.error(`wake: could not get the doorbell topic (${e?.message || e}) — polling continues`);
+      return scheduleReconnect();
+    }
+    if (stopped) return;
+    if (!chan?.url || !chan?.anonKey || !chan?.topic) return scheduleReconnect();
+    if (Number.isFinite(chan.refreshMs) && chan.refreshMs > 0) refreshMs = chan.refreshMs;
+    currentTopic = chan.topic;
+    // Armed here, not at startup, so the FIRST interval already uses the
+    // server's refreshMs instead of the built-in default.
+    if (!refreshArmed) {
+      refreshArmed = true;
+      scheduleRefresh();
+    }
+
+    const wsUrl =
+      chan.url.replace(/^http/, "ws").replace(/\/$/, "") +
+      "/realtime/v1/websocket?apikey=" +
+      encodeURIComponent(chan.anonKey) +
+      "&vsn=1.0.0";
+    phxTopic = "realtime:" + chan.topic;
+
+    let sock;
+    try {
+      sock = new WS(wsUrl);
+    } catch (e) {
+      log.error(`wake: connect failed (${e.message}) — polling continues`);
+      return scheduleReconnect();
+    }
+    ws = sock;
+
+    sock.onopen = () => {
+      send({
+        topic: phxTopic,
+        event: "phx_join",
+        payload: {
+          config: { broadcast: { self: false, ack: false }, presence: { key: "" }, private: false },
+          access_token: chan.anonKey,
+        },
+        ref: String(++ref),
+      });
+      joinTimer = setTimeout(() => recycle("join timed out"), JOIN_TIMEOUT_MS);
+      heartbeat = setInterval(() => {
+        send({ topic: "phoenix", event: "heartbeat", payload: {}, ref: String(++ref) });
+      }, HEARTBEAT_MS);
+    };
+
+    sock.onmessage = (evt) => {
+      let msg;
+      try {
+        msg = JSON.parse(String(evt.data));
+      } catch {
+        return;
+      }
+      if (msg.topic !== phxTopic) return;
+      if (msg.event === "phx_reply") {
+        if (joinTimer) clearTimeout(joinTimer);
+        joinTimer = null;
+        if (msg.payload?.status === "ok") {
+          // Joined: the doorbell is live. Reset the backoff so a later drop
+          // recovers quickly.
+          backoff = RECONNECT_MIN_MS;
+          return;
+        }
+        // A rejected join used to leave the socket open and silent forever.
+        return recycle(`join refused (${msg.payload?.response?.reason || msg.payload?.status || "error"})`);
+      }
+      // The channel died server-side (or was closed under us): same treatment.
+      if (msg.event === "phx_error" || msg.event === "phx_close") return recycle("channel closed");
+      if (msg.event === "broadcast" && msg.payload?.event === "wake") onWake();
+    };
+
+    sock.onclose = () => {
+      teardown();
+      scheduleReconnect();
+    };
+    sock.onerror = () => {
+      // onclose follows and owns the reconnect; nothing to do here.
+    };
+  }
+
+  // Slow re-check: if the workspace rotated its topic while we were happily
+  // joined to the old one, nothing drops the socket — we would just stop
+  // hearing pings. Re-resolve on a timer and reconnect only when it changed.
+  const scheduleRefresh = () => {
+    if (stopped) return;
+    refreshTimer = setTimeout(async () => {
+      refreshTimer = null;
+      if (stopped) return;
+      try {
+        const next = await resolve();
+        if (!stopped && next?.topic && next.topic !== currentTopic) {
+          log.log("wake: doorbell topic rotated — resubscribing");
+          teardown();
+          if (reconnectTimer) clearTimeout(reconnectTimer);
+          reconnectTimer = null;
+          backoff = RECONNECT_MIN_MS;
+          void connect();
+        }
+      } catch {
+        /* the doorbell is an accelerator; a failed re-check changes nothing */
+      }
+      scheduleRefresh();
+    }, refreshMs);
+    // Never hold the process open for a doorbell re-check.
+    refreshTimer?.unref?.();
+  };
+
+  void connect();
+
+  return {
+    stop() {
+      stopped = true;
+      if (reconnectTimer) clearTimeout(reconnectTimer);
+      reconnectTimer = null;
+      if (refreshTimer) clearTimeout(refreshTimer);
+      refreshTimer = null;
+      teardown();
+    },
+  };
+}
+
+/**
+ * The wake gate: the tiny bit of state that connects a doorbell ping to the
+ * poll loop's inter-poll sleep. Extracted from run.mjs so the race it exists to
+ * close is unit-testable — a ping that lands mid-poll (no sleeper armed) must
+ * be REMEMBERED, so the next sleep returns immediately instead of the ping
+ * being lost and the daemon waiting out a full pollMs anyway.
+ *
+ * @param {{ signal?: AbortSignal }} [opts]
+ * @returns {{ ping: () => void, sleep: (ms: number) => Promise<void> }}
+ */
+export function createWakeGate({ signal } = {}) {
+  let pending = false;
+  let sleeper = null;
+
+  const ping = () => {
+    pending = true;
+    if (sleeper) sleeper();
+  };
+
+  // A sleep that resolves immediately when the signal aborts (so "stop" doesn't
+  // wait out the whole poll interval) or when the wake doorbell rings.
+  const sleep = (ms) =>
+    new Promise((resolve) => {
+      if (signal?.aborted) return resolve();
+      if (pending) {
+        pending = false;
+        return resolve();
+      }
+      const done = () => {
+        signal?.removeEventListener?.("abort", onAbort);
+        sleeper = null;
+        resolve();
+      };
+      const timer = setTimeout(done, ms);
+      sleeper = () => {
+        pending = false;
+        clearTimeout(timer);
+        done();
+      };
+      function onAbort() {
+        clearTimeout(timer);
+        done();
+      }
+      signal?.addEventListener?.("abort", onAbort, { once: true });
+    });
+
+  return { ping, sleep };
+}