@vellumai/assistant 0.3.5 → 0.3.7

package/src/daemon/handlers/diagnostics.ts

@@ -61,7 +61,7 @@ const SENSITIVE_KEYS = new Set([
 function redactDeep(value: unknown): unknown {
   if (typeof value === 'string') return redact(value);
   if (Array.isArray(value)) return value.map(redactDeep);
-  if (value !== null && typeof value === 'object') {
+  if (value != null && typeof value === 'object') {
     const out: Record<string, unknown> = {};
     for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
       if (SENSITIVE_KEYS.has(k.toLowerCase())) {

package/src/daemon/handlers/dictation.ts

@@ -1,6 +1,5 @@
 import * as net from 'node:net';
-import { getConfig } from '../../config/loader.js';
-import { getFailoverProvider, listProviders } from '../../providers/registry.js';
+import { getConfiguredProvider } from '../../providers/provider-send-message.js';
 import type { DictationRequest } from '../ipc-protocol.js';
 import { log, defineHandlers, type HandlerContext } from './shared.js';
 
@@ -147,15 +146,14 @@ export async function handleDictationRequest(
     : msg.transcription; // command prompt already embeds the selected text and instruction
 
   try {
-    const config = getConfig();
-    if (!listProviders().includes(config.provider)) {
-      log.warn({ provider: config.provider }, 'Dictation: no provider available, returning raw transcription');
+    const provider = getConfiguredProvider();
+    if (!provider) {
+      log.warn('Dictation: no provider available, returning raw transcription');
       const fallbackText = mode === 'command' ? (msg.context.selectedText ?? msg.transcription) : msg.transcription;
       ctx.send(socket, { type: 'dictation_response', text: fallbackText, mode });
       return;
     }
 
-    const provider = getFailoverProvider(config.provider, config.providerOrder);
     const response = await provider.sendMessage(
       [{ role: 'user', content: [{ type: 'text', text: userText }] }],
       [], // no tools

package/src/daemon/handlers/documents.ts

@@ -2,12 +2,23 @@ import { defineHandlers } from './shared.js';
 import type { HandlerContext } from './shared.js';
 import type { DocumentSaveRequest, DocumentLoadRequest, DocumentListRequest } from '../ipc-protocol.js';
 import type * as net from 'node:net';
-import type { Database } from 'bun:sqlite';
-import { getDb } from '../../memory/db.js';
+import { rawRun, rawGet, rawAll } from '../../memory/db.js';
 import { getLogger } from '../../util/logger.js';
 
 const log = getLogger('documents');
 
+interface DocumentRow {
+  surface_id: string;
+  conversation_id: string;
+  title: string;
+  content: string;
+  word_count: number;
+  created_at: number;
+  updated_at: number;
+}
+
+type DocumentListRow = Omit<DocumentRow, 'content'>;
+
 export function handleDocumentSave(msg: DocumentSaveRequest, socket: net.Socket, ctx: HandlerContext): void {
   log.info({
     surfaceId: msg.surfaceId,
@@ -18,13 +29,9 @@ export function handleDocumentSave(msg: DocumentSaveRequest, socket: net.Socket,
   }, 'Received save request');
 
   try {
-    const db = getDb();
-    // Get the raw SQLite client from Drizzle
-    const sqlite = (db as unknown as { $client: Database }).$client;
     const now = Date.now();
 
-    // Upsert document (insert or update if exists)
-    sqlite.run(
+    rawRun(
       `INSERT INTO documents (surface_id, conversation_id, title, content, word_count, created_at, updated_at)
        VALUES (?, ?, ?, ?, ?, ?, ?)
        ON CONFLICT(surface_id) DO UPDATE SET
@@ -32,7 +39,7 @@ export function handleDocumentSave(msg: DocumentSaveRequest, socket: net.Socket,
          content = excluded.content,
          word_count = excluded.word_count,
          updated_at = excluded.updated_at`,
-      [msg.surfaceId, msg.conversationId, msg.title, msg.content, msg.wordCount, now, now]
+      msg.surfaceId, msg.conversationId, msg.title, msg.content, msg.wordCount, now, now,
     );
 
     ctx.send(socket, {
@@ -55,22 +62,11 @@ export function handleDocumentSave(msg: DocumentSaveRequest, socket: net.Socket,
 
 export function handleDocumentLoad(msg: DocumentLoadRequest, socket: net.Socket, ctx: HandlerContext): void {
   try {
-    const db = getDb();
-    const sqlite = (db as unknown as { $client: Database }).$client;
-
-    const result = sqlite.prepare(/*sql*/ `
+    const result = rawGet<DocumentRow>(/*sql*/ `
       SELECT surface_id, conversation_id, title, content, word_count, created_at, updated_at
       FROM documents
       WHERE surface_id = ?
-    `).get(msg.surfaceId) as {
-      surface_id: string;
-      conversation_id: string;
-      title: string;
-      content: string;
-      word_count: number;
-      created_at: number;
-      updated_at: number;
-    } | undefined;
+    `, msg.surfaceId);
 
     if (result) {
       ctx.send(socket, {
@@ -119,9 +115,6 @@ export function handleDocumentLoad(msg: DocumentLoadRequest, socket: net.Socket,
 
 export function handleDocumentList(msg: DocumentListRequest, socket: net.Socket, ctx: HandlerContext): void {
   try {
-    const db = getDb();
-    const sqlite = (db as unknown as { $client: Database }).$client;
-
     let query = /*sql*/ `
       SELECT surface_id, conversation_id, title, word_count, created_at, updated_at
       FROM documents
@@ -135,14 +128,7 @@ export function handleDocumentList(msg: DocumentListRequest, socket: net.Socket,
 
     query += ' ORDER BY updated_at DESC';
 
-    const results = sqlite.prepare(query).all(...params) as Array<{
-      surface_id: string;
-      conversation_id: string;
-      title: string;
-      word_count: number;
-      created_at: number;
-      updated_at: number;
-    }>;
+    const results = rawAll<DocumentListRow>(query, ...params);
 
     ctx.send(socket, {
       type: 'document_list_response',

package/src/daemon/handlers/index.ts

@@ -23,6 +23,8 @@ import { twitterAuthHandlers } from './twitter-auth.js';
 import { workspaceFileHandlers } from './workspace-files.js';
 import { identityHandlers } from './identity.js';
 import { dictationHandlers } from './dictation.js';
+import { inboxInviteHandlers } from './config-inbox.js';
+import { pairingHandlers } from './pairing.js';
 
 // Re-export types and utilities for backwards compatibility
 export type {
@@ -88,6 +90,11 @@ const inlineHandlers = defineHandlers({
   },
   integration_disconnect: () => { /* no-op — integration registry removed */ },
 
+  // Stub handler: assistant_inbox — real implementation will be added in a follow-up PR.
+  assistant_inbox: (_msg, socket, ctx) => {
+    ctx.send(socket, { type: 'assistant_inbox_response', success: false, error: 'Not yet implemented' });
+  },
+
 });
 
 const handlers = {
@@ -109,6 +116,8 @@ const handlers = {
   ...workspaceFileHandlers,
   ...identityHandlers,
   ...dictationHandlers,
+  ...inboxInviteHandlers,
+  ...pairingHandlers,
   ...inlineHandlers,
 } satisfies DispatchMap;
 

package/src/daemon/handlers/misc.ts

@@ -3,8 +3,7 @@ import { v4 as uuid } from 'uuid';
 import { readFileSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import * as conversationStore from '../../memory/conversation-store.js';
-import { getConfig } from '../../config/loader.js';
-import { getFailoverProvider, listProviders } from '../../providers/registry.js';
+import { getConfiguredProvider } from '../../providers/provider-send-message.js';
 import type { Provider } from '../../providers/types.js';
 import { classifyInteraction } from '../classifier.js';
 import { checkIngressForSecrets } from '../../security/secret-ingress.js';
@@ -172,10 +171,9 @@ export async function handleSuggestionRequest(
     }
 
     // Try LLM suggestion using the configured provider
-    const config = getConfig();
-    if (listProviders().includes(config.provider)) {
+    const provider = getConfiguredProvider();
+    if (provider) {
       try {
-        const provider = getFailoverProvider(config.provider, config.providerOrder);
         let promise = suggestionInFlight.get(m.id);
         if (!promise) {
           promise = generateSuggestion(provider, text);

package/src/daemon/handlers/pairing.ts

@@ -0,0 +1,98 @@
+import * as net from 'node:net';
+import type {
+  PairingApprovalResponse,
+  ApprovedDeviceRemove,
+} from '../ipc-protocol.js';
+import { log, defineHandlers, type HandlerContext } from './shared.js';
+import {
+  approveDevice,
+  removeDevice,
+  clearAllDevices,
+  listDevices,
+} from '../approved-devices-store.js';
+import type { PairingStore } from '../pairing-store.js';
+
+/** Module-level reference set by the daemon server at startup. */
+let pairingStoreRef: PairingStore | null = null;
+let bearerTokenRef: string | undefined;
+
+export function initPairingHandlers(store: PairingStore, bearerToken: string | undefined): void {
+  pairingStoreRef = store;
+  bearerTokenRef = bearerToken;
+}
+
+function handlePairingApprovalResponse(
+  msg: PairingApprovalResponse,
+  _socket: net.Socket,
+  _ctx: HandlerContext,
+): void {
+  if (!pairingStoreRef) {
+    log.warn('Pairing store not initialized');
+    return;
+  }
+
+  const entry = pairingStoreRef.get(msg.pairingRequestId);
+  if (!entry) {
+    log.warn({ pairingRequestId: msg.pairingRequestId }, 'Pairing request not found for approval response');
+    return;
+  }
+
+  // Idempotent: if already approved/denied, just re-broadcast the current status
+  if (entry.status === 'approved' || entry.status === 'denied') {
+    log.info({ pairingRequestId: msg.pairingRequestId, status: entry.status }, 'Duplicate approval response, no-op');
+    return;
+  }
+
+  if (msg.decision === 'deny') {
+    pairingStoreRef.deny(msg.pairingRequestId);
+    log.info({ pairingRequestId: msg.pairingRequestId }, 'Pairing request denied');
+    return;
+  }
+
+  // approve_once or always_allow
+  if (!bearerTokenRef) {
+    log.error('Cannot approve pairing: no bearer token configured');
+    return;
+  }
+
+  pairingStoreRef.approve(msg.pairingRequestId, bearerTokenRef);
+  log.info({ pairingRequestId: msg.pairingRequestId, decision: msg.decision }, 'Pairing request approved');
+
+  // If always_allow, persist the device to the allowlist
+  if (msg.decision === 'always_allow' && entry.hashedDeviceId) {
+    approveDevice(entry.hashedDeviceId, entry.deviceName ?? 'Unknown Device');
+  }
+}
+
+function handleApprovedDevicesList(socket: net.Socket, ctx: HandlerContext): void {
+  const devices = listDevices();
+  ctx.send(socket, {
+    type: 'approved_devices_list_response',
+    devices,
+  });
+}
+
+function handleApprovedDeviceRemove(
+  msg: ApprovedDeviceRemove,
+  socket: net.Socket,
+  ctx: HandlerContext,
+): void {
+  const success = removeDevice(msg.hashedDeviceId);
+  ctx.send(socket, {
+    type: 'approved_device_remove_response',
+    success,
+  });
+  log.info({ hashedDeviceId: msg.hashedDeviceId, success }, 'Device removal requested via IPC');
+}
+
+function handleApprovedDevicesClear(_socket: net.Socket, _ctx: HandlerContext): void {
+  clearAllDevices();
+  log.info('All approved devices cleared via IPC');
+}
+
+export const pairingHandlers = defineHandlers({
+  pairing_approval_response: handlePairingApprovalResponse,
+  approved_devices_list: (_msg, socket, ctx) => handleApprovedDevicesList(socket, ctx),
+  approved_device_remove: handleApprovedDeviceRemove,
+  approved_devices_clear: (_msg, socket, ctx) => handleApprovedDevicesClear(socket, ctx),
+});

package/src/daemon/handlers/sessions.ts

@@ -1,4 +1,6 @@
 import * as net from 'node:net';
+import { isChannelId, parseChannelId } from '../../channels/types.js';
+import { silentlyWithLog } from '../../util/silently.js';
 import { v4 as uuid } from 'uuid';
 import * as conversationStore from '../../memory/conversation-store.js';
 import * as externalConversationStore from '../../memory/external-conversation-store.js';
@@ -14,6 +16,7 @@ import type {
   SecretResponse,
   SessionCreateRequest,
   SessionSwitchRequest,
+  SessionRenameRequest,
   CancelRequest,
   DeleteQueuedMessage,
   HistoryRequest,
@@ -22,6 +25,7 @@ import type {
   UsageRequest,
   SandboxSetRequest,
   ServerMessage,
+  ConversationSearchRequest,
 } from '../ipc-protocol.js';
 import { getConfig } from '../../config/loader.js';
 import { getSubagentManager } from '../../subagent/index.js';
@@ -80,7 +84,20 @@ export async function handleUserMessage(
       attributes: { source: 'user_message' },
     });
 
-    const result = session.enqueueMessage(msg.content ?? '', msg.attachments ?? [], sendEvent, requestId, msg.activeSurfaceId, msg.currentPage);
+    const ipcChannel = parseChannelId(msg.channel) ?? 'macos';
+    const queuedChannelMetadata = {
+      userMessageChannel: ipcChannel,
+      assistantMessageChannel: ipcChannel,
+    };
+    const result = session.enqueueMessage(
+      msg.content ?? '',
+      msg.attachments ?? [],
+      sendEvent,
+      requestId,
+      msg.activeSurfaceId,
+      msg.currentPage,
+      queuedChannelMetadata,
+    );
     if (result.rejected) {
       rlog.warn('Message rejected — queue is full');
       session.traceEmitter.emit('request_error', 'Message rejected — queue is full', {
@@ -114,8 +131,13 @@ export async function handleUserMessage(
     }
 
     rlog.info('Processing user message');
+    session.setTurnChannelContext({
+      userMessageChannel: ipcChannel,
+      assistantMessageChannel: ipcChannel,
+    });
     session.setAssistantId('self');
     session.setGuardianContext(null);
+    session.setCommandIntent(null);
     // Fire-and-forget: don't block the IPC handler so the connection can
     // continue receiving messages (e.g. cancel, confirmations, or
     // additional user_message that will be queued by the session).
@@ -210,12 +232,14 @@ export function handleSessionList(socket: net.Socket, ctx: HandlerContext, offse
     type: 'session_list_response',
     sessions: conversations.map((c) => {
       const binding = bindings.get(c.id);
+      const originChannel = parseChannelId(c.originChannel);
       return {
         id: c.id,
         title: c.title ?? 'Untitled',
         updatedAt: c.updatedAt,
         threadType: normalizeThreadType(c.threadType),
-        ...(binding ? {
+        source: c.source ?? 'user',
+        ...(binding && isChannelId(binding.sourceChannel) ? {
           channelBinding: {
             sourceChannel: binding.sourceChannel,
             externalChatId: binding.externalChatId,
@@ -224,6 +248,7 @@ export function handleSessionList(socket: net.Socket, ctx: HandlerContext, offse
             username: binding.username,
           },
         } : {}),
+        ...(originChannel ? { conversationOriginChannel: originChannel } : {}),
       };
     }),
     hasMore: offset + conversations.length < totalCount,
@@ -276,6 +301,11 @@ export async function handleSessionCreate(
     ctx.socketToSession.set(socket, conversation.id);
     const sendEvent = (event: ServerMessage) => ctx.send(socket, event);
     const requestId = uuid();
+    const transportChannel = parseChannelId(msg.transport?.channelId) ?? 'macos';
+    session.setTurnChannelContext({
+      userMessageChannel: transportChannel,
+      assistantMessageChannel: transportChannel,
+    });
     session.processMessage(msg.initialMessage, [], sendEvent, requestId).catch((err) => {
       const message = err instanceof Error ? err.message : String(err);
       log.error({ err, sessionId: conversation.id }, 'Error processing initial message');
@@ -323,6 +353,24 @@ export async function handleSessionSwitch(
   });
 }
 
+export function handleSessionRename(
+  msg: SessionRenameRequest,
+  socket: net.Socket,
+  ctx: HandlerContext,
+): void {
+  const conversation = conversationStore.getConversation(msg.sessionId);
+  if (!conversation) {
+    ctx.send(socket, { type: 'error', message: `Session ${msg.sessionId} not found` });
+    return;
+  }
+  conversationStore.updateConversationTitle(msg.sessionId, msg.title);
+  ctx.send(socket, {
+    type: 'session_title_updated',
+    sessionId: msg.sessionId,
+    title: msg.title,
+  });
+}
+
 export function handleCancel(msg: CancelRequest, socket: net.Socket, ctx: HandlerContext): void {
   const sessionId = msg.sessionId || ctx.socketToSession.get(socket);
   if (sessionId) {
@@ -403,9 +451,12 @@ export function handleHistoryRequest(
           if (a.mimeType.startsWith('video/') && !a.thumbnailBase64) {
             const attachmentId = a.id;
             const base64 = a.dataBase64;
-            generateVideoThumbnail(base64).then((thumb) => {
-              if (thumb) setAttachmentThumbnail(attachmentId, thumb);
-            }).catch(() => {});
+            silentlyWithLog(
+              generateVideoThumbnail(base64).then((thumb) => {
+                if (thumb) setAttachmentThumbnail(attachmentId, thumb);
+              }),
+              'video thumbnail generation',
+            );
           }
 
           return {
@@ -541,6 +592,22 @@ export function handleDeleteQueuedMessage(
   }
 }
 
+export function handleConversationSearch(
+  msg: ConversationSearchRequest,
+  socket: net.Socket,
+  ctx: HandlerContext,
+): void {
+  const results = conversationStore.searchConversations(msg.query, {
+    limit: msg.limit,
+    maxMessagesPerConversation: msg.maxMessagesPerConversation,
+  });
+  ctx.send(socket, {
+    type: 'conversation_search_response',
+    query: msg.query,
+    results,
+  });
+}
+
 export const sessionHandlers = defineHandlers({
   user_message: handleUserMessage,
   confirmation_response: handleConfirmationResponse,
@@ -549,6 +616,7 @@ export const sessionHandlers = defineHandlers({
   session_create: handleSessionCreate,
   sessions_clear: (_msg, socket, ctx) => handleSessionsClear(socket, ctx),
   session_switch: handleSessionSwitch,
+  session_rename: handleSessionRename,
   cancel: handleCancel,
   delete_queued_message: handleDeleteQueuedMessage,
   history_request: handleHistoryRequest,
@@ -556,4 +624,5 @@ export const sessionHandlers = defineHandlers({
   regenerate: handleRegenerate,
   usage_request: handleUsageRequest,
   sandbox_set: handleSandboxSet,
+  conversation_search: handleConversationSearch,
 });

package/src/daemon/handlers/shared.ts

@@ -105,6 +105,8 @@ export interface SessionCreateOptions {
   memoryScopeId?: string;
   isPrivateThread?: boolean;
   strictPrivateSideEffects?: boolean;
+  /** Channel command intent metadata (e.g. Telegram /start). */
+  commandIntent?: { type: string; payload?: string; languageCode?: string };
 }
 
 /**
@@ -252,7 +254,7 @@ export function wireEscalationHandler(
 }
 
 export function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null;
+  return typeof value === 'object' && value != null;
 }
 
 export function formatBytes(sizeBytes: number): string {

package/src/daemon/handlers/skills.ts

@@ -423,7 +423,7 @@ export async function handleSkillsSearch(
   ctx: HandlerContext,
 ): Promise<void> {
   try {
-    // Search vellum-skills catalog (remote with bundled fallback)
+    // Search vellum-skills catalog (platform API with bundled fallback)
     const catalogEntries = await listCatalogEntries();
     const query = (msg.query ?? '').toLowerCase();
     const matchingCatalog = catalogEntries.filter((e) => {

package/src/daemon/handlers/twitter-auth.ts

@@ -72,6 +72,7 @@ export async function handleTwitterAuthStart(
       clientId,
       clientSecret,
       extraParams: {},
+      tokenEndpointAuthMethod: clientSecret ? 'client_secret_basic' : undefined,
     };
 
     const result = await startOAuth2Flow(oauthConfig, {
@@ -131,6 +132,7 @@ export async function handleTwitterAuthStart(
       oauth2TokenUrl: 'https://api.x.com/2/oauth2/token',
       oauth2ClientId: clientId,
       oauth2ClientSecret: clientSecret ?? null,
+      oauth2TokenEndpointAuthMethod: clientSecret ? 'client_secret_basic' : undefined,
       grantedScopes: result.grantedScopes,
       expiresAt: result.tokens.expiresIn ? Date.now() + result.tokens.expiresIn * 1000 : null,
     });

package/src/daemon/handlers/work-items.ts

@@ -393,7 +393,7 @@ export async function handleWorkItemRunTask(
   // Compute required tools using the same resolution logic as preflight:
   // work-item snapshot first, then task template, then all registered tools.
   let requiredTools: string[];
-  if (workItem.requiredTools !== null && workItem.requiredTools !== undefined) {
+  if (workItem.requiredTools != null) {
     requiredTools = sanitizeToolList(JSON.parse(workItem.requiredTools));
   } else {
     requiredTools = task.requiredTools
@@ -513,7 +513,7 @@ export async function handleWorkItemPreflight(
   // back to the task template (or all registered tools) when the
   // snapshot is null.
   let requiredTools: string[];
-  if (workItem.requiredTools !== null && workItem.requiredTools !== undefined) {
+  if (workItem.requiredTools != null) {
     requiredTools = sanitizeToolList(JSON.parse(workItem.requiredTools));
   } else {
     const task = getTask(workItem.taskId);

package/src/daemon/handlers/workspace-files.ts

@@ -1,6 +1,7 @@
 import * as net from 'node:net';
-import { existsSync, readFileSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import { join, resolve, sep } from 'node:path';
+import { pathExists } from '../../util/fs.js';
 import { getWorkspaceDir } from '../../util/platform.js';
 import { log, defineHandlers, type HandlerContext } from './shared.js';
 import type { WorkspaceFileReadRequest } from '../ipc-protocol.js';
@@ -13,7 +14,7 @@ function handleWorkspaceFilesList(socket: net.Socket, ctx: HandlerContext): void
   const files = WORKSPACE_FILES.map((name) => ({
     path: name,
     name,
-    exists: existsSync(join(base, name)),
+    exists: pathExists(join(base, name)),
   }));
   ctx.send(socket, { type: 'workspace_files_list_response', files });
 }
@@ -42,7 +43,7 @@ function handleWorkspaceFileRead(
   }
 
   try {
-    if (!existsSync(resolved)) {
+    if (!pathExists(resolved)) {
       ctx.send(socket, {
         type: 'workspace_file_read_response',
         path: requested,

package/src/daemon/install-cli-launchers.ts

@@ -0,0 +1,113 @@
+/**
+ * Installs standalone CLI launcher scripts in ~/.vellum/bin/ so that
+ * integration commands (e.g. `doordash`, `map`) can be invoked directly
+ * without requiring `vellum` on PATH.
+ *
+ * Each launcher is a shell script that hardcodes absolute paths to `bun`
+ * and the CLI entrypoint, forwarding all arguments to the appropriate
+ * subcommand.
+ */
+
+import { execSync } from 'node:child_process';
+import { existsSync, mkdirSync, writeFileSync, chmodSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { getLogger } from '../util/logger.js';
+
+const log = getLogger('install-cli-launchers');
+
+/** Integration subcommands that should get standalone launchers. */
+const INTEGRATION_COMMANDS = ['doordash', 'map'];
+
+/**
+ * Resolve the absolute path to the bun binary.
+ * Prefers process.execPath (works when running under bun), then falls
+ * back to `which bun`.
+ */
+function resolveBunPath(): string {
+  // process.execPath points to the bun binary when running under bun
+  if (process.execPath && process.execPath.includes('bun')) {
+    return process.execPath;
+  }
+  try {
+    return execSync('which bun', { encoding: 'utf-8' }).trim();
+  } catch {
+    throw new Error('Could not find bun binary');
+  }
+}
+
+/**
+ * Resolve the absolute path to the CLI entrypoint (index.ts).
+ * Uses import.meta.dirname to find the source tree root.
+ */
+function resolveCliEntrypoint(): string {
+  // This file is at assistant/src/daemon/install-cli-launchers.ts
+  // The CLI entrypoint is at assistant/src/index.ts
+  const thisDir = import.meta.dirname ?? __dirname;
+  return join(thisDir, '..', 'index.ts');
+}
+
+/**
+ * Check whether a given command name conflicts with an existing system
+ * binary (i.e. something other than our own launcher).
+ */
+function hasSystemConflict(name: string, binDir: string): boolean {
+  try {
+    const result = execSync(`which ${name}`, { encoding: 'utf-8' }).trim();
+    // If `which` resolves to our own bin dir, that's not a conflict
+    if (result.startsWith(binDir)) return false;
+    return true;
+  } catch {
+    // `which` failed — no conflict
+    return false;
+  }
+}
+
+/**
+ * Install standalone CLI launcher scripts in ~/.vellum/bin/.
+ *
+ * For each integration command, generates a shell script that execs
+ * bun with the CLI entrypoint and the subcommand name prepended.
+ * Uses the short name by default (e.g. `doordash`), falling back to
+ * `vellum-<name>` if the short name conflicts with an existing system binary.
+ */
+export function installCliLaunchers(): void {
+  const binDir = join(homedir(), '.vellum', 'bin');
+
+  let bunPath: string;
+  try {
+    bunPath = resolveBunPath();
+  } catch (err) {
+    log.warn({ err }, 'Cannot install CLI launchers: bun not found');
+    return;
+  }
+
+  const entrypoint = resolveCliEntrypoint();
+  if (!existsSync(entrypoint)) {
+    // In compiled builds (e.g. macOS app via `bun build --compile`), the
+    // source tree isn't available.  Launcher scripts are a dev-mode
+    // convenience; compiled builds use their own command dispatch, so we
+    // silently skip installation.
+    log.debug({ entrypoint }, 'CLI entrypoint not found (compiled build?) — skipping launcher installation');
+    return;
+  }
+
+  if (!existsSync(binDir)) {
+    mkdirSync(binDir, { recursive: true });
+  }
+
+  for (const name of INTEGRATION_COMMANDS) {
+    const launcherName = hasSystemConflict(name, binDir) ? `vellum-${name}` : name;
+    const launcherPath = join(binDir, launcherName);
+
+    const script = `#!/bin/bash
+exec "${bunPath}" "${entrypoint}" ${name} "$@"
+`;
+
+    writeFileSync(launcherPath, script);
+    chmodSync(launcherPath, 0o755);
+    log.debug({ launcherName, launcherPath }, 'Installed CLI launcher');
+  }
+
+  log.info({ binDir, commands: INTEGRATION_COMMANDS }, 'CLI launchers installed');
+}