deviceagent

package
v0.50.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 20, 2026 License: Apache-2.0 Imports: 22 Imported by: 0

Documentation

Index

Constants

View Source
const (
	ClaimDispatchNew     = "dispatch_new"
	ClaimReplayCompleted = "replay_completed"
	ClaimIndeterminate   = "indeterminate"
	ClaimDigestConflict  = "digest_conflict"
	ClaimNotFound        = "not_found"
)
View Source
const (
	ActionTurnOn  = "turn_on"
	ActionTurnOff = "turn_off"

	ExpectedStateOn  = "on"
	ExpectedStateOff = "off"

	PolicyErrorCodeDenied = "local_policy_denied"

	PolicyReasonRuleNotFound   = "local_rule_not_found"
	PolicyReasonDeviceMismatch = "local_rule_device_mismatch"
	PolicyReasonRoomMismatch   = "local_rule_room_mismatch"
	PolicyReasonTimeInvalid    = "local_rule_time_invalid"
	PolicyReasonNotYetValid    = "local_rule_not_yet_valid"
	PolicyReasonExpired        = "local_rule_expired"
	PolicyReasonTextMismatch   = "local_rule_text_mismatch"
	PolicyReasonLocaleMismatch = "local_rule_locale_mismatch"
)

Variables

View Source
var (
	ErrPolicyRuleInvalid   = errors.New("device-agent local policy: invalid rule")
	ErrPolicyRuleDuplicate = errors.New("device-agent local policy: duplicate rule id")
)

Functions

This section is empty.

Types

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 Bridge

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

func NewBridge

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

func (*Bridge) Mount

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

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

func (*DurableClaimLedger) Claim

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

func (*DurableClaimLedger) Complete

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

func (*DurableClaimLedger) Lookup

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

func (*DurableClaimLedger) MarkIndeterminate

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

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

func (*HomeAssistantClient) Converse

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

func (*HomeAssistantClient) Probe

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

func (*HomeAssistantClient) VerifyState

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

VerifyState reads the documented Home Assistant state resource from the already-validated origin and proves both the entity identity and exact state.

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 (*HomeAssistantDispatchError) Error

func (*HomeAssistantDispatchError) Unwrap

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

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

NewPolicy validates and copies a static local allowlist. Only reversible Tier-1 light turn_on/turn_off rules are accepted.

func (*Policy) Authorize

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

Authorize resolves one request against one explicitly named local rule. It performs no NLP, fuzzy matching, intent inference, fallback, or rule search. A nil Denial means the command is authorized; otherwise the zero command is returned and callers must not dispatch an action.

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
}

Directories

Path Synopsis
Package claimstore provides the durable at-most-once request ledger used by the local SpeechKit to Home Assistant bridge.
Package claimstore provides the durable at-most-once request ledger used by the local SpeechKit to Home Assistant bridge.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL