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

.github/CONTRIBUTING.md

@@ -5,12 +5,12 @@ Thanks for your interest in contributing to `@deepgram/react`!
 ## Prerequisites
 
 - [Bun](https://bun.sh/) 1.3+
-- [`deepgram/agent`](https://github.com/deepgram/agent) cloned as a sibling directory (`../agent`)
+- Optional: a [`deepgram/agent`](https://github.com/deepgram/agent) sibling checkout (`../agent`) for coordinated local development
 
 ## Setup
 
 ```bash
-# Clone the agent SDK (required -- @deepgram/react depends on it via file: pointer)
+# Optional: clone and build the sibling agent SDK used by the local TypeScript path mapping
 git clone git@github.com:deepgram/agent.git ../agent
 cd ../agent && bun install && bun run build
 cd -
@@ -21,6 +21,9 @@ cd react
 bun install
 ```
 
+The project intentionally uses TypeScript 5.9.3 until `vite-plugin-dts` bundles
+an API Extractor release that supports TypeScript 6.x.
+
 ## Development
 
 ```bash

.github/dependabot.yml

@@ -7,6 +7,10 @@ updates:
     groups:
       dependencies:
         update-types: [patch, minor]
+    ignore:
+      # vite-plugin-dts currently bundles API Extractor with TypeScript 5.9.3.
+      - dependency-name: "typescript"
+        update-types: ["version-update:semver-major"]
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:

.github/workflows/ci.yml

@@ -16,7 +16,7 @@ jobs:
         with:
           bun-version: "1.3.10"
 
-      - run: bun install
+      - run: bun install --frozen-lockfile
 
       - name: Typecheck
         run: bun run typecheck

.github/workflows/npm-publish.yml

@@ -42,7 +42,7 @@ jobs:
           node-version: 22
           registry-url: https://registry.npmjs.org
 
-      - run: bun install
+      - run: bun install --frozen-lockfile
 
       - run: bun run build
 

README.md

@@ -22,7 +22,7 @@ function App() {
     <AgentProvider
       config={{
         auth: { tokenFactory: () => fetch('/api/deepgram-token').then(r => r.text()) },
-        agent: { think: { provider: { type: 'open_ai' }, model: 'gpt-4o-mini' } },
+        agent: { think: { provider: { type: 'open_ai', model: 'gpt-4o-mini' } } },
       }}
     >
       <VoiceAgent />
@@ -33,10 +33,17 @@ function App() {
 function VoiceAgent() {
   const { state, start, stop } = useAgentState();
   const { conversation } = useAgentConversation();
+  const handleStart = async () => {
+    try {
+      await start();
+    } catch (error) {
+      console.error("Failed to start voice agent", error);
+    }
+  };
 
   return (
     <div>
-      <button onClick={state === "idle" ? start : stop}>
+      <button onClick={state === "idle" ? handleStart : stop}>
         {state === "idle" ? "Start" : "Stop"}
       </button>
       {conversation.map((entry) => (
@@ -47,16 +54,18 @@ function VoiceAgent() {
 }
 ```
 
+`config`, `playerSampleRate`, and the initial `autoStart` value establish the provider session for that component lifetime. Use the runtime update methods for supported listen, think, speak, and prompt changes rather than changing `config` in place.
+
 ## Hooks
 
 | Hook | Purpose |
 |------|---------|
 | `useAgentState` | Connection state (`idle`, `connecting`, `connected`, etc.) and `start`/`stop` controls |
-| `useAgentMode` | Speaking/listening mode tracking |
-| `useAgentConversation` | Conversation transcript and `sendUserMessage` |
+| `useAgentMode` | Listening/thinking/speaking mode tracking |
+| `useAgentConversation` | Conversation transcript plus user and agent messages |
 | `useAgentMicrophone` | Mic state, mute controls, input volume |
 | `useAgentPlayer` | Audio playback state, mute controls, output volume |
-| `useAgentControls` | Stable action methods (never change identity) |
+| `useAgentControls` | Grouped lifecycle, messaging, settings, and mute controls |
 | `useAgentClientTool` | Register client-side function call handlers scoped to component lifecycle |
 | `useAgentSession` | Direct access to the underlying `AgentSession` (escape hatch) |
 | `useDeepgramAgent` | Standalone hook -- no provider needed |
@@ -81,7 +90,7 @@ See the [package README](packages/react/README.md) for full API documentation.
 
 **Prerequisites:** [Bun](https://bun.sh/) 1.3+
 
-This package depends on `@deepgram/agents` via a `file:` pointer. Clone the agent repo as a sibling:
+The published package depends on the npm release of `@deepgram/agents`. For coordinated local development, you can optionally clone a sibling checkout; this repository's TypeScript config uses it when present and otherwise resolves the npm package:
 
 ```bash
 git clone git@github.com:deepgram/agent.git ../agent

examples/basic/App.tsx

@@ -10,7 +10,7 @@ const config = {
     tokenFactory: () => fetch("/api/deepgram-token").then((r) => r.text()),
   },
   agent: {
-    think: { provider: { type: "open_ai" as const }, model: "gpt-4o-mini" },
+    think: { provider: { type: "open_ai" as const, model: "gpt-4o-mini" } },
   },
 };
 
@@ -26,13 +26,20 @@ function VoiceAgent() {
   const { state, start, stop } = useAgentState();
   const { conversation, sendUserMessage } = useAgentConversation();
   const { mode } = useAgentMode();
+  const handleStart = async () => {
+    try {
+      await start();
+    } catch (error) {
+      console.error("Failed to start voice agent", error);
+    }
+  };
 
   return (
     <div style={{ fontFamily: "system-ui", maxWidth: 600, margin: "0 auto", padding: 24 }}>
       <h1>Deepgram Voice Agent</h1>
 
       <div style={{ display: "flex", gap: 8, alignItems: "center", marginBottom: 16 }}>
-        <button onClick={state === "idle" ? start : stop}>
+        <button onClick={state === "idle" ? handleStart : stop}>
           {state === "idle" ? "Start" : "Stop"}
         </button>
         <span>State: {state}</span>

examples/basic/README.md

@@ -20,4 +20,4 @@ This example is a standalone React component. To use it in your project:
 - Wrapping your app with `AgentProvider`
 - Using `useAgentState` for connection lifecycle (`start`/`stop`)
 - Using `useAgentConversation` for transcript display and text messaging
-- Using `useAgentMode` for speaking/listening state
+- Using `useAgentMode` for listening, thinking, and speaking mode tracking