tinker-agent 1.0.65

package/src/tools/read.ts

@@ -0,0 +1,319 @@
+import { readFile, stat } from "node:fs/promises";
+import { Buffer } from "node:buffer";
+import { cancellationError, throwIfTurnCancelled } from "../agent/turn-cancellation";
+import { sha256Bytes } from "./hash";
+import { resolveWorkspacePath } from "./path-safety";
+import { defineToolExecutor } from "./types";
+import type {
+  ReadFileRawResult,
+  ReadSnapshotStore,
+  ToolExecutionContext,
+  ToolExecutor,
+} from "./types";
+
+type ReadArgs = {
+  file_path: string;
+  offset?: number;
+  limit?: number;
+};
+
+export type ReadToolOptions = {
+  workspaceRoot: string;
+  snapshots: ReadSnapshotStore;
+  maxContentBytes?: number;
+};
+
+export const DEFAULT_MAX_READ_CONTENT_BYTES = 256 * 1024;
+
+export function createReadToolExecutor(options: ReadToolOptions): ToolExecutor {
+  const maxContentBytes = options.maxContentBytes ?? DEFAULT_MAX_READ_CONTENT_BYTES;
+
+  return defineToolExecutor("read", {
+    definition: {
+      name: "Read",
+      description:
+        "Read a file from the local workspace. Use offset and limit for line ranges.",
+      parameters: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          file_path: {
+            type: "string",
+            description: "Workspace-relative path or absolute path.",
+          },
+          offset: {
+            type: "integer",
+            minimum: 1,
+            description: "1-based line number to start reading from.",
+          },
+          limit: {
+            type: "integer",
+            minimum: 1,
+            description: "Maximum number of lines to read.",
+          },
+        },
+        required: ["file_path"],
+      },
+    },
+    async execute(
+      args,
+      _call,
+      context: ToolExecutionContext,
+    ): Promise<ReadFileRawResult> {
+      throwIfTurnCancelled(context.signal);
+      const parsed = parseReadArgs(args);
+
+      if (!parsed.ok) {
+        return {
+          ok: false,
+          filePath: "",
+          error: parsed.error,
+        };
+      }
+
+      const input = parsed.value;
+      let absolutePath: string;
+
+      try {
+        absolutePath = resolveWorkspacePath(options.workspaceRoot, input.file_path);
+      } catch (error) {
+        if (context.signal.aborted) {
+          throw cancellationError(context.signal, error);
+        }
+
+        return {
+          ok: false,
+          filePath: input.file_path,
+          error: errorMessage(error),
+        };
+      }
+
+      try {
+        const info = await stat(absolutePath);
+        throwIfTurnCancelled(context.signal);
+
+        if (!info.isFile()) {
+          return {
+            ok: false,
+            filePath: input.file_path,
+            absolutePath,
+            error: "Path is not a file.",
+          };
+        }
+
+        const bytes = await readFile(absolutePath);
+        throwIfTurnCancelled(context.signal);
+        const currentInfo = await stat(absolutePath);
+        throwIfTurnCancelled(context.signal);
+
+        if (currentInfo.mtimeMs > info.mtimeMs) {
+          return {
+            ok: false,
+            filePath: input.file_path,
+            absolutePath,
+            error: "File changed while it was being read. Read it again.",
+          };
+        }
+
+        const sha256 = sha256Bytes(bytes);
+        const text = bytes.toString("utf8");
+        const lines = splitLines(text);
+        const offset = input.offset ?? 1;
+
+        if (lines.length === 0) {
+          if (input.offset !== undefined || input.limit !== undefined) {
+            return {
+              ok: false,
+              filePath: input.file_path,
+              absolutePath,
+              error: "File is empty. Omit offset and limit to read the empty file.",
+            };
+          }
+
+          options.snapshots.set(absolutePath, {
+            sha256,
+            mtimeMs: currentInfo.mtimeMs,
+            source: "read",
+          });
+
+          return {
+            ok: true,
+            filePath: input.file_path,
+            absolutePath,
+            content: "",
+            contentBytes: 0,
+            sizeBytes: currentInfo.size,
+            totalLines: 0,
+            sha256,
+          };
+        }
+
+        if (offset > lines.length) {
+          return {
+            ok: false,
+            filePath: input.file_path,
+            absolutePath,
+            error: `Read.offset ${offset} exceeds the file's ${lines.length} lines.`,
+          };
+        }
+
+        const startIndex = offset - 1;
+        const selectedLines = lines.slice(
+          startIndex,
+          input.limit === undefined ? undefined : startIndex + input.limit,
+        );
+        const selectedText = selectedLines.join("\n");
+        const contentBytes = Buffer.byteLength(selectedText, "utf8");
+        const endLine = offset + selectedLines.length - 1;
+
+        if (contentBytes > maxContentBytes) {
+          return {
+            ok: false,
+            filePath: input.file_path,
+            absolutePath,
+            sizeBytes: currentInfo.size,
+            totalLines: lines.length,
+            startLine: offset,
+            endLine,
+            error: readSizeError({
+              contentBytes,
+              endLine,
+              explicitLimit: input.limit !== undefined,
+              maxContentBytes,
+              selectedLineCount: selectedLines.length,
+              startLine: offset,
+            }),
+          };
+        }
+
+        options.snapshots.set(absolutePath, {
+          sha256,
+          mtimeMs: currentInfo.mtimeMs,
+          source: "read",
+        });
+
+        return {
+          ok: true,
+          filePath: input.file_path,
+          absolutePath,
+          content: selectedText,
+          contentBytes,
+          sizeBytes: currentInfo.size,
+          totalLines: lines.length,
+          startLine: offset,
+          endLine,
+          sha256,
+        };
+      } catch (error) {
+        if (context.signal.aborted) {
+          throw cancellationError(context.signal, error);
+        }
+
+        return {
+          ok: false,
+          filePath: input.file_path,
+          absolutePath,
+          error: errorMessage(error),
+        };
+      }
+    },
+  });
+}
+
+function parseReadArgs(
+  args: unknown,
+): { ok: true; value: ReadArgs } | { ok: false; error: string } {
+  if (!isRecord(args)) {
+    return { ok: false, error: "Read arguments must be an object." };
+  }
+
+  if (typeof args.file_path !== "string") {
+    return { ok: false, error: "Read.file_path must be a string." };
+  }
+
+  const offset = parseOptionalPositiveInteger(args.offset, "Read.offset");
+  if (!offset.ok) {
+    return offset;
+  }
+
+  const limit = parseOptionalPositiveInteger(args.limit, "Read.limit");
+  if (!limit.ok) {
+    return limit;
+  }
+
+  return {
+    ok: true,
+    value: {
+      file_path: args.file_path,
+      offset: offset.value,
+      limit: limit.value,
+    },
+  };
+}
+
+function parseOptionalPositiveInteger(
+  value: unknown,
+  name: string,
+): { ok: true; value?: number } | { ok: false; error: string } {
+  if (value === undefined) {
+    return { ok: true };
+  }
+
+  if (!Number.isInteger(value) || typeof value !== "number" || value < 1) {
+    return { ok: false, error: `${name} must be a positive integer.` };
+  }
+
+  return { ok: true, value };
+}
+
+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;
+}
+
+function readSizeError(input: {
+  contentBytes: number;
+  endLine: number;
+  explicitLimit: boolean;
+  maxContentBytes: number;
+  selectedLineCount: number;
+  startLine: number;
+}): string {
+  if (input.selectedLineCount === 1) {
+    return (
+      `Line ${input.startLine} is ${input.contentBytes} bytes and exceeds the ` +
+      `${input.maxContentBytes}-byte Read limit. This line cannot be read with ` +
+      "line-based pagination."
+    );
+  }
+
+  if (input.explicitLimit) {
+    return (
+      `Requested lines ${input.startLine}-${input.endLine} contain ` +
+      `${input.contentBytes} bytes and exceed the ${input.maxContentBytes}-byte ` +
+      "Read limit. Reduce limit to request a smaller line range."
+    );
+  }
+
+  return (
+    `File content (${input.contentBytes} bytes) exceeds maximum allowed size ` +
+    `(${input.maxContentBytes} bytes). Use offset and limit parameters to read ` +
+    "specific portions of the file."
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/tools/recall.ts

@@ -0,0 +1,400 @@
+import { Buffer } from "node:buffer";
+import { throwIfTurnCancelled } from "../agent/turn-cancellation";
+import {
+  MessageSourceParseError,
+  parseMessageSource,
+  type MessageSource,
+} from "../context/context-source";
+import { SessionError } from "../session/session-errors";
+import {
+  RecallHistoryError,
+  type RecallRole,
+  type RecallSearchFilters,
+  type SessionHistoryReader,
+} from "../session/session-history-reader";
+import {
+  defineToolExecutor,
+  ToolExecutionFatalError,
+  type RecallRawResult,
+  type RecallToolErrorCode,
+  type ToolExecutionContext,
+  type ToolExecutor,
+} from "./types";
+
+type RecallSearchArgs = {
+  mode: "search";
+  query: string;
+  roles?: RecallRole[];
+  toolNames?: string[];
+  turnFrom?: number;
+  turnTo?: number;
+  limit: number;
+  offset: number;
+  snapshotThroughOrdinal?: number;
+};
+
+type RecallGetArgs = {
+  mode: "get";
+  source: MessageSource;
+  byteOffset: number;
+  byteLimit: number;
+};
+
+type ParsedRecallArgs = RecallSearchArgs | RecallGetArgs;
+
+type ParseResult =
+  | { ok: true; value: ParsedRecallArgs }
+  | {
+      ok: false;
+      mode: "search" | "get";
+      errorCode: "RECALL_ARGS_INVALID" | "RECALL_SOURCE_INVALID";
+      error: string;
+    };
+
+export function createRecallToolExecutor(options: {
+  historyReader: SessionHistoryReader;
+}): ToolExecutor {
+  return defineToolExecutor("recall", {
+    definition: {
+      name: "Recall",
+      description:
+        "Search or retrieve immutable model-visible history from the current session. Results are historical snapshots and may differ from the current workspace. Use search to find a source, get to retrieve exact content, and Read/Grep for current files.",
+      parameters: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          mode: { type: "string", enum: ["search", "get"] },
+          query: { type: "string", maxLength: 1024 },
+          roles: {
+            type: "array",
+            minItems: 1,
+            uniqueItems: true,
+            items: { type: "string", enum: ["user", "assistant", "tool"] },
+          },
+          tool_names: {
+            type: "array",
+            minItems: 1,
+            maxItems: 16,
+            uniqueItems: true,
+            items: { type: "string", minLength: 1 },
+          },
+          turn_from: { type: "integer", minimum: 1 },
+          turn_to: { type: "integer", minimum: 1 },
+          limit: { type: "integer", minimum: 1, maximum: 20, default: 10 },
+          offset: { type: "integer", minimum: 0, default: 0 },
+          snapshot_through_ordinal: { type: "integer", minimum: 1 },
+          source: { type: "string" },
+          byte_offset: { type: "integer", minimum: 0, default: 0 },
+          byte_limit: {
+            type: "integer",
+            minimum: 256,
+            maximum: 20_000,
+            default: 12_000,
+          },
+        },
+        required: ["mode"],
+      },
+    },
+    async execute(
+      args,
+      _call,
+      context: ToolExecutionContext,
+    ): Promise<RecallRawResult> {
+      throwIfTurnCancelled(context.signal);
+      const parsed = parseRecallArgs(args);
+      if (!parsed.ok) {
+        return recallFailure(parsed.mode, parsed.errorCode, parsed.error);
+      }
+
+      try {
+        if (parsed.value.mode === "get") {
+          const page = options.historyReader.get({
+            source: parsed.value.source,
+            byteOffset: parsed.value.byteOffset,
+            byteLimit: parsed.value.byteLimit,
+          });
+          throwIfTurnCancelled(context.signal);
+          return { ok: true, mode: "get", historical: true, page };
+        }
+
+        const input = parsed.value;
+        const page = options.historyReader.search({
+          query: input.query,
+          ...(input.roles === undefined ? {} : { roles: input.roles }),
+          ...(input.toolNames === undefined ? {} : { toolNames: input.toolNames }),
+          ...(input.turnFrom === undefined ? {} : { turnFrom: input.turnFrom }),
+          ...(input.turnTo === undefined ? {} : { turnTo: input.turnTo }),
+          limit: input.limit,
+          offset: input.offset,
+          ...(input.snapshotThroughOrdinal === undefined
+            ? {}
+            : { snapshotThroughOrdinal: input.snapshotThroughOrdinal }),
+        });
+        throwIfTurnCancelled(context.signal);
+        const filters: RecallSearchFilters = Object.freeze({
+          ...(input.roles === undefined
+            ? {}
+            : { roles: Object.freeze([...input.roles]) }),
+          ...(input.toolNames === undefined
+            ? {}
+            : { toolNames: Object.freeze([...input.toolNames]) }),
+          ...(input.turnFrom === undefined ? {} : { turnFrom: input.turnFrom }),
+          ...(input.turnTo === undefined ? {} : { turnTo: input.turnTo }),
+        });
+        return {
+          ok: true,
+          mode: "search",
+          historical: true,
+          query: input.query,
+          filters,
+          page,
+        };
+      } catch (error) {
+        if (error instanceof RecallHistoryError) {
+          return recallFailure(parsed.value.mode, error.code, error.message);
+        }
+        if (error instanceof SessionError) {
+          throw new ToolExecutionFatalError("Recall required history storage failed.", {
+            cause: error,
+          });
+        }
+        throw error;
+      }
+    },
+  });
+}
+
+function parseRecallArgs(args: unknown): ParseResult {
+  if (!isRecord(args)) {
+    return argsFailure("search", "Recall arguments must be an object.");
+  }
+  const mode = args.mode === "get" ? "get" : "search";
+  if (args.mode !== "search" && args.mode !== "get") {
+    return argsFailure(mode, 'Recall.mode must be "search" or "get".');
+  }
+  return args.mode === "search" ? parseSearchArgs(args) : parseGetArgs(args);
+}
+
+function parseSearchArgs(args: Record<string, unknown>): ParseResult {
+  const allowed = new Set([
+    "mode",
+    "query",
+    "roles",
+    "tool_names",
+    "turn_from",
+    "turn_to",
+    "limit",
+    "offset",
+    "snapshot_through_ordinal",
+  ]);
+  const unexpected = Object.keys(args).find((key) => !allowed.has(key));
+  if (unexpected !== undefined) {
+    return argsFailure(
+      "search",
+      `Recall search received unexpected field: ${unexpected}.`,
+    );
+  }
+  if (
+    typeof args.query !== "string" ||
+    args.query.trim() === "" ||
+    Buffer.byteLength(args.query, "utf8") > 1024
+  ) {
+    return argsFailure(
+      "search",
+      "Recall search query must be non-empty and at most 1024 UTF-8 bytes.",
+    );
+  }
+
+  const roles = parseRoles(args.roles);
+  if (!roles.ok) {
+    return argsFailure("search", roles.error);
+  }
+  const toolNames = parseToolNames(args.tool_names);
+  if (!toolNames.ok) {
+    return argsFailure("search", toolNames.error);
+  }
+  if (
+    toolNames.value !== undefined &&
+    roles.value !== undefined &&
+    (roles.value.length !== 1 || roles.value[0] !== "tool")
+  ) {
+    return argsFailure(
+      "search",
+      "Recall.tool_names requires roles to be omitted or contain only tool.",
+    );
+  }
+
+  const turnFrom = optionalInteger(args.turn_from, "Recall.turn_from", 1);
+  if (!turnFrom.ok) {
+    return argsFailure("search", turnFrom.error);
+  }
+  const turnTo = optionalInteger(args.turn_to, "Recall.turn_to", 1);
+  if (!turnTo.ok) {
+    return argsFailure("search", turnTo.error);
+  }
+  if (
+    turnFrom.value !== undefined &&
+    turnTo.value !== undefined &&
+    turnFrom.value > turnTo.value
+  ) {
+    return argsFailure("search", "Recall.turn_from must not exceed turn_to.");
+  }
+  const limit = optionalInteger(args.limit, "Recall.limit", 1, 20);
+  if (!limit.ok) {
+    return argsFailure("search", limit.error);
+  }
+  const offset = optionalInteger(args.offset, "Recall.offset", 0);
+  if (!offset.ok) {
+    return argsFailure("search", offset.error);
+  }
+  const snapshot = optionalInteger(
+    args.snapshot_through_ordinal,
+    "Recall.snapshot_through_ordinal",
+    1,
+  );
+  if (!snapshot.ok) {
+    return argsFailure("search", snapshot.error);
+  }
+
+  return {
+    ok: true,
+    value: {
+      mode: "search",
+      query: args.query,
+      ...(roles.value === undefined ? {} : { roles: roles.value }),
+      ...(toolNames.value === undefined ? {} : { toolNames: toolNames.value }),
+      ...(turnFrom.value === undefined ? {} : { turnFrom: turnFrom.value }),
+      ...(turnTo.value === undefined ? {} : { turnTo: turnTo.value }),
+      limit: limit.value ?? 10,
+      offset: offset.value ?? 0,
+      ...(snapshot.value === undefined
+        ? {}
+        : { snapshotThroughOrdinal: snapshot.value }),
+    },
+  };
+}
+
+function parseGetArgs(args: Record<string, unknown>): ParseResult {
+  const allowed = new Set(["mode", "source", "byte_offset", "byte_limit"]);
+  const unexpected = Object.keys(args).find((key) => !allowed.has(key));
+  if (unexpected !== undefined) {
+    return argsFailure("get", `Recall get received unexpected field: ${unexpected}.`);
+  }
+  if (typeof args.source !== "string") {
+    return sourceFailure("Recall.source must be a string.");
+  }
+  let source: MessageSource;
+  try {
+    parseMessageSource(args.source);
+    source = args.source as MessageSource;
+  } catch (error) {
+    if (error instanceof MessageSourceParseError) {
+      return sourceFailure(error.message);
+    }
+    throw error;
+  }
+  const byteOffset = optionalInteger(args.byte_offset, "Recall.byte_offset", 0);
+  if (!byteOffset.ok) {
+    return argsFailure("get", byteOffset.error);
+  }
+  const byteLimit = optionalInteger(args.byte_limit, "Recall.byte_limit", 256, 20_000);
+  if (!byteLimit.ok) {
+    return argsFailure("get", byteLimit.error);
+  }
+  return {
+    ok: true,
+    value: {
+      mode: "get",
+      source,
+      byteOffset: byteOffset.value ?? 0,
+      byteLimit: byteLimit.value ?? 12_000,
+    },
+  };
+}
+
+function parseRoles(
+  value: unknown,
+): { ok: true; value?: RecallRole[] } | { ok: false; error: string } {
+  if (value === undefined) {
+    return { ok: true };
+  }
+  if (
+    !Array.isArray(value) ||
+    value.length === 0 ||
+    value.some(
+      (entry) => entry !== "user" && entry !== "assistant" && entry !== "tool",
+    ) ||
+    new Set(value).size !== value.length
+  ) {
+    return {
+      ok: false,
+      error:
+        "Recall.roles must be a non-empty, unique list of user, assistant, or tool.",
+    };
+  }
+  return { ok: true, value: value as RecallRole[] };
+}
+
+function parseToolNames(
+  value: unknown,
+): { ok: true; value?: string[] } | { ok: false; error: string } {
+  if (value === undefined) {
+    return { ok: true };
+  }
+  if (
+    !Array.isArray(value) ||
+    value.length === 0 ||
+    value.length > 16 ||
+    value.some((entry) => typeof entry !== "string" || entry.trim() === "") ||
+    new Set(value).size !== value.length
+  ) {
+    return {
+      ok: false,
+      error: "Recall.tool_names must contain 1 to 16 unique, non-empty tool names.",
+    };
+  }
+  return { ok: true, value: value as string[] };
+}
+
+function optionalInteger(
+  value: unknown,
+  name: string,
+  minimum: number,
+  maximum = Number.MAX_SAFE_INTEGER,
+): { ok: true; value?: number } | { ok: false; error: string } {
+  if (value === undefined) {
+    return { ok: true };
+  }
+  if (
+    typeof value !== "number" ||
+    !Number.isSafeInteger(value) ||
+    value < minimum ||
+    value > maximum
+  ) {
+    return {
+      ok: false,
+      error: `${name} must be a safe integer from ${minimum} to ${maximum}.`,
+    };
+  }
+  return { ok: true, value };
+}
+
+function recallFailure(
+  mode: "search" | "get",
+  errorCode: RecallToolErrorCode,
+  error: string,
+): RecallRawResult {
+  return { ok: false, mode, errorCode, error };
+}
+
+function argsFailure(mode: "search" | "get", error: string): ParseResult {
+  return { ok: false, mode, errorCode: "RECALL_ARGS_INVALID", error };
+}
+
+function sourceFailure(error: string): ParseResult {
+  return { ok: false, mode: "get", errorCode: "RECALL_SOURCE_INVALID", error };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}