@oscharko-dev/keiko-server 0.2.0

package/dist/browser.js

@@ -0,0 +1,245 @@
+// ADR-0017 D8 — eight /api/browser/* BFF route handlers. CSRF guarding is enforced by the
+// server.ts state-changing-request gate (POST/DELETE all flow through it). GET status + GET
+// events are exempt by the same gate. SSE framing reuses the existing sse.ts helpers.
+import { BrowserToolError, } from "@oscharko-dev/keiko-tools";
+import { SSE_HEADERS, readyMessage } from "./sse.js";
+import { errorBody, STREAMING, } from "./routes.js";
+const MAX_BROWSER_BODY_BYTES = 64_000;
+class BodyTooLargeError extends Error {
+    constructor() {
+        super("browser request body too large");
+        this.name = "BodyTooLargeError";
+    }
+}
+function noBrowserDeps() {
+    return {
+        status: 503,
+        body: errorBody("BROWSER_UNAVAILABLE", "Browser tool is not configured for this BFF."),
+    };
+}
+function requireBrowser(deps) {
+    return deps.browser ?? noBrowserDeps();
+}
+function isRouteResult(value) {
+    return typeof value.status === "number";
+}
+function toRouteResult(error) {
+    return { status: error.status, body: errorBody(error.code, error.message) };
+}
+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_BROWSER_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);
+    });
+}
+async function readJsonObject(req) {
+    const raw = await readBody(req);
+    if (raw.length === 0)
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new BrowserToolError("BAD_REQUEST", "Request body is not valid JSON.");
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new BrowserToolError("BAD_REQUEST", "Request body must be a JSON object.");
+    }
+    return parsed;
+}
+function requireString(body, key) {
+    const value = body[key];
+    if (typeof value !== "string" || value.length === 0) {
+        throw new BrowserToolError("BAD_REQUEST", `Field "${key}" must be a non-empty string.`);
+    }
+    return value;
+}
+function requireNumber(body, key) {
+    const value = body[key];
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new BrowserToolError("BAD_REQUEST", `Field "${key}" must be a finite number.`);
+    }
+    return value;
+}
+async function runHandler(work) {
+    try {
+        return await work();
+    }
+    catch (error) {
+        if (error instanceof BodyTooLargeError) {
+            return {
+                status: 413,
+                body: errorBody("PAYLOAD_TOO_LARGE", "Request body exceeds the size limit."),
+            };
+        }
+        if (error instanceof BrowserToolError)
+            return toRouteResult(error);
+        throw error;
+    }
+}
+const UNREACHABLE_BODY = {
+    reachable: false,
+    userAgent: null,
+    browserVersion: null,
+    webSocketDebuggerUrl: null,
+};
+export async function handleBrowserStatus(ctx, deps) {
+    const guard = requireBrowser(deps);
+    if (isRouteResult(guard))
+        return guard;
+    return runHandler(async () => {
+        const portParam = ctx.url.searchParams.get("port");
+        if (portParam === null) {
+            throw new BrowserToolError("BAD_REQUEST", "Query parameter 'port' is required.");
+        }
+        const port = Number.parseInt(portParam, 10);
+        if (!Number.isFinite(port)) {
+            throw new BrowserToolError("BAD_REQUEST", "Query parameter 'port' must be an integer.");
+        }
+        try {
+            const status = await guard.checkStatus(port);
+            return { status: 200, body: status };
+        }
+        catch (err) {
+            if (err instanceof BrowserToolError && err.code === "CHROME_UNREACHABLE") {
+                return { status: 200, body: UNREACHABLE_BODY };
+            }
+            throw err;
+        }
+    });
+}
+export async function handleCreateBrowserSession(ctx, deps) {
+    const guard = requireBrowser(deps);
+    if (isRouteResult(guard))
+        return guard;
+    return runHandler(async () => {
+        const body = await readJsonObject(ctx.req);
+        const port = requireNumber(body, "port");
+        const meta = await guard.openSession(port);
+        return { status: 201, body: meta };
+    });
+}
+export async function handleDeleteBrowserSession(ctx, deps) {
+    const guard = requireBrowser(deps);
+    if (isRouteResult(guard))
+        return guard;
+    return runHandler(async () => {
+        const sessionId = ctx.params.sessionId ?? "";
+        await guard.closeSession(sessionId);
+        return { status: 200, body: { ok: true } };
+    });
+}
+export async function handleBrowserNavigate(ctx, deps) {
+    const guard = requireBrowser(deps);
+    if (isRouteResult(guard))
+        return guard;
+    return runHandler(async () => {
+        const body = await readJsonObject(ctx.req);
+        const url = requireString(body, "url");
+        const sessionId = ctx.params.sessionId ?? "";
+        const result = await guard.navigate(sessionId, url);
+        return { status: 200, body: result };
+    });
+}
+export async function handleBrowserScreenshot(ctx, deps) {
+    const guard = requireBrowser(deps);
+    if (isRouteResult(guard))
+        return guard;
+    return runHandler(async () => {
+        // Drain the body through readJsonObject so the 64 KB cap (MAX_BROWSER_BODY_BYTES) is
+        // enforced even though this handler expects no fields. Raw node:http has no global cap.
+        await readJsonObject(ctx.req);
+        const sessionId = ctx.params.sessionId ?? "";
+        const result = await guard.screenshot(sessionId);
+        return { status: 200, body: result };
+    });
+}
+export async function handleBrowserApplyScreenshot(ctx, deps) {
+    const guard = requireBrowser(deps);
+    if (isRouteResult(guard))
+        return guard;
+    return runHandler(async () => {
+        const body = await readJsonObject(ctx.req);
+        const captureSeq = requireNumber(body, "captureSeq");
+        const sessionId = ctx.params.sessionId ?? "";
+        const result = await guard.applyScreenshot(sessionId, captureSeq);
+        return { status: 200, body: result };
+    });
+}
+export async function handleBrowserContent(ctx, deps) {
+    const guard = requireBrowser(deps);
+    if (isRouteResult(guard))
+        return guard;
+    return runHandler(async () => {
+        // Drain the body through readJsonObject so the 64 KB cap (MAX_BROWSER_BODY_BYTES) is
+        // enforced even though this handler expects no fields. Raw node:http has no global cap.
+        await readJsonObject(ctx.req);
+        const sessionId = ctx.params.sessionId ?? "";
+        const result = await guard.content(sessionId);
+        return { status: 200, body: result };
+    });
+}
+// SSE — re-uses the existing framer shape. Each browser event becomes one SSE message with
+// event: <kind> and data: <JSON>. A 'ready' synthetic is sent first so clients can transition
+// from connecting to live.
+export function handleBrowserEvents(ctx, deps) {
+    const guard = requireBrowser(deps);
+    if (isRouteResult(guard))
+        return guard;
+    const sessionId = ctx.params.sessionId ?? "";
+    if (sessionId.length === 0) {
+        return { status: 400, body: errorBody("BAD_REQUEST", "sessionId is required.") };
+    }
+    if (!guard.hasSession(sessionId)) {
+        return { status: 404, body: errorBody("SESSION_NOT_FOUND", "Browser session not found.") };
+    }
+    openBrowserSseStream(ctx.res, guard, sessionId, deps.redactor);
+    ctx.req.on("close", () => {
+        ctx.res.end();
+    });
+    return STREAMING;
+}
+function openBrowserSseStream(res, manager, sessionId, redactor) {
+    res.writeHead(200, SSE_HEADERS);
+    let seq = 0;
+    const unsubscribe = manager.subscribe(sessionId, (event) => {
+        seq += 1;
+        writeBrowserEvent(res, event, seq, redactor);
+        if (event.kind === "session-closed") {
+            unsubscribe();
+            res.end();
+        }
+    });
+    res.write(readyMessage());
+    res.on("close", () => {
+        unsubscribe();
+    });
+}
+function writeBrowserEvent(res, event, seq, redactor) {
+    const redacted = redactor(event);
+    const data = JSON.stringify(redacted);
+    const frame = `id: ${String(seq)}\nevent: browser:${event.kind}\ndata: ${data}\n\n`;
+    if (!res.write(frame)) {
+        res.destroy();
+    }
+}

package/dist/chat-handlers.d.ts

@@ -0,0 +1,48 @@
+import type { ConversationDocumentContextWire } from "@oscharko-dev/keiko-contracts";
+import type { ConversationMemoryActionWire, ConversationMemoryResultWire } from "@oscharko-dev/keiko-contracts/bff-wire";
+import { type Chat, type ChatMessage } from "./store/index.js";
+import { type ConversationAttachment } from "./conversation-validation.js";
+import type { UiHandlerDeps } from "./deps.js";
+import type { RouteContext, RouteResult } from "./routes.js";
+import { type ConversationMemoryRuntimeContext } from "./memory-conversation-context.js";
+export interface GatewayConversationMessage {
+    readonly role: "system" | "user" | "assistant";
+    readonly content: string;
+}
+export declare function redactErrorMessage(message: string, deps: UiHandlerDeps): string;
+export declare function desktopChatErrorResult(error: unknown, deps: UiHandlerDeps): RouteResult;
+export interface SendDesktopChatRequest {
+    readonly chatId: string;
+    readonly projectPath: string;
+    readonly content: string;
+    readonly modelId: string | undefined;
+    readonly documentContext: readonly ConversationDocumentContextWire[];
+    readonly attachments: readonly ConversationAttachment[];
+    readonly memory: ParsedConversationMemoryRequest | undefined;
+}
+interface ParsedConversationMemoryRequest {
+    readonly enabled: boolean;
+    readonly budgetTokens?: number;
+    readonly context: Record<string, unknown>;
+}
+export declare function createUserMessage(deps: UiHandlerDeps, request: SendDesktopChatRequest): ChatMessage;
+export declare function createAssistantMessage(deps: UiHandlerDeps, request: SendDesktopChatRequest, content: string, modelId: string): ChatMessage;
+export declare function emptyMemoryResult(enabled: boolean): ConversationMemoryResultWire;
+export declare function buildMemoryResult(request: SendDesktopChatRequest, deps: UiHandlerDeps, context: ConversationMemoryRuntimeContext): Promise<ConversationMemoryResultWire>;
+export declare function collectMemoryActions(deps: UiHandlerDeps, request: SendDesktopChatRequest, memoryContext: ConversationMemoryRuntimeContext | undefined, modelId: string, assistantText: string): Promise<readonly ConversationMemoryActionWire[]>;
+export declare function buildChatPatch(chat: Chat, request: SendDesktopChatRequest, modelId: string): {
+    selectedModel: string;
+    title?: string;
+};
+export declare function buildGatewayMessages(deps: UiHandlerDeps, request: SendDesktopChatRequest, memoryText: string): GatewayConversationMessage[];
+export declare function handleCreateDesktopChat(ctx: RouteContext, deps: UiHandlerDeps): Promise<RouteResult>;
+export interface PreparedDesktopChatSend {
+    readonly request: SendDesktopChatRequest;
+    readonly chat: Chat;
+    readonly modelId: string;
+    readonly memoryContext: ConversationMemoryRuntimeContext | undefined;
+}
+export declare function prepareDesktopChatSend(ctx: RouteContext, deps: UiHandlerDeps): Promise<PreparedDesktopChatSend | RouteResult>;
+export declare function handleSendDesktopChat(ctx: RouteContext, deps: UiHandlerDeps): Promise<RouteResult>;
+export {};
+//# sourceMappingURL=chat-handlers.d.ts.map

package/dist/chat-handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-handlers.d.ts","sourceRoot":"","sources":["../src/chat-handlers.ts"],"names":[],"mappings":"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"}