diff --git a/docs/public-site-operations.md b/docs/public-site-operations.md index bcfe8fcd..c70b8603 100644 --- a/docs/public-site-operations.md +++ b/docs/public-site-operations.md @@ -29,18 +29,23 @@ must not influence Agent rank, compatibility conclusions, default selection, or tests. That boundary belongs to this repository; the site only displays the result. **Those fields are not read by the application, and that is enforced by omission.** -`relationship`, `disclosure`, `referral_url`, `order`, and `protocols` have no counterpart -in `providerFileEntry` (`internal/catalog/providers.go`), so `json.Unmarshal` discards -them. Filling in `referral_url` therefore changes nothing in the desktop app or the CLI — -it is published for the site to render, and the "get a key" button will keep opening -`key_management_url` (falling back to `home`) regardless. Routing users through a referral -link would be a product decision requiring the field to be parsed and given an explicit -precedence, not a matter of setting a value here. - -The reverse also holds: `key_management_url` and `default_model` are read by the app. They -are not disclosure fields and are not subject to the paragraph above; `default_model` is -the model pre-filled for a user who has not chosen one, so changing it changes what gets -written into a real Agent configuration. +`relationship`, `disclosure`, and `referral_url` have no counterpart in `providerFileEntry` +(`internal/catalog/providers.go`), so `json.Unmarshal` discards them. Filling in +`referral_url` therefore changes nothing in the desktop app or the CLI — it is published +for the site to render, and the "get a key" button will keep opening `key_management_url` +(falling back to `home`) regardless. Routing users through a referral link would be a +product decision requiring the field to be parsed and given an explicit precedence, not a +matter of setting a value here. + +The reverse also holds: `key_management_url`, `default_model`, `order`, and `protocols` are +read by the app. They are not disclosure fields and are not subject to the paragraph above; +`default_model` is the model pre-filled for a user who has not chosen one, so changing it +changes what gets written into a real Agent configuration. `order` is the display order of +the built-in Providers. `protocols` records how far each protocol has been confirmed on a +Provider's endpoint: when the protocol an Agent needs is anything other than +`implementation-supported` while `openai` is, the setup wizard offers compatibility mode +before any request is sent. It only ever adds that optional hint; it never hides a Provider, +and connection tests still decide what actually works. **Changing a lock file does not change the site.** The site vendors `agents.lock.json` and `providers.lock.json` into its own `data/` directory, refreshed from release tags diff --git a/frontend/bindings/github.com/MaimoryLab/BootAgent/internal/catalog/models.ts b/frontend/bindings/github.com/MaimoryLab/BootAgent/internal/catalog/models.ts index 84ab6bb5..31eb5434 100644 --- a/frontend/bindings/github.com/MaimoryLab/BootAgent/internal/catalog/models.ts +++ b/frontend/bindings/github.com/MaimoryLab/BootAgent/internal/catalog/models.ts @@ -122,6 +122,13 @@ export interface Provider { * custom Provider, which the frontend sorts by creation time instead. */ "order"?: number; + + /** + * Protocol ID -> confirmed support level on a built-in Provider's endpoint, + * from providers.lock.json. Absent for a custom Provider, whose endpoint + * nothing is known about. + */ + "protocols"?: { [_ in string]?: string } | null; "custom"?: boolean; "has_key"?: boolean; "created_at"?: string; diff --git a/frontend/e2e/wails.spec.ts b/frontend/e2e/wails.spec.ts index e43af2dc..8038e378 100644 --- a/frontend/e2e/wails.spec.ts +++ b/frontend/e2e/wails.spec.ts @@ -80,6 +80,36 @@ test("a machine with no BootAgent state opens onboarding from the landing route" await expect(page.getByRole("heading", { name: "选择 Agent", level: 1 })).toBeVisible(); }); +// A first-time user is not required to test the connection, so the step itself +// has to say when the Agent's format is unconfirmed on the chosen service. This +// runs against the real status binding: the protocol table comes from +// providers.lock.json through Go, which a unit-test fixture cannot show. +test("the Provider step suggests compatibility mode without a connection test", async ({ page }) => { + await page.goto("/#/"); + await expect(page.getByRole("heading", { name: "选择 Agent", level: 1 })).toBeVisible(); + await page.getByRole("tab", { name: "命令行 Agent" }).click(); + await page.getByLabel("选择 Codex").check(); + await page.getByRole("button", { name: "继续" }).click(); + + await expect(page.getByRole("heading", { name: "连接模型服务" })).toBeVisible(); + // JieKou.AI ships first and has not confirmed OpenAI Responses. + await expect(page.getByRole("combobox", { name: "模型服务" })).toHaveText("JieKou.AI"); + const suggestion = page.getByText("尚未确认 JieKou.AI 支持 Codex 的请求格式(OpenAI Responses),可以改用兼容模式,由 BootAgent 在本机转换"); + await expect(suggestion).toBeVisible(); + + await page.getByRole("button", { name: "使用兼容模式" }).click(); + await expect(page.getByText("已选择兼容模式,使用 Codex 时需要保持 BootAgent 运行")).toBeVisible(); + await page.getByRole("button", { name: "不用兼容模式" }).click(); + await expect(suggestion).toBeVisible(); + + // DeepSeek has confirmed it, so there is nothing to suggest. + await page.getByRole("combobox", { name: "模型服务" }).click(); + await page.getByRole("option", { name: "DeepSeek" }).click(); + await expect(page.getByRole("combobox", { name: "模型服务" })).toHaveText("DeepSeek"); + await expect(page.getByText(/尚未确认/)).toHaveCount(0); + await expect(page.getByRole("button", { name: "使用兼容模式" })).toHaveCount(0); +}); + test("onboarding installs one Agent end to end and writes its Profile", async ({ page }) => { const bindingMethodIDs = new Set(); page.on("request", (request) => { diff --git a/frontend/src/i18n.tsx b/frontend/src/i18n.tsx index 3fa916b1..c78c0fc9 100644 --- a/frontend/src/i18n.tsx +++ b/frontend/src/i18n.tsx @@ -1029,6 +1029,7 @@ const english = { "Claude Code 看到的模型名": "Model name Claude Code sees", "Codex 看到的模型名": "Model name Codex sees", "{agents} 已改用兼容模式": "{agents} now use compatibility mode", + "尚未确认 {provider} 支持 {agent} 的请求格式({protocol}),可以改用兼容模式,由 BootAgent 在本机转换": "{provider} isn't confirmed to support {agent}'s request format ({protocol}); compatibility mode lets BootAgent convert it on this computer", "{agent} 不能直接使用这个模型服务,BootAgent 可以在本机转换后使用": "{agent} can't use this model service directly, but BootAgent can convert its requests on this computer", "{agent} 不能直接使用这个模型服务,应用时会开启兼容模式在本机转换,使用期间需要保持 BootAgent 运行": "{agent} can't use this model service directly, so applying turns on compatibility mode, which needs BootAgent to keep running", "{agent} 不能直接使用这个配置模版,应用时会开启兼容模式在本机转换,使用期间需要保持 BootAgent 运行": "{agent} can't use this profile directly, so applying turns on compatibility mode, which needs BootAgent to keep running", diff --git a/frontend/src/pages/ProviderKeyPage.test.tsx b/frontend/src/pages/ProviderKeyPage.test.tsx index 18ceb530..20aa13a4 100644 --- a/frontend/src/pages/ProviderKeyPage.test.tsx +++ b/frontend/src/pages/ProviderKeyPage.test.tsx @@ -1,5 +1,5 @@ import { fireEvent, render, screen, waitFor } from "@testing-library/react"; -import { MemoryRouter } from "react-router-dom"; +import { MemoryRouter, Route, Routes } from "react-router-dom"; import { afterEach, describe, expect, it, vi } from "vitest"; import { api } from "../backend/api"; @@ -29,6 +29,28 @@ const status = { catalog: [], } as unknown as StatusResponse; +// Built-in Providers as the protocol table describes them: Chat Completions is +// confirmed on both, OpenAI Responses (what Codex speaks) only on the second. +const tabledStatus = { + providers: { + jiekou: { + name: "JieKou.AI", home: "", base_url: "https://api.jiekou.test/openai", has_key: true, + protocols: { openai: "implementation-supported", anthropic: "implementation-supported", responses: "route-present-unverified" }, + }, + deepseek: { + name: "DeepSeek", home: "", base_url: "https://api.deepseek.test", has_key: true, + protocols: { openai: "implementation-supported", anthropic: "implementation-supported", responses: "implementation-supported" }, + }, + }, + catalog: [{ id: "codex", name: "Codex", protocol: "responses", configMode: "auto", selectsModel: true }], +} as unknown as StatusResponse; + +const codexOn = (provider: string, patch: Partial = {}): WizardState => ({ + ...initialWizardState, status: tabledStatus, statusState: "success", setupKind: "cli", selectedAgentIds: ["codex"], provider, ...patch, +}); + +const SUGGESTION = "尚未确认 JieKou.AI 支持 Codex 的请求格式(OpenAI Responses),可以改用兼容模式,由 BootAgent 在本机转换"; + /** Pins the selected Provider to the one this fixture defines. Inheriting the * wizard's initial Provider instead coupled these cases to whichever Provider * ships first in providers.lock.json: when that changed, every case here looked @@ -100,6 +122,149 @@ describe("ProviderKeyPage", () => { expect(screen.getByRole("button", { name: "继续选择模型" })).toBeEnabled(); }); + // The connection test is optional, so a first-time user who skipped it got no + // word about compatibility mode and installed a Codex that failed on its first + // request. The protocol table answers the same question without a request. + it("suggests compatibility mode from the protocol table, without a connection test", () => { + state = codexOn("jiekou"); + keyRef.current = ""; + const probe = vi.spyOn(api, "probe"); + const models = vi.spyOn(api, "models").mockResolvedValue({ ok: true, reachable: true, status: 200, message: "", error_code: null, retryable: false, models: [] }); + const page = render(); + + expect(screen.getByText(SUGGESTION)).toBeTruthy(); + // "Not confirmed" is all the table can say; it has not shown a failure. + expect(screen.queryByText(/不能直接使用/)).toBeNull(); + expect(screen.queryByRole("alert")).toBeNull(); + + fireEvent.click(screen.getByRole("button", { name: "使用兼容模式" })); + page.rerender(); + expect(state.conversion).toBe(true); + expect(screen.getByText("已选择兼容模式,使用 Codex 时需要保持 BootAgent 运行")).toBeTruthy(); + expect(screen.queryByText(SUGGESTION)).toBeNull(); + expect(screen.getByRole("button", { name: "继续选择模型" })).toBeEnabled(); + + // Billed requests start from a button the user pressed, never from a guess. + expect(probe).not.toHaveBeenCalled(); + // Listing models is the page's existing unbilled lookup, not a probe. + expect(models.mock.calls.length).toBeLessThanOrEqual(1); + }); + + it("lets the user continue without taking the untested suggestion", async () => { + state = codexOn("jiekou"); + keyRef.current = ""; + const probe = vi.spyOn(api, "probe"); + vi.spyOn(api, "models").mockResolvedValue({ ok: true, reachable: true, status: 200, message: "", error_code: null, retryable: false, models: [] }); + render( + + + } /> + model step} /> + + , + ); + + expect(screen.getByText(SUGGESTION)).toBeTruthy(); + const next = screen.getByRole("button", { name: "继续选择模型" }); + expect(next).toBeEnabled(); + fireEvent.click(next); + + expect(await screen.findByRole("heading", { name: "model step" })).toBeTruthy(); + expect(state.conversion).toBe(false); + expect(probe).not.toHaveBeenCalled(); + }); + + it("makes no suggestion when the Provider has confirmed the Agent's format", () => { + state = codexOn("deepseek"); + keyRef.current = ""; + vi.spyOn(api, "models").mockResolvedValue({ ok: true, reachable: true, status: 200, message: "", error_code: null, retryable: false, models: [] }); + render(); + + expect(screen.queryByText(/尚未确认/)).toBeNull(); + expect(screen.queryByRole("button", { name: "使用兼容模式" })).toBeNull(); + expect(screen.getByRole("button", { name: "继续选择模型" })).toBeEnabled(); + }); + + it("makes no suggestion for a custom Provider, which has no protocol table", () => { + const custom = { + ...tabledStatus, + providers: { mine: { name: "Mine", home: "", base_url: "https://api.mine.test/v1", has_key: true, custom: true } }, + } as unknown as StatusResponse; + state = codexOn("mine", { status: custom }); + keyRef.current = ""; + vi.spyOn(api, "models").mockResolvedValue({ ok: true, reachable: true, status: 200, message: "", error_code: null, retryable: false, models: [] }); + render(); + + expect(screen.queryByText(/尚未确认/)).toBeNull(); + expect(screen.queryByRole("button", { name: "使用兼容模式" })).toBeNull(); + }); + + // Only the untested suggestion is optional. Once a test has shown the Agent's + // format failing while Chat Completions works, the choice is required again. + it("requires the choice once a connection test has actually failed", async () => { + state = codexOn("jiekou"); + keyRef.current = ""; + vi.spyOn(api, "models").mockResolvedValue({ ok: true, reachable: true, status: 200, message: "", error_code: null, retryable: false, models: [] }); + vi.spyOn(api, "probe").mockResolvedValue({ + ok: false, reachable: true, status: 404, message: "Model does not support OpenAI Responses.", + error_code: "PROTOCOL_UNSUPPORTED", retryable: false, convertible: ["responses"], + }); + const page = render(); + expect(screen.getByRole("button", { name: "继续选择模型" })).toBeEnabled(); + + fireEvent.click(screen.getByRole("button", { name: "测试连接" })); + await waitFor(() => expect(state.connectionState).toBe("error")); + page.rerender(); + + expect(screen.queryByText(SUGGESTION)).toBeNull(); + expect(screen.getByRole("alert")).toHaveTextContent("Codex 不能直接使用这个模型服务,BootAgent 可以在本机转换后使用"); + expect(screen.getAllByRole("button", { name: "使用兼容模式" })).toHaveLength(1); + expect(screen.getByRole("button", { name: "继续选择模型" })).toBeDisabled(); + }); + + it("drops the suggestion once a connection test passes", async () => { + state = codexOn("jiekou"); + keyRef.current = ""; + vi.spyOn(api, "models").mockResolvedValue({ ok: true, reachable: true, status: 200, message: "", error_code: null, retryable: false, models: [] }); + vi.spyOn(api, "probe").mockResolvedValue({ ok: true, reachable: true, status: 200, message: "ok", error_code: null, retryable: false }); + const page = render(); + + fireEvent.click(screen.getByRole("button", { name: "测试连接" })); + await waitFor(() => expect(state.connectionState).toBe("success")); + page.rerender(); + + expect(screen.queryByText(SUGGESTION)).toBeNull(); + expect(screen.queryByRole("button", { name: "使用兼容模式" })).toBeNull(); + }); + + // A first-time user has no key saved, so the key is typed on this same step + // and cleared again when Continue saves it. Both used to reset the choice. + it("keeps an untested choice while the key is typed and saved", async () => { + const noKey = { + ...tabledStatus, + providers: { jiekou: { ...tabledStatus.providers.jiekou, has_key: false } }, + } as unknown as StatusResponse; + state = codexOn("jiekou", { status: noKey }); + keyRef.current = ""; + const save = vi.spyOn(api, "saveProvider").mockResolvedValue({ + entry: { id: "jiekou", name: "JieKou.AI", home: "", base_url: "https://api.jiekou.test/openai", anthropic_base_url: "", api_key: "", built_in: true }, + reapplied: [], + failures: {}, + }); + const page = render(); + + fireEvent.click(screen.getByRole("button", { name: "使用兼容模式" })); + page.rerender(); + fireEvent.change(screen.getByLabelText("API Key"), { target: { value: "new-key" } }); + page.rerender(); + expect(state.conversion).toBe(true); + + fireEvent.click(screen.getByRole("button", { name: "继续选择模型" })); + await waitFor(() => expect(save).toHaveBeenCalledWith(expect.objectContaining({ id: "jiekou", api_key: "new-key" }))); + await waitFor(() => expect(keyRef.current).toBe("")); + expect(state.conversion).toBe(true); + }); + it("uses a custom model name for the connection test", async () => { state = { ...baseState, status, statusState: "success", hasApiKey: false }; keyRef.current = "test-key"; diff --git a/frontend/src/pages/ProviderKeyPage.tsx b/frontend/src/pages/ProviderKeyPage.tsx index f4587127..ab5f02ae 100644 --- a/frontend/src/pages/ProviderKeyPage.tsx +++ b/frontend/src/pages/ProviderKeyPage.tsx @@ -10,7 +10,7 @@ import { ProviderSegment } from "../components/ProviderSegment"; import { SecureKeyField } from "../components/SecureKeyField"; import { useI18n } from "../i18n"; import { useFeedback } from "../state/FeedbackContext"; -import { probeOffersConversion } from "../state/conversion"; +import { probeOffersConversion, providerSuggestsConversion } from "../state/conversion"; import { desktopProtocol, profileAgentIdForDesktop, selectedDesktopApp } from "../state/desktopSetup"; import { useWizard } from "../state/WizardContext"; import { wizardNeedsModel } from "../state/wizardReducer"; @@ -51,10 +51,14 @@ export function ProviderKeyPage() { // Other desktop apps share another Agent's settings and stay as they are. const conversionProtocol = protocols.length === 1 && (!desktop || desktop.id === "claude-desktop") ? protocols[0] : undefined; const conversionOffered = state.connectionState === "error" && probeOffersConversion(state.connection, conversionProtocol); + // Read from the Provider's protocol table, with no request sent. It speaks + // only until a connection test has: a test's verdict replaces the guess. + const conversionSuggested = state.connectionState === "idle" && providerSuggestsConversion(providerMeta, conversionProtocol); const agentName = desktop?.name || state.status?.catalog.find((item) => item.id === state.selectedAgentIds[0])?.name || ""; // A new key is persisted before continuing; probing remains optional. A test // that found compatibility mode would help is the exception: continuing past - // it unanswered installs an Agent that fails on its first request. + // it unanswered installs an Agent that fails on its first request. The + // untested suggestion is not: nothing has shown the Provider cannot serve it. const canContinue = (canProbe || (builtInProvider && state.hasApiKey)) && (!conversionOffered || state.conversion); const endpoint = useMemo(() => { @@ -213,6 +217,23 @@ export function ProviderKeyPage() { beside the one choice that fixes it. */} {conversionOffered ? null : } + {conversionSuggested && !state.conversion ? ( +
+ + {t("尚未确认 {provider} 支持 {agent} 的请求格式({protocol}),可以改用兼容模式,由 BootAgent 在本机转换", { + provider: providerMeta?.name ?? "", + agent: agentName, + protocol: conversionProtocol ? PROTOCOL_LABELS[conversionProtocol] : "", + })} + +
+ +
+
+ ) : null} {conversionOffered && !state.conversion ? (
{t("{agent} 不能直接使用这个模型服务,BootAgent 可以在本机转换后使用", { agent: agentName })} diff --git a/frontend/src/state/conversion.test.ts b/frontend/src/state/conversion.test.ts index 931705f5..ed0af9ca 100644 --- a/frontend/src/state/conversion.test.ts +++ b/frontend/src/state/conversion.test.ts @@ -1,8 +1,12 @@ +import { readFileSync } from "node:fs"; +import { dirname, join } from "node:path"; +import { fileURLToPath } from "node:url"; + import { describe, expect, it } from "vitest"; import { sourceTranslate, translate } from "../i18n"; import type { ProbeResponse, StatusResponse } from "../types/api"; -import { agentsUsingConversion, conversionDisplay, converterProfileName, probeOffersConversion, userProviders } from "./conversion"; +import { agentsUsingConversion, conversionDisplay, converterProfileName, probeOffersConversion, providerSuggestsConversion, userProviders } from "./conversion"; describe("converterProfileName", () => { it("names every generated adapter Profile by the Agent that uses it", () => { @@ -41,6 +45,59 @@ describe("probeOffersConversion", () => { }); }); +describe("providerSuggestsConversion", () => { + type Provider = StatusResponse["providers"][string]; + const provider = (protocols: Provider["protocols"]): Provider => ({ name: "P", home: "", base_url: "https://api.example.test", protocols }); + const confirmed = "implementation-supported"; + + it("suggests it when the Agent's format is unconfirmed but Chat Completions is confirmed", () => { + for (const level of ["route-present-unverified", "release-candidate-required", "not-supported"] as const) { + expect(providerSuggestsConversion(provider({ openai: confirmed, responses: level }), "responses")).toBe(true); + expect(providerSuggestsConversion(provider({ openai: confirmed, anthropic: level }), "anthropic")).toBe(true); + } + // A protocol the table does not mention has not been confirmed either. + expect(providerSuggestsConversion(provider({ openai: confirmed }), "responses")).toBe(true); + }); + + it("stays quiet when the Agent's format is confirmed", () => { + expect(providerSuggestsConversion(provider({ openai: confirmed, responses: confirmed }), "responses")).toBe(false); + expect(providerSuggestsConversion(provider({ openai: confirmed, anthropic: confirmed }), "anthropic")).toBe(false); + }); + + it("stays quiet when Chat Completions, which it converts to, is not confirmed", () => { + expect(providerSuggestsConversion(provider({ openai: "route-present-unverified", responses: "route-present-unverified" }), "responses")).toBe(false); + }); + + it("stays quiet for an Agent that already speaks Chat Completions", () => { + expect(providerSuggestsConversion(provider({ openai: confirmed }), "openai")).toBe(false); + expect(providerSuggestsConversion(provider({ openai: confirmed }), undefined)).toBe(false); + }); + + it("stays quiet for a Provider with no table, such as a custom one", () => { + expect(providerSuggestsConversion(provider(undefined), "responses")).toBe(false); + expect(providerSuggestsConversion(provider(null), "responses")).toBe(false); + expect(providerSuggestsConversion(undefined, "responses")).toBe(false); + }); + + // The fixtures above are invented. This reads the table that ships, so the + // pairing a first-time user actually meets is what is asserted: the default + // Provider with Codex gets the suggestion, a Provider that has confirmed + // Responses does not. + it("agrees with the shipped protocol table", () => { + const manifestPath = join(dirname(fileURLToPath(import.meta.url)), "../../../manifests/providers.lock.json"); + const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as { providers: Record }; + const suggested = (id: string, protocol: string) => providerSuggestsConversion(manifest.providers[id], protocol); + const first = Object.entries(manifest.providers).sort(([, a], [, b]) => a.order - b.order)[0][0]; + + expect(first).toBe("jiekou"); + expect(suggested("jiekou", "responses")).toBe(true); + expect(suggested("deepseek", "responses")).toBe(false); + // Claude Code's format is confirmed on both, so neither gets a suggestion. + expect(suggested("jiekou", "anthropic")).toBe(false); + expect(suggested("deepseek", "anthropic")).toBe(false); + }); +}); + describe("compatibility mode status helpers", () => { const ppio = { id: "ppio-chat", label: "PPIO Chat", provider: "ppio", model: "deepseek-v3", protocol: "openai" }; const other = { id: "other-chat", label: "Other Chat", provider: "other", model: "glm-5", protocol: "openai" }; diff --git a/frontend/src/state/conversion.ts b/frontend/src/state/conversion.ts index ab693f4e..65c38acc 100644 --- a/frontend/src/state/conversion.ts +++ b/frontend/src/state/conversion.ts @@ -58,6 +58,18 @@ export function probeOffersConversion(result: ProbeResponse | null, protocol: st return Boolean(result && !result.ok && canConvertProtocol(protocol) && result.convertible?.includes(protocol)); } +/** + * Whether a built-in Provider's protocol table says, before any request is + * sent, that `protocol` is not confirmed there while Chat Completions is: the + * case compatibility mode exists for. Unconfirmed is not unsupported, so this + * is a suggestion and never a verdict. A custom Provider has no table. + */ +export function providerSuggestsConversion(provider: StatusResponse["providers"][string] | undefined, protocol: string | null | undefined): boolean { + const support = provider?.protocols; + if (!support || !canConvertProtocol(protocol)) return false; + return support.openai === "implementation-supported" && support[protocol] !== "implementation-supported"; +} + /** * A Provider's name as the user should read it. The adapter's own Providers * carry internal names ("BootAgent Converter anthropic"); an Agent pointed at diff --git a/frontend/src/state/wizardReducer.test.ts b/frontend/src/state/wizardReducer.test.ts index 4e667a9f..88688b2d 100644 --- a/frontend/src/state/wizardReducer.test.ts +++ b/frontend/src/state/wizardReducer.test.ts @@ -398,14 +398,43 @@ describe("provider default model", () => { }); describe("compatibility mode choice", () => { - const chosen = { ...initialWizardState, provider: "ppio", selectedAgentIds: ["codex"], conversion: true, keyVerified: true }; + // Made after a connection test failed and found Chat Completions working. + const chosen = { ...initialWizardState, provider: "ppio", selectedAgentIds: ["codex"], connectionState: "error" as const, conversion: true, keyVerified: true }; + // Made from the Provider's protocol table, with no test run. + const untested = { ...initialWizardState, provider: "ppio", selectedAgentIds: ["codex"], conversion: true }; it("counts as a verified key, since Chat Completions answered with it", () => { - const next = wizardReducer({ ...initialWizardState, keyVerified: false }, { type: "SET_CONVERSION", value: true }); + const next = wizardReducer({ ...initialWizardState, connectionState: "error", keyVerified: false }, { type: "SET_CONVERSION", value: true }); expect(next.conversion).toBe(true); expect(next.keyVerified).toBe(true); }); + it("does not count as a verified key when no test backs it", () => { + const next = wizardReducer({ ...initialWizardState, keyVerified: false }, { type: "SET_CONVERSION", value: true }); + expect(next.conversion).toBe(true); + expect(next.keyVerified).toBe(false); + }); + + // Typing the key and picking a test model happen on the same step as the + // choice, and the key is cleared again when Continue saves it. None of them + // contradicts a choice that no test verdict produced. + it.each([ + { type: "SET_PROBE_MODEL", value: "other-model" }, + { type: "SET_HAS_API_KEY", value: true }, + { type: "SET_HAS_API_KEY", value: false }, + ])("survives $type when it was made without a test", (action) => { + expect(wizardReducer(untested, action).conversion).toBe(true); + }); + + it.each([ + { type: "SET_PROVIDER", value: "jiekou" }, + { type: "SELECT_AGENT", agentId: "claude-code" }, + { type: "START_NEW_PROFILE" }, + { type: "CONNECTION_LOADING" }, + ])("is cleared by $type even when it was made without a test", (action) => { + expect(wizardReducer(untested, action).conversion).toBe(false); + }); + it.each([ { type: "SET_PROVIDER", value: "jiekou" }, { type: "SET_PROBE_MODEL", value: "other-model" }, diff --git a/frontend/src/state/wizardReducer.ts b/frontend/src/state/wizardReducer.ts index e0de10cb..36c347ec 100644 --- a/frontend/src/state/wizardReducer.ts +++ b/frontend/src/state/wizardReducer.ts @@ -179,6 +179,15 @@ function appendActivationOutput(log: string, output: InstallOutput): string { return `${log}${output.kind === "command" && log && !log.endsWith("\n") ? "\n" : ""}${text}`; } +/** + * A compatibility mode choice made from the Provider's protocol table, before + * any connection test. It rests on no test verdict, so the edits that discard a + * verdict leave it standing; one made after a failed test is discarded with it. + */ +function untestedConversion(state: WizardState): boolean { + return state.conversion && state.connectionState === "idle"; +} + export function wizardReducer(state: WizardState, action: WizardAction): WizardState { switch (action.type) { case "STATUS_LOADING": @@ -320,12 +329,13 @@ export function wizardReducer(state: WizardState, action: WizardAction): WizardS connection: null, connectionState: "idle", keyVerified: false, - conversion: false, + conversion: untestedConversion(state), }; case "SET_CONVERSION": - // Accepting rests on a test in which Chat Completions answered with this - // key, which is as much proof of the key as a native success. - return { ...state, conversion: action.value, keyVerified: state.keyVerified || action.value }; + // Accepting after a failed test rests on Chat Completions having answered + // with this key, which is as much proof of the key as a native success. + // Accepting the untested suggestion proves nothing about the key. + return { ...state, conversion: action.value, keyVerified: state.keyVerified || (action.value && state.connectionState === "error") }; case "SET_HAS_API_KEY": // Any edit of the key invalidates the previous probe verdict. The reducer // only sees the non-empty boolean (the secret itself stays in a ref), so @@ -337,7 +347,10 @@ export function wizardReducer(state: WizardState, action: WizardAction): WizardS connection: null, connectionState: "idle", keyVerified: false, - conversion: false, + // Typing the key, and clearing it once it is saved on Continue, both + // land here: dropping an untested choice would install the Agent + // without the compatibility mode the user had just picked. + conversion: untestedConversion(state), }; case "CONNECTION_LOADING": return { ...state, connectionState: "loading", connection: null, conversion: false }; diff --git a/frontend/src/types/api.ts b/frontend/src/types/api.ts index 0c8921f8..ad4429b4 100644 --- a/frontend/src/types/api.ts +++ b/frontend/src/types/api.ts @@ -31,6 +31,14 @@ export type TransferV2Preview = TransferModels.Preview; export type MarketplaceDynamicResult = AppModels.MarketplaceDynamicResult; export type MarketplaceSourceStatus = AppModels.MarketplaceSourceStatus; +/** How far a protocol has been confirmed on a built-in Provider's endpoint, as + * providers.lock.json records it. Only the first means it was verified. */ +export type ProtocolSupport = "implementation-supported" | "route-present-unverified" | "release-candidate-required" | "not-supported"; +export type ProviderMeta = Omit & { + /** Absent for a custom Provider, whose endpoint nothing is known about. */ + protocols?: Partial> | null; +}; + export const PROTOCOL_LABELS: Record = { openai: "OpenAI Chat Completions", anthropic: "Anthropic Messages", @@ -172,7 +180,7 @@ export type StatusResponse = Omit< agents: Record; catalog: AgentCatalogItem[]; groups: Array & { id: AgentGroupId }>; - providers: Record; + providers: Record; mirrors: CatalogModels.Mirror[]; paths: Record; backups: Record; diff --git a/internal/app/testdata/status-empty-linux-arm64.json b/internal/app/testdata/status-empty-linux-arm64.json index efe67345..1343dcb1 100644 --- a/internal/app/testdata/status-empty-linux-arm64.json +++ b/internal/app/testdata/status-empty-linux-arm64.json @@ -431,7 +431,12 @@ "base_url": "https://api.deepseek.com", "anthropic_base_url": "https://api.deepseek.com/anthropic", "default_model": "deepseek-v4-pro", - "order": 4 + "order": 4, + "protocols": { + "anthropic": "implementation-supported", + "openai": "implementation-supported", + "responses": "implementation-supported" + } }, "jiekou": { "name": "JieKou.AI", @@ -440,7 +445,12 @@ "base_url": "https://api.highwayapi.ai/openai", "anthropic_base_url": "https://api.highwayapi.ai/anthropic", "default_model": "claude-sonnet-5", - "order": 1 + "order": 1, + "protocols": { + "anthropic": "implementation-supported", + "openai": "implementation-supported", + "responses": "route-present-unverified" + } }, "moonshot": { "name": "Moonshot", @@ -448,7 +458,12 @@ "key_management_url": "https://platform.moonshot.cn/console/api-keys", "base_url": "https://api.moonshot.cn", "default_model": "kimi-k2-0905-preview", - "order": 5 + "order": 5, + "protocols": { + "anthropic": "not-supported", + "openai": "route-present-unverified", + "responses": "route-present-unverified" + } }, "novita": { "name": "Novita", @@ -457,7 +472,12 @@ "base_url": "https://api.novita.ai/openai", "anthropic_base_url": "https://api.novita.ai/anthropic", "default_model": "deepseek/deepseek-v4-pro", - "order": 3 + "order": 3, + "protocols": { + "anthropic": "implementation-supported", + "openai": "implementation-supported", + "responses": "release-candidate-required" + } }, "ppio": { "name": "PPIO", @@ -466,7 +486,12 @@ "base_url": "https://api.ppio.com/openai", "anthropic_base_url": "https://api.ppio.com/anthropic", "default_model": "deepseek/deepseek-v4-pro", - "order": 2 + "order": 2, + "protocols": { + "anthropic": "implementation-supported", + "openai": "implementation-supported", + "responses": "release-candidate-required" + } } }, "mirrors": [ diff --git a/internal/catalog/catalog_test.go b/internal/catalog/catalog_test.go index df67bdc6..cba412e1 100644 --- a/internal/catalog/catalog_test.go +++ b/internal/catalog/catalog_test.go @@ -347,17 +347,17 @@ func TestParseProvidersRejectsInvalidEntries(t *testing.T) { // at the call site: someone adding a field would not know it was load-bearing. // This pins it, so wiring one up has to be a deliberate edit here too. // The site's explorer reads fields the desktop app has no business showing: -// sponsorship, referral links, and per-protocol support claims are editorial, and -// projecting them would put a vendor relationship in front of a user choosing an -// endpoint. `order` is deliberately not in that set -- it is display precedence, -// which both surfaces need, and is asserted below. +// sponsorship and referral links are editorial, and projecting them would put a +// vendor relationship in front of a user choosing an endpoint. `order` and +// `protocols` are deliberately not in that set -- display precedence and which +// protocols were verified are what both surfaces need, and are asserted below. func TestSiteOnlyProviderFieldsAreNotParsed(t *testing.T) { - // Every field carries a value that would be obvious if it leaked. + // Every site-only field carries a value that would be obvious if it leaked. data := `{"schema_version":1,"default_fallback_probe_model":"m","providers":{"ok":{ "name":"OK","home":"https://example.com","base_url":"https://api.example.com", "default_model":"m","fallback_probe_model":"m", "relationship":"LEAKED","disclosure":"LEAKED","referral_url":"https://leaked.example.com", - "order":9,"protocols":{"openai":"LEAKED"}}}}` + "order":9,"protocols":{"openai":"implementation-supported","responses":"route-present-unverified"}}}}` manifest, err := ParseProviders([]byte(data)) if err != nil { t.Fatal(err) @@ -366,7 +366,7 @@ func TestSiteOnlyProviderFieldsAreNotParsed(t *testing.T) { if err != nil { t.Fatal(err) } - for _, field := range []string{"LEAKED", "relationship", "disclosure", "referral", "protocols"} { + for _, field := range []string{"LEAKED", "relationship", "disclosure", "referral"} { if contains(string(encoded), field) { t.Fatalf("site-only field %q reached the parsed manifest: %s", field, encoded) } @@ -374,6 +374,60 @@ func TestSiteOnlyProviderFieldsAreNotParsed(t *testing.T) { if got := manifest.Providers["ok"].Order; got != 9 { t.Fatalf("Order = %d, want the manifest value 9", got) } + want := map[string]string{"openai": "implementation-supported", "responses": "route-present-unverified"} + if got := manifest.Providers["ok"].Protocols; !reflect.DeepEqual(got, want) { + t.Fatalf("Protocols = %v, want the manifest table %v", got, want) + } +} + +// A level outside the vocabulary is refused rather than carried through. The +// wizard treats everything but "implementation-supported" as unconfirmed, so a +// typo would not fail anywhere: it would show a compatibility mode hint for a +// Provider that needs none. +func TestParseProvidersRejectsAnUnknownProtocolSupportLevel(t *testing.T) { + data := `{"schema_version":1,"default_fallback_probe_model":"m","providers":{"ok":{ + "name":"OK","home":"https://example.com","base_url":"https://api.example.com", + "default_model":"m","fallback_probe_model":"m","order":1, + "protocols":{"responses":"implementation_supported"}}}}` + if _, err := ParseProviders([]byte(data)); err == nil { + t.Fatal("ParseProviders accepted a support level outside the vocabulary") + } +} + +// The table reaches the frontend through the public projection, which is how +// the wizard knows an Agent's protocol is unconfirmed without sending a request. +// Read from the manifest rather than pinned per vendor: which Providers have +// confirmed Responses will change, and what must hold is that the projection +// says what the manifest says. +func TestPublicProjectionCarriesTheProtocolSupportTable(t *testing.T) { + manifest, err := LoadEmbeddedProviders() + if err != nil { + t.Fatal(err) + } + public := PublicProviders() + for id, provider := range manifest.Providers { + if len(provider.Protocols) == 0 { + t.Fatalf("built-in Provider %q declares no protocol support", id) + } + if got := public[id].Protocols; !reflect.DeepEqual(got, provider.Protocols) { + t.Fatalf("PublicProviders()[%q].Protocols = %v, want %v", id, got, provider.Protocols) + } + if got := ProviderProtocols(id); !reflect.DeepEqual(got, provider.Protocols) { + t.Fatalf("ProviderProtocols(%q) = %v, want %v", id, got, provider.Protocols) + } + } + if got := ProviderProtocols("not-a-built-in-provider"); got != nil { + t.Fatalf("ProviderProtocols for an unknown Provider = %v, want nil", got) + } + + // A caller editing its copy must not change what the next caller reads. + for id := range manifest.Providers { + ProviderProtocols(id)[ProtocolResponses] = "edited" + PublicProviders()[id].Protocols[ProtocolResponses] = "edited" + if got, want := ProviderProtocols(id)[ProtocolResponses], manifest.Providers[id].Protocols[ProtocolResponses]; got != want { + t.Fatalf("catalog table for %q was edited through a copy: %q, want %q", id, got, want) + } + } } // A built-in Provider that omits `order` must be refused rather than defaulted. diff --git a/internal/catalog/providers.go b/internal/catalog/providers.go index 11911b23..6a53a1cf 100644 --- a/internal/catalog/providers.go +++ b/internal/catalog/providers.go @@ -40,6 +40,23 @@ type providerFileEntry struct { // already existed for the site's explorer; parsing it makes one manifest // answer the ordering question everywhere instead of two places drifting. Order int `json:"order"` + // Protocol ID -> how far support for it has been confirmed on this + // Provider's endpoint. Read so the wizard can say, before any request is + // sent, that an Agent's protocol is unconfirmed here. It is the only + // site-facing field with a technical meaning; the commercial ones beside + // it in the manifest stay unparsed. + Protocols map[string]string `json:"protocols"` +} + +// ProtocolSupportConfirmed is the one level that means a protocol was verified +// against a built-in Provider. Every other level is some form of "not yet". +const ProtocolSupportConfirmed = "implementation-supported" + +var protocolSupportLevels = map[string]bool{ + ProtocolSupportConfirmed: true, + "route-present-unverified": true, + "release-candidate-required": true, + "not-supported": true, } type providerFile struct { @@ -86,6 +103,7 @@ func ParseProviders(data []byte) (ProviderManifest, error) { AnthropicBaseURL: entry.AnthropicBaseURL, DefaultModel: entry.DefaultModel, Order: entry.Order, + Protocols: maps.Clone(entry.Protocols), fallbackModel: entry.FallbackProbeModel, } } @@ -136,6 +154,13 @@ func validateProviders(source providerFile) error { if entry.Order <= 0 { return invalidProvider(id, "order must be positive") } + // A misspelt level would read as "unconfirmed" and put a compatibility + // mode hint in front of a Provider that does not need one. + for protocol, level := range entry.Protocols { + if !protocolSupportLevels[level] { + return invalidProvider(id, "unknown support level for "+protocol) + } + } } return nil } @@ -147,7 +172,10 @@ func invalidProvider(providerID, message string) error { func cloneProviderManifest(source ProviderManifest) ProviderManifest { result := source result.Providers = make(map[string]Provider, len(source.Providers)) - maps.Copy(result.Providers, source.Providers) + for id, provider := range source.Providers { + provider.Protocols = maps.Clone(provider.Protocols) + result.Providers[id] = provider + } return result } diff --git a/internal/catalog/public.go b/internal/catalog/public.go index df8e9de8..6dc95876 100644 --- a/internal/catalog/public.go +++ b/internal/catalog/public.go @@ -1,6 +1,9 @@ package catalog -import "sort" +import ( + "maps" + "sort" +) const ( ProtocolOpenAI = "openai" @@ -107,12 +110,19 @@ func ProviderOrder(providerID string) int { return providerDefinitions[providerID].Order } +// ProviderProtocols is a built-in Provider's protocol support table, copied so +// a caller cannot edit the catalog. Nil for a Provider that is not built in. +func ProviderProtocols(providerID string) map[string]string { + return maps.Clone(providerDefinitions[providerID].Protocols) +} + func PublicProviders() map[string]Provider { result := make(map[string]Provider, len(providerDefinitions)) for id, provider := range providerDefinitions { // fallbackModel is unexported and therefore cannot leak through JSON, // but clear it here as an additional boundary for non-JSON callers. provider.fallbackModel = "" + provider.Protocols = maps.Clone(provider.Protocols) result[id] = provider } return result @@ -124,6 +134,7 @@ func ProviderByID(providerID string) (Provider, bool) { return Provider{}, false } provider.fallbackModel = "" + provider.Protocols = maps.Clone(provider.Protocols) return provider, true } diff --git a/internal/catalog/types.go b/internal/catalog/types.go index 78d551bb..b16c033b 100644 --- a/internal/catalog/types.go +++ b/internal/catalog/types.go @@ -115,10 +115,14 @@ type Provider struct { DefaultModel string `json:"default_model,omitempty"` // Display precedence among built-in Providers, ascending. Absent for a // custom Provider, which the frontend sorts by creation time instead. - Order int `json:"order,omitempty"` - Custom bool `json:"custom,omitempty"` - HasKey bool `json:"has_key,omitempty"` - CreatedAt string `json:"created_at,omitempty"` + Order int `json:"order,omitempty"` + // Protocol ID -> confirmed support level on a built-in Provider's endpoint, + // from providers.lock.json. Absent for a custom Provider, whose endpoint + // nothing is known about. + Protocols map[string]string `json:"protocols,omitempty"` + Custom bool `json:"custom,omitempty"` + HasKey bool `json:"has_key,omitempty"` + CreatedAt string `json:"created_at,omitempty"` // Unexported, and cleared again by PublicProviders: which model we probe // with is an internal implementation detail, not a recommendation. fallbackModel string diff --git a/internal/provider/store.go b/internal/provider/store.go index fa3c5966..a03d9ea0 100644 --- a/internal/provider/store.go +++ b/internal/provider/store.go @@ -191,6 +191,9 @@ func (s Store) Public() (map[string]catalog.Provider, error) { // built-in Provider would otherwise reset its order to zero and jump // it to the head of the list. Order: catalog.ProviderOrder(id), + // Nil for a custom Provider. Re-read for a built-in one as above: + // the wizard reads this right after the first key is saved. + Protocols: catalog.ProviderProtocols(id), } } return result, nil diff --git a/internal/provider/store_test.go b/internal/provider/store_test.go index f0a52fbf..1b05dbb8 100644 --- a/internal/provider/store_test.go +++ b/internal/provider/store_test.go @@ -4,8 +4,10 @@ import ( "context" "errors" "os" + "reflect" "testing" + "github.com/MaimoryLab/BootAgent/internal/catalog" oneerrors "github.com/MaimoryLab/BootAgent/internal/errors" "github.com/MaimoryLab/BootAgent/internal/securefs" ) @@ -133,3 +135,45 @@ func TestCreateRefusesABuiltInProviderID(t *testing.T) { t.Fatalf("editing a built-in Provider was refused: %v", err) } } + +// Public replaces a built-in Provider's catalog entry with the saved one, so +// every manifest field has to be re-read there. The protocol table is read by +// the wizard right after the first key is saved, which is exactly when a field +// dropped by the overlay would go missing. +func TestPublicKeepsABuiltInProvidersProtocolTableAfterAKeyIsSaved(t *testing.T) { + store := NewStore(t.TempDir(), securefs.New(securefs.Options{OS: "linux"})) + builtIn, ok := catalog.ProviderByID("ppio") + if !ok || len(builtIn.Protocols) == 0 { + t.Fatalf("fixture Provider ppio has no protocol table: %#v", builtIn) + } + before, err := store.Public() + if err != nil { + t.Fatal(err) + } + if !reflect.DeepEqual(before["ppio"].Protocols, builtIn.Protocols) { + t.Fatalf("Protocols before a key is saved = %v, want %v", before["ppio"].Protocols, builtIn.Protocols) + } + + if _, err := store.Save(context.Background(), Entry{ + ID: "ppio", Name: builtIn.Name, Home: builtIn.Home, BaseURL: builtIn.BaseURL, + AnthropicBaseURL: builtIn.AnthropicBaseURL, APIKey: "sk-saved", + }); err != nil { + t.Fatal(err) + } + if _, err := store.Save(context.Background(), Entry{ + ID: "acme", Name: "Acme", BaseURL: "https://api.acme.test/openai", APIKey: "sk-custom", + }); err != nil { + t.Fatal(err) + } + after, err := store.Public() + if err != nil { + t.Fatal(err) + } + if !after["ppio"].HasKey || !reflect.DeepEqual(after["ppio"].Protocols, builtIn.Protocols) { + t.Fatalf("Protocols after a key is saved = %v (has key: %v), want %v", after["ppio"].Protocols, after["ppio"].HasKey, builtIn.Protocols) + } + // Nothing is known about a custom endpoint, so it carries no table. + if got := after["acme"].Protocols; got != nil { + t.Fatalf("custom Provider Protocols = %v, want none", got) + } +}