@wrenai/genbi 0.0.1 → 0.0.3

package/README.md

@@ -8,8 +8,13 @@ The app does not write SQL itself. A question goes to the Wren agent harness,
 which answers with a structured envelope — the blocks to render, and whether the
 answer was verified — and the UI renders that.
 
-This README is for working on the app from source: getting it running, and the
-daily build/test/typecheck loop. Three companion docs cover the rest:
+To just run it, `npx @wrenai/genbi` is the whole story — see
+[Getting started](#getting-started) below, or [INSTALL.md](./INSTALL.md) for
+what it needs and how to configure it.
+
+The rest of this README is for working on the app **from source**: getting it
+running, and the daily build/test/typecheck loop. Three companion docs cover
+the rest:
 
 - [RUNNING.md](./RUNNING.md) — a live, BFF-backed dev loop against your own
   Warble build, and checking that the pieces still fit together.
@@ -20,10 +25,10 @@ daily build/test/typecheck loop. Three companion docs cover the rest:
 
 ## Developer preview
 
-`@wrenai/genbi` is at `0.0.0` and has not been published to npm. Nothing here is
-under a compatibility commitment yet — commands, environment variables and
-interfaces move without notice. The Codex runtime is supported in code but has
-not been exercised end to end; Claude is the one that is. See
+`@wrenai/genbi` is published at `0.0.3`. Nothing here is under a compatibility
+commitment yet — commands, environment variables and interfaces move without
+notice. The Codex runtime is supported in code but has not been exercised end
+to end; Claude is the one that is. See
 [MAINTAINING.md](./MAINTAINING.md#versioning) for what the version number does
 and does not promise.
 
@@ -40,8 +45,24 @@ pinned `@warble/*` packages are already pulled in by `pnpm install` — see
 
 ## Getting started
 
-This app lives in a pnpm workspace, so install JavaScript dependencies from
-the repo root:
+### Just run it
+
+```bash
+WREN_HARNESS_WORKSPACE_ROOT=/absolute/path/to/an/empty/directory npx @wrenai/genbi
+```
+
+That fetches the published package, downloads the Warble binary for your
+platform on install, and serves the built UI and the BFF from one process on
+`http://127.0.0.1:4787`. You still need a provider CLI you are logged in to
+(`claude` or `codex`) and the `wren` CLI on `PATH`.
+[INSTALL.md](./INSTALL.md) covers the prerequisites, what happens on first
+start, and every other environment variable.
+
+### From source
+
+Everything below is the development loop, and is only worth setting up if you
+are changing the app. It lives in a pnpm workspace, so install JavaScript
+dependencies from the repo root:
 
 ```bash
 corepack enable

package/dist-server/server/native-sessions.d.ts

@@ -95,6 +95,17 @@ export interface NativeVendorReadiness {
 export interface NativeProducerReadiness {
     readonly available: boolean;
     readonly category?: "native_session_producer_incompatible";
+    /**
+     * Why the preflight rejected the producer. Safe to send: every field is a
+     * fixed string plus a content digest of the resolved binary — the phase name,
+     * a `result=` token, and (for a Wren runtime rejection) one of that resolver's
+     * fixed sentences. None of them interpolate a path or process output.
+     *
+     * It is here because the category alone named a state without a cause, so an
+     * operator reading the Sessions view could not tell a missing binary from an
+     * incompatible one, and neither could a bug report.
+     */
+    readonly diagnostic?: string;
 }
 export interface NativePurposeReadiness {
     readonly scopeKind: "bootstrap" | "bound_project";
@@ -196,13 +207,30 @@ export interface NativeProducerIdentity {
     readonly executable: string;
     readonly identity: string;
 }
+/** One vendor's own preflight outcome. A vendor nobody selected must not speak for one that was. */
+export interface NativeProducerVendorProbe {
+    readonly available: boolean;
+    /** Browser-safe: a fixed sentence, never a path or process output. */
+    readonly reason?: string;
+    /** Fixed fields plus a content digest; never a command path or process output. */
+    readonly diagnostic: string;
+}
 export interface NativeProducerPreflightResult {
+    /** True when at least one vendor is usable — never a verdict on the vendor in use. */
     readonly available: boolean;
     readonly category?: typeof NATIVE_PRODUCER_CATEGORY;
     /** Server-only resolved executable and content identity for the eventual launch. */
     readonly producer?: NativeProducerIdentity;
     /** Server-only: fixed fields plus a content digest; never a command path or process output. */
     readonly diagnostic: string;
+    /**
+     * Per-vendor outcomes. The preflight probes every vendor so that readiness can
+     * answer for the one actually configured: the Codex leg requires a native Wren
+     * runtime the resolver can trace to the server's own repository, which an
+     * installed package can never satisfy, and a single boolean over both vendors
+     * let that failure take Claude down with it.
+     */
+    readonly vendors: Readonly<Record<NativeVendor, NativeProducerVendorProbe>>;
 }
 /**
  * Exercises the exact, file-only native dispatch boundary against the

package/dist-server/server/native-sessions.js

@@ -310,6 +310,24 @@ function configuredIrPath(irPath) {
         return false;
     }
 }
+/**
+ * Why a vendor's preflight rejected the producer. Each is a fixed sentence
+ * chosen here — none is built from a path, a command, or process output — so
+ * `nativeSessionLaunchFailure` may pass them through unchanged.
+ */
+const NATIVE_PRODUCER_REASONS = new Set([
+    "the Warble binary could not be resolved",
+    "the Warble binary could not be identified",
+    "the Warble binary could not be started",
+    "the Warble binary did not respond",
+    "the Warble binary rejected the dispatch probe",
+    "the Warble binary does not support the native session flags this build requires",
+    "the Warble binary could not be started for this vendor",
+    "the Warble binary did not respond for this vendor",
+    "Warble could not dispatch this profile for this vendor",
+    "Warble emitted a launch spec this build cannot run",
+    "the preflight could not create its temporary workspace",
+]);
 /** A deliberately small public classification; never expose process or filesystem detail. */
 export function nativeSessionLaunchFailure(error) {
     const message = error instanceof Error ? error.message : "";
@@ -319,8 +337,15 @@ export function nativeSessionLaunchFailure(error) {
         return message;
     if (message === "native session materialization prerequisites are unavailable")
         return message;
-    if (message === "native Wren runtime is unavailable")
-        return "native session materialization prerequisites are unavailable";
+    // Every NativeWrenRuntimeError message is `native Wren runtime is unavailable: `
+    // followed by one of that resolver's fixed literals; not one of them
+    // interpolates a path or process output, so the whole family may pass through.
+    // Matching the bare sentence, as this did, stopped matching anything once the
+    // resolver started naming which link in the chain broke.
+    if (message.startsWith("native Wren runtime is unavailable"))
+        return message;
+    if (NATIVE_PRODUCER_REASONS.has(message))
+        return message;
     if (message === "native session producer is incompatible")
         return message;
     if (message === "native session launch artifacts are unavailable" || message === "native session launch specification is invalid" || message === "native session launch specification is incompatible")
@@ -348,12 +373,25 @@ const NATIVE_HELP_MARKERS = [
     "--native-mcp",
     "--out",
 ];
-function nativeProducerResult(available, identity, phase, detail, producer) {
+function producerDiagnostic(identity, phase, detail) {
+    return `identity=${identity ?? "unavailable"} phase=${phase} ${detail}`;
+}
+/** A failure before any vendor-specific work rules out every vendor, for the same reason. */
+function everyVendorUnavailable(probe) {
+    const vendors = {};
+    for (const vendor of NATIVE_PROBE_TARGETS)
+        vendors[vendor] = probe;
+    return vendors;
+}
+/** A shared-phase outcome: it decided nothing vendor-specific, so it speaks for all of them. */
+function nativeProducerResult(available, identity, phase, detail, reason, producer) {
+    const diagnostic = producerDiagnostic(identity, phase, detail);
     return {
         available,
         ...(available ? {} : { category: NATIVE_PRODUCER_CATEGORY }),
-        ...(available && producer ? { producer } : {}),
-        diagnostic: `identity=${identity ?? "unavailable"} phase=${phase} ${detail}`,
+        ...(producer ? { producer } : {}),
+        diagnostic,
+        vendors: everyVendorUnavailable(available ? { available: true, diagnostic } : { available: false, reason, diagnostic }),
     };
 }
 function executableIdentity(executable) {
@@ -439,26 +477,34 @@ function runNativeProbe(command, args) {
 export async function probeNativeSessionProducer(input) {
     const executable = localExecutablePath(input.warbleBin);
     if (!executable)
-        return nativeProducerResult(false, undefined, "resolve", "result=binary_not_found");
+        return nativeProducerResult(false, undefined, "resolve", "result=binary_not_found", "the Warble binary could not be resolved");
     const identity = executableIdentity(executable);
     if (!identity)
-        return nativeProducerResult(false, undefined, "identity", "result=identity_unavailable");
+        return nativeProducerResult(false, undefined, "identity", "result=identity_unavailable", "the Warble binary could not be identified");
     const producer = { executable, identity };
     const help = await runNativeProbe(executable, ["dispatch", "--help"]);
     if (help.spawnFailed)
-        return nativeProducerResult(false, identity, "dispatch_help", "result=spawn_failed");
+        return nativeProducerResult(false, identity, "dispatch_help", "result=spawn_failed", "the Warble binary could not be started");
     if (help.timedOut)
-        return nativeProducerResult(false, identity, "dispatch_help", "result=timed_out");
+        return nativeProducerResult(false, identity, "dispatch_help", "result=timed_out", "the Warble binary did not respond");
     if (help.exitCode !== 0)
-        return nativeProducerResult(false, identity, "dispatch_help", `result=exit_code_${help.exitCode ?? "signal"}`);
+        return nativeProducerResult(false, identity, "dispatch_help", `result=exit_code_${help.exitCode ?? "signal"}`, "the Warble binary rejected the dispatch probe");
     const missingMarkers = NATIVE_HELP_MARKERS.filter((marker) => !help.output.includes(marker));
     if (missingMarkers.length > 0)
-        return nativeProducerResult(false, identity, "dispatch_help", `result=missing_markers_${missingMarkers.join(",")}`);
-    for (const purpose of NATIVE_PURPOSES) {
-        const irPath = input.irPaths[purpose];
-        if (!irPath || !configuredIrPath(irPath))
-            continue;
-        for (const vendor of NATIVE_PROBE_TARGETS) {
+        return nativeProducerResult(false, identity, "dispatch_help", `result=missing_markers_${missingMarkers.join(",")}`, "the Warble binary does not support the native session flags this build requires");
+    // Vendor is the outer loop on purpose. It used to be the inner one, and the
+    // first failing pair returned for the whole preflight — so a Codex rejection
+    // reported the producer incompatible even for a Claude-only install, which is
+    // exactly what an installed package produces.
+    const vendors = {};
+    for (const vendor of NATIVE_PROBE_TARGETS) {
+        let outcome = { available: true, diagnostic: producerDiagnostic(identity, `complete_${vendor}`, "result=compatible") };
+        for (const purpose of NATIVE_PURPOSES) {
+            const irPath = input.irPaths[purpose];
+            if (!irPath || !configuredIrPath(irPath))
+                continue;
+            const phase = `dispatch_${purpose}_${vendor}`;
+            const fail = (detail, reason) => ({ available: false, reason, diagnostic: producerDiagnostic(identity, phase, detail) });
             let root;
             try {
                 root = mkdtempSync(path.join(os.tmpdir(), "genbi-native-preflight-"));
@@ -478,32 +524,54 @@ export async function probeNativeSessionProducer(input) {
                 writeFileSync(scopePath, JSON.stringify({ version: "3", kind: NATIVE_DISPATCH_REGISTRY[purpose].scopeKind, scope_id: scopeId, cwd: outputRoot, entry: nativeEntryFor(purpose, vendor), ...(purpose === "setup" ? { bootstrap_root: bootstrapRoot } : {}), ...(wrenRuntime ? { wren_runtime: wrenRuntime } : {}), ...(binding ? { binding } : {}) }), { encoding: "utf8", mode: 0o600, flag: "wx" });
                 writeFileSync(mcpPath, JSON.stringify({ version: "1", url: "http://127.0.0.1:0/api/native-sessions/mcp", credential: "native-preflight-nonsecret" }), { encoding: "utf8", mode: 0o600, flag: "wx" });
                 const dispatched = await runNativeProbe(executable, ["dispatch", irPath, "--target", targetForProvider(vendor), "--purpose", purpose, "--native-scope", scopePath, "--native-mcp", mcpPath, "--out", outputRoot]);
-                const phase = `dispatch_${purpose}_${vendor}`;
-                if (dispatched.spawnFailed)
-                    return nativeProducerResult(false, identity, phase, "result=spawn_failed");
-                if (dispatched.timedOut)
-                    return nativeProducerResult(false, identity, phase, "result=timed_out");
-                if (dispatched.exitCode !== 0)
-                    return nativeProducerResult(false, identity, phase, `result=exit_code_${dispatched.exitCode ?? "signal"}`);
+                if (dispatched.spawnFailed) {
+                    outcome = fail("result=spawn_failed", "the Warble binary could not be started for this vendor");
+                    break;
+                }
+                if (dispatched.timedOut) {
+                    outcome = fail("result=timed_out", "the Warble binary did not respond for this vendor");
+                    break;
+                }
+                if (dispatched.exitCode !== 0) {
+                    outcome = fail(`result=exit_code_${dispatched.exitCode ?? "signal"}`, "Warble could not dispatch this profile for this vendor");
+                    break;
+                }
                 try {
                     readNativeLaunchSpec(outputRoot, purpose, vendor, scopeId, undefined, { version: "1", url: "http://127.0.0.1:0/api/native-sessions/mcp", credential: "native-preflight-nonsecret" });
                 }
                 catch {
-                    return nativeProducerResult(false, identity, phase, "result=launch_spec_incompatible");
+                    outcome = fail("result=launch_spec_incompatible", "Warble emitted a launch spec this build cannot run");
+                    break;
                 }
             }
             catch (error) {
-                if (error instanceof NativeWrenRuntimeError)
-                    return nativeProducerResult(false, identity, `dispatch_${purpose}_${vendor}`, `result=wren_runtime_unavailable (${error.message})`);
-                return nativeProducerResult(false, identity, `dispatch_${purpose}_${vendor}`, "result=preflight_workspace_unavailable");
+                outcome = error instanceof NativeWrenRuntimeError
+                    ? fail(`result=wren_runtime_unavailable (${error.message})`, error.message)
+                    : fail("result=preflight_workspace_unavailable", "the preflight could not create its temporary workspace");
+                break;
             }
             finally {
                 if (root)
                     rmSync(root, { recursive: true, force: true });
             }
         }
-    }
-    return nativeProducerResult(true, identity, "complete", "result=compatible", producer);
+        vendors[vendor] = outcome;
+    }
+    const usable = NATIVE_PROBE_TARGETS.filter((vendor) => vendors[vendor].available);
+    const available = usable.length > 0;
+    // When nothing is usable the summary must still carry each vendor's own cause;
+    // collapsing them to "no_compatible_vendor" would lose the only line that says
+    // what actually broke.
+    const vendorResults = NATIVE_PROBE_TARGETS
+        .map((vendor) => `${vendor}=${vendors[vendor].diagnostic.split(" result=")[1] ?? "unknown"}`)
+        .join(" ");
+    return {
+        available,
+        ...(available ? {} : { category: NATIVE_PRODUCER_CATEGORY }),
+        producer,
+        diagnostic: producerDiagnostic(identity, "complete", available ? `result=compatible_${usable.join("+")}` : `result=no_compatible_vendor ${vendorResults}`),
+        vendors,
+    };
 }
 function parseNativeSetupRecoveryReport(value) {
     const report = record(value);
@@ -1139,6 +1207,10 @@ export class NativeSessionService {
                 ? nativeSessionStateBaseAvailableForProject(this.materializationState(), configuredRoot)
                 : purpose === "setup" && projectAvailable && nativeSessionStateBaseAvailable(this.materializationState());
             const workspaceUnavailable = !projectAvailable || !stateAvailable;
+            // Only the configured vendor's own probe may block this purpose. Probing
+            // both and collapsing them into one boolean let an unselected vendor veto
+            // the selected one.
+            const selectedProducer = producer && dispatch ? producer.vendors[dispatch.provider] : undefined;
             const reason = runtimeCorrection
                 ?? (!dispatch && !legacyFixture
                     ? "native sessions require a saved Runtime & authentication binding"
@@ -1146,8 +1218,8 @@ export class NativeSessionService {
                         ? purpose === "setup" ? "native setup sessions require a workspace root" : "native sessions require a current bound project"
                         : workspaceUnavailable
                             ? "native session workspace is unavailable"
-                            : producer && !producer.available
-                                ? "native session producer is incompatible"
+                            : selectedProducer && !selectedProducer.available
+                                ? selectedProducer.reason ?? "native session producer is incompatible"
                                 : !irPath || !(this.options.dispatch !== undefined || configuredIrPath(irPath)) || !legacyProducerAvailable()
                                     ? "native session materialization prerequisites are unavailable"
                                     : mcpReadiness && !mcpReadiness.available
@@ -1160,6 +1232,17 @@ export class NativeSessionService {
                     ? `the ${executable} interactive CLI is not available on this machine`
                     : undefined);
             const vendorReadiness = {};
+            // Production readiness now reports every vendor, so the UI can say which
+            // one is unusable and why instead of only that "the producer" is.
+            if (!legacyFixture && producer)
+                for (const vendor of NATIVE_VENDORS) {
+                    const probe = producer.vendors[vendor];
+                    vendorReadiness[vendor] = probe?.available === false
+                        ? { available: false, reason: probe.reason ?? "native session producer is incompatible" }
+                        : !executableAvailable(vendor)
+                            ? { available: false, reason: `the ${vendor === "claude" ? "claude" : "codex"} interactive CLI is not available on this machine` }
+                            : { available: true };
+                }
             if (legacyFixture)
                 for (const vendor of NATIVE_VENDORS) {
                     const legacyExecutable = vendor === "claude" ? "claude" : "codex";
@@ -1174,7 +1257,16 @@ export class NativeSessionService {
                 scopeKind,
                 profile: definition.profile,
                 ...(dispatch ? { target: dispatch.target, targetLabel: dispatch.targetLabel } : {}),
-                ...(producer ? { producer: producer.available ? { available: true } : { available: false, category: NATIVE_PRODUCER_CATEGORY } } : {}),
+                // With a vendor selected this answers for that vendor; with none selected
+                // it falls back to "is any vendor usable", rather than claiming health
+                // no vendor could back.
+                ...(producer
+                    ? {
+                        producer: (selectedProducer ? selectedProducer.available : producer.available)
+                            ? { available: true, diagnostic: (selectedProducer ?? producer).diagnostic }
+                            : { available: false, category: NATIVE_PRODUCER_CATEGORY, diagnostic: (selectedProducer ?? producer).diagnostic },
+                    }
+                    : {}),
                 available: legacyAvailable,
                 ...(unavailable ? { reason: unavailable } : {}),
                 vendors: vendorReadiness,
@@ -1222,8 +1314,10 @@ export class NativeSessionService {
             ? configuredIr
             : await this.options.resolveDispatchIr(purpose, binding);
         const producer = this.legacyFixtureMode() ? undefined : await this.productionProducerPreflight();
-        if (producer && (!producer.available || !producer.producer))
-            throw new InteractiveLaunchError("native session producer is incompatible");
+        const launchProducer = producer ? producer.vendors[dispatchDefinition.provider] : undefined;
+        if (producer && (!launchProducer?.available || !producer.producer)) {
+            throw new InteractiveLaunchError(launchProducer?.reason ?? "native session producer is incompatible");
+        }
         if (producer?.producer)
             assertNativeProducerIdentity(producer.producer);
         const scopeId = resumed?.row.scopeId ?? newId("native-scope");

package/dist-server/server/runtime-binding.d.ts

@@ -41,10 +41,20 @@ export declare function collectBundleTierNames(bundle: {
 /** Reads the tier contract directly from a compiled Warble IR document. */
 export declare function collectIrTierNames(ir: unknown): string[];
 /**
- * Compiles the canonical profile source without rebinding its context and
- * extracts its tier contract from IR. This is intentionally independent of
- * auth choice and of any user project: the Setup form must discover the rows
- * before either exists.
+ * Reads the profile's tier contract, which the Setup form needs before an auth
+ * choice or a user project exists.
+ *
+ * A tier name is a static property of the profile — it comes from each
+ * `llm_calls[].tier` — so nothing here depends on what project is bound. The
+ * profile ships its own compiled IR next to it, so the contract is read from
+ * that and no Warble process runs at all.
+ *
+ * Compiling instead is the fallback, and only for a profile source that has no
+ * golden beside it (`WREN_HARNESS_PROFILE` pointed at someone's own profile
+ * tree). It is a fallback rather than the default because `warble compile`
+ * requires a resolvable context binding, and the shipped profiles are bound to
+ * a path that only resolves inside a checkout of this repository: in an
+ * installed package that compile fails, and the Setup form has no rows.
  */
 export declare function compileUnboundProfileTierNames(options: {
     readonly profileSource: string;

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

@@ -4,7 +4,7 @@
  * reads an API key only while constructing an in-memory in-process adapter spec.
  */
 import { createHash } from "node:crypto";
-import { mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { mkdtemp, readFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
@@ -233,12 +233,26 @@ export function collectIrTierNames(ir) {
     return [...seen];
 }
 /**
- * Compiles the canonical profile source without rebinding its context and
- * extracts its tier contract from IR. This is intentionally independent of
- * auth choice and of any user project: the Setup form must discover the rows
- * before either exists.
+ * Reads the profile's tier contract, which the Setup form needs before an auth
+ * choice or a user project exists.
+ *
+ * A tier name is a static property of the profile — it comes from each
+ * `llm_calls[].tier` — so nothing here depends on what project is bound. The
+ * profile ships its own compiled IR next to it, so the contract is read from
+ * that and no Warble process runs at all.
+ *
+ * Compiling instead is the fallback, and only for a profile source that has no
+ * golden beside it (`WREN_HARNESS_PROFILE` pointed at someone's own profile
+ * tree). It is a fallback rather than the default because `warble compile`
+ * requires a resolvable context binding, and the shipped profiles are bound to
+ * a path that only resolves inside a checkout of this repository: in an
+ * installed package that compile fails, and the Setup form has no rows.
  */
 export async function compileUnboundProfileTierNames(options) {
+    const goldenPath = path.join(path.resolve(options.profileSource), "ir.golden.json");
+    if (existsSync(goldenPath)) {
+        return collectIrTierNames(JSON.parse(await readFile(goldenPath, "utf8")));
+    }
     const workDir = await mkdtemp(path.join(tmpdir(), "wren-harness-runtime-tiers-"));
     try {
         const irPath = path.join(workDir, "ir.json");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wrenai/genbi",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Wren GenBI — the web UI for WrenAI: ask questions of your data and get dashboards back",
   "license": "Apache-2.0",
   "keywords": [