fix(cursor): preserve structured final-output contracts

[arikon]

Summary

Cursor-routed auto-review requests can end with guardian assessment was not valid JSON: the shared Responses parser retains text.format, but the Cursor adapter previously dropped it and Composer returned prose-only assessments.

Preserve json_object / json_schema through the Cursor request, render the final-answer contract into system roots, and repeat it in active user-message actions, including tool-result continuations. Bind the format (including its absence) to the checkpoint instruction digest so schema changes cannot reuse stale instructions. Ordinary text requests and intermediate tool calls retain their existing behavior.

This is a prompt fallback, not native constrained decoding or output-schema enforcement. It does not convert prose into an approval decision. Tests exercise the encoded Cursor wire action, array schemas, tool-result continuation, and checkpoint invalidation, including a format/system-text digest collision.

Verification

• Targeted regressions reproduced the missing contract before the fix and pass after it.
• bun test tests/providers/cursor — passed on the final rebased source.
• bun run typecheck — passed on the final rebased source.
• bun run structure:check, bun run privacy:scan, and git diff --check — passed on the final rebased source.
• cd docs-site && ASTRO_TELEMETRY_DISABLED=1 bun run build — passed on the final rebased source.
• Live isolated A/B using composer-2.5-fast, the same captured Guardian request, and six fresh sessions: baseline 0/3 accepted by a semantic port of Codex's tolerant assessment parser; patched 3/3 accepted (allow). Both arms were 0/3 whole-answer JSON: the patched model still prefixed the JSON with prose. This small sample establishes the reproduction, not general reliability; the Rust parser binary was not executed.
• Two fresh patched negative controls for an explicitly unauthorized destructive action returned 2/2 strict JSON deny. Tools were disabled and no reviewed action was executed. Credentials and captured transcripts are not included in this PR.
• Broader bun scripts/test.ts --changed=HEAD on the original experiment base selected 506 files: 9,946 pass, 1,554 fail, 5 skip, 3 errors. A representative unrelated failing file, tests/responses/chat-refusal.test.ts, reproduced 45 pass / 8 fail on both unpatched and patched code in the same environment. The entire broad failure set has not been classified; this PR remains draft pending CI and broader validation.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.

Review readiness checklist

This PR stays in draft until every box below is ticked. Tick all four boxes once the requirements are met:

• Required local validation passed; commands, results, and any full-suite exception are documented.

• I pushed my PR to a recent dev commit (at most 10 behind; a maintainer may still ask for the exact tip before merge).

• I resolved all correct Codex and CodeRabbit findings.

• My PR is ready for review.

Summary by CodeRabbit

• New Features

  • Cursor requests now include JSON output requirements for json_object and json_schema formats in final responses, including after tool results. Ordinary text requests and intermediate tool calls remain unchanged.
  • Changes to the output format trigger a full replay rather than reusing a checkpoint created with a different format.

• Documentation

  • Clarified that JSON requirements are prompt-based, not constrained decoding or response validation. Responses may be invalid; validate them when strict enforcement is needed.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: lidge-jun/opencodex/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 83e8e1b8-2122-4af9-96b1-fff74457bc21

📥 Commits

Reviewing files that changed from the base of the PR and between dfcdac5 and 0982e57.

📒 Files selected for processing (2)

• src/adapters/cursor/protobuf-request.ts
• src/adapters/cursor/request-builder.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

Cursor routes now translate supported Responses text.format options into prompt instructions for final output. The adapter includes those options in request construction and checkpoint digests. Tests cover encoded prompts and checkpoint replay behavior.

Changes

Cursor structured output

Layer / File(s)	Summary
Carry formats and build instructions src/adapters/cursor/types.ts, src/adapters/cursor/structured-output.ts	CursorRunRequest carries the optional text format. The instruction builder specifies JSON output requirements for the final response and includes a schema when provided.
Encode prompts and track format changes src/adapters/cursor/protobuf-request.ts, src/adapters/cursor/request-builder.ts, tests/providers/cursor/cursor-request-compat.test.ts, tests/providers/cursor/cursor-request-builder.test.ts, structure/providers/cursor.md, docs-site/src/content/docs/guides/model-routing.md	The protobuf builder adds instructions to system prompts and active actions. The digest includes the text format. Tests cover request encoding and checkpoint invalidation. Documentation describes the prompt fallback and its limits.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant createCursorRequest
  participant protobufRequest as protobuf-request
  participant cursorStructuredOutputInstructions
  createCursorRequest->>protobufRequest: request with textFormat
  protobufRequest->>cursorStructuredOutputInstructions: textFormat
  cursorStructuredOutputInstructions-->>protobufRequest: final-output instructions
  protobufRequest->>protobufRequest: add instructions to system prompts and active action

Loading

Merge Risk: ⚪ Minimal · up to 0982e

Cursor’s format guidance is a best-effort prompt fallback, not strict output validation; the documentation makes that limitation clear. No merge-blocking code issue was established.

Architecture Summary

Architecture risk: 🔵 Low · up to 0982e

The change affects 4 systems.

Changed systems: src, tests, docs-site, structure

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

• observed — src (service) was modified; 4 changed files map to changed impact.
• observed — tests (service) was modified; 2 changed files map to changed impact.
• observed — docs-site (service) was modified; 1 changed file maps to changed impact.
• observed — structure (service) was modified; 1 changed file maps to changed impact.

Before / after behavior

• observed — Modified behavior in docs-site/src/content/docs/guides/model-routing.md: Documents how Cursor routes translate supported Responses formats into prompt instructions, and states the limits of that fallback, caller validation guidance, and which request behavior remains unchanged.
• observed — Modified behavior in src/adapters/cursor/types.ts: Added optional textFormat to CursorRunRequest, using the request-options text-format type.
• observed — Modified behavior in structure/providers/cursor.md: Adds documentation describing Cursor structured-output handling, its prompt-based fallback and limits, where the format is included in protobuf requests, and how format changes affect checkpoint replay. It also names the tests covering request encoding and checkpoint invalidation.
• observed — Modified behavior in tests/providers/cursor/cursor-request-builder.test.ts: Adds checkpoint-continuation coverage for output-format lineage: the matching json_object format reuses the checkpoint, while a changed json_schema format triggers full replay with lineage_mismatch; moving the original format into system-prompt text also triggers full replay. The test clears checkpoint state before and after execution.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 90.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 20 functions across 6 files.
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the primary change: preserving structured final-output contracts for Cursor requests, including json_object and json_schema formats.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[github-actions]

✅ Deterministic PR hygiene checks passed.

[github-actions]

✅ READY

• all PR quality gates passed; the review readiness checklist is complete.

Review readiness checklist

• ✅ Required local validation passed; commands, results, and any full-suite exception are documented.
• ✅ I pushed my PR to a recent dev commit (at most 10 behind; a maintainer may still ask for the exact tip before merge).
• ✅ I resolved all correct Codex and CodeRabbit findings.
• ✅ My PR is ready for review.

✅ 4/4 boxes ticked.

This pull request is already Ready for Review.
The review-ready label marks this PR as ready; review automation runs independently.
Maintainers: @lidge-jun @Ingwannu

Hygiene

✅ Deterministic PR hygiene checks passed.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Ingwannu]

Review checkpoint at 0982e57: read the complete eight-file patch and independently ran bun test tests/providers/cursor/cursor-request-builder.test.ts tests/providers/cursor/cursor-request-compat.test.ts — 64 passed, 0 failed, 201 assertions, exit 0, Bun 1.4.0. The real encoded action/schema continuation, ordinary-text behavior and checkpoint lineage regressions passed under isolated temporary homes, CPUQuota=75%, MemoryHigh=1280M, MemoryMax=1536M, zero swap and TasksMax=64. No provider/account traffic or captured-user-request replay was used. The prompt-only limitation is accurately documented; this does not certify general JSON reliability or native constrained decoding. I authorized the existing read-only hosted CI for this exact head after full diff/workflow/install-surface inspection. This is not PR approval: required current-head CI and typecheck must actually complete successfully. GitHub comparison currently reports 10 behind dev, so any further dev movement may require a refreshed base before readiness/approval.

[arikon]

@Ingwannu Will you merge?

[lidge-jun]

Superseded by the integration in #6487, with reviewed follow-up fixes in #6490 and Windows validation repairs in #6494/#6495, all merged into dev.

Cursor structured-output prompt guidance and checkpoint invalidation were carried. Unrelated helper commentary was omitted; this is guidance, not a new constrained-decoding guarantee.

Original carry commit: ce0e7672c8b5a974b61c4f593c0ee0ce2b437dec. Attribution to @arikon is preserved in the integration history and merge trailers. The final integrated candidate passed the complete cross-platform CI run.

Closing this PR as superseded, not claiming that its original head was merged. Thank you for the contribution.