engine

type ChannelBrief struct {
	Channel string
	Chat    string
	Owner   string
	SID     string
}

type ChannelConfig struct {
	ID    string
	Model string
	Sink  ChannelSink
}

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

type ChannelSink interface {
	Deliver(b ChannelBrief, ev session.Event)
}

type CheckPointStore interface {
	Get(ctx context.Context, key string) ([]byte, bool, error)
	Set(ctx context.Context, key string, checkpoint []byte) error
}

type GateChecker func(ctx context.Context, workspaceRoot string) error

type GateConfig struct {
	Checkers   []GateChecker // 按序执行，首个失败即回灌（错误文案应含判据名——门卡展示用）
	MaxRetries int           // 回灌上限（负数 = 缺省 2；0 = 零回灌——首验失败即报错，codex Guardian cyber 档同型）
}

type InboundMsg struct {
	Channel     string
	Chat        string
	Owner       string
	Mode        string
	Text        string
	Attachments []session.Attachment
	// T6 多参与者：发送者身份（适配器解析协议后透传——feishu 的 open_id 等；
	// 渠道账号 ↔ 业务用户的映射归应用）。空 = 单用户零变化（Owner 语义原样）。
	// 群聊第二个及以后的发送者经此入链：名册首见登记 + 当轮说话人 + 排队署名
	//——此前（实锚）已绑定会话的后续发送者身份被静默丢弃。
	SpeakerID   string
	SpeakerName string
	// T6 会话形态（p2p | group——适配器解析透传，应用据此选择装配策略；
	// 基座不消费）。
	ChatType string
}

type Manager struct {
	Opt Options
	// contains filtered or unexported fields
}

type Options struct {
	// Providers 模型解析（组装期调用；空清单 = 未配置模型错误面）。
	Providers func() []llm.ProviderSpec
	// Instruction 系统提示词（应用内容——业务职责段 + 通用段 + 会话配置段 +
	// 模式段拼装归应用；入参 = 会话配置概要，每轮 assemble 实时注入）。
	Instruction func(sess SessionBrief) string
	// Tools 业务工具面（实现 contract.Tool；入参 = 会话概要——多租户按
	// Owner 裁剪工具面、按会话身份定制；nil = 无业务工具）。闭包每轮
	// assemble 求值、跨会话并发调用——应快速返回且无共享可变态。
	Tools func(sess SessionBrief) []contract.Tool
	// ProcessTools 进程级通用件（时间/网络等——应用选择加入的基座件）。
	ProcessTools func() []contract.Tool
	// SessionToolsOff 排除的会话域工具族（族名见 sessiontools.go 的族常量；
	// nil/空 = 全挂零行为变化——族构造失败照常上抛 CONFIG，不静默吞错），未知
	// 名 NewManager 即拒——对齐 DenyTools 的 fail-fast 纪律）。
	// 裁 fs 族 = 放弃 reduction 外置换指针取回（外置指针经 read_file 虚拟
	// 路径取回，工具不在场则超长结果只剩截断头尾）——留装配者知情决策，
	// 引擎不联动（上游截断与外置在同一 handler 内一体，禁外置须复制其逻辑）。
	SessionToolsOff []string
	// ToolWrap 工具包装缝（契约层最外包装，挂 hitl 审批包装之外；主面与
	// 子代理面同挂——审计/脱敏/动态准入覆盖主面与子代理面的全部契约工具，
	// spawn 派发本体不经包装）。nil = 不包装，零行为变化。契约义务：
	//  1. Info() 须透传原名（名字是审批名单/子代理白名单/动态装载分流的
	//     寻址键）；
	//  2. 拒绝执行以 {"ok":false,"error":…} 信封返回回喂模型自纠（勿返回
	//     Go error——本缝在 errFeed 外层，Go error 会终止整轮且模型不可见）；
	//  3. 只能收紧不能放宽：收到的是已含审批的实例，透传即保留全部审批
	//     语义（ArgsForce/模式审批不可豁免——以会话域件为界成立，裸实例
	//     在引擎内不可得；业务工具的裸实例本就在应用手中，绕过属应用
	//     自毁）；伪造结果属违约；
	//  4. 包装随每次 assemble 重建（Run/Resume 各一次）——有状态包装的
	//     计数不跨轮；
	//  5. 勿从包装内发起 *contract.Suspend（引擎三卡分叉与决议消费链路
	//     未对应用开放）。
	ToolWrap func(t contract.Tool) contract.Tool
	// Hooks 订阅式工具钩子（audit/拦截零样板订阅口，nil = 零变化）：挂
	// ToolWrap 之外的最外层（包装序 hitl → ToolWrap → Hooks → einoext——
	// 审计看终局：Pre 先于审批决策触发、Post 收审批拒绝信封与工具原始
	// 返回）。主面与子代理面同挂；Pre 可否决（error = 拒绝信封回喂，只能
	// 收紧不能放宽——与 ToolWrap 同纪律）。语义全貌见 toolhooks.go。
	Hooks *ToolHooks
	// NewModel 模型构造口（缺省生产构造 llm.NewChatModel；测试注入假模型）。
	NewModel llm.ModelFactory
	// ImageResolve 图片引用解析（文档仓库路径 → 字节+MIME；nil = 图片不可用——
	// 含图请求即错误面。vision 包装在模型调用边界消费）。
	ImageResolve llm.ImageResolver
	// CheckPoints 会话检查点存储构造（operator+sid 定位）。
	CheckPoints func(operator, sid string) CheckPointStore
	// SkillsDir skill 物化目录（nil/空 = 不挂 skill middleware；物化归应用。
	// 入参 = 会话概要——按租户物化不同 skill 包；与 Tools 同契约：每轮
	// assemble 求值、并发安全）。
	SkillsDir func(sess SessionBrief) string
	// AgentsMD AGENTS.md 注入清单（nil/空清单 = 不挂零变化；绝对路径，按序
	// 注入）。发现逻辑归应用（ZCode 双层形态：用户级文件先、工作区级文件后
	// 收窄覆盖——两文件按序进清单即得）；跨会话记忆注入通道同走此缝（owner
	// 级记忆文件进清单）。与 SkillsDir 同契约：每轮 assemble 求值、并发安全。
	AgentsMD func(sess SessionBrief) []string
	// AgentsMDMaxBytes 注入字节预算（0 = 缺省 32KiB；上游按序装载超限即跳过
	// 余下文件——预算显式化，防提示词面失控）。
	AgentsMDMaxBytes int
	// ContextBudget 常驻上下文预算（token，口径 = estTokens 启发式）：Instruction
	// + 常驻工具面（业务面+进程件+会话域件+spawn：名+描述+参数 schema JSON）
	// 合计的超限告警线。0 = 缺省关（nil 纪律：零配置零变化；推荐值 8192 与
	// 调法见 docs/04）。超限动作 = harness_note（Kind: budget）+ 服务端日志、
	// 不阻断运行（大工具面配 toolsearch 就是合法超标场景）；会话内只发一次
	// （判定扫 Events 既有同 Kind note，跨重启天然不重发）。env
	// EINO_CONTEXT_BUDGET 可覆盖（对齐 EINO_MAX_ITERATIONS 惯例）。toolsearch
	// 名单内工具不进核算——动态装载正是瘦身手段，只有常驻面计费。
	ContextBudget int
	// Approval 审批配置（写工具名单/动作名/参数豁免——业务内容）。
	Approval hitl.ApprovalConfig
	// ApprovalRouter 审批路由（T6，nil = 不路由——全员可见谁先点谁决议）：
	// 挂起卡生成时按会话概要与卡面裁决「问谁」，目标随卡下发（前端定向提示）
	// 并入 pending target（DecisionGuard 校验依据）。判据归应用（机制与内容
	// 分离：基座只携带身份与执行校验）。
	ApprovalRouter func(brief SessionBrief, req contract.ApprovalReq) *contract.Participant
	// DecisionGuard 决议校验缝（T6，nil = 不校验——应用自带认证时的零变化）：
	// 挂起卡有路由目标且决议带决议者时校验一致性，mismatch 拒绝（fail-closed
	// ——防越权点批）。
	DecisionGuard func(targetID, deciderID string) error
	// WorkspaceRoot 会话工作区根（用户域 workspaces/<sid>——WorkspaceKeep
	// 声明的持久子区跨任务保留、其余一轮一清；惰性创建）。
	WorkspaceRoot func(owner, sid string) string
	// WorkspaceKeep 任务收尾清理保留的工作区子目录（顶层目录名——挂载区、
	// 参考资料区等由装配层声明，基座不预设名字；nil/空 = 无持久区全清）。
	// 持久子区随会话删除/过期/孤儿清扫整清（Registry.Delete/Sweep 整目录
	// 移除，不看此栏）。
	WorkspaceKeep []string
	// WorkspaceProtect 工作区写保护区（顶层目录名；注入 fsutil/applypatch
	// 写面——delete_file 与补丁目标〔含 Move to 改名目标〕命中即整单拒绝、
	// 读面不受影响；nil/空 = 不设区零变化。命令面 run_command 不在此栏——
	// 命令内容不可静态可靠解析，写的硬约束归 Sandbox 档位）。
	WorkspaceProtect []string
	// SubAgents spawn 子代理装配（H2；nil = 不装配 spawn）。
	SubAgents *SubAgentsConfig
	// Topology 确定性场景多 agent 拓扑（H5：supervisor/deep 官方 prebuilt 接线；
	// nil = 单 agent react 既有主线。红线表对拓扑内子 agent 全量生效）。
	Topology *TopologyConfig
	// ToolSearchPolicy 动态工具装载（H7：名单外常驻、名单内经 tool_search
	// 检索后可见；nil = 全量常驻零变化。审批包装在分流上游——ArgsForce 与
	// 模式审批对动态工具不豁免）。
	ToolSearchPolicy *ToolSearchPolicy
	// Sandbox run_command 沙箱策略（nil = 不沙箱——产品默认关 opt-in；
	// 机制 = einox/sandbox re-exec 哨兵协议，产品 main 需挂 RunHelper 钩子）。
	Sandbox *sandbox.Policy
	// SandboxProvider 沙箱后端（nil = sandbox.OSProvider 平台内建；容器类
	// 后端如 sandbox.DockerProvider 经此注入——与 Sandbox 正交：策略定
	// 「施加什么」，后端定「怎么施加」）。
	SandboxProvider sandbox.Provider
	// Egress 网络出口校验器（S-9：run_command 命令串 URL 预检；nil = 不
	// 预检零变化。webfetch 侧的注入在应用 ProcessTools（进程级工具归应用
	// 装配），此处只管引擎持有的命令面）。
	Egress *egress.Validator
	// SummarizerFallbackModels 摘要模型 Failover 降级链（H9-10：主摘要模型
	// 失败按序降级的复合键清单，逐个同链包装 vision/shape 后填 adk Failover；
	// 空 = 不配降级零变化（单端点装配配了也白配）；链尽走既有清窗兜底不外抛。
	// ShouldFailover 排除 ctx 取消/中断类、MaxRetries=链长——审查补差内建。
	SummarizerFallbackModels []string
	// FallbackModels 主对话模型 Failover 降级链（复合键清单；空 = 零变化）。
	// 重试先耗尽（有界重连）、RetryExhaustedError 触发按序换链上模型（每档
	// 各享完整重连预算）；粘滞上次成功模型归 adk。切换发 model_change 事件；
	// 致命类（401/403/402 配置错）不降级直接停机；ctx 取消/审批中断不降级。
	// 清单错配（键不在 Providers 内）不阻断运行：降级失效 + harness_note 留痕。
	// 子代理/拓扑子面不挂（链按主模型语境配置，维持 retry-only）。
	FallbackModels []string
	// Recall 跨会话检索工具（记忆拉通道，opt-in）：模型可读本 owner 历史会话
	// 的摘要与消息投影（三模式 sid 深读/query 检索/最近列表；恒排除当前会话、
	// 有界、摘要级——授权五律见 recall.go）。是新能力面：装配即知情决策，
	// false = 不装配零变化。条件装配先例 = channels 之于 Options.Channels。
	Recall bool
	// TurnEpilogue 轮收尾交接钩子（记忆写通道，nil = 零变化）：自然收束
	// （StateEnded）每轮触发，载荷与 session_end 事件同源（摘要+文件变更）。
	// einox 的 session_end 是轮级——应用自行去重/节流。同步调用应快速返回，
	// 重提取（LLM 蒸馏/外部写）归应用异步；panic 由引擎兜底不影响终态。
	// 最小用法：把摘要追加进 owner 域记忆 markdown，经 AgentsMD 清单注入。
	TurnEpilogue func(sum TurnEndSummary)
	// FinalGate 收束质量门（nil = 零变化）：自然收束后、终态落盘前按
	// GateConfig.Checkers 强制验证——失败经 harness_note 门卡 + 反馈消息
	// 入史回灌重跑（有界，MaxRetries 缺省 2），耗尽 error 收束不静默放行。
	// 闭包入参 SessionBrief：按模式/任务形态决定开门与否与判据清单（判据
	// 归应用——build/test 命令或自包的对抗审查；基座只持门循环机制）。
	// 挂起/中断/错误轮不触发；重试预算随 Run/Resume 执行体。
	FinalGate func(sess SessionBrief) *GateConfig
	// Channels 消息渠道装配（nil/空 = 不装配零变化）：每条目一个渠道实例
	// （ID 进程内唯一、Sink 出站投递——渲染归适配器）。渠道编排面
	// Manager.Channels() 懒建总可用：入站 Handle 分流（空闲起轮/运行中
	// 排队）、常驻事件订阅出站（覆盖挂起期）、Approve/Answer 决议续流、
	// Cancel/Push。渠道协议归适配器（官方通用件 channels/ 子包；业务
	// 自定义渠道长在业务仓）——同 llm 供应商「内置目录 + 自定义」两层
	// 模式，见 docs/04。
	Channels []ChannelConfig
}

type SessionBrief struct {
	Mode   string
	Model  string // 复合键 provider/model
	Effort string
	Owner  string // 会话归属用户
	SID    string // 会话标识
	// ParentSID 辅助对话父会话（空 = 普通会话——应用可据此调 Instruction/
	// 工具面/skill 目录；side 共享父工作区与外置域，见 wsSID）。
	ParentSID string
	// T6 当轮说话人（空 = 单用户零变化）：应用装配面可见——按人裁剪
	// Instruction/工具面/审批判定（机制与内容分离：身份只透传，策略归应用）。
	TurnSpeakerID   string
	TurnSpeakerName string
}

type SpawnOutput struct {
	// Schema 期望结论 JSON Schema（根形必须 object——构造期校验拒收）。
	Schema *contract.Schema
}

type SubAgentSpec struct {
	Name        string
	Description string
	Instruction string   // 空 = 引擎缺省子提示词（subInstruction 同款）
	Tools       []string // 工具白名单（红线：数据域写与 repo 写工具不进）
	DenyTools   []string // 硬拒名单（H9-6：交集/未同名装配期 configError，与 spawn 同闸）
	Model       string   // 模型覆写复合键（空 = 随父会话快照）
}

type SubAgentsConfig struct {
	Tools         []string // 工具白名单（全量面按名筛；内容归业务——数据域写工具不列入）
	DenyTools     []string // 硬拒名单（H9-6 纪律升机制：与白名单交集非空或含全量面未同名 → 装配期 configError；不配 = 行为不变）
	Instruction   string   // 子提示词（空 = 引擎缺省模板）
	Model         string   // 模型覆写复合键（空 = 随父会话快照）
	MaxConcurrent int      // 并发 spawn 上限（0 = 不限）
	// EmitEvents 全量转发档（H8-2 事件折叠三档之一，默认关）：开 = 子代理
	// 内部事件经泵翻译为 EvSubAgent 转发父流（只读流——子过程不进父上下文，
	// 折叠卡展开态消费；并行多 spawn 同名事件交错，per-invocation 归组为
	// 升级位）。关 = 静默/折叠一行（spawn 的 EvToolCall/EvToolResult 即卡面）。
	EmitEvents bool
	// Output 结构化回传（T8，nil = 自由文本结论零变化）：子代理面注入
	// spawn_submit 工具，合法提交即收束，canonical JSON 回父。
	Output *SpawnOutput
}

type ToolHookCall struct {
	Sess SessionBrief // 含 ParentSID——side 面可区分
	Name string
	Args json.RawMessage
}

type ToolHookResult struct {
	Result json.RawMessage
	Err    error
	Dur    time.Duration
}

type ToolHooks struct {
	Pre  func(c ToolHookCall) error
	Post func(c ToolHookCall, r ToolHookResult)
}

type ToolSearchPolicy struct {
	// DynamicTools 动态面工具名（检索后可见）；名单外全量常驻
	// （ask_user/todo_write/submit_plan 等会话域件与高频件留常驻是装配纪律）。
	DynamicTools []string
}

type TopologyConfig struct {
	Kind      string
	SubAgents []SubAgentSpec
}

type TurnEndSummary struct {
	Owner   string
	SID     string
	Title   string
	Task    string
	Summary string                // 会话累计文本聚合（session_end 同源；列表摘要口径截 60 字，非单轮）
	Files   []contract.FileChange // 文件变更清单（有改动才非空）
	EndedAt time.Time
}