@ottocode/sdk 0.1.173

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

@@ -0,0 +1,72 @@
+import { tool, type Tool } from 'ai';
+import { z } from 'zod/v3';
+import { promises as fs } from 'node:fs';
+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';
+
+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[];
+		}): Promise<
+			ToolResponse<{
+				path: string;
+				entries: Array<{ name: string; type: string }>;
+			}>
+		> {
+			const req = expandTilde(path || '.');
+			const abs = isAbsoluteLike(req)
+				? req
+				: resolveSafePath(projectRoot, req || '.');
+			const ignored = toIgnoredBasenames(ignore);
+
+			try {
+				const dirents = await fs.readdir(abs, { withFileTypes: true });
+				const entries = dirents
+					.filter((d) => !String(d.name).startsWith('.'))
+					.map((d) => ({
+						name: String(d.name),
+						type: d.isDirectory() ? 'dir' : 'file',
+					}))
+					.filter((entry) => !(entry.type === 'dir' && ignored.has(entry.name)))
+					.sort((a, b) => a.name.localeCompare(b.name));
+				return { ok: true, path: req, entries };
+			} catch (error: unknown) {
+				const err = error as { code?: string; message?: string };
+				const message = err.message || 'ls failed';
+				return createToolError(
+					`ls failed for ${req}: ${message}`,
+					err.code === 'ENOENT' ? 'not_found' : 'execution',
+					{
+						parameter: 'path',
+						value: req,
+						suggestion:
+							err.code === 'ENOENT'
+								? 'Check if the directory exists'
+								: 'Check if the directory exists and is accessible',
+					},
+				);
+			}
+		},
+	});
+	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/v3';
+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,119 @@
+import { tool, type Tool } from 'ai';
+import { z } from 'zod/v3';
+import { readFile } from 'node:fs/promises';
+import { expandTilde, isAbsoluteLike, resolveSafePath } from './util.ts';
+import DESCRIPTION from './read.txt' with { type: 'text' };
+import { createToolError, type ToolResponse } from '../../error.ts';
+
+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;
+		}): Promise<
+			ToolResponse<{
+				path: string;
+				content: string;
+				size: number;
+				lineRange?: string;
+				totalLines?: number;
+			}>
+		> {
+			if (!path || path.trim().length === 0) {
+				return createToolError(
+					'Missing required parameter: path',
+					'validation',
+					{
+						parameter: 'path',
+						value: path,
+						suggestion: 'Provide a file path to read',
+					},
+				);
+			}
+
+			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 {
+						ok: true,
+						path: req,
+						content,
+						size: content.length,
+						lineRange: `@${startLine}-${endLine}`,
+						totalLines: lines.length,
+					};
+				}
+
+				return { ok: true, path: req, content, size: content.length };
+			} catch (error: unknown) {
+				const embedded = embeddedTextAssets[req];
+				if (embedded) {
+					const content = await readFile(embedded, 'utf-8');
+					return { ok: true, path: req, content, size: content.length };
+				}
+				const isEnoent =
+					error &&
+					typeof error === 'object' &&
+					'code' in error &&
+					error.code === 'ENOENT';
+				return createToolError(
+					isEnoent
+						? `File not found: ${req}`
+						: `Failed to read file: ${error instanceof Error ? error.message : String(error)}`,
+					isEnoent ? 'not_found' : 'execution',
+					{
+						parameter: 'path',
+						value: req,
+						suggestion: isEnoent
+							? 'Use ls or tree to find available files'
+							: undefined,
+					},
+				);
+			}
+		},
+	});
+	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,149 @@
+import { tool, type Tool } from 'ai';
+import { z } from 'zod/v3';
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+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';
+
+async function walkTree(
+	dir: string,
+	ignored: Set<string>,
+	maxDepth: number | null,
+	currentDepth: number,
+	prefix: string,
+): Promise<{ lines: string[]; dirs: number; files: number }> {
+	let dirs = 0;
+	let files = 0;
+	const lines: string[] = [];
+
+	if (maxDepth !== null && currentDepth >= maxDepth)
+		return { lines, dirs, files };
+
+	try {
+		const rawEntries = await fs.readdir(dir, { withFileTypes: true });
+		const entries = rawEntries.map((e) => ({
+			name: String(e.name),
+			isDir: e.isDirectory(),
+		}));
+
+		const filtered = entries
+			.filter((e) => !e.name.startsWith('.'))
+			.filter((e) => !(e.isDir && ignored.has(e.name)))
+			.sort((a, b) => {
+				if (a.isDir && !b.isDir) return -1;
+				if (!a.isDir && b.isDir) return 1;
+				return a.name.localeCompare(b.name);
+			});
+
+		for (let i = 0; i < filtered.length; i++) {
+			const entry = filtered[i];
+			const isLast = i === filtered.length - 1;
+			const connector = isLast ? '└── ' : '├── ';
+			const childPrefix = isLast ? '    ' : '│   ';
+
+			if (entry.isDir) {
+				dirs++;
+				lines.push(`${prefix}${connector}${entry.name}`);
+				const sub = await walkTree(
+					join(dir, entry.name),
+					ignored,
+					maxDepth,
+					currentDepth + 1,
+					`${prefix}${childPrefix}`,
+				);
+				lines.push(...sub.lines);
+				dirs += sub.dirs;
+				files += sub.files;
+			} else {
+				files++;
+				let lineCount = '';
+				try {
+					const content = await fs.readFile(join(dir, entry.name), 'utf-8');
+					const count = content.split('\n').length;
+					lineCount = ` (${count} lines)`;
+				} catch {}
+				lines.push(`${prefix}${connector}${entry.name}${lineCount}`);
+			}
+		}
+	} catch {
+		return { lines, dirs, files };
+	}
+
+	return { lines, dirs, files };
+}
+
+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[];
+		}): Promise<
+			ToolResponse<{ path: string; depth: number | null; tree: string }>
+		> {
+			const req = expandTilde(path || '.');
+			const start = isAbsoluteLike(req)
+				? req
+				: resolveSafePath(projectRoot, req || '.');
+			const ignored = toIgnoredBasenames(ignore);
+
+			try {
+				await fs.access(start);
+			} catch {
+				return createToolError(
+					`tree failed for ${req}: directory not found`,
+					'not_found',
+					{
+						parameter: 'path',
+						value: req,
+						suggestion: 'Check if the directory exists',
+					},
+				);
+			}
+
+			try {
+				const result = await walkTree(start, ignored, depth ?? null, 0, '');
+				const header = '.';
+				const summary = `\n${result.dirs} director${result.dirs === 1 ? 'y' : 'ies'}, ${result.files} file${result.files === 1 ? '' : 's'}`;
+				const output = [header, ...result.lines, summary].join('\n');
+				return { ok: true, path: req, depth: depth ?? null, tree: output };
+			} catch (error: unknown) {
+				const err = error as { message?: string };
+				return createToolError(
+					`tree failed for ${req}: ${err.message || 'unknown error'}`,
+					'execution',
+					{
+						parameter: 'path',
+						value: req,
+						suggestion: 'Check if the directory exists and is accessible',
+					},
+				);
+			}
+		},
+	});
+	return { name: 'tree', tool: tree };
+}

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

@@ -0,0 +1,11 @@
+- Render a directory tree from a starting path with line counts for each file
+- 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)
+- Each file shows its line count (e.g. "index.ts (42 lines)")
+
+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
+- Pay attention to line counts: files over 500 lines are large — prefer reading specific line ranges (startLine/endLine) or use Grep to find relevant sections instead of reading the entire file
+- Files over 2000 lines can consume significant context — always use targeted reads or search tools for these

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,106 @@
+import { tool, type Tool } from 'ai';
+import { z } from 'zod/v3';
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import {
+	buildWriteArtifact,
+	resolveSafePath,
+	expandTilde,
+	isAbsoluteLike,
+} from './util.ts';
+import DESCRIPTION from './write.txt' with { type: 'text' };
+import { createToolError, type ToolResponse } from '../../error.ts';
+
+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;
+		}): Promise<
+			ToolResponse<{
+				path: string;
+				bytes: number;
+				artifact: unknown;
+			}>
+		> {
+			if (!path || path.trim().length === 0) {
+				return createToolError(
+					'Missing required parameter: path',
+					'validation',
+					{
+						parameter: 'path',
+						value: path,
+						suggestion: 'Provide a file path to write',
+					},
+				);
+			}
+
+			const req = expandTilde(path);
+			if (isAbsoluteLike(req)) {
+				return createToolError(
+					`Refusing to write outside project root: ${req}. Use a relative path within the project.`,
+					'permission',
+					{
+						parameter: 'path',
+						value: req,
+						suggestion: 'Use a relative path within the project',
+					},
+				);
+			}
+			const abs = resolveSafePath(projectRoot, req);
+
+			try {
+				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 {
+					ok: true,
+					path: req,
+					bytes: content.length,
+					artifact,
+				};
+			} catch (error: unknown) {
+				return createToolError(
+					`Failed to write file: ${error instanceof Error ? error.message : String(error)}`,
+					'execution',
+					{
+						parameter: 'path',
+						value: req,
+					},
+				);
+			}
+		},
+	});
+	return { name: 'write', tool: write };
+}

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

@@ -0,0 +1,11 @@
+- 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:
+- Use for creating NEW files
+- Use when replacing >70% of a file's content (almost complete rewrite)
+- NEVER use for partial/targeted edits - use apply_patch or edit instead
+- Using write for partial edits wastes output tokens and risks hallucinating unchanged parts
+- Prefer idempotent writes by providing the full intended content when you do use write

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