Owner/openspec/changes/complete-full-duplex-agent-runtime/specs/voice-pet-pipeline/spec.md

ADDED Requirements

Requirement: Complete full-duplex agent runtime

The system SHALL provide a complete run-agent-live runtime that uses a dedicated full-duplex agent architecture instead of the legacy turn-based VoiceAssistantPipeline.run_agent_turn() loop.

Scenario: Full-duplex entry starts the new runtime

• WHEN the user runs .venv/bin/python -m owner_voice_pet run-agent-live
• THEN the command SHALL construct FullDuplexAgentRuntime
• AND it SHALL NOT call VoiceAssistantPipeline.run_agent_turn() as the primary runtime path

Scenario: Legacy runtime remains available

• WHEN the user runs .venv/bin/python -m owner_voice_pet run-live
• THEN the legacy wake-word turn-based runtime SHALL remain available

Requirement: AudioHub fanout

The full-duplex runtime SHALL use a single AudioHub to own microphone input and distribute frames to independent consumers without frame stealing.

Scenario: Multiple consumers subscribe

• WHEN VAD, streaming STT, interrupt detection, and diagnostics subscribe to processed capture audio
• THEN each consumer SHALL receive the same ordered audio frame sequence from its own cursor

Scenario: Ring buffer overflows

• WHEN capture or render ring buffer exceeds configured capacity
• THEN the hub SHALL drop oldest safe frames, emit an overrun diagnostic, and continue without blocking audio callbacks

Requirement: Required WebRTC APM in full-duplex mode

The full-duplex runtime SHALL process microphone capture through WebRTC AEC, NS, and AGC using playback render reference before VAD, STT, or interrupt detection consume frames.

Scenario: APM is unavailable

• WHEN OWNER_AUDIO_APM_PROVIDER=webrtc, OWNER_AUDIO_APM_REQUIRED=1, and no real WebRTC APM provider is available
• THEN run-agent-live SHALL fail startup with a structured audio APM error
• AND it SHALL NOT silently run the software barge-in fallback as complete full-duplex mode

Scenario: Fake APM is used in self-test

• WHEN agent-self-test or unit tests request fake APM
• THEN fake APM SHALL be allowed and SHALL be clearly reported as test-only

Scenario: Pure assistant echo occurs

• WHEN microphone input is only assistant render echo
• THEN APM-processed audio SHALL NOT trigger valid interruption or valid user transcript

Requirement: Always-on interruption controller

The full-duplex runtime SHALL run a continuous interruption controller that can cancel active response work from thinking, speaking, or cancellable tool_running states.

Scenario: User interrupts while speaking

• WHEN the assistant is playing audio and processed capture contains valid user speech
• THEN playback SHALL stop, active LLM/TTS work SHALL be cancelled, and the state SHALL transition through interrupted back to listening

Scenario: Interruption latency is measured

• WHEN self-test injects user speech during playback
• THEN the runtime SHALL report VAD-to-playback-stop latency and target P95 under 200 ms

Scenario: Interruption does not require STT partial

• WHEN valid user speech is detected before streaming STT emits partial text
• THEN playback cancellation SHALL still occur

Requirement: Streaming STT and streaming TTS runtime

The full-duplex runtime SHALL use streaming recognition and streaming speech output contracts for the agent path.

Scenario: User speaks during listening

• WHEN processed capture contains user speech
• THEN streaming STT SHALL emit partial or stable transcript events while speech continues and final transcript when the utterance ends

Scenario: LLM emits a sentence

• WHEN the LLM stream produces a complete safe speech segment
• THEN streaming TTS SHALL synthesize playable PCM chunks without waiting for the full assistant response

Scenario: Playback is interrupted

• WHEN cancellation occurs during streaming TTS or playback
• THEN unplayed audio chunks SHALL be discarded and unspoken assistant text SHALL NOT be committed to context

Requirement: Full-duplex Conversation Manager

The full-duplex runtime SHALL coordinate final user transcripts, session context, long-term memory retrieval, LLM streaming, tool calls, TTS playback, interruption, and recovery.

Scenario: Memory is enabled

• WHEN a final user transcript is accepted and memory is enabled
• THEN the Conversation Manager SHALL retrieve Top-K relevant memories and provide them as separate context to the LLM

Scenario: Tool call is requested

• WHEN the LLM stream requests a supported tool call
• THEN the Tool Router SHALL classify, approve, reject, or request confirmation before execution

Scenario: Tool is high risk

• WHEN a tool request involves deletion, upload, payment, account changes, installation, or other high-risk action
• THEN the runtime SHALL NOT execute it automatically

Requirement: Full-duplex self-test commands

The system SHALL provide deterministic self-test commands for the complete full-duplex agent runtime.

Scenario: Agent self-test runs

• WHEN the developer runs .venv/bin/python -m owner_voice_pet agent-self-test --profile full-duplex --turns 3
• THEN the command SHALL exercise STT, LLM, TTS, interruption, memory, and Tool Router paths and return JSON with success=true only when all checks pass

Scenario: Audio self-test runs

• WHEN the developer runs .venv/bin/python -m owner_voice_pet audio-self-test --duration 10 --check-echo
• THEN the command SHALL report device availability, APM provider health, echo suppression result, and interruption latency statistics