engine

type ActivityReason string

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

type ActivityTrackerConfig struct {
	// HeartbeatInterval 心跳间隔(busy 时定时触发).默认 30s.
	HeartbeatInterval time.Duration

	// IdleDelay 空闲延迟:refcount 归零后等多久才触发 OnIdle.默认 30s.
	// 精妙之处(CLEVER): 不是立刻触发 OnIdle--
	// 工具执行完到下一次 API 调用之间有短暂间隙,不应算 idle.
	// 只有真正 30s 无活动才算空闲.
	IdleDelay time.Duration

	// OnBusy refcount 0→1 时触发(Agent 从空闲变为繁忙)
	OnBusy func()

	// OnIdle refcount 1→0 且延迟到期后触发(Agent 真正空闲)
	OnIdle func(idleDuration time.Duration)

	// OnHeartbeat busy 时每 HeartbeatInterval 触发一次
	OnHeartbeat func(activeReasons map[ActivityReason]int, duration time.Duration)
}

type AgentDefLoader interface {
	// LoadAgentDefs 加载并返回所有 AgentDefinition.
	// 如果没有可加载的定义,返回空切片(不是错误).
	LoadAgentDefs() ([]*AgentDefinition, error)
}

type AgentDefinition struct {
	// AgentType 唯一标识符,如 "Explore","Plan"
	AgentType string

	// Description 一句话描述,展示给用户/模型
	Description string

	// WhenToUse 何时使用的指引文案,辅助 AI 做类型选择
	WhenToUse string

	// AllowedTools 允许使用的工具白名单(nil = 继承父代理所有工具).
	// MCP 工具(mcp__ 前缀)自动通过此过滤,无需在此列出.
	AllowedTools []string

	// DisallowedTools 额外禁用的工具(叠加在全局禁用之上)
	DisallowedTools []string

	// Model 使用的模型("" = 继承父代理模型)
	Model string

	// MaxTurns 最大轮数(0 = 默认 10)
	MaxTurns int

	// Background 是否默认后台运行.
	// 当 Background=true 且 BackgroundAllowedTools 非空时,
	// 在 AllowedTools 基础上额外收窄到 BackgroundAllowedTools.
	Background bool

	// BackgroundAllowedTools 后台运行时的附加工具白名单.
	//
	// 升华改进(ELEVATED): 早期实现 用全局常量 ASYNC_AGENT_ALLOWED_TOOLS(约16个工具),
	// 所有 isAsync=true 的 agent 都受此约束,无法针对不同 agent 类型定制.
	// 我们改为 per-agent 配置--每种 Agent 类型声明自己的后台工具集,
	// 仓储场景可以把 mcp__wms__* 加进去,而默认 Verification agent 只需文件读工具.
	// MCP 工具(mcp__ 前缀)仍然自动通过此过滤.
	// nil = Background 模式不附加额外限制(仍受 AllowedTools 约束).
	// 替代方案:<全局 ASYNC_AGENT_ALLOWED_TOOLS 常量> - 否决:扩展性差,
	//   增加新 agent 类型时必须修改全局常量.
	BackgroundAllowedTools []string

	// AllowedSubAgentTypes 限制此 Agent 可以 spawn 的子 Agent 类型.
	//
	// 升华改进(ELEVATED): 早期实现 resolveAgentTools() 第191-195行用 allowedAgentTypes
	// 元数据约束 Agent 工具只能 spawn 特定类型,但通过字符串解析("Agent(Explore)")实现.
	// 我们改为结构化字段--类型安全,易于序列化,不需要解析器.
	// 跨行业影响:Explore 类型只能 spawn Plan/Verification 子 agent(禁止 general-purpose),
	// 防止只读 agent 通过 spawn 全能 agent 来绕过工具限制.
	// nil/空 = 无限制,可 spawn 任何已注册的 AgentType.
	// 替代方案:<字符串语法 Agent(Explore, Plan)> - 否决:需要解析器,容易写错.
	AllowedSubAgentTypes []string
}

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

type ApprovalPolicy interface {
	// RequestApproval 请求用户审批计划.阻塞直到用户批准或拒绝.
	// 返回:
	//   - approved: 是否批准
	//   - editedPlan: 用户编辑后的计划文本(空字符串 = 未编辑,使用早期方案)
	//   - err: 系统错误(不是用户拒绝)
	RequestApproval(ctx context.Context, event PlanApprovalEvent) (approved bool, editedPlan string, err error)
}

type AttachmentReorderer struct{}

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

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

type CacheStats struct {
	Entries   int // 当前缓存条目数
	MaxSize   int // 最大缓存条目数
	Hits      int // 缓存命中次数(Get 命中)
	Misses    int // 缓存未命中次数(Get 未命中)
	Evictions int // 淘汰次数
}

type CheckpointEvent = flyto.CheckpointEvent

type CheckpointHandlerFn func(evt CheckpointEvent) bool

type CheckpointSuggestedEvent = flyto.CheckpointSuggestedEvent

type CompactEvent = flyto.CompactEvent

type Complexity string

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

type Config struct {
	// Model 指定默认使用的模型 ID(向后兼容,设置 RoleMain)
	Model string

	// Models 模型注册表(如果为 nil,使用默认)
	// 通过角色系统管理不同用途的模型选择
	Models *config.ModelRegistry

	// Cwd 是工作目录,工具执行的根目录
	Cwd string

	// Executor 是子进程启动器, 必填. engine.New 校验 nil 返回 error.
	//
	// 本地模式: 消费方传 execenv.DefaultExecutor{} (零开销包装 os/exec).
	// 云端模式: platform 层传 sandbox.Backend{} 实现 microVM 隔离.
	//
	// 方案 β 严格 DI: 引擎对执行环境零假设, 所有 exec 子进程走此抽象.
	// 详见 platform/common/internal/sandbox/DESIGN.md section 7 + 7.2.
	//
	// 2026-04-15 M1 commit 4b-1 引入.
	Executor execenv.Executor

	// Tools 指定启用的工具列表,为空则启用所有内置工具
	Tools []string

	// MaxTurns 限制单次 Run 的最大对话轮次,0 表示无限制
	MaxTurns int

	// MaxBudgetUSD 限制单次 Run 的最大花费(美元),0 表示无限制
	MaxBudgetUSD float64

	// PermissionMode 权限模式:default / accept_edits / bypass / plan
	PermissionMode permission.Mode

	// PermissionHandler 自定义权限处理器,消费层实现
	// 当工具需要用户批准时调用此函数
	// 如果为 nil,则根据 PermissionMode 自动决策
	PermissionHandler permission.Handler

	// PermissionTimeout 权限 Handler 调用超时(默认 5 分钟).
	// 0 表示使用 permission.DefaultPermissionTimeout.
	//
	// 升华改进(ELEVATED): 暴露到 Config 而非硬编码在引擎内部--
	// 自动化测试场景可以设为 100ms(快速失败),
	// 企业审批流程可以设为 30min(等人工审批).
	// 替代方案:硬编码 DefaultPermissionTimeout(无法按场景覆盖).
	PermissionTimeout time.Duration

	// CompactionPolicies 压缩策略列表(叠加为 CompositePolicy).
	// 为空时使用 DefaultCodePolicy.
	// 如果只有一个策略,不会包装 CompositePolicy,直接使用.
	CompactionPolicies []agentctx.CompactionPolicy

	// PermissionHandlers 权限处理器列表(叠加为 CompositeHandler).
	// 为空时使用 Config.PermissionHandler(向后兼容).
	PermissionHandlers []permission.NamedHandler

	// SystemPrompt 自定义系统提示词(覆盖默认)
	SystemPrompt string

	// AppendSystemPrompt 追加到默认系统提示词之后
	AppendSystemPrompt string

	// Scenario 场景标识符,用于 PromptBundle 选择("programming"/"warehouse"/"medical" 等).
	// 空字符串 = "programming"(默认).
	// 引擎内置 claude+programming Bundle;其他场景需通过 RegisterPromptBundle 注册.
	Scenario string

	// ModelFamily 模型族标识符("claude"/"gpt"/"gemini"/"local" 等).
	// 空字符串时从 Model 字段推断(前缀匹配 "claude-" → "claude").
	// 用于 PromptBundle 选择.
	ModelFamily string

	// Plugins declares plugin definitions that the engine registers at
	// construction time (engine.New) via plugin.Host.Load. Each definition
	// is a metadata triple (Name / Description / Source); it does NOT carry
	// a filesystem path to a plugin.json, so the registration is a
	// metadata-only placeholder -- skills, hooks, tools, and MCP servers
	// are NOT parsed from this path. For those, the sibling paths are:
	//   - engine.LoadPlugin(dir): reads a plugin.json on disk and registers
	//     all declared skills/hooks/tools/MCPServers. This is the primary
	//     path for "I have a packaged plugin on the filesystem".
	//   - plugin.Host.RegisterBuiltin: SDK consumers that want to ship a
	//     plugin in-binary (builtin) call this before engine.New and the
	//     host-wide LoadAll picks it up.
	// Config.Plugins is the narrow niche of "declaratively announce this
	// plugin's existence to the host registry without packaging it" --
	// useful for SDK tests, bookkeeping, or consumers that want the host to
	// know about a plugin before a later LoadFromDir call materializes it.
	//
	// Lifecycle: definitions are consumed once in engine.New
	// (loadConfigPlugins), before syncPluginHooks / syncPluginTools /
	// syncPluginMCPServers so any subsequent plugin operation observes a
	// stable registry. The slice is read once and not watched for changes
	// after construction.
	//
	// Failure strategy: an empty Name produces a config_plugin_skipped
	// observer event and is discarded. A Host.Load failure (rare -- the
	// current implementation only writes to a map under lock) produces a
	// config_plugin_load_failed event and is not fatal -- a broken entry
	// must not prevent the engine from starting or other entries from
	// loading.
	//
	// Plugins 声明 engine.New 时要往 plugin.Host 注册的插件定义. 每个
	// Definition 只是 metadata 三元组 (Name / Description / Source), 不
	// 带 plugin.json 的文件系统路径, 因此这条路径只做 metadata 占位登记
	// -- skills / hooks / tools / MCPServers 不会从这里解析. 要解析走
	// 两条姊妹路径:
	//   - engine.LoadPlugin(dir): 读磁盘上的 plugin.json 并注册里面声明
	//     的 skills / hooks / tools / MCPServers. 文件系统里有打包 plugin
	//     时用这条.
	//   - plugin.Host.RegisterBuiltin: SDK 消费方想把 plugin 内嵌进二进制
	//     (builtin), 在 engine.New 之前调这个, 随后 host 的 LoadAll 合并
	//     进 registry.
	// Config.Plugins 是个窄场景: "声明式地让 host registry 知道有这个
	// plugin, 但不打包". 用于 SDK 测试、bookkeeping, 或消费方希望在后续
	// LoadFromDir 真正物化之前 host 就知道 plugin 存在的场合.
	//
	// 生命周期: engine.New 里 loadConfigPlugins 消费一次, 位置在
	// syncPluginHooks / syncPluginTools / syncPluginMCPServers 之前,
	// 让随后任何 plugin 操作观察到一份稳定的 registry. slice 读一次,
	// 构造后不再 watch 变化.
	//
	// 失败策略: 空 Name 触发 config_plugin_skipped 事件并丢弃. Host.Load
	// 失败 (罕见, 当前实现仅是带锁 map 写入) 触发 config_plugin_load_failed
	// 事件且不 fatal -- 坏 entry 不能挡引擎启动或其他 entry 加载.
	Plugins []plugin.Definition

	// MCPServers declares MCP servers that the engine launches at construction
	// time (engine.New). Each entry becomes an mcp.Manager client under the
	// "config." namespace (see configMCPServerKey); its tools are wrapped as
	// mcpProxyTool and registered in the engine's tool registry with names of
	// the form "config:<ServerName>/<toolName>".
	//
	// This is the SDK-main-process path for "I want to plug in an external
	// MCP server subprocess without packaging it as a plugin". The two
	// sibling paths with different scopes:
	//   - plugin.Manifest.MCPServers: same subprocess style but declared
	//     via plugin.json, lifecycle tied to plugin enable/disable.
	//   - ExtraTools: same-process Go tools (tools.Tool interface) with no
	//     IPC round-trip, no subprocess, no MCP client -- preferable when
	//     the tool can be expressed in Go.
	//
	// Lifecycle: servers start once in engine.New (startConfigMCPServers)
	// and stop in engine.Close via mcpMgr.CloseAll. The slice is read once
	// and not watched for changes after construction.
	//
	// Failure strategy: a single server's connect/list-tools failure is an
	// observer event, not fatal -- a broken server must not prevent the
	// engine from starting or other servers from loading.
	//
	// MCPServers 声明 engine.New 时要拉起的 MCP server. 每个 entry 在
	// mcp.Manager 里以 "config." 前缀建 client (见 configMCPServerKey),
	// 发现的 tool 包成 mcpProxyTool 注册到引擎 tool registry, 名字形如
	// "config:<ServerName>/<toolName>".
	//
	// 这是 SDK 主进程侧 "我想接一个 external MCP server subprocess, 但不
	// 愿意打成 plugin 包" 的路径. 两条姊妹路径:
	//   - plugin.Manifest.MCPServers: 同样是 subprocess, 但经 plugin.json
	//     声明, 生命周期随 plugin enable/disable.
	//   - ExtraTools: same-process Go 工具 (tools.Tool 接口), 无 IPC 往返,
	//     无 subprocess, 无 MCP client -- 能用 Go 表达的工具首选这条路.
	//
	// 生命周期: engine.New 里 startConfigMCPServers 拉起一次,
	// engine.Close 里 mcpMgr.CloseAll 一并关闭. slice 读一次, 构造后不再
	// watch 变化.
	//
	// 失败策略: 单个 server connect / list-tools 失败是 observer 事件, 不
	// fatal -- 坏 server 不能挡引擎启动或其他 server 加载.
	MCPServers []config.MCPServerConfig

	// HooksConfig Hook 配置
	HooksConfig *hooks.Config

	// EnableCaching 启用 prompt caching(静态系统提示会被标记为可缓存)
	// EnableCaching 启用 prompt caching(静态系统提示会被标记为可缓存)
	// 当 Provider==nil 时用于创建默认 AnthropicProvider;
	// 当 Provider!=nil 时由 Provider 自己实现(如 anthropic.New(Config{EnableCaching: true})).
	EnableCaching bool

	// Thinking extended thinking 配置
	// 当 Provider==nil 时用于创建默认 AnthropicProvider;
	// 当 Provider!=nil 时通过 flyto.Request.NeedsThinking 控制.
	Thinking *ThinkingOptions

	// Effort 努力级别 ("low"/"medium"/"high"),空字符串表示不设置
	// 通过 flyto.Request.Effort 传递给 Provider.
	Effort string

	// FastMode 启用快速模式(调整 max_tokens 默认值)
	// 通过 flyto.Request.FastMode 传递给 Provider.
	FastMode bool

	// JSONSchema 结构化输出的 JSON Schema(如果设置,约束模型输出)
	// 通过 flyto.Request.ResponseFormat 传递给 Provider.
	JSONSchema json.RawMessage

	// Fallback 模型降级配置(可选).
	// 当主模型 API 调用失败时,自动降级到备用模型.
	Fallback *FallbackConfig

	// MemoryExtractor 记忆提取器(可选).
	// 设置后,查询循环结束时会异步 fork SubAgent 执行记忆提取.
	MemoryExtractor memory.MemoryExtractor

	// Verbose 详细日志模式
	Verbose bool

	// Observer 可观测性接口(可选).
	// 接收引擎运行时的结构化事件,指标和调用链.
	// 如果为 nil,使用 NoopObserver(零开销空实现).
	//
	// 升华改进(ELEVATED): Observer 是结构化事件流,与 Verbose 日志互补.
	// Verbose 是给开发者看的文本日志,Observer 是给监控系统消费的数据.
	// 替代方案:只用 Verbose + fmt.Fprintf(黑盒,无法被外部系统消费).
	Observer EventObserver

	// StrictMode 严格模式(可选).
	// 安全评估/测试环境开启,让引擎在检测到异常时 panic 而不是静默修复.
	// 如果为 nil,所有异常静默修复+记录.
	StrictMode *StrictMode

	// ActivityTracker 活动追踪器配置(可选).
	// 设置后启用心跳/空闲检测.nil 时不追踪.
	ActivityConfig *ActivityTrackerConfig

	// CloseTimeout 优雅关闭超时(默认 10s).
	// Close() 在 cancel context 后等待此时间让 goroutine 退出,
	// 然后强制清理剩余资源.
	// 仓储 daemon 场景可能需要更长(如 30s).
	CloseTimeout time.Duration

	// SecretGuard 秘密扫描器(可选).
	// FileWrite / FileEdit 工具写入前调用此扫描器,检测 API key,密码等敏感信息.
	//
	// 升华改进(ELEVATED): 默认行为"默认开,全路径保护"--
	// 若调用方不设置此字段,New() 自动注入 DefaultSecretGuard(45条内置规则).
	// 若要关闭扫描(测试场景,已知安全的场景),显式传入 security.NoopSecretGuard{}.
	// 若要自定义规则(行业特有 key 格式),传入 NewSecretGuardWithRules(...).
	//
	// 精妙之处(CLEVER): nil 与 NoopSecretGuard 的区别--
	// nil 触发默认注入(保护性行为),NoopSecretGuard 是显式关闭(必须有意为之).
	// 不可能因为"忘记设置"而静默绕过安全检查.
	// 替代方案:<nil = 不扫描> - 否决原因:遗漏配置等价于静默关闭安全,风险太高.
	SecretGuard security.SecretGuard

	// AuditSink 审计落地后端(可选).
	// 设置后,engine.New() 自动创建 AuditObserver 并与 Config.Observer 叠加,
	// 将 operation_recorded / secret_scan_blocked 事件翻译为审计条目写入此 sink.
	//
	// 升华改进(ELEVATED): 审计通过 Observer 模式接入,工具层无感知--
	// FileWrite/FileEdit 只需触发事件,AuditObserver 在 Observer 链中接收并写入.
	// 零侵入性:不需要修改任何工具代码就能开启/关闭审计.
	//
	// nil 表示不开启审计.想开启本地审计(JSONL 文件),使用 NewLocalAuditSink().
	// 替代方案:<在 OperationLog.Record 内部直接写 AuditSink>
	// - 否决原因:将审计落地耦合进操作日志,违反单一职责,且跨包导致循环导入.
	AuditSink security.AuditSink

	// AuditSessionID 审计会话 ID(可选).
	// 注入到每条 AuditEntry.SessionID 字段,用于多用户/多会话场景区分来源.
	// CLI 单用户场景可以为空(audit.jsonl 里会显示为空字符串).
	AuditSessionID string

	// AuditIncludeToolInput 决定是否把工具调用的 Input 参数写入 AuditEntry.Extra["tool_input"].
	//
	// 默认 false (早期实现的 beta 也默认关, 要求双 env 才开).
	// 开启前提: Input 已由 engine 层经 SecretStore.Redact 脱敏, 所以已注册的 secret 值
	// 会替换为 [SECRET:NAME]. 未注册的明文密码/PII 仍会进入审计日志, 调用方自担风险.
	//
	// 场景: 合规审计 (HIPAA/SOC2) 要求留存完整请求载荷做 forensics.
	// 单用户 CLI 场景保持默认关闭更安全.
	//
	// 替代方案: <引入可插拔 InputRedactor 接口 + SecretGuard regex 兜底> -
	// 否决原因: SecretStore.Redact 已覆盖用户注册的所有凭据, 再叠一层 regex 脱敏边际收益
	// 很低, 且违反 CLAUDE.md 原则 10 "叠加而非替换" (不应另造 redact 层, 应复用).
	AuditIncludeToolInput bool

	// AuditInputMaxBytes 限制 Extra["tool_input"] 单条字节数上限, 超出会截断并加
	// Extra["tool_input_truncated"]="true". <=0 表示不截断 (不推荐, 单条审计条目可能爆表).
	// 仅当 AuditIncludeToolInput=true 时生效. 建议值 4096 (早期方案 truncateContent 默认).
	AuditInputMaxBytes int

	// FreshnessConfig 记忆新鲜度警告配置(可选).
	// nil = 不启用新鲜度功能(UpdateIndex 回落到早期方案 30 天硬编码,CheckMemoryRelevance 不注入警告).
	// 启用:传 &memory.FreshnessConfig{GlobalThreshold: 24 * time.Hour}
	// 或使用便捷函数:memory.DefaultFreshnessConfig() 然后取地址.
	//
	// 升华改进(ELEVATED): 早期实现 无任何新鲜度提示,只有 MEMORY.md 里的静态年龄注记.
	// 模型无法根据静态注记判断"这条记忆当前对话是否仍然有效".
	// 我们在 CheckMemoryRelevance 注入时加 FreshnessNote,让模型在看到记忆内容的
	// 同时收到"此记忆已 N 天未更新,请核实"的提醒.
	// 替代方案:<在 Entry.Content 里追加警告文本> -
	// 否决原因:污染记忆内容本身,影响提取/检索评分.
	FreshnessConfig *memory.FreshnessConfig

	// MemoryScorer 自定义记忆相关性评分器(可选).
	// nil 时走默认 TextScorer (Jaccard 文本相似度).
	// 替代算法场景(嵌入向量/BM25)传入自定义实现.
	MemoryScorer memory.RelevanceScorer

	// MemoryTypeRegistry 自定义记忆类型注册表(可选).
	// nil 时用 memory.DefaultTypeRegistry (user/feedback/project/reference 四类型).
	// 多租户或行业特化场景可注册自定义类型(如 medical/legal/warehouse).
	MemoryTypeRegistry *memory.MemoryTypeRegistry

	// MemoryStrictSymlink 启用记忆文件严格符号链接保护(可选).
	// false(默认): 检测到符号链接记日志但放行(兼容 NFS/Docker/WSL).
	// true: 检测到符号链接拒绝操作(服务端部署/CI 环境推荐).
	MemoryStrictSymlink bool

	// MemorySyncAdapter 记忆远程同步适配器(可选).
	// nil 时不同步(纯本地). 团队协作场景传 memory.NewGitSyncAdapter(...).
	MemorySyncAdapter memory.SyncAdapter

	// MemorySyncConfig 同步策略配置(仅 MemorySyncAdapter 非 nil 时生效).
	MemorySyncConfig memory.SyncConfig

	// ElicitationHandler 处理 MCP 服务器发出的用户输入请求(可选).
	// 对应 MCP 2025-03-26 规范的 elicitation/create server-to-client 请求.
	//
	// 升华改进(ELEVATED): 早期实现 无此接口--遇到服务器主动请求时直接挂起.
	// 设置后,MCP Manager 会在 Initialize 时将此 handler 注入到每个 Client,
	// dispatchLoop 识别到 server-to-client 请求时路由到此 handler 处理.
	//
	// nil 时自动使用 NoopElicitationHandler(返回 cancel,不阻塞,不 panic).
	// 替代方案:<全局变量注册> - 否决:多 Engine 实例下每个引擎可以有不同的 UI 处理器.
	ElicitationHandler ElicitationHandler

	// EnableUDSInbox 启用 Unix Domain Socket Inbox(默认 false).
	// 启用后,引擎创建 UDS 服务端(路径由 resolveSockPath 决定,优先用户私有目录),
	// 通过 FLYTO_SESSION_SOCK 环境变量注入到所有工具子进程.
	// 工具子进程可向此 socket 发送 JSON 消息(进度,日志等),
	// 引擎接收后转为 InboxMessageEvent 推送给观察者.
	//
	// CLI 模式下建议设为 true;SDK 嵌入/无 shell 环境下可保持 false.
	//
	// 精妙之处(CLEVER): 默认 false 确保向后兼容--
	//   现有 SDK 用户不受影响,不会多出意外的 socket 文件.
	//   只有明确需要工具进度报告的场景才开启.
	//   替代方案:默认 true(更多功能但有副作用,/tmp 多文件,老用户可能困惑).
	EnableUDSInbox bool

	// UDSInboxSessionID 是 UDS socket 文件名的 sessionID 部分(可选).
	// 空字符串时自动生成(基于时间戳+随机数).
	// 显式设置:测试中可固定 socket 路径;多进程场景可通过外部协调分配路径.
	//
	// 升华改进(ELEVATED): sessionID 与 Engine 生命周期绑定(不是 Session.ID)--
	//   一个 Engine 实例有且仅有一个 UDS 路径,与会话数量无关.
	//   替代方案:每个 Session 独立 UDS(socket 文件爆炸,管理复杂).
	UDSInboxSessionID string

	// EnablePlanQueue 启用异步计划队列(默认 false).
	// 启用后:
	//   1. 引擎在 ~/.flyto/plans/ 创建 FilePlanQueue,daemon 重启时自动 RecoverPending.
	//   2. 引擎启动 PlanCommandServer(UDS 路径由 resolvePlanSockPath 决定),
	//      通过 FLYTO_PLAN_SOCK 环境变量注入,供外部进程提交/查询/取消计划.
	//
	// 适用场景:daemon 模式(长期驻留),需要 fire-and-forget 执行超大计划.
	// CLI 单次调用模式无需启用(每次调用都是独立进程).
	//
	// 精妙之处(CLEVER): 与 EnableUDSInbox 分开控制--
	//   UDSInbox 是工具进度上报(从工具子进程 → 引擎),
	//   PlanQueue 是计划异步执行(从外部客户端 → daemon 引擎).
	//   两者虽然都用 UDS,但方向和语义完全不同,应独立开关.
	EnablePlanQueue bool

	// PlanQueueDir 是计划状态文件的存储目录(可选).
	// 空字符串使用默认路径 ~/.flyto/plans/.
	// 显式设置主要用于测试隔离或自定义数据目录.
	PlanQueueDir string

	// PlanQueueSessionID 是 PlanCommandServer socket 文件名的 sessionID 部分(可选).
	// 空字符串时自动生成(基于时间戳).与 UDSInboxSessionID 分开是因为两个服务独立.
	PlanQueueSessionID string

	// SharedSystemPromptBytes 是父 Engine fork SubAgent 时传入的已渲染系统提示词字节(可选).
	//
	// 精妙之处(CLEVER): Anthropic Prompt Cache 按内容字节哈希命中--
	//   父子 Agent 如果分别渲染系统提示词,哪怕逻辑相同,
	//   任何微小差异(时间戳注入,随机 ID,空格)都会导致哈希不同,无法命中同一缓存 slot.
	//   父 Engine 将已发送给 API 的字节直接传给 SubAgent,
	//   SubAgent 用完全相同的字节发送请求,100% 命中缓存.
	//
	// 设置规则:
	//   nil  = 不共享(SubAgent 独立渲染,向后兼容旧行为).
	//   非nil = 优先使用此字节,跳过 buildSystemPromptWithContext 渲染.
	//
	// 注意:此字段由引擎内部(SpawnSubAgent)设置,SDK 用户通常不需要手动填写.
	// 替代方案:<每次都独立渲染>
	// - 否决:父子 Agent 分别渲染导致缓存 miss,每个 SubAgent 首轮都要付完整系统提示费用.
	SharedSystemPromptBytes []byte

	// IsOrchestrator 标记此 Engine 是否运行在协调器(Orchestrator)模式.
	//
	// 升华改进(ELEVATED): 协调器模式是"多 Agent 拓扑"的中间层角色--
	//   它不直接完成叶子任务,而是分解任务,分派 SubAgent,合并结果.
	//   开启此标志后,系统提示词会注入协调器专用指导段落,
	//   告知模型如何并行分派任务,如何检查一致性,如何处理子代理失败.
	//
	// 精妙之处(CLEVER): bool 标志而非字符串角色--
	//   IsOrchestrator=true 精确表达"我是协调器",消除歧义.
	//   如果将来需要更多角色("peer"/"leaf"),可扩展为 AgentRole string,
	//   当前阶段 bool 足够且最简单.
	// 替代方案:<在 SystemPrompt 里手动追加协调器指导文字>
	// - 否决:手动追加无法被 SectionRegistry 缓存,每轮都重算;
	//   且散落在调用方代码里难以统一维护.
	IsOrchestrator bool

	// ScratchpadDir 指定文件持久化 Scratchpad 的目录路径(模块 18.3).
	//
	// 升华改进(ELEVATED): 早期实现 无持久化 Scratchpad--所有暂存数据绑定单个进程.
	// 我们通过此字段启用跨进程共享(FileScratchpad 替换 in-memory Scratchpad):
	//   - ScratchpadDir=""(默认):使用 in-memory Scratchpad,生命周期绑定 Engine
	//   - ScratchpadDir 非空:使用 FileScratchpad,数据持久化到目录,支持跨进程共享
	// 跨行业应用:
	//   仓储调度:多个 picking-robot Worker 进程共享"已分配库位"暂存数据
	//   金融对账:并发 reconcile Worker 共享"已处理批次 ID 集合"
	// 替代方案:<Redis/共享内存> - 否决:破坏零外部依赖;文件系统已满足最终一致性需求.
	ScratchpadDir string

	// ExtraTools 是额外注册的工具(通过 --tools-schema 或 SDK 注入).
	//
	// 升华改进(ELEVATED): 叠加而非替换--ExtraTools 在内置工具注册完成后追加,
	// 支持"内置工具 + 外部工具"并存.SDK 用户可通过此字段注入任何实现了 tools.Tool 接口的工具,
	// 无需 fork 引擎源码.
	//
	// 跨行业扩展:
	//   ExecTool(外部进程工具)是最常见的注入方式--将任意 CLI 程序包装为 Agent 工具.
	//   也可以注入纯 Go 实现的定制工具(如特定行业 SDK 封装).
	//
	// 与 cfg.Tools 的交互:
	//   cfg.Tools 非空时会过滤内置工具,但 ExtraTools 不受此过滤--
	//   调用方既然显式注入了,就一定是想启用的.
	//
	// 替代方案:<通过 Plugin 系统注入> - Plugin 机制更重(需要实现 plugin.Definition 接口 + 注册),
	// ExtraTools 对简单场景(注入少量工具)代价更低.
	ExtraTools []tools.Tool

	// Provider 指定模型提供者(可选).
	//
	// 升华改进(ELEVATED): 当 Provider 非 nil 时,引擎通过 flyto.ModelProvider 接口
	// 而非 internal/api/client.go 直接调用 API--
	//   - 支持任何实现 flyto.ModelProvider 的 provider:Gemini/OpenAI/Ollama/本地模型等
	//   - provider 自己处理鉴权,SSE 解析,思考模式等细节,引擎与 API 格式解耦
	//   - nil 时回退到 internal/api 路径(保持对 Anthropic 原生 API 的完整向后兼容)
	//
	// 使用示例:
	//
	//	cfg := &engine.Config{
	//	    Provider: gemini.New(gemini.Config{APIKey: os.Getenv("GEMINI_API_KEY")}),
	//	}
	//
	// 注意:Provider 路径目前不支持 Anthropic 专有功能(cache_control 分块,ExtendedThinking 配置).
	// 需要这些功能时,使用 nil(默认 api.Client 路径)+ Anthropic provider 的对应配置.
	// 替代方案:<强制所有 provider 都走 flyto.ModelProvider 路径> -
	// 否决:Anthropic 路径有独特的 beta headers,cache_control 分块等,
	// 需要 api.Client 特定功能,无法通过 flyto.Request 表达.
	Provider flyto.ModelProvider

	// AgentName 是此 Engine 在 Agent Teams 通讯中的名称 (peer-to-peer 消息的 from 字段).
	// 空字符串时 = 不参与 Teams 通讯 (独立运行 / Leader 单机模式).
	//
	// 升华改进(ELEVATED): AgentName 解耦"Engine 实例"与"Team 成员身份"--
	// 同一个 Engine 实例在不同 Team 中可用不同名字 (通过 Config 新建 Engine),
	// Team 内成员名字由消费层决定 (code-reviewer / analyst / diagnoser 等跨行业语义).
	//
	// 跨行业扩展: 金融场景 "risk-analyst-1", 医疗场景 "triage-doctor", 仓储场景 "wave-planner"
	// 都是合法值, 引擎不解释此字段的含义, 只作为消息路由 key.
	//
	// 替代方案: <把 name 硬绑到 session_id> - 否决: 一个 session 可能涉及多个 agent 身份.
	AgentName string

	// IncomingInbox 是 Agent Teams peer-to-peer 通讯的收件入口.
	// nil = 不参与 Teams 通讯 (Engine 仍可正常运行, 只是无同伴消息).
	//
	// 升华改进(ELEVATED): 接口而非具体实现--
	// MemoryInbox 用于单进程 dogfood / 测试, 跨行业客户可注入自己的 Inbox 实现
	// (医疗合规加密存储 / 金融审计表 / SaaS 中间件桥接等).
	//
	// 消息由 Engine.runLoop 每轮开始时 Poll (非阻塞), 包装成 <teammate-message> XML
	// 注入到对话流, 模型下一轮可自然读到同伴消息.
	//
	// 设计权衡: Poll 而非 goroutine + Recv 阻塞--
	// Recv 需要独立 goroutine 和 channel 桥接到 runLoop, 复杂度高且死锁面大;
	// Poll 和 runLoop 同步, 无额外 goroutine, 延迟上限 = 一轮对话时间 (可接受).
	//
	// 替代方案: <每条消息起独立 goroutine enqueueTeamNotification> -
	// 否决: 额外协程和锁, 对 MVP 场景不必要.
	IncomingInbox inbox.Inbox
}

type ConsecutiveRoleMerger struct{}

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

type DoneEvent = flyto.DoneEvent

type DreamConfig struct {
	MemStore     memory.Store
	Models       *config.ModelRegistry
	MinHours     float64 // 默认 24
	MinSess      int     // 默认 5
	TaskStore    *DreamTaskStore
	ParentEngine EngineRef // 用于 fork 模式(可选;L1224 起仅 ForkSubAgent 需要它)

	// L1224: 独立注入的可观测性依赖.engine.go 构造顺序已调整为先建 observer/activity/rootCtx
	// 再 buildDreamEngine,所以这三项在 Config 里就可填,不必走 post-fill 回填.
	// Observer==nil 时 NewDreamEngine 兜底 NoopObserver;Activity/RootCtx 可保持 nil.
	Observer EventObserver
	Activity *ActivityTracker
	RootCtx  context.Context

	// SessionProvider 提供会话列表(可选).
	// CLI 场景:传 &FileSessionProvider{Dir: transcriptDir}.
	// SDK/API 长驻:可传自定义实现;nil = 不提供 session hint.
	SessionProvider SessionProvider

	// TranscriptDir 是 transcript 目录,用于 Dream prompt 中的 grep 示例(可选).
	// CLI 场景下通常与 FileSessionProvider.Dir 相同.
	TranscriptDir string

	// PeriodicInterval 是定时触发的间隔(0 = 不启用定时器).
	// CLI per-session 不需要设置(session end 触发已足够).
	// SDK/API 长驻进程可设置,例如 6 * time.Hour.
	PeriodicInterval time.Duration
}

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

type DreamStatus string

type DreamTaskState struct {
	ID               string      `json:"id"`
	Status           DreamStatus `json:"status"`
	Phase            string      `json:"phase"`
	SessionsReviewed int         `json:"sessions_reviewed"`

	// FilesTouched 是 Dream agent 通过 Edit/Write 工具触达的文件路径列表.
	//
	// 精妙之处(CLEVER): 通过 onMessage 回调从 tool_use 事件提取 file_path,
	// 而不是在 Dream 完成后扫描 memory dir 的 mtime--
	// 事件流提取:精确,不受并发写入干扰.
	// mtime 扫描:有竞态,其他进程写文件会误报.
	// filesTouched 用于完成提示"Improved N memories",精确比完整更重要.
	FilesTouched []string `json:"files_touched"`

	// Turns 是最近 maxDreamTurns 个 assistant 轮次的进度摘要(滚动窗口).
	Turns []DreamTurn `json:"turns,omitempty"`

	StartTime time.Time `json:"start_time"`
	EndTime   time.Time `json:"end_time,omitempty"`
	Error     string    `json:"error,omitempty"`
	// contains filtered or unexported fields
}

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

type DreamTurn struct {
	Text         string // assistant 回复的文本内容(摘要/推理)
	ToolUseCount int    // 本轮工具调用次数(折叠,不枚举)
}

type ElicitationField struct {
	// Name 字段名称(对应 JSON schema property key)
	Name string

	// Type 字段类型("string" / "number" / "boolean")
	Type string

	// Title 显示给用户的标题(可选)
	Title string

	// Description 字段描述(可选,展示为输入框 placeholder 或 tooltip)
	Description string

	// Required 是否必填
	Required bool

	// Default 默认值(字符串表示,消费层负责类型转换)
	Default string
}

type ElicitationHandler interface {
	HandleElicitation(req ElicitationRequest) (ElicitationResponse, error)
}

type ElicitationHandlerFunc func(req ElicitationRequest) (ElicitationResponse, error)

type ElicitationRequest struct {
	// ServerName 发起请求的 MCP 服务器名称
	ServerName string

	// Message 展示给用户的问题或说明文字(Markdown 格式)
	Message string

	// Fields 需要用户填写的字段列表(按声明顺序)
	Fields []ElicitationField
}

type ElicitationResponse struct {
	// Action 用户操作:
	//   "accept"  - 用户确认并提交了数据
	//   "decline" - 用户明确拒绝(服务器应该放弃该操作)
	//   "cancel"  - 用户取消(服务器可以重试或使用默认值)
	Action string

	// Values 用户填写的字段值(仅 Action=="accept" 时有意义)
	// key 为 ElicitationField.Name,value 为用户输入的字符串
	// 消费层负责类型校验;服务器负责最终语义解析
	Values map[string]string
}

type EmptyMessageFilter struct{}

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

type EngineBackend interface {
	// BuildAndStream 构建请求并发起流式调用.
	// attempt 用于可观测性(记录在重试日志中).
	BuildAndStream(ctx context.Context, model string, maxTokens int, promptBlocks []agentctx.SystemPromptBlock, messages []query.Message, toolDefs any, responseFormat *flyto.ResponseFormat, attempt int) (<-chan flyto.Event, error)
}

type EngineError struct {
	// Code 是错误码,用于程序化处理
	Code ErrorCode

	// Message 是人类可读的错误描述
	Message string

	// Detail 是技术细节,用于调试和日志
	Detail string

	// Suggestion 是恢复建议,帮助用户解决问题
	Suggestion string

	// Cause 是导致此错误的原始错误
	Cause error

	// Retryable 指示此错误是否可以通过重试解决
	Retryable bool
}

type EngineRef interface {
	// Run 启动一次对话轮次,返回事件流.
	Run(ctx context.Context, prompt string, opts ...RunOption) <-chan Event

	// Session 获取或创建指定 ID 的会话.
	Session(id string) *Session

	// Observer 返回事件观察者,用于埋点和错误上报.
	Observer() EventObserver

	// Activity 返回活动追踪器,用于引用计数(防止 Close() 误判空闲).
	Activity() *ActivityTracker

	// Context 返回引擎生命周期 context(引擎关闭时 cancel).
	Context() context.Context

	// Cwd 返回工作目录路径.
	Cwd() string

	// ForkSubAgent 从当前引擎 fork 一个子 Agent 实例.
	//
	// 升华改进(ELEVATED): 将 SpawnSubAgent(*Engine, cfg) 包进接口方法--
	// agentExecutor 不再需要类型断言(*Engine),EngineRef 成为真正的完整接口.
	// 原文件注释说 SpawnSubAgent 是"例外"(需访问大量内部成员),
	// 通过此方法封装后,内部成员访问移到 Engine.ForkSubAgent 实现里,
	// 对 agentExecutor 完全透明.
	// 替代方案:<保留类型断言,维持现状> --否决:三处重复断言,EngineRef 形同虚设.
	ForkSubAgent(cfg *SubAgentConfig) *SubAgent
}

type ErrorCode string

type ErrorContentStripper struct {
	// Patterns 错误模式映射.如果为 nil,使用 DefaultErrorPatterns.
	Patterns map[string][]query.ContentType
}

type ErrorEvent = flyto.ErrorEvent

type Event = flyto.Event

type EventEmitter func(evt Event)

type EventObserver = flyto.EventObserver

type ExecutionContext string

type FallbackConfig struct {
	// FallbackModel 是备用模型 ID(从 ModelRegistry 获取).
	// 如果为空,不做降级.
	FallbackModel string

	// MaxFallbacks 单次 Run 最大降级次数(防止无限循环).
	// 默认值为 1.
	MaxFallbacks int

	// FallbackOnErrors 触发降级的错误类型.
	// 例如 ["model_not_found", "quota_exceeded", "overloaded"].
	FallbackOnErrors []string
}

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

type FileAgentDefLoader struct {
	// Dir 是要扫描的目录路径
	Dir string
}

type FileBackup struct {
	ContentHash    string      // SHA256 前 16 字符
	BackupPath     string      // 备份文件的磁盘路径
	OriginalExists bool        // 原文件是否存在(新建文件为 false)
	FileMode       fs.FileMode // 原文件的权限
}

type FileCacheEntry struct {
	Path        string    // 绝对路径
	ContentHash string    // SHA256 前 16 字符
	Size        int64     // 文件大小(字节)
	LineCount   int       // 行数
	ReadAt      time.Time // 最后读取时间
	ModTime     time.Time // 文件修改时间(读取时的)
	WasModified bool      // 自上次读取后是否被外部修改
}

type FileChangeChecker interface {
	RecentFiles(n int) []string
	IsModified(path string) bool
	// Info returns a value snapshot of the cache entry for path so
	// reminders can tell the model what specifically was read (size,
	// hash, line count, read timestamp, prior-modified flag) -- not
	// just "this file changed". Implementations that cannot provide
	// the snapshot should return (FileCacheEntry{}, false); the
	// consumer (CheckFileModifications) falls back to path-only output.
	//
	// Info 返回 path 对应缓存条目的值快照, 让 reminder 能告诉模型"读
	// 的是什么"(大小 / 哈希 / 行数 / 读取时间 / 是否已被标记过) --
	// 而不仅仅是"这个文件变了". 实现若无法提供快照应返回
	// (FileCacheEntry{}, false); 消费者 (CheckFileModifications)
	// 会降级为只输出路径.
	Info(path string) (FileCacheEntry, bool)
}

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

type FileHistoryView interface {
	// CanRollback 检查指定 messageID 是否存在可回滚的快照.
	// 返回: (是否可回滚, 该次提交涉及的文件路径列表)
	CanRollback(messageID string) (bool, []string)

	// SnapshotCount 返回当前持有的快照总数.
	// 用于监控 / 诊断 / 容量告警场景.
	SnapshotCount() int
}

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

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

type FilePlanStore struct {
	// Dir 是计划文件目录(通常 ~/.flyto/plans/).
	// 若为空,使用 os.TempDir()/flyto-plans/.
	Dir string
	// contains filtered or unexported fields
}

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

type FileSessionProvider struct {
	// Dir 是 transcript 目录,例如 ~/.flyto/projects/<hash>/
	Dir string
	// ExcludeID 是要排除的会话 ID(通常是当前会话,其 mtime 总是很新)
	ExcludeID string
}

type FileSnapshot struct {
	MessageID   string                 // 关联的消息 ID
	Timestamp   time.Time              // 快照创建时间
	FileBackups map[string]*FileBackup // filePath → backup
}

type FileSnapshotStore struct {
	// Dir 快照文件目录.
	// 若为空,使用 defaultSnapshotDir()(~/.flyto/snapshots/).
	Dir string
}

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

type FlushGate[T any] struct {
	// contains filtered or unexported fields
}

type FuncApprovalPolicy struct {
	Fn func(ctx context.Context, event PlanApprovalEvent) (approved bool, editedPlan string, err error)
}

type ImageValidator struct {
	// MaxSizeBytes 图片大小限制(字节).如果为 0,使用默认值.
	MaxSizeBytes int64
}

type InboxMessageEvent = flyto.InboxMessageEvent

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

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

type ManagedSession struct {
	// Session 是底层会话对象
	Session *Session

	// Info 是会话摘要信息
	Info SessionInfo
	// contains filtered or unexported fields
}

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

type MessageNormalizer interface {
	Name() string
	Priority() int // 执行优先级(越小越先执行)
	Normalize(messages []query.Message) []query.Message
}

type MetricObserver = flyto.MetricObserver

type MigrateFunc func(*Transcript) error

type NoopApprovalPolicy struct{}

type NoopElicitationHandler struct{}

type NoopObserver struct{}

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

type OperationEntry struct {
	ID         string          // 操作唯一 ID(通常等于 tool_use ID)
	MessageID  string          // 关联的消息 ID
	TurnNumber int             // 对话轮次号 (pull API, 外部审计经 GetByMessage 读)
	ToolName   string          // 工具名称
	Input      json.RawMessage // 工具输入参数
	Output     string          // 工具输出 (pull API, 可能是 orchestrator 截断后的短摘要, 见 Truncated)
	UndoInfo   *tools.UndoInfo // 撤销信息(可选)
	Timestamp  time.Time       // 操作时间
	Status     string          // opStatusSuccess / opStatusFailed / opStatusRolledBack

	// Truncated marks that Output is a short summary -- the full tool
	// result was persisted to StoredPath by the orchestrator. Audit
	// consumers walking OperationLog need this flag to avoid treating
	// summary as the authoritative record.
	//
	// Truncated 标记 Output 是短摘要 -- 完整工具结果已由 orchestrator 落盘到
	// StoredPath. 走 OperationLog 的审计消费者据此避免把摘要当作权威记录.
	Truncated bool

	// StoredPath is the persistence location of the full tool result.
	// Path shape is consumer-defined (local path / sandbox path / object
	// key). Empty when Truncated is false. SECURITY: same constraints as
	// flyto.ToolResultEvent.StoredPath -- treat as caller-specific data.
	//
	// StoredPath 是完整工具结果的持久化位置. Path shape 由消费层定义 (本地
	// 路径 / sandbox 路径 / 对象 key). Truncated=false 时为空串. 安全: 约束
	// 同 flyto.ToolResultEvent.StoredPath -- 当调用方特定数据对待.
	StoredPath string
}

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

type OrphanThinkingFilter struct{}

type OrphanToolResultRemover struct{}

type PartialToolUse struct {
	// ID 工具调用的 ID(来自 content_block_start 事件)
	ID string `json:"id"`
	// Name 工具名称
	Name string `json:"name"`
	// Input 已收到的部分 JSON 字符串(可能不完整)
	Input string `json:"input"`
}

type PermissionHandler interface {
	// HandlePermissionRequest handles a Worker's permission request.
	// Returns approved=true to allow, false to deny.
	// updatedInput, when non-nil, replaces the original tool input (consumer-layer
	// sanitization, e.g. rewriting Bash commands or restricting file paths).
	// reason is a human-readable explanation surfaced in logs and tool-result errors.
	//
	// HandlePermissionRequest 处理来自 Worker 的权限请求.
	// approved=true 批准, false 拒绝.
	// updatedInput 非 nil 时替换原始 tool input (消费层 sanitize, 如改写 Bash 命令
	// 或限制文件路径).
	// reason 是人类可读说明, 写入日志并显示在 tool-result 错误里.
	HandlePermissionRequest(ctx context.Context, req inbox.PermissionRequestPayload) (approved bool, updatedInput map[string]any, reason string)
}

type PermissionLearnEvent = flyto.PermissionLearnEvent

type PermissionLearnRule = flyto.PermissionLearnRule

type PermissionRequestEvent = flyto.PermissionRequestEvent

type PlanApprovalEvent struct {
	// SessionID 标识是哪个会话的计划.
	SessionID string

	// Plan 计划的完整文本内容(从 PlanStore 读取).
	Plan string

	// FilePath 计划文件的逻辑路径(用于展示给用户).
	FilePath string

	// Steps 可选的结构化步骤列表(如果计划包含 YAML/JSON 步骤块则解析).
	Steps []PlanStep

	// Approve 批准计划(允许执行).editedPlan 非空时用编辑后的版本覆盖原计划.
	// 必须调用 Approve 或 Reject 之一,否则 ExitPlanMode 会一直等待.
	Approve func(editedPlan string) error

	// Reject 拒绝计划(保持 plan 模式,让模型修改计划).
	Reject func(reason string) error
}

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

type PlanExecFunc func(ctx context.Context, plan *QueuedPlan, onStepDone func(stepID string, err error)) error

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

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

type PlanProgressEvent struct {
	// Snapshot 当前进度快照.
	Snapshot PlanProgressSnapshot
}

type PlanProgressSnapshot struct {
	// SessionID 关联的会话 ID.
	SessionID string

	// Steps 步骤进度列表(有序,与注册顺序一致).
	Steps []StepProgress

	// 聚合计数(冗余但高频使用,快照生成时预计算)
	TotalCount   int
	PendingCount int
	RunningCount int
	DoneCount    int
	FailedCount  int
	SkippedCount int

	// StartedAt 第一个步骤开始的时间(所有步骤未开始时为零值).
	StartedAt time.Time

	// FinishedAt 所有步骤进入终态的时间(尚未完成时为零值).
	FinishedAt time.Time
}

type PlanQueue interface {
	// Submit 提交一个计划进入队列,立即返回 planID.
	// 如果队列已满返回 ErrPlanQueueFull.
	Submit(steps []PlanStep, opts PlanSubmitOptions) (planID string, err error)

	// Status 查询计划当前状态.planID 不存在返回 ErrPlanNotFound.
	Status(planID string) (*QueuedPlan, error)

	// Cancel 取消一个 pending 或 running 的计划.
	// 已是终态的计划返回 ErrPlanTerminal.
	Cancel(planID string) error

	// List 返回所有计划的列表(按提交时间倒序).
	List() ([]*QueuedPlan, error)

	// RecoverPending 在 daemon 启动时调用:扫描文件目录,
	// 将状态为 running 的计划(daemon 崩溃前的遗留)重置为 pending 并重新入队.
	RecoverPending() error

	// Close 关闭队列,等待当前执行中的计划完成(或超时).
	Close() error
}

type PlanStatus string

type PlanStep struct {
	// ID 步骤唯一标识符(模型生成,通常是顺序编号如 "step-1").
	ID string

	// Description 步骤的人类可读描述.
	Description string

	// Tools 该步骤预期用到的工具列表(提示性,不做强制限制).
	Tools []string

	// Complexity 预估复杂度(low/medium/high).
	Complexity Complexity

	// Deps 依赖的步骤 ID 列表.空表示无依赖(可并行执行).
	// 精妙之处(CLEVER): Deps 是拓扑排序的输入,而不是"顺序"--
	// 消费方可以 Kahn 算法找出可并行的步骤层.
	// 如果用 "after: step-2" 的字符串指令,消费方要解析 Markdown,容易错.
	Deps []string
}

type PlanStore interface {
	// WritePlan 将计划内容写入持久化存储.sessionID 用于路由到正确的文件/记录.
	WritePlan(sessionID, content string) error

	// ReadPlan 读取计划内容.若不存在返回 ("", nil),不是 error.
	ReadPlan(sessionID string) (string, error)

	// PlanPath 返回计划的逻辑路径(用于展示给用户,不保证是真实文件系统路径).
	PlanPath(sessionID string) string
}

type PlanSubmitOptions struct {
	// TimeoutSecs 单次执行超时(秒),0 使用默认值 planDefaultTimeoutSecs.
	TimeoutSecs int
}

type ProcessedInput struct {
	// Text 处理后的文本(文件引用已展开)
	Text string

	// ContentBlocks 额外的内容块(图片等)
	ContentBlocks []query.Content

	// ReferencedFiles 引用的文件列表
	ReferencedFiles []string

	// DetectedURLs 检测到的 URL
	DetectedURLs []string

	// SlashCommand 如果是斜杠命令,返回命令信息
	SlashCommand *SlashCommand

	// IsEmpty 输入是否为空
	IsEmpty bool
}

type QueryChainTracking struct {
	// ChainId 整条链的唯一 ID(从用户请求到所有子 agent 共享同一个)
	ChainId string
	// Depth 当前深度(0=主查询, 1=子agent, 2=子子agent)
	Depth int
	// ParentAgentId 父 agent 的 ID(主查询为空)
	ParentAgentId string
}

type QuerySource string

type QueuedPlan struct {
	// ID 全局唯一标识符,格式 "plan-{timestamp_ns}-{random_hex}".
	// 精妙之处(CLEVER): 时间戳前缀保证按提交顺序排序(ls 即可看到顺序).
	ID string `json:"id"`

	// Steps 计划的结构化步骤列表(来自 PlanStep,复用模块 17 的类型).
	Steps []PlanStep `json:"steps"`

	// Status 当前状态(状态机见上方注释).
	Status PlanStatus `json:"status"`

	// SubmittedAt 提交时间(UTC).
	SubmittedAt time.Time `json:"submitted_at"`

	// StartedAt 开始执行时间,nil 表示尚未开始.
	StartedAt *time.Time `json:"started_at,omitempty"`

	// FinishedAt 完成时间(成功/失败/取消),nil 表示尚未完成.
	FinishedAt *time.Time `json:"finished_at,omitempty"`

	// ErrorMsg 失败原因(仅 failed 状态有值).
	ErrorMsg string `json:"error,omitempty"`

	// TimeoutSecs 单次执行超时秒数(默认 planDefaultTimeoutSecs).
	TimeoutSecs int `json:"timeout_secs"`

	// StepStatuses 各步骤的执行状态,key = PlanStep.ID.
	// 升华改进(ELEVATED): 早期实现 PlanMode 没有 per-step 状态追踪,
	// 只有整体进度.我们按步骤粒度记录,客户端可以显示精确进度条.
	StepStatuses map[string]StepExecStatus `json:"step_statuses,omitempty"`

	// CurrentStepID 当前正在执行的步骤 ID.
	CurrentStepID string `json:"current_step_id,omitempty"`
}

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

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

type RetentionPolicy struct {
	// MaxAgeDays 超过 N 天的备份文件删除,0 表示不按时间清理.
	MaxAgeDays int

	// MaxVersions 每个原始文件保留最近 N 个版本,0 表示不按版本数清理.
	MaxVersions int
}

type RunOption func(*runConfig)

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

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