Contracts Attention State Machine

Contracts — Attention State Machine

Formal definition. terminal/bridge/lib/attention/ implements exactly this.

Product narrative: Attention Model.

---

States

ambient · noticed · engaged · listening · responding · sleeping

Sleep is not OS suspend. In sleeping, vision and speech (except wake word) are ignored until WakeWord exits to listening.

---

Inputs (events)

Event	Source
PersonDetected(confidence)	vision poll
PersonAbsent	vision poll, N consecutive no-person frames
FaceRecognized(userid, confidence)	vision poll
FaceUnknown	vision poll
WakeWord(score)	audio proc
SpeechStart / SpeechEnd(durationMs)	audio proc
TranscriptReady(text)	bridge STT
ResponseReady(text, audio)	bridge AO + TTS
PlaybackEnded	kiosk
Tick	injected clock, 10 Hz
Error(scope)	any
EnterSleep	terminal MCP / control HTTP

---

Transition table

from	event	guard	to	side effects
ambient	PersonDetected	conf ≥ person_confidence	noticed	raise vision poll to engaged_fps
ambient	WakeWord	score ≥ threshold	listening	open anonymous session, listen.start
noticed	FaceRecognized	votes reached, conf ≥ face_confidence	engaged	open AO session as userid, run greeter, cache identity
noticed	FaceUnknown	stranger_mode = greet	engaged	open guest session, restricted overlay
noticed	FaceUnknown	stranger_mode = restricted	noticed	no session; wake still armed
noticed	PersonAbsent	absent ≥ 3 frames	ambient	drop poll to ambient_fps
engaged	WakeWord	—	listening	listen.start, disable wake (half-duplex)
engaged	SpeechStart	follow-up open OR (face_attention AND gaze)	listening	listen.start
engaged	Tick	idle > identity_ttl AND absent	ambient	SessionBridge.stop()
listening	SpeechEnd	—	listening	finalize capture, call STT
listening	Tick	elapsed > max_utterance_seconds	responding	force-close capture
listening	TranscriptReady	text non-empty	responding	thinking on, directAgent
listening	TranscriptReady	text empty	engaged	error tone, listen.stop
responding	ResponseReady	—	responding	speak to kiosk
responding	PlaybackEnded	—	engaged	open follow-up window, re-enable wake
responding	Tick	elapsed > orchestration timeout	engaged	fallback line, re-enable wake
any (not sleeping)	EnterSleep	—	sleeping	stop listen, cancel follow-up, wake armed, ignore vision
sleeping	WakeWord	score ≥ threshold	listening	listen.start (keep session if open)
sleeping	PersonDetected / Face* / Speech*	—	sleeping	ignored
any	Error(fatal)	—	ambient	tear down session, log, re-arm

---

Invariants

1. AO session exists iff state ∈ {engaged, listening, responding} (session may remain open while sleeping until TTL/absent teardown).
2. Wake word armed iff state ∉ {listening} and not (half-duplex and playing), or state is sleeping.
3. At most one in-flight directAgent call.
4. turn_id non-null iff state ∈ {listening, responding}.
5. Identity cache TTL refreshed only by positive FaceRecognized.
6. No transition longer than 50 ms wall clock inside the machine — all I/O is dispatched, never awaited, inside a transition.
7. In sleeping, vision and VAD events are no-ops; only WakeWord exits.

Effects are returned as data from the pure machine; the runner executes them. That split is what makes exhaustive offline testing possible.

---

Related pages

• Attention Model
• Dev Loop — event injection
• Terminal Control