Summary

• Problem: provider invalid-request errors like Reasoning is mandatory for this endpoint and cannot be disabled. could be misrouted into context-overflow handling.
• Why it matters: users see misleading Context overflow guidance and embedded recovery paths may attempt the wrong remediation.
• What changed: added explicit reasoning-constraint exclusions in overflow classifiers and a dedicated user-facing message in assistant error formatting.
• What did NOT change (scope boundary): no model/provider routing changes, no compaction policy changes, and no fallback-chain behavior changes outside this specific error classification path.

Change Type (select all)

• Bug fix
• Feature
• Refactor
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes Context overflow on fresh session with Kimi K2.5 via OpenRouter — likely error misclassification #24520
• Related Fix Groq TPM limits misidentified as context overflow #16176

User-visible / Behavior Changes

• Invalid-request responses that state reasoning is required (for example, Reasoning is mandatory for this endpoint and cannot be disabled.) are no longer treated as context overflow.
• Users now receive a direct remediation message: enable reasoning (/think minimal or another non-off level) and retry.

Security Impact (required)

• New permissions/capabilities? (No)
• Secrets/tokens handling changed? (No)
• New/changed network calls? (No)
• Command/tool execution surface changed? (No)
• Data access scope changed? (No)
• If any Yes, explain risk + mitigation:

Repro + Verification

Environment

• OS: macOS
• Runtime/container: Node 22+, pnpm
• Model/provider: OpenRouter-style invalid-request payloads for reasoning-required endpoints
• Integration/channel (if any): embedded agent error formatting/classification
• Relevant config (redacted): N/A

Steps

1. Feed formatAssistantErrorText / overflow classifiers with 400 Reasoning is mandatory for this endpoint and cannot be disabled.
2. Verify overflow detectors return false.
3. Verify formatted output provides reasoning-required remediation, not context overflow.

Expected

• No context-overflow classification for reasoning-required invalid-request errors.
• Friendly message points users to enabling reasoning.

Actual

• Before this fix, these messages could be funneled into context-overflow handling in downstream recovery paths.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: updated tests for isContextOverflowError, isLikelyContextOverflowError, and formatAssistantErrorText for reasoning-required messages.
• Edge cases checked: JSON-wrapped invalid-request message variants and generic requires reasoning phrasing.
• What you did not verify: live provider/channel end-to-end run.

Compatibility / Migration

• Backward compatible? (Yes)
• Config/env changes? (No)
• Migration needed? (No)
• If yes, exact upgrade steps:

Failure Recovery (if this breaks)

• How to disable/revert this change quickly: revert the three commits in this PR.
• Files/config to restore: src/agents/pi-embedded-helpers/errors.ts, related tests.
• Known bad symptoms reviewers should watch for: reasoning-required errors still being surfaced as context overflow.

Risks and Mitigations

• Risk: matching text could miss alternate provider wording for reasoning constraints.
  • Mitigation: guard covers multiple common phrases and includes JSON-wrapped variants in tests.

Greptile Summary

This PR prevents reasoning-constraint invalid-request errors from being misclassified as context overflow errors by adding explicit exclusions in overflow classifiers and a dedicated user-facing message.

Key changes:

• Added isReasoningConstraintErrorMessage() helper that checks for phrases like "reasoning is mandatory", "reasoning is required", "requires reasoning", or "reasoning" + "cannot be disabled"
• Updated isContextOverflowError() and isLikelyContextOverflowError() to exclude reasoning-constraint errors before checking overflow patterns
• Added user-friendly message in formatAssistantErrorText() directing users to enable reasoning with /think minimal
• Comprehensive test coverage across all three functions with multiple test cases including JSON-wrapped variants

The fix follows the same pattern as the recent Groq TPM fix (commit 652099c) by adding early-exit guards to prevent false classification.

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• The changes are narrow in scope, well-tested, and follow established patterns in the codebase. The new guard is positioned correctly as an early exclusion before overflow checks. Test coverage is thorough with multiple variants including JSON-wrapped errors. No logic bugs or edge cases identified.
• No files require special attention

_{Last reviewed commit: de2f65c}