vellum 0.2.12 → 0.2.14

package/src/config/schema.ts

@@ -7,8 +7,19 @@ const VALID_SECRET_ACTIONS = ['redact', 'warn', 'block', 'prompt'] as const;
 const VALID_MEMORY_EMBEDDING_PROVIDERS = ['auto', 'local', 'openai', 'gemini', 'ollama'] as const;
 const VALID_SANDBOX_BACKENDS = ['native', 'docker'] as const;
 const VALID_DOCKER_NETWORKS = ['none', 'bridge'] as const;
-const VALID_PERMISSIONS_MODES = ['legacy', 'strict'] as const;
+const VALID_PERMISSIONS_MODES = ['legacy', 'strict', 'workspace'] as const;
 const VALID_CALL_PROVIDERS = ['twilio'] as const;
+const VALID_CALL_VOICE_MODES = ['twilio_standard', 'twilio_elevenlabs_tts', 'elevenlabs_agent'] as const;
+export const VALID_CALLER_IDENTITY_MODES = ['assistant_number', 'user_number'] as const;
+const VALID_CALL_TRANSCRIPTION_PROVIDERS = ['Deepgram', 'Google'] as const;
+const VALID_MEMORY_ITEM_KINDS = [
+  'preference', 'profile', 'project', 'decision', 'todo',
+  'fact', 'constraint', 'relationship', 'event', 'opinion', 'instruction', 'style',
+] as const;
+
+const DEFAULT_CONFLICTABLE_KINDS = [
+  'preference', 'profile', 'constraint', 'instruction', 'style',
+] as const;
 
 export const TimeoutConfigSchema = z.object({
   shellMaxTimeoutSec: z
@@ -126,7 +137,7 @@ export const PermissionsConfigSchema = z.object({
     .enum(VALID_PERMISSIONS_MODES, {
       error: `permissions.mode must be one of: ${VALID_PERMISSIONS_MODES.join(', ')}`,
     })
-    .default('strict'),
+    .default('workspace'),
 });
 
 export const AuditLogConfigSchema = z.object({
@@ -426,6 +437,11 @@ export const MemoryJobsConfigSchema = z.object({
     .int('memory.jobs.workerConcurrency must be an integer')
     .positive('memory.jobs.workerConcurrency must be a positive integer')
     .default(2),
+  batchSize: z
+    .number({ error: 'memory.jobs.batchSize must be a number' })
+    .int('memory.jobs.batchSize must be an integer')
+    .positive('memory.jobs.batchSize must be a positive integer')
+    .default(10),
 });
 
 export const MemoryRetentionConfigSchema = z.object({
@@ -548,6 +564,17 @@ export const MemoryConflictsConfigSchema = z.object({
     .min(0, 'memory.conflicts.relevanceThreshold must be >= 0')
     .max(1, 'memory.conflicts.relevanceThreshold must be <= 1')
     .default(0.3),
+  askOnIrrelevantTurns: z
+    .boolean({ error: 'memory.conflicts.askOnIrrelevantTurns must be a boolean' })
+    .default(false),
+  conflictableKinds: z
+    .array(
+      z.enum(VALID_MEMORY_ITEM_KINDS, {
+        error: `memory.conflicts.conflictableKinds entries must be one of: ${VALID_MEMORY_ITEM_KINDS.join(', ')}`,
+      }),
+    )
+    .nonempty({ message: 'memory.conflicts.conflictableKinds must not be empty' })
+    .default([...DEFAULT_CONFLICTABLE_KINDS]),
 });
 
 export const MemoryProfileConfigSchema = z.object({
@@ -626,6 +653,7 @@ export const MemoryConfigSchema = z.object({
   }),
   jobs: MemoryJobsConfigSchema.default({
     workerConcurrency: 2,
+    batchSize: 10,
   }),
   retention: MemoryRetentionConfigSchema.default({
     keepRawForever: true,
@@ -667,6 +695,8 @@ export const MemoryConfigSchema = z.object({
     reaskCooldownTurns: 3,
     resolverLlmTimeoutMs: 12000,
     relevanceThreshold: 0.3,
+    askOnIrrelevantTurns: false,
+    conflictableKinds: ['preference', 'profile', 'constraint', 'instruction', 'style'],
   }),
   profile: MemoryProfileConfigSchema.default({
     enabled: true,
@@ -885,6 +915,84 @@ export const CallsSafetyConfigSchema = z.object({
     .default([]),
 });
 
+export const CallsElevenLabsConfigSchema = z.object({
+  voiceId: z
+    .string({ error: 'calls.voice.elevenlabs.voiceId must be a string' })
+    .default(''),
+  voiceModelId: z
+    .string({ error: 'calls.voice.elevenlabs.voiceModelId must be a string' })
+    .default(''),
+  speed: z
+    .number({ error: 'calls.voice.elevenlabs.speed must be a number' })
+    .min(0.7, 'calls.voice.elevenlabs.speed must be >= 0.7')
+    .max(1.2, 'calls.voice.elevenlabs.speed must be <= 1.2')
+    .default(1.0),
+  stability: z
+    .number({ error: 'calls.voice.elevenlabs.stability must be a number' })
+    .min(0, 'calls.voice.elevenlabs.stability must be >= 0')
+    .max(1, 'calls.voice.elevenlabs.stability must be <= 1')
+    .default(0.5),
+  similarityBoost: z
+    .number({ error: 'calls.voice.elevenlabs.similarityBoost must be a number' })
+    .min(0, 'calls.voice.elevenlabs.similarityBoost must be >= 0')
+    .max(1, 'calls.voice.elevenlabs.similarityBoost must be <= 1')
+    .default(0.75),
+  useSpeakerBoost: z
+    .boolean({ error: 'calls.voice.elevenlabs.useSpeakerBoost must be a boolean' })
+    .default(true),
+  agentId: z
+    .string({ error: 'calls.voice.elevenlabs.agentId must be a string' })
+    .default(''),
+  apiBaseUrl: z
+    .string({ error: 'calls.voice.elevenlabs.apiBaseUrl must be a string' })
+    .default('https://api.elevenlabs.io'),
+  registerCallTimeoutMs: z
+    .number({ error: 'calls.voice.elevenlabs.registerCallTimeoutMs must be a number' })
+    .int('calls.voice.elevenlabs.registerCallTimeoutMs must be an integer')
+    .min(1000, 'calls.voice.elevenlabs.registerCallTimeoutMs must be >= 1000')
+    .max(15000, 'calls.voice.elevenlabs.registerCallTimeoutMs must be <= 15000')
+    .default(5000),
+});
+
+export const CallsVoiceConfigSchema = z.object({
+  mode: z
+    .enum(VALID_CALL_VOICE_MODES, {
+      error: `calls.voice.mode must be one of: ${VALID_CALL_VOICE_MODES.join(', ')}`,
+    })
+    .default('twilio_standard'),
+  language: z
+    .string({ error: 'calls.voice.language must be a string' })
+    .default('en-US'),
+  transcriptionProvider: z
+    .enum(VALID_CALL_TRANSCRIPTION_PROVIDERS, {
+      error: `calls.voice.transcriptionProvider must be one of: ${VALID_CALL_TRANSCRIPTION_PROVIDERS.join(', ')}`,
+    })
+    .default('Deepgram'),
+  fallbackToStandardOnError: z
+    .boolean({ error: 'calls.voice.fallbackToStandardOnError must be a boolean' })
+    .default(true),
+  elevenlabs: CallsElevenLabsConfigSchema.default({
+    voiceId: '',
+    voiceModelId: '',
+    speed: 1.0,
+    stability: 0.5,
+    similarityBoost: 0.75,
+    useSpeakerBoost: true,
+    agentId: '',
+    apiBaseUrl: 'https://api.elevenlabs.io',
+    registerCallTimeoutMs: 5000,
+  }),
+});
+
+export const CallerIdentityConfigSchema = z.object({
+  allowPerCallOverride: z
+    .boolean({ error: 'calls.callerIdentity.allowPerCallOverride must be a boolean' })
+    .default(true),
+  userNumber: z
+    .string({ error: 'calls.callerIdentity.userNumber must be a string' })
+    .optional(),
+});
+
 export const CallsConfigSchema = z.object({
   enabled: z
     .boolean({ error: 'calls.enabled must be a boolean' })
@@ -913,6 +1021,29 @@ export const CallsConfigSchema = z.object({
   safety: CallsSafetyConfigSchema.default({
     denyCategories: [],
   }),
+  voice: CallsVoiceConfigSchema.default({
+    mode: 'twilio_standard',
+    language: 'en-US',
+    transcriptionProvider: 'Deepgram',
+    fallbackToStandardOnError: true,
+    elevenlabs: {
+      voiceId: '',
+      voiceModelId: '',
+      speed: 1.0,
+      stability: 0.5,
+      similarityBoost: 0.75,
+      useSpeakerBoost: true,
+      agentId: '',
+      apiBaseUrl: 'https://api.elevenlabs.io',
+      registerCallTimeoutMs: 5000,
+    },
+  }),
+  model: z
+    .string({ error: 'calls.model must be a string' })
+    .optional(),
+  callerIdentity: CallerIdentityConfigSchema.default({
+    allowPerCallOverride: true,
+  }),
 });
 
 export const SkillsConfigSchema = z.object({
@@ -922,15 +1053,30 @@ export const SkillsConfigSchema = z.object({
   allowBundled: z.array(z.string()).nullable().default(null),
 });
 
-export const IngressConfigSchema = z.object({
+const IngressBaseSchema = z.object({
   enabled: z
     .boolean({ error: 'ingress.enabled must be a boolean' })
-    .default(false),
+    .optional(),
   publicBaseUrl: z
     .string({ error: 'ingress.publicBaseUrl must be a string' })
     .default(''),
 });
 
+export const IngressConfigSchema = IngressBaseSchema
+  .default({ publicBaseUrl: '' })
+  .transform((val) => ({
+    ...val,
+    // Backward compatibility: if `enabled` was never explicitly set (undefined),
+    // infer it from whether a publicBaseUrl is configured. Existing users who
+    // have a URL but predate the `enabled` field should not have their webhooks
+    // silently disabled on upgrade.
+    //
+    // When publicBaseUrl is empty and enabled is unset, leave enabled as
+    // undefined so getPublicBaseUrl() can still fall through to the
+    // INGRESS_PUBLIC_BASE_URL env-var fallback (env-only setups).
+    enabled: val.enabled ?? (val.publicBaseUrl ? true : undefined),
+  }));
+
 export const AssistantConfigSchema = z.object({
   provider: z
     .enum(VALID_PROVIDERS, {
@@ -1028,6 +1174,7 @@ export const AssistantConfigSchema = z.object({
     },
     jobs: {
       workerConcurrency: 2,
+      batchSize: 10,
     },
     retention: {
       keepRawForever: true,
@@ -1069,6 +1216,8 @@ export const AssistantConfigSchema = z.object({
       reaskCooldownTurns: 3,
       resolverLlmTimeoutMs: 12000,
       relevanceThreshold: 0.3,
+      askOnIrrelevantTurns: false,
+      conflictableKinds: ['preference', 'profile', 'constraint', 'instruction', 'style'],
     },
     profile: {
       enabled: true,
@@ -1109,7 +1258,7 @@ export const AssistantConfigSchema = z.object({
     blockIngress: true,
   }),
   permissions: PermissionsConfigSchema.default({
-    mode: 'strict',
+    mode: 'workspace',
   }),
   auditLog: AuditLogConfigSchema.default({
     retentionDays: 0,
@@ -1178,11 +1327,28 @@ export const AssistantConfigSchema = z.object({
     safety: {
       denyCategories: [],
     },
+    voice: {
+      mode: 'twilio_standard',
+      language: 'en-US',
+      transcriptionProvider: 'Deepgram',
+      fallbackToStandardOnError: true,
+      elevenlabs: {
+        voiceId: '',
+        voiceModelId: '',
+        speed: 1.0,
+        stability: 0.5,
+        similarityBoost: 0.75,
+        useSpeakerBoost: true,
+        agentId: '',
+        apiBaseUrl: 'https://api.elevenlabs.io',
+        registerCallTimeoutMs: 5000,
+      },
+    },
+    callerIdentity: {
+      allowPerCallOverride: true,
+    },
   }),
-  ingress: IngressConfigSchema.default({
-    enabled: false,
-    publicBaseUrl: '',
-  }),
+  ingress: IngressConfigSchema,
 }).superRefine((config, ctx) => {
   if (config.contextWindow.targetInputTokens >= config.contextWindow.maxInputTokens) {
     ctx.addIssue({
@@ -1243,4 +1409,7 @@ export type WorkspaceGitConfig = z.infer<typeof WorkspaceGitConfigSchema>;
 export type CallsConfig = z.infer<typeof CallsConfigSchema>;
 export type CallsDisclosureConfig = z.infer<typeof CallsDisclosureConfigSchema>;
 export type CallsSafetyConfig = z.infer<typeof CallsSafetyConfigSchema>;
+export type CallsVoiceConfig = z.infer<typeof CallsVoiceConfigSchema>;
+export type CallsElevenLabsConfig = z.infer<typeof CallsElevenLabsConfigSchema>;
+export type CallerIdentityConfig = z.infer<typeof CallerIdentityConfigSchema>;
 export type IngressConfig = z.infer<typeof IngressConfigSchema>;

package/src/config/types.ts

@@ -34,5 +34,8 @@ export type {
   CallsConfig,
   CallsDisclosureConfig,
   CallsSafetyConfig,
+  CallsVoiceConfig,
+  CallsElevenLabsConfig,
+  CallerIdentityConfig,
   IngressConfig,
 } from './schema.js';

package/src/config/vellum-skills/telegram-setup/SKILL.md

@@ -13,90 +13,85 @@ You are helping your user connect a Telegram bot to the Vellum Assistant gateway
 1. **Bot token** from Telegram's @BotFather (the user provides this)
 2. **Gateway webhook URL** — derived from the canonical ingress setting: `${ingress.publicBaseUrl}/webhooks/telegram`. The gateway is the only publicly reachable endpoint; Telegram sends webhooks to the gateway, which validates and forwards them to the assistant runtime internally. If `ingress.publicBaseUrl` is not configured, load and execute the **public-ingress** skill first (`skill_load` with `skill: "public-ingress"`) to set up an ngrok tunnel and persist the URL before continuing.
 
-If the user has already provided the bot token in the conversation, use it directly. Otherwise, ask for it.
+**IMPORTANT — Secure credential collection only:** Never use a bot token that was pasted in plaintext chat. Always collect the bot token through the secure credential prompt flow using `credential_store` with `action: "prompt"` and `service: "telegram"`, `field: "bot_token"`. If the user has already pasted a token in the conversation, inform them that for security reasons you cannot use tokens shared in chat and must collect it through the secure prompt instead.
 
 ## Setup Steps
 
-### Step 1: Verify the Bot Token
+### Step 1: Collect the Bot Token Securely
 
-Use `evaluate_typescript_code` to call the Telegram `getMe` API and confirm the token is valid:
+Collect the bot token through the secure credential prompt:
+- Call `credential_store` with `action: "prompt"`, `service: "telegram"`, `field: "bot_token"`, `label: "Telegram Bot Token"`, `description: "Enter the bot token you received from @BotFather"`, and `placeholder: "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"`.
 
-```typescript
-export default async (input: { token: string }) => {
-  const res = await fetch(`https://api.telegram.org/bot${input.token}/getMe`, { method: 'POST' });
-  return res.json();
-};
-```
+The token is collected securely via a system-level prompt and is never exposed in plaintext chat.
 
-Pass the bot token via `mock_input_json`. Verify the response has `ok: true` and note the bot's username and ID.
+### Step 2: Configure via Daemon
 
-If the token is invalid, tell the user and ask them to double-check it.
+After the token is collected, send it to the daemon's `telegram_config` handler which validates, stores, and configures everything in one step:
 
-### Step 2: Generate a Webhook Secret
+- Send the `telegram_config` IPC message with `action: "set"`. The daemon retrieves the token from secure storage internally when `botToken` is not provided in the message — you do not need to retrieve it yourself.
 
-Use `evaluate_typescript_code` to generate a random secret:
+The daemon's `telegram_config set` handler automatically:
+- Validates the token by calling the Telegram `getMe` API
+- Stores the bot token in secure storage with bot username metadata
+- Generates a webhook secret if one does not already exist
+- Triggers an immediate gateway webhook reconcile
 
-```typescript
-import { randomUUID } from 'node:crypto';
-export default () => ({ secret: randomUUID() });
-```
+If the token is invalid, the daemon returns an error. Tell the user and ask them to re-enter the token via the secure prompt.
 
-Save this value for the next steps.
+### Step 3: Webhook Registration (Automatic)
 
-### Step 3: Register the Webhook
+Manual webhook registration is no longer required. The gateway automatically reconciles the Telegram webhook on startup and whenever credentials change. It compares the current webhook URL against `${INGRESS_PUBLIC_BASE_URL}/webhooks/telegram` and updates it if needed, including the webhook secret and allowed updates.
 
-Use `evaluate_typescript_code` to register the webhook with Telegram:
-
-```typescript
-export default async (input: { token: string; url: string; secret: string }) => {
-  const res = await fetch(`https://api.telegram.org/bot${input.token}/setWebhook`, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({
-      url: input.url,
-      secret_token: input.secret,
-      allowed_updates: ['message', 'edited_message'],
-    }),
-  });
-  return res.json();
-};
-```
-
-Verify the response has `ok: true`.
+If the webhook secret changes (e.g., secret rotation), the gateway's credential watcher detects the change and re-registers the webhook automatically. If the ingress URL changes (e.g., tunnel restart), the assistant daemon triggers an immediate internal reconcile so the webhook re-registers automatically without a gateway restart.
 
 ### Step 4: Register Bot Commands
 
-Use `evaluate_typescript_code` to register the `/new` command:
-
-```typescript
-export default async (input: { token: string }) => {
-  const res = await fetch(`https://api.telegram.org/bot${input.token}/setMyCommands`, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({
-      commands: [{ command: 'new', description: 'Start a new conversation' }],
-    }),
-  });
-  return res.json();
-};
-```
+Send the `telegram_config` IPC message with `action: "set_commands"` to register the `/new` command. The daemon handles token retrieval from secure storage internally — you do not need to retrieve it yourself.
 
-### Step 5: Store Credentials
+### Step 5: Validate Routing Configuration
 
-Use `credential_store` twice to securely save the credentials:
+Verify that the gateway routing is configured to deliver inbound messages to the assistant:
 
-1. **Store the bot token:**
-   - action: `store`, service: `telegram`, field: `bot_token`, value: the bot token
+- In **single-assistant mode** (the default local deployment), routing is automatically configured. The CLI sets `GATEWAY_UNMAPPED_POLICY=default` and `GATEWAY_DEFAULT_ASSISTANT_ID` to the current assistant's ID when starting the gateway, so no manual routing configuration is needed.
+- In **multi-assistant mode**, the operator must set `GATEWAY_ASSISTANT_ROUTING_JSON` to map specific chat IDs or user IDs to assistant IDs, or configure a default assistant via `GATEWAY_DEFAULT_ASSISTANT_ID` with `GATEWAY_UNMAPPED_POLICY=default`.
 
-2. **Store the webhook secret:**
-   - action: `store`, service: `telegram`, field: `webhook_secret`, value: the generated secret
+If routing is misconfigured, inbound Telegram messages will be rejected and the gateway will send a visible notice to the chat explaining the issue (rate-limited to once per 5 minutes per chat).
 
 ### Step 6: Report Success
 
 Summarize what was done:
-- Bot verified: @username (ID: nnn)
-- Webhook registered at the provided URL
+- Bot verified and credentials stored securely via daemon
+- Webhook registration: handled automatically by the gateway
 - Bot commands registered: /new
-- Credentials stored securely in the vault
+- Routing configuration validated
+
+The gateway automatically detects credentials from the vault, reconciles the Telegram webhook registration, and begins accepting Telegram webhooks shortly. In single-assistant mode, routing is automatically configured — no manual environment variable configuration or webhook registration is needed. If the webhook secret changes later, the gateway's credential watcher will automatically re-register the webhook. If the ingress URL changes (e.g., tunnel restart), the assistant daemon triggers an immediate internal reconcile so the webhook re-registers automatically without a gateway restart.
+
+## Bot-Account Limitations
+
+Telegram bot accounts have inherent limitations imposed by the Bot API:
+
+- **No arbitrary messaging**: Bots cannot initiate conversations with users who have not first interacted with the bot (sent `/start` or added it to a group). Messaging arbitrary phone numbers is not possible.
+- **No conversation listing**: The Bot API does not expose a method to enumerate the chats a bot belongs to.
+- **No message history retrieval**: Bots cannot fetch past messages from a chat.
+- **No message search**: No search API is available for bots.
+
+These limitations apply to all Telegram bots regardless of configuration. Future support for MTProto user-account sessions may lift some of these restrictions.
+
+## Automated vs Manual Steps
+
+The following steps are now **automated** by the gateway and CLI:
+
+| Step | Status | Details |
+|------|--------|---------|
+| Webhook registration | Automated | The gateway reconciles the webhook URL on startup and when credentials change |
+| Routing configuration | Automated (single-assistant) | The CLI sets `GATEWAY_UNMAPPED_POLICY=default` and `GATEWAY_DEFAULT_ASSISTANT_ID` automatically |
+| Credential detection | Automated | The gateway watches the credential vault for changes |
+
+The following steps still require **manual** action:
 
-The gateway automatically detects credentials from the vault and will begin accepting Telegram webhooks shortly. No manual environment variable configuration is needed.
+| Step | Details |
+|------|---------|
+| Bot token from @BotFather | User must create a bot and provide the token via secure prompt |
+| Bot command registration | Registered via the setup skill (Step 4 above) |
+| Multi-assistant routing | Requires manual `GATEWAY_ASSISTANT_ROUTING_JSON` configuration |

package/src/daemon/assistant-attachments.ts

@@ -320,8 +320,10 @@ export function drainDirectiveDisplayBuffer(buffer: string): DirectiveDisplayDra
       // streaming mode more data may arrive in the next chunk — eagerly
       // trimming would merge words across the directive boundary.
       const nextChar = buffer[end + 2];
-      if (emitText.endsWith('\n') && (nextChar === '\n' || nextChar === '\r')) {
-        emitText = emitText.slice(0, -1);
+      if (emitText.endsWith('\r\n') && nextChar === '\r') {
+        emitText = emitText.slice(0, -2); // trim full \r\n
+      } else if (emitText.endsWith('\n') && (nextChar === '\n' || nextChar === '\r')) {
+        emitText = emitText.slice(0, -1); // trim \n
       }
     }
 

package/src/daemon/handlers/apps.ts

@@ -16,8 +16,13 @@ import type {
   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(
@@ -445,6 +450,66 @@ export function handleGalleryInstall(
   }
 }
 
+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,
@@ -458,4 +523,8 @@ export const appHandlers = defineHandlers({
   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,
 });