spawn

type BatchSpawnArgs struct {
	Agents []DynamicSpawnArgs `json:"agents"`
}

type BatchSpawnResult struct {
	WorkerIDs []string `json:"worker_ids"`
}

type CollectArgs struct {
	WorkerID  string `json:"worker_id"`
	TimeoutMs int    `json:"timeout_ms,omitempty"`
}

type CollectResult struct {
	Output string `json:"output"`
	Status string `json:"status"`
	Err    string `json:"error,omitempty"`
}

type DynamicLLM struct {
	Provider string `json:"provider,omitempty"`
	Model    string `json:"model,omitempty"`

	// Reasoning optionally sets how hard the worker thinks for models
	// that support it: one of "minimal" / "low" / "medium" / "high"
	// (empty = the model's default). Call list_models to see which
	// models accept reasoning and at which levels.
	Reasoning string `json:"reasoning,omitempty"`
}

type DynamicSpawnArgs struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	Prompt      string `json:"prompt"`

	LLM            DynamicLLM `json:"llm,omitempty"`
	Skills         []string   `json:"skills,omitempty"`
	MCPs           []string   `json:"mcps,omitempty"`
	AllowedSecrets []string   `json:"allowed_secrets,omitempty"`
	InitialMessage string     `json:"initial_message,omitempty"`
}

type InspectArgs struct {
	WorkerID   string `json:"worker_id"`
	SinceEvent int    `json:"since_event,omitempty"`
}

type KillArgs struct {
	WorkerID string `json:"worker_id"`

	// Reason is an optional explanation surfaced on the subsequent
	// collect_agent call as CollectResult.Err. The LLM can use it to
	// pass context ("superseded by newer plan", "worker stuck on
	// rate-limit", ...). Empty defaults to "killed by agent".
	Reason string `json:"reason,omitempty"`
}

type KillResult struct {
	OK bool `json:"ok"`
}

type ListResult struct {
	Workers []WorkerSummary `json:"workers"`
}

type NamedDescription struct {
	Name        string
	Description string
}

type QueryArgs struct {
	WorkerID string `json:"worker_id"`
	Message  string `json:"message"`
}

type QueryResult struct {
	OK bool `json:"ok"`
}

type RootDefaults struct {
	Provider string
	Model    string
}

type SpawnResult struct {
	WorkerID string `json:"worker_id"`
}

type SpawnStaticArgs struct {
	Name           string   `json:"name"`
	InitialMessage string   `json:"initial_message"`
	AllowedSecrets []string `json:"allowed_secrets,omitempty"`
}

type TemplateResolver interface {
	Resolve(name string) (config.AgentTemplate, bool)

	// ListTemplates returns every static-agent template currently
	// declared, in a stable order. Used by list_agents and by the
	// spawn_static_agent description so the LLM can see what is
	// actually available without trial-and-error.
	ListTemplates() []config.AgentTemplate
}

type TemplateSummary struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	Provider    string `json:"provider,omitempty"`
	Model       string `json:"model,omitempty"`
}

type TemplatesResult struct {
	Templates []TemplateSummary `json:"templates"`
}

type Tools struct {
	Manager   *workers.Manager
	Templates TemplateResolver

	// The next three fields are needed only when dynamic spawning is
	// enabled. Static-only deployments can leave them zero.
	Universe      Universe
	RootDefaults  RootDefaults
	EnableDynamic bool

	// ParentAllowedSecrets is the universe of secrets the spawning
	// agent itself can dereference. It bounds what its spawn calls
	// (static and dynamic) may grant to children — the secrets
	// pipeline enforces least-privilege from there.
	//
	// Two encodings:
	//
	//   - nil           → parent is "sovereign": no per-agent
	//                     restriction. Used for the root, which is
	//                     the user-facing coordinator and the
	//                     frontier of trust. Sub-agent allowlists
	//                     are validated against the global universe
	//                     of declared secrets in this mode.
	//   - non-nil slice → parent's explicit allowlist (possibly
	//                     empty). Sub-agent allowlists must be a
	//                     subset of this list, and an empty list
	//                     means the parent cannot delegate any
	//                     secret.
	//
	// Today only the root holds spawn tools, so this field is
	// effectively always nil in production. The shape is preserved
	// for the day a static template gets its own spawn tools.
	ParentAllowedSecrets []string
}

type Universe interface {
	ListSkills() []string
	ListMCPs() []string
	ListProviders() []string
	ListSecretNames() []string

	// MCPTools returns the names of the tools exposed by the named
	// MCP. Used by the spawn_dynamic_agent description so the LLM
	// understands what a worker actually inherits when it lists an
	// MCP in its spec — otherwise the model assumes from the MCP
	// name alone (e.g. it sees "filesystem" and concludes the MCP
	// is read/write only, missing that "exec" lives there too).
	// Returns nil for an unknown name; callers should not error.
	MCPTools(name string) []string

	// MCPExternal reports whether the named MCP uses an external
	// transport (http / stdio). Those connect lazily, so their tool
	// list is unknown at description-compose time and MCPTools
	// returns nil for them — not because the server is empty, but
	// because we haven't connected yet. writeMCPs uses this to phrase
	// the difference accurately ("tools resolve at call time") instead
	// of implying an external MCP advertises nothing.
	MCPExternal(name string) bool

	// SpawnSkillDetails and SecretDetails enrich the spawn
	// description with the metadata the LLM needs to choose well:
	// a skill's purpose (from frontmatter) and a secret's intent
	// (from the store's description field). Returning empty slices
	// is fine — composeDynamicDescription falls back to "(none)".
	// Skill variant is namespaced SpawnSkillDetails so it does not
	// collide with App.SkillDetails (which already exists for the
	// TUI's Settings overlay and returns a different shape).
	SpawnSkillDetails() []NamedDescription
	SecretDetails() []NamedDescription
}

type WorkerSummary struct {
	ID        string `json:"id"`
	Name      string `json:"name"`
	Kind      string `json:"kind"`
	Status    string `json:"status"`
	Elapsed   string `json:"elapsed"`
	LastEvent string `json:"last_event,omitempty"`
}