fix(observability): classify OpenHuman/Embedding/streaming backend 'Invalid token' 401 as SessionExpired (TAURI-RUST-4P0 + 4K5 + 1EE)

[CodeGhost21]

Summary

Extend is_session_expired_message in src/core/observability.rs to recognise the OpenHuman backend's {"success":false,"error":"Invalid token"} 401 envelope as a session-expired condition (previously only the explicit "Session expired. Please log in again." body was recognised). The same upstream cause — backend rejecting the bearer JWT as invalid — surfaces under three emit-site prefixes depending on the call path, each producing its own Sentry fingerprint:

Sentry ID	Emit-site prefix	Source	Events
TAURI-RUST-4P0	OpenHuman API error (401 …)	non-streaming chat (run_chat_task)	—
TAURI-RUST-4K5	Embedding API error (401 …)	embeddings/openai.rs:139	~118
TAURI-RUST-1EE	OpenHuman streaming API error (401 …)	streaming chat (compatible.rs:949)	~110

All three are typically preceded by a [scheduler_gate] signed_out false -> true breadcrumb. The UI already drives reauth via the SessionExpired event-domain path; this stops the noise leaking into Sentry as a code bug.

Why three arms, not one

The matcher uses conjunctive anchors per arm — "<emit-site prefix> (401" AND the envelope-shaped "\"error\":\"Invalid token\"". Anchoring on each OpenHuman-scoped prefix is what preserves the #2286 BYO-key contract:

• "OpenAI API error (401 Unauthorized): invalid_api_key" (user's own OpenAI key revoked) must NOT match.
• "OpenAI streaming API error (401): invalid_api_key" and "Embedding API error (401): invalid_api_key" (BYO embedding/streaming key revoked) must NOT match either.

Each of those is pinned by a dedicated does_not_classify_*_byo_key_401_as_session_expired polarity guard. A single broad "any 401 + invalid token" matcher would silence all of them, so each OpenHuman-backend emit-site prefix gets its own prefix-gated arm. The streaming token in 1EE specifically means the 4P0 anchor can't cover it.

Tests added (observability::tests)

• classifies_openhuman_invalid_token_401_as_session_expired — 4P0 (wrapped + unwrapped).
• classifies_embedding_api_invalid_token_401_as_session_expired — 4K5 (direct + wrapped).
• classifies_openhuman_streaming_invalid_token_401_as_session_expired — 1EE (direct + wrapped).
• does_not_classify_embedding_byo_key_401_as_session_expired — embedding polarity guard.
• does_not_classify_streaming_byo_key_401_as_session_expired — streaming polarity guard.
• Existing does_not_classify_byo_key_provider_401_as_session_expired — SessionExpired clears the session for unrelated backend 401s #2286 chat-path contract, still green.

Test plan

• cargo test classifies_openhuman_invalid_token — passes (4P0)
• cargo test classifies_embedding_api_invalid_token — passes (4K5)
• cargo test classifies_openhuman_streaming_invalid_token — passes (1EE)
• cargo test does_not_classify_embedding_byo_key / does_not_classify_streaming_byo_key / does_not_classify_byo_key_provider — pass (polarity)
• cargo test core::observability — 93 tests pass, 0 regressions
• cargo check --bin openhuman-core — passes
• cargo fmt --check — clean

Related

Self-hosted Sentry (sentry.tinyhumans.ai, tauri-rust project) — no GitHub issue:

Closes TAURI-RUST-4P0
Closes TAURI-RUST-4K5
Closes TAURI-RUST-1EE

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds conjunctive matching and docs in is_session_expired_message to classify OpenHuman/Embedding 401 "Invalid token" JSON envelopes as SessionExpired, and adds regression tests covering wrapped/unwrapped and negative BYO-key cases.

Changes

OpenHuman 401 Invalid Token Classification

Layer / File(s)	Summary
Session-expired classification for OpenHuman 401 invalid-token src/core/observability.rs	Doc comment expanded to describe the OpenHuman 401 {"error":"Invalid token"} envelope and the embedding wrapper; is_session_expired_message updated to conjunctively require the "OpenHuman API error (401" or "Embedding API error (401" prefix plus the exact invalid-token envelope before returning ExpectedErrorKind::SessionExpired.
Regression tests for invalid-token classification src/core/observability.rs	New tests assert both wrapped run_chat_task and unwrapped OpenHuman invalid-token envelopes classify as SessionExpired; verify embedding invalid-token wrapper classifies as SessionExpired; and guard that BYO-key/generic 401 variants do not classify as session-expired.

Sequence Diagram(s)

(omitted — change is a targeted classifier update and tests; no multi-component sequential flow requires visualization)

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• tinyhumansai/openhuman#2188 — Related tests and changes touching is_session_expired_message and SessionExpired matching.
• tinyhumansai/openhuman#1763 — Related updates to is_session_expired_message for OpenHuman 401 shapes.
• tinyhumansai/openhuman#2200 — Integrates classifier changes into ReliableProvider retry/abort behavior that depends on SessionExpired detection.

Suggested reviewers

• senamakel
• graycyrus
• M3gA-Mind

Poem

🐰 A token slipped out of date and key,
The 401 whispered, "Invalid token" to me.
I matched prefix and envelope with care,
So sessions expire only when they truly bear.
Hooray — tests hop in, the classifier set free!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title directly summarizes the main change: classifying OpenHuman/Embedding invalid token 401 responses as SessionExpired, which is the primary purpose of the changeset.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[graycyrus]

@CodeGhost21 hey! the code looks good to me — the conjunctive anchor approach is exactly right here. Requiring both the "OpenHuman API error (401" prefix and the envelope-shaped "\"error\":\"Invalid token\"" body together is the correct way to preserve the #2286 contract while catching this specific backend branch, and the two new test cases pin both the verbatim Sentry wire shape and the unwrapped emit shape cleanly.

CI still has a few checks pending (Windows E2E, core image build, Rust core coverage). Once those come back green I'll come back and approve this. Let me know if anything comes up in the meantime.

[graycyrus]

@CodeGhost21 the two follow-on commits look clean — the 4K5 (Embedding API) and 1EE (streaming) arms follow the same conjunctive-anchor pattern as the original 4P0 arm, the polarity guards for BYO-key embedding and streaming 401s are solid, and the test coverage (direct + caller-wrapped shapes for each arm) is thorough.

One CI check is still pending (Windows / Appium Chromium E2E). Once that clears, I'll come back and approve this.

[oxoxDev]

Walkthrough

Extends is_session_expired_message in src/core/observability.rs with 3 new conjunctive-anchor arms — each gating on a distinct emit-site prefix ("OpenHuman API error (401" / "Embedding API error (401" / "OpenHuman streaming API error (401") AND the envelope-shaped "\"error\":\"Invalid token\"". Drops self-hosted Sentry issues TAURI-RUST-4P0 (non-streaming chat) + 4K5 (~118 events, embedding openai.rs:139) + 1EE (~110 events, streaming compatible.rs:949). +209/-0, 1 file. 5 new tests. All CI green.

Verified

• Three-prefix split is real: "streaming" token between OpenHuman and API error breaks the 4P0 anchor on 1EE, so each path genuinely needs its own arm — confirmed in author doc + test ✓
• Polarity arithmetic: BYO 401s carry invalid_api_key / authentication_error payloads — they hit the prefix anchor but the envelope anchor "error":"Invalid token" fails → no match → still reach Sentry. Confirmed for OpenAI/Anthropic/Voyage/Cohere shapes ✓
• Pre-existing does_not_classify_byo_key_provider_401_as_session_expired (#2286 contract) still in place; both new polarity guards (embedding + streaming BYO) extend the same contract per emit-site ✓
• Wire-shape envelope tolerant of optional whitespace: {"success":false,"error":"Invalid token"} and {"success":false, "error":"Invalid token"} both substring-match "error":"Invalid token" ✓

Nits

• The 3 arms share the same (<prefix> && envelope) shape. When a 4th emit-site (e.g. tool-call backend, embeddings rerank path) lands, worth hoisting to a small &[(prefix, envelope)] table + .iter().any(...) so each new arm is one tuple line, not 4 lines of boilerplate. Don't block on it.
• Envelope match is case-sensitive on "Invalid token". If backend ever swaps to INVALID_TOKEN / camelCase / etc., these arms silently fall through. Cheap defense: anchor on the lowercase variant via lower.contains(...) like the existing arms above. Worth a follow-up.
• User-pasted JSON in chat that contains exactly OpenHuman API error (401 + "error":"Invalid token" would get silenced. Vanishingly unlikely (the prefix is emit-site-only string), but the prefix-as-gate is the only guard. Flagging only.

Questions

• Did you check whether the expected_error_kind dispatch path that calls is_session_expired_message produces an ExpectedErrorKind::SessionExpired with the same Breadcrumb-vs-Ignore tier as the existing arms? (Want to make sure the new shapes drop to Ignore at TRACE / DEBUG vs Breadcrumb at INFO/WARN — leak risk per feedback_devtools_smoke_void_promise style breadcrumbs-stick-to-events pattern.)
• Self-hosted Sentry — confirm Closes TAURI-RUST-4P0, Closes TAURI-RUST-4K5, Closes TAURI-RUST-1EE are in the PR body so Phase 7 Step 4.5 self-hosted sweep flips them on merge.

[CodeGhost21]

@oxoxDev thanks for the thorough review and the approval! Answering your two questions:

Q1 — tier / breadcrumb-leak risk. No divergence: classification routes on the kind, not the message shape. is_session_expired_message → expected_error_kind returns Some(ExpectedErrorKind::SessionExpired), and report_expected_message funnels every SessionExpired through the single match arm at src/core/observability.rs:1064, which deliberately demotes to tracing::info! ("breadcrumb survives for trace correlation but Sentry sees no error event"). All three new arms (4P0/4K5/1EE) inherit that exact treatment — there is no per-shape tier branch, so the new shapes can't drop to a different Breadcrumb/Ignore level than the existing arms. No leak risk introduced beyond the already-accepted SessionExpired behavior.

Q2 — self-hosted Sentry close directives. Added to the PR body under a new ## Related section:

Closes TAURI-RUST-4P0
Closes TAURI-RUST-4K5
Closes TAURI-RUST-1EE

One heads-up for the Phase 7 Step 4.5 sweep: PR #2692's body flagged that the post-merge resolve regex is anchored to OPENHUMAN-(TAURI|REACT|CORE) and may not match the bare TAURI-RUST-* prefix yet. If that widening hasn't landed, these may need a manual flip on merge.

Nits — all noted as follow-ups (not in this PR): the &[(prefix, envelope)] table hoist when a 4th emit-site lands, case-insensitive "invalid token" matching, and the user-paste edge case. Agreed they're worth a follow-up but not blockers here.

[sanil-23]

Posted #2869 with the root-cause fix: #2830's merge inadvertently reverted #2786's SessionExpired classification back to BackendUserError, so the classifies_embedding_api_invalid_token_401_as_session_expired test added by #2786 has been failing on every PR rebased onto post-#2830 main. One-line classifier fix + reconciled the stale companion test.