tinker-agent 2.8.0 → 2.10.0

package/src/tools/bash-task.ts

@@ -14,12 +14,8 @@ import {
   spawnShellProcess,
 } from "./shell-process";
 import { TaskOutput, type TaskOutputSnapshot } from "./task-output";
-import {
-  createTerminalScreen,
-  TERMINAL_SCREEN_COLUMNS,
-  TERMINAL_SCREEN_ROWS,
-  type TerminalScreen,
-} from "./terminal-screen";
+import type { TaskOutputRangeRequest } from "./task-output-range";
+import { createTerminalScreen, type TerminalScreen } from "./terminal-screen";
 import { resolveWorkspaceStorageRoot } from "../session/workspace-storage";
 
 export type ShellTaskStatus =
@@ -145,6 +141,8 @@ export class ShellTaskManager {
     description: string;
     origin: ShellTaskOrigin;
     tty: boolean;
+    cols?: number;
+    rows?: number;
   }): Promise<ShellTaskHandle> {
     if (!this.acceptingTasks) {
       throw new Error("Cannot start a Bash task after task manager shutdown.");
@@ -163,7 +161,7 @@ export class ShellTaskManager {
       throw new Error("Cannot start a Bash task after task manager shutdown.");
     }
 
-    const terminalScreen = input.tty ? createTerminalScreen() : undefined;
+    const terminalScreen = input.tty ? createTerminalScreen(input) : undefined;
     let shellProcess: ShellProcessHandle;
     try {
       shellProcess = await spawnShellProcess({
@@ -171,6 +169,8 @@ export class ShellTaskManager {
         command: input.command,
         cwd: this.options.cwdState.cwd,
         cwdFilePath,
+        cols: terminalScreen?.columns,
+        rows: terminalScreen?.rows,
         onOutput(bytes) {
           output.write(Buffer.from(bytes));
           if (terminalScreen !== undefined) {
@@ -259,7 +259,11 @@ export class ShellTaskManager {
     return this.inspection(task);
   }
 
-  async inspectTaskOutput(taskId: string): Promise<ShellTaskInspection | undefined> {
+  async inspectTaskOutput(
+    taskId: string,
+    range?: TaskOutputRangeRequest,
+    signal?: AbortSignal,
+  ): Promise<ShellTaskInspection | undefined> {
     const task = this.tasks.get(taskId);
     if (task === undefined) {
       return undefined;
@@ -271,7 +275,20 @@ export class ShellTaskManager {
     } else {
       await task.terminalScreen?.flush();
     }
-    return this.inspection(task);
+    const inspection = this.inspection(task);
+    if (range !== undefined && task.mode !== "pty") {
+      const output = await task.output.readRange(range, signal);
+      return {
+        ...inspection,
+        task: {
+          ...inspection.task,
+          outputBytes: output.outputBytes,
+          outputLines: output.outputLines,
+        },
+        output,
+      };
+    }
+    return inspection;
   }
 
   taskCompletion(taskId: string): Promise<ShellTaskSnapshot> {
@@ -399,8 +416,15 @@ export class ShellTaskManager {
     if (!(await completesWithin(task.completion, this.stopGraceMs))) {
       this.synchronizeTerminalState(task);
       if (!isTerminalStatus(task.status)) {
-        signalProcessGroup(task, "SIGKILL");
-        escalated = true;
+        escalated = signalProcessGroup(task, "SIGKILL");
+        if (
+          !(await completesWithin(task.completion, this.stopGraceMs)) &&
+          !task.process.outputClosed
+        ) {
+          task.error =
+            "Task output remained open after forced termination; closed local output streams. Descendant processes may still be running.";
+          task.process.close();
+        }
       }
     }
 
@@ -456,8 +480,8 @@ export class ShellTaskManager {
   private async monitorTask(task: ManagedShellTask): Promise<ShellTaskSnapshot> {
     const result = await task.process.wait();
 
-    this.applyTermination(task, result);
     await task.process.waitForOutputClose();
+    this.applyTermination(task, result);
     await task.output.end();
     if (task.terminalScreen !== undefined) {
       await task.terminalScreen.flush();
@@ -487,9 +511,9 @@ export class ShellTaskManager {
     }
 
     task.endedAt ??= new Date().toISOString();
-    if (result.error !== undefined) {
+    if (result.error !== undefined || task.error !== undefined) {
       task.status = "failed";
-      task.error = result.error;
+      task.error ??= result.error;
       return;
     }
 
@@ -504,7 +528,9 @@ export class ShellTaskManager {
   }
 
   private synchronizeTerminalState(task: ManagedShellTask): void {
-    if (isTerminalStatus(task.status)) {
+    // An exited wrapper can leave children holding its output descriptors open.
+    // Keep the task stoppable until both process exit and output closure occur.
+    if (isTerminalStatus(task.status) || !task.process.outputClosed) {
       return;
     }
 
@@ -558,8 +584,8 @@ export class ShellTaskManager {
       ...(screen === undefined
         ? {}
         : {
-            screenRows: TERMINAL_SCREEN_ROWS,
-            screenColumns: TERMINAL_SCREEN_COLUMNS,
+            screenRows: task.terminalScreen?.rows,
+            screenColumns: task.terminalScreen?.columns,
             screen,
           }),
     };
@@ -589,13 +615,15 @@ export class ShellTaskManager {
 function signalProcessGroup(
   task: ManagedShellTask,
   signal: "SIGTERM" | "SIGKILL",
-): void {
+): boolean {
   try {
     process.kill(-task.processGroupId, signal);
+    return true;
   } catch (error) {
     if (!isNoSuchProcess(error)) {
       throw error;
     }
+    return false;
   }
 }
 

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;
+}