@oscharko-dev/keiko-server 0.2.0

package/dist/run-request.js

@@ -0,0 +1,219 @@
+// Parsing + validation of the `POST /api/runs` request body (ADR-0011 D5 route 5). The body arrives
+// as untyped JSON; this module narrows it (no `any`) into a typed `RunRequest` or a typed validation
+// error. It performs SHAPE validation only — exactly one of workflowId/taskType, a present input
+// object, a non-empty modelId, and a selected project workspaceRoot. The create route is ALWAYS
+// dry-run: `apply` is forced false here regardless of the body, so applying is reachable only via
+// the gated apply route (D8). The deeper guards (`isSensitivePath`, patch limits, target validation)
+// are enforced by the workflow/harness entry points the engine calls; the BFF never reimplements
+// them.
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function resolveKind(body) {
+    const workflowId = body.workflowId;
+    const taskType = body.taskType;
+    const hasWorkflow = workflowId !== undefined;
+    const hasTask = taskType !== undefined;
+    if (hasWorkflow === hasTask) {
+        return { code: "BAD_REQUEST", message: "Provide exactly one of workflowId or taskType." };
+    }
+    if (hasWorkflow) {
+        if (workflowId === "unit-test-generation") {
+            return "unit-tests";
+        }
+        if (workflowId === "bug-investigation") {
+            return "bug-investigation";
+        }
+        return { code: "BAD_REQUEST", message: "Unknown workflowId." };
+    }
+    if (taskType === "explain-plan") {
+        return "explain-plan";
+    }
+    if (taskType === "verify") {
+        return "verify";
+    }
+    return { code: "BAD_REQUEST", message: "Unsupported taskType." };
+}
+function validateWorkspaceRoot(input) {
+    const workspaceRoot = input.workspaceRoot;
+    if (typeof workspaceRoot !== "string" || workspaceRoot.length === 0) {
+        return { code: "BAD_REQUEST", message: "A non-empty workspaceRoot is required." };
+    }
+    return null;
+}
+function validateStringField(input, name, label) {
+    const value = input[name];
+    if (typeof value !== "string" || value.length === 0) {
+        return { code: "BAD_REQUEST", message: `${label} must be a non-empty string.` };
+    }
+    return null;
+}
+function validateOptionalStringField(input, name, label) {
+    const value = input[name];
+    if (value === undefined) {
+        return null;
+    }
+    if (typeof value !== "string") {
+        return { code: "BAD_REQUEST", message: `${label} must be a string.` };
+    }
+    return null;
+}
+function validateStringArray(value, label, options = {
+    required: false,
+    allowEmpty: true,
+}) {
+    if (value === undefined) {
+        return options.required
+            ? { code: "BAD_REQUEST", message: `${label} must be a string array.` }
+            : null;
+    }
+    if (!Array.isArray(value)) {
+        return { code: "BAD_REQUEST", message: `${label} must be a string array.` };
+    }
+    if (!options.allowEmpty && value.length === 0) {
+        return { code: "BAD_REQUEST", message: `${label} must contain at least one entry.` };
+    }
+    for (const entry of value) {
+        if (typeof entry !== "string" || entry.length === 0) {
+            return { code: "BAD_REQUEST", message: `${label} must contain non-empty strings.` };
+        }
+    }
+    return null;
+}
+// Verify shape: targetFiles (when present) must be a string[] of non-empty entries. The deeper
+// guards (path containment, script detection) run inside the verification orchestrator; the BFF
+// only validates shape here.
+function validateVerifyInput(input) {
+    return validateStringArray(input.targetFiles, "verify targetFiles");
+}
+function validateExplainPlanInput(input) {
+    return (validateStringField(input, "filePath", "explain-plan filePath") ??
+        validateOptionalStringField(input, "question", "explain-plan question"));
+}
+function validateUnitTestTarget(target) {
+    const kind = target.kind;
+    if (kind === "file") {
+        return (validateStringField(target, "filePath", "unit-test target.filePath") ??
+            validateOptionalStringField(target, "targetFunction", "unit-test target.targetFunction"));
+    }
+    if (kind === "module") {
+        return validateStringField(target, "moduleDir", "unit-test target.moduleDir");
+    }
+    if (kind === "changedFiles") {
+        return validateStringArray(target.filePaths, "unit-test target.filePaths", {
+            required: true,
+            allowEmpty: false,
+        });
+    }
+    return {
+        code: "BAD_REQUEST",
+        message: "unit-test target.kind must be one of file, module, changedFiles.",
+    };
+}
+function validateUnitTestsInput(input) {
+    const target = input.target;
+    if (!isRecord(target)) {
+        return { code: "BAD_REQUEST", message: "unit-test target must be an object." };
+    }
+    return validateUnitTestTarget(target);
+}
+function validateBugReport(report) {
+    const descriptionError = validateOptionalStringField(report, "description", "bug report.description");
+    if (descriptionError !== null) {
+        return descriptionError;
+    }
+    const failingOutputError = validateOptionalStringField(report, "failingOutput", "bug report.failingOutput");
+    if (failingOutputError !== null) {
+        return failingOutputError;
+    }
+    const stackTraceError = validateOptionalStringField(report, "stackTrace", "bug report.stackTrace");
+    if (stackTraceError !== null) {
+        return stackTraceError;
+    }
+    const targetFilesError = validateStringArray(report.targetFiles, "bug report.targetFiles");
+    if (targetFilesError !== null) {
+        return targetFilesError;
+    }
+    return hasBugEvidence(report)
+        ? null
+        : {
+            code: "BAD_REQUEST",
+            message: "bug report requires at least one of description, failingOutput, stackTrace, or targetFiles.",
+        };
+}
+function hasNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function hasNonEmptyStringEntry(value) {
+    return Array.isArray(value) && value.some(hasNonEmptyString);
+}
+function hasBugEvidence(report) {
+    return (hasNonEmptyString(report.description) ||
+        hasNonEmptyString(report.failingOutput) ||
+        hasNonEmptyString(report.stackTrace) ||
+        hasNonEmptyStringEntry(report.targetFiles));
+}
+function validateBugInvestigationInput(input) {
+    const report = input.report;
+    if (!isRecord(report)) {
+        return { code: "BAD_REQUEST", message: "bug report must be an object." };
+    }
+    return validateBugReport(report);
+}
+function validateRunInput(kind, input) {
+    const workspaceRootError = validateWorkspaceRoot(input);
+    if (workspaceRootError !== null) {
+        return workspaceRootError;
+    }
+    if (kind === "verify") {
+        return validateVerifyInput(input);
+    }
+    if (kind === "explain-plan") {
+        return validateExplainPlanInput(input);
+    }
+    if (kind === "unit-tests") {
+        return validateUnitTestsInput(input);
+    }
+    return validateBugInvestigationInput(input);
+}
+// Parses the raw JSON text into a validated RunRequest, or a typed BAD_REQUEST error.
+export function parseRunRequest(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { code: "BAD_REQUEST", message: "Request body is not valid JSON." };
+    }
+    if (!isRecord(parsed)) {
+        return { code: "BAD_REQUEST", message: "Request body must be a JSON object." };
+    }
+    const kind = resolveKind(parsed);
+    if (typeof kind !== "string") {
+        return kind;
+    }
+    const modelId = parsed.modelId;
+    if (typeof modelId !== "string" || modelId.length === 0) {
+        return { code: "BAD_REQUEST", message: "A non-empty modelId is required." };
+    }
+    const input = parsed.input;
+    if (!isRecord(input)) {
+        return { code: "BAD_REQUEST", message: "An input object is required." };
+    }
+    const inputError = validateRunInput(kind, input);
+    if (inputError !== null) {
+        return inputError;
+    }
+    const limits = parsed.limits;
+    return {
+        kind,
+        modelId,
+        // Dry-run-first (ADR-0011 D8 / security M1): the create route NEVER applies, even if the client
+        // body carries `apply:true`. Applying is the sole responsibility of POST /api/runs/:runId/apply
+        // (route 9), which re-invokes the workflow through the gated path. A one-shot create-with-apply
+        // would bypass the explicit review→apply step, so the body flag is deliberately ignored here.
+        apply: false,
+        input,
+        ...(isRecord(limits) ? { limits } : { limits: undefined }),
+    };
+}

package/dist/runs.d.ts

@@ -0,0 +1,47 @@
+import type { WorkflowHandoffRequest } from "@oscharko-dev/keiko-contracts/workflow-handoff";
+import type { QueueEventSink } from "./sink.js";
+export type RunStatus = "running" | "completed" | "cancelled" | "failed";
+export interface AppliableSnapshot {
+    readonly kind: "unit-tests" | "bug-investigation";
+    readonly payload: unknown;
+    readonly limits: Record<string, unknown> | undefined;
+    readonly governedHandoff?: WorkflowHandoffRequest | undefined;
+}
+export interface RunRecord {
+    readonly runId: string;
+    readonly fingerprint: string;
+    readonly modelId: string;
+    readonly sink: QueueEventSink;
+    status: RunStatus;
+    report: unknown;
+    readonly cancel: (reason?: string) => void;
+    appliable: AppliableSnapshot | undefined;
+    applyReport: unknown;
+    appliedAt: number | undefined;
+    terminatedAt: number | undefined;
+}
+export interface RegisterRunInput {
+    readonly runId: string;
+    readonly fingerprint: string;
+    readonly modelId: string;
+    readonly sink: QueueEventSink;
+    readonly cancel: (reason?: string) => void;
+}
+export interface RunRegistryOptions {
+    readonly maxActiveRuns?: number | undefined;
+    readonly terminatedTtlMs?: number | undefined;
+    readonly now?: (() => number) | undefined;
+}
+export declare class ActiveRunLimitError extends Error {
+    constructor(limit: number);
+}
+export interface RunRegistry {
+    register: (input: RegisterRunInput) => RunRecord;
+    get: (runId: string) => RunRecord | undefined;
+    snapshot?: (limit?: number) => readonly RunRecord[];
+    complete: (runId: string, status: Exclude<RunStatus, "running">, report: unknown, appliable: AppliableSnapshot | undefined) => void;
+    activeCount: () => number;
+    size: () => number;
+}
+export declare function createRunRegistry(options?: RunRegistryOptions): RunRegistry;
+//# sourceMappingURL=runs.d.ts.map

package/dist/runs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runs.d.ts","sourceRoot":"","sources":["../src/runs.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gDAAgD,CAAC;AAC7F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,WAAW,GAAG,QAAQ,CAAC;AAMzE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,mBAAmB,CAAC;IAClD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IACrD,QAAQ,CAAC,eAAe,CAAC,EAAE,sBAAsB,GAAG,SAAS,CAAC;CAC/D;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAG7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,MAAM,EAAE,SAAS,CAAC;IAElB,MAAM,EAAE,OAAO,CAAC;IAEhB,QAAQ,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAE3C,SAAS,EAAE,iBAAiB,GAAG,SAAS,CAAC;IAEzC,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAE9B,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5C;AAED,MAAM,WAAW,kBAAkB;IAEjC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAE5C,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAE9C,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,SAAS,CAAC;CAC3C;AAED,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,KAAK,EAAE,MAAM;CAI1B;AAKD,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,SAAS,CAAC;IACjD,GAAG,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,SAAS,GAAG,SAAS,CAAC;IAE9C,QAAQ,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,MAAM,KAAK,SAAS,SAAS,EAAE,CAAC;IAEpD,QAAQ,EAAE,CACR,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,OAAO,CAAC,SAAS,EAAE,SAAS,CAAC,EACrC,MAAM,EAAE,OAAO,EACf,SAAS,EAAE,iBAAiB,GAAG,SAAS,KACrC,IAAI,CAAC;IAEV,WAAW,EAAE,MAAM,MAAM,CAAC;IAE1B,IAAI,EAAE,MAAM,MAAM,CAAC;CACpB;AAuED,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,kBAAuB,GAAG,WAAW,CAiC/E"}

package/dist/runs.js

@@ -0,0 +1,100 @@
+// The in-memory run registry (ADR-0011 D7). It maps a runId to a live run record (the streaming
+// sink, the run status, the captured final report, and a cancel handle). It is BOUNDED on two axes:
+// a cap on simultaneously-active runs (a new run is refused past the cap) and a TTL after which a
+// TERMINATED run's record — including its event ring buffer — is evicted to reclaim memory (D7's
+// documented retention: buffers are dropped once the run terminates and its TTL elapses). The
+// registry is created via `createRunRegistry` and hung off the handler deps, never a module global,
+// so each server instance (and each test) owns an isolated registry with no cross-talk.
+export class ActiveRunLimitError extends Error {
+    constructor(limit) {
+        super(`active run limit reached (${String(limit)})`);
+        this.name = "ActiveRunLimitError";
+    }
+}
+const DEFAULT_MAX_ACTIVE_RUNS = 16;
+const DEFAULT_TERMINATED_TTL_MS = 600_000;
+function isTerminal(status) {
+    return status !== "running";
+}
+function evictExpired(state) {
+    const cutoff = state.now();
+    for (const [runId, record] of state.records) {
+        if (record.terminatedAt !== undefined && cutoff - record.terminatedAt >= state.ttlMs) {
+            state.records.delete(runId);
+        }
+    }
+}
+function countActive(state) {
+    let count = 0;
+    for (const record of state.records.values()) {
+        if (!isTerminal(record.status)) {
+            count += 1;
+        }
+    }
+    return count;
+}
+function registerRun(state, input) {
+    evictExpired(state);
+    if (countActive(state) >= state.maxActive) {
+        throw new ActiveRunLimitError(state.maxActive);
+    }
+    const record = {
+        runId: input.runId,
+        fingerprint: input.fingerprint,
+        modelId: input.modelId,
+        sink: input.sink,
+        status: "running",
+        report: undefined,
+        cancel: input.cancel,
+        appliable: undefined,
+        applyReport: undefined,
+        appliedAt: undefined,
+        terminatedAt: undefined,
+    };
+    state.records.set(input.runId, record);
+    return record;
+}
+function completeRun(state, runId, status, report, appliable) {
+    const record = state.records.get(runId);
+    if (record === undefined) {
+        return;
+    }
+    record.status = status;
+    record.report = report;
+    record.appliable = appliable;
+    record.terminatedAt = state.now();
+}
+export function createRunRegistry(options = {}) {
+    const state = {
+        records: new Map(),
+        maxActive: options.maxActiveRuns ?? DEFAULT_MAX_ACTIVE_RUNS,
+        ttlMs: options.terminatedTtlMs ?? DEFAULT_TERMINATED_TTL_MS,
+        now: options.now ?? Date.now,
+    };
+    return {
+        register: (input) => registerRun(state, input),
+        get: (runId) => {
+            evictExpired(state);
+            return state.records.get(runId);
+        },
+        complete: (runId, status, report, appliable) => {
+            completeRun(state, runId, status, report, appliable);
+        },
+        snapshot: (limit) => {
+            evictExpired(state);
+            const records = Array.from(state.records.values());
+            if (limit === undefined || limit >= records.length) {
+                return records;
+            }
+            return records.slice(Math.max(0, records.length - limit));
+        },
+        activeCount: () => {
+            evictExpired(state);
+            return countActive(state);
+        },
+        size: () => {
+            evictExpired(state);
+            return state.records.size;
+        },
+    };
+}

package/dist/server.d.ts

@@ -0,0 +1,13 @@
+import { type Server } from "node:http";
+import { type UiHandlerDeps } from "./deps.js";
+export declare const DEFAULT_UI_PORT = 1983;
+export declare const UI_HOST = "127.0.0.1";
+export interface UiServerDeps {
+    readonly staticRoot: string;
+    readonly csp: string;
+    readonly cspProvider?: (() => string | Promise<string>) | undefined;
+    readonly port: number;
+    readonly handlerDeps?: UiHandlerDeps | undefined;
+}
+export declare function createUiServer(deps: UiServerDeps): Server;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAIA,OAAO,EAAsC,KAAK,MAAM,EAAuB,MAAM,WAAW,CAAC;AAejG,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAI9D,eAAO,MAAM,eAAe,OAAO,CAAC;AACpC,eAAO,MAAM,OAAO,cAAc,CAAC;AAEnC,MAAM,WAAW,YAAY;IAE3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAGrB,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC;IAEpE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAGtB,QAAQ,CAAC,WAAW,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;CAClD;AA0JD,wBAAgB,cAAc,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAgBzD"}

package/dist/server.js

@@ -0,0 +1,152 @@
+// The local UI BFF binds 127.0.0.1 only, applies security headers and CSP to every response,
+// rejects non-loopback Host/Origin headers, dispatches API routes through injected handlers,
+// and serves the static export from a contained root.
+import { createServer } from "node:http";
+import { extname, join } from "node:path";
+import { applySecurityHeaders } from "./headers.js";
+import { isAllowedHost } from "./host-check.js";
+import { resolveContainedPath, serveFile } from "./static.js";
+import { errorBody, isApiPath, matchRoute, methodNotAllowedBody, notFoundBody, STREAMING, } from "./routes.js";
+import { buildRedactor } from "./deps.js";
+import { createRunRegistry } from "./runs.js";
+import { createInMemoryUiStore } from "./store/index.js";
+export const DEFAULT_UI_PORT = 1983;
+export const UI_HOST = "127.0.0.1";
+function writeJson(res, status, body) {
+    res.statusCode = status;
+    res.setHeader("Content-Type", "application/json; charset=utf-8");
+    res.end(JSON.stringify(body));
+}
+function isJsonRequest(req) {
+    const header = req.headers["content-type"];
+    const value = typeof header === "string" ? header : header?.[0];
+    return value?.split(";", 1)[0]?.trim().toLowerCase() === "application/json";
+}
+function hasCsrfHeader(req) {
+    const header = req.headers["x-keiko-csrf"];
+    const value = Array.isArray(header) ? header[0] : header;
+    return value === "1";
+}
+function rejectUnsupportedMediaType(res) {
+    writeJson(res, 415, errorBody("UNSUPPORTED_MEDIA_TYPE", "State-changing API requests must use JSON."));
+}
+function rejectCsrf(res) {
+    writeJson(res, 403, errorBody("FORBIDDEN_CSRF", "Missing state-changing request guard."));
+}
+// A minimal default deps object so a 3-arg server can still serve the deps-bound read routes (e.g.
+// `/api/models` and `/api/workspace`, which need no config) without a config or evidence dir. The
+// fallback UI store is in-memory: a 3-arg server is used by the Wave 1 host smoke and by tests that
+// never exercise the store routes, so an ephemeral in-memory store is the safe degraded shape.
+function fallbackDeps() {
+    return {
+        config: undefined,
+        configPresent: false,
+        evidenceStore: { put: () => "", list: () => [], get: () => undefined, delete: () => undefined },
+        env: {},
+        redactor: buildRedactor({}),
+        registry: createRunRegistry(),
+        modelPortFactory: () => undefined,
+        store: createInMemoryUiStore(),
+    };
+}
+function isStateChangingMethod(method) {
+    return method === "POST" || method === "PATCH" || method === "PUT" || method === "DELETE";
+}
+// Returns true when the request was rejected (caller should return immediately).
+function rejectIfInvalidStateChange(req, res) {
+    if (!isJsonRequest(req)) {
+        rejectUnsupportedMediaType(res);
+        return true;
+    }
+    if (!hasCsrfHeader(req)) {
+        rejectCsrf(res);
+        return true;
+    }
+    return false;
+}
+async function dispatchApi(handlerDeps, req, res, method, url) {
+    const match = matchRoute(method, url.pathname);
+    if (match === undefined) {
+        writeJson(res, 404, notFoundBody());
+        return;
+    }
+    if (match === "method-not-allowed") {
+        writeJson(res, 405, methodNotAllowedBody());
+        return;
+    }
+    if (isStateChangingMethod(method) && rejectIfInvalidStateChange(req, res)) {
+        return;
+    }
+    const ctx = { req, res, params: match.params, url };
+    const outcome = await match.definition.handler(ctx, handlerDeps);
+    if (outcome === STREAMING) {
+        return;
+    }
+    writeJson(res, outcome.status, outcome.body);
+}
+async function serveStatic(res, staticRoot, pathname) {
+    const targets = pathname === "/"
+        ? ["/index.html"]
+        : extname(pathname) === ""
+            ? [pathname, `${pathname}.html`, `${pathname}/index.html`]
+            : [pathname];
+    for (const target of targets) {
+        const resolved = resolveContainedPath(staticRoot, target);
+        if (resolved !== undefined && (await serveFile(res, resolved))) {
+            return;
+        }
+    }
+    const indexPath = join(staticRoot, "index.html");
+    if (await serveFile(res, indexPath)) {
+        return;
+    }
+    writeJson(res, 404, errorBody("NOT_FOUND", "The requested resource was not found."));
+}
+function rejectForbiddenHost(res) {
+    const body = errorBody("FORBIDDEN_HOST", "Request host is not the local interface.");
+    writeJson(res, 403, body);
+}
+async function resolveCsp(deps) {
+    try {
+        return (await deps.cspProvider?.()) ?? deps.csp;
+    }
+    catch {
+        return deps.csp;
+    }
+}
+async function handle(deps, handlerDeps, req, res) {
+    const url = new URL(req.url ?? "/", `http://${UI_HOST}`);
+    const apiPath = isApiPath(url.pathname);
+    applySecurityHeaders(res, await resolveCsp(deps), apiPath);
+    if (!isAllowedHost(req, deps.port)) {
+        rejectForbiddenHost(res);
+        return;
+    }
+    const method = (req.method ?? "GET").toUpperCase();
+    if (apiPath) {
+        await dispatchApi(handlerDeps, req, res, method, url);
+        return;
+    }
+    await serveStatic(res, deps.staticRoot, url.pathname);
+}
+// Creates the BFF server. The caller binds it with `server.listen(deps.port, UI_HOST)` so it never
+// listens on a non-loopback interface. The previous PTY WebSocket upgrade handler is removed —
+// the terminal tool is now bounded-exec over plain HTTP (ADR-0018 D1/D8).
+export function createUiServer(deps) {
+    const handlerDeps = deps.handlerDeps ?? fallbackDeps();
+    const server = createServer((req, res) => {
+        void handle(deps, handlerDeps, req, res).catch(() => {
+            if (!res.headersSent) {
+                writeJson(res, 500, errorBody("INTERNAL", "An unexpected error occurred."));
+            }
+            else {
+                res.end();
+            }
+        });
+    });
+    server.on("upgrade", (_req, socket) => {
+        socket.write("HTTP/1.1 404 Not Found\r\nConnection: close\r\n\r\n");
+        socket.destroy();
+    });
+    return server;
+}

package/dist/sink.d.ts

@@ -0,0 +1,28 @@
+export interface StreamEvent {
+    readonly schemaVersion: "1";
+    readonly runId: string;
+    readonly fingerprint: string;
+    readonly seq: number;
+    readonly ts: number;
+    readonly type: string;
+}
+export interface SseWriter {
+    readonly write: (event: StreamEvent) => boolean | undefined;
+    readonly close: () => void;
+}
+export interface QueueEventSinkOptions {
+    readonly bufferCapacity?: number | undefined;
+}
+export declare class QueueEventSink {
+    private readonly buffer;
+    private readonly capacity;
+    private readonly writers;
+    private terminated;
+    readonly emit: (event: StreamEvent) => void;
+    constructor(options?: QueueEventSinkOptions);
+    attach(writer: SseWriter, afterSeq: number): () => void;
+    closeAll(): void;
+    isTerminated(): boolean;
+    buffered(afterSeq?: number): readonly StreamEvent[];
+}
+//# sourceMappingURL=sink.d.ts.map

package/dist/sink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sink.d.ts","sourceRoot":"","sources":["../src/sink.ts"],"names":[],"mappings":"AAgBA,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,aAAa,EAAE,GAAG,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAGD,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,OAAO,GAAG,SAAS,CAAC;IAC5D,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC;CAC5B;AAID,MAAM,WAAW,qBAAqB;IAEpC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9C;AAED,qBAAa,cAAc;IAEzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,UAAU,CAAS;IAG3B,QAAQ,CAAC,IAAI,GAAI,OAAO,WAAW,KAAG,IAAI,CAiBxC;gBAEU,OAAO,GAAE,qBAA0B;IAO/C,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,IAAI;IAkBvD,QAAQ,IAAI,IAAI;IAWhB,YAAY,IAAI,OAAO;IAKvB,QAAQ,CAAC,QAAQ,SAAK,GAAG,SAAS,WAAW,EAAE;CAGhD"}

package/dist/sink.js

@@ -0,0 +1,80 @@
+// The QueueEventSink bridges the harness's push-only, synchronous EventSink (and the structurally
+// identical workflow WorkflowEventSink / BugWorkflowEventSink) to Server-Sent Events (ADR-0011 D7).
+// It satisfies all three sink shapes — each is `{ emit(event): void }` over an event that carries
+// the `{ schemaVersion, runId, fingerprint, seq, ts, type }` envelope — with one `emit` typed over
+// that structural envelope (no `any`; the concrete unions are assignable to it).
+//
+// It deliberately does NOT set `retainsRawContent`, so the harness emitter redacts every SENSITIVE
+// field before this sink ever receives an event (the browser only sees redacted events). Internally
+// it (a) appends each received event to a per-run BOUNDED ring buffer for replay-on-connect (oldest
+// dropped past the cap), and (b) fans the event out to any currently-attached SSE writers. A late or
+// reconnecting subscriber replays the buffer (respecting Last-Event-ID = the harness `seq`), then
+// receives live events, then a close after the terminal event.
+const DEFAULT_BUFFER_CAPACITY = 512;
+export class QueueEventSink {
+    // retainsRawContent is intentionally absent (never true): the harness must redact before emit.
+    buffer = [];
+    capacity;
+    writers = new Set();
+    terminated = false;
+    // Bound so the sink can be passed directly as an `EventSink`/`WorkflowEventSink`/`BugWorkflowEventSink`.
+    emit = (event) => {
+        this.buffer.push(event);
+        if (this.buffer.length > this.capacity) {
+            this.buffer.shift();
+        }
+        for (const writer of [...this.writers]) {
+            try {
+                const accepted = writer.write(event);
+                if (accepted === false) {
+                    this.writers.delete(writer);
+                    writer.close();
+                }
+            }
+            catch {
+                this.writers.delete(writer);
+                writer.close();
+            }
+        }
+    };
+    constructor(options = {}) {
+        this.capacity = options.bufferCapacity ?? DEFAULT_BUFFER_CAPACITY;
+    }
+    // Attaches an SSE writer: replays the buffered events with `seq` strictly greater than
+    // `afterSeq` (Last-Event-ID resume), then keeps the writer attached for live fan-out. Returns a
+    // detach function the caller invokes on client disconnect to stop fan-out and avoid leaks.
+    attach(writer, afterSeq) {
+        for (const event of this.buffer) {
+            if (event.seq > afterSeq) {
+                const accepted = writer.write(event);
+                if (accepted === false) {
+                    writer.close();
+                    return () => undefined;
+                }
+            }
+        }
+        this.writers.add(writer);
+        return () => {
+            this.writers.delete(writer);
+        };
+    }
+    // Closes and clears every attached writer (called once the run terminates). The ring buffer is
+    // retained for the registry TTL so a late subscriber can still replay history before eviction.
+    closeAll() {
+        if (this.terminated) {
+            return;
+        }
+        this.terminated = true;
+        for (const writer of this.writers) {
+            writer.close();
+        }
+        this.writers.clear();
+    }
+    isTerminated() {
+        return this.terminated;
+    }
+    // Snapshot of buffered events with `seq` strictly greater than `afterSeq` (inspection/replay aid).
+    buffered(afterSeq = -1) {
+        return this.buffer.filter((event) => event.seq > afterSeq);
+    }
+}

package/dist/sse-write.d.ts

@@ -0,0 +1,9 @@
+import type { ServerResponse } from "node:http";
+/**
+ * Writes `frame` to `res`. When `res.write` returns false (TCP send-buffer full / slow client),
+ * aborts `controller` (stops the upstream producer) and destroys the socket.
+ *
+ * Returns the raw boolean from `res.write` so callers can short-circuit if needed.
+ */
+export declare function writeOrDestroy(res: ServerResponse, frame: string, controller: AbortController): boolean;
+//# sourceMappingURL=sse-write.d.ts.map

package/dist/sse-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse-write.d.ts","sourceRoot":"","sources":["../src/sse-write.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,cAAc,EACnB,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,eAAe,GAC1B,OAAO,CAOT"}