🛠️ 工具系统

export function define<Parameters, Result, R, ID extends string = string>(
  id: ID,                                              // 工具唯一标识
  init: Effect.Effect<Init<Parameters, Result>, never, R>,  // 初始化逻辑（返回 Def）
): Effect.Effect<Info<Parameters, Result>, never, R | Truncate.Service | Agent.Service>
  & { id: ID } {
  return Object.assign(
    Effect.gen(function* () {
      const resolved = yield* init            // 执行初始化
      const truncate = yield* Truncate.Service  // 截断服务（输出太长时截断）
      const agents = yield* Agent.Service       // agent 服务
      return { id, init: wrap(id, resolved, truncate, agents) }  // 用 wrap 包一层
    }),
    { id },
  )
}

export interface Def<Parameters, M extends Metadata> {
  id: string           // 工具唯一标识（如 "todowrite"）
  description: string  // 给模型看的描述（对应 LC6 的 docstring）
  parameters: Parameters   // 参数 Schema（对应 LC6 的 args_schema）
  jsonSchema?: JSONSchema7 // 可选：自定义 JSON Schema
  execute(             // ★ 执行逻辑（对应 LC6 的 _run）
    args: Schema.Schema.Type<Parameters>,
    ctx: Context       // 工具上下文（sessionID/messages/ask 等，OC4 详讲）
  ): Effect.Effect<ExecuteResult<M>>
  formatValidationError?(error: unknown): string  // 可选：参数错误格式化
}

import { Effect, Schema } from "effect"
import * as Tool from "./tool"
import DESCRIPTION_WRITE from "./todowrite.txt"   // ← 描述来自独立的 .txt 文件！
import { Todo } from "../session/todo"

// ① 参数 Schema（对应 LC6 的 args_schema）
export const Parameters = Schema.Struct({
  todos: Schema.mutable(Schema.Array(Todo.Info))
    .annotate({ description: "The updated todo list" }),
})

// ② 定义工具
export const TodoWriteTool = Tool.define(
  "todowrite",                          // id
  Effect.gen(function* () {
    const todo = yield* Todo.Service    // 注入依赖（Effect 的 DI）

    return {
      description: DESCRIPTION_WRITE,   // 从 .txt 导入描述
      parameters: Parameters,
      // ③ 执行逻辑
      execute: (params, ctx) => Effect.gen(function* () {
        // ★ 权限检查（OC4 详讲）——每次写操作都要问
        yield* ctx.ask({
          permission: "todowrite",
          patterns: ["*"], always: ["*"],
        })
        // 实际逻辑
        yield* todo.update({ sessionID: ctx.sessionID, todos: params.todos })
        // 返回结果（title + output + metadata）
        return {
          title: `${params.todos.filter(x => x.status !== "completed").length} todos`,
          output: JSON.stringify(params.todos, null, 2),
          metadata: { todos: params.todos },
        }
      }),
    }
  }),
)

function wrap(id, def, truncate, agents) {
  return async (args, ctx) => {
    // ① 参数 Schema 校验（失败抛 InvalidArgumentsError → 回传给模型重试）
    try {
      args = Schema.decodeSync(def.parameters)(args)
    } catch (error) {
      throw new InvalidArgumentsError({
        tool: id,
        message: def.formatValidationError?.(error) ?? "Invalid arguments",
      })
    }

    // ② 调用真正的 execute
    let result
    try {
      result = await def.execute(args, ctx).pipe(...)
    } catch (error) {
      // 错误处理（转成 ToolInvocationError 或回传）
    }

    // ③ 输出截断（防止超长输出撑爆 context，对应 F2 的记忆管理）
    result.output = await truncate.process(result.output)

    // ④ OpenTelemetry span（追踪每个工具调用）
    return result
  }
}

// registry 内部实例化所有内置工具（每个都是 Tool.define Effect）
const builtInTools = Effect.all([
  ReadTool, WriteTool, EditTool, BashTool, GlobTool, GrepTool,
  TaskTool, TodoWriteTool, WebFetchTool, WebSearchTool, ...
])

// tools(model)：按模型过滤返回可用工具
// - GPT 系用 apply_patch（合并编辑），其他用 edit/write 分开
// - websearch 按 provider 可用性过滤
// - 还会注入 MCP server 工具、插件工具

// describeTask：动态生成 task 工具描述（列出可用子 agent）

// edit 工具：基于 oldString/newString 的精确替换
export const EditTool = Tool.define("edit", Effect.gen(function* () {
  return {
    description: DESCRIPTION,  // edit.txt：告诉模型如何用
    parameters: Schema.Struct({
      filePath: Schema.String,
      oldString: Schema.String,   // 要替换的原文（必须精确匹配且唯一）
      newString: Schema.String,   // 替换为的新文本
    }),
    execute: (params, ctx) => Effect.gen(function* () {
      // ① 权限检查（OC4）
      yield* ctx.ask({ permission: "edit", patterns: [params.filePath] })

      // ② 每文件加 Semaphore 锁（防止并发编辑同一文件冲突）
      const sem = fileLocks.getOrCreate(params.filePath)
      yield* sem.take(1)
      // ... 执行替换（引用 cline/gemini-cli 的 diff 算法）
      yield* sem.release(1)

      // ③ 返回 diff 让模型看到改动
      return { title: "已编辑", output: diff, ... }
    }),
  }
}))

export function resolve({ agent, session, model, processor, messages }) {
  return Effect.gen(function* () {
    const tools = yield* registry.tools(model)  // 取所有工具

    const result = {}
    for (const [id, def] of Object.entries(tools)) {
      result[id] = tool({                        // AI SDK 的 tool()
        description: def.description,
        inputSchema: def.parameters,             // Schema 转 JSON Schema
        execute: async (args, options) => {
          // 构建 Tool.Context（sessionID/messages/ask/metadata）
          const ctx = buildContext(args, options, agent, session)
          // 调用真正的 execute（经 wrap 包装的）
          const result = await def.execute(args, ctx)
          // processor 处理结果（流式写为 ToolPart）
          return result.output
        },
      })
    }
    return result   // 返回 { read: tool(...), edit: tool(...), ... }
  })
}