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.
Per-modality token counts when the provider reports them. Lowercase keys: text, image, audio, video, document. Empty when the provider does not split modalities (Anthropic) or the request was text-only. Cost-attribution consumers read this to bill image / audio turns separately.
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.
Optional structured payload. When the tool’s ToolDef.OutputSchema is set, this should match that schema. Consumed by typed consumers like run_code’s bindings — Output stays freeform text for the LLM.
TurnID
string
Associated turn
ToolDef
Field
Type
Description
Name
string
Tool name the LLM will use
Description
string
Description shown to the LLM
Parameters
map[string]any
JSON Schema for inputs
OutputSchema
map[string]any
Optional JSON Schema describing the shape of ToolResult.OutputStructured. When set, run_code generates a typed Go struct bound to this schema.
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.
Event Type
Payload
Description
code.exec.request
CodeExecRequest
Script about to run; carries source, imports, active skills
code.exec.stdout
CodeExecStdout
Incremental stdout chunk produced while the script runs; Final=true marks the last chunk
code.exec.result
CodeExecResult
Script finished (success, compile error, runtime error, veto, or timeout)
CodeExecRequest
Field
Type
Description
CallID
string
Matches the outer run_code tool call ID
TurnID
string
Associated turn
Script
string
Full Go source submitted by the LLM
Imports
[]string
Import paths referenced by the script
Skills
[]string
Names of currently-active skills whose helpers were staged
CodeExecStdout
Field
Type
Description
CallID
string
Matches the outer run_code tool call ID
TurnID
string
Associated turn
Chunk
string
UTF-8 bytes written to stdout since the last emission; may contain newlines
Final
bool
True for the closing chunk of this call; code.exec.result follows immediately after
Truncated
bool
Only meaningful on the final chunk — true when total stdout exceeded max_output_bytes
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
Field
Type
Description
CallID
string
Matches the outer run_code tool call ID
TurnID
string
Associated turn
Output
string
Captured stdout (capped at max_output_bytes)
Result
string
JSON-marshaled Run() return value
Error
string
First error encountered (AST rejection, compile, runtime, timeout)
Batch of strings to embed (input). Used when Inputs is empty — back-compat with text-only adapters.
Inputs
[]EmbeddingsInput
Polymorphic batch (text + image inputs) for multimodal-aware providers. When non-empty, providers consume Inputs and ignore Texts.
Model
string
Requested model; provider may echo back actual model used.
Dimensions
int
Optional truncation hint. Zero = provider default.
Vectors
[][]float32
Result vectors, in input order (output).
Provider
string
Plugin ID of the adapter that answered (output).
Usage
EmbeddingsUsage
Token usage when reported by the provider (output).
Error
string
Non-empty on failure (output).
EmbeddingsInput
Field
Type
Description
Text
string
Text snippet. Mutually exclusive with Image and ImageURI.
Image
[]byte
Inline image bytes. Mutually exclusive with Text and ImageURI. Requires MimeType.
ImageURI
string
Image reference: nexus-blob:<sha> (engine blob store) or external URL. Mutually exclusive with Text and Image.
MimeType
string
IANA media type (e.g. image/png). Required when Image is set; recommended for ImageURI.
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.
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.
Event Type
Payload
Description
delegate.start
map
Sub-session is starting. Keys: sub_session_id, posture, posture_ver, task, parent_turn, depth.
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.
Event Type
Payload
Description
scene.created
map
New Scene created. Keys: session_id, scene_id, schema, version, agent_id, content (initial content).
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.
Event Type
Payload
Description
tool.stream.progress
map
Status-only update from a streaming tool. Keys: tool_name, tool_id, turn_id, sequence, progress (0.0–1.0 or -1), payload.
tool.stream.partial
map
Incremental data the consumer can render now. Keys: tool_name, tool_id, turn_id, sequence, payload.
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).
Event Type
Payload
Description
icm.run.started
ICMRunStarted
Workspace loaded; run created; before stage 1 dispatches.
icm.run.completed
ICMRunCompleted
All stages finished without halt.
icm.run.halted
ICMRunHalted
Stage error policy halted, gate rejected, or run context cancelled.
icm.stage.started
ICMStageStarted
Stage execution begins, before any human_gate: start.
icm.stage.completed
ICMStageCompleted
Artifact written; any end gate resolved.
icm.stage.failed
ICMStageFailed
Stage halted (dispatch error, rejected gate, or loop.on_exhausted: error).
icm.stage.iteration
ICMStageIteration
One per loop iteration, immediately before the iteration’s invocation.
icm.turn
ICMTurn
After each turn within an invocation (richer-UI feed; basic UIs already see plan.progress).
icm.fanout.item
ICMFanoutItem
Item lifecycle boundary in a fan-out stage (active → completed | failed).
icm.predicate.failed
ICMPredicateFailed
Any predicate evaluation returns verdict=false. Pass paths are not emitted.
ICMRunStarted
Field
Type
Description
RunID
string
Run identifier (r_<id>); also the on-disk dir under the plugin’s session data dir.
InstanceID
string
Plugin instance ID (nexus.workflows.icm or nexus.workflows.icm/<suffix>).
WorkspaceRoot
string
Absolute path to the loaded workspace.
WorkspaceName
string
Last folder name of the workspace path.
Stages
int
Stage count.
ICMRunCompleted
Field
Type
Description
RunID
string
Run identifier.
StagesRun
int
Number of stages that completed.
AggregatePath
string
Optional run aggregate path (set when a top-level aggregate is produced).
ElapsedSeconds
int64
Wall-clock seconds from icm.run.started.
ICMRunHalted
Field
Type
Description
RunID
string
Run identifier.
Reason
string
Free-text halt reason.
HaltedAtStage
string
Stage ID where the halt fired (empty for pre-stage halts).
Cancelled
bool
true when the halt was a context cancellation rather than a gate reject.
ElapsedSeconds
int64
Wall-clock seconds from icm.run.started.
ICMStageStarted
Field
Type
Description
RunID
string
Run identifier.
StageID
string
Stage folder name (e.g. 02_brief).
PostureName
string
Derived posture name registered for this stage (icm.<runID>.<stage_id>).
Order
int
1-based stage order in the workspace.
ICMStageCompleted
Field
Type
Description
RunID
string
Run identifier.
StageID
string
Stage folder name.
ArtifactPath
string
Path to the final artifact.
IterationsRun
int
Loop iterations executed (0 for non-looping stages).
ConvergenceFailed
bool
true when the loop exhausted without satisfying until.
ICMStageFailed
Field
Type
Description
RunID
string
Run identifier.
StageID
string
Stage folder name.
Reason
string
Free-text failure reason.
ICMStageIteration
Field
Type
Description
RunID
string
Run identifier.
StageID
string
Stage folder name.
ItemID
string
Fan-out item ID (empty for non-fan-out stages).
Iteration
int
1-based iteration index.
MaxIterations
int
loop.max_iterations.
ExitFailures
[]ConditionResult
Previous iteration’s failing until predicates (empty on iteration 1).