feat(react)!: harden lifecycle and expand agent APIs

[GregHolmes]

Summary

• align @deepgram/react with published @deepgram/agents 0.1.2 and @deepgram/sdk 5.9
• expose current Agent events, runtime setting updates, agent-message injection, thinking state, and SDK transport errors through the provider and standalone hook
• harden start, stop, reconnect, StrictMode, microphone/TTS prop transitions, client-tool ownership, and async function-response lifecycle behavior
• update examples, API documentation, dependency locks, TypeScript compatibility, linting, and Release Please configuration

Breaking Changes

• AgentMode now includes "thinking"; exhaustive consumers must handle the new member
• public context and hook result types add required state and control members

BREAKING CHANGE: AgentMode now includes "thinking" and public context and hook result types add required members.

The breaking conventional title and commit footer intentionally direct Release Please to propose 0.2.0 from 0.1.0.

Lifecycle Safety

• canceled starts no longer poison or disconnect replacement sessions
• terminal disconnects stop microphone capture and queued playback
• microphone disable/re-enable, pending permission, reconnect, and connected-before-resolve races serialize to at most one active startup
• client-tool results are scoped to the session generation that requested them
• duplicate dynamic tool registrations clean up by ownership without removing another mounted handler
• sdk-error is forwarded separately from protocol error

Validation

• bun install --frozen-lockfile
• bun run lint
• bun run typecheck
• bun run test (64 tests)
• bun run build
• packed clean-room consumer typecheck and Vite build
• ESM and CommonJS import smoke tests
• resolved dependency chain: React -> Agents 0.1.2 -> SDK 5.9.0
• independent DevRel re-review: approve, no remaining findings

[dg-coreylweathers]

DevRel review — changes requested, for completeness of the 0.2.0 release rather than code. Gates, semver mechanics, and the live Voice Agent run all pass; the four items under "Should fix before 0.2.0 ships" are docs and changelog gaps on a breaking release, and the four questions at the end need answers before I sign off.

What this PR does
Moves @deepgram/react onto @deepgram/agents 0.1.2 / @deepgram/sdk 5.9.0 and exposes the SDK's newer surface through the provider, the focused hooks, and useDeepgramAgent: a "thinking" mode, sendAgentMessage, updateListen/Think/Speak/Prompt, and seven typed notification callbacks. It also rewrites start/stop/reconnect/StrictMode handling with generation counters so a cancelled start, a microphone failure, or a dropped session cannot leave stale audio running or send a client-tool result into a replacement session, and removes release-as so Release Please proposes 0.2.0 from the feat! commit.

What I checked

• Do the gates pass with the lockfile frozen? Yes: bun install --frozen-lockfile, Biome lint (0 diagnostics), tsc against the npm @deepgram/agents 0.1.2 with no ../agent checkout, 64/64 tests, vite build + npm pack (7 files), all in a clean node:24 container.
• Does every type, event, and method this PR re-exports exist in the published agents 0.1.2? Yes; checked its dist/index.d.ts. fn.arguments is the real field on FunctionCallItem in sdk 5.9.0.
• Is the semver story honest? Yes. The built index.d.ts diff shows exactly the declared breaks (AgentMode gains "thinking"; required members added to AgentContextValue and the hook result types; registerClientTool now returns an unsubscribe function). No export, prop, or default was removed. Two behavior changes are not declared anywhere: useDeepgramAgent().start() now empties conversation, and microphone/tts prop changes now take effect mid-session.
• Does it work against the live Voice Agent API? Yes. I drove the built provider in Node with microphone={false} tts={false}: connect in 180 ms, SettingsApplied -> listening, sendUserMessage -> user + assistant entries, updatePrompt -> PromptUpdated, updateListen -> onListenUpdated, sendAgentMessage(..., "interrupt") -> injected assistant turn, a live FunctionCallRequest -> onFunctionCall -> reply "4711.", a registerClientTool override -> reply "9090." with the prop handler never called, 16 latency reports, 0 Error/Warning/sdk-error, stop() -> disconnected/idle, restart -> connected with conversation cleared. The standalone hook connected live, then the microphone failure rolled the session back to disconnected / micActive=false / mode="idle".
• What did not match the README? For a text-injected turn the server sent no AgentThinking and no AgentStartedSpeaking, and with tts={false} the provider skips the audio-based speaking inference, so mode stayed listening through the whole reply (97 audio chunks). Same as 0.1.0, but this PR is the one documenting four modes and adding isThinking.
• Not live-verified: tts={true} playback, microphone capture, mode transitions on voice turns, StrictMode replay, and reconnect after a dropped socket (browser audio APIs are unavailable in Node; the mocked unit tests cover these).

Should fix before 0.2.0 ships

• S1 packages/react/README.md "Mode Tracking": state that speaking is inferred from incoming agent audio and requires tts={true}, and that thinking is set only when the server sends AgentThinking (not observed on sendUserMessage text turns).
• S2 The generated 0.2.0 changelog will be one Features line plus the BREAKING CHANGE footer. Edit the Release Please PR (or the squash-commit body) to list each new API, each lifecycle fix, and the full breaking list including the registerClientTool return type and useDeepgramAgent().start() clearing conversation.
• S3 onListenUpdated exists but onPromptUpdated / onSpeakUpdated / onThinkUpdated do not, although updatePrompt/Speak/Think and their message types are exported. Either add the three callbacks (additive) or document that confirmations come from useAgentSession().on(...).
• S4 Document in the standalone-hook section that start() begins a fresh session and clears conversation.

Nits

• README.md:56 MicrophoneOptions has no VAD option; list the real fields (sampleRate, echoCancellation, noiseSuppression, autoGainControl).
• README.md:123 name the behavior values: "default" | "queue" | "interrupt".
• README.md:62 onSdkError also receives microphone start failures after connect (provider.tsx:365, :381).
• hooks/useAgentSession.ts:6 JSDoc still lists updatePrompt as an escape-hatch use; it is now on useAgentControls.
• ci.yml:19 / npm-publish.yml:45 bun install is unfrozen; add --frozen-lockfile (it passes).
• README.md:86-93 / CONTRIBUTING.md:8 the ../agent sibling reads as required; tsconfig paths falls back to npm when it is absent, so mark it optional.
• package.json:54 TypeScript pinned back 6.0.2 -> 5.9.3 with no stated reason; Dependabot will propose 6.x again (PR #9 already did).

Questions

• Where does the "independent DevRel re-review: approve" in the PR body live? Nothing is on GitHub and I could not find a Slack thread.
• Is "no AgentThinking / AgentStartedSpeaking on text-injected turns" expected server behavior? It decides the exact S1 wording.
• Add the three *Updated callbacks in this release, or defer?
• Why the TypeScript downgrade?