@oscharko-dev/keiko-server 0.2.7 → 0.2.9

package/dist/runtime/containerRunner.js

@@ -0,0 +1,443 @@
+// Issue #1388 (Epic #1491, ADR-0070, D2/D3) — the governed container-run pilot manager. A request
+// names a `taskId` from a server-frozen CLOSED catalog; the server resolves it to a vetted
+// ContainerTask whose image is in a closed allowlist and constructs the EXACT, server-frozen
+// `docker run` argv (no client-supplied image/argv/mount/flag). Execution reuses the single governed
+// runCommand spawn boundary (ADR-0043 D2) exactly as the #1387 command runner does — no Docker SDK,
+// no daemon-socket client, no second spawn path.
+//
+// Engine-unavailable is a GOVERNANCE failure, not an execution outcome: `execute` THROWS
+// ContainerRunnerError("CONTAINER_ENGINE_UNAVAILABLE") BEFORE any run id is minted, so there is no
+// run/event/evidence for a run that never started. Only real execution outcomes become a
+// ContainerRunResult.
+import { randomUUID } from "node:crypto";
+import { CommandCancelledError, CommandDeniedError, CommandTimeoutError, DEFAULT_SANDBOX_POLICY, runCommand, } from "@oscharko-dev/keiko-tools";
+import { nodeSpawnFn } from "@oscharko-dev/keiko-tools/internal/exec";
+import { nodeWorkspaceFs } from "@oscharko-dev/keiko-workspace/internal/fs";
+import { CONTAINER_RUNTIME_SCHEMA_VERSION, CONTAINER_TASK_RULES, } from "@oscharko-dev/keiko-contracts";
+import { ContainerRunnerError } from "./containerRunner-errors.js";
+import { appendContainerRunEvidence, buildContainerRunEvidenceEntry, } from "./containerRunner-evidence.js";
+import { detectContainerEngines } from "./containerEngineDetector.js";
+// Tight cap — a container run is a high-trust surface, so a small number of concurrent runs.
+const MAX_CONCURRENT_CONTAINER_RUNS = 2;
+const MIN_TIMEOUT_MS = 1_000;
+// ─── Defaults (conservative; justified inline) ─────────────────────────────────────
+export const DEFAULT_CONTAINER_RESOURCE_LIMITS = {
+    pidsLimit: 256, // enough for a small toolchain; blocks fork-bombs
+    memoryBytes: 536_870_912, // 512 MiB — bounded, fits a diagnostic image
+    cpus: 1, // single core; deterministic, no host saturation
+};
+// The pilot image is pinned by TAG (not digest) because no published Keiko-vetted digest exists yet;
+// the digest-pin path is documented in docs/container-runtime/security-notes.md and is a one-line
+// change here once a digest is vetted. `--pull never` means the image MUST already be present
+// locally — a missing image is a structured image-missing failure, never a silent network fetch.
+const PILOT_IMAGE = "docker.io/library/alpine:3.20";
+export const DEFAULT_CONTAINER_EXECUTION_POLICY = {
+    // Closed set: exactly the one pinned pilot image. An image ∉ this list → IMAGE_NOT_ALLOWED.
+    imageAllowlist: Object.freeze([PILOT_IMAGE]),
+    limits: DEFAULT_CONTAINER_RESOURCE_LIMITS,
+    mountMode: "read-only",
+    networkMode: "none",
+    workspaceMountPath: "/workspace",
+    pull: "never",
+};
+export const DEFAULT_CONTAINER_TASKS = Object.freeze([
+    {
+        id: "container-pilot:diagnostic",
+        kind: "diagnostic",
+        label: "Container engine pilot diagnostic",
+        image: PILOT_IMAGE,
+        // Trivial in-container command (NOT docker flags). Proves the detection+policy+spawn composition.
+        // Deliberately NOT `sh -c …`: `-c` is a CONTAINER_DENY_FLAGS member (a transitive-shell escalation
+        // flag), so a `-c` anywhere in the argv would self-deny at the runCommand boundary. A bare
+        // `echo …` argv keeps the frozen hardened argv passing isCommandAllowed (the §1.8 LOAD-BEARING
+        // no-self-deny invariant).
+        args: Object.freeze(["echo", "keiko-container-pilot ok"]),
+        engine: "docker",
+    },
+]);
+// ─── Server-frozen argv (D3) — PURE, unit-tested in isolation ──────────────────────
+// Returns the EXACT docker/podman argv. The image MUST already be asserted ∈ policy.imageAllowlist
+// by the caller (execute does this and throws IMAGE_NOT_ALLOWED otherwise); this builder additionally
+// re-asserts so a misuse can never emit a non-allowlisted image. No client input reaches this argv.
+export function buildContainerRunArgv(task, policy, workspaceRoot) {
+    if (!policy.imageAllowlist.includes(task.image)) {
+        throw new ContainerRunnerError("IMAGE_NOT_ALLOWED", "Task image is not allowlisted.");
+    }
+    return [
+        "run",
+        "--rm", // no container persistence (NIST 800-190 4.4)
+        "--network",
+        policy.networkMode, // "none" — the container has no network (4.1.3)
+        "--read-only", // read-only root filesystem (3.1.2 / 4.5.2)
+        "--cap-drop",
+        "ALL", // drop all Linux capabilities (4.5.3)
+        "--security-opt",
+        "no-new-privileges", // forbid privilege escalation (4.5.3)
+        "--pids-limit",
+        String(policy.limits.pidsLimit),
+        "--memory",
+        String(policy.limits.memoryBytes),
+        "--cpus",
+        String(policy.limits.cpus),
+        "--pull",
+        policy.pull, // "never" — the image must already be present locally (3.1.1 / 4.2)
+        "-v",
+        // read-only workspace bind mount at a fixed in-container path; NO read-write/broad host mount,
+        // and NEVER the Docker socket.
+        `${workspaceRoot}:${policy.workspaceMountPath}:ro`,
+        task.image,
+        ...task.args,
+    ];
+}
+const IMAGE_MISSING_SIGNATURES = [
+    "no such image",
+    "unable to find image",
+    "image not known",
+    "manifest unknown",
+];
+const PULL_DENIED_SIGNATURES = [
+    "pull policy",
+    "pull never",
+    "--pull=never",
+    "image must be present",
+];
+const MOUNT_FAILURE_SIGNATURES = [
+    "error mounting",
+    "invalid mount",
+    "bind mount",
+    "no such file or directory", // bind source absent
+    "are you trying to mount",
+];
+function matchesSignature(haystack, signatures) {
+    const lower = haystack.toLowerCase();
+    return signatures.some((needle) => lower.includes(needle));
+}
+// Classifies a NON-ZERO exit into a container-specific failure reason by stderr signature, so the
+// audit distinguishes a missing image / denied pull / mount failure from a plain non-zero exit.
+function classifyNonZeroFailure(stderr) {
+    if (matchesSignature(stderr, IMAGE_MISSING_SIGNATURES))
+        return "image-missing";
+    if (matchesSignature(stderr, PULL_DENIED_SIGNATURES))
+        return "pull-denied";
+    if (matchesSignature(stderr, MOUNT_FAILURE_SIGNATURES))
+        return "mount-failure";
+    return "non-zero-exit";
+}
+function outcomeFromResult(result) {
+    // runCommand resolves only on a real process exit (timeout/cancel reject). A truncation that
+    // killed the child is terminal → output-capped; otherwise classify by exit code + stderr.
+    const failureReason = result.truncated
+        ? "output-capped"
+        : result.exitCode === 0
+            ? "none"
+            : classifyNonZeroFailure(result.stderr);
+    return {
+        exitCode: result.exitCode,
+        durationMs: result.durationMs,
+        truncated: result.truncated,
+        timedOut: false,
+        failureReason,
+        eventKind: failureReason === "none" ? "run-completed" : "run-failed",
+        stdout: result.stdout,
+        stderr: result.stderr,
+    };
+}
+function deniedFailureReason(error) {
+    if (error instanceof CommandDeniedError && !error.message.includes("not found on PATH")) {
+        return "denied";
+    }
+    return "spawn-error";
+}
+function outcomeFromError(error, cancelledByUser, durationMs) {
+    const base = { exitCode: null, durationMs, truncated: false, stdout: "", stderr: "" };
+    if (error instanceof CommandCancelledError || cancelledByUser) {
+        return { ...base, timedOut: false, failureReason: "cancelled", eventKind: "run-cancelled" };
+    }
+    if (error instanceof CommandTimeoutError) {
+        return { ...base, timedOut: true, failureReason: "timed-out", eventKind: "run-failed" };
+    }
+    return {
+        ...base,
+        timedOut: false,
+        failureReason: deniedFailureReason(error),
+        eventKind: "run-failed",
+    };
+}
+function clampTimeout(requested, ceiling) {
+    if (requested === undefined || !Number.isFinite(requested)) {
+        return ceiling;
+    }
+    const rounded = Math.round(requested);
+    if (rounded <= MIN_TIMEOUT_MS)
+        return MIN_TIMEOUT_MS;
+    if (rounded >= ceiling)
+        return ceiling;
+    return rounded;
+}
+function requestIdPayload(input) {
+    return input.requestId === undefined ? {} : { requestId: input.requestId };
+}
+function projectFor(store, projectId) {
+    for (const project of store.listProjects()) {
+        if (project.path === projectId) {
+            return project;
+        }
+    }
+    return undefined;
+}
+function projectRootOrThrow(project) {
+    try {
+        return nodeWorkspaceFs.realPath(project.path);
+    }
+    catch {
+        throw new ContainerRunnerError("PROJECT_NOT_FOUND", "Project root path could not be resolved.");
+    }
+}
+function buildWorkspaceInfo(projectRoot) {
+    return {
+        root: projectRoot,
+        name: undefined,
+        version: undefined,
+        testFramework: "unknown",
+        sourceDirs: [],
+        testDirs: [],
+        languages: [],
+        ignoreLines: [],
+    };
+}
+class ContainerRunnerManagerImpl {
+    store;
+    evidenceStore;
+    policy;
+    executionPolicy;
+    catalog;
+    processEnv;
+    redactor;
+    runDeps;
+    detect;
+    now;
+    runs = new Map();
+    subscribers = new Set();
+    constructor(opts) {
+        this.store = opts.store;
+        this.evidenceStore = opts.evidenceStore;
+        this.policy = opts.policy ?? DEFAULT_SANDBOX_POLICY;
+        this.executionPolicy = opts.executionPolicy ?? DEFAULT_CONTAINER_EXECUTION_POLICY;
+        this.catalog = opts.catalog ?? DEFAULT_CONTAINER_TASKS;
+        this.processEnv = opts.processEnv ?? process.env;
+        this.redactor = opts.redactor ?? ((input) => input);
+        this.runDeps = opts.runDeps ?? {};
+        this.detect = opts.detect;
+        this.now = opts.now ?? Date.now;
+    }
+    inFlightCount = () => this.runs.size;
+    subscribe = (listener) => {
+        this.subscribers.add(listener);
+        return () => {
+            this.subscribers.delete(listener);
+        };
+    };
+    abort = (runId) => {
+        const entry = this.runs.get(runId);
+        if (entry === undefined)
+            return false;
+        entry.cancelledByUser = true;
+        entry.controller.abort();
+        return true;
+    };
+    capability = (projectId) => {
+        return this.resolveCapability(projectId);
+    };
+    listCatalog = async (projectId) => {
+        const capability = await this.resolveCapability(projectId);
+        // Graceful degradation: no engine → engineAvailable:false + tasks:[] (never an error).
+        const engineAvailable = capability.anyAvailable;
+        return {
+            schemaVersion: CONTAINER_RUNTIME_SCHEMA_VERSION,
+            projectId,
+            engineAvailable,
+            tasks: engineAvailable ? this.catalog : [],
+        };
+    };
+    execute = async (input) => {
+        const workspace = this.resolveWorkspace(input.projectId);
+        // Engine-unavailable is a GOVERNANCE failure: throw BEFORE minting a run id (route → 503).
+        const capability = await this.resolveCapability(input.projectId);
+        if (!capability.anyAvailable) {
+            throw new ContainerRunnerError("CONTAINER_ENGINE_UNAVAILABLE", "No container engine is available.");
+        }
+        const task = this.catalog.find((entry) => entry.id === input.taskId);
+        if (task === undefined) {
+            throw new ContainerRunnerError("TASK_NOT_FOUND", "Task is not in the container catalog.");
+        }
+        if (!this.executionPolicy.imageAllowlist.includes(task.image)) {
+            throw new ContainerRunnerError("IMAGE_NOT_ALLOWED", "Task image is not allowlisted.");
+        }
+        if (this.runs.size >= MAX_CONCURRENT_CONTAINER_RUNS) {
+            throw new ContainerRunnerError("RUN_LIMIT_EXCEEDED", "Too many in-flight container runs.");
+        }
+        return this.runExecution(task, workspace, input);
+    };
+    resolveCapability(projectId) {
+        if (this.detect !== undefined) {
+            return this.detect(projectId);
+        }
+        const probeDeps = {
+            runCommand,
+            workspace: this.tryWorkspace(projectId),
+            policy: this.policy,
+            processEnv: this.processEnv,
+            now: this.now,
+        };
+        return detectContainerEngines(probeDeps);
+    }
+    tryWorkspace(projectId) {
+        const project = projectFor(this.store, projectId);
+        if (project === undefined) {
+            return undefined;
+        }
+        try {
+            return buildWorkspaceInfo(projectRootOrThrow(project));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    resolveWorkspace(projectId) {
+        const project = projectFor(this.store, projectId);
+        if (project === undefined) {
+            throw new ContainerRunnerError("PROJECT_NOT_FOUND", "Project not found.");
+        }
+        return buildWorkspaceInfo(projectRootOrThrow(project));
+    }
+    buildRunDeps(workspace) {
+        return {
+            workspace,
+            // Host CLI policy: network:"inherit" so the docker/podman CLI reaches the daemon socket. The
+            // CONTAINER is isolated by --network none in the frozen argv (D4).
+            policy: { ...this.policy, network: "inherit" },
+            commandRules: CONTAINER_TASK_RULES,
+            spawn: this.runDeps.spawn ?? nodeSpawnFn,
+            processEnv: this.processEnv,
+            now: this.runDeps.now ?? this.now,
+            ...(this.runDeps.resolveExecutable === undefined
+                ? {}
+                : { resolveExecutable: this.runDeps.resolveExecutable }),
+            ...(this.runDeps.fs === undefined ? {} : { fs: this.runDeps.fs }),
+            ...(this.runDeps.home === undefined ? {} : { home: this.runDeps.home }),
+        };
+    }
+    async runExecution(task, workspace, input) {
+        const runId = randomUUID();
+        const controller = new AbortController();
+        const entry = { controller, cancelledByUser: false };
+        this.runs.set(runId, entry);
+        const startedAt = this.now();
+        this.emit({
+            kind: "run-started",
+            runId,
+            payload: {
+                taskId: task.id,
+                kind: task.kind,
+                engine: task.engine,
+                startedAt,
+                ...requestIdPayload(input),
+            },
+        });
+        try {
+            return await this.invoke(runId, task, workspace, input, entry, startedAt);
+        }
+        finally {
+            this.runs.delete(runId);
+        }
+    }
+    async invoke(runId, task, workspace, input, entry, startedAt) {
+        const deps = this.buildRunDeps(workspace);
+        const argv = buildContainerRunArgv(task, this.executionPolicy, workspace.root);
+        const timeoutMs = clampTimeout(input.timeoutMs, this.policy.defaultTimeoutMs);
+        try {
+            // Single governed spawn boundary; the injected fake spawn (if any) rides in `deps.spawn`.
+            const result = await runCommand({
+                command: task.engine,
+                args: argv,
+                cwd: undefined,
+                timeoutMs,
+                signal: entry.controller.signal,
+            }, deps);
+            return this.finalize(runId, task, argv.length, input, outcomeFromResult(result), startedAt);
+        }
+        catch (error) {
+            const outcome = outcomeFromError(error, entry.cancelledByUser, this.now() - startedAt);
+            return this.finalize(runId, task, argv.length, input, outcome, startedAt);
+        }
+    }
+    finalize(runId, task, argCount, input, outcome, startedAt) {
+        this.persist(runId, task, argCount, input, outcome, startedAt);
+        this.emit({
+            kind: outcome.eventKind,
+            runId,
+            payload: {
+                exitCode: outcome.exitCode,
+                durationMs: outcome.durationMs,
+                truncated: outcome.truncated,
+                timedOut: outcome.timedOut,
+                failureReason: outcome.failureReason,
+                ...requestIdPayload(input),
+            },
+        });
+        return {
+            schemaVersion: CONTAINER_RUNTIME_SCHEMA_VERSION,
+            runId,
+            taskId: task.id,
+            kind: task.kind,
+            engine: task.engine,
+            exitCode: outcome.exitCode,
+            durationMs: outcome.durationMs,
+            truncated: outcome.truncated,
+            timedOut: outcome.timedOut,
+            failureReason: outcome.failureReason,
+            stdout: outcome.stdout,
+            stderr: outcome.stderr,
+        };
+    }
+    persist(runId, task, argCount, input, outcome, startedAt) {
+        if (this.evidenceStore === undefined)
+            return;
+        try {
+            const evidence = buildContainerRunEvidenceEntry({
+                runId,
+                projectId: input.projectId,
+                taskId: task.id,
+                kind: task.kind,
+                engine: task.engine,
+                imageId: task.id, // closed-catalog id, NOT the raw image ref free-text
+                argCount,
+                exitCode: outcome.exitCode,
+                durationMs: outcome.durationMs,
+                timedOut: outcome.timedOut,
+                truncated: outcome.truncated,
+                failureReason: outcome.failureReason,
+                stdoutBytes: Buffer.byteLength(outcome.stdout, "utf8"),
+                stderrBytes: Buffer.byteLength(outcome.stderr, "utf8"),
+                startedAt,
+            });
+            appendContainerRunEvidence(this.evidenceStore, evidence, this.redactor);
+        }
+        catch {
+            // Evidence is best-effort process-evidence; a write hiccup must not corrupt a real run result.
+        }
+    }
+    emit(event) {
+        for (const listener of [...this.subscribers]) {
+            try {
+                listener(event);
+            }
+            catch {
+                // A subscriber throwing must not stop fan-out (matches the command-runner pattern).
+            }
+        }
+    }
+}
+export function createContainerRunnerManager(opts) {
+    return new ContainerRunnerManagerImpl(opts);
+}

package/dist/server.d.ts.map

@@ -1 +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"}
+{"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;AAM9D,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;AAiKD,wBAAgB,cAAc,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CA2BzD"}

package/dist/server.js

@@ -8,6 +8,8 @@ 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 { isVoiceDictationCapable, isVoiceRealtimeCapable } from "./read-handlers.js";
+import { createVoiceControlPlane } from "./voice-realtime.js";
 import { createRunRegistry } from "./runs.js";
 import { createInMemoryUiStore } from "./store/index.js";
 export const DEFAULT_UI_PORT = 1983;
@@ -117,7 +119,12 @@ async function resolveCsp(deps) {
 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);
+    // Issue #495/#497 — scope the Permissions-Policy microphone directive to deployments that advertise
+    // speech-to-text dictation OR full-realtime voice (whose WebRTC capture track also needs the mic);
+    // a no-voice deployment keeps the strict `microphone=()` default, never widened beyond `(self)`.
+    applySecurityHeaders(res, await resolveCsp(deps), apiPath, {
+        allowMicrophone: isVoiceDictationCapable(handlerDeps) || isVoiceRealtimeCapable(handlerDeps),
+    });
     if (!isAllowedHost(req, deps.port)) {
         rejectForbiddenHost(res);
         return;
@@ -130,10 +137,16 @@ async function handle(deps, handlerDeps, req, res) {
     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).
+// 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). Issue #497 (ADR-0058 D3,
+// ADR-0059) re-opens the upgrade for the single loopback voice control path `/api/voice/control`, and
+// ONLY when the deployment is full-realtime voice capable; every other upgrade keeps the hard reject.
 export function createUiServer(deps) {
     const handlerDeps = deps.handlerDeps ?? fallbackDeps();
+    const voiceControl = createVoiceControlPlane({
+        port: deps.port,
+        handlerDeps: () => handlerDeps,
+    });
     const server = createServer((req, res) => {
         void handle(deps, handlerDeps, req, res).catch(() => {
             if (!res.headersSent) {
@@ -144,9 +157,16 @@ export function createUiServer(deps) {
             }
         });
     });
-    server.on("upgrade", (_req, socket) => {
+    server.on("upgrade", (req, socket, head) => {
+        if (voiceControl.handleUpgrade(req, socket, head)) {
+            return;
+        }
+        // Default: every non-voice-control or ungated upgrade is hard-rejected, as before.
         socket.write("HTTP/1.1 404 Not Found\r\nConnection: close\r\n\r\n");
         socket.destroy();
     });
+    server.on("close", () => {
+        voiceControl.closeAll();
+    });
     return server;
 }

package/dist/store/db.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../src/store/db.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAI3C,OAAO,KAAK,EAMV,OAAO,EACP,qBAAqB,EAKtB,MAAM,YAAY,CAAC;AAiCpB,wBAAgB,kBAAkB,CAAC,OAAO,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAM9E;AA+JD,eAAO,MAAM,qBAAqB,OAAQ,CAAC;AAa3C,wBAAgB,qBAAqB,CAAC,IAAI,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAI3E;AAgCD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAkB/D;AAED,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,YAAY,EAAE,IAAI,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAEhG;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAEvF"}
+{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../src/store/db.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAI3C,OAAO,KAAK,EAMV,OAAO,EACP,qBAAqB,EAKtB,MAAM,YAAY,CAAC;AAkCpB,wBAAgB,kBAAkB,CAAC,OAAO,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAM9E;AAiKD,eAAO,MAAM,qBAAqB,OAAQ,CAAC;AAa3C,wBAAgB,qBAAqB,CAAC,IAAI,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAI3E;AAgCD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAkB/D;AAED,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,YAAY,EAAE,IAAI,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAEhG;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAEvF"}

package/dist/store/db.js

@@ -8,7 +8,7 @@ import { randomUUID } from "node:crypto";
 import { runMigrations } from "./schema.js";
 import { deleteProject as sqlDeleteProject, getProject as sqlGetProject, listProjects as sqlListProjects, updateProject as sqlUpdateProject, upsertProject as sqlUpsertProject, } from "./projects.js";
 import { deleteChat as sqlDeleteChat, findChatById as sqlFindChatById, insertChat as sqlInsertChat, listChats as sqlListChats, listChatsLimited as sqlListChatsLimited, touchChat as sqlTouchChat, updateChat as sqlUpdateChat, } from "./chats.js";
-import { findMessageById as sqlFindMessageById, insertMessage as sqlInsertMessage, listMessages as sqlListMessages, listMessagesLimited as sqlListMessagesLimited, updateMessage as sqlUpdateMessage, } from "./messages.js";
+import { findMessageById as sqlFindMessageById, attachGroundedAnswer as sqlAttachGroundedAnswer, insertMessage as sqlInsertMessage, listMessages as sqlListMessages, listMessagesLimited as sqlListMessagesLimited, updateMessage as sqlUpdateMessage, } from "./messages.js";
 import { validateProjectPath } from "./validation.js";
 import { basename } from "node:path";
 import { invalidRequest } from "./errors.js";
@@ -111,6 +111,7 @@ function buildStore(db, options) {
         },
         createMessages: (messages) => createMessageBatch(db, options, messages),
         updateMessage: (id, patch) => sqlUpdateMessage(db, id, patch, options.redactString),
+        attachGroundedAnswer: (id, answer) => sqlAttachGroundedAnswer(db, id, answer, options.redactString),
         close: () => {
             db.close();
         },

package/dist/store/index.d.ts

@@ -1,4 +1,4 @@
-export type { Chat, ChatConnectedScope, ChatLocalKnowledgeScope, ChatMessage, ChatRole, CreateChatOptions, NewChatMessage, Project, UiStore, UiStoreFactoryOptions, UpdateChatOptions, UpdateChatMessagePatch, UpdateChatPatch, UpdateProjectPatch, WorkflowStatus, } from "./types.js";
+export type { Chat, ChatConnectedScope, ChatLocalKnowledgeScope, ChatMessage, ChatRole, CreateChatOptions, GroundedAnswer, NewChatMessage, Project, UiStore, UiStoreFactoryOptions, UpdateChatOptions, UpdateChatMessagePatch, UpdateChatPatch, UpdateProjectPatch, WorkflowStatus, } from "./types.js";
 export { UiStoreError, type UiStoreErrorCode, invalidPath, invalidRequest, notFound, pathNotDirectory, pathNotFound, projectExists, } from "./errors.js";
 export { classifyPathShape, validateProjectPath, type PathShape, type ValidateProjectPathOptions, } from "./validation.js";
 export { assertUiDbOutsideProject, resolveUiDbPath, UI_DB_FILENAME, UI_DB_DIRNAME, } from "./paths.js";

package/dist/store/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/store/index.ts"],"names":[],"mappings":"AAEA,YAAY,EACV,IAAI,EACJ,kBAAkB,EAClB,uBAAuB,EACvB,WAAW,EACX,QAAQ,EACR,iBAAiB,EACjB,cAAc,EACd,OAAO,EACP,OAAO,EACP,qBAAqB,EACrB,iBAAiB,EACjB,sBAAsB,EACtB,eAAe,EACf,kBAAkB,EAClB,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,YAAY,EACZ,KAAK,gBAAgB,EACrB,WAAW,EACX,cAAc,EACd,QAAQ,EACR,gBAAgB,EAChB,YAAY,EACZ,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,KAAK,SAAS,EACd,KAAK,0BAA0B,GAChC,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,wBAAwB,EACxB,eAAe,EACf,cAAc,EACd,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/store/index.ts"],"names":[],"mappings":"AAEA,YAAY,EACV,IAAI,EACJ,kBAAkB,EAClB,uBAAuB,EACvB,WAAW,EACX,QAAQ,EACR,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,OAAO,EACP,OAAO,EACP,qBAAqB,EACrB,iBAAiB,EACjB,sBAAsB,EACtB,eAAe,EACf,kBAAkB,EAClB,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,YAAY,EACZ,KAAK,gBAAgB,EACrB,WAAW,EACX,cAAc,EACd,QAAQ,EACR,gBAAgB,EAChB,YAAY,EACZ,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,KAAK,SAAS,EACd,KAAK,0BAA0B,GAChC,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,wBAAwB,EACxB,eAAe,EACf,cAAc,EACd,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,SAAS,CAAC"}

package/dist/store/messages.d.ts

@@ -1,8 +1,9 @@
 import type { DatabaseSync } from "node:sqlite";
-import type { ChatMessage, NewChatMessage, UpdateChatMessagePatch } from "./types.js";
+import type { ChatMessage, GroundedAnswer, NewChatMessage, UpdateChatMessagePatch } from "./types.js";
 export declare function listMessages(db: DatabaseSync, chatId: string): readonly ChatMessage[];
 export declare function listMessagesLimited(db: DatabaseSync, chatId: string, limit: number): readonly ChatMessage[];
 export declare function findMessageById(db: DatabaseSync, id: string): ChatMessage | undefined;
 export declare function insertMessage(db: DatabaseSync, id: string, msg: NewChatMessage, redactString: (s: string) => string): ChatMessage;
+export declare function attachGroundedAnswer(db: DatabaseSync, id: string, answer: GroundedAnswer, redactString: (s: string) => string): ChatMessage;
 export declare function updateMessage(db: DatabaseSync, id: string, patch: UpdateChatMessagePatch, redactString: (s: string) => string): ChatMessage;
 //# sourceMappingURL=messages.d.ts.map

package/dist/store/messages.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../../src/store/messages.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EACV,WAAW,EAEX,cAAc,EACd,sBAAsB,EAEvB,MAAM,YAAY,CAAC;AA+GpB,wBAAgB,YAAY,CAAC,EAAE,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,WAAW,EAAE,CAErF;AAED,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,YAAY,EAChB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ,SAAS,WAAW,EAAE,CAOxB;AAED,wBAAgB,eAAe,CAAC,EAAE,EAAE,YAAY,EAAE,EAAE,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAGrF;AAED,wBAAgB,aAAa,CAC3B,EAAE,EAAE,YAAY,EAChB,EAAE,EAAE,MAAM,EACV,GAAG,EAAE,cAAc,EACnB,YAAY,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,GAClC,WAAW,CAoBb;AAOD,wBAAgB,aAAa,CAC3B,EAAE,EAAE,YAAY,EAChB,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,sBAAsB,EAC7B,YAAY,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,GAClC,WAAW,CA6Bb"}
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../../src/store/messages.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EACV,WAAW,EAEX,cAAc,EACd,cAAc,EACd,sBAAsB,EAEvB,MAAM,YAAY,CAAC;AA4IpB,wBAAgB,YAAY,CAAC,EAAE,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,WAAW,EAAE,CAErF;AAED,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,YAAY,EAChB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ,SAAS,WAAW,EAAE,CAOxB;AAED,wBAAgB,eAAe,CAAC,EAAE,EAAE,YAAY,EAAE,EAAE,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAGrF;AAED,wBAAgB,aAAa,CAC3B,EAAE,EAAE,YAAY,EAChB,EAAE,EAAE,MAAM,EACV,GAAG,EAAE,cAAc,EACnB,YAAY,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,GAClC,WAAW,CAsBb;AAED,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,YAAY,EAChB,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,cAAc,EACtB,YAAY,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,GAClC,WAAW,CAcb;AAOD,wBAAgB,aAAa,CAC3B,EAAE,EAAE,YAAY,EAChB,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,sBAAsB,EAC7B,YAAY,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,GAClC,WAAW,CA6Bb"}

package/dist/store/messages.js

@@ -17,7 +17,18 @@ const STATUSES = new Set([
     "failed",
     "cancelled",
 ]);
+function parseGroundedAnswer(raw) {
+    if (raw === null)
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
 function rowToMessage(row) {
+    const groundedAnswer = parseGroundedAnswer(row.grounded_answer_json);
     return {
         id: row.id,
         chatId: row.chat_id,
@@ -29,17 +40,18 @@ function rowToMessage(row) {
         workflowStatus: (row.workflow_status ?? undefined),
         shortResult: row.short_result ?? undefined,
         taskType: row.task_type ?? undefined,
+        ...(groundedAnswer === undefined ? {} : { groundedAnswer }),
     };
 }
-const COLUMNS = "id, chat_id, role, content, timestamp, run_id, workflow_id, workflow_status, short_result, task_type";
+const COLUMNS = "id, chat_id, role, content, timestamp, run_id, workflow_id, workflow_status, short_result, task_type, grounded_answer_json";
 const SQL_LIST = `SELECT ${COLUMNS} FROM chat_messages WHERE chat_id = ? ORDER BY timestamp ASC, rowid ASC`;
 const SQL_LIST_LIMITED = `${SQL_LIST} LIMIT ?`;
 const SQL_FIND_BY_ID = `SELECT ${COLUMNS} FROM chat_messages WHERE id = ? LIMIT 1`;
 const SQL_CHAT_EXISTS = "SELECT 1 FROM chats WHERE id = ?";
 const SQL_INSERT = `
 INSERT INTO chat_messages
-  (id, chat_id, role, content, timestamp, run_id, workflow_id, workflow_status, short_result, task_type)
-VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  (id, chat_id, role, content, timestamp, run_id, workflow_id, workflow_status, short_result, task_type, grounded_answer_json)
+VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
 RETURNING ${COLUMNS}
 `;
 function validateTaskType(value) {
@@ -66,6 +78,9 @@ function validateRunSummaryScope(msg) {
     if (hasRunSummaryFields(msg) && (msg.role !== "system" || msg.runId === undefined)) {
         throw invalidRequest("Run summary fields require a system message with runId.");
     }
+    if (msg.groundedAnswer !== undefined && msg.role !== "assistant") {
+        throw invalidRequest("Grounded answer metadata requires an assistant message.");
+    }
 }
 function validateMessage(msg) {
     if (!ROLES.has(msg.role))
@@ -86,6 +101,18 @@ function processShortResult(raw, redactString) {
     const redacted = redactString(raw);
     return redacted.length > MAX_SHORT_RESULT ? redacted.slice(0, MAX_SHORT_RESULT) : redacted;
 }
+function processGroundedAnswer(raw, redactString) {
+    if (raw === undefined)
+        return null;
+    const redacted = redactString(JSON.stringify(raw));
+    try {
+        JSON.parse(redacted);
+    }
+    catch {
+        throw invalidRequest("Grounded answer metadata is invalid.");
+    }
+    return redacted;
+}
 export function listMessages(db, chatId) {
     return db.prepare(SQL_LIST).all(chatId).map(rowToMessage);
 }
@@ -105,9 +132,24 @@ export function insertMessage(db, id, msg, redactString) {
     if (!chatExists)
         throw notFound("Chat");
     const shortResult = processShortResult(msg.shortResult, redactString);
+    const groundedAnswer = processGroundedAnswer(msg.groundedAnswer, redactString);
     const row = db
         .prepare(SQL_INSERT)
-        .get(id, msg.chatId, msg.role, msg.content, msg.timestamp, msg.runId ?? null, msg.workflowId ?? null, msg.workflowStatus ?? null, shortResult, msg.taskType ?? null);
+        .get(id, msg.chatId, msg.role, msg.content, msg.timestamp, msg.runId ?? null, msg.workflowId ?? null, msg.workflowStatus ?? null, shortResult, msg.taskType ?? null, groundedAnswer);
+    return rowToMessage(row);
+}
+export function attachGroundedAnswer(db, id, answer, redactString) {
+    const groundedAnswer = processGroundedAnswer(answer, redactString);
+    const row = db
+        .prepare(`
+        UPDATE chat_messages
+        SET grounded_answer_json = ?
+        WHERE id = ? AND role = 'assistant'
+        RETURNING ${COLUMNS}
+      `)
+        .get(groundedAnswer, id);
+    if (row === undefined)
+        throw notFound("Message");
     return rowToMessage(row);
 }
 // Issue #66 — Partial PATCH on a system run-summary message. Builds a dynamic SET clause from the

package/dist/store/schema.d.ts

@@ -1,4 +1,4 @@
 import type { DatabaseSync } from "node:sqlite";
-export declare const SCHEMA_VERSION = 5;
+export declare const SCHEMA_VERSION = 8;
 export declare function runMigrations(db: DatabaseSync): void;
 //# sourceMappingURL=schema.d.ts.map