compose

func AutoContinueBootScan ¶

func AutoContinueBootScan(deps SessionFactoryDeps, maxPerBoot int)

AutoContinueBootScan is the boot-time trigger for multi-session daemons: one pass over the persisted ACL rows that continues fresh interrupted sessions nobody re-touches (channel sessions). Candidates are found with bounded tail reads only — no agent construction for sessions that don't need it; the actual continuation happens by driving the registry's normal Lookup → resume path, so the lazy-path machinery is shared verbatim.

Guards, in order:

• crash-loop breaker: >= breakerBootThreshold recent boots with attempted continuations → stand down this boot, loudly. A boot whose continuations survive ages out of the window naturally.
• per-session single retry + cumulative cap: a session attempted inside breakerWindow is skipped this boot, and one attempted maxAttemptsPerSession times inside attemptLookback is skipped until the log ages — see the constants block for why counting is the only terminating bound.
• maxPerBoot (config agent.auto_continue.max_per_boot, default 10): oldest interruption first; the remainder is logged, not silently dropped, and lazy touch still covers it.

Runs synchronously; callers launch it on a goroutine after the attach listener is up. Every failure path logs and returns — a broken scan must never take the daemon down.

func AutoContinueRetryLoop ¶

func AutoContinueRetryLoop(ctx context.Context, interval time.Duration, pass func())

AutoContinueRetryLoop re-runs a guarded auto-continue pass on a fixed interval until ctx cancels. It runs NO pass immediately — callers keep their existing boot-time invocation, so the note-latches-before-wake- loop ordering is unchanged; this loop only adds the in-lifetime *re-tries* that let a stable daemon self-heal a stranded continuation without waiting for a reboot or a human message (#575 defect B).

Safety: a continuation turn that kills the daemon kills this loop too, so the loop can only ever re-fire failures that did NOT take the daemon down (transient run-lock contention, a provider blip, a poisoned-but-survivable turn). True crash loops remain bounded by the cross-boot breaker, and every pass is still bounded by the per-session single-retry guard (breakerWindow) + cumulative cap (maxAttemptsPerSession) — so no separate backoff schedule is needed: a session attempted within breakerWindow simply no-ops on the next tick, and the cap terminates a self-renewing session.

interval <= 0 disables the loop (returns immediately). Callers launch it on a goroutine tracked by a WaitGroup joined before the eventlog closes, so a mid-tick pass never races DB teardown.

func AutoContinueStartupSession ¶

func AutoContinueStartupSession(ctx context.Context, h *eventlog.Handle, ag *agent.Agent, freshness time.Duration)

AutoContinueStartupSession is the #558 trigger: the single startup-time session of a headless --no-repl daemon. No ACL rows or scan exist for it — there is exactly one session, whose triple comes from the agent itself — but the boot-log guards matter MORE here than on the lazy path: this trigger fires on every boot with no human touch gating it, so it is the closest analogue of the boot scan. Same discipline: pre-classify (unlocked, read-only), then WRITE-AHEAD intent record, then the shared lock/classify/inject core. Call before the wake loop starts; the injected note latches the wake signal.

func BuildAgenticTools ¶

func BuildAgenticTools(
	builtinTools []adktool.Tool,
	agentGetter func() *agent.Agent,
	provider models.Provider,
	smallModelID string,
) ([]adktool.Tool, error)

BuildAgenticTools constructs the agentic_* tool wrappers from docs/context-management-design.md Mechanism B. The wrappers call Agent.RunSubtask so raw tool output stays in the subtask and only the digest reaches the parent's context.

builtinTools is the already-constructed list (from tools.Build) — we pick out the canonical inner tools (read_file, fetch_url, grep, list_dir, glob) by name so the subtask shares the parent agent's permission gate and per-tool output caps. Wrappers whose required inner tool isn't in builtinTools are silently skipped (e.g. --no-builtin-tools, --disable-tools=read_file, or fetch_url disabled because url_scope.allow is empty).

agentGetter is the late-binding closure that resolves *Agent once agent.New finishes. provider+smallModelID is the cost- efficiency lever: when smallModelID is non-empty, the wrappers route subtasks through that cheaper model. Empty smallModelID means subtasks inherit the parent's model — the wrappers still work, just without the cost win.

func BuildCallPeerTool ¶ added in v2.9.0

func BuildCallPeerTool(gate *permissions.Gate, cfg *config.Config, getReg func() *attach.PeerRegistry) (adktool.Tool, error)

BuildCallPeerTool constructs the call_peer built-in over a hub's peer registry. Callers gate the call on cfg.Tools.CallPeer.Enabled AND the daemon actually being a hub; see cmd/core-agent, which refuses to start when the first is set without the second.

func BuildCompactor ¶

func BuildCompactor(cfg config.CompactionConfig) agent.Compactor

BuildCompactor constructs the auto-compaction trigger that the post-turn hook consults. Starts from the substrate's per-tier defaults (modeltier.DefaultCompactionThresholds) and the historical 0.85 fallback, then layers operator config overrides on top.

Resolution precedence for any one threshold lookup:

1. cfg.ThresholdByTier[currentModelTier], when present
2. The substrate per-tier default for that tier
3. cfg.Threshold (single fallback), when set
4. agent.DefaultCompactionThreshold

Operators who want to leave defaults alone provide an empty CompactionConfig — same behavior as agent.NewDefaultCompactor() returns directly.

func BuildMCPDigestLLMFallback ¶

func BuildMCPDigestLLMFallback(
	agentRef **agent.Agent,
	provider models.Provider,
	modelID string,
) func(ctx context.Context, raw []byte) (mcp.LLMFallbackResult, error)

BuildMCPDigestLLMFallback constructs the closure that pkg/mcp invokes on responses the structural pruner can't reduce below threshold. Returns nil when the operator hasn't opted in — callers nil-check before setting DigestOptions.LLMFallback so the wrap stays on the shipped structural-only default.

Late binding via **agent.Agent: mcp.Build runs before agent.New (the toolsets need to be constructed to pass into the agent's options), so agentRef is populated by the WithPostConstruct hook after mcp.Build has already recorded the closure into DigestOptions.LLMFallback. The model can't invoke an MCP tool through the wrap before its first turn anyway, so the pointer is non-nil by the time the closure fires in practice.

modelID is resolved up-front so it appears in the startup log; the closure caches the adkmodel.LLM on first invocation and reuses it. Empty modelID → subagent inherits the parent's model (functionally correct, no cost win). SubagentModel on the returned result carries the model that actually ran — modelID when set, else the parent's — so display-side pricing lookup uses the resolved tier and the session-side billing in observeToolSavings has something to charge.

func BuildMultiSessionAuthn ¶

func BuildMultiSessionAuthn(cfg config.MultiSessionConfig) (auth.Authenticator, auth.Caller, error)

BuildMultiSessionAuthn translates the operator's attach.multi_session config block into the pkg/auth Authenticator that the attach listener consults per-request. Returns:

• authn: the resolved Authenticator (or nil for single-user mode)
• fallback: the Caller stamped on requests that don't authenticate (used by the host's caller middleware as the no-cred default)
• err: a fatal startup error if the config is internally inconsistent OR a referenced file can't be loaded

In single-user mode (multi_session.enabled = false), returns (nil, zero-Caller, nil) — the attach server defaults its own AnonymousAuth and the wiring is a no-op.

func BuildSessionFactory ¶

func BuildSessionFactory(deps SessionFactoryDeps) attach.SessionFactory

BuildSessionFactory returns an attach.SessionFactory closure that constructs a fresh *agent.Agent per POST /sessions request. The closure captures the deps by value (slices + pointers); per-call it generates a unique sessionID, derives a per-session sub-gate + prompter, loads the per-caller instruction overlay, and assembles a minimal-but-functional agent.

The handler is responsible for calling RegisterOwned on the returned Registrant with the originating Caller.Identity — this factory deliberately does NOT register with the session registry itself, because that would self-register via the legacy Register() (no Owner stamp), losing the ACL ownership that's the whole point.

func BuildSessionResumer ¶

func BuildSessionResumer(deps SessionFactoryDeps) attach.SessionResumer

BuildSessionResumer wires the attach server's SessionResumer. Reads the persisted ACL row from deps.ACLStore; materializes the original Caller from row.Owner; reconstructs the agent via ReproduceAgent with the EXPLICIT sessionID so ADK's session.Service reattaches the prior conversation history from the eventlog.

Returns nil when deps.ACLStore is nil — session-resume is opt-in. The attach server's Options.Resumer being nil leaves the legacy "Lookup miss = 404" behavior in place, no behavior change for pre-v2.5 deployments.

Resumer failures propagate to the registry; the registry's resumeAndRegister handles ErrSessionACLNotFound → ErrSessionNotFound translation. Other errors surface as 500 with the underlying cause (per docs/session-resume-design.md OQ #2).

func BuiltinToolsSummary ¶ added in v2.9.0

func BuiltinToolsSummary(provider models.Provider) string

BuiltinToolsSummary renders the provider's effective server-side built-in tool set for the startup summary: a comma-joined list of the provider-neutral names, or "none" when the provider supports them and has them all off.

Returns "" — not "none" — for a provider with no server-side built-in concept at all (echo, scripted), so the model line can omit the segment rather than assert an absence that means nothing there.

Read off the constructed Provider rather than off config, for the same reason MaybeWirePromptCacheTTL reports what the provider carries: a line derived independently of the requests can drift from them. It also makes the line answer the question an operator actually has — `builtin_tools` keys are silently discarded when misspelled (config decoding does not reject unknown fields), so "did my key take" is only answerable from the far side of the constructor.

func CfgToCatalogOverride ¶

func CfgToCatalogOverride(m config.PricingMap) map[string]pricing.ModelRates

CfgToCatalogOverride translates config.PricingMap (the JSON-tagged per-model rate map operators put under model.pricing) into the pkg/pricing wire shape. nil-safe; an empty map means "no cfg override, fall through to the file + builtin layers".

Must stay field-for-field in step with pkg/usage's cfgToOverride, which performs the same translation on the path taken when no catalog has been installed (tests + library consumers). A field carried by one and dropped by the other means the same config prices a turn differently under test than it does in the daemon. TestCfgOverride_MatchesTheNoCatalogPath enforces the agreement — but only over fields its fixture sets to a non-zero value, which is how CacheCreation1hInputPerMTok was dropped here and stayed green: both translations returned the zero rate for a field neither carried, and two zeroes compare equal. New rate fields must be added to that fixture in the same change that adds them to config.PricingConfig.

func DescribeRefresh ¶

func DescribeRefresh(w io.Writer, out pricing.RefreshOutcome)

DescribeRefresh renders a one-line summary of a pricing-refresh outcome to w. Surfaces the four distinct shapes operators care about: fresh write (model count), 304-not-modified, skipped (cache still within MinInterval), network failure (cache age + error so the operator knows to expect stale rates).

func FormatStartupSummary ¶

func FormatStartupSummary(in StartupSummaryInputs) []string

FormatStartupSummary produces the config-summary block emitted at daemon startup right after the config / instruction / MCP / skills resolution completes. Seven lines, one per topic, in the standard core-agent: <topic>: <detail> shape. Callers wrap each returned line with the `send` helper defined in run().

Kept pure (no I/O beyond os.Getenv for the Vertex env-var summary) so it can be unit-tested by table-driven fixtures. Operators reading the daemon log see these lines FIRST (before "attach listener on" and the other established lines) — this is the "what did the daemon actually load" answer that was silent before #212.

func MaybeWirePromptCache ¶ added in v2.9.0

func MaybeWirePromptCache(provider models.Provider, noPromptCache bool) (status string, enabled bool)

MaybeWirePromptCache applies the operator's prompt-cache kill switch (the CLI's --no-prompt-cache) to an Anthropic provider and returns a one-line status plus whether caching survived.

Unlike MaybeWireContextCache there is nothing to construct: Anthropic prompt caching is cache_control markers on the ordinary request, not a server-side resource. The config gate is already applied by the registry constructor, so this helper exists for the one thing the registry can't see — a CLI flag that arrives after models.Resolve. Call it after Resolve and BEFORE the first provider.Model() call; Model() copies the policy into each LLM it builds.

Providers other than Anthropic are left alone and report "" — Gemini has no equivalent, and an operator running Gemini shouldn't see a line about a knob that doesn't apply to them. The caller decides what to print: the daemon announces its own provider either way, while a per-subagent provider only announces a deviation from the default.

func MaybeWirePromptCacheTTL ¶ added in v2.9.0

func MaybeWirePromptCacheTTL(provider models.Provider, noPromptCache bool, ttl string) (status string, enabled bool)

MaybeWirePromptCacheTTL is MaybeWirePromptCache plus the breakpoint TTL override behind --prompt-cache-ttl: config.PromptCacheTTL5m, config.PromptCacheTTL1h, or "" to keep whatever the config gate already put on the provider.

The TTL is a launch-time property more often than a repo-level one — the same checkout run interactively wants 5m and run from cron wants 1h — which is why it gets a flag and not just a config key. The 1-hour breakpoint bills writes at 2x base input against 5m's 1.25x, so it pays only when consecutive turns are more than five minutes apart (#770).

func NewFilteredLogWriter ¶

func NewFilteredLogWriter(w io.Writer) io.Writer

NewFilteredLogWriter wraps w in a writer that drops noisy log lines from genai/ADK that embedding surfaces don't want exposed. Today the only filtered lines are the `Error context canceled` / `Error context deadline exceeded` messages from genai's SSE scanner, which fire every time a turn is interrupted mid-stream (genai/api_client.go:484 log.Printf's it unconditionally).

Anything that isn't filtered passes through to w unchanged, so consumer-supplied log lines still appear. Typical use:

log.SetOutput(compose.NewFilteredLogWriter(os.Stderr))

func PeerDirectory ¶ added in v2.9.0

func PeerDirectory(getReg func() *attach.PeerRegistry, now func() time.Time) peer.Directory

PeerDirectory adapts a hub's peer registry to the roster the call_peer tool reads (#595). getReg is a closure, not a registry, because the tool is built with the rest of the tool catalog while the registry is constructed later in boot, inside the attach block. It may return nil — a nil registry reads as an empty roster, and call_peer says "no peers are registered" rather than panicking.

now is injectable for tests; nil means time.Now.

Expired leases are filtered here rather than trusted to the registry's 5-second prune tick. A peer that stopped heartbeating is presumed gone, and dialing it burns the caller's whole timeout on a pod that isn't there.

func RebuildPricingCatalog ¶

func RebuildPricingCatalog(cfg *config.Config, agentsDir, coreHome string) error

RebuildPricingCatalog re-reads every pricing source and installs the fresh catalog into usage.SetCatalog. Called after /pricing refresh + /pricing set so subsequent cost lookups see the new rates without a process restart.

func RefreshPricing ¶

func RefreshPricing(ctx context.Context, cfg *config.Config, agentsDir, coreHome string) (string, error)

RefreshPricing is the /pricing refresh slash callback. Forces an out-of-cycle fetch (MinInterval: -1s) regardless of how recently the daily refresh ran, rebuilds the catalog, and returns a summary line for the chat scrollback.

func RegistryAgents ¶

func RegistryAgents(reg *attach.SessionRegistry) []*agent.Agent

RegistryAgents unwraps the live *agent.Agent behind every registry entry whose Registrant exposes one (attachadapter.Adapter does). Duplicates collapse pointer-identity (the TUI /model swap leaves two entries wrapping distinct agents, so this mostly matters for hosts registering one adapter twice). Used by the daemon to feed agent.RegisterMetrics.

func RegistryTrackerProvider ¶

func RegistryTrackerProvider(reg *attach.SessionRegistry) usage.TrackerProvider

RegistryTrackerProvider bridges attach-mode sessions into the usage metrics observer (usage.RegisterMetrics). Entries whose Registrant does not expose the wrapped *agent.Agent (custom hosts registering their own Registrant implementations) or whose agent has a nil tracker are silently skipped — those sessions won't appear in usage metrics.

The Entry's identity triple is authoritative for the metric attributes: it is complete from registration time, whereas the agent's own fields may lag construction.

func RenderContextStats ¶

func RenderContextStats(s agent.ContextStats, parentInputRate float64) string

RenderContextStats formats Agent.ContextStats as a multi-line SystemMessage for the /context (alias /boundaries) slash. Empty sections collapse to a one-line "no X yet" so a fresh session still gets a meaningful response. Format intentionally mirrors /stats' two-column key-value layout for visual parity.

parentInputRate is the parent model's per-million-token input rate (in USD), used to compute the "savings vs. no-digest baseline" dollar figure for the Digest savings block. Zero means "unknown" (fresh session, provider-less pricing, or an unpriced model) — the block still renders but omits the dollar figures.

func ReproduceAgent ¶

func ReproduceAgent(deps SessionFactoryDeps, caller auth.Caller, sid string, origin string) (*attachadapter.Adapter, context.CancelFunc, error)

ReproduceAgent constructs an *agent.Agent under (caller, sid) using the shared SessionFactoryDeps shape. Used both by the on-demand session factory (sid is freshly minted) and by the resumer (sid comes from the persisted ACL row — ADK's session.Service reattaches the prior conversation history when the same triple opens the eventlog).

origin is "created" (factory path) or "resumed" (resumer path) and flows into the operator-visible stderr log line so the daemon log distinguishes the two.

Returns the constructed agent wrapped in its attach adapter (the registry entry the handler registers via RegisterOwnedWithCancel / registerResumed — recover the agent with Adapter.Agent()) + a CancelFunc that stops the per-session wake-loop goroutine. The caller hands the cancel to the registry so eviction terminates the loop cleanly instead of leaking it past the session's lifetime. The wake loop's ctx is derived from deps.DaemonCtx — either source of cancellation (daemon shutdown or per-session evict) closes ctx.Done and the loop exits.

func SetPricing ¶

func SetPricing(cfg *config.Config, agentsDir, coreHome, model string, inputPerMTok, outputPerMTok float64) (string, error)

SetPricing is the /pricing set slash callback. Reads the user file, writes/updates the manual entry, saves atomically, then rebuilds the catalog so the rate takes effect immediately.