fix(codex): keep collaboration guidance before conversation

[harryzhou2000]

Summary

• Keep OpenCodex collaboration guidance in the developer prefix for array-form stateless Responses requests, after leading system/developer metadata and before conversation input.
• Preserve stateful continuation precedence: unchanged guidance is deduplicated only from the trusted replay prefix, while changed non-null guidance is compared with the latest tagged replay item so current configuration or roster guidance remains newest.
• Preserve tool-result-first deltas and final compaction_trigger ordering, with focused regression coverage and documentation.

The root cause was tail placement. Stateless HTTP requests have no trusted replay prefix, so OpenCodex generates guidance for each request; appending it after current conversation made stable metadata look like fresh, recency-dominant input.

Current dev separately suppresses OpenCodex guidance when the host-global catalog observation is stale or unknown (#1407). This PR applies when guidance is generated and does not reintroduce the removed catalog warning.

Verification

• Full pre-push test suite under loopback-only network isolation: 10,932 pass, 0 fail, 11 skip
• bun run typecheck
• bun scripts/lint-gui-if-changed.ts
• bun run privacy:scan
• bun run doctor:gui:if-changed (React Doctor: no issues)
• Final-rebase focused suite: bun test tests/multi-agent-compat.test.ts tests/responses-state.test.ts tests/openai-responses-passthrough.test.ts tests/responses-compaction-routing.test.ts (238 pass, 0 fail)
• ASTRO_TELEMETRY_DISABLED=1 bun run build in docs-site
• git diff --check

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:

• All CI tests are green on my local testing.

• I pushed my PR to the latest dev commit.

• I resolved all correct Codex and CodeRabbit findings.

• My PR is ready for review.

Summary by CodeRabbit

• Bug Fixes

  • Improved generated guidance placement in Responses requests while preserving developer metadata and conversation order.
  • Stateful continuations now reuse trusted guidance without duplication.
  • Stateless requests place guidance before conversation content while preserving compaction triggers.
  • Improved handling of replayed tool updates and outdated guidance replacement.

• Documentation

  • Added guidance on generated instruction placement for stateless requests and stateful continuations.

[coderabbitai]

📝 Walkthrough

Walkthrough

The Responses collaboration path now detects replayed guidance, preserves developer prefixes, and places generated guidance before conversation content for stateless requests. Stateful continuations reuse or replace guidance without duplication. Tests and documentation cover these rules.

Changes

Developer guidance injection

Layer / File(s)	Summary
Guidance detection and placement src/server/responses/collaboration.ts, docs-site/src/content/docs/guides/sub-agent-surface.md	Helpers classify generated developer text and leading developer prefixes. Stateful requests append guidance after existing messages. Stateless requests insert guidance after the developer/additional-tools prefix and before conversation content. Trailing compaction_trigger items remain last. Documentation describes these rules.
Placement regression coverage tests/multi-agent-compat.test.ts, tests/responses-state.test.ts	Tests cover prefix preservation, repeated stateless requests, replayed tool deltas, stale guidance replacement, compaction ordering, and continuation input ordering.

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

Possibly related PRs

• lidge-jun/opencodex#350: Both changes update injectDeveloperMessage to prevent duplicate replayed guidance and adjust insertion behavior.
• lidge-jun/opencodex#397: Both changes modify developer guidance placement relative to leading metadata and conversation history.
• lidge-jun/opencodex#1412: Both changes modify stateful Responses replay handling and guidance insertion around replayed prefixes.

Suggested reviewers: lidge-jun, wibias

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: preserving collaboration guidance before conversation input.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

• ✅ All CI tests are green on my local testing.
• ✅ I pushed my PR to the latest dev commit.
• ✅ I resolved all correct Codex and CodeRabbit findings.
• ✅ My PR is ready for review.

✅ 4/4 boxes ticked.

This pull request has been marked Ready for Review.
The review-ready label marks this PR as ready; review automation runs independently. If no CodeRabbit review appears, comment @coderabbitai review to request one.
Maintainers notified: @lidge-jun @Ingwannu @Wibias

[Wibias]

@harryzhou2000 Please finish your pr.

[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-site/src/content/docs/guides/sub-agent-surface.md`:
- Around line 54-56: Update the documentation around the array-form stateless
Responses request ordering to explicitly state that generated guidance is
inserted after leading system and developer metadata, before conversational
input. Keep the existing stateful previous_response_id replay-prefix behavior
unchanged.

🪄 Autofix

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: ASSERTIVE

Plan: Pro Plus

Run ID: 405d5a07-ed5b-4f39-8780-45e28f90df7a

📥 Commits

Reviewing files that changed from the base of the PR and between ba1df18 and 8d5434a.

📒 Files selected for processing (4)

• docs-site/src/content/docs/guides/sub-agent-surface.md
• src/server/responses/collaboration.ts
• tests/multi-agent-compat.test.ts
• tests/responses-state.test.ts

[harryzhou2000]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[coderabbitai]

@github-actions[bot] Pull request #1380 is ready for review. I will review the current changes.

⚠️ Action not completed

No files to review.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.