Skip to content

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

23.7 KB
Raw Blame
/**
 * `--advisor` startup: plan every member, build the routed chains, then refuse
 * or print the notice.
 *
 * Design rule (requirements.md, decided Q3): anything claudish can determine at
 * LAUNCH is a refusal at startup with a named reason and a non-zero exit. Runtime
 * warnings are only for what cannot be known until the child is running. R5
 * forbids the alternative — a session that silently has no advisor looks exactly
 * like one that works.
 *
 * Refusals, in order:
 *   1. `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` is true in the child's environment.
 *      The enable variable does not override it, so no advisor tool is offered.
 *   2. A main-model path whose wire format drops every tool. Decided from the
 *      RESOLVED provider's transport and a probe of that format's
 *      `convertTools`, never from a model list.
 *   3. No panel models.
 *   4. ANY panel member whose plan is refused (routing found no route, a wire
 *      marker error, a Claude selector, a Claude member with no credential)
 *      or whose built chain has no callable hop. Every one is listed.
 *   5. A collector the user NAMED that is refused likewise. A DEFAULTED
 *      collector (`haiku`, supplied by parseAdvisorFlag) is instead dropped —
 *      see `decideAdvisorStartup`.
 *
 * Where a member goes is decided by `planAdvisorModel` (handlers/advisor-route-plan.ts),
 * which wraps `explainRoute`, the function main routing is derived from, and
 * decides a Claude name first, as the proxy does. Each routed member's chain is
 * then BUILT here, before the port is bound, with the getters main routing
 * uses, in a handler set of its own (`requestRole: "advisor"`). The notice, the
 * refusal and the runtime all read those plans and builds, so they cannot
 * disagree, and there is no lazy path. Members are planned, and chains built,
 * strictly one after another: a build may resolve a credential value
 * (1Password, Keychain), and concurrent handshakes are what 1Password refuses.
 *
 * `decideAdvisorStartup` is pure. `evaluateAdvisorStartup` gathers its facts
 * (the planning and building above, injectable for tests) and shuts every
 * built handler down when it refuses. Printing, exiting, applying the
 * effective collector and handing the runtime to the proxy belong to the
 * caller (index.ts).
 *
 * Output channel: the caller writes the notice to STDERR before the child
 * spawns. In `-p` mode stdout carries Claude Code's (often machine-readable)
 * output and nothing else; see ai-docs/architecture/headless-vs-interactive.md.
 * Terminal isolation (terminal-isolation.ts) is not active yet at that point, so
 * the write reaches the terminal instead of being diverted to the log.
 */

import { OllamaAPIFormat } from "./adapters/ollama-api-format.js";
import type { AdvisorToolEnv, ChildAuthControl } from "./claude-runner.js";
import { ADVISOR_TOOL_ENV_VAR, childAuthControl } from "./claude-runner.js";
import type { AdvisorRuntime } from "./handlers/advisor-panel-gateway.js";
import {
  type AdvisorChainBuild,
  type AdvisorModelPlan,
  type AdvisorRole,
  type PlanAdvisorDeps,
  advisorChainKey,
  buildAdvisorChains,
  describeAdvisorPlan,
  describeAdvisorRefusal,
  planAdvisorModel,
  shutdownAdvisorChains,
} from "./handlers/advisor-route-plan.js";
import { type HandlerSet, createHandlerSet } from "./handlers/handler-set.js";
import { resolveAdvisorCredential } from "./handlers/native-handler-advisor.js";
import { parseModelSpec } from "./providers/model-parser.js";
import { nativeRouteFor } from "./providers/native-route.js";
import { type TransportType, getProviderByName } from "./providers/provider-definitions.js";
import { resolveModelProvider } from "./providers/provider-resolver.js";
import { traceSpan } from "./startup-trace.js";
import type { ClaudishConfig } from "./types.js";

export type { AdvisorRole };

/** Claude Code's kill switch for the advisor tool. Wins over the enable variable. */
export const ADVISOR_DISABLE_ENV_VAR = "CLAUDE_CODE_DISABLE_ADVISOR_TOOL";

/**
 * Claude Code's strict boolean reader: `1`, `true`, `yes`, `on` after trim and
 * lowercase are true; EVERYTHING else is false — `"2"`, `"false"`, `""`, unset.
 */
export function isClaudeCodeBoolTrue(value: string | undefined): boolean {
  if (value === undefined) return false;
  const v = value.trim().toLowerCase();
  return v === "1" || v === "true" || v === "yes" || v === "on";
}

// ---------------------------------------------------------------------------
// Main-model path — can it carry a tool at all?
// ---------------------------------------------------------------------------

/** The slice of a wire format that decides whether tools survive it. */
export interface ToolSchemaConverter {
  convertTools(claudeRequest: unknown, summarize?: boolean): unknown[];
  getName(): string;
}

/**
 * Pure: does this format put ANY tool on the wire? Probes `convertTools` with a
 * one-tool request shaped like the advisor tool claudish swaps in. An empty
 * result means every tool is stripped (`OllamaAPIFormat.convertTools` returns
 * `[]`), so an advisor tool can never reach the model.
 *
 * Fails OPEN on a throw: a probe that breaks must not block every launch on
 * that path.
 */
export function formatCarriesTools(format: ToolSchemaConverter): boolean {
  try {
    const out = format.convertTools(
      {
        tools: [
          {
            name: "advisor",
            description: "startup probe",
            input_schema: { type: "object", properties: {}, additionalProperties: false },
          },
        ],
      },
      false
    );
    return Array.isArray(out) && out.length > 0;
  } catch {
    return true;
  }
}

/**
 * The wire format a transport pins, for transports whose profile builds ONE
 * fixed format regardless of model (`ollamaCloudProfile` → `OllamaAPIFormat`).
 * `null` means the format is chosen per model or per request (every other
 * transport) and all of those convert tools; the path is then treated as
 * tool-capable. Whether the pinned format carries tools is NOT asserted here —
 * `formatCarriesTools` probes it, so a future Ollama format that learns tools
 * lifts the refusal without anyone editing this file.
 */
export function pinnedFormatForTransport(
  transport: TransportType,
  modelName: string
): ToolSchemaConverter | null {
  switch (transport) {
    case "ollamacloud":
      return new OllamaAPIFormat(modelName);
    default:
      return null;
  }
}

/** One main-model candidate, resolved for the notice and the tool check. */
export interface MainModelFact {
  model: string;
  /** Display name of the provider that serves it. */
  providerName: string;
  carriesTools: boolean;
  /** The pinned wire format, when the transport pins one (for the refusal text). */
  wireFormat?: string;
}

/**
 * Resolve the provider and tool capability of one main-model spec, with no
 * network and no credential access.
 *
 * `nativeRouteFor` FIRST, as the proxy does (CLAUDE.md invariant): a bare Claude
 * name is served natively and must never be read through the remote-provider
 * resolver, which would mislabel it.
 */
export function resolveMainModelFact(model: string): MainModelFact {
  const native = nativeRouteFor(model);
  if (native) return { model, providerName: native.displayName, carriesTools: true };

  const resolution = resolveModelProvider(model);
  // toRemoteProvider renames exactly one provider (google → gemini); reverse it
  // to reach the definition, as createHandlerForProvider does.
  const definitionName = resolution.catalogName === "gemini" ? "google" : resolution.catalogName;
  const definition = definitionName ? getProviderByName(definitionName) : undefined;
  const format = definition
    ? pinnedFormatForTransport(definition.transport, resolution.modelName)
    : null;
  // `auto-route` is a bare name route() decides on the first request, so no
  // provider is known yet; `unknown` is a `vendor/` with no known vendor.
  const providerName =
    resolution.category === "unknown" || resolution.category === "auto-route"
      ? "unresolved (routed on the first request)"
      : definition?.displayName || resolution.providerName;
  return {
    model,
    providerName,
    carriesTools: format ? formatCarriesTools(format) : true,
    wireFormat: format?.getName(),
  };
}

/**
 * The main-model specs this launch actually routes: the pinned chain when there
 * is one (every element can serve a turn after a fallback), else `--model`, else
 * — only when no `--model` was given — the profile's tier mappings. Empty means
 * Claude Code picks its own model natively.
 */
export function mainModelSpecs(config: ClaudishConfig): string[] {
  if (config.modelChain && config.modelChain.length > 0) return [...config.modelChain];
  if (config.model) return [config.model];
  const tiers = [config.modelOpus, config.modelSonnet, config.modelHaiku, config.modelSubagent];
  return [...new Set(tiers.filter((m): m is string => typeof m === "string" && m.length > 0))];
}

/** Model identity for the "panel includes the main model" line: provider-free, vendor-free. */
function modelIdentity(spec: string): string {
  const model = parseModelSpec(spec).model.toLowerCase();
  const slash = model.lastIndexOf("/");
  return slash >= 0 ? model.slice(slash + 1) : model;
}

/** Pure: the panel members that are the main model, under the same or another spelling. */
export function panelMembersMatchingMain(panel: string[], mainModels: string[]): string[] {
  const main = new Set(mainModels.map(modelIdentity));
  return panel.filter((p) => main.has(modelIdentity(p)));
}

// ---------------------------------------------------------------------------
// The decision
// ---------------------------------------------------------------------------

/** Every fact the startup decision reads. Nothing in here needs I/O to inspect. */
export interface AdvisorLaunchFacts {
  panel: string[];
  collector: string | null;
  /** True when `collector` is parseAdvisorFlag's default, not the user's choice. */
  collectorDefaulted: boolean;
  /** Empty = no main model named; Claude Code's own session model serves. */
  mainModels: MainModelFact[];
  /** The environment the child Claude Code will inherit. */
  childEnv: Record<string, string | undefined>;
  toolEnv: AdvisorToolEnv;
  /** Index-aligned with `panel`: each member's startup plan. */
  panelPlans: AdvisorModelPlan[];
  /** The collector's plan; null when no collector was given. */
  collectorPlan: AdvisorModelPlan | null;
  /** Every routed member's built chain, keyed `"<role>:<spec>"` (`advisorChainKey`). */
  builds: ReadonlyMap<string, AdvisorChainBuild>;
  /** The launch's `childAuthControl` decision the Claude plans were made with. */
  childAuth: ChildAuthControl;
}

export type AdvisorStartupDecision =
  | { kind: "refuse"; reason: string }
  | {
      kind: "proceed";
      notice: string[];
      /**
       * The collector the proxy must use. Equals `facts.collector` except when a
       * DEFAULTED collector cannot be called, in which case it is `null`. The
       * caller MUST apply it to the config before the proxy is created.
       */
      effectiveCollector: string | null;
      /** The plans and chains the proxy's panel gateway runs on (no lazy path). */
      runtime: AdvisorRuntime;
    };

/**
 * Pure: the refusals decidable WITHOUT planning (1–3). Split out so the
 * caller can skip routing, credential lookups and handler construction — and
 * any 1Password prompt — for a launch that is refused anyway.
 */
export function refusalBeforeCredentials(
  facts: Pick<AdvisorLaunchFacts, "childEnv" | "mainModels" | "panel">
): string | null {
  const disable = facts.childEnv[ADVISOR_DISABLE_ENV_VAR];
  if (isClaudeCodeBoolTrue(disable)) {
    return (
      `${ADVISOR_DISABLE_ENV_VAR}=${JSON.stringify(disable)} is set in your environment. ` +
      `Claude Code then never offers the advisor tool, and ${ADVISOR_TOOL_ENV_VAR} does not ` +
      `override it. Unset ${ADVISOR_DISABLE_ENV_VAR} to use --advisor.`
    );
  }

  const toolless = facts.mainModels.filter((m) => !m.carriesTools);
  if (toolless.length > 0) {
    const named = toolless
      .map((m) => `${m.model} (${m.providerName}${m.wireFormat ? `, ${m.wireFormat}` : ""})`)
      .join(", ");
    return (
      `the main model path cannot carry tools: ${named} drops every tool from the request, ` +
      "so the advisor tool can never reach the model. Choose a main model on a provider " +
      "that supports tool calls, or drop --advisor."
    );
  }

  if (facts.panel.length === 0) {
    return 'no advisor panel models were given. Use --advisor "model1[,model2][:collector]".';
  }
  return null;
}

/**
 * Pure: why a member cannot be called, or null when it can. A refused plan
 * reads as its refusal; a routed plan whose chain has no callable hop names
 * every hop's outcome. A Claude member is callable once planned: its plan
 * already refused the launch that has no credential for it.
 */
export function advisorMemberRefusal(
  plan: AdvisorModelPlan,
  builds: ReadonlyMap<string, AdvisorChainBuild>
): string | null {
  if (plan.kind === "refused") return describeAdvisorRefusal(plan);
  if (plan.kind === "claude-native") return null;
  const build = builds.get(advisorChainKey(plan.role, plan.spec));
  if (!build) return `${plan.spec}: its chain was not built at startup`;
  if (build.firstCallableHop === null || !build.handler) {
    return describeAdvisorRefusal({ plan, build });
  }
  return null;
}

/**
 * The notice lines for one member: its plan described from its built chain,
 * then each routing warning (a subscription that does not serve the model, or
 * whose credential could not be read) as a `note:` line under it. `route()`
 * prints those per request; nothing prints them for an advisor call.
 */
function memberNoticeLines(
  plan: AdvisorModelPlan,
  builds: ReadonlyMap<string, AdvisorChainBuild>,
  indent: string
): string[] {
  const build =
    plan.kind === "routed" ? builds.get(advisorChainKey(plan.role, plan.spec)) : undefined;
  const lines = [describeAdvisorPlan(plan, build)];
  if (plan.kind === "routed") {
    for (const warning of plan.explanation.warnings) {
      if (warning.type === "rule-problem") continue;
      lines.push(`${indent}  note: ${warning.message}`);
    }
  }
  return lines;
}

/**
 * A refusal reason without its closing full stop, for a sentence that goes on
 * after it. Several reasons end in one ("…that carries it.", "…or a model
 * id."), and the refusal printed `….. Remove…`.
 */
function clause(reason: string): string {
  return reason.trimEnd().replace(/\.+$/, "");
}

/** The `claudish --probe` hint of a refusal: the first refused member's spec. */
function probeHint(specs: string[]): string {
  return `claudish --probe ${specs[0] ?? "<model>"} shows the routing decision`;
}

/**
 * Pure: the collector's part of the decision — refuse a NAMED collector that
 * cannot be called, drop a DEFAULTED one, else keep it — and its notice lines.
 */
function decideCollector(
  facts: Pick<AdvisorLaunchFacts, "collector" | "collectorDefaulted" | "collectorPlan" | "builds">
):
  | { kind: "refuse"; reason: string }
  | { kind: "keep"; effectiveCollector: string | null; lines: string[] } {
  const cp = facts.collectorPlan;
  if (!cp) return { kind: "keep", effectiveCollector: facts.collector, lines: ["none"] };
  const refusal = advisorMemberRefusal(cp, facts.builds);
  if (!refusal) {
    return {
      kind: "keep",
      effectiveCollector: facts.collector,
      lines: memberNoticeLines(cp, facts.builds, "  "),
    };
  }
  if (!facts.collectorDefaulted) {
    return {
      kind: "refuse",
      reason:
        `collector ${clause(refusal)}. ` +
        'Name another collector ("a,b:collector"), or end the value with ":" for no collector ' +
        `(${probeHint([cp.spec])}).`,
    };
  }
  // DEFAULTED collector that cannot be called: proceed WITHOUT it rather than
  // refuse. Every multi-model panel with no ":" defaults to `haiku`, and a
  // launch with a non-Claude --model has no Claude login and usually no
  // ANTHROPIC_API_KEY — refusing would break the default. The panel's answers
  // are concatenated instead, as the notice says.
  return {
    kind: "keep",
    effectiveCollector: null,
    lines: [`none — ${clause(refusal)}; panel answers will be concatenated`],
  };
}

/**
 * Pure: refuse, or proceed with the notice lines, the effective collector and
 * the runtime the proxy's panel gateway runs on.
 */
export function decideAdvisorStartup(facts: AdvisorLaunchFacts): AdvisorStartupDecision {
  const early = refusalBeforeCredentials(facts);
  if (early) return { kind: "refuse", reason: early };

  const refused = facts.panelPlans
    .map((plan) => ({ plan, reason: advisorMemberRefusal(plan, facts.builds) }))
    .filter((r): r is { plan: AdvisorModelPlan; reason: string } => r.reason !== null);
  if (refused.length > 0) {
    return {
      kind: "refuse",
      reason:
        `advisor panel model${refused.length > 1 ? "s" : ""} cannot be called: ` +
        `${refused.map((r) => clause(r.reason)).join("; ")}. ` +
        "Remove the model from --advisor, or fix what the reason names " +
        `(${probeHint(refused.map((r) => r.plan.spec))}).`,
    };
  }

  const collectorDecision = decideCollector(facts);
  if (collectorDecision.kind === "refuse") return collectorDecision;
  const { effectiveCollector, lines: collectorLines } = collectorDecision;
  const cp = facts.collectorPlan;

  const notice: string[] = ["[claudish] --advisor is on for this launch"];
  notice.push("  panel (each model is routed like a main-model request):");
  for (const plan of facts.panelPlans) {
    const [first, ...notes] = memberNoticeLines(plan, facts.builds, "    ");
    notice.push(`    ${first}`, ...notes);
  }
  const [collectorFirst, ...collectorNotes] = collectorLines;
  notice.push(`  collector:  ${collectorFirst}`, ...collectorNotes);

  const main =
    facts.mainModels.length === 0
      ? "your Claude Code session"
      : facts.mainModels.map((m) => `${m.model} via ${m.providerName}`).join(" -> ");
  notice.push(`  main model: ${main}`);

  const envValue = facts.childEnv[ADVISOR_TOOL_ENV_VAR];
  if (facts.toolEnv.source === "inherited") {
    notice.push(
      `  ${ADVISOR_TOOL_ENV_VAR}=${JSON.stringify(envValue ?? "")} inherited from your environment` +
        (isClaudeCodeBoolTrue(envValue)
          ? ""
          : " — Claude Code reads this value as FALSE, so the advisor tool appears only if your main model qualifies for it without the override")
    );
  } else {
    notice.push(`  ${ADVISOR_TOOL_ENV_VAR}=1 set by claudish`);
  }

  const includesMain = panelMembersMatchingMain(
    facts.panel,
    facts.mainModels.map((m) => m.model)
  );
  if (includesMain.length > 0) {
    notice.push(`  note: the panel includes the main model (${includesMain.join(", ")})`);
  }

  notice.push(
    "  cost: each advisor call sends the FULL conversation to every panel model, uncached; " +
      "subscription hops draw on the plan's allowance, metered hops bill per token; " +
      "routing keeps using the last hop that served"
  );
  // Planning ran main routing's credential filter for every routed member:
  // each candidate the chain keeps had its key resolved once, now, not on first
  // use (advisor.md, "Credentials are resolved at launch").
  const routedMembers = [...facts.panelPlans, ...(cp ? [cp] : [])].some(
    (plan) => plan.kind === "routed"
  );
  if (routedMembers) {
    notice.push(
      "  credentials: each routed advisor model's chain had its keys resolved at launch, " +
        "including fallback hops (1Password or Keychain may have been asked once)"
    );
  }

  const plans = new Map<string, AdvisorModelPlan>();
  for (const plan of facts.panelPlans) plans.set(advisorChainKey("panel", plan.spec), plan);
  if (cp && effectiveCollector !== null) plans.set(advisorChainKey("collector", cp.spec), cp);
  return {
    kind: "proceed",
    notice,
    effectiveCollector,
    runtime: { plans, chains: facts.builds, childAuth: facts.childAuth },
  };
}

/** Injectable I/O for `evaluateAdvisorStartup`; every field defaults to the real thing. */
export interface AdvisorStartupDeps {
  /** Default `childAuthControl(config, childEnv)`. */
  childAuth?: ChildAuthControl;
  /** Presence of ANTHROPIC_API_KEY; default the advisor's own lookup, value dropped. */
  anthropicKeyPresent?: () => Promise<boolean>;
  /** Default `planAdvisorModel`. */
  plan?: (spec: string, role: AdvisorRole, deps: PlanAdvisorDeps) => Promise<AdvisorModelPlan>;
  /** Default: a fresh advisor handler set (`requestRole: "advisor"`, no token file). */
  createHandlerSet?: () => HandlerSet;
  /** Default `buildAdvisorChains`. */
  buildChains?: (
    plans: readonly Extract<AdvisorModelPlan, { kind: "routed" }>[],
    set: HandlerSet
  ) => Promise<Map<string, AdvisorChainBuild>>;
  /** Default `shutdownAdvisorChains`. */
  shutdownChains?: (builds: Iterable<AdvisorChainBuild>) => Promise<void>;
}

/** Presence only: the resolved value is tested and dropped here, never returned or printed. */
async function anthropicKeyPresent(): Promise<boolean> {
  return Boolean(await resolveAdvisorCredential("anthropic"));
}

/**
 * Gather the facts for this launch and decide. Returns `null` when `--advisor`
 * was not given — the advisor is opt-in per launch (N1), and this reads only
 * the parsed CLI config, never stored config.
 *
 * Planning and building run only when the launch survives the refusals that
 * need no planning, and strictly in order: every member's plan (panel, then
 * collector, each in its own trace span), then every routed member's chain. A
 * refusal shuts down every handler that was built, so nothing outlives it.
 */
export async function evaluateAdvisorStartup(
  config: ClaudishConfig,
  toolEnv: AdvisorToolEnv,
  childEnv: Record<string, string | undefined> = process.env,
  deps: AdvisorStartupDeps = {}
): Promise<AdvisorStartupDecision | null> {
  if (!config.advisor) return null;

  const panel = config.advisorModels ?? [];
  const collector = config.advisorCollector ?? null;
  const mainModels = mainModelSpecs(config).map(resolveMainModelFact);

  const early = refusalBeforeCredentials({ childEnv, mainModels, panel });
  if (early) return { kind: "refuse", reason: early };

  const childAuth = deps.childAuth ?? childAuthControl(config, childEnv as NodeJS.ProcessEnv);
  const planDeps: PlanAdvisorDeps = {
    childAuth,
    anthropicKeyPresent: deps.anthropicKeyPresent ?? anthropicKeyPresent,
  };
  const plan = deps.plan ?? planAdvisorModel;

  const panelPlans: AdvisorModelPlan[] = [];
  for (const [i, spec] of panel.entries()) {
    panelPlans.push(
      await traceSpan(`startup:advisor-plan:panel:${i}`, () => plan(spec, "panel", planDeps))
    );
  }
  const collectorPlan = collector
    ? await traceSpan("startup:advisor-plan:collector:0", () =>
        plan(collector, "collector", planDeps)
      )
    : null;

  const routed = [...panelPlans, ...(collectorPlan ? [collectorPlan] : [])].filter(
    (p): p is Extract<AdvisorModelPlan, { kind: "routed" }> => p.kind === "routed"
  );
  const set =
    deps.createHandlerSet?.() ??
    createHandlerSet({
      requestRole: "advisor",
      // No token file is written for this set, so the port is never read.
      port: 0,
      isInteractive: config.interactive,
      // The notice describes each member; an `[Auto-route]` line would repeat it.
      quiet: true,
    });
  const builds =
    routed.length > 0
      ? await traceSpan("startup:advisor-build", () =>
          (deps.buildChains ?? buildAdvisorChains)(routed, set)
        )
      : new Map<string, AdvisorChainBuild>();

  const decision = decideAdvisorStartup({
    panel,
    collector,
    collectorDefaulted: config.advisorCollectorDefaulted === true,
    mainModels,
    childEnv,
    toolEnv,
    panelPlans,
    collectorPlan,
    builds,
    childAuth,
  });
  if (decision.kind === "refuse") {
    await (deps.shutdownChains ?? shutdownAdvisorChains)(builds.values());
  }
  return decision;
}