@vellumai/assistant 0.12.2-dev.202609181713.fb1ff61 → 0.12.2-dev.202609181913.1108ac3

package/ARCHITECTURE.md

@@ -96,7 +96,7 @@ All HTTP API requests use a single `Authorization: Bearer <jwt>` header for auth
 
 **Credential storage:** Only hashed tokens are persisted. Access token hashes go in `credential_records`; refresh token hashes in `refresh_token_records`. Raw tokens are returned once and never stored server-side.
 
-**Notification scoping:** Guardian-sensitive notifications are annotated with `targetGuardianPrincipalId` for identity-scoped delivery.
+**Notification scoping:** Guardian-sensitive notifications (`notification_intent`, `notification_conversation_created`) are published with `targetActorPrincipalId`, so the event hub delivers them, live, on reconnect replay, and from the `events/tail` recovery route, only to SSE connections whose verified `actorPrincipalId` is the guardian's. Connections without a principal never receive them. The payload's `targetGuardianPrincipalId` records the scoping.
 
 **Key source files:**
 
@@ -289,32 +289,35 @@ The WhatsApp channel enables inbound and outbound messaging via the Meta WhatsAp
 
 **Ingress** (`GET /webhooks/whatsapp` — verification, `POST /webhooks/whatsapp` — messages):
 
-1. **Webhook verification**: Meta sends a `GET` with `hub.mode=subscribe`, `hub.verify_token`, and `hub.challenge`. The gateway compares `hub.verify_token` against `WHATSAPP_WEBHOOK_VERIFY_TOKEN` and echoes `hub.challenge` as plain text.
-2. On `POST`, the gateway verifies the `X-Hub-Signature-256` header (HMAC-SHA256 of the raw request body using `WHATSAPP_APP_SECRET`) when the app secret is configured. Fail-closed: requests are rejected when the secret is set but the signature fails.
+1. **Webhook verification**: Meta sends a `GET` with `hub.mode=subscribe`, `hub.verify_token`, and `hub.challenge`. The gateway compares `hub.verify_token` against the `webhook_verify_token` credential and echoes `hub.challenge` as plain text.
+2. On `POST`, the gateway verifies the `X-Hub-Signature-256` header (HMAC-SHA256 of the raw request body using the `app_secret` credential). Fail-closed: a request is rejected with 500 when no app secret is configured, and with 403 when the signature does not match.
 3. **Normalization**: Text and media messages (image, audio, video, document, sticker) from `messages` change fields are forwarded. Delivery receipts, read receipts, and unsupported message types (contacts, location) are silently acknowledged with `{ ok: true }`. Media attachments are downloaded from the WhatsApp Cloud API, uploaded to the runtime attachment store, and their IDs are passed alongside the message content.
 4. **`/new` command**: When the message body is `/new` (case-insensitive), the gateway resolves routing, resets the conversation, and sends a confirmation message without forwarding to the runtime.
 5. The payload is normalized into a `GatewayInboundEvent` with `sourceChannel: "whatsapp"` and `conversationExternalId` set to the sender's WhatsApp phone number (E.164).
 6. WhatsApp message IDs are deduplicated via `StringDedupCache` (24-hour TTL).
 7. The gateway marks each inbound message as read (best-effort, fire-and-forget).
-8. The event is forwarded to the runtime via `POST /channels/inbound` with WhatsApp-specific transport hints and a `replyCallbackUrl` pointing to `/deliver/whatsapp`.
+8. The event is forwarded to the runtime via `POST /channels/inbound` with WhatsApp-specific transport hints and a `replyCallbackUrl` of `<gatewayInternalBaseUrl>/deliver/whatsapp`. The gateway serves no route at that path: the daemon uses the URL only to address the reply (see Egress).
 
-**Egress** (`POST /deliver/whatsapp`):
+**Egress** (daemon WhatsApp transport, `src/messaging/providers/whatsapp/`):
 
-1. The runtime calls the gateway's `/deliver/whatsapp` endpoint with `{ to, text }` or `{ chatId, text }` (alias).
-2. The gateway authenticates the request via bearer token (same fail-closed model as other deliver endpoints).
-3. The gateway sends the message via the WhatsApp Cloud API `/{phoneNumberId}/messages` endpoint using the configured access token.
-4. Text is split at 4096 characters if needed.
+1. Replies, approval prompts, and proactive sends go out through the daemon's `whatsappTransport` (`transport.ts`), which calls the Meta Cloud API itself. `isDirectDelivery()` in `src/messaging/providers/index.ts` resolves the `/deliver/whatsapp` callback URL to this transport through `channelForCallback()` (`src/messaging/providers/callback-routing.ts`), so the daemon never posts back to the gateway or dials the URL's host and port. The exception is on the gateway side: its replies to invite and verification codes it intercepts at ingress (`deliverVerificationReply` in `gateway/src/verification/reply-delivery.ts`) still POST to the callback URL, which no gateway route serves, so those replies are not delivered.
+2. `api.ts` reads `phone_number_id` and `access_token` from the secure store and sends through the Cloud API `/{phoneNumberId}/messages` endpoint.
+3. `send.ts` splits text into 4096-character chunks, preferring newline and then whitespace boundaries.
+4. An approval prompt renders as an interactive message with up to three reply buttons whose ids follow the shared `apr:<requestId>:<action>` convention. When the cap forces a cut, the reject and block actions are kept. The gateway normalizes the guardian's `button_reply` back into callback data on ingress.
+5. Attachments up to 25 MB are uploaded to the Cloud API media endpoint and sent as image, video, or document messages. Any that fail are listed in a follow-up text notice.
 
-**Required credentials**:
+The gateway sends only its own notices to WhatsApp (the `/new` confirmation and routing-rejection notices), through `gateway/src/whatsapp/send.ts`.
 
-- `WHATSAPP_PHONE_NUMBER_ID` — the numeric WhatsApp Business phone number ID from Meta
-- `WHATSAPP_ACCESS_TOKEN` — System User or temporary access token
-- `WHATSAPP_APP_SECRET` — App secret for webhook signature verification
-- `WHATSAPP_WEBHOOK_VERIFY_TOKEN` — Token for the Meta webhook subscription handshake
+**Required credentials** (credential vault, `whatsapp` service):
 
-These can be set via environment variables or stored in the credential vault (CES / encrypted store) under the `whatsapp` service prefix.
+- `phone_number_id`: the numeric WhatsApp Business phone number ID from Meta
+- `access_token`: System User or temporary access token
+- `app_secret`: app secret for webhook signature verification
+- `webhook_verify_token`: token for the Meta webhook subscription handshake
 
-**Limitations (v1)**: Rich approval UI (inline buttons) is not supported. Contacts and location message types are acknowledged but not forwarded.
+The daemon reads `phone_number_id` and `access_token` to send. The gateway reads all four: the last two for ingress, and the first two for its own notices.
+
+**Limitations**: Contacts and location message types are acknowledged but not forwarded.
 
 **Channel Readiness**: The channel readiness HTTP endpoints (`GET /v1/channels/readiness`, `POST /v1/channels/readiness/refresh`) backed by `ChannelReadinessService` in `src/runtime/channel-readiness-service.ts` provide a unified readiness subsystem for all channels. Each channel registers a `ChannelProbe` that runs synchronous local checks (credential presence, ingress config) and optional async remote checks with a 5-minute TTL cache. Built-in probes: Telegram (bot token, webhook secret, ingress). The GET endpoint returns cached snapshots; the refresh endpoint invalidates the cache first. Unknown channels return `unsupported_channel`. Route handlers live in `src/runtime/routes/channel-readiness-routes.ts`.
 
@@ -1993,7 +1996,7 @@ An SSE push event surfaces new conversations in the macOS client sidebar:
 
 - **`notification_conversation_created`** — Emitted by `broadcaster.ts` when a notification delivery **creates** a new vellum conversation (strategy `start_new_conversation`, `createdNewConversation: true`). **Not** emitted when a conversation is reused. Payload: `{ conversationId, title, sourceEventName }`.
 
-The event follows this pattern: the daemon creates a server-side conversation, persists an initial message, and broadcasts the SSE event so the macOS `ConversationManager` can create a visible conversation in the sidebar.
+The daemon persists the conversation and its initial message before broadcasting, so a client that receives the event can fetch the conversation immediately. A guardian-sensitive conversation is announced only to the guardian's own connections.
 
 ### Conversation Routing Decision Flow
 
@@ -2031,12 +2034,15 @@ Reminders carry optional `routingIntent` (`single_channel` | `multi_channel` | `
 
 ### Channel Delivery
 
-Notifications are delivered to three channel types:
+Notifications are delivered to five channel types. The daemon sends to external channels itself, calling each provider's API through the send modules in `src/messaging/providers/<channel>/`; nothing goes through the gateway.
 
 - **Vellum (always connected)**: SSE via the daemon's broadcast mechanism. The `VellumAdapter` emits a `notification_intent` message with rendered copy and optional `deepLinkMetadata` (includes `conversationId` for conversation navigation and `messageId` for message-level scroll anchoring).
-- **Telegram (when guardian binding exists)**: HTTP POST to the gateway's `/deliver/telegram` endpoint. Requires an active guardian binding for the assistant.
+- **Platform (always connected)**: the `PlatformPushAdapter` posts the notification to the platform's `/v1/assistants/{id}/push/dispatch/` endpoint for native mobile push. Without platform credentials the delivery is recorded as failed.
+- **Telegram (when the guardian has a chat ID)**: the `TelegramAdapter` calls the Telegram Bot API through `telegram-bot/send.ts`. Approval cards carry inline keyboard buttons and fall back to plain text with typed-reply instructions if the rich send fails.
+- **Slack (when the guardian's chat is a DM)**: the `SlackAdapter` posts through `slack/send.ts`. Only `D`-prefixed DM channels qualify, so a binding made from a shared channel never receives notifications.
+- **Discord (when the guardian binding names a user)**: the `DiscordAdapter` opens the guardian's DM through the Discord REST API and sends through `discord/send.ts`.
 
-Connected channels are resolved at signal emission time: vellum is always included, and binding-based channels (Telegram) are included only when an active guardian binding exists for the assistant.
+Connected channels are resolved at signal emission time by `getConnectedChannels()` in `emit-signal.ts`, from the guardian delivery list (`getGuardianDelivery()`): vellum and platform are always included, and Telegram, Slack, and Discord are included only when that list gives the guardian a deliverable endpoint on the channel.
 
 **Key modules:**
 
@@ -2050,8 +2056,11 @@ Connected channels are resolved at signal emission time: vellum is always includ
 | `assistant/src/notifications/conversation-pairing.ts`                      | Materializes conversation + message per delivery; executes conversation reuse decisions                                               |
 | `assistant/src/notifications/conversation-candidates.ts`                   | Builds per-channel candidate set of recent conversations for the decision engine                                                      |
 | `assistant/src/notifications/adapters/macos.ts`                            | Vellum adapter — broadcasts `notification_intent` via SSE with deep-link metadata                                                     |
-| `assistant/src/notifications/adapters/telegram.ts`                         | Telegram adapter — POSTs to gateway `/deliver/telegram`                                                                               |
-| `assistant/src/notifications/destination-resolver.ts`                      | Resolves per-channel endpoints (vellum SSE, Telegram chat ID from guardian binding)                                                   |
+| `assistant/src/notifications/adapters/platform.ts`                         | Platform adapter: posts to the platform push-dispatch endpoint for native mobile push                                                 |
+| `assistant/src/notifications/adapters/telegram.ts`                         | Telegram adapter: calls the Telegram Bot API through `messaging/providers/telegram-bot/send.ts`                                       |
+| `assistant/src/notifications/adapters/slack.ts`                            | Slack adapter: posts to the guardian's DM through `messaging/providers/slack/send.ts`                                                 |
+| `assistant/src/notifications/adapters/discord.ts`                          | Discord adapter: sends to the guardian's DM through `messaging/providers/discord/send.ts`                                             |
+| `assistant/src/notifications/destination-resolver.ts`                      | Resolves per-channel endpoints from the guardian delivery list (Telegram and Slack chat ID, Discord user ID)                          |
 | `assistant/src/notifications/copy-composer.ts`                             | Template-based fallback copy when LLM copy is unavailable                                                                             |
 | `assistant/src/notifications/preference-extractor.ts`                      | Detects preference statements in conversation messages                                                                                |
 | `assistant/src/notifications/preferences-store.ts`                         | CRUD for user notification preferences                                                                                                |

package/docs/mode-sessions.md

@@ -0,0 +1,183 @@
+# Transcript mode sessions
+
+Mode sessions are compact, conversation-owned lifecycle records for grouping
+computer-use, browser, Live vision, and reserved Ambient transcript activity.
+They connect runtime producers to immutable message membership while keeping
+model input and stored message content unchanged.
+
+## API contract
+
+`src/api/mode-session.ts` owns both shared shapes:
+
+- `ModeSession` is immutable transcript membership: an opaque `id` and one of
+  `computer_use`, `browser`, `live_vision`, or `ambient`.
+- `ModeSessionSummary` is the durable lifecycle record. It carries the owning
+  conversation, mode, timing bounds, boundary message IDs, terminal reason,
+  and a positive monotonic revision.
+
+Only three statuses are stored: `active`, `completed`, and `interrupted`.
+Waiting and draining are runtime presentation facts and do not add database
+states. Duration is derived from recorded time bounds instead of stored as a
+separate value. Active records have no terminal fields, completed records have
+a confirmed end, and interrupted records may leave the end unknown. A known end
+never precedes the last confirmed activity.
+
+## Persistence
+
+Migration 381 creates `conversation_mode_sessions`. Each row belongs to one
+conversation through an `ON DELETE CASCADE` foreign key. The
+`(conversation_id, status)` index supports conversation-scoped active reads,
+while the primary key supports bounded ID batches for transcript pages.
+
+`conversation-mode-sessions.ts` is the only lifecycle writer. Begin creates
+revision 1. Activity, boundary, revision-only, and terminal updates require the
+caller's expected revision and run in an immediate transaction. Each accepted
+write increments the revision. A stale revision, missing record, or terminal
+record is returned as an expected write outcome. Terminal rows cannot return
+to active or change to a different terminal result. Repeating the same terminal
+outcome is an accepted no-op and does not advance the revision.
+
+The first included boundary can precede source activation when a later action
+claims assistant content already persisted in the same logical turn. Last
+activity never moves backward. An interruption may have an unknown end, so
+`endedAt` remains nullable and `lastActivityAt` remains the last confirmed
+time.
+
+## Startup recovery
+
+After database migrations succeed, the assistant marks every leftover active
+record interrupted before database readiness is published. Recovery increments
+the revision, preserves activity and message boundaries, records
+`assistant_restarted`, and leaves `endedAt` null. It runs on every boot rather
+than as a checkpointed migration.
+
+If this auxiliary recovery fails, ordinary database readiness succeeds and
+tracking stays unavailable for that boot. History omits unrecovered active
+descriptors while preserving terminal records and message stamps. A subsequent
+boot retries through the same startup path. Required migration failures still
+block database readiness.
+
+Runtime source generations and structural question associations are owned by
+the producer and message-membership integration. Those process-local facts are
+not reconstructed after restart. Resumed mode work uses a fresh session ID and
+callbacks from retired source generations are rejected.
+
+New producer admissions are controlled by the default-off `session-groups`
+assistant feature flag. Browser and computer-use actions still execute when the
+flag is off, but they do not activate or claim a mode session. Existing owners
+and terminal cleanup continue to drain so disabling the flag cannot strand
+accepted work. Live voice snapshots the flag when its socket session is
+created: disabled sessions retain the existing camera transport without
+advertising or preparing tracked sight-session epochs.
+
+The same flag controls activity-label wording at the shared rendering
+boundary. Disabled views retain their existing labels and phase grouping.
+
+The migration, startup recovery, persisted message stamps, and history reads
+remain available while the flag is off. This keeps records made by an enabled
+cohort compatible with rollback and later re-enablement.
+
+## Runtime ownership
+
+Each live `Conversation` owns one `ConversationModeSessionCoordinator`.
+Computer-use, browser, and camera producers activate a source with a stable
+source identity and guarded generation. The first accepted mode action claims
+the logical turn. The coordinator backfills rows already persisted for that
+turn, then stamps later user, assistant, and tool-result rows as they are
+inserted. A turn keeps its first owner when another mode acts inside it.
+
+Source eligibility and captured turn ownership end separately. Ending or
+resetting a source prevents future claims immediately, but a captured turn
+keeps its owner until its final output is persisted. Ordinary computer-use and
+browser sources finish when the turn settles. Camera sources use a source
+lifetime plus a synthetic run turn, so accepted frame writes and captured
+voice turns form a settlement barrier before terminal persistence. A camera
+epoch snapshots ownership before asynchronous frame persistence; stale epochs
+cannot join a later run.
+
+Tracking failures are logged and isolated from authorized actions and accepted
+content persistence. They never repeat the underlying action. A refused camera
+start clears client negotiation and falls back to untracked frames without
+revoking consent or ending voice. Individual stale-frame rejection does not
+use this fallback.
+
+Server admission is the camera boundary: an admitted frame can finish saving
+after stop, but a device-side capture delivered after its run ends is rejected
+and reclaimed. Reconnect pauses capture delivery and announces a fresh run
+after replacement readiness. In-flight uploads and native samples retain their
+captured ownership and cannot join the replacement run.
+
+The coordinator stores only `active`, `completed`, or `interrupted`. Waiting
+and finishing are revisioned runtime hints. Terminal dispositions remain
+pending in memory until all captured turns release, then one idempotent
+compare-and-swap update records the terminal outcome. A successful turn with
+no explicit producer end also finalizes, allowing later work from the same
+resource generation to mint a new session.
+
+Regular reload, TTL, LRU, and memory-pressure eviction retain a conversation
+while it has an eligible mode source, captured owner, structural association,
+or unsettled terminal disposition. This preserves accepted camera output and
+exact structural continuation in the coordinator that admitted them. A long
+structural wait therefore remains resident until it is consumed, invalidated,
+or its source retires. Explicit conversation deletion and process shutdown
+keep their existing teardown semantics; startup recovery interrupts any
+durable active record left by process exit.
+
+Invalidating the final structural association retires a turn-lifetime source
+and lets accepted output settle. Successful abandoned waits end at their last
+confirmed activity with reason `structural_wait_abandoned`; cleanup does not
+extend their duration. Source-lifetime camera runs remain eligible. A retired
+disposition that cannot persist its terminal update releases residency and
+invalidates history without claiming completion. An active record without live
+ownership has no descriptor and renders as unavailable.
+
+## Structural continuation
+
+Structural waits associate an exact response identifier with the owned turn.
+Ordinary `ask_question` awaits its resolver inside that turn, so its answer
+resumes the existing owner. A blocking UI surface can accept a new turn: its
+matching response consumes the association before surface cleanup and retains
+the session ID. Rejected, stale, unrelated, or cross-conversation responses
+cannot inherit ownership. Dismissal invalidates the association. Ordinary prose
+and an idle reusable resource do not continue a session; later mode work starts
+a fresh ID and duration.
+
+Structural associations intentionally do not survive restart. Startup recovery
+terminalizes the old record, and a late response remains part of the existing
+interaction flow without reopening that record.
+
+## Transcript and synchronization
+
+`modeSession` is optional message metadata and is stripped from caller-supplied
+metadata. Membership is added only after a row insert succeeds. Text and
+thinking deltas carry no repeated ownership field; row-boundary events carry
+the current owner, and the normal conversation-messages invalidation refetches
+retrospective stamps.
+
+History returns one batched `modeSessions` descriptor list beside messages.
+The query resolves records for page members and accepts bounded explicit IDs
+for groups already loaded outside the newest page. Consolidation never crosses
+a stamped/unstamped or different-owner boundary. Same-owner folds retain row
+aliases and `modeSessionActivity.firstAt`/`lastAt`, so donor timestamps survive
+history compaction.
+
+Message deletion and retry paths recompute replaceable first/last display
+boundaries for every affected conversation session. They preserve status,
+terminal time, reason, and confirmed activity, and increment the revision.
+Deleting every owned row leaves the lifecycle record available for audit but
+produces no transcript container.
+
+All membership, lifecycle, boundary, and runtime-hint changes reuse the
+conversation-messages `sync_changed` tag. Clients merge descriptors by
+revision in the history query cache and refetch through the existing history
+reconciliation path. Explicit stale revisions cannot replace newer cached
+descriptors; an omitted descriptor remains unavailable. There is no separate
+descriptor store, session event stream, or polling endpoint.
+
+The transcript keeps lightweight segment identities for stable disclosure keys,
+not duplicate message bodies. Closed children unmount, and eligible mounted
+headers share one coarse clock that pauses while the app is hidden. No header
+visibility observer is required. The clock reads initial desktop visibility
+from the existing attention state on its coarse tick, without publishing a
+shared lifecycle edge. With grouping disabled, the load-older guard uses the
+ordinary flat-transcript behavior and skips grouped DOM scans.

package/openapi.yaml

@@ -20944,6 +20944,12 @@ paths:
           schema:
             type: integer
           description: Maximum number of messages to return.
+        - name: modeSessionIds
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Comma-separated mode-session IDs to include with summaries for loaded active groups outside this page.
       responses:
         "200":
           description: Successful response
@@ -20959,6 +20965,38 @@ paths:
                       properties:
                         id:
                           type: string
+                        modeSession:
+                          type: object
+                          properties:
+                            mode:
+                              type: string
+                              enum:
+                                - computer_use
+                                - browser
+                                - live_vision
+                                - ambient
+                            id:
+                              type: string
+                              minLength: 1
+                          required:
+                            - mode
+                            - id
+                          additionalProperties: false
+                        modeSessionActivity:
+                          type: object
+                          properties:
+                            firstAt:
+                              type: integer
+                              minimum: 0
+                              maximum: 8640000000000000
+                            lastAt:
+                              type: integer
+                              minimum: 0
+                              maximum: 8640000000000000
+                          required:
+                            - firstAt
+                            - lastAt
+                          additionalProperties: false
                         mergedMessageIds:
                           type: array
                           items:
@@ -22277,6 +22315,223 @@ paths:
                       locally but the server reports `processing: false`, the turn has ended (or died) and the UI should
                       stop waiting rather than spin indefinitely. Absent on older daemons that predate this field."
                     type: boolean
+                  modeSessions:
+                    description: Conversation-owned mode-session summaries referenced by this page or explicitly requested by ID.
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        summary:
+                          oneOf:
+                            - type: object
+                              properties:
+                                id:
+                                  type: string
+                                  minLength: 1
+                                conversationId:
+                                  type: string
+                                  minLength: 1
+                                mode:
+                                  type: string
+                                  enum:
+                                    - computer_use
+                                    - browser
+                                    - live_vision
+                                    - ambient
+                                sourceStartedAt:
+                                  type: integer
+                                  minimum: 0
+                                  maximum: 9007199254740991
+                                firstIncludedAt:
+                                  anyOf:
+                                    - type: integer
+                                      minimum: 0
+                                      maximum: 9007199254740991
+                                    - type: "null"
+                                firstIncludedMessageId:
+                                  anyOf:
+                                    - type: string
+                                      minLength: 1
+                                    - type: "null"
+                                lastActivityAt:
+                                  type: integer
+                                  minimum: 0
+                                  maximum: 9007199254740991
+                                lastOwnedMessageId:
+                                  anyOf:
+                                    - type: string
+                                      minLength: 1
+                                    - type: "null"
+                                revision:
+                                  type: integer
+                                  exclusiveMinimum: 0
+                                  maximum: 9007199254740991
+                                status:
+                                  type: string
+                                  const: active
+                                endedAt:
+                                  type: "null"
+                                endReason:
+                                  type: "null"
+                              required:
+                                - id
+                                - conversationId
+                                - mode
+                                - sourceStartedAt
+                                - firstIncludedAt
+                                - firstIncludedMessageId
+                                - lastActivityAt
+                                - lastOwnedMessageId
+                                - revision
+                                - status
+                                - endedAt
+                                - endReason
+                              additionalProperties: false
+                            - type: object
+                              properties:
+                                id:
+                                  type: string
+                                  minLength: 1
+                                conversationId:
+                                  type: string
+                                  minLength: 1
+                                mode:
+                                  type: string
+                                  enum:
+                                    - computer_use
+                                    - browser
+                                    - live_vision
+                                    - ambient
+                                sourceStartedAt:
+                                  type: integer
+                                  minimum: 0
+                                  maximum: 9007199254740991
+                                firstIncludedAt:
+                                  anyOf:
+                                    - type: integer
+                                      minimum: 0
+                                      maximum: 9007199254740991
+                                    - type: "null"
+                                firstIncludedMessageId:
+                                  anyOf:
+                                    - type: string
+                                      minLength: 1
+                                    - type: "null"
+                                lastActivityAt:
+                                  type: integer
+                                  minimum: 0
+                                  maximum: 9007199254740991
+                                lastOwnedMessageId:
+                                  anyOf:
+                                    - type: string
+                                      minLength: 1
+                                    - type: "null"
+                                revision:
+                                  type: integer
+                                  exclusiveMinimum: 0
+                                  maximum: 9007199254740991
+                                status:
+                                  type: string
+                                  const: completed
+                                endedAt:
+                                  type: integer
+                                  minimum: 0
+                                  maximum: 9007199254740991
+                                endReason:
+                                  type: string
+                                  minLength: 1
+                              required:
+                                - id
+                                - conversationId
+                                - mode
+                                - sourceStartedAt
+                                - firstIncludedAt
+                                - firstIncludedMessageId
+                                - lastActivityAt
+                                - lastOwnedMessageId
+                                - revision
+                                - status
+                                - endedAt
+                                - endReason
+                              additionalProperties: false
+                            - type: object
+                              properties:
+                                id:
+                                  type: string
+                                  minLength: 1
+                                conversationId:
+                                  type: string
+                                  minLength: 1
+                                mode:
+                                  type: string
+                                  enum:
+                                    - computer_use
+                                    - browser
+                                    - live_vision
+                                    - ambient
+                                sourceStartedAt:
+                                  type: integer
+                                  minimum: 0
+                                  maximum: 9007199254740991
+                                firstIncludedAt:
+                                  anyOf:
+                                    - type: integer
+                                      minimum: 0
+                                      maximum: 9007199254740991
+                                    - type: "null"
+                                firstIncludedMessageId:
+                                  anyOf:
+                                    - type: string
+                                      minLength: 1
+                                    - type: "null"
+                                lastActivityAt:
+                                  type: integer
+                                  minimum: 0
+                                  maximum: 9007199254740991
+                                lastOwnedMessageId:
+                                  anyOf:
+                                    - type: string
+                                      minLength: 1
+                                    - type: "null"
+                                revision:
+                                  type: integer
+                                  exclusiveMinimum: 0
+                                  maximum: 9007199254740991
+                                status:
+                                  type: string
+                                  const: interrupted
+                                endedAt:
+                                  anyOf:
+                                    - type: integer
+                                      minimum: 0
+                                      maximum: 9007199254740991
+                                    - type: "null"
+                                endReason:
+                                  type: string
+                                  minLength: 1
+                              required:
+                                - id
+                                - conversationId
+                                - mode
+                                - sourceStartedAt
+                                - firstIncludedAt
+                                - firstIncludedMessageId
+                                - lastActivityAt
+                                - lastOwnedMessageId
+                                - revision
+                                - status
+                                - endedAt
+                                - endReason
+                              additionalProperties: false
+                          type: object
+                        runtimeState:
+                          type: string
+                          enum:
+                            - waiting
+                            - finishing
+                      required:
+                        - summary
+                      additionalProperties: false
                 required:
                   - messages
                 additionalProperties: false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.12.2-dev.202609181713.fb1ff61",
+  "version": "0.12.2-dev.202609181913.1108ac3",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/annotate-activity-metadata.test.ts

@@ -53,6 +53,7 @@ import {
   handleToolResult,
 } from "../daemon/conversation-agent-loop-handlers.js";
 import type { ToolActivityMetadata } from "../daemon/message-types/web-activity.js";
+import { mockUnownedModeSessions } from "./helpers/mock-conversation.js";
 
 // ── Helpers ───────────────────────────────────────────────────────────────────
 
@@ -65,6 +66,7 @@ function makeDeps(): EventHandlerDeps {
       emitActivityState: () => {},
       markWorkspaceTopLevelDirty: () => {},
       currentTurnSurfaces: [],
+      modeSessions: mockUnownedModeSessions(),
     } as unknown as EventHandlerDeps["ctx"],
     onEvent: () => {},
     reqId: "test-req",

package/src/__tests__/annotate-risk-options.test.ts

@@ -47,6 +47,7 @@ import {
   createEventHandlerState,
   handleToolResult,
 } from "../daemon/conversation-agent-loop-handlers.js";
+import { mockUnownedModeSessions } from "./helpers/mock-conversation.js";
 
 // ── Helpers ───────────────────────────────────────────────────────────────────
 
@@ -59,6 +60,7 @@ function makeDeps(): EventHandlerDeps {
       emitActivityState: () => {},
       markWorkspaceTopLevelDirty: () => {},
       currentTurnSurfaces: [],
+      modeSessions: mockUnownedModeSessions(),
     } as unknown as EventHandlerDeps["ctx"],
     onEvent: () => {},
     reqId: "test-req",

package/src/__tests__/answered-question-persistence.test.ts

@@ -46,6 +46,7 @@ import {
   createEventHandlerState,
   handleToolResult,
 } from "../daemon/conversation-agent-loop-handlers.js";
+import { mockUnownedModeSessions } from "./helpers/mock-conversation.js";
 
 // ── Helpers ───────────────────────────────────────────────────────────────────
 
@@ -60,6 +61,7 @@ function makeDeps(): EventHandlerDeps {
       emitActivityState: () => {},
       markWorkspaceTopLevelDirty: () => {},
       currentTurnSurfaces: [],
+      modeSessions: mockUnownedModeSessions(),
     } as unknown as EventHandlerDeps["ctx"],
     onEvent: (event: unknown) => {
       emitted.push(event as Record<string, unknown>);