@vellumai/assistant 0.8.10 → 0.8.11-staging.1

package/src/runtime/routes/acp-routes.ts

@@ -4,6 +4,8 @@
  * Exposes spawn, steer, cancel, close, sessions, and permission operations
  * over HTTP and IPC.
  */
+import { randomUUID } from "node:crypto";
+
 import { and, desc, eq, inArray, notInArray } from "drizzle-orm";
 import { z } from "zod";
 
@@ -13,16 +15,20 @@ import { prepareAgentEnv } from "../../acp/prepare-agent-env.js";
 import { formatResolveFailure } from "../../acp/resolve-agent.js";
 import { AcpResumeError } from "../../acp/session-manager.js";
 import type { AcpSessionState } from "../../acp/types.js";
+import { getConfig } from "../../config/loader.js";
 import { getDb } from "../../memory/db-connection.js";
 import { rawChanges } from "../../memory/raw-query.js";
 import { acpSessionHistory } from "../../memory/schema.js";
+import type { UserDecision } from "../../permissions/types.js";
 import { broadcastMessage } from "../../runtime/assistant-event-hub.js";
 import { getLogger } from "../../util/logger.js";
 import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
+import * as pendingInteractions from "../pending-interactions.js";
 import {
   BadRequestError,
   ConflictError,
   FailedDependencyError,
+  ForbiddenError,
   NotFoundError,
 } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
@@ -53,7 +59,109 @@ type SessionEntry = z.infer<typeof sessionEntrySchema>;
 // Handlers
 // ---------------------------------------------------------------------------
 
-async function spawnSession({ body }: RouteHandlerArgs) {
+/**
+ * Surface a high-risk confirmation for an ACP route that starts a host agent
+ * subprocess (`POST /v1/acp/spawn`, and the resume branch of
+ * `POST /v1/acp/:id/steer`) and resolve to the guardian's decision.
+ *
+ * Unlike the `acp_spawn` / `acp_steer` skill tools (which are dispatched
+ * through `ToolExecutor`/`PermissionChecker` and so inherit the descriptors'
+ * `risk: "high"` approval prompt), these HTTP/IPC routes reach the ACP
+ * session manager directly. A spawned ACP agent is a host subprocess with
+ * advertised filesystem + terminal access whose in-session permission
+ * requests are auto-allowed, so starting one is exactly the high-risk action
+ * the descriptors gate. Without this prompt a caller holding only
+ * `chat.write` could start one with no human in the loop — directly via
+ * spawn (arbitrary `cwd`), or by resuming a terminal session via steer (its
+ * persisted `cwd`, enumerable through `GET /v1/acp/sessions`) (ATL-822).
+ *
+ * The confirmation is registered with `directResolve` so `POST /v1/confirm`
+ * resolves it without a live `Conversation` object. That route requires the
+ * bound guardian (`approval.write` + `requireGuardian`) — a strictly higher
+ * bar than the `chat.write` these routes demand — so the `chat.write` caller
+ * cannot self-approve. Timeout and client disconnect both deny, matching the
+ * tool path's "no interactive client → do not run" posture.
+ */
+function awaitRouteApproval(args: {
+  toolName: string;
+  input: Record<string, unknown>;
+  conversationId: string;
+  signal?: AbortSignal;
+}): Promise<UserDecision> {
+  const { toolName, input, conversationId, signal } = args;
+  const requestId = randomUUID();
+  // Mirror the interactive prompt timeout; fall back to the schema default
+  // (300s) if the timeouts block is somehow absent so the gate never wedges.
+  const timeoutMs = (getConfig().timeouts?.permissionTimeoutSec ?? 300) * 1000;
+
+  return new Promise<UserDecision>((resolve) => {
+    let settled = false;
+    const settle = (
+      decision: UserDecision,
+      state: "approved" | "rejected" | "cancelled",
+    ) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+      // Idempotent: the `/v1/confirm` directResolve path already removed the
+      // entry before invoking us, so this is a no-op there and only fires
+      // `interaction_resolved` for the timeout/abort paths.
+      pendingInteractions.resolve(requestId, state);
+      resolve(decision);
+    };
+
+    const timer = setTimeout(() => {
+      log.warn(
+        { requestId, toolName, conversationId },
+        "ACP route approval timed out — denying",
+      );
+      settle("deny", "cancelled");
+    }, timeoutMs);
+
+    const onAbort = () => settle("deny", "cancelled");
+    if (signal?.aborted) {
+      clearTimeout(timer);
+      resolve("deny");
+      return;
+    }
+    signal?.addEventListener("abort", onAbort, { once: true });
+
+    pendingInteractions.register(requestId, {
+      conversationId,
+      kind: "confirmation",
+      confirmationDetails: {
+        toolName,
+        input,
+        riskLevel: "high",
+        executionTarget: "host",
+        allowlistOptions: [],
+        scopeOptions: [],
+        persistentDecisionsAllowed: false,
+      },
+      directResolve: (decision) =>
+        settle(decision, decision === "allow" ? "approved" : "rejected"),
+    });
+
+    broadcastMessage(
+      {
+        type: "confirmation_request",
+        requestId,
+        toolName,
+        input,
+        riskLevel: "high",
+        executionTarget: "host",
+        allowlistOptions: [],
+        scopeOptions: [],
+        conversationId,
+        persistentDecisionsAllowed: false,
+      },
+      conversationId,
+    );
+  });
+}
+
+async function spawnSession({ body, abortSignal }: RouteHandlerArgs) {
   const agent = body?.agent as string | undefined;
   const task = body?.task as string | undefined;
   const conversationId = body?.conversationId as string | undefined;
@@ -63,6 +171,22 @@ async function spawnSession({ body }: RouteHandlerArgs) {
     throw new BadRequestError("agent, task, and conversationId are required");
   }
 
+  // High-risk approval gate. Block BEFORE any side effects — resolution can
+  // trigger a `bun` global install (auto-install.ts) and `manager.spawn`
+  // launches the host subprocess — so an unapproved request mutates nothing.
+  const decision = await awaitRouteApproval({
+    toolName: "acp_spawn",
+    input: { agent, task, cwd },
+    conversationId,
+    signal: abortSignal,
+  });
+  if (decision !== "allow") {
+    throw new ForbiddenError(
+      "Spawning an ACP coding agent requires guardian approval, which was " +
+        "not granted.",
+    );
+  }
+
   // Resolve the agent, silently auto-installing a missing allowlisted
   // adapter binary (see acp/auto-install.ts). Shared with the skill-tool
   // path in tools/acp/spawn.ts; only the transport mapping differs.
@@ -117,6 +241,43 @@ async function steerSession({ pathParams, body }: RouteHandlerArgs) {
   // broadcastMessage plays the sender role spawnSession gives it, so
   // connected clients render the session.
   const manager = getAcpSessionManager();
+
+  // Resume re-spawns the host agent subprocess, so it crosses the same
+  // high-risk boundary as spawn and needs guardian approval (ATL-822). A
+  // steer of a session still active in memory only redirects an
+  // already-running, already-approved process, so it is left unprompted —
+  // matching "gate before spawning". A resume only happens when the id is
+  // absent from memory AND a resumable history row (non-null cwd) exists.
+  if (!manager.getActiveAndPendingIds().includes(id)) {
+    const resumable = getDb()
+      .select({
+        cwd: acpSessionHistory.cwd,
+        agentId: acpSessionHistory.agentId,
+        parentConversationId: acpSessionHistory.parentConversationId,
+      })
+      .from(acpSessionHistory)
+      .where(eq(acpSessionHistory.id, id))
+      .get();
+    if (resumable?.cwd != null) {
+      // Guardian approval is an out-of-band human action that can take far
+      // longer than a client's ack timeout (the macOS client uses 10s; the
+      // approval window is permissionTimeoutSec, default 300s). Blocking the
+      // HTTP response here would surface as a client transport failure even
+      // on an eventual approval. Acknowledge immediately and run approval +
+      // resume in the background, streaming via SSE like any other ACP
+      // activity. The request abortSignal is deliberately NOT threaded into
+      // the wait — the request is already complete.
+      void approveThenResume({
+        id,
+        instruction,
+        agentId: resumable.agentId,
+        cwd: resumable.cwd,
+        conversationId: resumable.parentConversationId,
+      });
+      return { acpSessionId: id, steered: false, approvalPending: true };
+    }
+  }
+
   try {
     const { resumed } = await manager.steerOrResume(
       id,
@@ -138,6 +299,81 @@ async function steerSession({ pathParams, body }: RouteHandlerArgs) {
   }
 }
 
+/**
+ * Background worker for an approval-gated ACP resume initiated over the steer
+ * route. Awaits the guardian decision (see `awaitRouteApproval`), then resumes
+ * via the session manager so the agent's output streams back over SSE. A
+ * denial, timeout, or resume failure is surfaced as an `acp_session_error` on
+ * the parent conversation so the client isn't left with an optimistic steer
+ * row and no follow-up. Never throws — it owns the request lifecycle after the
+ * route has already acked.
+ */
+async function approveThenResume(args: {
+  id: string;
+  instruction: string;
+  agentId: string;
+  cwd: string;
+  conversationId: string;
+}): Promise<void> {
+  const decision = await awaitRouteApproval({
+    toolName: "acp_steer",
+    input: {
+      acp_session_id: args.id,
+      instruction: args.instruction,
+      agent: args.agentId,
+      cwd: args.cwd,
+    },
+    conversationId: args.conversationId,
+  });
+
+  if (decision !== "allow") {
+    log.info(
+      { acpSessionId: args.id, conversationId: args.conversationId },
+      "ACP resume approval not granted — skipping resume",
+    );
+    broadcastMessage(
+      {
+        type: "acp_session_error",
+        // Key the error by the daemon session id (the value the steer route
+        // accepts and ACP SSE consumers index by — see registerSession, where
+        // state.id is the broadcast acpSessionId), NOT the persisted protocol
+        // id. A denied resume never emits acp_session_spawned to map the
+        // protocol id, so a protocol-keyed error would be dropped.
+        acpSessionId: args.id,
+        error: "Resume was not approved.",
+      },
+      args.conversationId,
+    );
+    return;
+  }
+
+  try {
+    await getAcpSessionManager().steerOrResume(
+      args.id,
+      args.instruction,
+      broadcastMessage,
+    );
+  } catch (err) {
+    const message =
+      err instanceof AcpResumeError || err instanceof Error
+        ? err.message
+        : String(err);
+    log.warn(
+      { acpSessionId: args.id, conversationId: args.conversationId, err },
+      "Approved ACP resume failed",
+    );
+    broadcastMessage(
+      {
+        type: "acp_session_error",
+        // Daemon session id (route + SSE key), not the protocol id — see above.
+        acpSessionId: args.id,
+        error: message,
+      },
+      args.conversationId,
+    );
+  }
+}
+
 async function cancelSession({ pathParams }: RouteHandlerArgs) {
   const id = pathParams?.id as string;
   const manager = getAcpSessionManager();
@@ -276,7 +512,10 @@ export const ROUTES: RouteDefinition[] = [
       "Send a steering instruction to an ACP session. Sessions no longer " +
       "in memory (completed, or lost to a daemon restart) are " +
       "transparently resumed from persisted history first, when the agent " +
-      "supports ACP session loading.",
+      "supports ACP session loading. Resuming a terminal session re-spawns " +
+      "the host agent, so it requires guardian approval: the route acks " +
+      "immediately with approvalPending=true and performs the resume in the " +
+      "background once approved, streaming results over SSE.",
     tags: ["acp"],
     requestBody: z.object({
       instruction: z.string(),
@@ -290,6 +529,13 @@ export const ROUTES: RouteDefinition[] = [
         .describe(
           "True when the session was resumed from persisted history before steering.",
         ),
+      approvalPending: z
+        .boolean()
+        .optional()
+        .describe(
+          "True when the steer triggered a guardian-approval-gated resume " +
+            "that will run asynchronously; watch SSE for the outcome.",
+        ),
     }),
   },
   {

package/src/runtime/routes/browser-tabs-routes.ts

@@ -114,7 +114,7 @@ async function handleBrowserTabs({ body = {} }: RouteHandlerArgs) {
         }
       } else if (targetClientId) {
         // Only scope-clear the targeted client's pin. With the per-(conversationId,
-        // clientId) pin store (#31361), passing no clientId to clearPinnedTab
+        // clientId) pin store, passing no clientId to clearPinnedTab
         // would wipe pins for *every* connected client on this conversation
         // and break their routing — so we skip the clear entirely when the
         // caller didn't explicitly target a client. The stale pin (if any)

package/src/runtime/routes/channel-verification-routes.ts

@@ -23,6 +23,7 @@ import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import { revokePendingSessions } from "../channel-verification-service.js";
 import {
   cancelOutbound,
+  deliverVerificationEmail,
   deliverVerificationSlack,
   normalizeTelegramDestination,
   resendOutbound,
@@ -139,11 +140,15 @@ export async function handleCreateVerificationSession({
       verificationRateLimiter.recordFailure(rateLimitKey);
     }
 
-    // Dispatch Slack DM delivery from the daemon process (not sandboxed).
+    // Dispatch delivery from the daemon process (not sandboxed).
     if (result._pendingSlackDm) {
       const { userId, text, assistantId: aid } = result._pendingSlackDm;
       deliverVerificationSlack(userId, text, aid);
     }
+    if (result._pendingEmail) {
+      const { to, text, subject, assistantId: aid } = result._pendingEmail;
+      deliverVerificationEmail(to, text, subject, aid);
+    }
 
     if (!result.success) {
       if (result.error === "rate_limited") {
@@ -157,8 +162,8 @@ export async function handleCreateVerificationSession({
       );
     }
 
-    // Strip internal field from the response
-    const { _pendingSlackDm: _, ...publicResult } = result;
+    // Strip internal fields from the response
+    const { _pendingSlackDm: _, _pendingEmail: __, ...publicResult } = result;
     return publicResult;
   }
 
@@ -204,11 +209,15 @@ export async function handleResendVerificationSession({
 
   const result = resendOutbound({ channel, originConversationId });
 
-  // Dispatch Slack DM delivery from the daemon process (not sandboxed).
+  // Dispatch delivery from the daemon process (not sandboxed).
   if (result._pendingSlackDm) {
     const { userId, text, assistantId: aid } = result._pendingSlackDm;
     deliverVerificationSlack(userId, text, aid);
   }
+  if (result._pendingEmail) {
+    const { to, text, subject, assistantId: aid } = result._pendingEmail;
+    deliverVerificationEmail(to, text, subject, aid);
+  }
 
   if (!result.success) {
     if (result.error === "rate_limited") {
@@ -221,7 +230,7 @@ export async function handleResendVerificationSession({
     );
   }
 
-  const { _pendingSlackDm: _, ...publicResult } = result;
+  const { _pendingSlackDm: _, _pendingEmail: __, ...publicResult } = result;
   return publicResult;
 }
 

package/src/runtime/routes/chatgpt-subscription-auth-routes.ts

@@ -11,8 +11,6 @@
 
 import { z } from "zod";
 
-import { isAssistantFeatureFlagEnabled } from "../../config/assistant-feature-flags.js";
-import { getConfigReadOnly } from "../../config/loader.js";
 import { getDb } from "../../memory/db-connection.js";
 import {
   createConnection,
@@ -29,18 +27,8 @@ import {
 import { setSecureKeyAsync } from "../../security/secure-keys.js";
 import { getLogger } from "../../util/logger.js";
 import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
-import { BadRequestError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
-function requireFeatureFlag() {
-  const config = getConfigReadOnly();
-  if (!isAssistantFeatureFlagEnabled("chatgpt-subscription-auth", config)) {
-    throw new BadRequestError(
-      "ChatGPT subscription auth is not enabled for this assistant.",
-    );
-  }
-}
-
 const log = getLogger("chatgpt-subscription-auth");
 
 // ---------------------------------------------------------------------------
@@ -87,7 +75,6 @@ function cleanupExpiredEntries(): void {
 // ---------------------------------------------------------------------------
 
 async function handleStartAuth(_args: RouteHandlerArgs) {
-  requireFeatureFlag();
   cleanupExpiredEntries();
 
   const codeVerifier = generateCodeVerifier();
@@ -115,7 +102,6 @@ async function handleStartAuth(_args: RouteHandlerArgs) {
 }
 
 async function handleExchange(args: RouteHandlerArgs) {
-  requireFeatureFlag();
   const { code, state } = args.body as { code: string; state: string };
 
   const pending = pendingAuths.get(state);

package/src/runtime/routes/consolidation-routes.ts

@@ -15,20 +15,13 @@
 
 import { z } from "zod";
 
-import {
-  getConfig,
-  invalidateConfigCache,
-  loadRawConfig,
-  saveRawConfig,
-} from "../../config/loader.js";
-import type { AssistantConfig } from "../../config/schema.js";
+import { getConfig } from "../../config/loader.js";
 import { getMemoryCheckpoint } from "../../memory/checkpoints.js";
 import {
   getMessageRoleStatsByConversation,
   listConversationsBySource,
 } from "../../memory/conversation-queries.js";
 import {
-  cancelPendingAutomaticConsolidationJobs,
   enqueueMemoryJob,
   hasActiveJobOfType,
   MEMORY_V2_CONSOLIDATION_JOB_TRIGGERS,
@@ -37,15 +30,12 @@ import { GRAPH_MAINTENANCE_CHECKPOINTS } from "../../memory/jobs-worker.js";
 import { getUsageCostForConversationWindow } from "../../memory/llm-usage-store.js";
 import { MEMORY_V2_CONSOLIDATION_SOURCE } from "../../memory/v2/constants.js";
 import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
-import { BadRequestError, InternalError } from "./errors.js";
+import { BadRequestError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 function isConsolidationAvailable(): boolean {
-  return getConfig().memory.v2.enabled;
-}
-
-function isAutomaticConsolidationEnabled(config: AssistantConfig): boolean {
-  return config.memory.v2.enabled && config.memory.v2.consolidation_enabled;
+  const config = getConfig();
+  return config.memory.enabled !== false && config.memory.v2.enabled;
 }
 
 function consolidationIntervalMs(): number {
@@ -63,8 +53,8 @@ function readLastRunAt(): number | null {
 
 function readConsolidationConfigResponse() {
   const config = getConfig();
-  const available = config.memory.v2.enabled;
-  const enabled = isAutomaticConsolidationEnabled(config);
+  const available = config.memory.enabled !== false && config.memory.v2.enabled;
+  const enabled = available;
   const intervalMs = consolidationIntervalMs();
   const lastRunAt = readLastRunAt();
   const nextRunAt =
@@ -79,43 +69,6 @@ function readConsolidationConfigResponse() {
   };
 }
 
-function handleUpdateConfig(body: Record<string, unknown>) {
-  const consolidationPatch: Record<string, unknown> = {};
-  const disablingAutomaticConsolidation = body.enabled === false;
-  if ("enabled" in body && typeof body.enabled === "boolean") {
-    consolidationPatch.consolidation_enabled = body.enabled;
-  }
-
-  try {
-    const raw = loadRawConfig() as Record<string, unknown>;
-    const memory =
-      raw.memory != null && typeof raw.memory === "object"
-        ? (raw.memory as Record<string, unknown>)
-        : {};
-    const v2 =
-      memory.v2 != null && typeof memory.v2 === "object"
-        ? (memory.v2 as Record<string, unknown>)
-        : {};
-
-    raw.memory = {
-      ...memory,
-      v2: {
-        ...v2,
-        ...consolidationPatch,
-      },
-    };
-    saveRawConfig(raw);
-    invalidateConfigCache();
-    if (disablingAutomaticConsolidation) {
-      cancelPendingAutomaticConsolidationJobs();
-    }
-  } catch {
-    throw new InternalError("Failed to save consolidation config");
-  }
-
-  return readConsolidationConfigResponse();
-}
-
 // ---------------------------------------------------------------------------
 // Shared ROUTES
 // ---------------------------------------------------------------------------
@@ -145,35 +98,6 @@ export const ROUTES: RouteDefinition[] = [
       return readConsolidationConfigResponse();
     },
   },
-  {
-    operationId: "updateConsolidationConfig",
-    endpoint: "consolidation/config",
-    method: "PUT",
-    policy: {
-      requiredScopes: ["settings.write"],
-      allowedPrincipalTypes: ACTOR_PRINCIPALS,
-    },
-    summary: "Update consolidation config",
-    description: "Update the memory v2 consolidation schedule configuration.",
-    tags: ["consolidation"],
-    requestBody: z.object({
-      enabled: z
-        .boolean()
-        .optional()
-        .describe("Enable or disable automatic consolidation"),
-    }),
-    responseBody: z.object({
-      available: z.boolean(),
-      enabled: z.boolean(),
-      intervalMs: z.number(),
-      nextRunAt: z.number().nullable(),
-      lastRunAt: z.number().nullable(),
-      success: z.boolean(),
-    }),
-    handler: async ({ body = {} }: RouteHandlerArgs) => {
-      return handleUpdateConfig(body);
-    },
-  },
   {
     operationId: "runConsolidationNow",
     endpoint: "consolidation/run-now",

package/src/runtime/routes/conversation-list-routes.ts

@@ -133,6 +133,12 @@ export const conversationSummarySchema = z.object({
   groupId: z.string().nullable(),
   forkParent: forkParentSchema.optional(),
   archivedAt: z.number().optional(),
+  /**
+   * Epoch-ms timestamp set when a background/scheduled conversation was
+   * explicitly promoted ("surfaced") into the Recents sidebar grouping via
+   * `POST /v1/conversations/:id/surface`. Absent when not surfaced.
+   */
+  surfacedAt: z.number().optional(),
   inferenceProfile: z.string().optional(),
   /**
    * True when the agent loop is currently mid-turn for this conversation.

package/src/runtime/routes/conversation-management-routes.ts

@@ -11,6 +11,7 @@
  * DELETE /v1/conversations/:id            — delete a single conversation
  * POST   /v1/conversations/:id/archive    — archive a conversation
  * POST   /v1/conversations/:id/unarchive  — restore an archived conversation
+ * POST   /v1/conversations/:id/surface    — promote to / demote from Recents
  * POST   /v1/conversations/:id/cancel     — cancel generation
  * POST   /v1/conversations/:id/undo       — undo last message
  * POST   /v1/conversations/:id/regenerate — regenerate last assistant response
@@ -36,6 +37,7 @@ import {
   deleteConversation,
   forkConversation as forkConversationInStore,
   getConversation,
+  setConversationSurfaced,
   unarchiveConversation,
   updateConversationTitle,
   wipeConversation,
@@ -360,6 +362,43 @@ function handleUnarchiveConversation({
   return { ok: true, conversationId: resolvedId };
 }
 
+/**
+ * Set or clear the `surfacedAt` promotion marker on a conversation.
+ *
+ * Surfacing is the explicit opt-in that makes a background/scheduled
+ * conversation appear in the default conversation listing (and therefore the
+ * Recents sidebar grouping). It is never set automatically — product flows
+ * call this when a background conversation deserves foreground visibility
+ * (e.g. the user sent a follow-up message in it).
+ */
+function handleSurfaceConversation({
+  pathParams = {},
+  body = {},
+  headers,
+}: RouteHandlerArgs) {
+  if (typeof body.surfaced !== "boolean") {
+    throw new BadRequestError("Missing surfaced boolean");
+  }
+  const resolvedId = resolveOrThrow(pathParams.id!);
+  const result = setConversationSurfaced(resolvedId, body.surfaced);
+  if (!result) {
+    throw new NotFoundError(`Conversation ${pathParams.id} not found`);
+  }
+  // Shape-changing for the default list (row appears in / disappears from
+  // the standard listing), so publish with a shape-changing reason — web
+  // refetches the paginated list, macOS gets the legacy typed broadcast.
+  publishConversationListAndMetadataChanged(
+    "reordered",
+    resolvedId,
+    headers?.["x-vellum-client-id"]?.trim() || undefined,
+  );
+  return {
+    ok: true,
+    conversationId: resolvedId,
+    surfacedAt: result.surfacedAt,
+  };
+}
+
 function handleCancelGeneration({ pathParams = {} }: RouteHandlerArgs) {
   const resolvedId = resolveConversationId(pathParams.id!) ?? pathParams.id!;
   const cancelled = cancelGeneration(resolvedId);
@@ -656,6 +695,38 @@ export const ROUTES: RouteDefinition[] = [
     }),
     handler: handleUnarchiveConversation,
   },
+  {
+    operationId: "surfaceConversation",
+    endpoint: "conversations/:id/surface",
+    method: "POST",
+    policy: {
+      requiredScopes: ["chat.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "Surface a conversation into Recents",
+    description:
+      "Explicitly promote a background or scheduled conversation into the " +
+      "default conversation listing (the Recents sidebar grouping), or demote " +
+      "it with surfaced=false. Conversations are never surfaced automatically.",
+    tags: ["conversations"],
+    pathParams: [{ name: "id", type: "uuid" }],
+    requestBody: z.object({
+      surfaced: z
+        .boolean()
+        .describe(
+          "true to surface the conversation into Recents, false to clear the promotion.",
+        ),
+    }),
+    responseBody: z.object({
+      ok: z.boolean(),
+      conversationId: z.string(),
+      surfacedAt: z
+        .number()
+        .nullable()
+        .describe("Epoch-ms timestamp of the promotion, or null when cleared."),
+    }),
+    handler: handleSurfaceConversation,
+  },
   {
     operationId: "cancelConversationGeneration",
     endpoint: "conversations/:id/cancel",