@cohortapp/agent-sdk 2.3.0

package/lib/model-router.mjs

@@ -0,0 +1,677 @@
+/**
+ * Maestro — Model router
+ *
+ * Routes each `claude --print` spawn (and any other Anthropic-Messages
+ * caller) to the cheapest backend that satisfies the request's declared
+ * capability needs. Backends are configured via `config/model-routing.yaml`
+ * in the agent repo; if no config is present, the router is inert and the
+ * existing Claude-CLI-on-Max-subscription behaviour is preserved verbatim.
+ *
+ * Why this exists:
+ *   - Anthropic Sonnet 4.6 / Opus 4.7 are still the quality ceiling for
+ *     agent loops, but background work (classification, log triage,
+ *     scheduled summaries) does NOT need them.
+ *   - Moonshot exposes a native `/anthropic` Messages endpoint, so
+ *     Kimi K2.6 is a literal drop-in for Claude Code — no router,
+ *     no translation, no tool-use degradation.
+ *   - Qwen3-Coder via OpenRouter is one router-hop away and significantly
+ *     cheaper; usable for agents that don't need extended-thinking or
+ *     parallel tool calls.
+ *
+ * What this is NOT:
+ *   - Not a wire-format translator. We rely on the backend speaking
+ *     Anthropic Messages directly (Moonshot, Anthropic, NIM) OR a thin
+ *     OpenAI-compat shim that Claude Code's existing
+ *     ANTHROPIC_BASE_URL/AUTH_TOKEN/MODEL knobs already handle.
+ *   - Not a model wrapper. We only emit env vars for the spawned child;
+ *     the existing `claude` binary does the actual HTTP I/O.
+ *
+ * Public API:
+ *   loadRoutingConfig(agentRoot)        → parsed YAML or null if absent
+ *   resolveBackend(request, opts)       → { name, envForSpawn, model, … }
+ *   describeBackend(name, opts)         → human-readable backend summary
+ *   listBackends(opts)                  → array of backend names
+ *   estimateCost(request, opts)         → rough $ for a given req
+ *
+ * Caller integration: in dispatcher.mjs / responder.mjs / classifier.mjs,
+ * compute a small `AgentRequest` based on the item being processed and
+ * merge the returned `envForSpawn` into the child env. Returning a null
+ * backend (no config) means "use whatever you used before".
+ *
+ * Kill switch:
+ *   - MAESTRO_ROUTER_FORCE_ANTHROPIC=1 (or "true") short-circuits ALL
+ *     resolution to the stock Anthropic-CLI behaviour — the same path as
+ *     when no routing config is present (resolveBackend → null, callers
+ *     fall through to keychain-OAuth `claude --print`). This is the operator
+ *     escape hatch when a routed backend misbehaves fleet-wide; it overrides
+ *     any policy without editing config.
+ *
+ * Spec / risk notes (May 2026):
+ *   - ANTHROPIC_API_KEY MUST be set to the empty string when routing to a
+ *     non-Anthropic base URL; merely unsetting it makes Claude Code fall
+ *     back to its keychain OAuth and authenticate against api.anthropic.com.
+ *   - CLAUDE_CODE_ATTRIBUTION_HEADER=0 strips the system-prompt attribution
+ *     block so a third-party gateway's prompt-cache key isn't poisoned.
+ *   - Some OpenRouter providers return empty tool_use.input for Qwen3-Coder
+ *     (musistudio/claude-code-router#409). We classify those as
+ *     `degraded_tool_use: true` and route agents needing reliable tool use
+ *     away from them.
+ *   - A backend whose required `auth_env` is unset/empty is SKIPPED at
+ *     resolve time (treated as unavailable, chain continues) so we never
+ *     spawn a non-Anthropic backend with an empty credential.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+// v2 surface — the resolveChain "brain" + strict config validation. Imported as
+// a sibling module so the v1 API above stays byte-compatible; resolveChain is
+// purely additive (SPEC §3). See lib/model-router/resolve.mjs.
+import { resolveChain, validateRoutingConfig } from "./model-router/resolve.mjs";
+// Execution lane (additive, SPEC §6.2/§6.3): the session spawn primitive,
+// the governed cheap one-shot, and the cheap-model tool-call repair. Imported as
+// sibling modules so the v1 + resolveChain surfaces stay byte-compatible.
+import { spawnRouted } from "./model-router/spawn.mjs";
+import { llmTask } from "./model-router/llm-task.mjs";
+import { repairToolCalls } from "./model-router/repair.mjs";
+
+// We accept either YAML or JSON. js-yaml is optional; the loader gracefully
+// degrades to JSON-only if it isn't installed.
+let yamlParse = null;
+try {
+  const y = await import("js-yaml");
+  yamlParse = (text) => y.load(text);
+} catch {
+  yamlParse = null;
+}
+
+// ---------------------------------------------------------------------------
+// Defaults — used when no config exists OR when a config has gaps.
+// Anthropic-only fallback so existing agents keep working unchanged.
+// ---------------------------------------------------------------------------
+
+const ANTHROPIC_DEFAULT = Object.freeze({
+  transport: "anthropic-cli", // special: do nothing (current behaviour)
+  base_url: "https://api.anthropic.com",
+  auth_env: null, // null → use the keychain-resident OAuth token
+  capabilities: [
+    "thinking",
+    "vision",
+    "prompt_cache_1h",
+    "tool_use",
+    "parallel_tools",
+    "long_context_1m",
+  ],
+  pricing: { input_per_m: 3.0, output_per_m: 15.0 }, // Sonnet 4.6 ballpark
+  models: {
+    classifier: "claude-haiku-4-5-20251001",
+    default: "claude-sonnet-4-6",
+    premium: "claude-opus-4-7",
+    fast: "claude-haiku-4-5-20251001",
+  },
+});
+
+const DEFAULT_CONFIG = Object.freeze({
+  backends: { anthropic: ANTHROPIC_DEFAULT },
+  routing_policy: [{ default: true, backend: "anthropic" }],
+  fallback_to_anthropic: true,
+  strip_attribution_header: true,
+});
+
+/**
+ * The Anthropic-only default routing config (audit L21).
+ *
+ * Returns a normalised, deep-cloned copy of {@link DEFAULT_CONFIG} so callers
+ * that explicitly want "the built-in Anthropic-CLI default" — rather than the
+ * `null` that `loadRoutingConfig` returns when no config file is present — have
+ * a concrete config object to pass into `resolveBackend({}, { config })`.
+ *
+ * This is intentionally an OPT-IN accessor. The default search path
+ * (`loadRoutingConfig` returning `null` when no file exists) is preserved
+ * verbatim so existing callers keep falling through to "current Claude CLI
+ * behaviour"; nothing about that contract changes.
+ *
+ * @returns {object} A fresh, normalised default config (safe to mutate).
+ */
+export function defaultRoutingConfig() {
+  // Normalise through the same path as a file-loaded config so the returned
+  // shape (clones of ANTHROPIC_DEFAULT, derived booleans, etc.) is identical.
+  return normaliseConfig(
+    {
+      backends: { anthropic: cloneBackend(ANTHROPIC_DEFAULT) },
+      routing_policy: [{ default: true, backend: "anthropic" }],
+      fallback_to_anthropic: DEFAULT_CONFIG.fallback_to_anthropic,
+      strip_attribution_header: DEFAULT_CONFIG.strip_attribution_header,
+    },
+    { sourcePath: "<default>" }
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Config loader
+// ---------------------------------------------------------------------------
+
+export const CONFIG_RELATIVE_PATH = "config/model-routing.yaml";
+
+/**
+ * Resolve the active routing config. Search order:
+ *   1. opts.configPath (explicit)
+ *   2. $MAESTRO_ROUTING_CONFIG env var
+ *   3. <agentRoot>/config/model-routing.yaml
+ *   4. <agentRoot>/config/model-routing.json
+ *
+ * Returns null when no config exists so callers can fall through to
+ * "current behaviour". Throws on parse error so misconfiguration is loud.
+ *
+ * @param {string} [agentRoot]
+ * @param {{ configPath?: string, useDefault?: boolean }} [opts]
+ *   When `useDefault` is true, returns {@link defaultRoutingConfig} instead of
+ *   null if no config file is found (opt-in; default false preserves the
+ *   null-when-absent contract).
+ */
+export function loadRoutingConfig(agentRoot, opts = {}) {
+  const root = resolve(
+    agentRoot ||
+      process.env.AGENT_ROOT ||
+      process.env.AGENT_DIR ||
+      process.cwd()
+  );
+  const candidates = [
+    opts.configPath,
+    process.env.MAESTRO_ROUTING_CONFIG,
+    join(root, CONFIG_RELATIVE_PATH),
+    join(root, "config/model-routing.json"),
+  ].filter(Boolean);
+
+  for (const path of candidates) {
+    if (!existsSync(path)) continue;
+    const raw = readFileSync(path, "utf-8");
+    const parsed = path.endsWith(".json")
+      ? JSON.parse(raw)
+      : parseYaml(raw, path);
+    return normaliseConfig(parsed, { sourcePath: path });
+  }
+  // Opt-in: callers that want the built-in Anthropic default rather than null.
+  if (opts.useDefault) return defaultRoutingConfig();
+  return null;
+}
+
+function parseYaml(text, sourcePath) {
+  if (!yamlParse) {
+    throw new Error(
+      `[model-router] ${sourcePath} is YAML but js-yaml is not installed. ` +
+        "Install it (`npm i js-yaml`) or convert the config to JSON."
+    );
+  }
+  try {
+    return yamlParse(text);
+  } catch (err) {
+    throw new Error(`[model-router] failed to parse ${sourcePath}: ${err.message}`);
+  }
+}
+
+function normaliseConfig(raw, { sourcePath } = {}) {
+  if (!raw || typeof raw !== "object") {
+    throw new Error(`[model-router] config at ${sourcePath} is empty or not an object`);
+  }
+  // ── Policy v2 ─────────────────────────────────────────────────────────────
+  // A `schema_version: 2` config drives the new resolveChain brain (catalog
+  // rows + chains + task/data classes + lanes), NOT the v1 backend resolver.
+  // We pass it through largely verbatim (resolveChain validates it strictly via
+  // validateRoutingConfig); we only fill in the few defaults the brain reads.
+  if (raw.schema_version === 2) {
+    return normaliseConfigV2(raw, sourcePath);
+  }
+  const backends = { ...(raw.backends || {}) };
+  if (!Object.keys(backends).length) {
+    throw new Error(`[model-router] config at ${sourcePath} declares no backends`);
+  }
+  // Ensure an anthropic backend always exists as the safety net unless the
+  // operator has explicitly opted out via fallback_to_anthropic: false.
+  if (!backends.anthropic && raw.fallback_to_anthropic !== false) {
+    backends.anthropic = cloneBackend(ANTHROPIC_DEFAULT);
+  }
+
+  // Defensive normalisation of each backend.
+  for (const [name, b] of Object.entries(backends)) {
+    if (!b.transport) {
+      throw new Error(`[model-router] backend "${name}" missing transport`);
+    }
+    b.capabilities = Array.isArray(b.capabilities) ? b.capabilities : [];
+    b.models = b.models || {};
+    b.pricing = b.pricing || {};
+  }
+
+  const policy = Array.isArray(raw.routing_policy) && raw.routing_policy.length
+    ? raw.routing_policy
+    : [{ default: true, backend: Object.keys(backends)[0] }];
+
+  return {
+    backends,
+    routing_policy: policy,
+    fallback_to_anthropic: raw.fallback_to_anthropic !== false,
+    strip_attribution_header: raw.strip_attribution_header !== false,
+    disable_experimental_betas: raw.disable_experimental_betas !== false,
+    source_path: sourcePath,
+  };
+}
+
+/**
+ * Normalise a policy-v2 config. The v2 brain (resolveChain) consults the catalog
+ * for model rows; the config only carries policy: aliases, data-class backends,
+ * the ordered routing_policy chain rules, the budget ladder, and defaults. We
+ * keep the raw shape and only stamp defaults the brain relies on so a sparse
+ * config still resolves. Strict validation is the job of validateRoutingConfig.
+ */
+function normaliseConfigV2(raw, sourcePath) {
+  const defaults = raw.defaults && typeof raw.defaults === "object" ? { ...raw.defaults } : {};
+  if (defaults.needs_tool_use_for_sessions === undefined) defaults.needs_tool_use_for_sessions = true;
+  if (defaults.data_class === undefined) defaults.data_class = "sensitive";
+  if (defaults.cache_ttl === undefined) defaults.cache_ttl = "1h";
+  return {
+    schema_version: 2,
+    aliases: raw.aliases && typeof raw.aliases === "object" ? { ...raw.aliases } : {},
+    defaults,
+    backends: raw.backends && typeof raw.backends === "object" ? { ...raw.backends } : {},
+    routing_policy: Array.isArray(raw.routing_policy) ? raw.routing_policy : [],
+    budget_ladder: raw.budget_ladder && typeof raw.budget_ladder === "object" ? { ...raw.budget_ladder } : {},
+    fallback_to_anthropic: raw.fallback_to_anthropic !== false,
+    strip_attribution_header: raw.strip_attribution_header !== false,
+    disable_experimental_betas: raw.disable_experimental_betas !== false,
+    source_path: sourcePath,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Resolver
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {Object} AgentRequest
+ * @property {string}  [agent_role]         Maestro action role tag, e.g. "classifier", "responder", "ceo_pre_pass"
+ * @property {boolean} [needs_thinking]     Extended-thinking required
+ * @property {boolean} [needs_vision]       Vision input required
+ * @property {boolean} [needs_long_context] >200k token context window required
+ * @property {boolean} [needs_tool_use]     Tool/function calling required
+ * @property {boolean} [needs_parallel_tools] Multi-tool-per-turn required
+ * @property {string}  [tier]               "classifier" | "default" | "premium" | "fast"
+ * @property {string}  [model_hint]         "haiku" | "sonnet" | "opus" — coarse legacy tier
+ * @property {number}  [token_estimate]     Approximate input token count
+ * @property {string}  [source]             "inbox" | "backlog" | "cadence" | "voice" | etc
+ * @property {string}  [priority]           "critical" | "high" | "normal"
+ */
+
+/**
+ * Resolve a backend for the given request. Returns null when no config is
+ * loaded so callers can fall through to "use current Claude CLI behaviour".
+ *
+ * @param {AgentRequest} request
+ * @param {{ config?: object, agentRoot?: string, env?: object }} opts
+ * @returns {null | ResolvedBackend}
+ */
+export function resolveBackend(request = {}, opts = {}) {
+  const env = opts.env || process.env;
+  // Kill switch: force stock Anthropic-CLI behaviour regardless of policy.
+  // Returning null is the same fall-through path callers take when no config
+  // is present, so this is a true escape hatch — no env injection, no routing.
+  if (forceAnthropic(env)) return null;
+
+  const config = opts.config || loadRoutingConfig(opts.agentRoot);
+  if (!config) return null;
+
+  const tried = [];
+  const chosen = pickPolicyRule(config.routing_policy, request);
+  const backendOrder = [chosen.backend].concat(
+    Array.isArray(chosen.fallback) ? chosen.fallback : []
+  );
+
+  for (const backendName of backendOrder) {
+    const backend = config.backends[backendName];
+    if (!backend) {
+      tried.push({ backend: backendName, ok: false, reason: "unknown_backend" });
+      continue;
+    }
+    const supports = backendSupports(backend, request);
+    if (!supports.ok) {
+      tried.push({ backend: backendName, ok: false, reason: supports.reason });
+      continue;
+    }
+    // A backend with a configured-but-absent credential is unavailable, not a
+    // candidate to spawn with an empty token (which would silently fail auth
+    // at runtime, burn retries, and poison the breaker). Skip and continue.
+    if (!hasAuth(backend, env)) {
+      tried.push({ backend: backendName, ok: false, reason: "missing_auth_env" });
+      continue;
+    }
+    return buildResolved({
+      name: backendName,
+      backend,
+      request,
+      config,
+      ruleMeta: chosen,
+      env,
+      tried,
+    });
+  }
+
+  // Safety net: anthropic-cli needs no auth_env (keychain OAuth), so the
+  // hasAuth gate above never excludes it here.
+  if (config.fallback_to_anthropic && config.backends.anthropic) {
+    return buildResolved({
+      name: "anthropic",
+      backend: config.backends.anthropic,
+      request,
+      config,
+      ruleMeta: { backend: "anthropic", fallback_reason: "no_compatible_backend" },
+      env,
+      tried,
+    });
+  }
+
+  // No fallback declared and nothing satisfied the request.
+  return null;
+}
+
+/**
+ * @typedef {Object} ResolvedBackend
+ * @property {string}                 name           Backend key
+ * @property {string}                 transport      "anthropic-cli" | "anthropic-native" | "openai-compat"
+ * @property {string}                 model          Concrete model string for ANTHROPIC_MODEL
+ * @property {string}                 fastModel      Concrete model for ANTHROPIC_SMALL_FAST_MODEL
+ * @property {Object<string,string>}  envForSpawn    Env vars to merge into the child env
+ * @property {Array<object>}          tried          Diagnostic record of attempts
+ * @property {object}                 capabilities   Capability flags actually granted
+ * @property {object}                 pricing        Pricing info for cost tracking
+ * @property {string}                 [rule]         Matched policy rule (debug)
+ */
+
+function buildResolved({ name, backend, request, config, ruleMeta, env, tried }) {
+  const tier = request.tier || mapHintToTier(request.model_hint) || "default";
+  const model = backend.models[tier] || backend.models.default;
+  const fastModel = backend.models.fast || backend.models.classifier || model;
+
+  const envForSpawn = {};
+
+  if (backend.transport === "anthropic-cli") {
+    // Special case: preserve current `claude --print` behaviour exactly.
+    // We don't touch ANTHROPIC_BASE_URL/AUTH_TOKEN/API_KEY; Claude Code
+    // will use its keychain-resident OAuth token (Max subscription).
+    // We DO honour the request's tier via --model (caller passes it on
+    // the CLI), but we don't need to inject anything into the env.
+  } else {
+    // For any non-Anthropic backend, we must:
+    //   1. Point Claude Code at the new base URL
+    //   2. Provide the auth token
+    //   3. Set ANTHROPIC_API_KEY to the empty string (NOT unset) so
+    //      Claude Code skips its OAuth-with-Anthropic flow.
+    //   4. Optionally strip the attribution header so the backend's
+    //      prompt cache isn't poisoned.
+    envForSpawn.ANTHROPIC_BASE_URL = backend.base_url;
+    if (backend.auth_env) {
+      const token = env[backend.auth_env] || "";
+      envForSpawn.ANTHROPIC_AUTH_TOKEN = token;
+    }
+    envForSpawn.ANTHROPIC_API_KEY = "";
+    if (model) envForSpawn.ANTHROPIC_MODEL = model;
+    if (fastModel) envForSpawn.ANTHROPIC_SMALL_FAST_MODEL = fastModel;
+    if (config.strip_attribution_header) {
+      envForSpawn.CLAUDE_CODE_ATTRIBUTION_HEADER = "0";
+    }
+    if (config.disable_experimental_betas) {
+      envForSpawn.CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS = "1";
+    }
+  }
+
+  return {
+    name,
+    transport: backend.transport,
+    model,
+    fastModel,
+    envForSpawn,
+    tried,
+    capabilities: indexCapabilities(backend.capabilities),
+    pricing: backend.pricing || {},
+    rule: ruleMeta?.match ? JSON.stringify(ruleMeta.match) : "default",
+    fallback_reason: ruleMeta?.fallback_reason || null,
+    config_source: config.source_path || null,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Policy + capability matching
+// ---------------------------------------------------------------------------
+
+function pickPolicyRule(rules, request) {
+  // Rules are evaluated top-to-bottom; first match wins. A rule with
+  // `default: true` always matches and acts as the terminal fallback.
+  for (const rule of rules) {
+    if (rule.default) return rule;
+    if (matchesRule(rule.match || {}, request)) return rule;
+  }
+  // No rule matched — synthesize a default pointing to the first backend.
+  return { default: true, backend: rules[0]?.backend, synthesized: true };
+}
+
+function matchesRule(match, req) {
+  for (const [key, expected] of Object.entries(match)) {
+    if (key === "token_estimate_gte") {
+      if ((req.token_estimate ?? 0) < expected) return false;
+      continue;
+    }
+    if (key === "token_estimate_lt") {
+      if ((req.token_estimate ?? 0) >= expected) return false;
+      continue;
+    }
+    if (key === "needs_any") {
+      const needs = Array.isArray(expected) ? expected : [expected];
+      if (!needs.some((n) => req[n])) return false;
+      continue;
+    }
+    if (key === "agent_role_in") {
+      if (!Array.isArray(expected) || !expected.includes(req.agent_role)) return false;
+      continue;
+    }
+    if (req[key] !== expected) return false;
+  }
+  return true;
+}
+
+function backendSupports(backend, req) {
+  const caps = indexCapabilities(backend.capabilities);
+  if (req.needs_thinking && !caps.thinking) return { ok: false, reason: "no_thinking" };
+  if (req.needs_vision && !caps.vision) return { ok: false, reason: "no_vision" };
+  if (req.needs_tool_use && !caps.tool_use) return { ok: false, reason: "no_tool_use" };
+  if (req.needs_parallel_tools && !caps.parallel_tools)
+    return { ok: false, reason: "no_parallel_tools" };
+  if (req.needs_long_context) {
+    if (!caps.long_context_1m && !caps.long_context_262k && !caps.long_context_200k) {
+      return { ok: false, reason: "no_long_context" };
+    }
+  }
+  // Reject backends explicitly marked degraded for the requested capability.
+  if (req.needs_tool_use && caps.degraded_tool_use) {
+    return { ok: false, reason: "degraded_tool_use" };
+  }
+  return { ok: true };
+}
+
+function indexCapabilities(arr) {
+  const out = {};
+  for (const c of arr || []) out[c] = true;
+  return out;
+}
+
+/**
+ * True when the operator kill switch is set. Accepts "1" or "true" so it
+ * matches the other CLAUDE_CODE_* / GOV_* boolean env conventions in maestro.
+ */
+function forceAnthropic(env) {
+  const v = env?.MAESTRO_ROUTER_FORCE_ANTHROPIC;
+  return v === "1" || v === "true";
+}
+
+/**
+ * A backend is auth-available when it either needs no token (anthropic-cli
+ * keychain OAuth, or an explicit `auth_env: null` local server) or its named
+ * auth env var is present and non-empty. An empty/whitespace token counts as
+ * absent — spawning with it would just fail auth at runtime.
+ */
+function hasAuth(backend, env) {
+  if (!backend.auth_env) return true; // null/absent → no token required
+  const token = env?.[backend.auth_env];
+  return typeof token === "string" && token.trim() !== "";
+}
+
+function cloneBackend(b) {
+  return {
+    ...b,
+    capabilities: Array.isArray(b.capabilities) ? [...b.capabilities] : [],
+    models: { ...(b.models || {}) },
+    pricing: { ...(b.pricing || {}) },
+  };
+}
+
+function mapHintToTier(hint) {
+  if (!hint) return null;
+  const h = String(hint).toLowerCase();
+  if (h === "haiku") return "fast";
+  if (h === "sonnet") return "default";
+  if (h === "opus") return "premium";
+  if (h === "classifier") return "fast";
+  if (h === "premium" || h === "default" || h === "fast" || h === "classifier") return h;
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Cost estimation (rough — pricing differs by region and version)
+// ---------------------------------------------------------------------------
+
+/**
+ * Estimate the dollar cost for a request given the resolved backend.
+ * Treats pricing as $ per million tokens. Returns null if we lack data.
+ */
+export function estimateCost(request, resolved) {
+  if (!resolved || !resolved.pricing) return null;
+  const inTokens = request.token_estimate ?? 0;
+  const outTokens = request.token_estimate_out ?? Math.floor(inTokens * 0.5);
+  const { input_per_m, output_per_m, cache_hit_per_m } = resolved.pricing;
+  if (input_per_m == null || output_per_m == null) return null;
+  const cacheHits = request.cache_hit_ratio ?? 0;
+  const inputUsd =
+    ((inTokens * (1 - cacheHits)) / 1e6) * input_per_m +
+    (cache_hit_per_m
+      ? ((inTokens * cacheHits) / 1e6) * cache_hit_per_m
+      : 0);
+  const outputUsd = (outTokens / 1e6) * output_per_m;
+  return Number((inputUsd + outputUsd).toFixed(6));
+}
+
+// ---------------------------------------------------------------------------
+// Introspection helpers
+// ---------------------------------------------------------------------------
+
+export function listBackends(opts = {}) {
+  const config = opts.config || loadRoutingConfig(opts.agentRoot);
+  if (!config) return ["anthropic"];
+  return Object.keys(config.backends);
+}
+
+export function describeBackend(name, opts = {}) {
+  const config = opts.config || loadRoutingConfig(opts.agentRoot);
+  const backend = config?.backends?.[name];
+  if (!backend) return null;
+  return {
+    name,
+    transport: backend.transport,
+    base_url: backend.base_url || null,
+    capabilities: indexCapabilities(backend.capabilities),
+    models: { ...backend.models },
+    pricing: { ...backend.pricing },
+  };
+}
+
+/**
+ * Build the CLI `--model` flag value for a resolved backend. For
+ * anthropic-cli transport this is the bare model string (haiku/sonnet/opus
+ * shorthand or a fully-qualified id). For non-Anthropic transports we pass
+ * the concrete model string because Claude Code propagates it directly.
+ */
+export function modelFlagFor(resolved, request = {}) {
+  if (!resolved) return modelFlagFromHint(request);
+  const tier = request.tier || mapHintToTier(request.model_hint) || "default";
+  // For anthropic-cli, prefer the human-readable shorthand because the CLI
+  // accepts "sonnet" / "opus" / "haiku" and Anthropic resolves them to the
+  // current default version, which is what existing maestro code relies on.
+  if (resolved.transport === "anthropic-cli") {
+    if (tier === "fast" || tier === "classifier") return "haiku";
+    if (tier === "premium") return "opus";
+    if (tier === "default") return "sonnet";
+    return resolved.model;
+  }
+  return resolved.model;
+}
+
+function modelFlagFromHint(req) {
+  const tier = req?.tier || mapHintToTier(req?.model_hint) || "default";
+  if (tier === "fast" || tier === "classifier") return "haiku";
+  if (tier === "premium") return "opus";
+  return "sonnet";
+}
+
+// ---------------------------------------------------------------------------
+// Convenience: derive an AgentRequest from a maestro classifier result.
+// Keeps the dispatcher's call-site one-liner-clean.
+// ---------------------------------------------------------------------------
+
+export function requestFromClassifierResult(classResult = {}, opts = {}) {
+  const req = {
+    agent_role: opts.role || "responder",
+    source: opts.source || "inbox",
+    priority: classResult.priority || "normal",
+    model_hint: classResult.model || null, // "opus" | "sonnet"
+  };
+  // Dispatcher spawns are full Claude Code agent loops with the complete tool
+  // surface, so tool use is required by construction. Default needs_tool_use
+  // to TRUE for session work and let one-shot lookups opt out explicitly
+  // (opts.oneShot: true) — otherwise a normal-priority item could match a
+  // `degraded_tool_use` backend and the capability gate would never fire.
+  req.needs_tool_use = opts.oneShot ? false : true;
+  // Critical / opus → also needs extended thinking.
+  if (classResult.priority === "critical" || classResult.model === "opus") {
+    req.needs_thinking = true;
+    req.needs_tool_use = true;
+  }
+  if (opts.token_estimate) req.token_estimate = opts.token_estimate;
+  return req;
+}
+
+// ---------------------------------------------------------------------------
+// v2 surface (additive) — re-export the resolveChain brain + validator so
+// callers import everything from "@cohortapp/agent-sdk/model-router".
+// ---------------------------------------------------------------------------
+
+export { resolveChain, validateRoutingConfig };
+// Execution lane re-exports (additive). spawnRouted is the daemon's session
+// primitive; llmTask the sanctioned cheap one-shot; repairToolCalls promotes
+// cheap-model text/JSON tool-call leakage into native tool_use blocks.
+export { spawnRouted, llmTask, repairToolCalls };
+
+// Default export: the resolver itself, for ergonomic `import router from`.
+export default {
+  loadRoutingConfig,
+  defaultRoutingConfig,
+  resolveBackend,
+  estimateCost,
+  listBackends,
+  describeBackend,
+  modelFlagFor,
+  requestFromClassifierResult,
+  CONFIG_RELATIVE_PATH,
+  // v2:
+  resolveChain,
+  validateRoutingConfig,
+  // execution lane:
+  spawnRouted,
+  llmTask,
+  repairToolCalls,
+};