voiceagent

type ActivityDetectionFrame struct {
	Automatic         bool   `json:"automatic"`
	StartSensitivity  string `json:"start_sensitivity,omitempty"`
	EndSensitivity    string `json:"end_sensitivity,omitempty"`
	PrefixPaddingMs   int32  `json:"prefix_padding_ms,omitempty"`
	SilenceDurationMs int32  `json:"silence_duration_ms,omitempty"`
	ActivityHandling  string `json:"activity_handling,omitempty"`
	TurnCoverage      string `json:"turn_coverage,omitempty"`
}

type Adapter struct {
	Session *ManagedSession
	Conn    *websocket.Conn
	// Provider, when set, is used directly (tests pre-inject a fake). In
	// production it is nil and the provider is chosen per session from
	// Providers[StartFrame.Provider || DefaultProvider] after the start frame
	// is read — this is what makes the backend switchable per session.
	Provider        LiveProviderAdapter
	Providers       map[string]ProviderFactory
	DefaultProvider string
	Persona         PersonaResolver
	// MediaBridge starts an optional LiveKit media bridge for sessions that
	// keep this WebSocket as control transport and move audio through LiveKit.
	MediaBridge MediaBridgeFactory
	// IdleTimeout terminates a session whose readPump and writePump have
	// both been silent for the duration. Zero disables the server-side
	// idle watchdog. Defaults to 15 minutes when set by the WS handler.
	IdleTimeout time.Duration
	// MaxDuration terminates a session after this wall-clock duration even
	// when it remains active. Zero disables the hard cap.
	MaxDuration time.Duration
	// ToolRouter, when non-nil, supplies server-executed tools for this
	// session. Tool names it claims (via Definitions) are executed
	// server-side; all other provider tool calls keep the existing client
	// pass-through wire contract.
	ToolRouter SessionToolRouter
	// OnClose runs after both pumps have returned. Typically removes the
	// session from the manager.
	OnClose func()
	// contains filtered or unexported fields
}

type AdvanceStepFrame struct {
	Type   string `json:"type"` // "advance_step"
	StepID string `json:"step_id,omitempty"`
	Reason string `json:"reason,omitempty"`
}

type CascadedAgent = cascaded.Agent

type CascadedConfig = cascaded.Config

type CascadedDeps = cascaded.Deps

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

type CascadedSTT = cascaded.STT

type CascadedTTS = cascaded.TTS

type ErrorFrame struct {
	Type    string `json:"type"` // "error"
	Code    string `json:"code"`
	Message string `json:"message"`
}

type EventFrame struct {
	Type string `json:"type"` // "event"
	EventFrameFields
}

type EventFrameFields struct {
	EventType        string         `json:"event_type,omitempty"`
	EventTypes       []string       `json:"event_types,omitempty"`
	ProviderMetadata map[string]any `json:"provider_metadata,omitempty"`
}

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

type HandlerOptions struct {
	Manager *SessionManager
	// Provider is the single-provider form (back-compat): when Providers is
	// empty this factory becomes the sole, default backend.
	Provider ProviderFactory
	// Providers is the multi-provider form: a name→factory map (e.g.
	// "deepgram", "gemini", "cascaded") that the client selects between
	// per session via StartFrame.Provider. DefaultProvider names the entry
	// used when a session omits an explicit provider.
	Providers           map[string]ProviderFactory
	DefaultProvider     string
	Persona             PersonaResolver
	PublicURL           string
	AllowedOrigins      []string
	TrustedProxyCIDRs   []string
	MaxAllowedClockSkew time.Duration
	// IdleTimeout terminates a session that hasn't seen any activity
	// (client frame OR provider message) within the duration. Zero
	// disables the server-side idle watchdog. Defaults to 15 minutes
	// when zero is passed; pass a negative value to disable explicitly.
	IdleTimeout time.Duration
	// MaxSessionDuration terminates a session after this wall-clock duration
	// even if it remains active. Zero disables the hard cap.
	MaxSessionDuration time.Duration
	Store              store.Store
	LiveKit            *LiveKitTokenIssuer
	MediaBridge        MediaBridgeFactory
	// ReadLimit caps per-frame bytes the upgraded WebSocket will read.
	// Zero or negative falls back to defaultWSReadLimitBytes (64 KiB).
	ReadLimit int64
	// ToolRouter, when non-nil, supplies server-executed tools for each
	// session (voice-agent tool bridge). Nil disables server-side tool
	// execution; all provider tool calls pass through to the client as
	// before.
	ToolRouter SessionToolRouter
}

type Identity = wssession.Identity

type InterruptedFrame struct {
	Type string `json:"type"` // "interrupted"
	EventFrameFields
}

type LiveConfigFrame struct {
	PersonaID string
	RoleID    string
	// Sequence metadata is internal runtime state derived from the
	// persona/role resolver. It lets the WebSocket adapter report and advance
	// workflow steps without coupling to the persona package.
	SequenceID         string
	SequenceCompletion string
	SequenceMaxTurns   int
	StepID             string
	StepIndex          int
	StepCount          int
	StepInstruction    string
	StepExitCriteria   string
	StepMaxTurns       int

	Model string
	// FallbackModel is forwarded to providers that support same-provider
	// fallback (kernel Gemini Live retries the fallback when the primary
	// connect fails). Empty disables the fallback.
	FallbackModel    string
	APIKey           string
	Voice            string
	SystemPrompt     string
	RefinementPrompt string
	Locale           string
	// Raw activity-detection passthrough; adapter translates to the
	// kernel's internal types.
	Automatic         bool
	StartSensitivity  string
	EndSensitivity    string
	PrefixPaddingMs   int32
	SilenceDurationMs int32
	ActivityHandling  string
	TurnCoverage      string
	Speaker           speaker.Options
	// Tools are server-executed tool definitions merged in by the adapter
	// from the SessionToolRouter (tool bridge). Provider bridges that support
	// session tools map these onto the kernel's LiveConfig.Tools; providers
	// without tool support ignore them.
	Tools []ToolDefinitionFrame
}

type LiveInstructionUpdater interface {
	UpdateInstructions(ctx context.Context, cfg LiveConfigFrame) error
}

type LiveKitJoinInfo struct {
	URL                 string `json:"url"`
	Room                string `json:"room"`
	Token               string `json:"token"`
	TokenExpiresAt      string `json:"token_expires_at"`
	ParticipantIdentity string `json:"participant_identity"`
}

type LiveKitMediaBridgeFactory struct {
	Issuer         *LiveKitTokenIssuer
	ConnectTimeout time.Duration
	// contains filtered or unexported fields
}

type LiveKitTokenIssuer struct {
	URL        string
	APIKey     string
	APISecret  string
	TokenTTL   time.Duration
	RoomPrefix string
	Clock      func() time.Time
}

type LiveKitTransportSupport interface {
	SupportsLiveKitTransport() bool
}

type LiveMessage struct {
	EventType              string
	EventTypes             []string
	ProviderMetadata       map[string]any
	Audio                  []byte
	Done                   bool
	OutputTranscript       string
	OutputTranscriptDone   bool
	InputTranscript        string
	InputTranscriptDone    bool
	InputSpeakerLabel      string
	InputPersonID          string
	InputDisplayName       string
	InputSpeakerConfidence float64
	ToolCalls              []ToolCall
	Interrupted            bool
	GoAway                 bool
	SessionResumable       bool
}

type LiveProviderAdapter interface {
	Connect(ctx context.Context, cfg LiveConfigFrame) error
	SendAudio(chunk []byte) error
	SendAudioStreamEnd() error
	SendText(text string) error
	Receive(ctx context.Context) (*LiveMessage, error)
	Close() error
	Name() string
}

type LiveToolResponder interface {
	SendToolResponse(ToolResponseFrame) error
}

type ManagedSession = wssession.ManagedSession

type MediaBridge interface {
	SendAudio([]byte) error
	Close() error
}

type MediaBridgeFactory interface {
	Start(ctx context.Context, req MediaBridgeRequest) (MediaBridge, error)
}

type MediaBridgeRequest struct {
	SessionID string
	Owner     Identity
	Provider  LiveProviderAdapter
}

type Options = wssession.Options

type PersonaResolver interface {
	Resolve(StartFrame) (LiveConfigFrame, error)
}

type PongFrame struct {
	Type string `json:"type"` // "pong"
}

type ProviderFactory interface {
	NewProvider() LiveProviderAdapter
}

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

type SequenceStepFrame struct {
	Type       string `json:"type"` // "sequence_step"
	SequenceID string `json:"sequence_id,omitempty"`
	StepID     string `json:"step_id"`
	StepIndex  int    `json:"step_index,omitempty"`
	Status     string `json:"status"` // "entered" | "completed" | "sequence_completed"
	Reason     string `json:"reason,omitempty"`
}

type SequenceTransition struct {
	Completed         *SequenceStepFrame
	Entered           *SequenceStepFrame
	NextConfig        LiveConfigFrame
	SequenceCompleted bool
}

type SessionEndFrame struct {
	Type string `json:"type"` // "session_end"
	EventFrameFields
	Reason string `json:"reason"` // "idle" | "go_away" | "client" | "error" | "shutdown" | "max_duration"
}

type SessionManager = wssession.SessionManager

type SessionStats = wssession.SessionStats

type SessionToolRouter interface {
	// Definitions returns the tool frames to advertise for this session.
	// Returning nil (e.g. missing bridge credential, manifest fetch failure,
	// timeout) degrades the session to tool-less — never an error to the user.
	Definitions(ctx context.Context, session *ManagedSession, cfg LiveConfigFrame) []ToolDefinitionFrame
	// Execute runs one claimed tool call and returns the tool response
	// payload for the provider. ok=false means the router could not produce
	// any model-facing payload; the adapter then substitutes a structured
	// error response so the model can recover verbally.
	Execute(ctx context.Context, session *ManagedSession, call ToolCall) (map[string]any, bool)
}

type StartFrame struct {
	Type       string `json:"type"` // must be "start"
	PersonaID  string `json:"persona_id,omitempty"`
	RoleID     string `json:"role_id,omitempty"`
	SequenceID string `json:"sequence_id,omitempty"`
	// Provider selects the realtime backend for THIS session, e.g. "gemini",
	// "deepgram", "assemblyai", "openai", or "cascaded". Empty uses the
	// server's configured default. An unknown or unconfigured provider is rejected at start with a
	// provider_unavailable error. This is what lets a tester switch backends
	// per session ("laufend wechseln") without a server redeploy.
	Provider string `json:"provider,omitempty"`
	// MediaTransport selects where microphone and model audio move. Empty
	// defaults to "websocket" for existing clients. "livekit" keeps this
	// WebSocket as the control channel and moves audio through LiveKit tracks.
	MediaTransport string `json:"media_transport,omitempty"`
	Voice          string `json:"voice,omitempty"`
	Locale         string `json:"locale,omitempty"`
	Model          string `json:"model,omitempty"`
	Thinking       string `json:"thinking,omitempty"` // "off" | "low" | "medium" | "high"
	// Raw activity-detection policy override. Pipeline translates these to
	// the kernel's internal enums.
	ActivityDetection *ActivityDetectionFrame `json:"activity_detection,omitempty"`
	Speaker           *speaker.Options        `json:"speaker,omitempty"`
	// Optional durable instruction layered on top of the role's prompt.
	SystemPromptOverride string `json:"system_prompt_override,omitempty"`
}

type State = wssession.State

type StateFrame struct {
	Type string `json:"type"` // "state"
	EventFrameFields
	State string `json:"state"`
}

type StepResolver interface {
	ResolveStep(StartFrame, int) (LiveConfigFrame, error)
}

type TextFrame struct {
	Type string `json:"type"` // "text"
	Text string `json:"text"`
}

type ToolCall struct {
	ID   string
	Name string
	Args map[string]any
}

type ToolCallFrame struct {
	Type string `json:"type"` // "tool_call"
	EventFrameFields
	ID   string         `json:"id"`
	Name string         `json:"name"`
	Args map[string]any `json:"args,omitempty"`
}

type ToolDefinitionFrame struct {
	Name                 string         `json:"name"`
	Description          string         `json:"description,omitempty"`
	ParametersJSONSchema map[string]any `json:"parameters,omitempty"`
	// Behavior is "blocking", "non_blocking", or "" (provider default).
	// Bridge-sourced tools are always declared "blocking": Gemini 3.1 flash
	// live rejects non_blocking function declarations.
	Behavior  string `json:"behavior,omitempty"`
	TimeoutMs int    `json:"timeout_ms,omitempty"`
}

type ToolResponseFrame struct {
	Type     string         `json:"type"` // "tool_response"
	ID       string         `json:"id"`
	Name     string         `json:"name"`
	Response map[string]any `json:"response"`
}

type TranscriptFrame struct {
	Type string `json:"type"` // "input_transcript" | "output_transcript"
	EventFrameFields
	Text              string  `json:"text"`
	Done              bool    `json:"done"`
	SpeakerLabel      string  `json:"speaker_label,omitempty"`
	PersonID          string  `json:"person_id,omitempty"`
	DisplayName       string  `json:"display_name,omitempty"`
	SpeakerConfidence float64 `json:"speaker_confidence,omitempty"`
}