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(ai): managed AI steps follow their tier when it moves to a newer model (#15866)

Louai Boumediene703a9177ce97
diff --git a/brain/knowledge/ai-intelligence/ai-providers.md b/brain/knowledge/ai-intelligence/ai-providers.md
index 96f0e697cd9..3693e563370 100644
--- a/brain/knowledge/ai-intelligence/ai-providers.md
+++ b/brain/knowledge/ai-intelligence/ai-providers.md
@@ -63,8 +63,11 @@ the background every 15 minutes with a 5-minute back-off after a failure. `warmU
`defaultModelIdForProvider`, `resolveModelIdForAnalytics`) and the fast-model helpers in `agent-helpers.ts` read it,
every one with a required `surface` argument. `surfaceOf({ source })` in that file is the only place the run
source maps to a list (FLOW_STEP and AGENT to flow, CHAT and AGENT_BUILDER to chat), and `agent-config-rpc.ts`
-derives `namesItsOwnModel` from it. `AP_MODEL_TIERS_URL` overrides
-the URL. The file is published from the console in `ap-analytics`; see decision 000041.
+derives `namesItsOwnModel` from it. The AI piece's text steps resolve through `aiModelResolution.resolveTierModelId`
+(`src/app/ai/ai-model-resolution.ts`, CE), always on the flow surface, in `ai-execute-controller.ts` before the job is
+enqueued. `AP_MODEL_TIERS_URL` overrides the URL. The file is published from the console in `ap-analytics`; see
+decision 000041. The console publishes both lists and both fast pointers on every Publish, and on its first load
+after a file without chat keys it seeds the chat list from the live flow list.
### Gotchas
- **A catalog change takes up to ~2 days to reach a dropdown, through three caches in series.** CDN edge (`--cache-control max-age=3600`, 1h) → the server's in-memory catalog (`CATALOG_TTL_MS`, 24h) → `modelsCache` (flushed by the nightly `cron.schedule('0 0 * * *')`). So "I republished but the UI still shows the old price" is expected, not a bug; restarting the API short-circuits the two in-process layers. The edge TTL is deliberately 1h and not the 604800 that `publish-embed-sdk.yml` uses — that path is version-stamped, ours is a stable key rewritten in place, so a week-long edge cache would pin stale prices for a week.
- **`Sync AI Model Catalog` is the only workflow that proves the CDN S3 credentials still work — a green `Publish Embed SDK` proves nothing.** Both read the same `CDN_S3_ACCESS_KEY_ID` / `CDN_S3_SECRET_ACCESS_KEY` / `CDN_S3_BUCKET` / `CDN_S3_ENDPOINT` secrets, but `publish-embed-sdk.yml` guards its upload job on `needs.check.outputs.publish == 'true'`, which is false whenever the version in `packages/ee/embed-sdk/package.json` is already on the CDN. Its daily cron then finishes in about nine seconds with the upload skipped and the run still marked success, so the key can rot for weeks behind a green tick — that is how the model-catalog cron came to fail with `InvalidAccessKeyId` on three consecutive Mondays while the embed SDK looked healthy. To date a dead key, find the last embed-SDK run whose `publish` job actually ran (`gh run list --workflow=publish-embed-sdk.yml`, look for a duration in minutes rather than seconds) and compare it against the first model-catalog failure. To test a rotated key, dispatch `sync-model-catalog.yml` — it uploads unconditionally.
@@ -80,14 +83,17 @@ the URL. The file is published from the console in `ap-analytics`; see decision
- **Since the AI steps moved to the worker, the server sees every step's model id, and `ai-execute-controller` is the one place to act on it.** The piece POSTs `/v1/ai/execute` with `provider` and `modelId`, the controller builds the `EXECUTE_AI` job from that body, and the worker runs whatever model id the job carries. So anything that needs to rewrite or validate the model a flow step is about to use belongs there, not in the piece — one server-side edit covers all five AI steps, and an old pinned piece bundle keeps working because it only forwards the string it stored. This is what makes storing a tier id in a step cheap: the bundle never has to understand it. Note the agent step does **not** come through here — it resolves separately over `getAgentConfig`, in `agent-config-rpc`. Two conditions sit under that. **An old bundle only forwards the string from `0.11.0` up** — `AI_PIECE_COST_BILLING_VERSION`, the first version whose `ai-step.ts` POSTs `v1/ai/execute`. A step pinned below it runs the pre-worker code that calls the provider from the sandbox, so a tier id there would reach OpenRouter as the literal string. That case is already closed: `migrate-v26-ai-piece-cost-billing` bumps every saved `piece-ai` step below `0.11.0` up to it, which is why a later migration can rewrite what a step stores without touching `pieceVersion` for the runtime. **And resolve on the API, never in the worker**: `ExecuteAiRequest.modelId` is a bare `z.string()` so a tier id passes validation, `getEffectiveProviderAndModel` and `aiUtils.buildWebSearchToolsOrThrow` both read `data.modelId` as a real model, and the `resolveAiProvider` RPC does not carry the model at all, so using it as the seam would mean widening the worker contract.
- **Managed billing can only price an OpenRouter call, and a call it cannot price is simply not billed.** `openRouterCostOf` (`server/utils/activepieces-ai-cost.ts`) reads `providerMetadata['openrouter'].usage.cost`, with one fallback that GETs `openrouter.ai/api/v1/generation?id=` and takes `total_cost`. If neither answers, `createBillingInfo` returns `undefined` and the turn is never reported — it runs, the customer keeps the output, and nothing is charged. Nothing logs "unbilled". This is what actually welds the managed provider to OpenRouter, more than the client does: `create-language-model.ts` shares one branch for `OPENROUTER` and `ACTIVEPIECES`, every tier `modelId` is an OpenRouter id, and `openrouter-api.ts` mints the per-platform key from `OPENROUTER_PROVISION_KEY`. So putting managed credits on any other gateway needs a second cost extractor and a second generation lookup **first**, or every call through it bills zero. For reference, no Vercel AI Gateway code exists here at all — the only gateway in the repo is Cloudflare's (`CLOUDFLARE_GATEWAY`, the `ai-gateway-provider` package), and `@ai-sdk/gateway` appears only as a transitive dep of `ai` that nothing imports. A BYOK user can already reach Vercel's gateway today through `AIProviderName.CUSTOM`, which takes a base URL plus hand-typed model ids.
- **A tier id that no longer exists resolves to the default tier of its surface, on every door, with a warning.** `resolveNamedModelId` (the path FLOW_STEP and AGENT take) tells a tier id from a model id by the slash rule: a bare slug is a tier id and goes through `resolveTier`, which returns the surface default for an id the file no longer carries and logs `Tier is no longer published; running the surface default` with the tier id and surface; a slashed id is a managed model id and is still refused with `The model "X" is not available on Activepieces AI credits` unless the release ships it or a published tier on that surface carries it. Every other source goes through `resolveModelIdForProvider` → `resolveTier`, the same default. So removing a tier from the file never fails a flow or an agent; it moves them onto the default until they are re-picked. The console may keep saying that removing a tier is safe. Decided 2026-09-26 with PR 2 of the configurable tiers work.
-- **The console's Publish writes the live key directly; there is no draft, no staging and no filter.** `ai-pricing-service.ts` in `ap-analytics` writes `LIVE_PRICING_KEY` on Publish, and its "add tier" row seeds `id: tier-N`, `label: New tier`, so a half-finished experiment is one click from every server's cached tier list, with only the CDN `max-age=300` plus the 15-minute in-process TTL in between. Test against a local file with `AP_MODEL_TIERS_URL` (add the host to `AP_SSRF_ALLOW_LIST` for loopback), never by publishing.
-- **The AI piece's managed dropdown only ever offers tier models, so every stored managed model id came from a tier pick.** `props.ts` (`packages/pieces/community/ai/src/lib/common/props.ts`) builds its options from `ACTIVEPIECES_CHAT_TIERS`, the constant compiled into the release, in two places: `managedModelLabel` supplies the label, and the same lookup is the `.filter` that decides which models are offered at all. There is no way to pin a model deliberately through it. Two consequences. A re-pointed tier is invisible to the AI piece in both directions: a saved step keeps its concrete model id, and a new step cannot pick the new model because it matches no bundled tier. And any migration from stored model ids to tier ids has a trivially complete mapping, since each stored id is one of the three bundled tier model ids of the release it was saved on. Until the dropdown emits tier ids, the AI piece only ever follows the release.
+- **The console's Publish writes the live key directly; there is no draft, no staging and no filter.** `ai-pricing-service.ts` in `ap-analytics` writes `LIVE_PRICING_KEY` on Publish, and its "add tier" row seeds `id: tier-N`, `label: New tier`, so a half-finished experiment is one click from every server's cached tier list, with only the CDN `max-age=300` plus the 15-minute in-process TTL in between. Test against a local file with `AP_MODEL_TIERS_URL` (serve it on `127.0.0.1` and add `127.0.0.1` to `AP_SSRF_ALLOW_LIST`, which takes IPs or CIDRs, not hostnames, so `localhost` is still refused), never by publishing.
+- **A console older than the two-list change, or a rollback to one, strips the chat keys on read, and its next Publish drops them with no diff line.** The console parses the live file with a zod object, and zod strips keys it does not declare, so `chatTiers`, `chatDefaultTierId` and `chatFastTierId` vanish from the draft the moment an old console reads it. Publish writes the draft back, and the history diff shows nothing because that console never knew the keys. Activepieces then serves chat from the flow list again, silently, since the chat keys are optional. After any console rollback, republish from a current build and check `curl -s https://cdn.activepieces.com/ai/pricing.json | jq keys` lists all nine keys.
+- **A managed text step stores a tier id from AI piece 0.12.0 on, and every managed model id stored before that came from a tier pick.** For the managed provider and a text step, `props.ts` (`packages/pieces/community/ai/src/lib/common/props.ts`) reads `GET /v1/ai-providers/tiers` with the engine token and offers the `flow` list as `{ label, value: tier.id }`. On any failure (a server without the route, a network error, an empty list) it offers the release's `ACTIVEPIECES_CHAT_TIERS`, still as tier ids, so a step saved on 0.12.0 always holds a tier id. `/models` is still called for managed image steps (`managedImageModelLabel` filters to `ACTIVEPIECES_IMAGE_TIERS`) and for own-key providers. Up to 0.11.0 the dropdown filtered `/models` to the bundled tier models and stored the concrete id, with no way to pin a model deliberately. So the migration from stored model ids to tier ids (ENG-753) has a trivially complete mapping: each stored id is one of the three bundled tier model ids of the release it was saved on. Until it runs, those steps follow the release, not the file.
+- **A managed text step on 0.12.0 that still holds a concrete model id shows 'Select AI Model' and keeps running that model.** The options are tier ids now. `searchable-select.tsx` renders the placeholder when the value matches no option and keeps the value, and `dynamic-dropdown-piece-property.tsx` only clears it when a refresher (here `provider`) changes. The run is unaffected, because the slash rule passes a concrete id through. It only happens when something bumps `pieceVersion` in place, as a flow migration does. Options are fetched against the step's saved exact version, so a step left on 0.11.0 keeps its old options, and the update dialog's minor bump resets every input (`getInputAfterVersionChange`, `MINOR_OR_MAJOR`), so the user re-picks the model with everything else.
+- **The AI step resolver skips image steps, because image tiers reuse the text tier ids.** `ACTIVEPIECES_IMAGE_TIERS` are `fast` / `smart` / `premium` too, and `aiJobFor`'s shared `modelId` feeds all five actions. Resolving a `GENERATE_IMAGE` job against the flow list would hand an image step a text model. The controller gates on `body.action`; any future image-tier resolution needs its own list.
- **`AIProviderModel` is declared twice, and a field added to one half is stripped on the wire.** There is one in `core/piece-types` (what pieces import, since they cannot import `@activepieces/shared`) and one in `core/shared` (what the server and the response schema use). They are not re-exports of each other — today the shared copy carries `metadata` and the piece-types copy does not. Fastify serialises the response against the *shared* schema and drops every key it does not declare, so adding a field to the piece-types copy alone type-checks in the piece, type-checks in the server, and arrives as `undefined`. A published tier label was nearly shipped that way. Any new field on a provider model needs both files.
- **No image model belongs to a chat tier, so a tier-based filter empties the image picker.** The managed provider is OpenRouter underneath and `openrouter-provider.listModels` tags a model `IMAGE` when its `architecture.output_modalities` says so — `ACTIVEPIECES` is deliberately absent from `NO_IMAGE_GENERATION_PROVIDERS`, and `google/gemini-2.5-flash-image` and friends are real managed models. But `ACTIVEPIECES_CHAT_TIERS` is three *chat* tiers, so no image model can ever match one. Any filter of the form "a managed model must belong to a tier" therefore drops every image model silently, leaving `aiProps({ modelType: 'image' })` with an empty dropdown and no error. Gate that filter on `modelType === 'text'`.
- **The api test suite runs on the bundled tiers, never the live file.** `packages/server/api/vitest.setup.ts` points `AP_MODEL_TIERS_URL` at `model-tiers.invalid`, so boot warm-up fails fast and every test resolves against `ACTIVEPIECES_CHAT_TIERS`. CI runners have egress, and the first time a resolver read the file in CI the live `defaultTierId` was `fast`, which turned a test asserting the release default (Expert) red with no code change behind it. A test that wants the published shape mocks `modelTierCatalog` (`test/unit/app/ee/agent/model-tier-fixture.ts`); an integration test that boots the app cannot be handed a file.
- **A published tier without `nativeModelId` keeps every BYOK key on the release's model for that tier id.** `nativeModelIdFor` (`ee/agent/agent-model-resolution.ts`) takes the tier's own `nativeModelId`, else the `nativeModelId` of the bundled `ACTIVEPIECES_CHAT_TIERS` entry with the same id, else null, which sends a curated provider to its first curated model and a catalogue-less provider to the first text model its key lists. The fallback is keyed by tier id only, so two lists sharing an id resolve to the same native model on every own-key provider, whatever their managed models are. The BYOK tier map (PR 6 of the configurable tiers work) is the real fix.
- **`premium` pairs `modelId: anthropic/claude-opus-4.8` with `nativeModelId: claude-opus-4-7` on purpose.** The managed tier runs Opus 4.8 through OpenRouter; a customer's own Anthropic key runs Opus 4.7. The reason is cost on the customer's key: Heavy on a BYOK key must not silently move the customer onto the most expensive model without them choosing it. The console's `defaults.ts` carries the same pair. Do not "fix" either copy.
-- **Whatever the console publishes is in every Cloud customer's picker within about 20 minutes on a fresh page load, and about 35 minutes on a page left open: no draft, no staging, no filter.** `GET /v1/ai-providers/tiers` (`ListModelTiers` in `ai-provider-controller.ts`) returns `modelTierCatalog.current(surface)` for both lists, keyed `flow` and `chat`, to USER and ENGINE principals with no platform or project scope, because the tiers are global; the response schema puts only `id`, `label` and `modelId` on the wire. The web reads it through one hook, `aiProviderQueries.useModelTiers(surface)` (`features/platform-admin/hooks/ai-provider-hooks.ts`): the chat selector passes `chat`, the agent picker passes `flow`, and nothing but a test checks which one a caller passed, since the surface argument the server requires does not reach this layer. Both pickers show the release's bundled tiers while the call is in flight or has failed, so they never render empty. The web query is stale after 15 minutes and refetches on that interval while the tab is visible (`staleTime` alone only gates the mount, focus and reconnect triggers, so a tab left open would never refetch), which is where the two bounds come from: CDN `max-age` 5 min plus the server's 15-min TTL for a fresh load, plus one 15-min client tick for an open page, and the server serves its old copy once while it refreshes. The AI piece's own model dropdown still reads the bundled constant (the props.ts bullet above) until it stores tier ids.
+- **Whatever the console publishes is in every Cloud customer's picker within about 20 minutes on a fresh page load, and about 35 minutes on a page left open: no draft, no staging, no filter.** `GET /v1/ai-providers/tiers` (`ListModelTiers` in `ai-provider-controller.ts`) returns `modelTierCatalog.current(surface)` for both lists, keyed `flow` and `chat`, to USER and ENGINE principals with no platform or project scope, because the tiers are global; the response schema puts only `id`, `label` and `modelId` on the wire. The web reads it through one hook, `aiProviderQueries.useModelTiers(surface)` (`features/platform-admin/hooks/ai-provider-hooks.ts`): the chat selector passes `chat`, the agent picker passes `flow`, and nothing but a test checks which one a caller passed, since the surface argument the server requires does not reach this layer. Both pickers show the release's bundled tiers while the call is in flight or has failed, so they never render empty. The web query is stale after 15 minutes and refetches on that interval while the tab is visible (`staleTime` alone only gates the mount, focus and reconnect triggers, so a tab left open would never refetch), which is where the two bounds come from: CDN `max-age` 5 min plus the server's 15-min TTL for a fresh load, plus one 15-min client tick for an open page, and the server serves its old copy once while it refreshes. The AI piece's own model dropdown reads the same route from piece 0.12.0 (the props.ts bullet above).
- **Every provider auth schema is written twice, and only one copy is the one the server reads.** `packages/core/utils/src/lib/ai-provider-credentials.ts` (plain zod) backs the API and the web app; `packages/core/piece-types/src/lib/ai-providers.ts` (`zod/mini`, so `.check(z.minLength(1))` and `z.optional(x)` instead of `.min(1)` / `.optional()`) is what `@activepieces/pieces-framework` re-exports to pieces and the engine. Adding a credential field to only one leaves the other silently stripping it — zod objects drop unknown keys, so the upsert still returns 200 and the failure surfaces later as a provider-side auth error. Change both.
- **A schema change in `packages/core/utils` is invisible to another package's tests until you build it.** Sibling packages resolve `@activepieces/core-utils` through its `main` (`dist/src/index.js`), so vitest in `core/ai-providers` keeps parsing against the stale build and a new optional field reads back as dropped. `cd packages/core/utils && npm run build` first. The API dev server is the opposite: `serve` runs under tsx with the tsconfig path alias, so it reads `src` directly — but it only watches `packages/core/shared/src/**`, not `core/utils`, so a core-utils-only edit needs a restart to take effect. The same staleness makes a **branch** look green when it is not: `dist` is gitignored, so after `git checkout` it still holds whatever the previous branch built, and a test that depends on a field added by a sibling PR passes locally and fails in CI. Rebuild `core/utils` after every branch switch before trusting a run.
diff --git a/brain/knowledge/decisions/000041-ai-model-tiers-are-published-to-the-cdn-from-a-second-console.md b/brain/knowledge/decisions/000041-ai-model-tiers-are-published-to-the-cdn-from-a-second-console.md
index 21210624a7e..13fb0ae5f89 100644
--- a/brain/knowledge/decisions/000041-ai-model-tiers-are-published-to-the-cdn-from-a-second-console.md
+++ b/brain/knowledge/decisions/000041-ai-model-tiers-are-published-to-the-cdn-from-a-second-console.md
@@ -53,8 +53,11 @@ the bucket; a key scoped to `ai/pricing*` is the follow-up.
in ap-analytics, `packages/server/utils/src/model-tier-catalog.ts` here. Change one without the
other and Activepieces rejects the file and silently keeps serving the old tiers. The reader
ignores keys it does not declare, which is what kept the console publishable while it still sent
- the credit fields; ap-analytics dropped those on 2026-09-20 and added `nativeModelId`, so the two
- schemas name the same five tier fields again.
+ the credit fields; ap-analytics dropped those on 2026-09-20. Since 2026-09-27 the two schemas
+ name the same nine top-level keys (`version`, `publishedAt`, `publishedBy`, `tiers`,
+ `defaultTierId`, `fastTierId`, `chatTiers`, `chatDefaultTierId`, `chatFastTierId`). Per tier they
+ differ by one field: the console dropped `nativeModelId` again on 2026-09-27, while Activepieces
+ keeps it optional and falls back to the bundled tier's value.
- A tier change is no longer visible in `git log` of this repo. The audit trail is the CDN history
prefix.
- The reader **fails closed**: bad schema, no tiers, or a missing default tier all fall back to the
@@ -82,4 +85,4 @@ the bucket; a key scoped to `ai/pricing*` is the follow-up.
`CLAUDE.md` and the package names all say config-console. It was created as `config-console` and
renamed on 2026-09-02. A clone made before the rename pushes into a 404; fix it with
`git remote set-url origin [email protected]:activepieces/ap-analytics.git`.
-- **Internal tools run on DigitalOcean, but not all the same way.** `activepieces/discover` uses a **droplet** driven by Actions over SSH (`.github/workflows/deploy.yml` — build, rsync, `pm2 reload`), with nginx and certbot in front. `ap-analytics` uses **App Platform** instead: DO builds the Dockerfile, redeploys on push by itself, and issues TLS, so there is no server to log into and the repo carries no deploy workflow at all. Neither repo says which it is, so check the DO dashboard before assuming. Runbook: `DEPLOYMENT.md` in ap-analytics.
+- **Internal tools run on DigitalOcean, but not all the same way.** `activepieces/discover` uses a **droplet** driven by Actions over SSH (`.github/workflows/deploy.yml` — build, rsync, `pm2 reload`), with nginx and certbot in front. `ap-analytics` uses **App Platform** instead: DO builds the Dockerfile, redeploys on push by itself, and issues TLS, so there is no server to log into and the repo carries no deploy workflow at all. That repo takes no pull requests: commits go straight to `main`, and the push is the deploy. Neither repo says which it is, so check the DO dashboard before assuming. Runbook: `DEPLOYMENT.md` in ap-analytics.
diff --git a/brain/knowledge/engineering/ci-pr-review-hygiene.md b/brain/knowledge/engineering/ci-pr-review-hygiene.md
index e0ff28107a1..44c1c6ddc11 100644
--- a/brain/knowledge/engineering/ci-pr-review-hygiene.md
+++ b/brain/knowledge/engineering/ci-pr-review-hygiene.md
@@ -35,6 +35,7 @@ Enforcement is the **`Codeowners review` repository ruleset** (active on the def
- **Reading the parallel test job's log: trust the turbo `Failed:` line at the tail, not the scary lines in the middle.** The job runs about 21 turbo tasks at once, so `gh run view <run> --job <job> --log-failed` interleaves all of them. `FATAL ERROR: Reached heap limit` and `Caught fatal signal 9` next to `test/lib/sandbox/*.test.ts` are the sandbox suite killing isolates on purpose; `Error: Boom inside engine trigger hook` and the `HttpError` stderr dumps are fixture output. Strip the prefixes (`sed 's/^[^\t]*\t[^\t]*\t//'`), grep ` FAIL ` for the real assertion, and read the `Tasks: … Failed: <task>` summary to know which package actually failed. Engine handler tests timing out at 20 s in that job are load, not hangs: `flow-skip-progress.test.ts` (28 s) and then `flow-rerun.test.ts` timed out on consecutive runs of #15707 while each finishes in 0.6 s locally. The CI step starts `turbo run test` and the API's `test-unit test-ce test-ee test-cloud` in parallel with `&` on a 4-vCPU runner, and a branch that touches `packages/core/*` invalidates about 60 downstream tasks, so the engine suites compete with four Postgres-backed API suites for the same cores; main mostly hits the turbo cache and never sees it. The engine's `testTimeout` is now 60 s, the value the API's vitest config already used for the same job; the real lever, if it recurs, is not running the two turbo invocations concurrently.
- **A spurious `core` request on a pieces PR is not always the lockfile — check for a second root file.** [#14558](https://github.com/activepieces/activepieces/pull/14558) looked like the lockfile case but its non-pieces files were `bun.lock` *and* `tsconfig.base.json`; the `core` request landed 6s after the commit that touched the tsconfig, not after the pieces push. Per-piece `paths` mappings generated into root `tsconfig.base.json` mean a pieces change can still reach a core-owned file, and no CODEOWNERS pattern can fix that — the file holds real compiler options and CODEOWNERS has no sub-file granularity.
- **Greptile's Confidence Score prose is cumulative, so a low score mixes resolved findings with live ones — triage each claim separately rather than trusting or dismissing the number.** It edits one summary comment in place, and its "Files Needing Attention" list keeps naming findings that are already resolved and outdated: #14825 sat at 2/5 citing three files, two of which were a closed P1 and a duplicate view of the third. Read the *unresolved* review threads (`reviewThreads(first:60) { isResolved isOutdated }` over GraphQL — the REST comments endpoint carries no resolution state) and judge from those; re-trigger the review to refresh the score. It also re-raises the same class of finding each round with a new comment id, so a fix on one thread does not silence its sibling. **The score recomputes on a push, never on a reply** — so a finding Greptile *itself* withdraws still counts against it. On [#15243](https://github.com/activepieces/activepieces/pull/15243) the second pass read the pushed fix, filed zero new comments, and replied "this is not a valid finding… Withdrawing the comment" on its own P2; the summary comment was edited 67 seconds later, but only the footer (`Reviews (2)`, last-reviewed-commit link) changed — the headline stayed 2/5 and still justified itself with the finding just retracted. So compare the summary's `updated_at` against the review `submitted_at` from `gh api repos/:owner/:repo/pulls/<n>/reviews`: a summary newer than the last review pass has usually only had its footer bumped. But do not read "cumulative" as "stale": a 2/5 on [#14934](https://github.com/activepieces/activepieces/pull/14934) listed three files, two carrying findings already fixed and one naming a real bypass nobody had tested — the approve path published without the guard the direct path ran. The resolved-thread count is the right gate for *merging*, and a weak signal about *content*, because a finding Greptile states only in the summary never becomes a thread to resolve. Read the summary's file list even at zero unresolved threads, and check each named file against the code. The same applies to a human reviewer's tool-generated summary: Amr's review on #15707 said "Blockers: 4" and named them, but only two had an inline thread; the other two never left his tool. Count the threads against the summary before triaging, and answer the missing ones in a PR comment so the record shows they were checked.
+- **Greptile marks down a PR whose title describes the code instead of what the user gets.** A custom rule in the Greptile dashboard (not in this repo) deducts half a point and posts a P2 "Implementation-focused PR title" on a title like `feat(ai): the managed model dropdown stores a tier, not a model`. Write the title as the user-visible change and keep the Conventional Commit prefix, lowercase after the type ("Validate PR title" and commitlint check it), e.g. `feat(ai): managed AI steps follow their tier when it moves to a newer model`. Fix it with `gh pr edit <n> --title`; the `edited` event reruns the title check, and no commit is needed.
- **`api` and `worker` resolve `@activepieces/shared` and the `core-*` packages from `dist`, so a package-local `tsc --noEmit` there reports whatever was built last.** Both `packages/server/api/tsconfig.app.json` and `packages/server/worker/tsconfig.lib.json` set `"paths": {}`, clearing the inherited source mappings, so an export added to `packages/core/shared/src` shows up as `TS2305: has no exported member` until that package is rebuilt — the error names your file and is not about your file. `web` is not affected for the packages it actually imports: `vite.config.mts` aliases `@activepieces/shared`, `@activepieces/pieces-framework`, `core-utils`, `core-formula`, `core-piece-types` and `core-execution` to their `src`. Nothing else is aliased there, so check `vite.config.mts` before assuming a package is exempt — `@activepieces/ai-providers` (note the name: no `core-` prefix) has no Vite alias and resolves through `dist`, though it is mapped to source in `tsconfig.base.json` and web does not import it today. `npx turbo run build --filter=<pkg>` needs no manual pre-build, since `build` declares `dependsOn: ["^build"]` and builds dependencies first; only the direct `tsc` invocation can lie, and `npx turbo run build --filter=@activepieces/shared` is the cure. **The web editor and `tsc` are affected too, one hop out.** `packages/web/tsconfig.app.json` maps only `@activepieces/shared`, `pieces-framework` and a few pieces to `src`; `shared/src` then imports `@activepieces/core-utils`, which resolves through `node_modules` to `dist`. So after a sync that changes a `core-utils` schema (a `sessionToken` field on the Bedrock auth, #15747), the editor reports `'sessionToken' does not exist in type` on main's own web code while `vite` is fine. Rebuild the core packages and restart the TS server; the code needs no change.
- **The `main` CI job builds web, worker, api and engine before it runs a single test, so a build error there fails the whole job with no test output to point at it.** One missing enum import in a worker file surfaced only as `worker#build` exiting 2. Before pushing a change that moves code between files, run `npx turbo run build --filter=web --filter=worker --filter=api --filter=@activepieces/engine` — the same set the job builds — rather than trusting the per-package typecheck you happened to run before the move. Note that the `web` half of that command needs more heap than node gives it by default: on a 14 GB machine `vite build` transforms all ~7k modules and then dies with `node::OOMErrorHandler` / `SIGABRT` during bundling, which reads as a broken change rather than a full laptop. Run it as `NODE_OPTIONS=--max-old-space-size=8192 npx turbo run build --filter=web` and it finishes in well under a minute. CI runners have the headroom, so this only ever bites locally.
- **`check-migrations` runs against your own PGlite database, so a leftover index from work you abandoned fails the gate locally while CI is green.** The check runs migrations then asks TypeORM to generate one, and any difference between your database and the entity metadata counts as drift — including an index a reverted branch created and never dropped. The report names it (`DROP INDEX "public"."<name>"` in the generated `up`). CI starts from an empty database, so this class of failure is local-only. The database is `~/.activepieces/pglite` by default, which is also the dev server's, so drop the specific index rather than resetting the directory: a tiny CJS script with `PGlite.create({ dataDir })` and `DROP INDEX IF EXISTS` is enough, and it must run inside `packages/server/api` where the dependency resolves.
@@ -84,7 +85,7 @@ Enforcement is the **`Codeowners review` repository ruleset** (active on the def
- **Docs videos belong on `cdn.activepieces.com/videos/docs/`, never in the repo — and `docs/resources/` is the legacy path that suggests otherwise.** Every `<video>` already in the wiki points at that CDN prefix, but `docs/resources/` still holds ~43 MB of in-repo gifs from before the convention, so the tree itself gives mixed signals and a contributor reasonably copies the wrong one. [#15399](https://github.com/activepieces/activepieces/pull/15399) added a fresh `docs/videos/` folder with 155 MB of `.mp4` against an 880 MB `.git`, including one byte-identical duplicate. Nothing in CI catches it: `PR size` exempts unmatched areas and counts lines, not bytes, and a binary blob contributes zero lines. Review the *file list* of a docs PR, not just its diff. Once such a branch is pushed the blobs are already on the remote — dropping them at the tip only keeps them out of `main` if the PR is **squash**-merged and the branch deleted, so a merge commit ships them permanently. Because the blobs stay reachable until the branch is deleted, nobody has to re-request the assets from whoever recorded them — pull them straight back out of history with `git archive <commit> docs/videos | tar -x --strip-components=2 -C <dir>`, picking the commit *before* the removal, which is also how you get them under the post-rename filenames the pages already reference.
- **Mintlify-editor PRs arrive with `untitled-page*.mdx` at the docs root and `(1)`/`(2)`-suffixed media, wired into `docs.json` under those names.** The bot commits whatever the web editor autosaved, so pages land as `docs/untitled-page-5.mdx` rather than in the folder their nav group implies, and re-uploaded assets keep the browser's download-collision suffix (`data-flow-(1).mp4`, `01---insert-panel-(1.2x).mp4`). Mintlify's own link check passes — the names are internally consistent — so nothing flags it. Rename the files, fix the `docs.json` entries, then diff the *flattened nav tree* against `main` rather than reading the raw JSON diff: the editor also reindents, which buried a real change (the Enterprise Control `Security` group demoted to a child of `Guides`) inside 242 lines of whitespace churn on that PR.
- **After rewriting a lower branch of a stack, the `--onto` upstream you need is that branch's *old* tip, and `<branch>@{1}` is where to read it.** Every commit above a rewritten branch has to be replayed with `git rebase --onto <new lower tip> <old lower tip> <upper>`, and the old tip stops being reachable by name the moment the rebase finishes. Guessing a SHA from an earlier terminal scroll either fails outright with `invalid upstream` or, worse, succeeds against the wrong base and replays a handful of commits instead of all of them, which surfaces as a pile of conflicts the branch has with itself. `git rev-parse <branch>@{1}` reads it from the reflog every time. Re-run the whole `--onto` chain top-down after any lower-branch amend, and confirm afterwards that `git log --format=%s main..<top>` has no duplicate subjects.
-- **When a stacked PR's parent is squash-merged, merge `main` into the child and retarget; do not rebase.** The parent's commits are on `main` by content but not by SHA, so `git merge origin/main` on the child sees both sides make the same change and auto-merges it; only the lines the child *rewrote* from the parent conflict, plus anything `main` changed in the same functions since (PR 2 of the model tiers work, #15825: three brain and docs pages where PR 2 had rewritten PR 1's sentences, and `agent-helpers.ts` where main's `resolveImageModelId` landed next to the surface-threaded fast-model helper). No history rewrite, a normal push, and the PR above it keeps its base untouched; a `--onto` rebase would replay every commit up the stack and force-push each. After the retarget, the PR's Commits tab still lists the parent's original SHAs (they reached `main` only as a squash) while Files changed shows only the child's files; the second view is the one that matters, so do not "fix" the first. Two traps in the resolution. `git checkout --ours <file>` on a conflicted file takes the *whole* file from your side and silently discards main's auto-merged hunks in it, so resolve hunk by hunk and check `git diff origin/main -- <file>` afterwards shows only your lines. And `tsc` against the merged tree resolves `@activepieces/shared` through the built dist, which still holds the pre-merge exports: three phantom "has no exported member" errors vanished after `npx turbo run build --filter=@activepieces/server-utils`. Rebuild the core libs before believing a typecheck, then run the child's own tests.
+- **When a stacked PR's parent is squash-merged, merge `main` into the child and retarget; do not rebase.** The parent's commits are on `main` by content but not by SHA, so `git merge origin/main` on the child sees both sides make the same change and auto-merges it; only the lines the child *rewrote* from the parent conflict, plus anything `main` changed in the same functions since (PR 2 of the model tiers work, #15825: three brain and docs pages where PR 2 had rewritten PR 1's sentences, and `agent-helpers.ts` where main's `resolveImageModelId` landed next to the surface-threaded fast-model helper). No history rewrite, a normal push, and the PR above it keeps its base untouched; a `--onto` rebase would replay every commit up the stack and force-push each. After the retarget, the PR's Commits tab still lists the parent's original SHAs (they reached `main` only as a squash) while Files changed shows only the child's files; the second view is the one that matters, so do not "fix" the first. Two traps in the resolution. `git checkout --ours <file>` on a conflicted file takes the *whole* file from your side and silently discards main's auto-merged hunks in it, so resolve hunk by hunk and check `git diff origin/main -- <file>` afterwards shows only your lines. And `tsc` against the merged tree resolves `@activepieces/shared` through the built dist, which still holds the pre-merge exports: three phantom "has no exported member" errors vanished after `npx turbo run build --filter=@activepieces/server-utils`. Rebuild the core libs before believing a typecheck, then run the child's own tests. A child branched off an *older* head of its parent (the parent took review fixes after the child was cut) also conflicts in files the child never touched: those are the parent's early copy against its final one on `main`. If `git log <old parent head>..HEAD -- <file>` lists none of the child's commits, `git checkout --theirs <file>` is the right answer there, because the whole file is main's (PR 4 of the model tiers work, #15866: `use-chat.ts`, `core/execution/package.json` and an agent test).
- **Never commit a shared file onto a lower branch of a stack by copying it in from the stack top — you drag the upper branches' edits down with it.** Adding one gotcha bullet to a brain page while sitting on the top branch, then `git checkout <stash-or-top> -- <file>` after switching to the base branch, brings the *whole* file across, so every bullet the upper branches added to that page is silently duplicated onto the base. The commit stat is the tell: a one-line edit that reports six insertions is not a one-line edit. Switch branches first, re-apply the edit against **that branch's own copy** of the file, and re-check the stat before committing.
- **Cherry-picking a merged PR onto a release branch: the commit-msg hook rejects it, and `breaking-changes.mdx` conflicts pull in other people's entries.** GitHub writes the squash header server-side, so `fix(flows): … instead of reverting them (#14899)` never faced commitlint — replaying it locally trips the 100-character header limit and `git cherry-pick --continue` dies in husky with the working tree half-applied. Finish it with `git commit --no-verify -C <original-sha>` rather than rewording, so the release branch keeps the same subject as `main`. The `Unreleased` section of `docs/install/reference/breaking-changes.mdx` conflicts on almost every pick because it accumulates entries from unrelated `main` work: take only the section your own commit added. **Take it by its own heading, not by "everything after the marker" — the incoming side of that hunk usually runs on into `main`'s copy of an already-published `## X.Y.Z` section, and pasting the tail duplicates ~200 lines of published notes that no test, lint or typecheck will ever notice.** The reliable move is to rebuild the file: `git checkout origin/release/<version> -- docs/install/reference/breaking-changes.mdx`, then insert your entry under its own `## <new version>` heading above the previous release's, and confirm with `git diff --stat` that only your lines are added and `grep -c '^## '` that no version heading appears twice. Then run `bun install` before pushing — the release branch's `bun.lock` is usually stale against its own `package.json`s, and the pick drags those stale piece versions along until install corrects them; `git diff --stat origin/release/<version> -- bun.lock` should come back as just the packages your pick actually bumped. Expect the **PR size** gate to block it too: the picked commits drag their own upstream tests along (769/600 in `server/api` for two picks), and splitting a replay of already-reviewed work is the wrong answer — add `large-pr-ok`.
- **`api#test-ce` can exit 1 with every test passing — read the `Errors` line, not just `Tests`.** Vitest fails the run on *unhandled* errors too, so the summary reads `Test Files 92 passed`, `Tests 1076 passed`, `Errors 3 errors` and turbo reports `Failed: api#test-ce`. The recurring one is `TypeError: socket.destroySoon is not a function` at `Timeout.forceClose` in `@hono/node-server`, attributed to `test/integration/ce/mcp/mcp-platform-project-selection.test.ts` — a teardown race after the test already finished, not a failure of whatever you changed. Before chasing it, scroll to the `Unhandled Errors` block and check whether any test actually failed; if none did and the stack is in `forceClose`, re-run the job (`gh run rerun <id> --failed`) rather than editing code. Note the log section only has the whole `main` job, so `gh run view --job <id> --log-failed` buries it under thousands of lines of passing-test stderr — grep for `Unhandled Errors` or `Test Files`.
diff --git a/brain/knowledge/memory.md b/brain/knowledge/memory.md
index 90679dcc461..3b7c5930233 100644
--- a/brain/knowledge/memory.md
+++ b/brain/knowledge/memory.md
@@ -1,6 +1,7 @@
- 2026-09-26 — PR 2 of the configurable tiers work (`feat/tier-resolution`, ENG-767) moved chat, agent and Run Agent model resolution onto the published tier file, with a required `surface` argument on the whole `agent-model-resolution` family and `surfaceOf({ source })` as the one source-to-list rule. Three calls made that day, recorded on the AI Providers page: a removed tier resolves to its surface default with a warning on every door; the `chat-tool-billing.ts` tier-label and FLOW_STEP-provider bug stays as it is and lives in ENG-772; the end-to-end re-point check runs on canary after merge with `AP_MODEL_TIERS_URL`, not locally.
- 2026-09-24 — `test-unit` (api unit tests) only joined the PR pipeline on 2026-09-20 (#15653). A branch whose last CI run predates that has never had its unit tests run in CI; expect first-time failures when it merges `main`, as #15550 did (a test mock disagreeing with the real code, not a merge problem).
- 2026-09-27 — PR 3 of the configurable tiers work (`feat/tier-endpoint`, ENG-768): `GET /v1/ai-providers/tiers` serves both lists and both web pickers read it; a new chat no longer hardcodes `smart`. Found on the way: the live `ai/pricing.json` republished on 2026-09-26 carried `defaultTierId: fast`, which never reached web chats only because the web sent `smart` explicitly; it is being republished as `smart`.
+- 2026-09-28 — PR 4 of the configurable tiers work (`feat/tier-ai-piece`, ENG-752): the AI piece's managed text dropdown (piece 0.12.0, `minimumSupportedRelease` 0.93.0) offers the published flow tiers and stores the tier id, falling back to the bundled tier ids, never `/models`. `aiModelResolution.resolveTierModelId` (`src/app/ai/`, CE) turns the id into today's flow model in `ai-execute-controller` before enqueue, skips image steps, and logs `model.id` and `tier.id` on both branches. Merge gate: `origin/main`'s root version must be below 0.93.0 when it merges.
- 2026-09-20 — Found while planning the AI tier work: managed AI piece steps under-billed for about 23 days, between #14942 (2026-08-24) and #15494 (2026-09-16). #14942 changed the AI piece's `provider` prop to store an object (`{ provider, configId }`), but `flow-run-ai-usage-extractor` read that field with a string-only helper, so it resolved to `'unknown'`, failed the `provider !== ACTIVEPIECES` check in `resolveAiCreditWeight`, and charged **1 credit** per step instead of the model's table weight. It hit the five non-agent AI steps only, and only those configured or re-saved inside that window — a step saved earlier still held a plain string and billed correctly. `run_agent` was never affected, because it stores `aiProviderModel` instead. Nothing logged an error, and every test in the file passed a string provider, so the suite was green the whole time. The code is gone (#15494 deleted the extractor and bills on real provider cost now), so there is nothing left to fix — but the cloud credit events for that window are still wrong, and nobody has reconciled them.
- 2026-09-20 — The live `ai/pricing.json` (version 1, published 2026-09-14) carried a leftover test tier `tier-4` / "New tier" on `anthropic/claude-opus-4.8`, created by clicking "add tier" in the pricing console and publishing. It was removed on 2026-09-24 by deleting the whole object, so the key is 404 until someone publishes again from the console; every server falls back to the bundled tiers and warns every five minutes until then. Next time, edit the row and publish; do not delete the object.
- 2026-09-06 — Follow-up (Option B, "stub-writer cascade"): fix `engine-run-callback-service.ts` `ensureLogsFileExists` (line 84-86) so a fresh log-file stub isn't written with `{ steps: {}, tags: [] }` when the underlying file is missing — that stub is what the next BullMQ retry downloads and trips `EmptyResumeStateError` on. Options: (a) store `internalError` on `flow_run` itself so no stub is needed; (b) use a distinguishable stub shape (`executionState: null`) that the engine reader rejects fast; (c) `UnrecoverableError` in worker on state-loss errors so BullMQ doesn't retry the stub. Handles manual-admin-ops case (case #5 in the retention-hunt discussion) and any non-retention internal-error that would otherwise loop. Ping user once C.2/W.1/#2/#4 have landed.
diff --git a/brain/knowledge/pieces-engine/pieces.md b/brain/knowledge/pieces-engine/pieces.md
index 14099a98941..bdc06bfe9cd 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.
+- **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.
- **`/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`, which also shrinks its `JSON.parse(JSON.stringify(...))` deep clone. 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. Same trap in `pieceTranslation.translatePiece`: when the piece has no entry for the locale it returns the *original* object rather than a clone, so any `piece.i18n = undefined` after it would mutate the shared row — take the no-translations branch before calling it.
- **DynamicProperties clears its value before it knows the new schema, so the merge source must be a snapshot.** `DynamicPropertiesImplementation` re-fetches the child schema on every refresher change, clearing the form value synchronously and re-populating it in the mutation callback. The merge source for `getDefaultValueForProperties` has to be a `lastKnownValue` ref captured *before* the clear — reading `form.getValues()` in the callback sees the cleared `null` and defaults every child (GIT-1514). The snapshot must be spread-cloned: RHF `getValues(name)` hands back the live object and the clear's `setValue(...child, null)` mutates it in place. Guard the ref with `isNil` so it survives rapid successive changes, where later effect runs already observe `null`.
diff --git a/bun.lock b/bun.lock
index 11a75216720..6fa290b0f2d 100644
--- a/bun.lock
+++ b/bun.lock
@@ -336,7 +336,7 @@
},
"packages/pieces/community/ai": {
"name": "@activepieces/piece-ai",
- "version": "0.11.0",
+ "version": "0.12.0",
"dependencies": {
"@activepieces/core-piece-types": "workspace:*",
"@activepieces/core-utils": "workspace:*",
diff --git a/packages/pieces/community/ai/package.json b/packages/pieces/community/ai/package.json
index b5fd67b5566..9b5ec85571a 100644
--- a/packages/pieces/community/ai/package.json
+++ b/packages/pieces/community/ai/package.json
@@ -1,6 +1,6 @@
{
"name": "@activepieces/piece-ai",
- "version": "0.11.0",
+ "version": "0.12.0",
"type": "commonjs",
"main": "./dist/src/index.js",
"types": "./dist/src/index.d.ts",
diff --git a/packages/pieces/community/ai/src/index.ts b/packages/pieces/community/ai/src/index.ts
index b4149c5bb07..73de1f3a6a0 100644
--- a/packages/pieces/community/ai/src/index.ts
+++ b/packages/pieces/community/ai/src/index.ts
@@ -12,7 +12,7 @@ import { runAgent } from "./lib/actions/agents/run-agent";
export const ai = createPiece({
displayName: "AI",
auth: PieceAuth.None(),
- minimumSupportedRelease: '0.92.0',
+ minimumSupportedRelease: '0.93.0',
categories: [
PieceCategory.ARTIFICIAL_INTELLIGENCE,
PieceCategory.UNIVERSAL_AI,
diff --git a/packages/pieces/community/ai/src/lib/common/props.test.ts b/packages/pieces/community/ai/src/lib/common/props.test.ts
new file mode 100644
index 00000000000..ad9fa347e2e
--- /dev/null
+++ b/packages/pieces/community/ai/src/lib/common/props.test.ts
@@ -0,0 +1,134 @@
+import { httpClient } from '@activepieces/pieces-common';
+import { createMockActionContext } from '@activepieces/pieces-framework';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { aiProps } from './props';
+
+vi.mock('@activepieces/pieces-common', async (importOriginal) => {
+ const original = await importOriginal<Record<string, unknown>>();
+ return {
+ ...original,
+ httpClient: { sendRequest: vi.fn() },
+ };
+});
+
+const sendRequest = vi.mocked(httpClient.sendRequest);
+
+const publishedTiers = {
+ flow: {
+ tiers: [
+ { id: 'fast', label: 'Fast', modelId: 'anthropic/claude-haiku-4.5' },
+ { id: 'deep', label: 'Deep', modelId: 'anthropic/claude-fable-5.1' },
+ ],
+ defaultTierId: 'deep',
+ },
+ chat: {
+ tiers: [{ id: 'turbo', label: 'Turbo', modelId: 'openai/gpt-5.5' }],
+ defaultTierId: 'turbo',
+ },
+};
+
+const bundledTierOptions = [
+ { label: 'Fast', value: 'fast' },
+ { label: 'Expert', value: 'smart' },
+ { label: 'Heavy', value: 'premium' },
+];
+
+const catalog = [
+ { id: 'anthropic/claude-haiku-4.5', name: 'Claude Haiku 4.5', type: 'text' },
+ { id: 'anthropic/claude-sonnet-4.6', name: 'Claude Sonnet 4.6', type: 'text' },
+ { id: 'google/gemini-3.1-flash-image', name: 'Gemini Flash Image', type: 'image' },
+];
+
+function answer({ tiers }: { tiers: unknown }) {
+ sendRequest.mockImplementation(async (request: { url: string }) => {
+ if (request.url.includes('v1/ai-providers/tiers')) {
+ if (tiers === null) {
+ throw new Error('this server has no tiers route');
+ }
+ return { body: tiers } as never;
+ }
+ return { body: catalog } as never;
+ });
+}
+
+function modelOptions({ provider, modelType }: { provider: string; modelType: 'text' | 'image' }) {
+ return aiProps({ modelType }).model.options(
+ { provider: { provider } },
+ createMockActionContext({ propsValue: {} }),
+ );
+}
+
+function requestedUrls(): string[] {
+ return sendRequest.mock.calls.map((call) => call[0].url);
+}
+
+beforeEach(() => {
+ sendRequest.mockReset();
+ answer({ tiers: publishedTiers });
+});
+
+describe('the managed text model dropdown', () => {
+ it('offers the published flow tiers and stores the tier id', async () => {
+ const state = await modelOptions({ provider: 'activepieces', modelType: 'text' });
+
+ expect(state.options).toEqual([
+ { label: 'Fast', value: 'fast' },
+ { label: 'Deep', value: 'deep' },
+ ]);
+ });
+
+ it('never asks for the model catalog, because a tier is all a managed text step stores', async () => {
+ await modelOptions({ provider: 'activepieces', modelType: 'text' });
+
+ expect(requestedUrls().some((url) => url.includes('v1/ai-providers/tiers'))).toBe(true);
+ expect(requestedUrls().some((url) => url.includes('/models'))).toBe(false);
+ });
+
+ it('offers the release\'s tiers, still as tier ids, when the server has no tiers route', async () => {
+ answer({ tiers: null });
+ const state = await modelOptions({ provider: 'activepieces', modelType: 'text' });
+
+ expect(state.options).toEqual(bundledTierOptions);
+ expect(requestedUrls().some((url) => url.includes('/models'))).toBe(false);
+ });
+
+ it('offers the release\'s tiers when the published flow list is empty', async () => {
+ answer({ tiers: { ...publishedTiers, flow: { tiers: [], defaultTierId: '' } } });
+ const state = await modelOptions({ provider: 'activepieces', modelType: 'text' });
+
+ expect(state.options).toEqual(bundledTierOptions);
+ });
+});
+
+describe('the managed image model dropdown', () => {
+ it('stays on concrete models, because no image tier is published', async () => {
+ const state = await modelOptions({ provider: 'activepieces', modelType: 'image' });
+
+ expect(state.options).toEqual([
+ { label: 'Expert', value: 'google/gemini-3.1-flash-image' },
+ ]);
+ expect(requestedUrls().every((url) => !url.includes('/tiers'))).toBe(true);
+ });
+});
+
+describe('a provider the customer brought their own key for', () => {
+ it('lists concrete models and never asks for tiers', async () => {
+ const state = await modelOptions({ provider: 'openai', modelType: 'text' });
+
+ expect(state.options).toEqual([
+ { label: 'Claude Haiku 4.5', value: 'anthropic/claude-haiku-4.5' },
+ { label: 'Claude Sonnet 4.6', value: 'anthropic/claude-sonnet-4.6' },
+ ]);
+ expect(requestedUrls().every((url) => !url.includes('/tiers'))).toBe(true);
+ });
+
+ it('asks for a provider first when none is picked', async () => {
+ const state = await aiProps({ modelType: 'text' }).model.options(
+ {},
+ createMockActionContext({ propsValue: {} }),
+ );
+
+ expect(state.disabled).toBe(true);
+ expect(state.placeholder).toBe('Select AI Provider');
+ });
+});
diff --git a/packages/pieces/community/ai/src/lib/common/props.ts b/packages/pieces/community/ai/src/lib/common/props.ts
index af514dd0db8..d6b09f929f3 100644
--- a/packages/pieces/community/ai/src/lib/common/props.ts
+++ b/packages/pieces/community/ai/src/lib/common/props.ts
@@ -1,13 +1,12 @@
-import { ACTIVEPIECES_CHAT_TIERS, ACTIVEPIECES_IMAGE_TIERS, PieceAuth, Property } from '@activepieces/pieces-framework';
+import { ACTIVEPIECES_CHAT_TIERS, ACTIVEPIECES_IMAGE_TIERS, PieceAuth, Property, tryCatch } from '@activepieces/pieces-framework';
import { httpClient, HttpMethod } from '@activepieces/pieces-common';
import { isNil } from '@activepieces/pieces-framework';
import { AIProviderModel, AIProviderName, ProjectAIProvider } from '@activepieces/pieces-framework';
type AIModelType = 'text' | 'image';
-function managedModelLabel({ modelId, modelType }: { modelId: string; modelType: AIModelType }): string | undefined {
- const tiers = modelType === 'image' ? ACTIVEPIECES_IMAGE_TIERS : ACTIVEPIECES_CHAT_TIERS;
- return tiers.find((tier) => tier.modelId === modelId)?.label;
+function managedImageModelLabel({ modelId }: { modelId: string }): string | undefined {
+ return ACTIVEPIECES_IMAGE_TIERS.find((tier) => tier.modelId === modelId)?.label;
}
async function listProviders(ctx: {
@@ -23,6 +22,24 @@ async function listProviders(ctx: {
return body;
}
+async function listFlowTiers(ctx: {
+ server: { apiUrl: string; token: string };
+}): Promise<ListedTier[]> {
+ const { data } = await tryCatch(async () => {
+ const { body } = await httpClient.sendRequest<ListedTiers>({
+ method: HttpMethod.GET,
+ url: `${ctx.server.apiUrl}v1/ai-providers/tiers`,
+ headers: {
+ Authorization: `Bearer ${ctx.server.token}`,
+ },
+ });
+ return body.flow.tiers;
+ });
+ return isNil(data) || data.length === 0
+ ? ACTIVEPIECES_CHAT_TIERS.map(({ id, label }) => ({ id, label }))
+ : data;
+}
+
function providerOptionsOf(provider: ListedProvider): {
label: string;
value: AIProviderSelection;
@@ -106,6 +123,15 @@ export const aiProps = <T extends AIModelType>({
}
const { provider, configId } = selection;
+ if (provider === AIProviderName.ACTIVEPIECES && modelType === 'text') {
+ const tiers = await listFlowTiers(ctx);
+ return {
+ placeholder: 'Select AI Model',
+ disabled: false,
+ options: tiers.map((tier) => ({ label: tier.label, value: tier.id })),
+ };
+ }
+
const { body: allModels } =
await httpClient.sendRequest<AIProviderModel[]>({
method: HttpMethod.GET,
@@ -121,9 +147,9 @@ export const aiProps = <T extends AIModelType>({
disabled: false,
options: allModels
.filter(model => model.type === modelType)
- .filter(model => provider !== AIProviderName.ACTIVEPIECES || managedModelLabel({ modelId: model.id, modelType }) !== undefined)
+ .filter(model => provider !== AIProviderName.ACTIVEPIECES || managedImageModelLabel({ modelId: model.id }) !== undefined)
.map(model => ({
- label: provider === AIProviderName.ACTIVEPIECES ? (managedModelLabel({ modelId: model.id, modelType }) ?? model.name) : model.name,
+ label: provider === AIProviderName.ACTIVEPIECES ? (managedImageModelLabel({ modelId: model.id }) ?? model.name) : model.name,
value: model.id,
})),
};
@@ -157,3 +183,12 @@ type AIPropsParams<T extends AIModelType> = {
type ListedProvider = Omit<ProjectAIProvider, 'keys'> & {
keys?: ProjectAIProvider['keys'];
};
+
+type ListedTier = {
+ id: string;
+ label: string;
+};
+
+type ListedTiers = {
+ flow: { tiers: ListedTier[] };
+};
diff --git a/packages/server/api/src/app/ai/ai-execute-controller.ts b/packages/server/api/src/app/ai/ai-execute-controller.ts
index 25b0aa20b4a..7f309ff6f57 100644
--- a/packages/server/api/src/app/ai/ai-execute-controller.ts
+++ b/packages/server/api/src/app/ai/ai-execute-controller.ts
@@ -8,6 +8,7 @@ import { system } from '../helper/system/system'
import { AppSystemProp } from '../helper/system/system-props'
import { assertCreditsAndAppSumoNotExceeded } from '../platform/billing-provider'
import { aiExecution } from './ai-execution'
+import { aiModelResolution } from './ai-model-resolution'
export const aiExecuteController: FastifyPluginAsyncZod = async (app) => {
const bodyLimit = maxSocketHttpBufferSizeBytes(system.getNumberOrThrow(AppSystemProp.MAX_FILE_SIZE_MB))
@@ -26,29 +27,37 @@ export const aiExecuteController: FastifyPluginAsyncZod = async (app) => {
const requestId = apId()
const log = request.log.child({ flowRun: { id: body.flowRunId }, requestId })
const execution = aiExecution(log)
+ const modelId = body.action === AiStepAction.GENERATE_IMAGE
+ ? body.modelId
+ : aiModelResolution.resolveTierModelId({ provider: body.provider, modelId: body.modelId, log })
const answerInThisRequest = isNil(body.waitpointId)
const timeoutMs = system.getNumberOrThrow(AppSystemProp.FLOW_TIMEOUT_SECONDS) * 1000
const answer = answerInThisRequest ? execution.waitForAnswer({ requestId, timeoutMs }) : undefined
await execution.enqueue(aiJobFor({
body,
+ modelId,
requestId,
projectId,
platformId: platform.id,
webserverId: answerInThisRequest ? execution.serverId() : undefined,
}))
+ log.info({
+ project: { id: projectId },
+ model: { id: modelId },
+ tier: modelId === body.modelId ? undefined : { id: body.modelId },
+ }, '[aiExecuteController] Enqueued AI step')
if (!isNil(answer)) {
return reply.status(StatusCodes.OK).send({ requestId, ...await answer })
}
-
- log.info({ project: { id: projectId } }, '[aiExecuteController] Enqueued AI step')
return reply.status(StatusCodes.OK).send({ requestId })
})
}
-function aiJobFor({ body, requestId, projectId, platformId, webserverId }: {
+function aiJobFor({ body, modelId, requestId, projectId, platformId, webserverId }: {
body: z.infer<typeof ExecuteAiRequest>
+ modelId: string
requestId: string
projectId: string
platformId: string
@@ -65,7 +74,7 @@ function aiJobFor({ body, requestId, projectId, platformId, webserverId }: {
waitpointId: body.waitpointId,
webserverId,
provider: body.provider,
- modelId: body.modelId,
+ modelId,
prompt: body.prompt,
providerConfigId: body.providerConfigId,
maxOutputTokens: body.maxOutputTokens,
diff --git a/packages/server/api/src/app/ai/ai-model-resolution.ts b/packages/server/api/src/app/ai/ai-model-resolution.ts
new file mode 100644
index 00000000000..eb0445d1fdc
--- /dev/null
+++ b/packages/server/api/src/app/ai/ai-model-resolution.ts
@@ -0,0 +1,19 @@
+import { AIProviderName, isNil } from '@activepieces/core-utils'
+import { modelTierCatalog } from '@activepieces/server-utils'
+import { FastifyBaseLogger } from 'fastify'
+
+function resolveTierModelId({ provider, modelId, log }: { provider: AIProviderName, modelId: string, log: FastifyBaseLogger }): string {
+ if (provider !== AIProviderName.ACTIVEPIECES || modelId.length === 0 || modelId.includes('/')) {
+ return modelId
+ }
+ const flow = modelTierCatalog.current('flow')
+ const tier = flow.findTier({ tierId: modelId })
+ if (isNil(tier)) {
+ log.warn({ tier: { id: modelId }, surface: 'flow' }, '[aiModelResolution] Tier is no longer published; running the flow default')
+ }
+ return (tier ?? flow.resolveTier({ tierId: modelId })).modelId
+}
+
+export const aiModelResolution = {
+ resolveTierModelId,
+}
diff --git a/packages/server/api/test/integration/ce/ai-provider/ai-execute.test.ts b/packages/server/api/test/integration/ce/ai-provider/ai-execute.test.ts
new file mode 100644
index 00000000000..109584f5cb2
--- /dev/null
+++ b/packages/server/api/test/integration/ce/ai-provider/ai-execute.test.ts
@@ -0,0 +1,85 @@
+import { AIProviderName, apId } from '@activepieces/core-utils'
+import { modelTierCatalog } from '@activepieces/server-utils'
+import { AiStepAction, PrincipalType } from '@activepieces/shared'
+import { FastifyInstance } from 'fastify'
+import { StatusCodes } from 'http-status-codes'
+import { vi } from 'vitest'
+import { generateMockToken } from '../../../helpers/auth'
+import { createTestContext, TestContext } from '../../../helpers/test-context'
+import { setupTestEnvironment, teardownTestEnvironment } from '../../../helpers/test-setup'
+import { publishedTierReaders } from '../../../unit/app/ee/agent/model-tier-fixture'
+
+const { enqueue } = vi.hoisted(() => ({ enqueue: vi.fn() }))
+
+vi.mock('../../../../src/app/ai/ai-execution', () => ({
+ aiExecution: () => ({ serverId: () => 'server-1', enqueue, waitForAnswer: vi.fn() }),
+}))
+
+let app: FastifyInstance | null = null
+let ctx: TestContext
+
+beforeAll(async () => {
+ app = await setupTestEnvironment({ fresh: true })
+})
+
+afterAll(async () => {
+ await teardownTestEnvironment()
+})
+
+beforeEach(async () => {
+ ctx = await createTestContext(app!)
+ enqueue.mockReset().mockResolvedValue(undefined)
+ vi.spyOn(modelTierCatalog, 'current').mockImplementation((surface) => publishedTierReaders[surface])
+})
+
+afterEach(() => {
+ vi.restoreAllMocks()
+})
+
+async function executeAiStep({ action, modelId }: { action: AiStepAction, modelId: string }) {
+ const engineToken = await generateMockToken({
+ type: PrincipalType.ENGINE,
+ id: apId(),
+ projectId: ctx.project.id,
+ platform: { id: ctx.platform.id },
+ })
+ return app!.inject({
+ method: 'POST',
+ url: '/api/v1/ai/execute',
+ headers: { authorization: `Bearer ${engineToken}` },
+ body: {
+ action,
+ flowId: apId(),
+ flowRunId: apId(),
+ waitpointId: apId(),
+ provider: AIProviderName.ACTIVEPIECES,
+ modelId,
+ prompt: 'hello',
+ },
+ })
+}
+
+describe('POST /v1/ai/execute', () => {
+ it('enqueues the model a tier id points at today, so the worker and billing never see the tier', async () => {
+ const response = await executeAiStep({ action: AiStepAction.ASK_AI, modelId: 'deep' })
+
+ expect(response.statusCode).toBe(StatusCodes.OK)
+ expect(enqueue).toHaveBeenCalledTimes(1)
+ expect(enqueue.mock.calls[0][0]).toMatchObject({
+ action: AiStepAction.ASK_AI,
+ provider: AIProviderName.ACTIVEPIECES,
+ modelId: 'anthropic/claude-fable-5.1',
+ })
+ })
+
+ it('leaves an image step\'s model alone even when it spells a tier id, because image tiers reuse the text tier ids', async () => {
+ const response = await executeAiStep({ action: AiStepAction.GENERATE_IMAGE, modelId: 'smart' })
+
+ expect(response.statusCode).toBe(StatusCodes.OK)
+ expect(enqueue).toHaveBeenCalledTimes(1)
+ expect(enqueue.mock.calls[0][0]).toMatchObject({
+ action: AiStepAction.GENERATE_IMAGE,
+ modelId: 'smart',
+ })
+ })
+})
diff --git a/packages/server/api/test/unit/app/ai/ai-model-resolution.test.ts b/packages/server/api/test/unit/app/ai/ai-model-resolution.test.ts
new file mode 100644
index 00000000000..cc5ba6e0500
--- /dev/null
+++ b/packages/server/api/test/unit/app/ai/ai-model-resolution.test.ts
@@ -0,0 +1,65 @@
+import { AIProviderName } from '@activepieces/core-utils'
+import { modelTierCatalog } from '@activepieces/server-utils'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { aiModelResolution } from '../../../../src/app/ai/ai-model-resolution'
+import { publishedTierReaders } from '../ee/agent/model-tier-fixture'
+
+const warn = vi.fn()
+const log = { info: vi.fn(), warn, error: vi.fn(), debug: vi.fn() } as never
+
+function resolve({ provider = AIProviderName.ACTIVEPIECES, modelId }: { provider?: AIProviderName, modelId: string }): string {
+ return aiModelResolution.resolveTierModelId({ provider, modelId, log })
+}
+
+beforeEach(() => {
+ warn.mockClear()
+ vi.spyOn(modelTierCatalog, 'current').mockImplementation((surface) => publishedTierReaders[surface])
+})
+
+afterEach(() => {
+ vi.restoreAllMocks()
+})
+
+describe('aiModelResolution.resolveTierModelId', () => {
+ it('a tier the release never shipped runs the model the published flow list gives it', () => {
+ expect(resolve({ modelId: 'deep' })).toBe('anthropic/claude-fable-5.1')
+ expect(modelTierCatalog.current).toHaveBeenCalledWith('flow')
+ expect(warn).not.toHaveBeenCalled()
+ })
+
+ it('reads the flow list, not the chat list, where the two disagree on smart', () => {
+ expect(resolve({ modelId: 'smart' })).toBe('anthropic/claude-sonnet-4.6')
+ })
+
+ it('a chat-only tier is unknown on the flow surface and runs the flow default with one warning', () => {
+ expect(resolve({ modelId: 'turbo' })).toBe('anthropic/claude-sonnet-4.6')
+ expect(warn).toHaveBeenCalledTimes(1)
+ expect(warn).toHaveBeenCalledWith({ tier: { id: 'turbo' }, surface: 'flow' }, expect.stringContaining('no longer published'))
+ })
+
+ it('an unknown bare slug runs the flow default and warns once', () => {
+ expect(resolve({ modelId: 'tier-9' })).toBe('anthropic/claude-sonnet-4.6')
+ expect(warn).toHaveBeenCalledTimes(1)
+ })
+
+ it('leaves a managed model id alone: Haiku, not Sonnet, because Sonnet is the default a bare resolveTier would return by accident', () => {
+ expect(resolve({ modelId: 'anthropic/claude-haiku-4.5' })).toBe('anthropic/claude-haiku-4.5')
+ expect(warn).not.toHaveBeenCalled()
+ })
+
+ it('leaves an own-key provider\'s bare slug alone, because only the managed provider stores tiers', () => {
+ expect(resolve({ provider: AIProviderName.OPENAI, modelId: 'gpt-5' })).toBe('gpt-5')
+ expect(resolve({ provider: AIProviderName.AZURE, modelId: 'smart' })).toBe('smart')
+ expect(warn).not.toHaveBeenCalled()
+ })
+
+ it('passes an empty model id through so the provider reports it, as today', () => {
+ expect(resolve({ modelId: '' })).toBe('')
+ expect(warn).not.toHaveBeenCalled()
+ })
+
+ it('leaves the AI Router\'s model alone', () => {
+ expect(resolve({ modelId: 'typesafe/jev-1.13' })).toBe('typesafe/jev-1.13')
+ expect(warn).not.toHaveBeenCalled()
+ })
+})