// Package runtime 定义智能体执行端口与实现：mock（脚本回放）与 LLM
// （复用 agent-native 的 OpenAI 兼容流式客户端）。执行编排归 runmgr。
package runtime

import (
	"context"

	core "agent-system-core"
)

// RunCtx 是 Runner 的受控环境（由 runmgr 实现）：事件发布、HITL、子代理、
// 工件、检索、工具执行、历史。Runner 不得绕过 RunCtx 直接写库。
type RunCtx interface {
	Context() context.Context
	Run() core.Run
	Profile() core.AgentProfile
	Settings() core.EffectiveSettings
	Emit(typ core.StreamEventType, payload any) error
	SetAssistantParts(parts []core.Part) error
	AskHITL(card core.HITLCard) (core.HITLResponse, error)
	SpawnSubagent(name, task string, hint string) (core.AgentResultPayload, error)
	UpdatePlan(p core.PlanSnapshot) error
	UpdateTodos(l core.TodoList) error
	WriteArtifact(name, kind, mime string, content []byte) (core.Artifact, error)
	Retrieve(q core.RetrievalQuery) ([]core.RetrievalHit, error)
	ExecuteTool(call core.ToolCallRequest) core.ToolCallResult
	History() []core.Message
	Attachments() []core.ParsedDocument
	// Tools 返回注册表全部工具（画像过滤由 runner 做）。
	Tools() []core.ToolDesc
	// Subtask 返回子代理任务描述（仅 subagent run 有值）。
	Subtask() string
	// SetContextObservation 记录本次运行的上下文组装观测（随 run.completed 下发）。
	SetContextObservation(o core.ContextObservation)
}

// Runner 执行一个 run 至终态：返回 nil = completed；ctx 取消应返回 ctx.Err()。
type Runner interface {
	Name() string
	Execute(rc RunCtx) error
}