engine

package
v0.32.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 39 Imported by: 0

Documentation

Index

Constants

View Source
const (
	TaskKindSubagent = "subagent"
	TaskKindDelegate = "delegate"
)

Task kinds of the nested agent loops: they run inside a parent turn, keep their own in-process history, and offer a tool set scoped by their caller.

View Source
const (
	TaskKindReactMain              = "react_main"
	TaskKindPlanexecStep           = "planexec_step"
	TaskKindPlanexecSynthesize     = "planexec_synthesize"
	TaskKindOrchestratorDecompose  = "orchestrator_decompose"
	TaskKindOrchestratorSynthesize = "orchestrator_synthesize"
)

Task kinds of the top-level agent-loop turns. Their responses drive the conversation and tool execution, so IsInternalLLMRequest treats them as turns even though the loops stamp "_source" for cost attribution.

View Source
const (
	// TaskKindPlan is nexus.planner.dynamic's plan-generation request.
	TaskKindPlan = "plan"
	// TaskKindClassify is nexus.router.classifier's routing probe.
	TaskKindClassify = "classify"
	// TaskKindSummarise is nexus.memory.summary_buffer's summary request.
	TaskKindSummarise = "summarise"
	// TaskKindGateRetry is the shared gate retry-with-LLM helper's request
	// (plugins/gates/internal/retry).
	TaskKindGateRetry = "gate_retry"
	// TaskKindFanoutJudge is nexus.provider.fanout's judge request.
	TaskKindFanoutJudge = "fanout_judge"
	// TaskKindRAGContextualize is nexus.rag.ingest's contextual-chunk request.
	TaskKindRAGContextualize = "rag_contextualize"
	// TaskKindHITLSynthesize is nexus.control.hitl_synthesizer's answer
	// synthesis request.
	TaskKindHITLSynthesize = "hitl_synthesize"
)

Task kinds of internal sub-flows: requests Nexus makes on its own behalf whose response is not a conversation turn. Every value is a wire value — it lands in cost records (`nexus cost --group-by task_kind`) and router rules matching metadata.task_kind — so the spellings are fixed.

View Source
const (
	// MetaVetoed marks an llm.response that was substituted after a
	// before:llm.response veto. Always the bool true when present.
	MetaVetoed = "_vetoed"
	// MetaVetoReason carries the VetoResult.Reason of the handler that
	// vetoed. Present whenever MetaVetoed is.
	MetaVetoReason = "_veto_reason"
)

Metadata keys stamped onto a substituted llm.response. Gates read MetaVetoed to recognize a response they (or another handler) already replaced; MetaVetoReason carries the reason verbatim for logging and for consumers that want the machine-readable cause rather than the prose in Content.

View Source
const (
	// EventStreamChunk is the per-delta event every streaming provider
	// publishes. Emitted only via StreamPublisher, so that the
	// before:llm.stream.chunk hook cannot be skipped at one provider's emit
	// site.
	EventStreamChunk = "llm.stream.chunk"
	// EventBeforeStreamChunk is the vetoable hook offered before any text is
	// released. Payload is *events.StreamSegment.
	EventBeforeStreamChunk = "before:llm.stream.chunk"
	// EventStreamHold announces both edges of a suspended stream.
	EventStreamHold = "llm.stream.hold"
	// EventStreamRetract announces that a mid-flight block disowned the text
	// already released for a turn.
	EventStreamRetract = "llm.stream.retract"
)

Bus event types owned by the streaming seam. Declared here rather than as string literals at the emit sites so the provider Emissions() lists and the transports that subscribe agree on one spelling.

View Source
const (
	// StreamPolicyDowngrade turns streaming off for a request whenever a
	// plugin that adjudicates whole responses, and only whole responses, is
	// active. The default.
	StreamPolicyDowngrade = "downgrade"
	// StreamPolicyAllow leaves Stream as the caller set it and accepts that
	// such a plugin's veto cannot prevent disclosure.
	StreamPolicyAllow = "allow"
)

Response-gate policy values for core.streaming.response_gate_policy.

View Source
const DefaultConfigWatchDebounce = 1 * time.Second

DefaultConfigWatchDebounce balances editor save bursts (250-500ms) against reload latency. Set well above the typical fsnotify Write storm so partial writes never trigger validation. Exported for the CLI's watcher wiring, which substitutes it when ConfigWatchConfig.Debounce is zero.

View Source
const DefaultEventRingSize = 64

DefaultEventRingSize is the default capacity of the bus's in-memory replay ring. Sized for the boot-time pre-subscription gap only — durable event history lives in the per-session journal at <session>/journal/events.jsonl. Pre-Phase-1 callers used the bus ring as a poor-man's event log; that role is gone.

Bumping this does not buy you more durable history — use the journal or register a SubscribeAll handler at engine construction time.

View Source
const DefaultLogRingSize = 4096

DefaultLogRingSize is the default capacity of the in-engine log and event ring buffers.

View Source
const FinishReasonVetoed = "vetoed"

FinishReasonVetoed is the LLMResponse.FinishReason of a substituted response. Agent loops treat it as a terminal, non-tool-calling turn.

View Source
const LevelTrace slog.Level = slog.LevelDebug - 4

LevelTrace is a custom slog.Level below slog.LevelDebug, for ultra-verbose per-event output (bus dispatch, every tool-call arg, wire payloads) that should stay off even during normal Debug troubleshooting. stdlib log/slog defines only Debug/Info/Warn/Error, so this is a plain constant, not a new logging dependency (CLAUDE.md forbids adding a logging library).

*slog.Logger has no .Trace() convenience method — that only exists for the four standard levels — so emitting at this level uses the generic Log method: logger.Log(ctx, engine.LevelTrace, "msg", "key", val).

View Source
const MetaFanoutProvider = "_fanout_provider"

MetaFanoutProvider is the LLMResponse.Metadata key nexus.provider.fanout stamps on each per-provider leg of a fanout (its value is the leg's provider). Legs are copies of the intercepted request and keep its RequestID, so a producer correlating by RequestID must skip them and wait for the merged response, which carries the same RequestID without this key. Read it through IsFanoutLegResponse.

View Source
const MetaInterceptedBy = "_intercepted_by"

MetaInterceptedBy is the LLMRequest.Metadata key a before:llm.request handler stamps when it vetoes a request because it has taken ownership of answering it — it will publish the correlated llm.response itself, rather than blocking the request outright. Its value is the intercepting handler's plugin ID. Set it with InterceptLLMRequest; read it through LLMRequestResult.Intercepted.

The distinction matters to a producer that waits for its response: a blocked request will never be answered and the producer should give up at once, while an intercepted one will be answered (typically asynchronously) and the producer should keep waiting exactly as if it had been published. The fanout coordinator (which re-dispatches the request to several providers and publishes a merged response) and the test IO plugin's mock mode (which publishes a scripted response) are the two interceptors today.

View Source
const MetaLoopTurnID = "loop_turn_id"

MetaLoopTurnID is the LLMRequest.Metadata key a nested loop (subagent, delegate) sets to its private "subagent_<id>" / "delegate_<id>" turn — the TurnID its tool calls carry — beside MetaTurnID's parent turn. Providers echo it onto llm.response, so a consumer that correlates a response with that loop's own tool activity (nexus.rag.citations matching knowledge_search's rag.retrieved) reads it first and falls back to MetaTurnID. It is NOT a turn any transport saw start: bind HITL and other transport-visible emissions to MetaTurnID, never to this.

View Source
const MetaSource = "_source"

MetaSource is the LLMRequest.Metadata key a producer stamps with its own identity ("_source"). A non-empty value is the recursion guard documented in docs/src/architecture/event-bus.md, and it is also the cost-attribution tag: since #83 the agent loops stamp it on their own main turns too, so a non-empty "_source" alone no longer means "internal request".

View Source
const MetaTaskKind = "task_kind"

MetaTaskKind is the LLMRequest.Metadata key naming what kind of call a request is ("react_main", "summarise", "gate_retry", ...). It is the discriminator IsInternalLLMRequest reads to tell an agent-loop turn from an internal sub-flow.

View Source
const MetaTurnID = "turn_id"

MetaTurnID is the LLMRequest.Metadata key naming the agent turn a request serves. LLMRequest has no TurnID field, so request-time consumers read it here: nexus.gate.approval_policy copies it onto the HITLRequest an llm.request rule raises, which is what lets a turn-scoped transport (nexus.io.agui) resume and finish the right run (#218). Providers echo request metadata onto the response, so rag.citations and io.voice read it back off llm.response.

Every agent loop stamps it on every llm.request it publishes. A nested loop (subagent, delegate) stamps the PARENT turn it is serving — the one whose run is waiting on it — not its private tool-correlation turn id, since that id names no turn a transport ever saw start.

View Source
const ReservedPrincipalIDKey = "_principal_id"

ReservedPrincipalIDKey is the reserved-namespace session label holding the identity a transport's credential validator resolved for the current turn.

Why this is a different kind of value from a request header

Both live in the reserved namespace and both are per-turn, but they answer different questions and must not be confused by anything reading them. A request header (see session_headers.go) is an ASSERTION the caller made about itself: nothing verified it, and a caller that can reach the transport can write whatever it likes. This is the identity a pkg/nexusauth Validator CHECKED — a redeemed ticket, a validated bearer token, a JWKS-verified JWT.

So authorization decisions belong on this, and descriptive context (tenant, locale, timezone) belongs on the headers. A plugin that gates behaviour on a header is trusting the caller's own word about itself; one that gates on this is trusting the transport's validator. Keeping them in separate, differently-named slots is what lets a reader tell which it has.

View Source
const TaskKindCompaction = "compaction"

TaskKindCompaction is the task_kind nexus.memory.compaction stamps on its summarisation request. It is a named constant because two sides must agree on its spelling: the producer, and every consumer that recognises a compaction call by kind (the memory plugins' internalflow skip list, router rules matching metadata.task_kind). Those drifted once ("compact" vs "compaction") and the memory plugins recorded the compaction summary into the conversation history.

Variables

View Source
var ErrLLMRequestBlocked = errors.New("llm.request vetoed")

ErrLLMRequestBlocked is returned by AwaitLLMResponse when a before:llm.request handler vetoed the request outright: nothing will answer it.

View Source
var ErrNoLLMResponse = errors.New("no LLM response (provider not active for this role?)")

ErrNoLLMResponse is returned by AwaitLLMResponse when the request was published but no response was delivered during the synchronous emit (no provider active for the request's role, or the provider failed).

View Source
var ErrSessionLocked = errors.New("session is locked by a running process")

ErrSessionLocked is returned by acquire-style helpers when a non-stale lock is already present. Callers can errors.Is against it; the lock contents themselves are surfaced via SessionLockedError below.

View Source
var ErrToolCallCancelled = errors.New("tool call cancelled")

ErrToolCallCancelled is the cancellation cause for a call whose turn was cancelled (a cancel.active event naming the call's turn, or naming no turn at all). Match it with errors.Is.

View Source
var ErrToolCallTimedOut = errors.New("tool call timed out")

ErrToolCallTimedOut is the cancellation cause a tool handler sees, via context.Cause on its per-call context, when its call is timed out (a tool.timeout event naming its call ID). Match it with errors.Is.

View Source
var ErrToolCallsStopped = errors.New("engine stopped")

ErrToolCallsStopped is the cancellation cause for every call still in flight when the engine stops.

Functions

func AwaitLLMResponse

func AwaitLLMResponse[T any](ctx context.Context, res LLMRequestResult, ch <-chan T) (T, error)

AwaitLLMResponse collects the response to a request published with PublishLLMRequest by a producer that blocks on it. ch is the producer's own correlation channel, fed by its llm.response subscription (match on RequestID, skipping IsFanoutLegResponse legs); it must be subscribed before the publish so a response delivered inside the emit is not lost.

  • Emit error: returned as is.
  • Blocked: ErrLLMRequestBlocked wrapping the veto reason, at once.
  • Intercepted: a handler owns the answer and typically publishes it asynchronously (fanout merge, test IO mock), so this waits on ch until ctx is done and then returns ctx.Err(). ctx is the only bound.
  • Published: the bus dispatches synchronously and a non-streaming provider answers inside the emit, so the response is either already on ch or not coming — ErrNoLLMResponse (ctx.Err() if ctx is done).

func BuildEnvelope added in v0.32.2

func BuildEnvelope(ev Event[any], seq, parentSeq uint64) *journal.Envelope

BuildEnvelope materializes the on-disk record from an in-flight event. Detects vetoable events via the *VetoablePayload wrapper so the journal records the veto outcome without a separate envelope.

Exported so wildcard observers that ship events off-process (nexus.observe.tap) emit exactly the shape the journal stores: a consumer reading the file and one reading the stream parse one record. seq and parentSeq are fallbacks only — pass the bus's journal.SeqSource values when the bus implements it, zeros otherwise.

func CarryVetoMarker

func CarryVetoMarker(dst, respMeta map[string]any) map[string]any

CarryVetoMarker copies the substitution marker (and its reason) from an llm.response's metadata onto the metadata of a payload derived from it — typically the events.AgentOutput an agent loop builds from the response. It returns dst so it can be used inline in a struct literal. Nothing is copied when the response was not substituted.

Agent loops must call this when deriving user-facing output from a response, or the refusal loses its provenance at the io.output boundary and output-side gates re-judge operator-authored text.

func EvalObjectKeyPrefix

func EvalObjectKeyPrefix(runID string) string

EvalObjectKeyPrefix maps an eval run ID onto the key prefix holding its report. Exported because the caller is cmd/nexus rather than the engine: an eval run is a CLI invocation that writes its output once and exits, so there is no session, no turn boundary and no engine lifecycle to hang it off.

Kept here beside the other roots rather than in cmd/nexus so the whole key namespace is visible in one file. A second root scheme invented in a command is how a bucket ends up with two layouts.

func ExpandPath

func ExpandPath(path string) string

ExpandPath expands a leading "~" or "~/..." in a filesystem path to the user's home directory. Bare "~" maps to the home dir; "~/foo" maps to "<home>/foo". Other input is returned unchanged. If the home directory cannot be determined, the input is returned as-is.

This is the canonical helper for tilde expansion in Nexus. Plugins and embedders should funnel every config-supplied path through this function so users can write "~/.nexus/foo" anywhere a path is accepted.

func GenerateID

func GenerateID() string

GenerateID produces a random hex-encoded UUID-style identifier.

func InterceptLLMRequest

func InterceptLLMRequest(vp *VetoablePayload, req *events.LLMRequest, by, reason string)

InterceptLLMRequest vetoes a before:llm.request on behalf of a handler that takes ownership of answering it, stamping MetaInterceptedBy so the producer keeps waiting for the response instead of treating the veto as a block. The handler is then responsible for publishing a correlated llm.response (via PublishLLMResponse, carrying the request's RequestID and Metadata).

func IsAgentTurnTaskKind

func IsAgentTurnTaskKind(kind string) bool

IsAgentTurnTaskKind reports whether kind is the task_kind of an agent-loop turn (see IsInternalLLMRequest).

func IsConversationLLMRequest

func IsConversationLLMRequest(meta map[string]any) bool

IsConversationLLMRequest reports whether a request is a turn of the top-level conversation: not internal (see IsInternalLLMRequest) and not a nested agent loop (see IsNestedAgentTaskKind). Handlers that act on the conversation's own history or tool surface — the context-window gate (which compacts the main history) and progressive discovery (which replaces the tool list from the global catalog) — use this, because doing either to a subagent's or delegate's request would compact the wrong history or widen a caller-scoped tool set. An untagged request is a conversation turn.

func IsFanoutLegResponse

func IsFanoutLegResponse(meta map[string]any) bool

IsFanoutLegResponse reports whether a response is one per-provider leg of a fanout rather than the answer to the request (see MetaFanoutProvider).

func IsInternalLLMRequest

func IsInternalLLMRequest(meta map[string]any) bool

IsInternalLLMRequest reports whether a request's metadata marks it as one of Nexus's own internal requests rather than an agent-loop turn: it carries a non-empty "_source" and its "task_kind" is not an agent-turn kind. A request with no "_source" is never internal — an untagged request is treated as a turn, so a handler that skips internal requests fails closed on it.

Fallback retries copy the original request's metadata, so a retried agent turn stays a turn and a retried summary stays internal.

Content gates whose input was already checked at io.input (nexus.gate.prompt_injection, nexus.gate.stop_words), the iteration counter (nexus.gate.endless_loop) and the approval-policy gate skip internal requests on before:llm.request; budget gates (rate_limiter, token_budget) do not.

func IsLockStale

func IsLockStale(lock SessionLock) bool

IsLockStale returns true when the lock's PID is no longer alive on the host. A zero or negative PID is considered stale. On platforms where liveness probing is not implemented (anything other than linux/darwin), the lock is treated as non-stale so we err on the side of refusing to clobber a real run.

func IsNestedAgentTaskKind

func IsNestedAgentTaskKind(kind string) bool

IsNestedAgentTaskKind reports whether kind is the task_kind of a nested agent loop (subagent, delegate) — an agent turn that runs inside a parent turn rather than being the conversation itself.

func IsReplay

func IsReplay(ctx context.Context) bool

IsReplay reports whether the calling context is a replay context.

func IsReservedLabelKey

func IsReservedLabelKey(key string) bool

IsReservedLabelKey reports whether key belongs to the reserved (host-only) session-label namespace: any key starting with "_". Exported so every other consumer that needs the same rule — ICM's OperatorTemplateCtx.Context projection, react/orchestrator/subagent's <session_context> prompt builders, and the opt-in nexus.tool.session_tags plugin — shares this one definition rather than each re-implementing the prefix check and risking the two drifting apart.

func IsVetoSubstituted

func IsVetoSubstituted(meta map[string]any) bool

IsVetoSubstituted reports whether a payload's metadata carries the marker stamped by PublishLLMResponse on a substituted response. It reads the metadata map directly so it serves both events.LLMResponse.Metadata and the events.AgentOutput.Metadata that agent loops derive from it.

Output-side gates use this to recognize text that a before:llm.response handler already authored and adjudicated, and pass it through rather than judging it a second time. Without that, a gate vetoing the refusal at before:io.output would leave the user with nothing — the blank outcome the substitution contract exists to avoid.

The marker is not model- or user-controllable: it is set only by PublishLLMResponse, and the request metadata providers echo onto a response is authored by plugins with fixed keys.

func ListSessionArchives

func ListSessionArchives(cfg Config, sessionID string) ([]string, error)

ListSessionArchives returns the names of every rewind archive for the named session, sorted ascending by timestamp. Read-only — does not consult the session lock.

func NondeterministicWarn

func NondeterministicWarn(logger *slog.Logger, reason string)

NondeterministicWarn logs a one-shot warning that a plugin read non- deterministic state (wall clock, randomness, env, network) during dispatch. During deterministic replay these reads diverge from the journaled run.

The helper deduplicates by reason so a hot-path call site does not flood the log. Plugins should pass a stable reason string ("dynvars: time.Now", "tool.web: http.Get") so the dedup map keeps a small, comprehensible shape.

func ParseLogLevel

func ParseLogLevel(level string) slog.Level

ParseLogLevel converts a string log level ("trace", "debug", "info", "warn", "error") to slog.Level. Unrecognized values default to slog.LevelInfo.

func PluginBaseID

func PluginBaseID(id string) string

PluginBaseID extracts the base plugin ID from a potentially instanced ID. For example, "nexus.agent.subagent/researcher" returns "nexus.agent.subagent". A plain ID like "nexus.agent.react" returns itself unchanged.

func PublishLLMResponse

func PublishLLMResponse(bus EventBus, resp events.LLMResponse) (events.LLMResponse, bool)

PublishLLMResponse runs resp through the vetoable "before:llm.response" hook and then emits "llm.response" exactly once. It returns the response that was actually published, and whether that response was substituted for the one passed in.

Every producer of an llm.response — every provider plugin, the fanout coordinator's merged re-emit, the test IO plugin's mock responses — must publish through this function rather than calling bus.Emit directly, so that the hook fires uniformly and the invariants below hold everywhere.

The contract differs from every other before:* event in the system, in one way that matters:

A veto on before:llm.response means SUBSTITUTE, not DROP. Agent loops (react, planexec, orchestrator) subscribe to llm.response and block their turn waiting for it; suppressing the event entirely would hang the turn rather than block an action. So a vetoing handler does not prevent an llm.response — it changes which one is published.

Handlers have two ways to shape that response:

  • Mutate without vetoing. The payload is a *events.LLMResponse, so a handler that rewrites Content (or strips individual ToolCalls) in place and returns without setting Veto has its edits published as the model's response. This is the same mutate-then-veto convention the shipped gates already use on before:io.output.

  • Veto. The response is replaced by a substitute derived from it. A handler that wants to dictate the replacement text mutates Content and then vetoes; the substitute keeps the mutated Content. A handler that vetoes without touching Content gets a substitute whose Content is the veto reason, so the agent loop can see why it was blocked.

In both veto cases ToolCalls is cleared. A vetoed response must never drive tool execution — that invariant is the entire security value of the hook, and it lives here rather than in each provider so it cannot be forgotten at one of the emit sites.

Correlation and accounting fields survive substitution: RequestID (so the blocking sync-RPC helper and provider in-flight tracking still match the response to its request), Model, Tags, Usage and CostUSD. The tokens were spent whether or not the answer ships, so nexus.gate.token_budget must still see them.

A veto Reason can become user-visible text — it is published as the substitute's Content whenever the handler does not dictate its own — and output-side gates deliberately do not re-scan a substituted response (see IsVetoSubstituted). So a handler must NOT interpolate raw model output into its Reason: doing so would route the very content it just blocked to the user, past the gates that would otherwise catch it. Put the model's text in the log, and a description of what tripped in the Reason.

Streaming caveat: providers emit llm.stream.chunk as tokens arrive and llm.response only at the end of the stream. A veto here cannot unsay text already streamed to a UI. Gates that must prevent disclosure require stream: false; gates that only steer the loop (blocking tool calls) work unchanged under streaming.

func PublishTree

func PublishTree(ctx context.Context, cfg objectstore.Config, keyPrefix string, localDir string, skip func(rel string, isDir bool) bool) (objects int, bytes int64, err error)

PublishTree uploads every regular file under localDir to keyPrefix and flushes, opening and closing the backend around the call.

This is the seam's entry point for output that is produced outside an engine run — eval reports are the reason it exists. An eval run is a CLI invocation that writes a report directory once and exits: there is no session to hydrate into, no turn boundary to hang a snapshot off, and no Engine at all, so it gets a function rather than a lifecycle hook. It is still the same Backend with the same key rules, which is what keeps "one interface serves all four roots" true rather than aspirational.

skip is called with each entry's slash-separated path relative to localDir and reports whether to leave it out; a nil skip includes everything. Returning true for a directory prunes it.

A disabled cfg is a no-op returning zero counts and no error, so a caller does not have to branch on config internals.

func RemoveSessionLock

func RemoveSessionLock(dir string) error

RemoveSessionLock deletes the lock file under dir. Missing files are not an error — Stop is idempotent.

func ReplayToolShortCircuit

func ReplayToolShortCircuit(replay *ReplayState, bus EventBus, tc events.ToolCall, logger *slog.Logger) bool

ReplayToolShortCircuit handles the tool-side replay path. Side-effecting tool plugins call it from their tool.invoke handler — after they have filtered for tool calls they own — and return early when it returns true.

Lookup order:

  1. Args-keyed disk cache (ReplayState.ToolCache). Survives memory-state divergence between original and replay runs because the lookup key is sha256(tool_id || canonical_args), not call order.
  2. FIFO stash (ReplayState.Pop). Fallback for tools whose original result was not cached — typically because the cache subscription was not yet installed when the original tool.result fired.
  3. Empty-stash sentinel: emit an error tool.result so replay divergence surfaces as a tool-level error the agent can see rather than a silent stall.

In every case, the live invoke's correlation IDs win over journaled ones — the agent dispatched with these and matches results by ID.

Lives in the engine package (not journal) because the helper needs the events package, which the journal package intentionally does not import.

func RequestHeaderLabelKey

func RequestHeaderLabelKey(name string) string

RequestHeaderLabelKey returns the session-label key an X-Nexus-* header is bound under. name is the normalized header name nexusheaders.Name produces (`X-Nexus-Tenant-ID` -> `tenant-id` -> `_header.tenant-id`).

func RequestHeaderName

func RequestHeaderName(key string) (string, bool)

RequestHeaderName reports whether key is a request-header session label and, when it is, the header name it carries. It is the inverse of RequestHeaderLabelKey.

func ResolveModelConfig

func ResolveModelConfig(models *ModelRegistry, req events.LLMRequest) events.LLMRequest

ResolveModelConfig returns a copy of req with every per-entry axis it does not already carry filled in from the model registry, and is how a provider recovers a role's configuration on the paths no coordinator touches.

Layering, most specific first:

  1. whatever the request already carries — a coordinator's stamp, an agent posture's temperature, a gate's override;
  2. the entry for the role the request names, when it names one. This is also the late-recovery path: it is consulted whether or not `model` was already set, so a router that rewrote `model` and left `role` alone does not silently drop the role's configuration;
  3. the default role's entry — for the shared axes only.

Step 3 is deliberately narrower than step 2. The *shared* axes — max_tokens, effort and temperature — speak one vocabulary every provider understands, and an axis a named role leaves unset falling through to the default role is the long-standing Effort behaviour this generalises. The *provider-native* axes — the `thinking`, `reasoning`, `cache` and `retry` blocks and the `api` selector — do not fall through: they resolve from the role the request actually names, and the default role supplies them only when the request names no role at all, which is what "the default role" means.

Without that split a deployment whose default role is Anthropic with `thinking: {mode: adaptive}` would silently hand an Anthropic-shaped block to a named Gemini role that was never given one — a configuration the operator did not write, in a vocabulary that provider does not speak.

A stamped request is returned unchanged — the coordinator already supplied the only entry that is correct for it.

Resolution says nothing about *which* provider should answer: a role naming another provider still resolves here. Callers do their own `_target_provider` and resolved-provider checks first, as every provider plugin already does.

func RestoreSession

func RestoreSession(cfg Config, sessionID, archiveName string, force bool) error

RestoreSession swaps the live journal for a previously archived snapshot. The current live journal is itself archived first so the flip is reversible. Like RewindSession, refuses to operate when a non-stale session lock is present unless force is set.

func RewindSession

func RewindSession(cfg Config, sessionID string, toSeq uint64, force bool) (journal.RewindResult, error)

RewindSession is the offline equivalent of engine.ReplaySession.

It archives the named session's journal and writes a truncated copy that ends at toSeq inclusive. The original journal is preserved at <sessions.root>/<sessionID>/journal/archive/<timestamp>/ so the operation is reversible via RestoreSession.

The caller must guarantee the target session is not running. The engine writes a session.lock file under <sessions.root>/<sessionID>/ while a session is active; RewindSession refuses to operate when a non-stale lock is present. Pass force=true to bypass the check (the CLI surfaces this as --force) — concurrent writes against a journal being rewound produce undefined state, so this should only be used when the operator is certain the lock is from a wedged process that cannot be killed cleanly.

Returns the archive directory name for use with RestoreSession.

func SessionConfigSnapshotPath

func SessionConfigSnapshotPath(configPath string, sessionID string) (string, error)

SessionConfigSnapshotPath returns the path to a session's config snapshot. It uses the sessions root from the provided config file (or the default) to locate the session directory. The configPath is needed to determine the sessions root dir.

func SmokeValidateConfig

func SmokeValidateConfig(eng *Engine) error

SmokeValidateConfig runs the same schema validation pass that lifecycle Boot performs, but without instantiating any of the plugin's Init logic. Tests use it to verify that every shipped YAML config continues to satisfy every plugin's schema across the active set as declared in YAML. Returns the aggregate error verbatim from the validator so failures point at the offending key. Auto-activated requirements are NOT included — they receive engine-supplied defaults (already known-valid) and would require running expandRequirements which is part of Boot proper.

func StampModelConfig

func StampModelConfig(req *events.LLMRequest, cfg ModelConfig)

StampModelConfig applies the chain entry a coordinator is serving to an outgoing request, filling only the axes the request does not already carry and marking the request as stamped.

Callers are the fallback and fanout coordinators. Model is deliberately not touched: a coordinator retargets a request at a different model outright rather than filling a gap, so that assignment stays at the call site.

The stamp is authoritative. Once it is set, ResolveModelConfig will not consult the registry again, because the registry would answer with the role's first entry rather than the one being served.

func StreamUnsafePlugins

func StreamUnsafePlugins(plugins []Plugin) []string

StreamUnsafePlugins returns the IDs of active plugins that handle before:llm.response but not before:llm.stream.chunk, sorted for stable logging.

The distinction is the whole point of the streaming seam. A plugin holding only the response-level hook sees the model's text for the first time after the stream has finished, so its veto governs history and tool execution but arrives far too late to stop the text being shown. A plugin holding the chunk-level hook adjudicates before anything is released, so it keeps its guarantee with streaming on.

Declared subscriptions are the source of truth rather than the live bus table, for two reasons: it can be computed at boot before any dispatch has happened, and Subscriptions() is already the contract the plugin harness enforces against runtime behavior, so a plugin cannot quietly disagree with what it declared.

The consequence is a pleasant one: a gate acquires streaming support simply by growing a before:llm.stream.chunk handler, and streaming comes back on by itself. Nothing has to be re-registered, and no operator has to notice.

func WalkRoleEntries

func WalkRoleEntries(models *ModelRegistry, providerID string, fn func(role string, cfg ModelConfig) error) error

WalkRoleEntries calls fn once for every `core.models` chain entry that providerID could be asked to serve, and stops at the first error fn returns.

It is the skeleton every provider's Init-time `validateRole*` sweep is built from, and it exists because those sweeps all have to agree about four non-obvious things:

  • Roles are walked in sorted order, so a config with several broken roles fails on the same one every boot rather than on whichever one the map iteration reached first.
  • The whole chain is walked, not just the primary: a non-first entry's configuration reaches a provider through the fallback or fanout coordinator's stamp and is just as capable of being wrong.
  • An entry naming another provider is that provider's business and is skipped; an entry naming none may land anywhere, so it is checked.
  • A nil registry is not an error — an embedder may run without one.

The per-axis part — which block to read off the entry, what to do with it — stays with the provider, which is the only thing that can parse its own vocabulary.

func WithReplay

func WithReplay(ctx context.Context) context.Context

WithReplay returns a derived context tagged as a replay context.

func WriteSessionLock

func WriteSessionLock(dir string, pid int) error

WriteSessionLock writes session.lock under dir with the supplied PID and the current wall-clock time. Existing files are overwritten — callers that want refuse-on-conflict semantics must call ReadSessionLock + IsLockStale first.

func WriteSessionLockWithTransport

func WriteSessionLockWithTransport(dir string, pid int, transport string) error

WriteSessionLockWithTransport is the same as WriteSessionLock but records a transport tag (e.g. "tui", "browser", "oneshot") so stale- lock diagnostics can name the prior run's IO surface. Empty transports are omitted from the JSON.

func XMLCDATA

func XMLCDATA(content string) string

XMLCDATA wraps content in a CDATA section. Use for content that may contain characters that conflict with XML parsing (e.g. user input, LLM output).

func XMLClose

func XMLClose(b *strings.Builder, tag string)

XMLClose writes a closing XML tag to a strings.Builder.

func XMLEscape

func XMLEscape(s string) string

XMLEscape escapes XML special characters in a string.

func XMLTag

func XMLTag(b *strings.Builder, tag string, attrs ...string)

XMLTag writes an opening XML tag with optional attributes to a strings.Builder. Attributes are written as key="value" pairs.

func XMLWrap

func XMLWrap(tag, content string, attrs ...string) string

XMLWrap wraps content in an XML element with optional attributes. Returns empty string if content is empty.

Types

type Capability

type Capability struct {
	// Name is the dotted capability identifier (e.g. "memory.history").
	Name string
	// Description is a one-line human-readable summary of what the capability
	// provides. Shown in logs and surfaced through eng.Capabilities() for
	// agents that describe themselves.
	Description string
}

Capability is an abstract service a plugin advertises. Names are dotted namespaces mirroring event types ("memory.history", "memory.compaction", "control.cancel", "tool.catalog"). Description is a short, human-readable blurb for introspection (e.g. self-description prompts, debug logs).

type CausationContext

type CausationContext struct {
	SessionID string
	AgentID   string
	Depth     int
}

CausationContext is the session/agent/depth scope pushed onto the bus by callers so events emitted on a goroutine carry their owning session and agent automatically. See EventBus.PushCausationContext.

type CausationController

type CausationController interface {
	PushCausationContext(c CausationContext) func()
	SetDefaultCausationContext(c CausationContext)
	// CurrentCausationContext returns the active CausationContext for the
	// calling goroutine — the top of its push stack, or the bus-wide
	// default when nothing has been pushed. Callers that need to derive a
	// nested context (e.g. a subagent spawned synchronously inside a
	// parent agent's goroutine) read this to set Depth = parent.Depth + 1
	// without having to thread depth through every API.
	CurrentCausationContext() CausationContext
}

CausationController is implemented by buses that propagate per-goroutine CausationContext into emitted events. Plugins and runtimes (agent loops, sub-agent dispatch, IO transports binding to a session) push a context for the duration of their work; nested events automatically carry the SessionID, AgentID, and Depth without each emitter wiring them by hand.

type Config

type Config struct {
	Core   CoreConfig   `yaml:"core"`
	Engine EngineConfig `yaml:"engine"`
	// Capabilities pins a capability name to a specific provider plugin ID,
	// overriding the default resolution (first active provider, else first
	// registered). Populated from the top-level YAML `capabilities:` block.
	Capabilities map[string]string `yaml:"capabilities"`
	Plugins      PluginsConfig     `yaml:"plugins"`
	// Journal tunes the always-on durable event log. The journal cannot be
	// disabled — it is core, not a plugin — but its fsync, retention, and
	// rotation thresholds are exposed here for ops trade-offs.
	Journal JournalConfig `yaml:"journal"`

	// Raw is the original config YAML bytes the engine was loaded from.
	// Populated by LoadConfigFromBytes (and by extension LoadConfig). Empty
	// for configs constructed in-memory via DefaultConfig. Used by Engine
	// to write a bytes-faithful session config snapshot — re-marshaling the
	// typed Config drops fields parsed via the second-pass raw map (core.models
	// and per-plugin configs both have yaml:"-").
	Raw []byte `yaml:"-"`
}

Config is the top-level configuration for the engine.

func DefaultConfig

func DefaultConfig() *Config

DefaultConfig returns a Config with sensible defaults.

func LoadConfig

func LoadConfig(path string) (*Config, error)

LoadConfig reads a YAML config file from disk and returns a Config. It is a thin wrapper around LoadConfigFromBytes and exists for the CLI binary that still reads config from a path; embedders that want to ship a compiled-in config should use LoadConfigFromBytes (or NewFromBytes on Engine) instead, so the final binary has no filesystem dependency at boot.

func LoadConfigFromBytes

func LoadConfigFromBytes(data []byte) (*Config, error)

LoadConfigFromBytes parses a YAML config from a byte slice and returns a Config merged on top of DefaultConfig. Embedders that //go:embed a config.yaml alongside their main package use this to build a Config without ever touching the filesystem.

The two-pass unmarshal (typed struct first, then raw map for per-plugin configs and core.models) is the same shape the file-based loader always used — this function just takes the bytes as an argument instead of reading them itself.

type ConfigReloader

type ConfigReloader interface {
	ReloadConfig(old, new map[string]any) error
}

ConfigReloader is implemented by plugins that can apply a config change in place without a full Shutdown/Init cycle. Engine.ReloadConfig calls ReloadConfig with the previous and new raw config maps (both already schema-validated). Implementations must be transactional from the bus's perspective: returning an error must leave the plugin in its previous state — bus subscriptions, in-memory data, persisted scratch — unchanged.

Plugins that don't implement this interface go through the full restart path on a config change (Shutdown -> Init -> Ready). Implementing it is an optimization for plugins where a restart would drop in-progress work (active streams, bound HTTP listeners) the operator would notice.

type ConfigSchemaProvider

type ConfigSchemaProvider interface {
	ConfigSchema() []byte
}

ConfigSchemaProvider is an optional interface a plugin implements to expose a JSON Schema describing the shape of its config block. The engine type- asserts on plugin instances during boot and validates the raw config map against the schema before Init is called. Plugins that do not implement the interface are skipped with an info log.

The schema is canonical for the plugin's config — the same map[string]any passed to Init is what gets validated. Schemas should declare `additionalProperties: false` at every object level so unknown keys (typos) fail loudly. See docs/src/configuration/reference.md for the authoring guide.

type ConfigWatchConfig

type ConfigWatchConfig struct {
	// Enabled toggles the fsnotify watcher. When false, only SIGHUP and the
	// browser admin endpoint can trigger ReloadConfig.
	Enabled bool `yaml:"enabled"`
	// Debounce collapses bursts of fsnotify events on the same file into a
	// single reload. Zero falls back to defaultConfigWatchDebounce. Editors
	// commonly fire two or three Write events when saving — too short a
	// debounce reads a half-written file; too long delays the reload.
	Debounce time.Duration `yaml:"debounce"`
}

ConfigWatchConfig governs the optional fsnotify-based hot-reload watcher. Off by default — operators who want auto-reload opt in explicitly because in production environments rapid YAML edits during deploys can trigger undesired plugin restarts. SIGHUP and the admin HTTP endpoint remain available regardless of this setting.

type ContextManager

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

ContextManager manages agent context. This is a minimal v1 implementation that will be expanded as context windowing and summarization are added.

func NewContextManager

func NewContextManager(bus EventBus, logger *slog.Logger) *ContextManager

NewContextManager creates a new ContextManager.

type CoreConfig

type CoreConfig struct {
	LogLevel            string         `yaml:"log_level"`
	Logging             LoggingConfig  `yaml:"logging"`
	TickInterval        time.Duration  `yaml:"tick_interval"`
	MaxConcurrentEvents int            `yaml:"max_concurrent_events"`
	Sessions            SessionsConfig `yaml:"sessions"`
	// AgentID partitions per-agent storage and other per-agent state.
	// Set by multi-agent embedders (one host process running several
	// engines) so each agent instance gets its own ScopeAgent storage tree
	// under ~/.nexus/agents/<id>/. CLI and single-agent embedders leave it
	// empty, which collapses ScopeAgent to ScopeApp.
	AgentID string        `yaml:"agent_id"`
	Storage StorageConfig `yaml:"storage"`
	// ObjectStore optionally makes a remote object store the source of truth
	// for the engine's on-disk state between runs, for deployments with no
	// durable local disk. It governs four roots — the session tree, app- and
	// agent-scope plugin storage, and eval run output — which is why it sits
	// on core rather than under core.sessions.
	//
	// The zero value disables it and no object-store code runs at all, which
	// is what keeps the default path byte-identical to a build without the
	// feature. See pkg/engine/objectstore for why this is a lifecycle seam
	// rather than a filesystem abstraction.
	ObjectStore objectstore.Config `yaml:"object_store"`
	// Streaming governs how the engine reconciles token streaming with the
	// gates that adjudicate model output. See StreamingConfig.
	Streaming StreamingConfig `yaml:"streaming"`
	ModelsRaw map[string]any  `yaml:"-"` // Parsed from core.models, used to build ModelRegistry
}

CoreConfig holds engine-level settings.

type DrainOverride

type DrainOverride interface {
	DrainTimeout() time.Duration
}

DrainOverride is an optional interface a plugin implements when it needs a longer drain window than the engine default for in-flight work to complete (batch pollers flushing pending submissions, MCP servers waiting on remote acks). The engine takes the maximum of the configured engine.shutdown.drain_timeout and every plugin override before draining the bus, so a single slow plugin can extend the window without forcing every operator to bump the global default. Returning a non-positive duration is equivalent to not implementing the interface.

type Engine

type Engine struct {
	Config    *Config
	Bus       EventBus
	Registry  *PluginRegistry
	Lifecycle *LifecycleManager
	Context   *ContextManager
	Session   *SessionWorkspace
	Models    *ModelRegistry
	Prompts   *PromptRegistry
	Schemas   *SchemaRegistry
	System    *SystemInfo
	Logger    *slog.Logger
	// Logging is the LoggingHost passed to plugins via PluginContext. It is
	// the same FanoutHandler that backs Logger — exposed here so embedders
	// can register their own sinks without waiting for a plugin to do it.
	Logging LoggingHost
	// Journal is the durable per-session event log. Always non-nil after
	// Boot (or ResumeSession) succeeds; closed by Stop. The bus's wildcard
	// dispatch feeds it via a writer goroutine, so handler latency does not
	// block I/O.
	Journal *journal.Writer
	// Replay is the engine-wide replay coordination point. Always non-nil
	// after construction; idle until a replay coordinator activates it.
	// Plugins inspect Replay.Active() to short-circuit side effects.
	Replay *ReplayState
	// ToolCalls is the per-call tool context registry handed to plugins as
	// PluginContext.ToolCalls. Always non-nil after construction. Boot
	// attaches it to tool.timeout; Stop cancels whatever is still live.
	ToolCalls *ToolCallContexts
	// Storage opens scoped per-plugin SQLite-backed storage. Always
	// non-nil after construction; closed by Stop. Plugins access it via
	// PluginContext.Storage rather than reaching here directly.
	Storage *storage.Manager

	// RecallSessionID, when set, causes Boot to resume an existing session
	// instead of creating a new one.
	RecallSessionID string

	// ConfigPath is the on-disk path the engine was loaded from (set by
	// New(); empty for NewFromBytes / DefaultConfig). The CLI's SIGHUP
	// handler and the browser admin endpoint use this as the default for
	// hot-reload — a ConfigReloadRequest with an empty Path re-reads from
	// here. Embedders that ship //go:embed configs can leave it empty;
	// reload requests then need an explicit Path or a different trigger.
	ConfigPath string
	// contains filtered or unexported fields
}

Engine is the top-level orchestrator that ties all engine components together.

func New

func New(configPath string) (*Engine, error)

New creates a fully wired Engine from a config file path. If configPath is empty, default configuration is used.

func NewFromBytes

func NewFromBytes(configBytes []byte) (*Engine, error)

NewFromBytes creates a fully wired Engine from an in-memory YAML config. This is the embedder-facing constructor for binaries that //go:embed their config.yaml alongside the main package and do not want a filesystem dependency at boot.

Prefer this over New("") + manual eng.Config mutation: the manual path cannot populate core.models (which is loaded via the YAML second-pass in LoadConfigFromBytes) and requires callers to hand-roll per-plugin config installation.

func (*Engine) Abandon

func (e *Engine) Abandon()

Abandon stops the engine's background workers without persisting anything.

It is Stop's counterpart for a host that is *dropping* a session rather than closing it — an ephemeral container being reclaimed mid-session, or a test simulating a process death. Stop's job is to leave the session durably stored; Abandon's job is to leave it exactly as it is.

What it stops

  • the tick heartbeat and every run-scoped bus subscription Boot installed, which includes the turn-boundary snapshot handler and the strict turn gate;
  • the object-store recovery worker;
  • the blob write-through worker, discarding whatever it still had queued;
  • the owner-marker heartbeat.

It then drops the object-store handle, closing the backend if it implements io.Closer. After this returns, nothing the engine started can write to the object store again.

What it deliberately does not do

No shutdown snapshot, no flush, no ownership release. It also does not shut plugins down, close the journal, checkpoint per-plugin SQLite, finalize the session metadata or remove the session lock: every local writer is left open and the on-disk tree is left in the state a killed process would leave it. That is the point — a caller reaching for this has decided the session's stored state is already as good as it is going to get, and a final snapshot of a tree nobody will read is pure cost on compute that is about to vanish.

The price of that fidelity is that Abandon alone leaks the journal writer's goroutine and the file handles under the session tree, which is correct for a process about to exit and wrong for one that is not. A host that wants those released too can call Stop afterwards: with the store handle already gone, Stop degenerates to local teardown and writes nothing remote.

The owner marker

The heartbeat stops; the marker stays. That asymmetry is load-bearing. A clean Stop deletes the marker, which is what keeps the broker's ordinary release-and-respawn cycle from raising a split-brain alarm on every legitimate resume. Deleting it here would tell the next host this session was cleanly released when it was not, throwing away the one piece of evidence session_owner.go exists to preserve. Keeping the heartbeat running would be the opposite error — the marker would read as live for ever and a genuine takeover would be misreported as a conflict. With the beat stopped and the marker left behind, the next host applies the ordinary staleness rules: a dead PID on the same host, or a heartbeat older than sessionOwnerStaleAfter anywhere else. See abandonSessionOwnership.

Idempotent: calling it twice, after Stop, or on an engine that never booted does nothing. Like Stop it is not safe to call concurrently with itself or with Stop. Costs nothing when no object store is configured.

func (*Engine) Boot

func (e *Engine) Boot(ctx context.Context) error

Boot starts a session, initializes all active plugins, installs run-scoped bus subscriptions, and starts the tick heartbeat. It returns as soon as the engine is ready — it does not block.

Boot is the embedder-facing entry point. Host processes (tests, other Go binaries) call Boot, then select on SessionEnded() alongside their own lifecycle signals, and finally call Stop. Boot never installs OS signal handlers; that is the host's job.

The CLI convenience wrapper Run calls Boot + wait-for-signal-or-session-end + Stop in a single blocking call.

func (*Engine) Capabilities

func (e *Engine) Capabilities() map[string][]string

Capabilities returns a snapshot of the capability → provider-IDs map resolved at boot. Safe to call after Boot; before Boot it returns nil.

func (*Engine) EndSession

func (e *Engine) EndSession()

EndSession finalizes the session metadata with ended_at and status.

func (*Engine) ReloadConfig

func (e *Engine) ReloadConfig(newConfig *Config) error

ReloadConfig applies a config change to a running engine in two phases:

  1. Validate phase (atomic): the new config is run through the same schema validation pass that Boot performs. Capability-provider identity is pinned — a Requirement.Capability that resolved to plugin X at boot cannot resolve to plugin Y on reload because the session would lose its bound state (memory.history, vector.store handles, etc.). Any failure here returns the error and leaves the engine untouched.

  2. Apply phase (best-effort): the diff between current and new active sets is walked. For each delta:

    - Plugin added: Init -> Ready (subscriptions registered by Init). - Plugin removed: Shutdown (subscriptions unregistered by Shutdown). - Config-only change, plugin implements ConfigReloader: ReloadConfig is called with old/new maps; subscriptions preserved in place. - Config-only change, no ConfigReloader: Shutdown -> Init -> Ready.

Atomicity caveat: the apply phase is best-effort. If a per-plugin ReloadConfig or Init/Ready fails partway through, prior changes have already taken effect (a restarted plugin has already side-effected onto the bus, journals, storage). The engine logs the failure and surfaces it to the caller; rollback to the pre-reload state is not attempted because "undoing" a Shutdown is not generally possible. Operators can recover by re-issuing ReloadConfig with the previous config.

Engine-level fields (Engine.Shutdown.DrainTimeout, Engine.ConfigWatch) are swapped in atomically as part of the apply phase. They take effect on the next operation that reads them — DrainTimeout on the next Stop, ConfigWatch when the watcher restarts.

func (*Engine) ReplaySession

func (e *Engine) ReplaySession(ctx context.Context, sourceSessionID string) error

ReplaySession runs deterministic replay against a previously-journaled session. The engine must already be booted; the caller is responsible for Stop afterward.

Replay opens the source session's journal at <sessions.root>/<id>/journal, seeds the engine's ReplayState with journaled responses, and re-emits io.input events in seq order. Side-effecting plugins (LLM providers, tools) detect engine.Replay.Active() and pop stashed responses instead of calling out. The current session (the one this engine booted) writes its own fresh journal — the source is read-only.

For Phase 2, replay produces functional equivalence (same final assistant outputs) rather than byte-identical event re-emission. Phase 3 will extend this to crash-resume, where partial-turn detection picks up the live mode after replay completes.

func (*Engine) ResumeSession

func (e *Engine) ResumeSession(sessionID string) error

ResumeSession loads an existing session workspace for recall and emits the session-start event. Like StartSession, it is split into a workspace- load phase (no events) and an announce phase (the io.session.start emit) so the journal writer can subscribe between them.

func (*Engine) Run

func (e *Engine) Run(ctx context.Context) error

Run is the CLI convenience wrapper: Boot + wait-for-signal-or-session-end + Stop. It installs SIGINT/SIGTERM handlers and blocks until one of them fires, a plugin emits io.session.end, or the passed context is cancelled.

Run is intended for the stock cmd/nexus binary. Embedders (tests, other Go hosts) must call Boot and Stop directly and must not call Run, because Run owns signals and blocking behavior that conflict with a host process owning the lifecycle.

func (*Engine) SessionEnded

func (e *Engine) SessionEnded() <-chan struct{}

SessionEnded returns a channel that is signalled when a plugin emits io.session.end. The channel is created by Boot; calling SessionEnded before Boot returns nil.

func (*Engine) StartSession

func (e *Engine) StartSession() error

StartSession creates a new session workspace, writes its initial metadata artifacts, and emits the session start event. The artifact writes go via SessionWorkspace.WriteFile, which dispatches session.file.created on the bus — so the journal must be running before this is called for those events to be captured. Boot enforces that ordering.

func (*Engine) Stop

func (e *Engine) Stop(ctx context.Context) error

Stop tears down the run-scoped state installed by Boot: the tick heartbeat, run-scoped bus subscriptions, session metadata finalization, and plugin shutdown in reverse dependency order. Stop is safe to call from a host's shutdown hook (e.g. a GUI framework's on-shutdown callback).

type EngineConfig

type EngineConfig struct {
	Shutdown    ShutdownConfig    `yaml:"shutdown"`
	ConfigWatch ConfigWatchConfig `yaml:"config_watch"`
}

EngineConfig holds top-level engine resilience knobs that are not strictly "core" runtime settings (log level, tick interval) and not journal-specific. Currently houses the shutdown drain timeout and the optional fsnotify-based config watcher; future resilience phases will extend this struct rather than scattering settings under core.

type Event

type Event[T any] struct {
	Type      string
	ID        string
	Timestamp time.Time
	Source    string
	Payload   T
	// Causation carries provenance for this event: which event caused it,
	// which session and agent it belongs to, and its monotonic per-session
	// sequence. Populated automatically by the bus on dispatch — callers do
	// not need to set it. See EventCausation.
	Causation EventCausation
}

Event is a typed event with payload.

func (Event[T]) Meta

func (e Event[T]) Meta() EventMeta

Meta returns the untyped metadata for this event.

type EventBus

type EventBus interface {
	// Emit dispatches an event to all matching handlers synchronously.
	Emit(eventType string, payload any) error
	// EmitEvent dispatches a pre-built event.
	EmitEvent(event Event[any]) error
	// EmitAsync dispatches an event asynchronously, returning immediately.
	// Handlers run in a separate goroutine. The returned channel receives
	// nil on success or an error, then is closed.
	EmitAsync(eventType string, payload any) <-chan error
	// Subscribe registers a handler for an event type.
	// Returns an unsubscribe function.
	//
	// Handlers run in ascending Priority order (lower runs first). Handlers
	// that share a Priority run in subscription order — the first Subscribe
	// call runs first. On vetoable (before:*) events, dispatch breaks at the
	// first veto, so the tiebreak determines which veto reason wins. To
	// encode an intentional pipeline, give each handler a distinct Priority
	// rather than relying on registration order; the engine logs a WARN at
	// boot for every (before:*, priority) tuple shared by two or more
	// handlers.
	Subscribe(eventType string, handler HandlerFunc, opts ...SubscribeOption) (unsubscribe func())
	// SubscribeAll registers a wildcard handler that receives all events
	// emitted from this point forward. Pre-subscription events are not seen.
	SubscribeAll(handler HandlerFunc) (unsubscribe func())
	// SubscribeAllReplay is SubscribeAll plus a replay of every event
	// currently held in the bus's ring buffer. The replay runs before live
	// dispatch begins for the new subscriber, so observers that init after
	// other plugins have already emitted still see those events. Replay and
	// live dispatch are serialized: no event is delivered twice, none is
	// dropped at the boundary.
	SubscribeAllReplay(handler HandlerFunc) (unsubscribe func())
	// EmitVetoable dispatches a before:* event. Handlers may veto by setting
	// the VetoResult on the payload. Returns the result.
	EmitVetoable(eventType string, payload any) (VetoResult, error)
	// HasSubscribers reports whether anything is currently subscribed to an
	// exact event type. Wildcard (SubscribeAll) observers do not count: the
	// question it answers is "would a typed handler see this", not "would
	// anything".
	//
	// It exists so a hot-path emitter can skip work that only matters when
	// someone is listening. engine.StreamPublisher uses it to avoid running
	// the before:llm.stream.chunk hook once per token delta when no gate is
	// subscribed — that hook is journaled like any other event, so emitting
	// it unconditionally would roughly double journal volume on every
	// streaming turn for no benefit.
	//
	// Advisory, not a lock: a subscription can land immediately after the
	// call returns. Use it to elide optional work, never to decide whether a
	// safety check runs.
	HasSubscribers(eventType string) bool
	// Drain waits for all in-flight events to complete within the given context.
	Drain(ctx context.Context) error
}

EventBus is the central event dispatch system.

func NewEventBus

func NewEventBus() EventBus

NewEventBus creates a new in-process EventBus with the default-sized replay ring (DefaultEventRingSize). Pass NewEventBusWithRingSize to override — typical callers do not.

func NewEventBusWithRingSize

func NewEventBusWithRingSize(capacity int) EventBus

NewEventBusWithRingSize builds a bus whose replay ring holds up to capacity events. capacity <= 0 falls back to DefaultEventRingSize.

type EventCausation

type EventCausation struct {
	// ParentID is the ID of the event whose handler emitted this event.
	// Empty for root events (boot, user input arriving from IO transport).
	ParentID string
	// ParentSeq mirrors ParentID via the per-session monotonic sequence.
	// Zero when no parent is detectable.
	ParentSeq uint64
	// SessionID is the session this event belongs to, taken from the
	// causation context active on the emitting goroutine (else the
	// bus-wide default). Empty when emitted outside any session context
	// (engine boot, shutdown) — and also empty when a pushed frame simply
	// omitted it, because PushCausationContext replaces the active context
	// whole and inherits nothing. Sub-agent dispatch must propagate this
	// explicitly; see EventBus.PushCausationContext for the idiom.
	SessionID string
	// AgentID identifies the agent that produced the event. For sub-agent
	// activity this is the sub-agent's identity, not the parent agent's,
	// so causation chains expose specialist attribution.
	AgentID string
	// Sequence is monotonic per session, assigned by the bus on publish.
	// Starts at 1 within a session; never reused.
	Sequence uint64
	// Depth is the sub-agent recursion depth at the time of emission.
	// Zero for the top-level agent, 1 for its first-level sub-agent, etc.
	Depth int
}

EventCausation records the provenance of an event. The bus assigns Sequence monotonically per session on dispatch; ParentID is the ID of the event whose handler triggered this emission (zero for root events); SessionID and AgentID come from the active causation context pushed by callers (engine/session, agent loops, sub-agent runtime). All fields are best-effort: handlers emitting outside a known session/agent context see zero values.

Causation is purely descriptive — it never affects dispatch ordering or filtering. Replay and observability are the consumers.

type EventFilter

type EventFilter func(EventMeta) bool

EventFilter is a predicate that returns true to accept an event.

type EventMeta

type EventMeta struct {
	Type      string
	ID        string
	Timestamp time.Time
	Source    string
	Causation EventCausation
}

EventMeta carries untyped event metadata for wildcard and filter use.

type EventSubscription

type EventSubscription struct {
	EventType string
	Priority  int // lower = earlier
	Filter    EventFilter
}

EventSubscription declares a handler's interest in a particular event type.

type ExcludeController

type ExcludeController interface {
	SetExcludedTypes(types []string)
	IsExcluded(eventType string) bool
}

ExcludeController is implemented by buses that can suppress journal-bound bookkeeping for high-frequency, low-value event types. The engine installs the list from JournalConfig.ExcludeEvents during startJournal. Excluded events still dispatch to typed and wildcard subscribers — only seq assignment, dispatch-stack tracking, and replay-ring append are skipped, which keeps the journal's on-disk envelope sequence gap-free.

type FanoutHandler

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

FanoutHandler is the slog.Handler installed as the engine's root logger. It writes every record into a bounded ring buffer and to every currently registered sink. It has no implicit output target — absent a registered sink, records only live in the ring. This keeps log output from leaking to stdout/stderr when a visual IO plugin owns the terminal.

FanoutHandler supports WithAttrs for per-plugin scoping (lifecycle attaches a "plugin" attr per plugin logger). WithGroup is not supported and panics if called — no plugin uses it today and proper retroactive grouping across dynamic sinks is not trivial to implement. Revisit if a consumer appears.

func NewFanoutHandler

func NewFanoutHandler(capacity int, level slog.Level) *FanoutHandler

NewFanoutHandler builds a FanoutHandler with a ring buffer of the given capacity. Capacity <= 0 falls back to DefaultLogRingSize. The level gates Enabled for the whole handler; sinks may apply additional filtering.

func (*FanoutHandler) AddLogSink

func (h *FanoutHandler) AddLogSink(sink slog.Handler) (remove func())

AddLogSink registers a sink. Records already buffered in the ring are replayed to the sink in emission order before live records flow, so a late-arriving sink never misses pre-init output. The returned remove function is idempotent — calling it more than once is a no-op.

func (*FanoutHandler) Enabled

func (h *FanoutHandler) Enabled(_ context.Context, level slog.Level) bool

Enabled reports whether records at the given level should be processed. Sinks that want stricter filtering should implement their own Enabled.

func (*FanoutHandler) Handle

func (h *FanoutHandler) Handle(ctx context.Context, r slog.Record) error

Handle applies any accumulated WithAttrs state to the record, appends it to the ring buffer, and dispatches a clone to every currently-registered sink.

func (*FanoutHandler) RingStats

func (h *FanoutHandler) RingStats() (size int, overflow uint64)

RingStats returns the current number of records in the ring and the total count of records evicted since construction. Useful for tests and observability around the bootstrap phase.

func (*FanoutHandler) WithAttrs

func (h *FanoutHandler) WithAttrs(attrs []slog.Attr) slog.Handler

WithAttrs returns a derived handler that appends attrs to every record it processes. The derivation shares the underlying core, so sinks added after derivation still see records flowing through the child.

func (*FanoutHandler) WithGroup

func (h *FanoutHandler) WithGroup(_ string) slog.Handler

WithGroup is not supported. Nexus plugin code does not use groups today; the retroactive-group semantics across dynamically registered sinks are not worth the complexity until a concrete consumer exists.

type HandlerFunc

type HandlerFunc func(Event[any])

HandlerFunc is the callback signature for event handlers.

type JournalConfig

type JournalConfig struct {
	// Fsync controls the disk-flush policy. Values: "turn-boundary"
	// (default), "every-event", "none".
	Fsync string `yaml:"fsync"`
	// RetainDays is the age past which a session journal is swept on
	// engine boot. 0 disables sweeping (in-flight sessions are never
	// touched regardless).
	RetainDays int `yaml:"retain_days"`
	// RotateSizeMB triggers segment rotation on agent.turn.end when the
	// active segment exceeds this many MiB. Rotated segments are
	// zstd-compressed.
	RotateSizeMB int `yaml:"rotate_size_mb"`
	// ExcludeEvents lists event types that the journal must not record.
	// Excluded events still dispatch to subscribers on the bus (so otel
	// and other observers see them); they are simply skipped at the
	// wildcard handler that feeds the durable log and their seq is not
	// consumed, keeping on-disk envelopes contiguous. Default is
	// ["core.tick"] — the engine heartbeat is high-frequency noise that
	// replay regenerates from its own goroutine. Set to [] to disable
	// exclusion entirely.
	ExcludeEvents []string `yaml:"exclude_events"`
}

JournalConfig tunes the durable per-session event log. Defaults are picked for the typical interactive run (turns of 5–30 events, multi-day session retention). Set fsync to "every-event" for forensic durability or "none" for ephemeral test sessions.

type LLMRequestResult

type LLMRequestResult struct {
	// Request is the request as the before:llm.request handlers left it —
	// what was published, or what was vetoed. Handlers mutate in place
	// (tags, tool filters, routing, decorated messages), so a producer that
	// keeps its own copy of the request should take this one.
	Request events.LLMRequest
	// Published reports whether llm.request was emitted.
	Published bool
	// Veto is the veto that stopped the request, when one did.
	Veto VetoResult
	// Err is the error from emitting llm.request, when it was emitted.
	Err error
}

LLMRequestResult is the outcome of PublishLLMRequest.

func PublishLLMRequest

func PublishLLMRequest(bus EventBus, req events.LLMRequest) LLMRequestResult

PublishLLMRequest runs req through the vetoable "before:llm.request" hook and, unless a handler vetoes it, emits "llm.request" with whatever the handlers left in the payload.

Every producer of an llm.request — agent loops, planners, routers, memory summarisers, gate retries, provider failover, RAG contextualisation, HITL synthesis, embedder code — must publish through this function (or PublishLLMRequestAsync) rather than calling bus.Emit("llm.request") directly. The before:llm.request hop is where the engine seeds the cost-attribution tags (session_id, tenant, project, user) and where the request-side gates and curators run (rate limiting, token budget, tool filtering, dynamic variables, routing, stream policy). A producer that skips it is invisible to all of them.

Veto semantics: a vetoed request is not emitted. Producers should branch on the result — Blocked means give up now (nothing will answer), Intercepted means a handler owns the answer and the producer should keep waiting for the llm.response as though the request had been published.

Recursion: a before:llm.request handler that itself produces an llm.request (the classifier router's probe, compaction triggered by the context-window gate) re-enters this hook. Such handlers must recognise and skip their own follow-ups; the convention is that every internal request carries a non-empty Metadata["_source"] (and the classifier also "_routed_by"), which every emitting handler already skips on. The fanout coordinator uses "_fanout_id" the same way.

func PublishLLMRequestAsync

func PublishLLMRequestAsync(bus EventBus, req events.LLMRequest) LLMRequestResult

PublishLLMRequestAsync is PublishLLMRequest for a producer that must not block on the provider round-trip (it waits for the response under its own deadline instead). The before:llm.request hop still runs synchronously, so a veto is known on return; only the llm.request emission is dispatched with EmitAsync. Err is always nil — an emission error surfaces on the async channel, which this helper does not wait for.

func (LLMRequestResult) AwaitResponse

func (r LLMRequestResult) AwaitResponse() bool

AwaitResponse reports whether an llm.response for this request is still expected: it was published, or a handler intercepted it.

func (LLMRequestResult) Blocked

func (r LLMRequestResult) Blocked() bool

Blocked reports whether the request was vetoed outright: nothing will ever answer it, so a producer waiting on its response should stop waiting.

func (LLMRequestResult) Intercepted

func (r LLMRequestResult) Intercepted() bool

Intercepted reports whether the request was vetoed by a handler that will publish its llm.response itself (see MetaInterceptedBy).

type LateShutdown

type LateShutdown interface {
	LateShutdown() bool
}

LateShutdown is an optional marker interface. A plugin that implements it and returns true is shut down after every non-late plugin, regardless of its position in dependency order. Late shutdown is intended for observers (loggers, tracers) that must stay active through peer plugins' Shutdown calls so the records emitted during teardown still reach their sink.

A late plugin is still initialized in dependency order; only shutdown ordering shifts. Late plugins are shut down among themselves in reverse init order, just like the normal phase.

type LifecycleManager

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

LifecycleManager orchestrates plugin boot and shutdown sequences.

func NewLifecycleManager

func NewLifecycleManager(registry *PluginRegistry, bus EventBus, config *Config, logger *slog.Logger, models *ModelRegistry, prompts *PromptRegistry, schemas *SchemaRegistry, system *SystemInfo) *LifecycleManager

NewLifecycleManager creates a new lifecycle manager.

func (*LifecycleManager) Boot

func (lm *LifecycleManager) Boot(ctx context.Context) error

Boot initializes all active plugins in dependency order, then signals readiness.

func (*LifecycleManager) Capabilities

func (lm *LifecycleManager) Capabilities() map[string][]string

Capabilities returns a defensive copy of the capability → provider-IDs map built during Boot. Callers can mutate the returned map safely.

func (*LifecycleManager) Plugins

func (lm *LifecycleManager) Plugins() []Plugin

Plugins returns the ordered list of initialized plugins.

func (*LifecycleManager) Shutdown

func (lm *LifecycleManager) Shutdown(ctx context.Context) error

Shutdown tears down plugins in reverse order, drains the bus, and signals completion. Plugins that implement LateShutdown and return true are shut down after every non-late plugin, so observers (logger, tracers) can still receive records emitted during peer teardown.

Drain budget: the engine waits up to engine.shutdown.drain_timeout (default 30s) for in-flight bus dispatches to complete. Plugins that implement DrainOverride may extend the budget; the engine takes the maximum across the engine default and every override so a single slow plugin can flush without forcing operators to bump the global setting.

type LoggingConfig

type LoggingConfig struct {
	// BootstrapStderr, when true, registers a stderr sink at engine
	// construction time so pre-sink records appear on the terminal. Default
	// false. Rejected by config validation when a known visual transport
	// plugin (nexus.io.tui, nexus.io.browser) is active,
	// because interleaving slog output with the UI corrupts the display.
	BootstrapStderr bool `yaml:"bootstrap_stderr"`
	// BufferSize is the capacity of the slog log ring buffer. Values <= 0
	// default to DefaultLogRingSize. The bus event ring is sized
	// independently (DefaultEventRingSize) — durable event history lives
	// in the journal, not the bus ring.
	BufferSize int `yaml:"buffer_size"`
}

LoggingConfig controls the engine-wide logging pipeline.

The engine logger is a FanoutHandler with a bounded ring buffer and zero or more dynamically-registered sinks. Absent a sink, records live only in the ring until one registers (typically the logger plugin) or they are evicted. This prevents log output from leaking to stdout/stderr when a visual IO plugin owns the terminal.

type LoggingHost

type LoggingHost interface {
	// AddLogSink registers a slog.Handler. On registration, every record
	// currently in the engine's ring buffer is replayed to the sink in
	// emission order; subsequent records are dispatched live. The returned
	// function deregisters the sink.
	AddLogSink(h slog.Handler) (remove func())
}

LoggingHost is the engine-side surface a plugin uses to become a log sink. It is threaded onto PluginContext so the logger plugin (and only the logger plugin, in practice) can register its slog.Handler and receive both the buffered pre-init records and every live record from that point forward.

The "capture, not alter" contract: registering a sink does not transform records, strip attrs, or fan out to any implicit sink. The sink sees exactly what the engine logger emits. When no sink is registered, records accumulate in a bounded ring until one registers or they are evicted.

type ModelConfig

type ModelConfig struct {
	Provider  string `yaml:"provider"`
	Model     string `yaml:"model"`
	MaxTokens int    `yaml:"max_tokens"`
	Effort    string `yaml:"effort"`

	// API names the provider-side API surface this entry wants (e.g. a
	// provider offering more than one). Opaque to core; empty means "not set".
	API string `yaml:"api"`

	// Temperature is the sampling temperature. nil means "not set"; providers
	// must leave their own default alone.
	Temperature *float64 `yaml:"temperature"`

	// Thinking, Reasoning, Cache and Retry are native provider blocks carried
	// verbatim. nil means "not set"; an empty non-nil map means "set, empty".
	Thinking  map[string]any `yaml:"thinking"`
	Reasoning map[string]any `yaml:"reasoning"`
	Cache     map[string]any `yaml:"cache"`
	Retry     map[string]any `yaml:"retry"`
}

ModelConfig describes a specific model available through a provider.

Effort is an opaque, provider-interpreted reasoning-depth hint. Core does not validate it: the vocabularies genuinely differ per provider (Anthropic uses low|medium|high|xhigh|max, Gemini minimal|low|medium|high), so an unrecognised string parses fine and is handed to the provider, which decides what to do with it. An empty value means "not set" and providers must leave their reasoning configuration untouched.

Thinking, Reasoning, Cache and Retry extend that doctrine to whole native blocks: they are the role's copy of the provider's own configuration block, stored as raw maps and forwarded verbatim. Core neither knows nor checks what any inner key means — an unknown one parses and travels, and the provider that owns the vocabulary is the only thing that rejects anything. A nil map means "the role said nothing", which is deliberately distinct from an explicitly empty block (`thinking: {}`), because the two differ once a role block is merged over a plugin-level one.

Temperature is a pointer for the same reason: 0.0 is a meaningful sampling temperature, so "unset" cannot be spelled as the zero value.

The maps are shallow copies of the parsed config, so a chain entry does not alias the loaded configuration at its top level. Nested values are shared; treat everything reachable through them as read-only.

type ModelRegistry

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

ModelRegistry resolves model role names to concrete model configurations. Each role maps to an ordered chain of ModelConfigs. The first entry is the primary; subsequent entries are fallbacks tried in order when the primary (or prior fallback) fails with a non-retryable error or exhausts retries.

Roles with fanout: true send requests to all providers in parallel instead of using sequential fallback.

func NewModelRegistry

func NewModelRegistry(modelsRaw map[string]any) *ModelRegistry

NewModelRegistry builds a ModelRegistry from the core.models config section. The modelsRaw map may contain string values (for "default" alias), map[string]any values (single model — backward compatible), and []any values (ordered fallback chain).

func (*ModelRegistry) ChainLen

func (r *ModelRegistry) ChainLen(role string) int

ChainLen returns the number of entries in the fallback chain for a role. Returns 0 if the role doesn't exist.

func (*ModelRegistry) Default

func (r *ModelRegistry) Default() ModelConfig

Default returns the ModelConfig for the default role.

func (*ModelRegistry) Fallback

func (r *ModelRegistry) Fallback(role string, attempt int) (ModelConfig, bool)

Fallback returns the ModelConfig at the given attempt index in the fallback chain for the specified role. Attempt 0 is the primary (same as Resolve). Returns false if the chain is exhausted or the role doesn't exist.

func (*ModelRegistry) FanoutProviders

func (r *ModelRegistry) FanoutProviders(role string) []ModelConfig

FanoutProviders returns all provider configs for a fanout role. Returns nil if the role is not a fanout role or doesn't exist.

func (*ModelRegistry) IsFanout

func (r *ModelRegistry) IsFanout(role string) bool

IsFanout returns true if the role is configured for parallel fanout rather than sequential fallback.

func (*ModelRegistry) Resolve

func (r *ModelRegistry) Resolve(role string) (ModelConfig, bool)

Resolve returns the primary ModelConfig for the given role name (index 0). If role is empty, the default role is used. If the role is not found but looks like a raw model ID (contains "-"), it is returned as-is with an empty provider for backward compatibility. The second return value indicates whether the role was found.

func (*ModelRegistry) Roles

func (r *ModelRegistry) Roles() []string

Roles returns the names of all registered roles.

type Plugin

type Plugin interface {
	// ID returns the unique identifier for this plugin (e.g. "provider.anthropic").
	ID() string
	// Name returns a human-readable name.
	Name() string
	// Version returns the plugin version string.
	Version() string
	// Dependencies returns a list of plugin IDs this plugin depends on.
	// Dependencies() only validates boot order; it does NOT activate anything.
	// To auto-activate a required plugin, use Requires() instead.
	Dependencies() []string
	// Requires returns plugins this one needs active to function, and the
	// default config to use when the user has not configured them.
	// The lifecycle manager expands the active plugin set at boot to include
	// every Requirement reachable from a user-declared plugin. Requires()
	// differs from Dependencies() in that it activates; Dependencies() only
	// orders. See LifecycleManager.Boot for the expansion and merge rules.
	Requires() []Requirement
	// Capabilities returns the abstract capabilities this plugin advertises
	// to the engine (e.g. "memory.history", "control.cancel"). Other plugins
	// can require a capability name via Requirement.Capability rather than a
	// concrete plugin ID, letting the engine resolve a provider at boot.
	// Return nil when the plugin advertises nothing.
	Capabilities() []Capability
	// Init initializes the plugin with its context. Called during boot.
	Init(ctx PluginContext) error
	// Ready is called after all plugins have been initialized.
	Ready() error
	// Shutdown gracefully stops the plugin.
	Shutdown(ctx context.Context) error
	// Subscriptions declares the events this plugin listens to.
	Subscriptions() []EventSubscription
	// Emissions declares the event types this plugin may emit.
	Emissions() []string
}

Plugin is the interface that all Nexus plugins must implement.

type PluginContext

type PluginContext struct {
	Config map[string]any
	Bus    EventBus
	Logger *slog.Logger
	// PluginID is the configured plugin ID, including any instance suffix
	// (e.g. "nexus.agent.subagent/researcher"). Set by the lifecycle
	// manager when the context is built. Plugins that need to identify
	// themselves to engine services (storage, journal projections) read
	// this rather than hardcoding their base ID.
	PluginID string
	// DataDir is the per-plugin session-scoped directory:
	// <session.RootDir>/plugins/<PluginID>/. Created lazily on first
	// access. Empty when the engine is constructed without a session
	// (rare; mostly tests). For storage that should outlive the session,
	// use AppDataDir or AgentDataDir, or call Storage(ScopeApp/ScopeAgent).
	DataDir string
	// AppDataDir is the per-plugin machine-wide directory:
	// ~/.nexus/plugins/<PluginID>/. Survives across sessions and agents.
	AppDataDir string
	// AgentDataDir is the per-plugin per-agent directory:
	// ~/.nexus/agents/<AgentID>/plugins/<PluginID>/. Collapses to
	// AppDataDir when the engine has no AgentID configured (CLI / single-
	// agent embedders).
	AgentDataDir string
	// Storage opens scoped SQLite-backed storage for this plugin. The
	// returned handle exposes both KV sugar (Get/Put/Delete/List) and
	// raw *sql.DB access for plugins that need joins, transactions, or
	// virtual tables (FTS5). Handles are pooled — repeated calls with
	// the same scope return the same underlying database.
	Storage func(scope storage.Scope) (storage.Storage, error)
	Session *SessionWorkspace
	Models  *ModelRegistry
	Prompts *PromptRegistry
	Schemas *SchemaRegistry
	System  *SystemInfo

	// Capabilities is a snapshot of capability → provider-IDs resolved at
	// boot. Plugins that want to conditionally enable behavior when a given
	// capability is active can inspect it here rather than string-matching
	// specific plugin IDs.
	Capabilities map[string][]string

	// Logging lets a plugin register itself as a sink for the engine's
	// structured logger. Intended for the logger plugin (or equivalents);
	// most plugins should ignore this field. Registration replays buffered
	// pre-init records, then dispatches live records. See LoggingHost.
	Logging LoggingHost

	// InstanceID is set when a plugin is activated with an instance suffix
	// (e.g. "nexus.agent.subagent/researcher"). It contains the full ID
	// including the suffix. Plugins that support multiple instances should
	// use this as their identity instead of their hardcoded ID.
	InstanceID string

	// Replay is the engine-wide replay coordination point. Always non-nil.
	// Side-effecting plugins (LLM providers, tools) check Replay.Active()
	// in their event handlers and pop a journaled response from the queue
	// instead of calling out. Idle outside of a replay run.
	Replay *ReplayState

	// ToolCalls is the engine's per-call tool context registry. A
	// tool.invoke handler calls ToolCalls.Begin(parent, call.ID) and runs
	// its work under the returned context, which is cancelled when that
	// call is timed out (a tool.timeout naming its ID) or the engine stops;
	// context.Cause reports which (ErrToolCallTimedOut,
	// ErrToolCallsStopped). Nil-safe: a nil registry (hand-built test
	// contexts) returns contexts nothing cancels. See toolcall_ctx.go.
	ToolCalls *ToolCallContexts

	// Journal is the per-session durable event log. Non-nil after
	// startJournal — i.e. always populated when plugin Init runs. Plugins
	// that observe events post-journal (rather than via the live bus)
	// register via Journal.SubscribeProjection so their derived files are
	// driven by durable envelopes instead of live dispatch.
	Journal *journal.Writer

	// Sandbox is the per-plugin execution sandbox. Resolved at boot from
	// the plugin's `sandbox:` config block; falls back to a default host
	// backend when no block is supplied. Tools that shell out or evaluate
	// code call Sandbox.Exec rather than reaching for os/exec or an
	// in-process interpreter directly. Always non-nil during Init.
	Sandbox sandbox.Sandbox

	// LookupPlugin resolves a plugin by its instance ID (including the
	// "/suffix" if instanced) and returns the live Plugin value, or nil
	// when no such plugin is active. Provided so plugins that need a
	// typed handle on another plugin (delegate runtime reaching for the
	// posture registry, orchestrators introspecting subagent state) can
	// avoid event-based handoffs that race plugin Init ordering. Always
	// non-nil during Init; the lookup itself returns nil for unknown IDs.
	LookupPlugin func(id string) Plugin
}

PluginContext provides plugins with access to engine services.

type PluginFactory

type PluginFactory func() Plugin

PluginFactory creates a new instance of a plugin.

type PluginRegistry

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

PluginRegistry stores plugin factories by ID.

func NewPluginRegistry

func NewPluginRegistry() *PluginRegistry

NewPluginRegistry creates an empty plugin registry.

func (*PluginRegistry) Get

func (r *PluginRegistry) Get(id string) (PluginFactory, bool)

Get retrieves a plugin factory by ID.

func (*PluginRegistry) List

func (r *PluginRegistry) List() []string

List returns all registered plugin IDs.

func (*PluginRegistry) Register

func (r *PluginRegistry) Register(id string, factory PluginFactory)

Register adds a plugin factory to the registry.

type PluginsConfig

type PluginsConfig struct {
	Active  []string                  `yaml:"active"`
	Configs map[string]map[string]any `yaml:"-"`
}

PluginsConfig holds plugin activation and per-plugin config.

type PromptRegistry

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

PromptRegistry collects named prompt sections that are appended to the system prompt before LLM requests reach a provider.

func NewPromptRegistry

func NewPromptRegistry() *PromptRegistry

NewPromptRegistry creates an empty PromptRegistry.

func (*PromptRegistry) Apply

func (r *PromptRegistry) Apply(systemPrompt string) string

Apply appends all registered sections to the given system prompt. Each non-empty section is separated by a double newline.

func (*PromptRegistry) Register

func (r *PromptRegistry) Register(name string, priority int, fn PromptSectionFunc)

Register adds a named prompt section. Lower priority values execute first. If a section with the same name already exists, it is replaced.

func (*PromptRegistry) Unregister

func (r *PromptRegistry) Unregister(name string)

Unregister removes a named prompt section.

type PromptSectionFunc

type PromptSectionFunc func() string

PromptSectionFunc returns the content for a named prompt section. Returning an empty string means the section is skipped.

type ReplayState

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

ReplayState is the engine-wide replay coordination point. It is always non-nil on a constructed Engine; plugins that need to short-circuit during deterministic replay query it via PluginContext.Replay.

During replay, side-effecting plugins (LLM providers, tools) check Active() and pop the next journaled response from the per-event-type FIFO queue. The ToolCache, when attached, gives tool short-circuits an args-keyed lookup that beats FIFO order — order-independent and survives memory-state divergence between original and replay runs.

func NewReplayState

func NewReplayState() *ReplayState

NewReplayState constructs an idle ReplayState. The coordinator activates it and seeds queues; plugins consume.

func (*ReplayState) Active

func (r *ReplayState) Active() bool

Active reports whether the coordinator is currently driving replay. Cheap — backed by an atomic flag — safe to call from hot paths.

func (*ReplayState) Pop

func (r *ReplayState) Pop(eventType string) (any, bool)

Pop removes and returns the next queued payload for an event type. Returns (nil, false) when the queue is empty — replay mismatch the caller should surface as a non-deterministic divergence.

func (*ReplayState) Push

func (r *ReplayState) Push(eventType string, payload any)

Push appends a journaled payload to the queue for an event type. Used by the coordinator to seed responses before driving inputs.

func (*ReplayState) Remaining

func (r *ReplayState) Remaining(eventType string) int

Remaining reports the number of queued payloads for an event type. Used by tests asserting the queue was fully drained at end of replay.

func (*ReplayState) Reset

func (r *ReplayState) Reset()

Reset clears all queues and deactivates. Coordinator calls this before each replay run so prior state cannot leak across runs in the same engine instance. The ToolCache is left attached — it is bound to the session journal directory and survives across replays.

func (*ReplayState) SetActive

func (r *ReplayState) SetActive(active bool)

SetActive flips the replay flag. Coordinator-only.

func (*ReplayState) SetToolCache

func (r *ReplayState) SetToolCache(c *ToolCache)

SetToolCache attaches an args-keyed disk cache that short-circuit helpers consult before falling back to the FIFO stash. Engine wires this at boot once the journal directory is known.

func (*ReplayState) ToolCache

func (r *ReplayState) ToolCache() *ToolCache

ToolCache returns the attached args-keyed cache, or nil when none is installed. Callers that hit nil fall through to the FIFO stash.

type Requirement

type Requirement struct {
	// ID is the plugin ID to auto-activate (e.g. "nexus.memory.capped").
	// Mutually exclusive with Capability.
	ID string
	// Capability is an abstract capability name (e.g. "memory.history") the
	// engine resolves to a concrete provider at boot. Mutually exclusive
	// with ID.
	Capability string
	// Default is the config to install when the user has not configured the
	// resolved ID. Ignored entirely when the user supplies any config.
	Default map[string]any
	// Optional controls behavior when the requirement cannot be satisfied:
	// Optional=true skips with a WARN; Optional=false fails boot.
	Optional bool
}

Requirement declares another plugin that a plugin needs to be active. Exactly one of ID or Capability must be set.

ID-based lifecycle expansion:

  • If the required ID is already in the user's active list, nothing changes; the user's config wins entirely (no field-level merge).
  • If the required ID is not active and the factory is registered, it is appended to the active set and Default is installed as its config only when the user has not configured that ID at all.
  • If the factory is not registered and Optional is true, the requirement is skipped with a WARN log; boot continues.
  • If the factory is not registered and Optional is false, boot fails.

Capability-based lifecycle expansion:

  • If an explicit pin exists in Config.Capabilities, that provider is used.
  • Otherwise the first active plugin advertising the capability (in plugins.active order) satisfies the requirement.
  • Otherwise the engine auto-activates a registered provider advertising the capability, sorted alphabetically with a WARN log when more than one candidate exists without an explicit pin.
  • Default is installed on the resolved provider ID using the same whole-object replace rule as ID-based requirements.

The merge rule for Default is whole-object replace: when the user has supplied any config for the resolved ID, Default is discarded entirely. This keeps precedence predictable and avoids surprise field merges.

type SchemaRegistry

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

SchemaRegistry collects named output schemas registered by plugins and attaches them to LLM requests tagged with _expects_schema metadata.

func NewSchemaRegistry

func NewSchemaRegistry(logger *slog.Logger) *SchemaRegistry

NewSchemaRegistry creates an empty SchemaRegistry.

func (*SchemaRegistry) Deregister

func (r *SchemaRegistry) Deregister(name string, source string)

Deregister removes a named schema. Only the original source can remove it.

func (*SchemaRegistry) HandleBeforeLLMRequest

func (r *SchemaRegistry) HandleBeforeLLMRequest(event Event[any])

HandleBeforeLLMRequest attaches ResponseFormat to requests tagged with _expects_schema. Skips if ResponseFormat is already set directly on the request.

func (*SchemaRegistry) HandleSchemaDeregister

func (r *SchemaRegistry) HandleSchemaDeregister(event Event[any])

HandleSchemaDeregister processes schema.deregister events.

func (*SchemaRegistry) HandleSchemaRegister

func (r *SchemaRegistry) HandleSchemaRegister(event Event[any])

HandleSchemaRegister processes schema.register events.

func (*SchemaRegistry) Install

func (r *SchemaRegistry) Install(bus EventBus) []func()

Install subscribes the registry to the event bus for schema management and request attachment. Returns unsubscribe functions.

func (*SchemaRegistry) Lookup

func (r *SchemaRegistry) Lookup(name string) (map[string]any, bool)

Lookup returns the schema for a given name, or nil if not found.

func (*SchemaRegistry) Register

func (r *SchemaRegistry) Register(name string, schema map[string]any, source string)

Register adds a named schema. If a schema with the same name exists, it is replaced.

type SeqController

type SeqController interface {
	SetSeqFloor(seq uint64)
}

SeqController is implemented by buses that expose their dispatch seq counter. The engine uses it on session recall to continue numbering past the existing journal's LastSeq instead of resetting to 1.

type SessionLock

type SessionLock struct {
	// PID is the OS process ID that wrote the lock. Used by IsLockStale
	// to probe liveness.
	PID int `json:"pid"`
	// StartedAt is the wall-clock time the lock was written. Operators
	// inspecting a stale lock can use it to gauge how old the crashed
	// run was; the engine itself only relies on PID for staleness.
	StartedAt time.Time `json:"started_at"`
	// Transport names the IO plugin (or whatever bootstrapped the
	// engine) so a stale-lock message can hint at where the previous
	// run came from. Optional; empty when unknown.
	Transport string `json:"transport,omitempty"`
}

SessionLock describes the contents of a session.lock file. The PID plus StartedAt are the two pieces operator tools need to detect a stale lock (process gone) versus a live lock (process still running).

func ReadSessionLock

func ReadSessionLock(dir string) (SessionLock, error)

ReadSessionLock loads the lock file at dir, returning os.ErrNotExist (wrapped) when no lock is present. A malformed lock is reported as a JSON error — callers that want to treat it as stale should do so explicitly.

type SessionLockedError

type SessionLockedError struct {
	Dir  string
	Lock SessionLock
}

SessionLockedError carries the existing lock alongside ErrSessionLocked so error messages can name the offending PID without forcing every caller to re-read the file.

func (*SessionLockedError) Error

func (e *SessionLockedError) Error() string

func (*SessionLockedError) Unwrap

func (e *SessionLockedError) Unwrap() error

type SessionMeta

type SessionMeta struct {
	ID                   string            `json:"id"`
	StartedAt            time.Time         `json:"started_at"`
	EndedAt              *time.Time        `json:"ended_at,omitempty"`
	Profile              string            `json:"profile"`
	Plugins              []string          `json:"plugins"`
	Labels               map[string]string `json:"labels"`
	TurnCount            int               `json:"turn_count"`
	TokensUsed           int               `json:"tokens_used"`
	PromptTokensUsed     int               `json:"prompt_tokens_used"`
	CompletionTokensUsed int               `json:"completion_tokens_used"`
	CostUSD              float64           `json:"cost_usd"`
	Status               string            `json:"status"`
}

SessionMeta holds metadata about a session.

type SessionTreeWriter

type SessionTreeWriter struct {
	// Source is the repo-relative file that owns the raw os.* call. It is
	// the allowlist key: a raw write anywhere else is an undecided writer.
	Source string
	// Writes describes what lands where, in session-relative terms when the
	// writer is inside the tree.
	Writes string
	// Disposition is the decision.
	Disposition SessionWriterDisposition
	// Why records the reasoning, including the rejected alternative where
	// there was a real choice to make.
	Why string
}

SessionTreeWriter records one writer's disposition.

func SessionTreeWriters

func SessionTreeWriters() []SessionTreeWriter

SessionTreeWriters returns the closed set of writers that bypass the SessionWorkspace helpers, each with a decided disposition.

Exported so the enforcement test can consume it as an allowlist rather than keeping a second copy of the same list that is free to drift from this one.

type SessionWorkspace

type SessionWorkspace struct {
	ID        string
	RootDir   string
	StartedAt time.Time
	// contains filtered or unexported fields
}

SessionWorkspace manages a session's file-based workspace.

func LoadSessionWorkspace

func LoadSessionWorkspace(rootDir string, sessionID string, bus EventBus) (*SessionWorkspace, error)

LoadSessionWorkspace opens an existing session workspace by ID. It reads the session metadata and returns a workspace pointing at the existing directory.

func NewSessionWorkspace

func NewSessionWorkspace(rootDir string, bus EventBus) (*SessionWorkspace, error)

NewSessionWorkspace creates a new session workspace with the standard directory structure.

func (*SessionWorkspace) AnnounceAppend

func (s *SessionWorkspace) AnnounceAppend(fullPath string, bytesAdded int)

AnnounceAppend announces bytesAdded bytes appended to the end of fullPath by a caller holding its own append-mode descriptor.

Unlike AnnounceWrite it takes no "existed" flag, because for an append the answer is derivable and the derived answer is better than a sampled one: a file whose post-append offset is 0 held no bytes before the append, so this is the write that made it observable and "created" is the useful signal. Sampling existed instead would report "updated" for the first real line written to a file some earlier O_CREATE had left empty — which is how the scene patch journal, opened at plugin Init and appended to on the first tool call, would otherwise never announce a creation at all.

offset is derived as size-bytesAdded rather than read back from the caller's descriptor, because the caller still owns that descriptor and this helper must not seek it. That is exact for a single-writer append (the case every caller here is) and clamps to 0 if a concurrent truncation makes the arithmetic go negative — the conservative direction, since offset 0 reads as "the whole object changed".

func (*SessionWorkspace) AnnounceWrite

func (s *SessionWorkspace) AnnounceWrite(fullPath string, existed bool)

AnnounceWrite announces a whole-file write that a caller made under the session tree with its own os.* call instead of routing through WriteFile.

Why a second door exists at all

WriteFile is the door, and everything that can use it should. But a handful of writers genuinely cannot: they hold a long-lived *os.File (the scene patch journal), they write through temp-file + rename for atomicity (the ICM artifact writer), or they own a directory tree whose layout is theirs rather than the workspace's. Forcing those through WriteFile would mean either giving up atomicity or re-implementing it inside the workspace for one caller. Announcing after the fact is the honest alternative: the bytes landed the way that writer needs them to, and the bus still learns about it.

The rejected alternative was an fsnotify watcher over the session root. It buys completeness without any call-site changes, and costs a watch descriptor per directory, a rename storm to debounce on every atomic write, and — fatally — no way to distinguish "the writer finished" from "the writer is halfway through", which is exactly the distinction a sync backend needs.

Contract

existed selects created vs updated and must be sampled *before* the write; after it, every path exists. The emitted payload is byte-for-byte the shape WriteFile emits — see AppendFile for what "offset" and "bytes_added" do and do not promise. A whole-file write reports offset 0 and bytes_added == size.

Announcing never fails the write that preceded it, so there is no error to return: a dropped announcement costs a backend one deferred upload, whereas a returned error would tempt a caller into treating a successful write as failed. Silently does nothing when the workspace has no bus, when fullPath is not under the session root, or when the path is one objectStoreExcluded rejects — so it is impossible to announce store.db or session.lock by mistake, however a future caller wires it up.

func (*SessionWorkspace) AppendFile

func (s *SessionWorkspace) AppendFile(subpath string, data []byte) error

AppendFile appends data to a file in the session workspace. It emits session.file.created or session.file.updated events.

It reuses WriteFile's two event types rather than introducing a third "appended" type. Every existing subscriber — nexus.io.tui, nexus.io.browser, nexus.tool.fileio — treats these as "this path changed, re-read it", which is exactly true of an append; a new type would have left all of them silently blind to appends until each was updated, which is the same invisibility this emission exists to remove. An append-aware delta (how many bytes landed, and at what offset) is additional information about the same change and belongs on the payload, not in a separate event type.

The append-aware delta, and what it does not promise

The payload carries "offset" (where the change begins) and "bytes_added" (how many bytes landed there) beside "size" (the file size afterwards). The invariant across both emitters is that the region [offset, offset+bytes_added) is the only part of the object that changed, so:

offset == 0 && bytes_added == size   the whole object is new (WriteFile)
offset >  0 && offset+bytes_added == size   a pure append; every byte
                                            before offset is byte-identical
                                            to what the last event described

A distinct session.file.appended event was the rejected alternative. It would have carried exactly the same three numbers, cost every existing subscriber a code change to keep seeing appends at all, and — because conversation.jsonl is written by both WriteFile and AppendFile — forced each of them to merge two event streams to reconstruct one file's history. The delta is more information about a change subscribers already receive, not a different kind of change; putting it in a separate type would have split one fact across two topics. Adding map keys is also forward-compatible with the untyped payload: a subscriber that does not read them is unaffected.

Object stores have no append primitive. Nothing here lets a backend write the appended bytes into an existing object — S3, GCS and every S3-compatible store replace whole objects, and a "multipart append" is a different object with a different lifecycle, not an edit. What the delta buys is the ability to *coalesce and defer*: a backend that knows the last 200 events on context/conversation.jsonl only added bytes to the tail knows it can collapse them into one upload of the current file at the next boundary, and knows it has not missed a rewrite in between. Anyone reading "offset" as "seek here and write bytes_added bytes into the bucket" has misread it.

Until that emission existed the highest-churn writers in a session were invisible to the bus: conversation history (context/conversation.jsonl), turn timing, compaction output, shell history and the HITL cache all append here. conversation.jsonl was the sharpest case — WriteFile covered its rewrites and nothing covered its appends, so it looked correct in a smoke test and dropped data in a real run.

func (*SessionWorkspace) BlobStore

func (s *SessionWorkspace) BlobStore(byteBudget int64, opts ...blobs.Option) (*blobs.Store, error)

BlobStore opens the session's content-addressed blob store, wired for object-store write-through.

This is the door every in-tree caller should use instead of calling blobs.New(session.BlobsDir(), ...) directly. The difference is not the path — it is the PutHook: a store opened here pushes each new blob to a configured object store the moment it lands, rather than waiting for the whole-tree snapshot at the next agent.turn.end. A store opened by hand still works and still ends up in the bucket at the turn boundary; it just does not get the write-through.

The hook is installed unconditionally and costs one atomic load per *new* blob when no backend is configured, which is what keeps the default path indistinguishable from the one that existed before write-through: no goroutine, no event, no upload, no branch anywhere else.

byteBudget is the local LRU soft cap, passed straight through. It bounds local disk only: evicting a blob here never deletes the object the store already holds. See the blobs package doc.

func (*SessionWorkspace) BlobsDir

func (s *SessionWorkspace) BlobsDir() string

BlobsDir returns the path to the per-session blobs subdirectory used by pkg/engine/blobs. Lazily created by the blob store on first Put — no directory is forced at session boot, and none by opening a store either, so a session whose tools never produce a blob has no blobs/ directory at all.

func (*SessionWorkspace) ContextDir

func (s *SessionWorkspace) ContextDir() string

ContextDir returns the path to the context subdirectory.

func (*SessionWorkspace) DeleteReservedLabel

func (s *SessionWorkspace) DeleteReservedLabel(key string) error

DeleteReservedLabel removes a reserved-namespace ("_"-prefixed) session label directly. See SetReservedLabel's doc comment — same sanctioned-path reasoning, same defensive rejection of a non-reserved key, same shared apply-and-announce step.

func (*SessionWorkspace) FileExists

func (s *SessionWorkspace) FileExists(subpath string) bool

FileExists returns true if a file exists in the session workspace.

func (*SessionWorkspace) FilesDir

func (s *SessionWorkspace) FilesDir() string

FilesDir returns the path to the files subdirectory.

func (*SessionWorkspace) ListFiles

func (s *SessionWorkspace) ListFiles(subpath string) ([]string, error)

ListFiles lists files under a subdirectory in the session workspace.

func (*SessionWorkspace) MetadataDir

func (s *SessionWorkspace) MetadataDir() string

MetadataDir returns the path to the metadata subdirectory.

func (*SessionWorkspace) PluginDir

func (s *SessionWorkspace) PluginDir(pluginID string) string

PluginDir returns the path to a plugin-specific directory, creating it lazily.

func (*SessionWorkspace) PrincipalID

func (s *SessionWorkspace) PrincipalID() (string, bool)

PrincipalID returns the turn's verified caller identity and whether one is bound. It is absent when the transport runs with no validator chain configured, which is the honest answer: with authentication disabled there is no verified identity, only whatever the caller claimed.

func (*SessionWorkspace) ReadFile

func (s *SessionWorkspace) ReadFile(subpath string) ([]byte, error)

ReadFile reads a file from the session workspace.

func (*SessionWorkspace) RequestHeader

func (s *SessionWorkspace) RequestHeader(name string) (string, bool)

RequestHeader returns one bound request header by normalized name, and whether it was present. It is the convenience form of RequestHeaders for the common single-lookup case (`session.RequestHeader("timezone")`).

func (*SessionWorkspace) RequestHeaders

func (s *SessionWorkspace) RequestHeaders() (map[string]string, error)

RequestHeaders returns the X-Nexus-* headers bound for the current turn, keyed by normalized header name, or an empty map when none are bound.

This is the read seam for a plugin that never sees io.input — a tool, a memory provider, an LLM provider — and it is why the headers are bound to the session at all rather than only carried on the event. Plugins that DO handle io.input can read events.UserInput.Headers instead and skip the metadata read.

func (*SessionWorkspace) SaveMeta

func (s *SessionWorkspace) SaveMeta(meta *SessionMeta) error

SaveMeta writes session metadata to disk. It emits session.file.created or session.file.updated for metadata/session.json.

The write is routed through WriteFile rather than calling os.WriteFile and emitting alongside it. metadata/session.json is rewritten on every llm.response (token and cost totals) and every agent.turn.end (turn count), so it is one of the most frequently changed files in a session and was previously changing without a single event. Delegating means there is one implementation of "write a session file and announce it" — a second copy here would be free to drift in event type, payload shape or permissions, and the two would then disagree about the most-written file in the tree.

func (*SessionWorkspace) SessionMetadata

func (s *SessionWorkspace) SessionMetadata() (*SessionMeta, error)

SessionMeta reads and returns the session metadata.

func (*SessionWorkspace) SetLabel

func (s *SessionWorkspace) SetLabel(key, value string) error

SetLabel writes a general-namespace (non-reserved) session label directly, bypassing the before:session.tag.set vetoable bus path entirely.

A second sanctioned direct-write seam, for trusted decode-time input

Every other general-namespace write goes through installSessionTagHandlers, which lets a subscriber veto. This method exists for a caller that already sits on trusted, already-authenticated, already-decoded input and gains nothing from a veto hop — the same reasoning nexus.io.agui's buildUserInput already applies to RunAgentInput.messages when folding them into events.UserInput with no veto hop of its own. RunAgentInput.Context items are the motivating case: they ride an authenticated transport already, so re-litigating them through a gate built for untrusted general writes (e.g. a tool call) would add a hop with no caller able to usefully veto it.

A reserved ("_"-prefixed) key is rejected here, defensively, for the exact reason SetReservedLabel/DeleteReservedLabel reject a non-reserved one: this method bypasses the general validation completely, and without this check a caller mistake (or a client smuggling a "_"-prefixed key through RunAgentInput.Context) could write into the reserved namespace with none of the vetoable path's protection. See installSessionTagHandlers's doc comment for the risk this guards against on the bus path; this is the same guard on this second, non-bus path.

Ends by calling the same internal apply-and-announce step every other label write uses, so session.tag.set fires here exactly as it does for the vetoable general path or a reserved direct write.

func (*SessionWorkspace) SetPrincipalID

func (s *SessionWorkspace) SetPrincipalID(id string) error

SetPrincipalID binds the turn's verified caller identity, or clears it when id is empty.

Transports call this before emitting the turn's first downstream event, for the reason SetRequestHeaders documents: a plugin must never observe a turn ahead of the identity it belongs to. Every turn re-binds fresh rather than leaving the previous turn's value in place, so a conversation continued under a different principal is never read as still belonging to the first.

func (*SessionWorkspace) SetRequestHeaders

func (s *SessionWorkspace) SetRequestHeaders(headers map[string]string) error

SetRequestHeaders binds the X-Nexus-* headers of the request that opened the current turn as reserved session labels, REPLACING whatever the previous turn bound.

Why replace rather than merge

These describe one request, not the session. A second turn arriving without `X-Nexus-Tenant` must not be read by a plugin as still carrying the first turn's tenant: a stale bind that looks exactly like a fresh one is the one failure mode worth designing against here, and it is why the previous set is cleared in the same write that lays down the new one. nexus.io.agui already applies the same reasoning to `_principal_id` — every run re-binds fresh, with no "unchanged, skip the write" case — and this follows it.

Passing an empty map clears the namespace, which is the correct handling of a turn whose request carried no X-Nexus-* header at all.

Ordering

Call this BEFORE emitting the turn's io.input, for the reason bindSessionContext documents in nexus.io.agui: a plugin that reads the headers while handling io.input must not be able to observe the turn before the context it belongs to. Both the clear and the bind land in one read-modify-write, so no consumer ever sees a half-replaced set on disk.

Header names are expected to be normalized already (nexusheaders.Extract does this); a name carrying a "/" or a "=" is rejected rather than written, since a session-label key is also a manifest key and a prompt line.

func (*SessionWorkspace) SetReservedLabel

func (s *SessionWorkspace) SetReservedLabel(key, value string) error

SetReservedLabel writes a reserved-namespace ("_"-prefixed) session label directly, bypassing the general before:session.tag.set bus path entirely.

This is the only sanctioned write path for a reserved key

installSessionTagHandlers's before:session.tag.set handler rejects every reserved key unconditionally, with no veto exception and no caller-trust distinction — that is the one enforcement point protecting the reserved namespace from an ordinary plugin writing (or overwriting) something like `_principal_id` through the general request path. This method is the other side of that wall: the identity layer (nexus.io.agui today; a future transport tomorrow) calls it directly as a Go method, never through the bus, precisely because the bus path is barred to it. Calling this with a non-reserved key is rejected too — defensively, since this method bypasses the general validation completely and a caller mistake here would otherwise write an uncontrolled key with none of the vetoable path's checks.

Ends by calling the same internal apply-and-announce step the general path uses, so session.tag.set fires for a reserved write exactly as it does for a general one — one announce channel for everything watching session labels, regardless of which path produced the write.

func (*SessionWorkspace) WriteFile

func (s *SessionWorkspace) WriteFile(subpath string, data []byte) error

WriteFile writes data to a file within the session workspace. It emits session.file.created or session.file.updated events.

The emitted payload carries an append-aware delta — "offset" and "bytes_added" — alongside "size"; see the comment on AppendFile for why the delta lives on this payload rather than in a third event type, and for what a sync backend may and may not conclude from it. A whole-file write reports offset 0 and bytes_added == size, which is the honest reading of "every byte of this object is new".

type SessionWriterDisposition

type SessionWriterDisposition string

SessionWriterDisposition names what the object-store seam does with the bytes one writer puts under a session tree.

const (
	// DispositionEmit means the writer announces every write on the bus via
	// SessionWorkspace.AnnounceWrite / AnnounceAppend (or the WriteFile /
	// AppendFile helpers), so a sync backend can push it the moment it lands
	// and does not have to wait for a turn to end.
	DispositionEmit SessionWriterDisposition = "emit"

	// DispositionTurnBoundary means the writer is silent on the bus by
	// decision, and its bytes reach the store only through the whole-tree
	// snapshot taken at agent.turn.end (and at shutdown). This is a real
	// disposition, not an absence of one: the files still sync, just not in
	// real time.
	DispositionTurnBoundary SessionWriterDisposition = "turn-boundary-only"

	// DispositionExcluded means the bytes must never leave the machine at
	// all — not on the bus, not in the snapshot. Reserved for files that
	// describe the *host* rather than the session, where a faithful copy is
	// precisely the wrong thing to restore.
	DispositionExcluded SessionWriterDisposition = "excluded-by-design"

	// DispositionWriteThrough means the writer pushes to the object store the
	// moment its bytes land, without going through the bus at all.
	//
	// It is a fourth disposition rather than a flavour of DispositionEmit
	// because the two make different promises to a reader of this table. An
	// "emit" row says a subscriber can observe the write; a "write-through"
	// row says the bytes are already on their way to the store and no
	// subscriber will ever hear about them. Collapsing them would license a
	// sync backend to wait for events that are never emitted.
	//
	// Only justified where the object key is derived from the content, so a
	// duplicate upload is a no-op rather than a race and no barrier is needed
	// to order it against the turn-boundary snapshot. That is exactly one
	// subtree today: the sha256-addressed blob store.
	DispositionWriteThrough SessionWriterDisposition = "write-through"
)

type SessionsConfig

type SessionsConfig struct {
	Root      string `yaml:"root"`
	Retention string `yaml:"retention"`
	IDFormat  string `yaml:"id_format"`
}

SessionsConfig controls session workspace behavior.

type ShutdownConfig

type ShutdownConfig struct {
	// DrainTimeout caps how long the engine waits for in-flight events to
	// drain on Shutdown. Zero falls back to defaultShutdownDrainTimeout.
	DrainTimeout time.Duration `yaml:"drain_timeout"`
}

ShutdownConfig governs engine shutdown behavior. DrainTimeout is the wall clock the engine gives in-flight bus dispatches to complete before the plugin Shutdown phase begins; plugins that need a longer drain (batch pollers, MCP servers) opt in via the DrainOverride interface and the engine takes the larger of the two.

type StorageConfig

type StorageConfig struct {
	// Root overrides the data root used for App and Agent scope storage.
	// Defaults to "~/.nexus" (the same root used for sessions).
	Root          string `yaml:"root"`
	BusyTimeoutMs int    `yaml:"busy_timeout_ms"`
	CacheSizeKB   int    `yaml:"cache_size_kb"`
	PoolMaxIdle   int    `yaml:"pool_max_idle"`
	PoolMaxOpen   int    `yaml:"pool_max_open"`
}

StorageConfig tunes the per-plugin SQLite storage manager. Defaults match storage.DefaultSQLiteOptions and are picked for an interactive single-user agent.

type StreamPublisher

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

StreamPublisher is the single path from a provider's SSE loop to the bus, and the streaming half of the response-veto contract that PublishLLMResponse implements for whole responses.

The problem it solves: before:llm.response fires once, at end of stream, by which point every token has already been rendered. A veto there governs what enters history and what drives tools, but it cannot unsay text. The standing advice was therefore to run disclosure-preventing gates with streaming off — which, on top of costing time-to-first-token, was advice an operator could not actually follow, since the agent loops hardcode Stream: true.

So gating moves into the stream. Every text delta is offered to before:llm.stream.chunk as an *events.StreamSegment before any of it reaches the bus, and a handler can pass, redact, suspend, or block it. The guarantee that buys is categorical rather than best-effort: withheld text was never emitted, so it is not a question of whether a given transport can retract. It never had anything to retract.

Three properties make that hold in practice:

  • Suspension composes with detection latency. A handler that cannot yet judge a trailing fragment holds it (StreamSegment.Hold) instead of gambling. Held bytes are re-offered, prepended to the next delta, so a handler holding at least its longest pattern can never be beaten by a pattern split across two deltas.

  • A blocked stream stays blocked. Once a handler vetoes, the publisher drops what it was holding and swallows every later delta for the turn. Nothing re-opens it; the substitute arrives through PublishLLMResponse, as it does for the non-streaming path.

  • The unguarded path is unchanged. With nothing subscribed to before:llm.stream.chunk, Text emits exactly the delta it was handed, with no buffering, no extra events, and no hook dispatch.

What it deliberately does not do is make the residue vanish. Bytes released before a pattern was detectable are gone; llm.stream.retract asks transports to disown them and most can, but a human who already read them has read them. Hold is the knob that shrinks that window, and a gate that holds its full pattern width shrinks it to nothing.

A publisher belongs to one turn. Providers create one at stream start and Close it when the SSE loop ends, on every path including error returns. Methods are safe to call from one goroutine; providers drive their SSE loop from one, and the mutex guards against a Close racing a late delta rather than against genuine concurrent production.

func NewStreamPublisher

func NewStreamPublisher(bus EventBus, turnID, requestID string) *StreamPublisher

NewStreamPublisher returns a publisher for one turn's stream. requestID may be empty for providers that do not correlate, but passing it lets a gate tie a held or blocked stream back to the request that produced it.

func (*StreamPublisher) Blocked

func (sp *StreamPublisher) Blocked() (bool, string)

Blocked reports whether a handler cut this stream short, and why. Providers have no obligation to act on it — the response-level veto is what substitutes the answer — but it is useful for logging, and for a provider that wants to stop reading an SSE body it can no longer publish.

func (*StreamPublisher) Close

func (sp *StreamPublisher) Close()

Close flushes whatever is still held and settles any outstanding hold.

The final flush still runs the hook — a handler gets one last look at the tail it was deferring — but Hold is ignored on it: the stream is over, so "wait for more context" is no longer an option and the handler must decide. A handler that would rather block than release an unresolved tail vetoes here, which is the same move it has on any other segment.

Idempotent. Providers should defer it so an error path cannot leave a stream suspended forever.

func (*StreamPublisher) Released

func (sp *StreamPublisher) Released() string

Released returns the text actually emitted so far, post-redaction. Provided for tests and for providers that want to log the divergence between what the model produced and what the user saw.

func (*StreamPublisher) Text

func (sp *StreamPublisher) Text(delta string)

Text offers a text delta to the gate and emits whatever it allows.

The fast path — no before:llm.stream.chunk subscriber, nothing held, not blocked — emits delta verbatim and allocates nothing beyond the chunk itself, so an ungated deployment pays for none of this.

func (*StreamPublisher) ToolCall

func (sp *StreamPublisher) ToolCall(tc *events.ToolCallRequest)

ToolCall publishes a tool-call chunk. Tool calls bypass the text gate: they are not disclosure — nothing of a tool call is shown to a user as prose — and the authority over whether they may run belongs to before:llm.response, which clears ToolCalls on every substitution, and to before:tool.invoke, which sees parsed arguments. Gating a partial JSON fragment here would duplicate that with strictly less information.

A blocked stream still suppresses them, because a turn whose text was blocked is a turn whose response is about to be substituted anyway.

type StreamingConfig

type StreamingConfig struct {
	// ResponseGatePolicy decides what happens when a plugin gating
	// before:llm.response, without a before:llm.stream.chunk handler, is
	// active:
	//
	//   "downgrade" (default) — clear Stream on outbound LLM requests, so
	//   the gate sees the response before any of it is shown. Costs
	//   time-to-first-token; buys the non-disclosure the gate implies.
	//
	//   "allow" — leave Stream alone and log a warning at boot. The gate
	//   still governs conversation history and tool execution; it no longer
	//   governs what the user sees.
	//
	// Empty means "downgrade".
	ResponseGatePolicy string `yaml:"response_gate_policy"`
}

StreamingConfig governs the engine's reconciliation of token streaming with output gating.

Streaming and gating pull against each other: a gate that judges the whole response cannot run until the response is complete, by which point every token has been rendered. Nexus resolves that two ways. Gates that implement before:llm.stream.chunk adjudicate text before it is released and keep their guarantee with streaming on. Gates that implement only before:llm.response cannot, so by default the engine turns streaming off for them rather than letting their veto look like protection it is not.

type SubscribeOption

type SubscribeOption func(*subscribeConfig)

SubscribeOption configures a subscription.

func WithFilter

func WithFilter(f EventFilter) SubscribeOption

WithFilter sets an event filter on the subscription.

func WithPriority

func WithPriority(p int) SubscribeOption

WithPriority sets the handler priority (lower = earlier execution).

func WithSource

func WithSource(pluginID string) SubscribeOption

WithSource tags the subscription with a plugin ID.

type SubscriptionInfo

type SubscriptionInfo struct {
	EventType string
	Priority  int
	Source    string
}

SubscriptionInfo describes one typed subscription currently registered on a bus: the event type, the priority it was registered at, and the source tag passed via WithSource (empty when none was given). It carries no handler and no filter — it is a read-only view for introspection, not a way to dispatch.

type SubscriptionInspector

type SubscriptionInspector interface {
	RegisteredSubscriptions() []SubscriptionInfo
}

SubscriptionInspector is implemented by buses that can report their typed handler table. Wildcard (SubscribeAll) observers are not included. The contract harness uses it to check that the priority a plugin declares in Subscriptions() is the priority it actually subscribed at: the declaration is what operators and ordering tooling read, the registration is what dispatch obeys, and nothing else keeps the two in step.

The result is a snapshot ordered by event type, then dispatch order within a type. A subscription can land or be removed immediately after it returns.

type SystemInfo

type SystemInfo struct {
	OS   string // runtime.GOOS: "darwin", "linux", "windows", etc.
	Arch string // runtime.GOARCH: "amd64", "arm64", etc.

	// OpenCmd is the OS-native command for opening files/folders/URLs.
	// Empty if no suitable command was found.
	OpenCmd  string
	OpenArgs []string // extra args prepended before the target path
}

SystemInfo provides platform details detected at engine startup. Available to all plugins via PluginContext.System.

func DetectSystem

func DetectSystem() *SystemInfo

DetectSystem builds a SystemInfo from the current runtime environment.

func (*SystemInfo) HasOpen

func (s *SystemInfo) HasOpen() bool

HasOpen reports whether an OS-native open command is available.

type ToolCache

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

ToolCache persists tool.result payloads keyed by sha256(tool_id || canonical_args) under <session>/journal/cache/<tool_id>/<sha>.json. It is the durable, args-addressable companion to ReplayState's FIFO queue — replay tries the cache first (deterministic order-independent lookup) and falls back to the FIFO stash on miss.

The cache is bus-driven: a single subscription pair (tool.invoke + tool.result) records every tool that completes. Tools do not need to know about it, but the cache itself is exposed via ReplayState so the short-circuit helper can read on replay.

func NewToolCache

func NewToolCache(rootDir string, logger *slog.Logger) *ToolCache

NewToolCache constructs a cache rooted at <session>/journal/cache. The directory is created lazily on first write — empty sessions do not produce a cache subtree.

func (*ToolCache) Install

func (c *ToolCache) Install(bus EventBus) []func()

Install registers the cache as a bus subscriber so live tool.invoke / tool.result pairs auto-populate the cache. Returns the unsubscribe functions for the engine's run-scoped teardown.

func (*ToolCache) Lookup

func (c *ToolCache) Lookup(toolID string, args map[string]any) (events.ToolResult, bool)

Lookup attempts to return a cached result for the given tool name + canonical args. Returns ok=false on cache miss, malformed JSON, or a canonicalize failure (the caller falls back to the FIFO stash).

type ToolCallContexts added in v0.31.0

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

ToolCallContexts is the engine-owned registry of per-call contexts for tool dispatch. A tool.invoke handler calls Begin with the call's ID and runs its work under the returned context; anything that decides the call is over — the engine on a tool.timeout event, the engine on Stop, or any other holder of the registry — calls Cancel with that ID, and the handler's context is cancelled with a cause it can read back with context.Cause.

Cancellation is cooperative: the registry kills nothing itself. A handler that never calls Begin, or ignores the context it gets, keeps running exactly as before; its eventual result is the caller's to drop (the tool_timeout gate already vetoes a late result for a call it timed out).

The registry is keyed by call ID, which is how every tool lifecycle event (tool.invoke, tool.result, tool.timeout) is correlated. A Cancel for an ID with no live Begin is a no-op: it does not pre-cancel a later Begin.

Once attached to a bus, the registry also learns which turn each call belongs to from tool.invoke, so CancelTurn (and a cancel.active event) can reach every live call a cancelled turn set in motion — including calls a nested loop (subagent, delegate) issued on that turn's behalf, which carry the turn as ParentTurnID.

The zero value is not usable; build one with NewToolCallContexts. A nil *ToolCallContexts is valid and behaves as a registry nothing ever cancels, so plugins can use PluginContext.ToolCalls unconditionally even when a hand-built test context leaves it unset.

func NewToolCallContexts added in v0.31.0

func NewToolCallContexts() *ToolCallContexts

NewToolCallContexts returns an empty registry. The engine builds one per Engine and hands it to every plugin as PluginContext.ToolCalls; tests that drive a plugin against a bare bus build their own and Attach it.

func (*ToolCallContexts) Attach added in v0.31.0

func (r *ToolCallContexts) Attach(bus EventBus) func()

Attach subscribes the registry to bus:

  • tool.invoke records the call's turn(s) so CancelTurn can find it; tool.result forgets them.
  • tool.timeout cancels the timed-out call's context with a cause wrapping ErrToolCallTimedOut.
  • cancel.active cancels every live call bound to the cancelled turn (every live call, when the event names no turn) with a cause wrapping ErrToolCallCancelled.

It returns the unsubscribe func. The engine attaches its registry at Boot; any plugin that emits tool.timeout or cancel.active therefore cancels the dispatch with no further wiring.

func (*ToolCallContexts) Begin added in v0.31.0

func (r *ToolCallContexts) Begin(parent context.Context, callID string) (context.Context, func())

Begin derives a cancellable context for the call with the given ID from parent and registers it. The returned release func unregisters it and releases the context's resources; call it (typically deferred) when the handler is finished with the call. release is idempotent.

On a nil registry or an empty callID, Begin returns a plain cancellable child of parent that nothing else can cancel.

func (*ToolCallContexts) Cancel added in v0.31.0

func (r *ToolCallContexts) Cancel(callID string, cause error) bool

Cancel cancels every live context registered for callID with cause (nil means context.Canceled) and reports whether there was one. Entries stay registered until their handler releases them, so a repeated Cancel is a harmless no-op on an already-cancelled context.

func (*ToolCallContexts) CancelAll added in v0.31.0

func (r *ToolCallContexts) CancelAll(cause error)

CancelAll cancels every live call with cause. The engine calls it on Stop.

func (*ToolCallContexts) CancelTurn added in v0.31.0

func (r *ToolCallContexts) CancelTurn(turnID string, cause error) int

CancelTurn cancels every live call bound to turnID with cause (nil means context.Canceled) and returns how many contexts it cancelled. A call is bound to a turn when its tool.invoke carried that turn as TurnID or as ParentTurnID (see events.ToolCall.BindingTurnID), so cancelling a parent turn also reaches the calls a subagent or delegate loop issued for it. Calls of other turns are untouched. The turn mapping comes from the bus, so CancelTurn only reaches calls whose tool.invoke an attached registry saw.

func (*ToolCallContexts) Live added in v0.31.0

func (r *ToolCallContexts) Live(callID string) bool

Live reports whether a context is currently registered for callID.

type VetoResult

type VetoResult struct {
	Vetoed bool
	Reason string
}

VetoResult is the outcome of a vetoable (before:*) event dispatch.

type VetoableCollisionReporter

type VetoableCollisionReporter interface {
	WarnVetoableCollisions()
}

VetoableCollisionReporter is implemented by buses that can scan their handler table for equal-priority subscribers on vetoable (before:*) events. Equal-priority handlers on a veto-breaking event have their relative order decided by subscription sequence, so a benign plugin reorder or activation-set change can silently flip a safety decision. The engine calls WarnVetoableCollisions after all plugins finish Init so operators see the collisions in the boot log; bus-internal logger (SetLogger) is used.

type VetoablePayload

type VetoablePayload struct {
	Original any        // domain payload passed by the caller
	Veto     VetoResult // handlers set this to veto the action
}

VetoablePayload wraps the original domain payload for before:* events. Handlers inspect Original (e.g. *events.ToolCall) and set Veto to block. The wrapper is a pointer so handler mutations propagate back to EmitVetoable.

Directories

Path Synopsis
Package allplugins provides a single RegisterAll function that registers every built-in plugin factory with an engine.PluginRegistry.
Package allplugins provides a single RegisterAll function that registers every built-in plugin factory with an engine.PluginRegistry.
internal/optincheck
Package optincheck is a build-graph canary.
Package optincheck is a build-graph canary.
Package blobs implements a content-addressed blob store for multimodal payloads (images, audio, documents, video) referenced from event-payload MessageParts.
Package blobs implements a content-addressed blob store for multimodal payloads (images, audio, documents, video) referenced from event-payload MessageParts.
Package configwatch is an internal helper that fires a callback whenever the on-disk YAML config changes.
Package configwatch is an internal helper that fires a callback whenever the on-disk YAML config changes.
Package journal is the engine's durable, append-only event log.
Package journal is the engine's durable, append-only event log.
Package objectstore defines the lifecycle seam between a Nexus data tree on local disk and a remote object store, plus the driver-style registry that lets a backend module make itself selectable by name.
Package objectstore defines the lifecycle seam between a Nexus data tree on local disk and a remote object store, plus the driver-style registry that lets a backend module make itself selectable by name.
enginetest
Package enginetest holds the shared kill-and-resume suite: a real *engine.Engine, driven through a real object-store backend, killed, and resumed on a clean filesystem.
Package enginetest holds the shared kill-and-resume suite: a real *engine.Engine, driven through a real object-store backend, killed, and resumed on a clean filesystem.
objectstoretest
Package objectstoretest holds the shared conformance suite for objectstore.Backend, plus Memory - an in-memory backend that passes it.
Package objectstoretest holds the shared conformance suite for objectstore.Backend, plus Memory - an in-memory backend that passes it.
Package pricing centralizes per-model token pricing for all LLM providers.
Package pricing centralizes per-model token pricing for all LLM providers.
Package sandbox is the engine-wide execution-isolation abstraction.
Package sandbox is the engine-wide execution-isolation abstraction.
host
Package host is the trivially-isolated sandbox backend: shell commands run directly via os/exec against the host kernel.
Package host is the trivially-isolated sandbox backend: shell commands run directly via os/exec against the host kernel.
wasm
Package wasm is the wazero-backed sandbox for agent-generated Go snippets.
Package wasm is the wazero-backed sandbox for agent-generated Go snippets.
wasm/host
Package host implements the wasm host module that backs the nexus_sdk/* snippet API.
Package host implements the wasm host module that backs the nexus_sdk/* snippet API.
Package storage provides per-plugin SQLite-backed key/value and SQL storage scoped at session, agent, or application levels.
Package storage provides per-plugin SQLite-backed key/value and SQL storage scoped at session, agent, or application levels.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL