@vellumai/assistant 0.11.4-staging.3 → 0.11.4

package/src/subagent/types.ts

@@ -485,13 +485,13 @@ export const SUBAGENT_ROLE_REGISTRY: Record<SubagentRole, SubagentRoleConfig> =
       skillIds: [],
       systemPromptPreamble: [
         "You are a research subagent with read-only access: search the web, read and search files, and recall memories. There is no shell, and you cannot write or edit files.",
-        // `file_read` returns the first DEFAULT_READ_LINE_LIMIT (2000) lines
-        // unless a limit is passed, with a truncation notice naming the resume
-        // offset, and oversized results spool to .tool-results/ like any other
-        // tool's (only re-reads of spooled content stay inline). So a ranged
-        // read is both the cheap shape and the one that avoids a spool
-        // round-trip. The anti-slicing intent stays: one pass over the range
-        // that is needed rather than many small ones.
+        // `file_read` returns a bounded character window with a truncation
+        // notice naming the resume offset, and oversized results spool to
+        // .tool-results/ like any other tool's (only re-reads of spooled
+        // content stay inline). So a ranged read is both the cheap shape and
+        // the one that avoids a spool round-trip. The anti-slicing intent
+        // stays: one pass over the range that is needed rather than many
+        // small ones.
         "Working method: use code_search to search file contents across directories, file_list to enumerate paths, and file_read to read files and logs. Prefer broad code_search queries across a directory over one-symbol-at-a-time queries, and read the range you need in one pass rather than many small slices.",
         "Send notify_parent (urgency 'important') as soon as each finding is confirmed, so progress survives interruption.",
         "Your final message is the deliverable: a compact report that answers the objective, gives the evidence behind each claim (file:line references, URLs, or quotes), and names what you could not determine. For a root-cause investigation, use the sections Symptom, Root cause, Evidence, Suggested fix, Open questions.",

package/src/tools/__tests__/tool-input-schemas.test.ts

@@ -74,12 +74,12 @@ describe("parseToolInput", () => {
   test("file_read drops malformed optional fields the tool always ignored", () => {
     const result = parseToolInput("file_read", {
       path: "notes.md",
-      offset: "not-a-number",
-      limit: 10,
+      start_index: "not-a-number",
+      max_chars: 10,
     });
     expect(result).toEqual({
       ok: true,
-      data: { path: "notes.md", limit: 10 },
+      data: { path: "notes.md", max_chars: 10 },
     });
   });
 
@@ -184,9 +184,9 @@ describe("derived input_schema", () => {
       properties: Record<string, { type?: string; description?: string }>;
       required: string[];
     };
-    expect(schema.properties.offset?.type).toBe("number");
-    expect(schema.properties.offset?.description).toContain("1-indexed");
-    expect(schema.required).not.toContain("offset");
-    expect(schema.required).not.toContain("limit");
+    expect(schema.properties.start_index?.type).toBe("number");
+    expect(schema.properties.start_index?.description).toContain("0-indexed");
+    expect(schema.required).not.toContain("start_index");
+    expect(schema.required).not.toContain("max_chars");
   });
 });

package/src/tools/filesystem/read.ts

@@ -12,6 +12,7 @@ import {
   IMAGE_EXTENSIONS,
   readImageFile,
 } from "../shared/filesystem/image-read.js";
+import { legacyReadArgsError } from "../shared/filesystem/legacy-read-args.js";
 import { sandboxReadPolicy } from "../shared/filesystem/path-policy.js";
 import {
   invalidToolInputResult,
@@ -25,8 +26,8 @@ import type {
 
 /**
  * Model-input schema, the single source for both runtime validation (via
- * `TOOL_INPUT_SCHEMAS`) and the advertised `input_schema` below. `offset` and
- * `limit` catch to `undefined` because the tool has always ignored non-numeric
+ * `TOOL_INPUT_SCHEMAS`) and the advertised `input_schema` below. `start_index`
+ * and `max_chars` catch to `undefined` because the tool ignores non-numeric
  * values rather than failing the read.
  */
 export const fileReadInputSchema = z.looseObject({
@@ -36,14 +37,16 @@ export const fileReadInputSchema = z.looseObject({
     .describe(
       "The path to the file to read (absolute or relative to working directory)",
     ),
-  offset: z
+  start_index: z
     .number()
-    .describe("Line number to start reading from (1-indexed)")
+    .describe("Character to start reading from (0-indexed). Text files only.")
     .optional()
     .catch(undefined),
-  limit: z
+  max_chars: z
     .number()
-    .describe("Maximum number of lines to read (defaults to 2000)")
+    .describe(
+      "Maximum number of characters to read. Defaults to 20000, which is also the ceiling. Text files only.",
+    )
     .optional()
     .catch(undefined),
   activity: z
@@ -58,7 +61,7 @@ export const fileReadInputSchema = z.looseObject({
 export const fileReadTool = {
   name: "file_read",
   description:
-    "Read the contents of a file on your own machine. Text reads return the first 2000 lines unless you pass `limit`; when a read stops short the result says so, and `offset` pages on from there. For image files (JPEG, PNG, GIF, WebP), returns the image for visual analysis. For audio files (MP3, WAV, OGG, FLAC, AAC, M4A), returns the audio for listening. Use host_file_read for files on your guardian's device instead.",
+    "Read the contents of a file on your own machine. Text reads return the first 20000 characters unless you pass `max_chars`; when a read stops short the result says so, and `start_index` pages on from there. To find where something is in a large file, code_search is cheaper than paging through it. For image files (JPEG, PNG, GIF, WebP), returns the image for visual analysis. For audio files (MP3, WAV, OGG, FLAC, AAC, M4A), returns the audio for listening. Use host_file_read for files on your guardian's device instead.",
   category: "filesystem",
   executionTarget: "sandbox",
   defaultRiskLevel: RiskLevel.Low,
@@ -75,9 +78,14 @@ export const fileReadTool = {
     if (!parsed.success) {
       return invalidToolInputResult("file_read", parsed.error);
     }
-    const { path: rawPath, offset, limit } = parsed.data;
+    const {
+      path: rawPath,
+      start_index: startIndex,
+      max_chars: maxChars,
+    } = parsed.data;
 
-    // For image files, delegate to the shared image reader.
+    // For image files, delegate to the shared image reader. Media reads carry
+    // no window, so the legacy-argument guard below does not apply to them.
     const ext = extname(rawPath).toLowerCase();
     if (IMAGE_EXTENSIONS.has(ext)) {
       const pathCheck = sandboxReadPolicy(rawPath, context.workingDir);
@@ -102,11 +110,20 @@ export const fileReadTool = {
       return readAudioFile(pathCheck.resolved);
     }
 
+    const legacyArgs = legacyReadArgsError("file_read", input);
+    if (legacyArgs !== undefined) {
+      return { content: legacyArgs, isError: true };
+    }
+
     const ops = new FileSystemOps((path, opts) =>
       sandboxReadPolicy(path, context.workingDir, opts),
     );
 
-    const result = await ops.readFileSafe({ path: rawPath, offset, limit });
+    const result = await ops.readFileSafe({
+      path: rawPath,
+      startIndex,
+      maxChars,
+    });
 
     if (!result.ok) {
       const { error } = result;

package/src/tools/host-filesystem/read.ts

@@ -11,13 +11,14 @@ import {
   readAudioFile,
 } from "../shared/filesystem/audio-read.js";
 import {
-  DEFAULT_READ_LINE_LIMIT,
   FileSystemOps,
+  READ_CHAR_BUDGET,
 } from "../shared/filesystem/file-ops-service.js";
 import {
   IMAGE_EXTENSIONS,
   readImageFile,
 } from "../shared/filesystem/image-read.js";
+import { legacyReadArgsError } from "../shared/filesystem/legacy-read-args.js";
 import { hostPolicy } from "../shared/filesystem/path-policy.js";
 import {
   invalidToolInputResult,
@@ -32,9 +33,9 @@ import type {
 /**
  * Model-input schema, the single source for both runtime validation (via
  * `TOOL_INPUT_SCHEMAS`) and the advertised `input_schema` below — mirrors
- * `filesystem/read.ts`. `offset`/`limit` catch to `undefined` so a
- * non-numeric value falls back to the default line window instead of failing
- * the call; `target_client_id` catches so a non-string (or empty) value means
+ * `filesystem/read.ts`. `start_index`/`max_chars` catch to `undefined` so a
+ * non-numeric value falls back to the default character window instead of
+ * failing the call; `target_client_id` catches so a non-string (or empty) value means
  * "untargeted".
  */
 export const hostFileReadInputSchema = z.looseObject({
@@ -44,14 +45,16 @@ export const hostFileReadInputSchema = z.looseObject({
     .describe(
       "Absolute path on the guardian's device, which is a separate filesystem from your workspace, to read.",
     ),
-  offset: z
+  start_index: z
     .number()
-    .describe("Line number to start reading from (1-indexed)")
+    .describe("Character to start reading from (0-indexed). Text files only.")
     .optional()
     .catch(undefined),
-  limit: z
+  max_chars: z
     .number()
-    .describe("Maximum number of lines to read (defaults to 2000)")
+    .describe(
+      "Maximum number of characters to read. Defaults to 20000, which is also the ceiling. Text files only.",
+    )
     .optional()
     .catch(undefined),
   target_client_id: z
@@ -66,7 +69,7 @@ export const hostFileReadInputSchema = z.looseObject({
 export const hostFileReadTool = {
   name: "host_file_read",
   description:
-    "Read the contents of a file on your guardian's device, including images (JPEG, PNG, GIF, WebP) and audio (MP3, WAV, OGG, FLAC, AAC, M4A). Text reads return the first 2000 lines unless you pass `limit`; when a read stops short the result says so, and `offset` pages on from there. For files on your own machine, use file_read instead.",
+    "Read the contents of a file on your guardian's device, including images (JPEG, PNG, GIF, WebP) and audio (MP3, WAV, OGG, FLAC, AAC, M4A). Text reads return the first 20000 characters unless you pass `max_chars`; when a read stops short the result says so, and `start_index` pages on from there. For files on your own machine, use file_read instead.",
   category: "host-filesystem",
   executionTarget: "host",
   defaultRiskLevel: RiskLevel.Medium,
@@ -81,12 +84,12 @@ export const hostFileReadTool = {
     if (!parsed.success) {
       return invalidToolInputResult("host_file_read", parsed.error);
     }
-    const { path: rawPath, offset } = parsed.data;
+    const { path: rawPath, start_index: startIndex } = parsed.data;
     // Resolve the default here rather than leaving it to the read, so the
     // proxied branch below is bounded by the same window as the local one. A
-    // proxied read that sent no limit would stream a whole host file across
+    // proxied read that sent no budget would stream a whole host file across
     // the bridge before anything could trim it.
-    const limit = parsed.data.limit ?? DEFAULT_READ_LINE_LIMIT;
+    const maxChars = parsed.data.max_chars ?? READ_CHAR_BUDGET;
 
     const targetClientId =
       parsed.data.target_client_id !== ""
@@ -153,8 +156,8 @@ export const hostFileReadTool = {
         {
           operation: "read",
           path: rawPath,
-          offset,
-          limit,
+          startIndex,
+          maxChars,
           targetClientId,
         },
         context.conversationId,
@@ -181,9 +184,18 @@ export const hostFileReadTool = {
       return readAudioFile(pathCheck.resolved);
     }
 
+    const legacyArgs = legacyReadArgsError("host_file_read", input);
+    if (legacyArgs !== undefined) {
+      return { content: legacyArgs, isError: true };
+    }
+
     const ops = new FileSystemOps(hostPolicy);
 
-    const result = await ops.readFileSafe({ path: rawPath, offset, limit });
+    const result = await ops.readFileSafe({
+      path: rawPath,
+      startIndex,
+      maxChars,
+    });
 
     if (!result.ok) {
       const { error } = result;

package/src/tools/shared/filesystem/file-ops-service.ts

@@ -78,26 +78,55 @@ function pathError(
 }
 
 /**
- * Lines returned by a read that names no `limit`. Without a default the read
- * returns the whole file, and a file-read result is honored in full for the
- * rest of the turn (see `isSpoolEligible` in `context/tool-result-spool.ts`),
- * so one unbounded read of a large file rides every subsequent LLM call in
- * that turn. The cap bounds that; `offset`/`limit` page past it, and
- * {@link truncationNotice} tells the model when it is looking at a window
- * rather than the whole file.
+ * Characters returned by a read that names no `max_chars`. Stays under
+ * `THRESHOLD_CHARS` in `context/post-turn-tool-result-truncation.ts`, which
+ * spools any larger tool result to disk and replaces it inline with a short
+ * stub, so a default read returns content rather than a stub.
  */
-export const DEFAULT_READ_LINE_LIMIT = 2000;
+export const READ_CHAR_BUDGET = 20_000;
 
 /**
- * Trailing marker appended when a read stops short of the last line. Silent
- * truncation is the failure mode worth avoiding: a model that cannot tell a
- * window from a whole file reasons about code it never saw.
+ * Trailing marker appended when a read stops short of the end of the file. A
+ * model that cannot tell a window from a whole file reasons about code it
+ * never saw.
  */
 function truncationNotice(
-  lastLineReturned: number,
-  totalLines: number,
+  start: number,
+  end: number,
+  totalChars: number,
 ): string {
-  return `\n\n[Truncated: showing through line ${lastLineReturned} of ${totalLines}. Read on with offset=${lastLineReturned + 1}, or pass an explicit limit.]`;
+  return `\n\n[Truncated: characters ${start}-${end} of ${totalChars}. Read on with start_index=${end}.]`;
+}
+
+const isHighSurrogate = (code: number): boolean =>
+  code >= 0xd800 && code <= 0xdbff;
+const isLowSurrogate = (code: number): boolean =>
+  code >= 0xdc00 && code <= 0xdfff;
+
+/**
+ * Character window that never splits a surrogate pair. A split leaves a lone
+ * half at each edge, and each encodes to U+FFFD, so the character is lost from
+ * both this window and the next one paged in after it.
+ */
+export function surrogateSafeWindow(
+  total: number,
+  charCodeAt: (index: number) => number,
+  requestedStart: number,
+  maxChars: number,
+): { start: number; end: number } {
+  let start = Math.max(0, Math.min(requestedStart, total));
+  if (start > 0 && start < total && isLowSurrogate(charCodeAt(start))) {
+    start -= 1;
+  }
+
+  let end = Math.min(total, start + maxChars);
+  if (end > start && end < total && isHighSurrogate(charCodeAt(end - 1))) {
+    // Backing off would empty a one-character window, which stalls paging on
+    // the same offset, so take the whole pair instead.
+    end = end - 1 > start ? end - 1 : Math.min(total, end + 1);
+  }
+
+  return { start, end };
 }
 
 export class FileSystemOps {
@@ -139,28 +168,27 @@ export class FileSystemOps {
 
     try {
       const raw = await readFile(filePath, "utf-8");
-      const lines = raw.split("\n");
-
-      const offset = (input.offset ?? 1) - 1;
-      const start = Math.max(0, offset);
-      const limit = input.limit ?? DEFAULT_READ_LINE_LIMIT;
-      const selected = lines.slice(start, offset + limit);
-
-      const numbered = selected
-        .map((line, i) => {
-          const lineNum = offset + i + 1;
-          return `${String(lineNum).padStart(6)}  ${line}`;
-        })
-        .join("\n");
-
-      // Only when the window stops before the last line. An empty window means
-      // the caller paged past the end or asked for nothing, which is not a
-      // truncated read.
-      const lastLineReturned = start + selected.length;
+
+      // A ceiling, not just a default: a larger window would be spooled to
+      // disk and replaced with a stub, returning less than this.
+      const maxChars = Math.min(
+        READ_CHAR_BUDGET,
+        Math.max(0, input.maxChars ?? READ_CHAR_BUDGET),
+      );
+      const { start, end } = surrogateSafeWindow(
+        raw.length,
+        (i) => raw.charCodeAt(i),
+        input.startIndex ?? 0,
+        maxChars,
+      );
+      const window = raw.slice(start, end);
+
+      // An empty window means the caller paged past the end or asked for
+      // nothing, which is not a truncated read.
       const content =
-        selected.length > 0 && lastLineReturned < lines.length
-          ? numbered + truncationNotice(lastLineReturned, lines.length)
-          : numbered;
+        window.length > 0 && end < raw.length
+          ? window + truncationNotice(start, end, raw.length)
+          : window;
 
       return { ok: true, value: { content } };
     } catch (err) {

package/src/tools/shared/filesystem/legacy-read-args.ts

@@ -0,0 +1,22 @@
+/**
+ * Guard for callers still passing the line-based `offset`/`limit` read
+ * arguments. The tool schemas are loose, so those keys parse and are then
+ * dropped, which would silently serve the start of the file to a caller that
+ * asked to page into the middle of it.
+ *
+ * There is no safe translation: `offset` counted lines and `start_index`
+ * counts characters, so mapping one onto the other would read the wrong
+ * region rather than fail. Naming the rename lets the caller correct itself.
+ */
+export function legacyReadArgsError(
+  toolName: string,
+  input: Record<string, unknown>,
+): string | undefined {
+  const usesLegacy = input.offset !== undefined || input.limit !== undefined;
+  const usesCurrent =
+    input.start_index !== undefined || input.max_chars !== undefined;
+  if (!usesLegacy || usesCurrent) {
+    return undefined;
+  }
+  return `Error: ${toolName} no longer takes \`offset\`/\`limit\` (lines). Use \`start_index\` (0-indexed characters) and \`max_chars\` instead.`;
+}

package/src/tools/shared/filesystem/types.ts

@@ -6,14 +6,14 @@ import type { FsError } from "./errors.js";
 
 export interface ReadInput {
   path: string;
-  /** 1-indexed line number to start reading from. */
-  offset?: number;
-  /** Maximum number of lines to read. */
-  limit?: number;
+  /** 0-indexed character to start reading from. */
+  startIndex?: number;
+  /** Maximum number of characters to read. */
+  maxChars?: number;
 }
 
 export interface ReadOutput {
-  /** The (possibly line-numbered) file content. */
+  /** The character window, with a truncation notice when it stops short. */
   content: string;
 }