@dex-ai/tools-extension 0.1.4

package/README.md

@@ -0,0 +1,152 @@
+# @dex-ai/tools
+
+Core tool Extensions for [`@dex-ai/sdk`](https://github.com/klxdev/dex-ai-sdk). Each tool is its own Extension — compose the ones you want, skip the ones you don't.
+
+| Extension              | Tool        | What it does                                              | Sandboxed | Destructive |
+|------------------------|-------------|-----------------------------------------------------------|-----------|-------------|
+| `readFileExtension`    | `read_file` | Read a file (optional line range).                        | yes (cwd) | no          |
+| `writeFileExtension`   | `write_file`| Create or overwrite a file.                               | yes (cwd) | **yes**     |
+| `editFileExtension`    | `edit_file` | Atomic multi-edit by exact string match.                  | yes (cwd) | **yes**     |
+| `searchExtension`      | `search`    | grep regex over contents, or glob over paths.             | yes (cwd) | no          |
+| `bashExtension`        | `bash`      | Run `sh -c <command>` with timeout + captured output.     | no        | **yes**     |
+
+## Install + use
+
+```ts
+import { DexAgent } from '@dex-ai/runtime';
+import { openai } from '@dex-ai/openai';
+import {
+  readFileExtension, writeFileExtension, editFileExtension,
+  searchExtension, bashExtension,
+  allFsExtensions,
+} from '@dex-ai/tools';
+
+const agent = new DexAgent({
+  provider: openai({ modelId: 'gpt-4.1' }),
+  extensions: [
+    // pick individually...
+    readFileExtension({ cwd: process.cwd() }),
+    searchExtension({ cwd: process.cwd() }),
+
+    // ...or bulk register the full fs set:
+    ...allFsExtensions({ cwd: process.cwd() }),
+
+    bashExtension({ cwd: process.cwd() }),
+  ],
+});
+```
+
+Subpath imports are also available for bundle-size control:
+
+```ts
+import { bashExtension } from '@dex-ai/tools/bash';
+```
+
+## Tool contracts
+
+### `read_file`
+```
+params: { path: string, lineStart?: number, lineEnd?: number }
+output: { type: 'text', value: string }
+errors: path-outside-cwd, file-not-found, not-a-regular-file, too-large (>10MB)
+```
+
+### `write_file`
+```
+params: { path: string, content: string }
+output: { type: 'json', value: { bytesWritten: number, created: boolean } }
+behavior: creates parent dirs if missing; overwrites existing files
+```
+
+### `edit_file`
+```
+params: {
+  path: string,
+  edits: Array<{ oldString: string, newString: string, replaceAll?: boolean }>,
+}
+output: { type: 'json', value: { appliedEdits: number } }
+semantics: all-or-nothing. Each oldString must appear exactly once unless
+           replaceAll is true. Overlapping ranges fail. File must exist.
+           Use write_file to create new files.
+```
+
+### `search`
+```
+params: {
+  mode: 'grep' | 'find',
+  pattern: string,          // grep: regex source;  find: glob (*, **, ?)
+  path?: string,            // defaults to cwd
+  maxResults?: number,      // default 100
+  caseInsensitive?: boolean // grep-only
+}
+output: { type: 'json', value: { matches: [...], truncated: boolean } }
+behavior: skips node_modules, .git, dist by default unless the caller scopes
+          `path` into them.
+```
+
+### `bash`
+```
+params: { command: string, timeoutMs?: number }  // default 120_000ms
+output: { type: 'json', value: { stdout, stderr, exitCode, timedOut } }
+behavior: runs via /bin/sh -c in cwd. Timeout kills the process and returns
+          timedOut: true rather than throwing.
+```
+
+## Approval — it's not here
+
+This package ships **zero approval logic**. The SDK treats approval as cross-cutting via the `onToolCall` hook; apps install their own approver extension. The typical shape:
+
+```ts
+import type { Extension, ToolCall, ToolResult } from '@dex-ai/sdk';
+
+function approvalExtension(opts: {
+  gates: (call: ToolCall) => boolean;                 // returns true if this call needs approval
+  ask: (call: ToolCall) => Promise<boolean>;          // async prompt; returns true to allow
+}): Extension {
+  return {
+    name: 'approval',
+    async onToolCall(call): Promise<ToolResult | void> {
+      if (!opts.gates(call)) return;                  // no gate — run the tool
+      const ok = await opts.ask(call);
+      if (ok) return;                                 // approved — pass through
+      return {                                        // rejected — model sees this as a tool-result
+        toolCallId: call.toolCallId,
+        toolName: call.toolName,
+        output: { type: 'error-text', value: 'User rejected this tool call.' },
+      };
+    },
+  };
+}
+
+// wire it up:
+const agent = new DexAgent({
+  provider,
+  extensions: [
+    bashExtension({ cwd }),
+    writeFileExtension({ cwd }),
+    approvalExtension({
+      gates: (call) => ['bash', 'write_file', 'edit_file'].includes(call.toolName),
+      ask: (call) => ui.confirm(`Run ${call.toolName}: ${JSON.stringify(call.input)}?`),
+    }),
+  ],
+});
+```
+
+Rejected tool calls come back to the model as a normal `tool-result` message containing `error-text`. The model decides what to do next (try a different tool, stop, ask the user).
+
+## Sandbox details
+
+The four fs tools resolve every path against `cwd` and reject anything outside. Specifically:
+- `../` traversal is rejected (paths are normalized).
+- Absolute paths outside `cwd` are rejected.
+- Symlinks are followed via `fs.realpath` — a symlink inside `cwd` that points outside is rejected.
+
+`bash` is **not** sandboxed at the filesystem level. It runs with `cwd` as its working directory but any approved shell command can read/write anywhere the process has permission to. Approval is the gate — use `onToolCall`.
+
+## Testing
+
+```bash
+bun test
+```
+
+50 tests across 6 files as of v0.1 — every tool exercised end-to-end through a `DexAgent` + scripted fake Provider.

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@dex-ai/tools-extension",
+  "version": "0.1.4",
+  "description": "Core tool Extensions for @dex-ai/sdk — file read/write/edit, search, bash. Each tool is its own Extension.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./read-file": {
+      "types": "./src/read-file.ts",
+      "default": "./src/read-file.ts"
+    },
+    "./write-file": {
+      "types": "./src/write-file.ts",
+      "default": "./src/write-file.ts"
+    },
+    "./edit-file": {
+      "types": "./src/edit-file.ts",
+      "default": "./src/edit-file.ts"
+    },
+    "./search": {
+      "types": "./src/search.ts",
+      "default": "./src/search.ts"
+    },
+    "./bash": {
+      "types": "./src/bash.ts",
+      "default": "./src/bash.ts"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@dex-ai/sdk": "^0.1.2"
+  },
+  "peerDependencies": {
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "zod": "^3.23.8"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/_cwd.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, test, beforeEach, afterEach } from 'bun:test';
+import { mkdir, writeFile, symlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tempWorkspace } from './_test-helpers';
+import { resolveInCwd, PathOutsideCwdError } from './_cwd';
+
+describe('resolveInCwd', () => {
+  let cwd: string;
+  let cleanup: () => Promise<void>;
+
+  beforeEach(async () => {
+    ({ cwd, cleanup } = await tempWorkspace());
+  });
+
+  afterEach(() => cleanup());
+
+  test('relative path resolves under cwd', async () => {
+    await writeFile(join(cwd, 'a.txt'), 'hi');
+    const r = await resolveInCwd(cwd, 'a.txt');
+    expect(r.startsWith(cwd)).toBe(true);
+    expect(r.endsWith('a.txt')).toBe(true);
+  });
+
+  test('absolute path under cwd is accepted', async () => {
+    await writeFile(join(cwd, 'a.txt'), 'hi');
+    const r = await resolveInCwd(cwd, join(cwd, 'a.txt'));
+    expect(r.endsWith('a.txt')).toBe(true);
+  });
+
+  test('../ escape is rejected', async () => {
+    expect(resolveInCwd(cwd, '../escape.txt')).rejects.toBeInstanceOf(PathOutsideCwdError);
+  });
+
+  test('absolute path outside cwd is rejected', async () => {
+    expect(resolveInCwd(cwd, '/etc/passwd')).rejects.toBeInstanceOf(PathOutsideCwdError);
+  });
+
+  test('non-existent file inside cwd is fine (for write)', async () => {
+    const r = await resolveInCwd(cwd, 'new/file.txt');
+    expect(r.startsWith(cwd)).toBe(true);
+    expect(r.endsWith('new/file.txt')).toBe(true);
+  });
+
+  test('symlink inside cwd pointing OUTSIDE is rejected', async () => {
+    const outside = await tempWorkspace();
+    try {
+      await writeFile(join(outside.cwd, 'secret'), 'nope');
+      await symlink(join(outside.cwd, 'secret'), join(cwd, 'bad-link'));
+      expect(resolveInCwd(cwd, 'bad-link')).rejects.toBeInstanceOf(PathOutsideCwdError);
+    } finally {
+      await outside.cleanup();
+    }
+  });
+
+  test('symlink inside cwd pointing INSIDE is fine', async () => {
+    await mkdir(join(cwd, 'sub'));
+    await writeFile(join(cwd, 'sub', 'target'), 'ok');
+    await symlink(join(cwd, 'sub', 'target'), join(cwd, 'good-link'));
+    const r = await resolveInCwd(cwd, 'good-link');
+    expect(r.startsWith(cwd)).toBe(true);
+  });
+
+  test('mustExist=true rejects missing paths', async () => {
+    expect(resolveInCwd(cwd, 'missing.txt', { mustExist: true })).rejects.toThrow();
+  });
+});

package/src/_cwd.ts

@@ -0,0 +1,137 @@
+/**
+ * Shared cwd sandbox helper for fs tools.
+ *
+ * resolveInCwd takes an absolute or relative input path, resolves it
+ * (following `..` segments and symlinks via fs.realpath), and rejects
+ * anything that lands outside the sandbox root. Every fs-facing tool
+ * calls this before touching the filesystem.
+ */
+import { realpath } from "node:fs/promises";
+import { resolve, sep } from "node:path";
+
+/**
+ * A CwdProvider is either a static path string or a function that returns
+ * the current working directory. Tools use this to support dynamic cwd
+ * (e.g. changed via an env extension's `cd` tool).
+ */
+export type CwdProvider = string | (() => string);
+
+/**
+ * A RootsProvider returns the list of allowed sandbox root directories.
+ * Can be static or dynamic (grows when user adds directories).
+ */
+export type RootsProvider =
+	| ReadonlyArray<string>
+	| (() => ReadonlyArray<string>);
+
+/** Resolve a CwdProvider to a concrete path. */
+export function resolveCwd(provider: CwdProvider): string {
+	return typeof provider === "function" ? provider() : provider;
+}
+
+/** Resolve a RootsProvider to a concrete array. */
+export function resolveRoots(
+	provider: RootsProvider | undefined,
+): ReadonlyArray<string> | undefined {
+	if (provider === undefined) return undefined;
+	return typeof provider === "function" ? provider() : provider;
+}
+
+export class PathOutsideCwdError extends Error {
+	override readonly name = "PathOutsideCwdError";
+	constructor(
+		public readonly input: string,
+		public readonly cwd: string,
+		public readonly resolved: string,
+	) {
+		super(
+			`Path outside working directory: ${input} (resolved to ${resolved}; cwd=${cwd})`,
+		);
+	}
+}
+
+export interface ResolveOptions {
+	/**
+	 * If true, the target must already exist (realpath will throw ENOENT otherwise).
+	 * If false, we resolve as far as possible and check the deepest existing ancestor
+	 * — this supports write creating new paths inside cwd.
+	 */
+	mustExist?: boolean;
+	/**
+	 * Additional allowed root directories. When provided, a path is valid if it
+	 * resides within cwd OR within any of these roots. Supports multi-root sandboxes.
+	 */
+	roots?: ReadonlyArray<string> | undefined;
+}
+
+async function resolveToRealpath(
+	cwdReal: string,
+	input: string,
+): Promise<string> {
+	const joined = resolve(cwdReal, input);
+
+	try {
+		return await realpath(joined);
+	} catch (err) {
+		if ((err as { code?: string }).code !== "ENOENT") throw err;
+	}
+
+	// Path doesn't exist yet. Walk up to find the deepest existing ancestor,
+	// realpath that (to resolve symlinks), then reattach the missing suffix.
+	const parts = joined.split(sep);
+	for (let i = parts.length - 1; i > 0; i--) {
+		const candidate = parts.slice(0, i).join(sep) || sep;
+		try {
+			const real = await realpath(candidate);
+			const tail = parts.slice(i).join(sep);
+			return tail === "" ? real : resolve(real, tail);
+		} catch (err) {
+			if ((err as { code?: string }).code !== "ENOENT") throw err;
+		}
+	}
+	// Nothing exists up the chain; return the joined path as-is.
+	return joined;
+}
+
+/**
+ * Resolve `input` against `cwd` and assert the result stays inside the sandbox.
+ * Returns the realpath (absolute, symlinks resolved) on success.
+ * Throws PathOutsideCwdError on escape.
+ *
+ * When `opts.roots` is provided, the path is valid if it resides within
+ * cwd OR any of the given roots.
+ */
+export async function resolveInCwd(
+	cwd: string,
+	input: string,
+	opts: ResolveOptions = {},
+): Promise<string> {
+	// Realpath cwd once so symlinks in cwd itself don't confuse the comparison.
+	const cwdReal = await realpath(cwd);
+	const target =
+		opts.mustExist === true
+			? await realpath(resolve(cwdReal, input))
+			: await resolveToRealpath(cwdReal, input);
+
+	// Check if target is inside cwd
+	if (target === cwdReal || target.startsWith(cwdReal + sep)) {
+		return target;
+	}
+
+	// Check additional roots if provided
+	if (opts.roots && opts.roots.length > 0) {
+		for (const root of opts.roots) {
+			let rootReal: string;
+			try {
+				rootReal = await realpath(root);
+			} catch {
+				continue;
+			}
+			if (target === rootReal || target.startsWith(rootReal + sep)) {
+				return target;
+			}
+		}
+	}
+
+	throw new PathOutsideCwdError(input, cwdReal, target);
+}

package/src/_diff.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'bun:test';
+import { unifiedDiff } from './_diff';
+
+describe('unifiedDiff', () => {
+  it('returns empty string for identical content', () => {
+    const content = 'line1\nline2\nline3\n';
+    expect(unifiedDiff(content, content, 'test.ts')).toBe('');
+  });
+
+  it('shows single line change with context', () => {
+    const original = 'line1\nline2\nline3\nline4\nline5\n';
+    const modified = 'line1\nline2\nchanged\nline4\nline5\n';
+    const diff = unifiedDiff(original, modified, 'test.ts');
+
+    expect(diff).toContain('--- a/test.ts');
+    expect(diff).toContain('+++ b/test.ts');
+    expect(diff).toContain('-line3');
+    expect(diff).toContain('+changed');
+    // Context lines
+    expect(diff).toContain(' line2');
+    expect(diff).toContain(' line4');
+  });
+
+  it('shows addition', () => {
+    const original = 'line1\nline2\n';
+    const modified = 'line1\nnew\nline2\n';
+    const diff = unifiedDiff(original, modified, 'test.ts');
+
+    expect(diff).toContain('+new');
+  });
+
+  it('shows deletion', () => {
+    const original = 'line1\nline2\nline3\n';
+    const modified = 'line1\nline3\n';
+    const diff = unifiedDiff(original, modified, 'test.ts');
+
+    expect(diff).toContain('-line2');
+  });
+
+  it('shows multiple hunks for distant changes', () => {
+    const lines = Array.from({ length: 20 }, (_, i) => `line${i + 1}`);
+    const original = lines.join('\n') + '\n';
+    const modLines = [...lines];
+    modLines[2] = 'changed3';
+    modLines[17] = 'changed18';
+    const modified = modLines.join('\n') + '\n';
+    const diff = unifiedDiff(original, modified, 'test.ts');
+
+    expect(diff).toContain('-line3');
+    expect(diff).toContain('+changed3');
+    expect(diff).toContain('-line18');
+    expect(diff).toContain('+changed18');
+    // Should have two @@ hunk headers
+    const hunkHeaders = diff.split('\n').filter(l => l.startsWith('@@'));
+    expect(hunkHeaders.length).toBe(2);
+  });
+});

package/src/_diff.ts

@@ -0,0 +1,221 @@
+/**
+ * Minimal unified-diff generator for showing file edits.
+ * Produces git-style unified diff output with context lines.
+ */
+
+const CONTEXT_LINES = 3;
+
+interface Hunk {
+	oldStart: number;
+	oldCount: number;
+	newStart: number;
+	newCount: number;
+	lines: string[];
+}
+
+/**
+ * Simple LCS-based diff producing edit operations.
+ * Returns an array of { type, line } entries.
+ */
+function diffLines(
+	a: string[],
+	b: string[],
+): Array<{ type: "keep" | "del" | "add"; line: string }> {
+	const n = a.length;
+	const m = b.length;
+
+	// Optimize: for very large files, use a simpler approach
+	if (n * m > 1_000_000) {
+		return simpleDiff(a, b);
+	}
+
+	// LCS table
+	const dp: number[][] = Array.from({ length: n + 1 }, () =>
+		Array(m + 1).fill(0),
+	);
+	for (let i = 1; i <= n; i++) {
+		for (let j = 1; j <= m; j++) {
+			if (a[i - 1] === b[j - 1]) {
+				dp[i]![j] = dp[i - 1]![j - 1]! + 1;
+			} else {
+				dp[i]![j] = Math.max(dp[i - 1]![j]!, dp[i]![j - 1]!);
+			}
+		}
+	}
+
+	// Backtrack
+	const ops: Array<{ type: "keep" | "del" | "add"; line: string }> = [];
+	let i = n,
+		j = m;
+	while (i > 0 || j > 0) {
+		if (i > 0 && j > 0 && a[i - 1] === b[j - 1]) {
+			ops.push({ type: "keep", line: a[i - 1]! });
+			i--;
+			j--;
+		} else if (j > 0 && (i === 0 || dp[i]![j - 1]! >= dp[i - 1]![j]!)) {
+			ops.push({ type: "add", line: b[j - 1]! });
+			j--;
+		} else {
+			ops.push({ type: "del", line: a[i - 1]! });
+			i--;
+		}
+	}
+	ops.reverse();
+	return ops;
+}
+
+/**
+ * Fallback for large files: find changed regions by comparing line-by-line.
+ */
+function simpleDiff(
+	a: string[],
+	b: string[],
+): Array<{ type: "keep" | "del" | "add"; line: string }> {
+	const ops: Array<{ type: "keep" | "del" | "add"; line: string }> = [];
+
+	// Find common prefix
+	let prefix = 0;
+	while (prefix < a.length && prefix < b.length && a[prefix] === b[prefix]) {
+		ops.push({ type: "keep", line: a[prefix]! });
+		prefix++;
+	}
+
+	// Find common suffix
+	let suffixA = a.length - 1;
+	let suffixB = b.length - 1;
+	const suffixOps: Array<{ type: "keep" | "del" | "add"; line: string }> = [];
+	while (suffixA >= prefix && suffixB >= prefix && a[suffixA] === b[suffixB]) {
+		suffixOps.push({ type: "keep", line: a[suffixA]! });
+		suffixA--;
+		suffixB--;
+	}
+	suffixOps.reverse();
+
+	// Middle section: all deletions then all additions
+	for (let i = prefix; i <= suffixA; i++) {
+		ops.push({ type: "del", line: a[i]! });
+	}
+	for (let i = prefix; i <= suffixB; i++) {
+		ops.push({ type: "add", line: b[i]! });
+	}
+
+	ops.push(...suffixOps);
+	return ops;
+}
+
+/**
+ * Group diff ops into hunks with context lines.
+ */
+function buildHunks(
+	ops: Array<{ type: "keep" | "del" | "add"; line: string }>,
+): Hunk[] {
+	const hunks: Hunk[] = [];
+	let currentHunk: Hunk | null = null;
+	let oldLine = 0;
+	let newLine = 0;
+	let trailingContext = 0;
+
+	for (let idx = 0; idx < ops.length; idx++) {
+		const op = ops[idx]!;
+
+		if (op.type === "keep") {
+			oldLine++;
+			newLine++;
+
+			if (currentHunk) {
+				trailingContext++;
+				currentHunk.lines.push(` ${op.line}`);
+				currentHunk.oldCount++;
+				currentHunk.newCount++;
+
+				// If we've accumulated enough trailing context and there's no more changes nearby
+				if (trailingContext >= CONTEXT_LINES) {
+					// Check if next change is within context distance
+					let nextChange = -1;
+					for (
+						let k = idx + 1;
+						k < ops.length && k <= idx + CONTEXT_LINES;
+						k++
+					) {
+						if (ops[k]!.type !== "keep") {
+							nextChange = k;
+							break;
+						}
+					}
+					if (nextChange === -1) {
+						// Close hunk
+						hunks.push(currentHunk);
+						currentHunk = null;
+						trailingContext = 0;
+					}
+				}
+			}
+		} else {
+			// Change line — start or extend hunk
+			if (!currentHunk) {
+				// Start new hunk with leading context
+				const contextStart = Math.max(0, idx - CONTEXT_LINES);
+				currentHunk = {
+					oldStart: oldLine - (idx - contextStart) + 1,
+					oldCount: 0,
+					newStart: newLine - (idx - contextStart) + 1,
+					newCount: 0,
+					lines: [],
+				};
+				// Add leading context
+				for (let k = contextStart; k < idx; k++) {
+					currentHunk.lines.push(` ${ops[k]!.line}`);
+					currentHunk.oldCount++;
+					currentHunk.newCount++;
+				}
+			}
+			trailingContext = 0;
+
+			if (op.type === "del") {
+				currentHunk.lines.push(`-${op.line}`);
+				currentHunk.oldCount++;
+				oldLine++;
+			} else {
+				currentHunk.lines.push(`+${op.line}`);
+				currentHunk.newCount++;
+				newLine++;
+			}
+		}
+	}
+
+	if (currentHunk) {
+		hunks.push(currentHunk);
+	}
+
+	return hunks;
+}
+
+/**
+ * Produce a unified diff string from two file contents.
+ */
+export function unifiedDiff(
+	original: string,
+	modified: string,
+	path: string,
+): string {
+	const aLines = original.split("\n");
+	const bLines = modified.split("\n");
+
+	const ops = diffLines(aLines, bLines);
+	const hunks = buildHunks(ops);
+
+	if (hunks.length === 0) return "";
+
+	const out: string[] = [];
+	out.push(`--- a/${path}`);
+	out.push(`+++ b/${path}`);
+
+	for (const hunk of hunks) {
+		out.push(
+			`@@ -${hunk.oldStart},${hunk.oldCount} +${hunk.newStart},${hunk.newCount} @@`,
+		);
+		out.push(...hunk.lines);
+	}
+
+	return out.join("\n");
+}