@agi-cli/sdk 0.1.53 → 0.1.55

package/src/core/src/tools/builtin/fs/ls.ts

@@ -0,0 +1,60 @@
+import { tool, type Tool } from 'ai';
+import { z } from 'zod';
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+import { expandTilde, isAbsoluteLike, resolveSafePath } from './util.ts';
+import DESCRIPTION from './ls.txt' with { type: 'text' };
+import { toIgnoredBasenames } from '../ignore.ts';
+
+const execAsync = promisify(exec);
+
+// description imported above
+
+export function buildLsTool(projectRoot: string): { name: string; tool: Tool } {
+	const ls = tool({
+		description: DESCRIPTION,
+		inputSchema: z.object({
+			path: z
+				.string()
+				.default('.')
+				.describe(
+					"Directory path. Relative to project root by default; absolute ('/...') and home ('~/...') paths are allowed.",
+				),
+			ignore: z
+				.array(z.string())
+				.optional()
+				.describe('List of directory names/globs to ignore'),
+		}),
+		async execute({ path, ignore }: { path: string; ignore?: string[] }) {
+			const req = expandTilde(path || '.');
+			const abs = isAbsoluteLike(req)
+				? req
+				: resolveSafePath(projectRoot, req || '.');
+			const ignored = toIgnoredBasenames(ignore);
+
+			try {
+				const { stdout } = await execAsync('ls -1p', {
+					cwd: abs,
+					maxBuffer: 10 * 1024 * 1024,
+				});
+				const entries = stdout
+					.split('\n')
+					.map((line) => line.trim())
+					.filter((line) => line.length > 0 && !line.startsWith('.'))
+					.map((line) => ({
+						name: line.replace(/\/$/, ''),
+						type: line.endsWith('/') ? 'dir' : 'file',
+					}))
+					.filter(
+						(entry) => !(entry.type === 'dir' && ignored.has(entry.name)),
+					);
+				return { path: req, entries };
+			} catch (error: unknown) {
+				const err = error as { stderr?: string; stdout?: string };
+				const message = (err.stderr || err.stdout || 'ls failed').trim();
+				throw new Error(`ls failed for ${req}: ${message}`);
+			}
+		},
+	});
+	return { name: 'ls', tool: ls };
+}

package/src/core/src/tools/builtin/fs/ls.txt

@@ -0,0 +1,8 @@
+- Lists files and directories in a given path (non-recursive)
+- Accepts absolute ('/...'), home ('~/...'), or project-relative paths
+- Hides common build and cache folders by default (node_modules, dist, .git, etc.)
+- Optional ignore patterns allow further filtering of directory names
+
+Usage tips:
+- Prefer the Glob tool for pattern-based discovery and Grep for content search
+- Use the Tree tool for a hierarchical view with limited depth

package/src/core/src/tools/builtin/fs/pwd.ts

@@ -0,0 +1,17 @@
+import { tool, type Tool } from 'ai';
+import { z } from 'zod';
+import DESCRIPTION from './pwd.txt' with { type: 'text' };
+
+// description imported above
+
+export function buildPwdTool(): { name: string; tool: Tool } {
+	const pwd = tool({
+		description: DESCRIPTION,
+		inputSchema: z.object({}).optional(),
+		async execute() {
+			// Actual cwd resolution is handled in the adapter; this is a placeholder schema
+			return { cwd: '.' };
+		},
+	});
+	return { name: 'pwd', tool: pwd };
+}

package/src/core/src/tools/builtin/fs/pwd.txt

@@ -0,0 +1,5 @@
+- Return the current working directory (relative to the project root)
+- The runner maintains a per-session cwd; this tool reports it
+
+Usage tip:
+- Combine with the CD tool to navigate within the workspace

package/src/core/src/tools/builtin/fs/read.ts

@@ -0,0 +1,80 @@
+import { tool, type Tool } from 'ai';
+import { z } from 'zod';
+import { readFile } from 'node:fs/promises';
+import { expandTilde, isAbsoluteLike, resolveSafePath } from './util.ts';
+import DESCRIPTION from './read.txt' with { type: 'text' };
+
+const embeddedTextAssets: Record<string, string> = {};
+
+export function buildReadTool(projectRoot: string): {
+	name: string;
+	tool: Tool;
+} {
+	const read = tool({
+		description: DESCRIPTION,
+		inputSchema: z.object({
+			path: z
+				.string()
+				.describe(
+					"File path. Relative to project root by default; absolute ('/...') and home ('~/...') paths are allowed.",
+				),
+			startLine: z
+				.number()
+				.int()
+				.min(1)
+				.optional()
+				.describe(
+					'Starting line number (1-indexed). If provided, only reads lines from startLine to endLine.',
+				),
+			endLine: z
+				.number()
+				.int()
+				.min(1)
+				.optional()
+				.describe(
+					'Ending line number (1-indexed, inclusive). Required if startLine is provided.',
+				),
+		}),
+		async execute({
+			path,
+			startLine,
+			endLine,
+		}: {
+			path: string;
+			startLine?: number;
+			endLine?: number;
+		}) {
+			const req = expandTilde(path);
+			const abs = isAbsoluteLike(req) ? req : resolveSafePath(projectRoot, req);
+
+			try {
+				let content = await readFile(abs, 'utf-8');
+
+				if (startLine !== undefined && endLine !== undefined) {
+					const lines = content.split('\n');
+					const start = Math.max(1, startLine) - 1;
+					const end = Math.min(lines.length, endLine);
+					const selectedLines = lines.slice(start, end);
+					content = selectedLines.join('\n');
+					return {
+						path: req,
+						content,
+						size: content.length,
+						lineRange: `@${startLine}-${endLine}`,
+						totalLines: lines.length,
+					};
+				}
+
+				return { path: req, content, size: content.length };
+			} catch (_error: unknown) {
+				const embedded = embeddedTextAssets[req];
+				if (embedded) {
+					const content = await readFile(embedded, 'utf-8');
+					return { path: req, content, size: content.length };
+				}
+				throw new Error(`File not found: ${req}`);
+			}
+		},
+	});
+	return { name: 'read', tool: read };
+}

package/src/core/src/tools/builtin/fs/read.txt

@@ -0,0 +1,8 @@
+- Read a text file from the workspace
+- Accepts absolute ('/...'), home ('~/...'), or project-relative paths
+- Returns file text and size in bytes
+- May serve embedded text assets for some paths (internal optimization)
+
+Usage tips:
+- Prefer relative project paths when possible (more portable)
+- For large files or searches, use the Grep or Ripgrep tool

package/src/core/src/tools/builtin/fs/tree.ts

@@ -0,0 +1,71 @@
+import { tool, type Tool } from 'ai';
+import { z } from 'zod';
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+import { expandTilde, isAbsoluteLike, resolveSafePath } from './util.ts';
+import DESCRIPTION from './tree.txt' with { type: 'text' };
+import { toIgnoredBasenames } from '../ignore.ts';
+
+const execAsync = promisify(exec);
+
+// description imported above
+
+export function buildTreeTool(projectRoot: string): {
+	name: string;
+	tool: Tool;
+} {
+	const tree = tool({
+		description: DESCRIPTION,
+		inputSchema: z.object({
+			path: z.string().default('.'),
+			depth: z
+				.number()
+				.int()
+				.min(1)
+				.max(20)
+				.optional()
+				.describe('Optional depth limit (defaults to full depth).'),
+			ignore: z
+				.array(z.string())
+				.optional()
+				.describe('List of directory names/globs to ignore'),
+		}),
+		async execute({
+			path,
+			depth,
+			ignore,
+		}: {
+			path: string;
+			depth?: number;
+			ignore?: string[];
+		}) {
+			const req = expandTilde(path || '.');
+			const start = isAbsoluteLike(req)
+				? req
+				: resolveSafePath(projectRoot, req || '.');
+			const ignored = toIgnoredBasenames(ignore);
+
+			let cmd = 'tree';
+			if (typeof depth === 'number') cmd += ` -L ${depth}`;
+			if (ignored.size) {
+				const pattern = Array.from(ignored).join('|');
+				cmd += ` -I '${pattern.replace(/'/g, "'\\''")}'`;
+			}
+			cmd += ' .';
+
+			try {
+				const { stdout } = await execAsync(cmd, {
+					cwd: start,
+					maxBuffer: 10 * 1024 * 1024,
+				});
+				const output = stdout.trimEnd();
+				return { path: req, depth: depth ?? null, tree: output };
+			} catch (error: unknown) {
+				const err = error as { stderr?: string; stdout?: string };
+				const message = (err.stderr || err.stdout || 'tree failed').trim();
+				throw new Error(`tree failed for ${req}: ${message}`);
+			}
+		},
+	});
+	return { name: 'tree', tool: tree };
+}

package/src/core/src/tools/builtin/fs/tree.txt

@@ -0,0 +1,8 @@
+- Render a shallow directory tree from a starting path
+- Accepts absolute, home, or project-relative paths
+- Skips common build/cache folders (node_modules, dist, .git, etc.) by default
+- Depth is capped to avoid excessive output (1–5)
+
+Usage tips:
+- Use the LS tool for a flat listing of one directory
+- Use the Glob and Grep tools for file pattern and content searches respectively

package/src/core/src/tools/builtin/fs/util.ts

@@ -0,0 +1,95 @@
+import { createTwoFilesPatch } from 'diff';
+import { resolve as resolvePath } from 'node:path';
+
+function normalizeForComparison(value: string) {
+	const withForwardSlashes = value.replace(/\\/g, '/');
+	return process.platform === 'win32'
+		? withForwardSlashes.toLowerCase()
+		: withForwardSlashes;
+}
+
+export function resolveSafePath(projectRoot: string, p: string) {
+	const root = resolvePath(projectRoot);
+	const target = resolvePath(root, p || '.');
+	const rootNorm = (() => {
+		const normalized = normalizeForComparison(root);
+		if (normalized === '/') return '/';
+		return normalized.replace(/[\\/]+$/, '');
+	})();
+	const targetNorm = normalizeForComparison(target);
+	const rootWithSlash = rootNorm === '/' ? '/' : `${rootNorm}/`;
+	const inProject =
+		targetNorm === rootNorm || targetNorm.startsWith(rootWithSlash);
+	if (!inProject) throw new Error(`Path escapes project root: ${p}`);
+	return target;
+}
+
+export function expandTilde(p: string): string {
+	const home = process.env.HOME || process.env.USERPROFILE || '';
+	if (!home) return p;
+	if (p === '~') return home;
+	if (p.startsWith('~/')) return `${home}/${p.slice(2)}`;
+	return p;
+}
+
+export function isAbsoluteLike(p: string): boolean {
+	return p.startsWith('/') || /^[A-Za-z]:[\\/]/.test(p);
+}
+
+export async function buildWriteArtifact(
+	relPath: string,
+	existed: boolean,
+	oldText: string,
+	newText: string,
+) {
+	let patch = '';
+	try {
+		patch = createTwoFilesPatch(
+			`a/${relPath}`,
+			`b/${relPath}`,
+			String(oldText ?? ''),
+			String(newText ?? ''),
+			'',
+			'',
+			{ context: 3 },
+		);
+	} catch {}
+	if (!patch || !patch.trim().length) {
+		const header = existed ? 'Update File' : 'Add File';
+		const oldLines = String(oldText ?? '').split('\n');
+		const newLines = String(newText ?? '').split('\n');
+		const lines: string[] = [];
+		lines.push('*** Begin Patch');
+		lines.push(`*** ${header}: ${relPath}`);
+		lines.push('@@');
+		if (existed) for (const l of oldLines) lines.push(`-${l}`);
+		for (const l of newLines) lines.push(`+${l}`);
+		lines.push('*** End Patch');
+		patch = lines.join('\n');
+	}
+	const { additions, deletions } = summarizePatchCounts(patch);
+	return {
+		kind: 'file_diff',
+		patch,
+		summary: { files: 1, additions, deletions },
+	} as const;
+}
+
+export function summarizePatchCounts(patch: string): {
+	additions: number;
+	deletions: number;
+} {
+	let adds = 0;
+	let dels = 0;
+	for (const line of String(patch || '').split('\n')) {
+		if (
+			line.startsWith('+++') ||
+			line.startsWith('---') ||
+			line.startsWith('diff ')
+		)
+			continue;
+		if (line.startsWith('+')) adds += 1;
+		else if (line.startsWith('-')) dels += 1;
+	}
+	return { additions: adds, deletions: dels };
+}

package/src/core/src/tools/builtin/fs/write.ts

@@ -0,0 +1,61 @@
+import { tool, type Tool } from 'ai';
+import { z } from 'zod';
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import {
+	buildWriteArtifact,
+	resolveSafePath,
+	expandTilde,
+	isAbsoluteLike,
+} from './util.ts';
+import DESCRIPTION from './write.txt' with { type: 'text' };
+
+// description imported above
+
+export function buildWriteTool(projectRoot: string): {
+	name: string;
+	tool: Tool;
+} {
+	const write = tool({
+		description: DESCRIPTION,
+		inputSchema: z.object({
+			path: z
+				.string()
+				.describe(
+					'Relative file path within the project. Writes outside the project are not allowed.',
+				),
+			content: z.string().describe('Text content to write'),
+			createDirs: z.boolean().optional().default(true),
+		}),
+		async execute({
+			path,
+			content,
+			createDirs,
+		}: {
+			path: string;
+			content: string;
+			createDirs?: boolean;
+		}) {
+			const req = expandTilde(path);
+			if (isAbsoluteLike(req)) {
+				throw new Error(
+					`Refusing to write outside project root: ${req}. Use a relative path within the project.`,
+				);
+			}
+			const abs = resolveSafePath(projectRoot, req);
+			if (createDirs) {
+				const dirPath = abs.slice(0, abs.lastIndexOf('/'));
+				await mkdir(dirPath, { recursive: true });
+			}
+			let existed = false;
+			let oldText = '';
+			try {
+				oldText = await readFile(abs, 'utf-8');
+				existed = true;
+			} catch {}
+			await writeFile(abs, content);
+			const artifact = await buildWriteArtifact(req, existed, oldText, content);
+			return { path: req, bytes: content.length, artifact } as const;
+		},
+	});
+	return { name: 'write', tool: write };
+}

package/src/core/src/tools/builtin/fs/write.txt

@@ -0,0 +1,8 @@
+- Write text to a file in the workspace
+- Creates the file if it does not exist (when allowed)
+- Only writes within the project root; absolute paths are rejected
+- Returns a compact patch artifact summarizing the change
+
+Usage tips:
+- Prefer idempotent writes by providing the full intended content
+- For localized edits, consider the Edit tool with structured operations

package/src/core/src/tools/builtin/git.commit.txt

@@ -0,0 +1,6 @@
+- Create a git commit with the provided message
+- Supports `amend` and `signoff` flags
+
+Usage tips:
+- Only commit after explicit user approval
+- Consider including scope and brief rationale in the message

package/src/core/src/tools/builtin/git.diff.txt

@@ -0,0 +1,5 @@
+- Show git diff
+- By default shows staged changes; set `all=true` for full working tree diff
+
+Usage tips:
+- Use with `git_status` to preview changes before committing

package/src/core/src/tools/builtin/git.status.txt

@@ -0,0 +1,5 @@
+- Show git status in porcelain v1 format summary
+- Reports staged and unstaged counts and a capped raw list
+
+Usage tips:
+- Use before committing to understand working tree changes

package/src/core/src/tools/builtin/git.ts

@@ -0,0 +1,128 @@
+import { tool, type Tool } from 'ai';
+import { z } from 'zod';
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+import GIT_STATUS_DESCRIPTION from './git.status.txt' with { type: 'text' };
+import GIT_DIFF_DESCRIPTION from './git.diff.txt' with { type: 'text' };
+import GIT_COMMIT_DESCRIPTION from './git.commit.txt' with { type: 'text' };
+
+const execAsync = promisify(exec);
+
+export function buildGitTools(
+	projectRoot: string,
+): Array<{ name: string; tool: Tool }> {
+	// Helper to find git root directory
+	async function findGitRoot(): Promise<string> {
+		try {
+			const { stdout } = await execAsync(
+				`git -C "${projectRoot}" rev-parse --show-toplevel`,
+			);
+			return stdout.trim() || projectRoot;
+		} catch {
+			return projectRoot;
+		}
+	}
+
+	async function inRepo(): Promise<boolean> {
+		try {
+			const { stdout } = await execAsync(
+				`git -C "${projectRoot}" rev-parse --is-inside-work-tree`,
+			);
+			return stdout.trim() === 'true';
+		} catch {
+			return false;
+		}
+	}
+
+	const git_status = tool({
+		description: GIT_STATUS_DESCRIPTION,
+		inputSchema: z.object({}).optional(),
+		async execute() {
+			if (!(await inRepo())) throw new Error('Not a git repository');
+			const gitRoot = await findGitRoot();
+			const { stdout } = await execAsync(
+				`git -C "${gitRoot}" status --porcelain=v1`,
+			);
+			const lines = stdout.split('\n').filter(Boolean);
+			let staged = 0;
+			let unstaged = 0;
+			for (const line of lines) {
+				const x = line[0];
+				const y = line[1];
+				if (!x || !y) continue;
+				if (x === '!' && y === '!') continue; // ignored files
+				const isUntracked = x === '?' && y === '?';
+				if (x !== ' ' && !isUntracked) staged += 1;
+				if (isUntracked || y !== ' ') unstaged += 1;
+			}
+			return {
+				staged,
+				unstaged,
+				raw: lines.slice(0, 200),
+			};
+		},
+	});
+
+	const git_diff = tool({
+		description: GIT_DIFF_DESCRIPTION,
+		inputSchema: z.object({ all: z.boolean().optional().default(false) }),
+		async execute({ all }: { all?: boolean }) {
+			if (!(await inRepo())) throw new Error('Not a git repository');
+			const gitRoot = await findGitRoot();
+			// When all=true, show full working tree diff relative to HEAD
+			// so both staged and unstaged changes are included. Otherwise,
+			// show only the staged diff (index vs HEAD).
+			const cmd = all
+				? `git -C "${gitRoot}" diff HEAD`
+				: `git -C "${gitRoot}" diff --staged`;
+			const { stdout } = await execAsync(cmd, { maxBuffer: 10 * 1024 * 1024 });
+			const limited = stdout.split('\n').slice(0, 5000).join('\n');
+			return { all: !!all, patch: limited };
+		},
+	});
+
+	const git_commit = tool({
+		description: GIT_COMMIT_DESCRIPTION,
+		inputSchema: z.object({
+			message: z.string().min(5),
+			amend: z.boolean().optional().default(false),
+			signoff: z.boolean().optional().default(false),
+		}),
+		async execute({
+			message,
+			amend,
+			signoff,
+		}: {
+			message: string;
+			amend?: boolean;
+			signoff?: boolean;
+		}) {
+			if (!(await inRepo())) throw new Error('Not a git repository');
+			const gitRoot = await findGitRoot();
+			const args = [
+				'git',
+				'-C',
+				`"${gitRoot}"`,
+				'commit',
+				'-m',
+				`"${message.replace(/"/g, '\\"')}"`,
+			];
+			if (amend) args.push('--amend');
+			if (signoff) args.push('--signoff');
+			try {
+				const { stdout } = await execAsync(args.join(' '));
+				return { result: stdout.trim() };
+			} catch (error: unknown) {
+				const err = error as { stderr?: string; message?: string };
+				const txt = err.stderr || err.message || 'git commit failed';
+				throw new Error(txt);
+			}
+		},
+	});
+
+	return [
+		{ name: 'git_status', tool: git_status },
+		{ name: 'git_diff', tool: git_diff },
+		{ name: 'git_commit', tool: git_commit },
+	];
+}