[mcp, cli] fix: validate custom job ids

[Wangmerlyn]

Summary

• centralize custom job_id validation so only None/omitted means generated or all-sessions
• reject empty, non-string, and non URL-path-safe session IDs before start/status/stop mutates session state
• harden REST collection and targeted session routes against malformed path params/query/fragments
• preserve explicit empty --job-id in CLI service commands so service validation rejects it
• update AGENTS, README, MCP/API/CLI docs, and add a focused plan

Verification

• PYTHONPATH=$PWD/src pytest tests/utilities/test_session_config.py tests/mcp/test_server.py tests/mcp/test_http_api.py tests/test_cli_service_commands.py -q -> 130 passed
• PYTHONPATH=$PWD/src pytest tests -q -> 173 passed, 12 skipped
• PYTHONPATH=$PWD/src mkdocs build -> passed, with existing MkDocs Material warning and un-nav docs notices
• pre-commit run --all-files -> passed
• git diff --check -> passed before commit

Local review

• Local subagent review completed with no Critical, Important, or Minor issues after three review/fix rounds.
• Review-driven regressions added for targeted and collection REST query/path-param cases plus CLI explicit empty --job-id forwarding.

Summary by CodeRabbit

• New Features

  • Session IDs are now validated more consistently across the app and APIs.
  • Explicit empty --job-id values are now passed through correctly in CLI status/stop commands.

• Bug Fixes

  • Invalid session IDs are rejected before any session changes occur.
  • HTTP session routes now return clear 400 errors for malformed paths or invalid IDs.
  • null/omitted IDs are handled consistently as generated IDs or all-sessions actions, depending on the command.

• Documentation

  • Updated API, CLI, MCP, and README guidance to match the new session ID rules.

[coderabbitai]

Warning

Review limit reached

@Wangmerlyn, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 54 minutes and 35 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

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 credits.

🚦 How do rate 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 see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: d4c1bc7a-ff30-429f-9fa1-7e66e52d2bbe

📥 Commits

Reviewing files that changed from the base of the PR and between fc5b5f7 and f0ffb45.

📒 Files selected for processing (13)

• AGENTS.md
• README.md
• docs/guides/mcp.md
• docs/plans/mcp-job-id-validation.md
• docs/reference/api.md
• docs/reference/cli.md
• src/keep_gpu/cli.py
• src/keep_gpu/mcp/server.py
• src/keep_gpu/utilities/session_config.py
• tests/mcp/test_http_api.py
• tests/mcp/test_server.py
• tests/test_cli_service_commands.py
• tests/utilities/test_session_config.py

📝 Walkthrough

Walkthrough

Introduces a centralized validate_job_id helper in session_config.py that enforces a URL-path-safe non-empty string contract. Applies it to start_keep, stop_keep, and status JSON-RPC methods, adds HTTP path validation helpers returning 400 on invalid paths, fixes CLI falsy-check bugs, and updates tests and documentation throughout.

Changes

job_id Validation Centralization

Layer / File(s)	Summary
validate_job_id helper src/keep_gpu/utilities/session_config.py, tests/utilities/test_session_config.py	Adds _JOB_ID_PATTERN regex and validate_job_id(job_id) returning None for None, trimming and pattern-matching strings, raising ValueError on invalid input. Parametrized tests cover valid and invalid inputs.
JSON-RPC method validation src/keep_gpu/mcp/server.py, tests/mcp/test_server.py	Wires validate_job_id into start_keep, stop_keep, and status; switches all-vs-one session branching from truthiness to is None. Three new parametrized tests assert ValueError before any state change.
HTTP path validation helpers and routing src/keep_gpu/mcp/server.py, tests/mcp/test_http_api.py	Adds _job_id_from_session_path and _reject_session_route_components to _JSONRPCHandler, wired into do_GET, do_POST, and do_DELETE; returns 400 for invalid path shapes. Ten new HTTP tests assert rejection without side effects.
CLI is None fix src/keep_gpu/cli.py, tests/test_cli_service_commands.py	Fixes status and stop to use job_id is None instead of truthiness when building RPC params. Two new tests verify empty --job-id "" is forwarded as {"job_id": ""}.
Docs and architecture guidelines AGENTS.md, README.md, docs/guides/mcp.md, docs/plans/mcp-job-id-validation.md, docs/reference/api.md, docs/reference/cli.md	Adds architecture boundary rule in AGENTS.md, extends job_id format rules in README and reference docs, adds MCP guide clarifications, and adds a new validation plan document.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• Wangmerlyn/KeepGPU#59: Modifies the same start_keep/stop_keep/status JSON-RPC server flows that this PR now extends with validate_job_id.
• Wangmerlyn/KeepGPU#77: Also modifies KeepGPUServer.start_keep job_id handling (early reservation for duplicate detection), directly adjacent to the normalization/validation changes here.

Poem

🐇 A job_id walks in, all empty and bare,
The rabbit says "No! You must not go there!"
URL-safe strings, non-empty please,
None means omit—now validate with ease.
With regex and tests the contract is tight,
Every session ID validated just right! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 15.91% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: validating custom job IDs across MCP and CLI paths.
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 unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/mcp-job-id-validation

---

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

[gemini-code-assist]

Code Review

This pull request introduces centralized validation for custom job_id values across the service, ensuring they are URL-path-safe non-empty strings before any session state changes occur. It updates the server, CLI, REST endpoints, and documentation to enforce this contract, backed by a comprehensive suite of new tests. The review feedback highlights two important improvements: first, trimming the job_id in validate_job_id to match the design plan's requirement, and second, replacing a runtime assert statement with an explicit conditional check to prevent validation bypasses when Python is run with optimizations.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.