// Package flyto 是 Flyto Agent 引擎的公共契约包.
//
// 这个包只包含接口和类型定义,零实现,零外部依赖.
// 消费者(TUI,HTTP Server,第三方 SDK)只需 import 这一个包,
// 不需要了解引擎内部实现细节.
//
// 核心原则:
//
//   - 最大公约数:接口只包含所有实现者都必须支持的方法
//   - 可选能力:provider 特有功能通过 type assertion 的可选接口暴露
//   - 零依赖:只用 Go 标准库,可嵌入任何环境
//   - 向后兼容:此包的任何 breaking change 都需要版本升级
//
// 包结构:
//
//	events.go    - 引擎→消费者的事件流(Event 接口 + 所有具体事件)
//	observer.go  - 消费者实现的可观测性接口(EventObserver 等)
//	message.go   - 消息模型(Message,Block,Role)
//	tool.go      - 工具定义(Tool)
//	provider.go  - 模型提供商接口(ModelProvider + 可选能力接口)
//	engine.go    - 引擎接口(Engine,消费者编程的目标)
//	errors.go    - 结构化错误类型(ErrorCode,EngineError)
//
// API consumption shapes:
//
// Flyto exposes three distinct API shapes to consumers; pick by mechanism,
// not by domain. See docs/api-reference.md section "API 消费形态 / API
// Consumption Patterns" for full taxonomy and when to use which.
//
//   - Push (subscribe) — form 1:  consumers open a stream or register a
//     callback; the engine notifies asynchronously. Interfaces: Event (via
//     `<-chan flyto.Event`) and EventObserver.
//   - Pull — form 2:  consumers call a method to read a current snapshot.
//     Example consumers of this package's types: `Session.Stats() SessionStats`
//     and `DenialTracker.Stats() DenialStats` in engine/permission packages.
//   - Synchronous callback — form 3:  engine blocks for a consumer decision.
//     Interfaces in sibling packages: permission.Handler, engine.ApprovalPolicy,
//     engine.ElicitationHandler, security.AuditSink, hooks.HookHandler.
//
// API 消费形态:
//
// Flyto 对消费者暴露三种独立 API 形态, 按机制选而非按领域选. 完整分类和选型
// 指引见 docs/api-reference.md "API 消费形态 / API Consumption Patterns"
// 章节.
//
//   - 订阅 (push) —— 形态一:消费者开流或注册回调, 引擎异步通知. 本包接口:
//     Event (经 `<-chan flyto.Event`) 和 EventObserver.
//   - 调取 (pull) —— 形态二:消费者调方法读当前快照. 本包类型在引擎/权限包
//     的消费例: `Session.Stats() SessionStats`, `DenialTracker.Stats() DenialStats`.
//   - 同步回调 (callback) —— 形态三:引擎阻塞等消费者决策. 兄弟包接口:
//     permission.Handler, engine.ApprovalPolicy, engine.ElicitationHandler,
//     security.AuditSink, hooks.HookHandler.
package flyto