// Package engine implements the Flyto Agent engine: runtime loop, session
// management, tool dispatch, observability, context management, and the
// consumer-facing integration surfaces that platform / SaaS / CLI layers
// attach to.
//
// Consumer integration surfaces fall into three shapes. For the full
// taxonomy (mechanism, when-to-use, quick chooser, why each shape cannot
// replace another), see `docs/api-reference.md` section "API 消费形态 /
// API Consumption Patterns".
//
// Push (subscribe) — form 1:
//   - `<-chan flyto.Event` returned by Engine.Run / Session.Send (typed
//     event stream consumers range and type-switch on)
//   - engine.Config.Observer (flyto.EventObserver) for internal diagnostic
//     events such as `session_cost_threshold_crossed`, `compact_finished`,
//     `section_cache_break`
//
// Pull — form 2:
//   - Session.Stats() SessionStats
//   - Session.Title() / Messages() / Snapshot()
//   - FileStateCache.Stats() CacheStats
//
// Synchronous callback — form 3:
//   - engine.Config.PermissionHandler (permission.Handler)
//   - engine.Config.ApprovalPolicy (ApprovalPolicy interface)
//   - engine.Config.ElicitationHandler (ElicitationHandler interface)
//   - engine.Config.AuditSink (security.AuditSink)
//   - engine.Config.Hooks (pkg/hooks.HookHandler via Manager)
//
// Package engine 实现 Flyto Agent 引擎: 运行循环 / 会话管理 / 工具分发 / 可
// 观测性 / 上下文管理, 以及平台/SaaS/CLI 接入的消费者接口面.
//
// 消费者接入面分三种形态. 完整分类 (机制 / 何时用 / 选型速查 / 三者不互相
// 替代的原因) 见 `docs/api-reference.md` "API 消费形态 / API Consumption
// Patterns" 章节.
//
// 订阅 (push) —— 形态一:
//   - Engine.Run / Session.Send 返回的 `<-chan flyto.Event` (强类型事件流,
//     消费者 range + type-switch)
//   - engine.Config.Observer (flyto.EventObserver) 内部诊断事件, 如
//     `session_cost_threshold_crossed` / `compact_finished` /
//     `section_cache_break`
//
// 调取 (pull) —— 形态二:
//   - Session.Stats() SessionStats
//   - Session.Title() / Messages() / Snapshot()
//   - FileStateCache.Stats() CacheStats
//
// 同步回调 (callback) —— 形态三:
//   - engine.Config.PermissionHandler (permission.Handler)
//   - engine.Config.ApprovalPolicy
//   - engine.Config.ElicitationHandler
//   - engine.Config.AuditSink (security.AuditSink)
//   - engine.Config.Hooks (经 Manager 的 pkg/hooks.HookHandler)
package engine