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

24.2 KB
Raw Blame
import {
  commandBasename,
  getOpencodeLocalProviderNamespace,
  isAntigravityProvider,
  isClaudeProvider,
  isCodexProvider,
  isCursorProvider,
  isGrokProvider,
  isKimiProvider,
  isOpencodeProvider,
  prefixOpencodeModel,
} from './providerModels.js';
import { isKiloProvider } from './kilo.js';
import { isOpenchamberProvider } from './openchamber.js';

/**
 * The HARNESS half of the provider-connection graph proposed in
 * `docs/plans/2026-09-06-provider-connections-and-harnesses.md` (#6366).
 *
 * A harness is the agent program PortOS drives (Claude Code, OpenCode, Codex,
 * …) — stable, shipped-in-code identity, never a user-typed command fetched
 * from a server. It is deliberately SEPARATE from:
 *
 *   - `providerVendors.js`, which is argv/sandbox-recipe shaped;
 *   - `providerFamilies.js`, which answers "which paid subscription quota?";
 *   - `providerGateways.js`, which is a hosted OpenAI-compatible backend.
 *
 * A harness answers only: which program runs, which execution modes it can be
 * driven in, which wire protocol it speaks to a backend connection, how a
 * canonical backend model name becomes the string that program accepts — and,
 * since #7562, every WAY it can be pointed at a service (`bindings`, below).
 *
 * The `direct` row is the one harness that is not a program: a direct API
 * record is PortOS's own HTTP client speaking the OpenAI wire. Giving it a row
 * lets the epic compose `direct.api@<service>` from the same tables as every
 * CLI, while the graph keeps storing it as `harness_id = NULL` — see
 * {@link normalizeHarnessId} / {@link graphHarnessId}.
 *
 * Rows match through the existing `is*Provider` predicates rather than a fresh
 * command-string test, so a path-configured binary, a `.exe`, and the shipped
 * ids all resolve the same way they already do everywhere else in PortOS.
 */

/** Execution modes a route can carry. Mirrors the provider record's `type`. */
export const ROUTE_MODES = Object.freeze(['cli', 'tui', 'api']);

/** Modes every CLI/TUI harness supports. */
const CLI_TUI_MODES = Object.freeze(['cli', 'tui']);

/** The `direct` harness only: PortOS's own HTTP client has no process to drive. */
const API_ONLY_MODES = Object.freeze(['api']);

/**
 * Headless only. A harness whose interactive surface is not a terminal — today
 * OpenChamber, whose UI is a web app and whose bare binary starts a server —
 * has no TUI to attach a PTY to, so it must not be offered one.
 */
const CLI_ONLY_MODES = Object.freeze(['cli']);

/**
 * Why a harness cannot be minted from a bare CONNECTION (an arbitrary
 * endpoint), as the clause the create endpoint refuses with (`bindingBlocker`
 * in `providerRouteRecipes.js`). `connectionBlocker` on the row.
 *
 * This is DATA on the row rather than prose in a comment because the refusal
 * quotes it. Until three reasons existed, `bindingBlocker` hardcoded the first
 * one — so adding a row for a different reason told the user their harness
 * "reaches only its own vendor service", which is both wrong and points at the
 * wrong remedy.
 *
 * Two of these rows have no recipe at all (Kilo, OpenChamber: nothing can be
 * composed onto them, so they carry no `bindings` either). The others DO carry
 * a recipe and compose onto the services their bindings name through
 * `materializeRoute`; they just cannot be pointed at an endpoint they were
 * not built to know.
 */
const CONNECTION_BLOCKER = Object.freeze({
  /** The backend lives in a config file PortOS does not write (Kilo). */
  UNWRITTEN_CONFIG: 'resolves its backend from its own config file, which PortOS does not write',
  /** The backend belongs to a separate runtime the user configures (OpenChamber). */
  EXTERNAL_RUNTIME: 'runs against a workspace runtime you sign in to separately',
  /** A subscription program: it signs into its own vendor service and nothing else. */
  VENDOR_SERVICE: 'reaches only its own vendor service',
  /**
   * Verified against the installed CLI (`pi --help`, its `docs/models.md`): Pi
   * reaches a backend by `--provider <name>` / `--model provider/id` plus that
   * provider's env key, and a CUSTOM endpoint only through
   * `~/.pi/agent/models.json`, a user-owned file PortOS does not write. So a
   * Pi route can be materialized for any service Pi ships a provider name for
   * (`piProvider` on the definition) — nvidia, openrouter, anthropic, … — but
   * not for an arbitrary local daemon or endpoint.
   */
  PI_BUILTIN_PROVIDERS: 'reaches only the services Pi ships a provider name for (a custom endpoint lives in Pi\'s own models.json, which PortOS does not write)',
});

/**
 * The COMMAND RECIPE half of a harness row (#6369).
 *
 * Everything above classifies a provider record that already exists. A recipe
 * answers the opposite question — **how do you spawn a fresh one?** — which is
 * what minting a new executable route for a connection needs and what this
 * registry could not describe before.
 *
 * Each recipe is the shipped, proven configuration for that program, lifted
 * from its `defaults/providers.sample.json` entry rather than invented here;
 * `providerRouteRecipes.sampleParity.test.js` fails when the two drift, so a
 * minted route can never quietly become one the harness will not run.
 *
 * Columns:
 *
 *   - `command` / `modes[mode]` — the binary and its per-mode argv. `cli`
 *     carries `headlessArgs`, `tui` carries `tuiPromptDelayMs`; neither is
 *     meaningful for the other mode, so neither is declared for it.
 *   - `baseUrl` — where a connection's endpoint lands on the record:
 *     `{ via: 'env', name }` an environment variable, `{ via: 'field' }` the
 *     record's own `endpoint`, or `{ via: 'opencodeConfig' }` the inline
 *     provider JSON OpenCode reads.
 *   - `credential` — the key the connection must carry for this program, and
 *     whether it REFUSES to start without one. Claude Code does (it sends an
 *     Anthropic auth token even to a local daemon that ignores it), which is why
 *     the create endpoint refuses rather than minting a route that cannot run.
 *
 * A harness with **no** recipe is not an oversight — it means this program has
 * no backend PortOS can point at from a connection, and its row says WHICH of
 * the {@link CONNECTION_BLOCKER} reasons applies. Adding one of those stays `/ai/new`.
 */

/** Claude Code's headless argv, shared by every Claude recipe mode. */
const CLAUDE_HEADLESS_ARGS = Object.freeze(['--no-session-persistence', '--disable-slash-commands', '--tools', '']);

/** The delay a TUI harness needs before its first prompt, matching every shipped TUI sample. */
const TUI_PROMPT_DELAY_MS = 2500;

/** A local agent run is long; every shipped CLI/TUI sample uses this timeout. */
const HARNESS_TIMEOUT_MS = 600000;

/**
 * One recipe shape for every program: the binary, its per-mode argv (lifted
 * from the shipped samples), and — for a program the legacy connection path
 * can point at an endpoint — where that endpoint and its credential land.
 * A subscription program or Pi has no such columns (`baseUrl`/`credential`
 * stay `null`); their bindings say how they reach a service.
 */
const recipe = ({ command, cli, tui, headlessArgs = [], tuiPromptDelayMs = TUI_PROMPT_DELAY_MS, baseUrl = null, credential = null }) => Object.freeze({
  command,
  timeout: HARNESS_TIMEOUT_MS,
  baseUrl,
  credential,
  modes: {
    cli: { args: cli, headlessArgs },
    // Pi's shipped TUI sample declares no prompt delay; `null` keeps it that way.
    tui: { args: tui, ...(tuiPromptDelayMs === null ? {} : { tuiPromptDelayMs }) },
  },
});

/**
 * The CAPABILITY BINDINGS of a harness row (#7562): one entry per way the
 * program can be pointed at a service definition (`serviceDefinitions.js`).
 * `compatibleBindings` matches them against a resolved service instance, and
 * `materializeRoute` (`providerRouteRecipes.js`) writes the record each one
 * describes.
 *
 * A binding is a set of CONSTRAINTS on the service (every one present must
 * hold) plus WRITER columns saying where the service's values land:
 *
 *   Constraints — `service` (this definition id), `localRuntime` (one of these
 *   `LOCAL_RUNTIMES` ids), `piProvider: true` (the definition carries a name Pi
 *   ships), `protocol` (the instance declares that transport).
 *
 *   Writers — `baseUrl` is the ONE endpoint axis: `{via:'env', name}`,
 *   `{via:'field'}` (the record's own `endpoint`), `{via:'opencodeConfig',
 *   builtin?}` (the inline provider JSON OpenCode reads; `builtin` declares
 *   permissions only, for a provider OpenCode ships), `{via:'piProvider', flag}`
 *   (`--provider <name>` on the argv), or absent (nothing to write — the
 *   program signs in itself, or a static `env` switch selects the service, as
 *   Bedrock's `CLAUDE_CODE_USE_BEDROCK=1` does). `credential` is `{via:'env',
 *   name?, required}` (`name` defaults to the service's own key var),
 *   `{via:'field', required}` (the record's `apiKey`) or `{via:'gatewayEnv'}`
 *   (the gateway's own key var). `env` is static.
 *
 * Codex's local-runtime binding writes nothing Codex-specific: `--oss
 * --local-provider <x>` is emitted at spawn from the runtime marker the record
 * carries (`buildCodexOssArgs`), so the binding only constrains WHICH runtimes.
 *
 * A row with NO bindings is exactly a row nothing composes onto, and it says
 * why in `connectionBlocker`. `providerHarnesses.test.js` pins that.
 */

/** The credential Claude Code sends: required even to a daemon that ignores it. */
const CLAUDE_AUTH_TOKEN = Object.freeze({ via: 'env', name: 'ANTHROPIC_AUTH_TOKEN', required: true });

/**
 * @type {readonly {id:string,label:string,modes:readonly string[],protocol:string,recipe:object|null,bindings:readonly object[],matches:(p:object)=>boolean}[]}
 */
export const PROVIDER_HARNESSES = Object.freeze([
  Object.freeze({
    id: 'claude',
    label: 'Claude Code',
    modes: CLI_TUI_MODES,
    protocol: 'anthropic',
    recipe: recipe({
      command: 'claude',
      cli: ['--print'],
      headlessArgs: CLAUDE_HEADLESS_ARGS,
      tui: ['--dangerously-skip-permissions'],
      baseUrl: { via: 'env', name: 'ANTHROPIC_BASE_URL' },
      // Claude Code will not start without a token, even against a local daemon
      // that ignores it — so a backend carrying none cannot mint a Claude route.
      credential: CLAUDE_AUTH_TOKEN,
    }),
    bindings: Object.freeze([
      Object.freeze({ service: 'claude-subscription' }),
      Object.freeze({ protocol: 'anthropic', baseUrl: Object.freeze({ via: 'env', name: 'ANTHROPIC_BASE_URL' }), credential: CLAUDE_AUTH_TOKEN }),
      Object.freeze({
        service: 'bedrock',
        env: Object.freeze({ CLAUDE_CODE_USE_BEDROCK: '1' }),
        credential: Object.freeze({ via: 'env', name: 'AWS_BEARER_TOKEN_BEDROCK', required: true }),
      }),
    ]),
    matches: isClaudeProvider,
  }),
  Object.freeze({
    id: 'opencode',
    label: 'OpenCode',
    modes: CLI_TUI_MODES,
    protocol: 'openai',
    recipe: recipe({
      command: 'opencode',
      cli: ['run'],
      tui: [],
      // OpenCode reads its backend out of an inline provider JSON rather than an
      // environment variable, which is also why that string stays route-owned.
      baseUrl: { via: 'opencodeConfig' },
      credential: { via: 'field', required: false },
    }),
    bindings: Object.freeze([
      // OpenCode's own hosted service is a provider it ships; only permissions
      // go in the inline config, and the key rides its documented env var. The
      // FREE plan needs none: OpenCode serves Zen's free models to a signed-out
      // client, which is how every shipped Zen preset runs (no key on the record).
      Object.freeze({
        service: 'opencode-zen',
        baseUrl: Object.freeze({ via: 'opencodeConfig', builtin: true }),
        credential: Object.freeze({ via: 'env', name: 'OPENCODE_API_KEY', required: true, optionalOnPlans: Object.freeze(['free']) }),
      }),
      // A gateway's key is materialized under the gateway's own variable (what
      // the spawner exports for OpenCode); anything else keys off the record.
      Object.freeze({ protocol: 'openai', baseUrl: Object.freeze({ via: 'opencodeConfig' }), credential: Object.freeze({ via: 'gatewayEnv', required: false }) }),
    ]),
    matches: isOpencodeProvider,
  }),
  Object.freeze({
    id: 'kilo',
    label: 'Kilo Code',
    modes: CLI_TUI_MODES,
    protocol: 'openai',
    // Kilo is an OpenCode fork, so its backend is declared in a config file
    // rather than an environment variable — and PortOS has not verified which
    // config surface this fork reads (OpenCode's own `OPENCODE_CONFIG_CONTENT`
    // is the one PortOS writes, and Kilo renames its environment under
    // `KILO_*`). Minting a route on a guess would produce one that points at
    // nothing while reporting a backend, so Kilo stays classifiable and
    // installable but not creatable from a connection.
    recipe: null,
    connectionBlocker: CONNECTION_BLOCKER.UNWRITTEN_CONFIG,
    bindings: Object.freeze([]),
    matches: isKiloProvider,
  }),
  Object.freeze({
    id: 'openchamber',
    label: 'OpenChamber',
    modes: CLI_ONLY_MODES,
    protocol: 'openai',
    // OpenChamber is a control plane in front of a runtime the USER starts and
    // configures (its providers are signed in through its own web UI), so there
    // is no PortOS-supplied backend for a minted route to carry.
    recipe: null,
    connectionBlocker: CONNECTION_BLOCKER.EXTERNAL_RUNTIME,
    bindings: Object.freeze([]),
    matches: isOpenchamberProvider,
  }),
  Object.freeze({
    id: 'codex',
    label: 'Codex',
    modes: CLI_TUI_MODES,
    protocol: 'openai',
    recipe: recipe({
      command: 'codex',
      cli: [],
      tui: [],
      baseUrl: { via: 'field' },
      credential: { via: 'field', required: false },
    }),
    bindings: Object.freeze([
      Object.freeze({ service: 'codex-subscription' }),
      // The runtimes Codex's `--oss --local-provider` can serve — the same
      // pair as `CODEX_OSS_LOCAL_PROVIDERS`, pinned by providerHarnesses.test.js.
      Object.freeze({
        localRuntime: Object.freeze(['ollama', 'lmstudio']),
        protocol: 'openai',
        baseUrl: Object.freeze({ via: 'field' }),
        credential: Object.freeze({ via: 'field', required: false }),
      }),
      Object.freeze({ protocol: 'openai', baseUrl: Object.freeze({ via: 'env', name: 'OPENAI_BASE_URL' }), credential: Object.freeze({ via: 'env', name: 'OPENAI_API_KEY', required: true }) }),
    ]),
    matches: isCodexProvider,
  }),
  Object.freeze({
    id: 'antigravity',
    label: 'Antigravity',
    modes: CLI_TUI_MODES,
    protocol: 'native',
    recipe: recipe({ command: 'agy', cli: ['--print', '--dangerously-skip-permissions'], tui: ['--dangerously-skip-permissions'] }),
    connectionBlocker: CONNECTION_BLOCKER.VENDOR_SERVICE,
    bindings: Object.freeze([Object.freeze({ service: 'antigravity' })]),
    matches: isAntigravityProvider,
  }),
  Object.freeze({
    id: 'cursor',
    label: 'Cursor Agent',
    modes: CLI_TUI_MODES,
    protocol: 'native',
    recipe: recipe({ command: 'cursor-agent', cli: ['--print', '--force'], tui: ['--force'] }),
    connectionBlocker: CONNECTION_BLOCKER.VENDOR_SERVICE,
    bindings: Object.freeze([Object.freeze({ service: 'cursor' })]),
    matches: isCursorProvider,
  }),
  Object.freeze({
    id: 'grok',
    label: 'Grok',
    modes: CLI_TUI_MODES,
    protocol: 'native',
    recipe: recipe({ command: 'grok', cli: [], tui: [] }),
    connectionBlocker: CONNECTION_BLOCKER.VENDOR_SERVICE,
    bindings: Object.freeze([Object.freeze({ service: 'grok-build' })]),
    matches: isGrokProvider,
  }),
  Object.freeze({
    id: 'kimi',
    label: 'Kimi Code',
    modes: CLI_TUI_MODES,
    protocol: 'native',
    recipe: recipe({ command: 'kimi', cli: [], tui: ['--yolo'] }),
    connectionBlocker: CONNECTION_BLOCKER.VENDOR_SERVICE,
    bindings: Object.freeze([Object.freeze({ service: 'kimi' })]),
    matches: isKimiProvider,
  }),
  Object.freeze({
    id: 'pi',
    label: 'Pi',
    modes: CLI_TUI_MODES,
    // Pi speaks both wires; `openai` is what a bare record classifies as, and
    // the binding below is what says which one a given service gets.
    protocol: 'openai',
    recipe: recipe({ command: 'pi', cli: ['--print', '--approve'], tui: ['--approve'], tuiPromptDelayMs: null }),
    connectionBlocker: CONNECTION_BLOCKER.PI_BUILTIN_PROVIDERS,
    bindings: Object.freeze([
      // Pi selects its backend by provider NAME, not by URL — see
      // CONNECTION_BLOCKER.PI_BUILTIN_PROVIDERS. The flag pair is appended to
      // the mode argv, so the shipped sample argv stays the prefix.
      Object.freeze({
        piProvider: true,
        baseUrl: Object.freeze({ via: 'piProvider', flag: '--provider' }),
        credential: Object.freeze({ via: 'env', required: true }),
      }),
    ]),
    // No `isPiProvider` predicate exists — `pi` has no vendor module of its own
    // beyond `aiToolkit/internal/pi.js`, so match its binary basename directly.
    matches: (provider) => commandBasename(provider?.command) === 'pi',
  }),
  Object.freeze({
    id: 'direct',
    label: 'Direct API',
    modes: API_ONLY_MODES,
    protocol: 'openai',
    // Not a program: nothing to spawn, so no command recipe — and no
    // `connectionBlocker` either, because it CAN be pointed at a service.
    recipe: null,
    bindings: Object.freeze([
      Object.freeze({ protocol: 'openai', baseUrl: Object.freeze({ via: 'field' }), credential: Object.freeze({ via: 'field', required: false }) }),
    ]),
    matches: (provider) => provider?.type === 'api',
  }),
]);

/** The `direct` row, resolved once: every `api` record is driven by it. */
const DIRECT_HARNESS = PROVIDER_HARNESSES.find((h) => h.id === 'direct');

/** The harness id a direct API record resolves to. */
export const DIRECT_HARNESS_ID = 'direct';

/**
 * The graph stores a direct API binding as `harness_id = NULL` (nullable
 * column, partial unique index untouched); the registry names it `direct`.
 * These two are the only translation between the two vocabularies.
 */
export const normalizeHarnessId = (harnessId) => harnessId ?? DIRECT_HARNESS_ID;
export const graphHarnessId = (harnessId) => (harnessId === DIRECT_HARNESS_ID ? null : harnessId ?? null);

/** Every harness id, for schemas that must accept only a real harness. */
export const PROVIDER_HARNESS_IDS = Object.freeze(PROVIDER_HARNESSES.map((h) => h.id));

/** The registry row for a harness id, or `null` for anything else. */
export const harnessById = (id) => PROVIDER_HARNESSES.find((h) => h.id === id) || null;

/**
 * The harnesses a fresh route can be MINTED for — the ones carrying a command
 * recipe. Everything else stays classifiable but not creatable, which is a
 * property of the program, not a gap in this table.
 */
export const CREATABLE_HARNESS_IDS = Object.freeze(
  PROVIDER_HARNESSES.filter((h) => h.recipe && !h.connectionBlocker).map((h) => h.id),
);

/** Why `harnessId` cannot be minted from a bare connection, or `null` when it can. */
export const harnessConnectionBlocker = (harnessId) => harnessById(harnessId)?.connectionBlocker ?? null;

/** The command recipe for a harness id, or `null` when it has none. */
export const harnessRecipe = (id) => harnessById(id)?.recipe || null;

/**
 * The harness a provider record is driven by, or `null` for an UNKNOWN one.
 *
 * An `api`-type record resolves to the `direct` row (#7562); it used to be
 * `null`, which conflated "no program" with "a program this build does not
 * know" — a `cli`/`tui` record with no matching row, which must stay an
 * unlinked legacy route. Graph code that stores the id passes it through
 * {@link graphHarnessId} so a direct binding still lands as `NULL`.
 *
 * @param {{id?:string, type?:string, command?:string}|null|undefined} provider
 * @returns {{id:string,label:string,modes:readonly string[],protocol:string}|null}
 */
export function harnessForProvider(provider) {
  if (!provider || typeof provider !== 'object') return null;
  if (provider.type === 'api') return DIRECT_HARNESS;
  return PROVIDER_HARNESSES.find((h) => h.matches(provider)) || null;
}

/**
 * Whether one binding's constraints all hold for a resolved service instance.
 * Every constraint present must hold; a binding with none would match
 * everything, so at least one is always declared.
 */
const bindingMatches = (binding, { definition, transports }) => (
  (binding.service === undefined || binding.service === definition.id)
  && (binding.localRuntime === undefined || binding.localRuntime.includes(definition.localRuntime))
  && (binding.piProvider === undefined || typeof definition.piProvider === 'string')
  && (binding.protocol === undefined || Boolean(transports?.[binding.protocol]))
);

/**
 * The bindings a harness may use to reach a resolved service instance (from
 * `resolveServiceInstance`), in row order — the first is the one
 * `materializeRoute` writes. Empty when the pair cannot be composed. A
 * definition that is `harnessOnly` composes onto nothing but that harness.
 */
const bindingsFor = (harness, serviceInstance) => {
  const row = typeof harness === 'string' ? harnessById(harness) : harness;
  const definition = serviceInstance?.definition;
  if (!row || !definition) return [];
  if (definition.harnessOnly && definition.harnessOnly !== row.id) return [];
  return row.bindings;
};

/**
 * @param {object|string} harness - a registry row or its id
 * @param {{definition: object, transports: object}} serviceInstance
 * @returns {readonly object[]}
 */
export const compatibleBindings = (harness, serviceInstance) =>
  bindingsFor(harness, serviceInstance).filter((binding) => bindingMatches(binding, serviceInstance));

/** The binding `materializeRoute` writes for this pair, or `null`. */
export const firstCompatibleBinding = (harness, serviceInstance) =>
  bindingsFor(harness, serviceInstance).find((binding) => bindingMatches(binding, serviceInstance)) ?? null;

/** Whether `harness` can be pointed at `serviceInstance` at all. */
export const isCompatible = (harness, serviceInstance) => firstCompatibleBinding(harness, serviceInstance) !== null;

/** Whether `harnessId` can be driven in `mode`. Unknown harness → false. */
export const harnessSupportsMode = (harnessId, mode) =>
  Boolean(harnessById(harnessId)?.modes.includes(mode));

/**
 * The route mode a provider record executes in, or `null` when its `type` is
 * not one PortOS can execute. Never inferred from a name or command — the
 * record's own `type` is the execution contract.
 */
export const providerRouteMode = (provider) =>
  ROUTE_MODES.includes(provider?.type) ? provider.type : null;

/**
 * The string this provider's harness actually accepts for a canonical backend
 * model name — today only OpenCode needs one (its `<namespace>/<model>` form).
 *
 * Delegates to `prefixOpencodeModel`, the same adapter the spawner uses, so the
 * preview can never disagree with what a run would really send.
 */
export const toExecutableModelName = (provider, canonicalModel) =>
  prefixOpencodeModel(provider, canonicalModel);

/**
 * The inverse adapter: the canonical backend name behind a STORED model string.
 *
 * Import must never rewrite a saved model string by heuristically stripping a
 * prefix, so this is verified rather than guessed — a candidate is accepted
 * only when {@link toExecutableModelName} maps it back to the exact stored
 * string. A stored string that no candidate reproduces is left untouched and
 * reported, so it stays a visible unresolved alias instead of silently becoming
 * a model the harness cannot serve.
 *
 * @param {object} provider
 * @param {string} stored - the model string as saved on the provider record
 * @returns {{canonical:string, executable:string, resolved:boolean, reason:string|null}}
 */
export function toCanonicalModelName(provider, stored) {
  const unresolved = { canonical: stored, executable: stored, resolved: false, reason: 'unmappable-model-alias' };
  if (typeof stored !== 'string' || stored === '') return unresolved;

  const namespace = getOpencodeLocalProviderNamespace(provider);
  const stripped = namespace && stored.startsWith(`${namespace}/`)
    ? stored.slice(namespace.length + 1)
    : null;

  // Shortest-first: a namespaced string canonicalizes to its bare id, and an
  // already-canonical string round-trips to itself.
  for (const candidate of [stripped, stored]) {
    if (candidate && toExecutableModelName(provider, candidate) === stored) {
      return { canonical: candidate, executable: stored, resolved: true, reason: null };
    }
  }
  return unresolved;
}