= {
zcode: "integrations.tab.zcode",
prime: "integrations.tab.prime",
aside: "integrations.tab.aside",
+ raycast: "integrations.tab.raycast",
};
export default function FileIntegrationPage({
@@ -261,6 +264,8 @@ export default function FileIntegrationPage({
{t(SEMANTICS_KEY[client])}
{status.configPath}
+ {/* Only the raycast envelope carries this; the guard is the field, not the id. */}
+ {status.raycast && }
{status.appliedAt && (
diff --git a/gui/src/pages/integrations/RaycastPlanNotice.tsx b/gui/src/pages/integrations/RaycastPlanNotice.tsx
new file mode 100644
index 0000000000..9f08446751
--- /dev/null
+++ b/gui/src/pages/integrations/RaycastPlanNotice.tsx
@@ -0,0 +1,32 @@
+import { useT } from "../../i18n/shared";
+import { Notice } from "../../ui";
+import type { RaycastInstall } from "./integration-api";
+
+/*
+ * Raycast is the one file client whose `current` state can still mean
+ * "ignored": Custom Providers is a Pro feature, and the file is read from a
+ * folder Raycast only creates after a click in its own settings. Neither fact
+ * is a reason to refuse the write -- the user may be about to subscribe, or
+ * has already clicked and the folder is seconds old -- so the page writes and
+ * says so here instead of showing a green badge that overstates the result.
+ *
+ * `free` is a warning because it is a known blocker; `unknown` stays muted
+ * because on Linux and Windows there is no subscription signal to read, and a
+ * Pro user there must not be told they are not one.
+ */
+export default function RaycastPlanNotice({ install }: { install: RaycastInstall }) {
+ const t = useT();
+ return (
+ <>
+ {install.plan === "free" && (
+ {t("integrations.raycast.proRequired")}
+ )}
+ {install.plan === "unknown" && (
+
{t("integrations.raycast.planUnknown")}
+ )}
+ {!install.aiDirPresent && (
+ {t("integrations.raycast.revealConfig")}
+ )}
+
+ );
+}
diff --git a/gui/src/pages/integrations/integration-api.ts b/gui/src/pages/integrations/integration-api.ts
index 7a9139f436..85ffdc7be4 100644
--- a/gui/src/pages/integrations/integration-api.ts
+++ b/gui/src/pages/integrations/integration-api.ts
@@ -14,6 +14,7 @@ export const FILE_INTEGRATION_CLIENTS = [
"zcode",
"prime",
"aside",
+ "raycast",
] as const;
export type FileIntegrationClientId = (typeof FILE_INTEGRATION_CLIENTS)[number];
@@ -25,6 +26,7 @@ export type IntegrationReason =
| "foreign-edit"
| "unowned-key"
| "blocked-container"
+ | "ambiguous-selector"
| "unresolvable-path";
export type IntegrationRefusalReason =
@@ -36,6 +38,19 @@ export type IntegrationRefusalReason =
| "snapshot_expired"
| "write_failed";
+export type RaycastPlan = "pro" | "free" | "unknown";
+
+/**
+ * Raycast's app-side facts, sent only on `/api/client-integrations/raycast`.
+ * Custom Providers is a Pro feature, so a `current` file can still be one
+ * Raycast ignores — this is what lets the page say so instead of showing green.
+ */
+export interface RaycastInstall {
+ plan: RaycastPlan;
+ appPath: string | null;
+ aiDirPresent: boolean;
+}
+
export interface IntegrationStatus {
clientId: FileIntegrationClientId;
state: IntegrationState;
@@ -49,6 +64,7 @@ export interface IntegrationStatus {
/** Aside's explicit account-backed profile scope and desired sync state. */
profileId?: number;
enabled?: boolean;
+ raycast?: RaycastInstall;
}
export interface IntegrationStateListEnvelope {
diff --git a/gui/src/pages/integrations/integration-tabs.ts b/gui/src/pages/integrations/integration-tabs.ts
index 33c4f04358..99502bde87 100644
--- a/gui/src/pages/integrations/integration-tabs.ts
+++ b/gui/src/pages/integrations/integration-tabs.ts
@@ -46,6 +46,7 @@ export const TABS: readonly TabDefinition[] = [
{ id: "zcode", hash: "integrations/zcode", labelKey: "integrations.tab.zcode" },
{ id: "prime", hash: "integrations/prime", labelKey: "integrations.tab.prime" },
{ id: "aside", hash: "integrations/aside", labelKey: "integrations.tab.aside" },
+ { id: "raycast", hash: "integrations/raycast", labelKey: "integrations.tab.raycast" },
] as const;
export const FILE_CLIENTS = new Set([
@@ -61,4 +62,5 @@ export const FILE_CLIENTS = new Set([
"zcode",
"prime",
"aside",
+ "raycast",
]);
diff --git a/gui/src/pages/integrations/overview-clients.ts b/gui/src/pages/integrations/overview-clients.ts
index 4dd347b90c..7932cf5648 100644
--- a/gui/src/pages/integrations/overview-clients.ts
+++ b/gui/src/pages/integrations/overview-clients.ts
@@ -152,6 +152,7 @@ const FILE_LABEL_KEY: Record = {
zcode: "integrations.tab.zcode",
prime: "integrations.tab.prime",
aside: "integrations.tab.aside",
+ raycast: "integrations.tab.raycast",
};
/** A file client's block is in the file for both `current` and `stale`. */
diff --git a/gui/src/pages/models-shared.ts b/gui/src/pages/models-shared.ts
index fdc487301c..1f5ef7786b 100644
--- a/gui/src/pages/models-shared.ts
+++ b/gui/src/pages/models-shared.ts
@@ -1,4 +1,4 @@
-import type { TFn } from "../i18n/shared";
+import type { TFn, TKey } from "../i18n/shared";
import type { ProviderDiscoverySummary } from "../models-groups";
import { modelVisible, type ProviderModelMap } from "../model-visibility";
import { formatNamespacedModelId } from "../provider-icons";
@@ -35,6 +35,8 @@ export interface ModelRow {
custom?: boolean;
customId?: string;
displayName?: string;
+ displayNameOverride?: string;
+ displayNameSource?: "operator" | "provider" | "fallback";
inputModalities?: string[];
contextWindow?: number;
contextCap?: number;
@@ -43,6 +45,26 @@ export interface ModelRow {
reasoningEfforts?: string[];
}
+function containsDisplayNameControlCharacter(value: string): boolean {
+ return [...value].some(character => {
+ const codePoint = character.codePointAt(0)!;
+ return codePoint <= 0x1f
+ || (codePoint >= 0x7f && codePoint <= 0x9f)
+ || codePoint === 0x2028
+ || codePoint === 0x2029;
+ });
+}
+
+/** Mirror the server display-name contract for immediate form feedback. */
+export function modelDisplayNameValidationKey(value: string): TKey | null {
+ const trimmed = value.trim();
+ if (!trimmed) return "models.displayNameRequired";
+ if (trimmed.length > 128) return "models.displayNameTooLong";
+ if (trimmed.includes("/")) return "models.displayNameNoSlash";
+ if (containsDisplayNameControlCharacter(trimmed)) return "models.displayNameNoControl";
+ return null;
+}
+
/**
* Reasoning-effort labels offered in the custom-model dialog. The full set of real
* `reasoning_effort` values (none, minimal, low, medium, high, xhigh, max). Deliberately
diff --git a/gui/src/styles.css b/gui/src/styles.css
index b0bbc0a6ff..a5838be7e4 100644
--- a/gui/src/styles.css
+++ b/gui/src/styles.css
@@ -2639,6 +2639,53 @@ button.prov-account-row.active { cursor: default; }
/* ---- model row hover tooltip ---- */
.model-row-wrap { position: relative; }
+.models-model-identity {
+ display: inline-flex;
+ min-width: 0;
+ flex-direction: column;
+ align-items: flex-start;
+ gap: 1px;
+}
+.models-model-friendly {
+ max-width: min(42vw, 420px);
+ overflow: hidden;
+ color: var(--muted);
+ text-overflow: ellipsis;
+ white-space: nowrap;
+}
+.models-display-name-trigger { flex-shrink: 0; }
+.model-display-name-dialog { max-width: 460px; }
+.model-display-name-identity,
+.model-display-name-current {
+ display: grid;
+ gap: 5px;
+ margin-bottom: 16px;
+}
+.model-display-name-identity code {
+ overflow-wrap: anywhere;
+ color: var(--text);
+}
+.model-display-name-current {
+ grid-template-columns: 1fr auto;
+ align-items: center;
+}
+.model-display-name-current > .text-label { grid-column: 1 / -1; }
+.model-display-name-current strong { min-width: 0; overflow-wrap: anywhere; }
+.model-display-name-dialog > .input { margin-bottom: 6px; }
+.model-display-name-dialog > .small { text-wrap: balance; }
+.model-display-name-error {
+ margin-top: 8px;
+ color: var(--red);
+ font-size: var(--text-label);
+ line-height: var(--leading-body);
+}
+@media (max-width: 560px) {
+ .models-model-friendly { max-width: 58vw; }
+ .model-display-name-current { grid-template-columns: 1fr; }
+ .model-display-name-current > .text-label { grid-column: auto; }
+ .model-display-name-dialog .modal-actions { align-items: stretch; flex-direction: column; }
+ .model-display-name-dialog .modal-actions .btn { width: 100%; }
+}
.model-tip {
z-index: 10;
background: var(--surface);
diff --git a/gui/tests/client-config-panel.test.tsx b/gui/tests/client-config-panel.test.tsx
index 8acc44e9ee..ea8210e7e4 100644
--- a/gui/tests/client-config-panel.test.tsx
+++ b/gui/tests/client-config-panel.test.tsx
@@ -170,8 +170,8 @@ function rowButton(container: HTMLElement, name: string, label: string): HTMLBut
.find(el => el.textContent?.trim() === label)!;
}
-test("the API download surface includes DSH, MiniMax Code and Aside as clients", () => {
- expect(CLIENTS).toEqual(["opencode", "pi", "omp", "hermes", "openclaw", "kimi", "gajae", "dsh", "mcode", "zcode", "prime", "aside"]);
+test("the API download surface includes DSH, MiniMax Code, Aside and Raycast as clients", () => {
+ expect(CLIENTS).toEqual(["opencode", "pi", "omp", "hermes", "openclaw", "kimi", "gajae", "dsh", "mcode", "zcode", "prime", "aside", "raycast"]);
expect(CLIENT_LABEL_KEYS.dsh).toBe("api.clientConfig.clientDsh");
expect(CLIENT_LABEL_KEYS.mcode).toBe("api.clientConfig.clientMcode");
expect(CLIENT_LABEL_KEYS.zcode).toBe("api.clientConfig.clientZcode");
diff --git a/gui/tests/fr-localization.test.ts b/gui/tests/fr-localization.test.ts
index 221de55d00..8c1ca29ada 100644
--- a/gui/tests/fr-localization.test.ts
+++ b/gui/tests/fr-localization.test.ts
@@ -118,6 +118,8 @@ const INTENTIONAL_ENGLISH = new Set([
"api.clientConfig.clientPrime",
"integrations.tab.aside",
"api.clientConfig.clientAside",
+ "integrations.tab.raycast",
+ "api.clientConfig.clientRaycast",
"models.reasoningEffort.minimal",
"models.reasoningEffort.max",
"pws.pacingRpmUnit",
diff --git a/gui/tests/integration-marks.test.ts b/gui/tests/integration-marks.test.ts
index b964bc4ce1..b13387d1b6 100644
--- a/gui/tests/integration-marks.test.ts
+++ b/gui/tests/integration-marks.test.ts
@@ -61,15 +61,16 @@ test("no multi-color asset is masked", () => {
/*
* The inverse rule, and the one that cannot be derived from the file: a mark may
* be a single ink and still not be a masking candidate, because that ink is the
- * brand. openai.svg is #10A37F and deepseek-harness.svg is #4d6bfe; masking
- * either repaints a trademark in the theme's text color. Pinned with their inks
- * so a vendor changing its asset shows up here rather than silently satisfying
- * the assertion.
+ * brand. openai.svg is #10A37F, deepseek-harness.svg is #4d6bfe and raycast.svg
+ * is #FF6363; masking any of them repaints a trademark in the theme's text
+ * color. Pinned with their inks so a vendor changing its asset shows up here
+ * rather than silently satisfying the assertion.
*/
test("a single-ink asset whose ink is a brand color is not masked", () => {
for (const [src, ink] of [
["/provider-icons/openai.svg", "#10a37f"],
["/provider-icons/deepseek-harness.svg", "#4d6bfe"],
+ ["/provider-icons/raycast.svg", "#ff6363"],
] as const) {
expect(MASKED_MARKS.has(src), `${src} must not be masked`).toBe(false);
expect([...inksOf(bodyOf(src))], `${src} ink changed upstream`).toEqual([ink]);
diff --git a/gui/tests/integrations-api.test.ts b/gui/tests/integrations-api.test.ts
index 4338d9ead8..eea7dcfa0c 100644
--- a/gui/tests/integrations-api.test.ts
+++ b/gui/tests/integrations-api.test.ts
@@ -16,9 +16,9 @@ import {
const originalFetch = globalThis.fetch;
-test("DSH and Aside are file integration clients", () => {
+test("DSH, Aside and Raycast are file integration clients", () => {
expect(FILE_INTEGRATION_CLIENTS).toEqual([
- "opencode", "pi", "omp", "hermes", "openclaw", "kimi", "gajae", "dsh", "mcode", "zcode", "prime", "aside",
+ "opencode", "pi", "omp", "hermes", "openclaw", "kimi", "gajae", "dsh", "mcode", "zcode", "prime", "aside", "raycast",
]);
});
diff --git a/gui/tests/integrations-overview-rows.test.ts b/gui/tests/integrations-overview-rows.test.ts
index 5bd673f849..54809a4422 100644
--- a/gui/tests/integrations-overview-rows.test.ts
+++ b/gui/tests/integrations-overview-rows.test.ts
@@ -290,12 +290,17 @@ test("every client counts toward the summary, not just the file clients", () =>
test("an unsettled file list renders unknown rows instead of dropping them", () => {
const built = buildOverviewRows(sources({ clients: [], clientsSettled: false }));
- expect(built.rows).toHaveLength(17);
+ expect(built.rows).toHaveLength(18);
expect(rowById(built, "omp").state).toBe("unknown");
expect(rowById(built, "mcode").state).toBe("unknown");
expect(rowById(built, "zcode").state).toBe("unknown");
expect(rowById(built, "prime").state).toBe("unknown");
expect(rowById(built, "aside").state).toBe("unknown");
+ expect(rowById(built, "raycast")).toMatchObject({
+ hash: "integrations/raycast",
+ labelKey: "integrations.tab.raycast",
+ state: "unknown",
+ });
expect(rowById(built, "kimi").state).toBe("unknown");
expect(rowById(built, "dsh")).toMatchObject({
hash: "integrations/dsh",
diff --git a/gui/tests/locale-parity.test.ts b/gui/tests/locale-parity.test.ts
index 11976154c9..5ea6785493 100644
--- a/gui/tests/locale-parity.test.ts
+++ b/gui/tests/locale-parity.test.ts
@@ -130,6 +130,8 @@ const ZH_TW_KEEP_ENGLISH: ReadonlySet = new Set([
"api.clientConfig.clientPrime",
"integrations.tab.aside",
"api.clientConfig.clientAside",
+ "integrations.tab.raycast",
+ "api.clientConfig.clientRaycast",
"integrations.codex.title",
// Provider proper nouns kept in English
"provider.name.commandCodeAuth",
diff --git a/gui/tests/models-display-name-editor.test.tsx b/gui/tests/models-display-name-editor.test.tsx
new file mode 100644
index 0000000000..b0656391ed
--- /dev/null
+++ b/gui/tests/models-display-name-editor.test.tsx
@@ -0,0 +1,729 @@
+import { afterEach, beforeEach, describe, expect, jest, test } from "bun:test";
+import { Window } from "happy-dom";
+import { act } from "react";
+import type { Root } from "react-dom/client";
+import ModelDisplayNameDialog from "../src/components/ModelDisplayNameDialog";
+import { clearClientResourceStoresForTests } from "../src/client-resource";
+import { LanguageProvider } from "../src/i18n/provider";
+import { installApiAuthFetch, resetApiAuthFetchForTests } from "../src/api";
+import Models from "../src/pages/Models";
+import type { ModelRow } from "../src/pages/models-shared";
+import { modelDisplayNameValidationKey } from "../src/pages/models-shared";
+
+describe("discovered model display name validation", () => {
+ test("accepts a safe label at both ordinary and maximum length", () => {
+ expect(modelDisplayNameValidationKey("Grok 4.6")).toBeNull();
+ expect(modelDisplayNameValidationKey("A".repeat(128))).toBeNull();
+ expect(modelDisplayNameValidationKey("모델 이름")).toBeNull();
+ expect(modelDisplayNameValidationKey("🚀".repeat(64))).toBeNull();
+ expect(modelDisplayNameValidationKey("🚀".repeat(65))).toBe("models.displayNameTooLong");
+ });
+
+ test("rejects values that the management API cannot persist", () => {
+ expect(modelDisplayNameValidationKey(" ")).toBe("models.displayNameRequired");
+ expect(modelDisplayNameValidationKey("Grok/4.6")).toBe("models.displayNameNoSlash");
+ for (const control of ["\n", "\u0000", "\u007f", "\u0085", "\u2028", "\u2029"]) {
+ expect(modelDisplayNameValidationKey(`Grok${control}4.6`)).toBe("models.displayNameNoControl");
+ }
+ expect(modelDisplayNameValidationKey("A".repeat(129))).toBe("models.displayNameTooLong");
+ });
+});
+
+describe("discovered model display name responsive styles", () => {
+ test("keeps the narrow action order aligned with keyboard navigation", async () => {
+ const styles = await Bun.file(new URL("../src/styles.css", import.meta.url)).text();
+
+ expect(styles).toContain(
+ ".model-display-name-dialog .modal-actions { align-items: stretch; flex-direction: column; }",
+ );
+ expect(styles).not.toContain(
+ ".model-display-name-dialog .modal-actions { align-items: stretch; flex-direction: column-reverse; }",
+ );
+ });
+});
+
+describe("Models dashboard discovered display name integration", () => {
+ const globals = [
+ "document", "window", "navigator", "localStorage", "sessionStorage",
+ "IS_REACT_ACT_ENVIRONMENT", "fetch", "setInterval", "clearInterval",
+ ] as const;
+ let previousGlobals: Record<(typeof globals)[number], PropertyDescriptor | undefined>;
+ let testWindow: Window;
+ let container: HTMLElement;
+ let root: Root | null;
+ let mutationBodies: Array<{ modelId: string; displayName: string | null }>;
+ let mutationFailure: string | null;
+ let savedFailure: boolean;
+ let mutationGate: Promise | null;
+ let modelFetches: number;
+ let modelFetchFailure: string | null;
+ let currentModels: ModelRow[];
+
+ const routedModel = (): ModelRow => ({
+ provider: "xai-demo",
+ id: "grok-4.6",
+ namespaced: "xai-demo/grok-4.6",
+ disabled: false,
+ displayName: "Grok 4.6",
+ displayNameOverride: "Grok 4.6",
+ displayNameSource: "operator",
+ });
+
+ beforeEach(() => {
+ clearClientResourceStoresForTests();
+ previousGlobals = Object.fromEntries(
+ globals.map(key => [key, Object.getOwnPropertyDescriptor(globalThis, key)]),
+ ) as typeof previousGlobals;
+ testWindow = new Window({ url: "http://localhost/#models" });
+ Object.defineProperties(globalThis, {
+ document: { configurable: true, value: testWindow.document },
+ window: { configurable: true, value: testWindow },
+ navigator: { configurable: true, value: testWindow.navigator },
+ localStorage: { configurable: true, value: testWindow.localStorage },
+ sessionStorage: { configurable: true, value: testWindow.sessionStorage },
+ IS_REACT_ACT_ENVIRONMENT: { configurable: true, value: true },
+ setInterval: { configurable: true, value: () => 1 },
+ clearInterval: { configurable: true, value: () => {} },
+ });
+ currentModels = [
+ routedModel(),
+ {
+ provider: "command-code",
+ id: "deepseek-deepseek-v4-flash",
+ namespaced: "command-code/deepseek-deepseek-v4-flash",
+ disabled: false,
+ displayName: "DeepSeek V4 Flash",
+ displayNameSource: "provider",
+ },
+ { provider: "openai", id: "gpt-5.5", namespaced: "openai/gpt-5.5", disabled: false, native: true },
+ {
+ provider: "xai-demo", id: "custom-one", namespaced: "xai-demo/custom-one",
+ disabled: false, custom: true, customId: "custom-1", displayName: "Custom One",
+ },
+ ];
+ mutationBodies = [];
+ mutationFailure = null;
+ savedFailure = false;
+ resetApiAuthFetchForTests();
+ mutationGate = null;
+ modelFetches = 0;
+ modelFetchFailure = null;
+ testWindow.localStorage.setItem("ocx-models-collapsed:v2", JSON.stringify([]));
+ testWindow.sessionStorage.setItem("ocx.models.catalog.v1:http://localhost", JSON.stringify({
+ models: currentModels,
+ providers: [
+ { name: "xai-demo", liveModels: false, models: ["grok-4.6", "custom-one"] },
+ { name: "command-code", liveModels: false, models: ["deepseek-deepseek-v4-flash"] },
+ { name: "openai", liveModels: false, models: ["gpt-5.5"] },
+ ],
+ selectedModels: {},
+ disabled: [],
+ contextCaps: {},
+ contextCapValue: 350_000,
+ }));
+
+ globalThis.fetch = (async (input, init) => {
+ const url = String(input);
+ if (url.endsWith("/api/models")) {
+ modelFetches += 1;
+ if (modelFetchFailure) {
+ return Response.json({ error: modelFetchFailure }, { status: 500 });
+ }
+ return Response.json(currentModels);
+ }
+ if (url.endsWith("/api/providers")) return Response.json([
+ { name: "xai-demo", liveModels: false, models: ["grok-4.6", "custom-one"] },
+ { name: "command-code", liveModels: false, models: ["deepseek-deepseek-v4-flash"] },
+ { name: "openai", liveModels: false, models: ["gpt-5.5"] },
+ ]);
+ if (url.endsWith("/api/selected-models")) return Response.json({ selected: {} });
+ if (url.endsWith("/api/provider-context-caps")) return Response.json({ caps: {} });
+ if (url.endsWith("/api/aliases")) return Response.json({ providers: {}, models: {}, defaults: { global: false, providers: {} } });
+ if (url.endsWith("/api/combos")) return Response.json({ combos: [] });
+ if (url.endsWith("/api/shadow-call-settings")) return Response.json({ enabled: false, model: "" });
+ if (url.endsWith("/api/v2")) return Response.json({ enabled: false, agentsMaxThreadsConflict: false, multiAgentMode: "default" });
+ if (url.includes("/api/providers/xai-demo/model-display-names") && init?.method === "PUT") {
+ const body = JSON.parse(String(init.body)) as { modelId: string; displayName: string | null };
+ mutationBodies.push(body);
+ if (mutationGate) await mutationGate;
+ if (mutationFailure && !savedFailure) return Response.json({ error: mutationFailure }, { status: 500 });
+ currentModels = currentModels.map(row => row.namespaced !== "xai-demo/grok-4.6" ? row : {
+ ...row,
+ displayName: body.displayName ?? "xai-demo/grok-4.6",
+ displayNameOverride: body.displayName ?? undefined,
+ displayNameSource: body.displayName ? "operator" : "fallback",
+ });
+ if (savedFailure) return Response.json({
+ error: "model display name saved but catalog refresh failed",
+ saved: true,
+ displayNameOverride: body.displayName,
+ }, { status: 503 });
+ const row = currentModels.find(model => model.namespaced === "xai-demo/grok-4.6")!;
+ return Response.json({
+ ok: true,
+ displayName: row.displayName,
+ displayNameOverride: row.displayNameOverride ?? null,
+ displayNameSource: row.displayNameSource,
+ });
+ }
+ return new Response(null, { status: 404 });
+ }) as typeof fetch;
+
+ container = testWindow.document.createElement("div");
+ testWindow.document.body.appendChild(container as never);
+ root = null;
+ });
+
+ afterEach(async () => {
+ resetApiAuthFetchForTests();
+ clearClientResourceStoresForTests();
+ if (root) {
+ const mounted = root;
+ await act(async () => mounted.unmount());
+ }
+ testWindow.close();
+ for (const key of globals) {
+ const descriptor = previousGlobals[key];
+ if (descriptor) Object.defineProperty(globalThis, key, descriptor);
+ else Reflect.deleteProperty(globalThis, key);
+ }
+ });
+
+ async function flush() {
+ await act(async () => {
+ await new Promise(resolve => testWindow.setTimeout(resolve, 0));
+ await Promise.resolve();
+ });
+ }
+
+ async function mountModels() {
+ const { createRoot } = await import("react-dom/client");
+ await act(async () => {
+ root = createRoot(container);
+ root.render();
+ });
+ await flush();
+ }
+
+ function nameTrigger(): HTMLButtonElement {
+ return container.querySelector(
+ '[aria-label="Edit friendly name for xai-demo/grok-4.6"]',
+ )!;
+ }
+
+ function dialogInput(): HTMLInputElement {
+ return container.querySelector("dialog")!
+ .querySelector("input")!;
+ }
+
+ function setInputValue(input: HTMLInputElement, value: string) {
+ Object.getOwnPropertyDescriptor(testWindow.HTMLInputElement.prototype, "value")!
+ .set!.call(input, value);
+ input.dispatchEvent(new testWindow.Event("input", { bubbles: true }));
+ }
+
+ function dialogButton(label: string): HTMLButtonElement {
+ return [...container.querySelectorAll("dialog button")]
+ .find(button => button.textContent === label)!;
+ }
+
+ test("only discovered rows expose Name while showing friendly and exact identities", async () => {
+ await mountModels();
+
+ expect(nameTrigger()).not.toBeNull();
+ expect(container.querySelectorAll('[aria-label^="Edit friendly name for "]')).toHaveLength(2);
+ expect(container.querySelector('[aria-label="Edit friendly name for openai/gpt-5.5"]')).toBeNull();
+ expect(container.querySelector('[aria-label="Edit friendly name for xai-demo/custom-one"]')).toBeNull();
+ expect(container.textContent).toContain("Grok 4.6");
+ expect(container.textContent).toContain("xai-demo/grok-4.6");
+ expect([...container.querySelectorAll("code")].some(code =>
+ code.textContent === "command-code/deepseek-deepseek-v4-flash"
+ )).toBe(true);
+ expect(container.textContent).toContain("Custom One");
+ });
+
+ test("save and reset send exact payloads, reload the catalog, and restore trigger focus", async () => {
+ await mountModels();
+ const trigger = nameTrigger();
+ const fetchesBeforeSave = modelFetches;
+
+ await act(async () => trigger.click());
+ await act(async () => {
+ setInputValue(dialogInput(), " Grok Fast ");
+ dialogButton("Save").click();
+ });
+ await flush();
+
+ expect(mutationBodies).toEqual([{ modelId: "grok-4.6", displayName: "Grok Fast" }]);
+ expect(modelFetches).toBeGreaterThan(fetchesBeforeSave);
+ expect(container.querySelector("dialog")).toBeNull();
+ expect(container.textContent).toContain("Grok Fast");
+ expect(testWindow.document.activeElement).toBe(trigger);
+
+ await act(async () => nameTrigger().click());
+ await act(async () => dialogButton("Reset name").click());
+ await flush();
+
+ expect(mutationBodies[1]).toEqual({ modelId: "grok-4.6", displayName: null });
+ expect(container.querySelector("dialog")).toBeNull();
+ expect(container.textContent).toContain("xai-demo/grok-4.6");
+ });
+
+ test("a server failure keeps the dialog and edited draft available for retry", async () => {
+ mutationFailure = "Catalog refresh failed";
+ await mountModels();
+ await act(async () => nameTrigger().click());
+ await act(async () => {
+ setInputValue(dialogInput(), "Retry Name");
+ dialogButton("Save").click();
+ });
+ await flush();
+
+ expect(mutationBodies).toEqual([{ modelId: "grok-4.6", displayName: "Retry Name" }]);
+ expect(container.querySelector("dialog")).not.toBeNull();
+ expect(dialogInput().value).toBe("Retry Name");
+ expect(container.textContent).toContain("Catalog refresh failed");
+ expect(testWindow.document.activeElement).toBe(dialogInput());
+ mutationFailure = null;
+ await act(async () => dialogButton("Save").click());
+ await flush();
+ expect(mutationBodies).toHaveLength(2);
+ expect(currentModels[0]!.displayNameOverride).toBe("Retry Name");
+ expect(container.querySelector("dialog")).toBeNull();
+ });
+
+ test("a failed catalog reload after save keeps the dialog available for retry", async () => {
+ await mountModels();
+ modelFetchFailure = "Catalog reload failed";
+ await act(async () => nameTrigger().click());
+ await act(async () => {
+ setInputValue(dialogInput(), "Retry Reload");
+ dialogButton("Save").click();
+ });
+ await flush();
+
+ expect(mutationBodies).toEqual([{ modelId: "grok-4.6", displayName: "Retry Reload" }]);
+ expect(container.querySelector("dialog")).not.toBeNull();
+ expect(dialogInput().value).toBe("Retry Reload");
+ expect(container.textContent).toContain("The change was saved, but the model list could not be refreshed.");
+ expect(testWindow.document.activeElement).toBe(dialogInput());
+ });
+
+ function currentNameText(): string {
+ return container.querySelector(".model-display-name-current")!.textContent ?? "";
+ }
+
+ test("first save followed by failed reload updates the snapshot and enables Reset", async () => {
+ await mountModels();
+ await act(async () => nameTrigger().click());
+ await act(async () => dialogButton("Reset name").click());
+ await flush();
+ mutationBodies = [];
+ await act(async () => nameTrigger().click());
+ expect(dialogButton("Reset name").disabled).toBe(true);
+ modelFetchFailure = "reload failed";
+ await act(async () => {
+ setInputValue(dialogInput(), " First Name ");
+ dialogButton("Save").click();
+ });
+ await flush();
+ expect(dialogInput().value).toBe("First Name");
+ expect(currentNameText()).toContain("First Name");
+ expect(currentNameText()).toContain("Your name");
+ expect(dialogButton("Reset name").disabled).toBe(false);
+
+ modelFetchFailure = null;
+ await act(async () => dialogButton("Retry").click());
+ await flush();
+ expect(mutationBodies).toEqual([{ modelId: "grok-4.6", displayName: "First Name" }]);
+ expect(container.querySelector("dialog")).toBeNull();
+ });
+
+ test("reset followed by failed reload clears the draft and Enter retries only the read", async () => {
+ await mountModels();
+ await act(async () => nameTrigger().click());
+ modelFetchFailure = "reload failed";
+ await act(async () => dialogButton("Reset name").click());
+ await flush();
+ expect(dialogInput().value).toBe("");
+ expect(currentNameText()).toContain("xai-demo/grok-4.6");
+ expect(currentNameText()).not.toContain("Your name");
+ expect(dialogButton("Reset name").disabled).toBe(true);
+
+ modelFetchFailure = null;
+ await act(async () => container.querySelector("dialog form")!.dispatchEvent(
+ new testWindow.Event("submit", { bubbles: true, cancelable: true }),
+ ));
+ await flush();
+ expect(mutationBodies).toEqual([{ modelId: "grok-4.6", displayName: null }]);
+ expect(container.querySelector("dialog")).toBeNull();
+ expect(currentModels[0]!.displayNameOverride).toBeUndefined();
+ });
+
+ for (const value of ["Saved Name", null]) {
+ test(`saved:true failure reconciles ${value === null ? "reset" : "save"} and retries the same operation`, async () => {
+ await mountModels();
+ await act(async () => nameTrigger().click());
+ savedFailure = true;
+ await act(async () => {
+ if (value === null) dialogButton("Reset name").click();
+ else {
+ setInputValue(dialogInput(), value);
+ dialogButton("Save").click();
+ }
+ });
+ await flush();
+ expect(dialogInput().value).toBe(value ?? "");
+ expect(dialogButton("Reset name").disabled).toBe(value === null);
+ expect(currentNameText()).toContain(value ?? "Current name unavailable until refresh");
+ expect(currentNameText()).not.toContain(value === null ? "Your name" : "Model ID fallback");
+ expect(container.textContent).toContain("The change was saved");
+ savedFailure = false;
+ await act(async () => dialogButton("Retry").click());
+ await flush();
+ expect(mutationBodies).toEqual([
+ { modelId: "grok-4.6", displayName: value },
+ { modelId: "grok-4.6", displayName: value },
+ ]);
+ expect(container.querySelector("dialog")).toBeNull();
+ });
+ }
+
+ test("confirmed reset survives an ordinary convergence retry error before success", async () => {
+ await mountModels();
+ await act(async () => nameTrigger().click());
+ savedFailure = true;
+ await act(async () => dialogButton("Reset name").click());
+ await flush();
+ savedFailure = false;
+ mutationFailure = "Temporary server failure";
+ await act(async () => dialogButton("Retry").click());
+ await flush();
+ expect(dialogInput().value).toBe("");
+ expect(dialogButton("Reset name").disabled).toBe(true);
+ expect(dialogButton("Retry").disabled).toBe(false);
+ expect(container.textContent).toContain("The change was saved");
+ expect(currentNameText()).not.toContain("Your name");
+ expect(currentModels[0]!.displayNameOverride).toBeUndefined();
+
+ mutationFailure = null;
+ await act(async () => container.querySelector("dialog form")!.dispatchEvent(
+ new testWindow.Event("submit", { bubbles: true, cancelable: true }),
+ ));
+ await flush();
+ expect(mutationBodies.map(body => body.displayName)).toEqual([null, null, null]);
+ expect(container.querySelector("dialog")).toBeNull();
+ expect(currentModels[0]!.displayNameOverride).toBeUndefined();
+ });
+
+ for (const failure of ["transport", "body"] as const) {
+ for (const value of ["Saved despite disconnect", null]) {
+ test(`persisted ${value === null ? "reset" : "save"} with ${failure} failure retries only a read`, async () => {
+ await mountModels();
+ const transport = globalThis.fetch;
+ let failedSignal: AbortSignal | null | undefined;
+ globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+ const response = await transport(input, init);
+ if (init?.method === "PUT" && String(input).includes("model-display-names")) {
+ failedSignal = init.signal;
+ if (failure === "transport") throw new TypeError("Connection closed");
+ Object.defineProperty(response, "text", {
+ value: async () => { throw new TypeError("Response body interrupted"); },
+ });
+ }
+ return response;
+ }) as typeof fetch;
+ await act(async () => nameTrigger().click());
+ await act(async () => {
+ if (value === null) dialogButton("Reset name").click();
+ else {
+ setInputValue(dialogInput(), value);
+ dialogButton("Save").click();
+ }
+ });
+ await flush();
+ expect(failedSignal?.aborted).toBe(false);
+ expect(currentModels[0]!.displayNameOverride).toBe(value ?? undefined);
+ expect(dialogInput().value).toBe(value ?? "Grok 4.6");
+ expect(currentNameText()).toContain("Current name unavailable until refresh");
+ expect(currentNameText()).not.toContain("Your name");
+ expect(container.textContent).toContain("The change may have been saved");
+ expect(dialogButton("Retry").disabled).toBe(false);
+ expect(dialogButton("Cancel").disabled).toBe(false);
+ await act(async () => container.querySelector("dialog form")!.dispatchEvent(
+ new testWindow.Event("submit", { bubbles: true, cancelable: true }),
+ ));
+ await flush();
+ expect(mutationBodies).toEqual([{ modelId: "grok-4.6", displayName: value }]);
+ expect(currentModels[0]!.displayNameOverride).toBe(value ?? undefined);
+ expect(container.querySelector("dialog")).toBeNull();
+ });
+ }
+ }
+
+ test("editing after a saved receipt explicitly starts a new save", async () => {
+ await mountModels();
+ await act(async () => nameTrigger().click());
+ savedFailure = true;
+ await act(async () => dialogButton("Reset name").click());
+ await flush();
+ savedFailure = false;
+ await act(async () => setInputValue(dialogInput(), "New intention"));
+ await act(async () => dialogButton("Save").click());
+ await flush();
+ expect(mutationBodies.map(body => body.displayName)).toEqual([null, "New intention"]);
+ });
+
+ // Exercise the real global auth wrapper over an abort-aware transport. Only
+ // the deadline clock is controlled; the operation must supply its own signal.
+ for (const stage of ["mutation", "reload"] as const) {
+ test(`stalled ${stage} through installed API fetch releases the editor and retries a read`, async () => {
+ await mountModels();
+ const descriptor = Object.getOwnPropertyDescriptor(AbortSignal, "timeout");
+ const deadline = new AbortController();
+ const budgets: number[] = [];
+ const seenSignals: Array = [];
+ let stall = true;
+ const transport = globalThis.fetch;
+ Object.defineProperty(AbortSignal, "timeout", {
+ configurable: true,
+ value: (ms: number) => { budgets.push(ms); return deadline.signal; },
+ });
+ const boundedTransport = (async (input: RequestInfo | URL, init?: RequestInit) => {
+ if (String(input).includes("model-display-names") || String(input).endsWith("/api/models")) {
+ seenSignals.push(init?.signal);
+ }
+ if (stall && (stage === "mutation"
+ ? init?.method === "PUT" && String(input).includes("model-display-names")
+ : String(input).endsWith("/api/models"))) {
+ // Persist the write before losing its response: abort is not rollback.
+ if (stage === "mutation") await transport(input, init);
+ return new Promise((_resolve, reject) => {
+ const signal = init?.signal;
+ if (signal?.aborted) reject(signal.reason);
+ else signal?.addEventListener("abort", () => reject(signal.reason), { once: true });
+ });
+ }
+ return transport(input, init);
+ }) as typeof fetch;
+ Object.defineProperty(window, "fetch", { configurable: true, value: boundedTransport });
+ installApiAuthFetch();
+ globalThis.fetch = window.fetch;
+ try {
+ const trigger = nameTrigger();
+ await act(async () => trigger.click());
+ await act(async () => {
+ setInputValue(dialogInput(), "Possibly saved");
+ dialogButton("Save").click();
+ });
+ await flush();
+ expect(budgets).toEqual([60_000]);
+ expect(seenSignals.every(signal => signal != null)).toBe(true);
+ if (stage === "reload") expect(seenSignals[1]).toBe(seenSignals[0]);
+ await act(async () => deadline.abort(new DOMException("Timed out", "TimeoutError")));
+ await flush();
+ expect(dialogInput().disabled).toBe(false);
+ expect(dialogButton("Cancel").disabled).toBe(false);
+ expect(dialogInput().value).toBe("Possibly saved");
+ expect(container.textContent).toContain(stage === "mutation"
+ ? "The change may have been saved" : "The change was saved");
+ expect(testWindow.document.activeElement).toBe(dialogInput());
+ stall = false;
+ if (descriptor) Object.defineProperty(AbortSignal, "timeout", descriptor);
+ await act(async () => dialogButton("Retry").click());
+ await flush();
+ expect(mutationBodies).toHaveLength(1);
+ expect(currentModels[0]!.displayNameOverride).toBe("Possibly saved");
+ expect(container.querySelector("dialog")).toBeNull();
+ expect(testWindow.document.activeElement).toBe(trigger);
+ } finally {
+ if (descriptor) Object.defineProperty(AbortSignal, "timeout", descriptor);
+ else Reflect.deleteProperty(AbortSignal, "timeout");
+ }
+ });
+ }
+
+ test("a pending save blocks duplicate mutations", async () => {
+ let releaseMutation!: () => void;
+ mutationGate = new Promise(resolve => { releaseMutation = resolve; });
+ await mountModels();
+ await act(async () => nameTrigger().click());
+ const save = dialogButton("Save");
+
+ await act(async () => {
+ setInputValue(dialogInput(), "Grok Once");
+ save.click();
+ save.click();
+ await Promise.resolve();
+ });
+ expect(mutationBodies).toEqual([{ modelId: "grok-4.6", displayName: "Grok Once" }]);
+ expect(save.disabled).toBe(true);
+
+ releaseMutation();
+ await flush();
+ expect(container.querySelector("dialog")).toBeNull();
+ });
+
+ test("Cancel closes without mutation and restores focus to Name", async () => {
+ await mountModels();
+ const trigger = nameTrigger();
+ await act(async () => trigger.click());
+ await act(async () => dialogButton("Cancel").click());
+ await flush();
+
+ expect(mutationBodies).toHaveLength(0);
+ expect(container.querySelector("dialog")).toBeNull();
+ expect(testWindow.document.activeElement).toBe(trigger);
+ });
+});
+
+describe("discovered model display name dialog", () => {
+ const globals = ["document", "window", "navigator", "localStorage", "IS_REACT_ACT_ENVIRONMENT"] as const;
+ let previousGlobals: Record<(typeof globals)[number], PropertyDescriptor | undefined>;
+ let testWindow: Window;
+ let container: HTMLElement;
+ let root: Root | null;
+
+ const model: ModelRow = {
+ provider: "xai-demo",
+ id: "grok-4.6",
+ namespaced: "xai-demo/grok-4.6",
+ disabled: false,
+ displayName: "Grok 4.6",
+ displayNameOverride: "Grok 4.6",
+ displayNameSource: "operator",
+ };
+
+ beforeEach(() => {
+ previousGlobals = Object.fromEntries(
+ globals.map(key => [key, Object.getOwnPropertyDescriptor(globalThis, key)]),
+ ) as typeof previousGlobals;
+ testWindow = new Window({ url: "http://localhost/" });
+ Object.defineProperties(globalThis, {
+ document: { configurable: true, value: testWindow.document },
+ window: { configurable: true, value: testWindow },
+ navigator: { configurable: true, value: testWindow.navigator },
+ localStorage: { configurable: true, value: testWindow.localStorage },
+ IS_REACT_ACT_ENVIRONMENT: { configurable: true, value: true },
+ });
+ container = testWindow.document.createElement("div");
+ testWindow.document.body.appendChild(container as never);
+ root = null;
+ });
+
+ afterEach(async () => {
+ if (root) {
+ const mounted = root;
+ await act(async () => mounted.unmount());
+ }
+ testWindow.close();
+ for (const key of globals) {
+ const descriptor = previousGlobals[key];
+ if (descriptor) Object.defineProperty(globalThis, key, descriptor);
+ else Reflect.deleteProperty(globalThis, key);
+ }
+ });
+
+ async function renderDialog(options: {
+ saving?: boolean;
+ requestError?: string | null;
+ onSave?: (value: string) => void;
+ onReset?: () => void;
+ onClose?: () => void;
+ } = {}) {
+ const { createRoot } = await import("react-dom/client");
+ await act(async () => {
+ root ??= createRoot(container);
+ root.render(
+
+ {})}
+ onReset={options.onReset ?? (() => {})}
+ onClose={options.onClose ?? (() => {})}
+ />
+ ,
+ );
+ });
+ }
+
+ function setInputValue(input: HTMLInputElement, value: string) {
+ Object.getOwnPropertyDescriptor(testWindow.HTMLInputElement.prototype, "value")!
+ .set!.call(input, value);
+ input.dispatchEvent(new testWindow.Event("input", { bubbles: true }));
+ }
+
+ test("opens with immutable identity and only the operator override in the input", async () => {
+ await renderDialog();
+
+ const dialog = container.querySelector("dialog")!;
+ const input = container.querySelector("input")!;
+ expect(dialog.open).toBe(true);
+ expect(dialog.textContent).toContain("xai-demo/grok-4.6");
+ expect(dialog.textContent).toContain("Grok 4.6");
+ expect(dialog.textContent).toContain("Your name");
+ expect(input.value).toBe("Grok 4.6");
+ expect(testWindow.document.activeElement).toBe(input);
+ });
+
+ test("validates before save and sends the trimmed safe draft", async () => {
+ const onSave = jest.fn();
+ await renderDialog({ onSave });
+ const input = container.querySelector("input")!;
+ const save = [...container.querySelectorAll("button")]
+ .find(button => button.textContent === "Save")!;
+
+ await act(async () => {
+ setInputValue(input, "Bad/Name");
+ save.click();
+ });
+ expect(container.textContent).toContain("Friendly name cannot contain /.");
+ expect(onSave).not.toHaveBeenCalled();
+
+ await act(async () => {
+ setInputValue(input, " Grok Fast ");
+ save.click();
+ });
+ expect(onSave).toHaveBeenCalledTimes(1);
+ expect(onSave).toHaveBeenCalledWith("Grok Fast");
+ });
+
+ test("keeps request errors visible and locks every closing action while saving", async () => {
+ const onClose = jest.fn();
+ const onReset = jest.fn();
+ await renderDialog({ saving: true, requestError: "Catalog refresh failed", onClose, onReset });
+
+ expect(container.textContent).toContain("Catalog refresh failed");
+ const actionButtons = [...container.querySelectorAll("button")];
+ expect(actionButtons.filter(button => button.tabIndex !== -1).every(button => button.disabled)).toBe(true);
+
+ const dialog = container.querySelector("dialog")!;
+ await act(async () => {
+ dialog.dispatchEvent(new testWindow.Event("cancel", { bubbles: false, cancelable: true }));
+ container.querySelector(".modal-backdrop-dismiss")!.click();
+ });
+ expect(onClose).not.toHaveBeenCalled();
+ expect(onReset).not.toHaveBeenCalled();
+ });
+
+ test("a request failure does not mark a valid display name as invalid", async () => {
+ await renderDialog({ requestError: "Catalog refresh failed" });
+
+ const input = container.querySelector("input")!;
+ expect(input.getAttribute("aria-invalid")).toBeNull();
+ expect(testWindow.document.activeElement).toBe(input);
+ });
+
+ test("focus returns to the editable name after a pending save fails", async () => {
+ await renderDialog({ saving: true });
+ testWindow.document.body.tabIndex = -1;
+ testWindow.document.body.focus();
+ expect(testWindow.document.activeElement).toBe(testWindow.document.body);
+
+ await renderDialog({ requestError: "Catalog refresh failed" });
+
+ expect(testWindow.document.activeElement).toBe(container.querySelector("input"));
+ });
+});
diff --git a/gui/tests/raycast-plan-notice.test.tsx b/gui/tests/raycast-plan-notice.test.tsx
new file mode 100644
index 0000000000..7f08550317
--- /dev/null
+++ b/gui/tests/raycast-plan-notice.test.tsx
@@ -0,0 +1,61 @@
+import { expect, test } from "bun:test";
+import { createElement } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { DICTS, I18nContext, type TFn } from "../src/i18n/shared";
+import RaycastPlanNotice from "../src/pages/integrations/RaycastPlanNotice";
+import type { RaycastInstall } from "../src/pages/integrations/integration-api";
+
+/*
+ * Raycast reads providers.yaml only on a Pro plan and only from a folder it
+ * creates itself, so a `current` badge can be a lie. The notice is the one place
+ * that lie is corrected, and each of its three lines answers a different
+ * question; a regression that drops one leaves the page green and silent.
+ */
+
+const echoT: TFn = key => key;
+
+function render(install: RaycastInstall, t: TFn = echoT): string {
+ return renderToStaticMarkup(
+ createElement(
+ I18nContext.Provider,
+ { value: { locale: "en", setLocale: () => {}, t } },
+ createElement(RaycastPlanNotice, { install }),
+ ),
+ );
+}
+
+test("a Pro install with the ai folder renders nothing", () => {
+ expect(render({ plan: "pro", appPath: "/Applications/Raycast.app", aiDirPresent: true })).toBe("");
+});
+
+test("a free plan is a warning notice, never a refusal", () => {
+ const markup = render({ plan: "free", appPath: "/Applications/Raycast.app", aiDirPresent: true });
+ expect(markup).toContain("notice-warn");
+ expect(markup).toContain("integrations.raycast.proRequired");
+ expect(markup).not.toContain("notice-err");
+ expect(markup).not.toContain("integrations.raycast.planUnknown");
+});
+
+test("an unknown plan stays muted, because non-macOS hosts have no signal", () => {
+ const markup = render({ plan: "unknown", appPath: null, aiDirPresent: true });
+ expect(markup).toContain('data-raycast-plan="unknown"');
+ expect(markup).toContain("integrations.raycast.planUnknown");
+ expect(markup).not.toContain("notice-warn");
+});
+
+test("a missing ai folder adds the reveal hint independently of the plan", () => {
+ const markup = render({ plan: "free", appPath: "/Applications/Raycast.app", aiDirPresent: false });
+ expect(markup).toContain("integrations.raycast.proRequired");
+ expect(markup).toContain('data-raycast-ai-dir="absent"');
+ expect(markup).toContain("integrations.raycast.revealConfig");
+});
+
+test("a Windows install reports unknown Pro activity without claiming a preference read failed", () => {
+ const markup = render({
+ plan: "unknown", appPath: "C:\\Users\\u\\AppData\\Local\\Programs\\Raycast", aiDirPresent: true,
+ }, key => DICTS.en[key]);
+ expect(markup).toContain("Could not determine whether Raycast Pro is active");
+ expect(markup).not.toContain("Could not read");
+ expect(markup).not.toContain("notice-warn");
+ expect(markup).not.toContain(" = {};
+
+class SmokeFailure extends Error {}
+
+function check(ok: unknown, message: string): asserts ok {
+ if (!ok) throw new SmokeFailure(message);
+}
+
+// Do not include arguments, child output, HTTP bodies, or arbitrary error messages in diagnostics.
+function progress(name: string): void {
+ stage = name;
+ console.log(`docker-smoke: ${name}`);
+}
+
+async function run(args: string[], input?: string, timeout = 30_000, cleanup = false) {
+ if (!cleanup) cancelled.signal.throwIfAborted();
+ return await new Promise<{ code: number | null; out: string }>((accept, reject) => {
+ const child = spawn(args[0]!, args.slice(1), {
+ cwd: root, env, detached: true, stdio: ["pipe", "pipe", "pipe"],
+ });
+ const chunks: Buffer[] = [];
+ let bytes = 0;
+ let failed = false;
+ let killTimer: ReturnType | undefined;
+ let reapTimer: ReturnType | undefined;
+ const killGroup = (signal: NodeJS.Signals) => {
+ if (child.pid) {
+ try { process.kill(-child.pid, signal); } catch { /* already exited */ }
+ }
+ };
+ const stop = () => {
+ if (failed) return;
+ failed = true;
+ killGroup("SIGTERM");
+ killTimer = setTimeout(() => killGroup("SIGKILL"), 1_000);
+ // A daemon/plugin retaining a pipe must not keep the harness alive indefinitely.
+ reapTimer = setTimeout(() => {
+ child.stdout.destroy(); child.stderr.destroy(); child.stdin.destroy();
+ finish();
+ child.unref();
+ reject(new SmokeFailure("child did not close within the termination deadline"));
+ }, 4_000);
+ };
+ const timer = setTimeout(stop, timeout);
+ const finish = () => {
+ clearTimeout(timer); clearTimeout(killTimer); clearTimeout(reapTimer);
+ cancelled.signal.removeEventListener("abort", stop);
+ };
+ if (!cleanup) cancelled.signal.addEventListener("abort", stop, { once: true });
+ const collect = (data: Buffer, stdout: boolean) => {
+ bytes += data.length;
+ if (bytes > outputLimit) stop();
+ else if (stdout) chunks.push(data);
+ };
+ child.stdout.on("data", (data: Buffer) => collect(data, true));
+ child.stderr.on("data", (data: Buffer) => collect(data, false));
+ child.stdin.on("error", () => { /* EPIPE is possible on the refused bootstrap. */ });
+ child.on("error", () => { finish(); reject(new SmokeFailure("child could not start")); });
+ child.on("close", code => {
+ // A terminated CLI can close its pipes before its plugin exits.
+ if (failed) killGroup("SIGKILL");
+ finish();
+ if (failed) reject(new SmokeFailure("child exceeded time/output limit or was cancelled"));
+ else accept({ code, out: Buffer.concat(chunks).toString("utf8") });
+ });
+ child.stdin.end(input);
+ });
+}
+
+async function command(args: string[], input?: string, timeout?: number, cleanup = false) {
+ const result = await run(args, input, timeout, cleanup);
+ check(result.code === 0, `command exited ${result.code ?? "by signal"}`);
+ return result.out.trim();
+}
+
+function compose(args: string[], input?: string, timeout?: number, cleanup = false) {
+ return command(["docker", ...composeArgs, ...args], input, timeout, cleanup);
+}
+
+async function build() {
+ const directory = join(root, "src/generated");
+ const manifest = join(directory, "compatibility-version.json");
+ const directoryStat = lstatSync(directory, { throwIfNoEntry: false });
+ const hadDirectory = directoryStat !== undefined;
+ check(!directoryStat || directoryStat.isDirectory(), "unsafe generated directory");
+ const originalStat = lstatSync(manifest, { throwIfNoEntry: false });
+ check(!originalStat || originalStat.isFile(), "unsafe existing manifest");
+ check(!originalStat || originalStat.size <= 8 * 1024 * 1024, "existing manifest exceeds limit");
+ const original = originalStat ? readFileSync(manifest) : undefined;
+ try {
+ progress("generate compatibility manifest");
+ await command([process.execPath, "scripts/generate-compatibility-version.ts"]);
+ progress("build Docker image");
+ await compose(["build", "hub"], undefined, 600_000);
+ } finally {
+ if (original && originalStat) {
+ writeFileSync(manifest, original);
+ chmodSync(manifest, originalStat.mode & 0o777);
+ utimesSync(manifest, originalStat.atime, originalStat.mtime);
+ } else {
+ rmSync(manifest, { force: true });
+ }
+ if (!hadDirectory && existsSync(directory)) rmdirSync(directory);
+ }
+}
+
+const fixture = JSON.stringify({ models: [{
+ slug: "smoke/synthetic", display_name: "Smoke fixture", description: "Synthetic catalog only",
+ priority: 1, visibility: "list", base_instructions: "Synthetic", input_modalities: ["text"],
+}] });
+const token = randomBytes(32).toString("hex");
+const replacement = randomBytes(32).toString("hex");
+const sha256 = (value: string) => createHash("sha256").update(value).digest("hex");
+let seededConfigHash = "";
+let readyConfigHash = "";
+
+// Check the loader, including its schema-repair/default-provider fallback, before server startup
+// and again in each running container. This isolates synthetic inference, not all process egress.
+const fixtureConfigCheck = `
+ const { loadConfig } = await import('./src/config.ts');
+ const effective = loadConfig();
+ const provider = effective.providers.smoke;
+ if (Object.keys(effective.providers).join(',') !== 'smoke' || effective.defaultProvider !== 'smoke'
+ || provider?.adapter !== 'openai-responses' || provider?.authMode !== 'local'
+ || provider?.allowPrivateNetwork !== true
+ || provider?.baseUrl !== 'http://127.0.0.1:9/v1' || provider?.codexAccountMode !== undefined || provider?.apiKey
+ || effective.runtimeRole !== 'hub' || effective.hostname !== '0.0.0.0' || effective.port !== 10100
+ || effective.codexAutoStart !== false || effective.codexShimAutoRestore !== false) throw new Error('unsafe effective fixture config');
+`;
+
+interface Container {
+ Id: string;
+ State: { Running: boolean; Health?: { Status: string } };
+ HostConfig: { ReadonlyRootfs: boolean; CapDrop: string[]; SecurityOpt: string[]; Privileged: boolean };
+ Config: { Image: string; Labels: Record };
+ NetworkSettings: { Ports: Record | null> };
+ Mounts: Array<{ Type: string; Name?: string; Destination: string; RW: boolean }>;
+}
+
+async function inspect() {
+ const id = await compose(["ps", "-q", "hub"]);
+ check(/^[a-f0-9]{64}$/.test(id), "expected exactly one container");
+ const rows = JSON.parse(await command(["docker", "inspect", id])) as Container[];
+ check(rows.length === 1, "unexpected inspect result");
+ const container = rows[0]!;
+ check(container.Id === id && container.Config.Image === image
+ && container.Config.Labels["com.docker.compose.project"] === project, "container identity mismatch");
+ check(container.State.Running && container.State.Health?.Status === "healthy", "container not healthy");
+ check(container.HostConfig.ReadonlyRootfs && !container.HostConfig.Privileged
+ && container.HostConfig.CapDrop.includes("ALL")
+ && container.HostConfig.SecurityOpt.some(value => /^no-new-privileges(?::true)?$/.test(value)), "restrictions missing");
+ const ports = Object.entries(container.NetworkSettings.Ports).filter(([, entries]) => entries?.length);
+ check(ports.length === 1 && ports[0]![0] === "10100/tcp", "unexpected published port");
+ const bindings = ports[0]![1]!;
+ check(bindings.length === 1 && bindings[0]!.HostIp === "127.0.0.1", "non-loopback publication");
+ const port = Number(bindings[0]!.HostPort);
+ check(Number.isInteger(port) && port > 0 && port <= 65535, "invalid host port");
+ const volumes = [".opencodex", ".codex"].map(home => {
+ const mounts = container.Mounts.filter(mount => mount.Destination === `/home/bun/${home}`);
+ check(mounts.length === 1, "missing home mount");
+ const mount = mounts[0]!;
+ check(mount.Type === "volume" && mount.RW && mount.Name?.startsWith(`${project}_`), "unexpected home volume");
+ return mount.Name;
+ });
+ check(volumes[0] !== volumes[1], "homes share a volume");
+ return { id, volumes, url: `http://127.0.0.1:${port}` };
+}
+
+// This runs as the image's user. Only hashes/metadata leave the container, never file bytes.
+const stateProbe = `
+ import { readFileSync, statSync, writeFileSync } from 'node:fs';
+ import { createHash } from 'node:crypto';
+ import { isDeepStrictEqual } from 'node:util';
+ const phase = await Bun.stdin.text();
+ if (!['seed', 'first-ready', 'steady'].includes(phase)) throw new Error('invalid state phase');
+ ${fixtureConfigCheck}
+ const homes = ['/home/bun/.opencodex', '/home/bun/.codex'];
+ if (process.env.OCX_SERVICE !== '1') throw new Error('image service lifecycle mode missing');
+ const uid = process.getuid();
+ if (uid === 0) throw new Error('root user');
+ const status = readFileSync('/proc/self/status', 'utf8');
+ if (!/^CapEff:\\s+0+$/m.test(status) || !/^NoNewPrivs:\\s+1$/m.test(status)) throw new Error('effective restrictions');
+ for (const home of homes) {
+ const s = statSync(home);
+ if (s.uid !== uid || (s.mode & 0o777) !== 0o700) throw new Error('home permissions');
+ }
+ try { writeFileSync('/home/bun/app/.smoke-root-write', 'x'); throw new Error('writable root'); }
+ catch (e) { if (e.code !== 'EROFS') throw e; }
+ const paths = [homes[0] + '/config.json', homes[0] + '/service-api-token', homes[1] + '/opencodex-catalog.json'];
+ const hashes = paths.map(path => {
+ const s = statSync(path);
+ if (s.uid !== uid || (s.mode & 0o777) !== 0o600 || s.size > 65536) throw new Error('file permissions/size');
+ return createHash('sha256').update(readFileSync(path)).digest('hex');
+ });
+ // The immutable shipped config was byte-verified before fixture creation. Reconstruct only
+ // the deliberate fixture route edits, then compare every original key on disk (not loader defaults).
+ const seed = JSON.parse(readFileSync('docker/config.json', 'utf8'));
+ seed.providers = { smoke: { adapter: 'openai-responses', baseUrl: 'http://127.0.0.1:9/v1', authMode: 'local', allowPrivateNetwork: true } };
+ seed.defaultProvider = 'smoke';
+ const persisted = JSON.parse(readFileSync(paths[0], 'utf8'));
+ const loaded = JSON.parse(JSON.stringify(effective));
+ for (const key of Object.keys(seed)) {
+ for (const config of [persisted, loaded]) {
+ if (!Object.hasOwn(config, key) || !isDeepStrictEqual(config[key], seed[key])) throw new Error('seed semantics changed');
+ }
+ }
+ // Independent oracle measured by isolated startup; update only for an intentional contract change.
+ // Do not derive expected values from runtime migration/default helpers.
+ const additions = {
+ appOwnedMemoryBudgetMb: 256, fastRows: true, managementUsageMaxReadBytes: 67108864,
+ openaiProviderTierVersion: 2,
+ subagentModels: ['gpt-6-astra', 'gpt-5.6-sol', 'gpt-5.6-terra', 'gpt-5.6-luna', 'gpt-5.5'],
+ subagentModelsVersion: 1,
+ };
+ for (const config of [persisted, loaded]) {
+ if (Object.keys(config).some(key => !Object.hasOwn(seed, key) && !Object.hasOwn(additions, key))) throw new Error('unexpected startup config addition');
+ for (const [key, expected] of Object.entries(additions)) {
+ if (phase !== 'seed' || Object.hasOwn(config, key)) {
+ if (!Object.hasOwn(config, key) || !isDeepStrictEqual(config[key], expected)) throw new Error('startup oracle mismatch');
+ }
+ }
+ }
+ if (phase === 'seed' && Object.keys(persisted).some(key => !Object.hasOwn(seed, key))) throw new Error('premature seed addition');
+ console.log(JSON.stringify(hashes));
+`;
+
+async function state(phase: "seed" | "first-ready" | "steady" = "steady") {
+ const invocation = phase === "seed" ? ["run", "--rm", "-T", "--no-deps"] : ["exec", "-T"];
+ const hashes = JSON.parse(await compose([...invocation, "hub", "bun", "-e", stateProbe], phase)) as string[];
+ check(hashes.length === 3 && hashes.every(hash => /^[a-f0-9]{64}$/.test(hash)), "invalid state evidence");
+ check(hashes[1] === sha256(`${token}\n`) && hashes[2] === sha256(fixture), "token/catalog changed");
+ if (phase === "first-ready") {
+ check(!readyConfigHash, "post-start config baseline already established");
+ // stateProbe has checked persisted/effective semantics and the independent startup oracle.
+ readyConfigHash = hashes[0]!;
+ } else {
+ check(hashes[0] === (phase === "seed" ? seededConfigHash : readyConfigHash),
+ phase === "seed" ? "seeded config changed before startup" : "post-start config changed");
+ }
+ return JSON.stringify(hashes);
+}
+
+async function request(url: string, path: string, secret?: string) {
+ const controller = new AbortController();
+ const abort = () => controller.abort();
+ cancelled.signal.throwIfAborted();
+ cancelled.signal.addEventListener("abort", abort, { once: true });
+ const timer = setTimeout(abort, 5_000);
+ try {
+ const post = path !== "/healthz" && path !== "/readyz" && path !== "/v1/catalog";
+ const response = await fetch(`${url}${path}`, {
+ method: post ? "POST" : "GET", redirect: "error", signal: controller.signal,
+ headers: { ...(secret ? { "x-opencodex-api-key": secret } : {}), ...(post ? { "content-type": "application/json" } : {}) },
+ // Never send an authorized inference request, even with synthetic input.
+ body: post ? '{"model":"smoke/synthetic","input":[]}' : undefined,
+ });
+ const reader = response.body?.getReader();
+ const chunks: Uint8Array[] = [];
+ let size = 0;
+ try {
+ while (reader) {
+ const next = await reader.read();
+ if (next.done) break;
+ size += next.value.length;
+ check(size <= 64 * 1024, "HTTP body exceeds limit");
+ chunks.push(next.value);
+ }
+ } finally { controller.abort(); reader?.releaseLock(); }
+ return { status: response.status, body: Buffer.concat(chunks).toString("utf8") };
+ } finally {
+ clearTimeout(timer);
+ cancelled.signal.removeEventListener("abort", abort);
+ }
+}
+
+async function acceptance(url: string) {
+ check((await request(url, "/healthz")).status === 200, "liveness failed");
+ const deadline = Date.now() + 60_000;
+ while (true) {
+ const ready = await request(url, "/readyz");
+ const body = JSON.parse(ready.body) as { status?: string };
+ if (ready.status === 200 && body.status === "ready") break;
+ check(ready.status === 503 && body.status === "pending" && Date.now() < deadline, "readiness failed");
+ await Bun.sleep(500);
+ }
+ for (const path of ["/v1/catalog", "/v1/responses", "/v1/responses/compact"]) {
+ for (const secret of [undefined, replacement]) {
+ const result = await request(url, path, secret);
+ check(result.status === 401, `${path} ${secret ? "wrong" : "missing"} token returned ${result.status}, expected 401`);
+ }
+ }
+ const catalog = await request(url, "/v1/catalog", token);
+ check(catalog.status === 200 && catalog.body === fixture, "catalog not served exactly");
+}
+
+async function cleanup() {
+ let failed = false;
+ const attempt = async (action: () => Promise) => {
+ try { await action(); } catch { failed = true; }
+ };
+ if (composeArgs.length) {
+ await attempt(() => compose(["down", "--volumes", "--remove-orphans", "--timeout", "10"], undefined, 45_000, true));
+ for (const kind of ["container", "volume", "network"]) {
+ await attempt(async () => {
+ const remaining = await command(["docker", kind, "ls", "-q", ...(kind === "container" ? ["-a"] : []),
+ "--filter", `label=com.docker.compose.project=${project}`], undefined, 15_000, true);
+ check(!remaining, "project resources remain");
+ });
+ }
+ await attempt(async () => {
+ const ids = await command(["docker", "image", "ls", "-q", "--filter", `reference=${image}`], undefined, 15_000, true);
+ if (ids) await command(["docker", "image", "rm", image], undefined, 30_000, true);
+ check(!await command(["docker", "image", "ls", "-q", "--filter", `reference=${image}`], undefined, 15_000, true), "image remains");
+ });
+ }
+ try { if (scratch) rmSync(scratch, { recursive: true, force: true, maxRetries: 0 }); } catch { failed = true; }
+ check(!failed, "cleanup incomplete");
+}
+
+async function main() {
+ check(process.platform === "linux", "requires a disposable Linux Docker runner");
+ scratch = mkdtempSync(join(tmpdir(), `${project}-`));
+ mkdirSync(join(scratch, "docker"), { mode: 0o700 });
+ writeFileSync(join(scratch, "empty.env"), "", { mode: 0o600 });
+ writeFileSync(join(scratch, "override.json"), JSON.stringify({
+ services: { hub: { image, restart: "no" } },
+ }), { mode: 0o600 });
+ env = {
+ PATH: process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin", TMPDIR: scratch,
+ DOCKER_CONFIG: join(scratch, "docker"), DOCKER_HOST: "unix:///var/run/docker.sock",
+ COMPOSE_DISABLE_ENV_FILE: "1", OPENCODEX_BIND_ADDRESS: "127.0.0.1", OPENCODEX_PORT: "0",
+ };
+ composeArgs = ["compose", "--project-name", project, "--project-directory", root,
+ "--env-file", join(scratch, "empty.env"), "-f", join(root, "compose.yaml"), "-f", join(scratch, "override.json")];
+ progress("validate and build");
+ await compose(["config", "--quiet"]);
+ await build();
+ progress("verify shipped config and seed loopback-only fixture");
+ const seeded = await run(["docker", ...composeArgs, "run", "--rm", "-T", "--no-deps", "hub", "bun", "-e",
+ `
+ import { readFileSync, writeFileSync } from 'node:fs';
+ import { createHash } from 'node:crypto';
+ // Exit codes are fixed diagnostic markers; never serialize the caught exception.
+ let seedStage = 70;
+ try {
+ const { atomicWriteFile } = await import('./src/config/atomic-write.ts');
+ seedStage = 71;
+ const { shipped, catalog } = JSON.parse(await Bun.stdin.text());
+ const path = '/home/bun/.opencodex/config.json';
+ seedStage = 72;
+ if (readFileSync(path, 'utf8') !== shipped || readFileSync('docker/config.json', 'utf8') !== shipped) {
+ throw new Error('shipped config mismatch');
+ }
+ const config = JSON.parse(shipped);
+ if (config.runtimeRole !== 'hub' || config.hostname !== '0.0.0.0' || config.port !== 10100
+ || config.codexAutoStart !== false || config.codexShimAutoRestore !== false) throw new Error('shipped runtime contract');
+ // Port 9 has no listener in this image. Replace all provider routes before any server starts;
+ // even an admission regression cannot send these synthetic requests to a real provider.
+ config.providers = { smoke: { adapter: 'openai-responses', baseUrl: 'http://127.0.0.1:9/v1', authMode: 'local', allowPrivateNetwork: true } };
+ config.defaultProvider = 'smoke';
+ seedStage = 73;
+ const { validateConfigCandidate } = await import('./src/config.ts');
+ if (!validateConfigCandidate(config).ok) throw new Error('invalid fixture');
+ seedStage = 74;
+ atomicWriteFile(path, JSON.stringify(config) + '\\n');
+ seedStage = 75;
+ ${fixtureConfigCheck}
+ seedStage = 76;
+ writeFileSync('/home/bun/.codex/opencodex-catalog.json', catalog, { mode: 0o600, flag: 'wx' });
+ seedStage = 77;
+ console.log(createHash('sha256').update(readFileSync(path)).digest('hex'));
+ } catch { process.exitCode = seedStage; }
+ `], JSON.stringify({ shipped: readFileSync(join(root, "docker/config.json"), "utf8"), catalog: fixture }));
+ const seedFailures: Record = {
+ 70: "imports", 71: "input", 72: "shipped config contract", 73: "fixture validation",
+ 74: "atomic config write", 75: "effective config", 76: "catalog write", 77: "config hash",
+ };
+ check(seeded.code === 0, `seed failed: ${seedFailures[seeded.code ?? -1] ?? "unclassified child failure"} (exit ${seeded.code ?? "signal"})`);
+ seededConfigHash = seeded.out.trim();
+ check(/^[a-f0-9]{64}$/.test(seededConfigHash), "invalid seeded config evidence");
+ progress("bootstrap throwaway token");
+ await compose(["run", "--rm", "-T", "--no-deps", "hub", "bun", "run", "docker/bootstrap-token.ts"], `${token}\n`);
+ progress("verify exact seed state before startup");
+ await state("seed");
+ progress("start and check admission");
+ await compose(["up", "--no-build", "--wait", "--wait-timeout", "120", "hub"], undefined, 150_000);
+ const first = await inspect();
+ await acceptance(first.url);
+ const before = await state("first-ready");
+ progress("refuse token replacement");
+ const refused = await run(["docker", ...composeArgs, "run", "--rm", "-T", "--no-deps", "hub",
+ "bun", "run", "docker/bootstrap-token.ts"], `${replacement}\n`);
+ check(refused.code === 1, "bootstrap did not refuse replacement");
+ check(await state() === before, "state changed after refused bootstrap");
+ await acceptance(first.url);
+ progress("replace container and verify persistence");
+ await compose(["up", "--no-build", "--force-recreate", "--wait", "--wait-timeout", "120", "hub"], undefined, 150_000);
+ const second = await inspect();
+ check(second.id !== first.id && JSON.stringify(second.volumes) === JSON.stringify(first.volumes), "replacement/volume identity failed");
+ check(await state() === before, "persistent state changed");
+ await acceptance(second.url);
+}
+
+const abort = () => cancelled.abort();
+process.once("SIGINT", abort);
+process.once("SIGTERM", abort);
+const deadline = setTimeout(abort, 16 * 60_000);
+try {
+ await main();
+} catch (error) {
+ const reason = error instanceof SmokeFailure ? error.message : "unexpected failure; details suppressed";
+ console.error(`docker-smoke: failed at ${stage}: ${reason}`);
+ process.exitCode = 1;
+} finally {
+ clearTimeout(deadline);
+ try { await cleanup(); } catch {
+ console.error("docker-smoke: cleanup incomplete");
+ process.exitCode = 1;
+ }
+ process.removeListener("SIGINT", abort);
+ process.removeListener("SIGTERM", abort);
+}
+if (!process.exitCode) console.log("docker-smoke: build/start/recreate acceptance passed; cleanup complete");
diff --git a/scripts/test-layout/layout.json b/scripts/test-layout/layout.json
index d309073a3f..65ba23d900 100644
--- a/scripts/test-layout/layout.json
+++ b/scripts/test-layout/layout.json
@@ -204,6 +204,8 @@
"anthropic-image-retry.test.ts": "adapters/anthropic",
"anthropic-pool-toggle-copy.test.ts": "adapters/anthropic",
"anthropic-quorum-cache.test.ts": "routing",
+ "anthropic-quota-dispatch.test.ts": "adapters/anthropic",
+ "anthropic-ratelimit-headers.test.ts": "adapters/anthropic",
"anthropic-reasoning.test.ts": "adapters/anthropic",
"anthropic-sidecar-account-failover.test.ts": "adapters/anthropic",
"anthropic-stream-hardening.test.ts": "adapters/anthropic",
@@ -237,6 +239,7 @@
"aside-profiles-routes.test.ts": "server",
"aside-profiles.test.ts": "clients",
"aside-profile-paths.test.ts": "clients",
+ "aside-profile-identity.test.ts": "clients",
"aside-profile-sync-owner.test.ts": "clients",
"assert-mergeable-review.test.ts": "ci-workflows",
"auto-compact-budget.test.ts": "providers",
@@ -312,6 +315,7 @@
"claude-outbound.test.ts": "claude-integration",
"claude-shell-hook.test.ts": "claude-integration",
"claude-sidecar-override.test.ts": "claude-integration",
+ "claude-source-envelope.test.ts": "claude-integration",
"claude-system-env-auto.test.ts": "claude-integration",
"cleanup-orphaned-workflows.test.ts": "ci-workflows",
"clearable-deadline.test.ts": "lib",
@@ -690,6 +694,7 @@
"install-scripts.test.ts": "ci-workflows",
"integrations-invariants.test.ts": "gui",
"integrations-journal.test.ts": "clients",
+ "integrations-merge.test.ts": "clients",
"integrations-serialize.test.ts": "clients",
"integrations-state.test.ts": "clients",
"integrations-writer.test.ts": "clients",
@@ -998,7 +1003,10 @@
"reserve-quota-scope.test.ts": "codex-integration",
"rate-limit-reset-credits.test.ts": "gui",
"rate-limit-retry.test.ts": "providers",
+ "raycast-client.test.ts": "clients",
+ "raycast-detect.test.ts": "clients",
"reasoning-effort.test.ts": "codex-integration",
+ "reasoning-envelope.test.ts": "responses",
"reasoning-replay-identity.test.ts": "adapters",
"reasoning-replay-robustness.test.ts": "adapters",
"reasoning-replay-scope-source.test.ts": "lib",
diff --git a/skills/ocx/references/01_management_surface.md b/skills/ocx/references/01_management_surface.md
index d5711f3cac..10b0cd9e89 100644
--- a/skills/ocx/references/01_management_surface.md
+++ b/skills/ocx/references/01_management_surface.md
@@ -67,6 +67,7 @@ Drives no management route.
| Flag | Value | Meaning |
|---|---|---|
| `--json` | boolean | Emit the provider list as JSON. |
+| `--jsonl` | boolean | Emit one configured provider per JSON line. |
JSON mode: `envelope`.
diff --git a/skills/ocx/references/02_json_shapes.md b/skills/ocx/references/02_json_shapes.md
index a91e35a2e1..261c8be5a2 100644
--- a/skills/ocx/references/02_json_shapes.md
+++ b/skills/ocx/references/02_json_shapes.md
@@ -52,6 +52,11 @@ to `requestedModel` is how you get a wrong answer about which provider served it
`displayMetrics.cost.estimate.estimateReasons` lists why — for example `usage_estimated`,
`cache_detail_missing`, `expected_price_overlay`.
+## `ocx provider list --jsonl`
+
+One configured provider per line. Each object has the same fields as an item in the
+`configured` array from `ocx provider list --json`; the `registryCount` summary is omitted.
+
## `ocx logs explain `
```json
diff --git a/skills/ocx/references/03_recipes.md b/skills/ocx/references/03_recipes.md
index 424ad34a53..9159751424 100644
--- a/skills/ocx/references/03_recipes.md
+++ b/skills/ocx/references/03_recipes.md
@@ -157,6 +157,7 @@ exist for them — do not attribute usage to either.
```bash
ocx provider list --json
+ocx provider list --jsonl # one configured provider per line
ocx provider add --json # registry providers auto-configure by name
ocx provider test --json
ocx provider set-default --json
diff --git a/src/adapters/anthropic.ts b/src/adapters/anthropic.ts
index 6eea4764a1..a9a8279198 100644
--- a/src/adapters/anthropic.ts
+++ b/src/adapters/anthropic.ts
@@ -1118,9 +1118,14 @@ export function createAnthropicAdapter(provider: OcxProviderConfig, cacheRetenti
break;
}
case "content_block_start": {
- const block = data.content_block as { type: string; id?: string; name?: string; data?: string } | undefined;
+ const block = data.content_block as { type: string; id?: string; name?: string; data?: string; thinking?: string } | undefined;
if (!block) break;
currentBlockType = block.type;
+ if (block.type === "thinking") {
+ // Preserve even a display:omitted block boundary. The bridge can then
+ // distinguish consecutive empty signed blocks from signature updates.
+ yield { type: "thinking_delta", thinking: typeof block.thinking === "string" ? block.thinking : "" };
+ }
if (block.type === "tool_use") {
currentToolCallId = usableToolUseId(block.id);
currentToolCallName = toolNames.fromWire(block.name ?? "");
@@ -1151,8 +1156,8 @@ export function createAnthropicAdapter(provider: OcxProviderConfig, cacheRetenti
// later text blocks independent.
yield { type: "thinking_delta", thinking: delta.reasoning };
} else if (delta.type === "signature_delta" && typeof delta.signature === "string" && (currentBlockType === "thinking" || currentBlockType === "reasoning")) {
- // Arrives once, just before the thinking block's content_block_stop; block-scoped
- // so a stray signature on a non-thinking block can never be captured.
+ // Anthropic SDKs replace the signature with this value. Forward updates
+ // within the block; the bridge closes on the next semantic boundary.
yield { type: "thinking_signature", signature: delta.signature };
} else if (delta.type === "input_json_delta" && typeof delta.partial_json === "string" && currentBlockType === "tool_use") {
// Forwarded immediately: the bridge maps each delta to a client-visible
diff --git a/src/adapters/openai-responses.ts b/src/adapters/openai-responses.ts
index 07c0556d5e..1b8c1b076e 100644
--- a/src/adapters/openai-responses.ts
+++ b/src/adapters/openai-responses.ts
@@ -630,6 +630,13 @@ function mapRoutedResponsesReasoningEffort(
if (provider.authMode === "forward") return body;
if (configuredReasoningEfforts(provider, modelId) === undefined) return body;
if (!isPlainObject(body) || !isPlainObject(body.reasoning)) return body;
+ const declaredEfforts = modelRecordValue(provider.modelReasoningEfforts, modelId) ?? provider.reasoningEfforts;
+ // An explicitly empty ladder means no effort control, not no reasoning output.
+ // Omit only effort so the upstream default applies; unknown/non-rankable ladders stay untouched.
+ if (declaredEfforts?.length === 0 && Object.hasOwn(body.reasoning, "effort")) {
+ const { effort: _effort, ...reasoning } = body.reasoning;
+ return { ...body, reasoning: Object.keys(reasoning).length > 0 ? reasoning : undefined };
+ }
const requested = body.reasoning.effort;
if (typeof requested !== "string") return body;
diff --git a/src/bridge.ts b/src/bridge.ts
index 645dfff8e7..ff044a5e52 100644
--- a/src/bridge.ts
+++ b/src/bridge.ts
@@ -945,6 +945,13 @@ export function bridgeToResponsesSSE(
}
if (event.type !== "done" && event.type !== "incomplete" && event.type !== "error") continue;
}
+ // Anthropic signature_delta supplies the latest signature, not an append-only
+ // fragment (anthropic-sdk-typescript MessageStream). Keep consecutive updates
+ // together; the next semantic event belongs to the following block.
+ if (pendingSignature !== undefined && event.type !== "thinking_signature" && event.type !== "heartbeat") {
+ if (currentReasoning) closeCurrentReasoning();
+ else flushHiddenReasoningEnvelope();
+ }
switch (event.type) {
case "assistant_boundary": {
// A guarded continuation starts a fresh assistant output item while keeping the
@@ -1054,15 +1061,21 @@ export function bridgeToResponsesSSE(
case "thinking_signature": {
pendingSignatureBytes = replaceRetainedString(pendingSignatureBytes, event.signature, "reasoning");
pendingSignature = event.signature;
- // Signature arrives at the end of the thinking block. With a visible reasoning item
- // open, closeCurrentReasoning attaches the envelope; hidden/suppressed blocks flush
- // an envelope-only reasoning item now.
- if (!currentReasoning) flushHiddenReasoningEnvelope();
+ // Delay closing until the next semantic event so a signature update cannot
+ // create another block or become attached to the following thinking text.
break;
}
case "redacted_thinking": {
+ if (currentMsg) closeCurrentMessage("commentary");
+ if (currentReasoning) closeCurrentReasoning();
+ if (currentRawReasoning) closeCurrentRawReasoning();
+ flushHiddenRawReasoning();
+ if (currentToolCall) closeCurrentToolCall();
budget?.chargeRetained(bytesOf(event.data), { kind: "reasoning" });
pendingRedacted.push(event.data);
+ // A redacted block is complete at content_block_start. Emit it here,
+ // not with a later thinking block or after a tool call at turn end.
+ flushHiddenReasoningEnvelope();
break;
}
case "kiro_redacted_reasoning": {
@@ -1816,6 +1829,9 @@ function buildResponseJSONWithBudget(
if (budget) releaseTranslatedEvent(e, budget);
continue;
}
+ if (batchSignature !== undefined && e.type !== "thinking_signature" && e.type !== "heartbeat") {
+ flushSummaryReasoning();
+ }
switch (e.type) {
case "assistant_boundary":
flushText("commentary");
@@ -1860,19 +1876,23 @@ function buildResponseJSONWithBudget(
}
break;
case "thinking_signature":
- // End of the current thinking block — flush it WITH the signature envelope so the
- // block/signature pairing survives multi-block turns.
+ // Like streaming, retain the latest signature update until the next semantic
+ // event. Flushing every update would manufacture signature-only siblings.
batchSignatureBytes = replaceBatchRetainedString(batchSignatureBytes, e.signature, "reasoning");
batchSignature = e.signature;
- flushSummaryReasoning();
break;
case "redacted_thinking":
+ flushText("commentary");
+ flushSummaryReasoning();
+ flushRawReasoning();
+ flushToolCall();
{
const dataBytes = bytesOf(e.data);
budget?.chargeRetained(dataBytes, { kind: "reasoning" });
batchRedactedBytes += dataBytes;
}
batchRedacted.push(e.data);
+ flushSummaryReasoning();
break;
case "kiro_redacted_reasoning":
// Stash only — pushed after the trailing flushes. One blob per turn, so last wins.
diff --git a/src/claude/inbound.ts b/src/claude/inbound.ts
index 3ac4731385..5e876ca6cb 100644
--- a/src/claude/inbound.ts
+++ b/src/claude/inbound.ts
@@ -4,8 +4,8 @@
* Design (devlog/260711_claude_inbound/010, 003_evidence.md):
* - translate-and-replay: the produced body MUST pass the real responsesRequestSchema
* parse so routing/OAuth/pool/failover are inherited unchanged.
- * - thinking/redacted_thinking blocks on replay are DROPPED (v1 policy) — routed
- * providers carry reasoning in Responses items/ocxr1 envelopes instead.
+ * - thinking/redacted_thinking replay is preserved in Responses reasoning items;
+ * signatures and redacted payloads travel in bounded ocxr1 envelopes.
* - thinking.budget_tokens is NEVER forwarded raw; it maps to an effort tier.
* - top_k is accepted and silently dropped (no Responses equivalent, CCR parity).
*/
@@ -17,6 +17,7 @@ export { resolveInboundModel, effortForThinkingBudget, effortFromOutputConfig, e
import { AnthropicRequestError, isRec, type Rec } from "./inbound-records";
import { resolveInboundModel, effortForThinkingBudget, effortFromOutputConfig, formatFromOutputConfig } from "./inbound-model-options";
import { systemToInstructions, toolsToResponses, toolChoiceToResponses } from "./inbound-content-options";
+import { decodeReasoningEnvelope, encodeReasoningEnvelope, OCX_REASONING_PREFIX } from "../responses/reasoning-envelope";
@@ -234,9 +235,26 @@ function assistantMessageToItems(content: unknown, input: Rec[]): void {
input.push({ type: "function_call", call_id: raw.id, name: raw.name, arguments: JSON.stringify(raw.input ?? {}) });
break;
}
- case "thinking":
- case "redacted_thinking":
- break; // v1 policy: dropped on replay (003 evidence — safe for routed providers)
+ case "thinking": {
+ flush();
+ const thinking = typeof raw.thinking === "string" ? raw.thinking : "";
+ const signature = typeof raw.signature === "string" ? raw.signature : "";
+ if (signature.startsWith(OCX_REASONING_PREFIX)) {
+ const owned = decodeReasoningEnvelope(signature);
+ if (!owned) throw new AnthropicRequestError("malformed ocxr1 reasoning signature");
+ if (Object.hasOwn(owned, "sig")) throw new AnthropicRequestError("OpenCodex reasoning continuity cannot be replayed as an Anthropic signature");
+ }
+ const encrypted = signature.length === 0 ? undefined : signature.startsWith(OCX_REASONING_PREFIX) ? signature : encodeReasoningEnvelope({ sig: signature });
+ if (thinking.length === 0 && !encrypted) break;
+ input.push({ type: "reasoning", id: `rs_${crypto.randomUUID().replace(/-/g, "")}`, summary: thinking.length > 0 ? [{ type: "summary_text", text: thinking }] : [], ...(encrypted ? { encrypted_content: encrypted } : {}) });
+ break;
+ }
+ case "redacted_thinking": {
+ flush();
+ const data = typeof raw.data === "string" ? raw.data : "";
+ if (data.length > 0) input.push({ type: "reasoning", id: `rs_${crypto.randomUUID().replace(/-/g, "")}`, summary: [], encrypted_content: encodeReasoningEnvelope({ red: [data] }) });
+ break;
+ }
default:
break;
}
diff --git a/src/claude/outbound.ts b/src/claude/outbound.ts
index 48bb06c15a..ac06afac2d 100644
--- a/src/claude/outbound.ts
+++ b/src/claude/outbound.ts
@@ -5,8 +5,8 @@
* - Transport-only `ping` events may appear at any point, including before
* message_start. Semantic framing stays message_start ->
* (content_block_start -> deltas -> content_block_stop)* -> message_delta -> message_stop.
- * - thinking blocks get thinking_delta(s) then ONE synthetic signature_delta just
- * before content_block_stop (CCR precedent: Claude Code does not verify signatures).
+ * - thinking blocks get thinking_delta(s), then one signature_delta containing the
+ * genuine replay signature or a bounded ocxr1 fallback envelope.
* - message_delta.usage is cumulative; message_start embeds a full message snapshot.
* - errors: {type:"error", error:{type,message}}; may arrive mid-stream after HTTP 200.
*/
@@ -20,6 +20,7 @@ import {
type TranslatorBudget,
} from "../lib/translator-budget";
import { sseFieldOffset, sseFieldValue } from "../lib/sse-decoder";
+import { decodeReasoningEnvelope, encodeReasoningEnvelope } from "../responses/reasoning-envelope";
type Rec = Record;
@@ -214,6 +215,9 @@ interface OpenBlock {
callId?: string;
/** Last fixed-size reasoning identity (item + summary/content index) seen by this block. */
reasoningPartKey?: string;
+ thinkingBuf?: string;
+ thinkingBufBytes?: number;
+ reasoningSig?: string;
}
/** Streaming: Responses SSE bytes -> Anthropic Messages SSE bytes. */
@@ -230,6 +234,9 @@ export function responsesSseToAnthropicSse(
let bufferBytes = 0;
let started = false;
let terminated = false;
+ // Starting termination can still throw while closing a block or emitting its
+ // terminal frame. Only a delivered terminal forbids the bounded overflow error.
+ let terminalDelivered = false;
let cancelled = false;
let blockIndex = 0;
let open: OpenBlock | null = null;
@@ -253,6 +260,11 @@ export function responsesSseToAnthropicSse(
const bytes = queuedLiveFrameBytes.shift();
if (bytes !== undefined) translatorBudget.releaseRetained(bytes, { kind: "live_transient" });
};
+ const releaseThinkingBuffer = (block: OpenBlock | null | undefined) => {
+ if (block?.kind !== "thinking") return;
+ translatorBudget.releaseRetained(block.thinkingBufBytes ?? 0, { kind: "reasoning" });
+ block.thinkingBufBytes = 0;
+ };
return new ReadableStream({
start(controller) {
@@ -296,13 +308,14 @@ export function responsesSseToAnthropicSse(
open.webSearchArgsEmitted = true;
}
if (open.kind === "thinking") {
- // Synthetic signature: Claude Code accepts it (003 E6); inbound drops replays anyway.
+ const signature = open.reasoningSig ?? encodeReasoningEnvelope({ txt: open.thinkingBuf ?? "" });
emit("content_block_delta", {
type: "content_block_delta", index: open.index,
- delta: { type: "signature_delta", signature: `ocx${Date.now()}` },
+ delta: { type: "signature_delta", signature },
});
}
emit("content_block_stop", { type: "content_block_stop", index: open.index });
+ releaseThinkingBuffer(open);
if (open.callId) translatorBudget.closeCall(open.callId);
open = null;
};
@@ -315,7 +328,7 @@ export function responsesSseToAnthropicSse(
? { type: "text", text: "" }
: { type: "thinking", thinking: "", signature: "" };
emit("content_block_start", { type: "content_block_start", index, content_block: contentBlock });
- open = { kind, index };
+ open = { kind, index, thinkingBuf: "", thinkingBufBytes: 0 };
};
const finish = (stopReason: string, usage: unknown) => {
if (terminated) return;
@@ -328,6 +341,7 @@ export function responsesSseToAnthropicSse(
usage: anthropicUsage(usage, webSearchRequests),
});
emit("message_stop", { type: "message_stop" });
+ terminalDelivered = true;
};
// upstreamDerived: transient upstream statuses become overloaded_error so the
// Anthropic-SDK client retries with backoff; proxy-internal exceptions stay
@@ -336,11 +350,15 @@ export function responsesSseToAnthropicSse(
// resets reach the reader catch (no failed-tail relay) and stay api_error —
// same as today, deliberate residual.
const fail = (status: number, message: string, upstreamDerived = false, code?: string) => {
- if (terminated) return;
+ // finish/fail sets terminated before closeOpenBlock. A closure-time
+ // allocation failure must still emit one error, without retrying closure.
+ if (terminated && (code !== "translation_buffer_limit" || terminalDelivered)) return;
terminated = true;
if (code === "translation_buffer_limit") {
+ releaseThinkingBuffer(open);
if (open?.callId) translatorBudget.closeCall(open.callId);
open = null;
+ terminalDelivered = true;
// No normal close frames are valid after overflow. Emit exactly one bounded
// typed terminal without consulting the exhausted budget.
controller.enqueue(encoder.encode(sseFrame("error", anthropicErrorBody(
@@ -357,10 +375,12 @@ export function responsesSseToAnthropicSse(
// Do not manufacture message_start before the terminal error. Earlier transport-only
// pings remain valid and do not turn the failure into a partial message.
emit("error", anthropicErrorBody(status, message, type, code));
+ terminalDelivered = true;
return;
}
closeOpenBlock();
emit("error", anthropicErrorBody(status, message, type, code));
+ terminalDelivered = true;
};
const handleFrame = (eventName: string, data: Rec) => {
@@ -374,8 +394,10 @@ export function responsesSseToAnthropicSse(
case "response.output_text.delta": {
if (typeof data.delta !== "string" || data.delta.length === 0) break;
ensureBlock("text");
+ const active = open;
+ if (!active || active.kind !== "text") break;
emit("content_block_delta", {
- type: "content_block_delta", index: open!.index,
+ type: "content_block_delta", index: active.index,
delta: { type: "text_delta", text: data.delta },
});
break;
@@ -384,6 +406,8 @@ export function responsesSseToAnthropicSse(
case "response.reasoning_text.delta": {
if (typeof data.delta !== "string" || data.delta.length === 0) break;
ensureBlock("thinking");
+ const active = open;
+ if (!active || active.kind !== "thinking") break;
// The JSON path joins reasoning summary/content parts with "\n\n"
// (responsesJsonToAnthropicMessage); mirror that at part and item boundaries
// so multi-part summaries do not glue into one run-on paragraph. Frames
@@ -395,15 +419,32 @@ export function responsesSseToAnthropicSse(
// components while retaining item and part equality, rather than dropping item_id and
// accidentally joining distinct malformed reasoning items.
const partKey = `${boundedReasoningIdentity(data.item_id)}:${slot}`;
- if (open!.reasoningPartKey !== undefined && open!.reasoningPartKey !== partKey) {
+ const needsPartSeparator = active.reasoningPartKey !== undefined
+ && active.reasoningPartKey !== partKey;
+ const appended = `${needsPartSeparator ? "\n\n" : ""}${data.delta}`;
+ const previous = active.thinkingBuf ?? "";
+ const previousBytes = active.thinkingBufBytes ?? 0;
+ const nextBytes = appendedUtf8Bytes(previous, previousBytes, appended);
+ const scope = { kind: "reasoning" } as const;
+ const reservation = translatorBudget.reserveTransient(nextBytes, scope);
+ try {
+ active.thinkingBuf = previous + appended;
+ active.thinkingBufBytes = nextBytes;
+ reservation.commitRetained();
+ translatorBudget.releaseRetained(previousBytes, scope);
+ } catch (error) {
+ reservation.release();
+ throw error;
+ }
+ if (needsPartSeparator) {
emit("content_block_delta", {
- type: "content_block_delta", index: open!.index,
+ type: "content_block_delta", index: active.index,
delta: { type: "thinking_delta", thinking: "\n\n" },
});
}
- open!.reasoningPartKey = partKey;
+ active.reasoningPartKey = partKey;
emit("content_block_delta", {
- type: "content_block_delta", index: open!.index,
+ type: "content_block_delta", index: active.index,
delta: { type: "thinking_delta", thinking: data.delta },
});
break;
@@ -499,10 +540,9 @@ export function responsesSseToAnthropicSse(
if (pair.completed) webSearchRequests++;
break;
}
- if (!open) break;
// Close the matching open block (message/reasoning items close implicitly on
// the next block; function_call items must close here so tool input parses).
- if (open.kind === "tool_use" && item.type === "function_call") {
+ if (open && open.kind === "tool_use" && item.type === "function_call") {
if (open.bufferWebSearchArgs && !open.webSearchArgsEmitted) {
const rawArgs = typeof item.arguments === "string" && item.arguments.length > 0
? item.arguments
@@ -518,8 +558,26 @@ export function responsesSseToAnthropicSse(
}
closeOpenBlock();
}
- else if (open.kind === "text" && item.type === "message") closeOpenBlock();
- else if (open.kind === "thinking" && item.type === "reasoning") closeOpenBlock();
+ else if (open && open.kind === "text" && item.type === "message") closeOpenBlock();
+ else if (item.type === "reasoning") {
+ const encrypted = typeof item.encrypted_content === "string" ? item.encrypted_content : "";
+ const env = encrypted ? decodeReasoningEnvelope(encrypted) : null;
+ const red = env?.red ?? [];
+ if (env?.sig && open?.kind !== "thinking") ensureBlock("thinking");
+ if (open?.kind === "thinking") {
+ if (env?.sig) open.reasoningSig = env.sig;
+ closeOpenBlock();
+ }
+ if (red.length > 0) {
+ ensureStarted();
+ closeOpenBlock();
+ }
+ for (const data of red) {
+ const idx = blockIndex++;
+ emit("content_block_start", { type: "content_block_start", index: idx, content_block: { type: "redacted_thinking", data } });
+ emit("content_block_stop", { type: "content_block_stop", index: idx });
+ }
+ }
break;
}
case "response.completed": {
@@ -704,6 +762,7 @@ export function responsesSseToAnthropicSse(
fail(413, "upstream translation buffer exceeded the safe limit", false, "translation_buffer_limit");
} else fail(500, err instanceof Error ? err.message : String(err));
} finally {
+ releaseThinkingBuffer(open);
translatorBudget.releaseRetained(bufferBytes, { kind: "live_transient" });
if (pingTimer !== undefined) clearInterval(pingTimer);
reader.releaseLock();
@@ -717,6 +776,7 @@ export function responsesSseToAnthropicSse(
cancel(reason) {
cancelled = true;
while (queuedLiveFrameBytes.length > 0) releaseDeliveredFrame();
+ releaseThinkingBuffer(open);
if (open?.callId) translatorBudget.closeCall(open.callId);
if (pingTimer !== undefined) clearInterval(pingTimer);
return reader?.cancel(reason);
@@ -756,8 +816,15 @@ export function responsesJsonToAnthropicMessage(json: unknown, model: string): R
if (isRec(s) && typeof s.text === "string" && s.text.length > 0) parts.push(s.text);
}
}
- if (parts.length > 0) {
- content.push({ type: "thinking", thinking: parts.join("\n\n"), signature: `ocx${Date.now()}` });
+ const encrypted = typeof raw.encrypted_content === "string" ? raw.encrypted_content : "";
+ const env = encrypted ? decodeReasoningEnvelope(encrypted) : null;
+ // Legacy combined envelopes place redacted blocks before the signed block,
+ // matching the Anthropic adapter. New bridge output uses separate items.
+ for (const data of env?.red ?? []) content.push({ type: "redacted_thinking", data });
+ // env.txt may be locally hidden text. Do not expose it here or manufacture
+ // a new signed continuity carrier; hidden-summary replay remains limited.
+ if (parts.length > 0 || env?.sig) {
+ content.push({ type: "thinking", thinking: parts.join("\n\n"), signature: env?.sig ?? encodeReasoningEnvelope({ txt: parts.join("\n\n") }) });
}
break;
}
@@ -923,9 +990,10 @@ export async function collectAnthropicMessage(
} finally {
reader.releaseLock();
}
- closeBlock();
-
+ // Error is authoritative. In particular, do not allocate another copy of an
+ // unfinished thinking block after the translator reported closure overflow.
if (error) return error;
+ closeBlock();
return {
id: `msg_${uuid()}`,
type: "message",
diff --git a/src/cli/capabilities.ts b/src/cli/capabilities.ts
index 1b5cfd6283..ff1f5fb9a2 100644
--- a/src/cli/capabilities.ts
+++ b/src/cli/capabilities.ts
@@ -148,7 +148,10 @@ export const CAPABILITIES: readonly Capability[] = [
summary: "Configured providers with connectivity and selected models.",
// Local config + PROVIDER_REGISTRY. Does not call GET /api/providers.
routes: [],
- flags: [{ name: "--json", value: "boolean", summary: "Emit the provider list as JSON." }],
+ flags: [
+ { name: "--json", value: "boolean", summary: "Emit the provider list as JSON." },
+ { name: "--jsonl", value: "boolean", summary: "Emit one configured provider per JSON line." },
+ ],
mutates: false,
json: "envelope",
details: ["Reads local config; drives no management API route."],
diff --git a/src/cli/dispatch.ts b/src/cli/dispatch.ts
index 6d018536c7..c884bb2e5d 100644
--- a/src/cli/dispatch.ts
+++ b/src/cli/dispatch.ts
@@ -403,7 +403,7 @@ const commandRunners: Record = {
},
config,
port: live.port,
- }, ["mcode", "pi"]));
+ }, ["mcode", "pi", "raycast"]));
} catch (error) {
console.warn(`Client integrations were not refreshed: ${error instanceof Error ? error.message : String(error)}`);
}
diff --git a/src/cli/doctor.ts b/src/cli/doctor.ts
index 1ab4fe9f1b..d7148530a0 100644
--- a/src/cli/doctor.ts
+++ b/src/cli/doctor.ts
@@ -1157,11 +1157,11 @@ export async function runDoctor(args: string[] = []): Promise {
// No extra probe -- findLiveProxy already carried the version back.
{
const { packageVersion } = await import("./help");
- const { computeVersionSkew } = await import("./version-skew");
+ const { computeVersionSkew, isConfirmedVersionMatch } = await import("./version-skew");
const skew = computeVersionSkew(packageVersion(), live?.version);
if (skew.skewed && skew.warning) {
console.log(`!! ${skew.warning}`);
- } else if (skew.proxyVersion !== null) {
+ } else if (isConfirmedVersionMatch(skew)) {
console.log(`ok ocx ${skew.cliVersion} matches the running proxy`);
}
}
diff --git a/src/cli/export-command.ts b/src/cli/export-command.ts
index c576435432..739889a026 100644
--- a/src/cli/export-command.ts
+++ b/src/cli/export-command.ts
@@ -172,17 +172,29 @@ export async function handleExportCommand(argv: string[], deps: ExportCommandDep
const spec = EXPORT_CLIENTS[client];
const root = await runtimeBaseUrl(deps);
- const rows = await runtimeRequest("/api/models", {}, { ...deps, baseUrl: root });
- if (!Array.isArray(rows)) {
- throw new RuntimeApiError("Management API returned an unexpected /api/models payload.", 502, rows);
+ let built: { document: unknown; text: string };
+ if (client === "raycast") {
+ // The dial address alone cannot distinguish a wildcard authenticated bind
+ // from loopback. Let the live server resolve its admission/listener policy;
+ // saved config can differ from the process serving this request.
+ const exported = await runtimeRequest<{
+ client: string; format: string; config: unknown; text: string;
+ }>("/api/client-config?client=raycast", {}, { ...deps, baseUrl: root });
+ if (!exported || exported.client !== "raycast" || exported.format !== "yaml"
+ || typeof exported.text !== "string" || exported.config === undefined) {
+ throw new RuntimeApiError("Management API returned an unexpected Raycast export payload.", 502, null);
+ }
+ built = { document: exported.config, text: exported.text };
+ } else {
+ const rows = await runtimeRequest("/api/models", {}, { ...deps, baseUrl: root });
+ if (!Array.isArray(rows)) {
+ throw new RuntimeApiError("Management API returned an unexpected /api/models payload.", 502, rows);
+ }
+ // Discovery can persist selection; preserve the existing exporters' flow.
+ const config = (deps.configImpl ?? loadConfig)();
+ const models = exportModelsFromProxyRows(rows, config);
+ built = buildClientConfigText(client, { baseUrl: proxyV1BaseUrl(root), models, config });
}
- // Discovery can persist pending -> ready selection. Read from the caller's
- // config source after the response, rather than filtering with a stale snapshot.
- const config = (deps.configImpl ?? loadConfig)();
- const models = exportModelsFromProxyRows(rows, config);
- // The text is the client's OWN format — YAML, TOML and JSON5 clients would
- // otherwise receive a JSON rendering their parser reads differently.
- const built = buildClientConfigText(client, { baseUrl: proxyV1BaseUrl(root), models, config });
const clientConfig = built.document;
const text = built.text;
diff --git a/src/cli/help.ts b/src/cli/help.ts
index 0b3652ab59..0cd6bec4dc 100644
--- a/src/cli/help.ts
+++ b/src/cli/help.ts
@@ -77,7 +77,7 @@ Usage:
ocx memory [--json] Alias of ocx observe memory
ocx api-key Alias of ocx access key
ocx access External API keys and endpoint information
- ocx export --client Print a client config wired to the running proxy (12 clients)
+ ocx export --client Print a client config wired to the running proxy (13 clients)
ocx integration client Enable, disable, inspect or roll back a client integration
ocx grok Grok Build model selection and apply
ocx system Runtime settings, startup, sync, OpenCodex updates, and Codex CLI inspection
diff --git a/src/cli/index.ts b/src/cli/index.ts
index 7b863630b9..663514a120 100755
--- a/src/cli/index.ts
+++ b/src/cli/index.ts
@@ -92,6 +92,15 @@ import {
grokSyncFailureMessage,
reconcileEnsureDesiredIntegrations,
} from "./ensure-desired-integrations";
+import { refreshOwnedCatalogIntegrations } from "../integrations/catalog-refresh";
+import { loadExportModels } from "../server/management/model-rows";
+
+import { removeOwnedConfigAfterDesktopCleanup } from "./uninstall-client-state";
+import { withProcessRuntimeProvenance } from "../lib/bun-runtime";
+import { selfLaunchArgv } from "../lib/self-launch-argv";
+import { initializeNodeLauncherContext } from "./launcher-context";
+import { createLocalAttestationSecret } from "../lib/local-management-attestation";
+import { MEMORY_DRAIN_RESTART_MS, REPLACEMENT_READY_TIMEOUT_MS } from "../lib/system-restart-contract";
/**
* A failed shell-hook reconcile is not cosmetic: a stale hook keeps sourcing
@@ -105,13 +114,25 @@ function reportShellHookFailure(result: { state: "installed" | "absent" | "faile
console.warn(" Check ~/.zshrc for the '# opencodex claude-env hook' block.");
}
-
-import { removeOwnedConfigAfterDesktopCleanup } from "./uninstall-client-state";
-import { withProcessRuntimeProvenance } from "../lib/bun-runtime";
-import { selfLaunchArgv } from "../lib/self-launch-argv";
-import { initializeNodeLauncherContext } from "./launcher-context";
-import { createLocalAttestationSecret } from "../lib/local-management-attestation";
-import { MEMORY_DRAIN_RESTART_MS, REPLACEMENT_READY_TIMEOUT_MS } from "../lib/system-restart-contract";
+async function refreshOwnedRaycastCatalog(
+ config: ReturnType,
+ port: number,
+): Promise {
+ try {
+ const outcomes = await refreshOwnedCatalogIntegrations({
+ models: () => loadExportModels(config),
+ config,
+ port,
+ }, ["raycast"]);
+ for (const outcome of outcomes) {
+ if (!outcome.ok) {
+ console.error(`⚠️ Raycast integration was not refreshed: ${outcome.reason}`);
+ }
+ }
+ } catch (error) {
+ console.error(`⚠️ Raycast integration was not refreshed: ${error instanceof Error ? error.message : String(error)}`);
+ }
+}
initializeNodeLauncherContext();
@@ -493,6 +514,7 @@ async function handleStart(options: { block?: boolean } = {}) {
},
);
if (!startupSync.ran) console.log(" Codex integration OFF; startup left Codex native.");
+ await refreshOwnedRaycastCatalog(config, port);
// #1046: one warning per startup, after BOTH writes. The server's cache
// invalidation happens first and the catalog sync second, so the mtime is only
// final here — and neither write site warns on its own, or a boot that hits
@@ -558,6 +580,9 @@ async function handleEnsure(options: { existingIsSuccess?: boolean } = {}): Prom
return null;
});
if (synced?.status === "skipped") console.log(" Codex integration OFF; startup left Codex native.");
+ // Do not refresh Raycast from saved config here: live bind/admission and
+ // secondary-listener settings may differ. Explicit sync or server startup
+ // owns catalog refresh; ensure must not overwrite a working destination.
// Ensure env file exists for already-running proxy (may have been deleted or pre-dates this feature).
const systemEnv = await injectSystemEnv(live.port, config).catch(() => ({ injected: false }));
reportShellHookFailure(reconcileShellHook(systemEnv.injected));
@@ -602,6 +627,8 @@ async function handleEnsure(options: { existingIsSuccess?: boolean } = {}): Prom
return null;
});
if (synced?.status === "skipped") console.log(" Codex integration OFF; startup left Codex native.");
+ // The child performs Raycast refresh with its actual startup config. The
+ // parent's pre-spawn snapshot is not authoritative for a client-file write.
// The child opens /healthz before its best-effort roster reconcile. Await the same idempotent
// operation in the parent so `ocx ensure` cannot report success while stale ocx-*.md files are
// still observable. Always use the live port, including fallback-port starts.
diff --git a/src/cli/integrations.ts b/src/cli/integrations.ts
index bcb87d5d18..89ab3ee046 100644
--- a/src/cli/integrations.ts
+++ b/src/cli/integrations.ts
@@ -161,6 +161,39 @@ export async function handleGrokCommand(argv: string[], deps: RuntimeApiDeps = {
});
}
+/** The Raycast-only block the single-client route adds; see IntegrationStateEnvelope. */
+interface RaycastStatusBlock {
+ plan: string;
+ aiDirPresent: boolean;
+}
+
+function raycastBlock(result: unknown): RaycastStatusBlock | null {
+ if (!result || typeof result !== "object") return null;
+ const block = (result as { raycast?: unknown }).raycast;
+ if (!block || typeof block !== "object") return null;
+ const { plan, aiDirPresent } = block as Partial;
+ return typeof plan === "string" && typeof aiDirPresent === "boolean" ? { plan, aiDirPresent } : null;
+}
+
+/**
+ * Text view of one client's status.
+ *
+ * Raycast carries an extra block, and the generic summary would print it as
+ * three dotted keys. A `current` file that Raycast ignores for want of a Pro
+ * subscription is the one fact this view must not bury, so `plan` gets its own
+ * line and a missing `ai` folder gets the instruction that creates it.
+ */
+function singleClientStatusLines(result: unknown): string[] {
+ const raycast = raycastBlock(result);
+ if (!raycast) return summaryLines(result);
+ const rest = Object.fromEntries(Object.entries(result as Record).filter(([key]) => key !== "raycast"));
+ const lines = [...summaryLines(rest), `plan: ${raycast.plan}`];
+ if (!raycast.aiDirPresent) {
+ lines.push('Open Raycast → Settings → AI → "Reveal Providers Config" once so the ai folder exists.');
+ }
+ return lines;
+}
+
/**
* The headless half of the client-integration toggle.
*
@@ -197,7 +230,7 @@ export async function handleClientIntegrationCommand(
: [String((result as { error?: string }).error ?? "No Aside profiles found.")]
: rows
? rows.map(row => `${String(row.clientId)}: ${String(row.state)}${row.installed ? "" : " (not installed)"}`)
- : summaryLines(result));
+ : singleClientStatusLines(result));
return;
}
diff --git a/src/cli/provider.ts b/src/cli/provider.ts
index 55c654d8d7..47f23fee62 100644
--- a/src/cli/provider.ts
+++ b/src/cli/provider.ts
@@ -79,26 +79,37 @@ function validateAndSave(config: ReturnType): void {
function handleList(args: string[]): void {
const wantsJson = consumeFlag(args, "--json");
- rejectUnknownArgs(args, "Usage: ocx provider list [--json]");
+ const wantsJsonl = consumeFlag(args, "--jsonl");
+ rejectUnknownArgs(args, "Usage: ocx provider list [--json|--jsonl]");
+
+ if (wantsJson && wantsJsonl) {
+ console.error("Use only one of --json or --jsonl.");
+ process.exit(1);
+ }
const config = loadConfig();
const configured = Object.keys(config.providers);
+ const entries = configured.map(name => {
+ const prov = config.providers[name];
+ const registryEntry = getProviderRegistryEntry(name);
+ return {
+ name,
+ adapter: prov.adapter,
+ baseUrl: prov.baseUrl,
+ authMode: prov.authMode ?? "key",
+ defaultModel: prov.defaultModel ?? null,
+ isDefault: name === config.defaultProvider,
+ source: registryEntry ? "registry" : "custom",
+ models: prov.models ?? [],
+ };
+ });
+
+ if (wantsJsonl) {
+ for (const entry of entries) console.log(JSON.stringify(entry));
+ return;
+ }
if (wantsJson) {
- const entries = configured.map(name => {
- const prov = config.providers[name];
- const registryEntry = getProviderRegistryEntry(name);
- return {
- name,
- adapter: prov.adapter,
- baseUrl: prov.baseUrl,
- authMode: prov.authMode ?? "key",
- defaultModel: prov.defaultModel ?? null,
- isDefault: name === config.defaultProvider,
- source: registryEntry ? "registry" : "custom",
- models: prov.models ?? [],
- };
- });
console.log(JSON.stringify({ configured: entries, registryCount: PROVIDER_REGISTRY.length }, null, 2));
return;
}
@@ -444,6 +455,7 @@ Subcommands:
Examples:
ocx provider list
+ ocx provider list --jsonl
ocx provider add anthropic --api-key sk-ant-...
ocx provider add my-ollama --adapter openai-chat --base-url http://localhost:11434/v1
ocx provider show anthropic --json
diff --git a/src/cli/registry.ts b/src/cli/registry.ts
index 00ff25ed52..467a0f7971 100644
--- a/src/cli/registry.ts
+++ b/src/cli/registry.ts
@@ -287,8 +287,8 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
{ name: "api-key", usage: "ocx api-key ...", summary: "Alias of ocx access key." },
{
name: "export",
- usage: "ocx export --client [--json] [--out ] [--force]",
- summary: "Print a client config (OpenCode, Pi, OMP, Hermes, OpenClaw, Kimi Code, Gajae Code, DeepSeek Harness, MiniMax Code, ZCode, Prime Agent, Aside) wired to the running proxy.",
+ usage: "ocx export --client [--json] [--out ] [--force]",
+ summary: "Print a client config (OpenCode, Pi, OMP, Hermes, OpenClaw, Kimi Code, Gajae Code, DeepSeek Harness, MiniMax Code, ZCode, Prime Agent, Aside, Raycast) wired to the running proxy.",
details: [
"--json prints the generated document as JSON on stdout; use --out for the client's native format.",
"--out