@wrenai/genbi 0.0.1

package/dist-server/server/runtime-binding.js

@@ -0,0 +1,258 @@
+/**
+ * Compiles the Setup runtime form into the binding actually consumed by the
+ * harness.  Settings deliberately contain no credential values; this module
+ * reads an API key only while constructing an in-memory in-process adapter spec.
+ */
+import { createHash } from "node:crypto";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { resolveHubDir, resolveWarbleBinary, runWarble } from "../harness/index.js";
+export class RuntimeBindingError extends Error {
+}
+/**
+ * The Claude Agent SDK accepts concrete model ids for its top-level driver,
+ * but its per-step `agents[].model` surface is deliberately narrower. Keep
+ * this product-side contract explicit so an invalid saved Runtime is rejected
+ * before a user turn reaches the dispatcher.
+ */
+export const CLAUDE_AGENT_SDK_PER_STEP_MODELS = ["sonnet", "opus", "haiku", "inherit"];
+const CLAUDE_AGENT_SDK_PER_STEP_MODEL_SET = new Set(CLAUDE_AGENT_SDK_PER_STEP_MODELS);
+function nonEmpty(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+}
+function absoluteHttpUrl(value) {
+    try {
+        const protocol = new URL(value).protocol;
+        return protocol === "http:" || protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+function bindingByTier(settings) {
+    const bindings = new Map();
+    for (const binding of settings.tierModels) {
+        if (!nonEmpty(binding.tier))
+            throw new RuntimeBindingError("A tier binding must name a tier.");
+        if (bindings.has(binding.tier))
+            throw new RuntimeBindingError(`Duplicate tier binding: ${binding.tier}`);
+        bindings.set(binding.tier, binding);
+    }
+    return bindings;
+}
+/** The old single Model field is the default for every tier without a model override. */
+export function effectiveTierModel(binding, settings) {
+    return nonEmpty(binding.model) ?? nonEmpty(settings.apiKeyModel);
+}
+/**
+ * Returns a browser-safe correction for an already persisted Runtime. This is
+ * intentionally narrower than catalog validation: provider catalog entries
+ * remain free-form wherever their dispatcher accepts concrete model ids. Only
+ * Claude's SDK subagent tier field has the closed alias union below.
+ */
+export function runtimeSettingsCorrection(settings) {
+    if (settings.authMode !== "subscription" || settings.subscriptionProvider !== "claude")
+        return undefined;
+    for (const binding of settings.tierModels) {
+        const model = effectiveTierModel(binding, settings);
+        if (model && !CLAUDE_AGENT_SDK_PER_STEP_MODEL_SET.has(model)) {
+            return `Runtime needs correction in Setup: Claude per-step tier "${binding.tier}" must use one of ${CLAUDE_AGENT_SDK_PER_STEP_MODELS.join(", ")}.`;
+        }
+    }
+    return undefined;
+}
+/** Throws the same actionable error at every persisted-runtime dispatch boundary. */
+export function assertRuntimeSettingsDispatchable(settings) {
+    const correction = runtimeSettingsCorrection(settings);
+    if (correction)
+        throw new RuntimeBindingError(correction);
+}
+function requireModel(tier, binding, settings) {
+    const model = effectiveTierModel(binding, settings);
+    if (!model)
+        throw new RuntimeBindingError(`Tier "${tier}" needs a model override or the default Model.`);
+    if (absoluteHttpUrl(model)) {
+        throw new RuntimeBindingError(`Tier "${tier}": Model must be a model name, not a URL — got "${model}". Check that Model and Base URL weren't swapped.`);
+    }
+    return model;
+}
+function requireBaseUrl(tier, binding, settings) {
+    // A row without an explicit adapter is using the legacy/default runtime;
+    // retain its single Base URL as the default just as Model is a default.
+    const baseURL = nonEmpty(binding.baseURL) ?? (binding.adapter === undefined ? nonEmpty(settings.apiKeyBaseURL) : undefined);
+    const adapter = effectiveAdapter(binding, settings);
+    if (!baseURL)
+        throw new RuntimeBindingError(`A Base URL is required for the ${adapter} adapter on tier "${tier}" — there is no default.`);
+    if (!absoluteHttpUrl(baseURL)) {
+        throw new RuntimeBindingError(`Tier "${tier}": Base URL must be an absolute http(s) URL — got "${baseURL}". Check that Model and Base URL weren't swapped.`);
+    }
+    return baseURL;
+}
+function effectiveAdapter(binding, settings) {
+    if (binding.adapter)
+        return binding.adapter;
+    if (settings.authMode === "local")
+        return "local";
+    return settings.apiKeyAdapter ?? "anthropic";
+}
+/** Credential env vars used by the materialized in-process rows (local rows need none). */
+export function requiredInProcessCredentialEnvVars(settings) {
+    const required = new Set();
+    for (const binding of settings.tierModels) {
+        const adapter = effectiveAdapter(binding, settings);
+        if (adapter === "anthropic")
+            required.add("ANTHROPIC_API_KEY");
+        if (adapter === "openai-compatible")
+            required.add("OPENAI_API_KEY");
+    }
+    return [...required];
+}
+/** Validates the complete bundle map before Store/auth/live-route mutation. */
+export function validateRuntimeTierBindings(settings, bundleTiers) {
+    const expected = new Set(bundleTiers);
+    if (expected.size === 0)
+        throw new RuntimeBindingError("The compiled bundle declares no step tiers.");
+    const bindings = bindingByTier(settings);
+    const missing = bundleTiers.filter((tier) => !bindings.has(tier));
+    const extra = [...bindings.keys()].filter((tier) => !expected.has(tier));
+    if (missing.length || extra.length) {
+        const parts = [
+            ...(missing.length ? [`missing: ${missing.join(", ")}`] : []),
+            ...(extra.length ? [`unknown: ${extra.join(", ")}`] : []),
+        ];
+        throw new RuntimeBindingError(`Tier bindings must exactly match the compiled bundle (${parts.join("; ")}).`);
+    }
+    for (const tier of bundleTiers) {
+        const binding = bindings.get(tier);
+        requireModel(tier, binding, settings);
+        const adapter = effectiveAdapter(binding, settings);
+        if (adapter === "openai-compatible" || adapter === "local")
+            requireBaseUrl(tier, binding, settings);
+    }
+    if (settings.authMode === "subscription" && !nonEmpty(settings.subscriptionDriverModel)) {
+        throw new RuntimeBindingError("A subscription dispatcher driver model is required.");
+    }
+    assertRuntimeSettingsDispatchable(settings);
+}
+function inProcessSpec(tier, binding, settings) {
+    const model = requireModel(tier, binding, settings);
+    switch (effectiveAdapter(binding, settings)) {
+        case "anthropic":
+            // The Anthropic adapter reads ANTHROPIC_API_KEY from its environment.
+            return { adapter: "anthropic", config: { model } };
+        case "openai-compatible":
+            // The transient AdapterSpec may carry the env-backed credential, but the
+            // persisted settings and generated YAML never do.
+            return { adapter: "openai-compatible", config: { model, baseURL: requireBaseUrl(tier, binding, settings), apiKey: process.env["OPENAI_API_KEY"] ?? "" } };
+        case "local":
+            return { adapter: "openai-compatible", config: { model, baseURL: requireBaseUrl(tier, binding, settings) } };
+    }
+}
+function dispatchedTierYaml(tier, binding, settings) {
+    const model = requireModel(tier, binding, settings);
+    const adapter = effectiveAdapter(binding, settings);
+    const key = JSON.stringify(tier);
+    if (adapter === "anthropic")
+        return [`  ${key}: ${JSON.stringify(model)}`];
+    return [
+        `  ${key}:`,
+        "    provider: openai_compat",
+        `    endpoint: ${JSON.stringify(requireBaseUrl(tier, binding, settings))}`,
+        `    model: ${JSON.stringify(model)}`,
+    ];
+}
+/** Generates the dispatcher-owned models config without ever serializing an API key. */
+export function writeClaudeModelsConfig(settings, bundleTiers) {
+    const bindings = bindingByTier(settings);
+    const lines = ["tiers:"];
+    for (const tier of bundleTiers)
+        lines.push(...dispatchedTierYaml(tier, bindings.get(tier), settings));
+    // `orchestrator` is a dispatcher driver entry, deliberately separate from
+    // the bundle tier rows that the user edits.
+    lines.push(`  "orchestrator": ${JSON.stringify(nonEmpty(settings.subscriptionDriverModel) ?? "")}`, "");
+    const contents = lines.join("\n");
+    const dir = path.join(tmpdir(), "wren-harness-runtime");
+    mkdirSync(dir, { recursive: true });
+    const filename = `models-${createHash("sha256").update(contents).digest("hex").slice(0, 16)}.yaml`;
+    const output = path.join(dir, filename);
+    writeFileSync(output, contents, { mode: 0o600 });
+    return output;
+}
+export function codexModelsForRuntime(settings) {
+    const bindings = bindingByTier(settings);
+    const model = (tier) => requireModel(tier, bindings.get(tier) ?? { tier }, settings);
+    return {
+        orchestrator: nonEmpty(settings.subscriptionDriverModel) ?? "",
+        cheap: model("cheap"),
+        strong: model("strong"),
+    };
+}
+/** Materializes the already-validated live binding for the selected runtime. */
+export function materializeRuntimeRouteOptions(settings, authChoice) {
+    const tiers = settings.tierModels.map((binding) => binding.tier);
+    if (authChoice.mode === "subscription") {
+        if (authChoice.provider === "codex")
+            return { codexModels: codexModelsForRuntime(settings) };
+        return { modelsConfig: writeClaudeModelsConfig(settings, tiers) };
+    }
+    const bindings = bindingByTier(settings);
+    return {
+        tierBinding: Object.fromEntries(tiers.map((tier) => [tier, inProcessSpec(tier, bindings.get(tier), settings)])),
+    };
+}
+/** Bundle-owned tier names, in first-seen order. */
+export function collectBundleTierNames(bundle) {
+    const seen = new Set();
+    for (const agent of bundle.agents)
+        for (const step of agent.steps)
+            seen.add(step.tier);
+    return [...seen];
+}
+/** Reads the tier contract directly from a compiled Warble IR document. */
+export function collectIrTierNames(ir) {
+    if (ir === null || typeof ir !== "object" || !("components" in ir) || !Array.isArray(ir.components)) {
+        throw new RuntimeBindingError("Compiled profile IR must contain a components array.");
+    }
+    const seen = new Set();
+    for (const component of ir.components) {
+        if (component === null || typeof component !== "object" || !("llm_calls" in component) || !Array.isArray(component.llm_calls)) {
+            throw new RuntimeBindingError("Every compiled profile component must contain an llm_calls array.");
+        }
+        for (const call of component.llm_calls) {
+            if (call === null || typeof call !== "object" || !("tier" in call) || typeof call.tier !== "string" || !call.tier.trim()) {
+                throw new RuntimeBindingError("Every compiled profile llm_call must name a non-empty tier.");
+            }
+            seen.add(call.tier.trim());
+        }
+    }
+    if (seen.size === 0)
+        throw new RuntimeBindingError("The compiled profile declares no llm_call tiers.");
+    return [...seen];
+}
+/**
+ * Compiles the canonical profile source without rebinding its context and
+ * extracts its tier contract from IR. This is intentionally independent of
+ * auth choice and of any user project: the Setup form must discover the rows
+ * before either exists.
+ */
+export async function compileUnboundProfileTierNames(options) {
+    const workDir = await mkdtemp(path.join(tmpdir(), "wren-harness-runtime-tiers-"));
+    try {
+        const irPath = path.join(workDir, "ir.json");
+        const warbleBin = await resolveWarbleBinary(options.warbleBin);
+        // Same reason as the compile pipeline's own invocation (see `resolveHubDir`): name the Hub root
+        // the resolved binary belongs to, so a `warble` that isn't a checkout-local build can't
+        // silently resolve components against the wrong library — or none.
+        const hubDir = resolveHubDir(warbleBin);
+        const hubDirArgs = hubDir !== undefined ? ["--hub-dir", hubDir] : [];
+        await runWarble(warbleBin, ["compile", path.resolve(options.profileSource), "-o", irPath, ...hubDirArgs]);
+        const ir = JSON.parse(await readFile(irPath, "utf8"));
+        return collectIrTierNames(ir);
+    }
+    finally {
+        await rm(workDir, { recursive: true, force: true });
+    }
+}

package/dist-server/server/source-catalog.d.ts

@@ -0,0 +1,84 @@
+/** One connection field, as wren's own JSON-Schema-shaped output describes it. */
+export interface SourceField {
+    readonly name: string;
+    readonly label: string;
+    readonly required: boolean;
+    /** wren marks credential fields with `format: "password"`, including inside an `anyOf`. */
+    readonly secret: boolean;
+    /** wren's own prose for the field, e.g. BigQuery's "Base64 encode `credentials.json`". */
+    readonly description?: string;
+    /** wren's first worked example, shown as the input's placeholder. */
+    readonly example?: string;
+    /**
+     * A value wren fixes for this field. Variant discriminators carry one —
+     * `bigquery_type` is `const: "dataset"` on the dataset variant — so asking
+     * the user to type it is asking them to guess a value that is already known.
+     */
+    readonly fixedValue?: string;
+    /** wren's default, when it has one and the field is not fixed. */
+    readonly defaultValue?: string;
+}
+/**
+ * A source's connection shape. `bigquery`, `redshift` and `databricks` each
+ * publish several — one per authentication style — under `variants`; every
+ * other source publishes exactly one, which we normalize to a single unnamed
+ * variant so consumers need no special case.
+ */
+export interface SourceVariant {
+    readonly name?: string;
+    readonly fields: readonly SourceField[];
+    /**
+     * How wren tells this variant apart: the field it fixes and the value it
+     * fixes it to — `bigquery_type: "dataset"`, `redshift_type: "redshift_iam"`.
+     * The value is the stable, human-meaningful handle for the variant (the
+     * schema's own name is a Python class name), so it is what the UI offers and
+     * what travels on the wire.
+     */
+    readonly discriminator?: {
+        readonly field: string;
+        readonly value: string;
+    };
+}
+export interface CatalogSource {
+    readonly key: string;
+    readonly label: string;
+    readonly variants: readonly SourceVariant[];
+}
+export interface SourceCatalog {
+    readonly sources: readonly CatalogSource[];
+    /**
+     * True when this came from the wren CLI. False means the CLI could not be
+     * read and `sources` is the built-in floor below — a state the API reports
+     * rather than hides, because silently offering four sources when wren
+     * supports twenty-one is the bug this module exists to remove.
+     */
+    readonly fromCli: boolean;
+    /** Why the CLI read failed, when `fromCli` is false. */
+    readonly degradedReason?: string;
+}
+export declare class SourceCatalogError extends Error {
+}
+/** Parses the CLI's JSON. Exported so its edge cases are testable without a wren install. */
+export declare function parseSourceCatalog(raw: string): readonly CatalogSource[];
+/**
+ * Reads the catalog once per process. The registry only changes when the wren
+ * install does, which cannot happen under a running BFF, so a cache costs
+ * nothing in freshness and saves a subprocess on every Setup page load.
+ */
+export declare function loadSourceCatalog(options?: {
+    readonly refresh?: boolean;
+}): Promise<SourceCatalog>;
+/** Test seam: drops the per-process cache. */
+export declare function resetSourceCatalogCache(): void;
+/** The keys Setup will accept for `sourceType`, replacing the old hardcoded allowlist. */
+export declare function supportedSourceTypes(): Promise<ReadonlySet<string>>;
+/**
+ * The `.env` variable names a source's chosen connection shape needs, in the
+ * `<SOURCE>_<FIELD>` form the connect turn writes — with the prefix collapsed
+ * where the field name already carries it (`bigquery_type` -> BIGQUERY_TYPE,
+ * not BIGQUERY_BIGQUERY_TYPE).
+ *
+ * Naming them removes the guesswork that made the same source produce a
+ * different credential form on different runs.
+ */
+export declare function connectionVariableNames(sourceKey: string, variantValue: string): Promise<readonly string[] | undefined>;

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

@@ -0,0 +1,221 @@
+/**
+ * The set of data sources Setup may offer, read from the one place that
+ * actually decides it: the wren CLI's own connector registry, via
+ * `wren docs connection-info --format json`.
+ *
+ * Before this module the same list existed in four hand-maintained copies —
+ * the Setup picker (4 entries), this package's connect/adopt allowlist (8),
+ * a duplicate of that allowlist in the adopt tests (8), and wren's registry
+ * (21) — and they had drifted apart. `app.ts` said so itself: "No canonical
+ * connector-type list is currently exported anywhere in this repo (or in
+ * warble) to import instead — extend this list as wren gains connectors."
+ * There is one now, and it is not a copy.
+ *
+ * The catalog is descriptive, never prescriptive: it reports what wren
+ * supports and what each source's connection needs. Whether a given source's
+ * driver is installed is a separate question, answered by `driver.ts`.
+ */
+import { execFile } from "node:child_process";
+export class SourceCatalogError extends Error {
+}
+/**
+ * The floor used only when the CLI cannot be read. Deliberately the four the
+ * picker shipped before this module, not a guess at the full set: if wren is
+ * unreachable we have no basis for claiming more, and under-offering is
+ * recoverable where offering a source that cannot exist is not.
+ */
+const FALLBACK_SOURCE_KEYS = ["postgres", "bigquery", "snowflake", "duckdb"];
+/** Display names for the sources whose registry key does not read well raw. */
+const DISPLAY_LABELS = {
+    postgres: "PostgreSQL",
+    mysql: "MySQL",
+    mssql: "SQL Server",
+    bigquery: "BigQuery",
+    clickhouse: "ClickHouse",
+    duckdb: "Local file (CSV / DuckDB)",
+    local_file: "Local file",
+    s3_file: "S3 files",
+    gcs_file: "Google Cloud Storage files",
+    minio_file: "MinIO files",
+    datafusion: "DataFusion (in-process files)",
+    canner: "Canner Enterprise",
+    doris: "Apache Doris",
+    spark: "Apache Spark",
+    trino: "Trino",
+    athena: "Amazon Athena",
+    redshift: "Amazon Redshift",
+    databricks: "Databricks",
+    snowflake: "Snowflake",
+    oracle: "Oracle",
+    // Not a database: a raw connection string that bypasses per-source field
+    // validation. Named so nobody reads it as "some product called Connection URL".
+    connection_url: "Other — connection URL",
+};
+function labelFor(key) {
+    return DISPLAY_LABELS[key] ?? key;
+}
+/** `format: "password"` may sit on the property or inside its `anyOf` branches. */
+function isSecret(property) {
+    if (typeof property !== "object" || property === null)
+        return false;
+    const record = property;
+    if (record["format"] === "password")
+        return true;
+    const anyOf = record["anyOf"];
+    return Array.isArray(anyOf) && anyOf.some((branch) => isSecret(branch));
+}
+function stringOf(property, key) {
+    if (typeof property !== "object" || property === null)
+        return undefined;
+    const value = property[key];
+    if (typeof value === "string" && value.length > 0)
+        return value;
+    return typeof value === "number" ? String(value) : undefined;
+}
+function firstExample(property) {
+    if (typeof property !== "object" || property === null)
+        return undefined;
+    const examples = property["examples"];
+    if (!Array.isArray(examples) || examples.length === 0)
+        return undefined;
+    const [first] = examples;
+    return typeof first === "string" ? first : typeof first === "number" ? String(first) : undefined;
+}
+function titleOf(property, name) {
+    if (typeof property === "object" && property !== null) {
+        const title = property["title"];
+        if (typeof title === "string" && title.length > 0)
+            return title;
+    }
+    return name;
+}
+function parseVariant(schema, name) {
+    const properties = schema["properties"];
+    const requiredRaw = schema["required"];
+    const required = new Set(Array.isArray(requiredRaw) ? requiredRaw.filter((entry) => typeof entry === "string") : []);
+    const fields = [];
+    if (typeof properties === "object" && properties !== null) {
+        for (const [fieldName, property] of Object.entries(properties)) {
+            const description = stringOf(property, "description");
+            const example = firstExample(property);
+            const fixedValue = stringOf(property, "const");
+            const defaultValue = fixedValue === undefined ? stringOf(property, "default") : undefined;
+            fields.push({
+                name: fieldName,
+                label: titleOf(property, fieldName),
+                required: required.has(fieldName),
+                secret: isSecret(property),
+                ...(description !== undefined ? { description } : {}),
+                ...(example !== undefined ? { example } : {}),
+                ...(fixedValue !== undefined ? { fixedValue } : {}),
+                ...(defaultValue !== undefined ? { defaultValue } : {}),
+            });
+        }
+    }
+    const discriminatorField = fields.find((field) => field.fixedValue !== undefined);
+    const discriminator = discriminatorField?.fixedValue !== undefined ? { field: discriminatorField.name, value: discriminatorField.fixedValue } : undefined;
+    return {
+        ...(name !== undefined ? { name } : {}),
+        fields,
+        ...(discriminator !== undefined ? { discriminator } : {}),
+    };
+}
+/** Parses the CLI's JSON. Exported so its edge cases are testable without a wren install. */
+export function parseSourceCatalog(raw) {
+    let document;
+    try {
+        document = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new SourceCatalogError(`wren docs connection-info did not return JSON: ${error.message}`);
+    }
+    if (typeof document !== "object" || document === null || Array.isArray(document)) {
+        throw new SourceCatalogError("wren docs connection-info returned a non-object document");
+    }
+    const sources = [];
+    for (const [key, value] of Object.entries(document)) {
+        if (typeof value !== "object" || value === null)
+            continue;
+        const entry = value;
+        const variantsRaw = entry["variants"];
+        if (typeof variantsRaw === "object" && variantsRaw !== null) {
+            const variants = Object.entries(variantsRaw)
+                .filter((pair) => typeof pair[1] === "object" && pair[1] !== null)
+                .map(([variantName, schema]) => parseVariant(schema, variantName));
+            if (variants.length > 0)
+                sources.push({ key, label: labelFor(key), variants });
+            continue;
+        }
+        sources.push({ key, label: labelFor(key), variants: [parseVariant(entry)] });
+    }
+    if (sources.length === 0)
+        throw new SourceCatalogError("wren docs connection-info listed no data sources");
+    return sources;
+}
+function runWrenDocs() {
+    return new Promise((resolve) => {
+        execFile("wren", ["docs", "connection-info", "--format", "json"], { maxBuffer: 32 * 1024 * 1024 }, (error, stdout, stderr) => {
+            resolve({ stdout, stderr, error: error });
+        });
+    });
+}
+function fallbackCatalog(reason) {
+    return {
+        sources: FALLBACK_SOURCE_KEYS.map((key) => ({ key, label: labelFor(key), variants: [] })),
+        fromCli: false,
+        degradedReason: reason,
+    };
+}
+let cached;
+/**
+ * Reads the catalog once per process. The registry only changes when the wren
+ * install does, which cannot happen under a running BFF, so a cache costs
+ * nothing in freshness and saves a subprocess on every Setup page load.
+ */
+export async function loadSourceCatalog(options = {}) {
+    if (cached !== undefined && options.refresh !== true)
+        return cached;
+    const { stdout, stderr, error } = await runWrenDocs();
+    if (error !== null) {
+        const detail = error.code === "ENOENT" ? "the wren CLI is not on PATH" : (stderr.trim() || error.message);
+        cached = fallbackCatalog(`could not read wren's connector registry (${detail})`);
+        return cached;
+    }
+    try {
+        cached = { sources: parseSourceCatalog(stdout), fromCli: true };
+    }
+    catch (parseError) {
+        cached = fallbackCatalog(parseError.message);
+    }
+    return cached;
+}
+/** Test seam: drops the per-process cache. */
+export function resetSourceCatalogCache() {
+    cached = undefined;
+}
+/** The keys Setup will accept for `sourceType`, replacing the old hardcoded allowlist. */
+export async function supportedSourceTypes() {
+    const catalog = await loadSourceCatalog();
+    return new Set(catalog.sources.map((source) => source.key));
+}
+/**
+ * The `.env` variable names a source's chosen connection shape needs, in the
+ * `<SOURCE>_<FIELD>` form the connect turn writes — with the prefix collapsed
+ * where the field name already carries it (`bigquery_type` -> BIGQUERY_TYPE,
+ * not BIGQUERY_BIGQUERY_TYPE).
+ *
+ * Naming them removes the guesswork that made the same source produce a
+ * different credential form on different runs.
+ */
+export async function connectionVariableNames(sourceKey, variantValue) {
+    const catalog = await loadSourceCatalog();
+    const source = catalog.sources.find((entry) => entry.key === sourceKey);
+    const variant = source?.variants.find((entry) => entry.discriminator?.value === variantValue);
+    if (variant === undefined)
+        return undefined;
+    const prefix = sourceKey.toUpperCase();
+    return variant.fields.map((field) => {
+        const upper = field.name.toUpperCase();
+        return upper.startsWith(`${prefix}_`) || upper === prefix ? upper : `${prefix}_${upper}`;
+    });
+}

package/dist-server/server/source-driver.d.ts

@@ -0,0 +1,35 @@
+export type DriverProvisionStatus = "not_needed" | "ready" | "installed" | "failed" | "unavailable";
+export interface DriverProvisionResult {
+    readonly status: DriverProvisionStatus;
+    /** The extra that was (or would be) installed; absent when the source needs none. */
+    readonly extra?: string;
+    /** Human-readable reason, always set for `failed` and `unavailable`. */
+    readonly detail?: string;
+}
+/** The extra a source's driver ships under, or undefined when it needs none. */
+export declare function driverExtraFor(sourceKey: string): string | 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 declare function resolveWrenVenvPython(): string | undefined;
+/**
+ * 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 declare function provisionSourceDriver(sourceKey: string, options?: {
+    readonly run?: (args: readonly string[]) => Promise<{
+        stdout: string;
+        stderr: string;
+        error: NodeJS.ErrnoException | null;
+    }>;
+}): Promise<DriverProvisionResult>;
+/** One line describing the outcome for the composed prompt — verifiable, never a promise. */
+export declare function driverProvisionNote(sourceKey: string, result: DriverProvisionResult): string;