package loop

import (
	"context"

	"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/model"
)

// 本文件实现「回合内转向注入」（design/15 §2.0/§2.4，裁决 13.4.5 目标态）。
//
// 不变量按 design/15 §2.0 实现，语义不在循环里自创：
//
//   - **I1（同会话在途回合数恒为 1）**：转向只在**同一回合的边界**注入，绝不取消
//     当前回合、也绝不新开第二个回合。循环对这一点的保证是结构性的——它没有任何
//     「起新回合」的分支，注入只是把消息并进当前回合下一次模型调用的视图。
//   - **I2（消息恰好被处理一次）**：注入＝已消费。循环看不到消息 id
//     （model.Message 没有 id 字段），因此「按 created_at + id 去重」与「从待处理
//     队列移除」都归 SteerSource 的实现方（网关会话编排器，它同时持有转录与
//     pending 队列）。循环只保证同一个边界只问一次、按返回顺序追加。
//   - **I3（转向不取消已发起的工具）**：注入点只在**回合内边界**——一次模型步结束
//     与它那一批工具调用结束**之后**、下一次模型调用**之前**。此刻没有任何工具在
//     飞，因此注入不可能取消任何已发起的工具；正在执行的工具永远跑完（与 Cline
//     PR #13958「只打断在飞的模型请求、工具与整轮继续」同口径）。
//
// 为什么注入只进**本轮视图**而不写回运行窗口：写回会让注入内容进入 checkpoint
// 快照与后台记忆提取的输入面（两者都读该回合的 msgs），而它们本应只看到该回合真正
// 的输入与工具结果。注入在每一步重新并入视图，因此对模型而言它仍是**同一个窗口**
// （一致性＝同一窗口，design/15 §2.4），只是不落盘、不出现在记忆面。

// SteerRequest 是循环在回合内边界向 SteerSource 发起的一次「重读转录」请求。
type SteerRequest struct {
	// SessionID 是本次 Run 驱动的会话。
	SessionID string
	// Step 是**即将开始**的模型步序号（从 1 开始）：被返回的消息会出现在该步的
	// 模型可见视图里，因此它就是网关 `steer_ack` 帧上报的 `atStep`。
	Step int
}

// SteerSource 由调用方（网关会话编排器）提供，在指定的回合内边界重读该会话转录，
// 返回「本回合开始后新到、且尚未被本回合吃进」的用户消息，供循环追加进本轮视图。
// 返回空切片表示本次边界没有可注入的消息，是正常情形而非错误。
//
// 实现方负责去重与「已消费」口径（见文件头 I2）：循环按返回顺序原样追加，不做也
// 无法做 id 去重。它必须是非阻塞的——它在 Run 路径上被调用；网络/存储读取有界，
// 读失败时返回空（该消息留在待处理队列，照旧作为自己的回合被回答，绝不静默丢失）。
type SteerSource interface {
	Steer(ctx context.Context, req SteerRequest) []model.Message
}

// steerSourceKey 是回合内转向源的 context key。
type steerSourceKey struct{}

// WithSteerSource 把转向源挂到 ctx 上，使本次 Run 的每个回合内边界都能重读转录并
// 注入新到的用户消息（design/15 §2.4）。调用方（网关编排器）在**每个回合启动之前**
// 挂一份新的源：转向游标是按回合的状态，跨回合复用会让上一个回合已吃进的消息被
// 过滤掉或重复注入。
//
// nil 源是空操作，ctx 原样返回——未接线的调用方（子代理、后台思考、未接网关的循环）
// 行为逐字不变。
func WithSteerSource(ctx context.Context, src SteerSource) context.Context {
	if ctx == nil || src == nil {
		return ctx
	}
	return context.WithValue(ctx, steerSourceKey{}, src)
}

// SteerSourceFrom 返回 ctx 上挂的转向源，未挂载时为 nil。它是 WithSteerSource 的
// 读侧，供拿到 context 的调用方（网关测试、断言注入边界的实现）观察本次 Run 的
// 注入能力；nil 表示本次运行不做任何转向注入。
func SteerSourceFrom(ctx context.Context) SteerSource {
	if ctx == nil {
		return nil
	}
	src, _ := ctx.Value(steerSourceKey{}).(SteerSource)
	return src
}

// steerAtBoundary 在一个回合内边界重读该会话转录，并把新到的用户消息合并进本回合
// 已注入列表。未接线转向源、ctx 已取消、或本次边界无新消息时，它原样返回 steered
// （无新消息是常态：工具批次之间通常没有用户插话）。
//
// 它绝不返回错误：转向是增益，任何一个边界的读取失败都不该让用户已经在跑的回合
// 失败——失败时返回空（见 SteerSource 契约），该消息留在待处理队列里等下一个回合。
func (l *Loop) steerAtBoundary(ctx context.Context, sessionID string, step int, steered []model.Message) []model.Message {
	src := SteerSourceFrom(ctx)
	if src == nil || ctx.Err() != nil {
		return steered
	}
	msgs := src.Steer(ctx, SteerRequest{SessionID: sessionID, Step: step})
	if len(msgs) == 0 {
		return steered
	}
	// 注入的图片消息走与回合开始处同一条视觉改写（design/06 §0）：否则一条中途
	// 注入的图片会绕过 resolver，直接落到不支持视觉的主模型面前。
	msgs = l.resolveImages(ctx, msgs)
	// 链路图如实标记「本轮输入被中途追加过」（design/15 §5）。子代理 Run 不拥有
	// 自己的图（它的 span 并入派生它的会话），因此分支 Run 不打这个标记。
	if _, isBranch := flowBranch(ctx); !isBranch {
		l.flow.MarkInputSteered(sessionID)
	}
	l.log.Info("steer injected", "session", sessionID, "step", step, "messages", len(msgs))
	return append(steered, msgs...)
}