messaging

type ActorContext struct {
	UserID      string `json:"user_id,omitempty"`
	DisplayName string `json:"display_name,omitempty"`
	Channel     string `json:"channel,omitempty"`
	ExternalID  string `json:"external_id,omitempty"`
	AccountID   string `json:"account_id,omitempty"`
}

type ApprovalDecisionPayload struct {
	RequestID string `json:"request_id"`
	Action    string `json:"action"` // "approve" | "deny" | "always"
	Reason    string `json:"reason,omitempty"`
}

type ApprovalRequestPayload struct {
	RequestID   string            `json:"request_id"`
	ToolName    string            `json:"tool_name"`
	ToolCallID  string            `json:"tool_call_id,omitempty"`
	Description string            `json:"description"`
	Arguments   json.RawMessage   `json:"arguments,omitempty"`
	Metadata    map[string]string `json:"metadata,omitempty"`
}

type ApprovalResolveCommandPayload struct {
	Action string `json:"action"` // "approve" | "deny" | "always"
	Reason string `json:"reason,omitempty"`
}

type ArtifactPayload struct {
	ArtifactID           string `json:"artifact_id,omitempty"`
	Title                string `json:"title,omitempty"`
	Filename             string `json:"filename,omitempty"`
	OriginalName         string `json:"original_name,omitempty"`
	Description          string `json:"description,omitempty"`
	MimeType             string `json:"mime_type,omitempty"`
	ArtifactType         string `json:"artifact_type,omitempty"`
	FileSize             int64  `json:"file_size,omitempty"`
	CreatedAt            string `json:"created_at,omitempty"`
	RelativePath         string `json:"relative_path,omitempty"`
	PreviousRelativePath string `json:"previous_relative_path,omitempty"`
	StorageKey           string `json:"storage_key,omitempty"`
	StorageURI           string `json:"storage_uri,omitempty"`
	Sha256               string `json:"sha256,omitempty"`
	Source               string `json:"source,omitempty"`
	Status               string `json:"status,omitempty"`
	VersionNo            int    `json:"version_no,omitempty"`
}

type AssistantMessageTrigger struct {
	SenderType    SenderType `json:"sender_type"`
	AssistantID   *string    `json:"assistant_id,omitempty"`
	AssistantName string     `json:"assistant_name"`
	RunID         string     `json:"run_id,omitempty"`
}

type Attachment struct {
	ID       string `json:"id,omitempty"`
	Name     string `json:"name,omitempty"`
	MimeType string `json:"mime_type,omitempty"`
	URL      string `json:"url,omitempty"`
	// AttachmentRole 是工具场景赋予附件的语义角色；空表示普通附件。
	AttachmentRole string `json:"attachment_role,omitempty"`
}

type CancelRunCommandPayload struct {
	RunID  string `json:"run_id"`
	Reason string `json:"reason,omitempty"`
}

type ChatMessage struct {
	ID         string      `json:"id,omitempty"`
	Role       MessageRole `json:"role"`
	Content    string      `json:"content"`
	SenderName string      `json:"sender_name,omitempty"`
}

type CommandType string

type Envelope[T any] struct {
	ID        string      `json:"id"`
	Type      MessageType `json:"type"`
	CreatedAt time.Time   `json:"created_at"`

	Trace TraceContext `json:"trace"`
	Route RouteContext `json:"route"`

	Body     T               `json:"body"`
	Metadata json.RawMessage `json:"metadata,omitempty"`
}

type ExecutionTarget struct {
	// AssistantID 是 leros_digital_assistant.id，自增主键，用于 llm_history 关联。
	AssistantID uint `json:"assistant_id,omitempty"`
	// AssistantPublicID 是 leros_digital_assistant.public_id，用于 worker 侧日志展示。
	AssistantPublicID string   `json:"assistant_public_id,omitempty"`
	AssistantName     string   `json:"assistant_name,omitempty"`
	AssistantDesc     string   `json:"assistant_desc,omitempty"`
	SystemPrompt      string   `json:"system_prompt,omitempty"`
	Skills            []string `json:"skills,omitempty"`
	Tools             []string `json:"tools,omitempty"`
}

type GlobalEventPayload struct {
	Type      GlobalEventType `json:"type"`
	ProjectID uint            `json:"project_id"`
	SessionID string          `json:"session_id"`
	Seq       uint64          `json:"seq"`
	Timestamp int64           `json:"timestamp"`
	Data      json.RawMessage `json:"data"`
}

type GlobalEventType string

type HumanMessageData struct {
	SenderType  SenderType `json:"sender_type"`
	SenderUin   *uint      `json:"sender_uin,omitempty"`
	SenderName  string     `json:"sender_name"`
	Content     string     `json:"content"`
	MessageType string     `json:"message_type"`
	Sequence    int64      `json:"sequence"`
	RunID       string     `json:"run_id,omitempty"`
	CreatedAt   string     `json:"created_at"`
}

type InputType string

type Lane string

type MemberBrief struct {
	MemberID      uint   `json:"member_id"`
	MemberType    string `json:"member_type"` // user / assistant
	MemberRole    string `json:"member_role"` // owner / admin / member / viewer
	Name          string `json:"name"`
	IsDefault     bool   `json:"is_default,omitempty"`
	IsCurrentExec bool   `json:"is_current_exec,omitempty"` // marks the assistant executing this run
	IsCurrentUser bool   `json:"is_current_user,omitempty"` // marks the user who initiated this run
}

type MessageCreatedData struct {
	MessageID     uint       `json:"message_id"`
	Sequence      int64      `json:"sequence"`
	SenderType    SenderType `json:"sender_type"`
	SenderUin     *uint      `json:"sender_uin,omitempty"`
	SenderName    string     `json:"sender_name"`
	AssistantID   *string    `json:"assistant_id,omitempty"`
	AssistantName string     `json:"assistant_name,omitempty"`
	Content       string     `json:"content"`
	RunID         string     `json:"run_id,omitempty"`

	// 前端 human 消息渲染所需字段（assistant 事件不设置，omitempty 保证不出现）
	MessageType string                    `json:"message_type,omitempty"`
	Attachments []types.MessageAttachment `json:"attachments,omitempty"`
	Metadata    *types.ObjectMetadata     `json:"metadata,omitempty"`
}

type MessageRole string

type MessageType string

type ModelOptions struct {
	ModelID      uint   `json:"model_id,omitempty"`
	Provider     string `json:"provider,omitempty"`
	Model        string `json:"model,omitempty"`
	BaseURL      string `json:"base_url,omitempty"`
	BaseURLHasV1 bool   `json:"base_url_has_v1,omitempty"`
	APIKey       string `json:"api_key,omitempty"`
	// Vision 表示该模型是否支持图片（多模态）输入。
	Vision bool `json:"vision,omitempty"`

	// Temperature 默认采样温度；0 表示未配置，走 provider 默认。
	Temperature float64 `json:"temperature,omitempty"`
	// MaxTokens 默认最大输出 token 数；0 表示未配置，走 provider 默认。
	MaxTokens int `json:"max_tokens,omitempty"`

	TopP             *float64 `json:"top_p,omitempty"`
	FrequencyPenalty *float64 `json:"frequency_penalty,omitempty"`
	PresencePenalty  *float64 `json:"presence_penalty,omitempty"`
	ContextLimit     int      `json:"context_limit,omitempty"`
	OutputLimit      int      `json:"output_limit,omitempty"`
}

type PlanPublishedPayload struct {
	FileID       string `json:"file_id"`
	Directive    string `json:"directive"`
	SummaryLines int    `json:"summary_lines"`
	TotalLines   int    `json:"total_lines"`
	StorageKey   string `json:"storage_key,omitempty"`
	StorageURI   string `json:"storage_uri,omitempty"`
	Filename     string `json:"filename,omitempty"`
	OriginalName string `json:"original_name,omitempty"`
	MimeType     string `json:"mime_type,omitempty"`
	FileSize     int64  `json:"file_size,omitempty"`
	Sha256       string `json:"sha256,omitempty"`
}

type PluginSnapshot struct {
	PluginID   string          `json:"plugin_id"`
	Code       string          `json:"code"`
	Kind       string          `json:"kind"`
	Revision   int             `json:"revision"`
	Definition json.RawMessage `json:"definition"`
}

type ProjectContext struct {
	Name        string        `json:"name,omitempty"`
	Description string        `json:"description,omitempty"`
	Objective   string        `json:"objective,omitempty"`
	Members     []MemberBrief `json:"members,omitempty"`
}

type ProjectFileRestoreCommandPayload struct {
	ProjectPublicID string `json:"project_public_id"`
	RelativePath    string `json:"relative_path"`
	Branch          string `json:"branch,omitempty"`
	DownloadURL     string `json:"download_url"`
	AuthorName      string `json:"author_name,omitempty"`
	AuthorEmail     string `json:"author_email,omitempty"`
}

type ProjectFileRestoreResult struct {
	Success      bool   `json:"success"`
	RelativePath string `json:"relative_path,omitempty"`
	CommitSHA    string `json:"commit_sha,omitempty"`
	Error        string `json:"error,omitempty"`
}

type QuestionAnswerCommandPayload struct {
	Answers [][]string `json:"answers"`
}

type QuestionAnswerPayload struct {
	RequestID string     `json:"request_id"`
	Answers   [][]string `json:"answers"`
}

type QuestionItem struct {
	Question    string           `json:"question"`
	Header      string           `json:"header,omitempty"`
	Options     []QuestionOption `json:"options"`
	MultiSelect bool             `json:"multiple"`
	Custom      bool             `json:"custom"`
}

type QuestionOption struct {
	Label       string `json:"label"`
	Description string `json:"description,omitempty"`
}

type QuestionRequestPayload struct {
	RequestID       string            `json:"request_id"`
	SessionID       string            `json:"session_id,omitempty"`
	Questions       []QuestionItem    `json:"questions"`
	ToolCallID      string            `json:"tool_call_id,omitempty"`
	MessageID       string            `json:"message_id,omitempty"`
	InteractionType string            `json:"interaction_type,omitempty"`
	Metadata        map[string]string `json:"metadata,omitempty"`
}

type RouteContext struct {
	OrgID     uint   `json:"org_id"`
	SessionID string `json:"session_id,omitempty"` // SessionID 是 leros_session.public_id，用于消息路由和租户隔离。

	// WorkerID 是 leros_worker_deployment.worker_id（worker 主键），用于 worker 消息分发。
	WorkerID uint `json:"worker_id,omitempty"`
	// WorkerPublicID 是 leros_worker_deployment.public_id，用于日志展示和对外追溯。
	WorkerPublicID string `json:"worker_public_id,omitempty"`

	// AssistantID 是 leros_digital_assistant.id（assistant 主键），用于内部关联和 llm_history 记录。
	AssistantID uint `json:"assistant_id,omitempty"`
	// AssistantPublicID 是 leros_digital_assistant.public_id，用于对外标识和 SSE 过滤。
	AssistantPublicID string `json:"assistant_public_id,omitempty"`

	ClientIP string `json:"client_ip,omitempty"`
}

type RunCommandMetadata struct {
	SessionID   string `json:"session_id,omitempty"`
	MessageType string `json:"message_type,omitempty"`
	Sequence    int64  `json:"sequence,omitempty"`
}

type RunCommandPayload struct {
	TaskType      TaskType `json:"task_type"`
	ExecutionMode string   `json:"execution_mode,omitempty"`

	Actor     ActorContext     `json:"actor"`
	Execution ExecutionTarget  `json:"execution"`
	Workspace WorkspaceOptions `json:"workspace,omitempty"`
	Project   ProjectContext   `json:"project,omitempty"`
	Input     TaskInput        `json:"input"`

	Model   ModelOptions     `json:"model,omitempty"`
	Runtime RuntimeOptions   `json:"runtime,omitempty"`
	Policy  TaskPolicy       `json:"policy,omitempty"`
	Plugins []PluginSnapshot `json:"plugins,omitempty"`

	// 业务主键 ID，用于 llm_history 等调用记录关联。
	// 以下均为对应表的自增主键（int），区别于其它字段中的 public_id（string）。
	//
	//   ProjectID   leros_project.id          -> 区别于 Workspace.ProjectID（project public_id）
	//   SessionID   leros_session.id          -> 区别于 RouteContext.SessionID（session public_id）
	//   MessageID   leros_session_message.id  -> 当前触发 run 的消息主键
	//   AssistantID       leros_digital_assistant.id          -> 区别于 Execution.AssistantPublicID（assistant public_id）
	//   AssistantPublicID leros_digital_assistant.public_id    -> 用于 worker 侧展示和对外追溯
	//   Uin               leros_user.id                        -> 区别于 ActorContext.UserID（fmt.Sprintf("%d", uin)）
	ProjectID         uint   `json:"project_id"`
	SessionID         uint   `json:"session_id"`
	MessageID         uint   `json:"message_id"`
	AssistantID       uint   `json:"assistant_id"`
	AssistantPublicID string `json:"assistant_public_id,omitempty"`
	Uin               uint   `json:"uin"`

	// NotAfter Worker 最晚允许开始时间（RFC3339，UTC）。超过该时间 Worker 应拒绝执行。
	// 需要持久化进 worker inbox，崩溃恢复时仍能生效。
	NotAfter string `json:"not_after,omitempty"`
}

type RunCompletedPayload struct {
	Status      string              `json:"status"`
	Result      RunResultPayload    `json:"result"`
	Artifacts   []ArtifactPayload   `json:"artifacts,omitempty"`
	Usage       *UsagePayload       `json:"usage,omitempty"`
	Events      []RunEventRecord    `json:"events,omitempty"`
	StartedAt   string              `json:"started_at,omitempty"`
	CompletedAt string              `json:"completed_at,omitempty"`
	Metadata    *RunMetadataPayload `json:"metadata,omitempty"`
}

type RunEvent = Envelope[RunEventBody]

type RunEventBody struct {
	Seq               int64           `json:"seq"`
	Event             RunEventType    `json:"event"`
	Payload           RunEventPayload `json:"payload"`
	ReplyToMessageIDs []string        `json:"reply_to_message_ids,omitempty"`
	// MemberCommandIDs / MemberRunIDs 标识同一 Session 合并批次中的所有源命令。
	MemberCommandIDs []string `json:"member_command_ids,omitempty"`
	MemberRunIDs     []string `json:"member_run_ids,omitempty"`

	// RunCompleted 仅在终端事件（run.completed/failed/cancelled）时填充。
	RunCompleted *RunCompletedPayload `json:"run_completed,omitempty"`
	// Error 仅在 run.failed 时填充。
	Error *RunEventError `json:"error,omitempty"`
	// AssistantPKID 是 leros_digital_assistant.id（主键），用于 worker 侧持久化关联（如 llm_history）。
	AssistantPKID uint `json:"assistant_pk_id,omitempty"`
	// AssistantID 是 leros_digital_assistant.public_id，用于 server/UI 侧展示和 SSE 过滤。
	AssistantID string `json:"assistant_id,omitempty"`
}

type RunEventError struct {
	Code    string `json:"code,omitempty"`
	Message string `json:"message"`
}

type RunEventLane string

type RunEventPayload struct {
	MessageID        string                   `json:"message_id,omitempty"`
	Role             MessageRole              `json:"role,omitempty"`
	Content          string                   `json:"content,omitempty"`
	Usage            *UsagePayload            `json:"usage,omitempty"`
	ToolCall         *ToolCallPayload         `json:"tool_call,omitempty"`
	ToolResult       *ToolCallResultPayload   `json:"tool_result,omitempty"`
	Todos            []RuntimeTodoItem        `json:"todos,omitempty"`
	Artifact         *ArtifactPayload         `json:"artifact,omitempty"`
	ApprovalRequest  *ApprovalRequestPayload  `json:"approval_request,omitempty"`
	ApprovalDecision *ApprovalDecisionPayload `json:"approval_decision,omitempty"`
	QuestionRequest  *QuestionRequestPayload  `json:"question_request,omitempty"`
	QuestionAnswer   *QuestionAnswerPayload   `json:"question_answer,omitempty"`
	PlanPublished    *PlanPublishedPayload    `json:"plan_published,omitempty"`
	WorkTitle        *WorkTitleUpdatedPayload `json:"work_title,omitempty"`
}

type RunEventRecord struct {
	Seq         int64           `json:"seq,omitempty"`
	LastSeq     int64           `json:"last_seq,omitempty"`
	Type        string          `json:"type"`
	Timestamp   int64           `json:"timestamp,omitempty"`
	Payload     json.RawMessage `json:"payload,omitempty"`
	AssistantID string          `json:"assistant_id,omitempty"`
}

type RunEventType string

type RunMetadataPayload struct {
	Runtime    string `json:"runtime,omitempty"`
	WorkDir    string `json:"work_dir,omitempty"`
	ProviderID string `json:"provider_id,omitempty"`
	SessionID  string `json:"session_id,omitempty"`
	Phase      string `json:"phase,omitempty"`
	Resume     bool   `json:"resume,omitempty"`
}

type RunResultPayload struct {
	Message string `json:"message,omitempty"`
}

type RuntimeOptions struct {
	Kind    string `json:"kind,omitempty"`
	WorkDir string `json:"work_dir,omitempty"`
}

type RuntimeTodoItem struct {
	ID       string `json:"id"`
	Title    string `json:"title"`
	Status   string `json:"status"`
	Priority string `json:"priority,omitempty"`
}

type SenderType string

type SkillChangeType string

type SkillDetailData struct {
	SkillID     string   `json:"skill_id,omitempty"`
	Name        string   `json:"name"`
	Description string   `json:"description"`
	Category    string   `json:"category"`
	Source      string   `json:"source"`
	Trust       string   `json:"trust"`
	Version     string   `json:"version"`
	SkillMD     string   `json:"skill_md"`
	Tags        []string `json:"tags"`
	Files       []string `json:"files"`
}

type SkillListItem struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	Category    string `json:"category"`
	Source      string `json:"source"`
	Trust       string `json:"trust"`
}

type SkillPackageUploadedEvent struct {
	EventID    string          `json:"event_id"`
	WorkerID   uint            `json:"worker_id"`
	RunID      string          `json:"run_id"`
	ProjectID  uint            `json:"project_id,omitempty"`
	ActorUIN   uint            `json:"actor_uin"`
	SkillCode  string          `json:"skill_code"`
	ChangeType SkillChangeType `json:"change_type"`
	StorageURI string          `json:"storage_uri"`
	SHA256     string          `json:"sha256"`
	FileSize   int64           `json:"file_size"`
	Filename   string          `json:"filename"`
	MimeType   string          `json:"mime_type"`
}

type TaskInput struct {
	Type         InputType     `json:"type"`
	Scene        string        `json:"scene,omitempty"`
	OutputFormat string        `json:"output_format,omitempty"`
	Messages     []ChatMessage `json:"messages,omitempty"`
	Attachments  []Attachment  `json:"attachments,omitempty"`
}

type TaskPolicy struct {
	RequireApproval bool   `json:"require_approval,omitempty"`
	PermissionMode  string `json:"permission_mode,omitempty"`
}

type TaskType string

type ToolCallPayload struct {
	ToolCallID string          `json:"tool_call_id"`
	Name       string          `json:"name"`
	Arguments  json.RawMessage `json:"arguments,omitempty"`
}

type ToolCallResultPayload struct {
	ToolCallID string          `json:"tool_call_id"`
	Name       string          `json:"name,omitempty"`
	Result     json.RawMessage `json:"result,omitempty"`
	Error      string          `json:"error,omitempty"`
	IsError    bool            `json:"is_error"`
	ElapsedMS  int64           `json:"elapsed_ms,omitempty"`
}

type TraceContext struct {
	TraceID   string `json:"trace_id"`
	RequestID string `json:"request_id,omitempty"`
	ReqID     string `json:"req_id,omitempty"`
	TaskID    string `json:"task_id,omitempty"`
	RunID     string `json:"run_id,omitempty"`
	ParentID  string `json:"parent_id,omitempty"`
}

type UsagePayload struct {
	TotalTokens       int `json:"total_tokens"`
	InputTokens       int `json:"input_tokens"`
	OutputTokens      int `json:"output_tokens"`
	CacheInputTokens  int `json:"cache_input_tokens"`
	CacheOutputTokens int `json:"cache_output_tokens"`
}

type WorkTitleUpdatedPayload struct {
	ProjectID    string `json:"project_id"`
	ProjectName  string `json:"project_name"`
	TaskID       string `json:"task_id,omitempty"`
	TaskTitle    string `json:"task_title,omitempty"`
	SessionID    string `json:"session_id"`
	SessionTitle string `json:"session_title,omitempty"`
}

type WorkerCommand = Envelope[WorkerCommandBody]

type WorkerCommandBody struct {
	CommandType CommandType     `json:"command_type"`
	Payload     json.RawMessage `json:"payload,omitempty"`
	// ReplyTo 是 server Request() 注入的 NATS inbox，worker 通过 core NATS 直接回复。
	ReplyTo string `json:"reply_to,omitempty"`
}

type WorkerCommandResult struct {
	Success bool   `json:"success"`
	Action  string `json:"action"`
	Message string `json:"message,omitempty"`
	Error   string `json:"error,omitempty"`
	Data    any    `json:"data,omitempty"`
}

type WorkerRunSummary struct {
	RunID     string `json:"run_id,omitempty"`
	TaskID    string `json:"task_id,omitempty"`
	SessionID string `json:"session_id,omitempty"`
	CommandID string `json:"command_id,omitempty"`
	StreamSeq uint64 `json:"stream_seq,omitempty"`
	// Status 表示该任务当前所处阶段：running 或 waiting。
	Status string `json:"status,omitempty"`
	// CreatedAt / UpdatedAt / StartedAt 均为 Unix 秒；StartedAt 零值表示尚未开始。
	CreatedAt int64 `json:"created_at,omitempty"`
	UpdatedAt int64 `json:"updated_at,omitempty"`
	StartedAt int64 `json:"started_at,omitempty"`
}

type WorkerStatusRequest struct {
	OrgID    uint `json:"org_id"`
	WorkerID uint `json:"worker_id"`
}

type WorkerStatusSnapshot struct {
	// OrgID / WorkerID 标识生成该快照的 Worker，用于 Server 校验回复归属。
	OrgID          uint `json:"org_id"`
	WorkerID       uint `json:"worker_id"`
	MaxConcurrency int  `json:"max_concurrency"`
	// RunningCount 已启动但尚未结束的 Runtime 数量；交互等待中的 Runtime 也计入。
	RunningCount int `json:"running_count"`
	// WaitingCount 已接收但尚未开始 Runtime 执行的本地 Run 数量。
	WaitingCount int `json:"waiting_count"`
	// DebounceWaitingCount 仍处于 debounce 窗口内的 Run 数量。
	DebounceWaitingCount int `json:"debounce_waiting_count"`
	// CoordinatorWaitingCount 已进入 Coordinator 队列或正在等待计算槽的 Run 数量。
	CoordinatorWaitingCount int `json:"coordinator_waiting_count"`
	// AdmissionWaitingCount 被 Worker 准入 semaphore 实际阻塞的消息数量。
	AdmissionWaitingCount int `json:"admission_waiting_count"`
	// AcceptedCount Worker 已持久化并由当前进程拥有的命令数量，不含尚未准入的消息。
	AcceptedCount int `json:"accepted_count"`
	// ComputeBusyCount 当前占用计算槽的 Runtime 数量。
	ComputeBusyCount int `json:"compute_busy_count"`
	// InteractionWaitingCount 当前处于审批/问答等交互等待的 Runtime 数量。
	InteractionWaitingCount int `json:"interaction_waiting_count"`
	// InboxPendingCount 持久化 inbox 中处于 pending 状态的记录数。
	InboxPendingCount int `json:"inbox_pending_count"`
	// InboxProcessingCount 持久化 inbox 中处于 processing 状态的记录数。
	InboxProcessingCount int `json:"inbox_processing_count"`
	// SnapshotAt 快照生成时间（Unix 秒）。
	SnapshotAt int64 `json:"snapshot_at"`
	// Degraded 表示快照有局部数据源不可用；Errors 只返回稳定错误码，不暴露底层细节。
	Degraded bool     `json:"degraded,omitempty"`
	Errors   []string `json:"errors,omitempty"`

	// RunningTasks 正在执行的任务摘要。
	RunningTasks []WorkerRunSummary `json:"running_tasks,omitempty"`
	// WaitingTasks 等待执行的任务摘要；最多返回 maxWaitingTasks 条。
	WaitingTasks []WorkerRunSummary `json:"waiting_tasks,omitempty"`
	// WaitingTruncated 表示等待任务摘要因数量上限被截断。
	WaitingTruncated bool `json:"waiting_truncated,omitempty"`
}

type WorkspaceOptions struct {
	ProjectID string `json:"project_id,omitempty"`
	TaskID    string `json:"task_id,omitempty"`
}