Poll cached full scan results until ready

[John-David Dalton (jdalton)]

LLM Description written by Codex:gpt-6-astra

Keep full-scan reads working while analysis is still processing. Existing callers now use cached results with bounded polling instead of holding one long request.

Root Cause

fullscans.stream() made one uncached request and treated 202 Processing as a failed result.

Fix

• Poll cached results within the caller's configured timeout.
• Retry processing responses and existing transient errors; preserve authorization and not-found failures.
• Keep dictionary and typed artifact parsing unchanged.

Validation

29 tests pass against a local HTTP fixture using the real SDK and requests transport. Ruff and diff checks pass. Tests cover processing, timeout, transient and permanent failures, encoded identifiers, invalid settings, and artifact parsing.

No SDK release or CLI dependency update is included.

Public Changelog

Full-scan reads wait for cached analysis results within the configured timeout.

---

Note

Medium Risk
Changes default full-scan read behavior (cached polling, longer wall time, new timeout errors) for all stream() callers; logic is well-tested but affects a core API path.

Overview
fullscans.stream() no longer treats a single 202 Processing as failure. It requests ?cached=true, polls with exponential backoff (defaults 5–10s) until results are ready or the budget expires, and raises APITimeout when the poll window runs out.

Polling honors optional poll_timeout_seconds (default: SDK request timeout), validates timeout/interval values up front, URL-encodes org and scan IDs, retries transient APIFailures and 202 responses, and still fails fast on auth/not-found errors. HTTP responses are closed after use.

API.do_request gains an optional per-call request_timeout override so each poll uses a bounded timeout (min(30s, configured timeout, remaining poll budget)).

New localhost HTTP fixture and unit tests cover ready/processing/empty streams, retries, timeouts, encoded IDs, and invalid settings.

^{Reviewed by Cursor Bugbot for commit 97d148a. Configure here.}