stream

type AssistantReply struct {
	Base
	// Data contains the assistant reply payload. Clients should concatenate
	// Data.Text from sequential AssistantReply events to reconstruct the
	// full message.
	Data AssistantReplyPayload
}

type AssistantReplyPayload struct {
	Text string `json:"text"`
}

type AwaitClarification struct {
	Base
	Data AwaitClarificationPayload
}

type AwaitClarificationPayload struct {
	ID             string         `json:"id"`
	Question       string         `json:"question"`
	MissingFields  []string       `json:"missing_fields,omitempty"`
	RestrictToTool string         `json:"restrict_to_tool,omitempty"`
	ExampleInput   map[string]any `json:"example_input,omitempty"`
}

type AwaitConfirmation struct {
	Base
	Data AwaitConfirmationPayload
}

type AwaitConfirmationPayload struct {
	// ID correlates this await with a subsequent confirmation decision.
	ID string `json:"id"`
	// Title is an optional display title for the confirmation UI.
	Title string `json:"title,omitempty"`
	// Prompt is the operator-facing confirmation prompt.
	Prompt string `json:"prompt"`
	// ToolName identifies the tool that requires confirmation.
	ToolName string `json:"tool_name"`
	// ToolCallID is the tool_call_id for the pending tool call.
	ToolCallID string `json:"tool_call_id"`
	// Payload contains the canonical JSON arguments for the pending tool call.
	Payload rawjson.Message `json:"payload,omitempty"`
}

type AwaitExternalTools struct {
	Base
	Data AwaitExternalToolsPayload
}

type AwaitExternalToolsPayload struct {
	// ID correlates this await with a subsequent provide_tool_results
	// call from the orchestrator or UI.
	ID string `json:"id"`
	// Items enumerates the external tool calls that must be satisfied
	// before the run can resume.
	Items []AwaitToolPayload `json:"items"`
}

type AwaitQuestionOptionPayload struct {
	ID    string `json:"id"`
	Label string `json:"label"`
}

type AwaitQuestionPayload struct {
	ID            string                       `json:"id"`
	Prompt        string                       `json:"prompt"`
	Options       []AwaitQuestionOptionPayload `json:"options"`
	AllowMultiple bool                         `json:"allow_multiple,omitempty"`
}

type AwaitQuestions struct {
	Base
	Data AwaitQuestionsPayload
}

type AwaitQuestionsPayload struct {
	// ID correlates this await with a subsequent provide_tool_results call.
	ID string `json:"id"`
	// ToolName identifies the tool awaiting user answers.
	ToolName string `json:"tool_name"`
	// ToolCallID correlates the provided result with this requested call.
	ToolCallID string `json:"tool_call_id"`
	// Title is an optional display title for the questions UI.
	Title *string `json:"title,omitempty"`
	// Questions are the structured questions to present to the user.
	Questions []AwaitQuestionPayload `json:"questions"`
}

type AwaitToolPayload struct {
	// ToolName is the fully qualified identifier of the external tool
	// that must be executed (for example, "svc.read.get_time_series").
	ToolName string `json:"tool_name"`
	// ToolCallID optionally carries a caller-assigned identifier used
	// to correlate the provided result with this request.
	ToolCallID string `json:"tool_call_id,omitempty"`
	// Payload contains the JSON-serializable arguments for the external
	// tool. It may be omitted when the tool takes no parameters.
	Payload rawjson.Message `json:"payload,omitempty"`
}

type Base struct {
	// contains filtered or unexported fields
}

type ChildRunLinked struct {
	Base
	Data ChildRunLinkedPayload
}

type ChildRunLinkedPayload struct {
	// ToolName is the fully qualified identifier of the parent tool
	// that launched the child agent run.
	ToolName string `json:"tool_name"`
	// ToolCallID identifies the parent tool call associated with the
	// child run. UIs use this to attach child run links to tool cards.
	ToolCallID string `json:"tool_call_id"`
	// ChildRunID is the workflow execution identifier of the nested
	// agent run.
	ChildRunID string `json:"child_run_id"`
	// ChildAgentID is the identifier of the agent that executed the
	// child run.
	ChildAgentID agent.Ident `json:"child_agent_id"`
}

type Event interface {
	// Type returns the event type constant (e.g., EventToolEnd, EventAssistantReply).
	// Subscribers use this to filter events by category or route to type-specific
	// handlers without performing type assertions. For example, a UI might subscribe
	// only to EventAssistantReply and EventToolEnd to display final outputs while
	// ignoring planner thoughts.
	Type() EventType

	// RunID returns the unique workflow run identifier that produced this event. All
	// events within a single run execution share the same run ID, enabling clients to
	// filter or group events by run. This is critical for multi-account systems where
	// a single Sink may multiplex events from multiple concurrent runs.
	RunID() string

	// SessionID returns the logical session identifier associated with the run.
	// All events for a given run share the same session ID, providing a stable
	// join key across processes and transports.
	SessionID() string

	// EventKey returns the stable logical identity of the originating hook event
	// when the stream event was derived from one. Empty means the producer did not
	// attach a durable identity.
	EventKey() string

	// Payload returns the event-specific data in a JSON-serializable form. Sinks use
	// this for generic marshaling when they don't need typed access. For example, the
	// Pulse sink calls Payload() and marshals the result to JSON without knowing the
	// concrete event type.
	//
	// Consumers that need structured access to event fields (e.g., SSE adapters mapping
	// to Goa transport types) should use type assertions on the Event itself to access
	// fields like ToolStart.Data or AssistantReply.Text directly. Use Payload() for
	// generic serialization; use type assertions for type-safe field access.
	Payload() any
}

type EventType string

type PlannerThought struct {
	Base
	// Data contains the planner thought payload (e.g., "Analyzing user query...",
	// "Calling weather API to get forecast..."). This is human-readable text
	// suitable for displaying in a UI thought bubble or debug panel.
	Data PlannerThoughtPayload
}

type PlannerThoughtPayload struct {
	Note         string `json:"note,omitempty"`
	Text         string `json:"text,omitempty"`
	Signature    string `json:"signature,omitempty"`
	Redacted     []byte `json:"redacted,omitempty"`
	ContentIndex int    `json:"content_index,omitempty"`
	Final        bool   `json:"final,omitempty"`
}

type PromptRendered struct {
	Base
	Data PromptRenderedPayload
}

type PromptRenderedPayload struct {
	PromptID string       `json:"prompt_id"`
	Version  string       `json:"version"`
	Scope    prompt.Scope `json:"scope"`
}

type RunLinkPayload struct {
	// RunID is the workflow execution identifier of the child run.
	RunID string `json:"run_id"`
	// AgentID is the identifier of the child agent that executed
	// the nested run.
	AgentID agent.Ident `json:"agent_id"`
	// ParentRunID is the run identifier of the parent workflow
	// that launched this child run. It may be empty when the
	// child has no recorded parent.
	ParentRunID string `json:"parent_run_id,omitempty"`
	// ParentToolCallID is the tool call identifier on the parent
	// run that triggered this child run. It may be empty when the
	// linkage is not available.
	ParentToolCallID string `json:"parent_tool_call_id,omitempty"`
}

type RunStreamEnd struct {
	Base
	Data RunStreamEndPayload
}

type RunStreamEndPayload struct{}

type SessionStreamEnd struct {
	Base
	Data SessionStreamEndPayload
}

type SessionStreamEndPayload struct{}

type SessionStreamStarted struct {
	Base
	Data SessionStreamStartedPayload
}

type SessionStreamStartedPayload struct{}

type Sink interface {
	// Send publishes an event to the sink's underlying transport. The implementation
	// is responsible for marshaling the event into the wire format and handling
	// transport-specific delivery semantics (retry, buffering, backpressure).
	//
	// Send should return an error if delivery fails (connection closed, serialization
	// error, transport unavailable). The runtime propagates Send errors to the hook
	// bus, which stops event delivery to remaining subscribers, ensuring streaming
	// failures surface immediately rather than silently dropping events.
	//
	// Thread-safe: safe to call concurrently from multiple goroutines.
	Send(ctx context.Context, event Event) error

	// Close releases resources owned by the sink (connections, buffers, background
	// goroutines). After Close returns, subsequent Send calls must return errors.
	//
	// Close is idempotent: calling it multiple times is safe and has no effect after
	// the first call. Implementations should block until all pending events are
	// flushed or ctx is canceled.
	//
	// The context controls the maximum time allowed for graceful shutdown. If ctx
	// expires before shutdown completes, implementations should abort immediately,
	// potentially dropping unflushed events.
	Close(ctx context.Context) error
}

type StreamProfile struct {
	// Assistant controls assistant reply emission.
	Assistant bool
	// Thoughts controls planner thought / thinking emission.
	Thoughts bool
	// PromptRendered controls emission of prompt_rendered events.
	PromptRendered bool
	// ToolStart controls emission of tool_start events.
	ToolStart bool
	// ToolUpdate controls emission of tool_update events.
	ToolUpdate bool
	// ToolCallArgsDelta controls emission of tool_call_args_delta events.
	ToolCallArgsDelta bool
	// ToolEnd controls emission of tool_end events.
	ToolEnd bool
	// AwaitClarification controls emission of await_clarification events.
	AwaitClarification bool
	// AwaitConfirmation controls emission of await_confirmation events.
	AwaitConfirmation bool
	// AwaitQuestions controls emission of await_questions events.
	AwaitQuestions bool
	// AwaitExternalTools controls emission of await_external_tools events.
	AwaitExternalTools bool
	// ToolAuthorization controls emission of tool_authorization events.
	ToolAuthorization bool
	// Usage controls emission of usage events.
	Usage bool
	// Workflow controls emission of workflow lifecycle events.
	Workflow bool
	// ChildRuns controls emission of child_run_linked events.
	ChildRuns bool
}

type Subscriber struct {
	// contains filtered or unexported fields
}

type ToolAuthorization struct {
	Base
	Data ToolAuthorizationPayload
}

type ToolAuthorizationPayload struct {
	// ToolName identifies the tool that was authorized.
	ToolName string `json:"tool_name"`
	// ToolCallID is the tool_call_id for the pending tool call.
	ToolCallID string `json:"tool_call_id"`
	// Approved reports whether the operator approved execution.
	Approved bool `json:"approved"`
	// Summary is a deterministic, human-facing description of what was approved.
	Summary string `json:"summary"`
	// ApprovedBy identifies the actor that provided the decision, formatted as
	// "<principal_type>:<principal_id>".
	ApprovedBy string `json:"approved_by"`
}

type ToolCallArgsDelta struct {
	Base
	Data ToolCallArgsDeltaPayload
}

type ToolCallArgsDeltaPayload struct {
	// ToolCallID identifies the tool call being streamed.
	ToolCallID string `json:"tool_call_id"`
	// ToolName is the canonical tool identifier for this delta stream.
	ToolName string `json:"tool_name"`
	// Delta is the raw tool input JSON fragment emitted by the provider.
	Delta string `json:"delta"`
}

type ToolEnd struct {
	Base
	// ServerData carries server-only metadata emitted alongside the tool result.
	// It is not part of ToolEndPayload and is never serialized into the event
	// payload. Sinks that support server-only sidecars (for example Pulse)
	// may forward it out-of-band for UIs and persistence layers.
	ServerData rawjson.Message `json:"-"`
	// Data contains the structured result metadata for this tool completion. Clients
	// access this field directly for type-safe field access (e.g., event.Data.Duration,
	// event.Data.ToolCallID).
	Data ToolEndPayload
}

type ToolEndPayload struct {
	// ToolCallID uniquely identifies the tool invocation that completed. Clients use this
	// to correlate with the original ToolStart event, enabling UIs to match completion
	// events with their corresponding progress indicators and display results in the
	// correct context.
	ToolCallID string `json:"tool_call_id"`
	// ParentToolCallID identifies the parent tool that requested this tool, if any.
	// Empty for top-level planner-requested tools. Matches the ParentToolCallID from
	// the corresponding ToolStart event. Clients use this to maintain tool call hierarchies
	// and track which parent-child relationships have completed.
	ParentToolCallID string `json:"parent_tool_call_id,omitempty"`
	// ToolName is the fully qualified tool identifier that was executed (e.g.,
	// "weather.search.forecast"). Matches the ToolName from ToolStart. Useful for
	// displaying tool names in result summaries and correlating with tool metadata.
	ToolName string `json:"tool_name"`
	// Result contains the tool's output payload. This is the structured data
	// returned by the tool on success. It is the canonical JSON encoding
	// produced by the tool result codec. Nil when the tool failed.
	Result rawjson.Message `json:"result,omitempty"`
	// ResultPreview is a concise, user-facing summary of the tool result rendered from
	// DSL-authored templates when available. It is intended for UI ribbons and summaries
	// (for example, "Device list ready" or "Found 3 critical alarms").
	ResultPreview string `json:"result_preview,omitempty"`
	// Bounds, when non-nil, describes how the tool result has been bounded
	// relative to the full underlying data set (for example, list/window/
	// graph caps). It is supplied by tool implementations and surfaced for
	// observability; the runtime does not modify it.
	Bounds *agent.Bounds `json:"bounds,omitempty"`
	// Duration is the wall-clock execution time for the tool activity, including any
	// queuing delay, retries, and processing time. Clients can display this in
	// performance dashboards or debug panels to identify slow tools.
	Duration time.Duration `json:"duration"`
	// Telemetry holds structured observability metadata collected during tool execution:
	// token counts, model identifiers, retry attempts, and provider-specific metrics.
	// Nil if no telemetry was collected. Clients use this for cost tracking, performance
	// monitoring, and compliance reporting.
	Telemetry *telemetry.ToolTelemetry `json:"telemetry,omitempty"`
	// RetryHint carries structured guidance for recovering from tool failures.
	// When present, clients can ask the user a clarifying question and retry
	// the tool call deterministically.
	RetryHint *planner.RetryHint `json:"retry_hint,omitempty"`
	// Error contains any error returned by the tool execution. Nil on success. When
	// non-nil, Result is nil and this field contains structured error details (code,
	// message, retryability). Clients display error messages and may implement retry UIs.
	Error *toolerrors.ToolError `json:"error,omitempty"`
	// Extra carries optional extension data for clients that need to attach
	// transport- or domain-specific fields without breaking the wire contract.
	// The runtime ignores its contents; sinks may include it when present.
	Extra map[string]any `json:"extra,omitempty"`
}

type ToolOutputDelta struct {
	Base
	Data ToolOutputDeltaPayload
}

type ToolOutputDeltaPayload struct {
	// ToolCallID identifies the tool call producing the output.
	ToolCallID string `json:"tool_call_id"`
	// ParentToolCallID optionally identifies the parent tool call when the tool
	// was invoked as part of an agent-as-tool run.
	ParentToolCallID string `json:"parent_tool_call_id,omitempty"`
	// ToolName is the canonical tool identifier for this delta stream.
	ToolName string `json:"tool_name"`
	// Stream identifies which logical output channel produced the delta
	// (for example, "stdout", "stderr", "log", "progress").
	Stream string `json:"stream"`
	// Delta is the raw output fragment emitted by the tool.
	Delta string `json:"delta"`
}

type ToolStart struct {
	Base
	// Data contains the structured metadata for this tool invocation. Clients access
	// this field directly for type-safe field access (e.g., event.Data.ToolCallID).
	Data ToolStartPayload
}

type ToolStartPayload struct {
	// ToolCallID uniquely identifies this tool invocation. Clients use this to
	// correlate subsequent ToolEnd events with the original ToolStart, enabling
	// UIs to update progress indicators and display results for the correct tool call.
	ToolCallID string `json:"tool_call_id"`
	// ToolName is the fully qualified tool identifier (e.g., "weather.search.forecast").
	// Format: <service>.<toolset>.<tool>. Clients can use this to display tool names
	// or icons in progress indicators.
	ToolName string `json:"tool_name"`
	// Payload contains the structured tool arguments (JSON-serializable) for this call.
	// It is the canonical tool payload JSON produced by the tool payload codec.
	// It is never decoded into Go structs for streaming to avoid schema drift
	// from untagged Go fields.
	Payload rawjson.Message `json:"payload,omitempty"`
	// DisplayHint is a human-facing one-line description of the in-flight tool work,
	// rendered from DSL-authored templates when available. Suitable for progress lanes
	// and tool ribbons (for example, "Listing devices of kind VAV").
	DisplayHint string `json:"display_hint,omitempty"`
	// Queue is the activity queue name where the tool execution is scheduled. Empty for
	// in-process tools. Clients typically don't display this but may use it for routing
	// or infrastructure-level monitoring.
	Queue string `json:"queue,omitempty"`
	// ParentToolCallID identifies the parent tool that requested this tool, if any.
	// Empty for top-level planner-requested tools. Non-empty when an agent-as-tool
	// schedules child tools. Clients use this to render tool call hierarchies and
	// track parent-child relationships.
	ParentToolCallID string `json:"parent_tool_call_id,omitempty"`
	// ExpectedChildrenTotal indicates how many child tools are expected from this
	// tool's execution batch. Zero means no children are expected or the count is
	// not yet known. Clients use this to display progress like "3 of 5 child tools complete".
	ExpectedChildrenTotal int `json:"expected_children_total,omitempty"`
	// Extra carries optional extension data for clients that need to attach
	// transport- or domain-specific fields without breaking the wire contract.
	// The runtime ignores its contents; sinks may include it when present.
	Extra map[string]any `json:"extra,omitempty"`
}

type ToolUpdate struct {
	Base
	Data ToolUpdatePayload
}

type ToolUpdatePayload struct {
	// ToolCallID identifies the (parent) tool call being updated.
	ToolCallID string `json:"tool_call_id"`
	// ExpectedChildrenTotal is the new total of expected child tools.
	ExpectedChildrenTotal int `json:"expected_children_total"`
}

type Usage struct {
	Base
	Data UsagePayload
}

type UsagePayload struct {
	// TokenUsage contains the attributed token counts reported by the model
	// adapter. Model and ModelClass identify the specific model that produced
	// this delta.
	model.TokenUsage
}

type Workflow struct {
	Base
	Data WorkflowPayload
}

type WorkflowPayload struct {
	// Name is an optional human-readable workflow name.
	Name string `json:"name,omitempty"`
	// Phase is the lifecycle phase, e.g., "completed", "failed", "canceled".
	Phase string `json:"phase"`
	// Status is the coarse-grained terminal status when known
	// (typically "success", "failed", or "canceled"). It is populated
	// on terminal updates derived from RunCompletedEvent and may be
	// empty for non-terminal phase transitions.
	Status string `json:"status,omitempty"`
	// Error is a user-safe error message intended to be displayed directly
	// to end users. It is populated only on failures and is empty on success
	// and cancellations.
	Error string `json:"error,omitempty"`
	// DebugError is a raw error string intended for logs and diagnostics. It
	// may contain infrastructure details and should not be rendered in UIs.
	DebugError string `json:"debug_error,omitempty"`
	// ErrorProvider identifies the model provider when the terminal error was
	// caused by a provider failure (for example, "bedrock").
	ErrorProvider string `json:"error_provider,omitempty"`
	// ErrorOperation identifies the provider operation when available.
	ErrorOperation string `json:"error_operation,omitempty"`
	// ErrorKind classifies provider failures into a small set of stable categories.
	ErrorKind string `json:"error_kind,omitempty"`
	// ErrorCode is the provider-specific error code when available.
	ErrorCode string `json:"error_code,omitempty"`
	// HTTPStatus is the provider HTTP status code when available.
	HTTPStatus int `json:"http_status,omitempty"`
	// Retryable reports whether retrying may succeed without changing the request.
	Retryable bool `json:"retryable"`
}