talon-agent 5.18.2 → 5.19.0

package/src/frontend/telegram/userbot.ts

@@ -17,6 +17,7 @@ import writeFileAtomic from "write-file-atomic";
 import { log, logError, logWarn } from "../../util/log.js";
 import { dirs, files } from "../../util/paths.js";
 import { formatSmartTimestamp } from "../../util/time.js";
+import { createOutage, errorText } from "../health/outage.js";
 
 const SESSION_FILE = files.userSession;
 
@@ -152,6 +153,39 @@ export function withTimeout<T>(
   return Promise.race([p, timeout]).finally(() => clearTimeout(timer));
 }
 
+/** How long the monitor may fail to reconnect before the operator hears. */
+const USERBOT_OUTAGE_MS = 15 * 60 * 1000;
+
+const outage = createOutage({
+  key: "telegram.userbot",
+  thresholdMs: USERBOT_OUTAGE_MS,
+  severity: "warn",
+  describe: (err, mins) =>
+    `The Telegram user client has failed to reconnect for ${mins} min: ${err}. ` +
+    "Full history search and member lookups are unavailable.",
+  recovered: "The Telegram user client is reconnected.",
+});
+
+/** One failed monitor step, logged with its place in the outage. */
+function noteFailure(step: string, err: unknown): void {
+  const { attempt, downMs } = outage.fail(err);
+  logWarn(
+    "userbot",
+    `userbot.reconnect.fail step=${step} attempt=${attempt} down_ms=${downMs} ` +
+      `next_check_ms=${CHECK_INTERVAL_MS} err=${errorText(err)}`,
+  );
+}
+
+/** A healthy monitor step; logs the end of an outage when there was one. */
+function noteHealthy(via: string): void {
+  const ended = outage.ok();
+  if (!ended) return;
+  log(
+    "userbot",
+    `userbot.reconnect.ok via=${via} failed_attempts=${ended.attempts} down_ms=${ended.downMs}`,
+  );
+}
+
 let reconnecting = false;
 // Bumped by stopConnectionMonitor so a tick whose awaits straddle a shutdown
 // can tell that its own client was torn down under it — the liveness probe
@@ -164,8 +198,19 @@ function startConnectionMonitor(): void {
   const gen = monitorGeneration;
   reconnectTimer = setInterval(async () => {
     if (gen !== monitorGeneration) return;
-    if (!client) return;
     if (reconnecting) return; // prevent overlapping reconnect attempts
+    if (!client) {
+      // A failed re-init leaves no client. Retry it every tick; bailing
+      // here left the userbot dead until the daemon restarted.
+      if (!storedApiId || !storedApiHash) return;
+      reconnecting = true;
+      try {
+        await reinitClient();
+      } finally {
+        reconnecting = false;
+      }
+      return;
+    }
 
     // GramJS keeps `client.connected === true` even after the underlying
     // socket has silently died, so a real round-trip is the only reliable
@@ -179,6 +224,7 @@ function startConnectionMonitor(): void {
           RECONNECT_STEP_TIMEOUT_MS,
           "liveness probe",
         );
+        noteHealthy("probe");
         return; // genuinely alive
       } catch {
         if (gen !== monitorGeneration) return; // monitor stopped mid-probe
@@ -203,55 +249,73 @@ function startConnectionMonitor(): void {
         )
       ) {
         log("userbot", "Reconnected successfully.");
+        noteHealthy("reconnect");
       } else {
         logWarn("userbot", "Reconnected but not authorized.");
+        noteFailure("reconnect", "connected but not authorized");
       }
     } catch (err) {
       if (gen !== monitorGeneration) return; // stopped while reconnecting
       logError("userbot", "Reconnect failed", err);
-      // Try a full re-init on next check
-      if (storedApiId && storedApiHash) {
-        try {
-          // Drop the wedged client without awaiting it — its socket may be
-          // the thing that's hung.
-          const stale = client;
-          client = null;
-          void stale?.disconnect().catch(() => {});
-          let sessionString = "";
-          if (existsSync(SESSION_FILE)) {
-            sessionString = readFileSync(SESSION_FILE, "utf-8").trim();
-          }
-          const session = new StringSession(sessionString);
-          client = new TelegramClient(session, storedApiId, storedApiHash, {
-            connectionRetries: 5,
-          });
-          await withTimeout(
-            client.connect(),
-            RECONNECT_STEP_TIMEOUT_MS,
-            "re-init connect",
-          );
-          if (
-            await withTimeout(
-              client.isUserAuthorized(),
-              RECONNECT_STEP_TIMEOUT_MS,
-              "re-init auth check",
-            )
-          ) {
-            log("userbot", "Full re-init reconnect succeeded.");
-          }
-        } catch (retryErr) {
-          logError("userbot", "Full re-init reconnect failed", retryErr);
-          client = null;
-        }
-      }
+      if (storedApiId && storedApiHash) await reinitClient();
+      else noteFailure("reconnect", err);
     } finally {
       reconnecting = false;
     }
   }, CHECK_INTERVAL_MS);
 }
 
+/**
+ * Replace the client with a fresh one from the saved session. On failure
+ * the slot is left empty (and the failed client closed); the monitor's
+ * next tick tries again.
+ */
+async function reinitClient(): Promise<void> {
+  // Drop the wedged client without awaiting it — its socket may be the
+  // thing that's hung.
+  const stale = client;
+  client = null;
+  void stale?.disconnect().catch(() => {});
+  let fresh: TelegramClient | null = null;
+  try {
+    let sessionString = "";
+    if (existsSync(SESSION_FILE)) {
+      sessionString = readFileSync(SESSION_FILE, "utf-8").trim();
+    }
+    const session = new StringSession(sessionString);
+    fresh = new TelegramClient(session, storedApiId, storedApiHash, {
+      connectionRetries: 5,
+    });
+    client = fresh;
+    await withTimeout(
+      fresh.connect(),
+      RECONNECT_STEP_TIMEOUT_MS,
+      "re-init connect",
+    );
+    if (
+      await withTimeout(
+        fresh.isUserAuthorized(),
+        RECONNECT_STEP_TIMEOUT_MS,
+        "re-init auth check",
+      )
+    ) {
+      log("userbot", "Full re-init reconnect succeeded.");
+      noteHealthy("re-init");
+    } else {
+      noteFailure("re-init", "connected but not authorized");
+    }
+  } catch (retryErr) {
+    logError("userbot", "Full re-init reconnect failed", retryErr);
+    noteFailure("re-init", retryErr);
+    if (client === fresh) client = null;
+    // Its connect may still be retrying in the background.
+    void fresh?.disconnect().catch(() => {});
+  }
+}
+
 function stopConnectionMonitor(): void {
   monitorGeneration++;
+  outage.dispose();
   if (reconnectTimer) {
     clearInterval(reconnectTimer);
     reconnectTimer = null;

package/src/frontend/terminal/builtins/session.ts

@@ -1,7 +1,7 @@
 /** `/reset`, `/resume`, `/rename` — session lifecycle. */
 
 import pc from "picocolors";
-import { formatTimeAgo } from "../renderer.js";
+import { formatRelativeAge } from "../../../util/time.js";
 import { isTerminalChatId } from "../../../core/frontend-runtime/chat-id.js";
 import { resolveModel as coreResolveModel } from "../../../core/models/catalog.js";
 import {
@@ -49,7 +49,7 @@ export const resumeCommand: Command = {
         ? `"${s.info.sessionName}"`
         : pc.dim("(unnamed)");
       const turns = `${s.info.turns} turn${s.info.turns !== 1 ? "s" : ""}`;
-      const ago = formatTimeAgo(s.info.lastActive);
+      const ago = formatRelativeAge(s.info.lastActive);
       const model = s.info.lastModel
         ? (coreResolveModel(s.info.lastModel)?.displayName ?? s.info.lastModel)
         : "";

package/src/frontend/terminal/index.ts

@@ -8,9 +8,7 @@
  *   - Renderer NEVER touches readline. Only this file does.
  *
  * `start()` returns once that prompt is drawn — the frontend lifecycle
- * contract (core/frontend-runtime/capabilities.ts). It used to park on a
- * promise that never resolved, which is why the composition root had to
- * special-case the terminal and start it without awaiting.
+ * contract (core/frontend-runtime/capabilities.ts).
  */
 
 import pc from "picocolors";

package/src/frontend/terminal/renderer.ts

@@ -7,7 +7,7 @@
  */
 
 import pc from "picocolors";
-import { formatUsd } from "../presentation/format.js";
+import { formatTokenCount, formatUsd } from "../presentation/format.js";
 
 // ── Types ────────────────────────────────────────────────────────────────────
 
@@ -70,22 +70,6 @@ export function wrap(text: string, indent: number, maxWidth: number): string {
     .join("\n");
 }
 
-export function formatTimeAgo(ts: number): string {
-  const sec = Math.floor((Date.now() - ts) / 1000);
-  if (sec < 60) return "just now";
-  const min = Math.floor(sec / 60);
-  if (min < 60) return `${min}m ago`;
-  const hr = Math.floor(min / 60);
-  if (hr < 24) return `${hr}h ago`;
-  return `${Math.floor(hr / 24)}d ago`;
-}
-
-function fmtTok(n: number): string {
-  if (n < 1000) return String(n);
-  if (n < 1_000_000) return `${(n / 1000).toFixed(1)}k`;
-  return `${(n / 1_000_000).toFixed(1)}M`;
-}
-
 export function extractToolDetail(
   input: Record<string, unknown>,
   maxLen: number,
@@ -189,7 +173,7 @@ export function createRenderer(cols?: number, displayName = "Talon"): Renderer {
     if (info.sessionName) p.push(`"${info.sessionName}"`);
     p.push(
       `${info.turns} turn${info.turns !== 1 ? "s" : ""}`,
-      `${fmtTok(info.inputTokens + info.outputTokens)} tok`,
+      `${formatTokenCount(info.inputTokens + info.outputTokens)} tok`,
     );
     if (typeof info.cacheHitPct === "number") {
       p.push(`${info.cacheHitPct}% cache`);

package/src/frontend/whatsapp/actions/index.ts

@@ -33,6 +33,16 @@ import { mediaHandlers } from "./media.js";
 import { messagingHandlers } from "./messaging.js";
 import { moderationHandlers } from "./moderation.js";
 import type { WhatsAppActionContext, WhatsAppActionHandlers } from "./types.js";
+import {
+  createDeliveryTracker,
+  trackDeliveries,
+} from "../../health/delivery.js";
+
+const delivery = createDeliveryTracker("whatsapp", "WhatsApp", "whatsapp");
+
+/** A cross-send names its destination; everything else goes to `chatId`. */
+const destination = (body: Record<string, unknown>, chatId: number) =>
+  body.target !== undefined ? String(body.target) : chatId;
 
 // Null-prototype so a request `action` of "toString" / "constructor" can't
 // resolve an inherited Object.prototype method via `handlers[action]`.
@@ -62,7 +72,7 @@ export function createWhatsAppActionHandler(
 ) {
   const scheduledMessages = new Map<string, ReturnType<typeof setTimeout>>();
 
-  return async (
+  const dispatch = async (
     body: Record<string, unknown>,
     chatId: number,
   ): Promise<ActionResult | null> => {
@@ -118,4 +128,5 @@ export function createWhatsAppActionHandler(
       ? { ...result, chat_id: chat.chatId }
       : result;
   };
+  return trackDeliveries(delivery, dispatch, destination);
 }

package/src/frontend/whatsapp/actions/messaging.ts

@@ -17,6 +17,9 @@ import { tryAction } from "./try-action.js";
 import { resolveQuoted, sendContent, sendText, boundedSend } from "./send.js";
 import type { WhatsAppActionHandlers } from "./types.js";
 
+/** The tool schema's documented ceiling (1-86400), as telegram/discord clamp. */
+const MAX_DELAY_SEC = 24 * 60 * 60;
+
 /** WhatsApp keeps a pin for 24h, 7d, or 30d — no indefinite option. */
 const PIN_DURATIONS = [86_400, 604_800, 2_592_000] as const;
 
@@ -229,16 +232,18 @@ export const messagingHandlers: WhatsAppActionHandlers = {
   schedule_message: (body, _chatId, ctx) =>
     tryAction("schedule_message", async () => {
       const text = String(body.text ?? "");
-      const seconds = Number(body.delay_seconds ?? 0);
+      const requested = Number(body.delay_seconds ?? 0);
       if (!text.trim()) {
         return { ok: false, error: "schedule_message: text is required" };
       }
-      if (!Number.isFinite(seconds) || seconds <= 0) {
+      if (!Number.isFinite(requested) || requested <= 0) {
         return {
           ok: false,
           error: "schedule_message: delay_seconds must be a positive number",
         };
       }
+      // Past setTimeout's 2^31-1 ms (~24.8 days) the timer fires at once.
+      const seconds = Math.min(MAX_DELAY_SEC, requested);
       const id = randomUUID();
       const chat = ctx.chat!;
       const timer = setTimeout(() => {

package/src/frontend/whatsapp/connection/connection.ts

@@ -11,7 +11,10 @@ import makeWASocket, { type AuthenticationState, type WASocket } from "baileys";
 import qrcode from "qrcode-terminal";
 import { log, logError, logWarn } from "../../../util/log.js";
 import { dirs } from "../../../util/paths.js";
-import { notifyAdmin } from "../../../core/frontend-runtime/admin-notify.js";
+import {
+  raiseAlert,
+  resolveAlert,
+} from "../../../core/frontend-runtime/alerts.js";
 import { useAtomicAuthState } from "./auth-state.js";
 import { bareId } from "./identity.js";
 import { handleInbound } from "../messages/inbound.js";
@@ -23,6 +26,7 @@ import {
   type WhatsAppRuntime,
 } from "../runtime.js";
 import { makeWaLogger } from "./wa-logger.js";
+import { errorText } from "../../health/outage.js";
 
 /** What the connection loop should do after a socket ends. */
 type ConnectOutcome = "reconnect" | "logged-out" | "unpaired" | "stop";
@@ -64,9 +68,11 @@ function onQr(runtime: WhatsAppRuntime, qr: string): void {
   qrcode.generate(qr, { small: true });
   if (!runtime.unpairedNotified) {
     runtime.unpairedNotified = true;
-    void notifyAdmin(
-      "📱 WhatsApp is not linked. Send /whatsapp pair when you're " +
+    raiseAlert(
+      "whatsapp.linked",
+      "WhatsApp is not linked. Send /whatsapp pair when you're " +
         "ready and I'll reply with a QR to scan.",
+      { severity: "warn" },
     );
   }
 }
@@ -77,10 +83,10 @@ function onOpen(runtime: WhatsAppRuntime, socket: WASocket): void {
     .filter((id): id is string => Boolean(id))
     .map(bareId);
   runtime.reconnectDelay = RECONNECT_BASE_MS;
-  if (runtime.unpairedNotified) {
-    void notifyAdmin("✅ WhatsApp linked and connected.");
-  }
+  // Announces only when a "not linked" / "unlinked" alert went out.
+  resolveAlert("whatsapp.linked", "WhatsApp linked and connected.");
   runtime.unpairedNotified = false;
+  runtime.health.opened();
   log(
     "whatsapp",
     `Connected as ${socket.user?.name ?? "?"} (${runtime.selfIds.join("/") || "?"})`,
@@ -91,6 +97,7 @@ function onClose(
   runtime: WhatsAppRuntime,
   state: AuthenticationState,
   code: number | undefined,
+  reason: string,
 ): ConnectOutcome {
   if (runtime.stopping) return "stop";
   const disposition = classifyClose(code, state.creds.registered);
@@ -113,6 +120,7 @@ function onClose(
         "whatsapp",
         "Connection replaced by another client (440) — backing off",
       );
+      runtime.health.noteClose("replaced by another client (440)");
       runtime.reconnectDelay = REPLACED_BACKOFF_MS;
       return "reconnect";
     case "logged-out":
@@ -128,6 +136,7 @@ function onClose(
       // session on its first ordinary disconnect.
       if (!isPaired(state.creds)) return "unpaired";
       log("whatsapp", `Connection closed (code ${code ?? "?"}) — reconnecting`);
+      runtime.health.noteClose(`code=${code ?? "?"} ${reason}`);
       return "reconnect";
   }
 }
@@ -163,6 +172,9 @@ async function connectOnce(
   // Atomic replacement for Baileys' useMultiFileAuthState — same disk
   // format, torn-write-proof (see auth-state.ts for why that matters).
   const { state, saveCreds } = await useAtomicAuthState(dirs.whatsappAuth);
+  // stop() ends runtime.sock, which is still null while auth loads; a
+  // socket built after it would never close and stop() would wait forever.
+  if (runtime.stopping) return "stop";
   const socket = makeWASocket({
     auth: state,
     logger: makeWaLogger(),
@@ -195,7 +207,8 @@ async function connectOnce(
           lastDisconnect?.error as
             { output?: { statusCode?: number } } | undefined
         )?.output?.statusCode;
-        resolve(onClose(runtime, state, code));
+        const reason = errorText(lastDisconnect?.error ?? "closed");
+        resolve(onClose(runtime, state, code, reason));
       }
     });
   });
@@ -260,6 +273,7 @@ export async function runConnectionLoop(
   try {
     await connectionLoop(runtime, signalReady);
   } finally {
+    runtime.health.dispose();
     signalReady();
     log("whatsapp", "WhatsApp connection loop ended");
   }
@@ -290,6 +304,7 @@ async function connectionLoop(
       // half-written auth dir, say) must not hold the boot open while
       // the loop keeps trying.
       signalReady();
+      runtime.health.noteClose(`socket error: ${errorText(err)}`);
       outcome = "reconnect";
     }
     runtime.sock = null;
@@ -306,10 +321,13 @@ async function connectionLoop(
         "whatsapp",
         "Logged out by WhatsApp — parked until /whatsapp pair re-links",
       );
-      void notifyAdmin(
-        "⚠️ WhatsApp unlinked this device. When you're ready to " +
+      runtime.health.dispose();
+      raiseAlert(
+        "whatsapp.linked",
+        "WhatsApp unlinked this device. When you're ready to " +
           "re-link, send /whatsapp pair and scan the QR I reply with. " +
           "Nothing is retried until then.",
+        { severity: "warn" },
       );
       rmSync(dirs.whatsappAuth, { recursive: true, force: true });
       await parkUntilPaired(runtime);
@@ -318,10 +336,12 @@ async function connectionLoop(
     }
     if (outcome === "unpaired") {
       log("whatsapp", "Not paired — parked until /whatsapp pair links");
+      runtime.health.dispose();
       await parkUntilPaired(runtime);
       runtime.reconnectDelay = RECONNECT_BASE_MS;
       continue;
     }
+    runtime.health.reconnecting(runtime.reconnectDelay);
     await sleep(runtime, runtime.reconnectDelay);
     runtime.reconnectDelay = Math.min(
       runtime.reconnectDelay * 2,

package/src/frontend/whatsapp/connection/health.ts

@@ -0,0 +1,89 @@
+/**
+ * Connection health — the operator hears when the WhatsApp socket keeps
+ * dropping instead of staying up.
+ *
+ * Every unexpected close is logged with its attempt number, the time the
+ * connection has been unstable, the backoff before the next socket, and
+ * the reason. Closes that keep coming for `CONNECTION_OUTAGE_MS` raise
+ * `whatsapp.connection`. An open alone does not end the outage — a socket
+ * that opens and dies again is exactly the flapping this watches for — so
+ * the outage ends only once a socket has stayed open for `STABLE_OPEN_MS`.
+ *
+ * Unlinking is not a connection fault: the loop parks and the
+ * `whatsapp.linked` alert speaks for it (connection.ts).
+ */
+
+import { log, logWarn } from "../../../util/log.js";
+import { createOutage } from "../../health/outage.js";
+
+const CONNECTION_OUTAGE_MS = 10 * 60_000;
+/** How long a socket must stay open before the connection counts as stable. */
+const STABLE_OPEN_MS = 60_000;
+
+export type ConnectionHealth = {
+  /** Record why the socket just closed; `reconnecting` counts it. */
+  noteClose(detail: string): void;
+  /** The loop will build a new socket after `backoffMs`. */
+  reconnecting(backoffMs: number): void;
+  opened(): void;
+  /** Forget the outage without resolving it — park or shutdown. */
+  dispose(): void;
+};
+
+export function createConnectionHealth(
+  thresholdMs = CONNECTION_OUTAGE_MS,
+  stableMs = STABLE_OPEN_MS,
+): ConnectionHealth {
+  const outage = createOutage({
+    key: "whatsapp.connection",
+    thresholdMs,
+    describe: (err, mins) =>
+      `The WhatsApp connection has kept dropping for ${mins} min: ${err}. ` +
+      "Messages may not be received or delivered.",
+    recovered: "The WhatsApp connection is stable again.",
+  });
+  let pending: string | null = null;
+  let stableTimer: ReturnType<typeof setTimeout> | null = null;
+  const clearStable = (): void => {
+    if (stableTimer) clearTimeout(stableTimer);
+    stableTimer = null;
+  };
+
+  return {
+    noteClose(detail) {
+      clearStable();
+      pending = detail;
+    },
+    reconnecting(backoffMs) {
+      // A close nobody noted (515 finishing a pairing) is not a fault.
+      if (pending === null) return;
+      const detail = pending;
+      pending = null;
+      const { attempt, downMs } = outage.fail(detail);
+      logWarn(
+        "whatsapp",
+        `connection.reconnect attempt=${attempt} down_ms=${downMs} backoff_ms=${backoffMs} err=${detail}`,
+      );
+    },
+    opened() {
+      clearStable();
+      if (!outage.down) return;
+      stableTimer = setTimeout(() => {
+        stableTimer = null;
+        const ended = outage.ok();
+        if (ended) {
+          log(
+            "whatsapp",
+            `connection.stable failed_attempts=${ended.attempts} down_ms=${ended.downMs}`,
+          );
+        }
+      }, stableMs);
+      stableTimer.unref?.();
+    },
+    dispose() {
+      clearStable();
+      pending = null;
+      outage.dispose();
+    },
+  };
+}

package/src/frontend/whatsapp/connection/identity.ts

@@ -2,8 +2,8 @@
  * Identity resolution — the LID/phone-number duality.
  *
  * WhatsApp addresses people two ways. The historical form is the phone
- * number (`353834733284@s.whatsapp.net`, "PN"); the newer privacy form
- * is a linked identity (`180753715482747@lid`, "LID") that hides the
+ * number (`447700900102@s.whatsapp.net`, "PN"); the newer privacy form
+ * is a linked identity (`190000000000001@lid`, "LID") that hides the
  * number. Which one arrives depends on the sender's privacy settings and
  * the chat's addressing mode, and neither is derivable from the other —
  * they are looked up.
@@ -22,9 +22,9 @@
 import { isLidUser, jidNormalizedUser, type WASocket } from "baileys";
 
 export type Identity = {
-  /** Phone-number form, digits only, when known: "353834733284". */
+  /** Phone-number form, digits only, when known: "447700900102". */
   phone?: string;
-  /** LID form, digits only, when known: "180753715482747". */
+  /** LID form, digits only, when known: "190000000000001". */
   lid?: string;
   /** Every bare id this person is known by — what allowlists match on. */
   ids: string[];

package/src/frontend/whatsapp/runtime.ts

@@ -1,17 +1,20 @@
 /**
  * WhatsApp frontend runtime — the state every module shares.
  *
- * `createWhatsAppFrontend` used to hold all of this as closure variables
- * with every handler nested inside it. It is now one explicit object,
- * constructed once, that each module (access, inbound, connection) takes
- * as its first parameter. The runtime carries the parsed settings, the
- * allow-lists and the live socket state; the modules own the behaviour.
+ * One explicit object, constructed once, that each module (access,
+ * inbound, connection) takes as its first parameter. The runtime carries
+ * the parsed settings, the allow-lists and the live socket state; the
+ * modules own the behaviour.
  */
 
 import type { WASocket } from "baileys";
 import type { TalonConfig } from "../../core/config/index.js";
 import type { Gateway } from "../../core/engine/gateway.js";
 import { bareId } from "./connection/identity.js";
+import {
+  createConnectionHealth,
+  type ConnectionHealth,
+} from "./connection/health.js";
 
 type WhatsAppSettings = {
   allowedJids: string[];
@@ -47,6 +50,8 @@ export type WhatsAppRuntime = {
   reconnectDelay: number;
   /** One "not linked" admin note per outage, not one per QR window. */
   unpairedNotified: boolean;
+  /** Reconnect logging and the `whatsapp.connection` alert. */
+  readonly health: ConnectionHealth;
   /** Our own ids (phone and LID), once connected — for mention detection. */
   selfIds: string[];
 };
@@ -76,6 +81,7 @@ export function createWhatsAppRuntime(
     stopRequest: new AbortController(),
     reconnectDelay: RECONNECT_BASE_MS,
     unpairedNotified: false,
+    health: createConnectionHealth(),
     selfIds: [],
   };
 }

package/src/native/blake3.ts

@@ -34,6 +34,7 @@
 import { createReadStream } from "node:fs";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
+import { logDebug, logWarn } from "../util/log.js";
 import { BLAKE3_WASM_BASE64 } from "./blake3-wasm-bytes.js";
 import {
   allocRegion,
@@ -99,13 +100,38 @@ function loadNativeBlake3(): NativeBlake3 | null {
     const addon = requireAddon(candidate) as NativeBlake3;
     // Trust nothing that can't produce a known digest — a truncated or
     // wrong-arch artifact fails here and wasm silently takes over.
-    if (addon.hashHex(Buffer.alloc(0)) !== EMPTY_DIGEST) return null;
+    if (addon.hashHex(Buffer.alloc(0)) !== EMPTY_DIGEST) {
+      reportAddonRejected(candidate, "digest mismatch");
+      return null;
+    }
     return addon;
-  } catch {
+  } catch (err) {
+    reportAddonRejected(candidate, err);
     return null;
   }
 }
 
+/**
+ * Wasm takes over either way; the log says why. An absent default
+ * artifact is the normal npm install; an explicit TALON_BLAKE3_NODE
+ * that fails to load is operator config silently not taking effect.
+ */
+function reportAddonRejected(candidate: string, reason: unknown): void {
+  const code = (reason as { code?: unknown } | null)?.code;
+  const why = reason instanceof Error ? reason.message : String(reason);
+  if (process.env.TALON_BLAKE3_NODE) {
+    logWarn(
+      "native",
+      `TALON_BLAKE3_NODE addon rejected, using wasm path=${candidate}: ${why}`,
+    );
+  } else if (code !== "MODULE_NOT_FOUND") {
+    logDebug(
+      "native",
+      `blake3 addon rejected, using wasm path=${candidate}: ${why}`,
+    );
+  }
+}
+
 /** Tests swap addons via TALON_BLAKE3_NODE and need the memo dropped. */
 export function _resetNativeBlake3ForTesting(): void {
   nativeAddon = undefined;