serve

type AuthSurfaceBuilder func(red audit.Redactor, bus events.EventBus, logger *slog.Logger) (*auth.RotateSurface, error)

type AuthValidatorFactory func(ctx context.Context, cfg *config.Config, red audit.Redactor, bus events.EventBus, logger *slog.Logger) (auth.Validator, error)

type BuiltMux struct {
	// Mux is the transports mux the caller mounts under /v1/.
	Mux *http.ServeMux
	// FlowRegistry is the empty registry the flows surface serves. Nil when
	// the flows surface was not mounted (no artifact store / task registry).
	FlowRegistry *flow.Registry
}

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

type ExtraRoutesFunc func(ctx context.Context, m RouteMount) ([]func(context.Context) error, error)

type Handle struct {
	// Cfg / Bus are exported so a supervising caller (the dev hot-reload
	// loop) can read the reload policy and publish reload lifecycle events.
	Cfg *config.Config
	Bus events.EventBus
	// contains filtered or unexported fields
}

type LLMSnapshotBuilder func(cfg *config.Config) (*llm.ConfigSnapshot, error)

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

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

type MuxInput struct {
	Cfg     *config.Config
	Surface *protocol.ControlSurface
	Bus     events.EventBus
	// Redactor / Logger / Metrics feed every surface's audit + posture legs.
	Redactor audit.Redactor
	Logger   *slog.Logger
	Metrics  *telemetry.MetricsRegistry
	// LLMSnapshot is the resolved snapshot the posture provider projects.
	LLMSnapshot llm.ConfigSnapshot

	// Core subsystem handles.
	Tasks          tasks.TaskRegistry
	Sessions       *sessions.Registry
	Agents         *agentregistry.Registry
	Artifacts      artifacts.ArtifactStore
	Memory         memory.MemoryStore
	Catalog        tools.ToolCatalog
	Coordinator    pauseresume.Coordinator
	MCPRegistry    *mcpdrv.Registry
	MCPToolContext *mcpconsole.ToolContextStore
	State          state.StateStore
	Skills         skills.SkillStore

	// Control-plane handles.
	AgentConfig    agentcfg.Registry
	AgentConfigID  string
	SessionOverlay sessionoverlay.Store
	RunsStore      *runsprotocol.Store
	// RunLoopDriver backs the tasks.get trajectory enricher. Nil leaves
	// tasks reads un-enriched (a stack without a run loop).
	RunLoopDriver  *RunLoopDriver
	OAuthProviders map[string]toolauth.OAuthProvider

	// Governance handles. TenantOverridePolicy backs governance.set/get
	// tenant overrides; KeyRotator backs governance.rotate_key. Both are
	// built caller-side (the policy is shared with the run-loop driver; the
	// rotator's lifecycle is the assembly's).
	TenantOverridePolicy *governance.TenantOverridePolicy
	KeyRotator           *llm.ProviderKeyRotator
	ValidModels          []string

	// MCPAttacher backs agent_config.add_mcp_connection. Built caller-side so
	// its Close joins the caller's closer chain; nil leaves the add verb
	// unwired.
	MCPAttacher       agentcfgprotocol.ConnectionAttacher
	MCPStdioAllowlist []string
	BootDeclaredMCP   []string

	// Auth. Validator nil mounts the transports WithoutValidator (the
	// explicit test-kit opt-out); AuthSurface nil leaves auth.rotate_token
	// un-mounted (the production posture — no in-runtime token issuer).
	Validator   auth.Validator
	AuthSurface *auth.RotateSurface

	// Posture stamps.
	DisplayName  string
	InstanceID   string
	BuildVersion string
	BuildCommit  string
	// TopologyAvailable advertises the topology.snapshot capability (true
	// only when the caller wired a topology accessor onto the surface).
	TopologyAvailable bool
}

type Options struct {
	ConfigPath string

	// Config, when non-nil, is used directly instead of loading and
	// validating ConfigPath — the entry point for a caller that already
	// holds a validated (or programmatically-built) configuration.
	// Boot re-runs the full-binary Validate on it so a hand-built config
	// cannot bypass validation. When both Config and ConfigPath are set
	// Config wins; when Config is nil ConfigPath is loaded.
	Config *config.Config

	Port            int
	BindAddr        string
	Logger          *slog.Logger
	Stderr          io.Writer
	SubcommandLabel string

	// PreferConfigBindAddr opts into honoring the operator-configured
	// `server.bind_addr` (which may name a non-loopback interface) when no
	// explicit BindAddr override is given. ONLY the production serve caller
	// sets it. The dev/console callers leave it false so they stay
	// loopback-only on 127.0.0.1:<Port> — a dev boot against a serve-shaped
	// yaml must never expose the dev-token stack off-box.
	PreferConfigBindAddr bool

	// AuthValidatorFactory is REQUIRED (nil fails Boot loud).
	AuthValidatorFactory AuthValidatorFactory

	// MCPDefaultIdentity is the identity a boot-time / runtime-added MCP
	// connection dials under.
	MCPDefaultIdentity identity.Identity

	// DisplayName / InstanceID stamp the posture surface's runtime.info.
	DisplayName string
	InstanceID  string
	// BuildVersion / BuildCommit stamp runtime.info's build identity.
	BuildVersion string
	BuildCommit  string
	// DevAllowMock stamps the Serve start log's dev_allow_mock attribute —
	// the dev caller sets it when the mock escape hatch fired so an operator
	// reading the boot line sees the dev-only posture. A stamp only; the mock
	// gate itself is caller policy inside BuildLLMSnapshot.
	DevAllowMock bool

	// RegisterCatalog forwards a compiled-tool registrar onto the
	// assembly's pre-policy catalog seam (assemble.Options.RegisterCatalog):
	// a tool it registers is wrapped with its declared approval / OAuth /
	// policy shell before the run loop can dispatch it. Nil is a no-op —
	// the stock serve caller passes nil; an external serving binary passes
	// its agent's RegisterTools.
	RegisterCatalog func(catalog tools.ToolCatalog) error

	// Caller-side injection seams (all optional).
	BuildLLMSnapshot LLMSnapshotBuilder
	BuildAuthSurface AuthSurfaceBuilder
	ExtraRoutes      ExtraRoutesFunc
	PostBoot         PostBootFunc
}

type PostBootFunc func(ctx context.Context, h PostBootHandles) error

type PostBootHandles struct {
	Sessions  *sessions.Registry
	Agents    *agentregistry.Registry
	Tasks     tasks.TaskRegistry
	Artifacts artifacts.ArtifactStore
	Memory    memory.MemoryStore
	Tools     tools.ToolCatalog
	Flows     *flow.Registry
	Bus       events.EventBus
	Logger    *slog.Logger
}

type RouteMount struct {
	Router    *http.ServeMux
	Validator auth.Validator
	Bus       events.EventBus
	Redactor  audit.Redactor
	Logger    *slog.Logger
	// BindAddr is the resolved listen address (the bootstrap handler puts it
	// in its connection envelope).
	BindAddr string
}

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

type RunLoopDriverOptions struct {
	Logger   *slog.Logger
	Bus      events.EventBus
	RunLoop  *steering.RunLoop
	Planner  planner.Planner
	Tasks    tasks.TaskRegistry // mandatory: the FSM the driver advances on Run exit
	TaskKind tasks.TaskKind     // KindForeground at V1; the driver spawns RunLoops for this kind

	// driveBackground widens the driver to ALSO
	// drive KindBackground tasks — the ones a planner-emitted SpawnTask
	// creates. False (the default / legacy test path) keeps the
	// foreground-only behaviour. Recursion is bounded at the spawn site
	// by the dev executor's absolute_max_spawn_depth cap, not here.
	DriveBackground bool

	// RunContext consumer wiring. All three of
	// memory / skillsDirectory / planningHints are OPTIONAL: a dev
	// stack that did not open the respective subsystem hands nil; the
	// driver projects the corresponding RunContext field to nil and
	// the planner omits the wrapper. The skills
	// surface is the `skills.Directory` — the bounded,
	// pinned-then-recent, capability-filtered `<skills_context>`
	// producer (the directory carries its own MaxEntries cap; the
	// pre-111d SkillStore.Search + skillsContextMax pair is deleted).
	Memory          memory.MemoryStore
	MemoryRecall    memory.RecallSettings
	SkillsDirectory *skills.Directory
	PlanningHints   *planner.PlanningHints

	// tool dispatch + Catalog projection +
	// Trajectory. The tool catalog is the shared catalog the rest of
	// the dev stack already populated (in-process tools, MCP-discovered
	// tools, etc.). MaxStepsRunLoop caps the runloop's outer step
	// counter (separate from the planner-internal cap that goes onto
	// react via PlannerConfig.MaxSteps).
	Catalog         tools.ToolCatalog
	Executor        steering.ToolExecutor
	MaxStepsRunLoop int

	// operator-declared GrantedScopes
	// threaded into the per-run catalog view's CatalogFilter. Tools
	// whose AuthScopes exceed this set are invisible to the planner.
	// Nil / empty list means no scopes granted (the existing latent
	// default before the plumb-through).
	GrantedScopes []string

	// the artifact store the multimodal
	// materializer reads from. Required only when `task.InputArtifactIDs`
	// is non-empty (text-only tasks never touch the store). A nil
	// store with input artifacts on the task degrades gracefully —
	// the materializer emits text-stub-only references the LLM
	// routes via the catalog.
	ArtifactStore artifacts.ArtifactStore

	// trajectory compression. `tokenBudget`
	// projects onto RunSpec.Base.Budget.TokenBudget (the per-run
	// runtime budget — a run option, never
	// planner state); `compression` is the assembly-built
	// planner.CompressionRunner the runloop invokes at each step
	// boundary when the budget is non-zero. Both zero/nil (the
	// default) = compression off, byte-identical behaviour.
	TokenBudget int
	Compression *planner.CompressionRunner

	// the per-agent attachment disposition policy
	// decoded from `multimodal.disposition` (the middle precedence
	// layer of the disposition resolution). Zero value = no agent
	// policy; the runtime default applies.
	DispositionPolicy planner.DispositionPolicy

	// tenantOverrides resolves an admin-set tenant default for the run's
	// LLM parameters at run start (model / extra-instructions /
	// temperature / max-tokens / reasoning-effort). OPTIONAL — a nil
	// resolver means "no tenant defaults to apply" (the run uses the
	// agent/config defaults). When supplied, the driver reads it ONCE per
	// run and pins the resolved snapshot into the run's RunContext so the
	// swap lands on this run (next-turn relative to the admin's set), never
	// mid-flight.
	TenantOverrides TenantOverrideResolver

	// sessionOverrides is the in-process pending-override Store the
	// `runs.set_overrides` Service writes into. The driver Consumes the
	// session's pending override at run start (one-shot) and composes it
	// OVER the tenant default (session › tenant › config). OPTIONAL — a
	// nil Store means "no session overrides" (the run uses tenant/config
	// only). It is the SAME Store handed to the runs Service so a set and
	// the consume meet.
	SessionOverrides *runsprotocol.Store

	// agentConfig resolves the agent's active config revision at run start
	// (the agent-config control plane). OPTIONAL — a nil registry means
	// "no agent-config projection" (the run uses every directory-visible
	// skill). When supplied with a non-empty agentConfigID, the run reads
	// the active revision ONCE at run start and pins the resolved
	// skills-set into the per-run projection so a config edit applies on
	// the NEXT run (next-turn-only), never mid-flight.
	AgentConfig   agentcfg.Registry
	AgentConfigID string

	// sessionOverlay resolves the SESSION-scoped safe-subset overlay (the
	// non-admin lower tier) at run start: the session's user prompt layer,
	// narrow-only source/tool disables (UNIONED into the admin exclusion set
	// — can only narrow, never widen), and ephemeral personal skills. Keyed
	// by the REAL (tenant, user, session) triple, so it is session-isolated.
	// OPTIONAL — nil means "no session overlay" (the run uses the admin agent
	// config only). The SAME store the session-safe Protocol verbs write into.
	SessionOverlay sessionoverlay.Store

	// runCompletionHook is the static `runtime.hooks.run_completion`
	// projection (nil when unset). At run start the driver resolves the
	// effective hook via the shared projection (agent-config over this yaml
	// over none) and pins it into the RunSpec, so an edit lands next-run.
	RunCompletionHook *steering.CompletionHookSpec

	// connectionDetacher drives the DETACH leg of run-start reconciliation:
	// at run start the driver detaches every MCP server that is attached but
	// no longer declared by the agent's active config revision (a removed
	// connection, or a rollback past an add), so the next run's projected
	// catalog excludes it. OPTIONAL — nil means no reconcile (the
	// backward-compatible path). Injected at the cmd/harbor boundary (it
	// imports the concrete MCP driver; this driver stays driver-agnostic).
	ConnectionDetacher projection.ConnectionDetacher

	// bootDeclaredMCP is the set of boot-declared (yaml) MCP server names the
	// reconcile MUST NEVER detach (they are not revisioned state). Nil/empty
	// when no yaml server is declared.
	BootDeclaredMCP map[string]struct{}

	// namingDefault is the static `runtime.naming` fleet-default auto-naming
	// policy; the driver resolves the effective policy per run (agent-config
	// over this yaml over off). Opt-in, default off.
	NamingDefault config.RuntimeNamingConfig

	// sessionTitler is the session-registry seam the auto-naming trigger
	// writes/reads through (RecordCompletedTurn / AutoNamingState /
	// SetTitleAuto). The same *sessions.Registry the sessions Protocol routes
	// project over. Nil ⇒ no auto-naming trigger even when a policy resolves.
	SessionTitler steering.SessionTitler

	// namingLLM is the run's wrapped LLM client the ONE naming Complete call
	// flows through (governance/safety via ctx identity). Nil ⇒ no auto-naming
	// trigger.
	NamingLLM steering.NamingCompleter
}

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

type TenantOverrideResolver interface {
	Get(ctx context.Context, tenant string) (governance.TenantOverrideSpec, bool, error)
}