@vellumai/assistant 0.11.2 → 0.11.3-dev.202608080427.92f668a

package/src/stt/__tests__/speech-energy.test.ts

@@ -3,6 +3,8 @@ import { describe, expect, test } from "bun:test";
 import {
   DEFAULT_SPEECH_ENERGY_THRESHOLD,
   detectPcm16SpeechActivity,
+  pcm16MaxNormalizedCorrelation,
+  pcm16MeanAmplitude,
 } from "../speech-energy.js";
 
 /** Build a PCM16LE buffer from an array of sample values. */
@@ -66,3 +68,80 @@ describe("detectPcm16SpeechActivity", () => {
     expect(detectPcm16SpeechActivity(quiet, 500)).toBe(false);
   });
 });
+
+describe("pcm16MeanAmplitude", () => {
+  test("returns 0 for an empty buffer", () => {
+    expect(pcm16MeanAmplitude(Buffer.alloc(0))).toBe(0);
+  });
+
+  test("returns the exact mean absolute amplitude", () => {
+    expect(pcm16MeanAmplitude(pcm16([1_000, -2_000, 3_000, -4_000]))).toBe(
+      2_500,
+    );
+  });
+
+  test("ignores a trailing odd byte", () => {
+    const samples = pcm16([3_000, -3_000]);
+    expect(
+      pcm16MeanAmplitude(Buffer.concat([samples, Buffer.from([0x01])])),
+    ).toBe(3_000);
+  });
+
+  test("matches the detector's threshold comparison", () => {
+    const chunks = [
+      Buffer.alloc(0),
+      pcm16([0, 0]),
+      pcm16([500, -500]),
+      pcm16([DEFAULT_SPEECH_ENERGY_THRESHOLD]),
+      pcm16([DEFAULT_SPEECH_ENERGY_THRESHOLD + 1]),
+    ];
+    for (const chunk of chunks) {
+      expect(detectPcm16SpeechActivity(chunk)).toBe(
+        pcm16MeanAmplitude(chunk) > DEFAULT_SPEECH_ENERGY_THRESHOLD,
+      );
+    }
+  });
+});
+
+describe("pcm16MaxNormalizedCorrelation", () => {
+  const wave = (frequency: number, count: number): Buffer =>
+    pcm16(
+      Array.from({ length: count }, (_, index) =>
+        Math.round(
+          8_000 * Math.sin((2 * Math.PI * frequency * index) / 16_000),
+        ),
+      ),
+    );
+
+  test("finds a matching waveform at an arbitrary reference offset", () => {
+    const input = wave(240, 800);
+    const reference = Buffer.concat([wave(410, 400), input, wave(610, 400)]);
+
+    expect(pcm16MaxNormalizedCorrelation(input, reference)).toBeGreaterThan(
+      0.99,
+    );
+  });
+
+  test("is invariant to gain and polarity", () => {
+    const inputSamples = Array.from({ length: 800 }, (_, index) =>
+      Math.round(5_000 * Math.sin((2 * Math.PI * index) / 83)),
+    );
+    const inverted = pcm16(inputSamples.map((sample) => -2 * sample));
+
+    expect(
+      pcm16MaxNormalizedCorrelation(pcm16(inputSamples), inverted),
+    ).toBeGreaterThan(0.99);
+  });
+
+  test("rejects an unrelated waveform and flat power", () => {
+    expect(
+      pcm16MaxNormalizedCorrelation(wave(240, 800), wave(610, 1_600)),
+    ).toBeLessThan(0.3);
+    expect(
+      pcm16MaxNormalizedCorrelation(
+        pcm16(new Array(800).fill(3_000)),
+        pcm16(new Array(1_600).fill(3_000)),
+      ),
+    ).toBe(0);
+  });
+});

package/src/stt/__tests__/types.test.ts

@@ -2,10 +2,14 @@ import { describe, expect, test } from "bun:test";
 
 import type {
   SttStreamServerClosedEvent,
+  SttStreamServerEagerTurnEndEvent,
   SttStreamServerErrorEvent,
   SttStreamServerEvent,
   SttStreamServerFinalEvent,
   SttStreamServerPartialEvent,
+  SttStreamServerTurnEndEvent,
+  SttStreamServerTurnResumedEvent,
+  SttStreamServerTurnStartEvent,
 } from "../types.js";
 
 // ---------------------------------------------------------------------------
@@ -87,3 +91,93 @@ describe("SttStreamServerEvent types", () => {
     expect(_label).toBeUndefined();
   });
 });
+
+describe("turn-detection server events", () => {
+  test("turn-start event compiles and round-trips", () => {
+    const event: SttStreamServerTurnStartEvent = { type: "turn-start" };
+    const asUnion: SttStreamServerEvent = event;
+    expect(asUnion.type).toBe("turn-start");
+  });
+
+  test("eager-turn-end event carries the speculated transcript", () => {
+    const event: SttStreamServerEagerTurnEndEvent = {
+      type: "eager-turn-end",
+      text: "is this the end",
+    };
+    const asUnion: SttStreamServerEvent = event;
+    expect(asUnion.type).toBe("eager-turn-end");
+    expect(event.text).toBe("is this the end");
+  });
+
+  test("turn-resumed event compiles and round-trips", () => {
+    const event: SttStreamServerTurnResumedEvent = { type: "turn-resumed" };
+    const asUnion: SttStreamServerEvent = event;
+    expect(asUnion.type).toBe("turn-resumed");
+  });
+
+  test("turn-end event carries the committed transcript and optional confidence", () => {
+    const withoutConfidence: SttStreamServerTurnEndEvent = {
+      type: "turn-end",
+      text: "done speaking",
+    };
+    expect(withoutConfidence.confidence).toBeUndefined();
+
+    const event: SttStreamServerTurnEndEvent = {
+      type: "turn-end",
+      text: "done speaking",
+      confidence: 0.82,
+    };
+    const asUnion: SttStreamServerEvent = event;
+    expect(asUnion.type).toBe("turn-end");
+    expect(event.text).toBe("done speaking");
+    expect(event.confidence).toBe(0.82);
+  });
+
+  test("a consumer switch over every variant is exhaustive", () => {
+    // Fails to compile if a variant is added to SttStreamServerEvent
+    // without a case here, which is what forces consumers to be revisited.
+    const label = (event: SttStreamServerEvent): string => {
+      switch (event.type) {
+        case "partial":
+        case "final":
+        case "finalized":
+        case "error":
+        case "closed":
+          return "transcript";
+        case "turn-start":
+        case "eager-turn-end":
+        case "turn-resumed":
+        case "turn-end":
+          return "turn";
+        default: {
+          const _exhaustive: never = event;
+          return _exhaustive;
+        }
+      }
+    };
+
+    const events: SttStreamServerEvent[] = [
+      { type: "partial", text: "a" },
+      { type: "final", text: "a" },
+      { type: "finalized" },
+      { type: "error", category: "provider-error", message: "boom" },
+      { type: "closed" },
+      { type: "turn-start" },
+      { type: "eager-turn-end", text: "a" },
+      { type: "turn-resumed" },
+      { type: "turn-end", text: "a" },
+    ];
+
+    expect(events.map(label)).toEqual([
+      "transcript",
+      "transcript",
+      "transcript",
+      "transcript",
+      "transcript",
+      "turn",
+      "turn",
+      "turn",
+      "turn",
+    ]);
+  });
+});

package/src/stt/daemon-batch-transcriber.ts

@@ -13,6 +13,7 @@
  * - xAI (`xai`)
  */
 
+import { batchBoundaryGapReason } from "../providers/speech-to-text/provider-catalog.js";
 import type {
   BatchTranscriber,
   SttProviderId,
@@ -214,6 +215,8 @@ class VellumManagedBatchTranscriber implements BatchTranscriber {
   readonly providerId = "vellum" as const;
   readonly boundaryId = "daemon-batch" as const;
 
+  constructor(private readonly language: string | undefined) {}
+
   async transcribe(
     request: SttTranscribeRequest,
   ): Promise<SttTranscribeResult> {
@@ -223,6 +226,7 @@ class VellumManagedBatchTranscriber implements BatchTranscriber {
       request.audio,
       request.mimeType,
       request.signal,
+      this.language,
     );
   }
 }
@@ -237,12 +241,14 @@ class VellumManagedBatchTranscriber implements BatchTranscriber {
  * is unavailable.
  *
  * `language` is the spoken language, forwarded to providers whose batch API
- * accepts one: Deepgram (where `"multi"` also pins nova-3) and xAI (where
+ * accepts one: Deepgram (where `"multi"` also pins nova-3), xAI (where
  * `"multi"` is dropped because it is a Deepgram-specific value, not a
- * language code). Whisper and Gemini auto-detect natively and take no
- * language parameter, so it is silently ignored for them, as is the vellum
- * managed path (the platform speech proxy accepts no language parameter;
- * see the deferral note in `resolveBatchTranscriber`).
+ * language code), and the vellum managed path, whose platform proxy passes
+ * it to Deepgram server-side. Whisper and Gemini auto-detect natively and
+ * take no language parameter, so it is silently ignored for them.
+ *
+ * Throws an {@link SttError} for a provider with no batch endpoint at all,
+ * which no key can fix and `null` would understate.
  */
 export function createDaemonBatchTranscriber(
   apiKey: string | null | undefined,
@@ -251,7 +257,7 @@ export function createDaemonBatchTranscriber(
 ): BatchTranscriber | null {
   // vellum authenticates via the platform connection, not an API key.
   if (providerId === "vellum") {
-    return new VellumManagedBatchTranscriber();
+    return new VellumManagedBatchTranscriber(language);
   }
   if (!apiKey) {
     return null;
@@ -266,6 +272,12 @@ export function createDaemonBatchTranscriber(
       return new GoogleGeminiBatchTranscriber(apiKey);
     case "xai":
       return new XAIBatchTranscriber(apiKey, language);
+    case "deepgram-flux":
+      // Same copy the resolver raises, so a direct factory caller and a
+      // config-driven one report the mismatch identically.
+      throw new SttError("provider-error", batchBoundaryGapReason(providerId), {
+        userFacing: true,
+      });
     default: {
       // Exhaustive check — compile error if a new SttProviderId is added
       // without a corresponding case here.

package/src/stt/language-metadata.ts

@@ -0,0 +1,65 @@
+/**
+ * Pure helpers for tallying and ranking detected-language tags emitted
+ * by streaming STT providers (e.g. Deepgram nova-3 `multi` per-word tags).
+ *
+ * Tag normalization is `baseLanguageSubtag` (util/language-subtag.ts);
+ * these helpers layer vote-counting on top of it so provider adapters and
+ * event consumers share one notion of a dominant language.
+ */
+
+import { baseLanguageSubtag } from "../util/language-subtag.js";
+
+/**
+ * Cast one vote into a language tally for a transcript chunk's dominant
+ * detected language. `languages` is dominance-ranked, so only the first
+ * entry votes: secondary tags at full weight would let a minority
+ * language outvote the dominant one. Blank and absent tags cast no vote;
+ * regional variants count toward their base subtag.
+ */
+export function voteDominantLanguage(
+  tally: Map<string, number>,
+  languages: readonly string[] | undefined,
+): void {
+  const dominant = baseLanguageSubtag(languages?.[0]);
+  if (dominant !== undefined) {
+    tally.set(dominant, (tally.get(dominant) ?? 0) + 1);
+  }
+}
+
+/**
+ * The dominant tag in a language tally: most votes wins, ties break by
+ * first insertion (Map iteration is insertion order). Undefined for an
+ * empty tally.
+ */
+export function dominantLanguageTag(
+  tally: ReadonlyMap<string, number>,
+): string | undefined {
+  let dominant: string | undefined;
+  let dominantCount = 0;
+  for (const [tag, count] of tally) {
+    if (count > dominantCount) {
+      dominant = tag;
+      dominantCount = count;
+    }
+  }
+  return dominant;
+}
+
+/**
+ * Tally normalized language tags and return them most-frequent-first.
+ * Ties are broken by first appearance in the input. Blank tags are
+ * skipped; regional variants count toward their base subtag.
+ */
+export function rankLanguages(tags: Iterable<string>): string[] {
+  // Map iteration order is insertion order, so a stable sort by count
+  // leaves tied tags in first-appearance order.
+  const counts = new Map<string, number>();
+  for (const tag of tags) {
+    const normalized = baseLanguageSubtag(tag);
+    if (normalized === undefined) {
+      continue;
+    }
+    counts.set(normalized, (counts.get(normalized) ?? 0) + 1);
+  }
+  return [...counts.entries()].sort((a, b) => b[1] - a[1]).map(([tag]) => tag);
+}

package/src/stt/speech-energy.ts

@@ -18,6 +18,120 @@
  */
 export const DEFAULT_SPEECH_ENERGY_THRESHOLD = 800;
 
+/**
+ * Return the mean absolute amplitude of little-endian signed PCM16 audio.
+ * Empty buffers return 0, and a trailing odd byte is ignored.
+ */
+export function pcm16MeanAmplitude(chunk: Buffer): number {
+  const sampleCount = Math.floor(chunk.length / 2);
+  if (sampleCount === 0) {
+    return 0;
+  }
+
+  let totalAmplitude = 0;
+  for (let i = 0; i < sampleCount; i += 1) {
+    totalAmplitude += Math.abs(chunk.readInt16LE(i * 2));
+  }
+  return totalAmplitude / sampleCount;
+}
+
+/**
+ * Find the strongest normalized correlation between a PCM16 input window and
+ * any same-length window in a PCM16 reference. The samples are block-averaged
+ * before matching so this stays cheap enough for live audio and remains
+ * tolerant of the low-pass filtering introduced by speakers and microphones.
+ *
+ * The absolute coefficient makes polarity inversion harmless. A flat input or
+ * reference has no identifying waveform and returns 0 instead of being treated
+ * as a match based on level alone.
+ */
+export function pcm16MaxNormalizedCorrelation(
+  input: Buffer,
+  reference: Buffer,
+  downsampleFactor = 8,
+): number {
+  if (!Number.isInteger(downsampleFactor) || downsampleFactor <= 0) {
+    return 0;
+  }
+
+  let inputSamples = blockAveragePcm16(input, downsampleFactor);
+  const referenceSamples = blockAveragePcm16(reference, downsampleFactor);
+  if (inputSamples.length > referenceSamples.length) {
+    inputSamples = inputSamples.subarray(0, referenceSamples.length);
+  }
+  if (inputSamples.length < 2) {
+    return 0;
+  }
+
+  let inputSum = 0;
+  for (let index = 0; index < inputSamples.length; index += 1) {
+    inputSum += inputSamples[index]!;
+  }
+  const inputMean = inputSum / inputSamples.length;
+  const centeredInput = new Float64Array(inputSamples.length);
+  let inputEnergy = 0;
+  for (let index = 0; index < inputSamples.length; index += 1) {
+    const centered = inputSamples[index]! - inputMean;
+    centeredInput[index] = centered;
+    inputEnergy += centered * centered;
+  }
+  if (inputEnergy === 0) {
+    return 0;
+  }
+
+  const prefixSum = new Float64Array(referenceSamples.length + 1);
+  const prefixSquareSum = new Float64Array(referenceSamples.length + 1);
+  for (let index = 0; index < referenceSamples.length; index += 1) {
+    const sample = referenceSamples[index]!;
+    prefixSum[index + 1] = prefixSum[index]! + sample;
+    prefixSquareSum[index + 1] = prefixSquareSum[index]! + sample * sample;
+  }
+
+  let best = 0;
+  const windowLength = inputSamples.length;
+  for (
+    let offset = 0;
+    offset + windowLength <= referenceSamples.length;
+    offset += 1
+  ) {
+    const referenceSum = prefixSum[offset + windowLength]! - prefixSum[offset]!;
+    const referenceSquareSum =
+      prefixSquareSum[offset + windowLength]! - prefixSquareSum[offset]!;
+    const referenceEnergy =
+      referenceSquareSum - (referenceSum * referenceSum) / windowLength;
+    if (referenceEnergy <= 0) {
+      continue;
+    }
+
+    let dotProduct = 0;
+    for (let index = 0; index < windowLength; index += 1) {
+      dotProduct += centeredInput[index]! * referenceSamples[offset + index]!;
+    }
+    const correlation =
+      Math.abs(dotProduct) / Math.sqrt(inputEnergy * referenceEnergy);
+    best = Math.max(best, Math.min(correlation, 1));
+  }
+  return best;
+}
+
+function blockAveragePcm16(
+  chunk: Buffer,
+  downsampleFactor: number,
+): Float64Array {
+  const sampleCount = Math.floor(chunk.length / 2);
+  const blockCount = Math.floor(sampleCount / downsampleFactor);
+  const result = new Float64Array(blockCount);
+  for (let block = 0; block < blockCount; block += 1) {
+    let sum = 0;
+    const firstSample = block * downsampleFactor;
+    for (let offset = 0; offset < downsampleFactor; offset += 1) {
+      sum += chunk.readInt16LE((firstSample + offset) * 2);
+    }
+    result[block] = sum / downsampleFactor;
+  }
+  return result;
+}
+
 /**
  * Detect speech activity in a chunk of little-endian signed 16-bit mono
  * PCM samples.
@@ -34,16 +148,5 @@ export function detectPcm16SpeechActivity(
   chunk: Buffer,
   threshold = DEFAULT_SPEECH_ENERGY_THRESHOLD,
 ): boolean {
-  const sampleCount = Math.floor(chunk.length / 2);
-  if (sampleCount === 0) {
-    return false;
-  }
-
-  let totalAmplitude = 0;
-  for (let i = 0; i < sampleCount; i++) {
-    totalAmplitude += Math.abs(chunk.readInt16LE(i * 2));
-  }
-  const avgAmplitude = totalAmplitude / sampleCount;
-
-  return avgAmplitude > threshold;
+  return pcm16MeanAmplitude(chunk) > threshold;
 }

package/src/stt/stt-stream-session.ts

@@ -5,8 +5,11 @@
  * a client WebSocket connection and a provider-specific streaming adapter.
  * The orchestrator accepts client events (`audio`, `stop`), routes audio
  * frames to the resolved {@link StreamingTranscriber}, and emits normalized
- * server events (`partial`, `final`, `error`, `closed`) back over the same
- * WebSocket connection with per-session ordering guarantees.
+ * server events back over the same WebSocket connection with per-session
+ * ordering guarantees: transcripts (`partial`, `final`, `finalized`),
+ * turn boundaries from providers that detect them (`turn-start`,
+ * `eager-turn-end`, `turn-resumed`, `turn-end`), and termination
+ * (`error`, `closed`).
  *
  * Session lifecycle:
  * 1. Client opens a WebSocket to `/v1/stt/stream` with required `mimeType`
@@ -17,8 +20,9 @@
  *    `resolveStreamingTranscriber()` and starts the provider session.
  * 3. The client sends `audio` frames (binary or base64-encoded JSON) and
  *    a `stop` event when recording is complete.
- * 4. The provider emits `partial` and `final` transcript events which the
- *    orchestrator forwards to the client as JSON frames.
+ * 4. The provider emits transcript events, plus turn-boundary events when it
+ *    detects turns, and the orchestrator forwards each to the client as a
+ *    JSON frame.
  * 5. The session closes deterministically on client disconnect, `stop`
  *    event, idle timeout, or runtime shutdown.
  *

package/src/stt/types.ts

@@ -23,6 +23,11 @@
 export type SttProviderId =
   | "openai-whisper"
   | "deepgram"
+  /**
+   * Deepgram's Flux conversational speech model. Shares the `deepgram`
+   * credential and is streaming-only: Flux has no batch endpoint.
+   */
+  | "deepgram-flux"
   | "google-gemini"
   | "xai"
   | "vellum";
@@ -65,6 +70,26 @@ export type ConversationStreamingMode =
   | "incremental-batch"
   | "none";
 
+/**
+ * Turn-detection support mode.
+ *
+ * Describes whether a provider decides end-of-turn itself, in-band with the
+ * audio it is already transcribing, rather than leaving the boundary to the
+ * session's local silence timer and front-door hold verdict.
+ *
+ * - `"provider"`: the provider emits turn lifecycle events (`turn-start`,
+ *   `turn-end`) on its transcript stream, and a live-voice session may let
+ *   those events commit the turn.
+ * - `"none"`: the provider transcribes only; the local silence boundary owns
+ *   end-of-turn.
+ *
+ * A provider declaring `"provider"` should number its turns: the staleness
+ * check prefers the turn index carried on the event, and degrades to the
+ * session's local VAD generation counter when one is absent, which understates
+ * the recorded latency for a turn the caller resumed and stopped again.
+ */
+export type SttTurnDetectionMode = "provider" | "none";
+
 // ---------------------------------------------------------------------------
 // Boundary identifier
 // ---------------------------------------------------------------------------
@@ -245,6 +270,10 @@ export type SttStreamServerEvent =
   | SttStreamServerPartialEvent
   | SttStreamServerFinalEvent
   | SttStreamServerFinalizedEvent
+  | SttStreamServerTurnStartEvent
+  | SttStreamServerEagerTurnEndEvent
+  | SttStreamServerTurnResumedEvent
+  | SttStreamServerTurnEndEvent
   | SttStreamServerErrorEvent
   | SttStreamServerClosedEvent;
 
@@ -263,6 +292,14 @@ export interface SttStreamServerPartialEvent {
    * provider does not surface confidence on interim chunks.
    */
   readonly confidence?: number;
+  /**
+   * All detected languages of this chunk in dominance order (first entry
+   * dominant), already normalized to lowercase base subtags (e.g. "en",
+   * "hi") by the emitting adapter; consumers must not re-normalize. Only
+   * providers with code-switching metadata (currently Deepgram nova-3
+   * `multi`) populate this. Absence means "unknown", never English.
+   */
+  readonly languages?: readonly string[];
 }
 
 /**
@@ -279,6 +316,14 @@ export interface SttStreamServerFinalEvent {
    * provider does not surface confidence on this chunk.
    */
   readonly confidence?: number;
+  /**
+   * All detected languages of this chunk in dominance order (first entry
+   * dominant), already normalized to lowercase base subtags (e.g. "en",
+   * "hi") by the emitting adapter; consumers must not re-normalize. Only
+   * providers with code-switching metadata (currently Deepgram nova-3
+   * `multi`) populate this. Absence means "unknown", never English.
+   */
+  readonly languages?: readonly string[];
   /**
    * True when this final is the flush response to
    * {@link StreamingTranscriber.finalizeUtterance} — i.e. it commits audio
@@ -298,6 +343,80 @@ export interface SttStreamServerFinalizedEvent {
   readonly type: "finalized";
 }
 
+// ---------------------------------------------------------------------------
+// Turn-detection events
+//
+// Consumers that ignore these keep committing transcripts from `final`
+// exactly as they do without a turn-detecting provider.
+// ---------------------------------------------------------------------------
+
+/**
+ * The provider's turn model detected the start of a user turn.
+ *
+ * Emitted only by providers with model-integrated turn detection; providers
+ * without it never emit these.
+ */
+export interface SttStreamServerTurnStartEvent {
+  readonly type: "turn-start";
+  /**
+   * Provider's index for the turn being opened, monotonically increasing
+   * within a stream. Undefined when the provider does not number its turns.
+   */
+  readonly turnIndex?: number;
+}
+
+/**
+ * The provider's turn model speculates the user has finished, ahead of its
+ * committed end-of-turn decision. A {@link SttStreamServerTurnResumedEvent}
+ * retracts the speculation; a {@link SttStreamServerTurnEndEvent} confirms it.
+ *
+ * Emitted only by providers with model-integrated turn detection; providers
+ * without it never emit these.
+ */
+export interface SttStreamServerEagerTurnEndEvent {
+  readonly type: "eager-turn-end";
+  /** Transcript text as of the speculated turn end. */
+  readonly text: string;
+}
+
+/**
+ * The user kept speaking after an {@link SttStreamServerEagerTurnEndEvent},
+ * retracting the speculated turn end.
+ *
+ * Emitted only by providers with model-integrated turn detection; providers
+ * without it never emit these.
+ */
+export interface SttStreamServerTurnResumedEvent {
+  readonly type: "turn-resumed";
+}
+
+/**
+ * The provider's turn model committed an end of turn: the user has finished
+ * speaking and a reply can be dispatched.
+ *
+ * Emitted only by providers with model-integrated turn detection; providers
+ * without it never emit these.
+ */
+export interface SttStreamServerTurnEndEvent {
+  readonly type: "turn-end";
+  /** Committed transcript text for the completed turn. */
+  readonly text: string;
+  /**
+   * Provider-emitted end-of-turn confidence in [0, 1]. Undefined when the
+   * provider does not surface a score.
+   */
+  readonly confidence?: number;
+  /**
+   * Provider's index for the turn being closed, matching the
+   * {@link SttStreamServerTurnStartEvent} that opened it. A consumer can
+   * compare it against the newest turn it has seen opened to tell an
+   * end-of-turn for the turn still in progress from one the provider has
+   * already superseded. Undefined when the provider does not number its
+   * turns.
+   */
+  readonly turnIndex?: number;
+}
+
 /** An error occurred during streaming transcription. */
 export interface SttStreamServerErrorEvent {
   readonly type: "error";

package/src/subagent/__tests__/consult-prompt.test.ts

@@ -20,6 +20,31 @@ describe("buildAdvisorSystem", () => {
     expect(prompt).not.toContain("<agent_system_prompt>");
   });
 
+  test("tells the advisor it has read-only tools for verifying decisive facts", () => {
+    const prompt = buildAdvisorSystem(null);
+    expect(prompt).toContain("read-only tools");
+    expect(prompt).toContain("read files");
+    expect(prompt).toContain("verification, not exploration");
+    expect(prompt).toContain("You cannot change anything");
+  });
+
+  test("does not offer the advisor a memory or conversation search", () => {
+    // The advisor's read tools stop at the workspace. Naming `recall` here
+    // would advertise a search the role allowlist does not grant, and would
+    // contradict the scope the consult framing promises the user.
+    const prompt = buildAdvisorSystem(null);
+    expect(prompt).not.toContain("recall");
+    expect(prompt).toContain("you cannot see other conversations");
+  });
+
+  test("does not claim the advisor is tool-less", () => {
+    // The advisor can open a file to check a fact; a prompt that says otherwise
+    // suppresses the read it was given tools for.
+    const prompt = buildAdvisorSystem(null);
+    expect(prompt).not.toContain("You have no tools");
+    expect(prompt).not.toContain("cannot search, read files, or run commands");
+  });
+
   test("keeps the situational context pack out of the system prompt", () => {
     // System Prompt Minimalism: the pack rides in the request turn instead.
     expect(buildAdvisorSystem("parent")).not.toContain("<agent_environment>");