@kuralle-syrinx/core 4.1.0 → 4.2.0

package/src/policies/rule-based.ts

@@ -0,0 +1,140 @@
+// SPDX-License-Identifier: MIT
+
+import type { PipelineBus } from "../pipeline-bus.js";
+import type { InteractionDecision, InteractionObservation, InteractionPolicy } from "../interaction-policy.js";
+import { PrimarySpeakerGate } from "../primary-speaker-gate.js";
+import { TtsPlayoutClock } from "../tts-playout-clock.js";
+import { TurnArbiter } from "../turn-arbiter.js";
+
+export interface RuleBasedInteractionPolicyDeps {
+  readonly bus: PipelineBus;
+  readonly primarySpeakerGate: PrimarySpeakerGate;
+  readonly ttsPlayout: TtsPlayoutClock;
+  readonly minInterruptionMs: number;
+}
+
+export class RuleBasedInteractionPolicy implements InteractionPolicy {
+  readonly arbiter: TurnArbiter;
+  private readonly ttsPlayout: TtsPlayoutClock;
+  private pending: InteractionDecision[] = [];
+  private bargeInAudioConsumed = false;
+  private delegateGapOpen = false;
+  private delegateCuePlayed = false;
+  private userSpeaking = false;
+
+  constructor(deps: RuleBasedInteractionPolicyDeps) {
+    this.ttsPlayout = deps.ttsPlayout;
+    this.arbiter = new TurnArbiter({
+      ...deps,
+      onInterrupt: (id) => this.pending.push({ kind: "interrupt", interruptedContextId: id }),
+    });
+  }
+
+  observe(obs: InteractionObservation): readonly InteractionDecision[] {
+    switch (obs.kind) {
+      case "vad_speech_started":
+        this.userSpeaking = true;
+        if (obs.interruptedContextId) this.arbiter.onSpeechStarted(
+          {
+            kind: "vad.speech_started",
+            contextId: obs.contextId,
+            timestampMs: obs.timestampMs,
+            confidence: obs.confidence,
+          },
+          obs.interruptedContextId,
+        );
+        break;
+      case "vad_speech_activity":
+        this.arbiter.onSpeechActivity({
+          kind: "vad.speech_activity",
+          contextId: obs.contextId,
+          timestampMs: obs.timestampMs,
+          isAsync: true,
+        });
+        break;
+      case "vad_speech_ended":
+        this.userSpeaking = false;
+        this.arbiter.onSpeechEnded(
+          {
+            kind: "vad.speech_ended",
+            contextId: obs.contextId,
+            timestampMs: obs.timestampMs,
+          },
+          obs.hasActiveTts,
+        );
+        break;
+      case "vad_barge_in_audio":
+        this.bargeInAudioConsumed = this.arbiter.observeBargeInAudio({
+          kind: "vad.audio",
+          contextId: obs.contextId,
+          timestampMs: obs.timestampMs,
+          audio: obs.audio,
+        });
+        break;
+      case "stt_partial":
+        this.arbiter.noteInterimEvidence(obs.text);
+        if (obs.interruptedContextId) {
+          this.arbiter.onProviderSttEvidence(obs.contextId, obs.timestampMs, obs.interruptedContextId);
+        }
+        break;
+      case "stt_final":
+        this.arbiter.noteInterimEvidence(obs.text, obs.confidence);
+        if (obs.interruptedContextId) {
+          this.arbiter.onProviderSttEvidence(obs.contextId, obs.timestampMs, obs.interruptedContextId);
+        }
+        break;
+      case "delegate_state":
+        this.pending.push(...this.handleDelegateState(obs));
+        break;
+      default:
+        break;
+    }
+    if (this.pending.length === 0) return [];
+    const out = this.pending;
+    this.pending = [];
+    return out;
+  }
+
+  private handleDelegateState(obs: InteractionObservation & { kind: "delegate_state" }): InteractionDecision[] {
+    const phase = obs.toolCallPhase;
+    if (!phase) return [];
+
+    switch (phase) {
+      case "started":
+        this.delegateGapOpen = true;
+        this.delegateCuePlayed = false;
+        return [];
+      case "delayed": {
+        if (!this.delegateGapOpen || this.delegateCuePlayed) return [];
+        if (this.depsTtsActive()) return [];
+        if (this.userSpeaking) return [];
+        this.delegateCuePlayed = true;
+        return [{ kind: "backchannel", cue: "mm_hmm" }];
+      }
+      case "complete":
+      case "failed":
+        this.delegateGapOpen = false;
+        this.delegateCuePlayed = false;
+        return [];
+      default:
+        return [];
+    }
+  }
+
+  private depsTtsActive(): boolean {
+    return this.ttsPlayout.activeContexts().length > 0;
+  }
+
+  reset(_contextId: string): void {
+    this.delegateGapOpen = false;
+    this.delegateCuePlayed = false;
+    this.userSpeaking = false;
+    this.arbiter.clear();
+  }
+
+  takeBargeInAudioConsumed(): boolean {
+    const consumed = this.bargeInAudioConsumed;
+    this.bargeInAudioConsumed = false;
+    return consumed;
+  }
+}

package/src/reasoner-hedge.test.ts

@@ -0,0 +1,361 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it } from "vitest";
+
+import { PipelineBusImpl } from "./pipeline-bus.js";
+import type { ConversationMetricPacket } from "./packets.js";
+import type { Reasoner, ReasonerTurn, ReasoningPart } from "./reasoner.js";
+import { HedgedReasoner } from "./reasoner-hedge.js";
+import type { ScheduledCallback, Scheduler } from "./scheduler.js";
+
+class FakeScheduler implements Scheduler {
+  private readonly callbacks = new Map<string, ScheduledCallback>();
+
+  schedule(key: string, _delayMs: number, cb: ScheduledCallback): void {
+    this.callbacks.set(key, cb);
+  }
+
+  cancel(key: string): void {
+    this.callbacks.delete(key);
+  }
+
+  fire(key: string): void {
+    const cb = this.callbacks.get(key);
+    if (!cb) return;
+    this.callbacks.delete(key);
+    void cb();
+  }
+
+  has(key: string): boolean {
+    return this.callbacks.has(key);
+  }
+}
+
+class ControllableReasoner implements Reasoner {
+  streamInvoked = false;
+  capturedSignal: AbortSignal | undefined;
+  private deliver: ((part: ReasoningPart) => void) | null = null;
+
+  stream(turn: ReasonerTurn): AsyncIterable<ReasoningPart> {
+    this.streamInvoked = true;
+    this.capturedSignal = turn.signal;
+    const queue: ReasoningPart[] = [];
+    let wake: (() => void) | null = null;
+
+    this.deliver = (part: ReasoningPart) => {
+      queue.push(part);
+      wake?.();
+      wake = null;
+    };
+
+    async function* generator(): AsyncGenerator<ReasoningPart> {
+      while (!turn.signal.aborted) {
+        if (queue.length === 0) {
+          await new Promise<void>((resolve) => {
+            if (turn.signal.aborted) {
+              resolve();
+              return;
+            }
+            wake = resolve;
+            turn.signal.addEventListener("abort", () => resolve(), { once: true });
+          });
+        }
+        if (turn.signal.aborted) return;
+        const part = queue.shift();
+        if (part === undefined) return;
+        yield part;
+        if (part.type === "error" || part.type === "suspended" || part.type === "finish") return;
+      }
+    }
+
+    return generator();
+  }
+
+  emit(part: ReasoningPart): void {
+    this.deliver?.(part);
+  }
+}
+
+function baseTurn(signal = new AbortController().signal): ReasonerTurn {
+  return { userText: "hi", messages: [{ role: "user", content: "hi" }], signal };
+}
+
+async function collect(reasoner: Reasoner, turn: ReasonerTurn): Promise<ReasoningPart[]> {
+  const parts: ReasoningPart[] = [];
+  for await (const part of reasoner.stream(turn)) {
+    parts.push(part);
+  }
+  return parts;
+}
+
+function silentReasoner(hook?: (turn: ReasonerTurn) => void): Reasoner {
+  return {
+    stream(turn) {
+      hook?.(turn);
+      return (async function*() {
+        await new Promise<void>(() => {});
+      })();
+    },
+  };
+}
+
+function scriptedReasoner(
+  parts: readonly ReasoningPart[],
+  hook?: (turn: ReasonerTurn) => void,
+): Reasoner {
+  return {
+    stream(turn) {
+      hook?.(turn);
+      return (async function*() {
+        for (const part of parts) {
+          if (turn.signal.aborted) return;
+          yield part;
+        }
+      })();
+    },
+  };
+}
+
+describe("HedgedReasoner", () => {
+  it("(a) primary fast — backup never started", async () => {
+    const primary = new ControllableReasoner();
+    const backup = new ControllableReasoner();
+    const scheduler = new FakeScheduler();
+    const hedge = new HedgedReasoner({
+      primary,
+      backup,
+      hedgeAfterMs: 50,
+      scheduler,
+    });
+
+    const streamPromise = collect(hedge, baseTurn());
+    primary.emit({ type: "text-delta", text: "hello" });
+    primary.emit({ type: "finish", reason: "stop", text: "hello" });
+
+    const parts = await streamPromise;
+
+    expect(backup.streamInvoked).toBe(false);
+    expect(scheduler.has("hedge")).toBe(false);
+    expect(parts).toEqual([
+      { type: "text-delta", text: "hello" },
+      { type: "finish", reason: "stop", text: "hello" },
+    ]);
+  });
+
+  it("(b) hedge fires, primary still wins", async () => {
+    const primary = new ControllableReasoner();
+    const backup = new ControllableReasoner();
+    const scheduler = new FakeScheduler();
+    const bus = new PipelineBusImpl();
+    const started = bus.start();
+    const metrics: ConversationMetricPacket[] = [];
+    bus.on("metric.conversation", (pkt) => {
+      metrics.push(pkt as ConversationMetricPacket);
+    });
+
+    const hedge = new HedgedReasoner({
+      primary,
+      backup,
+      hedgeAfterMs: 50,
+      scheduler,
+      bus,
+      contextId: "ctx-1",
+    });
+
+    const streamPromise = collect(hedge, baseTurn());
+    await Promise.resolve();
+    scheduler.fire("hedge");
+    await Promise.resolve();
+    expect(backup.streamInvoked).toBe(true);
+    expect(metrics).toContainEqual(expect.objectContaining({ name: "hedge.fired", value: "1" }));
+
+    primary.emit({ type: "text-delta", text: "primary" });
+    backup.emit({ type: "text-delta", text: "backup" });
+    primary.emit({ type: "finish", reason: "stop", text: "primary" });
+
+    const parts = await streamPromise;
+
+    expect(parts).toEqual([
+      { type: "text-delta", text: "primary" },
+      { type: "finish", reason: "stop", text: "primary" },
+    ]);
+    expect(metrics).toContainEqual(expect.objectContaining({ name: "hedge.committed_to", value: "primary" }));
+    expect(backup.capturedSignal?.aborted).toBe(true);
+
+    bus.stop();
+    await started;
+  });
+
+  it("(c) backup wins — no interleaving", async () => {
+    let primarySignal: AbortSignal | undefined;
+    let backupStarted = false;
+    const scheduler = new FakeScheduler();
+    const hedge = new HedgedReasoner({
+      primary: silentReasoner((turn) => {
+        primarySignal = turn.signal;
+      }),
+      backup: scriptedReasoner(
+        [
+          { type: "text-delta", text: "backup" },
+          { type: "finish", reason: "stop", text: "backup" },
+        ],
+        () => {
+          backupStarted = true;
+        },
+      ),
+      hedgeAfterMs: 10,
+      scheduler,
+    });
+
+    const streamPromise = collect(hedge, baseTurn());
+    await Promise.resolve();
+    scheduler.fire("hedge");
+    const parts = await streamPromise;
+
+    expect(backupStarted).toBe(true);
+    expect(parts).toEqual([
+      { type: "text-delta", text: "backup" },
+      { type: "finish", reason: "stop", text: "backup" },
+    ]);
+    expect(primarySignal?.aborted).toBe(true);
+  });
+
+  it("(d) loser aborted after commit", async () => {
+    let primarySignal: AbortSignal | undefined;
+    let backupSignal: AbortSignal | undefined;
+    const scheduler = new FakeScheduler();
+    const hedge = new HedgedReasoner({
+      primary: silentReasoner((turn) => {
+        primarySignal = turn.signal;
+      }),
+      backup: scriptedReasoner(
+        [
+          { type: "text-delta", text: "backup" },
+          { type: "finish", reason: "stop", text: "backup" },
+        ],
+        (turn) => {
+          backupSignal = turn.signal;
+        },
+      ),
+      hedgeAfterMs: 5,
+      scheduler,
+    });
+
+    const streamPromise = collect(hedge, baseTurn());
+    await Promise.resolve();
+    scheduler.fire("hedge");
+    await streamPromise;
+
+    expect(primarySignal?.aborted).toBe(true);
+    expect(backupSignal?.aborted).toBe(false);
+  });
+
+  it("(e) pre-commit primary error fails over to backup", async () => {
+    let backupStarted = false;
+    const hedge = new HedgedReasoner({
+      primary: scriptedReasoner([
+        {
+          type: "error",
+          cause: new Error("primary down"),
+          recoverable: true,
+        },
+      ]),
+      backup: scriptedReasoner(
+        [
+          { type: "text-delta", text: "recovered" },
+          { type: "finish", reason: "stop", text: "recovered" },
+        ],
+        () => {
+          backupStarted = true;
+        },
+      ),
+      hedgeAfterMs: 100,
+      scheduler: new FakeScheduler(),
+    });
+
+    const parts = await collect(hedge, baseTurn());
+
+    expect(backupStarted).toBe(true);
+    expect(parts).toEqual([
+      { type: "text-delta", text: "recovered" },
+      { type: "finish", reason: "stop", text: "recovered" },
+    ]);
+    expect(parts.some((p) => p.type === "error")).toBe(false);
+  });
+
+  it("(f) post-commit error forwarded verbatim", async () => {
+    const primary = new ControllableReasoner();
+    const backup = new ControllableReasoner();
+    const hedge = new HedgedReasoner({
+      primary,
+      backup,
+      hedgeAfterMs: 100,
+      scheduler: new FakeScheduler(),
+    });
+
+    const streamPromise = collect(hedge, baseTurn());
+    primary.emit({ type: "text-delta", text: "partial" });
+    const err: ReasoningPart = {
+      type: "error",
+      cause: new Error("mid-stream"),
+      recoverable: false,
+    };
+    primary.emit(err);
+    backup.emit({ type: "text-delta", text: "backup-late" });
+
+    const parts = await streamPromise;
+
+    expect(parts).toEqual([
+      { type: "text-delta", text: "partial" },
+      err,
+    ]);
+    expect(backup.streamInvoked).toBe(false);
+  });
+
+  it("(g) metrics — fired iff backup started, committed_to reflects winner; no bus is safe", async () => {
+    const scheduler = new FakeScheduler();
+    const bus = new PipelineBusImpl();
+    const started = bus.start();
+    const metrics: ConversationMetricPacket[] = [];
+    bus.on("metric.conversation", (pkt) => {
+      metrics.push(pkt as ConversationMetricPacket);
+    });
+
+    const hedge = new HedgedReasoner({
+      primary: silentReasoner(),
+      backup: scriptedReasoner([
+        { type: "text-delta", text: "b" },
+        { type: "finish", reason: "stop", text: "b" },
+      ]),
+      hedgeAfterMs: 10,
+      scheduler,
+      bus,
+      contextId: "ctx-m",
+    });
+
+    const streamPromise = collect(hedge, baseTurn());
+    await Promise.resolve();
+    scheduler.fire("hedge");
+    await streamPromise;
+
+    expect(metrics).toContainEqual(expect.objectContaining({ name: "hedge.fired", value: "1" }));
+    expect(metrics).toContainEqual(expect.objectContaining({ name: "hedge.committed_to", value: "backup" }));
+
+    const noBusPrimary = new ControllableReasoner();
+    const noBusBackup = new ControllableReasoner();
+    const noBusHedge = new HedgedReasoner({
+      primary: noBusPrimary,
+      backup: noBusBackup,
+      hedgeAfterMs: 10,
+      scheduler: new FakeScheduler(),
+    });
+
+    const noBusPromise = collect(noBusHedge, baseTurn());
+    noBusPrimary.emit({ type: "text-delta", text: "ok" });
+    noBusPrimary.emit({ type: "finish", reason: "stop", text: "ok" });
+    await expect(noBusPromise).resolves.toHaveLength(2);
+
+    bus.stop();
+    await started;
+  });
+});

package/src/reasoner-hedge.ts

@@ -0,0 +1,216 @@
+// SPDX-License-Identifier: MIT
+
+import { Route, type PipelineBus } from "./pipeline-bus.js";
+import * as make from "./packet-factories.js";
+import type { Reasoner, ReasonerTurn, ReasoningPart } from "./reasoner.js";
+import { TimerScheduler, type Scheduler } from "./scheduler.js";
+
+export interface HedgedReasonerOptions {
+  readonly primary: Reasoner;
+  readonly backup: Reasoner;
+  readonly hedgeAfterMs: number;
+  readonly bus?: PipelineBus;
+  readonly contextId?: string;
+  readonly scheduler?: Scheduler;
+}
+
+type Backend = "primary" | "backup";
+
+type RacerResult = { who: Backend; result: IteratorResult<ReasoningPart> };
+
+const asRacer = (who: Backend, next: Promise<IteratorResult<ReasoningPart>>): Promise<RacerResult> =>
+  next
+    .then((result) => ({ who, result }))
+    .catch((err): RacerResult => ({
+      who,
+      result: {
+        done: false,
+        value: {
+          type: "error",
+          cause: err instanceof Error ? err : new Error(String(err)),
+          recoverable: true,
+        },
+      },
+    }));
+
+type CommitResult =
+  | { readonly ok: true; readonly winner: Backend; readonly first: ReasoningPart; readonly iter: AsyncIterator<ReasoningPart> }
+  | { readonly ok: false; readonly error: ReasoningPart };
+
+export class HedgedReasoner implements Reasoner {
+  private readonly scheduler: Scheduler;
+
+  constructor(private readonly opts: HedgedReasonerOptions) {
+    this.scheduler = opts.scheduler ?? new TimerScheduler();
+  }
+
+  stream(turn: ReasonerTurn): AsyncIterable<ReasoningPart> {
+    return this.doStream(turn);
+  }
+
+  private async *doStream(turn: ReasonerTurn): AsyncGenerator<ReasoningPart> {
+    const commit = await this.raceToCommit(turn);
+    if (!commit.ok) {
+      yield commit.error;
+      return;
+    }
+
+    yield commit.first;
+    let tail = await commit.iter.next();
+    while (!tail.done) {
+      yield tail.value;
+      tail = await commit.iter.next();
+    }
+  }
+
+  private async raceToCommit(turn: ReasonerTurn): Promise<CommitResult> {
+    const pc = new AbortController();
+    const bc = new AbortController();
+
+    if (turn.signal.aborted) {
+      pc.abort();
+      bc.abort();
+      return { ok: false, error: abortedError() };
+    }
+
+    turn.signal.addEventListener(
+      "abort",
+      () => {
+        pc.abort();
+        bc.abort();
+      },
+      { once: true },
+    );
+
+    let committed = false;
+    let primaryExhausted = false;
+    let backupExhausted = false;
+    let lastError: ReasoningPart | null = null;
+
+    const primaryIter = this.opts.primary.stream({ ...turn, signal: pc.signal })[Symbol.asyncIterator]();
+    let primaryNext: Promise<IteratorResult<ReasoningPart>> = primaryIter.next();
+
+    let backupIter: AsyncIterator<ReasoningPart> | null = null;
+    let backupNext: Promise<IteratorResult<ReasoningPart>> | null = null;
+    let repollRace: (() => void) | null = null;
+
+    const ensureBackup = (): void => {
+      if (backupIter) return;
+      backupIter = this.opts.backup.stream({ ...turn, signal: bc.signal })[Symbol.asyncIterator]();
+      backupNext = backupIter.next();
+      this.metric("hedge.fired", "1");
+      repollRace?.();
+    };
+
+    this.scheduler.schedule("hedge", this.opts.hedgeAfterMs, () => {
+      if (!committed) ensureBackup();
+    });
+
+    while (!committed) {
+      const raced = await new Promise<{ who: Backend; result: IteratorResult<ReasoningPart> } | "repoll">(
+        (resolve) => {
+          const racers: Array<Promise<RacerResult>> = [];
+
+          if (!primaryExhausted) {
+            racers.push(asRacer("primary", primaryNext));
+          }
+          if (backupNext && !backupExhausted) {
+            racers.push(asRacer("backup", backupNext));
+          }
+
+          if (racers.length === 0) {
+            repollRace = null;
+            resolve("repoll");
+            return;
+          }
+
+          repollRace = () => resolve("repoll");
+          void Promise.race(racers).then((winner) => {
+            repollRace = null;
+            resolve(winner);
+          });
+        },
+      );
+
+      if (raced === "repoll") {
+        if (primaryExhausted && (backupExhausted || !backupNext)) {
+          return { ok: false, error: lastError ?? abortedError() };
+        }
+        continue;
+      }
+
+      const { who, result } = raced;
+
+      if (result.done) {
+        if (who === "primary") {
+          primaryExhausted = true;
+          if (!backupIter) {
+            this.scheduler.cancel("hedge");
+            ensureBackup();
+          } else if (backupExhausted) {
+            return { ok: false, error: lastError ?? abortedError() };
+          }
+        } else {
+          backupExhausted = true;
+          if (primaryExhausted) {
+            return { ok: false, error: lastError ?? abortedError() };
+          }
+        }
+        continue;
+      }
+
+      const part = result.value;
+
+      if (part.type === "error") {
+        lastError = part;
+        if (who === "primary") {
+          primaryExhausted = true;
+          if (!backupIter) {
+            this.scheduler.cancel("hedge");
+            ensureBackup();
+          }
+          if (backupExhausted) {
+            return { ok: false, error: part };
+          }
+        } else {
+          backupExhausted = true;
+          if (primaryExhausted) {
+            return { ok: false, error: part };
+          }
+        }
+        continue;
+      }
+
+      committed = true;
+      this.scheduler.cancel("hedge");
+
+      if (who === "primary") {
+        bc.abort();
+        releaseIterator(backupIter);
+        this.metric("hedge.committed_to", "primary");
+        return { ok: true, winner: "primary", first: part, iter: primaryIter };
+      }
+
+      pc.abort();
+      releaseIterator(primaryIter);
+      this.metric("hedge.committed_to", "backup");
+      return { ok: true, winner: "backup", first: part, iter: backupIter! };
+    }
+
+    return { ok: false, error: lastError ?? abortedError() };
+  }
+
+  private metric(name: string, value: string): void {
+    this.opts.bus?.push(Route.Background, make.metric(this.opts.contextId ?? "", name, value));
+  }
+}
+
+function releaseIterator(iter: AsyncIterator<ReasoningPart> | null): void {
+  if (!iter) return;
+  const release = iter.return;
+  if (release) void release.call(iter, undefined);
+}
+
+function abortedError(): ReasoningPart {
+  return { type: "error", cause: new Error("aborted"), recoverable: true };
+}