Skip to content

armgit / avibe

Public Imported from GitHub
0

Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.

37.4 KB
Raw Blame
// Model Hub API client. Presents one typed surface over the frozen
// `/api/models/*` REST endpoints.
//
// Methods unwrap the frozen envelope ({ok:true, …} | {ok:false, error}) and
// throw an Error carrying the machine code on failure, so callers work with
// plain domain objects.
import { apiFetch, isApiFetchDeadlineAbort, withApiDeadline } from '@/lib/apiFetch';
import type {
  AdoptedBy,
  AddedTo,
  AgentBackend,
  AgentChain,
  TurnProvenance,
  AgentChainMutation,
  AgentChainPut,
  AgentMode,
  AgentSourcesPut,
  AgentSupply,
  ApiKeySourceCreate,
  ApiKeySourceObservation,
  BackendModelCandidates,
  BackendModelsPut,
  CredentialReplace,
  CustomModelCreate,
  MigrationApplyResult,
  MigrationScan,
  ModelCandidate,
  ModelCandidateModelsDev,
  ModelCandidateSupplier,
  ModelsDevMatch,
  HostedToolClear,
  HostedToolName,
  HostedToolPut,
  HostedToolsStatus,
  NativeProtocol,
  OAuthFlow,
  ProbeResult,
  ResolutionEvent,
  RouteHop,
  RouteHopRef,
  RuntimeDependency,
  Source,
  SourceObservation,
  SourcePatch,
  SourceProbeResult,
  SourceRepaired,
  SupplyChannel,
  SupplyGap,
  UsageReport,
  UsageWindowKey,
  QuotaSummary,
} from './types';
import { BACKEND_MODEL_INPUT_MODALITIES, BACKEND_MODEL_OUTPUT_MODALITIES, USAGE_DEFAULT_WINDOW } from './types';

/** Add-time Route placement returned by both source-creation paths. */
export type Adoption = { added_to: AddedTo[]; adopted_by: AdoptedBy[] };
export type SourceCreated = { source: Source } & Adoption;
export type SourceRefresh = { source: Source; discovered: number };
export type CredentialReplacement = {
  source: Source;
  removed_hops: RouteHopRef[];
  interrupted: SupplyGap[];
};
export type SourcePatched = {
  source: Source;
  removed_hops: RouteHopRef[];
  interrupted: SupplyGap[];
};
export type SourceDeleted = {
  removed_hops: RouteHopRef[];
  interrupted: SupplyGap[];
};
export type GuardConfirmation = {
  force: true;
  would_remove_hops: RouteHopRef[];
  would_interrupt: SupplyGap[];
};

/**
 * The response of BOTH oauth status and submit (api.md → OAuth completion): the
 * flow, plus — once a `create` flow reaches success — the source the server
 * materialized while answering THAT request, and who took it in.
 *
 * `created` is the half a client must not throw away. The server creates the
 * source inside the very call that first reports success and consumes the flow
 * binding doing it, so a client that keeps only `flow` and then posts to
 * `/sources` to "finalize" gets `flow_not_found` on a connection that in fact
 * succeeded. `null` means this response did not report a creation (still
 * pending, failed, cancelled, or a `reauth` flow, which reports recovery
 * instead) — NOT that nothing adopted the source. That distinction is why this
 * is nullable rather than `[]`.
 *
 * `repaired` is the other terminal arm, keyed on the payload's own `intent`: a
 * `reauth` flow succeeds into `{source, recovered, interrupted_pairs}` (api.md,
 * "recovery symmetry") rather than an adoption list. At most one arm is ever
 * non-null, because a flow has exactly one intent.
 */
export type OAuthResult = {
  flow: OAuthFlow;
  created: SourceCreated | null;
  repaired: SourceRepaired | null;
};

export type ModelsApi = {
  listSources(): Promise<Source[]>;
  /** Unsaved observation; its transient credential is revoked before settling. */
  observeApiKeySource(draft: ApiKeySourceObservation, signal?: AbortSignal): Promise<SourceObservation>;
  createApiKeySource(draft: ApiKeySourceCreate): Promise<SourceCreated>;
  /** Rename / re-point a source (display_name, base_url). */
  patchSource(id: string, patch: SourcePatch): Promise<SourcePatched>;
  /** Re-run discovery on a hub source; resolves with the updated source and count.
   *  Contractually ALSO the recovery test: run on a needs_action / error source
   *  it clears the blocker and returns the source to standby. v3 adds no second
   *  「recover」 endpoint, so this is the whole retry affordance. */
  refreshSource(id: string, confirmation?: GuardConfirmation): Promise<SourceRefresh>;
  probeSource(id: string, model: string): Promise<SourceProbeResult>;
  /** Delete a source. A destructive retry echoes the server's exact guard plan. */
  deleteSource(id: string, confirmation?: GuardConfirmation): Promise<SourceDeleted>;
  /** Replace the credential of a hub-channel api_key source. The normal guarded
   *  mutation tail reports every route hop removed and model interrupted. */
  replaceCredential(id: string, body: CredentialReplace): Promise<CredentialReplacement>;
  /** Re-check a blocked search Source and arm a trial when it has no free check. */
  reenableSearchSource(id: string): Promise<Source>;
  /** Start re-authorization for a subscription source. Irreversible once it
   *  begins, which is why the acknowledgement is sent unconditionally — the
   *  server rejects a native source without it (`reauth_confirmation_required`).
   *  Resolves with the flow to drive; the repair tail arrives on its terminal
   *  status/submit response as `OAuthResult.repaired`. */
  reauthSource(id: string): Promise<OAuthFlow>;
  listAgents(): Promise<AgentSupply[]>;
  /** Deep CLI discovery used after the fast Agent snapshot has painted. */
  refreshAgentPresence(): Promise<AgentSupply[]>;
  /** Per-backend enabled subset + order (the 来源顺序 drawer's read). */
  getAgentSources(backend: AgentBackend): Promise<AgentSupply>;
  /** Total write of the exact stored source order. */
  putAgentSources(backend: AgentBackend, body: AgentSourcesPut): Promise<AgentSupply>;
  /** Store an optional source order and apply it to every existing route atomically. */
  reorderAgentChains(backend: AgentBackend, order?: string[]): Promise<AgentSupply>;
  /** Resolution chain for one model. Hub mode only — direct answers `direct_mode`. */
  getAgentChain(backend: AgentBackend, model: string): Promise<AgentChain>;
  getAgentProvenance(backend: AgentBackend, model: string): Promise<TurnProvenance | null>;
  getTurnProvenance(turnId: string): Promise<TurnProvenance>;
  /** Complete overview chain projection for one Hub backend. */
  getAgentChains(backend: AgentBackend): Promise<AgentChain[]>;
  /** Total replacement of the exact stored chain. */
  putAgentChain(backend: AgentBackend, model: string, body: AgentChainPut): Promise<AgentChainMutation>;
  previewAgentChain(backend: AgentBackend, model: string, body: { manual_override: { hops: RouteHop[] } | null }): Promise<AgentChain>;
  restoreAgentChain(backend: AgentBackend, model: string, body?: GuardConfirmation): Promise<AgentChainMutation>;
  /** One real request through the chain. Hub mode only, same reason. */
  probeAgent(backend: AgentBackend, model?: string): Promise<ProbeResult>;
  setAgentMode(backend: AgentBackend, mode: AgentMode): Promise<AgentSupply>;
  /** Apply the difference between `baseline` and `models` to the latest saved
   *  catalog. The echoed `AgentSupply.catalog_models` is canonical — including
   *  the order, the server-derived `locked`/`routeable`, and any concurrent
   *  edit this caller never saw. */
  putAgentModels(backend: AgentBackend, body: BackendModelsPut): Promise<AgentSupply>;
  /** Everything the picker can offer for this backend, already grouped, deduped
   *  and ordered by the server (C4). A pure read. */
  getAgentModelCandidates(backend: AgentBackend): Promise<BackendModelCandidates>;
  /** Normalized models.dev candidates for a free-text query. A pure read: it
   *  persists nothing, so a fill the user abandons leaves no trace. */
  searchModelsDev(query: string, signal?: AbortSignal): Promise<ModelsDevMatch[]>;
  addCustomModel(sourceId: string, draft: CustomModelCreate): Promise<Source>;
  updateModelReasoningEfforts(sourceId: string, modelId: string, reasoningEfforts: string[]): Promise<Source>;
  deleteCustomModel(sourceId: string, modelId: string, confirmation?: GuardConfirmation): Promise<Source>;
  scanMigration(): Promise<MigrationScan>;
  /** API keys are copied and kept natively unless `cleanApiKeys`. */
  applyMigration(itemIds: string[], cleanApiKeys?: boolean): Promise<MigrationApplyResult>;
  /** `before` is an event id cursor (「查看全部」 pagination). */
  listEvents(limit?: number, before?: string): Promise<ResolutionEvent[]>;
  /** Usage analytics over the explicit modern window selector. */
  getUsageSummary(window?: UsageWindowKey): Promise<UsageReport>;
  /** Subscription rate-limit windows, served from the service's 5-minute cache. */
  getQuota(): Promise<QuotaSummary>;
  /** The same report, re-read now (the service bounds how often). */
  refreshQuota(): Promise<QuotaSummary>;
  /** The Tools tab read: each hosted tool's setting and what real use learned. */
  getHostedTools(): Promise<HostedToolsStatus>;
  /** Change the fields the body names; answers the whole status again. */
  putHostedTool(tool: HostedToolName, body: HostedToolPut): Promise<HostedToolsStatus>;
  /** Clear a tool's refusals (one Source, one of its models, or all); answers the whole status again. */
  clearHostedTool(tool: HostedToolName, body: HostedToolClear): Promise<HostedToolsStatus>;
  /** S2 route: offered only when a service candidate carries a cooldown. */
  retrySearchService(sourceId: string): Promise<void>;
  retryFetchService(sourceId: string): Promise<void>;
  /** Clear one refused reasoning effort on a Source model; answers that Source. */
  clearRefusedEffort(sourceId: string, modelId: string, effort: string): Promise<Source>;
  getRuntimeStatus(): Promise<RuntimeDependency>;
  /** Start the contract-owned client installation transaction. */
  installRuntime(): Promise<RuntimeDependency>;
  startRuntime(): Promise<RuntimeDependency>;
  startOAuth(vendor: string, channel: SupplyChannel, clientNonce?: string): Promise<OAuthFlow>;
  getOAuthStatus(flowId: string): Promise<OAuthResult>;
  submitOAuth(flowId: string, value: string): Promise<OAuthResult>;
  cancelOAuth(flowId: string): Promise<void>;
};

export class ApiCallError extends Error {
  code: string;
  detail?: string;
  /**
   * The `source_last_supplier` payload half. Carried on the error rather than
   * looked up afterwards for the same reason `adopted_by` travels with a
   * creation: it is the server's evaluation of the write it just refused, and
   * no later read of `/agents` reproduces it — that read describes today's
   * supply, not the supply the refused write would have left behind.
   *
   * `[]` on every other code, so a call site can render the gap report without
   * first proving which error it has.
   */
  wouldInterrupt: SupplyGap[];
  wouldRemoveHops: RouteHopRef[];
  /**
   * The OTHER half, and deliberately not the same field: `would_interrupt` names
   * what a REFUSED write would have stranded (nothing changed, the copy is future
   * tense), while `interrupted_pairs` on an error names what a write that already
   * COMMITTED did strand. A native reauth is where that difference is not
   * academic — `_materialize_reauth` clears the source, marks it unavailable, and
   * only then answers `discovery_failed` with the pairs beside it, so these gaps
   * are a report about the past, not a confirm about the future. Collapsed into
   * one field, the caller would have no way to pick the right tense.
   */
  interrupted: SupplyGap[];
  /**
   * Whether the ROUTE named this failure, i.e. whether `code` came off the wire.
   *
   * Two of the codes here are this client's own summary of a response that never
   * said what happened: `bad_response` when the body would not parse, `http_<n>`
   * when it parsed and carried no `error`. They are not outcomes — a route that
   * names a failure has already decided what it did, while these say only that
   * the answer did not arrive intact, which the server having written first is
   * entirely consistent with. Anything downstream that skips a corrective re-read
   * because 「the route said so」 has to ask this rather than 「is it one of ours?」.
   *
   * `true` by default because a named route error IS an outcome. `call` marks
   * each client-invented transport summary as false at its construction site.
   */
  serverNamed: boolean;
  /**
   * A stale-candidate refusal's `changed` map, keyed by added model id.
   *
   * Its own field, and deliberately not one of the two above: a guard refusal
   * reports what a write WOULD have destroyed and is answered by echoing that
   * plan back with `force`. This one destroys nothing and interrupts nothing —
   * the save simply did not happen, because the suppliers the picker displayed
   * are no longer the ones the server would seed. Forcing it would commit the
   * projection the user never saw, so the answer is the opposite: show these
   * suppliers and ask again. Collapsed into `wouldRemoveHops`, a caller could
   * not tell 「confirm this loss」 from 「re-read and re-ask」.
   *
   * `{}` on every other code, so a call site can read it without first proving
   * which error it has.
   */
  changedSuppliers: Record<string, RouteHop[]>;
  /** HTTP status observed by this client. Absent when no response arrived. */
  responseStatus?: number;
  /** Safe, structured add-time observation returned with a rejected create. */
  observation?: SourceObservation;
  constructor(
    code: string,
    detail?: string,
    serverNamed = true,
    wouldInterrupt: SupplyGap[] = [],
    interrupted: SupplyGap[] = [],
    wouldRemoveHops: RouteHopRef[] = [],
    responseStatus?: number,
    observation?: SourceObservation,
    changed: Record<string, RouteHop[]> = {},
  ) {
    super(detail || code);
    this.name = 'ApiCallError';
    this.code = code;
    this.detail = detail;
    this.serverNamed = serverNamed;
    this.wouldInterrupt = wouldInterrupt;
    this.interrupted = interrupted;
    this.wouldRemoveHops = wouldRemoveHops;
    this.changedSuppliers = changed;
    this.responseStatus = responseStatus;
    this.observation = observation;
  }
}

/** Normalize to the FULL contract shape: a gap without `agents` is a gap whose
 *  confirm copy has nothing to name, and `[]` renders as 「无」 rather than
 *  crashing the dialog that was opened to explain the refusal. */
const supplyGaps = (raw: unknown): SupplyGap[] =>
  Array.isArray(raw)
    ? raw
        .filter((g): g is Record<string, unknown> => Boolean(g) && typeof g === 'object')
        .map((g) => ({
          backend: g.backend as SupplyGap['backend'],
          model_id: String(g.model_id ?? ''),
          agents: Array.isArray(g.agents) ? g.agents.map(String) : [],
        }))
    : [];

const candidateSuppliers = (raw: unknown): ModelCandidateSupplier[] =>
  Array.isArray(raw)
    ? raw.flatMap((entry) => {
        if (!entry || typeof entry !== 'object') return [];
        const row = entry as Record<string, unknown>;
        return typeof row.source_id === 'string' && typeof row.model_id === 'string'
          ? [{
              source_id: row.source_id,
              model_id: row.model_id,
              // The display name a chip renders. Falls back to the id rather than
              // to an empty chip: an unnamed supplier is still one the user must
              // be able to recognize.
              source_name: typeof row.source_name === 'string' && row.source_name
                ? row.source_name
                : row.source_id,
            }]
          : [];
      })
    : [];

type CandidateOrigin = ModelCandidate['origin'];
/** The creation paths a candidate may state. A runtime set, because the type it
 *  mirrors erases — and asserted equal to the schema's own enum in
 *  `backendModelContract.test.ts`, so a path the contract gains fails a test
 *  rather than being quietly read as the group's fallback. */
export const CANDIDATE_ORIGINS: readonly CandidateOrigin[] = ['builtin', 'provider', 'models_dev', 'manual'];

/** The groups the server names as a removed row's way back (C4). A value it
 *  does not state is not a group, and `null` is a value it states. */
const REENTRY_GROUPS: readonly ('builtin' | 'providers')[] = ['builtin', 'providers'];
const NATIVE_PROTOCOLS: readonly NativeProtocol[] = ['openai_responses', 'anthropic'];

/** What the server says would offer this id again if it left the menu, read
 *  only when the server says it. Absent stays absent rather than becoming
 *  `null`: the two mean the same thing to the picker, and inventing a stated
 *  answer out of an unstated one is how a client starts deriving the field. */
const reentryGroup = (raw: Record<string, unknown>): Pick<ModelCandidate, 'group_if_removed'> => {
  if (!('group_if_removed' in raw)) return {};
  const stated = raw.group_if_removed;
  if (stated === null) return { group_if_removed: null };
  return REENTRY_GROUPS.includes(stated as 'builtin' | 'providers')
    ? { group_if_removed: stated as 'builtin' | 'providers' }
    : {};
};

const positiveInt = (value: unknown): number | null =>
  typeof value === 'number' && Number.isInteger(value) && value > 0 ? value : null;
const flag = (value: unknown): boolean | null => (typeof value === 'boolean' ? value : null);
const members = <T extends string>(value: unknown, allowed: readonly T[]): T[] =>
  Array.isArray(value) ? value.filter((item): item is T => allowed.includes(item as T)) : [];

/** A candidate's models.dev description, kept whole or not at all: the server
 *  states the seven fields together, keyed by `models_dev_id`. */
const candidateModelsDev = (row: Record<string, unknown>): ModelCandidateModelsDev | Record<string, never> =>
  typeof row.models_dev_id === 'string' && row.models_dev_id
    ? {
        models_dev_id: row.models_dev_id,
        context_window: positiveInt(row.context_window),
        max_output_tokens: positiveInt(row.max_output_tokens),
        input_modalities: members(row.input_modalities, BACKEND_MODEL_INPUT_MODALITIES),
        output_modalities: members(row.output_modalities, BACKEND_MODEL_OUTPUT_MODALITIES),
        supports_tools: flag(row.supports_tools),
        supports_reasoning: flag(row.supports_reasoning),
      }
    : {};

/**
 * One candidate group, read defensively.
 *
 * `fallbackOrigin` is the group's own creation path (C2), used only when the
 * server omits `origin`. It is not a guess about the model: the group a
 * candidate arrives in IS its creation path, so the two can never disagree.
 */
const modelCandidates = (raw: unknown, fallbackOrigin: CandidateOrigin): ModelCandidate[] =>
  Array.isArray(raw)
    ? raw.flatMap((entry) => {
        if (!entry || typeof entry !== 'object') return [];
        const row = entry as Record<string, unknown>;
        if (typeof row.id !== 'string' || !row.id) return [];
        return [{
          id: row.id,
          display_name: typeof row.display_name === 'string' && row.display_name ? row.display_name : null,
          reasoning_efforts: Array.isArray(row.reasoning_efforts)
            ? row.reasoning_efforts.filter((effort): effort is string => typeof effort === 'string')
            : [],
          suppliers: candidateSuppliers(row.suppliers),
          origin: CANDIDATE_ORIGINS.includes(row.origin as CandidateOrigin)
            ? row.origin as CandidateOrigin
            : fallbackOrigin,
          ...(NATIVE_PROTOCOLS.includes(row.native_protocol as NativeProtocol)
            ? { native_protocol: row.native_protocol as NativeProtocol }
            : {}),
          ...reentryGroup(row),
          ...candidateModelsDev(row),
        }];
      })
    : [];

const routeHopRefs = (raw: unknown): RouteHopRef[] =>
  Array.isArray(raw)
    ? raw.filter((hop): hop is RouteHopRef => Boolean(hop) && typeof hop === 'object')
    : [];

/** The `changed` map of a stale-candidate refusal: the suppliers the server
 *  matched at commit time, keyed by the added model id whose displayed
 *  projection they disagree with. Ids the caller never listed are absent, and an
 *  entry may be empty — 「nothing supplies this any more」 is itself the change
 *  the user has to see. */
const changedSuppliers = (raw: unknown): Record<string, RouteHop[]> => {
  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return {};
  const changed: Record<string, RouteHop[]> = {};
  for (const [modelId, hops] of Object.entries(raw as Record<string, unknown>)) {
    if (!Array.isArray(hops)) continue;
    changed[modelId] = hops.flatMap((hop) => {
      if (!hop || typeof hop !== 'object') return [];
      const row = hop as Record<string, unknown>;
      return typeof row.source_id === 'string' && typeof row.model_id === 'string'
        ? [{ source_id: row.source_id, model_id: row.model_id }]
        : [];
    });
  }
  return changed;
};

/**
 * The one reader every call site uses instead of casting a caught `unknown`.
 *
 * Both clients throw `ApiCallError`, but a caught value is still `unknown` to
 * TypeScript, and `(err as {code?: string}).code` spread across call sites is
 * how a renamed field goes silently unread. Returns null for anything that is
 * not one of ours — a TypeError from our own render code must not be reported
 * to the user as a supply refusal.
 */
export const apiFailure = (
  err: unknown,
): {
  code: string;
  detail?: string;
  serverNamed: boolean;
  wouldInterrupt: SupplyGap[];
  interrupted: SupplyGap[];
  wouldRemoveHops: RouteHopRef[];
  changedSuppliers: Record<string, RouteHop[]>;
  responseStatus?: number;
  observation?: SourceObservation;
} | null =>
  err instanceof ApiCallError
    ? {
        code: err.code,
        detail: err.detail,
        serverNamed: err.serverNamed,
        wouldInterrupt: err.wouldInterrupt,
        interrupted: err.interrupted,
        wouldRemoveHops: err.wouldRemoveHops,
        changedSuppliers: err.changedSuppliers,
        responseStatus: err.responseStatus,
        observation: err.observation,
      }
    : null;

// The server owns the execution ceiling; this browser deadline is only a
// backstop for a server that never answers, so it must outlast that controlled
// failure. The margin covers CSRF acquisition, both transits (including a
// tunnel), one fast CSRF-rejected attempt and replay, handler dispatch, and body
// decoding. Keep the ceiling aligned with vibe/model_hub_client.py:MODEL_HUB_RPC_TIMEOUT_SECONDS.
export const MODEL_HUB_RPC_CEILING_MS = 300_000;
const TRANSPORT_MARGIN_MS = 30_000;
export const MODEL_HUB_REQUEST_DEADLINE_MS =
  MODEL_HUB_RPC_CEILING_MS + TRANSPORT_MARGIN_MS;

async function call<T>(path: string, init?: RequestInit): Promise<T> {
  try {
    return await withApiDeadline(
      MODEL_HUB_REQUEST_DEADLINE_MS,
      init?.signal ?? undefined,
      async (signal) => {
        const res = await apiFetch(path, { ...init, signal });
        let payload: unknown = null;
        try {
          payload = await res.json();
        } catch (error) {
          if (signal.aborted) {
            throw signal.reason ?? error;
          }
          // Invented here, not read off the wire: the request may well have been
          // carried out and its answer lost coming back.
          throw new ApiCallError('bad_response', `Non-JSON response from ${path}`, false, [], [], [], res.status);
        }
        const envelope = payload && typeof payload === 'object' ? payload as Record<string, unknown> : {};
        if (!res.ok || envelope.ok === false) {
          const error = typeof envelope.error === 'string' ? envelope.error : null;
          throw new ApiCallError(
            error ?? `http_${res.status}`,
            typeof envelope.detail === 'string' ? envelope.detail : undefined,
            // `payload.error` is the only thing that carries a route's own verdict, so
            // its presence IS the answer. `http_502` is this client summarizing a
            // response that never gave one.
            error !== null,
            supplyGaps(envelope.would_interrupt),
            supplyGaps(envelope.interrupted_pairs),
            routeHopRefs(envelope.would_remove_hops),
            res.status,
            typeof envelope.observation === 'object' && envelope.observation !== null
              ? envelope.observation as SourceObservation
              : undefined,
            changedSuppliers(envelope.changed),
          );
        }
        return payload as T;
      },
    );
  } catch (error) {
    if (!isApiFetchDeadlineAbort(error)) throw error;
    // The deadline says the answer did not arrive, not whether the route wrote.
    throw new ApiCallError('bad_response', `Request deadline exceeded for ${path}`, false);
  }
}

const jsonInit = (method: string, body?: unknown): RequestInit => ({
  method,
  headers: { 'Content-Type': 'application/json' },
  body: body === undefined ? undefined : JSON.stringify(body),
});

/** The creation response's add-time placement projection. */
type AdoptionTail = { added_to?: AddedTo[]; adopted_by?: AdoptedBy[] };
const adoption = (r: AdoptionTail): Adoption => ({
  added_to: r.added_to ?? [],
  adopted_by: r.adopted_by ?? [],
});

/** api.md pins the shape to `{source, added_to, adopted_by}` with no extra
 *  nesting; the bare-`Source` arm is the same tolerance every other write here
 *  keeps. */
type SourceCreatedResponse = { source?: Source } & AdoptionTail & Source;
const created = (r: SourceCreatedResponse): SourceCreated => ({
  source: (r.source ?? r) as Source,
  ...adoption(r),
});

type CredentialReplacementResponse = {
  source?: Source;
  removed_hops?: RouteHopRef[];
  interrupted?: SupplyGap[];
} & Source;

const credentialReplacement = (r: CredentialReplacementResponse): CredentialReplacement => ({
  source: (r.source ?? r) as Source,
  removed_hops: routeHopRefs(r.removed_hops),
  interrupted: supplyGaps(r.interrupted),
});

type SourcePatchedResponse = {
  source?: Source;
  removed_hops?: RouteHopRef[];
  interrupted?: SupplyGap[];
} & Source;

const sourcePatched = (r: SourcePatchedResponse): SourcePatched => ({
  source: (r.source ?? r) as Source,
  removed_hops: routeHopRefs(r.removed_hops),
  interrupted: supplyGaps(r.interrupted),
});

type SourceDeletedResponse = {
  removed_hops?: RouteHopRef[];
  interrupted?: SupplyGap[];
};

const sourceDeleted = (r: SourceDeletedResponse): SourceDeleted => ({
  removed_hops: routeHopRefs(r.removed_hops),
  interrupted: supplyGaps(r.interrupted),
});

/** The oauth terminal envelope, unwrapped without discarding either tail. */
export type OAuthResultResponse = { flow?: OAuthFlow } & OAuthFlow &
  AdoptionTail & {
    source?: Source;
    recovered?: boolean;
    interrupted_pairs?: SupplyGap[];
  };
/** Exported for its own test: this is where the create half was being dropped. */
export const oauthResult = (r: OAuthResultResponse): OAuthResult => {
  const flow = (r.flow ?? r) as OAuthFlow;
  // Discriminate on the payload's own `intent`, not on which dialog is open:
  // `reauth` also terminates with a `source` but carries recovery counts instead
  // of adoption, and reading those as an adoption list would report the wrong
  // thing about the wrong flow. Absent `intent` is a `create` flow (the field
  // postdates the first shipped payloads, and create is the flow this UI starts
  // from the vendor buttons).
  const isCreate = flow.intent !== 'reauth';
  return {
    flow,
    // No bare-`Source` tolerance here, unlike `created()`: this envelope always
    // nests the source under `source`, beside the flow it accompanies. The tail
    // itself goes through the same `adoption` reader, so the two routes cannot
    // default one of these arrays differently from the other.
    created: isCreate && r.source ? { source: r.source, ...adoption(r) } : null,
    // The repair tail. `recovered` is defaulted false rather than optional: it is
    // the server's own 「this source had been blocked」 judgement, and absent must
    // read as 「did not say so」 — never as a client guess that it was.
    repaired:
      !isCreate && r.source
        ? {
            source: r.source,
            recovered: r.recovered === true,
            interrupted_pairs: supplyGaps(r.interrupted_pairs),
          }
        : null,
  };
};

/** The single client instance. Stable across renders (safe in effect deps). */
export const modelsApi: ModelsApi = {
  listSources: () => call<{ sources: Source[] }>('/api/models/sources').then((r) => r.sources),
  observeApiKeySource: (draft, signal) =>
    call<{ observation: SourceObservation }>('/api/models/sources/observe', {
      ...jsonInit('POST', draft),
      signal,
    }).then((r) => r.observation),
  // Both keep `adopted_by`. The old unwrap-to-`source` dropped it on the floor,
  // and no later read can put it back: `/agents` shows today's orders, not which
  // of them this commit changed.
  createApiKeySource: (draft) => call<SourceCreatedResponse>('/api/models/sources', jsonInit('POST', draft)).then(created),
  patchSource: (id, patch) => call<SourcePatchedResponse>(`/api/models/sources/${encodeURIComponent(id)}`, jsonInit('PATCH', patch)).then(sourcePatched),
  refreshSource: (id, confirmation) => call<SourceRefresh>(`/api/models/sources/${encodeURIComponent(id)}/refresh`, jsonInit('POST', confirmation ?? {})),
  reenableSearchSource: (id) => call<{ source: Source }>(`/api/models/sources/${encodeURIComponent(id)}/reenable`, jsonInit('POST', {})).then((r) => r.source),
  probeSource: (id, model) => call<{ probe: SourceProbeResult }>(
    `/api/models/sources/${encodeURIComponent(id)}/probe`, jsonInit('POST', { model }),
  ).then((r) => r.probe),
  deleteSource: (id, confirmation) => call<SourceDeletedResponse>(
    `/api/models/sources/${encodeURIComponent(id)}${confirmation ? '?force=true' : ''}`,
    jsonInit('DELETE', confirmation ? {
      would_remove_hops: confirmation.would_remove_hops,
      would_interrupt: confirmation.would_interrupt,
    } : undefined),
  ).then(sourceDeleted),
  // Both repair routes reject unknown body keys outright (`discovery_failed` /
  // `reauth_confirmation_required`), so these bodies are exactly the contract's
  // and carry no `contract_version` — the same closed-body rule as putAgentSources.
  replaceCredential: (id, body) => call<CredentialReplacementResponse>(`/api/models/sources/${encodeURIComponent(id)}/credential`, jsonInit('PUT', body)).then(credentialReplacement),
  // The OAuth acknowledgement is unconditional because beginning reauth may
  // irreversibly replace grant material. It does not stand in for destructive
  // supply consent: guarded inventory mutations separately echo the server plan.
  reauthSource: (id) => call<{ flow?: OAuthFlow } & OAuthFlow>(`/api/models/sources/${encodeURIComponent(id)}/reauth`, jsonInit('POST', { acknowledge_irreversible: true })).then((r) => (r.flow ?? r) as OAuthFlow),
  listAgents: () => call<{ agents: AgentSupply[] }>('/api/models/agents').then((r) => r.agents),
  refreshAgentPresence: () => call<{ agents: AgentSupply[] }>('/api/models/agents?refresh_cli_presence=1').then((r) => r.agents),
  getAgentSources: (backend) => call<{ agent: AgentSupply }>(`/api/models/agents/${backend}/sources`).then((r) => r.agent),
  // The body is TOTAL and closed: the route rejects unknown keys, so
  // `contract_version` is deliberately absent (unlike every other write here).
  putAgentSources: (backend, body) => call<{ agent: AgentSupply }>(`/api/models/agents/${backend}/sources`, jsonInit('PUT', body)).then((r) => r.agent),
  reorderAgentChains: (backend, order) => call<{ agent: AgentSupply }>(
    `/api/models/agents/${backend}/chains/reorder`,
    jsonInit('POST', order === undefined ? undefined : { order }),
  ).then((r) => r.agent),
  getAgentChain: (backend, model) => call<{ chain: AgentChain }>(`/api/models/agents/${backend}/chain?model=${encodeURIComponent(model)}`).then((r) => r.chain),
  getTurnProvenance: (turnId) => call<{ provenance: TurnProvenance }>(`/api/models/turns/${encodeURIComponent(turnId)}/provenance`).then((r) => r.provenance),
  getAgentProvenance: (backend, model) => call<{ provenance: TurnProvenance | null }>(`/api/models/agents/${backend}/provenance?model=${encodeURIComponent(model)}`).then((r) => r.provenance),
  getAgentChains: (backend) => call<{ chains: AgentChain[] }>(`/api/models/agents/${backend}/chains`).then((r) => r.chains),
  putAgentChain: (backend, model, body) => call<AgentChainMutation>(`/api/models/agents/${backend}/chain?model=${encodeURIComponent(model)}`, jsonInit('PUT', body)),
  previewAgentChain: (backend, model, body) => call<{ chain: AgentChain }>(`/api/models/agents/${backend}/chain/preview?model=${encodeURIComponent(model)}`, jsonInit('POST', body)).then((r) => r.chain),
  restoreAgentChain: (backend, model, body) => call<AgentChainMutation>(`/api/models/agents/${backend}/chain?model=${encodeURIComponent(model)}`, jsonInit('DELETE', body ?? {})),
  probeAgent: (backend, model) => call<{ probe: ProbeResult }>(`/api/models/agents/${backend}/probe`, jsonInit('POST', model ? { model } : {})).then((r) => r.probe),
  setAgentMode: (backend, mode) => call<{ agent?: AgentSupply } & AgentSupply>(`/api/models/agents/${backend}/mode`, jsonInit('PATCH', { mode })).then((r) => (r.agent ?? r) as AgentSupply),
  putAgentModels: (backend, body) => call<{ agent?: AgentSupply } & AgentSupply>(`/api/models/agents/${backend}/models`, jsonInit('PUT', body)).then((r) => (r.agent ?? r) as AgentSupply),
  getAgentModelCandidates: (backend) => call<{ candidates?: Record<string, unknown> }>(
    `/api/models/agents/${backend}/models/candidates`,
  ).then((r) => ({
    builtin: modelCandidates(r.candidates?.builtin, 'builtin'),
    providers: modelCandidates(r.candidates?.providers, 'provider'),
    // An in-list row's origin is whatever it was created as, so this group has
    // no creation path of its own to fall back to. `manual` is the floor a row
    // with no stated origin already carries (`blankBackendModel`), and nothing
    // reads it here: these rows are disabled, and only a pickable candidate is
    // ever poured into a draft.
    in_list: modelCandidates(r.candidates?.in_list, 'manual'),
  })),
  searchModelsDev: (query, signal) => call<{ matches: ModelsDevMatch[] }>(
    `/api/models/catalog/models-dev?query=${encodeURIComponent(query)}`,
    { signal },
  ).then((r) => r.matches ?? []),
  addCustomModel: (sourceId, draft) => call<{ source?: Source } & Source>(`/api/models/sources/${encodeURIComponent(sourceId)}/models`, jsonInit('POST', draft)).then((r) => (r.source ?? r) as Source),
  updateModelReasoningEfforts: (sourceId, modelId, reasoningEfforts) => call<{ source?: Source } & Source>(`/api/models/sources/${encodeURIComponent(sourceId)}/models/${encodeURIComponent(modelId)}`, jsonInit('PATCH', { reasoning_efforts: reasoningEfforts })).then((r) => (r.source ?? r) as Source),
  deleteCustomModel: (sourceId, modelId, confirmation) => call<{ source?: Source } & Source>(`/api/models/sources/${encodeURIComponent(sourceId)}/models/${encodeURIComponent(modelId)}`, jsonInit('DELETE', confirmation ?? {})).then((r) => (r.source ?? r) as Source),
  scanMigration: () => call<{ scan?: MigrationScan } & MigrationScan>('/api/models/migration/scan', jsonInit('POST')).then((r) => (r.scan ?? r) as MigrationScan),
  applyMigration: (itemIds, cleanApiKeys = false) => call<MigrationApplyResult>(
    '/api/models/migration/apply',
    jsonInit('POST', { item_ids: itemIds, clean_api_keys: cleanApiKeys }),
  ),
  listEvents: (limit = 20, before) =>
    call<{ events: ResolutionEvent[] }>(
      `/api/models/events?limit=${limit}${before ? `&before=${encodeURIComponent(before)}` : ''}`,
    ).then((r) => r.events),
  getUsageSummary: (window = USAGE_DEFAULT_WINDOW) =>
    call<{ usage: UsageReport }>(`/api/models/usage?window=${window}`).then((r) => r.usage),
  getQuota: () => call<{ quota: QuotaSummary }>('/api/models/quota').then((r) => r.quota),
  refreshQuota: () => call<{ quota: QuotaSummary }>('/api/models/quota/refresh', jsonInit('POST')).then((r) => r.quota),
  getHostedTools: () => call<{ hosted_tools: HostedToolsStatus }>('/api/models/hosted-tools').then((r) => r.hosted_tools),
  putHostedTool: (tool, body) => call<{ hosted_tools: HostedToolsStatus }>(
    `/api/models/hosted-tools/${encodeURIComponent(tool)}`, jsonInit('PUT', body),
  ).then((r) => r.hosted_tools),
  clearHostedTool: (tool, body) => call<{ hosted_tools: HostedToolsStatus }>(
    `/api/models/hosted-tools/${encodeURIComponent(tool)}/clear`, jsonInit('POST', body),
  ).then((r) => r.hosted_tools),
  retrySearchService: (sourceId) => call(
    `/api/models/hosted-tools/web_search/services/${encodeURIComponent(sourceId)}/retry`, jsonInit('POST', {}),
  ).then(() => undefined),
  retryFetchService: (sourceId) => call(
    `/api/models/hosted-tools/web_fetch/services/${encodeURIComponent(sourceId)}/retry`, jsonInit('POST', {}),
  ).then(() => undefined),
  clearRefusedEffort: (sourceId, modelId, effort) => call<{ source: Source }>(
    `/api/models/sources/${encodeURIComponent(sourceId)}/evidence/clear`,
    jsonInit('POST', { model_id: modelId, feature: { kind: 'effort', name: effort } }),
  ).then((r) => r.source),
  getRuntimeStatus: () => call<{ runtime?: RuntimeDependency } & RuntimeDependency>('/api/models/runtime/status').then((r) => (r.runtime ?? r) as RuntimeDependency),
  installRuntime: () => call<{ runtime?: RuntimeDependency } & RuntimeDependency>('/api/models/runtime/install', jsonInit('POST')).then((r) => (r.runtime ?? r) as RuntimeDependency),
  startRuntime: () => call<{ runtime?: RuntimeDependency } & RuntimeDependency>('/api/models/runtime/start', jsonInit('POST')).then((r) => (r.runtime ?? r) as RuntimeDependency),
  startOAuth: (vendor, channel, clientNonce) =>
    call<{ flow?: OAuthFlow } & OAuthFlow>(
      '/api/models/oauth/start',
      jsonInit('POST', { vendor, channel, ...(clientNonce ? { client_nonce: clientNonce } : {}) }),
    ).then((r) => (r.flow ?? r) as OAuthFlow),
  getOAuthStatus: (flowId) => call<OAuthResultResponse>(`/api/models/oauth/status/${encodeURIComponent(flowId)}`).then(oauthResult),
  submitOAuth: (flowId, value) => call<OAuthResultResponse>('/api/models/oauth/submit', jsonInit('POST', { flow_id: flowId, value })).then(oauthResult),
  cancelOAuth: (flowId) => call('/api/models/oauth/cancel', jsonInit('POST', { flow_id: flowId })).then(() => undefined),
};