AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents
TypeScript ai-agentai-agent-toolsai-agentsai-agents-frameworkmcpmcp-servermcp-toolsmcpsn8n-alternativeno-code-automationworkflowworkflow-automationworkflows
feat(web): providers page that scales to 18 providers (#17038)
Louai Boumediened08ecd3d21e5
diff --git a/brain/knowledge/ai-intelligence/ai-providers.md b/brain/knowledge/ai-intelligence/ai-providers.mdindex 7b26e1b91ed..1de8aa9e401 100644--- a/brain/knowledge/ai-intelligence/ai-providers.md+++ b/brain/knowledge/ai-intelligence/ai-providers.md@@ -75,6 +75,7 @@ after a file without chat keys it seeds the chat list from the live flow list.**Specific model** — a model a builder picks directly from one key (`{provider, configId, model}`), as opposed to a tier. The admin switch `platform_configuration.aiSpecificModelsVisible` (Tiers tab, "Visible to builders") hides them from builders. _Avoid_: "Advanced" (an early mockup word for the same section)### Gotchas+- **A new provider shows "—" for context and price until the catalog is republished from `main`.** Its `MODELS_DEV_PROVIDER` entry only takes effect when the weekly `sync-model-catalog` workflow runs on `main` (trigger it by hand after the merge), and the API caches the catalog for 24h. Even then only ids models.dev knows fill in: of NVIDIA's 85 hosted models about 26 match, and its prices are $0 because the hosted catalogue is free.- **The AI usage read API (`/v1/ai-usage/*`) works in UTC days and scales today's partial day inside the SQL.** Every previous-range sum is multiplied by a weight that is below 1 only on the day matching today, so totals, cards, lists and related items all compare the same way. Scaling after the query, in TypeScript, can't reach per-item numbers and makes the views disagree.- **Usage tracking starts per platform, at its copy cursor.** `trackingSince` is the cursor's `startedAt`, or the platform's creation if that is later. A period that starts earlier hides its change %, so a fresh platform never shows fake growth. A platform without a cursor has no tracking start.- **Usage ids are not always entity ids.** `no-project` is platform chat, `activepieces-credits` and `unknown-<provider>` are keys with no config, and a model id is `base64url(provider|modelId)`. Lists stop at 1000 rows. `ACTION_RUN` rows have no `flowId`, so the flows card never adds up to the flow-steps slice.@@ -163,7 +164,7 @@ after a file without chat keys it seeds the chat list from the live flow list.- **`secret: true` on a credential field is not about masking, it is what stops a stored credential being prefilled back into the form.** In `PROVIDER_CREDENTIAL_FIELDS` the flag feeds `secretKeysOf`, and the dialog's default-values builder blanks exactly those keys when reopening an existing key; the password-style `Input` is a side effect of the same flag, not its purpose. So dropping it to change how a field *renders* silently turns a stored secret into a prefilled value. Render differently instead: `type` (`dictionary`, `textarea`) is checked ahead of `secret` in `CredentialFieldInput`, so a field can keep the flag and still draw as something other than a masked input — that is how the Vertex service-account JSON gets a monospace textarea while staying blanked on edit. Both the initialiser and the required-field check filter only `dictionary`, so any other `type` is initialised and validated like a normal credential.- **Adding a provider is a leaf change, and the credential fields are the only part that is not.** A new vendor touches six places: the `AIProviderName` enum (`packages/core/utils/.../permission.ts`), its auth/config schemas plus the two unions and `ProviderConfigUnion` in `packages/core/shared/.../management/ai-providers/index.ts` (all in the per-provider region, well above the generic request/response schemas at the bottom), a strategy file registered in `ai/providers/index.ts`, the model factory switch, name/logo/markdown in `packages/web/src/features/agents/ai-providers.ts`, and translation keys. None of that is the credential form: extra fields beyond `apiKey` (Azure's `resourceName`, Bedrock's region) are declared in **one** file — `PROVIDER_CREDENTIAL_FIELDS` in `.../setup/ai/providers-tab/provider-credentials.ts`, which falls back to `DEFAULT_CREDENTIAL_FIELDS` (a single `apiKey`) for any provider with no entry, so a plain API-key vendor needs no UI work at all. That file replaced the deleted `universal-pieces/upsert-provider-config-form.tsx` in the multi-key redesign, so a provider authored against an older branch loses its custom fields on merge **silently** — git resolves delete-vs-modify by taking the deletion, no conflict marker, and the provider just becomes unconfigurable in the admin UI. A vendor with no `/models` endpoint also belongs in `MANUAL_MODEL_PROVIDERS` in that same file (`CUSTOM`, `CLOUDFLARE_GATEWAY`) so the admin enters model ids by hand. Everything else about a provider is orthogonal to multi-key: that is a table-level change (drop `UNIQUE (platformId, provider)`, add the four scope columns, keep a unique partial index for `activepieces` only), so a provider inherits multi-key with no provider-side code, and the admin providers-tab enumerates `SUPPORTED_AI_PROVIDERS` from `packages/web/src/features/agents/ai-providers.ts` rather than a catalog of its own, so a new vendor appears there on its own. When basing provider work off a branch that predates the redesign, re-check `provider-credentials.ts` after the merge.- **The OpenAI-compatible vendors (xAI, DeepSeek, Z.ai, Qwen, MiniMax, Moonshot) share one strategy rather than a file each**, via `openAiCompatibleVendor({ name, provider })` in `ai/providers/`, with defaults in `OPENAI_COMPATIBLE_VENDOR_BASE_URLS` and an optional per-key `baseUrl` override because four of them run separate China and international endpoints. Their `listModels` GETs `{baseUrl}/models`, which the vendor docs mostly do not document — **confirmed working against live keys for DeepSeek, Z.ai, MiniMax and Moonshot** (Qwen still unverified), so don't redo that research. If a future vendor turns out to lack `/models`, the fallback is the manual-models path rather than a bespoke strategy. Unlike its siblings this factory uses `safeHttp.axios`, not `httpClient` from `pieces-common`: the base URL is admin-supplied, so it must go through the SSRF filter.-- **Adding an API-key vendor touches these files, and two misses only fail at runtime.** `AIProviderName` (`core/utils/.../permission.ts`); the `AiProviderCredentials` union (`core/utils/.../ai-provider-credentials.ts`) — miss it and `aiProviderCredentials()` throws at run time, because `createLanguageModel`'s `never` check cannot see a provider the union never admits; `ProviderConfigUnion` (`core/shared/.../management/ai-providers`) — miss it and creating a key returns 400; `OpenAiCompatibleVendor`, `OPENAI_COMPATIBLE_VENDOR_BASE_URLS`, `NO_IMAGE_GENERATION_PROVIDERS` and the exhaustive `AI_PROVIDER_CAPABILITIES` (`core/piece-types/.../ai-providers.ts`); the `createLanguageModel` switch; the exhaustive `aiProviders` registry (`server/api/.../ai/providers`); web `SUPPORTED_AI_PROVIDERS`, the API-key group in `provider-request.ts`, and the markdown translation key; `MODELS_DEV_PROVIDER` in `tools/scripts/sync-model-catalog.ts`; the two provider lists in `docs/admin-guide/guides/setup-ai-providers.mdx`; and a CDN logo. The AI piece no longer has its own factory: `ai-sdk.ts` / `buildLanguageModel` were deleted in #15495 and AI steps run in the worker through `createLanguageModel`. `NO_IMAGE_GENERATION_PROVIDERS` is still load-bearing for text-only vendors, because `createImageModel` returns `undefined` for them and that list is what turns an image request into a clear error. Core libraries resolve each other from `dist`, so rebuild `core-utils` and `core-piece-types` (`npm run build` in each) before running a dependent package's tests, or the new enum value reads as `undefined`.+- **Adding an API-key vendor touches these files, and two misses only fail at runtime.** `AIProviderName` (`core/utils/.../permission.ts`); the `AiProviderCredentials` union (`core/utils/.../ai-provider-credentials.ts`) — miss it and `aiProviderCredentials()` throws at run time, because `createLanguageModel`'s `never` check cannot see a provider the union never admits; `ProviderConfigUnion` (`core/shared/.../management/ai-providers`) — miss it and creating a key returns 400; `OpenAiCompatibleVendor`, `OPENAI_COMPATIBLE_VENDOR_BASE_URLS`, `NO_IMAGE_GENERATION_PROVIDERS` and the exhaustive `AI_PROVIDER_CAPABILITIES` (`core/piece-types/.../ai-providers.ts`); the `createLanguageModel` switch; the exhaustive `aiProviders` registry (`server/api/.../ai/providers`); web `SUPPORTED_AI_PROVIDERS`, the API-key group in `provider-request.ts`, and the markdown translation key; `MODELS_DEV_PROVIDER` in `tools/scripts/sync-model-catalog.ts`; the two provider lists in `docs/admin-guide/guides/setup-ai-providers.mdx`; a slot in `PROVIDERS_BY_IMPORTANCE` (`setup/ai/providers-tab/index.tsx`), which orders the Providers page and otherwise drops the new vendor after Other (OpenAI Compatible); and a CDN logo. The AI piece no longer has its own factory: `ai-sdk.ts` / `buildLanguageModel` were deleted in #15495 and AI steps run in the worker through `createLanguageModel`. `NO_IMAGE_GENERATION_PROVIDERS` is still load-bearing for text-only vendors, because `createImageModel` returns `undefined` for them and that list is what turns an image request into a clear error. Core libraries resolve each other from `dist`, so rebuild `core-utils` and `core-piece-types` (`npm run build` in each) before running a dependent package's tests, or the new enum value reads as `undefined`.- **Overriding `fetch` on a provider silently switches off key-health reporting.** `...observed` *is* a `fetch` (`observedProviderFetch`), so any later `fetch` in the same options object replaces it rather than adding to it — spread order decides, and nothing errors or logs. A path that needs its own `fetch` (the Responses header-stripping one, the Cloudflare gateway's `Authorization`-deleting one) must take `observedProviderFetch(options.onOutcome)` as a delegate and call it, not call `globalThis.fetch`. Resolve the delegate at call time rather than capturing it at model-construction time; late binding is both more correct and the only way a test can stub the global. This is the same family as the merge hazard above — the failure is always one provider, or one path within a provider, quietly not reporting.- **A provider branch merges cleanly and still opts out of whatever the switch gained meanwhile.** `createLanguageModel` applies cross-cutting behaviour by spreading it into *every* case — `...observed` (`observedProviderFetch`, added by the key-health work) is the current one. Git treats a long-lived branch's new `case` as an added block, so it lands with none of the spreads its siblings picked up, and the merge reports no conflict: the new provider is simply the one that never reports health. Nothing fails, nothing logs. After merging main into any provider branch, diff your `case` against a neighbouring one and check the spreads match, rather than trusting a clean merge.- **Only two `Record<AIProviderName, …>` maps are exhaustive, so the enum addition barely fights back.** `AI_PROVIDER_CAPABILITIES` (piece-types) and `aiProviders` (`ai/providers/index.ts`) must gain an entry; `PROVIDER_CREDENTIAL_FIELDS`, `ALLOWED_CHAT_MODELS_BY_PROVIDER`, `PROVIDER_MAX_CONTEXT_TOKENS`, `EMBEDDING_MODELS` and `WEB_SEARCH_MODE_BY_PROVIDER` are all `Partial<Record<…>>` and degrade silently to defaults. `grep -rn 'Record<AIProviderName' | grep -v 'Partial<'` is the whole compile-time safety net — every other consequence of a new provider is a runtime question you have to reason about yourself.@@ -173,7 +174,7 @@ after a file without chat keys it seeds the chat list from the live flow list.- **Vertex is a different door onto the same models, not a different vendor.** The `GOOGLE` provider is the Gemini Developer API (`generativelanguage.googleapis.com`, static API key); `VERTEX` is Vertex AI (`{region}-aiplatform.googleapis.com/v1beta1/projects/{project}/locations/{region}/publishers/google`, service-account OAuth2 with ~1h tokens) — the same Gemini models, but billed to the customer's GCP account and inheriting IAM, VPC-SC, CMEK, data residency and audit logs, plus Model Garden's Claude/Llama/Mistral. That rotating token is why the CUSTOM provider can never reach Vertex: `buildOpenAICompatibleHeaders` injects one static header, which is why the workaround used to be a LiteLLM proxy. `@ai-sdk/google-vertex` does the JWT-to-token exchange itself, so the native provider needs no proxy. Vertex models are entered by hand (`MANUAL_MODEL_PROVIDERS`) on purpose: availability is project-, region- and Model-Garden-specific, and a `publishers/google` listing would miss exactly the third-party models that motivate choosing Vertex. **But "same models" only holds for Gemini.** Model Garden also serves Anthropic, Meta, Mistral and xAI, and those do not share Gemini's API surface — `@ai-sdk/google-vertex` ships separate `/anthropic`, `/maas` and `/xai` entry points for exactly that reason, so one `createVertex(...)` call does not cover Vertex. Because models are typed in by hand, a Claude id reaches the factory as an ordinary string and, unrouted, gets built with the Gemini client and fails at the endpoint. `create-language-model.ts` routes ids containing `claude` to `createVertexAnthropic`; `vertexClientFor` picks the client from the id shape, so all three are routed. Because the shapes are unambiguous the check is a lookup, not a tuned heuristic — and note the publisher prefix has to be tested *before* the `claude` one, or a MaaS path containing "claude" routes to the Anthropic client. Routing is cheap because the id shapes are distinct, not because a heuristic was tuned: `gemini-2.5-pro` is bare, Anthropic carries an `@date` (`claude-3-5-sonnet@20241022`), and MaaS is publisher-prefixed and suffixed (`meta/llama-4-scout-17b-16e-instruct-maas`). The publisher prefix is a stronger discriminator than the `includes('claude')` match currently shipped, and it looks like an argument for listing models rather than taking them by hand — but it is not, see below: the listing is scoped to a single publisher, so Model Garden ids stay hand-typed and the string matching stays with them. **Listing was considered and rejected**, and the reason is worth keeping so it does not get reopened, and **the response shape does not need a GCP account to learn** — every Google API publishes an unauthenticated discovery document: `curl -s 'https://aiplatform.googleapis.com/$discovery/rest?version=v1beta1'` returns ~5MB of JSON whose `schemas` are the authoritative request/response types. `publishers.models.list` returns `{ publisherModels: PublisherModel[], nextPageToken }`, and `PublisherModel` is `{ name: 'publishers/google/models/<id>', versionId, versionState (STABLE|UNSTABLE), launchStage (GA|PUBLIC_PREVIEW|PRIVATE_PREVIEW|EXPERIMENTAL), openSourceCategory, supportedActions, predictSchemata, frameworks, parent }`. **There is no `displayName` on it** — the one in `google-vertexai`'s piece comes from `@google/genai`'s `Model` type, which is a different shape, so copying that code gives every row a blank label with nothing failing. `displayName` exists only on the nested `parent`, which is the base model a tuned model derives from. The decisive fact is in that same doc: `publishers.models.list` takes `parent` matching `^publishers/[^/]+$` — **one publisher per call**. Listing everything therefore means hardcoding the set of publishers to enumerate, which is the same shape of hardcoding it was meant to remove, and Model Garden models would still need hand entry, leaving two mechanisms where there is now one. `VERTEX` stays in `MANUAL_MODEL_PROVIDERS` alongside `CUSTOM` and `CLOUDFLARE_GATEWAY`, which fits: Vertex model availability really is per-project. Reach for the discovery doc before a live probe on any `*.googleapis.com` integration; a curl against the real endpoint needs **billing attached to the project even for a read** (`403 BILLING_DISABLED`), so it is the slower path and it is not free to set up. The `x-goog-user-project` header is not optional when probing with a personal login: without it aiplatform answers `403 SERVICE_DISABLED` naming `consumer: projects/32555940559`, which is Google's shared gcloud CLI project rather than yours, and the message talks about quota projects rather than the missing header. This is a user-credential quirk only — a service account carries its own `project_id`, so the provider itself never hits it. **The multi-vendor story is text only.** Vertex's image models are Google's own Imagen (`imagen-3.0-*`, `imagen-4.0-*`), not Model Garden's third parties, and `createVertex(...)` also exposes `imageModel`, `video`, `speech`, `transcription` and `textEmbeddingModel` — none of which we wire today. Imagen is wired (`createVertex(...).imageModel()`, with a `VERTEX` case in the piece's image switch, so `VERTEX` is no longer in `NO_IMAGE_GENERATION_PROVIDERS`); video, speech, transcription and embeddings are not. Embeddings still have no `EMBEDDING_MODELS` entry, so those paths fail with an explanatory message instead of reaching a switch that has no case for it.- **Chat-tier resolution answers "which model" from three places, and only one of them is the key.** `resolveModelIdForProvider` (`ee/agent/agent-model-resolution.ts`, spread into `agentHelpers`) now prefers the resolved key's own configured text models when its config carries a `models` array — that is the `MANUAL_MODEL_PROVIDERS` case (Vertex, Custom, Cloudflare Gateway), where the admin typed the exact ids the key exposes. **An empty catalog is not a missing one**, and collapsing the two is how the first cut of this went wrong: a helper returning `string[] | undefined` treated "lists zero text models" the same as "has no catalog", so a key configured with only image models fell through to the curated list and resolved to a Gemini id it never offered. An admin-listed catalog is the whole truth about a key, so an empty one now refuses the turn with a message rather than guessing. Otherwise it falls back to the static `ALLOWED_CHAT_MODELS_BY_PROVIDER`, and if the provider is missing from that too it returns the raw tier id with its vendor prefix stripped — which is how a Vertex key once resolved to `claude-sonnet-4-6` and handed it to the Gemini client. That map is `Partial<`, so omitting a chat-capable provider compiles cleanly and fails only at the endpoint. **The key's own `modelScope`/`modelIds` allow-list is applied last, to whichever candidate list was chosen**, and a resolution with nothing left refuses the turn rather than returning a model the key forbids. `GetProviderConfigResponse` carries both fields for that, populated at all three construction sites (`getChatProvider`, `getConfigOrThrow`, `enrichWithKeysIfNeeded`); adding fields there is backward compatible because the AI piece reads the response as a typed shape rather than parsing it. I first recorded this as too big for a provider PR — "a wire contract the engine and the AI piece both consume" — having never measured it. It was about thirty lines across four files. Measure before recording something as out of scope; the estimate outlives the guess. **The resolver is exported and has five call sites across four files, and only two of them are runs.** `agent-rpc-handlers` resolves the chat turn's model *and* its fast model, and `chat-personalization-service` resolves both for research — those four must be given the resolved row's `config`, `modelScope` and `modelIds`, or the key's constraints are bypassed on exactly the paths a user takes. `resolveTierModel` inside `agent-helpers` is the fifth. `agent-service` also calls it but holds only a provider name and sets a stored default on a draft, so it is correctly left thin (`agent-draft-ai` did too, until #15676 deleted it). Adding a parameter here means grepping `resolveModelIdForProvider|resolveFastModelId` across `packages/server`, not editing the call site in front of you — threading only `resolveTierModel` looks complete, passes every test, and still leaves the real chat path unconstrained. The `surface` argument was added as a required key on the whole family for exactly that reason: a missed call site is a compile error, except inside a `vi.mock` factory, which is not type-checked and has to be updated by hand. One trap when touching this function: a tier id (`fast`, `smart`) is **not** a model id, so the preferred pick must be the resolved native id unless the selection is itself among the candidates — passing `selectedModel` straight through makes `resolveFastModelId` return the first curated model instead of the fast tier's.- **A failed credential validation tells the admin nothing, for every provider except Cloudflare Gateway.** `aiProviderService.validateProviderCredentials` gates the upstream message behind `includeHttpErrorInMessage`, which is `provider === CLOUDFLARE_GATEWAY` and nothing else, so everyone else gets a bare `Failed to validate credentials for <name>`. The cause is not lost — it is logged one line earlier (`log.error({ error }, '[aiProviderService#validateProviderCredentials] ...')`) and passed as the `httpErrorResponse` error param — but **web never renders `httpErrorResponse`**, so the only way to diagnose a rejected key is the server log. Grep the log for `validateProviderCredentials` before assuming the provider integration is broken — that text is the whole diagnosis, and it is often not about credentials at all. Confirmed case: a brand-new xAI team with no credits purchased answers `GET /v1/models` with `403 permission-denied — Your newly created team doesn't have any credits or licenses yet`, naming the console page that fixes it, and we render that as "Failed to validate credentials for xAI" — sending the admin off to regenerate a key that was never wrong. Vendors also phrase real key failures inconsistently (xAI uses `400 Incorrect API key provided`, not a 401). The corollary: **a provider that saves without error is not a working provider.** A no-credits 403 and a bad key are indistinguishable in the UI, so only an actual generation proves a key end to end. This is an admin-only surface (`platformAdminOnly`), so there is little reason to keep hiding it.-- **A provider's logo is an asset someone has to upload, not something the code ships.** `AiProviderInfo.logoUrl` in `packages/web/src/features/agents/ai-providers.ts` is a plain string rendered into an `<img src>`, and every provider points at `https://cdn.activepieces.com/pieces/<slug>.png` — nothing is bundled. Adding a provider therefore carries a cross-team dependency with no compile-time or test signal: a slug with no asset behind it renders a broken-image icon in the platform admin list, and only a live request tells you. Check the URL with `curl -o /dev/null -w '%{http_code}'` before assuming it works — a vendor that already ships as a *piece* usually has its logo there already (`deepseek.png`, `grok-xai.png` did), so start the upload request only for the genuinely missing ones. A Vite asset import also satisfies `logoUrl` (see `GoogleIcon` in `platform/security/sso/index.tsx`) and removes the runtime CDN dependency for air-gapped installs, but it diverges from every other provider — treat it as a fallback, not the default.+- **A provider's logo is an asset someone has to upload, not something the code ships.** `AiProviderInfo.logoUrl` in `packages/web/src/features/agents/ai-providers.ts` is a plain string rendered into an `<img src>`, and every provider points at `https://cdn.activepieces.com/pieces/<slug>.png` — nothing is bundled. Adding a provider therefore carries a cross-team dependency with no compile-time or test signal: a slug with no asset behind it renders a broken-image icon in the platform admin list, and only a live request tells you. Check the URL with `curl -o /dev/null -w '%{http_code}'` before assuming it works — a vendor that already ships as a *piece* usually has its logo there already (`deepseek.png`, `grok-xai.png` did), so start the upload request only for the genuinely missing ones. A Vite asset import also satisfies `logoUrl` (see `GoogleIcon` in `platform/security/sso/index.tsx`) and removes the runtime CDN dependency for air-gapped installs, but it diverges from every other provider — treat it as a fallback, not the default. Upload it trimmed, with no built-in whitespace and no solid background: `ProviderLogo` draws every logo at 22px inside a 36px `LogoPlate`, so padding baked into the PNG (Qwen, Azure) makes it look smaller than its neighbours and a filled square (xAI) looks heavier. No code fixes that. Use the symbol only, square, never a wordmark lockup: Meta's and NVIDIA's first uploads were full brand lockups and rendered as unreadable blobs. To cut one from a lockup: `magick in.png -crop WxH+X+Y +repage -fuzz 8% -transparent white -trim +repage -background none -gravity center -extent "%[fx:max(w,h)*1.08]x%[fx:max(w,h)*1.08]" -resize 256x256 out.png`.- **The manual-models panel stores a model id and nothing else, so every model an admin adds is typed `TEXT`.** `MANUAL_MODEL_PROVIDERS` (Vertex, Custom, Cloudflare Gateway) persist a `ProviderModelConfig` of `{ modelId, modelName, modelType }`, but since #14825 the UI keeps only `string[]`: `ManualModelList` is a chip list of ids, and `config-detail.tsx` rebuilds the objects on save with `?? { modelId, modelName: modelId, modelType: TEXT }`. The old `universal-pieces/model-form-popover.tsx` had all three fields; replacing it with chips dropped two of them, and no schema or test noticed because the reconstruction is type-correct. The visible damage is not just a mislabelled model: `cloudflareGatewayProvider.validateConnection` pings **only text models** with a `/chat/completions` request, so one image model added through the UI is validated as chat, fails, and takes the whole key down with `These models have issues: ...` — the admin cannot save a key that has an image model on it at all. Anything reading `modelType` downstream (the agent text-model filter, `ap-list-ai-models`, the builder's image pickers) is wrong the same way. Fixed by holding `ProviderModelConfig[]` in the draft rather than `string[]` (no migration; stored rows always had the right shape), so the standing rule is that **a manual-models UI must carry `modelType` all the way to the payload** — a panel that collapses models to ids reintroduces exactly this, and nothing downstream will complain until an admin adds an image model. Keys saved while the bug was live still hold image models typed `TEXT`; the type badge on each chip flips one in place, which is why it is editable rather than display-only.- **Custom keys get model suggestions; Vertex and Cloudflare Gateway stay typed by hand on purpose.** `GET /v1/ai-providers/configs/:id/suggested-models` calls the strategy's optional `suggestModels`, which only `openAICompatibleProvider` implements: `GET {baseUrl}/models` with the key's own header, through `fetchOpenAiModelIds` (shared with the vendor list), filtered by `isChatModelId`. The ids feed a `<datalist>` on the manual-models input, so free text still works and the admin still picks `modelType` (`/models` does not say text or image). Suggestions never touch `listModels`, which stays `config.models` because tiers and key scope read it. A failed fetch returns `[]` and logs, so a LAN or localhost base URL that `safeHttp` blocks (self-hosted Ollama, unless in `AP_SSRF_ALLOW_LIST`) just shows no suggestions. Vertex is not listed for the reason in the Vertex bullet (one publisher per call), and Cloudflare's gateway has no models endpoint. Any fetch to an admin-supplied URL needs three bounds, not one: axios's `timeout` only fires when the connection goes idle, so a server that drips bytes holds it open, and a huge body is read into memory in full. `fetchOpenAiModelIds` passes `timeout`, `signal: AbortSignal.timeout(...)` and `maxContentLength`. Trim a trailing slash with `/\/$/`, not `/\/+$/`: the `+` form is quadratic on a long run of slashes and `baseUrl` has no length limit (both from review on #16382).diff --git a/brain/knowledge/ai-intelligence/ai-usage-page.md b/brain/knowledge/ai-intelligence/ai-usage-page.mdindex 9c1a7e99c8f..04ef7f39ed7 100644--- a/brain/knowledge/ai-intelligence/ai-usage-page.md+++ b/brain/knowledge/ai-intelligence/ai-usage-page.md@@ -21,7 +21,7 @@ The AI Center page (`/platform/ai/usage`) that answers one question: **where is- **Costs are marked as estimates where the money is, not in the subtitle.** A quiet "Estimated" link sits next to the hero's Spend label (hidden for calls and tokens, which are exact) and opens a "Why these numbers are estimates" popover: providers mostly return tokens, not cost; discounts, caching, batch rates and price changes shift the real bill; reported costs are used as is; Activepieces credits are exact; the provider dashboard is the billing truth. Putting the caveat first in the page header made the whole page read as untrustworthy (dropped 2026-10-21).- **Empty overview is the real page at zero, not a splash.** Tiles read $0.00 and 0, the chart is a flat line, the donut is an empty grey ring, and cards show their small empty state. One slim note bar on top says why: never used → "No AI spend yet. It shows up a few minutes after the first AI step, agent run or chat message."; empty only for these filters → names the scope and period and offers "Show last 90 days" and "Include testing" / "Include production". A third state exists for self-hosted Enterprise with no billing connection (`trackingSince === null`): "AI usage isn't available on this install", with a one-line why — usage data comes from the billing connection, which the install does not have. List and detail pages use a compact left-aligned card with the same copy and buttons. Never link to provider setup from here. A centred splash and a ghost-preview panel were tried and dropped. The read API's has-any-usage flag (`history.hasAnyUsage`) tells never-used apart from filtered-empty (`usage-empty.tsx`).- **Loading looks like the page.** Every surface is the real white card with grey bars inside it in the shape of its content: tiles, the hero with one block for the chart, the donut, and the list rows with their share bars. Every usage page has its own: overview, see-all list (search, header, rows), and detail (tiles, hero, donut for projects and agents, one card per related list). Never draw bare grey blocks in place of cards (`usage-skeletons.tsx`).-- **The title is the breadcrumb.** List: "AI usage / Users". Detail: "AI usage / Users / Maya Chen", whatever page you came from, so one click reaches the list. There is no back link above the title and no type badge; the period and scope carry over in every crumb.+- **The title is the breadcrumb.** List: "AI usage / Users". Detail: "AI usage / Users / Maya Chen", whatever page you came from, so one click reaches the list. There is no back link above the title and no type badge; the period and scope carry over in every crumb. The trail is `AiCenterTrail` (`setup/ai/components/ai-center-trail.tsx`), shared across the AI Center: the provider key page uses it too ("Providers / key name"), so new AI Center sub-pages use it instead of a back link.- **One detail template.** Header + the same chart + top 5 of the *other* dimensions + one extra card per type: project → spend with its flow and agent counts, flow → runs and cost per run, key → reported vs estimated, model → list price. A flow detail stops at flow level; there is no per-step split. A detail page with zero calls and zero previous spend shows the empty card but keeps the item's name in the breadcrumb.- **"Previous period" means the same span right before**, except month views: "This month" and "Last month" compare with the same days of the month before (Oct 1–20 vs Sep 1–20). The chart legend reads its ranges straight from the read API's `ranges` field (not re-derived from chart point labels), since that is the only place the month-truncation rule is computed correctly.diff --git a/brain/knowledge/design-system/colour.md b/brain/knowledge/design-system/colour.mdindex 159f21c136b..7d9e4334753 100644--- a/brain/knowledge/design-system/colour.md+++ b/brain/knowledge/design-system/colour.md@@ -125,7 +125,7 @@ light island (`data-theme="light"`, `bg-gray-1`, `text-gray-12`), so the chip stdark mode; a fallback glyph or monogram inside it inherits the dark `gray-12`. A border or ring passed in `className`resolves in the island's light values. `className` styles the plate and `innerClassName` the box that holds the imageinside it (a percentage padding would resolve against the plate's *parent*). `PieceIcon` is a tooltip wrapper-over it.+over it. A `dark:` class passed in `className` never fires: the plate is its own `data-theme="light"` island, so the `dark` variant does not match it. Anything theme-dependent for a plate goes on a wrapper outside it. Dimming plates in dark mode with a brightness filter was tried on the AI Center provider logos and rejected: it greys the logo artwork too and reads as disabled.- **`tint` gives the plate a flat wash of the logo's own colour** (`lib/logo-tint.ts`). The logo is loaded once withCORS, sampled at 24px, and its visible, *coloured* pixels are averaged in OKLab, weighted by chroma, so white anddiff --git a/brain/knowledge/engineering/ci-pr-review-hygiene.md b/brain/knowledge/engineering/ci-pr-review-hygiene.mdindex 0ff0b1d02ad..4d4cbcbc892 100644--- a/brain/knowledge/engineering/ci-pr-review-hygiene.md+++ b/brain/knowledge/engineering/ci-pr-review-hygiene.md@@ -28,7 +28,7 @@ Enforcement is the **`Codeowners review` repository ruleset** (active on the def- **Any push to an approved PR dismisses the approval.** Seen 2026-10-08 on #16116: a one-commit change after approval left the PR `BLOCKED` with an empty `reviewDecision`. So land small follow-ups before asking for approval, or plan for a second approval. Check `gh pr view <n> --json reviewDecision` after pushing.- **When merging main, `rerere` can replay a stale `bun.lock` resolution.** "Staged 'bun.lock' using previous resolution" means git reused an old answer, which can carry workspace versions that no longer match any `package.json` (seen: core-utils `0.8.6` in the lockfile against `0.8.5` in the manifest). If the branch adds no dependencies, take main's `bun.lock` and edit only the branch's own workspace `version` lines. Expect `bun install` to then rewrite a few lines for pieces the branch never touched: piece PRs on `main` often bump a `package.json` without its `bun.lock` entry (seen 2026-10-05: grist, microsoft-todo, ticktick, zendesk). Those lines are main catching up, not your change; keep them, because the lock should match the manifests.- **Any change to `bun.lock` runs every package's tests in `build-test`, all 700+ pieces included.** The `changes` job in `ci.yml` sets `all=true` when a changed file is outside `packages/`, `docs/`, `brain/`, `.agents/` and `.claude/` and is not a `*.md` file (so root Markdown alone does not count), and `tools/scripts/test-filters.ts` then adds every package with a `test` script **except `api`** (it lists with `--filter=!api`). API tests run in the separate `api-tests` matrix job (`api (ce)`, `api (cloud)`, `api (ee, unit, migrations)`), so look there for their results, not in `build-test`. Without that, a piece only runs when its own files or `pieces/framework` / `pieces/common` change; a `core-utils` change alone does not pull pieces in. Any workspace version bump edits `bun.lock`, so this hits most PRs that bump a package. A CPU-heavy piece test can then fail on the starved runner with no change of yours: an Odoo polling test that takes ~350ms locally passed vitest's 5s default in 3 of 3 runs, reruns included. Don't keep rerunning: give the heavy test an explicit timeout (third `it` argument). Even a test-only change needs that piece's patch bump (and its `bun.lock` line): `validate-publishable-packages` diffs the whole package folder against `origin/main`.-- **After the base PR of a stack merges, merging main into the next PR silently keeps the base PR's old lines.** The merge base predates the base PR, so code the base PR dropped during review (fields, routes, columns) looks like a branch addition and survives with no conflict. Check with `git diff --name-only origin/main`: every file must be one the stacked PR itself changed. If not, save the stacked PR's own patch first (`git diff --binary <base-PR tip it was built on> <head before the merge> > pr.patch`; without `--binary`, an image or other binary file is written as "Binary files differ" and `read-tree` deletes it with no way back), then `git read-tree -u --reset origin/main` and `git apply --3way pr.patch`, and commit. `read-tree` also deletes files that exist only on the branch (a file the base PR added, then dropped), which `git checkout origin/main -- .` would leave behind. Use `origin/main`, not `MERGE_HEAD`: a merge with no conflicts commits itself and `MERGE_HEAD` is gone. **The rebuild is not finished until `origin/main` is an ancestor.** `read-tree` + `apply` makes a commit whose *tree* is main + patch, but the merge base with main is still the old one, so GitHub's PR diff counts every main change since then as the PR's (seen: 731 files for a 43-file PR). Follow it with `git merge origin/main`; every conflict is the same change on both sides, so `git diff --name-only --diff-filter=U | xargs git checkout --ours --` is the answer, and `git diff --cached HEAD --stat` must print nothing before you commit (the tree does not change, only the ancestry). A branch cut from a stacked branch with `git checkout -b` inherits its **upstream**, so `git status -sb` reads `feat/pr-4...origin/feat/pr-3` and a plain `git push` would push PR 4's commits onto PR 3's remote; run `git branch --unset-upstream` right after cutting it (seen 2026-10-05 on `feat/platform-tiers-admin-ui`). Then retarget it (`gh pr edit <n> --base main`): a PR still pointed at the merged base branch shows every main change since then (seen: 1,285 files for a 28-file PR). No rebase or force push needed.+- **After the base PR of a stack merges, merging main into the next PR silently keeps the base PR's old lines.** The merge base predates the base PR, so code the base PR dropped during review (fields, routes, columns) looks like a branch addition and survives with no conflict. Check with `git diff --name-only origin/main`: every file must be one the stacked PR itself changed. If not, save the stacked PR's own patch first (`git diff --binary <base-PR tip it was built on> <head before the merge> > pr.patch`; without `--binary`, an image or other binary file is written as "Binary files differ" and `read-tree` deletes it with no way back), then `git read-tree -u --reset origin/main` and `git apply --3way pr.patch`, and commit. `read-tree` also deletes files that exist only on the branch (a file the base PR added, then dropped), which `git checkout origin/main -- .` would leave behind. Use `origin/main`, not `MERGE_HEAD`: a merge with no conflicts commits itself and `MERGE_HEAD` is gone. **The rebuild is not finished until `origin/main` is an ancestor.** `read-tree` + `apply` makes a commit whose *tree* is main + patch, but the merge base with main is still the old one, so GitHub's PR diff counts every main change since then as the PR's (seen: 731 files for a 43-file PR). Follow it with `git merge origin/main`; every conflict is the same change on both sides, so `git diff --name-only --diff-filter=U | xargs git checkout --ours --` is the answer, and `git diff --cached HEAD --stat` must print nothing before you commit (the tree does not change, only the ancestry). A branch cut from a stacked branch with `git checkout -b` inherits its **upstream**, so `git status -sb` reads `feat/pr-4...origin/feat/pr-3` and a plain `git push` would push PR 4's commits onto PR 3's remote; run `git branch --unset-upstream` right after cutting it (seen 2026-10-05 on `feat/platform-tiers-admin-ui`). Shortcut when the base PR did not change in review (`git diff <base tip> origin/main -- <base PR's files>` prints nothing): a plain `git merge origin/main` is safe, then prove it with `diff <(git diff origin/main HEAD) <(git diff <base tip> <old head>)` ignoring `index` lines. Prefer it when you have uncommitted edits to tracked files (a local `.env.dev`): `read-tree -u --reset` overwrites them. Then retarget it (`gh pr edit <n> --base main`): a PR still pointed at the merged base branch shows every main change since then (seen: 1,285 files for a 28-file PR). No rebase or force push needed.- **The tests bucket keys off a path *segment*, so a feature folder named `test-step` is not mistaken for tests.** `packages/web/src/app/builder/test-step/` and `latest-test.ts` stay in `packages/web`; the regex requires `test/` as a whole segment or a `.test.`/`.spec.` suffix. The one deliberate overlap is `packages/pieces/framework/src/lib/test/index.ts` — shipped `createMockActionContext` helpers, counted as tests, and exempt either way because pieces are exempt.- **A job-level `env:` in `ci.yml` does not reach anything turbo runs.** Turbo 2.x defaults to `--env-mode=strict`: a task's process only receives variables named in `globalPassThroughEnv` / `passThroughEnv` / `env`, plus turbo's own system list. Everything else is dropped silently, so the task falls back to whatever `packages/server/api/.env.tests` set (dotenv there runs without `override`, so a real env var would otherwise win). Symptom: the workflow clearly sets the variable and the test still uses the old value. Add the name to `globalPassThroughEnv` in `turbo.json` — that is why `AP_DB_TYPE` and `AP_POSTGRES_*` are already listed. Jobs that call `npx vitest` directly, like `tool-search-postgres`, are unaffected, which is what makes the difference easy to miss. Verify with a throwaway test that `console.log`s the variable through `npx turbo run <task> --filter=<pkg>`.- **A GitHub service container is not reachable by its name from a non-container job.** `services:` attaches the container to a docker network with a `--network-alias`, but the runner itself is on the host, so the alias does not resolve (`getaddrinfo EAI_AGAIN redis`) and only the published `ports:` mapping on `localhost` works. `.env.tests` pins `AP_REDIS_HOST=redis` for `docker-compose`, so any test that opens a real connection needs `localhost` forced past it.diff --git a/brain/knowledge/engineering/platform-admin-structure.md b/brain/knowledge/engineering/platform-admin-structure.mdindex 81b053274b6..614ecd39778 100644--- a/brain/knowledge/engineering/platform-admin-structure.md+++ b/brain/knowledge/engineering/platform-admin-structure.md@@ -150,6 +150,9 @@ silently. Worker groups is the last page on the old full-page teaser.## Gotchas+- **One purple button per admin page: the header action.** An empty state's own button repeats that action, so it is `variant="outline"` (AI Center Providers "Add key", Tiers "New tier"), and cards below it carry no buttons of their own. Four primaries on one empty Providers page was the complaint that set this.+- **`AdminEmpty`'s `icon` is boxed in a 40px tile; anything wider goes in `media`.** `icon` renders inside `EmptyMedia variant="icon"`, which clips a logo row or illustration to one square. `media` renders unboxed (the AI Center providers empty state passes an `AvatarGroup` of provider logos there).+- **A `SettingsPanel` header centres its title against its action only when it has no description.** With a description the title block is two lines, so it stays top-aligned; without one, top alignment left a one-line title floating above a taller button (the AI Center provider cards). Pass no `description` rather than an empty one, or the panel keeps the top alignment.- **Adding an admin page is three edits**: the sidebar (`components/sidebar/platform`), the route(`platform-routes.tsx`), and global search (`components/global-search/static-pages.ts`). Nothingchecks the three agree. A page whose locked state is the sample overlay also needs adiff --git a/packages/web/public/locales/en/translation.json b/packages/web/public/locales/en/translation.jsonindex 180dac4fc7c..0c7606996a1 100644--- a/packages/web/public/locales/en/translation.json+++ b/packages/web/public/locales/en/translation.json@@ -2126,7 +2126,7 @@"Connect a provider": "Connect a provider","Models and project access stay as they are.": "Models and project access stay as they are.","We verify the credentials, then you pick models and projects.": "We verify the credentials, then you pick models and projects.",- "Select provider": "Select provider",+ "Search providers": "Search providers","e.g. Marketing": "e.g. Marketing","Save credentials": "Save credentials","How to get {name} credentials": "How to get {name} credentials",@@ -2147,20 +2147,16 @@"Add key": "Add key","AI providers": "AI providers","Also available": "Also available",- "Bring your own API key to connect any of these.": "Bring your own API key to connect any of these.",+ "No providers yet": "No providers yet",+ "Add an API key to turn on chat, agents and AI steps.": "Add an API key to turn on chat, agents and AI steps.",+ "Choose a provider": "Choose a provider","Your plan does not include Bring your own AI keys": "Your plan does not include Bring your own AI keys","You can still delete the keys below. Upgrade your plan to add new keys or change existing ones.": "You can still delete the keys below. Upgrade your plan to add new keys or change existing ones.",- "configurationsCount": "{count, plural, =1 {1 key} other {# keys}}","Keys": "Keys","modelsCount": "{count, plural, =1 {1 model} other {# models}}","exceptProjectsCount": "{count, plural, =1 {All except 1 project} other {All except # projects}}","projectsCount": "{count, plural, =1 {1 project} other {# projects}}","{count} projects have access. Excluded: {names}": "{count} projects have access. Excluded: {names}",- "Connect your first provider": "Connect your first provider",- "Bring an API key, then pick which models and projects can use it. Chat, agents, and AI steps run through it.": "Bring an API key, then pick which models and projects can use it. Chat, agents, and AI steps run through it.",- "Or choose another provider": "Or choose another provider",- "Claude models — strong for chat and agents": "Claude models — strong for chat and agents",- "GPT models — broad ecosystem and tooling": "GPT models — broad ecosystem and tooling","Search models": "Search models","Sort": "Sort","Loading models…": "Loading models…",diff --git a/packages/web/src/app/components/admin/admin-empty.tsx b/packages/web/src/app/components/admin/admin-empty.tsxindex 513650ec749..ae2e7c7a7dd 100644--- a/packages/web/src/app/components/admin/admin-empty.tsx+++ b/packages/web/src/app/components/admin/admin-empty.tsx@@ -14,6 +14,7 @@ import { adminSurface } from './admin-surface';export function AdminEmpty({icon,+ media,title,description,action,@@ -29,6 +30,7 @@ export function AdminEmpty({)}><EmptyHeader>+ {media && <EmptyMedia>{media}</EmptyMedia>}{icon && <EmptyMedia variant="icon">{icon}</EmptyMedia>}<EmptyTitle>{title}</EmptyTitle>{description && <EmptyDescription>{description}</EmptyDescription>}@@ -40,6 +42,7 @@ export function AdminEmpty({type AdminEmptyProps = {icon?: ReactNode;+ media?: ReactNode;title: ReactNode;description?: ReactNode;action?: ReactNode;diff --git a/packages/web/src/app/components/admin/settings-panel.tsx b/packages/web/src/app/components/admin/settings-panel.tsxindex 0dd5e9c9791..4920dc1bcae 100644--- a/packages/web/src/app/components/admin/settings-panel.tsx+++ b/packages/web/src/app/components/admin/settings-panel.tsx@@ -23,7 +23,8 @@ export function SettingsPanel({<headerclassName={cn(adminSurface.panelHeader,- 'flex items-start justify-between gap-4 p-5',+ 'flex justify-between gap-4 p-5',+ description ? 'items-start' : 'items-center',)}><div className="flex min-w-0 flex-col gap-1">diff --git a/packages/web/src/app/routes/platform/setup/ai/capabilities-tab/index.tsx b/packages/web/src/app/routes/platform/setup/ai/capabilities-tab/index.tsxindex 2ca18719dba..4ce773da33d 100644--- a/packages/web/src/app/routes/platform/setup/ai/capabilities-tab/index.tsx+++ b/packages/web/src/app/routes/platform/setup/ai/capabilities-tab/index.tsx@@ -68,11 +68,6 @@ export function CapabilitiesTab() {<><AdminPageHeadertitle={t('Assistant capabilities')}- badge={- <span className="text-sm tabular-nums text-gray-11">- {AI_TOOL_CATALOG.length}- </span>- }description={t('Search and images use your AI provider. Scraping needs a service of its own. Connect a service to use it in place of your provider.',)}diff --git a/packages/web/src/app/routes/platform/setup/ai/components/ai-center-trail.tsx b/packages/web/src/app/routes/platform/setup/ai/components/ai-center-trail.tsxnew file mode 100644index 00000000000..6aa95e61764--- /dev/null+++ b/packages/web/src/app/routes/platform/setup/ai/components/ai-center-trail.tsx@@ -0,0 +1,45 @@+import { Fragment } from 'react';+import { Link } from 'react-router-dom';++import {+ Breadcrumb,+ BreadcrumbItem,+ BreadcrumbLink,+ BreadcrumbList,+ BreadcrumbSeparator,+} from '@/components/ui/breadcrumb';++export function AiCenterTrail({+ crumbs,+ current,+}: {+ crumbs: { label: string; to: string }[];+ current: string;+}) {+ return (+ <Breadcrumb>+ <BreadcrumbList className="gap-2 text-2xl font-semibold tracking-tight sm:gap-2">+ {crumbs.map((crumb) => (+ <Fragment key={crumb.to}>+ <BreadcrumbItem>+ <BreadcrumbLink+ asChild+ className="rounded-md text-gray-11 hover:text-gray-12 focus-visible:outline-none focus-visible:ring-[3px] focus-visible:ring-gray-8/50"+ >+ <Link to={crumb.to}>{crumb.label}</Link>+ </BreadcrumbLink>+ </BreadcrumbItem>+ <BreadcrumbSeparator className="font-normal text-gray-8">+ /+ </BreadcrumbSeparator>+ </Fragment>+ ))}+ <BreadcrumbItem className="min-w-0">+ <h1 aria-current="page" className="min-w-0 break-words text-gray-12">+ {current}+ </h1>+ </BreadcrumbItem>+ </BreadcrumbList>+ </Breadcrumb>+ );+}diff --git a/packages/web/src/app/routes/platform/setup/ai/providers-tab/config-detail.tsx b/packages/web/src/app/routes/platform/setup/ai/providers-tab/config-detail.tsxindex 79026a0921f..f098d37e66c 100644--- a/packages/web/src/app/routes/platform/setup/ai/providers-tab/config-detail.tsx+++ b/packages/web/src/app/routes/platform/setup/ai/providers-tab/config-detail.tsx@@ -54,6 +54,8 @@ import { platformModelTierQueries } from '@/features/platform-admin/hooks/platfoimport { AdminControl, adminControl } from '@/lib/admin-control';import { formatUtils } from '@/lib/format-utils';+import { AiCenterTrail } from '../components/ai-center-trail';+import { KeyModelList } from './key-model-list';import { KeyStatusBadge } from './key-status';import { ManualModelList } from './manual-model-list';@@ -221,8 +223,12 @@ export function ConfigDetail({return (<><AdminPageHeader- title={draft.name}- back={{ label: t('Providers'), to: '/platform/ai' }}+ title={+ <AiCenterTrail+ crumbs={[{ label: t('Providers'), to: '/platform/ai' }]}+ current={draft.name}+ />+ }badge={<KeyStatusBadge status={config.status} />}description={<span className="flex items-center gap-2">diff --git a/packages/web/src/app/routes/platform/setup/ai/providers-tab/connect-provider-dialog.tsx b/packages/web/src/app/routes/platform/setup/ai/providers-tab/connect-provider-dialog.tsxindex 9df7dd6edeb..58b87f19eaf 100644--- a/packages/web/src/app/routes/platform/setup/ai/providers-tab/connect-provider-dialog.tsx+++ b/packages/web/src/app/routes/platform/setup/ai/providers-tab/connect-provider-dialog.tsx@@ -15,6 +15,7 @@ import { z } from 'zod';import { adminLayout } from '@/app/components/admin';import { DictionaryInput } from '@/components/custom/dictionary-input';import { ApMarkdown } from '@/components/custom/markdown';+import { SearchableSelect } from '@/components/custom/searchable-select';import { Button } from '@/components/ui/button';import {Collapsible,@@ -166,36 +167,29 @@ function ConnectProviderForm({render={({ field }) => (<FormItem className="flex flex-col gap-1.5"><FormLabel showRequiredIndicator>{t('Provider')}</FormLabel>- <Select- value={field.value}- onValueChange={(selected) => {- const next = selected as AIProviderName;- field.onChange(next);- form.setValue('credentials', emptyCredentialsOf(next));- form.setValue('headers', {});- form.setValue('name', defaultNameOf(next));- }}- disabled={editing !== undefined}- >- <FormControl>- <SelectTrigger>- <SelectValue placeholder={t('Select provider')} />- </SelectTrigger>- </FormControl>- <SelectContent>- {SUPPORTED_AI_PROVIDERS.map((candidate) => (- <SelectItem- key={candidate.provider}- value={candidate.provider}- >- <div className="flex items-center gap-2">- <ProviderLogo info={candidate} size="sm" />- <span>{candidate.name}</span>- </div>- </SelectItem>- ))}- </SelectContent>- </Select>+ <FormControl>+ <SearchableSelect+ value={field.value}+ options={SUPPORTED_AI_PROVIDERS.map((candidate) => ({+ value: candidate.provider,+ label: candidate.name,+ }))}+ placeholder={t('Search providers')}+ disabled={editing !== undefined}+ valuesRendering={(value) => (+ <ProviderOption provider={value} />+ )}+ onChange={(next) => {+ if (next === null || next === field.value) {+ return;+ }+ field.onChange(next);+ form.setValue('credentials', emptyCredentialsOf(next));+ form.setValue('headers', {});+ form.setValue('name', defaultNameOf(next));+ }}+ />+ </FormControl><FormMessage /></FormItem>)}@@ -366,6 +360,21 @@ function SecretInput({);}+function ProviderOption({ provider }: { provider: unknown }) {+ const info = SUPPORTED_AI_PROVIDERS.find(+ (candidate) => candidate.provider === provider,+ );+ if (!info) {+ return null;+ }+ return (+ <span className="flex min-w-0 items-center gap-2">+ <ProviderLogo info={info} size="sm" />+ <span className="truncate">{info.name}</span>+ </span>+ );+}+function SetupInstructions({ info }: { info: AiProviderInfo }) {const [open, setOpen] = useState(false);return (diff --git a/packages/web/src/app/routes/platform/setup/ai/providers-tab/index.tsx b/packages/web/src/app/routes/platform/setup/ai/providers-tab/index.tsxindex 8469d48dbb6..b0b2af9b9ca 100644--- a/packages/web/src/app/routes/platform/setup/ai/providers-tab/index.tsx+++ b/packages/web/src/app/routes/platform/setup/ai/providers-tab/index.tsx@@ -7,7 +7,15 @@ import {} from '@activepieces/shared';import { useQueryClient } from '@tanstack/react-query';import { t } from 'i18next';-import { Bot, ChevronRight, Lock, Plus, Trash2 } from 'lucide-react';+import {+ ChevronRight,+ Cpu,+ Layers,+ LayoutGrid,+ Lock,+ Plus,+ Trash2,+} from 'lucide-react';import { useState } from 'react';import { useSearchParams } from 'react-router-dom';import { toast } from 'sonner';@@ -23,7 +31,10 @@ import {import { PlanFeatureSample } from '@/app/routes/platform/plan-feature-sample';import { DataFetchErrorState } from '@/components/custom/data-fetch-error-state';import { ConfirmationDeleteDialog } from '@/components/custom/delete-dialog';+import { LogoPlate } from '@/components/custom/logo-plate';+import { TextWithTooltip } from '@/components/custom/text-with-tooltip';import { Alert, AlertDescription, AlertTitle } from '@/components/ui/alert';+import { Avatar, AvatarGroup, AvatarGroupCount } from '@/components/ui/avatar';import { Button } from '@/components/ui/button';import { Skeleton } from '@/components/ui/skeleton';import {@@ -211,11 +222,6 @@ export function ProvidersTab() {<><AdminPageHeadertitle={t('Providers')}- badge={- <span className="text-sm tabular-nums text-gray-11">- {configs.length}- </span>- }description={configs.length === 0? t(@@ -264,26 +270,11 @@ export function ProvidersTab() {/>))}{!locked && available.length > 0 && (- <AdminSection- title={- <span className="flex items-baseline gap-2">- {t('Also available')}- <span className="text-sm font-normal tabular-nums text-gray-11">- {available.length}- </span>- </span>- }- description={t('Bring your own API key to connect any of these.')}- >- <div className="grid grid-cols-1 gap-4 lg:grid-cols-2">- {available.map((info) => (- <AvailableProviderCard- key={info.provider}- info={info}- onConnect={() => openConnect(info.provider)}- />- ))}- </div>+ <AdminSection title={t('Also available')}>+ <ProviderTileGrid+ providers={available}+ onConnect={(provider) => openConnect(provider)}+ /></AdminSection>)}</>@@ -367,17 +358,13 @@ function ProviderGroup({}return (- <SettingsPanel- flush- title={- <span className="flex items-center gap-2">- <ProviderLogo info={info} size="sm" />+ <SettingsPanel flush>+ <header className="flex items-center gap-3 px-4 py-3">+ <ProviderLogo info={info} />+ <h2 className="min-w-0 flex-1 truncate text-sm font-medium text-gray-12">{info.name}- </span>- }- description={t('configurationsCount', { count: configs.length })}- action={- locked ? undefined : (+ </h2>+ {!locked && (<Buttonvariant="ghost"size="sm"@@ -387,10 +374,12 @@ function ProviderGroup({<Plus className="size-4" />{t('Add key')}</Button>- )- }- >- <p className="px-5 py-2 text-xs font-medium text-gray-11">{t('Keys')}</p>+ )}+ </header>+ <p className="flex items-center gap-1.5 px-4 py-1.5 text-xs font-medium text-gray-11">+ {t('Keys')}+ <span className="tabular-nums">{configs.length}</span>+ </p>{configs.map((config) => (<ConfigRowkey={config.id}@@ -456,38 +445,43 @@ function ConfigRow({}}}className={cn(- 'group flex items-center gap-4 px-5 py-3 transition-colors',+ 'group flex items-center gap-4 px-4 py-3 transition-colors',!locked &&'cursor-pointer hover:bg-gray-4 active:bg-gray-5 focus-visible:bg-gray-4 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-gray-8',)}>- <div className="flex min-w-0 flex-1 flex-col gap-1">- <div className="flex min-w-0 items-center gap-2">- <p className="truncate text-sm font-medium text-gray-12">+ <div className="flex min-w-0 flex-1 flex-col gap-1.5">+ <div className="flex min-w-0 items-center gap-2.5">+ <p className="truncate text-sm font-semibold text-gray-12">{config.name}</p><KeyStatusBadge status={config.status} /></div>- <Tooltip>- <TooltipTrigger asChild>- <p className="w-fit truncate text-xs text-gray-11">- {modelsLabel}- <span aria-hidden> · </span>- {projectsLabel}- {tierCount > 0 && (- <>- <span aria-hidden> · </span>- {t('usedByTiersCount', { count: tierCount })}- </>- )}- </p>- </TooltipTrigger>- {config.modelIds.length > 0 && (- <TooltipContent className="max-w-64">- {config.modelIds.join(', ')}- </TooltipContent>+ <div className="flex flex-wrap items-center gap-x-4 gap-y-1 text-xs text-gray-11 [&_svg]:text-gray-9">+ <Tooltip>+ <TooltipTrigger asChild>+ <span className="inline-flex items-center gap-1">+ <Cpu className="size-3.5" />+ {modelsLabel}+ </span>+ </TooltipTrigger>+ {config.modelIds.length > 0 && (+ <TooltipContent className="max-w-64">+ {config.modelIds.join(', ')}+ </TooltipContent>+ )}+ </Tooltip>+ <span className="inline-flex items-center gap-1">+ <LayoutGrid className="size-3.5" />+ {projectsLabel}+ </span>+ {tierCount > 0 && (+ <span className="inline-flex items-center gap-1">+ <Layers className="size-3.5" />+ {t('usedByTiersCount', { count: tierCount })}+ </span>)}- </Tooltip>+ </div></div>{config.projectScope !== 'all' && (@@ -590,87 +584,118 @@ function EmptyProviders({}: {onConnect: (provider?: AIProviderName) => void;}) {- const recommended = RECOMMENDED_PROVIDERS.map((provider) =>- SUPPORTED_AI_PROVIDERS.find((info) => info.provider === provider),- ).filter((info): info is AiProviderInfo => info !== undefined);- const others = SUPPORTED_AI_PROVIDERS.filter(- ({ provider }) => !RECOMMENDED_PROVIDERS.includes(provider),- );-return (<><AdminEmpty- icon={<Bot />}- title={t('Connect your first provider')}- description={t(- 'Bring an API key, then pick which models and projects can use it. Chat, agents, and AI steps run through it.',- )}+ media={<ProviderFaces />}+ title={t('No providers yet')}+ description={t('Add an API key to turn on chat, agents and AI steps.')}action={<Button+ variant="outline"onClick={() => onConnect()}{...adminControl(AdminControl.AI_PROVIDER_KEY_OPEN)}><Plus className="size-4" />- {t('Connect a provider')}+ {t('Add key')}</Button>}/>- <div className="grid grid-cols-1 gap-4 sm:grid-cols-2">- {recommended.map((info) => (- <AvailableProviderCard- key={info.provider}- info={info}- tagline={recommendedTagline({ provider: info.provider })}- recommended- onConnect={() => onConnect(info.provider)}- />- ))}- </div>- <AdminSection title={t('Or choose another provider')}>- <div className="grid grid-cols-1 gap-4 lg:grid-cols-2">- {others.map((info) => (- <AvailableProviderCard- key={info.provider}- info={info}- onConnect={() => onConnect(info.provider)}- />- ))}- </div>+ <AdminSection title={t('Choose a provider')}>+ <ProviderTileGrid+ providers={SUPPORTED_AI_PROVIDERS}+ onConnect={onConnect}+ /></AdminSection></>);}-function AvailableProviderCard({+function ProviderFaces() {+ const ranked = byImportance(SUPPORTED_AI_PROVIDERS);+ const shown = ranked.slice(0, PROVIDER_FACES_SHOWN);+ return (+ <AvatarGroup>+ {shown.map((info) => (+ <Avatar key={info.provider} size="lg" className="size-9">+ <LogoPlate+ src={info.logoUrl}+ alt={info.name}+ border+ className="size-full rounded-full"+ innerClassName="p-2"+ />+ </Avatar>+ ))}+ <AvatarGroupCount className="size-9 border border-gray-6 text-xs font-medium tabular-nums">+ {t('+{count}', { count: ranked.length - shown.length })}+ </AvatarGroupCount>+ </AvatarGroup>+ );+}++function ProviderTileGrid({+ providers,+ onConnect,+}: {+ providers: AiProviderInfo[];+ onConnect: (provider: AIProviderName) => void;+}) {+ return (+ <div className="grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-3">+ {byImportance(providers).map((info) => (+ <ProviderTile+ key={info.provider}+ info={info}+ recommended={RECOMMENDED_PROVIDERS.includes(info.provider)}+ onConnect={() => onConnect(info.provider)}+ />+ ))}+ </div>+ );+}++function ProviderTile({info,- tagline,recommended,onConnect,}: {info: AiProviderInfo;- tagline?: string;- recommended?: boolean;+ recommended: boolean;onConnect: () => void;}) {return (- <div className={cn(adminSurface.card, 'flex items-center gap-4 p-5')}>+ <button+ type="button"+ onClick={onConnect}+ className={cn(+ adminSurface.card,+ 'group flex min-w-0 items-center gap-3 px-4 py-3 text-left transition-colors hover:bg-gray-3 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-gray-8',+ recommended && 'border-accent-8',+ )}+ {...adminControl(AdminControl.AI_PROVIDER_OPEN)}+ ><ProviderLogo info={info} />- <div className="flex min-w-0 flex-1 flex-col gap-1">- <p className="truncate text-sm font-medium text-gray-12">{info.name}</p>- {tagline && <p className="truncate text-xs text-gray-11">{tagline}</p>}- </div>- <Button- size="sm"- variant={recommended ? 'default' : 'outline'}- onClick={onConnect}- {...adminControl(AdminControl.AI_PROVIDER_OPEN)}- >- {t('Connect')}- </Button>- </div>+ <span className="flex min-w-0 flex-1">+ <TextWithTooltip tooltipMessage={info.name}>+ <span className="truncate text-sm font-medium text-gray-12">+ {info.name}+ </span>+ </TextWithTooltip>+ </span>+ <ChevronRight className="size-4 shrink-0 text-gray-9 transition-transform duration-150 group-hover:translate-x-0.5 group-hover:text-gray-12" />+ </button>);}+function byImportance(providers: AiProviderInfo[]): AiProviderInfo[] {+ const rank = (provider: AIProviderName) => {+ const index = PROVIDERS_BY_IMPORTANCE.indexOf(provider);+ return index === -1 ? PROVIDERS_BY_IMPORTANCE.length : index;+ };+ return [...providers].sort((a, b) => rank(a.provider) - rank(b.provider));+}+function ProvidersSkeleton() {return (<>@@ -725,22 +750,30 @@ function providerInfoOf({);}+const PROVIDER_FACES_SHOWN = 5;+const RECOMMENDED_PROVIDERS: AIProviderName[] = [AIProviderName.ANTHROPIC,AIProviderName.OPENAI,];-function recommendedTagline({- provider,-}: {- provider: AIProviderName;-}): string | undefined {- switch (provider) {- case AIProviderName.ANTHROPIC:- return t('Claude models — strong for chat and agents');- case AIProviderName.OPENAI:- return t('GPT models — broad ecosystem and tooling');- default:- return undefined;- }-}+const PROVIDERS_BY_IMPORTANCE: AIProviderName[] = [+ AIProviderName.ANTHROPIC,+ AIProviderName.OPENAI,+ AIProviderName.GOOGLE,+ AIProviderName.AZURE,+ AIProviderName.BEDROCK,+ AIProviderName.VERTEX,+ AIProviderName.META,+ AIProviderName.MISTRAL,+ AIProviderName.XAI,+ AIProviderName.DEEPSEEK,+ AIProviderName.OPENROUTER,+ AIProviderName.QWEN,+ AIProviderName.NVIDIA,+ AIProviderName.MOONSHOT,+ AIProviderName.MINIMAX,+ AIProviderName.ZAI,+ AIProviderName.CLOUDFLARE_GATEWAY,+ AIProviderName.CUSTOM,+];diff --git a/packages/web/src/app/routes/platform/setup/ai/providers-tab/key-status.tsx b/packages/web/src/app/routes/platform/setup/ai/providers-tab/key-status.tsxindex 05315b135da..f9ec7378c32 100644--- a/packages/web/src/app/routes/platform/setup/ai/providers-tab/key-status.tsx+++ b/packages/web/src/app/routes/platform/setup/ai/providers-tab/key-status.tsx@@ -2,14 +2,22 @@ import { isNil } from '@activepieces/core-utils';import { AiProviderKeyStatus } from '@activepieces/shared';import { t } from 'i18next';-import { StatusDot, StatusTone } from '@/app/components/admin';+import { Badge } from '@/components/ui/badge';export function KeyStatusBadge({ status }: { status: AiProviderKeyStatus }) {const badge = badgeOf({ status });if (isNil(badge)) {return null;}- return <StatusDot tone={badge.tone}>{badge.text}</StatusDot>;+ return (+ <Badge+ variant={badge.variant}+ className="gap-1.5 rounded-full border-transparent px-2"+ >+ <span aria-hidden className="size-1.5 rounded-full bg-current" />+ {badge.text}+ </Badge>+ );}export function keyStatusText({@@ -22,17 +30,17 @@ export function keyStatusText({function badgeOf({ status }: { status: AiProviderKeyStatus }): {text: string;- tone: StatusTone;+ variant: 'success' | 'warning' | 'destructive' | 'secondary';} | null {switch (status) {case 'active':- return { text: t('Active'), tone: 'success' };+ return { text: t('Active'), variant: 'success' };case 'out_of_credits':- return { text: t('Out of credits'), tone: 'warning' };+ return { text: t('Out of credits'), variant: 'warning' };case 'rejected':- return { text: t('Key rejected'), tone: 'danger' };+ return { text: t('Key rejected'), variant: 'destructive' };case 'unreachable':- return { text: t('Unreachable'), tone: 'neutral' };+ return { text: t('Unreachable'), variant: 'secondary' };default:return null;}diff --git a/packages/web/src/app/routes/platform/setup/ai/providers-tab/provider-logo.tsx b/packages/web/src/app/routes/platform/setup/ai/providers-tab/provider-logo.tsxindex 1a52dde37b7..b872937f052 100644--- a/packages/web/src/app/routes/platform/setup/ai/providers-tab/provider-logo.tsx+++ b/packages/web/src/app/routes/platform/setup/ai/providers-tab/provider-logo.tsx@@ -10,14 +10,15 @@ export function ProviderLogo({}) {if (!info.logoUrl) {return size === 'sm' ? null : (- <div className="size-8 shrink-0 rounded-xl bg-gray-3" />+ <div className="size-9 shrink-0 rounded-lg bg-gray-3" />);}return (<LogoPlatesrc={info.logoUrl}alt={info.name}- className={size === 'sm' ? 'size-4' : 'size-8 rounded-xl p-2'}+ size={size === 'sm' ? undefined : 'md'}+ className={size === 'sm' ? 'size-4' : 'rounded-lg'}/>);}diff --git a/packages/web/src/app/routes/platform/setup/ai/tiers-tab/index.tsx b/packages/web/src/app/routes/platform/setup/ai/tiers-tab/index.tsxindex 39661c2a33d..bad7ac2a96a 100644--- a/packages/web/src/app/routes/platform/setup/ai/tiers-tab/index.tsx+++ b/packages/web/src/app/routes/platform/setup/ai/tiers-tab/index.tsx@@ -105,7 +105,6 @@ export function TiersTab() {<SectionHeadertitle={t('Tiers')}isPageTitle- count={isError ? undefined : liveTiers.length}description={t('Named model groups your builders pick. Each one is a main model plus fallbacks.',)}@@ -328,6 +327,7 @@ function NoTiersState({</p></div><Button+ variant="outline"onClick={(event) => onCreate(event.currentTarget)}{...adminControl(AdminControl.AI_TIER_OPEN)}>diff --git a/packages/web/src/app/routes/platform/setup/ai/usage-tab/usage-bits.tsx b/packages/web/src/app/routes/platform/setup/ai/usage-tab/usage-bits.tsxindex 6a8185b7a86..9fb372440da 100644--- a/packages/web/src/app/routes/platform/setup/ai/usage-tab/usage-bits.tsx+++ b/packages/web/src/app/routes/platform/setup/ai/usage-tab/usage-bits.tsx@@ -16,17 +16,8 @@ import {User,Workflow,} from 'lucide-react';-import { Fragment } from 'react';-import { Link } from 'react-router-dom';import { LogoPlate } from '@/components/custom/logo-plate';-import {- Breadcrumb,- BreadcrumbItem,- BreadcrumbLink,- BreadcrumbList,- BreadcrumbSeparator,-} from '@/components/ui/breadcrumb';import { SUPPORTED_AI_PROVIDERS } from '@/features/agents';import { cn } from '@/lib/utils';@@ -129,41 +120,6 @@ export function UsageEmptyState({);}-export function UsageTrail({- crumbs,- current,-}: {- crumbs: { label: string; to: string }[];- current: string;-}) {- return (- <Breadcrumb>- <BreadcrumbList className="gap-2 text-2xl font-semibold tracking-tight sm:gap-2">- {crumbs.map((crumb) => (- <Fragment key={crumb.to}>- <BreadcrumbItem>- <BreadcrumbLink- asChild- className="rounded-md text-gray-11 hover:text-gray-12 focus-visible:outline-none focus-visible:ring-[3px] focus-visible:ring-gray-8/50"- >- <Link to={crumb.to}>{crumb.label}</Link>- </BreadcrumbLink>- </BreadcrumbItem>- <BreadcrumbSeparator className="font-normal text-gray-8">- /- </BreadcrumbSeparator>- </Fragment>- ))}- <BreadcrumbItem className="min-w-0">- <h1 aria-current="page" className="min-w-0 break-words text-gray-12">- {current}- </h1>- </BreadcrumbItem>- </BreadcrumbList>- </Breadcrumb>- );-}-export function relatedSpan({index,count,diff --git a/packages/web/src/app/routes/platform/setup/ai/usage-tab/usage-detail-page.tsx b/packages/web/src/app/routes/platform/setup/ai/usage-tab/usage-detail-page.tsxindex 525e7aff37f..981109ad0aa 100644--- a/packages/web/src/app/routes/platform/setup/ai/usage-tab/usage-detail-page.tsx+++ b/packages/web/src/app/routes/platform/setup/ai/usage-tab/usage-detail-page.tsx@@ -27,8 +27,10 @@ import { Button } from '@/components/ui/button';import { aiUsageHooks } from '@/features/ai-usage';import { flagsHooks } from '@/hooks/flags-hooks';+import { AiCenterTrail } from '../components/ai-center-trail';+import { usageAdapters } from './usage-adapters';-import { relatedSpan, UsageTrail } from './usage-bits';+import { relatedSpan } from './usage-bits';import { UsageEmpty } from './usage-empty';import { usageFormat } from './usage-format';import {@@ -60,7 +62,7 @@ export function UsageDetailPage() {<><AdminPageHeadertitle={- <UsageTrail+ <AiCenterTrailcrumbs={[{ label: t('AI usage'), to: overviewLink },{diff --git a/packages/web/src/app/routes/platform/setup/ai/usage-tab/usage-list-page.tsx b/packages/web/src/app/routes/platform/setup/ai/usage-tab/usage-list-page.tsxindex 98cf78c52ea..6002505b28d 100644--- a/packages/web/src/app/routes/platform/setup/ai/usage-tab/usage-list-page.tsx+++ b/packages/web/src/app/routes/platform/setup/ai/usage-tab/usage-list-page.tsx@@ -23,8 +23,10 @@ import {import { aiUsageHooks } from '@/features/ai-usage';import { cn } from '@/lib/utils';+import { AiCenterTrail } from '../components/ai-center-trail';+import { usageAdapters } from './usage-adapters';-import { DeltaChip, ItemIcon, USAGE_LIST_GRID, UsageTrail } from './usage-bits';+import { DeltaChip, ItemIcon, USAGE_LIST_GRID } from './usage-bits';import { UsageEmpty } from './usage-empty';import { usageFormat } from './usage-format';import {@@ -53,7 +55,7 @@ export function UsageListPage() {<><AdminPageHeadertitle={- <UsageTrail+ <AiCenterTrailcrumbs={[{ label: t('AI usage'), to: `/platform/ai/usage${view.search}` },]}diff --git a/packages/web/src/components/custom/searchable-select.tsx b/packages/web/src/components/custom/searchable-select.tsxindex ed7fefe163f..89333ee8822 100644--- a/packages/web/src/components/custom/searchable-select.tsx+++ b/packages/web/src/components/custom/searchable-select.tsx@@ -56,6 +56,9 @@ type SearchableSelectProps<T> = {label: string;}[];onOptionDelete?: (value: T) => void;+ id?: string;+ 'aria-describedby'?: string;+ 'aria-invalid'?: boolean;};const useOpenState = (openStateInitializer?: {@@ -90,6 +93,9 @@ export const SearchableSelect = <T,>({refreshOnSearch,cachedOptions = [],onOptionDelete,+ id,+ 'aria-describedby': ariaDescribedBy,+ 'aria-invalid': ariaInvalid,}: SearchableSelectProps<T>) => {const triggerRef = useRef<HTMLButtonElement>(null);const [searchTerm, setSearchTerm] = useState('');@@ -159,6 +165,9 @@ export const SearchableSelect = <T,>({<div className="relative"><Buttonref={triggerRef}+ id={id}+ aria-describedby={ariaDescribedBy}+ aria-invalid={ariaInvalid}variant={variant}disabled={disabled}role="combobox"