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): 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.mdindex 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 everafter 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.mdindex 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 deploymenPostmortems (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 ``. 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.mdindex 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.tsindex 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.tsindex 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.tsxindex 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.tsnew file mode 100644index 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.tsxindex 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([]);+ });});