@kuralle-syrinx/cf-agents 4.0.0 → 4.2.0

package/README.md

@@ -97,6 +97,7 @@ comes with —
 | `onDelegateQuery` / `onDelegateResult` | G2 observability hooks around the reasoner run. `onDelegateResult` is self-contained (`{ query, answer, durationMs, grounded, toolId?, toolName?, turnId, sessionId, connection }`) — the one hook for logging/persisting grounded Q&A pairs. Throwing never affects the call. |
 | `durableHistory` | G4 durable session state over the Agent's SQLite (default `true`). Set `false` for ephemeral pre-G4 behavior. |
 | `delayCueAfterMs` | G3: ms before a pending tool call fires the `tool_call_delayed` ("still working") cue. 0 disables. Default 2000. |
+| `backgroundAudio` | `{ ambient?, thinking?, duckWhileSpeaking? }` — looped ambient bed + thinking loop (raw mono PCM16 sources), mixed (ducked) under assistant speech; on the `"twilio"` transport the bed also fills between-turn gaps as comfort noise. Thinking follows the G3 cues. |
 | `inputSampleRateHz` / `outputSampleRateHz` | Edge audio rates (default 16000). |
 | `resumeWindowMs` | How long a dropped connection can resume its session. |
 | `sessionId` | `(request, agentName) => string`. Defaults to the `?sessionId=` query param (so a reconnecting client can resume), else a per-connection random id. (Not the Agent name — concurrent connections to one instance must not share a session.) |

package/package.json

@@ -1,10 +1,31 @@
 {
   "name": "@kuralle-syrinx/cf-agents",
-  "version": "4.0.0",
+  "version": "4.2.0",
   "private": false,
-  "type": "module",
-  "license": "MIT",
   "description": "withVoice(Agent) — add a Syrinx realtime or cascaded voice pipeline to a Cloudflare agents SDK Agent",
+  "keywords": [
+    "kuralle",
+    "syrinx",
+    "voice",
+    "cloudflare",
+    "agents",
+    "durable-objects",
+    "realtime",
+    "cascaded",
+    "stt",
+    "tts"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/kuralle/syrinx#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kuralle/syrinx.git",
+    "directory": "packages/cf-agents"
+  },
+  "bugs": {
+    "url": "https://github.com/kuralle/syrinx/issues"
+  },
+  "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
@@ -12,13 +33,13 @@
     "./r2-recorder": "./src/r2-recorder.ts"
   },
   "dependencies": {
-    "@kuralle-syrinx/core": "4.0.0",
-    "@kuralle-syrinx/aisdk": "4.0.0",
-    "@kuralle-syrinx/kuralle": "4.0.0",
-    "@kuralle-syrinx/server-websocket": "4.0.0",
-    "@kuralle-syrinx/ws": "4.0.0",
-    "@kuralle-syrinx/realtime": "4.0.0",
-    "@kuralle-syrinx/recorder": "4.0.0"
+    "@kuralle-syrinx/kuralle": "4.2.0",
+    "@kuralle-syrinx/server-websocket": "4.2.0",
+    "@kuralle-syrinx/core": "4.2.0",
+    "@kuralle-syrinx/aisdk": "4.2.0",
+    "@kuralle-syrinx/ws": "4.2.0",
+    "@kuralle-syrinx/recorder": "4.2.0",
+    "@kuralle-syrinx/realtime": "4.2.0"
   },
   "peerDependencies": {
     "agents": ">=0.14.0 <1.0.0"
@@ -29,18 +50,6 @@
     "typescript": "^5.7.0",
     "vitest": "^2.1.0"
   },
-  "keywords": [
-    "kuralle",
-    "syrinx",
-    "voice",
-    "cloudflare",
-    "agents",
-    "durable-objects",
-    "realtime",
-    "cascaded",
-    "stt",
-    "tts"
-  ],
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "vitest run"

package/src/build-session.ts

@@ -89,6 +89,13 @@ export interface CascadedPipeline<Env> {
    * (engine default 7000). Set it when a provider-endpointed cascade tunes this (e.g. Deepgram at 3500).
    */
   readonly sttForceFinalizeTimeoutMs?: number;
+  /**
+   * Speculative generation: start the reasoner on an eager end-of-turn signal
+   * (`eos.interim` — Deepgram Flux `eager_eot_threshold`, smart-turn interim) and
+   * commit/discard when the endpoint confirms. Trades extra LLM calls for
+   * parallelizing LLM TTFT with endpoint confirmation. @default false
+   */
+  readonly speculative?: boolean;
 }
 
 export type VoicePipeline<Env> = RealtimePipeline<Env> | CascadedPipeline<Env>;
@@ -163,6 +170,7 @@ export function buildVoiceSession<Env>(
       ...(wiring.reasonerSessionStore
         ? { sessionStore: wiring.reasonerSessionStore, sessionId: ctx.sessionId }
         : {}),
+      ...(pipeline.speculative ? { speculative: true } : {}),
     }),
   );
   session.registerPlugin("tts", tts.plugin);

package/src/with-voice.ts

@@ -19,6 +19,7 @@
 import type { Agent, Connection, ConnectionContext, WSMessage } from "agents";
 import {
   runVoiceEdgeWebSocketConnection,
+  type BackgroundAudioConfig,
   type EdgeRecorder,
 } from "@kuralle-syrinx/server-websocket/edge";
 import { runTwilioEdgeWebSocketConnection } from "@kuralle-syrinx/server-websocket/edge-twilio";
@@ -118,6 +119,14 @@ export interface WithVoiceOptions<Env> {
   readonly reasoner?: (env: Env, ctx: VoicePipelineContext) => Reasoner | Promise<Reasoner>;
   /** Optional per-call recorder (e.g. an R2-backed `EdgeRecorder`). Applies to the `"edge"` transport. */
   readonly recorder?: (env: Env, ctx: VoicePipelineContext) => EdgeRecorder | undefined;
+  /**
+   * Ambient/thinking bed mixed (ducked) under assistant speech on both transports.
+   * On the `"twilio"` transport the bed also fills the gaps between turns as
+   * comfort noise — pure digital silence on a phone line reads as "the call died".
+   * The thinking loop follows the G3 tool-call cues. Sources are raw mono PCM16
+   * (e.g. `ffmpeg -i office.mp3 -ac 1 -ar 16000 -f s16le office.pcm`).
+   */
+  readonly backgroundAudio?: BackgroundAudioConfig;
   /**
    * Fired when the front model starts a delegate tool call, before the reasoner runs — the seam
    * for a deterministic latency-masking preamble / "thinking" earcon. Throwing here never affects
@@ -416,6 +425,7 @@ export function withVoice<Env, TBase extends AgentLike>(
             ? { engineSampleRateHz: options.inputSampleRateHz }
             : {}),
           ...(options.resumeWindowMs !== undefined ? { resumeWindowMs: options.resumeWindowMs } : {}),
+          ...(options.backgroundAudio ? { backgroundAudio: options.backgroundAudio } : {}),
         }).catch(onRunnerSettled);
         return;
       }
@@ -441,6 +451,7 @@ export function withVoice<Env, TBase extends AgentLike>(
           ? { outputSampleRateHz: options.outputSampleRateHz }
           : {}),
         ...(options.resumeWindowMs !== undefined ? { resumeWindowMs: options.resumeWindowMs } : {}),
+        ...(options.backgroundAudio ? { backgroundAudio: options.backgroundAudio } : {}),
         createSession,
       }).catch(onRunnerSettled);
     }