package flyto

import "context"

// engine.go - 引擎接口(消费者编程的目标).
//
// 消费者 import pkg/flyto,通过 Engine 接口驱动对话,
// 无需了解 pkg/engine 的内部实现细节.
// 测试时可 mock 此接口,无需启动真实引擎.

// Engine 是 Flyto Agent 引擎的公共接口.
//
// Shape: push (stream entry). Engine.Run returns `<-chan Event` that
// consumers range + type-switch on. Close is a pull-side lifecycle call.
//
// 形态: 订阅 (流入口). Engine.Run 返回 `<-chan Event`, 消费者 range +
// type-switch 处理. Close 是 pull 侧生命周期调用.
type Engine interface {
	// Run 在指定会话中执行一轮对话,返回事件流.
	//
	// messages 是本轮输入(用户消息 + 工具结果等).
	// 事件流关闭表示本轮结束,最后一个 *DoneEvent 或 *ErrorEvent 说明结束原因.
	//
	// 精妙之处(CLEVER): 返回 <-chan Event 而非 error--
	// 错误通过 *ErrorEvent 在流中传递,消费者用统一的 for-range 处理所有情况,
	// 不需要双返回值(err + channel)的尴尬.
	Run(ctx context.Context, sessionID string, messages []Message, opts ...RunOption) <-chan Event

	// Close 停止引擎,释放所有资源(goroutine,连接,文件句柄).
	// 幂等:多次调用安全.
	Close() error
}

// RunOption 是单次 Run 调用的选项(不透明类型).
//
// 精妙之处(CLEVER): interface 而非 func(*runConfig)--
// 外部包无法实现此接口(unexported method),只能使用引擎提供的 WithXxx 工厂函数.
// 这样引擎能在不破坏 API 的前提下修改内部 runConfig 结构.
type RunOption interface {
	applyRunOption() // 故意 unexported,防止外部实现
}