@wrenai/genbi 0.0.1

package/dist-server/server/native-wren-runtime.d.ts

@@ -0,0 +1,20 @@
+export interface NativeWrenRuntime {
+    readonly version: "1";
+    readonly shim: string;
+    readonly launcher: string;
+    readonly venv_python: string;
+    readonly tool_root: string;
+    readonly site_packages: string;
+    readonly source_root: string;
+    readonly interpreter: string;
+    readonly interpreter_root: string;
+}
+export declare class NativeWrenRuntimeError extends Error {
+}
+/** The documented server default; deployments can set an explicit absolute shim path. */
+export declare function defaultNativeWrenShim(): string;
+/**
+ * Validates every launcher hop before serializing the exact read/execute
+ * closure. The source root comes only from the one editable .pth entry.
+ */
+export declare function resolveNativeWrenRuntime(configuredShim?: string): NativeWrenRuntime;

package/dist-server/server/native-wren-runtime.js

@@ -0,0 +1,259 @@
+/**
+ * Resolves the fixed Wren installation that a native Codex session may use.
+ * This is BFF configuration, never a browser, request, PATH, or permission
+ * input. The returned object is the closed scope shape consumed by Warble.
+ */
+import { accessSync, constants, lstatSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+export class NativeWrenRuntimeError extends Error {
+}
+function unavailable(reason) { throw new NativeWrenRuntimeError(`native Wren runtime is unavailable: ${reason}`); }
+function regularExecutable(file) {
+    try {
+        const canonical = realpathSync(file);
+        const stat = statSync(canonical);
+        if (!stat.isFile() || (stat.mode & 0o111) === 0)
+            unavailable("shim target is not an executable regular file");
+        return canonical;
+    }
+    catch (error) {
+        if (error instanceof NativeWrenRuntimeError)
+            throw error;
+        return unavailable("shim target could not be stat-ed");
+    }
+}
+function directory(directory) {
+    try {
+        const canonical = realpathSync(directory);
+        if (!statSync(canonical).isDirectory())
+            unavailable("expected a directory");
+        accessSync(canonical, constants.R_OK | constants.X_OK);
+        return canonical;
+    }
+    catch (error) {
+        if (error instanceof NativeWrenRuntimeError)
+            throw error;
+        return unavailable("directory could not be resolved");
+    }
+}
+function contained(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+/** Reject symlinks (including symlinked parents) and detect a replacement while reading. */
+function stableRegularFile(file) {
+    try {
+        const stat = lstatSync(file);
+        const canonical = realpathSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink() || canonical !== file)
+            unavailable("expected a stable regular file, not a symlink or an alias");
+        return { canonical, dev: stat.dev, ino: stat.ino, size: stat.size, mtimeMs: stat.mtimeMs, ctimeMs: stat.ctimeMs };
+    }
+    catch (error) {
+        if (error instanceof NativeWrenRuntimeError)
+            throw error;
+        return unavailable("file could not be stat-ed");
+    }
+}
+function stableFileText(file) {
+    const before = stableRegularFile(file);
+    let text;
+    try {
+        text = readFileSync(file, "utf8");
+    }
+    catch {
+        return unavailable("file could not be read");
+    }
+    const after = stableRegularFile(file);
+    if (before.canonical !== after.canonical || before.dev !== after.dev || before.ino !== after.ino ||
+        before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs)
+        unavailable("file changed while it was being read");
+    return text;
+}
+function gitCommonDirectory(repository) {
+    const gitEntry = path.join(repository, ".git");
+    try {
+        const entry = lstatSync(gitEntry);
+        if (entry.isSymbolicLink())
+            unavailable("git entry is a symlink");
+        if (entry.isDirectory())
+            return directory(gitEntry);
+        if (!entry.isFile())
+            unavailable("git entry is not a file");
+        const match = /^gitdir: ([^\r\n]+)\r?\n?$/.exec(stableFileText(gitEntry));
+        if (!match)
+            unavailable("gitdir line did not parse");
+        const worktreeGitDir = directory(path.resolve(repository, match[1]));
+        const commonDirFile = path.join(worktreeGitDir, "commondir");
+        try {
+            const commonDir = stableFileText(commonDirFile).trim();
+            if (!commonDir)
+                unavailable("no common git directory");
+            const commonDirectory = directory(path.resolve(worktreeGitDir, commonDir));
+            if (!contained(path.join(commonDirectory, "worktrees"), worktreeGitDir))
+                unavailable("worktree gitdir escapes the common directory");
+            const declaredGitFile = path.resolve(worktreeGitDir, stableFileText(path.join(worktreeGitDir, "gitdir")).trim());
+            if (declaredGitFile !== gitEntry)
+                unavailable("declared gitdir does not match the entry");
+            return commonDirectory;
+        }
+        catch (error) {
+            if (error instanceof NativeWrenRuntimeError)
+                throw error;
+            return worktreeGitDir;
+        }
+    }
+    catch (error) {
+        if (error instanceof NativeWrenRuntimeError)
+            throw error;
+        return unavailable("git layout could not be inspected");
+    }
+}
+/** Finds the repository that shipped this BFF; it is never supplied by a request or environment variable. */
+function serverRepositoryRoot() {
+    let candidate = path.dirname(fileURLToPath(import.meta.url));
+    while (true) {
+        try {
+            const repository = directory(candidate);
+            stableRegularFile(path.join(repository, "apps", "genbi", "package.json"));
+            stableRegularFile(path.join(repository, "core", "wren", "pyproject.toml"));
+            return repository;
+        }
+        catch (error) {
+            if (error instanceof NativeWrenRuntimeError) {
+                const parent = path.dirname(candidate);
+                if (parent === candidate)
+                    return unavailable("walked past the filesystem root looking for a repository");
+                candidate = parent;
+                continue;
+            }
+            return unavailable("repository root could not be found");
+        }
+    }
+}
+/**
+ * A runtime may use a sibling Git worktree, but never an arbitrary editable
+ * directory. Only that worktree's exact core/wren/src root is granted.
+ */
+function approvedWrenSourceRoot(sourceRoot) {
+    try {
+        const sourceEntry = lstatSync(sourceRoot);
+        const canonical = realpathSync(sourceRoot);
+        if (!sourceEntry.isDirectory() || sourceEntry.isSymbolicLink() || canonical !== sourceRoot)
+            unavailable("source root is not a plain directory");
+        const runtimeRepository = directory(path.resolve(sourceRoot, "..", "..", ".."));
+        if (sourceRoot !== path.join(runtimeRepository, "core", "wren", "src"))
+            unavailable("source root is not core/wren/src");
+        stableRegularFile(path.join(runtimeRepository, "core", "wren", "pyproject.toml"));
+        stableRegularFile(path.join(sourceRoot, "wren", "__init__.py"));
+        if (gitCommonDirectory(runtimeRepository) !== gitCommonDirectory(serverRepositoryRoot()))
+            unavailable("source repository differs from the server repository");
+        const after = lstatSync(sourceRoot);
+        if (!after.isDirectory() || after.isSymbolicLink() || realpathSync(sourceRoot) !== canonical)
+            unavailable("source root changed while being checked");
+        return canonical;
+    }
+    catch (error) {
+        if (error instanceof NativeWrenRuntimeError)
+            throw error;
+        return unavailable("source root could not be inspected");
+    }
+}
+/** The documented server default; deployments can set an explicit absolute shim path. */
+export function defaultNativeWrenShim() {
+    return path.join(os.homedir(), ".local", "bin", "wren");
+}
+/**
+ * Validates every launcher hop before serializing the exact read/execute
+ * closure. The source root comes only from the one editable .pth entry.
+ */
+export function resolveNativeWrenRuntime(configuredShim = defaultNativeWrenShim()) {
+    if (!path.isAbsolute(configuredShim))
+        unavailable("configured shim path is not absolute");
+    try {
+        const shimEntry = lstatSync(configuredShim);
+        if (!shimEntry.isSymbolicLink())
+            unavailable("shim is not a symlink");
+    }
+    catch {
+        unavailable("shim could not be stat-ed");
+    }
+    const shim = path.resolve(configuredShim);
+    const launcher = regularExecutable(shim);
+    const toolRoot = directory(path.dirname(path.dirname(launcher)));
+    const toolBin = path.join(toolRoot, "bin");
+    const venvPython = path.join(toolBin, "python");
+    if (launcher !== path.join(toolBin, "wren"))
+        unavailable("shim does not resolve to <tool root>/bin/wren");
+    try {
+        if (!lstatSync(venvPython).isSymbolicLink())
+            unavailable("tool venv python is not a symlink");
+    }
+    catch {
+        unavailable("tool venv python could not be stat-ed");
+    }
+    const interpreter = regularExecutable(venvPython);
+    const interpreterRoot = directory(path.dirname(path.dirname(interpreter)));
+    const interpreterBin = path.join(interpreterRoot, "bin");
+    if (!contained(interpreterBin, interpreter) || interpreter === interpreterBin)
+        unavailable("interpreter is not inside its own bin directory");
+    directory(path.join(interpreterRoot, "lib"));
+    let hasVenvMetadata = false;
+    try {
+        hasVenvMetadata = statSync(path.join(toolRoot, "pyvenv.cfg")).isFile();
+    }
+    catch { /* fail below */ }
+    if (!hasVenvMetadata)
+        unavailable("tool root has no pyvenv.cfg, so it is not a venv");
+    let launcherText;
+    try {
+        launcherText = readFileSync(launcher, "utf8");
+    }
+    catch { /* fail below */ }
+    if (launcherText === undefined || (!launcherText.startsWith(`#!${venvPython}\n`) && !launcherText.startsWith(`#!${venvPython}\r\n`)))
+        unavailable("launcher shebang does not point at the tool venv python");
+    const toolLib = directory(path.join(toolRoot, "lib"));
+    let sitePackages;
+    try {
+        const candidates = readdirSync(toolLib, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory() && /^python\d+(?:\.\d+)?$/.test(entry.name))
+            .map((entry) => path.join(toolLib, entry.name, "site-packages"))
+            .filter((candidate) => {
+            try {
+                return statSync(candidate).isDirectory() && stableRegularFile(path.join(candidate, "_editable_impl_wrenai.pth")) !== undefined;
+            }
+            catch {
+                return false;
+            }
+        });
+        if (candidates.length !== 1)
+            unavailable("expected exactly one lib/python*/site-packages");
+        sitePackages = directory(candidates[0]);
+        if (!contained(toolLib, sitePackages))
+            unavailable("site-packages escapes the tool lib directory");
+    }
+    catch (error) {
+        if (error instanceof NativeWrenRuntimeError)
+            throw error;
+        return unavailable("tool lib could not be inspected");
+    }
+    let sourceRoot;
+    try {
+        const lines = stableFileText(path.join(sitePackages, "_editable_impl_wrenai.pth"))
+            .split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+        if (lines.length !== 1 || !path.isAbsolute(lines[0]))
+            unavailable("pth file did not contain a single absolute path");
+        sourceRoot = approvedWrenSourceRoot(lines[0]);
+    }
+    catch (error) {
+        if (error instanceof NativeWrenRuntimeError)
+            throw error;
+        return unavailable("pth file could not be read");
+    }
+    return {
+        version: "1", shim, launcher, venv_python: venvPython, tool_root: toolRoot,
+        site_packages: sitePackages, source_root: sourceRoot, interpreter, interpreter_root: interpreterRoot,
+    };
+}

package/dist-server/server/node-pty-host.d.ts

@@ -0,0 +1,31 @@
+import { type PtyFactory, type PtyProcess } from "./interactive-terminal.js";
+interface NodePtyModule {
+    spawn(file: string, args: string[], options: {
+        cwd: string;
+        cols: number;
+        rows: number;
+        name: string;
+        env: NodeJS.ProcessEnv;
+    }): PtyProcess;
+}
+export interface PtyHostOptions {
+    readonly cwd?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly probeExecutable?: string;
+    readonly probeTimeoutMs?: number;
+}
+/**
+ * node-pty 1.1 ships a small spawn-helper for prebuilt macOS binaries. Some
+ * package managers restore that regular file without its executable mode,
+ * making every PTY fork fail with the otherwise opaque `posix_spawnp failed`.
+ * Repair only that fixed package-owned helper; a read-only installation will
+ * fail closed in the spawn probe below and leave the copy-command fallback.
+ */
+export declare function ensureDarwinNodePtySpawnHelper(nodePtyEntry: string, platform?: NodeJS.Platform, arch?: NodeJS.Architecture): void;
+/**
+ * Build the production PTY adapter only after a fixed, no-model Node process
+ * successfully starts. Importability alone is not a readiness signal: native
+ * helpers can load while process creation is still broken.
+ */
+export declare function createProbedPtyFactory(nodePty: NodePtyModule, options?: PtyHostOptions): Promise<PtyFactory>;
+export {};

package/dist-server/server/node-pty-host.js

@@ -0,0 +1,100 @@
+import { closeSync, constants, fchmodSync, fstatSync, lstatSync, openSync } from "node:fs";
+import path from "node:path";
+import { nativeTerminalEnvironment } from "./interactive-terminal.js";
+/**
+ * node-pty 1.1 ships a small spawn-helper for prebuilt macOS binaries. Some
+ * package managers restore that regular file without its executable mode,
+ * making every PTY fork fail with the otherwise opaque `posix_spawnp failed`.
+ * Repair only that fixed package-owned helper; a read-only installation will
+ * fail closed in the spawn probe below and leave the copy-command fallback.
+ */
+export function ensureDarwinNodePtySpawnHelper(nodePtyEntry, platform = process.platform, arch = process.arch) {
+    if (platform !== "darwin")
+        return;
+    if (arch !== "arm64" && arch !== "x64")
+        throw new Error("node-pty spawn helper is unavailable");
+    const entry = path.resolve(nodePtyEntry);
+    const packageRoot = path.resolve(path.dirname(entry), "..");
+    // node-pty 1.1 has exactly this package entry and helper layout. Do not
+    // generalize a permission repair to an arbitrary dependency path.
+    if (entry !== path.join(packageRoot, "lib", "index.js")) {
+        throw new Error("node-pty spawn helper is unavailable");
+    }
+    const prebuilds = path.join(packageRoot, "prebuilds");
+    const platformPrebuild = path.join(prebuilds, `${platform}-${arch}`);
+    const helper = path.join(platformPrebuild, "spawn-helper");
+    // lstat never follows a link. Reject every package-owned component before
+    // opening the helper so the fixed package path cannot be redirected.
+    for (const directory of [packageRoot, prebuilds, platformPrebuild]) {
+        if (!lstatSync(directory).isDirectory())
+            throw new Error("node-pty spawn helper is unavailable");
+    }
+    if (!lstatSync(helper).isFile())
+        throw new Error("node-pty spawn helper is unavailable");
+    // Keep the chmod bound to the opened object, not the path. O_NOFOLLOW and
+    // fchmod remove the final-component symlink and replacement race.
+    const fd = openSync(helper, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stat = fstatSync(fd);
+        if (!stat.isFile())
+            throw new Error("node-pty spawn helper is unavailable");
+        if ((stat.mode & 0o111) === 0)
+            fchmodSync(fd, stat.mode | 0o111);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/**
+ * Build the production PTY adapter only after a fixed, no-model Node process
+ * successfully starts. Importability alone is not a readiness signal: native
+ * helpers can load while process creation is still broken.
+ */
+export async function createProbedPtyFactory(nodePty, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const env = nativeTerminalEnvironment(options.env);
+    const probeExecutable = options.probeExecutable ?? process.execPath;
+    const probeTimeoutMs = options.probeTimeoutMs ?? 2_000;
+    let probe;
+    try {
+        probe = nodePty.spawn(probeExecutable, ["--version"], {
+            cwd,
+            cols: 80,
+            rows: 24,
+            name: "xterm-256color",
+            env,
+        });
+    }
+    catch {
+        throw new Error("interactive terminal host cannot spawn local processes");
+    }
+    await new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (error)
+                reject(error);
+            else
+                resolve();
+        };
+        const timer = setTimeout(() => {
+            probe.kill();
+            finish(new Error("interactive terminal host spawn probe timed out"));
+        }, probeTimeoutMs);
+        probe.onExit(({ exitCode }) => finish(exitCode === 0 ? undefined : new Error("interactive terminal host spawn probe failed")));
+    });
+    return {
+        spawn: (file, args, spawnOptions) => nodePty.spawn(file, [...args], {
+            cwd: spawnOptions.cwd,
+            cols: spawnOptions.cols,
+            rows: spawnOptions.rows,
+            name: "xterm-256color",
+            // Defend this lower adapter too: future PTY callers cannot bypass the
+            // server-owned native-terminal color contract by supplying an env.
+            env: nativeTerminalEnvironment(spawnOptions.env ?? env),
+        }),
+    };
+}

package/dist-server/server/route-intent.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Deterministic (no LLM) intent router: picks which compiled
+ * agent should serve a question. Mirrors `classifyClarify`'s shape (a plain
+ * regex classifier, no dependencies) so intent routing stays exactly as
+ * auditable and replay-safe as the clarify pre-flight — same reason: a
+ * question's classification must be reproducible on SSE replay without
+ * re-invoking any LLM.
+ *
+ * This function IS the intent taxonomy — extend the regexes
+ * here, don't grow a second classification path elsewhere. Rules, in
+ * priority order:
+ *
+ *  1. Explanation intent ("why", "explain", "what caused/drove/led to",
+ *     "reason", "driver", "because") -> "explain_change" (the narrative
+ *     bundle agent).
+ *  2. Dashboard intent ("dashboard", "chart", "graph", "plot",
+ *     "visuali[sz]e", "trend", "over time", "breakdown", "by <dimension>")
+ *     -> "generate_dashboard".
+ *  3. Everything else -> "answer_query" (the existing default).
+ *
+ * Explanation is checked first because a question can plausibly match both
+ * ("why did revenue trend down over time?") — explaining the driver is the
+ * more specific ask.
+ *
+ * `availableAgentIds` guards against routing to an agent the compiled bundle
+ * doesn't actually have (e.g. a profile that never declared
+ * `generate_dashboard`): when the rule-matched id isn't present, this falls
+ * back to `"answer_query"` — never throws, never returns an unknown id.
+ *
+ * Returns the chosen `agentId` alongside a short human `reason` for
+ * WHY that route was picked — surfaced as the turn's "Route" decision entry in
+ * the work log (see `server/turn.ts`). The routing LOGIC is unchanged; the
+ * reason is purely a display label.
+ */
+export interface IntentDecision {
+    readonly agentId: string;
+    /** Short human label for why this agent was chosen, e.g. `dashboard intent (chart)` or `default → answer_query`. */
+    readonly reason: string;
+}
+export declare function classifyIntent(question: string, availableAgentIds: readonly string[]): IntentDecision;

package/dist-server/server/route-intent.js

@@ -0,0 +1,23 @@
+export function classifyIntent(question, availableAgentIds) {
+    const q = question.trim();
+    const explainMatch = q.match(/\b(why|explain|what\s+(?:caused|drove|led to)|reason|driver|because)\b/i);
+    const dashboardMatch = q.match(/\b(dashboard|chart|graph|plot|visuali[sz]e|trend|over time|breakdown|by\s+(?:region|month|quarter|year|week|day|category|product|customer|segment))\b/i);
+    // Exact candidate-selection logic: explanation has priority over dashboard, and
+    // a rule-matched id that the bundle lacks falls straight back to answer_query
+    // (it does NOT then reconsider a lower-priority rule).
+    const candidate = explainMatch ? "explain_change" : dashboardMatch ? "generate_dashboard" : "answer_query";
+    if (availableAgentIds.includes(candidate)) {
+        if (candidate === "explain_change" && explainMatch) {
+            return { agentId: candidate, reason: `explanation intent (${keyword(explainMatch)})` };
+        }
+        if (candidate === "generate_dashboard" && dashboardMatch) {
+            return { agentId: candidate, reason: `dashboard intent (${keyword(dashboardMatch)})` };
+        }
+        return { agentId: candidate, reason: "default → answer_query" };
+    }
+    return { agentId: "answer_query", reason: "default → answer_query" };
+}
+/** The matched intent keyword, lowercased — group 1 when present, else the whole match. */
+function keyword(match) {
+    return (match[1] ?? match[0]).toLowerCase();
+}

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

@@ -0,0 +1,52 @@
+import type { AuthChoice, RouteOptions } from "../harness/index.js";
+import type { CodexManifestModels } from "../harness/route/codex-local-manifest.js";
+import type { RuntimeSettings, TierModelBinding } from "./wire-types.js";
+export declare class RuntimeBindingError extends Error {
+}
+/**
+ * The Claude Agent SDK accepts concrete model ids for its top-level driver,
+ * but its per-step `agents[].model` surface is deliberately narrower. Keep
+ * this product-side contract explicit so an invalid saved Runtime is rejected
+ * before a user turn reaches the dispatcher.
+ */
+export declare const CLAUDE_AGENT_SDK_PER_STEP_MODELS: readonly ["sonnet", "opus", "haiku", "inherit"];
+/** The old single Model field is the default for every tier without a model override. */
+export declare function effectiveTierModel(binding: TierModelBinding, settings: RuntimeSettings): string | undefined;
+/**
+ * Returns a browser-safe correction for an already persisted Runtime. This is
+ * intentionally narrower than catalog validation: provider catalog entries
+ * remain free-form wherever their dispatcher accepts concrete model ids. Only
+ * Claude's SDK subagent tier field has the closed alias union below.
+ */
+export declare function runtimeSettingsCorrection(settings: RuntimeSettings): string | undefined;
+/** Throws the same actionable error at every persisted-runtime dispatch boundary. */
+export declare function assertRuntimeSettingsDispatchable(settings: RuntimeSettings): void;
+/** Credential env vars used by the materialized in-process rows (local rows need none). */
+export declare function requiredInProcessCredentialEnvVars(settings: RuntimeSettings): string[];
+/** Validates the complete bundle map before Store/auth/live-route mutation. */
+export declare function validateRuntimeTierBindings(settings: RuntimeSettings, bundleTiers: readonly string[]): void;
+/** Generates the dispatcher-owned models config without ever serializing an API key. */
+export declare function writeClaudeModelsConfig(settings: RuntimeSettings, bundleTiers: readonly string[]): string;
+export declare function codexModelsForRuntime(settings: RuntimeSettings): CodexManifestModels;
+/** Materializes the already-validated live binding for the selected runtime. */
+export declare function materializeRuntimeRouteOptions(settings: RuntimeSettings, authChoice: AuthChoice): Pick<RouteOptions, "tierBinding" | "modelsConfig" | "codexModels">;
+/** Bundle-owned tier names, in first-seen order. */
+export declare function collectBundleTierNames(bundle: {
+    readonly agents: readonly {
+        readonly steps: readonly {
+            readonly tier: string;
+        }[];
+    }[];
+}): string[];
+/** 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.
+ */
+export declare function compileUnboundProfileTierNames(options: {
+    readonly profileSource: string;
+    readonly warbleBin?: string;
+}): Promise<string[]>;