@vellumai/assistant 0.3.0

package/src/daemon/connection-policy.ts

@@ -0,0 +1,41 @@
+/**
+ * Connection policy helpers for daemon autostart and authentication behavior.
+ *
+ * When the user targets a remote/forwarded socket via VELLUM_DAEMON_SOCKET,
+ * autostart should be disabled by default to avoid accidentally spawning
+ * a local daemon. VELLUM_DAEMON_AUTOSTART=1 forces autostart regardless.
+ *
+ * Token authentication is always required, even with a socket override.
+ * To explicitly disable auth (e.g. SSH-forwarded sockets where the client
+ * can't read the remote token file), set VELLUM_DAEMON_NOAUTH=1 on both
+ * the daemon and the client. This is an intentional opt-in to an unsafe
+ * mode — never enable it on sockets accessible to untrusted users.
+ */
+
+export function hasSocketOverride(env: Record<string, string | undefined> = process.env): boolean {
+  const override = env.VELLUM_DAEMON_SOCKET?.trim();
+  return !!override;
+}
+
+/**
+ * True when the user has explicitly opted into unauthenticated connections
+ * via VELLUM_DAEMON_NOAUTH=1. This is separate from the socket override
+ * so that using a custom socket path alone does NOT bypass token auth.
+ */
+export function hasNoAuthOverride(env: Record<string, string | undefined> = process.env): boolean {
+  const value = env.VELLUM_DAEMON_NOAUTH?.trim();
+  return value === '1' || value === 'true';
+}
+
+export function shouldAutoStartDaemon(env: Record<string, string | undefined> = process.env): boolean {
+  // Explicit autostart flag takes precedence
+  const autostart = env.VELLUM_DAEMON_AUTOSTART?.trim();
+  if (autostart === '1' || autostart === 'true') return true;
+  if (autostart === '0' || autostart === 'false') return false;
+
+  // No explicit flag: disable autostart when using a remote/custom socket
+  if (hasSocketOverride(env)) return false;
+
+  // Default: autostart enabled
+  return true;
+}

package/src/daemon/date-context.ts

@@ -0,0 +1,136 @@
+/**
+ * Temporal context formatter for future weekday/weekend grounding.
+ *
+ * Produces a compact, deterministic payload describing the current date,
+ * upcoming weekend/work-week windows, and a short horizon of labelled
+ * future dates.  Intended for runtime injection into the model context.
+ */
+
+export interface TemporalContextOptions {
+  /** Override current time (epoch ms) for deterministic tests. */
+  nowMs?: number;
+  /** IANA timezone (e.g. "America/New_York"). Defaults to host timezone. */
+  timeZone?: string;
+  /** Number of future days to list (default 14, hard-capped at 14). */
+  horizonDays?: number;
+}
+
+const MAX_OUTPUT_CHARS = 1500;
+const MAX_HORIZON_ENTRIES = 14;
+
+const WEEKDAY_NAMES = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'] as const;
+
+/**
+ * Get the local date parts for a given instant in the specified timezone.
+ */
+function localDateParts(date: Date, timeZone: string): { year: number; month: number; day: number; weekday: number } {
+  const fmt = new Intl.DateTimeFormat('en-US', {
+    timeZone,
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    weekday: 'short',
+  });
+  const parts = fmt.formatToParts(date);
+  const get = (t: string) => parts.find((p) => p.type === t)?.value ?? '';
+  // Weekday as 0-6 (Sun-Sat)
+  const weekdayShort = get('weekday');
+  const weekdayMap: Record<string, number> = { Sun: 0, Mon: 1, Tue: 2, Wed: 3, Thu: 4, Fri: 5, Sat: 6 };
+  return {
+    year: parseInt(get('year'), 10),
+    month: parseInt(get('month'), 10),
+    day: parseInt(get('day'), 10),
+    weekday: weekdayMap[weekdayShort] ?? 0,
+  };
+}
+
+/**
+ * Format a Date as YYYY-MM-DD in the given timezone.
+ */
+function formatLocalDate(date: Date, timeZone: string): string {
+  const p = localDateParts(date, timeZone);
+  return `${p.year}-${String(p.month).padStart(2, '0')}-${String(p.day).padStart(2, '0')}`;
+}
+
+/**
+ * Advance a date by `days` calendar days in the given timezone.
+ *
+ * Computes the local date, adds days to the day component, then anchors
+ * the result at noon local time to avoid DST-transition edge cases.
+ */
+function addDays(date: Date, days: number, timeZone: string): Date {
+  const parts = localDateParts(date, timeZone);
+  // Use Date.UTC for calendar overflow (e.g. Jan 32 → Feb 1).
+  const ref = new Date(Date.UTC(parts.year, parts.month - 1, parts.day + days));
+  const tY = ref.getUTCFullYear();
+  const tM = ref.getUTCMonth() + 1;
+  const tD = ref.getUTCDate();
+  // Noon UTC covers UTC-12 through ~UTC+11.  For far-east timezones
+  // (UTC+12/+13/+14) noon UTC is already the next local day, so fall
+  // back to midnight UTC which resolves correctly there.
+  const noonUTC = new Date(Date.UTC(tY, tM - 1, tD, 12, 0, 0));
+  const r = localDateParts(noonUTC, timeZone);
+  if (r.year === tY && r.month === tM && r.day === tD) {
+    return noonUTC;
+  }
+  return new Date(Date.UTC(tY, tM - 1, tD, 0, 0, 0));
+}
+
+/**
+ * Build a compact temporal context string for model injection.
+ *
+ * Output is hard-capped at {@link MAX_OUTPUT_CHARS} characters and
+ * {@link MAX_HORIZON_ENTRIES} horizon entries.
+ */
+export function buildTemporalContext(options: TemporalContextOptions = {}): string {
+  const now = new Date(options.nowMs ?? Date.now());
+  const timeZone = options.timeZone ?? Intl.DateTimeFormat().resolvedOptions().timeZone;
+  const horizonDays = Math.min(options.horizonDays ?? MAX_HORIZON_ENTRIES, MAX_HORIZON_ENTRIES);
+
+  const todayParts = localDateParts(now, timeZone);
+  const todayStr = formatLocalDate(now, timeZone);
+  const todayWeekday = WEEKDAY_NAMES[todayParts.weekday];
+
+  // ── Next weekend (Saturday-Sunday) ──
+  const daysUntilSaturday = (6 - todayParts.weekday + 7) % 7 || 7;
+  const nextSaturday = addDays(now, daysUntilSaturday, timeZone);
+  const nextSunday = addDays(now, daysUntilSaturday + 1, timeZone);
+
+  // ── Next work week (Monday-Friday) ──
+  const daysUntilMonday = (1 - todayParts.weekday + 7) % 7 || 7;
+  const nextMonday = addDays(now, daysUntilMonday, timeZone);
+  const nextFriday = addDays(now, daysUntilMonday + 4, timeZone);
+
+  // ── Horizon list ──
+  const horizonLines: string[] = [];
+  for (let i = 1; i <= horizonDays; i++) {
+    const futureDate = addDays(now, i, timeZone);
+    const futureParts = localDateParts(futureDate, timeZone);
+    const label = WEEKDAY_NAMES[futureParts.weekday];
+    horizonLines.push(`  ${formatLocalDate(futureDate, timeZone)} ${label}`);
+  }
+
+  const lines = [
+    `<temporal_context>`,
+    `Today: ${todayStr} (${todayWeekday})`,
+    `Timezone: ${timeZone}`,
+    ``,
+    `Week definitions: work week = Monday–Friday, weekend = Saturday–Sunday`,
+    ``,
+    `Next weekend: ${formatLocalDate(nextSaturday, timeZone)} – ${formatLocalDate(nextSunday, timeZone)}`,
+    `Next work week: ${formatLocalDate(nextMonday, timeZone)} – ${formatLocalDate(nextFriday, timeZone)}`,
+    ``,
+    `Upcoming dates:`,
+    ...horizonLines,
+    `</temporal_context>`,
+  ];
+
+  let output = lines.join('\n');
+
+  // Hard cap: truncate if somehow over budget (shouldn't happen with 14 entries).
+  if (output.length > MAX_OUTPUT_CHARS) {
+    output = output.slice(0, MAX_OUTPUT_CHARS - 25) + '\n</temporal_context>';
+  }
+
+  return output;
+}

package/src/daemon/handlers/apps.ts

@@ -0,0 +1,530 @@
+import * as net from 'node:net';
+import { v4 as uuid } from 'uuid';
+import { existsSync, rmSync, readdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { queryAppRecords, createAppRecord, updateAppRecord, deleteAppRecord, listApps, getApp, getAppPreview, createApp, updateApp } from '../../memory/app-store.js';
+import { computeContentId } from '../../util/content-id.js';
+import { packageApp } from '../../bundler/app-bundler.js';
+import { createSharedAppLink } from '../../memory/shared-app-links-store.js';
+import { defaultGallery } from '../../gallery/default-gallery.js';
+import type {
+  AppDataRequest,
+  BundleAppRequest,
+  SharedAppDeleteRequest,
+  ForkSharedAppRequest,
+  ShareAppCloudRequest,
+  GalleryInstallRequest,
+  AppUpdatePreviewRequest,
+  AppHistoryRequest,
+  AppDiffRequest,
+  AppFileAtVersionRequest,
+  AppRestoreRequest,
+  UiSurfaceShow,
+} from '../ipc-protocol.js';
+import { getAppHistory, getAppDiff, getAppFileAtVersion, restoreAppVersion } from '../../memory/app-git-service.js';
+import { log, compareSemver, createSigningCallback, defineHandlers, type HandlerContext } from './shared.js';
+
+export function handleAppDataRequest(
+  msg: AppDataRequest,
+  socket: net.Socket,
+  ctx: HandlerContext,
+): void {
+  const { surfaceId, callId, method, appId, recordId, data } = msg;
+  try {
+    let result: unknown = null;
+    switch (method) {
+      case 'query':
+        result = queryAppRecords(appId);
+        break;
+      case 'create':
+        if (!data) throw new Error('data is required for create');
+        result = createAppRecord(appId, data);
+        break;
+      case 'update':
+        if (!recordId) throw new Error('recordId is required for update');
+        if (!data) throw new Error('data is required for update');
+        result = updateAppRecord(appId, recordId, data);
+        break;
+      case 'delete':
+        if (!recordId) throw new Error('recordId is required for delete');
+        deleteAppRecord(appId, recordId);
+        result = null;
+        break;
+      default:
+        throw new Error(`Unknown app data method: ${method}`);
+    }
+    ctx.send(socket, {
+      type: 'app_data_response',
+      surfaceId,
+      callId,
+      success: true,
+      result,
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    log.error({ err, method, appId, recordId }, 'Error handling app_data_request');
+    ctx.send(socket, {
+      type: 'app_data_response',
+      surfaceId,
+      callId,
+      success: false,
+      error: message,
+    });
+  }
+}
+
+export function handleAppOpenRequest(msg: { appId: string }, socket: net.Socket, ctx: HandlerContext): void {
+  const appId = msg.appId;
+  if (!appId) {
+    ctx.send(socket, { type: 'error', message: 'app_open_request requires appId' });
+    return;
+  }
+
+  const app = getApp(appId);
+  if (!app) {
+    ctx.send(socket, { type: 'error', message: `App not found: ${appId}` });
+    return;
+  }
+
+  const surfaceId = `app-open-${uuid()}`;
+  ctx.send(socket, {
+    type: 'ui_surface_show',
+    sessionId: 'app-panel',
+    surfaceId,
+    surfaceType: 'dynamic_page',
+    title: app.name,
+    data: { html: app.htmlDefinition, appId: app.id, appType: app.appType },
+    display: 'panel',
+  } as UiSurfaceShow);
+}
+
+export function handleAppUpdatePreview(msg: AppUpdatePreviewRequest, socket: net.Socket, ctx: HandlerContext): void {
+  try {
+    updateApp(msg.appId, { preview: msg.preview });
+    ctx.send(socket, { type: 'app_update_preview_response', success: true, appId: msg.appId });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    log.error({ err }, 'Failed to update app preview');
+    ctx.send(socket, { type: 'error', message: `Failed to update app preview: ${message}` });
+  }
+}
+
+export function handleAppsList(socket: net.Socket, ctx: HandlerContext): void {
+  try {
+    const apps = listApps();
+    ctx.send(socket, {
+      type: 'apps_list_response',
+      apps: apps.map((a) => {
+        const version = a.version ?? '1.0.0';
+        const contentId = computeContentId(a.name);
+        return {
+          id: a.id,
+          name: a.name,
+          description: a.description,
+          icon: a.icon,
+          createdAt: a.createdAt,
+          version,
+          contentId,
+          appType: a.appType,
+        };
+      }),
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    log.error({ err }, 'Failed to list apps');
+    ctx.send(socket, { type: 'error', message: `Failed to list apps: ${message}` });
+  }
+}
+
+export function handleAppPreview(
+  msg: { appId: string },
+  socket: net.Socket,
+  ctx: HandlerContext,
+): void {
+  try {
+    const preview = getAppPreview(msg.appId);
+    ctx.send(socket, {
+      type: 'app_preview_response',
+      appId: msg.appId,
+      preview: preview ?? undefined,
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    log.error({ err, appId: msg.appId }, 'Failed to get app preview');
+    ctx.send(socket, { type: 'error', message: `Failed to get app preview: ${message}` });
+  }
+}
+
+function getSharedAppsDir(): string {
+  return join(homedir(), 'Library', 'Application Support', 'vellum-assistant', 'shared-apps');
+}
+
+export function handleSharedAppsList(socket: net.Socket, ctx: HandlerContext): void {
+  try {
+    const dir = getSharedAppsDir();
+    if (!existsSync(dir)) {
+      ctx.send(socket, { type: 'shared_apps_list_response', apps: [] });
+      return;
+    }
+
+    const files = readdirSync(dir).filter((f) => f.endsWith('-meta.json'));
+    const apps: Array<{
+      uuid: string;
+      name: string;
+      description?: string;
+      icon?: string;
+      preview?: string;
+      entry: string;
+      trustTier: string;
+      signerDisplayName?: string;
+      bundleSizeBytes: number;
+      installedAt: string;
+      version?: string;
+      contentId?: string;
+      forked?: boolean;
+    }> = [];
+
+    for (const file of files) {
+      try {
+        const raw = readFileSync(join(dir, file), 'utf-8');
+        const meta = JSON.parse(raw);
+
+        // Try to read version and content_id from the manifest.json inside the app dir
+        let version: string | undefined;
+        let contentId: string | undefined;
+        const manifestPath = join(dir, meta.uuid, 'manifest.json');
+        if (existsSync(manifestPath)) {
+          try {
+            const manifestRaw = readFileSync(manifestPath, 'utf-8');
+            const manifest = JSON.parse(manifestRaw);
+            version = manifest.version;
+            contentId = manifest.content_id;
+          } catch {
+            // ignore malformed manifest
+          }
+        }
+
+        apps.push({
+          uuid: meta.uuid,
+          name: meta.name,
+          description: meta.description,
+          icon: meta.icon,
+          preview: meta.preview,
+          entry: meta.entry,
+          trustTier: meta.trustTier,
+          signerDisplayName: meta.signerDisplayName,
+          bundleSizeBytes: meta.bundleSizeBytes ?? 0,
+          installedAt: meta.installedAt,
+          version,
+          contentId,
+          forked: meta.forked,
+        });
+      } catch {
+        log.warn({ file }, 'Failed to read shared app metadata file');
+      }
+    }
+
+    // Detect update availability for non-forked shared apps.
+    // Group by contentId, then mark older versions as having an update available.
+    const contentIdVersions = new Map<string, string[]>();
+    for (const app of apps) {
+      if (app.contentId && !app.forked) {
+        const versions = contentIdVersions.get(app.contentId) ?? [];
+        if (app.version) versions.push(app.version);
+        contentIdVersions.set(app.contentId, versions);
+      }
+    }
+
+    // Find the latest version for each contentId
+    const latestVersions = new Map<string, string>();
+    for (const [cid, versions] of contentIdVersions) {
+      if (versions.length > 0) {
+        versions.sort((a, b) => compareSemver(a, b));
+        latestVersions.set(cid, versions[versions.length - 1]);
+      }
+    }
+
+    const result = apps.map((app) => {
+      let updateAvailable = false;
+      if (app.contentId && app.version && !app.forked) {
+        const latest = latestVersions.get(app.contentId);
+        if (latest && compareSemver(app.version, latest) < 0) {
+          updateAvailable = true;
+        }
+      }
+      // Remove the internal forked field before sending
+      const { forked: _, ...rest } = app;
+      return { ...rest, updateAvailable: updateAvailable || undefined };
+    });
+
+    ctx.send(socket, { type: 'shared_apps_list_response', apps: result });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    log.error({ err }, 'Failed to list shared apps');
+    ctx.send(socket, { type: 'error', message: `Failed to list shared apps: ${message}` });
+  }
+}
+
+export function handleSharedAppDelete(
+  msg: SharedAppDeleteRequest,
+  socket: net.Socket,
+  ctx: HandlerContext,
+): void {
+  try {
+    const uuid = msg.uuid;
+    // Validate UUID to prevent path traversal
+    if (uuid.includes('/') || uuid.includes('\\') || uuid.includes('..')) {
+      ctx.send(socket, { type: 'shared_app_delete_response', success: false });
+      return;
+    }
+
+    const dir = getSharedAppsDir();
+    const appDir = join(dir, uuid);
+    const metaFile = join(dir, `${uuid}-meta.json`);
+
+    if (existsSync(appDir)) {
+      rmSync(appDir, { recursive: true });
+    }
+    if (existsSync(metaFile)) {
+      rmSync(metaFile);
+    }
+
+    ctx.send(socket, { type: 'shared_app_delete_response', success: true });
+  } catch (err) {
+    log.error({ err }, 'Failed to delete shared app');
+    ctx.send(socket, { type: 'shared_app_delete_response', success: false });
+  }
+}
+
+export function handleForkSharedApp(
+  msg: ForkSharedAppRequest,
+  socket: net.Socket,
+  ctx: HandlerContext,
+): void {
+  try {
+    const appUuid = msg.uuid;
+    // Validate UUID to prevent path traversal
+    if (appUuid.includes('/') || appUuid.includes('\\') || appUuid.includes('..') || /\s/.test(appUuid)) {
+      ctx.send(socket, { type: 'fork_shared_app_response', success: false, error: 'Invalid UUID' });
+      return;
+    }
+
+    const dir = getSharedAppsDir();
+    const metaFile = join(dir, `${appUuid}-meta.json`);
+
+    if (!existsSync(metaFile)) {
+      ctx.send(socket, { type: 'fork_shared_app_response', success: false, error: 'Shared app not found' });
+      return;
+    }
+
+    const metaRaw = readFileSync(metaFile, 'utf-8');
+    const meta = JSON.parse(metaRaw);
+    const appName = meta.name ?? 'Untitled';
+    const appDescription = meta.description;
+
+    // Read the HTML from the shared app's entry file
+    const entry = meta.entry ?? 'index.html';
+    const htmlPath = join(dir, appUuid, entry);
+
+    if (!existsSync(htmlPath)) {
+      ctx.send(socket, { type: 'fork_shared_app_response', success: false, error: 'Shared app HTML not found' });
+      return;
+    }
+
+    const htmlContent = readFileSync(htmlPath, 'utf-8');
+
+    // Create a new local app via the app store
+    const newApp = createApp({
+      name: `${appName} (Fork)`,
+      description: appDescription,
+      schemaJson: JSON.stringify({ type: 'object', properties: {} }),
+      htmlDefinition: htmlContent,
+    });
+
+    ctx.send(socket, {
+      type: 'fork_shared_app_response',
+      success: true,
+      appId: newApp.id,
+      name: newApp.name,
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    log.error({ err }, 'Failed to fork shared app');
+    ctx.send(socket, { type: 'fork_shared_app_response', success: false, error: message });
+  }
+}
+
+export async function handleShareAppCloud(
+  msg: ShareAppCloudRequest,
+  socket: net.Socket,
+  ctx: HandlerContext,
+): Promise<void> {
+  try {
+    const result = await packageApp(msg.appId, createSigningCallback(socket, ctx));
+    const bundleData = readFileSync(result.bundlePath);
+    const { shareToken } = createSharedAppLink(bundleData, result.manifest);
+
+    const port = process.env.RUNTIME_HTTP_PORT
+      ? parseInt(process.env.RUNTIME_HTTP_PORT, 10)
+      : 7821;
+    const shareUrl = `http://localhost:${port}/v1/apps/shared/${shareToken}`;
+
+    ctx.send(socket, {
+      type: 'share_app_cloud_response',
+      success: true,
+      shareToken,
+      shareUrl,
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    log.error({ err, appId: msg.appId }, 'Failed to share app to cloud');
+    ctx.send(socket, {
+      type: 'share_app_cloud_response',
+      success: false,
+      error: message,
+    });
+  }
+}
+
+export async function handleBundleApp(
+  msg: BundleAppRequest,
+  socket: net.Socket,
+  ctx: HandlerContext,
+): Promise<void> {
+  try {
+    const result = await packageApp(msg.appId, createSigningCallback(socket, ctx));
+    ctx.send(socket, {
+      type: 'bundle_app_response',
+      bundlePath: result.bundlePath,
+      manifest: result.manifest,
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    log.error({ err, appId: msg.appId }, 'Failed to bundle app');
+    ctx.send(socket, { type: 'error', message: `Failed to bundle app: ${message}` });
+  }
+}
+
+export function handleGalleryList(socket: net.Socket, ctx: HandlerContext): void {
+  ctx.send(socket, { type: 'gallery_list_response', gallery: defaultGallery });
+}
+
+export function handleGalleryInstall(
+  msg: GalleryInstallRequest,
+  socket: net.Socket,
+  ctx: HandlerContext,
+): void {
+  try {
+    const galleryApp = defaultGallery.apps.find((a) => a.id === msg.galleryAppId);
+    if (!galleryApp) {
+      ctx.send(socket, {
+        type: 'gallery_install_response',
+        success: false,
+        error: `Gallery app not found: ${msg.galleryAppId}`,
+      });
+      return;
+    }
+
+    const app = createApp({
+      name: galleryApp.name,
+      description: galleryApp.description,
+      schemaJson: galleryApp.schemaJson,
+      htmlDefinition: galleryApp.htmlDefinition,
+    });
+
+    ctx.send(socket, {
+      type: 'gallery_install_response',
+      success: true,
+      appId: app.id,
+      name: app.name,
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    log.error({ err, galleryAppId: msg.galleryAppId }, 'Failed to install gallery app');
+    ctx.send(socket, {
+      type: 'gallery_install_response',
+      success: false,
+      error: message,
+    });
+  }
+}
+
+export async function handleAppHistory(
+  msg: AppHistoryRequest,
+  socket: net.Socket,
+  ctx: HandlerContext,
+): Promise<void> {
+  try {
+    const versions = await getAppHistory(msg.appId, msg.limit);
+    ctx.send(socket, { type: 'app_history_response', appId: msg.appId, versions });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    log.error({ err, appId: msg.appId }, 'Failed to get app history');
+    ctx.send(socket, { type: 'error', message: `Failed to get app history: ${message}` });
+  }
+}
+
+export async function handleAppDiff(
+  msg: AppDiffRequest,
+  socket: net.Socket,
+  ctx: HandlerContext,
+): Promise<void> {
+  try {
+    const diff = await getAppDiff(msg.appId, msg.fromCommit, msg.toCommit);
+    ctx.send(socket, { type: 'app_diff_response', appId: msg.appId, diff });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    log.error({ err, appId: msg.appId }, 'Failed to get app diff');
+    ctx.send(socket, { type: 'error', message: `Failed to get app diff: ${message}` });
+  }
+}
+
+export async function handleAppFileAtVersion(
+  msg: AppFileAtVersionRequest,
+  socket: net.Socket,
+  ctx: HandlerContext,
+): Promise<void> {
+  try {
+    const content = await getAppFileAtVersion(msg.appId, msg.path, msg.commitHash);
+    ctx.send(socket, { type: 'app_file_at_version_response', appId: msg.appId, path: msg.path, content });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    log.error({ err, appId: msg.appId }, 'Failed to get app file at version');
+    ctx.send(socket, { type: 'error', message: `Failed to get app file at version: ${message}` });
+  }
+}
+
+export async function handleAppRestore(
+  msg: AppRestoreRequest,
+  socket: net.Socket,
+  ctx: HandlerContext,
+): Promise<void> {
+  try {
+    await restoreAppVersion(msg.appId, msg.commitHash);
+    ctx.send(socket, { type: 'app_restore_response', success: true });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    log.error({ err, appId: msg.appId }, 'Failed to restore app version');
+    ctx.send(socket, { type: 'app_restore_response', success: false, error: message });
+  }
+}
+
+export const appHandlers = defineHandlers({
+  app_data_request: handleAppDataRequest,
+  app_open_request: handleAppOpenRequest,
+  app_update_preview: handleAppUpdatePreview,
+  app_preview_request: handleAppPreview,
+  apps_list: (_msg, socket, ctx) => handleAppsList(socket, ctx),
+  shared_apps_list: (_msg, socket, ctx) => handleSharedAppsList(socket, ctx),
+  shared_app_delete: handleSharedAppDelete,
+  fork_shared_app: handleForkSharedApp,
+  share_app_cloud: handleShareAppCloud,
+  bundle_app: handleBundleApp,
+  gallery_list: (_msg, socket, ctx) => handleGalleryList(socket, ctx),
+  gallery_install: handleGalleryInstall,
+  app_history_request: handleAppHistory,
+  app_diff_request: handleAppDiff,
+  app_file_at_version_request: handleAppFileAtVersion,
+  app_restore_request: handleAppRestore,
+});