mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
## Description In the unbranded sandbox run the agent never searched and wrote a 300-line trimmer by hand; nothing in its environment said Headroom exists. An Agent Skill is the one artifact that fires on the job words (cut input tokens, trim tool outputs, fit a context window) with zero fetches. Four unofficial "headroom" skills already exist on skills.sh; there is no official one. Depends on #4529 for the `/docs/fastapi` link in the skill body. ## Type of Change - [x] New feature (non-breaking change that adds functionality) ## Changes Made - `skills/headroom/SKILL.md`: job-language description; body is the no-key `compress()` path, the zero-network check, `model_limit` / `protect_recent`, the TypeScript proxy caveat, the coding-agent path, and a short do-not list (no savings claims, no `CompressionMiddleware` for apps that call a provider, no `[all]` unless asked). - `plugins/headroom-skill/`: the same SKILL.md under `skills/`, `.claude-plugin/plugin.json` and `.github/plugin/plugin.json` (identical), README with install lines for Claude Code, Copilot CLI and `npx skills add`. - Both marketplace manifests: `headroom-skill` entry, inserted after the hooks plugin so `plugins[0]` stays as the existing tests expect. - `scripts/version-sync.py` and `scripts/verify-versions.py`: the two new manifests, so the next release PR passes the version gate. `scripts/tests/test_version_sync.py` fixture and assertion extended; `tests/test_release_workflows.py` gate list extended. - `tests/test_plugin_manifests.py`: the two SKILL.md copies must be byte-identical (the repo has no symlinks, for Windows checkouts), frontmatter has `name: headroom`; the skill plugin's two manifests match each other and the marketplace entry. ## Testing - [x] Unit tests pass: `tests/test_plugin_manifests.py scripts/tests/test_version_sync.py tests/test_release_workflows.py -k "manifest or version or skill or sync"`: 30 passed - [x] `ruff check` / `ruff format --check` on the touched Python - [x] `python scripts/verify-versions.py`: "All versions aligned at 0.42.0" - [x] Manual testing performed ### Test Output ```text pytest tests/test_plugin_manifests.py scripts/tests/test_version_sync.py tests/test_release_workflows.py -k "manifest or version or skill or sync": 30 passed python scripts/verify-versions.py: All versions aligned at 0.42.0 claude plugin validate .: ✔ Validation passed ``` ## Real Behavior Proof - Environment: macOS arm64, Claude Code CLI. - Exact command / steps: `claude plugin validate .` at the repo root of this branch. - Observed result: `✔ Validation passed`. The only warning is pre-existing and about `plugins/headroom-agent-hooks/README.md` lacking a marketplace install line. - Not tested: installing the plugin from the marketplace into a fresh Claude Code or Copilot CLI session and triggering the skill on a real task; skills.sh indexing (happens on their side once this is on `main`). ## Runtime Rollout Safety - Rollout-managed feature(s): none; documentation and metadata only, no runtime code path changes - Minimum rollout channel: n/a - Stable/default behavior changed: no - Kill switch / disable path: n/a (revert the PR) - Unsafe override required: no - Qualification impact: none - Rollback path: revert the commit ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com> Co-authored-by: JD Davis <mxjerrett@gmail.com>
146 lines
6.3 KiB
Python
146 lines
6.3 KiB
Python
from __future__ import annotations
|
|
|
|
import json
|
|
from pathlib import Path
|
|
|
|
import pytest
|
|
|
|
REPO_ROOT = Path(__file__).resolve().parents[1]
|
|
|
|
|
|
def _load_json(relative_path: str) -> object:
|
|
return json.loads((REPO_ROOT / relative_path).read_text(encoding="utf-8"))
|
|
|
|
|
|
# Plugins built on Claude Code's function hooks, which Copilot CLI cannot load.
|
|
CLAUDE_CODE_ONLY = {"headroom-snip"}
|
|
|
|
|
|
def test_marketplace_manifests_match() -> None:
|
|
claude = _load_json(".claude-plugin/marketplace.json")
|
|
assert isinstance(claude, dict)
|
|
shared = {
|
|
**claude,
|
|
"plugins": [p for p in claude["plugins"] if p["name"] not in CLAUDE_CODE_ONLY],
|
|
}
|
|
assert shared == _load_json(".github/plugin/marketplace.json")
|
|
|
|
|
|
def test_claude_code_only_plugins_are_listed_and_versioned() -> None:
|
|
marketplace = _load_json(".claude-plugin/marketplace.json")
|
|
assert isinstance(marketplace, dict)
|
|
for entry in marketplace["plugins"]:
|
|
if entry["name"] not in CLAUDE_CODE_ONLY:
|
|
continue
|
|
plugin_root = (REPO_ROOT / entry["source"]).resolve()
|
|
manifest = _load_json(f"{entry['source']}/.claude-plugin/plugin.json")
|
|
assert isinstance(manifest, dict)
|
|
assert manifest["name"] == entry["name"]
|
|
assert manifest["version"] == entry["version"] == marketplace["metadata"]["version"]
|
|
assert (plugin_root / "hooks" / "hooks.json").is_file()
|
|
|
|
|
|
@pytest.mark.parametrize("plugin", ["headroom-agent-hooks", "headroom-skill"])
|
|
def test_plugin_manifests_share_core_metadata(plugin: str) -> None:
|
|
claude = _load_json(f"plugins/{plugin}/.claude-plugin/plugin.json")
|
|
copilot = _load_json(f"plugins/{plugin}/.github/plugin/plugin.json")
|
|
assert isinstance(claude, dict)
|
|
assert isinstance(copilot, dict)
|
|
for key in ("name", "version", "description", "author", "homepage", "repository", "keywords"):
|
|
assert claude[key] == copilot[key]
|
|
assert "hooks" not in claude
|
|
if plugin == "headroom-agent-hooks":
|
|
assert copilot["hooks"] == "./hooks"
|
|
else:
|
|
assert "hooks" not in copilot
|
|
|
|
|
|
def test_plugin_hooks_timeout_exceeds_cold_start_wait() -> None:
|
|
"""The plugin's `ensure` hooks are killed by the host (Claude Code, etc.)
|
|
at their declared `timeout`, independent of anything inside the process.
|
|
Headroom's own cold-start path can take up to wait_ready's 45s ceiling
|
|
(headroom/cli/init.py), so a shorter external timeout makes the hook
|
|
unwinnable by construction on every session start (#3417)."""
|
|
hooks = _load_json("plugins/headroom-agent-hooks/hooks/hooks.json")
|
|
assert isinstance(hooks, dict)
|
|
for event in ("SessionStart", "PreToolUse"):
|
|
for entry in hooks["hooks"][event]:
|
|
for hook in entry["hooks"]:
|
|
assert hook["timeout"] > 45
|
|
|
|
|
|
def test_marketplace_entry_points_to_plugin_root() -> None:
|
|
marketplace = _load_json(".claude-plugin/marketplace.json")
|
|
assert isinstance(marketplace, dict)
|
|
plugins = marketplace["plugins"]
|
|
assert isinstance(plugins, list)
|
|
plugin = plugins[0]
|
|
assert plugin["name"] == "headroom"
|
|
plugin_root = (REPO_ROOT / plugin["source"]).resolve()
|
|
assert plugin_root.is_dir()
|
|
assert (plugin_root / ".claude-plugin" / "plugin.json").is_file()
|
|
assert (plugin_root / "hooks" / "hooks.json").is_file()
|
|
|
|
|
|
def test_plugin_metadata_points_to_upstream_repo() -> None:
|
|
expected_repo = "https://github.com/headroomlabs-ai/headroom"
|
|
marketplace = _load_json(".claude-plugin/marketplace.json")
|
|
claude = _load_json("plugins/headroom-agent-hooks/.claude-plugin/plugin.json")
|
|
assert isinstance(marketplace, dict)
|
|
assert isinstance(claude, dict)
|
|
plugin = marketplace["plugins"][0]
|
|
assert plugin["author"]["url"] == expected_repo
|
|
assert plugin["homepage"] == expected_repo
|
|
assert plugin["repository"] == expected_repo
|
|
assert claude["author"]["url"] == expected_repo
|
|
assert claude["homepage"] == expected_repo
|
|
assert claude["repository"] == expected_repo
|
|
|
|
|
|
def test_plugin_hooks_share_anchored_launcher_and_rootless_tail() -> None:
|
|
hooks = _load_json("plugins/headroom-agent-hooks/hooks/hooks.json")
|
|
assert isinstance(hooks, dict)
|
|
commands = [
|
|
entry["hooks"][0]["command"] for entries in hooks["hooks"].values() for entry in entries
|
|
]
|
|
expected = (
|
|
'sh -c \'[ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && launcher="${CLAUDE_PLUGIN_ROOT}/bin/headroom-hook.sh" && '
|
|
'[ -r "$launcher" ] && exec sh "$launcher"; '
|
|
"exec headroom init hook ensure'"
|
|
)
|
|
assert commands == [expected, expected]
|
|
powershell = [
|
|
entry["hooks"][0]["powershell"] for entries in hooks["hooks"].values() for entry in entries
|
|
]
|
|
assert powershell == ["headroom init hook ensure", "headroom init hook ensure"]
|
|
assert hooks["hooks"]["SessionStart"][0]["matcher"] == "startup|resume"
|
|
assert hooks["hooks"]["PreToolUse"][0]["matcher"] == "Bash|PowerShell"
|
|
launcher = REPO_ROOT / "plugins/headroom-agent-hooks/bin/headroom-hook.sh"
|
|
assert launcher.is_file()
|
|
assert b"\r" not in launcher.read_bytes()
|
|
|
|
|
|
def test_skill_plugin_ships_the_repo_root_skill() -> None:
|
|
"""The skill is published twice: at `skills/headroom` for skills.sh / Codex /
|
|
Cursor, which read the repo root, and inside the plugin for the Claude Code
|
|
and Copilot marketplaces, which read the plugin root. No symlinks (Windows
|
|
checkouts), so this test is what keeps the two copies identical."""
|
|
root_skill = REPO_ROOT / "skills" / "headroom" / "SKILL.md"
|
|
plugin_skill = REPO_ROOT / "plugins" / "headroom-skill" / "skills" / "headroom" / "SKILL.md"
|
|
assert root_skill.read_bytes() == plugin_skill.read_bytes()
|
|
head = root_skill.read_text(encoding="utf-8").split("---")[1]
|
|
assert "name: headroom\n" in head
|
|
assert "description: " in head
|
|
|
|
|
|
def test_skill_plugin_manifests_match_marketplace() -> None:
|
|
marketplace = _load_json(".claude-plugin/marketplace.json")
|
|
assert isinstance(marketplace, dict)
|
|
entry = next(p for p in marketplace["plugins"] if p["name"] == "headroom-skill")
|
|
claude = _load_json("plugins/headroom-skill/.claude-plugin/plugin.json")
|
|
assert isinstance(claude, dict)
|
|
for key in ("name", "version", "description", "author", "homepage", "repository", "keywords"):
|
|
assert claude[key] == entry[key]
|
|
assert entry["version"] == marketplace["metadata"]["version"]
|
|
assert (REPO_ROOT / entry["source"] / "skills" / "headroom" / "SKILL.md").is_file()
|