@wrenai/genbi 0.0.4 → 0.0.5

package/dist-server/harness/setup/runner.js

@@ -61,6 +61,7 @@ import { buildUniformTierBinding } from "../route/tier-binding.js";
 import { createNativeToolRegistry, createSetupExecutionTool, SETUP_EXECUTION_TOOL_NAME } from "../tools/index.js";
 import { withResolvedTools } from "../tools/wiring.js";
 import { CodexSetupEventMapper } from "./codex-events.js";
+import { readYamlScalarField } from "./yaml-scalar.js";
 /** The warble component the setup wizard's connect step dispatches. */
 export const CONNECT_SOURCE_AGENT_ID = "connect_source";
 /** The Warble component the setup wizard's context step dispatches (`profiles/genbi-setup/components/build_context`). */
@@ -142,6 +143,7 @@ export class DispatchedSetupRunner {
         return resolveEffectiveMaxTurns(this.options.maxTurns, agentId);
     }
     async run(runOptions) {
+        runOptions.signal?.throwIfAborted();
         const { authChoice } = runOptions;
         const agentId = runOptions.agentId ?? CONNECT_SOURCE_AGENT_ID;
         // Only build_context needs the raised turn budget — generating an MDL is
@@ -176,6 +178,7 @@ export class DispatchedSetupRunner {
             ...(modelsConfig !== undefined ? { modelsConfig } : {}),
             ...(maxTurns !== undefined ? { maxTurns } : {}),
             ...(runOptions.onEvent !== undefined ? { onEvent: runOptions.onEvent } : {}),
+            ...(runOptions.signal !== undefined ? { signal: runOptions.signal } : {}),
             ...(runOptions.resumeSessionId !== undefined ? { resumeSessionId: runOptions.resumeSessionId } : {}),
         });
         return { finalText: result.finalText, ...(result.sessionId !== undefined ? { sessionId: result.sessionId } : {}) };
@@ -248,6 +251,7 @@ export class CodexSetupRunner {
         this.options = options;
     }
     async run(runOptions) {
+        runOptions.signal?.throwIfAborted();
         if (runOptions.authChoice.mode !== "subscription" || runOptions.authChoice.provider !== "codex") {
             throw new Error("Codex setup runner requires a Codex subscription auth choice");
         }
@@ -286,10 +290,9 @@ export class CodexSetupRunner {
             "--server-arg=--workspace-root",
             "--server-arg",
             turnRoot,
-            "--source-tool",
-            SETUP_EXECUTION_TOOL_NAME,
-            "--context-tool",
-            SETUP_EXECUTION_TOOL_NAME,
+            "--transport", "exec",
+            "--step-tool", `${agentId === CONNECT_SOURCE_AGENT_ID ? "connect" : "build"}=${SETUP_EXECUTION_TOOL_NAME}`,
+            "--require-tool", agentId === CONNECT_SOURCE_AGENT_ID ? "connect" : "build",
             "--timeout",
             String(timeoutMs),
             ...(this.options.codexBin ? ["--codex-bin", this.options.codexBin] : []),
@@ -299,7 +302,7 @@ export class CodexSetupRunner {
         emitter.emit({ kind: "run.start", mode: "B", agentId });
         const mapper = new CodexSetupEventMapper(tracePath);
         try {
-            const rawFinalText = await spawnCodexSetup(cli.command, args, mapper, emitter.emit, timeoutMs + 5_000);
+            const rawFinalText = await spawnCodexSetup(cli.command, args, mapper, emitter.emit, timeoutMs + 5_000, runOptions.signal);
             const finalText = unwrapCodexSetupEnvelope(rawFinalText, expectedProducedField);
             emitter.emit({ kind: "run.finish", status: "answer" });
             return { finalText };
@@ -325,8 +328,12 @@ function defaultCodexSetupMcpInvocation(tracePath) {
 function sanitizedCodexSetupEnvironment() {
     return Object.fromEntries(Object.entries(process.env).filter(([key, value]) => value !== undefined && !CODEX_BILLING_ENV_KEYS.has(key.toUpperCase())));
 }
-function spawnCodexSetup(command, args, mapper, emit, timeoutMs) {
+function spawnCodexSetup(command, args, mapper, emit, timeoutMs, abortSignal) {
     return new Promise((resolve, reject) => {
+        if (abortSignal?.aborted) {
+            reject(new Error("Codex setup cancelled"));
+            return;
+        }
         const child = spawn(command, [...args], {
             env: sanitizedCodexSetupEnvironment(),
             stdio: ["ignore", "pipe", "pipe"],
@@ -335,6 +342,7 @@ function spawnCodexSetup(command, args, mapper, emit, timeoutMs) {
         let stderr = "";
         let settled = false;
         let timedOut = false;
+        let cancelled = false;
         let killTimer;
         const terminate = (signal) => {
             if (child.pid !== undefined && process.platform !== "win32") {
@@ -348,7 +356,17 @@ function spawnCodexSetup(command, args, mapper, emit, timeoutMs) {
             }
             child.kill(signal);
         };
+        const cancel = () => {
+            if (settled || cancelled || timedOut)
+                return;
+            cancelled = true;
+            terminate("SIGTERM");
+            killTimer = setTimeout(() => terminate("SIGKILL"), 1_000);
+        };
+        abortSignal?.addEventListener("abort", cancel, { once: true });
         const timer = setTimeout(() => {
+            if (cancelled)
+                return;
             timedOut = true;
             terminate("SIGTERM");
             killTimer = setTimeout(() => terminate("SIGKILL"), 1_000);
@@ -365,6 +383,7 @@ function spawnCodexSetup(command, args, mapper, emit, timeoutMs) {
             catch (error) {
                 settled = true;
                 clearTimeout(timer);
+                abortSignal?.removeEventListener("abort", cancel);
                 terminate("SIGTERM");
                 killTimer = setTimeout(() => terminate("SIGKILL"), 1_000);
                 reject(error);
@@ -379,12 +398,14 @@ function spawnCodexSetup(command, args, mapper, emit, timeoutMs) {
                 return;
             settled = true;
             clearTimeout(timer);
+            abortSignal?.removeEventListener("abort", cancel);
             if (killTimer)
                 clearTimeout(killTimer);
             reject(new Error(`warble-codex-local failed to start: ${error.message}`));
         });
         child.on("close", (code, signal) => {
             clearTimeout(timer);
+            abortSignal?.removeEventListener("abort", cancel);
             lines.close();
             // Do not cancel an already-scheduled process-group SIGKILL here. The
             // direct dispatcher can exit on SIGTERM while one of its descendants
@@ -392,7 +413,10 @@ function spawnCodexSetup(command, args, mapper, emit, timeoutMs) {
             if (settled)
                 return;
             settled = true;
-            if (timedOut) {
+            if (cancelled) {
+                reject(new Error("Codex setup cancelled"));
+            }
+            else if (timedOut) {
                 reject(new Error(`warble-codex-local timed out after ${timeoutMs}ms`));
             }
             else if (code !== 0) {
@@ -483,6 +507,7 @@ export class InProcessSetupRunner {
         return resolveEffectiveMaxTurns(this.options.maxTurns, agentId);
     }
     async run(runOptions) {
+        runOptions.signal?.throwIfAborted();
         const { authChoice } = runOptions;
         const agentId = runOptions.agentId ?? CONNECT_SOURCE_AGENT_ID;
         if (authChoice.mode === "subscription") {
@@ -548,6 +573,7 @@ export class InProcessSetupRunner {
                 registry,
                 tools,
                 userInput: runOptions.prompt,
+                ...(runOptions.signal ? { signal: runOptions.signal } : {}),
                 onEvent: emitter.emit,
                 ...(maxSteps !== undefined ? { maxSteps } : {}),
             }));
@@ -620,7 +646,9 @@ export class InProcessSetupRunner {
  * rather than pulling in a YAML parser dependency. Matches only an unindented
  * `field:` key (so it can't be fooled by a same-named key nested under
  * another mapping), strips a single layer of surrounding quotes, and returns
- * `undefined` if the file is missing/unreadable or the field isn't present.
+ * `undefined` if the file is missing/unreadable or the field isn't present. Values
+ * are read as YAML scalars (trailing comments dropped; blank or comment-only is `""`),
+ * via `./yaml-scalar.ts`.
  */
 function readProjectYamlField(yamlPath, field) {
     let content;
@@ -630,14 +658,7 @@ function readProjectYamlField(yamlPath, field) {
     catch {
         return undefined;
     }
-    const pattern = new RegExp(`^${field}:\\s*(.+?)\\s*$`, "m");
-    const match = pattern.exec(content);
-    if (!match) {
-        return undefined;
-    }
-    const raw = match[1];
-    const unquoted = /^"(.*)"$/.exec(raw) ?? /^'(.*)'$/.exec(raw);
-    return (unquoted ? unquoted[1] : raw).trim();
+    return readYamlScalarField(content, field);
 }
 /** Parses the small KEY=value subset of a project .env file used by Wren profiles. */
 function parseDotEnv(text) {
@@ -809,7 +830,7 @@ export function contextLifecycleIdentityFingerprint(root, name, selectedSourceTy
         const declaredSourceType = readProjectYamlField(projectYml, "data_source");
         const normalizedSelectedSourceType = selectedSourceType.trim().toLowerCase();
         const normalizedDeclaredSourceType = declaredSourceType?.trim().toLowerCase();
-        if (profile === undefined || normalizedDeclaredSourceType === undefined || normalizedDeclaredSourceType !== normalizedSelectedSourceType)
+        if (!profile || normalizedDeclaredSourceType === undefined || normalizedDeclaredSourceType !== normalizedSelectedSourceType)
             return undefined;
         const connectionTargetDigest = effectiveConnectionTargetDigest(projectDir, normalizedSelectedSourceType);
         if (connectionTargetDigest === undefined)

package/dist-server/harness/setup/yaml-scalar.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Reads a top-level `field: value` scalar from a `wren_project.yml`-shaped
+ * document and returns the YAML *value*, not the raw line remainder.
+ *
+ * `wren context init` scaffolds lines such as
+ * `data_source:  # not set yet — ...`, and hand-edited projects keep trailing
+ * comments (`data_source: duckdb  # change to your datasource type`). A raw
+ * remainder would hand that comment to callers as part of the value. This
+ * stays a single-purpose reader (no YAML dependency, matching the rest of
+ * `server/`); it only understands what a plain scalar line can contain:
+ *
+ * - an unquoted value ends at the first ` #` (a `#` preceded by whitespace);
+ * - a quoted value ends at its closing quote, so `"a#b"` stays `a#b` and
+ *   anything after the closing quote is a comment;
+ * - a blank value, or one that is only a comment, reads as `""` (unset).
+ *
+ * Double-quoted escapes are NOT unescaped (`"a\"b"` yields `a\"b`): only plain
+ * identifiers (data source types, profile names) are ever read through here.
+ * A leading BOM is ignored.
+ *
+ * Returns `undefined` only when the field's key line is absent.
+ */
+export declare function readYamlScalarField(content: string, field: string): string | undefined;

package/dist-server/harness/setup/yaml-scalar.js

@@ -0,0 +1,62 @@
+/**
+ * Reads a top-level `field: value` scalar from a `wren_project.yml`-shaped
+ * document and returns the YAML *value*, not the raw line remainder.
+ *
+ * `wren context init` scaffolds lines such as
+ * `data_source:  # not set yet — ...`, and hand-edited projects keep trailing
+ * comments (`data_source: duckdb  # change to your datasource type`). A raw
+ * remainder would hand that comment to callers as part of the value. This
+ * stays a single-purpose reader (no YAML dependency, matching the rest of
+ * `server/`); it only understands what a plain scalar line can contain:
+ *
+ * - an unquoted value ends at the first ` #` (a `#` preceded by whitespace);
+ * - a quoted value ends at its closing quote, so `"a#b"` stays `a#b` and
+ *   anything after the closing quote is a comment;
+ * - a blank value, or one that is only a comment, reads as `""` (unset).
+ *
+ * Double-quoted escapes are NOT unescaped (`"a\"b"` yields `a\"b`): only plain
+ * identifiers (data source types, profile names) are ever read through here.
+ * A leading BOM is ignored.
+ *
+ * Returns `undefined` only when the field's key line is absent.
+ */
+export function readYamlScalarField(content, field) {
+    const escaped = field.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const text = content.charCodeAt(0) === 0xfeff ? content.slice(1) : content;
+    const match = new RegExp(`^${escaped}:[ \\t]*(.*)$`, "m").exec(text);
+    if (!match)
+        return undefined;
+    return parseScalarValue(match[1].replace(/\r$/, ""));
+}
+function parseScalarValue(rest) {
+    const quote = rest[0];
+    if (quote === '"' || quote === "'") {
+        const closing = findClosingQuote(rest, quote);
+        // An unterminated quote isn't a valid scalar; fall back to the plain-scalar rule rather than guessing.
+        if (closing !== -1)
+            return rest.slice(1, closing);
+    }
+    return stripPlainScalarComment(rest);
+}
+function findClosingQuote(rest, quote) {
+    for (let i = 1; i < rest.length; i++) {
+        if (quote === '"' && rest[i] === "\\") {
+            i++;
+            continue;
+        }
+        if (rest[i] === quote) {
+            if (quote === "'" && rest[i + 1] === "'") {
+                i++;
+                continue;
+            }
+            return i;
+        }
+    }
+    return -1;
+}
+function stripPlainScalarComment(rest) {
+    if (rest.startsWith("#"))
+        return "";
+    const comment = /\s#/.exec(rest);
+    return (comment ? rest.slice(0, comment.index) : rest).trim();
+}

package/dist-server/server/adopt.js

@@ -52,24 +52,8 @@
 import { execFile } from "node:child_process";
 import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import path from "node:path";
+import { readYamlScalarField } from "../harness/setup/yaml-scalar.js";
 import { listCandidateProfiles, loadProfileStore } from "./wren-profiles.js";
-/**
- * Matches a `wren_project.yml` top-level `field: value` scalar line — same
- * single-purpose-regex convention as `server/app.ts`'s `ENV_KEY_LINE`. Only
- * ever reads a handful of known scalar fields (`profile`, `data_source`);
- * never a general YAML parser (matches this repo's existing convention of
- * avoiding a YAML dependency for single-field reads).
- */
-function readYamlScalarField(content, field) {
-    const re = new RegExp(`^${field}:\\s*(.+?)\\s*$`, "m");
-    const match = re.exec(content);
-    if (!match)
-        return undefined;
-    const raw = match[1];
-    // Strip one layer of matching quotes (wren_project.yml sometimes quotes scalars, e.g. `version: '1.0'`) — never unescape further, this only ever reads plain identifiers.
-    const unquoted = /^(['"])(.*)\1$/.exec(raw);
-    return unquoted ? unquoted[2] : raw;
-}
 function execWren(args, cwd) {
     return new Promise((resolve) => {
         execFile("wren", args, { cwd, maxBuffer: 32 * 1024 * 1024 }, (error, stdout, stderr) => {

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

@@ -1,6 +1,7 @@
 import { Hono } from "hono";
 import type { InteractiveTerminalSession } from "./interactive-terminal.js";
 import type { TurnDeps } from "./turn.js";
+export declare const GATEWAY_CATALOG_UNAVAILABLE = "gateway catalog unavailable: the optional dependency @earendil-works/pi-ai is not installed or Node >= 22.19 is required";
 /** Applies only the narrow, size-bounded native-terminal WS wire contract. */
 export declare function applyInteractiveTerminalFrame(session: Pick<InteractiveTerminalSession, "write" | "resize" | "close">, raw: string): void;
 export declare function createApp(deps: TurnDeps): Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;

package/dist-server/server/app.js

@@ -10,10 +10,11 @@ import path from "node:path";
 import { Hono } from "hono";
 import { streamSSE } from "hono/streaming";
 import { upgradeWebSocket } from "@hono/node-server";
+import { conversationSocket } from "./conversation-socket.js";
 import { BUILD_CONTEXT_AGENT_ID, ComplianceError, CONNECT_SOURCE_AGENT_ID, contextLifecycleIdentityFingerprint, enforceCompliance, findLockedGatedCheck, resolveArtifactContent, resolveArtifactsDir } from "../harness/index.js";
 import { adoptWithChosenProfile, verifyAdoptProject } from "./adopt.js";
 import { mountSpaFallback } from "./spa.js";
-import { toAuthChoiceFromRuntimeSettings } from "./auth-choice.js";
+import { isRuntimeAuthMode, runtimeSettingsFromAuthChoice, toAuthChoiceFromRuntimeSettings } from "./auth-choice.js";
 import { composeSetupPrompt, zeroMdlSchemaDiscoveryInstruction } from "./compose.js";
 import { mapContextShowToOverview } from "./context-map.js";
 import { buildContextFileTree, computeKnowledgeStatus } from "./context-files.js";
@@ -25,7 +26,10 @@ import { INTERACTIVE_TARGETS, InteractiveLaunchError } from "./interactive-termi
 import { nativeSessionLaunchErrorCode, nativeSessionLaunchFailure, nativeSessionLifecycle, NATIVE_PURPOSES, NATIVE_SETUP_RECOVERY_MCP_TOOL_NAME, NativeSetupRecoveryError } from "./native-sessions.js";
 import { NATIVE_MCP_PERSIST_ANSWER_TOOL_NAME, NATIVE_MCP_TOOL_NAME, NATIVE_PERSIST_ANSWER_CONTRACT, NATIVE_SAVE_DASHBOARD_CONTRACT, NativeArtifactError } from "./native-artifacts.js";
 import { sameNativeRuntimeBinding } from "./native-dispatch-registry.js";
-import { detectAdapterEnv } from "./env-detect.js";
+import { ProfileRegistryError, toWarbleProfileDto } from "./profile-registry.js";
+import { DEFAULT_CONVERSATION_PROFILE } from "./native-sessions.js";
+import { detectAdapterEnv, GATEWAY_API_KEY_ENV } from "./env-detect.js";
+import { listPiAiCatalog } from "../harness/providers/index.js";
 import { redactPublicSetupText, redactSetupText, sanitizePublicSetupWorklog } from "./fold.js";
 import { assertHarnessBundlePurpose, buildHarnessDto } from "./harness.js";
 import { requiredInProcessCredentialEnvVars, RuntimeBindingError, runtimeSettingsCorrection, validateRuntimeTierBindings } from "./runtime-binding.js";
@@ -34,6 +38,7 @@ import { ArtifactNotFoundError, effectiveRouteOptions, getAskSessionData, invali
 import { connectionVariableNames, loadSourceCatalog, supportedSourceTypes } from "./source-catalog.js";
 import { driverProvisionNote, provisionSourceDriver } from "./source-driver.js";
 import { annotateEnvFields } from "./env-field-hints.js";
+export const GATEWAY_CATALOG_UNAVAILABLE = "gateway catalog unavailable: the optional dependency @earendil-works/pi-ai is not installed or Node >= 22.19 is required";
 /** Only explicit persisted settings can supersede the boot route or require repair. */
 function persistedRuntimeCorrection(deps) {
     return deps.store.hasExplicitRuntimeSettings() ? runtimeSettingsCorrection(deps.store.getRuntimeSettings()) : undefined;
@@ -1009,11 +1014,29 @@ export function createApp(deps) {
     // remains structured conversation storage and is never overloaded with PTYs.
     app.post("/api/native-sessions", async (c) => {
         const body = await c.req.json().catch(() => ({}));
+        if (!body || typeof body !== "object" || Array.isArray(body))
+            return c.json({ error: "native session launch request is invalid" }, 400);
         const intent = body.intent === undefined ? "open_existing" : body.intent;
         const requiresAction = intent === "start_separate" || intent === "resume";
-        const allowedKeys = intent === "start_separate" ? ["purpose", "intent", "idempotencyKey"] : intent === "resume" ? ["purpose", "intent", "sessionId", "idempotencyKey"] : ["purpose", "intent", "sessionId"];
+        // `profile` names a registry id for a NEW analysis session only: a start-separate, or an
+        // open-or-create with no sessionId. A resume or an explicit sessionId already carries its profile.
+        const allowedKeys = intent === "start_separate" ? ["purpose", "intent", "idempotencyKey", "entryVerb", "profile"] : intent === "resume" ? ["purpose", "intent", "sessionId", "idempotencyKey"] : ["purpose", "intent", "sessionId", "profile"];
         if (!NATIVE_PURPOSES.includes(body.purpose) || (intent !== "open_existing" && intent !== "start_separate" && intent !== "resume") || !Object.keys(body).every((key) => allowedKeys.includes(key)) || (requiresAction && (typeof body.idempotencyKey !== "string" || !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(body.idempotencyKey))) || ((intent === "resume" && (typeof body.sessionId !== "string" || !/^native-session-[0-9a-f-]{36}$/i.test(body.sessionId))) || (intent === "open_existing" && body.sessionId !== undefined && (typeof body.sessionId !== "string" || !/^native-session-[0-9a-f-]{36}$/i.test(body.sessionId)))))
             return c.json({ error: "native session launch request is invalid" }, 400);
+        if (body.entryVerb !== undefined && (body.purpose !== "analysis" || typeof body.entryVerb !== "string" || !["answer_query", "generate_dashboard"].includes(body.entryVerb)))
+            return c.json({ error: "native session entry is invalid" }, 400);
+        if (body.profile !== undefined) {
+            if (typeof body.profile !== "string" || !/^[a-z0-9][a-z0-9_-]{0,63}$/.test(body.profile))
+                return c.json({ error: "native session profile is invalid" }, 400);
+            if (body.purpose !== "analysis")
+                return c.json({ error: "native session profile is only selectable for analysis" }, 400);
+            if (intent === "open_existing" && body.sessionId !== undefined)
+                return c.json({ error: "native session profile cannot be changed on an existing session" }, 400);
+            // A selected profile's entry form was decided at admission; only the default takes an entry verb.
+            if (body.profile !== DEFAULT_CONVERSATION_PROFILE && body.entryVerb !== undefined)
+                return c.json({ error: "native session entry is invalid" }, 400);
+        }
+        const profile = typeof body.profile === "string" ? { profile: body.profile } : {};
         if (!deps.nativeSessions)
             return c.json({ error: "native sessions are not configured" }, 503);
         const runtimeCorrection = persistedRuntimeCorrection(deps);
@@ -1021,12 +1044,12 @@ export function createApp(deps) {
             return c.json({ error: runtimeCorrection, code: "runtime_correction_required" }, 409);
         try {
             const created = intent === "start_separate"
-                ? await deps.nativeSessions.startSeparate({ purpose: body.purpose, idempotencyKey: body.idempotencyKey })
+                ? await deps.nativeSessions.startSeparate({ purpose: body.purpose, idempotencyKey: body.idempotencyKey, ...(body.entryVerb !== undefined ? { entryVerb: body.entryVerb } : {}), ...profile })
                 : intent === "resume"
                     ? await deps.nativeSessions.resume({ id: body.sessionId, idempotencyKey: body.idempotencyKey })
                     : typeof body.sessionId === "string"
                         ? await deps.nativeSessions.openExisting({ purpose: body.purpose, id: body.sessionId })
-                        : await deps.nativeSessions.openOrCreate({ purpose: body.purpose });
+                        : await deps.nativeSessions.openOrCreate({ purpose: body.purpose, ...profile });
             return c.json({ session: { ...created.row, lifecycle: nativeSessionLifecycle(created.row, nativeResumeAvailability(created.row)) }, ...(created.capability ? { capability: created.capability } : {}), ...(created.recoveryCapability ? { recoveryCapability: created.recoveryCapability } : {}) }, 201);
         }
         catch (error) {
@@ -1076,8 +1099,16 @@ export function createApp(deps) {
         const body = await c.req.json().catch(() => ({}));
         if (!deps.nativeSessions || typeof body.capability !== "string")
             return c.json({ error: "native session unavailable" }, 404);
-        return deps.nativeSessions.stop(c.req.param("id") ?? "", body.capability) ? c.body(null, 204) : c.json({ error: "native session unavailable" }, 404);
+        try {
+            return await deps.nativeSessions.stopAndWait(c.req.param("id") ?? "", body.capability) ? c.body(null, 204) : c.json({ error: "native session unavailable" }, 404);
+        }
+        catch {
+            return c.json({ error: "Native session cleanup could not be confirmed." }, 409);
+        }
     });
+    app.get("/api/structured-runtime/readiness", async (c) => deps.structuredRuntime
+        ? c.json(await deps.structuredRuntime.readiness()) : c.json({ error: "Structured runtime is not configured." }, 503));
+    app.get("/api/native-sessions/:id/conversation", upgradeWebSocket((c) => conversationSocket(deps.nativeSessions, c.req.param("id") ?? "", c.req.query("cap") ?? "", c.req.query("after") ?? "0")));
     app.get("/api/native-sessions/:id/attach", upgradeWebSocket((c) => {
         const id = c.req.param("id") ?? "";
         const capability = c.req.query("cap") ?? "";
@@ -1165,7 +1196,7 @@ export function createApp(deps) {
         };
         const artifactTool = {
             name: NATIVE_MCP_TOOL_NAME,
-            description: "Save a verified dashboard to Artifacts. Use a prior persist_answer reference, or select this session's latest retained answer when the opaque reference is no longer available, without recomputing. The existing payload form remains available for compatibility.",
+            description: "Save a dashboard to Artifacts. Use a prior persist_answer reference, or select this session's latest retained answer when the opaque reference is no longer available, without recomputing. The host marks the artifact verified only when the referenced answer is one it grounded itself; a dashboard built from a payload you write is stored as unverified. The existing payload form remains available for compatibility.",
             inputSchema: NATIVE_SAVE_DASHBOARD_CONTRACT.inputSchema,
         };
         const persistAnswerTool = {
@@ -1196,11 +1227,15 @@ export function createApp(deps) {
         if (request.method === "tools/list")
             return isNotification ? invalidRequest() : c.json({
                 jsonrpc: "2.0", id,
-                result: { tools: nativeToolsForPurpose(nativeSession.purpose) },
+                result: { tools: [...nativeToolsForPurpose(nativeSession.purpose), ...(deps.nativeSessions?.componentTools(nativeSession.id) ?? [])] },
             });
         if (request.method !== "tools/call" || isNotification || !isRecord(request.params) || !Object.hasOwn(request.params, "arguments"))
             return methodNotFound();
         try {
+            if (typeof request.params.name === "string" && request.params.name.startsWith("warble_run_") && deps.nativeSessions && id !== null) {
+                const result = await deps.nativeSessions.callComponent(nativeSession.id, request.params.name, request.params.arguments, id, c.req.raw.signal);
+                return c.json({ jsonrpc: "2.0", id, result: { isError: result.status !== "ok", content: [{ type: "text", text: JSON.stringify(result) }], structuredContent: result } });
+            }
             if (nativeSession.purpose === "setup" && request.params.name === NATIVE_SETUP_RECOVERY_MCP_TOOL_NAME && deps.nativeSessions) {
                 const recovery = deps.nativeSessions.reportSetupRecovery(nativeSession.id, request.params.arguments, isRecord(request.params.arguments) && request.params.arguments.state === "reported_complete" && validateNativeSetupCompletion(deps, request.params.arguments.phase === "context" ? "context" : "connect"));
                 return c.json({ jsonrpc: "2.0", id, result: { content: [{ type: "text", text: JSON.stringify({ accepted: true, version: recovery.version }) }], structuredContent: { accepted: true, version: recovery.version } } });
@@ -1582,6 +1617,61 @@ export function createApp(deps) {
         }
     });
     // ---------------------------------------------------------------------
+    // Warble profile registry
+    // ---------------------------------------------------------------------
+    //
+    // Conversation profiles are selected from a server-held registry by id. The
+    // registry owns the directory, runs admission and resolves the launch tuple;
+    // a browser never submits a path for a session to run inside. Adding a
+    // profile takes a directory path on this machine, the same shape the adopt
+    // flow accepts for a project, and the registry copies and checks it.
+    const profileRegistryFailure = (c, error) => {
+        if (error instanceof ProfileRegistryError)
+            return c.json({ error: error.message }, error.status);
+        return c.json({ error: error instanceof Error ? error.message : String(error) }, 500);
+    };
+    app.get("/api/profiles", async (c) => {
+        if (!deps.profileRegistry)
+            return c.json({ error: "the profile registry is not configured on this BFF instance" }, 503);
+        try {
+            const rows = await deps.profileRegistry.list();
+            const response = { profiles: rows.map(toWarbleProfileDto) };
+            return c.json(response);
+        }
+        catch (error) {
+            return profileRegistryFailure(c, error);
+        }
+    });
+    app.post("/api/profiles", async (c) => {
+        if (!deps.profileRegistry)
+            return c.json({ error: "the profile registry is not configured on this BFF instance" }, 503);
+        const body = await c.req.json().catch(() => undefined);
+        if (typeof body !== "object" || body === null || Array.isArray(body) || !Object.keys(body).every((key) => key === "sourcePath")) {
+            return c.json({ error: "profile registration request is invalid: expected { sourcePath }" }, 400);
+        }
+        try {
+            const row = await deps.profileRegistry.add(body.sourcePath);
+            return c.json({ profile: toWarbleProfileDto(row) }, 201);
+        }
+        catch (error) {
+            return profileRegistryFailure(c, error);
+        }
+    });
+    app.delete("/api/profiles/:id", async (c) => {
+        if (!deps.profileRegistry)
+            return c.json({ error: "the profile registry is not configured on this BFF instance" }, 503);
+        const id = c.req.param("id");
+        if (!/^[a-z0-9][a-z0-9_-]{0,63}$/.test(id))
+            return c.json({ error: "profile id is invalid" }, 400);
+        try {
+            await deps.profileRegistry.remove(id);
+            return c.body(null, 204);
+        }
+        catch (error) {
+            return profileRegistryFailure(c, error);
+        }
+    });
+    // ---------------------------------------------------------------------
     // Harness introspection
     // ---------------------------------------------------------------------
     app.get("/api/harness", async (c) => {
@@ -1590,16 +1680,44 @@ export function createApp(deps) {
             return c.json({ error: "harness purpose must be exactly one of: setup, analysis, context_enrichment" }, 400);
         }
         const purpose = purposes[0];
+        // An optional registry id selects which conversation profile the analysis purpose describes.
+        // The server resolves it; the browser never names a directory.
+        const profiles = c.req.queries("profile") ?? [];
+        if (profiles.length > 1)
+            return c.json({ error: "harness profile must be given at most once" }, 400);
+        const requestedProfile = profiles[0];
+        if (requestedProfile !== undefined) {
+            if (!/^[a-z0-9][a-z0-9_-]{0,63}$/.test(requestedProfile))
+                return c.json({ error: "harness profile is invalid" }, 400);
+            if (purpose !== "analysis")
+                return c.json({ error: "harness profile is only selectable for analysis" }, 400);
+        }
+        const selectedProfile = requestedProfile !== undefined && requestedProfile !== DEFAULT_CONVERSATION_PROFILE ? requestedProfile : undefined;
         // Setup describes the raw bootstrap profile, before a project exists. The
         // other two profiles consume a bound project's context and stay gated.
         if (purpose !== "setup" && !isProjectBound(deps))
             return c.json({ error: PROJECT_NOT_BOUND_MESSAGE }, 409);
         if (!deps.describeHarnessBundle)
             return c.json({ error: "harness introspection is not configured" }, 500);
+        let selectedSource;
+        if (selectedProfile !== undefined) {
+            if (!deps.profileRegistry)
+                return c.json({ error: "the profile registry is not configured on this BFF instance" }, 503);
+            try {
+                selectedSource = (await deps.profileRegistry.resolveConversationProfileSource(selectedProfile)).sourceDir;
+            }
+            catch (error) {
+                return profileRegistryFailure(c, error);
+            }
+        }
         try {
             const routeOptions = effectiveRouteOptions(deps, { allowUnbound: purpose === "setup" });
-            const bundle = await deps.describeHarnessBundle(purpose, routeOptions);
-            assertHarnessBundlePurpose(bundle, purpose);
+            // Keep the two-argument call for the fixed profiles so existing describers and their tests see
+            // exactly the shape they always did; only a selection adds the third argument.
+            const bundle = selectedSource !== undefined
+                ? await deps.describeHarnessBundle(purpose, routeOptions, selectedSource)
+                : await deps.describeHarnessBundle(purpose, routeOptions);
+            assertHarnessBundlePurpose(bundle, purpose, selectedProfile);
             const setupRuntimeCorrection = purpose === "setup" ? persistedRuntimeCorrection(deps) : undefined;
             const setupReadiness = purpose === "setup"
                 ? setupRuntimeCorrection !== undefined
@@ -1616,7 +1734,7 @@ export function createApp(deps) {
             const nativeReadiness = purpose === "setup"
                 ? await deps.nativeSessions?.readiness().catch(() => undefined)
                 : await deps.nativeSessions?.readiness();
-            return c.json(buildHarnessDto(bundle, deps.store, routeOptions, purpose, nativeReadiness, setupReadiness));
+            return c.json(buildHarnessDto(bundle, deps.store, routeOptions, purpose, nativeReadiness, setupReadiness, selectedProfile));
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
@@ -1626,7 +1744,12 @@ export function createApp(deps) {
     // ---------------------------------------------------------------------
     // Config / setup pages
     // ---------------------------------------------------------------------
-    app.get("/api/config/runtime", (c) => c.json(deps.store.getRuntimeSettings()));
+    // Until the user saves, the effective runtime is the boot auth env, so report that rather than
+    // the seeded display default. Nothing here is persisted and no credential is read.
+    app.get("/api/config/runtime", (c) => {
+        const stored = deps.store.getRuntimeSettings();
+        return c.json(deps.store.hasExplicitRuntimeSettings() ? stored : runtimeSettingsFromAuthChoice(deps.baseRouteOptions.authChoice, stored));
+    });
     app.get("/api/config/runtime/readiness", (c) => {
         const correction = persistedRuntimeCorrection(deps);
         return c.json(correction ? { valid: false, correction } : { valid: true });
@@ -1673,9 +1796,31 @@ export function createApp(deps) {
             : { version: 1, status: "unavailable", provider, code: "runtime_unavailable", retryable: true };
         return c.json(result);
     });
+    /** pi-ai's built-in catalog (offline, no credentials) for the gateway option's suggestions. */
+    app.get("/api/harness/gateway-models", async (c) => {
+        const provider = c.req.query("provider")?.trim() || undefined;
+        try {
+            const catalog = await listPiAiCatalog(provider);
+            return c.json({
+                status: "ready",
+                providers: catalog.providers,
+                models: catalog.models.map((model) => ({ model: model.id, displayName: model.name })),
+            });
+        }
+        catch {
+            // A fixed reason: the load error is Node's module-resolution text, which can name local paths.
+            return c.json({ status: "unavailable", reason: GATEWAY_CATALOG_UNAVAILABLE });
+        }
+    });
     app.put("/api/config/runtime", async (c) => {
         const patch = await c.req.json().catch(() => ({}));
-        const updated = { ...deps.store.getRuntimeSettings(), ...patch };
+        // Seed the merge from what GET reports, so a first save patches the effective (boot) runtime.
+        const stored = deps.store.getRuntimeSettings();
+        const effective = deps.store.hasExplicitRuntimeSettings() ? stored : runtimeSettingsFromAuthChoice(deps.baseRouteOptions.authChoice, stored);
+        const updated = { ...effective, ...patch };
+        if (!isRuntimeAuthMode(updated.authMode)) {
+            return c.json({ error: "authMode must be one of subscription, byo, local, gateway" }, 400);
+        }
         // Derive the candidate live AuthChoice from the merged (not-yet-persisted)
         // settings and validate it BEFORE any mutation — a rejected save must leave
         // both the persisted settings and the live auth binding untouched.
@@ -1712,7 +1857,9 @@ export function createApp(deps) {
         if (candidateAuthChoice.mode !== "subscription") {
             const envStatus = detectAdapterEnv();
             for (const envVar of requiredInProcessCredentialEnvVars(updated)) {
-                const present = envVar === "OPENAI_API_KEY" ? envStatus.openaiCompatible : envStatus.anthropic;
+                const present = envVar === "OPENAI_API_KEY" ? envStatus.openaiCompatible
+                    : envVar === GATEWAY_API_KEY_ENV ? envStatus.gateway === true
+                        : envStatus.anthropic;
                 if (!present)
                     return c.json({ error: `${envVar} is not set on the server — required by a configured tier adapter` }, 400);
             }
@@ -1728,6 +1875,7 @@ export function createApp(deps) {
         }
         const revokedNativeSessionIds = deps.store.setRuntimeSettingsAndRevokeIncompatibleNativeSessions(updated);
         deps.nativeSessions?.revokeRuntimeCapabilities(revokedNativeSessionIds);
+        deps.structuredRuntime?.revoke();
         deps.revokeInteractiveTerminals?.();
         deps.setAuthChoice?.(candidateAuthChoice);
         // describeBundle branches its target on authChoice.mode, so a cached
@@ -1909,6 +2057,7 @@ export function createApp(deps) {
         }
         const revokedNativeSessionIds = deps.store.resetSetup();
         deps.nativeSessions?.revokeRuntimeCapabilities(revokedNativeSessionIds);
+        deps.structuredRuntime?.revoke();
         deps.revokeInteractiveTerminals?.();
         deps.unbindProject?.();
         // Reset also revokes the explicit runtime override. Restore the boot auth

package/dist-server/server/auth-choice.d.ts

@@ -3,14 +3,26 @@ import type { RuntimeSettings } from "./wire-types.js";
 /**
  * Maps the wizard's persisted `RuntimeSettings` to the harness-level `AuthChoice` that should
  * actually be dispatched with. `RuntimeSettings.authMode` is the wire/persisted vocabulary
- * (`"subscription" | "byo" | "local"`); `AuthChoice.mode` is the harness vocabulary
+ * (`"subscription" | "byo" | "local" | "gateway"`); `AuthChoice.mode` is the harness vocabulary
  * (`"subscription" | "api-key" | "local" | "gateway"`) — `"byo"` maps to `"api-key"`.
  *
  * For the `openai-compatible` adapter, the BFF reads `OPENAI_API_KEY` from its own process env
  * and injects it explicitly as `config.apiKey` — that adapter has no env self-read of its own.
  * For `anthropic`, `config.apiKey` is deliberately omitted so the adapter self-reads
  * `ANTHROPIC_API_KEY` from the process env itself (see `harness/providers/adapters/anthropic.ts`).
+ * For `gateway` (the `pi-ai` adapter), the BFF reads `GENBI_GATEWAY_API_KEY` and injects it as
+ * `config.apiKey` the same way — pi-ai never reads env vars or credential files on its own.
  * The key value is never read into `RuntimeSettings`, SQLite, or any log — only referenced here,
  * transiently, to build the in-memory `AuthChoice` passed straight to the adapter factory.
  */
 export declare function toAuthChoiceFromRuntimeSettings(settings: RuntimeSettings): AuthChoice;
+/** True for the wire `authMode` values `toAuthChoiceFromRuntimeSettings` can map. */
+export declare function isRuntimeAuthMode(value: unknown): value is RuntimeSettings["authMode"];
+/**
+ * The inverse of `toAuthChoiceFromRuntimeSettings`, for reporting the auth the BFF booted with
+ * (`WREN_HARNESS_MODE` / `MODEL` / `ENDPOINT` / flags) before the user has saved a runtime.
+ * Overlays only the auth-selection fields onto `base`; tier rows, deployment and hybrid stay the
+ * store's. Credentials never appear in the result. A boot adapter the wizard cannot represent
+ * leaves `base` untouched.
+ */
+export declare function runtimeSettingsFromAuthChoice(choice: AuthChoice, base: RuntimeSettings): RuntimeSettings;