Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

72.4 KB
Raw Blame
/**
 * Shared sentinel and helpers for provider model resolution.
 *
 * Pure leaf (no Node built-ins, nothing outside server/lib), so the browser
 * imports it: client/src/utils/providerModels.js re-exports the sentinels,
 * effort ladders and the Antigravity split, and delegates its own ladder
 * resolution to `effortLevelsForProvider` / `clampEffortToLadder`;
 * client/src/utils/providerTypes.js re-exports the `isXProvider` predicates,
 * `commandBasename`, `localRuntimeNamespace`, `isOpencodeLocalProvider` and
 * `isCodexSubscriptionProvider`. One caveat the purity guard
 * cannot see: the Bedrock / Claude-argv resolvers below default to
 * `process.env`, so they are server-only — never call them from the browser
 * (they tree-shake out unless something does).
 */

import { gatewayIdForProvider, isGatewayNamespace } from './providerGateways.js';
import { isLocalInstanceEndpoint } from './localEndpoint.js';
import { isPlainObject } from './objects.js';

export const CODEX_CONFIGURED_DEFAULT = 'codex-configured-default';
export const ANTIGRAVITY_CONFIGURED_DEFAULT = 'antigravity-configured-default';
// Legacy opt-in sentinel: shipped Grok Build providers now pin a concrete model
// so displayed model, execution, and planner attribution agree.
export const GROK_CONFIGURED_DEFAULT = 'grok-configured-default';
// Kimi Code CLI/TUI: same posture as Grok/Antigravity — PortOS does not select a
// model; the local `kimi` binary uses its own configured default. Stored as a
// sentinel so pickers hide the model dropdown.
export const KIMI_CONFIGURED_DEFAULT = 'kimi-configured-default';

const CONFIGURED_DEFAULT_SENTINELS = new Set([
  CODEX_CONFIGURED_DEFAULT,
  ANTIGRAVITY_CONFIGURED_DEFAULT,
  GROK_CONFIGURED_DEFAULT,
  KIMI_CONFIGURED_DEFAULT,
]);

export const isCodexConfiguredDefault = (model) => model === CODEX_CONFIGURED_DEFAULT;

/** True for any provider "use CLI's own default" sentinel (Codex / Antigravity / Grok Build). */
export const isConfiguredDefaultModel = (model) => CONFIGURED_DEFAULT_SENTINELS.has(model);

/**
 * Normalize a provider `command` to its lowercase binary basename, stripping any
 * directory prefix and a Windows `.exe` suffix — e.g. `/opt/homebrew/bin/Grok.exe`
 * → `grok`. Returns `''` for empty/non-string input. The shared primitive behind
 * `isClaudeCommand`/`isOpencodeCommand`/`isGrokCommand` so the split/pop/case/.exe
 * rule lives in exactly one place. (Only `.exe` is stripped, matching the runner's
 * `shell:false` spawn path — a `.cmd`/`.bat` shim isn't directly spawnable.)
 * @param {string|null|undefined} command
 * @returns {string}
 */
export function commandBasename(command) {
  if (typeof command !== 'string' || command === '') return '';
  return command.split(/[\\/]/).pop().toLowerCase().replace(/\.exe$/, '');
}

/**
 * True when argv contains any of `flags`, in either separated (`--flag`) or
 * joined (`--flag=value`) form. The generic scan behind the per-vendor argv
 * builders (`grok.js`, `kimi.js`, `cursor.js`), which each carried a private
 * byte-identical copy until the third one made it a rule. Lives here next to
 * its siblings `hasModelFlag` / `hasEffortFlag` / `hasCodexUpdateCheckConfig`,
 * so a fix to the matching rule is one edit rather than an N-file sweep.
 * Non-string argv entries are skipped.
 * @param {unknown[]} args
 * @param {string[]} flags
 * @returns {boolean}
 */
export function argvHasFlag(args = [], flags = []) {
  return args.some((a) => typeof a === 'string' && flags.some((f) => a === f || a.startsWith(`${f}=`)));
}

/**
 * Put a POSITIONAL subcommand at the head of an argv unless it is already
 * there. Several vendors select headless mode with a bare word rather than a
 * flag — `opencode run`, `kilo run`, `openchamber session create` — and every
 * one of them has the same failure when it is missing: the bare binary opens an
 * interactive session that never consumes the piped prompt and hangs until the
 * provider timeout fires (issue #2190's shape for OpenCode).
 *
 * Presence is tested on the FIRST token only, so a record that pinned
 * `session send` keeps the subcommand the user chose instead of being rewritten
 * to `session create`. The check is `includes` rather than `args[0] ===` to
 * match what the three hand-written copies of this did before it became a rule:
 * a legacy record may carry a leading global flag ahead of the subcommand.
 *
 * @param {unknown[]} args
 * @param {string|string[]} subcommand - one word, or the words of a nested one
 * @returns {string[]} a new array; `args` is never mutated
 */
export function ensureLeadingSubcommand(args = [], subcommand) {
  const words = Array.isArray(subcommand) ? subcommand : [subcommand];
  return args.includes(words[0]) ? [...args] : [...words, ...args];
}

/**
 * Returns the model string to pass to a CLI's --model flag, or null if the
 * caller should omit --model entirely (configured-default sentinels — the CLI
 * uses its own default: Codex via ~/.codex/config.toml, Antigravity/Grok Build
 * via the binary's built-in latest model).
 * @param {string|null|undefined} model
 * @returns {string|null}
 */
export const resolveCliModel = (model) => isConfiguredDefaultModel(model) ? null : (model || null);

// ---------------------------------------------------------------------------
// Reasoning-effort levels — Claude Code (`--effort <level>`), Antigravity
// (`--effort <level>`) and Codex (`-c model_reasoning_effort=<level>`) all
// accept a per-invocation override of how hard the model thinks. Value sets
// verified against claude CLI v2.1.x (`--help`), current Codex CLI config
// values (`none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, plus
// model-gated `ultra`) and agy
// (`--help`: "Reasoning effort for the current CLI session (low|medium|high)").
// Re-exported by client/src/utils/providerModels.js, whose own
// `effortLevelsForProvider` layers the server-published `effortLevels` /
// `effortLevelsByModel` fields on top of these ladders.
//
// Codex Ultra adds automatic task delegation on the models that advertise it.
// Keep it model-gated: older Codex models and Luna top out at `max`.
//
// `minimal` is model-gated the other way — it is a gpt-5-era rung that the
// gpt-6 family dropped. See CODEX_NO_MINIMAL_MODEL_RE below.
//
// `none` is a real codex variant but is deliberately NOT offered: it means "do
// not reason at all", which no PortOS effort control should be able to select.
// ---------------------------------------------------------------------------

export const CLAUDE_EFFORT_LEVELS = Object.freeze(['low', 'medium', 'high', 'xhigh', 'max']);
export const CODEX_EFFORT_LEVELS = Object.freeze(['minimal', 'low', 'medium', 'high', 'xhigh', 'max']);
export const CODEX_ULTRA_EFFORT_LEVELS = Object.freeze([...CODEX_EFFORT_LEVELS, 'ultra']);
export const ANTIGRAVITY_EFFORT_LEVELS = Object.freeze(['low', 'medium', 'high']);
// OpenCode forwards this narrow OpenAI-compatible ladder as `reasoningEffort`
// to whichever local backend it is wired to (Ollama, llama.cpp, MTPLX,
// OrcaRouter). Keep it separate from vendor-CLI-only levels.
export const OPENCODE_LOCAL_EFFORT_LEVELS = Object.freeze(['low', 'medium', 'high']);

// A model behind that gateway can still refuse a rung of the ladder above: the
// value is forwarded verbatim to the upstream vendor, whose own contract
// decides. NVIDIA NIM answers Moonshot's Kimi K3 with HTTP 400
// `Unsupported Kimi K3 thinking_effort="medium"; supported values are low,
// high, and max` — so an effort the picker offered wedged the agent at launch
// with the prompt still sitting in the TUI (the same failure shape as codex's
// `minimal` rejection above, and handled the same way).
//
// Keyed on the MODEL, not the gateway: the rejection is Moonshot's contract,
// so it holds for Kimi K3 behind NIM, OpenRouter, or any other front end.
// Matched as a family prefix for the reason CODEX_NO_MINIMAL_MODEL_RE is —
// missing a new spelling reships the 400, while over-matching a build that
// would have taken `medium` only clamps it one rung down to `low`.
const OPENCODE_MODEL_EFFORT_LEVELS = Object.freeze([
  Object.freeze([/(^|\/)kimi-k3([.-]|$)/, Object.freeze(['low', 'high', 'max'])]),
]);

/**
 * The effort ladder an OpenCode run offers for one model — the portable
 * low/medium/high set, narrowed for the models whose upstream vendor rejects a
 * rung of it. A blank/unknown model gets the full ladder (never an empty one:
 * "we do not know this model" must not read as "this model has no effort").
 * @param {string|null|undefined} model - bare or namespace-prefixed id
 * @returns {readonly string[]}
 */
export function opencodeEffortLevelsForModel(model) {
  const id = String(model || '').trim().toLowerCase();
  if (!id) return OPENCODE_LOCAL_EFFORT_LEVELS;
  return OPENCODE_MODEL_EFFORT_LEVELS.find(([re]) => re.test(id))?.[1] ?? OPENCODE_LOCAL_EFFORT_LEVELS;
}

// Cursor Agent's ladder. Cursor has NO `--effort` flag — the level is a
// parameter of the model id itself (`gpt-5[effort=max]`), folded in by
// `foldCursorEffortIntoModel` — so `buildEffortArgs` deliberately emits nothing
// for cursor while this ladder still drives every picker. The tier NAMES are
// slashdo's documented `~effort=<level>` set (`low|medium|high|xhigh|max`), which
// is what `--review-with cursor[gpt-5]~effort=max` parses; keeping them
// identical is the point, since the same pin has to survive a round trip
// through slashdo.
export const CURSOR_EFFORT_LEVELS = Object.freeze(['low', 'medium', 'high', 'xhigh', 'max']);
// Grok Build CLI. `--reasoning-effort <EFFORT>` (aliased `--effort`, which is what
// `buildEffortArgs` emits). The ladder is grok's own, read off its rejection
// message rather than guessed: `grok --reasoning-effort bogus` answers
// `use one of: xhigh, high, medium, low` — so there is no `max`/`minimal` here,
// and `resolveCliEffort` clamps a stored `max`/`ultra` down to `xhigh`.
export const GROK_EFFORT_LEVELS = Object.freeze(['low', 'medium', 'high', 'xhigh']);

/** Union of every accepted effort value across effort-capable CLIs, low→high. */
export const EFFORT_LEVELS = Object.freeze([...new Set([
  ...CODEX_ULTRA_EFFORT_LEVELS,
  ...CLAUDE_EFFORT_LEVELS,
  ...ANTIGRAVITY_EFFORT_LEVELS,
  ...CURSOR_EFFORT_LEVELS,
])]);

const CODEX_ULTRA_MODELS = new Set(['gpt-5.6', 'gpt-5.6-sol', 'gpt-5.6-terra', 'gpt-6-astra', 'gpt-6.1-sol']);

// Models that REJECT `minimal`. The gpt-6 family dropped the rung: codex
// against `gpt-6-astra` answers HTTP 400 `unsupported_value` — "'minimal' is
// not supported with the 'gpt-6-astra' model. Supported values are: 'low',
// 'medium', 'high', 'xhigh', and 'max'." — so a picker that offers it hands the
// user a level whose only outcome is a failed run.
//
// Matched as a FAMILY prefix rather than an id list, deliberately: the two
// failure directions are not symmetric. Missing a new gpt-6/7 model ships that
// 400 again, while over-matching a model that does still accept `minimal` costs
// it only its weakest rung (a stored `minimal` clamps up to `low`).
const CODEX_NO_MINIMAL_MODEL_RE = /^gpt-[6-9]([.-]|$)/;

const withoutMinimal = (levels) => Object.freeze(levels.filter((l) => l !== 'minimal'));
const CODEX_EFFORT_LEVELS_NO_MINIMAL = withoutMinimal(CODEX_EFFORT_LEVELS);
const CODEX_ULTRA_EFFORT_LEVELS_NO_MINIMAL = withoutMinimal(CODEX_ULTRA_EFFORT_LEVELS);

export const codexEffortLevelsForModel = (model) => {
  const id = String(model || '').trim().toLowerCase();
  const ultra = CODEX_ULTRA_MODELS.has(id);
  if (CODEX_NO_MINIMAL_MODEL_RE.test(id)) {
    return ultra ? CODEX_ULTRA_EFFORT_LEVELS_NO_MINIMAL : CODEX_EFFORT_LEVELS_NO_MINIMAL;
  }
  return ultra ? CODEX_ULTRA_EFFORT_LEVELS : CODEX_EFFORT_LEVELS;
};

// ---------------------------------------------------------------------------
// Antigravity base-model ↔ effort-suffix split.
//
// `agy models` enumerates the effort tiers as separate model ids
// (`gemini-3.6-flash-low|-medium|-high`), which forces the user to pick their
// reasoning effort *inside* the model dropdown. agy also accepts the BASE id
// with a separate `--effort` flag (`--model gemini-3.6-flash --effort high`) —
// verified against the real binary — so PortOS lists base models and carries
// effort as its own control.
//
// agy validates the PAIR, though: `--model gemini-3.1-pro --effort medium`
// errors with `gemini-3.1-pro has no "medium" effort (available: low, high)`.
// So the tiers a base model offers are derived from the provider's own model
// catalog rather than assumed to be the full low/medium/high ladder.
// Re-exported by client/src/utils/providerModels.js.
// ---------------------------------------------------------------------------

const ANTIGRAVITY_EFFORT_SUFFIX_RE = new RegExp(`-(${ANTIGRAVITY_EFFORT_LEVELS.join('|')})$`);

/**
 * Split an Antigravity model id into its base id and baked-in effort tier —
 * `gemini-3.6-flash-high` → `{ base: 'gemini-3.6-flash', effort: 'high' }`.
 * Ids with no effort suffix (`claude-sonnet-4-6`), configured-default sentinels,
 * and non-strings come back as `{ base: <input>, effort: null }`.
 * @param {string|null|undefined} id
 * @returns {{base: string|null|undefined, effort: string|null}}
 */
export function splitAntigravityModel(id) {
  if (typeof id !== 'string' || id === '' || isConfiguredDefaultModel(id)) {
    return { base: id, effort: null };
  }
  const match = ANTIGRAVITY_EFFORT_SUFFIX_RE.exec(id);
  return match
    ? { base: id.slice(0, -match[0].length), effort: match[1] }
    : { base: id, effort: null };
}

/**
 * The user-selectable view of an Antigravity model list: effort suffixes
 * stripped, duplicates collapsed, original order preserved. Configured-default
 * sentinels and non-string entries (`{ id, name }` objects some pickers pass)
 * ride through untouched so callers can hand this any `provider.models`.
 * @param {unknown[]} models
 * @returns {unknown[]}
 */
export function antigravityBaseModels(models) {
  const out = [];
  const seen = new Set();
  for (const entry of Array.isArray(models) ? models : []) {
    if (typeof entry !== 'string') {
      out.push(entry);
      continue;
    }
    const { base } = splitAntigravityModel(entry);
    if (seen.has(base)) continue;
    seen.add(base);
    out.push(base);
  }
  return out;
}

/**
 * The effort tiers an Antigravity base model actually offers, read off the
 * provider's own model catalog:
 *   - `['low','high']` — the suffixed variants present for that base.
 *   - `[]`             — the base is in the catalog with no suffixed variants
 *                        (`claude-sonnet-4-6`): agy has no effort knob for it.
 *   - `null`           — the model is UNKNOWN (blank, the configured-default
 *                        sentinel, or an empty catalog), so the caller should
 *                        fall back to the full ladder rather than assume none.
 *                        The sentinel case matters: it is the shipped agy
 *                        `defaultModel`, and reporting `[]` for it would hide
 *                        the effort control on every freshly-opened picker.
 * @param {string|null|undefined} model - base or suffixed model id
 * @param {unknown[]} models - the provider's model list
 * @returns {readonly string[]|null}
 */
export function antigravityModelEffortLevels(model, models) {
  const list = (Array.isArray(models) ? models : []).filter(m => typeof m === 'string');
  if (list.length === 0) return null;
  if (isConfiguredDefaultModel(model)) return null;
  const { base } = splitAntigravityModel(model);
  if (typeof base !== 'string' || base === '') return null;
  return Object.freeze(ANTIGRAVITY_EFFORT_LEVELS.filter(level => list.includes(`${base}-${level}`)));
}

/**
 * Is `id` a model the install's agy catalog still lists?
 *
 * Compared on BASE ids: once `--effort` carries the tier, `gemini-3.6-flash`
 * and `gemini-3.6-flash-low` are the same `--model` value, and a tier the base
 * does not offer is clamped by `antigravityModelEffortLevels` rather than being
 * a different model.
 *
 * An EMPTY catalog answers `true`. "We have no catalog" must never read as "the
 * model is gone" — the list is empty on a fresh install, when the provider
 * service isn't initialized, and whenever the `agy models` probe failed — and a
 * false negative there would swap out a model that works.
 *
 * @param {string} id - base or suffixed model id (a blank one reads as unlisted;
 *   callers ask this about a pin they already hold)
 * @param {unknown[]|null|undefined} models - the provider's model catalog
 * @returns {boolean}
 */
export function antigravityCatalogListsModel(id, models) {
  const bases = antigravityBaseModels((Array.isArray(models) ? models : []).filter(m => typeof m === 'string'));
  return !bases.length || bases.includes(splitAntigravityModel(id).base);
}

/**
 * The cheapest catalog entry that can drive an unattended agy relay — the tier
 * to pick on the user's behalf when an agent is needed only to issue one tool
 * call and does no creative work of its own. Today's caller is image gen's
 * shipped pin, `AGY_IMAGEGEN_DEFAULT_MODEL`, whose comment carries the whole
 * rationale and the incident that made a frozen id untenable.
 *
 * Re-derives that choice from whatever the catalog currently holds, in agy's
 * own listed order (newest first):
 *
 *   1. a flash model at the weakest effort tier — cheapest, and empirically
 *      enough to relay a tool call;
 *   2. any model at that tier, when no flash model is listed at all;
 *   3. any flash model, when the catalog exposes no effort suffixes;
 *   4. `null` — nothing cheap is listed, so the caller keeps what it had rather
 *      than escalating onto a reasoning-heavy tier (`claude-opus-4-6-thinking`)
 *      behind the user's back.
 *
 * The tier is read off `ANTIGRAVITY_EFFORT_LEVELS` rather than spelled `low`,
 * so a renamed ladder moves this with it. "flash" stays a literal: it is
 * Google's own family name, not something PortOS derives.
 *
 * @param {unknown[]|null|undefined} models - the provider's model catalog
 * @returns {string|null}
 */
export function pickAntigravityRelayModel(models) {
  const cheapest = ANTIGRAVITY_EFFORT_LEVELS[0];
  const tiers = filterSelectableModels((Array.isArray(models) ? models : []).filter(m => typeof m === 'string'))
    .map(id => ({ id, ...splitAntigravityModel(id) }));
  const pick = (match) => tiers.find(match)?.id;
  return pick(m => m.effort === cheapest && m.base.includes('flash'))
    || pick(m => m.effort === cheapest)
    || pick(m => m.base.includes('flash'))
    || null;
}

/**
 * True when a provider is codex-flavored — the shipped `codex`/`codex-tui`
 * provider ids or any provider whose launch command basename is `codex`
 * (path/exe tolerant). The single home for the codex signature, same posture
 * as `isClaudeCommand`/`isOpencodeCommand`.
 * @param {{id?:string, command?:string}|null|undefined} provider
 * @returns {boolean}
 */
export function isCodexProvider(provider) {
  const id = String(provider?.id || '').toLowerCase();
  return id === 'codex' || id === 'codex-tui' || commandBasename(provider?.command) === 'codex';
}

/**
 * True when a CLI/TUI record runs on Codex's ChatGPT subscription — what the
 * account half of the Codex providers (`codexAccount.js`, #5589) keys its
 * readiness on.
 *
 * Keyed on the COMMAND, not the id: a user who cloned `codex` into
 * `codex-review` still runs the same binary against the same ChatGPT sign-in,
 * and hard-coding two ids would leave that card blank. API providers are
 * excluded — an OpenAI API-key provider authenticates with its own stored key
 * and has nothing to do with a subscription. So is a local-runtime-backed codex
 * record (`codex --oss --local-provider ollama`): it generates its tokens on
 * this machine and authenticates against nothing, and without that exclusion
 * the card would paint "No ChatGPT account is signed in" on a provider that
 * needs no account and sit in UNKNOWN until an account read that will never
 * matter answers.
 *
 * Lives here rather than in `codexAccount.js` so the browser, which re-exports
 * it through client/src/utils/providerTypes.js, does not also carry that
 * module's frozen protocol tables — top-level `Object.freeze` calls the bundler
 * cannot shake.
 * @param {{type?:string, command?:string}|null|undefined} provider
 * @returns {boolean}
 */
export function isCodexSubscriptionProvider(provider) {
  if (provider?.type !== 'cli' && provider?.type !== 'tui') return false;
  const command = typeof provider?.command === 'string' ? provider.command.trim() : '';
  if (command === '') return false;
  if (commandBasename(command) !== 'codex') return false;
  return localRuntimeNamespace(provider) === null;
}

/**
 * True when a provider is Grok-Build-flavored — the shipped `grok-cli`/`grok-tui`
 * ids or any provider whose launch command basename is `grok`. Same posture as
 * `isCodexProvider`, and deliberately defined here rather than imported from
 * `grok.js`: that module imports THIS one, so importing back would cycle.
 *
 * The bare `grok` id is the HTTP API provider, which has no CLI to pass a flag
 * to — it is excluded so it gets no effort ladder.
 * @param {{id?:string, command?:string}|null|undefined} provider
 * @returns {boolean}
 */
export function isGrokProvider(provider) {
  const id = String(provider?.id || '').toLowerCase();
  return id === 'grok-cli' || id === 'grok-tui' || commandBasename(provider?.command) === 'grok';
}

/**
 * True when a provider is Claude-Code-flavored — a `claude-code*` provider id or
 * any provider whose launch command basename is `claude` (path/exe tolerant).
 *
 * Unlike `isClaudeCommand`, a BLANK command does not count: this identifies a
 * provider positively, and callers that gate a Claude-only capability on it must
 * not treat "unknown" as Claude. Same posture as `effortLevelsForProvider`, which
 * this replaces the inline copy of.
 * @param {{id?:string, command?:string}|null|undefined} provider
 * @returns {boolean}
 */
export function isClaudeProvider(provider) {
  if (!provider) return false;
  return String(provider.id || '').toLowerCase().startsWith('claude-code')
    || commandBasename(provider.command) === 'claude';
}

/**
 * True when a provider is OpenCode-flavored — the shipped `opencode`/`opencode-tui`
 * ids or any provider whose launch command basename is `opencode`. The
 * provider-shaped companion to `isOpencodeCommand`, same posture as
 * `isCodexProvider`.
 * @param {{id?:string, command?:string}|null|undefined} provider
 * @returns {boolean}
 */
export function isOpencodeProvider(provider) {
  const id = String(provider?.id || '').toLowerCase();
  return id === 'opencode' || id === 'opencode-tui' || isOpencodeCommand(provider?.command);
}

/**
 * True when a provider is Kimi-Code-flavored — the shipped `kimi-cli`/`kimi-tui`
 * ids or any provider whose launch command basename is `kimi` (path/exe tolerant).
 * The single home for the kimi signature, same posture as `isCodexProvider`.
 * Re-exported by client/src/utils/providerTypes.js, so it stays browser-safe.
 * @param {{id?:string, command?:string}|null|undefined} provider
 * @returns {boolean}
 */
export function isKimiProvider(provider) {
  const id = String(provider?.id || '').toLowerCase();
  return id === 'kimi-cli' || id === 'kimi-tui' || commandBasename(provider?.command) === 'kimi';
}

/**
 * True when a provider is Antigravity-flavored — the shipped
 * `antigravity-cli`/`antigravity-tui` ids or any provider whose launch command
 * basename is `agy`/`antigravity` (path/exe tolerant). The provider-shaped
 * companion to `isAntigravityCommand` in antigravity.js; lives here (rather
 * than there) so `effortLevelsForProvider` can key on it without this
 * dependency-light module importing a sibling. Re-exported by
 * client/src/utils/providerTypes.js, so it stays browser-safe.
 * @param {{id?:string, command?:string}|null|undefined} provider
 * @returns {boolean}
 */
export function isAntigravityProvider(provider) {
  if (!provider) return false;
  // A composite/derived record names its harness outright (#7564) and may
  // carry no command at all, so the harness id is the first word.
  if (provider.harnessId === 'antigravity') return true;
  const id = String(provider.id || '').toLowerCase();
  if (id === 'antigravity-cli' || id === 'antigravity-tui') return true;
  const base = commandBasename(provider.command);
  return base === 'agy' || base === 'antigravity';
}

/**
 * True when a provider is Cursor-Agent-flavored — the shipped `cursor-cli` /
 * `cursor-tui` ids or any provider whose launch command basename is
 * `cursor-agent` (path/exe tolerant). The provider-shaped companion to
 * `isCursorCommand` in cursor.js; lives here (rather than there) for the same
 * reason `isAntigravityProvider` does — so `effortLevelsForProvider` and
 * `buildEffortArgs` can key on it without this dependency-light module importing
 * a sibling vendor file that already imports IT.
 *
 * Deliberately never matches a bare `cursor` command: that is Cursor's GUI
 * editor launcher, not the agent binary (see cursor.js).
 * Re-exported by client/src/utils/providerTypes.js, so it stays browser-safe.
 * @param {{id?:string, command?:string}|null|undefined} provider
 * @returns {boolean}
 */
export function isCursorProvider(provider) {
  if (!provider) return false;
  const id = String(provider.id || '').toLowerCase();
  return id === 'cursor-cli' || id === 'cursor-tui' || commandBasename(provider.command) === 'cursor-agent';
}

/**
 * Fold a reasoning-effort level into a Cursor model id using Cursor's own
 * model-variant syntax, because `cursor-agent` has NO `--effort` flag and exits
 * non-zero when passed one. Three cases, matching slashdo's fold in
 * `lib/local-agent-review-loop.md` exactly (the same pin has to mean the same
 * invocation whether PortOS or slashdo builds it):
 *
 *   - `gpt-5` + `max`                       → `gpt-5[effort=max]`
 *   - `claude-opus-4-7[thinking=true]` + `high` → `claude-opus-4-7[thinking=true,effort=high]`
 *   - a model that ALREADY names `effort=`  → returned unchanged (the explicit
 *     variant the user typed wins over the ladder pin)
 *
 * Returns the model unchanged when there is no effort, and `null` when there is
 * no model — an effort with nothing to attach to is dropped rather than emitted
 * as a flag Cursor would reject.
 * @param {string|null|undefined} model
 * @param {string|null|undefined} effort
 * @returns {string|null}
 */
export function foldCursorEffortIntoModel(model, effort) {
  const id = typeof model === 'string' ? model.trim() : '';
  if (!id) return null;
  const level = typeof effort === 'string' ? effort.trim() : '';
  if (!level) return id;
  if (id.includes('effort=')) return id;
  if (id.endsWith(']')) return `${id.slice(0, -1)},effort=${level}]`;
  return `${id}[effort=${level}]`;
}

/**
 * The effort levels a provider's CLI accepts, or null when the provider has no
 * effort control (opencode, grok, kimi, HTTP API providers). Keyed on the
 * launch command basename (plus the shipped provider ids) so path-configured or
 * renamed claude/codex/agy providers still qualify — same detection posture as
 * `isClaudeCommand`/`isOpencodeCommand`. A blank command does NOT default to
 * Claude here (unlike `isClaudeCommand`): effort is an opt-in enhancement, and
 * only a provider we can positively identify should advertise levels.
 *
 * `model` narrows the Antigravity ladder to the tiers that base model actually
 * offers (agy rejects `gemini-3.1-pro --effort medium`), read off
 * `provider.models`. It ALSO narrows the OpenCode ladder for a model whose
 * upstream vendor rejects a rung (NVIDIA NIM 400s Kimi K3 on `medium` — see
 * `opencodeEffortLevelsForModel`). Omit it — or leave the catalog empty — to get the full
 * low/medium/high ladder. Returns null for an Antigravity model the catalog
 * says has no tiers at all (`claude-sonnet-4-6`), so no `--effort` is emitted.
 *
 * A ladder here does NOT imply an `--effort` flag: cursor advertises levels but
 * carries them inside `--model` (`foldCursorEffortIntoModel`), so
 * `buildEffortArgs` returns `[]` for it. Ask this function "can the user pick a
 * level?", and `buildEffortArgs` "what argv does that level become?".
 * @param {{id?:string, command?:string, models?:unknown[]}|null|undefined} provider
 * @param {string|null} [model]
 * @returns {readonly string[]|null}
 */
export function effortLevelsForProvider(provider, model = null) {
  if (!provider) return null;
  // A record materialized from a composite id names its harness (#7564); each
  // arm honors that before sniffing the command, so a path-configured binary or
  // a bootstrap-wrapped spawn still offers its rungs.
  const harness = provider.harnessId ?? null;
  if (harness === 'opencode' || isOpencodeLocalProvider(provider)) {
    return isOpencodeLocalProvider(provider) ? opencodeEffortLevelsForModel(model) : null;
  }
  if (harness === 'codex' || isCodexProvider(provider)) return codexEffortLevelsForModel(model);
  if (harness === 'antigravity' || isAntigravityProvider(provider)) {
    const perModel = model ? antigravityModelEffortLevels(model, provider.models) : null;
    if (perModel === null) return ANTIGRAVITY_EFFORT_LEVELS;
    return perModel.length ? perModel : null;
  }
  if (harness === 'pi' || commandBasename(provider.command) === 'pi') return PI_EFFORT_LEVELS;
  if (harness === 'cursor' || isCursorProvider(provider)) return CURSOR_EFFORT_LEVELS;
  if (harness === 'grok' || isGrokProvider(provider)) return GROK_EFFORT_LEVELS;
  if (harness === 'claude' || isClaudeProvider(provider)) return CLAUDE_EFFORT_LEVELS;
  return null;
}

/** Pi's reasoning ladder (`pi --effort`). */
const PI_EFFORT_LEVELS = Object.freeze(['low', 'medium', 'high', 'xhigh', 'max']);

// Every effort value any CLI accepts, ordered weakest→strongest. The clamp
// below walks this so an effort saved against one provider survives a switch to
// a provider with a narrower ladder (agy tops out at `high`; claude has no
// `minimal`/`ultra`) instead of vanishing.
const EFFORT_RANK = Object.freeze(['minimal', 'low', 'medium', 'high', 'xhigh', 'max', 'ultra']);

/**
 * Resolve a stored effort override to the value the provider's CLI actually
 * accepts, or null when the flag should be omitted entirely (no override set,
 * provider has no effort control, or the value isn't a known effort at all).
 * An out-of-range value is clamped to the nearest supported level at or below
 * it (`ultra`→`max` on claude and Codex models without Ultra,
 * `xhigh`/`max`/`ultra`→`high` on agy), falling back to the provider's weakest
 * level when nothing sits below it (`minimal`→`low`) — rather than being
 * dropped.
 * @param {string|null|undefined} effort
 * @param {{id?:string, command?:string, models?:unknown[]}|null|undefined} provider
 * @param {string|null} [model] - narrows the Antigravity ladder (see effortLevelsForProvider)
 * @returns {string|null}
 */
export function resolveCliEffort(effort, provider, model = null) {
  return clampEffortToLadder(effort, effortLevelsForProvider(provider, model));
}

/**
 * The clamp behind `resolveCliEffort`, over an explicit ladder: the effort
 * itself when `levels` has it, else the nearest supported level below it, else
 * the ladder's weakest — or null when there is no effort, no ladder, or the
 * value is not an effort at all. The client's `resolveCliEffort` clamps its own
 * ladder (which can come from the server-published fields) through this, so
 * the two ends can't rank the rungs differently.
 * @param {string|null|undefined} effort
 * @param {readonly string[]|null|undefined} levels
 * @returns {string|null}
 */
export function clampEffortToLadder(effort, levels) {
  if (!effort || !levels) return null;
  if (levels.includes(effort)) return effort;
  const requested = EFFORT_RANK.indexOf(effort);
  if (requested === -1) return null; // not an effort value at all
  const supported = levels.map(l => EFFORT_RANK.indexOf(l)).filter(i => i !== -1).sort((a, b) => a - b);
  if (supported.length === 0) return null;
  const below = supported.filter(i => i < requested);
  return EFFORT_RANK[below.length ? below[below.length - 1] : supported[0]];
}

// Codex's config key (set via `-c <key>=<value>`) that carries the reasoning
// effort. Named for the same reason as CODEX_UPDATE_CHECK_KEY below: the string
// is matched in one place, emitted in another, and read back by the error
// analyzer when a config rejection has to be blamed on PortOS or on the user.
export const CODEX_EFFORT_KEY = 'model_reasoning_effort';

// Every spelling of the effort flag a provider CLI accepts as a VALUE-taking
// argument. `--reasoning-effort` is grok's canonical long form (`--effort` is its
// documented alias, and the alias is what buildEffortArgs emits) — it has to be
// recognized here or a user who baked `--reasoning-effort high` into their
// provider args gets a SECOND, injected `--effort <level>` appended. Grok's
// parser accepts the duplicate and takes the last one, so their explicit pin
// would be silently overridden — the exact opposite of the contract below.
// Pi's --thinking is also a value-taking effort pin; shared stripping keeps
// per-run overrides consistent when switching providers.
const EFFORT_FLAG_NAMES = Object.freeze(['--effort', '--reasoning-effort', '--thinking']);

/** Remove saved model/effort pins only when a caller explicitly owns those selections.
 * Preserve transport, account, permission and unrelated config arguments.
 */
export function stripProviderPinArgs(args, { model = false, effort = false } = {}) {
  const flags = [...(model ? ['--model', '-m'] : []), ...(effort ? EFFORT_FLAG_NAMES : [])];
  const configPin = value => typeof value === 'string' && ((model && value.startsWith('model=')) || (effort && value.startsWith(`${CODEX_EFFORT_KEY}=`)));
  const result = [];
  for (let i = 0; i < args.length; i++) {
    const arg = args[i];
    if (flags.includes(arg)) {
      if (typeof args[i + 1] === 'string' && !args[i + 1].startsWith('-')) i++;
      continue;
    }
    if (flags.some(flag => arg.startsWith(`${flag}=`))) continue;
    if ((arg === '-c' || arg === '--config') && configPin(args[i + 1])) { i++; continue; }
    if ((arg.startsWith('-c=') && configPin(arg.slice(3))) || (arg.startsWith('--config=') && configPin(arg.slice(9)))) continue;
    result.push(arg);
  }
  return result;
}

/**
 * True when the user has already baked an effort override into the provider's
 * args — claude/agy/grok's `--effort <level>` / `--effort=<level>`, grok's
 * `--reasoning-effort` long form, or a codex `-c model_reasoning_effort=…`
 * config pair. Mirrors `hasModelFlag`: a baked pin wins and the
 * runner-injected effort is suppressed.
 * @param {unknown[]} args
 * @returns {boolean}
 */
export function hasEffortFlag(args) {
  if (!Array.isArray(args)) return false;
  return args.some((a, i) => {
    if (typeof a !== 'string') return false;
    for (const flag of EFFORT_FLAG_NAMES) {
      if (a.startsWith(`${flag}=`) && a.length > flag.length + 1) return true;
      if (a === flag) {
        const next = args[i + 1];
        if (typeof next === 'string' && next.length > 0 && !next.startsWith('-')) return true;
      }
    }
    return a.startsWith(`${CODEX_EFFORT_KEY}=`);
  });
}

/**
 * The argv fragment that applies an effort override to an effort-capable CLI:
 * `['--effort', <level>]` for claude and agy, `['-c', 'model_reasoning_effort=<level>']`
 * for codex, `[]` when the flag should be omitted (no override, provider has no
 * effort control, or a user-baked pin already sits in `existingArgs`). The one
 * home for both the detection AND the arg shape, so the two can't drift — spawn
 * builders just spread the result.
 *
 * **Cursor always gets `[]`, even though it HAS a ladder.** `cursor-agent`
 * exposes no `--effort` flag and exits non-zero when handed one; its effort is a
 * model-variant parameter, so cursor spawn builders fold the level into
 * `--model` with `foldCursorEffortIntoModel` instead of spreading this.
 * @param {string|null|undefined} effort
 * @param {{id?:string, command?:string, models?:unknown[]}|null|undefined} provider
 * @param {unknown[]} [existingArgs]
 * @param {string|null} [model] - narrows the Antigravity ladder (see effortLevelsForProvider)
 * @returns {string[]}
 */
export function buildEffortArgs(effort, provider, existingArgs = [], model = null) {
  const effectiveEffort = resolveCliEffort(effort, provider, model);
  if (!effectiveEffort || hasEffortFlag(existingArgs)) return [];
  if (commandBasename(provider?.command) === 'pi') return ['--thinking', effectiveEffort];
  if (isCursorProvider(provider)) return []; // rides `--model`, not a flag — see above
  return isCodexProvider(provider)
    ? ['-c', `${CODEX_EFFORT_KEY}=${effectiveEffort}`]
    : ['--effort', effectiveEffort];
}

// Codex's config key (set via `-c <key>=<value>`) that gates its startup
// update check. Kept as a named constant so a codex-side rename is a one-line
// edit rather than a four-builder grep.
export const CODEX_UPDATE_CHECK_KEY = 'check_for_update_on_startup';
export const CODEX_AGENT_THREADS_KEY = 'agents.max_concurrent_threads_per_session';
// Forced off/empty for autofixer repairs (#12487): no network or writes outside
// the cwd in the workspace-write sandbox, and no plugin/app tools beside it.
export const CODEX_WORKSPACE_NETWORK_KEY = 'sandbox_workspace_write.network_access';
export const CODEX_WORKSPACE_WRITABLE_ROOTS_KEY = 'sandbox_workspace_write.writable_roots';
export const CODEX_PLUGINS_FEATURE_KEY = 'features.plugins';
export const CODEX_APPS_FEATURE_KEY = 'features.apps';
export const CODEX_HOOKS_FEATURE_KEY = 'features.hooks';

/**
 * Give a Codex swarm enough session threads for its root orchestrator plus
 * every configured worker. The CLI counts the root against this limit, so a
 * six-worker claim run needs seven threads rather than six.
 *
 * Callers deliberately supply this only for cloud-backed Codex agents. Local
 * inference stays bounded by its runtime-specific concurrency posture instead
 * of turning one CoS task into an unbounded fan-out against a single GPU.
 *
 * @param {unknown} maxConcurrentThreads
 * @returns {string[]}
 */
export function buildCodexAgentThreadArgs(maxConcurrentThreads) {
  const limit = Number(maxConcurrentThreads);
  if (!Number.isSafeInteger(limit) || limit < 1) return [];
  return ['-c', `${CODEX_AGENT_THREADS_KEY}=${limit}`];
}

/**
 * True when the codex argv already pins the startup-update-check config, so a
 * caller-supplied value wins over the injected default. Null-safe. Recognizes
 * every codex override syntax for the key: the separate-arg value element of
 * `-c <key>=<v>` / `--config <key>=<v>` (which arrives as a standalone
 * `<key>=<v>` token), AND the joined forms `--config=<key>=<v>` / `-c=<key>=<v>`
 * (a single token). Missing the joined form would inject a second, conflicting
 * `-c <key>=false` that silently overrides the user's explicit value.
 * @param {unknown[]} args
 * @returns {boolean}
 */
export function hasCodexUpdateCheckConfig(args) {
  if (!Array.isArray(args)) return false;
  const pin = `${CODEX_UPDATE_CHECK_KEY}=`;
  return args.some((a) => {
    if (typeof a !== 'string') return false;
    if (a.startsWith(pin)) return true; // standalone value of `-c`/`--config <key>=<v>`
    // Joined `--config=<key>=<v>` / `-c=<key>=<v>` — strip the flag prefix, then test.
    const joined = a.startsWith('--config=') ? a.slice(9) : a.startsWith('-c=') ? a.slice(3) : null;
    return joined !== null && joined.startsWith(pin);
  });
}

/**
 * The argv fragment that disables codex's interactive startup update check:
 * `['-c', 'check_for_update_on_startup=false']`, or `[]` when a user-baked pin
 * already sits in `existingArgs`. Codex checks GitHub for a newer release on
 * every startup and, if one exists, an interactive run renders a BLOCKING
 * "Update available! → 1. Update now" modal — a headless agent's submit-Enter
 * lands on "Update now", triggering a ~100MB `brew upgrade` it can't complete,
 * and the session dies without processing the prompt. Non-interactive `codex
 * exec` runs never render the modal but still pay the check's network cost (and
 * can trip an unattended upgrade), so every codex spawn builder spreads this.
 * The one home for both the detection and the arg shape, so they can't drift.
 * @param {unknown[]} [existingArgs]
 * @returns {string[]}
 */
export function buildCodexStartupArgs(existingArgs = []) {
  if (hasCodexUpdateCheckConfig(existingArgs)) return [];
  return ['-c', `${CODEX_UPDATE_CHECK_KEY}=false`];
}

/**
 * Every CLI config key PortOS itself injects as a `-c <key>=<value>` override.
 * Exhaustive by construction — `buildEffortArgs` and `buildCodexStartupArgs`
 * above are the only two builders that emit `-c`, and both key off the
 * constants listed here.
 *
 * Read by the `cli-config-invalid` error analyzer (`agentErrorAnalysis.js`) to
 * answer the only question that matters when a CLI refuses to start: did PortOS
 * hand it that value, or was it already sitting in the user's own config file?
 * Getting this wrong sends the user grepping PortOS source for a key PortOS
 * never emits — the 2026-08-18 `service_tier` incident, where a newer install
 * of the same CLI had written a variant the CLI on PATH rejects into the shared
 * config file.
 */
export const PORTOS_CLI_CONFIG_KEYS = Object.freeze([
  CODEX_AGENT_THREADS_KEY,
  CODEX_EFFORT_KEY,
  CODEX_UPDATE_CHECK_KEY,
  CODEX_WORKSPACE_NETWORK_KEY,
  CODEX_WORKSPACE_WRITABLE_ROOTS_KEY,
  CODEX_PLUGINS_FEATURE_KEY,
  CODEX_APPS_FEATURE_KEY,
  CODEX_HOOKS_FEATURE_KEY,
]);

/**
 * True when `key` is a config key PortOS supplies via `-c` (see
 * PORTOS_CLI_CONFIG_KEYS). Null-safe; comparison is exact, so a lookalike key
 * from the user's config file is correctly reported as not-ours.
 * @param {unknown} key
 * @returns {boolean}
 */
export function isPortosSuppliedConfigKey(key) {
  return typeof key === 'string' && PORTOS_CLI_CONFIG_KEYS.includes(key.trim());
}

/**
 * True when a provider command points at the OpenCode binary — matching the bare
 * `opencode` on PATH OR an absolute/relative path to it (`/opt/homebrew/bin/opencode`,
 * common when the service PATH can't resolve the CLI), with an optional Windows `.exe`
 * suffix. The OpenCode arg-builder branches key on this rather than `command === 'opencode'`
 * so a path-configured provider isn't misrouted into the Claude-style invocation. Only
 * `.exe` is stripped (not `.cmd`/`.bat`), matching the runner allowlist and the
 * `shell: false` spawn path — a batch shim isn't directly spawnable.
 * @param {string|null|undefined} command
 * @returns {boolean}
 */
export function isOpencodeCommand(command) {
  return commandBasename(command) === 'opencode';
}

/**
 * The OpenCode agent a `no-tool` public-review stage runs as (`opencode run
 * --agent …`). `plan` is OpenCode's OWN built-in read-only agent, chosen over a
 * PortOS-declared one so the stage never depends on a custom agent definition
 * being accepted by whatever OpenCode version is installed.
 *
 * It is a belt, not the braces: `hardenOpencodeConfigForNoTool`
 * (`opencodeConfig.js`) still empties this agent's tool map, so a future
 * OpenCode that widens `plan` cannot widen the stage. Lives HERE rather than
 * beside that function because `providerVendors.js` — which passes the flag —
 * must not import `opencodeConfig.js`; doing so pulls `ports.js` in behind it
 * and breaks a suite that partially mocks it.
 */
export const OPENCODE_PUBLIC_REVIEW_AGENT = 'plan';

/**
 * OpenCode's built-in tool-enabled agent — the one an attachable Stage 3
 * session runs as (`providerVendors.js`) and the one `hardenOpencodeConfigForNoTool`
 * must still empty. Homed here for the same import-graph reason as above.
 */
export const OPENCODE_BUILD_AGENT = 'build';

/**
 * OpenCode addresses models as `provider/model` (e.g. `ollama/qwen2.5:7b`). The
 * OpenCode Ollama provider declares its local daemon under the config-provider
 * key `ollama` (via OPENCODE_CONFIG_CONTENT), so the bare Ollama model id stored
 * in `defaultModel` must be namespaced with `ollama/` before it's passed to
 * `opencode run -m` / `opencode --model`. Idempotent — an id that already starts
 * with `ollama/` is returned untouched, and a `/`-bearing Ollama id
 * (`hf.co/user/model:tag`) is namespaced as `ollama/hf.co/...` since OpenCode
 * splits provider/model on the FIRST slash only.
 *
 * Gated on a local-runtime marker, NOT just `command === 'opencode'`: a
 * user-configured OpenCode provider pointed at a different backend stores an
 * already-qualified id (`openai/gpt-4o`, `anthropic/claude-sonnet`), and blindly
 * prefixing `ollama/` would route it to the wrong backend. No-op for
 * non-local / non-OpenCode providers and empty models.
 * @param {{command?:string, ollamaBacked?:boolean, lmstudioBacked?:boolean, mtplxBacked?:boolean, llamaBacked?:boolean, vllmBacked?:boolean, sglangBacked?:boolean, orcarouterBacked?:boolean}} provider
 * @param {string|null|undefined} model
 * @returns {string|null|undefined}
 */
export function prefixOpencodeModel(provider, model) {
  const namespace = getOpencodeLocalProviderNamespace(provider);
  if (!isOpencodeCommand(provider?.command) || !namespace || !model) return model;
  const id = String(model);
  if (isGatewayNamespace(namespace)) {
    // A gateway model id is ALREADY `vendor/model` (`anthropic/claude-sonnet-4`,
    // `orcarouter/auto`), and OpenCode splits provider/model on the FIRST slash
    // only — so the namespaced form is legitimately doubled
    // (`openrouter/anthropic/claude-sonnet-4`, `openrouter/openrouter/auto`).
    // Guard on the DOUBLED prefix, never the single one: a single-prefix check
    // would read OpenRouter's own auto-router id `openrouter/auto` as
    // already-namespaced and emit it unchanged, which OpenCode resolves to the
    // model `auto` — a model that does not exist.
    return id.startsWith(`${namespace}/${namespace}/`) ? id : `${namespace}/${id}`;
  }
  return id.startsWith(`${namespace}/`) ? id : `${namespace}/${id}`;
}

/**
 * The inverse of {@link prefixOpencodeModel} for a KNOWN runtime kind: one model
 * id as the daemon's own listing spells it, with the `<kind>/` namespace
 * stripped. That namespace addresses the OpenCode provider entry and never
 * reaches the daemon, so a provider offering `llama/dflash` and a server serving
 * `dflash` are naming one model — and anything keyed on only one of the two
 * spellings answers "unknown" for half the providers.
 *
 * `null` for anything that does not name a model: blank, non-string, or a "use
 * the CLI's own default" sentinel. Callers that must keep the sentinel should
 * test it themselves before calling.
 *
 * Takes the kind rather than the provider because both callers
 * (`services/providerReadiness.js`'s checklist and
 * `services/observedContextWindows.js`'s dispatch gate) have already resolved
 * the runtime and would otherwise re-derive it per model id.
 *
 * @param {string|null|undefined} model
 * @param {string} kind - the local runtime kind (`llama`, `vllm`, `ollama`, …)
 * @returns {string|null}
 */
export function bareLocalModelId(model, kind) {
  if (typeof model !== 'string' || model.trim() === '' || isConfiguredDefaultModel(model)) return null;
  const trimmed = model.trim();
  return trimmed.startsWith(`${kind}/`) ? trimmed.slice(kind.length + 1) : trimmed;
}

/**
 * OpenCode's local OpenAI-compatible provider namespace, if this provider has
 * opted into one. Structural markers avoid deriving a backend from an editable
 * display name or endpoint and preserve the legacy Ollama outcome if a malformed
 * record carries both markers.
 * @param {{ollamaBacked?:boolean, lmstudioBacked?:boolean, mtplxBacked?:boolean, llamaBacked?:boolean, vllmBacked?:boolean, sglangBacked?:boolean, gatewayBacked?:string, orcarouterBacked?:boolean}|null|undefined} provider
 * @returns {'ollama'|'lmstudio'|'mtplx'|'llama'|'vllm'|'sglang'|string|null}
 */
export function getOpencodeLocalProviderNamespace(provider) {
  if (provider?.ollamaBacked === true) return 'ollama';
  if (provider?.lmstudioBacked === true) return 'lmstudio';
  if (provider?.mtplxBacked === true) return 'mtplx';
  if (provider?.llamaBacked === true) return 'llama';
  if (provider?.vllmBacked === true) return 'vllm';
  if (provider?.sglangBacked === true) return 'sglang';
  // Hosted gateways (`providerGateways.js`) come LAST so a malformed record
  // carrying both a local marker and a gateway marker keeps its legacy local
  // outcome, exactly as the old if-chain did with `orcarouterBacked`.
  return gatewayIdForProvider(provider);
}

/**
 * The namespace above, but only when it names a LOCAL daemon — a hosted gateway
 * (`providerGateways.js`) is an OpenCode namespace and a remote API, so every
 * consumer asking "is there a daemon on this machine behind this provider?"
 * has to exclude it.
 *
 * That exclusion was hand-written at three sites (`isLocalBackedClaude` in
 * `cliChildEnv.js`, `localRuntimeKind` in `localProviderRuntime.js`, and the
 * OpenCode public-review recipe in `providerVendors.js`), which is one more
 * than the `orcarouterBacked` → `providerGateways.js` sweep was meant to leave
 * behind — so the composed predicate lives here, beside the namespace resolver
 * it wraps.
 *
 * @param {object|null|undefined} provider
 * @returns {'ollama'|'lmstudio'|'mtplx'|'llama'|'vllm'|'sglang'|null}
 */
export function localRuntimeNamespace(provider) {
  const namespace = getOpencodeLocalProviderNamespace(provider);
  return namespace && !isGatewayNamespace(namespace) ? namespace : null;
}

/**
 * True when an OpenCode process provider runs against a local OpenAI-compatible
 * backend or a hosted gateway — any namespace `getOpencodeLocalProviderNamespace`
 * resolves — rather than a vendor cloud model. This is the gate on the OpenCode
 * effort ladder, and the browser re-exports it so the effort picker and the run
 * agree on which records get one (#4765).
 * @param {object|null|undefined} provider
 * @returns {boolean}
 */
export function isOpencodeLocalProvider(provider) {
  return isOpencodeProvider(provider) && getOpencodeLocalProviderNamespace(provider) !== null;
}

/**
 * The Codex CLI's own `--local-provider` values, mapped from PortOS's
 * local-runtime marker axis (`localRuntimeNamespace` in providerModels.js).
 *
 * Codex 0.153.0+ ships `--oss` / `--local-provider <lmstudio|ollama>`, so
 * running the Codex harness on a local model is a pair of flags rather than a
 * rewrite of the user's `~/.codex/config.toml` — the flags are per-invocation
 * and leave every other `codex` run on the machine untouched.
 *
 * Deliberately a TABLE, not a passthrough: PortOS's marker axis carries five
 * local runtimes (ollama / mtplx / llama / vllm / sglang) and Codex serves two
 * of them by name. Forwarding an unmapped namespace would hand codex a value it
 * rejects, and forwarding nothing would silently run the record against the
 * OpenAI cloud — which is why `codexUnsupportedLocalRuntime` below exists.
 *
 * Both of Codex's values are mapped: `lmstudio` joined the axis with the
 * `lmstudioBacked` marker (#6309). The remaining three (mtplx / vllm / sglang)
 * have no Codex spelling at all, which is what `codexUnsupportedLocalRuntime`
 * below is for.
 */
export const CODEX_OSS_LOCAL_PROVIDERS = Object.freeze({ ollama: 'ollama', lmstudio: 'lmstudio' });

/**
 * The first Codex CLI release that ships `--oss` / `--local-provider`. Used
 * only to NAME the requirement in a prerequisite finding — the gate itself is a
 * `codex exec --help` flag probe (`services/codexOssSupport.js`), because a
 * version string is a proxy for the contract and the help text IS the contract.
 */
export const CODEX_OSS_MIN_VERSION = '0.153.0';

/**
 * The `--local-provider` value for `provider`, or `null` when this record is not
 * backed by a local runtime Codex can serve.
 * @param {object|null|undefined} provider
 * @returns {string|null}
 */
export function codexOssLocalProvider(provider) {
  const namespace = localRuntimeNamespace(provider);
  return (namespace && CODEX_OSS_LOCAL_PROVIDERS[namespace]) || null;
}

/**
 * The local runtime this codex record is marked with but Codex cannot serve
 * (`vllm`, `sglang`, …), or `null`. A definite negative: the marker is on the
 * record, and no credential or config makes `--local-provider vllm` exist. The
 * prerequisite layer turns it into a finding rather than letting the row spawn
 * against the OpenAI cloud while the card claims it is local.
 * @param {object|null|undefined} provider
 * @returns {string|null}
 */
export function codexUnsupportedLocalRuntime(provider) {
  const namespace = localRuntimeNamespace(provider);
  return namespace && !CODEX_OSS_LOCAL_PROVIDERS[namespace] ? namespace : null;
}

/**
 * Parse a stored `OPENCODE_CONFIG_CONTENT` value, or null when it is absent or
 * no longer valid JSON (a hand-edited config tells us nothing, so every caller
 * falls back to its own default rather than guessing).
 *
 * Shared because four call sites read the same variable and must agree on what
 * counts as unusable: `opencodeConfig.js`'s merge base, `localProviderRuntime.js`'s
 * endpoint lookup, `cliChildEnv.js`'s public-review allowlist, and the locality
 * predicate below.
 *
 * @param {unknown} value
 * @returns {object|null}
 */
export function parseOpencodeConfigContent(value) {
  if (typeof value !== 'string' || value === '') return null;
  try {
    const parsed = JSON.parse(value);
    return isPlainObject(parsed) ? parsed : null;
  } catch {
    return null;
  }
}

/**
 * Every provider endpoint an OpenCode config object declares is on this machine.
 *
 * This is the ONE rule two public-review sites must not disagree about, which is
 * why it lives here rather than being spelled out at each of them:
 *
 *   - `providerVendors.js` decides whether an OpenCode wrapper may run the
 *     tool-free gate at all;
 *   - `cliChildEnv.js` decides whether `OPENCODE_CONFIG_CONTENT` survives the
 *     public-review env allowlist.
 *
 * If the first says yes and the second says no, the stage still spawns — but
 * with the hardened config stripped, so OpenCode falls back to reading the
 * user's own `~/.config/opencode`, tools and MCP servers and all, while every
 * signal still reports an enforced tool-free gate. A remote `baseURL` inside an
 * otherwise `ollamaBacked` provider is exactly that shape, and the marker alone
 * cannot see it.
 *
 * `requireDeclaration` is the one place the two callers legitimately differ, and
 * it is about PROVENANCE, not locality:
 *
 *   - A provider RECORD storing a config with no `provider` entry has relocated
 *     nothing — the builder still adds the canonical per-namespace entry, all of
 *     which are loopback — so that is vacuously local (the default).
 *   - The env allowlist sees a bare string that may be ambient rather than the
 *     config PortOS just built for this spawn. A value declaring no endpoint is
 *     not one we produced for an eligible provider, so it passes
 *     `requireDeclaration: true` and is dropped with every other inherited var.
 *
 * The locality rule itself — every declared endpoint is on this machine — is
 * identical for both, which is what keeps eligibility and the allowlist in step.
 * Absent config (`null`) is never local: there is nothing to keep.
 *
 * @param {object|null|undefined} config - a parsed OpenCode config
 * @param {{requireDeclaration?: boolean}} [options]
 * @returns {boolean}
 */
export function opencodeConfigIsLocalOnly(config, { requireDeclaration = false } = {}) {
  if (!isPlainObject(config)) return false;
  const declared = isPlainObject(config.provider) ? Object.values(config.provider) : [];
  if (declared.length === 0) return !requireDeclaration;
  return declared.every((entry) => isLocalInstanceEndpoint(entry?.options?.baseURL));
}

/**
 * The same question asked of a PROVIDER RECORD, before its config has been
 * built. A record storing no config — or an unparseable one, which the builder
 * discards too — runs against those same canonical defaults.
 *
 * @param {object|null|undefined} provider
 * @returns {boolean}
 */
export function opencodeProviderIsLocalOnly(provider) {
  const stored = parseOpencodeConfigContent(provider?.envVars?.OPENCODE_CONFIG_CONTENT);
  return stored === null || opencodeConfigIsLocalOnly(stored);
}

/**
 * Claude Code on AWS Bedrock wants region-prefixed model ids
 * (`global.anthropic.claude-opus-5`, `us.anthropic.claude-opus-4-1-...-v1:0`).
 * When `CLAUDE_CODE_USE_BEDROCK` is set on the box, passing a bare
 * `claude --model claude-opus-5` is rejected ("provided model identifier is
 * invalid") — which is exactly how a bare-id `claude-code` provider config
 * breaks autopilot/pipeline runs on a Bedrock host. The helpers below map a
 * bare id to its Bedrock form just-in-time at CLI-argv build time; the stored
 * provider config stays bare (so a box can move in/out of Bedrock mode freely).
 */

// Family → the env var Claude Code reads for that tier's resolved model. A
// Bedrock wrapper sets these to the exact region-prefixed id it wants, so when
// present they are preferred over a blind prefix-rewrite.
const BEDROCK_FAMILY_ENV = {
  opus: 'ANTHROPIC_DEFAULT_OPUS_MODEL',
  sonnet: 'ANTHROPIC_DEFAULT_SONNET_MODEL',
  haiku: 'ANTHROPIC_DEFAULT_HAIKU_MODEL',
  fable: 'ANTHROPIC_DEFAULT_FABLE_MODEL',
};

/**
 * True when the box is in Claude-Code-on-Bedrock mode. Treats the documented
 * `CLAUDE_CODE_USE_BEDROCK=1` plus the usual truthy spellings as enabled;
 * `0`/`false`/`no`/empty/unset are off.
 */
export const isBedrockEnabled = (env = process.env) => {
  const v = env?.CLAUDE_CODE_USE_BEDROCK;
  if (v == null) return false;
  const s = String(v).trim().toLowerCase();
  return s !== '' && s !== '0' && s !== 'false' && s !== 'no';
};

/**
 * True when an id already carries a Bedrock region prefix
 * (`global.anthropic.…`, `us.anthropic.…`, `eu.anthropic.…`, `apac.anthropic.…`)
 * or the bare `anthropic.…` form. Such ids are left untouched.
 */
export const hasBedrockRegionPrefix = (id) =>
  typeof id === 'string' && (/^[a-z]+\.anthropic\./i.test(id) || /^anthropic\./i.test(id));

const detectClaudeFamily = (id) => {
  if (typeof id !== 'string') return null;
  const lower = id.toLowerCase();
  return Object.keys(BEDROCK_FAMILY_ENV).find((fam) => lower.includes(fam)) || null;
};

/**
 * Map a bare Claude model id to its Bedrock form when (and only when) Bedrock
 * mode is on. Pure — no logging, no env mutation.
 *
 *  - No-op when Bedrock mode is off, the id is empty/non-string, or it already
 *    carries a region/`anthropic.` prefix.
 *  - No-op for any id that doesn't contain `claude` (codex `gpt-5`, gemini, a
 *    custom local alias like `my-sonnet-lora`, etc.) — only Claude ids are
 *    Bedrock-mappable, so applying this at a shared argv chokepoint can't
 *    corrupt another vendor's model.
 *  - Prefers the matching `ANTHROPIC_DEFAULT_<FAMILY>_MODEL` env value when it
 *    is itself a region-prefixed Bedrock id (the wrapper's exact choice); else
 *    falls back to a `global.anthropic.<id>` prefix-rewrite.
 *
 * @param {string|null|undefined} id
 * @param {NodeJS.ProcessEnv} [env]
 * @returns {string|null|undefined} the mapped id (or the input unchanged)
 */
export function toBedrockModelId(id, env = process.env) {
  if (!isBedrockEnabled(env)) return id;
  if (typeof id !== 'string' || !id) return id;
  if (hasBedrockRegionPrefix(id)) return id;
  if (!/claude/i.test(id)) return id; // not a Claude id — leave alone
  const family = detectClaudeFamily(id);
  if (family) {
    const override = env?.[BEDROCK_FAMILY_ENV[family]];
    if (hasBedrockRegionPrefix(override)) return override;
  }
  return `global.anthropic.${id}`;
}

// Dedup so the auto-correction notice prints once per (provider, model) per
// process rather than on every run.
const _warnedBareBedrockModels = new Set();

/**
 * One-time (per process, per provider+model) notice that a stored Claude-Code
 * model id reads non-Bedrock while the box is in Bedrock mode and is being
 * auto-corrected for this run. Surfaces via the emoji-prefixed console.error
 * path so the config stays self-explanatory.
 */
export function warnBareBedrockModel(providerId, originalId, mappedId) {
  const key = `${providerId || 'claude-code'}::${originalId}`;
  if (_warnedBareBedrockModels.has(key)) return;
  _warnedBareBedrockModels.add(key);
  console.error(
    `⚠️ Provider '${providerId || 'claude-code'}' model '${originalId}' is bare but CLAUDE_CODE_USE_BEDROCK is set — auto-correcting to Bedrock id '${mappedId}' for this run (stored config unchanged; set a global.anthropic.* / us.anthropic.* model to silence).`,
  );
}

/**
 * Side-effecting convenience used at CLI-argv build time: map a bare Claude id
 * to its Bedrock form and emit the one-time auto-correction notice when the map
 * actually changed the id. Returns the id to pass to `--model`.
 */
export function resolveBedrockCliModel(id, { env = process.env, providerId } = {}) {
  const mapped = toBedrockModelId(id, env);
  if (mapped !== id) warnBareBedrockModel(providerId, id, mapped);
  return mapped;
}

/**
 * Claude Code's first-party model ids spell a version with DASHES
 * (`claude-fable-5-1`, `claude-opus-4-8`), while the release is spoken and
 * written with a dot ("Fable 5.1"). A stored `claude-fable-5.1` therefore looks
 * right in the picker and is rejected by the CLI at spawn time — the run dies
 * with "model not found", the task blocks, and nothing about the id says why.
 *
 * This canonicalizes the dotted spelling to the dashed one, and ONLY that:
 *
 *  - the id must start with a first-party family prefix (`claude-opus-`,
 *    `claude-sonnet-`, `claude-haiku-`, `claude-fable-`), so a vendor id that
 *    merely mentions Claude (cursor's `claude-4.6-sonnet-medium`) is untouched;
 *  - only a dot BETWEEN DIGITS is rewritten, leaving any other dot alone;
 *  - a Bedrock region-prefixed id (`global.anthropic.…`) is left alone, since
 *    its prefix dots are structural.
 *
 * @param {string|null|undefined} id
 * @returns {string|null|undefined} the canonical id (or the input unchanged)
 */
export function normalizeClaudeModelId(id) {
  if (typeof id !== 'string' || !id) return id;
  if (hasBedrockRegionPrefix(id)) return id;
  if (!/^claude-(?:opus|sonnet|haiku|fable)-/i.test(id)) return id;
  return id.replace(/(\d)\.(?=\d)/g, '$1-');
}

// Dedup so the canonicalization notice prints once per (provider, model) per
// process rather than on every run, matching `warnBareBedrockModel`.
const _warnedDottedClaudeModels = new Set();

/**
 * The model string a Claude Code spawn should pass to `--model`: canonicalize a
 * dotted first-party id, then map it to its Bedrock form when the box is in
 * Bedrock mode. The single home for both corrections, called from every
 * Claude-command argv builder (`claudeCliArgs`, `claudeSpawnArgs`,
 * `resolveInjectedTuiModel`) so a fix in one is a fix in all.
 *
 * Deliberately NOT folded into `resolveBedrockCliModel`: that helper is also the
 * documented Bedrock-only mapper, and the dot rewrite is gated on the caller
 * already having resolved a Claude *Code* command — cursor and friends label
 * Anthropic models under their own dotted ids and must not be rewritten.
 *
 * @param {string|null|undefined} id
 * @param {{env?:NodeJS.ProcessEnv, providerId?:string}} [opts]
 * @returns {string|null|undefined}
 */
export function resolveClaudeCliModel(id, { env = process.env, providerId } = {}) {
  const canonical = normalizeClaudeModelId(id);
  if (canonical !== id) {
    const key = `${providerId || 'claude-code'}::${id}`;
    if (!_warnedDottedClaudeModels.has(key)) {
      _warnedDottedClaudeModels.add(key);
      console.error(
        `⚠️ Provider '${providerId || 'claude-code'}' model '${id}' spells its version with a dot — Claude Code only serves the dashed id, using '${canonical}' for this run (update the provider's model list to silence).`,
      );
    }
  }
  return resolveBedrockCliModel(canonical, { env, providerId });
}

/**
 * The model string a TUI spawn should actually pass to `--model`, given the
 * resolved launch command. The single home for a decision that used to be
 * open-coded in TWO parallel ladders — `tuiHandshake.js#buildTuiInvocation`
 * (one-shot TUI prompt runs) and `agentTuiSpawning.js#appendModelArgs` (CoS
 * agent / TUI-session spawns) — which is exactly how cursor's exemption landed
 * in one and not the other. Callers keep their own `hasModelFlag` gating; this
 * only answers "which id".
 *
 *  - OpenCode: namespace a bare Ollama id (`ollama/<id>`); never Bedrock-mapped.
 *  - Claude Code: canonicalize a dotted first-party id (`claude-fable-5.1` →
 *              `claude-fable-5-1`), then map a bare Claude id to its
 *              region-prefixed Bedrock form when the box is in Bedrock mode
 *              (no-op off Bedrock / for non-Claude ids).
 *  - Anything else: passed through verbatim.
 *
 * The Bedrock arm is deliberately OPT-IN on the launch command rather than the
 * default. Bedrock is a Claude *Code* transport, but `toBedrockModelId` gates
 * only on the model id matching `/claude/i` — so as the default it silently
 * captured any vendor that labels Anthropic models under its own ids. Cursor is
 * exactly that case (`claude-opus-5-thinking-high`), and on a Bedrock box it was
 * being rewritten to `global.anthropic.claude-opus-5-thinking-high`, an id
 * cursor's router has never heard of. Opting out per-vendor meant every future
 * vendor had to remember to; keying on `isClaudeCommand` inverts that default so
 * they don't. (`isClaudeCommand` treats a blank command as Claude, matching both
 * callers' blank→`claude` spawn fallback, so this is behavior-preserving for
 * every shipped provider.)
 *
 * @param {string} model - the already-resolved (non-sentinel) model id
 * @param {{id?:string, command?:string, ollamaBacked?:boolean, mtplxBacked?:boolean, envVars?:Record<string,string>}|null|undefined} provider
 * @param {string} [command] - resolved launch command (may differ from provider.command)
 * @returns {string}
 */
export function resolveInjectedTuiModel(model, provider, command = provider?.command) {
  if (isOpencodeCommand(command)) return prefixOpencodeModel(provider, model);
  if (!isClaudeCommand(command)) return model;
  return resolveClaudeCliModel(model, {
    env: { ...process.env, ...provider?.envVars },
    providerId: provider?.id,
  });
}

/**
 * Strip configured-default sentinels from a model list — the user-selectable view.
 * @param {string[]} models
 * @returns {string[]}
 */
export const filterSelectableModels = (models) =>
  (models || []).filter(m => !isConfiguredDefaultModel(m));

/**
 * Detects whether the provider's stored argv already pins a model with a
 * usable value. Checks both flag forms (`--model` / `-m`) and both styles
 * (separated `--model x` and joined `--model=x`). A separated flag with no
 * value following (`['--model']` at end of argv, or `['--model', '--other']`)
 * is treated as NOT a baked-in pin — the CLI would reject the argv at
 * runtime anyway, and pretending it's a pin would also make refiners report
 * `null` (from extractBakedModel) and skip injecting our own model.
 *
 * Used to gate runner-injected `--model` flags: when the user has hard-coded
 * a model in args, the runner-injected one is suppressed and the args-baked
 * model wins.
 */
export function hasModelFlag(args) {
  if (!Array.isArray(args)) return false;
  for (let i = 0; i < args.length; i++) {
    const a = args[i];
    if (typeof a !== 'string') continue;
    if (a.startsWith('--model=') && a.length > '--model='.length) return true;
    if (a.startsWith('-m=') && a.length > '-m='.length) return true;
    if (a === '--model' || a === '-m') {
      const next = args[i + 1];
      if (typeof next === 'string' && next.length > 0 && !next.startsWith('-')) return true;
    }
  }
  return false;
}

/**
 * Strip dangling/empty `--model` / `-m` tokens (no value follows, or the joined
 * form has an empty value). Those would survive into the spawned argv unchanged
 * and cause the CLI to reject the invocation — see the comment on `hasModelFlag`
 * for the full reasoning (it deliberately reports such a token as NOT a pin, so
 * the injection path fires; without this strip the CLI would then see two
 * `--model` occurrences). Pinned-with-value tokens are preserved untouched so
 * user-baked model selections still win.
 * @param {unknown[]} args
 * @returns {unknown[]}
 */
export function stripBrokenModelFlags(args) {
  if (!Array.isArray(args) || args.length === 0) return [];
  const out = [];
  for (let i = 0; i < args.length; i++) {
    const a = args[i];
    if (typeof a === 'string' && (a === '--model=' || a === '-m=')) {
      continue; // empty joined form
    }
    if (a === '--model' || a === '-m') {
      const next = args[i + 1];
      const hasValue = typeof next === 'string' && next.length > 0 && !next.startsWith('-');
      if (!hasValue) continue; // dangling separated form
    }
    out.push(a);
  }
  return out;
}

/**
 * True when a provider command points at the Claude Code binary — the bare
 * `claude` on PATH, an absolute/relative path to it, or an optional Windows
 * `.exe` suffix (same matching rules as `isOpencodeCommand`). An empty/null
 * command also counts as Claude: `buildCliSpawnConfig`'s default branch and
 * the TUI `inferTuiCommand` fallback both resolve a blank command to `claude`.
 * @param {string|null|undefined} command
 * @returns {boolean}
 */
export function isClaudeCommand(command) {
  // An empty/blank command also counts as Claude: `buildCliSpawnConfig`'s default
  // branch and the TUI `inferTuiCommand` fallback both resolve a blank command to
  // `claude` — a policy that differs from the other predicates, so it stays here.
  if (command == null || command === '') return true;
  return commandBasename(command) === 'claude';
}

/**
 * True for an Ollama-backed provider that launches the Claude Code binary
 * (`claude-ollama` / `claude-ollama-tui`). These sessions run a small local
 * model that drowns in Claude Code's full personal environment — hooks,
 * plugins, MCP servers, the global ~/.claude/CLAUDE.md — so the spawners put them in lean
 * mode (see `applyLeanClaudeArgs`). Keyed on the `ollamaBacked` marker + the
 * launch command, not provider ids, so renamed/custom local providers get the
 * same treatment.
 * @param {{command?:string, ollamaBacked?:boolean}|null|undefined} provider
 * @param {string} [command] - resolved launch command when it differs from
 *   `provider.command` (the TUI path may infer it from the provider id)
 * @returns {boolean}
 */
export function isOllamaClaudeProvider(provider, command = provider?.command) {
  return provider?.ollamaBacked === true && isClaudeCommand(command);
}

/**
 * True when a provider explicitly configures its own GitHub credential
 * (`GH_TOKEN` or `GITHUB_TOKEN`) in `envVars`. Agent-spawn paths that would
 * otherwise inject a repo-owner-pinned `GH_TOKEN` skip that injection when this
 * returns true, so the provider's explicit credential wins — `gh` prefers
 * `GH_TOKEN` over `GITHUB_TOKEN`, so an injected `GH_TOKEN` would silently
 * shadow a provider's configured `GITHUB_TOKEN` otherwise.
 * @param {{envVars?: Record<string,unknown>}} provider
 * @returns {boolean}
 */
export function providerSuppliesGithubToken(provider) {
  const env = provider?.envVars;
  return !!env && ('GH_TOKEN' in env || 'GITHUB_TOKEN' in env);
}

/**
 * Lean-context flags for local-model Claude Code sessions:
 * - `--bare` — skip hooks, plugin sync, auto-memory, and AGENTS.md
 *   auto-discovery (the user's personal environment derails small models).
 * - `--strict-mcp-config` — with no `--mcp-config` given, load zero MCP
 *   servers (their tool schemas alone can blow a small Ollama context).
 */
export const LEAN_CLAUDE_ARGS = ['--bare', '--strict-mcp-config'];

/**
 * Append the lean-context flags for Ollama-backed Claude providers. No-op for
 * every other provider, and idempotent when the user already baked either
 * flag into `provider.args`.
 * @param {{command?:string, ollamaBacked?:boolean, args?:string[]}} provider
 * @param {string[]} args - argv built so far
 * @param {string} [command] - resolved launch command (see isOllamaClaudeProvider)
 * @returns {string[]}
 */
export function applyLeanClaudeArgs(provider, args, command = provider?.command) {
  if (!isOllamaClaudeProvider(provider, command)) return args;
  return [...args, ...LEAN_CLAUDE_ARGS.filter(flag => !args.includes(flag))];
}

/**
 * Extract the pinned model id from provider.args when a model flag is baked
 * in. Supports separated form (`--model X` / `-m X`) and joined form
 * (`--model=X` / `-m=X`). Returns null when no model flag is present or the
 * separated form has no value following the flag.
 */
export function extractBakedModel(args) {
  if (!Array.isArray(args)) return null;
  for (let i = 0; i < args.length; i++) {
    const a = args[i];
    if (typeof a !== 'string') continue;
    if (a === '--model' || a === '-m') {
      const next = args[i + 1];
      if (typeof next === 'string' && next.length > 0 && !next.startsWith('-')) return next;
      return null;
    }
    if (a.startsWith('--model=')) return a.slice('--model='.length) || null;
    if (a.startsWith('-m=')) return a.slice('-m='.length) || null;
  }
  return null;
}