- {ProviderIcon ?
: null}
+
{providerLabel}
diff --git a/apps/web/src/components/chat/ModelPickerContent.tsx b/apps/web/src/components/chat/ModelPickerContent.tsx
index 57a04b1a2f24..70181947bc4a 100644
--- a/apps/web/src/components/chat/ModelPickerContent.tsx
+++ b/apps/web/src/components/chat/ModelPickerContent.tsx
@@ -57,6 +57,8 @@ type ModelPickerItem = {
driverKind: ProviderDriverKind;
instanceDisplayName: string;
instanceAccentColor?: string | undefined;
+ acpRegistryAgentId?: string | undefined;
+ acpRegistryIconUrl?: string | undefined;
continuationGroupKey?: string | undefined;
isLegacy?: boolean | undefined;
isUnavailable?: boolean | undefined;
@@ -387,6 +389,8 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
driverKind: entry.driverKind,
instanceDisplayName: entry.displayName,
...(entry.accentColor ? { instanceAccentColor: entry.accentColor } : {}),
+ ...(entry.acpRegistryAgentId ? { acpRegistryAgentId: entry.acpRegistryAgentId } : {}),
+ ...(entry.acpRegistryIconUrl ? { acpRegistryIconUrl: entry.acpRegistryIconUrl } : {}),
...(entry.continuationGroupKey
? { continuationGroupKey: entry.continuationGroupKey }
: {}),
@@ -987,6 +991,8 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
driverKind={model.driverKind}
providerDisplayName={model.instanceDisplayName}
providerAccentColor={model.instanceAccentColor}
+ acpRegistryAgentId={model.acpRegistryAgentId}
+ acpRegistryIconUrl={model.acpRegistryIconUrl}
isFavorite={favoritesSet.has(
providerModelKey(model.instanceId, model.slug),
)}
diff --git a/apps/web/src/components/chat/ModelPickerSidebar.tsx b/apps/web/src/components/chat/ModelPickerSidebar.tsx
index d043c053a073..6d4710205435 100644
--- a/apps/web/src/components/chat/ModelPickerSidebar.tsx
+++ b/apps/web/src/components/chat/ModelPickerSidebar.tsx
@@ -200,6 +200,8 @@ export const ModelPickerSidebar = memo(function ModelPickerSidebar(props: {
driverKind={entry.driverKind}
displayName={entry.displayName}
accentColor={entry.accentColor}
+ acpRegistryAgentId={entry.acpRegistryAgentId}
+ acpRegistryIconUrl={entry.acpRegistryIconUrl}
showBadge={showInstanceBadge}
className="size-6 z-30"
iconClassName="size-5"
diff --git a/apps/web/src/components/chat/ProviderInstanceIcon.test.ts b/apps/web/src/components/chat/ProviderInstanceIcon.test.ts
new file mode 100644
index 000000000000..edc68c599fb0
--- /dev/null
+++ b/apps/web/src/components/chat/ProviderInstanceIcon.test.ts
@@ -0,0 +1,32 @@
+import { ProviderDriverKind } from "@t3tools/contracts";
+import { describe, expect, it } from "vite-plus/test";
+
+import { resolveProviderInstanceAcpRegistryIconUrl } from "./ProviderInstanceIcon";
+
+describe("resolveProviderInstanceAcpRegistryIconUrl", () => {
+ it("uses allowlisted catalog metadata and rejects untrusted overrides", () => {
+ expect(
+ resolveProviderInstanceAcpRegistryIconUrl({
+ driverKind: ProviderDriverKind.make("acpRegistry"),
+ agentId: "kilo",
+ iconUrl: "https://cdn.agentclientprotocol.com/registry/icons/kilo.svg",
+ }),
+ ).toBe("https://cdn.agentclientprotocol.com/registry/icons/kilo.svg");
+ expect(
+ resolveProviderInstanceAcpRegistryIconUrl({
+ driverKind: ProviderDriverKind.make("acpRegistry"),
+ agentId: "generic-agent",
+ iconUrl: "https://example.com/not-official.svg",
+ }),
+ ).toBe("https://cdn.agentclientprotocol.com/registry/v1/latest/generic-agent.svg");
+ });
+
+ it("does not resolve registry icons for other provider drivers", () => {
+ expect(
+ resolveProviderInstanceAcpRegistryIconUrl({
+ driverKind: ProviderDriverKind.make("codex"),
+ agentId: "kilo",
+ }),
+ ).toBeNull();
+ });
+});
diff --git a/apps/web/src/components/chat/ProviderInstanceIcon.tsx b/apps/web/src/components/chat/ProviderInstanceIcon.tsx
index 6c36087a1e29..05e2a0a967d5 100644
--- a/apps/web/src/components/chat/ProviderInstanceIcon.tsx
+++ b/apps/web/src/components/chat/ProviderInstanceIcon.tsx
@@ -4,13 +4,33 @@ import { providerInstanceInitials } from "@t3tools/client-runtime/state/provider
import { PROVIDER_ICON_BY_PROVIDER } from "./providerIconUtils";
import { cn } from "~/lib/utils";
+import {
+ AcpRegistryAgentIcon,
+ officialAcpRegistryIconUrlForAgentId,
+ resolveOfficialAcpRegistryIconUrl,
+} from "../settings/AcpRegistryIcon";
export { providerInstanceInitials };
+/** Registry agents show their own official glyph, from the catalog or derived from the agent id. */
+export function resolveProviderInstanceAcpRegistryIconUrl(input: {
+ readonly driverKind: ProviderDriverKind;
+ readonly agentId?: string | undefined;
+ readonly iconUrl?: string | undefined;
+}): string | null {
+ if (input.driverKind !== "acpRegistry") return null;
+ return (
+ resolveOfficialAcpRegistryIconUrl(input.iconUrl ?? null) ??
+ officialAcpRegistryIconUrlForAgentId(input.agentId?.trim() || null)
+ );
+}
+
export const ProviderInstanceIcon = memo(function ProviderInstanceIcon(props: {
driverKind: ProviderDriverKind;
displayName: string;
accentColor?: string | undefined;
+ acpRegistryAgentId?: string | undefined;
+ acpRegistryIconUrl?: string | undefined;
showBadge?: boolean;
badgeContent?: "initials" | "none";
className?: string;
@@ -25,6 +45,7 @@ export const ProviderInstanceIcon = memo(function ProviderInstanceIcon(props: {
? ({ "--provider-accent": props.accentColor } as CSSProperties)
: undefined;
const badgeContent = props.badgeContent ?? "initials";
+ const isAcpRegistry = props.driverKind === "acpRegistry";
return (
- {Icon ? (
+ {isAcpRegistry ? (
+
+ ) : Icon ? (
) : (
diff --git a/apps/web/src/components/chat/ProviderModelPicker.tsx b/apps/web/src/components/chat/ProviderModelPicker.tsx
index fbc178965378..b8d5e0cf9d8e 100644
--- a/apps/web/src/components/chat/ProviderModelPicker.tsx
+++ b/apps/web/src/components/chat/ProviderModelPicker.tsx
@@ -245,6 +245,8 @@ export const ProviderModelPicker = memo(function ProviderModelPicker(props: {
driverKind={activeEntry.driverKind}
displayName={activeEntry.displayName}
accentColor={activeEntry.accentColor}
+ acpRegistryAgentId={activeEntry.acpRegistryAgentId}
+ acpRegistryIconUrl={activeEntry.acpRegistryIconUrl}
showBadge={showInstanceBadge}
className="size-4"
iconClassName={cn("size-4", props.activeProviderIconClassName)}
diff --git a/apps/web/src/components/chat/providerIconUtils.ts b/apps/web/src/components/chat/providerIconUtils.ts
index db0e5ca222f3..a9ebfebfb9b5 100644
--- a/apps/web/src/components/chat/providerIconUtils.ts
+++ b/apps/web/src/components/chat/providerIconUtils.ts
@@ -1,5 +1,6 @@
import { ProviderDriverKind } from "@t3tools/contracts";
import {
+ ACPRegistryIcon,
AntigravityIcon,
ClaudeAI,
CursorIcon,
@@ -16,6 +17,7 @@ export const PROVIDER_ICON_BY_PROVIDER: Partial
[ProviderDriverKind.make("cursor")]: CursorIcon,
[ProviderDriverKind.make("grok")]: GrokIcon,
[ProviderDriverKind.make("antigravity")]: AntigravityIcon,
+ [ProviderDriverKind.make("acpRegistry")]: ACPRegistryIcon,
};
export type ModelEsque = {
diff --git a/apps/web/src/components/settings/AcpRegistryIcon.test.ts b/apps/web/src/components/settings/AcpRegistryIcon.test.ts
new file mode 100644
index 000000000000..39e65f644c7d
--- /dev/null
+++ b/apps/web/src/components/settings/AcpRegistryIcon.test.ts
@@ -0,0 +1,206 @@
+import type { ReactElement } from "react";
+import { beforeEach, describe, expect, it, vi } from "vite-plus/test";
+
+import { visitElements } from "../../test/reactElementTree";
+import { reactHookHarness as hooks } from "../../test/reactHookHarness";
+
+vi.mock("react", async (importOriginal) => {
+ const actual = await importOriginal();
+ const { reactHookHarness } = await import("../../test/reactHookHarness");
+ return {
+ ...actual,
+ useEffect: (effect: () => void | (() => void)) => effect(),
+ useState: reactHookHarness.useState,
+ useId: () => "acp-icon-test-filter",
+ };
+});
+
+import {
+ AcpRegistryAgentIcon,
+ loadCachedAcpRegistryIcon,
+ officialAcpRegistryIconUrlForAgentId,
+ resolveOfficialAcpRegistryIconUrl,
+} from "./AcpRegistryIcon";
+
+describe("ACP Registry icon cache", () => {
+ const stored = new Map();
+ const match = vi.fn(async (url: string) => stored.get(url)?.clone());
+ const put = vi.fn(async (url: string, response: Response) => {
+ stored.set(url, response.clone());
+ });
+ const fetchIcon = vi.fn();
+
+ beforeEach(() => {
+ hooks.reset();
+ stored.clear();
+ match.mockClear();
+ put.mockClear();
+ fetchIcon.mockReset();
+ vi.stubGlobal("caches", { open: vi.fn(async () => ({ match, put })) });
+ vi.stubGlobal("fetch", fetchIcon);
+ });
+
+ it("single-flights the first fetch and serves later reads from persistent cache", async () => {
+ const url = "https://cdn.agentclientprotocol.com/registry/icons/cache-test.svg";
+ fetchIcon.mockResolvedValue(
+ new Response("", {
+ status: 200,
+ headers: { "content-type": "image/svg+xml" },
+ }),
+ );
+
+ const [first, concurrent] = await Promise.all([
+ loadCachedAcpRegistryIcon(url),
+ loadCachedAcpRegistryIcon(url),
+ ]);
+ const cached = await loadCachedAcpRegistryIcon(url);
+
+ expect(first.type).toBe("image/svg+xml");
+ expect(concurrent.size).toBe(first.size);
+ expect(cached.size).toBe(first.size);
+ expect(fetchIcon).toHaveBeenCalledOnce();
+ expect(put).toHaveBeenCalledOnce();
+ });
+
+ it("rejects oversized image responses before caching", async () => {
+ const url = "https://cdn.agentclientprotocol.com/registry/icons/oversized.svg";
+ fetchIcon.mockResolvedValue(
+ new Response("too large", {
+ status: 200,
+ headers: {
+ "content-length": String(513 * 1_024),
+ "content-type": "image/svg+xml",
+ },
+ }),
+ );
+
+ await expect(loadCachedAcpRegistryIcon(url)).rejects.toThrow("too large");
+ expect(put).not.toHaveBeenCalled();
+ });
+
+ it("falls back to the network when CacheStorage cannot be opened", async () => {
+ const url = "https://cdn.agentclientprotocol.com/registry/v1/latest/kilo.svg";
+ vi.stubGlobal("caches", {
+ open: vi.fn(async () => {
+ throw new Error("CacheStorage unavailable");
+ }),
+ });
+ fetchIcon.mockResolvedValue(
+ new Response("", {
+ status: 200,
+ headers: { "content-type": "image/svg+xml" },
+ }),
+ );
+
+ await expect(loadCachedAcpRegistryIcon(url)).resolves.toMatchObject({
+ type: "image/svg+xml",
+ });
+ expect(fetchIcon).toHaveBeenCalledWith(url, {
+ credentials: "omit",
+ redirect: "error",
+ referrerPolicy: "no-referrer",
+ });
+ });
+
+ it("accepts only credential-free HTTPS URLs on the official CDN", () => {
+ expect(
+ resolveOfficialAcpRegistryIconUrl(
+ "https://cdn.agentclientprotocol.com/registry/icons/gemini.png",
+ ),
+ ).toBe("https://cdn.agentclientprotocol.com/registry/icons/gemini.png");
+ expect(
+ resolveOfficialAcpRegistryIconUrl("http://cdn.agentclientprotocol.com/icon.png"),
+ ).toBeNull();
+ expect(
+ resolveOfficialAcpRegistryIconUrl("https://cdn.agentclientprotocol.com.evil/icon.png"),
+ ).toBeNull();
+ expect(
+ resolveOfficialAcpRegistryIconUrl("https://user@cdn.agentclientprotocol.com/icon.png"),
+ ).toBeNull();
+ expect(
+ resolveOfficialAcpRegistryIconUrl("https://cdn.agentclientprotocol.com:8443/icon.png"),
+ ).toBeNull();
+ expect(officialAcpRegistryIconUrlForAgentId("kilo")).toBe(
+ "https://cdn.agentclientprotocol.com/registry/v1/latest/kilo.svg",
+ );
+ expect(officialAcpRegistryIconUrlForAgentId("../kilo")).toBeNull();
+ });
+
+ it("falls back to the raw allowlisted CDN URL when the validating fetch is blocked", async () => {
+ const url = "https://cdn.agentclientprotocol.com/registry/v1/latest/kilo.svg";
+ // The official CDN serves no CORS headers, so the fetch can reject even
+ // though native ![]()
loading works.
+ fetchIcon.mockRejectedValue(new TypeError("Failed to fetch"));
+ hooks.beginRender();
+ AcpRegistryAgentIcon({ icon: url });
+
+ await new Promise((resolve) => setTimeout(resolve, 0));
+ hooks.beginRender();
+ const tree = AcpRegistryAgentIcon({ icon: url }) as ReactElement>;
+ const image = visitElements(tree, (element) => element.type === "img");
+ expect(image?.props).toMatchObject({ src: url, referrerPolicy: "no-referrer" });
+ expect(
+ visitElements(tree, (element) => element.props["data-slot"] === "acp-icon-fallback"),
+ ).not.toBeNull();
+ });
+
+ it("renders only the validated blob object URL and keeps the fallback until load", async () => {
+ const url = "https://cdn.agentclientprotocol.com/registry/v1/latest/kilo.svg";
+ const objectUrl = "blob:t3/kilo-icon";
+ Object.assign(URL, {
+ createObjectURL: vi.fn(() => objectUrl),
+ revokeObjectURL: vi.fn(),
+ });
+ fetchIcon.mockResolvedValue(
+ new Response("", {
+ status: 200,
+ headers: { "content-type": "image/svg+xml" },
+ }),
+ );
+ hooks.beginRender();
+ const validating = AcpRegistryAgentIcon({ icon: url }) as ReactElement>;
+
+ // The raw CDN URL is never rendered; only the fallback shows while the
+ // blob is fetched and validated.
+ expect(visitElements(validating, (element) => element.type === "img")).toBeNull();
+ expect(
+ visitElements(validating, (element) => element.props["data-slot"] === "acp-icon-fallback"),
+ ).not.toBeNull();
+
+ await new Promise((resolve) => setTimeout(resolve, 0));
+ hooks.beginRender();
+ const loading = AcpRegistryAgentIcon({ icon: url }) as ReactElement>;
+ const loadingImage = visitElements(loading, (element) => element.type === "img");
+
+ expect(loadingImage?.props).toMatchObject({
+ src: objectUrl,
+ alt: "",
+ decoding: "async",
+ referrerPolicy: "no-referrer",
+ });
+ expect(loadingImage?.props.className).not.toContain("dark:invert");
+ expect(loadingImage?.props.className).toContain("invisible");
+ expect(
+ visitElements(loading, (element) => element.props["data-slot"] === "acp-icon-fallback"),
+ ).not.toBeNull();
+
+ (loadingImage?.props.onLoad as (() => void) | undefined)?.();
+ hooks.beginRender();
+ const loaded = AcpRegistryAgentIcon({ icon: url }) as ReactElement>;
+ expect(
+ visitElements(loaded, (element) => element.type === "img")?.props.className,
+ ).not.toContain("invisible");
+ expect(
+ visitElements(loaded, (element) => element.props["data-slot"] === "acp-icon-fallback"),
+ ).toBeNull();
+
+ const loadedImage = visitElements(loaded, (element) => element.type === "img");
+ (loadedImage?.props.onError as (() => void) | undefined)?.();
+ hooks.beginRender();
+ const failed = AcpRegistryAgentIcon({ icon: url }) as ReactElement>;
+ expect(visitElements(failed, (element) => element.type === "img")).toBeNull();
+ expect(
+ visitElements(failed, (element) => element.props["data-slot"] === "acp-icon-fallback"),
+ ).not.toBeNull();
+ });
+});
diff --git a/apps/web/src/components/settings/AcpRegistryIcon.tsx b/apps/web/src/components/settings/AcpRegistryIcon.tsx
new file mode 100644
index 000000000000..62553177d14e
--- /dev/null
+++ b/apps/web/src/components/settings/AcpRegistryIcon.tsx
@@ -0,0 +1,170 @@
+import { useEffect, useId, useState } from "react";
+import {
+ resolveOfficialAcpRegistryIconUrl,
+ officialAcpRegistryIconUrlForAgentId,
+} from "@t3tools/contracts";
+
+import { cn } from "../../lib/utils";
+import { ACPRegistryIcon } from "../Icons";
+
+const ACP_REGISTRY_ICON_CACHE = "t3-acp-registry-icons-v1";
+const MAX_ICON_BYTES = 512 * 1_024;
+const inFlightIcons = new Map>();
+
+export { officialAcpRegistryIconUrlForAgentId, resolveOfficialAcpRegistryIconUrl };
+
+async function checkedIconBlob(response: Response): Promise {
+ if (!response.ok || response.redirected) throw new Error("ACP registry icon request failed.");
+ const contentType = response.headers.get("content-type")?.split(";", 1)[0]?.trim() ?? "";
+ if (!contentType.startsWith("image/")) throw new Error("ACP registry icon was not an image.");
+ const contentLength = Number(response.headers.get("content-length"));
+ if (Number.isFinite(contentLength) && contentLength > MAX_ICON_BYTES) {
+ throw new Error("ACP registry icon was too large.");
+ }
+ const bytes = await response.arrayBuffer();
+ if (bytes.byteLength > MAX_ICON_BYTES) throw new Error("ACP registry icon was too large.");
+ return new Blob([bytes], { type: contentType });
+}
+
+/** Fetches an official icon once, then serves it from persistent browser cache. */
+export function loadCachedAcpRegistryIcon(iconUrl: string): Promise {
+ if (resolveOfficialAcpRegistryIconUrl(iconUrl) !== iconUrl) {
+ return Promise.reject(new Error("ACP registry icon URL was not allowed."));
+ }
+ const pending = inFlightIcons.get(iconUrl);
+ if (pending) return pending;
+ const load = (async () => {
+ let cache: Cache | null = null;
+ if (typeof caches !== "undefined") {
+ try {
+ cache = await caches.open(ACP_REGISTRY_ICON_CACHE);
+ } catch {
+ // Some privacy modes expose CacheStorage but reject access. Icons can
+ // still load normally from the allowlisted registry CDN.
+ }
+ }
+ if (cache !== null) {
+ try {
+ const cached = await cache.match(iconUrl);
+ if (cached) return await checkedIconBlob(cached);
+ } catch {
+ // Ignore unreadable or invalid cache entries and repair from network.
+ }
+ }
+
+ const response = await fetch(iconUrl, {
+ credentials: "omit",
+ redirect: "error",
+ referrerPolicy: "no-referrer",
+ });
+ const clone = response.clone();
+ const blob = await checkedIconBlob(response);
+ await cache?.put(iconUrl, clone).catch(() => undefined);
+ return blob;
+ })();
+ inFlightIcons.set(iconUrl, load);
+ void load.then(
+ () => inFlightIcons.delete(iconUrl),
+ () => inFlightIcons.delete(iconUrl),
+ );
+ return load;
+}
+
+export function AcpRegistryAgentIcon({
+ icon,
+ className,
+ fallbackClassName,
+}: {
+ readonly icon: string | null;
+ readonly className?: string;
+ readonly fallbackClassName?: string;
+}) {
+ const colorFilterId = useId();
+ const iconUrl = resolveOfficialAcpRegistryIconUrl(icon);
+ const [image, setImage] = useState<{
+ readonly iconUrl: string;
+ readonly source: string;
+ readonly status: "loading" | "loaded" | "failed";
+ } | null>(null);
+ const currentImage = image?.iconUrl === iconUrl ? image : null;
+ // Render only after the load pipeline resolves: the validated blob when the
+ // fetch succeeds, or the raw allowlisted CDN URL when it fails (the official
+ // CDN serves no CORS headers, so the validating fetch is often blocked in
+ // cross-origin browser contexts while native ![]()
loading still works).
+ const source = currentImage?.source ?? null;
+ const status = currentImage?.status ?? "loading";
+
+ useEffect(() => {
+ if (iconUrl === null) return;
+ let active = true;
+ let objectUrl: string | null = null;
+ void loadCachedAcpRegistryIcon(iconUrl)
+ .then((blob) => {
+ if (!active) return;
+ objectUrl = URL.createObjectURL(blob);
+ setImage({ iconUrl, source: objectUrl, status: "loading" });
+ })
+ .catch(() => {
+ if (!active) return;
+ setImage((current) =>
+ current?.iconUrl === iconUrl ? current : { iconUrl, source: iconUrl, status: "loading" },
+ );
+ });
+ return () => {
+ active = false;
+ if (objectUrl !== null) URL.revokeObjectURL(objectUrl);
+ };
+ }, [iconUrl]);
+
+ return (
+
+ {/* Registry glyphs are monochrome. Recolor their alpha rather than
+ inverting RGB values; external images cannot inherit currentColor.
+ A local SVG filter also works when CDN CORS prevents CSS masks. */}
+
+ {status !== "loaded" ? (
+
+ ) : null}
+ {source !== null && status !== "failed" ? (
+ 
{
+ if (iconUrl === null) return;
+ setImage((current) =>
+ current?.iconUrl === iconUrl && current.source !== source
+ ? current
+ : { iconUrl, source, status: "failed" },
+ );
+ }}
+ onLoad={() => {
+ if (iconUrl !== null) setImage({ iconUrl, source, status: "loaded" });
+ }}
+ />
+ ) : null}
+
+ );
+}
diff --git a/apps/web/src/components/settings/AcpRegistrySearchStep.test.tsx b/apps/web/src/components/settings/AcpRegistrySearchStep.test.tsx
new file mode 100644
index 000000000000..06d5704c415c
--- /dev/null
+++ b/apps/web/src/components/settings/AcpRegistrySearchStep.test.tsx
@@ -0,0 +1,328 @@
+import type { ReactElement } from "react";
+import { EnvironmentId, ProviderDriverKind, type AcpRegistrySearchAgent } from "@t3tools/contracts";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
+
+import { visitElements } from "../../test/reactElementTree";
+import { reactHookHarness as hooks } from "../../test/reactHookHarness";
+
+const atoms = vi.hoisted(() => ({
+ search: Symbol("acp-search"),
+ prepare: Symbol("acp-prepare"),
+}));
+
+const state = vi.hoisted(() => ({
+ result: null as { readonly agents: ReadonlyArray } | null,
+ error: null as string | null,
+ isPending: false,
+ refresh: vi.fn(),
+ search: vi.fn(() => atoms.search),
+ prepare: vi.fn(),
+}));
+
+const lifecycle = vi.hoisted(() => ({
+ cleanups: [] as Array<() => void>,
+}));
+
+vi.mock("react", async (importOriginal) => {
+ const actual = await importOriginal();
+ const { reactHookHarness } = await import("../../test/reactHookHarness");
+ return {
+ ...actual,
+ useEffect: (effect: () => void | (() => void)) => {
+ const cleanup = effect();
+ if (cleanup) lifecycle.cleanups.push(cleanup);
+ },
+ useRef: reactHookHarness.useRef,
+ useLayoutEffect: (effect: () => void | (() => void)) => {
+ const cleanup = effect();
+ if (cleanup) lifecycle.cleanups.push(cleanup);
+ },
+ useState: reactHookHarness.useState,
+ };
+});
+
+vi.mock("react/compiler-runtime", async () => {
+ const { reactHookHarness } = await import("../../test/reactHookHarness");
+ return { c: reactHookHarness.useMemoCache };
+});
+
+vi.mock("../../state/server", () => ({
+ serverEnvironment: {
+ searchAcpRegistry: state.search,
+ prepareAcpRegistryAgent: atoms.prepare,
+ },
+}));
+
+vi.mock("../../state/query", () => ({
+ useEnvironmentQuery: () => ({
+ data: state.result,
+ error: state.error,
+ isPending: state.isPending,
+ refresh: state.refresh,
+ }),
+}));
+
+vi.mock("../../state/use-atom-command", () => ({
+ useAtomCommand: () => state.prepare,
+}));
+
+vi.mock("@t3tools/client-runtime/state/runtime", () => ({
+ isAtomCommandInterrupted: () => false,
+ squashAtomCommandFailure: () => new Error("Prepare failed."),
+}));
+
+import { AcpRegistrySearchStep } from "./AcpRegistrySearchStep";
+
+const environmentId = EnvironmentId.make("remote-device");
+const gemini: AcpRegistrySearchAgent = {
+ id: "gemini",
+ name: "Gemini CLI",
+ version: "1.2.3",
+ description: "Google's agent",
+ authors: ["Google ", "Contributor"],
+ license: "Apache-2.0",
+ website: "https://example.com/docs",
+ repository: "https://example.com/source",
+ icon: "https://example.com/icon.png",
+ distribution: "npx",
+ integrity: "registry",
+};
+
+function render(options?: {
+ readonly configured?: boolean;
+ readonly onPrepared?: (agent: AcpRegistrySearchAgent) => void;
+}): ReactElement> {
+ hooks.beginRender();
+ return AcpRegistrySearchStep({
+ environmentId,
+ providerInstances: options?.configured
+ ? {
+ acpRegistry_gemini: {
+ driver: ProviderDriverKind.make("acpRegistry"),
+ config: { agentId: "gemini" },
+ },
+ }
+ : {},
+ onPrepared: options?.onPrepared ?? vi.fn(),
+ onManualConfiguration: vi.fn(),
+ }) as ReactElement>;
+}
+
+function findByAriaLabel(
+ tree: ReactElement>,
+ label: string,
+): ReactElement> {
+ const found = visitElements(tree, (element) => element.props["aria-label"] === label);
+ expect(found).not.toBeNull();
+ return found!;
+}
+
+describe("AcpRegistrySearchStep", () => {
+ beforeEach(() => {
+ vi.useFakeTimers();
+ hooks.reset();
+ state.result = null;
+ state.error = null;
+ state.isPending = false;
+ state.refresh.mockReset();
+ state.search.mockClear();
+ state.prepare.mockReset().mockResolvedValue({
+ _tag: "Success",
+ value: { agentId: "gemini", version: "1.2.3", distribution: "npx", prepared: true },
+ });
+ lifecycle.cleanups = [];
+ vi.stubGlobal(
+ "fetch",
+ vi.fn(() => new Promise(() => {})),
+ );
+ });
+ afterEach(() => {
+ for (const cleanup of lifecycle.cleanups) cleanup();
+ vi.useRealTimers();
+ });
+
+ it("loads the catalog immediately and searches only after typing settles", () => {
+ const initial = render();
+ expect(state.search).toHaveBeenLastCalledWith({
+ environmentId,
+ input: { query: "" },
+ });
+
+ const input = findByAriaLabel(initial, "Search ACP Registry");
+ expect(input.props.size).toBe("sm");
+ (input.props.onChange as ((event: { currentTarget: { value: string } }) => void) | undefined)?.(
+ { currentTarget: { value: " Gemini " } },
+ );
+ vi.advanceTimersByTime(200);
+ render();
+ expect(state.search).toHaveBeenLastCalledWith({ environmentId, input: { query: "" } });
+ (input.props.onChange as ((event: { currentTarget: { value: string } }) => void) | undefined)?.(
+ {
+ currentTarget: { value: " Gemini CLI " },
+ },
+ );
+ vi.advanceTimersByTime(299);
+ render();
+ expect(state.search).toHaveBeenLastCalledWith({ environmentId, input: { query: "" } });
+ vi.advanceTimersByTime(1);
+ render();
+ expect(state.search).toHaveBeenLastCalledWith({
+ environmentId,
+ input: { query: "Gemini CLI" },
+ });
+ (input.props.onChange as ((event: { currentTarget: { value: string } }) => void) | undefined)?.(
+ {
+ currentTarget: { value: "" },
+ },
+ );
+ vi.advanceTimersByTime(300);
+ render();
+ expect(state.search).toHaveBeenLastCalledWith({ environmentId, input: { query: "" } });
+ });
+
+ it("renders deterministic loading, error, and empty states", () => {
+ state.isPending = true;
+ expect(
+ visitElements(render(), (element) => element.props.children === "Searching the registry..."),
+ ).not.toBeNull();
+
+ state.isPending = false;
+ state.error = "Registry unavailable.";
+ expect(
+ visitElements(render(), (element) => element.props.children === "Registry unavailable."),
+ ).not.toBeNull();
+
+ state.error = null;
+ state.result = { agents: [] };
+ expect(
+ visitElements(render(), (element) => element.props.children === "No compatible agents found"),
+ ).not.toBeNull();
+ });
+
+ it("keeps same-query refreshes visible and announced while retaining results", () => {
+ const first = render();
+ const input = findByAriaLabel(first, "Search ACP Registry");
+ (input.props.onChange as ((event: { currentTarget: { value: string } }) => void) | undefined)?.(
+ {
+ currentTarget: { value: "Codex" },
+ },
+ );
+ const draft = render();
+ const searchForm = visitElements(draft, (element) => element.type === "form");
+ (searchForm?.props.onSubmit as ((event: { preventDefault: () => void }) => void) | undefined)?.(
+ {
+ preventDefault: vi.fn(),
+ },
+ );
+
+ state.result = { agents: [gemini] };
+ const resultTree = render();
+ expect(state.search).toHaveBeenCalledWith({
+ environmentId,
+ input: { query: "Codex" },
+ });
+ const form = visitElements(resultTree, (element) => element.type === "form");
+ (form?.props.onSubmit as ((event: { preventDefault: () => void }) => void) | undefined)?.({
+ preventDefault: vi.fn(),
+ });
+ expect(state.refresh).toHaveBeenCalledOnce();
+
+ state.isPending = true;
+ const refreshingTree = render();
+ expect(
+ visitElements(
+ refreshingTree,
+ (element) =>
+ element.props.role === "status" &&
+ element.props.children === "Refreshing ACP Registry results.",
+ ),
+ ).not.toBeNull();
+ expect(findByAriaLabel(refreshingTree, "Add Gemini CLI")).not.toBeNull();
+ });
+
+ it("prepares a result before handing it back to the wizard", async () => {
+ state.prepare.mockResolvedValueOnce({
+ _tag: "Success",
+ value: { agentId: "gemini", version: "2.0.0", distribution: "binary", prepared: true },
+ });
+ state.result = { agents: [gemini] };
+ const onPrepared = vi.fn();
+ const tree = render({ onPrepared });
+
+ const add = findByAriaLabel(tree, "Add Gemini CLI");
+ (add.props.onClick as (() => void) | undefined)?.();
+ await Promise.resolve();
+ await Promise.resolve();
+
+ expect(state.prepare).toHaveBeenCalledWith({
+ environmentId,
+ input: { agentId: "gemini" },
+ });
+ expect(onPrepared).toHaveBeenCalledWith({
+ ...gemini,
+ version: "2.0.0",
+ distribution: "binary",
+ });
+ });
+
+ it("ignores a stale prepare completion", async () => {
+ let resolveFirst!: (value: { readonly _tag: "Success"; readonly value: unknown }) => void;
+ let resolveSecond!: (value: { readonly _tag: "Success"; readonly value: unknown }) => void;
+ state.prepare
+ .mockImplementationOnce(
+ () =>
+ new Promise((resolve) => {
+ resolveFirst = resolve;
+ }),
+ )
+ .mockImplementationOnce(
+ () =>
+ new Promise((resolve) => {
+ resolveSecond = resolve;
+ }),
+ );
+ state.result = { agents: [gemini] };
+ const onPrepared = vi.fn();
+ const tree = render({ onPrepared });
+ const add = findByAriaLabel(tree, "Add Gemini CLI");
+
+ (add.props.onClick as (() => void) | undefined)?.();
+ (add.props.onClick as (() => void) | undefined)?.();
+ resolveFirst({ _tag: "Success", value: {} });
+ await Promise.resolve();
+ expect(onPrepared).not.toHaveBeenCalled();
+
+ resolveSecond({ _tag: "Success", value: {} });
+ await Promise.resolve();
+ expect(onPrepared).toHaveBeenCalledOnce();
+ });
+
+ it("ignores prepare completion after unmount", async () => {
+ let resolvePrepare!: (value: { readonly _tag: "Success"; readonly value: unknown }) => void;
+ state.prepare.mockImplementationOnce(
+ () =>
+ new Promise((resolve) => {
+ resolvePrepare = resolve;
+ }),
+ );
+ state.result = { agents: [gemini] };
+ const onPrepared = vi.fn();
+ const tree = render({ onPrepared });
+
+ const add = findByAriaLabel(tree, "Add Gemini CLI");
+ (add.props.onClick as (() => void) | undefined)?.();
+ for (const cleanup of lifecycle.cleanups) cleanup();
+ resolvePrepare({ _tag: "Success", value: {} });
+ await Promise.resolve();
+
+ expect(onPrepared).not.toHaveBeenCalled();
+ });
+
+ it("renders existing registry configuration as already added", () => {
+ state.result = { agents: [gemini] };
+ const tree = render({ configured: true });
+ const added = findByAriaLabel(tree, "Already added Gemini CLI");
+
+ expect(added.props.disabled).toBe(true);
+ });
+});
diff --git a/apps/web/src/components/settings/AcpRegistrySearchStep.tsx b/apps/web/src/components/settings/AcpRegistrySearchStep.tsx
new file mode 100644
index 000000000000..2084c035d671
--- /dev/null
+++ b/apps/web/src/components/settings/AcpRegistrySearchStep.tsx
@@ -0,0 +1,279 @@
+import {
+ isAtomCommandInterrupted,
+ squashAtomCommandFailure,
+} from "@t3tools/client-runtime/state/runtime";
+import type {
+ AcpRegistryPrepareResult,
+ AcpRegistrySearchAgent,
+ EnvironmentId,
+ ProviderInstanceConfig,
+} from "@t3tools/contracts";
+import { ExternalLinkIcon, SearchIcon } from "lucide-react";
+import { type FormEvent, useEffect, useLayoutEffect, useRef, useState } from "react";
+
+import { serverEnvironment } from "../../state/server";
+import { useEnvironmentQuery } from "../../state/query";
+import { useAtomCommand } from "../../state/use-atom-command";
+import { Alert, AlertDescription } from "../ui/alert";
+import { Button } from "../ui/button";
+import { InputGroup, InputGroupAddon, InputGroupInput } from "../ui/input-group";
+import { ScrollArea } from "../ui/scroll-area";
+import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
+import { isConfiguredAcpRegistryAgent } from "./AddProviderInstanceDialog.logic";
+import { ProviderDriverKind } from "@t3tools/contracts";
+import { ProviderInstanceIcon } from "../chat/ProviderInstanceIcon";
+
+function errorMessage(error: unknown): string {
+ return error instanceof Error && error.message.trim()
+ ? error.message
+ : "The ACP could not be prepared.";
+}
+
+interface AcpRegistrySearchStepProps {
+ readonly environmentId: EnvironmentId;
+ readonly providerInstances: Readonly>;
+ readonly onPrepared: (agent: AcpRegistrySearchAgent) => void;
+ readonly onManualConfiguration: () => void;
+ readonly onLoadingChange?: (loading: boolean) => void;
+ readonly onPreparingChange?: (preparing: boolean) => void;
+}
+
+function applyAcpRegistryPrepareResult(
+ agent: AcpRegistrySearchAgent,
+ prepared: AcpRegistryPrepareResult,
+): AcpRegistrySearchAgent {
+ return {
+ ...agent,
+ id: prepared.agentId,
+ version: prepared.version,
+ distribution: prepared.distribution,
+ };
+}
+
+export function AcpRegistrySearchStep({
+ environmentId,
+ providerInstances,
+ onPrepared,
+ onManualConfiguration,
+ onLoadingChange,
+ onPreparingChange,
+}: AcpRegistrySearchStepProps) {
+ const [query, setQuery] = useState("");
+ // An empty registry query is the compact compatible catalog. Start there so
+ // entering this step is useful before the user knows what to search for.
+ const [submittedQuery, setSubmittedQuery] = useState("");
+ const [preparingId, setPreparingId] = useState(null);
+ const [prepareError, setPrepareError] = useState(null);
+ const prepareGeneration = useRef(0);
+ const searchTimer = useRef | null>(null);
+ const search = useEnvironmentQuery(
+ serverEnvironment.searchAcpRegistry({
+ environmentId,
+ input: { query: submittedQuery },
+ }),
+ );
+ const prepareAgent = useAtomCommand(serverEnvironment.prepareAcpRegistryAgent, {
+ reportFailure: false,
+ });
+
+ useEffect(
+ () => () => {
+ prepareGeneration.current += 1;
+ if (searchTimer.current !== null) clearTimeout(searchTimer.current);
+ onPreparingChange?.(false);
+ },
+ [onPreparingChange],
+ );
+
+ const submitSearch = (nextQuery: string) => {
+ if (searchTimer.current !== null) clearTimeout(searchTimer.current);
+ const trimmed = nextQuery.trim();
+ setQuery(trimmed);
+ setPrepareError(null);
+ if (trimmed === submittedQuery) {
+ search.refresh();
+ } else {
+ setSubmittedQuery(trimmed);
+ }
+ };
+
+ const handleSearch = (event: FormEvent) => {
+ event.preventDefault();
+ submitSearch(query);
+ };
+
+ const handlePrepare = async (agent: AcpRegistrySearchAgent) => {
+ const generation = ++prepareGeneration.current;
+ setPrepareError(null);
+ setPreparingId(agent.id);
+ onPreparingChange?.(true);
+ const result = await prepareAgent({ environmentId, input: { agentId: agent.id } });
+ if (prepareGeneration.current !== generation) return;
+ setPreparingId(null);
+ onPreparingChange?.(false);
+ if (result._tag === "Success") {
+ onPrepared(applyAcpRegistryPrepareResult(agent, result.value));
+ return;
+ }
+ if (!isAtomCommandInterrupted(result)) {
+ setPrepareError(errorMessage(squashAtomCommandFailure(result)));
+ }
+ };
+
+ const results = search.data?.agents ?? null;
+ const isInitialSearch = search.isPending && results === null;
+ const isRefreshing = search.isPending && results !== null;
+ const resultCount = results?.length ?? 0;
+
+ useLayoutEffect(() => {
+ onLoadingChange?.(search.isPending);
+ return () => onLoadingChange?.(false);
+ }, [onLoadingChange, search.isPending]);
+
+ return (
+
+
+ Choose an agent
+
+
+
+
+
+ {isInitialSearch
+ ? "Searching the ACP Registry."
+ : isRefreshing
+ ? "Refreshing ACP Registry results."
+ : results
+ ? `${resultCount} compatible ${resultCount === 1 ? "agent" : "agents"} found.`
+ : ""}
+
+
+ {search.error || prepareError ? (
+
+ {prepareError ?? search.error}
+
+ ) : null}
+
+ {isInitialSearch ? (
+
+ Searching the registry...
+
+ ) : null}
+
+ {results ? (
+ results.length === 0 ? (
+
+
No compatible agents found
+
Try a broader search.
+
+ {results.map((agent) => {
+ const alreadyAdded = isConfiguredAcpRegistryAgent(providerInstances, agent.id);
+ const isPreparing = preparingId === agent.id;
+ const progressLabel = agent.distribution === "binary" ? "Downloading" : "Preparing";
+ return (
+
+
+
+
+
+
+
+ {agent.name}
+
+
+ {agent.description ? (
+
+ {agent.description}
+
+ ) : null}
+
+
+
+ {agent.website || agent.repository ? (
+
+
+ }
+ >
+
+
+ }
+ />
+ About {agent.name}
+
+ ) : null}
+
+
+
+ );
+ })}
+