defs

type Address struct {
	Kind IdentityKind `json:"kind"`
	// ID 在 Agent 地址里是 Session ID。
	ID string `json:"id"`
}

type AgentRelation string

type AgentSender struct {
	// TaskName 是发送方 Session 的任务名；主 Agent 没有任务名，为空。
	TaskName string        `json:"task_name,omitempty"`
	Relation AgentRelation `json:"relation"`
}

type AgentsInstruction struct {
	Executor string `json:"executor"`
	Path     string `json:"path"`
	Text     string `json:"text"`
}

type CatalogProvider struct {
	ID         string `json:"id"`
	Name       string `json:"name"`
	Protocol   string `json:"protocol"`
	BaseURL    string `json:"base_url"`
	ModelCount int    `json:"model_count"`
}

type Content struct {
	Kind  ContentKind   `json:"kind"`
	Text  *TextContent  `json:"text,omitempty"`
	Image *ImageContent `json:"image,omitempty"`
}

type ContentKind string

type ContextSummary struct {
	Text string `json:"text"`
	// CoveredThroughItemID 是摘要覆盖到的最后一条原始 Item，包含它本身。
	CoveredThroughItemID ItemID `json:"covered_through_item_id"`
}

type Conversation struct {
	ID ConversationID `json:"id"`
	// ExecutorSettings 是对话的 Executor 设置：新建时补上缺的 local 目录后保存，之后只由改设置修改；打开对话不写它。
	ExecutorSettings ExecutorSettings `json:"executor_settings"`
	// UpdatedAt 是最后一次写入的 Unix 毫秒，由存储在写入时分配；写入时设置的值不会被保存。
	// 创建、分叉、改标题、改 Executor 设置、归档或取消归档、更新消息数都会刷新这个时间。
	UpdatedAt     int64     `json:"updated_at,omitempty"`
	Title         string    `json:"title,omitempty"`
	RootSessionID SessionID `json:"root_session_id"`
	// MessageCount 是根 Session 中用户消息与主 Agent 回复的条数，每轮结束时累加。
	MessageCount int `json:"message_count,omitempty"`
	// ForkedFromID 是分叉来源的对话；不是分叉出来的为空。
	ForkedFromID ConversationID `json:"forked_from_id,omitempty"`
	// ArchivedAt 是归档时间（Unix 毫秒），0 表示没归档。
	ArchivedAt int64 `json:"archived_at,omitempty"`
}

type ConversationID string

type ExecutorDefinition struct {
	ID          string
	Kind        ExecutorKind
	Description string
	// WorkspaceDirectory 是对话设置里没给目录时用的根目录：local 是 server.workspace_directory，
	// 没配时是 serve 的启动目录；virtual 没配时是 /workspace。
	WorkspaceDirectory string
	// SSH 是 ssh 的连接参数，其他种类为 nil。
	SSH *SSHExecutorDefinition
	// Files 是 virtual 工作区建好时预先放进去的文件，键为绝对路径；builtin 用它放内置 skill。
	// 每个对话各拷一份，对话之间互不可见。
	Files map[string][]byte
}

type ExecutorDirectoryChange struct {
	ID                string
	PreviousDirectory string
	Directory         string
}

type ExecutorKind string

type ExecutorSettings struct {
	// DefaultExecutorID 是默认 Executor：模型省略 executor 参数时用它，项目 Skills、用户主目录 Skills 和 AGENTS.md 从它读；
	// 为空时是筛选后列表的第一个。
	DefaultExecutorID string `json:"default_executor_id,omitempty"`
	// ExecutorIDs 是对话可用的 Executor，只决定能不能用，不决定顺序；为空时全部可用，包括以后新加的。
	ExecutorIDs []string `json:"executor_ids,omitempty"`
	// WorkspaceDirectories 是各 Executor 在这个对话里的根目录，键为 Executor ID。local 总有一项；
	// 其他 Executor 只记 /cd 改过的，没有的用默认根目录（配置里的 workspace_directory）。
	WorkspaceDirectories map[string]string `json:"workspace_directories,omitempty"`
}

type ExecutorsChange struct {
	PreviousExecutors []TurnExecutor `json:"previous_executors"`
	Executors         []TurnExecutor `json:"executors"`
}

type ExecutorsChangeDetails struct {
	// NewDefault 是换上的默认 Executor；默认没换或新列表为空时为 nil。
	NewDefault *TurnExecutor
	// PreviousDefaultID 是原来的默认 Executor ID；NewDefault 为 nil 时为空。
	PreviousDefaultID string
	// Removed 是不再可用的 Executor，目录取自上一轮。
	Removed []TurnExecutor
	// Added 是新增可用的 Executor；已经作为新默认写入 NewDefault 的不再重复列出。
	Added []TurnExecutor
	// DirectoryChanges 是仍然可用但根目录换了的 Executor；新默认的目录已写在 NewDefault 里，不再列出。
	DirectoryChanges []ExecutorDirectoryChange
}

type HookEventName string

type HookRun struct {
	ID    HookRunID     `json:"id"`
	Event HookEventName `json:"event"`
	// CallID 是工具事件对应的调用。
	CallID string `json:"call_id,omitempty"`
	// ExecutorID 是运行这个 hook 的 Executor。
	ExecutorID string `json:"executor_id"`
	// SourcePath 是定义这个 hook 的配置文件。
	SourcePath string `json:"source_path"`
	// Handler 是显示用的命令：command 原文，或 script 路径加 args。
	Handler      string        `json:"handler"`
	DisplayOrder int           `json:"display_order"`
	Status       HookRunStatus `json:"status"`
	// StartedAt 和 CompletedAt 是 Unix 毫秒；运行中时 CompletedAt 为 0。
	StartedAt   int64 `json:"started_at"`
	CompletedAt int64 `json:"completed_at,omitempty"`

	BlockReason          string `json:"block_reason,omitempty"`
	UpdatedToolArguments string `json:"updated_tool_arguments,omitempty"`
	AdditionalContext    string `json:"additional_context,omitempty"`
	StopReason           string `json:"stop_reason,omitempty"`
	SystemMessage        string `json:"system_message,omitempty"`
	// ErrorMessage 在 failed 时说明原因，例如超时、脚本不存在。
	ErrorMessage string `json:"error_message,omitempty"`
}

type HookRunID string

type HookRunStatus string

type IdentityKind string

type ImageContent struct {
	DataURL string `json:"data_url"`
	Alt     string `json:"alt,omitempty"`
}

type InputID string

type Item struct {
	ID ItemID `json:"id"`
	// UpdatedAt 是保存时的 Unix 毫秒，由存储分配；Item 保存后不再修改。
	UpdatedAt         int64              `json:"updated_at,omitempty"`
	TurnID            TurnID             `json:"turn_id"`
	ModelCallID       ModelCallID        `json:"model_call_id,omitempty"`
	Kind              ItemKind           `json:"kind"`
	Message           *Message           `json:"message,omitempty"`
	Reasoning         *Reasoning         `json:"reasoning,omitempty"`
	ToolCall          *ToolCall          `json:"tool_call,omitempty"`
	ToolResult        *ToolResult        `json:"tool_result,omitempty"`
	ModelError        *ModelError        `json:"model_error,omitempty"`
	ContextSummary    *ContextSummary    `json:"context_summary,omitempty"`
	SessionFork       *SessionFork       `json:"session_fork,omitempty"`
	ModelChange       *ModelChange       `json:"model_change,omitempty"`
	ExecutorsChange   *ExecutorsChange   `json:"executors_change,omitempty"`
	SkillInstruction  *SkillInstruction  `json:"skill_instruction,omitempty"`
	AgentsInstruction *AgentsInstruction `json:"agents_instruction,omitempty"`
	HookRun           *HookRun           `json:"hook_run,omitempty"`
}

type ItemID string

type ItemKind string

type Message struct {
	From    *Address   `json:"from"`
	To      *Address   `json:"to"`
	Content []*Content `json:"content"`
	// AgentSender 由 Conversation 在 Agent 之间转交消息时写入，模型请求据此标明消息来自哪个 Agent；用户消息为 nil。
	AgentSender *AgentSender `json:"agent_sender,omitempty"`
	// SubagentNotification 由 Conversation 在子 Agent 的 Turn 结束、通知父 Agent 时写入；其他消息为 nil。
	SubagentNotification *SubagentNotification `json:"subagent_notification,omitempty"`
}

type ModelCallID string

type ModelCapabilities struct {
	// Input 是模型能接收的输入，例如 [text, image]。
	Input []ModelInput `json:"input"`
}

type ModelChange struct {
	PreviousModel ModelRef `json:"previous_model"`
	Model         ModelRef `json:"model"`
}

type ModelDefaults struct {
	ContextWindow          int      `mapstructure:"context_window" yaml:"context_window" default:"256000" json:"context_window"`
	MaxOutputTokens        int      `mapstructure:"max_output_tokens" yaml:"max_output_tokens" default:"32000" json:"max_output_tokens"`
	Thinking               bool     `mapstructure:"thinking" yaml:"thinking" default:"true" json:"thinking"`
	ReasoningEfforts       []string `mapstructure:"reasoning_efforts" yaml:"reasoning_efforts" json:"reasoning_efforts"`
	DefaultReasoningEffort string   `mapstructure:"default_reasoning_effort" yaml:"default_reasoning_effort" json:"default_reasoning_effort"`
	MergeMessageRoles      []string `mapstructure:"merge_message_roles" yaml:"merge_message_roles" json:"merge_message_roles"`
	// Capabilities 是模型配置省略 capabilities 时使用的能力；Input 为空时按 [text]。
	Capabilities ProviderModelCapabilities `mapstructure:"capabilities" yaml:"capabilities" json:"capabilities"`
}

type ModelDefinition struct {
	Ref         ModelRef `json:"ref"`
	DisplayName string   `json:"display_name"`
	// Target 是连接参数，含凭证，不序列化。
	Target          *llmkit.Target `json:"-"`
	ContextWindow   int            `json:"context_window"`
	MaxOutputTokens int            `json:"max_output_tokens"`
	ThinkingEnabled bool           `json:"thinking_enabled"`
	// ReasoningEfforts 是可选的推理强度；为空表示不支持选择，请求不带强度。
	ReasoningEfforts       []string `json:"reasoning_efforts"`
	DefaultReasoningEffort string   `json:"default_reasoning_effort,omitempty"`
	// MergeMessageRoles 是发送前需要合并相邻同角色消息的角色；为空表示不合并。
	MergeMessageRoles []llmkit.Role `json:"merge_message_roles,omitempty"`
	// ReasoningContext 是请求要求保留的思考上下文；为空表示请求不发送，服务端按默认处理，只用于 openai-responses 协议。
	ReasoningContext llmkit.ReasoningContext `json:"reasoning_context,omitempty"`
	Capabilities     ModelCapabilities       `json:"capabilities"`
}

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

type ModelInput string

type ModelRef struct {
	ProviderID string `json:"provider_id"`
	ModelID    string `json:"model_id"`
}

type ModelSelection struct {
	Ref ModelRef `json:"ref"`
	// ReasoningEffort 是选的推理强度；为空时用模型的默认强度。
	ReasoningEffort string `json:"reasoning_effort,omitempty"`
}

type OptionalStringList []string

type Plugin struct {
	Name      string
	Version   string
	Directory string // serve 本机的插件根目录，绝对路径
	// SkillDirectories 是按扫描顺序排列的技能目录绝对路径；没有 skill 时为空。
	SkillDirectories []string
	// InstalledAt 是安装记录里的 installed_at，每次 plugin update 都会变；手动放入的插件为零值。
	InstalledAt time.Time
}

type ProviderConfig struct {
	ID string `yaml:"id" json:"id"`
	// Protocol 是模型没写 protocol 时用的协议：openai_chat、openai_responses 或 claude；省略为 openai_responses。
	Protocol string `yaml:"protocol,omitempty" json:"protocol,omitempty"`
	// BaseURL 带版本前缀，例如 https://api.openai.com/v1；各协议默认在后面拼 /chat/completions、/responses、/messages。
	BaseURL string `yaml:"base_url" json:"base_url"`
	// Endpoints 按协议写完整请求地址，写了的协议不再用 BaseURL 拼，可以是别的 host。
	Endpoints map[string]string `yaml:"endpoints,omitempty" json:"endpoints,omitempty"`
	APIKey    string            `yaml:"api_key" json:"api_key"`
	// Models 是模型 id 到模型配置的映射；值为 nil 时全部用默认。
	Models map[string]*ProviderModelConfig `yaml:"models" json:"models"`
}

type ProviderModelCapabilities struct {
	// Input 为 nil 时取 config.yaml 的 models.defaults.capabilities.input。
	Input OptionalStringList `mapstructure:"input" yaml:"input,omitempty" json:"input,omitzero"`
}

type ProviderModelConfig struct {
	// Protocol 省略时用 Provider 的 protocol。
	Protocol      string `yaml:"protocol,omitempty" json:"protocol,omitempty"`
	UpstreamModel string `yaml:"upstream_model,omitempty" json:"upstream_model,omitempty"`
	// DisplayName 省略时用模型 id。
	DisplayName     string `yaml:"display_name,omitempty" json:"display_name,omitempty"`
	ContextWindow   int    `yaml:"context_window,omitempty" json:"context_window,omitempty"`
	MaxOutputTokens int    `yaml:"max_output_tokens,omitempty" json:"max_output_tokens,omitempty"`
	Thinking        *bool  `yaml:"thinking,omitempty" json:"thinking,omitempty"`
	// ReasoningEfforts 为 nil 时继承全局默认，[] 表示明确不支持选择。
	ReasoningEfforts       OptionalStringList `yaml:"reasoning_efforts,omitempty" json:"reasoning_efforts,omitzero"`
	DefaultReasoningEffort string             `yaml:"default_reasoning_effort,omitempty" json:"default_reasoning_effort,omitempty"`
	// MergeMessageRoles 为 nil 时继承全局默认，[] 表示明确不合并。
	MergeMessageRoles OptionalStringList `yaml:"merge_message_roles,omitempty" json:"merge_message_roles,omitzero"`
	// ReasoningContext 是请求要求保留的思考上下文，可写 all_turns 或 current_turn；省略时请求不发送、
	// 服务端按默认处理，不从 models.defaults 继承，只用于 openai-responses 协议。
	ReasoningContext string                    `yaml:"reasoning_context,omitempty" json:"reasoning_context,omitempty"`
	Capabilities     ProviderModelCapabilities `yaml:"capabilities,omitempty" json:"capabilities,omitzero"`
}

type Reasoning struct {
	Status    ReasoningStatus `json:"status"`
	Summary   []string        `json:"summary,omitempty"`
	Content   []string        `json:"content,omitempty"`
	Encrypted string          `json:"encrypted,omitempty"`
	RawJSON   json.RawMessage `json:"raw_json,omitempty"`
}

type ReasoningStatus string

type SSHExecutorDefinition struct {
	// Address 是 [user@]host[:port]。
	Address string
	// IdentityFile 是本机私钥路径，已展开 ~；为空时依次使用 ssh-agent 与默认私钥。
	IdentityFile string
}

type Session struct {
	ID SessionID `json:"id"`
	// UpdatedAt 是最后一次写入的 Unix 毫秒，由存储在写入时分配；写入时设置的值不会被保存。
	UpdatedAt      int64          `json:"updated_at,omitempty"`
	ConversationID ConversationID `json:"conversation_id"`
	AgentName      string         `json:"agent_name"`
	// TaskName 是 spawn_agent 给子 Agent 起的任务名；根 Session 为空。
	TaskName string `json:"task_name,omitempty"`
	// ParentSessionID、ParentTurnID、ParentCallID 是创建这个子 Agent 的父 Session、Turn 和 spawn_agent 调用；根 Session 为空。
	ParentSessionID SessionID `json:"parent_session_id,omitempty"`
	ParentTurnID    TurnID    `json:"parent_turn_id,omitempty"`
	ParentCallID    string    `json:"parent_call_id,omitempty"`
	// Model 是解析后的模型和推理强度，新建或切换模型时写入；零值按 Agent 默认模型处理。
	Model ModelSelection `json:"model,omitzero"`
}

type SessionFork struct {
	// SourceSessionID 是历史来源的 Session。
	SourceSessionID SessionID `json:"source_session_id"`
	// SourceConversationID 是用户分叉的来源对话；spawn_agent 写的分界为空。
	SourceConversationID ConversationID `json:"source_conversation_id,omitempty"`
	// SourceEndOrdinal 是来源日志里第一条复制过来的 Item 的序号（来源对外的序号）；接上的部分是 [1, SourceEndOrdinal)。
	SourceEndOrdinal int64 `json:"source_end_ordinal,omitempty"`
}

type SessionID string

type SkillInstruction struct {
	// InputItemID 是点名这个 Skill 的用户输入 Item。
	InputItemID ItemID `json:"input_item_id"`
	Name        string `json:"name"`
	Path        string `json:"path"`
	Executor    string `json:"executor"`
	Text        string `json:"text"`
}

type SubagentNotification struct {
	// SourceTurnID 是子 Agent 结束的那个 Turn。
	SourceTurnID TurnID `json:"source_turn_id"`
	// Status 是那个 Turn 保存的终态。
	Status TurnStatus `json:"status"`
}

type TextContent struct {
	Text string `json:"text"`
	// IsContext 是不是附带材料？附带材料不参与用户命令解析。
	IsContext bool `json:"is_context,omitempty"`
}

type TokenUsage struct {
	Input      int `json:"input"`
	Output     int `json:"output"`
	CacheRead  int `json:"cache_read"`
	CacheWrite int `json:"cache_write"`
	Reasoning  int `json:"reasoning"`
}

type ToolCall struct {
	CallID    string `json:"call_id"`
	Name      string `json:"name"`
	Arguments string `json:"arguments"`
	// Status 为空时参数还在生成。
	Status ToolCallStatus `json:"status,omitempty"`
}

type ToolCallStatus string

type ToolDefinition struct {
	Name        string          `json:"name"`
	Description string          `json:"description"`
	InputSchema json.RawMessage `json:"input_schema"`
	// MCPServerID 是提供这个工具的 MCP server；内置工具和协作工具为空。不发给模型。
	MCPServerID string `json:"mcp_server_id,omitempty"`
}

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

type ToolResult struct {
	CallID string `json:"call_id,omitempty"`
	// Executor 是实际执行这次调用的 Executor；Agent 侧工具（spawn_agent 等）和没能分派的调用为空。
	Executor string          `json:"executor,omitempty"`
	Content  json.RawMessage `json:"content,omitempty"`
	// Images 是工具读到、要给模型看的图片；Alt 写模型传入的路径。发给模型时放进这串工具结果之后的一条用户消息。
	Images []*ImageContent `json:"images,omitempty"`
	Error  *ToolError      `json:"error,omitempty"`
	// Truncated 工具输出是否超长被截断了？
	Truncated bool `json:"truncated,omitempty"`
}

type Turn struct {
	ID TurnID `json:"id"`
	// UpdatedAt 是最后一次写入的 Unix 毫秒，由存储在写入时分配；写入时设置的值不会被保存。
	UpdatedAt int64 `json:"updated_at,omitempty"`
	// ConversationID 是所属对话；DAO 据此找到对话目录里的 metadata.jsonl。
	ConversationID ConversationID `json:"conversation_id"`
	SessionID      SessionID      `json:"session_id"`
	Status         TurnStatus     `json:"status"`
	// FinalModelCallID 是本轮最后一次成功的普通模型调用；只在 completed 时填写。
	FinalModelCallID ModelCallID `json:"final_model_call_id,omitempty"`
	// Error 是 Turn 失败或被中断时的错误说明。
	Error      string        `json:"error,omitempty"`
	ItemsRange TurnItemRange `json:"items_range,omitzero"`
	// Usage 是本 Turn 全部模型调用（包括压缩）的用量合计，写入终态时填写；running 时为零。
	Usage TokenUsage `json:"usage,omitzero"`
	// ContextUsage 是最近一次完整普通调用的报告；本轮没有完整普通调用时沿用上一轮的报告，模型切换后为空。
	ContextUsage *TurnContextUsage `json:"context_usage,omitempty"`
	// Model 是本 Turn 实际使用的模型和推理强度，创建 running 记录时写入。
	Model ModelSelection `json:"model,omitzero"`
	// Executors 是本 Turn 开始时对话可用的 Executor，按顺序，第一个是默认；创建 running 记录时写入。
	Executors []TurnExecutor `json:"executors,omitempty"`
}

type TurnContextUsage struct {
	ModelCallID ModelCallID `json:"model_call_id"`
	// InputThroughItemID 是请求发出前上下文最后一条 Item，不含该次生成输出。
	InputThroughItemID ItemID `json:"input_through_item_id"`
	// Usage 是服务端上报并已归一化的用量；没有上报时为零值。
	Usage            TokenUsage              `json:"usage,omitzero"`
	ReasoningContext llmkit.ReasoningContext `json:"reasoning_context,omitempty"`
}

type TurnExecutor struct {
	ID                 string `json:"id"`
	WorkspaceDirectory string `json:"workspace_directory"`
}

type TurnID string

type TurnItemRange struct {
	FirstOrdinal uint64 `json:"first_ordinal"`
	LastOrdinal  uint64 `json:"last_ordinal"`
}

type TurnStatus string