@kuralle-syrinx/core 2.1.0

package/src/primary-speaker-gate.test.ts

@@ -0,0 +1,150 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it, vi } from "vitest";
+import {
+  PrimarySpeakerGate,
+  extractSpeakerFingerprint,
+  fingerprintSimilarity,
+} from "./primary-speaker-gate.js";
+import * as primarySpeakerGateModule from "./primary-speaker-gate.js";
+import {
+  ASSISTANT_ECHO_TONE_HZ,
+  BYSTANDER_SPEAKER_TONE_HZ,
+  PRIMARY_SPEAKER_TONE_HZ,
+  mixPcm16,
+  synthesizeTonePcm16,
+} from "./primary-speaker-fixtures.js";
+
+describe("extractSpeakerFingerprint", () => {
+  it("separates distinct synthetic speakers by band shape", () => {
+    const primary = extractSpeakerFingerprint(
+      synthesizeTonePcm16({ frequencyHz: PRIMARY_SPEAKER_TONE_HZ, durationMs: 40 }),
+    );
+    const bystander = extractSpeakerFingerprint(
+      synthesizeTonePcm16({ frequencyHz: BYSTANDER_SPEAKER_TONE_HZ, durationMs: 40 }),
+    );
+    expect(primary).not.toBeNull();
+    expect(bystander).not.toBeNull();
+    const self = fingerprintSimilarity(primary!, primary!);
+    const cross = fingerprintSimilarity(primary!, bystander!);
+    expect(self).toBeGreaterThan(0.95);
+    expect(cross).toBeLessThan(0.72);
+  });
+});
+
+describe("PrimarySpeakerGate", () => {
+  it("commits barge-in for primary-only sustained speech", () => {
+    const gate = new PrimarySpeakerGate();
+    const primary = synthesizeTonePcm16({ frequencyHz: PRIMARY_SPEAKER_TONE_HZ, durationMs: 32 });
+    gate.enrollUserTurnChunk(primary);
+    gate.lockProfileFromFirstTurn();
+    gate.beginBargeInWindow();
+    for (let i = 0; i < 6; i += 1) {
+      gate.observeBargeInChunk(primary);
+    }
+    expect(gate.shouldCommitBargeIn()).toBe(true);
+  });
+
+  it("suppresses bystander sustained speech", () => {
+    const gate = new PrimarySpeakerGate();
+    gate.enrollUserTurnChunk(
+      synthesizeTonePcm16({ frequencyHz: PRIMARY_SPEAKER_TONE_HZ, durationMs: 32 }),
+    );
+    gate.lockProfileFromFirstTurn();
+    gate.beginBargeInWindow();
+    const bystander = synthesizeTonePcm16({ frequencyHz: BYSTANDER_SPEAKER_TONE_HZ, durationMs: 32 });
+    for (let i = 0; i < 8; i += 1) {
+      gate.observeBargeInChunk(bystander);
+    }
+    expect(gate.shouldCommitBargeIn()).toBe(false);
+  });
+
+  it("suppresses assistant echo over primary profile", () => {
+    const gate = new PrimarySpeakerGate();
+    gate.enrollUserTurnChunk(
+      synthesizeTonePcm16({ frequencyHz: PRIMARY_SPEAKER_TONE_HZ, durationMs: 32 }),
+    );
+    gate.lockProfileFromFirstTurn();
+    const echo = synthesizeTonePcm16({
+      frequencyHz: ASSISTANT_ECHO_TONE_HZ,
+      durationMs: 32,
+      amplitude: 0.2,
+    });
+    gate.observeAssistantPlayout(
+      synthesizeTonePcm16({ frequencyHz: ASSISTANT_ECHO_TONE_HZ, durationMs: 32 }),
+    );
+    gate.beginBargeInWindow();
+    for (let i = 0; i < 8; i += 1) {
+      gate.observeBargeInChunk(echo);
+    }
+    expect(gate.shouldCommitBargeIn()).toBe(false);
+  });
+
+  it("falls back to permissive commit when no profile is locked", () => {
+    const gate = new PrimarySpeakerGate();
+    gate.beginBargeInWindow();
+    gate.observeBargeInChunk(
+      synthesizeTonePcm16({ frequencyHz: BYSTANDER_SPEAKER_TONE_HZ, durationMs: 32 }),
+    );
+    expect(gate.hasProfile()).toBe(false);
+    expect(gate.shouldCommitBargeIn()).toBe(true);
+  });
+
+  it("commits barge-in when primary similarity beats echo even above threshold", () => {
+    const gate = new PrimarySpeakerGate({ similarityThreshold: 0.72, echoDominanceMargin: 0.12 });
+    const primary = synthesizeTonePcm16({ frequencyHz: PRIMARY_SPEAKER_TONE_HZ, durationMs: 32 });
+    gate.enrollUserTurnChunk(primary);
+    gate.lockProfileFromFirstTurn();
+    gate.observeAssistantPlayout(
+      synthesizeTonePcm16({ frequencyHz: ASSISTANT_ECHO_TONE_HZ, durationMs: 32 }),
+    );
+
+    const profile = (gate as unknown as { profile: NonNullable<ReturnType<typeof extractSpeakerFingerprint>> }).profile;
+    const assistantProfile = (gate as unknown as {
+      assistantProfile: NonNullable<ReturnType<typeof extractSpeakerFingerprint>>;
+    }).assistantProfile;
+
+    vi.spyOn(primarySpeakerGateModule, "fingerprintSimilarity").mockImplementation((_frame, reference) => {
+      if (reference === profile) return 0.95;
+      if (reference === assistantProfile) return 0.73;
+      return 0;
+    });
+
+    gate.beginBargeInWindow();
+    for (let i = 0; i < 6; i += 1) {
+      gate.observeBargeInChunk(primary);
+    }
+    expect(gate.shouldCommitBargeIn()).toBe(true);
+    vi.restoreAllMocks();
+  });
+
+  it("allows mixed audio when primary dominates", () => {
+    const gate = new PrimarySpeakerGate();
+    const primary = synthesizeTonePcm16({ frequencyHz: PRIMARY_SPEAKER_TONE_HZ, durationMs: 32 });
+    gate.enrollUserTurnChunk(primary);
+    gate.lockProfileFromFirstTurn();
+    const mixed = mixPcm16(
+      [
+        synthesizeTonePcm16({ frequencyHz: PRIMARY_SPEAKER_TONE_HZ, durationMs: 32 }),
+        synthesizeTonePcm16({ frequencyHz: BYSTANDER_SPEAKER_TONE_HZ, durationMs: 32, amplitude: 0.08 }),
+      ],
+      [1, 1],
+    );
+    gate.beginBargeInWindow();
+    for (let i = 0; i < 6; i += 1) {
+      gate.observeBargeInChunk(mixed);
+    }
+    expect(gate.shouldCommitBargeIn()).toBe(true);
+  });
+
+  it("mixes PCM chunks whose byteOffset is odd", () => {
+    const primary = synthesizeTonePcm16({ frequencyHz: PRIMARY_SPEAKER_TONE_HZ, durationMs: 32 });
+    const backing = new Uint8Array(primary.byteLength + 1);
+    backing.set(primary, 1);
+    const oddOffsetPrimary = backing.subarray(1);
+    expect(oddOffsetPrimary.byteOffset % 2).toBe(1);
+
+    expect(() => mixPcm16([oddOffsetPrimary], [1])).not.toThrow();
+    expect(mixPcm16([oddOffsetPrimary], [1])).toEqual(primary);
+  });
+});

package/src/primary-speaker-gate.ts

@@ -0,0 +1,186 @@
+// SPDX-License-Identifier: MIT
+//
+// VE-02 / G23 — lightweight primary-speaker gate for barge-in (FireRedChat pVAD direction).
+// Locks a spectral fingerprint from the first user turn; gates sustained barge-in on match.
+
+import { pcm16BytesToSamples } from "./audio/pcm.js";
+
+const SAMPLE_RATE_HZ = 16000;
+const MIN_SAMPLES = 320;
+const BAND_HZ = [150, 300, 600, 1200, 2400, 4800] as const;
+
+export interface SpeakerFingerprint {
+  readonly bands: readonly number[];
+  readonly rms: number;
+  readonly zcr: number;
+}
+
+export interface PrimarySpeakerGateConfig {
+  readonly enabled?: boolean;
+  readonly similarityThreshold?: number;
+  readonly echoDominanceMargin?: number;
+}
+
+export class PrimarySpeakerGate {
+  private readonly enabled: boolean;
+  private readonly similarityThreshold: number;
+  private readonly echoDominanceMargin: number;
+  private profile: SpeakerFingerprint | null = null;
+  private enrollFrames: SpeakerFingerprint[] = [];
+  private bargeInFrames: SpeakerFingerprint[] = [];
+  private assistantProfile: SpeakerFingerprint | null = null;
+
+  constructor(config: PrimarySpeakerGateConfig = {}) {
+    this.enabled = config.enabled !== false;
+    this.similarityThreshold = config.similarityThreshold ?? 0.72;
+    this.echoDominanceMargin = config.echoDominanceMargin ?? 0.12;
+  }
+
+  isEnabled(): boolean {
+    return this.enabled;
+  }
+
+  hasProfile(): boolean {
+    return this.profile !== null;
+  }
+
+  enrollUserTurnChunk(pcm: Uint8Array): void {
+    if (!this.enabled || this.profile !== null) return;
+    const frame = extractSpeakerFingerprint(pcm);
+    if (frame) this.enrollFrames.push(frame);
+  }
+
+  lockProfileFromFirstTurn(): void {
+    if (!this.enabled || this.profile !== null || this.enrollFrames.length === 0) return;
+    this.profile = averageFingerprints(this.enrollFrames);
+    this.enrollFrames = [];
+  }
+
+  beginBargeInWindow(): void {
+    this.bargeInFrames = [];
+  }
+
+  observeBargeInChunk(pcm: Uint8Array): void {
+    if (!this.enabled) return;
+    const frame = extractSpeakerFingerprint(pcm);
+    if (frame) this.bargeInFrames.push(frame);
+  }
+
+  observeAssistantPlayout(pcm: Uint8Array): void {
+    if (!this.enabled) return;
+    const frame = extractSpeakerFingerprint(pcm);
+    if (!frame) return;
+    this.assistantProfile = frame;
+  }
+
+  shouldCommitBargeIn(): boolean {
+    if (!this.enabled || this.profile === null) return true;
+    if (this.bargeInFrames.length === 0) return false;
+
+    let primaryHits = 0;
+    for (const frame of this.bargeInFrames) {
+      const primarySim = fingerprintSimilarity(frame, this.profile);
+      if (this.assistantProfile !== null) {
+        const echoSim = fingerprintSimilarity(frame, this.assistantProfile);
+        if (echoSim >= primarySim + this.echoDominanceMargin) continue;
+      }
+      if (primarySim >= this.similarityThreshold) primaryHits += 1;
+    }
+
+    const required = Math.max(1, Math.ceil(this.bargeInFrames.length * 0.45));
+    return primaryHits >= required;
+  }
+
+  resetBargeInWindow(): void {
+    this.bargeInFrames = [];
+  }
+}
+
+export function extractSpeakerFingerprint(pcm: Uint8Array): SpeakerFingerprint | null {
+  if (pcm.byteLength < MIN_SAMPLES * 2) return null;
+  let samples: Int16Array;
+  try {
+    samples = pcm16BytesToSamples(pcm);
+  } catch {
+    return null;
+  }
+  if (samples.length < MIN_SAMPLES) return null;
+
+  const window = samples.length > 512 ? samples.subarray(0, 512) : samples;
+  const bands = BAND_HZ.map((hz) => goertzelMagnitude(window, hz, SAMPLE_RATE_HZ));
+  const maxBand = Math.max(...bands, 1e-9);
+  const normalizedBands = bands.map((b) => b / maxBand);
+
+  let sumSq = 0;
+  let crossings = 0;
+  let prev = window[0]! >= 0;
+  for (let i = 0; i < window.length; i += 1) {
+    const s = window[i]!;
+    sumSq += s * s;
+    const positive = s >= 0;
+    if (i > 0 && positive !== prev) crossings += 1;
+    prev = positive;
+  }
+  const rms = Math.sqrt(sumSq / window.length) / 32768;
+  const zcr = crossings / window.length;
+
+  return { bands: normalizedBands, rms, zcr };
+}
+
+export function fingerprintSimilarity(a: SpeakerFingerprint, b: SpeakerFingerprint): number {
+  let dot = 0;
+  let normA = 0;
+  let normB = 0;
+  for (let i = 0; i < a.bands.length; i += 1) {
+    const av = a.bands[i] ?? 0;
+    const bv = b.bands[i] ?? 0;
+    dot += av * bv;
+    normA += av * av;
+    normB += bv * bv;
+  }
+  const denom = Math.sqrt(normA) * Math.sqrt(normB);
+  if (denom <= 0) return 0;
+
+  const spectral = dot / denom;
+  const rmsDelta = Math.abs(a.rms - b.rms);
+  const zcrDelta = Math.abs(a.zcr - b.zcr);
+  const timbrePenalty = Math.min(1, rmsDelta * 4 + zcrDelta * 2);
+  return Math.max(0, spectral * (1 - timbrePenalty * 0.35));
+}
+
+function averageFingerprints(frames: SpeakerFingerprint[]): SpeakerFingerprint {
+  const bandCount = frames[0]!.bands.length;
+  const bands = new Array<number>(bandCount).fill(0);
+  let rms = 0;
+  let zcr = 0;
+  for (const frame of frames) {
+    rms += frame.rms;
+    zcr += frame.zcr;
+    for (let i = 0; i < bandCount; i += 1) {
+      bands[i] = (bands[i] ?? 0) + (frame.bands[i] ?? 0);
+    }
+  }
+  const n = frames.length;
+  return {
+    bands: bands.map((b) => b / n),
+    rms: rms / n,
+    zcr: zcr / n,
+  };
+}
+
+function goertzelMagnitude(samples: Int16Array, targetHz: number, sampleRateHz: number): number {
+  const omega = (2 * Math.PI * targetHz) / sampleRateHz;
+  const coeff = 2 * Math.cos(omega);
+  let s0 = 0;
+  let s1 = 0;
+  let s2 = 0;
+  for (let i = 0; i < samples.length; i += 1) {
+    const x = samples[i]! / 32768;
+    s0 = x + coeff * s1 - s2;
+    s2 = s1;
+    s1 = s0;
+  }
+  const real = s1 - s2 * Math.cos(omega);
+  const imag = s2 * Math.sin(omega);
+  return Math.sqrt(real * real + imag * imag);
+}

package/src/provider-fallback.test.ts

@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it } from "vitest";
+import { PipelineBusImpl } from "./pipeline-bus.js";
+import { ProviderFallback, type FallbackProvider } from "./provider-fallback.js";
+import type { ConversationMetricPacket } from "./packets.js";
+
+function provider(
+  id: string,
+  send: FallbackProvider<string, string>["send"],
+  healthProbe: FallbackProvider<string, string>["healthProbe"] = async () => true,
+): FallbackProvider<string, string> {
+  return { id, send, healthProbe };
+}
+
+describe("ProviderFallback", () => {
+  it("falls through unavailable providers and emits availability metrics", async () => {
+    const bus = new PipelineBusImpl();
+    const started = bus.start();
+    const metrics: ConversationMetricPacket[] = [];
+    bus.on("metric.conversation", (pkt) => {
+      metrics.push(pkt as ConversationMetricPacket);
+    });
+    const first = provider("stt.primary", async () => {
+      throw new Error("primary down");
+    });
+    const second = provider("stt.backup", async (req) => `backup:${req}`);
+    const fallback = new ProviderFallback([first, second], {
+      bus,
+      contextId: "turn-1",
+      attemptTimeoutMs: 100,
+      recoveryProbeIntervalMs: 1000,
+    });
+
+    await expect(fallback.send("hello")).resolves.toBe("backup:hello");
+    await new Promise((resolve) => setTimeout(resolve, 10));
+
+    expect(metrics).toContainEqual(expect.objectContaining({
+      contextId: "turn-1",
+      name: "stt.primary.availability_changed",
+      value: "unavailable",
+    }));
+
+    fallback.close();
+    bus.stop();
+    await started;
+  });
+
+  it("runs background recovery probes and returns recovered providers to service", async () => {
+    const bus = new PipelineBusImpl();
+    const started = bus.start();
+    const metrics: ConversationMetricPacket[] = [];
+    bus.on("metric.conversation", (pkt) => {
+      metrics.push(pkt as ConversationMetricPacket);
+    });
+    let primaryHealthy = false;
+    const first = provider(
+      "tts.primary",
+      async () => {
+        if (!primaryHealthy) throw new Error("primary down");
+        return "primary";
+      },
+      async () => primaryHealthy,
+    );
+    const second = provider("tts.backup", async () => "backup");
+    const fallback = new ProviderFallback([first, second], {
+      bus,
+      contextId: "turn-2",
+      attemptTimeoutMs: 100,
+      recoveryProbeIntervalMs: 10,
+    });
+
+    await expect(fallback.send("hello")).resolves.toBe("backup");
+    primaryHealthy = true;
+    await new Promise((resolve) => setTimeout(resolve, 40));
+    await expect(fallback.send("hello")).resolves.toBe("primary");
+
+    expect(metrics).toContainEqual(expect.objectContaining({
+      name: "tts.primary.availability_changed",
+      value: "available",
+    }));
+
+    fallback.close();
+    bus.stop();
+    await started;
+  });
+});

package/src/provider-fallback.ts

@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: MIT
+
+import { Route, type PipelineBus } from "./pipeline-bus.js";
+import * as make from "./packet-factories.js";
+import { TimerScheduler, type Scheduler } from "./scheduler.js";
+
+export interface FallbackProvider<TReq, TResp> {
+  readonly id: string;
+  send(req: TReq, signal: AbortSignal): Promise<TResp>;
+  healthProbe(signal: AbortSignal): Promise<boolean>;
+}
+
+export interface ProviderFallbackOptions {
+  readonly bus: PipelineBus;
+  readonly contextId: string;
+  readonly attemptTimeoutMs: number;
+  readonly recoveryProbeIntervalMs: number;
+  readonly scheduler?: Scheduler;
+}
+
+export class ProviderFallback<TReq, TResp> {
+  private readonly unavailable = new Set<string>();
+  private readonly recoveryTimers = new Set<string>();
+  private readonly scheduler: Scheduler;
+
+  constructor(
+    private readonly providers: readonly FallbackProvider<TReq, TResp>[],
+    private readonly opts: ProviderFallbackOptions,
+  ) {
+    this.scheduler = opts.scheduler ?? new TimerScheduler();
+  }
+
+  async send(req: TReq): Promise<TResp> {
+    let lastError: unknown = null;
+    for (const provider of this.providers) {
+      if (this.unavailable.has(provider.id)) continue;
+      try {
+        return await provider.send(req, AbortSignal.timeout(this.opts.attemptTimeoutMs));
+      } catch (err) {
+        lastError = err;
+        this.markUnavailable(provider);
+      }
+    }
+    throw lastError instanceof Error ? lastError : new Error("all fallback providers unavailable");
+  }
+
+  close(): void {
+    for (const providerId of this.recoveryTimers) this.scheduler.cancel(recoveryKey(providerId));
+    this.recoveryTimers.clear();
+    this.unavailable.clear();
+  }
+
+  private markUnavailable(provider: FallbackProvider<TReq, TResp>): void {
+    if (!this.unavailable.has(provider.id)) {
+      this.unavailable.add(provider.id);
+      this.metric(`${provider.id}.availability_changed`, "unavailable");
+    }
+    this.scheduleRecoveryProbe(provider);
+  }
+
+  private scheduleRecoveryProbe(provider: FallbackProvider<TReq, TResp>): void {
+    if (this.recoveryTimers.has(provider.id)) return;
+    const runProbe = async (): Promise<void> => {
+      this.recoveryTimers.delete(provider.id);
+      try {
+        if (await provider.healthProbe(AbortSignal.timeout(this.opts.attemptTimeoutMs))) {
+          this.unavailable.delete(provider.id);
+          this.metric(`${provider.id}.availability_changed`, "available");
+          return;
+        }
+      } catch {
+        // Probe failure keeps the provider unavailable and schedules the next probe.
+      }
+      this.recoveryTimers.add(provider.id);
+      this.scheduler.schedule(recoveryKey(provider.id), this.opts.recoveryProbeIntervalMs, () => void runProbe());
+    };
+    this.recoveryTimers.add(provider.id);
+    this.scheduler.schedule(recoveryKey(provider.id), this.opts.recoveryProbeIntervalMs, () => void runProbe());
+  }
+
+  private metric(name: string, value: string): void {
+    this.opts.bus.push(Route.Background, make.metric(this.opts.contextId, name, value));
+  }
+}
+
+function recoveryKey(providerId: string): string {
+  return `voice.provider_fallback.recovery:${providerId}`;
+}

package/src/reasoner.test.ts

@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: MIT
+//
+// Compile-guard: pins the ReasoningPart union shape without runtime consumers.
+
+import { describe, expect, it } from "vitest";
+
+import type { Reasoner, ReasonerMessage, ReasonerTurn, ReasoningPart } from "./reasoner.js";
+
+describe("Reasoner seam types", () => {
+  it("reasoner_union_compile_guard", async () => {
+    const userMsg = { role: "user", content: "hi" } satisfies ReasonerMessage;
+
+    const turn: ReasonerTurn = {
+      userText: "hi",
+      messages: [userMsg],
+      signal: new AbortController().signal,
+    };
+
+    const textDeltaPart = { type: "text-delta", text: "hello" } satisfies ReasoningPart;
+    const toolCallPart = {
+      type: "tool-call",
+      toolId: "tool-1",
+      toolName: "doThing",
+      args: { input: 123 },
+    } satisfies ReasoningPart;
+    const toolResultPart = {
+      type: "tool-result",
+      toolId: "tool-1",
+      toolName: "doThing",
+      result: "ok",
+    } satisfies ReasoningPart;
+    const suspendedPart = {
+      type: "suspended",
+      runId: "run-1",
+      toolId: "tool-1",
+      prompt: "Pause for human-in-the-loop.",
+      payload: { step: 3 },
+    } satisfies ReasoningPart;
+    const errorPart = {
+      type: "error",
+      cause: new Error("backend exploded"),
+      recoverable: true,
+    } satisfies ReasoningPart;
+    const finishPart = { type: "finish", reason: "stop", text: "done" } satisfies ReasoningPart;
+
+    const emptyStream = async function*(): AsyncIterable<ReasoningPart> {
+      // Intentionally empty: this is purely a type-level compile guard.
+    };
+
+    const reasoner: Reasoner = {
+      stream: (_turn: ReasonerTurn): AsyncIterable<ReasoningPart> => emptyStream(),
+    };
+
+    const collected: ReasoningPart[] = [];
+    for await (const part of reasoner.stream(turn)) {
+      collected.push(part);
+    }
+
+    expect(collected).toEqual([]);
+    expect(textDeltaPart).toBeDefined();
+    expect(toolCallPart).toBeDefined();
+    expect(toolResultPart).toBeDefined();
+    expect(suspendedPart).toBeDefined();
+    expect(errorPart).toBeDefined();
+    expect(finishPart).toBeDefined();
+    expect(reasoner).toBeDefined();
+  });
+});
+

package/src/reasoner.ts

@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: MIT
+//
+// Syrinx Kernel v2 — Reasoner seam
+//
+// A reasoning backend reduced to one normalized pull-stream per turn. Frameworks
+// (AI SDK ToolLoopAgent, Mastra Agent, raw streamText) become a Reasoner via
+// adapters; the bridge drives the seam, not the framework. See RFC §4.2.
+
+/** A reasoning backend reduced to one normalized pull-stream per turn. */
+export interface Reasoner {
+  /**
+   * Drive one reasoning turn. The returned async-iterable IS the response.
+   * Cancellation (barge-in) is via `turn.signal` (abort) — the adapter forwards
+   * it into the backend stream and into tool execution.
+   *
+   * LATENCY INVARIANT (non-negotiable, see §7a): the adapter MUST yield every
+   * part the instant the backend produces it — NO buffering, NO awaiting the
+   * stream to completion, NO batching. The first `text-delta` must reach the
+   * caller as soon as the backend's first token lands. The seam adds at most one
+   * microtask + a synchronous object remap per part; it must add no I/O hop.
+   */
+  stream(turn: ReasonerTurn): AsyncIterable<ReasoningPart>;
+}
+
+export interface ReasonerTurn {
+  /** Finalized user transcript for this turn (from `eos.turn_complete`). */
+  readonly userText: string;
+  /** Full prior conversation context. The BRIDGE owns history (see §4.5). */
+  readonly messages: readonly ReasonerMessage[];
+  /** Barge-in / supersede cancellation. */
+  readonly signal: AbortSignal;
+  /** Present only when resuming a previously-suspended run (step 3). */
+  readonly resume?: { readonly runId: string; readonly data: unknown };
+}
+
+export interface ReasonerMessage {
+  readonly role: "system" | "user" | "assistant" | "tool";
+  readonly content: string;
+  readonly toolCallId?: string;
+}
+
+/** Normalized output — the union of what AI SDK + Mastra can produce, minus noise. */
+export type ReasoningPart =
+  | { readonly type: "text-delta"; readonly text: string }
+  | { readonly type: "tool-call"; readonly toolId: string; readonly toolName: string; readonly args: Record<string, unknown> }
+  | { readonly type: "tool-result"; readonly toolId: string; readonly toolName: string; readonly result: string }
+  // Human-in-the-loop pause (step 3). ALWAYS the terminal part for the turn.
+  | { readonly type: "suspended"; readonly runId: string; readonly toolId?: string; readonly prompt?: string; readonly payload: unknown }
+  // (B1) Error/abort the backend surfaced. The bridge treats `error` like today's
+  // thrown TextStreamPart `error`/`tool-error`/`finish-step(error)`: it drives the
+  // retry/`llm.error` path. `recoverable` mirrors `categorizeLlmError`. ALWAYS terminal.
+  | { readonly type: "error"; readonly cause: Error; readonly recoverable: boolean }
+  | { readonly type: "finish"; readonly reason: "stop" | "tool" | "length"; readonly text: string };
+