agent

type Agent interface {
	// Name 返回 Provider 唯一标识。
	Name() string
	// Invoke 执行一次性任务并同步返回最终结果。
	Invoke(ctx context.Context, req Request, rt Runtime) (*Result, error)
	// Stream 执行流式请求，通过 rt.Emit 逐块输出事件，返回最终聚合结果。
	Stream(ctx context.Context, req Request, rt Runtime) (*Result, error)
}

type AgentEvent struct {
	ID        string         `json:"id" gorm:"column:id;primaryKey;type:varchar(64)"`
	TaskID    string         `json:"task_id" gorm:"column:task_id;type:varchar(64);index:idx_agent_events_task_seq,priority:1"`
	Sequence  int64          `json:"sequence" gorm:"column:sequence;index:idx_agent_events_task_seq,priority:2"`
	Type      AgentEventType `json:"type" gorm:"column:type;type:varchar(32)"`
	Payload   any            `json:"payload,omitempty" gorm:"serializer:json"`
	CreatedAt time.Time      `json:"created_at" gorm:"column:created_at"`
}

type AgentEventType string

type AgentService struct {
	// contains filtered or unexported fields
}

type Client struct {
	// contains filtered or unexported fields
}

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

type Conversation struct {
	ID       string `json:"id" gorm:"column:id;primaryKey;type:varchar(64)"`
	UserID   string `json:"user_id" gorm:"column:user_id;type:varchar(64);index"`
	Provider string `json:"provider" gorm:"column:provider;type:varchar(64)"`
	Model    string `json:"model" gorm:"column:model;type:varchar(128)"`
	// Messages 保存完整历史（system 提示词之外的 user/assistant 消息）。
	// 关系由 Repository 自行维护（独立表 agent_conversation_messages），
	// 不使用 GORM 的 HasMany 关联，因此标记为 gorm:"-"。
	Messages []Message `json:"messages" gorm:"-"`
	// CurrentTaskID 记录当前活跃轮次（running / waiting_permission）的任务 ID；
	// 轮次结束时置空。供前端刷新 / 切换会话时恢复实时流。
	CurrentTaskID string    `json:"current_task_id,omitempty" gorm:"column:current_task_id;type:varchar(64)"`
	CreatedAt     time.Time `json:"created_at" gorm:"column:created_at"`
	UpdatedAt     time.Time `json:"updated_at" gorm:"column:updated_at"`
}

type ConversationMessage struct {
	ID             string    `json:"id" gorm:"column:id;primaryKey;type:varchar(64)"`
	ConversationID string    `json:"conversation_id" gorm:"column:conversation_id;type:varchar(64);index"`
	Seq            int       `json:"seq" gorm:"column:seq;index"`
	Role           string    `json:"role" gorm:"column:role;type:varchar(32)"`
	Content        string    `json:"content" gorm:"column:content;type:text"`
	CreatedAt      time.Time `json:"created_at" gorm:"column:created_at"`
}

type ConversationRepository interface {
	Get(ctx context.Context, id string) (*Conversation, error)
	Create(ctx context.Context, conv *Conversation) error
	Update(ctx context.Context, conv *Conversation) error
	// Page 分页查询会话（按 UpdatedAt 降序）；userID 为空表示全部用户。
	Page(ctx context.Context, userID string, offset, limit int) ([]*Conversation, int64, error)
}

type ConversationService struct {
	// contains filtered or unexported fields
}

type EventBus interface {
	// Publish 发布一个事件给订阅了该任务（或全部任务）的订阅者。
	Publish(ctx context.Context, event AgentEvent)
	// Subscribe 订阅某任务的事件；taskID 为空表示订阅全部任务。
	// 返回的 unsubscribe 用于取消订阅。
	Subscribe(taskID string, handler EventHandler) (unsubscribe func())
}

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

type EventRepository interface {
	// Append 为事件分配 sequence 并追加到任务事件流。
	Append(ctx context.Context, event *AgentEvent) error
	// ListByTask 返回任务中 sequence 大于 after 的事件（升序）。
	ListByTask(ctx context.Context, taskID string, after int64) ([]*AgentEvent, error)
	// Page 分页查询事件（按 CreatedAt 升序）；taskID 为空表示全部任务。
	Page(ctx context.Context, taskID string, offset, limit int) ([]*AgentEvent, int64, error)
}

type Memory struct {
	ID        string     `json:"id" gorm:"column:id;primaryKey;type:varchar(64)"`
	UserID    string     `json:"user_id" gorm:"column:user_id;type:varchar(64);index:idx_agent_memories_user_kind,priority:1"`
	SessionID string     `json:"session_id,omitempty" gorm:"column:session_id;type:varchar(64);index"`
	Kind      MemoryKind `json:"kind" gorm:"column:kind;type:varchar(32);index:idx_agent_memories_user_kind,priority:2"`
	Content   string     `json:"content" gorm:"column:content;type:text"`

	// 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 MemoryConfig struct {
	Repo      MemoryRepository
	Retriever MemoryRetriever
	Extractor MemoryExtractor
}

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 MemoryManager struct {
	// contains filtered or unexported fields
}

type MemoryRepository interface {
	Create(ctx context.Context, memory *Memory) error
	Get(ctx context.Context, id string) (*Memory, error)
	Update(ctx context.Context, memory *Memory) error
	Delete(ctx context.Context, id string) error
	// ListByUser 分页查询某用户的记忆（按 UpdatedAt 降序）；kinds 为空表示全部类别。
	ListByUser(ctx context.Context, userID string, offset, limit int, kinds ...MemoryKind) ([]*Memory, int64, error)
	// Search 按关键词检索某用户的记忆（返回按相关度 + 重要度排序）。
	// 基础实现为子串 / LIKE 匹配，可被更高级的检索器（向量 / 语义）替换。
	Search(ctx context.Context, userID, query string, limit int) ([]*Memory, error)
}

type MemoryRetriever interface {
	// Retrieve 返回与 query 相关的记忆，按相关度降序，最多 limit 条。
	Retrieve(ctx context.Context, userID, query string, limit int) ([]*Memory, error)
}

type MemoryTurn struct {
	UserID    string
	SessionID string
	Request   Request
	Result    *Result
}

type Message struct {
	Role    string `json:"role"`    // system / user / assistant / tool
	Content string `json:"content"` // 文本内容
}

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 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"`

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

type OperationType string

type Options struct {
	Model       string            `json:"model"`
	BaseURL     string            `json:"base_url"`
	APIKey      string            `json:"api_key"`
	BearerToken string            `json:"bearer_token"`
	WorkingDir  string            `json:"working_dir"`
	Extra       map[string]string `json:"extra"`

	// Tools 是本次调用可用的工具注册表。
	//
	// Provider 据此向模型暴露工具定义（tool.List()），并通过 ToolRunner /
	// tool.Executor 执行模型发起的工具调用。为 nil 表示本次调用不启用工具。
	Tools *tool.Registry `json:"-"`

	// Skills 是本次调用可用的技能注册表。
	//
	// Provider 据此向模型暴露技能定义（skill.List()）与指令正文（skill.Instructions()），
	// 并通过 SkillRunner / skill.Invoker 执行模型发起的技能调用。为 nil 表示本次
	// 调用不启用技能。
	Skills *skill.Registry `json:"-"`
}

type PermissionDecision string

type PermissionManager struct {
	// contains filtered or unexported fields
}

type PermissionPolicy interface {
	Check(ctx context.Context, operation Operation) PermissionDecision
}

type PermissionRepository interface {
	Create(ctx context.Context, permission *PermissionRequest) error
	Get(ctx context.Context, id string) (*PermissionRequest, error)
	Update(ctx context.Context, permission *PermissionRequest) error
	ListPendingByTask(ctx context.Context, taskID string) ([]*PermissionRequest, error)
	// Page 分页查询权限请求（按 CreatedAt 升序）；taskID 为空表示全部任务，statuses 为空表示全部状态。
	Page(ctx context.Context, offset, limit int, taskID string, statuses ...PermissionStatus) ([]*PermissionRequest, int64, error)
}

type PermissionRequest struct {
	ID        string           `json:"id" gorm:"column:id;primaryKey;type:varchar(64)"`
	TaskID    string           `json:"task_id" gorm:"column:task_id;type:varchar(64);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 *string    `json:"resolved_by,omitempty" gorm:"column:resolved_by;type:varchar(64)"`
}

type PermissionStatus string

type Profile struct {
	ID           string        `json:"id" gorm:"column:id;primaryKey;type:varchar(64)"`
	Name         string        `json:"name" gorm:"column:name;type:varchar(64);index:idx_agent_profiles_user_name,priority:2"`
	DisplayName  string        `json:"display_name" gorm:"column:display_name;type:varchar(128)"`
	Description  string        `json:"description" gorm:"column:description;type:text"`
	UserID       string        `json:"user_id" gorm:"column:user_id;type:varchar(64);index:idx_agent_profiles_user_name,priority:1"`
	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"`
	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 ProfileManager struct {
	// contains filtered or unexported fields
}

type ProfileRepository interface {
	Create(ctx context.Context, profile *Profile) error
	Get(ctx context.Context, id string) (*Profile, error)
	Update(ctx context.Context, profile *Profile) error
	Delete(ctx context.Context, id string) error
	// ListByUser 返回某用户全部自定义 Profile（按名称升序）。
	ListByUser(ctx context.Context, userID string) ([]*Profile, error)
	// GetByName 按名称返回某用户的自定义 Profile。
	GetByName(ctx context.Context, userID, name string) (*Profile, error)
	// GetDefault 返回某用户的默认自定义 Profile；不存在时返回 (nil, nil)。
	GetDefault(ctx context.Context, userID string) (*Profile, error)
	// ClearDefault 清除某用户除 exceptID 外的默认标记。
	ClearDefault(ctx context.Context, userID, exceptID string) error
}

type ProjectContextProvider interface {
	// ProjectContext 返回当前用户激活项目下的上下文文本块；无可用内容时返回空串。
	//
	// 返回的文本会作为独立段落追加到 SystemPrompt 末尾。
	ProjectContext(ctx context.Context, userID string) (string, error)
}

type Provider interface {
	// Name 返回 Provider 唯一标识（小写，如 claude_code / codex / copilot / custom）。
	Name() string
	// New 基于 Options 构建 Agent 实例。
	New(opts Options) (Agent, error)
}

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

type Registry struct {
	// contains filtered or unexported fields
}

type Request struct {
	// Provider 可选：强制指定 Provider 名称；为空则使用 Client 的默认 Provider。
	Provider string `json:"provider"`
	// Model 可选：模型名称，为空时由 Provider 自行决定。
	Model string `json:"model"`
	// SessionID 可选：会话标识，用于把多次调用关联到同一会话（与权限 / 任务联动）。
	SessionID string `json:"session_id"`
	// UserID 可选：发起调用的用户，用于记忆（memory）的归属隔离与检索。
	UserID string `json:"user_id,omitempty"`
	// Profile 可选：AgentProfile 名称，AgentService 据此解析系统提示词、技能与上下文注入开关。
	Profile string `json:"profile,omitempty"`
	// Skills 可选：本次调用启用的技能名列表；为空表示使用默认全部技能。
	Skills []string `json:"skills,omitempty"`
	// SystemPrompt 系统提示词。
	SystemPrompt string `json:"system_prompt"`
	// Messages 对话上下文（不含 SystemPrompt）。
	Messages []Message `json:"messages"`
	// WorkingDir 可选：Agent 执行的工作目录。
	WorkingDir string `json:"working_dir"`
	// 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 {
	Content string          `json:"content"`
	Usage   Usage           `json:"usage"`
	Raw     json.RawMessage `json:"raw,omitempty"` // Provider 原始返回，便于调试与扩展
}

type Runtime interface {
	// Emit 输出一个流式事件。
	Emit(ctx context.Context, event StreamEvent) error
	// RequestPermission 创建权限请求并阻塞等待决策（allow / deny）。
	RequestPermission(ctx context.Context, operation Operation) (PermissionDecision, error)
	// WaitPermission 等待一个已存在权限请求（permissionID）的决策。
	WaitPermission(ctx context.Context, permissionID string) (PermissionDecision, error)
}

type ServiceConfig struct {
	Client   *Client
	Tasks    TaskRepository
	Perms    *PermissionManager
	Events   EventRepository
	Bus      EventBus
	Policy   PermissionPolicy
	Memory   *MemoryManager
	Project  ProjectContextProvider
	Profiles *ProfileManager
}

type SkillCall struct {
	ID        string `json:"id"`   // skillCallId
	Name      string `json:"name"` // 技能名
	Arguments any    `json:"arguments,omitempty"`
}

type SkillCallProvider func(ctx context.Context, results []skill.Result) ([]SkillCall, error)

type SkillLoop struct {
	// contains filtered or unexported fields
}

type SkillPermissionResolver func(ctx context.Context, call SkillCall) (Operation, bool)

type SkillResultEvent struct {
	CallID  string `json:"call_id"`
	Name    string `json:"name"`
	Content string `json:"content"`
	IsError bool   `json:"is_error"`
}

type SkillRunner struct {
	// contains filtered or unexported fields
}

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         string     `json:"id" gorm:"column:id;primaryKey;type:varchar(64)"`
	SessionID  string     `json:"session_id,omitempty" gorm:"column:session_id;type:varchar(64);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"`
	// 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 TaskRepository interface {
	Create(ctx context.Context, task *Task) error
	Get(ctx context.Context, id string) (*Task, error)
	Update(ctx context.Context, task *Task) error
	ListByStatus(ctx context.Context, statuses ...TaskStatus) ([]*Task, error)
	// Page 分页查询任务（按 CreatedAt 升序）；statuses 为空表示全部状态。
	Page(ctx context.Context, offset, limit int, statuses ...TaskStatus) ([]*Task, int64, error)
}

type TaskStatus string

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

type ToolCallProvider func(ctx context.Context, results []tool.Result) ([]ToolCall, error)

type ToolLoop struct {
	// contains filtered or unexported fields
}

type ToolPermissionResolver func(ctx context.Context, call ToolCall) (Operation, bool)

type ToolResultEvent struct {
	CallID  string `json:"call_id"`
	Name    string `json:"name"`
	Content string `json:"content"`
	IsError bool   `json:"is_error"`
}

type ToolRunner struct {
	// contains filtered or unexported fields
}

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

type TurnInput struct {
	UserID         string
	ConversationID string // 为空则创建新会话
	Message        string // 本轮用户输入
	Provider       string
	Model          string
	SystemPrompt   string
	Profile        string // AgentProfile 名称（为空取默认）
	WorkingDir     string
}

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