Skip to content

feat: add detached mode capabilities - #617

Open
JerrettDavis wants to merge 33 commits into
headroomlabs-ai:mainfrom
JerrettDavis:feat/detached-mode-capabilities
Open

feat: add detached mode capabilities#617
JerrettDavis wants to merge 33 commits into
headroomlabs-ai:mainfrom
JerrettDavis:feat/detached-mode-capabilities

Conversation

@JerrettDavis

@JerrettDavis JerrettDavis commented Jun 5, 2026

Copy link
Copy Markdown
Collaborator

Description\n\nAdds detached-mode capability reporting and degradation behavior for stateless, read-only, and containerized Headroom deployments.\n\nCloses #180\n\n## Type of Change\n\n- [ ] Bug fix (non-breaking change that fixes an issue)\n- [x] New feature (non-breaking change that adds functionality)\n- [ ] Breaking change (fix or feature that would cause existing functionality to change)\n- [x] Documentation update\n- [ ] Performance improvement\n- [ ] Code refactoring (no functional changes)\n\n## Changes Made\n\n- Adds HEADROOM_DETACHED_PROFILE and --detached-profile policy support.\n- Adds runtime capability reporting for local-state dependency, feature state, degradation mode, reason, and strict-mode violations.\n- Exposes capabilities through GET /capabilities, /health, /stats, and Prometheus gauges.\n- Tightens stateless startup behavior so file logging is skipped when filesystem writes are disabled.\n- Uses collision-safe temporary probes so capability detection cannot overwrite workspace files.\n- Redacts workspace paths, backend URL credentials, and internal topology from remote capability projections.\n- Registers HEADROOM_DETACHED_PROFILE in the settings store.\n- Documents detached mode in website docs and wiki pages.\n- Merged current headroomlabs-ai/headroom@main; latest head is de0dbad.\n\n## Testing\n\n- [x] Focused detached-mode tests pass locally\n- [x] Linting passes locally\n- [x] GitHub CI is green on the latest head\n- [x] Documentation updated\n- [x] Manual review performed\n\n### Latest Local Validation\n\n ext\nuv run --extra dev python -m pytest tests/test_cli_proxy_env.py tests/test_proxy_capabilities.py -q\n81 passed, 1 skipped\nuv run --extra dev ruff check headroom/proxy/capabilities.py headroom/proxy/helpers.py headroom/proxy/server.py headroom/settings_store.py tests/test_cli_proxy_env.py tests/test_proxy_capabilities.py\ngit diff --check\n\n\n## Current Status\n\nThe branch is current with main; public path/backend disclosures and destructive probe collisions are fixed. GitHub CI is green on latest head de0dbad. No self-approval or merge was performed.\n\n## Real Behavior Proof\n\n- Environment: Local isolated worktree using the repository uv environment, merged with current main.\n- Exact command / steps: Ran targeted Ruff checks plus pytest -q tests/test_proxy_capabilities.py tests/test_cli_proxy_env.py after resolving the documentation conflict.\n- Observed result: Ruff passed; 81 tests passed and 1 skipped. Remote capability and health projections redact the workspace path while loopback operator views retain it.\n- Not tested: Live production deployment probes with production credentials; remote and loopback behavior are covered through TestClient regression tests.\n\n## Runtime Rollout Safety\n\n- Rollout-managed feature(s): detached-mode capability and health projections.\n- Minimum rollout channel: normal release after proxy capability and environment tests are green.\n- Stable/default behavior changed: capability responses gain additive detached-mode metadata with remote redaction preserved.\n- Kill switch / disable path: disable detached operation or human-revert the additive capability changes.\n- Unsafe override required: none.\n- Qualification impact: proxy capability, environment, loopback, and remote-redaction tests must remain green.\n- Rollback path: human revert removes the additive projections; no persistent migration is required.\n\n## Review Readiness\n\n- [x] I have performed a self-review\n- [x] This PR is ready for human review\n- [x] GitHub CI is green on the latest head\n- [x] Blocking review findings are resolved; refreshed CI is green\n\n## Checklist\n\n- [x] My code follows the project's style guidelines\n- [x] I have performed a self-review of my code\n- [x] I have commented hard-to-understand areas where appropriate\n- [x] I have made corresponding documentation changes\n- [x] My changes generate no new local warnings\n- [x] I have added or updated tests for the new behavior\n- [x] Focused unit tests pass locally\n- [x] I have updated CHANGELOG.md if applicable\n\n## Screenshots\n\nN/A\n

@JerrettDavis
JerrettDavis marked this pull request as ready for review June 5, 2026 02:37
@JerrettDavis
JerrettDavis force-pushed the feat/detached-mode-capabilities branch from 307b994 to eb72707 Compare June 5, 2026 02:45
@JerrettDavis
JerrettDavis requested review from DevanshiVyas and chopratejas and removed request for chopratejas June 10, 2026 17:55
@JerrettDavis
JerrettDavis force-pushed the feat/detached-mode-capabilities branch from 9925c67 to ca1cace Compare June 10, 2026 23:43
@github-actions github-actions Bot added status: has conflicts Pull request has merge conflicts with the base branch and removed status: has conflicts Pull request has merge conflicts with the base branch labels Jun 11, 2026
…capabilities

# Conflicts:
#	e2e/wrap/run.py
#	headroom/cli/proxy.py
#	headroom/proxy/server.py
#	tests/test_cli_proxy_env.py
@codecov

codecov Bot commented Jun 12, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 94.70199% with 8 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
headroom/proxy/capabilities.py 94.39% 4 Missing and 2 partials ⚠️
headroom/proxy/server.py 92.30% 1 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

@github-actions

github-actions Bot commented Jun 13, 2026

Copy link
Copy Markdown
Contributor

PR governance

This PR does not yet satisfy the required template fields:

  • Missing required section Description.
  • Missing required section Type of Change.
  • Missing required section Changes Made.
  • Missing required section Testing.
  • Missing required section Real Behavior Proof.
  • Missing required section Runtime Rollout Safety.
  • Missing required section Review Readiness.
  • Check I have performed a self-review before requesting human review.
  • Check This PR is ready for human review or convert the PR back to draft.

Please update the PR body, or move the PR back to draft while it is still in progress.

@github-actions github-actions Bot added status: needs author action Pull request body or readiness checklist still needs author updates status: ready for review Pull request body is complete and the author marked it ready for human review status: ci failing Required or reported CI checks are failing and removed status: needs author action Pull request body or readiness checklist still needs author updates status: ready for review Pull request body is complete and the author marked it ready for human review labels Jun 13, 2026
@JerrettDavis
JerrettDavis requested a review from chopratejas June 13, 2026 15:40
@github-actions github-actions Bot removed the status: ci failing Required or reported CI checks are failing label Jun 16, 2026
@JerrettDavis JerrettDavis added the status: has conflicts Pull request has merge conflicts with the base branch label Jul 9, 2026
@JerrettDavis
JerrettDavis marked this pull request as draft July 11, 2026 04:41
# Conflicts:
#	docs/content/docs/meta.json
#	e2e/wrap/run.py
#	headroom/proxy/helpers.py
#	headroom/proxy/server.py
#	headroom/subscription/tracker.py
@JerrettDavis JerrettDavis added status: ci failing Required or reported CI checks are failing and removed status: has conflicts Pull request has merge conflicts with the base branch labels Jul 14, 2026
@JerrettDavis JerrettDavis added the status: needs author action Pull request body or readiness checklist still needs author updates label Jul 15, 2026
@JerrettDavis JerrettDavis added status: ci failing Required or reported CI checks are failing and removed status: needs author action Pull request body or readiness checklist still needs author updates labels Aug 12, 2026
@JerrettDavis JerrettDavis added status: ready for review Pull request body is complete and the author marked it ready for human review and removed status: ci failing Required or reported CI checks are failing labels Aug 12, 2026
@github-actions github-actions Bot added status: needs author action Pull request body or readiness checklist still needs author updates and removed status: ready for review Pull request body is complete and the author marked it ready for human review labels Aug 12, 2026
@JerrettDavis JerrettDavis added status: ready for review Pull request body is complete and the author marked it ready for human review status: ci failing Required or reported CI checks are failing status: needs author action Pull request body or readiness checklist still needs author updates and removed status: needs author action Pull request body or readiness checklist still needs author updates status: ready for review Pull request body is complete and the author marked it ready for human review labels Aug 12, 2026
@github-actions github-actions Bot removed the status: ci failing Required or reported CI checks are failing label Aug 12, 2026
@JerrettDavis JerrettDavis added status: ready for review Pull request body is complete and the author marked it ready for human review status: ci failing Required or reported CI checks are failing status: needs author action Pull request body or readiness checklist still needs author updates and removed status: needs author action Pull request body or readiness checklist still needs author updates status: ready for review Pull request body is complete and the author marked it ready for human review status: ci failing Required or reported CI checks are failing labels Aug 12, 2026
@JerrettDavis

Copy link
Copy Markdown
Collaborator Author

Maintainer readiness refresh (2026-08-20): confirmed the detached-capabilities branch remains clean, mergeable, and fully green. The capability redaction/degradation behavior and validation narrative remain accurate; the description's exact-head references have been corrected to de0dbad. No merge performed.

@github-actions github-actions Bot added status: needs author action Pull request body or readiness checklist still needs author updates and removed status: ready for review Pull request body is complete and the author marked it ready for human review labels Aug 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

status: needs author action Pull request body or readiness checklist still needs author updates

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants