@wrenai/genbi 0.0.1

package/dist-server/harness/bundle/version.d.ts

@@ -0,0 +1,10 @@
+import { type Bundle } from "./schema.js";
+export declare class BundleCompatError extends Error {
+    constructor(message: string);
+}
+export interface HarnessSupport {
+    readonly irVersion: string;
+    readonly bundleVersions: readonly string[];
+}
+export declare const HARNESS_SUPPORT: HarnessSupport;
+export declare function assertCompat(bundle: Bundle, support?: HarnessSupport): void;

package/dist-server/harness/bundle/version.js

@@ -0,0 +1,43 @@
+import { bundleFormatVersion } from "./schema.js";
+export class BundleCompatError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "BundleCompatError";
+    }
+}
+export const HARNESS_SUPPORT = {
+    irVersion: "0.6",
+    bundleVersions: ["0.1"],
+};
+function parseVersion(version) {
+    const parts = version.split(".").map(Number);
+    if (parts.some((part) => Number.isNaN(part))) {
+        throw new BundleCompatError(`malformed version string: "${version}"`);
+    }
+    return parts;
+}
+function compareVersions(a, b) {
+    const partsA = parseVersion(a);
+    const partsB = parseVersion(b);
+    const length = Math.max(partsA.length, partsB.length);
+    for (let index = 0; index < length; index += 1) {
+        const diff = (partsA[index] ?? 0) - (partsB[index] ?? 0);
+        if (diff !== 0)
+            return diff;
+    }
+    return 0;
+}
+export function assertCompat(bundle, support = HARNESS_SUPPORT) {
+    const formatVersion = bundleFormatVersion(bundle);
+    if (!support.bundleVersions.includes(formatVersion)) {
+        throw new BundleCompatError(`unsupported bundle format version "${formatVersion}"; ` +
+            `harness supports: ${support.bundleVersions.join(", ")}`);
+    }
+    const { min_ir_version: min, max_ir_version: max } = bundle.compat;
+    const withinMin = compareVersions(support.irVersion, min) >= 0;
+    const withinMax = compareVersions(support.irVersion, max) <= 0;
+    if (!withinMin || !withinMax) {
+        throw new BundleCompatError(`bundle compat window [${min}, ${max}] does not include harness IR ` +
+            `version "${support.irVersion}"`);
+    }
+}

package/dist-server/harness/capability/gate.d.ts

@@ -0,0 +1,6 @@
+import type { Bundle } from "../bundle/schema.js";
+import type { CapabilityRegistry } from "./registry.js";
+export declare class CapabilityGateError extends Error {
+    constructor(message: string);
+}
+export declare function assertCapabilities(bundle: Bundle, registry: CapabilityRegistry): void;

package/dist-server/harness/capability/gate.js

@@ -0,0 +1,29 @@
+const GATED_CRITICALITIES = new Set(["required", "safety-critical"]);
+export class CapabilityGateError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CapabilityGateError";
+    }
+}
+export function assertCapabilities(bundle, registry) {
+    const missing = [];
+    for (const agent of bundle.agents) {
+        for (const capability of agent.capabilities) {
+            if (!GATED_CRITICALITIES.has(capability.criticality))
+                continue;
+            if (registry.provides(capability.capability))
+                continue;
+            missing.push({
+                agentId: agent.id,
+                capability: capability.capability,
+                criticality: capability.criticality,
+            });
+        }
+    }
+    if (missing.length > 0) {
+        const detail = missing
+            .map((entry) => `  - agent "${entry.agentId}": ${entry.capability} (${entry.criticality})`)
+            .join("\n");
+        throw new CapabilityGateError(`missing required capabilities:\n${detail}`);
+    }
+}

package/dist-server/harness/capability/registry.d.ts

@@ -0,0 +1,6 @@
+export interface CapabilityRegistry {
+    provides(capability: string): boolean;
+}
+export declare const DEFAULT_CAPABILITIES: readonly string[];
+export declare function createRegistry(capabilities: readonly string[]): CapabilityRegistry;
+export declare function createDefaultCapabilityRegistry(): CapabilityRegistry;

package/dist-server/harness/capability/registry.js

@@ -0,0 +1,17 @@
+export const DEFAULT_CAPABILITIES = [
+    "llm:cheap",
+    "llm:strong",
+    "llm:per_step_tier",
+    "sql_execution:read_only",
+    "semantic_introspection",
+    "genbi_build",
+    "render_contract",
+    "artifact_write",
+];
+export function createRegistry(capabilities) {
+    const set = new Set(capabilities);
+    return { provides: (capability) => set.has(capability) };
+}
+export function createDefaultCapabilityRegistry() {
+    return createRegistry(DEFAULT_CAPABILITIES);
+}

package/dist-server/harness/cli-args.d.ts

@@ -0,0 +1,123 @@
+import type { AuthChoice, LoginProbe } from "./auth/index.js";
+import type { Deployment } from "./compliance/index.js";
+import type { AdapterSpec } from "./providers/index.js";
+import type { RouteResult } from "./route/types.js";
+/**
+ * Parsed CLI flags after normalization. Kept separate from `node:util`'s
+ * `parseArgs` inferred type so these pure helpers can be unit-tested with
+ * plain objects, and so `exactOptionalPropertyTypes` is satisfied (optional
+ * fields are omitted, never set to `undefined`).
+ */
+export interface CliFlags {
+    readonly project?: string;
+    readonly profile?: string;
+    readonly mode?: string;
+    readonly provider?: string;
+    readonly adapter?: string;
+    readonly apiKey?: string;
+    readonly model?: string;
+    readonly endpoint?: string;
+    readonly warbleBin?: string;
+    readonly agentSdkBin?: string;
+    readonly out?: string;
+    readonly deployment?: string;
+    /** Hybrid mode, in-process: repeatable `--tier-adapter <tier>=<mode>[:<field>=<value>,...]` entries. */
+    readonly tierAdapters?: readonly string[];
+    /** Hybrid mode, dispatched: `--models-config <path>`, forwarded verbatim to `warble-agent-sdk chat`. */
+    readonly modelsConfig?: string;
+    /** Dispatched only: `--chat-timeout-ms <n>`, overrides `spawnChat`'s default 10-minute hang guard. See `DispatchedOptions.chatTimeoutMs`. */
+    readonly chatTimeoutMs?: number;
+}
+/** Thrown for user-facing CLI misuse (bad/missing flags), surfaced as a top-level `error:` line. */
+export declare class CliUsageError extends Error {
+    constructor(message: string);
+}
+/** Validates the required `--project` and positional question, rejecting empty/whitespace-only values. */
+export declare function validateRequiredInputs(project: string | undefined, question: string): string;
+/**
+ * Resolves `--deployment`, defaulting to `"personal"` and rejecting any
+ * value other than `"personal"`/`"hosted"`. Kept separate from
+ * `enforceCompliance` so the CLI's flag validation (bad flag value) and the
+ * compliance gate's policy decision (which flag values imply what) stay two
+ * independently testable pure functions, matching `validateRequiredInputs`.
+ */
+export declare function resolveDeployment(flags: CliFlags): Deployment;
+/**
+ * Parses `--chat-timeout-ms`'s raw string value into a positive integer,
+ * rejecting anything else (blank, non-numeric, zero/negative, non-integer)
+ * as a CLI usage error rather than silently passing `NaN`/0 down to
+ * `spawnChat`'s `setTimeout`. Returns `undefined` when the flag was omitted.
+ */
+export declare function parseChatTimeoutMs(raw: string | undefined): number | undefined;
+/**
+ * Parses `WREN_HARNESS_SETUP_MAX_TURNS` (the agentic setup wizard's per-turn
+ * agent-loop budget, forwarded as `warble-agent-sdk chat --max-turns`) into a
+ * positive integer, rejecting anything else rather than silently passing
+ * `NaN`/0 down. Returns `undefined` when unset, so the setup runner's own
+ * default applies. The heavy step is `build_context` (generating an MDL takes
+ * many read/introspect/write/validate tool calls), which routinely exceeds the
+ * dispatcher's default 40-turn cap and fails with `error_max_turns`.
+ */
+export declare function parseSetupMaxTurns(raw: string | undefined): number | undefined;
+/**
+ * Default auth-selection policy when `--mode` is omitted: prefer an
+ * explicitly-configured `api-key` (`--adapter`) or `local` (`--endpoint`)
+ * choice — since the operator clearly meant one of those — over
+ * auto-detection; otherwise enumerate options via `detectAndPick(probe)` and
+ * pick a detected logged-in subscription CLI (claude, then codex); otherwise
+ * fail loudly rather than silently guess a mode with no supporting evidence.
+ * The `probe` is injected so the subscription-detection branch is testable
+ * offline; `main()` passes `createDefaultLoginProbe()`.
+ */
+export declare function resolveAuthChoice(flags: CliFlags, probe: LoginProbe): Promise<AuthChoice>;
+/** Builds an `AuthChoice` for an explicit `--mode`, validating the flags each mode requires. */
+export declare function buildExplicitAuthChoice(mode: string, flags: CliFlags): AuthChoice;
+/** Exit code contract for the packaged `bin`: 0 = answered, 1 = error (unhandled throw), 2 = refusal. */
+export declare const EXIT_OK = 0;
+export declare const EXIT_ERROR = 1;
+export declare const EXIT_REFUSAL = 2;
+/**
+ * A `RouteResult` with `kind: "refusal"` (in-process only — the agent
+ * declined to answer because a `locked` `gated_check` guardrail wasn't
+ * satisfied) is a completed *run*, not a crash, but it is also not an
+ * answer; a shell/pipeline consumer of the packaged `bin` piping the CLI's
+ * stdout needs a way to tell "ran but refused" (`EXIT_REFUSAL`) apart from
+ * both "answered" (`EXIT_OK`) and "failed to run" (`EXIT_ERROR`, the
+ * top-level `main().catch()` in `cli.ts`). Dispatched has no refusal state of
+ * its own to map here — `runDispatchedDefault` throws (in `dispatched.ts`) on
+ * an empty final answer rather than returning a refusal-shaped result, so
+ * that already lands on `EXIT_ERROR` via the same top-level catch.
+ */
+export declare function determineExitCode(result: RouteResult): number;
+/** api-key config from `--api-key`/`--model`; `undefined` when neither is set (so the adapter's own env lookup applies). */
+export declare function buildApiKeyConfig(flags: CliFlags): Record<string, unknown> | undefined;
+/** gateway config from `--endpoint`/`--model`/`--api-key`; `undefined` when none are set (so `deriveAdapterSpec` loud-fails). */
+export declare function buildGatewayConfig(flags: CliFlags): Record<string, unknown> | undefined;
+/** One parsed `--tier-adapter` entry, before it's turned into an `AdapterSpec`. */
+interface ParsedTierAdapterFlag {
+    readonly tier: string;
+    readonly mode: string;
+    readonly fields: Pick<CliFlags, "adapter" | "apiKey" | "model" | "endpoint">;
+}
+/**
+ * Parses one hybrid-mode `--tier-adapter <tier>=<mode>[:<field>=<value>,...]`
+ * entry — e.g. `cheap=local:endpoint=http://localhost:11434/v1,model=llama3.1`
+ * or `strong=api-key:adapter=anthropic,model=claude-opus-4-6`. `mode` is
+ * restricted to `api-key`/`local`/`gateway` — subscription has no adapter of
+ * its own (dispatched is the whole-run back-end, never a per-tier one), so
+ * naming it here is a loud-fail rather than a silent no-op.
+ */
+export declare function parseTierAdapterFlag(raw: string): ParsedTierAdapterFlag;
+/**
+ * Builds the hybrid-mode per-tier `AdapterSpec` map from every `--tier-adapter`
+ * flag the CLI collected. Each entry is parsed with {@link parseTierAdapterFlag},
+ * turned into an `AuthChoice` by reusing {@link buildExplicitAuthChoice} (so a
+ * per-tier `api-key`/`local`/`gateway` entry validates exactly like the
+ * top-level `--mode` flag does — e.g. `api-key` still requires `adapter=`),
+ * and then resolved to an `AdapterSpec` via `deriveAdapterSpec`. Coverage
+ * against the compiled agent's actual tiers (missing/unknown tier names) is
+ * `buildHybridTierBinding`'s job at run time — this function only turns argv
+ * into a map, without knowing what tiers the agent uses.
+ */
+export declare function buildTierBindingFromFlags(raw: readonly string[]): Record<string, AdapterSpec>;
+export {};

package/dist-server/harness/cli-args.js

@@ -0,0 +1,247 @@
+import { detectAndPick } from "./auth/index.js";
+import { deriveAdapterSpec } from "./route/adapter-spec.js";
+/** Thrown for user-facing CLI misuse (bad/missing flags), surfaced as a top-level `error:` line. */
+export class CliUsageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CliUsageError";
+    }
+}
+function isBlank(value) {
+    return value.trim().length === 0;
+}
+/** Validates the required `--project` and positional question, rejecting empty/whitespace-only values. */
+export function validateRequiredInputs(project, question) {
+    if (project === undefined || isBlank(project)) {
+        throw new CliUsageError("--project <dir> is required and must not be empty");
+    }
+    if (isBlank(question)) {
+        throw new CliUsageError("a non-empty question is required");
+    }
+    return project;
+}
+/**
+ * Resolves `--deployment`, defaulting to `"personal"` and rejecting any
+ * value other than `"personal"`/`"hosted"`. Kept separate from
+ * `enforceCompliance` so the CLI's flag validation (bad flag value) and the
+ * compliance gate's policy decision (which flag values imply what) stay two
+ * independently testable pure functions, matching `validateRequiredInputs`.
+ */
+export function resolveDeployment(flags) {
+    const value = flags.deployment ?? "personal";
+    if (value !== "personal" && value !== "hosted") {
+        throw new CliUsageError(`--deployment must be "personal" or "hosted", got "${value}"`);
+    }
+    return value;
+}
+/**
+ * Parses `--chat-timeout-ms`'s raw string value into a positive integer,
+ * rejecting anything else (blank, non-numeric, zero/negative, non-integer)
+ * as a CLI usage error rather than silently passing `NaN`/0 down to
+ * `spawnChat`'s `setTimeout`. Returns `undefined` when the flag was omitted.
+ */
+export function parseChatTimeoutMs(raw) {
+    if (raw === undefined)
+        return undefined;
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new CliUsageError(`--chat-timeout-ms must be a positive integer (milliseconds), got "${raw}"`);
+    }
+    return value;
+}
+/**
+ * Parses `WREN_HARNESS_SETUP_MAX_TURNS` (the agentic setup wizard's per-turn
+ * agent-loop budget, forwarded as `warble-agent-sdk chat --max-turns`) into a
+ * positive integer, rejecting anything else rather than silently passing
+ * `NaN`/0 down. Returns `undefined` when unset, so the setup runner's own
+ * default applies. The heavy step is `build_context` (generating an MDL takes
+ * many read/introspect/write/validate tool calls), which routinely exceeds the
+ * dispatcher's default 40-turn cap and fails with `error_max_turns`.
+ */
+export function parseSetupMaxTurns(raw) {
+    if (raw === undefined)
+        return undefined;
+    // `/^\d+$/` before Number() so hex/float/whitespace-padded spellings
+    // ("0x10", "1e3", " 40 ") are rejected rather than silently coerced.
+    const value = /^\d+$/.test(raw.trim()) ? Number(raw.trim()) : NaN;
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new CliUsageError(`WREN_HARNESS_SETUP_MAX_TURNS must be a positive integer, got "${raw}"`);
+    }
+    return value;
+}
+/**
+ * Default auth-selection policy when `--mode` is omitted: prefer an
+ * explicitly-configured `api-key` (`--adapter`) or `local` (`--endpoint`)
+ * choice — since the operator clearly meant one of those — over
+ * auto-detection; otherwise enumerate options via `detectAndPick(probe)` and
+ * pick a detected logged-in subscription CLI (claude, then codex); otherwise
+ * fail loudly rather than silently guess a mode with no supporting evidence.
+ * The `probe` is injected so the subscription-detection branch is testable
+ * offline; `main()` passes `createDefaultLoginProbe()`.
+ */
+export async function resolveAuthChoice(flags, probe) {
+    if (flags.mode !== undefined) {
+        return buildExplicitAuthChoice(flags.mode, flags);
+    }
+    if (flags.adapter !== undefined) {
+        const config = buildApiKeyConfig(flags);
+        return { mode: "api-key", adapter: flags.adapter, ...(config !== undefined ? { config } : {}) };
+    }
+    if (flags.endpoint !== undefined) {
+        return { mode: "local", endpoint: flags.endpoint };
+    }
+    // `--api-key`/`--model` without `--adapter` and without an explicit
+    // `--mode` used to fall straight through to subscription auto-detection
+    // below — silently discarding credentials the operator clearly configured
+    // for a *different* mode and answering via whatever subscription CLI
+    // happens to be logged in instead. Loud-fail instead of guessing an
+    // adapter or silently picking subscription.
+    if (flags.apiKey !== undefined || flags.model !== undefined) {
+        throw new CliUsageError("--api-key/--model given without --adapter <name> and without an explicit --mode; " +
+            "pass --adapter <name> (to use api-key mode) or set --mode explicitly — refusing to " +
+            "silently fall back to subscription auto-detection with credentials configured for a " +
+            "different mode");
+    }
+    const options = await detectAndPick(probe);
+    const subscription = options.find((option) => option.mode === "subscription");
+    if (subscription !== undefined) {
+        return { mode: "subscription", provider: subscription.provider };
+    }
+    throw new CliUsageError("no --mode given, no explicit --adapter/--endpoint configured, and no subscription CLI " +
+        "(claude or codex) detected as logged in; pass --mode explicitly " +
+        "(subscription|api-key|local|gateway)");
+}
+/** Builds an `AuthChoice` for an explicit `--mode`, validating the flags each mode requires. */
+export function buildExplicitAuthChoice(mode, flags) {
+    switch (mode) {
+        case "subscription": {
+            const provider = flags.provider ?? "claude";
+            if (provider !== "claude" && provider !== "codex") {
+                throw new CliUsageError(`--provider must be "claude" or "codex", got "${provider}"`);
+            }
+            return { mode: "subscription", provider };
+        }
+        case "api-key": {
+            if (flags.adapter === undefined) {
+                throw new CliUsageError("--mode api-key requires --adapter <name>");
+            }
+            const config = buildApiKeyConfig(flags);
+            return { mode: "api-key", adapter: flags.adapter, ...(config !== undefined ? { config } : {}) };
+        }
+        case "local":
+            return { mode: "local", ...(flags.endpoint !== undefined ? { endpoint: flags.endpoint } : {}) };
+        case "gateway": {
+            const config = buildGatewayConfig(flags);
+            return { mode: "gateway", ...(config !== undefined ? { config } : {}) };
+        }
+        default:
+            throw new CliUsageError(`--mode must be one of subscription|api-key|local|gateway, got "${mode}"`);
+    }
+}
+/** Exit code contract for the packaged `bin`: 0 = answered, 1 = error (unhandled throw), 2 = refusal. */
+export const EXIT_OK = 0;
+export const EXIT_ERROR = 1;
+export const EXIT_REFUSAL = 2;
+/**
+ * A `RouteResult` with `kind: "refusal"` (in-process only — the agent
+ * declined to answer because a `locked` `gated_check` guardrail wasn't
+ * satisfied) is a completed *run*, not a crash, but it is also not an
+ * answer; a shell/pipeline consumer of the packaged `bin` piping the CLI's
+ * stdout needs a way to tell "ran but refused" (`EXIT_REFUSAL`) apart from
+ * both "answered" (`EXIT_OK`) and "failed to run" (`EXIT_ERROR`, the
+ * top-level `main().catch()` in `cli.ts`). Dispatched has no refusal state of
+ * its own to map here — `runDispatchedDefault` throws (in `dispatched.ts`) on
+ * an empty final answer rather than returning a refusal-shaped result, so
+ * that already lands on `EXIT_ERROR` via the same top-level catch.
+ */
+export function determineExitCode(result) {
+    return "kind" in result && result.kind === "refusal" ? EXIT_REFUSAL : EXIT_OK;
+}
+/** api-key config from `--api-key`/`--model`; `undefined` when neither is set (so the adapter's own env lookup applies). */
+export function buildApiKeyConfig(flags) {
+    const config = {};
+    if (flags.apiKey !== undefined)
+        config["apiKey"] = flags.apiKey;
+    if (flags.model !== undefined)
+        config["model"] = flags.model;
+    return Object.keys(config).length > 0 ? config : undefined;
+}
+/** gateway config from `--endpoint`/`--model`/`--api-key`; `undefined` when none are set (so `deriveAdapterSpec` loud-fails). */
+export function buildGatewayConfig(flags) {
+    const config = {};
+    if (flags.endpoint !== undefined)
+        config["baseURL"] = flags.endpoint;
+    if (flags.model !== undefined)
+        config["model"] = flags.model;
+    if (flags.apiKey !== undefined)
+        config["apiKey"] = flags.apiKey;
+    return Object.keys(config).length > 0 ? config : undefined;
+}
+const TIER_ADAPTER_ALLOWED_MODES = new Set(["api-key", "local", "gateway"]);
+const TIER_ADAPTER_ALLOWED_FIELDS = new Set(["adapter", "apiKey", "model", "endpoint"]);
+/**
+ * Parses one hybrid-mode `--tier-adapter <tier>=<mode>[:<field>=<value>,...]`
+ * entry — e.g. `cheap=local:endpoint=http://localhost:11434/v1,model=llama3.1`
+ * or `strong=api-key:adapter=anthropic,model=claude-opus-4-6`. `mode` is
+ * restricted to `api-key`/`local`/`gateway` — subscription has no adapter of
+ * its own (dispatched is the whole-run back-end, never a per-tier one), so
+ * naming it here is a loud-fail rather than a silent no-op.
+ */
+export function parseTierAdapterFlag(raw) {
+    const tierEnd = raw.indexOf("=");
+    if (tierEnd <= 0) {
+        throw new CliUsageError(`--tier-adapter must be "<tier>=<mode>[:<field>=<value>,...]", got "${raw}"`);
+    }
+    const tier = raw.slice(0, tierEnd);
+    const rest = raw.slice(tierEnd + 1);
+    const fieldsStart = rest.indexOf(":");
+    const mode = fieldsStart === -1 ? rest : rest.slice(0, fieldsStart);
+    const fieldsRaw = fieldsStart === -1 ? "" : rest.slice(fieldsStart + 1);
+    if (!TIER_ADAPTER_ALLOWED_MODES.has(mode)) {
+        throw new CliUsageError(`--tier-adapter "${raw}": mode must be one of api-key|local|gateway (a hybrid tier has no ` +
+            `subscription adapter of its own), got "${mode}"`);
+    }
+    const fields = {};
+    if (fieldsRaw.length > 0) {
+        for (const pair of fieldsRaw.split(",")) {
+            const pairEq = pair.indexOf("=");
+            if (pairEq <= 0) {
+                throw new CliUsageError(`--tier-adapter "${raw}": malformed field "${pair}", expected key=value`);
+            }
+            const key = pair.slice(0, pairEq);
+            if (!TIER_ADAPTER_ALLOWED_FIELDS.has(key)) {
+                throw new CliUsageError(`--tier-adapter "${raw}": unknown field "${key}" (allowed: adapter, apiKey, model, endpoint)`);
+            }
+            fields[key] = pair.slice(pairEq + 1);
+        }
+    }
+    return { tier, mode, fields };
+}
+/**
+ * Builds the hybrid-mode per-tier `AdapterSpec` map from every `--tier-adapter`
+ * flag the CLI collected. Each entry is parsed with {@link parseTierAdapterFlag},
+ * turned into an `AuthChoice` by reusing {@link buildExplicitAuthChoice} (so a
+ * per-tier `api-key`/`local`/`gateway` entry validates exactly like the
+ * top-level `--mode` flag does — e.g. `api-key` still requires `adapter=`),
+ * and then resolved to an `AdapterSpec` via `deriveAdapterSpec`. Coverage
+ * against the compiled agent's actual tiers (missing/unknown tier names) is
+ * `buildHybridTierBinding`'s job at run time — this function only turns argv
+ * into a map, without knowing what tiers the agent uses.
+ */
+export function buildTierBindingFromFlags(raw) {
+    const tiers = {};
+    for (const entry of raw) {
+        const { tier, mode, fields } = parseTierAdapterFlag(entry);
+        if (tier in tiers) {
+            throw new CliUsageError(`--tier-adapter names tier "${tier}" more than once`);
+        }
+        try {
+            const authChoice = buildExplicitAuthChoice(mode, fields); // `mode` was already restricted to api-key|local|gateway above, so this is never "subscription".
+            tiers[tier] = deriveAdapterSpec(authChoice, fields.model !== undefined ? { model: fields.model } : {});
+        }
+        catch (error) {
+            throw new CliUsageError(`--tier-adapter "${entry}": ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return tiers;
+}

package/dist-server/harness/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist-server/harness/cli.js

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { createDefaultLoginProbe } from "./auth/index.js";
+import { buildTierBindingFromFlags, determineExitCode, parseChatTimeoutMs, resolveAuthChoice, resolveDeployment, validateRequiredInputs, } from "./cli-args.js";
+import { enforceCompliance } from "./compliance/index.js";
+import { resolveDefaultProfileSource, route } from "./route/index.js";
+const USAGE = `Usage: wren-harness <question> --project <dir> [options]
+
+Options:
+  --project <dir>         User's wren project directory (required)
+  --profile <dir>         Warble profile source directory (default: this package's profiles/genbi-default)
+  --mode <mode>           subscription | api-key | local | gateway (default: see policy below)
+  --provider <name>       subscription mode: claude | codex (default: claude)
+  --adapter <name>        api-key mode: provider registry adapter id (e.g. anthropic)
+  --api-key <key>         api-key mode: API key (omit to rely on the adapter's own env var lookup)
+  --model <name>          api-key/local mode: model name
+  --endpoint <url>        local/gateway mode: endpoint URL
+  --warble-bin <path>     Explicit warble binary (default: the installed @warble/cli, then PATH)
+  --agent-sdk-bin <path>  Explicit warble-agent-sdk CLI (subscription mode only)
+  --out <dir>             subscription mode: run output directory
+  --deployment <ctx>      personal | hosted (default: personal). "hosted" means multi-tenant,
+                          shared, or always-on-server use; subscription mode is rejected when
+                          --deployment hosted (use api-key or gateway instead).
+  --tier-adapter <spec>   Hybrid mode, in-process only (api-key/local/gateway): repeatable
+                          "<tier>=<mode>[:<field>=<value>,...]" entry binding one bundle tier to
+                          its own adapter, e.g. --tier-adapter cheap=local:endpoint=http://localhost:11434/v1
+                          --tier-adapter strong=api-key:adapter=anthropic,model=claude-opus-4-6
+                          Every tier the compiled agent uses must be bound exactly once (loud-fail
+                          on missing/unknown tier names); when given, replaces the uniform
+                          --mode/--adapter/--model binding for tier resolution.
+  --models-config <path>  Hybrid mode, dispatched only (subscription): path to warble-agent-sdk's own
+                          per-tier YAML config, forwarded verbatim as --models-config <path> to
+                          "warble-agent-sdk chat". Known limitation: warble's render stage still
+                          wall-hits on non-"render: none" components under a non-Anthropic tier.
+  --chat-timeout-ms <n>   dispatched only (subscription): overrides the default 10-minute hang guard
+                          on a "warble-agent-sdk chat" invocation. Raise this for a legitimately
+                          slower cold-start turn (e.g. right after onboarding a project) rather
+                          than the turn being killed and reported as a timeout.
+  --help                  Show this help
+
+Default auth-selection policy (when --mode is omitted), in order:
+  1. --adapter given  -> api-key, using --adapter/--api-key/--model
+  2. --endpoint given -> local, using --endpoint/--model
+  3. otherwise, a detected logged-in subscription CLI (claude, then codex) -> subscription
+  4. otherwise         -> error: pass --mode explicitly
+
+Compliance: subscription mode uses your personal provider subscription. It is allowed for
+--deployment personal (the default), printing a ToS warning to stderr; it is rejected outright for
+--deployment hosted, since sharing a personal subscription behind a multi-tenant/always-on server is
+account sharing. This harness never embeds a proxy relay for subscription auth.
+
+Exit codes:
+  0   answered — result JSON on stdout is a normal answer.
+  1   error — an unhandled exception (bad flags, compile/spawn failure, compliance rejection, etc).
+  2   refusal — the agent declined to answer (a locked guardrail wasn't satisfied); result JSON on
+      stdout is still the refusal envelope, only the exit code differs from a normal answer.
+`;
+async function main() {
+    const { values, positionals } = parseArgs({
+        args: process.argv.slice(2),
+        allowPositionals: true,
+        options: {
+            project: { type: "string" },
+            profile: { type: "string" },
+            mode: { type: "string" },
+            provider: { type: "string" },
+            adapter: { type: "string" },
+            "api-key": { type: "string" },
+            model: { type: "string" },
+            endpoint: { type: "string" },
+            "warble-bin": { type: "string" },
+            "agent-sdk-bin": { type: "string" },
+            out: { type: "string" },
+            deployment: { type: "string" },
+            "tier-adapter": { type: "string", multiple: true },
+            "models-config": { type: "string" },
+            "chat-timeout-ms": { type: "string" },
+            help: { type: "boolean" },
+        },
+    });
+    if (values.help === true) {
+        process.stdout.write(USAGE);
+        return;
+    }
+    if (positionals.length === 0) {
+        process.stderr.write(`error: a question is required\n\n${USAGE}`);
+        process.exitCode = 1;
+        return;
+    }
+    const chatTimeoutMs = parseChatTimeoutMs(values["chat-timeout-ms"]);
+    const flags = {
+        ...(values.project !== undefined ? { project: values.project } : {}),
+        ...(values.profile !== undefined ? { profile: values.profile } : {}),
+        ...(values.mode !== undefined ? { mode: values.mode } : {}),
+        ...(values.provider !== undefined ? { provider: values.provider } : {}),
+        ...(values.adapter !== undefined ? { adapter: values.adapter } : {}),
+        ...(values["api-key"] !== undefined ? { apiKey: values["api-key"] } : {}),
+        ...(values.model !== undefined ? { model: values.model } : {}),
+        ...(values.endpoint !== undefined ? { endpoint: values.endpoint } : {}),
+        ...(values["warble-bin"] !== undefined ? { warbleBin: values["warble-bin"] } : {}),
+        ...(values["agent-sdk-bin"] !== undefined ? { agentSdkBin: values["agent-sdk-bin"] } : {}),
+        ...(values.out !== undefined ? { out: values.out } : {}),
+        ...(values.deployment !== undefined ? { deployment: values.deployment } : {}),
+        ...(values["tier-adapter"] !== undefined ? { tierAdapters: values["tier-adapter"] } : {}),
+        ...(values["models-config"] !== undefined ? { modelsConfig: values["models-config"] } : {}),
+        ...(chatTimeoutMs !== undefined ? { chatTimeoutMs } : {}),
+    };
+    const question = positionals.join(" ");
+    const project = validateRequiredInputs(flags.project, question);
+    const profileSource = flags.profile ?? resolveDefaultProfileSource();
+    const authChoice = await resolveAuthChoice(flags, createDefaultLoginProbe());
+    const deployment = resolveDeployment(flags);
+    // Compliance gate: run (and surface any ToS warning) before the back-end runs.
+    // A rejection (subscription + hosted) throws ComplianceError, caught below like any
+    // other error. route() re-runs the same gate as a structural backstop for any other
+    // caller of route() that doesn't go through this CLI.
+    const { warnings } = enforceCompliance(authChoice, { deployment });
+    for (const warning of warnings) {
+        process.stderr.write(`warning: ${warning}\n`);
+    }
+    // Hybrid mode: --tier-adapter (in-process) and --models-config (dispatched) are each
+    // meaningful for exactly one back-end; route() itself loud-fails (a plain
+    // Error, caught like any other error below) if the wrong one is supplied
+    // for the resolved authChoice.mode, so no separate CLI-level guard is
+    // duplicated here.
+    const tierBinding = flags.tierAdapters !== undefined ? buildTierBindingFromFlags(flags.tierAdapters) : undefined;
+    const result = await route({
+        authChoice,
+        profileSource,
+        userProject: project,
+        question,
+        deployment,
+        ...(flags.model !== undefined ? { model: flags.model } : {}),
+        ...(flags.warbleBin !== undefined ? { warbleBin: flags.warbleBin } : {}),
+        ...(flags.agentSdkBin !== undefined ? { agentSdkBin: flags.agentSdkBin } : {}),
+        ...(flags.out !== undefined ? { outDir: flags.out } : {}),
+        ...(tierBinding !== undefined ? { tierBinding } : {}),
+        ...(flags.modelsConfig !== undefined ? { modelsConfig: flags.modelsConfig } : {}),
+        ...(flags.chatTimeoutMs !== undefined ? { chatTimeoutMs: flags.chatTimeoutMs } : {}),
+    });
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    // A refusal is printed exactly as before — only the exit code
+    // changes, so callers that already parse stdout JSON are unaffected;
+    // callers that only check the exit code now see EXIT_REFUSAL (2), not a
+    // false-success 0. See `determineExitCode`'s doc comment for the contract.
+    process.exitCode = determineExitCode(result);
+}
+main().catch((error) => {
+    process.stderr.write(`error: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+});