agent

func (*Agent) AddSessionCostBudget ¶ added in v2.9.0

func (a *Agent) AddSessionCostBudget(usd float64) (CostCeiling, error)

AddSessionCostBudget raises the per-session ceiling by usd and returns the ceilings that result. This is the ONLY mutation the reset surface offers, and deliberately so: the alternatives — zeroing the accumulator, or restarting a spend "window" — would make Agent.SessionCostUSD, /usage and the eventlog-derived cost disagree about what the session actually spent. Raising the bar keeps every dollar counted and still hands the operator runway.

usd must be > 0. Raising a disabled (0) session ceiling is refused: that would silently ARM a bound the operator never configured, which is a tighter posture than they asked for, not a looser one.

func (*Agent) AgentName ¶

func (a *Agent) AgentName() string

AgentName returns the configured agent name (the WithName value) stored on construction. Used by NewSubagentTool to derive a default tool name.

func (*Agent) AppName ¶

func (a *Agent) AppName() string

AppName returns the AppName the agent was constructed with (the value passed to runner.Config). Used by callers that need to identify the session triple (app, user, session) for queries against the event log or session.Service.

func (*Agent) AskSideQuestion ¶

func (a *Agent) AskSideQuestion(ctx context.Context, question string) (string, error)

AskSideQuestion runs one tool-less LLM call that sees the agent's current conversation history plus the supplied question, and returns the model's answer as a single string. Intended for the TUI's /btw side-question flow (docs/operator-input-design.md layer C): the operator asks a quick context-grounded question ("what was that file again?") without polluting the main conversation. The call bypasses Agent.Run entirely — no inbox drain, no permission gating, no event-log writeback, no tools.

The question is appended to the existing history as a transient user turn that exists only for this one call; nothing about the agent's persisted session state changes. The model can therefore reference prior tool output, prior assistant turns, prior user messages — but cannot call any tool to do new work.

Errors:

• context cancellation: returns ctx.Err().
• no session.Service wired: returns a clear error (defensive; agent.New always installs one, but hand-constructed Agents used in tests don't).
• GenerateContent failures bubble up unchanged so callers can distinguish transport vs API vs model errors via errors.Is.
• the model answering with no text: *SideQuestionEmptyError, which wraps ErrSideQuestionEmpty. Callers are expected to render it as "no answer" rather than as a failed call — see that type's doc comment.

func (*Agent) BackgroundManager ¶

func (a *Agent) BackgroundManager() SubagentManager

BackgroundManager returns the SubagentManager the agent was constructed with via WithBackgroundManager, or nil when none was wired. Used by spawn tools + the runner's REPL alert display to reach the manager without keeping a separate reference. Callers that need the concrete *background.Manager recover it with background.ManagerOf.

func (*Agent) Checkpoint ¶

func (a *Agent) Checkpoint(ctx context.Context, taskNote string) (CheckpointResult, error)

Checkpoint writes a task-boundary checkpoint event to the session and clears any pending checkpoint flag. Like Compact, the event becomes the slicing boundary for the next turn's model request.

taskNote is the operator/model-supplied detail (the mark_task_done `detail` arg, or /done's argument). Empty is fine — the prompt still produces a useful summary, just without the leading completion note.

Errors:

• ErrNoCheckpointer when no checkpointer was wired.
• Context cancellation: ctx.Err().
• Model errors propagate wrapped so callers can errors.Is on transport vs API failures.

func (*Agent) CloseInbox ¶ added in v2.8.0

func (a *Agent) CloseInbox()

CloseInbox marks the agent's inbox closed so every subsequent Inject / InjectAs fails with ErrInboxClosed instead of queuing into a mailbox no live turn will ever drain. The wake-driven surfaces (runner.WakeLoop) call this when their loop exits — both daemon shutdown and per-session eviction cancel that loop's context — so a post-death inject that raced past handler-level gating fails loudly at the source rather than being acknowledged and silently lost (#566). Idempotent and nil-safe.

func (*Agent) Compact ¶

func (a *Agent) Compact(ctx context.Context, focus string) (CompactionResult, error)

Compact runs an out-of-band summarizer LLM call against the current session's history and writes the result as a "summary" marker event the history-slicing path in Run picks up on the next turn. Used both programmatically and by the TUI's /compact slash. See Agent.Checkpoint for the task-boundary variant that shares this machinery.

focus is an optional hint for the summarizer ("focus on the auth-rewrite thread"). Empty is fine — the default prompt instructs the model to produce a balanced handover.

Errors:

• ErrNoCompactor when no compactor was wired.
• Context cancellation: ctx.Err().
• Model errors propagate wrapped so callers can errors.Is on transport vs API failures.

func (*Agent) CompactIfNeeded ¶

func (a *Agent) CompactIfNeeded(ctx context.Context, focus string) (CompactionResult, error)

CompactIfNeeded fires Compact when the wired Compactor's ShouldCompact returns true, otherwise reports Skipped=true. Useful for hosts that want to drive automatic compaction on a turn-end hook without re-implementing the threshold check.

func (*Agent) ContextStats ¶

func (a *Agent) ContextStats() ContextStats

ContextStats returns a snapshot of compaction/checkpoint/subtask activity for this session. Safe to call from any goroutine. Errors fetching the session (e.g. session.Service hiccup) are swallowed and result in zero boundary fields — the subtask fields are populated regardless since they're in-memory.

Cost: one session.Service.Get() call + O(events) scan. Designed for operator-driven /context slash usage, not hot-path telemetry — cache or sample if you need it per-turn.

func (*Agent) CostCeilingLimits ¶ added in v2.9.0

func (a *Agent) CostCeilingLimits() CostCeiling

CostCeilingLimits returns the ceilings currently in force, including any runway added since construction via AddSessionCostBudget. Zero fields mean that bound is disabled.

func (*Agent) CostCeilingTripped ¶

func (a *Agent) CostCeilingTripped() (bool, string)

CostCeilingTripped reports whether the agent is currently blocking new turns because a configured ceiling was exceeded. Exposed for /stats and similar UI surfaces; operators surface this alongside the totals so the "why is the agent refusing my prompts?" question has an obvious answer.

Returns (true, reason) when blocked; (false, "") otherwise.

func (*Agent) DelegationBudgets ¶ added in v2.9.0

func (a *Agent) DelegationBudgets() SubagentBudgets

DelegationBudgets returns the caps that bound one delegation TO this agent when a parent exposes it as a subagent tool — what WithSubagentBudgets set. Zero dimensions are unbounded.

It reads back what was declared, not what a run has spent. The asynchronous twin's caps live on its background.SubagentTemplate; cmd/core-agent fills both from one config block, and this accessor is what lets a test assert the pair did not drift.

func (*Agent) Description ¶

func (a *Agent) Description() string

Description returns the one-line description set via WithDescription. Empty when unset. Satisfies attach.DescriptionProvider — the /.well-known/agent-card.json handler falls back to this when no explicit AgentCardConfig.Description override is supplied.

func (*Agent) DrainInbox ¶

func (a *Agent) DrainInbox() []string

DrainInbox pulls every currently-queued message off the inbox and returns them in arrival order. The queue is emptied as a side effect — repeat calls return nil until new messages arrive.

Exposed so harnesses that want to format inbox messages differently from the built-in `[Inbox]` block (e.g. the TUI's auto-continue flow uses FormatAutoContinueInbox to add system-note framing) can pull the messages themselves and pass the formatted result to Run as a regular prompt. Run's internal drain then finds an empty inbox and is a no-op, so there's no double-injection.

Returns nil when no agent or no inbox is wired — both are defensive cases for hand-constructed Agent structs in tests.

Emits an `inbox`/dequeued event for each drained message with the message's prompt_id, so SSE consumers can correlate the dequeue with the earlier queued event.

Callers that need the per-message originator identity (multi-session turn threading) should use drainInboxFull instead (internal). The public DrainInbox shape is preserved for external harnesses that only care about the text payloads.

func (*Agent) Emit ¶ added in v2.8.0

func (a *Agent) Emit(eventType string, payload any)

Emit is the exported seam over emit() for the packages that will split out of pkg/agent (pkg/agent/background's inbox lives outside the core type — see docs/agent-package-split-design.md). It pushes a typed event onto the attach SSE stream, or is a no-op when no subscriber is connected. Safe on a nil receiver.

func (*Agent) EventLog ¶

func (a *Agent) EventLog() *eventlog.Handle

EventLog returns the *eventlog.Handle the agent was constructed with via WithEventLog, or nil when no event log was wired. Use to reach back to Stream.Since / Stream.Watch for replay or live tail without keeping a separate reference.

func (*Agent) Gate ¶ added in v2.8.0

func (a *Agent) Gate() *permissions.Gate

Gate returns the permissions gate wired via WithGate, or nil when none was configured. Read-only seam for the split-out packages (pkg/attachadapter projects gate state onto the attach wire format); mutations go through the gate's own methods.

func (*Agent) GenerateSessionTitle ¶ added in v2.9.0

func (a *Agent) GenerateSessionTitle(ctx context.Context, prompt string) (string, error)

GenerateSessionTitle runs one tool-less LLM call that turns prompt into a short label. Exported so a host can drive titling explicitly (a backfill over existing sessions, a "retitle this" operator action) rather than only through the automatic first-turn path.

The call uses the small-model tier when one was wired via WithTitleModel and the parent model otherwise. Falling back to the parent model is safe HERE and not on the automatic path: a caller who reaches for this method has asked for a generated title and can be billed for one, whereas the first turn of every session cannot.

Unlike AskSideQuestion this deliberately does NOT see the session history: one call at session start, not a cost that recurs.

func (*Agent) HasCheckpointer ¶

func (a *Agent) HasCheckpointer() bool

HasCheckpointer reports whether a Checkpointer was wired via WithCheckpointer. Hosts use this to gate `/done` (and the `/checkpoint` alias) out of `/help` and the slash palette when --no-checkpoint was passed. Same shape as HasCompactor.

func (*Agent) HasCompactor ¶

func (a *Agent) HasCompactor() bool

HasCompactor reports whether a Compactor was wired via WithCompactor. Hosts use this to gate operator-facing surfaces: don't list `/compact` in `/help` when there's nothing to invoke. Same idea as nil-checking a.compactor directly, but exported so adapters living outside the agent package don't need a reflection trick.

func (*Agent) HasPendingOperatorInput ¶ added in v2.9.0

func (a *Agent) HasPendingOperatorInput() bool

HasPendingOperatorInput reports whether the inbox holds a queued message from someone OTHER than auto-continue itself — real operator/external input waiting to drive the next turn. Auto-continue consults this to STAND DOWN (#624): if an operator has already queued input (e.g. `stop`) while a turn was interrupted, that input must drive the next turn on its own — injecting a "continue the task" note into the same drained batch lets the note outrank the operator's stop (the #624 race). Messages injected by auto-continue itself (AutoContinueOriginator) are excluded so it never sees its own note as operator input. Zero-identity messages (legacy Inject / single-user) DO count — they are operator input without an attached identity.

Messages queued by QueueAsContext (#698) are excluded too, for the same reason auto-continue consults this at all: the stand-down is worth it only because the queued input is ITSELF about to drive a turn. A deferred message explicitly is not — standing down for one would leave an interrupted session with nothing to re-drive it and the deferred context undrained, which is the opposite of both features' intent. Auto-continue proceeds, and its turn drains the deferred message alongside its own note, which is exactly the batching {"wake": false} exists to get.

Returns false for nil agent / inbox.

func (*Agent) InboxArrived ¶

func (a *Agent) InboxArrived() <-chan struct{}

InboxArrived returns a channel that fires when a new message has been injected. The harness can use this to decide when to start the next turn instead of polling — typical pattern:

for {
    select {
    case <-ctx.Done():
        return
    case <-ag.InboxArrived():
        runOneTurn("continue") // inbox prepended automatically
    }
}

The channel has a 1-buffer signal-style semantics: multiple pushes between consumer wake-ups coalesce into one notification (the consumer drains the queue and sees them all).

func (*Agent) Inject ¶

func (a *Agent) Inject(message string) error

Inject queues message on the agent's inbox. The next call to Agent.Run will drain pending messages, format them as an "[Inbox]" block, and prepend the block to the prompt the model sees.

Inject is safe to call concurrently from any goroutine — typical usage is a harness goroutine reading from stdin, an HTTP handler, or an orchestrator's gRPC stream. Drop-oldest backpressure kicks in when the queue exceeds the soft cap (256) so a stuck consumer can't deadlock the agent.

Emits an `inbox`/queued event on the attach event stream (if one is wired) with the assigned prompt_id, so SSE consumers can surface the queued state to operators. The same prompt_id flows out as the `inbox`/dequeued event when the inbox is drained inside Run.

Returns ErrInboxClosed once the agent has been shut down; callers publishing on an unrelated lifecycle should treat that as "stop."

Inject queues without an originator identity. Callers that have a per-request auth.Caller (typically attach handlers in a multi-session deployment) should use InjectAs instead — the caller is threaded into the turn context so the eventlog metadata sidecar and per-caller MCP path see who triggered the turn.

Inject carries no trace context. Callers on an HTTP request path (the attach /inject and /wake handlers, an orchestrator's RPC server) should use InjectAsContext so the turn that answers the inject can be linked back to the injecting span.

Injecting into a PAUSED agent queues the message and leaves the gate shut (#878). The turn that eventually drains it is the one an operator releases with Resume/ResumeWith — see InjectAsContext.

func (*Agent) InjectAs ¶

func (a *Agent) InjectAs(message string, caller auth.Caller) error

InjectAs is Inject with a per-message originator identity. The caller is stored on the queued message and used as the turn originator when the inbox drains: the agent loop wraps the turn context with auth.WithCaller(caller) so eventlog metadata, MCP outbound context, and other caller-aware substrates see the identity that triggered the turn.

Zero-value caller (Identity == "") is equivalent to Inject — no identity is threaded.

When multiple injects queue between turns, the LAST message's caller wins as the turn originator (per docs/multi-session-design.md "the turn answers the most recent ask"). Same prompt_id correlation, same SSE events as Inject.

InjectAs carries no trace context; see InjectAsContext.

func (*Agent) InjectAsContext ¶ added in v2.9.0

func (a *Agent) InjectAsContext(ctx context.Context, message string, caller auth.Caller) error

InjectAsContext is InjectAs plus the injecting call's context, so the queued message remembers the OpenTelemetry span that produced it. Everything else is identical — same queue, same prompt_id, same SSE events, same last-caller-wins originator rule.

ctx is used ONLY to read the active span context. It is deliberately not stored, not used for cancellation, and not consulted for the caller identity (pass that explicitly): an inbox message outlives the request that queued it by design, so keeping the request's context alive on the queue would be a lifetime bug.

Why a link and not a parent: the injecting request returns as soon as the message is queued, so its span has already ended by the time a turn drains the inbox — and one turn can drain SEVERAL injects, so there is no single parent to pick. The agent loop therefore attaches one span LINK per drained inject that carried a valid span context to the turn span it starts (see turnspan.go). Injects with no trace context are a clean no-op.

Injecting into a paused agent ¶

An inject QUEUES; it does not un-park (#878). The message lands on the inbox, publishes its `inbox`/queued event, and fires the wake signal — which latches, buffered-1, so nothing is lost — and then waits behind the gate with everything else. Whatever turn the operator's Resume releases drains it, coalesced into the same `[Inbox]` block as the operator's own instruction.

Until #878 an inject from anyone but auto-continue called Resume itself, on the theory that injecting while parked IS the operator answering "what should I do instead?". That holds for a human at a keyboard and fails for everything else on the same door: auth.Caller carries no human/machine bit, and the identity a machine injects under can be a person's (k8s-lookout's watcher asserts its --owner via a proxy identity), so the runtime cannot tell them apart. An alert arriving mid-park was therefore enough to open a gate a human had deliberately shut.

Releasing a hold is now only ever done by something that says so: Resume, ResumeWithMode, or ResumeWith — reached over the wire as POST /resume. If you want the pre-#878 one-call behavior, that is ResumeWith(mode, message, caller), which queues and then opens the gate in the order that keeps the instruction ahead of the turn.

func (*Agent) InjectAsContextWithID ¶ added in v2.9.0

func (a *Agent) InjectAsContextWithID(ctx context.Context, message string, caller auth.Caller) (string, error)

InjectAsContextWithID is InjectAsContext returning the prompt_id it assigned to the queued message — the same id that goes out on the `inbox`/queued event, comes back on `inbox`/dequeued when a turn drains it, and names the turn on `turn-complete`.

It exists because the id was being computed and thrown away: an attach client that puts a chat thread in front of a session has no other way to key state on the turn its message will produce. `turn-complete.prompt_id` names it, but only at the end, and by then the client needed to have known since the start; the `inbox` events carry it but have no `seq`, so a counter driven off them desynchronises across exactly the reconnect it most needs to survive; and correlating "the queued event that just fired" with "the inject I just sent" holds right up until two goroutines inject on one session, which is the case that needs it (#840).

A sibling rather than a changed signature: pkg/agent is inside the stability promise, and InjectAsContext returning (string, error) would be a source break for every out-of-tree caller.

The id is NOT one-to-one with a turn, and callers must not treat it as one. The inbox coalesces — several messages queued between turns drain into a single "[Inbox]" block and run as one turn (see docs/multi-session-design.md, "the turn answers the most recent ask") — so N injects can share one turn, and `turn-complete` names only one of the ids. What the id buys is the ability to SEE that fan-in and collapse client state accordingly, which is not possible without it.

func (*Agent) Inner ¶ added in v2.8.0

func (a *Agent) Inner() adkagent.Agent

Inner returns the underlying ADK agent the turn loop drives. It is the read-only seam the split-out driver package (pkg/agent/autonomous, see docs/agent-package-split-design.md) uses instead of reaching the unexported field directly; returns nil if the agent is nil or was constructed without an inner agent.

func (*Agent) Interrupt ¶

func (a *Agent) Interrupt() bool

Interrupt cancels the in-flight turn (if any) by invoking the stored cancel func. Returns true if there was something to cancel (a turn was in flight when called), false if the agent was idle (no-op). Safe for concurrent callers.

Repeatable for as long as the turn is actually alive: the cancel func stays registered until the turn's own gen-keyed clearCancelInFlight fires from cleanup, so a second Interrupt while the first is still unwinding reports true again instead of "nothing in flight". It used to clear the func itself, which meant an operator whose first cancel didn't bite promptly — a tool ignoring its context, a model call mid-retry — pressed again and was told the agent was idle while it visibly kept working. context.CancelFunc is idempotent, so the repeat cancel costs nothing.

Note this also keeps turnInFlight() true through the unwind, so Compact / Checkpoint keep refusing their mid-turn boundary writes (#355) until the turn has genuinely finished flushing — which is the window those refusals exist to protect.

Cancellation propagates through context.Canceled to the in-flight model call. The agent's tools (bash, fetch_url, etc.) cancel their I/O when they see the cancel; the model call returns immediately with a partial response; the run loop emits any already-accumulated content and exits. Sessions, the event log, background subagents, and the attach registry all survive untouched.

Interrupt cancels but does not hold: the driver is free to start another turn on the next wake. Use InterruptAndHold for the operator "stop and wait for my next instruction" gesture (see pause.go).

func (*Agent) InterruptAndHold ¶ added in v2.9.0

func (a *Agent) InterruptAndHold(reason string) (interrupted bool, paused bool)

InterruptAndHold cancels the in-flight turn (if any) AND closes the pause gate, atomically with respect to each other: the gate is closed under the same a.mu acquisition that reads the cancel func, so a wake racing the interrupt can't slip a fresh turn in between the cancel and the hold.

Returns (interrupted, paused): interrupted is Interrupt's "there was something to cancel"; paused is the post-condition gate state, which is always true — an operator who hits interrupt while the agent happens to be idle still meant "stop", and holding is what makes that stick.

Empty reason defaults to PauseReasonOperatorInterrupt.

The interrupt audit row (#565) is armed BEFORE the cancel fires, which closes a real race: the attach handler used to call MarkInterruptPending only after AttachInterrupt returned, while drainInterruptAudit runs from the interrupted turn's own cleanup. If cleanup won, the row landed a turn late — and auto-continue, which reads that row as "deliberate kill, don't resume", could re-drive exactly the work the operator had just killed. Arming first makes the ordering deterministic.

func (*Agent) MarkInterruptPending ¶ added in v2.8.0

func (a *Agent) MarkInterruptPending()

MarkInterruptPending is the agent side of attach.InterruptSelfAuditor. The attach /interrupt handler calls it (via the adapter) after an operator cancel actually fired, instead of appending the audit row out-of-band. The row is then written from the post-turn cleanup (see drainInterruptAudit) once the interrupted turn has fully unwound.

Deferring the write this way is the whole fix for #565: the handler's out-of-band Get-then-AppendEvent bumped the live session row's last_update_time while the runner was still flushing the interrupted turn, tripping ADK's optimistic-concurrency check so the operator's clean cancel surfaced as an opaque "stale session error". Riding the turn loop moves the write to the one window with no live runner handle.

func (*Agent) MeterProvider ¶ added in v2.9.0

func (a *Agent) MeterProvider() metric.MeterProvider

MeterProvider returns the resolved OTel MeterProvider the agent's metric instruments were built from (the WithMeterProvider value, or the process-global resolved at New). Subagent construction sites use it to propagate an embedder's non-global provider down the tree — the background spawn path threads it into the spawned agent so subagent turns/tools land in the same provider as the parent rather than silently falling back to the global. Nil only on a hand-constructed Agent (tests); callers thread it conditionally.

func (*Agent) Mode ¶ added in v2.8.0

func (a *Agent) Mode() Mode

Mode reports the layer-3 overlay mode the agent was built with (#459). The autonomous driver consults this to warn when an interactive-mode agent is driven autonomously. Note a WithInstruction full-replace skips the overlay entirely; Mode still reports whatever WithMode set (default ModeInteractive) — the warning is advisory, and full-replace consumers know what they're doing.

func (*Agent) Model ¶ added in v2.8.0

func (a *Agent) Model() adkmodel.LLM

Model returns the LLM the agent was constructed with (#510). Exposes the value New received so drivers that accept a pre-built Agent — runner.Run in particular — can derive the streaming model from the agent instead of demanding it be passed alongside (the agent/model mismatch hazard #492 flagged). Nil-safe.

func (*Agent) ModelName ¶

func (a *Agent) ModelName() string

ModelName returns the name of the LLM the agent was constructed with (sourced from model.Name() at New() time). Used by the attach-mode /status endpoint so the TUI usage panel can label the in/out/cost figures with the model in use.

func (*Agent) Pause ¶ added in v2.9.0

func (a *Agent) Pause(reason string) bool

Pause closes the pause gate: no NEW turn starts until Resume (or a non-auto-continue Inject, which resumes implicitly — see InjectAs). A turn already in flight is deliberately left alone and runs to completion; there is no safe suspend point inside a model call, and reporting "paused" while tokens keep burning would be a lie. Use InterruptAndHold when the in-flight turn should die too.

Idempotent: reports whether this call actually closed the gate. Empty reason defaults to PauseReasonOperatorPause.

See docs/operator-interrupt-design.md for the full state machine.

func (*Agent) PauseState ¶ added in v2.9.0

func (a *Agent) PauseState() PauseState

PauseState snapshots the gate for operator surfaces.

func (*Agent) Paused ¶ added in v2.9.0

func (a *Agent) Paused() bool

Paused reports whether the gate is currently closed. Cheap enough for a status poll.

func (*Agent) PendingInboxCount ¶

func (a *Agent) PendingInboxCount() int

PendingInboxCount peeks at the inbox without draining it. Useful for UI surfaces (TUI queue panel) that need to render the current queue length without claiming the messages.

Returns 0 for nil agent / inbox.

func (*Agent) QueueAsContext ¶ added in v2.9.0

func (a *Agent) QueueAsContext(ctx context.Context, message string, caller auth.Caller) error

QueueAsContext files a message for the agent to read on its next turn WITHOUT causing that turn (#698). It is InjectAsContext minus the one thing that makes an inject preemptive: it does not fire the wake signal, so it cannot cut a sleep short. Everything else is identical — same queue, same prompt_id, same `inbox`/queued event, same caller and trace-context handling, same drain path, same last-caller-wins originator rule.

It used to differ on a second axis too: an inject opened a pause gate an operator had closed and this did not. Since #878 neither does, so against a PARKED agent the two are equivalent — both leave the message waiting for the operator's resume. The distinction that remains is about a SLEEPING agent, which is the one #698 was for.

This is the "file this away" primitive behind POST /inject with {"wake": false}. Its use case is a machine producer — an alert watcher, a monitoring hook — that has corroborating context worth having but no claim on the agent's attention right now. Before it, every such message drove its own turn: two watcher signals two minutes apart meant two wakes, the second landing while the agent was still working the first. Queued, they drain together as one block on whatever turn happens next.

It makes NO promptness guarantee, and callers must treat that literally. The message is drained by the next turn, but nothing here causes a next turn: an autonomous loop reaches one on its own sleep timer, an operator-driven session reaches one when the operator says something, and a session that is parked reaches one when it is resumed. If the message needs to be acted on, inject it normally.

Zero-value caller and the ctx rules are exactly InjectAsContext's; see there.

func (*Agent) QueueAsContextWithID ¶ added in v2.9.0

func (a *Agent) QueueAsContextWithID(ctx context.Context, message string, caller auth.Caller) (string, error)

QueueAsContextWithID is QueueAsContext returning the prompt_id it assigned — the deferred sibling of InjectAsContextWithID, and see there for why the id is worth having and why it is not a turn identity.

Both deliveries report an id because the client-side problem is the same on either: a deferred message still drains into a turn, still produces an `inbox`/queued frame, and still leaves a gateway with nothing to key on. Reporting the id on only the waking path would make the response shape depend on a flag in the request, which is the kind of conditional field clients read wrong.

func (*Agent) RecordGuardrailReset ¶ added in v2.9.0

func (a *Agent) RecordGuardrailReset(reset []string, budgetUSD float64, caller string)

RecordGuardrailReset persists an operator's reset (#643) and is the audit trail #331 asked for — one row, not two, so there is nothing to keep in agreement. reset names the guardrails whose flag was cleared, budgetUSD the runway added, caller the authenticated identity (empty when the reset came from an unauthenticated in-process surface).

Call it AFTER the state mutations, once per operator action. A reset that cleared nothing and added nothing writes nothing: a defensive reset against a healthy session is not an event.

func (*Agent) RequestWake ¶

func (a *Agent) RequestWake()

RequestWake fires the agent's wake signal AND publishes a `wake` event to connected operators. Callers, as the tree actually stands:

• The attach-mode `POST /sessions/<id>/wake` endpoint, when an operator outside the process wants an immediate rescan. This is the only caller in cmd/ or pkg/ that a shipped binary reaches.
• BackgroundAgentManager.pushAlert, on every alert a subagent reports. Background alerts are otherwise PULLED at the top of a parent turn, so a child that finishes after the parent's last turn reports into a queue nothing is scheduled to read; the wake is what makes "result will be pushed" true (#780).
• autonomous.Handle.RequestWake, the host-facing door, for wakes the host knows about and the runtime doesn't. Nothing in-tree wires it to anything now that the manager wakes for itself; dev/uat/scheduled-monitor is the worked example of a host doing the same thing by hand.
• ResumeWith(mode, "", caller) with no message — reachable from a library caller only. `POST /resume` never takes it: attachadapter frames a message for both steer and continue, and a non-empty message short-circuits ResumeWith before the wake.

Operator input via Agent.Inject fires the signal too, but through the unexported path — it deliberately does NOT publish the event. See injectAs.

The event is published here rather than from the attach handler for the same reason emitPause is: an attached operator has to see every wake, and the wake paths above are mostly NOT HTTP ones — the host wiring and the library call never touch a handler, and putting the emit in the handler would make them invisible to exactly the remote operator who can't see the process (#802). Publishing is also the only way an operator surface OUTSIDE this process can learn about a wake: SubscribeWake hands out in-process channels, and an attached TUI is at the other end of an SSE stream. (When #802 shipped, the event was the only way any operator surface could learn about a wake, in-process ones included, because the wake channel was single-consumer and a second subscriber would have stolen wakes from the autonomous scheduler it exists to interrupt. #813 replaced that channel with the fan-out below; the reason to emit here did not change.)

emit is a no-op with no operator transport wired, and the attach broadcaster's fan-out is non-blocking per subscriber, so this stays safe to call from a hot path. The wake fan-out is non-blocking per subscriber too and takes no lock at all. It is also safe to call while the loop is running: nothing here takes the agent's state lock.

No-op when the agent has no wake signal (defensive: hand-constructed Agent structs used in tests don't necessarily wire one up) — but the event still publishes, because "something asked for a wake" is true regardless of whether a scheduler was listening.

func (*Agent) ResetCostCeiling ¶

func (a *Agent) ResetCostCeiling()

ResetCostCeiling clears any tripped cost-ceiling flag, allowing the agent to accept new turns again. Typically wired to an operator slash command after the operator has reviewed why the ceiling tripped. Safe to call even if no ceiling is configured or no flag was set — no-op in that case.

A bare reset is enough for a per-TURN trip: the next turn starts from a fresh baseline. It is NOT enough for a per-SESSION trip — the accumulator is already at or past the ceiling, so the very next turn re-trips. Pair it with AddSessionCostBudget (see WouldRetripCostCeiling) to hand the session real runway.

func (*Agent) ResetWatchdog ¶ added in v2.9.0

func (a *Agent) ResetWatchdog()

ResetWatchdog clears a tripped enforce-mode watchdog, letting the agent accept new turns again. Typically wired to an operator slash command after the operator has reviewed why the watchdog tripped. Also resets the underlying watchdog's signal state so the next run of identical calls has to build back up to the threshold. Safe to call when nothing tripped — no-op in that case.

Deliberately does NOT drop queued feedback (#159). A reset resumes a model whose context still ends in the loop it was halted for; the queued observation is the only thing that stops the first post-reset turn from re-issuing the same call. Clearing it here would make the reset undo the correction along with the halt.

func (*Agent) RestoreGuardrails ¶ added in v2.9.0

func (a *Agent) RestoreGuardrails(ctx context.Context) error

RestoreGuardrails folds this session's durable guardrail rows and applies the result: a halt that survived a restart is re-armed, and budget an operator granted before the restart is re-applied to the per-session ceiling.

Idempotent and cheap to over-call — the fold applies at most once per agent, and Run calls it before its first pre-flight, so most callers never need it. Exposed for embedders that want the state restored (and any error surfaced) before accepting traffic rather than on the first turn.

The latch is set on SUCCESS only, so a read that fails is retried on the next call rather than leaving the agent permanently unrestored. A sync.Once here would mean one transient database error at the wrong moment disarms the backstop for the whole life of the process — the exact failure this durability work exists to remove.

Returns an error only when the session read fails. A session with no guardrail history restores nothing and reports success.

func (*Agent) Resume ¶ added in v2.9.0

func (a *Agent) Resume() bool

Resume opens the pause gate so the next turn can start. Idempotent: reports whether this call actually opened it (false when the agent wasn't paused, so a double-click from two operator surfaces isn't an error).

Resume does NOT itself drive a turn. Callers that want the agent to pick work back up pair it with an Inject (steer text or a continue note) and RequestWake — see the resume dispositions in docs/operator-interrupt-design.md.

func (*Agent) ResumeWith ¶ added in v2.9.0

func (a *Agent) ResumeWith(mode, message string, caller auth.Caller) (bool, error)

ResumeWith is the operator's full resume disposition in one call: queue the message (if any), open the gate, and wake the loop — in that order.

The order is the point. Injecting first means the steer is already on the queue when the gate opens, so the turn the resume releases picks it up; opening the gate first leaves a window where a wake loop blocked in awaitResume starts an un-steered turn and the operator's instruction lands a turn late, against work they'd just redirected.

message is the already-framed text (see FormatInterruptSteer / FormatInterruptContinue) — empty for an abandon, which opens the gate and wakes nothing. mode is carried on the `pause` SSE event.

Returns whether the gate was actually open()ed by this call; false (with no error) when the agent wasn't paused, which is the idempotent case, not a failure. A queued message is still queued and woken in that case: an operator whose resume raced someone else's still gets their instruction delivered.

ResumeWith takes no context, so a resume-steer message carries no trace context and contributes no link to the turn it shapes (unlike InjectAsContext). Deliberate for now: changing this exported signature would break every caller, and the resume path is not the one the cross-process watcher→daemon story runs through.

func (*Agent) ResumeWithMode ¶ added in v2.9.0

func (a *Agent) ResumeWithMode(mode string) bool

ResumeWithMode is Resume carrying the operator's disposition ("steer" / "continue" / "abandon") for the `pause` SSE event, so a second client watching the same session can render what the operator chose rather than just that something changed. The mode is purely observational — the injecting is the caller's job either way.

func (*Agent) Run ¶

func (a *Agent) Run(ctx context.Context, prompt string) iter.Seq2[*session.Event, error]

Run executes one turn of the agent against prompt and returns the event iterator straight from ADK's runner. Callers are expected to range over the returned iter.Seq2 and consume events as they arrive — partial text chunks, tool calls, and the final TurnComplete event.

Multi-turn use: call Run() repeatedly on the same Agent. The configured session ID is reused across calls, so the ADK accumulates conversation history automatically.

When a BackgroundAgentManager is wired via WithBackgroundManager, any alerts background subagents have emitted since the last turn are drained (non-blocking) and prepended to the prompt so the parent's model sees them before deciding what to do next.

Inbox messages queued via Agent.Inject from external callers (harness, orchestrator, HTTP handler) are also drained and prepended, sibling to the alerts block. Ordering: alerts go first (internal state changes); inbox goes second (external input, closer to the prompt logically); then the original prompt.

func (*Agent) RunSubtask ¶

func (a *Agent) RunSubtask(ctx context.Context, spec SubtaskSpec) (SubtaskResult, error)

RunSubtask runs a synchronous, fresh-context, single-purpose LLM call against the parent's session.Service (with a distinct branch so events don't leak into the parent's next Run request). Returns the model's digested answer.

Properties:

• Caller blocks until the subtask returns.
• The subtask runs in its own ADK session (deriveSubagentSessionID produces a parent-prefixed ID; the audit log can correlate).
• The subtask sees NO parent history; its model gets only the SystemPrompt + UserMessage from the spec.
• The subtask's tool set is the spec's Tools — nothing inherited from the parent.
• Cost rolls up to the parent's usage.Tracker (when one is wired via WithUsageTracker) so /stats reflects everything.
• On budget exhaustion: returns SubtaskResult{Truncated: true} with whatever partial Digest accumulated. NOT a Go error.
• On model failure or other unrecoverable error: returns the wrapped error; caller can errors.Is on transport vs API vs spec-validation failure.

Used by the agentic tool wrappers in core-agent/tools ( AgenticReadFile, AgenticFetchURL, AgenticGrep, AgenticResearch); also directly callable by host code that wants to spawn a one-shot research subagent without going through a tool.

func (*Agent) RunWithContents ¶

func (a *Agent) RunWithContents(ctx context.Context, contents []*genai.Content) iter.Seq2[*session.Event, error]

RunWithContents drives one agent turn from a pre-built conversation history (genai.Contents) instead of a single prompt string. The trailing message is treated as the new user input; everything before it is pre-populated into a fresh session as history events.

Each call uses a fresh sessionID so prior calls don't accumulate state — the caller-supplied history is authoritative. Use this when integrating with a runtime (the AX adapter is the motivating example) that supplies the full conversation history per turn rather than relying on a session-managed prompt.

The last content's Role must be genai.RoleUser; non-user trailing messages return an error. Empty contents return an error.

func (*Agent) SessionCostUSD ¶ added in v2.9.0

func (a *Agent) SessionCostUSD() float64

SessionCostUSD reports the session's cumulative spend as the ceiling enforcement sees it — the same accumulator a per-session trip is measured against. 0 when no usage tracker is wired.

func (*Agent) SessionID ¶

func (a *Agent) SessionID() string

SessionID returns the session identifier the agent was constructed with. Combined with AppName + UserID this is the key the event log uses to scope ForSession queries.

func (*Agent) SessionService ¶

func (a *Agent) SessionService() session.Service

SessionService returns the session.Service backing this agent. When no WithSessionService option was passed at construction this is the default in-memory service. Useful for callers that want to query session state directly (e.g. listing prior events) without keeping their own reference to the Service they passed in.

func (*Agent) SessionTitle ¶ added in v2.9.0

func (a *Agent) SessionTitle() string

SessionTitle returns the short operator-facing label for this session, or "" when none has been set or generated yet.

Safe to call from any goroutine — the attach layer reads it from an HTTP handler while the turn goroutine may be writing it.

func (*Agent) SetOperatorEventEmitter ¶ added in v2.8.0

func (a *Agent) SetOperatorEventEmitter(f func(eventType string, payload any))

SetOperatorEventEmitter installs (or clears, when f is nil) the callback the agent uses to push typed operator events — status-update, usage-update, turn-complete, turn-error, inbox — to whatever transport is listening. The attach SSE broadcaster is today's only consumer (it wires its Emit on first subscriber and clears it when the last disconnects), but the seam itself is transport-neutral (#506; formerly SetAttachEmitter, which baked one transport's name into the frozen core surface).

When a tracker is wired via WithUsageTracker, this also installs (or clears) a tracker.SetOnAppend callback that emits a usage-update event with cumulative + per-model totals after every Append. That's what carries the "running cost" the spec describes for the usage-update event type — the turn-complete event reports 0 for cost because the agent itself has no pricing reference (pricing lives in the harness).

Optional. When no callback is installed, all agent-side emit calls are no-ops — events are dropped to the floor since no consumer can see them. This matches the protocol's design intent: typed events are operator-visible signals, not audit log entries; if there's no operator, there's nothing to signal.

Safe to call concurrently with the agent's own emit path; the internal mutex serializes the swap and any in-flight emit reads.

func (*Agent) SetSessionTitle ¶ added in v2.9.0

func (a *Agent) SetSessionTitle(title string)

SetSessionTitle overrides the session's title and suppresses any generation that has not already started. Empty (or whitespace-only) input clears the title and re-arms generation, which is what an operator clearing a bad name would expect to happen.

This is the manual-rename path. An inferred title with no override is a worse deal than no title at all: the operator can see it is wrong and can do nothing about it.

func (*Agent) Streaming ¶ added in v2.8.0

func (a *Agent) Streaming() adkagent.StreamingMode

Streaming returns the ADK streaming mode the agent was constructed with. Part of the read-only accessor seam the split-out subagent packages (pkg/agent/background) use to build child agents that inherit the parent's streaming behavior without reaching the unexported field directly.

func (*Agent) SubagentNames ¶ added in v2.9.0

func (a *Agent) SubagentNames() []string

SubagentNames returns the resolved tool names of the declarative subagents registered via WithSubagents (empty when none). These are synchronous parent-callable subagent tools; operator surfaces use the set to classify their tool-source as "subagent" (#627), distinct from ordinary built-ins. The result is a copy — callers may mutate it.

func (*Agent) SubscribeWake ¶ added in v2.9.0

func (a *Agent) SubscribeWake() (<-chan struct{}, func())

SubscribeWake registers an independent wake subscription and returns its receive end plus an unsubscribe func. Every subscriber sees every wake: RequestWake and Inject fan out to all of them with one non-blocking send apiece, so a subscriber that isn't reading drops only its own redundant wakes.

Same per-channel semantics as WakeRequested — buffer 1, drop on full, "something happened, re-check state" rather than an event count. A wake fired after the subscription exists but before the caller starts reading is latched, not lost; one fired before it exists is not, so subscribe before the agent goes live if that window matters. (WakeRequested's channel has no such window: it is allocated with the agent.)

This is what an operator surface should use. The local `--tui` adapter is the in-tree caller: it holds one subscription for the lifetime of the TUI so an operator's toast and the driver's wake no longer consume each other (#813).

Lifecycle: the returned func is idempotent and safe to call from any goroutine. It deregisters the subscription; it does NOT close the channel, because closing races a concurrent fire and because a closed channel reads downstream as a permanently-ended subscription rather than a quiet one. An unsubscribed channel goes silent, which is what a select wants. Call it — a subscription nobody releases is retained for the agent's lifetime, which is one leaked channel per TUI attach or per host session that forgets.

Nil-safe on both a nil *Agent and a hand-constructed Agent with no wake signal wired: the channel comes back nil (a nil channel in a select blocks forever, the correct "no wake source" behavior) and the unsubscribe is a non-nil no-op, so callers can `defer` it unconditionally.

func (*Agent) Tools ¶

func (a *Agent) Tools() []tool.Tool

Tools returns the resolved tool list the agent was constructed with — including any subagent tools materialized by WithSubagents. Useful for diagnostics ("does my parent know about the research subagent?") without introspecting ADK internals.

func (*Agent) Tracker ¶ added in v2.8.0

func (a *Agent) Tracker() *usage.Tracker

Tracker returns the usage.Tracker the agent was constructed with via WithTracker, or nil when none was wired. Part of the read-only accessor seam pkg/agent/background uses to roll background subagent turns into the parent's usage totals.

func (*Agent) TurnInFlight ¶ added in v2.9.0

func (a *Agent) TurnInFlight() bool

TurnInFlight reports whether a Run turn is currently executing on this agent — the same signal Interrupt() acts on, exported so callers that must not act on a session mid-turn can ask instead of guessing.

The guarantee it carries is narrow but exact: registration happens in Run before runner.Run is handed the turn's message, and the clear happens in the post-drain cleanup, after the last event has been yielded (and therefore committed). Every event the RUNNER writes for the turn — the user message that opens it included — is thus written inside the interval where this reports true. That is what lets pkg/compose's auto-continue tell "the tail is an unanswered user message because the turn was interrupted" from "…because the turn is still generating" (#796), which the tail shape alone cannot distinguish (see ClassifyInterruptedTail). Events Run commits BEFORE registration are outside the interval — today that is #537's tail repair, which writes synthesized responses for a turn that was already interrupted, so a reader that sees them and no in-flight turn draws the same conclusion it would have drawn a moment earlier.

It is per-Agent, and therefore per-session, and it knows only about turns THIS process is driving: a turn running in a peer daemon against a shared eventlog reports false here. Cross-daemon exclusion is the eventlog run lock's job (eventlog.Handle.AcquireLock), not this method's.

Returns false for a nil agent.

func (*Agent) UserID ¶

func (a *Agent) UserID() string

UserID returns the user identifier the agent was constructed with.

func (*Agent) WakeRequested ¶

func (a *Agent) WakeRequested() <-chan struct{}

WakeRequested returns the agent's DEFAULT wake subscription: a channel that fires whenever RequestWake (or Inject, which fires the same signal internally) is invoked. Buffered(1) coalesced semantics: multiple wakes between drains land as one notification.

The same channel every call, for the agent's whole lifetime. Two callers rely on that and would break under a per-call subscription: core-tui re-invokes it to re-arm its listener after every wake, and the autonomous driver re-invokes it on every turn that schedules a successor, to attach it to the context it passes to Scheduler.BeforeNextTurn, where SleepScheduler selects on it alongside its sleep timer and ctx.Done.

Which is also the one caveat: because it is the same channel, two concurrent readers of THIS method still race each other for each value, exactly as they did before #813. That is fine for its callers as the tree stands, because they are the agent's driver — pkg/runner's REPL loop, pkg/runner.WakeLoop, and the autonomous scheduler — and an agent has exactly one driver at a time. Anything that merely wants to OBSERVE wakes alongside a driver must call SubscribeWake instead; that is the bug #813 fixed in the local TUI adapter, which used to hand this channel to core-tui and take turns with the scheduler for each wake.

func (*Agent) WatchdogMode ¶ added in v2.9.0

func (a *Agent) WatchdogMode() string

WatchdogMode reports the agent's configured watchdog posture as one of the config.Watchdog* strings: "off" (no watchdog wired), "warn" (observe and alert), "feedback" (observe, alert, and tell the model on its next turn), or "enforce" (all of that, and halt).

Exposed because "is the backstop actually on?" is the question #642 exists to answer, and the answer must be checkable from outside the package — by the startup summary, by operator surfaces, and by the wiring tests that keep a future refactor from quietly dropping the WithWatchdogEnforce option on a daemon's session-created agents.

func (*Agent) WatchdogTripped ¶ added in v2.9.0

func (a *Agent) WatchdogTripped() (bool, string)

WatchdogTripped reports whether the agent is currently blocking new turns because the enforce-mode watchdog fired. Exposed for /stats and similar surfaces so "why is the agent refusing my prompts?" has an obvious answer. Returns (true, reason) when blocked; (false, "") otherwise.

func (*Agent) WouldRetripCostCeiling ¶ added in v2.9.0

func (a *Agent) WouldRetripCostCeiling() (retrip bool, spent, ceiling float64)

WouldRetripCostCeiling reports whether clearing the trip flag right now would be immediately undone — the session's accumulated spend is already at or past the per-session ceiling, so the next turn's enforcement pass trips again before the operator sees any progress. Returns the spend and the ceiling so the caller can say so precisely.

This is the check that keeps the reset affordance honest: offering a button that provably does nothing is the same state-a-property-you-don't-enforce pattern the reset exists to fix.

func (*DefaultCheckpointer) CheckpointInstruction ¶

func (c *DefaultCheckpointer) CheckpointInstruction(taskNote string) string

CheckpointInstruction returns the five-section handover prompt with a "Completion record" preamble that names the just- finished task. The model's summary will frame the conversation from "this task is now done" angle rather than the "we're still mid-task" angle DefaultCompactor produces.

func (*DefaultCheckpointer) ShouldCheckpoint ¶

func (c *DefaultCheckpointer) ShouldCheckpoint(_ context.Context, _ *Agent) bool

ShouldCheckpoint returns false. Heuristic-based auto-checkpoint is intentionally off by default — false positives (declaring a task done when the operator is mid-thought) are costly. The mark_task_done tool gives the model an explicit signal it can invoke when it's confident; /done gives the operator the same.

func (*DefaultCompactor) ShouldCompact ¶

func (c *DefaultCompactor) ShouldCompact(_ context.Context, a *Agent) bool

ShouldCompact returns true when the agent's usage tracker reports context-window utilization at or above the resolved threshold for the current model's tier. Returns false when the tracker doesn't yet know the window size (no turn has landed, or the model isn't in usage.ContextWindowSizeFor's table) so a session with an unknown model never triggers premature compaction.

func (*DefaultCompactor) SummarizerInstruction ¶

func (c *DefaultCompactor) SummarizerInstruction(focus string) string

SummarizerInstruction returns the five-section handover prompt. focus, when non-empty, appended as a "Compact focus: <text>" directive so the summarizer prioritizes that thread.

func (*EmptySummaryError) Error ¶ added in v2.9.0

func (e *EmptySummaryError) Error() string

func (*EmptySummaryError) Unwrap ¶ added in v2.9.0

func (e *EmptySummaryError) Unwrap() error

func (*SideQuestionEmptyError) Error ¶ added in v2.9.0

func (e *SideQuestionEmptyError) Error() string

func (*SideQuestionEmptyError) Unwrap ¶ added in v2.9.0

func (e *SideQuestionEmptyError) Unwrap() error