Event Types Reference

Complete reference for all event types in Nexus, organized by domain.

Core Events

Payloads

BootConfig

ShutdownReason

TickInfo

ErrorInfo

core.error is vetoable — providers emit before:core.error first. The fallback plugin can veto the error to suppress it and retry with an alternate provider.

I/O Events

Payloads

UserInput

FileAttachment

AgentOutput

OutputChunk

StatusUpdate

ApprovalRequest

ApprovalResponse

AskUser

AskUserResponse

Provider Events

Payloads

ProviderFallback

ProviderFanoutStart

ProviderFanoutTarget

ProviderFanoutResponse

ProviderFanoutComplete

LLM Events

Payloads

LLMRequest

Message

ToolCallRequest

ToolDef

ToolChoice

ToolFilter

ResponseFormat

Metadata Conventions

Certain metadata keys carry special meaning:

LLMResponse

Usage

Multimodal tool results

ToolResult carries an OutputParts []MessagePart field for tools that emit multimodal content (image, audio, document, video). When non-empty, memory plugins copy the parts onto the resulting tool-role Message.Parts so the next LLM request includes the multimodal content alongside (or in place of) Output.

Large payloads should be stored via pkg/engine/blobs and referenced via MessagePart.URI = "nexus-blob:<sha256>" so the journal stays compact; small payloads can ride inline as MessagePart.Data. Provider plugins resolve nexus-blob: URIs at request-assembly time.

StreamChunk

StreamEnd

Tool Events

Payloads

ToolCall

ToolResult

ToolDef

Code Execution Events

Emitted by nexus.tool.code_exec alongside the standard tool.invoke/tool.result pair. Let other plugins observe programmatic tool-calling scripts without recomputing the run_code envelope from a tool result.

CodeExecRequest

CodeExecStdout

Chunks are flushed on every newline and on a ~512-byte threshold so long lines without newlines still reach the UI promptly. Consumers should concatenate Chunk values across events to reconstruct the full stdout stream; the final CodeExecResult.Output also carries the full aggregated string for non-streaming consumers.

CodeExecResult

Agent Events

Payloads

TurnInfo

Plan

PlanStep

AgentToolChoice

Subagent Events

Payloads

SubagentSpawn

SubagentComplete

Memory Events

Payloads

MemoryEntry

MemoryQuery

CompactionTriggered

CompactionComplete

Long-Term Memory Events

LongTermMemoryIndex

LongTermMemoryStoreRequest

Plan Events

Payloads

PlanRequest

PlanResult

PlanResultStep

PlanProgress

Skill Events

Payloads

SkillCatalog

SkillSummary

SkillContent

Schema Events

Payloads

SchemaRegistration

SchemaDeregistration

Session Events

The five object-store rows exist only when core.object_store.backend names a backend. With none configured — the default — nothing subscribes, a session.snapshot.request is inert, and none of the other four is ever emitted. See Object Storage. The four session tag events are independent of the object store and always active — see Session Tag Events below.

session.file.created / session.file.updated payload

Emitted as a map[string]any, not as the events.SessionFile struct, because every subscriber type-asserts a map. The struct is nonetheless the definition of the shape: the payload is built by events.SessionFile.Map, so renaming or retyping a field trips make check-events, and adding one without a wire key fails its own test. Before that the struct was declared and unused, and this payload was guarded by nothing at all.

The three counts are Go int, not int64. That is the type that has always been on the wire and subscribers assert it directly, so widening the struct field would turn every one of those assertions into a silent zero.

There is deliberately no action key. The action is the event type, and a copy of it in the payload is a second source of truth that can disagree with the first — which is what nexus.tool.pdf did, reporting every update as a creation.

Which event fires is decided by whether the path existed before the write, so a subscriber can rely on seeing exactly one created per path per session.

Who emits it. SessionWorkspace.WriteFile, AppendFile and SaveMeta, plus the two announcement helpers AnnounceWrite / AnnounceAppend that writers holding their own os.* call use — today nexus.scene (its state file and patch journal), nexus.workflows.icm (stage artifacts and copied inputs), nexus.tool.fileio (write_file) and the desktop matcher plugin. Every one of them publishes the session-relative path, so it can be used directly as an object key. nexus.tool.pdf used to emit a second, hand-built event beside the one WriteFile already produced, carrying the bare basename and no delta; it was removed rather than reconciled, and the plugin no longer emits session.file.* at all.

Writers that deliberately stay silent — the journal, the tool cache, the blob store, per-plugin SQLite and the session lock among them — each have a recorded reason. See Sessions.

The append-aware delta. offset and bytes_added together say that the region [offset, offset+bytes_added) is the only part of the object that changed:

They were added to this payload rather than introduced as a separate session.file.appended event: a new type would have carried the same three numbers, cost every existing subscriber a change just to keep seeing appends, and — because context/conversation.jsonl is written by both WriteFile and AppendFile — forced each of them to merge two streams to reconstruct one file’s history. New map keys are also invisible to subscribers that do not read them.

Object stores have no append primitive. These keys do not let a sync backend write appended bytes into an existing object; S3, GCS and every S3-compatible store replace whole objects. What they buy is the freedom to coalesce and defer — collapse a run of tail appends into one upload of the current file at the next boundary, knowing no rewrite was missed in between. offset is not a seek position in the bucket.

If the offset cannot be determined, offset is reported as 0, which reads as a whole -object change: a backend then re-uploads a file it could have coalesced, rather than coalescing a change it should have treated as a rewrite.

Who emits them

Every emitter goes through one of those five entry points, so every payload on the wire is built in one place. Two hand-built emitters that were not — nexus.tool.pdf and cmd/desktop/internal/matcher — published malformed events (a bare basename as path, an absolute host path, missing session_id, no delta keys); the first was removed and the second was routed through AnnounceWrite. Because the payload is an untyped map, a subscriber should still treat offset and bytes_added as optional and fall back to “the whole object changed” when they are absent — which is the same conservative reading offset == 0 already asks for.

AppendFile deliberately reuses the same two event types rather than introducing an append-specific one, so every existing subscriber sees appends without being changed. The events say this path changed, and here is which part of it changed; they never carry the changed bytes themselves.

Two moments are deliberately silent. Creating or loading a session workspace writes metadata/session.json without emitting, because that happens before the journal writer subscribes to the bus and an event there would consume a dispatch sequence number the journal never receives — which stalls its writer permanently. Engine.StartSession re-saves the metadata once the journal is running, so the file is still announced.

SessionSnapshotRequest

SessionSnapshotResult

Both events exist only when core.object_store.backend names a backend; with none configured nothing subscribes and a request is inert.

SessionOwnerConflict

Emitted at most once per run, during Boot, and only when core.object_store.backend names a backend. Detection, not prevention: by the time it is emitted the engine has already claimed the session and is running normally. No lock is taken, no fencing token is issued, nothing is refused and nothing waits. A subscriber that wants to act — page an operator, stop the run — has to do so itself. See Sessions → Two hosts, one session.

SessionStorageDegraded

SessionStorageRecovered

The two pair: exactly one session.storage.degraded per outage and one session.storage.recovered when it ends, so a subscriber counts outages rather than failed requests. Neither is emitted when core.object_store.backend is empty.

Under degrade the session keeps taking turns while degraded. The honest caveat is that the durability guarantee is not being met for as long as the outage lasts, even though nothing is failing.

Under strict TurnsBlocked is true and every subsequent io.input is vetoed until the state is stored. The turn that hit the outage already ran — its output was streamed, its tools executed — and the engine cannot un-run it. What strict guarantees is that no further turn runs against unstored state. Recovery is automatic under both policies; see Configuration → Failure policy.

The engine snapshots at every agent.turn.end on its own, so nothing needs to emit session.snapshot.request in a normal run — it is the escape hatch for embedders driving the engine outside an agent loop, and for custom agents that emit no turn events. Snapshotting is handled in core and never depends on plugin cooperation. See Sessions → Turn-boundary snapshots.

Session Tag Events

SessionMeta.Labels — the session’s key/value tag store — is split into two disjoint namespaces: reserved keys (starting with _) and general keys (everything else). Only general keys are reachable through the two before:* events below; a reserved key is rejected unconditionally, regardless of caller. See Session Tags for the full mechanism.

SessionTagSetRequest — payload of before:session.tag.set

SessionTagDeleteRequest — payload of before:session.tag.delete

Both ride the bus as the struct itself (via VetoablePayload.Original), not as a hand-spelled map — the same shape before:llm.request uses. The single handler for both lives in the core engine: it vetoes unconditionally when Key matches the reserved namespace (engine.IsReservedLabelKey), with a VetoResult.Reason naming the rejection, and otherwise applies the write immediately and fires the matching announce event below. There is no second “apply” step after the veto check passes — the request event doubles as the trigger, because the core engine is the only thing that knows how to mutate SessionMeta.Labels safely.

SessionTagSet — payload of session.tag.set

SessionTagDeleted — payload of session.tag.deleted

Both announce events fire from every successful write, whichever path produced it: the vetoable general path above, or the reserved-namespace direct-Go-call path (SessionWorkspace.SetReservedLabel / DeleteReservedLabel, e.g. nexus.io.agui’s _principal_id identity binding), which never touches the bus at all. A subscriber that only cares “this session’s tags changed” needs only these two event types regardless of which path wrote the label. SessionTagDeleted is also the end-of-run signal for nexus.io.agui’s identity binding: a transport that set _principal_id on run start deletes it on run end.

Unlike the object-store events above, all four session tag events are always active — they do not depend on core.object_store.backend.

Cancellation Events

CancelRequest

Embeddings Events

Payloads

EmbeddingsRequest

EmbeddingsInput

Adapters that don’t support image inputs must return a clear error when they encounter an image-bearing input rather than silently downgrading. See nexus.embeddings.cohere_multimodal for a multimodal-aware reference adapter.

EmbeddingsUsage

Vector Store Events

All four are pointer-fill — adapter sets Provider / Error (and Matches on query) in place.

Payloads

VectorDoc

VectorMatch

VectorUpsert

VectorQuery

VectorDelete

VectorNamespaceDrop

RAG Events

Payloads

RAGIngest

RAGIngestDelete

VectorMemoryStore

Delegate Events

Emitted by nexus.agent.delegate when a parent agent invokes a posture via the delegate tool. Payloads are map[string]any records — see pkg/delegate.Runtime for the canonical fields.

Posture Events

Emitted by nexus.agent.postures as posture YAML loads or changes.

Scene Events

Emitted by nexus.scene on every mutation. agent_id on the payload comes from Event.Causation.AgentID — sub-agent contributions remain attributable in the journal.

Tool Stream Events

Emitted by pkg/streamtool.Bridge while a ChannelTool runs. Consumers that only need the final value still subscribe to tool.result; UIs and observability collectors that want incremental progress subscribe here.

Thinking Events

ThinkingStep

ICM Workflow Events

Emitted by nexus.workflows.icm on top of the generic plan.created / plan.progress surface. Every payload carries a _schema_version field (constants in plugins/workflows/icm/icmtypes/types.go).

ICMRunStarted

ICMRunCompleted

ICMRunHalted

ICMStageStarted

ICMStageCompleted

ICMStageFailed

ICMStageIteration

ICMTurn

ICMFanoutItem

ICMPredicateFailed

ConditionResult (shared by ICMStageIteration.ExitFailures and ICMTurn.LastFailures)