@vellumai/assistant 0.8.7 → 0.8.8-dev.202606052332.17fc8ea

package/src/runtime/{conversation-stream-state.ts → assistant-stream-state.ts}

@@ -1,11 +1,19 @@
 /**
- * Conversation Stream State -- per-conversation SSE sequence counter and
- * ring buffer for `Last-Event-ID` replay (B7 Unit 1).
+ * Assistant Stream State -- a single per-assistant (per-daemon-process)
+ * SSE sequence counter and ring buffer for `Last-Event-ID` replay.
  *
  * Every conversation-scoped outbound event picks up a monotonic `seq`
- * number from this module. The same event is also pushed onto a bounded
- * ring buffer so a reconnecting client can request replay of events the
- * daemon emitted while it was disconnected.
+ * from one global counter shared across all conversations, and is pushed
+ * onto one shared ring buffer. A reconnecting client presents the highest
+ * `seq` it has applied; the daemon replays everything newer from the ring
+ * -- re-applying the subscriber's targeting/scope filter -- then goes
+ * live.
+ *
+ * A single global seq space means the reconnect cursor is one number, not
+ * a per-conversation map: on one ordered SSE connection the client has
+ * received a contiguous prefix of the global stream, so "highest seq
+ * applied" is a valid resume point no matter how many conversations are
+ * multiplexed on the connection.
  *
  * Bounds (oldest evicted first; first bound hit wins):
  * - Count: 200 events
@@ -13,9 +21,23 @@
  * - Age: 30 seconds
  *
  * The ring is in-memory and per-daemon-process. After a daemon restart
- * all seqs reset and reconnecting clients fall through to the snapshot
- * path (delivered by B7 Unit 2). The ring is sized generously enough
- * that a typical refresh round-trip (~1-3s) is well within window.
+ * the seq resets and reconnecting clients fall through to the snapshot
+ * path. The ring is sized generously enough that a typical refresh
+ * round-trip (~1-3s) is well within window.
+ *
+ * Persisted-seq map: alongside the live counter and ring, this module
+ * tracks, per conversation, the `seq` of the last event whose content is
+ * durably committed to the message rows (`persistedSeqByConversation`).
+ * The `/messages` snapshot returns this value so a client can align the
+ * snapshot with the stream: "these rows reflect all of this
+ * conversation's events through `seq = S`." It is recorded at each
+ * persistence flush (assistant rows persist incrementally, debounced, so
+ * the snapshot can lag the live counter) -- never the live counter
+ * itself, which would over-claim events that have streamed but not yet
+ * been written. It shares the live counter's lifetime by design: both
+ * are in-memory and reset together on restart, so a stored value can
+ * never dangle against a fresh counter. The map is LRU-bounded; an
+ * evicted conversation reports no seq and the client cold-starts.
  */
 
 import type { AssistantEvent } from "./assistant-event.js";
@@ -26,6 +48,16 @@ const RING_COUNT_LIMIT = 200;
 const RING_SIZE_LIMIT_BYTES = 256 * 1024;
 const RING_AGE_LIMIT_MS = 30_000;
 
+/**
+ * Cap on how many conversations retain a persisted-seq entry. Unlike the
+ * ring (which the live stream needs only briefly), the persisted-seq map
+ * grows with the number of conversations that have ever streamed in this
+ * process. Bound it LRU so it can't grow without limit; an evicted
+ * conversation simply reports no seq on its next `/messages` and the
+ * client cold-starts, which is harmless.
+ */
+const PERSISTED_SEQ_CONVERSATION_LIMIT = 1024;
+
 // ── Types ────────────────────────────────────────────────────────────
 
 /**
@@ -63,30 +95,33 @@ interface RingEntry {
   targeting?: EventTargeting;
 }
 
-interface ConversationStreamState {
+interface AssistantStreamState {
   nextSeq: number;
   ring: RingEntry[];
   totalSizeBytes: number;
+  /**
+   * Per-conversation `seq` of the last event durably committed to the
+   * message rows. Insertion order is maintained as an LRU recency list:
+   * the oldest key is evicted first once the map exceeds
+   * {@link PERSISTED_SEQ_CONVERSATION_LIMIT}.
+   */
+  persistedSeqByConversation: Map<string, number>;
 }
 
 // ── State ────────────────────────────────────────────────────────────
 
-const streams = new Map<string, ConversationStreamState>();
-
-function getOrCreate(conversationId: string): ConversationStreamState {
-  let state = streams.get(conversationId);
-  if (!state) {
-    state = { nextSeq: 1, ring: [], totalSizeBytes: 0 };
-    streams.set(conversationId, state);
-  }
-  return state;
-}
+const state: AssistantStreamState = {
+  nextSeq: 1,
+  ring: [],
+  totalSizeBytes: 0,
+  persistedSeqByConversation: new Map(),
+};
 
 // ── Public API ───────────────────────────────────────────────────────
 
 /**
- * Assign a monotonic `seq` to a conversation-scoped event and push it
- * onto the ring buffer. No-op when `event.conversationId` is absent
+ * Assign a monotonic global `seq` to a conversation-scoped event and push
+ * it onto the ring buffer. No-op when `event.conversationId` is absent
  * (unscoped broadcasts are never replayable).
  *
  * When `options.targeting` is provided, the metadata is stored on the
@@ -101,10 +136,8 @@ export function stampAndBuffer(
   event: AssistantEvent,
   options?: { targeting?: EventTargeting },
 ): void {
-  const cid = event.conversationId;
-  if (cid == null) return;
+  if (event.conversationId == null) return;
 
-  const state = getOrCreate(cid);
   event.seq = state.nextSeq++;
 
   // Approximate size by serialized JSON length. This is the same
@@ -123,43 +156,36 @@ export function stampAndBuffer(
   state.ring.push(entry);
   state.totalSizeBytes += sizeBytes;
 
-  evict(state);
+  evict();
 }
 
 /**
- * Replay events with `seq > lastSeenSeq` for a given conversation.
+ * Replay events with `seq > lastSeenSeq` from the single global ring.
  * Returns `null` when the requested cursor is older than the oldest
  * buffered entry -- callers should fall back to a snapshot resync.
  *
  * When `subscriber` is provided, entries carrying targeting metadata
  * are filtered using the same rules as the live `publish()` path in
- * `AssistantEventHub`. This prevents targeted events from leaking to
- * subscribers outside their intended delivery set on reconnect.
- * When `subscriber` is omitted, all entries are returned unfiltered
- * (backwards-compatible behaviour).
+ * `AssistantEventHub`, so targeted events do not leak to subscribers
+ * outside their intended delivery set on reconnect.
+ *
+ * When `conversationId` is provided, only that conversation's events are
+ * returned -- a conversation-scoped subscription only delivers its own
+ * conversation live, so replaying any other conversation's gap would
+ * push events the client will never receive again live.
  *
- * Sweeps age-expired entries at read time so an idle conversation
- * cannot serve stale deltas past the 30-second window (eviction
- * only runs on `stampAndBuffer`, so without this an idle stream
- * would retain its tail until the next write). When the sweep
- * drains the ring entirely, the conversation's state entry is
- * dropped to keep the global map from growing unboundedly with
- * inactive conversations.
+ * Sweeps age-expired entries at read time so an idle stream cannot serve
+ * stale deltas past the 30-second window (eviction otherwise only runs on
+ * `stampAndBuffer`).
  */
 export function getReplayWindow(
-  conversationId: string,
   lastSeenSeq: number,
   subscriber?: ReplaySubscriber,
+  conversationId?: string,
 ): readonly AssistantEvent[] | null {
-  const state = streams.get(conversationId);
-  if (!state) return [];
+  evict();
 
-  evict(state);
-
-  if (state.ring.length === 0) {
-    streams.delete(conversationId);
-    return [];
-  }
+  if (state.ring.length === 0) return [];
 
   const oldest = state.ring[0]?.seq ?? Infinity;
   if (lastSeenSeq < oldest - 1) return null;
@@ -168,39 +194,87 @@ export function getReplayWindow(
     .filter(
       (entry) =>
         entry.seq > lastSeenSeq &&
+        (conversationId == null ||
+          entry.event.conversationId === conversationId) &&
         (subscriber == null || matchesSubscriber(entry, subscriber)),
     )
     .map((entry) => entry.event);
 }
 
 /**
- * Drop all state for a conversation. Currently unused -- the ring
- * self-evicts by age -- but exposed for explicit dispose flows
- * (e.g. when a conversation is deleted).
+ * Current high-water `seq` -- the value last assigned by
+ * {@link stampAndBuffer}, or `0` when nothing has been stamped yet in
+ * this process.
+ *
+ * Read synchronously right after emitting an event to learn that event's
+ * `seq`: `stampAndBuffer` runs inline on the publish path (before the
+ * async fanout), so no other event can interleave between the emit
+ * returning and this read on the single-threaded event loop.
+ */
+export function getCurrentSeq(): number {
+  return state.nextSeq - 1;
+}
+
+/**
+ * Record that conversation `conversationId` has durably persisted all of
+ * its events through `seq`. Called at each persistence flush with the
+ * `seq` of the last event whose content the write committed.
+ *
+ * Monotonic: a lower `seq` never regresses a higher one (out-of-order
+ * async commits are clamped). LRU-bounded by
+ * {@link PERSISTED_SEQ_CONVERSATION_LIMIT}: re-recording refreshes
+ * recency, and the oldest conversation is evicted once the cap is
+ * exceeded. Non-positive or non-finite `seq` values are ignored.
+ */
+export function recordPersistedSeq(conversationId: string, seq: number): void {
+  if (!Number.isFinite(seq) || seq <= 0) return;
+
+  const map = state.persistedSeqByConversation;
+  const prev = map.get(conversationId);
+  if (prev !== undefined) {
+    // Re-insert to move this key to the most-recently-used end.
+    map.delete(conversationId);
+    map.set(conversationId, Math.max(prev, seq));
+    return;
+  }
+
+  map.set(conversationId, seq);
+  if (map.size > PERSISTED_SEQ_CONVERSATION_LIMIT) {
+    const oldestKey = map.keys().next().value;
+    if (oldestKey !== undefined) map.delete(oldestKey);
+  }
+}
+
+/**
+ * Highest `seq` durably persisted for `conversationId`, or `null` when
+ * none has been recorded in this process (cold conversation, or evicted
+ * from the LRU map). Returned by `/messages` so a client can align the
+ * snapshot with the live stream.
  */
-export function clearConversationStream(conversationId: string): void {
-  streams.delete(conversationId);
+export function getPersistedSeq(conversationId: string): number | null {
+  return state.persistedSeqByConversation.get(conversationId) ?? null;
 }
 
 /**
  * Reset all stream state. Test-only.
  */
-export function _resetConversationStreamsForTesting(): void {
-  streams.clear();
+export function _resetStreamStateForTesting(): void {
+  state.nextSeq = 1;
+  state.ring = [];
+  state.totalSizeBytes = 0;
+  state.persistedSeqByConversation.clear();
 }
 
 /**
  * Read-only inspector for tests.
  */
-export function _peekStreamForTesting(conversationId: string): {
+export function _peekStreamForTesting(): {
   nextSeq: number;
   ringLength: number;
   totalSizeBytes: number;
   oldestSeq: number | null;
   newestSeq: number | null;
-} | null {
-  const state = streams.get(conversationId);
-  if (!state) return null;
+} {
   return {
     nextSeq: state.nextSeq,
     ringLength: state.ring.length,
@@ -276,7 +350,7 @@ function matchesSubscriber(
   return true;
 }
 
-function evict(state: ConversationStreamState): void {
+function evict(): void {
   const now = Date.now();
   while (state.ring.length > 0) {
     const head = state.ring[0];

package/src/runtime/channel-approvals.ts

@@ -9,7 +9,7 @@
  *   3. Consume user decisions and apply them to the underlying session
  */
 
-import { findConversation } from "../daemon/conversation-store.js";
+import { findConversation } from "../daemon/conversation-registry.js";
 import type { UserDecision } from "../permissions/types.js";
 import { composeApprovalMessage } from "./approval-message-composer.js";
 import type {

package/src/runtime/http-router.ts

@@ -19,7 +19,12 @@ import { httpError } from "./http-errors.js";
 import { withErrorHandling } from "./middleware/error-handler.js";
 import { routeDefinitionsToHTTPRoutes } from "./routes/http-adapter.js";
 import { ROUTES } from "./routes/index.js";
-import type { RouteLoggingConfig, RoutePathParam } from "./routes/types.js";
+import type {
+  RouteLoggingConfig,
+  RoutePathParam,
+  RouteRequestBody,
+  RouteResponseBody,
+} from "./routes/types.js";
 
 // ---------------------------------------------------------------------------
 // Route definition types
@@ -64,17 +69,6 @@ export interface RouteAdditionalResponse {
   schema?: RouteBodySchema | Record<string, unknown>;
 }
 
-/**
- * Request-body variant keyed by Content-Type. Use this when an endpoint
- * accepts multiple body shapes (e.g. `application/octet-stream` OR
- * `application/json`). For the common single-JSON case, use `requestBody`.
- */
-export interface RouteRequestBodyVariant {
-  contentType: string;
-  /** Zod schema or plain JSON Schema fragment. Plain objects are embedded verbatim. */
-  schema: RouteBodySchema | Record<string, unknown>;
-}
-
 /**
  * A single route entry in the declarative table.
  *
@@ -110,17 +104,18 @@ export interface HTTPRouteDefinition {
   tags?: string[];
   /** Query parameter definitions for the operation. */
   queryParams?: RouteQueryParam[];
-  /** Zod schema for the request body (POST/PUT/PATCH/DELETE). */
-  requestBody?: RouteBodySchema;
   /**
-   * Alternate request-body variants keyed by Content-Type. When set,
-   * overrides `requestBody` in the generated OpenAPI spec — use this for
-   * endpoints that accept multiple body shapes on the same URL (e.g.
-   * raw bytes OR JSON URL).
+   * Request body for POST/PUT/PATCH/DELETE. A bare Zod schema is advertised
+   * as `application/json`; use the `{ contentType, schema }` form for non-JSON
+   * bodies (e.g. a raw `application/octet-stream` upload).
+   */
+  requestBody?: RouteRequestBody;
+  /**
+   * Success response body. A bare Zod schema is advertised as
+   * `application/json`; use the `{ contentType, schema }` form for non-JSON
+   * responses (e.g. a binary `application/octet-stream` download).
    */
-  requestBodies?: RouteRequestBodyVariant[];
-  /** Zod schema for the success response body. */
-  responseBody?: RouteBodySchema;
+  responseBody?: RouteResponseBody;
   /**
    * HTTP status code for the documented success response. Defaults to 200.
    * Set to "202" for async endpoints that enqueue a job and return

package/src/runtime/http-types.ts

@@ -1,6 +1,10 @@
 /**
  * Shared types for the runtime HTTP server and its route handlers.
  */
+import type {
+  ConversationMessage,
+  ConversationMessageAttachment,
+} from "../api/responses/conversation-message.js";
 import type { ChannelId, InterfaceId } from "../channels/types.js";
 import type { LLMCallSite } from "../config/schemas/llm.js";
 import type { Conversation } from "../daemon/conversation.js";
@@ -137,74 +141,16 @@ export interface RuntimeHttpServerOptions {
   hostname?: string;
 }
 
-export interface RuntimeAttachmentMetadata {
-  id: string;
-  filename: string;
-  mimeType: string;
-  sizeBytes: number;
-  kind: string;
-  data?: string;
-  thumbnailData?: string;
-  fileBacked?: boolean;
-}
+/**
+ * Structured attachment metadata returned on a history row. Canonical wire
+ * shape lives in `@vellumai/assistant-api`; aliased here so route modules can
+ * keep importing the runtime-local name.
+ */
+export type RuntimeAttachmentMetadata = ConversationMessageAttachment;
 
-export interface RuntimeMessagePayload {
-  id: string;
-  /**
-   * Server message ids that were folded into this display row when consecutive
-   * assistant messages were consolidated for history rendering.
-   */
-  mergedMessageIds?: string[];
-  role: string;
-  timestamp: string;
-  attachments: RuntimeAttachmentMetadata[];
-  toolCalls?: Array<{
-    name: string;
-    input: Record<string, unknown>;
-    result?: string;
-    isError?: boolean;
-    riskLevel?: string;
-    riskReason?: string;
-    autoApproved?: boolean;
-    approvalMode?: string;
-    approvalReason?: string;
-    riskThreshold?: string;
-  }>;
-  surfaces?: Array<{
-    surfaceId: string;
-    surfaceType: string;
-    title?: string;
-    data: Record<string, unknown>;
-    actions?: unknown[];
-    display?: string;
-  }>;
-  textSegments?: string[];
-  thinkingSegments?: string[];
-  contentOrder?: string[];
-  subagentNotification?: {
-    subagentId: string;
-    label: string;
-    status: string;
-    error?: string;
-    conversationId?: string;
-    objective?: string;
-  };
-  slackMessage?: {
-    channelId: string;
-    channelName?: string;
-    channelTs: string;
-    threadTs?: string;
-    sender?: {
-      displayName?: string;
-      externalUserId?: string;
-    };
-    messageLink?: {
-      appUrl?: string;
-      webUrl?: string;
-    };
-    threadLink?: {
-      appUrl?: string;
-      webUrl?: string;
-    };
-  };
-}
+/**
+ * The daemon's history-row payload. Canonical wire contract lives in
+ * `@vellumai/assistant-api` (`responses/conversation-message.ts`) so the
+ * producer and every consumer (web, CLI, evals) derive from one source.
+ */
+export type RuntimeMessagePayload = ConversationMessage;

package/src/runtime/interactive-ui.ts

@@ -30,7 +30,7 @@
  *     `"timed_out"`.
  */
 
-import { findConversation } from "../daemon/conversation-store.js";
+import { findConversation } from "../daemon/conversation-registry.js";
 import { showStandaloneSurface } from "../daemon/conversation-surfaces.js";
 import { getLogger } from "../util/logger.js";
 import { mintDecisionToken } from "./decision-token.js";

package/src/runtime/pending-interactions.ts

@@ -38,6 +38,7 @@ export interface ConfirmationDetails {
     pattern: string;
   }>;
   scopeOptions: Array<{ label: string; scope: string }>;
+  directoryScopeOptions?: Array<{ label: string; scope: string }>;
   persistentDecisionsAllowed?: boolean;
   /** ACP tool kind from the agent (e.g. "read", "edit", "execute"). */
   acpToolKind?: string;