@vellumai/assistant 0.8.2 → 0.8.4

package/src/documents/document-store.ts

@@ -240,6 +240,99 @@ export function deleteDocument(surfaceId: string): boolean {
   }
 }
 
+// ---------------------------------------------------------------------------
+// In-document search (grep)
+// ---------------------------------------------------------------------------
+
+export interface FindMatch {
+  lineNumber: number;
+  lineContent: string;
+  matchStart: number;
+  matchEnd: number;
+  matchText: string;
+}
+
+export interface FindResult {
+  surfaceId: string;
+  totalMatches: number;
+  matches: FindMatch[];
+}
+
+const MAX_FIND_MATCHES = 50;
+
+/**
+ * Search for text or a regex pattern within a document's content.
+ * Returns matching lines with line numbers and match positions.
+ * Results are capped at {@link MAX_FIND_MATCHES} to avoid oversized responses.
+ */
+export function findInDocument(
+  surfaceId: string,
+  query: string,
+  options: { regex?: boolean; caseSensitive?: boolean } = {},
+): FindResult | null {
+  try {
+    const row = rawGet<{ content: string }>(
+      /*sql*/ `SELECT content FROM documents WHERE surface_id = ?`,
+      surfaceId,
+    );
+    if (!row) return null;
+
+    const lines = row.content.split("\n");
+    const matches: FindMatch[] = [];
+    let uncappedTotal = 0;
+
+    if (options.regex) {
+      const flags = options.caseSensitive ? "g" : "gi";
+      const re = new RegExp(query, flags);
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        re.lastIndex = 0;
+        let m: RegExpExecArray | null;
+        while ((m = re.exec(line)) !== null) {
+          uncappedTotal++;
+          if (matches.length < MAX_FIND_MATCHES) {
+            matches.push({
+              lineNumber: i + 1,
+              lineContent: line,
+              matchStart: m.index,
+              matchEnd: m.index + m[0].length,
+              matchText: m[0],
+            });
+          }
+          if (m[0].length === 0) re.lastIndex++;
+        }
+      }
+    } else {
+      const needle = options.caseSensitive ? query : query.toLowerCase();
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const haystack = options.caseSensitive ? line : line.toLowerCase();
+        let startPos = 0;
+        while (startPos <= haystack.length) {
+          const idx = haystack.indexOf(needle, startPos);
+          if (idx === -1) break;
+          uncappedTotal++;
+          if (matches.length < MAX_FIND_MATCHES) {
+            matches.push({
+              lineNumber: i + 1,
+              lineContent: line,
+              matchStart: idx,
+              matchEnd: idx + needle.length,
+              matchText: line.slice(idx, idx + needle.length),
+            });
+          }
+          startPos = idx + Math.max(needle.length, 1);
+        }
+      }
+    }
+
+    return { surfaceId, totalMatches: uncappedTotal, matches };
+  } catch (error) {
+    log.error({ err: error, surfaceId }, "Find-in-document error");
+    return null;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Document persistence
 // ---------------------------------------------------------------------------
@@ -297,6 +390,115 @@ export function saveDocument(params: {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Find-and-replace
+// ---------------------------------------------------------------------------
+
+export interface ReplaceInDocumentOptions {
+  regex?: boolean;
+  caseSensitive?: boolean;
+  maxReplacements?: number;
+}
+
+export type ReplaceInDocumentResult =
+  | { success: true; replacements_made: number; content_changed: boolean }
+  | { success: false; error: string };
+
+function escapeRegExpChars(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Find and replace text within a document — like sed.
+ * Supports literal text and regex patterns with optional backreferences.
+ */
+export function replaceInDocument(
+  surfaceId: string,
+  find: string,
+  replace: string,
+  options: ReplaceInDocumentOptions = {},
+): ReplaceInDocumentResult {
+  try {
+    const row = rawGet<{ content: string }>(
+      /*sql*/ `SELECT content FROM documents WHERE surface_id = ?`,
+      surfaceId,
+    );
+    if (!row) {
+      return { success: false, error: "Document not found" };
+    }
+
+    const flags = "g" + (options.caseSensitive === true ? "" : "i");
+    const pattern = options.regex
+      ? new RegExp(find, flags)
+      : new RegExp(escapeRegExpChars(find), flags);
+
+    const totalMatches = [...row.content.matchAll(pattern)].length;
+    if (
+      totalMatches === 0 ||
+      (options.maxReplacements != null && options.maxReplacements <= 0)
+    ) {
+      return { success: true, replacements_made: 0, content_changed: false };
+    }
+
+    let newContent: string;
+    let replacementsMade: number;
+
+    if (
+      options.maxReplacements != null &&
+      options.maxReplacements < totalMatches
+    ) {
+      // Iterative replacement up to maxReplacements using manual exec loop
+      // so backreferences in the replacement string work correctly.
+      const limit = options.maxReplacements;
+      let count = 0;
+      let result = "";
+      let lastIndex = 0;
+      let m: RegExpExecArray | null;
+      while ((m = pattern.exec(row.content)) !== null) {
+        if (count >= limit) break;
+        result += row.content.slice(lastIndex, m.index);
+        const singleMatchPattern = new RegExp(
+          pattern.source,
+          pattern.flags.replace("g", ""),
+        );
+        result += m[0].replace(singleMatchPattern, replace);
+        lastIndex = m.index + m[0].length;
+        count++;
+        if (m[0].length === 0) pattern.lastIndex++;
+      }
+      result += row.content.slice(lastIndex);
+      newContent = result;
+      replacementsMade = count;
+    } else {
+      newContent = row.content.replace(pattern, replace);
+      replacementsMade = totalMatches;
+    }
+
+    const wordCount = newContent
+      .split(/\s+/)
+      .filter((w) => w.length > 0).length;
+    rawRun(
+      /*sql*/ `UPDATE documents SET content = ?, word_count = ?, updated_at = ? WHERE surface_id = ?`,
+      newContent,
+      wordCount,
+      Date.now(),
+      surfaceId,
+    );
+    log.info({ surfaceId, replacementsMade }, "Replaced text in document");
+    return {
+      success: true,
+      replacements_made: replacementsMade,
+      content_changed: true,
+    };
+  } catch (error) {
+    log.error({ err: error, surfaceId }, "Replace-in-document error");
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : "Unknown error",
+    };
+  }
+}
+
 /** Update persisted document content (append or replace). */
 export function updateDocumentContent(
   surfaceId: string,

package/src/export/__tests__/transcript-formatter.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, mock, test } from "bun:test";
+
+import { z } from "zod";
+
+type TestMessage = {
+  id: string;
+  conversationId: string;
+  role: string;
+  content: string;
+  createdAt: number;
+  metadata: string | null;
+};
+
+const parentMessages: TestMessage[] = [
+  {
+    id: "msg-parent-1",
+    conversationId: "parent-conv",
+    role: "user",
+    content: JSON.stringify([{ type: "text", text: "go research foo" }]),
+    createdAt: 1_700_000_000_000,
+    metadata: null,
+  },
+  {
+    id: "msg-parent-2",
+    conversationId: "parent-conv",
+    role: "assistant",
+    content: JSON.stringify([{ type: "text", text: "spawning subagent" }]),
+    createdAt: 1_700_000_001_000,
+    metadata: JSON.stringify({
+      subagentNotification: {
+        subagentId: "sa-1",
+        label: "research-foo",
+        status: "completed",
+        conversationId: "child-conv-1",
+      },
+    }),
+  },
+];
+
+const childMessages: TestMessage[] = [
+  {
+    id: "msg-child-1",
+    conversationId: "child-conv-1",
+    role: "user",
+    content: JSON.stringify([
+      { type: "text", text: "Objective: research foo and report back." },
+    ]),
+    createdAt: 1_700_000_002_000,
+    metadata: null,
+  },
+  {
+    id: "msg-child-2",
+    conversationId: "child-conv-1",
+    role: "assistant",
+    content: JSON.stringify([
+      { type: "text", text: "I found that foo is a bar." },
+    ]),
+    createdAt: 1_700_000_003_000,
+    metadata: null,
+  },
+];
+
+const messageMetadataSchema = z.object({
+  subagentNotification: z
+    .object({
+      subagentId: z.string(),
+      label: z.string(),
+      status: z.enum(["running", "completed", "failed", "aborted"]),
+      conversationId: z.string().optional(),
+    })
+    .optional(),
+});
+
+mock.module("../../memory/conversation-crud.js", () => ({
+  getConversation: (_id: string) => null,
+  getMessages: (id: string) =>
+    id === "child-conv-1" ? childMessages : parentMessages,
+  messageMetadataSchema,
+}));
+
+mock.module("../../util/truncate.js", () => ({
+  truncate: (s: string) => s,
+}));
+
+mock.module("../../daemon/date-context.js", () => ({
+  formatLocalTimestamp: (_ts: number, _tz?: string) => "TIME",
+}));
+
+const { formatMessageSliceForTranscript } =
+  await import("../transcript-formatter.js");
+
+describe("formatMessageSliceForTranscript subagent labels", () => {
+  test("embedded subagent transcripts render with generic role labels even when parent display names are provided", () => {
+    const out = formatMessageSliceForTranscript(parentMessages, {
+      assistantName: "Bob",
+      userName: "Alice",
+    });
+
+    // Parent messages use the provided display names.
+    expect(out).toContain("## Alice (TIME)");
+    expect(out).toContain("## Bob (TIME)");
+
+    // Subagent block headers must use generic labels — the child "user" message
+    // is actually the parent assistant's objective, so labeling it "Alice"
+    // would misattribute the assistant's tasking text to the human user.
+    expect(out).toContain("### Subagent: research-foo (completed)");
+    expect(out).toContain("> **User** (TIME)");
+    expect(out).toContain("> **Assistant** (TIME)");
+    expect(out).not.toContain("> **Alice**");
+    expect(out).not.toContain("> **Bob**");
+  });
+
+  test("without display-name options, parent and subagent both use generic labels", () => {
+    const out = formatMessageSliceForTranscript(parentMessages);
+
+    expect(out).toContain("## User (TIME)");
+    expect(out).toContain("## Assistant (TIME)");
+    expect(out).toContain("> **User** (TIME)");
+    expect(out).toContain("> **Assistant** (TIME)");
+  });
+});

package/src/export/transcript-formatter.ts

@@ -5,6 +5,7 @@
  * subagent conversation sections when present in message metadata.
  */
 
+import { formatLocalTimestamp } from "../daemon/date-context.js";
 import {
   getConversation,
   getMessages,
@@ -23,10 +24,6 @@ interface ContentBlock {
   source?: { media_type?: string; filename?: string };
 }
 
-function formatTimestamp(ms: number): string {
-  return new Date(ms).toISOString().replace("T", " ").slice(0, 19);
-}
-
 function extractAnalysisText(blocks: ContentBlock[]): string {
   const parts: string[] = [];
   for (const block of blocks) {
@@ -67,15 +64,36 @@ function extractAnalysisText(blocks: ContentBlock[]): string {
   return parts.join("\n");
 }
 
-function formatRole(role: string): string {
-  return role === "user" ? "User" : "Assistant";
+export interface TranscriptFormatOptions {
+  timeZone?: string;
+  assistantName?: string | null;
+  userName?: string | null;
+}
+
+function resolveName(
+  name: string | null | undefined,
+  fallback: string,
+): string {
+  return name && name.length > 0 ? name : fallback;
+}
+
+function formatRole(
+  role: string,
+  options: TranscriptFormatOptions = {},
+): string {
+  return role === "user"
+    ? resolveName(options.userName, "User")
+    : resolveName(options.assistantName, "Assistant");
 }
 
-function formatSubagentMessages(msgs: ReturnType<typeof getMessages>): string {
+function formatSubagentMessages(
+  msgs: ReturnType<typeof getMessages>,
+  options: TranscriptFormatOptions = {},
+): string {
   const lines: string[] = [];
   for (const msg of msgs) {
-    const role = formatRole(msg.role);
-    const time = formatTimestamp(msg.createdAt);
+    const role = formatRole(msg.role, options);
+    const time = formatLocalTimestamp(msg.createdAt, options.timeZone);
     const content = parseContent(msg.content);
     const text = extractAnalysisText(content);
     if (text) {
@@ -103,24 +121,33 @@ type TranscriptMessage = ReturnType<typeof getMessages>[number];
  * Format a slice of messages as a transcript body (no top-of-conversation
  * header). Used by background jobs that process incremental slices — the
  * memory-retrospective job re-renders only the messages added since its
- * last successful run rather than the whole conversation. The format
- * matches `buildAnalysisTranscript` per message so downstream agents see a
- * consistent shape regardless of whether the input is a full transcript or
- * a slice.
+ * last successful run rather than the whole conversation. The per-message
+ * structural shape matches `buildAnalysisTranscript` (header line, body,
+ * optional subagent block) so downstream agents see consistent framing.
+ * The participant *labels*, however, intentionally diverge: this function
+ * honors `TranscriptFormatOptions` so the memory-retrospective prompt can
+ * render the conversation under the assistant and user display names,
+ * while `buildAnalysisTranscript` always uses generic "User"/"Assistant"
+ * labels for the analyze-conversation flow.
  */
 export function formatMessageSliceForTranscript(
   messages: TranscriptMessage[],
+  options: TranscriptFormatOptions = {},
 ): string {
   const lines: string[] = [];
   for (const msg of messages) {
-    appendMessageBlock(lines, msg);
+    appendMessageBlock(lines, msg, options);
   }
   return lines.join("\n");
 }
 
-function appendMessageBlock(lines: string[], msg: TranscriptMessage): void {
-  const role = formatRole(msg.role);
-  const time = formatTimestamp(msg.createdAt);
+function appendMessageBlock(
+  lines: string[],
+  msg: TranscriptMessage,
+  options: TranscriptFormatOptions = {},
+): void {
+  const role = formatRole(msg.role, options);
+  const time = formatLocalTimestamp(msg.createdAt, options.timeZone);
   const content = parseContent(msg.content);
   const text = extractAnalysisText(content);
 
@@ -142,7 +169,14 @@ function appendMessageBlock(lines: string[], msg: TranscriptMessage): void {
           const subMessages = getMessages(notif.conversationId);
           lines.push(`### Subagent: ${notif.label} (${notif.status})`);
           lines.push("");
-          lines.push(formatSubagentMessages(subMessages));
+          // Subagent conversations persist the parent assistant's objective
+          // as a `user` message (see subagent/manager.ts), so reusing the
+          // parent's display-name options would render the assistant's
+          // tasking text under the human user's name. Keep child transcripts
+          // on generic role labels — and only pass through the time zone.
+          lines.push(
+            formatSubagentMessages(subMessages, { timeZone: options.timeZone }),
+          );
           lines.push("");
         }
       }
@@ -163,12 +197,12 @@ export function buildAnalysisTranscript(conversationId: string): string {
   const lines: string[] = [];
 
   lines.push(`# Conversation: ${title}`);
-  lines.push(`Created: ${formatTimestamp(conversation.createdAt)}`);
+  lines.push(`Created: ${formatLocalTimestamp(conversation.createdAt)}`);
   lines.push("");
 
   for (const msg of allMessages) {
     const role = formatRole(msg.role);
-    const time = formatTimestamp(msg.createdAt);
+    const time = formatLocalTimestamp(msg.createdAt);
     const content = parseContent(msg.content);
     const text = extractAnalysisText(content);
 

package/src/heartbeat/__tests__/heartbeat-service.test.ts

@@ -35,7 +35,6 @@ mock.module("../../util/platform.js", () => ({
   getEmbeddingModelsDir: () => join(workspaceDir ?? fallbackDir, "models"),
   getSandboxRootDir: () => join(workspaceDir ?? fallbackDir, "sandbox"),
   getSandboxWorkingDir: () => join(workspaceDir ?? fallbackDir, "sandbox/work"),
-  getInterfacesDir: () => join(workspaceDir ?? fallbackDir, "interfaces"),
   getSoundsDir: () => join(workspaceDir ?? fallbackDir, "sounds"),
   getAvatarDir: () => join(workspaceDir ?? fallbackDir, "avatar"),
   AVATAR_IMAGE_FILENAME: "avatar-image.png",
@@ -55,6 +54,7 @@ const stubConfig: {
     activeHoursStart: number | null;
     activeHoursEnd: number | null;
     maxConsecutiveRuns: number | null;
+    disposition: string;
   };
 } = {
   heartbeat: {
@@ -63,6 +63,7 @@ const stubConfig: {
     activeHoursStart: null,
     activeHoursEnd: null,
     maxConsecutiveRuns: null,
+    disposition: "Default disposition text.",
   },
 };
 mock.module("../../config/loader.js", () => ({
@@ -395,6 +396,48 @@ describe("HeartbeatService", () => {
       }
     });
 
+    test("resetTimer() during an in-flight run is not undone by that run's increment", async () => {
+      // Regression: if a guardian message arrives mid-run, `resetTimer()`
+      // zeroes the counter but the in-flight run's `finally` block used to
+      // unconditionally `_consecutiveRuns++`, leaving the counter at 1 and
+      // tripping the cap-at-1 path one auto run too early.
+      stubConfig.heartbeat.maxConsecutiveRuns = 1;
+
+      let releaseInflight: () => void = () => {};
+      const inflight = new Promise<void>((resolve) => {
+        releaseInflight = resolve;
+      });
+      runBackgroundJobImpl = async () => {
+        await inflight;
+        return { conversationId: STUB_CONVERSATION_ID, ok: true };
+      };
+
+      const service = new HeartbeatService({ alerter: () => {} });
+      service.start();
+      try {
+        const runPromise = service.runOnce({ force: false });
+        // Guardian message arrives while the run is still executing.
+        service.resetTimer();
+        releaseInflight();
+        expect(await runPromise).toBe(true);
+
+        // The reset during the in-flight run must survive: the next auto run
+        // should proceed because the counter is still 0, not 1.
+        runBackgroundJobImpl = async () => ({
+          conversationId: STUB_CONVERSATION_ID,
+          ok: true,
+        });
+        expect(await service.runOnce({ force: false })).toBe(true);
+        expect(
+          skipHeartbeatRunCalls.some(
+            (c) => c.reason === "max_consecutive_runs",
+          ),
+        ).toBe(false);
+      } finally {
+        await service.stop();
+      }
+    });
+
     test("null disables the cap entirely", async () => {
       stubConfig.heartbeat.maxConsecutiveRuns = null;
       const service = new HeartbeatService({ alerter: () => {} });