live

type Auth struct {
	AccessToken string
	AccountID   string
	// Headers carries the shared client identity (originator, User-Agent).
	Headers map[string]string
}

type AuthFunc func(ctx context.Context, refresh bool) (Auth, error)

type CallRequest struct {
	SDP     string          `json:"sdp"`
	Session json.RawMessage `json:"session"`
}

type CallResponse struct {
	AnswerSDP string
	CallID    string
}

type Capabilities struct {
	Provider    string   `json:"provider"`
	Model       string   `json:"model"`
	Voice       string   `json:"voice"`
	Voices      []string `json:"voices"`
	CanSetVoice bool     `json:"can_set_voice"`
}

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

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

type ControllerOptions struct {
	Session   Session
	Delegator Delegator
	// Observer receives host-visible updates. It must not block for long.
	Observer func(Update)
	// FlushInterval batches streamed agent text before it is appended.
	FlushInterval time.Duration
	// BusyRetry is the delay between retries when the chat session is busy.
	BusyRetry time.Duration
	// BusyRetries caps how many times a delegation waits for a busy session.
	BusyRetries int
}

type DelegationChunk struct {
	Text    string
	Channel string
}

type DelegationCompletionSession interface {
	CompleteDelegation(ctx context.Context, delegationID string) error
}

type DelegationRequest struct {
	// ID is the provider's stable delegation identifier when one was supplied.
	ID              string
	Input           string
	TranscriptDelta string
}

type DelegationState string

type Delegator interface {
	Run(ctx context.Context, request DelegationRequest, emit func(DelegationChunk)) error
}

type Event struct {
	Kind EventKind
	// RawType preserves the wire type, mainly for Unknown events.
	RawType string
	Role    string
	Text    string
	// Voice is the acknowledged output voice for EventSessionUpdated.
	Voice string
	// ErrorHandled means an operation caller already received this error. Keep
	// it on the event stream without also failing the conversational UI.
	ErrorHandled bool
	// DelegationID identifies the delegation item for EventDelegationCreated.
	DelegationID string
}

type EventKind string

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

type InitialItem struct {
	Role string
	Text string
}

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

type Outbound struct {
	Type             string          `json:"type"`
	DelegationItemID string          `json:"delegation_item_id,omitempty"`
	Channel          string          `json:"channel,omitempty"`
	Content          []wireContent   `json:"content,omitempty"`
	Session          json.RawMessage `json:"session,omitempty"`
}

type PCMFrame struct {
	Audio []byte
	Flush bool
}

type PCMSession interface {
	Session
	SendPCM(ctx context.Context, pcm []byte) error
	PCMFrames() <-chan PCMFrame
}

type Provider interface {
	// Name reports the configured provider name.
	Name() string
	// Ready reports whether a session could be started right now.
	Ready(ctx context.Context) error
	// Start exchanges the caller's SDP offer for a provider answer and opens
	// the control channel.
	Start(ctx context.Context, offerSDP string, opts SessionOptions) (Session, error)
}

type Session interface {
	// AnswerSDP returns the provider's SDP answer for the media peer.
	AnswerSDP() string
	// Events streams normalised provider events until the session ends.
	Events() <-chan Event
	// AppendDelegation streams delegated-turn output back to the voice model.
	AppendDelegation(ctx context.Context, delegationID string, chunk DelegationChunk) error
	// AppendText injects text into the conversation outside a delegation.
	AppendText(ctx context.Context, text string) error
	// Close ends the session.
	Close(ctx context.Context) error
}

type SessionOptions struct {
	// SessionID is the chat session the live call is bound to. It is sent as
	// x-session-id so provider-side logs line up with ours.
	SessionID string
	// Instructions replaces the default voice-model prompt when set.
	Instructions string
	// Context is authoritative host context appended to either the default or
	// custom instructions. It is kept separate so a custom prompt cannot erase
	// the current session capabilities supplied by the host.
	Context string
	// InitialItems seeds the voice model with prior conversation.
	InitialItems []InitialItem
	// Debug enables metadata-only live transport diagnostics. DebugRaw adds
	// sanitized inbound provider events and may include transcript text.
	Debug    bool
	DebugRaw bool
	// LiveID correlates provider diagnostics with host/browser media reports.
	LiveID string
}

type SteeringDelegator interface {
	Steer(ctx context.Context, request DelegationRequest) (bool, error)
}

type Update struct {
	Kind         UpdateKind
	Role         string
	Text         string
	Final        bool
	Interim      bool // replaceable UI-only recognition preview, not transcript history
	DelegationID string
	State        DelegationState
}

type UpdateKind string

type VoiceSession interface {
	// CurrentVoice returns the most recently acknowledged voice, including late
	// acknowledgements after a canceled SetVoice request.
	CurrentVoice() string
	SetVoice(ctx context.Context, voice string) error
}