Documentation
¶
Overview ¶
Package event defines the unified event model for LLM streaming in deepwork. All 9 Portals (Chat, Browser Sidebar, Open Design, Studio, Council, Claw, Companion, Workspace Run, CLI Escape) consume the same Event type regardless of source family (CLI Observer / LLM API Orchestrator / WebChat DOM Polling).
Design: TH-0503-k8v (8 rounds, 12 Codex reviews, 15 DDC, 7 BRR, 2 EUREKA).
Index ¶
- type DoneData
- type Emitter
- type Event
- func Burst(content string) []Event
- func DoneEvent(reason string, inputTokens, outputTokens int) Event
- func ErrorEvent(msg string) Event
- func RawEvent(data json.RawMessage) Event
- func StatusEvent(status string) Event
- func TextEvent(content string) Event
- func ThinkingEvent(content string) Event
- func ToolResultEvent(id, name, output string, isErr bool, durMs int) Event
- func ToolStartEvent(id, name string, input json.RawMessage) Event
- func UsageEvent(data UsageData) Event
- type Kind
- type ToolData
- type UsageData
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DoneData ¶
type DoneData struct {
Reason string `json:"reason,omitempty"` // stop / tool_use / length / cancel / error
InputTokens int `json:"input_tokens,omitempty"` // LLM: prompt tokens
OutputTokens int `json:"output_tokens,omitempty"` // LLM: completion tokens
}
DoneData holds stream completion information including usage.
type Emitter ¶
─── Emitter ────────────────────────────────────────── Emitter is the universal callback for streaming events. Returns false to signal the producer should stop (backpressure / client disconnect).
func Discard ¶
func Discard() Emitter
Discard returns an Emitter that silently drops all events. For benchmarks.
func NewSSEEmitter ¶
NewSSEEmitter creates an Emitter that writes each Event as an SSE data line. Returns false (backpressure) when the SSE write fails (client disconnected).
func SafeEmitter ¶
SafeEmitter wraps an Emitter with a mutex for concurrent use. Use this when multiple goroutines emit to the same downstream (e.g., Council fan-in).
func SeqEmitter ¶
SeqEmitter wraps an Emitter to stamp monotonic sequence numbers into Meta["seq"].
func TimestampEmitter ¶
TimestampEmitter wraps an Emitter to stamp current time into Meta["ts"].
type Event ¶
type Event struct {
Kind Kind `json:"kind"`
Status string `json:"status,omitempty"` // Status: waiting / running / tool / etc.
Content string `json:"content,omitempty"` // Text/Thinking/Error: direct string
Tool *ToolData `json:"tool,omitempty"` // ToolStart/ToolResult: structured
Usage *UsageData `json:"usage,omitempty"` // Usage: token accounting update
DoneInfo *DoneData `json:"done,omitempty"` // Done: usage + reason
Source string `json:"source,omitempty"` // Multi-source attribution (Council)
RawData json.RawMessage `json:"raw,omitempty"` // Raw: passthrough unknown events
Meta map[string]any `json:"meta,omitempty"` // Application extensions (seq, cost_usd, duration_ms)
}
Event is the universal streaming event for all deepwork Portals. Exactly one of Content/Tool/DoneInfo/RawData is meaningful per Kind.
func Burst ¶
Burst converts a complete (non-streaming) response into a sequence of events. Useful for WebChat DOM polling, non-streaming API fallback, cached responses.
func RawEvent ¶
func RawEvent(data json.RawMessage) Event
RawEvent creates a passthrough event for unknown provider data.
func StatusEvent ¶
StatusEvent creates a non-content progress event.
func ThinkingEvent ¶
ThinkingEvent creates a thinking/reasoning delta event.
func ToolResultEvent ¶
ToolResultEvent creates a tool execution result event.
func ToolStartEvent ¶
func ToolStartEvent(id, name string, input json.RawMessage) Event
ToolStartEvent creates a tool call event with complete arguments.
func UsageEvent ¶
UsageEvent creates a token accounting update.
func (Event) WithMeta ¶
WithMeta returns a copy of the event with Meta entries added. Existing Meta entries are preserved; new entries override on collision.
func (Event) WithSource ¶
WithSource returns a copy of the event with Source set. Used by Council to tag which LLM participant produced this event.
type Kind ¶
type Kind string
Kind classifies the semantic content of an LLM streaming event.
const ( // Status is a non-content progress signal for transport/agent lifecycle. Status Kind = "status" // Text is an incremental text content delta (打字机效果). Text Kind = "text" // Thinking is an incremental reasoning/CoT delta. // Maps to: OpenAI reasoning, Anthropic thinking_delta, DeepSeek/GLM reasoning_content. Thinking Kind = "thinking" // ToolStart signals a complete tool call (provider buffers incremental args internally). ToolStart Kind = "tool_start" // ToolResult signals a tool execution result. ToolResult Kind = "tool_result" // Usage reports token counters while a stream is still running or after a // provider emits cumulative accounting outside the final done frame. Usage Kind = "usage" // Done signals stream completion with usage/cost/reason. Done Kind = "done" // Error signals a recoverable error (stream may continue). Error Kind = "error" // Raw is an escape hatch for unknown/new event types from providers. Raw Kind = "raw" )
type ToolData ¶
type ToolData struct {
ID string `json:"id"`
Name string `json:"name"`
Input json.RawMessage `json:"input,omitempty"` // ToolStart: complete arguments JSON
Output string `json:"output,omitempty"` // ToolResult: execution output
IsError bool `json:"is_error,omitempty"` // ToolResult: tool failed
DurationMs int `json:"duration_ms,omitempty"` // ToolResult: execution time
}
ToolData holds tool call or tool result information.
type UsageData ¶
type UsageData struct {
InputTokens int `json:"input_tokens,omitempty"`
ThinkingTokens int `json:"thinking_tokens,omitempty"`
OutputTokens int `json:"output_tokens,omitempty"`
CacheReadInputTokens int `json:"cache_read_input_tokens,omitempty"`
CacheCreationInputTokens int `json:"cache_creation_input_tokens,omitempty"`
TotalTokens int `json:"total_tokens,omitempty"`
Estimated bool `json:"estimated,omitempty"`
}
UsageData holds provider token accounting. Providers may emit this incrementally, cumulatively, or only at completion.
Source Files