@oscharko-dev/keiko-server 0.2.7 → 0.2.9

package/dist/voice-realtime-grounded-tool.js

@@ -0,0 +1,322 @@
+import { resolveVoiceCapability, } from "@oscharko-dev/keiko-model-gateway";
+import { stripUnsafeFormatChars } from "@oscharko-dev/keiko-contracts/text-safety";
+import { validateProjectPath } from "./store/validation.js";
+import { currentGatewayConfig } from "./deps.js";
+import { errorBody } from "./routes.js";
+import { isVoiceDisabledByPolicy } from "./read-handlers.js";
+import { buildVoiceTurnMemoryResult, desktopChatErrorResult, parseMemoryRequest, } from "./chat-handlers.js";
+import { resolveConversationMemoryContext } from "./memory-conversation-context.js";
+import { runGroundedAskInput } from "./grounded-qa.js";
+const MAX_BODY_BYTES = 128_000;
+const MAX_TEXT_CHARS = 16_000;
+const MAX_CALL_ID_CHARS = 200;
+const MAX_CACHE_ENTRIES = 128;
+const SAFE_CALL_ID = /^[\x21-\x7e]+$/;
+class BodyTooLargeError extends Error {
+    constructor() {
+        super("body too large");
+        this.name = "BodyTooLargeError";
+    }
+}
+const responseCache = new Map();
+const responseInFlight = new Map();
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let total = 0;
+        let capped = false;
+        req.on("data", (chunk) => {
+            total += chunk.length;
+            if (total > MAX_BODY_BYTES) {
+                if (!capped) {
+                    capped = true;
+                    chunks.length = 0;
+                    reject(new BodyTooLargeError());
+                    req.resume();
+                }
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => {
+            if (!capped)
+                resolve(Buffer.concat(chunks).toString("utf8"));
+        });
+        req.on("error", reject);
+    });
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isRouteResult(value) {
+    return isRecord(value) && typeof value.status === "number" && "body" in value;
+}
+async function readJsonObject(req) {
+    let raw;
+    try {
+        raw = await readBody(req);
+    }
+    catch (error) {
+        if (error instanceof BodyTooLargeError) {
+            return {
+                status: 413,
+                body: errorBody("PAYLOAD_TOO_LARGE", "Request body exceeds the size limit."),
+            };
+        }
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = raw.length === 0 ? {} : JSON.parse(raw);
+    }
+    catch {
+        return { status: 400, body: errorBody("BAD_REQUEST", "Request body is not valid JSON.") };
+    }
+    if (!isRecord(parsed)) {
+        return { status: 400, body: errorBody("BAD_REQUEST", "Request body must be a JSON object.") };
+    }
+    return parsed;
+}
+function readRequiredString(body, key, maxChars = MAX_TEXT_CHARS) {
+    const value = typeof body[key] === "string" ? body[key].trim() : "";
+    if (value.length === 0 || value.length > maxChars) {
+        return {
+            status: 400,
+            body: errorBody("BAD_REQUEST", `${key} must be a non-empty bounded string.`),
+        };
+    }
+    return value;
+}
+function readOptionalText(body, key) {
+    if (body[key] === undefined)
+        return undefined;
+    if (typeof body[key] !== "string") {
+        return { status: 400, body: errorBody("BAD_REQUEST", `${key} must be a string when provided.`) };
+    }
+    const value = body[key].trim();
+    if (value.length === 0 || value.length > MAX_TEXT_CHARS) {
+        return {
+            status: 400,
+            body: errorBody("BAD_REQUEST", `${key} must be a non-empty bounded string when provided.`),
+        };
+    }
+    return value;
+}
+function parseRequest(body) {
+    const chatId = readRequiredString(body, "chatId", MAX_CALL_ID_CHARS);
+    if (isRouteResult(chatId))
+        return chatId;
+    const projectPath = readRequiredString(body, "projectPath");
+    if (isRouteResult(projectPath))
+        return projectPath;
+    const callId = readRequiredString(body, "callId", MAX_CALL_ID_CHARS);
+    if (isRouteResult(callId))
+        return callId;
+    if (!SAFE_CALL_ID.test(callId)) {
+        return { status: 400, body: errorBody("BAD_REQUEST", "callId contains invalid characters.") };
+    }
+    const query = readRequiredString(body, "query");
+    if (isRouteResult(query))
+        return query;
+    const userTranscript = readOptionalText(body, "userTranscript");
+    if (isRouteResult(userTranscript))
+        return userTranscript;
+    const modelId = readOptionalText(body, "modelId");
+    if (isRouteResult(modelId))
+        return modelId;
+    const memory = parseMemoryRequest(body.memory);
+    if (isRouteResult(memory))
+        return memory;
+    return { chatId, projectPath, callId, query, userTranscript, modelId, memory };
+}
+function normalizeText(text) {
+    return text.replace(/\s+/gu, " ").trim().toLowerCase();
+}
+function cacheKey(request) {
+    return `${request.chatId}:${request.callId}:${normalizeText(request.query)}`;
+}
+function rememberResponse(key, response) {
+    responseCache.set(key, response);
+    while (responseCache.size > MAX_CACHE_ENTRIES) {
+        const first = responseCache.keys().next().value;
+        if (first === undefined)
+            return;
+        responseCache.delete(first);
+    }
+}
+function realtimeGroundedVoiceAvailable(resolution) {
+    return (resolution.available &&
+        resolution.profile === "full-realtime" &&
+        resolution.capabilities.realtimeVoice &&
+        resolution.transport.webrtcMedia);
+}
+function validateVoiceToolCapability(deps) {
+    const resolution = resolveVoiceCapability(currentGatewayConfig(deps) ?? { providers: [] }, {
+        policyDisabled: isVoiceDisabledByPolicy(deps.env),
+    });
+    if (realtimeGroundedVoiceAvailable(resolution)) {
+        return undefined;
+    }
+    return {
+        status: 403,
+        body: errorBody("VOICE_TOOL_UNAVAILABLE", "Realtime grounded voice is not available for this deployment."),
+    };
+}
+function normalizeProjectPath(projectPath, deps) {
+    try {
+        return validateProjectPath(projectPath, { mustExist: false });
+    }
+    catch (error) {
+        return desktopChatErrorResult(error, deps);
+    }
+}
+function findValidatedChat(deps, projectPath, chatId) {
+    const chat = deps.store.findChatById(chatId);
+    if (chat?.projectPath !== projectPath) {
+        return { status: 404, body: errorBody("NOT_FOUND", "Chat not found.") };
+    }
+    return chat;
+}
+function citationMarker(index, citation) {
+    return citation.marker !== undefined ? `[${String(citation.marker)}]` : `[${String(index + 1)}]`;
+}
+function summarizeFolderCitation(citation, index) {
+    return {
+        marker: citationMarker(index, citation),
+        label: citation.scopePath,
+        ...(citation.source !== undefined ? { source: citation.source } : {}),
+    };
+}
+function summarizeKnowledgeCitation(citation) {
+    return {
+        marker: citation.marker,
+        label: citation.label,
+        ...(citation.source !== undefined ? { source: citation.source } : {}),
+    };
+}
+function summarizeCitations(answer) {
+    if (answer.groundingKind === "local-knowledge") {
+        return answer.citations.slice(0, 8).map(summarizeKnowledgeCitation);
+    }
+    const folder = answer.citations.slice(0, 8).map(summarizeFolderCitation);
+    if (answer.groundingKind === "hybrid") {
+        return [...folder, ...answer.knowledgeCitations.slice(0, 8).map(summarizeKnowledgeCitation)];
+    }
+    return folder;
+}
+function buildToolOutput(answer) {
+    return {
+        status: "ok",
+        answer: answer.content,
+        groundingKind: answer.groundingKind,
+        elapsedMs: answer.elapsedMs,
+        citations: summarizeCitations(answer),
+        ...(answer.evidenceRunId !== undefined ? { evidenceRunId: answer.evidenceRunId } : {}),
+        persisted: {
+            userMessageId: answer.userMessageId,
+            assistantMessageId: answer.assistantMessageId,
+        },
+        instruction: "Speak this answer faithfully in a concise voice-friendly way. Do not add facts that are not in the answer.",
+    };
+}
+function isGroundedAnswer(value) {
+    return (isRecord(value) &&
+        (value.groundingKind === "connected-context" ||
+            value.groundingKind === "local-knowledge" ||
+            value.groundingKind === "hybrid") &&
+        typeof value.userMessageId === "string" &&
+        typeof value.assistantMessageId === "string" &&
+        typeof value.content === "string");
+}
+function messagesForAnswer(deps, answer) {
+    const user = deps.store.findMessageById(answer.userMessageId);
+    const assistant = deps.store.findMessageById(answer.assistantMessageId);
+    if (user === undefined || assistant === undefined) {
+        return {
+            status: 500,
+            body: errorBody("INTERNAL", "Grounded voice turn was not persisted correctly."),
+        };
+    }
+    return [user, assistant];
+}
+async function buildMemory(deps, request, projectPath, chat, messages) {
+    if (request.memory === undefined)
+        return undefined;
+    const memoryContext = resolveConversationMemoryContext(deps, projectPath, request.chatId);
+    if (isRouteResult(memoryContext))
+        return memoryContext;
+    return buildVoiceTurnMemoryResult(deps, {
+        chatId: request.chatId,
+        projectPath,
+        messages: messages.map((message) => ({
+            role: message.role === "assistant" ? "assistant" : "user",
+            content: message.content,
+            timestamp: message.timestamp,
+        })),
+        memory: request.memory,
+    }, chat, memoryContext);
+}
+async function buildRealtimeGroundedToolResponse(deps, request, projectPath, chat) {
+    const content = stripUnsafeFormatChars(request.userTranscript ?? request.query).trim();
+    const grounded = await runGroundedAskInput({
+        chatId: request.chatId,
+        content,
+        modelId: request.modelId,
+    }, deps);
+    if (grounded.status !== 200)
+        return grounded;
+    if (!isGroundedAnswer(grounded.body)) {
+        return { status: 500, body: errorBody("INTERNAL", "Grounded voice tool returned no answer.") };
+    }
+    const answer = grounded.body;
+    const messages = messagesForAnswer(deps, answer);
+    if (isRouteResult(messages))
+        return messages;
+    const updatedChat = deps.store.findChatById(request.chatId) ?? chat;
+    const memory = await buildMemory(deps, request, projectPath, updatedChat, messages);
+    if (isRouteResult(memory))
+        return memory;
+    return {
+        chat: updatedChat,
+        messages,
+        groundedAnswer: answer,
+        toolOutput: buildToolOutput(answer),
+        ...(memory === undefined ? {} : { memory }),
+    };
+}
+export async function handleRealtimeGroundedVoiceTool(ctx, deps) {
+    const body = await readJsonObject(ctx.req);
+    if (isRouteResult(body))
+        return body;
+    const request = parseRequest(body);
+    if (isRouteResult(request))
+        return request;
+    const key = cacheKey(request);
+    const cached = responseCache.get(key);
+    if (cached !== undefined) {
+        return { status: 200, body: cached };
+    }
+    const capability = validateVoiceToolCapability(deps);
+    if (capability !== undefined)
+        return capability;
+    const projectPath = normalizeProjectPath(request.projectPath, deps);
+    if (isRouteResult(projectPath))
+        return projectPath;
+    const chat = findValidatedChat(deps, projectPath, request.chatId);
+    if (isRouteResult(chat))
+        return chat;
+    const inFlight = responseInFlight.get(key);
+    if (inFlight !== undefined) {
+        const result = await inFlight;
+        return isRouteResult(result) ? result : { status: 200, body: result };
+    }
+    const responsePromise = buildRealtimeGroundedToolResponse(deps, request, projectPath, chat);
+    responseInFlight.set(key, responsePromise);
+    const response = await responsePromise.finally(() => {
+        responseInFlight.delete(key);
+    });
+    if (isRouteResult(response))
+        return response;
+    rememberResponse(key, response);
+    return { status: 200, body: response };
+}

package/dist/voice-realtime.d.ts

@@ -0,0 +1,69 @@
+import type { IncomingMessage } from "node:http";
+import type { Duplex } from "node:stream";
+import { type RealtimeNegotiationOutcome } from "@oscharko-dev/keiko-model-gateway";
+import { type VoiceControlMessage, type VoicePersona, type VoiceProfile, type VoiceProviderLocality, type VoiceSessionChatContext } from "@oscharko-dev/keiko-contracts";
+import { type UiHandlerDeps } from "./deps.js";
+export declare const VOICE_CONTROL_PATH = "/api/voice/control";
+interface SessionState {
+    readonly sessionId: string;
+    readonly idempotencyKey: string;
+    readonly profile: VoiceProfile;
+    readonly providerLocality: VoiceProviderLocality | undefined;
+    readonly persona: VoicePersona | undefined;
+    readonly chatContext: VoiceSessionChatContext | undefined;
+    hostSeq: number;
+    lastClientSeq: number;
+    readonly replay: VoiceControlMessage[];
+    detachedAt: number | undefined;
+}
+type NegotiateFn = (offerSdp: string, persona: VoicePersona | undefined, chatContext: VoiceSessionChatContext | undefined, signal: AbortSignal) => Promise<RealtimeNegotiationOutcome>;
+export interface VoiceControlPlane {
+    handleUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer): boolean;
+    closeAll(): void;
+}
+export interface VoiceControlSocket {
+    send(data: string): void;
+    close(code: number, reason: string): void;
+}
+export interface VoiceControlConnectionOptions {
+    readonly socket: VoiceControlSocket;
+    readonly session: SessionState;
+    readonly negotiate: NegotiateFn;
+    readonly redact: (value: unknown) => unknown;
+}
+export declare class VoiceControlConnection {
+    private readonly socket;
+    private readonly session;
+    private readonly negotiate;
+    private readonly redact;
+    private negotiation;
+    private closed;
+    constructor(options: VoiceControlConnectionOptions);
+    start(resume: boolean): void;
+    receive(raw: string): Promise<void>;
+    dispose(): void;
+    private dispatchIn;
+    private cancelNegotiation;
+    private handleOffer;
+    private recordTranscript;
+    private emitError;
+    private build;
+    private emit;
+    private record;
+    private dispatchOut;
+    private fail;
+    private shutdown;
+}
+export interface VoiceControlPlaneDeps {
+    readonly port: number;
+    readonly handlerDeps: () => UiHandlerDeps;
+}
+export interface AliveControlSocket {
+    isAlive?: boolean;
+    ping(): void;
+    terminate(): void;
+}
+export declare function sweepControlHeartbeat(sockets: Iterable<AliveControlSocket>): void;
+export declare function createVoiceControlPlane(planeDeps: VoiceControlPlaneDeps): VoiceControlPlane;
+export {};
+//# sourceMappingURL=voice-realtime.d.ts.map

package/dist/voice-realtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice-realtime.d.ts","sourceRoot":"","sources":["../src/voice-realtime.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,EASL,KAAK,0BAA0B,EAGhC,MAAM,mCAAmC,CAAC;AAE3C,OAAO,EASL,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,KAAK,YAAY,EAEjB,KAAK,qBAAqB,EAE1B,KAAK,uBAAuB,EAE7B,MAAM,+BAA+B,CAAC;AAGvC,OAAO,EAAoD,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAUjG,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AAgFvD,UAAU,YAAY;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,gBAAgB,EAAE,qBAAqB,GAAG,SAAS,CAAC;IAG7D,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,WAAW,EAAE,uBAAuB,GAAG,SAAS,CAAC;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,mBAAmB,EAAE,CAAC;IACvC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAED,KAAK,WAAW,GAAG,CACjB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,YAAY,GAAG,SAAS,EACjC,WAAW,EAAE,uBAAuB,GAAG,SAAS,EAChD,MAAM,EAAE,WAAW,KAChB,OAAO,CAAC,0BAA0B,CAAC,CAAC;AAUzC,MAAM,WAAW,iBAAiB;IAIhC,aAAa,CAAC,GAAG,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAE3E,QAAQ,IAAI,IAAI,CAAC;CAClB;AAqOD,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3C;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;CAC9C;AAMD,qBAAa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IACxC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8B;IACrD,OAAO,CAAC,WAAW,CAA8B;IACjD,OAAO,CAAC,MAAM,CAAS;gBAEX,OAAO,EAAE,6BAA6B;IAUlD,KAAK,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI;IAuBtB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsCzC,OAAO,IAAI,IAAI;YAMD,UAAU;IAuCxB,OAAO,CAAC,iBAAiB;YAKX,WAAW;IA2CzB,OAAO,CAAC,gBAAgB;IAYxB,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,KAAK;IAmBb,OAAO,CAAC,IAAI;IAOZ,OAAO,CAAC,MAAM;IAId,OAAO,CAAC,WAAW;IAWnB,OAAO,CAAC,IAAI;IAKZ,OAAO,CAAC,QAAQ;CAajB;AA6BD,MAAM,WAAW,qBAAqB;IAEpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAGtB,QAAQ,CAAC,WAAW,EAAE,MAAM,aAAa,CAAC;CAC3C;AAQD,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,IAAI,IAAI,CAAC;IACb,SAAS,IAAI,IAAI,CAAC;CACnB;AAMD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,QAAQ,CAAC,kBAAkB,CAAC,GAAG,IAAI,CASjF;AAkSD,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,qBAAqB,GAAG,iBAAiB,CAE3F"}