assemble

type Options struct {
	// Logger receives the pre-telemetry bootstrap warnings (the window
	// before the redactor + bus exist). Once the telemetry Logger is
	// constructed, the assembly threads its Slog() bridge into every
	// subsequently-built subsystem, so subsystem log lines flow
	// through the canonical pipeline.
	// Defaults to slog.Default().
	Logger *slog.Logger

	// LLMSnapshot, when non-nil, overrides the snapshot Assemble would
	// otherwise project from cfg.LLM via llm.SnapshotFromConfig (
	// ). `harbor dev` uses this for the mock-LLM
	// escape hatch; tests flip the driver without rewriting yaml.
	LLMSnapshot *llm.ConfigSnapshot

	// PlannerOverride, when non-nil, replaces the registry-resolved
	// planner concrete. Tests inject stub / scripted / pausing
	// planners; production never sets it.
	PlannerOverride planner.Planner

	// SkillStore, when non-nil, wins over the cfg-opened store. The
	// caller owns its lifecycle (it is NOT added to the closer chain).
	SkillStore skills.SkillStore

	// Embedder, when non-nil, wins over the cfg-opened embedding
	// client. The caller owns its lifecycle (it is NOT added to the
	// closer chain). Tests inject deterministic embedders; headless
	// embedders inject a pre-built client.
	Embedder embeddings.Embedder

	// OAuthProviders pre-populates / overrides entries in the provider
	// map the catalog Builder consults. Entries here win over
	// same-named cfg-built providers; the caller owns their lifecycle.
	OAuthProviders map[string]toolauth.OAuthProvider

	// PreRegisterTools is registered on the catalog BEFORE the builtin
	// registration and the Builder apply, so operator config
	// in cfg.Tools.Entries can wrap in-process fixtures.
	PreRegisterTools []tools.ToolDescriptor

	// RegisterCatalog is an optional callback invoked at the same
	// pre-policy point as PreRegisterTools — on the freshly-constructed
	// catalog, BEFORE builtin registration and BEFORE the catalog
	// Builder wraps every entry with its declared reliability shell,
	// approval gate, and OAuth binding (cfg.Tools.Entries). A compiled
	// in-process tool registered here therefore receives the IDENTICAL
	// wrapping an operator's YAML-declared tool gets. It is an adapter
	// over the one registration seam, never a second registration path:
	// registering the same tool after Assemble returns (a post-assembly
	// Catalog.Register) skips the reliability/approval/OAuth shell.
	// A non-nil error from the callback fails Assemble loud (the partial
	// stack is returned for the caller to drain).
	RegisterCatalog func(catalog tools.ToolCatalog) error

	// MCPDefaultIdentity is the transport-event fallback identity for
	// attached MCP servers. Zero value falls
	// back to DefaultMCPIdentity.
	MCPDefaultIdentity identity.Identity

	// MetricsOptions is threaded into telemetry.NewMetricsRegistry.
	// The devstack injects an in-process manual reader so the kit does
	// not require a metrics-exporter driver per test binary.
	MetricsOptions []telemetry.MetricsOption

	// TelemetryOptions is threaded into telemetry.New.
	// Tests inject telemetry.WithWriter to observe emitted
	// records; production callers pass nothing (stdout handler).
	TelemetryOptions []telemetry.Option

	// TracerOptions is threaded into telemetry.NewTracer.
	// Tests inject telemetry.WithSpanExporter with an
	// in-memory recorder so derived spans are observable without a
	// collector; production callers pass nothing (exporter selection
	// follows cfg.Telemetry.OTelEndpoint — noop without a collector).
	TracerOptions []telemetry.TracerOption

	// ApprovalAuthorizer overrides the resolve-privilege seam threaded
	// into every catalog-built ApprovalGate. Nil
	// defaults to the runtime-vocabulary
	// `approval.NewIdentityAuthorizer()` (originating identity /
	// control scope). The serving binary and the devstack inject the
	// Protocol-side `server.NewProtocolScopeAuthorizer` so wire-driven
	// resolution keeps today\'s admin / console:fleet acceptance.
	ApprovalAuthorizer toolapproval.ResolveAuthorizer

	// SkipCatalog disables the tool-catalog band (search cache,
	// builtins, pause Coordinator, OAuth providers, approval gates, MCP
	// attach, executor). Catalog / Coordinator / Gates / OAuthProviders
	// / MCPRegistry / Executor are nil. Test-kit convenience; the
	// production binary never sets it.
	SkipCatalog bool

	// SkipSteering disables the steering Registry + planner + RunLoop
	// band. Steering / Planner / RunLoop are nil. Test-kit convenience.
	SkipSteering bool

	// SkipRunLoop disables only the RunLoop construction (the steering
	// Registry and planner still build). Test-kit convenience.
	SkipRunLoop bool
}

type RunOption func(*runOnceConfig)

type Stack struct {
	// Cfg is the *config.Config the stack was assembled from.
	Cfg *config.Config

	// Redactor / State / Bus / Metrics / Artifacts / Tasks / Sessions /
	// Agents are always non-nil after a successful Assemble — the
	// runtime's load-bearing core.
	Redactor  audit.Redactor
	State     state.StateStore
	Bus       events.EventBus
	Metrics   *telemetry.MetricsRegistry
	Artifacts artifacts.ArtifactStore
	Tasks     tasks.TaskRegistry
	Sessions  *sessions.Registry
	Agents    *agentregistry.Registry

	// Telemetry is the canonical redactor-mandatory structured Logger
	// (RFC §6.14), constructed with the bus-paired emitter so
	// Logger.Error emits the slog record AND a `runtime.error` bus
	// event. Always non-nil after a successful Assemble.
	// The Options.Logger slog logger remains the BOOT logger
	// for the pre-redactor bootstrap window only; the subsystems the
	// assembly constructs after this Logger exists receive its Slog()
	// bridge, and request-scoped emission
	// goes through this Logger directly.
	Telemetry *telemetry.Logger

	// Tracer is the canonical OTel tracer (RFC §6.14). Spans are a
	// derivation of the event bus: the assembly starts
	// telemetry.BridgeBusToTracer alongside the metrics bridge.
	// Always non-nil after a successful Assemble; with no collector
	// configured the noop exporter drops the spans (in-process
	// propagation still works).
	Tracer *telemetry.Tracer

	// RunErrorHandler is the production engine run-error handler:
	// it routes the structured engine.RunError
	// through Telemetry.Error so a terminal node failure emits the
	// paired `runtime.error` bus event. Flow composition forwards it
	// via `flow.WithRunErrorHandler(stack.RunErrorHandler)`.
	RunErrorHandler engine.RunErrorHandler

	// LLM / LLMSnapshot are populated when cfg.LLM.Driver (or
	// Options.LLMSnapshot) names a driver. LLMSnapshot is the resolved
	// snapshot the client was opened with — posture surfaces project it.
	LLM         llm.LLMClient
	LLMSnapshot llm.ConfigSnapshot
	// KeyRotator is the admin-write seam for Console-driven LLM key
	// rotation — it swaps the SAME atomic key holder the opened driver
	// reads per call. Populated alongside LLM (nil when no LLM driver is
	// configured). The serving binary wires it into the
	// `governance.rotate_key` service.
	KeyRotator *llm.ProviderKeyRotator

	// GovernanceTierSource is the hot-swappable ENFORCED identity-tier policy
	// (the record-over-config effective policy the CostAccumulator /
	// RateLimiter / MaxTokensEnforcer read per PreCall). Seeded at boot from
	// the persisted `set_posture` record layered over the config-declared
	// tiers; the serving binary wires it into the `governance.set_posture`
	// write service so a write ENFORCES with no restart. Nil when the runtime
	// booted fully latent (no config tiers AND no persisted record) — no
	// governance wrapper is composed, so a subsequent write enforces at the
	// next restart.
	GovernanceTierSource *governance.TierSource

	// GovernanceEnforcementActive reports whether this boot composed a
	// governance enforcement wrapper reading the TierSource (a non-empty
	// effective policy — config tiers OR a persisted record). The serving
	// binary threads it into the `governance.set_posture` write service so a
	// write on a fully-latent runtime (no wrapper) returns
	// `enforcement_pending_restart:true` rather than a silent inert 200.
	GovernanceEnforcementActive bool

	// LLMLiveKey is the SAME atomically-swappable primary-key holder the
	// opened LLM driver reads per call — exposed so the serving binary can
	// build the inference-plane broker-pull source over it (the boot-declared
	// brokered primary seeds this holder at connect + refresh, and the
	// `agent_config.set_llm_provider` installer rebinds it). Populated
	// alongside LLM (nil when no LLM driver is configured).
	LLMLiveKey *llm.LiveKey

	// Embedder is populated when the cfg carries a non-zero
	// `embeddings` block (or Options.Embedder is set — caller-owned
	// lifecycle). The semantic retrieval modes in Memory / Skills
	// consume it via their Deps; it is also directly usable for
	// à-la-carte embedding (docs/recipes/embed-and-retrieve.md).
	Embedder embeddings.Embedder

	// Memory / Skills follow cfg.Memory.Driver / cfg.Skills.Driver
	// (Options.SkillStore wins for Skills).
	Memory memory.MemoryStore
	Skills skills.SkillStore

	// Catalog band (nil under SkipCatalog).
	Catalog        tools.ToolCatalog
	Coordinator    pauseresume.Coordinator
	Gates          map[string]*toolapproval.ApprovalGate
	OAuthProviders map[string]toolauth.OAuthProvider
	// OAuthProviderSet is the runtime provider SET (boot-seeded from
	// OAuthProviders + owner-tagged Protocol-installed providers) the MCP attach
	// path resolves a connection's `oauth_provider` binding against. Nil under
	// SkipCatalog.
	OAuthProviderSet toolauth.ProviderSet
	// OAuthProviderBuilder builds Protocol-installed broker-pull providers from
	// a boot credential broker at runtime. Nil under SkipCatalog.
	OAuthProviderBuilder *toolauth.ProviderBuilder
	MCPRegistry          *mcpdrv.Registry
	Executor             steering.ToolExecutor

	// MCPToolContext is the MCP Apps tool-context store the MCP providers
	// capture through (input + lowered result behind a declared `ui://`
	// app) and the host reads back from for `mcp.apps.tool_context`. Nil
	// under SkipCatalog (no MCP providers attach). Wired into every
	// Provider so a planner-path app tool call's context is captured.
	MCPToolContext *mcpconsole.ToolContextStore

	// Steering band (nil under SkipSteering; RunLoop additionally nil
	// under SkipRunLoop or when no planner could be resolved).
	Steering *steering.Registry
	Planner  planner.Planner
	RunLoop  *steering.RunLoop

	// Compression is the trajectory-compression runner:
	// planner.NewCompressionRunner over the LLM-backed
	// summarizer.NewTrajectorySummariser. Non-nil only when
	// cfg.Planner.TokenBudget > 0 (and the steering band ran) — the
	// per-task run-loop drivers project it onto RunSpec.Compression
	// alongside Base.Budget.TokenBudget. Nil = compression off.
	Compression *planner.CompressionRunner
	// contains filtered or unexported fields
}

type StreamEvent struct {
	// Kind discriminates the event (token / tool_dispatched / step).
	Kind StreamEventKind
	// Text is the incremental output delta for a StreamToken event;
	// empty for StreamStep and StreamToolDispatched.
	Text string
	// Reasoning is true when a StreamToken / StreamStep event rides the
	// reasoning ("thinking") channel rather than the answer channel.
	Reasoning bool
}

type StreamEventKind string