package engine

// engine_ref.go - EngineRef 窄接口,替代子系统中的 *Engine 指针.
//
// 升华改进(ELEVATED): 原方案各子系统(DreamEngine,SubAgent,Session,SessionManager,
// agentExecutor)直接持有 *Engine 指针,导致:
//  1. 测试困难 -- 构造子系统必须先创建完整 Engine(40+ 字段),无法 mock
//  2. 依赖方向模糊 -- 子系统隐式依赖 Engine 的私有字段(activity,observer,rootCtx)
//
// 新方案:定义 EngineRef 接口,子系统依赖接口而非具体类型:
//   - 测试时可传入 mock
//   - 接口明确表达子系统实际需要哪些能力
//
// 例外:SpawnSubAgent 函数仍接受 *Engine(需访问 cfg,buildSystemPrompt,
// toolDefsSnapshot 等大量内部成员),DreamEngine 和 agentExecutor 在调用
// SpawnSubAgent 时做局部类型断言(见各自文件中的注释).
//
// 替代方案:<不引入接口,保持 *Engine>
// - 否决原因:无法对子系统写单元测试,且私有字段访问会随时间增生.

import "context"

// EngineRef 是各子系统对 Engine 的最小依赖接口.
//
// 只暴露子系统实际需要的能力--子系统不应通过此接口访问 Engine 的
// 工具注册,会话管理,配置等其他职责.
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
}

// 编译期断言:*Engine 实现 EngineRef.
// 若 Engine 缺少任何接口方法,此行将产生编译错误.
var _ EngineRef = (*Engine)(nil)