@vellumai/assistant 0.11.1 → 0.11.2-staging.2

package/src/daemon/message-types/conversations.ts

@@ -38,6 +38,14 @@ interface BaseTransportMetadata {
    * inference, which keys off `interfaceId`.
    */
   clientOs?: string;
+  /**
+   * Id of the app the client currently has open on screen (the app viewer or
+   * the app-editing split). Rendered as the `visible_app:` line in the per-turn
+   * context so the assistant knows which app "the app" refers to without the
+   * user naming it. View state only: it never affects transport or tool
+   * gating, and is absent whenever no app is in view.
+   */
+  visibleAppId?: string;
 }
 
 /**

package/src/daemon/message-types/surfaces.ts

@@ -21,6 +21,7 @@ import type {
   SurfaceDataByType,
   SurfaceType,
   TableSurfaceData,
+  VisualSurfaceData,
   WorkResultSurfaceData,
 } from "../../api/surfaces.js";
 
@@ -52,6 +53,7 @@ export {
   type TableColumn,
   type TableRow,
   TableSurfaceDataSchema,
+  VisualSurfaceDataSchema,
   type WorkResultDiff,
   type WorkResultItem,
   type WorkResultMetadata,
@@ -78,6 +80,7 @@ export type {
   SurfaceDataByType,
   SurfaceType,
   TableSurfaceData,
+  VisualSurfaceData,
   WorkResultSurfaceData,
 };
 

package/src/documents/document-store.ts

@@ -6,6 +6,7 @@
  * without going through the HTTP layer.
  */
 import { rawAll, rawGet, rawRun } from "../persistence/raw-query.js";
+import { writeWorkspaceFile } from "../runtime/routes/workspace-utils.js";
 import { getLogger } from "../util/logger.js";
 
 const log = getLogger("document-store");
@@ -23,6 +24,22 @@ export interface DocumentRecord {
   wordCount: number;
   createdAt: number;
   updatedAt: number;
+  /**
+   * Workspace-relative path of the markdown file this document is bound to,
+   * or `null` when the document has no file behind it.
+   */
+  workspacePath: string | null;
+}
+
+/**
+ * The listing projection: neither the body nor the file binding, which the
+ * list and search queries deliberately leave out of their SELECTs.
+ */
+export type DocumentSummary = Omit<DocumentRecord, "content" | "workspacePath">;
+
+/** Words in a markdown body, the count the `word_count` column stores. */
+function countWords(content: string): number {
+  return content.split(/\s+/).filter((word) => word.length > 0).length;
 }
 
 // ---------------------------------------------------------------------------
@@ -55,9 +72,10 @@ interface DocumentRow {
   word_count: number;
   created_at: number;
   updated_at: number;
+  workspace_path: string | null;
 }
 
-type DocumentListRow = Omit<DocumentRow, "content">;
+type DocumentListRow = Omit<DocumentRow, "content" | "workspace_path">;
 
 function escapeSqlLikePattern(value: string): string {
   return value.replace(/[\\%_]/g, "\\$&");
@@ -72,6 +90,7 @@ function mapRowToRecord(row: DocumentRow): DocumentRecord {
     wordCount: row.word_count,
     createdAt: row.created_at,
     updatedAt: row.updated_at,
+    workspacePath: row.workspace_path,
   };
 }
 
@@ -80,7 +99,7 @@ export function getDocumentById(surfaceId: string): DocumentRecord | null {
   try {
     const row = rawGet<DocumentRow>(
       "documents:getDocumentById",
-      /*sql*/ `SELECT surface_id, conversation_id, title, content, word_count, created_at, updated_at
+      /*sql*/ `SELECT surface_id, conversation_id, title, content, word_count, created_at, updated_at, workspace_path
        FROM documents
        WHERE surface_id = ?`,
       surfaceId,
@@ -99,6 +118,29 @@ export function getDocumentById(surfaceId: string): DocumentRecord | null {
   }
 }
 
+/**
+ * Look up the document bound to a workspace file. `workspacePath` must be the
+ * normalized workspace-relative path stored on the row. Returns `null` when no
+ * document is bound to that file.
+ */
+export function getDocumentByWorkspacePath(
+  workspacePath: string,
+): DocumentRecord | null {
+  try {
+    const row = rawGet<DocumentRow>(
+      "documents:getDocumentByWorkspacePath",
+      /*sql*/ `SELECT surface_id, conversation_id, title, content, word_count, created_at, updated_at, workspace_path
+       FROM documents
+       WHERE workspace_path = ?`,
+      workspacePath,
+    );
+    return row ? mapRowToRecord(row) : null;
+  } catch (error) {
+    log.error({ err: error, workspacePath }, "Load-by-workspace-path error");
+    return null;
+  }
+}
+
 /** Return true when a document is associated with a conversation. */
 export function isDocumentAssociatedWithConversation(
   surfaceId: string,
@@ -132,7 +174,7 @@ export function isDocumentAssociatedWithConversation(
  */
 export function getDocumentsForConversation(
   conversationId: string,
-): Omit<DocumentRecord, "content">[] {
+): DocumentSummary[] {
   try {
     const rows = rawAll<DocumentListRow>(
       "documents:getDocumentsForConversation",
@@ -174,7 +216,7 @@ export function getDocumentsForConversation(
 export function searchDocumentsByTitle(
   query: string,
   options: { conversationId?: string } = {},
-): Omit<DocumentRecord, "content">[] {
+): DocumentSummary[] {
   try {
     const pattern = `%${escapeSqlLikePattern(query)}%`;
     const rows = options.conversationId
@@ -387,6 +429,202 @@ export function findInDocument(
   }
 }
 
+// ---------------------------------------------------------------------------
+// Workspace file binding
+// ---------------------------------------------------------------------------
+
+/**
+ * Mirror `content` onto the workspace file a document is bound to.
+ *
+ * This is the single write-through choke point: every path that persists
+ * document content — {@link saveDocument} (client save and `document_create`),
+ * {@link updateDocumentContent} (`document_update`), and
+ * {@link replaceInDocument} (`document_replace_text`) — calls it immediately
+ * before its own row write, so a file-backed document's markdown on disk always
+ * matches the stored row.
+ *
+ * The file is written first and a failure throws: a rejected write aborts the
+ * update before the row changes rather than leaving the two silently diverged.
+ * Documents with no file behind them are a no-op.
+ */
+function writeThroughToWorkspaceFile(surfaceId: string, content: string): void {
+  const row = rawGet<{ workspace_path: string | null }>(
+    "documents:writeThroughToWorkspaceFile:getPath",
+    /*sql*/ `SELECT workspace_path FROM documents WHERE surface_id = ?`,
+    surfaceId,
+  );
+  const workspacePath = row?.workspace_path;
+  if (!workspacePath) {
+    return;
+  }
+
+  try {
+    writeWorkspaceFile(workspacePath, Buffer.from(content, "utf-8"));
+    log.info({ surfaceId, workspacePath }, "Wrote document through to file");
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Failed to write file-backed document to ${workspacePath}: ${message}`,
+    );
+  }
+}
+
+/**
+ * Create a document seeded from a workspace markdown file and bind it to that
+ * file. The returned surface ID is the file's document identity — comments,
+ * assistant iteration, and PDF export all key off it.
+ *
+ * The partial unique index on `workspace_path` makes a concurrent second
+ * create fail rather than produce a duplicate binding; callers re-read by path
+ * on failure.
+ */
+export function createFileBackedDocument(params: {
+  surfaceId: string;
+  conversationId: string;
+  title: string;
+  content: string;
+  workspacePath: string;
+}): { success: true } | { success: false; error: string } {
+  try {
+    const now = Date.now();
+    rawRun(
+      "documents:createFileBackedDocument",
+      /*sql*/ `INSERT INTO documents (surface_id, conversation_id, title, content, word_count, created_at, updated_at, workspace_path)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+      params.surfaceId,
+      params.conversationId,
+      params.title,
+      params.content,
+      countWords(params.content),
+      now,
+      now,
+      params.workspacePath,
+    );
+    addDocumentConversation(params.surfaceId, params.conversationId);
+    log.info(
+      { surfaceId: params.surfaceId, workspacePath: params.workspacePath },
+      "Created file-backed document",
+    );
+    return { success: true };
+  } catch (error) {
+    log.error(
+      { err: error, workspacePath: params.workspacePath },
+      "File-backed document create error",
+    );
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : "Unknown error",
+    };
+  }
+}
+
+/**
+ * Move file-backed documents onto the path a workspace rename moved their file
+ * to. `oldPath` and `newPath` are canonical workspace-relative paths, the same
+ * form {@link createFileBackedDocument} stores.
+ *
+ * A document bound to `oldPath` itself moves, and so does every document nested
+ * under it (`oldPath + "/"` prefix), which is what a directory rename produces.
+ *
+ * The rename on disk has already happened by the time this runs, so it is best
+ * effort and never throws: the caller has no way to undo the rename, and a
+ * document left on a stale path is recoverable while a failed rename response
+ * is not. Rows move one statement at a time so a single row that cannot move
+ * does not strand its siblings.
+ *
+ * A row whose destination is already taken by another binding is one such case:
+ * the partial unique index on `workspace_path` rejects the update, and the
+ * losing row keeps pointing at the old path. That is deliberate. Overwriting
+ * the winner would drop a binding that a client may have open, whereas the
+ * stale binding self-heals: opening the file refreshes the row's content from
+ * disk, and a document whose file is gone is reported as gone rather than
+ * rewritten from the row.
+ */
+export function rebindDocumentsToRenamedPath(params: {
+  oldPath: string;
+  newPath: string;
+}): void {
+  const { oldPath, newPath } = params;
+  if (!oldPath || !newPath || oldPath === newPath) {
+    return;
+  }
+
+  try {
+    const rows = rawAll<{ surface_id: string; workspace_path: string }>(
+      "documents:rebindRenamedPath:select",
+      /*sql*/ `SELECT surface_id, workspace_path
+       FROM documents
+       WHERE workspace_path = ? OR workspace_path LIKE ? ESCAPE '\\'`,
+      oldPath,
+      `${escapeSqlLikePattern(oldPath)}/%`,
+    );
+
+    for (const row of rows) {
+      const rebound =
+        row.workspace_path === oldPath
+          ? newPath
+          : newPath + row.workspace_path.slice(oldPath.length);
+      try {
+        rawRun(
+          "documents:rebindRenamedPath:update",
+          /*sql*/ `UPDATE documents SET workspace_path = ? WHERE surface_id = ?`,
+          rebound,
+          row.surface_id,
+        );
+        log.info(
+          {
+            surfaceId: row.surface_id,
+            from: row.workspace_path,
+            to: rebound,
+          },
+          "Rebound file-backed document to renamed path",
+        );
+      } catch (error) {
+        log.warn(
+          {
+            err: error,
+            surfaceId: row.surface_id,
+            from: row.workspace_path,
+            to: rebound,
+          },
+          "Left file-backed document on its old path after a rename",
+        );
+      }
+    }
+  } catch (error) {
+    log.error({ err: error, oldPath, newPath }, "Path rebind error");
+  }
+}
+
+/**
+ * Replace a document's stored content with the current text of the file it is
+ * bound to. The file is the source of truth when a document is opened, so this
+ * deliberately skips the write-through step — disk and row already agree.
+ */
+export function refreshDocumentContentFromFile(
+  surfaceId: string,
+  content: string,
+): { success: true } | { success: false; error: string } {
+  try {
+    rawRun(
+      "documents:refreshDocumentContentFromFile",
+      /*sql*/ `UPDATE documents SET content = ?, word_count = ?, updated_at = ? WHERE surface_id = ?`,
+      content,
+      countWords(content),
+      Date.now(),
+      surfaceId,
+    );
+    log.info({ surfaceId }, "Refreshed document content from file");
+    return { success: true };
+  } catch (error) {
+    log.error({ err: error, surfaceId }, "Document refresh error");
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : "Unknown error",
+    };
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Document persistence
 // ---------------------------------------------------------------------------
@@ -399,6 +637,7 @@ export function saveDocument(params: {
   wordCount: number;
 }): { success: true; surfaceId: string } | { success: false; error: string } {
   try {
+    writeThroughToWorkspaceFile(params.surfaceId, params.content);
     const now = Date.now();
     rawRun(
       "documents:saveDocument",
@@ -534,9 +773,8 @@ export function replaceInDocument(
       replacementsMade = totalMatches;
     }
 
-    const wordCount = newContent
-      .split(/\s+/)
-      .filter((w) => w.length > 0).length;
+    writeThroughToWorkspaceFile(surfaceId, newContent);
+    const wordCount = countWords(newContent);
     rawRun(
       "documents:replaceInDocument:update",
       /*sql*/ `UPDATE documents SET content = ?, word_count = ?, updated_at = ? WHERE surface_id = ?`,
@@ -579,9 +817,8 @@ export function updateDocumentContent(
     const sep = mode === "append" && existing.content.length > 0 ? "\n\n" : "";
     const newContent =
       mode === "append" ? existing.content + sep + markdown : markdown;
-    const wordCount = newContent
-      .split(/\s+/)
-      .filter((w) => w.length > 0).length;
+    writeThroughToWorkspaceFile(surfaceId, newContent);
+    const wordCount = countWords(newContent);
     rawRun(
       "documents:updateDocumentContent:update",
       /*sql*/ `UPDATE documents SET content = ?, word_count = ?, updated_at = ? WHERE surface_id = ?`,

package/src/home/__tests__/feed-types.test.ts

@@ -257,14 +257,49 @@ describe("parseFeedFile", () => {
     ).toThrow();
   });
 
-  test("throws when an item in the file is invalid", () => {
-    expect(() =>
-      parseFeedFile({
-        version: 2,
-        items: [{ ...minimalNotification(), priority: 999 }],
-        updatedAt: NOW_ISO,
-      }),
-    ).toThrow();
+  test("throws when `items` is missing entirely", () => {
+    expect(() => parseFeedFile({ version: 2, updatedAt: NOW_ISO })).toThrow();
+  });
+
+  test("throws when `updatedAt` is missing", () => {
+    expect(() => parseFeedFile({ version: 2, items: [] })).toThrow();
+  });
+
+  test("drops an invalid item but keeps the valid ones", () => {
+    const parsed = parseFeedFile({
+      version: 2,
+      items: [
+        minimalNotification(),
+        { ...minimalNotification(), id: "notif-bad", priority: 999 },
+      ],
+      updatedAt: NOW_ISO,
+    });
+    expect(parsed.items).toHaveLength(1);
+    expect(parsed.items[0]?.id).toBe("notif-1");
+    expect(parsed.droppedCount).toBe(1);
+    expect(parsed.updatedAt).toBe(NOW_ISO);
+  });
+
+  test("reports droppedCount 0 for a fully valid file", () => {
+    const parsed = parseFeedFile({
+      version: 2,
+      items: [minimalNotification(), notificationWithActions()],
+      updatedAt: NOW_ISO,
+    });
+    expect(parsed.items).toHaveLength(2);
+    expect(parsed.droppedCount).toBe(0);
+  });
+
+  test("returns an empty item list when every item is invalid", () => {
+    const parsed = parseFeedFile({
+      version: 2,
+      items: [{ ...minimalNotification(), type: "banner" }, null, "nope"],
+      updatedAt: NOW_ISO,
+    });
+    expect(parsed.items).toEqual([]);
+    expect(parsed.droppedCount).toBe(3);
+    expect(parsed.version).toBe(2);
+    expect(parsed.updatedAt).toBe(NOW_ISO);
   });
 
   test("accepts a file with a noteworthy item", () => {

package/src/home/__tests__/feed-writer.test.ts

@@ -50,6 +50,7 @@ const {
   bulkSetFeedItemStatus,
   clearAllConversationIds,
   getHomeFeedPath,
+  patchFeedItemContent,
   patchFeedItemStatus,
   readHomeFeed,
   stripConversationIds,
@@ -199,6 +200,23 @@ describe("feed-writer", () => {
       const feed = readHomeFeed();
       expect(feed.items).toEqual([]);
     });
+
+    test("keeps the valid items when a single row is malformed", () => {
+      mkdirSync(join(workspaceDir, "data"), { recursive: true });
+      const file = {
+        version: 2,
+        updatedAt: "2026-04-14T12:00:00.000Z",
+        items: [
+          makeItem({ id: "good" }),
+          { ...makeItem({ id: "bad" }), priority: 999 },
+        ],
+      };
+      writeFileSync(getHomeFeedPath(), JSON.stringify(file, null, 2), "utf-8");
+
+      const feed = readHomeFeed();
+      expect(feed.items).toHaveLength(1);
+      expect(feed.items[0]!.id).toBe("good");
+    });
   });
 
   describe("appendFeedItem", () => {
@@ -406,6 +424,47 @@ describe("feed-writer", () => {
     });
   });
 
+  describe("patchFeedItemContent", () => {
+    test("trims and applies a non-empty title", async () => {
+      await appendFeedItem(makeItem({ id: "item-1", title: "Original" }));
+
+      const result = await patchFeedItemContent("item-1", {
+        title: "  Renamed  ",
+      });
+
+      expect(result!.title).toBe("Renamed");
+      expect(readFileJson().items[0]!.title).toBe("Renamed");
+    });
+
+    test("ignores an empty or whitespace-only title instead of clearing it", async () => {
+      await appendFeedItem(makeItem({ id: "item-1", title: "Original" }));
+
+      const empty = await patchFeedItemContent("item-1", { title: "" });
+      expect(empty!.title).toBe("Original");
+
+      const blank = await patchFeedItemContent("item-1", { title: "   \t" });
+      expect(blank!.title).toBe("Original");
+
+      expect(readFileJson().items[0]!.title).toBe("Original");
+    });
+
+    test("a summary-only patch leaves the title untouched", async () => {
+      await appendFeedItem(makeItem({ id: "item-1", title: "Original" }));
+
+      const result = await patchFeedItemContent("item-1", {
+        summary: "Fresh summary",
+      });
+
+      expect(result!.title).toBe("Original");
+      expect(result!.summary).toBe("Fresh summary");
+    });
+
+    test("returns null for an unknown id", async () => {
+      await appendFeedItem(makeItem({ id: "known" }));
+      expect(await patchFeedItemContent("unknown", { title: "x" })).toBeNull();
+    });
+  });
+
   describe("concurrency", () => {
     test("10 concurrent appends with distinct ids all land", async () => {
       const items = Array.from({ length: 10 }, (_, i) =>

package/src/home/feed-types.ts

@@ -55,10 +55,13 @@ export interface HomeFeedFile {
   updatedAt: string;
 }
 
-/** Schema for the on-disk `home-feed.json` file. */
-const homeFeedFileSchema = z.object({
+/**
+ * Envelope schema for the on-disk `home-feed.json` file. Items stay
+ * unvalidated here so `parseFeedFile` can validate them one at a time.
+ */
+const homeFeedEnvelopeSchema = z.object({
   version: z.literal(2),
-  items: z.array(FeedItemSchema),
+  items: z.array(z.unknown()),
   updatedAt: z.string(),
 });
 
@@ -66,9 +69,33 @@ const homeFeedFileSchema = z.object({
  * Parse and validate a raw value read from `home-feed.json`.
  *
  * Used by the writer on read-back and by the HTTP route when serving the
- * feed. Throws a `ZodError` on any validation failure — callers are
- * expected to log + recover (e.g. treat the file as empty).
+ * feed. Throws a `ZodError` when the envelope itself is invalid (wrong
+ * `version`, non-object input, missing `updatedAt`). Callers are
+ * expected to log + recover (e.g. treat the file as empty). Individual
+ * items that fail validation are dropped and counted in `droppedCount`,
+ * an in-memory-only field on the return value that is never persisted,
+ * so one malformed row cannot erase the rest of the feed.
  */
-export function parseFeedFile(raw: unknown): HomeFeedFile {
-  return homeFeedFileSchema.parse(raw) as HomeFeedFile;
+export function parseFeedFile(
+  raw: unknown,
+): HomeFeedFile & { droppedCount: number } {
+  const envelope = homeFeedEnvelopeSchema.parse(raw);
+
+  const items: z.infer<typeof FeedItemSchema>[] = [];
+  let droppedCount = 0;
+  for (const rawItem of envelope.items) {
+    const result = FeedItemSchema.safeParse(rawItem);
+    if (result.success) {
+      items.push(result.data);
+    } else {
+      droppedCount++;
+    }
+  }
+
+  return {
+    version: envelope.version,
+    items,
+    updatedAt: envelope.updatedAt,
+    droppedCount,
+  };
 }

package/src/home/feed-writer.ts

@@ -68,7 +68,9 @@ export function getHomeFeedPath(): string {
  * Read the on-disk feed file, applying the stateless TTL filter.
  *
  * Returns an empty `HomeFeedFile` when the file is missing, unreadable,
- * or fails Zod validation — callers never see a throw from this path.
+ * or has an invalid envelope. Callers never see a throw from this path.
+ * Individual items that fail validation are dropped and warn-logged
+ * while the rest of the feed survives.
  * Items whose `expiresAt` is in the past are dropped from the returned
  * `items` array but are NOT rewritten to disk; the next append cycle
  * will persist the post-filter view naturally.
@@ -93,7 +95,7 @@ export function readHomeFeed(): HomeFeedFile {
     return empty;
   }
 
-  let parsed: HomeFeedFile;
+  let parsed: ReturnType<typeof parseFeedFile>;
   try {
     parsed = parseFeedFile(raw);
   } catch (err) {
@@ -104,6 +106,13 @@ export function readHomeFeed(): HomeFeedFile {
     return empty;
   }
 
+  if (parsed.droppedCount > 0) {
+    log.warn(
+      { path, droppedCount: parsed.droppedCount },
+      "Dropped invalid items from home-feed.json",
+    );
+  }
+
   const now = Date.now();
   const items = parsed.items.filter((item) => !isExpired(item, now));
   return {
@@ -165,7 +174,8 @@ export async function patchFeedItemStatus(
  *
  * Only fields explicitly present on `patch` are touched. Pass an empty
  * object and the call is a no-op that returns the existing item (or
- * `null` if the id isn't on disk).
+ * `null` if the id isn't on disk). A `title` that trims to empty is
+ * ignored, so no edit path can strip a title off an existing item.
  */
 export interface FeedItemContentPatch {
   title?: string;
@@ -363,9 +373,8 @@ async function runWrite(): Promise<void> {
     const updated: FeedItem = { ...existing };
     if (patch.title !== undefined) {
       const trimmed = patch.title.trim();
-      if (trimmed.length === 0) {
-        delete updated.title;
-      } else {
+      // Blank titles are ignored: an item keeps its title once it has one.
+      if (trimmed.length > 0) {
         updated.title = trimmed;
       }
     }