@oscharko-dev/keiko 0.1.0-beta.0

package/dist/ui/read-handlers.js

@@ -0,0 +1,247 @@
+// The six read-only BFF endpoints (ADR-0011 D5 routes 2,3,4,10,11,12). Each returns a redacted JSON
+// projection of already-safe data: config via `toSafeObject` (strips apiKey), the full capability
+// registry, the workflow launch-form descriptors, the workspace summary built from the workspace
+// layer, and evidence list/detail served straight from the store (manifests are redacted-by-
+// construction on disk, served as-is per D9). No secret reaches any response; the config route
+// never leaks the config path even on a load failure (handled upstream in deps.ts, which yields
+// `config: undefined` rather than throwing).
+import { toSafeObject, listCapabilities } from "../gateway/index.js";
+import { UNIT_TEST_WORKFLOW_DESCRIPTOR, BUG_INVESTIGATION_WORKFLOW_DESCRIPTOR, } from "../workflows/index.js";
+import { DEFAULT_LIMITS } from "../harness/index.js";
+import { listEvidence, loadEvidence, assertValidRunId, EvidenceReadError, EvidenceSchemaError, } from "../audit/index.js";
+import { buildContextPackFromFiles, buildWorkspaceSummary, DEFAULT_CONTEXT_REQUEST, detectWorkspace, discoverWithStats, WORKSPACE_CODES, WorkspaceError, } from "../workspace/index.js";
+import { errorBody } from "./routes.js";
+import { validateProjectPath } from "./store/validation.js";
+// Route 2 — resolved config (SafeGatewayConfig, never apiKey/baseUrl) or null when no config was resolved.
+export function handleConfig(_ctx, deps) {
+    const config = deps.config === undefined ? null : toSafeObject(deps.config);
+    return { status: 200, body: { config, configPresent: deps.configPresent } };
+}
+// Route 3 — models published by the resolved UI gateway config. If no config is resolved, no
+// model-backed run can start, so the endpoint returns an empty list.
+export function handleModels(_ctx, deps) {
+    const configured = new Set(deps.config?.providers.map((provider) => provider.modelId) ?? []);
+    const models = listCapabilities().filter((model) => configured.has(model.id));
+    return { status: 200, body: { models } };
+}
+// Route 4 — launch-form metadata: the workflow descriptors plus the synthesized explain-plan and
+// verify inputs (both are harness tasks with no workflow descriptor — verify is BFF-only and runs
+// the deterministic verification orchestrator).
+export function handleWorkflows() {
+    return {
+        status: 200,
+        body: {
+            descriptors: [UNIT_TEST_WORKFLOW_DESCRIPTOR, BUG_INVESTIGATION_WORKFLOW_DESCRIPTOR],
+            explainPlan: {
+                inputs: [
+                    {
+                        name: "filePath",
+                        type: "string",
+                        required: true,
+                        description: "Path to the file to explain (read-only task).",
+                    },
+                    {
+                        name: "question",
+                        type: "string",
+                        required: false,
+                        description: "Optional focusing question for the explanation.",
+                    },
+                ],
+                defaultLimits: DEFAULT_LIMITS,
+            },
+            verify: {
+                inputs: [
+                    {
+                        name: "workspaceRoot",
+                        type: "string",
+                        required: true,
+                        description: "Project root to verify.",
+                    },
+                    {
+                        name: "targetFiles",
+                        type: "string[]",
+                        required: false,
+                        description: "Optional file subset to target tests for.",
+                    },
+                ],
+                defaultLimits: DEFAULT_LIMITS,
+            },
+        },
+    };
+}
+function parsePositiveBudget(value) {
+    if (value === null) {
+        return undefined;
+    }
+    if (!/^[1-9][0-9]*$/u.test(value)) {
+        throw new Error("invalid budget");
+    }
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isSafeInteger(parsed)) {
+        throw new Error("invalid budget");
+    }
+    return parsed;
+}
+function workspaceErrorResult(error) {
+    const status = error.code === WORKSPACE_CODES.NOT_FOUND
+        ? 404
+        : error.code === WORKSPACE_CODES.FILE_TOO_LARGE || error.code === WORKSPACE_CODES.READ_FAILED
+            ? 422
+            : 400;
+    return { status, body: errorBody(error.code, workspaceErrorMessage(error.code)) };
+}
+const WORKSPACE_ERROR_MESSAGES = {
+    [WORKSPACE_CODES.PATH_ESCAPE]: "The workspace path is outside the registered project.",
+    [WORKSPACE_CODES.PATH_DENIED]: "The workspace path is denied by policy.",
+    [WORKSPACE_CODES.NOT_FOUND]: "The workspace could not be found.",
+    [WORKSPACE_CODES.FILE_TOO_LARGE]: "The workspace file is too large.",
+    [WORKSPACE_CODES.READ_FAILED]: "The workspace could not be read.",
+};
+function workspaceErrorMessage(code) {
+    return WORKSPACE_ERROR_MESSAGES[code];
+}
+function readWorkspaceRequest(q) {
+    let budget;
+    try {
+        budget = parsePositiveBudget(q.get("budget"));
+    }
+    catch {
+        return {
+            status: 400,
+            body: errorBody("BAD_REQUEST", "The budget query parameter must be a positive integer."),
+        };
+    }
+    const dir = q.get("dir");
+    if (dir === null) {
+        return {
+            status: 400,
+            body: errorBody("BAD_REQUEST", "The dir query parameter is required."),
+        };
+    }
+    return { dir, task: q.get("task") ?? undefined, budget };
+}
+function workspaceNotRegisteredResult() {
+    return {
+        status: 403,
+        body: errorBody("WORKSPACE_NOT_REGISTERED", "The workspace directory is not a registered project."),
+    };
+}
+function resolveRegisteredWorkspace(rawDir, deps) {
+    let normalized;
+    try {
+        normalized = validateProjectPath(rawDir, { mustExist: false });
+    }
+    catch {
+        return {
+            status: 400,
+            body: errorBody("BAD_REQUEST", "The dir query parameter must be a valid local project path."),
+        };
+    }
+    const registered = deps.store.listProjects().some((project) => project.path === normalized);
+    if (!registered) {
+        return workspaceNotRegisteredResult();
+    }
+    return { normalized };
+}
+function workspaceSummaryResult(request, registeredRoot, deps) {
+    try {
+        const workspace = detectWorkspace(registeredRoot);
+        if (workspace.root !== registeredRoot) {
+            return workspaceNotRegisteredResult();
+        }
+        const { files, stats } = discoverWithStats(workspace, DEFAULT_CONTEXT_REQUEST.discovery);
+        const wantsContext = request.task !== undefined || request.budget !== undefined;
+        const pack = wantsContext
+            ? buildContextPackFromFiles(workspace, {
+                ...DEFAULT_CONTEXT_REQUEST,
+                task: request.task,
+                budgetBytes: request.budget ?? DEFAULT_CONTEXT_REQUEST.budgetBytes,
+            }, files)
+            : undefined;
+        const summary = buildWorkspaceSummary(workspace, pack, stats);
+        const body = deps.redactor({ summary });
+        return { status: 200, body };
+    }
+    catch (error) {
+        if (error instanceof WorkspaceError) {
+            const result = workspaceErrorResult(error);
+            return { status: result.status, body: deps.redactor(result.body) };
+        }
+        throw error;
+    }
+}
+// Route 12 — workspace summary and optional context pack, built by the safe workspace layer.
+export function handleWorkspace(ctx, deps) {
+    const request = readWorkspaceRequest(ctx.url.searchParams);
+    if ("status" in request) {
+        return request;
+    }
+    const registered = resolveRegisteredWorkspace(request.dir, deps);
+    if ("status" in registered) {
+        return registered;
+    }
+    return workspaceSummaryResult(request, registered.normalized, deps);
+}
+function readFilters(url) {
+    const q = url.searchParams;
+    return {
+        workspace: q.get("workspace") ?? undefined,
+        date: q.get("date") ?? undefined,
+        workflow: q.get("workflow") ?? undefined,
+        model: q.get("model") ?? undefined,
+        outcome: q.get("outcome") ?? undefined,
+    };
+}
+// `EvidenceListEntry.startedAt` is epoch ms; the `date` filter matches the started-at calendar day
+// (UTC `YYYY-MM-DD`). `workspace` is a substring match to support path-fragment filtering, while
+// `model` is an exact model-id match.
+function matchesOptionalFilter(value, filter) {
+    return filter === undefined || value === filter;
+}
+function matchesDateFilter(entry, date) {
+    return date === undefined || new Date(entry.startedAt).toISOString().slice(0, 10) === date;
+}
+function matchesWorkspaceFilter(entry, workspace) {
+    return workspace === undefined || entry.workspaceRoot?.includes(workspace) === true;
+}
+function matchesFilters(entry, filters) {
+    return (matchesOptionalFilter(entry.taskType, filters.workflow) &&
+        matchesOptionalFilter(entry.outcome, filters.outcome) &&
+        matchesDateFilter(entry, filters.date) &&
+        matchesOptionalFilter(entry.modelId, filters.model) &&
+        matchesWorkspaceFilter(entry, filters.workspace));
+}
+// Route 10 — evidence list header projection, filtered server-side.
+export function handleEvidenceList(ctx, deps) {
+    const filters = readFilters(ctx.url);
+    const entries = listEvidence(deps.evidenceStore).filter((entry) => matchesFilters(entry, filters));
+    return { status: 200, body: { entries } };
+}
+// Route 11 — a single evidence manifest, served as-is (already redacted on disk). Invalid runId →
+// 400; absent → 404; an EvidenceSchemaError → 422; an EvidenceReadError → 422 (safe, pre-redacted
+// `.message`).
+export function handleEvidenceDetail(ctx, deps) {
+    const runId = ctx.params.runId ?? "";
+    try {
+        assertValidRunId(runId);
+    }
+    catch {
+        return { status: 400, body: errorBody("BAD_REQUEST", "The run id is not valid.") };
+    }
+    try {
+        const manifest = loadEvidence(deps.evidenceStore, runId);
+        if (manifest === undefined) {
+            return { status: 404, body: errorBody("NOT_FOUND", "No evidence for that run id.") };
+        }
+        return { status: 200, body: { manifest } };
+    }
+    catch (error) {
+        if (error instanceof EvidenceSchemaError) {
+            return { status: 422, body: errorBody("EVIDENCE_SCHEMA", error.message) };
+        }
+        if (error instanceof EvidenceReadError) {
+            return { status: 422, body: errorBody("EVIDENCE_READ", error.message) };
+        }
+        throw error;
+    }
+}

package/dist/ui/routes.d.ts

@@ -0,0 +1,36 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { UiHandlerDeps } from "./deps.js";
+export interface ApiError {
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+    };
+}
+export interface RouteResult {
+    readonly status: number;
+    readonly body: unknown;
+}
+export declare const STREAMING: unique symbol;
+export type HandlerOutcome = RouteResult | typeof STREAMING;
+export interface RouteContext {
+    readonly req: IncomingMessage;
+    readonly res: ServerResponse;
+    readonly params: Readonly<Record<string, string>>;
+    readonly url: URL;
+}
+export type RouteHandler = (ctx: RouteContext, deps: UiHandlerDeps) => HandlerOutcome | Promise<HandlerOutcome>;
+export interface RouteDefinition {
+    readonly method: string;
+    readonly pattern: string;
+    readonly handler: RouteHandler;
+}
+export declare const API_ROUTES: readonly RouteDefinition[];
+export interface RouteMatch {
+    readonly definition: RouteDefinition;
+    readonly params: Readonly<Record<string, string>>;
+}
+export declare function matchRoute(method: string, pathname: string): RouteMatch | "method-not-allowed" | undefined;
+export declare function isApiPath(pathname: string): boolean;
+export declare function errorBody(code: string, message: string): ApiError;
+export declare function notFoundBody(): ApiError;
+export declare function methodNotAllowedBody(): ApiError;

package/dist/ui/routes.js

@@ -0,0 +1,129 @@
+// BFF route dispatch (ADR-0011 D5). The route contract is wired here. The route TABLE
+// (method + pattern) is static and dependency-free; each entry names a handler that receives the
+// request context AND the per-server handler dependencies (resolved config, evidence store, run
+// registry, redactor — see deps.ts). A handler returns a RouteResult (status + JSON body, which the
+// server serializes) OR the STREAMING sentinel, meaning it has taken over the raw ServerResponse
+// (the SSE events route). Non-2xx bodies use the redacted error envelope `{ error: { code, message } }`.
+import { SDK_VERSION } from "../sdk/index.js";
+import { handleConfig, handleModels, handleWorkflows, handleWorkspace, handleEvidenceList, handleEvidenceDetail, } from "./read-handlers.js";
+import { handleCreateRun, handleCreateChatRun, handleRunEvents, handleCancelRun, handleGetRun, handleApplyRun, } from "./run-handlers.js";
+import { handleListProjects, handleCreateProject, handleUpdateProject, handleDeleteProject, handleListChats, handleCreateChat, handleUpdateChat, handleDeleteChat, handleListMessages, handleCreateMessage, handleCreateRunSummaryPair, handleUpdateMessage, } from "./store-handlers.js";
+import { handleCreateDesktopChat, handleSendDesktopChat } from "./chat-handlers.js";
+import { handleCreateTerminalExecution, handleDeleteTerminalExecution, handleTerminalDirectories, handleTerminalEvents, handleTerminalPolicy, } from "./terminal-routes.js";
+import { handleFilesDirectories, handleFilesPreview, handleFilesTree, } from "./files.js";
+import { handleBrowserApplyScreenshot, handleBrowserContent, handleBrowserEvents, handleBrowserNavigate, handleBrowserScreenshot, handleBrowserStatus, handleCreateBrowserSession, handleDeleteBrowserSession, } from "./browser.js";
+export const STREAMING = Symbol("streaming");
+function health() {
+    return { status: 200, body: { status: "ok", version: SDK_VERSION } };
+}
+// The full route contract: the twelve original (ADR-0011 D5), the 10 additive UI-store
+// routes (ADR-0013 D7), three Issue #66 run-summary routes, two desktop chat routes,
+// desktop terminal JSON routes, and read-only Files widget routes. Terminal byte I/O
+// uses a token-scoped WebSocket upgrade path.
+export const API_ROUTES = [
+    { method: "GET", pattern: "/api/health", handler: health },
+    { method: "GET", pattern: "/api/config", handler: handleConfig },
+    { method: "GET", pattern: "/api/models", handler: handleModels },
+    { method: "GET", pattern: "/api/workflows", handler: handleWorkflows },
+    { method: "POST", pattern: "/api/runs", handler: handleCreateRun },
+    { method: "GET", pattern: "/api/runs/:runId/events", handler: handleRunEvents },
+    { method: "POST", pattern: "/api/runs/:runId/cancel", handler: handleCancelRun },
+    { method: "GET", pattern: "/api/runs/:runId", handler: handleGetRun },
+    { method: "POST", pattern: "/api/runs/:runId/apply", handler: handleApplyRun },
+    { method: "GET", pattern: "/api/evidence", handler: handleEvidenceList },
+    { method: "GET", pattern: "/api/evidence/:runId", handler: handleEvidenceDetail },
+    { method: "GET", pattern: "/api/workspace", handler: handleWorkspace },
+    // ADR-0013 D7 — UI-local persistence routes (additive).
+    { method: "GET", pattern: "/api/projects", handler: handleListProjects },
+    { method: "POST", pattern: "/api/projects", handler: handleCreateProject },
+    { method: "PATCH", pattern: "/api/projects", handler: handleUpdateProject },
+    { method: "DELETE", pattern: "/api/projects", handler: handleDeleteProject },
+    { method: "GET", pattern: "/api/chats", handler: handleListChats },
+    { method: "POST", pattern: "/api/chats", handler: handleCreateChat },
+    // Issue #66 — composer launch path: persist chat pair and start the run as one BFF operation.
+    { method: "POST", pattern: "/api/chats/runs", handler: handleCreateChatRun },
+    { method: "PATCH", pattern: "/api/chats", handler: handleUpdateChat },
+    { method: "DELETE", pattern: "/api/chats", handler: handleDeleteChat },
+    { method: "GET", pattern: "/api/chats/messages", handler: handleListMessages },
+    { method: "POST", pattern: "/api/chats/messages", handler: handleCreateMessage },
+    // Issue #66 — atomic composer write: exactly one user message plus one run-summary system message.
+    { method: "POST", pattern: "/api/chats/messages/run-summary-pair", handler: handleCreateRunSummaryPair },
+    // Issue #66 — PATCH a run-summary message (status/shortResult/taskType).
+    { method: "PATCH", pattern: "/api/chats/messages", handler: handleUpdateMessage },
+    // Desktop canvas V1 — real chat against the configured gateway model without new agent scope.
+    { method: "POST", pattern: "/api/desktop/chats", handler: handleCreateDesktopChat },
+    { method: "POST", pattern: "/api/desktop/chat", handler: handleSendDesktopChat },
+    // ADR-0018 — bounded permitted-command execution. PTY routes (shells/sessions/WS upgrade) and
+    // the WebSocket upgrade handler in server.ts are removed; commands run via synchronous POST.
+    { method: "GET", pattern: "/api/terminal/policy", handler: handleTerminalPolicy },
+    { method: "GET", pattern: "/api/terminal/directories", handler: handleTerminalDirectories },
+    { method: "POST", pattern: "/api/terminal/executions", handler: handleCreateTerminalExecution },
+    { method: "DELETE", pattern: "/api/terminal/executions/:executionId", handler: handleDeleteTerminalExecution },
+    { method: "GET", pattern: "/api/terminal/events", handler: handleTerminalEvents },
+    // Desktop files — read-only selected-root browser and preview control plane.
+    { method: "GET", pattern: "/api/files/directories", handler: handleFilesDirectories },
+    { method: "GET", pattern: "/api/files/tree", handler: handleFilesTree },
+    { method: "GET", pattern: "/api/files/preview", handler: handleFilesPreview },
+    // ADR-0017 — browser tool (BYO Chrome over CDP).
+    { method: "GET", pattern: "/api/browser/status", handler: handleBrowserStatus },
+    { method: "POST", pattern: "/api/browser/sessions", handler: handleCreateBrowserSession },
+    { method: "DELETE", pattern: "/api/browser/sessions/:sessionId", handler: handleDeleteBrowserSession },
+    { method: "POST", pattern: "/api/browser/sessions/:sessionId/navigate", handler: handleBrowserNavigate },
+    { method: "POST", pattern: "/api/browser/sessions/:sessionId/screenshot", handler: handleBrowserScreenshot },
+    { method: "POST", pattern: "/api/browser/sessions/:sessionId/apply", handler: handleBrowserApplyScreenshot },
+    { method: "POST", pattern: "/api/browser/sessions/:sessionId/content", handler: handleBrowserContent },
+    { method: "GET", pattern: "/api/browser/sessions/:sessionId/events", handler: handleBrowserEvents },
+];
+// Matches a concrete path against a route pattern, capturing `:name` params. Returns the captured
+// params, or undefined when the segment counts differ or a literal segment mismatches.
+function matchPattern(pattern, pathname) {
+    const patternParts = pattern.split("/");
+    const pathParts = pathname.split("/");
+    if (patternParts.length !== pathParts.length) {
+        return undefined;
+    }
+    const params = {};
+    for (let i = 0; i < patternParts.length; i++) {
+        const p = patternParts[i] ?? "";
+        const actual = pathParts[i] ?? "";
+        if (p.startsWith(":")) {
+            if (actual.length === 0) {
+                return undefined;
+            }
+            params[p.slice(1)] = actual;
+        }
+        else if (p !== actual) {
+            return undefined;
+        }
+    }
+    return params;
+}
+// Resolves a method+path to a route. Returns `{ definition, params }` on a full match, the string
+// `"method-not-allowed"` when the path matches a route of a different method, or undefined when no
+// route path matches at all.
+export function matchRoute(method, pathname) {
+    let pathMatchedOtherMethod = false;
+    for (const definition of API_ROUTES) {
+        const params = matchPattern(definition.pattern, pathname);
+        if (params === undefined) {
+            continue;
+        }
+        if (definition.method === method) {
+            return { definition, params };
+        }
+        pathMatchedOtherMethod = true;
+    }
+    return pathMatchedOtherMethod ? "method-not-allowed" : undefined;
+}
+export function isApiPath(pathname) {
+    return pathname === "/api" || pathname.startsWith("/api/");
+}
+export function errorBody(code, message) {
+    return { error: { code, message } };
+}
+export function notFoundBody() {
+    return errorBody("NOT_FOUND", "The requested resource was not found.");
+}
+export function methodNotAllowedBody() {
+    return errorBody("METHOD_NOT_ALLOWED", "The HTTP method is not allowed for this resource.");
+}

package/dist/ui/run-engine.d.ts

@@ -0,0 +1,20 @@
+import type { ModelPort } from "../harness/index.js";
+import type { RunRequest } from "./run-request.js";
+import type { AppliableSnapshot, RunRegistry } from "./runs.js";
+import { type EvidencePersistContext } from "./evidence.js";
+export interface StartRunResult {
+    readonly runId: string;
+    readonly fingerprint: string;
+}
+export interface StartRunOptions {
+    readonly runId?: string;
+}
+interface EngineContext {
+    readonly request: RunRequest;
+    readonly model: ModelPort;
+    readonly registry: RunRegistry;
+    readonly evidence?: EvidencePersistContext | undefined;
+}
+export declare function startRun(ctx: EngineContext, redactReport: (value: unknown) => unknown, options?: StartRunOptions): StartRunResult;
+export declare function applyRun(snapshot: AppliableSnapshot, model: ModelPort, modelId: string, redactReport: (value: unknown) => unknown): Promise<unknown>;
+export type { EngineContext };