contract

type ApprovalCard struct {
	Tool     string     `json:"tool"`
	Action   string     `json:"action,omitempty"` // 动作名（缺省回退 Tool）
	Args     string     `json:"-"`
	ItemID   string     `json:"item_id,omitempty"`
	PlanMode bool       `json:"plan_mode,omitempty"` // plan 档计划卡（批准授权本轮全部写）
	Plan     []PlanItem `json:"plan"`
	Note     string     `json:"note,omitempty"`
	Diff     string     `json:"diff,omitempty"` // 审批卡逐行 diff 载荷——apply_patch 透传补丁原文 / repo_commit 现算 git diff；超长截断
}

type ApprovalDecision struct {
	Approve     bool
	Reason      string
	DeciderID   string
	DeciderName string
}

type ApprovalItem struct {
	ItemID   string     `json:"item_id"` // 项标识（工具挂起时生成、随保存态回放）
	Tool     string     `json:"tool"`
	Action   string     `json:"action,omitempty"`
	Plan     []PlanItem `json:"plan"`
	PlanMode bool       `json:"plan_mode,omitempty"`
	Note     string     `json:"note,omitempty"`
	Diff     string     `json:"diff,omitempty"`
	// T6 多参与者：谁的动作（同轮同 actor——顶层镜像之外的逐项署名，
	// 合并卡逐项可独立归因）。空 = 单用户零变化。
	RequesterID   string `json:"requester_id,omitempty"`
	RequesterName string `json:"requester_name,omitempty"`
}

type ApprovalReq struct {
	ApprovalID string         `json:"approval_id"`
	Tool       string         `json:"tool"`
	Action     string         `json:"action,omitempty"` // 动作名（直白话；缺省回退 tool）
	Plan       []PlanItem     `json:"plan"`
	TimeoutAt  time.Time      `json:"timeout_at"`
	PlanMode   bool           `json:"plan_mode,omitempty"` // plan 档计划卡语义（批准授权本轮全部写）
	Note       string         `json:"note,omitempty"`      // 卡面提示（如「批准后本轮后续写操作一并执行」）
	Diff       string         `json:"diff,omitempty"`      // 审批卡逐行 diff 载荷（apply_patch 补丁原文 / repo_commit git diff；超长截断）
	Items      []ApprovalItem `json:"items,omitempty"`     // 合并决议卡逐项（空 = 旧单卡形态）

	// T6 多参与者：谁的动作触发的审批（当轮说话人，回退 Owner ID——
	//「问谁」路由与审计「这条指令谁下的」的数据前提）
	RequesterID   string `json:"requester_id,omitempty"`
	RequesterName string `json:"requester_name,omitempty"`
	// T6 路由目标（Options.ApprovalRouter 裁决「问谁」；空 = 不路由——
	// 全员可见谁先点谁决议）：前端定向提示 + DecisionGuard 校验依据
	TargetID   string `json:"target_id,omitempty"`
	TargetName string `json:"target_name,omitempty"`
}

type AskCard struct {
	Question      string      `json:"question"`
	Options       []AskOption `json:"options"`
	AllowMulti    bool        `json:"allow_multi"`
	AllowFreeText bool        `json:"allow_free_text"`
}

type AskDecision struct {
	Answers     []string
	FreeText    string
	DeciderID   string // T6：谁作答（空 = 单用户零变化）
	DeciderName string
}

type AskOption struct {
	Label string `json:"label"`
	Value string `json:"value"`
}

type AskReq struct {
	AskID         string      `json:"ask_id"`
	Question      string      `json:"question"`
	Options       []AskOption `json:"options"`
	AllowMulti    bool        `json:"allow_multi,omitempty"`
	AllowFreeText bool        `json:"allow_free_text,omitempty"`
	TimeoutAt     time.Time   `json:"timeout_at"`
}

type Attachment struct {
	Name    string `json:"name"`
	Path    string `json:"path"`
	IsImage bool   `json:"is_image"`
}

type ChangeRecorder func(path, action string)

type DecisionOut struct {
	ApprovalID string            `json:"approval_id"`
	Approve    bool              `json:"approve"`
	Reason     string            `json:"reason,omitempty"`
	Items      []ItemDecisionOut `json:"items,omitempty"` // 合并决议逐项回执（空 = 旧单卡决议）

	// T6：顶层镜像（首项决议者；N=1 主形态直读）
	DeciderID   string `json:"decider_id,omitempty"`
	DeciderName string `json:"decider_name,omitempty"`
}

type Delta struct {
	Delta string `json:"delta"`
}

type DiffProvider interface {
	ApprovalDiff(args string) string
}

type ErrorOut struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

type Event struct {
	ID    int    `json:"id"`
	Event string `json:"event"`
	Data  any    `json:"data"`
	Ts    int64  `json:"ts,omitempty"` // 记录时刻墙钟毫秒（UI-B1：历史回放的时长计算源；旧数据零值=前端降级不显示）
}

type FileChange struct {
	Path   string `json:"path"`
	Action string `json:"action"` // created | edited | deleted
	Count  int    `json:"count"`
}

type HarnessNote struct {
	Kind   string `json:"kind"`             // offload（外置）| compaction（摘要压缩）
	Title  string `json:"title"`            // 单行标题（常显）
	Detail string `json:"detail,omitempty"` // 可展开内容（路径清单/全文指引）
}

type InterruptOut struct {
	Message string `json:"message"`
}

type ItemDecisionOut struct {
	ItemID  string `json:"item_id"`
	Approve bool   `json:"approve"`
	Reason  string `json:"reason,omitempty"`
	// T6 多参与者：谁决议的（空 = 单用户零变化——回放可答「谁批的」）
	DeciderID   string `json:"decider_id,omitempty"`
	DeciderName string `json:"decider_name,omitempty"`
}

type ModelChange struct {
	From string `json:"from"`
	To   string `json:"to"`
}

type OutputContract interface {
	// OutputSchema 结果 JSON Schema（object 形；nil = 只声明渲染不校验）。
	OutputSchema() *Schema
	// Render canonical 值 → 模型可见文本；空返回 = 退回原样 JSON。
	Render(args, result json.RawMessage) string
}

type Participant struct {
	ID   string `json:"id"`             // 稳定键（审计/权限/路由依据）
	Name string `json:"name,omitempty"` // 展示名（快照语义）
	Role string `json:"role,omitempty"` // 应用自定义角色
}

type ParticipantEvent struct {
	Participant Participant `json:"participant"`
	Kind        string      `json:"kind"` // joined | updated | left
}

type PlanCard struct {
	Task        string     `json:"task"` // 任务一句话
	Summary     string     `json:"summary"`
	Steps       []PlanStep `json:"steps"`
	Risks       string     `json:"risks,omitempty"`
	Seq         int        `json:"seq"`  // 文档序号（修订递增留痕）
	Path        string     `json:"path"` // 用户域相对路径 plans/<sid>/<seq>.md
	Mode        string     `json:"mode"` // 提交时档位（决议语义分叉：plan 批准=任务授权，manual 批准=仅确认方向）
	SubmittedAt time.Time  `json:"submitted_at"`
}

type PlanDecisionOut struct {
	PlanID      string `json:"plan_id"`
	Approve     bool   `json:"approve"`
	Reason      string `json:"reason,omitempty"`
	DeciderID   string `json:"decider_id,omitempty"` // T6：谁决议的（空 = 零变化）
	DeciderName string `json:"decider_name,omitempty"`
}

type PlanItem struct {
	Action  string `json:"action"`
	Summary string `json:"summary"`
	Count   int    `json:"count"`
}

type PlanReq struct {
	PlanID    string     `json:"plan_id"`
	Task      string     `json:"task"`
	Summary   string     `json:"summary"`
	Steps     []PlanStep `json:"steps"`
	Risks     string     `json:"risks,omitempty"`
	Path      string     `json:"path"` // 用户域相对路径 plans/<sid>/<seq>.md
	Seq       int        `json:"seq"`
	Mode      string     `json:"mode,omitempty"`
	TimeoutAt time.Time  `json:"timeout_at"`
}

type PlanStep struct {
	Title  string `json:"title"`
	Detail string `json:"detail,omitempty"`
}

type QueuedMsg struct {
	ID          string       `json:"id"`
	Text        string       `json:"text"`
	Attachments []Attachment `json:"attachments,omitempty"`
	Kind        string       `json:"kind,omitempty"`
	// 多参与者（T6）：谁排的队——空 = 单用户零变化（旧语义）
	SpeakerID   string `json:"speaker_id,omitempty"`
	SpeakerName string `json:"speaker_name,omitempty"`
}

type Schema struct {
	Type        string             `json:"type,omitempty"`
	Description string             `json:"description,omitempty"`
	Enum        []string           `json:"enum,omitempty"`
	Items       *Schema            `json:"items,omitempty"`
	Properties  map[string]*Schema `json:"properties,omitempty"`
	Required    []string           `json:"required,omitempty"`
	Minimum     *float64           `json:"minimum,omitempty"`
	Maximum     *float64           `json:"maximum,omitempty"`
}

type SessionEnd struct {
	Summary string       `json:"summary"`
	Files   []FileChange `json:"files,omitempty"` // 有改动才带（纯问答省缺）
	// HistLen 轮末历史长度（分叉锚定数据：ForkAt 截断重建依据；零值 = 不可
	// 锚——旧存量事件兼容）。记录时点先于本轮历史追加，值 = 追加前长度 +
	// 本轮待追加消息数（预测值即轮后精确值）。
	HistLen int `json:"hist_len,omitempty"`
}

type SteerEvent struct {
	ID          string       `json:"id"`
	Text        string       `json:"text,omitempty"`
	Attachments []Attachment `json:"attachments,omitempty"`
	Kind        string       `json:"kind,omitempty"`
	// T6 多参与者：谁排的队/谁的补充（空 = 单用户零变化）
	SpeakerID   string `json:"speaker_id,omitempty"`
	SpeakerName string `json:"speaker_name,omitempty"`
}

type SteerReorder struct {
	IDs []string `json:"ids"`
}

type SubAgentEvent struct {
	SpawnID string `json:"spawn_id,omitempty"` // 实例键（后台派生；会话域唯一）
	Agent   string `json:"agent"`              // 子代理名（spawn）
	Kind    string `json:"kind"`               // text | tool_call | tool_result | done | failed
	Text    string `json:"text,omitempty"`     // text 正文 / tool_result 摘要 / done = 结论全文（超长 spill 外置）
	Tool    string `json:"tool,omitempty"`     // 子代理调用的工具名
	Args    string `json:"args,omitempty"`     // tool_call 参数摘要
	OK      bool   `json:"ok,omitempty"`       // tool_result 成败
	// 终态细分（非终态零值）：
	StopReason string `json:"stop_reason,omitempty"` // completed | aborted | error | max_tokens
	Partial    string `json:"partial,omitempty"`     // failed 附带：终止前最后一段 assistant 输出（父模型可判补做/放弃）
}

type Suspend struct {
	Info  any
	State any
}

type Tool interface {
	// Info 工具元数据（名称/描述/参数 schema）。
	Info() *ToolInfo
	// Invoke 执行一次调用。返回值为 JSON 字节；业务性失败以 JSON 信封
	// {"ok":false,"error":…} 回喂模型自纠（Go error 会终止整轮）。
	Invoke(ctx context.Context, args json.RawMessage) (json.RawMessage, error)
}

type ToolCall struct {
	CallID     string `json:"call_id"`
	Tool       string `json:"tool"`
	ArgsDigest string `json:"args_digest"`
	Behavior   string `json:"behavior,omitempty"` // 行为面标记（ToolInfo.Behavior 快照——过程流分组数据源；空=未标记）
}

type ToolInfo struct {
	Name   string  `json:"name"`
	Desc   string  `json:"desc"`
	Params *Schema `json:"params,omitempty"` // JSON Schema（object 形）
	// Behavior 行为面标记（UI-B2：过程流「探索/更改/终端」分组的展示语义
	// 数据源；空 = 未标记——交互卡/待办类不入组，前端按工具名兜底）。
	// 与 hitl 写面名单无关：名单 = 审批语义（写才拦），本标记 = 展示语义。
	Behavior string `json:"behavior,omitempty"`
}

type ToolResult struct {
	CallID  string `json:"call_id"`
	OK      bool   `json:"ok"`
	Digest  string `json:"digest"`
	Preview string `json:"preview,omitempty"`
	Counts  string `json:"counts,omitempty"` // B4 文件变更信封 "+A -D"（写类工具结果自带；编辑卡/汇总行数据源）
	Verb    string `json:"verb,omitempty"`   // B4 信封扩展键 create|edit（新建/修改写动词——工具名判别不可分时工具方自带）
}

type TransportRetry struct {
	Attempt int `json:"attempt"` // 第几次重试（1 起）
	Max     int `json:"max"`     // 重试上限（llm.MaxRetries）
}

type UsageOut struct {
	PromptTokens     int    `json:"prompt_tokens"`
	CompletionTokens int    `json:"completion_tokens"`
	TotalTokens      int    `json:"total_tokens"`
	SpawnID          string `json:"spawn_id,omitempty"` // 子代理来源（空 = 主面）
	EstInstruction   int    `json:"est_instruction"`
	EstTools         int    `json:"est_tools"`
	EstMessages      int    `json:"est_messages"`
	EstSaved         int    `json:"est_saved,omitempty"` // 整形节省（原始-整形；0/负值省略）
}

type UserMsg struct {
	Text        string       `json:"text"`
	Attachments []Attachment `json:"attachments,omitempty"`
	// T6 多参与者：谁说的（Name = 快照；空 = 单用户零变化）
	SpeakerID   string `json:"speaker_id,omitempty"`
	SpeakerName string `json:"speaker_name,omitempty"`
}

type UserPrefs struct {
	Model  string `json:"model"`  // provider/model 复合键
	Effort string `json:"effort"` // 思考档位 off | low | high | max（旧值 on 由读侧归一 max、未知归一 low；能否真关由端点定）
	Mode   string `json:"mode"`   // 会话模式 manual | plan | auto
}