@kuralle-syrinx/core 2.1.0

package/src/observability-observer.ts

@@ -0,0 +1,195 @@
+// SPDX-License-Identifier: MIT
+
+import { Route, type PipelineBus } from "./pipeline-bus.js";
+import { monotonicNowMs, type MetricsExporter } from "./observability.js";
+import type {
+  TurnBoundaryKind,
+  VadSpeechStartedPacket,
+  VadSpeechEndedPacket,
+  EndOfSpeechPacket,
+  TextToSpeechAudioPacket,
+  TextToSpeechEndPacket,
+  InterruptionDetectedPacket,
+} from "./packets.js";
+import * as make from "./packet-factories.js";
+
+export interface ObservabilityDims {
+  readonly provider: string;
+  readonly model: string;
+  readonly region: string;
+}
+
+export interface ObservabilityObserverDeps {
+  readonly bus: PipelineBus;
+  readonly exporter: MetricsExporter;
+  readonly sessionId: string;
+  readonly dims: ObservabilityDims;
+  readonly getContextId: () => string;
+}
+
+type BoundaryTimes = Partial<Record<TurnBoundaryKind, number>>;
+type StageDims = Partial<ObservabilityDims> & { cancelled?: boolean };
+
+export class ObservabilityObserver {
+  private readonly boundaryTimes = new Map<string, BoundaryTimes>();
+  private readonly stageDims = new Map<string, StageDims>();
+  private readonly agentStartedEmitted = new Set<string>();
+  private readonly unsubscribes: Array<() => void> = [];
+
+  constructor(private readonly deps: ObservabilityObserverDeps) {}
+
+  wire(disposers?: Array<() => void>): void {
+    const reg = (unsub: () => void): void => {
+      this.unsubscribes.push(unsub);
+      disposers?.push(unsub);
+    };
+
+    reg(
+      this.deps.bus.on("vad.speech_started", (pkt) =>
+        this.onVadSpeechStarted(pkt as VadSpeechStartedPacket),
+      ),
+    );
+    reg(
+      this.deps.bus.on("vad.speech_ended", (pkt) =>
+        this.onVadSpeechEnded(pkt as VadSpeechEndedPacket),
+      ),
+    );
+    reg(
+      this.deps.bus.on("eos.turn_complete", (pkt) =>
+        this.onTurnComplete(pkt as EndOfSpeechPacket),
+      ),
+    );
+    reg(this.deps.bus.on("tts.audio", (pkt) => this.onTtsAudio(pkt as TextToSpeechAudioPacket)));
+    reg(this.deps.bus.on("tts.end", (pkt) => this.onTtsEnd(pkt as TextToSpeechEndPacket)));
+    reg(
+      this.deps.bus.on("interrupt.detected", (pkt) =>
+        this.onInterruptDetected(pkt as InterruptionDetectedPacket),
+      ),
+    );
+  }
+
+  dispose(): void {
+    for (const unsub of this.unsubscribes) unsub();
+    this.unsubscribes.length = 0;
+    this.boundaryTimes.clear();
+    this.stageDims.clear();
+    this.agentStartedEmitted.clear();
+  }
+
+  private speechId(contextId: string): string {
+    return contextId || this.deps.getContextId();
+  }
+
+  private onVadSpeechStarted(pkt: VadSpeechStartedPacket): void {
+    this.emitBoundary(this.speechId(pkt.contextId), "user_started_speaking");
+  }
+
+  private onVadSpeechEnded(pkt: VadSpeechEndedPacket): void {
+    this.emitBoundary(this.speechId(pkt.contextId), "user_stopped_speaking");
+  }
+
+  private onTurnComplete(pkt: EndOfSpeechPacket): void {
+    const provider = pkt.transcripts[0]?.provider;
+    if (provider) this.mergeStageDims(this.speechId(pkt.contextId), provider);
+    this.emitBoundary(this.speechId(pkt.contextId), "agent_thinking");
+  }
+
+  private onTtsAudio(pkt: TextToSpeechAudioPacket): void {
+    const id = pkt.contextId;
+    if (pkt.provider) this.mergeStageDims(id, pkt.provider);
+    if (this.agentStartedEmitted.has(id)) return;
+    this.agentStartedEmitted.add(id);
+    this.emitBoundary(id, "agent_started_speaking");
+  }
+
+  private onTtsEnd(pkt: TextToSpeechEndPacket): void {
+    this.emitBoundary(this.speechId(pkt.contextId), "agent_audio_done");
+  }
+
+  private onInterruptDetected(pkt: InterruptionDetectedPacket): void {
+    this.stageDims.set(this.speechId(pkt.contextId), {
+      ...this.stageDims.get(this.speechId(pkt.contextId)),
+      cancelled: true,
+    });
+    this.emitBoundary(this.speechId(pkt.contextId), "interruption", true);
+  }
+
+  private emitBoundary(speechId: string, boundary: TurnBoundaryKind, cancelled = false): void {
+    const now = monotonicNowMs();
+    let times = this.boundaryTimes.get(speechId);
+    if (!times) {
+      times = {};
+      this.boundaryTimes.set(speechId, times);
+    }
+
+    const dims = this.dimsFor(speechId, cancelled);
+    const tags = {
+      sessionId: this.deps.sessionId,
+      speechId,
+      provider: dims.provider,
+      model: dims.model,
+      region: dims.region,
+      cancelled: dims.cancelled ? "true" : "false",
+    };
+
+    if (boundary === "agent_started_speaking") {
+      const stopped = times.user_stopped_speaking;
+      if (stopped !== undefined) {
+        const delta = now - stopped;
+        if (delta >= 0) this.deps.exporter.observeHistogram("v2v_ms", delta, tags);
+      }
+      const thinking = times.agent_thinking;
+      if (thinking !== undefined) {
+        const delta = now - thinking;
+        if (delta >= 0) this.deps.exporter.observeHistogram("thinking_ms", delta, tags);
+      }
+    } else if (boundary === "agent_audio_done") {
+      const started = times.agent_started_speaking;
+      if (started !== undefined) {
+        const delta = now - started;
+        if (delta >= 0) this.deps.exporter.observeHistogram("agent_speech_ms", delta, tags);
+      }
+    }
+
+    times[boundary] = now;
+
+    this.deps.bus.push(
+      Route.Background,
+      make.turnBoundary(speechId, Date.now(), {
+        boundary,
+        sessionId: this.deps.sessionId,
+        speechId,
+        monotonicMs: now,
+        provider: dims.provider,
+        model: dims.model,
+        region: dims.region,
+        cancelled: dims.cancelled || undefined,
+      }),
+    );
+  }
+
+  private mergeStageDims(speechId: string, provider: Record<string, unknown>): void {
+    const current = this.stageDims.get(speechId) ?? {};
+    this.stageDims.set(speechId, {
+      ...current,
+      provider: readString(provider["name"], readString(provider["provider"], current.provider)),
+      model: readString(provider["model"], current.model),
+      region: readString(provider["region"], current.region),
+      cancelled: typeof provider["cancelled"] === "boolean" ? provider["cancelled"] : current.cancelled,
+    });
+  }
+
+  private dimsFor(speechId: string, cancelled: boolean): Required<ObservabilityDims> & { cancelled: boolean } {
+    const stage = this.stageDims.get(speechId) ?? {};
+    return {
+      provider: stage.provider ?? this.deps.dims.provider,
+      model: stage.model ?? this.deps.dims.model,
+      region: stage.region ?? this.deps.dims.region,
+      cancelled: cancelled || stage.cancelled === true,
+    };
+  }
+}
+
+function readString(value: unknown, fallback: string | undefined): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : fallback;
+}

package/src/observability.test.ts

@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  InMemoryMetricsExporter,
+  monotonicNowMs,
+  noopMetricsExporter,
+  reconstructTurnTimeline,
+} from "./observability.js";
+import type { TurnBoundaryEventPacket } from "./packets.js";
+
+describe("monotonicNowMs", () => {
+  it("returns increasing positive numbers", () => {
+    const first = monotonicNowMs();
+    const second = monotonicNowMs();
+    expect(first).toBeGreaterThan(0);
+    expect(second).toBeGreaterThanOrEqual(first);
+  });
+});
+
+describe("InMemoryMetricsExporter", () => {
+  it("records histogram name, value, and tags", () => {
+    const exporter = new InMemoryMetricsExporter();
+    exporter.observeHistogram("turn.latency_ms", 42, { sessionId: "s1", boundary: "agent_audio_done" });
+    expect(exporter.histograms).toEqual([
+      {
+        name: "turn.latency_ms",
+        valueMs: 42,
+        tags: { sessionId: "s1", boundary: "agent_audio_done" },
+      },
+    ]);
+  });
+
+  it("records non-negative span duration on end", () => {
+    vi.useFakeTimers();
+    const exporter = new InMemoryMetricsExporter();
+    const handle = exporter.startSpan("turn.process", { sessionId: "s1" });
+    vi.advanceTimersByTime(10);
+    handle.end();
+    expect(exporter.spans).toHaveLength(1);
+    expect(exporter.spans[0]?.durationMs).toBeGreaterThanOrEqual(0);
+    vi.useRealTimers();
+  });
+});
+
+describe("noopMetricsExporter", () => {
+  it("accepts histogram and span calls without throwing", () => {
+    noopMetricsExporter.observeHistogram("ignored", 0, {});
+    noopMetricsExporter.startSpan("ignored", {}).end();
+  });
+});
+
+describe("reconstructTurnTimeline", () => {
+  function ev(sessionId: string, speechId: string, boundary: TurnBoundaryEventPacket["boundary"], monotonicMs: number, cancelled = false): TurnBoundaryEventPacket {
+    return { kind: "obs.turn_boundary", contextId: speechId, timestampMs: 0, boundary, sessionId, speechId, monotonicMs, cancelled };
+  }
+
+  it("orders one session's boundaries by monotonic time with inter-boundary deltas", () => {
+    const events = [
+      ev("sess-A", "turn-1", "agent_started_speaking", 300),
+      ev("sess-A", "turn-1", "user_started_speaking", 100),
+      ev("sess-B", "turn-9", "user_started_speaking", 150), // other session — excluded
+      ev("sess-A", "turn-1", "user_stopped_speaking", 200),
+    ];
+    const timeline = reconstructTurnTimeline(events, "sess-A");
+    expect(timeline.map((s) => s.boundary)).toEqual([
+      "user_started_speaking",
+      "user_stopped_speaking",
+      "agent_started_speaking",
+    ]);
+    expect(timeline.map((s) => s.sincePrevMs)).toEqual([0, 100, 100]);
+    expect(timeline.every((s) => s.speechId === "turn-1")).toBe(true);
+  });
+
+  it("filters by speechId when provided and surfaces the cancelled flag", () => {
+    const events = [
+      ev("s", "t1", "user_started_speaking", 10),
+      ev("s", "t2", "interruption", 20, true),
+    ];
+    const t2 = reconstructTurnTimeline(events, "s", "t2");
+    expect(t2).toHaveLength(1);
+    expect(t2[0]!.cancelled).toBe(true);
+  });
+});

package/src/observability.ts

@@ -0,0 +1,93 @@
+// SPDX-License-Identifier: MIT
+
+import type { TurnBoundaryEventPacket } from "./packets.js";
+
+/** Monotonic clock immune to system-clock adjustments; ms since an arbitrary origin. */
+export function monotonicNowMs(): number {
+  return performance.timeOrigin + performance.now();
+}
+
+/** One step of a reconstructed turn timeline, with elapsed ms since the prior boundary. */
+export interface TurnTimelineStep {
+  readonly boundary: TurnBoundaryEventPacket["boundary"];
+  readonly speechId: string;
+  readonly monotonicMs: number;
+  /** ms since the previous boundary in this reconstruction (0 for the first). */
+  readonly sincePrevMs: number;
+  readonly cancelled: boolean;
+}
+
+/**
+ * Incident reconstruction (VE-07.5): given the `obs.turn_boundary` events for one
+ * session id, return the ordered turn timeline with inter-boundary deltas so a
+ * developer can replay what happened from a single session id.
+ */
+export function reconstructTurnTimeline(
+  events: readonly TurnBoundaryEventPacket[],
+  sessionId: string,
+  speechId?: string,
+): TurnTimelineStep[] {
+  const ordered = events
+    .filter((e) => e.sessionId === sessionId && (speechId === undefined || e.speechId === speechId))
+    .slice()
+    .sort((a, b) => a.monotonicMs - b.monotonicMs);
+  let prevMs: number | null = null;
+  return ordered.map((e) => {
+    const sincePrevMs = prevMs === null ? 0 : Math.max(0, e.monotonicMs - prevMs);
+    prevMs = e.monotonicMs;
+    return {
+      boundary: e.boundary,
+      speechId: e.speechId,
+      monotonicMs: e.monotonicMs,
+      sincePrevMs,
+      cancelled: e.cancelled === true,
+    };
+  });
+}
+
+export interface MetricTags {
+  readonly [key: string]: string;
+}
+
+export interface SpanHandle {
+  end(tags?: MetricTags): void;
+}
+
+/** Export seam — implementations (Prometheus/OTel) live in optional packages, NOT here. */
+export interface MetricsExporter {
+  observeHistogram(name: string, valueMs: number, tags: MetricTags): void;
+  startSpan(name: string, tags: MetricTags): SpanHandle;
+}
+
+/** Default no-op exporter (core never depends on a backend). */
+export const noopMetricsExporter: MetricsExporter = {
+  observeHistogram() {},
+  startSpan() {
+    return { end() {} };
+  },
+};
+
+/** In-memory exporter for tests + incident reconstruction. */
+export class InMemoryMetricsExporter implements MetricsExporter {
+  readonly histograms: Array<{ name: string; valueMs: number; tags: MetricTags }> = [];
+  readonly spans: Array<{ name: string; tags: MetricTags; durationMs?: number }> = [];
+
+  observeHistogram(name: string, valueMs: number, tags: MetricTags): void {
+    this.histograms.push({ name, valueMs, tags });
+  }
+
+  startSpan(name: string, tags: MetricTags): SpanHandle {
+    const startMs = monotonicNowMs();
+    const spanIndex = this.spans.length;
+    this.spans.push({ name, tags });
+    return {
+      end: (endTags?: MetricTags) => {
+        this.spans[spanIndex] = {
+          name,
+          tags: endTags ?? tags,
+          durationMs: monotonicNowMs() - startMs,
+        };
+      },
+    };
+  }
+}

package/src/packet-factories.test.ts

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it } from "vitest";
+
+import { reasoningResume, reasoningSuspended } from "./packet-factories.js";
+
+describe("reasoningSuspended", () => {
+  it("returns a reasoning.suspended packet with the expected shape", () => {
+    const pkt = reasoningSuspended("ctx-1", 1234, "run-1", { step: 3 }, "Pause for input.");
+
+    expect(pkt).toEqual({
+      kind: "reasoning.suspended",
+      contextId: "ctx-1",
+      timestampMs: 1234,
+      runId: "run-1",
+      prompt: "Pause for input.",
+      payload: { step: 3 },
+    });
+  });
+});
+
+describe("reasoningResume", () => {
+  it("returns a reasoning.resume packet with the expected shape", () => {
+    const pkt = reasoningResume("ctx-1", 5678, "run-1", "user answer");
+
+    expect(pkt).toEqual({
+      kind: "reasoning.resume",
+      contextId: "ctx-1",
+      timestampMs: 5678,
+      runId: "run-1",
+      data: "user answer",
+    });
+  });
+});

package/src/packet-factories.ts

@@ -0,0 +1,243 @@
+// SPDX-License-Identifier: MIT
+//
+// Syrinx Kernel v2 — Packet Factories
+//
+// Typed constructors for the packets the session orchestrator pushes onto the
+// bus. Each returns a fully-typed packet, so the shape is checked at the factory
+// definition and call sites need no `as` assertion — illegal packet shapes are
+// unrepresentable at construction instead of asserted-valid by a cast (CR-05).
+
+import { ErrorCategory } from "./packets.js";
+import type {
+  ConversationMetricPacket,
+  TurnBoundaryKind,
+  TurnBoundaryEventPacket,
+  DtmfDigit,
+  DtmfReceivedPacket,
+  RecordUserAudioPacket,
+  RecordAssistantAudioDataPacket,
+  RecordAssistantAudioTruncatePacket,
+  VadAudioPacket,
+  SpeechToTextAudioPacket,
+  EndOfSpeechAudioPacket,
+  EndOfSpeechPacket,
+  SttResultPacket,
+  UserInputPacket,
+  TextToSpeechTextPacket,
+  TextToSpeechDonePacket,
+  TtsErrorPacket,
+  InterruptionDetectedPacket,
+  InterruptionSource,
+  InterruptTtsPacket,
+  InterruptLlmPacket,
+  InterruptSttPacket,
+  InjectMessagePacket,
+  LlmDeltaPacket,
+  LlmResponseDonePacket,
+  ReasoningSuspendedPacket,
+  ReasoningResumePacket,
+  StartIdleTimeoutPacket,
+  StopIdleTimeoutPacket,
+  ModeSwitchRequestedPacket,
+} from "./packets.js";
+
+const DTMF_DIGITS = new Set<DtmfDigit>(["0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "*", "#"]);
+
+export function parseDtmfDigit(raw: string): DtmfDigit | null {
+  const trimmed = raw.trim();
+  if (trimmed.length !== 1 || !DTMF_DIGITS.has(trimmed as DtmfDigit)) return null;
+  return trimmed as DtmfDigit;
+}
+
+export function dtmfReceived(
+  contextId: string,
+  timestampMs: number,
+  digit: DtmfDigit,
+  provider: DtmfReceivedPacket["provider"],
+  rawDigit: string,
+): DtmfReceivedPacket {
+  return { kind: "dtmf.received", contextId, timestampMs, digit, provider, rawDigit };
+}
+
+export function metric(
+  contextId: string,
+  name: string,
+  value: string,
+  timestampMs: number = Date.now(),
+): ConversationMetricPacket {
+  return { kind: "metric.conversation", contextId, timestampMs, name, value };
+}
+
+export function turnBoundary(
+  contextId: string,
+  timestampMs: number,
+  fields: {
+    boundary: TurnBoundaryKind;
+    sessionId: string;
+    speechId: string;
+    monotonicMs: number;
+    provider?: string;
+    model?: string;
+    region?: string;
+    cancelled?: boolean;
+    requestId?: string;
+  },
+): TurnBoundaryEventPacket {
+  return {
+    kind: "obs.turn_boundary",
+    contextId,
+    timestampMs,
+    boundary: fields.boundary,
+    sessionId: fields.sessionId,
+    speechId: fields.speechId,
+    monotonicMs: fields.monotonicMs,
+    provider: fields.provider,
+    model: fields.model,
+    region: fields.region,
+    cancelled: fields.cancelled,
+    requestId: fields.requestId,
+  };
+}
+
+export function recordUserAudio(
+  contextId: string,
+  timestampMs: number,
+  audio: Uint8Array,
+): RecordUserAudioPacket {
+  return { kind: "record.user_audio", contextId, timestampMs, audio };
+}
+
+export function vadAudio(contextId: string, timestampMs: number, audio: Uint8Array): VadAudioPacket {
+  return { kind: "vad.audio", contextId, timestampMs, audio };
+}
+
+export function sttAudio(contextId: string, timestampMs: number, audio: Uint8Array): SpeechToTextAudioPacket {
+  return { kind: "stt.audio", contextId, timestampMs, audio };
+}
+
+export function eosAudio(contextId: string, timestampMs: number, audio: Uint8Array): EndOfSpeechAudioPacket {
+  return { kind: "eos.audio", contextId, timestampMs, audio };
+}
+
+export function eosTurnComplete(
+  contextId: string,
+  timestampMs: number,
+  text: string,
+  transcripts: readonly SttResultPacket[],
+): EndOfSpeechPacket {
+  return { kind: "eos.turn_complete", contextId, timestampMs, text, transcripts };
+}
+
+export function userInput(
+  contextId: string,
+  timestampMs: number,
+  text: string,
+  language: string,
+): UserInputPacket {
+  return { kind: "user.input", contextId, timestampMs, text, language };
+}
+
+export function ttsText(contextId: string, timestampMs: number, text: string): TextToSpeechTextPacket {
+  return { kind: "tts.text", contextId, timestampMs, text };
+}
+
+export function ttsDone(contextId: string, timestampMs: number, text: string): TextToSpeechDonePacket {
+  return { kind: "tts.done", contextId, timestampMs, text };
+}
+
+export function recordAssistantAudio(
+  contextId: string,
+  timestampMs: number,
+  audio: Uint8Array,
+  sampleRateHz: number,
+): RecordAssistantAudioDataPacket {
+  return { kind: "record.assistant_audio", contextId, timestampMs, audio, sampleRateHz, truncate: false };
+}
+
+export function recordAssistantTruncate(
+  contextId: string,
+  timestampMs: number,
+): RecordAssistantAudioTruncatePacket {
+  return { kind: "record.assistant_audio", contextId, timestampMs, audio: new Uint8Array(0), truncate: true };
+}
+
+export function interruptDetected(
+  contextId: string,
+  timestampMs: number,
+  source: InterruptionSource,
+): InterruptionDetectedPacket {
+  return { kind: "interrupt.detected", contextId, timestampMs, source };
+}
+
+export function interruptTts(contextId: string, timestampMs: number): InterruptTtsPacket {
+  return { kind: "interrupt.tts", contextId, timestampMs };
+}
+
+export function interruptLlm(contextId: string, timestampMs: number): InterruptLlmPacket {
+  return { kind: "interrupt.llm", contextId, timestampMs };
+}
+
+export function interruptStt(contextId: string, timestampMs: number): InterruptSttPacket {
+  return { kind: "interrupt.stt", contextId, timestampMs };
+}
+
+export function ttsError(
+  contextId: string,
+  timestampMs: number,
+  cause: Error,
+  category: ErrorCategory,
+  isRecoverable: boolean,
+): TtsErrorPacket {
+  return { kind: "tts.error", contextId, timestampMs, component: "tts", category, cause, isRecoverable };
+}
+
+export function injectMessage(contextId: string, timestampMs: number, text: string): InjectMessagePacket {
+  return { kind: "inject.message", contextId, timestampMs, text };
+}
+
+export function llmDelta(contextId: string, timestampMs: number, text: string): LlmDeltaPacket {
+  return { kind: "llm.delta", contextId, timestampMs, text };
+}
+
+export function llmDone(contextId: string, timestampMs: number, text: string): LlmResponseDonePacket {
+  return { kind: "llm.done", contextId, timestampMs, text };
+}
+
+export function reasoningSuspended(
+  contextId: string,
+  timestampMs: number,
+  runId: string,
+  payload: unknown,
+  prompt?: string,
+): ReasoningSuspendedPacket {
+  return { kind: "reasoning.suspended", contextId, timestampMs, runId, prompt, payload };
+}
+
+export function reasoningResume(
+  contextId: string,
+  timestampMs: number,
+  runId: string,
+  data: unknown,
+): ReasoningResumePacket {
+  return { kind: "reasoning.resume", contextId, timestampMs, runId, data };
+}
+
+export function startIdleTimeout(contextId: string, timestampMs: number): StartIdleTimeoutPacket {
+  return { kind: "behavior.idle_timeout_start", contextId, timestampMs };
+}
+
+export function stopIdleTimeout(
+  contextId: string,
+  timestampMs: number,
+  resetCount: boolean,
+): StopIdleTimeoutPacket {
+  return { kind: "behavior.idle_timeout_stop", contextId, timestampMs, resetCount };
+}
+
+export function modeSwitchRequested(
+  contextId: string,
+  timestampMs: number,
+  mode: "text" | "audio",
+): ModeSwitchRequestedPacket {
+  return { kind: "mode.switch_requested", contextId, timestampMs, mode };
+}