@vellumai/assistant 0.7.1 → 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/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/relay-server.ts

@@ -14,10 +14,6 @@ import {
   findGuardianForChannel,
   listGuardianChannels,
 } from "../contacts/contact-store.js";
-import {
-  touchContactInteraction,
-  upsertContactChannel,
-} from "../contacts/contacts-write.js";
 import { getAssistantName } from "../daemon/identity-helpers.js";
 import type { ServerMessage } from "../daemon/message-protocol.js";
 import { getCanonicalGuardianRequest } from "../memory/canonical-guardian-store.js";
@@ -615,13 +611,6 @@ export class RelayConnection {
         this.startNameCapture(outcome.assistantId, outcome.fromNumber);
         return;
       case "verification":
-        if (
-          resolved.actorTrust.memberRecord &&
-          (resolved.actorTrust.trustClass === "guardian" ||
-            resolved.actorTrust.trustClass === "trusted_contact")
-        ) {
-          touchContactInteraction(resolved.actorTrust.memberRecord.channel.id);
-        }
         if (this.controller && resolved.actorTrust.trustClass !== "unknown") {
           this.controller.setTrustContext(
             toTrustContext(resolved.actorTrust, msg.from),
@@ -631,15 +620,6 @@ export class RelayConnection {
         return;
       case "normal_call":
         if (outcome.isInbound) {
-          if (
-            resolved.actorTrust.memberRecord &&
-            (resolved.actorTrust.trustClass === "guardian" ||
-              resolved.actorTrust.trustClass === "trusted_contact")
-          ) {
-            touchContactInteraction(
-              resolved.actorTrust.memberRecord.channel.id,
-            );
-          }
           if (this.controller && resolved.actorTrust.trustClass !== "unknown") {
             this.controller.setTrustContext(
               toTrustContext(resolved.actorTrust, msg.from),
@@ -796,8 +776,6 @@ export class RelayConnection {
   private continueCallAfterTrustedContactActivation(params: {
     assistantId: string;
     fromNumber: string;
-    callerName?: string;
-    skipMemberActivation?: boolean;
     activationReason?:
       | "invite_redeemed"
       | "access_approved"
@@ -805,25 +783,10 @@ export class RelayConnection {
     friendName?: string;
     guardianName?: string;
   }): void {
-    const { assistantId, fromNumber, callerName } = params;
-
-    if (!params.skipMemberActivation) {
-      try {
-        upsertContactChannel({
-          sourceChannel: "phone",
-          externalUserId: fromNumber,
-          externalChatId: fromNumber,
-          displayName: callerName,
-          status: "active",
-          policy: "allow",
-        });
-      } catch (err) {
-        log.error(
-          { err, callSessionId: this.callSessionId },
-          "Failed to activate voice caller as trusted contact",
-        );
-      }
-    }
+    const { assistantId, fromNumber } = params;
+
+    // Contact activation is handled by the gateway — the assistant no
+    // longer writes contact/channel records on inbound voice calls.
 
     const updatedTrust = resolveActorTrust({
       assistantId,
@@ -1411,7 +1374,6 @@ export class RelayConnection {
     this.continueCallAfterTrustedContactActivation({
       assistantId,
       fromNumber,
-      callerName: callerName ?? undefined,
       activationReason: "access_approved",
     });
 
@@ -1594,8 +1556,6 @@ export class RelayConnection {
       this.continueCallAfterTrustedContactActivation({
         assistantId: this.inviteRedemptionAssistantId,
         fromNumber: this.inviteRedemptionFromNumber,
-        callerName: this.inviteRedemptionFriendName ?? undefined,
-        skipMemberActivation: true,
         activationReason: "invite_redeemed",
         friendName: this.inviteRedemptionFriendName ?? undefined,
         guardianName: this.inviteRedemptionGuardianName ?? undefined,

package/src/calls/twilio-config.ts

@@ -1,8 +1,4 @@
 import { loadConfig } from "../config/loader.js";
-import {
-  getPublicBaseUrl,
-  getTwilioRelayUrl,
-} from "../inbound/public-ingress-urls.js";
 import { credentialKey } from "../security/credential-key.js";
 import { getSecureKeyAsync } from "../security/secure-keys.js";
 import { ConfigError } from "../util/errors.js";
@@ -14,8 +10,6 @@ export interface TwilioConfig {
   accountSid: string;
   authToken: string;
   phoneNumber: string;
-  webhookBaseUrl: string;
-  wssBaseUrl: string;
 }
 
 /**
@@ -39,19 +33,10 @@ export function resolveTwilioPhoneNumber(): string {
 }
 
 export async function getTwilioConfig(): Promise<TwilioConfig> {
-  const config = loadConfig();
-  const accountSid = config.twilio?.accountSid || "";
+  const accountSid = loadConfig().twilio?.accountSid || "";
   const authToken =
     (await getSecureKeyAsync(credentialKey("twilio", "auth_token"))) || "";
   const phoneNumber = resolveTwilioPhoneNumber();
-  const webhookBaseUrl = getPublicBaseUrl(config);
-
-  let wssBaseUrl: string;
-  try {
-    wssBaseUrl = getTwilioRelayUrl(config);
-  } catch {
-    wssBaseUrl = "";
-  }
 
   if (!accountSid || !authToken) {
     throw new ConfigError(
@@ -64,5 +49,5 @@ export async function getTwilioConfig(): Promise<TwilioConfig> {
 
   log.debug("Twilio config loaded successfully");
 
-  return { accountSid, authToken, phoneNumber, webhookBaseUrl, wssBaseUrl };
+  return { accountSid, authToken, phoneNumber };
 }