fix(proxy): astgrep disk verify truncation (#3192)

## Description

`_detect_truncation()` currently relies on client-specific truncation
banners in `tool_result` text. This works for clients that emit a
recognizable line-count banner, but not for clients such as Cursor
(byte-based, direction-reversed truncation) and OpenCode (placeholder +
external file pointer).

Because `headroom proxy` runs alongside the client it wraps, it can
optionally verify the returned content against the actual file on disk.
If the `tool_result` is a strict prefix of the file, we can identify
truncation without depending on client-specific output formatting.

This adds disk verification as an opt-in fallback: the existing
banner-based detection always runs first, and disk verification is only
attempted when no banner is found. All disk-verification failures or
ambiguous cases return `UNKNOWN` rather than guessing.

Following review, the verifier is also constrained to a trusted,
confined workspace root rather than trusting caller-supplied input
directly — see the last four bullets under Changes Made.

**Current scope:** the session-token workspace binding this fallback
requires is wired for `headroom wrap claude` and plugin-loaded `headroom
wrap opencode` only. Cursor remains unsupported/not tested — it has no
header-injection surface today to transmit an authoritative session
token, so disk verification stays `UNKNOWN` for it; extending Cursor
support needs a separate, safe transport design.

Related to #2430
Closes #2421

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [x] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made
- Added optional disk-based Read truncation verification behind
`HEADROOM_VERIFY_TRUNCATION_ON_DISK`.
- Disk verification compares the visible `tool_result` against the file
on disk and distinguishes `COMPLETE`, `TRUNCATED`, and `UNKNOWN`.
- Disk verification only runs when the existing `_detect_truncation()`
banner check finds no truncation marker, avoiding unnecessary file I/O
when the client already provides a signal.
- Added a `current_cwd` contextvar populated from `x-headroom-cwd` so
relative Read paths can be resolved against the client's working
directory.
- Registered `HEADROOM_VERIFY_TRUNCATION_ON_DISK` as a hot-reloadable
runtime setting.
- Gated verification on a new `is_current_request_trusted` contextvar,
set from `is_loopback_host(request.client.host)` — a server-observed
fact, not the caller-supplied header — so `x-headroom-cwd` is never
sufficient authority on its own.
- Confined all path resolution strictly under the canonicalized `cwd`
(`.resolve()` + `relative_to()`), rejecting `..` traversal,
absolute-path escapes, and post-resolution symlink escapes.
- Required the resolved target to be a regular file and under a byte cap
(new `HEADROOM_VERIFY_TRUNCATION_MAX_BYTES` knob, default 5MB), both
checked via `fstat` on the open fd before any read.
- Opened with `O_NONBLOCK` so a non-regular/special file can't park the
read indefinitely; disk I/O already runs off the event loop via the
existing compression thread pool.
- Added unit and integration tests covering successful verification,
missing/unreadable paths, relative paths, content races, feature gating,
banner precedence, and the adversarial cases below.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
$ pytest tests/test_tool_result_interceptors.py -v
51 passed in 2.21s
(includes TestVerifyReadAgainstDisk::* [14 cases, incl. absolute-path escape, `..`
traversal, symlink escape, sibling-prefix boundary, non-regular file, oversized
file, and untrusted-request-touches-no-disk], plus the end-to-end disk-verification
and banner-precedence cases)

$ pytest tests/test_proxy_loopback_gating.py -k trusted
16 passed
(includes test_record_headroom_stack_binds_trusted_true_for_loopback_client and
..._false_for_non_loopback_client — proves a spoofed x-headroom-cwd from a
non-loopback peer does not bind trust)

$ ruff check headroom/proxy/interceptors/astgrep.py headroom/proxy/project_context.py \
    headroom/proxy/server.py headroom/proxy/runtime_env.py \
    tests/test_tool_result_interceptors.py tests/test_proxy_loopback_gating.py
All checks passed!

$ mypy headroom/proxy/interceptors/astgrep.py headroom/proxy/project_context.py \
    headroom/proxy/server.py headroom/proxy/runtime_env.py
Success: no issues found in 4 source files
```

## Real Behavior Proof

- Environment: Mac OS local dev machine, no live proxy/network involved.
Exercised the real interceptor pipeline (`apply_to_messages`) directly
against an actual file on disk, using the same fixture and cwd-binding
path a live proxy request would use.
- Exact command / steps: wrote a 9-function Python fixture to a temp
file, built a client-truncated `tool_result` (first 8 functions, cut
mid-file, **no truncation banner text anywhere**), bound
`x-headroom-cwd` to the temp directory via `set_current_cwd()`, then
called `apply_to_messages()` once with
`HEADROOM_VERIFY_TRUNCATION_ON_DISK` unset and once with it set to `1`.
- Observed result: With disk verification disabled, the existing
ast-grep interceptor produced its normal header without indicating that
the input was truncated. With HEADROOM_VERIFY_TRUNCATION_ON_DISK=1, disk
verification detected that the 50-line tool_result was a strict prefix
of the 59-line file and produced:
 ```text
=== HEADROOM_VERIFY_TRUNCATION_ON_DISK unset (default) ===
[headroom: outlined by ast-grep — 8 definition(s); bodies elided.
Re-read the file with a line range to see a specific body.]

=== HEADROOM_VERIFY_TRUNCATION_ON_DISK=1, x-headroom-cwd bound to the
real directory ===
[headroom: outlined by ast-grep — 8 definition(s) in the visible
portion; input was truncated upstream (showing through line 50 of 59
total). Bodies elided. Re-read remaining lines to see more.]
```

**Trust-gate behavior:** same fixture and disk layout, `HEADROOM_VERIFY_TRUNCATION_ON_DISK=1`, but the request context's trust flag left at its default (`False`, simulating a non-loopback caller) instead of being marked trusted.

```text
=== trusted context (loopback) ===
[headroom: outlined by ast-grep — 8 definition(s) in the visible
portion; input was truncated upstream ...]

=== untrusted context (non-loopback) — same file, same cwd header, same
tool_result ===
[headroom: outlined by ast-grep — 8 definition(s); bodies elided.
Re-read the file with a line range to see a specific body.]
(no disk read attempted — verified via a call-recording wrapper around
os.open asserting zero invocations)
```
Also verified at the HTTP-middleware level with `TestClient(..., client=("100.90.0.5", 12345))`: a request carrying a spoofed `x-headroom-cwd` header from a non-loopback client IP does not bind trust, regardless of header content.

- Not tested: a live `headroom proxy` session with a real coding-agent client; the WebSocket/Codex responses-WS path.

## Runtime Rollout Safety

- Rollout-managed feature(s): None. The feature is gated by `HEADROOM_VERIFY_TRUNCATION_ON_DISK`
- Minimum rollout channel: N/A. `--intercept-tool-results` must already be enabled for the ast-grep interceptor to run.
- Stable/default behavior changed: no
- Kill switch / disable path: Unset `HEADROOM_VERIFY_TRUNCATION_ON_DISK`; the setting is hot-reloadable and does not require a restart.
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert the commit, or unset the env var on a running proxy (takes effect immediately, no restart).

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this)

## Additional Notes

this branch is based on `fix/astgrep-truncation-marker` #2430 not main


<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/3192" target="_blank"><picture><source media="(prefers-color-scheme: dark)" srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4" alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

---------

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
This commit is contained in:
slxng1758
2026-10-08 10:52:09 -05:00
committed by GitHub
co-authored by Claude Sonnet 5 JerrettDavis
parent 2a12e035a3
commit 1fb4cbaea0
26 changed files with 1906 additions and 52 deletions
+37
View File
@@ -709,6 +709,43 @@ jobs:
- name: Run native installer wrapper tests
run: pytest tests/test_install/test_native_installers.py -q
# Runtime coverage for pure-Python proxy logic on Windows, kept separate
# from windows-native-wrapper (above), which is deliberately
# dependency-minimal and gated on native-installer changes only. Installs
# the latest published wheel from PyPI (real precompiled _core.pyd, no
# cargo/maturin build needed) so this branch's local ./headroom source
# tree can shadow it -- same shadowing the Linux `test` job relies on,
# just without needing our own freshly-built wheel, since none of the
# covered test files import headroom._core.
#
# Covers the full disk-verify session-token path, not just the
# interceptor: OpenCode config/launch-env building, the wrap opencode
# CLI command, and workspace-root registration through the real HTTP
# middleware -- so this gate actually exercises the OpenCode path, not
# only its final consumer.
windows-tool-result-interceptors:
needs: changes
if: needs.changes.outputs.code == 'true'
runs-on: windows-latest
timeout-minutes: 20
steps:
- uses: actions/checkout@v7
- uses: actions/setup-python@v6
with:
python-version: ${{ env.PY_VERSION }}
- name: Install headroom-ai[dev] (published wheel; local source shadows it)
run: |
python -m pip install --upgrade pip
pip install torch --index-url https://download.pytorch.org/whl/cpu
pip install "headroom-ai[dev]"
- name: Run disk-verify session-token path tests
shell: bash
run: |
pytest tests/test_tool_result_interceptors.py \
tests/test_providers_opencode_config.py \
tests/test_cli/test_wrap_opencode.py \
tests/test_proxy_workspace_registration_middleware.py -q
macos-native-wrapper:
needs: changes
if: needs.changes.outputs.native == 'true'
+61 -10
View File
@@ -27,6 +27,7 @@ import io
import json
import os
import re
import secrets
import shutil
import signal
import socket
@@ -3362,6 +3363,24 @@ def _apply_project_header_env(env: dict[str, str]) -> None:
)
# Read by proxy's workspace_registry.resolve_registered_cwd() to look up
# this session's registered cwd.
_SESSION_TOKEN_HEADER_NAME = "X-Headroom-Session-Token"
def _apply_session_token_header_env(env: dict[str, str], session_token: str) -> None:
"""Inject X-Headroom-Session-Token into ``ANTHROPIC_CUSTOM_HEADERS``.
Mirrors :func:`_apply_project_header_env`. No "user override wins" case
here -- the token is wrap-generated, not user-supplied.
"""
if not session_token:
return
header_line = f"{_SESSION_TOKEN_HEADER_NAME}: {session_token}"
existing = env.get("ANTHROPIC_CUSTOM_HEADERS")
env["ANTHROPIC_CUSTOM_HEADERS"] = f"{existing}\n{header_line}" if existing else header_line
# Codex's own built-in providers plus Headroom's injected one — never treated
# as a "custom upstream to preserve" by _detect_custom_codex_upstream_base_url.
_CODEX_BUILTIN_PROVIDER_NAMES = frozenset({"openai", "anthropic", "azure", "headroom"})
@@ -5279,11 +5298,19 @@ def _ensure_proxy(
def _client_marker_path(port: int) -> Path:
"""Path to this process's wrap-client marker for ``port``."""
"""Path to this process's wrap-client marker for ``port``.
Mode 0700: markers carry ``cwd``/``session_token`` the proxy treats as
an authoritative binding, so only the invoking OS user may read them.
"""
from headroom import paths as _paths
d = _paths.proxy_clients_dir(port)
d.mkdir(parents=True, exist_ok=True)
try:
os.chmod(d, 0o700)
except OSError:
pass
return d / f"{os.getpid()}.json"
@@ -5297,14 +5324,25 @@ def _proc_identity(pid: int) -> tuple[str, float] | None:
return proc_identity(pid)
def _register_proxy_client(port: int) -> None:
def _register_proxy_client(port: int, *, session_token: str | None = None) -> None:
"""Register this wrap process as a live client of the shared proxy.
Best-effort: a failed write just means our marker is missing, and the
liveness pruning in :func:`_live_proxy_clients` is the real safety net.
Also records ``cwd`` (wrap is the coding-agent CLI's real blocking
parent, so this is authoritative) and, if given, ``session_token`` --
also injected into the wrapped CLI's headers so the proxy can resolve
which registered cwd a request belongs to.
Best-effort: a failed write just means our marker is missing, and
:func:`_live_proxy_clients`'s liveness pruning is the real safety net.
"""
try:
payload: dict[str, Any] = {"pid": os.getpid(), "started_at": time.time()}
payload: dict[str, Any] = {
"pid": os.getpid(),
"started_at": time.time(),
"cwd": os.getcwd(),
}
if session_token:
payload["session_token"] = session_token
ident = _proc_identity(os.getpid())
if ident is not None:
payload["start_src"], payload["start_time"] = ident
@@ -6097,7 +6135,10 @@ def claude(
upstream_for_proxy = foundry_upstream or custom_upstream
_register_proxy_client(port)
# One token for the whole session -- written into the marker below
# and, further down, into the header the wrapped CLI sends.
_session_token = secrets.token_urlsafe(32)
_register_proxy_client(port, session_token=_session_token)
proxy_holder[0], actual_port = _ensure_proxy(
port,
no_proxy,
@@ -6113,7 +6154,7 @@ def claude(
)
if actual_port != port:
_unregister_proxy_client(port)
_register_proxy_client(actual_port)
_register_proxy_client(actual_port, session_token=_session_token)
port_holder[0] = actual_port
_push_runtime_env(actual_port, no_proxy)
@@ -6251,6 +6292,8 @@ def claude(
# Per-project savings attribution: tag every request with the launch
# directory's name via X-Headroom-Project (user override wins).
_apply_project_header_env(env)
# Same token written into the marker above.
_apply_session_token_header_env(env, _session_token)
# Issue #746: keep Claude Code's on-demand tool loading on through the
# proxy so tool schemas are not eagerly materialized into local context.
@@ -8530,7 +8573,11 @@ def opencode(
# Register our proxy client marker BEFORE _ensure_proxy so that another
# wrapper's cleanup sees us as an active client and doesn't terminate a
# shared proxy during the startup gap.
_register_proxy_client(port)
#
# Mirrors claude()'s token minting; only reaches OpenCode when the
# plugin layer is loaded (see build_launch_env).
_session_token = secrets.token_urlsafe(32)
_register_proxy_client(port, session_token=_session_token)
# Resolve port before config injection so the provider block and MCP
# URL both point at the port the proxy will actually be on.
@@ -8563,7 +8610,7 @@ def opencode(
# cleanup tracking stays accurate and update MCP config.
if actual_port != port:
_unregister_proxy_client(port)
_register_proxy_client(actual_port)
_register_proxy_client(actual_port, session_token=_session_token)
if not no_mcp:
from headroom.mcp_registry import OpencodeRegistrar
@@ -8573,7 +8620,11 @@ def opencode(
if subscription_resolution is not None:
_scrub_copilot_subscription_launch_env(launch_environ)
env, env_vars_display = _build_opencode_launch_env(
actual_port, launch_environ, project=_project_name_from_cwd(), include_mcp=not no_mcp
actual_port,
launch_environ,
project=_project_name_from_cwd(),
include_mcp=not no_mcp,
session_token=_session_token,
)
# Inject Headroom provider into OpenCode config so traffic routes through proxy.
+29 -13
View File
@@ -12493,6 +12493,7 @@ var fs = nodeRequire("node:fs");
var BASE_URL_HEADER = "x-headroom-base-url";
var ORIGINAL_PATH_HEADER = "x-headroom-original-path";
var PROJECT_HEADER = "x-headroom-project";
var SESSION_TOKEN_HEADER = "x-headroom-session-token";
var PROXY_ENV = "HEADROOM_OPENCODE_TRANSPORT_PROXY_URL";
var EXCLUDE_HOSTS_ENV = "HEADROOM_OPENCODE_EXCLUDE_HOSTS";
var STATE_KEY = /* @__PURE__ */ Symbol.for("headroom.opencode.transport");
@@ -12684,7 +12685,7 @@ function requestUrl(input) {
}
return new URL(String(input));
}
function mergeFetchHeaders(input, init, upstream, originalPath = void 0, project = void 0) {
function mergeFetchHeaders(input, init, upstream, originalPath = void 0, project = void 0, sessionToken = void 0) {
const headers = new Headers(input instanceof Request ? input.headers : void 0);
if (init?.headers) {
new Headers(init.headers).forEach((value, key) => headers.set(key, value));
@@ -12699,9 +12700,12 @@ function mergeFetchHeaders(input, init, upstream, originalPath = void 0, project
if (project) {
headers.set(PROJECT_HEADER, project);
}
if (sessionToken) {
headers.set(SESSION_TOKEN_HEADER, sessionToken);
}
return headers;
}
function withRoutedFetchInput(input, init, proxy, project, excludeHosts) {
function withRoutedFetchInput(input, init, proxy, project, excludeHosts, sessionToken) {
const upstream = requestUrl(input);
if (!shouldRoute(upstream, proxy, excludeHosts)) {
return [input, init];
@@ -12709,7 +12713,7 @@ function withRoutedFetchInput(input, init, proxy, project, excludeHosts) {
const { url: nextUrl, originalPath } = routedUrlForOpenCode(upstream, proxy);
const nextInit = {
...init,
headers: mergeFetchHeaders(input, init, upstream, originalPath, project)
headers: mergeFetchHeaders(input, init, upstream, originalPath, project, sessionToken)
};
if (input instanceof Request) {
return [new Request(nextUrl, input), nextInit];
@@ -12755,7 +12759,7 @@ function urlFromRequestOptions(options) {
return void 0;
}
}
function headersForNodeRequest(options, upstream, originalPath, project) {
function headersForNodeRequest(options, upstream, originalPath, project, sessionToken) {
const headers = new Headers(options.headers);
headers.set(BASE_URL_HEADER, upstream.origin);
if (originalPath) {
@@ -12764,6 +12768,9 @@ function headersForNodeRequest(options, upstream, originalPath, project) {
if (project) {
headers.set(PROJECT_HEADER, project);
}
if (sessionToken) {
headers.set(SESSION_TOKEN_HEADER, sessionToken);
}
headers.delete("host");
const result = {};
headers.forEach((value, key) => {
@@ -12771,7 +12778,7 @@ function headersForNodeRequest(options, upstream, originalPath, project) {
});
return result;
}
function routedNodeOptions(parts, proxy, project, excludeHosts) {
function routedNodeOptions(parts, proxy, project, excludeHosts, sessionToken) {
if (!parts.url || !shouldRoute(parts.url, proxy, excludeHosts)) {
return void 0;
}
@@ -12802,7 +12809,7 @@ function routedNodeOptions(parts, proxy, project, excludeHosts) {
hostname: nextUrl.hostname,
port: nextUrl.port || void 0,
path: `${nextUrl.pathname}${nextUrl.search}`,
headers: headersForNodeRequest(parts.options, parts.url, originalPath, project)
headers: headersForNodeRequest(parts.options, parts.url, originalPath, project, sessionToken)
};
}
function wrapRequest(originalHttpRequest, originalHttpsRequest, originalRequest) {
@@ -12813,7 +12820,7 @@ function wrapRequest(originalHttpRequest, originalHttpsRequest, originalRequest)
}
const proxy = normalizeProxyUrl(state.proxyUrl);
const parts = splitNodeArgs(args);
const nextOptions = routedNodeOptions(parts, proxy, state.project, state.excludeHosts);
const nextOptions = routedNodeOptions(parts, proxy, state.project, state.excludeHosts, state.sessionToken);
if (!nextOptions) {
return Reflect.apply(originalRequest, this, args);
}
@@ -12843,6 +12850,7 @@ function installHeadroomTransport(options) {
existing.project = options.project;
existing.excludeHosts = excludeHosts;
existing.debug = Boolean(options.debug);
existing.sessionToken = options.sessionToken;
installProcessEnv(options.proxyUrl, excludeHosts);
return () => uninstallHeadroomTransport();
}
@@ -12852,6 +12860,7 @@ function installHeadroomTransport(options) {
project: options.project,
excludeHosts,
debug: Boolean(options.debug),
sessionToken: options.sessionToken,
originalFetch: globalThis.fetch,
originalHttpRequest: http.request,
originalHttpGet: http.get,
@@ -12871,7 +12880,7 @@ function installHeadroomTransport(options) {
return state.originalFetch(...args);
}
const proxy = normalizeProxyUrl(current.proxyUrl);
const [nextInput, nextInit] = withRoutedFetchInput(args[0], args[1], proxy, current.project, current.excludeHosts);
const [nextInput, nextInit] = withRoutedFetchInput(args[0], args[1], proxy, current.project, current.excludeHosts, current.sessionToken);
return state.originalFetch(nextInput, nextInit);
};
http.request = wrapRequest(state.originalHttpRequest, state.originalHttpsRequest, state.originalHttpRequest);
@@ -12919,6 +12928,9 @@ function resolveProxyUrl(options) {
options?.proxyUrl ?? process.env.HEADROOM_PROXY_URL ?? process.env.HEADROOM_BASE_URL ?? getDefaultProxyUrl()
);
}
function resolveSessionToken(options) {
return options?.sessionToken ?? process.env.HEADROOM_OPENCODE_SESSION_TOKEN;
}
function resolveExcludeHosts(options) {
return normalizeExcludeHosts(options?.excludeHosts ?? process.env[EXCLUDE_HOSTS_ENV] ?? "");
}
@@ -12938,7 +12950,7 @@ function openAiWireSuffix(pkg) {
if (pkg.endsWith("-responses") || pkg.endsWith("/responses")) return "/responses";
return void 0;
}
function routeModelsThroughProxy(models, proxyUrl, project, excludeHosts) {
function routeModelsThroughProxy(models, proxyUrl, project, excludeHosts, sessionToken) {
for (const model of models.list()) {
const providerID = String(model.providerID);
const modelID = String(model.id);
@@ -12954,7 +12966,8 @@ function routeModelsThroughProxy(models, proxyUrl, project, excludeHosts) {
...draft.headers,
[BASE_URL_HEADER]: upstream.origin,
[ORIGINAL_PATH_HEADER]: `${trimTrailingSlashes(upstream.pathname)}${suffix}`,
[PROJECT_HEADER]: project
[PROJECT_HEADER]: project,
...sessionToken ? { [SESSION_TOKEN_HEADER]: sessionToken } : {}
};
});
}
@@ -12968,7 +12981,8 @@ var HeadroomPlugin = async (input, options = {}) => {
proxyUrl,
project,
excludeHosts: pluginOptions.excludeHosts,
debug: pluginOptions.debug
debug: pluginOptions.debug,
sessionToken: resolveSessionToken(pluginOptions)
});
return {
dispose: async () => {
@@ -12996,15 +13010,17 @@ var headroomSetup = async (ctx) => {
const project = pluginOptions.project ?? ctx.location.project.id ?? ctx.location.directory;
const retrieveTool = createHeadroomRetrieveTool({ proxyBaseUrl: proxyUrl });
const excludeHosts = resolveExcludeHosts(pluginOptions);
const sessionToken = resolveSessionToken(pluginOptions);
const uninstallTransport = installHeadroomTransport({
proxyUrl,
project,
excludeHosts,
debug: pluginOptions.debug
debug: pluginOptions.debug,
sessionToken
});
try {
await ctx.model.transform((models) => {
routeModelsThroughProxy(models, proxyUrl, project, excludeHosts);
routeModelsThroughProxy(models, proxyUrl, project, excludeHosts, sessionToken);
});
await ctx.tool.transform((editor) => {
editor.add({
@@ -9,6 +9,7 @@ var fs = nodeRequire("node:fs");
var BASE_URL_HEADER = "x-headroom-base-url";
var ORIGINAL_PATH_HEADER = "x-headroom-original-path";
var PROJECT_HEADER = "x-headroom-project";
var SESSION_TOKEN_HEADER = "x-headroom-session-token";
var PROXY_ENV = "HEADROOM_OPENCODE_TRANSPORT_PROXY_URL";
var EXCLUDE_HOSTS_ENV = "HEADROOM_OPENCODE_EXCLUDE_HOSTS";
var STATE_KEY = /* @__PURE__ */ Symbol.for("headroom.opencode.transport");
@@ -193,7 +194,7 @@ function requestUrl(input) {
}
return new URL(String(input));
}
function mergeFetchHeaders(input, init, upstream, originalPath = void 0, project = void 0) {
function mergeFetchHeaders(input, init, upstream, originalPath = void 0, project = void 0, sessionToken = void 0) {
const headers = new Headers(input instanceof Request ? input.headers : void 0);
if (init?.headers) {
new Headers(init.headers).forEach((value, key) => headers.set(key, value));
@@ -208,9 +209,12 @@ function mergeFetchHeaders(input, init, upstream, originalPath = void 0, project
if (project) {
headers.set(PROJECT_HEADER, project);
}
if (sessionToken) {
headers.set(SESSION_TOKEN_HEADER, sessionToken);
}
return headers;
}
function withRoutedFetchInput(input, init, proxy, project, excludeHosts) {
function withRoutedFetchInput(input, init, proxy, project, excludeHosts, sessionToken) {
const upstream = requestUrl(input);
if (!shouldRoute(upstream, proxy, excludeHosts)) {
return [input, init];
@@ -218,7 +222,7 @@ function withRoutedFetchInput(input, init, proxy, project, excludeHosts) {
const { url: nextUrl, originalPath } = routedUrlForOpenCode(upstream, proxy);
const nextInit = {
...init,
headers: mergeFetchHeaders(input, init, upstream, originalPath, project)
headers: mergeFetchHeaders(input, init, upstream, originalPath, project, sessionToken)
};
if (input instanceof Request) {
return [new Request(nextUrl, input), nextInit];
@@ -264,7 +268,7 @@ function urlFromRequestOptions(options) {
return void 0;
}
}
function headersForNodeRequest(options, upstream, originalPath, project) {
function headersForNodeRequest(options, upstream, originalPath, project, sessionToken) {
const headers = new Headers(options.headers);
headers.set(BASE_URL_HEADER, upstream.origin);
if (originalPath) {
@@ -273,6 +277,9 @@ function headersForNodeRequest(options, upstream, originalPath, project) {
if (project) {
headers.set(PROJECT_HEADER, project);
}
if (sessionToken) {
headers.set(SESSION_TOKEN_HEADER, sessionToken);
}
headers.delete("host");
const result = {};
headers.forEach((value, key) => {
@@ -280,7 +287,7 @@ function headersForNodeRequest(options, upstream, originalPath, project) {
});
return result;
}
function routedNodeOptions(parts, proxy, project, excludeHosts) {
function routedNodeOptions(parts, proxy, project, excludeHosts, sessionToken) {
if (!parts.url || !shouldRoute(parts.url, proxy, excludeHosts)) {
return void 0;
}
@@ -311,7 +318,7 @@ function routedNodeOptions(parts, proxy, project, excludeHosts) {
hostname: nextUrl.hostname,
port: nextUrl.port || void 0,
path: `${nextUrl.pathname}${nextUrl.search}`,
headers: headersForNodeRequest(parts.options, parts.url, originalPath, project)
headers: headersForNodeRequest(parts.options, parts.url, originalPath, project, sessionToken)
};
}
function wrapRequest(originalHttpRequest, originalHttpsRequest, originalRequest) {
@@ -322,7 +329,7 @@ function wrapRequest(originalHttpRequest, originalHttpsRequest, originalRequest)
}
const proxy = normalizeProxyUrl(state.proxyUrl);
const parts = splitNodeArgs(args);
const nextOptions = routedNodeOptions(parts, proxy, state.project, state.excludeHosts);
const nextOptions = routedNodeOptions(parts, proxy, state.project, state.excludeHosts, state.sessionToken);
if (!nextOptions) {
return Reflect.apply(originalRequest, this, args);
}
@@ -352,6 +359,7 @@ function installHeadroomTransport(options) {
existing.project = options.project;
existing.excludeHosts = excludeHosts;
existing.debug = Boolean(options.debug);
existing.sessionToken = options.sessionToken;
installProcessEnv(options.proxyUrl, excludeHosts);
return () => uninstallHeadroomTransport();
}
@@ -361,6 +369,7 @@ function installHeadroomTransport(options) {
project: options.project,
excludeHosts,
debug: Boolean(options.debug),
sessionToken: options.sessionToken,
originalFetch: globalThis.fetch,
originalHttpRequest: http.request,
originalHttpGet: http.get,
@@ -380,7 +389,7 @@ function installHeadroomTransport(options) {
return state.originalFetch(...args);
}
const proxy = normalizeProxyUrl(current.proxyUrl);
const [nextInput, nextInit] = withRoutedFetchInput(args[0], args[1], proxy, current.project, current.excludeHosts);
const [nextInput, nextInit] = withRoutedFetchInput(args[0], args[1], proxy, current.project, current.excludeHosts, current.sessionToken);
return state.originalFetch(nextInput, nextInit);
};
http.request = wrapRequest(state.originalHttpRequest, state.originalHttpsRequest, state.originalHttpRequest);
+8
View File
@@ -217,6 +217,7 @@ def build_launch_env(
*,
include_mcp: bool = True,
include_plugin: bool = True,
session_token: str | None = None,
) -> tuple[dict[str, str], list[str]]:
"""Build environment variables for launching OpenCode through Headroom.
@@ -224,6 +225,11 @@ def build_launch_env(
Existing provider/base URL environment variables are preserved. When the
transport plugin is loaded, ``HEADROOM_PROXY_URL`` tells it which proxy to
route to.
``session_token`` reaches the plugin (as
``HEADROOM_OPENCODE_SESSION_TOKEN``) only when it's loaded -- the only
layer able to send a header. Without it, disk-verify stays ``UNKNOWN``,
same as Cursor.
"""
env = dict(environ or os.environ)
@@ -237,6 +243,8 @@ def build_launch_env(
display = ["OPENCODE_CONFIG_CONTENT={provider: headroom}"]
if "plugin" in config_content:
env["HEADROOM_PROXY_URL"] = f"http://127.0.0.1:{port}"
if session_token:
env["HEADROOM_OPENCODE_SESSION_TOKEN"] = session_token
display.append(f"plugin={HEADROOM_OPENCODE_PLUGIN}")
if project and "HEADROOM_PROJECT" not in env:
+255 -7
View File
@@ -10,18 +10,23 @@ than three definitions to outline.
from __future__ import annotations
import asyncio
import json
import logging
import os
import re
import shutil
import stat
import subprocess
import tempfile
from enum import Enum
from pathlib import Path
from typing import Any
from headroom import binaries
from headroom._subprocess import run
from headroom.proxy import runtime_env
from headroom.proxy.project_context import get_registered_cwd
from . import base
@@ -88,6 +93,220 @@ _PATTERNS: dict[str, list[str]] = {
OUTLINE_MARKER = " # ... (body elided by Headroom; Read a specific line range to see it)\n"
# Per-client banner signatures -- add an entry only once a client's exact
# banner text is confirmed, never a generic keyword match.
_TRUNCATION_SIGNATURES: tuple[re.Pattern[str], ...] = (
# Claude Code: "[Truncated: PARTIAL view -- <path>: showing lines A-B of
# T total (...). Call Read with offset=N to see more.]"
re.compile(
r"\[\s*truncated\s*:\s*partial\s+view\b"
r"[^\[\]]*?"
r"showing\s+lines?\s+(?P<start_line>\d+)\s*[-–]\s*(?P<end_line>\d+)"
r"\s+of\s+(?P<total_lines>\d+)\s+total"
r"[^\[\]]*\]",
re.IGNORECASE,
),
)
def _is_plausible_truncation_range(
start_line: int, end_line: int, total_lines: int, source_line_count: int
) -> bool:
# end_line == total_lines means the whole file was shown, not truncated.
if start_line < 1 or end_line < start_line or end_line >= total_lines:
return False
return end_line <= source_line_count
def _detect_truncation(source: str) -> tuple[int, int] | None:
"""Return (end_line, total_lines) if `source` carries a recognized,
internally-consistent upstream truncation banner, else None."""
source_line_count = len(source.splitlines())
for pattern in _TRUNCATION_SIGNATURES:
for m in pattern.finditer(source):
start_line = int(m.group("start_line"))
end_line = int(m.group("end_line"))
total_lines = int(m.group("total_lines"))
if _is_plausible_truncation_range(start_line, end_line, total_lines, source_line_count):
return end_line, total_lines
return None
class ReadVerificationResult(Enum):
"""Client-independent fallback for `_detect_truncation`'s banner regex:
compares tool_output against the real file on disk instead of parsing
client-specific prose. Only used when the banner regex finds nothing.
Always UNKNOWN on Windows (no O_NOFOLLOW/dir_fd) -- never falls back to
a less-safe read."""
COMPLETE = "complete"
TRUNCATED = "truncated"
# Unresolvable path, unreadable file, or mismatched content — never guess.
UNKNOWN = "unknown"
def _verify_truncation_on_disk_enabled() -> bool:
# Live read (not a module constant), matching _min_chars_to_rewrite()'s
# hot-reload behavior.
return runtime_env.getenv("HEADROOM_VERIFY_TRUNCATION_ON_DISK", "").lower() in (
"1",
"true",
"yes",
)
def _max_disk_verify_bytes() -> int:
# Live read, same hot-reload pattern as _min_chars_to_rewrite(). 5 MB
# comfortably covers real source files while bounding worst-case read
# time/memory for the disk-verify fallback.
try:
return int(runtime_env.getenv("HEADROOM_VERIFY_TRUNCATION_MAX_BYTES", "5000000"))
except (TypeError, ValueError):
return 5_000_000
def _dir_fd_walk_supported() -> bool:
# hasattr, not bare os.O_NOFOLLOW/os.O_DIRECTORY refs -- missing on
# Windows, would AttributeError at import time otherwise.
return (
hasattr(os, "O_NOFOLLOW") and hasattr(os, "O_DIRECTORY") and os.open in os.supports_dir_fd
)
def _on_event_loop_thread() -> bool:
"""True only on a thread with a running asyncio loop (the request
coroutine) -- false on a plain ThreadPoolExecutor worker. Lets the
blocking read refuse itself if ever reached directly from the loop."""
try:
asyncio.get_running_loop()
except RuntimeError:
return False
return True
def _open_regular_file_under_root(
file_path: str, resolved_root: Path, max_bytes: int
) -> str | None:
"""Race-safe read of `file_path` confined under `resolved_root`.
Walks from an fd opened on `resolved_root` using dir_fd-relative,
O_NOFOLLOW opens at every hop -- no full path is ever resolved then
reopened, so there's no TOCTOU window for a symlink swap to exploit.
Refuses if called on the event-loop thread or if this platform lacks
dir_fd support (notably Windows) -- no less-safe fallback either way.
"""
if _on_event_loop_thread() or not _dir_fd_walk_supported():
return None
# Pure string math -- no I/O, can't itself be raced.
candidate = (
file_path if os.path.isabs(file_path) else os.path.join(str(resolved_root), file_path)
)
rel = os.path.relpath(os.path.normpath(candidate), str(resolved_root))
if rel == os.curdir:
return None # the root itself, not a file within it
if rel == os.pardir or rel.startswith(os.pardir + os.sep) or os.path.isabs(rel):
return None # escapes resolved_root
segments = [s for s in rel.split(os.sep) if s]
if not segments or any(s in (os.curdir, os.pardir) for s in segments):
return None
try:
# resolved_root already went through resolve(strict=True) in the
# caller, so it's symlink-free at that instant -- O_NOFOLLOW here
# closes the residual window where the anchor itself gets swapped
# for a symlink between that resolve() and this open().
current_fd = os.open(str(resolved_root), os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
except OSError:
return None
file_fd = -1
try:
for segment in segments[:-1]:
try:
next_fd = os.open(
segment, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=current_fd
)
except OSError:
return None
os.close(current_fd)
current_fd = next_fd
final = segments[-1]
try:
# O_NONBLOCK: a FIFO with no writer returns immediately instead
# of blocking -- no effect once fstat confirms a regular file.
file_fd = os.open(
final,
os.O_RDONLY | os.O_NONBLOCK | os.O_NOFOLLOW,
dir_fd=current_fd,
)
except OSError:
return None
try:
st = os.fstat(file_fd)
if not stat.S_ISREG(st.st_mode) or st.st_size > max_bytes:
return None
with os.fdopen(file_fd, "rb") as f:
file_fd = -1 # ownership transferred to the file object
data = f.read(max_bytes + 1)
# fstat can go stale by read time -- a regular file can grow
# between the two. Bound the read itself rather than trust the
# earlier size check; one byte past the cap is enough to detect
# an overflow without ever reading an unbounded amount.
if len(data) > max_bytes:
return None
return data.decode("utf-8")
except (OSError, UnicodeDecodeError):
return None
finally:
if file_fd >= 0:
os.close(file_fd)
if current_fd >= 0:
os.close(current_fd)
def _verify_read_against_disk(
file_path: str | None,
received_content: str,
registered_cwd: str | None,
) -> tuple[ReadVerificationResult, tuple[int, int] | None]:
"""Compare `received_content` against the real file at `file_path`.
`registered_cwd` is `project_context.get_registered_cwd()`, not a raw
header -- non-None only when a session token matched a workspace root
`wrap` itself registered (see workspace_registry.py). Its presence is
the trust signal; there's no separate boolean to check.
TRUNCATED requires an exact-prefix match with strictly more on disk —
a weaker match means the file diverged since the client read it, not
a provable truncation, so it's UNKNOWN. Returns `(visible_lines,
total_lines)` alongside TRUNCATED so the header can cite real numbers
without a second, potentially racy, read.
"""
if not file_path:
return ReadVerificationResult.UNKNOWN, None
if not registered_cwd or not os.path.isabs(registered_cwd):
return ReadVerificationResult.UNKNOWN, None
try:
resolved_root = Path(registered_cwd).resolve(strict=True)
except OSError:
return ReadVerificationResult.UNKNOWN, None
if not resolved_root.is_dir():
return ReadVerificationResult.UNKNOWN, None
disk_content = _open_regular_file_under_root(file_path, resolved_root, _max_disk_verify_bytes())
if disk_content is None:
return ReadVerificationResult.UNKNOWN, None
if disk_content == received_content:
return ReadVerificationResult.COMPLETE, None
if disk_content.startswith(received_content) and len(disk_content) > len(received_content):
visible_lines = len(received_content.splitlines())
total_lines = len(disk_content.splitlines())
return ReadVerificationResult.TRUNCATED, (visible_lines, total_lines)
return ReadVerificationResult.UNKNOWN, None
class AstGrepReadOutline:
"""Interceptor that outlines verbose code-file Read outputs."""
@@ -131,7 +350,17 @@ class AstGrepReadOutline:
if not matches:
return None
outline = _build_outline(matches, tool_output)
# Banner (cheap, no I/O) wins; disk verification is the opt-in fallback.
truncation = _detect_truncation(tool_output)
if truncation is None and _verify_truncation_on_disk_enabled():
verdict, disk_truncation = _verify_read_against_disk(
_path_from_input(tool_input),
tool_output,
get_registered_cwd(),
)
if verdict is ReadVerificationResult.TRUNCATED:
truncation = disk_truncation
outline = _build_outline(matches, tool_output, truncation)
return outline if outline else None
def progressive_disclosure_key(
@@ -258,12 +487,21 @@ def _run_ast_grep(
return all_matches
def _build_outline(matches: list[dict[str, Any]], source: str) -> str | None:
def _build_outline(
matches: list[dict[str, Any]],
source: str,
truncation: tuple[int, int] | None = None,
) -> str | None:
"""Build a compact outline from ast-grep matches.
Emits each definition's signature line + docstring (if next line is a
string literal) + an elision marker. Matches are sorted by byte offset
so the outline tracks the original file order.
`truncation`, if given, is (end_line, total_lines) from an upstream
truncation banner already present in `source` (e.g. a client's own Read
token-cap notice). When set, the header states that the input was a
partial view instead of implying `source` is the whole file.
"""
lines = source.splitlines(keepends=True)
outline_chunks: list[str] = []
@@ -292,11 +530,21 @@ def _build_outline(matches: list[dict[str, Any]], source: str) -> str | None:
if not outline_chunks:
return None
header = (
"[headroom: outlined by ast-grep — "
f"{len(seen_starts)} definition(s); "
"bodies elided. Re-read the file with a line range to see a specific body.]\n"
)
if truncation:
end_line, total_lines = truncation
header = (
"[headroom: outlined by ast-grep — "
f"{len(seen_starts)} definition(s) in the visible portion; "
f"input was truncated upstream (showing through line {end_line} of {total_lines} total). "
"Bodies elided. Re-read remaining lines to see more.]\n"
)
else:
header = (
"[headroom: outlined by ast-grep — "
f"{len(seen_starts)} definition(s); "
"bodies elided. Re-read the file with a line range to see a specific body.]\n"
)
return header + "".join(outline_chunks)
+24
View File
@@ -11,6 +11,13 @@ savings to a project without threading a parameter through every handler.
The value is sanitized (printable characters only, length-capped) before it
is stored; an absent or unusable header simply leaves attribution off for
that request, matching pre-feature behavior.
A second contextvar, ``_current_registered_cwd``, is what disk verification
trusts as a workspace root. It is never a raw header value — it's the
result of ``workspace_registry.resolve_registered_cwd()``, which matches a
session token against a workspace root ``headroom wrap`` itself registered
over a trusted local channel (a 0700 marker file). A request can only
*reference* a pre-established root this way, never assert an arbitrary one.
"""
from __future__ import annotations
@@ -31,6 +38,11 @@ from headroom.proxy.savings_tracker import sanitize_project_name
_current_project: ContextVar[str | None] = ContextVar("headroom_current_project", default=None)
# Server-verified, not header-derived -- see module docstring.
_current_registered_cwd: ContextVar[str | None] = ContextVar(
"headroom_current_registered_cwd", default=None
)
def set_current_project(project: str | None) -> None:
"""Bind the active request's project for downstream outcome recording."""
@@ -42,6 +54,16 @@ def get_current_project() -> str | None:
return _current_project.get()
def set_registered_cwd(cwd: str | None) -> None:
"""Bind the server-verified workspace root resolved for this request."""
_current_registered_cwd.set(cwd)
def get_registered_cwd() -> str | None:
"""Server-verified workspace root for the current request, or ``None``."""
return _current_registered_cwd.get()
def strip_project_path_prefix(scope: MutableMapping[str, Any]) -> str | None:
"""Strip a ``/p/<name>`` prefix from an ASGI scope, returning the name.
@@ -59,7 +81,9 @@ __all__ = [
"PROJECT_PATH_PREFIX",
"classify_project",
"get_current_project",
"get_registered_cwd",
"set_current_project",
"set_registered_cwd",
"split_project_path",
"strip_project_path_prefix",
"with_project_prefix",
+11
View File
@@ -73,6 +73,17 @@ RUNTIME_ENV_KNOBS: tuple[Knob, ...] = (
"int",
"Min tool-output chars before the ast-grep read rewrite.",
),
Knob(
"HEADROOM_VERIFY_TRUNCATION_ON_DISK",
"bool",
"Verify ast-grep Read truncation against disk when no client banner is found. "
"Always UNKNOWN on Windows (no dir_fd/O_NOFOLLOW support).",
),
Knob(
"HEADROOM_VERIFY_TRUNCATION_MAX_BYTES",
"int",
"Max on-disk file size (bytes) the disk-verify fallback will read.",
),
)
_KNOBS_BY_ENV: dict[str, Knob] = {k.env: k for k in RUNTIME_ENV_KNOBS}
+17 -2
View File
@@ -183,6 +183,7 @@ from headroom.proxy.probe_recorder import probe_recorder_from_env
from headroom.proxy.project_context import (
classify_project,
set_current_project,
set_registered_cwd,
strip_project_path_prefix,
)
from headroom.proxy.prometheus_metrics import PrometheusMetrics # noqa: F401
@@ -200,6 +201,7 @@ from headroom.proxy.tcp_keepalive import install_tcp_keepalive
from headroom.proxy.tool_schema_savings_policy import tool_schema_saved_from_tags
from headroom.proxy.upstream_pinning import install_upstream_pinning
from headroom.proxy.warmup import WarmupRegistry
from headroom.proxy.workspace_registry import resolve_registered_cwd
from headroom.proxy.ws_session_registry import WebSocketSessionRegistry
from headroom.subscription.base import get_quota_registry, reset_quota_registry
from headroom.subscription.codex_rate_limits import get_codex_rate_limit_state
@@ -1791,7 +1793,12 @@ class HeadroomProxy(
remaining,
)
future = loop.run_in_executor(self._compression_executor, _wrapped)
# run_in_executor doesn't copy contextvars into the worker thread
# (unlike asyncio.to_thread) -- without this, get_registered_cwd()
# etc. would silently see the ContextVar default, not what the
# request middleware bound.
ctx = contextvars.copy_context()
future = loop.run_in_executor(self._compression_executor, ctx.run, _wrapped)
try:
return await asyncio.wait_for(future, timeout=timeout)
except asyncio.TimeoutError:
@@ -1816,7 +1823,9 @@ class HeadroomProxy(
Runs on the dedicated single-thread background executor.
"""
loop = asyncio.get_running_loop()
return await loop.run_in_executor(self._background_compression_executor, fn)
# Same context-propagation fix as _run_compression_in_executor above.
ctx = contextvars.copy_context()
return await loop.run_in_executor(self._background_compression_executor, ctx.run, fn)
# How often the lazy TTL sweep in `_get_compression_cache` may run.
_COMPRESSION_CACHE_CLEANUP_INTERVAL_SECONDS = 60.0
@@ -3985,6 +3994,12 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
query = request.url.query
headers = dict(request.headers.items())
set_current_project(classify_project(headers) or prefix_project)
# Non-None only if a live wrap session registered this exact token
# (workspace_registry.py) -- the caller-supplied x-headroom-cwd
# header is never itself sufficient authority.
set_registered_cwd(
resolve_registered_cwd(config.port, headers.get("x-headroom-session-token"))
)
# Path-based Codex identification: stamp X-Client: codex on the
# Responses endpoint for callers that don't otherwise classify (e.g.
# Codex Desktop, whose User-Agent isn't a known codex UA). Without it
+61
View File
@@ -0,0 +1,61 @@
"""Server-side lookup of a wrap session's real workspace root.
``headroom wrap`` is the true, blocking parent of the coding-agent CLI it
launches, so its own ``os.getcwd()`` at launch time is authoritative for
that session. It records ``(session_token, cwd)`` into the same per-PID
marker file it already writes for proxy-client liveness tracking
(``paths.proxy_clients_dir(port)``), hardened to mode ``0700`` -- only the
invoking OS user can read or write there.
That's what makes ``session_token`` meaningfully different from the
``x-headroom-cwd`` header (PR #3192's review rejected trusting it directly):
the header's value was fully caller-chosen, so any loopback/SSRF-capable
caller could assert an arbitrary directory. A token only lets a caller
*reference* a root ``wrap`` already established over a channel an
HTTP-only attacker can't write to.
"""
from __future__ import annotations
import hmac
import json
from headroom import fsutil, paths
from headroom.proxy_client_liveness import marker_pid_reused, pid_alive
def resolve_registered_cwd(port: int, session_token: str | None) -> str | None:
"""Return the real cwd registered for `session_token` on `port`, or `None`.
`None` if the token is missing/blank, no marker matches it, or the
matching marker's process is no longer live -- never a guess. Read-only:
doesn't prune stale markers itself, that's wrap.py's job.
"""
if not session_token:
return None
token_bytes = session_token.encode("utf-8", "replace")
d = paths.proxy_clients_dir(port)
if not d.exists():
return None
for marker in d.glob("*.json"):
try:
pid = int(marker.stem)
except ValueError:
continue
try:
payload = json.loads(fsutil.read_text(marker))
except (OSError, ValueError):
continue
if not isinstance(payload, dict):
continue
candidate = payload.get("session_token")
if not isinstance(candidate, str):
continue
# Constant-time compare, same precedent as HEADROOM_PROXY_TOKEN.
if not hmac.compare_digest(candidate.encode("utf-8", "replace"), token_bytes):
continue
if not pid_alive(pid) or marker_pid_reused(marker, pid):
return None # matched but stale -- never guess
cwd = payload.get("cwd")
return cwd if isinstance(cwd, str) and cwd else None
return None
+77
View File
@@ -0,0 +1,77 @@
"""Shared PID-liveness/identity primitives for wrap-client marker files.
Both wrap.py (tearing down a shared proxy) and the proxy itself (resolving
a registered workspace root) need to answer "is the process that wrote this
marker still alive?" -- kept here once, importable from both, instead of
duplicated. No CLI dependencies, so the proxy can import it directly.
"""
from __future__ import annotations
from pathlib import Path
from typing import Any
from headroom import fsutil
from headroom._subprocess import pid_alive
__all__ = ["identity_mismatch", "marker_pid_reused", "pid_alive", "proc_identity"]
def proc_identity(pid: int) -> tuple[str, float] | None:
"""Best-effort ``(source, start_time)`` identity for a PID.
Used to defeat PID reuse: a marker is only trusted while the live PID is
*the same process* that wrote it. Returns ``None`` when start time can't be
determined (e.g. macOS without psutil), in which case callers fall back to
existence-only liveness -- no regression, just no reuse protection there.
The ``source`` tag ("psutil" vs "proc") guards against comparing values in
different units; we only compare like-for-like.
"""
try:
import psutil # type: ignore[import-untyped] # optional dependency; portable when present
return ("psutil", psutil.Process(pid).create_time())
except Exception:
pass
# Linux fallback: field 22 of /proc/<pid>/stat is starttime in clock ticks
# since boot -- a stable per-process value. `comm` (field 2) may contain
# spaces/parens, so split after the final ')'.
try:
with open(f"/proc/{pid}/stat", "rb") as fh:
fields = fh.read().rpartition(b")")[2].split()
return ("proc", float(fields[19]))
except (OSError, IndexError, ValueError):
return None
def identity_mismatch(src: Any, recorded: Any, pid: int) -> bool:
"""True only if ``pid``'s current identity *provably* differs from the
recorded ``(src, recorded)`` identity (i.e. the PID was recycled).
Conservative by design: any uncertainty (unknown/legacy identity, unknown
start time, mismatched source) returns ``False`` -- never claim a mismatch
without proof, since callers use this to decide whether to trust or
discard state tied to a live PID.
"""
if not isinstance(src, str) or not isinstance(recorded, int | float):
return False # legacy / identity-less record -- can't tell
ident = proc_identity(pid)
if ident is None or ident[0] != src:
return False # can't compare like-for-like -- don't claim mismatch
# Start times are stable per process; >1s apart means a different process.
return abs(ident[1] - float(recorded)) > 1.0
def marker_pid_reused(marker: Path, pid: int) -> bool:
"""True only if the live ``pid`` is *provably* a different process than the
one that wrote ``marker`` (i.e. the PID was recycled after a crash)."""
import json
try:
rec = json.loads(fsutil.read_text(marker))
except (OSError, ValueError):
return False
if not isinstance(rec, dict):
return False
return identity_mismatch(rec.get("start_src"), rec.get("start_time"), pid)
+22
View File
@@ -489,3 +489,25 @@ describe("default export", () => {
});
});
});
describe("OpenCode 2.x workspace session identity", () => {
it.each([undefined, "explicit-session"])("carries the resolved session token through both routes (%s)", async (sessionToken) => {
vi.stubEnv("HEADROOM_OPENCODE_SESSION_TOKEN", "environment-session");
const models: FakeModel[] = [{
id: "custom", providerID: "gateway",
package: "@opencode/ai/providers/openai-compatible",
settings: { baseURL: "https://gateway.example/v1" },
}];
const { context } = pluginContextV2({ sessionToken }, { models });
const cleanup = await headroomSetup(context);
try {
const expected = sessionToken ?? "environment-session";
expect(models[0].headers?.["x-headroom-session-token"]).toBe(expected);
expect((globalThis as Record<symbol, { sessionToken?: string }>)[TRANSPORT_STATE]?.sessionToken).toBe(expected);
} finally {
await cleanup?.();
vi.unstubAllEnvs();
}
});
});
+15 -1
View File
@@ -13,6 +13,7 @@ import {
EXCLUDE_HOSTS_ENV,
ORIGINAL_PATH_HEADER,
PROJECT_HEADER,
SESSION_TOKEN_HEADER,
installHeadroomTransport,
modelBaseRoutesThroughProxy,
normalizeExcludeHosts,
@@ -24,6 +25,7 @@ export interface HeadroomOpenCodePluginOptions {
excludeHosts?: string[];
backend?: string;
debug?: boolean;
sessionToken?: string;
}
export const HEADROOM_PLUGIN_ID = "headroom";
@@ -41,6 +43,13 @@ function resolveProxyUrl(options?: HeadroomOpenCodePluginOptions): string {
);
}
// Read by workspace_registry.resolve_registered_cwd() on the proxy side --
// mirrors wrap.py's _apply_session_token_header_env for claude.
function resolveSessionToken(options?: HeadroomOpenCodePluginOptions): string | undefined {
return options?.sessionToken ?? process.env.HEADROOM_OPENCODE_SESSION_TOKEN;
}
// The exclusion list governs both the transport patch and the 2.x model
// rewrite, so resolve it once: option over environment variable, normalized
// the same way the transport does.
@@ -86,6 +95,7 @@ function routeModelsThroughProxy(
proxyUrl: string,
project: string,
excludeHosts: string[],
sessionToken?: string,
): void {
for (const model of models.list()) {
// DeepMutable turns the branded ID strings into object types.
@@ -104,6 +114,7 @@ function routeModelsThroughProxy(
[BASE_URL_HEADER]: upstream.origin,
[ORIGINAL_PATH_HEADER]: `${trimTrailingSlashes(upstream.pathname)}${suffix}`,
[PROJECT_HEADER]: project,
...(sessionToken ? { [SESSION_TOKEN_HEADER]: sessionToken } : {}),
};
});
}
@@ -123,6 +134,7 @@ export const HeadroomPlugin: Plugin = async (input, options = {}) => {
project,
excludeHosts: pluginOptions.excludeHosts,
debug: pluginOptions.debug,
sessionToken: resolveSessionToken(pluginOptions),
});
return {
@@ -158,16 +170,18 @@ export const headroomSetup: PluginV2.Plugin["setup"] = async (ctx) => {
pluginOptions.project ?? ctx.location.project.id ?? ctx.location.directory;
const retrieveTool = createHeadroomRetrieveTool({ proxyBaseUrl: proxyUrl });
const excludeHosts = resolveExcludeHosts(pluginOptions);
const sessionToken = resolveSessionToken(pluginOptions);
const uninstallTransport = installHeadroomTransport({
proxyUrl,
project,
excludeHosts,
debug: pluginOptions.debug,
sessionToken,
});
try {
await ctx.model.transform((models) => {
routeModelsThroughProxy(models, proxyUrl, project, excludeHosts);
routeModelsThroughProxy(models, proxyUrl, project, excludeHosts, sessionToken);
});
await ctx.tool.transform((editor) => {
editor.add({
+110
View File
@@ -930,4 +930,114 @@ describe("Headroom OpenCode transport", () => {
expect(http.request).toBe(originalHttpRequest);
expect(https.request).toBe(originalHttpsRequest);
});
it("sends x-headroom-session-token header on routed fetch calls when sessionToken is set", async () => {
const originalFetch = globalThis.fetch;
const fetchMock = vi.fn(async (..._args: FetchCall) => new Response("ok"));
globalThis.fetch = fetchMock as unknown as typeof fetch;
installHeadroomTransport({ proxyUrl: "http://127.0.0.1:8787/v1", sessionToken: "tok-abc" });
await fetch("https://api.anthropic.com/v1/messages", { method: "POST" });
const headers = new Headers(fetchMock.mock.calls[0][1]?.headers);
expect(headers.get("x-headroom-session-token")).toBe("tok-abc");
globalThis.fetch = originalFetch;
});
it("omits x-headroom-session-token header when sessionToken is not set", async () => {
const originalFetch = globalThis.fetch;
const fetchMock = vi.fn(async (..._args: FetchCall) => new Response("ok"));
globalThis.fetch = fetchMock as unknown as typeof fetch;
installHeadroomTransport({ proxyUrl: "http://127.0.0.1:8787/v1" });
await fetch("https://api.anthropic.com/v1/messages", { method: "POST" });
const headers = new Headers(fetchMock.mock.calls[0][1]?.headers);
expect(headers.get("x-headroom-session-token")).toBeNull();
globalThis.fetch = originalFetch;
});
it("omits x-headroom-session-token header when sessionToken is an empty string", async () => {
const originalFetch = globalThis.fetch;
const fetchMock = vi.fn(async (..._args: FetchCall) => new Response("ok"));
globalThis.fetch = fetchMock as unknown as typeof fetch;
installHeadroomTransport({ proxyUrl: "http://127.0.0.1:8787/v1", sessionToken: "" });
await fetch("https://api.anthropic.com/v1/messages", { method: "POST" });
const headers = new Headers(fetchMock.mock.calls[0][1]?.headers);
expect(headers.get("x-headroom-session-token")).toBeNull();
globalThis.fetch = originalFetch;
});
it("sends x-headroom-session-token header on routed Node https.request calls when sessionToken is set", async () => {
const proxy = await proxyServer();
installHeadroomTransport({ proxyUrl: proxy.url, sessionToken: "tok-abc" });
await new Promise<void>((resolve, reject) => {
const req = https.request(
"https://api.anthropic.com/v1/messages",
{ method: "POST" },
(res) => {
res.resume();
res.on("end", resolve);
},
);
req.on("error", reject);
req.end("{}");
});
expect(proxy.seen[0].headers["x-headroom-session-token"]).toBe("tok-abc");
await proxy.close();
});
it("updates the session token on reinstall rather than keeping the first value", async () => {
const originalFetch = globalThis.fetch;
const fetchMock = vi.fn(async (..._args: FetchCall) => new Response("ok"));
globalThis.fetch = fetchMock as unknown as typeof fetch;
const firstDispose = installHeadroomTransport({
proxyUrl: "http://127.0.0.1:8787/v1",
sessionToken: "tok-A",
});
installHeadroomTransport({ proxyUrl: "http://127.0.0.1:8787/v1", sessionToken: "tok-B" });
await fetch("https://api.anthropic.com/v1/messages", { method: "POST" });
const headers = new Headers(fetchMock.mock.calls[0][1]?.headers);
expect(headers.get("x-headroom-session-token")).toBe("tok-B");
firstDispose();
globalThis.fetch = originalFetch;
});
it("clears the session token on reinstall when the new options omit it", async () => {
// Deliberate: reinstall is last-write-wins for every InstallOptions
// field (proxyUrl, project, debug already work this way) -- an install
// without a token must not leave a stale one active.
const originalFetch = globalThis.fetch;
const fetchMock = vi.fn(async (..._args: FetchCall) => new Response("ok"));
globalThis.fetch = fetchMock as unknown as typeof fetch;
const firstDispose = installHeadroomTransport({
proxyUrl: "http://127.0.0.1:8787/v1",
sessionToken: "tok-A",
});
installHeadroomTransport({ proxyUrl: "http://127.0.0.1:8787/v1" });
await fetch("https://api.anthropic.com/v1/messages", { method: "POST" });
const headers = new Headers(fetchMock.mock.calls[0][1]?.headers);
expect(headers.get("x-headroom-session-token")).toBeNull();
firstDispose();
globalThis.fetch = originalFetch;
});
});
+19 -4
View File
@@ -10,6 +10,7 @@ const fs = nodeRequire("node:fs") as typeof import("node:fs");
export const BASE_URL_HEADER = "x-headroom-base-url";
export const ORIGINAL_PATH_HEADER = "x-headroom-original-path";
export const PROJECT_HEADER = "x-headroom-project";
export const SESSION_TOKEN_HEADER = "x-headroom-session-token";
const PROXY_ENV = "HEADROOM_OPENCODE_TRANSPORT_PROXY_URL";
export const EXCLUDE_HOSTS_ENV = "HEADROOM_OPENCODE_EXCLUDE_HOSTS";
const STATE_KEY = Symbol.for("headroom.opencode.transport");
@@ -30,6 +31,7 @@ interface InstallOptions {
project?: string;
excludeHosts?: string[];
debug?: boolean;
sessionToken?: string;
}
interface TransportState {
@@ -38,6 +40,7 @@ interface TransportState {
project: string | undefined;
excludeHosts: string[];
debug: boolean;
sessionToken: string | undefined;
originalFetch: typeof fetch;
originalHttpRequest: HttpRequest;
originalHttpGet: HttpGet;
@@ -325,6 +328,7 @@ function mergeFetchHeaders(
upstream: URL | undefined,
originalPath: string | undefined = undefined,
project: string | undefined = undefined,
sessionToken: string | undefined = undefined,
): Headers {
const headers = new Headers(input instanceof Request ? input.headers : undefined);
if (init?.headers) {
@@ -340,6 +344,9 @@ function mergeFetchHeaders(
if (project) {
headers.set(PROJECT_HEADER, project);
}
if (sessionToken) {
headers.set(SESSION_TOKEN_HEADER, sessionToken);
}
return headers;
}
@@ -349,6 +356,7 @@ function withRoutedFetchInput(
proxy: URL,
project: string | undefined,
excludeHosts: string[],
sessionToken: string | undefined,
): FetchArgs {
const upstream = requestUrl(input);
if (!shouldRoute(upstream, proxy, excludeHosts)) {
@@ -358,7 +366,7 @@ function withRoutedFetchInput(
const { url: nextUrl, originalPath } = routedUrlForOpenCode(upstream, proxy);
const nextInit = {
...init,
headers: mergeFetchHeaders(input, init, upstream, originalPath, project),
headers: mergeFetchHeaders(input, init, upstream, originalPath, project, sessionToken),
};
if (input instanceof Request) {
@@ -416,6 +424,7 @@ function headersForNodeRequest(
upstream: URL,
originalPath: string | undefined,
project: string | undefined,
sessionToken: string | undefined,
): Record<string, string> {
const headers = new Headers(options.headers as HeadersInit | undefined);
headers.set(BASE_URL_HEADER, upstream.origin);
@@ -425,6 +434,9 @@ function headersForNodeRequest(
if (project) {
headers.set(PROJECT_HEADER, project);
}
if (sessionToken) {
headers.set(SESSION_TOKEN_HEADER, sessionToken);
}
headers.delete("host");
const result: Record<string, string> = {};
@@ -439,6 +451,7 @@ function routedNodeOptions(
proxy: URL,
project: string | undefined,
excludeHosts: string[],
sessionToken: string | undefined,
): Record<string, unknown> | undefined {
if (!parts.url || !shouldRoute(parts.url, proxy, excludeHosts)) {
return undefined;
@@ -472,7 +485,7 @@ function routedNodeOptions(
hostname: nextUrl.hostname,
port: nextUrl.port || undefined,
path: `${nextUrl.pathname}${nextUrl.search}`,
headers: headersForNodeRequest(parts.options, parts.url, originalPath, project),
headers: headersForNodeRequest(parts.options, parts.url, originalPath, project, sessionToken),
};
}
@@ -489,7 +502,7 @@ function wrapRequest(
const proxy = normalizeProxyUrl(state.proxyUrl);
const parts = splitNodeArgs(args);
const nextOptions = routedNodeOptions(parts, proxy, state.project, state.excludeHosts);
const nextOptions = routedNodeOptions(parts, proxy, state.project, state.excludeHosts, state.sessionToken);
if (!nextOptions) {
return Reflect.apply(originalRequest, this, args);
}
@@ -527,6 +540,7 @@ export function installHeadroomTransport(options: InstallOptions): () => void {
existing.project = options.project;
existing.excludeHosts = excludeHosts;
existing.debug = Boolean(options.debug);
existing.sessionToken = options.sessionToken;
installProcessEnv(options.proxyUrl, excludeHosts);
return () => uninstallHeadroomTransport();
}
@@ -537,6 +551,7 @@ export function installHeadroomTransport(options: InstallOptions): () => void {
project: options.project,
excludeHosts,
debug: Boolean(options.debug),
sessionToken: options.sessionToken,
originalFetch: globalThis.fetch,
originalHttpRequest: http.request,
originalHttpGet: http.get,
@@ -557,7 +572,7 @@ export function installHeadroomTransport(options: InstallOptions): () => void {
return state.originalFetch(...args);
}
const proxy = normalizeProxyUrl(current.proxyUrl);
const [nextInput, nextInit] = withRoutedFetchInput(args[0], args[1], proxy, current.project, current.excludeHosts);
const [nextInput, nextInit] = withRoutedFetchInput(args[0], args[1], proxy, current.project, current.excludeHosts, current.sessionToken);
return state.originalFetch(nextInput, nextInit);
};
+10 -3
View File
@@ -8,6 +8,7 @@ from pathlib import Path
import click
import pytest
from headroom import proxy_client_liveness
from headroom.cli import wrap as wrap_cli
@@ -300,10 +301,16 @@ def test_wrap_marker_is_not_stale_for_live_pid(tmp_path: Path) -> None:
def test_wrap_marker_is_stale_when_pid_reused(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
# Inject a deterministic PID identity: _proc_identity returns None on
# Inject a deterministic PID identity: proc_identity returns None on
# macOS without psutil, where reuse detection is deliberately best-effort
# and this scenario would be undetectable.
monkeypatch.setattr(wrap_cli, "_proc_identity", lambda pid: ("test", 50_000.0))
# and this scenario would be undetectable. Two targets needed: the write
# path (_write_wrap_marker) calls wrap_cli's own _proc_identity name
# directly; the later staleness check (_wrap_marker_is_stale ->
# _identity_mismatch) resolves proc_identity from proxy_client_liveness's
# own globals -- patching only one leaves the other on the real impl.
identity = lambda pid: ("test", 50_000.0) # noqa: E731
monkeypatch.setattr(wrap_cli, "_proc_identity", identity)
monkeypatch.setattr(proxy_client_liveness, "proc_identity", identity)
path = _settings(tmp_path)
wrap_cli._write_claude_wrap_base_url("http://127.0.0.1:8787", settings_path=path, port=8787)
marker = json.loads(_marker(tmp_path).read_text(encoding="utf-8"))
@@ -32,7 +32,7 @@ def test_finally_survives_early_proxy_start_failure(
monkeypatch.delenv(key, raising=False)
monkeypatch.setattr(wrap_mod.shutil, "which", lambda _name: "/usr/bin/claude")
monkeypatch.setattr(wrap_mod, "_register_proxy_client", lambda _port: None)
monkeypatch.setattr(wrap_mod, "_register_proxy_client", lambda _port, session_token=None: None)
monkeypatch.setattr(wrap_mod.signal, "signal", lambda *_a, **_k: None)
monkeypatch.setattr(wrap_mod, "_push_runtime_env", lambda *_a, **_k: None)
monkeypatch.setattr(wrap_mod, "_setup_coding_compressor", lambda *_a, **_k: None)
@@ -66,7 +66,7 @@ def _invoke_wrap_claude(
_clear_claude_mode_env(monkeypatch)
monkeypatch.setattr(wrap_mod.shutil, "which", lambda _name: "/usr/bin/claude")
monkeypatch.setattr(wrap_mod, "_register_proxy_client", lambda _port: None)
monkeypatch.setattr(wrap_mod, "_register_proxy_client", lambda _port, session_token=None: None)
monkeypatch.setattr(wrap_mod, "_make_cleanup", lambda _holder, _port: lambda: None)
monkeypatch.setattr(wrap_mod.signal, "signal", lambda *_args, **_kwargs: None)
monkeypatch.setattr(wrap_mod, "_push_runtime_env", lambda *_args, **_kwargs: None)
@@ -163,7 +163,11 @@ def test_wrap_claude_rejects_conflicting_auth_before_proxy_mutation(
monkeypatch.setattr(wrap_mod, "claude_user_settings_path", lambda: user_settings)
monkeypatch.setattr(wrap_mod.shutil, "which", lambda _name: "/usr/bin/claude")
proxy_calls: list[int] = []
monkeypatch.setattr(wrap_mod, "_register_proxy_client", lambda port: proxy_calls.append(port))
monkeypatch.setattr(
wrap_mod,
"_register_proxy_client",
lambda port, session_token=None: proxy_calls.append(port),
)
result = runner.invoke(
main,
+37
View File
@@ -1716,3 +1716,40 @@ def test_wrap_source_has_no_raw_control_bytes() -> None:
# tell the escape from a raw 0x08 byte typed into the file. Check the bytes.
source = Path(wrap_mod.__file__).read_bytes().decode("utf-8")
assert _has_control_chars(source.replace("\r", "")) == []
def test_wrap_opencode_session_token_matches_registration(
runner: CliRunner,
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""Same token must reach both proxy registration and the child env --
two independent presence checks could each pass with mismatched values."""
monkeypatch.chdir(tmp_path)
monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)
_set_test_home(monkeypatch, tmp_path)
captured: dict[str, object] = {}
register_calls: list[dict[str, object]] = []
def fake_launch_tool(**kwargs): # noqa: ANN003
captured.update(kwargs)
def spying_register(port, **kwargs): # noqa: ANN001, ANN003
register_calls.append(kwargs)
with patch.object(wrap_mod.shutil, "which", return_value="opencode"):
with patch.object(wrap_mod, "_launch_tool", side_effect=fake_launch_tool):
with patch.object(wrap_mod, "_register_proxy_client", side_effect=spying_register):
result = runner.invoke(main, ["wrap", "opencode", "--port", "9000", "--no-mcp"])
assert result.exit_code == 0, result.output
assert register_calls, "expected _register_proxy_client to be called"
registered_token = register_calls[0].get("session_token")
assert registered_token, "expected a non-empty session_token to be registered"
env = captured["env"]
assert isinstance(env, dict)
# Assumes the plugin resolves (packaged bundle ships in this checkout);
# see test_build_launch_env_omits_session_token_when_plugin_absent.
assert env.get("HEADROOM_OPENCODE_SESSION_TOKEN") == registered_token
@@ -0,0 +1,89 @@
"""Tests for wrap.py's workspace-root registration: marker cwd/session_token
fields, the 0700 hardening, and session-token header injection."""
from __future__ import annotations
import json
import os
import stat
import sys
import pytest
from headroom import paths
from headroom.cli import wrap as wrap_cli
def _marker_payload(port: int, pid: int) -> dict:
path = paths.proxy_clients_dir(port) / f"{pid}.json"
return json.loads(path.read_text(encoding="utf-8"))
def test_register_proxy_client_records_real_cwd(tmp_path, monkeypatch):
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
project_dir = tmp_path / "myproject"
project_dir.mkdir()
monkeypatch.chdir(project_dir)
try:
wrap_cli._register_proxy_client(8787)
payload = _marker_payload(8787, os.getpid())
# os.getcwd() resolves symlinks (e.g. macOS /tmp -> /private/tmp);
# compare against the same resolution, not the raw tmp_path string.
assert payload["cwd"] == os.getcwd()
assert "session_token" not in payload # no token passed -- optional
finally:
wrap_cli._unregister_proxy_client(8787)
def test_register_proxy_client_records_session_token_when_given(tmp_path, monkeypatch):
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
try:
wrap_cli._register_proxy_client(8788, session_token="tok-xyz")
payload = _marker_payload(8788, os.getpid())
assert payload["session_token"] == "tok-xyz"
finally:
wrap_cli._unregister_proxy_client(8788)
@pytest.mark.skipif(sys.platform == "win32", reason="POSIX file mode bits")
def test_client_marker_directory_is_hardened_to_0700(tmp_path, monkeypatch):
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
try:
wrap_cli._register_proxy_client(8789)
mode = stat.S_IMODE(paths.proxy_clients_dir(8789).stat().st_mode)
assert mode == 0o700
finally:
wrap_cli._unregister_proxy_client(8789)
def test_apply_session_token_header_env_sets_fresh_header():
env: dict[str, str] = {}
wrap_cli._apply_session_token_header_env(env, "tok-123")
assert env["ANTHROPIC_CUSTOM_HEADERS"] == "X-Headroom-Session-Token: tok-123"
def test_apply_session_token_header_env_appends_to_existing_headers():
env = {"ANTHROPIC_CUSTOM_HEADERS": "X-Some-Other: value"}
wrap_cli._apply_session_token_header_env(env, "tok-123")
assert env["ANTHROPIC_CUSTOM_HEADERS"] == (
"X-Some-Other: value\nX-Headroom-Session-Token: tok-123"
)
def test_apply_session_token_header_env_noop_for_blank_token():
env: dict[str, str] = {}
wrap_cli._apply_session_token_header_env(env, "")
assert "ANTHROPIC_CUSTOM_HEADERS" not in env
def test_claude_launch_uses_one_token_for_marker_and_header():
"""Same token must reach both the marker and the header, or lookups
never match."""
import secrets as _secrets
token = _secrets.token_urlsafe(32)
env: dict[str, str] = {}
wrap_cli._apply_session_token_header_env(env, token)
header_line = env["ANTHROPIC_CUSTOM_HEADERS"]
assert token in header_line
assert header_line.startswith(f"{wrap_cli._SESSION_TOKEN_HEADER_NAME}:")
+36
View File
@@ -596,6 +596,42 @@ def test_build_launch_env_with_project(monkeypatch: pytest.MonkeyPatch, tmp_path
assert "ANTHROPIC_BASE_URL" not in env
def test_build_launch_env_forwards_session_token_when_plugin_present(
monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None:
"""Token reaches OpenCode only via the transport plugin -- the only
header-capable layer (native baseURL is header-blind, like Cursor)."""
from headroom.providers.opencode.runtime import build_launch_env
plugin = tmp_path / "entry.opencode.js"
plugin.write_text("export default () => {}", encoding="utf-8")
monkeypatch.setenv("HEADROOM_OPENCODE_PLUGIN_PATH", str(plugin))
env, _display = build_launch_env(
port=8787,
include_mcp=False,
session_token="tok-abc",
)
assert env["HEADROOM_OPENCODE_SESSION_TOKEN"] == "tok-abc"
def test_build_launch_env_omits_session_token_when_plugin_absent(
monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None:
"""No plugin -> no header surface -> token must not be forwarded,
same as Cursor's UNKNOWN."""
from headroom.providers.opencode.runtime import build_launch_env
monkeypatch.setenv("HEADROOM_OPENCODE_PLUGIN_PATH", str(tmp_path / "missing.js"))
env, _display = build_launch_env(
port=8787,
include_mcp=False,
session_token="tok-abc",
)
assert "HEADROOM_OPENCODE_SESSION_TOKEN" not in env
def test_build_launch_env_with_custom_environ() -> None:
from headroom.providers.opencode.runtime import build_launch_env
+72
View File
@@ -0,0 +1,72 @@
"""Tests for headroom.proxy_client_liveness -- extracted from wrap.py so both
the CLI and the proxy (workspace_registry.py) share one liveness/identity
source of truth rather than two independently-decaying ones.
"""
from __future__ import annotations
import json
import os
from headroom import proxy_client_liveness as liveness
def test_pid_alive_true_for_current_process():
assert liveness.pid_alive(os.getpid()) is True
def test_pid_alive_false_for_pid_zero_or_negative():
assert liveness.pid_alive(0) is False
assert liveness.pid_alive(-1) is False
def test_identity_mismatch_conservative_false_for_legacy_record():
"""No start_src/start_time recorded (pre-identity marker format) -- must
not claim a mismatch without proof."""
assert liveness.identity_mismatch(None, None, os.getpid()) is False
def test_identity_mismatch_conservative_false_for_wrong_types():
assert liveness.identity_mismatch(123, "not-a-number", os.getpid()) is False
assert liveness.identity_mismatch("psutil", "not-a-number", os.getpid()) is False
def test_identity_mismatch_false_when_identity_matches_self():
ident = liveness.proc_identity(os.getpid())
if ident is None:
return # platform can't determine identity -- nothing to assert
src, start_time = ident
assert liveness.identity_mismatch(src, start_time, os.getpid()) is False
def test_marker_pid_reused_false_for_malformed_marker(tmp_path):
marker = tmp_path / "123.json"
marker.write_text("{not valid json", encoding="utf-8")
assert liveness.marker_pid_reused(marker, os.getpid()) is False
def test_marker_pid_reused_false_for_missing_marker(tmp_path):
marker = tmp_path / "does-not-exist.json"
assert liveness.marker_pid_reused(marker, os.getpid()) is False
def test_marker_pid_reused_false_for_non_object_json(tmp_path):
"""Valid JSON that isn't an object (e.g. a bare list) must not crash via
AttributeError on .get() -- same bug class as the malformed-syntax case,
just a step further past json.loads succeeding."""
marker = tmp_path / "123.json"
marker.write_text("[1, 2, 3]", encoding="utf-8")
assert liveness.marker_pid_reused(marker, os.getpid()) is False
def test_marker_pid_reused_false_when_recorded_identity_matches_self(tmp_path):
ident = liveness.proc_identity(os.getpid())
if ident is None:
return
src, start_time = ident
marker = tmp_path / f"{os.getpid()}.json"
marker.write_text(
json.dumps({"pid": os.getpid(), "start_src": src, "start_time": start_time}),
encoding="utf-8",
)
assert liveness.marker_pid_reused(marker, os.getpid()) is False
+56
View File
@@ -145,6 +145,62 @@ def test_in_flight_gauge_tracks_running_compressions() -> None:
assert proxy._compression_in_flight == 0
def test_contextvars_set_before_submission_are_visible_inside_the_worker() -> None:
"""`run_in_executor` doesn't copy contextvars into the worker thread by
default (unlike `asyncio.to_thread`) -- without the fix, code reading
`get_registered_cwd()` there would silently see the default, not what
request middleware bound. Locks the fix with a generic ContextVar and
the real one astgrep.py's disk-verify depends on."""
import contextvars
from headroom.proxy.project_context import get_registered_cwd, set_registered_cwd
proxy = _make_proxy(compression_max_workers=2)
probe: contextvars.ContextVar[str | None] = contextvars.ContextVar("test_probe", default=None)
observed: dict[str, object] = {}
def _read_contextvars_on_worker_thread():
observed["probe"] = probe.get()
observed["registered_cwd"] = get_registered_cwd()
return "done"
async def _drive():
probe.set("set-on-calling-coroutine")
set_registered_cwd("/some/registered/project")
return await proxy._run_compression_in_executor(
_read_contextvars_on_worker_thread, timeout=5.0
)
result = asyncio.run(_drive())
assert result == "done"
assert observed["probe"] == "set-on-calling-coroutine"
assert observed["registered_cwd"] == "/some/registered/project"
def test_contextvars_propagate_through_background_executor_too() -> None:
"""Same fix, same bug class, but the *other* submission point --
`_run_compression_background` (no timeout, no leaked-thread accounting)
-- has its own `contextvars.copy_context()` call, not shared code with
`_run_compression_in_executor`. Covered separately since a fix at one
call site doesn't imply the other was fixed too."""
from headroom.proxy.project_context import get_registered_cwd, set_registered_cwd
proxy = _make_proxy(compression_max_workers=1)
observed: dict[str, object] = {}
def _read_registered_cwd_on_worker_thread():
observed["registered_cwd"] = get_registered_cwd()
return "done"
async def _drive():
set_registered_cwd("/some/other/registered/project")
return await proxy._run_compression_background(_read_registered_cwd_on_worker_thread)
result = asyncio.run(_drive())
assert result == "done"
assert observed["registered_cwd"] == "/some/other/registered/project"
def test_high_water_mark_persists_after_completion() -> None:
"""``_compression_in_flight_max`` is monotonic — never decreases."""
proxy = _make_proxy(compression_max_workers=8)
@@ -0,0 +1,142 @@
"""End-to-end test of workspace-root registration through the real HTTP
middleware, including isolation between concurrent sessions on one proxy."""
from __future__ import annotations
import json
import os
from fastapi import FastAPI
from fastapi.testclient import TestClient
from headroom import paths
from headroom.proxy.server import ProxyConfig, create_app
_TEST_PORT = 18787
def _make_app() -> FastAPI:
return create_app(
ProxyConfig(
optimize=False,
cache_enabled=False,
rate_limit_enabled=False,
cost_tracking_enabled=False,
log_requests=False,
ccr_inject_tool=False,
ccr_handle_responses=False,
ccr_context_tracking=False,
image_optimize=False,
port=_TEST_PORT,
)
)
def _app_with_registered_cwd_probe() -> FastAPI:
"""Test-only route reading get_registered_cwd() after the middleware runs."""
from headroom.proxy.project_context import get_registered_cwd
app = _make_app()
@app.get("/__test/registered-cwd")
def _probe() -> dict[str, str | None]:
return {"registered_cwd": get_registered_cwd()}
# A catch-all passthrough route registered by create_app() would
# otherwise shadow this path -- Starlette matches routes in
# registration order, not by specificity.
app.router.routes.insert(0, app.router.routes.pop())
return app
def _write_marker(pid: int, session_token: str, cwd: str) -> None:
d = paths.proxy_clients_dir(_TEST_PORT)
d.mkdir(parents=True, exist_ok=True)
(d / f"{pid}.json").write_text(
json.dumps({"pid": pid, "session_token": session_token, "cwd": cwd}),
encoding="utf-8",
)
def test_valid_session_token_resolves_registered_cwd(tmp_path, monkeypatch):
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
project_dir = tmp_path / "project"
project_dir.mkdir()
_write_marker(os.getpid(), "tok-real", str(project_dir))
client = TestClient(_app_with_registered_cwd_probe())
resp = client.get("/__test/registered-cwd", headers={"x-headroom-session-token": "tok-real"})
assert resp.json() == {"registered_cwd": str(project_dir)}
def test_opencode_registration_marker_resolves_through_real_middleware(tmp_path, monkeypatch):
"""Closes the seam the reviewer flagged: proves there's no schema drift
between what opencode()'s wrap command actually writes
(wrap._register_proxy_client -- the same function claude() calls, not
a hand-rolled test marker) and what resolve_registered_cwd() reads,
using the lowercase header casing the OpenCode transport plugin sends
(vs. claude's title-case) over the real HTTP middleware."""
from headroom.cli import wrap as wrap_mod
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
project_dir = tmp_path / "opencode-project"
project_dir.mkdir()
monkeypatch.chdir(project_dir)
wrap_mod._register_proxy_client(_TEST_PORT, session_token="tok-opencode")
client = TestClient(_app_with_registered_cwd_probe())
resp = client.get(
"/__test/registered-cwd", headers={"x-headroom-session-token": "tok-opencode"}
)
assert resp.json() == {"registered_cwd": str(project_dir)}
def test_missing_or_wrong_token_resolves_to_none(tmp_path, monkeypatch):
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
project_dir = tmp_path / "project"
project_dir.mkdir()
_write_marker(os.getpid(), "tok-real", str(project_dir))
client = TestClient(_app_with_registered_cwd_probe())
no_token = client.get("/__test/registered-cwd")
assert no_token.json() == {"registered_cwd": None}
wrong_token = client.get(
"/__test/registered-cwd", headers={"x-headroom-session-token": "tok-guessed"}
)
assert wrong_token.json() == {"registered_cwd": None}
def test_spoofed_cwd_header_alone_never_resolves_anything(tmp_path, monkeypatch):
"""A spoofed x-headroom-cwd with no matching registration must never
surface as the registered root."""
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
client = TestClient(_app_with_registered_cwd_probe())
resp = client.get("/__test/registered-cwd", headers={"x-headroom-cwd": "/etc"})
assert resp.json() == {"registered_cwd": None}
def test_two_concurrent_sessions_on_one_shared_proxy_stay_isolated(tmp_path, monkeypatch):
"""Token A must resolve only project A's cwd, never project B's."""
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
project_a = tmp_path / "project-a"
project_b = tmp_path / "project-b"
project_a.mkdir()
project_b.mkdir()
import subprocess
import sys
child = subprocess.Popen([sys.executable, "-c", "import time; time.sleep(30)"])
try:
_write_marker(os.getpid(), "tok-a", str(project_a))
_write_marker(child.pid, "tok-b", str(project_b))
client = TestClient(_app_with_registered_cwd_probe())
resp_a = client.get("/__test/registered-cwd", headers={"x-headroom-session-token": "tok-a"})
resp_b = client.get("/__test/registered-cwd", headers={"x-headroom-session-token": "tok-b"})
assert resp_a.json() == {"registered_cwd": str(project_a)}
assert resp_b.json() == {"registered_cwd": str(project_b)}
finally:
child.kill()
child.wait()
+566 -1
View File
@@ -2,7 +2,11 @@
from __future__ import annotations
import asyncio
import os
import sys
import textwrap
from types import SimpleNamespace
import pytest
@@ -14,8 +18,14 @@ from headroom.proxy.interceptors import (
interceptor_failure_counts,
register,
)
from headroom.proxy.interceptors.astgrep import AstGrepReadOutline
from headroom.proxy.interceptors.astgrep import (
AstGrepReadOutline,
ReadVerificationResult,
_open_regular_file_under_root,
_verify_read_against_disk,
)
from headroom.proxy.interceptors.base import reset_interceptor_failure_counts
from headroom.proxy.project_context import get_registered_cwd, set_registered_cwd
from headroom.tokenizer import Tokenizer
@@ -211,6 +221,561 @@ def test_astgrep_outlines_large_python_read(tokenizer):
assert "def apply_promo" in new_content
# Bodies should NOT leak through unchanged.
assert "total += item.price * item.qty" not in new_content
# Complete-file control: no truncation banner in the input -> no truncation marker.
assert "truncated upstream" not in new_content
def test_astgrep_flags_truncated_read(tokenizer):
truncated_source = (
_PY_FIXTURE + "\n\n[Truncated: PARTIAL view — /repo/payments.py: "
"showing lines 1-42 of 90 total (26031 tokens, cap 25000). "
"Call Read with offset=43 to see more.]\n"
)
messages = [
{
"role": "assistant",
"content": [
{
"type": "tool_use",
"id": "abc",
"name": "Read",
"input": {"file_path": "/repo/payments.py"},
}
],
},
{
"role": "user",
"content": [{"type": "tool_result", "tool_use_id": "abc", "content": truncated_source}],
},
]
result = apply_to_messages(messages, tokenizer)
assert len(result.spans) == 1
new_content = result.messages[1]["content"][0]["content"]
assert "truncated upstream" in new_content
assert "showing through line 42 of 90 total" in new_content
# Still lists the definitions actually present in the visible portion.
assert "def process_payment" in new_content
assert "def apply_promo" in new_content
def _read_result_messages(content: str, file_path: str = "/repo/payments.py"):
return [
{
"role": "assistant",
"content": [
{
"type": "tool_use",
"id": "abc",
"name": "Read",
"input": {"file_path": file_path},
}
],
},
{
"role": "user",
"content": [{"type": "tool_result", "tool_use_id": "abc", "content": content}],
},
]
def test_astgrep_flags_truncated_read_wording_variants(tokenizer):
"""The signature tolerates wording/casing/dash variation, but only inside
the recognized envelope — not as a synonym match over arbitrary prose."""
truncated_source = (
_PY_FIXTURE + "\n\n[TRUNCATED: PARTIAL VIEW — /repo/payments.py: "
"SHOWING LINES 1–42 of 90 TOTAL. Call Read with offset=43 to see more.]\n"
)
messages = _read_result_messages(truncated_source)
result = apply_to_messages(messages, tokenizer)
assert len(result.spans) == 1
new_content = result.messages[1]["content"][0]["content"]
assert "truncated upstream" in new_content
assert "showing through line 42 of 90 total" in new_content
def test_astgrep_ignores_truncation_phrase_in_comment(tokenizer):
"""A count-shaped phrase in a plain comment, with no bracketed envelope,
must not be read as an upstream truncation claim."""
source_with_comment = (
_PY_FIXTURE + "\n\n# API pagination showing lines 10-20 of 30 total records\n"
)
messages = _read_result_messages(source_with_comment)
result = apply_to_messages(messages, tokenizer)
new_content = result.messages[1]["content"][0]["content"]
assert "truncated upstream" not in new_content
def test_astgrep_ignores_bracketed_phrase_without_signature(tokenizer):
"""Brackets plus a count-shaped phrase aren't enough on their own — the
exact recognized signature phrase must also be present."""
source_with_bracket = (
_PY_FIXTURE + "\n\n[Truncation happened; showing lines 1-42 of 90 total]\n"
)
messages = _read_result_messages(source_with_bracket)
result = apply_to_messages(messages, tokenizer)
new_content = result.messages[1]["content"][0]["content"]
assert "truncated upstream" not in new_content
@pytest.mark.parametrize(
"banner_numbers",
[
pytest.param("50-90 of 90", id="end_equals_total"),
pytest.param("42-10 of 90", id="end_less_than_start"),
pytest.param("0-42 of 90", id="start_is_zero"),
pytest.param("1-5000 of 9000", id="end_exceeds_visible_payload"),
],
)
def test_astgrep_ignores_malformed_truncation_counts(tokenizer, banner_numbers):
truncated_source = (
_PY_FIXTURE + "\n\n[Truncated: PARTIAL view — /repo/payments.py: "
f"showing lines {banner_numbers} total (26031 tokens, cap 25000). "
"Call Read with offset=43 to see more.]\n"
)
messages = _read_result_messages(truncated_source)
result = apply_to_messages(messages, tokenizer)
new_content = result.messages[1]["content"][0]["content"]
assert "outlined by ast-grep" in new_content
assert "truncated upstream" not in new_content
def test_astgrep_accepts_truncation_at_start_equals_end(tokenizer):
"""`end >= start` is inclusive — a single-line visible window is valid."""
truncated_source = (
_PY_FIXTURE + "\n\n[Truncated: PARTIAL view — /repo/payments.py: "
"showing lines 42-42 of 90 total (26031 tokens, cap 25000). "
"Call Read with offset=43 to see more.]\n"
)
messages = _read_result_messages(truncated_source)
result = apply_to_messages(messages, tokenizer)
new_content = result.messages[1]["content"][0]["content"]
assert "truncated upstream" in new_content
# -------- Disk verification: client-independent truncation fallback ----- #
def test_set_get_registered_cwd_round_trips():
set_registered_cwd("/repo/project")
try:
assert get_registered_cwd() == "/repo/project"
finally:
set_registered_cwd(None)
class TestVerifyReadAgainstDisk:
def test_missing_file_path_is_unknown(self):
verdict, info = _verify_read_against_disk(None, "abc", "/repo")
assert verdict is ReadVerificationResult.UNKNOWN
assert info is None
def test_no_registered_cwd_is_unknown(self):
verdict, info = _verify_read_against_disk("payments.py", "abc", None)
assert verdict is ReadVerificationResult.UNKNOWN
assert info is None
def test_untrusted_request_never_touches_disk(self, tmp_path, monkeypatch):
"""A valid file/content combo must short-circuit to UNKNOWN -- and
never call os.open -- when no root is registered."""
f = tmp_path / "payments.py"
f.write_text(_PY_FIXTURE, encoding="utf-8")
opened: list[object] = []
real_open = os.open
def _tracking_open(*args, **kwargs):
opened.append(args)
return real_open(*args, **kwargs)
monkeypatch.setattr(os, "open", _tracking_open)
verdict, info = _verify_read_against_disk(str(f), _PY_FIXTURE, None)
assert verdict is ReadVerificationResult.UNKNOWN
assert info is None
assert opened == []
def test_missing_file_under_workspace_root_is_unknown(self, tmp_path):
verdict, info = _verify_read_against_disk(
str(tmp_path / "missing.py"), "abc", str(tmp_path)
)
assert verdict is ReadVerificationResult.UNKNOWN
assert info is None
@pytest.mark.skipif(
sys.platform == "win32",
reason="dir_fd disk verification unavailable on Windows; falls back to UNKNOWN"
" (see test_open_regular_file_under_root_falls_back_unknown_when_dir_fd_unsupported)",
)
def test_exact_match_is_complete(self, tmp_path):
f = tmp_path / "payments.py"
f.write_text(_PY_FIXTURE, encoding="utf-8")
verdict, info = _verify_read_against_disk(str(f), _PY_FIXTURE, str(tmp_path))
assert verdict is ReadVerificationResult.COMPLETE
assert info is None
@pytest.mark.skipif(
sys.platform == "win32",
reason="dir_fd disk verification unavailable on Windows; falls back to UNKNOWN"
" (see test_open_regular_file_under_root_falls_back_unknown_when_dir_fd_unsupported)",
)
def test_strict_prefix_is_truncated(self, tmp_path):
f = tmp_path / "payments.py"
f.write_text(_PY_FIXTURE, encoding="utf-8")
partial = _PY_FIXTURE[:200]
verdict, info = _verify_read_against_disk(str(f), partial, str(tmp_path))
assert verdict is ReadVerificationResult.TRUNCATED
assert info == (len(partial.splitlines()), len(_PY_FIXTURE.splitlines()))
@pytest.mark.skipif(
sys.platform == "win32",
reason="dir_fd disk verification unavailable on Windows; falls back to UNKNOWN"
" (see test_open_regular_file_under_root_falls_back_unknown_when_dir_fd_unsupported)",
)
def test_relative_path_resolves_against_registered_cwd(self, tmp_path):
f = tmp_path / "payments.py"
f.write_text(_PY_FIXTURE, encoding="utf-8")
partial = _PY_FIXTURE[:200]
verdict, info = _verify_read_against_disk("payments.py", partial, str(tmp_path))
assert verdict is ReadVerificationResult.TRUNCATED
assert info is not None
def test_content_mismatch_is_unknown_not_truncated(self, tmp_path):
# File diverged since the client read it -- not a clean prefix.
f = tmp_path / "payments.py"
f.write_text(_PY_FIXTURE.replace("compute_subtotal", "compute_total"), encoding="utf-8")
verdict, info = _verify_read_against_disk(str(f), _PY_FIXTURE, str(tmp_path))
assert verdict is ReadVerificationResult.UNKNOWN
assert info is None
def test_absolute_path_outside_workspace_root_is_unknown(self, tmp_path):
root = tmp_path / "project"
root.mkdir()
sibling = tmp_path / "other"
sibling.mkdir()
f = sibling / "secret.py"
f.write_text(_PY_FIXTURE, encoding="utf-8")
verdict, info = _verify_read_against_disk(str(f), _PY_FIXTURE, str(root))
assert verdict is ReadVerificationResult.UNKNOWN
assert info is None
def test_relative_traversal_escapes_workspace_is_unknown(self, tmp_path):
root = tmp_path / "project"
root.mkdir()
f = tmp_path / "secret.py"
f.write_text(_PY_FIXTURE, encoding="utf-8")
verdict, info = _verify_read_against_disk("../secret.py", _PY_FIXTURE, str(root))
assert verdict is ReadVerificationResult.UNKNOWN
assert info is None
def test_sibling_directory_sharing_string_prefix_is_not_inside_workspace(self, tmp_path):
"""Containment is a path-segment check (relpath/segment split), not
a string-prefix check -- a target that merely starts with the
root's string must not be treated as inside it."""
root = tmp_path / "project"
root.mkdir()
other = tmp_path / "project-other"
other.mkdir()
f = other / "secret.py"
f.write_text(_PY_FIXTURE, encoding="utf-8")
verdict, info = _verify_read_against_disk(str(f), _PY_FIXTURE, str(root))
assert verdict is ReadVerificationResult.UNKNOWN
assert info is None
def test_directory_passed_as_file_path_is_unknown(self, tmp_path):
root = tmp_path / "project"
subdir = root / "subdir"
subdir.mkdir(parents=True)
verdict, info = _verify_read_against_disk("subdir", "abc", str(root))
assert verdict is ReadVerificationResult.UNKNOWN
assert info is None
def test_oversized_file_exceeding_byte_cap_is_unknown(self, tmp_path, monkeypatch):
monkeypatch.setenv("HEADROOM_VERIFY_TRUNCATION_MAX_BYTES", "10")
f = tmp_path / "payments.py"
f.write_text(_PY_FIXTURE, encoding="utf-8")
assert len(_PY_FIXTURE.encode("utf-8")) > 10
# Content matches exactly -- would be COMPLETE without the cap.
verdict, info = _verify_read_against_disk(str(f), _PY_FIXTURE, str(tmp_path))
assert verdict is ReadVerificationResult.UNKNOWN
assert info is None
# -------- _open_regular_file_under_root: race-safety + off-loop (review round 2) --------- #
@pytest.mark.skipif(sys.platform == "win32", reason="symlinks need elevated privilege on Windows")
def test_open_regular_file_under_root_rejects_symlinked_final_file(tmp_path):
"""A symlinked leaf file must be rejected by O_NOFOLLOW, not followed.
A static symlink is sufficient race evidence here: O_NOFOLLOW rejects it
the same way whether it's always been there or appeared 2ms ago -- a
concurrent-race harness would prove nothing more and would be flaky.
"""
root = tmp_path / "project"
root.mkdir()
outside = tmp_path / "outside.py"
outside.write_text(_PY_FIXTURE, encoding="utf-8")
link = root / "link.py"
link.symlink_to(outside)
assert _open_regular_file_under_root("link.py", root, 10_000) is None
@pytest.mark.skipif(sys.platform == "win32", reason="symlinks need elevated privilege on Windows")
def test_open_regular_file_under_root_rejects_symlinked_intermediate_directory(tmp_path):
"""A symlinked directory component must be rejected at that hop, not
walked into."""
root = tmp_path / "project"
root.mkdir()
real_dir = tmp_path / "realdir"
real_dir.mkdir()
(real_dir / "secret.py").write_text(_PY_FIXTURE, encoding="utf-8")
link_dir = root / "linkdir"
link_dir.symlink_to(real_dir)
assert _open_regular_file_under_root("linkdir/secret.py", root, 10_000) is None
@pytest.mark.skipif(sys.platform == "win32", reason="symlinks need elevated privilege on Windows")
def test_open_regular_file_under_root_rejects_symlinked_root_anchor(tmp_path):
"""The root anchor itself must be opened O_NOFOLLOW too, not just the
segments below it -- otherwise a symlink swapped in at the resolved root
path would be followed, the exact TOCTOU shape review round 2 flagged,
just moved from the leaf to the anchor."""
real_root = tmp_path / "real-project"
real_root.mkdir()
(real_root / "x.py").write_text("content", encoding="utf-8")
root_link = tmp_path / "project-link"
root_link.symlink_to(real_root)
assert _open_regular_file_under_root("x.py", root_link, 10_000) is None
def test_open_regular_file_under_root_refuses_on_event_loop_thread(tmp_path):
"""Calling from inside a running event loop must refuse immediately
rather than perform the read."""
f = tmp_path / "x.py"
f.write_text("content", encoding="utf-8")
async def _call_from_loop():
return _open_regular_file_under_root(str(f), tmp_path, 10_000)
assert asyncio.run(_call_from_loop()) is None
@pytest.mark.skipif(
sys.platform == "win32",
reason="dir_fd disk verification unavailable on Windows; falls back to UNKNOWN"
" (see test_open_regular_file_under_root_falls_back_unknown_when_dir_fd_unsupported)",
)
def test_open_regular_file_under_root_proceeds_from_plain_sync_context(tmp_path):
"""Sanity check: with no running loop, the read must still succeed."""
f = tmp_path / "x.py"
f.write_text("content", encoding="utf-8")
assert _open_regular_file_under_root(str(f), tmp_path, 10_000) == "content"
@pytest.mark.skipif(
sys.platform == "win32",
reason="dir_fd disk verification unavailable on Windows; falls back to UNKNOWN"
" (see test_open_regular_file_under_root_falls_back_unknown_when_dir_fd_unsupported)",
)
def test_open_regular_file_under_root_rejects_growth_between_stat_and_read(tmp_path, monkeypatch):
"""A file that grows past max_bytes between the fstat check and the
read must fail closed to None, not return the oversized content -- the
fstat result can go stale by the time the read actually runs. The file
genuinely contains >max_bytes on disk; only the fstat result lies, so a
passing test proves the read itself is bounded, not that fstat was
merely re-checked."""
f = tmp_path / "x.py"
f.write_bytes(b"x" * 1_000_001)
real_fstat = os.fstat
def lying_fstat(fd):
real_st = real_fstat(fd)
return SimpleNamespace(st_mode=real_st.st_mode, st_size=1)
monkeypatch.setattr(os, "fstat", lying_fstat)
assert _open_regular_file_under_root("x.py", tmp_path, max_bytes=8) is None
def test_open_regular_file_under_root_falls_back_unknown_when_dir_fd_unsupported(
tmp_path, monkeypatch
):
"""Fails closed (None) rather than falling back to a less-safe pattern
when dir_fd-relative opens aren't supported (notably Windows)."""
import headroom.proxy.interceptors.astgrep as astgrep_module
f = tmp_path / "x.py"
f.write_text("content", encoding="utf-8")
monkeypatch.setattr(astgrep_module, "_dir_fd_walk_supported", lambda: False)
assert _open_regular_file_under_root(str(f), tmp_path, 10_000) is None
def test_open_regular_file_under_root_directory_passed_as_target_is_unknown(tmp_path):
"""A directory at the leaf position must be rejected -- the target must
be a file."""
(tmp_path / "subdir").mkdir()
assert _open_regular_file_under_root("subdir", tmp_path, 10_000) is None
@pytest.mark.skipif(sys.platform == "win32", reason="os.mkfifo unavailable on Windows")
def test_open_regular_file_under_root_rejects_fifo_without_hanging(tmp_path):
"""A FIFO must be rejected by the S_ISREG check, and -- because the open
uses O_NONBLOCK -- must return promptly rather than blocking on a
writer that will never arrive. If this test hangs, O_NONBLOCK regressed."""
fifo_path = tmp_path / "pipe"
os.mkfifo(fifo_path)
assert _open_regular_file_under_root("pipe", tmp_path, 10_000) is None
# -------- End-to-end: apply_to_messages, real registered_cwd --------- #
def _disk_verification_messages(partial: str) -> list[dict]:
return [
{
"role": "assistant",
"content": [
{
"type": "tool_use",
"id": "abc",
"name": "Read",
"input": {"file_path": "payments.py"},
}
],
},
{
"role": "user",
"content": [{"type": "tool_result", "tool_use_id": "abc", "content": partial}],
},
]
@pytest.mark.skipif(
sys.platform == "win32",
reason="dir_fd disk verification unavailable on Windows; falls back to UNKNOWN"
" (see test_astgrep_disk_verification_stays_unknown_when_dir_fd_unsupported)",
)
def test_astgrep_disk_verification_flags_truncation_when_no_banner(
tokenizer, tmp_path, monkeypatch
):
"""Opted in, root registered, real on-disk prefix, no banner -- disk
verification alone qualifies the header."""
monkeypatch.setenv("HEADROOM_VERIFY_TRUNCATION_ON_DISK", "1")
monkeypatch.setenv("HEADROOM_INTERCEPT_READ_MIN_CHARS", "50")
f = tmp_path / "payments.py"
f.write_text(_PY_FIXTURE, encoding="utf-8")
marker = "\n\ndef format_receipt"
partial = _PY_FIXTURE[: _PY_FIXTURE.index(marker)] # no banner text anywhere
assert "truncated" not in partial.lower()
set_registered_cwd(str(tmp_path))
try:
result = apply_to_messages(_disk_verification_messages(partial), tokenizer)
finally:
set_registered_cwd(None)
assert len(result.spans) == 1
new_content = result.messages[1]["content"][0]["content"]
assert "truncated upstream" in new_content
visible_lines = len(partial.splitlines())
total_lines = len(_PY_FIXTURE.splitlines())
assert f"showing through line {visible_lines} of {total_lines} total" in new_content
assert "def compute_subtotal" in new_content
assert "def apply_promo" in new_content
assert "def format_receipt" not in new_content
def test_astgrep_disk_verification_stays_unknown_when_dir_fd_unsupported(
tokenizer, tmp_path, monkeypatch
):
"""Fail-closed contract, simulated cross-platform: dir_fd unsupported ->
UNKNOWN -> no false "truncated upstream" claim. Stands in for the real
Windows behavior the skipif'd tests above can't exercise here."""
import headroom.proxy.interceptors.astgrep as astgrep_module
monkeypatch.setattr(astgrep_module, "_dir_fd_walk_supported", lambda: False)
monkeypatch.setenv("HEADROOM_VERIFY_TRUNCATION_ON_DISK", "1")
monkeypatch.setenv("HEADROOM_INTERCEPT_READ_MIN_CHARS", "50")
f = tmp_path / "payments.py"
f.write_text(_PY_FIXTURE, encoding="utf-8")
marker = "\n\ndef format_receipt"
partial = _PY_FIXTURE[: _PY_FIXTURE.index(marker)] # no banner text anywhere
assert "truncated" not in partial.lower()
set_registered_cwd(str(tmp_path))
try:
result = apply_to_messages(_disk_verification_messages(partial), tokenizer)
finally:
set_registered_cwd(None)
# The outline rewrite is independent of the disk-verify verdict.
assert len(result.spans) == 1
new_content = result.messages[1]["content"][0]["content"]
assert "truncated upstream" not in new_content
def test_astgrep_disk_verification_skips_when_no_root_registered(tokenizer, tmp_path, monkeypatch):
"""No registered root at all (the default) -- opted in, real on-disk
prefix, but never flags. Spoofed-header-doesn't-work is covered
end-to-end in test_proxy_workspace_registration_middleware.py."""
monkeypatch.setenv("HEADROOM_VERIFY_TRUNCATION_ON_DISK", "1")
monkeypatch.setenv("HEADROOM_INTERCEPT_READ_MIN_CHARS", "50")
f = tmp_path / "payments.py"
f.write_text(_PY_FIXTURE, encoding="utf-8")
marker = "\n\ndef format_receipt"
partial = _PY_FIXTURE[: _PY_FIXTURE.index(marker)]
messages = [
{
"role": "assistant",
"content": [
{
"type": "tool_use",
"id": "abc",
"name": "Read",
"input": {"file_path": "payments.py"},
}
],
},
{
"role": "user",
"content": [{"type": "tool_result", "tool_use_id": "abc", "content": partial}],
},
]
result = apply_to_messages(messages, tokenizer)
new_content = result.messages[1]["content"][0]["content"]
assert "truncated upstream" not in new_content
def test_astgrep_banner_detection_takes_priority_over_disk_verification(tokenizer, monkeypatch):
"""When a banner is already present, disk verification must not run at
all (no cwd bound here -- if it ran, resolution would fail anyway), and
the banner's own numbers must be what the header reports."""
monkeypatch.setenv("HEADROOM_VERIFY_TRUNCATION_ON_DISK", "1")
truncated_source = (
_PY_FIXTURE + "\n\n[Truncated: PARTIAL view — /repo/payments.py: "
"showing lines 1-42 of 90 total (26031 tokens, cap 25000). "
"Call Read with offset=43 to see more.]\n"
)
messages = [
{
"role": "assistant",
"content": [
{
"type": "tool_use",
"id": "abc",
"name": "Read",
"input": {"file_path": "/repo/payments.py"},
}
],
},
{
"role": "user",
"content": [{"type": "tool_result", "tool_use_id": "abc", "content": truncated_source}],
},
]
result = apply_to_messages(messages, tokenizer)
new_content = result.messages[1]["content"][0]["content"]
assert "showing through line 42 of 90 total" in new_content
def test_astgrep_skips_small_files(tokenizer):
+128
View File
@@ -0,0 +1,128 @@
"""Tests for headroom.proxy.workspace_registry.resolve_registered_cwd."""
from __future__ import annotations
import json
import os
import subprocess
import sys
from headroom import paths
from headroom.proxy.workspace_registry import resolve_registered_cwd
def _write_marker(port: int, pid: int, payload: dict) -> None:
d = paths.proxy_clients_dir(port)
d.mkdir(parents=True, exist_ok=True)
(d / f"{pid}.json").write_text(json.dumps(payload), encoding="utf-8")
def _spawn_and_reap() -> int:
"""Return a PID that is guaranteed dead (spawned, then waited on)."""
proc = subprocess.Popen([sys.executable, "-c", "pass"])
proc.wait()
return proc.pid
def test_no_token_is_none(tmp_path, monkeypatch):
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
assert resolve_registered_cwd(8787, None) is None
assert resolve_registered_cwd(8787, "") is None
def test_no_marker_directory_is_none(tmp_path, monkeypatch):
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
assert resolve_registered_cwd(8787, "some-token") is None
def test_matching_token_live_pid_returns_cwd(tmp_path, monkeypatch):
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
project_dir = tmp_path / "project"
project_dir.mkdir()
_write_marker(
8787,
os.getpid(), # this test process -- always live
{"pid": os.getpid(), "session_token": "tok-A", "cwd": str(project_dir)},
)
assert resolve_registered_cwd(8787, "tok-A") == str(project_dir)
def test_wrong_token_is_none_even_with_a_live_marker_present(tmp_path, monkeypatch):
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
project_dir = tmp_path / "project"
project_dir.mkdir()
_write_marker(
8787,
os.getpid(),
{"pid": os.getpid(), "session_token": "tok-A", "cwd": str(project_dir)},
)
assert resolve_registered_cwd(8787, "tok-B-guessed") is None
def test_stale_marker_dead_pid_is_none_not_the_cwd(tmp_path, monkeypatch):
"""A crashed/killed session's marker must not be trusted."""
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
dead_pid = _spawn_and_reap()
project_dir = tmp_path / "project"
project_dir.mkdir()
_write_marker(
8787,
dead_pid,
{"pid": dead_pid, "session_token": "tok-dead", "cwd": str(project_dir)},
)
assert resolve_registered_cwd(8787, "tok-dead") is None
def test_multi_session_isolation_token_resolves_only_its_own_cwd(tmp_path, monkeypatch):
"""One proxy can serve N concurrent sessions -- token A must never
resolve project B's cwd."""
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
project_a = tmp_path / "project-a"
project_b = tmp_path / "project-b"
project_a.mkdir()
project_b.mkdir()
# Two distinct *live* PIDs: this test process and a spawned-but-blocked
# child (killed at teardown) so both are genuinely alive at lookup time.
child = subprocess.Popen([sys.executable, "-c", "import time; time.sleep(30)"])
try:
_write_marker(
8787,
os.getpid(),
{"pid": os.getpid(), "session_token": "tok-a", "cwd": str(project_a)},
)
_write_marker(
8787,
child.pid,
{"pid": child.pid, "session_token": "tok-b", "cwd": str(project_b)},
)
assert resolve_registered_cwd(8787, "tok-a") == str(project_a)
assert resolve_registered_cwd(8787, "tok-b") == str(project_b)
finally:
child.kill()
child.wait()
def test_non_string_cwd_in_marker_is_none(tmp_path, monkeypatch):
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
_write_marker(8787, os.getpid(), {"pid": os.getpid(), "session_token": "tok-A", "cwd": 12345})
assert resolve_registered_cwd(8787, "tok-A") is None
def test_malformed_marker_json_is_skipped_not_raised(tmp_path, monkeypatch):
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
d = paths.proxy_clients_dir(8787)
d.mkdir(parents=True, exist_ok=True)
(d / f"{os.getpid()}.json").write_text("{not valid json", encoding="utf-8")
assert resolve_registered_cwd(8787, "tok-A") is None
def test_non_object_marker_json_is_skipped_not_raised(tmp_path, monkeypatch):
"""Syntactically valid JSON that isn't an object (e.g. a bare list) must
not crash resolution via AttributeError on .get() -- this function runs
on every request through the middleware, so one bad marker must not take
down the whole proxy."""
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
d = paths.proxy_clients_dir(8787)
d.mkdir(parents=True, exist_ok=True)
(d / f"{os.getpid()}.json").write_text("[1, 2, 3]", encoding="utf-8")
assert resolve_registered_cwd(8787, "tok-A") is None