fix(sentry): summarize conversation id + wizard mapping

[BigSimmo]

Summary

• Re-declare dark body/heading ink and companion roles on .dark .ckb-v2 after the cascade port so light .ckb-v2 matching inside dark subtrees cannot resolve light ink on dark surfaces.
• Merge origin/main to clear DIRTY mergeability (prefer main’s post-feat(design-system): v2 token layer + 26 components — reconciled, cascade-ported, forced-colours owned #1538/fix(design-system): critique fixes + post-merge truth sweep (bundled hygiene PR) #1541 component copies; keep this tip’s dark-ink contract + HCM transparent overlay-backdrop rationale).
• Tabs: aria-controls only on the selected tab when a panel is owned (unselected tabs no longer point at missing IDs).
• Tooltip: compose mouse/focus/keydown handlers with the child’s existing handlers instead of replacing them.

RAG impact: no retrieval behaviour change — design-system token dark-cascade fix and unadopted UI component a11y only; no file under src/lib/rag/**, clinical-search, retrieval-selection, ranking, eval harness, golden fixtures, or retrieval RPCs is touched.

Verification

• npm run verify:pr-local
• focused: vitest tests/ckb-v2-token-contract.test.ts + tests/ui-v2-components.dom.test.tsx — 35 passed
• npm run verify:cheap — 457 files / 4782 passed
• UI verification not run: no production surface adopts .ckb-v2 / these components yet; phone-chrome and visual journeys unchanged. Prefer CI Production UI on this tip.

Risk and rollout

• Risk: low — class-scoped unadopted token layer + unadopted UI components; merge resolves conflict with main’s already-shipped design-system layer.
• Rollback: revert the squash / tip commits; no schema, data, or provider surface.
• Provider or production effects: None.

Clinical Governance Preflight

• Source-backed claims still require linked source verification before clinical use
• No patient-identifiable document workflow was introduced or expanded without explicit governance approval
• Supabase target remains Clinical KB Database (sjrfecxgysukkwxsowpy)
• Service-role keys and private document access remain server-only
• Demo/synthetic content remains clearly separated from real clinical sources
• Source metadata, review status, and outdated/unknown-source behavior remain conservative
• Deployment classification/TGA SaMD impact was checked when clinical decision-support behavior changed

Notes

• Remaining playbook work stays in later tranches (SPEC §13).
• Companion design-system docs already on main via docs(design-system): resolved five-document spec set + repair of the broken sentry merge #1531 / docs(design-system): perfection pass — per-component contracts, playbook, authoring DoD, usage rules #1537 / feat(design-system): v2 token layer + 26 components — reconciled, cascade-ported, forced-colours owned #1538 / fix(design-system): critique fixes + post-merge truth sweep (bundled hygiene PR) #1541.

Summary by CodeRabbit

• Enhancements

  • Improved monitoring for document summarization requests by associating each interaction with a unique conversation ID.
  • Expanded monitoring documentation for answer, streaming answer, and document-summary workflows.

• Tests

  • Added coverage to verify conversation IDs are assigned before document summarization begins.

[supabase]

This pull request has been ignored for the connected project sjrfecxgysukkwxsowpy because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 24 minutes

Your organization has reached its usage spending cap. Adjust your spending cap in the billing tab.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 2a7e252d-3517-4bda-b807-c1a9be3999e9

📥 Commits

Reviewing files that changed from the base of the PR and between 70173ce and a61470c.

📒 Files selected for processing (1)

• docs/error-tracking.md

📝 Walkthrough

Walkthrough

The document summarize route now assigns a synthetic interaction ID to agent monitoring before summarization. The route reuses the ID in feedback metadata and observability. Tests verify call order and UUID reuse. Documentation records the monitoring configuration.

Changes

Document summary monitoring

Layer / File(s)	Summary
Conversation ID wiring and validation src/app/api/documents/[id]/summarize/route.ts, tests/summarize-agent-conversation.test.ts	The route creates an interaction ID before summarization, assigns it to agent monitoring, and reuses it in response metadata. The test verifies ordering, UUID format, and observability metadata.
Agent monitoring documentation docs/error-tracking.md	The documentation covers answer, streaming answer, and document-summary requests. It maps repository settings to the Sentry Agent Monitoring wizard.

Estimated code review effort: 2 (Simple) | ~10 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant Route as Document summarize route
  participant Monitoring as Agent monitoring
  participant Summarizer as summarizeDocument
  participant Observability
  Client->>Route: POST summarize request
  Route->>Monitoring: Set interaction ID
  Route->>Summarizer: Summarize document
  Route->>Observability: Record interaction ID
  Route-->>Client: Return summary and interaction ID

Loading

Possibly related PRs

• BigSimmo/Database#634: Modifies the same document-summary route and feedback metadata flow.
• BigSimmo/Database#1478: Introduces the related Sentry and agent-monitoring documentation.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description is largely off-topic and omits the document summarization, Sentry instrumentation, documentation, and test changes.	Update the description to summarize the actual Sentry changes, document the verification performed, and describe the relevant risks and rollout effects.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly describes the Sentry conversation ID change and Agent Monitoring wizard mapping.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

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

[ecc-tools]

🔒 Upgrade Required

Private repository analysis requires Pro or Enterprise.

Upgrade: https://ecc.tools/pricing?plan=pro

---

_{ECC Tools keeps the core app open, and puts private repos, team features, and enterprise controls behind paid tiers.}

[ecc-tools]

🔒 Upgrade Required

Private repository analysis requires Pro or Enterprise.

Upgrade: https://ecc.tools/pricing?plan=pro

---

_{ECC Tools keeps the core app open, and puts private repos, team features, and enterprise controls behind paid tiers.}

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

[ecc-tools]

🔒 Upgrade Required

Private repository analysis requires Pro or Enterprise.

Upgrade: https://ecc.tools/pricing?plan=pro

---

_{ECC Tools keeps the core app open, and puts private repos, team features, and enterprise controls behind paid tiers.}

[qodo-code-review]

PR Summary by Qodo

Fix Sentry agent-monitoring conversation IDs for document summaries

🐞 Bug fix 🧪 Tests 📝 Documentation 🕐 10-20 Minutes

AI Description

• Set Sentry agent-monitoring conversation id before document-summary OpenAI calls.
• Document how Sentry “Agent Monitoring” wizard steps map to this repo.
• Add regression test asserting conversation id is set before summarize execution.

Diagram

graph TD
  R["/api/documents/[id]/summarize"] --> U["interactionId (UUID)"] --> C["setAgentConversationId()"] --> S{{"Sentry agent monitoring"}}
  R --> D["summarizeDocument()"] --> O{{"OpenAI API"}}

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Centralize interaction context creation (helper/middleware)

• ➕ Prevents future drift where new routes forget to set conversation id early
• ➕ Can standardize interactionId generation + Sentry context + feedback token wiring
• ➖ Requires additional plumbing across Next route handlers (and possibly streaming paths)
• ➖ May be overkill for a small number of endpoints

2. AsyncLocalStorage-based request context for Sentry conversation id

• ➕ Eliminates explicit per-route calls; context can be applied deep in the call stack
• ➕ Makes it harder to accidentally set the conversation id too late
• ➖ More complex and runtime-sensitive in Next.js/edge boundaries
• ➖ Harder to reason about and test; may add subtle context-leak risks if misused

Recommendation: The PR’s approach (explicitly setting interactionId + setAgentConversationId at the top of the summarize route) is the best fit for now: it’s simple, testable, and keeps privacy constraints obvious at the callsite. If more LLM-backed endpoints are added, consider a small shared helper to enforce the “set before LLM work” contract everywhere.

Files changed (3) +116 / -2

Bug fix (1) +5 / -1

route.tsSet Sentry conversation id before document summarization runs +5/-1

Set Sentry conversation id before document summarization runs

• Generates a synthetic 'interactionId' and calls 'setAgentConversationId(interactionId)' immediately after rate limiting and before invoking 'summarizeDocument()'. Keeps the same 'interactionId' used for 'answerFeedbackMetadata' in the response.

src/app/api/documents/[id]/summarize/route.ts

Tests (1) +95 / -0

summarize-agent-conversation.test.tsAdd regression test for summarize conversation id ordering +95/-0

Add regression test for summarize conversation id ordering

• Introduces a Vitest unit test that mocks 'setAgentConversationId' and 'summarizeDocument' to assert the conversation id is set exactly once and before any LLM summarization work begins. Also verifies the returned 'interactionId' is a UUID and matches the id passed to 'setAgentConversationId'.

tests/summarize-agent-conversation.test.ts

Documentation (1) +16 / -1

error-tracking.mdDocument conversation-id timing and Sentry wizard mapping +16/-1

Document conversation-id timing and Sentry wizard mapping

• Updates the privacy/agent-monitoring section to state that conversation IDs are set before any OpenAI work for answer, stream, and document summarize routes. Adds a table mapping Sentry’s “Agent Monitoring” wizard steps to the repo’s actual files/config and explicitly calls out rejected wizard options (recording inputs/outputs, setUser).

docs/error-tracking.md

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

_{To customize comments, go to the Qodo configuration screen, or learn more in the docs.}

[ecc-tools]

🔒 Upgrade Required

Private repository analysis requires Pro or Enterprise.

Upgrade: https://ecc.tools/pricing?plan=pro

---

_{ECC Tools keeps the core app open, and puts private repos, team features, and enterprise controls behind paid tiers.}

[ecc-tools]

🔒 Upgrade Required

Private repository analysis requires Pro or Enterprise.

Upgrade: https://ecc.tools/pricing?plan=pro

---

_{ECC Tools keeps the core app open, and puts private repos, team features, and enterprise controls behind paid tiers.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/error-tracking.md`:
- Line 46: Align the `@sentry/nextjs` version entries in both tables of
error-tracking.md: use the current repository dependency range consistently, or
explicitly label 10.67 as the minimum supported version if that distinction is
intended. Ensure the documentation does not present conflicting dependency
ranges or installed versions.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 8d113554-0b31-4425-ad8a-3d0d738edf11

📥 Commits

Reviewing files that changed from the base of the PR and between b1e0117 and 70173ce.

📒 Files selected for processing (3)

• docs/error-tracking.md
• src/app/api/documents/[id]/summarize/route.ts
• tests/summarize-agent-conversation.test.ts

[ecc-tools]

🔒 Upgrade Required

Private repository analysis requires Pro or Enterprise.

Upgrade: https://ecc.tools/pricing?plan=pro

---

_{ECC Tools keeps the core app open, and puts private repos, team features, and enterprise controls behind paid tiers.}