deviceagent

type AuthorizedCommand ¶

type AuthorizedCommand struct {
	RuleID        string `json:"rule_id"`
	Utterance     string `json:"utterance"`
	Locale        string `json:"locale"`
	EntityID      string `json:"entity_id"`
	ExpectedState string `json:"expected_state"`
}

AuthorizedCommand is assembled exclusively from the configured rule after every binding has matched. Utterance is the canonical server-owned trigger, never the caller-provided string.

type BoxMediaHandler ¶ added in v0.51.0

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

BoxMediaHandler accepts one complete L16 turn over a dedicated HTTPS listener. It is intentionally not mounted by Bridge.Mount, keeping the existing exactly-four speechkit.device_agent.v1 routes unchanged.

func NewBoxMediaHandler(opts BoxMediaHandlerOptions) (*BoxMediaHandler, error)

func (h *BoxMediaHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)

type BoxMediaHandlerOptions ¶ added in v0.51.0

type BoxMediaHandlerOptions struct {
	Bridge            *Bridge
	LocalSTT          BoxMediaLocalTranscriber
	MediaPairingToken string
	Rule              BoxMediaRuleOptions
	STTTimeout        time.Duration
	TurnTimeout       time.Duration
}

type BoxMediaLocalTranscriber ¶ added in v0.51.0

type BoxMediaLocalTranscriber interface {
	LocalOnly() bool
	TranscribeLocal(context.Context, []byte, string) (*BoxMediaTranscript, error)
}

BoxMediaLocalTranscriber deliberately differs from the general STT router: LocalOnly must attest that this dependency has no cloud or dynamic fallback. Production wiring passes the router's concrete Local() provider directly.

type BoxMediaRuleOptions ¶ added in v0.51.0

type BoxMediaRuleOptions struct {
	DeviceID   string
	PairingID  string
	RoomID     string
	Transcript string
	CommandID  string
	Locale     string
}

BoxMediaRuleOptions defines exactly one server-owned transcript-to-command mapping for the Phase-A representative light. There is no rule collection, fuzzy matching, search, intent inference, or fallback.

type BoxMediaTLSConfig ¶ added in v0.51.0

type BoxMediaTLSConfig struct {
	ListenAddr      string
	CertificateFile string
	PrivateKeyFile  string
}

BoxMediaTLSConfig is the explicit bootstrap contract for the dedicated Box listener. Certificate provisioning is intentionally out of scope: the host supplies an existing absolute-path key pair, and the Box must separately pin the issuing local CA. There is no plaintext listener or HTTP redirect mode.

type BoxMediaTLSRuntime ¶ added in v0.51.0

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

func (r *BoxMediaTLSRuntime) Addr() net.Addr

func (r *BoxMediaTLSRuntime) Errors() <-chan error

func (r *BoxMediaTLSRuntime) Shutdown(ctx context.Context) error

type BoxMediaTLSServer ¶ added in v0.51.0

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

BoxMediaTLSServer owns only the exact Box media handler. It never mounts the general SpeechKit mux, device-agent v1 routes, MCP, Gateway, or proxy paths.

func NewBoxMediaTLSServer(config BoxMediaTLSConfig, handler http.Handler) (*BoxMediaTLSServer, error)

func (s *BoxMediaTLSServer) CertificateChainDER() [][]byte

func (s *BoxMediaTLSServer) Start(ctx context.Context) (*BoxMediaTLSRuntime, error)

type BoxMediaTranscript ¶ added in v0.51.0

type BoxMediaTranscript struct {
	Text     string
	Provider string
}

BoxMediaTranscript is the bounded result returned by the host's local STT dependency. Provider identifies the local implementation for evidence only; it is never returned to the Box.

type Bridge ¶

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

func NewBridge(opts BridgeOptions) (*Bridge, error)

func (b *Bridge) ExecuteTurn(ctx context.Context, request TurnRequest) (*TurnResult, error)

func (b *Bridge) Mount(mux *http.ServeMux)

type BridgeOptions ¶

type BridgeOptions struct {
	ServerInstanceID   string
	Bindings           []DeviceBindingOptions
	HomeAssistant      HomeAssistant
	TTS                TTSSynthesizer
	TTSReady           bool
	Claims             ClaimLedger
	Policy             *Policy
	MaxRequestAge      time.Duration
	FutureSkew         time.Duration
	ProbeTimeout       time.Duration
	StateVerifyTimeout time.Duration
	Now                func() time.Time
}

type ClaimDecision ¶

type ClaimDecision struct {
	Disposition string
	Result      *StoredResult
}

type ClaimKey ¶

type ClaimKey struct {
	PairingID string
	RequestID string
}

type ClaimLedger ¶

type ClaimLedger interface {
	Claim(context.Context, ClaimKey, [32]byte, time.Time) (ClaimDecision, error)
	Lookup(context.Context, ClaimKey, time.Time) (ClaimDecision, error)
	Complete(context.Context, ClaimKey, [32]byte, StoredResult, time.Time) error
	MarkIndeterminate(context.Context, ClaimKey, [32]byte, string, time.Time) error
}

ClaimLedger is a durable at-most-once ledger. Claim must commit a new row before returning ClaimDispatchNew. Implementations must never turn an existing nonterminal claim back into a dispatch decision.

type Denial ¶

type Denial struct {
	ErrorCode    string `json:"error_code"`
	ReasonCode   string `json:"reason_code"`
	UserGuidance string `json:"user_guidance"`
}

Denial is the stable fail-closed reason envelope returned for every request that does not match one active local rule exactly.

type DeviceBindingOptions ¶

type DeviceBindingOptions struct {
	PairingID          string
	DeviceID           string
	RoomID             string
	Token              string
	AllowedClientCIDRs []string
}

type DurableClaimLedger ¶

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

DurableClaimLedger adapts the single-purpose SQLite ledger to the bridge contract. Handles exist only for claims won by this process; after a restart every previously nonterminal claim remains indeterminate and cannot be dispatched again.

func NewDurableClaimLedger(store *claimstore.Ledger) (*DurableClaimLedger, error)

func (l *DurableClaimLedger) Claim(ctx context.Context, key ClaimKey, digest [32]byte, now time.Time) (ClaimDecision, error)

func (l *DurableClaimLedger) Complete(ctx context.Context, key ClaimKey, digest [32]byte, result StoredResult, now time.Time) error

func (l *DurableClaimLedger) Lookup(ctx context.Context, key ClaimKey, now time.Time) (ClaimDecision, error)

func (l *DurableClaimLedger) MarkIndeterminate(ctx context.Context, key ClaimKey, digest [32]byte, reason string, now time.Time) error

type HomeAssistant ¶

type HomeAssistant interface {
	Probe(context.Context) error
	Converse(context.Context, string, string) (*HomeAssistantResult, error)
	VerifyState(context.Context, string, string) error
}

type HomeAssistantClient ¶

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

func NewHomeAssistantClient(opts HomeAssistantOptions) (*HomeAssistantClient, error)

func (c *HomeAssistantClient) Converse(ctx context.Context, text, locale string) (*HomeAssistantResult, error)

func (c *HomeAssistantClient) Probe(ctx context.Context) error

func (c *HomeAssistantClient) VerifyState(ctx context.Context, entityID, expectedState string) error

type HomeAssistantDispatchError ¶

type HomeAssistantDispatchError struct {
	ReasonCode     string
	Retryable      bool
	ActionExecuted string // no | unknown
	Cause          error
}

HomeAssistantDispatchError carries only stable bridge classification. It deliberately excludes response bodies and credentials from Error().

func (e *HomeAssistantDispatchError) Error() string

func (e *HomeAssistantDispatchError) Unwrap() error

type HomeAssistantOptions ¶

type HomeAssistantOptions struct {
	BaseURL  string
	Token    string
	AgentID  string
	Language string
	Timeout  time.Duration
}

type HomeAssistantResult ¶

type HomeAssistantResult struct {
	ConversationID string
	ResponseType   string
	Speech         string
	Language       string
	SuccessTargets []HomeAssistantTarget
	FailedTargets  []HomeAssistantTarget
	ErrorCode      string
	ReasonCode     string
	ActionExecuted string // yes | no | not_applicable | unknown
}

type HomeAssistantTarget ¶

type HomeAssistantTarget struct {
	Name string `json:"name"`
	Type string `json:"type"`
	ID   string `json:"id,omitempty"`
}

HomeAssistantTarget is the documented target projection returned in the Conversation API response data.success and data.failed arrays.

type Policy ¶

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

Policy is immutable after construction and therefore safe for concurrent authorization checks. An empty or nil Policy denies every request.

func NewPolicy(options ...RuleOptions) (*Policy, error)

func (p *Policy) Authorize(deviceID, roomID, ruleID, clientText, locale string, now time.Time) (AuthorizedCommand, *Denial)

type RuleOptions ¶

type RuleOptions struct {
	RuleID      string
	DeviceID    string
	RoomID      string
	TriggerText string
	Locale      string
	Action      string
	EntityID    string
	NotBefore   time.Time
	ExpiresAt   time.Time
}

RuleOptions defines one static, server-owned G0 authorization rule. A rule is a local per-request allowlist entry, not a Workbench approval, Cloud standing grant, delegated identity, or federation capability.

type StoredResult ¶

type StoredResult struct {
	Status         string
	ConversationID string
	ResponseType   string
	Speech         string
	Language       string
	ErrorCode      string
	ReasonCode     string
	Retryable      bool
	ActionExecuted string
}

type TTSSynthesizer ¶

type TTSSynthesizer interface {
	Synthesize(context.Context, string, tts.SynthesizeOpts) (*tts.Result, error)
	ReadyHealthCheck(context.Context) map[string]error
}

type TurnExecutionError ¶ added in v0.51.0

type TurnExecutionError struct {
	StatusCode int
	Envelope   wire.ErrorEnvelope
}

TurnExecutionError preserves the stable error/reason/guidance envelope from the existing device-agent bridge when an in-process adapter executes a turn.

func (e *TurnExecutionError) Error() string

type TurnRequest ¶ added in v0.51.0

type TurnRequest struct {
	RequestID    string
	SessionID    string
	CommandID    string
	DeviceID     string
	PairingID    string
	RoomID       string
	PairingToken string
	Text         string
	Locale       string
	InputSHA256  string
}

TurnRequest is the authenticated, host-side execution contract used by bounded media ingress adapters. PairingToken is consumed only for a constant-time binding check and is never serialized or returned.

InputSHA256 is optional for existing non-media callers. A media adapter must supply the lowercase digest it independently verified over the exact input bytes. The digest joins the durable HA claim, preventing a request ID from being reused with different audio.

type TurnResult ¶ added in v0.51.0

type TurnResult struct {
	Assist     wire.AssistResponse
	Audio      []byte
	Format     string
	SampleRate int
	DurationMS int64
	Provider   string
	Voice      string
}

TurnResult combines the existing durable Home Assistant result with the existing claim-bound local TTS result. Audio is the validated provider payload returned by the v1 TTS implementation (currently WAV); media adapters remain responsible for their own final wire encoding.