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 LiveProviderAdapter
	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
	// 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 Handler struct {
	// contains filtered or unexported fields
}

type HandlerOptions struct {
	Manager             *SessionManager
	Provider            ProviderFactory
	Persona             PersonaResolver
	PublicURL           string
	AllowedOrigins      []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
	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
}

type Identity struct {
	UserID string
	OrgID  string
	Plan   string
	Role   string
}

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

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
}

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 {
	Audio                []byte
	OutputTranscript     string
	OutputTranscriptDone bool
	InputTranscript      string
	InputTranscriptDone  bool
	ToolCalls            []ToolCall
	Interrupted          bool
	GoAway               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 struct {
	ID          string
	Owner       Identity
	CreatedAt   time.Time
	State       State
	HasWSClient bool // true once the client has upgraded
}

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 struct {
	// TicketSecret signs the one-time WS upgrade tickets. Must be at least
	// 16 bytes; when empty, the manager generates a random secret at
	// construction time (acceptable only for single-process deployments).
	TicketSecret []byte
	// TicketTTL limits how long a minted ticket remains valid. Defaults to
	// 90 seconds.
	TicketTTL time.Duration
	// MaxGlobalSessions caps concurrent sessions across all callers.
	// Defaults to 100.
	MaxGlobalSessions int
	// MaxPerIdentitySessions caps concurrent sessions per caller.
	// Defaults to 3.
	MaxPerIdentitySessions int
	// Clock is a time source; nil means time.Now. Tests can override.
	Clock func() time.Time
}

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"
	Reason string `json:"reason"` // "idle" | "go_away" | "client" | "error" | "shutdown"
}

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

type SessionStats struct {
	TotalSessions          int `json:"total_sessions"`
	ActiveSessions         int `json:"active_sessions"`
	PendingSessions        int `json:"pending_sessions"`
	IdentitySessions       int `json:"identity_sessions,omitempty"`
	MaxGlobalSessions      int `json:"max_global_sessions"`
	MaxPerIdentitySessions int `json:"max_per_identity_sessions"`
}

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"`
	// 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"`
	// Optional durable instruction layered on top of the role's prompt.
	SystemPromptOverride string `json:"system_prompt_override,omitempty"`
}

type State string

type StateFrame struct {
	Type  string `json:"type"` // "state"
	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"
	ID   string         `json:"id"`
	Name string         `json:"name"`
	Args map[string]any `json:"args,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"
	Text string `json:"text"`
	Done bool   `json:"done"`
}