@vellumai/assistant 0.11.4-staging.2 → 0.11.4-staging.4

package/src/__tests__/conversation-runtime-assembly.test.ts

@@ -4024,6 +4024,59 @@ describe("Slack channel chronological rendering — multi-thread", () => {
     expect(allText).not.toContain("private guardian-only context");
   });
 
+  // Slack builds provider history from rows rather than `this.messages`, so a
+  // guardian card dropped only at `Conversation.loadFromDb` would still reach
+  // the model here -- the channel the incident happened on.
+  test("loadSlackChronologicalContext drops guardian card rows", () => {
+    const caps: ChannelCapabilities = {
+      channel: "slack",
+      dashboardCapable: false,
+      supportsDynamicUi: false,
+      supportsVoiceInput: false,
+      chatType: "channel",
+    };
+    const cardRow: MessageRow = {
+      id: "m-card",
+      conversationId: "conv-1",
+      role: "assistant",
+      content: [
+        {
+          type: "ui_surface",
+          surfaceId: "tool-approval-req-1",
+          surfaceType: "card",
+          title: "Tool Approval",
+          data: {},
+          display: "inline",
+        },
+        { type: "text", text: "Tool Approval card body" },
+      ],
+      createdAt: 1700000035_000,
+      metadata: null,
+      clientMessageId: null,
+      finalized: 1,
+    } as MessageRow;
+    const rows: MessageRow[] = [
+      userRow({
+        id: "asked",
+        createdAt: 1700000030_000,
+        text: "please run it",
+        slackMeta: buildSlackMeta({ channelTs: T2, displayName: "carol" }),
+      }),
+      cardRow,
+    ];
+
+    const result = loadSlackChronologicalContext("conv-1", caps, {
+      loader: () => rows,
+      trustClass: "guardian",
+    });
+
+    expect(result).not.toBeNull();
+    const renderedText = JSON.stringify(result!.messages);
+    expect(renderedText).toContain("please run it");
+    expect(renderedText).not.toContain("Tool Approval card body");
+    expect(renderedText).not.toContain("tool-approval-req-1");
+  });
+
   test("loadSlackChronologicalContext preserves summary and filters by Slack watermark", () => {
     const caps: ChannelCapabilities = {
       channel: "slack",

package/src/__tests__/conversation-slash-queue.test.ts

@@ -62,6 +62,9 @@ mock.module("../persistence/conversation-crud.js", () => ({
   getLastUserTimestampBefore: () => 0,
   reserveMessage: mock(async () => ({ id: "msg-reserve" })),
   updateMessageContent: mock(() => {}),
+  // The drain records the snapshot-stream anchor after each echo. Mocked so a
+  // sink that stamps seqs (the hub) cannot send the real recorder to SQLite.
+  recordConversationPersistedSeq: () => {},
 }));
 
 mock.module("../persistence/conversation-queries.js", () => ({

package/src/__tests__/conversation-surfaces-action-delivery.test.ts

@@ -43,6 +43,7 @@ function makeContext(sent: AssistantEvent[] = []): Conversation & {
   return asConversation({
     conversationId: "conv-1",
     sendToClient: (msg: AssistantEvent) => sent.push(msg),
+    emit: (msg: AssistantEvent) => sent.push(msg),
     pendingSurfaceActions: new Map<string, { surfaceType: SurfaceType }>(),
     lastSurfaceAction: new Map<
       string,

package/src/__tests__/conversation-surfaces-activation-emit.test.ts

@@ -69,6 +69,7 @@ function makeContext(
   return {
     conversationId,
     sendToClient: (msg: AssistantEvent) => sent.push(msg),
+    emit: (msg: AssistantEvent) => sent.push(msg),
     pendingSurfaceActions: new Map<string, { surfaceType: SurfaceType }>(),
     lastSurfaceAction: new Map<
       string,

package/src/__tests__/conversation-surfaces-app-control.test.ts

@@ -97,6 +97,7 @@ function buildMockContext(
           } as Conversation["currentTurnAuthContext"])
         : undefined,
     sendToClient: () => {},
+    emit: () => {},
     pendingSurfaceActions: new Map(),
     lastSurfaceAction: new Map(),
     surfaceState: new Map(),

package/src/__tests__/conversation-surfaces-app-open.test.ts

@@ -29,7 +29,7 @@ function makeContext(
     channelCapabilities:
       options.channelCapabilities &&
       mockChannelCapabilities(options.channelCapabilities),
-    sendToClient: (msg) => sent.push(msg),
+    emit: (msg) => sent.push(msg),
     pendingSurfaceActions: new Map<string, { surfaceType: SurfaceType }>(),
     lastSurfaceAction: new Map<
       string,

package/src/__tests__/conversation-surfaces-data-persist.test.ts

@@ -57,7 +57,7 @@ import { asConversation } from "./helpers/mock-conversation.js";
 function makeContext(sent: AssistantEvent[] = []): Conversation {
   return asConversation({
     conversationId: "conv-persist-1",
-    sendToClient: (msg) => sent.push(msg),
+    emit: (msg) => sent.push(msg),
     pendingSurfaceActions: new Map<string, { surfaceType: SurfaceType }>(),
     lastSurfaceAction: new Map<
       string,

package/src/__tests__/conversation-surfaces-history-restored-completion.test.ts

@@ -124,13 +124,17 @@ type EnqueueResult = { queued: boolean; requestId: string; rejected?: boolean };
 
 function makeContext(
   enqueueResult: EnqueueResult = { queued: false, requestId: "req-1" },
-  overrides: { trustContext?: TrustContext; queueDepth?: number } = {},
+  overrides: {
+    trustContext?: TrustContext;
+    queueDepth?: number;
+    emit?: (msg: AssistantEvent) => void;
+  } = {},
 ): Conversation & { enqueuedContents: string[] } {
   const enqueuedContents: string[] = [];
   return asConversation({
     conversationId: CONVERSATION_ID,
     trustContext: overrides.trustContext ?? GUARDIAN_TRUST,
-    sendToClient: () => {},
+    emit: overrides.emit ?? (() => {}),
     pendingSurfaceActions: new Map<string, { surfaceType: SurfaceType }>(),
     lastSurfaceAction: new Map<
       string,
@@ -885,11 +889,12 @@ describe("surface completion when the persisted write does not land", () => {
   test("a ui_dismiss completion whose write throws stays retryable", async () => {
     const surfaceId = "surface-dismiss-persist-throws-1";
     seedSurfaceRow(surfaceId, "choice");
-    const ctx = makeContext();
     const sentToClient: AssistantEvent[] = [];
-    ctx.sendToClient = (msg) => {
-      sentToClient.push(msg);
-    };
+    const ctx = makeContext(undefined, {
+      emit: (msg) => {
+        sentToClient.push(msg);
+      },
+    });
     seedAnsweredSurface(ctx, surfaceId);
     persistError = new Error("database is locked");
 
@@ -919,11 +924,12 @@ describe("surface completion when the persisted write does not land", () => {
   test("a ui_dismiss completion that lands clears the live state", async () => {
     const surfaceId = "surface-dismiss-persist-lands-1";
     seedSurfaceRow(surfaceId, "choice");
-    const ctx = makeContext();
     const sentToClient: AssistantEvent[] = [];
-    ctx.sendToClient = (msg) => {
-      sentToClient.push(msg);
-    };
+    const ctx = makeContext(undefined, {
+      emit: (msg) => {
+        sentToClient.push(msg);
+      },
+    });
     seedAnsweredSurface(ctx, surfaceId);
 
     const result = await surfaceProxyResolver(ctx, "ui_dismiss", {
@@ -942,11 +948,12 @@ describe("surface completion when the persisted write does not land", () => {
   test("a ui_dismiss with no recorded action clears the live state even when the write throws", async () => {
     const surfaceId = "surface-dismiss-no-action-1";
     seedSurfaceRow(surfaceId, "card");
-    const ctx = makeContext();
     const sentToClient: AssistantEvent[] = [];
-    ctx.sendToClient = (msg) => {
-      sentToClient.push(msg);
-    };
+    const ctx = makeContext(undefined, {
+      emit: (msg) => {
+        sentToClient.push(msg);
+      },
+    });
     ctx.pendingSurfaceActions.set(surfaceId, { surfaceType: "card" });
     ctx.surfaceState.set(surfaceId, { surfaceType: "card", data: {} });
     persistError = new Error("database is locked");

package/src/__tests__/conversation-surfaces-queued-emit.test.ts

@@ -22,6 +22,7 @@ function makeQueuedContext(): Conversation {
   return asConversation({
     conversationId: CONV_ID,
     sendToClient: () => {},
+    emit: () => {},
     pendingSurfaceActions: new Map<string, { surfaceType: SurfaceType }>(),
     lastSurfaceAction: new Map<
       string,

package/src/__tests__/conversation-surfaces-standalone-payloads.test.ts

@@ -65,6 +65,7 @@ function createMockContext(
         })
       : undefined,
     sendToClient: (msg: AssistantEvent) => sentMessages.push(msg),
+    emit: (msg: AssistantEvent) => sentMessages.push(msg),
     pendingSurfaceActions: new Map(),
     lastSurfaceAction: new Map(),
     surfaceState: new Map(),

package/src/__tests__/conversation-surfaces-standalone.test.ts

@@ -53,6 +53,7 @@ function createMockContext(
         })
       : undefined,
     sendToClient: (msg: AssistantEvent) => sentMessages.push(msg),
+    emit: (msg: AssistantEvent) => sentMessages.push(msg),
     pendingSurfaceActions: new Map(),
     lastSurfaceAction: new Map(),
     surfaceState: new Map(),

package/src/__tests__/conversation-surfaces-state-update.test.ts

@@ -26,7 +26,7 @@ function makeContext(opts?: { sent?: AssistantEvent[] }): Conversation & {
 
   return asConversation({
     conversationId: "test-session",
-    sendToClient: (msg) => sent.push(msg),
+    emit: (msg) => sent.push(msg),
     pendingSurfaceActions: new Map<string, { surfaceType: SurfaceType }>(),
     lastSurfaceAction: new Map<
       string,

package/src/__tests__/conversation-surfaces-table-action.test.ts

@@ -49,7 +49,7 @@ function makeContext(): Conversation & {
 
   return asConversation({
     conversationId: "test-convo",
-    sendToClient: (msg) => sentMessages.push(msg),
+    emit: (msg) => sentMessages.push(msg),
     pendingSurfaceActions: new Map<string, { surfaceType: SurfaceType }>(),
     lastSurfaceAction: new Map<
       string,

package/src/__tests__/conversation-surfaces-task-progress.test.ts

@@ -26,7 +26,7 @@ function makeContext(
     conversationId: "session-1",
     channelCapabilities:
       channelCapabilities && mockChannelCapabilities(channelCapabilities),
-    sendToClient: (msg) => sent.push(msg),
+    emit: (msg) => sent.push(msg),
     pendingSurfaceActions: new Map<string, { surfaceType: SurfaceType }>(),
     lastSurfaceAction: new Map<
       string,

package/src/__tests__/conversation-tool-setup-app-refresh.test.ts

@@ -94,7 +94,7 @@ function makeCtx(overrides: Partial<Conversation> = {}): Conversation {
     workingDir: "/tmp/test",
     getTurnActorPrincipalId: () => undefined,
     abortController: null,
-    sendToClient: mock(() => {}),
+    emit: mock(() => {}),
     pendingSurfaceActions: new Map(),
     lastSurfaceAction: new Map(),
     surfaceState: new Map(),

package/src/__tests__/conversation-tool-setup-attribution.test.ts

@@ -101,7 +101,7 @@ function makeCtx(overrides: Partial<Conversation> = {}): Conversation {
     workingDir: "/tmp/test",
     getTurnActorPrincipalId: () => undefined,
     abortController: null,
-    sendToClient: mock(() => {}),
+    emit: mock(() => {}),
     pendingSurfaceActions: new Map(),
     lastSurfaceAction: new Map(),
     surfaceState: new Map(),

package/src/__tests__/cu-unified-flow.test.ts

@@ -97,6 +97,7 @@ function buildMockContext(
           } as Conversation["currentTurnAuthContext"])
         : undefined,
     sendToClient: () => {},
+    emit: () => {},
     pendingSurfaceActions: new Map(),
     lastSurfaceAction: new Map(),
     surfaceState: new Map(),

package/src/__tests__/document-sync-tags.test.ts

@@ -3,8 +3,6 @@
  * the Library and the per-conversation assets list converge on every surface.
  * Read routes and rejected writes must stay silent.
  */
-import { mkdirSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
 import { afterAll, beforeEach, describe, expect, test } from "bun:test";
 
 import type { AssistantEventEnvelope } from "../api/index.js";
@@ -24,9 +22,6 @@ import { resetDbForTesting } from "./db-test-helpers.js";
 
 await initializeDb();
 
-const workspaceDir = process.env.VELLUM_WORKSPACE_DIR!;
-const notesDir = join(workspaceDir, "sync-notes");
-
 const CONVERSATION_ID = "conv-doc-sync";
 const OTHER_CONVERSATION_ID = "conv-doc-sync-other";
 const MISSING_CONVERSATION_ID = "conv-doc-sync-missing";
@@ -110,15 +105,6 @@ async function saveViaRoute(
   });
 }
 
-async function openWorkspaceFile(
-  path: string,
-  conversationId = CONVERSATION_ID,
-): Promise<unknown> {
-  return await invoke("documentForWorkspaceFile", {
-    body: { path, conversationId },
-  });
-}
-
 async function linkViaRoute(
   surfaceId: string,
   conversationId: string,
@@ -136,12 +122,9 @@ beforeEach(() => {
   db.run("DELETE FROM conversations");
   createConversation({ id: CONVERSATION_ID });
   createConversation({ id: OTHER_CONVERSATION_ID });
-  rmSync(notesDir, { recursive: true, force: true });
-  mkdirSync(notesDir, { recursive: true });
 });
 
 afterAll(() => {
-  rmSync(notesDir, { recursive: true, force: true });
   resetDbForTesting();
 });
 
@@ -220,67 +203,9 @@ describe("document write routes publish documents:list", () => {
     expect(events).toHaveLength(1);
     expect("originClientId" in events[0].message).toBe(false);
   });
-
-  test("binding a workspace file publishes without an origin so the caller is not suppressed", async () => {
-    // `viewer-store.loadWorkspaceFileDocument` creates the row and invalidates
-    // nothing, so the client that opened the file is the one that most needs
-    // the invalidation.
-    writeFileSync(join(notesDir, "plan.md"), "# Plan");
-
-    const events = await captureSyncEvents(() =>
-      invoke("documentForWorkspaceFile", {
-        body: { path: "sync-notes/plan.md", conversationId: CONVERSATION_ID },
-        headers: { "x-vellum-client-id": "client-abc" },
-      }),
-    );
-
-    expect(events).toHaveLength(1);
-    expect("originClientId" in events[0].message).toBe(false);
-  });
-
-  test("binding a workspace file to a new document publishes", async () => {
-    writeFileSync(join(notesDir, "plan.md"), "# Plan");
-
-    const events = await captureSyncEvents(() =>
-      openWorkspaceFile("sync-notes/plan.md"),
-    );
-    expectDocumentsChanged(events);
-  });
-
-  test("reopening the file from another conversation publishes the new link", async () => {
-    writeFileSync(join(notesDir, "plan.md"), "# Plan");
-    await openWorkspaceFile("sync-notes/plan.md");
-
-    const events = await captureSyncEvents(() =>
-      openWorkspaceFile("sync-notes/plan.md", OTHER_CONVERSATION_ID),
-    );
-    expectDocumentsChanged(events);
-  });
-
-  test("refreshing a document whose file changed on disk publishes", async () => {
-    const filePath = join(notesDir, "plan.md");
-    writeFileSync(filePath, "# Plan");
-    await openWorkspaceFile("sync-notes/plan.md");
-    writeFileSync(filePath, "# Plan\n\nedited outside the editor");
-
-    const events = await captureSyncEvents(() =>
-      openWorkspaceFile("sync-notes/plan.md"),
-    );
-    expectDocumentsChanged(events);
-  });
 });
 
 describe("document routes that change nothing the list shows stay silent", () => {
-  test("reopening an unchanged, already-linked file publishes nothing", async () => {
-    writeFileSync(join(notesDir, "plan.md"), "# Plan");
-    await openWorkspaceFile("sync-notes/plan.md");
-
-    const events = await captureSyncEvents(() =>
-      openWorkspaceFile("sync-notes/plan.md"),
-    );
-    expect(events).toEqual([]);
-  });
-
   test("a save rejected by validation publishes nothing", async () => {
     const events = await captureSyncEvents(async () => {
       await expect(saveViaRoute({ title: undefined })).rejects.toThrow(

package/src/__tests__/file-ops-service.test.ts

@@ -10,10 +10,11 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, describe, expect, test } from "bun:test";
 
+import { THRESHOLD_CHARS } from "../context/post-turn-tool-result-truncation.js";
 import {
-  DEFAULT_READ_LINE_LIMIT,
   FileSystemOps,
   type PathPolicy,
+  READ_CHAR_BUDGET,
 } from "../tools/shared/filesystem/file-ops-service.js";
 import { sandboxPolicy } from "../tools/shared/filesystem/path-policy.js";
 
@@ -111,34 +112,28 @@ describe("FileSystemOps.readFileSafe", () => {
     expect(result.error.code).toBe("PATH_OUT_OF_BOUNDS");
   });
 
-  test("respects offset and limit", async () => {
+  test("respects startIndex and maxChars", async () => {
     const dir = makeTempDir();
     writeFileSync(join(dir, "lines.txt"), "a\nb\nc\nd\ne\n");
     const ops = new FileSystemOps(sandboxPolicyFor(dir));
 
     const result = await ops.readFileSafe({
       path: "lines.txt",
-      offset: 2,
-      limit: 2,
+      startIndex: 2,
+      maxChars: 3,
     });
     expect(result.ok).toBe(true);
     if (!result.ok) {
       return;
     }
-    // Assert on the numbered lines rather than bare letters: the truncation
-    // notice is prose, so a bare `toContain("d")` matches its wording.
     const [body] = result.value.content.split("\n\n[Truncated:");
-    expect(body).toContain("     2  b");
-    expect(body).toContain("     3  c");
-    expect(body).not.toContain("     1  a");
-    expect(body).not.toContain("     4  d");
+    expect(body).toBe("b\nc");
   });
 
-  test("caps an unbounded read at the default line limit and says so", async () => {
+  test("caps an unbounded read at the character budget and says so", async () => {
     const dir = makeTempDir();
-    const total = DEFAULT_READ_LINE_LIMIT + 500;
-    const lines = Array.from({ length: total }, (_, i) => `line${i + 1}`);
-    writeFileSync(join(dir, "big.txt"), lines.join("\n"));
+    const total = READ_CHAR_BUDGET + 500;
+    writeFileSync(join(dir, "big.txt"), "x".repeat(total));
     const ops = new FileSystemOps(sandboxPolicyFor(dir));
 
     const result = await ops.readFileSafe({ path: "big.txt" });
@@ -146,36 +141,74 @@ describe("FileSystemOps.readFileSafe", () => {
     if (!result.ok) {
       return;
     }
-    const content = result.value.content;
-    expect(content).toContain(`  ${DEFAULT_READ_LINE_LIMIT}  line2000`);
-    expect(content).not.toContain("line2001");
-    expect(content).toContain(
-      `[Truncated: showing through line ${DEFAULT_READ_LINE_LIMIT} of ${total}. Read on with offset=${DEFAULT_READ_LINE_LIMIT + 1}`,
+    const [body] = result.value.content.split("\n\n[Truncated:");
+    expect(body).toHaveLength(READ_CHAR_BUDGET);
+    expect(result.value.content).toContain(
+      `[Truncated: characters 0-${READ_CHAR_BUDGET} of ${total}. Read on with start_index=${READ_CHAR_BUDGET}.]`,
     );
   });
 
-  test("an explicit limit is honored rather than replaced by the default", async () => {
+  test("a maxChars above the budget is clamped to it", async () => {
     const dir = makeTempDir();
-    const lines = Array.from(
-      { length: DEFAULT_READ_LINE_LIMIT + 500 },
-      (_, i) => `line${i + 1}`,
-    );
-    writeFileSync(join(dir, "big.txt"), lines.join("\n"));
+    const total = READ_CHAR_BUDGET + 500;
+    writeFileSync(join(dir, "big.txt"), "x".repeat(total));
     const ops = new FileSystemOps(sandboxPolicyFor(dir));
 
     const result = await ops.readFileSafe({
       path: "big.txt",
-      limit: DEFAULT_READ_LINE_LIMIT + 500,
+      maxChars: total,
     });
     expect(result.ok).toBe(true);
     if (!result.ok) {
       return;
     }
-    expect(result.value.content).toContain("line2500");
-    expect(result.value.content).not.toContain("[Truncated:");
+    const [body] = result.value.content.split("\n\n[Truncated:");
+    expect(body).toHaveLength(READ_CHAR_BUDGET);
+  });
+
+  test("a maxChars below the budget is honored as given", async () => {
+    const dir = makeTempDir();
+    writeFileSync(join(dir, "big.txt"), "x".repeat(500));
+    const ops = new FileSystemOps(sandboxPolicyFor(dir));
+
+    const result = await ops.readFileSafe({ path: "big.txt", maxChars: 10 });
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    const [body] = result.value.content.split("\n\n[Truncated:");
+    expect(body).toHaveLength(10);
+    expect(result.value.content).toContain(
+      "[Truncated: characters 0-10 of 500. Read on with start_index=10.]",
+    );
+  });
+
+  test("paging with the offset from a notice returns the next window", async () => {
+    const dir = makeTempDir();
+    writeFileSync(join(dir, "big.txt"), "abcdefghij");
+    const ops = new FileSystemOps(sandboxPolicyFor(dir));
+
+    const first = await ops.readFileSafe({ path: "big.txt", maxChars: 4 });
+    expect(first.ok).toBe(true);
+    if (!first.ok) {
+      return;
+    }
+    expect(first.value.content).toContain("start_index=4");
+
+    const second = await ops.readFileSafe({
+      path: "big.txt",
+      startIndex: 4,
+      maxChars: 4,
+    });
+    expect(second.ok).toBe(true);
+    if (!second.ok) {
+      return;
+    }
+    const [body] = second.value.content.split("\n\n[Truncated:");
+    expect(body).toBe("efgh");
   });
 
-  test("a read that reaches the last line carries no truncation notice", async () => {
+  test("a read that reaches the end carries no truncation notice", async () => {
     const dir = makeTempDir();
     writeFileSync(join(dir, "small.txt"), "a\nb\nc");
     const ops = new FileSystemOps(sandboxPolicyFor(dir));
@@ -193,13 +226,113 @@ describe("FileSystemOps.readFileSafe", () => {
     writeFileSync(join(dir, "small.txt"), "a\nb\nc");
     const ops = new FileSystemOps(sandboxPolicyFor(dir));
 
-    const result = await ops.readFileSafe({ path: "small.txt", offset: 100 });
+    const result = await ops.readFileSafe({
+      path: "small.txt",
+      startIndex: 100,
+    });
     expect(result.ok).toBe(true);
     if (!result.ok) {
       return;
     }
     expect(result.value.content).not.toContain("[Truncated:");
   });
+
+  test("a window boundary inside a surrogate pair does not corrupt it", async () => {
+    const dir = makeTempDir();
+    // "ab" + a 2-unit emoji + "cd": a maxChars of 3 would split the pair.
+    writeFileSync(join(dir, "emoji.txt"), `ab\u{1F600}cd`);
+    const ops = new FileSystemOps(sandboxPolicyFor(dir));
+
+    const result = await ops.readFileSafe({ path: "emoji.txt", maxChars: 3 });
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    const [body] = result.value.content.split("\n\n[Truncated:");
+    expect(body).toBe("ab");
+    expect(body).not.toContain("\uFFFD");
+  });
+
+  test("paging across a surrogate pair reassembles the whole file", async () => {
+    const dir = makeTempDir();
+    const original = `ab\u{1F600}cd`;
+    writeFileSync(join(dir, "emoji.txt"), original);
+    const ops = new FileSystemOps(sandboxPolicyFor(dir));
+
+    let assembled = "";
+    let startIndex = 0;
+    for (let i = 0; i < 10; i++) {
+      const result = await ops.readFileSafe({
+        path: "emoji.txt",
+        startIndex,
+        maxChars: 3,
+      });
+      expect(result.ok).toBe(true);
+      if (!result.ok) {
+        return;
+      }
+      const [body] = result.value.content.split("\n\n[Truncated:");
+      assembled += body;
+      const match = /start_index=(\d+)/.exec(result.value.content);
+      if (match?.[1] === undefined) {
+        break;
+      }
+      startIndex = Number(match[1]);
+    }
+    expect(assembled).toBe(original);
+  });
+
+  test("a lone-low-surrogate startIndex backs up onto the whole pair", async () => {
+    const dir = makeTempDir();
+    writeFileSync(join(dir, "emoji.txt"), `ab\u{1F600}cd`);
+    const ops = new FileSystemOps(sandboxPolicyFor(dir));
+
+    // Index 3 (0-indexed) is the low half of the emoji.
+    const result = await ops.readFileSafe({
+      path: "emoji.txt",
+      startIndex: 3,
+      maxChars: 2,
+    });
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    const [body] = result.value.content.split("\n\n[Truncated:");
+    expect(body).toBe(`\u{1F600}`);
+    expect(body).not.toContain("\uFFFD");
+  });
+
+  test("legacy offset/limit are rejected rather than silently ignored", async () => {
+    const { fileReadTool } = await import("../tools/filesystem/read.js");
+    const dir = makeTempDir();
+    writeFileSync(join(dir, "big.txt"), "x".repeat(500));
+
+    const result = await fileReadTool.execute(
+      { path: join(dir, "big.txt"), offset: 2001, limit: 2000 },
+      { workingDir: dir } as never,
+    );
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain("no longer takes");
+    expect(result.content).toContain("start_index");
+  });
+
+  test("legacy fields alongside current ones do not trigger the guard", async () => {
+    const { fileReadTool } = await import("../tools/filesystem/read.js");
+    const dir = makeTempDir();
+    writeFileSync(join(dir, "big.txt"), "abcdefghij");
+
+    const result = await fileReadTool.execute(
+      { path: join(dir, "big.txt"), offset: 1, max_chars: 4 },
+      { workingDir: dir } as never,
+    );
+    expect(result.isError).toBe(false);
+    const [body] = result.content.split("\n\n[Truncated:");
+    expect(body).toBe("abcd");
+  });
+
+  test("the read budget stays under the tool-result spool threshold", () => {
+    expect(READ_CHAR_BUDGET).toBeLessThan(THRESHOLD_CHARS);
+  });
 });
 
 // ---------------------------------------------------------------------------