助手消息里的 toolCall.id
        │
        ├─→ tool_execution_start.toolCallId
        ├─→ tool_execution_end.toolCallId
        └─→ toolResult 消息的 toolCallId

// 失败必须抛异常：返回错误文本会被当成一次成功调用
execute: async (toolCallId, params, signal, onUpdate) => {
  if (!fs.existsSync(params.path)) {
    throw new Error(`File not found: ${params.path}`);
  }
  return { content: [{ type: "text", text: "..." }] };
}

Validation failed for tool "read":
  - path: must be string

Received arguments:
{
  "path": 42
}

// 差：模型只知道失败了，得自己再探一次
throw new Error("File not found");

// 好：模型知道哪个文件错了、目录下有什么、下一步该做什么
// 原则是把「事实 + 下一步」一起放进错误消息，纠错轮次会明显下降
throw new Error(
  `文件不存在：${params.path}。` +
    `同目录下相近的文件：${siblings.join("、") || "（无）"}。` +
    `请先用 ws_ls 列出目录内容，确认准确路径后重试。`
);

import { describe, expect, it } from "vitest";
import { runToolCall } from "@earendil-works/pi-agent-core";
import { Type } from "typebox";
import type { AgentTool, AgentToolCall } from "@earendil-works/pi-agent-core";

/** 一个最小助手消息：夹具只需要它提供调用来源。 */
const assistantMessage = {
	role: "assistant" as const,
	content: [],
	api: "openai-responses" as const,
	provider: "openai" as const,
	model: "mock",
	usage: {
		input: 0, output: 0, cacheRead: 0, cacheWrite: 0,
		totalTokens: 0,
		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
	},
	stopReason: "toolUse" as const,
	timestamp: Date.now(),
};

/** 构造一个工具调用块。id 就是回填时的锚点。 */
function call(id: string, name: string, args: Record<string, unknown>): AgentToolCall {
	return { type: "toolCall", id, name, arguments: args };
}

const readSchema = Type.Object({ path: Type.String() });

/** 夹具一：参数校验失败。path 传了对象，schema 要求字符串。 */
const schemaViolation: AgentTool = {
	name: "read",
	label: "read",
	description: "读取文件",
	parameters: readSchema,
	async execute() {
		throw new Error("不应该走到这里：参数校验就该挡住了");
	},
};

/** 夹具二：执行期抛错。 */
const throwing: AgentTool = {
	name: "read",
	label: "read",
	description: "读取文件",
	parameters: readSchema,
	async execute() {
		throw new Error("ENOENT: no such file or directory, access '/repo/missing.ts'");
	},
};

/** 夹具三：取消。signal 已 aborted 时工具应当立即失败。 */
const cancellable: AgentTool = {
	name: "read",
	label: "read",
	description: "读取文件",
	parameters: readSchema,
	async execute(_toolCallId, _params, signal) {
		if (signal?.aborted) throw new Error("Operation aborted");
		return { content: [{ type: "text", text: "不该执行到这" }], details: {} };
	},
};

const options = (tools: AgentTool[]) => ({
	tools,
	assistantMessage,
	context: { messages: [] },
});

describe("工具失败夹具", () => {
	it("参数校验失败：不进 execute，回填 isError 且带 toolCallId", async () => {
		const outcome = await runToolCall(call("call-schema", "read", { path: { bad: 1 } }), options([schemaViolation]));

		expect(outcome.toolCall.id).toBe("call-schema");
		expect(outcome.isError).toBe(true);
		// 校验失败发生在 prepare 阶段，工具体从未执行，因此没有耗时
		expect(outcome.durationMs).toBeUndefined();
		// 错误文本必须点名工具与字段，并回显模型实际传了什么
		const text = outcome.result.content.map((c) => (c.type === "text" ? c.text : "")).join("");
		expect(text).toContain('Validation failed for tool "read"');
		expect(text).toContain("Received arguments");
	});

	it("执行期抛错：错误文本原样回填，耗时存在", async () => {
		const outcome = await runToolCall(call("call-throw", "read", { path: "/repo/missing.ts" }), options([throwing]));

		expect(outcome.toolCall.id).toBe("call-throw");
		expect(outcome.isError).toBe(true);
		expect(outcome.durationMs).toBeGreaterThanOrEqual(0);
		const text = outcome.result.content.map((c) => (c.type === "text" ? c.text : "")).join("");
		expect(text).toContain("ENOENT");
	});

	it("取消：signal aborted 时工具失败而不是成功", async () => {
		const controller = new AbortController();
		controller.abort();

		const outcome = await runToolCall(call("call-abort", "read", { path: "/repo/a.ts" }), {
			...options([cancellable]),
			signal: controller.signal,
		});

		expect(outcome.toolCall.id).toBe("call-abort");
		expect(outcome.isError).toBe(true);
		const text = outcome.result.content.map((c) => (c.type === "text" ? c.text : "")).join("");
		expect(text).toContain("Operation aborted");
	});

	it("未知工具：回填 Tool <name> not found，不抛异常", async () => {
		const outcome = await runToolCall(call("call-unknown", "search", { query: "x" }), options([schemaViolation]));

		expect(outcome.isError).toBe(true);
		const text = outcome.result.content.map((c) => (c.type === "text" ? c.text : "")).join("");
		expect(text).toBe("Tool search not found");
	});
});

import { describe, expect, it } from "vitest";
import { agentLoop } from "@earendil-works/pi-agent-core";
import { createAssistantMessageEventStream } from "@earendil-works/pi-ai";
import { Type } from "typebox";
import type { AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, AgentTool } from "@earendil-works/pi-agent-core";

const failingTool: AgentTool = {
	name: "read",
	label: "read",
	description: "读取文件",
	parameters: Type.Object({ path: Type.String() }),
	async execute() {
		throw new Error("boom");
	},
};

describe("失败的事件序列", () => {
	it("失败也走完整的 tool_execution_start / end / toolResult 三段", async () => {
		const context: AgentContext = { messages: [], tools: [failingTool] };

		const config: AgentLoopConfig = {
			model: {
				id: "mock", name: "mock", api: "openai-responses", provider: "openai",
				baseUrl: "https://example.invalid", reasoning: false, input: ["text"],
				cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
				contextWindow: 8192, maxTokens: 2048,
			},
			convertToLlm: (messages) => messages as never,
		};

		const userMessage: AgentMessage = {
			role: "user", content: "读一下", timestamp: Date.now(),
		};

		let callIndex = 0;
		const stream = agentLoop([userMessage], context, config, undefined, () => {
			const mock = createAssistantMessageEventStream();
			queueMicrotask(() => {
				if (callIndex === 0) {
					mock.push({
						type: "done",
						reason: "toolUse",
						message: {
							role: "assistant",
							content: [{ type: "toolCall", id: "call-1", name: "read", arguments: { path: "a.ts" } }],
							api: "openai-responses", provider: "openai", model: "mock",
							usage: {
								input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0,
								cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
							},
							stopReason: "toolUse",
							timestamp: Date.now(),
						},
					});
				} else {
					mock.push({
						type: "done",
						reason: "stop",
						message: {
							role: "assistant", content: [{ type: "text", text: "done" }],
							api: "openai-responses", provider: "openai", model: "mock",
							usage: {
								input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0,
								cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
							},
							stopReason: "stop",
							timestamp: Date.now(),
						},
					});
				}
				callIndex++;
			});
			return mock;
		});

		const events: AgentEvent[] = [];
		for await (const event of stream) {
			events.push(event);
		}

		// 1) 起始事件一定发出
		const start = events.find((e) => e.type === "tool_execution_start");
		expect(start).toBeDefined();

		// 2) 失败同样有终态事件，且标记为错误
		const end = events.find((e) => e.type === "tool_execution_end");
		expect(end).toBeDefined();
		expect(end).toMatchObject({ toolCallId: "call-1", isError: true });

		// 3) 失败结果作为 toolResult 消息回填，且带着同一个 toolCallId
		const resultMessage = events.find(
			(e) => e.type === "message_end" && e.message.role === "toolResult",
		);
		expect(resultMessage).toMatchObject({
			message: { toolCallId: "call-1", toolName: "read", isError: true },
		});

		// 4) 本轮结束时会带上这个失败结果
		const turnEnd = events.find((e) => e.type === "turn_end");
		expect(turnEnd).toBeDefined();
	});
});

// 整批一致：批里每一个最终结果都必须带 terminate: true，有一个不带就整批不终止
function shouldTerminateToolBatch(finalizedCalls) {
	return finalizedCalls.length > 0 && finalizedCalls.every((f) => f.result.terminate === true);
}

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

const { session } = await createAgentSession({
	sessionManager: SessionManager.inMemory(),
	customTools: [
		defineTool({
			name: "always_fails",
			label: "always_fails",
			description: "必定失败的探针工具，用来验证失败回填",
			parameters: Type.Object({ reason: Type.String() }),
			async execute() {
				// 抛错 = 失败。这条错误会作为工具结果回到模型。
				throw new Error("探针失败：这是预期的错误");
			},
		}),
	],
});

try {
	const events: string[] = [];

	const unsubscribe = session.subscribe((event) => {
		if (event.type === "tool_execution_start") {
			events.push(`start:${event.toolName}`);
		}
		if (event.type === "tool_execution_end") {
			// isError 和 durationMs 是判断失败形态的关键字段
			events.push(`end:${event.toolName}:isError=${event.isError}:hasDuration=${event.durationMs !== undefined}`);
		}
	});

	await session.prompt("调用 always_fails 看看会发生什么");

	console.log(events);
	// 预期能看到 start -> end(isError=true) 两段，
	// 而且 hasDuration=true（因为 execute 真的跑过了）

	console.log("模型看到的最后回复:", session.getLastAssistantText());
} finally {
	// 释放：dispose 会中止在跑的工作并清空监听器
	session.dispose();
}