@vellumai/assistant 0.7.0 → 0.7.2

package/src/backup/restore.ts

@@ -1,116 +1,56 @@
 /**
- * High-level helpers for restoring and verifying backup snapshots produced
- * by the backup pipeline.
+ * High-level helpers for restoring and verifying backup snapshots.
  *
- * A snapshot is one of:
- *   - A plaintext `.vbundle` file (gzipped tar — see `vbundle-builder.ts`).
- *   - An encrypted `.vbundle.enc` file produced by `stream-crypt.encryptFile`.
+ * Only plaintext `.vbundle` files are supported directly. Encrypted
+ * `.vbundle.enc` files must be restored through the gateway, which owns the
+ * backup encryption key (ATL-397).
  *
- * The encryption status is detected purely from the file extension:
- *   - `.vbundle.enc` → encrypted (decryption key required)
- *   - `.vbundle`     → plaintext
- *
- * For encrypted snapshots, this module decrypts to a temporary file under the
- * OS temp directory, runs validation, and then either commits the import or
- * just reports validation status. The temp file is always cleaned up — on
- * success and on failure — via a `try { ... } finally { unlink }` block.
- *
- * Restore is intentionally a thin wrapper around the existing
- * `commitImport` flow in `runtime/migrations/vbundle-importer.ts`. That
- * function handles bundle validation, workspace clearing, per-file
- * backup-before-overwrite, and writing files to disk.
+ * Restore is a thin wrapper around `commitImport` in
+ * `runtime/migrations/vbundle-importer.ts`, which handles bundle validation,
+ * workspace clearing, per-file backup-before-overwrite, and writing files.
  *
  * `restoreFromSnapshot` closes the live SQLite singleton via `resetDb()`
- * immediately before the commit step so the daemon's DB handle is released
- * before `assistant.db` is overwritten on disk. This mirrors the pattern in
- * `handleMigrationImport` and ensures both the HTTP restore path and any
- * in-process CLI caller get the reset for free. Tests can inject a fake via
- * `opts.resetDbImpl`.
- *
- * `commitImport` does NOT invalidate cached config. Callers are responsible
- * for calling `invalidateConfigCache()` AFTER a successful restore so the
- * daemon re-reads the restored `config.json` instead of serving stale
- * in-process caches. A daemon restart is the simplest recovery path.
+ * before the commit step so the daemon's DB handle is released before
+ * `assistant.db` is overwritten on disk.
  *
  * Credentials are intentionally excluded from backups — they live in the OS
- * keychain / CES and are not restored by this path. Users re-authenticate
- * integrations after a restore.
+ * keychain / CES and are not restored by this path.
  */
 
-import { randomUUID } from "node:crypto";
-import { readFile, unlink } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { readFile } from "node:fs/promises";
 
 import { resetDb } from "../memory/db-connection.js";
 import type { PathResolver } from "../runtime/migrations/vbundle-import-analyzer.js";
+import {
+  evaluateRuntimeCompatibility,
+  formatRuntimeCompatibilityMessage,
+} from "../runtime/migrations/vbundle-import-policy.js";
 import { commitImport } from "../runtime/migrations/vbundle-importer.js";
 import type { ManifestType } from "../runtime/migrations/vbundle-validator.js";
 import { validateVBundle } from "../runtime/migrations/vbundle-validator.js";
-import { decryptFile } from "./stream-crypt.js";
+import { APP_VERSION } from "../version.js";
 
 // ---------------------------------------------------------------------------
 // Public types
 // ---------------------------------------------------------------------------
 
-/**
- * Optional injection point for the underlying commit function. Tests pass a
- * fake here to avoid running the destructive `commitImport` flow against the
- * live workspace. Production callers should leave this unset so the real
- * importer is used.
- */
 type CommitImpl = typeof commitImport;
 
 interface RestoreOptions {
-  /** AES-256 decryption key. Required for `.vbundle.enc` snapshots. */
-  key?: Buffer;
-  /**
-   * Resolver that maps archive paths (e.g. `workspace/config.json`) to
-   * absolute disk paths. Required by the underlying `commitImport` flow.
-   */
   pathResolver: PathResolver;
-  /**
-   * Absolute path to the workspace directory. When set and the bundle
-   * contains `workspace/` entries, `commitImport` clears the workspace
-   * before writing to ensure an exact-match restore.
-   */
   workspaceDir?: string;
-  /**
-   * Optional override for the underlying commit function. Tests inject a
-   * fake to avoid mutating disk; production callers should leave this unset.
-   */
   commitImpl?: CommitImpl;
-  /**
-   * Optional override for the DB-reset hook. Invoked immediately before
-   * `commitImpl` so the live SQLite singleton is closed before
-   * `assistant.db` is overwritten. Tests inject a spy; production callers
-   * should leave this unset so the real `resetDb` is used.
-   */
   resetDbImpl?: () => void;
 }
 
 export interface RestoreResult {
-  /** Manifest from the bundle that was restored. */
   manifest: ManifestType;
-  /** Number of files written (or skipped) by the underlying commit. */
   restoredFiles: number;
 }
 
-interface VerifyOptions {
-  /** AES-256 decryption key. Required for `.vbundle.enc` snapshots. */
-  key?: Buffer;
-}
-
 export interface VerifyResult {
-  /** True iff the bundle decrypts (when applicable) and validates. */
   valid: boolean;
-  /** Manifest from the bundle when `valid` is true. */
   manifest?: ManifestType;
-  /**
-   * Human-readable error message when `valid` is false. Populated for
-   * validation failures, decryption failures, and missing-file errors.
-   * Always undefined when `valid` is true.
-   */
   error?: string;
 }
 
@@ -118,201 +58,137 @@ export interface VerifyResult {
 // Internal helpers
 // ---------------------------------------------------------------------------
 
-/** Returns true if the snapshot path indicates an encrypted bundle. */
 function isEncryptedSnapshot(snapshotPath: string): boolean {
   return snapshotPath.endsWith(".vbundle.enc");
 }
 
-/** Build a unique temp path for a decrypted bundle. */
-function makeDecryptedTempPath(): string {
-  return join(tmpdir(), `vellum-restore-${randomUUID()}.vbundle`);
-}
-
-/**
- * Resolve `snapshotPath` to a path that holds plaintext `.vbundle` bytes.
- *
- * For plaintext snapshots, this just returns `{ path: snapshotPath }`. For
- * encrypted snapshots, it decrypts to a fresh temp file and returns
- * `{ path: tmpPath, tmpPath }` so the caller can clean up afterwards.
- *
- * Throws when an encrypted bundle has no key, when `decryptFile` fails
- * (bad key, tampered ciphertext, truncated file), or on any I/O error.
- */
-async function materializePlaintext(
-  snapshotPath: string,
-  key: Buffer | undefined,
-): Promise<{ path: string; tmpPath: string | null }> {
-  if (!isEncryptedSnapshot(snapshotPath)) {
-    return { path: snapshotPath, tmpPath: null };
-  }
-
-  if (!key) {
-    throw new Error("Encrypted snapshot requires a decryption key");
-  }
-
-  const tmpPath = makeDecryptedTempPath();
-  await decryptFile(snapshotPath, tmpPath, key);
-  return { path: tmpPath, tmpPath };
-}
-
-/** Best-effort temp file cleanup — swallows ENOENT and other errors. */
-async function safeUnlink(path: string | null): Promise<void> {
-  if (!path) return;
-  try {
-    await unlink(path);
-  } catch {
-    // Best-effort — temp file may already be gone.
-  }
-}
-
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
 
 /**
- * Restore a backup snapshot into the workspace.
- *
- * Auto-detects encryption from the file extension. Encrypted snapshots
- * (`.vbundle.enc`) decrypt to a temp file under `tmpdir()` before
- * validation; the temp file is unlinked in a `finally` block so it never
- * lingers, even on validation or commit failure.
+ * Restore a plaintext backup snapshot into the workspace.
  *
- * The actual restore is delegated to `commitImport`, which owns the
- * backup-before-overwrite, workspace-clearing, and integrity-check logic.
- * Tests can pass `opts.commitImpl` to substitute a fake without mutating
- * the live workspace.
+ * Encrypted `.vbundle.enc` snapshots are rejected — use the gateway's
+ * restore endpoint for those.
  */
 export async function restoreFromSnapshot(
   snapshotPath: string,
   opts: RestoreOptions,
 ): Promise<RestoreResult> {
+  if (isEncryptedSnapshot(snapshotPath)) {
+    throw new Error(
+      "Encrypted snapshot restore must go through the gateway, which owns the backup key. " +
+        "Use the gateway's restore endpoint instead.",
+    );
+  }
+
   const {
-    key,
     pathResolver,
     workspaceDir,
     commitImpl = commitImport,
     resetDbImpl = resetDb,
   } = opts;
 
-  let tmpPath: string | null = null;
-  try {
-    const materialized = await materializePlaintext(snapshotPath, key);
-    tmpPath = materialized.tmpPath;
-
-    // Read plaintext bytes for validation + commit. validateVBundle takes
-    // raw bytes (Uint8Array) — file paths are not part of its API.
-    const fileData = await readFile(materialized.path);
+  const fileData = await readFile(snapshotPath);
 
-    const validation = validateVBundle(fileData);
-    if (!validation.is_valid || !validation.manifest || !validation.entries) {
-      const summary = validation.errors
-        .map((e) => `${e.code}: ${e.message}`)
-        .join("; ");
-      throw new Error(`Snapshot failed validation: ${summary}`);
-    }
+  const validation = validateVBundle(fileData);
+  if (!validation.is_valid || !validation.manifest || !validation.entries) {
+    const summary = validation.errors
+      .map((e) => `${e.code}: ${e.message}`)
+      .join("; ");
+    throw new Error(`Snapshot failed validation: ${summary}`);
+  }
 
-    // Close the live SQLite singleton before overwriting assistant.db on
-    // disk — otherwise the daemon keeps a handle to the old inode and
-    // subsequent writes can corrupt the restored state. Mirrors the
-    // pattern in `handleMigrationImport`. The singleton will be lazily
-    // reopened on the next getDb() call.
-    resetDbImpl();
+  // Pre-check runtime-version compat before the DB close/reopen cycle.
+  // commitImport runs the same gate as defense-in-depth for callers that
+  // don't pre-check; we run it here too so an incompatible bundle short-
+  // circuits before resetDbImpl().
+  const compatResult = evaluateRuntimeCompatibility(
+    validation.manifest.compatibility,
+    APP_VERSION,
+  );
+  if (!compatResult.ok) {
+    throw new Error(
+      `Snapshot restore failed: ${formatRuntimeCompatibilityMessage(
+        compatResult.bundle_compat,
+        compatResult.runtime_version,
+      )}`,
+    );
+  }
 
-    const commitResult = commitImpl({
-      archiveData: fileData,
-      pathResolver,
-      preValidatedManifest: validation.manifest,
-      preValidatedEntries: validation.entries,
-      workspaceDir,
-    });
+  resetDbImpl();
 
-    if (!commitResult.ok) {
-      // Surface a single error message regardless of which discriminated
-      // branch failed — callers in the backup CLI just want a message.
-      let message: string;
-      switch (commitResult.reason) {
-        case "validation_failed":
-          message = commitResult.errors
-            .map((e) => `${e.code}: ${e.message}`)
-            .join("; ");
-          break;
-        case "extraction_failed":
-        case "write_failed":
-          message = commitResult.message;
-          break;
-      }
-      throw new Error(`Snapshot restore failed: ${message}`);
+  const commitResult = commitImpl({
+    archiveData: fileData,
+    pathResolver,
+    preValidatedManifest: validation.manifest,
+    preValidatedEntries: validation.entries,
+    workspaceDir,
+  });
+
+  if (!commitResult.ok) {
+    let message: string;
+    switch (commitResult.reason) {
+      case "validation_failed":
+        message = commitResult.errors
+          .map((e) => `${e.code}: ${e.message}`)
+          .join("; ");
+        break;
+      case "extraction_failed":
+      case "write_failed":
+        message = commitResult.message;
+        break;
+      case "version_incompatible":
+        message = formatRuntimeCompatibilityMessage(
+          commitResult.bundle_compat,
+          commitResult.runtime_version,
+        );
+        break;
     }
-
-    return {
-      manifest: commitResult.report.manifest,
-      restoredFiles: commitResult.report.summary.total_files,
-    };
-  } finally {
-    await safeUnlink(tmpPath);
+    throw new Error(`Snapshot restore failed: ${message}`);
   }
+
+  return {
+    manifest: commitResult.report.manifest,
+    restoredFiles: commitResult.report.summary.total_files,
+  };
 }
 
 /**
  * Verify a backup snapshot without restoring it.
  *
- * Auto-detects encryption from the file extension and decrypts to a temp
- * file when needed (cleaned up in a `finally` block). Runs the same
- * `validateVBundle` checks the importer would run, but never touches the
- * workspace.
- *
- * Does NOT throw on validation or decryption failure — those are returned
- * as `{ valid: false, error: ... }`. Only the missing-key precondition
- * for encrypted bundles throws, since that is a programmer error.
+ * Only plaintext `.vbundle` files are supported. Encrypted snapshots must be
+ * verified through the gateway.
  */
 export async function verifySnapshot(
   snapshotPath: string,
-  opts: VerifyOptions,
 ): Promise<VerifyResult> {
-  const { key } = opts;
-
-  // Encrypted bundles must have a key — this is a precondition error,
-  // not a validation failure, so we throw rather than return.
-  if (isEncryptedSnapshot(snapshotPath) && !key) {
-    throw new Error("Encrypted snapshot requires a decryption key");
+  if (isEncryptedSnapshot(snapshotPath)) {
+    return {
+      valid: false,
+      error:
+        "Encrypted snapshot verification must go through the gateway, which owns the backup key.",
+    };
   }
 
-  let tmpPath: string | null = null;
+  let fileData: Uint8Array;
   try {
-    let plaintextPath: string;
-    try {
-      const materialized = await materializePlaintext(snapshotPath, key);
-      tmpPath = materialized.tmpPath;
-      plaintextPath = materialized.path;
-    } catch (err) {
-      // Decryption / I/O failure — surface as a soft error so verification
-      // callers (e.g. snapshot list health checks) get a uniform shape.
-      return {
-        valid: false,
-        error: err instanceof Error ? err.message : String(err),
-      };
-    }
-
-    let fileData: Uint8Array;
-    try {
-      fileData = await readFile(plaintextPath);
-    } catch (err) {
-      return {
-        valid: false,
-        error: err instanceof Error ? err.message : String(err),
-      };
-    }
-
-    const validation = validateVBundle(fileData);
-    if (!validation.is_valid || !validation.manifest) {
-      const summary = validation.errors
-        .map((e) => `${e.code}: ${e.message}`)
-        .join("; ");
-      return { valid: false, error: summary };
-    }
+    fileData = await readFile(snapshotPath);
+  } catch (err) {
+    return {
+      valid: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
 
-    return { valid: true, manifest: validation.manifest };
-  } finally {
-    await safeUnlink(tmpPath);
+  const validation = validateVBundle(fileData);
+  if (!validation.is_valid || !validation.manifest) {
+    const summary = validation.errors
+      .map((e) => `${e.code}: ${e.message}`)
+      .join("; ");
+    return { valid: false, error: summary };
   }
+
+  return { valid: true, manifest: validation.manifest };
 }

package/src/browser-session/events.ts

@@ -132,15 +132,6 @@ export function isTargetInvalidated(targetId: string): boolean {
   return invalidatedTargetIds.has(targetId);
 }
 
-/**
- * Test-only helper: snapshot the current invalidated set without
- * draining it. Exported so unit tests can assert exact set contents
- * across multiple frames; production code must not rely on this.
- */
-export function __peekInvalidatedTargetIdsForTests(): string[] {
-  return Array.from(invalidatedTargetIds);
-}
-
 /**
  * Atomically remove and return a target id from the invalidated set.
  * Returns `true` when the id was present (and has now been removed),

package/src/bundler/app-bundler.ts

@@ -17,6 +17,7 @@ import JSZip from "jszip";
 import { getApp, getAppDirPath, isMultifileApp } from "../memory/app-store.js";
 import { computeContentId } from "../util/content-id.js";
 import { getLogger } from "../util/logger.js";
+import { APP_VERSION } from "../version.js";
 import { compileApp } from "./app-compiler.js";
 import type { SigningCallback } from "./bundle-signer.js";
 import { signBundle } from "./bundle-signer.js";
@@ -25,7 +26,6 @@ import { serializeManifest } from "./manifest.js";
 
 const bundlerLog = getLogger("app-bundler");
 
-import { APP_VERSION } from "../version.js";
 const PACKAGE_VERSION = APP_VERSION;
 
 const MAX_BUNDLE_SIZE_BYTES = 25 * 1024 * 1024; // 25 MB
@@ -37,6 +37,45 @@ export interface BundleResult {
   iconImageBase64?: string;
 }
 
+function isDefaultMainScaffold(source: string): boolean {
+  const normalized = source.replace(/\s+/g, " ").trim();
+  return (
+    normalized.startsWith(
+      `import { render } from 'preact'; function App() { return <div>{"Hello, `,
+    ) &&
+    normalized.endsWith(
+      `!"}</div>; } render(<App />, document.getElementById('app')!);`,
+    )
+  );
+}
+
+function assertMultifileSourceReady(
+  app: { name: string },
+  appDir: string,
+): void {
+  const srcIndexPath = join(appDir, "src", "index.html");
+  const srcMainPath = join(appDir, "src", "main.tsx");
+  const missing = [
+    !existsSync(srcIndexPath) ? "src/index.html" : null,
+    !existsSync(srcMainPath) ? "src/main.tsx" : null,
+  ].filter((value): value is string => value !== null);
+
+  if (missing.length > 0) {
+    throw new Error(
+      `App "${app.name}" is a multi-file TSX app but is missing ${missing.join(
+        " and ",
+      )}. Write source files under src/ and call app_refresh before sharing.`,
+    );
+  }
+
+  const mainSource = readFileSync(srcMainPath, "utf-8");
+  if (isDefaultMainScaffold(mainSource)) {
+    throw new Error(
+      `App "${app.name}" still has the default src/main.tsx scaffold. Write the real multi-file TSX source and call app_refresh before sharing.`,
+    );
+  }
+}
+
 /**
  * Package an app into a .vellum zip archive.
  *
@@ -82,6 +121,8 @@ export async function packageApp(
   const appDir = getAppDirPath(appId);
 
   if (multifile) {
+    assertMultifileSourceReady(app, appDir);
+
     // Multi-file TSX app: compile src/ -> dist/
     const compileResult = await compileApp(appDir);
     if (!compileResult.ok) {
@@ -97,8 +138,15 @@ export async function packageApp(
     }
 
     const distDir = join(appDir, "dist");
-    const indexHtml = await readFile(join(distDir, "index.html"), "utf-8");
-    const mainJs = await readFile(join(distDir, "main.js"));
+    const distIndexPath = join(distDir, "index.html");
+    const distMainPath = join(distDir, "main.js");
+    if (!existsSync(distIndexPath) || !existsSync(distMainPath)) {
+      throw new Error(
+        `Compilation for app "${app.name}" did not produce dist/index.html and dist/main.js. Check src/index.html and src/main.tsx, then call app_refresh.`,
+      );
+    }
+    const indexHtml = await readFile(distIndexPath, "utf-8");
+    const mainJs = await readFile(distMainPath);
 
     compiledFiles.push({ name: "index.html", data: Buffer.from(indexHtml) });
     compiledFiles.push({ name: "main.js", data: mainJs });

package/src/calls/call-store.ts

@@ -2,7 +2,7 @@ import { and, desc, eq, notInArray, or } from "drizzle-orm";
 import { v4 as uuid } from "uuid";
 
 import { getDb } from "../memory/db-connection.js";
-import { rawChanges, rawGet, rawRun } from "../memory/raw-query.js";
+import { rawChanges, rawRun } from "../memory/raw-query.js";
 import {
   callEvents,
   callPendingQuestions,
@@ -379,39 +379,6 @@ export function buildCallbackDedupeKey(
   return `${callSid}:${callStatus}:${discriminator}`;
 }
 
-/**
- * Check whether a callback dedupe key has already been processed (read-only).
- * Returns true if the key already exists, false otherwise.
- */
-export function isCallbackProcessed(dedupeKey: string): boolean {
-  return (
-    rawGet<{ 1: number }>(
-      `SELECT 1 FROM processed_callbacks WHERE dedupe_key = ?`,
-      dedupeKey,
-    ) != null
-  );
-}
-
-/**
- * Record a callback as processed. Should be called AFTER downstream writes
- * (session updates, event recording) have succeeded so that Twilio retries
- * are not silently dropped if those writes fail.
- *
- * Uses INSERT OR IGNORE so concurrent calls for the same key are safe.
- */
-export function recordProcessedCallback(
-  dedupeKey: string,
-  callSessionId: string,
-): void {
-  rawRun(
-    `INSERT OR IGNORE INTO processed_callbacks (id, dedupe_key, call_session_id, created_at) VALUES (?, ?, ?, ?)`,
-    uuid(),
-    dedupeKey,
-    callSessionId,
-    Date.now(),
-  );
-}
-
 /**
  * Atomically claim a callback for processing. Returns a unique claim ID
  * (string) if this caller won the claim, or null if another caller already