tinker-agent 1.0.65

package/src/tools/web-search.ts

@@ -0,0 +1,300 @@
+import { cancellationError, throwIfTurnCancelled } from "../agent/turn-cancellation";
+import { defineToolExecutor } from "./types";
+import type {
+  ToolExecutionContext,
+  ToolExecutor,
+  WebSearchRawResult,
+  WebSearchResultItem,
+} from "./types";
+
+type WebSearchArgs = {
+  query: string;
+  allowed_domains?: string[];
+  blocked_domains?: string[];
+};
+
+export type WebSearchToolOptions = {
+  apiKey: string;
+  baseUrl?: string;
+  fetchImpl?: typeof fetch;
+  numResults?: number;
+  timeoutMs?: number;
+};
+
+export const WEB_SEARCH_DEFAULT_BASE_URL = "https://api.exa.ai";
+export const WEB_SEARCH_DEFAULT_NUM_RESULTS = 10;
+export const WEB_SEARCH_DEFAULT_TIMEOUT_MS = 30_000;
+
+export function createWebSearchToolExecutor(
+  options: WebSearchToolOptions,
+): ToolExecutor {
+  if (options.apiKey.trim() === "") {
+    throw new Error("WebSearch requires a non-empty Exa API key.");
+  }
+
+  const baseUrl = options.baseUrl ?? WEB_SEARCH_DEFAULT_BASE_URL;
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const numResults = options.numResults ?? WEB_SEARCH_DEFAULT_NUM_RESULTS;
+  const timeoutMs = options.timeoutMs ?? WEB_SEARCH_DEFAULT_TIMEOUT_MS;
+
+  return defineToolExecutor("web_search", {
+    definition: {
+      name: "WebSearch",
+      description: [
+        "Search the web and use the results to inform responses.",
+        "- Provides up-to-date information for current events, recent releases, and documentation",
+        "- Returns result links with publication dates and query-relevant excerpts",
+        "- Use it when the local workspace cannot answer the question or the answer may be stale",
+      ].join("\n"),
+      parameters: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          query: {
+            type: "string",
+            minLength: 2,
+            description: "The search query to use",
+          },
+          allowed_domains: {
+            type: "array",
+            items: { type: "string" },
+            description: "Only include search results from these domains",
+          },
+          blocked_domains: {
+            type: "array",
+            items: { type: "string" },
+            description: "Never include search results from these domains",
+          },
+        },
+        required: ["query"],
+      },
+    },
+    async execute(
+      args,
+      _call,
+      context: ToolExecutionContext,
+    ): Promise<WebSearchRawResult> {
+      throwIfTurnCancelled(context.signal);
+      const parsed = parseWebSearchArgs(args);
+
+      if (!parsed.ok) {
+        return { ok: false, query: "", error: parsed.error };
+      }
+
+      const input = parsed.value;
+      const requestBody: Record<string, unknown> = {
+        query: input.query,
+        type: "auto",
+        numResults,
+        contents: { highlights: true },
+      };
+
+      if (input.allowed_domains !== undefined) {
+        requestBody.includeDomains = input.allowed_domains;
+      }
+
+      if (input.blocked_domains !== undefined) {
+        requestBody.excludeDomains = input.blocked_domains;
+      }
+
+      const startedAt = Date.now();
+      let response: Response;
+      const requestSignal = AbortSignal.any([
+        context.signal,
+        AbortSignal.timeout(timeoutMs),
+      ]);
+
+      try {
+        response = await fetchImpl(`${baseUrl}/search`, {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            "x-api-key": options.apiKey,
+          },
+          body: JSON.stringify(requestBody),
+          signal: requestSignal,
+        });
+      } catch (error) {
+        if (context.signal.aborted) {
+          throw cancellationError(context.signal, error);
+        }
+
+        return {
+          ok: false,
+          query: input.query,
+          error: requestErrorMessage(error, timeoutMs),
+        };
+      }
+
+      let responseText: string;
+      try {
+        responseText = await response.text();
+      } catch (error) {
+        if (context.signal.aborted) {
+          throw cancellationError(context.signal, error);
+        }
+
+        return {
+          ok: false,
+          query: input.query,
+          error: requestErrorMessage(error, timeoutMs),
+        };
+      }
+
+      throwIfTurnCancelled(context.signal);
+
+      if (!response.ok) {
+        return {
+          ok: false,
+          query: input.query,
+          error: `Exa /search returned HTTP ${response.status}: ${extractApiError(responseText)}`,
+        };
+      }
+
+      let payload: unknown;
+      try {
+        payload = JSON.parse(responseText);
+      } catch {
+        return {
+          ok: false,
+          query: input.query,
+          error: "Exa /search returned a non-JSON response body.",
+        };
+      }
+
+      if (!isRecord(payload) || !Array.isArray(payload.results)) {
+        return {
+          ok: false,
+          query: input.query,
+          error: "Exa /search response is missing a results array.",
+        };
+      }
+
+      const results = payload.results
+        .map(toResultItem)
+        .filter((item): item is WebSearchResultItem => item !== undefined);
+
+      return {
+        ok: true,
+        query: input.query,
+        searchType:
+          typeof payload.searchType === "string" ? payload.searchType : undefined,
+        requestId:
+          typeof payload.requestId === "string" ? payload.requestId : undefined,
+        results,
+        resultCount: results.length,
+        allowedDomains: input.allowed_domains,
+        blockedDomains: input.blocked_domains,
+        costDollars: extractTotalCost(payload.costDollars),
+        durationMs: Date.now() - startedAt,
+      };
+    },
+  });
+}
+
+function parseWebSearchArgs(
+  args: unknown,
+): { ok: true; value: WebSearchArgs } | { ok: false; error: string } {
+  if (!isRecord(args)) {
+    return { ok: false, error: "WebSearch arguments must be an object." };
+  }
+
+  if (typeof args.query !== "string" || args.query.trim().length < 2) {
+    return {
+      ok: false,
+      error: "WebSearch.query must be a string with at least 2 characters.",
+    };
+  }
+
+  const allowedDomains = parseDomainList(args.allowed_domains, "allowed_domains");
+  if (!allowedDomains.ok) {
+    return allowedDomains;
+  }
+
+  const blockedDomains = parseDomainList(args.blocked_domains, "blocked_domains");
+  if (!blockedDomains.ok) {
+    return blockedDomains;
+  }
+
+  return {
+    ok: true,
+    value: {
+      query: args.query.trim(),
+      allowed_domains: allowedDomains.value,
+      blocked_domains: blockedDomains.value,
+    },
+  };
+}
+
+function parseDomainList(
+  value: unknown,
+  name: string,
+): { ok: true; value: string[] | undefined } | { ok: false; error: string } {
+  if (value === undefined) {
+    return { ok: true, value: undefined };
+  }
+
+  const entries: unknown[] | undefined = Array.isArray(value) ? value : undefined;
+
+  if (
+    entries === undefined ||
+    !entries.every(
+      (entry): entry is string => typeof entry === "string" && entry.trim() !== "",
+    )
+  ) {
+    return {
+      ok: false,
+      error: `WebSearch.${name} must be an array of non-empty strings.`,
+    };
+  }
+
+  return entries.length === 0
+    ? { ok: true, value: undefined }
+    : { ok: true, value: entries.map((entry) => entry.trim()) };
+}
+
+function toResultItem(value: unknown): WebSearchResultItem | undefined {
+  if (!isRecord(value) || typeof value.url !== "string" || value.url === "") {
+    return undefined;
+  }
+
+  return {
+    title: typeof value.title === "string" ? value.title : "",
+    url: value.url,
+    publishedDate:
+      typeof value.publishedDate === "string" ? value.publishedDate : undefined,
+    author: typeof value.author === "string" ? value.author : undefined,
+    highlights: Array.isArray(value.highlights)
+      ? value.highlights.filter((entry): entry is string => typeof entry === "string")
+      : undefined,
+  };
+}
+
+function extractTotalCost(value: unknown): number | undefined {
+  return isRecord(value) && typeof value.total === "number" ? value.total : undefined;
+}
+
+function extractApiError(responseText: string): string {
+  try {
+    const payload: unknown = JSON.parse(responseText);
+    if (isRecord(payload) && typeof payload.error === "string") {
+      return payload.error;
+    }
+  } catch {
+    // Fall through to the raw body.
+  }
+
+  return responseText === "" ? "(empty response body)" : responseText;
+}
+
+function requestErrorMessage(error: unknown, timeoutMs: number): string {
+  if (error instanceof Error && error.name === "TimeoutError") {
+    return `Exa /search request timed out after ${timeoutMs}ms.`;
+  }
+
+  return `Exa /search request failed: ${error instanceof Error ? error.message : String(error)}`;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/tools/write.ts

@@ -0,0 +1,244 @@
+import path from "node:path";
+import { readFile, stat, writeFile } from "node:fs/promises";
+import { Buffer } from "node:buffer";
+import { throwIfTurnCancelled } from "../agent/turn-cancellation";
+import { computeFilePatch } from "./file-diff";
+import { sha256Bytes, sha256Text } from "./hash";
+import { resolveWorkspacePath } from "./path-safety";
+import { defineToolExecutor } from "./types";
+import type {
+  ReadSnapshotStore,
+  ToolExecutionContext,
+  ToolExecutor,
+  WriteFileRawResult,
+} from "./types";
+
+type WriteArgs = {
+  file_path: string;
+  content: string;
+};
+
+export type WriteToolOptions = {
+  workspaceRoot: string;
+  snapshots: ReadSnapshotStore;
+};
+
+export function createWriteToolExecutor(options: WriteToolOptions): ToolExecutor {
+  return defineToolExecutor("write", {
+    definition: {
+      name: "Write",
+      description:
+        "Write full file content in the local workspace. Existing files must be read first.",
+      parameters: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          file_path: {
+            type: "string",
+            description: "Workspace-relative path or absolute path.",
+          },
+          content: {
+            type: "string",
+            description: "The full content to write to the file.",
+          },
+        },
+        required: ["file_path", "content"],
+      },
+    },
+    async execute(
+      args,
+      _call,
+      context: ToolExecutionContext,
+    ): Promise<WriteFileRawResult> {
+      throwIfTurnCancelled(context.signal);
+      const parsed = parseWriteArgs(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) {
+        return {
+          ok: false,
+          filePath: input.file_path,
+          error: errorMessage(error),
+        };
+      }
+
+      const parentPath = path.dirname(absolutePath);
+      const parentCheck = await directoryExists(parentPath);
+      if (!parentCheck.ok) {
+        return {
+          ok: false,
+          filePath: input.file_path,
+          absolutePath,
+          error: parentCheck.error,
+        };
+      }
+
+      const target = await targetFileState(absolutePath);
+      if (!target.ok) {
+        return {
+          ok: false,
+          filePath: input.file_path,
+          absolutePath,
+          error: target.error,
+        };
+      }
+
+      let oldSha256: string | null = null;
+      let oldContent = "";
+
+      if (target.exists) {
+        const currentSha256 = target.sha256;
+        const lastSnapshot = options.snapshots.get(absolutePath);
+
+        if (lastSnapshot === undefined) {
+          return {
+            ok: false,
+            filePath: input.file_path,
+            absolutePath,
+            requiredReadBeforeWrite: true,
+            currentSha256,
+            error: "Existing file must be read before Write.",
+          };
+        }
+
+        if (lastSnapshot.sha256 !== currentSha256) {
+          return {
+            ok: false,
+            filePath: input.file_path,
+            absolutePath,
+            currentSha256,
+            lastReadSha256: lastSnapshot.sha256,
+            error:
+              "File changed after the last successful Read. Read it again before Write.",
+          };
+        }
+
+        oldSha256 = currentSha256;
+        oldContent = target.content;
+      }
+
+      throwIfTurnCancelled(context.signal);
+      await writeFile(absolutePath, input.content, "utf8");
+      const newSha256 = sha256Text(input.content);
+      const writtenInfo = await stat(absolutePath);
+      options.snapshots.set(absolutePath, {
+        sha256: newSha256,
+        mtimeMs: writtenInfo.mtimeMs,
+        source: "write",
+      });
+
+      const patch = computeFilePatch({
+        filePath: input.file_path,
+        oldContent,
+        newContent: input.content,
+      });
+
+      return {
+        ok: true,
+        filePath: input.file_path,
+        absolutePath,
+        bytesWritten: Buffer.byteLength(input.content, "utf8"),
+        oldSha256,
+        newSha256,
+        created: !target.exists,
+        patch: patch.hunks,
+        patchTruncated: patch.truncated,
+      };
+    },
+  });
+}
+
+function parseWriteArgs(
+  args: unknown,
+): { ok: true; value: WriteArgs } | { ok: false; error: string } {
+  if (!isRecord(args)) {
+    return { ok: false, error: "Write arguments must be an object." };
+  }
+
+  if (typeof args.file_path !== "string") {
+    return { ok: false, error: "Write.file_path must be a string." };
+  }
+
+  if (typeof args.content !== "string") {
+    return { ok: false, error: "Write.content must be a string." };
+  }
+
+  return {
+    ok: true,
+    value: {
+      file_path: args.file_path,
+      content: args.content,
+    },
+  };
+}
+
+async function directoryExists(
+  directoryPath: string,
+): Promise<{ ok: true } | { ok: false; error: string }> {
+  try {
+    const info = await stat(directoryPath);
+    return info.isDirectory()
+      ? { ok: true }
+      : { ok: false, error: "Parent path is not a directory." };
+  } catch {
+    return { ok: false, error: "Parent directory does not exist." };
+  }
+}
+
+async function targetFileState(
+  absolutePath: string,
+): Promise<
+  | { ok: true; exists: false }
+  | { ok: true; exists: true; sha256: string; content: string }
+  | { ok: false; error: string }
+> {
+  try {
+    const info = await stat(absolutePath);
+    if (!info.isFile()) {
+      return { ok: false, error: "Path is not a file." };
+    }
+
+    const bytes = await readFile(absolutePath);
+    return {
+      ok: true,
+      exists: true,
+      sha256: sha256Bytes(bytes),
+      content: bytes.toString("utf8"),
+    };
+  } catch (error) {
+    if (isNotFound(error)) {
+      return { ok: true, exists: false };
+    }
+
+    return { ok: false, error: errorMessage(error) };
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isNotFound(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    error.code === "ENOENT"
+  );
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}