@kuralle-syrinx/core 4.0.0 → 4.2.0

package/src/reasoner-route.test.ts

@@ -0,0 +1,248 @@
+// 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 { RoutingReasoner } from "./reasoner-route.js";
+
+class ControllableReasoner implements Reasoner {
+  streamInvoked = false;
+  streamCallCount = 0;
+  capturedSignal: AbortSignal | undefined;
+  private deliver: ((part: ReasoningPart) => void) | null = null;
+
+  stream(turn: ReasonerTurn): AsyncIterable<ReasoningPart> {
+    this.streamInvoked = true;
+    this.streamCallCount += 1;
+    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 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;
+        }
+      })();
+    },
+  };
+}
+
+const fastParts: ReasoningPart[] = [
+  { type: "text-delta", text: "fast" },
+  { type: "finish", reason: "stop", text: "fast" },
+];
+
+const deepParts: ReasoningPart[] = [
+  { type: "text-delta", text: "deep" },
+  { type: "finish", reason: "stop", text: "deep" },
+];
+
+describe("RoutingReasoner", () => {
+  it("classify routing — fast and deep without speculation", async () => {
+    let fastInvoked = false;
+    let deepInvoked = false;
+
+    const routes = [
+      {
+        id: "fast",
+        reasoner: scriptedReasoner(fastParts, () => {
+          fastInvoked = true;
+        }),
+      },
+      {
+        id: "deep",
+        reasoner: scriptedReasoner(deepParts, () => {
+          deepInvoked = true;
+        }),
+      },
+    ];
+
+    const fastRouter = new RoutingReasoner({
+      routes,
+      classify: () => "fast",
+    });
+    const fastOutput = await collect(fastRouter, baseTurn());
+    expect(fastOutput).toEqual(fastParts);
+    expect(fastInvoked).toBe(true);
+    expect(deepInvoked).toBe(false);
+
+    fastInvoked = false;
+    deepInvoked = false;
+
+    const deepRouter = new RoutingReasoner({
+      routes,
+      classify: () => "deep",
+    });
+    const deepOutput = await collect(deepRouter, baseTurn());
+    expect(deepOutput).toEqual(deepParts);
+    expect(deepInvoked).toBe(true);
+    expect(fastInvoked).toBe(false);
+  });
+
+  it("speculation kept (agree)", async () => {
+    const fast = new ControllableReasoner();
+    const deep = new ControllableReasoner();
+    const bus = new PipelineBusImpl();
+    const started = bus.start();
+    const metrics: ConversationMetricPacket[] = [];
+    bus.on("metric.conversation", (pkt) => {
+      metrics.push(pkt as ConversationMetricPacket);
+    });
+
+    const router = new RoutingReasoner({
+      routes: [
+        { id: "fast", reasoner: fast },
+        { id: "deep", reasoner: deep },
+      ],
+      classify: () => "fast",
+      speculateRouteId: "fast",
+      bus,
+      contextId: "ctx-1",
+    });
+
+    const streamPromise = collect(router, baseTurn());
+    fast.emit({ type: "text-delta", text: "fast" });
+    fast.emit({ type: "finish", reason: "stop", text: "fast" });
+    const parts = await streamPromise;
+
+    expect(fast.streamCallCount).toBe(1);
+    expect(deep.streamInvoked).toBe(false);
+    expect(parts).toEqual(fastParts);
+    expect(metrics).toContainEqual(expect.objectContaining({ name: "route.selected", value: "fast" }));
+    expect(metrics.some((m) => m.name === "route.mispredict")).toBe(false);
+
+    bus.stop();
+    await started;
+  });
+
+  it("speculation discarded (disagree) — no forwarded part from mispredicted route", async () => {
+    const fast = new ControllableReasoner();
+    let deepInvoked = false;
+    let resolveClassify: ((id: string) => void) | undefined;
+    const classifyGate = new Promise<string>((resolve) => {
+      resolveClassify = resolve;
+    });
+
+    const bus = new PipelineBusImpl();
+    const started = bus.start();
+    const metrics: ConversationMetricPacket[] = [];
+    bus.on("metric.conversation", (pkt) => {
+      metrics.push(pkt as ConversationMetricPacket);
+    });
+
+    const router = new RoutingReasoner({
+      routes: [
+        { id: "fast", reasoner: fast },
+        {
+          id: "deep",
+          reasoner: scriptedReasoner(deepParts, () => {
+            deepInvoked = true;
+          }),
+        },
+      ],
+      classify: () => classifyGate,
+      speculateRouteId: "fast",
+      bus,
+      contextId: "ctx-2",
+    });
+
+    const streamPromise = collect(router, baseTurn());
+    await Promise.resolve();
+    fast.emit({ type: "text-delta", text: "must-not-forward" });
+    resolveClassify!("deep");
+    const parts = await streamPromise;
+
+    expect(fast.capturedSignal?.aborted).toBe(true);
+    expect(fast.streamCallCount).toBe(1);
+    expect(deepInvoked).toBe(true);
+    expect(parts).toEqual(deepParts);
+    expect(metrics).toContainEqual(expect.objectContaining({ name: "route.mispredict", value: "1" }));
+    expect(metrics).toContainEqual(expect.objectContaining({ name: "route.selected", value: "deep" }));
+
+    bus.stop();
+    await started;
+  });
+
+  it("R8 passthrough — single route equals direct stream", async () => {
+    const soleParts: ReasoningPart[] = [
+      { type: "text-delta", text: "only" },
+      { type: "finish", reason: "stop", text: "only" },
+    ];
+    const sole = scriptedReasoner(soleParts);
+    const direct = await collect(sole, baseTurn());
+
+    const router = new RoutingReasoner({
+      routes: [{ id: "only", reasoner: sole }],
+      classify: () => "only",
+    });
+    const routed = await collect(router, baseTurn());
+
+    expect(routed).toEqual(direct);
+    expect(routed).toEqual(soleParts);
+  });
+
+  it("unknown id — throws clear error", async () => {
+    const router = new RoutingReasoner({
+      routes: [{ id: "fast", reasoner: scriptedReasoner(fastParts) }],
+      classify: () => "missing",
+    });
+
+    await expect(collect(router, baseTurn())).rejects.toThrow('RoutingReasoner: unknown route id "missing"');
+  });
+});

package/src/reasoner-route.ts

@@ -0,0 +1,113 @@
+// 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";
+
+export interface ReasonerRoute {
+  readonly id: string;
+  readonly reasoner: Reasoner;
+}
+
+export interface RoutingReasonerOptions {
+  readonly routes: readonly ReasonerRoute[];
+  readonly classify: (turn: ReasonerTurn) => string | Promise<string>;
+  readonly speculateRouteId?: string;
+  readonly bus?: PipelineBus;
+  readonly contextId?: string;
+}
+
+export class RoutingReasoner implements Reasoner {
+  constructor(private readonly opts: RoutingReasonerOptions) {}
+
+  stream(turn: ReasonerTurn): AsyncIterable<ReasoningPart> {
+    return this.doStream(turn);
+  }
+
+  private async *doStream(turn: ReasonerTurn): AsyncGenerator<ReasoningPart> {
+    if (turn.signal.aborted) return;
+
+    if (this.opts.speculateRouteId !== undefined) {
+      yield* this.streamWithSpeculation(turn);
+      return;
+    }
+
+    const routeId = await this.opts.classify(turn);
+    const route = this.resolveRoute(routeId);
+    this.metric("route.selected", routeId);
+    const iter = route.reasoner.stream({ ...turn, signal: turn.signal })[Symbol.asyncIterator]();
+    yield* this.forwardRoute(iter, undefined, turn.signal);
+  }
+
+  private async *streamWithSpeculation(turn: ReasonerTurn): AsyncGenerator<ReasoningPart> {
+    const specId = this.opts.speculateRouteId!;
+    const specRoute = this.resolveRoute(specId);
+
+    const child = new AbortController();
+    if (turn.signal.aborted) {
+      child.abort();
+      return;
+    }
+    turn.signal.addEventListener("abort", () => child.abort(), { once: true });
+
+    const specIter = specRoute.reasoner.stream({ ...turn, signal: child.signal })[Symbol.asyncIterator]();
+    const specNext = specIter.next();
+
+    const classifiedId = await this.opts.classify(turn);
+
+    if (classifiedId === specId) {
+      this.metric("route.selected", classifiedId);
+      yield* this.forwardRoute(specIter, specNext, turn.signal);
+      return;
+    }
+
+    child.abort();
+    releaseIterator(specIter);
+    void specNext.catch(() => undefined);
+    this.metric("route.mispredict", "1");
+
+    const route = this.resolveRoute(classifiedId);
+    this.metric("route.selected", classifiedId);
+    const iter = route.reasoner.stream({ ...turn, signal: turn.signal })[Symbol.asyncIterator]();
+    yield* this.forwardRoute(iter, undefined, turn.signal);
+  }
+
+  private async *forwardRoute(
+    iter: AsyncIterator<ReasoningPart>,
+    first: Promise<IteratorResult<ReasoningPart>> | undefined,
+    signal: AbortSignal,
+  ): AsyncGenerator<ReasoningPart> {
+    try {
+      let next = first ? await first : await iter.next();
+      while (!next.done) {
+        if (signal.aborted) return;
+        yield next.value;
+        next = await iter.next();
+      }
+    } catch (err) {
+      yield {
+        type: "error",
+        cause: err instanceof Error ? err : new Error(String(err)),
+        recoverable: true,
+      };
+    }
+  }
+
+  private resolveRoute(id: string): ReasonerRoute {
+    const route = this.opts.routes.find((r) => r.id === id);
+    if (!route) {
+      throw new Error(`RoutingReasoner: unknown route id "${id}"`);
+    }
+    return route;
+  }
+
+  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);
+}

package/src/route-throwing-spec.test.ts

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: MIT
+// Regression guard (RL-WBS-2): a mispredicted speculative route whose next() rejects must NOT leak an
+// unhandled rejection (the abandoned specNext must be caught); and a throwing route must surface, not hang.
+import { describe, expect, it } from "vitest";
+import { RoutingReasoner } from "./reasoner-route.js";
+import type { Reasoner, ReasonerTurn, ReasoningPart } from "./reasoner.js";
+
+class ThrowingReasoner implements Reasoner {
+  async *stream(_t: ReasonerTurn): AsyncGenerator<ReasoningPart> { throw new Error("spec boom"); }
+}
+class GoodReasoner implements Reasoner {
+  constructor(private readonly text: string) {}
+  async *stream(_t: ReasonerTurn): AsyncGenerator<ReasoningPart> {
+    yield { type: "text-delta", text: this.text };
+    yield { type: "finish", reason: "stop", text: this.text };
+  }
+}
+function turn(): ReasonerTurn { return { userText: "hi", messages: [], signal: new AbortController().signal }; }
+
+describe("route reject repro", () => {
+  it("mispredicted speculative route that throws must not cause an unhandled rejection", async () => {
+    const unhandled: unknown[] = [];
+    const onUnhandled = (e: unknown) => unhandled.push(e);
+    process.on("unhandledRejection", onUnhandled);
+    try {
+      const router = new RoutingReasoner({
+        routes: [
+          { id: "fast", reasoner: new ThrowingReasoner() },     // speculated → will be abandoned
+          { id: "deep", reasoner: new GoodReasoner("deep ok") }, // classify picks this (disagree)
+        ],
+        classify: () => "deep",
+        speculateRouteId: "fast",
+      });
+      const parts: string[] = [];
+      for await (const p of router.stream(turn())) if (p.type === "text-delta") parts.push(p.text);
+      expect(parts).toEqual(["deep ok"]); // no part from the discarded spec route
+      // let any dangling rejection surface
+      await new Promise((r) => setTimeout(r, 50));
+      expect(unhandled, `unhandled rejections: ${unhandled.map(String).join("; ")}`).toEqual([]);
+    } finally {
+      process.off("unhandledRejection", onUnhandled);
+    }
+  });
+});

package/src/turn-arbiter.ts

@@ -64,6 +64,7 @@ export interface TurnArbiterDeps {
   readonly primarySpeakerGate: PrimarySpeakerGate;
   readonly ttsPlayout: TtsPlayoutClock;
   readonly minInterruptionMs: number;
+  readonly onInterrupt?: (interruptedContextId: string, source: "vad") => void;
 }
 
 export class TurnArbiter {
@@ -92,7 +93,7 @@ export class TurnArbiter {
         return;
       }
       bus.push(Route.Background, make.metric(interruptedContextId, "vaqi.interruption", "1"));
-      this.emitInterruptDetected(interruptedContextId);
+      this.decideInterrupt(interruptedContextId);
       return;
     }
 
@@ -256,11 +257,19 @@ export class TurnArbiter {
       Route.Background,
       make.metric(pending.interruptedContextId, "interrupt.latency_ms", String(sustainedMs)),
     );
-    this.emitInterruptDetected(pending.interruptedContextId);
+    this.decideInterrupt(pending.interruptedContextId);
     this.latestInterimText = "";
     this.latestInterimConfidence = null;
   }
 
+  private decideInterrupt(interruptedContextId: string): void {
+    if (this.deps.onInterrupt) {
+      this.deps.onInterrupt(interruptedContextId, "vad");
+      return;
+    }
+    this.emitInterruptDetected(interruptedContextId);
+  }
+
   private suppress(
     pending: PendingTurnInterruption,
     metricName: string,