@kuralle-syrinx/core 4.4.0 → 4.5.0

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/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-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"');
+  });
+});