@vellumai/assistant 0.10.4 → 0.10.5-dev.202607022329.d89bf2f

package/src/runtime/routes/inbound-stages/background-dispatch.ts

@@ -12,6 +12,7 @@ import {
   extractChannelFromCallbackUrl,
   extractMessageTsFromCallbackUrl,
   extractThreadTsFromCallbackUrl,
+  isSlackDeliveryCallbackUrl,
   peekThreadMapping,
   setThreadTs,
 } from "../../../channels/slack-thread-store.js";
@@ -22,13 +23,10 @@ import {
 } from "../../../contacts/guardian-delivery-reader.js";
 import type { ServerMessage } from "../../../daemon/message-protocol.js";
 import type { TrustContext } from "../../../daemon/trust-context.js";
-import {
-  addSlackDmLiveDeliveredTextResponseIndex,
-  getSlackDmLiveDeliveredTextResponseIndexes,
-} from "../../../persistence/delivery-channels.js";
 import {
   linkMessage,
   storeReplyMessageId,
+  storeStreamedReplyTs,
 } from "../../../persistence/delivery-crud.js";
 import {
   markProcessed,
@@ -48,10 +46,14 @@ import type {
   MessageProcessor,
   SlackInboundMessageMetadata,
 } from "../../http-types.js";
+import { hasDeliverableAssistantText } from "../../slack-no-response.js";
+import { createSlackReplySession } from "../../slack-reply-session.js";
+import type { TaskProgressData } from "../../slack-task-progress.js";
 import {
-  createSlackDmTextDeliveryController,
-  isSlackDeliveryCallbackUrl,
-} from "../../slack-dm-text-delivery.js";
+  getTaskProgressDataFromSurfaceData,
+  mergeTaskProgressData,
+} from "../../slack-task-progress.js";
+import { isContactTrustClass } from "../../trust-class.js";
 import { resolveRoutingState } from "../../trust-context-resolver.js";
 import { finalizeEventDelivery } from "../channel-delivery-routes.js";
 import { deliverGeneratedApprovalPrompt } from "../guardian-approval-prompt.js";
@@ -236,20 +238,14 @@ export function processChannelMessageInBackground(
             }
           : undefined;
       let replyMessageId: string | undefined;
-      const slackDmTextDelivery = createSlackDmTextDeliveryController({
+      const slackReplySession = createSlackReplySession({
         sourceChannel,
         chatType,
         replyCallbackUrl,
         chatId: externalChatId,
         assistantId,
-        deliveredTextResponseIndexes:
-          getSlackDmLiveDeliveredTextResponseIndexes(eventId),
-        onTextResponseDelivered: (responseIndex, reason) => {
-          addSlackDmLiveDeliveredTextResponseIndex(eventId, responseIndex);
-          if (reason === "before_tool") {
-            slackThinkingStatus?.refreshAfterReply();
-          }
-        },
+        recipientUserId: slackInbound?.actorExternalUserId,
+        recipientTeamId: slackInbound?.actorTeamId,
       });
       const observeAgentEvent = (msg: ServerMessage): void => {
         if (
@@ -259,7 +255,7 @@ export function processChannelMessageInBackground(
         ) {
           replyMessageId = msg.messageId;
         }
-        slackDmTextDelivery?.observeEvent(msg);
+        slackReplySession?.observeEvent(msg);
         slackThinkingStatus?.observeEvent(msg);
       };
 
@@ -317,8 +313,11 @@ export function processChannelMessageInBackground(
           { err, conversationId },
           "Background channel message processing failed",
         );
-        if (slackDmTextDelivery) {
-          await slackDmTextDelivery.waitForPendingDeliveries();
+        if (slackReplySession) {
+          const reconciliation = await slackReplySession.finish();
+          if (reconciliation.mode === "streamed") {
+            storeStreamedReplyTs(eventId, reconciliation.messageTs);
+          }
         }
         recordProcessingFailure(eventId, err);
         return;
@@ -334,7 +333,7 @@ export function processChannelMessageInBackground(
             assistantId,
             replyMessageId,
             userMessageId,
-            slackDmTextDelivery,
+            slackReplySession,
           });
         } catch (err) {
           log.error(
@@ -414,47 +413,16 @@ function startTelegramTypingHeartbeat(
 
 type SlackThinkingStatusController = {
   observeEvent: (msg: ServerMessage) => void;
-  refreshAfterReply: () => void;
   stop: () => void;
 };
 
 type SlackThinkingStatusHandle = {
   updateLoadingMessages: (loadingMessages?: string[]) => void;
-  refresh: (loadingMessages?: string[]) => void;
   clear: () => void;
 };
 
-type TaskProgressStep = {
-  label: string;
-  status: "pending" | "in_progress" | "completed" | "failed";
-};
-
-type TaskProgressData = {
-  steps: TaskProgressStep[];
-};
-
-const NO_RESPONSE_RE = /^\s*<no_response\s*\/?>\s*$/i;
-const NO_RESPONSE_INLINE_RE = /<no_response\s*\/?>/gi;
-const NO_RESPONSE_SENTINEL_FORMS = [
-  "<no_response/>",
-  "<no_response />",
-  "<no_response>",
-] as const;
-
-function isPotentialNoResponsePrefix(text: string): boolean {
-  const lower = text.toLowerCase();
-  return NO_RESPONSE_SENTINEL_FORMS.some((sentinel) =>
-    sentinel.startsWith(lower),
-  );
-}
-
 export function shouldStartSlackThinkingStatusForText(text: string): boolean {
-  const trimmed = text.trim();
-  if (trimmed.length === 0) return false;
-  if (NO_RESPONSE_RE.test(trimmed)) return false;
-  if (isPotentialNoResponsePrefix(trimmed)) return false;
-
-  return trimmed.replace(NO_RESPONSE_INLINE_RE, "").trim().length > 0;
+  return hasDeliverableAssistantText(text);
 }
 
 function shouldEmitSlackThinkingStatus(
@@ -565,13 +533,6 @@ function createSlackThinkingStatusController(params: {
         start();
       }
     },
-    refreshAfterReply() {
-      if (stopped || !slackThinkingStatus) return;
-      // Slack clears assistant thread status when the app sends a reply, so
-      // live pre-tool replies need to reassert it while work continues.
-      slackThinkingStatus.refresh(currentLoadingMessages);
-      lastSentLoadingMessageKey = getLoadingMessagesKey(currentLoadingMessages);
-    },
     stop() {
       stopped = true;
       slackThinkingStatus?.clear();
@@ -593,53 +554,6 @@ function getLoadingMessagesKey(loadingMessages?: string[]): string | undefined {
   return loadingMessages?.join("\n");
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function getTaskProgressDataFromSurfaceData(
-  data: unknown,
-): TaskProgressData | undefined {
-  if (!isRecord(data)) return undefined;
-  if (data.template !== "task_progress") return undefined;
-  return parseTaskProgressData(data.templateData);
-}
-
-function parseTaskProgressData(value: unknown): TaskProgressData | undefined {
-  if (!isRecord(value) || !Array.isArray(value.steps)) return undefined;
-
-  const steps = value.steps.flatMap((step): TaskProgressStep[] => {
-    if (!isRecord(step)) return [];
-    if (typeof step.label !== "string") return [];
-    if (
-      step.status !== "pending" &&
-      step.status !== "in_progress" &&
-      step.status !== "completed" &&
-      step.status !== "failed"
-    ) {
-      return [];
-    }
-    return [{ label: step.label, status: step.status }];
-  });
-
-  return steps.length > 0 ? { steps } : undefined;
-}
-
-function mergeTaskProgressData(
-  existing: TaskProgressData | undefined,
-  data: unknown,
-): TaskProgressData | undefined {
-  if (!isRecord(data)) return existing;
-  const update = getTaskProgressDataFromSurfaceData(data);
-  if (update) return update;
-  if (!existing || !("templateData" in data)) return existing;
-
-  return parseTaskProgressData({
-    steps: existing.steps,
-    ...(isRecord(data.templateData) ? data.templateData : {}),
-  });
-}
-
 function getTaskProgressLoadingMessage(
   progress: TaskProgressData | undefined,
 ): string[] | undefined {
@@ -683,7 +597,6 @@ function setSlackThinkingStatus(
     if (!messageTs) {
       return {
         updateLoadingMessages: () => {},
-        refresh: () => {},
         clear: () => {},
       };
     }
@@ -725,7 +638,6 @@ function setSlackThinkingStatus(
 
     return {
       updateLoadingMessages: () => {},
-      refresh: () => {},
       clear: clearReaction,
     };
   }
@@ -768,10 +680,6 @@ function setSlackThinkingStatus(
     );
   };
 
-  const refresh = (nextLoadingMessages?: string[]): void => {
-    updateLoadingMessages(nextLoadingMessages);
-  };
-
   const clearStatus = (): void => {
     if (cleared) return;
     cleared = true;
@@ -799,7 +707,6 @@ function setSlackThinkingStatus(
 
   return {
     updateLoadingMessages,
-    refresh,
     clear: clearStatus,
   };
 }
@@ -935,9 +842,7 @@ function startTrustedContactApprovalNotifier(params: {
 
   // Only notify identity-known non-guardian contacts (trusted_contact and
   // unverified_contact) who have a resolvable guardian route.
-  const isIdentityKnownNonGuardian =
-    trustClass === "trusted_contact" || trustClass === "unverified_contact";
-  if (!isIdentityKnownNonGuardian || !guardianExternalUserId) {
+  if (!isContactTrustClass(trustClass) || !guardianExternalUserId) {
     return () => {};
   }
 

package/src/runtime/routes/inbound-stages/edit-intercept.ts

@@ -28,6 +28,7 @@ import {
   findMessageBySourceId,
   recordInbound,
 } from "../../../persistence/delivery-crud.js";
+import { enqueueLexicalIndexForMessage } from "../../../persistence/job-handlers/message-lexical.js";
 import { safeParseRecord } from "../../../util/json.js";
 import { getLogger } from "../../../util/logger.js";
 
@@ -100,7 +101,9 @@ export async function handleEditIntercept(
       conversationExternalId,
       sourceMessageId,
     );
-    if (original) break;
+    if (original) {
+      break;
+    }
     if (attempt < EDIT_LOOKUP_RETRIES) {
       log.info(
         {
@@ -156,6 +159,11 @@ export async function handleEditIntercept(
     } else {
       updateMessageContent(original.messageId, newContent);
     }
+    // The edit changed searchable text (the no-op guard above already returned
+    // for identical content) and this path bypasses `onMessagePersisted`, so
+    // reindex the message into the lexical index — the idempotent upsert
+    // replaces the stale Qdrant point with the edited content.
+    enqueueLexicalIndexForMessage(original.messageId);
     log.info(
       { assistantId, sourceMessageId, messageId: original.messageId },
       "Updated message content from edited_message",

package/src/runtime/routes/inbound-stages/escalation-intercept.test.ts

@@ -0,0 +1,158 @@
+/**
+ * Unit tests for `handleEscalationIntercept` guardian-principal resolution.
+ *
+ * A guardian binding whose gateway row carries no principal is UNRESOLVED, not
+ * present-but-empty: the intercept adopts the principal from the assistant's
+ * vellum anchor (via `resolveDecidableGuardianPrincipalId`), and when neither
+ * resolves it fails closed instead of creating an undecidable (principal-less)
+ * canonical request. The `""`-is-unresolved contract itself is pinned in
+ * `local-actor-identity.test.ts`.
+ */
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+mock.module("../../../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, { get: () => () => {} }),
+}));
+
+let mockBindingPrincipalId: string | null = null;
+let mockBindingPresent = true;
+mock.module("../../channel-verification-service.js", () => ({
+  getGuardianBinding: async () =>
+    mockBindingPresent
+      ? {
+          guardianExternalUserId: "guardian-1",
+          guardianPrincipalId: mockBindingPrincipalId,
+        }
+      : null,
+}));
+
+// Faithful stand-in for the shared adopt/repair helper: binding principal
+// when present, else the (test-controlled) vellum anchor principal.
+let mockAnchorPrincipal: string | undefined;
+mock.module("../../local-actor-identity.js", () => ({
+  resolveDecidableGuardianPrincipalId: async (
+    bindingPrincipalId: string | null,
+  ) => bindingPrincipalId || mockAnchorPrincipal,
+}));
+
+const createdRequests: Array<Record<string, unknown>> = [];
+mock.module("../../../contacts/canonical-guardian-store.js", () => ({
+  createCanonicalGuardianRequest: (params: Record<string, unknown>) => {
+    createdRequests.push(params);
+    return { ...params, requestCode: "ABC123" };
+  },
+}));
+
+mock.module("../../../notifications/emit-signal.js", () => ({
+  emitNotificationSignal: async () => ({ deliveryResults: [] }),
+}));
+
+mock.module("../../../persistence/delivery-crud.js", () => ({
+  storePayload: () => {},
+}));
+
+const { handleEscalationIntercept } = await import("./escalation-intercept.js");
+type EscalationInterceptParams = Parameters<
+  typeof handleEscalationIntercept
+>[0];
+
+function makeParams(
+  overrides: Partial<EscalationInterceptParams> = {},
+): EscalationInterceptParams {
+  return {
+    resolvedMember: {
+      contactId: "contact-1",
+      channelId: "channel-1",
+      status: "active",
+      policy: "escalate",
+      verifiedAt: null,
+      displayName: "Member",
+    },
+    canonicalAssistantId: "self",
+    sourceChannel: "telegram",
+    sourceInterface: "telegram",
+    conversationExternalId: "chat-1",
+    externalMessageId: "msg-1",
+    conversationId: "conv-1",
+    eventId: "evt-1",
+    content: "hello",
+    attachmentIds: undefined,
+    sourceMetadata: undefined,
+    actorDisplayName: "Member",
+    actorExternalId: "member-1",
+    actorUsername: "member_one",
+    replyCallbackUrl: "http://localhost/deliver",
+    canonicalSenderId: "member-1",
+    rawSenderId: "member-1",
+    ...overrides,
+  };
+}
+
+beforeEach(() => {
+  mockBindingPresent = true;
+  mockBindingPrincipalId = null;
+  mockAnchorPrincipal = undefined;
+  createdRequests.length = 0;
+});
+
+describe("handleEscalationIntercept — guardian principal resolution", () => {
+  test("binding with a principal creates the request with that principal", async () => {
+    mockBindingPrincipalId = "principal-1";
+
+    const response = await handleEscalationIntercept(makeParams());
+
+    expect(response).toMatchObject({ accepted: true, escalated: true });
+    expect(createdRequests).toHaveLength(1);
+    expect(createdRequests[0].guardianPrincipalId).toBe("principal-1");
+  });
+
+  test("null-principal binding adopts the vellum anchor principal (repair path)", async () => {
+    mockBindingPrincipalId = null;
+    mockAnchorPrincipal = "anchor-principal";
+
+    const response = await handleEscalationIntercept(makeParams());
+
+    expect(response).toMatchObject({ accepted: true, escalated: true });
+    expect(createdRequests).toHaveLength(1);
+    expect(createdRequests[0].guardianPrincipalId).toBe("anchor-principal");
+  });
+
+  test("unresolvable principal fails closed — no principal-less request is created", async () => {
+    mockBindingPrincipalId = null;
+    mockAnchorPrincipal = undefined;
+
+    const response = await handleEscalationIntercept(makeParams());
+
+    expect(response).toMatchObject({
+      accepted: true,
+      denied: true,
+      reason: "escalate_no_guardian",
+    });
+    expect(createdRequests).toHaveLength(0);
+  });
+
+  test("no binding at all still denies fail-closed", async () => {
+    mockBindingPresent = false;
+
+    const response = await handleEscalationIntercept(makeParams());
+
+    expect(response).toMatchObject({
+      accepted: true,
+      denied: true,
+      reason: "escalate_no_guardian",
+    });
+    expect(createdRequests).toHaveLength(0);
+  });
+
+  test("non-escalate member policy is a pass-through", async () => {
+    const params = makeParams();
+    const response = await handleEscalationIntercept(
+      makeParams({
+        resolvedMember: { ...params.resolvedMember!, policy: "allow" },
+      }),
+    );
+
+    expect(response).toBeNull();
+  });
+});

package/src/runtime/routes/inbound-stages/escalation-intercept.ts

@@ -13,6 +13,7 @@ import { emitNotificationSignal } from "../../../notifications/emit-signal.js";
 import { storePayload } from "../../../persistence/delivery-crud.js";
 import { getLogger } from "../../../util/logger.js";
 import { getGuardianBinding } from "../../channel-verification-service.js";
+import { resolveDecidableGuardianPrincipalId } from "../../local-actor-identity.js";
 import type { VerdictMember } from "../../trust-verdict-consumer.js";
 import { GUARDIAN_APPROVAL_TTL_MS } from "../channel-route-shared.js";
 
@@ -90,6 +91,26 @@ export async function handleEscalationIntercept(
     };
   }
 
+  // A binding with no principal is unresolved, not empty: adopt the vellum
+  // anchor principal so the resulting request is decidable by the guardian.
+  // When neither resolves, fail closed — a principal-less tool_approval
+  // request can never be authorized by anyone (it would sit pending with
+  // dead Approve/Reject buttons until expiry).
+  const guardianPrincipalId = await resolveDecidableGuardianPrincipalId(
+    binding.guardianPrincipalId,
+  );
+  if (!guardianPrincipalId) {
+    log.warn(
+      { sourceChannel, channelId: resolvedMember.channelId },
+      "Ingress ACL: escalate policy but guardian principal unresolved, denying",
+    );
+    return {
+      accepted: true,
+      denied: true,
+      reason: "escalate_no_guardian",
+    };
+  }
+
   // Persist the raw payload so the decide handler can recover the original
   // message content when the escalation is approved.
   storePayload(eventId, {
@@ -115,7 +136,7 @@ export async function handleEscalationIntercept(
       conversationId,
       requesterExternalUserId: canonicalSenderId ?? rawSenderId ?? undefined,
       guardianExternalUserId: binding.guardianExternalUserId,
-      guardianPrincipalId: binding.guardianPrincipalId,
+      guardianPrincipalId,
       toolName: "ingress_message",
       questionText: "Ingress policy requires guardian approval",
       expiresAt: Date.now() + GUARDIAN_APPROVAL_TTL_MS,

package/src/runtime/routes/index.ts

@@ -95,8 +95,10 @@ import { ROUTES as LLM_CALL_SITES_ROUTES } from "./llm-call-sites-routes.js";
 import { ROUTES as LOG_EXPORT_ROUTES } from "./log-export-routes.js";
 import { ROUTES as MCP_AUTH_ROUTES } from "./mcp-auth-routes.js";
 import { ROUTES as MEMORY_WORKER_ROUTES } from "./memory-worker-routes.js";
+import { ROUTES as MESSAGES_LEXICAL_ROUTES } from "./messages-lexical-routes.js";
 import { ROUTES as MIGRATION_ROLLBACK_ROUTES } from "./migration-rollback-routes.js";
 import { ROUTES as MIGRATION_ROUTES } from "./migration-routes.js";
+import { ROUTES as MONITORING_ROUTES } from "./monitoring-routes.js";
 import { ROUTES as NOTIFICATION_ROUTES } from "./notification-routes.js";
 import { ROUTES as OAUTH_APPS_ROUTES } from "./oauth-apps.js";
 import { ROUTES as OAUTH_COMMANDS_ROUTES } from "./oauth-commands-routes.js";
@@ -116,6 +118,7 @@ import { ROUTES as RENAME_CONVERSATION_ROUTES } from "./rename-conversation-rout
 import { ROUTES as RETROSPECTIVE_ROUTES } from "./retrospective-routes.js";
 import { ROUTES as SANITY_ROUTES } from "./sanity-routes.js";
 import { ROUTES as SCHEDULE_ROUTES } from "./schedule-routes.js";
+import { ROUTES as SCHEDULE_WORKER_ROUTES } from "./schedule-worker-routes.js";
 import { ROUTES as SECRET_ROUTES } from "./secret-routes.js";
 import { ROUTES as SEQUENCE_ROUTES } from "./sequence-routes.js";
 import { ROUTES as SETTINGS_ROUTES } from "./settings-routes.js";
@@ -230,6 +233,7 @@ export const ROUTES: RouteDefinition[] = [
   ...MEMORY_V2_ROUTES,
   ...MEMORY_V3_ROUTES,
   ...MEMORY_WORKER_ROUTES,
+  ...MESSAGES_LEXICAL_ROUTES,
   ...MIGRATION_ROLLBACK_ROUTES,
   ...MIGRATION_ROUTES,
   ...NOTIFICATION_ROUTES,
@@ -247,8 +251,10 @@ export const ROUTES: RouteDefinition[] = [
   ...QUESTION_ROUTES,
   ...RECORDING_ROUTES,
   ...RENAME_CONVERSATION_ROUTES,
+  ...MONITORING_ROUTES,
   ...RETROSPECTIVE_ROUTES,
   ...SCHEDULE_ROUTES,
+  ...SCHEDULE_WORKER_ROUTES,
   ...SANITY_ROUTES,
   ...SECRET_ROUTES,
   ...SETTINGS_ROUTES,

package/src/runtime/routes/inference-provider-connection-routes.ts

@@ -10,6 +10,7 @@
 
 import { z } from "zod";
 
+import { getIsPlatform } from "../../config/env-registry.js";
 import { getConfigReadOnly } from "../../config/loader.js";
 import { getDb } from "../../persistence/db-connection.js";
 import {
@@ -103,24 +104,29 @@ async function parseCustomProviderFields(
         );
       }
 
-      // SSRF protection: reject private IPs, localhost, cloud metadata endpoints.
-      const hostname = parsed.hostname;
-      if (isPrivateOrLocalHost(hostname)) {
-        throw new BadRequestError(
-          `Invalid base_url: must not point to a private or local network address.`,
-        );
-      }
+      // SSRF protection: reject private IPs, localhost, cloud metadata
+      // endpoints — but only for platform-hosted daemons where the container
+      // runs on Vellum infrastructure. Self-hosted daemons run on the user's
+      // own machine, so localhost/private addresses are the expected target
+      // (e.g. LM Studio, vLLM, text-generation-webui).
+      if (getIsPlatform()) {
+        const hostname = parsed.hostname;
+        if (isPrivateOrLocalHost(hostname)) {
+          throw new BadRequestError(
+            `Invalid base_url: must not point to a private or local network address.`,
+          );
+        }
 
-      // DNS resolution check: hostname may resolve to a private IP.
-      const resolved = await resolveRequestAddress(
-        hostname,
-        resolveHostAddresses,
-        /* allowPrivateNetwork */ false,
-      );
-      if (resolved.blockedAddress) {
-        throw new BadRequestError(
-          `Invalid base_url: hostname resolves to a private network address.`,
+        const resolved = await resolveRequestAddress(
+          hostname,
+          resolveHostAddresses,
+          /* allowPrivateNetwork */ false,
         );
+        if (resolved.blockedAddress) {
+          throw new BadRequestError(
+            `Invalid base_url: hostname resolves to a private network address.`,
+          );
+        }
       }
 
       out.baseUrl = raw;

package/src/runtime/routes/internal-twilio-routes.ts

@@ -6,7 +6,6 @@
  */
 
 import {
-  handleInternalConnectAction,
   handleInternalStatusCallback,
   handleInternalVoiceWebhook,
 } from "../../calls/twilio-routes.js";
@@ -42,18 +41,4 @@ export const ROUTES: RouteDefinition[] = [
     tags: ["internal"],
     handler: handleInternalStatusCallback,
   },
-  {
-    operationId: "internal_twilio_connect_action",
-    endpoint: "internal/twilio/connect-action",
-    method: "POST",
-    policy: {
-      requiredScopes: ["internal.write"],
-      allowedPrincipalTypes: GATEWAY_PRINCIPALS,
-    },
-    summary: "Internal Twilio connect-action",
-    description:
-      "Gateway-to-runtime forwarding for ConversationRelay connect-action callback.",
-    tags: ["internal"],
-    handler: handleInternalConnectAction,
-  },
 ];

package/src/runtime/routes/messages-lexical-routes.ts

@@ -0,0 +1,75 @@
+/**
+ * Messages lexical-index route — enqueues the resumable backfill that indexes
+ * existing messages into the Qdrant lexical collection.
+ *
+ * Deliberately NOT gated on `memory.v2.enabled`: the lexical index powers
+ * regular message-content search and is independent of the v2 concept-page
+ * machinery. The backfill runs off the event loop as a cursor-checkpointed
+ * background job. This route enqueues it on demand (operator or client); the
+ * one-time, checkpoint-guarded startup auto-enqueue
+ * (`maybeEnqueueLexicalBackfillOnUpgrade`) enqueues the same job once per
+ * instance on upgrade.
+ */
+
+import { z } from "zod";
+
+import { clearLexicalBackfillComplete } from "../../persistence/checkpoints.js";
+import {
+  enqueueMemoryJob,
+  type MemoryJobType,
+} from "../../persistence/jobs-store.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
+import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
+
+const BACKFILL_LEXICAL_INDEX_JOB: MemoryJobType = "backfill_lexical_index";
+
+const MessagesLexicalBackfillParams = z
+  .object({
+    /**
+     * Reset the cursor and re-index every message from the beginning. Omit (or
+     * pass false) to resume from the last checkpoint — the common case for
+     * continuing an interrupted backfill.
+     */
+    force: z.boolean().optional(),
+  })
+  .strict();
+
+export type MessagesLexicalBackfillResult = {
+  jobId: string;
+};
+
+async function handleBackfillLexicalIndex({
+  body = {},
+}: RouteHandlerArgs): Promise<MessagesLexicalBackfillResult> {
+  const { force } = MessagesLexicalBackfillParams.parse(body);
+  if (force === true) {
+    // Clear the completion sentinel at enqueue time so `isLexicalBackfillComplete()`
+    // flips false immediately — the read paths fall back to SQLite FTS in the window
+    // between enqueue and the worker claiming the job, instead of serving from the
+    // stale/emptying `messages_lexical` collection the forced rebuild is about to
+    // reset. The handler clears it again when it runs (idempotent).
+    clearLexicalBackfillComplete();
+  }
+  const payload: Record<string, unknown> =
+    force === true ? { force: true } : {};
+  const jobId = enqueueMemoryJob(BACKFILL_LEXICAL_INDEX_JOB, payload);
+  return { jobId };
+}
+
+export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "messages_lexical_backfill",
+    method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    endpoint: "messages/lexical/backfill",
+    handler: handleBackfillLexicalIndex,
+    summary: "Enqueue a resumable backfill of messages into the lexical index",
+    description:
+      "Enqueues the cursor-checkpointed backfill job that indexes existing messages into the Qdrant lexical (BM25-style) collection in batches. Resumable and idempotent — re-running continues from the last checkpoint. Pass `force: true` to reset the cursor and re-index from the beginning. The same backfill is also auto-enqueued once per instance on upgrade at assistant startup.",
+    tags: ["memory"],
+    requestBody: MessagesLexicalBackfillParams,
+  },
+];