@vellumai/assistant 0.4.42 → 0.4.43

package/src/runtime/guardian-action-message-composer.ts

@@ -75,7 +75,7 @@ export const GUARDIAN_ACTION_COPY_MAX_TOKENS = 200;
 export const GUARDIAN_ACTION_COPY_SYSTEM_PROMPT =
   "You are an assistant writing one user-facing message about a guardian action in a voice call scenario. " +
   "Keep it concise, natural, and conversational. Preserve factual details exactly. " +
-  "These messages are spoken aloud or sent as SMS, so use a warm, human tone. " +
+  "These messages are spoken aloud, so use a warm, human tone. " +
   "Do not mention internal systems, scenario IDs, or technical details. " +
   "Return plain text only.";
 
@@ -132,7 +132,7 @@ export function buildGuardianActionGenerationPrompt(
       : "";
   return [
     "Rewrite the following guardian action message as a natural, conversational reply.",
-    "These messages are for voice call scenarios and may be spoken aloud or sent as SMS.",
+    "These messages are for voice call scenarios and may be spoken aloud.",
     "Keep the same concrete facts and next-step guidance.",
     keywordClause,
     `Context JSON: ${JSON.stringify(context)}`,
@@ -165,7 +165,7 @@ export function includesRequiredKeywords(
  * Return a scenario-specific deterministic fallback message.
  *
  * Each template produces natural, conversational text suitable for voice
- * or SMS delivery.
+ * delivery.
  */
 export function getGuardianActionFallbackMessage(
   context: GuardianActionMessageContext,
@@ -248,7 +248,7 @@ export function getGuardianActionFallbackMessage(
         : "Got it! Your answer has been applied to the current active request on the call.";
 
     case "outbound_message_copy":
-      // This SMS is sent TO the original caller relaying the guardian's answer.
+      // This message is sent TO the original caller relaying the guardian's answer.
       // When lateAnswerText is available, include it — that's the whole point of message_back.
       if (context.lateAnswerText && context.questionText) {
         return `Hi! You asked "${context.questionText}" earlier. Here's the answer: ${context.lateAnswerText}`;

package/src/runtime/guardian-reply-router.ts

@@ -2,7 +2,7 @@
  * Shared guardian reply router for inbound channel messages.
  *
  * Provides a single entry point (`routeGuardianReply`) for all inbound
- * guardian reply processing across Telegram, SMS, and WhatsApp. Routes
+ * guardian reply processing across Telegram and WhatsApp. Routes
  * through a priority-ordered pipeline:
  *
  *   1. Deterministic callback/ref parsing (button presses with `apr:<requestId>:<action>`)
@@ -57,7 +57,7 @@ const log = getLogger("guardian-reply-router");
 export interface GuardianReplyContext {
   /** The raw message text (trimmed). */
   messageText: string;
-  /** Source channel (telegram, sms, whatsapp, etc.). */
+  /** Source channel (telegram, whatsapp, etc.). */
   channel: string;
   /** Actor identity context for the sender. */
   actor: ActorContext;
@@ -260,7 +260,7 @@ function notConsumed(): GuardianReplyResult {
  * Route an inbound guardian reply through the canonical decision pipeline.
  *
  * This is the single entry point for all inbound guardian reply processing.
- * It handles messages from any channel (Telegram, SMS, WhatsApp) and
+ * It handles messages from any channel (Telegram, WhatsApp) and
  * routes through priority-ordered matching:
  *
  *   1. Deterministic callback parsing (button presses)

package/src/runtime/http-server.ts

@@ -33,20 +33,25 @@ import {
   hasUngatedHttpAuthDisabled,
   isHttpAuthDisabled,
 } from "../config/env.js";
-import type { ServerMessage } from "../daemon/ipc-contract.js";
+import type { ServerMessage } from "../daemon/message-protocol.js";
 import { PairingStore } from "../daemon/pairing-store.js";
 import {
   type Confidence,
   getAttentionStateByConversationIds,
+  markConversationUnread,
   recordConversationSeenSignal,
   type SignalType,
 } from "../memory/conversation-attention-store.js";
-import * as conversationStore from "../memory/conversation-store.js";
+import {
+  countConversations,
+  listConversations,
+} from "../memory/conversation-queries.js";
 import * as externalConversationStore from "../memory/external-conversation-store.js";
 import {
   consumeCallback,
   consumeCallbackError,
 } from "../security/oauth-callback-registry.js";
+import { UserError } from "../util/errors.js";
 import { getLogger } from "../util/logger.js";
 import { buildAssistantEvent } from "./assistant-event.js";
 import { assistantEventHub } from "./assistant-event-hub.js";
@@ -86,6 +91,7 @@ import {
   TWILIO_WEBHOOK_RE,
   validateTwilioWebhook,
 } from "./middleware/twilio-validation.js";
+import { appManagementRouteDefinitions } from "./routes/app-management-routes.js";
 import { handleServePage } from "./routes/app-routes.js";
 import { appRouteDefinitions } from "./routes/app-routes.js";
 import { approvalRouteDefinitions } from "./routes/approval-routes.js";
@@ -102,6 +108,8 @@ import {
   startGuardianExpirySweep,
   stopGuardianExpirySweep,
 } from "./routes/channel-routes.js";
+import { channelVerificationRouteDefinitions } from "./routes/channel-verification-routes.js";
+import { computerUseRouteDefinitions } from "./routes/computer-use-routes.js";
 import {
   contactCatchAllRouteDefinitions,
   contactRouteDefinitions,
@@ -109,6 +117,8 @@ import {
 import { conversationAttentionRouteDefinitions } from "./routes/conversation-attention-routes.js";
 import { conversationRouteDefinitions } from "./routes/conversation-routes.js";
 import { debugRouteDefinitions } from "./routes/debug-routes.js";
+import { diagnosticsRouteDefinitions } from "./routes/diagnostics-routes.js";
+import { documentRouteDefinitions } from "./routes/documents-routes.js";
 import { eventsRouteDefinitions } from "./routes/events-routes.js";
 import { globalSearchRouteDefinitions } from "./routes/global-search-routes.js";
 import { guardianActionRouteDefinitions } from "./routes/guardian-action-routes.js";
@@ -116,7 +126,10 @@ import { handleGuardianBootstrap } from "./routes/guardian-bootstrap-routes.js";
 import { handleGuardianRefresh } from "./routes/guardian-refresh-routes.js";
 import { handleHealth } from "./routes/identity-routes.js";
 import { identityRouteDefinitions } from "./routes/identity-routes.js";
-import { integrationRouteDefinitions } from "./routes/integration-routes.js";
+import { slackChannelRouteDefinitions } from "./routes/integrations/slack/channel.js";
+import { slackShareRouteDefinitions } from "./routes/integrations/slack/share.js";
+import { telegramRouteDefinitions } from "./routes/integrations/telegram.js";
+import { twilioRouteDefinitions } from "./routes/integrations/twilio.js";
 import { inviteRouteDefinitions } from "./routes/invite-routes.js";
 import { migrationRouteDefinitions } from "./routes/migration-routes.js";
 import type { PairingHandlerContext } from "./routes/pairing-routes.js";
@@ -125,13 +138,20 @@ import {
   handlePairingStatus,
   pairingRouteDefinitions,
 } from "./routes/pairing-routes.js";
+import { recordingRouteDefinitions } from "./routes/recording-routes.js";
+import { scheduleRouteDefinitions } from "./routes/schedule-routes.js";
 import { secretRouteDefinitions } from "./routes/secret-routes.js";
-import { slackShareRouteDefinitions } from "./routes/slack-share-routes.js";
+import { sessionManagementRouteDefinitions } from "./routes/session-management-routes.js";
+import { sessionQueryRouteDefinitions } from "./routes/session-query-routes.js";
+import { settingsRouteDefinitions } from "./routes/settings-routes.js";
+import { skillRouteDefinitions } from "./routes/skills-routes.js";
+import { subagentRouteDefinitions } from "./routes/subagents-routes.js";
 import { surfaceActionRouteDefinitions } from "./routes/surface-action-routes.js";
 import { surfaceContentRouteDefinitions } from "./routes/surface-content-routes.js";
 import { trustRulesRouteDefinitions } from "./routes/trust-rules-routes.js";
-import { twilioRouteDefinitions } from "./routes/twilio-routes.js";
 import { usageRouteDefinitions } from "./routes/usage-routes.js";
+import { workItemRouteDefinitions } from "./routes/work-items-routes.js";
+import { workspaceRouteDefinitions } from "./routes/workspace-routes.js";
 
 // Re-export for consumers
 export { isPrivateAddress } from "./middleware/auth.js";
@@ -187,6 +207,12 @@ export class RuntimeHttpServer {
   private pairingBroadcast?: (msg: ServerMessage) => void;
   private sendMessageDeps?: SendMessageDeps;
   private findSession?: RuntimeHttpServerOptions["findSession"];
+  private findSessionBySurfaceId?: RuntimeHttpServerOptions["findSessionBySurfaceId"];
+  private getSkillContext?: RuntimeHttpServerOptions["getSkillContext"];
+  private sessionManagementDeps?: RuntimeHttpServerOptions["sessionManagementDeps"];
+  private getModelSetContext?: RuntimeHttpServerOptions["getModelSetContext"];
+  private getComputerUseDeps?: RuntimeHttpServerOptions["getComputerUseDeps"];
+  private getRecordingDeps?: RuntimeHttpServerOptions["getRecordingDeps"];
   private router: HttpRouter;
 
   constructor(options: RuntimeHttpServerOptions = {}) {
@@ -202,6 +228,12 @@ export class RuntimeHttpServer {
     this.interfacesDir = options.interfacesDir ?? null;
     this.sendMessageDeps = options.sendMessageDeps;
     this.findSession = options.findSession;
+    this.findSessionBySurfaceId = options.findSessionBySurfaceId;
+    this.getSkillContext = options.getSkillContext;
+    this.sessionManagementDeps = options.sessionManagementDeps;
+    this.getModelSetContext = options.getModelSetContext;
+    this.getComputerUseDeps = options.getComputerUseDeps;
+    this.getRecordingDeps = options.getRecordingDeps;
     this.router = new HttpRouter(this.buildRouteTable());
   }
 
@@ -240,10 +272,9 @@ export class RuntimeHttpServer {
       featureFlagToken: this.readFeatureFlagToken(),
       pairingBroadcast: ipcBroadcast
         ? (msg) => {
-            // Broadcast to IPC socket clients (local Unix socket)
+            // Broadcast to all clients via the event hub so HTTP/SSE clients
+            // (e.g. macOS app) receive pairing approval requests.
             ipcBroadcast(msg);
-            // Also publish to the event hub so HTTP/SSE clients (e.g. macOS
-            // app with localHttpEnabled) receive pairing approval requests.
             void assistantEventHub.publish(
               buildAssistantEvent(DAEMON_INTERNAL_ASSISTANT_ID, msg),
             );
@@ -458,16 +489,10 @@ export class RuntimeHttpServer {
     // needs to work when the access token is expired. Bootstrap has its
     // own loopback IP validation; refresh is secured by the refresh token
     // in the request body (32 random bytes, hash-only storage).
-    if (
-      path === "/v1/integrations/guardian/vellum/bootstrap" &&
-      req.method === "POST"
-    ) {
+    if (path === "/v1/guardian/init" && req.method === "POST") {
       return await handleGuardianBootstrap(req, server);
     }
-    if (
-      path === "/v1/integrations/guardian/vellum/refresh" &&
-      req.method === "POST"
-    ) {
+    if (path === "/v1/guardian/refresh" && req.method === "POST") {
       return await handleGuardianRefresh(req);
     }
 
@@ -683,10 +708,44 @@ export class RuntimeHttpServer {
         getPairingContext: () => this.pairingContext,
       }),
       ...appRouteDefinitions(),
+      ...appManagementRouteDefinitions(),
       ...secretRouteDefinitions(),
       ...identityRouteDefinitions(),
       ...debugRouteDefinitions(),
       ...usageRouteDefinitions(),
+      ...workspaceRouteDefinitions(),
+      ...settingsRouteDefinitions(),
+      ...scheduleRouteDefinitions({
+        sendMessageDeps: this.sendMessageDeps,
+      }),
+      ...diagnosticsRouteDefinitions(),
+      ...documentRouteDefinitions(),
+      ...workItemRouteDefinitions(
+        this.sendMessageDeps
+          ? {
+              getOrCreateSession: (conversationId) =>
+                this.sendMessageDeps!.getOrCreateSession(conversationId),
+              findSession: this.findSession
+                ? (conversationId) => {
+                    const s = this.findSession!(conversationId);
+                    if (!s || !("abort" in s)) return undefined;
+                    return s as import("../daemon/session.js").Session;
+                  }
+                : undefined,
+            }
+          : undefined,
+      ),
+      ...subagentRouteDefinitions(),
+      ...sessionQueryRouteDefinitions({
+        getModelSetContext: this.getModelSetContext,
+        findSessionForQueue: this.findSession
+          ? (id) => {
+              const s = this.findSession!(id);
+              if (!s?.removeQueuedMessage) return undefined;
+              return { removeQueuedMessage: s.removeQueuedMessage.bind(s) };
+            }
+          : undefined,
+      }),
 
       // Browser relay — not extracted into a domain module because
       // these two routes depend on the in-process extensionRelayServer
@@ -720,12 +779,8 @@ export class RuntimeHttpServer {
         handler: ({ url }) => {
           const limit = Number(url.searchParams.get("limit") ?? 50);
           const offset = Number(url.searchParams.get("offset") ?? 0);
-          const conversations = conversationStore.listConversations(
-            limit,
-            false,
-            offset,
-          );
-          const totalCount = conversationStore.countConversations();
+          const conversations = listConversations(limit, false, offset);
+          const totalCount = countConversations();
           const conversationIds = conversations.map((c) => c.id);
           const bindings =
             externalConversationStore.getBindingsForConversations(
@@ -772,6 +827,7 @@ export class RuntimeHttpServer {
                 updatedAt: c.updatedAt,
                 threadType: c.threadType === "private" ? "private" : "standard",
                 source: c.source ?? "user",
+                ...(c.scheduleJobId ? { scheduleJobId: c.scheduleJobId } : {}),
                 ...(binding
                   ? {
                       channelBinding: {
@@ -796,6 +852,10 @@ export class RuntimeHttpServer {
 
       ...conversationAttentionRouteDefinitions(),
 
+      ...(this.sessionManagementDeps
+        ? sessionManagementRouteDefinitions(this.sessionManagementDeps)
+        : []),
+
       {
         endpoint: "conversations/seen",
         method: "POST",
@@ -832,6 +892,34 @@ export class RuntimeHttpServer {
         },
       },
 
+      {
+        endpoint: "conversations/unread",
+        method: "POST",
+        handler: async ({ req }) => {
+          const body = (await req.json()) as Record<string, unknown>;
+          const conversationId = body.conversationId as string | undefined;
+          if (!conversationId)
+            return httpError("BAD_REQUEST", "Missing conversationId", 400);
+          try {
+            markConversationUnread(conversationId);
+            return Response.json({ ok: true });
+          } catch (err) {
+            if (err instanceof UserError) {
+              return httpError("UNPROCESSABLE_ENTITY", err.message, 422);
+            }
+            log.error(
+              { err, conversationId },
+              "POST /v1/conversations/unread: failed",
+            );
+            return httpError(
+              "INTERNAL_ERROR",
+              "Failed to mark conversation unread",
+              500,
+            );
+          }
+        },
+      },
+
       ...conversationRouteDefinitions({
         interfacesDir: this.interfacesDir,
         sendMessageDeps: this.sendMessageDeps,
@@ -841,8 +929,16 @@ export class RuntimeHttpServer {
       }),
       ...globalSearchRouteDefinitions(),
       ...approvalRouteDefinitions(),
+      ...(this.getSkillContext
+        ? skillRouteDefinitions({
+            getSkillContext: this.getSkillContext,
+          })
+        : []),
       ...trustRulesRouteDefinitions(),
-      ...surfaceActionRouteDefinitions({ findSession: this.findSession }),
+      ...surfaceActionRouteDefinitions({
+        findSession: this.findSession,
+        findSessionBySurfaceId: this.findSessionBySurfaceId,
+      }),
       ...surfaceContentRouteDefinitions({ findSession: this.findSession }),
       ...guardianActionRouteDefinitions(),
 
@@ -851,12 +947,25 @@ export class RuntimeHttpServer {
       // contacts/:id catch-all must follow invite routes to avoid shadowing
       ...contactCatchAllRouteDefinitions(),
 
-      ...integrationRouteDefinitions(),
+      ...telegramRouteDefinitions(),
+      ...channelVerificationRouteDefinitions(),
+      ...slackChannelRouteDefinitions(),
       ...slackShareRouteDefinitions(),
       ...twilioRouteDefinitions(),
       ...channelReadinessRouteDefinitions(),
       ...attachmentRouteDefinitions(),
 
+      ...(this.getComputerUseDeps
+        ? computerUseRouteDefinitions({
+            getComputerUseDeps: this.getComputerUseDeps,
+          })
+        : []),
+      ...(this.getRecordingDeps
+        ? recordingRouteDefinitions({
+            getRecordingDeps: this.getRecordingDeps,
+          })
+        : []),
+
       {
         endpoint: "interfaces/:path*",
         method: "GET",

package/src/runtime/http-types.ts

@@ -2,7 +2,12 @@
  * Shared types for the runtime HTTP server and its route handlers.
  */
 import type { ChannelId, InterfaceId } from "../channels/types.js";
-import type { SurfaceData, SurfaceType } from "../daemon/ipc-contract/surfaces.js";
+import type { SkillOperationContext } from "../daemon/handlers/skills.js";
+import type { ServerMessage } from "../daemon/message-protocol.js";
+import type {
+  SurfaceData,
+  SurfaceType,
+} from "../daemon/message-types/surfaces.js";
 import type { Session } from "../daemon/session.js";
 import type { TrustContext } from "../daemon/session-runtime-assembly.js";
 import type {
@@ -14,6 +19,7 @@ import type {
   ComposeGuardianActionMessageOptions,
   GuardianActionMessageContext,
 } from "./guardian-action-message-composer.js";
+import type { SessionManagementDeps } from "./routes/session-management-routes.js";
 /**
  * Daemon-injected function that generates approval copy using a provider.
  * Returns generated text or `null` on failure (caller falls back to deterministic text).
@@ -122,6 +128,8 @@ export interface RuntimeMessageSessionOptions {
   isInteractive?: boolean;
   /** Channel command intent metadata (e.g. Telegram /start). */
   commandIntent?: { type: string; payload?: string; languageCode?: string };
+  /** Optional callback to receive real-time agent loop events (text deltas, tool starts, etc.). */
+  onEvent?: (msg: ServerMessage) => void;
 }
 
 export type MessageProcessor = (
@@ -170,6 +178,8 @@ export interface RuntimeHttpServerOptions {
   guardianFollowUpConversationGenerator?: GuardianFollowUpConversationGenerator;
   /** Dependencies for the POST /v1/messages queue-if-busy handler. */
   sendMessageDeps?: SendMessageDeps;
+  /** Context provider for skill management HTTP routes. */
+  getSkillContext?: () => SkillOperationContext;
   /** Lookup an active session by ID (for surface actions and content fetches). */
   findSession?: (sessionId: string) =>
     | {
@@ -189,8 +199,31 @@ export interface RuntimeHttpServerOptions {
           data: SurfaceData;
           actions?: Array<{ id: string; label: string; style?: string }>;
         }>;
+        removeQueuedMessage?: (requestId: string) => boolean;
+      }
+    | undefined;
+  /** Lookup an active session by surfaceId (fallback when sessionId is absent). */
+  findSessionBySurfaceId?: (surfaceId: string) =>
+    | {
+        handleSurfaceAction(
+          surfaceId: string,
+          actionId: string,
+          data?: Record<string, unknown>,
+        ): void;
+        surfaceState: Map<
+          string,
+          { surfaceType: SurfaceType; data: SurfaceData; title?: string }
+        >;
       }
     | undefined;
+  /** Dependencies for session management HTTP routes (switch, rename, clear, cancel, undo, regenerate). */
+  sessionManagementDeps?: SessionManagementDeps;
+  /** Lazy factory for model config set context (session eviction, config reload suppression). */
+  getModelSetContext?: () => import("../daemon/handlers/config-model.js").ModelSetContext;
+  /** Provider for computer-use session dependencies (CU routes). */
+  getComputerUseDeps?: () => import("./routes/computer-use-routes.js").ComputerUseDeps;
+  /** Provider for recording dependencies (recording routes). */
+  getRecordingDeps?: () => import("./routes/recording-routes.js").RecordingDeps;
 }
 
 export interface RuntimeAttachmentMetadata {

package/src/runtime/invite-instruction-generator.ts

@@ -32,13 +32,11 @@ export function channelDisplayLabel(type: string): string {
   switch (type) {
     case "telegram":
       return "Telegram";
-    case "sms":
-      return "SMS";
     case "email":
       return "Email";
     case "slack":
       return "Slack";
-    case "voice":
+    case "phone":
       return "Voice";
     default:
       return type.charAt(0).toUpperCase() + type.slice(1);

package/src/runtime/invite-redemption-service.ts

@@ -285,7 +285,7 @@ export function redeemInvite(params: {
 export function redeemVoiceInviteCode(params: {
   assistantId?: string;
   callerExternalUserId: string;
-  sourceChannel: "voice";
+  sourceChannel: "phone";
   code: string;
 }): VoiceRedemptionOutcome {
   const { callerExternalUserId, code } = params;
@@ -325,16 +325,16 @@ export function redeemVoiceInviteCode(params: {
   }
 
   // Channel enforcement: voice invites can only be redeemed on the voice channel
-  if (invite.sourceChannel !== "voice") {
+  if (invite.sourceChannel !== "phone") {
     return { ok: false, reason: "invalid_or_expired" };
   }
 
   // Check for existing membership
   const canonicalCallerId =
-    canonicalizeInboundIdentity("voice" as ChannelId, callerExternalUserId) ??
+    canonicalizeInboundIdentity("phone" as ChannelId, callerExternalUserId) ??
     callerExternalUserId;
   const voiceContactResult = findContactChannel({
-    channelType: "voice",
+    channelType: "phone",
     externalUserId: canonicalCallerId,
   });
   const existingVoiceChannel = voiceContactResult?.channel ?? null;
@@ -367,7 +367,7 @@ export function redeemVoiceInviteCode(params: {
     getSqlite()
       .transaction(() => {
         const writeResult = upsertContactChannel({
-          sourceChannel: "voice",
+          sourceChannel: "phone",
           externalUserId: callerExternalUserId,
           externalChatId: callerExternalUserId,
           displayName: preservedDisplayName,

package/src/runtime/invite-service.ts

@@ -9,11 +9,6 @@
  */
 
 import { isChannelId } from "../channels/types.js";
-import {
-  DECLINED_BY_USER_SENTINEL,
-  DEFAULT_USER_REFERENCE,
-  resolveGuardianName,
-} from "../config/user-reference.js";
 import {
   createInvite,
   findByTokenHash,
@@ -23,6 +18,11 @@ import {
   listInvites,
   revokeInvite,
 } from "../memory/invite-store.js";
+import {
+  DECLINED_BY_USER_SENTINEL,
+  DEFAULT_USER_REFERENCE,
+  resolveGuardianName,
+} from "../prompts/user-reference.js";
 import { isValidE164 } from "../util/phone.js";
 import { generateVoiceCode, hashVoiceCode } from "../util/voice-code.js";
 import {
@@ -167,7 +167,7 @@ export async function createIngressInvite(params: {
   let voiceCode: string | undefined;
   let voiceCodeHash: string | undefined;
   let effectiveGuardianName: string | undefined;
-  const isVoice = params.sourceChannel === "voice";
+  const isVoice = params.sourceChannel === "phone";
 
   // For non-voice invites: generate a 6-digit invite code for guardian-mediated
   // redemption. The plaintext code is returned once in the response; only the
@@ -351,7 +351,7 @@ export function redeemIngressInviteTyped(params: {
 export function redeemVoiceInviteCode(params: {
   assistantId?: string;
   callerExternalUserId: string;
-  sourceChannel: "voice";
+  sourceChannel: "phone";
   code: string;
 }): VoiceRedemptionOutcome {
   return redeemVoiceInviteCodeTyped(params);

package/src/runtime/local-actor-identity.ts

@@ -13,16 +13,42 @@
 
 import type { ChannelId } from "../channels/types.js";
 import { findGuardianForChannel } from "../contacts/contact-store.js";
-import { buildIpcAuthContext } from "../daemon/ipc-handler.js";
 import type { TrustContext } from "../daemon/session-runtime-assembly.js";
 import { getLogger } from "../util/logger.js";
 import { DAEMON_INTERNAL_ASSISTANT_ID } from "./assistant-scope.js";
+import { CURRENT_POLICY_EPOCH } from "./auth/policy.js";
+import { resolveScopeProfile } from "./auth/scopes.js";
 import type { AuthContext } from "./auth/types.js";
 import { ensureVellumGuardianBinding } from "./guardian-vellum-migration.js";
 import { resolveTrustContext } from "./trust-context-resolver.js";
 
 const log = getLogger("local-actor-identity");
 
+/**
+ * Build a synthetic AuthContext for a local session.
+ *
+ * Local connections are pre-authenticated via the daemon's file-system
+ * permission model. This produces the same AuthContext shape that HTTP
+ * routes receive from JWT verification, keeping downstream code
+ * transport-agnostic.
+ */
+export function buildLocalAuthContext(sessionId: string): AuthContext {
+  return {
+    subject: `ipc:self:${sessionId}`,
+    principalType: "ipc",
+    assistantId: DAEMON_INTERNAL_ASSISTANT_ID,
+    sessionId,
+    scopeProfile: "ipc_v1",
+    scopes: resolveScopeProfile("ipc_v1"),
+    policyEpoch: CURRENT_POLICY_EPOCH,
+  };
+}
+
+/**
+ * @deprecated Use `buildLocalAuthContext` instead.
+ */
+export const buildIpcAuthContext = buildLocalAuthContext;
+
 /**
  * Resolve the guardian runtime context for a local IPC connection.
  *
@@ -90,7 +116,7 @@ export function resolveLocalIpcTrustContext(
  * `authContext.actorPrincipalId` path as HTTP sessions.
  */
 export function resolveLocalIpcAuthContext(sessionId: string): AuthContext {
-  const authContext = buildIpcAuthContext(sessionId);
+  const authContext = buildLocalAuthContext(sessionId);
 
   // Enrich with the guardian principal ID from contacts-first path
   const guardianResult = findGuardianForChannel("vellum");