Files
kandev/docs/plans/cursor-retriable-stream-reset/plan.md
T
2026-08-31 13:18:54 +00:00

149 lines
7.9 KiB
Markdown

---
created: 2026-08-31
status: done
requirements:
- REQ-PLATFORM-PROVIDER-ERROR-RECOVERY-001
system_design:
- ../../specs/platform/system-design/provider-error-recovery.md
legacy_specs: []
---
# Implementation Plan: Cursor Retriable Stream Reset
## Overview
Project Cursor's terminal HTTP/2 `RetriableError` control frame into one
structured provider failure. Classify its safe diagnostic as the existing
transient transport-loss cause. Authorize the existing same-provider retry only
for prompt attempts that have no output or tool activity. Adapter detection and
classifier work can proceed independently. Replay-safety wiring depends on both
contracts and completes the end-to-end behavior.
## Scope
### In scope
- Cursor-only, prompt-generation-scoped detection of the complete terminal
stream reset control frame.
- Suppression of the control frame and one post-barrier structured error.
- Suppression of a Kandev retry when Cursor resumes its own attempt after the
marker.
- A dedicated deterministic classifier rule for the safe Cursor diagnostic.
- Provider-neutral replay evidence for concrete interactive retry decisions.
- Existing same-provider retry ownership, attempt limit, delay schedule, and
manual recovery fallback.
### Out of scope
- Generic scanning of arbitrary assistant output.
- Widening the existing generic `transportLostRe` expression.
- Cursor-specific retry timers, counters, or backoff values.
- Automatic provider or model switching for `agent_transport_lost`.
- New UI, user-facing copy, persistence, or public API changes.
## Technical approach
### Cursor ACP evidence projection
- Add the allocation-conscious matcher and bounded safe diagnostic to
`apps/backend/internal/agentctl/server/adapter/transport/acp/dialect_cursor.go`.
- Extend `promptTurnState` in `adapter.go` with mutex-guarded pending Cursor
evidence. Matching control frames set the pending marker. Later
same-generation provider progress clears it. A later matching frame re-arms
it.
- Add `observeCursorRetriableEvidence` beside the Codex observer in
`adapter_updates.go`. Check agent identity, event type, prompt generation, and
the anchored prefix before the full fingerprint. Suppress only a matching
control frame.
- In `adapter_prompt.go`, inspect pending evidence only after `syncNotifQueue()`.
Emit one `EventTypeError` with a valid `ProviderError` and return instead of
emitting the ordinary complete event.
- Add `ProviderErrorSourceCursorACP` to
`apps/backend/internal/agentctl/types/streams/provider_error.go`.
### Deterministic classification
- Add `cursor.retriable_stream_reset.v1` to
`apps/backend/internal/agent/runtime/routingerr/runtime_rules.go` before the
generic transport-loss rule.
- Require the complete normalized Cursor diagnostic, with the existing
bracketed `canceled` decoration allowed.
Apply the existing context-cancellation veto without changing
`transportLostRe`.
- Assert the full `Classify` result is `CodeAgentTransportLost`,
`ClassTransient`, high confidence, and auto-retryable. Pin that `[canceled]`
does not trigger the cancellation veto.
### Replay authorization and existing retry owner
- Generalize the process-local attempt evidence in
`apps/backend/internal/orchestrator/dynamic_evidence.go`. Concrete interactive
prompts also retain output and tool observations. The evidence has session,
execution, and prompt-generation scope. Preserve `DynamicRouteAttempt` as
routing identity. Do not turn concrete prompts into dynamic attempts.
- Carry a conservative terminal evidence snapshot from lifecycle on
`agent.failed`, captured before completion bookkeeping marks the terminal
event as activity. The orchestrator must prefer this immutable snapshot over
stream-subscription timing while retaining local identity fencing.
- Begin or replace concrete prompt evidence at prompt dispatch. Bind it to the
execution and generation. Update it from `event_handlers_streaming.go`. Clear
only the matching completed or replaced attempt.
- Cache and reserve replay identity before a model-switch restart can dispatch
its replacement prompt, then bind it to the replacement execution.
- Make `handleTransientFailure` require known evidence with no output or tool
activity before it schedules any automatic prompt replay. Missing, stale,
output-bearing, or tool-bearing evidence falls through to manual recovery.
- Keep `CodeAgentTransportLost.FallbackAllowed` false. Dynamic routing retains
its current fail-closed gate and cannot reinterpret the Cursor signature as
permission to switch providers.
- Reuse `transientMaxAttempts`, `transientRetryDelayFor`, the existing single
retry entry, and the existing resume-before-reprompt path without adding a
Cursor-specific retry loop.
## Tests
- `AC-PLATFORM-PROVIDER-ERROR-RECOVERY-001.12`: a new ACP test file covers the
exact captured payload, anchored negatives, partial negatives, agent scope,
and generation scope. It also covers chunk suppression, queue-barrier
ordering, and one structured error instead of complete.
- `AC-PLATFORM-PROVIDER-ERROR-RECOVERY-001.13`: ACP tests cover progress that
clears the pending marker. They also cover a later matching marker that re-arms
it.
- `AC-PLATFORM-PROVIDER-ERROR-RECOVERY-001.14`: a new `routingerr` test file
covers the semantic code, class, rule ID, invariants, and negative cases. It
also covers the `[canceled]` non-veto case.
- `AC-PLATFORM-PROVIDER-ERROR-RECOVERY-001.15`: a new orchestrator test file
covers safe retry scheduling. It covers fail-closed behavior for missing,
stale, output, and tool evidence. It also covers prompt-generation
replacement.
## Work orders
- [x] [Task 01: Project Cursor terminal evidence](task-01-project-cursor-terminal-evidence.md)
- [x] [Task 02: Classify Cursor stream resets](task-02-classify-cursor-stream-resets.md)
- [x] [Task 03: Gate automatic prompt replay](task-03-gate-automatic-prompt-replay.md)
## Verification results
- Task 01: `cd apps/backend && go test -race ./internal/agentctl/server/adapter/transport/acp -run 'Test(CursorRetriable|ObserveCursorRetriable|SendPrompt.*Cursor)'` passed.
- Task 02: `cd apps/backend && go test -race ./internal/agent/runtime/routingerr -run 'Test(ClassifyCursorRetriable|MatchRuntimeEnvironmentRules_CursorRetriable|IsTransientProviderError_Cursor)'` passed.
- Task 03 targeted suite: `cd apps/backend && go test -race -tags fts5 ./internal/orchestrator -run 'Test(HandleTransientFailure.*Replay|PromptAttemptEvidence|CursorTransportLost)'` passed.
- Remediation identity-fence suite: `cd apps/backend && go test -race -tags fts5 ./internal/orchestrator -run 'TestDynamicAttemptEvidence|TestDynamicPreResultRequiresExplicitKnownEvidence|TestHandleTransientFailure.*Replay|TestCursorTransportLost'` passed.
- Full lifecycle race suite: `go test -race ./internal/agent/runtime/lifecycle` passed, 2088 tests.
- Full orchestrator race suite: `go test -race -tags fts5 ./internal/orchestrator` passed, 2261 tests.
- `make -C apps/backend lint` and changed-lines `golangci-lint` passed with 0 issues.
- Changed Go files reported no `gofmt` differences; `git diff --check` passed.
- `python3 scripts/lint-spec-files.py --all` passed.
- `make -C apps/backend test` was attempted. The changed packages passed, while unrelated baseline tests failed because the host config discovery selected `/root/.kandev/config.yaml` and the GitHub fixture lacked `github_task_prs`.
## Risks
- ACP notification ordering can misclassify Cursor-owned retry progress if the
pending marker is examined before the queue barrier.
- Clearing on an old tool update can hide a true terminal failure. Only renewed
provider generation or a newly-started tool can clear the marker.
- Generalizing replay evidence can expose existing transient tests that assumed
unknown evidence was safe. Those tests must provide explicit safe evidence or
assert manual recovery.
- A stale prompt generation must not clear or authorize a successor turn.