subagent

type Config struct {
	Name        string
	Description string
	// Model is resolved when each sub-agent run starts. Wrappers that swap the
	// underlying model at runtime (e.g. agentcore.SwappableModel) take effect
	// on the next sub-agent run.
	Model        agentcore.ChatModel
	SystemPrompt string
	// SystemPromptMode is a host-interpreted hint controlling how
	// SystemPrompt composes with the host's base prompt. agentcore does
	// NOT consume this field — the team spawner / executor on the host
	// side reads it to assemble AgentContext.SystemBlocks. Kept as a
	// plain string at the boundary so agentcore stays agnostic to enum
	// values that only matter inside one host; empty / unrecognized
	// values fall back to the host's default mode.
	SystemPromptMode string
	Tools            []agentcore.Tool
	MaxTurns         int

	// ToolGate, when non-nil, is called once per tool call in this
	// sub-agent's runs — same contract as agentcore.WithToolGate for
	// top-level agents (nil decision = allow, UpdatedArgs rewrites the
	// executed arguments). Without it a sub-agent's tools run ungated, so
	// a harness with a permission system should thread its gate here.
	ToolGate agentcore.ToolGate

	// Middlewares wrap each tool execution in this sub-agent's runs
	// (outermost first). Mirrors agentcore.WithMiddlewares.
	Middlewares []agentcore.ToolMiddleware

	// ThinkingLevel sets the reasoning depth for this sub-agent's runs.
	// Empty ("") leaves it unspecified (model/provider default). Mirrors
	// agentcore.WithThinkingLevel for top-level agents. A runtime override
	// installed via Runner.SetThinkingLevel takes precedence over this baseline.
	ThinkingLevel agentcore.ThinkingLevel

	// MaxRetries caps the LLM call retry count for retryable errors within
	// this sub-agent's loop. 0 (default) disables retry entirely.
	MaxRetries int

	// StopAfterTools lists tool names that trigger early loop exit after
	// successful execution.
	StopAfterTools []string

	// StopAfterToolResult is the result-aware variant of StopAfterTools.
	StopAfterToolResult func(toolName string, result json.RawMessage) bool

	// OnMessage, if non-nil, is called after each message is appended to
	// context. The agentName and task are provided for session routing.
	OnMessage func(agentName, task string, msg agentcore.AgentMessage)

	// Optional context lifecycle hooks for long-running sub-agents.
	ContextManager        agentcore.ContextManager
	ContextManagerFactory func(model agentcore.ChatModel) agentcore.ContextManager
	ConvertToLLM          func(msgs []agentcore.AgentMessage) []agentcore.Message

	// CacheLastMessage, when non-empty, tags the last non-system message of
	// every LLM request in this sub-agent's loop with the given cache_control
	// value ("ephemeral", or "ephemeral:1h" for extended TTL). Mirrors
	// agentcore.WithCacheLastMessage for top-level agents; see that option
	// for placement semantics.
	CacheLastMessage string

	// PromptCacheKey is the base prompt-cache routing identity for this
	// sub-agent's LLM requests. Each spawn appends "#<seq>" so every run gets
	// its own cache lineage — one conversation, one key — which providers
	// with key-routed prefix caching (OpenAI prompt_cache_key) use to keep a
	// session's requests on the same cache shard. Empty sends no hint.
	PromptCacheKey string

	// StopGuardFactory, if non-nil, creates a fresh StopGuard for each run.
	StopGuardFactory func(agentName, task string) agentcore.StopGuard
}

type RunMeta struct {
	Agent      string
	InstanceID string
	Mode       string
}

type RunResult struct {
	// Agent is the registered agent definition that ran.
	Agent string

	// Output is the final assistant text. Unlike the LLM tool-call surface,
	// it is NOT concatenated with TerminalResult and has no "(no output)"
	// placeholder — an agent that only called tools yields "".
	Output string

	// TerminalResult is the successful result of the tool that triggered a
	// StopAfterTools / StopAfterToolResult exit, nil when the run ended some
	// other way.
	TerminalResult json.RawMessage

	// Usage carries aggregated counters. Populated on both success and
	// failure paths (a run that errors mid-way still consumed tokens);
	// zero-valued when the run never started (e.g. unknown agent).
	Usage Usage
}

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

type TeamSpawnRequest struct {
	// Config is the resolved sub-agent definition the teammate runs as.
	// Spawner reads SystemPrompt, Tools, Model, MaxTurns etc. from here.
	Config Config

	// Name is the teammate's identifier inside the team (routing key for
	// send_message). May equal Config.Name when the LLM did not specify one.
	Name string

	// TeamName is the active team's name; spawner validates against registry.
	TeamName string

	// InitialPrompt is the leader's first message to the teammate.
	InitialPrompt string

	// Description is an optional one-line summary for transcripts/UI.
	Description string

	// Color is an optional UI color assigned to this teammate.
	Color string

	// Model is non-nil when the LLM requested an override; nil means the
	// spawner should fall back to Config.Model.
	Model agentcore.ChatModel

	// History, if non-empty, seeds the teammate's conversation before its
	// first turn — the spawner forwards it to team.SpawnConfig.History. The
	// LLM never sets this; a harness populates it when resuming a teammate
	// with its prior transcript after a restart. nil ⇒ fresh teammate.
	History []agentcore.AgentMessage
}

type TeamSpawnResult struct {
	TaskID  string
	AgentID string // "name@team"
}

type TeamSpawner func(ctx context.Context, req TeamSpawnRequest) (*TeamSpawnResult, error)

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

type UnknownAgentError struct {
	Agent     string
	Available []string
}

type Usage struct {
	Input      int     `json:"input"`
	Output     int     `json:"output"`
	CacheRead  int     `json:"cache_read"`
	CacheWrite int     `json:"cache_write"`
	Cost       float64 `json:"cost"`
	Turns      int     `json:"turns"`
	Tools      int     `json:"tools"`
}