FamReynaBrain/projects/factory/kids-hermes-voice.md

project_key, status, factory_maturity, updated

project_key	status	factory_maturity	updated
kids-hermes-voice	active	discovery	2026-08-18

Kids Hermes Voice — Project Definition

Purpose

Kids Hermes Voice is the child-safe, local voice experience spanning the Tactility ESP32 client, the voice-gateway application, and the Hermes kids/voice runtime. It is distinct from family-voice, which remains the evaluation-only speaker-identification and privacy research project. Speaker identification may later supply non-authoritative context to this project only after an explicit consent decision.

Execution map

Host / target	Repository / service	Paseo-project role	Current evidence
Mac mini .102	~/Projects/electronics/tactility/tactility_apps — Apps/PipecatVoice / related ReynaBot paths	Kids Hermes Voice · Tactility client	Repository is present on main, ahead of origin/main by 1 commit, with existing modified/untracked voice-related work; preserve it until inventoried. Existing Tactility Apps workspace: wks_c488f281bcb459c7 (registration must be rechecked before dispatch).
Mac mini .102	~/Projects/pipecat-voice-gateway	Kids Hermes Voice · Gateway	Repository is present on main, with existing modified/untracked gateway work; no reset, commit, or deployment is authorized. Workspace registration still needs discovery.
AeroPi5 .126	Hermes kids/voice runtime and legacy voice-host role	Kids Hermes Voice · Runtime	Host was reachable on 2026-08-18. Exact checkout, active service ownership, and current configuration are unverified; read-only discovery only.
Tactility ESP32 fleet	First target board must be named per task	Deployment target, not a Paseo host	No install, flash, or runtime change is authorized by this record.

Architecture boundary

Tactility voice client  <->  voice-gateway protocol  <->  Hermes kids/voice runtime
         device UX                 transport                 child-safe response policy

• The client owns capture, playback, device UI, and protocol compatibility.
• The gateway owns the versioned voice transport, capability negotiation, turn telemetry, and compatibility fallbacks.
• The Hermes runtime owns the child-safe profile, permitted tools, and local response routing.
• family-voice owns offline speaker-ID evaluation and privacy review; it is not an authentication mechanism.

Personas

• Integration planner: maps protocol, repository boundaries, and acceptance criteria; read-only.
• Tactility client implementer: isolated worktree only.
• Gateway/runtime implementer: isolated worktree only; never edits both repositories in one shared checkout.
• Build/protocol verifier: reports exact commands and outcomes without source fixes.
• Child-safety/privacy reviewer: checks profile/tool boundary, retention, and no-cloud/raw-audio claims.
• Device QA/deployment executor: acts only for a named device after explicit approval, rollback plan, and compatible SDK/firmware verification.

Safety boundaries

• Do not expose administrator/system tools to child-facing sessions.
• Do not upload, commit, or place raw audio, embeddings, credentials, or pairing material in project records.
• No always-listening capture, enrollment, firmware flash, device install, daemon restart, gateway deployment, profile/permission change, or service reconfiguration without explicit human approval.
• Existing dirty worktrees are evidence to inventory, not permission to reset, commit, merge, or overwrite.
• Every source-changing lane uses one isolated worktree and an explicitly auto-review Paseo coding session; planners/reviewers remain read-only.

First coordination task — baseline contract and inventory

Goal: establish an implementation-ready, evidence-backed baseline without changing source or devices.

Incident context: this voice path reportedly worked previously but has not been restored for an extended period. Treat the current effort as a restoration investigation: establish the last known working boundaries and concrete present blockers before proposing a change.

Acceptance criteria:

1. Identify the intended first device/board and its current firmware/SDK compatibility.
2. Inventory existing uncommitted client and gateway work by file and behavioral intent; classify it as preserve, superseded, or candidate for the first worktree.
3. Confirm the live runtime host, checkout/service owner, and the current kids/voice entry route on AeroPi5.
4. Produce a versioned client↔gateway protocol contract covering capability negotiation, PCM-first streamed output, state/error events, interruption behavior, and the full-WAV/base64 fallback.
5. Name the first source-changing milestone and its repository owner; no coding until the human approves that scope.

Allowed now: read-only repository, workspace, host, and device discovery; protocol planning; build-command discovery.

Required evidence: exact git/workspace status; repository AGENTS.md; runtime/service ownership; device identity plus firmware/SDK version; proposed contract location and verification commands.

Forbidden effects: source edits, commits, resets, installs, flashes, starts/stops/restarts, profile/permission changes, external sends, credentials, and raw-audio collection/export.

Approval gate: explicit human approval is required before dispatching an implementation agent, changing source, or interacting with a device/runtime.

Baseline findings — 2026-08-18

• The canonical device architecture is protocol-v1 LAN WebSocket, not Pipecat SmallWebRTC inside a Tactility external ELF. The latter is a documented no-go for the current SDK/firmware boundary.
• The Mac mini currently has a live LAN adapter at 192.168.68.102:8644, serving /api/esp32/voice/ws; a non-mutating HTTP probe correctly received 400 requesting a WebSocket upgrade. The default Hermes gateway separately listens on *:8642.
• Current Tactility PipecatVoice source and README agree on the .102:8644 adapter endpoint, but prior restoration evidence refers to a different endpoint. The first gate is therefore endpoint plus persisted-device-config reconciliation, not a transport redesign.
• AeroPi5 has an active hermes-gateway-kids.service running the kids profile from ~/.hermes/profiles/kids. It has no Paseo CLI/workspace registration, and no :8642 listener was observed in this discovery; it is a runtime-policy dependency, not the current LAN adapter host.
• Board .129 is reachable and its dashboard API returned HTTP 200; board .112 responds to ICMP but its dashboard port 80 was unavailable. .129 is the evidence-backed candidate for the first restoration validation, pending the human naming it as the approved target.
• The local client protocol test passed (voice_protocol tests passed) and both involved working trees passed git diff --check. This is static evidence only; it does not prove a board WebSocket session, upstream PCM, speaker playback, reconnect, or STT/Hermes/TTS.
• Existing gateway/client modifications must be inventoried and retained. A credential-bearing source artifact was encountered during read-only inspection; it must be remediated in an explicitly approved, secret-safe source-change lane and must never be copied into records, logs, or chat.

Canonical project layout

Kids Hermes Voice (cross-project record)
├── Tactility client: tactility_apps/Apps/PipecatVoice
│   └── device capture/playback, protocol-v1 state machine, persisted non-secret endpoint
├── LAN adapter: voice-assistant/hermes-esp32-voice-gateway
│   └── 192.168.68.102:8644 protocol boundary, LAN framing/limits, deterministic audio fixtures
├── Voice processing: pipecat-voice-gateway
│   └── STT/TTS/turn-service experimentation; never silently substitutes for the adapter contract
└── Kids runtime: AeroPi5 ~/.hermes profile `kids`
    └── child-safe policy and allowed-tool boundary; distinct from transport ownership

The next read-only deliverable is an endpoint/persisted-config reconciliation report for the approved board. Only after that evidence exists may a separate, approved worktree lane define the smallest restoration edit.

Related records

• family-voice.md
• tactility.md
• ../tactility_voice_gateway_elato_transition_2026.md
• ../voice_dev_infrastructure_2026.md
• ../../areas/operations/services_inventory.md