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(flows): AI Router, one question picks the route (#15707)

Louai Boumediene5885f009ad30
diff --git a/brain/knowledge/ai-intelligence/ai-agents.md b/brain/knowledge/ai-intelligence/ai-agents.md
index 0ffbc194f80..4402b623bb5 100644
--- a/brain/knowledge/ai-intelligence/ai-agents.md
+++ b/brain/knowledge/ai-intelligence/ai-agents.md
@@ -62,6 +62,8 @@ A flow step type (the `run_agent` action of `@activepieces/piece-ai`) that runs
- **A tool's *property keys* are user text too, and nothing guards them.** `mcpToolNameUtils` covers the tool NAME; the input schema's keys come straight from `property.name`, the field labels a customer typed into the MCP trigger, at `agent-run-controller.ts` (`resolveFlowTools`) and `mcp-server-builder.ts` (`registerFlowTools`), which build the shape identically. A field called `Email Sender` produces a key with a space, which Anthropic rejects on the same `^[a-zA-Z0-9_.-]{1,64}$` rule it applies to names, so that flow-as-tool step can never succeed. Sanitising is only half a fix: the payload is handed to the flow as its trigger body, so `{{trigger['Email Sender']}}` in existing flows needs a key→label map to translate back. Fix it in one shared helper, because the MCP server ships the same invalid schema to any Anthropic-backed client.
+- **Do not raise `ai` past 7.0.69 — from `[email protected]` the SDK stops auto-executing tools, and it fails silently.** Bisected on 2026-09-21 while trying to reach `experimental_evaluate`. On 7.0.44 (what the repo pins) and every version through 7.0.69, a tool call executes normally. From **7.0.70** onward, including 7.0.103–7.0.107, `generateText`/`streamText` still *recognise* the call — `staticToolCalls=1`, a `tool-call` part is emitted with correctly parsed input — but `execute` is never invoked and `toolResults` stays `0`. No error, no warning. The changelog entry for 7.0.70 is `a828527: Prevent automatic tool execution when a model call ends with an unsafe finish reason`, but the gate fires for every `finishReason` tried, `tool-calls` and `stop` included. Reproduced in a clean project outside the monorepo, on both `MockLanguageModelV3` and `MockLanguageModelV4`, on zod 3 and zod 4; `needsApproval: false` and `toolApproval: () => false` do not restore it, and neither does emitting the full `tool-input-start`/`delta`/`end` lifecycle before the `tool-call`. The alarm is `packages/server/worker/test/lib/agent-eval/agent-tool-call-repair.test.ts` — 4 of its 5 tests go red, and they look like a *repair* regression, which is the wrong trail: a plain valid tool call does not execute either. **Consequence: `experimental_evaluate` (first shipped in 7.0.103) cannot be reached without breaking the agent**, so anything needing typed evaluation calls the gateway's `/v4/ai/evaluation-model` endpoint over `safeHttp` instead of taking the bump. Re-test the table above before any future `ai` upgrade; if a release fixes it, that is the one to jump to.
+
### Key files
Entry point: `runAgent`, the createAction in the `ai` piece registered in `packages/pieces/community/ai/src/index.ts`.
diff --git a/brain/knowledge/ai-intelligence/ai-providers.md b/brain/knowledge/ai-intelligence/ai-providers.md
index 8028d07b79e..13d7a3ba78c 100644
--- a/brain/knowledge/ai-intelligence/ai-providers.md
+++ b/brain/knowledge/ai-intelligence/ai-providers.md
@@ -116,7 +116,13 @@ renders and preserves every real price; the cheapest in the set is 0.01.
per turn for an agent** — an agent turn is many model round-trips, so charging it per call would have
silently raised the price of every agent on a customer's own key. The caller says which it wants with
`ownKeyCredit`, and the agent's turn credit is charged in `chatToolBilling.chargeForLatestTurn`
- alongside its tool calls.
+ alongside its tool calls. **The worker does not know the edition, so the one own-key credit is
+ reported on Community too; the API is what drops it.** `aiChargeFor` returns fixed credits for any
+ non-`ACTIVEPIECES` provider, and only the CLOUD and ENTERPRISE arms of `app.ts` set the Autumn
+ `billingProvider`; the default provider's `trackFeature` is a no-op, so Community records nothing
+ and its `getCreditsAndAppSumoState` never blocks. Enterprise records the credit but
+ `shouldBlockRunOnCredits` returns false for that edition, so only Cloud can refuse an AI call for
+ being out of credits. Self-hosters on their own OpenRouter key pay OpenRouter directly, not us.
- **OpenRouter only reports `usage.cost` when the request asks for it.** The provider sends
`usage: this.settings.usage` in the request body and copies `cost` into `providerMetadata` only when
the response carries one, so without `usage: { include: true }` every managed call reports no cost,
@@ -164,3 +170,5 @@ renders and preserves every real price; the cheapest in the set is 0.01.
- `packages/web/src/features/agents/ai-model/` — model selector used in agent step settings
Paths verified 2026-07-26.
+- **`OPENROUTER_PROVISION_KEY` is a management key and cannot make inference calls; only the per-platform keys it mints can.** OpenRouter states it outright: management keys are for creating, listing, updating and deleting other keys and are rejected by every completion or decisions endpoint. So "we already have an OpenRouter key" is true for provisioning and false for anything that needs to call a model at the instance level (the AI Router's Jev call, for example): that needs an ordinary inference key from the same account, created in the dashboard or via the same `POST /keys` the instance already uses, with a credit `limit`. The AI Router does exactly that since 2026-09-23: it runs on the platform's managed key where credits are on, else the admin's own OpenRouter row, as a worker `EXECUTE_AI` job billed like any AI step.
+- **`z.enum(SomeTsEnum).exclude([SomeTsEnum.MEMBER])` compiles and excludes nothing at the type level; pass the key string, `.exclude(['MEMBER'])`.** zod's `exclude` is typed over `keyof T` and returns `ZodEnum<Omit<T, U[number]>>`. A TS enum member is its own literal type, not the string `'MEMBER'`, so `Omit` finds no key to drop and the inferred value type keeps every member, while the runtime check does exclude it. The symptom is one step removed from the cause: a switch over the parsed field is suddenly non-exhaustive (`switch-exhaustiveness-check` in lint, `TS2366` in the build) even though the branch you removed can never arrive. `/v1/ai/execute` hit this when `ROUTE` was carved out of `AiStepAction` for #15707. Neither vitest nor a package-local eslint run without type information reports it; only the build does.
diff --git a/brain/knowledge/ai-intelligence/mcp-server.md b/brain/knowledge/ai-intelligence/mcp-server.md
index d2cd7b043ee..54e9bd3be4a 100644
--- a/brain/knowledge/ai-intelligence/mcp-server.md
+++ b/brain/knowledge/ai-intelligence/mcp-server.md
@@ -126,3 +126,4 @@ Paths verified 2026-07-17.
list rather than hiding the rows. Note the failure shape: a disabled tool is never `registerTool`d, so the
client gets an unknown-tool error from the protocol, not a permission denial from inside the tool — the
copy "every call fails" is directionally right but one layer off.
+- **The wording of an MCP tool's `❌ …` reply is part of a contract: `test/integration/ce/mcp/mcp-tools.test.ts` asserts substrings of it verbatim.** Rewording `resolveRouterStep`'s rejection from `not a ROUTER step` to `not a router step (ROUTER or AI_ROUTER)` failed case 62 of that suite, and only in CI, because the CE integration tests need Postgres and are not run locally. Before touching any tool's user-facing text, `grep -n "<old phrase>" packages/server/api/test/integration/ce/mcp/` and either keep the asserted substring or update the assertion in the same commit.
diff --git a/brain/knowledge/decisions/000016-managed-ai-metering-moves-to-centralized-worker-execution.md b/brain/knowledge/decisions/000016-managed-ai-metering-moves-to-centralized-worker-execution.md
index d365f2c5108..16aabade149 100644
--- a/brain/knowledge/decisions/000016-managed-ai-metering-moves-to-centralized-worker-execution.md
+++ b/brain/knowledge/decisions/000016-managed-ai-metering-moves-to-centralized-worker-execution.md
@@ -54,3 +54,4 @@ managed-AI gate/metering should fold into it rather than being hardened in its c
- The centralized path must preserve today's non-blocking properties (billing must not add per-token
latency, per WS6): the goal is *observed* usage at one place, not a synchronous console/Autumn round-trip
on every token.
+- The AI Router (2026-09-23) is the first non-language-model call through the chokepoint: an `EXECUTE_AI` job with `action: ROUTE`, billed from the Decisions response's `usage.cost` via `activepiecesAiCost.reportProviderCost` on the managed key, or one fixed credit on an own key. No managed AI call is exempt. "Runs in the worker" names where the model call and the billing happen, not the request's origin: the engine still posts to the API (`/v1/engine/ai-router`, or `/v1/ai/execute` for AI pieces), because the sandbox can reach nothing but the API and must never hold a provider key — a reviewer's first reading of the architecture diagram was that the engine hop had been removed.
diff --git a/brain/knowledge/decisions/000039-the-ai-router-is-its-own-action-type-and-bills-nobody.md b/brain/knowledge/decisions/000039-the-ai-router-is-its-own-action-type-and-bills-nobody.md
new file mode 100644
index 00000000000..1906742ec3d
--- /dev/null
+++ b/brain/knowledge/decisions/000039-the-ai-router-is-its-own-action-type-and-bills-nobody.md
@@ -0,0 +1,122 @@
+---
+title: The AI router is its own action type and runs as a worker AI step
+icon: 🔀
+status: accepted
+---
+
+# The AI router is its own action type and runs as a worker AI step
+
+## Decision
+
+**AI Router is a real `FlowActionType.AI_ROUTER`**, not a Router mode and not a piece action. It asks
+one question at the root and each branch is one possible answer, inverting the Router's one-condition-
+tree-per-branch model. It calls Jev (`typesafe/jev-1.13`) through **OpenRouter's Decisions API on the
+platform's own OpenRouter key**, as a `ROUTE` action of the worker's `EXECUTE_AI` job, and it **pauses
+the run while it waits**: the engine creates a waitpoint, posts to `/v1/engine/ai-router` with its id,
+marks the step `PAUSED` and gives its worker slot back; the API picks the provider, gates credits and
+enqueues; the worker makes the call, bills it and resumes the run through `resumeAiStep`. On resume a
+decided router reuses its stored evaluations and never asks again, so a pause inside a route costs
+nothing. Only a single-action run, which cannot pause, still waits synchronously. The key is the managed Activepieces provider where credits are on, else the admin's own
+OpenRouter row; the step has no provider or model picker and appears in the picker only when the
+project's provider list contains one of the two. Billing is decision 000037 unchanged: observed
+`usage.cost` on the managed key, one fixed credit on an own key. In the picker it sits in the Utility
+tab under **Flow Controller** beside the Router, never in the AI tab: it is a branching step that
+happens to use a model, and `isAiAndAgentPiece` says so by returning false for every core type.
+
+## Context
+
+The capability first shipped as `AI_MATCHES`, a 23rd entry in the Router's condition-operator
+dropdown (PR #15666, parked unmerged). It worked and nobody could find it — there is nothing to
+market from inside a `<SelectItem>`, and a condition row is the wrong shape for the decision anyway.
+
+A piece action was the cheap option and is not buildable: a piece cannot own child steps, so "AI
+Router as a piece" is Classify Text followed by a normal Router.
+
+## Why
+
+**Separate type, for the product.** The requirement was discoverability, and a distinct card, icon,
+settings panel and docs page is what delivers it. The cost is real — `FlowActionType.ROUTER` appears
+in 31 source files — but most sites widen to `flowStructureUtil.isBranchedAction` in one line, and
+the engine's branch-walking loop was extracted to `executeBranches` so both routers share it.
+
+**One `choice` question, not one `boolean` per branch.** Measured live against Jev on 2026-09-21:
+three sequential boolean calls took **1699 ms / 871 input tokens**; the same decision as one choice
+question took **385 ms / 367 tokens**. The choice answer is also guaranteed to be one of the option
+names, so "the model picked a branch that does not exist" is structurally impossible.
+
+**The fallback branch is sent to the model as a real named option.** This is the non-obvious part.
+Without it, the input `"hi"` routed to `Sales` at probability **0.87** — confidently wrong, and past
+any sane threshold. With an explicit `Otherwise` criterion, `"hi"` and `"what is the weather today"`
+both go to Otherwise at **1.00** while a clear billing message still goes to Billing at 1.00. A
+confidence floor is kept as a second, independent net, but it is not the mechanism.
+
+**Billed like any AI step, through the worker chokepoint.** The first cut billed nobody and called a
+Vercel AI Gateway from the API process with an instance-wide key, on the reasoning that Jev costs
+$0.042 per 1M input tokens and a usage pipeline would cost more than the inference. Its own
+Consequences warned that metering had to land before flows depended on free routing, and the PR was
+unmerged, so it did. Running the call as an `EXECUTE_AI` job reuses the pipeline decisions 000016 and
+000037 already built — provider resolution, `assertCreditsAndAppSumoNotExceeded` before the job, cost
+reported from the worker over RPC — instead of a second one beside it. The step still asks nothing of
+the user: the provider is picked server-side from `listForProject`, which is also what the picker
+reads, so server and picker agree by construction.
+
+## Consequences
+
+A routing decision costs the platform what it costs us on the managed key (about 0.02 to 0.08
+credit) and one credit on an own key; a production run through one router is therefore about one
+credit plus a fraction. The pause exists because a flow job and the router's `EXECUTE_AI` job share
+one worker queue and a loop holds its slot for the whole job: a router that blocked on its own answer
+would starve itself at low concurrency and deadlock five flows at the default of five (see the
+starvation gotcha on [[workers]]). The waitpoint's deadline is ten minutes; a deadline resume carries
+no answer and fails the step with a readable message. The synchronous path (single-action runs) keeps
+the old nesting: engine 30 s, API 25 s, worker HTTP 8 s. Community Edition has no OpenRouter key
+unless the admin adds one, so the step is hidden there by default — the price of dropping the
+instance-wide env var. OpenRouter's Decisions endpoint is alpha; its wire format lives in one worker
+file (`route.ts`) with a unit test per answer shape.
+
+A failed or timed-out call **fails the step**. It never quietly takes the fallback, because routing a
+refund down the wrong branch because a model timed out is a correctness bug that looks like normal
+operation.
+
+The step started with **no `executionType`**, on the reasoning that a choice answer names exactly one
+branch so all-match had no meaning. That held only while the step asked one `choice` question. It now
+carries `matchMode`: `BEST_MATCH` asks one `choice` question and exactly one route runs, while
+`ALL_MATCHES` asks one `noul` question per route — in a single request, since Jev's
+`questions` field is a record — and every affirmed route runs. The fallback rule mirrors the Router's
+exactly: it runs iff no other route did.
+
+The two modes differ in a way that is easy to get wrong: **`ALL_MATCHES` never sends the fallback to
+the model.** There is no forced choice to decline from, so booleans can all be false on their own and
+the fallback is computed locally. The measured "give the model an explicit `Otherwise` criterion or
+`hi` routes to Sales at 0.87" finding therefore applies to `BEST_MATCH` only. `ALL_MATCHES` also
+costs one question per route instead of one per step, which is the honest trade for fan-out.
+
+`AI_MATCHES` (PR #15666) is parked. If it ever merges, the product carries two AI branching concepts
+and that needs its own call.
+
+**The AI router will never absorb the Router, and the reason is worth knowing before someone
+proposes it.** The two differ in *evaluator*, not interface: determinism, zero cost and zero latency
+are properties of not calling a model. You can get "same answer usually"; you cannot get "same answer
+forever", because the model version lives outside the flow and a vendor upgrade can re-route a
+historical case. Temperature, seeds and caching do not change that. So anything a human must defend
+years later — compliance gates, billing tiers, approval thresholds — stays on the Router permanently.
+
+The gaps that *are* reachable, and how, so the design does not get re-derived: **fan-out** by a
+match-mode toggle (one `choice` question → one route, N `boolean` questions → every route that
+applies, which is the Router's first-match/all-match concept and the cheapest of the three);
+**facts** (thresholds, exists, two-value comparisons) by an optional one-line deterministic *guard*
+per route, evaluated first so guarded-out routes never reach the criteria map; **multi-dimensional
+routing** by asking several questions in one call and matching routes on combinations, which Jev's
+plural `questions` record already supports and which the Router cannot do on meaning at
+all. The guiding line is that the model turns unbounded text into a small enumerated value and
+everything after that is data. The standing risk on guards is that a nested condition builder inside
+a route rebuilds the Router twice and loses the pitch — one guard, one line, no AND/OR groups.
+
+The MCP flow-building tools resolve both router kinds for structure, validation and delete.
+`ap_add_branch` and `ap_update_branch` refuse an AI router with a message, and `ap_add_step` cannot
+create one, because letting the agent build one without settings support would let it build broken
+steps. Those three need a per-type body.
+
+**Jev is on OpenRouter, but not where a catalog scan looks.** `GET /api/v1/models` lists text-producing models only; Jev's output modality is `decisions`, so it is absent there and lives at `POST https://openrouter.ai/api/alpha/decisions` as model `typesafe/jev-1.13` (`jev-latest` 404s, so pin the version). Same price as the gateway, $0.042/M in and free out, 32k context. The wire format, confirmed against OpenRouter's own Jev tutorial: body `{ model, state, questions }` with `state` an object (we send `{ text }`), a yes/no question is `type: "noul"` and its answer is `{ type: "noul", noul }` where `noul` is P(true) — no `answer`, no `probability` field — a choice answer is `{ choice, confidence, probabilities }`, and `usage` carries `input_tokens`, `output_tokens` and `cost` in dollars by default. A first pass of this note claimed OpenRouter had no Jev, from scanning the text-model catalog only.
+
+**Decided 2026-09-23: run in the worker on OpenRouter, reversing the previous day's "stay on the gateway".** That call rested on a false premise: it said the only OpenRouter key the instance held was the management key, which cannot call a model. The management key is indeed inference-blind, but `enrichWithKeysIfNeeded` uses it to mint a real inference key per platform for the managed Activepieces provider, and any admin who added OpenRouter under AI providers holds one too. So the deployment already had a callable key, the gateway added a second vendor for nothing, and the worker pipeline could bill the call for free. The move also improves `.claude/rules/self-hosting.md` compliance: one env var fewer, and the key it reuses is one the deployment already manages.
diff --git a/brain/knowledge/engineering/ci-pr-review-hygiene.md b/brain/knowledge/engineering/ci-pr-review-hygiene.md
index bb5df7218db..65f3e930e25 100644
--- a/brain/knowledge/engineering/ci-pr-review-hygiene.md
+++ b/brain/knowledge/engineering/ci-pr-review-hygiene.md
@@ -30,10 +30,13 @@ Enforcement is the **`Codeowners review` repository ruleset** (active on the def
- **Repo-wide regenerators sweep `main`'s pending drift into your PR — run them, then keep only your own lines.** `npm run i18n:extract` reorders all of `en/translation.json` and rewrites nine locale files (130 moved lines for six new keys), and `bun install` after a version bump writes back every community-piece version that was bumped without a lockfile sync (103 lines for four intended bumps). Both diffs are indistinguishable from real work in review, and both bury the change you actually made. Revert the file and hand-apply your own entries instead — then prove parity by running the generator into a scratch copy and diffing just your keys against it, so you keep byte-identical output without the churn. Provider setup markdown in `features/agents/ai-providers.ts` is extracted as translation keys in **source order**, so new entries go beside their neighbours in `SUPPORTED_AI_PROVIDERS`, not at the end.
- **`.env.dev` is TRACKED, so the `.env*` line in `.gitignore` does not protect it — secrets put there get committed.** `.gitignore` line 82 is `.env*`, which reads as blanket protection for every env file, but gitignore has no effect on a path already in the index, and both `.env.dev` and `.env.example` are committed on `main`. `git check-ignore .env.dev` returns nothing, which is the tell. So an SMTP password or API key dropped into `.env.dev` shows up in `git status` as a normal modification and rides the next `git add -A`. Put local secrets under `dev/` instead — that whole directory is genuinely ignored (line 27) — and reach for `git check-ignore -v <path>` before writing a credential anywhere, rather than trusting the pattern.
- **A bare `*` in CODEOWNERS matches every file at every depth, so the catch-all owner is dragged into PRs that have nothing to do with them.** Unlike `docs/*` (direct children only), `*` is fully recursive, and last-match-wins means only an explicit later rule can release a path. A lockfile-only PR requested `core` ([#14629](https://github.com/activepieces/activepieces/pull/14629)), and so did a single-page docs PR ([#14422](https://github.com/activepieces/activepieces/pull/14422), one file under `brain/`). The release valve is a **path listed with no owner after the `*` line**, which GitHub reads as owned-by-nobody; CODEOWNERS has no `!negation` syntax and no brace expansion — `packages/**/{A,B}.md` parses clean and matches a file literally named `{A,B}.md`. Verify any edit with `gh api repos/activepieces/activepieces/codeowners/errors` — an invalid line is silently *skipped*, which quietly restores the catch-all owner instead of failing loudly.
+- **A long-lived branch that bumps a `packages/core/*` version will conflict with main in exactly two places, `package.json` and the workspace's `"version"` line in `bun.lock`, and the fix is the same both times.** Both sides bumped from the same base (main 0.7.0→0.8.0, the branch 0.7.0→0.7.1 on `core-utils` for #15707), so take main's number and apply the branch's own bump on top (0.8.1), write it into both files, then run `bun install`: it is a one-second no-op when `node_modules` is current and proves the lock matches the manifests. Do not take either side wholesale — main's lock alone leaves the branch's manifest unsatisfied, and the branch's alone drops main's dependency changes. Check the other core packages too: if main bumped `shared` or `execution` to the *same* number the branch chose, git auto-merges it silently and one bump then covers two releases. It happened on the very next sync of #15707: both sides took `shared` 0.176.0 → 0.177.0, the merge reported no conflict, and only a deliberate check caught it. So on every sync of a branch that touches `packages/core/*`, run `for f in packages/core/*/package.json; do echo "$f $(git show origin/main:$f | grep version) $(git show HEAD:$f | grep version)"; done` and re-bump any package where the two match but the branch changed it.
+- **Answering and resolving review threads from the CLI takes two different ids.** A reply goes through REST with the inline comment's numeric id: `gh api repos/<o>/<r>/pulls/<n>/comments/<comment_id>/replies -f body=…`. Resolving needs the *thread* id, which REST never returns: query GraphQL `pullRequest(number:<n>) { reviewThreads(first:50) { nodes { id isResolved comments(first:1) { nodes { databaseId } } } } }`, match `databaseId` to the comment you replied to, then `mutation { resolveReviewThread(input:{threadId:"PRRT_…"}) { thread { isResolved } } }`. Greptile's summary links its findings as `discussion_r<comment_id>`, which is the same numeric id. Resolve only what actually changed; leave the thread for a deferred follow-up open as its tracker.
+- **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.
-- **`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 `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.
+- **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.
+- **`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.
- **A red check does not block a merge.** The gate only prevents merges once `PR size` is added as a **required status check** for `main` in branch protection. Until then it is visible but advisory.
- **A workflow that opens a PR must authenticate with `secrets.CROWDIN_PRS`, not `GITHUB_TOKEN`.** Despite the name, that PAT is this repo's open-a-PR-as-a-bot token: `crowdin-pr-merger.yml`, `reusable-finalize-translations-pr.yml` and — the tell — `release-self-hosted.yml`, which has nothing to do with Crowdin and uses it for both `actions/checkout`'s `token:` and `gh pr create`'s `GH_TOKEN`. Those jobs declare only `permissions: contents: read`, because the PAT does the pushing and the PR-opening; raising `GITHUB_TOKEN` to `contents: write` / `pull-requests: write` instead is treating the symptom, since *Allow GitHub Actions to create and approve pull requests* is evidently off for the org (not readable without `admin:org`). The failure mode is nasty because it is half-done and unattended: the branch pushes fine and only `pulls.create` fails, leaving an orphan `auto/*` branch every scheduled run. Copy `release-self-hosted.yml`, and have the job delete its own branch on failure so a bad week retries clean instead of accumulating.
diff --git a/brain/knowledge/engineering/engineering-handbook-playbooks.md b/brain/knowledge/engineering/engineering-handbook-playbooks.md
index 081cf17d5f4..649ee54a630 100644
--- a/brain/knowledge/engineering/engineering-handbook-playbooks.md
+++ b/brain/knowledge/engineering/engineering-handbook-playbooks.md
@@ -24,3 +24,4 @@ Postmortems (Redis/queue overload, infra upgrade — March 2026) and product int
- **Running EE locally (outside the dev container) to preview a chat/agents-gated view hits four macOS-specific walls the [Run EE](https://www.activepieces.com/docs/handbook/engineering/playbooks/run-ee) playbook doesn't cover.** (1) The default dev DB, PGlite (`.env.dev`'s `AP_DB_TYPE=PGLITE`), hard-refuses `AP_EDITION=ee`/`cloud` with `Error: Edition ee not supported in pglite mode in dev environment` — point at a real local Postgres instead (`AP_DB_TYPE=POSTGRES` + a throwaway DB via `createdb`). (2) In a fresh git worktree, symlinking `node_modules` from another worktree/checkout works for lint/typecheck but not for actually running the server: workspace packages resolve through the symlink to whatever commit *that* checkout is on, so a genuine cross-branch source/type skew appears (e.g. `AIProviderName.VERTEX does not exist`) purely from the mismatch — do a real `bun install` scoped to the worktree instead. (3) `bun install` aborts the *entire* install (not just its own package) if `isolated-vm`'s native build fails, which it does on Darwin 25 (`node-gyp` / `undici` `webidl.util.markAsUncloneable is not a function`) — even though `isolated-vm` is only needed by the engine/worker sandbox, not by `api`+`web`. Fix: `bun install --ignore-scripts`, then `cd` into `node_modules/.bun/sqlite3@*/node_modules/sqlite3` and run `npx prebuild-install -r napi` directly to fetch its prebuilt native binding (something in the queue/api dependency tree requires it to *load* even when the configured DB isn't sqlite). (4) The repo requires Node 22.15+/24 (`bootstrap.ts` uses `zlib.zstdDecompress`, added in Node 22.15); a system default of Node 20 (common via `nvm`) crashes API boot with `ERR_INVALID_ARG_TYPE` in `file-compressor.ts` — put a `nvm`-installed v24 first on `PATH` before starting `serve`. Once booted: `AP_EDITION=ee` alone (no license key) is enough to preview chat/agents, since the unlicensed `AUTUMN_FREE_PLAN` already sets `chatEnabled`/`agentsEnabled: true` — but that plan's `aiProvidersEnabled: false` hides the "Connect" button on every provider card, so there is no UI path to satisfy chat's "Set up an AI provider" gate; insert a throwaway row into `ai_provider` directly via SQL (`enabledForChat: true`, `config: '{}'`, any `auth` JSON — it's only decrypted when a message is actually sent) to get past it for pure layout/UI verification.
- **`DISCORD_ON_CALL_WEBHOOK` is the single repo secret behind every on-call Discord notification** — cloud production deploys (`continuous-delivery-cloud.yml`), self-hosted releases (`release-self-hosted.yml`), and release-pieces failure alerts all post through it. Rotating it repoints all of them at once; there is no per-workflow webhook. Self-hosted release notifications skip `-rc` tags unless `publish_rc_release` is set, mirroring the release-drafter condition so the message never links a release page that doesn't exist.
- **Docs media lives on the CDN, never in the repo — and videos and images sit on two different paths.** A video embeds as `<video src="https://cdn.activepieces.com/videos/docs/<Exact-File-Name>.mp4" controls />`, an image as `![Alt](https://cdn.activepieces.com/assets/<exact-file-name>.png)`. Videos are namespaced under `videos/docs/`; images are **flat** under `assets/` with no `docs/` segment, so don't infer one path from the other — check the URL you actually mean. Both mirror the filename verbatim, so an upload is fetchable with no config change. Committing the binary instead bloats every clone forever (`docs/videos/` reached 63 MB and `docs/images/` 1.6 MB before both were removed in Sept 2026) since git history keeps the blob even after a delete. Curl each URL for a 200 before deleting a local copy: `docs/` also carries stale `.mdx` references to images that never existed in git history at all, and rewriting one of those to a CDN URL turns a visibly-missing asset into a confident 404.
+- **`mint dev` defaults to port 3000, which the local API already holds, so preview the docs with `cd docs && mint dev --port 3333`.** The CLI is `mint` (installed globally; `mintlify` is not on the path). Do not pipe its output through `head`: the spinner alone emits dozens of lines, the pipe closes, and the server dies with exit 0 looking like a clean finish. Redirect to a file and probe with `curl --retry-connrefused` instead. `mint broken-links` is the quick check for internal links and needs no server.
diff --git a/brain/knowledge/engineering/web-feature-anatomy.md b/brain/knowledge/engineering/web-feature-anatomy.md
index 8f933b3efd0..9a56c4dcb9c 100644
--- a/brain/knowledge/engineering/web-feature-anatomy.md
+++ b/brain/knowledge/engineering/web-feature-anatomy.md
@@ -180,4 +180,8 @@ way back was to stash the handful of intended edits, `git checkout` the package,
- **A `.ts` and a `.tsx` of the same name can both sit in the tree, and every importer silently binds to the `.ts`.** `hooks/use-mobile.ts` and `hooks/use-mobile.tsx` were byte-for-byte identical for months: the `.ts` arrived with #11554 and nothing removed the `.tsx` that #11440 had left. Both TypeScript's Node resolution and Vite try `.ts` before `.tsx`, so all five importers of `@/hooks/use-mobile` resolved to the `.ts` and the `.tsx` was unreachable — while still being edited, linted and typechecked like live code. Nothing flags this: the import resolves, tsc is happy, and a `grep` for the symbol shows five healthy importers, which reads as proof the file is *used*. Only a reachability tool sees it. When a file looks dead but its symbol has importers, check for a same-named sibling with the other extension before concluding the tool is wrong.
- **`knip` is the reachability check for `packages/web`; `npm run knip` must exit clean.** Config in `knip.json` at the repo root, every rule at its default `error` severity — nothing is muted, so a non-zero exit means real dead code, not noise. Two settings carry the weight. `src/features/*/index.ts` are **entry points**, because a feature barrel is that feature's public surface (see *Feature folder* above) and is meant to export more than today's callers import; without that, reachability reports the convention itself as dead. `ignoreExportsUsedInFile: true` means anything it does report is referenced *nowhere*, not even in its own file. The two `ignore*` lists cover what knip genuinely cannot see: `tailwindcss`/`tw-animate-css` arrive via `@import` in `styles.css` (knip does not follow CSS), and `dwebp`/`sips`/`cwebp` are system binaries shelled out to by `scripts/generate-usecase-images.mjs`.
- **When knip flags an export whose name clearly has live callers, look for a second symbol of that name before concluding knip is wrong.** This codebase repeatedly grew duplicates — something was moved or re-implemented and the old copy stayed — so a `grep` for the symbol finds the *other* one and reads as proof the finding is bogus. Every instance checked was knip being right: `use-mobile.ts` vs `.tsx` (identical files, resolution silently picks `.ts`), `cursor-position-context.tsx` duplicated under `flow-canvas/` and `state/` (two separate `createContext()` calls), `parseAnswerPairs` shared vs a local copy in `assistant-message.tsx`, and `FlowApprovalRequestState`/`PieceSelectorTabConfig` re-exported locally while every consumer imports them from `@activepieces/shared`. knip also resolves this repo's dynamic imports correctly, including `React.lazy(() => import(x))` (needs `default`) and `import(x).then(m => ({default: m.Named}))` (needs the named export) — do not assume it is guessing. Verify a finding by reading the importing file's actual `import` statement, never by counting `grep` hits on the name.
+- **A master/detail settings panel that `return`s one `FormField` early silently deletes that field's value when you go back.** React unwraps a keyless fragment and reconciles by position, so a detail view whose whole return is `<FormField name={`settings.branches.${i}.description`}/>` and a master view whose fragment *starts* with `<FormField name="settings.text"/>` are the same component type at index 0 — React keeps the instance and swaps the `name` prop instead of unmounting. react-hook-form's `useController` then hits `if (previousName && previousName !== name && !isArrayField) control.unregister(previousName)` ([useController.ts:200](https://github.com/react-hook-form/react-hook-form), 7.71.2), and `unregister` does `unset(_formValues, previousName)` — the value the user just typed is **deleted from the form**. `shouldUnregister` is irrelevant; this path ignores it. `isArrayField` is `isNameInFieldArray(_names.array, name)` computed from the **new** name, so detail→detail (`branches.0.description` → `branches.1.description`) is safe and detail→master (`… → settings.text`) is not — which is why the symptom reads as "the *other* route lost its value" rather than "this field is broken". The next keystroke anywhere then persists the pruned settings through `UPDATE_ACTION`, so it survives a reload too. The AI Router settings panel had this; the Router panel does not, because it never early-returns — it renders master and detail as `{isNil(selectedBranchIndex) && …}` / `{!isNil(selectedBranchIndex) && …}` siblings and gives `BranchSettings` an explicit `key` carrying the index. Copy that shape, or key the detail field, whenever a panel swaps between two subtrees that both begin with a form field. To catch it, `Proxy` the object under test with a `deleteProperty` trap that prints `new Error().stack`: a `delete` is invisible to a setter spy, and the stack names the exact library line. The same reuse also explains the *other* symptom, a route description that shows the Input text: `useWatch` keeps the default it computed at mount in a ref (`_defaultValue`) and never refreshes it on a `name` change, so when the swapped-in name has no value yet (a branch whose `description` key the unregister already deleted) `getCurrentOutput()` falls back to the first field's mount-time value, and `useController`'s render-phase `control.register(name, { value })` writes that into `_formValues`. One `key` carrying the branch index on the detail field remounts it and fixes both; `packages/web/test/app/builder/step-settings/ai-router-settings/route-description.test.tsx` reproduces both against the real panel, with the builder store stubbed through `useSyncExternalStore` because the panel is `memo`-wrapped and a non-subscribing stub never re-renders it.
+- **`applyOperation` hands the form's live `settings` object to the flow version and to the queued request.** [`flow-state.ts`](packages/web/src/app/builder/state/flow-state.ts) `applyOperation` spreads `{...cleanedNewValues}` shallowly, so `request.settings` — and after `_updateAction`'s `{...request.settings}`, `flowVersion.…settings.branches` — is the *same array of the same objects* react-hook-form is still mutating. `UPDATE_ACTION` is debounced 1 s while every other operation queues immediately, so a request can be serialized with values typed after it was created, and the local flow version mutates without zustand seeing a new reference. It also means logging a queued operation shows you the *final* state, not what was queued — do not debug ordering that way. Separately, `PromiseQueue.halt()` in the `catch` is permanent: one rejected flow update stops every later save for the rest of the session, with only the `UNSAVED_CHANGES_TOAST` to say so.
+- **A core step's picker copy (`buildCoreStepMetadata` in `step-utils.tsx`) is pinned in four places, and the test that guards it fails with a misleading message.** The English sentence is the i18n key, so it lives in `step-utils.tsx`, in `public/locales/en/translation.json`, in the matching `docs/flows/*.mdx` frontmatter, and as a key of the fake `JAPANESE_BUNDLE` inside `test/features/pieces/utils/step-utils.test.ts`. Reword the first three and the test fails with `expected ['コード', …] to include '<new sentence>'`, which reads as a locale problem; the fix is the test's own map, not a locale file. Nothing else in the repo carried the old key.
+- **A core step's icon is a CDN URL, not a bundled asset, and the SVGs under `packages/web/src/assets/img/piece/` are dead copies.** `buildCoreStepMetadata` in `step-utils.tsx` points Code, Loop, Router and Empty Trigger at `https://cdn.activepieces.com/pieces/new-core/<name>.svg`; the AI Router's is `https://cdn.activepieces.com/pieces/ai_router.png`, a PNG outside `new-core/`, so do not assume every core icon shares one folder or one format. A new core step therefore needs someone with bucket access to upload `pieces/new-core/<name>.svg` before the URL is changed — `curl -o /dev/null -w '%{http_code}'` it first, because a missing asset is a broken image that no test sees. A Vite asset import also satisfies `logoUrl` (the SSO page's Google icon does this) if the cross-team wait is not worth it. Nothing imports the local `img/piece/*.svg`; they are not the fallback.
- **Rewriting a shared component silently drops whatever props it stops destructuring, and optional props make the compiler complicit.** Replacing `LockedFeatureGuard`'s body took the `RequestTrial` sales form off 17 pages at once: every caller still passed `featureKey` and `showContactSales`, the new component just never read them, and because both stayed `?:` in the props type nothing failed to compile and no call site changed in the diff. The prop a rewrite must not lose is the one to make **required** — the moment `featureKey` was, `tsc` listed exactly the call sites that had dropped it, across all three branches of the stack. When a component's props feed a business surface rather than styling, review the destructure, not the prop list.
diff --git a/brain/knowledge/execution-runtime/workers.md b/brain/knowledge/execution-runtime/workers.md
index 4247e53dfb3..ab6b93ba862 100644
--- a/brain/knowledge/execution-runtime/workers.md
+++ b/brain/knowledge/execution-runtime/workers.md
@@ -109,6 +109,10 @@ Three things that look like bugs and aren't:
- **Removing a scheduler does not remove its already-enqueued job.** The outstanding `repeat:<oldVersionId>:<millis>` stays in `prioritized` and fires once against a soft-deleted `trigger_source`.
- **Priority-6 sludge.** `RATE_LIMIT_PRIORITY` is `lowest` = 6, so rate-limited `EXECUTE_FLOW` jobs re-enter *behind* the polling lane and never drain while polling is chronically backed up. The 2026-07-27 pile held jobs going back 19 days. Anything demoted to priority 6 on a queue with a standing priority-5 backlog is silently dropped.
+#### A worker job that waits synchronously on another worker job can starve itself
+
+`EXECUTE_FLOW` and `EXECUTE_AI` are consumed by the same poll loops from the same `WORKER_JOBS` queue, and a poll loop holds its slot for the whole job. So an engine step that blocks on an HTTP call to the API, which enqueues a worker job and waits for its answer, needs a *second* free loop to ever complete. The AI Router (#15707) has this shape: engine → `POST /v1/engine/ai-router` (30 s) → API enqueues `EXECUTE_AI {action: ROUTE}` and waits 25 s on pubsub → a worker calls OpenRouter. At `AP_WORKER_CONCURRENCY=1` on one replica, the decision-0001 destination, the flow job holds the only loop, the ROUTE job sits in the queue, the API times out, the step fails, and then the ROUTE job runs anyway, calls the model and **bills it**. At the default of 5, five flows at AI Routers deadlock each other for 25 s. Under fleet saturation on Cloud the same thing shows up as "step failed but the platform was charged". The AI piece steps do not have this problem because they pause the flow with a waitpoint and come back through `resumeAiStep`, releasing the slot. Rule: nothing inside the engine may block on a job in its own queue; pause and resume, or do the work in the API process. A job that answers a caller with a timeout should also carry that deadline and skip the paid call when it is already past. Fixed the same day: the router now pauses like the AI pieces (a waitpoint plus `resumeAiStep`), reuses its stored decision when a later step in the route pauses, and only a single-action run, which cannot pause, still waits synchronously.
+
### Key files
Entry point: `worker`, the exported lifecycle object in `worker.ts`; `worker.start(...)` is wired up in the worker process main.
diff --git a/brain/knowledge/flows-execution/flow-runs.md b/brain/knowledge/flows-execution/flow-runs.md
index 9659c1c166b..fa8898fe14c 100644
--- a/brain/knowledge/flows-execution/flow-runs.md
+++ b/brain/knowledge/flows-execution/flow-runs.md
@@ -61,6 +61,7 @@ A Flow Run records one execution of a specific flow version, from trigger to ter
- **A cancelled run's terminal status is only *queued*, so `flow_run.status` still reads `PAUSED` for a moment — read the Redis intent, not the row.** `cancelSingleRun` holds `runs_metadata_${id}`, removes the jobs and deletes every waitpoint, then hands `CANCELED` to `runsMetadataQueue` rather than writing it. For that window a resume request sees a `PAUSED` run with no waitpoint and cannot tell it from a legacy pre-waitpoint pause, and nothing downstream stops it — `execute-flow.ts` has no terminal-status guard, so the resume actually runs and overwrites the cancellation. The intent *is* observable: `runsMetadataQueue.add` writes the pending status into the `runs_metadata:<runId>` hash synchronously, inside that same lock, before enqueuing, and the metadata worker clears the key with `deleteKeyIfFieldValueMatches` once it lands. So `resumeService` refuses when `hgetJson(redisMetadataKey(id))` already holds a terminal status, and every resume path — the legacy by-run ones included — takes `runs_metadata_${id}` so the two orderings are both safe: cancel-first makes the resume wait and then see it, resume-first lets cancel's `removeAllFlowRunJobs` reap the job it just enqueued. The lock alone is not enough, and neither is re-reading `flow_run` inside it.
- **The `RESUME_DELAY_WAITPOINT` job id is keyed per waitpoint, and it has to stay that way.** `waitpointService.createForPause` schedules it as `resumeDelayJobId(waitpoint.id)` — never per run — because `systemJobsSchedule.upsertJob` only adds when that id is free (`if (isNil(existingJob))`), so a run-keyed id means the first waitpoint to arm owns the run's **only** timer and every later one silently gets none. Since decision 000015 one run legitimately holds several waitpoints, so that is a hang, not an edge case: `create_approval_links` (WEBHOOK, +30d) followed by `delayFor 45s` (DELAY) left the delay with no timer and the run sat `PAUSED` until the 30-day webhook expiry marked it FAILED. Two `WEBHOOK` rows hide it — identical `AP_PAUSED_FLOW_TIMEOUT_DAYS` deadlines, and each is resumed by its own callback anyway — which is why flow 4 of `/test-waitpoints` never caught it and flow 9 was added. Found and fixed 2026-09-10; the bug had been live on `main`, not introduced by the barrier work. Per-waitpoint keying also fixes the `removeOnFail: { age: ONE_MONTH }` case, where `upsertJob` retries a month-old failed job and would otherwise replay it against a **different** waitpoint's id. Pinned by "should give each waitpoint of one run its own resume job id" in `waitpoint.test.ts`.
- **Post-run metering window**: AI usage is metered only at `onFinish`, so a long run can spend past the credit limit before anything lands; interim by design — see decision 000016.
+- **A step that arms a waitpoint and then asks the API to fill it can leave the row behind if that second call fails, and the leftover is safe only while the run stays out of PAUSED.** Both the AI pieces (`createWaitpoint` then `POST /v1/ai/execute`) and the AI Router (`waitpointClient.create` then `POST /v1/engine/ai-router`) create the row first, because the request has to carry the waitpoint id. A failed second call fails the step and the run, but the PENDING row and its `RESUME_DELAY_WAITPOINT` timer survive; nothing on the failure path deletes them, only `cancel` does (`cancelSingleRun` calls `deleteByFlowRunId`). `handleResumeDelayWaitpoint` skips a timer whose run is not PAUSED or whose row is not PENDING, so a failed run is never touched. The one corner: a retry of that run within the deadline (10 min for the router) that pauses somewhere else is PAUSED when the stale WEBHOOK timer fires, and `isWebhookExpiry` marks it FAILED. Reviewed on #15707 and left as is; the fix, if it ever bites, is a delete of the row on the failure path or a retry that clears pending waitpoints.
### Editions
CE has full run tracking. Cloud may enforce retention windows; bulk-retry admin endpoint is Cloud-only.
diff --git a/brain/knowledge/flows-execution/flows.md b/brain/knowledge/flows-execution/flows.md
index cb6dbc914e6..15668fb6638 100644
--- a/brain/knowledge/flows-execution/flows.md
+++ b/brain/knowledge/flows-execution/flows.md
@@ -44,6 +44,26 @@ Flows are the core automation primitive: a versioned directed graph of trigger +
- **Any query that reads `flow_version.trigger` across a whole platform is TOAST-bound, not index-bound.** Trigger blobs are jsonb and TOAST'd on rows past ~2 KB, so a report that walks piece steps across all published flows on a platform pays ~2–5 ms of TOAST fetch + JSON parse per flow no matter how tight the WHERE clause is — a 10k-published-flow platform lands at 30 s–1 min. Endpoints of this shape (`platform/pieces-report/pieces-report.controller.ts` is the current example) must page + stream (`Readable.from(async iterable)`) so memory is bounded even when wall clock isn't; the escape hatch for the biggest platforms is a background job with async delivery, unlocked when a real sync request times out. Postgres jsonpath in-DB is not a shortcut — it still reads the whole TOASTed blob and the branch schema (`nextAction`/`children.*`/`onSuccessAction`/`firstLoopAction`/router children) drifts every time the flow shape changes, which is what `flowStructureUtil.getAllSteps` is authoritative over.
- **`transferFlow` already deep-clones the whole flow — a callback that clones `step` again is quadratic.** `flowStructureUtil.transferFlow` opens with `JSON.parse(JSON.stringify(flowVersion))`, so the callback is handed a private copy and can mutate in place. Cloning per step instead is O(N²), because a `step` carries `nextAction` (the entire rest of the chain) plus loop/router children: cloning step *i* copies the remaining `N-i` steps. Measured on prod app containers (CDP CPU profile, 2026-08-21): the callback at `flow-version.service.ts` was **42% of wall-clock / ~84% of non-idle CPU**, at `transferStep` recursion depth 255 ≈ 32k step serializations per call, plus the GC churn behind ~2.5 GB RSS. It ran on **every** `getFlowVersionOrThrow` — including the default `removeConnectionsName=false, removeSampleData=false`, where the callback does nothing but the cloning still happens. Symptom was containers pegged at their `cpus: 1` cap and the 5s healthcheck `curl` timing out, which reads as "app unhealthy" with nothing crashed (the leftover zombie `curl`s are those killed healthchecks). Same pattern at `ee/…/project-state/diff/flow-diff.service.ts` (colder path, untouched here). When you write a `transferFlow` callback, mutate and return `step` — don't re-clone it.
+- **`StepSettings` is an untagged union, so a new settings field named like an existing one changes what every *other* step narrows to.** It unions `CodeActionSettings | PieceActionSettings | PieceTriggerSettings | RouterActionSettings | LoopOnItemsActionSettings` (`flows/triggers/trigger.ts`), and `getDefaultStepValues` in `packages/web/src/features/pieces/utils/piece-selector-utils.ts` relies on `settings: overrideDefaultSettings ?? { … }` collapsing to the right member inside each `case`. Adding a member whose `input` is a **string** — every other member's `input` is a props record — widened `StepSettings['input']` to `string | Record<…>` and produced six type errors in code nobody had touched, including the existing **Router's** own default-step seed and `getInitalStepInput`. The lesson is not "avoid the union": it is that a settings field name is shared vocabulary, so reuse a name only when the type matches, and otherwise pick a different one (the AI router's became `text`). When a `case` still will not narrow, discriminate on a field only that member has — `'executionType' in settings` for the Router, `'question' in settings` for the AI router — rather than casting, which the repo bans anyway. Nothing in lint catches this; it surfaces only as `npm run typecheck` in `packages/web`, which CI runs but no per-package build does.
+
+- **Branch names are not unique and nothing enforces it, which is fine for the Router and a correctness bug for anything keyed on the name.** `DUPLICATE_BRANCH` deliberately produces `"Billing Copy"`, and no layer — zod, the validator, the builder — rejects two branches with the same name. The Router does not care, because its branches are independent condition trees. The AI router uses the branch name as the model's option key, so two branches named `Billing` collapse to one key in `Object.fromEntries` (wins-last) and then `branches.map((b) => b.branchName === chosen)` returns `true` for **both**, executing two branches from a single-choice answer. `AiRouterActionSettingsWithValidation` rejects duplicates and `ai-router-executor.ts` de-dupes defensively, because a flow imported from JSON never passes through the builder's validation. Any future feature that treats a branch name as an identifier needs the same pair. The same key doubles as a plain-object property, so a route named `constructor` or `toString` read an inherited value and was skipped by an `isNil(options[name])` guard (Greptile P1 on #15707); `Object.hasOwn` is the check, and a `__proto__` route is still lost silently on assignment and through JSON, which nothing guards against.
+
+- **Adding a `FlowActionType` is ~31 source files, and twenty-one of them fail silently.** The compiler catches the unions in `flows/actions/action.ts` (zod `FlowAction`, the hand-written `FlowAction` TS union — both, because `z.infer` on the recursive type OOMs tsc — plus `SingleActionSchema` and `UpdateActionRequest`), `getExecutors()` in the engine, `buildCoreStepMetadata()` and `PrimitiveStepMetadata['type']` in web, and `system-validator.ts` if you add an env var. ESLint's `switch-exhaustiveness-check` catches `test-execution-context.ts`. What nothing catches: `flowStructureUtil.transferStep`'s child traversal (miss it and every migration, rename, duplicate and connection-extraction silently skips the new type's subtree), `flowStructureUtil.isStepAction`, both `getFlowBoundingBox` guards in **`core/execution`'s** `flow-canvas-util.ts` — which is *not* the canvas, and the trap that cost the most here: **`packages/web/src/app/builder/flow-canvas/` keeps its own ten `type === ROUTER` checks** and widening the shared util does nothing for them. The one that shows immediately is `buildFlowGraph`'s child-graph choice in `utils/flow-canvas-utils.ts`: with no matching arm the step renders as a lone node with no branches, no labels and no add buttons. Behind it sit the straight-line-edge suppression, three guards in `edges/branch-label.tsx`, the paste-as-branch-child entry in the context menu, and **two graph cache keys in `flow-canvas/index.tsx`** that fold `settings.branches` into the repaint key — miss those and renaming a branch does not repaint the canvas. `buildRouterChildGraph` itself needs no logic change, only a widened parameter type: it reads `children` and `branchName`, which every branched type has. `buildSchema` in web's `form-utils.tsx` (miss it and the settings form never validates, so the step saves as valid while empty), and `clean-flow-state.ts` for project releases. **And, the half that is easiest to miss, the six flow operations that manipulate branches** — `_addAction`'s parent `switch` (falls through to `default`, which throws `Router step parent INSIDE_BRANCH not found`, so adding a step inside a branch 400s), `_addBranch` / `_deleteBranch` / `_moveBranch` (plain `type !== ROUTER` guards that return the step untouched, so the builder's local `useFieldArray` insert drifts out of sync with the server and the next save sends `branches` and `children` of different lengths), `_deleteAction` and `_getImportOperations` / `removeAnySubsequentAction` in `import-flow.ts` (skip the subtree, dropping children on delete, copy, paste and project release). These are `if` guards and `switch` cases **with a `default`**, which is exactly what the type system cannot see. `_addBranch` and `_duplicateBranch` additionally need to build the branch *shape* from the parent's type rather than calling `flowStructureUtil.createBranch`, which always returns the Router shape. A purely additive type needs **no** flow migration — `LATEST_FLOW_SCHEMA_VERSION` stays put, because no persisted flow contains an instance of it; `migrate-v0-branch-to-router.ts` was a migration only because it *converted* the old `BRANCH` shape. Most of the 31 sites are one-line widenings if you add a shared guard (`flowStructureUtil.isBranchedAction` covers ROUTER + AI_ROUTER) rather than a second case everywhere. A twelfth silent site is the MCP flow-editing toolset in `packages/server/api/src/app/mcp/tools/`: `resolveRouterStep` in `mcp-utils.ts` filters on `FlowActionType.ROUTER`, so `ap_add_branch`/`ap_update_branch`/`ap_delete_branch` refuse the new type; `ap-flow-structure.ts` only maps `ROUTER` children to `relationship: 'branch'`, so the new type's branches read as flat `next` steps; `ap-validate-flow.ts` skips them in the empty-branch check; `ap-add-step.ts` has a closed `stepType` enum; and `ap-update-branch.ts` hard-codes `type: ROUTER` with `conditions`. The AI router reached review on #15707 with all five untouched, found by a reviewer, not by any test. The structural checks (`resolveRouterStep`, the structure tool's parent detection and rendering, the validator) were then widened to `flowStructureUtil.isBranchedAction`, and `ap_add_branch`/`ap_update_branch` now refuse an AI router with a message instead of writing `conditions` onto it; they still need a per-type body, as does `ap_add_step`.
+
+- **A step's `*ActionSettings` is a persisted schema, so adding a *required* field there makes every already-saved step of that type unsavable — and the builder loses the edit silently.** Adding `matchMode` to `AiRouterActionSettings` as required meant a step stored before that commit no longer satisfied the `AI_ROUTER` member of `UpdateActionRequest`; the union then failed every member and the flow endpoint answered `400 body/request Invalid input`. The builder saves from its form resolver on each keystroke and does not surface that rejection, so the value stayed on screen, never reached the flow version, and vanished on the next load — which reads as "my branch value is not being saved" rather than as a validation error. The Router never hit this because `executionType` was required from its first commit. So a new settings field is `.optional()`, with the absent case given a meaning at the one place that reads it (`matchMode ?? BEST_MATCH` in the executor, `?? BEST_MATCH` for the select's displayed value) — not required, and not backfilled by a flow migration, which `LATEST_FLOW_SCHEMA_VERSION` would otherwise force for a purely additive change. Worth pinning with a test that parses a payload *without* the new field through `UpdateActionRequest`, because nothing else catches it: the schema compiles, every fixture in the repo is written with the new field, and only a step saved by an older build reproduces it.
+
+- **The Router and AI router settings panels mirror every branch operation into react-hook-form by hand, and the `ADD_BRANCH` mirror was one off — silently editing the wrong branch.** `BranchesList` renders from `step.settings.branches` (the flow version) while the detail pane binds `settings.branches.${selectedBranchIndex}.description` (the form's `useFieldArray`), so the two arrays must stay index-for-index identical or a click selects one branch and types into another. `addButtonClicked` sends `branchIndex: branches.length - 1` computed from the **pre**-operation step, but the operation listener re-derived it from the **post**-operation step (`updatedStep.settings.branches.length - 1`), which is one larger. Starting from `[Route 1, Otherwise]`, the flow became `[Route 1, Route 2, Otherwise]` and the form became `[Route 1, Otherwise, Route 3]`; the resolver then saved the form array over the flow on the next keystroke, so the new route was replaced by the fallback and a phantom route appeared. The name drifted the same way (`Route 2` vs `Route 3`). Fix is to stop re-deriving: the operation already carries the `branchIndex` and `branchName` it used, so mirror `operation.request.*` and there is no arithmetic left to get wrong. `DUPLICATE_BRANCH` was always correct because it already read the request. This shipped in the Router long before the AI router copied it.
+
+- **Nothing typechecked `packages/web/test/` — a type error in a web test passed CI, lint and the test run alike.** `npm run typecheck` ran `tsconfig.app.json`, whose `include` is `src/**` only; `npm run lint` globs `src/**/*.{ts,tsx}`; and vitest transpiles without checking types. `tsconfig.spec.json` did cover `test/**` and was wired as a project reference, but no script or CI step ever invoked it, so it was reachable only from the editor — which is how this surfaced, as a red squiggle in someone's IDE on a branch whose CI was green. `web`'s `typecheck` script now runs both projects. Worth knowing before copying the pattern: the equivalent `tsconfig.spec.json` in **`server/engine` and `server/api` are stale** — they set `"module": "commonjs"` against an ESM/vitest setup, so they report ~37 and several errors on untouched files (every builder in `test-helper.ts`, every top-level `await import`). Those are pre-existing and wiring them up is a real cleanup, not a one-line change; web's was clean, which is the only reason enabling it there was safe.
+
+- **The AI router's two match modes ask the model completely different questions, and only one of them sends the fallback.** `BEST_MATCH` posts one `choice` question whose `criteria` map includes the Otherwise route, and the guarantee is that the answer is one of the keys. `ALL_MATCHES` posts one `noul` question **per non-fallback route** — all in a single request, because Jev's `questions` field is a record, not a single question — and computes the fallback locally with the Router's own rule (true iff nothing else matched). So the measured finding that an explicit `Otherwise` criterion is what stops `"hi"` routing to Sales at 0.87 is a `BEST_MATCH` property only; under `ALL_MATCHES` every noul can independently answer no, so there is nothing to decline from and the fallback description is unused. Anyone "simplifying" the two paths into one will either start paying per route in best-match mode or silently drop the escape hatch in all-matches mode. A yes/no answer on OpenRouter's Decisions API is `{ type: 'noul', noul }` where `noul` is P(true) — there is no `answer` and no `probability` field — so "applies" is `noul >= 0.5` and `probabilities` is P(true) as-is; it means the same thing in both modes, and the run detail's bar chart needs no mode awareness. Two earlier cuts each guessed the field (`answer.answer`, then Vercel's `probability`) and each failed only at runtime as a bare 400 from our own API, because `ENGINE_OPERATION_FAILURE` is not in `error-handler.ts`'s status map. The wire format now lives in one worker file (`packages/server/worker/src/lib/execute/jobs/ai/route.ts`) with a unit test per answer shape, the engine client appends the API error's `params.message`, and the source of truth is OpenRouter's Jev tutorial, not an SDK's mirror of it.
+
+- **The AI router's confidence floor reroutes to Otherwise without changing the probabilities, so a run can show Route 1 at 63% and Otherwise as the pick.** `confidentRoutes` in `ai-router-executor.ts` drops the model's answer when its probability is under `minConfidence`, and `bestMatchEvaluations` then takes the fallback; the `probabilities` in the step output are the model's raw answer and are left alone. Measured Sep 2026 with a 90% floor: a two-topic message ("charged twice" plus a 404) scored billing 0.63, technical 0.33, otherwise 0.04 and ran Otherwise, which read as a wrong pick until the floor was checked. The run view's bar chart now appends "Route 1 scored 63%, under your 90% floor, so Otherwise ran" (`floorExplanation` in `ai-router-routes.tsx`), reading the floor from the step's `input` — which is why both render sites pass `input` as well as `output`. The sentence is best-match only: in all-matches mode a route answered *no* shows `1 - p`, so the top bar there is not the floor's doing. A two-topic input is also the case all-matches mode exists for; best-match forces one winner on a message that has two. **In all-matches mode the floor is the only threshold once it is set.** The worker's `readNouls` marks a route as applying at `noul >= 0.5`, which is the default with no floor; with a floor the engine recomputes `matched` from `probabilities` against `minConfidence`, so a floor under 50% keeps routes the worker left out instead of silently doing nothing (Amr's review on #15707). The builder offers 50, 70 and 90 only, so the low-floor case is API-only, but the schema accepts 0..1.
+
+- **A Router branch's `conditions` is OR-of-ANDs, and the nesting reads backwards from how most people guess.** `evaluateConditions` is `conditionGroups.some((group) => group.every((condition) => …))` (`router-executor.ts`), so the **outer** array is OR and the **inner** array is AND: `[[a, b], [c]]` means `(a AND b) OR c`. The builder calls the outer entries groups and the inner ones rows, which is the same orientation but never says OR/AND in those words. Get it inverted and the branch still compiles, still runs, and quietly takes the wrong path. An unknown operator returns `true` (it does not throw), while a *missing* operator throws `OperatorNotSetError` — so a condition referencing an operator this engine version does not know matches everything rather than nothing. The AI router has none of this: it has no conditions, no operators and no `executionType`, because a `choice` answer names exactly one branch.
+
+- **An engine API client that throws `EngineGenericError` makes its executor's own `failStep` branch unreachable.** `utils.tryCatchAndThrowOnEngineError` returns USER-level `ExecutionError`s to the caller but **rethrows** ENGINE-level ones, so `const { error } = await tryCatchAndThrowOnEngineError(() => api.call())` followed by `if (error) return failStep(...)` is dead code for an ENGINE error: the run ends as `INTERNAL_ERROR`, which fails the worker job and pages oncall. `packages/server/engine/CLAUDE.md` says to use `EngineGenericError` for "failed API calls to the server", and that is right for the engine's own plumbing (progress, file store) and wrong for anything proxying a third party — OpenRouter returning 500 to the AI router is not our bug, and the docs promise a retryable FAILED step. Classify by whose fault it is, not by which layer threw. The AI router's client now throws a USER-level `AiRouterEvaluationError`. Nothing in lint or tsc catches this; only an executor test that asserts `steps.<name>.status === FAILED` does, which is how it was found.
+
### Editions
CE has full authoring/publishing/folders/forms. EE/Cloud add owner transfer, piece filtering, template sharing, and active-flow quota enforcement on publish/enable.
diff --git a/brain/knowledge/pieces-engine/pieces.md b/brain/knowledge/pieces-engine/pieces.md
index 711184ffecb..14099a98941 100644
--- a/brain/knowledge/pieces-engine/pieces.md
+++ b/brain/knowledge/pieces-engine/pieces.md
@@ -57,6 +57,7 @@ The metadata catalog of automation integrations ("pieces") — each a named inte
- **`piece-upgrade-register.json` has two consumers, not one.** The upgrade/downgrade dialog is the obvious one; the other is `migrate-v23`, which sits in the flow migration chain — so the register rewrites `pieceVersion` on every flow-version read, not only when someone clicks something. That makes regenerating it a live change to running flows. It also means a migration that pins a version can be undone by a later one in the same `apply()` pass: `migrate-v22` hands off at schemaVersion 23 and `migrate-v23`'s `targetSchemaVersion` is 23, so both run in one pass. Harmless only because the register's highest AI entry is `0.4.4` — add entries and v23 starts upgrading what v22 just pinned. **Pin versions in a migration of your own, appended last; leave the register alone.**
- **`ctx.files.write()` returns a URL served as `application/octet-stream`, so a vendor that sniffs Content-Type will reject it.** The signed read URL (`v1/files/{id}?token=`) carries no file extension, and on S3/R2 storage it 307-redirects to presigned storage where the real filename rides only on `response-content-disposition`. WhatsScale's `/make/prepareFile` refuses it outright — `"URL did not return an image, video, document, or audio file. Got content-type: application/octet-stream" (400)` — unless an explicit `mediaType` is passed alongside the URL. Any piece that hands an AP-hosted file URL to a third party has to tell that API the media type out-of-band; do not assume the URL is self-describing. Verified live 2026-08-24 on the WhatsScale piece: identical URL, 400 without `mediaType`, delivered correctly with it.
+- **On Cloud edition the catalog lives in the database and only the sync fills it, so `ap-dev up cloud --fresh` with `AP_PIECES_SYNC_MODE=NONE` boots with two pieces and no error.** `pieceSyncService` (`piece-sync-service.ts`) pulls the official catalog from cloud.activepieces.com at startup and hourly, but returns early with `Piece sync service is disabled` when the mode is anything but `OFFICIAL_AUTO`, the default. A stale `NONE` left in `.env.dev` from a CE session survives the wipe because the dev script only rewrites its own keys, and `AP_DEV_PIECES` is ignored on cloud, so the picker is simply empty. Confirm with `GET /api/v1/flags` (`PIECES_SYNC_MODE`) and `SELECT count(*) FROM piece_metadata`, then `ap-dev up cloud AP_PIECES_SYNC_MODE=OFFICIAL_AUTO` without `--fresh`. Seen 2026-09-23 while testing the AI Router on a fresh cloud dev instance.
### Key files
Entry point: `pieceModule`, the Fastify plugin registered in `packages/server/api/src/app/app.ts` that mounts every `/v1/pieces` route.
diff --git a/bun.lock b/bun.lock
index 108f12b7bf7..38acaabdf07 100644
--- a/bun.lock
+++ b/bun.lock
@@ -120,7 +120,7 @@
},
"packages/core/execution": {
"name": "@activepieces/core-execution",
- "version": "0.22.0",
+ "version": "0.23.0",
"dependencies": {
"@activepieces/core-piece-types": "workspace:*",
"@activepieces/core-utils": "workspace:*",
@@ -165,7 +165,7 @@
},
"packages/core/shared": {
"name": "@activepieces/shared",
- "version": "0.179.0",
+ "version": "0.180.0",
"dependencies": {
"@activepieces/core-execution": "workspace:*",
"@activepieces/core-formula": "workspace:*",
@@ -188,7 +188,7 @@
},
"packages/core/utils": {
"name": "@activepieces/core-utils",
- "version": "0.8.0",
+ "version": "0.8.1",
"dependencies": {
"deepmerge-ts": "8.0.2",
"ipaddr.js": "2.3.0",
diff --git a/docs/docs.json b/docs/docs.json
index 783eb4d19a4..966942f03ce 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -119,6 +119,7 @@
"group": "Flows",
"pages": [
"flows/building-flows",
+ "flows/ai-router",
"flows/passing-data",
"flows/using-formulas",
"flows/formula-reference",
diff --git a/docs/flows/ai-router.mdx b/docs/flows/ai-router.mdx
new file mode 100644
index 00000000000..caeda0fa618
--- /dev/null
+++ b/docs/flows/ai-router.mdx
@@ -0,0 +1,171 @@
+---
+title: "AI Router"
+description: "Ask one question and Jev, an evaluation model, picks the route"
+icon: "shuffle"
+---
+
+A normal [Router](/flows/building-flows) asks you to write a condition for every branch. The AI
+Router inverts that: you write **one question**, and each branch is **one possible answer**.
+
+```
+Input {{trigger.body.message}}
+Question Which team should handle this?
+
+Routes
+ Billing Payments, invoices, refunds
+ Technical Bugs, errors, something not working
+ Sales Pricing questions, upgrades
+ Otherwise Anything that fits none of the routes above
+```
+
+One request decides. Jev, an evaluation model built to judge text rather than generate it, makes
+the call. By default exactly one route runs; switch **Match** to run every route that applies.
+
+## Which router do you want?
+
+The AI Router reads. The normal [Router](/flows/building-flows) compares. Reach for the AI Router
+the moment you catch yourself typing a fifth `OR contains "…"`.
+
+**Use the normal Router for** exact field values, numbers and dates, comparing two dynamic values
+against each other (`{{step.total}} > {{step.limit}}`), "does this field exist", anything inside a
+big loop, and anything that has to be auditable or reproducible — compliance gates, billing tiers,
+approval thresholds. It is free, instant and gives the same answer forever.
+
+**Use the AI Router for** anything a human typed. Intent, topic, sentiment, urgency, "is this worth
+a call". It routes `"i got billed 2x lol wtf"` and `"Mi tarjeta fue cobrada dos veces"` to Billing
+without you listing a single keyword in either language.
+
+**Most real flows use both.** Let the AI Router take the judgement and put a normal Router inside
+the branch for the facts:
+
+```
+AI Router — "Which team should handle this?"
+├── Billing ──▶ Router — "Over $500?" ──▶ approval / auto-refund
+├── Technical ─▶ create an issue
+└── Otherwise ─▶ human review
+```
+
+Never ask the model whether 500 is bigger than 499.
+
+## Fields
+
+| Field | What it does |
+|---|---|
+| **Input** | The text the model reads. Reference a previous step, e.g. `{{trigger.body.message}}`. Only the first 20,000 characters are sent. |
+| **Question** | One question. With the default match, exactly one route answers it. |
+| **Routes** | Each route's **name** is a possible answer; its **description** tells the model when to pick it. |
+| **Otherwise** | Always present, always last. Edit its description like any other route. |
+| **Match** | Take the best route, or every route that applies. |
+| **Confidence floor** | Optional. Below it, the flow takes the Otherwise route, and the run detail says so. |
+
+## One route, or every route that applies
+
+**Match** decides how many routes run.
+
+**The best route** (the default) asks one question and exactly one route runs. Use it when the routes
+are alternatives — a ticket goes to one team.
+
+**Every route that applies** runs each route that fits, and the Otherwise route only when none did.
+Use it when the routes are independent — one message can be *both* a billing question *and* an
+angry customer.
+
+```
+Input {{trigger.body}}
+Question What does this message need?
+Match Every route that applies
+
+Routes
+ Refund Wants money back
+ Escalate Angry, threatening to churn, or asking for a manager
+ Log feedback Mentions a feature or a complaint about the product
+ Otherwise Nothing above applies
+```
+
+`"I want a refund and honestly I'm done with you"` runs **Refund** and **Escalate**, and skips the
+other two.
+
+Two things to know before you switch:
+
+- It **asks the model once per route**, so a 6-route step is 6 questions instead of 1. They go in one
+ request. On the built-in Activepieces key you pay the real cost of those extra questions, still a
+ fraction of a credit; on your own OpenRouter key it is one credit either way.
+- It does **not** send Otherwise to the model. There is no forced choice to decline from — every
+ route can simply answer no — so Otherwise is decided here rather than by the model, and its
+ description is unused in this mode.
+
+A confidence floor works per route here: a route the model affirmed at 60% is dropped by a 70%
+floor, and if the floor rejects every route, Otherwise runs.
+
+## Write route descriptions, not prompts
+
+The description is the whole instruction the model gets for that route. Short and concrete beats
+long and careful:
+
+<CodeGroup>
+```text Good
+Billing Payments, invoices, refunds, double charges
+Technical Bugs, errors, something not working
+```
+
+```text Worse
+Billing If the customer seems to be talking about anything financial in nature,
+ including but not limited to payments, you should probably pick this one
+```
+</CodeGroup>
+
+## Otherwise is a real route (best-route mode)
+
+Give it a description. It is sent to the model as a genuine option, not used as a leftover bucket,
+and that is what lets the router decline rather than guess.
+
+The difference is large. With `Billing / Technical / Sales` and no Otherwise description, the input
+`"hi"` is routed to **Sales** — confidently, and past any threshold you would have set. Add
+*"Anything that fits none of the routes above"* and `"hi"` goes to **Otherwise** instead, while a
+clear billing message still goes to Billing.
+
+## Reading a run
+
+In a published flow the step pauses the run while the decision is made, usually a second or two, so
+you may see it as Paused before it turns green. Test runs from the builder wait for the answer
+instead.
+
+The run detail shows how sure the model was across every route, not just the one it picked:
+
+```
+Billing ████████████░░ 91%
+Technical █░░░░░░░░░░░░░ 6%
+Sales ░░░░░░░░░░░░░░ 3%
+```
+
+The route that ran is marked. A route picked at 91% and one picked at 34% look identical in a
+normal run log. Use the spread to tell a routing rule you can trust from one you cannot, and tighten
+the descriptions that come out close.
+
+When a confidence floor sends the run to Otherwise, the run detail says which route fell short:
+
+```
+Billing ████████░░░░░░ 63%
+Technical ████░░░░░░░░░░ 33%
+Otherwise █░░░░░░░░░░░░░ 4%
+
+Billing scored 63%, under your 70% floor, so Otherwise ran
+```
+
+## When a call fails
+
+The step **fails**. It does not quietly take the Otherwise route, because sending a refund down the
+wrong branch because a model timed out is a bug that looks like normal operation. A failed step is
+visible in the run and can be retried.
+
+When the platform is out of AI credits, the step fails the same way, with an error that says so, and
+nothing is charged. If no answer arrives within ten minutes, the step fails too.
+
+## Self-hosting
+
+The AI Router runs on the platform's OpenRouter key, the same way every AI step does, and reaches Jev
+through OpenRouter's Decisions API. On Cloud, and on Enterprise instances with billing, that is the
+built-in Activepieces provider, and each decision is billed at the cost OpenRouter reports, about
+0.03 credit. With your own OpenRouter key, added under **AI providers** in the platform admin, each
+decision costs one AI credit, and nothing on Community Edition, which has no credits. The step
+appears in the step list as soon as the project can reach one of those keys, and is hidden otherwise.
+There is nothing to configure on the step itself.
diff --git a/packages/core/execution/package.json b/packages/core/execution/package.json
index 36b79910954..e52c52d0547 100644
--- a/packages/core/execution/package.json
+++ b/packages/core/execution/package.json
@@ -1,6 +1,6 @@
{
"name": "@activepieces/core-execution",
- "version": "0.22.0",
+ "version": "0.23.0",
"type": "commonjs",
"main": "./dist/src/index.js",
"scripts": {
diff --git a/packages/core/execution/src/lib/engine/execution-errors.ts b/packages/core/execution/src/lib/engine/execution-errors.ts
index 7f6a3d20d99..b9dd400a457 100644
--- a/packages/core/execution/src/lib/engine/execution-errors.ts
+++ b/packages/core/execution/src/lib/engine/execution-errors.ts
@@ -151,4 +151,9 @@ export class SSRFBlockedError extends ExecutionError {
cause,
)
}
-}
\ No newline at end of file
+}
+export class AiRouterEvaluationError extends ExecutionError {
+ constructor({ message, cause }: { message: string, cause?: unknown }) {
+ super('AiRouterEvaluationError', formatMessage(message), ExecutionErrorType.USER, cause)
+ }
+}
diff --git a/packages/core/execution/src/lib/engine/requests.ts b/packages/core/execution/src/lib/engine/requests.ts
index 7fb8f5a8187..be83287ec6c 100644
--- a/packages/core/execution/src/lib/engine/requests.ts
+++ b/packages/core/execution/src/lib/engine/requests.ts
@@ -3,6 +3,7 @@ import { RunInternalError } from '../flow-run/execution/execution-output'
import { FlowRunStatus } from '../flow-run/execution/flow-execution'
import { StepOutput } from '../flow-run/execution/step-output'
import { FailedStep, FlowRun } from '../flow-run/flow-run'
+import { AiRouterMatchMode } from '../flows/actions/action'
import { StepRunResponse } from '../flows/sample-data'
import { StreamStepProgress } from './engine-operation'
@@ -81,3 +82,30 @@ export type UpdateRunProgressRequest = {
output: StepOutput
}
}
+
+export const AI_ROUTER_MAX_STATE_LENGTH = 20_000
+
+export const ChooseAiRouteRequest = z.object({
+ state: z.string().max(AI_ROUTER_MAX_STATE_LENGTH),
+ question: z.string(),
+ options: z.record(z.string(), z.string()),
+ matchMode: z.enum(AiRouterMatchMode),
+ flowId: z.string(),
+ flowRunId: z.string(),
+ waitpointId: z.string().optional(),
+})
+
+export type ChooseAiRouteRequest = z.infer<typeof ChooseAiRouteRequest>
+
+export const StartAiRouteResponse = z.object({
+ requestId: z.string(),
+})
+
+export type StartAiRouteResponse = z.infer<typeof StartAiRouteResponse>
+
+export const ChooseAiRouteResponse = z.object({
+ matched: z.array(z.string()),
+ probabilities: z.record(z.string(), z.number()).optional(),
+})
+
+export type ChooseAiRouteResponse = z.infer<typeof ChooseAiRouteResponse>
diff --git a/packages/core/execution/src/lib/flow-run/execution/step-output.ts b/packages/core/execution/src/lib/flow-run/execution/step-output.ts
index 0f3fb349920..73a61badb82 100644
--- a/packages/core/execution/src/lib/flow-run/execution/step-output.ts
+++ b/packages/core/execution/src/lib/flow-run/execution/step-output.ts
@@ -109,8 +109,9 @@ export type BaseStepOutput = GenericStepOutput<FlowActionType | FlowTriggerType,
export type StepOutput =
| GenericStepOutput<FlowActionType.LOOP_ON_ITEMS, LoopStepResult>
| GenericStepOutput<FlowActionType.ROUTER, unknown>
+ | GenericStepOutput<FlowActionType.AI_ROUTER, AiRouterStepResult>
| GenericStepOutput<
- | Exclude<FlowActionType, FlowActionType.LOOP_ON_ITEMS | FlowActionType.ROUTER>
+ | Exclude<FlowActionType, FlowActionType.LOOP_ON_ITEMS | FlowActionType.ROUTER | FlowActionType.AI_ROUTER>
| FlowTriggerType,
unknown
>
@@ -138,6 +139,25 @@ RouterStepResult
}
}
+type AiRouterStepResult = {
+ branches: BranchResult[]
+ choice?: string
+ probabilities?: Record<string, number>
+}
+
+export class AiRouterStepOutput extends GenericStepOutput<
+FlowActionType.AI_ROUTER,
+AiRouterStepResult
+> {
+ static init({ input }: { input: unknown }): AiRouterStepOutput {
+ return new AiRouterStepOutput({
+ type: FlowActionType.AI_ROUTER,
+ input,
+ status: StepOutputStatus.SUCCEEDED,
+ })
+ }
+}
+
export type LoopStepResult = {
item: unknown
index: number
diff --git a/packages/core/execution/src/lib/flows/actions/action.ts b/packages/core/execution/src/lib/flows/actions/action.ts
index d64ef08fee1..8d19d0a080b 100755
--- a/packages/core/execution/src/lib/flows/actions/action.ts
+++ b/packages/core/execution/src/lib/flows/actions/action.ts
@@ -1,5 +1,5 @@
import { z } from 'zod'
-import { STEP_NAME_REGEX } from '@activepieces/core-utils'
+import { formErrors, STEP_NAME_REGEX } from '@activepieces/core-utils'
import { VersionType } from '@activepieces/core-piece-types'
import { PropertySettings } from '../properties'
import { SampleDataSetting } from '../sample-data'
@@ -9,6 +9,7 @@ export enum FlowActionType {
PIECE = 'PIECE',
LOOP_ON_ITEMS = 'LOOP_ON_ITEMS',
ROUTER = 'ROUTER',
+ AI_ROUTER = 'AI_ROUTER',
}
export enum RouterExecutionType {
@@ -284,6 +285,59 @@ export const RouterActionSettingsWithValidation = z.object({
export type RouterActionSettings = z.infer<typeof RouterActionSettings>
+export enum AiRouterMatchMode {
+ BEST_MATCH = 'BEST_MATCH',
+ ALL_MATCHES = 'ALL_MATCHES',
+}
+
+export const AiRouterBranchesSchema = (addMinLength: boolean) =>
+ z.array(
+ z.union([
+ z.object({
+ branchType: z.literal(BranchExecutionType.CONDITION),
+ branchName: z.string(),
+ description: addMinLength ? z.string().min(1, formErrors.required) : z.string().optional(),
+ }),
+ z.object({
+ branchType: z.literal(BranchExecutionType.FALLBACK),
+ branchName: z.string(),
+ description: z.string().optional(),
+ }),
+ ]),
+ )
+
+export const AiRouterActionSettings = z.object({
+ ...commonActionSettings,
+ text: z.string(),
+ question: z.string(),
+ branches: AiRouterBranchesSchema(false),
+ matchMode: z.enum(AiRouterMatchMode).optional(),
+ minConfidence: z.number().min(0).max(1).optional(),
+})
+
+export const AiRouterActionSettingsWithValidation = z.object({
+ text: z.string().min(1, formErrors.required),
+ question: z.string().min(1, formErrors.required),
+ branches: AiRouterBranchesSchema(true),
+ matchMode: z.enum(AiRouterMatchMode).optional(),
+ minConfidence: z.number().min(0).max(1).optional(),
+}).superRefine((settings, ctx) => {
+ const seen = new Set<string>()
+ settings.branches.forEach((branch, index) => {
+ const name = branch.branchName.trim().toLowerCase()
+ if (seen.has(name)) {
+ ctx.addIssue({
+ code: 'custom',
+ message: formErrors.duplicateRouteName,
+ path: ['branches', index, 'branchName'],
+ })
+ }
+ seen.add(name)
+ })
+})
+
+export type AiRouterActionSettings = z.infer<typeof AiRouterActionSettings>
+
// Union of all actions
@@ -309,6 +363,13 @@ export const FlowAction: z.ZodType<FlowAction> = z.lazy(() =>
nextAction: FlowAction.optional(),
children: z.array(z.union([FlowAction, z.null()])),
}),
+ z.object({
+ ...commonActionProps,
+ type: z.literal(FlowActionType.AI_ROUTER),
+ settings: AiRouterActionSettings,
+ nextAction: FlowAction.optional(),
+ children: z.array(z.union([FlowAction, z.null()])),
+ }),
]),
)
@@ -323,11 +384,18 @@ export const RouterActionSchema = z.object({
settings: RouterActionSettings,
})
+export const AiRouterActionSchema = z.object({
+ ...commonActionProps,
+ type: z.literal(FlowActionType.AI_ROUTER),
+ settings: AiRouterActionSettings,
+})
+
export const SingleActionSchema = z.discriminatedUnion('type', [
CodeActionSchema,
PieceActionSchema,
LoopOnItemsActionSchema,
RouterActionSchema,
+ AiRouterActionSchema,
])
// Manually defined to avoid z.infer in recursive types (causes TypeScript OOM)
@@ -344,6 +412,7 @@ export type FlowAction =
| (BaseActionProps & { type: FlowActionType.PIECE, settings: PieceActionSettings, nextAction?: FlowAction, continueOnFailureBranches?: ContinueOnFailureBranches })
| (BaseActionProps & { type: FlowActionType.LOOP_ON_ITEMS, settings: LoopOnItemsActionSettings, nextAction?: FlowAction, firstLoopAction?: FlowAction })
| (BaseActionProps & { type: FlowActionType.ROUTER, settings: RouterActionSettings, nextAction?: FlowAction, children: (FlowAction | null)[] })
+ | (BaseActionProps & { type: FlowActionType.AI_ROUTER, settings: AiRouterActionSettings, nextAction?: FlowAction, children: (FlowAction | null)[] })
export type RouterAction = BaseActionProps & {
type: FlowActionType.ROUTER
@@ -352,6 +421,15 @@ export type RouterAction = BaseActionProps & {
children: (FlowAction | null)[]
}
+export type AiRouterAction = BaseActionProps & {
+ type: FlowActionType.AI_ROUTER
+ settings: AiRouterActionSettings
+ nextAction?: FlowAction
+ children: (FlowAction | null)[]
+}
+
+export type BranchedAction = RouterAction | AiRouterAction
+
export type LoopOnItemsAction = BaseActionProps & {
type: FlowActionType.LOOP_ON_ITEMS
settings: LoopOnItemsActionSettings
diff --git a/packages/core/execution/src/lib/flows/operations/add-action.ts b/packages/core/execution/src/lib/flows/operations/add-action.ts
index c4d098a0a32..a40c5c357fe 100644
--- a/packages/core/execution/src/lib/flows/operations/add-action.ts
+++ b/packages/core/execution/src/lib/flows/operations/add-action.ts
@@ -1,7 +1,7 @@
import dayjs from 'dayjs'
import { isNil } from '@activepieces/core-utils'
import { ActivepiecesError, ErrorCode } from '@activepieces/core-utils'
-import { FlowAction, FlowActionType, LoopOnItemsAction, RouterAction, SingleActionSchema } from '../actions/action'
+import { BranchedAction, FlowAction, FlowActionType, LoopOnItemsAction, SingleActionSchema } from '../actions/action'
import { FlowVersion } from '../flow-version'
import { flowStructureUtil, Step } from '../util/flow-structure-util'
import { AddActionRequest, StepLocationRelativeToParent, UpdateActionRequest } from './index'
@@ -35,6 +35,15 @@ function createAction(request: UpdateActionRequest, {
children: request.settings.branches.map(() => null),
}
+ break
+ case FlowActionType.AI_ROUTER:
+ action = {
+ ...baseProperties,
+ type: FlowActionType.AI_ROUTER,
+ settings: request.settings,
+ children: request.settings.branches.map(() => null),
+ }
+
break
case FlowActionType.LOOP_ON_ITEMS:
action = {
@@ -89,7 +98,7 @@ function handleLoopOnItems(parentStep: LoopOnItemsAction, request: AddActionRequ
return parentStep
}
-function handleRouter(parentStep: RouterAction, request: AddActionRequest): Step {
+function handleRouter(parentStep: BranchedAction, request: AddActionRequest): Step {
if (request.stepLocationRelativeToParent === StepLocationRelativeToParent.INSIDE_BRANCH && !isNil(request.branchIndex)) {
parentStep.children[request.branchIndex] = createAction(request.action, {
nextAction: parentStep.children[request.branchIndex] ?? undefined,
@@ -150,6 +159,7 @@ function _addAction(flowVersion: FlowVersion, request: AddActionRequest): FlowVe
case FlowActionType.LOOP_ON_ITEMS:
return handleLoopOnItems(parentStep, request)
case FlowActionType.ROUTER:
+ case FlowActionType.AI_ROUTER:
return handleRouter(parentStep, request)
default: {
parentStep.nextAction = createAction(request.action, {
diff --git a/packages/core/execution/src/lib/flows/operations/add-branch.ts b/packages/core/execution/src/lib/flows/operations/add-branch.ts
index fc3a6be93b2..8a441de28ae 100644
--- a/packages/core/execution/src/lib/flows/operations/add-branch.ts
+++ b/packages/core/execution/src/lib/flows/operations/add-branch.ts
@@ -1,5 +1,5 @@
import { insertAt } from '@activepieces/core-utils'
-import { FlowActionType, RouterAction } from '../actions/action'
+import { BranchExecutionType, FlowActionType } from '../actions/action'
import { FlowVersion } from '../flow-version'
import { flowStructureUtil } from '../util/flow-structure-util'
import { AddBranchRequest } from '.'
@@ -7,20 +7,33 @@ import { AddBranchRequest } from '.'
function _addBranch(flowVersion: FlowVersion, request: AddBranchRequest): FlowVersion {
return flowStructureUtil.transferFlow(flowVersion, (parentStep) => {
- if (parentStep.name !== request.stepName || parentStep.type !== FlowActionType.ROUTER) {
+ if (parentStep.name !== request.stepName || !flowStructureUtil.isBranchedAction(parentStep)) {
return parentStep
}
- const routerAction = parentStep as RouterAction
+ const children = insertAt(parentStep.children, request.branchIndex, null)
+ if (parentStep.type === FlowActionType.AI_ROUTER) {
+ return {
+ ...parentStep,
+ settings: {
+ ...parentStep.settings,
+ branches: insertAt(parentStep.settings.branches, request.branchIndex, {
+ branchType: BranchExecutionType.CONDITION as const,
+ branchName: request.branchName,
+ description: request.description ?? '',
+ }),
+ },
+ children,
+ }
+ }
return {
- ...routerAction,
+ ...parentStep,
settings: {
- ...routerAction.settings,
- branches: insertAt(routerAction.settings.branches, request.branchIndex, flowStructureUtil.createBranch(request.branchName, request.conditions)),
+ ...parentStep.settings,
+ branches: insertAt(parentStep.settings.branches, request.branchIndex, flowStructureUtil.createBranch(request.branchName, request.conditions)),
},
- children: insertAt(routerAction.children, request.branchIndex, null),
+ children,
}
})
}
-
-export { _addBranch }
\ No newline at end of file
+export { _addBranch }
diff --git a/packages/core/execution/src/lib/flows/operations/delete-action.ts b/packages/core/execution/src/lib/flows/operations/delete-action.ts
index c9c5e48adbb..94498e761e8 100644
--- a/packages/core/execution/src/lib/flows/operations/delete-action.ts
+++ b/packages/core/execution/src/lib/flows/operations/delete-action.ts
@@ -25,7 +25,8 @@ function _deleteAction(
}
break
}
- case FlowActionType.ROUTER: {
+ case FlowActionType.ROUTER:
+ case FlowActionType.AI_ROUTER: {
parentStep.children = parentStep.children.map((child) => {
if (child && child.name === name) {
return child.nextAction ?? null
diff --git a/packages/core/execution/src/lib/flows/operations/delete-branch.ts b/packages/core/execution/src/lib/flows/operations/delete-branch.ts
index ddc8665e974..1a40ae24639 100644
--- a/packages/core/execution/src/lib/flows/operations/delete-branch.ts
+++ b/packages/core/execution/src/lib/flows/operations/delete-branch.ts
@@ -1,23 +1,28 @@
-import { FlowActionType, RouterAction } from '../actions/action'
+import { FlowActionType } from '../actions/action'
import { FlowVersion } from '../flow-version'
import { flowStructureUtil } from '../util/flow-structure-util'
import { DeleteBranchRequest } from '.'
function _deleteBranch(flowVersion: FlowVersion, request: DeleteBranchRequest): FlowVersion {
return flowStructureUtil.transferFlow(flowVersion, (parentStep) => {
- if (parentStep.name !== request.stepName || parentStep.type !== FlowActionType.ROUTER) {
+ if (parentStep.name !== request.stepName || !flowStructureUtil.isBranchedAction(parentStep)) {
return parentStep
}
- const routerAction = parentStep as RouterAction
+ const keep = (_: unknown, index: number) => index !== request.branchIndex
+ const children = parentStep.children.filter(keep)
+ if (parentStep.type === FlowActionType.AI_ROUTER) {
+ return {
+ ...parentStep,
+ settings: { ...parentStep.settings, branches: parentStep.settings.branches.filter(keep) },
+ children,
+ }
+ }
return {
- ...routerAction,
- settings: {
- ...routerAction.settings,
- branches: routerAction.settings.branches.filter((_, index) => index !== request.branchIndex),
- },
- children: routerAction.children.filter((_, index) => index !== request.branchIndex),
+ ...parentStep,
+ settings: { ...parentStep.settings, branches: parentStep.settings.branches.filter(keep) },
+ children,
}
})
}
-export { _deleteBranch }
\ No newline at end of file
+export { _deleteBranch }
diff --git a/packages/core/execution/src/lib/flows/operations/duplicate-step.ts b/packages/core/execution/src/lib/flows/operations/duplicate-step.ts
index 7916b9a9afa..407b4acb7d1 100644
--- a/packages/core/execution/src/lib/flows/operations/duplicate-step.ts
+++ b/packages/core/execution/src/lib/flows/operations/duplicate-step.ts
@@ -1,5 +1,5 @@
import { isNil } from '@activepieces/core-utils'
-import { BranchExecutionType, FlowAction, RouterAction } from '../actions/action'
+import { BranchCondition, BranchedAction, BranchExecutionType, FlowAction, FlowActionType } from '../actions/action'
import { FlowVersion } from '../flow-version'
import { flowStructureUtil } from '../util/flow-structure-util'
import { addActionUtils } from './add-action-util'
@@ -32,20 +32,29 @@ function _duplicateStep(stepName: string, flowVersion: FlowVersion): FlowOperati
]
}
+function branchShapeOf(router: BranchedAction, childIndex: number): { conditions?: BranchCondition[][], description?: string } {
+ if (router.type === FlowActionType.AI_ROUTER) {
+ const branch = router.settings.branches[childIndex]
+ return branch.branchType === BranchExecutionType.CONDITION ? { description: branch.description } : {}
+ }
+ const branch = router.settings.branches[childIndex]
+ return branch.branchType === BranchExecutionType.CONDITION ? { conditions: branch.conditions } : {}
+}
+
function _duplicateBranch(
routerName: string,
childIndex: number,
flowVersion: FlowVersion,
): FlowOperationRequest[] {
const router = flowStructureUtil.getActionOrThrow(routerName, flowVersion.trigger)
- const clonedRouter: RouterAction = JSON.parse(JSON.stringify(router))
+ const clonedRouter: BranchedAction = JSON.parse(JSON.stringify(router))
const operations: FlowOperationRequest[] = [{
type: FlowOperationType.ADD_BRANCH,
request: {
branchName: `${clonedRouter.settings.branches[childIndex].branchName} Copy`,
branchIndex: childIndex + 1,
stepName: routerName,
- conditions: clonedRouter.settings.branches[childIndex].branchType === BranchExecutionType.CONDITION ? clonedRouter.settings.branches[childIndex].conditions : undefined,
+ ...branchShapeOf(clonedRouter, childIndex),
},
}]
diff --git a/packages/core/execution/src/lib/flows/operations/import-flow.ts b/packages/core/execution/src/lib/flows/operations/import-flow.ts
index bbf11597af9..b86c753ba82 100644
--- a/packages/core/execution/src/lib/flows/operations/import-flow.ts
+++ b/packages/core/execution/src/lib/flows/operations/import-flow.ts
@@ -54,7 +54,8 @@ function _getImportOperationsForSteps(step: FlowAction | FlowTrigger | undefined
}
break
}
- case FlowActionType.ROUTER: {
+ case FlowActionType.ROUTER:
+ case FlowActionType.AI_ROUTER: {
if (step.children) {
for (const [index, child] of step.children.entries()) {
if (!isNil(child)) {
@@ -133,7 +134,8 @@ function _getImportOperationsForNotes(flowVersion: FlowVersion, request: ImportF
function removeAnySubsequentAction(action: FlowAction): FlowAction {
const clonedAction: FlowAction = JSON.parse(JSON.stringify(action))
switch (clonedAction.type) {
- case FlowActionType.ROUTER: {
+ case FlowActionType.ROUTER:
+ case FlowActionType.AI_ROUTER: {
clonedAction.children = clonedAction.children.map((child: FlowAction | null) => {
if (isNil(child)) {
return null
diff --git a/packages/core/execution/src/lib/flows/operations/index.ts b/packages/core/execution/src/lib/flows/operations/index.ts
index a81550c1ef5..84baa078e11 100644
--- a/packages/core/execution/src/lib/flows/operations/index.ts
+++ b/packages/core/execution/src/lib/flows/operations/index.ts
@@ -1,7 +1,7 @@
import { z } from 'zod'
import { Nullable } from '@activepieces/core-utils'
import { Metadata } from '@activepieces/core-utils'
-import { BranchCondition, CodeActionSchema, CodeActionSettings, FlowActionType, LoopOnItemsActionSchema, LoopOnItemsActionSettings, PieceActionSchema, PieceActionSettings, RouterActionSchema, RouterActionSettings } from '../actions/action'
+import { AiRouterActionSchema, AiRouterActionSettings, BranchCondition, CodeActionSchema, CodeActionSettings, FlowActionType, LoopOnItemsActionSchema, LoopOnItemsActionSettings, PieceActionSchema, PieceActionSettings, RouterActionSchema, RouterActionSettings } from '../actions/action'
import { FlowStatus } from '../flow'
import { FlowVersion, FlowVersionState } from '../flow-version'
import { Note } from '../note'
@@ -69,6 +69,7 @@ export const AddBranchRequest = z.object({
branchIndex: z.number(),
stepName: z.string(),
conditions: z.array(z.array(BranchCondition)).optional(),
+ description: z.string().optional(),
branchName: z.string(),
})
export const MoveBranchRequest = z.object({
@@ -153,6 +154,7 @@ export const UpdateActionRequest = z.union([
LoopOnItemsActionSchema.omit({ lastUpdatedDate: true, settings: true }).and(z.object({ settings: LoopOnItemsActionSettings.omit({ sampleData: true }) })),
PieceActionSchema.omit({ lastUpdatedDate: true, settings: true }).and(z.object({ settings: PieceActionSettings.omit({ sampleData: true }) })),
RouterActionSchema.omit({ lastUpdatedDate: true, settings: true }).and(z.object({ settings: RouterActionSettings.omit({ sampleData: true }) })),
+ AiRouterActionSchema.omit({ lastUpdatedDate: true, settings: true }).and(z.object({ settings: AiRouterActionSettings.omit({ sampleData: true }) })),
])
diff --git a/packages/core/execution/src/lib/flows/operations/move-branch.ts b/packages/core/execution/src/lib/flows/operations/move-branch.ts
index cf6a9975df1..3f2842a8fd7 100644
--- a/packages/core/execution/src/lib/flows/operations/move-branch.ts
+++ b/packages/core/execution/src/lib/flows/operations/move-branch.ts
@@ -1,29 +1,32 @@
-import { BranchExecutionType, FlowActionType } from '../actions/action'
+import { AiRouterAction, BranchExecutionType, RouterAction } from '../actions/action'
import { FlowVersion } from '../flow-version'
import { flowStructureUtil } from '../util/flow-structure-util'
import { MoveBranchRequest } from '.'
const isIndexWithinBounds = (index: number, arrayLength: number) => index >= 0 && index < arrayLength
+
export function _moveBranch(flowVersion: FlowVersion, request: MoveBranchRequest): FlowVersion {
return flowStructureUtil.transferFlow(flowVersion, (stepToUpdate) => {
- if (stepToUpdate.name !== request.stepName || stepToUpdate.type !== FlowActionType.ROUTER) {
+ if (stepToUpdate.name !== request.stepName || !flowStructureUtil.isBranchedAction(stepToUpdate)) {
return stepToUpdate
}
- const routerStep = stepToUpdate
- if (!isIndexWithinBounds(request.sourceBranchIndex, routerStep.settings.branches.length) || !isIndexWithinBounds(request.targetBranchIndex, routerStep.settings.branches.length) || request.sourceBranchIndex === request.targetBranchIndex) {
+ const branches = stepToUpdate.settings.branches
+ if (!isIndexWithinBounds(request.sourceBranchIndex, branches.length) || !isIndexWithinBounds(request.targetBranchIndex, branches.length) || request.sourceBranchIndex === request.targetBranchIndex) {
return stepToUpdate
}
- if (routerStep.settings.branches[request.sourceBranchIndex].branchType === BranchExecutionType.FALLBACK || routerStep.settings.branches[request.targetBranchIndex].branchType === BranchExecutionType.FALLBACK) {
+ if (branches[request.sourceBranchIndex].branchType === BranchExecutionType.FALLBACK || branches[request.targetBranchIndex].branchType === BranchExecutionType.FALLBACK) {
return stepToUpdate
}
- const sourceBranch = routerStep.settings.branches[request.sourceBranchIndex]
- routerStep.settings.branches.splice(request.sourceBranchIndex, 1)
- routerStep.settings.branches.splice(request.targetBranchIndex, 0, sourceBranch)
- const sourceBranchChildren = routerStep.children[request.sourceBranchIndex]
- routerStep.children.splice(request.sourceBranchIndex, 1)
- routerStep.children.splice(request.targetBranchIndex, 0, sourceBranchChildren)
- return routerStep
+ moveInPlace({ items: stepToUpdate.children, from: request.sourceBranchIndex, to: request.targetBranchIndex })
+ moveInPlace<Branch>({ items: stepToUpdate.settings.branches, from: request.sourceBranchIndex, to: request.targetBranchIndex })
+ return stepToUpdate
})
+}
+
+function moveInPlace<T>({ items, from, to }: { items: T[], from: number, to: number }): void {
+ const [moved] = items.splice(from, 1)
+ items.splice(to, 0, moved)
+}
-}
\ No newline at end of file
+type Branch = (RouterAction | AiRouterAction)['settings']['branches'][number]
diff --git a/packages/core/execution/src/lib/flows/operations/update-action.ts b/packages/core/execution/src/lib/flows/operations/update-action.ts
index 3085324bf28..85bd17b1ad0 100644
--- a/packages/core/execution/src/lib/flows/operations/update-action.ts
+++ b/packages/core/execution/src/lib/flows/operations/update-action.ts
@@ -75,6 +75,19 @@ function _updateAction(flowVersion: FlowVersion, request: UpdateActionRequest):
}
break
}
+
+ case FlowActionType.AI_ROUTER: {
+ const existingSampleData = stepToUpdate.type === FlowActionType.AI_ROUTER ? stepToUpdate.settings.sampleData : undefined
+ const children = stepToUpdate.type === FlowActionType.AI_ROUTER ? stepToUpdate.children : [null, null]
+ updatedAction = {
+ ...baseProps,
+ settings: { ...request.settings, sampleData: existingSampleData },
+ type: FlowActionType.AI_ROUTER,
+ nextAction: stepToUpdate.nextAction,
+ children,
+ }
+ break
+ }
}
const parseResult = SingleActionSchema.safeParse(updatedAction)
const valid = (isNil(request.valid) ? true : request.valid) && parseResult.success
diff --git a/packages/core/execution/src/lib/flows/triggers/trigger.ts b/packages/core/execution/src/lib/flows/triggers/trigger.ts
index 59e64e79d3d..45af9c9afda 100755
--- a/packages/core/execution/src/lib/flows/triggers/trigger.ts
+++ b/packages/core/execution/src/lib/flows/triggers/trigger.ts
@@ -1,7 +1,7 @@
import { z } from 'zod'
import { STEP_NAME_REGEX } from '@activepieces/core-utils'
import { VersionType } from '@activepieces/core-piece-types'
-import { CodeActionSettings, LoopOnItemsActionSettings, PieceActionSettings, RouterActionSettings } from '../actions/action'
+import { AiRouterActionSettings, CodeActionSettings, LoopOnItemsActionSettings, PieceActionSettings, RouterActionSettings } from '../actions/action'
import { PropertySettings } from '../properties'
import { SampleDataSetting } from '../sample-data'
@@ -69,4 +69,5 @@ export type StepSettings =
| PieceActionSettings
| PieceTriggerSettings
| RouterActionSettings
+ | AiRouterActionSettings
| LoopOnItemsActionSettings
diff --git a/packages/core/execution/src/lib/flows/util/flow-canvas-util.ts b/packages/core/execution/src/lib/flows/util/flow-canvas-util.ts
index 8ab4ed5e8b6..92931d57f56 100644
--- a/packages/core/execution/src/lib/flows/util/flow-canvas-util.ts
+++ b/packages/core/execution/src/lib/flows/util/flow-canvas-util.ts
@@ -37,7 +37,7 @@ function getFlowBoundingBox(step: Step | FlowAction | null | undefined, forBranc
withChildMaxX = Math.max(FLOW_CANVAS_STEP_WIDTH, deltaLeftX + FLOW_CANVAS_STEP_WIDTH, childOffsetX + childBoundingBox.maxX)
withChildHeight = Math.max(FLOW_CANVAS_STEP_HEIGHT + FLOW_CANVAS_VSPACE, subgraphEndY)
}
- else if (step.type === FlowActionType.ROUTER) {
+ else if (flowStructureUtil.isBranchedAction(step)) {
const children = step.children
if (children.length > 0) {
const childBoundingBoxes = children.map(c => getFlowBoundingBox(c, true))
@@ -88,7 +88,7 @@ function buildPositions({ step, offsetX, offsetY, positions }: {
const subgraphEndY = FLOW_CANVAS_STEP_HEIGHT + FLOW_CANVAS_LOOP_VOFFSET + childBoundingBox.height + FLOW_CANVAS_ARC + FLOW_CANVAS_VSPACE
buildPositions({ step: step.nextAction, offsetX, offsetY: offsetY + subgraphEndY, positions })
}
- else if (step.type === FlowActionType.ROUTER) {
+ else if (flowStructureUtil.isBranchedAction(step)) {
const subgraphEndY = positionBranchedChildren({ children: step.children, offsetX, offsetY, positions })
buildPositions({ step: step.nextAction, offsetX, offsetY: offsetY + subgraphEndY, positions })
}
diff --git a/packages/core/execution/src/lib/flows/util/flow-structure-util.ts b/packages/core/execution/src/lib/flows/util/flow-structure-util.ts
index b768ca293e7..6d687960a24 100644
--- a/packages/core/execution/src/lib/flows/util/flow-structure-util.ts
+++ b/packages/core/execution/src/lib/flows/util/flow-structure-util.ts
@@ -1,7 +1,7 @@
import { AgentPieceProps } from '@activepieces/core-piece-types'
import { isNil, unique } from '@activepieces/core-utils'
import { ActivepiecesError, ErrorCode } from '@activepieces/core-utils'
-import { BranchCondition, BranchExecutionType, emptyCondition, FlowAction, FlowActionType } from '../actions/action'
+import { BranchCondition, BranchedAction, BranchExecutionType, emptyCondition, FlowAction, FlowActionType } from '../actions/action'
import { FlowVersion } from '../flow-version'
import { FlowTrigger, FlowTriggerType } from '../triggers/trigger'
@@ -22,6 +22,12 @@ function isStepAction(step: Step): step is FlowAction {
|| step.type === FlowActionType.PIECE
|| step.type === FlowActionType.LOOP_ON_ITEMS
|| step.type === FlowActionType.ROUTER
+ || step.type === FlowActionType.AI_ROUTER
+}
+
+function isBranchedAction(step: Step): step is BranchedAction {
+ return step.type === FlowActionType.ROUTER
+ || step.type === FlowActionType.AI_ROUTER
}
function isTrigger(type: FlowActionType | FlowTriggerType | undefined): type is FlowTriggerType {
@@ -93,7 +99,8 @@ function transferStep<T extends Step>(
}
break
}
- case FlowActionType.ROUTER: {
+ case FlowActionType.ROUTER:
+ case FlowActionType.AI_ROUTER: {
const { children } = updatedStep
if (children) {
updatedStep.children = children.map((child) =>
@@ -292,5 +299,6 @@ export const flowStructureUtil = {
getAllChildSteps,
extractConnectionIds,
isAgentPiece,
+ isBranchedAction,
extractAgentIds,
}
\ No newline at end of file
diff --git a/packages/core/execution/src/lib/workers/job-data.ts b/packages/core/execution/src/lib/workers/job-data.ts
index 47a804fc1cd..5da507e4951 100644
--- a/packages/core/execution/src/lib/workers/job-data.ts
+++ b/packages/core/execution/src/lib/workers/job-data.ts
@@ -4,7 +4,7 @@ import { AIProviderName, AiStepAction, isNil } from '@activepieces/core-utils'
import { ResumeReason, StreamStepProgress, TriggerHookType, TriggerPayload } from '../engine'
import { ExecutionType } from '../flow-run/execution/execution-output'
import { RunEnvironment } from '../flow-run/flow-run'
-import { CodeActionSchema, PieceActionSchema } from '../flows/actions/action'
+import { AiRouterMatchMode, CodeActionSchema, PieceActionSchema } from '../flows/actions/action'
import { FlowVersion } from '../flows/flow-version'
import { FlowTriggerType } from '../flows/triggers/trigger'
import { AppConnectionType, AppConnectionValue, PiecePackage } from '@activepieces/core-piece-types'
@@ -455,12 +455,22 @@ export const GenerateImageJobData = AiStepJobBase.extend({
})
export type GenerateImageJobData = z.infer<typeof GenerateImageJobData>
+export const RouteJobData = AiStepJobBase.extend({
+ action: z.literal(AiStepAction.ROUTE),
+ state: z.string(),
+ question: z.string(),
+ options: z.record(z.string(), z.string()),
+ matchMode: z.enum(AiRouterMatchMode),
+})
+export type RouteJobData = z.infer<typeof RouteJobData>
+
export const ExecuteAiJobData = z.discriminatedUnion('action', [
AskAiJobData,
SummarizeTextJobData,
ClassifyTextJobData,
ExtractStructuredDataJobData,
GenerateImageJobData,
+ RouteJobData,
])
export type ExecuteAiJobData = z.infer<typeof ExecuteAiJobData>
diff --git a/packages/core/execution/test/flow/ai-router-branches.test.ts b/packages/core/execution/test/flow/ai-router-branches.test.ts
new file mode 100644
index 00000000000..07c54f26dac
--- /dev/null
+++ b/packages/core/execution/test/flow/ai-router-branches.test.ts
@@ -0,0 +1,187 @@
+import { describe, expect, it } from 'vitest'
+import { AiRouterMatchMode, BranchExecutionType, FlowActionType } from '../../src/lib/flows/actions/action'
+import { FlowVersion, FlowVersionState } from '../../src/lib/flows/flow-version'
+import { flowOperations, FlowOperationType, StepLocationRelativeToParent, UpdateActionRequest } from '../../src/lib/flows/operations'
+import { flowStructureUtil } from '../../src/lib/flows/util/flow-structure-util'
+import { FlowTriggerType } from '../../src/lib/flows/triggers/trigger'
+
+function flowWithAiRouter(): FlowVersion {
+ return {
+ id: 'v1',
+ flowId: 'f1',
+ displayName: 'test',
+ valid: true,
+ state: FlowVersionState.DRAFT,
+ schemaVersion: '27',
+ updatedBy: null,
+ created: '',
+ updated: '',
+ trigger: {
+ name: 'trigger',
+ displayName: 'Trigger',
+ valid: true,
+ type: FlowTriggerType.EMPTY,
+ settings: {},
+ lastUpdatedDate: new Date().toISOString(),
+ nextAction: {
+ name: 'step_1',
+ displayName: 'AI Router',
+ valid: false,
+ lastUpdatedDate: new Date().toISOString(),
+ type: FlowActionType.AI_ROUTER,
+ settings: {
+ text: '',
+ question: '',
+ matchMode: AiRouterMatchMode.BEST_MATCH,
+ branches: [
+ { branchType: BranchExecutionType.CONDITION, branchName: 'Route 1', description: '' },
+ { branchType: BranchExecutionType.FALLBACK, branchName: 'Otherwise', description: 'else' },
+ ],
+ },
+ children: [null, null],
+ },
+ },
+ } as FlowVersion
+}
+
+function routerOf(flowVersion: FlowVersion) {
+ const step = flowStructureUtil.getActionOrThrow('step_1', flowVersion.trigger)
+ if (step.type !== FlowActionType.AI_ROUTER) {
+ throw new Error('expected an ai router')
+ }
+ return step
+}
+
+describe('branch operations on an AI_ROUTER', () => {
+ it('adds a route with a description rather than a condition tree', () => {
+ const flowVersion = flowOperations.apply(flowWithAiRouter(), {
+ type: FlowOperationType.ADD_BRANCH,
+ request: { stepName: 'step_1', branchIndex: 1, branchName: 'Route 2', description: 'refunds' },
+ })
+
+ const router = routerOf(flowVersion)
+ expect(router.settings.branches.map((branch) => branch.branchName)).toEqual(['Route 1', 'Route 2', 'Otherwise'])
+ expect(router.settings.branches[1]).toEqual({
+ branchType: BranchExecutionType.CONDITION,
+ branchName: 'Route 2',
+ description: 'refunds',
+ })
+ expect(router.children).toHaveLength(3)
+ })
+
+ it('puts an added step inside the branch it was added to', () => {
+ const flowVersion = flowOperations.apply(flowWithAiRouter(), {
+ type: FlowOperationType.ADD_ACTION,
+ request: {
+ parentStep: 'step_1',
+ stepLocationRelativeToParent: StepLocationRelativeToParent.INSIDE_BRANCH,
+ branchIndex: 0,
+ action: {
+ name: 'step_2',
+ displayName: 'Code',
+ valid: true,
+ type: FlowActionType.CODE,
+ settings: { sourceCode: { packageJson: '{}', code: 'x' }, input: {} },
+ },
+ },
+ })
+
+ const router = routerOf(flowVersion)
+ expect(router.children[0]?.name).toBe('step_2')
+ expect(router.children[1]).toBeNull()
+ expect(flowStructureUtil.getAllSteps(flowVersion.trigger).map((step) => step.name)).toContain('step_2')
+ })
+
+ it('duplicates a route carrying its description, not conditions', () => {
+ const base = flowWithAiRouter()
+ routerOf(base).settings.branches[0] = { branchType: BranchExecutionType.CONDITION, branchName: 'Route 1', description: 'payments and refunds' }
+
+ const flowVersion = flowOperations.apply(base, {
+ type: FlowOperationType.DUPLICATE_BRANCH,
+ request: { stepName: 'step_1', branchIndex: 0 },
+ })
+
+ const router = routerOf(flowVersion)
+ expect(router.settings.branches.map((branch) => branch.branchName)).toEqual(['Route 1', 'Route 1 Copy', 'Otherwise'])
+ expect(router.settings.branches[1]).toEqual({
+ branchType: BranchExecutionType.CONDITION,
+ branchName: 'Route 1 Copy',
+ description: 'payments and refunds',
+ })
+ expect(router.children).toHaveLength(3)
+ })
+
+ it('can still be saved when it predates a newer settings field', () => {
+ const legacy = {
+ name: 'step_1',
+ displayName: 'AI Router',
+ valid: false,
+ skip: false,
+ type: FlowActionType.AI_ROUTER,
+ settings: {
+ text: 'x',
+ question: 'q',
+ branches: [
+ { branchType: BranchExecutionType.CONDITION, branchName: 'Route 1', description: 'Payments' },
+ { branchType: BranchExecutionType.FALLBACK, branchName: 'Otherwise', description: 'else' },
+ ],
+ },
+ }
+
+ const parsed = UpdateActionRequest.safeParse(legacy)
+ expect(parsed.success).toBe(true)
+ })
+
+ it('keeps a route description through an update', () => {
+ const flowVersion = flowOperations.apply(flowWithAiRouter(), {
+ type: FlowOperationType.UPDATE_ACTION,
+ request: {
+ name: 'step_1',
+ displayName: 'AI Router',
+ valid: false,
+ skip: false,
+ type: FlowActionType.AI_ROUTER,
+ settings: {
+ text: 'x',
+ question: 'q',
+ matchMode: AiRouterMatchMode.BEST_MATCH,
+ branches: [
+ { branchType: BranchExecutionType.CONDITION, branchName: 'Route 1', description: 'Payments and refunds' },
+ { branchType: BranchExecutionType.FALLBACK, branchName: 'Otherwise', description: 'else' },
+ ],
+ },
+ },
+ })
+
+ expect(routerOf(flowVersion).settings.branches[0].description).toBe('Payments and refunds')
+ })
+
+ it('keeps branches and children in lockstep across move and delete', () => {
+ let flowVersion = flowOperations.apply(flowWithAiRouter(), {
+ type: FlowOperationType.ADD_BRANCH,
+ request: { stepName: 'step_1', branchIndex: 1, branchName: 'Route 2' },
+ })
+ flowVersion = flowOperations.apply(flowVersion, {
+ type: FlowOperationType.MOVE_BRANCH,
+ request: { stepName: 'step_1', sourceBranchIndex: 0, targetBranchIndex: 1 },
+ })
+ expect(routerOf(flowVersion).settings.branches.map((branch) => branch.branchName)).toEqual(['Route 2', 'Route 1', 'Otherwise'])
+
+ flowVersion = flowOperations.apply(flowVersion, {
+ type: FlowOperationType.DELETE_BRANCH,
+ request: { stepName: 'step_1', branchIndex: 0 },
+ })
+ const router = routerOf(flowVersion)
+ expect(router.settings.branches.map((branch) => branch.branchName)).toEqual(['Route 1', 'Otherwise'])
+ expect(router.children).toHaveLength(2)
+ })
+
+ it('never moves the fallback route out of last place', () => {
+ const flowVersion = flowOperations.apply(flowWithAiRouter(), {
+ type: FlowOperationType.MOVE_BRANCH,
+ request: { stepName: 'step_1', sourceBranchIndex: 1, targetBranchIndex: 0 },
+ })
+
+ expect(routerOf(flowVersion).settings.branches.map((branch) => branch.branchName)).toEqual(['Route 1', 'Otherwise'])
+ })
+})
diff --git a/packages/core/execution/test/workers/ai-job-data.test.ts b/packages/core/execution/test/workers/ai-job-data.test.ts
index f829ba2377b..c2372e5042b 100644
--- a/packages/core/execution/test/workers/ai-job-data.test.ts
+++ b/packages/core/execution/test/workers/ai-job-data.test.ts
@@ -60,6 +60,13 @@ describe('what an AI step job accepts', () => {
expect(ExecuteAiJobData.safeParse({ ...base, action: AiStepAction.EXTRACT_STRUCTURED_DATA, prompt: undefined }).success).toBe(true)
})
+ it('takes a route job with its state, question, options and match mode, and refuses one without a question', () => {
+ const route = { ...base, action: AiStepAction.ROUTE, state: 'charged twice', question: 'Which team?', options: { Billing: 'Payments' }, matchMode: 'BEST_MATCH' }
+
+ expect(ExecuteAiJobData.safeParse(route).success).toBe(true)
+ expect(ExecuteAiJobData.safeParse({ ...route, question: undefined }).success).toBe(false)
+ })
+
it('still rejects an action nobody ships', () => {
expect(ExecuteAiJobData.safeParse({ ...base, action: 'TRANSLATE' }).success).toBe(false)
})
diff --git a/packages/core/shared/package.json b/packages/core/shared/package.json
index 76ff9a9bad9..f047f5dcd0c 100644
--- a/packages/core/shared/package.json
+++ b/packages/core/shared/package.json
@@ -1,6 +1,6 @@
{
"name": "@activepieces/shared",
- "version": "0.179.0",
+ "version": "0.180.0",
"type": "commonjs",
"sideEffects": false,
"main": "./dist/src/index.js",
diff --git a/packages/core/utils/package.json b/packages/core/utils/package.json
index 2f51b0a80ef..84db8f954ae 100644
--- a/packages/core/utils/package.json
+++ b/packages/core/utils/package.json
@@ -1,6 +1,6 @@
{
"name": "@activepieces/core-utils",
- "version": "0.8.0",
+ "version": "0.8.1",
"type": "commonjs",
"main": "./dist/src/index.js",
"scripts": {
diff --git a/packages/core/utils/src/lib/activepieces-error.ts b/packages/core/utils/src/lib/activepieces-error.ts
index 318d93d0eeb..5696e6c790f 100644
--- a/packages/core/utils/src/lib/activepieces-error.ts
+++ b/packages/core/utils/src/lib/activepieces-error.ts
@@ -380,6 +380,7 @@ ErrorCode.QUOTA_EXCEEDED,
metric: PlatformUsageMetric
usage?: number
limit?: number
+ message?: string
}
>
diff --git a/packages/core/utils/src/lib/ai-step.ts b/packages/core/utils/src/lib/ai-step.ts
index 3da62518caf..4a799147f18 100644
--- a/packages/core/utils/src/lib/ai-step.ts
+++ b/packages/core/utils/src/lib/ai-step.ts
@@ -4,4 +4,5 @@ export enum AiStepAction {
CLASSIFY_TEXT = 'CLASSIFY_TEXT',
EXTRACT_STRUCTURED_DATA = 'EXTRACT_STRUCTURED_DATA',
GENERATE_IMAGE = 'GENERATE_IMAGE',
+ ROUTE = 'ROUTE',
}
diff --git a/packages/core/utils/src/lib/form-errors.ts b/packages/core/utils/src/lib/form-errors.ts
index ffd87bbfb5d..ab25cb23770 100644
--- a/packages/core/utils/src/lib/form-errors.ts
+++ b/packages/core/utils/src/lib/form-errors.ts
@@ -8,6 +8,7 @@ export const formErrors = {
messageRequiresContentOrFiles: 'messageRequiresContentOrFiles',
agentConfigTooLarge: 'agentConfigTooLarge',
invalidGcpResourceId: 'invalidGcpResourceId',
+ duplicateRouteName: 'duplicateRouteName',
atLeastOne: 'atLeastOne',
wholeNumber: 'wholeNumber',
atMostTenThousand: 'atMostTenThousand',
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 53620f4ee13..25b0aa20b4a 100644
--- a/packages/server/api/src/app/ai/ai-execute-controller.ts
+++ b/packages/server/api/src/app/ai/ai-execute-controller.ts
@@ -1,6 +1,5 @@
import { ActivepiecesError, AIProviderName, apId, ErrorCode, isNil } from '@activepieces/core-utils'
-import { AiStepAction, AiStepFile, AiStepSchema, AiStepWebSearch, EngineResponseStatus, ExecuteAiJobData, LATEST_JOB_DATA_SCHEMA_VERSION, maxSocketHttpBufferSizeBytes, PrincipalType, WorkerJobType } from '@activepieces/shared'
-import { FastifyBaseLogger } from 'fastify'
+import { AiStepAction, AiStepFile, AiStepSchema, AiStepWebSearch, ExecuteAiJobData, LATEST_JOB_DATA_SCHEMA_VERSION, maxSocketHttpBufferSizeBytes, PrincipalType, WorkerJobType } from '@activepieces/shared'
import { FastifyPluginAsyncZod } from 'fastify-type-provider-zod'
import { StatusCodes } from 'http-status-codes'
import { z } from 'zod'
@@ -8,8 +7,7 @@ import { securityAccess } from '../core/security/authorization/fastify-security'
import { system } from '../helper/system/system'
import { AppSystemProp } from '../helper/system/system-props'
import { assertCreditsAndAppSumoNotExceeded } from '../platform/billing-provider'
-import { engineResponseWatcher } from '../workers/engine-response-watcher'
-import { jobQueue, JobType } from '../workers/job-queue/job-queue'
+import { aiExecution } from './ai-execution'
export const aiExecuteController: FastifyPluginAsyncZod = async (app) => {
const bodyLimit = maxSocketHttpBufferSizeBytes(system.getNumberOrThrow(AppSystemProp.MAX_FILE_SIZE_MB))
@@ -27,20 +25,18 @@ export const aiExecuteController: FastifyPluginAsyncZod = async (app) => {
const requestId = apId()
const log = request.log.child({ flowRun: { id: body.flowRunId }, requestId })
+ const execution = aiExecution(log)
const answerInThisRequest = isNil(body.waitpointId)
- const answer = answerInThisRequest ? listenForWorkerAnswer({ requestId, log }) : undefined
+ const timeoutMs = system.getNumberOrThrow(AppSystemProp.FLOW_TIMEOUT_SECONDS) * 1000
+ const answer = answerInThisRequest ? execution.waitForAnswer({ requestId, timeoutMs }) : undefined
- await jobQueue(log).add({
- id: apId(),
- type: JobType.ONE_TIME,
- data: aiJobFor({
- body,
- requestId,
- projectId,
- platformId: platform.id,
- webserverId: answerInThisRequest ? engineResponseWatcher(log).getServerId() : undefined,
- }),
- })
+ await execution.enqueue(aiJobFor({
+ body,
+ requestId,
+ projectId,
+ platformId: platform.id,
+ webserverId: answerInThisRequest ? execution.serverId() : undefined,
+ }))
if (!isNil(answer)) {
return reply.status(StatusCodes.OK).send({ requestId, ...await answer })
@@ -107,22 +103,10 @@ function aiJobFor({ body, requestId, projectId, platformId, webserverId }: {
}
}
-async function listenForWorkerAnswer({ requestId, log }: { requestId: string, log: FastifyBaseLogger }): Promise<{ output?: unknown, failure?: string }> {
- const timeoutMs = system.getNumberOrThrow(AppSystemProp.FLOW_TIMEOUT_SECONDS) * 1000
- const response = await engineResponseWatcher(log).oneTimeListener<WorkerResponse | undefined>(requestId, true, timeoutMs, undefined)
- if (isNil(response)) {
- return { failure: 'The AI step did not finish in time' }
- }
- if (response.status !== EngineResponseStatus.OK) {
- return { failure: response.error ?? 'The AI step failed' }
- }
- return response.response ?? { failure: 'The AI step reported nothing back' }
-}
-
const RUN_PRINCIPALS = [PrincipalType.ENGINE] as const
const ExecuteAiRequest = z.object({
- action: z.enum(AiStepAction),
+ action: z.enum(AiStepAction).exclude(['ROUTE']),
flowId: z.string(),
flowRunId: z.string(),
waitpointId: z.string().optional(),
@@ -157,9 +141,3 @@ const ExecuteAiRoute = {
response: { [StatusCodes.OK]: ExecuteAiResponse },
},
}
-
-type WorkerResponse = {
- status: EngineResponseStatus
- response?: { output?: unknown, failure?: string }
- error?: string
-}
diff --git a/packages/server/api/src/app/ai/ai-execution.ts b/packages/server/api/src/app/ai/ai-execution.ts
new file mode 100644
index 00000000000..13bdea444d1
--- /dev/null
+++ b/packages/server/api/src/app/ai/ai-execution.ts
@@ -0,0 +1,35 @@
+import { apId, isNil } from '@activepieces/core-utils'
+import { EngineResponseStatus, ExecuteAiJobData } from '@activepieces/shared'
+import { FastifyBaseLogger } from 'fastify'
+import { engineResponseWatcher } from '../workers/engine-response-watcher'
+import { jobQueue, JobType } from '../workers/job-queue/job-queue'
+
+export const aiExecution = (log: FastifyBaseLogger) => ({
+ serverId(): string {
+ return engineResponseWatcher(log).getServerId()
+ },
+ async enqueue(data: ExecuteAiJobData): Promise<void> {
+ await jobQueue(log).add({ id: apId(), type: JobType.ONE_TIME, data })
+ },
+ async waitForAnswer({ requestId, timeoutMs }: { requestId: string, timeoutMs: number }): Promise<AiStepAnswer> {
+ const response = await engineResponseWatcher(log).oneTimeListener<WorkerResponse | undefined>(requestId, true, timeoutMs, undefined)
+ if (isNil(response)) {
+ return { failure: 'The AI step did not finish in time' }
+ }
+ if (response.status !== EngineResponseStatus.OK) {
+ return { failure: response.error ?? 'The AI step failed' }
+ }
+ return response.response ?? { failure: 'The AI step reported nothing back' }
+ },
+})
+
+export type AiStepAnswer = {
+ output?: unknown
+ failure?: string
+}
+
+type WorkerResponse = {
+ status: EngineResponseStatus
+ response?: AiStepAnswer
+ error?: string
+}
diff --git a/packages/server/api/src/app/ai/ai-router.service.ts b/packages/server/api/src/app/ai/ai-router.service.ts
new file mode 100644
index 00000000000..27779c89092
--- /dev/null
+++ b/packages/server/api/src/app/ai/ai-router.service.ts
@@ -0,0 +1,111 @@
+import { ActivepiecesError, AIProviderName, apId, ErrorCode, isNil, tryCatch } from '@activepieces/core-utils'
+import { AiStepAction, ChooseAiRouteRequest, ChooseAiRouteResponse, ExecuteAiJobData, LATEST_JOB_DATA_SCHEMA_VERSION, StartAiRouteResponse, WorkerJobType } from '@activepieces/shared'
+import { FastifyBaseLogger } from 'fastify'
+import { assertCreditsAndAppSumoNotExceeded } from '../platform/billing-provider'
+import { aiExecution } from './ai-execution'
+import { aiProviderService } from './ai-provider-service'
+
+export const aiRouterService = (log: FastifyBaseLogger) => ({
+ async start({ platformId, projectId, waitpointId, ...request }: StartParams): Promise<StartAiRouteResponse> {
+ const provider = await pickProvider({ platformId, projectId, log })
+ await assertHasCredits({ platformId, log })
+ const requestId = apId()
+ await aiExecution(log).enqueue(routeJob({ request, requestId, platformId, projectId, provider, waitpointId }))
+ log.info({ requestId, flowRun: { id: request.flowRunId }, provider }, 'Started the AI router decision for a paused step')
+ return { requestId }
+ },
+
+ async choose({ platformId, projectId, ...request }: ChooseParams): Promise<ChooseAiRouteResponse> {
+ const provider = await pickProvider({ platformId, projectId, log })
+ await assertHasCredits({ platformId, log })
+
+ const execution = aiExecution(log)
+ const requestId = apId()
+ const answer = execution.waitForAnswer({ requestId, timeoutMs: WAIT_MS })
+ await execution.enqueue(routeJob({ request, requestId, platformId, projectId, provider, webserverId: execution.serverId() }))
+
+ const { output, failure } = await answer
+ if (!isNil(failure)) {
+ throw new ActivepiecesError({ code: ErrorCode.ENGINE_OPERATION_FAILURE, params: { message: failure } })
+ }
+ const parsed = ChooseAiRouteResponse.safeParse(output)
+ if (!parsed.success) {
+ throw new ActivepiecesError({ code: ErrorCode.ENGINE_OPERATION_FAILURE, params: { message: 'The routing model answered in a shape the AI Router does not understand' } })
+ }
+ log.info({ matched: parsed.data.matched, matchMode: request.matchMode, provider }, 'Chose the AI router routes')
+ return parsed.data
+ },
+})
+
+function routeJob({ request, requestId, platformId, projectId, provider, waitpointId, webserverId }: RouteJobParams): ExecuteAiJobData {
+ return {
+ schemaVersion: LATEST_JOB_DATA_SCHEMA_VERSION,
+ jobType: WorkerJobType.EXECUTE_AI,
+ action: AiStepAction.ROUTE,
+ requestId,
+ waitpointId,
+ webserverId,
+ projectId,
+ platformId,
+ flowId: request.flowId,
+ flowRunId: request.flowRunId,
+ provider,
+ modelId: AI_ROUTER_MODEL_ID,
+ state: request.state,
+ question: request.question,
+ options: request.options,
+ matchMode: request.matchMode,
+ }
+}
+
+async function pickProvider({ platformId, projectId, log }: { platformId: string, projectId: string, log: FastifyBaseLogger }): Promise<AIProviderName> {
+ const available = await aiProviderService(log).listForProject({ platformId, projectId })
+ const provider = ROUTER_PROVIDERS.find((candidate) => available.some((entry) => entry.provider === candidate))
+ if (isNil(provider)) {
+ throw new ActivepiecesError({
+ code: ErrorCode.FEATURE_DISABLED,
+ params: { message: 'The AI Router needs an OpenRouter key. On Cloud that is the Activepieces provider; self-hosted, add OpenRouter under AI providers.' },
+ })
+ }
+ return provider
+}
+
+async function assertHasCredits({ platformId, log }: { platformId: string, log: FastifyBaseLogger }): Promise<void> {
+ const { error } = await tryCatch(() => assertCreditsAndAppSumoNotExceeded({ platformId, log }))
+ if (isNil(error)) {
+ return
+ }
+ const details = error instanceof ActivepiecesError ? error.error : undefined
+ if (isNil(details) || details.code !== ErrorCode.QUOTA_EXCEEDED) {
+ log.warn({ error, platform: { id: platformId } }, '[aiRouterService] Credits check failed, allowing the call')
+ return
+ }
+ throw new ActivepiecesError({
+ code: ErrorCode.QUOTA_EXCEEDED,
+ params: { ...details.params, message: OUT_OF_CREDITS_MESSAGE },
+ })
+}
+
+const ROUTER_PROVIDERS = [AIProviderName.ACTIVEPIECES, AIProviderName.OPENROUTER] as const
+const AI_ROUTER_MODEL_ID = 'typesafe/jev-1.13'
+const WAIT_MS = 25_000
+const OUT_OF_CREDITS_MESSAGE = 'The AI Router did not run because the platform is out of AI credits. Add credits or upgrade the plan, then retry the run.'
+
+type ChooseParams = Omit<ChooseAiRouteRequest, 'waitpointId'> & {
+ platformId: string
+ projectId: string
+}
+
+type StartParams = ChooseParams & {
+ waitpointId: string
+}
+
+type RouteJobParams = {
+ request: Omit<ChooseAiRouteRequest, 'waitpointId'>
+ requestId: string
+ platformId: string
+ projectId: string
+ provider: AIProviderName
+ waitpointId?: string
+ webserverId?: string
+}
diff --git a/packages/server/api/src/app/ee/projects/project-release/project-state/clean-flow-state.ts b/packages/server/api/src/app/ee/projects/project-release/project-state/clean-flow-state.ts
index a79f8e7ce86..9002734fb58 100644
--- a/packages/server/api/src/app/ee/projects/project-release/project-state/clean-flow-state.ts
+++ b/packages/server/api/src/app/ee/projects/project-release/project-state/clean-flow-state.ts
@@ -82,6 +82,11 @@ function cleanAction(action: FlowAction): FlowAction {
...commonProps, type: action.type, settings: action.settings, nextAction,
children: action.children.map((child) => isNil(child) ? null : cleanAction(child)),
}
+ case FlowActionType.AI_ROUTER:
+ return {
+ ...commonProps, type: action.type, settings: action.settings, nextAction,
+ children: action.children.map((child) => isNil(child) ? null : cleanAction(child)),
+ }
}
}
diff --git a/packages/server/api/src/app/flows/flow-version/flow-version-validator-util.ts b/packages/server/api/src/app/flows/flow-version/flow-version-validator-util.ts
index 39f7e3be63e..08c7530708c 100644
--- a/packages/server/api/src/app/flows/flow-version/flow-version-validator-util.ts
+++ b/packages/server/api/src/app/flows/flow-version/flow-version-validator-util.ts
@@ -4,7 +4,7 @@ import {
piecePropertiesUtils,
PiecePropertyMap,
} from '@activepieces/pieces-framework'
-import { CodeActionSettings, FlowActionType, FlowOperationRequest, FlowOperationType, flowPieceUtil, flowStructureUtil, FlowTrigger, FlowTriggerType, LoopOnItemsActionSettings, PieceActionSettings, PieceTriggerSettings, RouterActionSettingsWithValidation, SourceCode } from '@activepieces/shared'
+import { AiRouterActionSettingsWithValidation, CodeActionSettings, FlowActionType, FlowOperationRequest, FlowOperationType, flowPieceUtil, flowStructureUtil, FlowTrigger, FlowTriggerType, LoopOnItemsActionSettings, PieceActionSettings, PieceTriggerSettings, RouterActionSettingsWithValidation, SourceCode } from '@activepieces/shared'
import { FastifyBaseLogger } from 'fastify'
import { z } from 'zod'
import { pieceMetadataService } from '../../pieces/metadata/piece-metadata-service'
@@ -13,6 +13,7 @@ const loopSettingsValidator = LoopOnItemsActionSettings.and(z.object({
items: z.string().min(1),
}))
const routerSettingsValidator = RouterActionSettingsWithValidation
+const aiRouterSettingsValidator = AiRouterActionSettingsWithValidation
const codeSettingsValidator = CodeActionSettings.and(z.object({
sourceCode: SourceCode.and(z.object({
code: z.string().min(1),
@@ -53,6 +54,11 @@ export const flowVersionValidationUtil = (log: FastifyBaseLogger) => ({
clonedRequest.request.action.settings,
).success
break
+ case FlowActionType.AI_ROUTER:
+ clonedRequest.request.action.valid = aiRouterSettingsValidator.safeParse(
+ clonedRequest.request.action.settings,
+ ).success
+ break
case FlowActionType.CODE:
clonedRequest.request.action.valid = codeSettingsValidator.safeParse(
clonedRequest.request.action.settings,
@@ -83,6 +89,11 @@ export const flowVersionValidationUtil = (log: FastifyBaseLogger) => ({
clonedRequest.request.settings,
).success
break
+ case FlowActionType.AI_ROUTER:
+ clonedRequest.request.valid = aiRouterSettingsValidator.safeParse(
+ clonedRequest.request.settings,
+ ).success
+ break
case FlowActionType.CODE:
clonedRequest.request.valid = codeSettingsValidator.safeParse(
clonedRequest.request.settings,
diff --git a/packages/server/api/src/app/mcp/tools/ap-add-branch.ts b/packages/server/api/src/app/mcp/tools/ap-add-branch.ts
index 1136c7a42b4..d03c2cbd1c5 100644
--- a/packages/server/api/src/app/mcp/tools/ap-add-branch.ts
+++ b/packages/server/api/src/app/mcp/tools/ap-add-branch.ts
@@ -1,5 +1,5 @@
import { isNil, Permission } from '@activepieces/core-utils'
-import { BranchCondition, FlowOperationRequest, FlowOperationType, McpToolContext, McpToolDefinition } from '@activepieces/shared'
+import { BranchCondition, FlowActionType, FlowOperationRequest, FlowOperationType, McpToolContext, McpToolDefinition } from '@activepieces/shared'
import { FastifyBaseLogger } from 'fastify'
import { z } from 'zod'
import { flowService } from '../../flows/flow/flow.service'
@@ -44,8 +44,11 @@ export const apAddBranchTool = ({ mcp, userId }: McpToolContext, log: FastifyBas
return resolved.error
}
const routerStep = resolved.routerStep
+ if (routerStep.type === FlowActionType.AI_ROUTER) {
+ return { content: [{ type: 'text', text: `❌ "${routerStepName}" is an AI Router. Its routes have descriptions, not conditions, and can only be edited in the builder for now.` }] }
+ }
- const routerSettings = (routerStep as { settings: { branches: unknown[] } }).settings
+ const routerSettings = routerStep.settings
// Insert before the last (fallback) branch
const branchIndex = Math.max(0, routerSettings.branches.length - 1)
diff --git a/packages/server/api/src/app/mcp/tools/ap-delete-branch.ts b/packages/server/api/src/app/mcp/tools/ap-delete-branch.ts
index c23636266c7..03cd0638e08 100644
--- a/packages/server/api/src/app/mcp/tools/ap-delete-branch.ts
+++ b/packages/server/api/src/app/mcp/tools/ap-delete-branch.ts
@@ -41,7 +41,7 @@ export const apDeleteBranchTool = ({ mcp, userId }: McpToolContext, log: Fastify
}
const routerStep = resolved.routerStep
- const branches = (routerStep as { settings: { branches: unknown[] } }).settings.branches
+ const branches = routerStep.settings.branches
if (branchIndex < 0 || branchIndex >= branches.length) {
return {
content: [{
diff --git a/packages/server/api/src/app/mcp/tools/ap-flow-structure.ts b/packages/server/api/src/app/mcp/tools/ap-flow-structure.ts
index f28faa18cb0..323751f3919 100644
--- a/packages/server/api/src/app/mcp/tools/ap-flow-structure.ts
+++ b/packages/server/api/src/app/mcp/tools/ap-flow-structure.ts
@@ -36,6 +36,8 @@ function getConfigStatus(step: Step): string {
return 'invalid (loopItems expression missing or invalid)'
case FlowActionType.ROUTER:
return 'invalid (check branch conditions)'
+ case FlowActionType.AI_ROUTER:
+ return 'invalid (check the input, question and route descriptions)'
default:
return 'invalid'
}
@@ -143,14 +145,13 @@ function buildFlowStructure(trigger: Step): { structure: StepInfo[], stepByName:
relationship = 'first_loop_action'
break
}
- if (parent.type === FlowActionType.ROUTER) {
- const children = (parent as { children?: { name: string }[] }).children
- const idx = children?.findIndex((c) => c?.name === step.name)
- if (idx !== undefined && idx >= 0) {
+ if (flowStructureUtil.isBranchedAction(parent)) {
+ const idx = parent.children.findIndex((c) => c?.name === step.name)
+ if (idx >= 0) {
parentName = parent.name
relationship = 'branch'
branchIndex = idx
- branchName = (parent as { settings?: { branches?: { branchName?: string }[] } }).settings?.branches?.[idx]?.branchName
+ branchName = parent.settings.branches[idx]?.branchName
break
}
}
@@ -244,6 +245,14 @@ function formatFlowStructure(
}
})
}
+ if (fullStep?.type === FlowActionType.AI_ROUTER) {
+ lines.push(` question: "${fullStep.settings.question}"`)
+ fullStep.settings.branches.forEach((b, i) => {
+ const btype = b.branchType === BranchExecutionType.FALLBACK ? 'fallback' : 'route'
+ const when = isNil(b.description) || b.description.length === 0 ? '' : ` | when: ${b.description}`
+ lines.push(` branch[${i}]: "${b.branchName}" (${btype})${when}`)
+ })
+ }
}
lines.push('')
@@ -262,10 +271,9 @@ function formatFlowStructure(
if (step.type === FlowActionType.LOOP_ON_ITEMS) {
lines.push(` Inside loop of "${step.name}": parentStepName="${step.name}", stepLocationRelativeToParent="${StepLocationRelativeToParent.INSIDE_LOOP}"`)
}
- if (step.type === FlowActionType.ROUTER) {
- const routerStep = stepByName.get(step.name)
- const branches = (routerStep?.settings as { branches?: { branchName?: string }[] } | undefined)?.branches ?? []
- branches.forEach((b, i) => {
+ const branchedStep = stepByName.get(step.name)
+ if (!isNil(branchedStep) && flowStructureUtil.isBranchedAction(branchedStep)) {
+ branchedStep.settings.branches.forEach((b, i) => {
lines.push(` Branch ${i} of "${step.name}"${b.branchName ? ` ("${b.branchName}")` : ''}: parentStepName="${step.name}", stepLocationRelativeToParent="${StepLocationRelativeToParent.INSIDE_BRANCH}", branchIndex=${i}`)
})
}
diff --git a/packages/server/api/src/app/mcp/tools/ap-update-branch.ts b/packages/server/api/src/app/mcp/tools/ap-update-branch.ts
index 31a8523b5dc..c135a44d69a 100644
--- a/packages/server/api/src/app/mcp/tools/ap-update-branch.ts
+++ b/packages/server/api/src/app/mcp/tools/ap-update-branch.ts
@@ -49,6 +49,9 @@ export const apUpdateBranchTool = ({ mcp, userId }: McpToolContext, log: Fastify
return resolved.error
}
const routerStep = resolved.routerStep
+ if (routerStep.type === FlowActionType.AI_ROUTER) {
+ return { content: [{ type: 'text', text: `❌ "${routerStepName}" is an AI Router. Its routes have descriptions, not conditions, and can only be edited in the builder for now.` }] }
+ }
const branches = [...routerStep.settings.branches]
diff --git a/packages/server/api/src/app/mcp/tools/ap-validate-flow.ts b/packages/server/api/src/app/mcp/tools/ap-validate-flow.ts
index 88c86eb1f8f..76b92308f24 100644
--- a/packages/server/api/src/app/mcp/tools/ap-validate-flow.ts
+++ b/packages/server/api/src/app/mcp/tools/ap-validate-flow.ts
@@ -1,5 +1,5 @@
import { isNil, Permission } from '@activepieces/core-utils'
-import { BranchExecutionType, FlowActionType, flowStructureUtil, FlowTriggerType, McpToolDefinition, ProjectScopedMcpServer, Step } from '@activepieces/shared'
+import { BranchExecutionType, flowStructureUtil, FlowTriggerType, McpToolDefinition, ProjectScopedMcpServer, Step } from '@activepieces/shared'
import { FastifyBaseLogger } from 'fastify'
import { z } from 'zod'
import { flowService } from '../../flows/flow/flow.service'
@@ -91,7 +91,7 @@ function validateFlow({ trigger }: { trigger: Step }): ValidationResult {
}
}
- if (step.type === FlowActionType.ROUTER) {
+ if (flowStructureUtil.isBranchedAction(step)) {
const { children, settings } = step
const branches = settings.branches ?? []
for (let i = 0; i < children.length; i++) {
diff --git a/packages/server/api/src/app/mcp/tools/mcp-utils.ts b/packages/server/api/src/app/mcp/tools/mcp-utils.ts
index fbccbaf70fc..837f16c896b 100644
--- a/packages/server/api/src/app/mcp/tools/mcp-utils.ts
+++ b/packages/server/api/src/app/mcp/tools/mcp-utils.ts
@@ -1,7 +1,7 @@
import { isNil, isObject, tryCatch } from '@activepieces/core-utils'
import { AiMetadata, OutputSchema, OutputSchemaField, PieceMetadataModel, PiecePropertyMap, PropertyType } from '@activepieces/pieces-framework'
-import { BranchOperator, EngineResponse, EngineResponseStatus, FlowActionType, flowStructureUtil, McpServerType, McpToolResult, ProjectScopedMcpServer, singleValueConditions, WorkerJobType } from '@activepieces/shared'
-import type { RouterAction, Step } from '@activepieces/shared'
+import { BranchOperator, EngineResponse, EngineResponseStatus, flowStructureUtil, McpServerType, McpToolResult, ProjectScopedMcpServer, singleValueConditions, WorkerJobType } from '@activepieces/shared'
+import type { BranchedAction, Step } from '@activepieces/shared'
import { FastifyBaseLogger } from 'fastify'
import { z } from 'zod'
import { expressionRewriter } from '../../flows/flow-version/migrations/expression-rewriter'
@@ -469,16 +469,16 @@ function truncate(str: string, max: number): string {
function resolveRouterStep({ stepName, trigger }: { stepName: string, trigger: Step }): ResolveRouterStepResult {
const step = flowStructureUtil.getStep(stepName, trigger)
- if (isNil(step) || step.type !== FlowActionType.ROUTER) {
+ if (isNil(step) || !flowStructureUtil.isBranchedAction(step)) {
const routers = flowStructureUtil.getAllSteps(trigger)
- .filter(s => s.type === FlowActionType.ROUTER)
+ .filter(flowStructureUtil.isBranchedAction)
.map(s => s.name)
.join(', ')
return {
- error: { content: [{ type: 'text', text: `❌ Step "${stepName}" is not a ROUTER step. Available routers: ${routers || 'none'}` }] },
+ error: { content: [{ type: 'text', text: `❌ Step "${stepName}" is not a ROUTER or AI_ROUTER step. Available routers: ${routers || 'none'}` }] },
}
}
- return { routerStep: step as RouterAction }
+ return { routerStep: step }
}
function routerInvalidWarning({ stepName, trigger }: { stepName: string, trigger: Step }): string {
@@ -882,7 +882,7 @@ type LookupPieceComponentResult =
| { error: McpToolResult, piece?: never, component?: never, pieceName?: never }
type ResolveRouterStepResult =
- | { routerStep: RouterAction, error?: never }
+ | { routerStep: BranchedAction, error?: never }
| { error: McpToolResult, routerStep?: never }
type ResolveLatestPieceVersionResult =
diff --git a/packages/server/api/src/app/workers/engine-controller.ts b/packages/server/api/src/app/workers/engine-controller.ts
index e8ce056c58a..b5272a6420b 100644
--- a/packages/server/api/src/app/workers/engine-controller.ts
+++ b/packages/server/api/src/app/workers/engine-controller.ts
@@ -1,8 +1,10 @@
-import { FileType, FlowVersion, GetFlowVersionForWorkerRequest, ListFlowsRequest, PrincipalType, SendFlowResponseRequest, UpdateStepProgressRequest, UploadRunLogsRequest } from '@activepieces/shared'
+import { ActivepiecesError, ErrorCode, isNil } from '@activepieces/core-utils'
+import { ChooseAiRouteRequest, ChooseAiRouteResponse, FileType, FlowVersion, GetFlowVersionForWorkerRequest, ListFlowsRequest, PrincipalType, SendFlowResponseRequest, StartAiRouteResponse, UpdateStepProgressRequest, UploadRunLogsRequest } from '@activepieces/shared'
import { FastifyPluginAsyncZod } from 'fastify-type-provider-zod'
import { StatusCodes } from 'http-status-codes'
import { z } from 'zod'
+import { aiRouterService } from '../ai/ai-router.service'
import { entitiesMustBeOwnedByCurrentProject } from '../authentication/authorization'
import { securityAccess } from '../core/security/authorization/fastify-security'
import { fileService } from '../file/file.service'
@@ -100,6 +102,22 @@ export const flowEngineWorker: FastifyPluginAsyncZod = async (app) => {
return reply.status(StatusCodes.OK).send()
})
+ app.post('/ai-router', AiRouterRequest, async (request, reply) => {
+ if (request.principal.type !== PrincipalType.ENGINE) {
+ throw new ActivepiecesError({
+ code: ErrorCode.AUTHORIZATION,
+ params: { message: 'Only a running flow can ask the AI Router' },
+ })
+ }
+ const { waitpointId, ...body } = request.body
+ const params = { ...body, platformId: request.principal.platform.id, projectId: request.principal.projectId }
+ if (!isNil(waitpointId)) {
+ const started = await aiRouterService(request.log).start({ ...params, waitpointId })
+ return reply.status(StatusCodes.ACCEPTED).send(started)
+ }
+ return aiRouterService(request.log).choose(params)
+ })
+
}
@@ -171,4 +189,17 @@ const FlowResponseRequest = {
schema: {
body: SendFlowResponseRequest,
},
-}
\ No newline at end of file
+}
+
+const AiRouterRequest = {
+ config: {
+ security: securityAccess.engine(),
+ },
+ schema: {
+ body: ChooseAiRouteRequest,
+ response: {
+ [StatusCodes.OK]: ChooseAiRouteResponse,
+ [StatusCodes.ACCEPTED]: StartAiRouteResponse,
+ },
+ },
+}
diff --git a/packages/server/api/test/unit/app/ai/ai-router.service.test.ts b/packages/server/api/test/unit/app/ai/ai-router.service.test.ts
new file mode 100644
index 00000000000..67dd20f6146
--- /dev/null
+++ b/packages/server/api/test/unit/app/ai/ai-router.service.test.ts
@@ -0,0 +1,141 @@
+import { ActivepiecesError, AIProviderName, ErrorCode, PlatformUsageMetric } from '@activepieces/core-utils'
+import { AiRouterMatchMode, AiStepAction } from '@activepieces/shared'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { enqueue, waitForAnswer, listForProject, assertCredits } = vi.hoisted(() => ({
+ enqueue: vi.fn(),
+ waitForAnswer: vi.fn(),
+ listForProject: vi.fn(),
+ assertCredits: vi.fn(),
+}))
+
+vi.mock('../../../../src/app/ai/ai-execution', () => ({
+ aiExecution: () => ({ serverId: () => 'server-1', enqueue, waitForAnswer }),
+}))
+
+vi.mock('../../../../src/app/ai/ai-provider-service', () => ({
+ aiProviderService: () => ({ listForProject }),
+}))
+
+vi.mock('../../../../src/app/platform/billing-provider', () => ({
+ assertCreditsAndAppSumoNotExceeded: assertCredits,
+}))
+
+const { aiRouterService } = await import('../../../../src/app/ai/ai-router.service')
+
+const log = { info: vi.fn(), warn: vi.fn() }
+const service = () => aiRouterService(log as never)
+
+const REQUEST = {
+ platformId: 'platform-1',
+ projectId: 'project-1',
+ flowId: 'flow-1',
+ flowRunId: 'run-1',
+ state: 'charged twice',
+ question: 'Which team?',
+ options: { Billing: 'Payments', Technical: 'Bugs' },
+ matchMode: AiRouterMatchMode.BEST_MATCH,
+}
+
+const OUT_OF_CREDITS = new ActivepiecesError({ code: ErrorCode.QUOTA_EXCEEDED, params: { metric: PlatformUsageMetric.CREDITS } })
+
+function provider(name: AIProviderName) {
+ return { provider: name, name, enabledForChat: false, keys: [] }
+}
+
+beforeEach(() => {
+ vi.clearAllMocks()
+ listForProject.mockResolvedValue([provider(AIProviderName.OPENROUTER), provider(AIProviderName.ACTIVEPIECES)])
+ assertCredits.mockResolvedValue(undefined)
+ enqueue.mockResolvedValue(undefined)
+ waitForAnswer.mockResolvedValue({ output: { matched: ['Billing'], probabilities: { Billing: 0.9, Technical: 0.1 } } })
+})
+
+describe('aiRouterService runs the decision as a worker AI job', () => {
+ it('enqueues a route job on the managed provider and returns the worker\'s answer', async () => {
+ const answer = await service().choose(REQUEST)
+
+ expect(enqueue).toHaveBeenCalledTimes(1)
+ expect(enqueue.mock.calls[0][0]).toMatchObject({
+ action: AiStepAction.ROUTE,
+ provider: AIProviderName.ACTIVEPIECES,
+ modelId: 'typesafe/jev-1.13',
+ webserverId: 'server-1',
+ platformId: 'platform-1',
+ projectId: 'project-1',
+ flowId: 'flow-1',
+ flowRunId: 'run-1',
+ state: 'charged twice',
+ question: 'Which team?',
+ options: { Billing: 'Payments', Technical: 'Bugs' },
+ matchMode: AiRouterMatchMode.BEST_MATCH,
+ })
+ expect(waitForAnswer.mock.calls[0][0].requestId).toBe(enqueue.mock.calls[0][0].requestId)
+ expect(answer).toEqual({ matched: ['Billing'], probabilities: { Billing: 0.9, Technical: 0.1 } })
+ })
+
+ it('starts listening for the answer before the job is enqueued, so a fast worker cannot answer into the void', async () => {
+ await service().choose(REQUEST)
+
+ expect(waitForAnswer.mock.invocationCallOrder[0]).toBeLessThan(enqueue.mock.invocationCallOrder[0])
+ })
+
+ it('falls back to the platform\'s own OpenRouter key when the managed provider is absent', async () => {
+ listForProject.mockResolvedValue([provider(AIProviderName.OPENROUTER), provider(AIProviderName.OPENAI)])
+
+ await service().choose(REQUEST)
+
+ expect(enqueue.mock.calls[0][0]).toMatchObject({ provider: AIProviderName.OPENROUTER })
+ })
+
+ it('refuses with a setup message when no OpenRouter-capable key exists, and enqueues nothing', async () => {
+ listForProject.mockResolvedValue([provider(AIProviderName.OPENAI)])
+
+ await expect(service().choose(REQUEST)).rejects.toMatchObject({ error: { code: ErrorCode.FEATURE_DISABLED, params: { message: expect.stringContaining('OpenRouter') } } })
+ expect(enqueue).not.toHaveBeenCalled()
+ })
+
+ it('refuses with a credits message when the platform is definitely out of credits', async () => {
+ assertCredits.mockRejectedValue(OUT_OF_CREDITS)
+
+ await expect(service().choose(REQUEST)).rejects.toMatchObject({ error: { code: ErrorCode.QUOTA_EXCEEDED, params: { message: expect.stringContaining('out of AI credits') } } })
+ expect(enqueue).not.toHaveBeenCalled()
+ })
+
+ it('lets the call through when the credits lookup itself fails', async () => {
+ assertCredits.mockRejectedValue(new Error('autumn is down'))
+
+ await service().choose(REQUEST)
+
+ expect(enqueue).toHaveBeenCalledTimes(1)
+ expect(log.warn).toHaveBeenCalled()
+ })
+
+ it('turns the worker\'s failure text into the error the engine shows', async () => {
+ waitForAnswer.mockResolvedValue({ failure: 'The routing model did not answer: HTTP 402: Insufficient credits' })
+
+ await expect(service().choose(REQUEST)).rejects.toMatchObject({ error: { code: ErrorCode.ENGINE_OPERATION_FAILURE, params: { message: 'The routing model did not answer: HTTP 402: Insufficient credits' } } })
+ })
+
+ it('starts a decision for a paused step without waiting, carrying the waitpoint', async () => {
+ const started = await service().start({ ...REQUEST, waitpointId: 'wp-1' })
+
+ expect(waitForAnswer).not.toHaveBeenCalled()
+ expect(enqueue.mock.calls[0][0]).toMatchObject({ action: AiStepAction.ROUTE, waitpointId: 'wp-1', provider: AIProviderName.ACTIVEPIECES, flowRunId: 'run-1' })
+ expect(enqueue.mock.calls[0][0].webserverId).toBeUndefined()
+ expect(started.requestId).toBe(enqueue.mock.calls[0][0].requestId)
+ })
+
+ it('gates credits before starting a paused decision too', async () => {
+ assertCredits.mockRejectedValue(OUT_OF_CREDITS)
+
+ await expect(service().start({ ...REQUEST, waitpointId: 'wp-1' })).rejects.toMatchObject({ error: { code: ErrorCode.QUOTA_EXCEEDED } })
+ expect(enqueue).not.toHaveBeenCalled()
+ })
+
+ it('fails when the worker answered in a shape the engine cannot read', async () => {
+ waitForAnswer.mockResolvedValue({ output: { chosen: 'Billing' } })
+
+ await expect(service().choose(REQUEST)).rejects.toMatchObject({ error: { code: ErrorCode.ENGINE_OPERATION_FAILURE } })
+ })
+})
diff --git a/packages/server/api/test/unit/app/mcp/mcp-utils.test.ts b/packages/server/api/test/unit/app/mcp/mcp-utils.test.ts
index e7adebc2fd9..a8b3e025cd5 100644
--- a/packages/server/api/test/unit/app/mcp/mcp-utils.test.ts
+++ b/packages/server/api/test/unit/app/mcp/mcp-utils.test.ts
@@ -1,4 +1,5 @@
import { PropertyType } from '@activepieces/pieces-framework'
+import { AiRouterAction, BranchExecutionType, EmptyTrigger, FlowActionType, FlowTriggerType } from '@activepieces/shared'
import { describe, expect, it } from 'vitest'
import { mcpUtils } from '../../../../src/app/mcp/tools/mcp-utils'
@@ -466,3 +467,44 @@ describe('mcpUtils.buildExampleInput — runnable, sentinel-free once resolved',
expect(example.fields).toEqual({ name: '<Name>' })
})
})
+
+describe('mcpUtils.resolveRouterStep', () => {
+ const aiRouter: AiRouterAction = {
+ name: 'ai_router',
+ displayName: 'AI Router',
+ type: FlowActionType.AI_ROUTER,
+ valid: true,
+ lastUpdatedDate: '2026-09-23T00:00:00.000Z',
+ settings: {
+ text: '{{trigger.body}}',
+ question: 'Which team?',
+ branches: [
+ { branchType: BranchExecutionType.CONDITION, branchName: 'Billing', description: 'Payments' },
+ { branchType: BranchExecutionType.FALLBACK, branchName: 'Otherwise', description: 'Anything else' },
+ ],
+ },
+ children: [null, null],
+ }
+ const trigger: EmptyTrigger = {
+ name: 'trigger',
+ displayName: 'Trigger',
+ type: FlowTriggerType.EMPTY,
+ valid: false,
+ lastUpdatedDate: '2026-09-23T00:00:00.000Z',
+ settings: {},
+ nextAction: aiRouter,
+ }
+
+ it('resolves an AI router as a branched step', () => {
+ const resolved = mcpUtils.resolveRouterStep({ stepName: 'ai_router', trigger })
+ expect(resolved.routerStep?.name).toBe('ai_router')
+ })
+
+ it('names both router kinds and lists the AI router when the step is not one', () => {
+ const resolved = mcpUtils.resolveRouterStep({ stepName: 'trigger', trigger })
+ const text = resolved.error?.content[0]
+ expect(text).toMatchObject({ type: 'text' })
+ expect(text && 'text' in text ? text.text : '').toContain('ROUTER or AI_ROUTER')
+ expect(text && 'text' in text ? text.text : '').toContain('ai_router')
+ })
+})
diff --git a/packages/server/engine/CLAUDE.md b/packages/server/engine/CLAUDE.md
index 0c4eb44445a..4bab93bfb9c 100644
--- a/packages/server/engine/CLAUDE.md
+++ b/packages/server/engine/CLAUDE.md
@@ -3,7 +3,7 @@
## Error Handling
- **Always throw `ExecutionError` subclasses** (from `@activepieces/shared`) instead of plain `Error`. The engine uses `tryCatchAndThrowOnEngineError` which only propagates errors of type `ExecutionErrorType.ENGINE` — plain `Error` instances are silently swallowed and treated as user-level failures.
-- Use `EngineGenericError` for engine-level failures (e.g., failed API calls to the server).
+- Use `EngineGenericError` for engine-level failures — but **only when the failure means the engine or its own infrastructure is broken**, because `tryCatchAndThrowOnEngineError` *rethrows* ENGINE errors instead of returning them. An executor that wraps an API client in it and then branches on the returned `error` has written dead code: the run dies with `INTERNAL_ERROR` and pages oncall, and the executor's `failStep` never runs. A call that proxies a third-party service (the AI router's gateway) fails for reasons that are not our bug, so it throws a USER-level `ExecutionError` and the step goes FAILED.
- Use the existing specific error classes (`ConnectionNotFoundError`, `StorageLimitError`, `PausedFlowTimeoutError`, etc.) when applicable.
## USER vs ENGINE errors during input resolution
diff --git a/packages/server/engine/src/lib/api/ai-router-api.ts b/packages/server/engine/src/lib/api/ai-router-api.ts
new file mode 100644
index 00000000000..b93150c46dc
--- /dev/null
+++ b/packages/server/engine/src/lib/api/ai-router-api.ts
@@ -0,0 +1,70 @@
+import { AiRouterEvaluationError, AiRouterMatchMode, ChooseAiRouteResponse, tryCatch } from '@activepieces/shared'
+import { z } from 'zod'
+
+const TIMEOUT_MS = 30_000
+
+export const aiRouterApi = {
+ async choose(params: ChooseParams): Promise<ChooseAiRouteResponse> {
+ const { response, url, startedAt } = await post({ apiUrl: params.apiUrl, engineToken: params.engineToken, body: bodyOf(params) })
+ const parsed = ChooseAiRouteResponse.safeParse(await response.json())
+ if (!parsed.success) {
+ throw new AiRouterEvaluationError({ message: `${url} answered with an unexpected body after ${Date.now() - startedAt} ms` })
+ }
+ return parsed.data
+ },
+ async start({ waitpointId, ...params }: StartParams): Promise<void> {
+ await post({ apiUrl: params.apiUrl, engineToken: params.engineToken, body: { ...bodyOf(params), waitpointId } })
+ },
+}
+
+function bodyOf({ state, question, options, matchMode, flowId, flowRunId }: ChooseParams): Record<string, unknown> {
+ return { state, question, options, matchMode, flowId, flowRunId }
+}
+
+async function post({ apiUrl, engineToken, body }: { apiUrl: string, engineToken: string, body: Record<string, unknown> }): Promise<{ response: Response, url: string, startedAt: number }> {
+ const url = `${apiUrl}v1/engine/ai-router`
+ const startedAt = Date.now()
+ const response = await global.fetch(url, {
+ method: 'POST',
+ headers: {
+ 'Content-Type': 'application/json',
+ Authorization: `Bearer ${engineToken}`,
+ },
+ body: JSON.stringify(body),
+ signal: AbortSignal.timeout(TIMEOUT_MS),
+ }).catch((error: unknown) => {
+ const timedOut = error instanceof Error && error.name === 'TimeoutError'
+ const reason = timedOut
+ ? `did not answer within ${TIMEOUT_MS} ms`
+ : `could not be reached (${String(error)})`
+ throw new AiRouterEvaluationError({ message: `${url} ${reason} after ${Date.now() - startedAt} ms`, cause: error })
+ })
+ if (!response.ok) {
+ const reason = await apiErrorReason(response)
+ throw new AiRouterEvaluationError({ message: `${url} answered ${response.status} after ${Date.now() - startedAt} ms${reason}` })
+ }
+ return { response, url, startedAt }
+}
+
+async function apiErrorReason(response: Response): Promise<string> {
+ const { data } = await tryCatch(() => response.json())
+ const parsed = ApiErrorBody.safeParse(data)
+ return parsed.success ? `: ${parsed.data.params.message}` : ''
+}
+
+const ApiErrorBody = z.object({ params: z.object({ message: z.string() }) })
+
+type ChooseParams = {
+ apiUrl: string
+ engineToken: string
+ state: string
+ question: string
+ options: Record<string, string>
+ matchMode: AiRouterMatchMode
+ flowId: string
+ flowRunId: string
+}
+
+type StartParams = ChooseParams & {
+ waitpointId: string
+}
diff --git a/packages/server/engine/src/lib/handler/ai-router-executor.ts b/packages/server/engine/src/lib/handler/ai-router-executor.ts
new file mode 100644
index 00000000000..441419fa806
--- /dev/null
+++ b/packages/server/engine/src/lib/handler/ai-router-executor.ts
@@ -0,0 +1,258 @@
+import { isNil, spreadIfDefined } from '@activepieces/core-utils'
+import { LATEST_CONTEXT_VERSION } from '@activepieces/pieces-framework'
+import { AI_ROUTER_MAX_STATE_LENGTH, AiRouterAction, AiRouterActionSettings, AiRouterEvaluationError, AiRouterMatchMode, AiRouterStepOutput, BranchExecutionType, ChooseAiRouteResponse, FlowActionType, FlowRunStatus, ResumePayload, StepOutputStatus } from '@activepieces/shared'
+import { z } from 'zod'
+import { aiRouterApi } from '../api/ai-router-api'
+import { waitpointClient } from '../piece-context/waitpoint-client'
+import { utils } from '../utils'
+import { BaseExecutor, failStep } from './base-executor'
+import { executeBranches } from './branch-execution'
+import { EngineConstants } from './context/engine-constants'
+import { FlowExecutorContext } from './context/flow-execution-context'
+
+export const aiRouterExecuter: BaseExecutor<AiRouterAction> = {
+ async handle({
+ action,
+ executionState,
+ constants,
+ }) {
+ const stepStartTime = performance.now()
+ const stored = executionState.getStepOutput(action.name)
+ if (stored?.type === FlowActionType.AI_ROUTER && stored.status === StepOutputStatus.SUCCEEDED && !isNil(stored.output)) {
+ return executeBranches({
+ action,
+ executionState,
+ constants,
+ stepOutput: AiRouterStepOutput.init({ input: stored.input }).setOutput(stored.output),
+ evaluations: stored.output.branches.map((branch) => branch.evaluation),
+ stopAfterFirstMatch: false,
+ })
+ }
+ const resuming = stored?.status === StepOutputStatus.PAUSED
+
+ const { data: resolved, error: resolveError } = await utils.tryCatchAndThrowOnEngineError(() =>
+ constants.getPropsResolver({ contextVersion: LATEST_CONTEXT_VERSION }).resolve<AiRouterActionSettings>({
+ unresolvedInput: {
+ ...action.settings,
+ },
+ executionState,
+ }),
+ )
+ if (resolveError) {
+ return failStep({
+ action,
+ executionState,
+ stepOutput: AiRouterStepOutput.init({ input: {} }),
+ error: resolveError,
+ durationMs: performance.now() - stepStartTime,
+ })
+ }
+ const { censoredInput, resolvedInput } = resolved
+ const matchMode = resolvedInput.matchMode ?? AiRouterMatchMode.BEST_MATCH
+ const bestMatch = matchMode === AiRouterMatchMode.BEST_MATCH
+ const options = toOptions(askableBranches({ branches: resolvedInput.branches, bestMatch }))
+ const request = {
+ apiUrl: constants.internalApiUrl,
+ engineToken: constants.engineToken,
+ state: truncate(asPlainText(resolvedInput.text)),
+ question: asPlainText(resolvedInput.question),
+ options,
+ matchMode,
+ flowId: constants.flowId,
+ flowRunId: constants.flowRunId,
+ }
+ const nothingToAsk = Object.keys(options).length === 0
+
+ if (!resuming && !nothingToAsk && canPause(constants)) {
+ const { data: paused, error: pauseError } = await utils.tryCatchAndThrowOnEngineError(() =>
+ pauseForAnswer({ action, executionState, constants, censoredInput, request }),
+ )
+ if (pauseError) {
+ return failStep({
+ action,
+ executionState,
+ stepOutput: AiRouterStepOutput.init({ input: censoredInput }),
+ error: pauseError,
+ durationMs: performance.now() - stepStartTime,
+ })
+ }
+ return paused
+ }
+
+ const { data: answer, error: answerError } = await utils.tryCatchAndThrowOnEngineError(() => {
+ if (nothingToAsk) {
+ return Promise.resolve<ChooseAiRouteResponse>({ matched: [] })
+ }
+ if (resuming) {
+ return Promise.resolve(answerFromResume(constants.resumePayload))
+ }
+ return aiRouterApi.choose(request)
+ })
+ if (answerError) {
+ return failStep({
+ action,
+ executionState,
+ stepOutput: AiRouterStepOutput.init({ input: censoredInput }),
+ error: answerError,
+ durationMs: performance.now() - stepStartTime,
+ })
+ }
+
+ const confident = confidentRoutes({ answer, minConfidence: resolvedInput.minConfidence, bestMatch })
+ const evaluations = bestMatch
+ ? bestMatchEvaluations({ branches: resolvedInput.branches, confident })
+ : allMatchesEvaluations({ branches: resolvedInput.branches, confident })
+
+ const stepOutput = AiRouterStepOutput.init({
+ input: censoredInput,
+ }).setOutput({
+ branches: resolvedInput.branches.map((branch, index) => ({
+ branchName: branch.branchName,
+ branchIndex: index + 1,
+ evaluation: evaluations[index],
+ })),
+ ...spreadIfDefined('choice', bestMatch ? chosenName({ branches: resolvedInput.branches, evaluations }) : undefined),
+ ...spreadIfDefined('probabilities', answer.probabilities),
+ }).setDuration(performance.now() - stepStartTime)
+
+ return executeBranches({
+ action,
+ executionState,
+ constants,
+ stepOutput,
+ evaluations,
+ stopAfterFirstMatch: bestMatch,
+ })
+ },
+}
+
+async function pauseForAnswer({ action, executionState, constants, censoredInput, request }: PauseForAnswerParams): Promise<FlowExecutorContext> {
+ const waitpoint = await waitpointClient.create({
+ apiUrl: constants.internalApiUrl,
+ engineToken: constants.engineToken,
+ flowRunId: constants.flowRunId,
+ projectId: constants.projectId,
+ stepName: executionState.currentPath.waitpointKeyFor({ stepName: action.name }),
+ type: 'WEBHOOK',
+ version: 'V1',
+ resumeDateTime: new Date(Date.now() + ANSWER_BACKSTOP_MS).toISOString(),
+ workerHandlerId: constants.workerHandlerId ?? undefined,
+ httpRequestId: constants.httpRequestId ?? undefined,
+ })
+ await aiRouterApi.start({ ...request, waitpointId: waitpoint.id })
+ const paused = AiRouterStepOutput.init({ input: censoredInput }).setStatus(StepOutputStatus.PAUSED)
+ return (await executionState.upsertStep(action.name, paused)).incrementStepsExecuted().setVerdict({ status: FlowRunStatus.PAUSED })
+}
+
+function answerFromResume(payload: ResumePayload | undefined): ChooseAiRouteResponse {
+ const parsed = ResumeBody.safeParse(payload?.body)
+ if (parsed.success && !isNil(parsed.data.failure)) {
+ throw new AiRouterEvaluationError({ message: parsed.data.failure })
+ }
+ if (!parsed.success || isNil(parsed.data.output)) {
+ throw new AiRouterEvaluationError({ message: 'The routing model did not answer before the step timed out' })
+ }
+ return parsed.data.output
+}
+
+function canPause(constants: EngineConstants): boolean {
+ return !constants.actionRunMode && isNil(constants.stepNameToTest)
+}
+
+function askableBranches({ branches, bestMatch }: { branches: AiRouterActionSettings['branches'], bestMatch: boolean }): AiRouterActionSettings['branches'] {
+ if (bestMatch) {
+ return branches
+ }
+ return branches.filter((branch) => branch.branchType !== BranchExecutionType.FALLBACK)
+}
+
+function toOptions(branches: AiRouterActionSettings['branches']): Record<string, string> {
+ const options: Record<string, string> = {}
+ for (const branch of branches) {
+ if (!Object.hasOwn(options, branch.branchName)) {
+ options[branch.branchName] = criterionOf(branch)
+ }
+ }
+ return options
+}
+
+function criterionOf(branch: AiRouterActionSettings['branches'][number]): string {
+ const description = branch.description?.trim()
+ if (!isNil(description) && description.length > 0) {
+ return description
+ }
+ return branch.branchType === BranchExecutionType.FALLBACK ? FALLBACK_CRITERION : branch.branchName
+}
+
+function confidentRoutes({ answer, minConfidence, bestMatch }: ConfidentRoutesParams): string[] {
+ if (isNil(minConfidence)) {
+ return answer.matched
+ }
+ if (!bestMatch && !isNil(answer.probabilities)) {
+ return Object.entries(answer.probabilities).filter(([, probability]) => probability >= minConfidence).map(([route]) => route)
+ }
+ return answer.matched.filter((route) => {
+ const confidence = answer.probabilities?.[route]
+ return isNil(confidence) || confidence >= minConfidence
+ })
+}
+
+function bestMatchEvaluations({ branches, confident }: EvaluationsParams): boolean[] {
+ const fallbackName = branches.find((branch) => branch.branchType === BranchExecutionType.FALLBACK)?.branchName
+ const answered = confident[0]
+ const known = !isNil(answered) && branches.some((branch) => branch.branchName === answered)
+ const chosen = known ? answered : fallbackName
+ return branches.map((branch) => branch.branchName === chosen)
+}
+
+function allMatchesEvaluations({ branches, confident }: EvaluationsParams): boolean[] {
+ const matched = new Set(confident)
+ const withoutFallback = branches.map((branch) => branch.branchType !== BranchExecutionType.FALLBACK && matched.has(branch.branchName))
+ const nothingMatched = withoutFallback.every((match) => !match)
+ return branches.map((branch, index) => branch.branchType === BranchExecutionType.FALLBACK ? nothingMatched : withoutFallback[index])
+}
+
+function chosenName({ branches, evaluations }: { branches: AiRouterActionSettings['branches'], evaluations: boolean[] }): string | undefined {
+ const index = evaluations.findIndex((evaluation) => evaluation)
+ return index === -1 ? undefined : branches[index].branchName
+}
+
+function asPlainText(value: unknown): string {
+ if (typeof value === 'string') {
+ return value
+ }
+ return JSON.stringify(value) ?? ''
+}
+
+function truncate(text: string): string {
+ const cut = text.slice(0, AI_ROUTER_MAX_STATE_LENGTH)
+ return LONE_HIGH_SURROGATE_AT_END.test(cut) ? cut.slice(0, -1) : cut
+}
+
+type EvaluationsParams = {
+ branches: AiRouterActionSettings['branches']
+ confident: string[]
+}
+
+type ConfidentRoutesParams = {
+ answer: ChooseAiRouteResponse
+ minConfidence: number | undefined
+ bestMatch: boolean
+}
+
+const FALLBACK_CRITERION = 'Anything that fits none of the other routes'
+const ANSWER_BACKSTOP_MS = 10 * 60 * 1000
+const LONE_HIGH_SURROGATE_AT_END = /[\uD800-\uDBFF]$/
+
+const ResumeBody = z.object({
+ output: ChooseAiRouteResponse.optional(),
+ failure: z.string().optional(),
+})
+
+type PauseForAnswerParams = {
+ action: AiRouterAction
+ executionState: FlowExecutorContext
+ constants: EngineConstants
+ censoredInput: unknown
+ request: Parameters<typeof aiRouterApi.choose>[0]
+}
diff --git a/packages/server/engine/src/lib/handler/branch-execution.ts b/packages/server/engine/src/lib/handler/branch-execution.ts
new file mode 100644
index 00000000000..3e05ef443b0
--- /dev/null
+++ b/packages/server/engine/src/lib/handler/branch-execution.ts
@@ -0,0 +1,57 @@
+import { isNil } from '@activepieces/core-utils'
+import { BaseStepOutput, FlowAction, FlowRunStatus, StepOutputStatus } from '@activepieces/shared'
+import { utils } from '../utils'
+import { failStep } from './base-executor'
+import { EngineConstants } from './context/engine-constants'
+import { FlowExecutorContext } from './context/flow-execution-context'
+import { flowExecutor } from './flow-executor'
+
+export async function executeBranches({ action, executionState, constants, stepOutput, evaluations, stopAfterFirstMatch }: ExecuteBranchesParams): Promise<FlowExecutorContext> {
+ let state = await executionState.upsertStep(action.name, stepOutput)
+
+ const { data: executionStateResult, error: executionStateError } = await utils.tryCatchAndThrowOnEngineError(async () => {
+ for (let i = 0; i < evaluations.length; i++) {
+ if (!isNil(constants.stepNameToTest)) {
+ break
+ }
+ if (!evaluations[i]) {
+ continue
+ }
+
+ state = await flowExecutor.execute({
+ action: action.children[i],
+ executionState: state,
+ constants,
+ })
+
+ const shouldBreakExecution = state.verdict.status !== FlowRunStatus.RUNNING || stopAfterFirstMatch
+ if (shouldBreakExecution) {
+ break
+ }
+ }
+ return state
+ })
+ if (executionStateError) {
+ return failStep({
+ action,
+ executionState: state,
+ stepOutput: stepOutput.setStatus(StepOutputStatus.FAILED),
+ error: executionStateError,
+ })
+ }
+
+ return executionStateResult
+}
+
+export type BranchedStep = Pick<FlowAction, 'name' | 'displayName'> & {
+ children: (FlowAction | null)[]
+}
+
+type ExecuteBranchesParams = {
+ action: BranchedStep
+ executionState: FlowExecutorContext
+ constants: EngineConstants
+ stepOutput: BaseStepOutput
+ evaluations: boolean[]
+ stopAfterFirstMatch: boolean
+}
diff --git a/packages/server/engine/src/lib/handler/context/test-execution-context.ts b/packages/server/engine/src/lib/handler/context/test-execution-context.ts
index 46202b1663d..9da372fc3fa 100644
--- a/packages/server/engine/src/lib/handler/context/test-execution-context.ts
+++ b/packages/server/engine/src/lib/handler/context/test-execution-context.ts
@@ -1,6 +1,6 @@
import { isNil, spreadIfDefined } from '@activepieces/core-utils'
import { LATEST_CONTEXT_VERSION } from '@activepieces/pieces-framework'
-import { FlowActionType, flowStructureUtil, FlowTriggerType, FlowVersion, GenericStepOutput, LoopStepOutput, RouterStepOutput, StepOutputStatus } from '@activepieces/shared'
+import { AiRouterStepOutput, FlowActionType, flowStructureUtil, FlowTriggerType, FlowVersion, GenericStepOutput, LoopStepOutput, RouterStepOutput, StepOutputStatus } from '@activepieces/shared'
import { createPropsResolver } from '../../variables/props-resolver'
import { EngineConstants } from './engine-constants'
import { FlowExecutorContext } from './flow-execution-context'
@@ -44,6 +44,17 @@ export const testExecutionContext = {
}),
)
break
+ case FlowActionType.AI_ROUTER:
+ flowExecutionContext = await flowExecutionContext.upsertStep(
+ step.name,
+ AiRouterStepOutput.create({
+ input: step.settings,
+ type: stepType,
+ status: StepOutputStatus.SUCCEEDED,
+ ...spreadIfDefined('output', sampleData?.[step.name]),
+ }),
+ )
+ break
case FlowActionType.LOOP_ON_ITEMS: {
const { resolvedInput } = await createPropsResolver({
apiUrl,
diff --git a/packages/server/engine/src/lib/handler/flow-executor.ts b/packages/server/engine/src/lib/handler/flow-executor.ts
index 550839abc4b..15ef7dc46d0 100644
--- a/packages/server/engine/src/lib/handler/flow-executor.ts
+++ b/packages/server/engine/src/lib/handler/flow-executor.ts
@@ -5,6 +5,7 @@ import dayjs from 'dayjs'
import { flowRunProgressReporter } from '../helper/flow-run-progress-reporter'
import { loggingUtils } from '../helper/logging-utils'
import { triggerHelper } from '../helper/trigger-helper'
+import { aiRouterExecuter } from './ai-router-executor'
import { BaseExecutor } from './base-executor'
import { codeExecutor } from './code-executor'
import { EngineConstants, ResolvedExecuteFlowOperation } from './context/engine-constants'
@@ -23,6 +24,7 @@ function getExecutors(): Record<FlowActionType, BaseExecutor<FlowAction>> {
[FlowActionType.LOOP_ON_ITEMS]: loopExecutor,
[FlowActionType.PIECE]: pieceExecutor,
[FlowActionType.ROUTER]: routerExecuter,
+ [FlowActionType.AI_ROUTER]: aiRouterExecuter,
}
return executors
}
diff --git a/packages/server/engine/src/lib/handler/router-executor.ts b/packages/server/engine/src/lib/handler/router-executor.ts
index eb9e11a2538..4be57c6fce0 100755
--- a/packages/server/engine/src/lib/handler/router-executor.ts
+++ b/packages/server/engine/src/lib/handler/router-executor.ts
@@ -1,12 +1,12 @@
import { isNil, tryCatchSync } from '@activepieces/core-utils'
import { LATEST_CONTEXT_VERSION } from '@activepieces/pieces-framework'
-import { BranchCondition, BranchExecutionType, BranchOperator, EngineGenericError, FlowRunStatus, RouterAction, RouterActionSettings, RouterExecutionType, RouterStepOutput, StepOutputStatus } from '@activepieces/shared'
+import { BranchCondition, BranchExecutionType, BranchOperator, EngineGenericError, RouterAction, RouterActionSettings, RouterExecutionType, RouterStepOutput } from '@activepieces/shared'
import dayjs, { Dayjs } from 'dayjs'
import { utils } from '../utils'
import { BaseExecutor, failStep } from './base-executor'
+import { executeBranches } from './branch-execution'
import { EngineConstants } from './context/engine-constants'
import { FlowExecutorContext } from './context/flow-execution-context'
-import { flowExecutor } from './flow-executor'
export const routerExecuter: BaseExecutor<RouterAction> = {
async handle({
@@ -114,41 +114,15 @@ async function handleRouterExecution({ action, executionState, constants, censor
evaluation: evaluatedConditions[index],
})),
}).setDuration(performance.now() - stepStartTime)
- executionState = await executionState.upsertStep(action.name, routerOutput)
-
- const { data: executionStateResult, error: executionStateError } = await utils.tryCatchAndThrowOnEngineError(async () => {
- for (let i = 0; i < resolvedInput.branches.length; i++) {
- if (!isNil(constants.stepNameToTest)) {
- break
- }
- const condition = routerOutput.output?.branches[i].evaluation
- if (!condition) {
- continue
- }
-
- executionState = await flowExecutor.execute({
- action: action.children[i],
- executionState,
- constants,
- })
- const shouldBreakExecution = executionState.verdict.status !== FlowRunStatus.RUNNING || routerExecutionType === RouterExecutionType.EXECUTE_FIRST_MATCH
- if (shouldBreakExecution) {
- break
- }
- }
- return executionState
+ return executeBranches({
+ action,
+ executionState,
+ constants,
+ stepOutput: routerOutput,
+ evaluations: evaluatedConditions,
+ stopAfterFirstMatch: routerExecutionType === RouterExecutionType.EXECUTE_FIRST_MATCH,
})
- if (executionStateError) {
- return failStep({
- action,
- executionState,
- stepOutput: routerOutput.setStatus(StepOutputStatus.FAILED),
- error: executionStateError,
- })
- }
-
- return executionStateResult
}
function toConditionValues(condition: BranchCondition): ConditionValues {
diff --git a/packages/server/engine/test/handler/ai-router-branching.test.ts b/packages/server/engine/test/handler/ai-router-branching.test.ts
new file mode 100644
index 00000000000..5b0bec881f1
--- /dev/null
+++ b/packages/server/engine/test/handler/ai-router-branching.test.ts
@@ -0,0 +1,457 @@
+import { AI_ROUTER_MAX_STATE_LENGTH, AiRouterMatchMode, FlowAction, FlowRunStatus, StepOutputStatus } from '@activepieces/shared'
+import { FlowExecutorContext } from '../../src/lib/handler/context/flow-execution-context'
+import { StepExecutionPath } from '../../src/lib/handler/context/step-execution-path'
+import { flowExecutor } from '../../src/lib/handler/flow-executor'
+import { buildAiRouter, buildPieceAction, generateMockEngineConstants } from './test-helper'
+
+vi.mock('../../src/lib/piece-context/waitpoint-client', () => ({
+ waitpointClient: {
+ create: async () => ({ id: 'mock-waitpoint-id', resumeUrl: 'http://localhost/resume' }),
+ },
+}))
+
+const AI_ROUTER_PATH = '/v1/engine/ai-router'
+
+function mapperStep(name: string): FlowAction {
+ return buildPieceAction({
+ name,
+ pieceName: '@activepieces/piece-data-mapper',
+ actionName: 'advanced_mapping',
+ input: { mapping: { key: '{{ 1 + 2 }}' } },
+ })
+}
+
+function answerWith(body: unknown, status = 200) {
+ const calls: unknown[] = []
+ vi.spyOn(global, 'fetch').mockImplementation(async (input, init) => {
+ const url = String(input)
+ if (!url.endsWith(AI_ROUTER_PATH)) {
+ throw new Error(`unexpected fetch to ${url}`)
+ }
+ calls.push(JSON.parse(String(init?.body)))
+ return new Response(JSON.stringify(body), { status, headers: { 'Content-Type': 'application/json' } })
+ })
+ return calls
+}
+
+function execute(action: FlowAction): Promise<FlowExecutorContext> {
+ return flowExecutor.execute({
+ action,
+ executionState: FlowExecutorContext.empty(),
+ constants: generateMockEngineConstants({ actionRunMode: true }),
+ })
+}
+
+function executeInFlow(action: FlowAction, executionState = FlowExecutorContext.empty(), resumePayload?: { body: unknown }): Promise<FlowExecutorContext> {
+ return flowExecutor.execute({
+ action,
+ executionState,
+ constants: generateMockEngineConstants(resumePayload ? { resumePayload: { ...resumePayload, headers: {}, queryParams: {} } } : {}),
+ })
+}
+
+function resumedFrom(paused: FlowExecutorContext): FlowExecutorContext {
+ return paused.setCurrentPath(StepExecutionPath.empty()).setVerdict({ status: FlowRunStatus.RUNNING })
+}
+
+describe('ai router', () => {
+ afterEach(() => {
+ vi.restoreAllMocks()
+ })
+
+ it('runs only the route the model chose', async () => {
+ answerWith({ matched: ['Billing'], probabilities: { Billing: 0.91, Technical: 0.09 } })
+
+ const result = await execute(buildAiRouter({
+ routes: [{ branchName: 'Billing', description: 'Payments' }, { branchName: 'Technical', description: 'Bugs' }],
+ fallback: { branchName: 'Otherwise', description: 'Anything else' },
+ children: [mapperStep('billing'), mapperStep('technical'), mapperStep('otherwise')],
+ }))
+
+ expect(result.verdict).toStrictEqual({ status: FlowRunStatus.RUNNING })
+ expect(result.steps.billing.output).toEqual({ key: 3 })
+ expect(result.steps.technical).toBeUndefined()
+ expect(result.steps.otherwise).toBeUndefined()
+ expect(result.steps.ai_router.output).toMatchObject({
+ choice: 'Billing',
+ probabilities: { Billing: 0.91, Technical: 0.09 },
+ branches: [
+ { branchName: 'Billing', branchIndex: 1, evaluation: true },
+ { branchName: 'Technical', branchIndex: 2, evaluation: false },
+ { branchName: 'Otherwise', branchIndex: 3, evaluation: false },
+ ],
+ })
+ })
+
+ it('sends every route as a named criterion, fallback included', async () => {
+ const calls = answerWith({ matched: ['Otherwise'] })
+
+ await execute(buildAiRouter({
+ routes: [{ branchName: 'Billing', description: 'Payments' }],
+ fallback: { branchName: 'Otherwise' },
+ children: [mapperStep('billing'), mapperStep('otherwise')],
+ }))
+
+ expect(calls[0]).toEqual({
+ state: 'My card was charged twice',
+ question: 'Which team should handle this?',
+ matchMode: AiRouterMatchMode.BEST_MATCH,
+ options: {
+ Billing: 'Payments',
+ Otherwise: 'Anything that fits none of the other routes',
+ },
+ flowId: 'flowId',
+ flowRunId: 'flowRunId',
+ })
+ })
+
+ it('sends at most the first 20,000 characters of the input', async () => {
+ const calls = answerWith({ matched: ['Billing'] })
+
+ await execute(buildAiRouter({
+ text: 'x'.repeat(AI_ROUTER_MAX_STATE_LENGTH + 5_000),
+ routes: [{ branchName: 'Billing', description: 'Payments' }],
+ children: [mapperStep('billing')],
+ }))
+
+ expect(calls[0]).toMatchObject({ state: 'x'.repeat(AI_ROUTER_MAX_STATE_LENGTH) })
+ })
+
+ it('never cuts the input through the middle of an emoji', async () => {
+ const calls = answerWith({ matched: ['Billing'] })
+
+ await execute(buildAiRouter({
+ text: 'x'.repeat(AI_ROUTER_MAX_STATE_LENGTH - 1) + '😀',
+ routes: [{ branchName: 'Billing', description: 'Payments' }],
+ children: [mapperStep('billing')],
+ }))
+
+ expect(calls[0]).toMatchObject({ state: 'x'.repeat(AI_ROUTER_MAX_STATE_LENGTH - 1) })
+ })
+
+ it('fails the step with the credits message when the API refuses for lack of credits', async () => {
+ answerWith({ code: 'QUOTA_EXCEEDED', params: { metric: 'credits', message: 'The AI Router did not run because the platform is out of AI credits.' } }, 402)
+
+ const result = await execute(buildAiRouter({
+ routes: [{ branchName: 'Billing', description: 'Payments' }],
+ fallback: { branchName: 'Otherwise' },
+ children: [mapperStep('billing'), mapperStep('otherwise')],
+ }))
+
+ expect(result.steps.ai_router.status).toBe(StepOutputStatus.FAILED)
+ expect(result.steps.ai_router.errorMessage).toContain('out of AI credits')
+ expect(result.steps.billing).toBeUndefined()
+ expect(result.steps.otherwise).toBeUndefined()
+ })
+
+ it('runs the fallback without asking the model when every-route mode has no route to ask about', async () => {
+ const calls = answerWith({ matched: [] })
+
+ const result = await execute(buildAiRouter({
+ matchMode: AiRouterMatchMode.ALL_MATCHES,
+ routes: [],
+ fallback: { branchName: 'Otherwise', description: 'Anything else' },
+ children: [mapperStep('otherwise')],
+ }))
+
+ expect(calls).toHaveLength(0)
+ expect(result.steps.otherwise.output).toEqual({ key: 3 })
+ })
+
+ it('sends a route named after an inherited object property', async () => {
+ const calls = answerWith({ matched: ['constructor'] })
+
+ await execute(buildAiRouter({
+ routes: [{ branchName: 'constructor', description: 'Building work' }, { branchName: 'toString', description: 'Text' }],
+ fallback: { branchName: 'Otherwise' },
+ children: [mapperStep('constructor_route'), mapperStep('to_string'), mapperStep('otherwise')],
+ }))
+
+ expect(calls[0]).toMatchObject({
+ options: { constructor: 'Building work', toString: 'Text' },
+ })
+ })
+
+ it('takes the fallback when the answer is below the confidence floor', async () => {
+ answerWith({ matched: ['Billing'], probabilities: { Billing: 0.4, Otherwise: 0.6 } })
+
+ const result = await execute(buildAiRouter({
+ routes: [{ branchName: 'Billing', description: 'Payments' }],
+ fallback: { branchName: 'Otherwise', description: 'Anything else' },
+ minConfidence: 0.7,
+ children: [mapperStep('billing'), mapperStep('otherwise')],
+ }))
+
+ expect(result.steps.billing).toBeUndefined()
+ expect(result.steps.otherwise.output).toEqual({ key: 3 })
+ expect(result.steps.ai_router.output).toMatchObject({ choice: 'Otherwise' })
+ })
+
+ it('runs no route when the answer is below the floor and there is no fallback', async () => {
+ answerWith({ matched: ['Billing'], probabilities: { Billing: 0.4 } })
+
+ const result = await execute(buildAiRouter({
+ routes: [{ branchName: 'Billing', description: 'Payments' }],
+ minConfidence: 0.7,
+ children: [mapperStep('billing')],
+ }))
+
+ expect(result.verdict).toStrictEqual({ status: FlowRunStatus.RUNNING })
+ expect(result.steps.billing).toBeUndefined()
+ expect(result.steps.ai_router.output).toMatchObject({
+ branches: [{ branchName: 'Billing', branchIndex: 1, evaluation: false }],
+ })
+ })
+
+ it('ignores the floor when the model returns no probabilities', async () => {
+ answerWith({ matched: ['Billing'] })
+
+ const result = await execute(buildAiRouter({
+ routes: [{ branchName: 'Billing', description: 'Payments' }],
+ fallback: { branchName: 'Otherwise', description: 'Anything else' },
+ minConfidence: 0.9,
+ children: [mapperStep('billing'), mapperStep('otherwise')],
+ }))
+
+ expect(result.steps.billing.output).toEqual({ key: 3 })
+ expect(result.steps.otherwise).toBeUndefined()
+ })
+
+ it('falls back when the model names a route that does not exist', async () => {
+ answerWith({ matched: ['Refunds'] })
+
+ const result = await execute(buildAiRouter({
+ routes: [{ branchName: 'Billing', description: 'Payments' }],
+ fallback: { branchName: 'Otherwise', description: 'Anything else' },
+ children: [mapperStep('billing'), mapperStep('otherwise')],
+ }))
+
+ expect(result.steps.billing).toBeUndefined()
+ expect(result.steps.otherwise.output).toEqual({ key: 3 })
+ })
+
+ it('records no choice when the model names a route that does not exist and there is no fallback', async () => {
+ answerWith({ matched: ['Refunds'] })
+
+ const result = await execute(buildAiRouter({
+ routes: [{ branchName: 'Billing', description: 'Payments' }],
+ children: [mapperStep('billing')],
+ }))
+
+ expect(result.steps.billing).toBeUndefined()
+ expect(result.steps.ai_router.output).not.toHaveProperty('choice')
+ })
+
+ it('fails the step when the routing call fails, and takes no route', async () => {
+ answerWith({ message: 'boom' }, 500)
+
+ const result = await execute(buildAiRouter({
+ routes: [{ branchName: 'Billing', description: 'Payments' }],
+ fallback: { branchName: 'Otherwise', description: 'Anything else' },
+ children: [mapperStep('billing'), mapperStep('otherwise')],
+ }))
+
+ expect(result.steps.ai_router.status).toBe(StepOutputStatus.FAILED)
+ expect(result.steps.billing).toBeUndefined()
+ expect(result.steps.otherwise).toBeUndefined()
+ })
+
+ describe('taking every route that applies', () => {
+ const allMatches = AiRouterMatchMode.ALL_MATCHES
+
+ it('runs every route the model affirmed', async () => {
+ answerWith({ matched: ['Billing', 'Sales'], probabilities: { Billing: 0.9, Sales: 0.7, Technical: 0.05 } })
+
+ const result = await execute(buildAiRouter({
+ matchMode: allMatches,
+ routes: [{ branchName: 'Billing', description: 'Payments' }, { branchName: 'Technical', description: 'Bugs' }, { branchName: 'Sales', description: 'Pricing' }],
+ fallback: { branchName: 'Otherwise', description: 'Anything else' },
+ children: [mapperStep('billing'), mapperStep('technical'), mapperStep('sales'), mapperStep('otherwise')],
+ }))
+
+ expect(result.steps.billing.output).toEqual({ key: 3 })
+ expect(result.steps.sales.output).toEqual({ key: 3 })
+ expect(result.steps.technical).toBeUndefined()
+ expect(result.steps.otherwise).toBeUndefined()
+ expect(result.steps.ai_router.output).not.toHaveProperty('choice')
+ })
+
+ it('never asks about the fallback route', async () => {
+ const calls = answerWith({ matched: ['Billing'] })
+
+ await execute(buildAiRouter({
+ matchMode: allMatches,
+ routes: [{ branchName: 'Billing', description: 'Payments' }],
+ fallback: { branchName: 'Otherwise', description: 'Anything else' },
+ children: [mapperStep('billing'), mapperStep('otherwise')],
+ }))
+
+ expect(calls[0]).toEqual({
+ state: 'My card was charged twice',
+ question: 'Which team should handle this?',
+ matchMode: allMatches,
+ options: { Billing: 'Payments' },
+ flowId: 'flowId',
+ flowRunId: 'flowRunId',
+ })
+ })
+
+ it('runs the fallback only when nothing matched', async () => {
+ answerWith({ matched: [] })
+
+ const result = await execute(buildAiRouter({
+ matchMode: allMatches,
+ routes: [{ branchName: 'Billing', description: 'Payments' }, { branchName: 'Sales', description: 'Pricing' }],
+ fallback: { branchName: 'Otherwise', description: 'Anything else' },
+ children: [mapperStep('billing'), mapperStep('sales'), mapperStep('otherwise')],
+ }))
+
+ expect(result.steps.billing).toBeUndefined()
+ expect(result.steps.sales).toBeUndefined()
+ expect(result.steps.otherwise.output).toEqual({ key: 3 })
+ })
+
+ it('drops individual routes that fall below the floor', async () => {
+ answerWith({ matched: ['Billing', 'Sales'], probabilities: { Billing: 0.95, Sales: 0.4 } })
+
+ const result = await execute(buildAiRouter({
+ matchMode: allMatches,
+ minConfidence: 0.7,
+ routes: [{ branchName: 'Billing', description: 'Payments' }, { branchName: 'Sales', description: 'Pricing' }],
+ fallback: { branchName: 'Otherwise', description: 'Anything else' },
+ children: [mapperStep('billing'), mapperStep('sales'), mapperStep('otherwise')],
+ }))
+
+ expect(result.steps.billing.output).toEqual({ key: 3 })
+ expect(result.steps.sales).toBeUndefined()
+ expect(result.steps.otherwise).toBeUndefined()
+ })
+
+ it('runs the fallback when the floor rejects every route', async () => {
+ answerWith({ matched: ['Billing'], probabilities: { Billing: 0.4 } })
+
+ const result = await execute(buildAiRouter({
+ matchMode: allMatches,
+ minConfidence: 0.7,
+ routes: [{ branchName: 'Billing', description: 'Payments' }],
+ fallback: { branchName: 'Otherwise', description: 'Anything else' },
+ children: [mapperStep('billing'), mapperStep('otherwise')],
+ }))
+
+ expect(result.steps.billing).toBeUndefined()
+ expect(result.steps.otherwise.output).toEqual({ key: 3 })
+ })
+
+ it('lets a floor under 50% keep a route the worker left out', async () => {
+ answerWith({ matched: [], probabilities: { Billing: 0.4, Sales: 0.2 } })
+
+ const result = await execute(buildAiRouter({
+ matchMode: allMatches,
+ minConfidence: 0.3,
+ routes: [{ branchName: 'Billing', description: 'Payments' }, { branchName: 'Sales', description: 'Pricing' }],
+ fallback: { branchName: 'Otherwise', description: 'Anything else' },
+ children: [mapperStep('billing'), mapperStep('sales'), mapperStep('otherwise')],
+ }))
+
+ expect(result.steps.billing.output).toEqual({ key: 3 })
+ expect(result.steps.sales).toBeUndefined()
+ expect(result.steps.otherwise).toBeUndefined()
+ })
+ })
+})
+
+describe('ai router pauses the run while the worker decides', () => {
+ afterEach(() => {
+ vi.restoreAllMocks()
+ })
+
+ const billingFlow = () => buildAiRouter({
+ routes: [{ branchName: 'Billing', description: 'Payments' }],
+ fallback: { branchName: 'Otherwise' },
+ children: [mapperStep('billing'), mapperStep('otherwise')],
+ })
+
+ const answerFor = (route: string) => ({ body: { output: { matched: [route], probabilities: { Billing: 0.9, Otherwise: 0.1 } } } })
+
+ it('creates a waitpoint, starts the decision, and pauses without running a route', async () => {
+ const calls = answerWith({ requestId: 'req-1' }, 202)
+
+ const result = await executeInFlow(billingFlow())
+
+ expect(result.verdict).toEqual({ status: FlowRunStatus.PAUSED })
+ expect(result.steps.ai_router.status).toBe(StepOutputStatus.PAUSED)
+ expect(calls[0]).toMatchObject({ waitpointId: 'mock-waitpoint-id', flowId: 'flowId', flowRunId: 'flowRunId' })
+ expect(result.steps.billing).toBeUndefined()
+ expect(result.steps.otherwise).toBeUndefined()
+ })
+
+ it('resumes with the worker answer, runs that route, and asks nothing a second time', async () => {
+ const calls = answerWith({ requestId: 'req-1' }, 202)
+ const flow = billingFlow()
+ const paused = await executeInFlow(flow)
+
+ const resumed = await executeInFlow(flow, resumedFrom(paused), answerFor('Billing'))
+
+ expect(calls).toHaveLength(1)
+ expect(resumed.steps.ai_router).toMatchObject({ status: StepOutputStatus.SUCCEEDED, output: { choice: 'Billing' } })
+ expect(resumed.steps.billing.output).toEqual({ key: 3 })
+ expect(resumed.steps.otherwise).toBeUndefined()
+ })
+
+ it('fails the step with the worker failure text when the answer is a failure', async () => {
+ answerWith({ requestId: 'req-1' }, 202)
+ const flow = billingFlow()
+ const paused = await executeInFlow(flow)
+
+ const resumed = await executeInFlow(flow, resumedFrom(paused), { body: { failure: 'The routing model did not answer: HTTP 402: Insufficient credits' } })
+
+ expect(resumed.steps.ai_router.status).toBe(StepOutputStatus.FAILED)
+ expect(resumed.steps.ai_router.errorMessage).toContain('Insufficient credits')
+ expect(resumed.steps.billing).toBeUndefined()
+ })
+
+ it('fails the step when the deadline resumes it with no answer at all', async () => {
+ answerWith({ requestId: 'req-1' }, 202)
+ const flow = billingFlow()
+ const paused = await executeInFlow(flow)
+
+ const resumed = await executeInFlow(flow, resumedFrom(paused), { body: {} })
+
+ expect(resumed.steps.ai_router.status).toBe(StepOutputStatus.FAILED)
+ expect(resumed.steps.ai_router.errorMessage).toContain('did not answer before the step timed out')
+ })
+
+ it('reuses the decision when a step inside the chosen route pauses and resumes later', async () => {
+ const calls = answerWith({ requestId: 'req-1' }, 202)
+ const flow = buildAiRouter({
+ routes: [{ branchName: 'Billing', description: 'Payments' }],
+ fallback: { branchName: 'Otherwise' },
+ children: [
+ buildPieceAction({
+ name: 'approval',
+ pieceName: '@activepieces/piece-approval',
+ actionName: 'wait_for_approval',
+ input: {},
+ nextAction: mapperStep('billing'),
+ }),
+ mapperStep('otherwise'),
+ ],
+ })
+
+ const pausedOnRouter = await executeInFlow(flow)
+ const pausedOnApproval = await executeInFlow(flow, resumedFrom(pausedOnRouter), answerFor('Billing'))
+ expect(pausedOnApproval.verdict).toEqual({ status: FlowRunStatus.PAUSED })
+ expect(pausedOnApproval.steps.approval.status).toBe(StepOutputStatus.PAUSED)
+
+ const finished = await flowExecutor.execute({
+ action: flow,
+ executionState: resumedFrom(pausedOnApproval),
+ constants: generateMockEngineConstants({ resumePayload: { body: {}, headers: {}, queryParams: { action: 'approve' } } }),
+ })
+
+ expect(calls).toHaveLength(1)
+ expect(finished.steps.ai_router).toMatchObject({ status: StepOutputStatus.SUCCEEDED, output: { choice: 'Billing' } })
+ expect(finished.steps.approval.status).toBe(StepOutputStatus.SUCCEEDED)
+ expect(finished.steps.billing.output).toEqual({ key: 3 })
+ })
+})
diff --git a/packages/server/engine/test/handler/test-helper.ts b/packages/server/engine/test/handler/test-helper.ts
index 06d3f0eb3fc..9a2a0559b5e 100644
--- a/packages/server/engine/test/handler/test-helper.ts
+++ b/packages/server/engine/test/handler/test-helper.ts
@@ -1,4 +1,4 @@
-import { ActionErrorHandlingOptions, BeginExecuteFlowOperation, BranchCondition, BranchExecutionType, CodeAction, ExecutionType, FlowAction, FlowActionType, FlowVersionState, LoopOnItemsAction, PieceAction, PropertyExecutionType, RouterExecutionType, RunEnvironment, StreamStepProgress } from '@activepieces/shared'
+import { ActionErrorHandlingOptions, AiRouterAction, AiRouterMatchMode, BeginExecuteFlowOperation, BranchCondition, BranchExecutionType, CodeAction, ExecutionType, FlowAction, FlowActionType, FlowVersionState, LoopOnItemsAction, PieceAction, PropertyExecutionType, RouterExecutionType, RunEnvironment, StreamStepProgress } from '@activepieces/shared'
import { EngineConstants, ResolvedBeginExecuteFlowOperation } from '../../src/lib/handler/context/engine-constants'
export const generateMockEngineConstants = (params?: Partial<EngineConstants>): EngineConstants => {
@@ -24,6 +24,7 @@ export const generateMockEngineConstants = (params?: Partial<EngineConstants>):
workerHandlerId: params?.workerHandlerId ?? null,
httpRequestId: params?.httpRequestId ?? null,
resumePayload: params?.resumePayload,
+ actionRunMode: params?.actionRunMode,
runEnvironment: params?.runEnvironment ?? RunEnvironment.TESTING,
stepNameToTest: params?.stepNameToTest ?? undefined,
stepNames: params?.stepNames ?? [],
@@ -82,6 +83,36 @@ export function buildRouterWithOneCondition({ children, conditions, executionTyp
}
}
+export function buildAiRouter({ children, routes, fallback, minConfidence, matchMode, text }: { children: (FlowAction | null)[], routes: { branchName: string, description?: string }[], fallback?: { branchName: string, description?: string }, minConfidence?: number, matchMode?: AiRouterMatchMode, text?: string }): AiRouterAction {
+ const fallbackBranches = fallback === undefined ? [] : [{
+ branchType: BranchExecutionType.FALLBACK as const,
+ branchName: fallback.branchName,
+ description: fallback.description,
+ }]
+ return {
+ name: 'ai_router',
+ displayName: 'Your AI Router Name',
+ type: FlowActionType.AI_ROUTER,
+ skip: false,
+ settings: {
+ text: text ?? 'My card was charged twice',
+ question: 'Which team should handle this?',
+ matchMode: matchMode ?? AiRouterMatchMode.BEST_MATCH,
+ branches: [
+ ...routes.map((route) => ({
+ branchType: BranchExecutionType.CONDITION as const,
+ branchName: route.branchName,
+ description: route.description,
+ })),
+ ...fallbackBranches,
+ ],
+ minConfidence,
+ },
+ children,
+ valid: true,
+ }
+}
+
export function buildCodeAction({ name, input, skip, nextAction, errorHandlingOptions, useDeno }: { name: 'echo_step' | 'runtime' | 'echo_step_1' | 'system_error' | 'process_exit' | 'unhandled_rejection' | 'hello_world_npm' | 'stdout_on_failure' | 'setTimeout_error' | 'echo_step_legacy', input: Record<string, unknown>, skip?: boolean, errorHandlingOptions?: ActionErrorHandlingOptions, nextAction?: FlowAction, useDeno?: boolean }): CodeAction {
return {
name,
diff --git a/packages/server/engine/vitest.config.ts b/packages/server/engine/vitest.config.ts
index 970ff7df0a1..bcc417db87a 100644
--- a/packages/server/engine/vitest.config.ts
+++ b/packages/server/engine/vitest.config.ts
@@ -22,7 +22,7 @@ export default defineConfig({
test: {
globals: true,
environment: 'node',
- testTimeout: 20000,
+ testTimeout: 60000,
include: [path.resolve(__dirname, 'test/**/*.test.ts')],
},
resolve: {
diff --git a/packages/server/utils/src/activepieces-ai-cost.ts b/packages/server/utils/src/activepieces-ai-cost.ts
index cf8c91594ef..ab801c146bc 100644
--- a/packages/server/utils/src/activepieces-ai-cost.ts
+++ b/packages/server/utils/src/activepieces-ai-cost.ts
@@ -38,6 +38,19 @@ export function reportFixedCredits({ billing, provider, modelId, generationId }:
})
}
+export function reportProviderCost({ billing, provider, modelId, costUsd, inputTokens, outputTokens, generationId }: ReportProviderCostParams): void {
+ const context: BillingContext = { basis: AiChargeBasis.PROVIDER_REPORTED_COST, billing, provider, modelId }
+ if (isNil(costUsd)) {
+ report({ context, generationId, call: undefined })
+ return
+ }
+ report({
+ context,
+ generationId,
+ call: { charge: AiChargeBasis.PROVIDER_REPORTED_COST, generationId, costUsd, inputTokens, outputTokens },
+ })
+}
+
function billingContextOf({ provider, modelId, billing, charge }: BillingContextParams): BillingContext | undefined {
if (isNil(billing) || isNil(charge)) {
return undefined
@@ -236,6 +249,7 @@ export const activepiecesAiCost = {
billedLanguageModel,
billedEmbeddingModel,
reportFixedCredits,
+ reportProviderCost,
}
type BillingContext = {
@@ -275,6 +289,10 @@ type ReportFixedCreditsParams = {
generationId?: string
}
+type ReportProviderCostParams = ReportFixedCreditsParams & AiCallTokens & {
+ costUsd?: number
+}
+
type StreamState = {
reported: boolean
generationId?: string
diff --git a/packages/server/worker/src/lib/execute/jobs/ai/execute-ai.ts b/packages/server/worker/src/lib/execute/jobs/ai/execute-ai.ts
index fa34064c188..9422cc58859 100644
--- a/packages/server/worker/src/lib/execute/jobs/ai/execute-ai.ts
+++ b/packages/server/worker/src/lib/execute/jobs/ai/execute-ai.ts
@@ -6,6 +6,7 @@ import { JobContext, JobHandler, JobResult, JobResultKind } from '../../types'
import { resolveAiFiles } from './ai-files'
import { extractStructuredData } from './extract-structured-data'
import { generateImageStep } from './generate-image'
+import { routeStep } from './route'
export const executeAiJob: JobHandler<ExecuteAiJobData, JobResult> = {
jobType: WorkerJobType.EXECUTE_AI,
@@ -64,6 +65,8 @@ async function callTheModel({ ctx, data }: { ctx: JobContext, data: ExecuteAiJob
return { answer: await extractStructuredData({ data, resolved, flowStep, billing, files: await resolveAiFiles({ ctx, data }) }) }
case AiStepAction.GENERATE_IMAGE:
return { answer: await generateImageStep({ ctx, data, resolved, flowStep, billing, inputImages: await resolveAiFiles({ ctx, data }) }) }
+ case AiStepAction.ROUTE:
+ return routeStep({ data, resolved, billing })
case AiStepAction.ASK_AI:
case AiStepAction.SUMMARIZE_TEXT:
case AiStepAction.CLASSIFY_TEXT:
@@ -131,6 +134,7 @@ function buildMessages(data: ExecuteAiJobData): ModelMessage[] {
return [{ role: 'user', content: classificationPrompt(data) }]
case AiStepAction.EXTRACT_STRUCTURED_DATA:
case AiStepAction.GENERATE_IMAGE:
+ case AiStepAction.ROUTE:
throw new Error(`${data.action} does not build plain messages`)
}
}
@@ -171,6 +175,7 @@ function toStepOutput({ data, text, sources }: { data: ExecuteAiJobData, text: s
}
case AiStepAction.EXTRACT_STRUCTURED_DATA:
case AiStepAction.GENERATE_IMAGE:
+ case AiStepAction.ROUTE:
throw new Error(`${data.action} returns its own output shape`)
}
}
diff --git a/packages/server/worker/src/lib/execute/jobs/ai/route.ts b/packages/server/worker/src/lib/execute/jobs/ai/route.ts
new file mode 100644
index 00000000000..73ca70d5438
--- /dev/null
+++ b/packages/server/worker/src/lib/execute/jobs/ai/route.ts
@@ -0,0 +1,152 @@
+import { ActivepiecesAiBilling, AiChargeBasis, aiChargeFor, AIProviderName, isNil, tryCatch } from '@activepieces/core-utils'
+import { activepiecesAiCost, safeHttp } from '@activepieces/server-utils'
+import { AiRouterMatchMode, ChooseAiRouteResponse, ResolveAiProviderResponse, RouteJobData } from '@activepieces/shared'
+import { z } from 'zod'
+
+export async function routeStep({ data, resolved, billing }: RouteStepParams): Promise<ChooseAiRouteResponse> {
+ const apiKey = resolved.provider === AIProviderName.ACTIVEPIECES || resolved.provider === AIProviderName.OPENROUTER ? resolved.auth.apiKey : undefined
+ if (isNil(apiKey) || apiKey.length === 0) {
+ throw new Error('The AI Router has no OpenRouter key to call the routing model with')
+ }
+ const keyToRoute = Object.fromEntries(Object.keys(data.options).map((route, index) => [`r${index}`, route]))
+ const { data: response, error } = await tryCatch(() => safeHttp.axios.post<unknown>(
+ DECISIONS_URL,
+ {
+ model: data.modelId,
+ state: { text: data.state },
+ questions: buildQuestions({ data, keyToRoute }),
+ },
+ {
+ timeout: TIMEOUT_MS,
+ headers: {
+ 'Authorization': `Bearer ${apiKey}`,
+ 'Content-Type': 'application/json',
+ },
+ },
+ ))
+ if (error) {
+ throw new Error(`The routing model did not answer: ${describeFailure(error)}`)
+ }
+ const parsed = DecisionsResponse.safeParse(response.data)
+ if (!parsed.success) {
+ throw new Error('The routing model answered in a shape the AI Router does not understand')
+ }
+ const answer = data.matchMode === AiRouterMatchMode.BEST_MATCH
+ ? readChoice(parsed.data)
+ : readNouls({ decisions: parsed.data, keyToRoute })
+ if (isNil(answer)) {
+ throw new Error('The routing model did not answer the routing question')
+ }
+ bill({ data, resolved, billing, decisions: parsed.data })
+ return answer
+}
+
+function buildQuestions({ data, keyToRoute }: { data: RouteJobData, keyToRoute: Record<string, string> }): Record<string, unknown> {
+ if (data.matchMode === AiRouterMatchMode.BEST_MATCH) {
+ return {
+ [CHOICE_KEY]: { type: 'choice', instructions: data.question, criteria: data.options },
+ }
+ }
+ return Object.fromEntries(Object.entries(keyToRoute).map(([key, route]) => [
+ key,
+ { type: 'noul', instructions: `${data.question}\n\nAnswer yes only if this route applies: ${route} — ${data.options[route]}` },
+ ]))
+}
+
+function readChoice(decisions: DecisionsResponse): ChooseAiRouteResponse | undefined {
+ const answer = decisions.answers[CHOICE_KEY]
+ if (isNil(answer) || isNil(answer.choice)) {
+ return undefined
+ }
+ return {
+ matched: [answer.choice],
+ ...(isNil(answer.probabilities) ? {} : { probabilities: answer.probabilities }),
+ }
+}
+
+function readNouls({ decisions, keyToRoute }: { decisions: DecisionsResponse, keyToRoute: Record<string, string> }): ChooseAiRouteResponse | undefined {
+ const entries = Object.entries(keyToRoute).flatMap(([key, route]) => {
+ const probability = decisions.answers[key]?.noul
+ return isNil(probability) ? [] : [{ route, probability }]
+ })
+ if (entries.length === 0) {
+ return undefined
+ }
+ return {
+ matched: entries.filter(({ probability }) => probability >= APPLIES_THRESHOLD).map(({ route }) => route),
+ probabilities: Object.fromEntries(entries.map(({ route, probability }) => [route, probability])),
+ }
+}
+
+function bill({ data, resolved, billing, decisions }: BillParams): void {
+ const charge = aiChargeFor({ credentials: resolved })
+ if (charge?.basis === AiChargeBasis.PROVIDER_REPORTED_COST) {
+ activepiecesAiCost.reportProviderCost({
+ billing,
+ provider: resolved.provider,
+ modelId: data.modelId,
+ costUsd: decisions.usage?.cost,
+ inputTokens: decisions.usage?.input_tokens,
+ outputTokens: decisions.usage?.output_tokens,
+ generationId: decisions.id,
+ })
+ return
+ }
+ activepiecesAiCost.reportFixedCredits({ billing, provider: resolved.provider, modelId: data.modelId, generationId: decisions.id })
+}
+
+function describeFailure(error: unknown): string {
+ const failure = HttpFailure.safeParse(error)
+ if (!failure.success) {
+ return 'the request failed'
+ }
+ const status = failure.data.response?.status
+ if (isNil(status)) {
+ return failure.data.message
+ }
+ const detail = ErrorBody.safeParse(failure.data.response?.data)
+ return detail.success ? `HTTP ${status}: ${detail.data.error.message}` : `HTTP ${status}`
+}
+
+const DECISIONS_URL = 'https://openrouter.ai/api/alpha/decisions'
+const CHOICE_KEY = 'route'
+const APPLIES_THRESHOLD = 0.5
+const TIMEOUT_MS = 8_000
+
+const DecisionsResponse = z.object({
+ id: z.string().optional(),
+ answers: z.record(z.string(), z.object({
+ choice: z.string().optional(),
+ probabilities: z.record(z.string(), z.number()).optional(),
+ noul: z.number().optional(),
+ }).optional()),
+ usage: z.object({
+ input_tokens: z.number().optional(),
+ output_tokens: z.number().optional(),
+ cost: z.number().optional(),
+ }).optional(),
+})
+
+const HttpFailure = z.object({
+ message: z.string(),
+ response: z.object({
+ status: z.number(),
+ data: z.unknown().optional(),
+ }).optional(),
+})
+
+const ErrorBody = z.object({
+ error: z.object({ message: z.string() }),
+})
+
+type DecisionsResponse = z.infer<typeof DecisionsResponse>
+
+type RouteStepParams = {
+ data: RouteJobData
+ resolved: ResolveAiProviderResponse
+ billing: ActivepiecesAiBilling
+}
+
+type BillParams = RouteStepParams & {
+ decisions: DecisionsResponse
+}
diff --git a/packages/server/worker/test/lib/execute/jobs/ai/route.test.ts b/packages/server/worker/test/lib/execute/jobs/ai/route.test.ts
new file mode 100644
index 00000000000..9eebefd0f5a
--- /dev/null
+++ b/packages/server/worker/test/lib/execute/jobs/ai/route.test.ts
@@ -0,0 +1,168 @@
+import { AIProviderName } from '@activepieces/core-utils'
+import { AiRouterMatchMode, AiStepAction, ResolveAiProviderResponse, RouteJobData } from '@activepieces/shared'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { post, reportFixedCredits, reportProviderCost } = vi.hoisted(() => ({
+ post: vi.fn(),
+ reportFixedCredits: vi.fn(),
+ reportProviderCost: vi.fn(),
+}))
+
+vi.mock('@activepieces/server-utils', async (importOriginal) => ({
+ ...(await importOriginal<Record<string, unknown>>()),
+ safeHttp: { axios: { post: (...args: unknown[]) => post(...args) } },
+ activepiecesAiCost: { reportFixedCredits, reportProviderCost },
+}))
+
+const { routeStep } = await import('../../../../../src/lib/execute/jobs/ai/route')
+const { executeAiJob } = await import('../../../../../src/lib/execute/jobs/ai/execute-ai')
+
+const BILLING = {
+ source: 'ai-step-in-flow' as const,
+ platformId: 'platform-1',
+ projectId: 'project-1',
+ flowRun: { flowId: 'flow-1', flowRunId: 'run-1' },
+}
+
+const MANAGED: ResolveAiProviderResponse = {
+ provider: AIProviderName.ACTIVEPIECES,
+ providerConfigId: 'config-1',
+ auth: { apiKey: 'managed-key', apiKeyHash: 'hash' },
+ config: {},
+}
+
+const OWN_KEY: ResolveAiProviderResponse = {
+ provider: AIProviderName.OPENROUTER,
+ providerConfigId: 'config-2',
+ auth: { apiKey: 'own-key' },
+ config: {},
+}
+
+function routeJob(overrides: Partial<RouteJobData> = {}): RouteJobData {
+ return {
+ schemaVersion: 1,
+ jobType: 'EXECUTE_AI',
+ action: AiStepAction.ROUTE,
+ requestId: 'request-1',
+ projectId: 'project-1',
+ platformId: 'platform-1',
+ flowId: 'flow-1',
+ flowRunId: 'run-1',
+ provider: AIProviderName.ACTIVEPIECES,
+ modelId: 'typesafe/jev-1.13',
+ state: 'my card was charged twice',
+ question: 'Which team should handle this?',
+ options: { Billing: 'Payments, invoices, refunds', Sales: 'Pricing questions' },
+ matchMode: AiRouterMatchMode.BEST_MATCH,
+ ...overrides,
+ }
+}
+
+function sentBody(): Record<string, unknown> {
+ return post.mock.calls[0][1]
+}
+
+function sentConfig(): { headers: Record<string, string> } {
+ return post.mock.calls[0][2]
+}
+
+describe('routeStep asks OpenRouter\'s decisions endpoint', () => {
+ beforeEach(() => {
+ post.mockReset()
+ reportFixedCredits.mockReset()
+ reportProviderCost.mockReset()
+ })
+
+ it('sends one choice question carrying every route as a criterion, on the resolved key', async () => {
+ post.mockResolvedValue({ data: { id: 'gen-1', answers: { route: { type: 'choice', choice: 'Billing', probabilities: { Billing: 0.91, Sales: 0.09 } } } } })
+
+ const answer = await routeStep({ data: routeJob(), resolved: MANAGED, billing: BILLING })
+
+ expect(post.mock.calls[0][0]).toBe('https://openrouter.ai/api/alpha/decisions')
+ expect(sentBody()).toEqual({
+ model: 'typesafe/jev-1.13',
+ state: { text: 'my card was charged twice' },
+ questions: {
+ route: { type: 'choice', instructions: 'Which team should handle this?', criteria: { Billing: 'Payments, invoices, refunds', Sales: 'Pricing questions' } },
+ },
+ })
+ expect(sentConfig().headers.Authorization).toBe('Bearer managed-key')
+ expect(answer).toEqual({ matched: ['Billing'], probabilities: { Billing: 0.91, Sales: 0.09 } })
+ })
+
+ it('asks one noul question per route in every-route mode and reads the probability from the noul field', async () => {
+ post.mockResolvedValue({ data: { answers: { r0: { type: 'noul', noul: 0.7 }, r1: { type: 'noul', noul: 0.2 } } } })
+
+ const answer = await routeStep({ data: routeJob({ matchMode: AiRouterMatchMode.ALL_MATCHES }), resolved: MANAGED, billing: BILLING })
+
+ const questions = sentBody().questions as Record<string, { type: string, instructions: string }>
+ expect(Object.keys(questions)).toEqual(['r0', 'r1'])
+ expect(questions.r0.type).toBe('noul')
+ expect(questions.r0.instructions).toContain('Billing — Payments, invoices, refunds')
+ expect(answer).toEqual({ matched: ['Billing'], probabilities: { Billing: 0.7, Sales: 0.2 } })
+ })
+
+ it('bills the cost OpenRouter reports when the call ran on the managed key', async () => {
+ post.mockResolvedValue({ data: { id: 'gen-2', answers: { route: { choice: 'Billing' } }, usage: { input_tokens: 476, output_tokens: 70, cost: 0.00002 } } })
+
+ await routeStep({ data: routeJob(), resolved: MANAGED, billing: BILLING })
+
+ expect(reportProviderCost).toHaveBeenCalledWith({
+ billing: BILLING,
+ provider: AIProviderName.ACTIVEPIECES,
+ modelId: 'typesafe/jev-1.13',
+ costUsd: 0.00002,
+ inputTokens: 476,
+ outputTokens: 70,
+ generationId: 'gen-2',
+ })
+ expect(reportFixedCredits).not.toHaveBeenCalled()
+ })
+
+ it('bills one fixed credit when the call ran on the platform\'s own OpenRouter key', async () => {
+ post.mockResolvedValue({ data: { id: 'gen-3', answers: { route: { choice: 'Sales' } }, usage: { cost: 0.00002 } } })
+
+ await routeStep({ data: routeJob({ provider: AIProviderName.OPENROUTER }), resolved: OWN_KEY, billing: BILLING })
+
+ expect(reportFixedCredits).toHaveBeenCalledWith({ billing: BILLING, provider: AIProviderName.OPENROUTER, modelId: 'typesafe/jev-1.13', generationId: 'gen-3' })
+ expect(reportProviderCost).not.toHaveBeenCalled()
+ })
+
+ it('turns an HTTP failure into a readable message that never carries the key, and bills nothing', async () => {
+ post.mockRejectedValue(Object.assign(new Error('Request failed with status code 402'), {
+ response: { status: 402, data: { error: { message: 'Insufficient credits' } } },
+ config: { headers: { Authorization: 'Bearer managed-key' } },
+ }))
+
+ const attempt = routeStep({ data: routeJob(), resolved: MANAGED, billing: BILLING })
+
+ await expect(attempt).rejects.toThrow('HTTP 402: Insufficient credits')
+ await expect(attempt).rejects.not.toThrow('Bearer')
+ expect(reportProviderCost).not.toHaveBeenCalled()
+ expect(reportFixedCredits).not.toHaveBeenCalled()
+ })
+
+ it('fails readably when the model answered none of the questions', async () => {
+ post.mockResolvedValue({ data: { answers: {} } })
+
+ await expect(routeStep({ data: routeJob(), resolved: MANAGED, billing: BILLING })).rejects.toThrow('did not answer the routing question')
+ expect(reportProviderCost).not.toHaveBeenCalled()
+ })
+
+ it('refuses to call without a key instead of sending an empty bearer', async () => {
+ await expect(routeStep({ data: routeJob(), resolved: { ...OWN_KEY, auth: {} }, billing: BILLING })).rejects.toThrow('no OpenRouter key')
+ expect(post).not.toHaveBeenCalled()
+ })
+
+ it('hands the raw routing answer back as the step output when run through the AI job', async () => {
+ post.mockResolvedValue({ data: { answers: { route: { choice: 'Billing', probabilities: { Billing: 0.8, Sales: 0.2 } } } } })
+ const ctx = {
+ apiClient: { resolveAiProvider: async () => MANAGED },
+ log: { warn: () => undefined, error: () => undefined },
+ } as unknown as Parameters<typeof executeAiJob.execute>[0]
+
+ const result = await executeAiJob.execute(ctx, routeJob())
+
+ expect(result).toMatchObject({ response: { output: { matched: ['Billing'], probabilities: { Billing: 0.8, Sales: 0.2 } } } })
+ })
+})
diff --git a/packages/web/package.json b/packages/web/package.json
index 7e2c4707fe7..ae975f1ed95 100644
--- a/packages/web/package.json
+++ b/packages/web/package.json
@@ -137,6 +137,6 @@
"preview": "vite preview",
"test": "vitest run --passWithNoTests",
"lint": "eslint 'src/**/*.{ts,tsx}'",
- "typecheck": "tsc --noEmit -p tsconfig.app.json"
+ "typecheck": "tsc --noEmit -p tsconfig.app.json && tsc --noEmit -p tsconfig.spec.json"
}
}
diff --git a/packages/web/public/locales/en/translation.json b/packages/web/public/locales/en/translation.json
index c14153dca25..020c9857f83 100644
--- a/packages/web/public/locales/en/translation.json
+++ b/packages/web/public/locales/en/translation.json
@@ -1,4 +1,28 @@
{
+ "Exactly one route runs.": "Exactly one route runs.",
+ "Asks the model once per route, so it costs more than picking one.": "Asks the model once per route, so it costs more than picking one.",
+ "Every route that applies": "Every route that applies",
+ "The best route": "The best route",
+ "Match": "Match",
+ "How sure the model was": "How sure the model was",
+ "{route} scored {percent}%, under your {floor}% floor, so {fallback} ran": "{route} scored {percent}%, under your {floor}% floor, so {fallback} ran",
+ "50% \u2014 maybe": "50% \u2014 maybe",
+ "70% \u2014 likely": "70% \u2014 likely",
+ "90% \u2014 very likely": "90% \u2014 very likely",
+ "When to pick this route": "When to pick this route",
+ "Anything that fits none of the routes above": "Anything that fits none of the routes above",
+ "Payments, invoices, refunds": "Payments, invoices, refunds",
+ "The model reads this to decide. Be specific, not long.": "The model reads this to decide. Be specific, not long.",
+ "The text the model should read.": "The text the model should read.",
+ "One question, answered by exactly one route below.": "One question, answered by exactly one route below.",
+ "Routes": "Routes",
+ "Confidence floor": "Confidence floor",
+ "No floor": "No floor",
+ "Below this, the flow takes the Otherwise route.": "Below this, the flow takes the Otherwise route.",
+ "AI Router": "AI Router",
+ "Ask one question and Jev, an evaluation model, picks the route": "Ask one question and Jev, an evaluation model, picks the route",
+ "Question": "Question",
+ "duplicateRouteName": "Route names must be unique",
"Request approval": "Request approval",
"Sensitive Project": "Sensitive Project",
"When enabled, publishing flows in this project requires approval.": "When enabled, publishing flows in this project requires approval.",
diff --git a/packages/web/src/app/builder/flow-canvas/context-menu/canvas-context-menu-content.tsx b/packages/web/src/app/builder/flow-canvas/context-menu/canvas-context-menu-content.tsx
index 8e74603f445..53500f3f305 100644
--- a/packages/web/src/app/builder/flow-canvas/context-menu/canvas-context-menu-content.tsx
+++ b/packages/web/src/app/builder/flow-canvas/context-menu/canvas-context-menu-content.tsx
@@ -1,3 +1,4 @@
+import { isNil } from '@activepieces/core-utils';
import {
FlowAction,
FlowActionType,
@@ -99,7 +100,8 @@ export const CanvasContextMenuContent = ({
contextMenuType === ContextMenuType.STEP;
const showPasteAsBranchChild =
selectedNodes.length === 1 &&
- firstSelectedStep?.type === FlowActionType.ROUTER &&
+ !isNil(firstSelectedStep) &&
+ flowStructureUtil.isBranchedAction(firstSelectedStep) &&
!readonly &&
contextMenuType === ContextMenuType.STEP;
const showPasteAsCofBranchChild =
diff --git a/packages/web/src/app/builder/flow-canvas/edges/branch-label.tsx b/packages/web/src/app/builder/flow-canvas/edges/branch-label.tsx
index d87fa983e8d..9ed199049a1 100644
--- a/packages/web/src/app/builder/flow-canvas/edges/branch-label.tsx
+++ b/packages/web/src/app/builder/flow-canvas/edges/branch-label.tsx
@@ -1,6 +1,5 @@
import { isNil } from '@activepieces/core-utils';
import {
- FlowActionType,
BranchExecutionType,
FlowOperationType,
flowStructureUtil,
@@ -76,7 +75,8 @@ const BranchLabel = (props: BaseBranchLabel) => {
const isInsideRouterBranch = branchIndex !== null;
const isFallbackBranch =
isInsideRouterBranch &&
- step?.type === FlowActionType.ROUTER &&
+ !isNil(step) &&
+ flowStructureUtil.isBranchedAction(step) &&
step?.settings.branches[branchIndex]?.branchType ===
BranchExecutionType.FALLBACK;
const isOtherwiseBranch =
@@ -91,7 +91,7 @@ const BranchLabel = (props: BaseBranchLabel) => {
if (isNil(step)) {
return <></>;
}
- if (isInsideRouterBranch && step.type !== FlowActionType.ROUTER) {
+ if (isInsideRouterBranch && !flowStructureUtil.isBranchedAction(step)) {
return <></>;
}
@@ -149,7 +149,7 @@ const BranchLabel = (props: BaseBranchLabel) => {
{!isOtherwiseBranch &&
!readonly &&
- step.type === FlowActionType.ROUTER && (
+ flowStructureUtil.isBranchedAction(step) && (
<DropdownMenu
modal={true}
open={isDropdownMenuOpen}
diff --git a/packages/web/src/app/builder/flow-canvas/index.tsx b/packages/web/src/app/builder/flow-canvas/index.tsx
index fd2e2dff38e..c33710dbe4f 100644
--- a/packages/web/src/app/builder/flow-canvas/index.tsx
+++ b/packages/web/src/app/builder/flow-canvas/index.tsx
@@ -161,7 +161,7 @@ export const FlowCanvas = React.memo(
selectedSteps.forEach((step) => {
if (
step.type === FlowActionType.LOOP_ON_ITEMS ||
- step.type === FlowActionType.ROUTER ||
+ flowStructureUtil.isBranchedAction(step) ||
sharedFlowCanvasUtils.hasContinueOnFailureBranches(step)
) {
const childrenNotSelected = flowStructureUtil
@@ -270,6 +270,7 @@ const getChildrenKey = (step: Step) => {
case FlowActionType.LOOP_ON_ITEMS:
return step.firstLoopAction ? step.firstLoopAction.name : '';
case FlowActionType.ROUTER:
+ case FlowActionType.AI_ROUTER:
return step.children.reduce((routerKey, child) => {
const childrenKey = child
? flowStructureUtil
@@ -308,10 +309,9 @@ const createGraphKey = (
const flowGraphKey = flowStructureUtil
.getAllSteps(flowVersion.trigger)
.reduce((acc, step) => {
- const branchesNames =
- step.type === FlowActionType.ROUTER
- ? step.settings.branches.map((branch) => branch.branchName).join('-')
- : '0';
+ const branchesNames = flowStructureUtil.isBranchedAction(step)
+ ? step.settings.branches.map((branch) => branch.branchName).join('-')
+ : '0';
const childrenKey = getChildrenKey(step);
return `${acc}-${step.displayName}-${step.type}-${
step.nextAction ? step.nextAction.name : ''
diff --git a/packages/web/src/app/builder/flow-canvas/utils/flow-canvas-utils.ts b/packages/web/src/app/builder/flow-canvas/utils/flow-canvas-utils.ts
index 8548dda38f7..9f86b2d8048 100644
--- a/packages/web/src/app/builder/flow-canvas/utils/flow-canvas-utils.ts
+++ b/packages/web/src/app/builder/flow-canvas/utils/flow-canvas-utils.ts
@@ -8,7 +8,7 @@ import {
flowStructureUtil,
FlowVersion,
LoopOnItemsAction,
- RouterAction,
+ BranchedAction,
StepLocationRelativeToParent,
FlowTrigger,
FlowTriggerType,
@@ -136,7 +136,7 @@ const createStepGraph: (params: {
nodes: [stepNode, graphEndNode],
edges:
step.type !== FlowActionType.LOOP_ON_ITEMS &&
- step.type !== FlowActionType.ROUTER &&
+ !flowStructureUtil.isBranchedAction(step) &&
!sharedFlowCanvasUtils.hasContinueOnFailureBranches(step)
? [straightLineEdge]
: [],
@@ -162,7 +162,7 @@ const buildFlowGraph: (params: {
const childGraph =
step.type === FlowActionType.LOOP_ON_ITEMS
? buildLoopChildGraph({ step, orientation })
- : step.type === FlowActionType.ROUTER
+ : flowStructureUtil.isBranchedAction(step)
? buildRouterChildGraph({ step, orientation })
: sharedFlowCanvasUtils.hasContinueOnFailureBranches(step)
? buildContinueOnFailureBranchesGraph({ step, orientation })
@@ -377,7 +377,7 @@ const buildRouterChildGraph = ({
step,
orientation,
}: {
- step: RouterAction;
+ step: BranchedAction;
orientation: CanvasOrientation;
}) => {
const layout = getLayout(orientation);
@@ -650,7 +650,7 @@ const isSkipped = (stepName: string, trigger: FlowTrigger) => {
.filter(
(stepInPath) =>
stepInPath.type === FlowActionType.LOOP_ON_ITEMS ||
- stepInPath.type === FlowActionType.ROUTER ||
+ flowStructureUtil.isBranchedAction(stepInPath) ||
sharedFlowCanvasUtils.hasContinueOnFailureBranches(stepInPath),
)
.filter((parentInPath) =>
diff --git a/packages/web/src/app/builder/pieces-selector/generic-piece-selector-item.tsx b/packages/web/src/app/builder/pieces-selector/generic-piece-selector-item.tsx
index 8bff696be9d..7e149a26798 100644
--- a/packages/web/src/app/builder/pieces-selector/generic-piece-selector-item.tsx
+++ b/packages/web/src/app/builder/pieces-selector/generic-piece-selector-item.tsx
@@ -82,7 +82,7 @@ const GenericActionOrTriggerItem = ({
pieceSelectorItemInfo.classification
].variant
}
- className="shrink-0 px-1.5 py-0 text-[10px] font-normal"
+ className="shrink-0 px-1.5 py-0 text-xss font-normal"
>
{ACTION_CLASSIFICATION_BADGES[
pieceSelectorItemInfo.classification
diff --git a/packages/web/src/app/builder/pieces-selector/index.tsx b/packages/web/src/app/builder/pieces-selector/index.tsx
index 32b44708e56..da5f62120be 100644
--- a/packages/web/src/app/builder/pieces-selector/index.tsx
+++ b/packages/web/src/app/builder/pieces-selector/index.tsx
@@ -159,11 +159,10 @@ const PieceSelectorContent = ({
};
const { platform } = platformHooks.useCurrentPlatform();
+ const hasAiPieceActions =
+ !isNil(aiProviders) && aiProviders.length > 0 && !isAiPieceUnavailable;
const tabsList = pieceSelectorCustomization.buildResolvedTabs({
- availableBuiltinTabs: getTabsList(
- operation.type,
- !isNil(aiProviders) && aiProviders.length > 0 && !isAiPieceUnavailable,
- ),
+ availableBuiltinTabs: getTabsList(operation.type, hasAiPieceActions),
config: platform.pieceSelectorConfig,
});
const firstTab = tabsList[0];
diff --git a/packages/web/src/app/builder/pieces-selector/piece-actions-or-triggers-list.tsx b/packages/web/src/app/builder/pieces-selector/piece-actions-or-triggers-list.tsx
index 9d80f077a7b..2090400715b 100644
--- a/packages/web/src/app/builder/pieces-selector/piece-actions-or-triggers-list.tsx
+++ b/packages/web/src/app/builder/pieces-selector/piece-actions-or-triggers-list.tsx
@@ -54,7 +54,8 @@ export const convertStepMetadataToPieceSelectorItems = (
}
case FlowActionType.CODE:
case FlowActionType.LOOP_ON_ITEMS:
- case FlowActionType.ROUTER: {
+ case FlowActionType.ROUTER:
+ case FlowActionType.AI_ROUTER: {
return stepUtils
.coreActionsMetadata()
.filter((step) => step.type === stepMetadataWithSuggestions.type);
diff --git a/packages/web/src/app/builder/pieces-selector/pieces-card-list.tsx b/packages/web/src/app/builder/pieces-selector/pieces-card-list.tsx
index f71351900f9..2bbdfea50fa 100644
--- a/packages/web/src/app/builder/pieces-selector/pieces-card-list.tsx
+++ b/packages/web/src/app/builder/pieces-selector/pieces-card-list.tsx
@@ -218,7 +218,8 @@ const getItemHeight = (
const isCoreAction =
pieceMetadata.type === FlowActionType.CODE ||
pieceMetadata.type === FlowActionType.LOOP_ON_ITEMS ||
- pieceMetadata.type === FlowActionType.ROUTER;
+ pieceMetadata.type === FlowActionType.ROUTER ||
+ pieceMetadata.type === FlowActionType.AI_ROUTER;
if (isCoreAction && showActionsOrTriggersInsidePiecesList) {
return ACTION_OR_TRIGGER_ITEM_HEIGHT + PIECE_ITEM_HEIGHT;
}
diff --git a/packages/web/src/app/builder/run-details/ai-router-routes.tsx b/packages/web/src/app/builder/run-details/ai-router-routes.tsx
new file mode 100644
index 00000000000..da76707d276
--- /dev/null
+++ b/packages/web/src/app/builder/run-details/ai-router-routes.tsx
@@ -0,0 +1,169 @@
+import { isNil } from '@activepieces/core-utils';
+import { AiRouterMatchMode } from '@activepieces/shared';
+import { t } from 'i18next';
+import { Check, Info } from 'lucide-react';
+import { z } from 'zod';
+
+import { TextWithTooltip } from '@/components/custom/text-with-tooltip';
+import { Progress } from '@/components/ui/progress';
+import { cn } from '@/lib/utils';
+
+const VISIBLE_ROUTES = 5;
+
+export const AiRouterRoutes = ({ output, input }: AiRouterRoutesProps) => {
+ const ranked = rankRoutes(output);
+ if (isNil(ranked)) {
+ return null;
+ }
+ const shown = ranked.slice(0, VISIBLE_ROUTES);
+ const hidden = ranked.length - shown.length;
+ const floor = floorExplanation({ input, ranked });
+
+ return (
+ <div className="flex flex-col gap-2 p-3 rounded-lg border">
+ <span className="text-xs font-medium text-muted-foreground">
+ {t('How sure the model was')}
+ </span>
+ {shown.map((route) => (
+ <div key={route.name} className="flex items-center gap-2">
+ <span className="flex size-4 shrink-0 items-center justify-center">
+ {route.chosen && <Check className="size-3.5 text-primary" />}
+ </span>
+ <TextWithTooltip tooltipMessage={route.name}>
+ <span
+ className={cn('text-sm w-28 shrink-0 truncate block', {
+ 'font-medium text-primary': route.chosen,
+ 'text-muted-foreground': !route.chosen,
+ })}
+ >
+ {route.name}
+ </span>
+ </TextWithTooltip>
+ <Progress
+ value={route.percent ?? 0}
+ className={cn('h-1.5 grow', { 'bg-muted': !route.chosen })}
+ indicatorClassName={cn({
+ 'bg-muted-foreground/50': !route.chosen,
+ })}
+ />
+ <span
+ className={cn('text-xs w-10 shrink-0 text-right tabular-nums', {
+ 'font-medium text-primary': route.chosen,
+ 'text-muted-foreground': !route.chosen,
+ })}
+ >
+ {isNil(route.percent) ? '—' : `${route.percent}%`}
+ </span>
+ </div>
+ ))}
+ {hidden > 0 && (
+ <span className="text-xs text-muted-foreground">
+ {t('and {count} more', { count: hidden })}
+ </span>
+ )}
+ {!isNil(floor) && (
+ <div className="flex items-start gap-2 border-t pt-2 text-xs text-muted-foreground">
+ <Info className="size-3.5 shrink-0 mt-0.5" />
+ <span>
+ {t(
+ '{route} scored {percent}%, under your {floor}% floor, so {fallback} ran',
+ floor,
+ )}
+ </span>
+ </div>
+ )}
+ </div>
+ );
+};
+
+const AiRouterOutput = z.object({
+ branches: z.array(
+ z.object({ branchName: z.string(), evaluation: z.boolean() }),
+ ),
+ probabilities: z.record(z.string(), z.unknown()).optional(),
+});
+
+function rankRoutes(output: unknown): RankedRoute[] | undefined {
+ const parsed = AiRouterOutput.safeParse(output);
+ if (!parsed.success) {
+ return undefined;
+ }
+ const { branches, probabilities } = parsed.data;
+ if (isNil(probabilities)) {
+ return undefined;
+ }
+ const ranked = branches.map((branch) => {
+ const probability = probabilities[branch.branchName];
+ return {
+ name: branch.branchName,
+ percent:
+ typeof probability === 'number'
+ ? Math.round(probability * 100)
+ : undefined,
+ chosen: branch.evaluation,
+ };
+ });
+ if (ranked.every((route) => isNil(route.percent))) {
+ return undefined;
+ }
+ return ranked.sort((a, b) => (b.percent ?? -1) - (a.percent ?? -1));
+}
+
+const AiRouterInput = z.object({
+ minConfidence: z.number().optional(),
+ matchMode: z.enum(AiRouterMatchMode).optional(),
+});
+
+function floorExplanation({
+ input,
+ ranked,
+}: {
+ input: unknown;
+ ranked: RankedRoute[];
+}): FloorExplanation | undefined {
+ const parsed = AiRouterInput.safeParse(input);
+ if (!parsed.success || isNil(parsed.data.minConfidence)) {
+ return undefined;
+ }
+ if (parsed.data.matchMode === AiRouterMatchMode.ALL_MATCHES) {
+ return undefined;
+ }
+ const top = ranked[0];
+ const chosen = ranked.find((route) => route.chosen);
+ const floor = Math.round(parsed.data.minConfidence * 100);
+ if (
+ isNil(top) ||
+ isNil(chosen) ||
+ isNil(top.percent) ||
+ top.name === chosen.name ||
+ top.percent >= floor
+ ) {
+ return undefined;
+ }
+ return {
+ route: top.name,
+ percent: top.percent,
+ floor,
+ fallback: chosen.name,
+ };
+}
+
+export const aiRouterRoutesUtils = { rankRoutes, floorExplanation };
+
+type RankedRoute = {
+ name: string;
+ percent: number | undefined;
+ chosen: boolean;
+};
+
+type FloorExplanation = {
+ route: string;
+ percent: number;
+ floor: number;
+ fallback: string;
+};
+
+type AiRouterRoutesProps = {
+ output: unknown;
+ input?: unknown;
+};
diff --git a/packages/web/src/app/builder/run-details/flow-step-input-output.tsx b/packages/web/src/app/builder/run-details/flow-step-input-output.tsx
index a4ed8509888..a2932ec2c7b 100644
--- a/packages/web/src/app/builder/run-details/flow-step-input-output.tsx
+++ b/packages/web/src/app/builder/run-details/flow-step-input-output.tsx
@@ -39,6 +39,7 @@ import { StepDataPanelHeader } from '../step-data/step-data-panel-header';
import { StepDataPanelViewToggle } from '../step-data/step-data-panel-view-toggle';
import { isRunAgent } from '../test-step/agent-test-step';
+import { AiRouterRoutes } from './ai-router-routes';
import { truncatedInputUtils } from './truncated-input-utils';
type RunActiveTab = 'input' | 'output' | 'timeline';
@@ -270,7 +271,14 @@ export const FlowStepInputOutput = () => {
/>
</TabsContent>
)}
- <TabsContent value="output">
+ <TabsContent value="output" className="flex flex-col gap-3">
+ {selectedStep.type === FlowActionType.AI_ROUTER &&
+ !isStepRunning && (
+ <AiRouterRoutes
+ output={selectedStepOutput.output}
+ input={selectedStepOutput.input}
+ />
+ )}
{isStepRunning ? (
<StepOutputSkeleton className="p-4" />
) : slicedOutputRef ? (
diff --git a/packages/web/src/app/builder/step-settings/ai-router-settings/index.tsx b/packages/web/src/app/builder/step-settings/ai-router-settings/index.tsx
new file mode 100644
index 00000000000..243dee15094
--- /dev/null
+++ b/packages/web/src/app/builder/step-settings/ai-router-settings/index.tsx
@@ -0,0 +1,365 @@
+import { isNil } from '@activepieces/core-utils';
+import {
+ AiRouterAction,
+ AiRouterMatchMode,
+ BranchExecutionType,
+ FlowActionType,
+ FlowOperationRequest,
+ FlowOperationType,
+ flowStructureUtil,
+ FlowVersion,
+} from '@activepieces/shared';
+import { useReactFlow } from '@xyflow/react';
+import { t } from 'i18next';
+import { Split } from 'lucide-react';
+import { memo, useEffect } from 'react';
+import { useFieldArray, useFormContext } from 'react-hook-form';
+
+import { SearchableSelect } from '@/components/custom/searchable-select';
+
+import {
+ FormField,
+ FormItem,
+ FormMessage,
+} from '../../../../components/ui/form';
+import { Label } from '../../../../components/ui/label';
+import {
+ Select,
+ SelectContent,
+ SelectItem,
+ SelectTrigger,
+ SelectValue,
+} from '../../../../components/ui/select';
+import { Textarea } from '../../../../components/ui/textarea';
+import { useBuilderStateContext } from '../../builder-hooks';
+import { flowCanvasUtils } from '../../flow-canvas/utils/flow-canvas-utils';
+import { TextInputWithMentions } from '../../piece-properties/text-input-with-mentions';
+import { BranchesList } from '../router-settings/branches-list';
+import BranchesToolbar from '../router-settings/branches-toolbar';
+
+export const AiRouterSettings = memo(({ readonly }: { readonly: boolean }) => {
+ const [
+ step,
+ applyOperation,
+ setSelectedBranchIndex,
+ selectedBranchIndex,
+ addOperationListener,
+ removeOperationListener,
+ ] = useBuilderStateContext((state) => [
+ flowStructureUtil.getActionOrThrow(
+ state.selectedStep!,
+ state.flowVersion.trigger,
+ ) as AiRouterAction,
+ state.applyOperation,
+ state.setSelectedBranchIndex,
+ state.selectedBranchIndex,
+ state.addOperationListener,
+ state.removeOperationListener,
+ ]);
+ const { fitView } = useReactFlow();
+ const confidenceOptions = [
+ { value: '0.5', label: t('50% — maybe') },
+ { value: '0.7', label: t('70% — likely') },
+ { value: '0.9', label: t('90% — very likely') },
+ ];
+
+ const form =
+ useFormContext<Omit<AiRouterAction, 'children' | 'nextAction'>>();
+ const { control, setValue, formState } = form;
+
+ const { insert, remove, move } = useFieldArray({
+ control,
+ name: 'settings.branches',
+ });
+
+ const deleteBranch = (index: number) => {
+ applyOperation({
+ type: FlowOperationType.DELETE_BRANCH,
+ request: {
+ stepName: step.name,
+ branchIndex: index,
+ },
+ });
+
+ setSelectedBranchIndex(null);
+ fitView(flowCanvasUtils.createFocusStepInGraphParams(step.name));
+ };
+
+ useEffect(() => {
+ const operationListener = (
+ flowVersion: FlowVersion,
+ operation: FlowOperationRequest,
+ ) => {
+ switch (operation.type) {
+ case FlowOperationType.DELETE_BRANCH: {
+ if (operation.request.stepName !== step.name) {
+ return;
+ }
+ remove(operation.request.branchIndex);
+ break;
+ }
+ case FlowOperationType.DUPLICATE_BRANCH:
+ case FlowOperationType.ADD_BRANCH: {
+ if (operation.request.stepName !== step.name) return;
+ const updatedStep = flowStructureUtil.getActionOrThrow(
+ operation.request.stepName,
+ flowVersion.trigger,
+ );
+ if (updatedStep.type !== FlowActionType.AI_ROUTER) {
+ console.error(
+ `Trying to change a route on a none ai router step! ${operation.request.stepName}`,
+ );
+ return;
+ }
+ const branch =
+ updatedStep.settings.branches[operation.request.branchIndex];
+ if (operation.type === FlowOperationType.DUPLICATE_BRANCH) {
+ insert(operation.request.branchIndex + 1, {
+ ...branch,
+ branchName: `${branch.branchName} Copy`,
+ });
+ } else {
+ insert(operation.request.branchIndex, {
+ branchType: BranchExecutionType.CONDITION,
+ branchName: operation.request.branchName,
+ description: operation.request.description ?? '',
+ });
+ }
+ form.trigger();
+ break;
+ }
+ case FlowOperationType.MOVE_BRANCH: {
+ if (operation.request.stepName !== step.name) return;
+ move(
+ operation.request.sourceBranchIndex,
+ operation.request.targetBranchIndex,
+ );
+ break;
+ }
+ }
+ };
+
+ addOperationListener(operationListener);
+ return () => removeOperationListener(operationListener);
+ }, []);
+
+ if (!isNil(selectedBranchIndex)) {
+ const isFallback =
+ step.settings.branches[selectedBranchIndex]?.branchType ===
+ BranchExecutionType.FALLBACK;
+ return (
+ <FormField
+ key={`route-${selectedBranchIndex}-description`}
+ control={control}
+ name={`settings.branches.${selectedBranchIndex}.description`}
+ render={({ field }) => (
+ <FormItem className="flex flex-col gap-1">
+ <Label>{t('When to pick this route')}</Label>
+ <Textarea
+ {...field}
+ value={field.value ?? ''}
+ disabled={readonly}
+ rows={3}
+ placeholder={
+ isFallback
+ ? t('Anything that fits none of the routes above')
+ : t('Payments, invoices, refunds')
+ }
+ onChange={(e) => {
+ field.onChange(e.target.value);
+ form.trigger();
+ }}
+ />
+ <span className="text-xs text-muted-foreground">
+ {t('The model reads this to decide. Be specific, not long.')}
+ </span>
+ <FormMessage />
+ </FormItem>
+ )}
+ />
+ );
+ }
+
+ return (
+ <>
+ <FormField
+ control={control}
+ name="settings.text"
+ render={({ field }) => (
+ <FormItem className="flex flex-col gap-1">
+ <Label>{t('Input')}</Label>
+ <TextInputWithMentions
+ disabled={readonly}
+ onChange={(value) => {
+ field.onChange(value);
+ form.trigger();
+ }}
+ initialValue={field.value}
+ ></TextInputWithMentions>
+ <span className="text-xs text-muted-foreground">
+ {t('The text the model should read.')}
+ </span>
+ </FormItem>
+ )}
+ />
+
+ <FormField
+ control={control}
+ name="settings.question"
+ render={({ field }) => (
+ <FormItem className="flex flex-col gap-1">
+ <Label>{t('Question')}</Label>
+ <TextInputWithMentions
+ disabled={readonly}
+ onChange={(value) => {
+ field.onChange(value);
+ form.trigger();
+ }}
+ initialValue={field.value}
+ ></TextInputWithMentions>
+ <span className="text-xs text-muted-foreground">
+ {t('One question, answered by exactly one route below.')}
+ </span>
+ </FormItem>
+ )}
+ />
+
+ <FormField
+ control={control}
+ name="settings.matchMode"
+ render={({ field }) => (
+ <FormItem className="flex flex-col gap-1">
+ <Label>{t('Match')}</Label>
+ <Select
+ disabled={readonly}
+ value={field.value ?? AiRouterMatchMode.BEST_MATCH}
+ onValueChange={(value) => {
+ field.onChange(value);
+ form.trigger();
+ }}
+ >
+ <SelectTrigger>
+ <SelectValue placeholder={t('Match')} />
+ </SelectTrigger>
+ <SelectContent>
+ <SelectItem value={AiRouterMatchMode.BEST_MATCH}>
+ {t('The best route')}
+ </SelectItem>
+ <SelectItem value={AiRouterMatchMode.ALL_MATCHES}>
+ {t('Every route that applies')}
+ </SelectItem>
+ </SelectContent>
+ </Select>
+ <span className="text-xs text-muted-foreground">
+ {field.value === AiRouterMatchMode.ALL_MATCHES
+ ? t(
+ 'Asks the model once per route, so it costs more than picking one.',
+ )
+ : t('Exactly one route runs.')}
+ </span>
+ </FormItem>
+ )}
+ />
+
+ <div>
+ <div className="flex gap-2 mb-2 items-center">
+ <Split className="w-4 h-4 rotate-180"></Split>
+ <Label>{t('Routes')}</Label>
+ </div>
+
+ <BranchesList
+ errors={(formState.errors.settings?.branches as unknown[]) ?? []}
+ readonly={readonly}
+ step={step}
+ showFallbackBranch={true}
+ branchNameChanged={(index, name) => {
+ setValue(`settings.branches.${index}.branchName` as const, name, {
+ shouldValidate: true,
+ });
+ }}
+ deleteBranch={deleteBranch}
+ moveBranch={({ sourceIndex, targetIndex }) => {
+ applyOperation({
+ type: FlowOperationType.MOVE_BRANCH,
+ request: {
+ stepName: step.name,
+ sourceBranchIndex: sourceIndex,
+ targetBranchIndex: targetIndex,
+ },
+ });
+ }}
+ duplicateBranch={(index) => {
+ applyOperation({
+ type: FlowOperationType.DUPLICATE_BRANCH,
+ request: {
+ stepName: step.name,
+ branchIndex: index,
+ },
+ });
+ setSelectedBranchIndex(index + 1);
+ }}
+ setSelectedBranchIndex={(index) => {
+ setSelectedBranchIndex(index);
+ if (step.children[index]) {
+ fitView(
+ flowCanvasUtils.createFocusStepInGraphParams(
+ step.children[index].name,
+ ),
+ );
+ } else {
+ fitView(
+ flowCanvasUtils.createFocusStepInGraphParams(
+ `${step.name}-big-add-button-${step.name}-branch-${index}-start-edge`,
+ ),
+ );
+ }
+ }}
+ ></BranchesList>
+ {!readonly && (
+ <div className="mt-2">
+ <BranchesToolbar
+ addButtonClicked={() => {
+ applyOperation({
+ type: FlowOperationType.ADD_BRANCH,
+ request: {
+ stepName: step.name,
+ branchIndex: step.settings.branches.length - 1,
+ branchName: `Route ${step.settings.branches.length}`,
+ },
+ });
+
+ setSelectedBranchIndex(step.settings.branches.length - 1);
+ }}
+ ></BranchesToolbar>
+ </div>
+ )}
+ </div>
+
+ <FormField
+ control={control}
+ name="settings.minConfidence"
+ render={({ field }) => (
+ <FormItem className="flex flex-col gap-1">
+ <Label>{t('Confidence floor')}</Label>
+ <SearchableSelect
+ disabled={readonly}
+ value={isNil(field.value) ? undefined : String(field.value)}
+ options={confidenceOptions}
+ showDeselect={true}
+ placeholder={t('No floor')}
+ onChange={(value) => {
+ field.onChange(isNil(value) ? undefined : Number(value));
+ form.trigger();
+ }}
+ />
+ <span className="text-xs text-muted-foreground">
+ {t('Below this, the flow takes the Otherwise route.')}
+ </span>
+ </FormItem>
+ )}
+ />
+ </>
+ );
+});
+
+AiRouterSettings.displayName = 'AiRouterSettings';
diff --git a/packages/web/src/app/builder/step-settings/index.tsx b/packages/web/src/app/builder/step-settings/index.tsx
index db5683c0fe0..94bc7a4d02b 100644
--- a/packages/web/src/app/builder/step-settings/index.tsx
+++ b/packages/web/src/app/builder/step-settings/index.tsx
@@ -37,6 +37,7 @@ import {
import { TestStepCTAButton } from '../test-step/test-step-cta-button';
import { AgentSettings } from './agent-settings';
+import { AiRouterSettings } from './ai-router-settings';
import { CodeSettings } from './code-settings';
import EditableStepName from './editable-step-name';
import { LoopsSettings } from './loops-settings';
@@ -207,6 +208,9 @@ const StepSettingsContainer = () => {
{modifiedStep.type === FlowActionType.ROUTER && modifiedStep && (
<RouterSettings readonly={readonly}></RouterSettings>
)}
+ {modifiedStep.type === FlowActionType.AI_ROUTER && modifiedStep && (
+ <AiRouterSettings readonly={readonly}></AiRouterSettings>
+ )}
{modifiedStep.type === FlowTriggerType.PIECE && modifiedStep && (
<PieceSettings
step={modifiedStep}
diff --git a/packages/web/src/app/builder/step-settings/router-settings/branches-list.tsx b/packages/web/src/app/builder/step-settings/router-settings/branches-list.tsx
index 6b0d2b4b788..9bc7eaee766 100644
--- a/packages/web/src/app/builder/step-settings/router-settings/branches-list.tsx
+++ b/packages/web/src/app/builder/step-settings/router-settings/branches-list.tsx
@@ -1,9 +1,5 @@
import { isNil } from '@activepieces/core-utils';
-import {
- RouterAction,
- BranchExecutionType,
- RouterActionSettings,
-} from '@activepieces/shared';
+import { BranchedAction, BranchExecutionType } from '@activepieces/shared';
import { t } from 'i18next';
import { GripVertical, Trash, CopyPlus, Pencil } from 'lucide-react';
import React, { useState } from 'react';
@@ -27,7 +23,8 @@ import {
import { cn } from '../../../../lib/utils';
type BranchListProps = {
- step: RouterAction;
+ step: BranchedAction;
+ showFallbackBranch?: boolean;
setSelectedBranchIndex: (index: number) => void;
deleteBranch: (index: number) => void;
duplicateBranch: (index: number) => void;
@@ -44,6 +41,7 @@ type BranchListProps = {
};
export const BranchesList = ({
step,
+ showFallbackBranch = false,
setSelectedBranchIndex,
errors,
duplicateBranch,
@@ -55,7 +53,7 @@ export const BranchesList = ({
const [branchNameEditingIndex, setBranchNameEditingIndex] = useState<
number | null
>(null);
- const form = useFormContext<RouterAction>();
+ const form = useFormContext<BranchedAction>();
return (
<Sortable
value={step.settings.branches.map((branch, idx) => ({
@@ -107,12 +105,43 @@ export const BranchesList = ({
</SortableItem>
),
)}
+ {showFallbackBranch &&
+ step.settings.branches.map((branch, index) =>
+ branch.branchType === BranchExecutionType.FALLBACK ? (
+ <div key={`fallback-${index}`}>
+ <Separator></Separator>
+ <BranchListItem
+ branch={branch}
+ branchIndex={index}
+ readonly={readonly}
+ onClick={() => {
+ setSelectedBranchIndex(index);
+ }}
+ errors={errors}
+ duplicateBranch={() => undefined}
+ deleteBranch={() => undefined}
+ isEditingBranchName={branchNameEditingIndex === index}
+ setIsEditingBranchName={(isEditing) =>
+ isEditing
+ ? setBranchNameEditingIndex(index)
+ : setBranchNameEditingIndex(null)
+ }
+ branchNameChanged={(name) => {
+ branchNameChanged(index, name);
+ }}
+ showDeleteButton={false}
+ showDuplicateButton={false}
+ showDragHandle={false}
+ ></BranchListItem>
+ </div>
+ ) : null,
+ )}
</Sortable>
);
};
type BranchListItemProps = {
- branch: RouterActionSettings['branches'][number];
+ branch: { branchName: string };
branchIndex: number;
readonly: boolean;
onClick: () => void;
@@ -123,6 +152,8 @@ type BranchListItemProps = {
setIsEditingBranchName: (isEditing: boolean) => void;
branchNameChanged: (name: string) => void;
showDeleteButton: boolean;
+ showDuplicateButton?: boolean;
+ showDragHandle?: boolean;
};
export const BranchListItem = ({
@@ -137,6 +168,8 @@ export const BranchListItem = ({
setIsEditingBranchName,
branchNameChanged,
showDeleteButton,
+ showDuplicateButton = true,
+ showDragHandle = true,
}: BranchListItemProps) => {
return (
<div
@@ -213,34 +246,38 @@ export const BranchListItem = ({
<TooltipContent side="bottom">{t('Rename')}</TooltipContent>
</Tooltip>
- <Tooltip>
- <TooltipTrigger asChild>
- <Button
- variant={'ghost'}
- size={'icon'}
- onClick={(e) => {
- e.stopPropagation();
- duplicateBranch();
- }}
- >
- <CopyPlus className="h-4 w-4" />
- </Button>
- </TooltipTrigger>
- <TooltipContent side="bottom">{t('Duplicate')}</TooltipContent>
- </Tooltip>
- <Tooltip>
- <TooltipTrigger asChild>
- <SortableDragHandle
- variant="ghost"
- size="icon"
- disabled={readonly}
- className={'shrink-0 size-7'}
- >
- <GripVertical className="size-4" aria-hidden="true" />
- </SortableDragHandle>
- </TooltipTrigger>
- <TooltipContent side="bottom">{t('Move')}</TooltipContent>
- </Tooltip>
+ {showDuplicateButton && (
+ <Tooltip>
+ <TooltipTrigger asChild>
+ <Button
+ variant={'ghost'}
+ size={'icon'}
+ onClick={(e) => {
+ e.stopPropagation();
+ duplicateBranch();
+ }}
+ >
+ <CopyPlus className="h-4 w-4" />
+ </Button>
+ </TooltipTrigger>
+ <TooltipContent side="bottom">{t('Duplicate')}</TooltipContent>
+ </Tooltip>
+ )}
+ {showDragHandle && (
+ <Tooltip>
+ <TooltipTrigger asChild>
+ <SortableDragHandle
+ variant="ghost"
+ size="icon"
+ disabled={readonly}
+ className={'shrink-0 size-7'}
+ >
+ <GripVertical className="size-4" aria-hidden="true" />
+ </SortableDragHandle>
+ </TooltipTrigger>
+ <TooltipContent side="bottom">{t('Move')}</TooltipContent>
+ </Tooltip>
+ )}
</div>
</div>
);
diff --git a/packages/web/src/app/builder/step-settings/router-settings/index.tsx b/packages/web/src/app/builder/step-settings/router-settings/index.tsx
index 8bb6748aaa6..21ec327109b 100644
--- a/packages/web/src/app/builder/step-settings/router-settings/index.tsx
+++ b/packages/web/src/app/builder/step-settings/router-settings/index.tsx
@@ -108,10 +108,10 @@ export const RouterSettings = memo(({ readonly }: { readonly: boolean }) => {
});
} else {
insert(
- updatedStep.settings.branches.length - 1,
+ operation.request.branchIndex,
flowStructureUtil.createBranch(
- `Branch ${updatedStep.settings.branches.length}`,
- undefined,
+ operation.request.branchName,
+ operation.request.conditions,
),
);
}
diff --git a/packages/web/src/app/builder/test-step/test-sample-data-viewer.tsx b/packages/web/src/app/builder/test-step/test-sample-data-viewer.tsx
index 25011594c22..a40d96b452e 100644
--- a/packages/web/src/app/builder/test-step/test-sample-data-viewer.tsx
+++ b/packages/web/src/app/builder/test-step/test-sample-data-viewer.tsx
@@ -1,5 +1,10 @@
import { isNil, tryParseFriendlyPieceError } from '@activepieces/core-utils';
-import { AgentResult, AgentTaskStatus, FlowAction } from '@activepieces/shared';
+import {
+ AgentResult,
+ AgentTaskStatus,
+ FlowAction,
+ FlowActionType,
+} from '@activepieces/shared';
import { t } from 'i18next';
import { Loader2, Play } from 'lucide-react';
import React, { useState } from 'react';
@@ -12,6 +17,7 @@ import { cn } from '@/lib/utils';
import { DataDisplayTabs } from '../data-display/data-display-tabs';
import { ErrorExplanationContext } from '../data-display/explanation-prompt';
import { FriendlyErrorView } from '../data-display/friendly-error-view';
+import { AiRouterRoutes } from '../run-details/ai-router-routes';
import { ClosePanelButton } from '../step-data/close-panel-button';
import { StepDataPanelHeader } from '../step-data/step-data-panel-header';
import { StepDataPanelViewToggle } from '../step-data/step-data-panel-view-toggle';
@@ -149,11 +155,16 @@ export const TestSampleDataViewer = React.memo(
pieceDisplayName={pieceDisplayName}
/>
) : activeTab === 'Output' && !errorMessage ? (
- <SmartOutputViewer
- json={outputData}
- title={t('Output')}
- pieceSchema={pieceSchema ?? null}
- />
+ <div className="flex flex-col gap-3">
+ {currentStep?.type === FlowActionType.AI_ROUTER && (
+ <AiRouterRoutes output={outputData} input={sampleDataInput} />
+ )}
+ <SmartOutputViewer
+ json={outputData}
+ title={t('Output')}
+ pieceSchema={pieceSchema ?? null}
+ />
+ </div>
) : (
<DataDisplayTabs
data={activeData}
diff --git a/packages/web/src/features/pieces/hooks/pieces-hooks.ts b/packages/web/src/features/pieces/hooks/pieces-hooks.ts
index a5d656680e8..bfdbded4d44 100644
--- a/packages/web/src/features/pieces/hooks/pieces-hooks.ts
+++ b/packages/web/src/features/pieces/hooks/pieces-hooks.ts
@@ -556,6 +556,9 @@ const getExploreTabContent = (
const loopPiece = queryResult.find(
(piece) => piece.type === FlowActionType.LOOP_ON_ITEMS,
);
+ const aiRouterPiece = queryResult.find(
+ (piece) => piece.type === FlowActionType.AI_ROUTER,
+ );
if (highlightedPieces.length > 0) {
hightlightedPiecesCategory.metadata.push(...highlightedPieces);
@@ -564,6 +567,9 @@ const getExploreTabContent = (
if (branchPiece) {
hightlightedPiecesCategory.metadata.splice(0, 0, branchPiece);
}
+ if (aiRouterPiece) {
+ hightlightedPiecesCategory.metadata.splice(1, 0, aiRouterPiece);
+ }
if (codePiece) {
hightlightedPiecesCategory.metadata.splice(3, 0, codePiece);
diff --git a/packages/web/src/features/pieces/hooks/steps-hooks.ts b/packages/web/src/features/pieces/hooks/steps-hooks.ts
index 043035857ee..6f47622ef6c 100644
--- a/packages/web/src/features/pieces/hooks/steps-hooks.ts
+++ b/packages/web/src/features/pieces/hooks/steps-hooks.ts
@@ -9,6 +9,7 @@ import {
import { useQueries, useQuery } from '@tanstack/react-query';
import { useTranslation } from 'react-i18next';
+import { aiProviderQueries } from '@/features/platform-admin/hooks/ai-provider-hooks';
import { authenticationSession } from '@/lib/authentication-session';
import { piecesApi } from '../api/pieces-api';
@@ -54,6 +55,8 @@ export const stepsHooks = {
useAllStepsMetadata: ({ searchQuery, type, enabled }: UseMetadataProps) => {
const { i18n } = useTranslation();
const projectId = authenticationSession.getProjectId() ?? undefined;
+ const { data: aiProviders } = aiProviderQueries.useProjectAiProviders();
+ const aiRouterEnabled = stepUtils.hasAiRouterProvider(aiProviders);
const query = useQuery<StepMetadataWithSuggestions[], Error>({
queryKey: [
'pieces-metadata',
@@ -61,6 +64,7 @@ export const stepsHooks = {
type,
projectId,
i18n.language,
+ aiRouterEnabled,
],
queryFn: async () => {
const pieces = await piecesApi.list({
@@ -93,6 +97,10 @@ export const stepsHooks = {
case 'action': {
const filteredCoreActions = stepUtils
.coreActionsMetadata()
+ .filter(
+ (step) =>
+ aiRouterEnabled || step.type !== FlowActionType.AI_ROUTER,
+ )
.filter((step) => passSearch(searchQuery, step));
return [...filteredCoreActions, ...piecesMetadata];
}
diff --git a/packages/web/src/features/pieces/types/index.ts b/packages/web/src/features/pieces/types/index.ts
index 8ee2de3e98c..799bda58f58 100644
--- a/packages/web/src/features/pieces/types/index.ts
+++ b/packages/web/src/features/pieces/types/index.ts
@@ -36,6 +36,7 @@ export type PrimitiveStepMetadata = BaseStepMetadata & {
| FlowActionType.CODE
| FlowActionType.LOOP_ON_ITEMS
| FlowActionType.ROUTER
+ | FlowActionType.AI_ROUTER
| FlowTriggerType.EMPTY;
};
diff --git a/packages/web/src/features/pieces/utils/form-utils.tsx b/packages/web/src/features/pieces/utils/form-utils.tsx
index b66a9fe7e50..f6215accb53 100644
--- a/packages/web/src/features/pieces/utils/form-utils.tsx
+++ b/packages/web/src/features/pieces/utils/form-utils.tsx
@@ -15,6 +15,8 @@ import {
PropertyType,
} from '@activepieces/pieces-framework';
import {
+ AiRouterActionSchema,
+ AiRouterActionSettingsWithValidation,
AppConnectionScope,
AppConnectionType,
CodeActionSchema,
@@ -596,6 +598,10 @@ export const formUtils = {
}),
}).shape,
);
+ case FlowActionType.AI_ROUTER:
+ return AiRouterActionSchema.omit({ settings: true }).extend(
+ z.object({ settings: AiRouterActionSettingsWithValidation }).shape,
+ );
case FlowActionType.CODE:
return CodeActionSchema;
case FlowActionType.PIECE: {
diff --git a/packages/web/src/features/pieces/utils/piece-search-utils.ts b/packages/web/src/features/pieces/utils/piece-search-utils.ts
index f423b6607e2..c708bcfe687 100644
--- a/packages/web/src/features/pieces/utils/piece-search-utils.ts
+++ b/packages/web/src/features/pieces/utils/piece-search-utils.ts
@@ -22,7 +22,8 @@ const isFlowController = (stepMetadata: StepMetadata) => {
}
return (
stepMetadata.type === FlowActionType.LOOP_ON_ITEMS ||
- stepMetadata.type === FlowActionType.ROUTER
+ stepMetadata.type === FlowActionType.ROUTER ||
+ stepMetadata.type === FlowActionType.AI_ROUTER
);
};
diff --git a/packages/web/src/features/pieces/utils/piece-selector-utils.ts b/packages/web/src/features/pieces/utils/piece-selector-utils.ts
index eb03c0f57b6..e2ef51d2be8 100644
--- a/packages/web/src/features/pieces/utils/piece-selector-utils.ts
+++ b/packages/web/src/features/pieces/utils/piece-selector-utils.ts
@@ -21,6 +21,8 @@ import {
flowStructureUtil,
StepSettings,
RouterActionSettingsWithValidation,
+ AiRouterActionSettingsWithValidation,
+ AiRouterMatchMode,
FlowTriggerType,
PropertyExecutionType,
DEFAULT_SAMPLE_DATA_SETTINGS,
@@ -77,6 +79,12 @@ const isPieceStepInputValid = ({
return schema.safeParse(input).success && authValid;
};
+const routerSettingsOverride = (settings: StepSettings | undefined) =>
+ !isNil(settings) && 'executionType' in settings ? settings : undefined;
+
+const aiRouterSettingsOverride = (settings: StepSettings | undefined) =>
+ !isNil(settings) && 'question' in settings ? settings : undefined;
+
const isStepInitiallyValid = (
pieceSelectorItem: PieceSelectorItem,
overrideDefaultSettings?: StepSettings,
@@ -119,6 +127,14 @@ const isStepInitiallyValid = (
}
return false;
}
+ case FlowActionType.AI_ROUTER: {
+ if (overrideDefaultSettings) {
+ return AiRouterActionSettingsWithValidation.safeParse(
+ overrideDefaultSettings,
+ ).success;
+ }
+ return false;
+ }
}
};
@@ -203,7 +219,7 @@ const getDefaultStepValues = ({
return deepMergeAndCast<FlowAction>(
{
type: FlowActionType.ROUTER,
- settings: overrideDefaultSettings ?? {
+ settings: routerSettingsOverride(overrideDefaultSettings) ?? {
executionType: RouterExecutionType.EXECUTE_FIRST_MATCH,
branches: [
{
@@ -230,6 +246,31 @@ const getDefaultStepValues = ({
},
common,
);
+ case FlowActionType.AI_ROUTER:
+ return deepMergeAndCast<FlowAction>(
+ {
+ type: FlowActionType.AI_ROUTER,
+ settings: aiRouterSettingsOverride(overrideDefaultSettings) ?? {
+ text: '',
+ question: '',
+ matchMode: AiRouterMatchMode.BEST_MATCH,
+ branches: [
+ {
+ branchType: BranchExecutionType.CONDITION,
+ branchName: 'Route 1',
+ description: '',
+ },
+ {
+ branchType: BranchExecutionType.FALLBACK,
+ branchName: 'Otherwise',
+ description: 'Anything that fits none of the routes above',
+ },
+ ],
+ },
+ children: [null, null],
+ },
+ common,
+ );
case FlowActionType.PIECE: {
if (!isPieceActionOrTrigger(pieceSelectorItem)) {
throw new Error(
diff --git a/packages/web/src/features/pieces/utils/step-utils.tsx b/packages/web/src/features/pieces/utils/step-utils.tsx
index 85ddd20d1cc..edd89281321 100644
--- a/packages/web/src/features/pieces/utils/step-utils.tsx
+++ b/packages/web/src/features/pieces/utils/step-utils.tsx
@@ -1,4 +1,8 @@
-import { LocalesEnum, spreadIfDefined } from '@activepieces/core-utils';
+import {
+ AIProviderName,
+ LocalesEnum,
+ spreadIfDefined,
+} from '@activepieces/core-utils';
import {
ErrorHandlingOptionsParam,
PieceMetadataModel,
@@ -13,6 +17,7 @@ import {
FlowTrigger,
StepOutput,
StepRunResponse,
+ ProjectAIProvider,
} from '@activepieces/shared';
import { t } from 'i18next';
@@ -25,12 +30,20 @@ import {
} from '../types';
export const stepUtils = {
+ hasAiRouterProvider(providers: ProjectAIProvider[] | undefined): boolean {
+ return (providers ?? []).some(
+ (provider) =>
+ provider.provider === AIProviderName.ACTIVEPIECES ||
+ provider.provider === AIProviderName.OPENROUTER,
+ );
+ },
coreActionsMetadata(): PrimitiveStepMetadata[] {
const coreStepMetadata = buildCoreStepMetadata();
return [
coreStepMetadata[FlowActionType.CODE],
coreStepMetadata[FlowActionType.LOOP_ON_ITEMS],
coreStepMetadata[FlowActionType.ROUTER],
+ coreStepMetadata[FlowActionType.AI_ROUTER],
];
},
getKeys(
@@ -57,6 +70,7 @@ export const stepUtils = {
'customLogoUrl' in step ? step.customLogoUrl : undefined;
switch (step.type) {
case FlowActionType.ROUTER:
+ case FlowActionType.AI_ROUTER:
case FlowActionType.LOOP_ON_ITEMS:
case FlowActionType.CODE:
case FlowTriggerType.EMPTY:
@@ -179,6 +193,14 @@ function buildCoreStepMetadata(): Record<
description: t('Split your flow into branches depending on condition(s)'),
type: FlowActionType.ROUTER,
},
+ [FlowActionType.AI_ROUTER]: {
+ displayName: t('AI Router'),
+ logoUrl: 'https://cdn.activepieces.com/pieces/ai_router.png',
+ description: t(
+ 'Ask one question and Jev, an evaluation model, picks the route',
+ ),
+ type: FlowActionType.AI_ROUTER,
+ },
[FlowTriggerType.EMPTY]: {
displayName: t('Empty Trigger'),
logoUrl: 'https://cdn.activepieces.com/pieces/new-core/empty-trigger.svg',
diff --git a/packages/web/test/app/builder/flow-canvas/utils/flow-canvas-utils.test.ts b/packages/web/test/app/builder/flow-canvas/utils/flow-canvas-utils.test.ts
index 85cdd7ae92c..fbaa4de9414 100644
--- a/packages/web/test/app/builder/flow-canvas/utils/flow-canvas-utils.test.ts
+++ b/packages/web/test/app/builder/flow-canvas/utils/flow-canvas-utils.test.ts
@@ -1,7 +1,11 @@
// @vitest-environment jsdom
import {
+ AiRouterAction,
+ AiRouterMatchMode,
+ BranchExecutionType,
CodeAction,
EmptyTrigger,
+ FlowAction,
FlowActionType,
FlowTriggerType,
FlowVersion,
@@ -39,7 +43,38 @@ const createCodeAction = (
nextAction,
});
-const createFlowVersion = (firstAction?: CodeAction): FlowVersion => {
+const createAiRouter = (): AiRouterAction => ({
+ name: 'step_1',
+ valid: true,
+ displayName: 'AI Router',
+ lastUpdatedDate: '2026-01-01T00:00:00.000Z',
+ type: FlowActionType.AI_ROUTER,
+ settings: {
+ text: '{{trigger.body.message}}',
+ question: 'Which team?',
+ matchMode: AiRouterMatchMode.BEST_MATCH,
+ branches: [
+ {
+ branchType: BranchExecutionType.CONDITION,
+ branchName: 'Billing',
+ description: 'payments',
+ },
+ {
+ branchType: BranchExecutionType.CONDITION,
+ branchName: 'Technical',
+ description: 'bugs',
+ },
+ {
+ branchType: BranchExecutionType.FALLBACK,
+ branchName: 'Otherwise',
+ description: 'else',
+ },
+ ],
+ },
+ children: [null, null, null],
+});
+
+const createFlowVersion = (firstAction?: FlowAction): FlowVersion => {
const trigger: EmptyTrigger = {
name: 'trigger',
valid: false,
@@ -115,3 +150,33 @@ describe('flowCanvasUtils.createFlowGraph', () => {
expect(lastEdge?.target).toEqual('step_1-subgraph-end');
});
});
+
+describe('flowCanvasUtils.createFlowGraph with an AI router', () => {
+ it('draws one labelled branch per route', () => {
+ const graph = flowCanvasUtils.createFlowGraph({
+ version: createFlowVersion(createAiRouter()),
+ notes: [],
+ orientation: 'vertical',
+ });
+
+ const branchLabels = graph.edges
+ .filter((edge) => edge.type === ApEdgeType.ROUTER_START_EDGE)
+ .map((edge) => edge.data?.label);
+
+ expect(branchLabels).toEqual(['Billing', 'Technical', 'Otherwise']);
+ });
+
+ it('gives every empty route its own add button', () => {
+ const graph = flowCanvasUtils.createFlowGraph({
+ version: createFlowVersion(createAiRouter()),
+ notes: [],
+ orientation: 'vertical',
+ });
+
+ const addButtons = graph.nodes.filter(
+ (node) => node.type === ApNodeType.BIG_ADD_BUTTON,
+ );
+
+ expect(addButtons).toHaveLength(3);
+ });
+});
diff --git a/packages/web/test/app/builder/run-details/ai-router-routes.test.ts b/packages/web/test/app/builder/run-details/ai-router-routes.test.ts
new file mode 100644
index 00000000000..a08400a0f0e
--- /dev/null
+++ b/packages/web/test/app/builder/run-details/ai-router-routes.test.ts
@@ -0,0 +1,135 @@
+import { describe, expect, it } from 'vitest';
+
+import { aiRouterRoutesUtils } from '@/app/builder/run-details/ai-router-routes';
+
+const { rankRoutes, floorExplanation } = aiRouterRoutesUtils;
+
+function branch(branchName: string, evaluation: boolean) {
+ return { branchName, branchIndex: 0, evaluation };
+}
+
+describe('rankRoutes', () => {
+ it('sorts routes by probability and marks the one that ran', () => {
+ const ranked = rankRoutes({
+ branches: [
+ branch('Billing', true),
+ branch('Technical', false),
+ branch('Sales', false),
+ ],
+ choice: 'Billing',
+ probabilities: { Sales: 0.03, Billing: 0.91, Technical: 0.06 },
+ });
+
+ expect(ranked).toEqual([
+ { name: 'Billing', percent: 91, chosen: true },
+ { name: 'Technical', percent: 6, chosen: false },
+ { name: 'Sales', percent: 3, chosen: false },
+ ]);
+ });
+
+ it('marks what ran, not what the model answered', () => {
+ const ranked = rankRoutes({
+ branches: [branch('Billing', false), branch('Otherwise', true)],
+ choice: 'Billing',
+ probabilities: { Billing: 0.4, Otherwise: 0.6 },
+ });
+
+ expect(ranked?.find((route) => route.chosen)?.name).toBe('Otherwise');
+ expect(ranked?.find((route) => route.name === 'Billing')?.chosen).toBe(
+ false,
+ );
+ });
+
+ it('marks every route that ran when several did', () => {
+ const ranked = rankRoutes({
+ branches: [
+ branch('Billing', true),
+ branch('Sales', true),
+ branch('Technical', false),
+ ],
+ probabilities: { Billing: 0.9, Sales: 0.7, Technical: 0.05 },
+ });
+
+ expect(ranked?.filter((route) => route.chosen).map((r) => r.name)).toEqual([
+ 'Billing',
+ 'Sales',
+ ]);
+ });
+
+ it('shows an unscored route that ran, and sorts it last', () => {
+ const ranked = rankRoutes({
+ branches: [branch('Billing', false), branch('Otherwise', true)],
+ probabilities: { Billing: 0.2 },
+ });
+
+ expect(ranked).toEqual([
+ { name: 'Billing', percent: 20, chosen: false },
+ { name: 'Otherwise', percent: undefined, chosen: true },
+ ]);
+ });
+
+ it('returns nothing when no route carries a usable probability', () => {
+ const branches = [branch('Billing', true)];
+ expect(rankRoutes({ branches })).toBeUndefined();
+ expect(rankRoutes({ branches, probabilities: {} })).toBeUndefined();
+ expect(
+ rankRoutes({ branches, probabilities: { Billing: 'high' } }),
+ ).toBeUndefined();
+ });
+
+ it('returns nothing for an output that is not an ai router result', () => {
+ expect(rankRoutes(undefined)).toBeUndefined();
+ expect(rankRoutes('No output')).toBeUndefined();
+ expect(rankRoutes({ choice: 'Billing' })).toBeUndefined();
+ });
+
+ it('ignores a non numeric probability rather than rendering NaN', () => {
+ const ranked = rankRoutes({
+ branches: [branch('Billing', true), branch('Broken', false)],
+ probabilities: { Billing: 1, Broken: 'high' },
+ });
+
+ expect(ranked).toEqual([
+ { name: 'Billing', percent: 100, chosen: true },
+ { name: 'Broken', percent: undefined, chosen: false },
+ ]);
+ });
+});
+
+describe('floorExplanation', () => {
+ const ranked = [
+ { name: 'Route 1', percent: 63, chosen: false },
+ { name: 'Route 2', percent: 33, chosen: false },
+ { name: 'Otherwise', percent: 4, chosen: true },
+ ];
+
+ it('explains why the fallback ran when the top route is under the floor', () => {
+ expect(floorExplanation({ input: { minConfidence: 0.9 }, ranked })).toEqual(
+ {
+ route: 'Route 1',
+ percent: 63,
+ floor: 90,
+ fallback: 'Otherwise',
+ },
+ );
+ });
+
+ it('says nothing without a floor, in all-matches mode, or when the top route ran', () => {
+ expect(floorExplanation({ input: {}, ranked })).toBeUndefined();
+ expect(
+ floorExplanation({
+ input: { minConfidence: 0.9, matchMode: 'ALL_MATCHES' },
+ ranked,
+ }),
+ ).toBeUndefined();
+ expect(
+ floorExplanation({
+ input: { minConfidence: 0.5 },
+ ranked: [
+ { name: 'Route 1', percent: 63, chosen: true },
+ { name: 'Otherwise', percent: 4, chosen: false },
+ ],
+ }),
+ ).toBeUndefined();
+ });
+});
diff --git a/packages/web/test/app/builder/step-settings/ai-router-settings/route-description.test.tsx b/packages/web/test/app/builder/step-settings/ai-router-settings/route-description.test.tsx
new file mode 100644
index 00000000000..081a2e96163
--- /dev/null
+++ b/packages/web/test/app/builder/step-settings/ai-router-settings/route-description.test.tsx
@@ -0,0 +1,274 @@
+/**
+ * @vitest-environment jsdom
+ *
+ * The AI Router panel swaps between a master view (Input, Question, Match,
+ * Routes, Confidence floor) and a detail view (one route's description). Both
+ * views begin with a FormField, so unless the detail field carries a key React
+ * keeps the same FormField instance and only swaps its `name`. react-hook-form's
+ * useController then unregisters the previous name when the new one is not in
+ * a field array (detail -> master deletes the description you just typed), and
+ * seeds a missing value from the default it captured at mount (master -> detail
+ * shows the Input text as the route's description).
+ *
+ * The component is rendered for real with a real react-hook-form. The builder
+ * store, the canvas, the mentions editor and the routes list are stubbed; the
+ * form fields render for real. This file uses raw react-dom + React's act
+ * rather than @testing-library/react (not a dependency of this package).
+ */
+/* eslint-disable testing-library/no-unnecessary-act */
+import {
+ AiRouterAction,
+ BranchExecutionType,
+ EmptyTrigger,
+ FlowActionType,
+ FlowTriggerType,
+} from '@activepieces/shared';
+import * as React from 'react';
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { FormProvider, useForm, type UseFormReturn } from 'react-hook-form';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+type BuilderStateStub = {
+ selectedStep: string;
+ selectedBranchIndex: number | null;
+ flowVersion: { trigger: EmptyTrigger };
+ applyOperation: () => void;
+ setSelectedBranchIndex: () => void;
+ addOperationListener: () => void;
+ removeOperationListener: () => void;
+};
+
+const builder = vi.hoisted(() => {
+ const listeners = new Set<() => void>();
+ let state: BuilderStateStub | undefined;
+ return {
+ get: () => state,
+ set: (next: BuilderStateStub | undefined) => {
+ state = next;
+ listeners.forEach((listener) => listener());
+ },
+ subscribe: (listener: () => void) => {
+ listeners.add(listener);
+ return () => listeners.delete(listener);
+ },
+ };
+});
+
+vi.mock('i18next', () => ({ t: (key: string) => key }));
+
+vi.mock('lucide-react', () => ({ Split: () => null }));
+
+vi.mock('@xyflow/react', () => ({
+ useReactFlow: () => ({ fitView: () => {} }),
+}));
+
+vi.mock('@/app/builder/builder-hooks', () => ({
+ useBuilderStateContext: (selector: (state: BuilderStateStub) => unknown) => {
+ const state = React.useSyncExternalStore(builder.subscribe, builder.get);
+ if (!state) {
+ throw new Error('builder state is not set');
+ }
+ return selector(state);
+ },
+}));
+
+vi.mock('@/app/builder/flow-canvas/utils/flow-canvas-utils', () => ({
+ flowCanvasUtils: { createFocusStepInGraphParams: () => ({}) },
+}));
+
+vi.mock('@/app/builder/piece-properties/text-input-with-mentions', () => ({
+ TextInputWithMentions: ({ initialValue }: { initialValue?: string }) => (
+ <input data-testid="mentions-input" defaultValue={initialValue ?? ''} />
+ ),
+}));
+
+vi.mock('@/app/builder/step-settings/router-settings/branches-list', () => ({
+ BranchesList: () => null,
+}));
+
+vi.mock('@/app/builder/step-settings/router-settings/branches-toolbar', () => ({
+ default: () => null,
+}));
+
+vi.mock('@/components/custom/searchable-select', () => ({
+ SearchableSelect: () => null,
+}));
+
+vi.mock('@/components/ui/select', () => ({
+ Select: ({ children }: React.PropsWithChildren) => <div>{children}</div>,
+ SelectTrigger: ({ children }: React.PropsWithChildren) => (
+ <div>{children}</div>
+ ),
+ SelectValue: () => null,
+ SelectContent: ({ children }: React.PropsWithChildren) => (
+ <div>{children}</div>
+ ),
+ SelectItem: ({ children }: React.PropsWithChildren) => <div>{children}</div>,
+}));
+
+// eslint-disable-next-line import/first
+import { AiRouterSettings } from '@/app/builder/step-settings/ai-router-settings';
+
+declare global {
+ // eslint-disable-next-line no-var
+ var IS_REACT_ACT_ENVIRONMENT: boolean;
+}
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+type AiRouterFormShape = Omit<AiRouterAction, 'children' | 'nextAction'>;
+
+const INPUT_TEXT = 'Hello from the trigger';
+const TYPED_DESCRIPTION = 'Payments, invoices, refunds';
+
+let container: HTMLDivElement;
+let root: Root;
+let formApi: UseFormReturn<AiRouterFormShape> | undefined;
+
+function buildStep(
+ firstRoute: AiRouterAction['settings']['branches'][number],
+): AiRouterAction {
+ return {
+ name: 'step_1',
+ displayName: 'AI Router',
+ type: FlowActionType.AI_ROUTER,
+ valid: true,
+ lastUpdatedDate: '2026-09-22T00:00:00.000Z',
+ settings: {
+ text: INPUT_TEXT,
+ question: 'What is this message about?',
+ branches: [
+ firstRoute,
+ {
+ branchType: BranchExecutionType.FALLBACK,
+ branchName: 'Otherwise',
+ description: 'Anything that fits none of the routes above',
+ },
+ ],
+ },
+ children: [null, null],
+ };
+}
+
+function Harness({ step }: { step: AiRouterFormShape }) {
+ const form = useForm<AiRouterFormShape>({
+ defaultValues: step,
+ mode: 'all',
+ });
+ formApi = form;
+ return (
+ <FormProvider {...form}>
+ <AiRouterSettings readonly={false} />
+ </FormProvider>
+ );
+}
+
+function setup(step: AiRouterAction, selectedBranchIndex: number | null) {
+ const trigger: EmptyTrigger = {
+ name: 'trigger',
+ displayName: 'Trigger',
+ type: FlowTriggerType.EMPTY,
+ valid: false,
+ lastUpdatedDate: '2026-09-22T00:00:00.000Z',
+ settings: {},
+ nextAction: step,
+ };
+ builder.set({
+ selectedStep: step.name,
+ selectedBranchIndex,
+ flowVersion: { trigger },
+ applyOperation: () => {},
+ setSelectedBranchIndex: () => {},
+ addOperationListener: () => {},
+ removeOperationListener: () => {},
+ });
+ container = document.createElement('div');
+ document.body.appendChild(container);
+ root = createRoot(container);
+ const { children: _children, ...formStep } = step;
+ act(() => {
+ root.render(<Harness step={formStep} />);
+ });
+}
+
+function showBranch(selectedBranchIndex: number | null) {
+ const state = builder.get();
+ if (!state) {
+ throw new Error('builder state is not set');
+ }
+ act(() => {
+ builder.set({ ...state, selectedBranchIndex });
+ });
+}
+
+function descriptionTextarea(): HTMLTextAreaElement {
+ const textarea = container.querySelector('textarea');
+ if (!textarea) {
+ throw new Error('route description textarea is not rendered');
+ }
+ return textarea;
+}
+
+async function typeIntoTextarea(textarea: HTMLTextAreaElement, value: string) {
+ const setValue = Object.getOwnPropertyDescriptor(
+ HTMLTextAreaElement.prototype,
+ 'value',
+ )?.set;
+ if (!setValue) {
+ throw new Error('textarea value setter is missing');
+ }
+ await act(async () => {
+ setValue.call(textarea, value);
+ textarea.dispatchEvent(new Event('input', { bubbles: true }));
+ });
+}
+
+function savedDescription(index: number): unknown {
+ return formApi?.getValues(`settings.branches.${index}.description`);
+}
+
+afterEach(() => {
+ act(() => {
+ root.unmount();
+ });
+ container.remove();
+ formApi = undefined;
+ builder.set(undefined);
+});
+
+describe('AiRouterSettings route description', () => {
+ it('keeps the description typed on a route after going back to the routes list', async () => {
+ setup(
+ buildStep({
+ branchType: BranchExecutionType.CONDITION,
+ branchName: 'Route 1',
+ description: '',
+ }),
+ 0,
+ );
+
+ await typeIntoTextarea(descriptionTextarea(), TYPED_DESCRIPTION);
+ expect(savedDescription(0)).toBe(TYPED_DESCRIPTION);
+
+ showBranch(null);
+
+ expect(savedDescription(0)).toBe(TYPED_DESCRIPTION);
+ });
+
+ it('shows an empty description for a route that has none, not the Input text', () => {
+ setup(
+ buildStep({
+ branchType: BranchExecutionType.CONDITION,
+ branchName: 'Route 1',
+ description: undefined,
+ }),
+ null,
+ );
+
+ showBranch(0);
+
+ expect(descriptionTextarea().value).toBe('');
+ expect(savedDescription(0)).not.toBe(INPUT_TEXT);
+ });
+});
diff --git a/packages/web/test/features/pieces/utils/step-utils.test.ts b/packages/web/test/features/pieces/utils/step-utils.test.ts
index a22a9a1d9d4..499fe87a4fb 100644
--- a/packages/web/test/features/pieces/utils/step-utils.test.ts
+++ b/packages/web/test/features/pieces/utils/step-utils.test.ts
@@ -18,6 +18,9 @@ const JAPANESE_BUNDLE = {
Router: 'ルーター',
'Split your flow into branches depending on condition(s)':
'条件に応じてフローを分岐します',
+ 'AI Router': 'AI ルーター',
+ 'Ask one question and Jev, an evaluation model, picks the route':
+ '1つの質問をすると、評価モデルの Jev がルートを選びます',
'Empty Trigger': '空のトリガー',
};
@@ -65,7 +68,7 @@ describe('core step metadata translation', () => {
it('translates every core action offered by the piece selector', () => {
const coreActions = stepUtils.coreActionsMetadata();
- expect(coreActions).toHaveLength(3);
+ expect(coreActions).toHaveLength(4);
for (const step of coreActions) {
expect(Object.values(JAPANESE_BUNDLE)).toContain(step.displayName);
expect(Object.values(JAPANESE_BUNDLE)).toContain(step.description);