talon-agent 5.2.2 → 5.3.0

package/src/cli/index.ts

@@ -14,6 +14,8 @@
  *   - `chat`        — terminal chat mode
  *   - `daemon`      — start/stop/restart outcome rendering
  *   - `menu`        — interactive main menu (no-subcommand default)
+ *   - `commands/`   — one module per command; new commands land here
+ *                     (docs/structure.md worklist item 8)
  */
 
 import pc from "picocolors";
@@ -36,6 +38,7 @@ import { runPluginCommand } from "./plugin.js";
 import { runSkillCommand } from "./skill.js";
 import { runMemoryCommand } from "./memory.js";
 import { mainMenu } from "./menu.js";
+import { runBackupCommand } from "./commands/backup.js";
 
 export * from "./context.js";
 export * from "./config.js";
@@ -58,8 +61,63 @@ const CLI_COMMANDS = [
   "plugin",
   "skill",
   "memory",
+  "backup",
 ];
 
+/** `talon events [-f] [--history [N]]` → the tail options. */
+function eventsOptions(args: string[]): {
+  follow: boolean;
+  history?: number;
+} {
+  const historyAt = args.findIndex((a) => a === "--history");
+  const next = historyAt >= 0 ? Number(args[historyAt + 1]) : NaN;
+  return {
+    follow: args.includes("-f") || args.includes("--follow"),
+    ...(historyAt >= 0
+      ? { history: Number.isInteger(next) && next > 0 ? next : 100 }
+      : {}),
+  };
+}
+
+/** The `talon --help` sheet. Its own function: `runCli` is a router. */
+function printHelp(): void {
+  printBanner();
+  console.log("  Usage: talon [command]\n");
+  console.log("  Commands:");
+  console.log(`    ${pc.cyan("setup")}      Guided setup wizard`);
+  console.log(`    ${pc.cyan("start")}      Start as background daemon`);
+  console.log(`    ${pc.cyan("stop")}       Stop the daemon`);
+  console.log(`    ${pc.cyan("restart")}    Restart the daemon`);
+  console.log(`    ${pc.cyan("run")}        Run in foreground (attached)`);
+  console.log(`    ${pc.cyan("chat")}       Terminal chat mode`);
+  console.log(`    ${pc.cyan("status")}     Show bot health`);
+  console.log(
+    `    ${pc.cyan("ps")}         List agent tasks (--all includes journal history)`,
+  );
+  console.log(`    ${pc.cyan("kill")}       Abort a killable task by id`);
+  console.log(
+    `    ${pc.cyan("events")}     Tail the event bus (-f follows, --history [N] reads the journal)`,
+  );
+  console.log(
+    `    ${pc.cyan("plugin")}     Manage plugins (install/enable/disable)`,
+  );
+  console.log(
+    `    ${pc.cyan("skill")}      Manage skills (install/enable/disable)`,
+  );
+  console.log(
+    `    ${pc.cyan("memory")}     Read/edit the memory store (list/search/import/render)`,
+  );
+  console.log(
+    `    ${pc.cyan("backup")}     Snapshots and checkpoints (now/list/show/pin/restore)`,
+  );
+  console.log(`    ${pc.cyan("config")}     View/edit configuration`);
+  console.log(`    ${pc.cyan("logs")}       Tail log file`);
+  console.log(`    ${pc.cyan("doctor")}     Validate environment`);
+  console.log(`    ${pc.cyan("--version")}  Print the package version`);
+  console.log();
+  console.log(`  Run ${pc.cyan("talon")} with no args for interactive menu.\n`);
+}
+
 /** Route a `talon <command>` invocation. Called by the entry point. */
 export async function runCli(): Promise<void> {
   const command = process.argv[2];
@@ -105,18 +163,12 @@ export async function runCli(): Promise<void> {
     case "kill":
       await killTask(process.argv[3]);
       break;
-    case "events": {
-      const args = process.argv.slice(3);
-      const historyAt = args.findIndex((a) => a === "--history");
-      const next = historyAt >= 0 ? Number(args[historyAt + 1]) : NaN;
-      await showEvents({
-        follow: args.includes("-f") || args.includes("--follow"),
-        ...(historyAt >= 0
-          ? { history: Number.isInteger(next) && next > 0 ? next : 100 }
-          : {}),
-      });
+    case "events":
+      await showEvents(eventsOptions(process.argv.slice(3)));
+      break;
+    case "backup":
+      await runBackupCommand(process.argv.slice(3));
       break;
-    }
     case "plugin":
       await runPluginCommand(process.argv.slice(3));
       break;
@@ -133,40 +185,7 @@ export async function runCli(): Promise<void> {
     }
     case "--help":
     case "-h":
-      printBanner();
-      console.log("  Usage: talon [command]\n");
-      console.log("  Commands:");
-      console.log(`    ${pc.cyan("setup")}      Guided setup wizard`);
-      console.log(`    ${pc.cyan("start")}      Start as background daemon`);
-      console.log(`    ${pc.cyan("stop")}       Stop the daemon`);
-      console.log(`    ${pc.cyan("restart")}    Restart the daemon`);
-      console.log(`    ${pc.cyan("run")}        Run in foreground (attached)`);
-      console.log(`    ${pc.cyan("chat")}       Terminal chat mode`);
-      console.log(`    ${pc.cyan("status")}     Show bot health`);
-      console.log(
-        `    ${pc.cyan("ps")}         List agent tasks (--all includes journal history)`,
-      );
-      console.log(`    ${pc.cyan("kill")}       Abort a killable task by id`);
-      console.log(
-        `    ${pc.cyan("events")}     Tail the event bus (-f follows, --history [N] reads the journal)`,
-      );
-      console.log(
-        `    ${pc.cyan("plugin")}     Manage plugins (install/enable/disable)`,
-      );
-      console.log(
-        `    ${pc.cyan("skill")}      Manage skills (install/enable/disable)`,
-      );
-      console.log(
-        `    ${pc.cyan("memory")}     Read/edit the memory store (list/search/import/render)`,
-      );
-      console.log(`    ${pc.cyan("config")}     View/edit configuration`);
-      console.log(`    ${pc.cyan("logs")}       Tail log file`);
-      console.log(`    ${pc.cyan("doctor")}     Validate environment`);
-      console.log(`    ${pc.cyan("--version")}  Print the package version`);
-      console.log();
-      console.log(
-        `  Run ${pc.cyan("talon")} with no args for interactive menu.\n`,
-      );
+      printHelp();
       break;
     case undefined:
       mainMenu();

package/src/core/backup/archive/digest.ts

@@ -0,0 +1,77 @@
+/**
+ * Digests — what makes a snapshot verifiable and the palace part reusable.
+ *
+ * Two jobs:
+ *   - `Sha256Tap` sits in the write pipeline and hashes the COMPRESSED
+ *     bytes on their way to disk, so the manifest's sha256 is produced
+ *     without a second pass over a multi-GB part. The restore path checks
+ *     the same digest before it unpacks anything.
+ *   - `treeHash` fingerprints a directory (path + size + mtime + content
+ *     digest of every file) so an unchanged memory palace can be carried
+ *     forward from the previous snapshot instead of recompressed and
+ *     re-uploaded every six hours.
+ */
+
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { Transform, type TransformCallback } from "node:stream";
+
+/** Pass-through stream that hashes (and counts) everything crossing it. */
+export class Sha256Tap extends Transform {
+  private readonly hash = createHash("sha256");
+  private digested: string | null = null;
+  private seen = 0;
+
+  override _transform(
+    chunk: Buffer,
+    _encoding: BufferEncoding,
+    done: TransformCallback,
+  ): void {
+    this.hash.update(chunk);
+    this.seen += chunk.length;
+    done(null, chunk);
+  }
+
+  /** Hex digest of everything written. Valid once the stream has finished. */
+  digest(): string {
+    if (this.digested === null) this.digested = this.hash.digest("hex");
+    return this.digested;
+  }
+
+  /** Bytes seen so far — the part's size, without a stat() race. */
+  get byteLength(): number {
+    return this.seen;
+  }
+}
+
+/** Streaming sha256 of a file on disk. */
+export async function sha256File(path: string): Promise<string> {
+  const hash = createHash("sha256");
+  for await (const chunk of createReadStream(path))
+    hash.update(chunk as Buffer);
+  return hash.digest("hex");
+}
+
+/** One file's identity inside a tree fingerprint. */
+export type TreeFile = {
+  /** Path relative to the tree root, POSIX separators. */
+  path: string;
+  size: number;
+  /** Modification time in epoch SECONDS (tar's resolution — stable). */
+  mtime: number;
+  sha256: string;
+};
+
+/**
+ * Fingerprint a set of files. Sorted by path so the value depends on the
+ * content of the tree and not on readdir order.
+ */
+export function treeHash(files: readonly TreeFile[]): string {
+  const hash = createHash("sha256");
+  for (const file of [...files].sort((a, b) =>
+    a.path < b.path ? -1 : a.path > b.path ? 1 : 0,
+  )) {
+    hash.update(`${file.path}\0${file.size}\0${file.mtime}\0${file.sha256}\n`);
+  }
+  return hash.digest("hex");
+}