native

type AgentParams struct {
	Prompt         string            `json:"prompt,omitempty"`
	Prompts        []AgentTaskParams `json:"prompts,omitempty"`
	MaxConcurrency int               `json:"max_concurrency,omitempty"`
}

type AgentTaskParams struct {
	// Name 是子任务名称，用于在汇总结果里标识来源；为空时自动编号。
	Name string `json:"name,omitempty"`
	// Prompt 是该子 Agent 的任务描述。
	Prompt string `json:"prompt"`
}

type AgentToolConfig struct {
	// NewClient 构建子 Agent 的 LLM 客户端；每次执行时调用（批量模式下每个子任务各一次），
	// 返回的错误会转成该子任务的失败结果。
	//
	// 由 Provider 基于父请求的模型 / 厂商配置实现（见 providers.customAgent）。
	NewClient func(ctx context.Context) (provider.Client, error)
	// Tools 是子 Agent 可用的工具集合；为 nil 时使用 TaskAgentTools()（只读集合）。
	Tools *tool.Registry
	// PrepareToolContext 在子 Agent 每次工具执行前装饰 ctx（权限 / 运行时上下文 / 技能等）。
	//
	// 通常直接复用父 Agent 的 toolContext：子 Agent 与父 Agent 处在同一个工作目录、
	// 同一个业务上下文里，只读工具也不需要额外的授权声明。
	PrepareToolContext func(context.Context) context.Context
	// WorkingDir 是子 Agent 的工作目录；为空时沿用工具执行 ctx 中的运行时上下文。
	WorkingDir string
	// SystemPrompt 是子 Agent 的系统提示词；为空时回退到 TaskAgentSystemPrompt。
	SystemPrompt string
	// MaxConcurrency 是批量模式下默认的并发子 Agent 数；<=0 时使用 defaultAgentConcurrency，
	// 超过 MaxAgentConcurrency 时按上限截断。
	MaxConcurrency int
	// SessionStore 把子 Agent 的会话与消息写入数据库（必填）。
	//
	// 子 Agent 始终拥有自己的会话：父请求有会话 ID 时创建 ParentSessionID = 父会话的
	// 子会话，否则（如 AI 摘要等无会话任务）创建一个独立会话；会话创建失败会让该
	// 子任务失败，不再降级为「无会话、事件丢弃」的执行。
	SessionStore SubAgentSessionStore
	// ParentRuntime 是父 Agent 的 Runtime：子 Agent 的权限 / 提问委托给它，
	// 事件仍只写入子会话（不污染父任务时间线）。
	ParentRuntime agentinterfaces.Runtime
	// Provider / Model 是写入子会话的溯源信息（可为空）。
	Provider string
	Model    string
	// ParentSessionID / UserID 是父请求的会话与用户 ID（回退值）。
	//
	// 正常情况下从工具执行 ctx 的 RuntimeContext 读取；ctx 没有时用这里的值，
	// 保证 Request.SessionID 设置了但 RuntimeContext 缺失的场景也能落库。
	ParentSessionID int64
	UserID          int64
}

type Config struct {
	Client provider.Client
	Tools  *tool.Registry
	// PrepareToolContext 在每次工具执行前装饰 ctx（注入权限、运行时上下文、技能等）。
	PrepareToolContext func(context.Context) context.Context
	// OnStart / OnFinish 是执行生命周期钩子（可选）：OnFinish 在本次 Run 返回前被调用，
	// 用于释放执行期创建的资源（如宿主机持久 shell）。
	// 循环本身不关心具体工具，因此由 Provider 注入，不形成对工具实现的依赖。
	OnStart  func(context.Context)
	OnFinish func(context.Context)
}

type SubAgentSessionInfo struct {
	// ProjectID 是会话所属项目（与父请求保持一致，可为 0）。
	ProjectID int64
	// ParentSessionID 是父会话 ID（写入 agent_sessions.parent_session_id）；
	// 为 0 表示创建独立会话。
	ParentSessionID int64
	// Title 是子会话标题（优先使用子任务名，否则截取 prompt 首行）。
	Title string
	// UserID 是会话归属用户（从父请求的 RuntimeContext 读取）。
	UserID int64
	// Provider / Model 记录本次子 Agent 使用的 Provider 与模型。
	Provider string
	Model    string
}

type SubAgentSessionStore interface {
	// CreateChildSession 创建 ParentSessionID = info.ParentSessionID 的子会话并返回会话 ID。
	CreateChildSession(ctx context.Context, info SubAgentSessionInfo) (int64, error)
	// CreateSession 创建一个独立会话（无父会话时使用）并返回会话 ID。
	CreateSession(ctx context.Context, info SubAgentSessionInfo) (int64, error)
	// AppendUserMessage 追加子任务的 user 消息。
	AppendUserMessage(ctx context.Context, sessionID int64, content string) error
	// AppendEvent 把一条流式事件投影为子会话消息（投影规则由实现方决定，通常复用
	// agentservice.ProjectTimelineEvent；不产生消息的事件直接忽略）。
	AppendEvent(ctx context.Context, sessionID int64, event agenttypes.StreamEvent) error
	// AppendFinalMessage 追加子 Agent 的最终回答（或错误信息）。
	AppendFinalMessage(ctx context.Context, sessionID int64, content string) error
}