@agi-cli/sdk 0.1.54 → 0.1.56

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

@@ -0,0 +1,140 @@
+import { tool, type Tool } from 'ai';
+import { z } from 'zod';
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+import { join } from 'node:path';
+import { stat } from 'node:fs/promises';
+import DESCRIPTION from './grep.txt' with { type: 'text' };
+import { defaultIgnoreGlobs } from './ignore.ts';
+
+const execAsync = promisify(exec);
+
+function expandTilde(p: 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 buildGrepTool(projectRoot: string): {
+	name: string;
+	tool: Tool;
+} {
+	const grep = tool({
+		description: DESCRIPTION,
+		inputSchema: z.object({
+			pattern: z
+				.string()
+				.describe('Regex pattern to search for in file contents'),
+			path: z
+				.string()
+				.optional()
+				.describe('Directory to search in (default: project root).'),
+			include: z
+				.string()
+				.optional()
+				.describe('File glob to include (e.g., "*.js", "*.{ts,tsx}")'),
+			ignore: z
+				.array(z.string())
+				.optional()
+				.describe('Glob patterns to exclude from search'),
+		}),
+		async execute(params) {
+			const pattern = String(params.pattern || '');
+			if (!pattern) throw new Error('pattern is required');
+
+			const p = expandTilde(String(params.path || '')).trim();
+			const isAbs = p.startsWith('/') || /^[A-Za-z]:[\\/]/.test(p);
+			const searchPath = p ? (isAbs ? p : join(projectRoot, p)) : projectRoot;
+
+			let cmd = `rg -n --color never`;
+			for (const g of defaultIgnoreGlobs(params.ignore)) {
+				cmd += ` --glob "${g.replace(/"/g, '\\"')}"`;
+			}
+			if (params.include) {
+				cmd += ` --glob "${params.include.replace(/"/g, '\\"')}"`;
+			}
+			cmd += ` "${pattern.replace(/"/g, '\\"')}" "${searchPath}"`;
+
+			let output = '';
+			try {
+				const result = await execAsync(cmd, { maxBuffer: 10 * 1024 * 1024 });
+				output = result.stdout;
+			} catch (error: unknown) {
+				const err = error as { code?: number; stderr?: string };
+				if (err.code === 1) {
+					return {
+						title: pattern,
+						metadata: { matches: 0, truncated: false },
+						output: 'No files found',
+					};
+				}
+				const err2 = error as { stderr?: string; message?: string };
+				throw new Error(`ripgrep failed: ${err2.stderr || err2.message}`);
+			}
+
+			const lines = output.trim().split('\n');
+			const matches: Array<{
+				path: string;
+				modTime: number;
+				lineNum: number;
+				lineText: string;
+			}> = [];
+
+			for (const line of lines) {
+				if (!line) continue;
+				const idx1 = line.indexOf(':');
+				const idx2 = idx1 === -1 ? -1 : line.indexOf(':', idx1 + 1);
+				if (idx1 === -1 || idx2 === -1) continue;
+				const filePath = line.slice(0, idx1);
+				const lineNumStr = line.slice(idx1 + 1, idx2);
+				const lineText = line.slice(idx2 + 1);
+				const lineNum = parseInt(lineNumStr, 10);
+				if (!filePath || !Number.isFinite(lineNum)) continue;
+				const stats = await stat(filePath)
+					.then((s) => s.mtime.getTime())
+					.catch(() => 0);
+				matches.push({ path: filePath, modTime: stats, lineNum, lineText });
+			}
+
+			matches.sort((a, b) => b.modTime - a.modTime);
+
+			const limit = 100;
+			const truncated = matches.length > limit;
+			const finalMatches = truncated ? matches.slice(0, limit) : matches;
+
+			if (finalMatches.length === 0) {
+				return {
+					title: pattern,
+					metadata: { matches: 0, truncated: false },
+					output: 'No files found',
+				};
+			}
+
+			const outputLines = [`Found ${finalMatches.length} matches`];
+			let currentFile = '';
+			for (const match of finalMatches) {
+				if (currentFile !== match.path) {
+					if (currentFile !== '') outputLines.push('');
+					currentFile = match.path;
+					outputLines.push(`${match.path}:`);
+				}
+				outputLines.push(`  Line ${match.lineNum}: ${match.lineText}`);
+			}
+			if (truncated) {
+				outputLines.push('');
+				outputLines.push(
+					'(Results are truncated. Consider using a more specific path or pattern.)',
+				);
+			}
+
+			return {
+				title: pattern,
+				metadata: { matches: finalMatches.length, truncated },
+				output: outputLines.join('\n'),
+			};
+		},
+	});
+	return { name: 'grep', tool: grep };
+}

package/src/core/src/tools/builtin/grep.txt

@@ -0,0 +1,9 @@
+- Fast content search tool powered by ripgrep (rg)
+- Supports full regex syntax (e.g., "log.*Error", "function\\s+\\w+")
+- Optional include glob to filter files (e.g., "*.js", "*.{ts,tsx}")
+- Returns files with at least one match and line previews, sorted by modification time
+- Skips common build and cache folders by default; add 'ignore' patterns to refine
+
+Usage tips:
+- For counting matches, use the Bash tool with rg directly (do not use grep)
+- Batch multiple searches when exploring a codebase broadly

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

@@ -0,0 +1,45 @@
+export const IGNORE_PATTERNS: string[] = [
+	'node_modules/',
+	'__pycache__/',
+	'.git/',
+	'dist/',
+	'build/',
+	'target/',
+	'vendor/',
+	'bin/',
+	'obj/',
+	'.idea/',
+	'.vscode/',
+	'.zig-cache/',
+	'zig-out',
+	'.coverage',
+	'coverage/',
+	'vendor/',
+	'tmp/',
+	'temp/',
+	'.cache/',
+	'cache/',
+	'logs/',
+	'.venv/',
+	'venv/',
+	'env/',
+];
+
+export function defaultIgnoreGlobs(extra?: string[]): string[] {
+	const base = IGNORE_PATTERNS.map((p) => `!${p}*`);
+	if (Array.isArray(extra) && extra.length) return base.concat(extra);
+	return base;
+}
+
+export function toIgnoredBasenames(extra?: string[]): Set<string> {
+	const names = new Set<string>();
+	for (const p of IGNORE_PATTERNS) {
+		const n = p.replace(/\/$/, '');
+		if (n) names.add(n);
+	}
+	for (const p of extra ?? []) {
+		const n = String(p).replace(/^!/, '').replace(/\/$/, '');
+		if (n) names.add(n);
+	}
+	return names;
+}

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

@@ -0,0 +1,269 @@
+import { tool, type Tool } from 'ai';
+import { z } from 'zod';
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+import { writeFile, readFile, mkdir } from 'node:fs/promises';
+import DESCRIPTION from './patch.txt' with { type: 'text' };
+
+const execAsync = promisify(exec);
+
+/**
+ * Apply enveloped patch by directly modifying files
+ */
+async function applyEnvelopedPatch(projectRoot: string, patch: string) {
+	const lines = patch.split('\n');
+	let currentFile: string | null = null;
+	let operation: 'add' | 'update' | 'delete' | null = null;
+	let fileContent: string[] = [];
+
+	async function applyCurrentFile() {
+		if (!currentFile || !operation) return { ok: true };
+
+		const fullPath = `${projectRoot}/${currentFile}`;
+
+		if (operation === 'delete') {
+			try {
+				await writeFile(fullPath, '');
+			} catch (e) {
+				return {
+					ok: false,
+					error: `Failed to delete ${currentFile}: ${e instanceof Error ? e.message : String(e)}`,
+				};
+			}
+		} else if (operation === 'add') {
+			// For add, only use lines starting with +
+			const newContent = fileContent
+				.filter((l) => l.startsWith('+'))
+				.map((l) => l.substring(1))
+				.join('\n');
+			try {
+				await writeFile(fullPath, newContent);
+			} catch (e) {
+				return {
+					ok: false,
+					error: `Failed to create ${currentFile}: ${e instanceof Error ? e.message : String(e)}`,
+				};
+			}
+		} else if (operation === 'update') {
+			try {
+				// Read existing file
+				let existingContent = '';
+				try {
+					existingContent = await readFile(fullPath, 'utf-8');
+				} catch {
+					// File doesn't exist yet
+				}
+
+				// Get the old content (lines starting with -)
+				const oldLines = fileContent
+					.filter((l) => l.startsWith('-'))
+					.map((l) => l.substring(1));
+
+				// Get the new content (lines starting with +)
+				const newLines = fileContent
+					.filter((l) => l.startsWith('+'))
+					.map((l) => l.substring(1));
+
+				// Simple replacement: if old content is empty, append
+				// Otherwise try to replace old with new
+				let newContent = existingContent;
+				if (oldLines.length > 0) {
+					const oldText = oldLines.join('\n');
+					const newText = newLines.join('\n');
+					if (existingContent.includes(oldText)) {
+						newContent = existingContent.replace(oldText, newText);
+					} else {
+						// Can't find exact match, this is where enveloped format fails
+						// Provide more context about what couldn't be found
+						const preview = oldText.substring(0, 100);
+						return {
+							ok: false,
+							error: `Cannot find content to replace in ${currentFile}. Looking for: "${preview}${oldText.length > 100 ? '...' : ''}"`,
+						};
+					}
+				} else if (newLines.length > 0) {
+					// Just appending new lines
+					newContent =
+						existingContent +
+						(existingContent.endsWith('\n') ? '' : '\n') +
+						newLines.join('\n');
+				}
+
+				await writeFile(fullPath, newContent);
+			} catch (e) {
+				return {
+					ok: false,
+					error: `Failed to update ${currentFile}: ${e instanceof Error ? e.message : String(e)}`,
+				};
+			}
+		}
+		return { ok: true };
+	}
+
+	for (const line of lines) {
+		if (line === '*** Begin Patch' || line === '*** End Patch') {
+			continue;
+		}
+
+		if (
+			line.startsWith('*** Add File:') ||
+			line.startsWith('*** Update File:') ||
+			line.startsWith('*** Delete File:')
+		) {
+			// Apply previous file if any
+			const result = await applyCurrentFile();
+			if (!result.ok) return result;
+
+			// Start new file
+			if (line.startsWith('*** Add File:')) {
+				currentFile = line.replace('*** Add File:', '').trim();
+				operation = 'add';
+			} else if (line.startsWith('*** Update File:')) {
+				currentFile = line.replace('*** Update File:', '').trim();
+				operation = 'update';
+			} else if (line.startsWith('*** Delete File:')) {
+				currentFile = line.replace('*** Delete File:', '').trim();
+				operation = 'delete';
+			}
+			fileContent = [];
+		} else if (
+			currentFile &&
+			(line.startsWith('+') || line.startsWith('-') || line.startsWith(' '))
+		) {
+			// Collect patch content lines
+			fileContent.push(line);
+		}
+	}
+
+	// Apply the last file
+	const result = await applyCurrentFile();
+	return result;
+}
+
+export function buildApplyPatchTool(projectRoot: string): {
+	name: string;
+	tool: Tool;
+} {
+	const applyPatch = tool({
+		description: DESCRIPTION,
+		inputSchema: z.object({
+			patch: z.string().min(1).describe('Unified diff patch content'),
+			allowRejects: z
+				.boolean()
+				.optional()
+				.default(false)
+				.describe(
+					'Allow hunks to be rejected without failing the whole operation',
+				),
+		}),
+		async execute({
+			patch,
+			allowRejects,
+		}: {
+			patch: string;
+			allowRejects?: boolean;
+		}) {
+			// Check if this is an enveloped patch format
+			const isEnveloped =
+				patch.includes('*** Begin Patch') ||
+				patch.includes('*** Add File:') ||
+				patch.includes('*** Update File:');
+
+			if (isEnveloped) {
+				// Handle enveloped patches directly
+				const result = await applyEnvelopedPatch(projectRoot, patch);
+				const summary = summarizePatch(patch);
+				if (result.ok) {
+					return {
+						ok: true,
+						output: 'Applied enveloped patch',
+						artifact: { kind: 'file_diff', patch, summary },
+					} as const;
+				} else {
+					return {
+						ok: false,
+						error: result.error || 'Failed to apply enveloped patch',
+						artifact: { kind: 'file_diff', patch, summary },
+					} as const;
+				}
+			}
+
+			// For unified diffs, use git apply as before
+			const dir = `${projectRoot}/.agi/tmp`;
+			await mkdir(dir, { recursive: true }).catch(() => {});
+			const file = `${dir}/patch-${Date.now()}.diff`;
+			await writeFile(file, patch);
+			const summary = summarizePatch(patch);
+			// Try -p1 first for canonical git-style patches (a/ b/ prefixes), then fall back to -p0.
+			const baseArgs = ['apply', '--whitespace=nowarn'];
+			const rejectArg = allowRejects ? '--reject' : '';
+			const tries = [
+				`git -C "${projectRoot}" ${baseArgs.join(' ')} ${rejectArg} -p1 "${file}"`,
+				`git -C "${projectRoot}" ${baseArgs.join(' ')} ${rejectArg} -p0 "${file}"`,
+			];
+			let lastError = '';
+			for (const cmd of tries) {
+				try {
+					const { stdout } = await execAsync(cmd, {
+						maxBuffer: 10 * 1024 * 1024,
+					});
+					// Check if any files were actually modified
+					try {
+						const { stdout: statusOut } = await execAsync(
+							`git -C "${projectRoot}" status --porcelain`,
+						);
+						if (statusOut && statusOut.trim().length > 0) {
+							return {
+								ok: true,
+								output: stdout.trim(),
+								artifact: { kind: 'file_diff', patch, summary },
+							} as const;
+						}
+					} catch {}
+				} catch (error: unknown) {
+					const err = error as { stderr?: string; message?: string };
+					lastError = err.stderr || err.message || 'git apply failed';
+				}
+			}
+
+			// Final check if files were modified anyway
+			try {
+				const { stdout: statusOut } = await execAsync(
+					`git -C "${projectRoot}" status --porcelain`,
+				);
+				if (statusOut && statusOut.trim().length > 0) {
+					return {
+						ok: true,
+						output: 'Patch applied with warnings',
+						artifact: { kind: 'file_diff', patch, summary },
+					} as const;
+				}
+			} catch {}
+
+			// If both attempts fail and no files changed, return error with more context
+			const errorDetails = lastError.includes('patch does not apply')
+				? 'The patch cannot be applied because the target content has changed or does not match. The file may have been modified since the patch was created.'
+				: lastError ||
+					'git apply failed (tried -p1 and -p0) — ensure paths match project root';
+			return {
+				ok: false,
+				error: errorDetails,
+				artifact: { kind: 'file_diff', patch, summary },
+			} as const;
+		},
+	});
+	return { name: 'apply_patch', tool: applyPatch };
+}
+
+function summarizePatch(patch: string) {
+	const lines = String(patch || '').split('\n');
+	let files = 0;
+	let additions = 0;
+	let deletions = 0;
+	for (const l of lines) {
+		if (/^\*\*\*\s+(Add|Update|Delete) File:/.test(l)) files += 1;
+		else if (l.startsWith('+') && !l.startsWith('+++')) additions += 1;
+		else if (l.startsWith('-') && !l.startsWith('---')) deletions += 1;
+	}
+	return { files, additions, deletions };
+}

package/src/core/src/tools/builtin/patch.txt

@@ -0,0 +1,7 @@
+- Apply a unified diff patch (`*** Begin Patch`/`*** Update File`/`---`/`+++`/`@@`)
+- Uses `git apply` under the hood; tries `-p1` then `-p0`
+- Returns an artifact summary and any output from `git apply`
+
+Usage tips:
+- Ensure paths in the patch match the project root (prefer `a/` and `b/` prefixes)
+- For small edits, consider the Edit or Write tools instead

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

@@ -0,0 +1,58 @@
+import { tool, type Tool } from 'ai';
+import { z } from 'zod';
+import DESCRIPTION from './plan.txt' with { type: 'text' };
+
+const STATUS_ENUM = z.enum(['pending', 'in_progress', 'completed']);
+
+const ITEM_SCHEMA = z
+	.union([
+		z.string().min(1, 'Plan steps must be non-empty'),
+		z.object({
+			step: z.string().min(1, 'Plan steps must be non-empty'),
+			status: STATUS_ENUM.optional(),
+		}),
+	])
+	.describe('Plan item');
+
+type PlanItemInput = z.infer<typeof ITEM_SCHEMA>;
+
+function normalizeItems(
+	raw: PlanItemInput[],
+): Array<{ step: string; status: z.infer<typeof STATUS_ENUM> }> {
+	const normalized = raw.map((item) => {
+		if (typeof item === 'string') {
+			return { step: item.trim(), status: 'pending' as const };
+		}
+		const step = item.step.trim();
+		const status = item.status ?? 'pending';
+		return { step, status };
+	});
+
+	const filtered = normalized.filter((item) => item.step.length > 0);
+	if (!filtered.length) {
+		throw new Error('At least one plan step is required');
+	}
+
+	const inProgressCount = filtered.filter(
+		(item) => item.status === 'in_progress',
+	).length;
+	if (inProgressCount > 1) {
+		throw new Error('Only one plan step may be marked as in_progress');
+	}
+
+	return filtered;
+}
+
+export const updatePlanTool: Tool = tool({
+	description: DESCRIPTION,
+	inputSchema: z.object({
+		items: z.array(ITEM_SCHEMA).min(1).describe('Ordered list of plan steps'),
+		note: z
+			.string()
+			.optional()
+			.describe('Optional note or context for the plan update'),
+	}),
+	async execute({ items, note }: { items: PlanItemInput[]; note?: string }) {
+		return { items: normalizeItems(items), note };
+	},
+});

package/src/core/src/tools/builtin/plan.txt

@@ -0,0 +1,6 @@
+- Publish or update the current execution plan
+- Displays ordered steps and optional note/context to the user
+
+Usage tips:
+- Keep steps concise (imperative verbs) and reflect progress updates
+- Update the plan whenever scope changes or new steps emerge

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

@@ -0,0 +1,55 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+import DESCRIPTION from './progress.txt' with { type: 'text' };
+
+// Progress update tool: allows the model to emit lightweight status signals
+// without revealing chain-of-thought. The runner/UI should surface these
+// messages immediately.
+const StageEnum = z.enum([
+	'planning',
+	'discovering',
+	'generating',
+	'preparing',
+	'writing',
+	'verifying',
+]);
+
+export const progressUpdateTool = tool({
+	description: DESCRIPTION,
+	inputSchema: z.object({
+		message: z
+			.string()
+			.min(1)
+			.max(200)
+			.describe('Short, user-facing status message (<= 200 chars).'),
+		pct: z
+			.number()
+			.min(0)
+			.max(100)
+			.optional()
+			.describe('Optional overall progress percent 0-100.'),
+		stage: StageEnum.optional().default('planning'),
+	}),
+	async execute({
+		message,
+		pct,
+		stage,
+	}: {
+		message: string;
+		pct?: number;
+		stage?: z.infer<typeof StageEnum>;
+	}) {
+		// Keep the tool lightweight; no side effects beyond the event itself.
+		// Returning the normalized payload allows generic renderers to inspect it if needed.
+		const normalizedPct =
+			typeof pct === 'number'
+				? Math.min(100, Math.max(0, Math.round(pct)))
+				: undefined;
+		return {
+			ok: true,
+			message,
+			pct: normalizedPct,
+			stage: stage ?? 'planning',
+		} as const;
+	},
+});

package/src/core/src/tools/builtin/progress.txt

@@ -0,0 +1,7 @@
+- Emit a short, user-facing progress/status update
+- Supports optional `pct` (0–100) and `stage` indicators
+- Lightweight; intended for immediate UI display
+
+Usage tips:
+- Keep messages short (<= 200 chars) and informative
+- Use multiple updates during long-running tasks