profiles

type Assistant struct {
	// Skills is the Agent Skills it may use, by name.
	Skills []string
	// MaxTurns caps its steps, and ZERO means no cap: a step cap fires mid-answer on a turn
	// that is working, which is why it is off unless somebody asks for it.
	MaxTurns int
	// Timeout is the wall clock that bounds a turn instead, always positive. It is what
	// stops a stuck turn running for ever on the conductor's own machine.
	Timeout time.Duration
}

type Backend struct {
	ID          string
	DisplayName string
	Provider    string
	Note        string
	// DefaultModel is what a profile naming this backend and no model runs.
	DefaultModel string
	Models       []Model
}

type Choice struct {
	Agent  string
	Model  string
	Effort string
}

type GitPersona struct {
	Name  string `yaml:"name" json:"name"`
	Email string `yaml:"email" json:"email"`
}

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

type Model struct {
	ID            string
	DisplayName   string
	Note          string
	ContextTokens int
	// Efforts are the levels this model accepts, weakest first. Empty means the model takes
	// no effort setting at all, and naming one for it is refused.
	Efforts []string
}

type Override struct {
	Agent  string
	Model  string
	Effort string
}

type Overrides struct {
	DisplayName     string    `json:"display_name,omitempty"`
	Model           string    `json:"model,omitempty"`
	Agent           string    `json:"agent,omitempty"`
	Effort          string    `json:"effort,omitempty"`
	DefaultPlaybook string    `json:"default_playbook,omitempty"`
	UpdatedBy       string    `json:"updated_by,omitempty"`
	UpdatedAt       time.Time `json:"updated_at,omitzero"`
}

type Playbook struct {
	Image        string        `yaml:"image" json:"image"`
	SystemPrompt string        `yaml:"system_prompt" json:"system_prompt"`
	AllowedTools []string      `yaml:"allowed_tools" json:"allowed_tools"`
	MaxTurns     int           `yaml:"max_turns" json:"max_turns"`
	Timeout      spec.Duration `yaml:"timeout" json:"timeout"`
	Model        string        `yaml:"model" json:"model,omitempty"`
	Agent        string        `yaml:"agent" json:"agent,omitempty"`
	Effort       string        `yaml:"effort" json:"effort,omitempty"`
	Labels       []string      `yaml:"labels" json:"labels,omitempty"`
	// Priority is where a turn of this playbook goes in Podium's queue: the scheduler
	// claims higher first and breaks ties by age. Zero is the default and negative is
	// allowed, so a playbook that grinds for two hours can be told to wait behind
	// everything somebody is watching.
	//
	// It is a sort key and not a budget: it changes what runs next when the fleet is full,
	// and nothing at all about what a turn is given or how long it may take.
	Priority  int              `yaml:"priority" json:"priority,omitempty"`
	Resources spec.Resources   `yaml:"resources" json:"resources,omitempty"`
	Secrets   []spec.SecretRef `yaml:"secrets" json:"secrets,omitempty"`
	Repos     []Repo           `yaml:"repos" json:"repos,omitempty"`
	// Git is who this playbook's turns commit as: it overrides the profile's, and unset
	// inherits it. Unset in both leaves the runtime's fallback, which belongs to no GitHub
	// account — see GitPersona for why that is a deployment failure rather than a cosmetic one.
	Git           GitPersona        `yaml:"git" json:"git,omitzero"`
	SlackChannels []string          `yaml:"slack_channels" json:"slack_channels,omitempty"`
	Env           map[string]string `yaml:"env" json:"env,omitempty"`
	// Skills is the Agent Skills a turn of this playbook may use, by name, out of
	// PODIUM_AGENT_SKILLS_DIR on the conductor's host. Nothing is implicit: a playbook that
	// names none gets none, and the harness's own permission map denies every skill it has
	// not been told about — including the ones built into the harness.
	//
	// An Agent Skill is executable content somebody else wrote, and it runs in the turn's
	// container with that turn's credentials. This list is the whole of what decides which
	// ones do. See docs/security.md.
	Skills []string `yaml:"skills" json:"skills,omitempty"`
	// MCPServers is the MCP servers a turn of this playbook may use, by name, out of the
	// registry an operator manages in the web UI. Nothing is implicit here either: a
	// playbook that names none gets none, and the runtime writes the harness exactly the
	// entries the brief carried.
	//
	// A server is somebody else's API with a credential attached, and the tools it exposes
	// run with whatever that credential can do. This list is the whole of what decides
	// which turns get which of them. See docs/security.md.
	MCPServers []string `yaml:"mcp_servers" json:"mcp_servers,omitempty"`
	// Docker gives the turn a real Docker daemon beside it: the conductor attaches a
	// privileged `dind` sidecar and points DOCKER_HOST at it. A playbook needs this to run a
	// dev stack, `docker compose`, or testcontainers.
	//
	// It only works on a node started with --allow-privileged-sidecars, and Podium places
	// on labels alone, so a playbook that sets this must also carry a label its operator put
	// on those nodes. Getting that wrong fails the turn with a message naming the flag
	// rather than hanging.
	Docker bool `yaml:"docker" json:"docker,omitempty"`

	// Browser gives the turn a headless Chrome of its own and the tools to drive it: the
	// conductor adds a browser sidecar and the runtime points an MCP server at it, so the
	// agent navigates, clicks and screenshots rather than shelling out to curl.
	//
	// The browser is a SIDECAR and not something in the image, which is what keeps it
	// isolated: its own container, its own profile, its own network namespace, thrown away
	// with the task. It needs no privilege — unlike `docker`, this asks nothing of the node
	// beyond an ordinary container, so it carries no label requirement.
	Browser bool `yaml:"browser" json:"browser,omitempty"`

	// Linear marks the one playbook Linear tickets run. Tickets are not chat, so there is no
	// /playbook prefix to route them and no channel to match: the flag is the routing rule.
	// At most one playbook may set it; zero means this bot does not take tickets, which is
	// only a misconfiguration when a Linear API key is also set — and the conductor says
	// so at start-up, where the key is known.
	Linear bool `yaml:"linear" json:"linear,omitempty"`

	// Interactive lets a turn ask a human a question and wait for the answer in the same
	// container, instead of ending the turn. Off by default: a waiting container still
	// holds a node slot (and a dind sidecar, if the playbook asked for one).
	Interactive bool `yaml:"interactive" json:"interactive,omitempty"`

	// Name is the file name without the extension.
	Name string `yaml:"-" json:"-"`
}

type Profile struct {
	Name         string `yaml:"name"`
	DisplayName  string `yaml:"display_name"`
	SystemPrompt string `yaml:"system_prompt"`
	Model        string `yaml:"model"`
	// Agent is the backend every playbook runs on unless it names its own. Empty is
	// DefaultAgent, so a profile.yaml written before Grok existed still loads.
	Agent string `yaml:"agent"`
	// Effort is the reasoning effort every playbook runs at unless it names its own. Empty
	// means the model's own default, which is what the provider picks.
	Effort string `yaml:"effort"`
	// DefaultPlaybook is unused. It is still decoded so a profile.yaml that names one
	// continues to load; Select does not fall back to it.
	DefaultPlaybook string `yaml:"default_playbook"`
	// Git is who every playbook's turns commit as unless the playbook names its own. It is
	// the DEFAULT and not the rule: the identity has to match the account behind the token
	// that pushes, and the GitHub token is a per-playbook secret, so a second playbook
	// pushing with a second token needs a persona of its own.
	Git GitPersona `yaml:"git"`
	// Skills is the Agent Skills the ASSISTANT may use — the turn the conductor answers a
	// conversation with, on this host. A playbook names its own; this is the other end of
	// that list and not a default for it, because the two turns are nothing alike: one has
	// a container and a workspace, and this one has a conversation.
	Skills []string `yaml:"skills"`
	// Timeout bounds one assistant turn on the wall clock. Zero is DefaultAssistantTimeout;
	// unlike MaxTurns there is no "off", because a turn with neither bound has no automatic
	// stop at all.
	Timeout spec.Duration `yaml:"timeout"`
	// MaxTurns caps one assistant turn's steps. UNSET MEANS NO CAP, which is the opposite of
	// a playbook's max_turns and deliberately so: the assistant answers a conversation and
	// delegates, so what is worth bounding is the container it starts rather than the relay
	// that started it, and a cap that fires mid-answer says "I ran out of turns" about a turn
	// that had not failed. An operator who wants a ceiling sets one.
	MaxTurns int `yaml:"max_turns"`

	// Playbooks is every playbooks/*.yaml, keyed by file name without the extension.
	Playbooks map[string]Playbook `yaml:"-"`
	// Dir is where the profile was loaded from.
	Dir string `yaml:"-"`
}

type Repo struct {
	Name          string `yaml:"name" json:"name"`
	URL           string `yaml:"url" json:"url"`
	DefaultBranch string `yaml:"default_branch" json:"default_branch"`
}

type Routing struct {
	// Playbook is a playbook the source KNOWS is right, and which no routing rule may
	// second-guess: Linear's linear: true playbook. Empty means the rules decide. Slack
	// always leaves it empty.
	Playbook string
	// Channel is the routing key matched against a playbook's slack_channels.
	Channel string
	// Text is what the human said, a /playbook prefix included.
	Text string
}

type Selection struct {
	// Playbook is the playbook that will run the turn.
	Playbook Playbook
	// Instruction is the triggering text with a /playbook prefix stripped.
	Instruction string
	// Explicit is true when the caller named the playbook — a /playbook prefix, or a source that
	// chose one itself. An explicit playbook that disagrees with an existing session's playbook is
	// refused rather than honoured: one session, one playbook. A default is never explicit.
	Explicit bool
}