@vellumai/assistant 0.11.4 → 0.11.5-staging.2

package/src/runtime/routes/__tests__/user-route-dispatcher-host.test.ts

@@ -3,7 +3,10 @@ import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
 
 import type { RouteInvokeParams } from "../../../routes/route-host-protocol.js";
-import { getWorkspaceRoutesDir } from "../../../util/platform.js";
+import {
+  getWorkspacePluginsDir,
+  getWorkspaceRoutesDir,
+} from "../../../util/platform.js";
 
 // The dispatcher constructs the route host client inline and reads the enabled
 // flag from config, so both are mocked here (there is no injection seam).
@@ -58,6 +61,16 @@ function writeHandler(name: string, content: string): void {
   writeFileSync(join(getWorkspaceRoutesDir(), name), content);
 }
 
+function writePluginHandler(
+  pluginName: string,
+  name: string,
+  content: string,
+): void {
+  const dir = join(getWorkspacePluginsDir(), pluginName, "routes");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, name), content);
+}
+
 function jsonResponse(status: number, value: unknown): RouteInvokeResponse {
   return {
     status,
@@ -75,6 +88,7 @@ beforeEach(() => {
 
 afterEach(() => {
   rmSync(getWorkspaceRoutesDir(), { recursive: true, force: true });
+  rmSync(getWorkspacePluginsDir(), { recursive: true, force: true });
 });
 
 describe("UserRouteDispatcher — route host delegation", () => {
@@ -101,6 +115,43 @@ describe("UserRouteDispatcher — route host delegation", () => {
     expect(invokeCalls[0].params.url).toContain("/v1/x/foo");
   });
 
+  test("names the owning plugin so the host executes in its context", async () => {
+    // The host marks this plugin as in context for the handler, so
+    // plugin-scoped host APIs behave the same in the host and in-thread.
+    writePluginHandler(
+      "my-plugin",
+      "status.ts",
+      `export function GET() { return new Response(); }`,
+    );
+    hostEnabled = true;
+    const dispatcher = makeDispatcher();
+
+    await dispatcher.dispatch(
+      "plugins/my-plugin/status",
+      new Request("http://localhost/v1/x/plugins/my-plugin/status", {
+        method: "GET",
+      }),
+    );
+
+    expect(invokeCalls[0].params.pluginName).toBe("my-plugin");
+  });
+
+  test("leaves a workspace route unowned", async () => {
+    writeHandler(
+      "plain.ts",
+      `export function GET() { return new Response(); }`,
+    );
+    hostEnabled = true;
+    const dispatcher = makeDispatcher();
+
+    await dispatcher.dispatch(
+      "plain",
+      new Request("http://localhost/v1/x/plain", { method: "GET" }),
+    );
+
+    expect(invokeCalls[0].params.pluginName).toBeUndefined();
+  });
+
   test("runs in-band when disabled (host never called)", async () => {
     writeHandler(
       "bar.ts",

package/src/runtime/routes/__tests__/user-route-dispatcher.test.ts

@@ -56,6 +56,15 @@ function writePluginHandler(
   return fullPath;
 }
 
+/**
+ * Absolute specifier for the plugin execution context, so a handler written to
+ * a temp routes directory imports the same module instance this process holds.
+ */
+const PLUGIN_CONTEXT_MODULE = new URL(
+  "../../../plugins/plugin-execution-context.ts",
+  import.meta.url,
+).href;
+
 async function readErrorBody(
   response: Response,
 ): Promise<{ error: { code: string; message: string } }> {
@@ -466,6 +475,71 @@ describe("plugin routes", () => {
     expect(body.plugin).toBe(true);
   });
 
+  test("executes the handler as the plugin that owns the namespace", async () => {
+    // Plugin-scoped host APIs (resolveCredential, indexDocument) read the
+    // execution context to decide what the caller may touch. A route handler
+    // that ran outside it would fall through to their unscoped branch and
+    // reach every plugin's credentials.
+    writePluginHandler(
+      "my-plugin",
+      "whoami.ts",
+      `import { getCurrentPluginName } from ${JSON.stringify(PLUGIN_CONTEXT_MODULE)};
+       export function GET(request) {
+        return Response.json({ plugin: getCurrentPluginName() ?? null });
+      }`,
+    );
+
+    const dispatcher = makeDispatcher();
+    const res = await dispatcher.dispatch(
+      "plugins/my-plugin/whoami",
+      makeRequest("GET"),
+    );
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.plugin).toBe("my-plugin");
+  });
+
+  test("evaluates the route module in the plugin's context too", async () => {
+    // A module can reach a scoped host API at import time, and the import
+    // happens once per mtime. A load left outside the context would take the
+    // unscoped branch and never be re-run scoped, so the context has to cover
+    // module evaluation and not just the handler call.
+    writePluginHandler(
+      "my-plugin",
+      "at-import.ts",
+      `import { getCurrentPluginName } from ${JSON.stringify(PLUGIN_CONTEXT_MODULE)};
+       const atImport = getCurrentPluginName() ?? null;
+       export function GET(request) {
+        return Response.json({ atImport });
+      }`,
+    );
+
+    const dispatcher = makeDispatcher();
+    const res = await dispatcher.dispatch(
+      "plugins/my-plugin/at-import",
+      makeRequest("GET"),
+    );
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.atImport).toBe("my-plugin");
+  });
+
+  test("leaves a workspace route outside any plugin context", async () => {
+    writeHandler(
+      "whoami.ts",
+      `import { getCurrentPluginName } from ${JSON.stringify(PLUGIN_CONTEXT_MODULE)};
+       export function GET(request) {
+        return Response.json({ plugin: getCurrentPluginName() ?? null });
+      }`,
+    );
+
+    const dispatcher = makeDispatcher();
+    const res = await dispatcher.dispatch("whoami", makeRequest("GET"));
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.plugin).toBeNull();
+  });
+
   test("resolves nested paths and the index (namespace root)", async () => {
     writePluginHandler(
       "my-plugin",
@@ -583,10 +657,7 @@ describe("plugin routes", () => {
     const plugin = "stale-helper";
     const helperPath = join(getWorkspacePluginsDir(), plugin, "src", "http.ts");
     mkdirSync(dirname(helperPath), { recursive: true });
-    writeFileSync(
-      helperPath,
-      `export function label() { return "v1"; }\n`,
-    );
+    writeFileSync(helperPath, `export function label() { return "v1"; }\n`);
     writePluginHandler(
       plugin,
       "frame.ts",

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

@@ -9,6 +9,7 @@
  */
 import { z } from "zod";
 
+import { PendingToolQuestionSchema } from "../../api/responses/conversation-message.js";
 import { findConversation } from "../../daemon/conversation-registry.js";
 import type {
   SecretDelivery,
@@ -210,9 +211,18 @@ function handleSecret({ body }: RouteHandlerArgs) {
  * GET /v1/pending-interactions?conversationKey=...&conversationId=...
  *
  * Returns pending interactions. When conversationKey or conversationId is
- * provided, returns the first pending confirmation and secret for that
- * conversation. When neither is provided, returns all pending interactions
- * across all conversations (diagnostic mode).
+ * provided, returns the outstanding confirmation, secret, and question for
+ * that conversation. When neither is provided, returns all pending
+ * interactions across all conversations (diagnostic mode).
+ *
+ * This registry is the authority on whether a prompt is still awaiting the
+ * user, so the conversation-scoped shape is what clients project their prompt
+ * UI from: a key present with a `null` value states "nothing outstanding of
+ * this kind" as positively as an object states the opposite. Every
+ * conversation-scoped return path below therefore names all three keys, even
+ * the early return for an unresolvable conversation. A client that sees a key
+ * missing entirely is talking to an assistant that predates it, which is how
+ * `pendingQuestion` consumers detect support without a version check.
  */
 function handleListPendingInteractions({ queryParams }: RouteHandlerArgs) {
   const conversationKey = queryParams?.conversationKey;
@@ -241,7 +251,11 @@ function handleListPendingInteractions({ queryParams }: RouteHandlerArgs) {
   }
 
   if (!resolvedConversationId) {
-    return { pendingConfirmation: null, pendingSecret: null };
+    return {
+      pendingConfirmation: null,
+      pendingSecret: null,
+      pendingQuestion: null,
+    };
   }
 
   const interactions = pendingInteractions.getByConversation(
@@ -252,6 +266,13 @@ function handleListPendingInteractions({ queryParams }: RouteHandlerArgs) {
     (i) => i.kind === "confirmation" || i.kind === "acp_confirmation",
   );
   const secret = interactions.find((i) => i.kind === "secret");
+  // Newest-first for questions: a new user message supersedes an open
+  // ask_question by steering to it, which settles the old prompt through its
+  // abort signal rather than synchronously, so both can sit in the registry
+  // for the width of that turn. The newer prompt is the one the user is being
+  // asked, so it is the one to report.
+  const questions = interactions.filter((i) => i.kind === "question");
+  const question = questions[questions.length - 1];
 
   return {
     pendingConfirmation: confirmation
@@ -288,6 +309,15 @@ function handleListPendingInteractions({ queryParams }: RouteHandlerArgs) {
           allowOneTimeSend: secret.secretDetails?.allowOneTimeSend,
         }
       : null,
+    // Reported only with its `entries`, since the batch is what the card
+    // renders; a prompt that somehow carries none is not something a client
+    // could raise.
+    pendingQuestion: question?.questionDetails
+      ? {
+          requestId: question.requestId,
+          entries: question.questionDetails.entries,
+        }
+      : null,
   };
 }
 
@@ -396,6 +426,9 @@ export const ROUTES: RouteDefinition[] = [
         .nullable()
         .describe("Pending secret request or null")
         .optional(),
+      pendingQuestion: PendingToolQuestionSchema.nullable()
+        .describe("Outstanding ask_question prompt or null")
+        .optional(),
       interactions: z
         .array(
           z.object({

package/src/runtime/routes/approval-strategies/guardian-text-engine-strategy.ts

@@ -3,6 +3,7 @@
  * the conversational approval engine when an approvalConversationGenerator is
  * available. Classifies natural language and responds conversationally.
  */
+import { audienceForReader } from "../../../channels/message-audience.js";
 import type { ChannelId } from "../../../channels/types.js";
 import { getLogger } from "../../../util/logger.js";
 import { runApprovalConversationTurn } from "../../approval-conversation-turn.js";
@@ -22,17 +23,6 @@ import { deliverStaleApprovalReply } from "../guardian-approval-reply-helpers.js
 
 const log = getLogger("runtime-http");
 
-/**
- * Resolve the Slack ephemeral user ID when the source channel is Slack.
- * Returns `undefined` for non-Slack channels.
- */
-function slackEphemeralUserId(
-  sourceChannel: ChannelId,
-  userId: string | undefined,
-): string | undefined {
-  return sourceChannel === "slack" && userId ? userId : undefined;
-}
-
 export interface TextEngineDecisionParams {
   conversationId: string;
   conversationExternalId: string;
@@ -96,11 +86,11 @@ export async function handleGuardianTextEngineDecision(
         text: engineResult.replyText,
         assistantId,
       };
-      const ephemeral = slackEphemeralUserId(sourceChannel, actorExternalId);
-      if (ephemeral) {
-        keepPendingPayload.ephemeral = true;
-        keepPendingPayload.user = ephemeral;
-      }
+      keepPendingPayload.audience = audienceForReader(
+        sourceChannel,
+        conversationExternalId,
+        actorExternalId,
+      );
       await deliverChannelReply(replyCallbackUrl, keepPendingPayload);
     } catch (err) {
       log.error(
@@ -131,11 +121,11 @@ export async function handleGuardianTextEngineDecision(
         text: engineResult.replyText,
         assistantId,
       };
-      const ephemeral = slackEphemeralUserId(sourceChannel, actorExternalId);
-      if (ephemeral) {
-        decisionPayload.ephemeral = true;
-        decisionPayload.user = ephemeral;
-      }
+      decisionPayload.audience = audienceForReader(
+        sourceChannel,
+        conversationExternalId,
+        actorExternalId,
+      );
       await deliverChannelReply(replyCallbackUrl, decisionPayload);
     } catch (err) {
       log.error(
@@ -160,7 +150,11 @@ export async function handleGuardianTextEngineDecision(
     logger: log,
     errorLogMessage: "Failed to deliver stale approval notice",
     errorLogContext: { conversationId },
-    ephemeralUserId: slackEphemeralUserId(sourceChannel, actorExternalId),
+    audience: audienceForReader(
+      sourceChannel,
+      conversationExternalId,
+      actorExternalId,
+    ),
   });
 
   return { handled: true, type: "stale_ignored" };

package/src/runtime/routes/canned-message-complete.ts

@@ -3,8 +3,8 @@ import type { AssistantEvent } from "../../api/index.js";
 import {
   addMessage,
   recordConversationPersistedSeq,
-  SYSTEM_CARD_MESSAGE_KIND,
 } from "../../persistence/conversation-crud.js";
+import { SYSTEM_CARD_MESSAGE_KIND } from "../../persistence/conversation-types.js";
 import type { Message } from "../../providers/types.js";
 import { broadcastMessage } from "../assistant-event-hub.js";
 import { getCurrentSeq } from "../assistant-stream-state.js";
@@ -40,33 +40,42 @@ export function emitCannedMessageComplete(
 }
 
 /**
- * Persist a canned assistant "card" — a pre-composed reply that bypasses the
- * agent loop (the /compact, /clean, and summarize-up-to result cards). The
- * row is stamped `messageKind: "system_card"` so transcripts render it as a
- * standalone system notice instead of assistant-persona speech, and display
- * merging never folds it into an adjacent assistant turn.
+ * Persist a system card: a daemon-authored notice that bypasses the agent
+ * loop. The row is stamped `messageKind: "system_card"` so transcripts render
+ * it as a standalone system notice instead of assistant-persona speech, and
+ * display merging never folds it into an adjacent assistant turn.
  *
- * Cards are announced with `message_complete` (persisted assistant id), the
- * persisted-seq anchor advance (so a stale /messages reseed cannot erase the
- * card), and the messages-changed sync invalidation that drives every client
- * to refetch. That invalidation carries no origin-client id: the card body
- * streams nowhere (`message_complete` is bodyless, no `assistant_text_delta`),
- * so the initiating client materializes it only by refetching, and origin
- * self-echo suppression (meant for content the origin already rendered) would
- * otherwise hide the card from the initiator until a reload. A delta is
- * deliberately omitted; it would stream the card into the tail assistant
- * bubble as if the persona were speaking.
+ * The card is persisted and announced to clients but not appended to the live
+ * conversation's working history, so a card written while a turn is in flight
+ * cannot leave a trailing assistant message for the next provider call to
+ * continue from. Callers whose card ends the turn use
+ * {@link persistCannedAssistantCard}, which also seats it in the live history.
  *
- * Returns the persisted card's message id so callers can link related
- * records to it (e.g. the compaction `llm_request_logs` row).
+ * Every card advances the persisted-seq anchor (so a stale /messages reseed
+ * cannot erase it) and publishes the messages-changed sync invalidation that
+ * drives every client to refetch. That invalidation carries no origin-client
+ * id: the card body streams nowhere (no `assistant_text_delta`), so the
+ * initiating client materializes it only by refetching, and origin self-echo
+ * suppression (meant for content the origin already rendered) would otherwise
+ * hide the card from the initiator until a reload. A delta is deliberately
+ * omitted; it would stream the card into the tail assistant bubble as if the
+ * persona were speaking.
+ *
+ * `endsTurn` decides whether the card also emits `message_complete`. Clients
+ * treat that event as terminal (it clears the processing state and closes the
+ * turn), so only a card that *is* the reply carries it. A card posted while a
+ * turn is still running (`endsTurn: false`) rides the sync invalidation alone,
+ * leaving the in-flight turn's streaming state intact.
+ *
+ * Returns the persisted card's id and the in-memory message it persisted.
  */
-export async function persistCannedAssistantCard(opts: {
-  conversation: { getMessages(): Message[] };
+export async function persistSystemCard(opts: {
   conversationId: string;
   text: string;
   metadata: Record<string, unknown>;
-}): Promise<string> {
-  const { conversation, conversationId, text, metadata } = opts;
+  endsTurn: boolean;
+}): Promise<{ id: string; message: Message }> {
+  const { conversationId, text, metadata, endsTurn } = opts;
   const assistantMsg = createAssistantMessage(text);
   const persistedAssistant = await addMessage(
     conversationId,
@@ -74,13 +83,43 @@ export async function persistCannedAssistantCard(opts: {
     JSON.stringify(assistantMsg.content),
     { metadata: { ...metadata, messageKind: SYSTEM_CARD_MESSAGE_KIND } },
   );
-  conversation.getMessages().push(assistantMsg);
-  emitCannedMessageComplete(
-    broadcastMessage,
-    conversationId,
-    persistedAssistant.id,
-  );
+  if (endsTurn) {
+    emitCannedMessageComplete(
+      broadcastMessage,
+      conversationId,
+      persistedAssistant.id,
+    );
+  }
   recordConversationPersistedSeq(conversationId, getCurrentSeq());
   publishConversationMessagesChanged(conversationId);
-  return persistedAssistant.id;
+  return { id: persistedAssistant.id, message: assistantMsg };
+}
+
+/**
+ * Persist a canned assistant "card" (a pre-composed reply that bypasses the
+ * agent loop: the /compact, /clean, and summarize-up-to result cards) and
+ * seat it in the live conversation's history so the turn that follows sees it.
+ * The row is stamped `messageKind: "system_card"` so transcripts render it as a
+ * standalone system notice instead of assistant-persona speech, and display
+ * merging never folds it into an adjacent assistant turn. Delivery is
+ * {@link persistSystemCard}'s.
+ *
+ * Returns the persisted card's message id so callers can link related
+ * records to it (e.g. the compaction `llm_request_logs` row).
+ */
+export async function persistCannedAssistantCard(opts: {
+  conversation: { getMessages(): Message[] };
+  conversationId: string;
+  text: string;
+  metadata: Record<string, unknown>;
+}): Promise<string> {
+  const { conversation, conversationId, text, metadata } = opts;
+  const card = await persistSystemCard({
+    conversationId,
+    text,
+    metadata,
+    endsTurn: true,
+  });
+  conversation.getMessages().push(card.message);
+  return card.id;
 }

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

@@ -37,6 +37,23 @@ const PresenceBodySchema = z.object({
     .describe("Reported desktop presence state."),
 });
 
+/**
+ * Body of `POST /v1/clients/web-presence`, declared as the route's
+ * `requestBody` and parsed by the handler, so the OpenAPI contract and the
+ * runtime check are one schema rather than two hand-kept copies.
+ */
+const WebPresenceBodySchema = z.object({
+  visible: z
+    .boolean()
+    .describe("Whether the reporting tab is currently visible."),
+  focusedConversationId: z
+    .string()
+    .nullable()
+    .describe(
+      "The conversation currently focused (chat composer on screen) in the tab, or null.",
+    ),
+});
+
 export const ROUTES: RouteDefinition[] = [
   {
     operationId: "list_clients",
@@ -228,4 +245,100 @@ export const ROUTES: RouteDefinition[] = [
       return { recorded: true };
     },
   },
+  {
+    operationId: "report_web_presence",
+    endpoint: "clients/web-presence",
+    method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "Report web tab visibility and focused conversation",
+    description:
+      "Record the visibility and focused conversation reported by the web client identified by the X-Vellum-Client-Id header.",
+    tags: ["clients"],
+    requestBody: WebPresenceBodySchema,
+    responseBody: z.object({
+      recorded: z
+        .boolean()
+        .describe("Whether a connected client matched the reporting clientId."),
+    }),
+    handler: ({ body, headers }) => {
+      const clientId = headers?.["x-vellum-client-id"]?.trim();
+      if (!clientId) {
+        throw new BadRequestError(
+          "x-vellum-client-id header is required to report presence.",
+        );
+      }
+      const { visible, focusedConversationId } = parseBody(
+        WebPresenceBodySchema,
+        body,
+      );
+
+      // Resolving the client first separates "nobody is listening" from
+      // "somebody else owns this", so only the second one is worth a warn.
+      const client = assistantEventHub.getClientById(clientId);
+      if (!client) {
+        // Debug, not warn: a report racing an SSE reconnect matches nothing,
+        // and a reconnect storm would otherwise emit a warn per client for a
+        // benign race. Not a 404 either, for the same reason.
+        log.debug(
+          { op: "report_web_presence" },
+          "Web presence report matched no connected client",
+        );
+        return { recorded: false };
+      }
+
+      // Only the actor that opened the target client's SSE stream may report
+      // its presence, so a caller who learns another user's clientId cannot
+      // spoof that tab. Clients with no stored `actorPrincipalId` (legacy SSE
+      // subscribers, service-gateway tokens) never match: fail-closed, the
+      // same posture as `report_client_presence`. Dev-bypass mode
+      // (DISABLE_HTTP_AUTH=true) skips the check for platform-managed
+      // deployments where the platform handles auth.
+      if (!isHttpAuthDisabled()) {
+        const callerPrincipalId = headers?.["x-vellum-actor-principal-id"];
+        const ownerPrincipalId = client.actorPrincipalId;
+        if (
+          ownerPrincipalId === undefined ||
+          ownerPrincipalId !== callerPrincipalId
+        ) {
+          // Warn, not debug: the client is connected, so a mismatch means the
+          // gateway stopped forwarding the actor header, a scope profile
+          // shifted, or a caller is probing someone else's client. Without
+          // this line presence gating dies silently and every suppressed
+          // push quietly resumes. Client and principal ids stay out of the
+          // entry so the log cannot be used to enumerate them.
+          log.warn(
+            {
+              op: "report_web_presence",
+              hasStoredOwner: ownerPrincipalId !== undefined,
+              hasCallerPrincipal: callerPrincipalId !== undefined,
+              targetInterfaceId: client.interfaceId,
+            },
+            "Rejecting web presence report from a caller that does not own the client",
+          );
+          // Answering like "no match" keeps the reply from probing client ids.
+          return { recorded: false };
+        }
+      }
+
+      // The lookup ran in this same synchronous handler, so the write lands on
+      // the entry it resolved.
+      assistantEventHub.setClientWebPresence(clientId, {
+        visible,
+        focusedConversationId,
+      });
+
+      log.debug(
+        {
+          op: "report_web_presence",
+          visible,
+          interfaceId: client.interfaceId,
+        },
+        "Recorded web presence",
+      );
+      return { recorded: true };
+    },
+  },
 ];

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

@@ -269,12 +269,18 @@ function handleListConversations({ queryParams = {} }: RouteHandlerArgs) {
       ? true
       : undefined;
 
+  const foregroundOnly =
+    parseEnumQueryParam(queryParams, "foregroundOnly", ["true"]) === "true"
+      ? true
+      : undefined;
+
   const filter: ConversationListFilter = {
     conversationType,
     archiveStatus,
     originChannel,
     groupId,
     needsAttention,
+    foregroundOnly,
   };
   let rows = listConversations({ ...filter, limit, offset });
   const totalCount = countConversations(filter);
@@ -289,19 +295,20 @@ function handleListConversations({ queryParams = {} }: RouteHandlerArgs) {
   // Skipped for group-scoped queries for the same reason: a caller asking
   // for one group gets that group, and a client that fetches the Pinned
   // section via `groupId=system:pinned` has no use for rows appended to
-  // some other group's page. Skipped for attention-scoped queries too: the
-  // caller asked for the unseen subset, and a seen pinned row appended to
-  // it would put a row outside the filter in the page while `hasMore` is
-  // computed from the filtered count. This is the compatibility shim for
-  // clients that still read Pinned out of the unfiltered list; it goes
-  // away once every section fetches its own group.
+  // some other group's page. Skipped for attention-scoped and
+  // foreground-only queries too: the caller asked for a subset, and a
+  // pinned row outside it appended to the page would sit there while
+  // `hasMore` is computed from the filtered count. This is the
+  // compatibility shim for clients that still read Pinned out of the
+  // unfiltered list; it goes away once every section fetches its own group.
   if (
     offset === 0 &&
     conversationType === "standard" &&
     archiveStatus === "active" &&
     originChannel === undefined &&
     groupId === undefined &&
-    needsAttention === undefined
+    needsAttention === undefined &&
+    foregroundOnly === undefined
   ) {
     const pinned = listPinnedConversations(archiveStatus);
     const seen = new Set(rows.map((c) => c.id));
@@ -611,6 +618,14 @@ export const ROUTES: RouteDefinition[] = [
           'Pass "true" to return only conversations whose latest assistant message the user has not seen: the same predicate behind the unread count and the section index, so a client that keeps no complete conversation list can ask for exactly the rows its attention surfaces need. Composes with every other filter. Any value other than "true" is rejected. Omit to span every conversation.',
         schema: { type: "string", enum: ["true"] },
       },
+      {
+        name: "foregroundOnly",
+        type: "string",
+        required: false,
+        description:
+          'Pass "true" to return only user-facing foreground conversations, dropping the automated background and scheduled runs the standard listing admits when they are filed in a custom group (a surfaced run stays). This is the same predicate the unread count and the section index apply, so a client can ask for the newest conversation a user can open in one row instead of paging past runs it would skip. Composes with every other filter; a foreground-only first page never has pinned rows appended to it. Any value other than "true" is rejected. Omit to keep every visible row.',
+        schema: { type: "string", enum: ["true"] },
+      },
     ],
     responseBody: listConversationsResponseSchema,
     handler: handleListConversations,