@vellumai/assistant 0.8.6 → 0.8.7-dev.202606052118.34cd356

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

@@ -39,6 +39,9 @@ import {
   AssistantEventHub,
   assistantEventHub,
 } from "../assistant-event-hub.js";
+import type { ReplaySubscriber } from "../assistant-stream-state.js";
+import { getReplayWindow } from "../assistant-stream-state.js";
+import { ACTOR_PRINCIPALS, GATEWAY_PRINCIPALS } from "../auth/route-policy.js";
 import { resolveActorPrincipalIdForLocalGuardian } from "../local-actor-identity.js";
 import {
   BadRequestError,
@@ -140,6 +143,12 @@ export interface SseSubscriberInstrumentation {
   clientId: string | null;
   interfaceId: string | null;
   conversationKey: string | null;
+  /**
+   * Per-connection id assigned by the hub. Distinguishes connections
+   * sharing a `clientId` (old vs reconnected) so a shed can be attributed
+   * to a specific connection. `null` until the hub subscription is created.
+   */
+  connectionId: string | null;
 }
 
 export type SseShedReason = "callback_backpressure" | "heartbeat_backpressure";
@@ -174,6 +183,7 @@ export function buildSseShedSentryContext(
     heartbeats_sent: inst.heartbeatsSent,
     client_id: inst.clientId,
     interface_id: inst.interfaceId,
+    connection_id: inst.connectionId,
     event_loop_delay_mean_ms: elDelay.mean_ms,
     event_loop_delay_p99_ms: elDelay.p99_ms,
     event_loop_delay_max_ms: elDelay.max_ms,
@@ -213,6 +223,7 @@ const defaultSseShedReporter: SseShedReporter = (reason, inst) => {
       scope.setTag("sse_shed_reason", reason);
       if (inst.clientId) scope.setTag("client_id", inst.clientId);
       if (inst.interfaceId) scope.setTag("interface_id", inst.interfaceId);
+      if (inst.connectionId) scope.setTag("connection_id", inst.connectionId);
       scope.setContext("sse_shed", sentryContext);
       Sentry.captureMessage(`sse_subscriber_shed:${reason}`);
     });
@@ -263,19 +274,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"];
@@ -355,6 +379,7 @@ export function handleSubscribeAssistantEvents(
     clientId,
     interfaceId,
     conversationKey: scopeConversationKey,
+    connectionId: null,
   };
 
   ensureEventLoopDelayMonitorStarted();
@@ -371,9 +396,24 @@ 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;
+
   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);
@@ -413,6 +453,9 @@ export function handleSubscribeAssistantEvents(
             ...subscriberBase,
             type: "process" as const,
           });
+    // Stamp the hub-assigned connection id so a later backpressure shed can be
+    // tied back to this specific connection in logs and Sentry.
+    instrumentation.connectionId = sub.connectionId;
   } catch (err) {
     if (err instanceof RangeError) {
       throw new ServiceUnavailableError("Too many concurrent connections");
@@ -431,6 +474,49 @@ export function handleSubscribeAssistantEvents(
           return;
         }
 
+        // Reconnect replay: when the caller passed lastSeenSeq, deliver
+        // any buffered events the client missed before the first
+        // heartbeat. `seq` is a single global per-assistant counter, so
+        // one cursor resumes the stream regardless of how many
+        // conversations are multiplexed on an unfiltered connection.
+        // Replay re-applies the subscriber's targeting filter; a
+        // conversation-scoped subscription additionally scopes replay to
+        // its own conversation (other conversations are never delivered
+        // live on that connection, so replaying them would be wrong).
+        //
+        // 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) {
+          const replaySubscriber: ReplaySubscriber =
+            clientId && interfaceId
+              ? {
+                  type: "client",
+                  clientId,
+                  interfaceId,
+                  capabilities: ALL_CAPABILITIES.filter((cap) =>
+                    supportsHostProxy(interfaceId, cap),
+                  ),
+                }
+              : { type: "process" };
+          const window = getReplayWindow(
+            lastSeenSeq,
+            replaySubscriber,
+            filter.conversationId,
+          );
+          if (window !== null) {
+            for (const replayed of window) {
+              controller.enqueue(encoder.encode(formatSseFrame(replayed)));
+              instrumentation.eventsDelivered += 1;
+              if (replayed.seq != null && replayed.seq > highWaterReplaySeq) {
+                highWaterReplaySeq = replayed.seq;
+              }
+            }
+          }
+        }
+
         controller.enqueue(encoder.encode(formatSseHeartbeat()));
         instrumentation.heartbeatsSent += 1;
 
@@ -486,6 +572,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 +594,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 +612,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 global event seq the client has already applied. `seq` is a single per-assistant counter shared across all conversations, so one cursor resumes the stream regardless of how many conversations are multiplexed on the connection. When set, the daemon replays any buffered events with seq > lastSeenSeq (re-applying the subscriber's targeting/scope filter) 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 ───────────────────────────────────────────────────────
@@ -34,7 +35,14 @@ async function gatewayFetch(
 
 // ── Schemas ─────────────────────────────────────────────────────────────
 
-const LEVEL_NAMES = ["trace", "debug", "info", "warn", "error", "fatal"] as const;
+const LEVEL_NAMES = [
+  "trace",
+  "debug",
+  "info",
+  "warn",
+  "error",
+  "fatal",
+] as const;
 
 const GatewayLogsTailParams = z
   .object({
@@ -44,9 +52,18 @@ const GatewayLogsTailParams = z
   })
   .strict();
 
+const GatewayLogsTailResponseSchema = z.object({
+  lines: z.array(z.record(z.string(), z.unknown())),
+  truncated: z.boolean(),
+});
+type GatewayLogsTailResponse = z.infer<typeof GatewayLogsTailResponseSchema>;
+
 // ── Handlers ────────────────────────────────────────────────────────────
 
-async function handleGatewayLogsTail({ queryParams = {}, body = {} }: RouteHandlerArgs) {
+async function handleGatewayLogsTail({
+  queryParams = {},
+  body = {},
+}: RouteHandlerArgs): Promise<GatewayLogsTailResponse> {
   // HTTP GET delivers filters via queryParams; CLI IPC puts them in body.
   const source = Object.keys(queryParams).length > 0 ? queryParams : body;
   const p = GatewayLogsTailParams.parse(source);
@@ -55,7 +72,9 @@ async function handleGatewayLogsTail({ queryParams = {}, body = {} }: RouteHandl
   if (p.level !== undefined) qs.set("level", p.level);
   if (p.module !== undefined) qs.set("module", p.module);
   const query = qs.toString();
-  return gatewayFetch(`/v1/logs/tail${query ? `?${query}` : ""}`);
+  return gatewayFetch(
+    `/v1/logs/tail${query ? `?${query}` : ""}`,
+  ) as Promise<GatewayLogsTailResponse>;
 }
 
 // ── Route definitions ───────────────────────────────────────────────────
@@ -64,14 +83,22 @@ 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",
     description:
       "Return the last N structured log entries from the gateway log files.",
     tags: ["gateway-logs"],
+    responseBody: GatewayLogsTailResponseSchema,
     queryParams: [
-      { name: "n", description: "Number of lines to return (1–1000, default: 10)" },
+      {
+        name: "n",
+        description: "Number of lines to return (1–1000, default: 10)",
+      },
       { name: "level", description: "Minimum pino level name (default: info)" },
       { name: "module", description: "Filter to exact pino module name" },
     ],

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) {