@wrenai/genbi 0.0.4 → 0.0.6

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/harness/tools/setup-native.d.ts

@@ -17,6 +17,13 @@ export interface SetupExecutionToolOptions {
      * never broaden either its cwd or its write scope beyond it.
      */
     readonly workspaceRoot: string;
+    /**
+     * The bound project directory of a project-bound setup step. When set and the
+     * directory exists, an `exec` without an explicit `cwd` runs there instead of
+     * at `workspaceRoot`; an explicit `cwd` still wins. Must lie within
+     * `workspaceRoot` (same containment check as an explicit `cwd`).
+     */
+    readonly defaultExecCwd?: string;
 }
 /**
  * A single flat top-level object, NOT a `z.discriminatedUnion` — a

package/dist-server/harness/tools/setup-native.js

@@ -109,7 +109,7 @@ export const setupExecutionInputSchema = z.object({
     cwd: z
         .string()
         .optional()
-        .describe('Optional for both actions: use this directory instead of the workspace root as the command cwd or the base for a relative write path (e.g. the project directory). Absolute or relative to the workspace root, and must resolve within it. Defaults to the workspace root when omitted. For exec, use this instead of "cd <dir> && ..." chaining.'),
+        .describe('Optional for both actions: use this directory instead of the workspace root as the command cwd or the base for a relative write path (e.g. the project directory). Absolute or relative to the workspace root, and must resolve within it. Defaults to the workspace root when omitted (for exec, the bound project directory once the step has one). For exec, use this instead of "cd <dir> && ..." chaining.'),
     path: z
         .string()
         .optional()
@@ -291,8 +291,11 @@ function resolveWritePath(workspaceRoot, requestedPath, requestedCwd) {
  * exec cwd to any directory within `workspaceRoot` (e.g. the project
  * directory), but never broaden it beyond that root.
  */
-function resolveExecCwd(workspaceRoot, requestedCwd) {
+function resolveExecCwd(workspaceRoot, requestedCwd, defaultCwd) {
     if (requestedCwd === undefined) {
+        if (defaultCwd !== undefined && existsSync(defaultCwd)) {
+            return assertWithinScope(workspaceRoot, defaultCwd, (requested, scope) => new SetupExecCwdScopeError(requested, scope));
+        }
         return workspaceRoot;
     }
     return assertWithinScope(workspaceRoot, requestedCwd, (requestedCwd, scope) => new SetupExecCwdScopeError(requestedCwd, scope));
@@ -319,7 +322,7 @@ export async function executeSetupExecution(input, options) {
             throw new SetupExecutionInputError("exec", "command");
         }
         assertCommandAllowed(input.command);
-        const cwd = resolveExecCwd(workspaceRoot, input.cwd);
+        const cwd = resolveExecCwd(workspaceRoot, input.cwd, options.defaultExecCwd);
         const result = await env.exec({ mode: "write", command: "/bin/sh", args: ["-c", input.command], cwd, timeoutMs: SETUP_EXEC_TIMEOUT_MS }, policy);
         const { stdout, stderr } = redactSetupExecutionOutput(input.command, result);
         return {
@@ -343,7 +346,7 @@ export function createSetupExecutionTool(options) {
     return tool({
         description: "Run a shell command or write a file within the setup workspace, subject to a destructive/redirection " +
             'command denylist and a workspace-root scope. Two call shapes: {action: "exec", command, cwd?} runs a ' +
-            "shell command (command is required; cwd is optional, defaults to the workspace root, and must resolve " +
+            "shell command (command is required; cwd is optional, defaults to the bound project directory for a project step once it exists (otherwise the workspace root), and must resolve " +
             'within it — path/content are unused); {action: "write", path, content, cwd?} writes a file (path and content ' +
             "are both required; a relative path uses cwd when supplied, otherwise the workspace root; command is unused). A call missing the field(s) its action requires, or " +
             "supplying a cwd/path that escapes the workspace root, is rejected before anything runs or is written.",

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";
@@ -23,9 +24,12 @@ import { verifyProposal } from "./enrichment-verify.js";
 import { canonicalizeProposal, hashEnrichmentOperation, NATIVE_ENRICHMENT_SUBMIT_INPUT_SCHEMA, NATIVE_ENRICHMENT_SUBMIT_MCP_TOOL_NAME, requiresApproval, resolveEnrichmentBinding, sameEnrichmentBinding, EnrichmentContractError } from "./enrichment.js";
 import { INTERACTIVE_TARGETS, InteractiveLaunchError } from "./interactive-terminal.js";
 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 { NATIVE_MCP_PERSIST_ANSWER_TOOL_NAME, NATIVE_MCP_QUERY_TOOL_NAME, NATIVE_MCP_TOOL_NAME, NATIVE_PERSIST_ANSWER_CONTRACT, NATIVE_QUERY_INPUT_SCHEMA, 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,14 +1196,19 @@ 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, or when a payload you write holds only table and definition blocks (plus an optional summary) and every definition cites a query this session ran through the query tool (by its query_id, else its SQL); its tables and definitions are then rebuilt from those query results and your summary is kept. A payload with any other block (narrative, chart, KPI) or an estimate flag is stored intact and unverified, as is any other payload. The existing payload form remains available for compatibility.",
             inputSchema: NATIVE_SAVE_DASHBOARD_CONTRACT.inputSchema,
         };
         const persistAnswerTool = {
             name: NATIVE_MCP_PERSIST_ANSWER_TOOL_NAME,
-            description: "Persist this answer's exact typed table and optional definition result before conversational presentation. idempotency_key is retry authority only; the host returns canonical provenance. On success, later save_dashboard calls should use its opaque answer_ref, with the session-scoped latest selector available if that ref leaves the conversation; on failure, present the answer but report that reference saving is unavailable.",
+            description: "Persist this answer's exact typed table and optional definition result before conversational presentation. idempotency_key is retry authority only; the host returns canonical provenance. On success, later save_dashboard calls should use its opaque answer_ref, with the session-scoped latest selector available if that ref leaves the conversation; on failure, present the answer but report that reference saving is unavailable. The host records the answer as verified only when its definition cites a query this session ran through the query tool (by its query_id, else its SQL); its table and definition are then rebuilt from that query's result. Any other answer is stored as written and unverified.",
             inputSchema: NATIVE_PERSIST_ANSWER_CONTRACT.inputSchema,
         };
+        const queryTool = {
+            name: NATIVE_MCP_QUERY_TOOL_NAME,
+            description: "Run one read-only SQL query through the host and return its rows plus a query_id. Cite that query_id in the definition block of the answer you persist or save; only answers whose every definition cites a query this session ran here can be recorded as verified.",
+            inputSchema: NATIVE_QUERY_INPUT_SCHEMA,
+        };
         const enrichmentSubmitTool = {
             name: NATIVE_ENRICHMENT_SUBMIT_MCP_TOOL_NAME,
             description: "Submit a drafted context enrichment proposal for host verification. The host re-checks the project binding, canonicalizes the proposal, and runs it through a shadow-copy verification ladder (grammar, sink, validate, build, dry-run) against a throwaway copy of the project -- the bound project itself is never written to. Only a verified proposal is recorded, into the same enrichment ledger a human reviews through accept/edit/skip. A refuted proposal is never recorded; the refuting step and reason are returned so the draft can be revised.",
@@ -1185,7 +1221,7 @@ export function createApp(deps) {
         const nativeToolsForPurpose = (purpose) => {
             switch (purpose) {
                 case "setup": return [setupTool];
-                case "analysis": return [persistAnswerTool, artifactTool];
+                case "analysis": return deps.nativeArtifacts?.queryAvailable() ? [queryTool, persistAnswerTool, artifactTool] : [persistAnswerTool, artifactTool];
                 case "context_enrichment": return [enrichmentSubmitTool];
                 default: {
                     const exhaustive = purpose;
@@ -1196,11 +1232,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 } } });
@@ -1209,6 +1249,10 @@ export function createApp(deps) {
                 const saved = deps.nativeArtifacts.save(credential, request.params.arguments);
                 return c.json({ jsonrpc: "2.0", id, result: { content: [{ type: "text", text: JSON.stringify(saved) }], structuredContent: saved } });
             }
+            if (nativeSession.purpose === "analysis" && request.params.name === NATIVE_MCP_QUERY_TOOL_NAME && deps.nativeArtifacts.queryAvailable()) {
+                const queried = await deps.nativeArtifacts.query(credential, request.params.arguments);
+                return c.json({ jsonrpc: "2.0", id, result: { isError: queried.isError, content: [{ type: "text", text: queried.text }], ...(queried.result !== undefined ? { structuredContent: queried.result } : {}) } });
+            }
             if (nativeSession.purpose === "analysis" && request.params.name === NATIVE_MCP_PERSIST_ANSWER_TOOL_NAME) {
                 const persisted = deps.nativeArtifacts.persistAnswer(credential, request.params.arguments);
                 return c.json({ jsonrpc: "2.0", id, result: { content: [{ type: "text", text: JSON.stringify(persisted) }], structuredContent: persisted } });
@@ -1582,6 +1626,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 +1689,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 +1743,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 +1753,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 +1805,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 +1866,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 +1884,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 +2066,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;

package/dist-server/server/auth-choice.js

@@ -1,13 +1,16 @@
+import { GATEWAY_API_KEY_ENV } from "./env-detect.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.
  */
@@ -17,6 +20,19 @@ export function toAuthChoiceFromRuntimeSettings(settings) {
             return { mode: "subscription", provider: settings.subscriptionProvider ?? "claude" };
         case "local":
             return { mode: "local" };
+        case "gateway": {
+            const config = {};
+            if (settings.gatewayProvider !== undefined)
+                config["provider"] = settings.gatewayProvider;
+            if (settings.gatewayModel !== undefined)
+                config["model"] = settings.gatewayModel;
+            if (settings.gatewayBaseURL?.trim())
+                config["baseUrl"] = settings.gatewayBaseURL;
+            const apiKey = process.env[GATEWAY_API_KEY_ENV];
+            if (apiKey?.trim())
+                config["apiKey"] = apiKey;
+            return { mode: "gateway", config };
+        }
         case "byo": {
             const adapter = settings.apiKeyAdapter ?? "anthropic";
             if (adapter === "openai-compatible") {
@@ -34,3 +50,52 @@ export function toAuthChoiceFromRuntimeSettings(settings) {
         }
     }
 }
+const RUNTIME_AUTH_MODES = new Set(["subscription", "byo", "local", "gateway"]);
+/** True for the wire `authMode` values `toAuthChoiceFromRuntimeSettings` can map. */
+export function isRuntimeAuthMode(value) {
+    return typeof value === "string" && RUNTIME_AUTH_MODES.has(value);
+}
+function stringField(config, key) {
+    const value = config?.[key];
+    return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+/**
+ * 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 function runtimeSettingsFromAuthChoice(choice, base) {
+    switch (choice.mode) {
+        case "subscription":
+            return { ...base, authMode: "subscription", subscriptionProvider: choice.provider };
+        case "local":
+            return { ...base, authMode: "local" };
+        case "gateway": {
+            const provider = stringField(choice.config, "provider");
+            const model = stringField(choice.config, "model");
+            const baseURL = stringField(choice.config, "baseUrl");
+            return {
+                ...base,
+                authMode: "gateway",
+                ...(provider !== undefined ? { gatewayProvider: provider } : {}),
+                ...(model !== undefined ? { gatewayModel: model } : {}),
+                ...(baseURL !== undefined ? { gatewayBaseURL: baseURL } : {}),
+            };
+        }
+        case "api-key": {
+            if (choice.adapter !== "anthropic" && choice.adapter !== "openai-compatible")
+                return base;
+            const model = stringField(choice.config, "model");
+            const baseURL = choice.adapter === "openai-compatible" ? stringField(choice.config, "baseURL") : undefined;
+            return {
+                ...base,
+                authMode: "byo",
+                apiKeyAdapter: choice.adapter,
+                ...(model !== undefined ? { apiKeyModel: model } : {}),
+                ...(baseURL !== undefined ? { apiKeyBaseURL: baseURL } : {}),
+            };
+        }
+    }
+}