stagent 0.6.2 → 0.7.0

package/src/lib/schedules/scheduler.ts

@@ -12,7 +12,7 @@
  */
 
 import { db } from "@/lib/db";
-import { schedules, tasks, agentLogs } from "@/lib/db/schema";
+import { schedules, tasks, agentLogs, scheduleDocumentInputs, documents } from "@/lib/db/schema";
 import { eq, and, lte, inArray, sql } from "drizzle-orm";
 import { computeNextFireTime } from "./interval-parser";
 import { executeTaskWithRuntime } from "@/lib/agents/runtime";
@@ -178,6 +178,21 @@ async function fireSchedule(
     updatedAt: now,
   });
 
+  // Link schedule's documents to the created task
+  try {
+    const schedDocs = await db
+      .select({ documentId: scheduleDocumentInputs.documentId })
+      .from(scheduleDocumentInputs)
+      .where(eq(scheduleDocumentInputs.scheduleId, schedule.id));
+    for (const { documentId } of schedDocs) {
+      await db.update(documents)
+        .set({ taskId, projectId: schedule.projectId, updatedAt: now })
+        .where(eq(documents.id, documentId));
+    }
+  } catch (err) {
+    console.error(`[scheduler] Document linking failed for schedule ${schedule.id}:`, err);
+  }
+
   // Update schedule counters
   const isOneShot = !schedule.recurs;
   const reachedMax =
@@ -335,6 +350,21 @@ async function fireHeartbeat(
     updatedAt: now,
   });
 
+  // Link schedule's documents to the heartbeat task
+  try {
+    const schedDocs = await db
+      .select({ documentId: scheduleDocumentInputs.documentId })
+      .from(scheduleDocumentInputs)
+      .where(eq(scheduleDocumentInputs.scheduleId, schedule.id));
+    for (const { documentId } of schedDocs) {
+      await db.update(documents)
+        .set({ taskId: evalTaskId, projectId: schedule.projectId, updatedAt: now })
+        .where(eq(documents.id, documentId));
+    }
+  } catch (err) {
+    console.error(`[scheduler] Document linking failed for heartbeat ${schedule.id}:`, err);
+  }
+
   // 5. Execute and wait for result (with timeout)
   try {
     await executeTaskWithRuntime(evalTaskId);

package/src/lib/snapshots/auto-backup.ts

@@ -0,0 +1,132 @@
+/**
+ * Auto-backup timer — creates snapshots on a user-configurable interval.
+ *
+ * Lifecycle:
+ *   - `startAutoBackup()` — call once at server boot (idempotent)
+ *   - `stopAutoBackup()`  — call on graceful shutdown
+ *   - `tickAutoBackup()`  — exposed for testing; runs one check cycle
+ *
+ * Each tick reads settings to check if auto-backup is enabled and whether
+ * enough time has elapsed since the last snapshot. This allows users to
+ * change settings without restarting the server.
+ */
+
+import { db } from "@/lib/db";
+import { snapshots } from "@/lib/db/schema";
+import { desc, eq } from "drizzle-orm";
+import { getSettingSync } from "@/lib/settings/helpers";
+import { parseInterval } from "@/lib/schedules/interval-parser";
+import { computeNextFireTime } from "@/lib/schedules/interval-parser";
+import { createSnapshot, isSnapshotLocked } from "./snapshot-manager";
+import { enforceRetention } from "./retention";
+
+// Check every 60 seconds whether an auto-backup is due
+const POLL_INTERVAL_MS = 60_000;
+
+let intervalHandle: ReturnType<typeof setInterval> | null = null;
+
+// Settings keys
+const SETTINGS = {
+  enabled: "snapshot.autoBackup.enabled",
+  interval: "snapshot.autoBackup.interval",
+  maxCount: "snapshot.retention.maxCount",
+  maxAgeWeeks: "snapshot.retention.maxAgeWeeks",
+} as const;
+
+/**
+ * Start the auto-backup timer. Safe to call multiple times.
+ */
+export function startAutoBackup(): void {
+  if (intervalHandle !== null) return;
+
+  console.log("[auto-backup] Starting auto-backup timer (60s poll)");
+  intervalHandle = setInterval(() => {
+    tickAutoBackup().catch((err) => {
+      console.error("[auto-backup] Tick error:", err);
+    });
+  }, POLL_INTERVAL_MS);
+
+  // Run first check shortly after startup
+  setTimeout(() => {
+    tickAutoBackup().catch((err) => {
+      console.error("[auto-backup] Initial tick error:", err);
+    });
+  }, 5_000);
+}
+
+/**
+ * Stop the auto-backup timer.
+ */
+export function stopAutoBackup(): void {
+  if (intervalHandle !== null) {
+    clearInterval(intervalHandle);
+    intervalHandle = null;
+    console.log("[auto-backup] Stopped auto-backup timer");
+  }
+}
+
+/**
+ * Run one auto-backup check cycle. Exposed for testing.
+ */
+export async function tickAutoBackup(): Promise<void> {
+  // 1. Check if enabled
+  const enabled = getSettingSync(SETTINGS.enabled);
+  if (enabled !== "true") return;
+
+  // 2. Skip if a snapshot operation is in progress
+  if (isSnapshotLocked()) return;
+
+  // 3. Get the configured interval
+  const intervalStr = getSettingSync(SETTINGS.interval) || "1d";
+  let cronExpr: string;
+  try {
+    cronExpr = parseInterval(intervalStr);
+  } catch {
+    console.warn(`[auto-backup] Invalid interval "${intervalStr}", skipping`);
+    return;
+  }
+
+  // 4. Check if enough time has passed since last auto-backup
+  const [lastAutoSnapshot] = await db
+    .select()
+    .from(snapshots)
+    .where(eq(snapshots.type, "auto"))
+    .orderBy(desc(snapshots.createdAt))
+    .limit(1);
+
+  if (lastAutoSnapshot) {
+    const lastTime = lastAutoSnapshot.createdAt;
+    const nextFire = computeNextFireTime(cronExpr, lastTime);
+    if (nextFire && nextFire > new Date()) {
+      // Not due yet
+      return;
+    }
+  }
+
+  // 5. Create auto-backup snapshot
+  console.log("[auto-backup] Creating auto-backup snapshot...");
+  try {
+    const now = new Date();
+    const label = `Auto-backup ${now.toISOString().slice(0, 16).replace("T", " ")}`;
+    await createSnapshot(label, "auto");
+    console.log("[auto-backup] Auto-backup snapshot created successfully");
+  } catch (err) {
+    console.error("[auto-backup] Failed to create snapshot:", err);
+    return;
+  }
+
+  // 6. Enforce retention after snapshot creation
+  try {
+    const maxCount = parseInt(getSettingSync(SETTINGS.maxCount) || "10", 10);
+    const maxAgeWeeks = parseInt(
+      getSettingSync(SETTINGS.maxAgeWeeks) || "4",
+      10
+    );
+    const deleted = await enforceRetention(maxCount, maxAgeWeeks);
+    if (deleted > 0) {
+      console.log(`[auto-backup] Retention enforced: deleted ${deleted} old snapshot(s)`);
+    }
+  } catch (err) {
+    console.error("[auto-backup] Retention enforcement failed:", err);
+  }
+}

package/src/lib/snapshots/retention.ts

@@ -0,0 +1,64 @@
+/**
+ * Snapshot retention policy — enforces max count and max age limits.
+ * Deletes oldest snapshots first when either limit is exceeded.
+ */
+
+import { db } from "@/lib/db";
+import { snapshots } from "@/lib/db/schema";
+import { asc, eq, and, lte } from "drizzle-orm";
+import { deleteSnapshot } from "./snapshot-manager";
+
+/**
+ * Enforce retention limits. Should be called after every snapshot creation.
+ *
+ * @param maxCount - Maximum number of snapshots to keep (0 = unlimited)
+ * @param maxAgeWeeks - Maximum age in weeks (0 = unlimited)
+ * @returns Number of snapshots deleted
+ */
+export async function enforceRetention(
+  maxCount: number,
+  maxAgeWeeks: number
+): Promise<number> {
+  let deleted = 0;
+
+  // 1. Enforce max age — delete snapshots older than N weeks
+  if (maxAgeWeeks > 0) {
+    const cutoff = new Date();
+    cutoff.setDate(cutoff.getDate() - maxAgeWeeks * 7);
+
+    const expired = await db
+      .select()
+      .from(snapshots)
+      .where(
+        and(
+          eq(snapshots.status, "completed"),
+          lte(snapshots.createdAt, cutoff)
+        )
+      )
+      .orderBy(asc(snapshots.createdAt));
+
+    for (const row of expired) {
+      await deleteSnapshot(row.id);
+      deleted++;
+    }
+  }
+
+  // 2. Enforce max count — delete oldest beyond the limit
+  if (maxCount > 0) {
+    const all = await db
+      .select()
+      .from(snapshots)
+      .where(eq(snapshots.status, "completed"))
+      .orderBy(asc(snapshots.createdAt));
+
+    const excess = all.length - maxCount;
+    if (excess > 0) {
+      for (let i = 0; i < excess; i++) {
+        await deleteSnapshot(all[i].id);
+        deleted++;
+      }
+    }
+  }
+
+  return deleted;
+}

package/src/lib/snapshots/snapshot-manager.ts

@@ -0,0 +1,429 @@
+/**
+ * Core snapshot manager — create, list, delete, and restore full-state snapshots.
+ *
+ * A snapshot includes:
+ *   1. Atomic SQLite backup via .backup() API (WAL-safe)
+ *   2. Tarball of all ~/.stagent/ file directories (uploads, screenshots, outputs, etc.)
+ *   3. manifest.json with metadata
+ */
+
+import { db, sqlite } from "@/lib/db";
+import { snapshots } from "@/lib/db/schema";
+import type { SnapshotRow } from "@/lib/db/schema";
+import {
+  getStagentDataDir,
+  getStagentSnapshotsDir,
+  getStagentDbPath,
+} from "@/lib/utils/stagent-paths";
+import { eq, desc } from "drizzle-orm";
+import {
+  mkdirSync,
+  existsSync,
+  statSync,
+  rmSync,
+  readdirSync,
+  writeFileSync,
+  readFileSync,
+} from "fs";
+import { join } from "path";
+import * as tar from "tar";
+
+// Directories included in snapshot (relative to stagent data dir)
+const SNAPSHOT_DIRS = [
+  "uploads",
+  "screenshots",
+  "outputs",
+  "sessions",
+  "documents",
+  "logs",
+];
+
+// Directories excluded from snapshot
+const EXCLUDED_DIRS = ["backups", "snapshots"];
+
+// Mutex to prevent concurrent snapshot operations
+let snapshotLock = false;
+
+export function isSnapshotLocked(): boolean {
+  return snapshotLock;
+}
+
+interface SnapshotManifest {
+  version: 1;
+  timestamp: string;
+  label: string;
+  type: "manual" | "auto";
+  includedDirs: string[];
+  excludedDirs: string[];
+  dirStats: Record<string, { fileCount: number; sizeBytes: number }>;
+  dbSizeBytes: number;
+  filesSizeBytes: number;
+  totalSizeBytes: number;
+}
+
+function generateId(): string {
+  return crypto.randomUUID();
+}
+
+function formatTimestamp(date: Date): string {
+  return date.toISOString().replace(/[:.]/g, "-");
+}
+
+/** Calculate total size of files in a directory (recursive). */
+function dirSize(dirPath: string): { fileCount: number; sizeBytes: number } {
+  if (!existsSync(dirPath)) return { fileCount: 0, sizeBytes: 0 };
+
+  let fileCount = 0;
+  let sizeBytes = 0;
+
+  function walk(dir: string) {
+    try {
+      for (const entry of readdirSync(dir)) {
+        const fullPath = join(dir, entry);
+        try {
+          const stat = statSync(fullPath);
+          if (stat.isDirectory()) {
+            walk(fullPath);
+          } else if (stat.isFile()) {
+            fileCount++;
+            sizeBytes += stat.size;
+          }
+        } catch {
+          // Skip unreadable entries
+        }
+      }
+    } catch {
+      // Skip unreadable directories
+    }
+  }
+
+  walk(dirPath);
+  return { fileCount, sizeBytes };
+}
+
+/**
+ * Create a full-state snapshot (DB + files).
+ */
+export async function createSnapshot(
+  label: string,
+  type: "manual" | "auto" = "manual"
+): Promise<SnapshotRow> {
+  if (snapshotLock) {
+    throw new Error("Another snapshot operation is already in progress");
+  }
+
+  snapshotLock = true;
+  const id = generateId();
+  const now = new Date();
+  const sanitizedLabel = label.replace(/[^a-zA-Z0-9-_ ]/g, "_").slice(0, 100);
+  const dirName = `${formatTimestamp(now)}_${sanitizedLabel.replace(/\s+/g, "_")}`;
+  const snapshotsDir = getStagentSnapshotsDir();
+  const snapshotPath = join(snapshotsDir, dirName);
+  const dataDir = getStagentDataDir();
+
+  try {
+    mkdirSync(snapshotPath, { recursive: true });
+
+    // Insert in-progress record
+    await db.insert(snapshots).values({
+      id,
+      label: sanitizedLabel,
+      type,
+      status: "in_progress",
+      filePath: snapshotPath,
+      sizeBytes: 0,
+      dbSizeBytes: 0,
+      filesSizeBytes: 0,
+      fileCount: 0,
+      createdAt: now,
+    });
+
+    // 1. Atomic SQLite backup
+    const dbDestPath = join(snapshotPath, "snapshot.db");
+    await sqlite.backup(dbDestPath);
+    const dbSize = statSync(dbDestPath).size;
+
+    // 2. Tarball of file directories
+    const tarballPath = join(snapshotPath, "files.tar.gz");
+    const existingDirs = SNAPSHOT_DIRS.filter((d) =>
+      existsSync(join(dataDir, d))
+    );
+
+    let filesSizeBytes = 0;
+    let totalFileCount = 0;
+    const dirStats: Record<string, { fileCount: number; sizeBytes: number }> =
+      {};
+
+    for (const dir of existingDirs) {
+      const stats = dirSize(join(dataDir, dir));
+      dirStats[dir] = stats;
+      filesSizeBytes += stats.sizeBytes;
+      totalFileCount += stats.fileCount;
+    }
+
+    if (existingDirs.length > 0) {
+      await tar.create(
+        {
+          gzip: true,
+          file: tarballPath,
+          cwd: dataDir,
+        },
+        existingDirs
+      );
+    } else {
+      // Create empty tarball
+      await tar.create(
+        {
+          gzip: true,
+          file: tarballPath,
+          cwd: dataDir,
+        },
+        []
+      );
+    }
+
+    const tarballSize = existsSync(tarballPath)
+      ? statSync(tarballPath).size
+      : 0;
+    const totalSize = dbSize + tarballSize;
+
+    // 3. Write manifest
+    const manifest: SnapshotManifest = {
+      version: 1,
+      timestamp: now.toISOString(),
+      label: sanitizedLabel,
+      type,
+      includedDirs: existingDirs,
+      excludedDirs: EXCLUDED_DIRS,
+      dirStats,
+      dbSizeBytes: dbSize,
+      filesSizeBytes,
+      totalSizeBytes: totalSize,
+    };
+    writeFileSync(
+      join(snapshotPath, "manifest.json"),
+      JSON.stringify(manifest, null, 2)
+    );
+
+    // 4. Update record with final sizes
+    await db
+      .update(snapshots)
+      .set({
+        status: "completed",
+        sizeBytes: totalSize,
+        dbSizeBytes: dbSize,
+        filesSizeBytes: tarballSize,
+        fileCount: totalFileCount,
+      })
+      .where(eq(snapshots.id, id));
+
+    const [row] = await db
+      .select()
+      .from(snapshots)
+      .where(eq(snapshots.id, id));
+    return row;
+  } catch (error) {
+    // Mark as failed
+    try {
+      await db
+        .update(snapshots)
+        .set({
+          status: "failed",
+          error: error instanceof Error ? error.message : String(error),
+        })
+        .where(eq(snapshots.id, id));
+    } catch {
+      // If we can't even update the record, clean up the directory
+    }
+
+    // Clean up partial snapshot directory
+    if (existsSync(snapshotPath)) {
+      try {
+        rmSync(snapshotPath, { recursive: true, force: true });
+      } catch {
+        // Best effort cleanup
+      }
+    }
+
+    throw error;
+  } finally {
+    snapshotLock = false;
+  }
+}
+
+/**
+ * List all snapshots, newest first.
+ * Checks file existence and marks missing snapshots.
+ */
+export async function listSnapshots(): Promise<
+  (SnapshotRow & { filesMissing: boolean })[]
+> {
+  const rows = await db
+    .select()
+    .from(snapshots)
+    .orderBy(desc(snapshots.createdAt));
+
+  return rows.map((row) => ({
+    ...row,
+    filesMissing: row.status === "completed" && !existsSync(row.filePath),
+  }));
+}
+
+/**
+ * Get a single snapshot by ID.
+ */
+export async function getSnapshot(
+  id: string
+): Promise<(SnapshotRow & { filesMissing: boolean; manifest: SnapshotManifest | null }) | null> {
+  const [row] = await db
+    .select()
+    .from(snapshots)
+    .where(eq(snapshots.id, id));
+
+  if (!row) return null;
+
+  let manifest: SnapshotManifest | null = null;
+  const manifestPath = join(row.filePath, "manifest.json");
+  if (existsSync(manifestPath)) {
+    try {
+      manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+    } catch {
+      // Corrupt manifest — continue without it
+    }
+  }
+
+  return {
+    ...row,
+    filesMissing: row.status === "completed" && !existsSync(row.filePath),
+    manifest,
+  };
+}
+
+/**
+ * Delete a snapshot (metadata + files on disk).
+ */
+export async function deleteSnapshot(id: string): Promise<boolean> {
+  const [row] = await db
+    .select()
+    .from(snapshots)
+    .where(eq(snapshots.id, id));
+
+  if (!row) return false;
+
+  // Delete files on disk
+  if (existsSync(row.filePath)) {
+    rmSync(row.filePath, { recursive: true, force: true });
+  }
+
+  // Delete metadata
+  await db.delete(snapshots).where(eq(snapshots.id, id));
+  return true;
+}
+
+/**
+ * Get total disk usage of all snapshot files.
+ */
+export async function getSnapshotsSize(): Promise<{
+  totalBytes: number;
+  snapshotCount: number;
+}> {
+  const snapshotsDir = getStagentSnapshotsDir();
+  if (!existsSync(snapshotsDir)) return { totalBytes: 0, snapshotCount: 0 };
+
+  const rows = await db.select().from(snapshots);
+  let totalBytes = 0;
+
+  for (const row of rows) {
+    if (row.status === "completed" && existsSync(row.filePath)) {
+      const stats = dirSize(row.filePath);
+      totalBytes += stats.sizeBytes;
+    }
+  }
+
+  return { totalBytes, snapshotCount: rows.length };
+}
+
+/**
+ * Restore from a snapshot — DESTRUCTIVE operation.
+ * Creates a pre-restore safety snapshot, then replaces DB + files.
+ * Returns { requiresRestart: true } to signal the server must restart.
+ */
+export async function restoreFromSnapshot(id: string): Promise<{
+  requiresRestart: boolean;
+  preRestoreSnapshotId: string;
+}> {
+  if (snapshotLock) {
+    throw new Error("Another snapshot operation is already in progress");
+  }
+
+  const snapshot = await getSnapshot(id);
+  if (!snapshot) throw new Error("Snapshot not found");
+  if (snapshot.status !== "completed")
+    throw new Error("Cannot restore from incomplete snapshot");
+  if (snapshot.filesMissing)
+    throw new Error("Snapshot files are missing from disk");
+
+  const snapshotDbPath = join(snapshot.filePath, "snapshot.db");
+  const snapshotTarPath = join(snapshot.filePath, "files.tar.gz");
+
+  if (!existsSync(snapshotDbPath)) {
+    throw new Error("Snapshot database file is missing");
+  }
+
+  snapshotLock = true;
+
+  try {
+    // 1. Create pre-restore safety snapshot
+    const preRestore = await createSnapshot(
+      `pre-restore-${formatTimestamp(new Date())}`,
+      "auto"
+    );
+
+    // 2. Replace file directories
+    const dataDir = getStagentDataDir();
+
+    // Clear existing file directories
+    for (const dir of SNAPSHOT_DIRS) {
+      const fullPath = join(dataDir, dir);
+      if (existsSync(fullPath)) {
+        rmSync(fullPath, { recursive: true, force: true });
+      }
+    }
+
+    // Extract tarball
+    if (existsSync(snapshotTarPath)) {
+      await tar.extract({
+        file: snapshotTarPath,
+        cwd: dataDir,
+      });
+    }
+
+    // 3. Replace database file
+    // Close any prepared statements first
+    const currentDbPath = getStagentDbPath();
+    const walPath = currentDbPath + "-wal";
+    const shmPath = currentDbPath + "-shm";
+
+    // Checkpoint WAL to ensure consistency
+    try {
+      sqlite.pragma("wal_checkpoint(TRUNCATE)");
+    } catch {
+      // Best effort
+    }
+
+    // Copy snapshot DB over current DB
+    const { copyFileSync } = await import("fs");
+    copyFileSync(snapshotDbPath, currentDbPath);
+
+    // Remove WAL/SHM files (snapshot DB is self-contained)
+    if (existsSync(walPath)) rmSync(walPath);
+    if (existsSync(shmPath)) rmSync(shmPath);
+
+    return {
+      requiresRestart: true,
+      preRestoreSnapshotId: preRestore.id,
+    };
+  } finally {
+    snapshotLock = false;
+  }
+}