Files
kandev/apps/backend/internal/agent/runtime/routingerr/runtime_rules.go
T
2026-09-17 19:01:53 +01:00

341 lines
13 KiB
Go

package routingerr
import (
"regexp"
"strings"
)
// runtimeEnvironmentRules match failures caused by the local execution
// environment (npm/npx cache state, missing binaries' install steps,
// etc.) rather than by the provider or remote API. They are tried by
// Classify after provider-specific rules and before the phase-based
// fallback, so a specific environment fingerprint wins over the
// low-confidence "phase.prestart.unknown" verdict.
//
// Each entry pairs a matcher with a builder that can extract signal-specific
// metadata (e.g. RemediationPath) from the raw text. Most matchers are regular
// expressions; rules that share an adapter's byte-level contract can provide a
// custom matcher instead.
var runtimeEnvironmentRules = []runtimeRule{
{
// npm 9 and npm 10 use different casing for the error prefix. Require
// both the ETARGET code and the matching package@version diagnostic in
// one bounded sample so generic disconnects and registry errors do not
// trigger managed-runtime recovery.
id: "npm.etarget.managed_runtime.v1",
pattern: managedRuntimeNpmResolutionRe,
sanitizedOnly: true,
build: func(string) *Error {
return &Error{
Code: CodeManagedRuntimeNpmResolution,
Confidence: ConfHigh,
}
},
},
{
id: "npm.enotempty.npx.v1",
pattern: regexp.MustCompile(`(?s)npm error code ENOTEMPTY.*?_npx/[0-9a-f]+`),
build: func(text string) *Error {
path := extractNpxCachePath(text)
if path == "" {
return nil
}
return &Error{
Code: CodeNpxCacheCorrupted,
Confidence: ConfHigh,
RemediationPath: path,
}
},
},
{
// Anthropic 400 surfaced by the claude-agent-acp adapter on a
// prompt after session/load: the reconstructed history loses the
// extended-thinking block signatures, so the API rejects the
// modified `thinking`/`redacted_thinking` blocks. Provider-agnostic
// because the signature is unique enough to never false-positive,
// and any adapter routing to Anthropic models can hit it.
id: resumeCorruptedRuleID,
pattern: thinkingBlocksImmutableRe,
build: func(string) *Error {
return &Error{
Code: CodeResumeCorrupted,
Confidence: ConfHigh,
RemediationPath: RemediationStartFreshSession,
}
},
},
{
// Anthropic 529 Overloaded surfaced over ACP as a prompt-time error
// event: a transient, server-side condition the orchestrator should
// retry with backoff rather than tear down. Provider-agnostic because
// the "529 ... overloaded" / "overloaded_error" signature is unique
// enough not to false-positive on unrelated logs.
id: overloadedRuleID,
pattern: overloadedRe,
build: func(string) *Error {
return &Error{
Code: CodeProviderOverloaded,
Confidence: ConfHigh,
}
},
},
{
// ACP adapters preserve these upstream gateway 5xx envelopes as text
// instead of structured HTTP metadata. Require the ACP "API Error"
// prefix and an exact status/reason pair so ordinary model output or a
// local process error cannot authorize dynamic recovery.
id: gatewayServerFailureRuleID,
pattern: gatewayServerFailureRe,
build: func(string) *Error {
return &Error{
Code: CodeProviderUnavailable,
Confidence: ConfHigh,
}
},
},
{
// Cursor emits this control prefix as an assistant message chunk for
// transient provider failures. Keep the fingerprint anchored to the
// control frame and bounded so user-authored prose cannot turn into an
// automatic retry. The custom matcher shares the adapter's byte and
// Unicode-whitespace contract.
id: cursorRetriableStreamResetRuleID,
providerID: cursorRetriableProviderID,
match: matchCursorRetriableStreamReset,
rawMatch: matchCursorRetriableStreamReset,
build: func(text string) *Error {
if IsCursorRetriableCancellation(text) {
return nil
}
return &Error{
Code: CodeAgentTransportLost,
Confidence: ConfHigh,
}
},
},
{
// The ACP transport pipe died mid-turn: the upstream provider service
// dropped the connection before a response arrived. This is
// provider-agnostic wire-level transport death, not a model or
// availability problem — recoverable by retrying the same provider.
// Appended last so the more specific resume-corrupted and
// 529-overloaded rules above still win when signatures co-occur.
id: transportLostRuleID,
pattern: transportLostRe,
build: func(text string) *Error {
// A context cancellation or deadline can be reported alongside the
// same "connection closed" wording the transport-lost signature
// matches on (e.g. "context canceled: connection closed"). Those
// envelopes must keep falling through to manual recovery, so
// reject them here rather than trust the substring match alone.
if cancellationOrDeadlineRe.MatchString(text) {
return nil
}
return &Error{
Code: CodeAgentTransportLost,
Confidence: ConfHigh,
}
},
},
}
var managedRuntimeNpmResolutionRe = regexp.MustCompile(
`(?ism)^\s*npm\s+(ERR!|error)\s+code\s+ETARGET\b[\s\S]{0,999}^\s*npm\s+(ERR!|error)\s+notarget\s+No matching version found for\s+\S+@\S+`,
)
// cancellationOrDeadlineRe matches context-cancellation and deadline
// signatures that can co-occur with the transport-lost wording in the same
// error string. Kept separate from transportLostRe so the two can be
// combined without the transport-lost pattern itself growing lookahead
// complexity.
var cancellationOrDeadlineRe = regexp.MustCompile(`(?i)\bcontext (?:canceled|deadline exceeded)\b|\bcancel escalated\b`)
const resumeCorruptedRuleID = "anthropic.thinking_blocks.immutable.v1"
const overloadedRuleID = "anthropic.overloaded.529.v1"
const gatewayServerFailureRuleID = "acp.gateway_server_failure.v1"
const cursorRetriableStreamResetRuleID = "cursor.retriable_stream_reset.v1"
const transportLostRuleID = "acp.transport_lost.v1"
// transportLostRe matches the narrow ACP wire-level transport-death
// signatures: the peer disconnecting before a response, or the underlying
// connection closing outright. Deliberately narrow (only these two
// substrings) so it never matches context-cancellation or shutdown-teardown
// error strings, which must keep falling through to manual recovery. It does
// not fire when the signature never leaves a terminal ACP prompt error's
// `RequestError.Data`, because the generic prompt-error projection classifies
// on `Message` alone; it still fires whenever the projected `Message` itself
// carries the signature.
var transportLostRe = regexp.MustCompile(`(?i)peer disconnected|connection closed`)
const (
cursorRetriableStreamResetPrefix = "Error: RetriableError:"
cursorRetriableStreamResetMaxTail = 256
cursorRetriableProviderID = "cursor-acp"
)
// matchCursorRetriableStreamReset matches Cursor's complete bounded control
// diagnostic using the same trim, prefix, byte-limit, and cancellation-veto
// rules as the ACP adapter. The byte limit prevents the classifier from
// accepting a diagnostic that the adapter would reject after multibyte text is
// measured.
func matchCursorRetriableStreamReset(text string) bool {
trimmed := strings.TrimSpace(text)
if len(trimmed) < len(cursorRetriableStreamResetPrefix) ||
!strings.EqualFold(trimmed[:len(cursorRetriableStreamResetPrefix)], cursorRetriableStreamResetPrefix) {
return false
}
suffix := strings.TrimSpace(trimmed[len(cursorRetriableStreamResetPrefix):])
if suffix == "" || len(suffix) > cursorRetriableStreamResetMaxTail || IsCursorRetriableCancellation(suffix) {
return false
}
return true
}
// IsCursorRetriableCancellation reports whether Cursor's RetriableError
// suffix carries cancellation or deadline evidence that must not be retried.
// The adapter uses this same predicate before it suppresses diagnostic output.
func IsCursorRetriableCancellation(text string) bool {
lower := strings.ToLower(text)
return strings.Contains(lower, "context canceled") ||
strings.Contains(lower, "context deadline exceeded") ||
strings.Contains(lower, "cancel escalated")
}
// overloadedRe matches the transient 529 Overloaded signature: either the
// numeric code adjacent to "overloaded" on a single line (in either order), or
// the Anthropic "overloaded_error" type token. Kept tight ([^\n] stays within
// one line) so a stray "529" and "overloaded" in unrelated multi-line logs
// can't bridge into a false positive.
var overloadedRe = regexp.MustCompile(`(?i)\b529\b[^\n]*overloaded|overloaded[^\n]*\b529\b|\boverloaded_error\b`)
// gatewayServerFailureRe accepts only status/reason pairs emitted by the ACP
// API-error wrapper. The bounded, one-line expression intentionally excludes
// bare 5xx numbers and generic "internal error" prose.
var gatewayServerFailureRe = regexp.MustCompile(`(?i)\bAPI\s+Error:\s*(?:500\s+Internal(?:\s+Server)?\s+Error|502\s+Bad\s+Gateway|504\s+Gateway\s+Timeout)\b`)
// IsTransientProviderError reports whether a provider-neutral error is eligible
// for a short same-provider retry. Provider-specific callers must use
// IsTransientProviderErrorForProvider so a signature cannot cross adapters.
func IsTransientProviderError(message string) bool {
return isTransientProviderError(Classify(Input{Phase: PhasePromptSend, Stderr: message}))
}
// IsTransientProviderErrorForProvider reports whether a provider error is
// eligible for a short same-provider retry while preserving provider-specific
// catalogue scope.
func IsTransientProviderErrorForProvider(providerID, message string) bool {
if message == "" {
return false
}
return isTransientProviderError(Classify(Input{
Phase: PhasePromptSend,
ProviderID: providerID,
Stderr: message,
}))
}
func isTransientProviderError(e *Error) bool {
if e == nil || !e.AutoRetryable || e.UserAction {
return false
}
switch e.Code {
case CodeProviderOverloaded, CodeModelCapacity, CodeNetworkUnavailable, CodeProviderUnavailable, CodeAgentTransportLost:
return true
default:
return false
}
}
// thinkingBlocksImmutableRe matches the Anthropic "thinking blocks cannot be
// modified" 400 in either the `thinking` or `redacted_thinking` form. The
// gaps stay bounded ([^\n] is non-greedy-friendly within a single line) so a
// stray "thinking" elsewhere in a multi-line log can't accidentally bridge to
// an unrelated "cannot be modified".
var thinkingBlocksImmutableRe = regexp.MustCompile(`(?i)(?:redacted_)?thinking[^\n]*blocks[^\n]*cannot be modified`)
// IsResumeCorrupted reports whether the error message carries the
// resume-corrupted (thinking-blocks-immutable) signature. Exposed for callers
// outside the classify path (e.g. the orchestrator's recovery UI) that need to
// steer the user toward a fresh session without re-running full Classify.
func IsResumeCorrupted(message string) bool {
return message != "" && thinkingBlocksImmutableRe.MatchString(message)
}
type runtimeRule struct {
id string
providerID string
pattern *regexp.Regexp
match func(text string) bool
rawMatch func(text string) bool
build func(text string) *Error
sanitizedOnly bool
}
// npxCachePathRe captures the cache root, e.g.
// `/Users/cfl/.npm/_npx/d820eb7d96bc2600` from any npm error line that
// references a file beneath it. The hash segment is hex (npm uses an
// 8-byte hex of the package spec). `[^\n]*?` lets the home prefix
// contain spaces (e.g. `/Users/John Doe/...`); RemediateNpxCache's
// `EvalSymlinks` + `$HOME/.npm/_npx/` prefix guard validates the path
// before any deletion, so we don't need the regex to do that work too.
var npxCachePathRe = regexp.MustCompile(`(/[^\n]*?/\.npm/_npx/[0-9a-f]+)`)
func extractNpxCachePath(text string) string {
m := npxCachePathRe.FindStringSubmatch(text)
if len(m) < 2 {
return ""
}
return m[1]
}
func matchRuntimeEnvironmentRules(text string) (*Error, bool) {
return matchRuntimeRules(text, text, "", false)
}
func matchLegacyRuntimeEnvironmentRules(text string) (*Error, bool) {
return matchRuntimeRules(text, text, "", true)
}
func matchRuntimeEnvironmentRulesForProvider(providerID, text, rawText string) (*Error, bool) {
return matchRuntimeRules(text, rawText, providerID, false)
}
func matchLegacyRuntimeEnvironmentRulesForProvider(providerID, text, rawText string) (*Error, bool) {
return matchRuntimeRules(text, rawText, providerID, true)
}
func matchRuntimeRules(text, rawText, providerID string, legacyOnly bool) (*Error, bool) {
if text == "" {
return nil, false
}
for _, r := range runtimeEnvironmentRules {
if legacyOnly && r.sanitizedOnly {
continue
}
if r.providerID != "" && r.providerID != providerID {
continue
}
if r.rawMatch != nil && !r.rawMatch(rawText) {
continue
}
var matched bool
if r.match != nil {
matched = r.match(text)
} else {
matched = r.pattern != nil && r.pattern.MatchString(text)
}
if !matched {
continue
}
if e := r.build(text); e != nil {
e.ClassifierRule = r.id
return e, true
}
}
return nil, false
}