Skip to content

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

feat(web): admins on cloud find the ai tiers page in the sidebar and search (#16889)

Louai Boumedienee564dee4971b
diff --git a/brain/knowledge/ai-intelligence/ai-providers.md b/brain/knowledge/ai-intelligence/ai-providers.md
index aa306426dc3..b271f90b0ad 100644
--- a/brain/knowledge/ai-intelligence/ai-providers.md
+++ b/brain/knowledge/ai-intelligence/ai-providers.md
@@ -70,7 +70,7 @@ decision 000041. The console publishes both lists and both fast pointers on ever
after a file without chat keys it seeds the chat list from the live flow list.
### Platform tiers
-**Platform tier** — an admin-built, platform-owned list of up to 5 `{configId, modelId}` entries (main + ranked fallbacks, any keys), table `platform_model_tier`, API `/v1/platform-model-tiers`. A tier follows key scope: in a project it runs only the entries whose key serves that project, and it is listed there only when its main entry can run; see decision [000048](../decisions/000048-platform-tiers-follow-key-project-scope.md) (replaces 000044's grant). _Avoid_: "model tier" alone — that is the console **credits tier** (`ModelTier`, above).
+**Platform tier** — an admin-built, platform-owned list of up to 5 `{configId, modelId}` entries (main + ranked fallbacks, any keys), table `platform_model_tier`, API `/v1/platform-model-tiers`. A tier follows key scope: in a project it runs only the entries whose key serves that project, and it is listed there only when its main entry can run; see decision [000048](../decisions/000048-platform-tiers-follow-key-project-scope.md) (replaces 000044's grant). The admin Tiers page (`/platform/ai/tiers`) is listed in the AI Center sidebar and global search on **cloud only** (`edition === CLOUD`, search `requiresEdition`); self-hosted can still open it by URL. _Avoid_: "model tier" alone — that is the console **credits tier** (`ModelTier`, above).
**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)
diff --git a/brain/knowledge/engineering/engineering-handbook-playbooks.md b/brain/knowledge/engineering/engineering-handbook-playbooks.md
index e6add8a47e7..5ec42bd76b0 100644
--- a/brain/knowledge/engineering/engineering-handbook-playbooks.md
+++ b/brain/knowledge/engineering/engineering-handbook-playbooks.md
@@ -21,7 +21,7 @@ Run EE, building for self-hosting, setup BetterStack, releases, canary deploymen
Postmortems (Redis/queue overload, infra upgrade — March 2026) and product interface-design notes.
## Gotchas
-- **Put a scratch worktree *inside* the repo root, or it cannot lint or typecheck at all.** Node resolves `node_modules` by walking up the directory tree, so a worktree at `/tmp/...` finds nothing and eslint dies on `couldn't find the plugin "@typescript-eslint/eslint-plugin"` before it reads a single rule — no install, no symlink, no checks. The same worktree created at `.claude/worktrees/<name>` walks up to the repo root's `node_modules` and runs lint, `tsc` and vitest with zero setup. This is cheaper than both workarounds in the next bullet and has none of the cross-branch skew, because the resolved packages belong to the same checkout. It matters most during a long conflict resolution: files you edit while resolving are easy to treat as "already reviewed" and never check again, and in an unusable worktree you *cannot* check them. A merge resolved in `/tmp` shipped a `sort-imports` error and a `TS2783` to CI this way — both in files touched only during conflict resolution, both caught by the first `turbo run lint` / `turbo run typecheck` that could actually run. After a merge, run the task CI runs (`turbo run lint --filter=<pkg>`), not a list of the files you remember editing.
+- **Put a scratch worktree *inside* the repo root, or it cannot lint or typecheck at all.** Node resolves `node_modules` by walking up the directory tree, so a worktree at `/tmp/...` finds nothing and eslint dies on `couldn't find the plugin "@typescript-eslint/eslint-plugin"` before it reads a single rule — no install, no symlink, no checks. The same worktree created at `.claude/worktrees/<name>` walks up to the repo root's `node_modules` and runs lint, `tsc` and vitest with zero setup. This is cheaper than both workarounds in the next bullet and has none of the cross-branch skew, because the resolved packages belong to the same checkout. It matters most during a long conflict resolution: files you edit while resolving are easy to treat as "already reviewed" and never check again, and in an unusable worktree you *cannot* check them. A merge resolved in `/tmp` shipped a `sort-imports` error and a `TS2783` to CI this way — both in files touched only during conflict resolution, both caught by the first `turbo run lint` / `turbo run typecheck` that could actually run. After a merge, run the task CI runs (`turbo run lint --filter=<pkg>`), not a list of the files you remember editing. Never free space with `find -name node_modules -exec rm -rf`: git tracks a fixture under `packages/server/engine/test/resources/codes/flowVersionId/hello_world_npm/node_modules/`, so the next `git add -A` commits its deletion; restore it with `git checkout HEAD -- $(git ls-tree -r --name-only HEAD | grep /node_modules/)`.
- **Running EE locally (outside the dev container) to preview a chat/agents-gated view hits four macOS-specific walls the [Run EE](https://www.activepieces.com/docs/handbook/engineering/playbooks/run-ee) playbook doesn't cover.** (1) The default dev DB, PGlite (`.env.dev`'s `AP_DB_TYPE=PGLITE`), hard-refuses `AP_EDITION=ee`/`cloud` with `Error: Edition ee not supported in pglite mode in dev environment` — point at a real local Postgres instead (`AP_DB_TYPE=POSTGRES` + a throwaway DB via `createdb`). (2) In a fresh git worktree, symlinking `node_modules` from another worktree/checkout works for lint/typecheck but not for actually running the server: workspace packages resolve through the symlink to whatever commit *that* checkout is on, so a genuine cross-branch source/type skew appears (e.g. `AIProviderName.VERTEX does not exist`) purely from the mismatch — do a real `bun install` scoped to the worktree instead. (3) `bun install` aborts the *entire* install (not just its own package) if `isolated-vm`'s native build fails, which it does on Darwin 25 (`node-gyp` / `undici` `webidl.util.markAsUncloneable is not a function`) — even though `isolated-vm` is only needed by the engine/worker sandbox, not by `api`+`web`. Fix: `bun install --ignore-scripts`, then `cd` into `node_modules/.bun/sqlite3@*/node_modules/sqlite3` and run `npx prebuild-install -r napi` directly to fetch its prebuilt native binding (something in the queue/api dependency tree requires it to *load* even when the configured DB isn't sqlite). (4) The repo requires Node 22.15+/24 (`bootstrap.ts` uses `zlib.zstdDecompress`, added in Node 22.15); a system default of Node 20 (common via `nvm`) crashes API boot with `ERR_INVALID_ARG_TYPE` in `file-compressor.ts` — put a `nvm`-installed v24 first on `PATH` before starting `serve`. Once booted: `AP_EDITION=ee` alone (no license key) is enough to preview chat/agents, since the unlicensed `AUTUMN_FREE_PLAN` already sets `chatEnabled`/`agentsEnabled: true` — but that plan's `aiProvidersEnabled: false` hides the "Connect" button on every provider card, so there is no UI path to satisfy chat's "Set up an AI provider" gate; insert a throwaway row into `ai_provider` directly via SQL (`enabledForChat: true`, `config: '{}'`, any `auth` JSON — it's only decrypted when a message is actually sent) to get past it for pure layout/UI verification.
- **`DISCORD_ON_CALL_WEBHOOK` is the single repo secret behind every on-call Discord notification** — cloud production deploys (`continuous-delivery-cloud.yml`), self-hosted releases (`release-self-hosted.yml`), and release-pieces failure alerts all post through it. Rotating it repoints all of them at once; there is no per-workflow webhook. Self-hosted release notifications skip `-rc` tags unless `publish_rc_release` is set, mirroring the release-drafter condition so the message never links a release page that doesn't exist.
- **Docs media lives on the CDN, never in the repo — and videos and images sit on two different paths.** A video embeds as `<video src="https://cdn.activepieces.com/videos/docs/<Exact-File-Name>.mp4" controls />`, an image as `![Alt](https://cdn.activepieces.com/assets/<exact-file-name>.png)`. Videos are namespaced under `videos/docs/`; images are **flat** under `assets/` with no `docs/` segment, so don't infer one path from the other — check the URL you actually mean. Both mirror the filename verbatim, so an upload is fetchable with no config change. Committing the binary instead bloats every clone forever (`docs/videos/` reached 63 MB and `docs/images/` 1.6 MB before both were removed in Sept 2026) since git history keeps the blob even after a delete. Curl each URL for a 200 before deleting a local copy: `docs/` also carries stale `.mdx` references to images that never existed in git history at all, and rewriting one of those to a CDN URL turns a visibly-missing asset into a confident 404.
diff --git a/brain/knowledge/pieces-engine/pieces.md b/brain/knowledge/pieces-engine/pieces.md
index c92cf7bf048..32070742730 100644
--- a/brain/knowledge/pieces-engine/pieces.md
+++ b/brain/knowledge/pieces-engine/pieces.md
@@ -23,7 +23,7 @@ The metadata catalog of automation integrations ("pieces") — each a named inte
- EE/Cloud per-piece and per-action/trigger visibility flows through `resolveVisibility` (`ee/pieces/filters/piece-filtering-utils.ts`), which returns a `VisibilityPolicy` or `null` on CE / when `platformId`/`projectId` is nil (callers treat `null` as no filtering). The policy is derived from the project's **piece set** (via `project.pieceSetId`, falling back to the platform Default).
- Install and sync also enqueue a tool-search reindex, but only when `isToolSearchEnabled()`; no-op otherwise.
- `delete` removes all versions sharing the name on that platform, and only for `CUSTOM` pieces the caller owns.
-- **A piece silently vanishes from the list when its `minimumSupportedRelease` is ahead of the root `package.json` version.** `fetchLatestPieces` filters every piece through `isSupportedRelease(apVersionUtil.getCurrentRelease(), piece)`. Pieces are routinely merged targeting the *next* release, so on `main` a couple dozen are invisible locally until the version bump lands. No warning is logged — it just isn't there. The same gate hides the version from exact-version lookups (`findExactVersion`), so a flow step saved on it fails to load on an older server, and `AP_DEV_PIECES` does not bypass it: the database copies are dropped by name and the dev copy by release, so the piece vanishes entirely. To test a piece that targets the next release, bump the root `package.json` version locally and do not commit it. A server that already reports that release but lacks the server code the piece needs is the dangerous case; check `origin/main`'s root version at merge time. Cloud runs the same gate on its root version: on 2026-10-20 cloud reported 0.92.2 and served piece-ai 0.11.0 while main had 0.14.1, so every version gated on the next release (0.12 to 0.15) switches on for everyone at once with the bump. See what cloud serves with `curl https://cloud.activepieces.com/api/v1/pieces/@activepieces/piece-<name>` (`version`, `minimumSupportedRelease`). Merging publishes the piece to the registry at once (`release-pieces.yml` on push to main), before any deploy. That is safe because the gate also covers self-hosted: sync asks the registry with `release=<own version>` (`listCloudPieces`), so an older backend never downloads it.
+- **A piece silently vanishes from the list when its `minimumSupportedRelease` is ahead of the root `package.json` version.** `fetchLatestPieces` filters every piece through `isSupportedRelease(apVersionUtil.getCurrentRelease(), piece)`. Pieces are routinely merged targeting the *next* release, so on `main` a couple dozen are invisible locally until the version bump lands. No warning is logged — it just isn't there. The same gate hides the version from exact-version lookups (`findExactVersion`), so a flow step saved on it fails to load on an older server, and `AP_DEV_PIECES` does not bypass it: the database copies are dropped by name and the dev copy by release, so the piece vanishes entirely. To test a piece that targets the next release, bump the root `package.json` version locally and do not commit it. A server that already reports that release but lacks the server code the piece needs is the dangerous case; check `origin/main`'s root version at merge time. Cloud runs the same gate on its root version: on 2026-10-20 cloud reported 0.92.2 and served piece-ai 0.11.0 while main had 0.14.1, so every version gated on the next release (0.12 to 0.15) switches on for everyone at once with the bump. See what cloud serves with `curl https://cloud.activepieces.com/api/v1/pieces/@activepieces/piece-<name>` (`version`, `minimumSupportedRelease`). Merging publishes the piece to the registry at once (`release-pieces.yml` on push to main), before any deploy. That is safe because the gate also covers self-hosted: sync asks the registry with `release=<own version>` (`listCloudPieces`), so an older backend never downloads it. Self-hosted releases are made by hand, so moving the root version on main changes cloud only until someone cuts that self-hosted release; bump it in its own `chore: release X` PR with only `package.json` (leave `docker-compose.yml` and the Helm chart on the last published image), and never revert it: a server that drops back below a gated piece version can no longer load steps saved on it.
- **`/v1/pieces` is uncached, so a new `piece_metadata` column must be added to `PIECE_COLUMNS_WITHOUT_TRANSLATIONS` or it silently will not appear in the list.** `pieceCache` caches only the *registry* (name/version/platformId tuples) for `get`/`findExactVersion`/`registry`; the list path never touches it, and the `dedupe()` helper in `piece-metadata-service.ts` is in-flight-only (it deletes the key in `finally`), so it collapses concurrent callers but caches nothing between requests. Every request therefore re-runs the whole pipeline against the DB. Because of that, `fetchLatestCompatiblePiecesFromDB` selects an explicit column list that deliberately omits `i18n` — that column holds every locale for the piece (~50 MB across the catalogue, written by `pieceInstallService`) and the list path discards it, so loading it was pure waste. Non-English requests now pull only the one locale in a second query (`pm."i18n" -> :locale`) and hand it to `pieceTranslation.translatePiece`. The single-piece path (`get`/`getOrThrow`) selects the same columns and goes through the same `translatePieces`, so no response ever carries `i18n`. The cost is that the explicit select is a list to keep in sync with the entity.
- **Piece sorting mutates its input, which is why the list result cannot simply be cached.** `pieceSorting`'s comparators and `reverseIfDesc` sort in place (`pieces.sort(...)`, `pieces.reverse()`). That is safe only because the array is rebuilt per request; making them non-mutating is a prerequisite for ever caching the built list, or requests would reorder shared state under each other.
- **`translatePiece` is copy-on-write: never deep-clone a piece to translate it, and never cache translated lists.** It copies only the objects on a translated path and returns the input's other subtrees by reference, in one walk over a tree built from `pathsToValuesToTranslate`. The input is shared through `dedupe()` across concurrent requests in different locales, so mutating it leaks one locale into another. The old `JSON.parse(JSON.stringify(piece))` made every non-English list ~3x slower than English (GIT-1891), and caching the translated catalogue per locale was tried twice (#15340, #15639) and dropped over memory. `packages/pieces/framework/test/i18n.test.ts` fails if a deep clone comes back. Translations are read from `piece_translation` (one row per piece version and locale, `pieceTranslationService`), not from the `json` `i18n` column: extracting one locale from that column re-parsed every locale (~160 ms on prod, paid even for a locale with no rows) and was ~5x slower than the table (GIT-2013).
diff --git a/packages/web/src/app/components/global-search/static-pages.ts b/packages/web/src/app/components/global-search/static-pages.ts
index 54163e1d04f..b648794a21d 100644
--- a/packages/web/src/app/components/global-search/static-pages.ts
+++ b/packages/web/src/app/components/global-search/static-pages.ts
@@ -1,3 +1,5 @@
+import { isNil } from '@activepieces/core-utils';
+import { ApEdition } from '@activepieces/shared';
import { type ComponentType } from 'react';
import { BotIcon } from '@/components/icons/bot';
@@ -29,6 +31,7 @@ export type StaticPage = {
href: string;
icon: ComponentType<{ className?: string; size?: number }>;
requiresPlatformAdmin?: boolean;
+ requiresEdition?: ApEdition;
};
export const STATIC_PAGES: StaticPage[] = [
@@ -78,6 +81,14 @@ export const STATIC_PAGES: StaticPage[] = [
icon: BotIcon,
requiresPlatformAdmin: true,
},
+ {
+ id: 'page-platform-ai-tiers',
+ label: 'Platform Admin — AI Tiers',
+ href: '/platform/ai/tiers',
+ icon: BotIcon,
+ requiresPlatformAdmin: true,
+ requiresEdition: ApEdition.CLOUD,
+ },
{
id: 'page-platform-ai-capabilities',
label: 'Platform Admin — AI Capabilities',
@@ -240,3 +251,20 @@ export const STATIC_PAGES: StaticPage[] = [
requiresPlatformAdmin: true,
},
];
+
+function isVisible({
+ page,
+ isPlatformAdmin,
+ edition,
+}: {
+ page: StaticPage;
+ isPlatformAdmin: boolean;
+ edition: ApEdition | null;
+}): boolean {
+ return (
+ (!page.requiresPlatformAdmin || isPlatformAdmin) &&
+ (isNil(page.requiresEdition) || page.requiresEdition === edition)
+ );
+}
+
+export const staticPageUtils = { isVisible };
diff --git a/packages/web/src/app/components/global-search/use-global-search-results.ts b/packages/web/src/app/components/global-search/use-global-search-results.ts
index 7f56e715eb1..224d285cb46 100644
--- a/packages/web/src/app/components/global-search/use-global-search-results.ts
+++ b/packages/web/src/app/components/global-search/use-global-search-results.ts
@@ -1,4 +1,8 @@
-import { PROJECT_COLOR_PALETTE } from '@activepieces/shared';
+import {
+ ApEdition,
+ ApFlagId,
+ PROJECT_COLOR_PALETTE,
+} from '@activepieces/shared';
import { keepPreviousData, useQuery } from '@tanstack/react-query';
import { t } from 'i18next';
@@ -8,10 +12,11 @@ import { foldersApi } from '@/features/folders';
import { projectCollectionUtils, getProjectName } from '@/features/projects';
import { tablesApi } from '@/features/tables';
import { useIsPlatformAdmin } from '@/hooks/authorization-hooks';
+import { flagsHooks } from '@/hooks/flags-hooks';
import { authenticationSession } from '@/lib/authentication-session';
import { getAccessHistory } from './access-history';
-import { STATIC_PAGES, type StaticPage } from './static-pages';
+import { STATIC_PAGES, staticPageUtils, type StaticPage } from './static-pages';
const SEARCH_LIMIT = 6;
const SUPPLEMENT_THRESHOLD = 5;
@@ -39,6 +44,7 @@ function getTimePeriod(
export function useGlobalSearchResults(query: string, open: boolean) {
const projectId = authenticationSession.getProjectId() ?? '';
const isPlatformAdmin = useIsPlatformAdmin();
+ const { data: edition } = flagsHooks.useFlag<ApEdition>(ApFlagId.EDITION);
const { embedState } = useEmbedding();
const hideTables = embedState.hideTables;
const { data: allProjects = [] } = projectCollectionUtils.useAll();
@@ -100,7 +106,7 @@ export function useGlobalSearchResults(query: string, open: boolean) {
const matchedPages = STATIC_PAGES.filter(
(p) =>
- (!p.requiresPlatformAdmin || isPlatformAdmin) &&
+ staticPageUtils.isVisible({ page: p, isPlatformAdmin, edition }) &&
(!hasQuery || p.label.toLowerCase().includes(query.toLowerCase())),
).slice(0, SEARCH_LIMIT);
diff --git a/packages/web/src/app/components/sidebar/platform/index.tsx b/packages/web/src/app/components/sidebar/platform/index.tsx
index 032ef9d30a2..b1d8b47949e 100644
--- a/packages/web/src/app/components/sidebar/platform/index.tsx
+++ b/packages/web/src/app/components/sidebar/platform/index.tsx
@@ -109,6 +109,9 @@ export function PlatformNav() {
? undefined
: [
{ to: '/platform/ai', label: t('Providers'), end: true },
+ ...(edition === ApEdition.CLOUD
+ ? [{ to: '/platform/ai/tiers', label: t('Tiers') }]
+ : []),
{
to: '/platform/ai/capabilities',
label: t('Capabilities'),
diff --git a/packages/web/test/app/components/global-search/static-pages.test.ts b/packages/web/test/app/components/global-search/static-pages.test.ts
new file mode 100644
index 00000000000..84e789d9697
--- /dev/null
+++ b/packages/web/test/app/components/global-search/static-pages.test.ts
@@ -0,0 +1,53 @@
+import { ApEdition } from '@activepieces/shared';
+import { describe, expect, it } from 'vitest';
+
+import {
+ STATIC_PAGES,
+ staticPageUtils,
+ type StaticPage,
+} from '@/app/components/global-search/static-pages';
+
+describe('global search Tiers page', () => {
+ it('shows to platform admins on cloud', () => {
+ expect(
+ staticPageUtils.isVisible({
+ page: tiersPage(),
+ isPlatformAdmin: true,
+ edition: ApEdition.CLOUD,
+ }),
+ ).toBe(true);
+ });
+
+ it.each([ApEdition.ENTERPRISE, ApEdition.COMMUNITY, null])(
+ 'stays hidden on %s',
+ (edition) => {
+ expect(
+ staticPageUtils.isVisible({
+ page: tiersPage(),
+ isPlatformAdmin: true,
+ edition,
+ }),
+ ).toBe(false);
+ },
+ );
+
+ it('stays hidden from non-admins on cloud', () => {
+ expect(
+ staticPageUtils.isVisible({
+ page: tiersPage(),
+ isPlatformAdmin: false,
+ edition: ApEdition.CLOUD,
+ }),
+ ).toBe(false);
+ });
+});
+
+function tiersPage(): StaticPage {
+ const page = STATIC_PAGES.find(
+ (candidate) => candidate.href === '/platform/ai/tiers',
+ );
+ if (page === undefined) {
+ throw new Error('The Tiers page is missing from global search');
+ }
+ return page;
+}
diff --git a/packages/web/test/app/components/sidebar/platform/index.test.tsx b/packages/web/test/app/components/sidebar/platform/index.test.tsx
index 35f2e581c7a..87f0b813886 100644
--- a/packages/web/test/app/components/sidebar/platform/index.test.tsx
+++ b/packages/web/test/app/components/sidebar/platform/index.test.tsx
@@ -9,6 +9,7 @@ import { describe, expect, it, vi } from 'vitest';
import { PlatformNav } from '@/app/components/sidebar/platform';
const plan = vi.hoisted(() => ({ aiProvidersEnabled: false }));
+const flags = vi.hoisted(() => ({ edition: 'cloud' }));
vi.mock('i18next', () => ({ t: (key: string) => key }));
@@ -20,7 +21,7 @@ vi.mock('@/hooks/platform-hooks', () => ({
vi.mock('@/hooks/flags-hooks', () => ({
flagsHooks: {
- useFlag: () => ({ data: 'cloud' }),
+ useFlag: () => ({ data: flags.edition }),
},
}));
@@ -98,4 +99,27 @@ describe('platform sidebar AI Center', () => {
screen.queryAllByRole('listitem', { name: 'Providers locked' }),
).toEqual([]);
});
+
+ it('shows Tiers between Providers and Capabilities on cloud', () => {
+ plan.aiProvidersEnabled = true;
+ flags.edition = 'cloud';
+
+ renderSidebar();
+
+ const aiCenter = screen.getByRole('list', { name: 'AI Center' });
+ expect(
+ Array.from(aiCenter.children).map((item) =>
+ item.getAttribute('aria-label'),
+ ),
+ ).toEqual(['Providers', 'Tiers', 'Capabilities']);
+ });
+
+ it('hides Tiers on self-hosted enterprise', () => {
+ plan.aiProvidersEnabled = true;
+ flags.edition = 'ee';
+
+ renderSidebar();
+
+ expect(screen.queryAllByRole('listitem', { name: 'Tiers' })).toEqual([]);
+ });
});