@vellumai/assistant 0.3.2 → 0.3.4

package/src/daemon/handlers/config.ts

@@ -5,7 +5,7 @@ import { addRule, removeRule, updateRule, getAllRules, acceptStarterBundle } fro
 import { classifyRisk, check, generateAllowlistOptions, generateScopeOptions } from '../../permissions/checker.js';
 import { isSideEffectTool } from '../../tools/executor.js';
 import { resolveExecutionTarget } from '../../tools/execution-target.js';
-import { getAllTools, getTool } from '../../tools/registry.js';
+import { getAllTools } from '../../tools/registry.js';
 import { listSchedules, updateSchedule, deleteSchedule, describeCronExpression } from '../../schedule/schedule-store.js';
 import { listReminders, cancelReminder } from '../../tools/reminder/reminder-store.js';
 import { getSecureKey, setSecureKey, deleteSecureKey } from '../../security/secure-keys.js';
@@ -37,7 +37,14 @@ import {
   listIncomingPhoneNumbers,
   searchAvailableNumbers,
   provisionPhoneNumber,
+  updatePhoneNumberWebhooks,
 } from '../../calls/twilio-rest.js';
+import {
+  getTwilioVoiceWebhookUrl,
+  getTwilioStatusCallbackUrl,
+  getTwilioSmsWebhookUrl,
+  type IngressConfig,
+} from '../../inbound/public-ingress-urls.js';
 import { createVerificationChallenge, getGuardianBinding, revokeBinding as revokeGuardianBinding } from '../../runtime/channel-guardian-service.js';
 import { log, CONFIG_RELOAD_DEBOUNCE_MS, defineHandlers, type HandlerContext } from './shared.js';
 import { MODEL_TO_PROVIDER } from '../session-slash.js';
@@ -509,11 +516,46 @@ function triggerGatewayReconcile(ingressPublicBaseUrl: string | undefined): void
   });
 }
 
-export function handleIngressConfig(
+/**
+ * Best-effort Twilio webhook sync helper.
+ *
+ * Computes the voice, status-callback, and SMS webhook URLs from the current
+ * ingress config and pushes them to the Twilio IncomingPhoneNumber API.
+ *
+ * Returns `{ success, warning }`. When the update fails, `success` is false
+ * and `warning` contains a human-readable message. Callers should treat
+ * failure as non-fatal so that the primary operation (provision, assign,
+ * ingress save) still succeeds.
+ */
+async function syncTwilioWebhooks(
+  phoneNumber: string,
+  accountSid: string,
+  authToken: string,
+  ingressConfig: IngressConfig,
+): Promise<{ success: boolean; warning?: string }> {
+  try {
+    const voiceUrl = getTwilioVoiceWebhookUrl(ingressConfig);
+    const statusCallbackUrl = getTwilioStatusCallbackUrl(ingressConfig);
+    const smsUrl = getTwilioSmsWebhookUrl(ingressConfig);
+    await updatePhoneNumberWebhooks(accountSid, authToken, phoneNumber, {
+      voiceUrl,
+      statusCallbackUrl,
+      smsUrl,
+    });
+    log.info({ phoneNumber }, 'Twilio webhooks configured successfully');
+    return { success: true };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    log.warn({ err, phoneNumber }, `Webhook configuration skipped: ${message}`);
+    return { success: false, warning: `Webhook configuration skipped: ${message}` };
+  }
+}
+
+export async function handleIngressConfig(
   msg: IngressConfigRequest,
   socket: net.Socket,
   ctx: HandlerContext,
-): void {
+): Promise<void> {
   const localGatewayTarget = computeGatewayTarget();
   try {
     if (msg.action === 'get') {
@@ -584,6 +626,40 @@ export function handleIngressConfig(
       // fallback branch above) rather than the raw `value` from the UI.
       const effectiveUrl = isEnabled ? process.env.INGRESS_PUBLIC_BASE_URL : undefined;
       triggerGatewayReconcile(effectiveUrl);
+
+      // Best-effort Twilio webhook reconciliation: when ingress is being
+      // enabled/updated and Twilio numbers are assigned with valid credentials,
+      // push the new webhook URLs to Twilio so calls and SMS route correctly.
+      if (isEnabled && hasTwilioCredentials()) {
+        const currentConfig = loadRawConfig();
+        const smsConfig = (currentConfig?.sms ?? {}) as Record<string, unknown>;
+        const assignedNumbers = new Set<string>();
+        const legacyNumber = (smsConfig.phoneNumber as string) ?? '';
+        if (legacyNumber) assignedNumbers.add(legacyNumber);
+
+        const assistantPhoneNumbers = smsConfig.assistantPhoneNumbers;
+        if (assistantPhoneNumbers && typeof assistantPhoneNumbers === 'object' && !Array.isArray(assistantPhoneNumbers)) {
+          for (const number of Object.values(assistantPhoneNumbers as Record<string, unknown>)) {
+            if (typeof number === 'string' && number) {
+              assignedNumbers.add(number);
+            }
+          }
+        }
+
+        if (assignedNumbers.size > 0) {
+          const acctSid = getSecureKey('credential:twilio:account_sid')!;
+          const acctToken = getSecureKey('credential:twilio:auth_token')!;
+          // Fire-and-forget: webhook sync failure must not block the ingress save.
+          // Reconcile every assigned number so assistant-scoped mappings do not
+          // retain stale Twilio webhook URLs after ingress URL changes.
+          for (const assignedNumber of assignedNumbers) {
+            syncTwilioWebhooks(assignedNumber, acctSid, acctToken, currentConfig as IngressConfig)
+              .catch(() => {
+                // Already logged inside syncTwilioWebhooks
+              });
+          }
+        }
+      }
     } else {
       ctx.send(socket, { type: 'ingress_config_response', enabled: false, publicBaseUrl: '', localGatewayTarget, success: false, error: `Unknown action: ${String((msg as unknown as Record<string, unknown>).action)}` });
     }
@@ -1109,7 +1185,15 @@ export async function handleTwilioConfig(
       const hasCredentials = hasTwilioCredentials();
       const raw = loadRawConfig();
       const sms = (raw?.sms ?? {}) as Record<string, unknown>;
-      const phoneNumber = (sms.phoneNumber as string) ?? '';
+      // When assistantId is provided, look up in assistantPhoneNumbers first,
+      // fall back to the legacy phoneNumber field
+      let phoneNumber: string;
+      if (msg.assistantId) {
+        const mapping = (sms.assistantPhoneNumbers as Record<string, string> | undefined) ?? {};
+        phoneNumber = mapping[msg.assistantId] ?? (sms.phoneNumber as string) ?? '';
+      } else {
+        phoneNumber = (sms.phoneNumber as string) ?? '';
+      }
       ctx.send(socket, {
         type: 'twilio_config_response',
         success: true,
@@ -1192,9 +1276,12 @@ export async function handleTwilioConfig(
         hasCredentials: true,
       });
     } else if (msg.action === 'clear_credentials') {
+      // Only clear authentication credentials (Account SID and Auth Token).
+      // Preserve the phone number in both config (sms.phoneNumber) and secure
+      // key (credential:twilio:phone_number) so that re-entering credentials
+      // resumes working without needing to reassign the number.
       deleteSecureKey('credential:twilio:account_sid');
       deleteSecureKey('credential:twilio:auth_token');
-      deleteSecureKey('credential:twilio:phone_number');
       deleteCredentialMetadata('twilio', 'account_sid');
       deleteCredentialMetadata('twilio', 'auth_token');
 
@@ -1233,11 +1320,64 @@ export async function handleTwilioConfig(
       // Purchase the first available number
       const purchased = await provisionPhoneNumber(accountSid, authToken, available[0].phoneNumber);
 
+      // Auto-assign: persist the purchased number in secure storage and config
+      // (same persistence as assign_number for consistency)
+      const phoneStored = setSecureKey('credential:twilio:phone_number', purchased.phoneNumber);
+      if (!phoneStored) {
+        ctx.send(socket, {
+          type: 'twilio_config_response',
+          success: false,
+          hasCredentials: hasTwilioCredentials(),
+          phoneNumber: purchased.phoneNumber,
+          error: `Phone number ${purchased.phoneNumber} was purchased but could not be saved. Use assign_number to assign it manually.`,
+        });
+        return;
+      }
+
+      const raw = loadRawConfig();
+      const sms = (raw?.sms ?? {}) as Record<string, unknown>;
+      // When assistantId is provided, only set the legacy global phoneNumber
+      // if it's not already set — this prevents multi-assistant assignments
+      // from clobbering each other's outbound SMS number.
+      if (msg.assistantId) {
+        if (!sms.phoneNumber) {
+          sms.phoneNumber = purchased.phoneNumber;
+        }
+      } else {
+        sms.phoneNumber = purchased.phoneNumber;
+      }
+      // When assistantId is provided, also persist into the per-assistant mapping
+      if (msg.assistantId) {
+        const mapping = (sms.assistantPhoneNumbers as Record<string, string> | undefined) ?? {};
+        mapping[msg.assistantId] = purchased.phoneNumber;
+        sms.assistantPhoneNumbers = mapping;
+      }
+
+      const wasSuppressed = ctx.suppressConfigReload;
+      ctx.setSuppressConfigReload(true);
+      try {
+        saveRawConfig({ ...raw, sms });
+      } catch (err) {
+        ctx.setSuppressConfigReload(wasSuppressed);
+        throw err;
+      }
+      ctx.debounceTimers.schedule('__suppress_reset__', () => { ctx.setSuppressConfigReload(false); }, CONFIG_RELOAD_DEBOUNCE_MS);
+
+      // Best-effort webhook configuration — non-fatal so the number is
+      // still usable even if ingress isn't configured yet.
+      const webhookResult = await syncTwilioWebhooks(
+        purchased.phoneNumber,
+        accountSid,
+        authToken,
+        loadRawConfig() as IngressConfig,
+      );
+
       ctx.send(socket, {
         type: 'twilio_config_response',
         success: true,
         hasCredentials: true,
         phoneNumber: purchased.phoneNumber,
+        warning: webhookResult.warning,
       });
     } else if (msg.action === 'assign_number') {
       if (!msg.phoneNumber) {
@@ -1266,7 +1406,22 @@ export async function handleTwilioConfig(
       // Also persist in assistant config (non-secret) for the UI
       const raw = loadRawConfig();
       const sms = (raw?.sms ?? {}) as Record<string, unknown>;
-      sms.phoneNumber = msg.phoneNumber;
+      // When assistantId is provided, only set the legacy global phoneNumber
+      // if it's not already set — this prevents multi-assistant assignments
+      // from clobbering each other's outbound SMS number.
+      if (msg.assistantId) {
+        if (!sms.phoneNumber) {
+          sms.phoneNumber = msg.phoneNumber;
+        }
+      } else {
+        sms.phoneNumber = msg.phoneNumber;
+      }
+      // When assistantId is provided, also persist into the per-assistant mapping
+      if (msg.assistantId) {
+        const mapping = (sms.assistantPhoneNumbers as Record<string, string> | undefined) ?? {};
+        mapping[msg.assistantId] = msg.phoneNumber;
+        sms.assistantPhoneNumbers = mapping;
+      }
 
       const wasSuppressed = ctx.suppressConfigReload;
       ctx.setSuppressConfigReload(true);
@@ -1278,11 +1433,26 @@ export async function handleTwilioConfig(
       }
       ctx.debounceTimers.schedule('__suppress_reset__', () => { ctx.setSuppressConfigReload(false); }, CONFIG_RELOAD_DEBOUNCE_MS);
 
+      // Best-effort webhook configuration when credentials are available
+      let webhookWarning: string | undefined;
+      if (hasTwilioCredentials()) {
+        const acctSid = getSecureKey('credential:twilio:account_sid')!;
+        const acctToken = getSecureKey('credential:twilio:auth_token')!;
+        const webhookResult = await syncTwilioWebhooks(
+          msg.phoneNumber,
+          acctSid,
+          acctToken,
+          loadRawConfig() as IngressConfig,
+        );
+        webhookWarning = webhookResult.warning;
+      }
+
       ctx.send(socket, {
         type: 'twilio_config_response',
         success: true,
         hasCredentials: hasTwilioCredentials(),
         phoneNumber: msg.phoneNumber,
+        warning: webhookWarning,
       });
     } else if (msg.action === 'list_numbers') {
       if (!hasTwilioCredentials()) {
@@ -1330,12 +1500,12 @@ export function handleGuardianVerification(
   socket: net.Socket,
   ctx: HandlerContext,
 ): void {
-  try {
-    // In single-assistant mode, 'self' is the canonical assistant ID used
-    // by channel routes when validating challenges on the inbound path.
-    const assistantId = 'self';
-    const channel = msg.channel ?? 'telegram';
+  // Use the assistant ID from the request when available; fall back to
+  // 'self' for backward compatibility with single-assistant mode.
+  const assistantId = msg.assistantId ?? 'self';
+  const channel = msg.channel ?? 'telegram';
 
+  try {
     if (msg.action === 'create_challenge') {
       const result = createVerificationChallenge(assistantId, channel, msg.sessionId);
 
@@ -1344,6 +1514,7 @@ export function handleGuardianVerification(
         success: true,
         secret: result.secret,
         instruction: result.instruction,
+        channel,
       });
     } else if (msg.action === 'status') {
       const binding = getGuardianBinding(assistantId, channel);
@@ -1352,19 +1523,24 @@ export function handleGuardianVerification(
         success: true,
         bound: binding !== null,
         guardianExternalUserId: binding?.guardianExternalUserId,
+        channel,
+        assistantId,
+        guardianDeliveryChatId: binding?.guardianDeliveryChatId,
       });
     } else if (msg.action === 'revoke') {
-      const revoked = revokeGuardianBinding(assistantId, channel);
+      revokeGuardianBinding(assistantId, channel);
       ctx.send(socket, {
         type: 'guardian_verification_response',
         success: true,
         bound: false,
+        channel,
       });
     } else {
       ctx.send(socket, {
         type: 'guardian_verification_response',
         success: false,
         error: `Unknown action: ${String(msg.action)}`,
+        channel,
       });
     }
   } catch (err) {
@@ -1374,6 +1550,7 @@ export function handleGuardianVerification(
       type: 'guardian_verification_response',
       success: false,
       error: message,
+      channel,
     });
   }
 }
@@ -1411,11 +1588,10 @@ export async function handleToolPermissionSimulate(
 
     const workingDir = msg.workingDir ?? process.cwd();
 
-    // Only infer execution target when the tool is actually registered;
-    // for unresolved tools, leave it undefined so trust rules are unscoped.
-    const isRegistered = getTool(msg.toolName) !== undefined;
-    const executionTarget = isRegistered ? resolveExecutionTarget(msg.toolName) : undefined;
-    const policyContext = executionTarget ? { executionTarget } : undefined;
+    // Resolve execution target using manifest metadata or prefix heuristics.
+    // resolveExecutionTarget handles unregistered tools via prefix fallback.
+    const executionTarget = resolveExecutionTarget(msg.toolName);
+    const policyContext = { executionTarget };
 
     const riskLevel = await classifyRisk(msg.toolName, msg.input, workingDir);
     const result = await check(msg.toolName, msg.input, workingDir, policyContext);

package/src/daemon/handlers/sessions.ts

@@ -198,8 +198,9 @@ export function handleSecretResponse(
   log.warn({ requestId: msg.requestId }, 'No session found with pending secret prompt for requestId');
 }
 
-export function handleSessionList(socket: net.Socket, ctx: HandlerContext): void {
-  const conversations = conversationStore.listConversations(50);
+export function handleSessionList(socket: net.Socket, ctx: HandlerContext, offset = 0, limit = 50): void {
+  const conversations = conversationStore.listConversations(limit, false, offset);
+  const totalCount = conversationStore.countConversations();
   const bindings = externalConversationStore.getBindingsForConversations(
     conversations.map((c) => c.id),
   );
@@ -223,6 +224,7 @@ export function handleSessionList(socket: net.Socket, ctx: HandlerContext): void
         } : {}),
       };
     }),
+    hasMore: offset + conversations.length < totalCount,
   });
 }
 
@@ -541,7 +543,7 @@ export const sessionHandlers = defineHandlers({
   user_message: handleUserMessage,
   confirmation_response: handleConfirmationResponse,
   secret_response: handleSecretResponse,
-  session_list: (_msg, socket, ctx) => handleSessionList(socket, ctx),
+  session_list: (msg, socket, ctx) => handleSessionList(socket, ctx, msg.offset ?? 0, msg.limit ?? 50),
   session_create: handleSessionCreate,
   sessions_clear: (_msg, socket, ctx) => handleSessionsClear(socket, ctx),
   session_switch: handleSessionSwitch,

package/src/daemon/handlers/skills.ts

@@ -5,8 +5,9 @@ import { getConfig, loadRawConfig, saveRawConfig, invalidateConfigCache } from '
 import { loadSkillCatalog, loadSkillBySelector, ensureSkillIcon } from '../../config/skills.js';
 import { resolveSkillStates } from '../../config/skill-state.js';
 import { getWorkspaceSkillsDir } from '../../util/platform.js';
-import { clawhubInstall, clawhubUpdate, clawhubSearch, clawhubCheckUpdates, clawhubInspect } from '../../skills/clawhub.js';
+import { clawhubInstall, clawhubUpdate, clawhubSearch, clawhubCheckUpdates, clawhubInspect, type ClawhubSearchResultItem } from '../../skills/clawhub.js';
 import { removeSkillsIndexEntry, deleteManagedSkill, validateManagedSkillId } from '../../skills/managed-store.js';
+import { listCatalogEntries, installFromVellumCatalog, checkVellumSkill } from '../../tools/skills/vellum-catalog.js';
 import type {
   SkillDetailRequest,
   SkillsEnableRequest,
@@ -186,26 +187,44 @@ export async function handleSkillsInstall(
   ctx: HandlerContext,
 ): Promise<void> {
   try {
-    const result = await clawhubInstall(msg.slug, { version: msg.version });
-    if (!result.success) {
-      ctx.send(socket, {
-        type: 'skills_operation_response',
-        operation: 'install',
-        success: false,
-        error: result.error ?? 'Unknown error',
-      });
-      return;
+    // Check if the slug matches a vellum-skills catalog entry first
+    const isVellumSkill = await checkVellumSkill(msg.slug);
+
+    let skillId: string;
+
+    if (isVellumSkill) {
+      // Install from vellum-skills catalog (remote with bundled fallback)
+      const result = await installFromVellumCatalog(msg.slug);
+      if (!result.success) {
+        ctx.send(socket, {
+          type: 'skills_operation_response',
+          operation: 'install',
+          success: false,
+          error: result.error ?? 'Unknown error',
+        });
+        return;
+      }
+      skillId = result.skillName ?? msg.slug;
+    } else {
+      // Install from clawhub (community)
+      const result = await clawhubInstall(msg.slug, { version: msg.version });
+      if (!result.success) {
+        ctx.send(socket, {
+          type: 'skills_operation_response',
+          operation: 'install',
+          success: false,
+          error: result.error ?? 'Unknown error',
+        });
+        return;
+      }
+      const rawId = result.skillName ?? msg.slug;
+      skillId = rawId.includes('/') ? rawId.split('/').pop()! : rawId;
     }
 
     // Reload skill catalog so the newly installed skill is picked up
     loadSkillCatalog();
 
     // Auto-enable the newly installed skill so it's immediately usable.
-    // Use basename of slug to match the catalog ID (directory basename), since
-    // install slugs can be namespaced (e.g. "org/name") but skill state keys use
-    // the bare directory name.
-    const rawId = result.skillName ?? msg.slug;
-    const skillId = rawId.includes('/') ? rawId.split('/').pop()! : rawId;
     try {
       const raw = loadRawConfig();
       ensureSkillEntry(raw, skillId).enabled = true;
@@ -404,12 +423,36 @@ export async function handleSkillsSearch(
   ctx: HandlerContext,
 ): Promise<void> {
   try {
-    const result = await clawhubSearch(msg.query);
+    // Search vellum-skills catalog (remote with bundled fallback)
+    const catalogEntries = await listCatalogEntries();
+    const query = (msg.query ?? '').toLowerCase();
+    const matchingCatalog = catalogEntries.filter((e) => {
+      if (!query) return true;
+      return e.name.toLowerCase().includes(query) || e.description.toLowerCase().includes(query) || e.id.toLowerCase().includes(query);
+    });
+    const vellumSkills: ClawhubSearchResultItem[] = matchingCatalog.map((e) => ({
+      name: e.name,
+      slug: e.id,
+      description: e.description,
+      author: 'Vellum',
+      stars: 0,
+      installs: 0,
+      version: '',
+      createdAt: 0,
+      source: 'vellum' as const,
+    }));
+
+    // Search clawhub concurrently
+    const clawhubResult = await clawhubSearch(msg.query);
+
+    // Merge: vellum first, then clawhub
+    const merged = { skills: [...vellumSkills, ...clawhubResult.skills] };
+
     ctx.send(socket, {
       type: 'skills_operation_response',
       operation: 'search',
       success: true,
-      data: result,
+      data: merged,
     });
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);

package/src/daemon/ipc-contract-inventory.json

@@ -91,6 +91,7 @@
     "ToolNamesListRequest",
     "ToolPermissionSimulateRequest",
     "TrustRulesList",
+    "TwilioConfigRequest",
     "TwitterAuthStartRequest",
     "TwitterAuthStatusRequest",
     "TwitterIntegrationConfigRequest",
@@ -215,6 +216,7 @@
     "ToolUseStart",
     "TraceEvent",
     "TrustRulesListResponse",
+    "TwilioConfigResponse",
     "TwitterAuthResult",
     "TwitterAuthStatusResponse",
     "TwitterIntegrationConfigResponse",
@@ -338,6 +340,7 @@
     "tool_names_list",
     "tool_permission_simulate",
     "trust_rules_list",
+    "twilio_config",
     "twitter_auth_start",
     "twitter_auth_status",
     "twitter_integration_config",
@@ -462,6 +465,7 @@
     "tool_use_start",
     "trace_event",
     "trust_rules_list_response",
+    "twilio_config_response",
     "twitter_auth_result",
     "twitter_auth_status_response",
     "twitter_integration_config_response",

package/src/daemon/ipc-contract.ts

@@ -67,6 +67,10 @@ export interface SecretResponse {
 
 export interface SessionListRequest {
   type: 'session_list';
+  /** Number of sessions to skip (for pagination). Defaults to 0. */
+  offset?: number;
+  /** Maximum number of sessions to return. Defaults to 50. */
+  limit?: number;
 }
 
 /** Lightweight session transport metadata for channel identity and natural-language guidance. */
@@ -557,6 +561,7 @@ export interface TwilioConfigRequest {
   phoneNumber?: string;       // Only for action: 'assign_number'
   areaCode?: string;          // Only for action: 'provision_number'
   country?: string;           // Only for action: 'provision_number' (ISO 3166-1 alpha-2, default 'US')
+  assistantId?: string;       // Scope number assignment/lookup to a specific assistant
 }
 
 export interface TwilioConfigResponse {
@@ -566,6 +571,8 @@ export interface TwilioConfigResponse {
   phoneNumber?: string;
   numbers?: Array<{ phoneNumber: string; friendlyName: string; capabilities: { voice: boolean; sms: boolean } }>;
   error?: string;
+  /** Non-fatal warning message (e.g. webhook sync failure that did not prevent the primary operation). */
+  warning?: string;
 }
 
 export interface GuardianVerificationRequest {
@@ -573,6 +580,7 @@ export interface GuardianVerificationRequest {
   action: 'create_challenge' | 'status' | 'revoke';
   channel?: string;  // Defaults to 'telegram'
   sessionId?: string;
+  assistantId?: string;  // Defaults to 'self'
 }
 
 export interface GuardianVerificationResponse {
@@ -583,6 +591,12 @@ export interface GuardianVerificationResponse {
   /** Present when action is 'status'. */
   bound?: boolean;
   guardianExternalUserId?: string;
+  /** The channel this status pertains to (e.g. "telegram", "sms"). Present when action is 'status'. */
+  channel?: string;
+  /** The assistant ID scoped to this status. Present when action is 'status'. */
+  assistantId?: string;
+  /** The delivery chat ID for the guardian (e.g. Telegram chat ID). Present when action is 'status' and bound is true. */
+  guardianDeliveryChatId?: string;
   error?: string;
 }
 
@@ -1271,6 +1285,8 @@ export interface ChannelBinding {
 export interface SessionListResponse {
   type: 'session_list_response';
   sessions: Array<{ id: string; title: string; updatedAt: number; threadType?: ThreadType; channelBinding?: ChannelBinding }>;
+  /** Whether more sessions exist beyond the returned page. */
+  hasMore?: boolean;
 }
 
 export interface SessionsClearResponse {

package/src/daemon/ipc-handler.ts

@@ -0,0 +1,87 @@
+/**
+ * IPC wire-level helpers: socket writing, broadcast, and assistant-event
+ * hub publishing. Extracted from DaemonServer to separate transport
+ * concerns from session management and business logic.
+ */
+import * as net from 'node:net';
+import { serialize, type ServerMessage } from './ipc-protocol.js';
+import { assistantEventHub } from '../runtime/assistant-event-hub.js';
+import { buildAssistantEvent } from '../runtime/assistant-event.js';
+import { getLogger } from '../util/logger.js';
+
+const log = getLogger('ipc-handler');
+
+/**
+ * Manages IPC message delivery: writing to individual sockets,
+ * broadcasting to all authenticated sockets, and publishing events
+ * to the assistant-events hub in order.
+ */
+export class IpcSender {
+  private _hubChain: Promise<void> = Promise.resolve();
+
+  /** Write to a single socket without publishing to the event hub. */
+  writeToSocket(socket: net.Socket, msg: ServerMessage): void {
+    if (!socket.destroyed && socket.writable) {
+      socket.write(serialize(msg));
+    }
+  }
+
+  /**
+   * Send a message to a single socket and publish to the event hub.
+   * `sessionId` is resolved from the message itself or the socket binding.
+   */
+  send(
+    socket: net.Socket,
+    msg: ServerMessage,
+    socketToSession: Map<net.Socket, string>,
+    assistantId: string,
+  ): void {
+    this.writeToSocket(socket, msg);
+    const sessionId = extractSessionId(msg) ?? socketToSession.get(socket);
+    this.publishAssistantEvent(msg, sessionId, assistantId);
+  }
+
+  /**
+   * Broadcast a message to all authenticated sockets, then publish
+   * a single event to the hub.
+   */
+  broadcast(
+    authenticatedSockets: Set<net.Socket>,
+    msg: ServerMessage,
+    socketToSession: Map<net.Socket, string>,
+    assistantId: string,
+    excludeSocket?: net.Socket,
+  ): void {
+    for (const socket of authenticatedSockets) {
+      if (socket === excludeSocket) continue;
+      this.writeToSocket(socket, msg);
+    }
+    const sessionId = extractSessionId(msg)
+      ?? (excludeSocket ? socketToSession.get(excludeSocket) : undefined);
+    this.publishAssistantEvent(msg, sessionId, assistantId);
+  }
+
+  /**
+   * Publish `msg` as an `AssistantEvent` to the process-level hub.
+   * Publications are serialized via a promise chain so subscribers
+   * always observe events in send order.
+   */
+  private publishAssistantEvent(msg: ServerMessage, sessionId?: string, assistantId?: string): void {
+    const id = assistantId ?? 'default';
+    const event = buildAssistantEvent(id, msg, sessionId);
+    this._hubChain = this._hubChain
+      .then(() => assistantEventHub.publish(event))
+      .catch((err: unknown) => {
+        log.warn({ err }, 'assistant-events hub subscriber threw during IPC send');
+      });
+  }
+}
+
+/** Extract sessionId from a ServerMessage if present. */
+function extractSessionId(msg: ServerMessage): string | undefined {
+  const record = msg as unknown as Record<string, unknown>;
+  if ('sessionId' in msg && typeof record.sessionId === 'string') {
+    return record.sessionId as string;
+  }
+  return undefined;
+}

package/src/daemon/lifecycle.ts

@@ -429,11 +429,23 @@ export async function runDaemon(): Promise<void> {
   if (httpPortEnv) {
     const port = parseInt(httpPortEnv, 10);
     if (!isNaN(port) && port > 0) {
-      // Use an explicit env var if provided; otherwise generate a fresh
-      // random token. Either way, write it to disk so HTTP clients and
-      // the gateway can authenticate.
-      const bearerToken = process.env.RUNTIME_PROXY_BEARER_TOKEN || randomBytes(32).toString('hex');
+      // Resolve the bearer token in priority order:
+      //   1. Explicit env var (e.g. cloud deploys)
+      //   2. Existing token file on disk (preserves QR-paired iOS devices across restarts)
+      //   3. Fresh random token (first-time startup)
       const httpTokenPath = getHttpTokenPath();
+      let bearerToken = process.env.RUNTIME_PROXY_BEARER_TOKEN;
+      if (!bearerToken) {
+        try {
+          const existing = readFileSync(httpTokenPath, 'utf-8').trim();
+          if (existing) bearerToken = existing;
+        } catch {
+          // File doesn't exist or can't be read — will generate below
+        }
+      }
+      if (!bearerToken) {
+        bearerToken = randomBytes(32).toString('hex');
+      }
       writeFileSync(httpTokenPath, bearerToken, { mode: 0o600 });
       chmodSync(httpTokenPath, 0o600);