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
icon: 💬
Chat
A platform-level AI chat assistant that manages Activepieces projects via natural language. Streams LLM responses over WebSocket and exposes project resources (flows, tables, connections, runs) as callable tools through the project's MCP server. Conversations persist per-user with cross-session memory (personal instructions + remembered facts injected into every turn), compaction, attachments, multi-project context, and two-phase tool gating. EE/Cloud only (not registered in CE).
Execution model (read first)
The chat LLM loop runs in the worker, not the API. Send path: agent-conversation-controller.ts (POST /conversations/:id/messages) enqueues a WorkerJobType.EXECUTE_AGENT_RUN job → worker execute-agent-run.ts calls getAgentConfig RPC, assembles tools, runs run-agent-turn.ts (shared streamText() DI loop) → chunks stream back via sendAgentEvent RPC → websocket CHAT_MESSAGE_CHUNK (filtered by runId) → frontend reducer. agent-conversation-service.ts only does conversation CRUD + persistence.
Entities & services
- ChatPersonalization (
chat_personalization) — first-run onboarding: role + company, background research, researched empty-state cards. See chat personalization. - AgentConversation (
agent_conversation) — per-user, per-platform, optionally per-project;statusSTREAMING/IDLE/ERROR,activeRunId,messages(ModelMessage[] JSONB),uiMessages,summary/summarizedUpToIndexfor compaction. - UserMemory (
user_memory) — one row per (platformId, userId):instructions(nullable text) +memories(jsonb string[]); capped at 50 facts × 280 chars and 4000 chars of instructions (agentHelpers.capMemories). Every write tomemoriesis{ next, base }and goes through a three-way merge under a row lock (agentHelpers.saveUserMemory); there is no blind overwrite, so a writer working from a stale list can't resurrect removed facts or wipe ones saved meanwhile. - Tool logic in
ee/agent/; shared tool phase/classification incore/shared/.../ee/agent/.
How it works
- Tools: local (
ap_execute_action,ap_select_project,ap_fetch_url…), display cards (ap_show_connection_picker,ap_show_questions,ap_show_quick_replies…), and project-scoped MCP tools. Each tool is wired across up to four files — see gotcha: a chat tool lives in four files. - Two phases — every message starts in
discoveryand moves tobuildwhen a build skill loads (entersBuildPhase) or a build-only tool runs, including throughap_lazy_tool. It never goes back within a message. In skills mode the phase only turns thinking on; it does not hide tools and does not change the model (the fast model is step one only). - Gates (Redis pub/sub, 5-min timeout): display-tool cards, the action-run action preview, and the test-flow write gate. Flow build + publish are NOT gated.
- Web access:
ap_web_searchis Tavily when configured, otherwise a sub-call to the provider's own search on the configured LLM credential (Anthropicweb_search_20250305, Google grounding, OpenRouterwebplugin);ap_fetch_urlworks everywhere. - Cross-session memory: instructions + facts injected into every turn (
buildMemoryNoteinagent-rpc-handlers.ts). Writes go throughagentMemoryAi.applyInstruction— an LLM reconcile on the fast-tier model (add/forget, dedupe, supersede contradictions; non-AI fallbacks so it never hard-fails) — used by both theap_remembertool and the/v1/chat/memory[/import|/instruct]endpoints; concurrent saves are merged under apessimistic_writelock. UI lives in the settings hub (packages/web/src/app/components/settings-hub/). - Billing & credit gating:
POST /conversations/:id/messagesgates pre-enqueue —assertCreditsAndAppSumoNotExceededblocks ALL chat (any provider) on the platform's credit/AppSumo balance (QUOTA_EXCEEDED), next to a per-user rate limit (40 messages / 10 min, HTTP 429). After each turnchatUsageTracker.trackmeters Autumn credits withcreditValue = creditWeight + billableToolCalls(tier's weight for the managed ACTIVEPIECES provider, default 2; 1 for BYO), idempotency key{conversationId}:chat:{turnIndex}(CreditUsageSource.CHAT), plus the AppSumo meter on AppSumo plans; it then emits the PostHogchat_messagebilling event (skipped when the platform has no license key — the Autumn tracking always runs).chat-tool-billing.tsdecides which tool calls bill: everymcp__tool plus a fixed set (ap_web_search,ap_scrape_url,ap_generate_image,ap_execute_action,ap_explore_data,ap_run_code).
Turn liveness — three independent timers (get this right)
A turn is kept alive / reclaimed by three separate mechanisms in execute-agent-run.ts; confusing them causes "chat randomly stops" bugs:
- Heartbeat (
HEARTBEAT_INTERVAL_MS15s): asetIntervalthat bumpsconversation.updated(viaheartbeatAgentConversationRPC) + sends an empty keepalive chunk, so a live-but-slow turn is never reclaimed as stale. - DB stale-recovery (
STREAMING_STALENESS_TIMEOUT_MS90s,agent-helpers.ts): on-read (getConversationOrThrow) + a per-minute sweep flip any STREAMING conversation whoseupdatedis >90s old back to IDLE. The heartbeat is what holds this off. - Stream idle watchdog (
STREAM_IDLE_TIMEOUT_MS90s, instreamChunksToClient): aborts the turn if the drain-stream reader is silent 90s. It must be SUSPENDED while legitimate silent work is in flight — pending tool calls AND in-flight reasoning (reasoning-start→reasoning-end). Reasoning-awareness was missing and caused the bug where long "thinking" on the Expert tier randomly aborted a healthy turn (a >90s gap between reasoning deltas looked like a wedge). Backstop for a genuine mid-reasoning wedge isMAX_TURN_WALL_CLOCK_MS(20 min).
Gotchas
A piece's declared classification beats its action name.
agentToolClassificationstill guesses read or write from words in the action name, but a piece that declaresREAD,SEARCH,WRITEorDESTRUCTIVEwins:mark_as_readandadd_member_to_listare writes. The API refuses a declared write inap_explore_data(runAgentAction,readOnlyOnly), and the worker's approval card asks the API through__action_read_onlybefore deciding. If that lookup fails, the gate falls back to the name rule.custom_api_callkeeps following its HTTP method (AI-106).Compaction is not metered.
getAgentConfigbuilds the compaction model withaiUtils.createModeland nobilling, so the summarizing call on the main model never reaches credits or usage reporting. Count it by hand when measuring cost per turn.Bedrock ignores our cache and thinking options.
agentProviderOptionssendsanthropic.cacheControlandanthropic.thinkingfor BEDROCK, but@ai-sdk/amazon-bedrockreads onlybedrock/amazonBedrockkeys (cachePoint,reasoningConfig). Bedrock chat therefore runs with no prompt caching and default thinking.Tiers only resolve on Anthropic-shaped providers.
PublishedTier.nativeModelIdis a single Anthropic id. On OpenAI and Google bothfastandsmartfall to the first curated model; on Azure and Bedrock the fast model is passedfallbackModelId: resolvedModelId, so it equals the main model.Managed chat has no system-prompt cache breakpoint.
buildSystemPromptWithCachingsets one only for ANTHROPIC/BEDROCK; managed/OpenRouter rely on automatic caching at the end of the request. So any change to the tool list or thinking settings (the discovery→build flip swapsactiveTools) rewrites the whole ~22k-token prefix.@openrouter/ai-sdk-providerdoes honorcacheControlon system messages.Refusals aren't handled. Nothing branches on
content-filter. A refused step with no visible output hitsdecideLoopAction→continue_emptyand re-sends the full context with "Continue".The per-user tail breaks the prompt cache. The date, memory, connection inventory and
{{PROJECT_LIST}}sit inside the same single system block as the ~22k-token static prompt. Any change re-writes the whole cached prefix, and the prompt is effectively unique per user.A step's
response.messagesholds only that step's messages (AI SDK v7). The older SDK made it cumulative, socollectStepMessagesonce took the last step; under v7 that saved only a turn's closing text and dropped every tool call and result. The next turn then saw replies like "New agent is updated" with no tool call behind them, and repeated the pattern by claiming changes it never made. It now joins every step, andrun-agent-turn-history.test.tsruns a realstreamTextturn so a future SDK change to these semantics fails loudly.Chat has no fixed step cap. A chat turn is bounded by credits (checked after every step), the runaway-token ceiling (
RUNAWAY_TURN_CONTEXT_MULTIPLE× the context window), the identical-failure guard and the 2-hourMAX_AGENT_TURN_WALL_CLOCK_MS, so it finishes long jobs. A saved agent's author-setmaxStepsis still honored on its last step: an agent with structured output is forced to callTASK_COMPLETION_TOOL_NAMEso the flow gets a result, and any other agent runs withtoolChoice: 'none'plus a wrap-up note, so it replies with what's done and what's left. Never a silent stop or an error.A turn limit only works as a stop condition. One
streamTextcall runs every step of a turn, so a check after it returns can't stop a runaway. The token ceiling used to be checked only there, and a turn on 24 Oct 2026 ran 181 steps and 50.8M input tokens (AI-86). Put every per-turn bound inloopStopCondition. Test mocks must report usage in the V3 shape (inputTokens: { total, ... }); flat numbers read as 0 tokens.The streaming lock is per run, not per conversation. A re-send can claim
activeRunIdbefore the first job reachesgetAgentConfig.agentHelpers.acquireStreamingLockonly lets the owning run set STREAMING; an older run getsAGENT_RUN_SUPERSEDEDand the worker exits quietly, with no ERROR save and no events. A lock that ignoredrunIdlet the old run stream unowned while the new one was rejected as busy and marked ERROR, which is how users saw nothing after tapping a starter card twice.A redelivered run is a duplicate, not busy. A worker socket blip makes the app requeue a chat job whose worker is still running it (
releaseConnectionJobs). The second delivery finds its ownactiveRunIdSTREAMING, soacquireStreamingLockreturnsduplicateand it exits quietly like a superseded run. When this came back asbusyit saved ERROR, and users saw "An agent is already running for this conversation" in the middle of a working turn (prod, 2026-10-13). If the first worker really died, the 90sCHAT_STALE_SWEEPfrees the conversation. This only works when the conversation carries the run'sactiveRunId: chat claims it in the controller, and a flow-step run claims it whengetAgentConfigcreates the conversation. Without that claim the redelivery read asbusyand failed the job (prod, 2026-10-21). A copy that arrives after its run already finished finds the row IDLE, so the lock alone would let the agent run again and its tools act twice (AI-153).acquireStreamingLocktherefore also sets a Redis marker per conversation and run (agent-run-started:<conversationId>:<runId>, 24h) withputIfAbsent, and any later delivery of that run is aduplicate. That's safe because every enqueue mints a freshrunIdand agent jobs run withattempts: 1. If the first worker really died, the redelivery is still dropped, soCHAT_STALE_SWEEPfails the step itself: a flow-step conversation keeps itswaitpointId, and the sweep resumes that waitpoint with afailureresult, so the flow doesn't sit paused until the 3h step timeout. It never re-runs the agent, because its tools may already have acted.A flow-step run that loses its
getAgentConfigresponse exits quietly, and the redelivered copy finishes it. A socket drop mid-RPC surfaces on the worker asRpcTimeoutError.disconnected. The API handler doesn't stop when the socket drops: it still takes the streaming lock, so the copy used to getduplicateand the step failed, either right away as "provider temporarily unavailable" or 90s later throughCHAT_STALE_SWEEP. Now the worker exits quietly on a disconnect, andgetAgentConfiginworker-rpc-service.tscallsagentHelpers.handLockToRedeliverywhen the worker socket is gone by the time it replies. That writes a one-timeagent-run-handed-offtoken (60s), and the next delivery of that run consumes it inacquireStreamingLockinstead of being dropped ('handed-off'), so the copy runs the step (AI-156). The first delivery already saved the user message, so a handed-off copy re-reads the history after the lock and does not append it again. The hand-off never touches the row: setting it IDLE would hide the run fromCHAT_STALE_SWEEPwhen the copy was already turned away, and the flow would sit paused for 3h. The token's TTL is shorter than the sweep window, so a late copy can't revive a step the sweep already failed. A plain timeout on a live socket is never redelivered, so it still fails the step. Chat still reports the error, because its buffered emits would mark ERROR over a copy that is streaming.A failed turn used to leave status ERROR with an empty reply. The error text only travelled as a websocket
ERRORevent, so a reload, another tab, or a user who was away saw a dead conversation (and often no user message either when the job died insidegetAgentConfig, before it persists the turn). Theexecute-agent-run.tscatch now sendsfailure: { message, userMessage? }on the emptysaveAgentMessagescall andconversation-rpc.tsappends it touiMessagesas an assistant text reply;use-chat.tsshows the Retry banner when a loaded conversation is ERROR. Stale STREAMING to IDLE recovery, a worker that never picks the job up, andassertAgentMessageRateLimitNotExceededstill leave no reply of their own.A built flow ends with a "Turn it on?" card, never an auto-publish: an audit found 40% of built-but-unpublished flows ended on "open it to review", some claiming LIVE. Chat never publishes on its own; only a yes to the card calls
ap_lock_and_publish(build_flow.md"Turn it on?"). Pinned by thebuild-then-ask-turn-it-onfixture (askedToTurnItOn,noLiveClaimWithoutPublish). The live-claim check is a regex plus "wasap_lock_and_publishcalled", so it cannot see whether publish succeeded.Server-managed connections: the LLM never sees connection externalIds;
ap_execute_actionauto-fills them from a Redis store.Prompt-injection taint: a per-turn
taintStateflips totaintedonce the turn reads outside or user data (MCP tools, web/search/scrape,ap_explore_data,ap_execute_action,ap_run_code,ap_list_across_projects, configured tools). It forces the action-preview gate on non-read-only actions, makes saved-agent edits (ap_update_agent,ap_add_agent_tool,ap_remove_agent_tool,ap_create_agent) ask for approval on the action card instead of refusing, and makesap_rememberask before saving (memory reaches every future conversation). It carries one message: each saved reply storestainted(this reply's own reads, viacreateTaintState), and the next message starts from it. Deletes are confirmed always, not by taint.Write-check gate: before a live
ap_test_flow,__flow_write_checkRPC flags write/destructive PIECE steps; read-only flows run ungated; if the check itself errors, the approval card still shows (fails closed).Chat follows the plan on Cloud and Enterprise.
chatVisibilityreturnsplan.chatEnabledon both, and Community and embedded sessions never see chat. Chat reaches a Cloud user only throughCHAT_ENABLEDon their Autumn plan, whichtoPlatformPlanFlagswrites tochatEnabled; the code has no Cloud override.Flow correctness is 100% prompt/guide-driven — nothing in code enforces it. The "#1 silent bug" ("Class A"): the agent frames a recurring automation as a one-time task and omits any anti-reprocessing step, so run N+1 redoes run N's work (re-pays, re-sends). It's a design-time reasoning gap, not a testing gap —
ap_test_flowruns ONCE, so a single test looks perfect; the bug only shows on the 2nd run. Fix lives in the prompt (chat-system-prompt.md<decision_framework>+build_flow.md"Recurring flows must not reprocess") + capability eval fixtures with arecurring_avoids_reprocessingjudge dimension. The platform already has every primitive (Tables New-Record webhook, pollingDedupeStrategy,_dedupe_key, Store, update/delete-record); the agent just wasn't reaching for them. Watch thebuild_flow.md"don't over-build" bias — it once actively discouraged the fix.Compaction runs inside the 60s
getAgentConfigRPC, so it must stay bounded. The summarizer call is capped atSUMMARY_OUTPUT_RESERVE_TOKENSand aborted afterCOMPACTION_TIMEOUT_MS(35s). On failure the previous summary is kept andbuildCompactedPayloadstill fits the history to the budget, flagging trimmed messages to the model. An unbounded summary once ran for 2.5 min and failed the turn asRPC [getAgentConfig] failed (timeout: 60000ms).The eval replay harness drifts silently when a worker tool's signature changes.
buildEvalToolSet(agent-eval/core/runner.ts) hand-builds the tool set with stubs, and nothing type-checkstest/lib/agent-eval/in CI, so a new required param never fails a build. Until Oct 2026 the eval passed notaintStatetocreateCrossProjectTools(every data tool threw, transcripts showedTOOL_RESULT: null, and fixtures like the injection one never saw their data),onSetProjectContextreturned void, and approvals lackedoutcomeso all counted as declined. When you change a tool factory's params, update the eval stubs too, and treatTOOL_RESULT: nullin an eval transcript as a harness bug, not agent behaviour. Check withnpx tsc -p packages/server/worker/test/lib/agent-eval/cli/tsconfig.json --noEmit.An eval verdict is a majority over repeats, graded by a different model. LLM output is random, so one run proves little (two full runs of the same commit 13 seconds apart, Oct 2026, scored 55/78 vs 54/78 repeats but disagreed on 7 of 26 fixtures):
CHAT_EVAL_REPEATS(nightly 3) runs each fixture N times; judge dimensions pass on a majority, but a deterministic assertion must hold on every run (one run that emails the attacker is a real failure, not noise). The report showspasses/runsand the first failing run's checks;runVerdictsin the JSON keeps every run. The judge isCHAT_EVAL_JUDGE_MODEL(default an Opus slug), never the agent's own model, which went easy on itself. The judge's transcript carries each tool call's input and result, not just its name, so it can see where an email went. The report's "expected-label match" only compares the judge to each fixture'sexpectedLabel, so an agent miss counts as a judge error; judge accuracy is the separate "judge vs human labels" line, from person-reviewed cases inagent-eval/calibration/. A model-written label measures Claude against Claude, so labels carrying"labelledBy": "claude"are excluded from it and only feed a separate "draft estimate" line until a person reviews them. Each run is published (public) tocdn.activepieces.com/ai/evals/runs/. Nightly runs cover gate fixtures only; a Sunday 07:00 UTC run covers all fixtures, and only those full runs feed the Config Console's Agent score (share of repeats passed), whose "+N pts" compares just the fixtures present in both runs so adding a fixture never fakes a gain. Prefer a deterministic assertion (noToolArgMatches,neverCalledTool) over a judge dimension wherever code can see the behaviour.A stopped
npm run agent-evalskeeps nothing and leaks its key. The CLI writes.agent-eval/last-run.jsononly after every fixture, and Ctrl-C skipscleanupAuth, so the minted "activepieces-agent-eval (ephemeral)" OpenRouter key ($25 cap) stays alive until deleted by hand. Try a model with--limit 3or--only <ids>first. The cost it shows is what OpenRouter reported for the agent's own calls, and—means some call reported none; judge cost is a separate line.The context budget subtracts what the request reserves. Anthropic/OpenRouter count tool schemas and the reserved
max_tokensagainst the 200k window, sogetAgentConfigpassesreservedTokens(the clamped output window fromagentAiUtils.affordableOutputTokens, the same helper the worker uses formaxOutputTokens, plusTOOL_SCHEMA_TOKEN_ESTIMATE = 12_000) intoagentCompaction. The threshold, the fit check and the recent window are all measured againstmaxContext - reservedTokens, and the recent window is sized by estimated tokens, not message count. The tool-schema figure is a constant because the tools are built in the worker and the API never sees their definitions. The worker setsmaxOutputTokensper step inprepareStep, so a thinking-disabled step (round one, discovery phase) does not reservethinkingBudget. The system prompt's size is added to the reserve for the window and fit check, and each message is capped at 20k chars in the summary request so the summarizer itself cannot overflow.ap_set_phaseandap_load_guideare gone. Skills replaced both:ap_load_skillreturns the guide and its tools' schemas, and the build phase flips on its own.BUILD_ONLY_TOOL_NAMESnow only decides when thinking turns on, and only hides tools on surfaces outside skills mode. The web app keeps both names so old conversations still render.Read-only checks don't belong in
BUILD_ONLY_TOOL_NAMES.ap_validate_flowwas in it, so "check that this solution fits together" never saw the tool. The agent inspected flows by hand instead and misread a Call FlowflowId(an externalId) as a mismatch with the flow's id. It now stays visible in discovery, likeap_flow_structure.A dynamic property only runs with a saved schema. The engine processes a
DYNAMICprop's sub-fields (JSON parse, numbers, arrays) only frompropertySettings[prop].schema, which the builder saves when it resolves the prop. Chat tools used to savepropertySettings: {}, so an advanced-mode Call Flow payload reached the subflow as one string and a live run saved empty fields.mcpUtils.resolveDynamicPropertySettingsnow resolves and saves it on build, add and update.Focused goals run as task sub-agents.
ap_run_task(task-subagent-tools.ts) runs a secondrunAgentTurnwith a fresh context and the main's tools, minus anything that talks to the user, nests, tests, publishes or flips flow status. The prompt istask-subagent-prompt.md. Tasks start in the build phase with their ownap_set_phase: any tool whose closure holds run state must be rebuilt per task, because reusing the main's copy flipped the main's phase. A task must end withupdateTaskStatus. If it's cut off it continues (up to 2 times), and if it forgets to report it gets one forced report step, sofailedis rare and the main retries it. Histories live inagent_task, sotaskIdresumes the same sub-agent. Approvals inside a task carrytaskTitle(viaAsyncLocalStorage). Flat-billed calls come back asbilledToolCalls, andtoModelOutputkeeps the card data out of the main's context. Delegation happens only when it buys something: multi-flow solutions build in dependency waves, one task per flow; single flows stay with the main.Research goes through
ap_deep_research, not prompt rules. Prompt rules alone got research delegated in 3 of 8 runs, because the model reaches for the quickap_web_search. A dedicated tool whose name matches the intent fixed it. It runs one task per subject under progress idstoolCallId:index, and the web expands it into one row per subject. Its timeline (statuses, searches, page reads) streams into the right-side task panel (task-panel.tsx), which opens on its own on the first search.Capability notes are built where
discoveryOnlyis not known, so a prompt can promise tools the worker has stripped.getAgentConfigcomposes the system prompt in the api, whilediscoveryOnlyrides on the job data; before Aug 2026 it never crossed that boundary. Meanwhile the worker strips image tools, email tools and the agent tools on such a run, so the notes claimed all three. Two of the three had been wrong since long before anyone noticed, because each note computed its own availability term. The flag now travels with the config request and the three notes read one sharedactingRun = !dryRun && !discoveryOnly. Whenever a tool group is gated on a run mode in the worker, the note that advertises it has to be gated on the same term, in one place.Tool output can't be trusted to waive a charge. A user's own MCP server or
ap_run_codecontrols its output's top-level keys, and they reach the persisted part unchanged. Chat billing only honoursbilledAtCostfromap_web_searchandap_generate_image; a new built-in tool that bills at cost must be added toTOOLS_THAT_BILL_AT_COSTinchatBilling.Credits are checked after every step, not just before the turn.
runAgentTurnasks the API (agentHasCredits) after each tool step, sending what the turn has used so far (chatBilling.creditsForTurn, the same rule end-of-turn billing uses), and stops once the remaining balance no longer covers it. Flat credits are only charged when the turn ends, so without that pending count the balance never moves mid-turn. The check fails open if the RPC errors.Chat files belong to a conversation, not just a project. Conversations are private to their user, so a project check is not enough.
saveAgentFileandpersistAgentAttachmentsstampconversationIdinto the file metadata, andreadAgentFilerefuses a file whose stamp doesn't match. Files saved before the stamp existed can't be read back (image editing can't use them). Any tool that reads chat files by a model-supplied ID must go throughreadConversationFile(agent-file-utils.ts), and any new save that hands the model a file ID must stampconversationId.Local dev needs
AP_DB_TYPE=POSTGRES+ Redis; refuses PGLite. PreferAP_EDITION=cloudovereefor chat work. Cloud boots locally against plain Postgres and Redis with no Autumn, Stripe or license-key config (verified Aug 2026: API healthy, migrations applied, zero billing or license errors), and on Cloud chat followsplan.chatEnabled, so set it on the local platform's plan. Oneeit is gated behindplan.chatEnabledand you have to get a plan onto the platform first. Note SMTP is usually unset locally, which makes the auth card open on the password form rather than the email-code step. Debug a run withnpm run chat:logs -- <conversationId> [runId](needsLOG_FILE=true/AP_LOG_FILE=trueset when the turn ran — otherwise.evlog/logsis empty).Chat was renamed to agent in code and DB, but only the storage half. As of release 0.87.1 (
1823000000000-AddRenamedChatTableCompatViews)chat_conversation→agent_conversationanduser_chat_memory→user_memory, the server module movedee/chat/→ee/agent/(entry pointagentModule), the worker dir movedjobs/ee/chat/→jobs/ee/agent/, shared types movedcore/shared/.../ee/chat/→.../ee/agent/, andserver/utils/src/chat-ai-utils.ts→agent-ai-utils.ts. The rename is not uniform, and the split is the thing to learn: files describing chat as a user-facing surface deliberately kept theirchat-names insideee/agent/—chat-visibility.ts,chat-analytics-sync.ts,chat-tool-billing.ts,chat-usage-tracker.ts,chat-plan-grant.ts. So a new chat-surface concern keeps thechat-prefix; a new stored entity takesagent_. The migration also leavesCREATE OR REPLACE VIEWcompat views at both old table names, so raw SQL againstchat_conversationstill reads fine and will NOT tell you the rename happened — grep the entity, not the database.An AI SDK major bump can typecheck clean while a callback payload silently changed shape. v7 keeps most v6 option names as working deprecated aliases (
system,onStepFinish,experimental_repairToolCall,stepCountIs,result.toUIMessageStream), so the option compiles but the data underneath can differ:experimental_onToolCallFinishsurvived as an alias foronToolExecutionEndwhile its event lostdurationMs/success/error(nowtoolExecutionMsplus atoolOutput.type === 'tool-result'discriminator). A type-probe that only names the option passes; you have to exercise each callback's property access.onStepEnd'scontentis also cast to a structuralContentPartLikewith anargs ?? inputfallback (agent-ai-utils.ts), which means a shape change there fails at runtime, not compile time — always smoke a real turn after a provider/SDK major.aiandevlogare version-coupled. evlog ≤2.18.1 importsTelemetryIntegrationfromai, which v7 renamed toTelemetry, so bumpingaito 7 without bumpingevlog(≥2.22.4, which peersai >=6.0.168 <8.0.0and supports both v6 and v7 hooks) will not compile. That evlog bump in turn changesDefinedAuditActionfrom<TargetType>to<Action, Options>and breakshelper/audit-events.ts— drop the explicit annotation and letdefineAuditAction's inference supply it.AI SDK v7 is ESM-only, and that is NOT a reason to convert the server to ESM.
ai@7shipstype: modulewith norequirecondition, but the CJS server consumes it fine through Node'srequire(esm)(Node 22.12+/24, verified), and TS 5.5.4 resolves its types undermodule: CommonJS+moduleResolution: nodebecause a rootmainand an adjacentindex.d.tsstill exist andskipLibCheckis on. No ESM migration, no TypeScript upgrade. Mixedaimajors across workspaces are also safe and intentional —bunfig.tomlsetslinker = "isolated", so pieces/framework/engine can stay on v6 while the agent path runs v7.ap_show_connection_requiredis an alias ofap_show_connection_picker, not a smaller capability. Both names resolve to the sameConnectionPickerCard, which lists every account the caller has for that piece and offers "Use a different account"; the only schema difference is an optionalstatus: 'missing' | 'error'hint. So an allow-list that grants one name and asserts the other is absent proves nothing: verified live on the agent surface, granting onlyap_show_connection_requiredrenders "Which account should I use?". The card also fetches the account list itself from the frontend, keyed byconversationId, so the tool payload cannot constrain what it offers. A repair-only variant therefore lives in the endpoint feeding the card, not in the tool set.On a saved-agent run, choosing a different account in the connection card does nothing.
onConnectionSelectedwrites intoselectedConnectionByPiece(execute-agent-run.ts), which is read only throughgetSelectedAuth, passed only to the MCP tool set — andAgentRunSource.AGENTis not grantedgroups.mcpat all. Configured piece tools carry the agent's storedpieceMetadataauth instead. So the card reports the account as connected while the tool keeps calling on the pinned one. Only the in-place Reconnect actually repairs an agent run, because it re-authorizes the same connection row the agent is pinned to. So/v1/agents/conversations/:id/connectionsanswers{ connections, reconnectOnly }, and for anAGENT-source conversation returns only the accounts that agent's tools pin. Three things that branch has to get right, each of which was a live bug first: match on(projectId, externalId), becauseexternalIdis caller-supplied and its index is not unique, so a same-id row in another project can pose as the pinned one; read the pin throughpublished ?? draft, the same as the run; and unwrap the pre-0.87{{connections['id']}}template form, or an older agent reads as having no pinned account and the card tells the user their live account is gone. The card must also carry the row's ownprojectIdinto the reconnect dialog, which otherwise falls back to the session project and repairs the wrong one.A task agent's cost is steps × context, and a cache read isn't free. A cache read still costs 10% of the normal input price, so a 30-step task over a 30k context costs about $0.60 on Sonnet even with 92% cache hits. Three things broke task cost (measured 2026-10-11): a status-only step every other step (tasks get no
ap_update_thinking_status; the card falls back to the latest tool title), a report turn that swapped the tool set (any change to the tools, oractiveTools, re-writes the whole cached context: 25–44k at write price), and researchers on Sonnet with full 128KB pages. After the fixes a researcher costs 3–5¢ on Haiku. Builds are the opposite: a task per flow costs $0.21–0.38 because it repeats the chat's setup, while the main chat builds four flows with parallelap_build_flowcalls for about $0.51, so builds stay in the main chat.The chat's internal MCP token lives as long as a turn can (2 hours), not 15 minutes. It's issued once per turn by
issueChatTurnAccessToken(called fromagentMcp.getCredentials) and kept in worker memory.issueInternalAccessToken, which the/mcp-server/tokenroute hands to callers, keeps 15 minutes. With the 15-minute outside-client lifetime, any turn that waited on a card long enough lost everyap_*tool with "authentication failed" and stopped half done. Outside MCP clients keep their 15-minute tokens.
Key files
Entry point: agentModule, the Fastify plugin registered in packages/server/api/src/app/app.ts.
packages/server/api/src/app/ee/agent/— the API module: controllers, service, helpers, approval gate, compaction, console sync, billing (chat-usage-tracker.ts,chat-tool-billing.ts), memory (agent-memory-ai.ts,user-memory-entity.ts), entities, plustools/,mcp/,prompt/,history/subdirspackages/server/worker/src/lib/execute/jobs/ee/agent/— where the LLM loop actually runs:execute-agent-run.tsjob handler (+ the three liveness timers +streamChunksToClientidle watchdog),run-agent-turn.tsDI streaming loop,agent-worker-tools.tstool defspackages/server/utils/src/ai-utils.ts— the provider-agnostic half:createModelper provider,createEmbeddingModel/toStorageEmbedding,supportsWebSearch/buildWebSearchToolspackages/server/utils/src/agent-ai-utils.ts— what is genuinely agent-shaped:collapseStaleToolOutputshistory hygiene, theonStepEndcontent handlingpackages/core/shared/src/lib/ee/agent/— shared zod schemas and types,tool-phases.tsgating,tool-classification.ts,chat-visibility.tspackages/server/api/src/assets/prompts/— system prompt + project-context markdown and the on-demandguides/; agent-eval fixtures live inpackages/server/worker/test/lib/agent-eval/packages/web/src/app/routes/chat-with-ai/— the chat page, chat box, conversation list, andcomponents/cardspackages/web/src/features/chat/— API client, Zustand store,use-chat.ts,chunk-reducer.ts, streaming and voice hooks
Paths verified 2026-08-19 against main. An earlier version pointed at ee/chat/chat-model-factory.ts and ee/chat/chat-history-hygiene.ts; both were folded into packages/server/utils/src/agent-ai-utils.ts. Every ee/chat/ path on this page before that date is dead — see the chat-to-agent rename gotcha above.
setConversationIdis a reload, not a setter. It callsstopStream(), resets the interaction stores and refetches history, so handing it the id of a conversation the hook is already in destroys the turn in flight.AIChatBoxseeds it from theconversationIdprop in an effect, which makes the obvious wiring — feedonConversationCreatedback into that prop — kill the very turn that created the conversation: the pane goes blank while the reply completes fine on the server. It now early-returns when the id is unchanged, so re-seeding is a no-op, but the shape is worth knowing before adding another caller.