@vellumai/assistant 0.11.5 → 0.11.6-staging.1

package/src/oauth/connection.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  decodeJsonSafeOAuthBody,
+  decodeOAuthResponseBytes,
+  jsonSafeOAuthBody,
+  materializeOAuthRequestOutput,
+} from "./connection.js";
+
+const PNG_MAGIC = Buffer.from([
+  0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0xff, 0xfe, 0x00,
+]);
+
+describe("decodeOAuthResponseBytes", () => {
+  test("parses JSON bodies", () => {
+    const raw = Buffer.from(JSON.stringify({ id: "file-123", name: "Doc" }));
+    expect(
+      decodeOAuthResponseBytes(raw, "application/json; charset=utf-8"),
+    ).toEqual({ id: "file-123", name: "Doc" });
+  });
+
+  test("returns UTF-8 text for text content types", () => {
+    const raw = Buffer.from("hello café", "utf8");
+    expect(decodeOAuthResponseBytes(raw, "text/plain; charset=utf-8")).toBe(
+      "hello café",
+    );
+  });
+
+  test("preserves non-ASCII binary bytes instead of UTF-8 replacement characters", () => {
+    const body = decodeOAuthResponseBytes(
+      PNG_MAGIC,
+      "application/octet-stream",
+    );
+    expect(Buffer.isBuffer(body)).toBe(true);
+    expect(Buffer.from(body as Uint8Array).equals(PNG_MAGIC)).toBe(true);
+    expect(Buffer.from(body as Uint8Array).includes(0xff)).toBe(true);
+  });
+
+  test("treats Google Drive media downloads as raw bytes", () => {
+    const body = decodeOAuthResponseBytes(
+      PNG_MAGIC,
+      "application/pdf",
+    );
+    expect(Buffer.from(body as Uint8Array).equals(PNG_MAGIC)).toBe(true);
+  });
+
+  test("returns null for an empty body", () => {
+    expect(decodeOAuthResponseBytes(Buffer.alloc(0), "application/json")).toBe(
+      null,
+    );
+  });
+});
+
+describe("jsonSafeOAuthBody", () => {
+  test("leaves JSON and text bodies unchanged", () => {
+    expect(jsonSafeOAuthBody({ ok: true })).toEqual({ body: { ok: true } });
+    expect(jsonSafeOAuthBody("hello")).toEqual({ body: "hello" });
+  });
+
+  test("base64-encodes binary buffers for JSON envelopes", () => {
+    expect(jsonSafeOAuthBody(PNG_MAGIC)).toEqual({
+      body: PNG_MAGIC.toString("base64"),
+      bodyEncoding: "base64",
+    });
+    expect(Buffer.from(PNG_MAGIC.toString("base64"), "base64").equals(PNG_MAGIC)).toBe(
+      true,
+    );
+  });
+});
+
+describe("decodeJsonSafeOAuthBody", () => {
+  test("round-trips a binary envelope back to the original bytes", () => {
+    const encoded = jsonSafeOAuthBody(PNG_MAGIC);
+    const decoded = decodeJsonSafeOAuthBody(encoded);
+    expect(Buffer.isBuffer(decoded)).toBe(true);
+    expect(Buffer.from(decoded as Uint8Array).equals(PNG_MAGIC)).toBe(true);
+  });
+
+  test("leaves JSON and text envelopes unchanged", () => {
+    expect(decodeJsonSafeOAuthBody({ body: { ok: true } })).toEqual({
+      ok: true,
+    });
+    expect(decodeJsonSafeOAuthBody({ body: "hello" })).toBe("hello");
+  });
+
+  test("rejects a base64 marker whose body is not a string", () => {
+    expect(() =>
+      decodeJsonSafeOAuthBody({ body: { ok: true }, bodyEncoding: "base64" }),
+    ).toThrow("bodyEncoding=base64");
+  });
+});
+
+describe("materializeOAuthRequestOutput", () => {
+  test("writes raw bytes for a base64-marked envelope", () => {
+    const output = materializeOAuthRequestOutput(jsonSafeOAuthBody(PNG_MAGIC));
+    expect(output?.isBinary).toBe(true);
+    expect(output?.bytes.equals(PNG_MAGIC)).toBe(true);
+  });
+
+  test("pretty-prints parsed JSON and marks it as text", () => {
+    const output = materializeOAuthRequestOutput({ body: { ok: true } });
+    expect(output?.isBinary).toBe(false);
+    expect(output?.bytes.toString("utf8")).toBe(
+      JSON.stringify({ ok: true }, null, 2),
+    );
+  });
+
+  test("returns null for a missing body", () => {
+    expect(materializeOAuthRequestOutput({ body: null })).toBeNull();
+  });
+});

package/src/oauth/connection.ts

@@ -3,7 +3,12 @@ export interface OAuthConnectionRequest {
   path: string; // relative, e.g. "/2/tweets"
   query?: Record<string, string | string[]>;
   headers?: Record<string, string>;
-  body?: unknown; // JSON-serializable
+  /**
+   * A string is forwarded to the provider verbatim under the caller's own
+   * `Content-Type` (multipart, XML, form-encoded). Anything else is
+   * JSON-serialized and sent as `application/json`.
+   */
+  body?: unknown;
   /**
    * Override the connection's default base URL for this request.
    * Required for providers that span multiple API hosts sharing
@@ -18,7 +23,143 @@ export interface OAuthConnectionRequest {
 export interface OAuthConnectionResponse {
   status: number;
   headers: Record<string, string>;
+  /** JSON, UTF-8 text, or a Buffer of raw bytes for binary payloads. */
+  body: unknown;
+}
+
+const TEXT_MEDIA_TYPES = new Set([
+  "application/json",
+  "application/ld+json",
+  "application/xml",
+  "text/xml",
+  "application/javascript",
+  "application/x-www-form-urlencoded",
+  "application/problem+json",
+  "application/xhtml+xml",
+  "application/graphql",
+  "application/graphql+json",
+]);
+
+function mediaTypeOf(contentType: string): string {
+  return contentType.split(";", 1)[0].trim().toLowerCase();
+}
+
+function isTextMediaType(mediaType: string): boolean {
+  if (!mediaType) {
+    return false;
+  }
+  if (mediaType.startsWith("text/")) {
+    return true;
+  }
+  if (TEXT_MEDIA_TYPES.has(mediaType)) {
+    return true;
+  }
+  return mediaType.endsWith("+json") || mediaType.endsWith("+xml");
+}
+
+/**
+ * Decode an HTTP body into JSON, UTF-8 text, or a raw Buffer.
+ *
+ * Binary payloads (Google Drive `?alt=media`, images, PDFs) stay as bytes.
+ * JSON and text content types keep their existing parsed/string behavior.
+ */
+export function decodeOAuthResponseBytes(
+  raw: Uint8Array,
+  contentType: string,
+): unknown {
+  if (raw.byteLength === 0) {
+    return null;
+  }
+
+  const mediaType = mediaTypeOf(contentType);
+  let utf8: string | undefined;
+  try {
+    utf8 = new TextDecoder("utf-8", { fatal: true }).decode(raw);
+  } catch {
+    utf8 = undefined;
+  }
+
+  if (utf8 !== undefined) {
+    try {
+      return JSON.parse(utf8) as unknown;
+    } catch {
+      if (!mediaType || isTextMediaType(mediaType)) {
+        return utf8;
+      }
+    }
+  }
+
+  if (isTextMediaType(mediaType)) {
+    return new TextDecoder("utf-8").decode(raw);
+  }
+
+  return Buffer.from(raw);
+}
+
+export function isBinaryOAuthBody(body: unknown): body is Uint8Array {
+  return body instanceof Uint8Array;
+}
+
+/**
+ * JSON-safe form of an OAuth response body. Binary buffers become a base64
+ * string plus `bodyEncoding: "base64"` so CLI/HTTP JSON envelopes can round
+ * trip the original bytes.
+ */
+export function jsonSafeOAuthBody(body: unknown): {
+  body: unknown;
+  bodyEncoding?: "base64";
+} {
+  if (isBinaryOAuthBody(body)) {
+    return {
+      body: Buffer.from(body).toString("base64"),
+      bodyEncoding: "base64",
+    };
+  }
+  return { body };
+}
+
+/**
+ * Inverse of {@link jsonSafeOAuthBody}. Restores a `bodyEncoding: "base64"`
+ * envelope to a Buffer so callers can write the original bytes.
+ */
+export function decodeJsonSafeOAuthBody(envelope: {
+  body: unknown;
+  bodyEncoding?: string | null;
+}): unknown {
+  if (envelope.bodyEncoding === "base64") {
+    if (typeof envelope.body !== "string") {
+      throw new Error(
+        "OAuth response marked bodyEncoding=base64 but body is not a string",
+      );
+    }
+    return Buffer.from(envelope.body, "base64");
+  }
+  return envelope.body;
+}
+
+/**
+ * Bytes to write for a CLI `oauth request` body. Binary envelopes become
+ * raw bytes. Text stays UTF-8. Parsed JSON is pretty-printed. Null bodies
+ * produce no output.
+ */
+export function materializeOAuthRequestOutput(envelope: {
   body: unknown;
+  bodyEncoding?: string | null;
+}): { bytes: Buffer; isBinary: boolean } | null {
+  const decoded = decodeJsonSafeOAuthBody(envelope);
+  if (decoded == null) {
+    return null;
+  }
+  if (isBinaryOAuthBody(decoded)) {
+    return { bytes: Buffer.from(decoded), isBinary: true };
+  }
+  if (typeof decoded === "string") {
+    return { bytes: Buffer.from(decoded, "utf8"), isBinary: false };
+  }
+  return {
+    bytes: Buffer.from(JSON.stringify(decoded, null, 2), "utf8"),
+    isBinary: false,
+  };
 }
 
 export interface OAuthConnection {

package/src/oauth/platform-connection.test.ts

@@ -102,6 +102,40 @@ describe("PlatformOAuthConnection", () => {
     expect(result.body).toEqual(upstreamBody);
   });
 
+  test("decodes base64 binary proxy bodies into a Buffer", async () => {
+    const binary = Buffer.from([
+      0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0xff, 0xfe, 0x00,
+    ]);
+
+    const client = makeMockClient(
+      mock(async () => {
+        return new Response(
+          JSON.stringify({
+            status: 200,
+            headers: { "Content-Type": "application/octet-stream" },
+            body: binary.toString("base64"),
+            body_encoding: "base64",
+          }),
+          { status: 200 },
+        );
+      }) as unknown as typeof globalThis.fetch,
+    );
+
+    const conn = new PlatformOAuthConnection({
+      ...DEFAULT_OPTIONS,
+      client,
+    });
+    const result = await conn.request({
+      method: "GET",
+      path: "/drive/v3/files/file-123",
+      query: { alt: "media" },
+    });
+
+    expect(result.status).toBe(200);
+    expect(Buffer.isBuffer(result.body)).toBe(true);
+    expect(Buffer.from(result.body as Uint8Array).equals(binary)).toBe(true);
+  });
+
   test("forwards per-request baseUrl when provided", async () => {
     const client = makeMockClient(
       mock(async (_url: string | URL | Request, init?: RequestInit) => {

package/src/oauth/platform-connection.ts

@@ -82,6 +82,10 @@ export class PlatformOAuthConnection implements OAuthConnection {
   async request(req: OAuthConnectionRequest): Promise<OAuthConnectionResponse> {
     const proxyPath = `/v1/assistants/${this.client.platformAssistantId}/external-provider-proxy/${this.connectionId}/`;
 
+    // The envelope carries the caller's headers and body side by side. A
+    // string body is placed in the envelope as a string, so the proxy forwards
+    // those bytes verbatim under the caller's Content-Type; an object body
+    // travels as JSON and the proxy serializes it.
     const body: Record<string, unknown> = {
       request: {
         method: req.method,
@@ -143,13 +147,10 @@ export class PlatformOAuthConnection implements OAuthConnection {
         status: number;
         headers: Record<string, string>;
         body: unknown;
+        body_encoding?: string | null;
       };
 
-      return {
-        status: json.status,
-        headers: json.headers,
-        body: json.body,
-      };
+      return decodePlatformProxyEnvelope(json);
     }
 
     throw new BackendError("Platform proxy request failed after retries");
@@ -161,3 +162,25 @@ export class PlatformOAuthConnection implements OAuthConnection {
     );
   }
 }
+
+function decodePlatformProxyEnvelope(json: {
+  status: number;
+  headers: Record<string, string>;
+  body: unknown;
+  body_encoding?: string | null;
+}): OAuthConnectionResponse {
+  let body = json.body;
+  if (json.body_encoding === "base64") {
+    if (typeof body !== "string") {
+      throw new BackendError(
+        "Platform proxy returned body_encoding=base64 without a string body",
+      );
+    }
+    body = Buffer.from(body, "base64");
+  }
+  return {
+    status: json.status,
+    headers: json.headers ?? {},
+    body,
+  };
+}

package/src/oauth/seed-providers.ts

@@ -92,7 +92,7 @@ export const PROVIDER_SEED_DATA: Record<
     // base URL override (see GMAIL_API_BASE_URL) for their short paths.
     baseUrl: "https://www.googleapis.com",
     displayLabel: "Google",
-    description: "Gmail, Calendar, Drive, and Contacts",
+    description: "Gmail, Calendar, Drive, Docs, Sheets, Slides, and Contacts",
     dashboardUrl: "https://console.cloud.google.com/apis/credentials",
     clientIdPlaceholder: "123456789.apps.googleusercontent.com",
     logoUrl: "https://cdn.simpleicons.org/google",
@@ -137,6 +137,20 @@ export const PROVIDER_SEED_DATA: Record<
         headerName: "Authorization",
         valuePrefix: "Bearer ",
       },
+      // The Sheets and Slides APIs accept the auth/drive scope, so the
+      // existing token covers them; only the hosts need injection entries.
+      {
+        hostPattern: "sheets.googleapis.com",
+        injectionType: "header",
+        headerName: "Authorization",
+        valuePrefix: "Bearer ",
+      },
+      {
+        hostPattern: "slides.googleapis.com",
+        injectionType: "header",
+        headerName: "Authorization",
+        valuePrefix: "Bearer ",
+      },
       {
         hostPattern: "tasks.googleapis.com",
         injectionType: "header",

package/src/permissions/types.ts

@@ -1,3 +1,5 @@
+import type { ChannelConversationType } from "@vellumai/gateway-client";
+
 export type { AllowlistOption, ScopeOption } from "../tools/tool-types.js";
 export { RiskLevel } from "../tools/tool-types.js";
 
@@ -79,7 +81,7 @@ export interface PolicyContext {
    * Conversation type on the permission-matrix axis (dm | private | public),
    * for the channel-type tier of cell resolution.
    */
-  channelConversationType?: string;
+  channelConversationType?: ChannelConversationType;
   /**
    * Whether procedural-memory-as-skills is active for this assistant (memory-v3
    * is live). Precomputed in {@link buildPolicyContext} so the checker can gate

package/src/persistence/conversation-crud.ts

@@ -50,6 +50,10 @@ import {
   isRetryableSqliteError,
   withSqliteRetry,
 } from "../util/sqlite-retry.js";
+import {
+  purgeAllWatchTimelines,
+  purgeWatchTimelineForConversation,
+} from "../watch/watch-timeline.js";
 import {
   deleteOrphanAttachments,
   linkAttachmentToMessage,
@@ -191,6 +195,36 @@ function dedicatedTableExists(db: DrizzleDb, table: string): boolean {
  * keys on `conversation_id` regardless of event name, so this covers every
  * conversation-scoped pending event.
  */
+/**
+ * Remove a conversation's watch-session timeline: the narration, the screens,
+ * and the frames of them the entries carry.
+ *
+ * The rows are keyed by conversation id with no cascade behind them, so a
+ * delete that skipped them would keep pictures of the user's screen for a
+ * conversation they asked to remove. It runs after the row deletes, which is
+ * the order the watch store expects: once `conversations` no longer has the
+ * row, a later append is refused rather than left for a purge that has already
+ * been.
+ *
+ * Best-effort, like the rest of the post-transaction cleanup. The conversation
+ * row is already gone by this point, so throwing here would turn a completed
+ * delete into an error the caller cannot usefully retry. A swallowed failure
+ * is not the end of the story: `sweepOrphanedWatchTimelineEntries` runs from
+ * daemon startup and from database maintenance and deletes entries whose
+ * conversation no longer exists, so whatever this pass leaves behind is
+ * reclaimed on a later one.
+ */
+function purgeWatchTimelineForDeletedConversation(id: string): void {
+  try {
+    purgeWatchTimelineForConversation(id);
+  } catch (err) {
+    log.warn(
+      { err, conversationId: id },
+      "Failed to purge the watch timeline for a deleted conversation",
+    );
+  }
+}
+
 function deletePendingTelemetryEventsForConversation(id: string): void {
   const telemetry = getTelemetryDb({ createIfMissing: false });
   if (!telemetry || !dedicatedTableExists(telemetry, "telemetry_events")) {
@@ -2109,6 +2143,8 @@ export function deleteConversation(id: string): DeletedMemoryIds {
     removeConversationDir(id, createdAtForDiskCleanup);
   }
 
+  purgeWatchTimelineForDeletedConversation(id);
+
   // Notify `conversation-deleted` hooks (e.g. the memory plugin failing its
   // still-pending jobs for this conversation). Fire-and-forget from this
   // synchronous primitive — the pipeline contains per-hook failures, and
@@ -2259,6 +2295,8 @@ export async function deleteConversationGently(
     removeConversationDir(id, createdAtForDiskCleanup);
   }
 
+  purgeWatchTimelineForDeletedConversation(id);
+
   // Notify `conversation-deleted` hooks — fire-and-forget, same contract as
   // the synchronous delete primitive.
   void runHook(HOOKS.CONVERSATION_DELETED, {
@@ -3588,6 +3626,14 @@ export async function clearAll(): Promise<{
   // cascade; wipe them explicitly so labels/objectives don't survive (or
   // rehydrate after) a clear-all.
   await runOrThrow("DELETE FROM subagents");
+  // Watch-session timelines are conversation-keyed rows the cascade does not
+  // reach. They come after `conversations` so this statement is the last thing
+  // that needs to reach one: an append arriving from here on finds no
+  // conversation to key itself to and is refused, and an append that already
+  // ran is a row this deletes. The bulk deletes above run in a sqlite3
+  // subprocess, so the event loop is free while they work; this one is a
+  // synchronous in-process statement, which nothing can interleave with.
+  purgeAllWatchTimelines();
 
   // The memory feature's relocated conversation-keyed tables lost their main-DB
   // cascade. Signal the wipe through the hook rather than reaching into the

package/src/persistence/conversation-types.ts

@@ -228,21 +228,22 @@ export function isVoiceSessionUserMessage(
 }
 
 /**
- * True when the row that opened the turn was sent from the macOS app, on that
+ * True when the row that opened the turn was sent from a desktop app, on that
  * row's own evidence.
  *
  * Two markers, both required. The `client` bag's `os` entry is the only
  * per-platform attribution on a message: `userMessageInterface` is `"web"` for
- * the macOS app, the iOS app, and a desktop browser alike. `clientOsFromRequest`
- * says that `os` was reported by this row's request or transport rather than
- * inherited from the conversation's live client state, which names the surface
- * of an earlier turn: a button tapped on the phone against a conversation last
- * sent to from the Mac persists `os: "macos"` with no marker.
+ * the desktop apps, the iOS app, and a desktop browser alike.
+ * `clientOsFromRequest` says that `os` was reported by this row's request or
+ * transport rather than inherited from the conversation's live client state,
+ * which names the surface of an earlier turn. A button tapped on the phone
+ * against a conversation last sent to from desktop persists the old OS with no
+ * marker.
  *
  * Origin a row did not report itself is origin unknown. Callers gate
- * suppression on this, so unknown has to read as not-macOS.
+ * suppression on this, so unknown has to read as not-desktop.
  */
-export function isMacOriginatedUserMessage(
+export function isDesktopOriginatedUserMessage(
   metadata: Record<string, unknown> | undefined,
 ): boolean {
   if (metadata?.clientOsFromRequest !== true) {
@@ -252,7 +253,8 @@ export function isMacOriginatedUserMessage(
   if (typeof client !== "object" || client === null) {
     return false;
   }
-  return parseClientOs((client as Record<string, unknown>).os) === "macos";
+  const clientOs = parseClientOs((client as Record<string, unknown>).os);
+  return clientOs === "macos" || clientOs === "windows";
 }
 
 /**

package/src/persistence/db-async-query.ts

@@ -216,6 +216,7 @@ async function runViaCli(
   // never an issue regardless of the statement complexity.
   const proc = Bun.spawn({
     cmd: [sqlite3Path, dbPath],
+    windowsHide: true,
     stdin: "pipe",
     stdout: "pipe",
     stderr: "pipe",
@@ -396,7 +397,7 @@ export function spawnDetachedWalCheckpoint(): boolean {
         getDbPath(),
         `PRAGMA busy_timeout=${SQLITE_BUSY_TIMEOUT_MS}; PRAGMA wal_checkpoint(TRUNCATE);`,
       ],
-      { detached: true, stdio: "ignore" },
+      { detached: true, stdio: "ignore", windowsHide: true },
     );
     // A post-spawn failure can't be acted on — the daemon is exiting — but an
     // unlistened ChildProcess "error" event would throw as an uncaught

package/src/persistence/db-maintenance.ts

@@ -3,6 +3,7 @@ import { statSync } from "node:fs";
 import { getConfig } from "../config/loader.js";
 import { getLogger } from "../util/logger.js";
 import { getDbPath } from "../util/platform.js";
+import { sweepOrphanedWatchTimelineEntries } from "../watch/watch-timeline.js";
 import { pruneRuns } from "../workflows/journal-store.js";
 import { getMemoryCheckpoint, setMemoryCheckpoint } from "./checkpoints.js";
 import { getLastInteractiveUserMessageTimestamp } from "./conversation-crud.js";
@@ -81,6 +82,20 @@ async function runDbMaintenance(): Promise<void> {
     log.warn({ err }, "Workflow run pruning failed (non-fatal)");
   }
 
+  // Reclaim watch-timeline entries whose conversation is gone. Their purge runs
+  // after the conversation row is already deleted and cannot be retried by the
+  // caller, and nothing cascades into the table, so a failed purge or a crash
+  // between the two writes would otherwise keep screenshots of the user's
+  // screen indefinitely. Bounded per pass and best-effort inside the sweep,
+  // which reports zero rather than throwing, so it needs no guard here.
+  const sweptWatchEntries = sweepOrphanedWatchTimelineEntries();
+  if (sweptWatchEntries > 0) {
+    log.info(
+      { sweptWatchEntries },
+      "Swept watch timeline entries for deleted conversations",
+    );
+  }
+
   // Refresh the query planner's statistics (see PLANNER_OPTIMIZE_PRAGMA for
   // what the mask buys here). Routed through the async path to keep it off the
   // main thread when the sqlite3 CLI backend is available.

package/src/persistence/embeddings/qdrant-manager.ts

@@ -154,6 +154,7 @@ export class QdrantManager {
 
     const proc = Bun.spawn({
       cmd: [spawnPath],
+      windowsHide: true,
       env: {
         ...process.env,
         QDRANT__SERVICE__HOST: this.host,

package/src/persistence/migrations/367-create-watch-timeline-entries.ts

@@ -0,0 +1,46 @@
+import { type DrizzleDb, getSqliteFrom } from "../db-connection.js";
+
+/**
+ * Creates `watch_timeline_entries`: the per-session record of what a watch
+ * session's user narrated and what was on their screen.
+ *
+ * The table is the timeline's only home. Entries live outside conversation
+ * message history, so nothing here participates in turn alternation or
+ * provider-facing sanitization, and only the retrospective's rendered summary
+ * reaches a model.
+ *
+ * `screenshot_attachment_id` holds the id of a row in `attachments`, so the
+ * pixels stay on disk behind the attachment store rather than in this table.
+ * Timeline rows and the screenshots they own are removed together by the
+ * watch store's purge.
+ *
+ * The two indexes cover the two access paths: reads are scoped to one session
+ * and ordered by offset, and purges are scoped to one conversation.
+ *
+ * Idempotent: `IF NOT EXISTS` on the table and both indexes.
+ */
+export function migrateCreateWatchTimelineEntries(db: DrizzleDb): void {
+  const raw = getSqliteFrom(db);
+
+  raw.exec(/*sql*/ `
+    CREATE TABLE IF NOT EXISTS watch_timeline_entries (
+      id                       TEXT PRIMARY KEY,
+      session_id               TEXT NOT NULL,
+      conversation_id          TEXT NOT NULL,
+      at_ms                    INTEGER NOT NULL,
+      kind                     TEXT NOT NULL,
+      text                     TEXT NOT NULL,
+      ax_tree                  TEXT,
+      ax_diff                  TEXT,
+      screenshot_attachment_id TEXT,
+      created_at               INTEGER NOT NULL
+    )
+  `);
+
+  raw.exec(
+    `CREATE INDEX IF NOT EXISTS idx_watch_timeline_entries_session ON watch_timeline_entries(session_id, at_ms)`,
+  );
+  raw.exec(
+    `CREATE INDEX IF NOT EXISTS idx_watch_timeline_entries_conversation ON watch_timeline_entries(conversation_id)`,
+  );
+}

package/src/persistence/migrations/368-watch-timeline-screenshot-blob.ts

@@ -0,0 +1,33 @@
+import type { DrizzleDb } from "../db-connection.js";
+import { tableHasColumn } from "./schema-introspection.js";
+
+/**
+ * Move a watch timeline entry's screenshot into the row that owns it.
+ *
+ * `screenshot` holds the frame's JPEG bytes directly, so an entry is one row
+ * with one lifetime: a single `DELETE` takes the narration, the screen, and
+ * the pixels together, with nothing staged elsewhere to coordinate against.
+ * `screenshot_attachment_id`, the id of a separately staged file, goes with
+ * it.
+ *
+ * Idempotent: each `ALTER TABLE` is guarded by a column check, so a crash
+ * between the two leaves the next boot able to finish the job.
+ */
+export function migrateWatchTimelineScreenshotBlob(database: DrizzleDb): void {
+  if (!tableHasColumn(database, "watch_timeline_entries", "screenshot")) {
+    database.run(
+      /*sql*/ `ALTER TABLE watch_timeline_entries ADD COLUMN screenshot BLOB`,
+    );
+  }
+  if (
+    tableHasColumn(
+      database,
+      "watch_timeline_entries",
+      "screenshot_attachment_id",
+    )
+  ) {
+    database.run(
+      /*sql*/ `ALTER TABLE watch_timeline_entries DROP COLUMN screenshot_attachment_id`,
+    );
+  }
+}