tinker-agent 1.0.65

package/src/tools/registry.ts

@@ -0,0 +1,213 @@
+import { createBashToolExecutor } from "./bash";
+import { ShellTaskManager } from "./bash-task";
+import { createCwdState } from "./cwd-state";
+import { createEditToolExecutor } from "./edit";
+import { createGlobToolExecutor } from "./glob";
+import { createGrepToolExecutor } from "./grep";
+import { createReadToolExecutor } from "./read";
+import { createRecallToolExecutor } from "./recall";
+import { createTaskListToolExecutor } from "./task-list";
+import { createTaskOutputToolExecutor } from "./task-output-tool";
+import { createTaskStopToolExecutor } from "./task-stop";
+import { createWebFetchToolExecutor } from "./web-fetch";
+import type { Refiner } from "./web-fetch/refiner";
+import { createWebSearchToolExecutor } from "./web-search";
+import { createWriteToolExecutor } from "./write";
+import { cancellationError, throwIfTurnCancelled } from "../agent/turn-cancellation";
+import type {
+  RuntimeSessionContext,
+  SessionDisposeReason,
+} from "../agent/runtime-session";
+import type {
+  ReadSnapshotStore,
+  ToolDefinition,
+  ToolExecutionContext,
+  ToolExecutor,
+  ToolRawResult,
+} from "./types";
+import type { ToolCall } from "../agent/types";
+import type { SessionHistoryReader } from "../session/session-history-reader";
+import { ToolExecutionFatalError } from "./types";
+
+export class ToolRegistry {
+  private readonly tools = new Map<string, ToolExecutor>();
+  private readonly sources = new Map<string, string>();
+
+  register(tool: ToolExecutor, source = "built-in"): void {
+    const name = tool.definition.name;
+    const existingSource = this.sources.get(name);
+    if (existingSource !== undefined) {
+      throw new Error(
+        `Tool ${name} from ${source} conflicts with an existing registration from ${existingSource}.`,
+      );
+    }
+    this.tools.set(name, tool);
+    this.sources.set(name, source);
+  }
+
+  definitions(): ToolDefinition[] {
+    return [...this.tools.values()].map((tool) => tool.definition);
+  }
+
+  get(name: string): ToolExecutor | undefined {
+    return this.tools.get(name);
+  }
+}
+
+export class ToolRuntime {
+  constructor(private readonly registry: ToolRegistry) {}
+
+  async execute(call: ToolCall, context: ToolExecutionContext): Promise<ToolRawResult> {
+    throwIfTurnCancelled(context.signal);
+
+    if (call.argsParseError !== undefined) {
+      return {
+        kind: "generic",
+        ok: false,
+        toolName: call.name,
+        error: `Invalid tool arguments JSON: ${call.argsParseError}`,
+      };
+    }
+
+    const tool = this.registry.get(call.name);
+
+    if (tool === undefined) {
+      return {
+        kind: "generic",
+        ok: false,
+        toolName: call.name,
+        error: `Unknown tool: ${call.name}`,
+      };
+    }
+
+    try {
+      return await tool.execute(call.args, call, context);
+    } catch (error) {
+      if (context.signal.aborted) {
+        throw cancellationError(context.signal, error);
+      }
+      if (error instanceof ToolExecutionFatalError) {
+        throw error;
+      }
+
+      return {
+        kind: "generic",
+        ok: false,
+        toolName: call.name,
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+}
+
+export type DefaultTooling = {
+  registry: ToolRegistry;
+  runtime: ToolRuntime;
+  snapshots: ReadSnapshotStore;
+  bashState: BashToolingState;
+  taskManager: ShellTaskManager;
+  dispose(reason?: SessionDisposeReason["type"]): Promise<void>;
+};
+
+export type BashToolingState = {
+  cwd: string;
+  sessionId: string;
+  workspaceRoot: string;
+};
+
+export function createDefaultTooling(options: {
+  workspaceRoot: string;
+  runtimeSession: RuntimeSessionContext;
+  historyReader: SessionHistoryReader;
+  maxReadContentBytes?: number;
+  exaApiKey?: string;
+  webFetchRefiner?: Refiner;
+  taskStopGraceMs?: number;
+}): DefaultTooling {
+  const snapshots: ReadSnapshotStore = new Map();
+  const registry = new ToolRegistry();
+  const runtimeSession = options.runtimeSession;
+  const cwdState = createCwdState(options.workspaceRoot);
+  const taskManager = new ShellTaskManager({
+    workspaceRoot: options.workspaceRoot,
+    cwdState,
+    runtimeSession,
+    stopGraceMs: options.taskStopGraceMs,
+  });
+
+  registry.register(
+    createGlobToolExecutor({
+      workspaceRoot: options.workspaceRoot,
+    }),
+  );
+  registry.register(
+    createGrepToolExecutor({
+      workspaceRoot: options.workspaceRoot,
+      cwdState,
+    }),
+  );
+  registry.register(
+    createReadToolExecutor({
+      workspaceRoot: options.workspaceRoot,
+      snapshots,
+      maxContentBytes: options.maxReadContentBytes,
+    }),
+  );
+  registry.register(createRecallToolExecutor({ historyReader: options.historyReader }));
+  registry.register(
+    createWriteToolExecutor({
+      workspaceRoot: options.workspaceRoot,
+      snapshots,
+    }),
+  );
+  registry.register(
+    createEditToolExecutor({
+      workspaceRoot: options.workspaceRoot,
+      snapshots,
+    }),
+  );
+  registry.register(
+    createBashToolExecutor({
+      workspaceRoot: options.workspaceRoot,
+      cwdState,
+      taskManager,
+    }),
+  );
+  registry.register(createTaskListToolExecutor({ taskManager }));
+  registry.register(createTaskOutputToolExecutor({ taskManager }));
+  registry.register(createTaskStopToolExecutor({ taskManager }));
+
+  const exaApiKey = options.exaApiKey ?? process.env.EXA_API_KEY;
+  const hasExaKey = exaApiKey !== undefined && exaApiKey.trim() !== "";
+
+  if (hasExaKey) {
+    registry.register(createWebSearchToolExecutor({ apiKey: exaApiKey }));
+  }
+
+  registry.register(
+    createWebFetchToolExecutor({
+      exaApiKey: hasExaKey ? exaApiKey : undefined,
+      refiner: options.webFetchRefiner,
+    }),
+  );
+
+  return {
+    registry,
+    runtime: new ToolRuntime(registry),
+    snapshots,
+    taskManager,
+    bashState: {
+      get cwd() {
+        return cwdState.cwd;
+      },
+      set cwd(value: string) {
+        cwdState.cwd = value;
+      },
+      sessionId: runtimeSession.sessionId,
+      workspaceRoot: options.workspaceRoot,
+    },
+    async dispose(reason = "oneshot_complete") {
+      await taskManager.shutdown(reason);
+    },
+  };
+}

package/src/tools/ripgrep.ts

@@ -0,0 +1,220 @@
+import { execFile } from "node:child_process";
+import { cancellationError, throwIfTurnCancelled } from "../agent/turn-cancellation";
+
+export const RIPGREP_MISSING_ERROR =
+  "ripgrep is required. Install rg and ensure it is available on PATH.";
+
+const defaultTimeoutMs = 20_000;
+const defaultMaxBufferBytes = 20_000_000;
+
+export type RipgrepResult = {
+  ok: boolean;
+  lines: string[];
+  exitCode?: number;
+  truncated: boolean;
+  error?: string;
+};
+
+export type RipgrepOptions = {
+  signal: AbortSignal;
+  timeoutMs?: number;
+  maxBufferBytes?: number;
+};
+
+export function findRipgrepCommand(): string {
+  return process.env.TINKER_RIPGREP_PATH ?? "rg";
+}
+
+export async function ripGrep(
+  args: string[],
+  options: RipgrepOptions,
+): Promise<RipgrepResult> {
+  throwIfTurnCancelled(options.signal);
+  const timeoutMs =
+    options.timeoutMs ??
+    parsePositiveInteger(process.env.TINKER_GREP_TIMEOUT_MS, defaultTimeoutMs);
+  const maxBufferBytes =
+    options.maxBufferBytes ??
+    parsePositiveInteger(
+      process.env.TINKER_GREP_MAX_BUFFER_BYTES,
+      defaultMaxBufferBytes,
+    );
+
+  const first = await runRipgrep(args, timeoutMs, maxBufferBytes, options.signal);
+  if (first.retryWithSingleThread) {
+    throwIfTurnCancelled(options.signal);
+    return finalizeResult(
+      await runRipgrep(["-j", "1", ...args], timeoutMs, maxBufferBytes, options.signal),
+    );
+  }
+
+  return finalizeResult(first);
+}
+
+type RipgrepAttempt = {
+  ok: boolean;
+  stdout: string;
+  exitCode?: number;
+  truncated: boolean;
+  error?: string;
+  retryWithSingleThread?: boolean;
+};
+
+function runRipgrep(
+  args: string[],
+  timeoutMs: number,
+  maxBufferBytes: number,
+  signal: AbortSignal,
+): Promise<RipgrepAttempt> {
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) {
+      reject(cancellationError(signal));
+      return;
+    }
+
+    execFile(
+      findRipgrepCommand(),
+      args,
+      { timeout: timeoutMs, maxBuffer: maxBufferBytes, signal },
+      (error, stdout, stderr) => {
+        if (signal.aborted) {
+          reject(cancellationError(signal, error));
+          return;
+        }
+
+        if (error === null) {
+          resolve({ ok: true, stdout, exitCode: 0, truncated: false });
+          return;
+        }
+
+        const execError = error as Error & {
+          killed?: boolean;
+          signal?: string | null;
+          code?: number | string;
+        };
+
+        if (execError.code === "ENOENT") {
+          resolve({
+            ok: false,
+            stdout: "",
+            truncated: false,
+            error: RIPGREP_MISSING_ERROR,
+          });
+          return;
+        }
+
+        if (isEagainError(execError, stderr)) {
+          resolve({
+            ok: false,
+            stdout: "",
+            truncated: false,
+            retryWithSingleThread: true,
+          });
+          return;
+        }
+
+        if (execError.code === 1 && stderr.trim() === "") {
+          resolve({ ok: true, stdout, exitCode: 1, truncated: false });
+          return;
+        }
+
+        if (execError.killed === true || typeof execError.signal === "string") {
+          resolve({
+            ok: false,
+            stdout,
+            truncated: true,
+            error: `ripgrep timed out after ${timeoutMs}ms. Narrow the search with path, glob, or a more specific pattern.`,
+          });
+          return;
+        }
+
+        if (execError.message.includes("maxBuffer")) {
+          resolve({
+            ok: false,
+            stdout,
+            truncated: true,
+            error: `ripgrep output exceeded ${maxBufferBytes} bytes. Narrow the search with path, glob, or a more specific pattern.`,
+          });
+          return;
+        }
+
+        resolve({
+          ok: false,
+          stdout,
+          exitCode: typeof execError.code === "number" ? execError.code : undefined,
+          truncated: false,
+          error: stderr.trim() !== "" ? stderr.trim() : execError.message,
+        });
+      },
+    );
+  });
+}
+
+function finalizeResult(attempt: RipgrepAttempt): RipgrepResult {
+  const lines = splitCompleteLines(attempt.stdout, attempt.truncated);
+
+  if (attempt.ok) {
+    return {
+      ok: true,
+      lines,
+      exitCode: attempt.exitCode,
+      truncated: false,
+    };
+  }
+
+  if (attempt.truncated && lines.length > 0) {
+    return {
+      ok: true,
+      lines,
+      exitCode: attempt.exitCode,
+      truncated: true,
+      error: attempt.error,
+    };
+  }
+
+  return {
+    ok: false,
+    lines: [],
+    exitCode: attempt.exitCode,
+    truncated: attempt.truncated,
+    error: attempt.error ?? "ripgrep failed.",
+  };
+}
+
+function splitCompleteLines(stdout: string, droppedPartialTail: boolean): string[] {
+  if (stdout === "") {
+    return [];
+  }
+
+  const lines = stdout.split("\n");
+  const last = lines.at(-1);
+
+  if (last === "") {
+    lines.pop();
+  } else if (droppedPartialTail) {
+    lines.pop();
+  }
+
+  return lines;
+}
+
+function isEagainError(
+  error: Error & { code?: number | string },
+  stderr: string,
+): boolean {
+  return (
+    error.code === "EAGAIN" ||
+    error.message.includes("EAGAIN") ||
+    error.message.includes("Resource temporarily unavailable") ||
+    stderr.includes("Resource temporarily unavailable")
+  );
+}
+
+function parsePositiveInteger(value: string | undefined, fallback: number): number {
+  if (value === undefined || value.trim() === "") {
+    return fallback;
+  }
+
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
+}

package/src/tools/task-list.ts

@@ -0,0 +1,59 @@
+import type { ShellTaskManager } from "./bash-task";
+import { throwIfTurnCancelled } from "../agent/turn-cancellation";
+import { defineToolExecutor } from "./types";
+import type { TaskListRawResult, ToolExecutionContext, ToolExecutor } from "./types";
+
+export function createTaskListToolExecutor(options: {
+  taskManager: ShellTaskManager;
+}): ToolExecutor {
+  return defineToolExecutor("task_list", {
+    definition: {
+      name: "TaskList",
+      description: "List background shell tasks in the current session.",
+      parameters: {
+        type: "object",
+        additionalProperties: false,
+        properties: {},
+      },
+    },
+    async execute(
+      args,
+      _call,
+      context: ToolExecutionContext,
+    ): Promise<TaskListRawResult> {
+      throwIfTurnCancelled(context.signal);
+      if (!isRecord(args)) {
+        return {
+          ok: false,
+          runningCount: 0,
+          tasks: [],
+          error: "TaskList arguments must be an object.",
+        };
+      }
+
+      const unexpected = Object.keys(args)[0];
+      if (unexpected !== undefined) {
+        return {
+          ok: false,
+          runningCount: 0,
+          tasks: [],
+          error: `TaskList received unexpected argument: ${unexpected}.`,
+        };
+      }
+
+      const tasks = options.taskManager.listBackgroundTasks();
+      throwIfTurnCancelled(context.signal);
+      return {
+        ok: true,
+        runningCount: tasks.filter(
+          (task) => task.status === "running" || task.status === "stopping",
+        ).length,
+        tasks,
+      };
+    },
+  });
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/tools/task-output-snapshot.ts

@@ -0,0 +1,47 @@
+import { Buffer } from "node:buffer";
+import type { TaskOutputSnapshot } from "./task-output";
+
+const maxPreviewLines = 200;
+const previewEdgeLines = 100;
+
+export function buildOutputSnapshotFromText(bytes: Buffer): TaskOutputSnapshot {
+  const text = bytes.toString("utf8");
+  const lines = splitLines(text);
+
+  if (lines.length <= maxPreviewLines) {
+    return {
+      outputBytes: bytes.byteLength,
+      outputLines: lines.length,
+      preview: lines.join("\n"),
+      truncated: false,
+    };
+  }
+
+  const omittedLines = lines.length - maxPreviewLines;
+  const omittedStartLine = previewEdgeLines + 1;
+  const omittedEndLine = lines.length - previewEdgeLines;
+  return {
+    outputBytes: bytes.byteLength,
+    outputLines: lines.length,
+    preview: [
+      ...lines.slice(0, previewEdgeLines),
+      `... output omitted: lines ${omittedStartLine}-${omittedEndLine} (${omittedLines} ${omittedLines === 1 ? "line" : "lines"}). Full output is available at outputFilePath.`,
+      ...lines.slice(-previewEdgeLines),
+    ].join("\n"),
+    truncated: true,
+    omittedLines,
+  };
+}
+
+function splitLines(text: string): string[] {
+  if (text.length === 0) {
+    return [];
+  }
+
+  const lines = text.split(/\r\n|\n|\r/);
+  if (text.endsWith("\n") || text.endsWith("\r")) {
+    lines.pop();
+  }
+
+  return lines;
+}

package/src/tools/task-output-tool.ts

@@ -0,0 +1,62 @@
+import type { ShellTaskManager } from "./bash-task";
+import { throwIfTurnCancelled } from "../agent/turn-cancellation";
+import { parseTaskIdArgs } from "./task-tool-args";
+import { defineToolExecutor } from "./types";
+import type { TaskOutputRawResult, ToolExecutionContext, ToolExecutor } from "./types";
+
+export function createTaskOutputToolExecutor(options: {
+  taskManager: ShellTaskManager;
+}): ToolExecutor {
+  return defineToolExecutor("task_output", {
+    definition: {
+      name: "TaskOutput",
+      description: "Get the current status and latest output of a shell task.",
+      parameters: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          task_id: {
+            type: "string",
+            description: "The task ID returned by Bash or TaskList.",
+          },
+        },
+        required: ["task_id"],
+      },
+    },
+    async execute(
+      args,
+      _call,
+      context: ToolExecutionContext,
+    ): Promise<TaskOutputRawResult> {
+      throwIfTurnCancelled(context.signal);
+      const parsed = parseTaskIdArgs(args, "TaskOutput");
+      if (!parsed.ok) {
+        return { ok: false, taskId: "", error: parsed.error };
+      }
+
+      const inspection = options.taskManager.inspectTask(parsed.taskId);
+      throwIfTurnCancelled(context.signal);
+      if (inspection === undefined) {
+        return {
+          ok: false,
+          taskId: parsed.taskId,
+          error: `Unknown task ID: ${parsed.taskId}`,
+        };
+      }
+
+      return {
+        ok: true,
+        taskId: parsed.taskId,
+        task: inspection.task,
+        status: inspection.task.status,
+        command: inspection.task.command,
+        outputBytes: inspection.output.outputBytes,
+        outputLines: inspection.output.outputLines,
+        preview: inspection.output.preview,
+        truncated: inspection.output.truncated,
+        omittedLines: inspection.output.omittedLines,
+        outputFilePath: inspection.task.outputFilePath,
+      };
+    },
+  });
+}