@wrenai/genbi 0.0.1

package/dist-server/server/source-driver.js

@@ -0,0 +1,124 @@
+/**
+ * Makes the selected data source's Python driver available before the connect
+ * turn starts, rather than letting the agent discover it is missing.
+ *
+ * wren ships connectors for twenty-one sources but installs almost none of
+ * their drivers: each lives behind an optional extra. Picking a source whose
+ * extra is absent used to fail deep inside the turn with whatever the connector
+ * happened to raise — a bare `ModuleNotFoundError` for most, and for Oracle an
+ * `AttributeError: 'NoneType' object has no attribute 'connect'`, since that
+ * module binds its driver to `None` on ImportError.
+ *
+ * Provisioning happens here, in the BFF, and not in the agent's turn: the
+ * agent-run `pip install` that the onboarding skill's Preflight used to perform
+ * was removed precisely because it could consume the whole turn. A deterministic
+ * step costs no turn budget, is testable, and does not depend on the model
+ * choosing to run it.
+ */
+import { execFile } from "node:child_process";
+import path from "node:path";
+import { realpathSync, statSync } from "node:fs";
+/**
+ * Sources that need no extra: their dependencies are wren's core ones. The four
+ * file sources and `duckdb` all route to wren's duckdb connector, whose driver
+ * is a core dependency; `datafusion` runs in-process on wren-core. Note wren's
+ * own `_INSTALL_EXTRA` maps the file sources to a `duckdb` extra that does not
+ * exist in its pyproject — harmless there because nothing needs installing,
+ * but a reason not to derive the extra name blindly.
+ */
+const NO_EXTRA_SOURCES = new Set(["duckdb", "local_file", "s3_file", "minio_file", "gcs_file", "datafusion", "connection_url"]);
+/** Sources whose driver ships under a differently-named extra (wren's `_INSTALL_EXTRA`). */
+const EXTRA_ALIASES = { doris: "mysql", canner: "postgres" };
+/** The driver extras wren's pyproject actually declares. */
+const DRIVER_EXTRAS = new Set([
+    "postgres", "mysql", "bigquery", "snowflake", "clickhouse", "trino",
+    "mssql", "databricks", "redshift", "spark", "athena", "oracle",
+]);
+/** The extra a source's driver ships under, or undefined when it needs none. */
+export function driverExtraFor(sourceKey) {
+    if (NO_EXTRA_SOURCES.has(sourceKey))
+        return undefined;
+    const extra = EXTRA_ALIASES[sourceKey] ?? sourceKey;
+    return DRIVER_EXTRAS.has(extra) ? extra : undefined;
+}
+/**
+ * The interpreter of the wren install on PATH. `wren` is a console script inside
+ * its environment's `bin/`, so its realpath's sibling `python` is that
+ * environment — the one whose site-packages a connector import will search.
+ */
+export function resolveWrenVenvPython() {
+    const found = process.env["PATH"]
+        ?.split(path.delimiter)
+        .map((dir) => path.join(dir, "wren"))
+        .find((candidate) => {
+        try {
+            return statSync(candidate).isFile();
+        }
+        catch {
+            return false;
+        }
+    });
+    if (found === undefined)
+        return undefined;
+    try {
+        const interpreter = path.join(path.dirname(realpathSync(found)), "python");
+        const stat = statSync(interpreter);
+        return stat.isFile() && (stat.mode & 0o111) !== 0 ? interpreter : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function runUv(args) {
+    return new Promise((resolve) => {
+        execFile("uv", args, { maxBuffer: 32 * 1024 * 1024 }, (error, stdout, stderr) => {
+            resolve({ stdout, stderr, error: error });
+        });
+    });
+}
+/**
+ * Installs the source's driver extra into the wren environment. Idempotent:
+ * `uv pip install` on an already-satisfied extra makes no changes, so this is
+ * safe to run before every connect turn without probing first.
+ *
+ * Installs the extra (`wrenai[postgres]`) rather than the driver package
+ * directly, so the pins come from wren rather than from a second list here.
+ * uv resolves the already-installed editable `wrenai` as satisfying itself, so
+ * this adds the driver without disturbing a local editable checkout.
+ */
+export async function provisionSourceDriver(sourceKey, options = {}) {
+    const extra = driverExtraFor(sourceKey);
+    if (extra === undefined)
+        return { status: "not_needed" };
+    const interpreter = resolveWrenVenvPython();
+    if (interpreter === undefined) {
+        return { status: "unavailable", extra, detail: "could not locate the wren environment's interpreter from PATH" };
+    }
+    const run = options.run ?? runUv;
+    const { stdout, stderr, error } = await run(["pip", "install", "--python", interpreter, `wrenai[${extra}]`]);
+    if (error !== null) {
+        const detail = error.code === "ENOENT" ? "uv is not on PATH" : (stderr.trim() || error.message);
+        return { status: error.code === "ENOENT" ? "unavailable" : "failed", extra, detail };
+    }
+    // uv prints "Installed N packages" only when it changed something; an
+    // already-satisfied extra makes no changes.
+    const changed = /^\s*(Installed|Prepared)\s+\d+\s+package/m.test(stdout) || /^\s*\+ /m.test(stdout);
+    return changed ? { status: "installed", extra } : { status: "ready", extra };
+}
+/** One line describing the outcome for the composed prompt — verifiable, never a promise. */
+export function driverProvisionNote(sourceKey, result) {
+    switch (result.status) {
+        case "not_needed":
+            return `The "${sourceKey}" connector needs no optional driver: its dependencies ship with wren.`;
+        case "installed":
+            return `The "${sourceKey}" driver (wren's "${result.extra}" extra) was just installed into the wren environment.`;
+        case "ready":
+            return `The "${sourceKey}" driver (wren's "${result.extra}" extra) is present in the wren environment.`;
+        default:
+            // Say what is actually known. The agent can check this in one command, so
+            // claiming the driver is available when provisioning did not succeed would
+            // be disproved immediately.
+            return (`The "${sourceKey}" driver (wren's "${result.extra}" extra) could NOT be provisioned: ${result.detail ?? "unknown reason"}. ` +
+                `Do not attempt to install it yourself. If a wren command fails because the driver is missing, stop and report exactly that — do not work around it.`);
+    }
+}

package/dist-server/server/spa.d.ts

@@ -0,0 +1,2 @@
+import type { Hono } from "hono";
+export declare function mountSpaFallback(app: Hono, staticDir: string): void;

package/dist-server/server/spa.js

@@ -0,0 +1,51 @@
+/**
+ * Serves the built SPA (`vite build`'s `dist/`) from the same Hono app as
+ * the BFF's own `/api/*` routes, so a published build can run as one
+ * process on one port instead of a separate static host in front of the
+ * BFF. Mounting is opt-in: `server/app.ts`'s `createApp` only calls
+ * `mountSpaFallback` when `TurnDeps.staticDir` is wired, and `server/bin.ts`
+ * (the only place that wires real production values) only wires it when
+ * `<staticDir>/index.html` actually exists — a dev boot with no `dist/`
+ * never touches this module, so the vite-proxied dev flow is unaffected.
+ *
+ * MUST be mounted last, after every `/api/*` route `createApp` registers.
+ * Hono resolves an overlapping match by registration order — whichever
+ * matching, non-`next()`-calling handler was registered first wins — so a
+ * catch-all mounted any earlier would shadow real routes (worst case: an
+ * SSE route that still "connects" but silently never streams an event).
+ * Both middlewares below additionally check the path themselves rather
+ * than relying on mount order alone, so an `/api/*` request that somehow
+ * reaches this module (no earlier route matched it) still 404s instead of
+ * getting HTML.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { serveStatic } from "@hono/node-server/serve-static";
+function isApiPath(pathname) {
+    return pathname === "/api" || pathname.startsWith("/api/");
+}
+export function mountSpaFallback(app, staticDir) {
+    // Real files (including `/` -> `index.html`, handled internally by
+    // `serveStatic`) are served as-is. `/api/*` is excluded up front so a
+    // request under it is never resolved against `staticDir` at all.
+    app.use("*", async (c, next) => {
+        if (isApiPath(c.req.path))
+            return next();
+        return serveStatic({ root: staticDir })(c, next);
+    });
+    // Anything serveStatic didn't find. Three cases:
+    //  - `/api/*` with no matching route: a real 404, never HTML.
+    //  - `/assets/...` (Vite's own hashed-bundle convention) with no matching
+    //    file: a real 404 — a missing/renamed build asset must not silently
+    //    resolve to `index.html`.
+    //  - anything else: a client-side route; serve `index.html` so the SPA's
+    //    own router can take over.
+    app.get("*", (c) => {
+        if (isApiPath(c.req.path) || c.req.path.startsWith("/assets/"))
+            return c.notFound();
+        const indexPath = path.join(staticDir, "index.html");
+        if (!existsSync(indexPath))
+            return c.notFound();
+        return c.html(readFileSync(indexPath, "utf8"));
+    });
+}

package/dist-server/server/subscription-model-catalog.d.ts

@@ -0,0 +1,27 @@
+import type { SubscriptionModelCatalog, SubscriptionProvider } from "./wire-types.js";
+export interface SubscriptionModelCatalogOptions {
+    readonly agentSdkBin?: string;
+    readonly codexLocalBin?: string;
+    readonly codexHome?: string;
+    readonly codexBin?: string;
+    /** The live project identity used by the runtime, when one is bound. */
+    readonly getUserProject: () => string | undefined;
+    /** Hermetic test seam. It receives no credentials and returns parsed JSON only. */
+    readonly execute?: (provider: SubscriptionProvider) => Promise<unknown>;
+    readonly now?: () => number;
+}
+/** Parses a provider payload into the public allowlist, intentionally discarding every other field. */
+export declare function sanitizeSubscriptionModelCatalog(provider: SubscriptionProvider, payload: unknown): SubscriptionModelCatalog;
+/**
+ * Runs a provider-owned command with bounded output and process-group cleanup.
+ * The test-only `onSpawn` hook observes only a PID; it never crosses the BFF
+ * wire boundary and lets the regression suite prove a TERM-ignoring child is
+ * eventually removed by the group KILL fallback.
+ */
+export declare function spawnJson(command: string, args: readonly string[], options: {
+    readonly env: NodeJS.ProcessEnv;
+    readonly cwd?: string;
+    readonly onSpawn?: (pid: number) => void;
+}): Promise<unknown>;
+/** Builds the BFF seam and owns a small provider-keyed process-memory TTL cache. */
+export declare function createSubscriptionModelCatalog(options: SubscriptionModelCatalogOptions): (provider: SubscriptionProvider, refresh: boolean) => Promise<SubscriptionModelCatalog>;

package/dist-server/server/subscription-model-catalog.js

@@ -0,0 +1,203 @@
+import { spawn } from "node:child_process";
+import { resolveAgentSdkCli } from "../harness/index.js";
+import { resolveCodexLocalCli } from "../harness/route/codex-local-cli.js";
+const CATALOG_TIMEOUT_MS = 15_000;
+const CATALOG_CACHE_MS = 30_000;
+const MAX_OUTPUT_BYTES = 1024 * 1024;
+const TERMINATION_GRACE_MS = 1_000;
+function unavailable(provider, code, retryable = true) {
+    return { version: 1, status: "unavailable", provider, code, retryable };
+}
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : undefined;
+}
+function nonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+function entry(value) {
+    const candidate = record(value);
+    const model = candidate && nonEmptyString(candidate.model);
+    const displayName = candidate && nonEmptyString(candidate.displayName);
+    if (!candidate || !model || !displayName)
+        return undefined;
+    const description = typeof candidate.description === "string" ? candidate.description : undefined;
+    const reasoningEfforts = Array.isArray(candidate.reasoningEfforts)
+        ? candidate.reasoningEfforts.map((effort) => {
+            const item = record(effort);
+            const value = item && nonEmptyString(item.value);
+            const effortDisplayName = item && nonEmptyString(item.displayName);
+            if (!item || !value || !effortDisplayName)
+                return undefined;
+            return {
+                value,
+                displayName: effortDisplayName,
+                ...(typeof item.description === "string" ? { description: item.description } : {}),
+            };
+        }).filter((item) => item !== undefined)
+        : undefined;
+    return {
+        model,
+        displayName,
+        ...(description !== undefined ? { description } : {}),
+        ...(typeof candidate.isDefault === "boolean" ? { isDefault: candidate.isDefault } : {}),
+        ...(reasoningEfforts && reasoningEfforts.length > 0 ? { reasoningEfforts } : {}),
+    };
+}
+/** Parses a provider payload into the public allowlist, intentionally discarding every other field. */
+export function sanitizeSubscriptionModelCatalog(provider, payload) {
+    const result = record(payload);
+    if (!result || result.version !== 1 || result.provider !== provider)
+        return unavailable(provider, "protocol_error", false);
+    if (result.status === "unavailable") {
+        const code = result.code;
+        if (code !== "not_authenticated" && code !== "runtime_unavailable" && code !== "timeout" && code !== "protocol_error") {
+            return unavailable(provider, "protocol_error", false);
+        }
+        return unavailable(provider, code, typeof result.retryable === "boolean" ? result.retryable : true);
+    }
+    if (result.status !== "ready" || !Array.isArray(result.models))
+        return unavailable(provider, "protocol_error", false);
+    const models = result.models.map(entry);
+    if (models.some((model) => model === undefined))
+        return unavailable(provider, "protocol_error", false);
+    return { version: 1, status: "ready", provider, models: models };
+}
+async function runProviderCommand(provider, options) {
+    const cli = provider === "claude"
+        ? await resolveAgentSdkCli(options.agentSdkBin)
+        : await resolveCodexLocalCli(options.codexLocalBin);
+    // `list-models` is intentionally a provider-owned, no-turn command. Its
+    // documented flags mirror the active runtime's project/Codex identity; the
+    // process output still crosses this module only after allowlist validation.
+    const project = options.getUserProject();
+    const args = [
+        ...cli.prefixArgs,
+        "list-models",
+        ...(project ? ["--project", project] : []),
+        ...(provider === "codex" && options.codexHome ? ["--codex-home", options.codexHome] : []),
+        ...(provider === "codex" && options.codexBin ? ["--codex-bin", options.codexBin] : []),
+        "--timeout",
+        String(CATALOG_TIMEOUT_MS),
+    ];
+    return spawnJson(cli.command, args, { env: process.env });
+}
+/**
+ * Runs a provider-owned command with bounded output and process-group cleanup.
+ * The test-only `onSpawn` hook observes only a PID; it never crosses the BFF
+ * wire boundary and lets the regression suite prove a TERM-ignoring child is
+ * eventually removed by the group KILL fallback.
+ */
+export function spawnJson(command, args, options) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, [...args], {
+            env: options.env,
+            ...(options.cwd !== undefined ? { cwd: options.cwd } : {}),
+            stdio: ["ignore", "pipe", "pipe"],
+            detached: process.platform !== "win32",
+        });
+        let stdout = "";
+        let bytes = 0;
+        let settled = false;
+        let timedOut = false;
+        let cleanupStarted = false;
+        const signalProcessGroup = (signal) => {
+            if (child.pid !== undefined && process.platform !== "win32") {
+                try {
+                    process.kill(-child.pid, signal);
+                    return;
+                }
+                catch { /* direct-child fallback */ }
+            }
+            child.kill(signal);
+        };
+        const cleanup = () => {
+            if (cleanupStarted)
+                return;
+            cleanupStarted = true;
+            signalProcessGroup("SIGTERM");
+            // Never clear this fallback on an early caller settlement: the command
+            // may ignore TERM (or have descendants) after the BFF has returned its
+            // sanitized failure. KILLing the detached group prevents a leak.
+            setTimeout(() => signalProcessGroup("SIGKILL"), TERMINATION_GRACE_MS).unref();
+        };
+        const settle = (action) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            action();
+        };
+        const abort = (error) => {
+            cleanup();
+            settle(() => reject(new Error(error)));
+        };
+        if (child.pid !== undefined)
+            options.onSpawn?.(child.pid);
+        const timer = setTimeout(() => {
+            timedOut = true;
+            abort("timeout");
+        }, CATALOG_TIMEOUT_MS);
+        child.stdout.on("data", (chunk) => {
+            if (settled)
+                return;
+            bytes += chunk.length;
+            if (bytes > MAX_OUTPUT_BYTES) {
+                abort("protocol_error");
+                return;
+            }
+            stdout += chunk.toString("utf8");
+        });
+        // Drain stderr without retaining it: provider details must never cross the BFF boundary.
+        child.stderr.resume();
+        child.on("error", () => settle(() => reject(new Error("runtime_unavailable"))));
+        child.on("close", (code) => settle(() => {
+            if (timedOut) {
+                reject(new Error("timeout"));
+                return;
+            }
+            if (code !== 0) {
+                reject(new Error("runtime_unavailable"));
+                return;
+            }
+            try {
+                resolve(JSON.parse(stdout));
+            }
+            catch {
+                reject(new Error("protocol_error"));
+            }
+        }));
+    });
+}
+/** Builds the BFF seam and owns a small provider-keyed process-memory TTL cache. */
+export function createSubscriptionModelCatalog(options) {
+    const cache = new Map();
+    const latestRequest = new Map();
+    const now = options.now ?? Date.now;
+    return async (provider, refresh) => {
+        const cached = cache.get(provider);
+        if (!refresh && cached && cached.expiresAt > now())
+            return cached.result;
+        const requestId = (latestRequest.get(provider) ?? 0) + 1;
+        latestRequest.set(provider, requestId);
+        const writeCacheIfCurrent = (result) => {
+            // A refresh is authoritative over every request that preceded it. An
+            // older promise may still resolve for its original caller, but cannot
+            // replace the provider cache used by subsequent reads.
+            if (latestRequest.get(provider) === requestId) {
+                cache.set(provider, { expiresAt: now() + CATALOG_CACHE_MS, result });
+            }
+            return result;
+        };
+        try {
+            const raw = await (options.execute ? options.execute(provider) : runProviderCommand(provider, options));
+            const result = sanitizeSubscriptionModelCatalog(provider, raw);
+            return writeCacheIfCurrent(result);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "runtime_unavailable";
+            const code = message === "timeout" ? "timeout" : message === "protocol_error" ? "protocol_error" : "runtime_unavailable";
+            const result = unavailable(provider, code, code !== "protocol_error");
+            return writeCacheIfCurrent(result);
+        }
+    };
+}

package/dist-server/server/turn.d.ts

@@ -0,0 +1,249 @@
+import type { AuthChoice, Bundle, LoginProbe, RouteOptions, RouteResult, SetupStepRunner } from "../harness/index.js";
+import type { SubscriptionModelCatalog, SubscriptionProvider } from "./wire-types.js";
+import { type Store } from "./db.js";
+import type { EnrichmentApprovalProvider, EnrichmentApplyRunner, EnrichmentRunner } from "./enrichment.js";
+import type { verifyProposal } from "./enrichment-verify.js";
+import type { EnrichmentBinding } from "./enrichment.js";
+import type { InteractiveTarget, InteractiveTargetReadiness, InteractiveTerminalSession, PreparedInteractiveHandoff } from "./interactive-terminal.js";
+import type { NativeSessionService } from "./native-sessions.js";
+import type { NativeArtifactService } from "./native-artifacts.js";
+import type { NativePurpose } from "./native-dispatch-registry.js";
+import type { AskSessionData, ClarifyEvent, PublishedEvent, PublishScope, SavedEvent, SetupMode, SseFrame, UnsavedEvent } from "./wire-types.js";
+export declare class SessionNotFoundError extends Error {
+    readonly sessionId: string;
+    constructor(sessionId: string);
+}
+export declare class TurnNotFoundError extends Error {
+    readonly turnId: string;
+    constructor(turnId: string);
+}
+export declare class ArtifactNotFoundError extends Error {
+    readonly artifactId: string;
+    constructor(artifactId: string);
+}
+export interface TurnDeps {
+    readonly store: Store;
+    readonly route: (options: RouteOptions) => Promise<RouteResult>;
+    /** A native vendor TUI host, deliberately independent from Ask/SSE. */
+    readonly startInteractiveTerminal?: (input: {
+        readonly target: InteractiveTarget;
+        readonly binding: EnrichmentBinding;
+    }) => Promise<InteractiveTerminalSession>;
+    readonly getInteractiveTerminal?: (id: string) => InteractiveTerminalSession | undefined;
+    /** Revokes compatibility terminals outside the durable NativeSessionService. */
+    readonly revokeInteractiveTerminals?: () => void;
+    readonly interactiveTerminalReadiness?: () => Promise<Record<InteractiveTarget, InteractiveTargetReadiness>>;
+    readonly prepareInteractiveTerminal?: (input: {
+        readonly target: InteractiveTarget;
+        readonly binding: EnrichmentBinding;
+    }) => Promise<PreparedInteractiveHandoff>;
+    /** Durable native Sessions control plane; intentionally distinct from Ask. */
+    /**
+     * Refutes a drafted enrichment proposal before it is offered for approval.
+     * Injected rather than imported so a test can exercise the surrounding flow
+     * without a real project on disk — and, more importantly, so the production
+     * default is the real ladder rather than something a caller can weaken.
+     */
+    readonly verifyEnrichmentProposal?: typeof verifyProposal;
+    readonly nativeSessions?: NativeSessionService;
+    /** Session-scoped MCP persistence service; never used by Ask publish routes. */
+    readonly nativeArtifacts?: NativeArtifactService;
+    readonly baseRouteOptions: Omit<RouteOptions, "question" | "onEvent">;
+    /**
+     * Ask/compile-bind only: compiles+loads the analysis profile's bundle.
+     * Harness purpose introspection uses `describeHarnessBundle` below. Optional so
+     * every other route and every existing test's `TurnDeps` literal is
+     * unaffected — `server/bin.ts` wires the real `describeBundle` (from
+     * `../harness/index.js`); a `TurnDeps` without it simply can't serve
+     * `/api/harness` (that route reports a 500 instead of throwing).
+     */
+    readonly describeBundle?: (options: Omit<RouteOptions, "question" | "onEvent">) => Promise<Bundle>;
+    /**
+     * Harness-only bundle description for one closed native purpose. The
+     * purpose is parsed by the BFF from its read-only query vocabulary; this
+     * dependency resolves the corresponding server-owned profile source. It is
+     * intentionally distinct from native-session IR/launch wiring.
+     */
+    readonly describeHarnessBundle?: (purpose: NativePurpose, options: Omit<RouteOptions, "question" | "onEvent">) => Promise<Bundle>;
+    /**
+     * Compiles the canonical post-bind profile without rebinding its context and
+     * returns its declared tier names. Unlike `describeBundle`, this seam is
+     * intentionally auth-independent and works before a user project is bound.
+     */
+    readonly getRuntimeTierNames?: () => Promise<readonly string[]>;
+    /**
+     * Dispatches a setup-wizard turn (`connect` / `connect_resume` — see
+     * `TurnRow.setupStepKey`) via `harness/setup/runner.ts`'s `SetupStepRunner`
+     * seam, instead of the normal `route()` path. Optional so every existing
+     * test's `TurnDeps` literal is unaffected; a setup turn dispatched against
+     * a `TurnDeps` without this wired resolves as an error turn with a clear
+     * "not configured" message rather than throwing.
+     */
+    readonly setupRunner?: SetupStepRunner;
+    /**
+     * Resolves which `SetupStepRunner` a setup turn should dispatch through,
+     * given the auth choice actually in effect (Claude subscription, Codex
+     * subscription, or non-subscription — the same selection `server/bin.ts`
+     * uses at boot). Optional so every existing test's `TurnDeps` literal is
+     * unaffected: when absent, `resolveSetupRunner` falls back to the fixed
+     * `setupRunner` above (the pre-live-auth-choice behavior). Wired by
+     * `server/bin.ts` so a setup turn dispatches through the runner matching
+     * whatever auth mode is ACTUALLY bound at run time, not the one resolved at
+     * boot.
+     */
+    setupRunnerFor?(choice: AuthChoice): SetupStepRunner;
+    /**
+     * The workspace root new wren projects are scaffolded under
+     * (`WREN_HARNESS_WORKSPACE_ROOT`) — the `root` half of
+     * `parseSetupTerminal`'s `{root, name}` context, and `SetupStepRunOptions.workspaceRoot`.
+     * Optional for the same reason as `setupRunner` above.
+     */
+    readonly workspaceRoot?: string;
+    /**
+     * Binds (or rebinds) the process's single active wren project — the
+     * bootstrap mode's mutable project binding (see `server/bin.ts`). Optional:
+     * a `TurnDeps` built with a fixed `baseRouteOptions.userProject` (every
+     * existing test, and any non-bootstrap boot) simply has no rebinding
+     * capability, which is fine — `resolveUserProject` falls back to the fixed
+     * `baseRouteOptions.userProject` when this isn't wired.
+     */
+    bindProject?(dir: string): void;
+    /**
+     * Reads the process's currently bound project, if any. Optional; when
+     * absent, `resolveUserProject` reads `baseRouteOptions.userProject` instead
+     * (the pre-bootstrap-mode, single-fixed-project behavior).
+     */
+    getUserProject?(): string | undefined;
+    /**
+     * Clears the bootstrap project binding (back to unbound), for the setup
+     * wizard's "Reset setup" action. Optional and symmetric with `bindProject`:
+     * a fixed-project (non-bootstrap) `TurnDeps` has no binding to clear.
+     */
+    unbindProject?(): void;
+    /**
+     * Reads the process's currently bound auth choice, if a live binding is
+     * wired — the auth-choice mirror of `getUserProject`. Optional; when
+     * absent, `resolveAuthChoice` reads `baseRouteOptions.authChoice` instead
+     * (the pre-live-auth-choice, boot-fixed behavior every existing test's
+     * `TurnDeps` literal still gets).
+     */
+    getAuthChoice?(): AuthChoice;
+    /**
+     * Rebinds the process's live auth choice — the auth-choice mirror of
+     * `bindProject`. Wired by `server/bin.ts`; `PUT /api/config/runtime`
+     * (`server/app.ts`) calls this once a candidate `AuthChoice` has passed the
+     * compliance gate, so every later `route()`/setup dispatch reads the live
+     * binding through `resolveAuthChoice`/`effectiveRouteOptions` instead of the
+     * boot-fixed `baseRouteOptions.authChoice`.
+     */
+    setAuthChoice?(choice: AuthChoice): void;
+    /** Injectable, boolean-only subscription login probe used by config UI/API. */
+    readonly loginProbe?: LoginProbe;
+    /** Provider-owned, already-sanitized model discovery for the Setup form. */
+    readonly listSubscriptionModels?: (provider: SubscriptionProvider, refresh: boolean) => Promise<SubscriptionModelCatalog>;
+    /** Optional post-bind enrichment seams; absence is an intentional fail-closed runtime wall. */
+    readonly enrichmentRunner?: EnrichmentRunner;
+    readonly enrichmentApplyRunner?: EnrichmentApplyRunner;
+    readonly enrichmentApprovalProvider?: EnrichmentApprovalProvider;
+    /**
+     * Points every subsequent `wren` CLI subprocess (via `harness/exec/local.ts`'s
+     * `execFile` and `server/adopt.ts`'s own `execWren`, both of which inherit
+     * `process.env` verbatim) at the right `WREN_HOME` for the wizard's chosen
+     * entry path: `"create"` anchors it to `<workspaceRoot>/.wren` so a
+     * scaffolded project's `wren profile add` writes into a fresh,
+     * workspace-scoped `profiles.yml` instead of the operator's real
+     * `~/.wren/profiles.yml`; `"adopt"` (or `undefined`, e.g.
+     * after "Reset setup") restores the real baseline `WREN_HOME` the process
+     * booted with, since adopt is strictly read-only against global state and
+     * must keep resolving the operator's own profiles. Optional so every
+     * existing test's `TurnDeps` literal is unaffected — a `TurnDeps` without
+     * this wired just leaves `process.env.WREN_HOME` untouched (the
+     * pre-isolation behavior). Wired by `server/bin.ts`; called from
+     * `server/app.ts`'s `dispatchConnectTurn` (create) and `POST
+     * /api/setup/adopt` (adopt) — the two single choke points every actual
+     * `wren` invocation for each mode passes through — plus `POST
+     * /api/setup/reset` (restores baseline) so a mode change mid-boot (pick
+     * create, reset, pick adopt, or the reverse) can never leave a stale
+     * `WREN_HOME` from the previous choice in effect.
+     */
+    setWrenHomeForSetupMode?(mode: SetupMode | undefined): void;
+    /**
+     * Absolute path to a built SPA (`vite build`'s `dist/`, containing
+     * `index.html`) to serve from this same process, same origin as every
+     * `/api/*` route below. Optional so every existing test's `TurnDeps`
+     * literal is unaffected: when absent, `server/app.ts`'s `createApp` never
+     * mounts the SPA fallback and the BFF behaves exactly as it does today
+     * (no static serving at all — the dev flow's vite proxy on a separate
+     * port is the only way the UI is served). `server/bin.ts` wires this only
+     * when `<staticDir>/index.html` actually exists, so a dev boot with no
+     * `dist/` present leaves this unset.
+     */
+    readonly staticDir?: string;
+}
+/**
+ * Thrown by `effectiveRouteOptions` when no wren project is bound yet
+ * (bootstrap-mode, before the setup wizard's bind step). Routes that require
+ * a bound project (`server/app.ts`'s 409 guard) check `isProjectBound` first
+ * and never actually let this escape in normal operation — it exists mainly
+ * so a caller that forgets the guard fails loudly instead of silently
+ * compiling against `undefined`.
+ */
+/** Shared 409 message for every route that requires a bound project (`server/app.ts`'s guard) — single source of truth so the guard and `ProjectNotBoundError` never drift apart. */
+export declare const PROJECT_NOT_BOUND_MESSAGE = "no wren project is bound yet \u2014 complete the setup wizard's connect/bind steps first";
+export declare class ProjectNotBoundError extends Error {
+    constructor();
+}
+/** Whether a wren project is currently bound (always true for a `TurnDeps` without `getUserProject` wired — the pre-bootstrap-mode case). */
+export declare function isProjectBound(deps: TurnDeps): boolean;
+/** Resolves the currently-bound project directory, preferring the mutable `getUserProject` binding over the fixed `baseRouteOptions.userProject`. */
+export declare function resolveUserProject(deps: TurnDeps): string | undefined;
+/** Resolves the auth choice actually in effect, preferring the mutable `getAuthChoice` binding over the fixed `baseRouteOptions.authChoice` — the auth-choice mirror of `resolveUserProject`. */
+export declare function resolveAuthChoice(deps: TurnDeps): AuthChoice;
+/** Resolves which `SetupStepRunner` a setup turn should dispatch through, given the auth choice actually in effect. Falls back to the fixed `deps.setupRunner` when `setupRunnerFor` isn't wired (pre-live-auth-choice behavior). */
+export declare function resolveSetupRunner(deps: TurnDeps): SetupStepRunner | undefined;
+/**
+ * `deps.baseRouteOptions` with `userProject`/`authChoice` re-resolved through
+ * their mutable bindings at call time. By default this throws while unbound;
+ * the read-only bootstrap Harness descriptor is the one deliberate exception
+ * and receives an empty project value that its raw-profile path never reads.
+ */
+export declare function effectiveRouteOptions(deps: TurnDeps, options?: {
+    readonly allowUnbound?: boolean;
+}): Omit<RouteOptions, "question" | "onEvent">;
+/** Evicts `deps`'s memoized compiled-bundle-agent-ids entry (see `bundleAgentInfoCache` below) — called by `bindProject` so a turn after a (re)bind recompiles against the newly-bound project instead of replaying a stale/empty cache entry. */
+export declare function invalidateBundleAgentIdsCache(deps: TurnDeps): void;
+export interface PostTurnResult {
+    readonly turnId: string;
+    readonly clarify?: ClarifyEvent;
+}
+/** POST /api/sessions/:id/turns — persists the user event, runs the D1 clarify pre-flight, and either short-circuits with a clarify prompt or prepares a turn for streaming. */
+export declare function postTurn(deps: TurnDeps, sessionId: string, question: string): Promise<PostTurnResult>;
+/** GET (SSE) /api/sessions/:id/stream?turn=:turnId — replays a resolved turn, or executes+streams a pending one. */
+export declare function streamTurn(deps: TurnDeps, sessionId: string, turnId: string, emit: (frame: SseFrame) => Promise<void>, signal?: AbortSignal): Promise<void>;
+/** GET /api/sessions/:id — the Ask page's session snapshot: full event log + the latest turn's work log. */
+export declare function getAskSessionData(store: Store, sessionId: string): AskSessionData;
+/** POST /api/sessions/:id/artifacts/:artifactId/publish */
+export declare function publishArtifactForSession(store: Store, sessionId: string, artifactId: string, scope: PublishScope): PublishedEvent;
+/**
+ * POST /api/sessions/:id/artifacts/:artifactId/save — promotes an
+ * auto-created artifact onto the Artifacts page. Idempotent: a repeat call
+ * on an already-saved artifact returns the same `savedAt` (via
+ * `store.saveArtifact`'s own idempotency) and does NOT insert a second
+ * `SavedEvent` into the session's event log — otherwise every no-op re-save
+ * would grow the persisted history with duplicate events.
+ */
+export declare function saveArtifactForSession(store: Store, sessionId: string, artifactId: string): SavedEvent;
+/**
+ * POST /api/sessions/:id/artifacts/:artifactId/unsave — the
+ * mirror of `saveArtifactForSession`: unpins an artifact from the Artifacts
+ * page. The artifact row and its envelope file are left exactly as they are
+ * — only `saved_at` clears — so the artifact remains re-saveable. Idempotent:
+ * a repeat call on an already-unsaved artifact does NOT append a second
+ * `UnsavedEvent` into the session's event log, for the same reason
+ * `saveArtifactForSession` guards its own repeat calls.
+ *
+ * Appends an `UnsavedEvent` rather than deleting the earlier `SavedEvent` —
+ * the event log is append-only/replayed (see `getAskSessionData`), so
+ * "unsaved" is recorded as a newer fact, never as erasing an older one.
+ */
+export declare function unsaveArtifactForSession(store: Store, sessionId: string, artifactId: string): UnsavedEvent;