talon-agent 5.2.1 → 5.3.0

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

@@ -0,0 +1,203 @@
+/**
+ * /backup — snapshots and checkpoints (admin only), the Discord half.
+ *
+ * Same surface as Telegram's /backup: status, now, checkpoint, list,
+ * pin/unpin, restore. Restore is behind a button (`backup:restore:<id>`)
+ * because it replaces the database, memory and identity of a running
+ * agent — and even then it does not restore in place: the request is
+ * staged to ~/.talon/restore-pending.json and applied by the next boot,
+ * before anything opens the database.
+ *
+ * The button handler lives here rather than under callbacks/components/
+ * so the whole command — prompt, confirmation and staging — reads as one
+ * file.
+ */
+
+import {
+  ActionRowBuilder,
+  ButtonBuilder,
+  ButtonStyle,
+  MessageFlags,
+  type ChatInputCommandInteraction,
+} from "discord.js";
+import {
+  collectBackupStatus,
+  formatBackupStatus,
+  formatSnapshotList,
+  isSnapshotId,
+  listSnapshots,
+  readManifest,
+  runBackup,
+  setSnapshotPinned,
+  writeRestorePending,
+} from "../../../core/backup/index.js";
+import { respawnSelf } from "../../../core/daemon/respawn.js";
+import { logError } from "../../../util/log.js";
+import { escapeForCodeBlock } from "../formatting.js";
+import { isAdmin } from "../handlers/index.js";
+import type { ComponentInteraction } from "../callbacks/components/types.js";
+import { reply } from "./interaction.js";
+
+function block(text: string): string {
+  return `\`\`\`\n${escapeForCodeBlock(text)}\n\`\`\``;
+}
+
+function confirmRow(id: string): ActionRowBuilder<ButtonBuilder> {
+  return new ActionRowBuilder<ButtonBuilder>().addComponents(
+    new ButtonBuilder()
+      .setCustomId(`backup:restore:${id}`)
+      .setLabel("Restore and restart")
+      .setStyle(ButtonStyle.Danger),
+    new ButtonBuilder()
+      .setCustomId("backup:cancel")
+      .setLabel("Cancel")
+      .setStyle(ButtonStyle.Secondary),
+  );
+}
+
+async function takeSnapshot(
+  i: ChatInputCommandInteraction,
+  label?: string,
+): Promise<void> {
+  await i.deferReply({ flags: MessageFlags.Ephemeral });
+  try {
+    const manifest = await runBackup({
+      kind: label ? "checkpoint" : "backup",
+      label,
+      pinned: Boolean(label),
+      trigger: "command",
+    });
+    await i.editReply(
+      `✅ \`${manifest.id}\` — ${manifest.parts.length} part(s), ` +
+        `${(manifest.sizeBytes / 1024 / 1024).toFixed(1)} MB` +
+        (label ? " (pinned)" : ""),
+    );
+  } catch (err) {
+    logError("backup", "/backup now failed", err);
+    await i.editReply(
+      `⚠️ Backup failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}
+
+async function askToRestore(
+  i: ChatInputCommandInteraction,
+  id: string,
+): Promise<void> {
+  if (!isSnapshotId(id)) {
+    await reply(i, "That is not a snapshot id.", true);
+    return;
+  }
+  const manifest = await readManifest(id);
+  if (!manifest) {
+    await reply(i, `No snapshot \`${id}\` on this machine.`, true);
+    return;
+  }
+  await i.reply({
+    content:
+      `♻️ **Restore \`${id}\`?**\n` +
+      (manifest.label ? `“${manifest.label}”\n` : "") +
+      `Taken ${new Date(manifest.createdAt).toISOString()}\n\n` +
+      "This replaces config, prompts, keys, sessions, the database and memory, " +
+      "then restarts. A pinned checkpoint of the current state is taken first.",
+    components: [confirmRow(id).toJSON()],
+    flags: MessageFlags.Ephemeral,
+  });
+}
+
+/** `/backup <subcommand> [arg]`. */
+export async function handleBackup(
+  i: ChatInputCommandInteraction,
+): Promise<void> {
+  if (!isAdmin(i.user.id)) {
+    await reply(i, "Not authorized.", true);
+    return;
+  }
+  const subcommand = i.options.getString("command") ?? "status";
+  const argument = (i.options.getString("arg") ?? "").trim();
+  switch (subcommand) {
+    case "now":
+      await takeSnapshot(i);
+      return;
+    case "checkpoint":
+      if (!argument) {
+        await reply(i, "Give the checkpoint a label.", true);
+        return;
+      }
+      await takeSnapshot(i, argument);
+      return;
+    case "list":
+      await reply(i, block(formatSnapshotList(await listSnapshots())), true);
+      return;
+    case "pin":
+    case "unpin": {
+      if (!isSnapshotId(argument)) {
+        await reply(i, "That is not a snapshot id.", true);
+        return;
+      }
+      const ok = await setSnapshotPinned(argument, subcommand === "pin");
+      await reply(
+        i,
+        ok
+          ? `${subcommand === "pin" ? "📌 Pinned" : "Unpinned"} \`${argument}\``
+          : `No snapshot \`${argument}\``,
+        true,
+      );
+      return;
+    }
+    case "restore":
+      await askToRestore(i, argument);
+      return;
+    default:
+      await reply(
+        i,
+        block(formatBackupStatus(await collectBackupStatus())),
+        true,
+      );
+  }
+}
+
+/**
+ * `backup:*` buttons. Returns false for ids this does not own, the way
+ * every component handler does, so a stale button is acked not answered.
+ */
+export async function handleBackupComponent(
+  interaction: ComponentInteraction,
+): Promise<boolean> {
+  const [prefix, action, id] = interaction.customId.split(":");
+  if (prefix !== "backup") return false;
+  if (!isAdmin(interaction.user.id)) {
+    await interaction.update({ content: "Not authorized.", components: [] });
+    return true;
+  }
+  if (action === "cancel") {
+    await interaction.update({ content: "Restore cancelled.", components: [] });
+    return true;
+  }
+  if (action !== "restore" || !id || !isSnapshotId(id)) return false;
+  await interaction.update({
+    content:
+      `♻️ Restoring \`${id}\` — restarting now. The restore is applied during ` +
+      "boot; I will report back when I am up.",
+    components: [],
+  });
+  try {
+    const chatId = interaction.guildId
+      ? `discord_guild_${interaction.guildId}_${interaction.channelId}`
+      : `discord_dm_${interaction.user.id}`;
+    await writeRestorePending({
+      id,
+      requestedAt: Date.now(),
+      requestedBy: chatId,
+    });
+    respawnSelf(`discord /backup restore ${id}`);
+  } catch (err) {
+    logError("backup", "Staging the restore failed", err);
+    await interaction
+      .editReply({
+        content: `⚠️ Could not stage the restore: ${err instanceof Error ? err.message : String(err)}`,
+      })
+      .catch(() => {});
+  }
+  return true;
+}

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

@@ -17,6 +17,40 @@ import type { TalonConfig } from "../../../core/config/index.js";
 import { log, logError, logWarn } from "../../../util/log.js";
 import { getRepoRoot } from "../../../core/update/self-update.js";
 
+/**
+ * /backup — its own builder: the definitions list is one long literal and
+ * this is the only entry with two options and seven choices.
+ */
+function backupCommand(): unknown {
+  return new SlashCommandBuilder()
+    .setName("backup")
+    .setDescription("Snapshots and checkpoints (admin only)")
+    .addStringOption((o) =>
+      o
+        .setName("command")
+        .setDescription("What to do (default: status)")
+        .setRequired(false)
+        .addChoices(
+          { name: "status", value: "status" },
+          { name: "now", value: "now" },
+          { name: "checkpoint", value: "checkpoint" },
+          { name: "list", value: "list" },
+          { name: "pin", value: "pin" },
+          { name: "unpin", value: "unpin" },
+          { name: "restore", value: "restore" },
+        ),
+    )
+    .addStringOption((o) =>
+      o
+        .setName("arg")
+        .setDescription(
+          "Checkpoint label, or snapshot id for pin/unpin/restore",
+        )
+        .setRequired(false),
+    )
+    .toJSON();
+}
+
 function buildCommandDefinitions(devBuild = false): unknown[] {
   return [
     new SlashCommandBuilder()
@@ -125,6 +159,7 @@ function buildCommandDefinitions(devBuild = false): unknown[] {
             .toJSON(),
         ]
       : []),
+    backupCommand(),
     new SlashCommandBuilder()
       .setName("admin")
       .setDescription("Admin operations (admin only)")

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

@@ -37,6 +37,7 @@ import {
   handlePulse,
   handleSettings,
 } from "./settings.js";
+import { handleBackup } from "./backup.js";
 import {
   handleRestart,
   handleMetrics,
@@ -160,6 +161,8 @@ async function routeSlashCommand(
       return handleMesh(interaction);
     case "update":
       return handleUpdate(interaction, config);
+    case "backup":
+      return handleBackup(interaction);
     case "admin":
       return handleAdmin(interaction, config, gateway);
     default:

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

@@ -0,0 +1,55 @@
+/**
+ * `backup:*` callbacks — the /backup restore confirmation.
+ *
+ *   backup:restore:<id>  stage the restore and restart
+ *   backup:cancel        do nothing, say so
+ *
+ * The button is the whole safety mechanism: a restore replaces the
+ * database, the memory and the identity of a running agent, so nothing
+ * here happens without a second, explicit admin tap.
+ */
+
+import type { Context } from "grammy";
+import { isSnapshotId } from "../../../core/backup/index.js";
+import { stageRestore } from "../commands/backup.js";
+import { isAuthorizedAdmin } from "../commands/state.js";
+import { logError } from "../../../util/log.js";
+import { answerCallbackQuerySafe } from "./query.js";
+
+export async function handleBackupCallback(
+  ctx: Context,
+  data: string,
+): Promise<void> {
+  if (!isAuthorizedAdmin(ctx)) {
+    await answerCallbackQuerySafe(ctx, { text: "Not authorized." });
+    return;
+  }
+  const [, action, id] = data.split(":");
+  if (action === "cancel") {
+    await answerCallbackQuerySafe(ctx, { text: "Cancelled." });
+    await ctx.editMessageText("Restore cancelled.").catch(() => {});
+    return;
+  }
+  if (action !== "restore" || !id || !isSnapshotId(id)) {
+    await answerCallbackQuerySafe(ctx, { text: "Invalid callback data" });
+    return;
+  }
+  await answerCallbackQuerySafe(ctx, { text: "Restoring…" });
+  await ctx
+    .editMessageText(
+      `♻️ Restoring <code>${id}</code> — restarting now. ` +
+        "The restore is applied during boot; I will report back when I am up.",
+      { parse_mode: "HTML" },
+    )
+    .catch(() => {});
+  try {
+    await stageRestore(String(ctx.chat?.id ?? ctx.from?.id ?? ""), id);
+  } catch (err) {
+    logError("backup", "Staging the restore failed", err);
+    await ctx
+      .editMessageText(
+        `⚠️ Could not stage the restore: ${err instanceof Error ? err.message : String(err)}`,
+      )
+      .catch(() => {});
+  }
+}

package/src/frontend/telegram/callbacks/index.ts

@@ -11,6 +11,7 @@
  *   - `model`    — `model:*` (menu / backend / browse controller)
  *   - `auth`     — `auth:*` (backend sign-in panel, admin only)
  *   - `whatsapp` — `whatsapp:*` (WhatsApp link panel, admin only)
+ *   - `backup`   — `backup:*` (restore confirmation, admin only)
  *
  * `registerCallbacks` installs one `callback_query:data` listener that
  * dispatches on the data prefix, preserving the original order and the
@@ -29,6 +30,7 @@ import { handleMetricsCallback } from "./metrics.js";
 import { handleModelCallback } from "./model.js";
 import { handleAuthCallback } from "./auth.js";
 import { handleWhatsAppCallback } from "./whatsapp.js";
+import { handleBackupCallback } from "./backup.js";
 
 export { answerCallbackQuerySafe } from "./query.js";
 
@@ -50,6 +52,12 @@ export function registerCallbacks(
       return;
     }
 
+    // Restore confirmation — destructive, so it is behind its own tap.
+    if (data.startsWith("backup:")) {
+      await handleBackupCallback(ctx, data);
+      return;
+    }
+
     // Handle pulse callbacks
     if (data.startsWith("pulse:")) {
       await handlePulseCallback(ctx, data, cid);

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

@@ -0,0 +1,209 @@
+/**
+ * /backup — the snapshot panel (admin only).
+ *
+ *   /backup                    status: schedule, sizes, targets
+ *   /backup now                take a snapshot now
+ *   /backup checkpoint <label> take a labelled, pinned-on-request snapshot
+ *   /backup list               recent snapshots
+ *   /backup pin|unpin <id>     keep past retention, or release
+ *   /backup restore <id>       confirm button → staged restore + restart
+ *
+ * Restore is the only destructive one, so it is the only one behind a
+ * button. It does not restore in place: a running daemon holds the
+ * database it would replace, so the request is staged to
+ * ~/.talon/restore-pending.json and applied by the next boot before
+ * anything opens the database (see core/backup/restore.ts).
+ */
+
+import type { Bot, Context } from "grammy";
+import {
+  collectBackupStatus,
+  formatBackupStatus,
+  formatSnapshotList,
+  isSnapshotId,
+  listSnapshots,
+  readManifest,
+  runBackup,
+  setSnapshotPinned,
+  writeRestorePending,
+} from "../../../core/backup/index.js";
+import { respawnSelf } from "../../../core/daemon/respawn.js";
+import { escapeHtml } from "../formatting.js";
+import { logError } from "../../../util/log.js";
+import { isAuthorizedAdmin } from "./state.js";
+
+const HELP = [
+  "<b>/backup</b> — snapshots and checkpoints",
+  "",
+  "<code>/backup</code> — status",
+  "<code>/backup now</code> — take a snapshot",
+  "<code>/backup checkpoint &lt;label&gt;</code> — labelled checkpoint",
+  "<code>/backup list</code> — recent snapshots",
+  "<code>/backup pin &lt;id&gt;</code> · <code>/backup unpin &lt;id&gt;</code>",
+  "<code>/backup restore &lt;id&gt;</code> — restore (asks to confirm, then restarts)",
+].join("\n");
+
+function pre(text: string): string {
+  return `<pre>${escapeHtml(text)}</pre>`;
+}
+
+async function sendStatus(ctx: Context): Promise<void> {
+  const status = await collectBackupStatus();
+  await ctx.reply(pre(formatBackupStatus(status)), { parse_mode: "HTML" });
+}
+
+async function sendList(ctx: Context): Promise<void> {
+  const snapshots = await listSnapshots();
+  await ctx.reply(pre(formatSnapshotList(snapshots)), { parse_mode: "HTML" });
+}
+
+async function takeSnapshot(ctx: Context, label?: string): Promise<void> {
+  const sent = await ctx.reply(
+    label
+      ? `📸 Taking checkpoint “${escapeHtml(label)}”…`
+      : "📸 Taking a snapshot…",
+    { parse_mode: "HTML" },
+  );
+  try {
+    const manifest = await runBackup({
+      kind: label ? "checkpoint" : "backup",
+      label,
+      pinned: Boolean(label),
+      trigger: "command",
+    });
+    await ctx.api.editMessageText(
+      ctx.chat!.id,
+      sent.message_id,
+      `✅ <code>${escapeHtml(manifest.id)}</code> — ${manifest.parts.length} part(s), ` +
+        `${(manifest.sizeBytes / 1024 / 1024).toFixed(1)} MB` +
+        (label ? " (pinned)" : ""),
+      { parse_mode: "HTML" },
+    );
+  } catch (err) {
+    logError("backup", "/backup now failed", err);
+    await ctx.api.editMessageText(
+      ctx.chat!.id,
+      sent.message_id,
+      `⚠️ Backup failed: ${escapeHtml(err instanceof Error ? err.message : String(err))}`,
+      { parse_mode: "HTML" },
+    );
+  }
+}
+
+async function setPinned(
+  ctx: Context,
+  id: string,
+  pinned: boolean,
+): Promise<void> {
+  if (!isSnapshotId(id)) {
+    await ctx.reply("That is not a snapshot id.");
+    return;
+  }
+  const ok = await setSnapshotPinned(id, pinned);
+  await ctx.reply(
+    ok
+      ? `${pinned ? "📌 Pinned" : "Unpinned"} <code>${escapeHtml(id)}</code>`
+      : `No snapshot <code>${escapeHtml(id)}</code>`,
+    { parse_mode: "HTML" },
+  );
+}
+
+/** The confirmation prompt. The button carries the id; nothing happens yet. */
+async function askToRestore(ctx: Context, id: string): Promise<void> {
+  if (!isSnapshotId(id)) {
+    await ctx.reply("That is not a snapshot id.");
+    return;
+  }
+  const manifest = await readManifest(id);
+  if (!manifest) {
+    await ctx.reply(
+      `No snapshot <code>${escapeHtml(id)}</code> on this machine.`,
+      {
+        parse_mode: "HTML",
+      },
+    );
+    return;
+  }
+  await ctx.reply(
+    `♻️ <b>Restore <code>${escapeHtml(id)}</code>?</b>\n` +
+      (manifest.label ? `“${escapeHtml(manifest.label)}”\n` : "") +
+      `Taken ${new Date(manifest.createdAt).toISOString()}\n\n` +
+      "This replaces config, prompts, keys, sessions, the database and memory, " +
+      "then restarts. A pinned checkpoint of the current state is taken first.",
+    {
+      parse_mode: "HTML",
+      reply_markup: {
+        inline_keyboard: [
+          [
+            {
+              text: "♻️ Restore and restart",
+              callback_data: `backup:restore:${id}`,
+            },
+            { text: "Cancel", callback_data: "backup:cancel" },
+          ],
+        ],
+      },
+    },
+  );
+}
+
+/**
+ * Stage the restore and hand off to the successor. Called by the
+ * confirmation button — see callbacks/backup.ts.
+ */
+export async function stageRestore(chatId: string, id: string): Promise<void> {
+  await writeRestorePending({
+    id,
+    requestedAt: Date.now(),
+    requestedBy: chatId,
+  });
+  respawnSelf(`telegram /backup restore ${id}`);
+}
+
+export function registerBackupCommand(bot: Bot): void {
+  bot.command("backup", async (ctx) => {
+    if (!isAuthorizedAdmin(ctx)) {
+      await ctx.reply("Not authorized.");
+      return;
+    }
+    const [subcommand, ...rest] = (ctx.match ?? "")
+      .trim()
+      .split(/\s+/)
+      .filter(Boolean);
+    switch (subcommand) {
+      case undefined:
+      case "status":
+        await sendStatus(ctx);
+        return;
+      case "now":
+        await takeSnapshot(ctx);
+        return;
+      case "checkpoint": {
+        const label = rest.join(" ").trim();
+        if (!label) {
+          await ctx.reply(
+            "Give the checkpoint a label: <code>/backup checkpoint before the rewrite</code>",
+            {
+              parse_mode: "HTML",
+            },
+          );
+          return;
+        }
+        await takeSnapshot(ctx, label);
+        return;
+      }
+      case "list":
+        await sendList(ctx);
+        return;
+      case "pin":
+      case "unpin":
+        await setPinned(ctx, rest[0] ?? "", subcommand === "pin");
+        return;
+      case "restore":
+        await askToRestore(ctx, rest[0] ?? "");
+        return;
+      default:
+        await ctx.reply(HELP, { parse_mode: "HTML" });
+    }
+  });
+}

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

@@ -48,6 +48,10 @@ export const TELEGRAM_COMMANDS: ReadonlyArray<{
     command: "memory",
     description: "What Talon remembers — list, search, why <id>",
   },
+  {
+    command: "backup",
+    description: "Snapshots and checkpoints; /backup restore <id> (admin)",
+  },
   { command: "plugins", description: "List loaded plugins" },
   { command: "help", description: "All commands and features" },
 ];

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

@@ -26,6 +26,7 @@ import { registerSettingsCommands } from "./settings.js";
 import { registerAdminCommands } from "./admin.js";
 import { registerWhatsAppPairingCommand } from "./whatsapp-pairing.js";
 import { registerAuthCommand } from "./auth.js";
+import { registerBackupCommand } from "./backup.js";
 
 export { telegramCommandMenu } from "./definitions.js";
 export { setAdminUserId } from "./state.js";
@@ -42,6 +43,7 @@ export function registerCommands(
   registerSettingsCommands(bot, deps);
   registerWhatsAppPairingCommand(bot);
   registerAuthCommand(bot);
+  registerBackupCommand(bot);
   // admin LAST: it owns the unknown-command catch-all, which must only
   // be reached after every real command has had its chance to match.
   // Registering anything after it makes that command look unknown

package/src/index.ts

@@ -1,11 +1,13 @@
 /**
  * Talon entry shim.
  *
- * Dispatches the hidden `_mcp-launch` (MCP supervisor) and `_lua-run`
- * (WASM Lua trigger runner) subcommands BEFORE the app graph loads —
- * both are Talon re-invoking itself (see core/mcp-hub/launcher.ts). The
- * dynamic import keeps these helper processes light: they evaluate this
- * shim and their own module, never the backends/frontends/plugins.
+ * Dispatches the hidden `_mcp-launch` (MCP supervisor), `_lua-run`
+ * (WASM Lua trigger runner) and `_handoff-watch` (restart/update
+ * witness) subcommands BEFORE the app graph loads — all three are Talon
+ * re-invoking itself (see core/mcp-hub/launcher.ts, core/daemon/
+ * handoff.ts). The dynamic import keeps these helper processes light:
+ * they evaluate this shim and their own module, never the
+ * backends/frontends/plugins.
  */
 
 import {
@@ -13,11 +15,17 @@ import {
   runSupervisor,
 } from "./core/mcp-hub/launcher.js";
 import { LUA_RUN_SUBCOMMAND, runLuaMain } from "./core/scripts/lua.js";
+import {
+  HANDOFF_WATCH_SUBCOMMAND,
+  runHandoffWatch,
+} from "./core/daemon/handoff.js";
 
 if (process.argv[2] === MCP_LAUNCH_SUBCOMMAND) {
   await runSupervisor(process.argv.slice(3));
 } else if (process.argv[2] === LUA_RUN_SUBCOMMAND) {
   await runLuaMain(process.argv.slice(3));
+} else if (process.argv[2] === HANDOFF_WATCH_SUBCOMMAND) {
+  await runHandoffWatch(process.argv.slice(3));
 } else {
   await import("./app.js");
 }