// 内置工具的全部名字：模型按名字猜错会直接拿到 Tool <name> not found
export const allToolNames: Set<ToolName> = new Set([
	// 四个只读：read 读文件，grep/find 搜内容与文件名，ls 列目录
	"read",
	// 两个任意副作用：bash 和 powershell 能改任何路径、跑任何命令
	"bash",
	"powershell",
	// 两个写入：write 整file覆盖，edit 做局部精确替换
	"edit",
	"write",
	"grep",
	"find",
	"ls",
]);

// 错：普通名和修饰符混在一起，抛错
tools: ["read", "+grep"]

// 对：全是普通名，等于白名单
tools: ["read", "grep", "find", "ls"]

// 对：全是修饰符，在默认集合（read/bash/edit/write）上增减
tools: ["-bash", "-edit", "-write", "+grep"]

// 方案一：自定义工具名写进白名单
tools: ["read", "grep", "find", "ls", "ws_read", "ws_search", "ws_edit"]

// 方案二：用黑名单收敛内置工具，自定义工具不受影响
excludeTools: ["bash", "write", "edit"]

import { basename, isAbsolute, relative, resolve, sep } from "node:path";

/**
 * 把模型给的路径解析到工作区内。越界直接抛错，不做静默截断。
 * 相对路径基于工作区根解析；绝对路径原样参与校验。
 */
export function resolveInWorkspace(workspaceRoot: string, requestedPath: string): string {
	const root = resolve(workspaceRoot);
	const target = isAbsolute(requestedPath) ? resolve(requestedPath) : resolve(root, requestedPath);

	const rel = relative(root, target);
	// rel 为空表示就是根目录本身；以 ".." 开头说明已经跑出去了
	if (rel !== "" && (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel))) {
		throw new Error(
			`路径越界：${requestedPath} 解析为 ${target}，超出工作区 ${root}。` +
				`请使用工作区内的相对路径，例如 src/${basename(target)}。`,
		);
	}
	return target;
}

import { realpath } from "node:fs/promises";
import { isAbsolute, relative, resolve, sep } from "node:path";

/** 软链接目标可能落在工作区外，需要在 realpath 之后再校验一次。 */
export async function resolveRealInWorkspace(workspaceRoot: string, requestedPath: string): Promise<string> {
	// 根目录也要 realpath：工作区本身可能是软链接，不解析会拿错基准
	const root = await realpath(resolve(workspaceRoot));
	// 新建文件时 realpath 会失败，那不是越界，退回词法解析结果
	const target = await realpath(resolve(root, requestedPath)).catch(() => resolve(root, requestedPath));
	const rel = relative(root, target);
	// rel 为空表示就是根目录本身；以 ".." 开头说明已经跑出去了
	if (rel !== "" && (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel))) {
		throw new Error(`路径越界（经软链接解析）：${requestedPath} -> ${target}，超出工作区 ${root}。`);
	}
	return target;
}

import { readdir, readFile } from "node:fs/promises";
import { basename, dirname } from "node:path";
import { Type } from "@earendil-works/pi-ai";
import { defineTool, truncateHead } from "@earendil-works/pi-coding-agent";

/** 找出目录下与目标文件名最接近的条目，让模型能直接改对路径。 */
async function closestSiblings(dir: string, wanted: string): Promise<string[]> {
	try {
		const entries = await readdir(dir);
		const target = basename(wanted).toLowerCase();
		const stem = target.replace(/\.[^.]+$/, "");
		return entries
			.filter((name) => {
				const lower = name.toLowerCase();
				return lower.includes(stem) || stem.includes(lower.replace(/\.[^.]+$/, ""));
			})
			.slice(0, 5);
	} catch {
		return [];
	}
}

export function createWorkspaceReadTool(workspaceRoot: string) {
	return defineTool({
		name: "ws_read",
		label: "读取文件",
		description:
			"读取工作区内的文件内容。path 必须是工作区内的相对路径。文件不存在时错误信息会列出同目录下的相近文件。",
		parameters: Type.Object({
			path: Type.String({ description: "工作区内的相对路径，例如 src/index.ts" }),
			offset: Type.Optional(Type.Number({ description: "起始行号（1 起）" })),
			limit: Type.Optional(Type.Number({ description: "最多读取的行数" })),
		}),
		async execute(_toolCallId, params, signal) {
			// 先校验路径再碰文件系统：越界的请求连 open 都不会走到
			const absolute = await resolveRealInWorkspace(workspaceRoot, params.path);

			let content: string;
			try {
				content = await readFile(absolute, "utf-8");
			} catch (error: any) {
				if (error?.code === "ENOENT") {
					// 错误信息里带上相近文件名，模型能直接改对路径，不用多跑一轮 ls
					const siblings = await closestSiblings(dirname(absolute), params.path);
					const hint = siblings.length
						? `同目录下相近的文件：${siblings.join("、")}`
						: `目录 ${dirname(absolute)} 下没有匹配的条目，可用 ls 查看目录内容。`;
					throw new Error(`文件不存在：${params.path}。${hint}`);
				}
				if (error?.code === "EISDIR") {
					throw new Error(`${params.path} 是目录，不能读取。请改用 ws_ls 列出其中的文件。`);
				}
				throw error;
			}

			if (signal?.aborted) throw new Error("操作已取消");

			const lines = content.split("\n");
			// offset 是 1 起的行号，切片前要先减一
			const start = params.offset ? Math.max(0, params.offset - 1) : 0;
			const end = params.limit ? start + params.limit : lines.length;
			const slice = lines.slice(start, end).join("\n");

			// 用官方截断工具，和内置 read 保持同一套阈值
			const truncation = truncateHead(slice);

			return {
				// content 给模型读，details 给程序读，两者不要混
				content: [{ type: "text", text: truncation.content }],
				details: {
					path: params.path,
					lines: end - start,
					totalLines: lines.length,
					truncation: truncation.truncated ? truncation : undefined,
				},
			};
		},
	});
}

import { Type } from "@earendil-works/pi-ai";
import { createGrepTool, defineTool } from "@earendil-works/pi-coding-agent";

export function createWorkspaceSearchTool(workspaceRoot: string) {
	return defineTool({
		name: "ws_search",
		label: "搜索文件内容",
		description: "在工作区内按正则搜索文件内容，返回 路径:行号: 内容 的形式。",
		parameters: Type.Object({
			pattern: Type.String({ description: "正则表达式" }),
			path: Type.Optional(Type.String({ description: "限定搜索目录，相对工作区根" })),
			limit: Type.Optional(Type.Number({ description: "最多返回多少条匹配，默认 50" })),
		}),
		async execute(_toolCallId, params, signal) {
			// path 参数先过边界校验：模型给的路径在这里就被替换成已验证的绝对路径
			const searchRoot = params.path
				? await resolveRealInWorkspace(workspaceRoot, params.path)
				: await resolveRealInWorkspace(workspaceRoot, ".");

			// 复用内置 grep 的后端，但把搜索根和结果上限都钉死在工作区内。
			const grep = createGrepTool(searchRoot);
			const result = await grep.execute(
				"ws_search",
				// 上限再夹一层 200：模型可以传更大的 limit，但搜索结果会撑爆上下文
				{ pattern: params.pattern, path: searchRoot, limit: Math.min(params.limit ?? 50, 200) },
				signal,
			);

			return {
				// content 原样透传给模型，details 里补上这次实际搜的根
				content: result.content,
				details: { ...(result.details ?? {}), root: params.path ?? "." },
			};
		},
	});
}

import { mkdir, readFile, writeFile } from "node:fs/promises";
import { dirname } from "node:path";
import { Type } from "@earendil-works/pi-ai";
import { defineTool } from "@earendil-works/pi-coding-agent";

export function createWorkspaceEditTool(workspaceRoot: string) {
	return defineTool({
		name: "ws_edit",
		label: "精确编辑文件",
		description: "在工作区文件内做精确文本替换。oldText 必须在文件中唯一出现，否则报错并给出出现次数。",
		parameters: Type.Object({
			path: Type.String({ description: "工作区内的相对路径" }),
			oldText: Type.String({ description: "要被替换的原文，必须唯一出现" }),
			newText: Type.String({ description: "替换后的新文本" }),
		}),
		async execute(_toolCallId, params, signal) {
			// 编辑前同样要过边界校验，否则模型能改到工作区之外
			const absolute = await resolveRealInWorkspace(workspaceRoot, params.path);

			let content: string;
			try {
				content = await readFile(absolute, "utf-8");
			} catch (error: any) {
				if (error?.code === "ENOENT") {
					throw new Error(`文件不存在：${params.path}，无法编辑。请先用 ws_search 确认路径。`);
				}
				throw error;
			}

			// 用出现次数代替「取第一个匹配」：不唯一就报错，让模型自己扩大上下文
			const occurrences = content.split(params.oldText).length - 1;
			if (occurrences === 0) {
				throw new Error(
					`在 ${params.path} 中找不到 oldText。请先用 ws_read 读取该文件的准确内容，再构造 oldText。`,
				);
			}
			if (occurrences > 1) {
				throw new Error(
					`oldText 在 ${params.path} 中出现了 ${occurrences} 次，无法唯一定位。` +
						`请扩大 oldText 的上下文范围直到只匹配一次。`,
				);
			}

			if (signal?.aborted) throw new Error("操作已取消");

			const updated = content.replace(params.oldText, params.newText);
			// 写文件前确保父目录存在：内置 write 会自动 mkdir，自定义工具要自己补上
			await mkdir(dirname(absolute), { recursive: true });
			await writeFile(absolute, updated, "utf-8");

			return {
				content: [{ type: "text", text: `已在 ${params.path} 中替换 1 处内容。` }],
				details: { path: params.path, bytesBefore: content.length, bytesAfter: updated.length },
			};
		},
	});
}

import { createAgentSession, SessionManager } from "@earendil-works/pi-coding-agent";

const workspaceRoot = process.cwd();

const { session } = await createAgentSession({
	cwd: workspaceRoot,
	// 用黑名单收敛内置工具；自定义工具不受黑名单影响
	excludeTools: ["bash", "write", "edit"],
	customTools: [
		createWorkspaceReadTool(workspaceRoot),
		createWorkspaceSearchTool(workspaceRoot),
		createWorkspaceEditTool(workspaceRoot),
	],
	sessionManager: SessionManager.inMemory(workspaceRoot),
});

try {
	// 先确认实际生效的工具集合：比读配置可靠
	console.log("生效工具：", session.getActiveToolNames());

	const unsubscribe = session.subscribe((event) => {
		if (event.type === "tool_execution_start") {
			console.log(`[tool] ${event.toolName}`, event.args);
		}
		// isError 为 true 说明工具抛了异常，模型收到的是失败结果
		if (event.type === "tool_execution_end" && event.isError) {
			console.log(`[tool error] ${event.toolName}`);
		}
	});

	await session.prompt("读取 package.json，找出 scripts 里的 test 命令");
	console.log(session.getLastAssistantText());
} finally {
	// 释放顺序：先退订，再 dispose
	unsubscribe?.();
	session.dispose();
}