feat(notifications): agent spoken narration via speak tool

[jonmcwest]

What

Gives the agent a voice. A new speak local tool lets the agent narrate out loud — when it finishes your request, reaches a meaningful new phase, or is blocked and needs you (a question, decision, confirmation, or an error only you can resolve). You hear it even when you're in another tab.

How it fits the architecture

The flow follows the same "pure side-effect off the event stream" pattern as completion/permission notifications:

• speak tool (packages/agent) — no-op agent-side (the agent subprocess/sandbox can't reach your speakers). It just surfaces a tool_call carrying the text + kind.
• SpeechQueueService (packages/core) — portable orchestration. Serializes utterances so parallel sessions never talk over each other, coalesces stale per-task narration, lets needs_input lines jump the queue (never dropped), and caps the queue so a burst can't back up minutes of speech. Depends only on the host-neutral ISpeech capability + injected settings/name providers — no tRPC, Node, or Electron.
• composeUtterance (packages/core) — the app owns the PostHog Code task '…' — prefix and the Hey <name>, greeting for needs-user lines, so the agent supplies only content. Idempotent against an agent that already added a prefix/greeting.
• ISpeech adapter (apps/code) — ElevenLabs playback with a macOS say fallback (audio tags like [laughs] are stripped by the fallback).
• Settings — users choose which kinds are spoken (and can mute progress), pick a voice, and set the API key in Notifications settings.

Testing

• packages/core speech + composeUtterance: 18 tests pass
• packages/ui speechRouting: 12 tests pass
• packages/agent speak tool: 11 tests pass
• Full pnpm typecheck clean across all 22 packages
• Biome lint clean on touched files (no noRestrictedImports violations in core)

---

Created with PostHog Code

[github-actions]

React Doctor found no issues in the changed files. 🎉

_{Reviewed by React Doctor for commit 8818df8.}

[greptile-apps]

Comments Outside Diff (2)

1. packages/core/src/sessions/sessionService.ts, line 1414-1421 (link)

   Orphaned speakCalls entries on session teardown

   unsubscribeFromChannel cleans up agentSpokeAt for the departing taskRunId, but not speakCalls. If a session ends while a speak tool call is mid-stream (registered in the map with a null value but not yet reaching terminal status), the entry for that tool-call ID persists in the map until reset() is called on logout. Because speakCalls is keyed by tool-call ID rather than taskRunId, the entries can't be filtered here cheaply — a small parallel set of tool-call IDs per run would make cleanup straightforward, or the map can accept the existing mild leak since reset() does clear it on logout.

2. packages/core/src/speech/composeUtterance.ts, line 975-983 (link)

   Greeting injection runs before the double-prefix guard

   The greeting is prepended to body before the "posthog code task" prefix check. If an agent-authored needs_input line (which triggers addressByName: true) already contains a task prefix — a violation of the instructions, but one that can happen with a noncompliant response — the replace(/^\s*hey\b[\s,]*/i) call has nothing to strip (the line starts with "PostHog…"), so body becomes "Hey Jon, PostHog Code task '…' — …", which then fails the early-return check and exits with a double-prefixed result. Moving the task-prefix check to run first (before any greeting logic is applied) would make the function order-independent. The existing test for "does not double-prefix" uses addressByName: false and so misses this case.

_{Reviews (1): Last reviewed commit: "fix(notifications): make agent speak on ..." | Re-trigger Greptile}

[jonmcwest]

Addressed both Greptile P2 comments in dd25b52:

1. Orphaned speakCalls on teardown — speakCalls is now keyed by taskRunId (inner map keyed by tool-call id), so unsubscribeFromChannel drops any speak calls still mid-stream for a departing run instead of leaking them until reset().

2. Greeting injection before the double-prefix guard — the ^posthog code task guard now runs before any greeting logic in composeUtterance, so an already-prefixed agent line can no longer be double-prefixed when addressByName is true. Added a regression test covering that case.

Also fixed the two failing CI checks: added enqueueSpeech to the cloud-task-update notification test harness deps, and allowlisted the host-resident ElevenLabs speech service (the API key intentionally stays in the host process, matching secure-store/encryption).

[pauldambra]

i'd be happy to approve this since i've seen it run but it's big enough we should probably get team code to review it

i think it has the natural next step of hooking up speech to text so you can reply when ph-ode talks to you