@wrenai/genbi 0.0.1

package/dist-server/harness/route/codex-ask.js

@@ -0,0 +1,242 @@
+import { spawn } from "node:child_process";
+import { accessSync, constants as fsConstants } from "node:fs";
+import { createInterface } from "node:readline";
+import path from "node:path";
+import { enforceCompliance } from "../compliance/index.js";
+import { compileProfile } from "../compile/pipeline.js";
+import { createAgentEventEmitter } from "../events/index.js";
+import { CodexAskEventMapper } from "./codex-ask-events.js";
+import { resolveCodexLocalCli } from "./codex-local-cli.js";
+import { CODEX_ASK_COMPONENTS, } from "./codex-local-manifest.js";
+const CODEX_BILLING_ENV_KEYS = new Set([
+    "OPENAI_API_KEY",
+    "CODEX_API_KEY",
+    "AZURE_OPENAI_API_KEY",
+    "OPENAI_ORGANIZATION",
+    "OPENAI_ORG_ID",
+    "OPENAI_PROJECT",
+    "OPENAI_PROJECT_ID",
+]);
+const DEFAULT_CODEX_ASK_TIMEOUT_MS = 10 * 60 * 1000;
+export function buildCodexAskArgs(cli, options) {
+    if (!options.question.trim())
+        throw new Error("Codex Ask question must not be empty");
+    return [
+        ...cli.prefixArgs,
+        "dispatch",
+        options.irPath,
+        options.question,
+        "--component",
+        options.component ?? "answer_query",
+        "--project",
+        options.userProject,
+        "--codex-home",
+        options.codexHome,
+        "--orchestrator-model",
+        options.models.orchestrator,
+        "--cheap-model",
+        options.models.cheap,
+        "--strong-model",
+        options.models.strong,
+        "--server",
+        "wren",
+        "--server-command",
+        options.mcpServer.command,
+        ...options.mcpServer.prefixArgs.flatMap((arg) => arg.startsWith("-") ? [`--server-arg=${arg}`] : ["--server-arg", arg]),
+        "--server-arg",
+        "serve",
+        "--server-arg",
+        "mcp",
+        "--server-arg=--project",
+        "--server-arg",
+        options.userProject,
+        "--server-arg=--quiet",
+        "--inspect-tool",
+        "get_context",
+        "--query-tool",
+        "run_sql",
+        "--timeout",
+        String(options.timeoutMs),
+        ...(options.codexBin ? ["--codex-bin", options.codexBin] : []),
+        "--stream-json",
+    ];
+}
+export async function runCodexAskDefault(options) {
+    enforceCompliance(options.authChoice, { deployment: options.deployment ?? "personal" });
+    if (options.authChoice.provider !== "codex") {
+        throw new Error("Codex Ask runner requires a Codex subscription auth choice");
+    }
+    const agentId = options.agentId ?? "answer_query";
+    if (!CODEX_ASK_COMPONENTS.includes(agentId)) {
+        throw new Error(`codex:local Ask does not support the "${agentId}" component`);
+    }
+    const component = agentId;
+    const models = resolveModels(options.codexModels);
+    const codexHome = options.codexHome?.trim();
+    if (!codexHome || !path.isAbsolute(codexHome)) {
+        throw new Error("Codex Ask requires an absolute WREN_HARNESS_CODEX_HOME for its dedicated authenticated session home");
+    }
+    if (options.signal?.aborted)
+        throw new Error("warble-codex-local Ask was cancelled before start");
+    const emitter = createAgentEventEmitter(options.onEvent);
+    emitter.emit({ kind: "run.start", mode: "B", agentId: component });
+    try {
+        const irPath = options.irPath ?? (await compileProfile({
+            profileSource: options.profileSource,
+            userProject: options.userProject,
+            mode: "native",
+            ...(options.warbleBin !== undefined ? { warbleBin: options.warbleBin } : {}),
+            ...(options.workDir !== undefined ? { workDir: options.workDir } : {}),
+        })).irPath;
+        if (options.signal?.aborted)
+            throw new Error("warble-codex-local Ask was cancelled during preparation");
+        const cli = options.codexLocalCli ?? (await resolveCodexLocalCli(options.codexLocalBin));
+        if (options.signal?.aborted)
+            throw new Error("warble-codex-local Ask was cancelled during preparation");
+        const mcpServer = options.mcpServer ?? { command: resolveExecutableOnPath("wren"), prefixArgs: [] };
+        if (options.signal?.aborted)
+            throw new Error("warble-codex-local Ask was cancelled during preparation");
+        const timeoutMs = options.timeoutMs ?? DEFAULT_CODEX_ASK_TIMEOUT_MS;
+        const args = buildCodexAskArgs(cli, {
+            irPath,
+            question: options.question,
+            userProject: options.userProject,
+            codexHome,
+            models,
+            mcpServer,
+            timeoutMs,
+            component,
+            ...(options.codexBin !== undefined ? { codexBin: options.codexBin } : {}),
+        });
+        const mapper = new CodexAskEventMapper(models, component);
+        const finalText = await spawnCodexAsk(cli.command, args, mapper, emitter.emit, options.processTimeoutMs ?? timeoutMs + 5_000, options.signal);
+        emitter.emit({ kind: "run.finish", status: "answer" });
+        return { finalText };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        emitter.emit({ kind: "error", message });
+        emitter.emit({ kind: "run.finish", status: "error" });
+        throw error;
+    }
+}
+function resolveModels(value) {
+    const models = typeof value === "function" ? value() : value;
+    if (!models || !models.orchestrator.trim() || !models.cheap.trim() || !models.strong.trim()) {
+        throw new Error("Codex Ask requires orchestrator, cheap, and strong model bindings");
+    }
+    return models;
+}
+function resolveExecutableOnPath(name) {
+    for (const directory of (process.env.PATH ?? "").split(path.delimiter)) {
+        if (!directory)
+            continue;
+        const candidate = path.join(directory, name);
+        try {
+            accessSync(candidate, fsConstants.X_OK);
+            return candidate;
+        }
+        catch {
+            // Keep searching.
+        }
+    }
+    throw new Error(`could not find the "${name}" executable on PATH`);
+}
+function sanitizedCodexEnvironment() {
+    return Object.fromEntries(Object.entries(process.env).filter(([key, value]) => value !== undefined && !CODEX_BILLING_ENV_KEYS.has(key.toUpperCase())));
+}
+function spawnCodexAsk(command, args, mapper, emit, timeoutMs, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new Error("warble-codex-local Ask was cancelled before spawn"));
+            return;
+        }
+        const child = spawn(command, [...args], {
+            env: sanitizedCodexEnvironment(),
+            stdio: ["ignore", "pipe", "pipe"],
+            detached: process.platform !== "win32",
+        });
+        let stderr = "";
+        let settled = false;
+        let stopReason;
+        let killTimer;
+        const terminate = (childSignal) => {
+            if (child.pid !== undefined && process.platform !== "win32") {
+                try {
+                    process.kill(-child.pid, childSignal);
+                    return;
+                }
+                catch {
+                    // Fall through to the direct child.
+                }
+            }
+            child.kill(childSignal);
+        };
+        const stop = (reason) => {
+            if (settled || stopReason !== undefined)
+                return;
+            stopReason = reason;
+            terminate("SIGTERM");
+            killTimer = setTimeout(() => terminate("SIGKILL"), 1_000);
+        };
+        const timer = setTimeout(() => stop("timeout"), timeoutMs);
+        const cancel = () => stop("cancelled");
+        signal?.addEventListener("abort", cancel, { once: true });
+        const lines = createInterface({ input: child.stdout, crlfDelay: Infinity });
+        lines.on("line", (line) => {
+            if (settled || !line.trim())
+                return;
+            try {
+                for (const event of mapper.nextLine(line))
+                    emit(event);
+            }
+            catch (error) {
+                settled = true;
+                clearTimeout(timer);
+                signal?.removeEventListener("abort", cancel);
+                terminate("SIGTERM");
+                killTimer = setTimeout(() => terminate("SIGKILL"), 1_000);
+                reject(error);
+            }
+        });
+        child.stderr.on("data", (chunk) => {
+            if (stderr.length < 8_192)
+                stderr += chunk.toString("utf8");
+        });
+        child.on("error", (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (killTimer)
+                clearTimeout(killTimer);
+            signal?.removeEventListener("abort", cancel);
+            reject(new Error(`warble-codex-local Ask failed to start: ${error.message}`));
+        });
+        child.on("close", (code, childSignal) => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", cancel);
+            lines.close();
+            if (settled)
+                return;
+            settled = true;
+            if (stopReason === "timeout") {
+                reject(new Error(`warble-codex-local Ask timed out after ${timeoutMs}ms`));
+            }
+            else if (stopReason === "cancelled") {
+                reject(new Error("warble-codex-local Ask was cancelled"));
+            }
+            else if (code !== 0) {
+                reject(new Error(`warble-codex-local Ask exited with ${code ?? childSignal ?? "unknown"}: ${stderr.trim()}`));
+            }
+            else {
+                try {
+                    resolve(mapper.result());
+                }
+                catch (error) {
+                    reject(error);
+                }
+            }
+        });
+    });
+}

package/dist-server/harness/route/codex-local-cli.d.ts

@@ -0,0 +1,20 @@
+import type { ResolvedCli } from "./agent-sdk-cli.js";
+export declare class CodexLocalCliNotFoundError extends Error {
+    constructor(attempts: readonly string[]);
+}
+/**
+ * Resolves the warble `codex-local` dispatcher CLI in four tiers, mirroring
+ * `resolveAgentSdkCli`/`resolveWarbleBinary`:
+ *
+ * 1. `explicit` — trusted as-is, no existence check.
+ * 2. The pinned `@warble/codex-local` npm package this workspace depends on, run via
+ *    `node <dist/cli.js>`.
+ * 3. `PATH` — a `warble-codex-local` executable found by walking `PATH` directly (this resolver's
+ *    existing convention, unlike `resolveAgentSdkCli`'s `--help` probe).
+ * 4. A sibling `warble` repo's dev-mode invocation, gated behind the explicit
+ *    `WREN_HARNESS_ALLOW_WARBLE_SIBLING_CHECKOUT=1` opt-in — must not silently win over the pinned
+ *    package now that tier 2 exists.
+ *
+ * Throws {@link CodexLocalCliNotFoundError} (loud-fail) if none of the four work.
+ */
+export declare function resolveCodexLocalCli(explicit?: string): Promise<ResolvedCli>;

package/dist-server/harness/route/codex-local-cli.js

@@ -0,0 +1,78 @@
+import { accessSync, constants as fsConstants, existsSync } from "node:fs";
+import { delimiter, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { isWarbleSiblingCheckoutDevModeEnabled, resolveInstalledPackageBin } from "../npm-package-resolve.js";
+export class CodexLocalCliNotFoundError extends Error {
+    constructor(attempts) {
+        super(`could not resolve the warble-codex-local CLI:\n${attempts.map((attempt) => `  - ${attempt}`).join("\n")}`);
+        this.name = "CodexLocalCliNotFoundError";
+    }
+}
+/**
+ * Resolves the warble `codex-local` dispatcher CLI in four tiers, mirroring
+ * `resolveAgentSdkCli`/`resolveWarbleBinary`:
+ *
+ * 1. `explicit` — trusted as-is, no existence check.
+ * 2. The pinned `@warble/codex-local` npm package this workspace depends on, run via
+ *    `node <dist/cli.js>`.
+ * 3. `PATH` — a `warble-codex-local` executable found by walking `PATH` directly (this resolver's
+ *    existing convention, unlike `resolveAgentSdkCli`'s `--help` probe).
+ * 4. A sibling `warble` repo's dev-mode invocation, gated behind the explicit
+ *    `WREN_HARNESS_ALLOW_WARBLE_SIBLING_CHECKOUT=1` opt-in — must not silently win over the pinned
+ *    package now that tier 2 exists.
+ *
+ * Throws {@link CodexLocalCliNotFoundError} (loud-fail) if none of the four work.
+ */
+export async function resolveCodexLocalCli(explicit) {
+    if (explicit !== undefined)
+        return { command: explicit, prefixArgs: [] };
+    const attempts = [];
+    const packageBin = resolveInstalledPackageBin("@warble/codex-local", "warble-codex-local");
+    if (packageBin !== undefined)
+        return { command: process.execPath, prefixArgs: [packageBin] };
+    attempts.push(`"@warble/codex-local" is not installed (or declares no "warble-codex-local" bin) in this workspace`);
+    const fromPath = resolveOnPath("warble-codex-local");
+    if (fromPath !== undefined)
+        return { command: fromPath, prefixArgs: [] };
+    attempts.push('not found on PATH as "warble-codex-local"');
+    if (isWarbleSiblingCheckoutDevModeEnabled()) {
+        const sibling = findSiblingDevInvocation();
+        if (sibling !== undefined)
+            return sibling;
+        attempts.push('no sibling "warble/dispatcher/codex-local" package with a tsx dev entry was found');
+    }
+    else {
+        attempts.push(`sibling "warble" checkout dev mode is disabled (set WREN_HARNESS_ALLOW_WARBLE_SIBLING_CHECKOUT=1 to enable it)`);
+    }
+    throw new CodexLocalCliNotFoundError(attempts);
+}
+function resolveOnPath(binaryName) {
+    for (const dir of (process.env.PATH ?? "").split(delimiter)) {
+        if (!dir)
+            continue;
+        const candidate = join(dir, binaryName);
+        try {
+            accessSync(candidate, fsConstants.X_OK);
+            return candidate;
+        }
+        catch {
+            // Keep searching.
+        }
+    }
+    return undefined;
+}
+function findSiblingDevInvocation() {
+    let dir = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+    for (let i = 0; i < 10; i += 1) {
+        const parent = dirname(dir);
+        const pkgDir = join(parent, "warble", "dispatcher", "codex-local");
+        const tsx = join(pkgDir, "node_modules", ".bin", "tsx");
+        const entry = join(pkgDir, "src", "cli.ts");
+        if (existsSync(tsx) && existsSync(entry))
+            return { command: tsx, prefixArgs: [entry] };
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return undefined;
+}

package/dist-server/harness/route/codex-local-manifest.d.ts

@@ -0,0 +1,22 @@
+import type { Bundle } from "../bundle/schema.js";
+import type { ResolvedCli } from "./agent-sdk-cli.js";
+export interface CodexManifestModels {
+    readonly orchestrator: string;
+    readonly cheap: string;
+    readonly strong: string;
+}
+export declare const CODEX_ASK_COMPONENTS: readonly ["answer_query", "generate_dashboard"];
+export type CodexAskComponent = (typeof CODEX_ASK_COMPONENTS)[number];
+export declare const CODEX_ENRICH_COMPONENTS: readonly ["inspect_context", "draft_enrichment"];
+export type CodexManifestPurpose = "analysis" | "setup" | "context_enrichment";
+export declare function buildCodexAskManifestArgs(cli: ResolvedCli, irPath: string, models: CodexManifestModels, component?: CodexAskComponent): readonly string[];
+export declare function buildCodexBootstrapManifestArgs(cli: ResolvedCli, irPath: string): readonly string[];
+export declare function buildCodexEnrichmentManifestArgs(cli: ResolvedCli, irPath: string, models: CodexManifestModels, component: (typeof CODEX_ENRICH_COMPONENTS)[number]): readonly string[];
+export declare function describeCodexAskManifest(cli: ResolvedCli, irPath: string, models: CodexManifestModels): Promise<Bundle>;
+/**
+ * Setup is a raw/bootstrap profile, not an Ask profile. Its dispatcher has a
+ * dedicated whole-profile `manifest` command that neither needs nor accepts a
+ * bound Wren project, so never route it through the Ask-only component list.
+ */
+export declare function describeCodexBootstrapManifest(cli: ResolvedCli, irPath: string): Promise<Bundle>;
+export declare function describeCodexEnrichmentManifest(cli: ResolvedCli, irPath: string, models: CodexManifestModels): Promise<Bundle>;

package/dist-server/harness/route/codex-local-manifest.js

@@ -0,0 +1,180 @@
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { loadBundle } from "../bundle/loader.js";
+export const CODEX_ASK_COMPONENTS = ["answer_query", "generate_dashboard"];
+export const CODEX_ENRICH_COMPONENTS = ["inspect_context", "draft_enrichment"];
+export function buildCodexAskManifestArgs(cli, irPath, models, component = "answer_query") {
+    return [
+        ...cli.prefixArgs,
+        "manifest",
+        irPath,
+        "--component",
+        component,
+        "--orchestrator-model",
+        models.orchestrator,
+        "--cheap-model",
+        models.cheap,
+        "--strong-model",
+        models.strong,
+        // Manifest preparation validates an absolute MCP command but does not
+        // spawn it; the runtime binds the real Wren MCP command separately.
+        "--server-command",
+        process.execPath,
+        "--inspect-tool",
+        "get_context",
+        "--query-tool",
+        "run_sql",
+    ];
+}
+export function buildCodexBootstrapManifestArgs(cli, irPath) {
+    return [
+        ...cli.prefixArgs,
+        "manifest",
+        irPath,
+        "--server-command",
+        process.execPath,
+        "--source-tool",
+        "setup_execution",
+        "--context-tool",
+        "setup_execution",
+    ];
+}
+export function buildCodexEnrichmentManifestArgs(cli, irPath, models, component) {
+    return [
+        ...cli.prefixArgs,
+        "manifest",
+        irPath,
+        "--component",
+        component,
+        "--model",
+        component === "inspect_context" ? models.cheap : models.strong,
+        "--server-command",
+        process.execPath,
+        "--semantic-tool",
+        "get_context",
+        "--raw-material-tool",
+        "get_context",
+    ];
+}
+async function describeCodexComponentManifests(cli, irPath, components, argsFor) {
+    const ir = JSON.parse(await readFile(irPath, "utf8"));
+    const bundles = await Promise.all(components.map(async (component) => {
+        const stdout = await execCodexManifest(cli.command, argsFor(component));
+        return normalizeCodexManifest(JSON.parse(stdout), ir);
+    }));
+    const primary = bundles[0];
+    for (const bundle of bundles.slice(1)) {
+        if (bundle.manifest_version !== primary.manifest_version ||
+            JSON.stringify(bundle.compat) !== JSON.stringify(primary.compat) ||
+            bundle.profile !== primary.profile ||
+            bundle.target !== primary.target) {
+            throw new Error("Codex component manifests disagree on their target identity");
+        }
+    }
+    return loadBundle({ ...primary, agents: bundles.flatMap((bundle) => bundle.agents) });
+}
+export async function describeCodexAskManifest(cli, irPath, models) {
+    return describeCodexComponentManifests(cli, irPath, CODEX_ASK_COMPONENTS, (component) => buildCodexAskManifestArgs(cli, irPath, models, component));
+}
+/**
+ * Setup is a raw/bootstrap profile, not an Ask profile. Its dispatcher has a
+ * dedicated whole-profile `manifest` command that neither needs nor accepts a
+ * bound Wren project, so never route it through the Ask-only component list.
+ */
+export async function describeCodexBootstrapManifest(cli, irPath) {
+    const ir = JSON.parse(await readFile(irPath, "utf8"));
+    const stdout = await execCodexManifest(cli.command, buildCodexBootstrapManifestArgs(cli, irPath));
+    return normalizeCodexManifest(JSON.parse(stdout), ir);
+}
+export async function describeCodexEnrichmentManifest(cli, irPath, models) {
+    return describeCodexComponentManifests(cli, irPath, CODEX_ENRICH_COMPONENTS, (component) => buildCodexEnrichmentManifestArgs(cli, irPath, models, component));
+}
+function execCodexManifest(command, args) {
+    return new Promise((resolve, reject) => {
+        execFile(command, [...args], { maxBuffer: 32 * 1024 * 1024, timeout: 120_000 }, (error, stdout, stderr) => {
+            if (error) {
+                reject(new Error(`warble-codex-local manifest failed: ${stderr || error.message}`));
+                return;
+            }
+            resolve(stdout);
+        });
+    });
+}
+function records(value) {
+    return Array.isArray(value)
+        ? value.filter((entry) => typeof entry === "object" && entry !== null)
+        : [];
+}
+function normalizeCodexManifest(manifest, ir) {
+    const irComponents = records(ir["components"]);
+    const agents = records(manifest["agents"]).map((agent) => {
+        const id = String(agent["id"] ?? "");
+        const component = irComponents.find((candidate) => candidate["id"] === id);
+        if (!component)
+            throw new Error(`Codex manifest component "${id}" is absent from compiled IR`);
+        const irSteps = records(component["llm_calls"]);
+        const irGuards = records(component["guardrails"]);
+        const renderBlocks = records(component["effect"]?.["render_blocks"]);
+        const manifestGuards = (agent["guardrails"] ?? {});
+        return {
+            id,
+            verb: String(agent["verb"] ?? component["verb"] ?? id),
+            component_type: String(agent["component_type"] ?? component["type"] ?? "analytical"),
+            realization_kind: String(agent["realization_kind"] ?? component["realization_kind"] ?? "skill"),
+            trigger: String(agent["trigger"] ?? component["trigger"]?.["kind"] ?? "one_shot"),
+            outcome: String(agent["outcome"] ?? component["effect"]?.["outcome"] ?? "none"),
+            steps: records(agent["steps"]).map((step) => {
+                const name = String(step["name"] ?? "");
+                const source = irSteps.find((candidate) => candidate["name"] === name) ?? {};
+                const when = source["when"];
+                return {
+                    name,
+                    tier: String(step["tier"] ?? source["tier"] ?? "strong"),
+                    consumes: Array.isArray(step["consumes"]) ? step["consumes"].map(String) : [],
+                    produces: String(step["produces"] ?? source["produces"] ?? "result"),
+                    prompt: String(source["prompt"] ?? ""),
+                    realization: when
+                        ? { kind: "repair_fold", fold_into: String(when["target"] ?? ""), max_attempts: 1 }
+                        : { kind: "independent" },
+                    ...(when ? { when: { guard: String(when["guard"] ?? ""), target: String(when["target"] ?? "") } } : {}),
+                };
+            }),
+            guardrails: Object.fromEntries(irGuards.map((guard) => {
+                const name = String(guard["name"] ?? "");
+                const described = manifestGuards[name] ?? {};
+                return [
+                    name,
+                    {
+                        enforcement: String(described["enforcement"] ?? "codex-local"),
+                        locked: Boolean(guard["locked"]),
+                        ...(typeof guard["threshold"] === "number" ? { threshold: guard["threshold"] } : {}),
+                        ...(typeof guard["scope"] === "string" ? { scope: guard["scope"] } : {}),
+                    },
+                ];
+            })),
+            tools: records(agent["tools"]).map((tool) => ({ name: String(tool["name"] ?? ""), source: String(tool["source"] ?? "") })),
+            output_schema: {
+                properties: {
+                    blocks: {
+                        items: {
+                            anyOf: renderBlocks.map((block) => ({ properties: { type: { const: String(block["type"] ?? "") } } })),
+                        },
+                    },
+                },
+            },
+            capabilities: records(agent["capabilities"]).map((capability) => ({
+                capability: String(capability["capability"] ?? ""),
+                outcome: String(capability["outcome"] ?? "native"),
+                provided_by: typeof capability["via"] === "string" ? capability["via"] : "codex-local",
+                criticality: "required",
+            })),
+        };
+    });
+    return loadBundle({
+        manifest_version: manifest["manifest_version"],
+        compat: manifest["compat"],
+        profile: manifest["profile"],
+        target: manifest["target"],
+        agents,
+    });
+}

package/dist-server/harness/route/describe.d.ts

@@ -0,0 +1,54 @@
+import type { AuthChoice } from "../auth/index.js";
+import type { Bundle } from "../bundle/schema.js";
+import { type CodexManifestModels, type CodexManifestPurpose } from "./codex-local-manifest.js";
+/**
+ * The subset of `RouteOptions`/`InProcessOptions` needed to describe how a
+ * profile is CURRENTLY realized. `authChoice` is required (not optional)
+ * because it's the discriminator `describeBundle` branches on — see below —
+ * unlike `question`/`onEvent`/model-routing options, which don't affect what
+ * gets described.
+ */
+interface DescribeBundleBaseOptions {
+    readonly authChoice: AuthChoice;
+    readonly profileSource: string;
+    readonly warbleBin?: string;
+    readonly agentSdkBin?: string;
+    readonly codexLocalBin?: string;
+    readonly codexModels?: CodexManifestModels;
+    readonly workDir?: string;
+    /** Selects the executable component family shown by the purpose-scoped Harness. */
+    readonly codexManifestPurpose?: CodexManifestPurpose;
+}
+/** A profile whose context must be rebound to the currently bound project. */
+export interface BoundDescribeBundleOptions extends DescribeBundleBaseOptions {
+    /** Omitted by legacy bound callers; bootstrap must always be explicit. */
+    readonly context?: "bound_project";
+    readonly userProject: string;
+}
+/** A profile that owns its authored raw/bootstrap context and has no user project. */
+export interface BootstrapDescribeBundleOptions extends DescribeBundleBaseOptions {
+    readonly context: "bootstrap";
+}
+export type DescribeBundleOptions = BoundDescribeBundleOptions | BootstrapDescribeBundleOptions;
+/**
+ * Describes whichever back-end will ACTUALLY run a turn for
+ * `options.authChoice` — the invariant this maintains is: Harness-shown
+ * target == `runtimeDispatcher`'s prediction (`server/harness.ts`)
+ * == what `route()` really dispatches to. The IR itself stays target-neutral
+ * either way; only the DISPLAY artifact this function loads differs:
+ *
+ * - `authChoice.mode === "subscription"` (dispatched): compiles IR only
+ *   (`mode: "native"`, reusing `compileProfile`'s cache) — no vercel bundle
+ *   is produced on this path at all — then sources the display from the
+ *   claude-agent-sdk dispatcher's OWN `manifest` subcommand, which reads
+ *   that same IR and emits a structurally-identical-to-the-vercel-bundle
+ *   JSON (`target: "claude-agent-sdk:local"`) to stdout. This is genuinely
+ *   what dispatched runs — `runDispatchedDefault` (`./dispatched.js`) shells this same
+ *   dispatcher's `chat` subcommand against the same IR.
+ * - every other `authChoice.mode` (in-process: api-key/local/gateway): compiles
+ *   to a vercel bundle (`mode: "agnostic"`, `warble dispatch --target
+ *   vercel`) — unchanged pre-existing behavior; `runInProcessDefault`
+ *   (`./in-process.js`) calls this too rather than keeping its own copy.
+ */
+export declare function describeBundle(options: DescribeBundleOptions): Promise<Bundle>;
+export {};