@kognitivedev/voice-tracing 0.2.29

package/dist/types.d.ts

@@ -0,0 +1,177 @@
+import type { KognitiveUIMessage, Metadata, ResourceId } from "@kognitivedev/shared";
+export interface VoiceTracingUsageSnapshot {
+    type: "tokens" | "seconds";
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    cachedInputTokens?: number;
+    inputAudioTokens?: number;
+    inputTextTokens?: number;
+    outputAudioTokens?: number;
+    outputTextTokens?: number;
+    cachedAudioTokens?: number;
+    cachedTextTokens?: number;
+    seconds?: number;
+}
+export type VoiceTracingTelemetryEvent = {
+    type: "voice.call.started";
+    at: string;
+    callId: string;
+    modelId: string;
+    voice: string;
+} | {
+    type: "voice.call.ended";
+    at: string;
+    callId?: string;
+    reason?: string;
+} | {
+    type: "voice.session.updated";
+    at: string;
+    callId?: string;
+    session: Record<string, unknown>;
+} | {
+    type: "voice.response.created";
+    at: string;
+    callId?: string;
+    responseId: string;
+} | {
+    type: "voice.response.output.completed";
+    at: string;
+    callId?: string;
+    responseId?: string;
+    itemId?: string;
+    outputText?: string;
+    status?: string;
+    rawEvent: Record<string, unknown>;
+} | {
+    type: "voice.response.done";
+    at: string;
+    callId?: string;
+    responseId: string;
+    status: string;
+    outputText?: string;
+    usage?: VoiceTracingUsageSnapshot;
+    rawEvent: Record<string, unknown>;
+} | {
+    type: "voice.user.transcribed";
+    at: string;
+    callId?: string;
+    itemId?: string;
+    transcript: string;
+    usage?: VoiceTracingUsageSnapshot;
+    rawEvent: Record<string, unknown>;
+} | {
+    type: "voice.assistant.started";
+    at: string;
+    callId?: string;
+    responseId?: string;
+    rawEvent: Record<string, unknown>;
+} | {
+    type: "voice.assistant.stopped";
+    at: string;
+    callId?: string;
+    responseId?: string;
+    rawEvent: Record<string, unknown>;
+} | {
+    type: "voice.tool.started";
+    at: string;
+    callId?: string;
+    responseId?: string;
+    toolCallId: string;
+    toolName: string;
+    input?: unknown;
+    rawEvent: Record<string, unknown>;
+} | {
+    type: "voice.tool.completed";
+    at: string;
+    callId?: string;
+    responseId?: string;
+    toolCallId: string;
+    toolName: string;
+    output?: unknown;
+} | {
+    type: "voice.tool.failed";
+    at: string;
+    callId?: string;
+    responseId?: string;
+    toolCallId: string;
+    toolName: string;
+    error: string;
+} | {
+    type: "voice.interrupted";
+    at: string;
+    callId?: string;
+    responseId?: string;
+    reason?: string;
+    rawEvent?: Record<string, unknown>;
+} | {
+    type: "voice.error";
+    at: string;
+    callId?: string;
+    error: string;
+    rawEvent?: Record<string, unknown>;
+} | {
+    type: "voice.raw";
+    at: string;
+    callId?: string;
+    rawEvent: Record<string, unknown>;
+};
+type VoiceTracingSessionStateShape = {
+    callId?: string;
+    messages: KognitiveUIMessage[];
+    toolInvocations: unknown[];
+    connectionStatus?: string;
+    agentState?: string;
+    speechState?: string;
+    transcriptionStatus?: string;
+};
+export type VoiceTracingSessionEvent = {
+    type: "state.updated";
+    state: VoiceTracingSessionStateShape;
+} | {
+    type: "tool-call";
+    toolCall: {
+        toolName: string;
+    };
+    state: VoiceTracingSessionStateShape;
+} | {
+    type: "tool-result";
+    toolResult: {
+        toolName: string;
+        isError?: boolean;
+    };
+    state: VoiceTracingSessionStateShape;
+} | {
+    type: "raw";
+    event: Record<string, unknown>;
+    state: VoiceTracingSessionStateShape;
+} | {
+    type: "error";
+    error: unknown;
+    state: VoiceTracingSessionStateShape;
+};
+export type PersistedConversationPart = Record<string, unknown>;
+export type PersistedConversationMessage = {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string | PersistedConversationPart[];
+    metadata?: Metadata;
+};
+export interface VoiceTracingAdapter {
+    reportAgentRun(data: Record<string, unknown>): Promise<unknown> | unknown;
+    reportConversationLog(data: Record<string, unknown>): Promise<unknown> | unknown;
+    reportTraceEvents(data: Record<string, unknown>): Promise<{
+        traceDbId?: string | null;
+    } | null>;
+}
+export interface VoiceTracingReporterConfig {
+    adapter: VoiceTracingAdapter;
+    agentName: string;
+    callId: string;
+    modelId: string;
+    transcriptionModelId?: string;
+    voice: string;
+    resourceId: ResourceId;
+    metadata?: Metadata;
+    transport?: string;
+}
+export {};

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@kognitivedev/voice-tracing",
+  "version": "0.2.29",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc -w --noCheck",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@kognitivedev/shared": "^0.2.29"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  },
+  "description": "Voice tracing adapters and reporter for Kognitive",
+  "keywords": [
+    "kognitive",
+    "voice",
+    "tracing",
+    "observability"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kognitivedev/kognitive",
+    "directory": "packages/voice-tracing"
+  },
+  "homepage": "https://kognitive.dev"
+}

package/src/__tests__/voice-tracing.test.ts

@@ -0,0 +1,341 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+    createKognitiveBackendVoiceTracingAdapter,
+    createKognitiveVoiceTracingAdapter,
+    createVoiceTracingReporter,
+} from "../index";
+
+function flushAsyncWork() {
+    return new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+function makeBaseState() {
+    return {
+        callId: "rtc_test_1",
+        messages: [] as Array<Record<string, unknown>>,
+        toolInvocations: [],
+        connectionStatus: "connected",
+        agentState: "listening",
+        micState: "ready",
+        speechState: "idle",
+        transcriptionStatus: "completed",
+    };
+}
+
+describe("@kognitivedev/voice-tracing reporter", () => {
+    it("bootstraps the session run before starting traces and carries backend ids forward", async () => {
+        const adapter = {
+            reportAgentRun: vi.fn().mockResolvedValue({
+                runDbId: "run-db-1",
+                sessionDbId: "session-db-1",
+            }),
+            reportConversationLog: vi.fn(),
+            reportTraceEvents: vi.fn().mockResolvedValue({ traceDbId: "trace-db-1" }),
+        };
+
+        const reporter = createVoiceTracingReporter({
+            adapter,
+            agentName: "voice-demo",
+            callId: "rtc_bootstrap_1",
+            modelId: "gpt-realtime-1.5",
+            transcriptionModelId: "gpt-4o-transcribe",
+            voice: "marin",
+            resourceId: { userId: "user-1" },
+            transport: "webrtc",
+        });
+
+        reporter.handleSessionEvent({
+            type: "state.updated",
+            state: {
+                ...makeBaseState(),
+                callId: "rtc_bootstrap_1",
+                messages: [
+                    {
+                        id: "user-msg-1",
+                        role: "user",
+                        parts: [{ type: "text", text: "hello" }],
+                    },
+                ],
+            },
+        });
+        await flushAsyncWork();
+
+        const firstTraceCall = adapter.reportTraceEvents.mock.calls[0]?.[0];
+        expect(adapter.reportAgentRun).toHaveBeenCalled();
+        expect(firstTraceCall).toEqual(expect.objectContaining({
+            sessionDbId: "session-db-1",
+            agentRunDbId: "run-db-1",
+            start: expect.objectContaining({
+                sessionDbId: "session-db-1",
+                agentRunDbId: "run-db-1",
+            }),
+        }));
+    });
+
+    it("normalizes voice messages for persistence and avoids placeholder trace logs", async () => {
+        const adapter = {
+            reportAgentRun: vi.fn(),
+            reportConversationLog: vi.fn(),
+            reportTraceEvents: vi.fn().mockResolvedValue({ traceDbId: "trace-db-1" }),
+        };
+
+        const reporter = createVoiceTracingReporter({
+            adapter,
+            agentName: "voice-demo",
+            callId: "rtc_test_1",
+            modelId: "gpt-realtime-1.5",
+            transcriptionModelId: "gpt-4o-transcribe",
+            voice: "marin",
+            resourceId: { userId: "user-1" },
+            transport: "webrtc",
+        });
+
+        reporter.handleSessionEvent({
+            type: "state.updated",
+            state: {
+                ...makeBaseState(),
+                messages: [
+                    {
+                        id: "user-msg-1",
+                        role: "user",
+                        parts: [{ type: "text", text: "What is the weather in Paris?" }],
+                    },
+                    {
+                        id: "assistant-msg-1",
+                        role: "assistant",
+                        parts: [
+                            { type: "text", text: "Checking that now." },
+                            { type: "tool-call", toolCallId: "tool-1", toolName: "weather-tool", input: { city: "Paris" } },
+                            { type: "tool-result", toolCallId: "tool-1", toolName: "weather-tool", result: { temperature: 22 } },
+                            { type: "text", text: "It is 22 degrees." },
+                        ],
+                    },
+                ],
+            },
+        });
+
+        await reporter.handleTelemetry({
+            type: "voice.response.done",
+            at: "2026-04-06T13:16:53.000Z",
+            callId: "rtc_test_1",
+            responseId: "resp_1",
+            status: "completed",
+            outputText: "It is 22 degrees.",
+            usage: {
+                type: "tokens",
+                inputTokens: 120,
+                outputTokens: 24,
+                totalTokens: 144,
+                cachedInputTokens: 15,
+                inputTextTokens: 20,
+                inputAudioTokens: 100,
+                cachedTextTokens: 5,
+                cachedAudioTokens: 10,
+                outputTextTokens: 4,
+                outputAudioTokens: 20,
+            },
+            rawEvent: {},
+        });
+
+        expect(adapter.reportTraceEvents).toHaveBeenCalledWith(expect.objectContaining({
+            start: expect.objectContaining({
+                traceId: expect.stringContaining("agent:voice-demo:"),
+                metadata: expect.objectContaining({ source: "voice" }),
+            }),
+        }));
+
+        const completedLogPayload = adapter.reportConversationLog.mock.calls
+            .map(([payload]) => payload)
+            .find((payload) => Array.isArray(payload?.sessionEvents) && payload.sessionEvents.some((sessionEvent: { eventType: string }) => sessionEvent.eventType === "voice.turn.completed"));
+
+        expect(completedLogPayload).toEqual(expect.objectContaining({
+            skipTraceTracking: true,
+            turnIndex: 0,
+            sessionEvents: [
+                expect.objectContaining({
+                    eventType: "voice.turn.completed",
+                    traceId: expect.stringContaining("agent:voice-demo:"),
+                }),
+            ],
+        }));
+    });
+
+    it("recovers completed turns from conversation history on disconnect", async () => {
+        const adapter = {
+            reportAgentRun: vi.fn(),
+            reportConversationLog: vi.fn(),
+            reportTraceEvents: vi.fn().mockResolvedValue({ traceDbId: "trace-db-fallback" }),
+        };
+
+        const reporter = createVoiceTracingReporter({
+            adapter,
+            agentName: "voice-demo",
+            callId: "rtc_test_fallback",
+            modelId: "gpt-realtime-1.5",
+            transcriptionModelId: "gpt-4o-transcribe",
+            voice: "marin",
+            resourceId: { userId: "user-1" },
+            transport: "webrtc",
+        });
+
+        reporter.handleSessionEvent({
+            type: "state.updated",
+            state: {
+                ...makeBaseState(),
+                callId: "rtc_test_fallback",
+                messages: [
+                    {
+                        id: "user-msg-1",
+                        role: "user",
+                        parts: [{ type: "data", data: "What is the weather in Paris right now?" }],
+                    },
+                    {
+                        id: "assistant-msg-1",
+                        role: "assistant",
+                        parts: [
+                            { type: "text", text: "Checking now." },
+                            { type: "tool-call", toolCallId: "tool-1", toolName: "weather-tool", input: { city: "Paris" } },
+                            { type: "tool-result", toolCallId: "tool-1", toolName: "weather-tool", result: { tempC: 18 } },
+                            { type: "text", text: "It is 18C." },
+                        ],
+                    },
+                ],
+            },
+        });
+
+        reporter.flushCallEnd("disconnect");
+        await flushAsyncWork();
+
+        expect(adapter.reportTraceEvents).toHaveBeenCalledWith(expect.objectContaining({
+            start: expect.objectContaining({
+                metadata: expect.objectContaining({
+                    source: "voice",
+                    synthetic: true,
+                }),
+            }),
+            finish: expect.objectContaining({
+                state: "completed",
+            }),
+        }));
+    });
+
+    it("does not replay the full transcript again on disconnect flush when nothing changed", async () => {
+        const adapter = {
+            reportAgentRun: vi.fn().mockResolvedValue({
+                runDbId: "run-db-1",
+                sessionDbId: "session-db-1",
+            }),
+            reportConversationLog: vi.fn(),
+            reportTraceEvents: vi.fn().mockResolvedValue({ traceDbId: "trace-db-1" }),
+        };
+
+        const reporter = createVoiceTracingReporter({
+            adapter,
+            agentName: "voice-demo",
+            callId: "rtc_test_flush_dedupe",
+            modelId: "gpt-realtime-1.5",
+            transcriptionModelId: "gpt-4o-transcribe",
+            voice: "marin",
+            resourceId: { userId: "user-1" },
+            transport: "webrtc",
+        });
+
+        reporter.handleSessionEvent({
+            type: "state.updated",
+            state: {
+                ...makeBaseState(),
+                callId: "rtc_test_flush_dedupe",
+                messages: [
+                    {
+                        id: "user-msg-1",
+                        role: "user",
+                        parts: [{ type: "text", text: "hello" }],
+                    },
+                    {
+                        id: "assistant-msg-1",
+                        role: "assistant",
+                        parts: [{ type: "text", text: "hi there" }],
+                    },
+                ],
+            },
+        });
+
+        await reporter.handleTelemetry({
+            type: "voice.response.done",
+            at: "2026-04-06T13:16:53.000Z",
+            callId: "rtc_test_flush_dedupe",
+            responseId: "resp_1",
+            status: "completed",
+            outputText: "hi there",
+            usage: {
+                type: "tokens",
+                inputTokens: 10,
+                outputTokens: 4,
+                totalTokens: 14,
+            },
+            rawEvent: {},
+        });
+
+        reporter.flushCallEnd("disconnect");
+        await flushAsyncWork();
+
+        const conversationLogPayloads = adapter.reportConversationLog.mock.calls.map(([payload]) => payload);
+        const payloadWithTranscript = conversationLogPayloads.find((payload) => Array.isArray(payload.messages) && payload.messages.length === 2);
+        const disconnectFlushPayload = conversationLogPayloads
+            .filter((payload) => Array.isArray(payload.sessionEvents) && payload.sessionEvents.some((event: { eventType: string }) => event.eventType === "voice.call.ended"))
+            .at(-1);
+
+        expect(payloadWithTranscript).toBeTruthy();
+        expect(disconnectFlushPayload).toEqual(expect.objectContaining({
+            messages: [],
+            sessionEvents: expect.arrayContaining([
+                expect.objectContaining({ eventType: "voice.call.ended" }),
+            ]),
+        }));
+    });
+});
+
+describe("@kognitivedev/voice-tracing adapters", () => {
+    it("posts backend payloads to the configured endpoints", async () => {
+        const fetchMock = vi.fn().mockResolvedValue({
+            ok: true,
+            json: async () => ({ traceDbId: "trace-db-1" }),
+        });
+
+        const adapter = createKognitiveBackendVoiceTracingAdapter({
+            baseUrl: "https://example.test",
+            apiKey: "secret",
+            fetch: fetchMock as unknown as typeof fetch,
+        });
+
+        adapter.reportAgentRun({ runId: "run-1" });
+        adapter.reportConversationLog({ sessionId: "session-1" });
+        const result = await adapter.reportTraceEvents({ traceId: "trace-1" });
+
+        expect(fetchMock).toHaveBeenCalledTimes(3);
+        expect(fetchMock).toHaveBeenNthCalledWith(1, "https://example.test/api/kognitive/cognitive/agent-run", expect.any(Object));
+        expect(fetchMock).toHaveBeenNthCalledWith(2, "https://example.test/api/kognitive/cognitive/log", expect.objectContaining({
+            body: JSON.stringify({ type: "voice", sessionId: "session-1" }),
+        }));
+        expect(fetchMock).toHaveBeenNthCalledWith(3, "https://example.test/api/kognitive/cognitive/trace-events", expect.any(Object));
+        expect(result).toEqual({ traceDbId: "trace-db-1" });
+    });
+
+    it("forwards through the Kognitive bridge adapter", async () => {
+        const kognitive = {
+            reportAgentRun: vi.fn(),
+            reportConversationLog: vi.fn(),
+            reportTraceEvents: vi.fn().mockResolvedValue({ traceDbId: "trace-db-kognitive" }),
+        };
+
+        const adapter = createKognitiveVoiceTracingAdapter(kognitive);
+        adapter.reportAgentRun({ runId: "run-1" });
+        adapter.reportConversationLog({ sessionId: "session-1" });
+        const result = await adapter.reportTraceEvents({ traceId: "trace-1" });
+
+        expect(kognitive.reportAgentRun).toHaveBeenCalledWith({ runId: "run-1" });
+        expect(kognitive.reportConversationLog).toHaveBeenCalledWith({ sessionId: "session-1" });
+        expect(kognitive.reportTraceEvents).toHaveBeenCalledWith({ traceId: "trace-1" });
+        expect(result).toEqual({ traceDbId: "trace-db-kognitive" });
+    });
+});

package/src/backend-adapter.ts

@@ -0,0 +1,82 @@
+import type { VoiceTracingAdapter } from "./types";
+
+type Logger = Pick<Console, "log" | "error" | "warn">;
+
+export interface KognitiveBackendVoiceTracingAdapterConfig {
+    baseUrl: string;
+    apiKey?: string;
+    getBearerToken?: () => Promise<string | null | undefined> | string | null | undefined;
+    fetch?: typeof globalThis.fetch;
+    logger?: Logger;
+    endpoints?: {
+        agentRun?: string;
+        log?: string;
+        traceEvents?: string;
+    };
+}
+
+function trimTrailingSlash(value: string): string {
+    return value.endsWith("/") ? value.slice(0, -1) : value;
+}
+
+export function createKognitiveBackendVoiceTracingAdapter(
+    config: KognitiveBackendVoiceTracingAdapterConfig,
+): VoiceTracingAdapter {
+    const fetchImpl = config.fetch ?? globalThis.fetch;
+    const logger = config.logger;
+    const baseUrl = trimTrailingSlash(config.baseUrl);
+    const endpoints = {
+        agentRun: config.endpoints?.agentRun ?? "/api/kognitive/cognitive/agent-run",
+        log: config.endpoints?.log ?? "/api/kognitive/cognitive/log",
+        traceEvents: config.endpoints?.traceEvents ?? "/api/kognitive/cognitive/trace-events",
+    };
+
+    const post = async (endpoint: string, payload: Record<string, unknown>) => {
+        try {
+            const bearerToken = await config.getBearerToken?.();
+            const response = await fetchImpl(`${baseUrl}${endpoint}`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    ...(bearerToken || config.apiKey
+                        ? { Authorization: `Bearer ${bearerToken ?? config.apiKey}` }
+                        : {}),
+                },
+                body: JSON.stringify(payload),
+            });
+
+            if (!response.ok) {
+                const errorText = await response.text().catch(() => "");
+                logger?.warn?.("[VoiceTracing:backend-adapter] request failed", {
+                    endpoint,
+                    status: response.status,
+                    body: errorText.slice(0, 400),
+                });
+                return null;
+            }
+
+            return await response.json().catch(() => null);
+        } catch (error) {
+            logger?.error?.("[VoiceTracing:backend-adapter] request error", {
+                endpoint,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return null;
+        }
+    };
+
+    return {
+        async reportAgentRun(data) {
+            return await post(endpoints.agentRun, data);
+        },
+        async reportConversationLog(data) {
+            return await post(endpoints.log, {
+                type: "voice",
+                ...data,
+            });
+        },
+        async reportTraceEvents(data) {
+            return await post(endpoints.traceEvents, data) as { traceDbId?: string | null } | null;
+        },
+    };
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+export type {
+    VoiceTracingAdapter,
+    VoiceTracingReporterConfig,
+    VoiceTracingSessionEvent,
+    VoiceTracingTelemetryEvent,
+    VoiceTracingUsageSnapshot,
+    PersistedConversationMessage,
+} from "./types";
+
+export { createVoiceTracingReporter, createVoiceTelemetryReporter } from "./reporter";
+export { createKognitiveBackendVoiceTracingAdapter } from "./backend-adapter";
+export { createKognitiveVoiceTracingAdapter } from "./kognitive-adapter";

package/src/kognitive-adapter.ts

@@ -0,0 +1,22 @@
+import type { VoiceTracingAdapter } from "./types";
+
+type KognitiveLike = {
+    reportAgentRun(data: Record<string, unknown>): Promise<unknown> | unknown;
+    reportConversationLog(data: Record<string, unknown>): Promise<unknown> | unknown;
+    reportTraceEvents(data: Record<string, unknown>): Promise<unknown> | unknown;
+};
+
+export function createKognitiveVoiceTracingAdapter(kognitive: KognitiveLike): VoiceTracingAdapter {
+    return {
+        async reportAgentRun(data) {
+            return await kognitive.reportAgentRun(data);
+        },
+        async reportConversationLog(data) {
+            return await kognitive.reportConversationLog(data);
+        },
+        async reportTraceEvents(data) {
+            const result = await kognitive.reportTraceEvents(data);
+            return (result ?? null) as { traceDbId?: string | null } | null;
+        },
+    };
+}