Skip to content

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

120 KB
Raw Blame
/**
 * Advisor-tool transformer for NativeHandler (monitor mode).
 *
 * PURPOSE — experimental
 * ======================
 * When the client sends `{type: "advisor_20260301", name: "advisor", model: ...}`
 * in `tools[]`, optionally replace it with a regular tool definition named
 * "advisor" so we can observe whether Sonnet still calls it as a normal tool.
 *
 * This is Stage 1 of the advisor-replacement experiment: detection only.
 * No tool loop, no third-party model routing. We just want to see whether
 * the executor still emits `tool_use` for `advisor` when the server-tool
 * version is gone.
 *
 * ENABLING
 * ========
 * Opt-in via env var:
 *
 *   export CLAUDISH_SWAP_ADVISOR=1         # swap tool + strip beta header
 *   export CLAUDISH_SWAP_ADVISOR_LOG=/tmp/advisor-swap.log  # optional log path
 *
 * When unset, this module is a no-op and the proxy behaves as before.
 *
 * STATE AND PROVENANCE (P2, P7, P8)
 * =================================
 * - Pending advisor calls are keyed by Claude Code session, then by tool-use
 *   id, and are RETAINED after their advice is delivered (see
 *   `NO_SESSION_BUCKET` and `markAdvisorCallConsumed`).
 * - Every tool_result that does not carry real advice from a named model is
 *   produced through one of the stub paths in `ADVISOR_STUB_PATHS`, and the
 *   advisor log records which one (`advisor_call`, `advisor_rewrite`).
 * - Failures reach the model as plain text naming the model and the reason,
 *   with `is_error: true`, and raise one warning per call via `logStderr`.
 */

import { appendFileSync } from "node:fs";
import type { Context } from "hono";
import { credentials } from "../auth/credentials/authority.js";
import type { ChildAuthControl, ChildAuthSource } from "../child-auth-types.js";
import { getAlwaysOnLogPath, getLogFilePath, log, logStderr } from "../logger.js";
import { resolveConnection } from "../providers/connection-resolver.js";
import type { KnownWire, WireApi } from "../providers/connection-wire.js";
import { getProviderByName } from "../providers/provider-definitions.js";
import { mergeWireHeaders, shapeRequestFromWire } from "../providers/wire-request.js";
import {
  acquireSigningLease,
  redactExactValues,
  redactForClient,
  redactSigningValues,
} from "../redact.js";
import type { StatsEvent } from "../stats-otlp.js";
import { recordStats } from "../stats.js";
import { isBillingHeaderText } from "../transform.js";
import { ANTHROPIC_API_HOST, ANTHROPIC_MESSAGES_URL } from "./advisor-claude-route.js";
import {
  type AdvisorBilling,
  type AdvisorEmptyReason,
  type AdvisorModelPlan,
  type AdvisorPanelGateway,
  type AdvisorPanelResult,
  type AdvisorTurn,
  type ExtractedAdvice,
  buildAdvisorPanelPayload,
  describeAdvisorRefusal,
  extractAdvice,
  hopLabel,
} from "./advisor-route-plan.js";
import { extractProviderMessage, extractUpstreamStatus } from "./shared/anthropic-error.js";
import { addSigningSecrets, credentialValuesFromRequest } from "./shared/call-context.js";
import { calculateCost } from "./shared/remote-provider-types.js";

const ADVISOR_SERVER_TOOL_TYPE = "advisor_20260301";
const ADVISOR_BETA_FLAG = "advisor-tool-2026-03-01";

export interface AdvisorSwapConfig {
  enabled: boolean;
  logPath?: string;
  /** When true, include entire request bodies in the log — large but useful for debugging the tool_result round-trip. */
  dumpBodies?: boolean;
  models?: string[];
  collector?: string | null;
}

export function loadAdvisorSwapConfig(
  cliModels?: string[],
  cliCollector?: string | null
): AdvisorSwapConfig {
  return {
    enabled: process.env.CLAUDISH_SWAP_ADVISOR === "1" || (cliModels?.length ?? 0) > 0,
    logPath: process.env.CLAUDISH_SWAP_ADVISOR_LOG,
    dumpBodies: process.env.CLAUDISH_SWAP_ADVISOR_DUMP === "1",
    models: cliModels,
    collector: cliCollector ?? undefined,
  };
}

interface AdvisorInfo {
  /** The original server-tool definition we removed. */
  originalTool: Record<string, unknown>;
  /** The regular-tool definition we replaced it with. */
  regularTool: Record<string, unknown>;
  /** Original value of the anthropic-beta header (for possible restoration). */
  originalBetaHeader?: string;
  /** Beta header after stripping advisor-tool-2026-03-01. */
  strippedBetaHeader?: string;
}

/**
 * Mutates `payload.tools` in place: finds `advisor_20260301` and replaces it
 * with a regular tool of the same name. Also returns metadata describing
 * what we changed (for logging).
 *
 * Returns `null` if the payload had no advisor server tool (nothing to do).
 */
export function swapAdvisorToolInBody(payload: Record<string, unknown>): AdvisorInfo | null {
  const tools = payload.tools;
  if (!Array.isArray(tools)) return null;

  const idx = tools.findIndex(
    (t) => t && typeof t === "object" && (t as any).type === ADVISOR_SERVER_TOOL_TYPE
  );
  if (idx < 0) return null;

  const originalTool = tools[idx] as Record<string, unknown>;
  const originalName = (originalTool.name as string) || "advisor";
  const originalAdvisorModel = (originalTool.model as string) || "unknown";

  // Regular tool definition. We deliberately keep the same name ("advisor")
  // so we can compare behavior before/after the swap.
  //
  // The description is longer than strictly necessary because the native
  // server-tool has trained behavior baked into the model — a regular tool
  // with the same name does NOT inherit that training, so we compensate
  // with more explicit prompting.
  const regularTool: Record<string, unknown> = {
    name: originalName,
    description:
      "Consult a stronger advisor model for strategic guidance on complex decisions. " +
      "Call this tool when: (a) facing an architectural or design decision with " +
      "multiple valid approaches, (b) stuck after 2+ failed attempts, (c) about to " +
      "make an irreversible change, or (d) when you believe the task is complete " +
      "and want verification. Takes no arguments; the advisor will read the full " +
      "conversation history.",
    input_schema: {
      type: "object",
      properties: {},
      additionalProperties: false,
    },
  };

  tools[idx] = regularTool;

  return {
    originalTool,
    regularTool,
    // eslint-disable-next-line @typescript-eslint/no-unused-expressions
    ...{ _note: `replaced advisor_20260301 (advisor model: ${originalAdvisorModel})` },
  } as AdvisorInfo;
}

/**
 * Removes `advisor-tool-2026-03-01` from a comma-separated anthropic-beta
 * header value. Returns `undefined` if the header had no advisor beta flag.
 */
export function stripAdvisorBeta(betaHeader: string | undefined): {
  stripped: string | undefined;
  changed: boolean;
} {
  if (!betaHeader) return { stripped: betaHeader, changed: false };
  const parts = betaHeader
    .split(",")
    .map((s) => s.trim())
    .filter((s) => s.length > 0);
  const filtered = parts.filter((p) => p !== ADVISOR_BETA_FLAG);
  if (filtered.length === parts.length) {
    return { stripped: betaHeader, changed: false };
  }
  return {
    stripped: filtered.length > 0 ? filtered.join(",") : undefined,
    changed: true,
  };
}

/** Prefix of the debug-log line that mirrors each advice-origin record. */
export const ADVISOR_ORIGIN_LOG_PREFIX = "[advisor-origin]";

/** The P7 records that also go to the debug log (`--debug-claudish`). */
const ORIGIN_RECORD_KINDS: ReadonlySet<string> = new Set([
  "advisor_call",
  "advisor_collector_call",
  "advisor_rewrite",
]);

/**
 * Defence in depth for EVERY sink a record reaches — the advisor log file and
 * the debug-log mirror. The records carry no key or header field by
 * construction; `reason` quotes the provider's own error body, and some
 * providers echo the key they rejected. The file outlives the session, so it
 * is the sink that most needs this (it was previously written raw).
 *
 * The replacements only ever shorten a run of key characters inside a JSON
 * string value — none of `"`, `\` or a structural character is produced — so
 * the scrubbed line is still valid JSON.
 */
/** What a redacted credential is replaced with, in every sink and in model text. */
const REDACTED = "[redacted]";

function scrubSecrets(text: string): string {
  return text
    .replace(/Bearer\s+[A-Za-z0-9._~+/=-]{8,}/gi, `Bearer ${REDACTED}`)
    .replace(/\bsk-[A-Za-z0-9_-]{8,}/g, REDACTED)
    .replace(/\bAIza[0-9A-Za-z_-]{20,}/g, REDACTED)
    .replace(/\bxai-[A-Za-z0-9_-]{16,}/g, REDACTED);
}

/**
 * Below this length a "secret" is not distinctive enough to redact BY VALUE:
 * an empty or one-character key would match everywhere and shred the message.
 * A real credential is far longer; a short one is caught by shape, or not at all.
 */
const MIN_REDACTABLE_SECRET_LENGTH = 8;

/**
 * THE sanitiser for provider-controlled text, applied ONCE before the text
 * enters an `AdvisorModelOutcome` — so the model text, the terminal warning and
 * every log sink all carry the same sanitised value. It used to be applied only
 * to the log line, and the reason went RAW into the tool_result the MAIN MODEL
 * reads and into the terminal: a panel endpoint that echoes the key it rejected
 * ("Incorrect API key provided: sk-…") sent that key across a vendor boundary.
 *
 * Two layers:
 *   1. BY VALUE — the exact credentials presented on THIS call. Nothing else can
 *      recognise a key with no recognisable shape (a bare uuid, an internal
 *      token), and this is the only text where such a key can appear at all.
 *   2. BY SHAPE — the known key formats (`scrubSecrets`), for a credential this
 *      call did not present: a key quoted by the provider from its own state, or
 *      one a proxy in between added.
 *
 * Replacements only shorten a run of key characters, so a JSON-serialized record
 * stays valid JSON after `scrubSecrets` runs over it a second time in
 * `logAdvisorEvent` (defence in depth: a record may carry text from elsewhere).
 */
export function sanitizeAdvisorReason(
  text: string,
  secretValues: Iterable<string | undefined> = []
): string {
  const values: string[] = [];
  for (const secret of secretValues) {
    const value = secret?.trim();
    if (value && value.length >= MIN_REDACTABLE_SECRET_LENGTH) values.push(value);
  }
  // The registry's matcher: verbatim, JSON-escaped (once and twice) and
  // URL-encoded forms, longest first. A plain split missed an escaped echo.
  return scrubSecrets(redactExactValues(text, values));
}

/**
 * Appends a structured log entry to the configured advisor-swap log file
 * (`CLAUDISH_SWAP_ADVISOR_LOG`); a no-op for the file when no path is set.
 *
 * The origin records (`advisor_call`, `advisor_collector_call`,
 * `advisor_rewrite`) are ALSO written, one compact JSON line each after
 * `[advisor-origin]`, to claudish's debug log whenever it is on
 * (`--debug-claudish`), so a real run can be checked from the debug log alone.
 *
 * The record is serialized and scrubbed ONCE, and the same scrubbed line goes
 * to every sink. The file used to get the raw record while only the debug
 * mirror was scrubbed, so a provider error body that echoed a key landed in
 * clear text in a file that outlives the session.
 *
 * ORIGIN RECORDS DO NOT DEPEND ON DEBUG MODE. Provenance is what the design
 * promises for EVERY advisor call, so `advisor_call`,
 * `advisor_collector_call` and `advisor_rewrite` are appended to claudish's
 * always-on log (`~/.claudish/logs/claudish_*.log`, `--log-off` turns it off)
 * as well. They used to be written only with `--debug-claudish` or an explicit
 * `CLAUDISH_SWAP_ADVISOR_LOG`, so an ordinary run kept no per-call record at
 * all. The other kinds — marker greps, body dumps — remain opt-in noise.
 */
export function logAdvisorEvent(cfg: AdvisorSwapConfig, event: Record<string, unknown>): void {
  const ts = new Date().toISOString();
  const record = { ts, ...event };
  let line: string;
  try {
    // The exact-value registry first (every signing value a live request
    // holds), then the shape rules. `appendLine` writes the advisor log and the
    // always-on log directly, not through `log()`, so this is their only pass.
    line = scrubSecrets(redactSigningValues(JSON.stringify(record)));
  } catch {
    // a record that will not serialize is a logging problem only
    return;
  }
  if (typeof event.kind === "string" && ORIGIN_RECORD_KINDS.has(event.kind)) {
    if (getLogFilePath() !== null) log(`${ADVISOR_ORIGIN_LOG_PREFIX} ${line}`);
    appendLine(getAlwaysOnLogPath(), `[${ts}] ${ADVISOR_ORIGIN_LOG_PREFIX} ${line}`);
  }
  appendLine(cfg.logPath, line);
}

/** Appends one complete line to `path`, or does nothing. Never throws. */
function appendLine(path: string | null | undefined, line: string): void {
  if (!path) return;
  try {
    appendFileSync(path, `${line}\n`);
  } catch {
    // silent — don't break the proxy if the log file is unwritable
  }
}

/**
 * Scans a chunk of raw SSE bytes for advisor-related activity and records
 * any hits to the log file. Call this once per streamed chunk.
 *
 * NOT stateless: SSE frames are reassembled across chunk boundaries (see
 * `SseFrameBuffer`) before they are parsed. This entry point shares ONE
 * module-level buffer; a caller that owns a stream should prefer
 * `createAdvisorStreamScanner`, which gives the stream its own.
 *
 * Also extracts advisor `tool_use.id`s and records them as pending calls in
 * `sessionId`'s bucket (or `NO_SESSION_BUCKET` when it is absent) so that
 * subsequent inbound requests containing tool_result blocks for those ids can
 * be recognized and rewritten (Stage 2).
 */
export function recordAdvisorEventsFromChunk(
  cfg: AdvisorSwapConfig,
  chunkText: string,
  sessionId?: string
): void {
  // Regardless of logPath, always try to extract advisor tool_use ids —
  // Stage 2 rewrite depends on them even when no log file is configured.
  extractAdvisorToolUseIds(chunkText, streamFrameBuffer, sessionId);
  logAdvisorMarkers(cfg, chunkText);
}

/**
 * Advisor tap for a NON-STREAMING response: the parsed JSON body, whose
 * `content[]` carries `{type:"tool_use", name:"advisor", id:...}` blocks.
 * A non-stream response is NOT a `content_block_start`, so the SSE path
 * above would never see it.
 *
 * Prefer this over `recordAdvisorEventsFromChunk(cfg, JSON.stringify(body))`:
 * it reads the object structurally instead of re-serializing and grepping.
 */
export function recordAdvisorEventsFromResponseBody(
  cfg: AdvisorSwapConfig,
  body: unknown,
  sessionId?: string
): void {
  collectAdvisorIdsFromValue(body, 0, sessionId);
  if (!cfg.logPath) return;
  try {
    logAdvisorMarkers(cfg, JSON.stringify(body));
  } catch {
    // ignore — a body that will not serialize is a logging problem only
  }
}

/**
 * Byte-grep for markers worth flagging in the log. Stage 1 cares about
 * whether the executor emits a regular tool_use for "advisor" (which proves
 * the model still reaches for the advisor when the tool_type is regular).
 *
 * Logging only — id capture never depends on this.
 */
function logAdvisorMarkers(cfg: AdvisorSwapConfig, text: string): void {
  if (!cfg.logPath) return;
  const markers: Array<[string, string]> = [
    ['"name":"advisor"', "tool_use_for_advisor"],
    ['"type":"tool_use"', "any_tool_use"],
    ['"type":"server_tool_use"', "server_tool_use_unexpected"],
    ['"type":"advisor_tool_result"', "advisor_tool_result_unexpected"],
    ['"stop_reason":"tool_use"', "stop_reason_tool_use"],
    ['"stop_reason":"end_turn"', "stop_reason_end_turn"],
  ];
  for (const [needle, kind] of markers) {
    let i = 0;
    while (true) {
      i = text.indexOf(needle, i);
      if (i < 0) break;
      const ctx = text.slice(Math.max(0, i - 40), i + 160);
      logAdvisorEvent(cfg, { kind, needle, ctx });
      i += needle.length;
    }
  }
}

// ---------------------------------------------------------------------------
// Stub paths and provenance vocabulary (P7)
// ---------------------------------------------------------------------------

/**
 * Every path by which an advisor tool_result can reach the model WITHOUT real
 * advice from the named model. Numbering follows research.md §4, so a log
 * record's `stubPath` can be read against that table.
 *
 * S1 and S3 are the feature-off answer (legacy env-var mode, no panel) and
 * keep `is_error: false`. S2 and S4 to S9 are genuine failures and carry
 * `is_error: true` plus a textual reason. S10 is a call that was never
 * rewritten at all; it can only be observed on a later request.
 */
export const ADVISOR_STUB_PATHS = Object.freeze({
  /** Legacy `CLAUDISH_SWAP_ADVISOR=1` with no panel: the canary stub is delivered. */
  LEGACY_STUB: "S1",
  /**
   * A recorded call reached the rewrite with no prepared result, or its answer
   * could not be associated with it because the record was gone by the time the
   * answer arrived (`reportUnassociatedAdvisorResult`). Either way claudish
   * holds no result for a call it is answering: an internal error.
   */
  PREPARED_RESULT_MISSING: "S2",
  /** The canary text itself (`stubAdvisorAdvice`), the advisor-disabled answer. */
  DISABLED_STUB: "S3",
  /** A panel model answered HTTP 2xx with no extractable advice text. */
  PANEL_EMPTY: "S4",
  /** The Anthropic collector answered HTTP 2xx with no text block. */
  ANTHROPIC_COLLECTOR_EMPTY: "S5",
  /** A non-Anthropic collector answered HTTP 2xx with no advice text. */
  COLLECTOR_EMPTY: "S6",
  /** A panel model failed: non-2xx, network error, or timeout. */
  PANEL_ERROR: "S7",
  /** Every panel model failed, so there is no advice to deliver. */
  ALL_PANEL_FAILED: "S8",
  /** The collector failed: non-2xx, network error, or timeout. */
  COLLECTOR_FAILED: "S9",
  /** Claude Code's own `No such tool available: advisor` error was never rewritten. */
  NOT_REWRITTEN: "S10",
} as const);

export type AdvisorStubPath = (typeof ADVISOR_STUB_PATHS)[keyof typeof ADVISOR_STUB_PATHS];

/**
 * `upstream` — real, non-empty advice bytes from the named model.
 * `stub`     — claudish produced the text (a stub path ran).
 * `absent`   — no call was made at all.
 */
export type AdviceOrigin = "upstream" | "stub" | "absent";

/** Which observation `upstreamStatus` came from. */
export type UpstreamStatusSource = "error.upstream_status" | "http_status";

/** The tool_result delivered for one advisor call. */
export interface AdvisorToolResult {
  text: string;
  isError: boolean;
}

/** Marker that opens every failure report the model receives. */
const ADVISOR_ERROR_PREFIX = "[claudish advisor error]";

/** Closing sentence for failure reports: the text is not advice. */
const ADVISOR_ERROR_SUFFIX =
  "This tool result is an error report from the claudish proxy, not advice.";

/** Sends one user-visible advisor warning through the sanctioned diagnostic channel. */
function warnAdvisor(message: string): void {
  // logStderr, never console/stderr directly: while Claude Code owns the TTY,
  // logStderr routes to DiagOutput instead of tearing the TUI
  // (terminal-isolation.ts, logger.ts).
  logStderr(`[advisor] ${message}`);
}

// ---------------------------------------------------------------------------
// Stage 2: pending-call state + tool_result rewrite (P2)
// ---------------------------------------------------------------------------

/**
 * Bucket for advisor calls recorded from a request that carried NO Claude
 * Code session id (`metadata.user_id` absent, or not the JSON blob).
 *
 * The rule, a documented compromise (architecture.md §4 and §11):
 *   - RECORD: a response to a session-less request records into this bucket.
 *   - CONSUME: a request looks in ITS OWN session bucket first, then here. A
 *     session-less request looks only here.
 *   - ADOPT: when a request with a known session id consumes an entry found
 *     here, the entry moves into that session's bucket. So two known,
 *     different session ids can never both resolve the same entry.
 *
 * The fallback exists because the id can be absent on the record request and
 * present on the consume request. Keying strictly on it would split one
 * logical call across two buckets and lose the advice (stub path S10).
 */
export const NO_SESSION_BUCKET = "__no_session__";

/** One observed advisor tool_use, tracked until TTL or eviction. */
export interface PendingAdvisorCall {
  toolUseId: string;
  /** A Claude Code session id, or `NO_SESSION_BUCKET`. */
  sessionKey: string;
  recordedAt: number;
  /** Refreshed on every record or lookup; the TTL is measured from here. */
  lastSeenAt: number;
  /** Set once advice was delivered. The entry is RETAINED after this. */
  consumedAt?: number;
  /** The exact tool_result delivered first, replayed verbatim on later turns. */
  result?: AdvisorToolResult;
}

/**
 * Bounds on the pending-call state. Entries are NOT deleted on consume: the
 * tool-use id stays in the conversation history and Claude Code re-sends it
 * on every later turn, still carrying its own "No such tool" error. Deleting
 * it made turn two lose its advice (plan-review-v2 C4). So state is bounded by
 * eviction only: a per-session LRU cap, a session LRU cap, and a sliding TTL.
 */
export const ADVISOR_PENDING_LIMITS = Object.freeze({
  maxCallsPerSession: 256,
  maxSessions: 64,
  /** Sliding: an entry re-sent by an active conversation never expires. */
  ttlMs: 24 * 60 * 60 * 1000,
});

/** How often a full expiry sweep may run. Lookups check expiry inline anyway. */
const SWEEP_INTERVAL_MS = 60_000;

/** sessionKey → (toolUseId → call). Both maps are kept in LRU order. */
const pendingBySession = new Map<string, Map<string, PendingAdvisorCall>>();

let clock: () => number = Date.now;
let lastSweepAt = Number.NEGATIVE_INFINITY;

/** The tool name we track. Claudish keeps the client's own name on the swap. */
const ADVISOR_TOOL_NAME = "advisor";

/** Guard against a pathological (or hostile) nesting depth while walking JSON. */
const MAX_WALK_DEPTH = 32;

/**
 * Hard cap on the SSE reassembly buffer. A stream that never terminates an
 * event (malformed, or simply not SSE at all) must not grow it without limit;
 * past the cap we keep only the tail, which is where a frame boundary can
 * still appear.
 */
const MAX_SSE_BUFFER_CHARS = 256 * 1024;

function sessionKeyFor(sessionId?: string): string {
  return typeof sessionId === "string" && sessionId.length > 0 ? sessionId : NO_SESSION_BUCKET;
}

/**
 * How many panel calls are running for a tool-use id right now. Keyed by id
 * ALONE, not by (session, id): the state entry for an id can live in
 * `NO_SESSION_BUCKET` while the request running it has a session, so a
 * session-keyed test would fail to protect exactly the entry that is about to
 * be adopted. Maintained by `joinOrStartAdvisorCall`.
 */
const inFlightByToolUseId = new Map<string, number>();

/**
 * An id with a panel call IN FLIGHT. Such an entry is never evicted and never
 * expires: dropping it while its own advice is being fetched means
 * `markAdvisorCallConsumed` cannot associate the result, the model is handed a
 * claudish error instead of the advice that did arrive, and the log claims
 * `origin: "upstream"` for text the model never saw.
 */
function isCallInFlight(toolUseId: string): boolean {
  return (inFlightByToolUseId.get(toolUseId) ?? 0) > 0;
}

/** True when any call in `bucket` is in flight, which pins the whole bucket. */
function bucketHasInFlightCall(bucket: Map<string, PendingAdvisorCall>): boolean {
  for (const id of bucket.keys()) if (isCallInFlight(id)) return true;
  return false;
}

function isExpired(call: PendingAdvisorCall, now: number): boolean {
  if (isCallInFlight(call.toolUseId)) return false;
  return now - call.lastSeenAt > ADVISOR_PENDING_LIMITS.ttlMs;
}

function sweepExpiredIfDue(): void {
  const now = clock();
  if (now - lastSweepAt < SWEEP_INTERVAL_MS) return;
  lastSweepAt = now;
  for (const [key, bucket] of pendingBySession) {
    for (const [id, call] of bucket) {
      if (isExpired(call, now)) bucket.delete(id);
    }
    if (bucket.size === 0) pendingBySession.delete(key);
  }
}

/** Returns a bucket and marks it most-recently-used. */
function touchBucket(key: string): Map<string, PendingAdvisorCall> | undefined {
  const bucket = pendingBySession.get(key);
  if (!bucket) return undefined;
  pendingBySession.delete(key);
  pendingBySession.set(key, bucket);
  return bucket;
}

/**
 * Returns the bucket for `key`, creating it (and evicting the LRU session) if
 * needed. A session holding a call IN FLIGHT is skipped: the cap may be
 * exceeded for as long as that call runs, which is bounded by the panel and
 * collector timeouts, rather than losing the call's own state under it.
 */
function bucketForWrite(key: string): Map<string, PendingAdvisorCall> {
  const existing = touchBucket(key);
  if (existing) return existing;
  const bucket = new Map<string, PendingAdvisorCall>();
  pendingBySession.set(key, bucket);
  while (pendingBySession.size > ADVISOR_PENDING_LIMITS.maxSessions) {
    const evictable = [...pendingBySession].find(
      ([k, b]) => k !== key && !bucketHasInFlightCall(b)
    );
    if (!evictable) break;
    pendingBySession.delete(evictable[0]);
  }
  return bucket;
}

/**
 * Inserts `call` as most-recently-used, evicting the LRU entry past the cap —
 * skipping any entry whose panel call is in flight (see `isCallInFlight`).
 */
function putCall(bucket: Map<string, PendingAdvisorCall>, call: PendingAdvisorCall): void {
  bucket.delete(call.toolUseId);
  if (bucket.size >= ADVISOR_PENDING_LIMITS.maxCallsPerSession) {
    const oldest = [...bucket.keys()].find((id) => !isCallInFlight(id));
    if (oldest !== undefined) bucket.delete(oldest);
  }
  bucket.set(call.toolUseId, call);
}

function rememberAdvisorToolUseId(id: string, sessionId?: string): void {
  sweepExpiredIfDue();
  const key = sessionKeyFor(sessionId);
  const bucket = bucketForWrite(key);
  const now = clock();
  const existing = bucket.get(id);
  if (existing) {
    // Re-observed: keep its state (a delivered result must survive), refresh LRU.
    existing.lastSeenAt = now;
    putCall(bucket, existing);
    return;
  }
  putCall(bucket, { toolUseId: id, sessionKey: key, recordedAt: now, lastSeenAt: now });
  log(`[advisor] recorded advisor tool_use ${id} (session=${key})`);
}

/**
 * Resolves a tool-use id for a request: its own session bucket first, then
 * `NO_SESSION_BUCKET`. A session-less request consults only the fallback.
 * A hit refreshes the entry's TTL and LRU position.
 */
function lookupAdvisorCall(toolUseId: string, sessionId?: string): PendingAdvisorCall | undefined {
  sweepExpiredIfDue();
  const now = clock();
  const own = sessionKeyFor(sessionId);
  const keys = own === NO_SESSION_BUCKET ? [NO_SESSION_BUCKET] : [own, NO_SESSION_BUCKET];
  for (const key of keys) {
    const bucket = pendingBySession.get(key);
    const call = bucket?.get(toolUseId);
    if (!bucket || !call) continue;
    if (isExpired(call, now)) {
      bucket.delete(toolUseId);
      continue;
    }
    call.lastSeenAt = now;
    putCall(bucket, call);
    touchBucket(key);
    return call;
  }
  return undefined;
}

/**
 * The tracked call for `toolUseId` as seen from `sessionId`'s request, or
 * `undefined`. Follows the `NO_SESSION_BUCKET` lookup rule. A delivered call
 * carries its `result`, which callers replay instead of re-fetching.
 */
export function getAdvisorCall(
  toolUseId: string,
  sessionId?: string
): Readonly<PendingAdvisorCall> | undefined {
  return lookupAdvisorCall(toolUseId, sessionId);
}

/**
 * Marks a tracked call consumed and stores the tool_result delivered for it.
 * The entry is RETAINED so that later turns, which re-send the same id, get
 * the same text back. An entry found in `NO_SESSION_BUCKET` by a request with
 * a known session id is adopted into that session's bucket.
 *
 * Returns false when the id is not tracked for this request.
 */
export function markAdvisorCallConsumed(
  toolUseId: string,
  result: AdvisorToolResult,
  sessionId?: string
): boolean {
  const call = lookupAdvisorCall(toolUseId, sessionId);
  if (!call) return false;
  const own = sessionKeyFor(sessionId);
  if (call.sessionKey === NO_SESSION_BUCKET && own !== NO_SESSION_BUCKET) {
    pendingBySession.get(NO_SESSION_BUCKET)?.delete(toolUseId);
    call.sessionKey = own;
    putCall(bucketForWrite(own), call);
  }
  call.consumedAt ??= clock();
  call.result = result;
  return true;
}

/**
 * Panel calls currently RUNNING, keyed exactly as the pending state is: the
 * request's session key (`NO_SESSION_BUCKET` when it has none) and the
 * tool-use id.
 *
 * WHY: a delivered result is only visible once `markAdvisorCallConsumed` has
 * run, i.e. after the whole panel returned. Claude Code retrying a request
 * that carries the same advisor tool_result (socket reset, harness retry)
 * therefore used to find no cached result and run the ENTIRE panel a second
 * time — every panel model gets the full conversation again and the user pays
 * twice. The loop is awaited before the upstream request is sent, so the
 * window is the whole call: up to the panel timeout plus the collector
 * timeout. The second request now joins the first call instead of starting
 * one; after completion the cached-result path serves later turns as before.
 *
 * Entries are removed in a `finally`, so this map holds only calls actually in
 * flight. It is bounded like the pending state (the same per-session and
 * session caps, multiplied) in case a pathological caller outruns that: past
 * the cap the oldest entries are dropped, which only costs a later retry its
 * de-duplication.
 */
const inFlightAdvisorCalls = new Map<string, Promise<AdvisorToolResult>>();

const MAX_IN_FLIGHT_ADVISOR_CALLS =
  ADVISOR_PENDING_LIMITS.maxSessions * ADVISOR_PENDING_LIMITS.maxCallsPerSession;

/**
 * Runs `start` for (session, toolUseId), or joins the run already in flight
 * for that key.
 *
 * `joined: true` means the returned promise belongs to ANOTHER request: this
 * caller started nothing and pays for nothing. The owner is responsible for
 * `markAdvisorCallConsumed`, so a joiner reads the delivered result from the
 * pending state as any later turn does — or from the promise, which resolves
 * to the same `AdvisorToolResult`.
 *
 * A rejection is not swallowed: it reaches every waiter exactly as it reached
 * the owner. The entry is gone by then, so a caller that would rather run its
 * own call after someone else's failure can simply call this again.
 */
export function joinOrStartAdvisorCall(
  toolUseId: string,
  sessionId: string | undefined,
  start: () => Promise<AdvisorToolResult>
): { promise: Promise<AdvisorToolResult>; joined: boolean } {
  const key = `${sessionKeyFor(sessionId)}\u0000${toolUseId}`;
  const existing = inFlightAdvisorCalls.get(key);
  if (existing) return { promise: existing, joined: true };

  while (inFlightAdvisorCalls.size >= MAX_IN_FLIGHT_ADVISOR_CALLS) {
    const oldest = inFlightAdvisorCalls.keys().next().value;
    if (oldest === undefined) break;
    inFlightAdvisorCalls.delete(oldest);
  }

  // The id counts as in flight from BEFORE `start()` runs, so nothing its own
  // first await lets in can evict the state entry it is about to fill.
  inFlightByToolUseId.set(toolUseId, (inFlightByToolUseId.get(toolUseId) ?? 0) + 1);
  // `.finally` (never a `try/finally` inside the IIFE) so the cleanup cannot
  // run before `promise` is assigned: its callback is always a microtask.
  // The refcount is released unconditionally — the map entry may already have
  // been dropped by the cap loop above, and a leaked count would pin an entry
  // for the life of the process.
  const release = () => {
    const left = (inFlightByToolUseId.get(toolUseId) ?? 1) - 1;
    if (left > 0) inFlightByToolUseId.set(toolUseId, left);
    else inFlightByToolUseId.delete(toolUseId);
  };
  let started: Promise<AdvisorToolResult>;
  try {
    started = start();
  } catch (err) {
    // A synchronous throw would otherwise pin the id in flight forever.
    release();
    throw err;
  }
  const promise: Promise<AdvisorToolResult> = started.finally(() => {
    release();
    if (inFlightAdvisorCalls.get(key) === promise) inFlightAdvisorCalls.delete(key);
  });
  inFlightAdvisorCalls.set(key, promise);
  return { promise, joined: false };
}

/** Test/debug: the keys of the panel calls currently in flight. */
export function _debug_getInFlightAdvisorCallKeys(): string[] {
  return [...inFlightAdvisorCalls.keys()];
}

/**
 * Reassembles SSE events across chunk boundaries.
 *
 * Anthropic splits `content_block_start` across byte boundaries, so a
 * per-chunk `JSON.parse` of `data:` lines misses exactly the frames we care
 * about. Buffer until an event terminator (`\n\n`, or `\r\n\r\n`), then hand
 * the complete event out.
 */
class SseFrameBuffer {
  private buf = "";

  /** Appends a chunk and returns every COMPLETE event now available. */
  take(chunkText: string): string[] {
    this.buf += chunkText;
    const events: string[] = [];
    while (true) {
      const lf = this.buf.indexOf("\n\n");
      const crlf = this.buf.indexOf("\r\n\r\n");
      // Earliest terminator wins; -1 means "not present".
      let idx = -1;
      let width = 2;
      if (crlf >= 0 && (lf < 0 || crlf < lf)) {
        idx = crlf;
        width = 4;
      } else if (lf >= 0) {
        idx = lf;
      }
      if (idx < 0) break;
      events.push(this.buf.slice(0, idx));
      this.buf = this.buf.slice(idx + width);
    }
    if (this.buf.length > MAX_SSE_BUFFER_CHARS) {
      this.buf = this.buf.slice(-MAX_SSE_BUFFER_CHARS);
    }
    return events;
  }

  reset(): void {
    this.buf = "";
  }
}

/**
 * One module-level buffer, shared by every stream that reaches the legacy
 * per-chunk entry point `recordAdvisorEventsFromChunk`.
 *
 * Two concurrent streams can interleave here and produce a spliced "event".
 * That degrades gracefully rather than losing the id: a spliced event fails
 * `JSON.parse` and falls through to the regex fallback below, which is the
 * same byte-grep this code used to be. Stream owners use
 * `createAdvisorStreamScanner` instead.
 */
const streamFrameBuffer = new SseFrameBuffer();

/** A per-stream advisor tap: its own SSE buffer, bound to one session. */
export interface AdvisorStreamScanner {
  /** Feed one decoded chunk of the response stream. */
  push(chunkText: string): void;
}

/**
 * Creates an advisor tap for ONE response stream. It owns its SSE reassembly
 * buffer, so concurrent streams cannot splice frames into each other, and it
 * records ids into `sessionId`'s bucket (`NO_SESSION_BUCKET` when absent).
 * Capture logic is identical to `recordAdvisorEventsFromChunk`.
 */
export function createAdvisorStreamScanner(
  cfg: AdvisorSwapConfig,
  sessionId?: string
): AdvisorStreamScanner {
  const frames = new SseFrameBuffer();
  return {
    push(chunkText: string): void {
      extractAdvisorToolUseIds(chunkText, frames, sessionId);
      logAdvisorMarkers(cfg, chunkText);
    },
  };
}

/**
 * Records the id of every advisor tool_use block visible in this chunk.
 *
 * Structural first, regex only as a fallback. The id is captured whatever it
 * looks like: `toolu_*` is an ANTHROPIC spelling, and the advisor swap must
 * work behind every parser. `openai-sse.ts` mints `call_*` from the upstream
 * or synthesizes `tool_<ts>_<idx>`, and it is the DEFAULT stream format
 * (`base-api-format.ts`), so a prefix test silently captures nothing for
 * every foreign main model.
 */
function extractAdvisorToolUseIds(
  chunkText: string,
  frames: SseFrameBuffer,
  sessionId?: string
): void {
  // Whole-body JSON (the non-streaming branch hands us one). If it parses we
  // have read it structurally and there is nothing for the regex to add.
  if (parseAdvisorIdsFromJsonText(chunkText, sessionId)) return;

  // SSE: parse each COMPLETE event; a frame that will not parse falls back to
  // the regex so we never capture less than the byte-grep did.
  let sawCompleteFrame = false;
  for (const event of frames.take(chunkText)) {
    sawCompleteFrame = true;
    if (!scanSseEventForAdvisorIds(event, sessionId)) matchAdvisorIdsByRegex(event, sessionId);
  }

  // No complete frame yet — either a fragment (the rest is still coming and
  // will be parsed then) or text that is not SSE at all, e.g. a bare
  // `"content_block":{...}` snippet. Grep it so neither case is dropped.
  if (!sawCompleteFrame) matchAdvisorIdsByRegex(chunkText, sessionId);
}

/**
 * Reads one complete SSE event structurally: concatenates its `data:` lines
 * per the SSE spec, parses the result and walks it for advisor tool_use
 * blocks. Returns false when the payload did not parse, which is the
 * caller's signal to fall back to the regex.
 */
function scanSseEventForAdvisorIds(rawEvent: string, sessionId?: string): boolean {
  const dataLines: string[] = [];
  for (const line of rawEvent.split(/\r?\n/)) {
    if (!line.startsWith("data:")) continue;
    dataLines.push(line.slice(5).trimStart());
  }
  if (dataLines.length === 0) return false;
  const payload = dataLines.join("\n").trim();
  // A comment/heartbeat frame or the terminator carries nothing to capture,
  // but it is not a parse FAILURE either — no regex fallback needed.
  if (!payload || payload === "[DONE]") return true;
  return parseAdvisorIdsFromJsonText(payload, sessionId);
}

/** Parses `text` as JSON and walks it. Returns false when it is not JSON. */
function parseAdvisorIdsFromJsonText(text: string, sessionId?: string): boolean {
  const trimmed = text.trimStart();
  if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) return false;
  let parsed: unknown;
  try {
    parsed = JSON.parse(trimmed);
  } catch {
    return false;
  }
  collectAdvisorIdsFromValue(parsed, 0, sessionId);
  return true;
}

/**
 * Walks any parsed JSON value and records the id of every object that IS an
 * advisor tool_use block. Key order is irrelevant here, which is the point:
 * the old regex required `type`,`id`,`name` adjacent and in that order.
 *
 * Covers both shapes with one walk: the streamed
 * `content_block_start.content_block` and the non-streamed `content[]` entry.
 */
function collectAdvisorIdsFromValue(value: unknown, depth: number, sessionId?: string): void {
  if (value === null || typeof value !== "object" || depth > MAX_WALK_DEPTH) return;
  if (Array.isArray(value)) {
    for (const item of value) collectAdvisorIdsFromValue(item, depth + 1, sessionId);
    return;
  }
  const obj = value as Record<string, unknown>;
  if (
    obj.type === "tool_use" &&
    obj.name === ADVISOR_TOOL_NAME &&
    typeof obj.id === "string" &&
    obj.id.length > 0
  ) {
    rememberAdvisorToolUseId(obj.id, sessionId);
  }
  for (const nested of Object.values(obj)) collectAdvisorIdsFromValue(nested, depth + 1, sessionId);
}

/**
 * Prefix-agnostic fallback for payloads that do not parse — a truncated
 * frame, a spliced one, or a raw fragment. `[^}]*?` keeps every match inside
 * a single JSON object, so an id belonging to an enclosing object (a
 * `message.id`, say) can never be picked up for the advisor block nested
 * inside it.
 */
const ADVISOR_ID_PATTERNS: RegExp[] = [
  // type → id → name. The canonical fallback from the design doc.
  /"type"\s*:\s*"tool_use"[^}]*?"id"\s*:\s*"([^"]+)"[^}]*?"name"\s*:\s*"advisor"/g,
  // name → id, whatever sits between them (input may be serialized first).
  /"name"\s*:\s*"advisor"[^}]*?"id"\s*:\s*"([^"]+)"/g,
  // id → name with no `type` ahead of them. Adjacency is required precisely
  // because `type` is not there to prove the id belongs to this block.
  /"id"\s*:\s*"([^"]+)"\s*,\s*"name"\s*:\s*"advisor"/g,
];

function matchAdvisorIdsByRegex(text: string, sessionId?: string): void {
  for (const re of ADVISOR_ID_PATTERNS) {
    re.lastIndex = 0;
    let m: RegExpExecArray | null;
    // biome-ignore lint/suspicious/noAssignInExpressions: canonical RegExp.exec() iteration idiom
    while ((m = re.exec(text)) !== null) {
      rememberAdvisorToolUseId(m[1], sessionId);
    }
  }
}

/**
 * Test helper. With `sessionId`, the ids in that session's bucket (pass
 * `NO_SESSION_BUCKET` for the fallback). Without it, every tracked id across
 * all buckets, de-duplicated.
 */
export function _debug_getTrackedAdvisorIds(sessionId?: string): string[] {
  if (sessionId !== undefined) {
    return [...(pendingBySession.get(sessionKeyFor(sessionId))?.keys() ?? [])];
  }
  const all = new Set<string>();
  for (const bucket of pendingBySession.values()) for (const id of bucket.keys()) all.add(id);
  return [...all];
}

/** Test helper — the session bucket keys, least-recently-used first. */
export function _debug_getAdvisorSessionKeys(): string[] {
  return [...pendingBySession.keys()];
}

/** Test helper — replaces the clock used for TTL; `null` restores `Date.now`. */
export function _debug_setAdvisorClock(now: (() => number) | null): void {
  clock = now ?? Date.now;
  lastSweepAt = Number.NEGATIVE_INFINITY;
}

/**
 * Reset ALL advisor state: pending calls in every bucket, the shared SSE
 * reassembly buffer, the S10 report memory and the clock. Intended for tests.
 */
export function _debug_resetTrackedAdvisorIds(): void {
  pendingBySession.clear();
  inFlightAdvisorCalls.clear();
  inFlightByToolUseId.clear();
  streamFrameBuffer.reset();
  reportedUnrecorded.clear();
  servedUnlikePlan.clear();
  clock = Date.now;
  lastSweepAt = Number.NEGATIVE_INFINITY;
}

/**
 * Supplies the tool_result for an advisor tool_use_id.
 *
 * - a `string` is delivered as advice and CLEARS `is_error` (the original
 *   contract, kept for the legacy stub and existing callers);
 * - an `AdvisorToolResult` sets `is_error` from `isError`;
 * - `undefined` leaves that block untouched.
 */
export type AdvisorResultSupplier = (toolUseId: string) => string | AdvisorToolResult | undefined;

/**
 * Scans a payload for `tool_result` blocks whose tool_use_id we recorded as
 * an advisor call (for this request's session, see `NO_SESSION_BUCKET`), and
 * rewrites them in place:
 *   - `content` → `[{type:"text", text: <supplied text>}]`
 *   - `is_error` → cleared for a string or `isError:false`, set for `isError:true`
 *
 * Returns the list of rewritten tool_use_ids (empty if nothing changed).
 */
export function rewriteAdvisorToolResults(
  payload: Record<string, unknown>,
  /**
   * Must be synchronous. Callers that need an async model call pre-fetch the
   * result keyed by tool_use_id before invoking this function.
   */
  getAdviceFor: AdvisorResultSupplier,
  sessionId?: string
): string[] {
  const messages = payload.messages;
  if (!Array.isArray(messages)) return [];
  const rewritten: string[] = [];

  for (const msg of messages) {
    if (!msg || typeof msg !== "object") continue;
    if ((msg as any).role !== "user") continue;
    const content = (msg as any).content;
    if (!Array.isArray(content)) continue;

    for (const block of content) {
      if (!block || typeof block !== "object") continue;
      if ((block as any).type !== "tool_result") continue;
      const toolUseId = (block as any).tool_use_id;
      if (typeof toolUseId !== "string") continue;
      if (!lookupAdvisorCall(toolUseId, sessionId)) continue;

      const supplied = getAdviceFor(toolUseId);
      if (supplied === undefined) continue;
      const result: AdvisorToolResult =
        typeof supplied === "string" ? { text: supplied, isError: false } : supplied;
      // Rewrite in place.
      (block as any).content = [{ type: "text", text: result.text }];
      if (result.isError) {
        (block as any).is_error = true;
      } else if ((block as any).is_error) {
        // Clear the error flag Claude Code set for "No such tool".
        (block as any).is_error = false;
      }
      rewritten.push(toolUseId);
    }
  }
  return rewritten;
}

/**
 * Stub advisor: returns a canary string. Used during PoC to prove the
 * rewrite reached the executor without yet wiring up a real third-party
 * model. The canary string is intentionally distinctive so we can grep for
 * it in the executor's continuation. Stub path S3.
 */
export function stubAdvisorAdvice(toolUseId: string): string {
  return `CLAUDISH_ADVISOR_STUB_${toolUseId}: Evaluation mode — this advice was supplied by a claudish proxy stub. For the rate-limiter design, consider a hybrid: local token bucket per node for burst tolerance plus a central quota coordinator for cross-region fairness. Use the CAP tradeoff as your framing; expose availability vs accuracy knobs per tenant. The single most important decision is your failure mode: fail-open vs fail-closed.`;
}

/**
 * Legacy env-var mode (stub path S1): prepares the canary result for a call,
 * marks it consumed so later turns replay it, and writes the call's
 * `advisor_rewrite` record. `is_error` stays false — this is the feature-off
 * answer, not a failure.
 */
export function prepareLegacyStubResult(
  cfg: AdvisorSwapConfig,
  toolUseId: string,
  sessionId?: string
): AdvisorToolResult {
  const result: AdvisorToolResult = { text: stubAdvisorAdvice(toolUseId), isError: false };
  markAdvisorCallConsumed(toolUseId, result, sessionId);
  logAdvisorEvent(cfg, {
    kind: "advisor_rewrite",
    event: "advisor_rewrite",
    toolUseId,
    sessionId: sessionId ?? null,
    panel: [],
    originsByModel: {},
    // No model was called, so none failed (see logAdvisorCallOutcome).
    failedModels: [],
    collector: null,
    collectorOrigin: null,
    resultOrigin: "stub" satisfies AdviceOrigin,
    stubPath: ADVISOR_STUB_PATHS.LEGACY_STUB,
    isError: false,
  });
  return result;
}

/**
 * Stub path S2: the rewrite found a recorded call with no prepared result.
 * Unreachable by construction in NativeHandler; if it ever runs, the model is
 * told so in plain text instead of being handed a canary as advice.
 */
export function missingAdvisorResult(toolUseId: string): AdvisorToolResult {
  log(`[advisor] no prepared result for recorded call ${toolUseId} (stub path S2)`);
  warnAdvisor(`advisor call ${toolUseId}: claudish had no prepared result (internal error)`);
  return {
    text: `${ADVISOR_ERROR_PREFIX} claudish recorded advisor call ${toolUseId} but had no result prepared for it (internal error). ${ADVISOR_ERROR_SUFFIX}`,
    isError: true,
  };
}

// ---------------------------------------------------------------------------
// Stage 3: Multi-model advisor (--advisor flag)
// ---------------------------------------------------------------------------

/**
 * Scans payload for tool_result blocks whose tool_use_id is tracked as an
 * advisor call for this request (see `NO_SESSION_BUCKET`). Returns the list of
 * matching IDs without modifying the payload. Includes calls already consumed:
 * check `getAdvisorCall(id, sessionId)?.result` to tell a replay from a call
 * that still needs a fetch.
 */
export function findPendingAdvisorToolResults(
  payload: Record<string, unknown>,
  sessionId?: string
): string[] {
  const messages = payload.messages;
  if (!Array.isArray(messages)) return [];
  const found: string[] = [];
  for (const msg of messages) {
    if (!msg || typeof msg !== "object") continue;
    if ((msg as any).role !== "user") continue;
    const content = (msg as any).content;
    if (!Array.isArray(content)) continue;
    for (const block of content) {
      if (!block || typeof block !== "object") continue;
      if ((block as any).type !== "tool_result") continue;
      const toolUseId = (block as any).tool_use_id;
      if (typeof toolUseId === "string" && lookupAdvisorCall(toolUseId, sessionId)) {
        found.push(toolUseId);
      }
    }
  }
  return found;
}

/** Claude Code's own error for a tool it does not know. */
const NO_SUCH_ADVISOR_TOOL = /No such tool available:\s*advisor\b/;

/** (sessionKey, toolUseId) pairs already reported as S10, so each warns once. */
const reportedUnrecorded = new Set<string>();
const MAX_REPORTED_UNRECORDED = 1024;

function toolResultText(content: unknown): string {
  if (typeof content === "string") return content;
  if (!Array.isArray(content)) return "";
  return content
    .map((b: any) => (b && typeof b.text === "string" ? b.text : ""))
    .filter(Boolean)
    .join("\n");
}

/**
 * The tool_use ids in THIS payload that belong to an advisor tool_use block —
 * `{type:"tool_use", name:"advisor"}` in an assistant message. The same
 * structural test the capture path uses (`collectAdvisorIdsFromValue`), applied
 * to the conversation history Claude Code re-sends on every turn.
 *
 * This is the ONLY thing that may identify an advisor call in a payload, next
 * to claudish's own recorded state. The model's output is untrusted input: it
 * can contain any string, including claudish's and Claude Code's own error
 * phrases, so no detection may rest on text the model produced.
 */
export function advisorToolUseIdsInPayload(payload: Record<string, unknown>): Set<string> {
  const ids = new Set<string>();
  const messages = payload.messages;
  if (!Array.isArray(messages)) return ids;
  for (const msg of messages) {
    if (!msg || typeof msg !== "object") continue;
    const content = (msg as any).content;
    if (!Array.isArray(content)) continue;
    for (const block of content) {
      if (!block || typeof block !== "object") continue;
      const b = block as Record<string, unknown>;
      if (b.type !== "tool_use" || b.name !== ADVISOR_TOOL_NAME) continue;
      if (typeof b.id === "string" && b.id.length > 0) ids.add(b.id);
    }
  }
  return ids;
}

/**
 * Stub path S10: finds advisor tool_results still carrying Claude Code's
 * `No such tool available: advisor` error for an id this request's session
 * never recorded — an advisor call that was never rewritten. Run it AFTER the
 * rewrite. Each (session, id) is logged (`advisor_rewrite`, origin `absent`)
 * and warned about once. Returns the ids newly reported.
 *
 * STRUCTURE FIRST, TEXT ONLY AS CORROBORATION. The id must belong to an actual
 * advisor `tool_use` block in this payload. Matching the error phrase alone
 * made any tool that PRINTED the phrase mint an advisor record: observed live,
 * the model ran `rg -n "advisor" …` and its Bash tool_result produced a fake
 * S10 record and the user-visible warning "claudish never saw the advisor tool
 * call" for a Bash call id.
 */
export function reportUnrecordedAdvisorCalls(
  cfg: AdvisorSwapConfig,
  payload: Record<string, unknown>,
  sessionId?: string
): string[] {
  const messages = payload.messages;
  if (!Array.isArray(messages)) return [];
  const advisorIds = advisorToolUseIdsInPayload(payload);
  if (advisorIds.size === 0) return [];
  const reported: string[] = [];
  for (const msg of messages) {
    if (!msg || typeof msg !== "object" || (msg as any).role !== "user") continue;
    const content = (msg as any).content;
    if (!Array.isArray(content)) continue;
    for (const block of content) {
      if (!block || typeof block !== "object" || (block as any).type !== "tool_result") continue;
      const toolUseId = (block as any).tool_use_id;
      if (typeof toolUseId !== "string") continue;
      if (!advisorIds.has(toolUseId)) continue;
      if (!NO_SUCH_ADVISOR_TOOL.test(toolResultText((block as any).content))) continue;
      if (lookupAdvisorCall(toolUseId, sessionId)) continue;
      const memo = `${sessionKeyFor(sessionId)}\u0000${toolUseId}`;
      if (reportedUnrecorded.has(memo)) continue;
      if (reportedUnrecorded.size >= MAX_REPORTED_UNRECORDED) {
        const oldest = reportedUnrecorded.values().next().value;
        if (oldest !== undefined) reportedUnrecorded.delete(oldest);
      }
      reportedUnrecorded.add(memo);
      reported.push(toolUseId);

      const panel = cfg.models ?? [];
      logAdvisorEvent(cfg, {
        kind: "advisor_rewrite",
        event: "advisor_rewrite",
        toolUseId,
        sessionId: sessionId ?? null,
        panel,
        originsByModel: Object.fromEntries(panel.map((m) => [m, "absent" satisfies AdviceOrigin])),
        // No model was called — `resultOrigin: "absent"` is the signal here, and
        // counting never-called models as failures would inflate any audit.
        failedModels: [],
        collector: cfg.collector ?? null,
        collectorOrigin: cfg.collector ? ("absent" satisfies AdviceOrigin) : null,
        resultOrigin: "absent" satisfies AdviceOrigin,
        stubPath: ADVISOR_STUB_PATHS.NOT_REWRITTEN,
        isError: true,
      });
      log(`[advisor] call ${toolUseId} was never rewritten (stub path S10)`);
      warnAdvisor(
        `advisor call ${toolUseId} was not answered: claudish never saw the advisor tool call, so the model got "No such tool available: advisor"`
      );
    }
  }
  return reported;
}

export function convertToOpenAIMessages(
  anthropicMessages: any[]
): Array<{ role: string; content: string }> {
  return anthropicMessages
    .filter((m) => m.role === "user" || m.role === "assistant")
    .map((m) => ({
      role: m.role,
      content: extractBlocksAsText(m.content),
    }))
    .filter((m) => m.content.length > 0);
}

export function extractBlocksAsText(content: any): string {
  if (typeof content === "string") return content;
  if (!Array.isArray(content)) return "";
  return content
    .map((b: any) => {
      if (b.type === "text") return b.text;
      if (b.type === "tool_use") {
        const inputStr = JSON.stringify(b.input ?? {}).slice(0, 500);
        return `[Called tool: ${b.name} with input: ${inputStr}]`;
      }
      if (b.type === "tool_result") {
        const resultText =
          typeof b.content === "string"
            ? b.content.slice(0, 500)
            : Array.isArray(b.content)
              ? b.content
                  .filter((x: any) => x.type === "text")
                  .map((x: any) => x.text)
                  .join("\n")
                  .slice(0, 500)
              : "(binary)";
        return `[Tool result (${b.tool_use_id}): ${resultText}]`;
      }
      return "";
    })
    .filter(Boolean)
    .join("\n");
}

// ---------------------------------------------------------------------------
// What the PANEL is asked (the transcript, minus claudish's own plumbing)
// ---------------------------------------------------------------------------

/**
 * What the tool_result for the call BEING ANSWERED is replaced with.
 *
 * Claude Code has no local implementation of the function tool claudish swaps
 * in, so it answers its own tool_use with `Error: No such tool available:
 * advisor` and claudish replaces that on the way upstream. The panel, however,
 * was handed the transcript with the error still in it, and answered about the
 * error: run C returned 2964 bytes beginning "The requested workflow is
 * currently impossible because the runtime explicitly ret…", and in run B the
 * advisors scolded the main model for "passing {}". Neither is the question.
 *
 * The block is not deleted, because a tool_use with no tool_result is a
 * malformed transcript for several of the panel endpoints. It is neutralised.
 */
const ADVISOR_PLUMBING_MARKER =
  "(handled by the claudish proxy — this advisor call is what you are being asked to answer; there is no local tool output)";

/** Fields an advisor `input` object may carry the question in, most specific first. */
const ADVISOR_QUESTION_FIELDS = [
  "question",
  "prompt",
  "query",
  "request",
  "task",
  "topic",
  "context",
  "input",
  "text",
] as const;

/** Cap on the question text quoted back to the panel. */
const MAX_ADVISOR_QUESTION_CHARS = 4000;

/**
 * The question an advisor `tool_use` asked, from its own `input`, or null when
 * it carries none.
 *
 * The swapped tool declares an EMPTY input schema ("takes no arguments; the
 * advisor will read the full conversation history"), so `{}` is the expected
 * case and not an error — it means "advise on the conversation", which
 * `advisorQuestionMessage` then says in words. A model that ignores the schema
 * and passes a field anyway is taken at its word: that field IS the question.
 */
export function describeAdvisorQuestion(input: unknown): string | null {
  const clip = (s: string) =>
    s.length > MAX_ADVISOR_QUESTION_CHARS
      ? `${s.slice(0, MAX_ADVISOR_QUESTION_CHARS)}…`
      : s || null;
  if (typeof input === "string") return clip(input.trim());
  if (!input || typeof input !== "object" || Array.isArray(input)) return null;
  const obj = input as Record<string, unknown>;
  for (const field of ADVISOR_QUESTION_FIELDS) {
    const value = obj[field];
    if (typeof value === "string" && value.trim().length > 0) return clip(value.trim());
  }
  if (Object.keys(obj).length === 0) return null;
  try {
    return clip(JSON.stringify(obj));
  } catch {
    return null;
  }
}

/** The final user turn: what the panel is being asked, stated plainly. */
function advisorQuestionMessage(question: string | null): string {
  const body =
    question === null
      ? "The assistant named no explicit question, so its question is the conversation itself: " +
        "advise it on the decision it now faces, the risks in the approach it has taken, and what " +
        "it should do next."
      : `The assistant's question is:\n\n${question}`;
  return (
    "[claudish] The coding assistant paused the work above and consulted its advisor. " +
    "You are the advisor.\n\n" +
    `${body}\n\n` +
    "Answer that question, using the conversation above as context. The advisor tool is provided " +
    "by the claudish proxy and has no implementation inside the assistant's harness, so any tool " +
    "error about it is plumbing: do not treat it as the subject, and do not comment on how the " +
    "call was made."
  );
}

/**
 * The message list ONE advisor call sends to every panel model: the whole
 * conversation, minus claudish's own plumbing error for THIS call, plus a final
 * user turn stating the question.
 *
 * Detection is STRUCTURAL — the `tool_use_id` of the call being answered, which
 * claudish minted the record for — never the error phrase. Text the harness or
 * the model wrote is untrusted input, and a phrase test would neutralise any
 * tool result that merely quoted the phrase (the same trap
 * `reportUnrecordedAdvisorCalls` documents). No OTHER tool_result is touched:
 * another tool's output is legitimate context.
 *
 * Returns a new list; the caller's payload, which is the live upstream request,
 * is never mutated — only the messages and blocks that change are copied.
 */
export function prepareAdvisorPanelMessages(messages: unknown, toolUseId: string): any[] {
  if (!Array.isArray(messages)) return [];
  let question: string | null = null;

  const prepared = messages.map((msg: any) => {
    if (!msg || typeof msg !== "object" || !Array.isArray(msg.content)) return msg;
    let changed = false;
    const content = msg.content.map((block: any) => {
      if (!block || typeof block !== "object") return block;
      if (block.type === "tool_use" && block.name === ADVISOR_TOOL_NAME && block.id === toolUseId) {
        question ??= describeAdvisorQuestion(block.input);
        return block;
      }
      if (block.type === "tool_result" && block.tool_use_id === toolUseId) {
        changed = true;
        return {
          ...block,
          content: [{ type: "text", text: ADVISOR_PLUMBING_MARKER }],
          is_error: false,
        };
      }
      return block;
    });
    return changed ? { ...msg, content } : msg;
  });

  prepared.push({
    role: "user",
    content: [{ type: "text", text: advisorQuestionMessage(question) }],
  });
  return prepared;
}

const ADVISOR_SYSTEM_PROMPT = `You are a strategic advisor to a coding agent. \
You have been given the full conversation history between a user and a Claude Code \
coding assistant. The assistant has paused to consult you for guidance.

Review the conversation and provide concise, actionable advice. Focus on:
- Architectural decisions and trade-offs
- Potential pitfalls the assistant might miss
- Alternative approaches worth considering
- Security, performance, or correctness concerns

Be direct. Limit your response to 300-500 words.`;

const COLLECTOR_SYSTEM_PROMPT = `You are synthesizing advice from multiple AI models \
for a coding agent. You will receive several independent advisor opinions about the \
same coding problem. Synthesize them into a single, coherent response that:
- Identifies consensus points (where advisors agree)
- Highlights disagreements and explains which perspective is stronger
- Produces a clear, actionable recommendation
Be concise. Do not attribute advice to specific models.`;

/** The credentials `resolveAdvisorCredential` can look up. */
export type AdvisorRouteKind = "google" | "openai" | "openrouter" | "anthropic";

/**
 * The fixed endpoint of a Claude advisor call (`claudeAdvisorRoute`). A routed
 * member has no such route: its chain was built at startup from
 * `planAdvisorModel`, and its record names the planned chain instead.
 */
export interface AdvisorRoute {
  kind: AdvisorRouteKind;
  /** Endpoint host, e.g. `openrouter.ai`. */
  host: string;
  /** Full endpoint URL the request is POSTed to. */
  url: string;
  /** Which advisor credential signs the request. */
  credential: AdvisorRouteKind;
  /** The model id placed in the request body, after catalog resolution. */
  wireModel: string;
  /**
   * The API this request is built for: the connection's `wire.api` (catalog
   * 3.7.0), or the profile's Chat Completions when the wire is not known.
   */
  api: WireApi;
  /** The connection's known wire, when the catalog publishes one. */
  wire?: KnownWire;
}

/**
 * The credential-authority provider each advisor credential resolves through.
 * `anthropic` is `native-anthropic`, which resolves exactly ANTHROPIC_API_KEY
 * (env → config → keychain → op://) and never the Claude Code OAuth token.
 */
export const ADVISOR_AUTHORITY_PROVIDER: Readonly<Record<AdvisorRouteKind, string>> = Object.freeze(
  {
    google: "google",
    openai: "openai",
    openrouter: "openrouter",
    anthropic: "native-anthropic",
  }
);

/**
 * True for the placeholder key claude-runner installs in proxy-auth mode
 * (`sk-ant-api03-placeholder-not-used-…`). It is not a credential: sending it
 * to api.anthropic.com is a guaranteed 401. Matched loosely on purpose — every
 * placeholder claudish or a wrapper has ever installed says so in its value,
 * and a real Anthropic key does not.
 */
export function isPlaceholderAnthropicKey(key: string): boolean {
  return /placeholder/i.test(key);
}

/**
 * THE advisor credential lookup: the startup check and the runtime call path
 * both resolve through this one function, so they cannot disagree about
 * whether a launch is possible. They did: startup asked the authority alone
 * and refused a Google panel model the runtime would have called with
 * GOOGLE_API_KEY.
 *
 * Only the two auth headers a credential provider signs with are read
 * (`Authorization` / `x-api-key`). The api-key half ALWAYS returns an object —
 * `{headers:{}}` with no key, or one carrying only static non-auth headers —
 * so neither the object nor "some header is non-empty" proves a credential
 * (CLAUDE.md).
 *
 * google: the authority's `google` provider is the DIRECT Gemini API
 * (GEMINI_API_KEY); Antigravity and Code Assist are registered under their own
 * names, and nothing may alias `google`. GOOGLE_API_KEY, which that provider
 * therefore never reads, stays a last-resort env fallback because the advisor
 * always accepted it.
 *
 * anthropic (collector only): ANTHROPIC_API_KEY as the authority resolves it,
 * never claudish's placeholder and never ANTHROPIC_AUTH_TOKEN — which the
 * native-anthropic provider would otherwise hand out as an `x-api-key`, and
 * which is the subscription arm's OAuth token. Claude Code's inbound
 * `authorization` bearer is not visible here at all; the runtime's own
 * inbound-`x-api-key` preference lives at its call site.
 *
 * Returns the secret, so a caller that needs presence only (the startup check)
 * must test it and drop it — never log or print it.
 */
export async function resolveAdvisorCredential(
  credential: AdvisorRouteKind
): Promise<string | undefined> {
  const fromAuthority = async (provider: string, header: "any" | "x-api-key") => {
    try {
      const auth = await credentials.getRequestAuth(provider, { model: "" });
      const bearer = auth.headers.Authorization?.replace(/^Bearer\s+/i, "").trim();
      const apiKey = auth.headers["x-api-key"]?.trim();
      return (header === "x-api-key" ? apiKey : bearer || apiKey) || undefined;
    } catch {
      return undefined;
    }
  };

  if (credential === "anthropic") {
    const key = await fromAuthority(ADVISOR_AUTHORITY_PROVIDER.anthropic, "x-api-key");
    if (!key || key === process.env.ANTHROPIC_AUTH_TOKEN || isPlaceholderAnthropicKey(key)) {
      return undefined;
    }
    return key;
  }
  if (credential === "google") {
    return (
      (await fromAuthority(ADVISOR_AUTHORITY_PROVIDER.google, "any")) ||
      process.env.GOOGLE_API_KEY?.trim() ||
      undefined
    );
  }
  return fromAuthority(ADVISOR_AUTHORITY_PROVIDER[credential], "any");
}

/** How many output tokens an advisor or collector call asks for. */
const ADVISOR_MAX_OUTPUT_TOKENS = 2048;

/**
 * What one panel or collector call actually did. Provenance is part of the
 * data type, never reconstructed from placeholder strings: `text` exists only
 * when `origin` is `upstream`, `reason` and `stubPath` only when it is not.
 */
export interface AdvisorModelOutcome {
  role: "panel" | "collector";
  /** The model spec as the user named it. */
  requestedModel: string;
  /** The route the request was sent on; null when the request could not be built. */
  route: AdvisorRoute | null;
  /** `extractUpstreamStatus(body) ?? response.status`; null when no response arrived. */
  upstreamStatus: number | null;
  upstreamStatusSource: UpstreamStatusSource | null;
  /** Bytes of the HTTP response body; 0 when none arrived. */
  responseBytes: number;
  latencyMs: number;
  origin: AdviceOrigin;
  stubPath: AdvisorStubPath | null;
  text?: string;
  reason?: string;
  /** How the record names the route: the planned chain, or the fixed Claude host. */
  recordRoute?: AdvisorRecordRoute;
  /** Who served the call; null when nothing served (`origin` is not `upstream`). */
  servedBy?: AdvisorServedBy | null;
  /** The serving hop's wire model, or the resolved Anthropic id. */
  routedModel?: string | null;
  /** Routed only: provider uids whose `handle()` was entered, in order, once each. */
  hopsTried?: string[];
  /** `servedBy.billing`; null when nothing served. */
  billing?: AdvisorBilling | null;
  usage?: { input_tokens: number; output_tokens: number };
  emptyReason?: AdvisorEmptyReason;
  stopReason?: string;
}

/** The `route` field of an advisor record. */
export type AdvisorRecordRoute =
  | { kind: "routed"; plannedChain: string[] }
  | { kind: "claude-native"; host: string };

/** The `servedBy` field of an advisor record: labels only, never a credential. */
export interface AdvisorServedBy {
  /** The claudish provider that served the call. */
  provider: string;
  displayName: string;
  /** The arm that signed: `oauth` for a subscription login, `api-key` otherwise; null when unknown. */
  arm: string | null;
  billing: AdvisorBilling | null;
}

/** One advisor call end to end: every model's outcome and the delivered result. */
export interface AdvisorCallOutcome {
  toolUseId: string;
  sessionId: string | null;
  panel: AdvisorModelOutcome[];
  collector: string | null;
  /** null when no collector ran (none configured, one model, or no advice to synthesize). */
  collectorOutcome: AdvisorModelOutcome | null;
  /** `upstream` only when ≥1 panel model AND the collector (if it ran) were upstream. */
  resultOrigin: AdviceOrigin;
  /** The aggregate stub path when `resultOrigin` is not `upstream`. */
  stubPath: AdvisorStubPath | null;
  result: AdvisorToolResult;
}

/** Abort a panel call after this long; a failure like any other (stub path S7). */
const ADVISOR_PANEL_TIMEOUT_MS = 60_000;

/**
 * Abort a collector call after this long — BOTH collector routes. The
 * Anthropic collector had no timeout at all, so a collector that never
 * answered stalled a LIVE request indefinitely (the panel loop is awaited
 * before the upstream request is sent). A timeout is a recorded failure like
 * any other: origin `stub`, stub path S9, and the unchanged fall-back to the
 * panel's unsynthesized sections.
 */
const ADVISOR_COLLECTOR_TIMEOUT_MS = 30_000;

interface ObservedResponse {
  status: number;
  source: UpstreamStatusSource;
  bytes: number;
}

/**
 * The ONE constructor of a failed outcome, and therefore the one place the
 * provider's own words are sanitised (`sanitizeAdvisorReason`). Every consumer
 * — the tool_result the MAIN MODEL reads, the terminal warning, the advisor log
 * file, the debug mirror and the always-on log — reads `reason` from here, so
 * none of them can see the raw text.
 *
 * `secrets` is the credentials this very call presented; they are redacted by
 * value, on top of the known key shapes.
 */
function stubOutcome(
  base: Pick<AdvisorModelOutcome, "role" | "requestedModel" | "route">,
  stubPath: AdvisorStubPath,
  reason: string,
  latencyMs: number,
  secrets: readonly (string | undefined)[],
  observed?: ObservedResponse
): AdvisorModelOutcome {
  return {
    ...base,
    upstreamStatus: observed?.status ?? null,
    upstreamStatusSource: observed?.source ?? null,
    responseBytes: observed?.bytes ?? 0,
    latencyMs,
    origin: "stub",
    stubPath,
    reason: sanitizeAdvisorReason(reason, secrets),
  };
}

function summarizeErrorBody(bodyText: string): string {
  let message = "";
  try {
    message = extractProviderMessage(JSON.parse(bodyText));
  } catch {
    message = bodyText;
  }
  const oneLine = String(message ?? "")
    .replace(/\s+/g, " ")
    .trim();
  return oneLine ? oneLine.slice(0, 200) : "(empty body)";
}

function describeFetchError(err: unknown, timeoutMs?: number): string {
  const e = err as { name?: string; message?: string } | undefined;
  if (e?.name === "AbortError" && timeoutMs) {
    return `timed out after ${Math.round(timeoutMs / 1000)}s`;
  }
  return `request failed: ${e?.message ?? String(err)}`;
}

// ---------------------------------------------------------------------------
// Claude advisor calls: the Claude Code login arm
// ---------------------------------------------------------------------------
//
// A Claude panel member or collector is ONE request to the fixed
// `ANTHROPIC_MESSAGES_URL`. On a launch where claudish controls the child's
// auth (`childAuthControl`, claude-runner.ts) it is signed with the bearer
// Claude Code sent, which can then only be the claude.ai login; on every
// other launch the bearer is never used, and the call signs with the inbound
// `x-api-key` if real, else ANTHROPIC_API_KEY, metered. The request on the
// login arm is S0 shape A: the inbound identity block, then the advisor prompt
// (test-fixtures/advisor/replay-results-*.json: A0, the prompt alone, is
// refused on every tier; A is accepted on opus, sonnet, haiku and fable).
//
// The bearer reaches exactly one function, `runClaudeAdvisorCall`, which takes
// no URL. It is held in `ClaudeLogin`, which prints as `[redacted]`, and its
// value is registered on the main request's signing lease the moment it is
// read, so every log line of that request is redacted against it.

/**
 * Claude Code's inbound `authorization` value, held so it cannot print:
 * `String()`, `JSON.stringify` and `Bun.inspect` all give `[redacted]`. Only
 * `headerValue()` yields it, and only `runClaudeAdvisorCall` calls that.
 */
export class ClaudeLogin {
  readonly #value: string;

  constructor(authorizationHeader: string) {
    this.#value = authorizationHeader;
  }

  /** The `authorization` header value, verbatim (`Bearer …`). */
  headerValue(): string {
    return this.#value;
  }

  toString(): string {
    return REDACTED;
  }

  toJSON(): string {
    return REDACTED;
  }

  [Symbol.for("nodejs.util.inspect.custom")](): string {
    return REDACTED;
  }
}

/**
 * Why a bearer on the request was not used as the Claude login:
 * - `placeholder`: claudish's own placeholder (a proxy-auth launch);
 * - `user-auth-token`: it equals this process's ANTHROPIC_AUTH_TOKEN;
 * - `launch-auth-not-claudish-controlled`: this launch lets the child sign
 *   with something other than the login (`childAuthControl`), so no bearer
 *   can be placed.
 */
export type ClaudeLoginSkipped =
  | "placeholder"
  | "user-auth-token"
  | "launch-auth-not-claudish-controlled";

/** What a Claude advisor call may sign with, read once from the MAIN request. */
export interface ClaudeRequestFacts {
  /** Present only when every provenance check passed. */
  login?: ClaudeLogin;
  /** Set when a bearer was present but not used. */
  loginSkipped?: ClaudeLoginSkipped;
  /** The launch's non-login credential source, when that is why the bearer was skipped. */
  authSource?: { reason: ChildAuthSource; where: string };
  /** The inbound `x-api-key`, when it is a real key (never a placeholder). */
  inboundApiKey?: string;
  /** Inbound `anthropic-beta`, verbatim; the call strips the advisor flag. */
  anthropicBeta?: string;
  anthropicVersion?: string;
  /** The first inbound system text block that is not the billing block and is one line. */
  identityBlock?: string;
}

export interface ClaudeRequestFactsDeps {
  /** This launch's `childAuthControl(config, env)`. */
  childAuth: ChildAuthControl;
  /** Read for ANTHROPIC_AUTH_TOKEN; defaults to `process.env`. */
  env?: NodeJS.ProcessEnv;
}

/** Not global: no `lastIndex`. */
const BEARER_PREFIX = /^Bearer\s+/i;

/**
 * Claude Code's identity block: the first system text block that is not the
 * billing-header block and spans one line, copied without its `cache_control`.
 * Absent for a string system or when no block qualifies (the call then sends
 * the advisor prompt alone, `systemHead: "none"`).
 */
export function claudeIdentityBlock(system: unknown): string | undefined {
  if (!Array.isArray(system)) return undefined;
  for (const block of system) {
    const text = (block as { type?: unknown; text?: unknown } | null)?.text;
    if ((block as { type?: unknown } | null)?.type !== "text" || typeof text !== "string") continue;
    if (isBillingHeaderText(text)) continue;
    return text.includes("\n") || text.trim() === "" ? undefined : text;
  }
  return undefined;
}

/**
 * Read what a Claude advisor call may sign with from the MAIN request, once,
 * and register every real credential value on that request's signing lease.
 *
 * The login arm needs ALL of: an inbound `Bearer` that is not a claudish
 * placeholder; a value that is not this process's ANTHROPIC_AUTH_TOKEN; and a
 * launch where claudish controls the child's auth. A request cannot prove
 * provenance on its own (the OAuth beta is client-declared, S0), so the third
 * check is the launch's decision, made in claude-runner.ts.
 */
export function claudeRequestFacts(
  c: Context,
  payload: unknown,
  deps: ClaudeRequestFactsDeps
): ClaudeRequestFacts {
  const authorization = c.req.header("authorization")?.trim();
  const bearer = authorization?.replace(BEARER_PREFIX, "").trim();
  const apiKey = c.req.header("x-api-key")?.trim();
  const realApiKey = apiKey && !isPlaceholderAnthropicKey(apiKey) ? apiKey : undefined;
  const realBearer = bearer && !isPlaceholderAnthropicKey(bearer) ? bearer : undefined;
  addSigningSecrets(
    c,
    [realBearer, realApiKey].filter((v): v is string => Boolean(v))
  );

  const facts: ClaudeRequestFacts = {
    ...(realApiKey ? { inboundApiKey: realApiKey } : {}),
    ...(c.req.header("anthropic-beta") ? { anthropicBeta: c.req.header("anthropic-beta") } : {}),
    ...(c.req.header("anthropic-version")
      ? { anthropicVersion: c.req.header("anthropic-version") }
      : {}),
  };
  const identity = claudeIdentityBlock((payload as { system?: unknown } | null)?.system);
  if (identity !== undefined) facts.identityBlock = identity;

  if (!authorization || !bearer || !BEARER_PREFIX.test(authorization)) return facts;
  if (!realBearer) return { ...facts, loginSkipped: "placeholder" };
  const env = deps.env ?? process.env;
  if (realBearer === env.ANTHROPIC_AUTH_TOKEN?.trim()) {
    return { ...facts, loginSkipped: "user-auth-token" };
  }
  if (!deps.childAuth.controlled) {
    return {
      ...facts,
      loginSkipped: "launch-auth-not-claudish-controlled",
      authSource: { reason: deps.childAuth.reason, where: deps.childAuth.where },
    };
  }
  return { ...facts, login: new ClaudeLogin(authorization) };
}

/** Where a Claude advisor call's credential came from: a label, never a value. */
export type ClaudeCredentialSource =
  | "claude-code-login"
  | "inbound-x-api-key"
  | "ANTHROPIC_API_KEY";

export type ClaudeAdvisorAuth =
  | { arm: "oauth"; source: "claude-code-login"; login: ClaudeLogin; facts: ClaudeRequestFacts }
  | {
      arm: "api-key";
      source: "inbound-x-api-key" | "ANTHROPIC_API_KEY";
      apiKey: string;
      facts: ClaudeRequestFacts;
      /** Why a present bearer was not used; the call warns with it (never silent). */
      warning?: string;
    }
  | { arm: null; reason: string; facts: ClaudeRequestFacts; warning?: string };

/** The reason a skipped bearer was not used, as a clause. */
function loginSkippedPhrase(facts: ClaudeRequestFacts): string {
  switch (facts.loginSkipped) {
    case "user-auth-token":
      return "it is your ANTHROPIC_AUTH_TOKEN, not a Claude login";
    case "launch-auth-not-claudish-controlled":
      return facts.authSource
        ? `${facts.authSource.reason} (${facts.authSource.where}) lets Claude Code sign with something other than your login, so claudish cannot tell which it is`
        : "this launch lets Claude Code sign with something other than your login";
    default:
      return "it is claudish's placeholder";
  }
}

/**
 * The credential for one Claude advisor call, by presence and provenance on
 * the request, never by failure: the login when `facts.login` exists; else the
 * inbound `x-api-key` if real; else ANTHROPIC_API_KEY (`anthropicKey`, the
 * advisor's own lookup, asked only now). A real bearer that failed a check, or
 * a request with no bearer at all, is never moved to a metered key silently:
 * the result carries a warning naming the reason. claudish's own placeholder
 * (a proxy-auth launch, whose startup notice already says metered) is not a
 * credential and only shows in the record (`loginSkipped`).
 */
export async function resolveClaudeAdvisorAuth(
  facts: ClaudeRequestFacts,
  anthropicKey: () => Promise<string | undefined> = () => resolveAdvisorCredential("anthropic")
): Promise<ClaudeAdvisorAuth> {
  if (facts.login) {
    return { arm: "oauth", source: "claude-code-login", login: facts.login, facts };
  }
  const skipped =
    facts.loginSkipped === undefined
      ? "this request carries no Claude login"
      : facts.loginSkipped !== "placeholder"
        ? `Claude Code's bearer was not used (${loginSkippedPhrase(facts)})`
        : undefined;
  if (facts.inboundApiKey) {
    return {
      arm: "api-key",
      source: "inbound-x-api-key",
      apiKey: facts.inboundApiKey,
      facts,
      ...(skipped ? { warning: `${skipped}; billed per token on the request's x-api-key` } : {}),
    };
  }
  const key = await anthropicKey();
  if (key) {
    return {
      arm: "api-key",
      source: "ANTHROPIC_API_KEY",
      apiKey: key,
      facts,
      ...(skipped ? { warning: `${skipped}; billed per token on ANTHROPIC_API_KEY` } : {}),
    };
  }
  return {
    arm: null,
    reason:
      "no Claude credential: this request carries no Claude login and no ANTHROPIC_API_KEY was found",
    facts,
    ...(skipped ? { warning: skipped } : {}),
  };
}

/**
 * HTTP 429 `rate_limit_error` with the message "Error" and none of the
 * `anthropic-ratelimit-unified-*` headers every real limit carries: Anthropic
 * refusing the request's SHAPE on the Claude login (S0: shape A0 on every
 * tier), not quota exhaustion. Never retried as a rate limit, never a reason
 * to cool anything down; the call becomes a stub saying so.
 *
 * `status` must be the recovered upstream status (`extractUpstreamStatus(body)
 * ?? response.status`), which is what the caller passes.
 */
export function isClaudeShapeRefusal(status: number, bodyText: string, headers: Headers): boolean {
  if (status !== 429) return false;
  let unifiedLimitHeader = false;
  headers.forEach((_value, name) => {
    if (name.toLowerCase().startsWith("anthropic-ratelimit-unified-")) unifiedLimitHeader = true;
  });
  if (unifiedLimitHeader) return false;
  try {
    const error = (JSON.parse(bodyText) as { error?: { type?: unknown; message?: unknown } }).error;
    return error?.type === "rate_limit_error" && error.message === "Error";
  } catch {
    return false;
  }
}

/** One Claude advisor call's outcome: the common fields plus what signed and how it billed. */
export interface ClaudeAdvisorOutcome extends AdvisorModelOutcome {
  credentialSource: ClaudeCredentialSource | null;
  /** The arm that signed; null when no credential was found. */
  servedArm: "oauth" | "api-key" | null;
  /** Arm-derived: `subscription` iff the login signed; null when nothing served. */
  billing: AdvisorBilling | null;
  loginSkipped?: ClaudeLoginSkipped;
  /** Login arm only: the system head actually sent. */
  systemHead?: "none" | "identity";
  usage?: { input_tokens: number; output_tokens: number };
  emptyReason?: AdvisorEmptyReason;
  stopReason?: string;
  /** True for the 429 "Error" shape refusal (`isClaudeShapeRefusal`). */
  shapeRefusal?: boolean;
}

export interface ClaudeAdvisorCallParams {
  role: "panel" | "collector";
  /** The spec as the user named it. */
  spec: string;
  /** The resolved Anthropic model id. */
  model: string;
  auth: ClaudeAdvisorAuth;
  /** The advisor or collector prompt. */
  system: string;
  turns: AdvisorTurn[];
  timeoutMs: number;
  /** Test seam; defaults to the global fetch at call time. */
  fetchImpl?: typeof fetch;
  /** Test seam for the provenance warning; defaults to `warnAdvisor`. */
  warn?: (message: string) => void;
}

/** The record route of every Claude advisor call: the fixed Anthropic endpoint. */
function claudeAdvisorRoute(model: string): AdvisorRoute {
  return {
    kind: "anthropic",
    host: ANTHROPIC_API_HOST,
    url: ANTHROPIC_MESSAGES_URL,
    credential: "anthropic",
    wireModel: model,
    api: "anthropic-messages",
  };
}

/** Headers and body for the arm `auth` names. The login arm sends S0 shape A. */
function claudeAdvisorRequestInit(
  params: ClaudeAdvisorCallParams,
  auth: Exclude<ClaudeAdvisorAuth, { arm: null }>
): {
  headers: Record<string, string>;
  body: Record<string, unknown>;
  systemHead?: "none" | "identity";
} {
  if (auth.arm === "api-key") {
    // Today's metered request, byte for byte, shaped by the connection's wire
    // when the catalog publishes one.
    const headers: Record<string, string> = {
      "Content-Type": "application/json",
      "x-api-key": auth.apiKey,
      "anthropic-version": "2023-06-01",
    };
    const body: Record<string, unknown> = {
      model: params.model,
      system: params.system,
      messages: params.turns,
      max_tokens: ADVISOR_MAX_OUTPUT_TOKENS,
    };
    const resolution = resolveConnection("anthropic", params.model);
    if (resolution.ok && resolution.connection.wire.status === "known") {
      const shaped = shapeRequestFromWire(body, resolution.connection.wire, {
        maxTokens: ADVISOR_MAX_OUTPUT_TOKENS,
        hasTools: false,
      });
      mergeWireHeaders(headers, shaped.headers);
    }
    return { headers, body };
  }
  const { facts } = auth;
  const headers: Record<string, string> = {
    "content-type": "application/json",
    authorization: auth.login.headerValue(),
    "anthropic-version": facts.anthropicVersion || "2023-06-01",
  };
  const beta = stripAdvisorBeta(facts.anthropicBeta).stripped;
  if (beta) headers["anthropic-beta"] = beta;
  const prompt = { type: "text", text: params.system };
  const identity = facts.identityBlock;
  return {
    headers,
    body: {
      model: params.model,
      system: identity ? [{ type: "text", text: identity }, prompt] : [prompt],
      messages: params.turns,
      max_tokens: ADVISOR_MAX_OUTPUT_TOKENS,
    },
    systemHead: identity ? "identity" : "none",
  };
}

/**
 * The (Claude member, warning) pairs, `"<role>:<spec>\n<warning>"`, that have
 * already printed the "cannot use the bearer / no bearer, signing with a
 * metered key" warning. Every request of a launch whose login is skipped (a
 * Console-key login, say) gives the same answer, so the line is printed once
 * per launch per member and reason, not once per advisor call. Keyed by the
 * text too, so a later DIFFERENT reason for the same member (no bearer, then a
 * skipped one; the request's x-api-key, then ANTHROPIC_API_KEY) is printed
 * rather than hidden. The text names only a reason and a key source, never a
 * value, so the set stays bounded. The per-call record still carries
 * `loginSkipped` and the arm.
 */
const claudeAuthWarned = new Set<string>();

/** Test seam: let every Claude member warn again. */
export function _debug_resetClaudeAuthWarnings(): void {
  claudeAuthWarned.clear();
}

/**
 * One Claude advisor call. Never rejects. The URL is the module constant
 * `ANTHROPIC_MESSAGES_URL` and cannot be changed by the caller, so the login
 * bearer goes nowhere else. Immediately before the fetch it logs one boundary
 * line read from the `Request` being sent, never a value:
 * `[advisor] Calling API: <url> (role, auth: bearer|x-api-key, source, systemHead)`.
 *
 * A failed login (401, 429) is reported with Anthropic's message; it is never
 * retried on a metered key.
 */
export async function runClaudeAdvisorCall(
  params: ClaudeAdvisorCallParams
): Promise<ClaudeAdvisorOutcome> {
  const { auth, role } = params;
  const base = { role, requestedModel: params.spec, route: claudeAdvisorRoute(params.model) };
  const stubPaths =
    role === "panel"
      ? { empty: ADVISOR_STUB_PATHS.PANEL_EMPTY, error: ADVISOR_STUB_PATHS.PANEL_ERROR }
      : {
          empty: ADVISOR_STUB_PATHS.ANTHROPIC_COLLECTOR_EMPTY,
          error: ADVISOR_STUB_PATHS.COLLECTOR_FAILED,
        };
  const labels = {
    credentialSource: auth.arm === null ? null : auth.source,
    servedArm: auth.arm,
    ...(auth.facts.loginSkipped ? { loginSkipped: auth.facts.loginSkipped } : {}),
  };
  const warning = auth.arm === "oauth" ? undefined : auth.warning;
  const warnedKey = `${role}:${params.spec}\n${warning}`;
  if (warning && !claudeAuthWarned.has(warnedKey)) {
    claudeAuthWarned.add(warnedKey);
    (params.warn ?? warnAdvisor)(`${params.spec}: ${warning}`);
  }
  if (auth.arm === null) {
    return {
      ...stubOutcome(base, stubPaths.error, auth.reason, 0, []),
      ...labels,
      billing: null,
    };
  }

  const init = claudeAdvisorRequestInit(params, auth);
  const extra = { ...labels, ...(init.systemHead ? { systemHead: init.systemHead } : {}) };
  // Held for this call's own log lines; the login value is also on the main
  // request's lease from the moment it was read.
  const lease = acquireSigningLease();
  const secrets = credentialValuesFromRequest(init.headers);
  lease.add(secrets);
  const started = performance.now();
  const elapsed = () => Math.round(performance.now() - started);
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), params.timeoutMs);
  try {
    const request = new Request(ANTHROPIC_MESSAGES_URL, {
      method: "POST",
      headers: init.headers,
      body: JSON.stringify(init.body),
      signal: controller.signal,
    });
    log(
      `[advisor] Calling API: ${request.url} (role: ${role}, auth: ${request.headers.has("authorization") ? "bearer" : "x-api-key"}, source: ${auth.source}${init.systemHead ? `, systemHead: ${init.systemHead}` : ""})`
    );
    const outcome = await fetchClaudeAdvice(request, params, base, stubPaths, secrets, elapsed);
    const billing: AdvisorBilling | null =
      outcome.origin === "upstream" ? (auth.arm === "oauth" ? "subscription" : "metered") : null;
    recordClaudeAdvisorStats(params.model, auth.arm, outcome);
    return { ...outcome, ...extra, billing };
  } finally {
    clearTimeout(timer);
    lease.release();
  }
}

/**
 * The running cost of this launch's Claude advisor calls, per model id. Main
 * requests report `estimated_cost` as their handler's running total and
 * `is_free_model` as "that total is 0" (`TokenTracker`); a Claude advisor call
 * has no handler, so this accumulator gives its events the same meaning. The
 * login arm adds 0; an API-key arm adds `calculateCost("native-anthropic", …)`,
 * the oracle every tracker prices with. Output tokens accumulate and input
 * tokens are the latest call's, as the standard token strategy reports them.
 */
const claudeAdvisorSpend = new Map<string, { cost: number; outputTokens: number }>();

/** Test seam: forget the Claude advisor spend accumulated so far. */
export function _debug_resetClaudeAdvisorSpend(): void {
  claudeAdvisorSpend.clear();
}

/**
 * The stats event for one Claude advisor request sent, updating the launch's
 * accumulator (`request_role: "advisor"`, `provider_name: "native-anthropic"`,
 * no token file). A 2xx with usage adds to the accumulator, empty advice
 * included (the tokens were spent); any other answer is `success: false` with
 * its status and leaves the accumulator unchanged.
 */
export function claudeAdvisorStatsEvent(
  model: string,
  arm: "oauth" | "api-key",
  outcome: Pick<AdvisorModelOutcome, "upstreamStatus" | "latencyMs"> & {
    usage?: { input_tokens: number; output_tokens: number };
  }
): Partial<StatsEvent> {
  const status = outcome.upstreamStatus;
  const success = status !== null && status >= 200 && status < 300;
  const acc = claudeAdvisorSpend.get(model) ?? { cost: 0, outputTokens: 0 };
  const usage = success ? outcome.usage : undefined;
  if (usage) {
    acc.cost +=
      arm === "oauth"
        ? 0
        : calculateCost("native-anthropic", model, usage.input_tokens, usage.output_tokens);
    acc.outputTokens += usage.output_tokens;
    claudeAdvisorSpend.set(model, acc);
  }
  return {
    model_id: model,
    provider_name: "native-anthropic",
    stream_format: "anthropic-messages",
    latency_ms: outcome.latencyMs,
    success,
    http_status: status ?? 0,
    input_tokens: usage?.input_tokens ?? 0,
    output_tokens: usage ? acc.outputTokens : 0,
    estimated_cost: acc.cost,
    is_free_model: acc.cost === 0,
    token_strategy: "standard",
    adapter_name: "none",
    fallback_used: false,
    request_role: "advisor",
  };
}

function recordClaudeAdvisorStats(
  model: string,
  arm: "oauth" | "api-key",
  outcome: AdvisorModelOutcome & { usage?: { input_tokens: number; output_tokens: number } }
): void {
  try {
    recordStats(claudeAdvisorStatsEvent(model, arm, outcome));
  } catch {
    // Stats must never break an advisor call
  }
}

type ClaudeCallBase = Pick<AdvisorModelOutcome, "role" | "requestedModel" | "route">;
type ClaudeFetchOutcome = AdvisorModelOutcome &
  Pick<ClaudeAdvisorOutcome, "usage" | "emptyReason" | "stopReason" | "shapeRefusal">;

/** Send the request and classify the answer; the stub reasons are sanitised by value. */
async function fetchClaudeAdvice(
  request: Request,
  params: ClaudeAdvisorCallParams,
  base: ClaudeCallBase,
  stubPaths: { empty: AdvisorStubPath; error: AdvisorStubPath },
  secrets: readonly string[],
  elapsed: () => number
): Promise<ClaudeFetchOutcome> {
  let resp: Response;
  let bodyText: string;
  try {
    resp = await (params.fetchImpl ?? fetch)(request);
  } catch (err) {
    return stubOutcome(
      base,
      stubPaths.error,
      describeFetchError(err, params.timeoutMs),
      elapsed(),
      secrets
    );
  }
  let responseBytes: number;
  try {
    const raw = await resp.text();
    responseBytes = new TextEncoder().encode(raw).byteLength;
    // The panel gateway's two passes (advisor-panel-gateway.ts), applied before
    // the body is parsed, summarised or returned as advice: every value the
    // registry holds, then this call's own values in every form. Advice text
    // can reach a collector of another vendor, so an echoed Claude credential
    // must not survive into it.
    bodyText = redactExactValues(redactForClient(raw), secrets);
  } catch (err) {
    return stubOutcome(
      base,
      stubPaths.error,
      `HTTP ${resp.status} but the body could not be read: ${describeFetchError(err, params.timeoutMs)}`,
      elapsed(),
      secrets,
      { status: resp.status, source: "http_status", bytes: 0 }
    );
  }
  const bodyStatus = extractUpstreamStatus(bodyText);
  const observed: ObservedResponse = {
    status: bodyStatus ?? resp.status,
    source: bodyStatus !== undefined ? "error.upstream_status" : "http_status",
    bytes: responseBytes,
  };
  if (!resp.ok || (bodyStatus !== undefined && bodyStatus >= 400)) {
    if (isClaudeShapeRefusal(observed.status, bodyText, resp.headers)) {
      log(
        `[advisor] ${params.spec}: Anthropic refused the request shape (429 "Error"); not retried`
      );
      return {
        ...stubOutcome(
          base,
          stubPaths.error,
          `HTTP ${observed.status} rate_limit_error "Error" with no unified rate-limit headers: Anthropic refused this request's shape on the Claude login; this is not a quota limit and was not retried`,
          elapsed(),
          secrets,
          observed
        ),
        shapeRefusal: true,
      };
    }
    return stubOutcome(
      base,
      stubPaths.error,
      `HTTP ${observed.status}: ${summarizeErrorBody(bodyText)}`,
      elapsed(),
      secrets,
      observed
    );
  }
  return claudeAdviceOutcome(bodyText, base, stubPaths.empty, secrets, observed, elapsed);
}

/** What each empty-answer reason means, for the stub text the model and the user read. */
const EMPTY_ADVICE_PHRASE: Readonly<Record<AdvisorEmptyReason, string>> = {
  "no-content": "the answer had no content",
  "reasoning-only": "the model returned reasoning only, and no text",
  "max-tokens-before-text": `the ${ADVISOR_MAX_OUTPUT_TOKENS}-token output limit was reached before any text`,
  "max-tokens-during-reasoning": `the ${ADVISOR_MAX_OUTPUT_TOKENS}-token output limit was reached while the model was still reasoning`,
};

/**
 * The S4/S5/S6 reason for a 2xx answer with no advice text, naming why:
 * `HTTP 200 but the response carried no advice text (reasoning-only: the
 * model returned reasoning only, and no text; stop_reason end_turn)`. A
 * reasoning-only or max-tokens reply is never reported as a bare "no advice".
 */
function emptyAdviceReason(status: number, advice: ExtractedAdvice): string {
  const why = advice.emptyReason
    ? `${advice.emptyReason}: ${EMPTY_ADVICE_PHRASE[advice.emptyReason]}`
    : "no-content";
  const stop = advice.stopReason !== undefined ? `; stop_reason ${advice.stopReason}` : "";
  return `HTTP ${status} but the response carried no advice text (${why}${stop})`;
}

/** A 2xx answer: the advice, or an empty-stub naming why there is none. */
function claudeAdviceOutcome(
  bodyText: string,
  base: ClaudeCallBase,
  emptyStubPath: AdvisorStubPath,
  secrets: readonly string[],
  observed: ObservedResponse,
  elapsed: () => number
): ClaudeFetchOutcome {
  let data: unknown;
  try {
    data = JSON.parse(bodyText);
  } catch {
    return stubOutcome(
      base,
      emptyStubPath,
      `HTTP ${observed.status} but the response body is not JSON`,
      elapsed(),
      secrets,
      observed
    );
  }
  const advice = extractAdvice(data);
  const fields = {
    ...(advice.usage ? { usage: advice.usage } : {}),
    ...(advice.stopReason !== undefined ? { stopReason: advice.stopReason } : {}),
  };
  if (!advice.text) {
    return {
      ...stubOutcome(
        base,
        emptyStubPath,
        emptyAdviceReason(observed.status, advice),
        elapsed(),
        secrets,
        observed
      ),
      ...fields,
      ...(advice.emptyReason ? { emptyReason: advice.emptyReason } : {}),
    };
  }
  return {
    ...base,
    upstreamStatus: observed.status,
    upstreamStatusSource: observed.source,
    responseBytes: observed.bytes,
    latencyMs: elapsed(),
    origin: "upstream",
    stubPath: null,
    text: advice.text,
    ...fields,
  };
}

/** The panel section for a model that produced no advice. Names model and reason. */
function panelFailureSection(o: AdvisorModelOutcome): string {
  return `## ${o.requestedModel}\n[Error: ${o.requestedModel} returned no advice — ${o.reason}]`;
}

function allPanelFailedText(panel: AdvisorModelOutcome[]): string {
  if (panel.length === 0) {
    return `${ADVISOR_ERROR_PREFIX} No advisor model is configured, so no advice was produced. ${ADVISOR_ERROR_SUFFIX}`;
  }
  const head =
    panel.length === 1
      ? `The advisor model ${panel[0].requestedModel} did not return advice.`
      : `None of the ${panel.length} advisor models returned advice.`;
  const lines = panel.map((o) => `- ${o.requestedModel}: ${o.reason}`);
  return `${ADVISOR_ERROR_PREFIX} ${head}\n${lines.join("\n")}\n${ADVISOR_ERROR_SUFFIX}`;
}

function collectorFailedText(collector: AdvisorModelOutcome, sections: string[]): string {
  return (
    `${ADVISOR_ERROR_PREFIX} The collector model ${collector.requestedModel} failed to synthesize ` +
    `the advice: ${collector.reason}. The panel's unsynthesized answers follow.\n\n` +
    sections.join("\n\n")
  );
}

function modelCallRecord(
  kind: "advisor_call" | "advisor_collector_call",
  outcome: AdvisorModelOutcome,
  call: Pick<AdvisorCallOutcome, "toolUseId" | "sessionId">
): Record<string, unknown> {
  return {
    kind,
    event: kind,
    toolUseId: call.toolUseId,
    sessionId: call.sessionId,
    role: outcome.role,
    requestedModel: outcome.requestedModel,
    // The claudish provider that SERVED the call, never the planned one.
    provider: outcome.servedBy?.provider ?? null,
    route:
      outcome.recordRoute ??
      (outcome.route ? { kind: outcome.route.kind, host: outcome.route.host } : null),
    routedModel: outcome.routedModel ?? outcome.route?.wireModel ?? null,
    servedBy: outcome.servedBy ?? null,
    billing: outcome.billing ?? null,
    ...(outcome.hopsTried ? { hopsTried: outcome.hopsTried } : {}),
    ...claudeRecordFields(outcome),
    ...(outcome.usage ? { usage: outcome.usage } : {}),
    ...(outcome.emptyReason ? { emptyReason: outcome.emptyReason } : {}),
    ...(outcome.stopReason !== undefined && outcome.origin !== "upstream"
      ? { stopReason: outcome.stopReason }
      : {}),
    upstreamStatus: outcome.upstreamStatus,
    upstreamStatusSource: outcome.upstreamStatusSource,
    responseBytes: outcome.responseBytes,
    latencyMs: outcome.latencyMs,
    origin: outcome.origin,
    stubPath: outcome.stubPath,
    reason: outcome.reason ?? null,
  };
}

/** The Claude-only record fields (labels, never a value), when the outcome carries them. */
function claudeRecordFields(outcome: AdvisorModelOutcome): Record<string, unknown> {
  const claude = outcome as Partial<ClaudeAdvisorOutcome>;
  return {
    ...(claude.credentialSource !== undefined ? { credentialSource: claude.credentialSource } : {}),
    ...(claude.loginSkipped ? { loginSkipped: claude.loginSkipped } : {}),
    ...(claude.systemHead ? { systemHead: claude.systemHead } : {}),
    ...(claude.shapeRefusal ? { shapeRefusal: true } : {}),
  };
}

/**
 * Writes the P7 records for one call: one `advisor_call` per panel model, one
 * `advisor_collector_call` when a collector ran, and one `advisor_rewrite`.
 * Origin goes to the LOG only — never into the prompt or the advice text.
 */
function logAdvisorCallOutcome(cfg: AdvisorSwapConfig, o: AdvisorCallOutcome): void {
  for (const p of o.panel) logAdvisorEvent(cfg, modelCallRecord("advisor_call", p, o));
  if (o.collectorOutcome) {
    logAdvisorEvent(cfg, modelCallRecord("advisor_collector_call", o.collectorOutcome, o));
  }
  // `failedModels`: every panel member — and the collector, when it ran and
  // failed — whose origin is not `upstream`. Empty when nothing failed.
  //
  // WHY THE FIELD EXISTS. A PARTIAL panel failure (one member failed, another
  // answered, no collector) deliberately keeps `isError: false` and
  // `resultOrigin: "upstream"`: the model still receives the other members'
  // REAL advice, with the failure named in the text, and `is_error: true`
  // would tell it the whole call failed. That decision stands. But it left the
  // record for a partial failure indistinguishable from a clean one at a
  // glance — `originsByModel` carries the same truth, keyed per model, which
  // an audit has to walk. This is that truth as one flat list.
  const failedModels = [...o.panel, ...(o.collectorOutcome ? [o.collectorOutcome] : [])]
    .filter((m) => m.origin !== "upstream")
    .map((m) => m.requestedModel);
  logAdvisorEvent(cfg, {
    kind: "advisor_rewrite",
    event: "advisor_rewrite",
    toolUseId: o.toolUseId,
    sessionId: o.sessionId,
    panel: o.panel.map((p) => p.requestedModel),
    originsByModel: Object.fromEntries(o.panel.map((p) => [p.requestedModel, p.origin])),
    failedModels,
    collector: o.collector,
    collectorOrigin: o.collectorOutcome
      ? o.collectorOutcome.origin
      : o.collector
        ? ("absent" satisfies AdviceOrigin)
        : null,
    resultOrigin: o.resultOrigin,
    stubPath: o.stubPath,
    isError: o.result.isError,
  });
}

/** One warning per call in which any model failed, naming each model and reason. */
function warnOnAdvisorFailures(
  o: AdvisorCallOutcome,
  warn: (message: string) => void = warnAdvisor
): void {
  const failed = [...o.panel, ...(o.collectorOutcome ? [o.collectorOutcome] : [])].filter(
    (m) => m.origin !== "upstream"
  );
  if (failed.length === 0 && o.resultOrigin === "upstream") return;
  const detail =
    failed.length > 0
      ? failed
          .map(
            (m) => `${m.role === "collector" ? "collector " : ""}${m.requestedModel}: ${m.reason}`
          )
          .join("; ")
      : "no advisor model is configured";
  const verdict =
    o.resultOrigin === "upstream"
      ? "advice from the other models was still delivered"
      : "the model received an error report instead of advice";
  warn(`advisor call ${o.toolUseId} — ${detail} (${verdict})`);
}

/**
 * The call finished, but claudish could not attach its result to the tracked
 * call (`markAdvisorCallConsumed` returned false) — the state entry is gone.
 *
 * That return used to be ignored. The advice was then logged as
 * `origin: "upstream"` while the rewrite, finding no cached result, handed the
 * model `missingAdvisorResult` — a claudish error. The log said one thing and
 * the model saw another, which is the exact failure the provenance records
 * exist to make impossible. (An in-flight call can no longer be evicted, so
 * this is now defence in depth rather than the expected path.)
 *
 * Writes a CORRECTING `advisor_rewrite` record — the last record for a
 * tool-use id is the one that describes what the model received — listing every
 * model whose advice was lost in `failedModels`, and returns the text the model
 * gets instead.
 *
 * It also REPAIRS the state entry, because otherwise the model would receive
 * nothing at all: `rewriteAdvisorToolResults` only touches a block whose id is
 * tracked, and the id not being tracked is exactly why we are here. Re-recording
 * it makes the failure deliverable now and replayable on later turns, as any
 * other delivered result is.
 */
export function recoverUnassociatedAdvisorResult(
  cfg: AdvisorSwapConfig | undefined,
  outcome: AdvisorCallOutcome,
  warn: (message: string) => void = warnAdvisor
): AdvisorToolResult {
  const lost = [
    ...outcome.panel.map((p) => p.requestedModel),
    ...(outcome.collectorOutcome ? [outcome.collectorOutcome.requestedModel] : []),
  ];
  const result: AdvisorToolResult = {
    text:
      `${ADVISOR_ERROR_PREFIX} claudish could not associate the advisor answer with call ` +
      `${outcome.toolUseId}: its record was gone by the time the answer arrived, so the advice ` +
      `from ${lost.length > 0 ? lost.join(", ") : "the panel"} could not be delivered. ` +
      ADVISOR_ERROR_SUFFIX,
    isError: true,
  };
  const sessionId = outcome.sessionId ?? undefined;
  rememberAdvisorToolUseId(outcome.toolUseId, sessionId);
  markAdvisorCallConsumed(outcome.toolUseId, result, sessionId);
  log(
    `[advisor] call ${outcome.toolUseId}: the result could not be associated with the tracked call (stub path ${ADVISOR_STUB_PATHS.PREPARED_RESULT_MISSING})`
  );
  if (cfg) {
    logAdvisorEvent(cfg, {
      kind: "advisor_rewrite",
      event: "advisor_rewrite",
      toolUseId: outcome.toolUseId,
      sessionId: outcome.sessionId,
      // This record CORRECTS the one runAdvisorCall wrote for the same id.
      corrects: "advisor_rewrite",
      panel: outcome.panel.map((p) => p.requestedModel),
      originsByModel: Object.fromEntries(
        outcome.panel.map((p) => [p.requestedModel, "stub" satisfies AdviceOrigin])
      ),
      failedModels: lost,
      collector: outcome.collector,
      collectorOrigin: outcome.collectorOutcome ? ("stub" satisfies AdviceOrigin) : null,
      resultOrigin: "stub" satisfies AdviceOrigin,
      stubPath: ADVISOR_STUB_PATHS.PREPARED_RESULT_MISSING,
      isError: true,
    });
  }
  warn(
    `advisor call ${outcome.toolUseId}: the panel answered, but claudish no longer had a record of the call, so the model received an error report instead of the advice`
  );
  return result;
}

/** What a Claude member or collector needs from the main request, supplied by the decorator. */
export interface ClaudeAdvisorDeps {
  /**
   * The credential for this advisor call's Claude members, by presence and
   * provenance on the main request (`resolveClaudeAdvisorAuth`). Called only
   * when a Claude member runs, and memoised per advisor call, so a routed-only
   * panel never resolves an Anthropic key.
   */
  resolveAuth: () => Promise<ClaudeAdvisorAuth>;
  /** Test seam; defaults to the global fetch at call time. */
  fetchImpl?: typeof fetch;
}

export interface RunAdvisorCallParams {
  toolUseId: string;
  /** Claude Code session id of the request that consumed the call. */
  sessionId?: string;
  messages: any[];
  models: string[];
  collector: string | null;
  /** When given, the P7 records are written to its advisor log. */
  cfg?: AdvisorSwapConfig;
  /**
   * The startup plans and the routed members' chains. Absent ⇒ nothing was
   * planned for this launch, and every member is S7 (there is no lazy path).
   */
  gateway?: AdvisorPanelGateway;
  /** Absent ⇒ a Claude member has no credential and reports S7. */
  claude?: ClaudeAdvisorDeps;
  /**
   * Test seam: receives the per-failure warning. Defaults to the sanctioned
   * warning channel (`warnAdvisor` -> `logStderr`, which adds the `[advisor] `
   * prefix; the seam receives the message without it). Production callers
   * leave it unset.
   */
  warn?: (message: string) => void;
}

/** The plan for one member; a launch with no gateway planned nothing. */
function memberPlan(
  gateway: AdvisorPanelGateway | undefined,
  spec: string,
  role: "panel" | "collector"
): AdvisorModelPlan {
  return (
    gateway?.plan(spec, role) ?? {
      kind: "refused",
      spec,
      role,
      cause: "no-callable-hop",
      reason: "advisor runtime not planned for this launch",
    }
  );
}

/** The stub paths one role uses for an empty answer and for a failure. */
function stubPathsFor(
  role: "panel" | "collector",
  claude: boolean
): { empty: AdvisorStubPath; error: AdvisorStubPath } {
  if (role === "panel") {
    return { empty: ADVISOR_STUB_PATHS.PANEL_EMPTY, error: ADVISOR_STUB_PATHS.PANEL_ERROR };
  }
  return {
    empty: claude
      ? ADVISOR_STUB_PATHS.ANTHROPIC_COLLECTOR_EMPTY
      : ADVISOR_STUB_PATHS.COLLECTOR_EMPTY,
    error: ADVISOR_STUB_PATHS.COLLECTOR_FAILED,
  };
}

/** One member's request: who to ask, what to ask, and how long to wait. */
interface MemberRequest {
  spec: string;
  role: "panel" | "collector";
  system: string;
  turns: AdvisorTurn[];
  timeoutMs: number;
}

/**
 * Run one panel member or the collector by its startup plan: a refused plan
 * is S7/S9 with its refusal; a routed plan goes through the gateway's chain; a
 * Claude plan is one call to api.anthropic.com on the arm its credential
 * allows. Never rejects.
 */
async function runAdvisorMember(
  req: MemberRequest,
  params: Pick<RunAdvisorCallParams, "gateway" | "claude" | "warn">,
  claudeAuth: () => Promise<ClaudeAdvisorAuth>
): Promise<AdvisorModelOutcome> {
  const plan = memberPlan(params.gateway, req.spec, req.role);
  switch (plan.kind) {
    case "refused":
      return {
        ...stubOutcome(
          { role: req.role, requestedModel: req.spec, route: null },
          stubPathsFor(req.role, false).error,
          describeAdvisorRefusal(plan),
          0,
          []
        ),
        servedBy: null,
        billing: null,
      };
    case "routed":
      return runRoutedMember(plan, req, params.gateway, params.warn);
    case "claude-native":
      return runClaudeMember(plan, req, params, claudeAuth);
  }
}

async function runRoutedMember(
  plan: Extract<AdvisorModelPlan, { kind: "routed" }>,
  req: MemberRequest,
  gateway: AdvisorPanelGateway | undefined,
  warn?: (message: string) => void
): Promise<AdvisorModelOutcome> {
  const recordRoute: AdvisorRecordRoute = {
    kind: "routed",
    plannedChain: plan.hops.map((hop) => hop.displayName),
  };
  const base = { role: req.role, requestedModel: req.spec, route: null };
  const paths = stubPathsFor(req.role, false);
  if (!gateway) {
    return {
      ...stubOutcome(base, paths.error, "advisor gateway unavailable", 0, []),
      recordRoute,
      servedBy: null,
      billing: null,
    };
  }
  const result = await gateway.call({
    plan,
    payload: buildAdvisorPanelPayload(
      plan.hops[0].modelSpec,
      req.system,
      req.turns,
      ADVISOR_MAX_OUTPUT_TOKENS
    ),
    timeoutMs: req.timeoutMs,
  });
  const outcome = classifyPanelResult(result, base, paths);
  warnWhenServedUnlikePlan(req, result.plannedHop, outcome.servedBy, warn);
  return { ...outcome, recordRoute };
}

/**
 * The hop that last served each routed member, when its billing differs from
 * the hop the startup notice named, keyed `"<role>:<spec>"`. `FallbackHandler`
 * starts every later call at the last hop that served (`lastSuccessIndex`), so
 * after one transient subscription failure or one rejected subscription
 * credential that a metered hop answered, every later call of that member is
 * metered too — exactly as on main routing (R3).
 * That is accepted, but never silent: one line per change.
 */
const servedUnlikePlan = new Map<string, string>();

/**
 * Warn once per change when a routed call was served by a hop whose billing
 * differs from the startup notice's first callable hop:
 * `[advisor] <spec> was served by <displayName> (<billing>), not <planned> as
 * the notice said; later calls start there (routing keeps the last hop that
 * served)`. A call served as planned clears the record, so a later drift warns
 * again.
 */
function warnWhenServedUnlikePlan(
  req: MemberRequest,
  planned: AdvisorPanelResult["plannedHop"],
  servedBy: AdvisorServedBy | null | undefined,
  warn: (message: string) => void = warnAdvisor
): void {
  if (!planned || !servedBy?.billing) return;
  const key = `${req.role}:${req.spec}`;
  if (servedBy.billing === planned.billing) {
    servedUnlikePlan.delete(key);
    return;
  }
  const served = `${servedBy.provider}:${servedBy.billing}`;
  if (servedUnlikePlan.get(key) === served) return;
  servedUnlikePlan.set(key, served);
  warn(
    `${req.spec} was served by ${hopLabel(servedBy.displayName, servedBy.billing)}, ` +
      `not ${hopLabel(planned.displayName, planned.billing)} as the notice said; later ` +
      "calls start there (routing keeps the last hop that served)"
  );
}

/** The hop-log facts of a routed call: which hops were entered, and the last one. */
function routedHopFacts(result: AdvisorPanelResult): {
  hopsTried: string[];
  last: AdvisorPanelResult["hops"][number] | undefined;
} {
  const hopsTried: string[] = [];
  for (const hop of result.hops) {
    const uid = hop.uid ?? hop.provider;
    if (!hopsTried.includes(uid)) hopsTried.push(uid);
  }
  return { hopsTried, last: result.hops[result.hops.length - 1] };
}

/** The outcome of a routed call that answered with no advice: a stub on one of the role's paths. */
function routedStub(
  base: Pick<AdvisorModelOutcome, "role" | "requestedModel" | "route">,
  stubPath: AdvisorStubPath,
  reason: string,
  result: AdvisorPanelResult,
  hopsTried: string[],
  observed?: ObservedResponse
): AdvisorModelOutcome {
  return {
    ...stubOutcome(base, stubPath, reason, result.latencyMs, [], observed),
    hopsTried,
    servedBy: null,
    billing: null,
  };
}

/**
 * A gateway result as an outcome. The body was already redacted by value
 * against every credential the chain signed with; the reason is sanitised by
 * shape on top (`stubOutcome`). Status reads are `extractUpstreamStatus(body)
 * ?? status`, so a terminal error the 400 remap rewrote is reported with the
 * provider's own status.
 */
function classifyPanelResult(
  result: AdvisorPanelResult,
  base: Pick<AdvisorModelOutcome, "role" | "requestedModel" | "route">,
  paths: { empty: AdvisorStubPath; error: AdvisorStubPath }
): AdvisorModelOutcome {
  const { hopsTried, last } = routedHopFacts(result);
  if (result.failure || result.status === null) {
    const reason = result.failure?.message ?? "the advisor call produced no response";
    return routedStub(base, paths.error, reason, result, hopsTried);
  }
  const bodyStatus = extractUpstreamStatus(result.bodyText);
  const observed: ObservedResponse = {
    status: bodyStatus ?? result.status,
    source: bodyStatus !== undefined ? "error.upstream_status" : "http_status",
    bytes: new TextEncoder().encode(result.bodyText).byteLength,
  };
  const summary = summarizeErrorBody(result.bodyText);
  if (result.streamFailure) {
    const reason = `the stream failed after HTTP ${result.status}: ${summary}`;
    return routedStub(base, paths.error, reason, result, hopsTried, observed);
  }
  const httpOk = result.status >= 200 && result.status < 300;
  if (!httpOk || (bodyStatus !== undefined && bodyStatus >= 400)) {
    const reason = `HTTP ${observed.status}: ${summary}`;
    return routedStub(base, paths.error, reason, result, hopsTried, observed);
  }
  let data: unknown;
  try {
    data = JSON.parse(result.bodyText);
  } catch {
    const reason = `HTTP ${observed.status} but the response body is not JSON`;
    return routedStub(base, paths.empty, reason, result, hopsTried, observed);
  }
  const advice = extractAdvice(data);
  const usage = advice.usage ? { usage: advice.usage } : {};
  if (!advice.text) {
    return {
      ...routedStub(
        base,
        paths.empty,
        emptyAdviceReason(observed.status, advice),
        result,
        hopsTried,
        observed
      ),
      ...usage,
      ...(advice.emptyReason ? { emptyReason: advice.emptyReason } : {}),
      ...(advice.stopReason !== undefined ? { stopReason: advice.stopReason } : {}),
    };
  }
  const servedBy: AdvisorServedBy | null = last
    ? {
        provider: last.uid ?? last.provider,
        displayName: last.displayName,
        arm: last.arm,
        billing: last.billing,
      }
    : null;
  return {
    ...base,
    upstreamStatus: observed.status,
    upstreamStatusSource: observed.source,
    responseBytes: observed.bytes,
    latencyMs: result.latencyMs,
    origin: "upstream",
    stubPath: null,
    text: advice.text,
    hopsTried,
    servedBy,
    billing: servedBy?.billing ?? null,
    routedModel: last?.wireModel ?? null,
    ...usage,
  };
}

/** The display name of the native Anthropic provider, for `servedBy`. */
function nativeAnthropicDisplayName(): string {
  return getProviderByName("native-anthropic")?.displayName ?? "Anthropic (Native)";
}

async function runClaudeMember(
  plan: Extract<AdvisorModelPlan, { kind: "claude-native" }>,
  req: MemberRequest,
  params: Pick<RunAdvisorCallParams, "claude" | "warn">,
  claudeAuth: () => Promise<ClaudeAdvisorAuth>
): Promise<AdvisorModelOutcome> {
  const outcome = await runClaudeAdvisorCall({
    role: req.role,
    spec: req.spec,
    model: plan.model,
    auth: await claudeAuth(),
    system: req.system,
    turns: req.turns,
    timeoutMs: req.timeoutMs,
    ...(params.claude?.fetchImpl ? { fetchImpl: params.claude.fetchImpl } : {}),
    ...(params.warn ? { warn: params.warn } : {}),
  });
  const served = outcome.origin === "upstream" && outcome.servedArm !== null;
  return {
    ...outcome,
    recordRoute: { kind: "claude-native", host: ANTHROPIC_API_HOST },
    routedModel: plan.model,
    servedBy: served
      ? {
          provider: "native-anthropic",
          displayName: nativeAnthropicDisplayName(),
          arm: outcome.servedArm,
          billing: outcome.billing,
        }
      : null,
  };
}

/** One credential resolution per advisor call, and none unless a Claude member asks. */
function memoClaudeAuth(claude: ClaudeAdvisorDeps | undefined): () => Promise<ClaudeAdvisorAuth> {
  let pending: Promise<ClaudeAdvisorAuth> | undefined;
  return () => {
    pending ??= claude
      ? claude.resolveAuth()
      : Promise.resolve({
          arm: null,
          reason: "no Claude credential: the advisor was given no access to the main request",
          facts: {},
        });
    return pending;
  };
}

/** The panel's turns: the prepared transcript flattened to text. */
function panelTurns(panelMessages: any[]): AdvisorTurn[] {
  return convertToOpenAIMessages(panelMessages).map((m) => ({
    role: m.role === "assistant" ? "assistant" : "user",
    content: m.content,
  }));
}

/**
 * Runs one advisor call: every panel model in parallel, then the collector
 * when there is more than one answer to synthesize. Never rejects.
 *
 * Each member runs by its startup plan (`gateway.plan`): a routed member as
 * one in-process request through its startup-built chain, a Claude member as
 * one call to api.anthropic.com. The Claude credential is resolved at most
 * once per call, and only when a Claude member runs.
 *
 * The success path produces exactly the text it always did (R4): a single
 * model's answer as-is, the collector's synthesis, or — with no collector —
 * the `## model` sections. Failures produce plain text naming the model and
 * reason with `isError: true`, write the P7 log records, and raise one
 * warning.
 */
export async function runAdvisorCall(params: RunAdvisorCallParams): Promise<AdvisorCallOutcome> {
  const { toolUseId, messages, models, collector } = params;
  const claudeAuth = memoClaudeAuth(params.claude);

  // What the panel is ASKED: the transcript with claudish's own "No such tool"
  // plumbing for THIS call neutralised, and the advisor's question stated last.
  // Built once and shared by every panel model, so they all answer the same
  // question. Never mutates `messages` — it is the live upstream payload.
  const turns = panelTurns(prepareAdvisorPanelMessages(messages, toolUseId));

  const panel = await Promise.all(
    models.map((spec) =>
      runAdvisorMember(
        {
          spec,
          role: "panel",
          system: ADVISOR_SYSTEM_PROMPT,
          turns,
          timeoutMs: ADVISOR_PANEL_TIMEOUT_MS,
        },
        params,
        claudeAuth
      )
    )
  );
  const successful = panel.filter(
    (o): o is AdvisorModelOutcome & { text: string } => o.origin === "upstream"
  );
  const sections = panel.map((o) =>
    o.origin === "upstream" ? `## ${o.requestedModel}\n${o.text}` : panelFailureSection(o)
  );

  let result: AdvisorToolResult;
  let collectorOutcome: AdvisorModelOutcome | null = null;
  let resultOrigin: AdviceOrigin;
  let stubPath: AdvisorStubPath | null = null;

  if (models.length === 1 && successful.length === 1) {
    // Single advisor: its answer as-is.
    result = { text: successful[0].text, isError: false };
    resultOrigin = "upstream";
  } else if (successful.length === 0) {
    result = { text: allPanelFailedText(panel), isError: true };
    resultOrigin = "stub";
    stubPath = ADVISOR_STUB_PATHS.ALL_PANEL_FAILED;
  } else if (!collector) {
    // No collector: the sections verbatim.
    result = { text: sections.join("\n\n"), isError: false };
    resultOrigin = "upstream";
  } else {
    const adviceText = successful
      .map((o, i) => `### Advisor ${i + 1} (${o.requestedModel})\n${o.text}`)
      .join("\n\n");
    collectorOutcome = await runAdvisorMember(
      {
        spec: collector,
        role: "collector",
        system: COLLECTOR_SYSTEM_PROMPT,
        turns: [{ role: "user", content: adviceText }],
        timeoutMs: ADVISOR_COLLECTOR_TIMEOUT_MS,
      },
      params,
      claudeAuth
    );
    if (collectorOutcome.origin === "upstream" && collectorOutcome.text !== undefined) {
      result = { text: collectorOutcome.text, isError: false };
      resultOrigin = "upstream";
    } else {
      log(
        `[advisor] collector ${collector} failed: ${collectorOutcome.reason}, falling back to concat`
      );
      result = { text: collectorFailedText(collectorOutcome, sections), isError: true };
      resultOrigin = "stub";
      stubPath = collectorOutcome.stubPath;
    }
  }

  const outcome: AdvisorCallOutcome = {
    toolUseId,
    sessionId: params.sessionId ?? null,
    panel,
    collector,
    collectorOutcome,
    resultOrigin,
    stubPath,
    result,
  };

  log(
    `[advisor] call ${toolUseId}: resultOrigin=${resultOrigin}${stubPath ? ` stubPath=${stubPath}` : ""} ` +
      `origins=${panel.map((p) => `${p.requestedModel}:${p.origin}`).join(",")}` +
      (collectorOutcome
        ? ` collector=${collectorOutcome.requestedModel}:${collectorOutcome.origin}`
        : "")
  );
  if (params.cfg) logAdvisorCallOutcome(params.cfg, outcome);
  warnOnAdvisorFailures(outcome, params.warn);
  return outcome;
}