// schemas.ts
import { Type } from "typebox";

// 参数 schema 同时给模型和运行时看：模型据此填参数，运行时据此校验和转换
export const listFilesParameters = Type.Object({
	dir: Type.String({
		description: "要列出的目录，相对会话工作目录。空字符串表示工作目录本身。",
	}),
	// Optional 在 schema 层就告诉模型这个参数可以不传
	maxEntries: Type.Optional(
		Type.Number({
			description: "最多返回多少条，默认 200。",
			minimum: 1,
			maximum: 1000,
		}),
	),
});

// execute 的四个参数都由运行时注入：params 已经过 schema 校验，不是模型原始发来的 JSON
const execute = async (
	toolCallId: string,
	params: { dir: string },
	signal: AbortSignal | undefined,
	onUpdate: ((partial: { content: { type: "text"; text: string }[]; details: unknown }) => void) | undefined,
) => {
	// 用 signal 判断是否被取消，用 onUpdate 报进度
	// 返回 { content, details }
	return { content: [{ type: "text", text: "..." }], details: {} };
};

// content 给模型读，details 给程序用：两者不要互相串味
return {
	content: [{ type: "text", text: "src/index.ts\nsrc/util.ts\nREADME.md" }],
	details: { dir: "src", count: 3, truncated: false },
};

// 反例：错误被伪装成成功输出
const listFilesParams = Type.Object({ dir: Type.String() });

const badTool: AgentTool<typeof listFilesParams> = {
	name: "list_files",
	label: "List Files",
	description: "列出目录下的文件",
	parameters: listFilesParams,
	execute: async (toolCallId, params) => {
		// 错在这里：把失败写进 content 返回，模型会当成一次成功调用
		if (!existsSync(params.dir)) {
			return {
				content: [{ type: "text", text: `目录不存在：${params.dir}` }],
				details: { ok: false },
			};
		}
		// 成功路径也没有任何错误标记：整个返回值里找不到「这次调用失败了」的信号
		return { content: [], details: {} };
	},
};

// onUpdate 报的是中间进度，参数形状和最终返回值同构，但只活到 promise 落地为止
onUpdate?.({
	content: [{ type: "text", text: "正在扫描 src/ ……" }],
	details: { phase: "scan", dir: "src" },
});

// 单个工具覆盖全局执行模式：标了它，这一批工具调用整批串行
executionMode: "sequential",

# 一个工具调用从产生到落地的四道关卡，箭头方向就是实际执行顺序
tool_execution_start
  → prepareArguments（可选的参数预处理）
  → 参数 schema 校验与转换
  → beforeToolCall 钩子
  → execute
  → afterToolCall 钩子
  → tool_execution_end

const agent = new Agent({
	initialState: { systemPrompt: "你是一个文件助手。", model },
	streamFn: models.streamSimple.bind(models),
	// beforeToolCall 在参数校验之后、执行之前跑：这里挡住调用，execute 一次都不会跑
	beforeToolCall: async ({ toolCall, args }) => {
		if (toolCall.name === "list_files") {
			const dir = String((args as { dir?: string })?.dir ?? "");
			// 越出工作目录的路径一律拒绝
			if (dir.includes("..") || dir.startsWith("/")) {
				return {
					block: true,
					// reason 会成为给模型看的错误文本，要给出可照做的修正方向
					reason: "只能列出工作目录内的相对路径，请去掉 .. 和开头的 /",
				};
			}
		}
		// 返回 undefined 表示放行
		return undefined;
	},
});

// tools/list-files.ts
import { readdir } from "node:fs/promises";
import { join, relative, resolve, sep } from "node:path";
import { Type, type Static } from "typebox";
import type { AgentTool } from "@earendil-works/pi-agent-core";

const parameters = Type.Object({
	dir: Type.String({ description: "要列出的目录，相对工作目录。空字符串表示工作目录本身。" }),
	maxEntries: Type.Optional(
		Type.Number({ description: "最多返回多少条，默认 200。", minimum: 1, maximum: 1000 }),
	),
});

type Params = Static<typeof parameters>;

export function createListFilesTool(cwd: string): AgentTool<typeof parameters> {
	const base = resolve(cwd);
	return {
		name: "list_files",
		label: "List Files",
		description:
			"列出指定目录下的文件条目，返回相对路径。只读，不修改任何文件。" +
			"当用户问某个目录里有哪些文件时使用。",
		parameters,
		executionMode: "sequential",
		execute: async (toolCallId, params: Params, signal, onUpdate) => {
			const maxEntries = params.maxEntries ?? 200;
			const target = resolve(base, params.dir || ".");

			// resolve() 只做规范化，不做限制：../ 依然能逃出工作目录，必须自己检查
			if (target !== base && !target.startsWith(base + sep)) {
				throw new Error(`路径越出工作目录：${params.dir}`);
			}

			onUpdate?.({
				content: [{ type: "text", text: `正在列出 ${params.dir || "."} …` }],
				details: { phase: "scan", dir: params.dir },
			});

			let entries;
			try {
				entries = await readdir(target, { withFileTypes: true });
			} catch (error) {
				// 失败必须抛出：模型会收到 isError 的工具结果，可以据此调整
				throw new Error(`无法列出目录 ${params.dir || "."}：${(error as Error).message}`);
			}

			const lines: string[] = [];
			for (const entry of entries) {
				if (signal?.aborted) throw new Error("已取消");
				if (lines.length >= maxEntries) break;
				const relativePath = relative(base, join(target, entry.name));
				lines.push(entry.isDirectory() ? `${relativePath}/` : relativePath);
			}

			const truncated = entries.length > lines.length;

			return {
				content: [{ type: "text", text: lines.join("\n") || "(空目录)" }],
				details: { dir: params.dir, count: lines.length, truncated },
			};
		},
	};
}

// run.ts
import { createAgentSession, SessionManager } from "@earendil-works/pi-coding-agent";
import { createListFilesTool } from "./tools/list-files.js";

const { session } = await createAgentSession({
	cwd: process.cwd(),
	// customTools 是追加，不是替换：内置工具照样在
	customTools: [createListFilesTool(process.cwd())],
	// 用内存会话：练习不写磁盘文件
	sessionManager: SessionManager.inMemory(),
});

try {
	await session.prompt("这个项目里 src 目录下有哪些文件？");
	console.log(session.getLastAssistantText());
} finally {
	// 必须释放：否则扩展的清理处理器不会运行
	session.dispose();
}