talon-agent 5.27.0 → 5.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "5.27.0",
+  "version": "5.28.0",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "The Falconry",
   "license": "Apache-2.0",

package/src/app.ts

@@ -128,10 +128,18 @@ stampDaemonOwner();
  *
  * Never throws: a failed restore still boots the daemon (with the reason
  * in the log and the request deleted, so the next boot is normal).
+ * Returns the confirmation line and who asked for it, so it can be sent
+ * back to that chat once the frontends are up.
  */
-async function applyStagedRestore(): Promise<string | null> {
+async function applyStagedRestore(): Promise<{
+  text: string;
+  requestedBy?: string;
+  frontend?: string;
+} | null> {
   const { applyPendingRestore, readRestorePending } =
     await import("./core/backup/index.js");
+  const { formatRestoreNotice } =
+    await import("./core/backup/restore/notice.js");
   if (!(await readRestorePending())) return null;
   const { loadConfig } = await import("./core/config/index.js");
   const { resolveBackupSettings } = await import("./core/backup/plan.js");
@@ -141,12 +149,11 @@ async function applyStagedRestore(): Promise<string | null> {
     beforeApply: closeDatabase,
   });
   if (!report) return null;
-  return (
-    `♻️ Restored snapshot ${report.id}` +
-    (report.checkpointId
-      ? ` (previous state saved as checkpoint ${report.checkpointId})`
-      : "")
-  );
+  return {
+    text: formatRestoreNotice(report),
+    requestedBy: report.requestedBy,
+    frontend: report.frontend,
+  };
 }
 
 /**
@@ -546,12 +553,21 @@ async function main(): Promise<void> {
   // Phase 0 accounting (docs/ts-migration-plan.md): the boot is over the
   // moment the frontends are listening, so the totals are folded into the
   // metrics store here, from the same uptime figure the log line prints.
-  // A restore applied at boot happened before any frontend existed, so the
-  // operator hears about it here, on the first channel that can carry it.
+  // A restore applied at boot happened before any frontend existed, so it
+  // is reported here, on the first channels that can carry it: the chat
+  // that asked for it, or the admin's primary chat when that one can't be
+  // reached. Not awaited — delivery may retry while a frontend finishes
+  // connecting, and the boot shouldn't wait on a courtesy message.
   if (restoreReport) {
     const { notifyAdmin } =
       await import("./core/frontend-runtime/admin-notify.js");
-    await notifyAdmin(restoreReport);
+    const { deliverRestoreNotice } =
+      await import("./core/backup/restore/notice.js");
+    void deliverRestoreNotice({
+      text: restoreReport.text,
+      requester: restoreReport,
+      notifyAdmin,
+    });
   }
   // Same reasoning for a crash: the process that died couldn't say so,
   // so the marker it left is announced now. The probes start here too —

package/src/core/backup/{restore-guard.ts → restore/guard.ts}

@@ -22,11 +22,11 @@
  */
 
 import { chmod } from "node:fs/promises";
-import { logWarn } from "../../util/log.js";
-import { TalonError } from "../errors.js";
-import { verifyManifest } from "./archive/manifest-auth.js";
-import { resolvePassphrase } from "./passphrase.js";
-import type { BackupSettings, Manifest } from "./types.js";
+import { logWarn } from "../../../util/log.js";
+import { TalonError } from "../../errors.js";
+import { verifyManifest } from "../archive/manifest-auth.js";
+import { resolvePassphrase } from "../passphrase.js";
+import type { BackupSettings, Manifest } from "../types.js";
 
 export type ManifestTrust = {
   /** Operator override for unauthenticated manifests. */

package/src/core/backup/restore/notice.ts

@@ -0,0 +1,164 @@
+/**
+ * Reporting a staged restore back to the chat that asked for it.
+ *
+ * `/backup restore <id>` stages the request and restarts; the restore runs
+ * in the next boot before any frontend exists (see `applyStagedRestore` in
+ * app.ts). Once the frontends are up, the "♻️ Restored snapshot …" line is
+ * delivered here: to the requesting chat, on the frontend it came from,
+ * and — when that chat can't be reached (frontend disabled, delivery
+ * failing) or the request never said who asked — to the operator's
+ * primary chat through the admin notifier, which is where it always went
+ * before.
+ *
+ * Core never imports src/frontend, so delivery goes through the same
+ * cross-send broker `send_via` uses: each enabled frontend's action
+ * handler, keyed by frontend name.
+ */
+
+import { log, logWarn } from "../../../util/log.js";
+import {
+  isNativeChatId,
+  isTelegramChatId,
+  numericChatIdFor,
+} from "../../frontend-runtime/chat-id.js";
+import { crossSendTarget } from "../../engine/gateway-actions/cross-send.js";
+import type { RestoreReport } from "../restore.js";
+
+/** Who asked for a staged restore, as recorded in restore-pending.json. */
+export type RestoreRequester = {
+  /** The requesting chat's key (Telegram id, `d_…`, `discord_…`). */
+  requestedBy?: string;
+  /** The frontend the request came from. Absent in files staged before it existed. */
+  frontend?: string;
+};
+
+/**
+ * The frontend a requester belongs to: the recorded one when the request
+ * carries it, else inferred from the shape of the chat key — Telegram's
+ * ids are numeric, native's start `d_`, Discord's `discord_`. Undefined
+ * when neither says.
+ */
+export function requesterFrontend(
+  requester: RestoreRequester,
+): string | undefined {
+  const explicit =
+    typeof requester.frontend === "string"
+      ? requester.frontend.trim().toLowerCase()
+      : "";
+  if (explicit) return explicit;
+  const key =
+    typeof requester.requestedBy === "string" ? requester.requestedBy : "";
+  if (!key) return undefined;
+  if (isTelegramChatId(key)) return "telegram";
+  if (isNativeChatId(key)) return "native";
+  if (key.startsWith("discord_")) return "discord";
+  return undefined;
+}
+
+/** The confirmation line a successful staged restore reports. */
+export function formatRestoreNotice(
+  report: Pick<RestoreReport, "id" | "checkpointId">,
+): string {
+  return (
+    `♻️ Restored snapshot ${report.id}` +
+    (report.checkpointId
+      ? ` (previous state saved as checkpoint ${report.checkpointId})`
+      : "")
+  );
+}
+
+/**
+ * Send `text` to one chat through its frontend's registered action
+ * handler. The chat key rides in `target` so a frontend that has not
+ * seen the chat since the restart (a Discord channel nobody has spoken
+ * in yet, a native chat the restored database doesn't list) can adopt it.
+ * Resolves true only when the frontend reports the message delivered.
+ */
+async function sendToRequester(
+  frontend: string,
+  chatKey: string,
+  text: string,
+): Promise<boolean> {
+  const handler = crossSendTarget(frontend);
+  if (!handler) return false;
+  const result = await handler(
+    { action: "send_message", text, target: chatKey },
+    numericChatIdFor(chatKey),
+  );
+  return Boolean(result && result.ok === true);
+}
+
+const RESTORE_NOTICE_ATTEMPTS = 6;
+const RESTORE_NOTICE_DELAY_MS = 5_000;
+
+export type RestoreNoticeOptions = {
+  text: string;
+  requester: RestoreRequester;
+  /** The operator's primary chat — the fallback. */
+  notifyAdmin: (text: string) => Promise<unknown>;
+  send?: (frontend: string, chatKey: string, text: string) => Promise<boolean>;
+  /** Whether a frontend is enabled at all (no point retrying one that isn't). */
+  isEnabled?: (frontend: string) => boolean;
+  attempts?: number;
+  sleep?: (ms: number) => Promise<void>;
+};
+
+/**
+ * Deliver the restore notice to the requesting chat, falling back to the
+ * admin's primary chat. Retries a while when the requester's frontend is
+ * enabled but can't deliver yet — the frontends have just started, and a
+ * Discord client may still be logging in. Never throws; resolves with
+ * where the notice went.
+ */
+export async function deliverRestoreNotice(
+  options: RestoreNoticeOptions,
+): Promise<"requester" | "admin"> {
+  const {
+    text,
+    requester,
+    notifyAdmin,
+    send = sendToRequester,
+    isEnabled = (name) => crossSendTarget(name) !== undefined,
+    attempts = RESTORE_NOTICE_ATTEMPTS,
+    sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms).unref?.()),
+  } = options;
+  const frontend = requesterFrontend(requester);
+  const chatKey =
+    typeof requester.requestedBy === "string" ? requester.requestedBy : "";
+
+  if (frontend && chatKey && isEnabled(frontend)) {
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+      try {
+        if (await send(frontend, chatKey, text)) {
+          log("backup", `Restore reported to ${frontend} chat ${chatKey}`);
+          return "requester";
+        }
+      } catch (err) {
+        logWarn(
+          "backup",
+          `Restore report to ${frontend} chat ${chatKey} failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+      if (attempt < attempts) await sleep(RESTORE_NOTICE_DELAY_MS);
+    }
+    logWarn(
+      "backup",
+      `Could not reach ${frontend} chat ${chatKey}; reporting the restore to the admin chat instead`,
+    );
+  } else if (chatKey || frontend) {
+    logWarn(
+      "backup",
+      `Restore requester ${frontend ?? "?"}:${chatKey || "?"} is not reachable here; reporting to the admin chat`,
+    );
+  }
+
+  try {
+    await notifyAdmin(text);
+  } catch (err) {
+    logWarn(
+      "backup",
+      `Admin restore report failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  return "admin";
+}

package/src/core/backup/restore.ts

@@ -4,7 +4,7 @@
  * The rules that make this safe to run on a live home directory:
  *
  *   1. Verify before you touch anything. The manifest's signature is
- *      checked (restore-guard.ts), then every part's sha256 and — for
+ *      checked (restore/guard.ts), then every part's sha256 and — for
  *      encrypted parts — every record's tag; a part that fails is a
  *      stopped restore, not a half-applied one.
  *   2. Stage, then swap. The archive is extracted into a staging
@@ -55,7 +55,7 @@ import {
   authenticateManifest,
   makePrivate,
   type ManifestTrust,
-} from "./restore-guard.js";
+} from "./restore/guard.js";
 import { buildSnapshot } from "./snapshot.js";
 import {
   relocateRoot,
@@ -84,6 +84,12 @@ export type RestorePending = {
   requestedAt: number;
   /** Chat key that asked, so the boot can report back. */
   requestedBy?: string;
+  /**
+   * Frontend the request came from ("telegram", "discord", "native"), so
+   * the report goes back the way it came. Absent in files staged before
+   * it was recorded — the boot then infers it from `requestedBy`.
+   */
+  frontend?: string;
 };
 
 export type RestoreReport = {
@@ -507,7 +513,7 @@ export type RestoreOptions = {
   beforeApply?: () => void | Promise<void>;
   /** Skip the automatic pre-restore checkpoint (it has already been taken). */
   skipCheckpoint?: boolean;
-  /** Restore a manifest that carries no signature (see restore-guard.ts). */
+  /** Restore a manifest that carries no signature (see restore/guard.ts). */
   allowUnauthenticated?: ManifestTrust["allowUnauthenticated"];
   /**
    * Restoring onto a different machine: relocate the session stores and
@@ -641,7 +647,9 @@ export async function applyPendingRestore(options: {
   settings: BackupSettings;
   home?: string;
   beforeApply?: () => void | Promise<void>;
-}): Promise<(RestoreReport & { requestedBy?: string }) | null> {
+}): Promise<
+  (RestoreReport & { requestedBy?: string; frontend?: string }) | null
+> {
   const home = options.home ?? dirs.root;
   const pending = await readRestorePending(home);
   if (!pending) return null;
@@ -654,7 +662,11 @@ export async function applyPendingRestore(options: {
       beforeApply: options.beforeApply,
     });
     await clearRestorePending(home);
-    return { ...report, requestedBy: pending.requestedBy };
+    return {
+      ...report,
+      requestedBy: pending.requestedBy,
+      frontend: pending.frontend,
+    };
   } catch (err) {
     logWarn("backup", `Staged restore of ${pending.id} failed: ${String(err)}`);
     await clearRestorePending(home);

package/src/core/mesh/credentials/store.ts

@@ -23,7 +23,7 @@ import { resolve } from "node:path";
 import { dirs } from "../../../util/paths.js";
 import { log, logWarn } from "../../../util/log.js";
 import { TalonError } from "../../errors.js";
-import { readArray, writePrivateJson } from "../persist.js";
+import { readArray, writePrivateJson, writesSettled } from "../persist.js";
 import { faultText } from "../../engine/fault-text.js";
 import { raiseAlert, resolveAlert } from "../../frontend-runtime/alerts.js";
 import {
@@ -506,6 +506,14 @@ export class DeviceCredentialStore {
     }
   }
 
+  /**
+   * Wait for every background write queued so far (mintNow, bind, re-pair
+   * revocation, lastUsedAt touches) to reach disk or fail.
+   */
+  flush(): Promise<void> {
+    return writesSettled(this.file);
+  }
+
   private persistSoon(): void {
     void this.persist().catch((err: unknown) =>
       logWarn("mesh", `Could not persist mesh credentials: ${err}`),

package/src/core/mesh/persist.ts

@@ -25,6 +25,15 @@ export async function readArray<T>(path: string): Promise<T[]> {
   }
 }
 
+/**
+ * Resolve once every write queued for `path` so far has finished (settled,
+ * success or failure) — for callers that persisted fire-and-forget and now
+ * need the file on disk.
+ */
+export function writesSettled(path: string): Promise<void> {
+  return writeQueues.get(path) ?? Promise.resolve();
+}
+
 /** Persist JSON atomically with 0600 perms, serialized per path. */
 export async function writePrivateJson(
   path: string,

package/src/frontend/discord/actions/channels.ts

@@ -14,9 +14,12 @@ export async function resolveChannel(
   const info = lookupDiscordChat(numericChatId);
   if (!info) return null;
   try {
-    const ch = await client.channels.fetch(info.channelId);
-    if (ch && "send" in ch && (ch as TextBasedChannel).isSendable?.()) {
-      return ch as TextBasedChannel;
+    // A DM rebuilt from its chat key has no channel id — open it by user.
+    if (info.channelId) {
+      const ch = await client.channels.fetch(info.channelId);
+      if (ch && "send" in ch && (ch as TextBasedChannel).isSendable?.()) {
+        return ch as TextBasedChannel;
+      }
     }
     if (info.userId) {
       const user = await client.users.fetch(info.userId);

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

@@ -24,6 +24,11 @@ import type { Client } from "discord.js";
 import type { Gateway } from "../../../core/engine/gateway.js";
 import type { ActionResult } from "../../../core/types.js";
 import { resolveChannel } from "./channels.js";
+import {
+  lookupDiscordChat,
+  parseDiscordChatKey,
+  registerDiscordChat,
+} from "../handlers/registry.js";
 import { messagingHandlers, restoreScheduledMessages } from "./messaging.js";
 import { mediaHandlers } from "./media.js";
 import { chatInfoHandlers } from "./chat-info.js";
@@ -43,6 +48,24 @@ const handlers: DiscordActionHandlers = Object.assign(Object.create(null), {
   ...chatInfoHandlers,
 });
 
+/**
+ * A plain send addressed to a chat this process hasn't registered — the
+ * channel that asked for a staged restore, say, before anyone has spoken
+ * in it since the restart. The sender names the chat by key in
+ * `body.target`; when that key is the one the numeric id was derived
+ * from, register it so the channel resolves. send_message only.
+ */
+function adoptAddressedChat(
+  action: string,
+  body: Record<string, unknown>,
+  chatId: number,
+): void {
+  if (action !== "send_message" || lookupDiscordChat(chatId)) return;
+  const key = typeof body.target === "string" ? body.target : "";
+  const info = key ? parseDiscordChatKey(key) : undefined;
+  if (info && info.numericChatId === chatId) registerDiscordChat(info);
+}
+
 export function createDiscordActionHandler(client: Client, gateway: Gateway) {
   const scheduledMessages = new Map<string, ReturnType<typeof setTimeout>>();
 
@@ -58,6 +81,7 @@ export function createDiscordActionHandler(client: Client, gateway: Gateway) {
     const handler = handlers[action];
     if (!handler) return null; // not a Discord action
 
+    adoptAddressedChat(action, body, chatId);
     const channel = await resolveChannel(client, chatId);
 
     // For non-channel actions (e.g. cancel_scheduled) that don't need a

package/src/frontend/discord/commands/backup.ts

@@ -180,6 +180,7 @@ export async function handleBackupComponent(
       id,
       requestedAt: Date.now(),
       requestedBy: chatId,
+      frontend: "discord",
     });
     respawnSelf(`discord /backup restore ${id}`);
   } catch (err) {

package/src/frontend/discord/handlers/registry.ts

@@ -3,6 +3,7 @@
  * Discord channel info the action handler needs to post back.
  */
 
+import { deriveNumericChatId } from "../../../core/frontend-runtime/chat-id.js";
 import {
   chatRegistry,
   chatRegistryByString,
@@ -21,3 +22,37 @@ export function lookupDiscordChat(
 ): DiscordChatInfo | undefined {
   return chatRegistry.get(numericChatId);
 }
+
+/**
+ * Rebuild a chat's registry entry from its string key alone
+ * (`discord_guild_<guild>_<channel>` or `discord_dm_<user>`), for a chat
+ * this process hasn't seen a message from yet — the registry is in-memory,
+ * so after a restart only the allowed users' DMs are known until someone
+ * speaks. A DM entry carries no channel id; resolveChannel opens the DM
+ * from the user id. Undefined for anything that isn't a Discord chat key.
+ */
+export function parseDiscordChatKey(
+  chatKey: string,
+): DiscordChatInfo | undefined {
+  const guild = /^discord_guild_(\d+)_(\d+)$/.exec(chatKey);
+  if (guild) {
+    return {
+      channelId: guild[2]!,
+      guildId: guild[1]!,
+      userId: null,
+      numericChatId: deriveNumericChatId(chatKey),
+      chatId: chatKey,
+    };
+  }
+  const dm = /^discord_dm_(\d+)$/.exec(chatKey);
+  if (dm) {
+    return {
+      channelId: "",
+      guildId: null,
+      userId: dm[1]!,
+      numericChatId: deriveNumericChatId(chatKey),
+      chatId: chatKey,
+    };
+  }
+  return undefined;
+}

package/src/frontend/native/commands/backup.ts

@@ -145,6 +145,7 @@ async function restore(
       id,
       requestedAt: Date.now(),
       requestedBy: ctx.entry.id,
+      frontend: "native",
     });
   } catch (err) {
     logError("backup", "Staging the restore failed", err);

package/src/frontend/native/turn/actions.ts

@@ -15,6 +15,10 @@ import type {
 import type { Gateway } from "../../../core/engine/gateway.js";
 import type { NativeChats, ChatEntry } from "../chats/chats.js";
 import type { BridgeEvent, ClientButton } from "../protocol.js";
+import {
+  deriveNumericChatId,
+  isNativeChatId,
+} from "../../../core/frontend-runtime/chat-id.js";
 
 export type NativeActionDeps = {
   chats: NativeChats;
@@ -69,6 +73,28 @@ const NATIVE_ACTIONS = new Set([
   "send_chat_action",
 ]);
 
+/**
+ * A plain send addressed to a native chat this daemon doesn't list — the
+ * chat that asked for a staged restore, say, when the restored database
+ * predates it. The sender names the chat by key in `body.target`; the
+ * chat is adopted (as a deep link would) so the message lands in its
+ * history and the app shows it. Only when the key really is the chat the
+ * numeric id was derived from, and only for send_message: edits,
+ * reactions and deletes address messages, which an unknown chat has none of.
+ */
+function adoptAddressedChat(
+  chats: NativeChats,
+  action: string,
+  body: Record<string, unknown>,
+  chatId: number,
+): ChatEntry | undefined {
+  if (action !== "send_message") return undefined;
+  const key = typeof body.target === "string" ? body.target : "";
+  if (!key || !isNativeChatId(key) || deriveNumericChatId(key) !== chatId)
+    return undefined;
+  return chats.ensure(key);
+}
+
 export function createNativeActionHandler(
   deps: NativeActionDeps,
 ): FrontendActionHandler {
@@ -77,7 +103,9 @@ export function createNativeActionHandler(
   return async (body, chatId): Promise<ActionResult | null> => {
     const action = typeof body.action === "string" ? body.action : "";
     if (!NATIVE_ACTIONS.has(action)) return null;
-    const entry = chats.byNumeric(chatId);
+    const entry =
+      chats.byNumeric(chatId) ??
+      adoptAddressedChat(chats, action, body, chatId);
     if (!entry) return { ok: false, error: "No active native chat" };
 
     switch (action) {

package/src/frontend/telegram/commands/backup.ts

@@ -166,6 +166,7 @@ export async function stageRestore(chatId: string, id: string): Promise<void> {
     id,
     requestedAt: Date.now(),
     requestedBy: chatId,
+    frontend: "telegram",
   });
   respawnSelf(`telegram /backup restore ${id}`);
 }