@vellumai/assistant 0.8.7 → 0.8.8

package/src/runtime/assistant-event-hub.ts

@@ -43,7 +43,7 @@ import { appendEventToStream } from "../signals/event-stream.js";
 import { getLogger } from "../util/logger.js";
 import type { AssistantEvent } from "./assistant-event.js";
 import { buildAssistantEvent } from "./assistant-event.js";
-import { stampAndBuffer } from "./conversation-stream-state.js";
+import { stampAndBuffer } from "./assistant-stream-state.js";
 
 const log = getLogger("assistant-event-hub");
 
@@ -64,6 +64,13 @@ export interface AssistantEventSubscription {
   dispose(): void;
   /** True until `dispose()` has been called. */
   readonly active: boolean;
+  /**
+   * Per-connection identifier, unique within the hub instance. Distinguishes
+   * connections that share a `clientId` (e.g. an old connection and the new
+   * one that replaced it on reconnect) so subscribe / dispose / shed log
+   * lines can be attributed to a specific connection.
+   */
+  readonly connectionId: string;
 }
 
 // ── Subscriber entries (discriminated union) ─────────────────────────────────
@@ -75,6 +82,13 @@ interface BaseSubscriberEntry {
   onEvict: () => void;
   connectedAt: Date;
   lastActiveAt: Date;
+  /**
+   * Per-connection identifier, unique within the hub instance. Two entries
+   * with the same `clientId` (old vs reconnected connection) get distinct
+   * connection ids, making them traceable across subscribe / dispose / shed
+   * logs.
+   */
+  connectionId: string;
 }
 
 interface ClientEntry extends BaseSubscriberEntry {
@@ -106,10 +120,15 @@ type DistributiveOmit<T, K extends PropertyKey> = T extends unknown
   ? Omit<T, K>
   : never;
 
-/** Input shape for `subscribe()` — hub fills `active`, `connectedAt`, `lastActiveAt` and defaults `filter`/`onEvict`. */
+/** Input shape for `subscribe()` — hub fills `active`, `connectedAt`, `lastActiveAt`, `connectionId` and defaults `filter`/`onEvict`. */
 type SubscriberInput = DistributiveOmit<
   SubscriberEntry,
-  "active" | "connectedAt" | "lastActiveAt" | "filter" | "onEvict"
+  | "active"
+  | "connectedAt"
+  | "lastActiveAt"
+  | "filter"
+  | "onEvict"
+  | "connectionId"
 > & {
   filter?: AssistantEventFilter;
   onEvict?: () => void;
@@ -132,6 +151,8 @@ type SubscriberInput = DistributiveOmit<
 export class AssistantEventHub {
   private readonly subscribers = new Set<SubscriberEntry>();
   private readonly maxSubscribers: number;
+  /** Monotonic source for per-connection ids, scoped to this hub. */
+  private connectionCounter = 0;
 
   constructor(options?: { maxSubscribers?: number }) {
     this.maxSubscribers = options?.maxSubscribers ?? Infinity;
@@ -173,7 +194,11 @@ export class AssistantEventHub {
       }
       if (stale.length > 0) {
         log.info(
-          { clientId: subscriber.clientId, count: stale.length },
+          {
+            clientId: subscriber.clientId,
+            count: stale.length,
+            disposedConnectionIds: stale.map((entry) => entry.connectionId),
+          },
           "disposed stale subscribers for reconnecting client",
         );
       }
@@ -196,6 +221,7 @@ export class AssistantEventHub {
     }
 
     const now = new Date();
+    const connectionId = `conn-${++this.connectionCounter}`;
     const entry: SubscriberEntry = {
       ...subscriber,
       filter: subscriber.filter ?? {},
@@ -203,6 +229,7 @@ export class AssistantEventHub {
       active: true,
       connectedAt: now,
       lastActiveAt: now,
+      connectionId,
     } as SubscriberEntry;
 
     if (entry.type === "client") {
@@ -211,11 +238,12 @@ export class AssistantEventHub {
           clientId: entry.clientId,
           interfaceId: entry.interfaceId,
           capabilities: entry.capabilities,
+          connectionId,
         },
         "subscriber registered (client)",
       );
     } else {
-      log.info("subscriber registered (process)");
+      log.info({ connectionId }, "subscriber registered (process)");
     }
 
     this.subscribers.add(entry);
@@ -230,17 +258,19 @@ export class AssistantEventHub {
               {
                 clientId: entry.clientId,
                 interfaceId: entry.interfaceId,
+                connectionId,
               },
               "subscriber unregistered (client)",
             );
           } else {
-            log.info("subscriber unregistered (process)");
+            log.info({ connectionId }, "subscriber unregistered (process)");
           }
         }
       },
       get active() {
         return entry.active;
       },
+      connectionId,
     };
   }
 

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/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/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;