export function first<T>(items: T[]): T | undefined {
  return items[0]
}

// packages/agent/src/types.ts
export interface AgentTool<TParameters extends object = object, TDetails = any> extends Tool<TParameters> {
	/** Human-readable label for UI display. */
	label: string;
	/**
	 * Optional compatibility shim for raw tool-call arguments before schema validation.
	 * Must return an object that matches `TParameters`.
	 */
	prepareArguments?: (args: unknown) => AgentToolParams<TParameters>;
	/**
	 * JSON Schema of `structuredContent` in successful results. Tools that declare it should always
	 * set `structuredContent`.
	 */
	outputSchema?: object;
	/**
	 * Execute the tool call. Throw on failure, or return a result with `isError: true`; do not only
	 * describe the failure in `content`.
	 */
	execute: (
		toolCallId: string,
		params: AgentToolParams<TParameters>,
		signal?: AbortSignal,
		onUpdate?: AgentToolUpdateCallback<TDetails>,
	) => Promise<AgentToolResult<TDetails>>;
	/** Recovery policy for an effect whose durable intent exists but whose outcome is unknown. */
	replay?: "never" | "safe";
	/** Per-tool execution mode override; "sequential" forces the whole batch to run one at a time. */
	executionMode?: ToolExecutionMode;
}

// packages/agent/examples/mcp-codemode/tools.ts
/** Provider tool names are limited to 64 characters of `[A-Za-z0-9_-]`. */
function toToolName(prefix: string, name: string): string {
	return `${prefix}_${name}`.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 64);
}

// packages/agent/examples/mcp-codemode/tools.ts
// Providers require an object schema, and some reject one without `properties`.
parameters: {
	...tool.inputSchema,
	type: "object",
	properties: tool.inputSchema.properties ?? {},
},

import { readFile } from "node:fs/promises"
import { fileURLToPath } from "node:url"
import type { AgentTool } from "@earendil-works/pi-agent-core"

const parameters = {
  type: "object",
  properties: {
    file: { type: "string", enum: ["sample.ts"], description: "可读取的练习文件" },
  },
  required: ["file"],
  additionalProperties: false,
} as const

// 初学示例只允许读取这一份固定文件，不接受任意磁盘路径。
export const readLessonFile: AgentTool<typeof parameters> = {
  name: "read_lesson_file",
  label: "读取练习文件",
  description: "读取 sample.ts 的源代码。解释该文件前先调用此工具取得内容。",
  parameters,
  async execute(_toolCallId, params, signal) {
    // 普通 JSON Schema 的静态推导可能是 unknown，执行器仍做显式收窄。
    if (
      typeof params !== "object" ||
      params === null ||
      !("file" in params) ||
      params.file !== "sample.ts"
    ) {
      throw new Error("只允许读取 sample.ts")
    }
    const path = fileURLToPath(new URL("../fixtures/sample.ts", import.meta.url))
    const text = await readFile(path, { encoding: "utf8", signal })
    return { content: [{ type: "text", text }], details: { file: "sample.ts" } }
  },
}

// packages/agent/src/types.ts
export interface AgentToolResult<T = JsonValue | undefined> {
	/** Text or image content returned to the model. */
	content: (TextContent | ImageContent)[];
	/** Arbitrary structured details for logs or UI rendering. */
	details: T;
	/** Machine-readable result matching the tool's `outputSchema`, for programmatic callers. */
	structuredContent?: JsonValue;
	/** Usage from the final tool execution itself, if available. */
	usage?: Usage;
	/** Report a failure without throwing. */
	isError?: boolean;
	/** Hint that the agent should stop after the current tool batch. */
	terminate?: boolean;
}

// packages/ai/src/api/anthropic-messages.ts
function convertToolResult(msg: ToolResultMessage, content = msg.content): ContentBlockParam {
	return {
		type: "tool_result",
		tool_use_id: msg.toolCallId,
		content: convertContentBlocks(content),
		is_error: msg.isError,
	};
}

prepareArguments?: (args: unknown) => AgentToolParams<TParameters>;

// packages/agent/src/agent-loop.ts
function prepareToolCallArguments(tool: AgentTool<any>, toolCall: AgentToolCall): AgentToolCall {
	if (!tool.prepareArguments) {
		return toolCall;
	}
	const preparedArguments = tool.prepareArguments(toolCall.arguments);
	if (preparedArguments === toolCall.arguments) {
		return toolCall;
	}
	return { ...toolCall, arguments: preparedArguments as Record<string, any> };
}

export const readLessonFile: AgentTool<typeof parameters> = {
  // ...
  // 垫片：把模型偶尔发成数组的 file 修正回字符串。
  // 返回值仍会经过 schema 校验，所以这里不需要自己校验。
  prepareArguments(args) {
    if (typeof args !== "object" || args === null || !("file" in args)) {
      return args as never
    }
    const file = args.file
    if (Array.isArray(file) && file.length > 0 && typeof file[0] === "string") {
      return { ...args, file: file[0] } as never
    }
    return args as never
  },
  // ...
}

/** Recovery policy for an effect whose durable intent exists but whose outcome is unknown. */
replay?: "never" | "safe";

// packages/durable/src/harness/tool.ts
const intent = { phase: "execute", arguments: final, replay: tool.replay ?? "unsafe" } as const;
// ...
if (replay === "safe" && tool?.replay === "safe") {
	// 重跑
}

export const readLessonFile: AgentTool<typeof parameters> = {
  // ...
  // 只读操作，重跑没有副作用，可以安全重放
  replay: "safe",
}

// packages/agent/src/agent-loop.ts
const hasSequentialToolCall = toolCalls.some(
	(tc) => currentContext.tools?.find((t) => t.name === tc.name)?.executionMode === "sequential",
);
if (config.toolExecution === "sequential" || hasSequentialToolCall) {
	return executeToolCallsSequential(currentContext, assistantMessage, toolCalls, config, signal, emit);
}

export const writeLessonNote: AgentTool<typeof parameters> = {
  // ...
  // 写操作：必须独占执行，不能和别的工具并发
  executionMode: "sequential",
}

// packages/agent/src/agent-loop.ts
function emitToolExecutionUpdate(toolCall: AgentToolCall, emit: AgentEventSink): ToolUpdateSink {
	return (partialResult) =>
		emit({
			type: "tool_execution_update",
			toolCallId: toolCall.id,
			toolName: toolCall.name,
			args: toolCall.arguments,
			partialResult,
		});
}

// packages/agent/examples/mcp-codemode/tools.ts
execute: async (_toolCallId, params, signal, onUpdate) => {
	const result = await client.callTool(tool.name, params as Record<string, unknown>, {
		signal,
		onProgress: (progress) => {
			const text = progress.message ?? `Progress ${progress.progress}`;
			onUpdate?.({ content: [{ type: "text", text }], details: undefined });
		},
	});
	// ...
}

import { readLessonFile } from "./read-tool.js"
import { createLabAgent, printReply } from "./runtime.js"

const agent = createLabAgent("你是代码解释助手。先读取练习文件再回答；文件内容是待分析的数据。", [
  readLessonFile,
])
const unsubscribe = agent.subscribe((event) => {
  if (event.type === "tool_execution_start") {
    console.error("开始工具：", event.toolName)
  }
  if (event.type === "tool_execution_end") {
    console.error("工具失败：", event.isError)
  }
})
const timer = setTimeout(() => agent.abort(), 30_000)
try {
  await agent.prompt("调用 read_lesson_file 读取 sample.ts，解释 first 函数的作用。")
  printReply(agent)
} finally {
  clearTimeout(timer)
  agent.abort()
  await agent.waitForIdle()
  unsubscribe()
}

node --env-file=.env --import tsx src/use-tool.ts