types

type AgentEvent struct {
	ID     int64 `json:"id,string"`
	TaskID int64 `json:"task_id,string"`
	// UserID / SessionID 是事件的推送路由与归属信息：由服务层从 TaskFacts 填充，
	// 传输层（WS / SSE）据此决定推给谁，不需要再维护 taskID → userID 的映射表，
	// 也不需要按任务逐个订阅。
	//
	// UserID 为 0 表示无登录用户（后台任务 / 系统摘要），不应推送给任何客户端。
	UserID    int64          `json:"user_id,string,omitempty"`
	SessionID int64          `json:"session_id,string,omitempty"`
	Type      AgentEventType `json:"type"`
	Payload   any            `json:"payload,omitempty"`
	CreatedAt time.Time      `json:"created_at"`
}

type AgentEventType string

type AskUserAnswer struct {
	RequestID   string           `json:"request_id,omitempty"`
	Answers     []QuestionAnswer `json:"answers"`
	AnsweredIDs []string         `json:"answered_ids,omitempty"` // 本次已作答的问题 ID（用于逐题提交合并）
}

type AskUserInput struct {
	RequestID   string     `json:"request_id,omitempty"`  // 模型侧请求 ID（可选，用于回填）
	Title       string     `json:"title,omitempty"`       // 提问卡片标题
	Description string     `json:"description,omitempty"` // 补充说明
	Questions   []Question `json:"questions"`             // 需要用户回答的问题列表
}

type ContextConfig struct {
	InjectMemory bool `json:"inject_memory"`
}

type EventHandler func(ctx context.Context, event AgentEvent) error

type File struct {
	ID        int64     `json:"id,string" gorm:"column:id;primaryKey;type:bigint;autoIncrement:false"`
	SessionID int64     `json:"session_id,string" gorm:"column:session_id;type:bigint;index:idx_history_session_path,priority:1"`
	Path      string    `` /* 145-byte string literal not displayed */
	Content   string    `json:"content" gorm:"column:content;type:longtext"`
	Version   string    `json:"version" gorm:"column:version;type:varchar(64);uniqueIndex:uk_history_session_path_version,priority:3"`
	CreatedAt time.Time `json:"created_at" gorm:"column:created_at"`
	UpdatedAt time.Time `json:"updated_at" gorm:"column:updated_at"`
}

type Memory struct {
	ID        int64      `json:"id,string" gorm:"column:id;primaryKey;type:bigint;autoIncrement:false"`
	UserID    int64      `json:"user_id,string" gorm:"column:user_id;type:bigint;index:idx_agent_memories_user_kind,priority:1"`
	ProjectID int64      `json:"project_id,omitempty,string" gorm:"column:project_id;type:bigint;index"`
	SessionID int64      `json:"session_id,omitempty,string" gorm:"column:session_id;type:bigint;index"`
	Kind      MemoryKind `json:"kind" gorm:"column:kind;type:varchar(32);index:idx_agent_memories_user_kind,priority:2"`
	// Content 可能是整段会话 / 任务摘要或长事实，64KB 的 text 会触发 1406，这里用 longtext。
	Content string `json:"content" gorm:"column:content;type:longtext"`

	// Importance 表示记忆重要度（0-10），检索排序时权重更高。
	Importance int `json:"importance" gorm:"column:importance"`
	// Metadata 承载扩展信息（来源、标签等），由序列化为 JSON 持久化。
	Metadata map[string]any `json:"metadata,omitempty" gorm:"column:metadata;serializer:json"`

	CreatedAt      time.Time  `json:"created_at" gorm:"column:created_at"`
	UpdatedAt      time.Time  `json:"updated_at" gorm:"column:updated_at"`
	LastAccessedAt *time.Time `json:"last_accessed_at,omitempty" gorm:"column:last_accessed_at"`
}

type MemoryExtractor interface {
	Extract(ctx context.Context, turn MemoryTurn) ([]*Memory, error)
}

type MemoryExtractorFunc func(ctx context.Context, turn MemoryTurn) ([]*Memory, error)

type MemoryKind string

type MemoryQuery struct {
	UserID    int64
	ProjectID int64
	SessionID int64
	// Text 是检索关键词；为空时退化为「按上下文 + 更新时间」的分页读取。
	Text  string
	Limit int
}

type MemoryTurn struct {
	UserID    int64
	ProjectID int64
	SessionID int64
	Request   Request
	Result    *Result
}

type Message struct {
	ID        int64  `json:"id,string" gorm:"column:id;primaryKey;type:bigint;autoIncrement:false"`
	SessionID int64  `json:"session_id,string" gorm:"column:session_id;type:bigint;index"`
	Seq       int    `json:"seq" gorm:"column:seq;index"`
	Role      string `json:"role" gorm:"column:role;type:varchar(32)"`
	Kind      string `json:"kind,omitempty" gorm:"column:kind;type:varchar(32);index"`
	TaskID    int64  `json:"task_id,string,omitempty" gorm:"column:task_id;type:bigint;index"`
	// Content 可能包含完整工具输出 / 长回复，64KB 的 text 会触发 1406，这里用 longtext。
	Content   string    `json:"content,omitempty" gorm:"column:content;type:longtext"`
	Data      any       `json:"data,omitempty" gorm:"serializer:json"`
	CreatedAt time.Time `json:"created_at" gorm:"column:created_at"`
}

type MessageBlock struct {
	ID        string     `json:"id"`                // messageId
	TurnID    string     `json:"turn_id,omitempty"` // 所属 turn
	Content   string     `json:"content"`
	ToolCalls []ToolCall `json:"tool_calls,omitempty"`
}

type MessageCreateParams struct {
	SessionID int64
	Role      string
	Kind      string
	TaskID    int64
	Content   string
	Data      any
}

type Operation struct {
	ID   string        `json:"id,omitempty"`
	Type OperationType `json:"type"`

	// read / write / delete / move
	Path string `json:"path,omitempty"`
	// write
	Content string `json:"content,omitempty"`
	// execute
	Command string `json:"command,omitempty"`

	// Description 是人类可读的操作摘要（如 "Execute command: ls -la" /
	// "Replace content in file /a/b.go"）。Provider 有更精确的描述时填入，
	// 供 UI 在批准前展示；为空时前端回退到 Path / Command / Content。
	Description string `json:"description,omitempty"`

	// Metadata 承载操作相关的扩展信息（如命令参数、网络地址等）。
	Metadata map[string]any `json:"metadata,omitempty"`
}

type OperationType = coretypes.OperationType

type PermissionDecision = coretypes.PermissionDecision

type PermissionRequest struct {
	ID        int64            `json:"id,string" gorm:"column:id;primaryKey;type:bigint;autoIncrement:false"`
	TaskID    int64            `json:"task_id,string" gorm:"column:task_id;type:bigint;index"`
	SessionID string           `json:"session_id,omitempty" gorm:"column:session_id;type:varchar(64)"`
	Operation Operation        `json:"operation" gorm:"serializer:json"`
	Status    PermissionStatus `json:"status" gorm:"column:status;type:varchar(32);index"`

	CreatedAt  time.Time  `json:"created_at" gorm:"column:created_at"`
	UpdatedAt  time.Time  `json:"updated_at" gorm:"column:updated_at"`
	ResolvedAt *time.Time `json:"resolved_at,omitempty" gorm:"column:resolved_at"`
	ResolvedBy *int64     `json:"resolved_by,string,omitempty" gorm:"column:resolved_by;type:bigint"`
}

type PermissionStatus string

type Profile struct {
	ID int64 `json:"id,string" gorm:"column:id;primaryKey;type:bigint;autoIncrement:false"`
	// Name 仅作为展示名使用，不参与任何查询。
	Name         string `json:"name" gorm:"column:name;type:varchar(128)"`
	Description  string `json:"description" gorm:"column:description;type:text"`
	IsDefault    bool   `json:"is_default" gorm:"column:is_default"`
	IsBuiltin    bool   `json:"is_builtin" gorm:"column:is_builtin"`
	SystemPrompt string `json:"system_prompt" gorm:"column:system_prompt;type:text"`
	// Model 指定本 Profile 使用的模型名（对应 config.agent.providers 的 key）。
	// 为空时回退到请求级 req.Model（若仍未指定则由 Provider 兜底）。
	Model string `json:"model" gorm:"column:model;type:varchar(128)"`
	// Provider 指定本 Profile 使用的 Agent（Provider）名称（mock | claude_code | codex | copilot | custom）。
	// 为空时回退到请求级 req.Provider（若仍未指定则由 Client 的默认 Provider 兜底）。
	Provider string        `json:"provider" gorm:"column:provider;type:varchar(64)"`
	Skills   []string      `json:"skills" gorm:"column:skills;serializer:json"`
	Context  ContextConfig `json:"context" gorm:"column:context;serializer:json"`

	CreatedAt time.Time `json:"created_at" gorm:"column:created_at"`
	UpdatedAt time.Time `json:"updated_at" gorm:"column:updated_at"`
}

type Question struct {
	ID          string           `json:"id"`                     // 问题标识（答案按此 ID 回填）
	Type        string           `json:"type"`                   // single_choice / multiple_choice / text
	Title       string           `json:"title"`                  // 问题文本
	Description string           `json:"description,omitempty"`  // 问题补充说明
	Required    bool             `json:"required,omitempty"`     // 是否必答
	Options     []QuestionOption `json:"options,omitempty"`      // 选项（choice 类型）
	AllowCustom bool             `json:"allow_custom,omitempty"` // 是否允许自定义输入
	Placeholder string           `json:"placeholder,omitempty"`  // 自定义 / 文本输入的占位提示
}

type QuestionAnswer struct {
	ID     string   `json:"id"`
	Value  string   `json:"value,omitempty"`
	Values []string `json:"values,omitempty"`
	Custom string   `json:"custom,omitempty"`
}

type QuestionOption struct {
	Label       string `json:"label"`                 // 展示文案
	Value       string `json:"value"`                 // 提交值
	Description string `json:"description,omitempty"` // 选项说明
}

type QuestionRequest struct {
	ID        int64  `json:"id,string" gorm:"column:id;primaryKey;type:bigint;autoIncrement:false"`
	TaskID    int64  `json:"task_id,string" gorm:"column:task_id;type:bigint;index"`
	SessionID string `json:"session_id,omitempty" gorm:"column:session_id;type:varchar(64)"`
	// ToolCallID 是发起本次提问的工具调用 ID（ask_user）。
	// 重启后据此把“已作答的提问”与待重放的 ask_user 调用精确配对，避免重复创建提问。
	ToolCallID  string         `json:"tool_call_id,omitempty" gorm:"column:tool_call_id;type:varchar(128);index"`
	RequestID   string         `json:"request_id,omitempty" gorm:"column:request_id;type:varchar(64)"`
	Title       string         `json:"title,omitempty" gorm:"column:title;type:text"`
	Description string         `json:"description,omitempty" gorm:"column:description;type:text"`
	Questions   []Question     `json:"questions" gorm:"serializer:json"`
	Status      QuestionStatus `json:"status" gorm:"column:status;type:varchar(32);index"`
	Answer      *AskUserAnswer `json:"answer,omitempty" gorm:"serializer:json"`

	CreatedAt  time.Time  `json:"created_at" gorm:"column:created_at"`
	UpdatedAt  time.Time  `json:"updated_at" gorm:"column:updated_at"`
	ResolvedAt *time.Time `json:"resolved_at,omitempty" gorm:"column:resolved_at"`
	ResolvedBy *int64     `json:"resolved_by,string,omitempty" gorm:"column:resolved_by;type:bigint"`
}

type QuestionStatus string

type ReasoningBlock struct {
	ID      string `json:"id"`      // reasoningId
	Content string `json:"content"` // 完整思考文本
}

type Request struct {
	// Provider 可选：强制指定 Provider 名称；为空则使用 Client 的默认 Provider。
	Provider string `json:"provider"`
	// ModelID 可选：模型标识（对应 config.agent.providers 的 key），为空时由 Provider 自行决定。
	ModelID string `json:"model_id"`
	// ProfileID 可选：AgentProfile ID，AgentService 据此解析系统提示词、技能与上下文注入开关。
	ProfileID int64 `json:"profile_id,omitempty,string"`
	// Skills 可选：本次调用启用的技能名列表；为空表示使用默认全部技能。
	Skills []string `json:"skills,omitempty"`
	// RuntimeContext 是本轮调用的业务上下文（业务类型 / 模板变量）。
	//
	// 由 HTTP Handler 的 RuntimeContextResolver 解析 env(type,id) 产出，随请求一路传到
	// 配置了工具的 Provider；Provider 在每次调用时把它注入工具执行上下文，供
	// builtin 工具（如 run_analysis_node）在执行期读取 SystemPromptVars。
	//
	// 它只承载业务事实；「谁在执行」（任务 / 会话 / 用户 / 项目）由 Task 与 TaskFacts
	// 承载，经 Runtime 注入工具 ctx（见 tool.WithTaskFacts）。它随 Request 一起被 JSON
	// 序列化进 agent_tasks.request（gorm serializer:json），因此任务从 DB 恢复后依然可用。
	RuntimeContext *runtimecontext.RuntimeContext `json:"runtime_context,omitempty"`
	// SystemPrompt 是最终发送给 Provider 的系统提示词（仅运行时使用）。
	//
	// 它是派生值：AgentService 依据 Profile.SystemPrompt 模板 +
	// RuntimeContext.SystemPromptVars 在 run 时渲染后写入（见 applyProfile），
	// Provider 只读该字段。因此不随 Request 持久化（json:"-"）：
	// 任务恢复时会按 Profile 重新渲染，避免把过期快照写进 agent_tasks.request。
	SystemPrompt string `json:"-"`
	// Messages 对话上下文（不含 SystemPrompt）。
	Messages []Message `json:"messages"`
	// Env 可选：额外环境变量（也可携带 Provider 特有开关）。
	Env map[string]string `json:"env"`
	// MaxTokens 可选：最大输出 token 数，0 表示不限制。
	MaxTokens int `json:"max_tokens"`
	// Stream 可选：任务模式下是否使用流式调用；默认 false 使用 Invoke。
	Stream bool `json:"stream"`
	// Timeout 可选：单次调用超时，0 表示不限制。
	Timeout time.Duration `json:"-"`
}

type Result struct {
	// TaskID 本次调用对应的 Agent 任务 ID（agent_tasks 表），仅任务模式（RunTaskSync）下返回。
	TaskID  int64           `json:"task_id,string,omitempty"`
	Content string          `json:"content"`
	Usage   Usage           `json:"usage"`
	Raw     json.RawMessage `json:"raw,omitempty"` // Provider 原始返回，便于调试与扩展
}

type ResumeMessage struct {
	Role        string             `json:"role"`
	Content     string             `json:"content,omitempty"`
	ToolCalls   []ResumeToolCall   `json:"tool_calls,omitempty"`
	ToolResults []ResumeToolResult `json:"tool_results,omitempty"`
}

type ResumeToolCall struct {
	ID    string `json:"id"`
	Name  string `json:"name"`
	Input string `json:"input,omitempty"` // JSON 参数
}

type ResumeToolResult struct {
	ToolCallID string `json:"tool_call_id"`
	Content    string `json:"content,omitempty"`
	IsError    bool   `json:"is_error,omitempty"`
}

type ResumeTurn struct {
	Assistant ResumeMessage      `json:"assistant"`
	Completed []ResumeToolResult `json:"completed,omitempty"`
}

type Session struct {
	ID int64 `json:"id,string" gorm:"column:id;primaryKey;type:bigint;autoIncrement:false"`
	// ProjectID 是会话所属项目（创建时取用户当前激活项目），会话列表按项目隔离。
	ProjectID int64 `json:"project_id,string" gorm:"column:project_id;type:bigint;index"`
	// ParentSessionID 指向父会话（如子任务会话 / 标题生成会话），0 表示顶层会话。
	ParentSessionID int64  `json:"parent_session_id,string" gorm:"column:parent_session_id;type:bigint;index"`
	Title           string `json:"title" gorm:"column:title;type:varchar(255)"`
	UserID          int64  `json:"user_id,string" gorm:"column:user_id;type:bigint;index"`
	Provider        string `json:"provider" gorm:"column:provider;type:varchar(64)"`
	Model           string `json:"model" gorm:"column:model;type:varchar(128)"`
	// CurrentTaskID 记录当前活跃轮次（running / waiting_permission）的任务 ID；
	// 轮次正常结束时置空。failed 但仍有检查点（可续跑）的任务会保留该指针，
	// 供前端刷新 / 切换会话时展示「Continue」并从 /agent/task/resume 恢复执行。
	CurrentTaskID int64     `json:"current_task_id,string" gorm:"column:current_task_id;type:bigint"`
	CreatedAt     time.Time `json:"created_at" gorm:"column:created_at"`
	UpdatedAt     time.Time `json:"updated_at" gorm:"column:updated_at"`
}

type SessionChildParams struct {
	// ProjectID 是会话所属项目；通常与父会话保持一致。
	ProjectID int64
	// ParentSessionID 是父会话 ID，必须 > 0。
	ParentSessionID int64
	Title           string
	UserID          int64
	Provider        string
	Model           string
}

type SessionCreateParams struct {
	// ID 可选：指定会话主键（如 CreateTaskSession 以 toolCallID 作为会话 ID）；
	// 为 0 时由 BeforeCreate 分配雪花 ID。
	ID int64
	// ProjectID 是会话所属项目；0 表示未归属项目。
	ProjectID       int64
	ParentSessionID int64
	Title           string
	UserID          int64
	Provider        string
	Model           string
}

type SessionListParams struct {
	UserID int64 // 0 表示全部用户
	// ProjectID 限定只返回该项目的会话；0 表示不按项目过滤。
	ProjectID int64
	Offset    int
	Limit     int
}

type StreamEvent struct {
	Type    StreamEventType `json:"type"`
	Content string          `json:"content,omitempty"` // 仅增量事件使用
	Data    any             `json:"data,omitempty"`    // 完整块的结构化数据（reasoning/message/tool_call/turn）
	Err     error           `json:"-"`                 // 仅当 Type == StreamEventError 时有效
}

type StreamEventType string

type StreamHandler func(ctx context.Context, event StreamEvent) error

type Task struct {
	ID        int64 `json:"id,string" gorm:"column:id;primaryKey;type:bigint;autoIncrement:false"`
	SessionID int64 `json:"session_id,string,omitempty" gorm:"column:session_id;type:bigint;index"`
	// ProjectID 是任务所属项目（创建时由调用方提供），0 表示未知。
	ProjectID int64 `json:"project_id,string,omitempty" gorm:"column:project_id;type:bigint;index"`
	// UserID 是任务归属用户（0 表示后台任务 / 无登录用户）。
	UserID     int64      `json:"user_id,string,omitempty" gorm:"column:user_id;type:bigint;index"`
	Provider   string     `json:"provider" gorm:"column:provider;type:varchar(64)"`
	Model      string     `json:"model,omitempty" gorm:"column:model;type:varchar(128)"`
	Status     TaskStatus `json:"status" gorm:"column:status;type:varchar(32);index"`
	WorkingDir string     `json:"working_dir,omitempty" gorm:"column:working_dir;type:text"`

	// Request 保存原始请求，用于恢复时重建上下文。
	Request Request `json:"request,omitempty" gorm:"serializer:json"`
	// ResumeState 是可恢复执行检查点（Agent 循环的对话历史 / 待执行工具调用）。
	// 为空表示该任务不可续跑（例如 Provider 未实现检查点，或任务从未开始执行）。
	// 该列只由 TaskRepository.UpdateResumeState 维护，普通 Update 会显式 Omit，
	// 避免内存中的旧 Task 快照在状态迁移时把检查点覆盖成 NULL。
	ResumeState *TaskResumeState `json:"-" gorm:"column:resume_state;type:longtext;serializer:json"`
	// Resumable 是非持久化派生字段：只要存在检查点就可以被手动 / 自动恢复。
	Resumable bool `json:"resumable" gorm:"-"`
	// Error 保存最近一次错误信息（Status == failed 时有效）。
	Error string `json:"error,omitempty" gorm:"column:error;type:text"`

	CreatedAt  time.Time  `json:"created_at" gorm:"column:created_at"`
	UpdatedAt  time.Time  `json:"updated_at" gorm:"column:updated_at"`
	StartedAt  *time.Time `json:"started_at,omitempty" gorm:"column:started_at"`
	FinishedAt *time.Time `json:"finished_at,omitempty" gorm:"column:finished_at"`
}

type TaskFacts struct {
	TaskID     int64
	SessionID  int64
	ProjectID  int64
	UserID     int64
	WorkingDir string
}

type TaskFinishedHandler func(ctx context.Context, task *Task)

type TaskResumeState struct {
	Version  int             `json:"version"`
	Provider string          `json:"provider,omitempty"`
	Model    string          `json:"model,omitempty"`
	History  []ResumeMessage `json:"history,omitempty"`
	// Pending 非空表示上一轮模型响应已落库、但工具调用尚未全部完成。
	Pending *ResumeTurn `json:"pending,omitempty"`
	// UpdatedAt 便于排查恢复时的检查点新旧。
	UpdatedAt time.Time `json:"updated_at"`
}

type TaskStatus string

type ToolCall struct {
	ID        string `json:"id"`   // toolCallId
	Name      string `json:"name"` // 工具名
	Arguments any    `json:"arguments,omitempty"`
}

type TurnBlock struct {
	TurnID string `json:"turn_id"`
	Model  string `json:"model,omitempty"`
}

type Usage struct {
	InputTokens  int64 `json:"input_tokens"`
	OutputTokens int64 `json:"output_tokens"`
}

type UserAgentConfig = coretypes.UserAgentConfig