feat: Let the AI hold the line (New Wait Tool with Music & Interrupts)

[arnofrxdd]

feat: complete wait_for_user tool implementation

Description

This PR adds a built-in wait_for_user tool that allows the AI agent to dynamically pause and wait on the line when the user asks for a moment (e.g., "Hold on", "Give me 20 seconds").

Key Features:

• Dynamic Wait Loop: The tool intelligently parses how long the user asked to wait and pauses the AI engine, preventing the LLM from hallucinating responses while the user is away.
• Instant Interruptions: Registers a custom pipeline observer (_WaitInterruptObserver) that listens for user speech. If the user returns early and says "I'm back", the wait loop instantly cancels and the AI immediately responds.
• Hold Music: Plays a dedicated wait music file in 500ms chunks during the wait period. The chunking allows for near-instant cancellation of the music the moment the user speaks, preventing audio bleeding into the AI's next response.
• TTS Pipeline Sync: Uses a TTSStoppedFrame observer to ensure the AI finishes speaking its acknowledgment message ("Sure, I'll wait...") before the wait loop and interrupt observer actually begin, preventing stale transcription frames from accidentally cancelling the wait early.
• Context Preservation: Captures the exact transcription text that triggered the interruption and injects it into the tool result, allowing the LLM to seamlessly respond to exactly what the user said when they returned.
• UI Integration: Fully integrated into the UI as a built-in tool, alongside the Calculator tool.

Changes Made

• Added wait_music_8000.wav and wait_music_16000.wav to api/assets.
• Updated api/schemas/tool.py to support the new wait tool category.
• Refactored play_audio_loop in audio_playback.py to chunk audio into 500ms segments for instant cancellation.
• Implemented the wait_for_user logic in pipecat_engine_custom_tools.py.
• Added UI configuration in page.tsx and config.tsx.

---

Summary by cubic

Adds a built-in wait_for_user tool so the agent can hold the line when asked, with instant speech interrupts and hold music. Enforces a hard 5-minute cap (defaults to 60s; min 15s), adds a wait category, TTS-safe sync, LLM schema exposure, and UI support.

• New Features

  • New wait tool category and wait_for_user function exposed to the LLM (default 60s, min 15s, max 300s).
  • Speaks an acknowledgment before waiting and starts only after TTS finishes to avoid stale frames.
  • Instant interrupt on user speech; captured transcript is returned so the model can reply to exactly what was said.
  • Hold music streamed in 500ms chunks for near-instant cancellation and no audio bleed.
  • UI: added as a built-in tool (like calculator) with simple name/description and create/edit support.

• Migration

  • Alembic migration adds wait to the tool_category enum; down revision updated. Run DB migrations.

^{Written for commit ddb9eda. Summary will update on new commits.}

Greptile Summary

This PR adds a built-in tool that lets the agent wait for a caller. The main changes are:

• Adds configurable waiting with speech interruption and transcript capture.
• Plays cancellable hold music while the agent waits.
• Adds backend schema, enum, and database support for wait tools.
• Exposes the function to the LLM and adds create and edit support in the UI.

Confidence Score: 5/5

This looks safe to merge.

The wait category now passes backend validation. The wait function schema is exposed to the LLM. The transfer mapping and HTTP test editor paths are present in the updated code. No blocking issues were found in the changed code.

T-Rex Logs

What T-Rex did

• Observed that the base merge showed HANDLER_DEFINED was False before the change.
• Validated that the handler registration used a 330-second timeout, the acknowledgement TTS started and stopped before waiting, and the interrupt observer captured 'I am back' with the callback including the exact transcription.
• Confirmed that after the change one audio chunk was queued, the loop logged 'stopped', and both temporary observers were removed.
• Verified that all six harness assertions passed after the change.

_{Ran code and verified through T-Rex}

Important Files Changed

Filename	Overview
api/services/workflow/pipecat_engine_custom_tools.py	Registers the wait handler, exposes its schema to the LLM, and manages acknowledgment, interruption, hold music, and tool results.
api/services/pipecat/audio_playback.py	Splits looped audio into short chunks so playback can stop quickly.
api/services/workflow/tools/wait.py	Defines the wait function schema and its duration guidance.
api/schemas/tool.py	Adds the wait category and definition to the tool API schema.
api/alembic/versions/ceeaf3c37b2f_add_wait_to_tool_category.py	Adds the wait value to the PostgreSQL tool category enum.
ui/src/app/tools/config.tsx	Adds wait tool metadata and definition construction to the tools UI.
ui/src/app/tools/[toolUuid]/page.tsx	Adds wait tool editing while preserving the transfer and HTTP tool editor flows.

_{Reviews (4): Last reviewed commit: "fixes" | Re-trigger Greptile}

[cubic-dev-ai]

1 issue found across 9 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="api/schemas/tool.py">

<violation number="1" location="api/schemas/tool.py:28">
P0: Cannot create WaitToolDefinition through the API — ToolCategory enum in api/enums.py is missing a WAIT = "wait" member. The validate_category validator, DB CheckConstraint, and route-level validation all check category against ToolCategory values, so any request with category="wait" will be rejected before reaching the DB. Add `WAIT = "wait"` to the ToolCategory enum to match the new ToolCategoryValue literal and WaitToolDefinition.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P0: Cannot create WaitToolDefinition through the API — ToolCategory enum in api/enums.py is missing a WAIT = "wait" member. The validate_category validator, DB CheckConstraint, and route-level validation all check category against ToolCategory values, so any request with category="wait" will be rejected before reaching the DB. Add WAIT = "wait" to the ToolCategory enum to match the new ToolCategoryValue literal and WaitToolDefinition.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At api/schemas/tool.py, line 28:

<comment>Cannot create WaitToolDefinition through the API — ToolCategory enum in api/enums.py is missing a WAIT = "wait" member. The validate_category validator, DB CheckConstraint, and route-level validation all check category against ToolCategory values, so any request with category="wait" will be rejected before reaching the DB. Add `WAIT = "wait"` to the ToolCategory enum to match the new ToolCategoryValue literal and WaitToolDefinition.</comment>

<file context>
@@ -25,6 +25,7 @@
     "end_call",
     "transfer_call",
     "calculator",
+    "wait",
     "native",
     "integration",
</file context>

[cubic-dev-ai]

All reported issues were addressed across 8 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[greptile-apps]

Want your agent to iterate on Greptile's feedback? Try greploops.