[6214] fix(api): Reject wrapped or empty session header edits

[XonkelX]

Summary

PUT /sessions/streams/header accepted wrapped or empty JSON because every header field is optional and Pydantic ignored unknown keys. Those requests reached the service as an empty edit, returned 200, and changed nothing.

This change makes the endpoint-specific SessionStreamHeaderEdit reject unknown top-level keys and require at least one recognized name or description field. Validation now returns 422 before the service runs, while valid top-level updates, partial updates, explicit None, and the existing empty-string clear-title action remain compatible.

Fixes #6214.

Related prior attempt: #6215 was automatically closed before maintainer review. Thanks to @Hashim1999164 for documenting the same validation direction.

Testing

Verified locally

• uv sync --locked
• ruff format --check — 2,098 files already formatted
• ruff check — passed
• pytest oss/tests/pytest/unit/sessions -q — 477 passed, 41 skipped because local Postgres is not configured
• Focused DTO/router tests — 25 passed
• Acceptance test collection — all 11 cases collected successfully
• Confirmed the shared desktop/mobile session API helper sends name and description at the request-body top level

Added or updated tests

• DTO coverage rejects a fieldless edit while preserving explicit name=None compatibility.
• In-process FastAPI coverage verifies {} and {"header": {...}} return 422 before set_header is called.
• Live acceptance coverage verifies both invalid bodies return 422 and leave the stored session name unchanged.
• Existing happy-path coverage continues to verify top-level updates return and persist the new name.

QA follow-up

• Run the updated acceptance test against a live OSS stack; this machine has no AGENTA_API_URL / AGENTA_AUTH_KEY configured.
• Smoke-test rename from the desktop chat rail and /m against that stack.

Demo

Request/response contract after this change:

PUT /api/sessions/streams/header?session_id=demo
{"header":{"name":"Wrapped"}}
→ 422 extra_forbidden (service is not called)

PUT /api/sessions/streams/header?session_id=demo
{}
→ 422 "no header field to update; send name or description at the top level"

PUT /api/sessions/streams/header?session_id=demo
{"name":"Renamed"}
→ 200, stream.name == "Renamed"

The automated in-process API demo for both invalid requests passes in test_stream_header_rejects_noop_bodies_before_calling_service.

Checklist

• I have included a demo for this API behavior
• Relevant tests pass locally
• Relevant linting and formatting pass locally
• I have signed the CLA, or I will sign it when the bot prompts me

[vercel]

@XonkelX is attempting to deploy a commit to the agenta projects Team on Vercel.

A member of the Team first needs to authorize it.

[CLAassistant]

All committers have signed the CLA.

[github-actions]

✅ Thanks @XonkelX! This PR now meets the contribution requirements and has been reopened. A maintainer will review it soon.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 54426e5b-cf5a-484b-a70c-21514ee145a2

📥 Commits

Reviewing files that changed from the base of the PR and between 753af38 and 0a89f47.

📒 Files selected for processing (4)

• api/oss/src/core/sessions/streams/dtos.py
• api/oss/tests/pytest/acceptance/sessions/test_stream_header_basics.py
• api/oss/tests/pytest/unit/sessions/test_session_response_sanitization.py
• api/oss/tests/pytest/unit/sessions/test_stream_header_merge.py

Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.

---

📝 Walkthrough

Summary by CodeRabbit

• Bug Fixes

  • Session stream header updates now reject empty or unrecognized fields with a clear validation error.
  • Updates must provide at least a name or description.
  • Whitespace-only names are no longer accepted.
  • Valid no-op updates and explicit name-clearing behavior remain supported.

• Tests

  • Added coverage confirming invalid requests return HTTP 422 and do not modify persisted stream data.

Walkthrough

The session stream header DTO now rejects unknown fields and empty updates. Acceptance and unit tests verify HTTP 422 responses, unchanged stream names, and skipped service calls for invalid payloads.

Changes

Session stream header validation

Layer / File(s)	Summary
Header edit validation contract api/oss/src/core/sessions/streams/dtos.py	SessionStreamHeaderEdit rejects unknown fields and requires name or description. Whitespace-only names remain invalid.
Invalid update regression coverage api/oss/tests/pytest/acceptance/sessions/test_stream_header_basics.py, api/oss/tests/pytest/unit/sessions/test_session_response_sanitization.py, api/oss/tests/pytest/unit/sessions/test_stream_header_merge.py	Tests verify that empty and nested-only payloads return HTTP 422, preserve the stream name, and do not invoke the service. Explicit name=None remains a no-op.

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

Merge Risk: ⚪ Minimal · up to 0a89f

The change rejects wrapped or empty session-header edits before they reach the service while preserving valid updates and existing clear-title behavior; no actionable merge-blocking risk remains after normal checks and review.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 60.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 10 functions across 4 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the main change: rejecting wrapped or empty session header edits.
Description check	✅ Passed	The description directly explains the validation change, compatibility requirements, tests, and affected endpoint.
Linked Issues check	✅ Passed	The changes reject wrapped and empty bodies, preserve valid top-level updates, and add tests for the required API behavior [#6214].
Out of Scope Changes check	✅ Passed	The DTO changes and added tests directly support the linked issue and its API validation requirements.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 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.}