Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

19.7 KB
Raw Blame
/**
 * prehydrate — resolve provider credentials in the PARENT before spawning
 * child `claudish` processes.
 *
 * WHY THIS EXISTS
 *
 * The 1Password SDK's DesktopAuth handshake is arbitrated by the desktop app
 * across the whole MACHINE, not per process: it authorizes ONE client and
 * instantly denies every concurrent peer with
 *
 *   "Denied authorization for SDK client"
 *
 * claudish already serializes SDK calls WITHIN a process (`runSdkExclusive` in
 * op-source.ts — the -4 IPC fix), but `team` and `create_session` spawn
 * N sibling PROCESSES, and no in-process queue can span those. Each child
 * constructs its own SDK client and they all race.
 *
 * Measured on a 7-model `team` run (session team-20260729-163623): all seven
 * children spawned within 6ms, five hit the denial, and only the models whose
 * key happened to be in the shell env survived. Reduced repro: 6 children in a
 * tight loop → 5 denied; the same 6 staggered 4s apart → 0 denied.
 *
 * The denial is swallowed by `onAuthFailure: "skip"` (correct — a bad op source
 * must never lock the user out), so the child dies with a bare
 * "X API Key is required", which reads as "claudish ignored my 1Password setup".
 *
 * THE FIX
 *
 * Do in the parent, ONCE, what each child would otherwise do N times in
 * parallel. `validateApiKeysForModels` runs every model through the credential
 * authority, and the authority write-throughs each resolved op:// key into
 * `process.env` (api-key-credential.ts). Spawned children inherit `process.env`,
 * so they find the key in step 1 of the resolution chain and never construct an
 * SDK client at all — exactly the state the surviving models were already in.
 *
 * The parent's own resolution is serialized by the existing op queue, and a
 * 1Password Environment is fetched once per process (single-flight), so this
 * costs ONE handshake regardless of how many models are being spawned.
 *
 * Pre-hydration is the cheap path, not the whole fix. It covers the keys
 * 1Password CAN supply, at every spawn site claudish owns. Two other gaps are
 * handled elsewhere:
 *
 *   · Keys 1Password does NOT hold still send each child to the SDK →
 *     `publishOpSkipList` below tells children not to bother.
 *   · Two INDEPENDENT claudish processes launched at the same instant by
 *     unrelated sessions cannot be reached by any parent/child protocol →
 *     `providers/onepassword-handshake-lock.ts` serializes the handshake
 *     across processes.
 *
 * WHY HYDRATION ALONE WAS NOT ENOUGH — the spawn PLAN
 *
 * Hydration resolves a CREDENTIAL. What it never resolved is the ROUTING
 * DECISION, and a bare model name is a chain, not a credential.
 * `validateApiKeysForModels` asks the authority about the ONE provider
 * `resolveModelProvider` picked and stops as soon as the answer is "available"
 * (`rescueRoutableResolutions` only runs on a "missing" verdict). The child,
 * handed that same bare name, re-walks the WHOLE chain and asks 1Password about
 * every candidate the parent short-circuited past — so it builds its own SDK
 * client after all. Measured: 17 MCP session children logged
 * "Denied authorization for SDK client" on runs where pre-hydration had already
 * succeeded (see baseline-evidence.md in this feature's session dir).
 *
 * So the parent now also RESOLVES THE ROUTE and returns a {@link SpawnPlan}
 * mapping each bare name to explicit `prefix@model` specs. A child launched with
 * explicit specs skips routing entirely and finds each provider's key in the
 * inherited env at step 1 of the resolution chain — `hasOpSources()` is never
 * reached, so no SDK client is ever built.
 *
 * The pin carries the WHOLE credential-filtered chain, joined by
 * `MODEL_CHAIN_SEPARATOR` (`zgo@m+mm@M+or@v/m`), not just the primary. Pinning
 * only the primary bought the one-dialog property at the cost of retryability:
 * `FallbackHandler` is built only for a name the child routes ITSELF, and
 * `isRetryableError` has no other caller, so a spawned child could not fall
 * through on a spent subscription, a rotated key, or a provider that rejects the
 * request shape — recoveries an interactive run makes for free. Every element of
 * the chain is still explicit, so nothing re-routes and the dialog property is
 * unchanged; the child just has somewhere to go when the first candidate fails.
 *
 * Handing over the chain is safe rather than merely hopeful because the keys for
 * ALL of it are already in `process.env` when the pin is made: `route()`'s bare
 * path calls `credentials.isAvailable()` on every candidate, and that resolution
 * write-throughs each op:// value into the env children inherit. Candidates that
 * failed the filter are absent from the chain, so the child never looks them up.
 *
 * ORDERING IS LOAD-BEARING: phase A (hydrate) MUST complete before phase B
 * (route). `route()`'s credential filter reads the same env phase A writes;
 * run them the other way round and every candidate is a miss, so `route()`
 * itself re-enters the SDK for candidates hydration would have satisfied — the
 * same storm, relocated to the parent. That is the reason the pin lives in
 * here rather than at the two call sites.
 *
 * NOTHING SECRET GOES ON ARGV. The only thing added is a provider prefix; keys
 * still travel exclusively by inherited `process.env`. `team-orchestrator.ts`
 * persists the spawn command into `status.json`, and that string stays
 * secret-free under this design.
 */

import { loadConfig } from "../../profile-config.js";
import { PROVIDER_TO_PREFIX } from "../../providers/auto-route.js";
import { ensureCatalogReady } from "../../providers/catalog-client.js";
import { ensureEndpointsRegistered } from "../../providers/endpoint-registration.js";
import { MODEL_CHAIN_SEPARATOR } from "../../providers/model-parser.js";
import { proxyRouteDecision } from "../../providers/native-route.js";
import { getOpFailures } from "../../providers/onepassword.js";
import { validateApiKeysForModels } from "../../providers/provider-resolver.js";
import type { Route, RoutePlan } from "../../providers/routing-rules.js";
import { route } from "../../providers/routing-rules.js";
import { OP_UNAVAILABLE_ENV, getOpUnavailableVars } from "./op-source.js";

/** The routing oracle {@link prehydrateCredentialsForSpawn} consults (test seam). */
export type RouteOracle = (spec: string) => Promise<RoutePlan>;

/** Phase-A credential validator (test seam; production uses the real authority). */
export type CredentialValidator = typeof validateApiKeysForModels;

/** How long to wait for the OpenRouter catalog before pinning. Best-effort. */
const CATALOG_WARM_TIMEOUT_MS = 5000;

/**
 * The result of a pre-spawn resolve: which explicit spec to hand each child.
 */
export interface SpawnPlan {
  /**
   * The original `--model` value → the explicit spec (or `+`-joined chain of
   * specs) to spawn with.
   *
   * ABSENT means "spawn with the original string" — it is NEVER an error
   * signal. Call sites degrade with `plan.pinned.get(m) ?? m`, which is exactly
   * today's behaviour, so every degradation case in the design doc (§4) is
   * handled by simply omitting the entry.
   */
  pinned: Map<string, string>;
}

export interface PrehydrateOptions {
  /**
   * Resolve routes and populate `plan.pinned` (default `true`).
   *
   * Pass `false` when the parent's routing view is not the child's — the only
   * current case is `create_session` with a `work_dir` outside the parent's
   * cwd, because `route()` reads project-local config relative to
   * `process.cwd()` and would decide with the wrong project's rules.
   * (`process.chdir()` is not an option: it is process-global and races
   * concurrent calls.) Phase A still runs.
   */
  pin?: boolean;
  /** Test seam — injectable router, mirroring `RouteOracle` in provider-resolver. */
  router?: RouteOracle;
  /** Test seam — proves phase A runs without replacing a shared Bun module. */
  validator?: CredentialValidator;
}

/**
 * Resolve credentials for `models` into `process.env` — and their routes into a
 * {@link SpawnPlan} — before spawning children.
 *
 * Cheap and safe to call unconditionally: with no 1Password source configured
 * the sync sniff (`hasOpSources`) short-circuits without importing the SDK, and
 * any provider whose key is already in env never reaches 1Password either.
 *
 * NEVER THROWS. Pre-hydration is an optimization of WHERE resolution happens,
 * not a gate on whether the spawn proceeds — a credential that cannot be
 * resolved here simply stays missing, and the child reports it exactly as
 * before. Failing the spawn on a pre-hydration error would turn a soft
 * "this one model has no key" into a hard "the whole team run died". The same
 * contract covers the plan: a model that cannot be routed is simply absent
 * from `plan.pinned` and spawns bare, exactly as it does today.
 */
export async function prehydrateCredentialsForSpawn(
  models: (string | undefined)[],
  opts?: PrehydrateOptions
): Promise<SpawnPlan> {
  const plan: SpawnPlan = { pinned: new Map() };
  const wanted = models.filter((m): m is string => !!m);
  if (wanted.length === 0) return plan;
  try {
    // Phase A — hydrate. Write-throughs land in process.env here, and phase B
    // depends on seeing them (see ORDERING IS LOAD-BEARING above).
    await (opts?.validator ?? validateApiKeysForModels)(wanted);

    // Phase B — route. Never throws; every failure omits an entry.
    if (opts?.pin !== false) {
      await pinRoutes(wanted, plan.pinned, opts?.router ?? route);
    }

    // Phase C — unchanged, and still LAST so it sees the fuller record that
    // phase B's whole-chain walk produces.
    publishOpSkipList();
  } catch {
    // Non-fatal by contract — see above.
  }
  return plan;
}

/**
 * Resolve an explicit spawn spec for each distinct model. Never throws.
 *
 * Deliberately SEQUENTIAL. The op queue (`runSdkExclusive`) serializes SDK work
 * anyway, and going one model at a time means the first model's resolution has
 * already write-throughed its keys into `process.env` before the second model's
 * chain is filtered — so shared candidates are answered from env instead of
 * being asked concurrently.
 */
async function pinRoutes(
  models: string[],
  into: Map<string, string>,
  router: RouteOracle
): Promise<void> {
  try {
    const routable = [...new Set(models)].filter(isRoutablyPinnable);
    if (routable.length === 0) return;

    await prepareParentRoutingContext();

    for (const model of routable) {
      const spec = await pinSpecFor(model, router);
      if (spec) into.set(model, spec);
    }
  } catch {
    // Belt-and-braces: `pinSpecFor` already swallows per-model failures, and a
    // pin that never happens just means a bare spawn. Contained HERE rather
    // than in the caller's catch so phase C (`publishOpSkipList`) keeps running
    // exactly as it did before pinning existed.
  }
}

/**
 * Would the CHILD route this name at all?
 *
 * This asks the child's own gate (`proxy-server.ts` step 2c), `proxyRouteDecision`,
 * so the two cannot drift: only a `bare` decision is routed. Pinning a name the
 * child would not have routed does not just waste a `route()` call — it CHANGES
 * the child's behaviour, which the pin must never do:
 *
 *   - **explicit spec** (`gc@glm-5`, `or@x/y`, `[email protected]:3`, a URL) —
 *     nothing to decide, the child already skips routing. Unconditional and
 *     first, and it is what protects concurrency suffixes: `parseModelSpec`
 *     STRIPS the `:3` off `[email protected]:3` (`model` comes back `"llama3.2"`),
 *     so a spec rebuilt from parsed parts would silently lose it. The early-out,
 *     NOT lossless round-tripping, is the guarantee.
 *   - **native-anthropic** (Claude Code's own names: `opus`, `sonnet`,
 *     `opusplan`, `claude-*`; see `isClaudeCodeModelName`) — the child never
 *     routes these. `route()` would nonetheless answer `ok` for them, because
 *     `defaultProvider` is appended to EVERY bare-name chain, so an unguarded pin
 *     would spawn `--model or@opus` and send a native model through OpenRouter.
 *     Both `team` and `create_session` run these as native slots (see "Native
 *     Model Slots" in team-orchestrator.ts), so this check is what keeps them
 *     bare. Any other bare name with no `/` (`o4-mini`, a typo) is `bare`: the
 *     child routes it, so the parent pins its chain like any other.
 *   - **`poe:` models** — same gate, same reason.
 */
function isRoutablyPinnable(model: string): boolean {
  return proxyRouteDecision(model).type === "bare";
}

/**
 * Give the parent the same routing view the child would have.
 *
 * Endpoint registration is normally driven by `createProxyServer`, and the
 * parent starts no proxy for `team` / `create_session`. Without it a
 * custom-endpoint provider is unregistered here but registered in the child,
 * so the parent could pin a DIFFERENT provider than the child would pick.
 * Registration is sync, config-only and idempotent per name; the `once` guard
 * keeps it to a single config read per process.
 *
 * `ensureEndpointsRegistered` now covers BOTH the bundled catalog and the
 * user's own `customEndpoints`, so the separate `loadCustomEndpoints` call that
 * used to sit here is gone. It had to be both in the first place, which is the
 * bug #192 describes from the other side.
 *
 * Warming the OpenRouter catalog mirrors what `proxy-server.ts` does before its
 * own `route()` call. Best-effort: on timeout the resolver falls back to the
 * on-disk cache, and an under-resolved OpenRouter id is re-resolved (and thus
 * repaired) by the child anyway.
 */
let parentRoutingContextReady = false;
async function prepareParentRoutingContext(): Promise<void> {
  if (!parentRoutingContextReady) {
    parentRoutingContextReady = true;
    try {
      // One config object for both halves — the bundled catalog's suppression
      // set is built from this same `customEndpoints` map, and the two reading
      // different objects (or scopes) is what could suppress a bundled row
      // without registering its replacement.
      const config = loadConfig();
      ensureEndpointsRegistered({ config });
    } catch {
      // Config read failure must not block the spawn — the parent just keeps
      // the builtin-only provider set, same as any other consumer of a broken
      // config. Validation errors are already surfaced by the proxy.
    }
  }
  try {
    await ensureCatalogReady(CATALOG_WARM_TIMEOUT_MS);
  } catch {
    // ensureCatalogReady is documented not to throw; belt-and-braces.
  }
}

/**
 * The explicit `prefix@model` spec to spawn `model` with, or `null` when the
 * child should be handed the original string.
 *
 * `null` is returned for every degradation case, never an exception:
 *   - the child would not have routed this name ({@link isRoutablyPinnable}) —
 *     the router is not even called
 *   - `route()` found no credentialed provider (`kind: "no-route"`) — the child
 *     re-runs the same routing and produces the real error with its hint,
 *     which is a better message than the parent could guess at here
 *   - `route()` threw (catalog / disk / network hiccup)
 */
export async function pinSpecFor(
  model: string,
  router: RouteOracle = route
): Promise<string | null> {
  if (!isRoutablyPinnable(model)) return null;
  try {
    const plan = await router(model);
    if (plan.kind !== "ok") return null;
    return joinPinnedChain([plan.primary, ...plan.fallbacks]);
  } catch {
    return null;
  }
}

/**
 * Render a credential-filtered chain as ONE argv-safe value.
 *
 * Pinning only the primary was the original design, and it left every spawned
 * child with a chain of one — no `FallbackHandler`, so no retry on a spent
 * subscription, a rotated key, or a provider that cannot serve the request shape.
 * The parent had already computed the fallbacks and dropped them on the floor.
 *
 * THE KEYS FOR THE WHOLE CHAIN ARE ALREADY IN `process.env` BY THE TIME THIS RUNS,
 * which is what makes handing over the chain safe rather than merely optimistic.
 * `route()`'s bare path calls `credentials.isAvailable()` on EVERY candidate, and
 * `ApiKeyCredentialProvider.resolveKey` write-throughs each resolved op:// value
 * into `process.env` (api-key-credential.ts). Children inherit that env, so every
 * candidate here resolves at step 1 of the child's chain — `hasOpSources()` is
 * never reached and no child ever builds an SDK client, exactly as with a
 * single-candidate pin. Candidates that FAILED the filter are absent from the
 * chain, so the child never even looks their key up.
 *
 * A candidate that cannot be made self-describing is DROPPED rather than
 * failing the pin: the surviving prefix of the chain is strictly better than
 * spawning bare, and `normalizePinnedSpec` only returns null for a malformed
 * route. Returns null only when nothing survives, which the caller reads as
 * "spawn with the original name".
 */
export function joinPinnedChain(routes: Route[]): string | null {
  const specs = routes.map(normalizePinnedSpec).filter((s): s is string => !!s);
  return specs.length > 0 ? specs.join(MODEL_CHAIN_SEPARATOR) : null;
}

/**
 * Make a `Route` argv-safe.
 *
 * `buildRoutingChain` builds `modelSpec` two different ways: OpenRouter gets
 * the catalog-resolved id with NO prefix (`x-ai/grok-4.20`), everything else
 * gets a self-describing `prefix@model` (`gc@glm-5`). Inside the proxy that
 * asymmetry is harmless because the candidate's `provider` field picks the
 * handler. On argv the string must describe itself:
 *
 *   parseModelSpec("x-ai/grok-4.20") → provider "x-ai", isExplicitProvider FALSE
 *
 * i.e. handing that to `--model` produces a bare name again and the child
 * re-routes — the pin silently does nothing for every OpenRouter primary, which
 * a chain has whenever OpenRouter is its first credentialed hop (it is a
 * gateway candidate for many catalog models and the default fallback hop).
 * Prefixing fixes it:
 * `or@x-ai/grok-4.20` parses as provider "openrouter", explicit.
 *
 * The `?? r.provider` branch covers runtime-registered custom endpoints, which
 * are absent from `PROVIDER_TO_PREFIX` (an IIFE over the builtin table) and
 * round-trip on their literal name (`my-vllm@model`).
 */
export function normalizePinnedSpec(r: Route): string | null {
  const spec = r.modelSpec?.trim();
  if (!spec) return null;
  // Already self-describing: a "provider@model" spec, or a custom URL (which
  // parseModelSpec treats as explicit on its own).
  if (spec.includes("@")) return spec;
  if (spec.startsWith("http://") || spec.startsWith("https://")) return spec;
  const prefix = PROVIDER_TO_PREFIX[r.provider] ?? r.provider;
  if (!prefix || prefix.includes("@")) return null;
  return `${prefix}@${spec}`;
}

/**
 * Tell children which env vars 1Password answered it does NOT hold, so they
 * skip the SDK for those entirely.
 *
 * Pre-hydration alone cannot silence the race. It hands children every key
 * 1Password CAN supply — but a bare model name filters a CHAIN, and each child
 * walks that chain from the top. The candidates 1Password has nothing for are
 * still a miss in env, so each child opens its own SDK client for them, all at
 * the same instant. Observed in ai-docs/sessions/opverify3: 3/3 models
 * succeeded on inherited keys, and two children still logged
 * "Denied authorization for SDK client" chasing a key that does not exist.
 *
 * ONLY published when the run recorded NO op failures. A denial also produces
 * an empty resolve, and publishing that would teach every child that a key the
 * user really does store in 1Password is permanently absent — turning one
 * transient denial into a run-wide outage. With failures present we publish
 * nothing and children behave exactly as before.
 */
function publishOpSkipList(): void {
  if (getOpFailures().length > 0) return;
  const unavailable = getOpUnavailableVars();
  if (unavailable.length === 0) return;
  process.env[OP_UNAVAILABLE_ENV] = unavailable.join(",");
}