@vellumai/assistant 0.11.2 → 0.11.3-staging.2

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

@@ -35,8 +35,6 @@ import { DAEMON_INTERNAL_ASSISTANT_ID } from "../assistant-scope.js";
 import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import {
   cancelOutbound,
-  deliverVerificationEmail,
-  deliverVerificationSlack,
   normalizeTelegramDestination,
   resendOutbound,
   startOutbound,
@@ -152,16 +150,6 @@ export async function handleCreateVerificationSession({
       verificationRateLimiter.recordFailure(rateLimitKey);
     }
 
-    // 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") {
         throw new TooManyRequestsError(
@@ -174,9 +162,7 @@ export async function handleCreateVerificationSession({
       );
     }
 
-    // Strip internal fields from the response
-    const { _pendingSlackDm: _, _pendingEmail: __, ...publicResult } = result;
-    return publicResult;
+    return result;
   }
 
   // Inbound challenge path
@@ -222,16 +208,6 @@ export async function handleResendVerificationSession({
 
   const result = await resendOutbound({ channel, originConversationId });
 
-  // 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") {
       throw new TooManyRequestsError(
@@ -243,8 +219,7 @@ export async function handleResendVerificationSession({
     );
   }
 
-  const { _pendingSlackDm: _, _pendingEmail: __, ...publicResult } = result;
-  return publicResult;
+  return result;
 }
 
 /**

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

@@ -159,8 +159,13 @@ async function handleExchange(args: RouteHandlerArgs) {
 
   const existing = getConnection(db, CONNECTION_NAME);
   if (existing) {
+    // Stamp the provider with the auth: this row is the subscription
+    // connection by name, and dispatch derives auth from the provider for
+    // managed rows, so a claiming row with e.g. provider "vellum" would
+    // otherwise strand the fresh token behind derived platform auth.
     const updateResult = updateConnection(db, CONNECTION_NAME, {
       auth: authInput,
+      provider: "openai",
     });
     if (!updateResult.ok) {
       log.error(

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

@@ -10,15 +10,33 @@ import { z } from "zod";
 import type { HostProxyCapability } from "../../channels/types.js";
 import { isHttpAuthDisabled } from "../../config/env.js";
 import { datesToISO } from "../../util/json.js";
-import { assistantEventHub } from "../assistant-event-hub.js";
+import { getLogger } from "../../util/logger.js";
+import {
+  assistantEventHub,
+  DESKTOP_PRESENCE_STATES,
+} from "../assistant-event-hub.js";
 import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import {
   DEFAULT_HEARTBEAT_INTERVAL_MS,
   isClientDegraded,
 } from "../client-health.js";
-import { NotFoundError } from "./errors.js";
+import { BadRequestError, NotFoundError } from "./errors.js";
+import { parseBody } from "./parse-body.js";
 import type { RouteDefinition } from "./types.js";
 
+const log = getLogger("client-routes");
+
+/**
+ * Body of `POST /v1/clients/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 PresenceBodySchema = z.object({
+  state: z
+    .enum(DESKTOP_PRESENCE_STATES)
+    .describe("Reported desktop presence state."),
+});
+
 export const ROUTES: RouteDefinition[] = [
   {
     operationId: "list_clients",
@@ -116,4 +134,98 @@ export const ROUTES: RouteDefinition[] = [
       return { disconnected: count };
     },
   },
+  {
+    operationId: "report_client_presence",
+    endpoint: "clients/presence",
+    method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "Report desktop presence",
+    description:
+      "Record the desktop presence state reported by the client identified by the X-Vellum-Client-Id header.",
+    tags: ["clients"],
+    requestBody: PresenceBodySchema,
+    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 { state } = parseBody(PresenceBodySchema, 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 every
+        // 30 seconds for a benign race. Not a 404 either, for the same reason.
+        log.debug(
+          { op: "report_client_presence", state },
+          "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 desktop. Clients with no stored `actorPrincipalId` (legacy
+      // SSE subscribers, service-gateway tokens) never match: fail-closed, the
+      // same posture as the listing filter above. 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_client_presence",
+              hasStoredOwner: ownerPrincipalId !== undefined,
+              hasCallerPrincipal: callerPrincipalId !== undefined,
+              targetInterfaceId: client.interfaceId,
+            },
+            "Rejecting 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.setClientPresence(clientId, state);
+
+      // Records which state a client actually reported. Nothing else persists
+      // it, so this is the only evidence for why a machine did or did not
+      // count as attended. Only `macos` clients gate pushes, hence the
+      // interface id.
+      log.debug(
+        {
+          op: "report_client_presence",
+          state,
+          interfaceId: client.interfaceId,
+        },
+        "Recorded desktop presence",
+      );
+      return { recorded: true };
+    },
+  },
 ];

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

@@ -44,12 +44,11 @@ function handleListCli({ body = {} }: RouteHandlerArgs) {
   // user sees archived rows alongside live ones in the picker.
   const includeArchived = (body.includeArchived as boolean) ?? false;
 
-  const rows = listConversations(
+  const rows = listConversations({
     limit,
-    "standard",
-    0,
-    includeArchived ? "all" : "active",
-  );
+    conversationType: "standard",
+    archiveStatus: includeArchived ? "all" : "active",
+  });
   return {
     conversations: rows.map((c) => ({
       id: c.id,
@@ -140,7 +139,7 @@ function handleExportCli({ body = {} }: RouteHandlerArgs) {
   let conversationId = body.conversationId as string | undefined;
 
   if (!conversationId) {
-    const all = listConversations(1);
+    const all = listConversations({ limit: 1 });
     if (all.length === 0) {
       throw new NotFoundError("No conversations found");
     }
@@ -151,12 +150,11 @@ function handleExportCli({ body = {} }: RouteHandlerArgs) {
   // behavior of letting `vellum export <prefix>` resolve an archived row.
   let conversation = getConversation(conversationId);
   if (!conversation) {
-    const all = listConversations(
-      Number.MAX_SAFE_INTEGER,
-      "standard",
-      0,
-      "all",
-    );
+    const all = listConversations({
+      limit: Number.MAX_SAFE_INTEGER,
+      conversationType: "standard",
+      archiveStatus: "all",
+    });
     const match = all.find((c) => c.id.startsWith(conversationId!));
     if (match) {
       conversation = match;

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

@@ -2,6 +2,7 @@
  * Route handlers for conversation listing, detail, and seen/unread state.
  *
  * GET    /v1/conversations              — paginated conversation list
+ * GET    /v1/conversations/unread-count - count of unseen foreground conversations
  * POST   /v1/conversations/seen         — record a seen signal (single)
  * POST   /v1/conversations/seen/bulk    — record seen signals (batch)
  * POST   /v1/conversations/unread       — mark a conversation unread
@@ -26,7 +27,9 @@ import {
 } from "../../persistence/conversation-crud.js";
 import { resolveConversationId } from "../../persistence/conversation-key-store.js";
 import {
+  type ConversationListFilter,
   countConversations,
+  countUnreadConversations,
   listConversations,
   listPinnedConversations,
 } from "../../persistence/conversation-queries.js";
@@ -101,6 +104,13 @@ export const conversationSummarySchema = z.object({
   displayOrder: z.number().nullable().optional(),
   groupId: z.string().nullable(),
   forkParent: forkParentSchema.optional(),
+  /**
+   * Present only on a referential fork whose parent conversation was deleted.
+   * The fork keeps the messages it owns and the lineage read truncates at the
+   * missing parent, so it renders as a conversation that starts mid-thought.
+   * Clients surface this so that reads as a deletion rather than as data loss.
+   */
+  historyOrphaned: z.literal(true).optional(),
   archivedAt: z.number().optional(),
   /**
    * Epoch-ms timestamp set when a background/scheduled conversation was
@@ -141,6 +151,10 @@ const conversationDetailResponseSchema = z.object({
   conversation: conversationSummarySchema,
 });
 
+const unreadConversationCountResponseSchema = z.object({
+  count: z.number(),
+});
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -194,18 +208,19 @@ function handleListConversations({ queryParams = {} }: RouteHandlerArgs) {
       ? queryParams.originChannel
       : undefined;
 
-  let rows = listConversations(
-    limit,
-    conversationType,
-    offset,
-    archiveStatus,
-    originChannel,
-  );
-  const totalCount = countConversations(
+  const groupId =
+    queryParams.groupId !== undefined && queryParams.groupId !== ""
+      ? queryParams.groupId
+      : undefined;
+
+  const filter: ConversationListFilter = {
     conversationType,
     archiveStatus,
     originChannel,
-  );
+    groupId,
+  };
+  let rows = listConversations({ ...filter, limit, offset });
+  const totalCount = countConversations(filter);
 
   // On the first page, ensure all pinned conversations are included
   // even if they fall outside the paginated window. Pinned injection is
@@ -213,11 +228,19 @@ function handleListConversations({ queryParams = {} }: RouteHandlerArgs) {
   // rows in archive-time order, not pin order. Also skipped for
   // channel-scoped queries — those return only items matching the
   // requested origin channel; pinned items render in their own section.
+  //
+  // 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. 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
+    originChannel === undefined &&
+    groupId === undefined
   ) {
     const pinned = listPinnedConversations(archiveStatus);
     const seen = new Set(rows.map((c) => c.id));
@@ -265,6 +288,10 @@ function handleListConversations({ queryParams = {} }: RouteHandlerArgs) {
   return response;
 }
 
+function handleGetUnreadConversationCount() {
+  return { count: countUnreadConversations() };
+}
+
 function handleRecordSeen({ body = {}, headers }: RouteHandlerArgs) {
   const rawConversationId = body.conversationId as string | undefined;
   if (!rawConversationId) {
@@ -450,10 +477,32 @@ export const ROUTES: RouteDefinition[] = [
           enum: [...CHANNEL_IDS],
         },
       },
+      {
+        name: "groupId",
+        type: "string",
+        required: false,
+        description:
+          'Filter to a single group, so each sidebar section can load independently of the paginated list. Pass "system:all" for conversations in no group, "system:pinned" for the Pinned section, or a custom group id. A group-scoped request is ordered by the user\'s arrangement (display order, then recency) and never has pinned rows appended to it. Omit to span every group.',
+      },
     ],
     responseBody: listConversationsResponseSchema,
     handler: handleListConversations,
   },
+  {
+    operationId: "getUnreadConversationCount",
+    endpoint: "conversations/unread-count",
+    method: "GET",
+    policy: {
+      requiredScopes: ["chat.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "Unread conversation count",
+    description:
+      "Count of foreground conversations whose latest assistant message is unseen. Matches the sidebar's unread indicators: archived rows and non-surfaced background/scheduled rows are excluded.",
+    tags: ["conversations"],
+    responseBody: unreadConversationCountResponseSchema,
+    handler: handleGetUnreadConversationCount,
+  },
   {
     operationId: "recordConversationSeen",
     endpoint: "conversations/seen",

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

@@ -46,7 +46,7 @@ import { normalizeConversationType } from "../../daemon/message-types/shared.js"
 import { stripConversationIds } from "../../home/feed-writer.js";
 import {
   archiveConversation,
-  batchSetDisplayOrders,
+  batchSetConversationPlacement,
   countConversationsByScheduleJobId,
   deleteConversation,
   forkConversation as forkConversationInStore,
@@ -63,9 +63,10 @@ import {
   resolveConversationId,
   setConversationKeyIfAbsent,
 } from "../../persistence/conversation-key-store.js";
+import type { NonScheduledConversationType } from "../../persistence/conversation-types.js";
 import { enqueueMemoryJob } from "../../persistence/jobs-store.js";
 import { linkRequestLogsToMessage } from "../../persistence/llm-request-log-store.js";
-import { deleteSchedule } from "../../schedule/schedule-store.js";
+import { deleteSchedule, getSchedule } from "../../schedule/schedule-store.js";
 import { UserError } from "../../util/errors.js";
 import { safeParseRecord } from "../../util/json.js";
 import { getLogger } from "../../util/logger.js";
@@ -100,6 +101,12 @@ const log = getLogger("conversation-management-routes");
 // Helpers
 // ---------------------------------------------------------------------------
 
+/** Conversation types this endpoint may mint. */
+const createConversationTypeSchema = z.enum([
+  "standard",
+  "background",
+] as const satisfies readonly NonScheduledConversationType[]);
+
 function resolveOrThrow(rawId: string): string {
   const id = resolveConversationId(rawId);
   if (!id) {
@@ -111,11 +118,17 @@ function resolveOrThrow(rawId: string): string {
 async function cancelScheduleIfLast(conversationId: string): Promise<void> {
   const conv = getConversation(conversationId);
   if (
-    conv?.scheduleJobId &&
-    countConversationsByScheduleJobId(conv.scheduleJobId) <= 1
+    !conv?.scheduleJobId ||
+    countConversationsByScheduleJobId(conv.scheduleJobId) > 1
   ) {
-    await deleteSchedule(conv.scheduleJobId);
+    return;
+  }
+  // A plugin-declared schedule outlives its run conversations: its lifecycle
+  // belongs to the reconciler, and `deleteSchedule` refuses sourced rows.
+  if (getSchedule(conv.scheduleJobId)?.sourceKey != null) {
+    return;
   }
+  await deleteSchedule(conv.scheduleJobId);
 }
 
 // ---------------------------------------------------------------------------
@@ -126,14 +139,26 @@ function handleCreateConversation({ body = {}, headers }: RouteHandlerArgs) {
   const conversationKey =
     (body.conversationKey as string | undefined) ?? crypto.randomUUID();
   // The shared route adapter does not runtime-validate the body against the
-  // Zod requestBody (it's codegen-only), so guard the type before trimming —
-  // a malformed `{ title: 123 }` would otherwise throw on `.trim()` and 500.
+  // Zod requestBody (it's codegen-only), so guard the types here: a malformed
+  // `{ title: 123 }` would otherwise throw on `.trim()` and 500, and an
+  // unsupported conversationType would reach the store unchecked.
+  // `.nullish()`: an explicit JSON `null` is how serializers spell an absent
+  // optional, so it means the same thing as omitting the key.
+  const requestedType = createConversationTypeSchema
+    .nullish()
+    .safeParse(body.conversationType);
+  if (!requestedType.success) {
+    throw new BadRequestError(
+      `conversationType must be one of ${createConversationTypeSchema.options.join(", ")}`,
+    );
+  }
   if (body.title !== undefined && typeof body.title !== "string") {
     throw new BadRequestError("title must be a string");
   }
   const customTitle = body.title?.trim() || undefined;
+  const conversationType = requestedType.data ?? "standard";
   const result = getOrCreateConversation(conversationKey, {
-    conversationType: "standard",
+    conversationType,
   });
   if (result.created) {
     // A caller-supplied title is user-set: persist it with isAutoTitle = 0 so
@@ -151,10 +176,14 @@ function handleCreateConversation({ body = {}, headers }: RouteHandlerArgs) {
       headers?.["x-vellum-client-id"]?.trim() || undefined,
     );
   }
+  // On a conversationKey hit the row already exists, so the type it carries
+  // can differ from the requested one.
+  const storedType = normalizeConversationType(result.conversationType);
   log.info(
     {
       conversationId: result.conversationId,
       conversationKey,
+      conversationType: storedType,
       created: result.created,
     },
     "Created conversation via POST",
@@ -162,7 +191,7 @@ function handleCreateConversation({ body = {}, headers }: RouteHandlerArgs) {
   return {
     id: result.conversationId,
     conversationKey,
-    conversationType: normalizeConversationType(result.conversationType),
+    conversationType: storedType,
     created: result.created,
   };
 }
@@ -816,7 +845,6 @@ function handleReorderConversations({ body = {}, headers }: RouteHandlerArgs) {
   const updates = body.updates as
     | Array<{
         conversationId: string;
-        displayOrder?: number;
         isPinned?: boolean;
         groupId?: string | null;
       }>
@@ -824,10 +852,9 @@ function handleReorderConversations({ body = {}, headers }: RouteHandlerArgs) {
   if (!Array.isArray(updates)) {
     throw new BadRequestError("Missing updates array");
   }
-  batchSetDisplayOrders(
+  batchSetConversationPlacement(
     updates.map((u) => ({
       id: u.conversationId,
-      displayOrder: u.displayOrder ?? null,
       isPinned: u.isPinned,
       groupId: u.groupId,
     })),
@@ -863,10 +890,11 @@ export const ROUTES: RouteDefinition[] = [
         .describe(
           "Optional external key. Echoed back in the response. Non-vellum channels (Telegram, WhatsApp) use this to scope to a logical channel thread; vellum-web clients can omit it and rely on the assistant-minted `id`.",
         ),
-      conversationType: z
-        .literal("standard")
+      conversationType: createConversationTypeSchema
         .optional()
-        .describe("Only standard conversations are created by this endpoint"),
+        .describe(
+          'Conversation type for the new row. "background" keeps it out of the foreground list and the sidebar\'s Recents grouping, used by internal side-channel flows (onboarding research, persona/identity rewrites) that mint a throwaway thread the user should never see. "scheduled" is not accepted here; scheduled rows are owned by the schedule pipeline.',
+        ),
       title: z
         .string()
         .optional()
@@ -1274,14 +1302,15 @@ export const ROUTES: RouteDefinition[] = [
       requiredScopes: ["chat.write"],
       allowedPrincipalTypes: ACTOR_PRINCIPALS,
     },
-    summary: "Reorder conversations",
-    description: "Batch-update display order and pin state for conversations.",
+    summary: "Move conversations between sections",
+    description:
+      "Batch-update which group holds each conversation, and its pin state. " +
+      "Lists are ordered by recency, so this sets placement, not order.",
     tags: ["conversations"],
     requestBody: z.object({
       updates: z.array(
         z.object({
           conversationId: z.string(),
-          displayOrder: z.number().optional(),
           isPinned: z.boolean().optional(),
           groupId: z.string().nullable().optional(),
         }),