模型输出 tool_call
-> 参数校验
-> 工具存在性检查
-> 权限判断
-> 风险评估
-> 执行
-> 输出截断
-> 审计记录
-> 回填给模型

// ToolRisk = 工具风险等级。
// 风险等级决定是否需要审批、审计强度、默认是否允许。
export type ToolRisk = "read" | "write" | "execute" | "network";

// Tool = 一个可被模型调用的工具定义。
// Input/Output 是泛型，表示这个工具自己的入参和返回类型。
export type Tool<Input, Output> = {
  name: string;              // 工具名，暴露给模型，例如 read_file。
  description: string;       // 工具说明，影响模型什么时候调用它。
  inputSchema: JsonSchema;   // 参数 schema，运行前必须校验。
  risk: ToolRisk;            // 风险等级：读、写、执行命令、网络。
  timeoutMs: number;         // 最大执行时间，防止工具卡死。
  maxOutputBytes: number;    // 最大返回内容大小，防止撑爆上下文。
  run(input: Input, ctx: ToolContext): Promise<Output>; // 真正的工具实现。
};

// ToolContext = 工具执行时的受控上下文。
// 不要直接给工具全局 process/env，应该只给它需要的最小信息。
export type ToolContext = {
  cwd: string;                              // 当前工作区根目录。
  sessionId: string;                        // 用于 audit/trace。
  env: Record<string, string | undefined>;  // 受控环境变量。
};

// registry = 工具注册表。
// key 是工具名，value 是工具定义。
const registry = new Map<string, Tool<any, any>>();

// frozen 表示注册表是否已冻结。
// 启动完成后冻结，避免运行中被插件或代码动态篡改。
let frozen = false;

// registerTool = 注册工具。
export function registerTool(tool: Tool<any, any>) {
  // 冻结后不允许再注册，保证模型看到的工具列表和实际执行列表一致。
  if (frozen) {
    throw new Error("Tool registry is frozen.");
  }

  // 工具名必须是稳定、安全、可序列化的名字。
  if (!/^[a-zA-Z0-9_:-]+$/.test(tool.name)) {
    throw new Error(`Invalid tool name: ${tool.name}`);
  }

  // 禁止重名。重名会导致模型以为调用 A，实际执行 B。
  if (registry.has(tool.name)) {
    throw new Error(`Duplicate tool: ${tool.name}`);
  }

  registry.set(tool.name, tool);
}

// freezeTools = 启动阶段结束后冻结工具注册表。
export function freezeTools() {
  frozen = true;
}

{
  "path": "../../secret.txt"
}

{
  "path": 123
}

// validateToolInput = 工具参数校验。
// 模型输出的 input 不可信，必须先过 schema。
export function validateToolInput(tool: Tool<any, any>, input: unknown) {
  // validateJson 只检查 JSON 形状是否符合 inputSchema。
  const schemaResult = validateJson(input, tool.inputSchema);
  if (!schemaResult.ok) {
    // 参数不合法时抛结构化错误，后续可让模型重试。
    throw new AgentError("TOOL_INPUT_INVALID", schemaResult.message, {
      tool: tool.name,
      input
    });
  }

  // schema 通过后返回 input。真实系统可在这里做类型收窄。
  return input;
}

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

// resolveWorkspacePath = 文件工具的路径安全闸门。
// 目标：把用户路径解析成绝对路径，同时禁止逃出 workspace。
export function resolveWorkspacePath(cwd: string, userPath: string) {
  // 空路径和 NUL 字符都拒绝。NUL 可能导致底层文件 API 行为异常。
  if (!userPath || userPath.includes("\0")) {
    throw new AgentError("TOOL_INPUT_INVALID", "Invalid path.");
  }

  // 如果用户给绝对路径，就规范化；否则相对 cwd 解析。
  const abs = isAbsolute(userPath)
    ? resolve(userPath)
    : resolve(cwd, userPath);

  // 计算 abs 相对于 cwd 的相对路径。
  const rel = relative(cwd, abs);

  // rel 以 .. 开头或仍是绝对路径，说明 abs 不在 workspace 内。
  if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) {
    throw new AgentError("TOOL_PERMISSION_DENIED", "Path escapes workspace.", {
      cwd,
      userPath,
      abs
    });
  }

  // 返回安全的绝对路径。
  return abs;
}

// PermissionDecision = 权限判断结果。
// 不是 boolean，因为我们还要知道允许/拒绝的原因，方便 audit。
type PermissionDecision =
  | {
      type: "allow";
      // source 表示为什么允许：只读策略、用户批准、可信工具等。
      source: "readonly_policy" | "user_approved" | "trusted_tool";
    }
  | {
      type: "deny";
      // 拒绝原因要写清楚，最终要能反馈给用户和 trace。
      reason: string;
    }
  | {
      type: "ask";
      // ask 表示需要用户确认，prompt 是展示给用户看的批准文案。
      prompt: string;
    };

// checkPermission = 根据工具风险和输入决定是否允许执行。
export async function checkPermission(
  tool: Tool<any, any>,
  input: unknown,
  ctx: ToolContext
): Promise<PermissionDecision> {
  // 只读工具默认允许，但工具内部仍要拦敏感路径。
  if (tool.risk === "read") {
    return { type: "allow", source: "readonly_policy" };
  }

  // 某些工具/输入可以被策略信任，例如固定安全命令。
  if (isTrustedTool(tool.name, input)) {
    return { type: "allow", source: "trusted_tool" };
  }

  // 执行命令风险高，默认询问用户。
  if (tool.risk === "execute") {
    return {
      type: "ask",
      prompt: `Allow command execution by ${tool.name}?`
    };
  }

  // 写文件也默认询问用户，最好展示 diff。
  if (tool.risk === "write") {
    return {
      type: "ask",
      prompt: `Allow file modification by ${tool.name}?`
    };
  }

  // 没处理到的风险类型默认拒绝，安全上 fail closed。
  return {
    type: "deny",
    reason: `Unhandled risk type: ${tool.risk}`
  };
}

// WritePreview = 写文件前的预览对象。
// 权限提示应该展示这个对象里的 diff，而不是只说“我要写文件”。
type WritePreview = {
  path: string;       // 目标文件路径。
  oldContent: string; // 写入前内容。新建文件时为空。
  newContent: string; // 计划写入的新内容。
  diff: string;       // old/new 生成的统一 diff。
};

// previewWrite = 生成写入前 diff。
export async function previewWrite(path: string, newContent: string): Promise<WritePreview> {
  // 文件不存在时按新建处理。
  const oldContent = await readFile(path, "utf8").catch(() => "");

  return {
    path,
    oldContent,
    newContent,
    diff: createUnifiedDiff(oldContent, newContent)
  };
}

// BashInput = 结构化命令输入。
// command 和 args 分开，避免模型拼出一整条危险 shell 字符串。
type BashInput = {
  command: string;    // 命令名，例如 git、npm、node。
  args: string[];     // 参数数组，例如 ["test", "--", "auth"]。
  timeoutMs?: number; // 可选超时，但程序会再设上限。
};

type BadBashInput = {
  command: string; // 坏例子：整条 shell 字符串，可能包含 "rm -rf . && curl ..."
};

// runAllowedCommand = 执行白名单命令。
// 入门版只允许固定命令集合，真实系统还要按风险和用户批准细分。
export async function runAllowedCommand(input: BashInput, ctx: ToolContext) {
  // 白名单比黑名单安全，因为危险命令变体太多。
  const allowed = new Set(["git", "npm", "node", "python"]);

  // 不在白名单就拒绝。
  if (!allowed.has(input.command)) {
    throw new AgentError("TOOL_PERMISSION_DENIED", `Command not allowed: ${input.command}`);
  }

  // execFile 不走 shell 展开，command/args 分离，注入风险更低。
  return execFileWithLimit(input.command, input.args, {
    cwd: ctx.cwd,                                      // 限制在当前工作区执行。
    timeoutMs: Math.min(input.timeoutMs ?? 10_000, 30_000), // 用户传的超时不能超过上限。
    maxOutputBytes: 512_000                            // 输出最多 512KB。
  });
}

// truncateOutput = 截断工具输出。
// 目的：避免命令输出、grep 结果、日志把模型上下文撑爆。
export function truncateOutput(text: string, maxBytes: number) {
  // 按 UTF-8 字节数算，不按字符串长度算，因为 token/传输更接近字节成本。
  const bytes = Buffer.byteLength(text, "utf8");
  if (bytes <= maxBytes) {
    return { text, truncated: false };
  }

  // 截取前 maxBytes 个字节，再转回字符串。
  // 真实系统要注意不要截断在多字节字符中间。
  const sliced = Buffer.from(text, "utf8").subarray(0, maxBytes).toString("utf8");

  return {
    // 明确告诉模型输出被截断，不能让模型误以为这是完整输出。
    text: `${sliced}\n\n[Output truncated: ${bytes} bytes total]`,
    truncated: true
  };
}

// ToolAuditRecord = 工具调用审计记录。
// 它回答：模型请求了什么工具、传了什么参数、权限怎么判、结果如何。
type ToolAuditRecord = {
  sessionId: string;              // 会话 ID。
  callId: string;                 // 工具调用 ID。
  toolName: string;               // 工具名。
  risk: ToolRisk;                 // 风险等级。
  input: unknown;                 // 实际执行输入，敏感字段应脱敏。
  decision: PermissionDecision;   // 权限决策。
  startedAt: string;              // 开始时间。
  endedAt: string;                // 结束时间。
  durationMs: number;             // 耗时。
  ok: boolean;                    // 是否成功。
  outputSummary?: string;         // 成功时输出摘要。
  outputBytes?: number;           // 成功时输出大小。
  errorCode?: string;             // 失败错误码。
  errorMessage?: string;          // 失败错误信息。
};

// appendToolAudit = 追加一条工具审计记录。
// JSONL 一行一个记录，适合不断追加和后续 grep/分析。
export async function appendToolAudit(record: ToolAuditRecord) {
  await appendFile(
    ".agent/tool-audit.jsonl",
    JSON.stringify(record) + "\n"
  );
}

// executeToolCall = 工具执行总入口。
// 所有工具调用都必须经过这里：查工具 -> 校验参数 -> 权限 -> 执行 -> 截断 -> 审计。
export async function executeToolCall(call: ToolCall): Promise<ToolResult> {
  // 记录开始时间，用于审计 durationMs。
  const startedAt = Date.now();

  // 从注册表查找工具定义。
  const tool = registry.get(call.name);

  if (!tool) {
    // 工具不存在，抛结构化错误。上层可把可用工具列表回填给模型。
    throw new AgentError("TOOL_NOT_FOUND", `Unknown tool: ${call.name}`);
  }

  // 参数 schema 校验。模型生成的 input 不可信。
  const input = validateToolInput(tool, call.input);

  // 创建工具上下文，例如 cwd、sessionId、受控 env。
  const ctx = createToolContext(call.sessionId);

  // 权限判断：可能 allow、deny、ask。
  const decision = await checkPermission(tool, input, ctx);

  if (decision.type === "deny") {
    // 策略拒绝，直接失败。
    throw new AgentError("TOOL_PERMISSION_DENIED", decision.reason);
  }

  if (decision.type === "ask") {
    // 需要用户批准。真实 CLI 会弹确认或终端询问。
    const approved = await askUser(decision.prompt);
    if (!approved) {
      throw new AgentError("TOOL_PERMISSION_DENIED", "User denied tool call.");
    }
  }

  try {
    // withTimeout 包住工具执行，防止工具无限挂起。
    const raw = await withTimeout(
      tool.run(input, ctx),
      tool.timeoutMs
    );

    // 统一工具输出形状，并按 maxOutputBytes 截断。
    const normalized = normalizeToolOutput(raw, tool.maxOutputBytes);

    // 成功也要写审计。
    await appendToolAudit({
      sessionId: call.sessionId,
      callId: call.id,
      toolName: tool.name,
      risk: tool.risk,
      input,
      decision,
      startedAt: new Date(startedAt).toISOString(),
      endedAt: new Date().toISOString(),
      durationMs: Date.now() - startedAt,
      ok: true,
      outputSummary: normalized.summary,
      outputBytes: Buffer.byteLength(normalized.content, "utf8")
    });

    // 返回给 QueryEngine，随后会作为 tool message 回填给模型。
    return normalized;
  } catch (error) {
    // 工具内部抛的任何错误，都归一化成 AgentError。
    const agentError = normalizeToolError(error);

    // 失败也要写审计。没有失败审计，最关键的排查信息就丢了。
    await appendToolAudit({
      sessionId: call.sessionId,
      callId: call.id,
      toolName: tool.name,
      risk: tool.risk,
      input,
      decision,
      startedAt: new Date(startedAt).toISOString(),
      endedAt: new Date().toISOString(),
      durationMs: Date.now() - startedAt,
      ok: false,
      errorCode: agentError.code,
      errorMessage: agentError.message
    });

    // 继续抛给 QueryEngine，由状态机决定是否 recover。
    throw agentError;
  }
}

// ToolRiskProfile = 工具上线前的风险画像。
// 它回答：这个工具能碰什么资源、会不会产生副作用、什么时候必须问用户。
type ToolRiskProfile = {
  toolName: string;                  // 稳定工具名，必须能和 audit/tool call 对上。
  capability: "read" | "write" | "network" | "execute"; // 工具能力类别，用于默认策略。
  sideEffect: "none" | "idempotent" | "destructive";    // 是否会改变外部状态。
  schemaVersion: string;             // 参数契约版本，防止 client/server 漂移。

  workspaceBoundary?: {
    mode: "allowlist";               // 生产环境优先白名单，不靠黑名单猜危险路径。
    roots: string[];                 // 允许访问的根目录。
    denyGlobs: string[];             // 即使在根目录内也禁止访问的路径模式。
  };

  approval: {
    requiredWhen: string[];           // 触发人工批准的条件，例如 write/delete/execute。
    promptFields: string[];           // 批准界面必须展示哪些字段，例如 diff、target、reason。
  };

  limits: {
    timeoutMs: number;                // 单次工具最大执行时间。
    maxInputBytes: number;            // 防止模型塞入超大参数。
    maxOutputBytes: number;           // 防止工具输出挤爆上下文。
    maxAffectedFiles?: number;        // 文件类工具的影响半径。
  };

  auditFields: string[];              // 必须落盘的审计字段，不能靠日志文本临时 grep。
};