@agi-cli/sdk 0.1.110 → 0.1.111

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@agi-cli/sdk",
-	"version": "0.1.110",
+	"version": "0.1.111",
 	"description": "AI agent SDK for building intelligent assistants - tree-shakable and comprehensive",
 	"author": "ntishxyz",
 	"license": "MIT",

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

@@ -3,6 +3,7 @@ import { z } from 'zod';
 import { readFile, writeFile, access } from 'node:fs/promises';
 import { constants } from 'node:fs';
 import DESCRIPTION from './edit.txt' with { type: 'text' };
+import { createToolError, type ToolResponse } from '../error.ts';
 
 const replaceOp = z.object({
 	type: z.literal('replace'),
@@ -54,7 +55,9 @@ export const editTool: Tool = tool({
 		path: string;
 		ops: z.infer<typeof opSchema>[];
 		create?: boolean;
-	}) {
+	}): Promise<
+		ToolResponse<{ path: string; opsApplied: number; bytes: number }>
+	> {
 		let exists = false;
 		try {
 			await access(path, constants.F_OK);
@@ -62,7 +65,13 @@ export const editTool: Tool = tool({
 		} catch {}
 
 		if (!exists) {
-			if (!create) throw new Error(`File not found: ${path}`);
+			if (!create) {
+				return createToolError(`File not found: ${path}`, 'not_found', {
+					parameter: 'path',
+					value: path,
+					suggestion: 'Set create: true to create a new file',
+				});
+			}
 			await writeFile(path, '');
 		}
 		let text = await readFile(path, 'utf-8');
@@ -120,8 +129,16 @@ export const editTool: Tool = tool({
 					applied += 1;
 					continue;
 				}
-				if (!op.pattern)
-					throw new Error('insert requires pattern for before/after');
+				if (!op.pattern) {
+					return createToolError(
+						'insert requires pattern for before/after',
+						'validation',
+						{
+							parameter: 'pattern',
+							suggestion: 'Provide a pattern to anchor the insertion',
+						},
+					);
+				}
 				const idx = text.indexOf(op.pattern);
 				if (idx === -1) continue;
 				if (op.position === 'before')
@@ -147,6 +164,6 @@ export const editTool: Tool = tool({
 		}
 
 		await writeFile(path, text);
-		return { path, opsApplied: applied, bytes: text.length };
+		return { ok: true, path, opsApplied: applied, bytes: text.length };
 	},
 });

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

@@ -1,11 +1,12 @@
 import { z } from 'zod';
 import { tool } from 'ai';
 import DESCRIPTION from './finish.txt' with { type: 'text' };
+import type { ToolResponse } from '../error.ts';
 
 export const finishTool = tool({
 	description: DESCRIPTION,
 	inputSchema: z.object({}),
-	async execute() {
-		return { done: true } as const;
+	async execute(): Promise<ToolResponse<{ done: true }>> {
+		return { ok: true, done: true };
 	},
 });

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

@@ -5,6 +5,7 @@ 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';
+import { createToolError, type ToolResponse } from '../../error.ts';
 
 const execAsync = promisify(exec);
 
@@ -25,7 +26,18 @@ export function buildLsTool(projectRoot: string): { name: string; tool: Tool } {
 				.optional()
 				.describe('List of directory names/globs to ignore'),
 		}),
-		async execute({ path, ignore }: { path: string; ignore?: string[] }) {
+		async execute({
+			path,
+			ignore,
+		}: {
+			path: string;
+			ignore?: string[];
+		}): Promise<
+			ToolResponse<{
+				path: string;
+				entries: Array<{ name: string; type: string }>;
+			}>
+		> {
 			const req = expandTilde(path || '.');
 			const abs = isAbsoluteLike(req)
 				? req
@@ -48,11 +60,19 @@ export function buildLsTool(projectRoot: string): { name: string; tool: Tool } {
 					.filter(
 						(entry) => !(entry.type === 'dir' && ignored.has(entry.name)),
 					);
-				return { path: req, entries };
+				return { ok: true, 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 createToolError(
+					`ls failed for ${req}: ${message}`,
+					'execution',
+					{
+						parameter: 'path',
+						value: req,
+						suggestion: 'Check if the directory exists and is accessible',
+					},
+				);
 			}
 		},
 	});

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

@@ -5,6 +5,7 @@ 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';
+import { createToolError, type ToolResponse } from '../../error.ts';
 
 const execAsync = promisify(exec);
 
@@ -38,7 +39,9 @@ export function buildTreeTool(projectRoot: string): {
 			path: string;
 			depth?: number;
 			ignore?: string[];
-		}) {
+		}): Promise<
+			ToolResponse<{ path: string; depth: number | null; tree: string }>
+		> {
 			const req = expandTilde(path || '.');
 			const start = isAbsoluteLike(req)
 				? req
@@ -59,11 +62,20 @@ export function buildTreeTool(projectRoot: string): {
 					maxBuffer: 10 * 1024 * 1024,
 				});
 				const output = stdout.trimEnd();
-				return { path: req, depth: depth ?? null, tree: output };
+				return { ok: true, 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 createToolError(
+					`tree failed for ${req}: ${message}`,
+					'execution',
+					{
+						parameter: 'path',
+						value: req,
+						suggestion:
+							'Check if the directory exists and tree command is installed',
+					},
+				);
 			}
 		},
 	});

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

@@ -5,6 +5,7 @@ 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' };
+import { createToolError, type ToolResponse } from '../error.ts';
 
 const execAsync = promisify(exec);
 
@@ -37,14 +38,13 @@ export function buildGitTools(
 	const git_status = tool({
 		description: GIT_STATUS_DESCRIPTION,
 		inputSchema: z.object({}).optional(),
-		async execute() {
+		async execute(): Promise<
+			ToolResponse<{ staged: number; unstaged: number; raw: string[] }>
+		> {
 			if (!(await inRepo())) {
-				return {
-					error: 'Not a git repository',
-					staged: 0,
-					unstaged: 0,
-					raw: [],
-				};
+				return createToolError('Not a git repository', 'not_found', {
+					suggestion: 'Initialize a git repository with git init',
+				});
 			}
 			const gitRoot = await findGitRoot();
 			const { stdout } = await execAsync(
@@ -63,6 +63,7 @@ export function buildGitTools(
 				if (isUntracked || y !== ' ') unstaged += 1;
 			}
 			return {
+				ok: true,
 				staged,
 				unstaged,
 				raw: lines.slice(0, 200),
@@ -73,9 +74,15 @@ export function buildGitTools(
 	const git_diff = tool({
 		description: GIT_DIFF_DESCRIPTION,
 		inputSchema: z.object({ all: z.boolean().optional().default(false) }),
-		async execute({ all }: { all?: boolean }) {
+		async execute({
+			all,
+		}: {
+			all?: boolean;
+		}): Promise<ToolResponse<{ all: boolean; patch: string }>> {
 			if (!(await inRepo())) {
-				return { error: 'Not a git repository', all: !!all, patch: '' };
+				return createToolError('Not a git repository', 'not_found', {
+					suggestion: 'Initialize a git repository with git init',
+				});
 			}
 			const gitRoot = await findGitRoot();
 			// When all=true, show full working tree diff relative to HEAD
@@ -86,7 +93,7 @@ export function buildGitTools(
 				: `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 };
+			return { ok: true, all: !!all, patch: limited };
 		},
 	});
 
@@ -105,9 +112,11 @@ export function buildGitTools(
 			message: string;
 			amend?: boolean;
 			signoff?: boolean;
-		}) {
+		}): Promise<ToolResponse<{ result: string }>> {
 			if (!(await inRepo())) {
-				return { success: false, error: 'Not a git repository' };
+				return createToolError('Not a git repository', 'not_found', {
+					suggestion: 'Initialize a git repository with git init',
+				});
 			}
 			const gitRoot = await findGitRoot();
 			const args = [
@@ -122,11 +131,14 @@ export function buildGitTools(
 			if (signoff) args.push('--signoff');
 			try {
 				const { stdout } = await execAsync(args.join(' '));
-				return { result: stdout.trim() };
+				return { ok: true, 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 createToolError(txt, 'execution', {
+					suggestion:
+						'Check if there are staged changes and the commit message is valid',
+				});
 			}
 		},
 	});

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

@@ -5,6 +5,7 @@ import { join } from 'node:path';
 import { stat } from 'node:fs/promises';
 import DESCRIPTION from './glob.txt' with { type: 'text' };
 import { defaultIgnoreGlobs } from './ignore.ts';
+import { createToolError, type ToolResponse } from '../error.ts';
 
 function expandTilde(p: string) {
 	const home = process.env.HOME || process.env.USERPROFILE || '';
@@ -54,7 +55,14 @@ export function buildGlobTool(projectRoot: string): {
 			path?: string;
 			ignore?: string[];
 			limit?: number;
-		}) {
+		}): Promise<
+			ToolResponse<{
+				count: number;
+				total: number;
+				files: string[];
+				truncated: boolean;
+			}>
+		> {
 			const p = expandTilde(String(path || '.')).trim();
 			const isAbs = p.startsWith('/') || /^[A-Za-z]:[\\/]/.test(p);
 			const searchPath = p ? (isAbs ? p : join(projectRoot, p)) : projectRoot;
@@ -96,6 +104,7 @@ export function buildGlobTool(projectRoot: string): {
 				const limitedFiles = filesWithStats.slice(0, limit).map((f) => f.file);
 
 				return {
+					ok: true,
 					count: limitedFiles.length,
 					total: files.length,
 					files: limitedFiles,
@@ -103,12 +112,15 @@ export function buildGlobTool(projectRoot: string): {
 				};
 			} catch (error: unknown) {
 				const err = error as { message?: string };
-				return {
-					count: 0,
-					total: 0,
-					files: [],
-					error: `Glob search failed: ${err.message || String(error)}`,
-				};
+				return createToolError(
+					`Glob search failed: ${err.message || String(error)}`,
+					'execution',
+					{
+						parameter: 'pattern',
+						value: pattern,
+						suggestion: 'Check if the pattern syntax is valid',
+					},
+				);
 			}
 		},
 	});

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

@@ -5,6 +5,7 @@ import { promisify } from 'node:util';
 import { join } from 'node:path';
 import DESCRIPTION from './grep.txt' with { type: 'text' };
 import { defaultIgnoreGlobs } from './ignore.ts';
+import { createToolError, type ToolResponse } from '../error.ts';
 
 const execAsync = promisify(exec);
 
@@ -39,9 +40,24 @@ export function buildGrepTool(projectRoot: string): {
 				.optional()
 				.describe('Glob patterns to exclude from search'),
 		}),
-		async execute(params) {
+		async execute(params: {
+			pattern: string;
+			path?: string;
+			include?: string;
+			ignore?: string[];
+		}): Promise<
+			ToolResponse<{
+				count: number;
+				matches: Array<{ file: string; line: number; text: string }>;
+			}>
+		> {
 			const pattern = String(params.pattern || '');
-			if (!pattern) throw new Error('pattern is required');
+			if (!pattern) {
+				return createToolError('pattern is required', 'validation', {
+					parameter: 'pattern',
+					suggestion: 'Provide a regex pattern to search for',
+				});
+			}
 
 			const p = expandTilde(String(params.path || '')).trim();
 			const isAbs = p.startsWith('/') || /^[A-Za-z]:[\\/]/.test(p);
@@ -63,10 +79,19 @@ export function buildGrepTool(projectRoot: string): {
 			} catch (error: unknown) {
 				const err = error as { code?: number; stderr?: string };
 				if (err.code === 1) {
-					return { count: 0, matches: [] };
+					return { ok: true, count: 0, matches: [] };
 				}
 				const err2 = error as { stderr?: string; message?: string };
-				throw new Error(`ripgrep failed: ${err2.stderr || err2.message}`);
+				return createToolError(
+					`ripgrep failed: ${err2.stderr || err2.message}`,
+					'execution',
+					{
+						parameter: 'pattern',
+						value: pattern,
+						suggestion:
+							'Check if ripgrep (rg) is installed and the pattern is valid',
+					},
+				);
 			}
 
 			const lines = output.trim().split('\n');
@@ -94,6 +119,7 @@ export function buildGrepTool(projectRoot: string): {
 			const finalMatches = truncated ? matches.slice(0, limit) : matches;
 
 			return {
+				ok: true,
 				count: finalMatches.length,
 				matches: finalMatches,
 			};

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

@@ -3,6 +3,7 @@ import { z } from 'zod';
 import { spawn } from 'node:child_process';
 import { join } from 'node:path';
 import DESCRIPTION from './ripgrep.txt' with { type: 'text' };
+import { createToolError, type ToolResponse } from '../error.ts';
 
 export function buildRipgrepTool(projectRoot: string): {
 	name: string;
@@ -36,7 +37,12 @@ export function buildRipgrepTool(projectRoot: string): {
 			ignoreCase?: boolean;
 			glob?: string[];
 			maxResults?: number;
-		}) {
+		}): Promise<
+			ToolResponse<{
+				count: number;
+				matches: Array<{ file: string; line: number; text: string }>;
+			}>
+		> {
 			function expandTilde(p: string) {
 				const home = process.env.HOME || process.env.USERPROFILE || '';
 				if (!home) return p;
@@ -70,7 +76,16 @@ export function buildRipgrepTool(projectRoot: string): {
 
 					proc.on('close', (code) => {
 						if (code !== 0 && code !== 1) {
-							resolve({ count: 0, matches: [], error: stderr.trim() });
+							resolve(
+								createToolError(
+									stderr.trim() || 'ripgrep failed',
+									'execution',
+									{
+										suggestion:
+											'Check if ripgrep (rg) is installed and the query is valid',
+									},
+								),
+							);
 							return;
 						}
 
@@ -86,15 +101,21 @@ export function buildRipgrepTool(projectRoot: string): {
 							const text = parts.slice(2).join(':');
 							return { file, line, text };
 						});
-						resolve({ count: matches.length, matches });
+						resolve({ ok: true, count: matches.length, matches });
 					});
 
 					proc.on('error', (err) => {
-						resolve({ count: 0, matches: [], error: String(err) });
+						resolve(
+							createToolError(String(err), 'execution', {
+								suggestion: 'Ensure ripgrep (rg) is installed',
+							}),
+						);
 					});
 				});
 			} catch (err) {
-				return { count: 0, matches: [], error: String(err) };
+				return createToolError(String(err), 'execution', {
+					suggestion: 'Ensure ripgrep (rg) is installed',
+				});
 			}
 		},
 	});

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

@@ -1,6 +1,7 @@
 import { tool, type Tool } from 'ai';
 import { z } from 'zod';
 import DESCRIPTION from './websearch.txt' with { type: 'text' };
+import { createToolError, type ToolResponse } from '../error.ts';
 
 export function buildWebSearchTool(): {
 	name: string;
@@ -42,7 +43,22 @@ export function buildWebSearchTool(): {
 			url?: string;
 			query?: string;
 			maxLength?: number;
-		}) {
+		}): Promise<
+			ToolResponse<
+				| {
+						url: string;
+						content: string;
+						contentLength: number;
+						truncated: boolean;
+						contentType: string;
+				  }
+				| {
+						query: string;
+						results: Array<{ title: string; url: string; snippet: string }>;
+						count: number;
+				  }
+			>
+		> {
 			const maxLen = maxLength ?? 50000;
 
 			if (url) {
@@ -76,9 +92,11 @@ export function buildWebSearchTool(): {
 					) {
 						content = await response.text();
 					} else {
-						return {
-							error: `Unsupported content type: ${contentType}. Only text-based content can be fetched.`,
-						};
+						return createToolError(
+							`Unsupported content type: ${contentType}. Only text-based content can be fetched.`,
+							'unsupported',
+							{ contentType },
+						);
 					}
 
 					// Strip HTML tags for better readability (basic cleaning)
@@ -93,6 +111,7 @@ export function buildWebSearchTool(): {
 					const wasTruncated = cleanContent.length > maxLen;
 
 					return {
+						ok: true,
 						url,
 						content: truncated,
 						contentLength: cleanContent.length,
@@ -102,9 +121,11 @@ export function buildWebSearchTool(): {
 				} catch (error) {
 					const errorMessage =
 						error instanceof Error ? error.message : String(error);
-					return {
-						error: `Failed to fetch URL: ${errorMessage}`,
-					};
+					return createToolError(
+						`Failed to fetch URL: ${errorMessage}`,
+						'execution',
+						{ url },
+					);
 				}
 			}
 
@@ -183,16 +204,19 @@ export function buildWebSearchTool(): {
 					}
 
 					if (results.length === 0) {
-						return {
-							error:
-								'No search results found. The search service may have changed its format or blocked the request.',
-							query,
-							suggestion:
-								'Try using the url parameter to fetch a specific webpage instead.',
-						};
+						return createToolError(
+							'No search results found. The search service may have changed its format or blocked the request.',
+							'execution',
+							{
+								query,
+								suggestion:
+									'Try using the url parameter to fetch a specific webpage instead.',
+							},
+						);
 					}
 
 					return {
+						ok: true,
 						query,
 						results,
 						count: results.length,
@@ -200,18 +224,25 @@ export function buildWebSearchTool(): {
 				} catch (error) {
 					const errorMessage =
 						error instanceof Error ? error.message : String(error);
-					return {
-						error: `Search failed: ${errorMessage}`,
-						query,
-						suggestion:
-							'Search services may be temporarily unavailable. Try using the url parameter to fetch a specific webpage instead.',
-					};
+					return createToolError(
+						`Search failed: ${errorMessage}`,
+						'execution',
+						{
+							query,
+							suggestion:
+								'Search services may be temporarily unavailable. Try using the url parameter to fetch a specific webpage instead.',
+						},
+					);
 				}
 			}
 
-			return {
-				error: 'Must provide either url or query parameter',
-			};
+			return createToolError(
+				'Must provide either url or query parameter',
+				'validation',
+				{
+					suggestion: 'Provide either a url to fetch or a query to search',
+				},
+			);
 		},
 	});