fix: stop treating a model list as an allowlist (#3330)

* fix(core,runtime,runtime-host,storage): stop treating a model list as an allowlist

A Volcengine Ark Agent Plan key could not select the models its own plan
serves. The plan's key reaches only the inference data plane, so Maka had
no way to enumerate the account and fell back to the array this build
ships. Every gate then read that array as the set of models the account
has, and refused everything else.

The array is not that set, and no array Maka holds is. A `/models`
response describes one call at one moment, scoped to whatever the
provider chose to report; a shipped snapshot describes the provider, not
the account; and four providers have no list endpoint at all. Only the
user knows what their account can run, and only the provider can settle
it — by answering the request.

So the allowlist goes, rather than growing another exception:

- `authorizeConnectionModel` in `llm-connections.ts` is the one seam that
  answers "can this connection run this model". The user's selection is
  the authorization. The observed row still wins wherever it exists, for
  its wire metadata and capabilities, but its absence authorizes nothing
  and vetoes nothing.
- A fetch no longer prunes what the user chose. `reconcileConnectionAfterModelFetch`
  seeds a first default only for a connection that has never had a list
  to pick from, and otherwise returns the selection untouched.
- `filterDiscoveredModels` no longer intersects a live response with the
  shipped snapshot, which was silently dropping models from six
  providers whose real catalogs outgrew it.
- Readiness, the connection probe, the hosted execution target and the
  catalog coordinator all consult that one seam. `connection-model-admission.ts`
  and its hardcoded DeepSeek exception are deleted.

What the picker SAYS is unchanged in spirit and now purely advisory:
`classifyConnectionModelInventory` still separates a live response from a
snapshot, and a model the live response omitted is annotated
`not_in_live_list` — a warning the user can act on, not a refusal.

Fixes #1584

Generated-by: Claude Code

* feat(core,runtime,desktop): let a user state the model facts Maka cannot learn

Once a model no catalog lists is selectable, the user needs somewhere to
put what they know about it, and a way to add it in the first place.

Model declarations (`relayModelProfiles`) already existed but were
refused on any non-relay connection. That gate split the wrong way. It
turns on the FIELD, not the provider:

- `contextWindow` and `vision` state facts about a model. A user has them
  whenever Maka does not — a model newer than the bundled snapshot, or
  any model on a provider with no model-list endpoint — so they are legal
  on every provider.
- `thinkingLevels` and `serviceTier` name a wire feature instead
  (`reasoning_effort` tiers, priority processing) that only the
  OpenAI-compatible relays accept, and stay relay-only. Declaring them
  elsewhere would describe a request Maka never sends, or draw a 400 the
  user cannot explain.

`assertProfileFieldsFitProvider` in the catalog codec is the single write
seam for that rule, so the read paths do not re-derive it.

On the settings side, a connection detail page now offers "Add model"
alongside "Update models" rather than instead of it: the two answer
different questions, and a provider that supports discovery can still
serve a model its discovery did not report. The dialog takes an id plus
the optional declarations above.

The field name stays `relayModelProfiles` — renaming a persisted field is
a migration this change does not need — and its doc comment now explains
that the name is historical.

Generated-by: Claude Code

* fix(desktop): hold the add-model draft until the write lands

The dialog closed on submit and cleared both fields while the write was
still in flight, so a rejection left the user with a toast and nothing to
retry from — and an exact model id is not something anyone reproduces
from memory, which is the whole reason this dialog asks for one.

`addDeclaredModel` now returns whether the write landed, matching `save`
and `saveRelayProfiles` in the same hook, and the dialog closes only on
success. While the write is in flight the confirm button shows a saving
state and dismissal is refused, as in `goal-dialog`.

Generated-by: Claude Code

Author: Astro-Han

apps/desktop/src/renderer/locales/settings-provider-copy.ts

@@ -69,6 +69,16 @@ const zhCopy = {
     credentialUnknownDetail: '模型凭据状态暂时没刷新成功，已避免把未知状态显示成未登录或未配置。',
     testConnection: '测试连接',
     updateModels: '更新模型目录', endpoint: '服务地址',
+    addModel: '添加模型',
+    addModelConfirm: '添加',
+    addModelIdField: '模型 ID',
+    addModelIdFieldHelp: '需与服务商完全一致，区分大小写。',
+    addModelIdPlaceholder: 'deepseek-v4-pro-beta',
+    addModelIdRequired: '请填写模型 ID。',
+    addModelIdDuplicate: '该模型已在列表中。',
+    addModelContextWindow: '上下文窗口',
+    addModelContextWindowHelp: '服务商模型页给出的最大 token 数。缺少它 Maka 只能按 32k 处理，长对话会被提前截断。',
+    addModelContextWindowRequired: '请填写上下文窗口。',
     credentials: '连接', dangerZone: '删除连接', deleteRowHelp: '此操作不可撤销。',
     credentialsHelp: '密钥只保存在本机。',
     credentialsHelpAccount: '登录令牌只保存在本机。',
@@ -205,6 +215,17 @@ const enCopy: ProviderSettingsCopy = {
     credentialUnknownDetail: 'Model credential status could not be refreshed, so the connection is not being mislabeled as signed out or unconfigured.',
     testConnection: 'Test connection',
     updateModels: 'Update model catalog', endpoint: 'Service URL',
+    addModel: 'Add model',
+    addModelConfirm: 'Add',
+    addModelIdField: 'Model ID',
+    addModelIdFieldHelp: 'Must match the provider exactly, including case.',
+    addModelIdPlaceholder: 'deepseek-v4-pro-beta',
+    addModelIdRequired: 'Enter a model ID.',
+    addModelIdDuplicate: 'This model is already in the list.',
+    addModelContextWindow: 'Context window',
+    addModelContextWindowHelp:
+      "The maximum token count from the provider's model page. Without it Maka can only assume 32k, and long conversations get truncated early.",
+    addModelContextWindowRequired: 'Enter a context window.',
     credentials: 'Connection', dangerZone: 'Delete connection', deleteRowHelp: 'This cannot be undone.',
     credentialsHelp: 'The key stays on this machine.',
     credentialsHelpAccount: 'The sign-in token stays on this machine.',

apps/desktop/src/renderer/settings/provider-add-model-dialog.tsx

@@ -0,0 +1,152 @@
+import { useState, type FormEvent } from 'react';
+import { Dialog, DialogHeader } from '@astryxdesign/core/Dialog';
+import { FormLayout } from '@astryxdesign/core/FormLayout';
+import { Layout, LayoutContent, LayoutFooter } from '@astryxdesign/core/Layout';
+import { Button, HStack, NumberInput, TextInput, useUiLocale } from '@maka/ui';
+import { getProviderSettingsCopy } from '../locales/settings-provider-copy';
+
+/**
+ * Introduce a model by exact id, for a provider whose catalog cannot grow on
+ * its own: without a model-list endpoint, refresh replays the array this build
+ * shipped, so a model the user's plan already serves has no other way in
+ * (#1584).
+ *
+ * Two fields. The id enters `enabledModelIds`, which is the authorization. The
+ * context window is the one fact nothing else can supply: an id Maka has never
+ * seen resolves no window, and the history budget falls back to a flat 32k
+ * (context-budget-policy.ts) — three percent of a 1M-token window.
+ *
+ * Everything else a user can declare is edited in the capability section below
+ * the model list, which shows a row for exactly the models Maka cannot
+ * describe — every model added here, the moment it is added.
+ */
+export function AddModelDialog(props: {
+  isOpen: boolean;
+  existingModelIds: readonly string[];
+  /** Another write is in flight; the store would drop this one on the floor. */
+  isSubmitDisabled?: boolean;
+  onOpenChange(open: boolean): void;
+  /** Resolves to whether the write landed; the draft is held until it did. */
+  onSubmit(id: string, contextWindow: number): Promise<boolean>;
+}) {
+  const copy = getProviderSettingsCopy(useUiLocale()).detail;
+  const [id, setId] = useState('');
+  const [contextWindow, setContextWindow] = useState<number | null>(null);
+  const [submitAttempted, setSubmitAttempted] = useState(false);
+  const [isSaving, setSaving] = useState(false);
+
+  const trimmedId = id.trim();
+  const idError = !trimmedId
+    ? copy.addModelIdRequired
+    : props.existingModelIds.includes(trimmedId)
+      ? copy.addModelIdDuplicate
+      : null;
+  // Required, not defaulted: an unknown window falls back to a flat 32k history
+  // budget, and guessing higher on the user's behalf would trade a wasted
+  // window for requests the provider rejects outright. Whoever types an exact
+  // model id is reading the provider's own model page, where this is stated.
+  const contextWindowError = contextWindow ? null : copy.addModelContextWindowRequired;
+
+  function close() {
+    setId('');
+    setContextWindow(null);
+    setSubmitAttempted(false);
+    props.onOpenChange(false);
+  }
+
+  // Closing on submit would clear the draft before the write settles, and an
+  // exact model id is not something a user can reproduce from memory. The
+  // failure is reported by the caller's toast; what this owes them is the
+  // typed text, still there to retry from.
+  async function submit(event: FormEvent) {
+    event.preventDefault();
+    setSubmitAttempted(true);
+    if (idError || !contextWindow || isSaving) return;
+    setSaving(true);
+    try {
+      if (await props.onSubmit(trimmedId, contextWindow)) close();
+    } finally {
+      setSaving(false);
+    }
+  }
+
+  return (
+    <Dialog
+      isOpen={props.isOpen}
+      onOpenChange={(open) => {
+        // A write in flight owns the draft until it settles: dismissing here
+        // would discard the very text the retry needs.
+        if (!open && !isSaving) close();
+      }}
+      purpose="form"
+      width={480}
+    >
+      <Layout
+        header={
+          <DialogHeader
+            title={copy.addModel}
+            onOpenChange={(open) => {
+              if (!open && !isSaving) close();
+            }}
+          />
+        }
+        content={
+          <LayoutContent>
+            <form id="maka-add-model-form" onSubmit={(event) => void submit(event)}>
+              <FormLayout>
+                {/* The exact id, kept verbatim through selection and inference
+                    — `deepseek-v4-pro-beta` is a different model from
+                    `deepseek-v4-pro`, and only the user knows which one their
+                    plan actually serves. */}
+                <TextInput
+                  label={copy.addModelIdField}
+                  description={copy.addModelIdFieldHelp}
+                  isRequired
+                  hasAutoFocus
+                  value={id}
+                  placeholder={copy.addModelIdPlaceholder}
+                  onChange={setId}
+                  status={
+                    submitAttempted && idError ? { type: 'error', message: idError } : undefined
+                  }
+                />
+                <NumberInput
+                  label={copy.addModelContextWindow}
+                  description={copy.addModelContextWindowHelp}
+                  isRequired
+                  value={contextWindow}
+                  hasClear
+                  isIntegerOnly
+                  min={1}
+                  onChange={setContextWindow}
+                  status={
+                    submitAttempted && contextWindowError
+                      ? { type: 'error', message: contextWindowError }
+                      : undefined
+                  }
+                />
+              </FormLayout>
+            </form>
+          </LayoutContent>
+        }
+        footer={
+          <LayoutFooter>
+            {/* One button, as in scheduled-task-form-dialog: the header's close
+                control and Escape are already two ways out, so a footer cancel
+                would be a third route to the same place. */}
+            <HStack gap={2} hAlign="end">
+              <Button
+                variant="primary"
+                type="submit"
+                form="maka-add-model-form"
+                isDisabled={props.isSubmitDisabled || isSaving}
+                isLoading={isSaving}
+                label={copy.addModelConfirm}
+              />
+            </HStack>
+          </LayoutFooter>
+        }
+      />
+    </Dialog>
+  );
+}

apps/desktop/src/renderer/settings/provider-connection-detail.tsx

@@ -12,6 +12,7 @@ import {
   VStack,
 } from '@astryxdesign/core';
 import { isRelayProviderType, PROVIDER_DEFAULTS } from '@maka/core/llm-connections';
+import { hasModelMetadata } from '@maka/core/model-metadata';
 import {
   DECLARABLE_RELAY_THINKING_LEVELS,
   THINKING_LEVELS,
@@ -33,6 +34,7 @@ import { PasswordInput } from './password-input';
 import { SettingsExpandableRow } from './settings-expandable-row';
 import { getProviderSettingsCopy } from '../locales/settings-provider-copy';
 import { providerDisplay } from './provider-display';
+import { AddModelDialog } from './provider-add-model-dialog';
 import { EnabledModelManager } from './provider-enabled-model-manager';
 import { useActionGuard } from './use-action-guard';
 import { useRuntimeHostSettingsTarget } from './runtime-host-settings-target.js';
@@ -149,6 +151,7 @@ function ConnectionDetailInner(props: ConnectionDetailProps) {
     savedBaseUrl,
     save,
     updateEnabledModels,
+    addDeclaredModel,
     relayProfileDraft,
     hasRelayProfileChanges,
     setDraftThinkingLevels,
@@ -161,22 +164,34 @@ function ConnectionDetailInner(props: ConnectionDetailProps) {
     remove,
     refreshAfterRelogin,
   } = useConnectionDetail(props);
-  // Capability switches only exist for custom OpenAI relays: built-in
-  // providers declare their thinking support in model metadata, a custom
-  // relay's backing model is unknown until the user says what it can do. The
-  // declaration is per model — a relay can front both a reasoner and a plain
-  // instruct model.
-  const showsCapabilities = isRelayProviderType(connection.providerType);
+  // A model gets capability switches when Maka cannot describe it otherwise.
+  // On a custom OpenAI relay that is every model: the id is whatever the
+  // operator chose, so even one that collides with a known name may front
+  // something else entirely. Elsewhere it is the models the bundled metadata
+  // has never heard of — a model newer than this build, or one the user typed
+  // in on a provider whose key cannot call a model-list endpoint, which no
+  // refresh will ever describe (#1584).
+  //
+  // A model that already carries a declaration always keeps its row, or a
+  // stale declaration would be uneditable and unclearable.
+  const isRelay = isRelayProviderType(connection.providerType);
   // Rows are the enabled models, exactly — the store prunes a model's profile
   // the moment it is disabled, so no declaration can ever belong to a row
   // this list does not show. The editor edits the per-model draft; 保存
   // commits the whole table in one write.
-  const capabilityModelIds = enabledModelIds;
+  const capabilityModelIds = enabledModelIds.filter(
+    (modelId) =>
+      isRelay ||
+      relayProfileDraft[modelId] !== undefined ||
+      !hasModelMetadata(connection.providerType, modelId),
+  );
+  const showsCapabilities = capabilityModelIds.length > 0;
   // One row is a form at a time, the way the settings-sidebar template does it.
   // Opening a row discards the other's draft: leaving an abandoned draft in
   // state meant it reappeared when the user came back to that row, and — until
   // `save` became per-field — rode along with the next save.
   const [editingRow, setEditingRow] = useState<'key' | 'endpoint' | 'headers' | 'body' | null>(null);
+  const [addModelOpen, setAddModelOpen] = useState(false);
   const [savedHeaderNames, setSavedHeaderNames] = useState<readonly string[]>([]);
   const [headerDrafts, setHeaderDrafts] = useState<RequestHeaderDraft[]>([]);
   const savedBodyText = formatRequestBodyOverlay(connection.requestBodyOverlay);
@@ -521,10 +536,31 @@ function ConnectionDetailInner(props: ConnectionDetailProps) {
             would pass a MouseEvent as `opts`. */}
         <HStack gap={2} vAlign="center" wrap="wrap">
           <Button variant="secondary" isDisabled={allActionsBusy || !hasUsableCredential} clickAction={() => runTest()} label={copy.testConnection} />
+          {/* Both, wherever refresh exists. Refresh is the fast path and stays
+              first, but having a model-list endpoint does not mean the endpoint
+              answers for this account: a self-hosted gateway on
+              `openai-compatible` may not serve /models at all, and a provider's
+              list can lag a model the account already has. Making the two
+              alternatives left those users with no way in (#1584). */}
           {supportsRemoteDiscovery && (
             <Button variant="ghost" isDisabled={allActionsBusy || !hasUsableCredential} clickAction={() => refreshModels()} label={copy.updateModels} />
           )}
+          <Button variant="ghost" isDisabled={allActionsBusy} clickAction={() => setAddModelOpen(true)} label={copy.addModel} />
         </HStack>
+        <AddModelDialog
+          isOpen={addModelOpen}
+          /* The catalog, not just the selection: `models` is usually a proper
+             superset of what the user enabled. Checking only the selection lets
+             a listed-but-unchecked id through, and the dialog then requires a
+             hand-typed context window that overrides the one Maka already
+             knows. */
+          existingModelIds={[...enabledModelIds, ...(connection.models ?? []).map(({ id }) => id)]}
+          /* A write started after the dialog opened would make the store drop
+             this submission silently, taking the typed id with it. */
+          isSubmitDisabled={allActionsBusy}
+          onOpenChange={setAddModelOpen}
+          onSubmit={addDeclaredModel}
+        />
       </DetailSection>
       )}
       {showsCapabilities && !retired && (
@@ -568,6 +604,12 @@ function ConnectionDetailInner(props: ConnectionDetailProps) {
                         left, one compact control on the right (the 模型功能
                         row language). A CheckboxList wall was the reason this
                         section looked like a form from a different app. */}
+                    {/* Relay-only, like 快速模式 below: a declared level encodes
+                        into `reasoning_effort`, a wire field only the
+                        OpenAI-compatible relays accept. The catalog codec
+                        refuses to persist one elsewhere, so offering the
+                        control would promise an edit that cannot be saved. */}
+                    {isRelay && (
                     <CapabilityRow label={copy.thinkingEffort} description={copy.thinkingEffortHelp}>
                       {/* DropdownMenu, not MultiSelector: levels have a
                           canonical order (low → max) that must not shuffle —
@@ -609,6 +651,7 @@ function ConnectionDetailInner(props: ConnectionDetailProps) {
                         ))}
                       </DropdownMenu>
                     </CapabilityRow>
+                    )}
                     <CapabilityRow label={copy.visionInput} description={copy.visionInputHelp}>
                       <Selector
                         label={`${copy.visionInput} — ${modelId}`}

apps/desktop/src/renderer/settings/use-connection-detail.ts

@@ -244,6 +244,7 @@ export function useConnectionDetail(props: ConnectionDetailProps) {
       slug: connection.slug,
       providerType: connection.providerType,
       defaultModel: connection.defaultModel,
+      enabledModelIds,
       models: modelSource === 'fetched' || models.length > 0 ? models : undefined,
       modelSource,
       modelsFetchedAt: connection.modelsFetchedAt,
@@ -484,6 +485,70 @@ export function useConnectionDetail(props: ConnectionDetailProps) {
     }
   }
 
+  /**
+   * Introduce a model the provider's catalog does not list.
+   *
+   * Only offered where refresh cannot help: a provider with no model-list
+   * endpoint replays the array this build shipped, so a model the user's plan
+   * serves but Maka has never heard of has no other way in (#1584).
+   *
+   * The id enters `enabledModelIds` — the same user-selection authority a
+   * catalogued model uses, so nothing here pretends the provider advertised
+   * it — and the context window enters `relayModelProfiles`, which is where a
+   * user states a fact no other source knows. Both go in ONE write: the store
+   * requires every declaration to key an enabled model, so a table written
+   * ahead of its id would be rejected.
+   *
+   * The saved table is the base, not the unsaved draft: adding a model must
+   * not silently commit edits the user has open in the capability section.
+   * The draft is then caught up by hand, because a dirty draft deliberately
+   * does not reseed from props — see `relayProfileDraftReseedPlan`.
+   */
+  async function addDeclaredModel(id: string, contextWindow: number): Promise<boolean> {
+    const modelId = id.trim();
+    if (!modelId || enabledModelIds.includes(modelId)) return false;
+    if (connectionDetailActionGuard.has('save-enabled-models') || detailActionBusy) return false;
+    const next = [...enabledModelIds, modelId];
+    const previous = enabledModelIds;
+    const lifecycle = connectionDetailLifecycleRef.current;
+    const releaseSaveModels = connectionDetailActionGuard.begin('save-enabled-models');
+    if (!releaseSaveModels) return false;
+    setSavingEnabledModels(true);
+    setEnabledModelIds(next);
+    let saved = false;
+    try {
+      await props.bridge.update(connection.slug, {
+        enabledModelIds: next,
+        relayModelProfiles: { ...(savedRelayProfiles ?? {}), [modelId]: { contextWindow } },
+      });
+      saved = true;
+      if (!isConnectionDetailCurrent(lifecycle)) return saved;
+      // The editor's draft is a second copy of this table, and while it is
+      // dirty it does not reseed from props — that is what keeps an unrelated
+      // reload from discarding typed work. So the declaration just written has
+      // to be merged in here. Without it the draft is a table that no longer
+      // contains this model, the capability-save button lights up on that
+      // difference, and its whole-table replace drops the context window the
+      // user just declared — silently, back to the unknown-model default.
+      setRelayProfileDrafts((current) => ({ ...current, [modelId]: { contextWindow } }));
+      await props.onChanged();
+    } catch (error) {
+      if (!isConnectionDetailCurrent(lifecycle)) return saved;
+      if (!saved) setEnabledModelIds(previous);
+      toast.error(
+        saved ? copy.refreshFailed : copy.saveModelsFailed,
+        providerPanelActionErrorMessage(error, locale),
+      );
+    } finally {
+      releaseSaveModels();
+      if (isConnectionDetailCurrent(lifecycle)) setSavingEnabledModels(false);
+    }
+    // Whether the write landed. The dialog holds the typed id and context
+    // window until it did: a rejected write leaves nothing to retype from, and
+    // an exact model id is not something a user can reproduce from memory.
+    return saved;
+  }
+
   async function runTest() {
     const releaseTest = connectionDetailActionGuard.beginExclusive('test');
     if (!releaseTest) return;
@@ -653,6 +718,7 @@ export function useConnectionDetail(props: ConnectionDetailProps) {
     lastTestAtMs,
     save,
     updateEnabledModels,
+    addDeclaredModel,
     relayProfileDraft: relayProfileDrafts,
     relayProfilesDirty,
     hasRelayProfileChanges,