@oh-my-pi/pi-coding-agent 16.2.12 → 16.3.0

package/src/exec/bash-executor.ts

@@ -3,7 +3,6 @@
  *
  * Uses brush-core via native bindings for shell execution.
  */
-import * as fs from "node:fs/promises";
 import { ExponentialYield } from "@oh-my-pi/pi-agent-core/utils/yield";
 import { executeShell, type MinimizerOptions, Shell, type ShellRunResult } from "@oh-my-pi/pi-natives";
 import { isExecutable, type ShellConfig } from "@oh-my-pi/pi-utils/procmgr";
@@ -51,6 +50,7 @@ export interface BashResult {
 	outputLines: number;
 	outputBytes: number;
 	artifactId?: string;
+	workingDir?: string;
 }
 
 const shellSessions = new Map<string, Shell>();
@@ -115,16 +115,10 @@ function quarantineShellSession(
 		.catch(() => undefined);
 }
 
-async function resolveShellCwd(cwd: string | undefined): Promise<string | undefined> {
-	if (!cwd) return undefined;
-
-	try {
-		// Brush preserves the working directory string verbatim, so resolve symlinks
-		// up front to keep `pwd` aligned with tools like `git worktree list`.
-		return await fs.realpath(cwd);
-	} catch {
-		return cwd;
-	}
+function resolveShellCwd(cwd: string | undefined): string | undefined {
+	// Preserve the caller's logical cwd string. Brush uses this value to update `PWD` and its
+	// internal working directory, so realpathing here collapses symlinks before the shell sees them.
+	return cwd;
 }
 
 /** Translate `ShellMinimizerSettings` into native `MinimizerOptions`, or `undefined` when disabled. */
@@ -219,7 +213,7 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 
 	const minimizer = buildMinimizerOptions(settings.getGroup("shellMinimizer"));
 
-	const commandCwd = await resolveShellCwd(options?.cwd);
+	const commandCwd = resolveShellCwd(options?.cwd);
 	const commandEnv = buildNonInteractiveEnv(options?.env);
 
 	// Apply command prefix if configured
@@ -429,6 +423,7 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 		return {
 			exitCode: winner.result.exitCode,
 			cancelled: false,
+			workingDir: winner.result.workingDir,
 			...(await sink.dump()),
 		};
 	} catch (err) {

package/src/extensibility/legacy-pi-coding-agent-shim.ts

@@ -12,21 +12,140 @@
  * the same module identity as a direct `@oh-my-pi/pi-coding-agent` import.
  */
 
-import type { AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
 import type { TSchema } from "@oh-my-pi/pi-ai";
+import { Text } from "@oh-my-pi/pi-tui";
 import { parseFrontmatter as parseOmpFrontmatter } from "@oh-my-pi/pi-utils";
-import { Settings } from "../config/settings";
-import { BUILTIN_TOOLS, type Tool, type ToolSession } from "../tools";
+import { type SettingPath, Settings } from "../config/settings";
+import { EditTool } from "../edit";
+import {
+	DEFAULT_MAX_BYTES,
+	DEFAULT_MAX_LINES,
+	type TruncationResult,
+	truncateHead,
+	truncateTail,
+} from "../session/streaming-output";
+import type { Tool, ToolSession } from "../tools";
+import { BashTool } from "../tools/bash";
+import { GlobTool } from "../tools/glob";
+import { GrepTool } from "../tools/grep";
+import { ReadTool } from "../tools/read";
+import { formatBytes } from "../tools/render-utils";
+import { WriteTool } from "../tools/write";
 import type { ToolDefinition } from "./extensions/types";
 import { Type } from "./typebox";
 
 const TOOL_DEFINITION_MARKER = "__isToolDefinition";
 const LEGACY_BUILTIN_TOOL_MARKER = "__ompLegacyBuiltinTool";
 const LEGACY_CODING_TOOL_NAMES = ["read", "bash", "edit", "write"] as const;
+const LEGACY_READ_ONLY_TOOL_NAMES = ["read", "grep", "find", "ls"] as const;
 
 type LegacyCodingToolName = (typeof LEGACY_CODING_TOOL_NAMES)[number];
+type LegacyRegistryToolName = LegacyCodingToolName | "grep" | "glob";
 type LegacyBuiltinToolDefinition = ToolDefinition & { [LEGACY_BUILTIN_TOOL_MARKER]: true };
 
+type LegacySettingOverrides = Partial<Record<SettingPath, unknown>>;
+
+interface LegacyThemeLike {
+	fg(color: string, text: string): string;
+	bold(text: string): string;
+}
+
+export interface BashSpawnContext {
+	command: string;
+	cwd: string;
+	env: NodeJS.ProcessEnv;
+}
+
+export type BashSpawnHook = (context: BashSpawnContext) => BashSpawnContext;
+
+export interface BashOperations {
+	exec: (
+		command: string,
+		cwd: string,
+		options: {
+			onData: (data: Buffer) => void;
+			signal?: AbortSignal;
+			timeout?: number;
+			env?: NodeJS.ProcessEnv;
+		},
+	) => Promise<{ exitCode: number | null }>;
+}
+
+export interface BashToolOptions {
+	operations?: BashOperations;
+	commandPrefix?: string;
+	spawnHook?: BashSpawnHook;
+}
+
+export interface ReadToolOptions {
+	/** Auto-resize large images; maps onto the `images.autoResize` setting. Default: true. */
+	autoResizeImages?: boolean;
+}
+
+export interface GrepToolOptions {
+	/**
+	 * Unsupported. The historical grep operations seam (isDirectory/readFile for
+	 * context lines) never delegated the search itself — ripgrep always ran
+	 * locally — and the built-in native grep tool exposes no filesystem seam at
+	 * all. Supplying operations throws at tool creation instead of silently
+	 * searching the local filesystem.
+	 */
+	operations?: unknown;
+}
+
+export interface FindOperations {
+	exists: (absolutePath: string) => Promise<boolean> | boolean;
+	glob: (pattern: string, cwd: string, options: { ignore: string[]; limit: number }) => Promise<string[]> | string[];
+}
+
+export interface FindToolOptions {
+	operations?: FindOperations;
+}
+
+export interface LsOperations {
+	exists: (absolutePath: string) => Promise<boolean> | boolean;
+	stat: (absolutePath: string) => Promise<{ isDirectory(): boolean }> | { isDirectory(): boolean };
+	readdir: (absolutePath: string) => Promise<string[]> | string[];
+}
+
+export interface LsToolOptions {
+	operations?: LsOperations;
+}
+
+const legacyBashSchema = Type.Object({
+	command: Type.String({ description: "Bash command to execute" }),
+	timeout: Type.Optional(Type.Number({ description: "Timeout in seconds" })),
+});
+
+const legacyReadSchema = Type.Object({
+	path: Type.String({ description: "Path to read" }),
+	offset: Type.Optional(Type.Number({ description: "1-based line offset" })),
+	limit: Type.Optional(Type.Number({ description: "Maximum lines to read" })),
+});
+
+const legacyGrepSchema = Type.Object({
+	pattern: Type.String({ description: "Search pattern" }),
+	path: Type.Optional(Type.String({ description: "Directory or file to search" })),
+	glob: Type.Optional(Type.String({ description: "Glob filter" })),
+	ignoreCase: Type.Optional(Type.Boolean({ description: "Case-insensitive search" })),
+	literal: Type.Optional(Type.Boolean({ description: "Treat pattern as a literal string" })),
+	context: Type.Optional(Type.Number({ description: "Context lines" })),
+});
+
+const legacyFindSchema = Type.Object({
+	pattern: Type.String({ description: "Glob pattern to match files" }),
+	path: Type.Optional(Type.String({ description: "Directory to search" })),
+	limit: Type.Optional(Type.Number({ description: "Maximum results" })),
+});
+
+const legacyLsSchema = Type.Object({
+	path: Type.Optional(Type.String({ description: "Directory to list" })),
+	limit: Type.Optional(Type.Number({ description: "Maximum entries" })),
+});
+
 function markToolDefinition<TParams extends TSchema, TDetails>(
 	tool: ToolDefinition<TParams, TDetails>,
 ): ToolDefinition<TParams, TDetails> {
@@ -38,25 +157,37 @@ function markToolDefinition<TParams extends TSchema, TDetails>(
 	});
 	return tool;
 }
-function legacyToolSession(cwd: string): ToolSession {
+
+function legacyToolSession(cwd: string, settingOverrides?: LegacySettingOverrides): ToolSession {
 	return {
 		cwd,
 		hasUI: false,
 		getSessionFile: () => null,
 		getSessionSpawns: () => null,
-		settings: Settings.isolated(),
+		settings: Settings.isolated(settingOverrides),
 	};
 }
 
-function createBuiltinTool(cwd: string, name: LegacyCodingToolName): Tool {
-	const tool = BUILTIN_TOOLS[name](legacyToolSession(cwd));
-	if (tool instanceof Promise) {
-		throw new Error(`Built-in ${name} tool factory unexpectedly returned a promise.`);
-	}
-	if (!tool) {
-		throw new Error(`Built-in ${name} tool is unavailable.`);
+function createRegistryTool(
+	cwd: string,
+	name: LegacyRegistryToolName,
+	settingOverrides?: LegacySettingOverrides,
+): Tool {
+	const session = legacyToolSession(cwd, settingOverrides);
+	switch (name) {
+		case "bash":
+			return new BashTool(session);
+		case "edit":
+			return new EditTool(session);
+		case "glob":
+			return new GlobTool(session);
+		case "grep":
+			return new GrepTool(session);
+		case "read":
+			return new ReadTool(session);
+		case "write":
+			return new WriteTool(session);
 	}
-	return tool;
 }
 
 async function executeBuiltinTool(
@@ -67,12 +198,12 @@ async function executeBuiltinTool(
 	signal: AbortSignal | undefined,
 	onUpdate: AgentToolUpdateCallback | undefined,
 ) {
-	const tool = createBuiltinTool(cwd, name);
+	const tool = createRegistryTool(cwd, name);
 	return tool.execute(toolCallId, params, signal, onUpdate);
 }
 
 function legacyBuiltinTool(cwd: string, name: LegacyCodingToolName): ToolDefinition {
-	const tool = createBuiltinTool(cwd, name);
+	const tool = createRegistryTool(cwd, name);
 	const definition: LegacyBuiltinToolDefinition = {
 		name: tool.name,
 		label: tool.label,
@@ -88,11 +219,144 @@ function legacyBuiltinTool(cwd: string, name: LegacyCodingToolName): ToolDefinit
 	return markToolDefinition(definition);
 }
 
+function stringField(value: unknown, key: string): string | undefined {
+	if (value === null || typeof value !== "object") return undefined;
+	const field = Reflect.get(value, key);
+	return typeof field === "string" ? field : undefined;
+}
+
+function numberField(value: unknown, key: string): number | undefined {
+	if (value === null || typeof value !== "object") return undefined;
+	const field = Reflect.get(value, key);
+	return typeof field === "number" ? field : undefined;
+}
+
+function booleanField(value: unknown, key: string): boolean | undefined {
+	if (value === null || typeof value !== "object") return undefined;
+	const field = Reflect.get(value, key);
+	return typeof field === "boolean" ? field : undefined;
+}
+
+function isLegacyThemeLike(value: unknown): value is LegacyThemeLike {
+	if (value === null || typeof value !== "object") return false;
+	return typeof Reflect.get(value, "fg") === "function" && typeof Reflect.get(value, "bold") === "function";
+}
+
+function renderTheme(second: unknown, third: unknown): LegacyThemeLike | undefined {
+	if (isLegacyThemeLike(second)) return second;
+	if (isLegacyThemeLike(third)) return third;
+	return undefined;
+}
+
+function themedTitle(theme: LegacyThemeLike | undefined, title: string): string {
+	return theme ? theme.fg("toolTitle", theme.bold(title)) : title;
+}
+
+function themedMuted(theme: LegacyThemeLike | undefined, text: string): string {
+	return theme ? theme.fg("toolOutput", text) : text;
+}
+
+function textResult(result: AgentToolResult<unknown> | undefined): string {
+	return result?.content.find(block => block.type === "text")?.text ?? "";
+}
+
+function legacyRenderResult(result: AgentToolResult<unknown>, _options: unknown, themeArg: unknown): Text {
+	const theme = renderTheme(themeArg, undefined);
+	const output = textResult(result);
+	return new Text(output ? `\n${themedMuted(theme, output)}` : "", 0, 0);
+}
+
+function lineRangePath(readPath: string, offset: number | undefined, limit: number | undefined): string {
+	if (offset === undefined && limit === undefined) return readPath;
+	const start = Math.max(1, Math.floor(offset ?? 1));
+	if (limit === undefined) return `${readPath}:${start}`;
+	const end = Math.max(start, start + Math.max(1, Math.floor(limit)) - 1);
+	return `${readPath}:${start}-${end}`;
+}
+
+function escapeRegexLiteral(value: string): string {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function joinLegacyGlob(searchPath: string, pattern: string): string {
+	if (path.isAbsolute(pattern)) return pattern;
+	if (!searchPath || searchPath === ".") return pattern;
+	return path.join(searchPath, pattern);
+}
+
+function normalizeLegacyLimit(limit: number | undefined, fallback: number): number {
+	if (limit === undefined || !Number.isFinite(limit)) return fallback;
+	return Math.max(1, Math.floor(limit));
+}
+
+function appendStatus(text: string, status: string): string {
+	return text ? `${text}\n\n${status}` : status;
+}
+
+function legacyBashSnapshot(output: string): { text: string; details?: { truncation: TruncationResult } } {
+	const truncation = truncateTail(output, { maxLines: DEFAULT_MAX_LINES, maxBytes: DEFAULT_MAX_BYTES });
+	if (!truncation.truncated) {
+		return { text: truncation.content };
+	}
+	const startLine = truncation.totalLines - (truncation.outputLines ?? 0) + 1;
+	const note =
+		truncation.truncatedBy === "lines"
+			? `Showing lines ${startLine}-${truncation.totalLines} of ${truncation.totalLines}`
+			: `Showing lines ${startLine}-${truncation.totalLines} of ${truncation.totalLines} (${formatBytes(DEFAULT_MAX_BYTES)} limit)`;
+	return {
+		text: `${truncation.content}\n\n[${note}]`,
+		details: { truncation },
+	};
+}
+
+async function executeLegacyBashOperations(
+	operations: BashOperations,
+	spawn: BashSpawnContext,
+	timeout: number | undefined,
+	signal: AbortSignal | undefined,
+	onUpdate: AgentToolUpdateCallback | undefined,
+): Promise<AgentToolResult> {
+	let output = "";
+	const onData = (data: Buffer) => {
+		output += data.toString("utf8");
+		if (onUpdate) {
+			const snapshot = legacyBashSnapshot(output);
+			onUpdate({ content: [{ type: "text", text: snapshot.text }], details: snapshot.details });
+		}
+	};
+	try {
+		const result = await operations.exec(spawn.command, spawn.cwd, {
+			onData,
+			signal,
+			timeout,
+			env: spawn.env,
+		});
+		const snapshot = legacyBashSnapshot(output);
+		const text = snapshot.text || "(no output)";
+		if (result.exitCode !== 0 && result.exitCode !== null) {
+			throw new Error(appendStatus(text, `Command exited with code ${result.exitCode}`));
+		}
+		return { content: [{ type: "text", text }], details: snapshot.details };
+	} catch (err) {
+		const snapshot = legacyBashSnapshot(output);
+		const text = snapshot.text;
+		if (err instanceof Error && err.message === "aborted") {
+			throw new Error(appendStatus(text, "Command aborted"));
+		}
+		if (err instanceof Error && err.message.startsWith("timeout:")) {
+			throw new Error(appendStatus(text, `Command timed out after ${err.message.slice("timeout:".length)} seconds`));
+		}
+		throw err;
+	}
+}
+
+/** Parse frontmatter using the historical Pi package-root helper. */
 export interface ParsedFrontmatter<T extends Record<string, unknown> = Record<string, unknown>> {
 	frontmatter: T;
 	body: string;
 }
 
+/** Parse YAML frontmatter and throw on invalid metadata. */
 export function parseFrontmatter<T extends Record<string, unknown> = Record<string, unknown>>(
 	content: string,
 ): ParsedFrontmatter<T> {
@@ -100,20 +364,273 @@ export function parseFrontmatter<T extends Record<string, unknown> = Record<stri
 	return { frontmatter: frontmatter as T, body };
 }
 
+/** Return content without YAML frontmatter. */
 export function stripFrontmatter(content: string): string {
 	return parseFrontmatter(content).body;
 }
 
+/** Mark an extension-authored tool as a Pi-compatible tool definition. */
 export function defineTool<TParams extends TSchema = TSchema, TDetails = unknown>(
 	tool: ToolDefinition<TParams, TDetails>,
 ): ToolDefinition<TParams, TDetails> {
 	return markToolDefinition(tool);
 }
 
+/** Create the legacy read tool definition. */
+export function createReadToolDefinition(cwd: string, options?: ReadToolOptions): ToolDefinition {
+	const tool = createRegistryTool(
+		cwd,
+		"read",
+		options?.autoResizeImages === undefined ? undefined : { "images.autoResize": options.autoResizeImages },
+	);
+	return markToolDefinition({
+		name: "read",
+		label: "Read",
+		description: tool.description,
+		parameters: legacyReadSchema,
+		approval: "read",
+		renderCall: (params, options, themeArg) => {
+			const theme = renderTheme(options, themeArg);
+			const readPath = stringField(params, "path") ?? "";
+			return new Text(`${themedTitle(theme, "read")} ${themedMuted(theme, readPath)}`, 0, 0);
+		},
+		renderResult: legacyRenderResult,
+		execute: (toolCallId, params, signal, onUpdate) => {
+			const readPath = stringField(params, "path") ?? "";
+			const pathWithRange = lineRangePath(readPath, numberField(params, "offset"), numberField(params, "limit"));
+			return tool.execute(toolCallId, { path: pathWithRange }, signal, onUpdate);
+		},
+	});
+}
+
+/** Create the legacy read tool. */
+export function createReadTool(cwd: string, options?: ReadToolOptions): ToolDefinition {
+	return createReadToolDefinition(cwd, options);
+}
+
+/** Create the legacy bash tool definition. */
+export function createBashToolDefinition(cwd: string, options?: BashToolOptions): ToolDefinition {
+	const tool = createRegistryTool(cwd, "bash");
+	return markToolDefinition({
+		name: "bash",
+		label: "Bash",
+		description: tool.description,
+		parameters: legacyBashSchema,
+		approval: "exec",
+		renderCall: (params, optionsArg, themeArg) => {
+			const theme = renderTheme(optionsArg, themeArg);
+			const command = stringField(params, "command") ?? "";
+			return new Text(`${themedTitle(theme, "bash")} ${themedMuted(theme, command)}`, 0, 0);
+		},
+		renderResult: legacyRenderResult,
+		execute: (toolCallId, params, signal, onUpdate) => {
+			const rawCommand = stringField(params, "command") ?? "";
+			const command = options?.commandPrefix ? `${options.commandPrefix}\n${rawCommand}` : rawCommand;
+			const timeout = numberField(params, "timeout");
+			const spawn = options?.spawnHook?.({ command, cwd, env: process.env });
+			if (options?.operations) {
+				return executeLegacyBashOperations(
+					options.operations,
+					{ command: spawn?.command ?? command, cwd: spawn?.cwd ?? cwd, env: spawn?.env ?? process.env },
+					timeout,
+					signal,
+					onUpdate,
+				);
+			}
+			return tool.execute(
+				toolCallId,
+				{
+					command: spawn?.command ?? command,
+					cwd: spawn?.cwd ?? cwd,
+					env: spawn?.env,
+					timeout,
+				},
+				signal,
+				onUpdate,
+			);
+		},
+	});
+}
+
+/** Create the legacy bash tool. */
+export function createBashTool(cwd: string, options?: BashToolOptions): ToolDefinition {
+	return createBashToolDefinition(cwd, options);
+}
+
+/** Create the legacy grep tool definition. */
+export function createGrepToolDefinition(cwd: string, options?: GrepToolOptions): ToolDefinition {
+	if (options?.operations) {
+		throw new Error(
+			"Legacy GrepToolOptions.operations is not supported: the built-in grep tool searches the local " +
+				"filesystem natively and exposes no pluggable filesystem seam (the historical seam only customized " +
+				"context-line reads; the search itself always ran locally). Register a custom grep tool via " +
+				"defineTool() instead of passing operations to createGrepTool()/createGrepToolDefinition().",
+		);
+	}
+	const tool = createRegistryTool(cwd, "grep");
+	return markToolDefinition({
+		name: "grep",
+		label: "grep",
+		description: "Search file contents for a pattern.",
+		parameters: legacyGrepSchema,
+		approval: "read",
+		renderCall: (params, optionsArg, themeArg) => {
+			const theme = renderTheme(optionsArg, themeArg);
+			const pattern = stringField(params, "pattern") ?? "";
+			const searchPath = stringField(params, "path") ?? ".";
+			return new Text(`${themedTitle(theme, "grep")} ${themedMuted(theme, `/${pattern}/ in ${searchPath}`)}`, 0, 0);
+		},
+		renderResult: legacyRenderResult,
+		execute: (toolCallId, params, signal, onUpdate) => {
+			const rawPattern = stringField(params, "pattern") ?? "";
+			const pattern = booleanField(params, "literal") ? escapeRegexLiteral(rawPattern) : rawPattern;
+			const searchPath = stringField(params, "path") ?? ".";
+			const glob = stringField(params, "glob");
+			const context = numberField(params, "context");
+			// The new grep reads context from settings fixed at construction; build a
+			// per-call tool when the model passes an explicit legacy `context`.
+			const grepTool =
+				context === undefined
+					? tool
+					: createRegistryTool(cwd, "grep", {
+							"grep.contextBefore": Math.max(0, Math.floor(context)),
+							"grep.contextAfter": Math.max(0, Math.floor(context)),
+						});
+			return grepTool.execute(
+				toolCallId,
+				{
+					pattern,
+					paths: glob ? joinLegacyGlob(searchPath, glob) : searchPath,
+					case: booleanField(params, "ignoreCase") ? false : undefined,
+				},
+				signal,
+				onUpdate,
+			);
+		},
+	});
+}
+
+/** Create the legacy grep tool. */
+export function createGrepTool(cwd: string, options?: GrepToolOptions): ToolDefinition {
+	return createGrepToolDefinition(cwd, options);
+}
+
+/** Create the legacy find tool definition. */
+export function createFindToolDefinition(cwd: string, options?: FindToolOptions): ToolDefinition {
+	const tool = createRegistryTool(cwd, "glob");
+	return markToolDefinition({
+		name: "find",
+		label: "find",
+		description: "Find files by glob pattern.",
+		parameters: legacyFindSchema,
+		approval: "read",
+		renderCall: (params, optionsArg, themeArg) => {
+			const theme = renderTheme(optionsArg, themeArg);
+			const pattern = stringField(params, "pattern") ?? "";
+			const searchPath = stringField(params, "path") ?? ".";
+			return new Text(`${themedTitle(theme, "find")} ${themedMuted(theme, `${pattern} in ${searchPath}`)}`, 0, 0);
+		},
+		renderResult: legacyRenderResult,
+		execute: async (toolCallId, params, signal, onUpdate) => {
+			const pattern = stringField(params, "pattern") ?? "*";
+			const searchPath = stringField(params, "path") ?? ".";
+			const limit = normalizeLegacyLimit(numberField(params, "limit"), 1000);
+			const absolutePath = path.resolve(cwd, searchPath);
+			if (options?.operations) {
+				if (!(await options.operations.exists(absolutePath))) {
+					throw new Error(`Path not found: ${absolutePath}`);
+				}
+				const matches = await options.operations.glob(pattern, absolutePath, {
+					ignore: ["**/node_modules/**", "**/.git/**"],
+					limit,
+				});
+				const output = matches
+					.map(match => {
+						const rel = path.isAbsolute(match) ? path.relative(absolutePath, match) : match;
+						return rel.split(path.sep).join("/");
+					})
+					.join("\n");
+				const truncation = truncateHead(output, { maxLines: Number.MAX_SAFE_INTEGER });
+				return {
+					content: [{ type: "text", text: truncation.content || "No files found matching pattern" }],
+					details: truncation.truncated ? { truncation } : undefined,
+				};
+			}
+			return tool.execute(
+				toolCallId,
+				{ paths: [joinLegacyGlob(searchPath, pattern)], hidden: true, gitignore: true, limit },
+				signal,
+				onUpdate,
+			);
+		},
+	});
+}
+
+/** Create the legacy find tool. */
+export function createFindTool(cwd: string, options?: FindToolOptions): ToolDefinition {
+	return createFindToolDefinition(cwd, options);
+}
+
+/** Create the legacy ls tool definition. */
+export function createLsToolDefinition(cwd: string, options?: LsToolOptions): ToolDefinition {
+	return markToolDefinition({
+		name: "ls",
+		label: "ls",
+		description: "List directory entries.",
+		parameters: legacyLsSchema,
+		approval: "read",
+		renderCall: (params, optionsArg, themeArg) => {
+			const theme = renderTheme(optionsArg, themeArg);
+			return new Text(`${themedTitle(theme, "ls")} ${themedMuted(theme, stringField(params, "path") ?? ".")}`, 0, 0);
+		},
+		renderResult: legacyRenderResult,
+		execute: async (_toolCallId, params, _signal, _onUpdate) => {
+			const rawPath = stringField(params, "path") ?? ".";
+			const limit = normalizeLegacyLimit(numberField(params, "limit"), 500);
+			const absolutePath = path.resolve(cwd, rawPath);
+			const ops = options?.operations;
+			const exists = ops
+				? await ops.exists(absolutePath)
+				: await fs.stat(absolutePath).then(
+						() => true,
+						() => false,
+					);
+			if (!exists) throw new Error(`Path not found: ${absolutePath}`);
+			const stat = ops ? await ops.stat(absolutePath) : await fs.stat(absolutePath);
+			if (!stat.isDirectory()) {
+				return { content: [{ type: "text", text: rawPath }] };
+			}
+			const entries = ops ? await ops.readdir(absolutePath) : await fs.readdir(absolutePath);
+			const sorted = [...entries].sort((a, b) => a.localeCompare(b));
+			const limited = sorted.slice(0, limit);
+			const output = limited.join("\n");
+			const details = sorted.length > limited.length ? { entryLimitReached: limit } : undefined;
+			const suffix = details ? `\n\n[${limit} entries limit reached]` : "";
+			return { content: [{ type: "text", text: `${output}${suffix}` }], details };
+		},
+	});
+}
+
+/** Create the legacy ls tool. */
+export function createLsTool(cwd: string, options?: LsToolOptions): ToolDefinition {
+	return createLsToolDefinition(cwd, options);
+}
+
+/** Create legacy read, bash, edit, and write tools. */
 export function createCodingTools(cwd: string): ToolDefinition[] {
 	return LEGACY_CODING_TOOL_NAMES.map(name => legacyBuiltinTool(cwd, name));
 }
 
+/** Create legacy read, grep, find, and ls tools. */
+export function createReadOnlyTools(cwd: string): ToolDefinition[] {
+	return LEGACY_READ_ONLY_TOOL_NAMES.map(name => {
+		if (name === "read") return createReadTool(cwd);
+		if (name === "grep") return createGrepTool(cwd);
+		if (name === "find") return createFindTool(cwd);
+		return createLsTool(cwd);
+	});
+}
+
 export const SettingsManager = {
 	create(cwd: string, agentDir?: string): Promise<Settings> {
 		return Settings.init({ cwd, agentDir });
@@ -125,4 +642,5 @@ export const SettingsManager = {
 } as const;
 
 export * from "../index";
-export { Type };
+export { formatBytes as formatSize } from "../tools/render-utils";
+export { Type } from "./typebox";