@vellumai/assistant 0.8.6 → 0.8.7

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

@@ -39,6 +39,9 @@ import {
   AssistantEventHub,
   assistantEventHub,
 } from "../assistant-event-hub.js";
+import { ACTOR_PRINCIPALS, GATEWAY_PRINCIPALS } from "../auth/route-policy.js";
+import type { ReplaySubscriber } from "../conversation-stream-state.js";
+import { getReplayWindow } from "../conversation-stream-state.js";
 import { resolveActorPrincipalIdForLocalGuardian } from "../local-actor-identity.js";
 import {
   BadRequestError,
@@ -263,19 +266,32 @@ export function handleSubscribeAssistantEvents(
 
   const rawConversationId = queryParams?.conversationId;
   const rawConversationKey = queryParams?.conversationKey;
-  if (
-    "conversationId" in (queryParams ?? {}) &&
-    !rawConversationId?.trim()
-  ) {
+  const rawLastSeenSeq = queryParams?.lastSeenSeq;
+  if ("conversationId" in (queryParams ?? {}) && !rawConversationId?.trim()) {
     throw new BadRequestError("conversationId must not be empty");
   }
-  if (
-    "conversationKey" in (queryParams ?? {}) &&
-    !rawConversationKey?.trim()
-  ) {
+  if ("conversationKey" in (queryParams ?? {}) && !rawConversationKey?.trim()) {
     throw new BadRequestError("conversationKey must not be empty");
   }
 
+  // Parse the optional reconnect cursor. We accept any non-negative integer
+  // -- including 0, which is the natural cursor for a client that has not
+  // yet observed any event in this conversation but still wants its full
+  // ring buffer replayed (as opposed to omitting the param entirely, which
+  // means "no replay attempt, just connect live").
+  let lastSeenSeq: number | null = null;
+  if (rawLastSeenSeq != null) {
+    const trimmed = rawLastSeenSeq.trim();
+    if (trimmed === "") {
+      throw new BadRequestError("lastSeenSeq must not be empty");
+    }
+    const parsed = Number(trimmed);
+    if (!Number.isInteger(parsed) || parsed < 0) {
+      throw new BadRequestError("lastSeenSeq must be a non-negative integer");
+    }
+    lastSeenSeq = parsed;
+  }
+
   // ── Client identity from headers ──────────────────────────────────────
   const rawClientId = headers?.["x-vellum-client-id"];
   const rawInterfaceId = headers?.["x-vellum-interface-id"];
@@ -371,9 +387,37 @@ export function handleSubscribeAssistantEvents(
     }
   }
 
+  // Tracks the highest seq enqueued during the synchronous replay drain.
+  // Live events that race in with seq <= this watermark are dropped to
+  // avoid double-delivery -- broadcastMessage stamps and rings BEFORE
+  // calling publish, so any in-flight event mid-replay is already in the
+  // replay window we just drained.
+  let highWaterReplaySeq = -1;
+
+  // Per-conversation subscriber-filtered sequence counters. Incremented
+  // for each conversation-scoped event this specific subscriber receives
+  // (after capability/client/interface targeting), producing a gap-free
+  // sequence from the subscriber's perspective. Clients use `clientSeq`
+  // for gap detection instead of the global `seq` to avoid false
+  // positives from targeted events they never receive.
+  const clientSeqCounters = new Map<string, number>();
+  function nextClientSeqFor(conversationId: string): number {
+    const next = (clientSeqCounters.get(conversationId) ?? 0) + 1;
+    clientSeqCounters.set(conversationId, next);
+    return next;
+  }
+
   const callback: AssistantEventCallback = (event) => {
     const controller = controllerRef;
     if (!controller) return;
+    if (
+      event.seq != null &&
+      highWaterReplaySeq >= 0 &&
+      event.seq <= highWaterReplaySeq
+    ) {
+      // Already delivered via replay; skip the duplicate.
+      return;
+    }
     try {
       if (controller.desiredSize != null && controller.desiredSize <= 0) {
         shedReporter("callback_backpressure", instrumentation);
@@ -381,7 +425,11 @@ export function handleSubscribeAssistantEvents(
         cleanup();
         return;
       }
-      controller.enqueue(encoder.encode(formatSseFrame(event)));
+      const frame =
+        event.conversationId != null && event.seq != null
+          ? { ...event, clientSeq: nextClientSeqFor(event.conversationId) }
+          : event;
+      controller.enqueue(encoder.encode(formatSseFrame(frame)));
       instrumentation.eventsDelivered += 1;
     } catch {
       sub.dispose();
@@ -431,6 +479,50 @@ export function handleSubscribeAssistantEvents(
           return;
         }
 
+        // Reconnect replay: when the caller passed lastSeenSeq and the
+        // subscription is scoped to a single conversation, deliver any
+        // buffered events the client missed before the first heartbeat.
+        //
+        // If the cursor is older than the ring's oldest entry,
+        // `getReplayWindow` returns `null`. We do not surface that to
+        // the client over the wire -- the connection just goes live.
+        // The client detects the gap from the seq jump on its first
+        // live event and refetches via the existing messages API.
+        if (lastSeenSeq != null && filter.conversationId) {
+          const replaySubscriber: ReplaySubscriber =
+            clientId && interfaceId
+              ? {
+                  type: "client",
+                  clientId,
+                  interfaceId,
+                  capabilities: ALL_CAPABILITIES.filter((cap) =>
+                    supportsHostProxy(interfaceId, cap),
+                  ),
+                }
+              : { type: "process" };
+          const window = getReplayWindow(
+            filter.conversationId,
+            lastSeenSeq,
+            replaySubscriber,
+          );
+          if (window !== null) {
+            for (const replayed of window) {
+              const frame =
+                replayed.conversationId != null && replayed.seq != null
+                  ? {
+                      ...replayed,
+                      clientSeq: nextClientSeqFor(replayed.conversationId),
+                    }
+                  : replayed;
+              controller.enqueue(encoder.encode(formatSseFrame(frame)));
+              instrumentation.eventsDelivered += 1;
+              if (replayed.seq != null && replayed.seq > highWaterReplaySeq) {
+                highWaterReplaySeq = replayed.seq;
+              }
+            }
+          }
+        }
+
         controller.enqueue(encoder.encode(formatSseHeartbeat()));
         instrumentation.heartbeatsSent += 1;
 
@@ -486,6 +578,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "emit_event",
     endpoint: "events/emit",
     method: "POST",
+    policy: {
+      requiredScopes: ["internal.write"],
+      allowedPrincipalTypes: GATEWAY_PRINCIPALS,
+    },
     summary: "Emit an assistant event",
     description:
       "Trigger an in-process assistant event by kind. Used by the gateway after owning a write that the assistant runtime would normally emit.",
@@ -504,6 +600,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "subscribe_assistant_events",
     endpoint: "events",
     method: "GET",
+    policy: {
+      requiredScopes: ["chat.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Subscribe to assistant events",
     description: "Stream assistant events as Server-Sent Events (SSE).",
     tags: ["events"],
@@ -518,6 +618,11 @@ export const ROUTES: RouteDefinition[] = [
         description:
           "Scope to a single conversation by an external key (non-vellum channels) or the web idempotency key. Materializes a row on first use. Ignored when conversationId is also provided.",
       },
+      {
+        name: "lastSeenSeq",
+        description:
+          "Optional reconnect cursor: the highest per-conversation event seq the client has already applied. When set together with a conversation scope, the daemon replays any buffered events with seq > lastSeenSeq before going live. If the cursor is older than the ring buffer's oldest entry the connection simply goes live; the client is expected to detect the gap from the next event's seq and refetch via the messages API. Must be a non-negative integer.",
+      },
     ],
     responseHeaders: {
       "Content-Type": "text/event-stream",

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

@@ -12,6 +12,7 @@ import { z } from "zod";
 import { getConfig } from "../../config/loader.js";
 import { FilingService } from "../../filing/filing-service.js";
 import { getLogger } from "../../util/logger.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import { BadRequestError, InternalError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
@@ -30,8 +31,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "getFilingConfig",
     endpoint: "filing/config",
     method: "GET",
-    policyKey: "filing",
-    requirePolicyEnforcement: true,
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Get filing config",
     description: "Return the current filing schedule configuration.",
     tags: ["filing"],
@@ -64,8 +67,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "runFilingNow",
     endpoint: "filing/run-now",
     method: "POST",
-    policyKey: "filing",
-    requirePolicyEnforcement: true,
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Run filing now",
     description: "Trigger an immediate filing run.",
     tags: ["filing"],

package/src/runtime/routes/gateway-log-routes.ts

@@ -7,6 +7,7 @@
 import { z } from "zod";
 
 import { getGatewayInternalBaseUrl } from "../../config/env.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 // ── Shared helper ───────────────────────────────────────────────────────
@@ -64,6 +65,10 @@ export const ROUTES: RouteDefinition[] = [
   {
     operationId: "gateway_logs_tail",
     method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     endpoint: "gateway/logs/tail",
     handler: handleGatewayLogsTail,
     summary: "Tail gateway log entries",

package/src/runtime/routes/global-search-routes.ts

@@ -21,6 +21,7 @@ import { rawAll } from "../../memory/raw-query.js";
 import { semanticSearch } from "../../memory/search/semantic.js";
 import { listSchedules } from "../../schedule/schedule-store.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";
 
@@ -30,49 +31,53 @@ const log = getLogger("global-search");
 // Types
 // ---------------------------------------------------------------------------
 
-interface GlobalSearchConversation {
-  id: string;
-  title: string | null;
-  updatedAt: number;
-  excerpt: string;
-  matchCount: number;
-}
-
-interface GlobalSearchMemory {
-  id: string;
-  kind: string;
-  text: string;
-  subject: string | null;
-  confidence: number;
-  updatedAt: number;
-  source: "lexical" | "semantic";
-}
-
-interface GlobalSearchSchedule {
-  id: string;
-  name: string;
-  expression: string | null;
-  message: string;
-  enabled: boolean;
-  nextRunAt: number | null;
-}
-
-interface GlobalSearchContact {
-  id: string;
-  displayName: string;
-  notes: string | null;
-  lastInteraction: number | null;
-}
-
-export interface GlobalSearchResponse {
-  query: string;
-  results: {
-    conversations: GlobalSearchConversation[];
-    memories: GlobalSearchMemory[];
-    schedules: GlobalSearchSchedule[];
-    contacts: GlobalSearchContact[];
-  };
-}
+const globalSearchConversationSchema = z.object({
+  id: z.string(),
+  title: z.string().nullable(),
+  updatedAt: z.number(),
+  excerpt: z.string(),
+  matchCount: z.number().int(),
+});
+
+const globalSearchMemorySchema = z.object({
+  id: z.string(),
+  kind: z.string(),
+  text: z.string(),
+  subject: z.string().nullable(),
+  confidence: z.number(),
+  updatedAt: z.number(),
+  source: z.enum(["lexical", "semantic"]),
+});
+
+const globalSearchScheduleSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  expression: z.string().nullable(),
+  message: z.string(),
+  enabled: z.boolean(),
+  nextRunAt: z.number().nullable(),
+});
+
+const globalSearchContactSchema = z.object({
+  id: z.string(),
+  displayName: z.string(),
+  notes: z.string().nullable(),
+  lastInteraction: z.number().nullable(),
+});
+
+const globalSearchResponseSchema = z.object({
+  query: z.string(),
+  results: z.object({
+    conversations: z.array(globalSearchConversationSchema),
+    memories: z.array(globalSearchMemorySchema),
+    schedules: z.array(globalSearchScheduleSchema),
+    contacts: z.array(globalSearchContactSchema),
+  }),
+});
+
+type GlobalSearchMemory = z.infer<typeof globalSearchMemorySchema>;
+type GlobalSearchSchedule = z.infer<typeof globalSearchScheduleSchema>;
+export type GlobalSearchResponse = z.infer<typeof globalSearchResponseSchema>;
 
 // ---------------------------------------------------------------------------
 // Category search helpers
@@ -274,6 +279,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "search_global",
     endpoint: "search/global",
     method: "GET",
+    policy: {
+      requiredScopes: ["chat.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleGlobalSearch,
     summary: "Global search",
     description:
@@ -299,12 +308,6 @@ export const ROUTES: RouteDefinition[] = [
         description: "Enable semantic search for memories (true/false)",
       },
     ],
-    responseBody: z.object({
-      query: z.string(),
-      results: z
-        .object({})
-        .passthrough()
-        .describe("Results grouped by category"),
-    }),
+    responseBody: globalSearchResponseSchema,
   },
 ];

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

@@ -18,6 +18,7 @@ import {
   reorderGroups,
   updateGroup,
 } from "../../memory/group-crud.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import { publishConversationListChanged } from "../sync/resource-sync-events.js";
 import { BadRequestError, ForbiddenError, NotFoundError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
@@ -171,7 +172,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "groups_list",
     endpoint: "groups",
     method: "GET",
-    policyKey: "groups",
+    policy: {
+      requiredScopes: ["chat.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleListGroups,
     summary: "List groups",
     description: "Return all conversation groups.",
@@ -182,7 +186,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "groups_create",
     endpoint: "groups",
     method: "POST",
-    policyKey: "groups",
+    policy: {
+      requiredScopes: ["chat.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleCreateGroup,
     responseStatus: "201",
     summary: "Create group",
@@ -204,7 +211,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "groups_update",
     endpoint: "groups/:groupId",
     method: "PATCH",
-    policyKey: "groups",
+    policy: {
+      requiredScopes: ["chat.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleUpdateGroup,
     summary: "Update group",
     description: "Update a conversation group's name or sort position.",
@@ -227,7 +237,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "groups_delete",
     endpoint: "groups/:groupId",
     method: "DELETE",
-    policyKey: "groups",
+    policy: {
+      requiredScopes: ["chat.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleDeleteGroup,
     responseStatus: "204",
     summary: "Delete group",
@@ -246,7 +259,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "groups_reorder",
     endpoint: "groups/reorder",
     method: "POST",
-    policyKey: "groups/reorder",
+    policy: {
+      requiredScopes: ["chat.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleReorderGroups,
     summary: "Reorder groups",
     description: "Batch-update sort positions for conversation groups.",

package/src/runtime/routes/guardian-action-routes.ts

@@ -19,6 +19,7 @@ import {
   type CanonicalGuardianRequest,
   listPendingRequestsByConversationScope,
 } from "../../memory/canonical-guardian-store.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import { processGuardianDecision } from "../guardian-action-service.js";
 import type { GuardianDecisionPrompt } from "../guardian-decision-types.js";
 import { buildOneTimeDecisionActions } from "../guardian-decision-types.js";
@@ -226,6 +227,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "guardian_actions_pending",
     endpoint: "guardian-actions/pending",
     method: "GET",
+    policy: {
+      requiredScopes: ["approval.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "List pending guardian actions",
     description: "Return pending guardian decision prompts for a conversation.",
     tags: ["guardian"],
@@ -248,6 +253,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "guardian_actions_decision",
     endpoint: "guardian-actions/decision",
     method: "POST",
+    policy: {
+      requiredScopes: ["approval.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     requireGuardian: true,
     summary: "Submit guardian decision",
     description: "Submit a guardian action decision (approve/reject).",

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

@@ -494,37 +494,6 @@ export async function handleApprovalInterception(
     }
   }
 
-  // ── Slack reaction path ──
-  // Reactions produce `callbackData` of the form `reaction:<emoji_name>`.
-  // Only guardians can approve via reaction — non-guardian reactions are
-  // silently ignored to prevent self-approval. `reaction_removed:` never
-  // expresses an approval intent.
-  if (
-    callbackData?.startsWith("reaction:") &&
-    !callbackData.startsWith("reaction_removed:")
-  ) {
-    if (trustCtx.trustClass !== "guardian") {
-      return { handled: true, type: "stale_ignored" };
-    }
-    const reactionDecision = parseReactionCallbackData(callbackData);
-    if (!reactionDecision) {
-      // Unknown emoji — ignore silently
-      return { handled: true, type: "stale_ignored" };
-    }
-    const pending = getApprovalInfoByConversation(conversationId);
-    if (pending.length === 0) {
-      return { handled: true, type: "stale_ignored" };
-    }
-    const result = await handleChannelDecision(
-      conversationId,
-      reactionDecision,
-    );
-    if (result.applied) {
-      return { handled: true, type: "decision_applied" };
-    }
-    return { handled: true, type: "stale_ignored" };
-  }
-
   // Try to extract a decision from callback data (button press) first.
   // Callback/button path remains deterministic and takes priority.
   if (callbackData) {

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

@@ -21,6 +21,7 @@ import { HeartbeatService } from "../../heartbeat/heartbeat-service.js";
 import { readTextFileSync } from "../../util/fs.js";
 import { getLogger } from "../../util/logger.js";
 import { getWorkspacePromptPath } from "../../util/platform.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import { BadRequestError, InternalError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
@@ -88,7 +89,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "listHeartbeatRuns",
     endpoint: "heartbeat/runs",
     method: "GET",
-    policyKey: "heartbeat",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "List heartbeat runs",
     description: "Return recent heartbeat conversation runs.",
     tags: ["heartbeat"],
@@ -124,7 +128,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "getHeartbeatChecklist",
     endpoint: "heartbeat/checklist",
     method: "GET",
-    policyKey: "heartbeat",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Get heartbeat checklist",
     description: "Return the HEARTBEAT.md checklist content.",
     tags: ["heartbeat"],
@@ -138,7 +145,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "writeHeartbeatChecklist",
     endpoint: "heartbeat/checklist",
     method: "PUT",
-    policyKey: "heartbeat",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Write heartbeat checklist",
     description: "Overwrite the HEARTBEAT.md checklist content.",
     tags: ["heartbeat"],
@@ -154,8 +164,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "getHeartbeatConfig",
     endpoint: "heartbeat/config",
     method: "GET",
-    policyKey: "heartbeat",
-    requirePolicyEnforcement: true,
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Get heartbeat config",
     description: "Return the current heartbeat schedule configuration.",
     tags: ["heartbeat"],
@@ -190,8 +202,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "updateHeartbeatConfig",
     endpoint: "heartbeat/config",
     method: "PUT",
-    policyKey: "heartbeat",
-    requirePolicyEnforcement: true,
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Update heartbeat config",
     description: "Update the heartbeat schedule configuration.",
     tags: ["heartbeat"],
@@ -295,8 +309,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "runHeartbeatNow",
     endpoint: "heartbeat/run-now",
     method: "POST",
-    policyKey: "heartbeat",
-    requirePolicyEnforcement: true,
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Run heartbeat now",
     description: "Trigger an immediate heartbeat run.",
     tags: ["heartbeat"],