You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* release: v0.7.1 — provider error handling pass
A focused pre-release review (5-persona + 2-persona re-review) widened v0.7.1
from a single OpenAI-message-extraction fix into a tight provider-error pass.
All changes are surgical, marker-disciplined, and pinned by 40 adversarial
tests in `release-v0.7.1-adversarial.test.ts`.
User-facing fixes:
- Bedrock / AWS Lambda `errorMessage` shape now extracted by both
`parseAPICallError` and `parseStreamError`.
- `parseStreamError` no longer falls through to `JSON.stringify(e)` for
non-OpenAI codes — uses the same string-typeof chain as the API path.
- `model_not_found` short-circuits OpenAI 404 retry-storm; user sees the
actionable error on attempt 1 instead of after 5 silent retries.
- `altimate models` discoverability hint appended on `model_not_found`.
Privacy / defense-in-depth:
- `Telemetry.maskString` redacts email addresses and internal hostnames
(`*.local` / `*.internal` / RFC1918 / IMDS) so the unwrapped provider
text from #789 doesn't leak more PII than the prior JSON-quote shred.
- `MessageV2.APIError.metadata.url` masks internal hosts (incl. IPv6
loopback / ULA / link-local, AWS IMDS) and strips basic-auth userinfo
before the URL flows into local storage / share / telemetry.
- `responseBody` capped at 4KB at the `parseAPICallError` boundary.
Docs:
- New "Provider API Errors" section in `docs/docs/reference/troubleshooting.md`.
CI gates passed locally:
- typecheck (`tsgo --noEmit`): clean
- marker guard (`analyze.ts --markers --base main --strict`): clean
- pre-release (`bun run pre-release`): all 4 checks pass; binary starts
- targeted tests: 102/102 (provider/error + adversarial + branding + retry)
- full opencode suite: 8011 pass / 503 skip / 0 fail
Closes#788
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix: address PR #794 review feedback (CodeRabbit + cubic)
CodeRabbit and cubic flagged three classes of issue on the v0.7.1 PR.
All three are addressed here; CHANGELOG, troubleshooting doc, and code
are now consistent.
1. Hint spelling consistency (CR Minor / cubic P3)
- Three different forms shipped in the original PR:
- error.ts:290 -> "Run `altimate models` to see available models."
- troubleshooting.md:47 -> "altimate-code models <provider>"
- CHANGELOG.md:21 -> "Run `altimate-code models` to see available models."
- Aligned to the form actually emitted by the code: `altimate models`
(no dash, no provider arg). troubleshooting.md auth-login example
also aligned to `altimate auth login` to match error.ts:99.
2. maskString missing IMDS + IPv6 (CR Major / cubic P1)
- The regex covered only RFC1918 + *.local / *.internal, while the
paired maskInternalHost in error.ts already covered AWS IMDS
(169.254.169.254), IPv6 loopback ([::1]), ULA (fc00::/7), and
link-local (fe80::/10).
- Extended the regex so an error string containing the same URL is
redacted with the same coverage as the metadata.url path.
- Added query-string/fragment chars (`+`, `#`, `,`, `;`) to the
trailing char class so secrets after `?` don't survive past the
`<internal-host>` marker.
- 5 new adversarial tests for IMDS, IPv6 loopback/ULA/link-local,
and the query/fragment leak guard.
3. maskInternalHost only stripped userinfo for internal hosts (cubic P1)
- Previously, `https://user:pass@10.0.0.5/x` redacted host AND
userinfo, but `https://user:pass@api.openai.com/x` preserved
`user:pass@`. A credential in a public-host URL is at least as
sensitive as one in an internal-host URL — strip userinfo on
EVERY URL, regardless of internal/public classification.
- 1 new adversarial test for public-host userinfo strip.
Also expanded the upstream_fix marker comment in parseAPICallError to
mention all four extractor shapes (OpenAI nested, Anthropic-style top-
level, Bedrock errorMessage, legacy string error) so readers don't have
to reverse-engineer the chain.
Tests: 46 release-v0.7.1 adversarial cases (40 -> 46), 238/238 across
provider+adversarial+upgrade+retry+telemetry suites. Typecheck clean.
Marker guard --strict clean.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix: wrap capResponseBody call sites in altimate_change markers
The capResponseBody helper was wrapped in markers but the two call
sites in parseAPICallError (context_overflow and api_error returns)
were unmarked. Marker analyzer --strict caught this. Same fix as the
"hint comment expanded" pass — every modified line in an upstream-
shared file needs to live inside a marker block.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix: wrap finalMessage usage in altimate_change markers
* fix: address PR #794 round-2 review feedback (cubic P1 + CR nits)
cubic flagged a real P1 on the previous round's commit and CodeRabbit
posted a few low-value nits worth picking up while we're here.
P1 (cubic) — `Telemetry.maskString` URL regex missed URLs carrying
basic-auth userinfo before the host. `https://admin:hunter2@10.0.0.5/x`
fell through unredacted because the regex started with the host
alternation. Added an optional `(?:[^\/\s@]+@)?` userinfo prefix so the
whole URL — credentials + host — is captured into `<internal-host>`.
CR quick wins:
- Hoisted the `Telemetry` import to the top of the adversarial test
file (mid-file imports work in Bun but tooling that scans headers
miss them).
- Tightened the `/models` hint test to assert the full canonical string
``Run `altimate models` to see available models.`` so docs / changelog
/ code can't quietly diverge again.
Defense-in-depth from CR nits:
- Added `0.0.0.0` (any-interface bind) to maskInternalHost — shows up
in misconfigured proxy URLs and is functionally internal.
- Added a one-line comment to the silent `catch {}` in
isOpenAiErrorRetryable so a future refactor doesn't "fix" it into
something that throws on malformed JSON.
Also added 2 new adversarial tests pinning the userinfo+host case and
the `0.0.0.0` case (240/240 across the 5 affected files, up from 238).
Deferred to v0.7.2: extracting `makeAPICallError` to a shared fixture
(refactor, scope creep), reusing `codeFromBody` in
`isOpenAiErrorRetryable` (signature change), IPv4-mapped IPv6
(`::ffff:10.0.0.1`) coverage, byte-vs-char `RESPONSE_BODY_CAP` rename.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix: pin prototype-pollution test to a real malicious payload
CodeRabbit caught that the __proto__ regression guard was hollow:
JSON.stringify({__proto__: ...}) produces `{}` — `__proto__` in
object-literal syntax is the prototype setter, not an enumerable
own property, so it never makes it into the JSON. The test was
serializing an empty payload and asserting prototype wasn't
polluted (trivially true).
Replace the JSON.stringify call with a hand-written JSON literal
containing an explicit "__proto__" key. parseAPICallError's
JSON.parse now actually receives the malicious key, exercising
the regression guard against a future refactor that switches
to Object.assign / spread.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix: address PR #794 round-4 nits + bump release date
CodeRabbit Quick Wins:
1. Wrap prototype-pollution tests in try/finally. If a regression ever
breaks the guards, Object.prototype stays polluted for the rest of
the suite — cascading noise instead of a localized failure. The
finally block restores (or deletes) the original key value.
2. Pin the 4KB truncation boundary exactly. The test was asserting
`length < 5000`, which would still pass if a future refactor moved
the cap from 4096 → 4500 → 4900 — none of those are the documented
guarantee. Now asserts the exact 4096-char prefix and the full
truncation suffix `…[truncated 95904 chars]`. Cap is now the
load-bearing assertion, not the upper bound.
Also bumped CHANGELOG date to today (2026-05-06) since the tag pushes today.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix: deflake tracing-display-crash flushSync test
CI run 25448250105 hit:
(fail) flushSync — crash recovery > flushSync preserves all
accumulated data [126.00ms]
The test used two `await new Promise((r) => setTimeout(r, 50))` waits
for async snapshot operations to settle. The neighboring test on the
same describe block already documents this exact failure mode and uses
`await tracer.flush()` as the deterministic antidote (see comment at
line 215: "deterministic vs sleep(50) which flakes on slow CI runners").
Replace both setTimeout waits with `tracer.flush()`. Locally now ~700ms
(was ~1.2s with the sleeps) and 5/5 passes in a row. The test exercises
the same crash-recovery invariants with no timing dependency.
Pre-existing flake unrelated to v0.7.1 scope but blocking the release
PR's CI — fixing in scope per the project's "no flaky tests" rule.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Copy file name to clipboardExpand all lines: CHANGELOG.md
+26Lines changed: 26 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,6 +5,32 @@ All notable changes to this project will be documented in this file.
5
5
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
8
+
## [0.7.1] - 2026-05-06
9
+
10
+
A focused pass on provider error handling, surfaced by a 5-persona pre-release review.
11
+
12
+
### Fixed
13
+
14
+
-**Provider 4xx errors now show the inner error message instead of a raw JSON dump.** When any provider returned the standard `{error: {message, type, code}}` shape (OpenAI, Azure OpenAI, OpenRouter, etc.), `parseAPICallError`'s extraction chain short-circuited on the truthy parent `error` object, the `typeof errMsg === "string"` guard rejected it, and the parser fell through to dumping the raw response body — which appeared as `APIError: Bad Request: {?:?}` after telemetry redaction collapsed string values to `?`. Telemetry caught users retrying broken model selections 3+ times in the same session because the surfaced error gave no clue about the cause. Users now see actionable text such as `APIError: Bad Request: The model 'gpt-5-codex' does not exist or you do not have access to it.` The OR-chain is replaced with explicit-typeof ternaries that mirror `parseStreamError`'s pattern, so a truthy non-string at any tier cannot block a valid string further down the chain. (#789, closes #788)
15
+
-**Bedrock / AWS Lambda `errorMessage` shape is now extracted.** AWS APIs that return `{errorMessage: "...", errorType: "..."}` (Lambda style) previously fell through the OpenAI/Anthropic-shaped chain to a raw-body dump. Added `body.errorMessage` to the extraction ladder in both `parseAPICallError` and `parseStreamError`.
16
+
-**Streaming error path no longer dumps `Unknown: {"type":"error",...}` for non-OpenAI codes.**`parseStreamError` previously handled only 4 OpenAI error codes (`context_length_exceeded`, `insufficient_quota`, `usage_not_included`, `invalid_prompt`); everything else fell through to `JSON.stringify(e)`. Added a default fallback that runs the same string-typeof chain as `parseAPICallError`, so any extractable provider message becomes a clean api_error.
17
+
-**`model_not_found` no longer triggers a silent retry storm.** OpenAI 404s are forced retryable in general (some legitimate models 404 transiently), but `error.code === "model_not_found"` now short-circuits to `isRetryable: false` — the user sees the actionable error on attempt 1 instead of after 5 silent retries.
18
+
19
+
### Added
20
+
21
+
-**`altimate models` discoverability hint on model-not-found errors.** When `error.code === "model_not_found"`, the surfaced message now ends with `Run \`altimate models\` to see available models.` so the next step is one command away.
22
+
-**Provider-API-Errors troubleshooting reference** at `docs/docs/reference/troubleshooting.md` covering model-not-found, unauthorized, rate-limited, context-overflow, and HTML-page error classes.
23
+
24
+
### Privacy
25
+
26
+
-**`Telemetry.maskString` now redacts email addresses and internal hostnames.** Pre-fix, the JSON-quote masking rule incidentally collapsed everything inside provider error JSON to `?`. The provider-error fix unwraps that JSON, which means provider-side identifiers (caller emails, internal `*.local` / `*.internal` / RFC1918 / IPv6 loopback / ULA / link-local / AWS IMDS endpoints) now flow as plain English. Added explicit redaction patterns so they're masked before reaching telemetry, the share backend, or local session storage. The masker is kept in sync with `parseAPICallError`'s `maskInternalHost` (same internal-endpoint coverage); query-string and fragment characters (`+`, `#`, `,`, `;`) are inside the trailing char class so secrets past the `<internal-host>` marker don't survive. `sk-…` and `Bearer …` token redaction is unchanged.
27
+
-**`metadata.url` on `MessageV2.APIError` masks internal hosts and strips basic-auth userinfo.** When `error.url` points at `localhost`, `*.local`, `*.internal`, an RFC1918 IPv4, IPv6 loopback / ULA / link-local, or the AWS IMDS address (`169.254.169.254`), the host is rewritten to `internal-host.redacted` before the URL lands on the parsed error. Basic-auth userinfo (`user:pass@…`) is stripped on **every** URL — internal or public — since a credential in a public-host URL is at least as risky as one in an internal proxy. Public-host URLs are otherwise preserved verbatim for debugging.
28
+
-**`responseBody` is capped at 4KB** at the `parseAPICallError` boundary. Without this, a hostile or verbose gateway could persist a 100KB+ body into local storage and (for shared sessions) the share backend.
29
+
30
+
### Testing
31
+
32
+
- 46 adversarial tests covering JSON-scalar bodies, prototype-pollution attempts, 100KB error messages, malformed JSON, every-tier null/numeric extraction, Bedrock `errorMessage` precedence, the `parseStreamError` fallback for unknown codes, the `model_not_found` retry-storm carve-out, the `altimate models` hint, the responseBody cap, the metadata.url internal-host masking (incl. IPv6 loopback/ULA/link-local, AWS IMDS, public-host basic-auth userinfo strip, RFC1918 boundary checks, lookalike-hostname guards), and the new email / internal-host `maskString` patterns (incl. IMDS, IPv6, and query-fragment leak guards).
3. If behind a proxy, set `HTTPS_PROXY` (see [Network](network.md))
31
31
4. Try a different provider to isolate the issue
32
32
33
+
### Provider API Errors
34
+
35
+
**Symptoms:**`APIError: <status>: <message>` shown in chat output. Common forms:
36
+
37
+
-`APIError: Bad Request: The model 'foo' does not exist or you do not have access to it.`
38
+
-`APIError: Unauthorized: Invalid API key`
39
+
-`APIError: Rate limit exceeded`
40
+
41
+
As of v0.7.1, altimate-code surfaces the **inner provider message** instead of dumping the raw JSON body. The status prefix (`Bad Request:`, `Unauthorized:`, etc.) comes from the provider's HTTP status code; everything after the colon is the provider's text verbatim.
42
+
43
+
**Solutions by error class:**
44
+
45
+
1.**Model not found** (`APIError: Bad Request: The model '<name>' does not exist...`) — list the models your provider currently exposes and re-run with one of them:
46
+
```bash
47
+
altimate models <provider>
48
+
```
49
+
`model_not_found` errors no longer auto-retry; the message you see is the first attempt, not the fifth.
50
+
2.**Unauthorized / 401** — re-run `altimate auth login <provider>` and re-issue the request.
51
+
3.**Rate limited / 429** — altimate-code automatically retries on rate-limit responses (including plain-text 429s from Alibaba/DashScope). If you keep hitting rate limits, lower `parallel_tool_calls` or switch to a less-saturated model.
52
+
4.**Context overflow** — switch to a larger-context model or trim earlier turns with `/compact`. Detection covers Anthropic, Bedrock, OpenAI, Gemini, xAI, Groq, OpenRouter, DeepSeek, Copilot, llama.cpp, LM Studio, MiniMax, Kimi, Moonshot, Azure OpenAI, and HTTP 413.
53
+
5.**HTML page returned** — usually a gateway/proxy error. The CLI returns a friendly hint pointing at `altimate auth login` rather than dumping the raw HTML.
54
+
55
+
**Privacy note:** error messages flow through the same redaction layer as everything else (`sk-…`, `Bearer …`, email addresses, and `*.local` / `*.internal` / RFC1918 / IPv6 loopback / ULA / link-local / AWS IMDS hostnames are masked before reaching telemetry). Internal-host URLs in `metadata.url` are also redacted before they reach local storage or shared sessions, and basic-auth userinfo (`user:pass@…`) is stripped from every URL regardless of whether the host is internal.
56
+
33
57
### Tool Execution Errors
34
58
35
59
**Symptoms:** "No native handler" or tool execution failures for data engineering tools.
0 commit comments