events

Event-bus shapes.

agent-shutdown #

Emitted once per run during teardown. :error is present for crashed paths.

Fields for agent-shutdown event contract

Field	Type	Required	Summary
:agent #	Agent	yes	Agent instance associated with the event.
:error #	string		Crash details when shutdown follows an error path.
:reason #	keyword	yes	:normal | :crashed
:type #	:agent-shutdown	yes	Event discriminator for :agent-shutdown events.

agent-started #

Emitted once per run after setup and before the first new step.

Fields for agent-started event contract

Field	Type	Required	Summary
:agent #	Agent	yes	Agent instance associated with the event.
:cwd #	string	yes	Working directory for the active agent run.
:model #	string	yes	Model identifier selected for the active run.
:provider #	keyword|string	yes	Provider name selected for the active run.
:type #	:agent-started	yes	Event discriminator for :agent-started events.

agent-turn-complete #

Emitted once per submitted user turn after the agent coroutine finishes and the presenter busy flag has been cleared.

Fields for agent-turn-complete event contract

Field	Type	Required	Summary
:agent #	Agent	yes	Agent instance associated with the completed turn.
:error #	string		Error summary when the turn ended with :status :error.
:message-count #	number	yes	Conversation message count after the turn finished.
:result #	string		Final visible assistant text for successful or cancelled turns, when available.
:status #	keyword	yes	:ok | :cancelled | :error
:type #	:agent-turn-complete	yes	Event discriminator for :agent-turn-complete events.

assistant-stream-end #

Stream finished. Emitted once after all per-block end events for a single AssistantMessage.

Fields for assistant-stream-end event contract

Field	Type	Required	Summary
:type #	:assistant-stream-end	yes	Event discriminator for :assistant-stream-end events.

assistant-text #

Final visible text emitted by the assistant. One per AssistantMessage with text blocks.

Fields for assistant-text event contract

Field	Type	Required	Summary
:final? #	boolean		True when this is the final aggregate payload for the current block.
:text #	string	yes	Complete assistant text payload for this event.
:type #	:assistant-text	yes	Event discriminator for :assistant-text events.

assistant-text-delta #

Streaming text token. Aggregated by presenters during a stream.

Fields for assistant-text-delta event contract

Field	Type	Required	Summary
:delta #	string	yes	Incremental streamed text fragment for the open content block.
:type #	:assistant-text-delta	yes	Event discriminator for :assistant-text-delta events.

assistant-thinking #

Final reasoning text from the assistant (for providers that surface reasoning content).

Fields for assistant-thinking event contract

Field	Type	Required	Summary
:final? #	boolean		True when this is the final aggregate payload for the current block.
:text #	string	yes	Complete assistant text payload for this event.
:type #	:assistant-thinking	yes	Event discriminator for :assistant-thinking events.

assistant-thinking-delta #

Streaming reasoning token.

Fields for assistant-thinking-delta event contract

Field	Type	Required	Summary
:delta #	string	yes	Incremental streamed text fragment for the open content block.
:type #	:assistant-thinking-delta	yes	Event discriminator for :assistant-thinking-delta events.

cancelled #

Cooperative cancel observed; the current step appended an aborted assistant message.

Fields for cancelled event contract

Field	Type	Required	Summary
:type #	:cancelled	yes	Event discriminator for :cancelled events.

compaction-summary #

Context compaction completed and produced a summary for older messages.

Fields for compaction-summary event contract

Field	Type	Required	Summary
:guidance #	string		Optional user guidance supplied to /compact.
:messages-kept #	number		Number of recent messages kept verbatim.
:messages-summarized #	number		Number of older messages summarized.
:summary #	string	yes	Summary text installed into the compacted model context.
:tokens-after #	number		Approximate context tokens after compaction.
:tokens-before #	number		Approximate context tokens before compaction.
:trigger #	keyword		Why compaction ran, such as :manual.
:type #	:compaction-summary	yes	Event discriminator for :compaction-summary events.

dismiss #

Presenter signal that an open overlay/picker should close.

Fields for dismiss event contract

Field	Type	Required	Summary
:type #	:dismiss	yes	Event discriminator for :dismiss events.

done #

Provider stream: terminal event for a successful AssistantMessage.

Fields for done event contract

Field	Type	Required	Summary
:message #	AssistantMessage	yes	Canonical assistant message produced by the provider stream.
:type #	:done	yes	Event discriminator for :done events.

error #

Generic surface error — typically command-dispatch or user-input failures.

Fields for error event contract

Field	Type	Required	Summary
:error #	string	yes	Human-readable error message for presenters and logs.
:type #	:error	yes	Event discriminator for :error events.

extension-error #

Emitted when an extension event handler raises. Suppressed for recursive extension-error events to prevent loops.

Fields for extension-error event contract

Field	Type	Required	Summary
:error #	string	yes	Human-readable error message for presenters and logs.
:event #	keyword|string		Original event being handled when the extension error occurred.
:owner #	keyword|string		Extension owner whose handler raised, when known.
:type #	:extension-error	yes	Event discriminator for :extension-error events.

extension-loaded #

Emitted by the loader for each successfully loaded extension manifest.

Fields for extension-loaded event contract

Field	Type	Required	Summary
:first-party? #	boolean		True when the loaded extension came from fen's bundled extension set.
:name #	string	yes	Extension manifest name that was loaded.
:type #	:extension-loaded	yes	Event discriminator for :extension-loaded events.

info #

Transient informational message intended for the presenter status row or panel.

Fields for info event contract

Field	Type	Required	Summary
:info #	string		Human-readable informational message payload.
:text #	string		Alternative human-readable informational text.
:type #	:info	yes	Event discriminator for :info events.

llm-end #

Provider call completed (success or error). The :message field carries the canonical AssistantMessage.

Fields for llm-end event contract

Field	Type	Required	Summary
:message #	AssistantMessage	yes	Canonical assistant message produced by the provider stream.
:type #	:llm-end	yes	Event discriminator for :llm-end events.

llm-start #

Provider call beginning.

Fields for llm-start event contract

Field	Type	Required	Summary
:model #	string		Model identifier used for the provider request, when known.
:provider #	keyword		Provider name for the outbound LLM call, when known.
:type #	:llm-start	yes	Event discriminator for :llm-start events.

message-appended #

Emitted by fen.core.agent immediately after agent.messages grows.

Fields for message-appended event contract

Field	Type	Required	Summary
:agent #	Agent	yes	Agent instance associated with the event.
:index #	number	yes	1-based index of the appended message.
:message #	Message	yes	Canonical message that was appended to the conversation.
:type #	:message-appended	yes	Event discriminator for :message-appended events.

queued #

User-line queued while the agent is busy. Consumed by the agent on natural-stop.

Fields for queued event contract

Field	Type	Required	Summary
:line #	string	yes	Raw user input line associated with the event.
:type #	:queued	yes	Event discriminator for :queued events.

redraw #

Presenter hint that a registered panel needs to be repainted.

Fields for redraw event contract

Field	Type	Required	Summary
:type #	:redraw	yes	Event discriminator for :redraw events.

reinit-presenter #

Presenter signal that the UI should be torn down and re-initialized (used by /reload).

Fields for reinit-presenter event contract

Field	Type	Required	Summary
:type #	:reinit-presenter	yes	Event discriminator for :reinit-presenter events.

reset-conversation #

Presenter signal that the active conversation should be cleared (used by /new).

Fields for reset-conversation event contract

Field	Type	Required	Summary
:type #	:reset-conversation	yes	Event discriminator for :reset-conversation events.

set-status-info #

Presenter-level status hint. Owners post a transient status line; nil clears.

Fields for set-status-info event contract

Field	Type	Required	Summary
:info #	string|nil		Transient status text to show, or nil to clear it.
:type #	:set-status-info	yes	Event discriminator for :set-status-info events.

start #

Provider stream opened. Marker event emitted before any block events.

Fields for start event contract

Field	Type	Required	Summary
:type #	:start	yes	Event discriminator for :start events.

text-delta #

Provider stream: incremental text token within the open block.

Fields for text-delta event contract

Field	Type	Required	Summary
:content-index #	number	yes	Position within the assistant's content array.
:delta #	string	yes	Incremental streamed text fragment for the open content block.
:type #	:text-delta	yes	Event discriminator for :text-delta events.

text-end #

Provider stream: TextContent block closed; full text supplied.

Fields for text-end event contract

Field	Type	Required	Summary
:content #	string	yes	Complete text or thinking content for the closed stream block.
:content-index #	number	yes	Position within the assistant's content array.
:type #	:text-end	yes	Event discriminator for :text-end events.

text-start #

Provider stream: a TextContent block is starting.

Fields for text-start event contract

Field	Type	Required	Summary
:content-index #	number	yes	Position within the assistant's content array.
:type #	:text-start	yes	Event discriminator for :text-start events.

thinking-delta #

Provider stream: incremental reasoning token within the open block.

Fields for thinking-delta event contract

Field	Type	Required	Summary
:content-index #	number	yes	Position within the assistant's content array.
:delta #	string	yes	Incremental streamed text fragment for the open content block.
:type #	:thinking-delta	yes	Event discriminator for :thinking-delta events.

thinking-end #

Provider stream: ThinkingContent block closed; full text supplied.

Fields for thinking-end event contract

Field	Type	Required	Summary
:content #	string	yes	Complete text or thinking content for the closed stream block.
:content-index #	number	yes	Position within the assistant's content array.
:type #	:thinking-end	yes	Event discriminator for :thinking-end events.

thinking-start #

Provider stream: a ThinkingContent block is starting.

Fields for thinking-start event contract

Field	Type	Required	Summary
:content-index #	number	yes	Position within the assistant's content array.
:type #	:thinking-start	yes	Event discriminator for :thinking-start events.

tool-call #

Tool call about to execute. Carries the canonical ToolCall block.

Fields for tool-call event contract

Field	Type	Required	Summary
:tool-call #	ToolCall	yes	Canonical tool-call block associated with this event.
:type #	:tool-call	yes	Event discriminator for :tool-call events.

tool-call-delta #

Provider stream: incremental JSON-text fragment for the open ToolCall arguments. Some providers stream arguments token-by-token; consumers may concatenate.

Fields for tool-call-delta event contract

Field	Type	Required	Summary
:content-index #	number	yes	Position within the assistant's content array.
:delta #	string	yes	Incremental streamed text fragment for the open content block.
:type #	:tool-call-delta	yes	Event discriminator for :tool-call-delta events.

tool-call-end #

Provider stream: ToolCall block closed; complete canonical ToolCall block supplied.

Fields for tool-call-end event contract

Field	Type	Required	Summary
:content-index #	number	yes	Position within the assistant's content array.
:tool-call #	ToolCall	yes	Canonical tool-call block associated with this event.
:type #	:tool-call-end	yes	Event discriminator for :tool-call-end events.

tool-call-start #

Provider stream: a ToolCall block is starting; arguments not yet known.

Fields for tool-call-start event contract

Field	Type	Required	Summary
:content-index #	number	yes	Position within the assistant's content array.
:type #	:tool-call-start	yes	Event discriminator for :tool-call-start events.

tool-result #

Tool execution finished. Carries the canonical ToolResultMessage.

Fields for tool-result event contract

Field	Type	Required	Summary
:result #	ToolResultMessage	yes	Canonical tool-result message produced by the tool executor.
:type #	:tool-result	yes	Event discriminator for :tool-result events.

user #

User-submitted line accepted by the presenter input layer. Distinct from :queued (which fires when the line is queued during a busy turn).

Fields for user event contract

Field	Type	Required	Summary
:line #	string	yes	Raw user input line associated with the event.
:type #	:user	yes	Event discriminator for :user events.