@oscharko-dev/keiko 0.1.0-beta.0 → 0.1.0-beta.3

package/dist/ui/chat-handlers.js

@@ -2,12 +2,13 @@
 // behind the existing ModelPort/Gateway boundary: the browser sends only chat content and a registry
 // model id, while provider endpoints and keys remain resolved from the local gateway config/.env.
 import { basename } from "node:path";
-import { GatewayError, findCapability } from "../gateway/index.js";
+import { GatewayError, findCapability, findConfiguredCapability, listConfiguredCapabilities, } from "../gateway/index.js";
 import { UiStoreError, isProjectAvailable, } from "./store/index.js";
 import { validateProjectPath } from "./store/validation.js";
+import { currentGatewayConfig } from "./deps.js";
 import { errorBody } from "./routes.js";
-const DEFAULT_CHAT_MODEL = "gpt-oss-120b";
-const DEFAULT_CHAT_TITLE = "GPT OSS 120B";
+const DEFAULT_CHAT_MODEL = "example-chat-model";
+const DEFAULT_CHAT_TITLE = "New chat";
 const MAX_BODY_BYTES = 128_000;
 const MAX_CHAT_INPUT_CHARS = 16_000;
 const MAX_CONTEXT_MESSAGES = 24;
@@ -75,13 +76,26 @@ async function readJsonObject(req) {
 function isRouteResult(value) {
     return isRecord(value) && typeof value.status === "number" && "body" in value;
 }
-function modelFromBody(body) {
+function chatCapability(deps, modelId) {
+    const config = currentGatewayConfig(deps);
+    return config === undefined ? findCapability(modelId) : findConfiguredCapability(config, modelId);
+}
+function defaultChatModelId(deps) {
+    const config = currentGatewayConfig(deps);
+    if (config === undefined) {
+        return DEFAULT_CHAT_MODEL;
+    }
+    const configured = listConfiguredCapabilities(config);
+    return (configured.find((model) => model.id === DEFAULT_CHAT_MODEL && model.kind === "chat") ??
+        configured.find((model) => model.kind === "chat"))?.id ?? DEFAULT_CHAT_MODEL;
+}
+function modelFromBody(body, deps) {
     const modelId = typeof body.modelId === "string" && body.modelId.length > 0
         ? body.modelId
-        : DEFAULT_CHAT_MODEL;
-    const capability = findCapability(modelId);
+        : defaultChatModelId(deps);
+    const capability = chatCapability(deps, modelId);
     if (capability?.kind !== "chat") {
-        return { status: 400, body: errorBody("BAD_REQUEST", "modelId must be a chat model registry id.") };
+        return { status: 400, body: errorBody("BAD_REQUEST", "modelId must be a configured chat model id.") };
     }
     return modelId;
 }
@@ -176,12 +190,12 @@ function sendRequestFromBody(body) {
         modelId: typeof body.modelId === "string" && body.modelId.length > 0 ? body.modelId : undefined,
     };
 }
-function invalidChatModelResult(modelId) {
-    const capability = findCapability(modelId);
+function invalidChatModelResult(modelId, deps) {
+    const capability = chatCapability(deps, modelId);
     if (capability?.kind === "chat") {
         return undefined;
     }
-    return { status: 400, body: errorBody("BAD_REQUEST", "modelId must be a chat model registry id.") };
+    return { status: 400, body: errorBody("BAD_REQUEST", "modelId must be a configured chat model id.") };
 }
 function createUserMessage(deps, request) {
     return deps.store.createMessage({
@@ -242,7 +256,7 @@ export async function handleCreateDesktopChat(ctx, deps) {
     const body = await readJsonObject(ctx.req);
     if (isRouteResult(body))
         return body;
-    const modelId = modelFromBody(body);
+    const modelId = modelFromBody(body, deps);
     if (isRouteResult(modelId))
         return modelId;
     try {
@@ -274,7 +288,7 @@ export async function handleSendDesktopChat(ctx, deps) {
         return { status: 404, body: errorBody("NOT_FOUND", "Chat not found.") };
     }
     const modelId = request.modelId ?? chat.selectedModel;
-    const invalidModel = invalidChatModelResult(modelId);
+    const invalidModel = invalidChatModelResult(modelId, deps);
     if (invalidModel !== undefined)
         return invalidModel;
     return persistModelChatTurn(deps, request, chat, modelId);

package/dist/ui/csp-hashes.json

@@ -1,15 +1,15 @@
 [
+  "'sha256-2Flzo4ItPYV57isCh/jl3+kdIDk82tJZynJPKUh7Pw8='",
+  "'sha256-7mSPGegJYFJGVEtaRwBRsbc8ZbNmoSO6U/jFhIwVyUo='",
   "'sha256-FhLHRUQz4c4ntLU9VkfEesX7PnzNLENSe/16Hi523Kk='",
+  "'sha256-JvBgydXt9/FYJ748ftCVGdeG0nrCETPaVqZP4+fgvkQ='",
   "'sha256-NMmsYxPlvKu6BMNDUuiUA/0HWXXhODWSkUJ3CrerHAI='",
   "'sha256-OBTN3RiyCV4Bq7dFqZ5a2pAXjnCcCYeTJMO2I/LYKeo='",
-  "'sha256-OogwkdfeAY//FSbFGNeTewmi/U11IUHAkAgKNEwJCG0='",
   "'sha256-U9W+ZoRW19rf6ohEfUh2oSN8UmJ8mZjCoxp31AbEGYM='",
-  "'sha256-bDep1P+WNj2FZ2j0g3tUvt5ISNYG1nCzFE65Y9sE1c8='",
+  "'sha256-Xhv62fM7dwD82udSCiqrICSFGK4rIE9t+2k2y0fsEwg='",
   "'sha256-bg+CWjI8RppcgHYH6RuW4z4OnLAUEUPDXRoYUo9Tyok='",
-  "'sha256-iqYTUJ5u/EtWNaG9+D7Y0DM2wPtGyVS2aRVXbTOsfag='",
-  "'sha256-oJekvGO4J2NYcfsZB+NVPai5HyR1UVOFcmKB3PORB8M='",
-  "'sha256-pQjgKfZ7Pcb9s5HrqqpJnRrMazbJ0Nhk6e1aFQNuFsU='",
-  "'sha256-q3VO3K+1hbob0r8DheOST7SIt4DQWr76alv4VzyZ44s='",
+  "'sha256-dkXQrDpCKNXpywUKLu04aGkL4/5JXS2LWCKQ806R0rU='",
+  "'sha256-o5xPG0ZoS77FlzyLEClBD+u6el5Y3HrgzBsy+JPyHx8='",
   "'sha256-qBQ7RdQKJEJuW7Fj1MbGjDbF6lnRdfu+KV0V4A5MTRg='",
   "'sha256-qjuzziE6xLU3Cras89VlShlRYHgYZuOxceXUDmuvClo='",
   "'sha256-xLP5QIbvR88RAxDKoSWqs6CVxNIRu17hhr7S/Q6hlU0='",

package/dist/ui/deps.d.ts

@@ -7,6 +7,12 @@ import { type TerminalExecutionManager } from "./terminal.js";
 import { type BrowserSessionManager } from "../tools/browser/index.js";
 export type Redactor = (value: unknown) => unknown;
 export type ModelPortFactory = (modelId: string) => ModelPort | undefined;
+export interface RuntimeGatewayConfig {
+    readonly storagePath: string;
+    current(): GatewayConfig | undefined;
+    present(): boolean;
+    set(config: GatewayConfig | undefined, present: boolean): void;
+}
 export interface UiHandlerDeps {
     readonly config: GatewayConfig | undefined;
     readonly configPresent: boolean;
@@ -20,6 +26,9 @@ export interface UiHandlerDeps {
     readonly uiDbPath?: string | undefined;
     readonly terminal?: TerminalExecutionManager | undefined;
     readonly browser?: BrowserSessionManager | undefined;
+    readonly gatewayConfig?: RuntimeGatewayConfig | undefined;
+    readonly gatewaySetupTester?: ((config: GatewayConfig, candidateModelIds: readonly string[]) => Promise<readonly string[]>) | undefined;
+    readonly gatewayModelDiscovery?: ((baseUrl: string, apiKey: string) => Promise<readonly string[]>) | undefined;
 }
 export interface BuildHandlerDepsOptions {
     readonly configPath: string | undefined;
@@ -29,6 +38,11 @@ export interface BuildHandlerDepsOptions {
     readonly modelPortFactory?: ModelPortFactory | undefined;
     readonly uiDbPath?: string | undefined;
     readonly store?: UiStore | undefined;
+    readonly gatewaySetupTester?: ((config: GatewayConfig, candidateModelIds: readonly string[]) => Promise<readonly string[]>) | undefined;
+    readonly gatewayModelDiscovery?: ((baseUrl: string, apiKey: string) => Promise<readonly string[]>) | undefined;
 }
+export declare function currentGatewayConfig(deps: UiHandlerDeps): GatewayConfig | undefined;
+export declare function currentGatewayConfigPresent(deps: UiHandlerDeps): boolean;
 export declare function buildRedactor(env: EnvSource, config?: GatewayConfig): Redactor;
+export declare function currentRedactionSecrets(deps: UiHandlerDeps): readonly string[];
 export declare function buildUiHandlerDeps(options: BuildHandlerDepsOptions): UiHandlerDeps;

package/dist/ui/deps.js

@@ -5,12 +5,13 @@
 // 3-arg `createUiServer({ staticRoot, csp, port })` form still compiles and the Wave 1 server tests
 // pass unchanged; the handlers degrade gracefully (no config → 400 NO_MODEL on a run, null config on
 // the inspector; no store → an empty evidence list).
-import { listCapabilities, loadConfigFromFile, parseGatewayConfig, } from "../gateway/index.js";
+import { createDefaultChatCapability, loadConfigFromFile, parseGatewayConfig, } from "../gateway/index.js";
 import { GatewayError, Gateway } from "../gateway/index.js";
 import { GatewayModelPort } from "../harness/index.js";
 import { createAuditRedactor } from "../audit/index.js";
 import { deepRedactStrings } from "../audit/redaction.js";
 import { createNodeEvidenceStore, resolveEvidenceDir } from "../audit/store.js";
+import { dirname, join } from "node:path";
 import { createRunRegistry } from "./runs.js";
 import { createNodeUiStore, resolveUiDbPath, } from "./store/index.js";
 import { createTerminalExecutionManager, } from "./terminal.js";
@@ -18,16 +19,38 @@ import { createBrowserSessionManager, } from "../tools/browser/index.js";
 function envModelToken(modelId) {
     return modelId.replace(/[^A-Za-z0-9]/g, "_").toUpperCase();
 }
+function envModelIdFromApiKeyName(name) {
+    const prefix = "KEIKO_MODEL_";
+    const suffix = "_API_KEY";
+    if (!name.startsWith(prefix) || !name.endsWith(suffix)) {
+        return undefined;
+    }
+    const token = name.slice(prefix.length, -suffix.length);
+    return token.length === 0 ? undefined : token.toLowerCase().replace(/_/g, "-");
+}
 function hasEnvProvider(modelId, env) {
     const token = envModelToken(modelId);
     const baseUrl = env[`KEIKO_MODEL_${token}_BASE_URL`];
     const apiKey = env[`KEIKO_MODEL_${token}_API_KEY`];
     return baseUrl !== undefined && baseUrl.length > 0 && apiKey !== undefined && apiKey.length > 0;
 }
+function envModelIds(env) {
+    const modelIds = [];
+    for (const key of Object.keys(env)) {
+        const modelId = envModelIdFromApiKeyName(key);
+        if (modelId !== undefined && hasEnvProvider(modelId, env)) {
+            modelIds.push(modelId);
+        }
+    }
+    return Array.from(new Set(modelIds));
+}
 function resolveEnvOnlyConfig(env) {
-    const providers = listCapabilities()
-        .filter((capability) => capability.kind === "chat" && hasEnvProvider(capability.id, env))
-        .map((capability) => ({ modelId: capability.id, baseUrl: "", apiKey: "" }));
+    const providers = envModelIds(env).map((modelId) => ({
+        modelId,
+        baseUrl: "",
+        apiKey: "",
+        capability: createDefaultChatCapability(modelId),
+    }));
     if (providers.length === 0) {
         return undefined;
     }
@@ -41,11 +64,25 @@ function resolveEnvOnlyConfig(env) {
         throw error;
     }
 }
+function localGatewayConfigPath(uiDbPath) {
+    return join(dirname(uiDbPath), "keiko.config.json");
+}
 // Loads the config without leaking the path or any secret on failure: a missing/invalid config file
 // falls back to KEIKO_MODEL_* env wiring when present, otherwise it is a normal "no config" state.
-function resolveConfig(configPath, env) {
+function resolveConfig(configPath, env, localConfigPath) {
     if (configPath === undefined) {
-        const config = resolveEnvOnlyConfig(env);
+        let config;
+        try {
+            config = loadConfigFromFile(localConfigPath, env);
+        }
+        catch (error) {
+            if (error instanceof GatewayError) {
+                config = resolveEnvOnlyConfig(env);
+            }
+            else {
+                throw error;
+            }
+        }
         return { config, configPresent: config !== undefined };
     }
     try {
@@ -59,6 +96,25 @@ function resolveConfig(configPath, env) {
         throw error;
     }
 }
+function createRuntimeGatewayConfig(initial, initialPresent, storagePath) {
+    let config = initial;
+    let present = initialPresent;
+    return {
+        storagePath,
+        current: () => config,
+        present: () => present,
+        set(next, nextPresent) {
+            config = next;
+            present = nextPresent;
+        },
+    };
+}
+export function currentGatewayConfig(deps) {
+    return deps.gatewayConfig?.current() ?? deps.config;
+}
+export function currentGatewayConfigPresent(deps) {
+    return deps.gatewayConfig?.present() ?? deps.configPresent;
+}
 function isKeikoApiKeyEnvName(name) {
     return (name === "KEIKO_DEFAULT_API_KEY" ||
         (name.startsWith("KEIKO_MODEL_") && name.endsWith("_API_KEY")));
@@ -85,28 +141,44 @@ export function buildRedactor(env, config) {
     const redactString = createAuditRedactor({ additionalSecrets: redactionSecrets(env, config) }, env);
     return (value) => deepRedactStrings(value, redactString);
 }
+export function currentRedactionSecrets(deps) {
+    return redactionSecrets(deps.env, currentGatewayConfig(deps));
+}
 // The production ModelPort factory: a GatewayModelPort over a Gateway built from the resolved
 // config (mirrors the CLI's `new GatewayModelPort(new Gateway(config))`). Returns undefined when no
 // config was resolved so the run route answers 400 NO_MODEL rather than constructing a broken port.
-function defaultModelPortFactory(config) {
+function defaultModelPortFactory(runtimeConfig) {
     return () => {
+        const config = runtimeConfig.current();
         if (config === undefined) {
             return undefined;
         }
         return new GatewayModelPort(new Gateway(config));
     };
 }
+function buildTerminalManager(options) {
+    return createTerminalExecutionManager({
+        store: options.store,
+        evidenceStore: options.evidenceStore,
+        processEnv: options.env,
+        redactor: (value) => {
+            const redacted = options.liveRedactor(value);
+            return typeof redacted === "string" ? redacted : value;
+        },
+    });
+}
 // Assembles the handler deps for the real `keiko ui` process, mirroring the CLI config/evidence
 // wiring (loadConfigFromFile / resolveEvidenceDir / createNodeEvidenceStore). The UI store is
 // created at the resolved UI-DB path (explicit → KEIKO_UI_DATA_DIR → ~/.keiko/keiko-ui.db) unless
 // an injected store is supplied (tests).
 export function buildUiHandlerDeps(options) {
-    const { config, configPresent } = resolveConfig(options.configPath, options.env);
-    const evidenceStore = createNodeEvidenceStore(resolveEvidenceDir(options.evidenceDir, options.env));
-    const secrets = redactionSecrets(options.env, config);
-    const redactString = createAuditRedactor({ additionalSecrets: secrets }, options.env);
-    const liveRedactor = buildRedactor(options.env, config);
     const resolvedUiDbPath = resolveUiDbPath(options.uiDbPath, options.env);
+    const runtimeConfigPath = localGatewayConfigPath(resolvedUiDbPath);
+    const { config, configPresent } = resolveConfig(options.configPath, options.env, runtimeConfigPath);
+    const runtimeConfig = createRuntimeGatewayConfig(config, configPresent, runtimeConfigPath);
+    const evidenceStore = createNodeEvidenceStore(resolveEvidenceDir(options.evidenceDir, options.env));
+    const redactString = (value) => createAuditRedactor({ additionalSecrets: redactionSecrets(options.env, runtimeConfig.current()) }, options.env)(value);
+    const liveRedactor = (value) => deepRedactStrings(value, redactString);
     const uiStore = options.store ?? createNodeUiStore(resolvedUiDbPath, { redactString });
     return {
         config,
@@ -115,18 +187,18 @@ export function buildUiHandlerDeps(options) {
         env: options.env,
         redactor: liveRedactor,
         registry: options.registry ?? createRunRegistry(),
-        modelPortFactory: options.modelPortFactory ?? defaultModelPortFactory(config),
-        redactionSecrets: secrets,
+        modelPortFactory: options.modelPortFactory ?? defaultModelPortFactory(runtimeConfig),
+        redactionSecrets: redactionSecrets(options.env, runtimeConfig.current()),
         store: uiStore,
         uiDbPath: resolvedUiDbPath,
-        terminal: createTerminalExecutionManager({
+        gatewayConfig: runtimeConfig,
+        gatewaySetupTester: options.gatewaySetupTester,
+        gatewayModelDiscovery: options.gatewayModelDiscovery,
+        terminal: buildTerminalManager({
             store: uiStore,
             evidenceStore,
-            processEnv: options.env,
-            redactor: (value) => {
-                const redacted = liveRedactor(value);
-                return typeof redacted === "string" ? redacted : value;
-            },
+            env: options.env,
+            liveRedactor,
         }),
         browser: createBrowserSessionManager({
             evidenceDir: resolveEvidenceDir(options.evidenceDir, options.env),

package/dist/ui/gateway-setup.d.ts

@@ -0,0 +1,3 @@
+import type { RouteContext, RouteResult } from "./routes.js";
+import type { UiHandlerDeps } from "./deps.js";
+export declare function handleGatewaySetup(ctx: RouteContext, deps: UiHandlerDeps): Promise<RouteResult>;

package/dist/ui/gateway-setup.js

@@ -0,0 +1,235 @@
+// First-run gateway setup for non-technical UI users. The browser provides only a base URL and API
+// token; the loopback BFF builds the local provider config, performs a real chat-completions smoke
+// call, stores the resulting config on disk with private permissions, and updates the in-memory
+// runtime config without exposing credentials back to the browser.
+import { chmodSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { Gateway, createDefaultChatCapability, listConfiguredCapabilities, parseGatewayConfig, toSafeObject, } from "../gateway/index.js";
+import { redact } from "../gateway/redaction.js";
+import { errorBody } from "./routes.js";
+const MAX_BODY_BYTES = 64_000;
+const MAX_DISCOVERED_MODELS = 25;
+class BodyTooLargeError extends Error {
+    constructor() {
+        super("request body too large");
+        this.name = "BodyTooLargeError";
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let total = 0;
+        let capped = false;
+        req.on("data", (chunk) => {
+            total += chunk.length;
+            if (total > MAX_BODY_BYTES) {
+                if (!capped) {
+                    capped = true;
+                    chunks.length = 0;
+                    reject(new BodyTooLargeError());
+                    req.resume();
+                }
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => {
+            if (!capped) {
+                resolve(Buffer.concat(chunks).toString("utf8"));
+            }
+        });
+        req.on("error", reject);
+    });
+}
+function normalizeBaseUrl(raw) {
+    let value = raw.trim().replace(/\/+$/u, "");
+    if (value.endsWith("/chat/completions")) {
+        value = value.slice(0, -"/chat/completions".length).replace(/\/+$/u, "");
+    }
+    return value;
+}
+function candidateBaseUrls(baseUrl) {
+    const primary = normalizeBaseUrl(baseUrl);
+    const candidates = [primary];
+    if (!primary.endsWith("/v1")) {
+        candidates.push(`${primary}/v1`);
+    }
+    return Array.from(new Set(candidates));
+}
+function providerRaw(modelId, baseUrl, apiKey) {
+    return {
+        modelId,
+        baseUrl,
+        apiKey,
+        capability: createDefaultChatCapability(modelId),
+        timeoutMs: 30_000,
+        maxRetries: 2,
+        retryBaseDelayMs: 500,
+    };
+}
+function buildRawConfig(baseUrl, apiKey, modelIds) {
+    return {
+        providers: modelIds.map((modelId) => providerRaw(modelId, baseUrl, apiKey)),
+        circuitBreaker: { failureThreshold: 5, cooldownMs: 30_000, halfOpenProbes: 2 },
+    };
+}
+function modelsEndpoint(baseUrl) {
+    return `${baseUrl}/models`;
+}
+function parseModelList(payload) {
+    if (!isRecord(payload) || !Array.isArray(payload.data)) {
+        throw new Error("model discovery response must contain a data array");
+    }
+    const ids = [];
+    for (const item of payload.data) {
+        if (!isRecord(item) || typeof item.id !== "string" || item.id.trim().length === 0) {
+            continue;
+        }
+        ids.push(item.id.trim());
+    }
+    const unique = Array.from(new Set(ids));
+    if (unique.length === 0) {
+        throw new Error("model discovery returned no model ids");
+    }
+    return unique.slice(0, MAX_DISCOVERED_MODELS);
+}
+async function defaultGatewayModelDiscovery(baseUrl, apiKey) {
+    const response = await fetch(modelsEndpoint(baseUrl), {
+        method: "GET",
+        headers: { authorization: `Bearer ${apiKey}` },
+        signal: AbortSignal.timeout(30_000),
+    });
+    if (!response.ok) {
+        throw new Error(`model discovery returned HTTP ${String(response.status)}`);
+    }
+    let payload;
+    try {
+        payload = await response.json();
+    }
+    catch {
+        throw new Error("model discovery response was not readable JSON");
+    }
+    return parseModelList(payload);
+}
+async function defaultGatewaySetupTester(config, candidateModelIds) {
+    const gateway = new Gateway(config);
+    const tested = [];
+    for (const modelId of candidateModelIds) {
+        try {
+            await gateway.chat({
+                modelId,
+                messages: [{ role: "user", content: "Reply with exactly: OK" }],
+            });
+            tested.push(modelId);
+        }
+        catch {
+            // Non-chat models can appear in OpenAI-compatible model discovery responses. They are
+            // intentionally ignored so only chat-callable models become selectable in the UI.
+        }
+    }
+    if (tested.length === 0) {
+        throw new Error("no discovered model accepted the chat-completions smoke test");
+    }
+    return tested;
+}
+function savePrivateJson(path, raw) {
+    const dir = dirname(path);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    if (process.platform !== "win32") {
+        chmodSync(dir, 0o700);
+    }
+    writeFileSync(path, `${JSON.stringify(raw, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    if (process.platform !== "win32") {
+        chmodSync(path, 0o600);
+    }
+}
+function readSetupRequest(raw) {
+    if (!isRecord(raw)) {
+        return { status: 400, body: errorBody("BAD_REQUEST", "Request body must be a JSON object.") };
+    }
+    const baseUrl = typeof raw.baseUrl === "string" ? raw.baseUrl.trim() : "";
+    const apiKey = typeof raw.apiKey === "string" ? raw.apiKey.trim() : "";
+    if (baseUrl.length === 0 || apiKey.length === 0) {
+        return { status: 400, body: errorBody("BAD_REQUEST", "baseUrl and apiKey are required.") };
+    }
+    return { baseUrl, apiKey };
+}
+function safeError(error, secrets) {
+    if (error instanceof Error) {
+        return redact(error.message, secrets);
+    }
+    return "Gateway setup failed.";
+}
+async function verifySetupCandidate(baseUrl, apiKey, tester, discovery) {
+    const candidateModelIds = await discovery(baseUrl, apiKey);
+    const candidateRawConfig = buildRawConfig(baseUrl, apiKey, candidateModelIds);
+    const candidateConfig = parseGatewayConfig(candidateRawConfig);
+    const testedModelIds = await tester(candidateConfig, candidateModelIds);
+    const rawConfig = buildRawConfig(baseUrl, apiKey, testedModelIds);
+    const config = parseGatewayConfig(rawConfig);
+    return { rawConfig, config, testedModelIds };
+}
+function setupSuccessResult(config, testedModelIds) {
+    const testedModelId = testedModelIds[0] ?? "unknown";
+    return {
+        status: 200,
+        body: {
+            ok: true,
+            testedModelId,
+            testedModelIds,
+            providerCount: config.providers.length,
+            models: listConfiguredCapabilities(config),
+            config: toSafeObject(config),
+        },
+    };
+}
+function setupFailureResult(errors) {
+    return {
+        status: 502,
+        body: errorBody("GATEWAY_SETUP_FAILED", `Credentials could not be verified. ${errors.join(" ")}`),
+    };
+}
+export async function handleGatewaySetup(ctx, deps) {
+    if (deps.gatewayConfig === undefined) {
+        return { status: 500, body: errorBody("GATEWAY_SETUP_UNAVAILABLE", "Gateway setup is unavailable.") };
+    }
+    let bodyText;
+    try {
+        bodyText = await readBody(ctx.req);
+    }
+    catch (error) {
+        if (error instanceof BodyTooLargeError) {
+            return { status: 413, body: errorBody("PAYLOAD_TOO_LARGE", "Request body exceeds the size limit.") };
+        }
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(bodyText);
+    }
+    catch {
+        return { status: 400, body: errorBody("BAD_REQUEST", "Request body is not valid JSON.") };
+    }
+    const request = readSetupRequest(parsed);
+    if ("status" in request) {
+        return request;
+    }
+    const tester = deps.gatewaySetupTester ?? defaultGatewaySetupTester;
+    const discovery = deps.gatewayModelDiscovery ?? defaultGatewayModelDiscovery;
+    const errors = [];
+    for (const baseUrl of candidateBaseUrls(request.baseUrl)) {
+        try {
+            const verified = await verifySetupCandidate(baseUrl, request.apiKey, tester, discovery);
+            savePrivateJson(deps.gatewayConfig.storagePath, verified.rawConfig);
+            deps.gatewayConfig.set(verified.config, true);
+            return setupSuccessResult(verified.config, verified.testedModelIds);
+        }
+        catch (error) {
+            errors.push(`candidate ${String(errors.length + 1)}: ${safeError(error, [request.apiKey, baseUrl])}`);
+        }
+    }
+    return setupFailureResult(errors);
+}

package/dist/ui/read-handlers.js

@@ -1,27 +1,34 @@
 // The six read-only BFF endpoints (ADR-0011 D5 routes 2,3,4,10,11,12). Each returns a redacted JSON
-// projection of already-safe data: config via `toSafeObject` (strips apiKey), the full capability
-// registry, the workflow launch-form descriptors, the workspace summary built from the workspace
+// projection of already-safe data: config via `toSafeObject` (strips apiKey), configured model
+// capabilities, the workflow launch-form descriptors, the workspace summary built from the workspace
 // layer, and evidence list/detail served straight from the store (manifests are redacted-by-
 // construction on disk, served as-is per D9). No secret reaches any response; the config route
 // never leaks the config path even on a load failure (handled upstream in deps.ts, which yields
 // `config: undefined` rather than throwing).
-import { toSafeObject, listCapabilities } from "../gateway/index.js";
+import { toSafeObject, listConfiguredCapabilities } from "../gateway/index.js";
 import { UNIT_TEST_WORKFLOW_DESCRIPTOR, BUG_INVESTIGATION_WORKFLOW_DESCRIPTOR, } from "../workflows/index.js";
 import { DEFAULT_LIMITS } from "../harness/index.js";
 import { listEvidence, loadEvidence, assertValidRunId, EvidenceReadError, EvidenceSchemaError, } from "../audit/index.js";
 import { buildContextPackFromFiles, buildWorkspaceSummary, DEFAULT_CONTEXT_REQUEST, detectWorkspace, discoverWithStats, WORKSPACE_CODES, WorkspaceError, } from "../workspace/index.js";
 import { errorBody } from "./routes.js";
+import { currentGatewayConfig, currentGatewayConfigPresent } from "./deps.js";
 import { validateProjectPath } from "./store/validation.js";
 // Route 2 — resolved config (SafeGatewayConfig, never apiKey/baseUrl) or null when no config was resolved.
 export function handleConfig(_ctx, deps) {
-    const config = deps.config === undefined ? null : toSafeObject(deps.config);
-    return { status: 200, body: { config, configPresent: deps.configPresent } };
+    const config = currentGatewayConfig(deps);
+    return {
+        status: 200,
+        body: {
+            config: config === undefined ? null : toSafeObject(config),
+            configPresent: currentGatewayConfigPresent(deps),
+        },
+    };
 }
 // Route 3 — models published by the resolved UI gateway config. If no config is resolved, no
 // model-backed run can start, so the endpoint returns an empty list.
 export function handleModels(_ctx, deps) {
-    const configured = new Set(deps.config?.providers.map((provider) => provider.modelId) ?? []);
-    const models = listCapabilities().filter((model) => configured.has(model.id));
+    const config = currentGatewayConfig(deps);
+    const models = config === undefined ? [] : listConfiguredCapabilities(config);
     return { status: 200, body: { models } };
 }
 // Route 4 — launch-form metadata: the workflow descriptors plus the synthesized explain-plan and

package/dist/ui/routes.js

@@ -9,6 +9,7 @@ import { handleConfig, handleModels, handleWorkflows, handleWorkspace, handleEvi
 import { handleCreateRun, handleCreateChatRun, handleRunEvents, handleCancelRun, handleGetRun, handleApplyRun, } from "./run-handlers.js";
 import { handleListProjects, handleCreateProject, handleUpdateProject, handleDeleteProject, handleListChats, handleCreateChat, handleUpdateChat, handleDeleteChat, handleListMessages, handleCreateMessage, handleCreateRunSummaryPair, handleUpdateMessage, } from "./store-handlers.js";
 import { handleCreateDesktopChat, handleSendDesktopChat } from "./chat-handlers.js";
+import { handleGatewaySetup } from "./gateway-setup.js";
 import { handleCreateTerminalExecution, handleDeleteTerminalExecution, handleTerminalDirectories, handleTerminalEvents, handleTerminalPolicy, } from "./terminal-routes.js";
 import { handleFilesDirectories, handleFilesPreview, handleFilesTree, } from "./files.js";
 import { handleBrowserApplyScreenshot, handleBrowserContent, handleBrowserEvents, handleBrowserNavigate, handleBrowserScreenshot, handleBrowserStatus, handleCreateBrowserSession, handleDeleteBrowserSession, } from "./browser.js";
@@ -16,14 +17,15 @@ export const STREAMING = Symbol("streaming");
 function health() {
     return { status: 200, body: { status: "ok", version: SDK_VERSION } };
 }
-// The full route contract: the twelve original (ADR-0011 D5), the 10 additive UI-store
-// routes (ADR-0013 D7), three Issue #66 run-summary routes, two desktop chat routes,
-// desktop terminal JSON routes, and read-only Files widget routes. Terminal byte I/O
-// uses a token-scoped WebSocket upgrade path.
+// The full route contract: the twelve original (ADR-0011 D5), the first-run gateway setup
+// endpoint, the 10 additive UI-store routes (ADR-0013 D7), three Issue #66 run-summary routes,
+// two desktop chat routes, desktop terminal JSON routes, and read-only Files widget routes.
+// Terminal byte I/O uses a token-scoped WebSocket upgrade path.
 export const API_ROUTES = [
     { method: "GET", pattern: "/api/health", handler: health },
     { method: "GET", pattern: "/api/config", handler: handleConfig },
     { method: "GET", pattern: "/api/models", handler: handleModels },
+    { method: "POST", pattern: "/api/gateway/setup", handler: handleGatewaySetup },
     { method: "GET", pattern: "/api/workflows", handler: handleWorkflows },
     { method: "POST", pattern: "/api/runs", handler: handleCreateRun },
     { method: "GET", pattern: "/api/runs/:runId/events", handler: handleRunEvents },

package/dist/ui/run-handlers.js

@@ -11,6 +11,7 @@ import { startRun, applyRun } from "./run-engine.js";
 import { ActiveRunLimitError } from "./runs.js";
 import { SSE_HEADERS, writeEvent, readyMessage } from "./sse.js";
 import { errorBody, STREAMING } from "./routes.js";
+import { currentRedactionSecrets } from "./deps.js";
 import { UiStoreError } from "./store/index.js";
 const MAX_BODY_BYTES = 1_000_000;
 const VERIFY_NOOP_MODEL = {
@@ -221,7 +222,7 @@ function engineContextFor(deps, request, model) {
         evidence: {
             store: deps.evidenceStore,
             env: deps.env,
-            additionalSecrets: deps.redactionSecrets ?? [],
+            additionalSecrets: currentRedactionSecrets(deps),
         },
     };
 }
@@ -288,7 +289,7 @@ export async function handleCreateRun(ctx, deps) {
         evidence: {
             store: deps.evidenceStore,
             env: deps.env,
-            additionalSecrets: deps.redactionSecrets ?? [],
+            additionalSecrets: currentRedactionSecrets(deps),
         },
     };
     try {