@wrenai/genbi 0.0.1

package/dist-server/harness/route/in-process.js

@@ -0,0 +1,106 @@
+import os from "node:os";
+import path from "node:path";
+import { createDefaultCapabilityRegistry } from "../capability/registry.js";
+import { createLocalExecutionEnv } from "../exec/index.js";
+import { deriveEnforcement } from "../guardrails/index.js";
+import { createDefaultProviderRegistry } from "../providers/index.js";
+import { runAgent } from "../session/index.js";
+import { createWrenNativeToolRegistry, resolveWrenBinary } from "../tools/index.js";
+import { deriveAdapterSpec } from "./adapter-spec.js";
+import { describeBundle } from "./describe.js";
+import { buildHybridTierBinding, buildUniformTierBinding } from "./tier-binding.js";
+const ANSWER_QUERY_AGENT_ID = "answer_query";
+/** Operator-wide override for `resolveArtifactsDir`'s default, e.g. for a long-running BFF process. */
+const ARTIFACTS_DIR_ENV_VAR = "WREN_HARNESS_ARTIFACTS_DIR";
+/** Projects a bundle-wide validated map onto the component selected for one turn. */
+export function filterTierBindingForAgent(agent, tierBinding) {
+    return Object.fromEntries([...new Set(agent.steps.map((step) => step.tier))]
+        .filter((tier) => tierBinding[tier] !== undefined)
+        .map((tier) => [tier, tierBinding[tier]]));
+}
+/**
+ * Resolves the `rootDir` the native `write_artifact` tool's
+ * `createLocalExecutionEnv` scope is rooted at. Precedence: an explicit
+ * `outDir` (per-call override, e.g. `InProcessOptions.outDir` /
+ * `WREN_HARNESS_OUT`) > the `WREN_HARNESS_ARTIFACTS_DIR` env var
+ * (operator-wide override) > a fixed `os.tmpdir()` subdirectory.
+ * Deliberately NEVER `process.cwd()` — that was the bug this fixes:
+ * `runInProcessDefault` used to call `createLocalExecutionEnv()` with no
+ * `rootDir` at all, which defaults to `process.cwd()` (`harness/exec/local.ts`)
+ * — for a live BFF process that's wherever this package's server process
+ * happens to be launched from, so every `write_artifact` call (from
+ * `explain_change`/`generate_dashboard`, both scoped-write-gated) dropped its
+ * output straight into whatever directory started the process.
+ *
+ * This is entirely independent of `projectDir` (`options.userProject`),
+ * which is the ONLY thing that governs the `query` tool's exec cwd (see
+ * `createWrenQueryTool` in `harness/tools/native.ts` — it takes `projectDir` as
+ * its `cwd` directly, never touching `env`'s own `rootDir`). Changing this
+ * default never changes where `query` runs.
+ */
+export function resolveArtifactsDir(outDir) {
+    return outDir ?? process.env[ARTIFACTS_DIR_ENV_VAR] ?? path.join(os.tmpdir(), "wren-harness-artifacts");
+}
+/**
+ * In-process ("api-key" | "local" | "gateway"): compile the profile to a vercel
+ * bundle (unless `options.bundle` overrides it, for tests), resolve which
+ * compiled agent to run (`options.agentId`, defaulting to
+ * `ANSWER_QUERY_AGENT_ID` — intent routing picks this upstream in
+ * `server/turn.ts`, not here), assemble a `RunAgentContext` bound either to a
+ * single adapter covering every tier that agent uses (the default), or —
+ * when `options.tierBinding` is set ("hybrid" mode) — to that non-uniform
+ * per-tier map, validated via `buildHybridTierBinding`; wire its `query` tool
+ * to the real `wren` CLI against `options.userProject` (unless
+ * `options.mcpServers` overrides it, for tests), and run it in-process via
+ * `runAgent`.
+ */
+export async function runInProcessDefault(options) {
+    const bundle = options.bundle ?? (await describeBundle(options));
+    // Intent routing (server/turn.ts) picks the agent id when present; falls back to answer_query,
+    // the original default from before intent routing existed.
+    const agentId = options.agentId ?? ANSWER_QUERY_AGENT_ID;
+    const agent = bundle.agents.find((candidate) => candidate.id === agentId);
+    if (!agent) {
+        throw new Error(`compiled bundle has no "${agentId}" agent`);
+    }
+    // Runtime settings are validated against every tier declared by the
+    // compiled bundle, but one turn executes only one selected component. Keep
+    // that complete map at the server boundary and pass this agent's projection
+    // here; `buildHybridTierBinding` intentionally rejects tiers used solely by
+    // another component.
+    const agentTierBinding = options.tierBinding === undefined ? undefined : filterTierBindingForAgent(agent, options.tierBinding);
+    const binding = options.tierBinding !== undefined
+        ? buildHybridTierBinding(agent, agentTierBinding)
+        : buildUniformTierBinding(agent, deriveAdapterSpec(options.authChoice, options.model !== undefined ? { model: options.model } : {}));
+    const registry = createDefaultProviderRegistry();
+    const capabilityRegistry = createDefaultCapabilityRegistry();
+    if (options.mcpServers !== undefined) {
+        return runAgent(bundle, agentId, options.question, {
+            binding,
+            registry,
+            capabilityRegistry,
+            mcpServers: options.mcpServers,
+            ...(options.onEvent !== undefined ? { onEvent: options.onEvent } : {}),
+        });
+    }
+    // Preflight `wren` before wiring the native tool registry around
+    // it. Without this, a missing `wren` binary stayed invisible until the
+    // tool loop actually called `query` — surfacing as an opaque,
+    // indistinguishable-from-a-normal-failure exec result rather than a clear
+    // "wren is not installed" error at the point where it's actually
+    // diagnosable.
+    await resolveWrenBinary();
+    const policy = deriveEnforcement(agent);
+    // Scoped to an artifacts dir, never the default `process.cwd()`
+    // (see `resolveArtifactsDir`'s doc comment) — independent of `projectDir`
+    // below, which alone governs the `query` tool's exec cwd.
+    const env = createLocalExecutionEnv({ rootDir: resolveArtifactsDir(options.outDir) });
+    const nativeTools = createWrenNativeToolRegistry({ env, policy, projectDir: options.userProject });
+    return runAgent(bundle, agentId, options.question, {
+        binding,
+        registry,
+        capabilityRegistry,
+        nativeTools,
+        ...(options.onEvent !== undefined ? { onEvent: options.onEvent } : {}),
+    });
+}

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

@@ -0,0 +1,19 @@
+export { DEFAULT_LOCAL_ENDPOINT, DEFAULT_LOCAL_MODEL, deriveAdapterSpec } from "./adapter-spec.js";
+export type { DeriveAdapterSpecOptions } from "./adapter-spec.js";
+export { AgentSdkCliNotFoundError, resolveAgentSdkCli } from "./agent-sdk-cli.js";
+export type { ResolvedCli } from "./agent-sdk-cli.js";
+export { buildAgentSdkManifestArgs, runAgentSdkManifest } from "./agent-sdk-manifest.js";
+export type { AgentSdkManifestCommand, BuildAgentSdkManifestArgsOptions } from "./agent-sdk-manifest.js";
+export { describeBundle } from "./describe.js";
+export type { DescribeBundleOptions } from "./describe.js";
+export { resolveArtifactContent } from "./artifact-content.js";
+export type { ArtifactContentDto, ArtifactContentUnavailableReason } from "./artifact-content.js";
+export { buildAgentSdkChatArgs, DispatchedSessionError, runDispatchedDefault } from "./dispatched.js";
+export type { AgentSdkChatCommand, BuildAgentSdkChatArgsOptions } from "./dispatched.js";
+export { buildCodexAskArgs, runCodexAskDefault } from "./codex-ask.js";
+export { CodexAskEventMapper } from "./codex-ask-events.js";
+export { resolveArtifactsDir, runInProcessDefault } from "./in-process.js";
+export { resolveDefaultEnrichIrPath, resolveDefaultProfileSource, resolveDefaultSetupIrPath } from "./profile-source.js";
+export { route } from "./route.js";
+export { buildHybridTierBinding, buildUniformTierBinding } from "./tier-binding.js";
+export type { InProcessExecutor, InProcessOptions, CodexAskExecutor, CodexAskOptions, CodexAskResult, DispatchedExecutor, DispatchedOptions, DispatchedResult, RouteOptions, RouteResult, } from "./types.js";

package/dist-server/harness/route/index.js

@@ -0,0 +1,12 @@
+export { DEFAULT_LOCAL_ENDPOINT, DEFAULT_LOCAL_MODEL, deriveAdapterSpec } from "./adapter-spec.js";
+export { AgentSdkCliNotFoundError, resolveAgentSdkCli } from "./agent-sdk-cli.js";
+export { buildAgentSdkManifestArgs, runAgentSdkManifest } from "./agent-sdk-manifest.js";
+export { describeBundle } from "./describe.js";
+export { resolveArtifactContent } from "./artifact-content.js";
+export { buildAgentSdkChatArgs, DispatchedSessionError, runDispatchedDefault } from "./dispatched.js";
+export { buildCodexAskArgs, runCodexAskDefault } from "./codex-ask.js";
+export { CodexAskEventMapper } from "./codex-ask-events.js";
+export { resolveArtifactsDir, runInProcessDefault } from "./in-process.js";
+export { resolveDefaultEnrichIrPath, resolveDefaultProfileSource, resolveDefaultSetupIrPath } from "./profile-source.js";
+export { route } from "./route.js";
+export { buildHybridTierBinding, buildUniformTierBinding } from "./tier-binding.js";

package/dist-server/harness/route/profile-source.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Resolves the v1 default profile (`profiles/genbi-default`). Callers that
+ * already have an explicit `--profile`/`profileSource` never call this.
+ * Throws (loud-fail) if this package's own profile tree is not present.
+ */
+export declare function resolveDefaultProfileSource(): string;
+/**
+ * Resolves the committed genbi-setup IR (`profiles/genbi-setup/ir.golden.json`)
+ * via the same walk as {@link resolveDefaultProfileSource}. Unlike that
+ * function, this one does NOT hard-fail when it is absent — only the setup
+ * wizard's agentic connect step needs this IR, so a bootstrap-mode BFF instance
+ * that never uses `/api/setup/connect` should still boot fine without it.
+ * Callers should surface a clear error at the point of actually dispatching a
+ * setup turn if this returns `undefined`, not at boot.
+ */
+export declare function resolveDefaultSetupIrPath(): string | undefined;
+/**
+ * Resolves the committed genbi-enrich-context IR
+ * (`profiles/genbi-enrich-context/ir.golden.json`) via the same walk as
+ * {@link resolveDefaultSetupIrPath}. This profile's `context_precondition`
+ * ("an existing pinned Wren project ... that parses and has a successful
+ * build proof") is a host runtime obligation, not something the compiled IR
+ * itself is validated against.
+ *
+ * This used to say the golden was "dispatched against whichever project is
+ * actually bound at runtime via --project". That was the bug: a golden is the
+ * profile compiled once against its own fixture binding, so dispatching it
+ * described the example project's schema to an agent working on someone
+ * else's. An enrichment draft now compiles against the bound project (see the
+ * runner's `profileSource`), and this path remains only as the prebuilt
+ * fallback for a caller that has no profile source. Does NOT hard-fail when it
+ * is absent — only an enrichment draft call needs this; a BFF instance that
+ * never starts an enrichment run should still boot fine without it. Callers
+ * should surface a clear error at the point of actually dispatching a draft
+ * turn if this returns `undefined`, not at boot.
+ */
+export declare function resolveDefaultEnrichIrPath(): string | undefined;

package/dist-server/harness/route/profile-source.js

@@ -0,0 +1,76 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * The GenBI profiles (`genbi-default`, `genbi-setup`, `genbi-enrich-context`,
+ * `genbi-monitor`) live in this package's own `profiles/` tree, alongside their
+ * committed `ir.golden.json`. The `warble` binary and its dispatchers still
+ * come from a sibling Warble checkout (see `harness/compile/resolve-binary.ts`);
+ * only the behavior source is ours.
+ *
+ * Resolution walks up from this module's own location looking for an ancestor
+ * that contains `profiles/<id>`, so it works both from the TypeScript sources
+ * (`harness/route/`) and from the built bundle (`dist-server/harness/route/`),
+ * whether the caller runs from the main checkout or a nested git worktree.
+ */
+function resolveProfileEntry(...segments) {
+    let dir = path.dirname(fileURLToPath(import.meta.url));
+    const maxDepth = 10;
+    for (let i = 0; i < maxDepth; i += 1) {
+        const candidate = path.join(dir, "profiles", ...segments);
+        if (existsSync(candidate))
+            return candidate;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break; // reached filesystem root
+        dir = parent;
+    }
+    return undefined;
+}
+/**
+ * Resolves the v1 default profile (`profiles/genbi-default`). Callers that
+ * already have an explicit `--profile`/`profileSource` never call this.
+ * Throws (loud-fail) if this package's own profile tree is not present.
+ */
+export function resolveDefaultProfileSource() {
+    const resolved = resolveProfileEntry("genbi-default");
+    if (resolved !== undefined)
+        return resolved;
+    throw new Error('no default profile source found (searched ancestors of this module for "<ancestor>/profiles/' +
+        'genbi-default"); pass --profile explicitly');
+}
+/**
+ * Resolves the committed genbi-setup IR (`profiles/genbi-setup/ir.golden.json`)
+ * via the same walk as {@link resolveDefaultProfileSource}. Unlike that
+ * function, this one does NOT hard-fail when it is absent — only the setup
+ * wizard's agentic connect step needs this IR, so a bootstrap-mode BFF instance
+ * that never uses `/api/setup/connect` should still boot fine without it.
+ * Callers should surface a clear error at the point of actually dispatching a
+ * setup turn if this returns `undefined`, not at boot.
+ */
+export function resolveDefaultSetupIrPath() {
+    return resolveProfileEntry("genbi-setup", "ir.golden.json");
+}
+/**
+ * Resolves the committed genbi-enrich-context IR
+ * (`profiles/genbi-enrich-context/ir.golden.json`) via the same walk as
+ * {@link resolveDefaultSetupIrPath}. This profile's `context_precondition`
+ * ("an existing pinned Wren project ... that parses and has a successful
+ * build proof") is a host runtime obligation, not something the compiled IR
+ * itself is validated against.
+ *
+ * This used to say the golden was "dispatched against whichever project is
+ * actually bound at runtime via --project". That was the bug: a golden is the
+ * profile compiled once against its own fixture binding, so dispatching it
+ * described the example project's schema to an agent working on someone
+ * else's. An enrichment draft now compiles against the bound project (see the
+ * runner's `profileSource`), and this path remains only as the prebuilt
+ * fallback for a caller that has no profile source. Does NOT hard-fail when it
+ * is absent — only an enrichment draft call needs this; a BFF instance that
+ * never starts an enrichment run should still boot fine without it. Callers
+ * should surface a clear error at the point of actually dispatching a draft
+ * turn if this returns `undefined`, not at boot.
+ */
+export function resolveDefaultEnrichIrPath() {
+    return resolveProfileEntry("genbi-enrich-context", "ir.golden.json");
+}

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

@@ -0,0 +1,33 @@
+import type { RouteOptions, RouteResult } from "./types.js";
+/**
+ * The single seam mapping a resolved `AuthChoice` to a back-end:
+ * Claude subscription -> dispatched (warble-agent-sdk), Codex subscription ->
+ * codex:local, everything else
+ * (`api-key`/`local`/`gateway`) -> in-process (compile to a vercel bundle and run
+ * In-process via `runAgent`). `inProcess`/`dispatched` are injectable so callers and
+ * tests can stub either back-end without touching the other or invoking any
+ * real compile/dispatch — this is the hook point later tickets (compliance
+ * gating, hybrid dispatch) attach to without needing to touch the CLI or
+ * either mode's internals.
+ *
+ * The compliance gate (`enforceCompliance`) runs first, before either
+ * back-end is invoked: a `subscription` `AuthChoice` used for a `"hosted"`
+ * deployment throws `ComplianceError` here, so no caller of `route()` can
+ * reach dispatched for a use the ToS doesn't allow, regardless of whether it
+ * came through the CLI's own (separate, warning-printing) check. The
+ * resulting `warnings` (e.g. `SUBSCRIPTION_TOS_WARNING`) are attached to the
+ * returned `RouteResult` so programmatic callers of `route()` see them too
+ * — the CLI additionally prints them to stderr from its own, separately
+ * timed `enforceCompliance` call (before `route()` is even invoked, so they
+ * print before the back-end runs rather than after `route()` resolves), but
+ * that's an independent concern from surfacing them on the result value
+ * here. `runDispatchedDefault` also re-runs this same gate as a belt for direct
+ * (non-`route()`) callers — see its doc comment.
+ *
+ * The per-tier "hybrid" override: `options.tierBinding` (in-process's per-tier override) and
+ * `options.modelsConfig` (dispatched's `--models-config` passthrough) are each
+ * meaningful for exactly one back-end. Rather than silently ignore one when
+ * the `authChoice` picks the other back-end, `route()` loud-fails — the
+ * same "no silent misrouting" posture as the existing dispatched provider guard.
+ */
+export declare function route(options: RouteOptions): Promise<RouteResult>;

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

@@ -0,0 +1,114 @@
+import { enforceCompliance } from "../compliance/index.js";
+import { runInProcessDefault } from "./in-process.js";
+import { runDispatchedDefault } from "./dispatched.js";
+import { runCodexAskDefault } from "./codex-ask.js";
+/**
+ * The single seam mapping a resolved `AuthChoice` to a back-end:
+ * Claude subscription -> dispatched (warble-agent-sdk), Codex subscription ->
+ * codex:local, everything else
+ * (`api-key`/`local`/`gateway`) -> in-process (compile to a vercel bundle and run
+ * In-process via `runAgent`). `inProcess`/`dispatched` are injectable so callers and
+ * tests can stub either back-end without touching the other or invoking any
+ * real compile/dispatch — this is the hook point later tickets (compliance
+ * gating, hybrid dispatch) attach to without needing to touch the CLI or
+ * either mode's internals.
+ *
+ * The compliance gate (`enforceCompliance`) runs first, before either
+ * back-end is invoked: a `subscription` `AuthChoice` used for a `"hosted"`
+ * deployment throws `ComplianceError` here, so no caller of `route()` can
+ * reach dispatched for a use the ToS doesn't allow, regardless of whether it
+ * came through the CLI's own (separate, warning-printing) check. The
+ * resulting `warnings` (e.g. `SUBSCRIPTION_TOS_WARNING`) are attached to the
+ * returned `RouteResult` so programmatic callers of `route()` see them too
+ * — the CLI additionally prints them to stderr from its own, separately
+ * timed `enforceCompliance` call (before `route()` is even invoked, so they
+ * print before the back-end runs rather than after `route()` resolves), but
+ * that's an independent concern from surfacing them on the result value
+ * here. `runDispatchedDefault` also re-runs this same gate as a belt for direct
+ * (non-`route()`) callers — see its doc comment.
+ *
+ * The per-tier "hybrid" override: `options.tierBinding` (in-process's per-tier override) and
+ * `options.modelsConfig` (dispatched's `--models-config` passthrough) are each
+ * meaningful for exactly one back-end. Rather than silently ignore one when
+ * the `authChoice` picks the other back-end, `route()` loud-fails — the
+ * same "no silent misrouting" posture as the existing dispatched provider guard.
+ */
+export async function route(options) {
+    const runInProcess = options.inProcess ?? runInProcessDefault;
+    const runDispatched = options.dispatched ?? runDispatchedDefault;
+    const runCodexAsk = options.codexAsk ?? runCodexAskDefault;
+    const { authChoice } = options;
+    const deployment = options.deployment ?? "personal";
+    const { warnings } = enforceCompliance(authChoice, { deployment });
+    if (authChoice.mode === "subscription") {
+        if (options.tierBinding !== undefined) {
+            throw new Error("tierBinding (hybrid in-process per-tier routing) has no effect under a subscription " +
+                "authChoice — dispatched has no adapter/tier binding of its own; use modelsConfig instead " +
+                "(warble-agent-sdk's own --models-config per-step routing)");
+        }
+        if (authChoice.provider === "codex") {
+            if (options.modelsConfig !== undefined) {
+                throw new Error("modelsConfig applies only to the Claude subscription dispatcher, not codex:local Ask");
+            }
+            const result = await runCodexAsk({
+                authChoice: { ...authChoice, provider: "codex" },
+                profileSource: options.profileSource,
+                userProject: options.userProject,
+                question: options.question,
+                deployment,
+                ...(options.warbleBin !== undefined ? { warbleBin: options.warbleBin } : {}),
+                ...(options.workDir !== undefined ? { workDir: options.workDir } : {}),
+                ...(options.onEvent !== undefined ? { onEvent: options.onEvent } : {}),
+                ...(options.agentId !== undefined ? { agentId: options.agentId } : {}),
+                ...(options.codexModels !== undefined ? { codexModels: options.codexModels } : {}),
+                ...(options.codexHome !== undefined ? { codexHome: options.codexHome } : {}),
+                ...(options.codexLocalBin !== undefined ? { codexLocalBin: options.codexLocalBin } : {}),
+                ...(options.codexLocalCli !== undefined ? { codexLocalCli: options.codexLocalCli } : {}),
+                ...(options.codexBin !== undefined ? { codexBin: options.codexBin } : {}),
+                ...(options.codexMcpServer !== undefined ? { mcpServer: options.codexMcpServer } : {}),
+                ...(options.chatTimeoutMs !== undefined ? { timeoutMs: options.chatTimeoutMs } : {}),
+                ...(options.signal !== undefined ? { signal: options.signal } : {}),
+            });
+            return { backend: "codex-local", warnings, ...result };
+        }
+        const result = await runDispatched({
+            authChoice,
+            profileSource: options.profileSource,
+            userProject: options.userProject,
+            question: options.question,
+            deployment,
+            ...(options.warbleBin !== undefined ? { warbleBin: options.warbleBin } : {}),
+            ...(options.agentSdkBin !== undefined ? { agentSdkBin: options.agentSdkBin } : {}),
+            ...(options.outDir !== undefined ? { outDir: options.outDir } : {}),
+            ...(options.workDir !== undefined ? { workDir: options.workDir } : {}),
+            ...(options.modelsConfig !== undefined ? { modelsConfig: options.modelsConfig } : {}),
+            ...(options.onEvent !== undefined ? { onEvent: options.onEvent } : {}),
+            ...(options.agentId !== undefined ? { agentId: options.agentId } : {}),
+            ...(options.chatTimeoutMs !== undefined ? { chatTimeoutMs: options.chatTimeoutMs } : {}),
+            ...(options.signal !== undefined ? { signal: options.signal } : {}),
+        });
+        return { backend: "agent-sdk", warnings, ...result };
+    }
+    if (options.modelsConfig !== undefined) {
+        throw new Error(`modelsConfig (hybrid dispatched --models-config passthrough) has no effect under a ` +
+            `"${authChoice.mode}" authChoice — that flag only reaches warble-agent-sdk's chat ` +
+            "invocation, which in-process never shells; use tierBinding instead (this harness's own " +
+            "per-tier adapter map)");
+    }
+    const result = await runInProcess({
+        authChoice,
+        profileSource: options.profileSource,
+        userProject: options.userProject,
+        question: options.question,
+        ...(options.model !== undefined ? { model: options.model } : {}),
+        ...(options.warbleBin !== undefined ? { warbleBin: options.warbleBin } : {}),
+        ...(options.workDir !== undefined ? { workDir: options.workDir } : {}),
+        ...(options.outDir !== undefined ? { outDir: options.outDir } : {}),
+        ...(options.bundle !== undefined ? { bundle: options.bundle } : {}),
+        ...(options.mcpServers !== undefined ? { mcpServers: options.mcpServers } : {}),
+        ...(options.tierBinding !== undefined ? { tierBinding: options.tierBinding } : {}),
+        ...(options.onEvent !== undefined ? { onEvent: options.onEvent } : {}),
+        ...(options.agentId !== undefined ? { agentId: options.agentId } : {}),
+    });
+    return { backend: "agent", warnings, ...result };
+}

package/dist-server/harness/route/tier-binding.d.ts

@@ -0,0 +1,36 @@
+import type { Agent } from "../bundle/schema.js";
+import type { AdapterSpec, TierBinding } from "../providers/index.js";
+/**
+ * Builds a `TierBinding` mapping every distinct `tier` name used by `agent`'s
+ * steps to the same `adapterSpec` — one model realizing every tier. Tier
+ * names are open strings owned by individual steps, not
+ * declared centrally on the agent, so a single-adapter run must enumerate
+ * them from the bundle itself rather than assuming fixed names like
+ * `cheap`/`strong`. This also covers the render envelope stage automatically:
+ * `renderEnvelope`'s default tier is always the tier of the agent's last
+ * `independent` step, which is necessarily one of the tiers already
+ * collected here.
+ */
+export declare function buildUniformTierBinding(agent: Agent, adapterSpec: AdapterSpec): TierBinding;
+/**
+ * Builds a "hybrid" `TierBinding` — a NON-uniform map from `agent`'s
+ * tiers to independently-chosen `AdapterSpec`s (e.g. `cheap` on a free local
+ * model, `strong` on a paid cloud one). Unlike `buildUniformTierBinding`
+ * (which derives its single map from one `AdapterSpec`, so it can never be
+ * short a tier), this takes a caller-supplied per-tier map and must validate
+ * it against the agent's actual tiers before trusting it:
+ *
+ * - every tier `agent`'s steps use must have an entry in `tiers` — a step
+ *   whose tier resolves to nothing would otherwise surface late, deep inside
+ *   `resolveTierModel`, as a bare `UnknownTierError` with no hint that the
+ *   hybrid map (not the agent) is what's incomplete.
+ * - every entry in `tiers` must name a tier `agent` actually uses — an entry
+ *   for a typo'd or stale tier name would otherwise silently do nothing
+ *   (the intended tier stays unbound) rather than fail at the point the typo
+ *   was made.
+ *
+ * Both failure modes loud-fail here, before `runAgent` starts, naming the
+ * agent and every offending tier — mirroring this module's/`adapter-spec.ts`'s
+ * existing loud-fail style (e.g. `gateway` mode's missing `baseURL`/`model`).
+ */
+export declare function buildHybridTierBinding(agent: Agent, tiers: Readonly<Record<string, AdapterSpec>>): TierBinding;

package/dist-server/harness/route/tier-binding.js

@@ -0,0 +1,63 @@
+/**
+ * Builds a `TierBinding` mapping every distinct `tier` name used by `agent`'s
+ * steps to the same `adapterSpec` — one model realizing every tier. Tier
+ * names are open strings owned by individual steps, not
+ * declared centrally on the agent, so a single-adapter run must enumerate
+ * them from the bundle itself rather than assuming fixed names like
+ * `cheap`/`strong`. This also covers the render envelope stage automatically:
+ * `renderEnvelope`'s default tier is always the tier of the agent's last
+ * `independent` step, which is necessarily one of the tiers already
+ * collected here.
+ */
+export function buildUniformTierBinding(agent, adapterSpec) {
+    const tiers = {};
+    for (const step of agent.steps) {
+        tiers[step.tier] = adapterSpec;
+    }
+    return { tiers };
+}
+/** The distinct `tier` names `agent`'s steps use, in first-seen order. */
+function agentTierNames(agent) {
+    const seen = new Set();
+    for (const step of agent.steps) {
+        seen.add(step.tier);
+    }
+    return [...seen];
+}
+/**
+ * Builds a "hybrid" `TierBinding` — a NON-uniform map from `agent`'s
+ * tiers to independently-chosen `AdapterSpec`s (e.g. `cheap` on a free local
+ * model, `strong` on a paid cloud one). Unlike `buildUniformTierBinding`
+ * (which derives its single map from one `AdapterSpec`, so it can never be
+ * short a tier), this takes a caller-supplied per-tier map and must validate
+ * it against the agent's actual tiers before trusting it:
+ *
+ * - every tier `agent`'s steps use must have an entry in `tiers` — a step
+ *   whose tier resolves to nothing would otherwise surface late, deep inside
+ *   `resolveTierModel`, as a bare `UnknownTierError` with no hint that the
+ *   hybrid map (not the agent) is what's incomplete.
+ * - every entry in `tiers` must name a tier `agent` actually uses — an entry
+ *   for a typo'd or stale tier name would otherwise silently do nothing
+ *   (the intended tier stays unbound) rather than fail at the point the typo
+ *   was made.
+ *
+ * Both failure modes loud-fail here, before `runAgent` starts, naming the
+ * agent and every offending tier — mirroring this module's/`adapter-spec.ts`'s
+ * existing loud-fail style (e.g. `gateway` mode's missing `baseURL`/`model`).
+ */
+export function buildHybridTierBinding(agent, tiers) {
+    const agentTiers = agentTierNames(agent);
+    const agentTierSet = new Set(agentTiers);
+    const boundTierSet = new Set(Object.keys(tiers));
+    const missing = agentTiers.filter((tier) => !boundTierSet.has(tier));
+    if (missing.length > 0) {
+        throw new Error(`hybrid tier binding is missing an adapter for tier(s): ${missing.join(", ")} — ` +
+            `agent "${agent.id}" uses tier(s): ${agentTiers.join(", ")}`);
+    }
+    const unknown = [...boundTierSet].filter((tier) => !agentTierSet.has(tier));
+    if (unknown.length > 0) {
+        throw new Error(`hybrid tier binding names unknown tier(s) not used by agent "${agent.id}": ${unknown.join(", ")} — ` +
+            `known tier(s): ${agentTiers.join(", ")}`);
+    }
+    return { tiers };
+}