Documentation
¶
Overview ¶
Package event defines the stream events shared by agent runtimes and the conversation layer.
Index ¶
Constants ¶
View Source
const RuntimeNoticesMetadataKey = "runtime_notices"
RuntimeNoticesMetadataKey stores UI-only runtime facts alongside a round. Notices must never become model prose or enter the provider transcript.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type FileAttachment ¶
type FileAttachment struct {
Type string `json:"type"`
Base64 string `json:"base64,omitempty"`
Path string `json:"path,omitempty"`
URL string `json:"url,omitempty"`
PlatformKey string `json:"platform_key,omitempty"`
Mime string `json:"mime,omitempty"`
Name string `json:"name,omitempty"`
ContentHash string `json:"content_hash,omitempty"`
Size int64 `json:"size,omitempty"`
Metadata map[string]any `json:"metadata,omitempty"`
}
FileAttachment represents a file reference extracted from agent output.
type Notice ¶ added in v0.21.0
type Notice struct {
Code string `json:"code,omitempty"`
Content string `json:"content"`
Args map[string]string `json:"args,omitempty"`
}
Notice is the public part of a RuntimeNotice event. Producers must supply public text and arguments, just as they do for the live conversation stream.
func AppendNotice ¶ added in v0.21.0
AppendNotice coalesces repeated delivery of the same public fact in a run.
func NoticeFromStream ¶ added in v0.21.0
func NoticeFromStream(ev StreamEvent) (Notice, bool)
NoticeFromStream excludes diagnostic fields and non-string metadata from the durable record, matching the existing public notice projection.
func NoticesFromMetadata ¶ added in v0.21.0
NoticesFromMetadata accepts both in-process values and JSON-decoded rows.
type NoticeKind ¶ added in v0.21.0
type NoticeKind string
NoticeKind names the degradation a RuntimeNotice reports.
const ( // NoticeNativeHistoryLost: the runtime started a new native session and // does not remember the conversation shown so far. NoticeNativeHistoryLost NoticeKind = "native_history_lost" NoticeToolsUnavailable NoticeKind = "tools_unavailable" // NoticeElicitationDeclined: a request for user input was declined // without asking the user. NoticeElicitationDeclined NoticeKind = "elicitation_declined" // NoticeSteerFailed: an instruction sent during the turn was not // delivered to the runtime. NoticeSteerFailed NoticeKind = "steer_failed" // NoticeOutputTruncated: the model stopped because it reached its output // limit, so the reply is cut off. NoticeOutputTruncated NoticeKind = "output_truncated" )
type ReactionItem ¶
type ReactionItem struct {
Emoji string `json:"emoji"`
}
ReactionItem represents an emoji reaction extracted from agent output.
type SpeechItem ¶
type SpeechItem struct {
Text string `json:"text"`
}
SpeechItem represents a TTS request extracted from agent output.
type StreamEvent ¶
type StreamEvent struct {
InternalFeedbackIndexes []int `json:"internal_feedback_indexes,omitempty"`
Type StreamEventType `json:"type"`
Delta string `json:"delta,omitempty"`
ToolName string `json:"toolName,omitempty"`
ToolCallID string `json:"toolCallId,omitempty"`
ApprovalID string `json:"approvalId,omitempty"`
UserInputID string `json:"userInputId,omitempty"`
ShortID int `json:"shortId,omitempty"`
Status string `json:"status,omitempty"`
Input any `json:"input,omitempty"`
// InlineDecision marks a request whose caller waits inside the current turn.
InlineDecision bool `json:"inline_decision,omitempty"`
Metadata map[string]any `json:"metadata,omitempty"`
Progress any `json:"progress,omitempty"`
Result any `json:"result,omitempty"`
Attachments []FileAttachment `json:"attachments,omitempty"`
Reactions []ReactionItem `json:"reactions,omitempty"`
Speeches []SpeechItem `json:"speeches,omitempty"`
Messages json.RawMessage `json:"messages,omitempty"`
Usage json.RawMessage `json:"usage,omitempty"`
Reasoning []string `json:"reasoning,omitempty"`
Code string `json:"code,omitempty"`
Error string `json:"error,omitempty"`
Attempt int `json:"attempt,omitempty"`
MaxAttempt int `json:"maxAttempt,omitempty"`
StepNumber int `json:"stepNumber,omitempty"`
TotalSteps int `json:"totalSteps,omitempty"`
ProgressStatus string `json:"progressStatus,omitempty"`
// RetryDelayMs and RetryReason describe a Retry: how long the runtime
// waits before it calls the model again, and the class of the failure
// (rate_limited, server_error, stream_incomplete, network). The
// provider's own text never reaches the wire.
RetryDelayMs int64 `json:"retryDelayMs,omitempty"`
RetryReason string `json:"retryReason,omitempty"`
// NoticeKind is set by the runtime on a RuntimeNotice. It never reaches
// the wire: the application replaces it with Code.
NoticeKind NoticeKind `json:"-"`
// Cause is the failure an Error event from the native runtime reports. It
// never reaches the wire: the application translates it into Code and
// the catalog detail.
Cause error `json:"-"`
// Args are the catalog args of the public error an Error event reports
// under Code.
Args map[string]string `json:"args,omitempty"`
}
StreamEvent is emitted by an agent runtime during streaming. The JSON shape is the wire format WebSocket clients consume; do not change tags.
func (StreamEvent) IsTerminal ¶
func (e StreamEvent) IsTerminal() bool
IsTerminal returns true for events that signal end of stream.
type StreamEventType ¶
type StreamEventType string
StreamEventType identifies the kind of stream event.
const ( AgentStart StreamEventType = "agent_start" TextStart StreamEventType = "text_start" TextDelta StreamEventType = "text_delta" TextEnd StreamEventType = "text_end" ReasoningStart StreamEventType = "reasoning_start" ReasoningDelta StreamEventType = "reasoning_delta" ReasoningEnd StreamEventType = "reasoning_end" ToolCallInputStart StreamEventType = "tool_call_input_start" ToolCallStart StreamEventType = "tool_call_start" ToolCallMetadata StreamEventType = "tool_call_metadata" ToolCallProgress StreamEventType = "tool_call_progress" ToolCallEnd StreamEventType = "tool_call_end" ToolApprovalRequest StreamEventType = "tool_approval_request" UserInputRequest StreamEventType = "user_input_request" Attachment StreamEventType = "attachment_delta" Reaction StreamEventType = "reaction_delta" Speech StreamEventType = "speech_delta" AgentEnd StreamEventType = "agent_end" AgentAbort StreamEventType = "agent_abort" Retry StreamEventType = "retry" Progress StreamEventType = "progress" Error StreamEventType = "error" // RuntimeNotice surfaces a runtime-side degradation the user should see // in the conversation (tools unavailable, an interaction declined). // A runtime sets NoticeKind and Delta; the application turns the kind // into the public Code before the event leaves it. RuntimeNotice StreamEventType = "runtime_notice" // CommandOutput is native command output, separate from model prose. CommandOutput StreamEventType = "command_output" // RuntimeStatus replaces the current transient activity; an empty Code clears it. RuntimeStatus StreamEventType = "runtime_status" // StepEnd marks that every streamed part of one model step has been // emitted. StepNumber carries the durable step index. It is a sequencing // marker for the session runtime, carries no visible content, and is // emitted before the step's commit barrier runs, so a consumer that has // seen it holds the complete pre-commit projection of that step. StepEnd StreamEventType = "step_end" )
Source Files
Directories
Click to show internal directories.
Click to hide internal directories.