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
	// 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 interface {
	Run(ctx context.Context, input flows.AgentInput) (flows.AgentOutput, error)
}

type CascadedConfig struct {
	// SilenceRMSThreshold is the RMS level (0.0–1.0) below which a frame is
	// considered silence. Default 0.02.
	SilenceRMSThreshold float64
	// SilenceTurnMs is the minimum silence duration before we commit the
	// current turn. Default 800 ms.
	SilenceTurnMs int
	// MinTurnMs is the minimum accumulated non-silence needed to treat a
	// buffer as a real turn. Default 300 ms — filters coughs and clicks.
	MinTurnMs int
	// MaxTurnMs caps a runaway turn before forcing processing. Default
	// 30 000 ms.
	MaxTurnMs int
	// HistoryTurns is how many (user, assistant) turns to keep as rolling
	// context for the agent flow. Default 5.
	HistoryTurns int
	// TTSFormat is the audio format the TTS provider should emit. Default
	// "mp3" (provider passthrough, client transcodes if needed).
	TTSFormat string
	// TTSSpeed is the TTS speech rate. Default 1.0.
	TTSSpeed float64
}

type CascadedDeps struct {
	STT    CascadedSTT
	Agent  CascadedAgent
	TTS    CascadedTTS
	Config CascadedConfig
}

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

type CascadedSTT interface {
	Route(ctx context.Context, audio []byte, audioDurationSecs float64, opts stt.TranscribeOpts) (*stt.Result, error)
}

type CascadedTTS interface {
	Synthesize(ctx context.Context, text string, opts tts.SynthesizeOpts) (*tts.Result, error)
}

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
}

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 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 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
	// 30 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 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"`
	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"`
}