Skip to content

fix(telegram): show only user-worded ACP failure reasons - #19713

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
fix/telegram-user-worded-failure-reason
Oct 13, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
fix/telegram-user-worded-failure-reason

Conversation

@iamwhatever

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A failed Telegram turn shows the error's own text only when Kiro Crew wrote that text for a person; any other failure gets the generic retry reply.

When a turn fails on the Telegram transport path, _user_safe_failure_reason in src/kiro_crew/telegram/transport_dispatch.py decides whether to show the error's message. It checked exc.transient is not False. That flag only says "do not retry". The ACP error formatter sets it on its fallback too, and the fallback passes the provider's own text (or the raw error dict) straight through. So a non-retryable error that no curated branch matched reached the Telegram user as raw provider text under ⚠.

Why it matters

Telegram users can be shown provider-internal text (redacted for credentials and paths, but still not written for them) instead of the plain retry reply. Slack fixed the same gap in #15190, so the two transports disagree on the same error.

Not a goal

  • Changing which errors the ACP formatter marks user_worded or transient.
  • Changing the Slack, Discord or dashboard error paths.
  • Changing the reply wording, the redaction, or the 500-character cap.

What changed (motivation → approach → change)

A non-retryable ACP error with provider text leaked into Telegram chat, because the gate read the retry flag (transient) instead of asking "did Kiro Crew word this?".

AcpError.user_worded (added in #15190) answers that question, and the shared helper is_user_worded_failure in agent_sdk/drivers/acp_vocab.py already wraps it for Slack: worded, not retryable, and not a timeout or process death.

Telegram's gate now calls that same helper. A private-memory refusal still shows its reason. Every other failure, including the provider-text fallback, gets the generic reply.

The facade no longer imports AcpError, its last ACP-layer import, so .github/agent-sdk-boundary-baseline.txt drops its entry and the composition contract test records that the facade now holds no agent-SDK import and binds is_user_worded_failure.

Backwards compatibility

Compatible: the reply shape is unchanged. Errors that are not user-worded move from showing their text to the generic reply, which matches Slack since #15190. That includes transient=False errors raised without user_worded (for example AcpSandboxInitFailed, whose text embeds the child's stderr) and the timeout / process-death types the shared helper excludes.

Reader: src/kiro_crew/telegram/transport_dispatch.py:AcpError (facade name dropped) -- entry: chat -- no module or test reads AcpError through the Telegram facade; every caller imports it from kiro_crew.acp.

Tests

  • test/test_telegram.py TestUserSafeFailureReason::test_non_retryable_provider_fallback_returns_none: a transient=False error without user_worded returns no reason. Red on main, green here.
  • TestTurnLifecycleCharacterization::test_close_gets_the_failure_reason_the_turn_classified gains the same fallback case end to end: the renderer's close() gets None.
  • The existing positive cases construct their errors with user_worded=True, matching what the real formatter raises for curated wording.
  • test/test_telegram_transport_dispatch_composition_contract.py lists is_user_worded_failure in BASE_NAMES; test/test_acp_error_surface.py has one docstring updated to the new gate.

Manual verification

N/A — unit coverage sufficient: the change is one predicate, and the tests drive both the helper and the full dispatcher turn.

Related Issues

Fixes #18439

Pattern harvest

Rule candidate: review-prompt
Pattern: a chat surface gating "show this error's text" on a retry flag (transient) instead of on the error's user_worded provenance.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@iamwhatever
iamwhatever requested review from a team and KiroCrewCaptain as code owners October 13, 2026 06:12
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 13, 2026
@github-actions

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision d5b87bb680b625d6f408b6353c1b46eecf6d6026 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of d5b87bb680b625d6f408b6353c1b46eecf6d6026 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

A user-worded AcpError with transient=None now shows its text in Telegram, where it used to get the generic reply. Confirm this matches Slack.

[DESIGN-REVIEWED] d5b87bb

Description read

[DESCRIPTION-READ] 0971091e01fc3e786935c044492227554629da6ebeb702cd9320a3e1261b7b6a

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of d5b87bb680b625d6f408b6353c1b46eecf6d6026 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: PASS

The positive tests now set user_worded=True themselves. Confirm that the curated messages users currently see (model-not-in-plan, malformed request) really are raised with that flag.

What this change ships

Inventory (3 items) — 3 justified

Intent: when a Telegram turn fails, show the error's own text only if Kiro Crew wrote it for a person. FIX (#18439).

  1. A non-retryable failure that carries the provider's raw text now gets the generic retry reply on Telegram instead of that text — justified
  2. Timeout, process-death, and non-retryable errors without user_worded (e.g. sandbox-init stderr) now get the generic reply on Telegram — justified
  3. The Telegram facade's entry is gone from the agent-SDK boundary baseline, and the contract test now forbids that import in the facade — justified

[FIRST-PRINCIPLES-REVIEWED] d5b87bb

Description read

[DESCRIPTION-READ] 371a83a4614191c2846aa63728ffed75469c8e295145ab38f43444778477ecc6

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed d5b87bb680b625d6f408b6353c1b46eecf6d6026 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] d5b87bb

Verdict parsed from the review's SHA-scoped output markers for commit d5b87bb680b625d6f408b6353c1b46eecf6d6026.

False positive or not applicable? A repository writer can comment:
/ai-review override fable d5b87bb680b625d6f408b6353c1b46eecf6d6026: <one-sentence reason>

@github-actions

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of d5b87bb680b625d6f408b6353c1b46eecf6d6026 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] d5b87bb

False positive or not applicable? A repository writer can comment:
/ai-review override gpt d5b87bb680b625d6f408b6353c1b46eecf6d6026: <one-sentence reason>

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Backend Tests (Windows) (6) failure is not caused by this PR.

The one failing test is test/test_mcp_gateway_wedge_ping_gate.py::test_unknown_notification_silently_ignored (the tools/call with id 7 got no response). This PR does not touch src/kiro_crew/mcp_shared.py or any MCP code.

Evidence:

Re-ran the failed jobs.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 13, 2026
@KiroCrewCaptain
KiroCrewCaptain enabled auto-merge (squash) October 13, 2026 09:04

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tier 1 auto-approve: fix (5 files). Criteria: no conflict, no requested changes, security path denylist clean, design-doc gate clean, security checklist all-NO, no reviewer-lane findings, readiness signal fresh for this head SHA, declared category matches the diff. Category: limits the failure reasons a Telegram chat shows to errors worded for a person, so a provider's raw fallback text gets the generic reply; updates the boundary baseline and tests.

@KiroCrewCaptain
KiroCrewCaptain merged commit 049122d into main Oct 13, 2026
147 of 148 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the fix/telegram-user-worded-failure-reason branch October 13, 2026 09:06
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Telegram transport path shows raw provider text for non-retryable ACP errors

2 participants