tools

type CapabilityProvider interface {
	Capability() ToolCapability
}

type DeferredRegistry struct {
	// contains filtered or unexported fields
}

type DryRunResult struct {
	// WouldAffect is a human-readable description of what will be
	// affected (e.g. file path, table name, endpoint URL). Consumed by
	// preview UI to show "this will touch X" before approval.
	//
	// WouldAffect 是会影响什么的人类可读描述 (如文件路径 / 表名 /
	// endpoint URL). 预览 UI 消费用于批准前展示 "即将影响 X".
	WouldAffect string

	// Preview is the detailed preview payload (e.g. unified diff, change
	// summary, SQL plan). Shown to the human operator / presented to the
	// LLM in an approval loop.
	//
	// Preview 是详细预览载荷 (如 unified diff / 变更摘要 / SQL plan).
	// 展示给人类操作员 / 在审批循环中展示给 LLM.
	Preview string

	// EstimatedImpact is a structured extension slot (map[string]any) for
	// consumer-specific impact metrics -- row counts, byte deltas,
	// estimated cost, etc. Schema is consumer-defined; engine does not
	// interpret it. Similar extension shape as ShadowResult.Meta and
	// ReplayEvent.Meta.
	//
	// EstimatedImpact 是结构化扩展槽 (map[string]any), 给消费端特定的
	// 影响指标 -- 行数 / byte 增量 / 预估成本等. schema 由消费端定义,
	// 引擎不解读. 扩展形状同 ShadowResult.Meta / ReplayEvent.Meta.
	EstimatedImpact map[string]any
}

type DryRunnable interface {
	// DryRun 模拟执行,返回"会发生什么"但不真正执行
	DryRun(ctx context.Context, input json.RawMessage) (*DryRunResult, error)
}

type MessageIDAware interface {
	// SetMessageID sets the current turn id used to key per-turn side
	// effects. Called by the engine at the start of every turn.
	//
	// LEGACY / fallback only: storing the turn id on a SHARED tool instance
	// races when one engine runs concurrent Runs (e.g. platform serves
	// /agent/run + the plan queue on one engine), because each turn's
	// SetMessageID WRITE overlaps another Run's Execute READ of the same field
	// -- a data race that also corrupts file-history snapshot keys. The engine
	// now threads the turn id through the per-call context (WithMessageID); a
	// tool should prefer MessageIDFromContext(ctx) and treat the field set here
	// as a fallback for direct callers that do not thread a context. Implementing
	// this interface stays optional and backward compatible.
	//
	// 仅 LEGACY / fallback: 把轮次 id 存在 SHARED 工具实例上, 当一个 engine 跑并发
	// Run 时会 race (如平台在一个 engine 上同时服务 /agent/run + 计划队列), 因为每轮
	// SetMessageID 的 WRITE 与另一个 Run 的 Execute 对同一字段的 READ 重叠 -- 既是
	// data race 又破坏 file-history 快照键. engine 现在经 per-call context 透传轮次
	// id (WithMessageID); 工具应优先 MessageIDFromContext(ctx), 把这里设的字段当作
	// 不透传 context 的直接调用者的 fallback. 实现本接口仍是可选且向后兼容.
	SetMessageID(id string)
}

type Metadata struct {
	// ConcurrencySafe 表示该工具是否可以与其他工具并行执行.
	// true: Glob,Grep,FileRead 等只读工具
	// false: FileEdit,FileWrite,Bash(可能有副作用)等
	ConcurrencySafe bool

	// ReadOnly declares this tool has no side effects (pure queries /
	// read-only FS access). Informational metadata: external SDK / TUI /
	// audit consumers render a "read-only" label; evolve's tool generator
	// may auto-set it.
	//
	// Not part of permission decisions -- permission path is driven by
	// PermissionClass (above). No in-tree consumer reads this field for
	// permission logic today.
	//
	// ReadOnly 声明该工具不产生副作用 (纯查询 / 只读 FS 访问).
	// Informational 元数据: 外部 SDK / TUI / audit 消费层据此渲染 "只读"
	// 标签, evolve 工具生成器也可据此自动设置.
	//
	// 不参与权限决策 -- 权限路径由 PermissionClass 驱动 (见上方).
	// 本字段当前无 in-tree 消费者读取做权限判断.
	ReadOnly bool

	// Destructive declares the tool may cause irreversible damage (rm -rf,
	// git push --force, DROP TABLE). Informational metadata: audit / UI
	// render warning icons; reports count "N destructive calls this session".
	//
	// Not part of permission decisions -- same constraint as ReadOnly.
	//
	// Destructive 声明该工具可能造成不可逆破坏 (rm -rf / git push --force /
	// DROP TABLE 等). Informational 元数据: audit / UI 据此渲染警告图标,
	// 审计报表统计 "本 session 破坏性调用 N 次".
	//
	// 不参与权限决策 -- 约束同 ReadOnly.
	Destructive bool

	// Aliases 工具的别名列表(向后兼容用).
	Aliases []string

	// SearchHint 搜索提示词(3-10 字),用于 ToolSearch 延迟加载时的匹配.
	SearchHint string

	// PermissionClass 声明工具的权限检查类型.
	// 权限引擎据此分派正确的安全检查逻辑,避免权限系统硬编码工具名.
	//
	// 升华改进(ELEVATED): P0-2 修复核心--工具自描述权限语义,
	// 第三方工具注册时 tools.Registry 自动调用 permission.RegisterToolClass.
	// 有效取值(见 permission 包中的 PermClass* 常量):
	//   "bash"      - 命令执行类(子命令分割 + 危险命令检测)
	//   "file"      - 文件操作类(路径权限 + 危险路径检测)
	//   "webfetch"  - Web 请求类(域名权限检查)
	//   "readonly"  - 只读类(直接放行)
	//   "generic"   - 通用(默认,规则匹配后 Ask)
	//   ""          - 未声明,权限系统使用内置 fallback(向后兼容)
	PermissionClass string

	// AuditOperation 声明工具的审计操作类型.
	// 用于 AuditObserver 将工具事件翻译为 AuditEntry.Operation 字段.
	//
	// 升华改进(ELEVATED): P1 L1191 修复 - 与 PermissionClass 同源模式, 工具自描述
	// 跨切面语义 (权限 + 审计), 消费者 (flysafe / flyto-platform-common / 新工具作者)
	// 注册自定义工具时不需要 fork 引擎修改 audit_observer.operationFromTool 的
	// switch.例如第三方 "DatabaseWrite" / "SlackSend" / "K8sApply" 工具通过
	// Metadata{AuditOperation: "write"} 声明, 审计记录立即正确.
	//
	// 常用取值 (任意自定义字符串也合法, 由消费者与其审计后端约定):
	//   "write"   - 写入 (文件写, DB 写, 消息发送)
	//   "edit"    - 修改 (文件编辑, DB 更新)
	//   "read"    - 读取 (文件读, DB 查询, glob, grep)
	//   "execute" - 命令执行 (bash, 子进程)
	//   "delete"  - 删除 (文件删, DB 删)
	//   "invoke"  - 通用调用 (默认值, 无副作用)
	//   ""        - 未声明, AuditObserver 回退到启发式 (基于工具名匹配)
	//
	// 替代方案 A: <保留硬编码 switch, 不加 Metadata 字段> - 否决:
	//   违反开闭原则, 消费者加新工具必须 fork 引擎.
	// 替代方案 B: <新增全局 RegisterAuditOperation(name, op) 函数> - 否决:
	//   引入平行于 Metadata 的第二种注册路径, 与既有 PermissionClass 风格不一致.
	// 替代方案 C: <AuditObserver 构造时注入 operationMapper func> - 否决:
	//   消费者要事先知道所有工具名, 插件动态注册场景不适用.
	AuditOperation string

	// RequiresCheckpoint 表示该工具执行前需要等待外部确认.
	//
	// 升华改进(ELEVATED): 早期实现 中"Human checkpoint"只是提示词里的文字建议,
	// 模型自己决定要不要暂停--不可靠(模型可能忽略).
	// 我们在工具声明层强制暂停:RequiresCheckpoint=true 的工具,
	// 引擎在执行前必须经过 CheckpointHandlerFn 放行,handler 未注册默认拒绝.
	//
	// 适用场景(不可逆操作):
	//   - 发送消息(邮件,IM,短信)
	//   - 删除数据(DROP TABLE,rm -rf)
	//   - 生产部署(kubectl apply,terraform apply)
	//   - 资金操作(转账,支付)
	//
	// 替代方案:<在 prompt 中写"执行前问用户">
	// - 否决:依赖模型遵守,不可靠;且无法在 SDK 嵌入模式下触发程序级回调.
	RequiresCheckpoint bool

	// RequiresReverseThinking flags this tool as one whose call benefits
	// from a reverse-thinking pass before execution: producing a
	// counterfactual.Deliverable (hidden assumptions / failure scenarios /
	// verdict / verdict_reason) that is persisted alongside the call for
	// audit and evolve.Reflector replay.
	//
	// Boundary with RequiresCheckpoint: RequiresCheckpoint asks "should a
	// human approve this call?"; RequiresReverseThinking asks "should the
	// agent challenge its own recommendation before this call?". Both can
	// be true simultaneously (high-stakes calls deserve both); core does
	// not impose ordering -- the consuming hook chain (e.g.
	// platform/common/safetychain) decides whether reverse-think runs
	// before / after / instead-of the human checkpoint.
	//
	// Suitable when (non-trivial design space, not every irreversible op):
	//   - Tool selects between competing strategies (route planning,
	//     carrier choice, policy parameter)
	//   - Tool encodes a decision whose failure mode is non-obvious
	//     (settlement matching, fraud judgment)
	//   - Tool calls a downstream system whose schema may shift
	//     (third-party API, partner integration)
	//
	// Avoid when: the tool is a pure mechanical operation (file read,
	// arithmetic, well-defined CRUD); reverse-think on these is overhead
	// without insight.
	//
	// Default false. When false, no reverse-thinking pass is invoked
	// regardless of any hooks layered on; opt-in is per-tool.
	//
	// ELEVATED rationale: rule of two with RequiresCheckpoint -- both are
	// "self-describing tool flags consumed by hooks / handlers above core",
	// adding one alongside the existing one is cheaper than introducing a
	// new metadata category.
	//
	// 替代方案 (已否决):
	//   A. 引擎级 ReverseThinkingGate 接口 (TODO L569 原方案 8 模块完整版)
	//      -- 否决: 与 hooks / permission / validator / staging / RequiresCheckpoint
	//         5 套现有 gate 重叠, 业界零先例 (调研: Claude Agent SDK / OpenAI
	//         Assistants / Vertex ADK / LangGraph / AutoGen / CrewAI / Semantic
	//         Kernel / Cline 全部走 prompt-level + tool desc + 开发者自填策略).
	//   B. 仅写 prompt 层引导, 不加字段
	//      -- 否决: prompt 易丢, 无法在 SDK 嵌入模式下程序级判定; 且
	//         Deliverable 持久化无锚点字段.
	//
	// RequiresReverseThinking 标记本工具调用前应走反向思维 pass: 产 counterfactual
	// .Deliverable (hidden_assumptions / failure_scenarios / verdict /
	// verdict_reason) 与调用一同持久化供审计和 evolve.Reflector 重放.
	//
	// 与 RequiresCheckpoint 边界: RequiresCheckpoint 问 "需要人确认吗?";
	// RequiresReverseThinking 问 "agent 应不应该挑战自己的建议?". 两者可同时
	// true (高风险调用值得两道); core 不规定顺序 -- 消费 hook 链
	// (例如 platform/common/safetychain) 决定 reverse-think 在 checkpoint
	// 之前 / 之后 / 替代.
	//
	// 适用场景 (非平凡设计空间, 不是所有不可逆操作):
	//   - 工具在多个候选策略中选择 (路由规划 / 承运商选择 / 策略参数)
	//   - 工具编码失败模式不直观的决策 (账单匹配 / 反欺诈判定)
	//   - 工具调下游 schema 可能漂移的系统 (三方 API / 合作方集成)
	//
	// 不适用: 纯机械操作 (文件读 / 算术 / 良定义 CRUD); 反向思维只是开销
	// 没有洞察.
	//
	// 默认 false. false 时无论上层挂多少 hook 都不触发反向思维; 按工具 opt-in.
	//
	// 升华理由 (ELEVATED): 与 RequiresCheckpoint 走 rule of two -- 两者都是
	// "core 之上 hook / handler 消费的自描述工具 flag", 在已有字段旁加同源字段
	// 比新增 metadata 类别更便宜.
	RequiresReverseThinking bool
}

type MetadataProvider interface {
	Metadata() Metadata
}

type Orchestrator struct {
	// contains filtered or unexported fields
}

type ProgressFunc func(progress float64, detail string)

type Registry struct {
	// contains filtered or unexported fields
}

type Result struct {
	// Output 是工具的文本输出.
	Output string

	// IsError 标记输出是否为错误信息.
	IsError bool

	// Data 是结构化数据输出(可选).
	// 用于工具间传递结构化信息.
	Data any

	// UndoInfo 撤销信息(由 Reversible 工具填充).
	// 升华改进(ELEVATED): 撤销信息嵌入 Result 而非单独返回--
	// 这样编排器在收集工具结果时自然就拿到了撤销信息,不需要额外调用.
	// 替代方案:在 Orchestrator 中单独调用 GenerateUndo(多一次调用,时序更复杂).
	UndoInfo *UndoInfo
}

type ResultProcessor interface {
	ProcessResult(toolUseID, toolName, output string) (processedOutput string, storedPath string)
}

type Reversible interface {
	// GenerateUndo 基于执行结果生成撤销信息
	GenerateUndo(ctx context.Context, input json.RawMessage, result *Result) (*UndoInfo, error)
}

type SocketAware interface {
	// SetSessionSockPath sets the path to the session UDS socket. Called by
	// engine when the Inbox UDS server starts.
	// 设 session UDS socket 路径. engine 启动 Inbox UDS server 时调用.
	SetSessionSockPath(path string)

	// SetPlanSockPath sets the path to the plan-queue UDS socket. Called by
	// engine when PlanCommandServer starts.
	// 设 plan-queue UDS socket 路径. engine 启动 PlanCommandServer 时调用.
	SetPlanSockPath(path string)
}

type Tool interface {
	// Name 返回工具的唯一标识符.
	Name() string

	// Description 返回工具的描述(提供给模型的说明).
	// 可以是动态的,根据当前上下文返回不同内容.
	Description(ctx context.Context) string

	// InputSchema 返回工具的 JSON Schema 输入定义.
	// 模型根据此 schema 生成工具调用参数.
	InputSchema() json.RawMessage

	// Execute 执行工具逻辑.
	// input 是模型生成的 JSON 参数(已通过 schema 验证).
	// 返回 Result 和可能的错误.
	//
	// ctx 携带取消信号,对应原 TS 项目的 AbortController.
	// progress 回调用于报告长时间任务的进度.
	Execute(ctx context.Context, input json.RawMessage, progress ProgressFunc) (*Result, error)
}

type ToolCall struct {
	ID    string          // API 生成的工具调用 ID
	Name  string          // 工具名称
	Input json.RawMessage // 工具输入参数(JSON)
}

type ToolCallResult struct {
	ID      string // 对应的工具调用 ID
	Name    string // 工具名称
	Output  string // 工具输出(可能被截断, 见 Truncated)
	IsError bool   // 是否出错

	// Truncated marks that Output is a short summary and the full result
	// has been persisted to StoredPath.
	//
	// Truncated 标记 Output 是短摘要, 完整结果已落盘到 StoredPath.
	Truncated bool

	// StoredPath is where the ResultProcessor persisted the full output.
	// Empty when Truncated is false. Path shape is consumer-defined
	// (local path / sandbox path / object-storage key).
	//
	// SECURITY: path may carry sandbox-internal structure. Downstream
	// observers / SSE bridges treat it as caller-specific, untrusted data
	// (e.g. do not log to shared destinations without review). Same
	// constraint applies in flyto.ToolResultEvent.StoredPath and
	// OperationEntry.StoredPath; all three share one trust boundary.
	//
	// StoredPath 是 ResultProcessor 落盘完整输出的位置. Truncated=false 时
	// 为空串. Path shape 由消费层定义 (本地路径 / sandbox 路径 / 对象存储
	// key).
	//
	// 安全: path 可能带 sandbox 内部结构. 下游 observer / SSE bridge 当作
	// 调用方特定的不可信数据对待 (未审查前不写入共享目的地). 此约束同样
	// 适用于 flyto.ToolResultEvent.StoredPath 和 OperationEntry.StoredPath,
	// 三者共享同一条信任边界.
	StoredPath string

	UndoInfo *UndoInfo // 撤销信息(由 Reversible 工具生成)

	// Data is the structured payload that the tool's Result.Data carries
	// through to the engine. Primary consumer (2026-04): engine wraps an
	// *tools/builtin.ImageResult into an array-form tool_result so vision
	// models see the real image bytes (see engine.go tool_result
	// construction). Future non-image structured payloads (e.g. document,
	// chart) can plug in without another field.
	//
	// Orchestrator preserves the reference verbatim -- no copy, no
	// serialization. Consumers MUST type-assert (`if img, ok := res.Data.(*ImageResult); ok`)
	// and handle the nil case.
	//
	// Data 是工具 Result.Data 透传到引擎的结构化载荷. 主消费者 (2026-04):
	// 引擎把 *tools/builtin.ImageResult 包成 array-form tool_result 让 vision
	// 模型真读到图 (见 engine.go tool_result 构造点). 未来非图结构化载荷
	// (文档 / 图表 / 结构化表格) 可直接沿用, 不用再加字段.
	//
	// Orchestrator 原样透传引用 -- 不拷贝不序列化. 消费方必须 type-assert
	// (`if img, ok := res.Data.(*ImageResult); ok`) 并处理 nil 情况.
	Data any
}

type ToolCapability struct {
	// DryRun 是否支持模拟执行(不产生副作用)
	DryRun bool

	// Reversible 执行后是否可撤销
	Reversible bool

	// UndoMethod is an informational static declaration of how this tool
	// can be undone: "tool" / "manual" / "" (irreversible). This is a
	// surface for external audit UI / tool panels to show rollback
	// category before execution; the engine's actual rollback path reads
	// UndoInfo.ToolName (dynamic, captured by Reversible.GenerateUndo at
	// execute time), not this field. Static vs dynamic are complementary,
	// not redundant: static lets the UI render "this tool is reversible"
	// without running; dynamic carries the concrete undo input per call.
	//
	// UndoMethod 是工具如何被撤销的 informational 静态声明: "tool" / "manual"
	// / "" (不可逆). 此字段面向外部审计 UI / 工具面板, 让其在执行前就能
	// 展示回滚分类; 引擎真实 rollback 路径读 UndoInfo.ToolName (动态, 由
	// Reversible.GenerateUndo 执行时捕获), 不读本字段. 静态和动态互补非
	// 冗余: 静态让 UI 不跑也能渲染 "此工具可撤销"; 动态携带每次调用的
	// 具体撤销参数.
	UndoMethod string

	// UndoToolName is the informational static name of the undo tool
	// when UndoMethod="tool". Same static-vs-dynamic split as UndoMethod:
	// external UI / audit consumers read this field to show "undo is
	// handled by tool X" pre-execution; the engine dispatches undo via
	// UndoInfo.ToolName (dynamic, same value in practice but sourced
	// per-call by GenerateUndo).
	//
	// UndoToolName 是 UndoMethod="tool" 时撤销工具的 informational 静态名.
	// 和 UndoMethod 同构的静态-动态分层: 外部 UI / 审计消费者读本字段
	// 在执行前展示 "由工具 X 撤销"; 引擎执行 undo 时派发 UndoInfo.ToolName
	// (动态值, 通常同值但按次由 GenerateUndo 提供).
	UndoToolName string

	// MinConfidence is the minimum self-reported confidence the engine
	// requires before dispatching this tool (0-100). Zero disables the
	// gate entirely (all calls pass).
	//
	// Wire (2026-04-21):
	//   - engine.buildToolDefs appends a "[Safety] requires _flyto_confidence
	//     in input, min=N" hint to Description for tools with MinConfidence>0,
	//     so the LLM sees the contract in the tool definition itself.
	//   - orchestrator.executeSingle calls CheckConfidenceGate before
	//     Execute. The gate parses the `_flyto_confidence` reserved field
	//     from input JSON, rejects calls below the threshold with a
	//     tool-level error (letting the LLM retry with a reconsidered
	//     value), and strips the field before handing input to the tool
	//     (so tool InputSchema stays clean).
	//   - Missing _flyto_confidence when MinConfidence>0 is treated as
	//     gate-fail (not implicit 100) -- LLM must explicitly self-assess
	//     for high-risk tools.
	//
	// MinConfidence 是引擎派发本工具前要求的最低自评置信度 (0-100). 零值
	// 完全 disable gate (所有调用放行).
	//
	// Wire (2026-04-21):
	//   - engine.buildToolDefs 对 MinConfidence>0 的工具, 在 Description 末
	//     尾追加 "[Safety] 需要在 input 中附 _flyto_confidence, 最低 N" 提示,
	//     让 LLM 在工具定义层就看到契约.
	//   - orchestrator.executeSingle 在 Execute 前调 CheckConfidenceGate.
	//     Gate 从 input JSON 解析保留字段 `_flyto_confidence`, 低于阈值返工具
	//     级错误 (让 LLM 重新评估), 放行前剥除该字段 (保持工具 InputSchema
	//     干净).
	//   - MinConfidence>0 而 _flyto_confidence 缺失视为 gate-fail (非隐式 100)
	//     -- LLM 必须为高风险工具显式自评.
	MinConfidence int

	// AffectedResources is a human-readable list of resource categories
	// the tool touches (e.g. ["file"], ["database","network"]). Pure
	// informational surface for tool panels / audit UI to classify tools
	// by blast radius. Engine does not read this field; consumers walk
	// CapabilityProvider externally.
	//
	// AffectedResources 是工具触及的资源类别人类可读列表 (如 ["file"] /
	// ["database","network"]). 纯 informational, 给工具面板 / 审计 UI 按
	// 影响范围分类. 引擎不读本字段, 外部消费者走 CapabilityProvider 调取.
	AffectedResources []string
}

type ToolPolicy interface {
	// Resolve returns the tools the engine should register, in the order
	// the model should see them. Empty slice or nil = no tools.
	//
	// Resolve 返回 engine 该注册的工具, 按模型看到的顺序. 空切片或 nil = 无工具.
	Resolve() []Tool
}

type UndoInfo struct {
	// ToolName 用哪个工具撤销
	ToolName string

	// Input 撤销工具的输入
	Input map[string]any

	// Description is a human-readable summary of the undo action shown to
	// external operators (rollback UI / audit logs). The engine does not
	// read this field during RollbackMessage -- it is purely a consumer
	// surface.
	//
	// Description 是向外部操作员展示的撤销动作人类可读摘要 (rollback UI /
	// 审计日志). 引擎在 RollbackMessage 过程中不读本字段 -- 纯消费者表面.
	Description string

	// Irreversible 标记为不可逆(某些操作执行后无法撤销)
	Irreversible bool

	// ManualGuide 不可逆时的人工处理指南
	ManualGuide string
}