flyto

type Block struct {
	Type BlockType

	// --- TextBlock 字段 ---
	Text string

	// --- ToolUseBlock 字段(模型请求调用工具)---
	ToolUseID string
	ToolName  string
	ToolInput map[string]any

	// --- ToolResultBlock 字段(工具执行结果回传)---
	// ToolUseID 复用上方同名字段(关联请求)
	ResultText string
	IsError    bool

	// ResultBlocks carries tool_result content as an array of blocks when
	// the result includes non-text payloads (e.g. image). Populated by the
	// engine when a tool returns *tools/builtin.ImageResult via Result.Data.
	// Nil when ResultText is sufficient (plain text result). Provider
	// layer emits "content":[...] when non-nil; otherwise falls back to
	// "content":"string" using ResultText.
	//
	// Anthropic API spec (verified 2026-04-21, docs.anthropic.com): a
	// tool_result content field accepts either string or array. Array form
	// supports text + image mixed blocks so the model can ground its
	// response in the returned image.
	//
	// ResultBlocks 以 block 数组形式承载 tool_result 内容, 当结果含非文本
	// 载荷 (如图片) 时填入. 引擎在工具经 Result.Data 返回
	// *tools/builtin.ImageResult 时填. 纯文本结果 ResultText 够用时为 nil.
	// Provider 层据此决定 wire 形态: 非 nil 发 "content":[...] array,
	// 否则用 "content":"string" 字符串 (fallback 到 ResultText).
	//
	// Anthropic spec (2026-04-21 verify): tool_result content 支持 string
	// 或 array. Array 形式允许 text + image 混排, 让模型基于返回图片应答.
	ResultBlocks []Block

	// --- ThinkingBlock 字段(模型扩展思考内容)---
	ThinkingText string // 思考内容文本

	// --- ImageBlock 字段 (BlockImage 类型消息内容) ---
	// ImageSource carries image data in either base64-inline or URL form.
	// Nil for non-image blocks. Populated by engine when the user inlines
	// an image path or a tool returns image data via tools.Result.Data.
	//
	// ImageSource 携带图片数据, base64 内联或 URL 两种形式. 非图片块为 nil.
	// 用户粘贴图片路径或工具经 tools.Result.Data 返图时由引擎填入.
	ImageSource *ImageSource

	// ProviderMetadata 存储 Provider 特有的不透明数据(如签名,ID 等).
	// 引擎不解读此字段,原样回传给 Provider.
	ProviderMetadata map[string]string
}

type BlockType string

type CheckpointEvent struct {
	ToolCallID string
	ToolName   string
	Input      map[string]any
	Message    string
}

type CheckpointSuggestedEvent struct {
	ToolCallID  string         // 触发建议的工具调用 ID
	ToolName    string         // 工具名("Bash" / "FileEdit" / "FileWrite" 等)
	Input       map[string]any // 工具输入(用于消费层展示)
	RiskReason  string         // 高风险原因(英文,方便日志分析)
	RiskPattern string         // 匹配到的风险模式(如 "rm -rf" / "drop table" / "overwrite")
}

type CompactEvent struct {
	Summary      string
	TokensBefore int
	TokensAfter  int
}

type DoneEvent struct {
	TotalInputTokens  int
	TotalOutputTokens int
	TotalCostUSD      float64
	TurnCount         int
	// Reason 非空表示受控终止(如 "pre_sampling_blocked"),空字符串表示正常结束.
	Reason string
}

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
}

type EngineError struct {
	Code       ErrorCode
	Message    string
	Detail     string
	Suggestion string
	Cause      error
	Retryable  bool
}

type ErrorCode string

type ErrorEvent struct {
	Err        error
	Code       string
	Suggestion string
	Retryable  bool
}

type Event interface {
	EventType() string
}

type EventObserver interface {
	// Event 记录离散事件.
	// name 例如 "tool_result_pairing_repaired",data 是结构化上下文.
	Event(name string, data map[string]any)

	// Error 记录错误(含上下文,用于告警).
	Error(err error, context map[string]any)
}

type ImageSource struct {
	// SourceType is "base64" or "url".
	// SourceType 为 "base64" 或 "url".
	SourceType string

	// MediaType is the IANA media type (e.g. "image/png", "image/jpeg").
	// Required when SourceType is "base64".
	//
	// MediaType 是 IANA 媒体类型 (如 "image/png" / "image/jpeg"). SourceType
	// 为 "base64" 时必填.
	MediaType string

	// Data is the base64-encoded image bytes (no data-URL prefix). Required
	// when SourceType is "base64".
	//
	// Data 是图片 bytes 的 base64 编码 (不带 data-URL 前缀). SourceType 为
	// "base64" 时必填.
	Data string

	// URL points to an image served over HTTPS. Required when SourceType is
	// "url".
	//
	// URL 是 HTTPS 图片链接. SourceType 为 "url" 时必填.
	URL string
}

type InboxMessageEvent struct {
	Type      string // "progress" / "log" / "result"
	ToolUseID string
	Data      string
	Meta      string // JSON 格式的额外元数据
}

type Message struct {
	Role   Role
	Blocks []Block // 一条消息可包含多个内容块
}

type MetricObserver interface {
	// Metric 记录数值指标.
	// 例如:name="api_latency_ms", value=123.4, tags={"model":"claude-sonnet-4-6"}
	Metric(name string, value float64, tags map[string]string)
}

type ModelInfo struct {
	ID          string // API 使用的模型 ID,如 "claude-sonnet-4-6"
	DisplayName string // 展示名称,如 "Claude Sonnet 4.6"
	Provider    string // provider 标识

	ContextWindow   int // 上下文窗口(tokens)
	MaxOutputTokens int // 最大输出(tokens)

	// 定价(USD / 1M tokens,0 = 免费或未知)
	InputPricePer1M      float64
	OutputPricePer1M     float64
	CacheReadPricePer1M  float64 // 缓存读取价格(美元/百万 token)
	CacheWritePricePer1M float64 // 缓存写入价格(美元/百万 token)

	// 能力标志(provider 填写).
	// 升华改进(ELEVATED): 早期仅作展示元数据,新版同时驱动引擎自动决策--
	// SupportsCaching=true + CachingMinTokens > 0 → 引擎自动检查 system 长度并注入 cache_control(已实现,2026-04)
	// SupportsThinking=true → 消费者可用 Request.NeedsThinking 触发自动 budget 注入(已实现,2026-04)
	// 替代方案:<把所有能力逻辑放在消费者侧> - 否决:每个消费者都得手动处理阈值/header/格式差异.
	//
	// SupportsCaching 已知支持(2026-04):
	//   anthropic claude-opus-4-6 / claude-sonnet-4-6 : 1024t(官方文档)
	//   anthropic claude-haiku-4-5                    : 4096t(官方文档)
	//   minimax MiniMax-M2.7/M2.5/M2.1/M2            : 1024t(probe 实测)
	//   openrouter → anthropic 路径                   : ✗(probe 确认 cr=0@7200t)
	SupportsCaching  bool
	SupportsBatch    bool
	SupportsThinking bool
	SupportsVision   bool

	// CachingMinTokens 是触发 prompt caching 的最低系统提示 token 数.
	// 数据来源:官方文档 + 实测探测(2026-04).
	// 0 = 不支持或未知.
	//
	// 已知阈值(2026-04):
	//   anthropic claude-opus-4-6 / claude-sonnet-4-6 : 1024t(官方文档)
	//   anthropic claude-haiku-4-5                    : 4096t(官方文档;probe 确认需要 ~7200t 才触发,文档值 4096 在范围内)
	//   minimax MiniMax-M2.x                          : 1024t(probe 实测 cr=1110 @~1000t 系统提示)
	//
	// 历史包袱(LEGACY): OpenRouter 路径 cache_control 不被转发给上游后端
	// (probe 确认 cr=0@7200t),OpenRouter 路由的模型应设 SupportsCaching=false.
	CachingMinTokens int

	// MaxTools 是单次请求允许的最大工具数(0 = 未知/无限制).
	//
	// 已知值(2026-04):
	//   OpenAI Chat API  : 128(OpenAPI spec 明确记录)
	//   Anthropic strict : 20(官方文档;普通模式无明确文档上限,此处填 0)
	//   MiniMax          : 0(probe 实测 @256 未发现上限,待后续验证)
	//   OpenRouter       : 0(透传底层模型,自身无额外限制)
	//
	// 精妙之处(CLEVER): 用 0 表示"未知/不限制"而非 MaxInt--
	// 0 是 Go 零值,静态表不填此字段即表示"不限制",无需显式声明;
	// MaxInt 在各层传递时容易溢出或被误用为"极大数"参与比较运算.
	MaxTools int

	// MaxToolsExhaustive 表示 MaxTools 是否是穷尽测试得到的真上限.
	//
	// 升华改进(ELEVATED): 与 cmd/capability-probe 输出的 max_tools.exhaustive
	// schema 对应.区分两种语义:
	//   true  = MaxTools 是确认上限,provider 可硬执行(len(tools) > MaxTools 即报错)
	//   false = MaxTools 是已知下界(probe 测到这个数没出错,但没找到真上限),
	//           provider 应软处理(继续发请求让 API 自己拒),不应客户端硬拒
	//
	// 默认零值 false 是保守选择:静态表不显式填写时按"已知下界"对待,避免误伤.
	// 替代方案:<*bool 三态> - 否决:MaxTools=0 已是哨兵语义(无上限),
	// Exhaustive 仅在 MaxTools > 0 时有意义,bool 零值刚好对应"保守软处理".
	MaxToolsExhaustive bool
}

type ModelProvider interface {
	// Name 返回 provider 标识,如 "openai","ollama".
	Name() string

	// Stream 向模型发送请求,返回事件流.
	//
	// 精妙之处(CLEVER): channel 而非回调--
	// channel 天然背压(consumer 慢则 provider 等待),
	// 与 Go 的 for-range 习惯完美契合,支持 context 取消.
	//
	// provider 负责将 API 响应转换为 flyto.Event 事件序列.
	// channel 关闭表示流结束,最后一个事件为 *ErrorEvent 表示出错.
	Stream(ctx context.Context, req *Request) (<-chan Event, error)

	// Models 返回此 provider 可用的模型列表.
	// 用于模型选择 UI,合法性验证,定价展示,token 进度条等.
	Models(ctx context.Context) ([]ModelInfo, error)
}

type PermissionLearnEvent struct {
	Rules []PermissionLearnRule
}

type PermissionLearnRule struct {
	RuleString  string
	Description string
}

type PermissionRequestEvent struct {
	ID       string
	ToolName string
	Input    map[string]any
	Message  string
}

type Request struct {
	Model     string    // 模型 ID,如 "claude-sonnet-4-6"
	Messages  []Message // 对话历史(含工具调用/结果)
	System    string    // 系统提示(空 = 不使用)
	MaxTokens int       // 最大输出 token 数
	Tools     []Tool    // 可用工具列表(空 = 不使用工具)

	// ResponseFormat 约束输出格式(nil = 文本,不限制).
	// 仅 "json_object" 类型在所有主流 provider 中通用.
	// Provider 特有的 json_schema + 额外 header 通过 provider Config 配置.
	ResponseFormat *ResponseFormat

	// NeedsThinking: 消费者声明需要扩展思考(thinking 是有感知的,消费者主动声明).
	// 引擎无法判断业务复杂度,因此 thinking 必须由消费者显式开启,而非自动决策.
	// Provider 自动注入 ThinkingBudget 或 reasoning 参数.
	// 若模型不支持 thinking,silently skip(不报错).
	// 对比 Config 级别的 ThinkingBudget:Config 是全局开关,NeedsThinking 是 per-request 开关.
	NeedsThinking bool

	// FastMode 启用快速模式(影响 max_tokens 默认值 + provider 专有 beta header).
	// 仅部分 provider 支持,不支持的 provider 应忽略此字段.
	FastMode bool

	// Effort 努力级别("low"/"medium"/"high"),空字符串表示不设置.
	// 仅部分 provider 支持,不支持的 provider 应忽略此字段.
	Effort string

	// Temperature controls per-request sampling temperature. Nil = use the
	// provider/model default (do not transmit a temperature field on the
	// wire). Non-nil = use this value; each provider passes it through to
	// its native API and lets the upstream service validate (Anthropic
	// 0-1, OpenAI/Gemini/Ollama 0-2, MiniMax (0,1], OpenRouter per-model,
	// LMStudio backend-defined). Out-of-range values surface as the
	// provider's natural 4xx ErrorEvent rather than client-side clamp --
	// this matches industry consensus (Vercel AI SDK / LangChain /
	// instructor passthrough; only litellm tries drop_params and is
	// empirically buggy). One in-Request deterministic conflict gets
	// pre-handled: Anthropic + NeedsThinking + Temperature != 1.0 →
	// silent override to 1.0 + WarningEvent (server otherwise 400s).
	//
	// Temperature 控制本次请求的采样温度. nil = 用 provider/模型默认
	// (wire 上不传 temperature 字段); 非 nil = 用该值, 每个 provider 直接
	// 透传到原生 API 由上游服务校验 (Anthropic 0-1, OpenAI/Gemini/Ollama
	// 0-2, MiniMax (0,1], OpenRouter 按 model 各异, LMStudio 由 backend
	// 决定). 越界一律不在 flyto 层 clamp, 由上游 4xx 自然冒泡为
	// ErrorEvent -- 与业界共识一致 (Vercel AI SDK / LangChain /
	// instructor 全 passthrough; 只有 litellm 尝试 drop_params 且 bug
	// 频发). 仅一个 wire 时已知冲突预拦: Anthropic + NeedsThinking +
	// Temperature != 1.0 → silent override 1.0 + WarningEvent (否则
	// 服务端 400).
	//
	// CLEVER: nullable *float64 而非 float64 + sentinel -- Go 零值 0
	// 在采样语义里是合法的 deterministic, 不能复用作 "未设". helper
	// flyto.Float() 简化指针字段构造.
	Temperature *float64

	// TopP controls nucleus sampling cutoff (1.0 = disabled). Nil = use
	// the provider/model default. Non-nil = use this value; same
	// passthrough policy as Temperature -- upstream validates, out-of-range
	// surfaces as 4xx ErrorEvent. One pre-handled conflict: Anthropic +
	// NeedsThinking restricts top_p to [0.95, 1.0]; values below 0.95
	// silent-override to 1.0 + WarningEvent.
	//
	// TopP 控制 nucleus 采样阈值 (1.0 = 不启用). nil = 用 provider/
	// 模型默认; 非 nil = 用该值. 与 Temperature 同 passthrough 策略,
	// 上游校验, 越界 4xx 自然冒泡. 仅一个预拦特例: Anthropic +
	// NeedsThinking 限制 top_p 在 [0.95, 1.0], 低于 0.95 silent override
	// 1.0 + WarningEvent.
	TopP *float64

	// SystemBlocks 分段系统提示词(支持 per-block 缓存策略).
	// 如果非 nil 且非空,Provider 应优先使用此字段而非 System string.
	// 每个 block 有 Text 和 CacheScope 字段.
	SystemBlocks []SystemBlock

	// Capabilities 是本次请求关联的模型能力快照(由 engine 在调用 provider 之前注入).
	//
	// 升华改进(ELEVATED): data-driven-capabilities RFC 的核心机制--
	// engine 每次调用 provider.Stream 之前从 ModelRegistry 取出当前模型的 ModelInfo,
	// 塞进这个字段.Provider 优先读取这里的字段(registry 数据驱动),
	// 缺失时降级到 provider 包内的硬编码常量(向后兼容兜底).
	//
	// 设计要点:
	//  - nil = engine 未注入(单元测试 / mock 场景 / model 不在 registry 中),
	//    provider 必须降级到包内常量,行为完全等同于现状(零回归)
	//  - 非 nil = engine 已注入快照,provider 优先使用此字段
	//  - 这是只读快照--provider 不应修改它的字段,registry 后续修改也不影响
	//    进行中的请求(值的指针,但 ModelInfo 字段都是值类型)
	//
	// 替代方案:<provider 持有 ModelRegistry 引用> - 否决:
	// 会让 provider 包 import config 包,引入依赖循环风险;
	// 而 Request 字段注入让 provider 完全无感知 registry 的存在.
	// 替代方案:<让 engine 全部预先解析完成后只传 maxTools/supportsThinking 等扁平字段> - 否决:
	// flyto.Request 字段会膨胀,且每加一个能力都要改 Request schema.
	Capabilities *ModelInfo
}

type ResponseFormat struct {
	// Type 是格式类型:
	//   "json_object" - 约束输出为合法 JSON 对象(所有主流 provider 支持)
	//   "json_schema" - 按指定 schema 约束(OpenAI/OpenRouter/MiniMax 原生支持;
	//                    不支持的 provider 降级为 fence strip,不传 schema)
	Type string

	// JSONSchema 是 json_schema 类型的 schema 定义(json_schema 时必填,其他类型忽略)
	JSONSchema json.RawMessage `json:"json_schema,omitempty"`
}

type Role string

type RunOption interface {
	// contains filtered or unexported methods
}

type SessionInfoEvent struct {
	SessionID    string
	Title        string
	TurnCount    int
	InputTokens  int
	OutputTokens int
	CostUSD      float64
}

type SlashCommandEvent struct {
	Name string
	Args string
}

type SystemBlock struct {
	Text       string // 文本内容
	CacheScope string // "", "session", "global" - 非空表示需要缓存
}

type TeammateMessageReceivedEvent struct {
	From        string // 发送方 agent 名称
	To          string // 接收方 agent 名称 (自己)
	Type        string // Message.Type (task_assignment / idle_notification 等)
	MessageID   string // Message.ID
	PayloadSize int    // payload 字节数
}

type TextDeltaEvent struct {
	Text string
}

type TextEvent struct {
	Text string
}

type ThinkingDeltaEvent struct {
	Text string
}

type ThinkingEvent struct {
	Text string
}

type Tool struct {
	Name        string          // 工具名称,如 "Bash"
	Description string          // 工具描述(给模型看的自然语言说明)
	InputSchema json.RawMessage // 输入参数的 JSON Schema(object 类型)
}

type ToolProgressEvent struct {
	ID       string
	ToolName string
	Progress float64 // 0.0-1.0
	Detail   string
}

type ToolResultEvent struct {
	ID       string // 对应 ToolUseEvent.ID
	ToolName string
	Output   string
	IsError  bool

	// Truncated marks that Output is a short summary and the full tool
	// result has been persisted to StoredPath. Consumer UIs use this to
	// render "result truncated -- click to open full content".
	//
	// Truncated 标记 Output 是短摘要, 完整结果已经落盘到 StoredPath. 消费层
	// UI 据此渲染 "结果已截断 -- 点击打开完整内容".
	Truncated bool

	// StoredPath is where the full tool result was persisted (by the
	// orchestrator's pluggable ResultProcessor). Empty when Truncated is
	// false. Path shape is consumer-layer defined (local filesystem path,
	// sandbox-internal path, object-storage key, ...); callers parse per
	// the ResultProcessor they installed.
	//
	// SECURITY: the path may carry sandbox-internal structure or caller-
	// specific details. Downstream observers / SSE bridges MUST treat it
	// as untrusted data (e.g. avoid logging to shared destinations without
	// review).
	//
	// StoredPath 是完整工具结果的持久化位置 (由 orchestrator 的可插拔
	// ResultProcessor 决定). Truncated=false 时为空串. Path shape 由消费层
	// 定义 (本地文件路径 / sandbox 内部路径 / 对象存储 key / ...); 调用方按
	// 自己装的 ResultProcessor 解析.
	//
	// 安全: path 可能携带 sandbox 内部结构或调用方特定细节. 下游 observer /
	// SSE bridge 必须把它当作不可信数据 (例如未审查前不写入共享目的地).
	StoredPath string
}

type ToolSummaryEvent struct {
	ID       string
	ToolName string
	Summary  string // 5-20 字
}

type ToolUseEvent struct {
	ID       string         // 工具调用 ID
	ToolName string         // 工具名称
	Input    map[string]any // 工具输入参数
}

type TraceObserver interface {
	SpanStart(name string, tags map[string]string) string // 返回 span ID
	SpanEnd(spanID string, err error)
}

type TurnEndEvent struct {
	TurnNumber   int
	InputTokens  int
	OutputTokens int
	CostUSD      float64
	MaxTokens    int
}

type TurnStartEvent struct {
	TurnNumber          int
	Model               string
	ContextWindowTokens int // 由 provider.Models() 提供,消费层无需硬编码
}

type UsageEvent struct {
	InputTokens         int
	OutputTokens        int
	CacheReadTokens     int    // prompt caching 命中的 token 数(仅支持缓存的 provider)
	CacheCreationTokens int    // prompt caching 写入的 token 数(仅支持缓存的 provider)
	StopReason          string // "end_turn"/"max_tokens"/"tool_use"/"stop_sequence"/"length"
}

type WarningEvent struct {
	Code    string
	Message string
	Detail  string
}