v1

type AssistantTextDelta struct {
	// Kind is "assistant.text.delta".
	Kind MessageKind `json:"kind"`
	// Text is an incremental assistant text fragment.
	Text string `json:"text"`
}

type Context struct {
	// SystemInstruction is provider-neutral instruction text for the assistant.
	SystemInstruction string `json:"systemInstruction,omitempty"`
	// Text is additional conversational context for the session.
	Text string `json:"text,omitempty"`
}

type ContextUpdate struct {
	// Kind must be "context.update".
	Kind MessageKind `json:"kind"`
	// Context contains the instructions or text to append.
	Context Context `json:"context"`
}

type Error struct {
	// Kind is "error".
	Kind MessageKind `json:"kind"`
	// Message is a human-readable error description.
	Message string `json:"message"`
	// Recoverable reports whether the client may continue using the session.
	Recoverable bool `json:"recoverable"`
}

type InterruptSource string

type Interrupted struct {
	// Kind is "interrupted".
	Kind MessageKind `json:"kind"`
	// Source identifies what interrupted the turn.
	Source InterruptSource `json:"source"`
	// Message optionally provides more detail about the interruption.
	Message string `json:"message,omitempty"`
}

type MessageEnvelope struct {
	// Kind is the message discriminator used to decode the concrete message type.
	Kind MessageKind `json:"kind"`
}

type MessageKind string

type Route struct {
	Name        string       // Function name, e.g. "voiceRTCOffer"
	Doc         string       // One-line description for SDK comments and docs.
	Method      string       // HTTP method, e.g. "GET" or "POST"
	Path        string       // "/api/voicegateway/v1/voice/rtc/offer"
	Req         reflect.Type // Request body type; nil for no body.
	Resp        reflect.Type // Response body type.
	IsArray     bool         // response is T[] not T
	IsSSE       bool         // SSE stream, not JSON
	QueryParams []string     // Query parameter names (GET endpoints only).
}

type ServiceAuthorization struct {
	Kind       string `json:"kind"`
	InstanceID string `json:"instanceID"`
	BaseURL    string `json:"baseURL"`
	Token      string `json:"token"`
}

type SessionClose struct {
	// Kind must be "session.close".
	Kind MessageKind `json:"kind"`
	// Reason optionally explains why the client closed the session.
	Reason string `json:"reason,omitempty"`
}

type SessionReady struct {
	// Kind is "session.ready".
	Kind MessageKind `json:"kind"`
}

type SessionSetup struct {
	// Kind must be "session.setup".
	Kind MessageKind `json:"kind"`
	// Voice contains the requested voice and language.
	Voice VoiceConfig `json:"voice"`
	// Tools declares the client-side tools the assistant may call.
	Tools []ToolDeclaration `json:"tools"`
	// Context provides initial instructions or text context for the session.
	Context Context `json:"context"`
}

type Speaker string

type SpeechEnded struct {
	// Kind is "speech.ended".
	Kind MessageKind `json:"kind"`
	// Speaker identifies whose speech output ended.
	Speaker Speaker `json:"speaker"`
}

type SpeechStarted struct {
	// Kind is "speech.started".
	Kind MessageKind `json:"kind"`
	// Speaker identifies whose speech output started.
	Speaker Speaker `json:"speaker"`
}

type StatusResp struct {
	// Status is a short human-readable result such as "closed".
	Status string `json:"status"`
}

type ToolCall struct {
	// Kind is "tool.call".
	Kind MessageKind `json:"kind"`
	// ID uniquely identifies this tool call for the matching tool.result.
	ID string `json:"id"`
	// Name is the requested tool name.
	Name string `json:"name"`
	// Args is the JSON argument object for the requested tool.
	Args json.RawMessage `json:"args"`
}

type ToolDeclaration struct {
	// Name is the tool name the assistant uses in tool.call messages.
	Name string `json:"name"`
	// Description explains when and how the assistant should use the tool.
	Description string `json:"description"`
	// Parameters is a JSON Schema object describing the tool arguments.
	Parameters json.RawMessage `json:"parameters"`
}

type ToolResult struct {
	// Kind must be "tool.result".
	Kind MessageKind `json:"kind"`
	// ID matches the tool.call ID being answered.
	ID string `json:"id"`
	// Name is the tool name that produced the result.
	Name string `json:"name"`
	// Result is the JSON result returned to the assistant.
	Result json.RawMessage `json:"result"`
}

type TranscriptDelta struct {
	// Kind is "transcript.delta".
	Kind MessageKind `json:"kind"`
	// Speaker identifies who produced this transcript text.
	Speaker Speaker `json:"speaker"`
	// Text is an incremental transcript fragment.
	Text string `json:"text"`
}

type TurnCancel struct {
	// Kind must be "turn.cancel".
	Kind MessageKind `json:"kind"`
	// Reason optionally explains why the current assistant turn was cancelled.
	Reason string `json:"reason,omitempty"`
}

type UserMessage struct {
	// Kind must be "user.message".
	Kind MessageKind `json:"kind"`
	// Text is the completed user utterance to send to the assistant.
	Text string `json:"text"`
}

type VoiceConfig struct {
	// Name is the requested provider-specific voice name.
	Name string `json:"name"`
	// Language is the requested BCP 47 language tag, such as "en" or "fr-CA".
	Language string `json:"language"`
}

type VoiceRTCAnswerResp struct {
	// SDP is the gateway WebRTC answer session description to pass to setRemoteDescription with type "answer".
	SDP string `json:"sdp"`
	// SessionID identifies the voice RTC session for diagnostics and close calls.
	SessionID string `json:"sessionID"`
}

type VoiceRTCClientDiagnostics struct {
	// ICEConnectionState is the client's RTCPeerConnection.iceConnectionState.
	ICEConnectionState VoiceRTCICEConnectionState `json:"iceConnectionState,omitempty"`
	// ICEGatheringState is the client's RTCPeerConnection.iceGatheringState.
	ICEGatheringState VoiceRTCICEGatheringState `json:"iceGatheringState,omitempty"`
	// ConnectionState is the client's RTCPeerConnection.connectionState.
	ConnectionState VoiceRTCConnectionState `json:"connectionState,omitempty"`
	// SignalingState is the client's RTCPeerConnection.signalingState.
	SignalingState VoiceRTCSignalingState `json:"signalingState,omitempty"`
	// DataChannelState is the client's voice-gateway RTCDataChannel.readyState.
	DataChannelState VoiceRTCDataChannelState `json:"dataChannelState,omitempty"`
}

type VoiceRTCConnectionState string

type VoiceRTCConnectivityIssue string

type VoiceRTCConnectivitySide string

type VoiceRTCDataChannelState string

type VoiceRTCDiagnosticsReq struct {
	// Client contains the browser/client WebRTC state observed by the caller.
	Client VoiceRTCClientDiagnostics `json:"client,omitzero"`
}

type VoiceRTCDiagnosticsResp struct {
	// SessionID is the diagnosed voice RTC session ID.
	SessionID string `json:"sessionID"`
	// Issue is the machine-readable connectivity diagnosis.
	Issue VoiceRTCConnectivityIssue `json:"issue"`
	// Side identifies where the issue appears to be.
	Side VoiceRTCConnectivitySide `json:"side"`
	// Message is a human-readable explanation of the diagnosis.
	Message string `json:"message"`
	// Server contains gateway-observed WebRTC state.
	Server VoiceRTCServerDiagnostics `json:"server"`
	// Client echoes the client diagnostics included in the request.
	Client VoiceRTCClientDiagnostics `json:"client,omitzero"`
}

type VoiceRTCICEConnectionState string

type VoiceRTCICEGatheringState string

type VoiceRTCOfferReq struct {
	// SDP is the browser/client WebRTC offer session description from RTCSessionDescription.sdp after createOffer and setLocalDescription.
	SDP string `json:"sdp"`
	// Service authorizes a session on a standalone gateway. Embedded gateways use host authentication.
	Service *ServiceAuthorization `json:"service,omitempty"`
}

type VoiceRTCServerDiagnostics struct {
	// SessionFound reports whether the gateway still has the requested session.
	SessionFound bool `json:"sessionFound"`
	// UDPEndpoints are the LAN/Tailscale and optional UPnP public UDP candidates advertised to the client.
	UDPEndpoints []VoiceRTCUDPEndpoint `json:"udpEndpoints,omitempty"`
	// UDPMappingError is the last UPnP mapping or refresh error, if any.
	UDPMappingError string `json:"udpMappingError,omitempty"`
	// ICEConnectionState is the gateway PeerConnection ICE connection state.
	ICEConnectionState VoiceRTCICEConnectionState `json:"iceConnectionState,omitempty"`
	// ICEGatheringState is the gateway PeerConnection ICE gathering state.
	ICEGatheringState VoiceRTCICEGatheringState `json:"iceGatheringState,omitempty"`
	// ConnectionState is the gateway PeerConnection aggregate connection state.
	ConnectionState VoiceRTCConnectionState `json:"connectionState,omitempty"`
	// SignalingState is the gateway PeerConnection signaling state.
	SignalingState VoiceRTCSignalingState `json:"signalingState,omitempty"`
	// DataChannelState is the gateway-observed voice data channel state.
	DataChannelState VoiceRTCDataChannelState `json:"dataChannelState,omitempty"`
	// DataChannelOpened reports whether the voice data channel reached open.
	DataChannelOpened bool `json:"dataChannelOpened,omitempty"`
	// AudioTrackReceived reports whether the gateway received the client's microphone track.
	AudioTrackReceived bool `json:"audioTrackReceived,omitempty"`
	// BackendConnected reports whether the gateway connected to the configured voice backend.
	BackendConnected bool `json:"backendConnected,omitempty"`
	// SessionReadySent reports whether the gateway sent session.ready to the client.
	SessionReadySent bool `json:"sessionReadySent,omitempty"`
	// LastError is the last gateway error sent to the client, if any.
	LastError string `json:"lastError,omitempty"`
}

type VoiceRTCSignalingState string

type VoiceRTCUDPEndpoint struct {
	// Host is an IP address advertised in the gateway SDP answer.
	Host string `json:"host"`
	// Port is the UDP port paired with host in the gateway SDP answer.
	Port int `json:"port"`
}