fix(pipeline): tell the customer when the AI backend fails (CRM-236) - #9
Merged
Merged
Conversation
When the LLM provider degrades the turn exceeds the ceiling and the pipeline only logged and cleared state — nothing reached the chat. For the customer that is indistinguishable from a bot ignoring them, and it is worse than it looks: the tool's side effect may ALREADY be applied. In the live run the pipeline card moved at ~20s and the timeout fired at 30s, so the funnel advanced while the conversation stayed silent. Two changes. 1. AI_CALL_TIMEOUT_SECONDS default 30 -> 90. Measured against gemini-2.5-flash, the SAME trivial prompt answered in 0.74s / 0.79s / 1.36s / 10.34s / 20.40s — a 27x spread on the provider's tail. A tool-calling turn makes at least two of those round trips (decide the tool, then write the reply), so two bad tails alone exceed 30s with nothing wrong in the code. 90s covers that and still bounds a genuinely hung provider. Note this is NOT the fix on its own: raising a ceiling only moves it. The notice below is what protects the customer when the ceiling IS reached. 2. On timeout or error, dispatch a plain sentence to the conversation instead of silence. The provider's raw error never reaches the customer — it carries model names, quota ids and URLs (litellm.RateLimitError: ... limit: 20, model: gemini-2.5-flash) — it goes to the operator's log as `cause`. AI_FAILURE_NOTICE overrides the text; setting it empty keeps today's silence for operators who prefer it. Tests: 6 in pkg/pipeline/service/ai_failure_notice_test.go — the customer is told, the provider error never leaks, the text is overridable, empty disables it, a missing postback url is not a crash, and the default holds when the env is unset. go build + go vet clean; full suite green (pkg/... and internal/..., Redis-backed). Not addressed here, deliberately: the processor keeps working after the bot-runtime gives up, and the provider's 429/503 still surfaces as a generic 500 on the A2A route. Both are real and belong to the processor side.
Reviewer's GuideExtends AI pipeline robustness by increasing the AI call timeout and proactively notifying customers in chat when the AI backend times out or errors, with configurable and non‑leaky messaging, plus tests to validate the behavior. Sequence diagram for AI failure customer notificationsequenceDiagram
participant Pipeline
participant AIBackend
participant Chat
participant OperatorLog
Pipeline->>AIBackend: runAIStage
AIBackend-->>Pipeline: timeout or error
Pipeline->>Pipeline: clearStateWithLog
Pipeline->>OperatorLog: pipeline.ai.failure_notice.sending(cause)
Pipeline->>Chat: runDispatchStage(notice)
Chat-->>Pipeline: postback delivered
Flow diagram for configurable AI failure noticeflowchart TD
A[AI timeout or error] --> B[clearStateWithLog]
B --> C{AI_FAILURE_NOTICE configured?}
C -->|empty| D[Return silently]
C -->|unset| E[Use default notice]
C -->|non-empty| F[Use configured notice]
E --> G{postbackURL available?}
F --> G
G -->|no| H[Log no_postback and return]
G -->|yes| I[Log provider error as cause]
I --> J[runDispatchStage with customer-safe notice]
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've found 1 issue
Prompt for AI Agents
Please address the comments from this code review:
## Individual Comments
### Comment 1
<location path="pkg/pipeline/service/pipeline_service.go" line_range="422" />
<code_context>
+ // CRM-236: silence is indistinguishable from "the bot is ignoring you",
+ // and the tool's side effect may already be applied (the card moved at
+ // ~20s, the timeout fired at 30s). Tell the customer something.
+ s.sendAIFailureNotice(contactID, conversationID, cfg, postbackURL, err)
default:
slog.Error("pipeline.ai.error",
</code_context>
<issue_to_address>
**issue (bug_risk):** The failure notice is dispatched with a fresh background context after the AI stage has cleared its state, so a newer message can start a replacement pipeline before this dispatch completes. When the notice dispatch succeeds, `runDispatchStage` clears the state and deletes the entry for the same contact/conversation, thereby deleting or clearing the newer pipeline and causing its response to be lost.
**Triggers:** When a new customer message arrives after the AI failure has been recorded but before the fallback notice finishes dispatching.
**Suggested fix:** Revalidate ownership of the pipeline entry before dispatching and before cleanup, or route the notice through an ownership-aware dispatch path that cannot clear state belonging to a newer pipeline.
</issue_to_address>Sourcery assessment
Needs a human reviewer. 1 finding to address first, and if the new timeout or default failure message is the wrong product decision, every affected failed AI turn will wait up to 90 seconds and may send a customer-facing message; those messages cannot be undone by reverting the change. Reverting prevents future notices and restores the old timeout, but it cannot retract notifications already delivered.
Blocking findings: pkg/pipeline/service/pipeline_service.go:422
Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
This was referenced Aug 22, 2026
…-236 review)
Addresses the CRITICAL findings on the bot-runtime side.
1. The notice could delete the follow-up turn's entry.
sendAIFailureNotice dispatched through runDispatchStage, which owns the
turn's bookkeeping: its success path runs SetState(StageDone) -> ClearState
-> entries.Delete(pairKey). That Delete is what runDispatchStage's own
comments forbid ("A Delete here would race with the new event's Store and
could delete the replacement entry").
The race lands on the very scenario this feature targets — the customer who
waited and follows up. They send "oi?" while the notice is being dispatched,
startDebounce stores the new turn, then the notice finishes and deletes THAT
entry and clears its state. The new turn is orphaned: the next message cannot
cancel it, so two pipelines run concurrently on the same pair and the
customer gets a duplicated reply.
The notice now dispatches directly. There was nothing to book-keep anyway:
both call sites already run clearStateWithLog before asking for it.
2. The 5s budget truncated the notice and then lied about why.
cleanupCtx's 5s are documented for cleanup calls (ClearState, SetState). A
Dispatch is a different animal: it segments by TextSegmentationLimit and
sleeps DelayPerCharacter per rune between parts. With segmentation on, the
84-rune default became 2-3 parts and the delays alone exceeded 5s ->
ErrDispatchInterrupted -> the log said "New message arrived" when nothing had
arrived. Now bounded by noticeCtx (30s).
3. The 90s ceiling was still pinned at 30 inside this repo.
.env.example:8 and k8s/configmap.yaml:8 both set it explicitly, and by this
PR's own reasoning ("an explicit env beats the code default") the fix had no
effect where it runs — the ConfigMap is what actually serves staging/prod.
NOT fixed here: evolution-ecosystem/k8s/base/bot-runtime.yaml:44-45 pins 30
too, but that is the SaaS repo, outside these three PRs.
4. The default notice was hardcoded pt-BR (finding 9).
bot-runtime ships in community/self-hosted installs worldwide, so customers
of installations that never chose Portuguese were answered in it. Now English,
with AI_FAILURE_NOTICE documented in .env.example for localisation and the
empty value still restoring silence.
Tests: 10 (was 6). The new ones pin that the notice leaves the follow-up entry
and its state untouched, that its budget fits a segmented dispatch, and that the
default carries no pt-BR.
Negative proof: restoring the runDispatchStage call fails
"DoesNotTouchTheEntryOfTheNextTurn" with the orphaned-turn message.
gofmt: pipeline_service.go is already unformatted on develop (CRLF); left as-is
rather than reformatting the whole file into this diff.
11 — the doc comment of clearStateWithLog had been orphaned: the new constants
landed between it and its function, so godoc showed aiFailureNoticeEnv
documented as "clearStateWithLog calls ClearState...". Moved back.
12 — the test helper reimplemented strings.Contains in 9 lines with a closure.
13 — os.Unsetenv mutated the process env without restoring it, so every test
running after that one inherited the change. Restores via t.Cleanup now.
No behaviour change. build/vet clean, full suite green with a real Redis.
CI was red on TestE2E_PipelineIsolation, and the test was right to fail:
postback content = "We are having a temporary issue…", want "pair-b response"
It asserted callCount == 1 with the comment "only pair B should deliver". That
described the OLD behaviour, where pair A's AI error was swallowed — log, clear
state, nothing reaching the chat. Making that pair speak is the entire point of
this card, so the assertion had to move.
Updated rather than relaxed. The test is about isolation, and it now checks that
more strictly than before: both pairs deliver, and each must receive ITS OWN
message. A crossed delivery fails here even though the count would be right —
the previous version could not have caught that.
The notice is pinned through AI_FAILURE_NOTICE instead of reaching for the
package constant: it keeps test/e2e out of service's internals and exercises the
operator-facing env on the way.
On how this reached CI: I ran ./pkg/... and ./internal/... and called it "the
full suite". test/e2e was never in it. Same mistake as the migration parity spec
on CRM-210 — a hand-picked list reported as a green suite. Ran ./... this time.
…eview) The round-1 defect was runDispatchStage's success bookkeeping running for the failure notice: SetState(StageDone) -> ClearState -> entries.Delete(pairKey), against a pair that may already belong to a follow-up turn. The fix is in, but nothing pinned it: the existing test read Redis after the fact, and SetState followed by ClearState leaves nothing to read, so it passed with or without the regression. DoesNotTouchTheEntryOfTheNextTurn seeds the pair the way startDebounce leaves it (entry in the map, StageDebounce in Redis) and asserts both survive. Restoring the runDispatchStage call fails all three assertions. Also make DoesNotWriteTurnState fail on a read error instead of passing on it, and drop its unused rdb binding.
… 14) The measurement table, the incident timeline and the race walkthrough belong in the PR body, where they already are. In the source they were 11 lines above one call to getEnvIntOrDefault, 18 above one call to Dispatch, and 10 above a context.WithTimeout. What is kept is what the code cannot say: why 90 and not 30, why the notice must not go through runDispatchStage, why noticeCtx is not cleanupCtx. 102 added comment lines to 58, no behaviour touched.
gomessguii
approved these changes
Aug 22, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problema
Quando o provedor de LLM degrada, o turno estoura o teto e o pipeline apenas logava e limpava o estado — nada chegava ao chat. Para o cliente é indistinguível de um bot que o está ignorando.
E é pior do que parece: o efeito colateral da ferramenta já foi aplicado. Na execução ao vivo o card do funil moveu aos ~20s e o timeout disparou aos 30s — o funil andou e a conversa ficou muda.
Medição (a premissa original do card estava errada)
O card dizia "30s não cobre turno com tool-calling". Falso. Turno completo, em condições normais:
O que oscila é o provedor. Mesma chamada trivial ("responda apenas: ok") ao
gemini-2.5-flash, cinco vezes seguidas:Variação de 27× na mesma chamada. Um turno com ferramenta faz ao menos duas dessas idas (decidir a tool, depois redigir a resposta), então duas caudas ruins sozinhas passam de 30s sem nada de errado no código.
E sob cota estourada o litellm ainda retenta internamente:
Mudanças
1.
AI_CALL_TIMEOUT_SECONDS30 → 90. Cobre duas chamadas na cauda mais o round trip do CRM, e ainda limita um provedor genuinamente travado.Isto não é a correção sozinha: elevar um teto só o desloca. É a mensagem abaixo que protege o cliente quando o teto é atingido.
2. Aviso no chat em vez de silêncio. No timeout ou erro, o pipeline despacha uma frase para a conversa. O erro cru do provedor nunca chega ao cliente — ele carrega nome de modelo, id de cota e URLs — e vai para o log do operador como
cause:AI_FAILURE_NOTICEsobrescreve o texto; defini-la vazia mantém o silêncio de hoje, para quem preferir.Testes
pkg/pipeline/service/ai_failure_notice_test.go— 6 testes: o cliente é avisado; o erro do provedor nunca vaza (verifica quegemini,Quota,RateLimitError,googleapisnão aparecem na mensagem); o texto é sobrescrevível; vazio desativa; postback ausente não quebra; o default vale quando a env não existe.Deliberadamente fora deste PR
Dois defeitos reais que pertencem ao lado do processor, não ao bot-runtime:
500 INTERNAL_ERRORgenérico na rota A2A, então nem o operador vê "cota excedida" sem ler o log do container.Ambos estão registrados no card. Fiz aqui o que resolve o sintoma para o cliente; aquilo exige mexer no caminho de erro do processor e merece PR próprio.
Trade-off assumido
Um teto de 90s significa que um provedor travado segura o turno por mais tempo antes de o cliente receber o aviso. É o preço de não cortar turnos legítimos com cauda alta — e o aviso garante que, mesmo no pior caso, a conversa não termina em silêncio.
Summary by Sourcery
Ensure customers receive a safe, actionable response when AI processing times out or fails instead of being left in silence.
New Features:
Bug Fixes:
Enhancements:
Tests:
Descoberto ao verificar o CRM-236 na stack rodando: depois de rebuildar com este fix, o container ainda reportava
AI_CALL_TIMEOUT_SECONDS=30.Todo compose entregue setava a env explicitamente em 30, e env explícita ganha do default do código. Elevar o default para 90 aqui não muda nada onde importa.
Corrigido em PR separado no repo raiz — evo-crm-community#175 (
docker-compose.swarm.yamleinternal/review/docker-compose.yml). Mergear os dois juntos..env.example:224carrega o mesmo30e é arquivo protegido no ambiente onde trabalhei, então precisa de um mantenedor — sem isso, toda instalação nova nasce com o teto antigo.Ordem de merge — PRs irmãos do CRM-236
#9 (este) e #175 devem subir juntos; o #52 é independente e pode ir em qualquer ordem.
evo-bot-runtimeevo-ai-processor-communityevo-crm-communityVerificação ao vivo do aviso (item C do card)
Feita após este PR: bot-runtime rebuildado, teto forçado a 1s, evento real injetado numa conversa.
A conversa foi de 7 para 8 mensagens e a nova é o aviso,
message_type=1(outgoing), persistida no CRM. O cliente vê texto em vez de silêncio.Summary by Sourcery
Ensure customers receive a clear response when AI processing fails or times out instead of being left in silence.
New Features:
Bug Fixes:
Enhancements:
Deployment:
Tests:
Review — críticos 2, 3 e item 9
🔴 2 — o aviso podia apagar o turno seguinte
Confirmado, e o cenário é justamente o que a feature mira.
sendAIFailureNoticedespachava viarunDispatchStage, que é dono do bookkeeping do turno: o caminho de sucesso rodaSetState(StageDone)→ClearState→entries.Delete(pairKey). EsseDeleteé o que os comentários da própria função proíbem: "A Delete here would race with the new event's Store and could delete the replacement entry."O cliente espera, desiste, manda "oi?" durante o despacho do aviso →
startDebounceguarda o turno novo → o aviso termina e deleta essa entry, órfã o turno novo, e sobem dois pipelines no mesmo par: resposta duplicada.Agora o aviso despacha direto. Não havia o que book-keepar de todo jeito: os dois call sites já rodam
clearStateWithLogantes.Prova negativa: restaurando a chamada, falha
DoesNotTouchTheEntryOfTheNextTurncom a mensagem do turno órfão.🟡 6 — fechou junto
cleanupCtxsão 5s documentados para cleanup (ClearState,SetState). UmDispatchsegmenta porTextSegmentationLimite dormeDelayPerCharacterpor runa entre as partes: com segmentação ligada, o aviso de 84 runas virava 2-3 partes e só os delays estouravam os 5s →ErrDispatchInterrupted→ o log dizia "New message arrived" sem que mensagem nenhuma tivesse chegado. AgoranoticeCtx()(30s).🔴 3 — o teto seguia anulado dentro deste repo
.env.example:8ek8s/configmap.yaml:8corrigidos para 90. O critério é do próprio PR: se env explícita ganha do default, deixar 30 no ConfigMap que serve staging/prod anula o fix onde ele mais importa.Não tocado:
evolution-ecosystem/k8s/base/bot-runtime.yaml:44-45também fixa 30, mas é o SaaS, fora destes três PRs.🟡 9 — aviso default em pt-BR hardcoded
O bot-runtime roda em instalações community/self-hosted no mundo todo, e clientes de instalações que nunca escolheram português eram respondidos nele. Agora inglês, com
AI_FAILURE_NOTICEdocumentada em.env.examplepara localização — e string vazia ainda restaura o silêncio. Há teste que falha se o pt-BR voltar.🟢 11, 12, 13
Doc comment devolvido ao
clearStateWithLog(meu bloco novo tinha caído entre ele e a função, então o godoc deaiFailureNoticeEnvcomeçava com "clearStateWithLog calls ClearState…"),containstrocado porstrings.Contains, eos.Unsetenvagora restaura viat.Cleanup.Testes
10 (eram 6): entry do turno seguinte intacta, estado não reescrito, orçamento do dispatch, default sem pt-BR.
go build/go vetlimpos, suíte completa verde com Redis real.gofmt:pipeline_service.gojá está fora de formato em develop (CRLF); deixado como está para não jogar o arquivo inteiro neste diff.Em aberto, dito por mim
10 (nada exercita
sendAIFailureNoticeviarunAIStage) e 14 (AI_FAILURE_NOTICElido poros.LookupEnvem vez de passar pelointernal/config).