streaming

Documentation

Overview

Package streaming holds protocol-agnostic conversation and stream types shared by inference, the agent harness, and server protocols (ACP, SSE, and future A2A).

Layering:

• inference: provider wire (e.g. OpenAI SSE) → LLMResponseChunk
• harness: agent loop → StreamEvent (tools, interrupts, complete, cancel)
• server.Protocol: StreamEvent → client wire (ACP session/update, SSE, A2A, …)

This package does not parse provider SSE and does not encode client protocols. Client presentation belongs on server.Protocol.OnStreamEvent / OnStreamClosed.

Index

• Constants
• func DataURL(mime, data string) string
• func IsTextMIME(mime string) bool
• func MIMEFromDataURL(u string) string
• func NormalizeMIME(mime string) string
• type Annotation
• type ContentPart
• type FileData
• type ImageURL
• type ItemStatus
• type LLMResponseChunk
• type Message
  • func (m *Message) MIMETypes() []string
• type MessageRole
• type StreamEvent
• type StreamEventType
• type Todo
• type TodoStatus
• type ToolCall
  • func (tc ToolCall) Key() string
  • func (tc ToolCall) WireID() string
• type ToolCategory
• type URLAnnotation

Constants

const (
	ContentTypeOutputText = "output_text"
	ContentTypeInputText  = "input_text"
	ContentTypeInputImage = "input_image"
	ContentTypeInputFile  = "input_file"
	ContentTypeRefusal    = "refusal"
)

Functions

func DataURL

func DataURL(mime, data string) string

DataURL builds a data:<mime>;base64,<data> URL. data may already be a data URL.

func IsTextMIME

func IsTextMIME(mime string) bool

IsTextMIME is true for empty and text/* types (always model-safe as text).

func MIMEFromDataURL

func MIMEFromDataURL(u string) string

MIMEFromDataURL extracts the MIME type from a data: URL, or empty.

func NormalizeMIME

func NormalizeMIME(mime string) string

NormalizeMIME lowercases a MIME type and strips parameters (after ';').

Types

type Annotation

type Annotation struct {
	Type   string         `json:"type"`
	Text   string         `json:"text,omitempty"`
	FileID string         `json:"file_id,omitempty"`
	URL    *URLAnnotation `json:"url,omitempty"`
}

Annotation attaches file/URL citations to output_text content.

type ContentPart

type ContentPart struct {
	Type        string       `json:"type"`
	Text        string       `json:"text,omitempty"`
	Refusal     string       `json:"refusal,omitempty"`
	ImageURL    *ImageURL    `json:"image_url,omitempty"`
	FileData    *FileData    `json:"file_data,omitempty"`
	Annotations []Annotation `json:"annotations,omitempty"`
}

ContentPart is a single content block within a message. Discriminated by Type — oneOf{output_text, input_text, input_image, input_file, refusal}.

type FileData

type FileData struct {
	FileID   string `json:"file_id,omitempty"`
	URL      string `json:"url,omitempty"`
	Data     string `json:"data,omitempty"`
	MIMEType string `json:"mime_type,omitempty"`
	// Filename is preferred by providers for input_file (e.g. PDF data URLs).
	Filename string `json:"filename,omitempty"`
}

FileData represents an image or file input by ID, URL, or base64 data.

type ImageURL

type ImageURL struct {
	URL    string `json:"url"`
	Detail string `json:"detail,omitempty"`
}

ImageURL represents an image input by URL or data URI.

type ItemStatus

type ItemStatus string

ItemStatus tracks the lifecycle state of an output item.

const (
	StatusInProgress ItemStatus = "in_progress"
	StatusCompleted  ItemStatus = "completed"
	StatusIncomplete ItemStatus = "incomplete"
)

type LLMResponseChunk

type LLMResponseChunk struct {
	TurnId     string
	MessageId  string
	ToolCalls  []ToolCall
	Type       StreamEventType
	Content    string
	IsComplete bool
	// Error is set on terminal provider failures (Type == StreamEventError).
	// Harness copies it onto StreamEvent.Error so protocols can errors.Is
	// stop-reason sentinels (refusal, max_tokens, …).
	Error error

	// Token usage when the provider reports it (typically on StreamEventComplete
	// after response.completed). Zero means unknown / not reported.
	InputTokens     int
	OutputTokens    int
	ReasoningTokens int
}

LLMResponseChunk is the streaming unit emitted by an InferenceStrategy's Invoke call. Provider parse only — not client-facing wire.

type Message

type Message struct {
	Role    MessageRole `json:"role"`
	Content string      `json:"content,omitempty"`

	// MessageID is the provider-assigned identifier for this output item,
	// used when serializing prior assistant or reasoning turns as typed
	// response items.
	MessageID string `json:"message_id,omitempty"`

	ContentParts     []ContentPart `json:"content_parts,omitempty"`
	ToolCalls        []ToolCall    `json:"tool_calls,omitempty"`
	ToolCallID       string        `json:"tool_call_id,omitempty"`
	StructuredOutput any           `json:"-"`
}

Message is the primary conversation unit in the context window. It handles both simple text and structured content, tool calls, tool results, and reasoning content produced by reasoning models. The Role field determines the purpose:

• system/developer: system instructions
• user: user input (Content or ContentParts)
• assistant: model response (Content + optional ToolCalls)
• reasoning: model reasoning content (a distinct previous-response item)
• tool: result of a tool execution (ToolCallID + Content)

func (*Message) MIMETypes

func (m *Message) MIMETypes() []string

MIMETypes returns unique binary MIME types from ContentParts (images/files). Producers set FileData.MIMEType (and image parts via FileData or data URL). Text and refusal parts are ignored. Order is first-seen.

type MessageRole

type MessageRole string

MessageRole indicates who sent the message.

const (
	RoleUser      MessageRole = "user"
	RoleAssistant MessageRole = "assistant"
	RoleReasoning MessageRole = "reasoning"
	RoleSystem    MessageRole = "system"
	RoleDeveloper MessageRole = "developer"
	RoleTool      MessageRole = "tool"
)

type StreamEvent

type StreamEvent struct {
	Type      StreamEventType
	TurnID    string
	MessageID string
	Content   string
	Data      []byte
	ToolCalls []ToolCall
	Error     error
}

StreamEvent is the harness interior event bus. Protocols map these events to wire formats; the harness does not own ACP/SSE/A2A framing.

type StreamEventType

type StreamEventType string

StreamEventType categorizes events sent to the caller.

const (
	StreamEventMessage      StreamEventType = "message"
	StreamEventReasoning    StreamEventType = "reasoning"
	StreamEventFunctionCall StreamEventType = "function_call"
	StreamEventToolResult   StreamEventType = "tool_result"
	StreamEventComplete     StreamEventType = "complete"
	StreamEventError        StreamEventType = "error"
	StreamEventInterrupt    StreamEventType = "yield"
	StreamEventToolUpdate   StreamEventType = "tool_update"
	StreamEventPlanUpdate   StreamEventType = "plan_update"
)

type Todo

type Todo struct {
	Title       string     `json:"title"`
	Status      TodoStatus `json:"status"`
	Description string     `json:"description"`
}

Todo is one item in an agent plan list (create_plan / plan_update stream data).

type TodoStatus

type TodoStatus string

const (
	TodoStatusPending    TodoStatus = "pending"
	TodoStatusCompleted  TodoStatus = "completed"
	TodoStatusInProgress TodoStatus = "in_progress"
)

type ToolCall

type ToolCall struct {
	ID        string       `json:"id,omitempty"`
	Type      string       `json:"type,omitempty"`
	CallID    string       `json:"call_id"`
	Name      string       `json:"name,omitempty"`  // programmatic tool id (model-facing)
	Title     string       `json:"title,omitempty"` // human-readable invocation label for UIs/protocols
	Category  ToolCategory `json:"category,omitempty"`
	Namespace string       `json:"namespace,omitempty"`
	Arguments string       `json:"arguments,omitempty"`
	Status    string       `json:"status,omitempty"`
}

ToolCall represents an assistant request to invoke a tool.

func (ToolCall) Key

func (tc ToolCall) Key() string

Key is the client/lifecycle id: provider item id, else call_id.

func (ToolCall) WireID

func (tc ToolCall) WireID() string

WireID is the Responses API call_id field: CallID, else ID.

type ToolCategory

type ToolCategory string

const (
	ToolCategoryRead    ToolCategory = "read"
	ToolCategoryEdit    ToolCategory = "edit"
	ToolCategorySearch  ToolCategory = "search"
	ToolCategoryFetch   ToolCategory = "fetch"
	ToolCategoryMove    ToolCategory = "move"
	ToolCategoryThink   ToolCategory = "think"
	ToolCategoryExecute ToolCategory = "execute"
	ToolCategoryDelete  ToolCategory = "delete"
)

type URLAnnotation

type URLAnnotation struct {
	URL   string `json:"url"`
	Title string `json:"title"`
}

URLAnnotation references a specific URL as a citation source.