tinker-agent 2.9.0 → 2.11.0

package/src/tools/bash.ts

@@ -13,6 +13,7 @@ import type { TaskOutputSnapshot } from "./task-output";
 import type { BashRawResult, ToolExecutionContext, ToolExecutor } from "./types";
 import { DEFAULT_PUBLIC_TOOLING_CONFIG } from "../cli/public-config-contract";
 import { classifyBashRisk } from "./bash-guard";
+import { MAX_TERMINAL_DIMENSION, MIN_TERMINAL_COLUMNS } from "./terminal-screen";
 
 type BashArgs = {
   command: string;
@@ -20,6 +21,8 @@ type BashArgs = {
   description?: string;
   run_in_background?: boolean;
   tty?: boolean;
+  cols?: number;
+  rows?: number;
 };
 
 export type BashToolOptions = {
@@ -44,7 +47,8 @@ export function createBashToolExecutor(options: BashToolOptions): ToolExecutor {
   return defineToolExecutor("bash", {
     definition: {
       name: "Bash",
-      description: "Run a shell command locally.",
+      description:
+        "Run a shell command locally. If the foreground timeout expires while the command is still running, it continues as a background task and returns a task ID; it is not killed. Use TaskOutput to inspect progress, then decide whether to keep waiting or stop it with TaskStop.",
       parameters: {
         type: "object",
         additionalProperties: false,
@@ -57,7 +61,8 @@ export function createBashToolExecutor(options: BashToolOptions): ToolExecutor {
             type: "integer",
             minimum: 1,
             maximum: maxTimeoutMs,
-            description: "Optional foreground timeout in milliseconds.",
+            description:
+              "Optional foreground wait duration in milliseconds. On timeout, a still-running command continues in the background instead of being killed.",
           },
           description: {
             type: "string",
@@ -72,6 +77,20 @@ export function createBashToolExecutor(options: BashToolOptions): ToolExecutor {
             description:
               "Run the command in a pseudo-terminal so it can receive interactive input.",
           },
+          cols: {
+            type: "integer",
+            minimum: MIN_TERMINAL_COLUMNS,
+            maximum: MAX_TERMINAL_DIMENSION,
+            description:
+              "Initial PTY width in columns. Defaults to 80. Ignored unless tty=true.",
+          },
+          rows: {
+            type: "integer",
+            minimum: 1,
+            maximum: MAX_TERMINAL_DIMENSION,
+            description:
+              "Initial PTY height in rows. Defaults to 24. Ignored unless tty=true.",
+          },
         },
         required: ["command"],
       },
@@ -137,6 +156,8 @@ export function createBashToolExecutor(options: BashToolOptions): ToolExecutor {
         description: input.description ?? input.command,
         origin: call,
         tty: input.tty === true,
+        cols: input.cols,
+        rows: input.rows,
       });
 
       if (input.run_in_background === true) {
@@ -232,6 +253,25 @@ export function parseBashArgs(
     return { ok: false, error: "Bash.tty must be a boolean." };
   }
 
+  if (args.tty === true) {
+    for (const name of ["cols", "rows"] as const) {
+      const value = args[name];
+      const minimum = name === "cols" ? MIN_TERMINAL_COLUMNS : 1;
+      if (
+        value !== undefined &&
+        (typeof value !== "number" ||
+          !Number.isInteger(value) ||
+          value < minimum ||
+          value > MAX_TERMINAL_DIMENSION)
+      ) {
+        return {
+          ok: false,
+          error: `Bash.${name} must be an integer between ${minimum} and ${MAX_TERMINAL_DIMENSION}.`,
+        };
+      }
+    }
+  }
+
   return {
     ok: true,
     value: {
@@ -243,6 +283,8 @@ export function parseBashArgs(
           : args.description,
       run_in_background: args.run_in_background,
       tty: args.tty,
+      cols: args.tty === true ? (args.cols as number | undefined) : undefined,
+      rows: args.tty === true ? (args.rows as number | undefined) : undefined,
     },
   };
 }

package/src/tools/glob.ts

@@ -1,6 +1,6 @@
 import path from "node:path";
-import { stat } from "node:fs/promises";
-import { glob } from "glob";
+import { realpath, stat } from "node:fs/promises";
+import { glob, type Path } from "glob";
 import { cancellationError, throwIfTurnCancelled } from "../agent/turn-cancellation";
 import { resolveWorkspacePath, toDisplayPath } from "./path-safety";
 import { defineToolExecutor } from "./types";
@@ -9,6 +9,8 @@ import type { GlobRawResult, ToolExecutionContext, ToolExecutor } from "./types"
 type GlobArgs = {
   pattern: string;
   path?: string;
+  head_limit: number;
+  offset: number;
 };
 
 export type GlobToolOptions = {
@@ -16,12 +18,15 @@ export type GlobToolOptions = {
 };
 
 const ignoredDirectories = ["node_modules", ".git"];
+const defaultHeadLimit = 200;
+const maxHeadLimit = 500;
 
 export function createGlobToolExecutor(options: GlobToolOptions): ToolExecutor {
   return defineToolExecutor("glob", {
     definition: {
       name: "Glob",
-      description: "Find files by glob pattern. node_modules and .git are ignored.",
+      description:
+        "Find regular files by glob pattern, including symbolic links to regular files. Case sensitivity follows platform defaults. Directory links and broken links are excluded. node_modules and .git are skipped during traversal; to search inside either, set path directly to that directory.",
       parameters: {
         type: "object",
         additionalProperties: false,
@@ -33,7 +38,21 @@ export function createGlobToolExecutor(options: GlobToolOptions): ToolExecutor {
           path: {
             type: "string",
             description:
-              "Optional workspace-relative or absolute search directory. Defaults to the workspace root.",
+              "Optional workspace-relative or absolute search directory. Defaults to the workspace root. A directory symbolic link is allowed as the search root.",
+          },
+          head_limit: {
+            type: "integer",
+            minimum: 1,
+            maximum: maxHeadLimit,
+            description:
+              "Maximum paths to return. Defaults to 200; must be between 1 and 500.",
+          },
+          offset: {
+            type: "integer",
+            minimum: 0,
+            maximum: Number.MAX_SAFE_INTEGER,
+            description:
+              "Skip the first N sorted matches. Defaults to 0. To continue, pass nextOffset from the previous result with the same pattern and path.",
           },
         },
         required: ["pattern"],
@@ -46,8 +65,16 @@ export function createGlobToolExecutor(options: GlobToolOptions): ToolExecutor {
       if (!parsed.ok) {
         return {
           ok: false,
-          pattern: "",
-          searchPath: ".",
+          pattern:
+            isRecord(args) && typeof args.pattern === "string"
+              ? args.pattern
+              : undefined,
+          searchPath:
+            isRecord(args) && args.path !== undefined
+              ? typeof args.path === "string"
+                ? args.path
+                : "(invalid path)"
+              : ".",
           ignored: ignoredDirectories,
           error: parsed.error,
         };
@@ -87,27 +114,43 @@ export function createGlobToolExecutor(options: GlobToolOptions): ToolExecutor {
       }
 
       try {
+        // Resolve the root only; keep the traversal policy for links below it.
+        const realSearchPath = await realpath(absoluteSearchPath);
+        throwIfTurnCancelled(context.signal);
         const matches = await glob(input.pattern, {
-          cwd: absoluteSearchPath,
+          cwd: realSearchPath,
           nodir: true,
           dot: true,
           follow: false,
+          withFileTypes: true,
           signal: context.signal,
           ignore: ["**/node_modules/**", "**/.git/**"],
         });
-        const displayMatches = toDisplayMatches({
+        const displayMatches = await toDisplayMatches({
           workspaceRoot: options.workspaceRoot,
           absoluteSearchPath,
+          realSearchPath,
           matches,
+          signal: context.signal,
         });
+        const page = displayMatches.slice(
+          input.offset,
+          input.offset + input.head_limit,
+        );
+        const hasMore = input.offset + page.length < displayMatches.length;
 
         return {
           ok: true,
           pattern: input.pattern,
           searchPath,
           absoluteSearchPath,
-          matches: displayMatches,
-          matchCount: displayMatches.length,
+          matches: page,
+          matchCount: page.length,
+          totalMatches: displayMatches.length,
+          returnedCount: page.length,
+          appliedOffset: input.offset,
+          hasMore,
+          ...(hasMore ? { nextOffset: input.offset + page.length } : {}),
           ignored: ignoredDirectories,
         };
       } catch (error) {
@@ -151,11 +194,35 @@ function parseGlobArgs(
     return { ok: false, error: "Glob.path must be a string." };
   }
 
+  if (
+    args.head_limit !== undefined &&
+    (typeof args.head_limit !== "number" ||
+      !Number.isSafeInteger(args.head_limit) ||
+      args.head_limit < 1 ||
+      args.head_limit > maxHeadLimit)
+  ) {
+    return {
+      ok: false,
+      error: "Glob.head_limit must be an integer between 1 and 500.",
+    };
+  }
+
+  if (
+    args.offset !== undefined &&
+    (typeof args.offset !== "number" ||
+      !Number.isSafeInteger(args.offset) ||
+      args.offset < 0)
+  ) {
+    return { ok: false, error: "Glob.offset must be a non-negative safe integer." };
+  }
+
   return {
     ok: true,
     value: {
       pattern: args.pattern,
       path: args.path,
+      head_limit: args.head_limit ?? defaultHeadLimit,
+      offset: args.offset ?? 0,
     },
   };
 }
@@ -177,22 +244,43 @@ async function ensureDirectory(
   }
 }
 
-function toDisplayMatches(input: {
+async function toDisplayMatches(input: {
   workspaceRoot: string;
   absoluteSearchPath: string;
-  matches: string[];
-}): string[] {
-  const normalized = input.matches.map((match) => {
-    const absolutePath = resolveWorkspacePath(
-      input.workspaceRoot,
-      path.resolve(input.absoluteSearchPath, match),
+  realSearchPath: string;
+  matches: Path[];
+  signal: AbortSignal;
+}): Promise<string[]> {
+  const normalized: string[] = [];
+  for (const match of input.matches) {
+    throwIfTurnCancelled(input.signal);
+    if (!(await isRegularFileMatch(match))) continue;
+    // Preserve the caller's root spelling, including directory links and aliases.
+    const absolutePath = path.resolve(
+      input.absoluteSearchPath,
+      path.relative(input.realSearchPath, match.fullpath()),
     );
-    return toDisplayPath(input.workspaceRoot, absolutePath);
-  });
+    normalized.push(toDisplayPath(input.workspaceRoot, absolutePath));
+  }
+  throwIfTurnCancelled(input.signal);
 
   return [...new Set(normalized)].sort((left, right) => left.localeCompare(right));
 }
 
+async function isRegularFileMatch(match: Path): Promise<boolean> {
+  if (!match.isSymbolicLink()) return match.isFile();
+
+  try {
+    // Resolve only the type; keep the link's path in the returned matches.
+    return (await stat(match.fullpath())).isFile();
+  } catch (error) {
+    if (isRecord(error) && (error.code === "ENOENT" || error.code === "ENOTDIR")) {
+      return false;
+    }
+    throw error;
+  }
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }

package/src/tools/grep-output.ts

@@ -0,0 +1,130 @@
+import path from "node:path";
+import { toDisplayPath } from "./path-safety";
+import type { GrepOutputMode } from "./types";
+import { excerptGrepLines } from "./grep-snippets";
+
+export type GrepContentRecord = {
+  kind: "match" | "context";
+  filePath: string;
+  lineNumber: number;
+  /** Keep each JSON event intact so pagination cannot split a multiline match. */
+  lines: string[];
+};
+
+export type GrepRecord =
+  | { kind: "file"; filePath: string }
+  | { kind: "count"; filePath: string; count: number }
+  | GrepContentRecord;
+
+/** Decode complete protocol records only. A truncated tail is never a record. */
+export function parseGrepOutput(
+  stdout: string,
+  mode: GrepOutputMode,
+  workspaceRoot: string,
+  truncated: boolean,
+  searchCwd: string = workspaceRoot,
+): GrepRecord[] {
+  if (mode === "content") {
+    return parseJsonOutput(stdout, workspaceRoot, truncated, searchCwd);
+  }
+  const records: GrepRecord[] = [];
+  let start = 0;
+  while (start < stdout.length) {
+    const nul = stdout.indexOf("\0", start);
+    if (nul === -1) {
+      if (truncated) break;
+      throw new Error("Missing NUL path delimiter.");
+    }
+    const reportedPath = stdout.slice(start, nul);
+    if (reportedPath === "") throw new Error("Empty path in ripgrep output.");
+    const filePath = toDisplayPath(
+      workspaceRoot,
+      path.resolve(searchCwd, reportedPath),
+    );
+    if (mode === "files_with_matches") {
+      records.push({ kind: "file", filePath });
+      start = nul + 1;
+      continue;
+    }
+    const end = stdout.indexOf("\n", nul + 1);
+    if (end === -1) {
+      if (truncated) break;
+      throw new Error("Unterminated count record.");
+    }
+    const value = stdout.slice(nul + 1, end);
+    if (!/^\d+$/.test(value) || !Number.isSafeInteger(Number(value))) {
+      throw new Error("Invalid count in ripgrep output.");
+    }
+    records.push({ kind: "count", filePath, count: Number(value) });
+    start = end + 1;
+  }
+  return records;
+}
+
+function parseJsonOutput(
+  stdout: string,
+  workspaceRoot: string,
+  truncated: boolean,
+  searchCwd: string,
+): GrepRecord[] {
+  const records: GrepRecord[] = [];
+  let start = 0;
+  while (start < stdout.length) {
+    const end = stdout.indexOf("\n", start);
+    if (end === -1) {
+      if (truncated) break;
+      throw new Error("Unterminated JSON event.");
+    }
+    const event: unknown = JSON.parse(stdout.slice(start, end));
+    start = end + 1;
+    if (!isRecord(event) || typeof event.type !== "string" || !isRecord(event.data)) {
+      throw new Error("Invalid ripgrep JSON event.");
+    }
+    if (["begin", "end", "summary"].includes(event.type)) continue;
+    if (event.type !== "match" && event.type !== "context") {
+      throw new Error("Unexpected ripgrep JSON event type.");
+    }
+    const data = event.data;
+    const reportedPath = decodeText(data.path, true);
+    if (reportedPath === "") throw new Error("Empty path in ripgrep JSON event.");
+    if (
+      typeof data.line_number !== "number" ||
+      !Number.isSafeInteger(data.line_number) ||
+      data.line_number < 1
+    ) {
+      throw new Error("Invalid line number in ripgrep JSON event.");
+    }
+    const filePath = toDisplayPath(
+      workspaceRoot,
+      path.resolve(searchCwd, reportedPath),
+    );
+    records.push({
+      kind: event.type,
+      filePath,
+      lineNumber: data.line_number,
+      lines: excerptGrepLines(decodeBytes(data.lines), data.submatches),
+    });
+  }
+  return records;
+}
+
+function decodeText(value: unknown, isPath: boolean): string {
+  if (isRecord(value) && typeof value.text === "string") return value.text;
+  return new TextDecoder("utf-8", { fatal: isPath }).decode(decodeBytes(value));
+}
+
+function decodeBytes(value: unknown): Buffer {
+  if (!isRecord(value)) throw new Error("Invalid text field in ripgrep JSON event.");
+  if (typeof value.text === "string") return Buffer.from(value.text, "utf8");
+  if (
+    typeof value.bytes === "string" &&
+    /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value.bytes)
+  ) {
+    return Buffer.from(value.bytes, "base64");
+  }
+  throw new Error("Invalid text encoding in ripgrep JSON event.");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/tools/grep-pagination.ts

@@ -0,0 +1,73 @@
+import type { GrepContentRecord, GrepRecord } from "./grep-output";
+
+const defaultHeadLimit = 250;
+
+export function applyHeadLimit<T>(items: T[], limit: number | undefined, offset = 0) {
+  const effectiveLimit = limit ?? defaultHeadLimit;
+  const selected =
+    effectiveLimit === 0
+      ? items.slice(offset)
+      : items.slice(offset, offset + effectiveLimit);
+  const hasMore = offset + selected.length < items.length;
+  return {
+    items: selected,
+    totalResults: items.length,
+    returnedResults: selected.length,
+    hasMore,
+    nextOffset: hasMore ? offset + selected.length : undefined,
+    appliedLimit: hasMore ? effectiveLimit : undefined,
+  };
+}
+
+/** Match events select windows; matches encountered inside a window never expand it. */
+export function applyContentHeadLimit(
+  records: GrepRecord[],
+  limit: number | undefined,
+  offset: number,
+  context: { before: number; after: number },
+) {
+  const matches = records.filter(
+    (record): record is GrepContentRecord => record.kind === "match",
+  );
+  const page = applyHeadLimit(matches, limit, offset);
+  const windows = new Map<string, { start: number; end: number }[]>();
+  for (const match of page.items) {
+    const ranges = windows.get(match.filePath) ?? [];
+    const start = Math.max(1, match.lineNumber - context.before);
+    const end = match.lineNumber + match.lines.length - 1 + context.after;
+    const last = ranges.at(-1);
+    if (last !== undefined && start <= last.end + 1) {
+      last.end = Math.max(last.end, end);
+    } else {
+      ranges.push({ start, end });
+    }
+    windows.set(match.filePath, ranges);
+  }
+
+  const items: GrepContentRecord[] = [];
+  // rg emits each physical line once, in file/line order. Walk merged windows
+  // linearly rather than rescanning all records for every selected match.
+  const cursors = new Map<string, number>();
+  for (const record of records) {
+    if (record.kind !== "match" && record.kind !== "context") continue;
+    const ranges = windows.get(record.filePath);
+    if (ranges === undefined) continue;
+    let cursor = cursors.get(record.filePath) ?? 0;
+    for (const [index, text] of record.lines.entries()) {
+      const lineNumber = record.lineNumber + index;
+      while (cursor < ranges.length && ranges[cursor].end < lineNumber) cursor++;
+      const range = ranges[cursor];
+      if (range === undefined) break;
+      if (lineNumber >= range.start) {
+        items.push({
+          kind: record.kind,
+          filePath: record.filePath,
+          lineNumber,
+          lines: [text],
+        });
+      }
+    }
+    cursors.set(record.filePath, cursor);
+  }
+  return { ...page, items };
+}

package/src/tools/grep-path.ts

@@ -0,0 +1,11 @@
+// Quote only paths that need escaping; ordinary paths remain easy to scan/copy.
+export function formatGrepPath(filePath: string): string {
+  return /[\p{Cc}\p{Cf}"\\\u2028\u2029]/u.test(filePath)
+    ? JSON.stringify(filePath).replace(/[\p{Cc}\p{Cf}\u2028\u2029]/gu, (character) =>
+        character
+          .split("")
+          .map((unit) => `\\u${unit.charCodeAt(0).toString(16).padStart(4, "0")}`)
+          .join(""),
+      )
+    : filePath;
+}

package/src/tools/grep-snippets.ts

@@ -0,0 +1,111 @@
+const maxLineCodePoints = 500;
+const matchContextCodePoints = 100;
+
+type MatchRange = { start: number; end: number };
+
+/** rg submatch offsets address the original bytes of the entire JSON event. */
+export function excerptGrepLines(bytes: Buffer, submatches: unknown): string[] {
+  const matches = parseSubmatches(submatches, bytes.length);
+  const lines: string[] = [];
+  let start = 0;
+  let matchIndex = 0;
+  while (start < bytes.length) {
+    const newline = bytes.indexOf(10, start);
+    const end = newline === -1 ? bytes.length : newline;
+    const textEnd = end > start && bytes[end - 1] === 13 ? end - 1 : end;
+    while (matchIndex < matches.length && matches[matchIndex].end < start) {
+      matchIndex++;
+    }
+    lines.push(excerptLine(bytes.subarray(start, textEnd), matches, matchIndex, start));
+    start = end + 1;
+  }
+  return lines;
+}
+
+function excerptLine(
+  bytes: Buffer,
+  matches: MatchRange[],
+  matchIndex: number,
+  lineStart: number,
+): string {
+  const points = [...bytes.toString("utf8")];
+  if (points.length <= maxLineCodePoints) return points.join("");
+
+  const windows: MatchRange[] = [];
+  const codePointOffset = createCodePointOffsetReader(bytes);
+  let remaining = maxLineCodePoints;
+  for (let index = matchIndex; index < matches.length && remaining > 0; index++) {
+    const match = matches[index];
+    if (match.start > lineStart + bytes.length) break;
+    if (match.end === lineStart && match.start < lineStart) continue;
+    const matchStart = codePointOffset(match.start - lineStart);
+    const matchEnd = codePointOffset(match.end - lineStart);
+    const previous = windows.at(-1);
+    // Reserve room for the match even when earlier windows used most of the budget.
+    const before = Math.min(matchContextCodePoints, Math.floor(remaining / 2));
+    const start = Math.max(0, matchStart - before);
+    const end = Math.min(points.length, matchEnd + matchContextCodePoints);
+    if (previous !== undefined && start <= previous.end) {
+      const extension = Math.min(remaining, Math.max(0, end - previous.end));
+      previous.end += extension;
+      remaining -= extension;
+    } else {
+      const keptEnd = Math.min(end, start + remaining);
+      windows.push({ start, end: keptEnd });
+      remaining -= keptEnd - start;
+    }
+  }
+  // Context events (and legacy fixtures without submatches) still retain useful text.
+  if (windows.length === 0) windows.push({ start: 0, end: maxLineCodePoints });
+
+  const parts: string[] = [];
+  let cursor = 0;
+  for (const window of windows) {
+    if (window.start > cursor) parts.push(omission(window.start - cursor));
+    parts.push(points.slice(window.start, window.end).join(""));
+    cursor = window.end;
+  }
+  if (cursor < points.length) parts.push(omission(points.length - cursor));
+  return parts.join("");
+}
+
+function createCodePointOffsetReader(bytes: Buffer): (offset: number) => number {
+  let byteCursor = 0;
+  let pointCursor = 0;
+  // Submatches are ordered and non-overlapping; scan each prefix only once.
+  return (offset) => {
+    const end = Math.max(0, Math.min(offset, bytes.length));
+    pointCursor += [...bytes.subarray(byteCursor, end).toString("utf8")].length;
+    byteCursor = end;
+    return pointCursor;
+  };
+}
+
+function omission(count: number): string {
+  return `[... ${count} code points omitted ...]`;
+}
+
+function parseSubmatches(value: unknown, byteLength: number): MatchRange[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) throw new Error("Invalid ripgrep submatches.");
+  let previousEnd = 0;
+  return value.map((item: unknown) => {
+    if (
+      typeof item !== "object" ||
+      item === null ||
+      !("start" in item) ||
+      !("end" in item) ||
+      typeof item.start !== "number" ||
+      typeof item.end !== "number" ||
+      !Number.isSafeInteger(item.start) ||
+      !Number.isSafeInteger(item.end) ||
+      item.start < previousEnd ||
+      item.end < item.start ||
+      item.end > byteLength
+    ) {
+      throw new Error("Invalid ripgrep submatch offsets.");
+    }
+    previousEnd = item.end;
+    return { start: item.start, end: item.end };
+  });
+}