Tool definitions

import { memoryFileSystem } from "@better-fs-tools/fs";
import { memoryStore, textOf } from "@better-fs-tools/read";
import { fsToolDefinitions } from "@better-fs-tools/write/signature";

const fs = memoryFileSystem({ files: { "/a.ts": "x\n" } });
const defs = fsToolDefinitions({ fs, state: memoryStore() });
const tools = [defs.read, defs.edit, defs.write];

// What your framework declares to the model.
export const declarations = tools.map((tool) => ({
  name: tool.name,
  description: tool.description,
  parameters: tool.inputSchema,
}));

// What your framework calls for each tool call of the model.
export async function runToolCall(id: string, name: string, input: unknown) {
  const tool = tools.find((candidate) => candidate.name === name);
  if (tool === undefined) return { text: `Unknown tool: ${name}`, isError: true };
  const result = await tool.execute(input, { callId: id, host: undefined });
  return { text: textOf(result), isError: result.status === "error" };
}

[edit:not-read] Read /a.ts with the read tool before changing it.

TypeError: Unknown edit input key: file. Expected path, old_string, new_string, replace_all

import { createAiSdkReadTool } from "@better-fs-tools/ai-sdk";
import { nodeFileSystem } from "@better-fs-tools/node";
import { defaultReadSignature } from "@better-fs-tools/read/signature";

const cwd = process.cwd();
const read = createAiSdkReadTool({
  fs: nodeFileSystem({ cwd, allowedRoots: [cwd] }),
  signature: defaultReadSignature({
    description: "Read a file in the repository.",
    describe: { path: "Path relative to the repository root." },
  }),
});

import { defaultReadSignature } from "@better-fs-tools/read/signature";

const signature = defaultReadSignature({
  name: "read_file",
  names: { path: "file_path", offset: "start", limit: "max_lines" },
});

import { createAiSdkFsTools } from "@better-fs-tools/ai-sdk";
import { nodeFileSystem } from "@better-fs-tools/node";
import { defaultEditSignature, defaultWriteSignature } from "@better-fs-tools/write/signature";

const cwd = process.cwd();
const { tools } = createAiSdkFsTools({
  fs: nodeFileSystem({ cwd, allowedRoots: [cwd] }),
  edit: {
    signature: defaultEditSignature({
      names: {
        path: "filePath",
        old_string: "oldString",
        new_string: "newString",
        replace_all: "replaceAll",
      },
    }),
  },
  write: {
    signature: defaultWriteSignature({ name: "write_file", names: { path: "file_path" } }),
  },
});

[edit:no-match] Edit 1: the oldString was not found in a.ts.

TypeError: Unknown read input key: path. Expected file_path, start, max_lines

Read a UTF-8 text file. `offset` is a one-based source line and `limit` is a number of source lines. Output is bounded by line, byte, and line-length limits. When the result reports truncation, follow the continuation it returns instead of guessing the next `offset`. Paths outside the allowed roots, binary content, and special files are refused.

Edit a text file by replacing text. `old_string` must match exactly one place in the file: add surrounding lines to make it unique, or set `replace_all` to change every place. `old_string` should match the file exactly. When it does not, a close match is used, and the result says so. A close match may differ in: trailing whitespace, Unicode normalization, curly quotes, dashes, and special spaces. Copy old text from the file without the line-number prefix the read tool adds. Read the file with the read tool before you edit it. After an edit, the same file can be edited again without another read. To create a file or replace all of its content, use the write tool.

import { createAiSdkFsTools } from "@better-fs-tools/ai-sdk";
import { nodeFileSystem } from "@better-fs-tools/node";
import { exactMatcher } from "@better-fs-tools/write";
import { defaultEditSignature } from "@better-fs-tools/write/signature";

const cwd = process.cwd();
const matchers = [exactMatcher()];
const { tools } = createAiSdkFsTools({
  fs: nodeFileSystem({ cwd, allowedRoots: [cwd] }),
  edit: { matchers, signature: defaultEditSignature({ name: "str_replace", matchers }) },
});

Create a text file, or replace all of its content. Missing parent directories are created. To replace a file that exists, read all of it with the read tool first. To change part of a file, use the edit tool: it sends less text and keeps the rest of the file as it is.

Apply a patch that adds, updates, moves, or deletes text files. The input is one patch text (the `patch` parameter) in the Codex apply_patch format:

*** Begin Patch
*** Update File: src/app.ts
@@ export function main() {
 const a = 1;
-const b = 2;
+const b = 3;
*** Add File: docs/notes.md
+# Notes
*** Delete File: old.txt
*** End Patch

In an Update, each line starts with a space (context), `-` (remove), or `+` (add). `@@ <line>` names a line above the change to find the right place. Put `*** Move to: <path>` after an Update line to rename the file. Every line of an Add starts with `+`. Every hunk is checked before any file changes: when one fails, no file changes. Read each file you update or delete with the read tool first.

Run a shell command with bash -c and return its exit code and output. Each call starts a new shell: a cd, an export, or a variable does not carry to the next call. stdin is closed, so a command that waits for input gets end of file. Do not start interactive programs. The command stops after 2 min unless you set a timeout. The whole process tree is stopped at the timeout. stdout and stderr are merged. Long output keeps the first and the last lines, up to 2000 lines or 30000 bytes. Prefer the read, edit, and write tools for files.

import { createAiSdkBashTool } from "@better-fs-tools/ai-sdk";
import { nodeCommandRunner } from "@better-fs-tools/node";
import { shellEnv } from "@better-fs-tools/shell";
import { defaultBashSignature } from "@better-fs-tools/shell/signature";

const runner = nodeCommandRunner();
const limits = { defaultTimeoutMs: 30_000, maxTimeoutMs: 60_000 };
const bash = createAiSdkBashTool({
  runner,
  env: shellEnv(() => process.env),
  limits,
  signature: defaultBashSignature({
    timeoutUnit: "s",
    names: { timeout: "timeout_seconds" },
    runner: runner.id,
    limits,
  }),
});

Edit a text file with one or more replacements in one call. Each `edits[].oldText` must match exactly one place in the original file. Edits must not overlap or nest: merge nearby changes into one edit. `edits[].oldText` should match the file exactly. When it does not, a close match is used, and the result says so. A close match may differ in: trailing whitespace, Unicode normalization, curly quotes, dashes, and special spaces. Copy old text from the file without the line-number prefix the read tool adds. Read the file with the read tool before you edit it. After an edit, the same file can be edited again without another read. To create a file or replace all of its content, use the write tool.

import { memoryFileSystem } from "@better-fs-tools/fs";
import { textOf } from "@better-fs-tools/read";
import { lineRangeSignature, readToolDefinition } from "@better-fs-tools/read/signature";

const fs = memoryFileSystem({
  files: {
    "/src/greet.ts":
      "export function greet(name: string): string {\n  return `Hello, ${name}!`;\n}\n",
  },
});
const read = readToolDefinition({
  fs,
  signature: lineRangeSignature({
    name: "read_file",
    names: { path: "file_path", start: "start_line", end: "end_line" },
  }),
});

const result = await read.execute(
  { file_path: "/src/greet.ts", start_line: 1, end_line: 2 },
  { host: undefined },
);
console.log(textOf(result));

1|export function greet(name: string): string {
2|  return `Hello, ${name}!`;

[read:continue] Output stopped at the line limit. Continue with {"file_path":"/src/greet.ts","start_line":3,"end_line":4}.

import { CODEX_PATCH_GRAMMAR } from "@better-fs-tools/write/patch";
import { freeformPatchSignature } from "@better-fs-tools/write/signature";

const signature = freeformPatchSignature();
signature.grammar?.lark === CODEX_PATCH_GRAMMAR; // true