@vellumai/assistant 0.7.1 → 0.7.3

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/backup/snapshot-lock.ts

@@ -32,10 +32,10 @@ import {
   writeSync,
 } from "node:fs";
 import { dirname, join } from "node:path";
-import { kill } from "node:process";
 import { setTimeout as sleep } from "node:timers/promises";
 
 import { getLogger } from "../util/logger.js";
+import { isProcessAlive } from "../util/process-liveness.js";
 import { getLocalBackupsDir } from "./paths.js";
 
 const log = getLogger("snapshot-lock");
@@ -88,29 +88,6 @@ export function getSnapshotLockPath(): string {
   return join(dirname(getLocalBackupsDir()), ".snapshot.lock");
 }
 
-/**
- * Check whether a PID refers to a live process. Uses `kill(pid, 0)`, which
- * does not send any signal — it just probes for existence and permission.
- *
- * Returns `false` for obviously invalid PIDs (<= 0) and for any error that
- * indicates the process is gone. Returns `true` for ESRCH-negative results
- * (meaning a process exists) and for EPERM (process exists but is owned by
- * another user — still a live process, still should not be taken over).
- */
-function isProcessAlive(pid: number): boolean {
-  if (!Number.isInteger(pid) || pid <= 0) return false;
-  try {
-    kill(pid, 0);
-    return true;
-  } catch (err) {
-    const code = (err as NodeJS.ErrnoException).code;
-    // EPERM means the PID exists but we cannot signal it — treat as alive so
-    // we don't accidentally take over another user's lock.
-    if (code === "EPERM") return true;
-    return false;
-  }
-}
-
 /**
  * Try to atomically create the lock file with mode `0o600` and the current
  * PID as its contents. Returns `true` on success, `false` if the file
@@ -348,9 +325,7 @@ export async function acquireSnapshotLock(
     }
 
     if (isProcessAlive(holder.pid)) {
-      throw new Error(
-        `snapshot in progress (locked by pid ${holder.pid})`,
-      );
+      throw new Error(`snapshot in progress (locked by pid ${holder.pid})`);
     }
 
     // --- Step 3: stale takeover via rename-aside ---

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/bundler/compiler-tools.ts

@@ -15,10 +15,11 @@ import {
   rmSync,
   writeFileSync,
 } from "node:fs";
-import { arch, homedir, platform } from "node:os";
+import { arch, platform } from "node:os";
 import { join } from "node:path";
 
 import { getLogger } from "../util/logger.js";
+import { getWorkspaceDir } from "../util/platform.js";
 import { PromiseGuard } from "../util/promise-guard.js";
 
 const log = getLogger("compiler-tools");
@@ -44,7 +45,7 @@ interface VersionManifest {
 }
 
 function getToolsDir(): string {
-  return join(homedir(), ".vellum", "workspace", "compiler-tools");
+  return join(getWorkspaceDir(), "compiler-tools");
 }
 
 const installGuard = new PromiseGuard<void>();

package/src/calls/call-conversation-messages.ts

@@ -6,6 +6,21 @@
 import { addMessage } from "../memory/conversation-crud.js";
 import { getCallEvents, getCallSession } from "./call-store.js";
 
+function buildCallSummaryLabel(
+  status: string | undefined,
+  duration: number | null,
+  eventCount: number,
+): string {
+  const statusLabel =
+    status === "failed"
+      ? "Call failed"
+      : status === "cancelled"
+        ? "Call cancelled"
+        : "Call completed";
+  const durationStr = duration != null ? ` (${duration}s)` : "";
+  return `**${statusLabel}**${durationStr}. ${eventCount} event(s) recorded.`;
+}
+
 export function buildCallCompletionMessage(callSessionId: string): string {
   const callSession = getCallSession(callSessionId);
   const events = getCallEvents(callSessionId);
@@ -13,25 +28,46 @@ export function buildCallCompletionMessage(callSessionId: string): string {
     callSession?.endedAt && callSession?.startedAt
       ? Math.round((callSession.endedAt - callSession.startedAt) / 1000)
       : null;
-  const durationStr = duration != null ? ` (${duration}s)` : "";
-  const statusLabel =
-    callSession?.status === "failed"
-      ? "Call failed"
-      : callSession?.status === "cancelled"
-        ? "Call cancelled"
-        : "Call completed";
-  return `**${statusLabel}**${durationStr}. ${events.length} event(s) recorded.`;
+  return buildCallSummaryLabel(callSession?.status, duration, events.length);
 }
 
 export async function persistCallCompletionMessage(
   conversationId: string,
   callSessionId: string,
 ): Promise<string> {
-  const summaryText = buildCallCompletionMessage(callSessionId);
+  const callSession = getCallSession(callSessionId);
+  const events = getCallEvents(callSessionId);
+  const duration =
+    callSession?.endedAt && callSession?.startedAt
+      ? Math.round((callSession.endedAt - callSession.startedAt) / 1000)
+      : null;
+  const summaryText = buildCallSummaryLabel(
+    callSession?.status,
+    duration,
+    events.length,
+  );
+
   await addMessage(
     conversationId,
     "assistant",
-    JSON.stringify([{ type: "text", text: summaryText }]),
+    JSON.stringify([
+      {
+        type: "ui_surface",
+        surfaceType: "call_summary",
+        surfaceId: crypto.randomUUID(),
+        completed: true,
+        data: {
+          summaryText,
+          status: callSession?.status ?? "completed",
+          duration,
+          events: events.map((e) => ({
+            eventType: e.eventType,
+            payloadJson: e.payloadJson,
+            createdAt: e.createdAt,
+          })),
+        },
+      },
+    ]),
     {
       userMessageChannel: "phone",
       assistantMessageChannel: "phone",