talon-agent 5.2.2 → 5.3.0

package/src/core/backup/upload.ts

@@ -0,0 +1,172 @@
+/**
+ * Getting a snapshot off this machine — and keeping the remote tidy.
+ *
+ * Targets run in parallel (they are independent networks) but the parts
+ * of one snapshot go up sequentially, manifest last. That order is the
+ * completeness marker: a remote snapshot with no manifest.json is an
+ * interrupted upload, and nothing will ever mistake it for a restorable
+ * backup.
+ *
+ * One target failing is not a failed backup. The snapshot is already on
+ * local disk by the time we get here, so a target that errors records
+ * `failed` with its reason and the run carries on — the next run retries
+ * it. The manifest keeps the per-target state alongside the parts, so a
+ * snapshot restored onto a new machine still knows where its copies are.
+ */
+
+import { bus } from "../bus/index.js";
+import { log, logWarn } from "../../util/log.js";
+import { dirs } from "../../util/paths.js";
+import {
+  deleteBackupRemote,
+  recordBackupRemote,
+} from "../../storage/backup/index.js";
+import {
+  partPath,
+  reindexSnapshot,
+  selectPrunable,
+  writeManifest,
+} from "./store.js";
+import type { BackupTarget } from "./targets.js";
+import type { Manifest, RemoteState } from "./types.js";
+
+function recordState(id: string, targetId: string, state: RemoteState): void {
+  recordBackupRemote({
+    backupId: id,
+    targetId,
+    status: state.status,
+    remoteId: state.remoteId,
+    uploadedAt: state.uploadedAt,
+    error: state.error,
+  });
+}
+
+/** Push every part, then the manifest. Throws with the target's own words. */
+async function sendSnapshot(
+  target: BackupTarget,
+  manifest: Manifest,
+  home: string,
+): Promise<{ state: RemoteState; deduplicated: boolean }> {
+  let deduplicated = manifest.parts.length > 0;
+  for (const part of manifest.parts) {
+    const result = await target.upload(
+      manifest.id,
+      { ...part, path: partPath(manifest.id, part.name, home) },
+      manifest,
+    );
+    if (!result.deduplicated) deduplicated = false;
+  }
+  const { remoteId } = await target.uploadManifest(manifest.id, manifest);
+  return {
+    state: { status: "uploaded", remoteId, uploadedAt: Date.now() },
+    deduplicated,
+  };
+}
+
+/**
+ * Upload one snapshot to every target. Returns the manifest with its
+ * `remote` map filled in; it is rewritten on disk and reindexed so the
+ * status surfaces can answer without asking the network.
+ */
+export async function uploadSnapshot(
+  manifest: Manifest,
+  targets: readonly BackupTarget[],
+  home: string = dirs.root,
+): Promise<Manifest> {
+  if (targets.length === 0) return manifest;
+  await Promise.all(
+    targets.map(async (target) => {
+      if (!target.ready) {
+        const state: RemoteState = {
+          status: "pending",
+          error: target.detail ?? "target not ready",
+        };
+        manifest.remote[target.id] = state;
+        recordState(manifest.id, target.id, state);
+        logWarn("backup", `Target ${target.id} not ready: ${state.error}`);
+        return;
+      }
+      try {
+        const { state, deduplicated } = await sendSnapshot(
+          target,
+          manifest,
+          home,
+        );
+        manifest.remote[target.id] = state;
+        recordState(manifest.id, target.id, state);
+        bus.publish({
+          type: "backup.uploaded",
+          snapshotId: manifest.id,
+          targetId: target.id,
+          bytes: manifest.sizeBytes,
+          deduplicated,
+        });
+        log(
+          "backup",
+          `Uploaded ${manifest.id} to ${target.id}${deduplicated ? " (deduplicated)" : ""}`,
+        );
+      } catch (err) {
+        const state: RemoteState = {
+          status: "failed",
+          error: err instanceof Error ? err.message : String(err),
+        };
+        manifest.remote[target.id] = state;
+        recordState(manifest.id, target.id, state);
+        logWarn("backup", `Upload to ${target.id} failed: ${state.error}`);
+      }
+    }),
+  );
+  await writeManifest(manifest, home);
+  reindexSnapshot(manifest);
+  return manifest;
+}
+
+/**
+ * Apply the remote retention policy on each target. Same rule as local:
+ * the newest `keep` unpinned snapshots survive, pinned ones always do.
+ * A target that cannot list is skipped — deleting on a partial listing is
+ * how a retention pass turns into data loss.
+ */
+export async function pruneRemote(
+  targets: readonly BackupTarget[],
+  keep: number,
+): Promise<void> {
+  for (const target of targets) {
+    if (!target.ready) continue;
+    let snapshots;
+    try {
+      snapshots = await target.list();
+    } catch (err) {
+      logWarn(
+        "backup",
+        `Cannot list ${target.id}, skipping remote prune: ${String(err)}`,
+      );
+      continue;
+    }
+    const doomed = selectPrunable(
+      snapshots.map((entry) => ({
+        id: entry.snapshotId,
+        createdAt: entry.manifest?.createdAt ?? 0,
+        pinned: entry.manifest?.pinned === true,
+      })),
+      keep,
+    );
+    for (const victim of doomed) {
+      try {
+        await target.remove(victim.id);
+        deleteBackupRemote(victim.id, target.id);
+      } catch (err) {
+        logWarn(
+          "backup",
+          `Could not delete ${victim.id} from ${target.id}: ${String(err)}`,
+        );
+      }
+    }
+    if (doomed.length > 0) {
+      log(
+        "backup",
+        `Pruned ${doomed.length} snapshot(s) from ${target.id} (keepRemote=${keep})`,
+      );
+    }
+  }
+}

package/src/core/bus/events.ts

@@ -15,6 +15,9 @@
  *     `agent.spawned` when an isolated sub-agent run starts, `agent.settled`
  *     when it reaches a terminal state, `agent.message` when a note or a
  *     report crosses between an agent and its parent.
+ *   - `backup.*` — the snapshot lifecycle, published by `core/backup`:
+ *     `backup.started` / `backup.completed` / `backup.failed` per run, and
+ *     `backup.uploaded` once per target a snapshot reaches.
  *   - `turn.*` — the chat-domain moments inside a turn that other
  *     subsystems key off: `turn.started` fires once the warp is bound and
  *     the backend is about to run (never for a no-model refusal);
@@ -91,6 +94,43 @@ interface AgentMessageEvent {
   readonly kind: "message" | "result";
 }
 
+/** A snapshot run began. `trigger` is what asked for it, never content. */
+interface BackupStartedEvent {
+  readonly type: "backup.started";
+  readonly kind: "backup" | "checkpoint";
+  /** "schedule", "manual", "pre-update", "pre-restore", … */
+  readonly trigger: string;
+}
+
+/** A snapshot was written and indexed. */
+interface BackupCompletedEvent {
+  readonly type: "backup.completed";
+  /** Not `id`: the bus stamps every published event with its own numeric id. */
+  readonly snapshotId: string;
+  readonly kind: "backup" | "checkpoint";
+  readonly sizeBytes: number;
+  readonly parts: number;
+  readonly durationMs: number;
+}
+
+/** A snapshot run failed. `error` is the reason, never a path's contents. */
+interface BackupFailedEvent {
+  readonly type: "backup.failed";
+  readonly trigger: string;
+  readonly error: string;
+  readonly consecutiveFailures: number;
+}
+
+/** One snapshot reached one remote target. */
+interface BackupUploadedEvent {
+  readonly type: "backup.uploaded";
+  readonly snapshotId: string;
+  readonly targetId: string;
+  readonly bytes: number;
+  /** True when the target already held every part (content-addressed reuse). */
+  readonly deduplicated: boolean;
+}
+
 export type TalonEvent =
   | TaskStartedEvent
   | TaskSettledEvent
@@ -98,7 +138,11 @@ export type TalonEvent =
   | TurnCompletedEvent
   | AgentSpawnedEvent
   | AgentSettledEvent
-  | AgentMessageEvent;
+  | AgentMessageEvent
+  | BackupStartedEvent
+  | BackupCompletedEvent
+  | BackupFailedEvent
+  | BackupUploadedEvent;
 
 export type TalonEventType = TalonEvent["type"];
 

package/src/core/config/index.ts

@@ -6,6 +6,7 @@ import { hardenTalonPermissions } from "./harden.js";
 import { setTimezone } from "../../util/time.js";
 import { BACKEND_IDS } from "../agent-runtime/model-ref.js";
 import { REASONING_LEVEL_ORDER } from "../models/reasoning-levels.js";
+import { DEFAULT_BACKUP_SETTINGS } from "../backup/plan.js";
 import {
   assembleSystemPrompt,
   joinSystemPromptParts,
@@ -458,6 +459,57 @@ const configSchema = z.object({
         .default(15 * 60 * 1000),
     })
     .optional(),
+  /**
+   * Backups & checkpoints (docs/backups.md). Talon's only safety net, so
+   * it is on by default: every `intervalHours` it writes a snapshot of
+   * the identity, state, database and memory under ~/.talon/backups/,
+   * keeps `keepLocal` of them, and uploads to whatever remote targets
+   * are registered (`targets: []` keeps everything local).
+   *
+   *   - `workspaceInclude` — the workspace is mostly bulk that can be
+   *     refetched; this is the subset that IS the agent.
+   *   - `extraPaths` — absolute or `~/…` paths outside ~/.talon worth
+   *     carrying along (a Claude Code memory directory, say).
+   *   - `checkpointBeforeUpdate` — pinned checkpoint before `/update`,
+   *     so a bad update is one restore away from undone.
+   *   - `notifyChatId` — where failures are reported; falls back to the
+   *     admin chat.
+   */
+  backup: z
+    .object({
+      enabled: z.boolean().default(DEFAULT_BACKUP_SETTINGS.enabled),
+      intervalHours: z
+        .number()
+        .int()
+        .min(1)
+        .max(168)
+        .default(DEFAULT_BACKUP_SETTINGS.intervalHours),
+      keepLocal: z
+        .number()
+        .int()
+        .min(1)
+        .max(1000)
+        .default(DEFAULT_BACKUP_SETTINGS.keepLocal),
+      keepRemote: z
+        .number()
+        .int()
+        .min(1)
+        .max(1000)
+        .default(DEFAULT_BACKUP_SETTINGS.keepRemote),
+      includePalace: z.boolean().default(DEFAULT_BACKUP_SETTINGS.includePalace),
+      workspaceInclude: z
+        .array(z.string().min(1))
+        .default([...DEFAULT_BACKUP_SETTINGS.workspaceInclude]),
+      extraPaths: z.array(z.string().min(1)).default([]),
+      /** Unset = every registered target; `[]` = local only. */
+      targets: z.array(z.string().min(1)).optional(),
+      checkpointBeforeUpdate: z
+        .boolean()
+        .default(DEFAULT_BACKUP_SETTINGS.checkpointBeforeUpdate),
+      notifyChatId: z.string().optional(),
+    })
+    .strict()
+    .optional(),
   braveApiKey: z.string().optional(),
   /**
    * Codex-specific OpenAI API key. Prefer this, CODEX_API_KEY, or

package/src/core/engine/gateway-actions/backup/index.ts

@@ -0,0 +1,129 @@
+/**
+ * Backup actions — the agent tools and the companion app's read surface.
+ *
+ * Two vocabularies over one subsystem. `create_checkpoint`,
+ * `list_checkpoints` and `backup_status` are the model's tools and answer
+ * in prose; `backup.status`, `backup.now` and `backup.list` are the
+ * companion app's and answer with structured fields beside the text.
+ *
+ * All of them are chat-free: a snapshot belongs to the daemon, not to a
+ * conversation, so the heartbeat and background runs can take one too.
+ *
+ * There is no restore action. Restoring replaces memory, database and
+ * identity underneath a running daemon — that is a decision for a human
+ * at a CLI or behind a confirmation button, never a tool call.
+ */
+
+import {
+  collectBackupStatus,
+  formatBackupStatus,
+  formatSnapshotList,
+  listSnapshots,
+  runBackup,
+} from "../../../backup/index.js";
+import { log } from "../../../../util/log.js";
+import type { SharedActionHandlers } from "../types.js";
+
+const DEFAULT_LIST_LIMIT = 20;
+
+function limitOf(
+  body: Record<string, unknown>,
+  fallback = DEFAULT_LIST_LIMIT,
+): number {
+  const raw = Number(body.limit);
+  return Number.isInteger(raw) && raw > 0 ? Math.min(raw, 100) : fallback;
+}
+
+async function takeCheckpoint(
+  label: string,
+  pinned: boolean,
+  trigger: string,
+): Promise<ReturnType<SharedActionHandlers[string]>> {
+  try {
+    const manifest = await runBackup({
+      kind: "checkpoint",
+      label,
+      pinned,
+      trigger,
+    });
+    log("gateway", `create_checkpoint: ${manifest.id} "${label}"`);
+    return {
+      ok: true,
+      id: manifest.id,
+      text:
+        `Checkpoint ${manifest.id} taken — "${label}"` +
+        (pinned ? " (pinned, never pruned)" : "") +
+        `\n${manifest.parts.length} part(s), ${(manifest.sizeBytes / 1024 / 1024).toFixed(1)} MB.` +
+        `\nRestore it with: talon backup restore ${manifest.id}`,
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      error: `Checkpoint failed: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+}
+
+export const backupHandlers: SharedActionHandlers = {
+  create_checkpoint: async (body) => {
+    const label = String(body.label ?? "").trim();
+    if (!label)
+      return { ok: false, error: "create_checkpoint: label is required" };
+    return takeCheckpoint(label, body.pin === true, "tool");
+  },
+
+  list_checkpoints: async (body) => {
+    const snapshots = await listSnapshots();
+    if (snapshots.length === 0) {
+      return {
+        ok: true,
+        text: "No snapshots yet. create_checkpoint takes one now.",
+        snapshots: [],
+      };
+    }
+    const limited = snapshots.slice(0, limitOf(body));
+    return {
+      ok: true,
+      text: formatSnapshotList(limited, limited.length),
+      snapshots: limited,
+    };
+  },
+
+  backup_status: async () => {
+    const status = await collectBackupStatus({ withTargets: false });
+    return { ok: true, text: formatBackupStatus(status) };
+  },
+
+  "backup.status": async () => {
+    const status = await collectBackupStatus();
+    return { ok: true, text: formatBackupStatus(status), status };
+  },
+
+  "backup.list": async (body) => {
+    const snapshots = (await listSnapshots()).slice(0, limitOf(body, 50));
+    return { ok: true, text: formatSnapshotList(snapshots), snapshots };
+  },
+
+  "backup.now": async (body) => {
+    const label = String(body.label ?? "").trim();
+    if (label) return takeCheckpoint(label, body.pin === true, "manual");
+    try {
+      const manifest = await runBackup({ kind: "backup", trigger: "manual" });
+      return {
+        ok: true,
+        id: manifest.id,
+        text: `Snapshot ${manifest.id} taken (${(manifest.sizeBytes / 1024 / 1024).toFixed(1)} MB).`,
+      };
+    } catch (err) {
+      return {
+        ok: false,
+        error: `Backup failed: ${err instanceof Error ? err.message : String(err)}`,
+      };
+    }
+  },
+};
+
+/** None of these need a chat — backups belong to the daemon. */
+export const backupChatFreeActions: ReadonlySet<string> = new Set(
+  Object.keys(backupHandlers),
+);

package/src/core/engine/gateway-actions/index.ts

@@ -21,6 +21,7 @@
  *   - `models`    — model / backend discovery
  *   - `mesh`      — companion device mesh (presence + location)
  *   - `cross-send` — explicit-target sends through any enabled frontend
+ *   - `backup`    — snapshots and checkpoints (chat-free; no restore)
  */
 
 import type { ActionResult } from "../../types.js";
@@ -47,6 +48,7 @@ import {
   whatsappAccountChatFreeActions,
 } from "./whatsapp-account.js";
 import { nativeHandlers } from "./native/index.js";
+import { backupChatFreeActions, backupHandlers } from "./backup/index.js";
 
 // Null-prototype so a request `action` of "toString" / "constructor" / etc.
 // can't resolve an inherited Object.prototype method — `handlers[action]` only
@@ -67,6 +69,7 @@ const handlers: SharedActionHandlers = Object.assign(Object.create(null), {
   ...crossSendHandlers,
   ...whatsappAccountHandlers,
   ...nativeHandlers,
+  ...backupHandlers,
 });
 
 /**
@@ -77,6 +80,7 @@ const chatFreeActions: ReadonlySet<string> = new Set([
   ...meshChatFreeActions,
   ...crossSendChatFreeActions,
   ...whatsappAccountChatFreeActions,
+  ...backupChatFreeActions,
 ]);
 
 /**

package/src/core/mcp-hub/talon-server.ts

@@ -16,7 +16,7 @@
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { composeTools } from "../tools/index.js";
-import { createBridge, textResult } from "../tools/ops/bridge.js";
+import { createBridge, textResult } from "../tools/bridge.js";
 import type { ToolFrontend, ToolTag } from "../tools/types.js";
 
 export const VALID_TOOL_FRONTENDS: ReadonlySet<string> = new Set([

package/src/core/plugin/actions.ts

@@ -2,6 +2,13 @@
  * Action routing — try a gateway action through every loaded plugin in load
  * order; first non-null result wins. Per-plugin errors are caught and surfaced
  * as error results rather than cascading.
+ *
+ * `handlePluginActionIn` is the addressed form: the backup subsystem asks
+ * each plugin in turn whether it is a remote target, and must then be able
+ * to send the follow-up uploads to THAT plugin. First-non-null routing
+ * cannot express "this one", and the wire protocol carries no plugin id —
+ * so the addressing lives here, on the core side, and the plugin-facing
+ * contract is unchanged.
  */
 
 import { logError } from "../../util/log.js";
@@ -30,3 +37,30 @@ export async function handlePluginAction(
   }
   return null;
 }
+
+/** Names of the loaded plugins that can answer gateway actions, in load order. */
+export function pluginsWithActions(): string[] {
+  return registry.all
+    .filter(({ plugin }) => plugin.handleAction !== undefined)
+    .map(({ plugin }) => plugin.name);
+}
+
+/**
+ * Run an action against one named plugin. Returns null when no plugin by
+ * that name is loaded or it does not recognise the action.
+ */
+export async function handlePluginActionIn(
+  name: string,
+  body: Record<string, unknown>,
+  chatId: string,
+): Promise<ActionResult | null> {
+  const entry = registry.all.find(({ plugin }) => plugin.name === name);
+  if (!entry?.plugin.handleAction) return null;
+  try {
+    return await entry.plugin.handleAction(body, chatId);
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    logError("plugin", `${name} action error: ${detail}`);
+    return { ok: false, error: `Plugin ${name}: ${detail}` };
+  }
+}

package/src/core/plugin/index.ts

@@ -23,5 +23,9 @@ export {
   getPluginPromptAdditions,
 } from "./loader.js";
 export { loadBuiltinPlugins, reloadPlugins } from "./builtins.js";
-export { handlePluginAction } from "./actions.js";
+export {
+  handlePluginAction,
+  handlePluginActionIn,
+  pluginsWithActions,
+} from "./actions.js";
 export { getPluginMcpServers } from "./mcp.js";

package/src/core/tools/{ops/bridge.ts → bridge.ts}

@@ -3,11 +3,16 @@
  *
  * Extracted from the old per-backend tools.ts files so there's
  * exactly one copy of callBridge / textResult.
+ *
+ * At the tools root, not in `ops/`: the group directories hold tool
+ * DOMAINS (one file per family of tool definitions), and this is the
+ * transport they all answer over — the same kind of module as
+ * `types.ts` and `schemas.ts` beside it.
  */
 
 import { Agent, fetch as undiciFetch } from "undici";
-import { isBunRuntime } from "../../../util/runtime.js";
-import type { BridgeFunction } from "../types.js";
+import { isBunRuntime } from "../../util/runtime.js";
+import type { BridgeFunction } from "./types.js";
 
 /** Default wall-clock budget for a bridge action. */
 const DEFAULT_TIMEOUT_MS = 120_000;

package/src/core/tools/index.ts

@@ -28,6 +28,7 @@ import { crossSendTools } from "./chat/cross-send.js";
 import { whatsappTools } from "./chat/whatsapp.js";
 import { moderationTools } from "./chat/moderation.js";
 import { nativeTools } from "./ops/native.js";
+import { backupTools } from "./ops/backup.js";
 
 /** All built-in tool definitions. */
 export const ALL_TOOLS: readonly ToolDefinition[] = [
@@ -54,6 +55,7 @@ export const ALL_TOOLS: readonly ToolDefinition[] = [
   // prefix, so a new family goes on the end or every live chat re-bills its
   // system prompt (see compose-tools.test.ts).
   ...agentTools,
+  ...backupTools,
 ];
 
 /**

package/src/core/tools/ops/backup.ts

@@ -0,0 +1,67 @@
+/**
+ * Backup tools — the agent's own access to its safety net.
+ *
+ * Three tools, and deliberately no fourth: there is no restore tool.
+ * Restoring replaces the agent's memory, database and identity while it
+ * is running, which is a decision for a human at a CLI or behind a
+ * confirmation button, not something a model should be able to reach for
+ * mid-turn. Taking a checkpoint, on the other hand, is cheap and always
+ * safe — so the agent is encouraged to do it before it changes itself.
+ */
+
+import { z } from "zod";
+import type { ToolDefinition } from "../types.js";
+
+export const backupTools: ToolDefinition[] = [
+  {
+    name: "create_checkpoint",
+    description: `Take a labelled snapshot of your whole state right now — config, prompts, keys, sessions, the database, your memory and skills, and the memory palace.
+
+Reach for this BEFORE you change yourself in a way you might want undone: editing identity.md, a big memory rewrite, a risky config change, installing or reconfiguring a plugin. It takes seconds and costs no tokens.
+
+Pin a checkpoint you want kept past the retention window (12 scheduled backups by default). Restoring is a human operation — 'talon backup restore <id>' or /backup restore <id> — so say the id in your reply if the checkpoint is the point of the turn.`,
+    schema: {
+      label: z
+        .string()
+        .min(1)
+        .max(80)
+        .describe(
+          "Why this checkpoint exists, in a few words ('before identity rewrite'). Shown in every listing.",
+        ),
+      pin: z
+        .boolean()
+        .optional()
+        .describe(
+          "Keep it forever — pinned checkpoints are never pruned by retention. Default false.",
+        ),
+    },
+    execute: (params, bridge) => bridge("create_checkpoint", params),
+    tag: "backup",
+  },
+
+  {
+    name: "list_checkpoints",
+    description:
+      "List recent snapshots — id, kind, label, size, whether pinned, and which remote targets hold a copy. Newest first. Use it to find the id of something you or the schedule took earlier.",
+    schema: {
+      limit: z
+        .number()
+        .int()
+        .positive()
+        .max(100)
+        .optional()
+        .describe("How many to return (default 20, max 100)."),
+    },
+    execute: (params, bridge) => bridge("list_checkpoints", params),
+    tag: "backup",
+  },
+
+  {
+    name: "backup_status",
+    description:
+      "Health of the backup subsystem: when the last snapshot ran and when the next one is due, how many snapshots exist locally and how big they are, which remote targets are registered and whether they are ready, and whether recent runs have been failing.",
+    schema: {},
+    execute: (_params, bridge) => bridge("backup_status", {}),
+    tag: "backup",
+  },
+];

package/src/core/tools/types.ts

@@ -31,7 +31,8 @@ export type ToolTag =
   | "models"
   | "mesh"
   | "moderation"
-  | "native";
+  | "native"
+  | "backup";
 
 /** The bridge caller signature — injected into execute(). */
 export type BridgeFunction = (

package/src/core/update/self-update.ts

@@ -30,6 +30,7 @@
  */
 
 import { execFile } from "node:child_process";
+import { checkpointBeforeUpdate } from "../backup/index.js";
 import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -248,6 +249,8 @@ export async function runSelfUpdate(
     return { ok: true, repoRoot, steps, before, after, changed: false };
   }
 
+  await checkpointBeforeUpdate(before, after);
+
   const install = await record(
     "npm install",
     "npm",

package/src/frontend/discord/callbacks/components/index.ts

@@ -18,6 +18,7 @@
  *   model:nav:*                 (pager)
  *   model:backend-select        (select menu)
  *   metrics:today | metrics:all
+ *   backup:restore:<id> | backup:cancel  (restore confirmation, admin only)
  *   ai:<id>                     (AI-generated buttons — forwarded to agent)
  */
 
@@ -36,6 +37,7 @@ import { handleMetricsComponent } from "./metrics.js";
 import { handleModelComponent } from "./model.js";
 import { handlePulseComponent } from "./pulse.js";
 import { handleSettingsComponent } from "./settings.js";
+import { handleBackupComponent } from "../../commands/backup.js";
 import type { ComponentHandlers, ComponentInteraction } from "./types.js";
 
 // Null-prototype so a custom id of "toString:" / "constructor:" / etc.
@@ -48,6 +50,7 @@ export const COMPONENT_HANDLERS: ComponentHandlers = Object.assign(
     "effort:": handleEffortComponent,
     "model:": handleModelComponent,
     "metrics:": handleMetricsComponent,
+    "backup:": handleBackupComponent,
     "ai:": forwardToAgent,
   } satisfies ComponentHandlers,
 );