fix: resolve dependency lock conflicts with upstream main

This commit is contained in:
Alicia
2026-10-25 01:26:52 +08:00
197 changed files with 22932 additions and 5029 deletions
+1 -1
View File
@@ -7,7 +7,7 @@ jobs:
smoke:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
- name: Exercise production notification component
uses: ./.github/actions/release-slack-notification
with:
+24
View File
@@ -747,6 +747,30 @@ jobs:
tests/test_cli/test_wrap_opencode.py \
tests/test_proxy_workspace_registration_middleware.py -q
windows-file-permissions:
# Verifies the Windows NTFS-ACL path in headroom._fileperms_windows for
# real: those tests were previously skipped everywhere, so the module
# was asserted correct but never run (#4058). The mode-bits (POSIX)
# assertions in the same file stay skipped here deliberately.
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 the owner-only file-permission tests
shell: bash
run: |
pytest tests/test_cache_breakpoint_diagnostics.py tests/test_private_state_files.py -v
macos-native-wrapper:
needs: changes
if: needs.changes.outputs.native == 'true'
+148 -3
View File
@@ -51,9 +51,105 @@ jobs:
wc -l requirements-prod.txt
- name: Audit dependencies (pip-audit)
uses: pypa/gh-action-pip-audit@v1.1.0
# The export is uv.lock's fully pinned set, overrides applied: audit it
# as is. pip must not re-resolve it (fastembed's pillow<13 cap would
# fail; see [tool.uv] override-dependencies), and the pip-audit action
# has no --disable-pip input, so pip-audit runs directly.
run: uvx pip-audit==2.10.1 -r requirements-prod.txt --no-deps --disable-pip
# ---- SCA: what `pip install headroom-ai[all]` gets ---------------------
# The job above audits uv.lock, which the release image also installs
# (overrides applied). pip ignores [tool.uv] and resolves the package
# metadata, where fastembed caps pillow <13: audit that set too. Its Pillow
# advisories fixed in 13 are accepted only because headroom/image/
# decoder_guard.py never decodes an image on Pillow <13, which the guard step
# proves on that same Pillow first. Any other finding fails the job.
# `uv pip compile` stands in for pip's resolver on Linux/Python 3.12, so it
# approximates, not reproduces, every user's install; on Python 3.10 pip
# also gets Pillow 12 (guarded) and filelock <4.2.1 (no fixed release there).
# It resolves live from PyPI, so a new upstream advisory would fail PRs that
# did not cause it: on pull requests it runs only when pyproject.toml changes;
# pushes to main and the weekly schedule always run it.
published-install-audit:
name: Dependency audit (pip install from package metadata)
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- uses: actions/checkout@v7
with:
inputs: requirements-prod.txt
fetch-depth: 0
- name: Run on this event?
id: gate
run: |
if [ "${{ github.event_name }}" != "pull_request" ] || \
git diff --name-only "${{ github.event.pull_request.base.sha }}" HEAD | grep -qx pyproject.toml; then
echo "run=true" >> "$GITHUB_OUTPUT"
else
echo "pyproject.toml unchanged in this PR; main and the weekly run cover it."
fi
- name: Set up Python
if: steps.gate.outputs.run == 'true'
uses: actions/setup-python@v7
with:
python-version: "3.12"
- name: Install uv
if: steps.gate.outputs.run == 'true'
uses: astral-sh/setup-uv@v10.3.0
- name: Resolve what pip installs from the package metadata
if: steps.gate.outputs.run == 'true'
run: |
uv --no-config pip compile pyproject.toml --extra all --python-version 3.12 \
--no-header --no-annotate -o published.txt
uv --no-config pip compile pyproject.toml --python-version 3.12 \
--no-header --no-annotate -o core.txt
grep -iE '^(pillow|fastembed)==' published.txt
- name: The decoder guard holds on that Pillow
if: steps.gate.outputs.run == 'true'
run: |
uv venv -p 3.12 .published
uv --no-config pip install -p .published -r core.txt \
"$(grep -i '^pillow==' published.txt)" pytest pytest-asyncio
.published/bin/python -m pytest -p no:cacheprovider tests/test_image_decoder_guard.py
PINNED="$(grep -i '^pillow==' published.txt | cut -d= -f3)" .published/bin/python - <<'PY'
import os
import PIL
from headroom.image.decoder_guard import FIXED_PILLOW_MAJOR, pillow_is_safe
# The guard reads the Pillow that is imported; it must be pip's pick.
assert PIL.__version__ == os.environ["PINNED"], (PIL.__version__, os.environ["PINNED"])
fixed = int(PIL.__version__.split(".")[0]) >= FIXED_PILLOW_MAJOR
assert pillow_is_safe() is fixed, (PIL.__version__, pillow_is_safe())
print("Pillow", PIL.__version__, "decodes images:", fixed)
PY
- name: Audit it (pip-audit)
if: steps.gate.outputs.run == 'true'
run: |
uvx pip-audit==2.10.1 -r published.txt --no-deps --disable-pip \
--format json -o audit.json || true
python - <<'PY'
import json
deps = json.load(open("audit.json"))["dependencies"]
findings = [(d["name"], d["version"], v) for d in deps for v in d.get("vulns", [])]
guarded = [
f for f in findings
# The guard turns off all decoding below Pillow 13, whatever the fix.
if f[0].lower() == "pillow" and int(f[1].split(".")[0]) < 13
]
for name, ver, v in findings:
note = " (guarded: decoder_guard)" if (name, ver, v) in guarded else ""
print(f"{name} {ver} {v['id']} fix {v['fix_versions']}{note}")
assert len(deps) > 50, "pip-audit produced no dependency list"
if len(findings) > len(guarded):
raise SystemExit("Unguarded advisories in the pip-installed set; see above.")
PY
# ---- SCA: Rust dependency advisories -----------------------------------
# `cargo audit` reads Cargo.lock only (no build, about a minute), so it runs
@@ -104,9 +200,58 @@ jobs:
- uses: actions/setup-node@v7
with:
node-version: ">=24.16.0 <25"
# A directory may hold npm-audit-exceptions.json for advisories in copies
# bundled inside a package, which overrides cannot replace. A listed
# advisory is accepted only at its listed path, only while the lock has
# that exact version there as a bundled copy, and only until `expires`.
# Any other finding fails, and so does an entry that no longer matches.
- name: Audit locked dependencies at every severity
working-directory: ${{ matrix.directory }}
run: npm audit --package-lock-only --audit-level=low
run: |
if [ ! -f npm-audit-exceptions.json ]; then
npm audit --package-lock-only --audit-level=low
exit
fi
npm audit --package-lock-only --audit-level=low || true
npm audit --package-lock-only --json > "$RUNNER_TEMP/audit.json" || true
python3 - "$RUNNER_TEMP/audit.json" <<'PY'
import datetime
import json
import sys
exceptions = json.load(open("npm-audit-exceptions.json"))
if datetime.date.today().isoformat() > exceptions["expires"]:
sys.exit(f"npm-audit-exceptions.json expired on {exceptions['expires']}: recheck upstream.")
allowed = exceptions["advisories"] # {advisory: {lock path: bundled version}}
locked = json.load(open("package-lock.json"))["packages"]
vulns = json.load(open(sys.argv[1])).get("vulnerabilities", {})
seen, unexpected = set(), []
for name, vuln in vulns.items():
for via in vuln["via"]:
if isinstance(via, str):
# Inherited: its advisories are checked on that package's
# own entry, which therefore has to be in the report.
if via not in vulns:
unexpected.append(f"{name} via {via} (no entry for {via})")
continue
advisory = via["url"].rsplit("/", 1)[-1]
for node in vuln["nodes"]:
entry = locked.get(node, {})
pinned = allowed.get(advisory, {}).get(node)
if pinned and entry.get("version") == pinned and entry.get("inBundle"):
seen.add((advisory, node))
else:
found = f"{entry.get('version')}{' bundled' if entry.get('inBundle') else ''}"
unexpected.append(f"{advisory} {node} {found} ({via['severity']})")
stale = [f"{a} {n}" for a, nodes in allowed.items() for n in nodes if (a, n) not in seen]
for line in unexpected:
print("NOT EXCEPTED:", line)
for line in stale:
print("STALE EXCEPTION (fixed? remove it):", line)
if unexpected or stale:
sys.exit(1)
print(f"Only excepted bundled advisories remain ({len(seen)}), until {exceptions['expires']}.")
PY
# ---- SAST: CodeQL static analysis ------------------------------------
codeql:
Generated
+6 -16
View File
@@ -1351,9 +1351,9 @@ dependencies = [
[[package]]
name = "ctutils"
version = "0.4.2"
version = "0.4.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7d5515a3834141de9eafb9717ad39eea8247b5674e6066c404e8c4b365d2a29e"
checksum = "38d28fb6aa7dd680b3ffd1a3e64e115c177bdba63c0ae7f9cd48129ff05c4fa0"
dependencies = [
"cmov",
]
@@ -2098,7 +2098,7 @@ dependencies = [
"tracing-subscriber",
"url",
"uuid",
"webpki-roots 1.0.10",
"webpki-roots",
"wiremock",
]
@@ -2298,7 +2298,7 @@ dependencies = [
"tokio",
"tokio-rustls",
"tower-service",
"webpki-roots 1.0.10",
"webpki-roots",
]
[[package]]
@@ -3835,7 +3835,7 @@ dependencies = [
"wasm-bindgen-futures",
"wasm-streams",
"web-sys",
"webpki-roots 1.0.10",
"webpki-roots",
]
[[package]]
@@ -4642,7 +4642,6 @@ dependencies = [
"tokio",
"tokio-rustls",
"tungstenite 0.30.0",
"webpki-roots 0.26.11",
]
[[package]]
@@ -5084,7 +5083,7 @@ dependencies = [
"socks",
"ureq-proto",
"utf8-zero",
"webpki-roots 1.0.10",
"webpki-roots",
]
[[package]]
@@ -5312,15 +5311,6 @@ dependencies = [
"wasm-bindgen",
]
[[package]]
name = "webpki-roots"
version = "0.26.11"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "521bc38abb08001b01866da9f51eb7c5d647a19260e00054a8c7fd5f9e57f7a9"
dependencies = [
"webpki-roots 1.0.10",
]
[[package]]
name = "webpki-roots"
version = "1.0.10"
+6 -1
View File
@@ -51,11 +51,16 @@ COPY headroom/ headroom/
# `headroom proxy --backend`, including Bedrock temporary/SSO credentials.
# Those credentials require botocore (GH #1551), supplied by [bedrock].
ARG HEADROOM_EXTRAS=proxy,code,bedrock
# `uv pip install` ignores [tool.uv] override-dependencies (uv.lock only), so
# pass them explicitly: the image gets the security overrides the lock has
# (pillow 13 over fastembed's <13 cap). Python 3.10 has no tomllib: pip's
# vendored tomli reads the file there.
RUN --mount=type=cache,target=/root/.cache/uv \
--mount=type=cache,target=/usr/local/cargo/registry \
--mount=type=cache,target=/usr/local/cargo/git \
--mount=type=cache,target=/build/target \
uv pip install --system ".[${HEADROOM_EXTRAS}]"
python -c "exec('try: import tomllib\\nexcept ImportError: from pip._vendor import tomli as tomllib'); print('\\n'.join(tomllib.load(open('pyproject.toml', 'rb'))['tool']['uv']['override-dependencies']))" > /tmp/overrides.txt && \
uv pip install --system --overrides /tmp/overrides.txt ".[${HEADROOM_EXTRAS}]"
RUN --mount=type=bind,source=.,target=/context,readonly \
HEADROOM_BUILD_VERSION="${HEADROOM_BUILD_VERSION}" PYTHON_SITE_PACKAGES="${PYTHON_SITE_PACKAGES}" python - <<'PY'
+3 -6
View File
@@ -183,13 +183,10 @@ back at you, and deep reasoning spent on routine steps like reading a file.
Headroom trims it from the proxy, with no change to your code:
- **Verbosity steering** appends a short "be terse, don't restate context" note to the *end* of the system prompt, so your prompt cache still hits.
- **Effort routing** dials thinking effort down when a turn is only the model resuming after a tool result — a file read, a passing test. New questions and errors keep full effort.
Both apply to Anthropic `/v1/messages` and to OpenAI-compatible
`/v1/chat/completions` and `/v1/responses`. Effort routing uses
`reasoning_effort` on OpenAI and `thinking.budget_tokens` / `output_config.effort`
on Anthropic, with the same clamp-only invariant and the same `output_shaper:*`
labels on both paths.
It applies to Anthropic `/v1/messages` and to OpenAI-compatible
`/v1/chat/completions` and `/v1/responses`, with the same `output_shaper:*`
labels on all paths.
```bash
export HEADROOM_OUTPUT_SHAPER=1 # off by default
@@ -1532,35 +1532,50 @@ impl LogCompressor {
let omitted = all_lines.len().saturating_sub(selected.len());
if omitted > 0 {
// Keep public stats as input totals; describe only dropped identities here.
let mut omitted_levels = [0u64; 4];
for line in all_lines {
if selected_numbers.contains(&line.line_number) {
continue;
}
match line.level {
LogLevel::Error => omitted_levels[0] += 1,
LogLevel::Fail => omitted_levels[1] += 1,
LogLevel::Warn => omitted_levels[2] += 1,
LogLevel::Info => omitted_levels[3] += 1,
_ => {}
}
}
let mut summary_parts: Vec<String> = Vec::new();
for (label, key) in [
("ERROR", "errors"),
("FAIL", "fails"),
("WARN", "warnings"),
("INFO", "info"),
for (label, n) in [
("ERROR", omitted_levels[0]),
("FAIL", omitted_levels[1]),
("WARN", omitted_levels[2]),
("INFO", omitted_levels[3]),
] {
let n = stats.get(key).copied().unwrap_or(0);
if n > 0 {
summary_parts.push(format!("{} {}", n, label));
}
}
if !summary_parts.is_empty() {
let omitted_names = if omitted_short_summary_ids.is_empty() {
String::new()
let omitted_names = if omitted_short_summary_ids.is_empty() {
String::new()
} else {
let shown = omitted_short_summary_ids
.iter()
.take(5)
.copied()
.collect::<Vec<_>>()
.join(", ");
let overflow = omitted_short_summary_ids.len().saturating_sub(5);
if overflow > 0 {
format!("; omitted: {shown}, +{overflow} more")
} else {
let shown = omitted_short_summary_ids
.iter()
.take(5)
.copied()
.collect::<Vec<_>>()
.join(", ");
let overflow = omitted_short_summary_ids.len().saturating_sub(5);
if overflow > 0 {
format!("; omitted: {shown}, +{overflow} more")
} else {
format!("; omitted: {shown}")
}
};
format!("; omitted: {shown}")
}
};
if summary_parts.is_empty() {
output.push(format!("[{} lines omitted{}]", omitted, omitted_names));
} else {
output.push(format!(
"[{} lines omitted: {}{}]",
omitted,
@@ -1963,12 +1978,6 @@ mod tests {
let (output, _) = c.format_output(&selected, &parsed);
assert!(!output.contains("; omitted: "));
if !keep_summary_lines {
assert_eq!(
output,
"FAILED outside.py::test_0\nFAILED outside.py::test_9\nERROR outside.py::test_10\nERROR outside.py::test_19\n[67 lines omitted: 10 ERROR, 10 FAIL, 51 INFO]"
);
}
}
}
@@ -2366,7 +2375,79 @@ mod tests {
}
#[test]
fn format_output_emits_summary_with_omitted_count() {
fn omitted_marker_counts_only_dropped_lines_on_live_path() {
let mut lines = (0..400)
.map(|i| format!("INFO worker processed item {i}"))
.collect::<Vec<_>>();
let error = "ERROR worker failed: connection reset";
lines.insert(200, error.to_string());
let c = LogCompressor::new(LogCompressorConfig {
enable_ccr: false,
..Default::default()
});
let (result, _) = c.compress(&lines.join("\n"), 1.0);
let marker = result
.compressed
.lines()
.find(|line| line.contains("lines omitted:"))
.expect("large input must have omitted lines");
let pattern = Regex::new(r"(\d+) (ERROR|FAIL|WARN|INFO)").unwrap();
let mut level_counts = pattern.captures_iter(marker);
let count = level_counts.next().expect("omitted INFO count");
assert!(result.compressed.lines().any(|line| line == error));
assert_eq!(&count[2], "INFO");
assert_eq!(
count[1].parse::<usize>().unwrap(),
result.original_line_count - result.compressed_line_count
);
assert!(level_counts.next().is_none());
assert_eq!(
marker,
format!("[{} lines omitted: {} INFO]", &count[1], &count[1])
);
assert_eq!(result.stats["errors"], 1);
assert_eq!(result.stats["info"], 400);
}
#[test]
fn omitted_non_severity_lines_keep_count_notice_on_live_path() {
use std::fmt::Write as _;
let count_pattern = Regex::new(r"(?m)^\[(\d+) lines omitted[^\]]*\]$").unwrap();
let level_pattern = Regex::new(r"\d+ (ERROR|FAIL|WARN|INFO)\b").unwrap();
let error = "ERROR retained failure";
for prefix in ["DEBUG ", "TRACE ", ""] {
let mut input = String::with_capacity(4096);
for i in 0..100 {
writeln!(input, "{prefix}progress step {i}").unwrap();
}
input.push_str(error);
let c = LogCompressor::new(LogCompressorConfig {
enable_ccr: false,
..Default::default()
});
let (result, _) = c.compress(&input, 1.0);
let marker = count_pattern
.captures(&result.compressed)
.expect("dropped lines must retain an omission count");
assert_eq!(
marker[1].parse::<usize>().unwrap(),
result.original_line_count - result.compressed_line_count
);
assert!(!level_pattern.is_match(marker.get(0).unwrap().as_str()));
assert_eq!(
marker.get(0).unwrap().as_str(),
format!("[{} lines omitted]", &marker[1])
);
assert!(result.compressed.lines().any(|line| line == error));
assert_eq!(result.stats["errors"], 1);
assert_eq!(result.stats["total"], 101);
}
}
#[test]
fn format_output_preserves_input_totals() {
let c = cmp();
let all_lines = vec![
LogLine::new(0, "ERROR a"),
@@ -2388,9 +2469,9 @@ mod tests {
.collect::<Vec<_>>();
let selected = vec![all_lines[0].clone()];
let (output, stats) = c.format_output(&selected, &all_lines);
assert!(output.contains("[3 lines omitted: 1 ERROR, 1 WARN, 2 INFO]"));
assert_eq!(stats["errors"], 1);
assert_eq!(stats["info"], 2);
assert_eq!(output, "ERROR a\n[3 lines omitted: 1 WARN, 2 INFO]");
}
#[test]
@@ -2415,11 +2496,9 @@ mod tests {
} else {
String::new()
};
assert!(
output.ends_with(&format!(
"[{count} lines omitted: {count} FAIL, 1 INFO; omitted: {shown}{overflow}]"
)),
"{output}"
assert_eq!(
output.lines().last().unwrap(),
format!("[{count} lines omitted: {count} FAIL; omitted: {shown}{overflow}]")
);
}
}
@@ -2442,11 +2521,9 @@ mod tests {
];
let (output, stats) = cmp().format_output(&selected, &all_lines);
assert!(
output.ends_with(
"[3 lines omitted: 1 ERROR, 3 FAIL, 1 INFO; omitted: tests/test_ids.py::test_error, tests/test_ids.py::test_repeat, tests/test_ids.py::test_repeat]"
),
"{output}"
assert_eq!(
output.lines().last().unwrap(),
"[3 lines omitted: 1 ERROR, 2 FAIL; omitted: tests/test_ids.py::test_error, tests/test_ids.py::test_repeat, tests/test_ids.py::test_repeat]"
);
assert_eq!(stats["errors"], 1);
assert_eq!(stats["fails"], 3);
@@ -2482,26 +2559,12 @@ mod tests {
);
let (output, _) = c.format_output(&selected, &all_lines);
assert!(
output.ends_with(
"[4 lines omitted: 4 FAIL, 1 INFO; omitted: tests/test_ids.py::test_1, tests/test_ids.py::test_2]"
),
"{output}"
assert_eq!(
output.lines().last().unwrap(),
"[4 lines omitted: 2 FAIL, 1 INFO; omitted: tests/test_ids.py::test_1, tests/test_ids.py::test_2]"
);
}
#[test]
fn format_output_marker_is_unchanged_without_omitted_short_summary_entries() {
let c = cmp();
let mut error = LogLine::new(0, "ERROR a");
error.level = LogLevel::Error;
let mut info = LogLine::new(1, "INFO b");
info.level = LogLevel::Info;
let (output, _) = c.format_output(&[error.clone()], &[error, info]);
assert_eq!(output, "ERROR a\n[1 lines omitted: 1 ERROR, 1 INFO]");
}
#[test]
fn score_line_caps_at_one_point_zero() {
let line = LogLine {
+5 -2
View File
@@ -26,7 +26,10 @@ tracing-subscriber = { version = "0.3", features = ["json", "env-filter", "fmt"]
# roots (Zscaler, Netskope, ...) are installed in the OS store, never in
# Mozilla's list, so webpki alone rejects every re-signed upstream certificate.
reqwest = { version = "0.12", default-features = false, features = ["stream", "rustls-tls", "rustls-tls-native-roots", "http2"] }
tokio-tungstenite = { version = "0.30", default-features = false, features = ["connect", "rustls-tls-webpki-roots", "rustls-tls-native-roots"] }
# websocket.rs always supplies tls::websocket_tls_config(), which loads our
# direct webpki-roots 1.x dependency plus native/additive roots. Do not enable
# tungstenite's unused default webpki store: it pulls the obsolete 0.26 shim.
tokio-tungstenite = { version = "0.30", default-features = false, features = ["connect", "rustls-tls-native-roots"] }
clap = { workspace = true, features = ["derive", "env"] }
serde = { workspace = true }
serde_json = { workspace = true }
@@ -122,7 +125,7 @@ tokio-rustls = { version = "0.26", default-features = false, features = ["ring",
# is the generator rustls' own test-suite uses; dev-only, never shipped.
rcgen = { version = "0.14", default-features = false, features = ["ring", "pem"] }
reqwest = { version = "0.12", default-features = false, features = ["stream", "rustls-tls", "http2", "json"] }
tokio-tungstenite = { version = "0.30", default-features = false, features = ["connect", "rustls-tls-webpki-roots"] }
tokio-tungstenite = { version = "0.30", default-features = false, features = ["connect", "rustls-tls-native-roots"] }
futures-util = "0.3"
tokio = { workspace = true, features = ["macros", "rt-multi-thread", "signal", "net", "io-util", "time", "test-util", "process"] }
hyper = { version = "1", features = ["server", "http1", "http2"] }
+8
View File
@@ -7,6 +7,11 @@ services:
tty: true
environment:
HOME: /tmp/headroom-home
# Docker creates /tmp/headroom-home as root:root, so $HOME is not
# writable by the --user the container runs as (issue #4207). Keep the
# HuggingFace/XDG caches on the bind-mounted workspace instead.
HF_HOME: /tmp/headroom-home/.headroom/cache/huggingface
XDG_CACHE_HOME: /tmp/headroom-home/.headroom/cache
# Canonical Headroom filesystem contract (issue #175). Forwarded into
# the container so the proxy resolves state/config to the bind-mounted
# /tmp/headroom-home/.headroom path. HEADROOM_WORKSPACE (above) remains
@@ -28,6 +33,9 @@ services:
restart: unless-stopped
environment:
HOME: /tmp/headroom-home
# See the `cli` service above (issue #4207).
HF_HOME: /tmp/headroom-home/.headroom/cache/huggingface
XDG_CACHE_HOME: /tmp/headroom-home/.headroom/cache
HEADROOM_HOST: 0.0.0.0
HEADROOM_PROXY_TOKEN: ${HEADROOM_PROXY_TOKEN:-}
# The container binds 0.0.0.0 so the loopback publication below can reach
@@ -0,0 +1,40 @@
# ADR 0001: Main and release branch semantics
- Status: Accepted
- Date: 2026-08-13
## Context
Headroom currently develops and releases from `main`. The target lifecycle needs
`main` to continue moving while an exact source revision is qualified. A branch
name alone is not evidence, and creating a `release` branch before qualification
is authoritative would make unqualified code appear publishable.
## Decision
`main` remains the default integration branch and the target for ordinary pull
requests. The future protected `release` branch represents qualified source. It
may receive only an ancestry-preserving promotion of an exact Gate-A-qualified
`main` SHA, a verified metadata-only Release Please change, an authorized hotfix,
or release-control maintenance.
Promotion must leave the qualified candidate SHA reachable from `release`.
Squash and rebase merges are therefore forbidden for promotion pull requests.
Normal pull requests into `main` may retain the repository's usual merge policy.
The first `release` branch must be created from an exact SHA with a passing,
unrevoked qualification manifest. Branch creation, protection, lifecycle
activation, and publication credentials remain explicit administrator actions.
They are not performed by this contract-only change.
Gate A admits source to `release`. Gate B independently authorizes publication
of final distribution bytes. Neither branch membership nor a tag or GitHub
Release substitutes for either gate.
## Consequences
Release Please will eventually watch `release`, but only after the qualification
controller and migration guard are operational. Promotion automation must use an
ancestry-preserving merge. A hotfix made on `release` requires qualification and
forward synchronization to `main`; `release` must not become a second development
branch.
@@ -0,0 +1,35 @@
# ADR 0002: Release artifact identity and provenance
- Status: Accepted
- Date: 2026-08-13
## Context
Rebuilding a moving source reference can produce different bytes. Source identity
alone cannot prove what qualification tested or what publication shipped.
## Decision
Every candidate is bound to an exact full Git commit SHA and an immutable artifact
identified by SHA-256, filename, package name, version, size, and build-run
identity. When runtime behavior comes from a payload that can differ from package
bytes, its SHA-256 is recorded separately.
Evidence documents are themselves immutable bytes with a SHA-256 and an opaque
URI. A producer identity records repository, workflow, run ID, attempt, and the
producer commit. Cross-repository consumers verify the digest before processing
the artifact or evidence. Secrets and credentials are never evidence fields.
The candidate artifact is built once. Downstream deterministic, integration, and
benchmark lanes consume those exact bytes; they do not rebuild `main` and reuse
the candidate identity. Final Gate B compares published bytes with the qualified
artifact or applies an explicitly approved, policy-versioned runtime-payload
equivalence rule.
## Consequences
Artifact stores and workflow runs require immutable retention sufficient for
audit. A digest, source SHA, schema version, or producer mismatch makes evidence
`inconclusive` or `fail` according to policy; it can never pass silently. Future
controllers must enforce equality across documents in addition to validating
each document's JSON Schema.
+37
View File
@@ -0,0 +1,37 @@
# ADR 0003: A1 versus B is the release benchmark claim
- Status: Accepted
- Date: 2026-08-13
## Context
Comparing Headroom against a direct provider path changes more than compression
and cannot isolate Headroom's effect. Release evidence needs a paired comparison
whose intended difference is only optimization state.
## Decision
The headline release comparison is:
- A1 (`a1_passthrough`): the Headroom proxy and candidate artifact with
optimization disabled.
- B (`b_headroom`): the same Headroom proxy and candidate artifact with
optimization enabled.
A1 and B must have equal candidate source SHA, artifact digest, rollout registry
and snapshot digests, model, agent, taskset, environment image, and resource
limits. Tasks are paired, arm order is randomized, and the versioned policy sets
repeat count and statistical decision rules. A direct-provider A0 arm may be
recorded for diagnosis but is not the headline comparator.
The benchmark producer reports an explicit identity-verification verdict. Any
identity mismatch makes the experiment and release evidence inconclusive. JSON
Schema constrains the arm shapes and intended optimization states; the benchmark
worker and qualification controller must enforce equality between arms.
## Consequences
A single noisy run is not hard release evidence. Missing telemetry, provider
outages, unequal environments, or identity drift remain visible and cannot be
coerced into `pass`. Accuracy, savings, latency, reliability, and missing-data
rules live in versioned policy rather than workflow shell code.
@@ -0,0 +1,38 @@
# ADR 0004: Black-box release benchmark boundary
- Status: Accepted
- Date: 2026-08-13
## Context
Internal unit and compression tests are necessary but do not prove that the
packaged proxy preserves real agent, streaming, and tool-use behavior. Conversely,
benchmark infrastructure must not gain release credentials or execute arbitrary
release commands.
## Decision
Release benchmarks exercise Headroom through its supported public protocol and
observable provenance surfaces, using the immutable candidate artifact. They
record taskset revision and digest, model and agent identities, environment,
resource limits, rollout snapshot, artifact digest, attempts, telemetry
completeness, and raw-result identity.
The benchmark repository receives only the minimum candidate and experiment
identities needed to run. It verifies artifact digests before installation and
returns an immutable result reference with authenticated producer identity. It
does not receive provider secrets through release evidence, package-publish
credentials, or permission to mutate the Headroom repository.
Failures and cancellations preserve terminal evidence. A provider or
infrastructure failure is `inconclusive`, not a candidate pass and not necessarily
a candidate-caused failure. The qualification controller applies the registered
policy to the returned reference; callback identity alone does not establish a
passing result.
## Consequences
Hermetic PR simulators, scheduled live smoke tests, and release-candidate lanes
can share one result shape while retaining their execution depth. Cross-repository
authentication, artifact transport, callback authorization, and retention need
separate implementation and security review in later PRs.
@@ -0,0 +1,40 @@
# ADR 0005: Release overrides and fail-closed policy
- Status: Accepted
- Date: 2026-08-13
## Context
Headroom product transforms may fail open to preserve requests, but release
control makes a different safety decision: publication must not proceed without
complete, matching, current evidence. Operational exceptions still need an
auditable representation.
## Decision
Release evidence uses exactly four policy statuses: `pass`, `fail`,
`inconclusive`, and `skipped_by_policy`. Missing, stale, invalid, mismatched,
revoked, unauthorized, or schema-incompatible required evidence cannot produce
`pass`. `skipped_by_policy` is allowed only when the selected policy version does
not require that evidence.
Policy is versioned data. It maps risk classes to required Gate A and Gate B
evidence and deterministic rules. Missing-data behavior is `inconclusive`.
Thresholds and exceptions are not embedded as ad hoc workflow conditions.
An override records a unique ID, narrow scope, reason, human approver, approval
time, expiry, and optional ticket URI. It never contains credentials. Controllers
authenticate the approver, reject expired or unauthorized overrides, and include
accepted overrides in the gate result. An unsafe runtime rollout override makes
the rollout qualification-ineligible and cannot be overridden into a release
pass by this mechanism.
Qualification revocation is explicit, immutable evidence linked to the original
qualification. A revoked qualification cannot authorize promotion or publication.
## Consequences
The stable GitHub check will be named `release-policy` even when risk-specific
evidence varies. Workflow code remains a thin adapter around a tested policy
evaluator. Operational urgency stays visible to reviewers instead of silently
weakening the evidence chain.
+12 -12
View File
@@ -15,7 +15,7 @@
"fumadocs-typescript": "^5.5.1",
"fumadocs-ui": "16.17.1",
"lucide-react": "^1.48.0",
"next": "^16.4.0",
"next": "^16.4.3",
"react": "^19.3.0",
"react-dom": "^19.3.0",
"recharts": "^3.10.1",
@@ -193,23 +193,23 @@
"@mdx-js/mdx": ["@mdx-js/mdx@3.1.1", "", { "dependencies": { "@types/estree": "^1.0.0", "@types/estree-jsx": "^1.0.0", "@types/hast": "^3.0.0", "@types/mdx": "^2.0.0", "acorn": "^8.0.0", "collapse-white-space": "^2.0.0", "devlop": "^1.0.0", "estree-util-is-identifier-name": "^3.0.0", "estree-util-scope": "^1.0.0", "estree-walker": "^3.0.0", "hast-util-to-jsx-runtime": "^2.0.0", "markdown-extensions": "^2.0.0", "recma-build-jsx": "^1.0.0", "recma-jsx": "^1.0.0", "recma-stringify": "^1.0.0", "rehype-recma": "^1.0.0", "remark-mdx": "^3.0.0", "remark-parse": "^11.0.0", "remark-rehype": "^11.0.0", "source-map": "^0.7.0", "unified": "^11.0.0", "unist-util-position-from-estree": "^2.0.0", "unist-util-stringify-position": "^4.0.0", "unist-util-visit": "^5.0.0", "vfile": "^6.0.0" } }, ""],
"@next/env": ["@next/env@16.4.0", "", {}, "sha512-pyLlT5oafGlX8X7xjgGNXz5dNIDSxREm+qD6i9VLSZiZFopA/XWl8NM/KPmLx/8EG/++c49iid3gNWSQW1+2dQ=="],
"@next/env": ["@next/env@16.4.3", "", {}, "sha512-a7tz1QCcWWkwC/rPJcPMJk/UNRu9CFhDd3OHYE5hddbJrs8BqRTalxI6GlKCWEGzRLHN+S/B7a4PAHCtm25aBQ=="],
"@next/swc-darwin-arm64": ["@next/swc-darwin-arm64@16.4.0", "", { "os": "darwin", "cpu": "arm64" }, "sha512-yyZ+9MgViAKLLb5l1gPBGjRwnq3teNLb5Zx6JEw8LzNSTjlsnp+baUHFxTgl7PpjCmKf48VQfyipG1eBflb48Q=="],
"@next/swc-darwin-arm64": ["@next/swc-darwin-arm64@16.4.3", "", { "os": "darwin", "cpu": "arm64" }, "sha512-4yq5EXBt+VDtAZwTyfijaFp5D2C5oz3Ikw5a2kiX2K9nw72vrZX2q5UuAlkPtUMO1tQz6JTKpaKWjS7OOefTDQ=="],
"@next/swc-darwin-x64": ["@next/swc-darwin-x64@16.4.0", "", { "os": "darwin", "cpu": "x64" }, "sha512-RePEEejEj1Auf5s9qEcG0JbcDP3ceNUS/ofNX8AhxzgIjTVlZIHMatlp16YplcSMpsVo/ZMQHJTjbMYJznjGUg=="],
"@next/swc-darwin-x64": ["@next/swc-darwin-x64@16.4.3", "", { "os": "darwin", "cpu": "x64" }, "sha512-1Rvkn/LUhnEF8WxnRkOrqGhbwXui1bkWFxONKIbN+r7C+9KHDSZ+iUoj4CzymVMWUyZIyx9szcb9+kbKhD500A=="],
"@next/swc-linux-arm64-gnu": ["@next/swc-linux-arm64-gnu@16.4.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-HhsyCqd+NpmvDDVY/LqkAN24f+QVvXh3ie+PfcwKinWL2Mu826JymQxJXGjAIfmJ4VlHjp4Pe/nZtXtUoEMAqw=="],
"@next/swc-linux-arm64-gnu": ["@next/swc-linux-arm64-gnu@16.4.3", "", { "os": "linux", "cpu": "arm64" }, "sha512-dCKpXErGg3abUM6t5JTJV/ottVBTStJB5lRJTbgdUdQaQ+jNHiK56Hsc0YAEg/rinSh42hYG3HWiYmEMdilnxg=="],
"@next/swc-linux-arm64-musl": ["@next/swc-linux-arm64-musl@16.4.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-sN9Pf+Zh+RpZAOmbR7d8KAA8T61CVhawtbEJ2Bk6QrRzx6Z/6haaF4UiwBzytM96GRRRWZh9/WALIEO3npMamA=="],
"@next/swc-linux-arm64-musl": ["@next/swc-linux-arm64-musl@16.4.3", "", { "os": "linux", "cpu": "arm64" }, "sha512-WwYbhWkhYBvBtib1K4W0kL8MW2snBD2A5b3SN4vPpqalZbZs5+bQ1yzAdepVoOqrFfEW3dmREy4Zs1MrWcrFbw=="],
"@next/swc-linux-x64-gnu": ["@next/swc-linux-x64-gnu@16.4.0", "", { "os": "linux", "cpu": "x64" }, "sha512-D5M5xLWQVd1CvR+L7BickM1weRfmM41x3L1NWcnKY/oyJJqr1qwaCgmu3dMAhLBOMdZwSuDCRV6DJRRpiUkbDQ=="],
"@next/swc-linux-x64-gnu": ["@next/swc-linux-x64-gnu@16.4.3", "", { "os": "linux", "cpu": "x64" }, "sha512-QymWvfUwDEC5/lpJOsxX5VAbyoR2D13+2Jsjz4be7gT4LPqEgdpkeLIR/HFfCLgKzoMhpJbp6I/JnogyNZHcaA=="],
"@next/swc-linux-x64-musl": ["@next/swc-linux-x64-musl@16.4.0", "", { "os": "linux", "cpu": "x64" }, "sha512-8d5WLS6a9YalqpOgXdlbvonFu+sIgjA+CO6tGzetrpPVcUL56foa7B7664h41rAlbLi5fJwK4vWji3zf4QDy+w=="],
"@next/swc-linux-x64-musl": ["@next/swc-linux-x64-musl@16.4.3", "", { "os": "linux", "cpu": "x64" }, "sha512-Vmjd9D7DpA4Vv3cUlr82QWgJD/BQZmns801vtC5VWHg6jCIA4a5vMKpQnfrM2pyCrp2eV0ENdUg4PlN3bAc2Yw=="],
"@next/swc-win32-arm64-msvc": ["@next/swc-win32-arm64-msvc@16.4.0", "", { "os": "win32", "cpu": "arm64" }, "sha512-sQuOIiW3snb48UwrBcDMvFA/u03qtw2LeuSIxFIQ9AJuW9UG/4Ddsfo+eV73PnZwBhyncMtsKVh7PrzMol2/fA=="],
"@next/swc-win32-arm64-msvc": ["@next/swc-win32-arm64-msvc@16.4.3", "", { "os": "win32", "cpu": "arm64" }, "sha512-lG1pPdPLk7gTyGb00n5JIMLdBJgjb+UEhSdZvFbhUMg0DyC6z4B7RnpSKF9VCd4imkLObVbXOFA0kFCpw7yFow=="],
"@next/swc-win32-x64-msvc": ["@next/swc-win32-x64-msvc@16.4.0", "", { "os": "win32", "cpu": "x64" }, "sha512-6/33lCuxpdHUy27RegyGM/5uTpF7YZd3UR4D0gpkOA/tWY5YR7msbQjqPgCZmSmxrrTLGCXYA4A8vT2H5DPGTQ=="],
"@next/swc-win32-x64-msvc": ["@next/swc-win32-x64-msvc@16.4.3", "", { "os": "win32", "cpu": "x64" }, "sha512-NmQC9RkJdnPXRaMxtkCzobB3teVjqF33oSOnwDfi+XYGWWYpt+xlGK3mtktSKLbdjwaWbJu2OkkMiRFGUUncKg=="],
"@radix-ui/number": ["@radix-ui/number@1.1.3", "", {}, "sha512-Road2bidD0uu/1BGDOWNdPI06g0lIRy6IF9GZcIrDK2KGItfor8IQwQa+yM2ERgHM1MmHxaxpTzk0/Jp42lNfA=="],
@@ -781,7 +781,7 @@
"nanoid": ["nanoid@3.3.20", "", { "bin": { "nanoid": "bin/nanoid.cjs" } }, "sha512-uKdg2G3GNCKQn9byYOpxbGqrT2fGO5KRt5J/8b3pok8rT6qxGWF6hxMyJiEYtAf+FVyYuD9hRaDqX5uPFYJ4ZQ=="],
"next": ["next@16.4.0", "", { "dependencies": { "@next/env": "16.4.0", "@swc/helpers": "0.5.23", "baseline-browser-mapping": "^2.9.19", "caniuse-lite": "^1.0.30001579", "postcss": "8.5.23", "styled-jsx": "5.1.6" }, "optionalDependencies": { "@next/swc-darwin-arm64": "16.4.0", "@next/swc-darwin-x64": "16.4.0", "@next/swc-linux-arm64-gnu": "16.4.0", "@next/swc-linux-arm64-musl": "16.4.0", "@next/swc-linux-x64-gnu": "16.4.0", "@next/swc-linux-x64-musl": "16.4.0", "@next/swc-win32-arm64-msvc": "16.4.0", "@next/swc-win32-x64-msvc": "16.4.0", "sharp": "^0.35.4" }, "peerDependencies": { "@opentelemetry/api": "^1.1.0", "@playwright/test": "^1.51.1", "babel-plugin-react-compiler": "*", "react": "^18.2.0 || 19.0.0-rc-de68d2f4-20241204 || ^19.0.0", "react-dom": "^18.2.0 || 19.0.0-rc-de68d2f4-20241204 || ^19.0.0", "sass": "^1.3.0" }, "optionalPeers": ["@opentelemetry/api", "@playwright/test", "babel-plugin-react-compiler", "sass"], "bin": { "next": "dist/bin/next" } }, "sha512-N2C+9q89Z/oLrsepSRS4jRMtwmUZAoZuAHU0e9T6+sAB5DdhADmrnOW+zjYijlrYFmVfmQhGVGy9eMFoB7UgKg=="],
"next": ["next@16.4.3", "", { "dependencies": { "@next/env": "16.4.3", "@swc/helpers": "0.5.23", "baseline-browser-mapping": "^2.9.19", "caniuse-lite": "^1.0.30001579", "postcss": "8.5.23", "styled-jsx": "5.1.6" }, "optionalDependencies": { "@next/swc-darwin-arm64": "16.4.3", "@next/swc-darwin-x64": "16.4.3", "@next/swc-linux-arm64-gnu": "16.4.3", "@next/swc-linux-arm64-musl": "16.4.3", "@next/swc-linux-x64-gnu": "16.4.3", "@next/swc-linux-x64-musl": "16.4.3", "@next/swc-win32-arm64-msvc": "16.4.3", "@next/swc-win32-x64-msvc": "16.4.3", "sharp": "^0.35.5" }, "peerDependencies": { "@opentelemetry/api": "^1.1.0", "@playwright/test": "^1.51.1", "babel-plugin-react-compiler": "*", "react": "^18.2.0 || 19.0.0-rc-de68d2f4-20241204 || ^19.0.0", "react-dom": "^18.2.0 || 19.0.0-rc-de68d2f4-20241204 || ^19.0.0", "sass": "^1.3.0" }, "optionalPeers": ["@opentelemetry/api", "@playwright/test", "babel-plugin-react-compiler", "sass"], "bin": { "next": "dist/bin/next" } }, "sha512-OqxKTGi9u80FydydsMNYNjnuje9Au+kvHlt2GZ//ftdpDHm1dxKqAaENoOOTX5wKzn+9vaKUNIfZeyZUuLhCnA=="],
"next-themes": ["next-themes@0.4.6", "", { "peerDependencies": { "react": "^16.8 || ^17 || ^18 || ^19 || ^19.0.0-rc", "react-dom": "^16.8 || ^17 || ^18 || ^19 || ^19.0.0-rc" } }, ""],
@@ -955,7 +955,7 @@
"zbsearch": ["zbsearch@4.0.1", "", {}, "sha512-lmnEEnb93QQcNv7qARDr7jBVPxYdZbZ9XdZ0dbZ0qaOvGne4jJMW4fjwPfVaUKQXv3FNWvGbDwRDgyaSb1pc8w=="],
"zod": ["zod@4.6.5", "", {}, "sha512-v5l/aFXZQeai4awLbOpSoHecE9UiMrnfx75tEXLjNonXVARxQ5mOeipTjROUchszUNCqnE+hqAMujRsRHsut2Q=="],
"zod": ["zod@4.6.7", "", {}, "sha512-g8W2D2kU6a8untc053fX1uVBKzM7yqAxW/3zwk83+6RyF2+SKOuV+c0wBDhUwzV1PaGapmZH+rmcUzPf+3CGwg=="],
"zwitch": ["zwitch@2.0.4", "", {}, ""],
+16 -1
View File
@@ -62,6 +62,19 @@ Headroom injects a `headroom_retrieve` tool into the LLM's available tools:
The LLM sees this tool alongside your application's tools and can call it whenever the compressed data is insufficient.
If your client already registers retrieval through MCP, Headroom keeps that
client-owned tool instead of adding a second bare `headroom_retrieve`.
Supported spellings include OpenCode's `headroom_headroom_retrieve` and MCP
wrappers such as `mcp__headroom__headroom_retrieve` and
`mcp_Headroom_headroom_retrieve`. The same rule applies to session-aware
injection and the per-request fallback, so Headroom does not advertise an
unavailable bare retrieval tool alongside the client's executable alias.
These ownership aliases are limited to the default `headroom` MCP server
name. An unrelated server such as `mcp__other__headroom_retrieve` does not
replace the proxy's retrieval tool. Optional CCR system instructions use
the executable name selected from the available tool definitions.
## Phase 3: Response Handler
When the LLM calls `headroom_retrieve`:
@@ -71,7 +84,9 @@ When the LLM calls `headroom_retrieve`:
3. The result is added to the conversation
4. The API call continues automatically
The client never sees CCR tool calls on the Anthropic and OpenAI proxy paths; Headroom resolves them transparently there.
On the Anthropic and OpenAI proxy paths, only retrieval-only responses naming
the proxy's bare `headroom_retrieve` are resolved server-side. Mixed responses
and all MCP-registered retrieval aliases are forwarded for the client to execute.
<Callout type="warning" title="Gemini CCR boundary">
Buffered native Gemini requests resolve `headroom_retrieve` server-side and
+1 -1
View File
@@ -383,7 +383,7 @@ headroom proxy --learn --min-evidence 3
| `HEADROOM_TOIN_PATH` | Override TOIN telemetry file location. Always wins when set. | derived from `${HEADROOM_WORKSPACE_DIR}` |
| `HEADROOM_SUBSCRIPTION_STATE_PATH` | Override subscription tracker state file. Always wins when set. | derived from `${HEADROOM_WORKSPACE_DIR}` |
| `HEADROOM_PERIODIC_TOIN_STATS` | Controls periodic TOIN stats logging in long-lived proxy workers. Set to `0`, `false`, `off`, or `no` to disable the 5-minute stats loop without disabling TOIN learning or request-time feedback. | `true` |
| `HEADROOM_MEMORY_INJECTION_MODE` | Memory-context routing mode: `live_zone_tail` (default) or `disabled`. The legacy `system_prompt` mode was retired by PR-A2; supplying it raises. | `live_zone_tail` |
| `HEADROOM_MEMORY_INJECTION_MODE` | Memory-context routing mode: `live_zone_tail` (default), `disabled`, or `tool` (auto-injection off; the agent calls memory tools explicitly). The legacy `system_prompt` mode was retired by PR-A2; supplying it raises. | `live_zone_tail` |
| `HEADROOM_PROXY_PYTHON_FORWARDER_MODE` | Python forwarder serialization mode. `byte_faithful` (default) forwards original request bytes verbatim when no transform mutated the body and re-serializes canonically only when needed — keeps Anthropic prompt-cache hit-rate intact. `legacy_json_kwarg` is an explicit operator opt-in for emergency rollback to the historical `httpx ... json=body` behavior. NOT a fallback — only flip on explicit operator decision. | `byte_faithful` |
| `HEADROOM_STRIP_INTERNAL_HEADERS` | Python proxy: whether to strip internal `x-headroom-*` request headers (e.g. `x-headroom-bypass`, `x-headroom-mode`, `x-headroom-user-id`, `x-headroom-stack`, `x-headroom-base-url`) before every upstream forwarder call (PR-A5, fixes P5-49). `enabled` (default) stops fingerprinting / leakage. `disabled` is an explicit operator opt-in for diagnostic shadow tracing — NOT a fallback. Inbound reads of these headers (bypass gating, memory user-id resolution) are unaffected because they read `request.headers` directly. | `enabled` |
| `HEADROOM_PROXY_STRIP_INTERNAL_HEADERS` | Rust proxy: same policy as `HEADROOM_STRIP_INTERNAL_HEADERS` but for the Rust transparent proxy. Stripping happens inside `build_forward_request_headers` so both HTTP and WebSocket upstream calls are gated by one flag. `enabled` default; `disabled` operator opt-in for diagnostic shadow tracing. Response-side `X-Headroom-*` injection (e.g. `x-headroom-tokens-saved`) is unrelated and stays. | `enabled` |
+40 -8
View File
@@ -148,6 +148,35 @@ headroom proxy --codex-wire-debug
HEADROOM_COMPRESS_PASSTHROUGH=1 headroom proxy
```
Automatic memory lookup renders a separate, bounded embedding query:
| Input | Maximum characters |
| --- | ---: |
| Entire query, including delimiters | 4096 |
| Latest user message tail | 2048 |
| Each recent tool-output tail | 512 |
| Each recent assistant-turn tail | 512 |
These are source-size limits, not token estimates. The local ONNX and
sentence-transformers embedders then use their actual tokenizer and configured
input window, including special tokens. When both sources are present, they
reserve room for the question and context separately; unused space can go to
the other source. Newest tool evidence is at the end of the context so retaining
its tail does not silently discard it behind a long question.
Remote embedders that do not expose a local tokenizer retain the character
limits; these do not guarantee an arbitrary remote model's token window.
The raw `MemoryQuery` fields stay unchanged, and SDK callers that render without
a budget still receive the full sources.
Anthropic's pre-upstream lookup keeps its existing 2.0-second deadline,
configured by `ProxyConfig.anthropic_pre_upstream_memory_context_timeout_seconds`.
Bounding the input limits embedding work; it is not a guarantee against cold
model initialization or a slow embedding server. Memory failures include the
exception representation, so an otherwise empty timeout is identifiable as
`TimeoutError()`.
<Callout type="info" title="LLMLingua removed from the proxy CLI">
The old LLMLingua proxy toggles are no longer part of the CLI. Headroom's proxy compression path uses ContentRouter plus the current built-in compressors, including Kompress where applicable.
</Callout>
@@ -381,13 +410,16 @@ when they are enabled.
only, and so is every rotated backup (`proxy-8000.log.1`, …). This is not
conditional on which content switch is on. If the log path already exists as a
symlink, Headroom refuses to log rather than write through it, and says so.
- **Windows:** **Headroom does not restrict the log file.** Read access on NTFS is
decided by the file's ACL; `chmod` there only toggles the read-only attribute,
and Python has no API for setting an ACL, so Headroom does not claim a
protection it cannot establish. The log inherits the ACL of the directory it
is written into, and the proxy logs a warning at startup saying so. Keep
`%USERPROFILE%\.headroom` (or your chosen `--log-file` path) off shared
volumes and out of directories with broadened permissions.
- **Windows:** Headroom restricts the log file too, through an NTFS ACL —
Python has no ACL API, so this goes directly through `ctypes` rather than a
third-party dependency. The DACL it sets grants access to exactly the
current user, replacing (not merging with) whatever was inherited from the
parent directory. This can fail for reasons unrelated to Headroom's own
code — a non-NTFS volume, a missing privilege — so the proxy re-reads the
file afterward to confirm, and only logs a warning at startup if that
check fails. If you see that warning, keep `%USERPROFILE%\.headroom` (or
your chosen `--log-file` path) off shared volumes and out of directories
with broadened permissions.
A log shipper or sidecar running as a different user or group cannot read the
runtime log on Linux/macOS. Run the collector as the same user, or copy the file
@@ -401,7 +433,7 @@ with a privileged job.
| `HEADROOM_PROXY_TOKEN` | none | Require a token from non-loopback callers, as `X-Headroom-Proxy-Token: <token>` or `Authorization: Bearer <token>`. The token is removed from the request before it is forwarded upstream; clients that also send a provider credential should use `X-Headroom-Proxy-Token` and keep `Authorization` for the provider. Also gates the read-only operator routes (`/stats-history`, `/quota`, `/subscription-window`, `/metrics`), which otherwise answer loopback and trusted-CIDR callers only. |
| `HEADROOM_ALLOW_UNAUTHENTICATED_BIND` | `false` | Acknowledge a non-loopback bind (`--host 0.0.0.0`, `::`, a LAN address) with **no** `HEADROOM_PROXY_TOKEN`. Without a token or this flag the proxy refuses to start, because `/v1/*` would relay upstream with the operator's credentials for every peer that can reach the port. Only set it when the runtime already restricts reachability (a container published on `127.0.0.1`). |
| `HEADROOM_COMPRESS_ALLOW_REMOTE` | `false` | Allow non-loopback callers to reach [`POST /v1/compress`](#post-v1compress) and `POST /v1/usage`. Required to run Headroom as a remote gateway/sidecar; without it remote callers get `404`. |
| `HEADROOM_OFFLINE` | `false` | Air-gap mode: refuse every connection Headroom itself initiates — telemetry, update checks, license reporting, model/tokenizer/binary/dataset downloads, remote Kompress, OTLP and Langfuse export, Copilot auth, the subscription pollers, the OpenAI embedders, Headroom Cloud compression and the TLS diagnostics (`headroom doctor --network` reports them as skipped). Four things still work on purpose: forwarding your own requests to the upstream you configured, operator-configured local endpoints (the Ollama embedder), loopback health probes, and paths an `is_offline()` check already disables. Refusals surface as messages, not tracebacks. See the air-gap notes in `docs/metrics-technical-guide.md`. |
| `HEADROOM_OFFLINE` | `false` | Air-gap mode: refuse every connection Headroom itself initiates — telemetry, update checks, license reporting, model/tokenizer/binary/dataset downloads, litellm's pricing-table refresh, CrewAI's install tracking, remote Kompress, OTLP and Langfuse export, Copilot auth, the subscription pollers, the OpenAI embedders, Headroom Cloud compression and the TLS diagnostics (`headroom doctor --network` reports them as skipped). Four things still work on purpose: forwarding your own requests to the upstream you configured, operator-configured local endpoints (the Ollama embedder), loopback health probes, and paths an `is_offline()` check already disables. Refusals surface as messages, not tracebacks. See the air-gap notes in `docs/metrics-technical-guide.md`. |
| `HEADROOM_LICENSE` | unset | Licence token, read by core and every licensed extension. `HEADROOM_LICENSE_KEY` is a deprecated alias for one release and logs a warning. A licence on its own sends nothing to Headroom. |
| `HEADROOM_USAGE_REPORTING` | `false` | Set `1` to let the proxy validate the licence and post aggregate usage counts (no content) to the Headroom cloud. Off unless set; `HEADROOM_OFFLINE` still overrides it. |
| `--stateless` / `HEADROOM_STATELESS` | `false` | Keep all state in memory; no filesystem writes (disables logs, memory, TOIN). |
+1
View File
@@ -284,6 +284,7 @@ accept arbitrary environment variables — writes are restricted to a hardcoded
| `HEADROOM_INTERCEPT_READ_MIN_CHARS` | ast-grep read-interception threshold |
| `HEADROOM_VERIFY_TRUNCATION_ON_DISK` | Verify ast-grep Read truncation against disk when no client banner is found. Always returns `UNKNOWN` on Windows, where `dir_fd` / `O_NOFOLLOW` support is unavailable. |
| `HEADROOM_VERIFY_TRUNCATION_MAX_BYTES` | Max on-disk file size (bytes) the disk-verify fallback will read |
| `HEADROOM_WEB_SEARCH_HISTORY` | Drop `web_search_call` history from a Responses request that declares no web_search tool (default on; `0` disables) |
| `HEADROOM_BUFFERED_UPSTREAM_STREAM` | Send buffered CCR requests (and their continuations) upstream as `stream: true` and fold the reply (default on; `0` sends `stream: false`) |
Keys outside this list are ignored, and `/admin/upstream` is read-only — there is no
+5
View File
@@ -93,6 +93,11 @@ print(f"Compression ratio: {result.compression_ratio:.1%}")
- Verbose success output
- Repeated patterns
Omission markers count `ERROR`, `FAIL`, `WARN`, and `INFO` levels only among the dropped lines, not the full input. An error retained in the compressed output is therefore not advertised as omitted. Debug, trace, and unclassified lines are not listed in the level breakdown.
When only debug, trace, or unclassified lines are dropped, the marker is simply `[N lines omitted]`, without a severity breakdown.
`result.stats` continues to report whole-input totals; the marker's narrower counts do not change those statistics. CCR still retains the exact original log when enabled.
## DiffCompressor
Compresses unified diffs while keeping the actual changes and enough context to understand them.
+22
View File
@@ -364,6 +364,28 @@ pipx install --python python3.13 "headroom-ai[all]==0.21.4"
If you already have Headroom installed under `pipx`, uninstall it first or
reinstall it with the supported interpreter.
### Docker image frozen at an old version
**Symptom**: `headroom --version` inside the running container reports an old
release (e.g. `0.27.0`) no matter how recently you pulled the image.
**Cause**: the project moved from the `chopratejas` personal account to the
`headroomlabs-ai` org, and GHCR does not redirect packages across that move.
`ghcr.io/chopratejas/headroom` still exists but stopped receiving pushes at
that point, so it is permanently frozen at the last version built under the
old namespace. A `HEADROOM_DOCKER_IMAGE` override, an install script, or a
tutorial saved from before the move can still point there.
Pull the current image instead:
```bash
docker pull ghcr.io/headroomlabs-ai/headroom:latest
```
If you set `HEADROOM_DOCKER_IMAGE` yourself, check it does not still read
`ghcr.io/chopratejas/headroom`. See [Docker install](/docs/docker-install)
for the current default and the available tags.
### pip install fails with C++ compilation error
**Symptom**: `RuntimeError: Unsupported compiler -- at least C++11 support is needed!`
+14 -2
View File
@@ -117,8 +117,20 @@ snapshot in response metadata (for example, a request for `gpt-5.5` returned
Copilot plan and organization policy.
The proxy supports the native Copilot OpenAI-compatible request paths used by
GPT and Claude models. Headroom's upstream auth hook replaces local client auth
with the current Copilot API token on every Copilot-bound request.
GPT and Claude models. Inline completions retain the editor's own `ghu_` OAuth
bearer and native integration metadata on the completions host, including an
operator-configured gateway with a base-path prefix. Headroom does not replace
that editor identity with the proxy operator's Copilot seat or add chat-specific
headers. Chat and Responses retain their existing managed Copilot API-token
policy; a raw OAuth bearer on those routes does not gain the inline exception.
A configured base path is removed only for the same scheme and authority, at a
complete path-segment boundary. Other recognized completions endpoints keep
their native `/v1` paths.
The inline auth branch logs only the credential kind (`ghu_***`), not the
editor's OAuth token. Case variants of unrelated provider API-key headers are
removed before any Copilot auth branch forwards the request.
## Stop and undo
+3 -1
View File
@@ -268,7 +268,7 @@ Verify with `curl -s localhost:8787/stats | jq .otel`.
**Multi-tenant labels:** `register_otel_metric_attribute_provider()` adds request-scoped attributes (tenant, team, cost centre) to every OTel datapoint. Max 16 attributes, 256 chars each.
**Air-gapped deployments:** `HEADROOM_OFFLINE=1` refuses every connection Headroom itself decides to make to a destination Headroom itself chose. That is the whole list, not a sample: the anonymous usage beacon (which is **on by default**), the update check, the license/usage reporter, **OTLP metric and Langfuse trace export**, HuggingFace / Kompress / fastembed model and tokenizer downloads (Python and Rust), the remote Kompress endpoint, the `headroom install` release-binary and codebase-memory-mcp downloads, the BFCL eval-dataset fetch and the provider SDK clients the eval harness drives, GitHub Copilot device-flow auth and token exchange, the Anthropic / Codex / Copilot subscription pollers, the OpenAI embedders, the Headroom Cloud compression modes in the ASGI and LiteLLM integrations, and the TLS diagnostics (`headroom doctor --network` endpoint checks and the certificate-chain re-probe after an upstream TLS failure).
**Air-gapped deployments:** `HEADROOM_OFFLINE=1` refuses every connection Headroom itself decides to make to a destination Headroom itself chose. That is the whole list, not a sample: the anonymous usage beacon (which is **on by default**), the update check, the license/usage reporter, **OTLP metric and Langfuse trace export**, HuggingFace / Kompress / fastembed model and tokenizer downloads (Python and Rust), the remote Kompress endpoint, the `headroom install` release-binary and codebase-memory-mcp downloads, litellm's import-time pricing-table refresh, CrewAI's import-time install tracking, the BFCL eval-dataset fetch and the provider SDK clients the eval harness drives, GitHub Copilot device-flow auth and token exchange, the Anthropic / Codex / Copilot subscription pollers, the OpenAI embedders, the Headroom Cloud compression modes in the ASGI and LiteLLM integrations, and the TLS diagnostics (`headroom doctor --network` endpoint checks and the certificate-chain re-probe after an upstream TLS failure).
Four things are deliberately still allowed, and they are the complete set of exceptions:
@@ -279,6 +279,8 @@ Four things are deliberately still allowed, and they are the complete set of exc
Those four are enumerated with written reasons in `_EGRESS_ALLOWLIST` in `tests/test_offline_egress_chokepoint.py`, which fails the build if a new egress path appears that is neither guarded nor one of them. There is no category for "known violation": a path that can dial the internet with the flag set is a bug. A refusal reaches you as a message — a Click error on the CLI, a named "model unavailable" from a model loader, a logged line from a background poller — never as a traceback and never as a silent degradation. Enforcing the same policy at the network layer as well is still good practice; it is no longer the only thing standing between you and Headroom-initiated egress.
litellm's pricing-table refresh is refused by setting `LITELLM_LOCAL_MODEL_COST_MAP=True` before litellm is imported, so it holds only when Headroom is the first thing in the process to import litellm. A host that imports litellm before Headroom, such as a LiteLLM proxy loading the Headroom callback, has made that fetch already and must set the variable itself. Offline, cost and savings figures use the pricing table bundled with the installed litellm release, so a model released after it prices as unknown.
OTLP export is refused loudly: with `HEADROOM_OFFLINE=1` set, `HEADROOM_OTEL_METRICS_ENABLED=1` plus the default `otlp_http` exporter makes the proxy exit 78 at startup with an explanation, rather than quietly dropping metrics. There is no exemption for a collector that looks local — an in-cluster address is not reliably distinguishable from an internet one. For metrics under an air-gap, either scrape `localhost:8787/metrics` or set `HEADROOM_OTEL_METRICS_EXPORTER=console`, both of which stay on-box. `HEADROOM_KOMPRESS_ENDPOINT` and `HEADROOM_LANGFUSE_ENABLED` are refused the same way, for the same reason.
---
+47 -47
View File
@@ -19,7 +19,7 @@
"fumadocs-typescript": "^5.5.1",
"fumadocs-ui": "16.17.1",
"lucide-react": "^1.48.0",
"next": "^16.4.0",
"next": "^16.4.3",
"react": "^19.3.0",
"react-dom": "^19.3.0",
"recharts": "^3.10.1",
@@ -1347,15 +1347,15 @@
}
},
"node_modules/@next/env": {
"version": "16.4.0",
"resolved": "https://registry.npmjs.org/@next/env/-/env-16.4.0.tgz",
"integrity": "sha512-pyLlT5oafGlX8X7xjgGNXz5dNIDSxREm+qD6i9VLSZiZFopA/XWl8NM/KPmLx/8EG/++c49iid3gNWSQW1+2dQ==",
"version": "16.4.3",
"resolved": "https://registry.npmjs.org/@next/env/-/env-16.4.3.tgz",
"integrity": "sha512-a7tz1QCcWWkwC/rPJcPMJk/UNRu9CFhDd3OHYE5hddbJrs8BqRTalxI6GlKCWEGzRLHN+S/B7a4PAHCtm25aBQ==",
"license": "MIT"
},
"node_modules/@next/swc-darwin-arm64": {
"version": "16.4.0",
"resolved": "https://registry.npmjs.org/@next/swc-darwin-arm64/-/swc-darwin-arm64-16.4.0.tgz",
"integrity": "sha512-yyZ+9MgViAKLLb5l1gPBGjRwnq3teNLb5Zx6JEw8LzNSTjlsnp+baUHFxTgl7PpjCmKf48VQfyipG1eBflb48Q==",
"version": "16.4.3",
"resolved": "https://registry.npmjs.org/@next/swc-darwin-arm64/-/swc-darwin-arm64-16.4.3.tgz",
"integrity": "sha512-4yq5EXBt+VDtAZwTyfijaFp5D2C5oz3Ikw5a2kiX2K9nw72vrZX2q5UuAlkPtUMO1tQz6JTKpaKWjS7OOefTDQ==",
"cpu": [
"arm64"
],
@@ -1369,9 +1369,9 @@
}
},
"node_modules/@next/swc-darwin-x64": {
"version": "16.4.0",
"resolved": "https://registry.npmjs.org/@next/swc-darwin-x64/-/swc-darwin-x64-16.4.0.tgz",
"integrity": "sha512-RePEEejEj1Auf5s9qEcG0JbcDP3ceNUS/ofNX8AhxzgIjTVlZIHMatlp16YplcSMpsVo/ZMQHJTjbMYJznjGUg==",
"version": "16.4.3",
"resolved": "https://registry.npmjs.org/@next/swc-darwin-x64/-/swc-darwin-x64-16.4.3.tgz",
"integrity": "sha512-1Rvkn/LUhnEF8WxnRkOrqGhbwXui1bkWFxONKIbN+r7C+9KHDSZ+iUoj4CzymVMWUyZIyx9szcb9+kbKhD500A==",
"cpu": [
"x64"
],
@@ -1385,9 +1385,9 @@
}
},
"node_modules/@next/swc-linux-arm64-gnu": {
"version": "16.4.0",
"resolved": "https://registry.npmjs.org/@next/swc-linux-arm64-gnu/-/swc-linux-arm64-gnu-16.4.0.tgz",
"integrity": "sha512-HhsyCqd+NpmvDDVY/LqkAN24f+QVvXh3ie+PfcwKinWL2Mu826JymQxJXGjAIfmJ4VlHjp4Pe/nZtXtUoEMAqw==",
"version": "16.4.3",
"resolved": "https://registry.npmjs.org/@next/swc-linux-arm64-gnu/-/swc-linux-arm64-gnu-16.4.3.tgz",
"integrity": "sha512-dCKpXErGg3abUM6t5JTJV/ottVBTStJB5lRJTbgdUdQaQ+jNHiK56Hsc0YAEg/rinSh42hYG3HWiYmEMdilnxg==",
"cpu": [
"arm64"
],
@@ -1404,9 +1404,9 @@
}
},
"node_modules/@next/swc-linux-arm64-musl": {
"version": "16.4.0",
"resolved": "https://registry.npmjs.org/@next/swc-linux-arm64-musl/-/swc-linux-arm64-musl-16.4.0.tgz",
"integrity": "sha512-sN9Pf+Zh+RpZAOmbR7d8KAA8T61CVhawtbEJ2Bk6QrRzx6Z/6haaF4UiwBzytM96GRRRWZh9/WALIEO3npMamA==",
"version": "16.4.3",
"resolved": "https://registry.npmjs.org/@next/swc-linux-arm64-musl/-/swc-linux-arm64-musl-16.4.3.tgz",
"integrity": "sha512-WwYbhWkhYBvBtib1K4W0kL8MW2snBD2A5b3SN4vPpqalZbZs5+bQ1yzAdepVoOqrFfEW3dmREy4Zs1MrWcrFbw==",
"cpu": [
"arm64"
],
@@ -1423,9 +1423,9 @@
}
},
"node_modules/@next/swc-linux-x64-gnu": {
"version": "16.4.0",
"resolved": "https://registry.npmjs.org/@next/swc-linux-x64-gnu/-/swc-linux-x64-gnu-16.4.0.tgz",
"integrity": "sha512-D5M5xLWQVd1CvR+L7BickM1weRfmM41x3L1NWcnKY/oyJJqr1qwaCgmu3dMAhLBOMdZwSuDCRV6DJRRpiUkbDQ==",
"version": "16.4.3",
"resolved": "https://registry.npmjs.org/@next/swc-linux-x64-gnu/-/swc-linux-x64-gnu-16.4.3.tgz",
"integrity": "sha512-QymWvfUwDEC5/lpJOsxX5VAbyoR2D13+2Jsjz4be7gT4LPqEgdpkeLIR/HFfCLgKzoMhpJbp6I/JnogyNZHcaA==",
"cpu": [
"x64"
],
@@ -1442,9 +1442,9 @@
}
},
"node_modules/@next/swc-linux-x64-musl": {
"version": "16.4.0",
"resolved": "https://registry.npmjs.org/@next/swc-linux-x64-musl/-/swc-linux-x64-musl-16.4.0.tgz",
"integrity": "sha512-8d5WLS6a9YalqpOgXdlbvonFu+sIgjA+CO6tGzetrpPVcUL56foa7B7664h41rAlbLi5fJwK4vWji3zf4QDy+w==",
"version": "16.4.3",
"resolved": "https://registry.npmjs.org/@next/swc-linux-x64-musl/-/swc-linux-x64-musl-16.4.3.tgz",
"integrity": "sha512-Vmjd9D7DpA4Vv3cUlr82QWgJD/BQZmns801vtC5VWHg6jCIA4a5vMKpQnfrM2pyCrp2eV0ENdUg4PlN3bAc2Yw==",
"cpu": [
"x64"
],
@@ -1461,9 +1461,9 @@
}
},
"node_modules/@next/swc-win32-arm64-msvc": {
"version": "16.4.0",
"resolved": "https://registry.npmjs.org/@next/swc-win32-arm64-msvc/-/swc-win32-arm64-msvc-16.4.0.tgz",
"integrity": "sha512-sQuOIiW3snb48UwrBcDMvFA/u03qtw2LeuSIxFIQ9AJuW9UG/4Ddsfo+eV73PnZwBhyncMtsKVh7PrzMol2/fA==",
"version": "16.4.3",
"resolved": "https://registry.npmjs.org/@next/swc-win32-arm64-msvc/-/swc-win32-arm64-msvc-16.4.3.tgz",
"integrity": "sha512-lG1pPdPLk7gTyGb00n5JIMLdBJgjb+UEhSdZvFbhUMg0DyC6z4B7RnpSKF9VCd4imkLObVbXOFA0kFCpw7yFow==",
"cpu": [
"arm64"
],
@@ -1477,9 +1477,9 @@
}
},
"node_modules/@next/swc-win32-x64-msvc": {
"version": "16.4.0",
"resolved": "https://registry.npmjs.org/@next/swc-win32-x64-msvc/-/swc-win32-x64-msvc-16.4.0.tgz",
"integrity": "sha512-6/33lCuxpdHUy27RegyGM/5uTpF7YZd3UR4D0gpkOA/tWY5YR7msbQjqPgCZmSmxrrTLGCXYA4A8vT2H5DPGTQ==",
"version": "16.4.3",
"resolved": "https://registry.npmjs.org/@next/swc-win32-x64-msvc/-/swc-win32-x64-msvc-16.4.3.tgz",
"integrity": "sha512-NmQC9RkJdnPXRaMxtkCzobB3teVjqF33oSOnwDfi+XYGWWYpt+xlGK3mtktSKLbdjwaWbJu2OkkMiRFGUUncKg==",
"cpu": [
"x64"
],
@@ -5976,12 +5976,12 @@
}
},
"node_modules/next": {
"version": "16.4.0",
"resolved": "https://registry.npmjs.org/next/-/next-16.4.0.tgz",
"integrity": "sha512-N2C+9q89Z/oLrsepSRS4jRMtwmUZAoZuAHU0e9T6+sAB5DdhADmrnOW+zjYijlrYFmVfmQhGVGy9eMFoB7UgKg==",
"version": "16.4.3",
"resolved": "https://registry.npmjs.org/next/-/next-16.4.3.tgz",
"integrity": "sha512-OqxKTGi9u80FydydsMNYNjnuje9Au+kvHlt2GZ//ftdpDHm1dxKqAaENoOOTX5wKzn+9vaKUNIfZeyZUuLhCnA==",
"license": "MIT",
"dependencies": {
"@next/env": "16.4.0",
"@next/env": "16.4.3",
"@swc/helpers": "0.5.23",
"baseline-browser-mapping": "^2.9.19",
"caniuse-lite": "^1.0.30001579",
@@ -5995,15 +5995,15 @@
"node": ">=20.9.0"
},
"optionalDependencies": {
"@next/swc-darwin-arm64": "16.4.0",
"@next/swc-darwin-x64": "16.4.0",
"@next/swc-linux-arm64-gnu": "16.4.0",
"@next/swc-linux-arm64-musl": "16.4.0",
"@next/swc-linux-x64-gnu": "16.4.0",
"@next/swc-linux-x64-musl": "16.4.0",
"@next/swc-win32-arm64-msvc": "16.4.0",
"@next/swc-win32-x64-msvc": "16.4.0",
"sharp": "^0.35.4"
"@next/swc-darwin-arm64": "16.4.3",
"@next/swc-darwin-x64": "16.4.3",
"@next/swc-linux-arm64-gnu": "16.4.3",
"@next/swc-linux-arm64-musl": "16.4.3",
"@next/swc-linux-x64-gnu": "16.4.3",
"@next/swc-linux-x64-musl": "16.4.3",
"@next/swc-win32-arm64-msvc": "16.4.3",
"@next/swc-win32-x64-msvc": "16.4.3",
"sharp": "^0.35.5"
},
"peerDependencies": {
"@opentelemetry/api": "^1.1.0",
@@ -6849,9 +6849,9 @@
}
},
"node_modules/undici": {
"version": "7.29.1",
"resolved": "https://registry.npmjs.org/undici/-/undici-7.29.1.tgz",
"integrity": "sha512-RYONW2MeafgYlkVOKYKkA/Ag7BmXqgIWCa8t1m0JcxrQg9pI9lEqRhAOruOBCbAohOa/gkCF+iPi9hrgvTzu6Q==",
"version": "7.30.1",
"resolved": "https://registry.npmjs.org/undici/-/undici-7.30.1.tgz",
"integrity": "sha512-03KrMbjIFDWQR5RNPrSw3bd1r12JpyFQl9/yxjUbJtqkjmllqC5lFjZh6ujeuJCKr8EOQvRW872Oy/az+nLYxg==",
"dev": true,
"license": "MIT",
"engines": {
@@ -7149,9 +7149,9 @@
}
},
"node_modules/zod": {
"version": "4.6.5",
"resolved": "https://registry.npmjs.org/zod/-/zod-4.6.5.tgz",
"integrity": "sha512-v5l/aFXZQeai4awLbOpSoHecE9UiMrnfx75tEXLjNonXVARxQ5mOeipTjROUchszUNCqnE+hqAMujRsRHsut2Q==",
"version": "4.6.7",
"resolved": "https://registry.npmjs.org/zod/-/zod-4.6.7.tgz",
"integrity": "sha512-g8W2D2kU6a8untc053fX1uVBKzM7yqAxW/3zwk83+6RyF2+SKOuV+c0wBDhUwzV1PaGapmZH+rmcUzPf+3CGwg==",
"license": "MIT",
"funding": {
"url": "https://github.com/sponsors/colinhacks"
+1 -1
View File
@@ -23,7 +23,7 @@
"fumadocs-typescript": "^5.5.1",
"fumadocs-ui": "16.17.1",
"lucide-react": "^1.48.0",
"next": "^16.4.0",
"next": "^16.4.3",
"react": "^19.3.0",
"react-dom": "^19.3.0",
"recharts": "^3.10.1",
@@ -0,0 +1,283 @@
# HEAOSS-6 Pull Request Split Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Replace PR #3382 with six focused draft pull requests whose cumulative tip preserves its reviewed HEAOSS-6 behavior.
**Architecture:** Build a linear Git branch stack from current upstream `main`. Each branch introduces one independently useful layer: decisions, policy contracts, evidence contracts, manifest tooling, reusable release builds, then candidate orchestration.
**Tech Stack:** Git, GitHub CLI, Python 3.13, pytest, JSON Schema 2020-12, GitHub Actions, Ruff, mypy, actionlint
**Spec:** `docs/superpowers/specs/2026-09-17-heaoss-6-pr-split-design.md`
## Global Constraints
- The first branch is based on current upstream `main`; each later branch is based on its immediate predecessor.
- Every pull request is opened as a draft and targets the preceding branch.
- The original PR #3382 stays unchanged until all six drafts and the cumulative-equivalence audit exist.
- No unrelated merge-commit changes from PR #3382 may enter the new stack.
- Release publishing behavior remains intact after every executable slice.
- Every PR body states `Part of HEAOSS-6; split from #3382.` and identifies its stack position.
---
### Task 1: Release Qualification Decisions
**Files:**
- Create: `docs/adr/0001-main-release-branch-semantics.md`
- Create: `docs/adr/0002-release-artifact-identity.md`
- Create: `docs/adr/0003-a1-b-release-benchmark.md`
- Create: `docs/adr/0004-black-box-release-benchmarks.md`
- Create: `docs/adr/0005-release-overrides-and-fail-closed-policy.md`
- Existing: `docs/superpowers/specs/2026-09-17-heaoss-6-pr-split-design.md`
- Existing: `docs/superpowers/plans/2026-09-17-heaoss-6-pr-split.md`
**Interfaces:**
- Consumes: HEAOSS-6 decisions preserved on `upstream/pr-3382`.
- Produces: Stable terminology for source, artifact, rollout, policy, benchmark, and override identity used by later PRs.
- [ ] **Step 1: Restore the five reviewed ADRs**
```powershell
git checkout upstream/pr-3382 -- docs/adr/0001-main-release-branch-semantics.md docs/adr/0002-release-artifact-identity.md docs/adr/0003-a1-b-release-benchmark.md docs/adr/0004-black-box-release-benchmarks.md docs/adr/0005-release-overrides-and-fail-closed-policy.md
```
- [ ] **Step 2: Verify documentation integrity**
Run both `git diff --check` and `git diff --cached --check`; stop if either exits nonzero. The restore command stages the ADRs, so the cached check is required to inspect those files.
Run `rg -n 'TB[D]|TO[D]O'` against the five restored ADRs and this split's specification and plan. Exit 1 means no placeholders; exit 0 reports unresolved markers, and exit 2 is a scan error.
Expected: both whitespace checks exit 0 and no unresolved placeholder is present in these seven documents. Unrelated plans and ADRs are outside this slice's placeholder check.
- [ ] **Step 3: Commit the documentation slice**
```powershell
git add docs/adr docs/superpowers
git commit -m "docs(release): define qualification decisions"
```
- [ ] **Step 4: Push and open draft PR 1**
```powershell
git push -u origin jd/heaoss-6-01-release-qualification-decisions
gh pr create --repo headroomlabs-ai/headroom --draft --base main --head JerrettDavis:jd/heaoss-6-01-release-qualification-decisions --title "docs(release): define qualification decisions" --body-file <body-file>
```
### Task 2: Shared Policy Contracts
**Files:**
- Create: `release/contracts/common.schema.json`
- Create: `release/contracts/policy.schema.json`
- Create: `release/contracts/examples/policy.valid.json`
- Create: `release/contracts/README.md`
- Modify: `pyproject.toml`
- Modify: `uv.lock`
- Create: `tests/test_release_contracts.py`
**Interfaces:**
- Consumes: ADR terminology from Task 1.
- Produces: JSON Schema definitions referenced as `common.schema.json#/$defs/...` and a complete `policy.schema.json` consumer.
- [ ] **Step 1: Create the stacked branch and restore contract sources**
```powershell
git switch -c jd/heaoss-6-02-release-policy-contracts
git checkout upstream/pr-3382 -- release/contracts/common.schema.json release/contracts/policy.schema.json release/contracts/examples/policy.valid.json release/contracts/README.md pyproject.toml uv.lock
```
- [ ] **Step 2: Add focused policy contract tests**
Extract the schema-registry helpers and policy-specific cases from PR #3382's
`tests/test_release_contracts.py`. The resulting test file must load local
schemas through `referencing.Registry`, validate `policy.valid.json`, reject an
unknown schema version, and enforce policy pass/fail invariants.
- [ ] **Step 3: Validate and commit**
Run: `uv lock --check`
Run: `uv run --extra dev pytest tests/test_release_contracts.py -q`
Run: `uv run --extra dev ruff check tests/test_release_contracts.py`
Expected: all commands exit 0.
```powershell
git add release/contracts tests/test_release_contracts.py pyproject.toml uv.lock
git commit -m "feat(release): define versioned policy contracts"
```
- [ ] **Step 4: Push and open draft PR 2 targeting PR 1's branch**
Use title `feat(release): define versioned policy contracts` and base
`jd/heaoss-6-01-release-qualification-decisions`.
### Task 3: Qualification Evidence Contracts
**Files:**
- Create: `release/contracts/benchmark-result-ref.schema.json`
- Create: `release/contracts/candidate-manifest.schema.json`
- Create: `release/contracts/gate-result.schema.json`
- Create: `release/contracts/integration-result.schema.json`
- Create: `release/contracts/qualification-manifest.schema.json`
- Create: matching files under `release/contracts/examples/`
- Modify: `tests/test_release_contracts.py`
**Interfaces:**
- Consumes: `common.schema.json` definitions and the release policy contract.
- Produces: Complete evidence formats used by candidate tooling and future qualification lanes.
- [ ] **Step 1: Create the branch and restore all remaining schemas/examples**
Create `jd/heaoss-6-03-qualification-evidence-contracts` from Task 2, then
restore the declared files from `upstream/pr-3382`.
- [ ] **Step 2: Restore the complete reviewed contract test suite**
```powershell
git checkout upstream/pr-3382 -- tests/test_release_contracts.py
```
- [ ] **Step 3: Validate and commit**
Run: `uv run --extra dev pytest tests/test_release_contracts.py -q`
Run: `uv run --extra dev ruff check tests/test_release_contracts.py`
Expected: all contract examples and negative invariants pass.
Commit as `feat(release): add qualification evidence contracts`.
- [ ] **Step 4: Push and open draft PR 3 targeting PR 2's branch**
### Task 4: Candidate Manifest CLI
**Files:**
- Create: `scripts/candidate_manifest.py`
- Create: `tests/test_candidate_manifest.py`
- Modify: `.gitignore`
**Interfaces:**
- Consumes: `release/contracts/candidate-manifest.schema.json` and common definitions.
- Produces: `inventory`, `create`, and `verify` CLI commands used by Task 6.
- [ ] **Step 1: Create the branch and restore reviewed CLI files**
Create `jd/heaoss-6-04-candidate-manifest-cli`, then restore the three declared
paths from `upstream/pr-3382`.
- [ ] **Step 2: Validate behavior and types**
Run: `uv run --extra dev pytest tests/test_candidate_manifest.py tests/test_release_contracts.py -q`
Run: `uv run --extra dev ruff check scripts/candidate_manifest.py tests/test_candidate_manifest.py`
Run: `uv run --extra dev mypy scripts/candidate_manifest.py`
Expected: all commands exit 0.
- [ ] **Step 3: Commit, push, and open draft PR 4 targeting PR 3's branch**
Commit as `feat(release): add immutable candidate manifest verifier`.
### Task 5: Read-Only Release Build Workflow
**Files:**
- Create: `.github/workflows/release-build.yml`
- Modify: `.github/workflows/release.yml`
- Modify: `tests/test_release_workflows.py`
- Modify: `docs/content/docs/releases.mdx`
**Interfaces:**
- Consumes: Existing release build and smoke jobs.
- Produces: Reusable `workflow_call` accepting `source_sha`, `manual_version`, and `release_tag`, with version/npm/canonical outputs and retained artifacts.
- [ ] **Step 1: Create the branch and restore the reviewed extraction**
Create `jd/heaoss-6-05-read-only-release-build`, then restore the four declared
paths from `upstream/pr-3382`.
- [ ] **Step 2: Validate workflow structure and release invariants**
Run: `uv run --extra dev pytest tests/test_release_workflows.py -q`
Run: `actionlint .github/workflows/release.yml .github/workflows/release-build.yml`
Expected: 50 or more release workflow tests pass and actionlint emits no findings.
- [ ] **Step 3: Commit, push, and open draft PR 5 targeting PR 4's branch**
Commit as `refactor(release): extract read-only build workflow`.
### Task 6: Immutable Candidate Workflow
**Files:**
- Create: `.github/workflows/candidate-artifact.yml`
- Create: `tests/test_candidate_workflow.py`
- Modify: `docs/content/docs/releases.mdx`
**Interfaces:**
- Consumes: Task 4 CLI and Task 5 reusable workflow.
- Produces: A manual exact-main-SHA candidate artifact and independently verified retained bytes.
- [ ] **Step 1: Create the branch and restore candidate orchestration**
Create `jd/heaoss-6-06-immutable-candidate-workflow`, then restore the workflow
and test from `upstream/pr-3382`. Reconcile the release documentation so only
candidate-specific additions remain in this branch.
- [ ] **Step 2: Run cumulative focused validation**
Run: `uv run --extra dev pytest tests/test_candidate_workflow.py tests/test_candidate_manifest.py tests/test_release_contracts.py tests/test_release_workflows.py -q`
Run: `uv run --extra dev ruff check scripts/candidate_manifest.py tests/test_candidate_manifest.py tests/test_candidate_workflow.py tests/test_release_contracts.py tests/test_release_workflows.py`
Run: `uv run --extra dev mypy scripts/candidate_manifest.py`
Run: `actionlint .github/workflows/candidate-artifact.yml .github/workflows/release-build.yml .github/workflows/release.yml`
Expected: 96 focused tests or the current-main-adjusted equivalent pass; lint,
types, and workflow validation exit 0.
- [ ] **Step 3: Audit cumulative equivalence**
```powershell
git diff --stat upstream/pr-3382...HEAD
git diff upstream/pr-3382 HEAD -- .github docs/adr docs/content/docs/releases.mdx release scripts tests/test_candidate_manifest.py tests/test_candidate_workflow.py tests/test_release_contracts.py tests/test_release_workflows.py pyproject.toml uv.lock .gitignore
```
Expected: only the approved split documents and intentional current-main
reconciliation differ. Investigate and document every other difference.
- [ ] **Step 4: Commit, push, and open draft PR 6 targeting PR 5's branch**
Commit as `feat(release): build immutable exact-SHA candidates`.
### Task 7: Link the Stack and Supersede PR #3382
**Files:**
- Modify: GitHub draft PR bodies only.
**Interfaces:**
- Consumes: URLs and exact head/base SHAs for all six draft PRs.
- Produces: Navigable stack metadata and a non-destructive supersession notice on #3382.
- [ ] **Step 1: Update each draft body with complete previous/next links**
Use `gh pr edit` and verify the rendered bodies with `gh pr view --json body`.
- [ ] **Step 2: Convert #3382 to draft and prepend the supersession notice**
The notice must link all six drafts and retain the prior validation history
below it. Do not close #3382.
- [ ] **Step 3: Verify authoritative GitHub state**
Run `gh pr view` for all seven PRs and verify draft status, base branch, head
branch, mergeability, and URLs. Confirm every new PR head SHA matches the pushed
local branch.
- [ ] **Step 4: Report hosted-check status without claiming unobserved success**
List terminal, pending, or failing checks for each exact head. Hosted checks may
continue after handoff; local validation and PR creation are required before
the task is reported complete.
@@ -0,0 +1,243 @@
# HEAOSS-6 Pull Request Split Design
## Purpose
Replace the 3,279-line change in PR #3382 with a reviewable stack of six draft
pull requests. Every pull request must have one coherent deliverable, pass its
own focused validation, and leave the repository in a useful state if the stack
stops there.
The final stack must preserve the behavior and safety properties already
reviewed on PR #3382: versioned qualification evidence contracts, fail-closed
candidate manifest verification, exact-main-SHA builds, a read-only build call
tree, deterministic artifact inventory, and independent verification of the
retained candidate bytes.
## Constraints
- Base the first branch on the current upstream `main`.
- Stack every later branch on its immediate predecessor.
- Keep each pull request draft until the whole stack is reconstructed and its
cumulative tip is equivalent to PR #3382, except for deliberate documentation
and history changes described here.
- Do not modify or delete the original PR #3382 branch while constructing the
stack.
- Do not include unrelated changes from merge commits or the dirty primary
checkout.
- Preserve the release workflow's existing publish behavior at every executable
step of the stack.
- Use conventional commit messages and include the HEAOSS-6 context and stack
position in every pull request body.
## Stack Topology
| Position | Branch | Base | Deliverable |
| --- | --- | --- | --- |
| 1 | `jd/heaoss-6-01-release-qualification-decisions` | `main` | Release qualification ADRs and this split specification |
| 2 | `jd/heaoss-6-02-release-policy-contracts` | PR 1 branch | Shared evidence vocabulary and versioned release policy contract |
| 3 | `jd/heaoss-6-03-qualification-evidence-contracts` | PR 2 branch | Candidate, benchmark, integration, gate, and qualification evidence schemas |
| 4 | `jd/heaoss-6-04-candidate-manifest-cli` | PR 3 branch | Local candidate inventory, manifest creation, and fail-closed verification CLI |
| 5 | `jd/heaoss-6-05-read-only-release-build` | PR 4 branch | Reusable read-only build/smoke workflow used by the existing release pipeline |
| 6 | `jd/heaoss-6-06-immutable-candidate-workflow` | PR 5 branch | Manual exact-SHA candidate build, bundling, retention, and independent verification |
GitHub draft PRs use the preceding branch as their base. This makes each diff
show only its own deliverable while retaining an executable cumulative tip.
## PR 1: Release Qualification Decisions
### Scope
- Add ADR 0001 defining authoritative-main release semantics.
- Add ADR 0002 defining artifact and runtime-payload identity.
- Add ADR 0003 defining the A1/B benchmark comparison.
- Add ADR 0004 defining black-box release benchmarks.
- Add ADR 0005 defining overrides and fail-closed policy.
- Add this stack design document.
### Value at Merge
The repository gains an explicit, reviewable release-qualification model before
automation encodes it. No runtime or workflow behavior changes.
### Validation
- Markdown and formatting checks applicable to documentation.
- Confirm the ADRs contain no unresolved placeholders and agree on identity,
policy, and override terminology.
## PR 2: Shared Policy Contracts
### Scope
- Add `release/contracts/common.schema.json` with shared identity, status,
rollout, producer, environment, override, and equivalence definitions.
- Add `release/contracts/policy.schema.json` and its valid example.
- Add `release/contracts/README.md` covering schema versioning and validation.
- Add `jsonschema>=4.23.0,<5.0` to the development dependencies and refresh
`uv.lock`.
- Introduce the reusable schema loading and validation test helpers in
`tests/test_release_contracts.py`, with positive and negative policy tests.
### Value at Merge
Policy authors can publish and validate a complete versioned release policy.
The shared vocabulary is exercised by a real consumer in the same pull request;
it is not unused scaffolding.
### Validation
- `uv lock --check`
- `uv run --extra dev pytest tests/test_release_contracts.py -q`
- `uv run --extra dev ruff check tests/test_release_contracts.py`
## PR 3: Qualification Evidence Contracts
### Scope
- Add candidate-manifest, benchmark-result-reference, integration-result,
gate-result, and qualification-manifest schemas.
- Add one valid example for every schema.
- Extend contract tests to validate every example, reject malformed identities,
enforce pass/fail invariants, enforce Gate B runtime-payload equivalence, and
reject unsupported schema versions.
### Value at Merge
Qualification producers and consumers have a complete, machine-validated
evidence interchange format. The contracts are independently useful without
the candidate workflow and can be adopted by later qualification lanes.
### Validation
- `uv run --extra dev pytest tests/test_release_contracts.py -q`
- `uv run --extra dev ruff check tests/test_release_contracts.py`
- Validate that all relative `$ref` targets resolve from the checked-in schema
registry.
## PR 4: Candidate Manifest CLI
### Scope
- Add `scripts/candidate_manifest.py` with `inventory`, `create`, and `verify`
commands.
- Add `.candidate/` to `.gitignore` for local command output.
- Add focused tests for deterministic ordering, hashes, sizes, package/version
identity, source SHA, producer repository/workflow/run identity, rollout
identity, safe qualification eligibility, schema versions, missing files,
changed bytes, and unsupported embedded schemas.
### Value at Merge
Maintainers can create and independently verify immutable candidate manifests
locally or from any later CI workflow. The CLI is fully functional before it is
wired into GitHub Actions.
### Validation
- `uv run --extra dev pytest tests/test_candidate_manifest.py tests/test_release_contracts.py -q`
- `uv run --extra dev ruff check scripts/candidate_manifest.py tests/test_candidate_manifest.py`
- `uv run --extra dev mypy scripts/candidate_manifest.py`
## PR 5: Read-Only Release Build Workflow
### Scope
- Extract version resolution, package construction, the cross-platform wheel
matrix, distribution collection, and smoke imports from `release.yml` into
the reusable `release-build.yml` workflow.
- Make `release.yml` call the reusable workflow, then retain all publishing and
release creation in `release.yml`.
- Ensure every publisher waits for the complete build/smoke group.
- Preserve the release workflow entry points and published outputs.
- Update release workflow tests and release documentation to describe the new
boundary.
### Value at Merge
The production release uses a reusable, contents-read-only build boundary with
no publishing job in its call tree. This is immediately useful even without the
candidate workflow and removes duplicated future build logic.
### Validation
- `uv run --extra dev pytest tests/test_release_workflows.py -q`
- `actionlint .github/workflows/release.yml .github/workflows/release-build.yml`
- Hosted PR dry-run must complete all platform builds and smoke-import jobs;
publishing jobs must remain skipped.
## PR 6: Immutable Candidate Workflow
### Scope
- Add `candidate-artifact.yml` as a manual workflow accepting only a full SHA
reachable from authoritative `main`.
- Call `release-build.yml` directly under `contents: read` permissions.
- Produce a deterministic artifact inventory and X-001A candidate manifest.
- Verify the manifest before upload, download the retained artifact in a
separate job, and verify the exact bytes again.
- Reject wrong source, repository, producer, workflow, run, attempt,
package/version, filename, size, digest, rollout identity, unsafe rollout,
qualification-ineligible rollout, or unsupported schema.
- Add focused structural workflow tests and document the candidate workflow.
### Value at Merge
Maintainers can build and retain an immutable release candidate from an exact
commit on authoritative `main` without exposing publishing permissions. The
same bytes are verified independently after artifact retention.
### Validation
- `uv run --extra dev pytest tests/test_candidate_workflow.py tests/test_candidate_manifest.py tests/test_release_contracts.py tests/test_release_workflows.py -q`
- `uv run --extra dev ruff check scripts/candidate_manifest.py tests/test_candidate_manifest.py tests/test_candidate_workflow.py tests/test_release_contracts.py tests/test_release_workflows.py`
- `uv run --extra dev mypy scripts/candidate_manifest.py`
- `actionlint .github/workflows/candidate-artifact.yml .github/workflows/release-build.yml .github/workflows/release.yml`
- Hosted fork validation must build all five platform targets, run all smoke
jobs, emit the candidate, download it independently, and verify its bytes.
No publishing job may run.
## Reconstruction Method
For each branch, restore only the files or coherent hunks assigned to that pull
request from PR #3382's reviewed tip. Where one original test file spans two
stack positions, split its tests by the behavior introduced at that position.
Commit and validate each branch before creating the next branch from it.
After PR 6, compare its cumulative tree to PR #3382 with `git diff`, allowing
only this specification and any necessary stack metadata. Review every
remaining difference rather than assuming equivalence from file counts.
## Draft Pull Request Format
Each draft body must include:
- `Stack: N of 6` and links to adjacent draft PRs when available.
- The branch/base relationship.
- A concise statement of the independently deliverable value.
- Exact local validation results for that branch.
- A note that hosted validation is pending or a link to its exact run.
- `Part of HEAOSS-6; split from #3382.`
- Runtime rollout safety and rollback notes appropriate to the slice.
## Original PR Transition
Keep #3382 unchanged until all six draft heads exist and the cumulative tip has
passed local equivalence and validation checks. Then convert #3382 to draft and
replace its leading status section with a supersession notice linking the six
drafts. Do not close it until the stack is confirmed visible and complete; its
existing discussion and hosted validation remain useful review evidence.
## Completion Criteria
The split is complete only when:
1. Six draft PRs exist with the topology above.
2. Every PR diff contains only its declared slice and has passing focused local
validation.
3. PR 5 demonstrates unchanged release build/smoke behavior with publication
skipped on PR validation.
4. PR 6 demonstrates candidate creation and independent byte verification with
no publishing permissions or publishing jobs in its call tree.
5. The cumulative PR 6 tree is reconciled against PR #3382 and every difference
is documented and intentional.
6. PR #3382 is a draft with a supersession notice linking the complete stack.
+1 -1
View File
@@ -69,7 +69,7 @@ ENV DEBIAN_FRONTEND=noninteractive \
PYTHONUNBUFFERED=1 \
PYTHONDONTWRITEBYTECODE=1
# OpenClaw 2026.9.3 requires Node >=24.16.0 (or >=26.1.0). Install the
# OpenClaw 2026.10.6 requires Node >=24.22.1 <25 (or >=26.12.1). Install the
# Node 24 LTS line alongside Python 3.11. Also install git for packages
# that clone at install time.
RUN apt-get update && \
+15
View File
@@ -0,0 +1,15 @@
{
"expires": "2026-11-15",
"reason": "E2E harness only, never shipped in the wheel or SDK. npm 12.2.1 bundles undici 6.29.0 and ip-address 10.7.2; bundled copies ignore overrides and no newer npm release is available. OpenClaw is updated to 2026.10.6 and uses fixed Undici 8.12.3, so no OpenClaw path is excepted. Recheck npm upstream and remove these exact-path exceptions by the existing expiry.",
"advisories": {
"GHSA-4qv8-2p9j-2685": {
"node_modules/npm/node_modules/undici": "6.29.0"
},
"GHSA-xjj6-f33q-929c": {
"node_modules/npm/node_modules/undici": "6.29.0"
},
"GHSA-rxp7-6hxx-x8q5": {
"node_modules/npm/node_modules/ip-address": "10.7.2"
}
}
}
+290 -262
View File
@@ -9,22 +9,22 @@
"version": "1.0.0",
"dependencies": {
"@openai/codex": "0.162.1",
"openclaw": "2026.10.2"
"openclaw": "2026.10.6"
}
},
"node_modules/@agentclientprotocol/sdk": {
"version": "1.5.0",
"resolved": "https://registry.npmjs.org/@agentclientprotocol/sdk/-/sdk-1.5.0.tgz",
"integrity": "sha512-524jwbB2iYWA+kWWyv9fhKbhU89dH/lu9u5EXwVNmfYzopV8BujCDxByBDZhxRUkB7RWIJzISCnwivdDk+bdVg==",
"version": "1.7.0",
"resolved": "https://registry.npmjs.org/@agentclientprotocol/sdk/-/sdk-1.7.0.tgz",
"integrity": "sha512-ZORuxsuEnLjRly7t6Ad7zAsWitjWsyprswyPUHz/yycPb+tTm3DGa8XheaHhRXqX8LS9snuxaYavXSRA50TlHw==",
"license": "Apache-2.0",
"peerDependencies": {
"zod": "^3.25.0 || ^4.0.0"
}
},
"node_modules/@anthropic-ai/sdk": {
"version": "0.128.0",
"resolved": "https://registry.npmjs.org/@anthropic-ai/sdk/-/sdk-0.128.0.tgz",
"integrity": "sha512-tl5cBFZC1jVFrTuQyvQObA4WmuNgcYVeXfriqOumgtLAHUm4gPUj18YnszBW60v0PrjDB8nBDOC6wd9CmHQFlA==",
"version": "0.131.0",
"resolved": "https://registry.npmjs.org/@anthropic-ai/sdk/-/sdk-0.131.0.tgz",
"integrity": "sha512-9+PepoU7qVMmM70jSahdnfcMHAvAnzhMOLv2W9WjRLO+OG/MAiBETkwKZqv7KIJ1Cj5h8eZ019bHzZaq+Mbepw==",
"license": "MIT",
"dependencies": {
"json-schema-to-ts": "^3.1.1",
@@ -207,9 +207,9 @@
}
},
"node_modules/@earendil-works/pi-tui": {
"version": "0.86.1",
"resolved": "https://registry.npmjs.org/@earendil-works/pi-tui/-/pi-tui-0.86.1.tgz",
"integrity": "sha512-FU/zU/zG4RWokcZt+BVXXcieWi5ggvYnWP2kkB5XXjMaHRoy5BDhcZJ9JAnLTN9MwrCRoXgPQxOI0bFqwYeZkQ==",
"version": "1.0.0",
"resolved": "https://registry.npmjs.org/@earendil-works/pi-tui/-/pi-tui-1.0.0.tgz",
"integrity": "sha512-JsT7kXnpZA2YOtQu6RyriyxEO0eJIzPyfiH09bH+OLN5+s18HYkwaUD/tBkjhnSfMu6/50CQPRYJagzSP6HdPw==",
"license": "MIT",
"dependencies": {
"get-east-asian-width": "1.6.0",
@@ -636,9 +636,9 @@
}
},
"node_modules/@google/genai": {
"version": "2.24.0",
"resolved": "https://registry.npmjs.org/@google/genai/-/genai-2.24.0.tgz",
"integrity": "sha512-bIu5eoxF1AaPWs9ivmUJGp1RpDHyapoODvWvnkzRDx2CTIW6UJXFhDdjj0BlRve3ZHMMuEkQBVrA/ALqpW4apA==",
"version": "2.27.0",
"resolved": "https://registry.npmjs.org/@google/genai/-/genai-2.27.0.tgz",
"integrity": "sha512-W6F9Y9d4h7cVQNa85IPCOVVP9PiUzve/ZQPBvQnBmnBJcLvxstEw+R2X/RyCH0SOe0HVDQzeKDpDUf6ZRtbmdQ==",
"hasInstallScript": true,
"license": "Apache-2.0",
"dependencies": {
@@ -696,9 +696,9 @@
}
},
"node_modules/@hono/node-server": {
"version": "2.1.4",
"resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-2.1.4.tgz",
"integrity": "sha512-2g1qeHl4BduwDn6L8nkAvDrPUWPMlkQ//a5NhP/zIyaXKMjZNRV+cG9Csu+BiJFf6+68pqzjf4Hi5sJGKHuS1g==",
"version": "2.1.5",
"resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-2.1.5.tgz",
"integrity": "sha512-MgP/I06GdvsilDspMk/qmRzpk8LOUStP6jFAbSRi40W09DhoyUn+Mj7eyKICPqeYKybOjVFLVIAQzvu1bfIa7Q==",
"license": "MIT",
"engines": {
"node": ">=20"
@@ -755,9 +755,9 @@
}
},
"node_modules/@koromix/koffi-android-arm64": {
"version": "3.3.1",
"resolved": "https://registry.npmjs.org/@koromix/koffi-android-arm64/-/koffi-android-arm64-3.3.1.tgz",
"integrity": "sha512-S3yMzUGca5UJRioY7wdBjeO+LuW9mQhrksL+Wd5ri1X7kWMB2IGLzrT1mn1xqx02Vicgvuy5GtkhHuxG5mkzYw==",
"version": "3.3.2",
"resolved": "https://registry.npmjs.org/@koromix/koffi-android-arm64/-/koffi-android-arm64-3.3.2.tgz",
"integrity": "sha512-6mFtwFJCy1skaf/qzl82OtELmT2BwHXbephfrIFqKoxIghc7N+kiW33J3ZNRP8JhBYFI6xJ8jiatGwPJ7mCOMw==",
"cpu": [
"arm64"
],
@@ -771,9 +771,9 @@
}
},
"node_modules/@koromix/koffi-android-x64": {
"version": "3.3.1",
"resolved": "https://registry.npmjs.org/@koromix/koffi-android-x64/-/koffi-android-x64-3.3.1.tgz",
"integrity": "sha512-QaKSyVi37j19CfN2tR3q8lQMosZ+mQIOQXcNQmWXfYDUs9x2CSCxzvMTeQyFyGdAqB58dBluEiy8V5ZMvARSHg==",
"version": "3.3.2",
"resolved": "https://registry.npmjs.org/@koromix/koffi-android-x64/-/koffi-android-x64-3.3.2.tgz",
"integrity": "sha512-wzIWXvldodHWST6KZBdjJlpdH0DJ2rIN5YppY+/T+mTR1DcRYdYhOXzZMGDDx9W3ao8Hry8G4GqVzK9IuYpuWA==",
"cpu": [
"x64"
],
@@ -787,9 +787,9 @@
}
},
"node_modules/@koromix/koffi-darwin-arm64": {
"version": "3.3.1",
"resolved": "https://registry.npmjs.org/@koromix/koffi-darwin-arm64/-/koffi-darwin-arm64-3.3.1.tgz",
"integrity": "sha512-xVLQMZzACn6TQJsGp/mBF71mfRyuhmxTBGcQLfJM59YArNN/9+1JV8FFCElmgspffijASZsLwbSEdPwZMNeDhQ==",
"version": "3.3.2",
"resolved": "https://registry.npmjs.org/@koromix/koffi-darwin-arm64/-/koffi-darwin-arm64-3.3.2.tgz",
"integrity": "sha512-gQKOkA/4tkOxXP3hdau2MrvVvTYlKQiXd86hK+B2FKErV0QcwqrWt6DWZ3FtJUYGB1scenT0srS9VfsWmbgeMQ==",
"cpu": [
"arm64"
],
@@ -803,9 +803,9 @@
}
},
"node_modules/@koromix/koffi-darwin-x64": {
"version": "3.3.1",
"resolved": "https://registry.npmjs.org/@koromix/koffi-darwin-x64/-/koffi-darwin-x64-3.3.1.tgz",
"integrity": "sha512-+VGqqnBQvR+AbAbRyRDsxK0D6wwAivUURWsyVX8NhR5agf+0+sSAdNMsSy+9DyO7CmioTUVwV+Do+12uWnFrmA==",
"version": "3.3.2",
"resolved": "https://registry.npmjs.org/@koromix/koffi-darwin-x64/-/koffi-darwin-x64-3.3.2.tgz",
"integrity": "sha512-qxysFokAwiMLiWYYVhooWZHSV3REKJErsUjnX9IeG2rAVpWNkdcXUiQ2GMdfH3hZ0f2fuv0fTuv293/tYu1yew==",
"cpu": [
"x64"
],
@@ -819,9 +819,9 @@
}
},
"node_modules/@koromix/koffi-freebsd-arm64": {
"version": "3.3.1",
"resolved": "https://registry.npmjs.org/@koromix/koffi-freebsd-arm64/-/koffi-freebsd-arm64-3.3.1.tgz",
"integrity": "sha512-oPkfxEiLiZs1jV6qqw3DzZy3aigzOb9mGbRtK6ENNgoiZ2QdAw55cXUTOMNiAwgbkBwt7SsorFdUnYUuP5b0Gg==",
"version": "3.3.2",
"resolved": "https://registry.npmjs.org/@koromix/koffi-freebsd-arm64/-/koffi-freebsd-arm64-3.3.2.tgz",
"integrity": "sha512-EinnZVzK3KVTQe0N+XXnUfUN2fwNiYEY5IuAcMqtJO4rbOR+8S+C+bbViUKwqmkLG8OvL/kBesuwGLn5DLNZCQ==",
"cpu": [
"arm64"
],
@@ -835,9 +835,9 @@
}
},
"node_modules/@koromix/koffi-freebsd-ia32": {
"version": "3.3.1",
"resolved": "https://registry.npmjs.org/@koromix/koffi-freebsd-ia32/-/koffi-freebsd-ia32-3.3.1.tgz",
"integrity": "sha512-uLb93keIlk6TkECtb17z2d5nehEIJ2labIXF0ava3s+9w7VE7QZUw3O2IQVq4t95sIm5rMoE1Y+cFa0aN6444w==",
"version": "3.3.2",
"resolved": "https://registry.npmjs.org/@koromix/koffi-freebsd-ia32/-/koffi-freebsd-ia32-3.3.2.tgz",
"integrity": "sha512-gnJFMVbxeyY4dSQbw0p3smSyFGDrp8QzI5krF73QxP7GSIMHR2lplejZseNQGyHIeR3XDdxuJFsfAfXmZdQM3w==",
"cpu": [
"ia32"
],
@@ -851,9 +851,9 @@
}
},
"node_modules/@koromix/koffi-freebsd-x64": {
"version": "3.3.1",
"resolved": "https://registry.npmjs.org/@koromix/koffi-freebsd-x64/-/koffi-freebsd-x64-3.3.1.tgz",
"integrity": "sha512-+Iuh+m5Ln0fjubgw/6bzEkliBcFBIFWWL7IqzmktPy0Q0Bq+XCGtUf+5/KTlodYlTOLv/SE/YTbVkk3c02+E6w==",
"version": "3.3.2",
"resolved": "https://registry.npmjs.org/@koromix/koffi-freebsd-x64/-/koffi-freebsd-x64-3.3.2.tgz",
"integrity": "sha512-56mIFadXceWImQbsO0fN1hoZ76LCIvAjouL4fntoA7IKDI64BFbLSkcJ7Roww31YwxKjJaA9vdk93qt7bXXJZw==",
"cpu": [
"x64"
],
@@ -867,9 +867,9 @@
}
},
"node_modules/@koromix/koffi-linux-arm": {
"version": "3.3.1",
"resolved": "https://registry.npmjs.org/@koromix/koffi-linux-arm/-/koffi-linux-arm-3.3.1.tgz",
"integrity": "sha512-rE6QypE/h4nDHPlzzVPok5W2gL5CopvBYI44lJXO2SauxVAeV86bbf+ucmF/toYENdjF0DBdY7GbloyixwQpPQ==",
"version": "3.3.2",
"resolved": "https://registry.npmjs.org/@koromix/koffi-linux-arm/-/koffi-linux-arm-3.3.2.tgz",
"integrity": "sha512-NhvFzykswakToxAWVhpHf5qA/y8z755MAz4MU1m89yIL1lqUuJDSk6Fy/moD3YIQPOjjuHVf09wO7mlO5ukCbw==",
"cpu": [
"arm"
],
@@ -883,9 +883,9 @@
}
},
"node_modules/@koromix/koffi-linux-arm64": {
"version": "3.3.1",
"resolved": "https://registry.npmjs.org/@koromix/koffi-linux-arm64/-/koffi-linux-arm64-3.3.1.tgz",
"integrity": "sha512-Itv2N+TvBFTSdEZdokM4ydjbBwr6GNKd51+UXoh/5HVXALBRnMQek2QhBnG7z6H9+/p2SB4rqBnvhuLQpv4B7g==",
"version": "3.3.2",
"resolved": "https://registry.npmjs.org/@koromix/koffi-linux-arm64/-/koffi-linux-arm64-3.3.2.tgz",
"integrity": "sha512-adabETUHezNDJ6jpqpJV01oJRW8rI4KWH3xV6EpFlIAXCtj6l4aLCbJ6DbGH8fNmsJBLnWiuLkyoNm8zkVotCw==",
"cpu": [
"arm64"
],
@@ -899,9 +899,9 @@
}
},
"node_modules/@koromix/koffi-linux-ia32": {
"version": "3.3.1",
"resolved": "https://registry.npmjs.org/@koromix/koffi-linux-ia32/-/koffi-linux-ia32-3.3.1.tgz",
"integrity": "sha512-pb1NJ/Ih4MAPB1e2koQOKxGtLuPWKMT3QXxBrPptkkkDz/XpV6+bAA4ys7amXxpA0ybM2u/+VM0gGzdJRThkRg==",
"version": "3.3.2",
"resolved": "https://registry.npmjs.org/@koromix/koffi-linux-ia32/-/koffi-linux-ia32-3.3.2.tgz",
"integrity": "sha512-IMJAp4dg+l1N5Yek43NpDHDVaJFRkMaBnAg9uI3Z1vk61+WxxtaugOl0lC6gDPLBeNE+lzSXcAEeKBIkTwDzdw==",
"cpu": [
"ia32"
],
@@ -915,9 +915,9 @@
}
},
"node_modules/@koromix/koffi-linux-loong64": {
"version": "3.3.1",
"resolved": "https://registry.npmjs.org/@koromix/koffi-linux-loong64/-/koffi-linux-loong64-3.3.1.tgz",
"integrity": "sha512-RdS57JuF39tLXS/yYq4KlFnU7CMrn1+x/4v171bji+1aPYOXPxzYDAJVjapv/6tnrESrMTnfWIja3jfzieFmpQ==",
"version": "3.3.2",
"resolved": "https://registry.npmjs.org/@koromix/koffi-linux-loong64/-/koffi-linux-loong64-3.3.2.tgz",
"integrity": "sha512-Sdf+iQ5Fo3Px6e8xFx7eTES+cAIiHxCLt9KDVmnHm0ls6fW2eTVu5ez1+3GUBb/gjLTMODX2U4+dP9LHagwHHg==",
"cpu": [
"loong64"
],
@@ -931,9 +931,9 @@
}
},
"node_modules/@koromix/koffi-linux-ppc64": {
"version": "3.3.1",
"resolved": "https://registry.npmjs.org/@koromix/koffi-linux-ppc64/-/koffi-linux-ppc64-3.3.1.tgz",
"integrity": "sha512-nmOTpQQS5pWG73X01y7K70JQaL+5T/v04i0G4BtXDAxQq3WHmyeJCgmdHhz5W0JVtjHicitSZoothTspAopF9A==",
"version": "3.3.2",
"resolved": "https://registry.npmjs.org/@koromix/koffi-linux-ppc64/-/koffi-linux-ppc64-3.3.2.tgz",
"integrity": "sha512-FVHtjljl9vUvT6dSsAE1ObOqmPeJXzS8Ez7cidlsI/rJ5pa7h50KQutU/jPfTaK1cqChRjI66hwnJseLG8VPTA==",
"cpu": [
"ppc64"
],
@@ -947,9 +947,9 @@
}
},
"node_modules/@koromix/koffi-linux-riscv64": {
"version": "3.3.1",
"resolved": "https://registry.npmjs.org/@koromix/koffi-linux-riscv64/-/koffi-linux-riscv64-3.3.1.tgz",
"integrity": "sha512-mk0Av5QmK0BPD3OHytOThVhEe4VCTrYv3+em6h75E1rNYiCfixzeh3d5+s5x2vCaby8zzxvNd39sO89Bp1juwg==",
"version": "3.3.2",
"resolved": "https://registry.npmjs.org/@koromix/koffi-linux-riscv64/-/koffi-linux-riscv64-3.3.2.tgz",
"integrity": "sha512-4Q3haXJ3oP5AJ0vlyd9HZsI7gS+s+fycqz1CDDrT6JftlSruIUbfr8be1/jetUlmh7Pd8HtQBM6x2gpQBNTttQ==",
"cpu": [
"riscv64"
],
@@ -963,9 +963,9 @@
}
},
"node_modules/@koromix/koffi-linux-x64": {
"version": "3.3.1",
"resolved": "https://registry.npmjs.org/@koromix/koffi-linux-x64/-/koffi-linux-x64-3.3.1.tgz",
"integrity": "sha512-uU5cJNe145TvITqrUWvBmZO4WLNObdZ2Gnm8eNk/OdrhRFG9LB44RUv07aQwPbdo1438j+Cr+tFNnpjTBadZFQ==",
"version": "3.3.2",
"resolved": "https://registry.npmjs.org/@koromix/koffi-linux-x64/-/koffi-linux-x64-3.3.2.tgz",
"integrity": "sha512-78qO1oqd9GYfzcKOxIaRiN0KgvzQzgbPfdClf0/jErlWYdxnr8gB4i9KOFvsYMdnc7kTIa/wnubl1lPCiQnqvA==",
"cpu": [
"x64"
],
@@ -979,9 +979,9 @@
}
},
"node_modules/@koromix/koffi-openbsd-arm64": {
"version": "3.3.1",
"resolved": "https://registry.npmjs.org/@koromix/koffi-openbsd-arm64/-/koffi-openbsd-arm64-3.3.1.tgz",
"integrity": "sha512-owXmXHI+5kkDyVjqGPfPgIHIzH1swsGY+YNbQ4ozkO23UKzJElAtmQPcmA1pQwiDCeyojHEelgd9+BV58uOIkA==",
"version": "3.3.2",
"resolved": "https://registry.npmjs.org/@koromix/koffi-openbsd-arm64/-/koffi-openbsd-arm64-3.3.2.tgz",
"integrity": "sha512-rB6HZ/RnEAu7CZoD8IMXonCJSD6WJIX8QfZ11RCOy9MXxA8wQR5CRnP3ffy4/8IbABorRoERLLFTFk5wFFZqCw==",
"cpu": [
"arm64"
],
@@ -995,9 +995,9 @@
}
},
"node_modules/@koromix/koffi-openbsd-ia32": {
"version": "3.3.1",
"resolved": "https://registry.npmjs.org/@koromix/koffi-openbsd-ia32/-/koffi-openbsd-ia32-3.3.1.tgz",
"integrity": "sha512-fvIKWycDdc9XL3ATQT0uvt/j82EB3/JWzJU4yqUCJbMotTP8mvo/c1D1Jus4mO+fNGEYM33YuFDkJcQkHJd9Dg==",
"version": "3.3.2",
"resolved": "https://registry.npmjs.org/@koromix/koffi-openbsd-ia32/-/koffi-openbsd-ia32-3.3.2.tgz",
"integrity": "sha512-XmzyeUEsCc8f6n26684mzn73I5VdDBxFydm8JxwYCmvrzfkSkDPU7eQyRoxHDRwgveIK/plmRiMUIj3/7J1flw==",
"cpu": [
"ia32"
],
@@ -1011,9 +1011,9 @@
}
},
"node_modules/@koromix/koffi-openbsd-x64": {
"version": "3.3.1",
"resolved": "https://registry.npmjs.org/@koromix/koffi-openbsd-x64/-/koffi-openbsd-x64-3.3.1.tgz",
"integrity": "sha512-UYk2xNAK5wEyskLtrgTRt+2lwfBOvgaK8UJDz4B2qm57VvRrqb7ye1hzKFZrRVa8NWRPUk6W/zsqZyFHu4BoLA==",
"version": "3.3.2",
"resolved": "https://registry.npmjs.org/@koromix/koffi-openbsd-x64/-/koffi-openbsd-x64-3.3.2.tgz",
"integrity": "sha512-Bt+beMlH6yK4X21+y7lgk+lthjBODfwJjREFITVQH68v8rHWZ5UxV7FBInHZ7ZT0o07G/fgIr2l1DG6SpaTbEA==",
"cpu": [
"x64"
],
@@ -1027,9 +1027,9 @@
}
},
"node_modules/@koromix/koffi-win32-arm64": {
"version": "3.3.1",
"resolved": "https://registry.npmjs.org/@koromix/koffi-win32-arm64/-/koffi-win32-arm64-3.3.1.tgz",
"integrity": "sha512-SZsmAWUKxBHdUR6Z5IJTslOOy0VEFHxoDHMZkn3k0P5TuP/aOZfQYoEa34UwnLI8t2Fmgyhmympth+39tR/XUw==",
"version": "3.3.2",
"resolved": "https://registry.npmjs.org/@koromix/koffi-win32-arm64/-/koffi-win32-arm64-3.3.2.tgz",
"integrity": "sha512-+fLooyTbldECuFH54h1ags7BAOB4fmqnshyVkXr+HbJBhgHdHoIbZ+CcaoH1ELVth7L7G+5XNwbXDH1TOyQMvA==",
"cpu": [
"arm64"
],
@@ -1043,9 +1043,9 @@
}
},
"node_modules/@koromix/koffi-win32-ia32": {
"version": "3.3.1",
"resolved": "https://registry.npmjs.org/@koromix/koffi-win32-ia32/-/koffi-win32-ia32-3.3.1.tgz",
"integrity": "sha512-pARisOvxCPkk6Wg1HkwRCnrkJIVS31kDweWLo+bQay/Dr1915s7skVydWpTKS30EcfOh4Jay7B4c0dgamTLBHg==",
"version": "3.3.2",
"resolved": "https://registry.npmjs.org/@koromix/koffi-win32-ia32/-/koffi-win32-ia32-3.3.2.tgz",
"integrity": "sha512-knegFlqbXsYfWcbIsAHMrKHqVbLctqzYD9xW3+GfO1Dyt+xe1xY8YDiadjRaWtKkLz5uF1aJD886EfBZUhECLA==",
"cpu": [
"ia32"
],
@@ -1059,9 +1059,9 @@
}
},
"node_modules/@koromix/koffi-win32-x64": {
"version": "3.3.1",
"resolved": "https://registry.npmjs.org/@koromix/koffi-win32-x64/-/koffi-win32-x64-3.3.1.tgz",
"integrity": "sha512-LYoO19cTIA7xjl+3s4VeGagCAO38VNXZ969DNszb1wTwJUjrHLrAbHFkk8fYkXineM3HJkFwElW0VLmZqXcfRg==",
"version": "3.3.2",
"resolved": "https://registry.npmjs.org/@koromix/koffi-win32-x64/-/koffi-win32-x64-3.3.2.tgz",
"integrity": "sha512-OWc6s6gziEabkQj+xc+ZNaf5g69hc/DQJLBcmbhxJAifAdXDgj9vB5d8hcjS2mTHjBeAIqQ4nkd9d/Jc7OUuHw==",
"cpu": [
"x64"
],
@@ -1370,15 +1370,15 @@
}
},
"node_modules/@openclaw/ai": {
"version": "2026.10.2",
"resolved": "https://registry.npmjs.org/@openclaw/ai/-/ai-2026.10.2.tgz",
"integrity": "sha512-cgw8vpCfbmnY5Qbe+7gZWN1lsnCuBUFasu2nNjUkDAtKh+RzvPQZudMvkhA34vVhuQZ8KUf6D45dMePWC560Ww==",
"version": "2026.10.6",
"resolved": "https://registry.npmjs.org/@openclaw/ai/-/ai-2026.10.6.tgz",
"integrity": "sha512-cSsfmzCkv3F3GLNkwZ9vL2QVLnrBSV0S4h3v5u48tgpUf6y/ivyhrv0hokPHpWNApQmLTGAAXChKkUTvzAg4tg==",
"license": "MIT",
"dependencies": {
"@anthropic-ai/sdk": "0.128.0",
"@google/genai": "2.24.0",
"@anthropic-ai/sdk": "0.131.0",
"@google/genai": "2.27.0",
"@mistralai/mistralai": "2.7.0",
"openai": "7.23.0",
"openai": "7.27.0",
"partial-json": "0.1.7",
"typebox": "1.3.34"
},
@@ -1387,28 +1387,28 @@
}
},
"node_modules/@openclaw/fs-safe": {
"version": "0.24.2",
"resolved": "https://registry.npmjs.org/@openclaw/fs-safe/-/fs-safe-0.24.2.tgz",
"integrity": "sha512-MEq9TssvajMJTZxXlURwrOP7Or8CSS6c9F02rdG04BEe0LLRmfQqzTtRyrDi3uaj+yxr9tw2Tpy5yrLPuO+oZg==",
"version": "0.25.0",
"resolved": "https://registry.npmjs.org/@openclaw/fs-safe/-/fs-safe-0.25.0.tgz",
"integrity": "sha512-/8XzfW0zulV1BPzjnkD7vRG12u0u517w00rIuAGmW4GU07fxatYSkLHc1GaFCSX/WuLwGPzoxjPSKuRloBprIQ==",
"license": "MIT",
"engines": {
"node": ">=22"
},
"optionalDependencies": {
"@openclaw/fs-safe-darwin-arm64": "0.24.2",
"@openclaw/fs-safe-darwin-x64": "0.24.2",
"@openclaw/fs-safe-linux-arm64-gnu": "0.24.2",
"@openclaw/fs-safe-linux-arm64-musl": "0.24.2",
"@openclaw/fs-safe-linux-x64-gnu": "0.24.2",
"@openclaw/fs-safe-linux-x64-musl": "0.24.2",
"@openclaw/fs-safe-win32-x64-msvc": "0.24.2",
"@openclaw/fs-safe-darwin-arm64": "0.25.0",
"@openclaw/fs-safe-darwin-x64": "0.25.0",
"@openclaw/fs-safe-linux-arm64-gnu": "0.25.0",
"@openclaw/fs-safe-linux-arm64-musl": "0.25.0",
"@openclaw/fs-safe-linux-x64-gnu": "0.25.0",
"@openclaw/fs-safe-linux-x64-musl": "0.25.0",
"@openclaw/fs-safe-win32-x64-msvc": "0.25.0",
"jszip": "^3.10.2"
}
},
"node_modules/@openclaw/fs-safe-darwin-arm64": {
"version": "0.24.2",
"resolved": "https://registry.npmjs.org/@openclaw/fs-safe-darwin-arm64/-/fs-safe-darwin-arm64-0.24.2.tgz",
"integrity": "sha512-rzAAoT0l4JGg4ZcqDz0F+OYcT9lz3I0recweHyqcF1zXydrMF4ZCyWkGOL0+wwJGJJgaWU56614jq+Ox9j/4Bw==",
"version": "0.25.0",
"resolved": "https://registry.npmjs.org/@openclaw/fs-safe-darwin-arm64/-/fs-safe-darwin-arm64-0.25.0.tgz",
"integrity": "sha512-ftwB6/cM4bdWXn2pBwUSEL4A5ZnX5jh6aEPBhS5Q3Yd/bQgJyWIFTNv4+kC+4QrufuX20/VF/kIjPyu17RcDMg==",
"cpu": [
"arm64"
],
@@ -1422,9 +1422,9 @@
}
},
"node_modules/@openclaw/fs-safe-darwin-x64": {
"version": "0.24.2",
"resolved": "https://registry.npmjs.org/@openclaw/fs-safe-darwin-x64/-/fs-safe-darwin-x64-0.24.2.tgz",
"integrity": "sha512-ai5h+Xr7NIoL0PMmlqoS8pbBqU/FjitFtZnXA50KZ+j/WCDi0yYCd5H8mhO8B3Q6REMALB3m7m4Ee33PlrS+/w==",
"version": "0.25.0",
"resolved": "https://registry.npmjs.org/@openclaw/fs-safe-darwin-x64/-/fs-safe-darwin-x64-0.25.0.tgz",
"integrity": "sha512-HFAAytEr0MN4zZwoLiv3oLmDOJFchanUHl5gi5YQyPTqf7/C0AEuPcR1+gP0dWpuccCEmuxivKE30yriw+WUUw==",
"cpu": [
"x64"
],
@@ -1438,9 +1438,9 @@
}
},
"node_modules/@openclaw/fs-safe-linux-arm64-gnu": {
"version": "0.24.2",
"resolved": "https://registry.npmjs.org/@openclaw/fs-safe-linux-arm64-gnu/-/fs-safe-linux-arm64-gnu-0.24.2.tgz",
"integrity": "sha512-rT0tCzQMbYBgnU8S28xeY6XsysCvvFFXOoslAR+WON+JigVdckDVQZ87JUwr6QBOMKbOYc8BtKCVR3cRbZH7SQ==",
"version": "0.25.0",
"resolved": "https://registry.npmjs.org/@openclaw/fs-safe-linux-arm64-gnu/-/fs-safe-linux-arm64-gnu-0.25.0.tgz",
"integrity": "sha512-7Cpa7T7s53TpPMH3Uc5iB3SqzHmta/jsU+2xrdBxTk/Ztc2bKy21hPlaoEI/ITMdXL1L0bYxaRvlIzoJH+6XKw==",
"cpu": [
"arm64"
],
@@ -1454,9 +1454,9 @@
}
},
"node_modules/@openclaw/fs-safe-linux-arm64-musl": {
"version": "0.24.2",
"resolved": "https://registry.npmjs.org/@openclaw/fs-safe-linux-arm64-musl/-/fs-safe-linux-arm64-musl-0.24.2.tgz",
"integrity": "sha512-Ij24lYQSNLDO468uQ6OW+0tVXmy+QbC534N9EgdF8NzV4oQDWagiSpf/sdUTAgPp6ojAFh0Z6WMqC3KENCX/aQ==",
"version": "0.25.0",
"resolved": "https://registry.npmjs.org/@openclaw/fs-safe-linux-arm64-musl/-/fs-safe-linux-arm64-musl-0.25.0.tgz",
"integrity": "sha512-9ZeTBNh1OKCSCZzc1Ne4SN96IlFA1qrHs1yclP8vxCXFXGgkTFyX2xwZ8qLuONodPDezifqVxzP66tGvyBQadw==",
"cpu": [
"arm64"
],
@@ -1470,9 +1470,9 @@
}
},
"node_modules/@openclaw/fs-safe-linux-x64-gnu": {
"version": "0.24.2",
"resolved": "https://registry.npmjs.org/@openclaw/fs-safe-linux-x64-gnu/-/fs-safe-linux-x64-gnu-0.24.2.tgz",
"integrity": "sha512-5I8s6XuvEcG231DdJ3DXsaIFz81ieiyJbQWJeSASHwhIsuKjICZx8NK+ujrjms32iutsvE2MbMQ5crwBpPCkEw==",
"version": "0.25.0",
"resolved": "https://registry.npmjs.org/@openclaw/fs-safe-linux-x64-gnu/-/fs-safe-linux-x64-gnu-0.25.0.tgz",
"integrity": "sha512-/OMLec2NpYuBRnDeexaKwJEkgIBrUO78AxSEBqoJpAzbZ9foLvtwxyEyOZfqnTrtrHwkY1PC+ebNMQbZDj6Z7g==",
"cpu": [
"x64"
],
@@ -1486,9 +1486,9 @@
}
},
"node_modules/@openclaw/fs-safe-linux-x64-musl": {
"version": "0.24.2",
"resolved": "https://registry.npmjs.org/@openclaw/fs-safe-linux-x64-musl/-/fs-safe-linux-x64-musl-0.24.2.tgz",
"integrity": "sha512-Ebu436lbC2Ytt8t88gO43REPrtldjFeD9NuJeuKZEL/jbHfzWApCnxDFYN1p/B6iAUKVlbt/ez4bReFcQm6Fdw==",
"version": "0.25.0",
"resolved": "https://registry.npmjs.org/@openclaw/fs-safe-linux-x64-musl/-/fs-safe-linux-x64-musl-0.25.0.tgz",
"integrity": "sha512-WQXl6zfqS4nbWwDsMx7cAH0jI8sD8DRLrgLv2pygM7lPgbX5zVC7mz8reI632qyYJBHYbg0l+FymNUk0YxocFg==",
"cpu": [
"x64"
],
@@ -1502,9 +1502,9 @@
}
},
"node_modules/@openclaw/fs-safe-win32-x64-msvc": {
"version": "0.24.2",
"resolved": "https://registry.npmjs.org/@openclaw/fs-safe-win32-x64-msvc/-/fs-safe-win32-x64-msvc-0.24.2.tgz",
"integrity": "sha512-W68nGloWTm9hQnbeovnku6lQhQ7CEEFvx0fhlpGYGw0+nGRcmSIz31D7K+cNolZZ9HloWlysxvim9Ii2kNaaxQ==",
"version": "0.25.0",
"resolved": "https://registry.npmjs.org/@openclaw/fs-safe-win32-x64-msvc/-/fs-safe-win32-x64-msvc-0.25.0.tgz",
"integrity": "sha512-O4cDKqwownShG/LvhxrrQl5sa9D8WSCTT51vzmugi8dAdXGLwaEa+qtpSWJEfA2BY9rQW3ohipHEO92uO52Gbw==",
"cpu": [
"x64"
],
@@ -1517,6 +1517,18 @@
"node": ">=22"
}
},
"node_modules/@openclaw/proxyline": {
"version": "0.4.0",
"resolved": "https://registry.npmjs.org/@openclaw/proxyline/-/proxyline-0.4.0.tgz",
"integrity": "sha512-Yd32LmKmu1kHrc7Wt8OHK0z+Tjc52fOfWYHl2znIGqskPrC/YaIKUgrhG4x7/oAemGMwBWHf3Eb3iaMKpZ/otg==",
"license": "MIT",
"engines": {
"node": ">=22.19.0"
},
"peerDependencies": {
"undici": ">=8.5.0 <9"
}
},
"node_modules/@opentelemetry/semantic-conventions": {
"version": "1.43.0",
"resolved": "https://registry.npmjs.org/@opentelemetry/semantic-conventions/-/semantic-conventions-1.43.0.tgz",
@@ -1637,27 +1649,27 @@
"license": "MIT"
},
"node_modules/@trycua/cua-driver": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@trycua/cua-driver/-/cua-driver-0.28.2.tgz",
"integrity": "sha512-18DHs68WpIdKtkAMecd5mLKwJtT854gXzie24Ag0QMxveRNgzKphAje51t0oeI7ZnHetyXKDAQUr5fQyZu7S6Q==",
"version": "0.32.0",
"resolved": "https://registry.npmjs.org/@trycua/cua-driver/-/cua-driver-0.32.0.tgz",
"integrity": "sha512-lg53Ayp2PuI7RdI7NvHerD7Y8/EzSZnfxHkBd9E2xei3XkP4tcmZaVAu10qK9jkAhhTTIwz0wC6pe4IJDza18A==",
"license": "MIT",
"dependencies": {
"@ubjs/core": "0.31.0-3",
"@ubjs/node": "0.31.0-3"
},
"optionalDependencies": {
"@trycua/cua-driver-darwin-arm64": "0.28.2",
"@trycua/cua-driver-darwin-x64": "0.28.2",
"@trycua/cua-driver-linux-arm64-gnu": "0.28.2",
"@trycua/cua-driver-linux-x64-gnu": "0.28.2",
"@trycua/cua-driver-win32-arm64-msvc": "0.28.2",
"@trycua/cua-driver-win32-x64-msvc": "0.28.2"
"@trycua/cua-driver-darwin-arm64": "0.32.0",
"@trycua/cua-driver-darwin-x64": "0.32.0",
"@trycua/cua-driver-linux-arm64-gnu": "0.32.0",
"@trycua/cua-driver-linux-x64-gnu": "0.32.0",
"@trycua/cua-driver-win32-arm64-msvc": "0.32.0",
"@trycua/cua-driver-win32-x64-msvc": "0.32.0"
}
},
"node_modules/@trycua/cua-driver-darwin-arm64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@trycua/cua-driver-darwin-arm64/-/cua-driver-darwin-arm64-0.28.2.tgz",
"integrity": "sha512-Eeo62jJjxi67/XwSQKvxpJQMmJg7pjLqGa4vZTxLj3KUmjfGYjwt3wifLl82yU0AfJs6icB7V1uu6sYE+nm9mg==",
"version": "0.32.0",
"resolved": "https://registry.npmjs.org/@trycua/cua-driver-darwin-arm64/-/cua-driver-darwin-arm64-0.32.0.tgz",
"integrity": "sha512-wSUwXMj/KJPi+SEy3PfrN94p2ji8TOlIxQn4kPw8GG0NtiVqtfdOA7kOcjLZZeeJdTlS/r0PKKlghG+5JrC9PQ==",
"cpu": [
"arm64"
],
@@ -1668,9 +1680,9 @@
]
},
"node_modules/@trycua/cua-driver-darwin-x64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@trycua/cua-driver-darwin-x64/-/cua-driver-darwin-x64-0.28.2.tgz",
"integrity": "sha512-n7iWl2iqIyPoDpCJ3hyK2gKZqu0RTolabRptmZKYPzRSTbRbzO3mejOa+CXHsJjVbM4+FyDJDNn5NE2CZLMdXg==",
"version": "0.32.0",
"resolved": "https://registry.npmjs.org/@trycua/cua-driver-darwin-x64/-/cua-driver-darwin-x64-0.32.0.tgz",
"integrity": "sha512-9Q61a7XHSPycuT0fTQtmTT+fbXkVEL05iHgaRv+OtYHTyzJG1KVpTjntJsSlaQgD7NVl1uAapumZ9gMmvrOhuQ==",
"cpu": [
"x64"
],
@@ -1681,9 +1693,9 @@
]
},
"node_modules/@trycua/cua-driver-linux-arm64-gnu": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@trycua/cua-driver-linux-arm64-gnu/-/cua-driver-linux-arm64-gnu-0.28.2.tgz",
"integrity": "sha512-ZFrYmA53ooEGyImEHo7cxYxgyXidP6Mkxc1KYiM8KoFmeHFSX3TmuKDsVV9dwZGKrhAOJBvQTvLvlb85RlccQg==",
"version": "0.32.0",
"resolved": "https://registry.npmjs.org/@trycua/cua-driver-linux-arm64-gnu/-/cua-driver-linux-arm64-gnu-0.32.0.tgz",
"integrity": "sha512-E3fJdJYnfguFbEK9VRqqVnT8yMZZKTSxZz08kmF7DAXnKNQ7mfQTdqNeC1qCrx5JuIRyPp7dyBCTQdUAVqEAaA==",
"cpu": [
"arm64"
],
@@ -1694,9 +1706,9 @@
]
},
"node_modules/@trycua/cua-driver-linux-x64-gnu": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@trycua/cua-driver-linux-x64-gnu/-/cua-driver-linux-x64-gnu-0.28.2.tgz",
"integrity": "sha512-mZp8rRyaT0/gUXnHGAC53EKA6WHKvRbliacMVsiwf/EEUOLNtz6pRNfhYyF4GLT6jHbC/Xwu8V9kpntz9Tssdg==",
"version": "0.32.0",
"resolved": "https://registry.npmjs.org/@trycua/cua-driver-linux-x64-gnu/-/cua-driver-linux-x64-gnu-0.32.0.tgz",
"integrity": "sha512-br78WwTofTHMAq7HZgKUDYvjLXZsLF2tUX5lKniJ20D6GXq41m5PHakuFBRAJFvA6wAdpoqZE7TsrMxnFbyMog==",
"cpu": [
"x64"
],
@@ -1707,9 +1719,9 @@
]
},
"node_modules/@trycua/cua-driver-win32-arm64-msvc": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@trycua/cua-driver-win32-arm64-msvc/-/cua-driver-win32-arm64-msvc-0.28.2.tgz",
"integrity": "sha512-prShQ7VSVXMkytMGj+d43u54/9H3K0nJT5OOAqT3S78XATw7dlu1ESdEacr/J2lNcmn5mxwEy+i+9HRmEt0DJw==",
"version": "0.32.0",
"resolved": "https://registry.npmjs.org/@trycua/cua-driver-win32-arm64-msvc/-/cua-driver-win32-arm64-msvc-0.32.0.tgz",
"integrity": "sha512-HrxAEGWTf5IO5PudG8apCUW3wnJFTYnCAxfR4PKDzRWBcFdc/fEPW4S3qrYL7i8St8gLPoPSasOgAmLm2InxBQ==",
"cpu": [
"arm64"
],
@@ -1720,9 +1732,9 @@
]
},
"node_modules/@trycua/cua-driver-win32-x64-msvc": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@trycua/cua-driver-win32-x64-msvc/-/cua-driver-win32-x64-msvc-0.28.2.tgz",
"integrity": "sha512-H7pUIwbrKCqkyDBcI4ovk1ggN+MOmFtATGl0fokPkD7dp1EHGn5I9vRJEPVvqjP0BTwdlBJ8NucIy0g2eFK86Q==",
"version": "0.32.0",
"resolved": "https://registry.npmjs.org/@trycua/cua-driver-win32-x64-msvc/-/cua-driver-win32-x64-msvc-0.32.0.tgz",
"integrity": "sha512-gOcMNjdL42z1QhRFz8ZMIkfmsLWqsqE72RChO9NSj9eeH8XNK31RKZv+KONhCxfL9Hq1sfM2dgozQ33qxFiYlQ==",
"cpu": [
"x64"
],
@@ -2166,9 +2178,9 @@
}
},
"node_modules/chalk": {
"version": "6.0.0",
"resolved": "https://registry.npmjs.org/chalk/-/chalk-6.0.0.tgz",
"integrity": "sha512-2uNTXIuTTxk7ciZgAU1BQcgnchcG0xXnrs6jzkQfj9SsRa9M2s5zE8WT96hS6KmG4MzWHSrvH43DF1m4XRkrFg==",
"version": "6.0.1",
"resolved": "https://registry.npmjs.org/chalk/-/chalk-6.0.1.tgz",
"integrity": "sha512-/Ce6KNm3vIbWdMlNna6RVIZ/ICQxnJxCicet5LBKK9ZffBkqzDw0xh9EiKSljdRtiIQ1S1z4YgcscUUGzNCWrA==",
"license": "MIT",
"engines": {
"node": ">=22"
@@ -2512,9 +2524,9 @@
}
},
"node_modules/dotenv": {
"version": "18.0.3",
"resolved": "https://registry.npmjs.org/dotenv/-/dotenv-18.0.3.tgz",
"integrity": "sha512-/8CJTyL817qPnfbQrJgOEcrU3fDrJkRIoXBE566wHuvIXKOCHUZhPqGPbCPi9SogjdGnreF0TlvnTgK6J/8zpA==",
"version": "18.0.5",
"resolved": "https://registry.npmjs.org/dotenv/-/dotenv-18.0.5.tgz",
"integrity": "sha512-aBrGvt6KhjxbEnatqMWOMidftwsrCiCvqh1yNIGB9QyF0J+VcWkKDMsvYOEm7ZS82oiV+BT1sTOtIlAmUlTpwQ==",
"license": "BSD-2-Clause",
"bin": {
"dotenv": "dist/index.cjs"
@@ -3403,9 +3415,9 @@
"license": "BSD-3-Clause"
},
"node_modules/ignore": {
"version": "7.0.9",
"resolved": "https://registry.npmjs.org/ignore/-/ignore-7.0.9.tgz",
"integrity": "sha512-brTTsvFRt5C1gGHtPst/281UjPD5t9fBqbgoMPlVWy11ZLTPfu7HxK4ZYqO9H7o/yC9rSTCI85EaQ4OoY12qYw==",
"version": "7.0.12",
"resolved": "https://registry.npmjs.org/ignore/-/ignore-7.0.12.tgz",
"integrity": "sha512-/8UvqAPU9DGTI9k4mxtf49U37Isfwr8Uts96+SBHIkFxPJnHS0Ew4f00sM4Scd8V8EjM0jUNtVDdv1kPdt35lg==",
"license": "MIT",
"engines": {
"node": ">= 4"
@@ -3524,9 +3536,9 @@
}
},
"node_modules/jose": {
"version": "6.2.12",
"resolved": "https://registry.npmjs.org/jose/-/jose-6.2.12.tgz",
"integrity": "sha512-9NiFmJEex0sy2Dk58j2UGBSHgUs2ypF9eZSu4L6vjOX3Dp96Sw1F3uL+H+D1sx02jZZdzUT0HgvCy59CuvXcWw==",
"version": "6.2.13",
"resolved": "https://registry.npmjs.org/jose/-/jose-6.2.13.tgz",
"integrity": "sha512-7TIg10ZE1x82YediN+lcrPNvGMKge9yFHQD+Qho/b8y2adfugU3AsvvHfxV0fzyFllT6l9xCjf4RWY9g/Z9PJQ==",
"license": "MIT",
"funding": {
"url": "https://github.com/sponsors/panva"
@@ -3630,35 +3642,35 @@
}
},
"node_modules/koffi": {
"version": "3.3.1",
"resolved": "https://registry.npmjs.org/koffi/-/koffi-3.3.1.tgz",
"integrity": "sha512-FZYfhBfYQr/cmHhZpaQ9rhbKpkjHhxaytn2A0mbPhiD5yV8QzF3SiQwR1w/34rCJ1fw+6qBQSj/ZoXRdC+Xc2Q==",
"version": "3.3.2",
"resolved": "https://registry.npmjs.org/koffi/-/koffi-3.3.2.tgz",
"integrity": "sha512-f9Rrcmpy7lQs0ayJfhaxiG5OLp1aZjXKOFLXo7Gax6snJRKmdpYnYEOkpQ7ImCBrbvOdzFT06EP+FaLZv35W7Q==",
"hasInstallScript": true,
"license": "MIT",
"funding": {
"url": "https://liberapay.com/Koromix"
},
"optionalDependencies": {
"@koromix/koffi-android-arm64": "3.3.1",
"@koromix/koffi-android-x64": "3.3.1",
"@koromix/koffi-darwin-arm64": "3.3.1",
"@koromix/koffi-darwin-x64": "3.3.1",
"@koromix/koffi-freebsd-arm64": "3.3.1",
"@koromix/koffi-freebsd-ia32": "3.3.1",
"@koromix/koffi-freebsd-x64": "3.3.1",
"@koromix/koffi-linux-arm": "3.3.1",
"@koromix/koffi-linux-arm64": "3.3.1",
"@koromix/koffi-linux-ia32": "3.3.1",
"@koromix/koffi-linux-loong64": "3.3.1",
"@koromix/koffi-linux-ppc64": "3.3.1",
"@koromix/koffi-linux-riscv64": "3.3.1",
"@koromix/koffi-linux-x64": "3.3.1",
"@koromix/koffi-openbsd-arm64": "3.3.1",
"@koromix/koffi-openbsd-ia32": "3.3.1",
"@koromix/koffi-openbsd-x64": "3.3.1",
"@koromix/koffi-win32-arm64": "3.3.1",
"@koromix/koffi-win32-ia32": "3.3.1",
"@koromix/koffi-win32-x64": "3.3.1"
"@koromix/koffi-android-arm64": "3.3.2",
"@koromix/koffi-android-x64": "3.3.2",
"@koromix/koffi-darwin-arm64": "3.3.2",
"@koromix/koffi-darwin-x64": "3.3.2",
"@koromix/koffi-freebsd-arm64": "3.3.2",
"@koromix/koffi-freebsd-ia32": "3.3.2",
"@koromix/koffi-freebsd-x64": "3.3.2",
"@koromix/koffi-linux-arm": "3.3.2",
"@koromix/koffi-linux-arm64": "3.3.2",
"@koromix/koffi-linux-ia32": "3.3.2",
"@koromix/koffi-linux-loong64": "3.3.2",
"@koromix/koffi-linux-ppc64": "3.3.2",
"@koromix/koffi-linux-riscv64": "3.3.2",
"@koromix/koffi-linux-x64": "3.3.2",
"@koromix/koffi-openbsd-arm64": "3.3.2",
"@koromix/koffi-openbsd-ia32": "3.3.2",
"@koromix/koffi-openbsd-x64": "3.3.2",
"@koromix/koffi-win32-arm64": "3.3.2",
"@koromix/koffi-win32-ia32": "3.3.2",
"@koromix/koffi-win32-x64": "3.3.2"
}
},
"node_modules/kysely": {
@@ -5873,15 +5885,19 @@
}
},
"node_modules/on-finished": {
"version": "2.4.1",
"resolved": "https://registry.npmjs.org/on-finished/-/on-finished-2.4.1.tgz",
"integrity": "sha512-oVlzkg3ENAhCk2zdv7IJwd/QUD4z2RxRwpkcGY8psCVcCYZNq4wYnVWALHM+brtuJjePWiYF/ClmuDr8Ch5+kg==",
"version": "2.4.2",
"resolved": "https://registry.npmjs.org/on-finished/-/on-finished-2.4.2.tgz",
"integrity": "sha512-ATWUv387i+nLD49EiDoOft5scf32Vsdz3ktrQJG9bi7jRFmaXTssvyvj1EmeKVVgvesbqUtvQQvaS2TpTukAZQ==",
"license": "MIT",
"dependencies": {
"ee-first": "1.1.1"
},
"engines": {
"node": ">= 0.8"
},
"funding": {
"type": "opencollective",
"url": "https://opencollective.com/express"
}
},
"node_modules/once": {
@@ -5894,9 +5910,9 @@
}
},
"node_modules/openai": {
"version": "7.23.0",
"resolved": "https://registry.npmjs.org/openai/-/openai-7.23.0.tgz",
"integrity": "sha512-0ecOXnFSMNWZq6cUBcTV6Lf93y+fm8BH/+QzFvpoP1UGNOE5pnytRa6HAPGCw+3IS9SIAW7rc1M8yyzN1PiBAQ==",
"version": "7.27.0",
"resolved": "https://registry.npmjs.org/openai/-/openai-7.27.0.tgz",
"integrity": "sha512-QDo1FvnRDZn15YwGVOhT9vpyypDiLphkd/7a4mcURWf5upMoEetgA6o4DJeII+ZZkC6m6DvlilCwii3+ynDcTw==",
"license": "Apache-2.0",
"engines": {
"node": ">=22.0.0"
@@ -5931,45 +5947,43 @@
}
},
"node_modules/openclaw": {
"version": "2026.10.2",
"resolved": "https://registry.npmjs.org/openclaw/-/openclaw-2026.10.2.tgz",
"integrity": "sha512-FuLLF+WI12ypwQ0r+pcKDcmB+kXus5N4QClaKEnaAn6GN4I1AitkOhwv0GFl2rVKpvuUBDQWIfglHNy6Trv/EQ==",
"version": "2026.10.6",
"resolved": "https://registry.npmjs.org/openclaw/-/openclaw-2026.10.6.tgz",
"integrity": "sha512-jSpQPa2Jw5rG0J2GC07j9+qHtVYIuoHjgccU88JeS+p7188sBCnvIJeuaiNPHj1zsWkuHcBv443QiEUh7qrxwA==",
"bundleDependencies": [
"@openclaw/proxyline",
"chrome-devtools-mcp",
"undici"
"chrome-devtools-mcp"
],
"hasInstallScript": true,
"license": "MIT",
"dependencies": {
"@agentclientprotocol/sdk": "1.5.0",
"@anthropic-ai/sdk": "0.128.0",
"@agentclientprotocol/sdk": "1.7.0",
"@anthropic-ai/sdk": "0.131.0",
"@babel/generator": "8.0.6",
"@babel/parser": "8.0.6",
"@babel/traverse": "8.0.6",
"@clack/core": "1.5.1",
"@clack/prompts": "1.8.1",
"@earendil-works/pi-tui": "0.86.1",
"@google/genai": "2.24.0",
"@earendil-works/pi-tui": "1.0.0",
"@google/genai": "2.27.0",
"@grammyjs/transformer-throttler": "1.2.1",
"@homebridge/ciao": "1.3.12",
"@lydell/node-pty": "1.2.0-beta.15",
"@mistralai/mistralai": "2.7.0",
"@modelcontextprotocol/sdk": "1.31.0",
"@modelcontextprotocol/sdk": "1.32.0",
"@mozilla/readability": "0.6.0",
"@openclaw/ai": "2026.10.2",
"@openclaw/fs-safe": "0.24.2",
"@openclaw/proxyline": "0.3.12",
"@openclaw/ai": "2026.10.6",
"@openclaw/fs-safe": "0.25.0",
"@openclaw/proxyline": "0.4.0",
"@silvia-odwyer/photon-node": "0.3.4",
"@trycua/cua-driver": "0.28.2",
"@trycua/cua-driver": "0.32.0",
"acorn": "8.18.0",
"chalk": "6.0.0",
"chalk": "6.0.1",
"chrome-devtools-mcp": "1.10.1",
"clawpdf": "0.3.2",
"commander": "15.0.0",
"croner": "10.0.1",
"diff": "9.0.0",
"dotenv": "18.0.3",
"dotenv": "18.0.5",
"entities": "8.1.0",
"esbuild": "0.28.2",
"execa": "10.0.1",
@@ -5978,25 +5992,26 @@
"grammy": "1.46.0",
"highlight.js": "11.12.0",
"hosted-git-info": "10.1.1",
"htmlparser2": "12.0.0",
"iconv-lite": "0.7.3",
"ignore": "7.0.9",
"ignore": "7.0.12",
"import-meta-resolve": "4.2.0",
"jiti": "2.7.0",
"json5": "2.2.3",
"jszip": "3.10.2",
"koffi": "3.3.1",
"koffi": "3.3.2",
"kysely": "0.29.6",
"linkedom": "0.18.13",
"minimatch": "10.2.6",
"node-edge-tts": "1.2.10",
"npm": "12.1.0",
"openai": "7.23.0",
"npm": "12.2.0",
"openai": "7.27.0",
"p-limit": "7.3.3",
"p-map": "7.0.8",
"partial-json": "0.1.7",
"playwright-core": "1.63.0",
"qrcode": "1.5.4",
"rastermill": "0.3.3",
"rastermill": "0.4.0",
"semver": "7.8.5",
"tar": "7.5.22",
"tslog": "5.2.0",
@@ -6004,7 +6019,7 @@
"undici": "8.11.2",
"web-push": "3.6.7",
"web-tree-sitter": "0.27.0",
"ws": "8.21.3",
"ws": "8.22.0",
"yaml": "2.9.1",
"zod": "4.6.5"
},
@@ -6012,7 +6027,7 @@
"openclaw": "openclaw.mjs"
},
"engines": {
"node": ">=24.16.0 <25 || >=26.1.0"
"node": ">=24.22.1 <25 || >=26.12.1"
},
"optionalDependencies": {
"@esbuild/aix-ppc64": "0.28.2",
@@ -6041,45 +6056,45 @@
"@esbuild/win32-arm64": "0.28.2",
"@esbuild/win32-ia32": "0.28.2",
"@esbuild/win32-x64": "0.28.2",
"@koromix/koffi-android-arm64": "3.3.1",
"@koromix/koffi-android-x64": "3.3.1",
"@koromix/koffi-darwin-arm64": "3.3.1",
"@koromix/koffi-darwin-x64": "3.3.1",
"@koromix/koffi-freebsd-arm64": "3.3.1",
"@koromix/koffi-freebsd-ia32": "3.3.1",
"@koromix/koffi-freebsd-x64": "3.3.1",
"@koromix/koffi-linux-arm": "3.3.1",
"@koromix/koffi-linux-arm64": "3.3.1",
"@koromix/koffi-linux-ia32": "3.3.1",
"@koromix/koffi-linux-loong64": "3.3.1",
"@koromix/koffi-linux-ppc64": "3.3.1",
"@koromix/koffi-linux-riscv64": "3.3.1",
"@koromix/koffi-linux-x64": "3.3.1",
"@koromix/koffi-openbsd-arm64": "3.3.1",
"@koromix/koffi-openbsd-ia32": "3.3.1",
"@koromix/koffi-openbsd-x64": "3.3.1",
"@koromix/koffi-win32-arm64": "3.3.1",
"@koromix/koffi-win32-ia32": "3.3.1",
"@koromix/koffi-win32-x64": "3.3.1",
"@koromix/koffi-android-arm64": "3.3.2",
"@koromix/koffi-android-x64": "3.3.2",
"@koromix/koffi-darwin-arm64": "3.3.2",
"@koromix/koffi-darwin-x64": "3.3.2",
"@koromix/koffi-freebsd-arm64": "3.3.2",
"@koromix/koffi-freebsd-ia32": "3.3.2",
"@koromix/koffi-freebsd-x64": "3.3.2",
"@koromix/koffi-linux-arm": "3.3.2",
"@koromix/koffi-linux-arm64": "3.3.2",
"@koromix/koffi-linux-ia32": "3.3.2",
"@koromix/koffi-linux-loong64": "3.3.2",
"@koromix/koffi-linux-ppc64": "3.3.2",
"@koromix/koffi-linux-riscv64": "3.3.2",
"@koromix/koffi-linux-x64": "3.3.2",
"@koromix/koffi-openbsd-arm64": "3.3.2",
"@koromix/koffi-openbsd-ia32": "3.3.2",
"@koromix/koffi-openbsd-x64": "3.3.2",
"@koromix/koffi-win32-arm64": "3.3.2",
"@koromix/koffi-win32-ia32": "3.3.2",
"@koromix/koffi-win32-x64": "3.3.2",
"@lydell/node-pty-darwin-arm64": "1.2.0-beta.15",
"@lydell/node-pty-darwin-x64": "1.2.0-beta.15",
"@lydell/node-pty-linux-arm64": "1.2.0-beta.15",
"@lydell/node-pty-linux-x64": "1.2.0-beta.15",
"@lydell/node-pty-win32-arm64": "1.2.0-beta.15",
"@lydell/node-pty-win32-x64": "1.2.0-beta.15",
"@openclaw/fs-safe-darwin-arm64": "0.24.2",
"@openclaw/fs-safe-darwin-x64": "0.24.2",
"@openclaw/fs-safe-linux-arm64-gnu": "0.24.2",
"@openclaw/fs-safe-linux-arm64-musl": "0.24.2",
"@openclaw/fs-safe-linux-x64-gnu": "0.24.2",
"@openclaw/fs-safe-linux-x64-musl": "0.24.2",
"@openclaw/fs-safe-win32-x64-msvc": "0.24.2",
"@trycua/cua-driver-darwin-arm64": "0.28.2",
"@trycua/cua-driver-darwin-x64": "0.28.2",
"@trycua/cua-driver-linux-arm64-gnu": "0.28.2",
"@trycua/cua-driver-linux-x64-gnu": "0.28.2",
"@trycua/cua-driver-win32-arm64-msvc": "0.28.2",
"@trycua/cua-driver-win32-x64-msvc": "0.28.2",
"@openclaw/fs-safe-darwin-arm64": "0.25.0",
"@openclaw/fs-safe-darwin-x64": "0.25.0",
"@openclaw/fs-safe-linux-arm64-gnu": "0.25.0",
"@openclaw/fs-safe-linux-arm64-musl": "0.25.0",
"@openclaw/fs-safe-linux-x64-gnu": "0.25.0",
"@openclaw/fs-safe-linux-x64-musl": "0.25.0",
"@openclaw/fs-safe-win32-x64-msvc": "0.25.0",
"@trycua/cua-driver-darwin-arm64": "0.32.0",
"@trycua/cua-driver-darwin-x64": "0.32.0",
"@trycua/cua-driver-linux-arm64-gnu": "0.32.0",
"@trycua/cua-driver-linux-x64-gnu": "0.32.0",
"@trycua/cua-driver-win32-arm64-msvc": "0.32.0",
"@trycua/cua-driver-win32-x64-msvc": "0.32.0",
"@ubjs/node-darwin-arm64": "0.31.0-3",
"@ubjs/node-darwin-x64": "0.31.0-3",
"@ubjs/node-linux-arm64-gnu": "0.31.0-3",
@@ -6096,17 +6111,6 @@
"sqlite-vec-windows-x64": "0.1.9"
}
},
"node_modules/openclaw/node_modules/@openclaw/proxyline": {
"version": "0.3.12",
"inBundle": true,
"license": "MIT",
"engines": {
"node": ">=22.19.0"
},
"peerDependencies": {
"undici": ">=8.5.0 <9"
}
},
"node_modules/openclaw/node_modules/chrome-devtools-mcp": {
"version": "1.10.1",
"inBundle": true,
@@ -6131,12 +6135,26 @@
}
}
},
"node_modules/openclaw/node_modules/undici": {
"version": "8.11.2",
"inBundle": true,
"node_modules/openclaw/node_modules/htmlparser2": {
"version": "12.0.0",
"resolved": "https://registry.npmjs.org/htmlparser2/-/htmlparser2-12.0.0.tgz",
"integrity": "sha512-Tz7u1i95/g2x2jz81+x0FBVhBhY5aRTvD3tXXdFaljuNdzDLJ8UGNRrTcj2cgQvAg3iW/h77Fz15nLW0L0CrZw==",
"funding": [
"https://github.com/fb55/htmlparser2?sponsor=1",
{
"type": "github",
"url": "https://github.com/sponsors/fb55"
}
],
"license": "MIT",
"dependencies": {
"domelementtype": "^3.0.0",
"domhandler": "^6.0.0",
"domutils": "^4.0.2",
"entities": "^8.0.0"
},
"engines": {
"node": ">=22.19.0"
"node": ">=20.19.0"
}
},
"node_modules/p-limit": {
@@ -6414,9 +6432,9 @@
}
},
"node_modules/rastermill": {
"version": "0.3.3",
"resolved": "https://registry.npmjs.org/rastermill/-/rastermill-0.3.3.tgz",
"integrity": "sha512-tnNH+jymMZxcGfR+w32fbD9xpDytCrHEyYx/OCFTTIf2gAcaiasUSurBA3lObRrRHy1leitG0QRfJB6mV/SJ4w==",
"version": "0.4.0",
"resolved": "https://registry.npmjs.org/rastermill/-/rastermill-0.4.0.tgz",
"integrity": "sha512-5WrZ6tuK54oVk45w/riFm0/VwTSieJ45c/zAGIaNtTKOSYL2zwx1r3VdBB2pKwlOO/tG+A9lmvN+3S6hwU6znA==",
"license": "MIT",
"dependencies": {
"@silvia-odwyer/photon-node": "0.3.4"
@@ -7039,6 +7057,16 @@
"url": "https://github.com/sponsors/sindresorhus"
}
},
"node_modules/undici": {
"version": "8.12.3",
"resolved": "https://registry.npmjs.org/undici/-/undici-8.12.3.tgz",
"integrity": "sha512-+fdndUTwBP86cVjihTp21hZHo7d6oj1c/47XPA3lL8mM0XHs+C4EkcjmgRsFnFk2f/UONGDy9ItBItmXsLOQHw==",
"license": "MIT",
"peer": true,
"engines": {
"node": ">=22.19.0"
}
},
"node_modules/undici-types": {
"version": "8.9.0",
"resolved": "https://registry.npmjs.org/undici-types/-/undici-types-8.9.0.tgz",
@@ -7191,9 +7219,9 @@
"license": "ISC"
},
"node_modules/ws": {
"version": "8.21.3",
"resolved": "https://registry.npmjs.org/ws/-/ws-8.21.3.tgz",
"integrity": "sha512-201TZ/kPWxoPr/OKWjquZR1SWKXcvxdH+e1xrx89b3YbmzLMFCLfnaG1HFIgWzJOEWZ7MvpK++odZufgYR50Rw==",
"version": "8.22.0",
"resolved": "https://registry.npmjs.org/ws/-/ws-8.22.0.tgz",
"integrity": "sha512-Ydggc987+RO0AnWtZ/7Wq9FtNvcrL1b/RO0ud9mWjUPgDrsAAwQSF51sm2hm1XofbU/4jkpGEsLFsZZxU+1DOg==",
"license": "MIT",
"engines": {
"node": ">=10.0.0"
@@ -7310,9 +7338,9 @@
}
},
"node_modules/zod": {
"version": "4.6.5",
"resolved": "https://registry.npmjs.org/zod/-/zod-4.6.5.tgz",
"integrity": "sha512-v5l/aFXZQeai4awLbOpSoHecE9UiMrnfx75tEXLjNonXVARxQ5mOeipTjROUchszUNCqnE+hqAMujRsRHsut2Q==",
"version": "4.6.6",
"resolved": "https://registry.npmjs.org/zod/-/zod-4.6.6.tgz",
"integrity": "sha512-4UmzQUF5fxvfcYHlbjBmejU+w+hbDnWFx4aS8kBx7nPBHcO2SqPbpAG8snbdg+Xse4pRefR98hgjFgIMCI/UhA==",
"license": "MIT",
"funding": {
"url": "https://github.com/sponsors/colinhacks"
+6 -2
View File
@@ -5,10 +5,14 @@
"description": "Locked CLI dependencies for the Docker wrap E2E harness",
"dependencies": {
"@openai/codex": "0.162.1",
"openclaw": "2026.10.2"
"openclaw": "2026.10.6"
},
"overrides": {
"@modelcontextprotocol/sdk": "1.32.1",
"npm": "12.2.1"
"npm": "12.2.1",
"zod": "4.6.6",
"openclaw": {
"undici": "8.12.3"
}
}
}
+7
View File
@@ -75,6 +75,7 @@ from typing import Any
from ._ort import ensure_ort_dylib_pinned
from ._version import __version__ # noqa: F401
from .offline import pin_litellm_cost_map_local
# Must run before anything can import `headroom._core`: on Windows the
# Rust core resolves onnxruntime.dll at runtime (ort load-dynamic), and
@@ -83,6 +84,12 @@ from ._version import __version__ # noqa: F401
# ~microseconds. See `headroom/_ort.py` for the full story.
ensure_ort_dylib_pinned()
# Under HEADROOM_OFFLINE, litellm must not fetch its pricing table from GitHub
# at import time. Each litellm import in this package pins that itself; this
# call also covers a host that imports litellm after Headroom. A no-op unless
# the switch is set. See `headroom/offline.py`.
pin_litellm_cost_map_local()
from .compress import ( # noqa: E402
CompressConfig,
CompressResult,
+494
View File
@@ -0,0 +1,494 @@
"""Windows NTFS ACL implementation backing :mod:`headroom.fileperms`.
Python ships no ACL API, so this module talks to ``advapi32``/``kernel32``
through ``ctypes`` directly rather than adding a third-party dependency
(``pywin32``) for a handful of calls. Imported only on Windows; every public
function fails closed (returns ``False``) on any error rather than raising,
because the caller's contract (see :mod:`headroom.fileperms`) is "report
whether owner-only protection took effect" — a partially-applied ACL that
raised out of a logging setup path would be worse than one that silently
reports failure and lets the caller warn.
Both entry points restrict a HANDLE, not a path: :func:`restrict_handle` for
a file we hold open (its fd's handle is reopened via ``ReOpenFile`` for
``WRITE_DAC``, which the CRT's own open does not request, with no path
re-resolution and therefore no TOCTOU window), and :func:`restrict_path` for
one we did not (rotated backups) — opened with ``FILE_FLAG_OPEN_REPARSE_POINT``
so a symlink/junction at the path is restricted as the link itself rather
than followed, mirroring the POSIX ``O_NOFOLLOW`` used for the same purpose.
The DACL this sets has exactly one entry: full control for the calling
user's own SID, created fresh (not merged with the inherited DACL) and
applied with ``PROTECTED_DACL_SECURITY_INFORMATION`` so the parent
directory's inherited entries — which is what made the file readable in the
first place — are dropped rather than left alongside the new entry. That is
deliberately stricter than POSIX ``0600`` relative to an administrator:
POSIX root bypasses file permissions outright, while this ACL does not carve
out Administrators/SYSTEM, matching what "owner-only" says.
"""
from __future__ import annotations
import ctypes
import msvcrt
import os
from ctypes import wintypes
_advapi32 = ctypes.WinDLL("advapi32", use_last_error=True) # type: ignore[attr-defined]
_kernel32 = ctypes.WinDLL("kernel32", use_last_error=True) # type: ignore[attr-defined]
_SE_FILE_OBJECT = 1
_DACL_SECURITY_INFORMATION = 0x00000004
_PROTECTED_DACL_SECURITY_INFORMATION = 0x80000000
_NO_INHERITANCE = 0
_SET_ACCESS = 2
_ERROR_SUCCESS = 0
_FILE_ALL_ACCESS = 0x001F01FF
_TOKEN_QUERY = 0x0008
_TokenUser = 1
_WRITE_DAC = 0x00040000
_READ_CONTROL = 0x00020000
_OPEN_EXISTING = 3
_CREATE_NEW = 1
_GENERIC_WRITE = 0x40000000
_ERROR_FILE_NOT_FOUND = 2
_FILE_BEGIN = 0
_FILE_ATTRIBUTE_NORMAL = 0x80
_FILE_ATTRIBUTE_REPARSE_POINT = 0x400
_FILE_SHARE_READ = 1
_FILE_SHARE_WRITE = 2
_FILE_SHARE_DELETE = 4
_FILE_FLAG_OPEN_REPARSE_POINT = 0x00200000
_INVALID_HANDLE_VALUE = wintypes.HANDLE(-1).value
class _TRUSTEE_W(ctypes.Structure):
pass
_TRUSTEE_W._fields_ = [
("pMultipleTrustee", ctypes.POINTER(_TRUSTEE_W)),
("MultipleTrusteeOperation", ctypes.c_int),
("TrusteeForm", ctypes.c_int),
("TrusteeType", ctypes.c_int),
("ptstrName", ctypes.c_void_p),
]
class _EXPLICIT_ACCESS_W(ctypes.Structure):
_fields_ = [
("grfAccessPermissions", wintypes.DWORD),
("grfAccessMode", ctypes.c_int),
("grfInheritance", wintypes.DWORD),
("Trustee", _TRUSTEE_W),
]
_advapi32.BuildTrusteeWithSidW.argtypes = [ctypes.POINTER(_TRUSTEE_W), ctypes.c_void_p]
_advapi32.BuildTrusteeWithSidW.restype = None
_advapi32.SetEntriesInAclW.argtypes = [
wintypes.ULONG,
ctypes.POINTER(_EXPLICIT_ACCESS_W),
ctypes.c_void_p,
ctypes.POINTER(ctypes.c_void_p),
]
_advapi32.SetEntriesInAclW.restype = wintypes.DWORD
_advapi32.SetSecurityInfo.argtypes = [
wintypes.HANDLE,
ctypes.c_int,
wintypes.DWORD,
ctypes.c_void_p,
ctypes.c_void_p,
ctypes.c_void_p,
ctypes.c_void_p,
]
_advapi32.SetSecurityInfo.restype = wintypes.DWORD
_advapi32.GetSecurityInfo.argtypes = [
wintypes.HANDLE,
ctypes.c_int,
wintypes.DWORD,
ctypes.POINTER(ctypes.c_void_p),
ctypes.POINTER(ctypes.c_void_p),
ctypes.POINTER(ctypes.c_void_p),
ctypes.POINTER(ctypes.c_void_p),
ctypes.POINTER(ctypes.c_void_p),
]
_advapi32.GetSecurityInfo.restype = wintypes.DWORD
_advapi32.GetAclInformation.argtypes = [
ctypes.c_void_p,
ctypes.c_void_p,
wintypes.DWORD,
ctypes.c_int,
]
_advapi32.GetAclInformation.restype = wintypes.BOOL
_advapi32.GetAce.argtypes = [ctypes.c_void_p, wintypes.DWORD, ctypes.POINTER(ctypes.c_void_p)]
_advapi32.GetAce.restype = wintypes.BOOL
_advapi32.EqualSid.argtypes = [ctypes.c_void_p, ctypes.c_void_p]
_advapi32.EqualSid.restype = wintypes.BOOL
_advapi32.OpenProcessToken.argtypes = [
wintypes.HANDLE,
wintypes.DWORD,
ctypes.POINTER(wintypes.HANDLE),
]
_advapi32.OpenProcessToken.restype = wintypes.BOOL
_advapi32.GetTokenInformation.argtypes = [
wintypes.HANDLE,
ctypes.c_int,
ctypes.c_void_p,
wintypes.DWORD,
ctypes.POINTER(wintypes.DWORD),
]
_advapi32.GetTokenInformation.restype = wintypes.BOOL
_kernel32.GetCurrentProcess.restype = wintypes.HANDLE
_kernel32.CloseHandle.argtypes = [wintypes.HANDLE]
_kernel32.LocalFree.argtypes = [ctypes.c_void_p]
_kernel32.ReOpenFile.argtypes = [wintypes.HANDLE, wintypes.DWORD, wintypes.DWORD, wintypes.DWORD]
_kernel32.ReOpenFile.restype = wintypes.HANDLE
_kernel32.CreateFileW.argtypes = [
wintypes.LPCWSTR,
wintypes.DWORD,
wintypes.DWORD,
ctypes.c_void_p,
wintypes.DWORD,
wintypes.DWORD,
wintypes.HANDLE,
]
_kernel32.CreateFileW.restype = wintypes.HANDLE
_kernel32.SetFilePointerEx.argtypes = [
wintypes.HANDLE,
ctypes.c_longlong,
ctypes.POINTER(ctypes.c_longlong),
wintypes.DWORD,
]
_kernel32.SetFilePointerEx.restype = wintypes.BOOL
_kernel32.SetEndOfFile.argtypes = [wintypes.HANDLE]
_kernel32.SetEndOfFile.restype = wintypes.BOOL
class _ByHandleFileInformation(ctypes.Structure):
_fields_ = [
("dwFileAttributes", wintypes.DWORD),
("ftCreationTime", wintypes.FILETIME),
("ftLastAccessTime", wintypes.FILETIME),
("ftLastWriteTime", wintypes.FILETIME),
("dwVolumeSerialNumber", wintypes.DWORD),
("nFileSizeHigh", wintypes.DWORD),
("nFileSizeLow", wintypes.DWORD),
("nNumberOfLinks", wintypes.DWORD),
("nFileIndexHigh", wintypes.DWORD),
("nFileIndexLow", wintypes.DWORD),
]
_kernel32.GetFileInformationByHandle.argtypes = [
wintypes.HANDLE,
ctypes.POINTER(_ByHandleFileInformation),
]
_kernel32.GetFileInformationByHandle.restype = wintypes.BOOL
class _AclSizeInformation(ctypes.Structure):
_fields_ = [
("AceCount", wintypes.DWORD),
("AclBytesInUse", wintypes.DWORD),
("AclBytesFree", wintypes.DWORD),
]
class _AceHeader(ctypes.Structure):
_fields_ = [
("AceType", ctypes.c_ubyte),
("AceFlags", ctypes.c_ubyte),
("AceSize", wintypes.WORD),
]
def _current_user_sid() -> tuple[ctypes.c_void_p, ctypes.Array[ctypes.c_char]]:
"""The calling process's user SID, plus the buffer it lives in.
Caller must keep the buffer alive for as long as the SID pointer is used
-- the SID is a view into it, not a copy.
"""
token = wintypes.HANDLE()
if not _advapi32.OpenProcessToken(
_kernel32.GetCurrentProcess(), _TOKEN_QUERY, ctypes.byref(token)
):
raise ctypes.WinError(ctypes.get_last_error()) # type: ignore[attr-defined]
try:
size = wintypes.DWORD(0)
_advapi32.GetTokenInformation(token, _TokenUser, None, 0, ctypes.byref(size))
buf = ctypes.create_string_buffer(size.value)
if not _advapi32.GetTokenInformation(token, _TokenUser, buf, size, ctypes.byref(size)):
raise ctypes.WinError(ctypes.get_last_error()) # type: ignore[attr-defined]
# TOKEN_USER is { SID_AND_ATTRIBUTES { PSID Sid; DWORD Attributes; } };
# the first pointer-sized field is the PSID.
sid = ctypes.cast(buf, ctypes.POINTER(ctypes.c_void_p))[0]
return ctypes.c_void_p(sid), buf
finally:
_kernel32.CloseHandle(token)
def _apply_owner_only_dacl(handle: wintypes.HANDLE) -> bool:
"""Replace *handle*'s DACL with a single owner-only entry.
*handle* must already carry ``WRITE_DAC``.
"""
try:
sid, _buf = _current_user_sid()
except OSError:
return False
trustee = _TRUSTEE_W()
_advapi32.BuildTrusteeWithSidW(ctypes.byref(trustee), sid)
entry = _EXPLICIT_ACCESS_W()
entry.grfAccessPermissions = _FILE_ALL_ACCESS
entry.grfAccessMode = _SET_ACCESS
entry.grfInheritance = _NO_INHERITANCE
entry.Trustee = trustee
new_dacl = ctypes.c_void_p()
# Passing NULL for the existing-ACL argument builds a fresh ACL containing
# only *entry*, rather than merging with whatever inherited entries the
# file already had -- those inherited entries are exactly what made it
# readable, so merging would defeat the point.
if (
_advapi32.SetEntriesInAclW(1, ctypes.byref(entry), None, ctypes.byref(new_dacl))
!= _ERROR_SUCCESS
):
return False
try:
rc = _advapi32.SetSecurityInfo(
handle,
_SE_FILE_OBJECT,
_DACL_SECURITY_INFORMATION | _PROTECTED_DACL_SECURITY_INFORMATION,
None,
None,
new_dacl,
None,
)
return bool(rc == _ERROR_SUCCESS)
finally:
_kernel32.LocalFree(new_dacl)
def restrict_handle(fd: int) -> bool:
"""Make the open file behind CRT descriptor *fd* owner-only.
The CRT's own ``CreateFileW`` call underneath ``os.open``/``open()`` does
not request ``WRITE_DAC``, so this reopens the same file object (via
``ReOpenFile`` -- no path involved, so nothing for a symlink to redirect)
with that right, applies the DACL, and closes the reopened handle. *fd*
itself is left exactly as the caller had it.
"""
try:
original = wintypes.HANDLE(msvcrt.get_osfhandle(fd)) # type: ignore[attr-defined]
except OSError:
return False
reopened = _kernel32.ReOpenFile(
original,
_WRITE_DAC | _READ_CONTROL,
_FILE_SHARE_READ | _FILE_SHARE_WRITE | _FILE_SHARE_DELETE,
0,
)
if not reopened or reopened == _INVALID_HANDLE_VALUE:
return False
try:
return _apply_owner_only_dacl(reopened)
finally:
_kernel32.CloseHandle(reopened)
def restrict_path(path: str) -> bool:
"""Make the file at *path* owner-only without following a symlink there.
For files this process did not open itself (rotated log backups).
``FILE_FLAG_OPEN_REPARSE_POINT`` opens a symlink/junction as the link
itself rather than its target, the Windows equivalent of the POSIX
``O_NOFOLLOW`` the caller's own ``islink`` check already guards against
on both platforms.
"""
handle = _kernel32.CreateFileW(
path,
_WRITE_DAC | _READ_CONTROL,
_FILE_SHARE_READ | _FILE_SHARE_WRITE | _FILE_SHARE_DELETE,
None,
_OPEN_EXISTING,
_FILE_FLAG_OPEN_REPARSE_POINT,
None,
)
if not handle or handle == _INVALID_HANDLE_VALUE:
return False
try:
return _apply_owner_only_dacl(handle)
finally:
_kernel32.CloseHandle(handle)
def open_no_follow(path: str, *, truncate: bool) -> int:
"""Create-or-open *path* for append/truncate, refusing a symlink or
junction there, and apply the owner-only DACL -- all against the one
HANDLE this opens, so there is no window between checking the path and
writing through it.
This is the primitive :func:`headroom.fileperms.open_owner_only` needs
and plain ``os.open()`` cannot provide on Windows: the CRT open it wraps
has no ``O_NOFOLLOW`` equivalent, so it silently follows a planted
symlink/junction to whatever it points at, and anything opened that way
-- including a later DACL change -- lands on the target, not the
intended file. ``FILE_FLAG_OPEN_REPARSE_POINT`` makes this CreateFileW
call open the reparse point itself rather than its target regardless of
*disposition*, so the attribute check below sees the real thing even on
the create-or-open path a planted link races against.
Raises ``OSError`` on any failure, including when *path* is a symlink or
junction -- matching the POSIX ``O_NOFOLLOW`` contract this mirrors, and
the caller's existing "failing closed is deliberate" policy.
Always opens with ``OPEN_EXISTING`` first, regardless of *truncate*.
``CREATE_ALWAYS``/``OPEN_ALWAYS`` against an existing reparse point does
not error or open the link -- it deletes it and creates a fresh regular
file in its place, *before* this function ever gets a handle to inspect,
so the refusal below would silently never fire for exactly the request
(truncate) that most needs it. Truncating, when asked for, happens via
``SetEndOfFile`` on the one handle this function opens, once that handle
is confirmed not to be a reparse point -- never by asking ``CreateFileW``
to recreate the path.
"""
access = _GENERIC_WRITE | _WRITE_DAC
share = _FILE_SHARE_READ | _FILE_SHARE_WRITE | _FILE_SHARE_DELETE
flags = _FILE_FLAG_OPEN_REPARSE_POINT | _FILE_ATTRIBUTE_NORMAL
handle = _kernel32.CreateFileW(path, access, share, None, _OPEN_EXISTING, flags, None)
if not handle or handle == _INVALID_HANDLE_VALUE:
err = ctypes.get_last_error() # type: ignore[attr-defined]
if err != _ERROR_FILE_NOT_FOUND:
raise OSError(f"CreateFileW failed for {path!r}: error {err}")
# Nothing there yet. CREATE_NEW fails outright instead of silently
# opening whatever a symlink planted in the gap since the check
# above left behind -- the same race OPEN_EXISTING already closed
# for the file-exists case, closed here for the file-missing one.
handle = _kernel32.CreateFileW(path, access, share, None, _CREATE_NEW, flags, None)
if not handle or handle == _INVALID_HANDLE_VALUE:
err = ctypes.get_last_error() # type: ignore[attr-defined]
raise OSError(f"CreateFileW failed for {path!r}: error {err}")
try:
info = _ByHandleFileInformation()
if not _kernel32.GetFileInformationByHandle(handle, ctypes.byref(info)):
err = ctypes.get_last_error() # type: ignore[attr-defined]
raise OSError(f"GetFileInformationByHandle failed for {path!r}: error {err}")
if info.dwFileAttributes & _FILE_ATTRIBUTE_REPARSE_POINT:
raise OSError(f"refusing to open {path!r}: it is a symlink or junction")
if truncate:
if not _kernel32.SetFilePointerEx(handle, 0, None, _FILE_BEGIN):
err = ctypes.get_last_error() # type: ignore[attr-defined]
raise OSError(f"SetFilePointerEx failed for {path!r}: error {err}")
if not _kernel32.SetEndOfFile(handle):
err = ctypes.get_last_error() # type: ignore[attr-defined]
raise OSError(f"SetEndOfFile failed for {path!r}: error {err}")
# Best-effort, like every other restrict_* call: a failure here does
# not fail the open (see fileperms.verify_owner_only for why), but a
# planted symlink always fails above regardless of this result.
_apply_owner_only_dacl(handle)
fd: int = msvcrt.open_osfhandle( # type: ignore[attr-defined]
handle, os.O_APPEND if not truncate else os.O_TRUNC
)
return fd
except BaseException:
_kernel32.CloseHandle(handle)
raise
def verify_handle(fd: int) -> bool:
"""Like :func:`verify_path`, for a file this process already holds open."""
try:
handle = wintypes.HANDLE(msvcrt.get_osfhandle(fd)) # type: ignore[attr-defined]
except OSError:
return False
return _verify_handle(handle)
def verify_path(path: str) -> bool:
"""Re-read the DACL at *path* and confirm it grants access to exactly the
calling user and no one else.
Independent of :func:`restrict_path`/:func:`restrict_handle`'s own
success return: that return says the API calls reported success, this
re-reads what is actually on the object now. Used to decide whether to
warn, so the warning reflects the file in front of it rather than a
static assumption about the platform. Only needs ``READ_CONTROL``, not
``WRITE_DAC`` -- it never modifies the DACL.
"""
handle = _kernel32.CreateFileW(
path,
_READ_CONTROL,
_FILE_SHARE_READ | _FILE_SHARE_WRITE | _FILE_SHARE_DELETE,
None,
_OPEN_EXISTING,
_FILE_FLAG_OPEN_REPARSE_POINT,
None,
)
if not handle or handle == _INVALID_HANDLE_VALUE:
return False
try:
return _verify_handle(handle)
finally:
_kernel32.CloseHandle(handle)
def _verify_handle(handle: wintypes.HANDLE) -> bool:
try:
sid, _buf = _current_user_sid()
except OSError:
return False
dacl = ctypes.c_void_p()
sec_desc = ctypes.c_void_p()
rc = _advapi32.GetSecurityInfo(
handle,
_SE_FILE_OBJECT,
_DACL_SECURITY_INFORMATION,
None,
None,
ctypes.byref(dacl),
None,
ctypes.byref(sec_desc),
)
if rc != _ERROR_SUCCESS:
return False
try:
size_info = _AclSizeInformation()
if not _advapi32.GetAclInformation(
dacl,
ctypes.byref(size_info),
ctypes.sizeof(size_info),
2, # AclSizeInformation
):
return False
if size_info.AceCount != 1:
return False
ace_ptr = ctypes.c_void_p()
if not _advapi32.GetAce(dacl, 0, ctypes.byref(ace_ptr)):
return False
# ACCESS_ALLOWED_ACE lays out as ACE_HEADER, then a DWORD access mask,
# then the SID -- the SID starts right after those two fixed fields.
ace_addr = ace_ptr.value
if ace_addr is None:
return False
sid_offset = ctypes.sizeof(_AceHeader) + ctypes.sizeof(wintypes.DWORD)
ace_sid = ctypes.c_void_p(ace_addr + sid_offset)
return bool(_advapi32.EqualSid(ace_sid, sid))
finally:
# sec_desc, not dacl: GetSecurityInfo returns pointers into one
# LocalAlloc'd block: freeing dacl (an offset into it, not its start)
# is an invalid free. See cpython ctypes issue discussions on
# GetSecurityInfo for the same gotcha.
_kernel32.LocalFree(sec_desc)
+1 -1
View File
@@ -173,7 +173,7 @@ _PROFILES: dict[str, AgentSavingsProfile] = {
# Coding posture: defer non-core tool schemas, dedupe re-reads, extend
# lossy coverage when lossless found nothing, and NEVER lossy-compress a
# file read (the agent patches exact bytes). CCR stays ON (unset) so any
# lossy loss is recoverable. Effort router off; low block floor so modest
# lossy loss is recoverable. Low block floor so modest
# deltas are eligible.
tool_search=True,
cross_turn_dedup=True,
+3
View File
@@ -21,6 +21,7 @@ from collections.abc import AsyncIterator
from dataclasses import dataclass, field
from typing import Any
from headroom.offline import pin_litellm_cost_map_local
from headroom.proxy.public_errors import client_message
from headroom.utils import format_exception_message
@@ -67,6 +68,7 @@ try:
import os as _os
_env_snapshot = set(_os.environ)
pin_litellm_cost_map_local()
import litellm
from litellm import acompletion
from litellm.utils import supports_prompt_caching
@@ -536,6 +538,7 @@ def _caller_key_travels_to(model: str, key: str) -> bool:
if not key.startswith("sk-ant-"):
return True
try:
pin_litellm_cost_map_local()
from litellm import get_llm_provider
provider = (get_llm_provider(model)[1] or "").lower()
+6 -1
View File
@@ -49,13 +49,18 @@ class CompressionStoreBackend(Protocol):
"""
...
def set(self, hash_key: str, entry: CompressionEntry) -> None:
def set(self, hash_key: str, entry: CompressionEntry) -> bool | None:
"""Store an entry with the given hash key.
Args:
hash_key: The unique hash identifying the entry.
entry: The CompressionEntry to store.
Returns:
``False`` when a backend that absorbs its errors did not store it
(``CompressionStore.store`` then raises ``StorageError``);
``None`` (or ``True``) otherwise.
Note:
Overwrites any existing entry with the same key.
"""
+117
View File
@@ -0,0 +1,117 @@
"""Redis storage backend for CompressionStore: one CCR store for every replica.
A ``<<ccr:hash>>`` marker points at an original kept by whichever replica
compressed it; behind a gateway that spreads requests across replicas, the
retrieval can land anywhere. With ``HEADROOM_CCR_BACKEND=redis`` and
``HEADROOM_REDIS_URL``, every replica reads and writes one store.
Each entry is one key, ``<prefix>:ccr:<hash>``, holding the entry as JSON and
expiring when the entry does (``created_at + ttl``). A Redis error is a miss
(see :mod:`headroom.cache.redis_client`): a retrieval then fails as it would for
an expired entry, and compression never waits on Redis.
"""
from __future__ import annotations
import json
import time
from dataclasses import asdict, fields
from typing import TYPE_CHECKING, Any
from ..redis_client import Guard, connect, key_prefix
if TYPE_CHECKING:
from ..compression_store import CompressionEntry
class RedisBackend:
"""CCR entries in Redis, shared by every replica that points at it."""
#: Redis expires each entry with its TTL: CompressionStore neither caps nor
#: sweeps this store (a per-replica cap would evict other replicas' entries).
expires_entries = True
def __init__(self, url: str, client: Any = None) -> None:
self._client = client if client is not None else connect(url, setting="HEADROOM_REDIS_URL")
self._prefix = f"{key_prefix()}:ccr:"
self._guard = Guard("CCR store")
def _key(self, hash_key: str) -> str:
return self._prefix + hash_key
def get(self, hash_key: str) -> CompressionEntry | None:
raw = self._guard.call("read", lambda: self._client.get(self._key(hash_key)), None)
return None if raw is None else _decode(raw)
def set(self, hash_key: str, entry: CompressionEntry) -> bool:
"""Whether Redis took the entry (an error is logged, not raised)."""
remaining_ms = int((entry.created_at + entry.ttl - time.time()) * 1000)
if remaining_ms <= 0:
return False
blob = json.dumps(asdict(entry))
return bool(
self._guard.call(
"write", lambda: self._client.set(self._key(hash_key), blob, px=remaining_ms), None
)
)
def delete(self, hash_key: str) -> bool:
return bool(self._guard.call("delete", lambda: self._client.delete(self._key(hash_key)), 0))
def exists(self, hash_key: str) -> bool:
return bool(self._guard.call("read", lambda: self._client.exists(self._key(hash_key)), 0))
def clear(self) -> None:
keys = self._scan()
if keys:
self._guard.call("delete", lambda: self._client.delete(*keys), 0)
def count(self) -> int:
return len(self._scan())
def keys(self) -> list[str]:
return [k[len(self._prefix) :] for k in self._scan()]
def items(self) -> list[tuple[str, CompressionEntry]]:
out = []
for hash_key in self.keys():
entry = self.get(hash_key)
if entry is not None:
out.append((hash_key, entry))
return out
def purge_expired(self, now: float | None = None) -> int:
"""Redis has already dropped them."""
return 0
def get_stats(self) -> dict[str, Any]:
return {"backend_type": "redis", "entry_count": self.count()}
def _scan(self) -> list[str]:
def scan() -> list[str]:
return [
k.decode() if isinstance(k, bytes) else k
for k in self._client.scan_iter(match=_glob_escape(self._prefix) + "*", count=500)
]
return self._guard.call("scan", scan, [])
def _decode(raw: Any) -> CompressionEntry | None:
"""An entry from its JSON, or ``None`` when it is not one (a miss)."""
from ..compression_store import CompressionEntry
try:
data = json.loads(raw)
known = {f.name for f in fields(CompressionEntry)}
entry = CompressionEntry(**{k: v for k, v in data.items() if k in known})
except (ValueError, TypeError, AttributeError):
return None
texts_ok = isinstance(entry.original_content, str) and isinstance(entry.compressed_content, str)
times_ok = isinstance(entry.created_at, (int, float)) and isinstance(entry.ttl, int)
return entry if texts_ok and times_ok else None
def _glob_escape(text: str) -> str:
"""``text`` matched literally in a SCAN pattern."""
return "".join("\\" + c if c in "*?[]\\" else c for c in text)
+89 -8
View File
@@ -43,6 +43,7 @@ from contextvars import ContextVar
from dataclasses import asdict, dataclass, field, replace
from typing import TYPE_CHECKING, Any
from ..exceptions import StorageError
from ..log_safety import describe_exception, safe_id
if TYPE_CHECKING:
@@ -279,6 +280,14 @@ class CompressionStore:
self._heap_rebuild_threshold = 0.5
external_revision = getattr(self._backend, "external_revision", None)
self._backend_revision_reader = external_revision if callable(external_revision) else None
# A backend that expires entries itself and is shared by replicas
# (Redis) is bounded by TTL, not by this process's max_entries: counting
# it on every store would scan the shared keyspace, and evicting would
# remove other replicas' live entries.
self._backend_expires_entries = bool(getattr(self._backend, "expires_entries", False))
# A shared store's totals, as this process contributed them since it
# started: [original tokens stored, compressed tokens stored, retrievals].
self._own_totals = [0, 0, 0]
self._backend_revision = self._read_backend_revision()
@property
@@ -329,6 +338,11 @@ class CompressionStore:
Returns:
Hash key for retrieving this content.
Raises:
StorageError: The backend did not keep the entry (a shared store
refused the write or was unreachable). No hash is issued for
it: the caller must keep the original rather than emit a marker.
"""
# Generate hash from original content. Default: SHA-256[:24] of the
# original. When the caller provides `explicit_hash`, use it
@@ -424,7 +438,8 @@ class CompressionStore:
# turn a marker is re-encountered, so duplicate stores are common.
existing = self._backend.get(hash_key)
if existing is None:
self._evict_if_needed()
if not self._backend_expires_entries:
self._evict_if_needed()
else:
# Hash already present. Different content means a true (extremely
# rare with SHA256[:24]) collision; same content is a duplicate
@@ -445,7 +460,18 @@ class CompressionStore:
# Mark old heap entry as stale since we're replacing it.
self._mark_heap_entries_stale()
self._backend.set(hash_key, entry)
if self._backend.set(hash_key, entry) is False:
# Only a backend that absorbs its errors (Redis) returns False;
# it has logged why. A hash here would be a marker that never
# resolves, and producers drop the original once they hold one.
raise StorageError(
f"CCR store did not keep hash={hash_key}; keep the original content"
)
if self._backend_expires_entries:
if existing is None:
self._own_totals[0] += entry.original_tokens
self._own_totals[1] += entry.compressed_tokens
return hash_key # no local index: Redis expires it
# MEDIUM FIX #16: Add to eviction heap for O(log n) eviction
heapq.heappush(self._eviction_heap, (entry.created_at, hash_key))
heapq.heappush(
@@ -485,8 +511,13 @@ class CompressionStore:
# Track access for feedback
entry.record_access(query)
# Update the backend with the modified entry
self._backend.set(hash_key, entry)
# Update the backend with the modified entry. Not a shared store:
# writing the whole entry back per read races other replicas and
# resends the original; retrieval events below stay per process.
if self._backend_expires_entries:
self._own_totals[2] += 1
else:
self._backend.set(hash_key, entry)
# Log retrieval event
if self._enable_feedback:
@@ -654,6 +685,25 @@ class CompressionStore:
def get_stats(self) -> dict[str, Any]:
"""Get store statistics for monitoring."""
if self._backend_expires_entries:
# Totals over the store would read every replica's entries (a GET
# each) under the lock retrievals take: a shared store reports the
# entry count across replicas, and the totals this replica added
# since it started ("totals_scope").
backend_stats = self._backend.get_stats()
with self._lock:
original, compressed, retrievals = self._own_totals
return {
"entry_count": backend_stats["entry_count"],
"max_entries": self._max_entries,
"default_ttl_seconds": self._default_ttl,
"total_original_tokens": original,
"total_compressed_tokens": compressed,
"total_retrievals": retrievals,
"totals_scope": "this_replica",
"event_count": len(self._retrieval_events),
"backend": backend_stats,
}
with self._lock:
# Clean expired entries
self._clean_expired()
@@ -704,10 +754,15 @@ class CompressionStore:
return ComponentStats(
name="compression_store",
entry_count=self._backend.count(),
entry_count=backend_stats.get("entry_count", 0)
if self._backend_expires_entries
else self._backend.count(),
size_bytes=bytes_used,
budget_bytes=None, # No budget set yet
hits=sum(1 for _, e in self._backend.items() if e.retrieval_count > 0),
# A shared store would be read whole to count these.
hits=0
if self._backend_expires_entries
else sum(1 for _, e in self._backend.items() if e.retrieval_count > 0),
misses=0, # CompressionStore doesn't track misses directly
evictions=0, # Would need to track this separately
)
@@ -868,6 +923,8 @@ class CompressionStore:
def _mark_heap_entries_stale(self) -> None:
"""Record lazy tuples invalidated by deleting or replacing an entry."""
if self._backend_expires_entries:
return # no index kept for a self-expiring backend
self._stale_heap_entries += 1
self._stale_expiration_heap_entries += 1
@@ -892,6 +949,8 @@ class CompressionStore:
def _rebuild_heap_if_needed(self) -> None:
"""Rebuild both indexes when either stale ratio reaches the threshold."""
if self._backend_expires_entries:
return # rebuilding would scan the shared store
heap_size = len(self._eviction_heap)
expiration_heap_size = len(self._expiration_heap)
stale_ratio = self._stale_heap_entries / heap_size if heap_size else 0
@@ -1155,8 +1214,10 @@ def _create_default_ccr_backend() -> CompressionStoreBackend | None:
Default (env unset or "sqlite"): SQLiteBackend at workspace_dir()/ccr_store.db
— restart-safe and shared across worker processes, which the
session-scale 30-minute TTL assumes.
"memory" opts back into the in-process dict. Other values load
adapters via setuptools entry point 'headroom.ccr_backend'.
"memory" opts back into the in-process dict. "redis" shares one store
across replicas (HEADROOM_REDIS_URL; headroom.cache.backends.redis) unless a
plugin registers that name. Other values load adapters via setuptools entry
point 'headroom.ccr_backend'.
Returns None to use InMemoryBackend.
Stateless mode (``--stateless`` / ``HEADROOM_STATELESS``) never opens the
@@ -1171,6 +1232,13 @@ def _create_default_ccr_backend() -> CompressionStoreBackend | None:
from ..paths import persistence_allowed
backend_type = (os.environ.get("HEADROOM_CCR_BACKEND") or "").strip().lower()
session_store = os.environ.get("HEADROOM_COMPRESS_SESSION_STORE", "").strip()
if not backend_type and session_store:
# Replicas sharing compress sessions share the CCR store too: a marker
# in a replayed transcript must resolve on whichever replica serves it.
from .backends.redis import RedisBackend
return RedisBackend(session_store)
if backend_type == "memory":
return None
if not backend_type or backend_type == "sqlite":
@@ -1193,6 +1261,19 @@ def _create_default_ccr_backend() -> CompressionStoreBackend | None:
all_eps = entry_points(group="headroom.ccr_backend")
ep = next((e for e in all_eps if e.name == backend_type), None)
if ep is None and backend_type == "redis":
# Built in: one store for every replica behind a gateway. A plugin
# registered as "redis" still wins, above.
from .backends.redis import RedisBackend
url = os.environ.get("HEADROOM_REDIS_URL", "").strip() or session_store
if not url:
logger.error(
"HEADROOM_CCR_BACKEND=redis needs HEADROOM_REDIS_URL; using the "
"in-process store, so a marker resolves only on the replica that made it"
)
return None
return RedisBackend(url)
if ep is None:
logger.warning(
"HEADROOM_CCR_BACKEND=%s but no entry point headroom.ccr_backend[%s]",
+4 -4
View File
@@ -421,9 +421,7 @@ class OpenAICacheOptimizer(BaseCacheOptimizer):
leading = len(line) - len(line.lstrip())
# Collapse multiple spaces in content (not indentation)
content_part = " ".join(stripped.split())
normalized_lines.append(
" " * leading + content_part[leading:] if leading else content_part
)
normalized_lines.append(line[:leading] + content_part)
else:
normalized_lines.append("")
@@ -434,7 +432,9 @@ class OpenAICacheOptimizer(BaseCacheOptimizer):
while "\n\n\n" in result:
result = result.replace("\n\n\n", "\n\n")
return result.strip()
# Lines are already right-stripped and blank lines are empty, so only
# surrounding newlines remain; keep the first line's indentation.
return result.strip("\n")
def _format_dynamic_section(
self,
+74 -23
View File
@@ -1206,6 +1206,11 @@ class PrefixCacheTracker:
# builds the manager.
self.restored_from_disk = False
self.restored_maturation_state: dict[str, Any] | None = None
# Shared-store state (headroom.cache.shared_sessions): the write token
# this tracker matches ("" when never shared) and the digests of the
# messages known to be stored with it.
self.shared_token = ""
self.shared_digests: frozenset[str] = frozenset()
# Stats
self._busts_avoided: int = 0
@@ -1509,16 +1514,20 @@ class PrefixCacheTracker:
def is_expired_for_cache_ttl(self, cache_ttl_seconds: int | None) -> bool:
"""Check expiry including the longest configured or observed cache lifetime."""
return (time.time() - self._last_activity) > self.retention_seconds(cache_ttl_seconds)
def retention_seconds(self, cache_ttl_seconds: int | None = None) -> float:
"""How long this tracker is kept after its last activity: the session
TTL, or the longest configured or observed cache lifetime plus a margin."""
observed_ttl = max(
self._cache_ttl_seconds or 0,
self.config.cache_ttl_seconds or 0,
cache_ttl_seconds or 0,
)
retention = max(
return max(
self.config.session_ttl_seconds,
observed_ttl + _CACHE_TTL_CLEANUP_MARGIN_SECONDS if observed_ttl else 0,
)
return (time.time() - self._last_activity) > retention
def observe_cache_ttl(self, cache_ttl_seconds: int | None) -> None:
"""Remember the longest provider cache lifetime observed for this lineage."""
@@ -2144,6 +2153,14 @@ class SessionTrackerStore:
pairs mostly repeat the same messages, so this keeps the file near one
copy of each conversation instead of up to eleven.
"""
meta, table = self._tracker_parts(key, tracker, session_id)
return f'{{"meta":{json.dumps(meta)},"messages":[{",".join(table)}]}}'
def _tracker_parts(
self, key: str, tracker: PrefixCacheTracker, session_id: str | None
) -> tuple[dict[str, Any], list[str]]:
"""A tracker as its metadata, whose message lists are indexes into the
table, and the table: each distinct message once, as JSON."""
index: dict[str, int] = {}
memo: dict[int, list[int]] = {}
@@ -2172,7 +2189,7 @@ class SessionTrackerStore:
"history": [[ref(snap), t] for snap, t in self._lineage_history.get(key, ())],
"maturation": None if maturation is None else maturation.export_state(),
}
return f'{{"meta":{json.dumps(meta)},"messages":[{",".join(index)}]}}'
return meta, list(index)
def load_state(self, path: str) -> int:
"""Resume the trackers :meth:`save_state` wrote, before serving.
@@ -2213,6 +2230,58 @@ class SessionTrackerStore:
)
return restored
def _decode_tracker(self, entry: Any, now: float) -> PrefixCacheTracker | None:
"""One :meth:`_encode_tracker` entry as a tracker marked restored, or
``None`` when it has expired. Raises on a malformed entry."""
meta, table = entry["meta"], entry["messages"]
tracker = PrefixCacheTracker(str(meta["provider"]), self._default_config)
tracker._last_activity = float(meta["last_activity"])
tracker.observe_cache_ttl(meta["cache_ttl"])
# NaN or a future stamp would never expire.
if tracker.is_expired or not tracker._last_activity <= now:
return None
(
tracker._turn_number,
tracker._cached_token_count,
tracker._cached_message_count,
tracker._last_original_messages,
tracker._last_forwarded_messages,
) = _decode_turn_state(table, meta["state"])
tracker._turn_states = {int(t): _decode_turn_state(table, s) for t, s in meta["turns"]}
tracker.restored_from_disk = True
if meta["maturation"] is not None:
from headroom.transforms.read_maturation import ReadMaturationManager
tracker.restored_maturation_state = ReadMaturationManager.validate_state(
meta["maturation"]
)
return tracker
def encode_shared(
self, key: str, tracker: PrefixCacheTracker
) -> tuple[dict[str, Any], list[str]]:
"""``tracker`` for another process (headroom.cache.shared_sessions): its
metadata and its message table, each distinct message once, as JSON.
Raises when its messages are not JSON."""
return self._tracker_parts(key, tracker, None)
def decode_shared(self, meta: Any, messages: list[Any]) -> PrefixCacheTracker | None:
"""The tracker :meth:`encode_shared` described, marked restored so its
next turn seeds the compression cache from it; ``None`` when it has
expired. Raises on malformed input. Does not install it."""
if not isinstance(meta, dict):
raise ValueError("tracker metadata is not an object")
now = time.time()
# Written on another host: a clock ahead of ours is not a future stamp.
meta = {**meta, "last_activity": min(float(meta["last_activity"]), now)}
return self._decode_tracker({"meta": meta, "messages": messages}, now)
def install(self, key: str, tracker: PrefixCacheTracker) -> None:
"""Make ``tracker`` the one under ``key``. Call on the event loop, or
from a worker thread only for a key already present (replacing a value
does not resize the dict the loop may be iterating)."""
self._trackers[key] = tracker
def _decode_state(self, data: Any) -> int:
"""Validate the whole file first, then install it; a bad file installs nothing."""
from headroom.cache.compression_store import CompressionEntry, get_compression_store
@@ -2228,27 +2297,9 @@ class SessionTrackerStore:
# Oldest first, so each family keeps its lineages in creation order.
for entry in reversed(data["trackers"]):
meta, table = entry["meta"], entry["messages"]
tracker = PrefixCacheTracker(str(meta["provider"]), self._default_config)
tracker._last_activity = float(meta["last_activity"])
tracker.observe_cache_ttl(meta["cache_ttl"])
# NaN or a future stamp would never expire.
if tracker.is_expired or not tracker._last_activity <= now:
tracker = self._decode_tracker(entry, now)
if tracker is None:
continue
(
tracker._turn_number,
tracker._cached_token_count,
tracker._cached_message_count,
tracker._last_original_messages,
tracker._last_forwarded_messages,
) = _decode_turn_state(table, meta["state"])
tracker._turn_states = {int(t): _decode_turn_state(table, s) for t, s in meta["turns"]}
tracker.restored_from_disk = True
if meta["maturation"] is not None:
from headroom.transforms.read_maturation import ReadMaturationManager
tracker.restored_maturation_state = ReadMaturationManager.validate_state(
meta["maturation"]
)
key = str(meta["key"])
trackers[key] = tracker
history = deque(
+121
View File
@@ -0,0 +1,121 @@
"""Redis connections for state that several Headroom replicas share.
The CCR store (``HEADROOM_CCR_BACKEND=redis``) and shared ``/v1/compress``
sessions keep their keys under ``HEADROOM_REDIS_KEY_PREFIX`` (default
``headroom``), so two deployments can share one Redis without sharing state.
Redis holds tool output and transcripts verbatim: it must be private to the
deployment, with authentication and TLS (``rediss://``). Plain ``redis://`` to a
host other than this machine is accepted with a warning.
Shared state is an optimisation of a request, never a condition for it: a Redis
error is a miss, logged when it starts and when Redis is back, and Redis is not
asked again for :data:`BACKOFF_SECONDS` after a connection failure, so an outage
costs requests nothing but the sharing.
"""
from __future__ import annotations
import logging
import os
import re
import threading
import time
from collections.abc import Callable
from typing import Any, TypeVar
from urllib.parse import urlsplit
from headroom.exceptions import ConfigurationError
logger = logging.getLogger(__name__)
PREFIX_ENV = "HEADROOM_REDIS_KEY_PREFIX"
#: Seconds Redis is skipped after a connection error.
BACKOFF_SECONDS = 5.0
#: Seconds a command may take. Commands carry small values (an entry, a few
#: messages), so a slow one is an outage, not a large transfer.
TIMEOUT_SECONDS = 1.0
T = TypeVar("T")
def key_prefix() -> str:
return os.environ.get(PREFIX_ENV, "").strip() or "headroom"
def connect(url: str, *, setting: str) -> Any:
"""A client for ``url``. Raises :class:`ConfigurationError`, naming
``setting``, when the URL is not Redis or the client is not installed.
Does not connect: an unreachable Redis does not stop startup."""
scheme = urlsplit(url).scheme
if scheme not in ("redis", "rediss", "unix"):
raise ConfigurationError(f"{setting} must be a redis://, rediss:// or unix:// URL")
try:
import redis
except ImportError as exc:
raise ConfigurationError(
f"{setting} names Redis but the client is not installed: "
"pip install 'headroom-ai[redis]'"
) from exc
from headroom.proxy.loopback_guard import is_loopback_host
host = urlsplit(url).hostname
if scheme == "redis" and not is_loopback_host(host):
logger.warning(
"%s: plain redis:// to %s; Redis will hold tool output and transcripts, "
"so use rediss:// with authentication on a private network",
setting,
host,
)
return redis.Redis.from_url(
url, socket_timeout=TIMEOUT_SECONDS, socket_connect_timeout=TIMEOUT_SECONDS
)
class Guard:
"""Runs Redis calls for one feature: an error is a miss, logged when that
kind of call (``what``: read, write, ...) starts failing and when it works
again; after a connection error Redis is skipped for :data:`BACKOFF_SECONDS`.
Tracking each kind apart keeps a Redis that serves reads but refuses writes
(``maxmemory`` with ``noeviction``) from logging on every request."""
def __init__(self, feature: str) -> None:
import redis
self._feature = feature
self._errors: tuple[type[BaseException], ...] = (redis.RedisError,)
self._connection_errors = (redis.ConnectionError, redis.TimeoutError)
self._lock = threading.Lock()
self._skip_until = 0.0
self._failing: set[str] = set()
def call(self, what: str, fn: Callable[[], T], default: T) -> T:
if time.monotonic() < self._skip_until:
return default
try:
result = fn()
except self._errors as exc:
with self._lock:
if isinstance(exc, self._connection_errors):
self._skip_until = time.monotonic() + BACKOFF_SECONDS
if what not in self._failing:
self._failing.add(what)
logger.warning(
"%s: Redis %s failed (%s: %s); carrying on without shared state",
self._feature,
what,
type(exc).__name__,
_redact(str(exc)),
)
return default
if what in self._failing:
with self._lock:
if what in self._failing:
self._failing.discard(what)
logger.info("%s: Redis %s works again", self._feature, what)
return result
def _redact(message: str) -> str:
"""``message`` with any URL credentials (``//user:password@``) masked."""
return re.sub(r"//[^/@\s]*@", "//***@", message)
+159
View File
@@ -0,0 +1,159 @@
"""SQLite tier behind the content router's in-memory compression cache.
The router keeps recent results in a byte-budgeted LRU; this file holds the rest,
so an entry the budget evicted comes back from disk instead of being compressed
again (which costs a Kompress pass and can give different bytes, rewriting a
cached prompt prefix). It also survives a restart and is shared by worker
processes (WAL), like the CCR store; WAL needs a local filesystem.
Each router reads and writes under its own namespace (a digest of its config and
the headroom version), so routers configured differently, or a restart with
other settings, never serve each other's output. Results carrying a CCR marker
are not written here: their originals live in the CCR store, on its own clock.
The file holds compressed tool output, so it follows the CCR store's rules:
owner-only, ``workspace_dir()/compression_cache.db`` (``HEADROOM_COMPRESSION_CACHE_PATH``
to move it), expired rows deleted on open, never opened in stateless mode, and
``HEADROOM_COMPRESSION_CACHE_DISK=0`` keeps the cache in memory only. A database
error is a miss, never a failed request.
"""
from __future__ import annotations
import logging
import os
import sqlite3
import threading
import time
from pathlib import Path
from ..fileperms import connect_private_sqlite
logger = logging.getLogger(__name__)
_SCHEMA = """
CREATE TABLE IF NOT EXISTS results (
k TEXT PRIMARY KEY,
text TEXT NOT NULL,
ratio REAL NOT NULL,
strategy TEXT NOT NULL,
expires REAL NOT NULL
);
CREATE INDEX IF NOT EXISTS idx_results_expires ON results (expires);
"""
#: Expired rows are deleted every this many writes, and on open.
_PURGE_EVERY = 1000
class ResultStore:
"""Compressed results by key; an entry expires ``ttl_seconds`` after it was
last read or written. Thread-safe; several processes may share the file."""
def __init__(self, path: Path, ttl_seconds: float) -> None:
path.parent.mkdir(parents=True, exist_ok=True)
self._path = path
self._ttl = ttl_seconds
self._lock = threading.Lock()
self._writes = 0
self._warned = False
self._db = connect_private_sqlite(
path, what="compression cache", check_same_thread=False, isolation_level=None
)
self._db.execute("PRAGMA busy_timeout=5000")
self._db.execute("PRAGMA journal_mode=WAL")
self._db.execute("PRAGMA synchronous=NORMAL")
self._db.executescript(_SCHEMA)
# Sessions that ended while the proxy was down go now.
self._db.execute("DELETE FROM results WHERE expires <= ?", (time.time(),))
def get(self, key: str) -> tuple[str, float, str] | None:
now = time.time()
try:
with self._lock:
row = self._db.execute(
"SELECT text, ratio, strategy, expires FROM results "
"WHERE k = ? AND expires > ?",
(key, now),
).fetchone()
# Keep what a live session still reads; refresh at most every half ttl.
if row is not None and row[3] - now < self._ttl / 2:
self._db.execute(
"UPDATE results SET expires = ? WHERE k = ?", (now + self._ttl, key)
)
except sqlite3.Error as exc:
self._failed("read", exc)
return None
return None if row is None else (row[0], row[1], row[2])
def put(self, key: str, text: str, ratio: float, strategy: str) -> None:
now = time.time()
try:
with self._lock:
self._db.execute(
"INSERT OR REPLACE INTO results (k, text, ratio, strategy, expires) "
"VALUES (?, ?, ?, ?, ?)",
(key, text, ratio, strategy, now + self._ttl),
)
self._writes += 1
if self._writes % _PURGE_EVERY == 0:
self._db.execute("DELETE FROM results WHERE expires <= ?", (now,))
except sqlite3.Error as exc:
self._failed("write", exc)
def touch(self, key: str) -> None:
"""Keep ``key`` for another ttl (it is in use from memory)."""
self._run("UPDATE results SET expires = ? WHERE k = ?", (time.time() + self._ttl, key))
def delete(self, key: str) -> None:
self._run("DELETE FROM results WHERE k = ?", (key,))
def clear_prefix(self, prefix: str) -> None:
"""Delete every row whose key starts with ``prefix`` (a router's namespace)."""
self._run("DELETE FROM results WHERE substr(k, 1, ?) = ?", (len(prefix), prefix))
def _run(self, sql: str, args: tuple[object, ...]) -> None:
try:
with self._lock:
self._db.execute(sql, args)
except sqlite3.Error as exc:
self._failed("write", exc)
def _failed(self, what: str, exc: sqlite3.Error) -> None:
if not self._warned:
self._warned = True
logger.warning(
"compression cache: %s of %s failed (%s); treating it as a miss. "
"Check the disk, or set HEADROOM_COMPRESSION_CACHE_DISK=0.",
what,
self._path,
exc,
)
def open_result_store(ttl_seconds: float) -> ResultStore | None:
"""The disk tier, or ``None`` (memory only) in stateless mode, with
``HEADROOM_COMPRESSION_CACHE_DISK=0``, or when the file cannot be opened."""
from ..paths import persistence_allowed, workspace_dir
if os.environ.get("HEADROOM_COMPRESSION_CACHE_DISK", "1").strip().lower() in (
"0",
"false",
"no",
"off",
):
return None
if not persistence_allowed("compression result cache (compression_cache.db)"):
return None
configured = os.environ.get("HEADROOM_COMPRESSION_CACHE_PATH", "").strip()
path = Path(configured).expanduser() if configured else workspace_dir() / "compression_cache.db"
try:
return ResultStore(path, ttl_seconds)
except (OSError, sqlite3.Error) as exc:
logger.warning(
"compression cache: cannot open %s (%s); keeping results in memory only. "
"Set HEADROOM_COMPRESSION_CACHE_PATH to a writable file or "
"HEADROOM_COMPRESSION_CACHE_DISK=0.",
path,
exc,
)
return None
+276
View File
@@ -0,0 +1,276 @@
"""Session-aware ``/v1/compress`` state shared by several Headroom replicas.
A compress session's state is its prefix tracker: the transcript it was last
given and the one it returned, which every later turn must replay byte for byte
so the provider's prompt cache holds. In memory, only the replica that served
the last turn has it, so a gateway running several replicas must pin each
session to one (``session_affinity``).
With ``HEADROOM_COMPRESS_SESSION_STORE=redis://...`` every replica also keeps
each session in Redis, and any replica can serve its next turn. Per session:
* ``<prefix>:session:{<digest>}:msgs``, a hash of message digest to message
JSON. The original and returned transcripts mostly share messages, and each
turn mostly repeats the last one's, so each message is stored once and a turn
writes only the messages Redis does not have yet: what the turn added, and
any message whose bytes changed (a moved cache marker, an edit, a compaction);
* ``<prefix>:session:{<digest>}:meta``, the tracker's counters and its
transcripts as lists of digests (``m``), and a write token (``t``).
Before a turn a replica reads the token (one small ``HGET``). When another
replica has written since, it reads the metadata and only the messages it does
not already hold, and the turn seeds its compression cache from that tracker as
after a restart (:func:`~headroom.cache.prefix_tracker.seed_restored_compression_cache`).
After the turn it writes the new messages, then the metadata if the token is
still the one it read and every message it references is stored, checked in
one script (compare-and-set): a random token, so a lost key or a failover
cannot leave a replica believing stale state is current. A missing key
resets the replica, whose next write stores the session whole again. Fetched
messages are checked against their digests. Both keys expire with the tracker.
A Redis error never fails a turn (:mod:`headroom.cache.redis_client`): the
replica serves from its own memory, as without the store. CCR originals behind
the markers in these transcripts live in the shared CCR store, which this
setting selects too unless ``HEADROOM_CCR_BACKEND`` names another. Requires the
``redis`` extra.
"""
from __future__ import annotations
import functools
import hashlib
import json
import logging
import os
import uuid
from typing import TYPE_CHECKING, Any
from .redis_client import Guard, connect, key_prefix
if TYPE_CHECKING:
from .prefix_tracker import PrefixCacheTracker, SessionTrackerStore
logger = logging.getLogger(__name__)
STORE_ENV = "HEADROOM_COMPRESS_SESSION_STORE"
#: Messages per HSET/HMGET, so no single command carries a whole transcript.
_CHUNK = 256
# Install ARGV[2] as the token and ARGV[3] as the metadata if the token is still
# ARGV[1] ("" when the key must not exist) and the messages hash (KEYS[2]) holds
# every message the metadata references (ARGV[5:], including those this write
# just sent: Redis can evict the hash between those writes and this script).
# 1 on success, 0 when another replica wrote first, 2 when the messages hash
# lost one.
_CAS = """
local t = redis.call('HGET', KEYS[1], 't') or ''
if t ~= ARGV[1] then return 0 end
for i = 5, #ARGV do
if redis.call('HEXISTS', KEYS[2], ARGV[i]) == 0 then return 2 end
end
redis.call('HSET', KEYS[1], 't', ARGV[2], 'm', ARGV[3])
redis.call('PEXPIRE', KEYS[1], ARGV[4])
return 1
"""
_FAILED = object()
class SharedSessions:
"""Compress-session trackers in Redis, beside the in-memory store."""
def __init__(self, client: Any) -> None:
self._client = client
self._cas = client.register_script(_CAS)
self._guard = Guard("compress sessions")
self._prefix = f"{key_prefix()}:session:"
def fetch(
self, store: SessionTrackerStore, key: str, local: PrefixCacheTracker | None
) -> PrefixCacheTracker | None:
"""The session's tracker when another replica wrote a newer one than
``local``, decoded but not installed; else ``None``."""
meta_key, msgs_key = self._keys(key)
token = self._guard.call("read", lambda: self._client.hget(meta_key, "t"), _FAILED)
if token is _FAILED:
return None
if token is None:
if local is not None: # lost or expired: the next write stores it whole
local.shared_token, local.shared_digests = "", frozenset()
return None
try:
if local is not None and _text(token) == local.shared_token:
return None
except UnicodeDecodeError:
return self._drop(local, meta_key, msgs_key)
row = self._guard.call("read", lambda: self._client.hmget(meta_key, "t", "m"), None)
if row is None:
return None
if row[0] is None: # expired between the two reads
return None
try:
token = _text(row[0])
except UnicodeDecodeError:
return self._drop(local, meta_key, msgs_key)
try:
meta = json.loads(_text(row[1]))
digests = meta.pop("table")
if not isinstance(digests, list) or not all(isinstance(d, str) for d in digests):
raise ValueError("table is not a list of digests")
except (TypeError, ValueError, KeyError, AttributeError, IndexError):
return self._unusable(local, token, "metadata", meta_key)
held = self._held(store, key, local)
missing = [d for d in dict.fromkeys(digests) if d not in held]
for start in range(0, len(missing), _CHUNK):
part = missing[start : start + _CHUNK]
values = self._guard.call(
"read", functools.partial(self._client.hmget, msgs_key, part), None
)
if values is None:
return None
for digest, value in zip(part, values, strict=True):
try:
text = None if value is None else _text(value)
except UnicodeDecodeError:
text = None
if text is None or _digest(text) != digest:
return self._unusable(local, token, "messages", msgs_key)
held[digest] = text
try:
tracker = store.decode_shared(meta, [json.loads(held[d]) for d in digests])
except (TypeError, ValueError, KeyError, AttributeError, OverflowError):
return self._unusable(local, token, "metadata", meta_key)
if tracker is None:
logger.info("compress sessions: shared state for %s has expired", meta_key)
return None
tracker.shared_token, tracker.shared_digests = token, frozenset(digests)
return tracker
@staticmethod
def _unusable(
local: PrefixCacheTracker | None, token: str, what: str, name: str
) -> PrefixCacheTracker | None:
"""Shared state this replica cannot use (evicted, corrupt or altered):
keep its own, and claim the current token with no messages known to be
stored, so its next write replaces the session whole."""
logger.warning("compress sessions: unusable %s in %s; this replica rewrites it", what, name)
if local is not None:
local.shared_token, local.shared_digests = token, frozenset()
return None
def _drop(
self, local: PrefixCacheTracker | None, meta_key: str, msgs_key: str
) -> PrefixCacheTracker | None:
"""A token that is not text cannot be claimed: delete the session, so
the next write stores it whole."""
logger.warning("compress sessions: corrupt token in %s; deleting the session", meta_key)
self._guard.call("write", lambda: self._client.delete(meta_key, msgs_key), 0)
if local is not None:
local.shared_token, local.shared_digests = "", frozenset()
return None
def publish(self, store: SessionTrackerStore, key: str, tracker: PrefixCacheTracker) -> None:
"""Write the messages Redis lacks, then the metadata unless another
replica wrote since ``tracker`` was read."""
try:
meta, table = store.encode_shared(key, tracker)
except (TypeError, ValueError) as exc: # messages that are not JSON
logger.debug("compress sessions: tracker not shareable (%s)", exc)
return
digests = [_digest(m) for m in table]
meta["table"] = digests
meta_json = json.dumps(meta)
ttl_ms = max(1000, int(tracker.retention_seconds() * 1000))
meta_key, msgs_key = self._keys(key)
referenced = sorted(set(digests))
def write(known: frozenset[str]) -> tuple[int, str]:
new = [(d, m) for d, m in zip(digests, table, strict=True) if d not in known]
token = uuid.uuid4().hex
pipe = self._client.pipeline(transaction=False)
for start in range(0, len(new), _CHUNK):
pipe.hset(msgs_key, mapping=dict(new[start : start + _CHUNK]))
pipe.pexpire(msgs_key, ttl_ms)
pipe.execute()
args = [tracker.shared_token, token, meta_json, ttl_ms, *referenced]
return int(self._cas(keys=[meta_key, msgs_key], args=args)), token
result = self._guard.call("write", lambda: write(tracker.shared_digests), None)
if result is not None and result[0] == 2:
# The messages hash lost entries (evicted on its own): store it whole.
result = self._guard.call("write", lambda: write(frozenset()), None)
if result is None:
return
written, token = result
if written == 1:
tracker.shared_token, tracker.shared_digests = token, frozenset(digests)
self._prune(msgs_key, set(digests))
elif written == 2:
# Evicted again during the whole rewrite: publish nothing, so no
# replica takes a session it cannot replay; the next turn retries.
logger.warning("compress sessions: messages of %s evicted while writing", meta_key)
elif written == 0:
# Two replicas ran turns of one session at once, which the caller's
# contract excludes; the next turn takes the state that won.
logger.warning("compress sessions: another replica wrote %s first", meta_key)
def _prune(self, msgs_key: str, referenced: set[str]) -> None:
"""Drop messages no transcript references (moved markers, edits,
compactions) once they outnumber the referenced ones."""
size = self._guard.call("write", lambda: int(self._client.hlen(msgs_key)), 0)
if size <= 2 * len(referenced):
return
def prune() -> None:
stale = [k for k in map(_text, self._client.hkeys(msgs_key)) if k not in referenced]
for start in range(0, len(stale), _CHUNK):
self._client.hdel(msgs_key, *stale[start : start + _CHUNK])
self._guard.call("write", prune, None)
def _keys(self, key: str) -> tuple[str, str]:
# One hash tag: the compare-and-set script names both keys, which Redis
# Cluster allows only within one slot.
base = f"{self._prefix}{{{hashlib.blake2b(key.encode(), digest_size=16).hexdigest()}}}"
return f"{base}:meta", f"{base}:msgs"
@staticmethod
def _held(
store: SessionTrackerStore, key: str, local: PrefixCacheTracker | None
) -> dict[str, str]:
"""The messages this replica already holds for the session, by digest."""
if local is None:
return {}
try:
_, table = store.encode_shared(key, local)
except (TypeError, ValueError):
return {}
return {_digest(m): m for m in table}
def _digest(message_json: str) -> str:
return hashlib.blake2b(message_json.encode(), digest_size=16).hexdigest()
def _text(value: Any) -> str:
return value.decode() if isinstance(value, bytes) else str(value)
def open_shared_sessions() -> SharedSessions | None:
"""The shared store ``HEADROOM_COMPRESS_SESSION_STORE`` names, or ``None``.
Raises :class:`~headroom.exceptions.ConfigurationError` when it is set but
unusable, so a replica meant to share sessions never starts without it."""
url = os.environ.get(STORE_ENV, "").strip()
if not url:
return None
client = connect(url, setting=STORE_ENV)
ccr = (os.environ.get("HEADROOM_CCR_BACKEND") or "").strip().lower()
if ccr not in ("", "redis"):
logger.warning(
"%s is set but HEADROOM_CCR_BACKEND=%s: CCR markers in a session's "
"transcript resolve only on the replica that made them",
STORE_ENV,
ccr,
)
return SharedSessions(client)
+41 -20
View File
@@ -36,6 +36,7 @@ from typing import TYPE_CHECKING, Any
from headroom import paths as _paths
from headroom import savings_ledger
from headroom.cache.compression_store import format_retrieval_miss_detail
from headroom.exceptions import StorageError
from headroom.log_safety import describe_exception, redact_url, safe_id
from headroom.telemetry import session as telemetry_session
@@ -460,16 +461,31 @@ class HeadroomMCPServer:
# Store original in local store for later retrieval
store = self._get_local_store()
hash_key = store.store(
original=content,
compressed=compressed_content
if isinstance(compressed_content, str)
else json.dumps(compressed_content),
original_tokens=input_tokens,
compressed_tokens=output_tokens,
compression_strategy="mcp_compress",
ttl=MCP_SESSION_TTL,
)
try:
hash_key = store.store(
original=content,
compressed=compressed_content
if isinstance(compressed_content, str)
else json.dumps(compressed_content),
original_tokens=input_tokens,
compressed_tokens=output_tokens,
compression_strategy="mcp_compress",
ttl=MCP_SESSION_TTL,
)
except StorageError as e:
# No stored original: hand back the content itself, which also
# keeps out any marker the pipeline put in the compressed text.
logger.warning("headroom_compress: returning the original, CCR store refused it: %s", e)
return {
"compressed": content,
"hash": None,
"original_tokens": input_tokens,
"compressed_tokens": input_tokens,
"tokens_saved": 0,
"savings_percent": 0,
"transforms": [],
"note": "Not compressed: the CCR store could not keep the original.",
}
# Track stats
strategy = (
@@ -1085,16 +1101,21 @@ class HeadroomMCPServer:
# Fresh read: store in CCR and cache the hash
store = self._get_local_store()
token_estimate = self._estimate_tokens(content)
ccr_hash = store.store(
original=content,
compressed=f"[File: {path.name}, {line_count} lines]",
original_tokens=token_estimate,
compressed_tokens=5,
tool_name="headroom_read",
ttl=MCP_SESSION_TTL,
)
self._file_cache[str_path] = (content_hash, ccr_hash, line_count, token_estimate)
try:
ccr_hash = store.store(
original=content,
compressed=f"[File: {path.name}, {line_count} lines]",
original_tokens=token_estimate,
compressed_tokens=5,
tool_name="headroom_read",
ttl=MCP_SESSION_TTL,
)
except StorageError as e:
# The full content is returned below either way; without a stored
# original, a re-read must not answer with a hash.
logger.warning("headroom_read: not cached, the CCR store refused it: %s", e)
else:
self._file_cache[str_path] = (content_hash, ccr_hash, line_count, token_estimate)
# Return full content with line numbers (like Claude Code's Read tool)
numbered_lines = []
+22
View File
@@ -5,8 +5,18 @@ from __future__ import annotations
from dataclasses import dataclass
from typing import Any
from headroom.proxy.tool_name_policy import extract_tool_name
from .tool_injection import CCR_TOOL_NAME, parse_tool_call
_CLIENT_CCR_TOOL_ALIASES = frozenset(
{
"headroom_headroom_retrieve",
"mcp__headroom__headroom_retrieve",
"mcp_headroom_headroom_retrieve",
}
)
@dataclass
class CCRToolCall:
@@ -128,6 +138,18 @@ def has_ccr_retrieve_tool(tools: Any) -> bool:
return False
def client_retrieval_tool_name(tools: list[dict[str, Any]] | None) -> str | None:
"""Select the canonical retrieval tool, or a default Headroom MCP alias."""
alias = None
for tool in tools or ():
name = extract_tool_name(tool)
if name == CCR_TOOL_NAME:
return name
if alias is None and isinstance(name, str) and name.lower() in _CLIENT_CCR_TOOL_ALIASES:
alias = name
return alias
def has_ccr_tool_calls(response: dict[str, Any], provider: str) -> bool:
"""Return true when ``response`` contains at least one CCR tool call."""
return any(is_ccr_tool_call(tool_call) for tool_call in extract_tool_calls(response, provider))
+15 -8
View File
@@ -154,6 +154,8 @@ def create_ccr_tool_definition(
def create_system_instructions(
hashes: list[str],
retrieval_endpoint: str = "/v1/retrieve",
*,
retrieval_tool_name: str = CCR_TOOL_NAME,
) -> str:
"""Create system message instructions for CCR retrieval.
@@ -163,6 +165,7 @@ def create_system_instructions(
Args:
hashes: List of hash keys for compressed content in this context.
retrieval_endpoint: The endpoint path for retrieval.
retrieval_tool_name: Executable tool name from the client's registry.
Returns:
Instruction text to append to system message.
@@ -173,10 +176,10 @@ def create_system_instructions(
## Compressed Context Available
Some tool outputs have been compressed to reduce context size. If you need
the full uncompressed data, you can retrieve it using the `{CCR_TOOL_NAME}` tool.
the full uncompressed data, you can retrieve it using the `{retrieval_tool_name}` tool.
**How to retrieve:**
- Call `{CCR_TOOL_NAME}(hash="<hash>")` to get the full original content back
- Call `{retrieval_tool_name}(hash="<hash>")` to get the full original content back
**Available hashes:** {hash_list}
@@ -456,11 +459,10 @@ class CCRToolInjector:
tools = tools or []
# Check if already present (e.g., from MCP server)
for tool in tools:
tool_name = tool.get("name") or tool.get("function", {}).get("name")
if tool_name == CCR_TOOL_NAME:
return tools, False # Already present, skip injection
from .tool_calls import client_retrieval_tool_name
if client_retrieval_tool_name(tools):
return tools, False # Already present, skip injection
# Add CCR tool
ccr_tool = create_ccr_tool_definition(self.provider)
@@ -469,11 +471,13 @@ class CCRToolInjector:
def inject_into_system_message(
self,
messages: list[dict[str, Any]],
tools: list[dict[str, Any]] | None = None,
) -> list[dict[str, Any]]:
"""Inject retrieval instructions into system message.
Args:
messages: List of messages.
tools: Available tool definitions for selecting an executable retrieval name.
Returns:
Updated messages with instructions added to system message.
@@ -481,9 +485,12 @@ class CCRToolInjector:
if not self.inject_system_instructions or not self.has_compressed_content:
return messages
from .tool_calls import client_retrieval_tool_name
instructions = create_system_instructions(
self._detected_hashes,
self.retrieval_endpoint,
retrieval_tool_name=client_retrieval_tool_name(tools) or CCR_TOOL_NAME,
)
# Find and update system message
@@ -567,7 +574,7 @@ class CCRToolInjector:
updated_tools, was_injected = self.inject_tool_definition(
tools, session_has_done_ccr=session_has_done_ccr
)
updated_messages = self.inject_into_system_message(messages)
updated_messages = self.inject_into_system_message(messages, tools=updated_tools)
return updated_messages, updated_tools if updated_tools else None, was_injected
+3
View File
@@ -7,6 +7,8 @@ from pathlib import Path
import click
from headroom.offline import pin_litellm_cost_map_local
from .main import main
@@ -480,6 +482,7 @@ def _run_memory_eval(
answer_fn = None
if answer_model:
try:
pin_litellm_cost_map_local()
import litellm
def answer_fn(question: str, memories: list[str]) -> str:
+3
View File
@@ -7,6 +7,8 @@ from typing import TYPE_CHECKING, Any, NamedTuple
import click
from headroom.offline import pin_litellm_cost_map_local
if TYPE_CHECKING:
from ..learn.base import LearnPlugin
@@ -390,6 +392,7 @@ def _make_llm_judge(model: str) -> Any:
try:
import json
pin_litellm_cost_map_local()
import litellm
except ImportError:
return None
+1 -1
View File
@@ -598,7 +598,7 @@ def show_memory(
# If not found with exact ID, try partial match
if mem is None:
# Query all and filter by prefix
all_memories = asyncio.run(store.query(MemoryFilter(limit=1000)))
all_memories = asyncio.run(store.query(MemoryFilter()))
matches = [m for m in all_memories if m.id.startswith(memory_id)]
if len(matches) == 0:
+9 -1
View File
@@ -8110,7 +8110,15 @@ def zcode(
if prepare_only:
return
upstream = _detect_zcode_upstream()
# _ensure_proxy moves to another port when the requested one is held by a
# non-Headroom service. Resolve that port first so the upstream is chosen
# against the port the proxy will actually bind.
if not no_proxy and not (_check_proxy(port) and not _foreign_listener(port)):
try:
port = _find_available_port(port)
except (OSError, RuntimeError):
pass # _ensure_proxy reports the same error
upstream = _detect_zcode_upstream(proxy_port=port)
anthropic_url, openai_url = _zcode_upstream_to_urls(upstream)
def _print_zcode_setup(actual_port: int = port) -> None:
+41 -9
View File
@@ -1069,6 +1069,14 @@ def _set_header_default(headers: dict[str, str], name: str, value: str) -> None:
headers[name] = value
def _remove_headers(headers: dict[str, str], *names: str) -> None:
"""Remove every case variant of the named headers in place."""
names_lower = {name.lower() for name in names}
for key in list(headers):
if key.lower() in names_lower:
del headers[key]
def _copilot_token_exchange_headers(
oauth_token: str, *, integration_id: str | None = None
) -> dict[str, str]:
@@ -1695,7 +1703,7 @@ def _is_forwardable_copilot_bearer_token(token: str) -> bool:
def _token_kind(token: str) -> str:
"""Return a non-sensitive label for the token type, safe to log."""
t = token.strip()
for prefix in ("tid_", "gho_", "ghs_", "ghp_", "github_pat_"):
for prefix in ("tid_", "ghu_", "gho_", "ghs_", "ghp_", "github_pat_"):
if t.startswith(prefix):
return prefix + "***"
return "unknown" if t else "empty"
@@ -1725,6 +1733,36 @@ async def apply_copilot_api_auth(headers: dict[str, str], *, url: str) -> dict[s
if not is_copilot_upstream_url(url):
return resolved
incoming_auth = next((v for k, v in resolved.items() if k.lower() == "authorization"), None)
scheme, _, raw_token = incoming_auth.partition(" ") if incoming_auth else ("", "", "")
# Inline completions accept the editor's own OAuth credential. Keep its
# account and integration metadata rather than substituting the operator's
# seat or adding chat-specific defaults (#3352).
if (
scheme.lower() == "bearer"
and raw_token.startswith("ghu_")
and is_copilot_completions_host(url)
and not _is_managed_copilot_seeded_bearer(raw_token)
):
upstream = urlparse(url)
base = urlparse(copilot_completions_base_url())
path = upstream.path
prefix = base.path.rstrip("/")
if (
prefix
and upstream.scheme == base.scheme
and upstream.netloc.lower() == base.netloc.lower()
and path.startswith(prefix + "/")
):
path = path[len(prefix) :]
if is_copilot_completions_path(path):
logger.info(
"apply_copilot_api_auth: passing through inline editor token kind=%s",
_token_kind(raw_token),
)
_remove_headers(resolved, "x-api-key")
return resolved
# Read the CLIENT's integration ID before any default is applied, so the
# credential we mint below can be bound to the surface that actually made
# the call rather than to whatever this proxy happens to default to.
@@ -1734,9 +1772,7 @@ async def apply_copilot_api_auth(headers: dict[str, str], *, url: str) -> dict[s
for name, value in _copilot_chat_header_defaults(integration_id).items():
_set_header_default(resolved, name, value)
incoming_auth = next((v for k, v in resolved.items() if k.lower() == "authorization"), None)
if incoming_auth:
scheme, _, raw_token = incoming_auth.partition(" ")
if (
scheme.lower() == "bearer"
and raw_token
@@ -1752,9 +1788,7 @@ async def apply_copilot_api_auth(headers: dict[str, str], *, url: str) -> dict[s
"apply_copilot_api_auth: passing through client token kind=%s",
_token_kind(raw_token),
)
for key in list(resolved):
if key.lower() == "x-api-key":
resolved.pop(key)
_remove_headers(resolved, "x-api-key")
return resolved
logger.info(
"apply_copilot_api_auth: incoming token not suitable (kind=%s), will replace",
@@ -1762,9 +1796,7 @@ async def apply_copilot_api_auth(headers: dict[str, str], *, url: str) -> dict[s
)
token = await get_copilot_token_provider().get_api_token(integration_id=integration_id)
for key in list(resolved):
if key.lower() in {"authorization", "x-api-key"}:
resolved.pop(key)
_remove_headers(resolved, "authorization", "x-api-key")
resolved["Authorization"] = f"Bearer {token.token}"
# The credential and the integration ID must leave together. Until now the
# ID was applied with set-default semantics BEFORE this branch was chosen,
+3 -1
View File
@@ -15,7 +15,7 @@ from collections.abc import Callable
from dataclasses import dataclass, field
from typing import TYPE_CHECKING, Any
from headroom.offline import guard_egress
from headroom.offline import guard_egress, pin_litellm_cost_map_local
if TYPE_CHECKING:
from headroom.transforms.html_extractor import HTMLExtractor
@@ -316,6 +316,7 @@ class HTMLExtractionEvaluator:
else:
try:
pin_litellm_cost_map_local()
import litellm
def judge(question: str, ground_truth: str, prediction: str) -> tuple[float, str]:
@@ -396,6 +397,7 @@ Answer concisely and factually based only on the content provided."""
)
else:
pin_litellm_cost_map_local()
import litellm
litellm_response = litellm.completion(
+2 -1
View File
@@ -17,7 +17,7 @@ from __future__ import annotations
import logging
from collections.abc import Callable
from headroom.offline import guard_egress
from headroom.offline import guard_egress, pin_litellm_cost_map_local
logger = logging.getLogger(__name__)
@@ -169,6 +169,7 @@ def create_litellm_judge(
score, reasoning = judge_fn(question, ground_truth, prediction)
"""
try:
pin_litellm_cost_map_local()
import litellm
except ImportError as e:
raise ImportError(
+2
View File
@@ -30,6 +30,7 @@ from headroom.evals.memory.locomo import (
)
from headroom.evals.metrics import compute_exact_match, compute_f1
from headroom.memory import HierarchicalMemory, MemoryConfig
from headroom.offline import pin_litellm_cost_map_local
logger = logging.getLogger(__name__)
@@ -277,6 +278,7 @@ class LoCoMoEvaluator:
List of extracted memory dicts with 'content' and 'category'.
"""
try:
pin_litellm_cost_map_local()
import litellm
except ImportError:
logger.warning("litellm not available, falling back to raw dialogue storage")
+6 -2
View File
@@ -24,8 +24,6 @@ from datetime import datetime
from pathlib import Path
from typing import Any
import litellm
from headroom.evals.memory.locomo import (
LOCOMO_CATEGORIES,
LoCoMoCase,
@@ -37,6 +35,12 @@ from headroom.memory.backends.local import LocalBackend, LocalBackendConfig
from headroom.memory.models import Memory
from headroom.memory.system import MemoryBackend
from headroom.memory.tools import MEMORY_TOOLS
from headroom.offline import pin_litellm_cost_map_local
# Before the import: litellm fetches its pricing table at import time unless
# told not to, and HEADROOM_OFFLINE forbids that fetch.
pin_litellm_cost_map_local()
import litellm # noqa: E402
logger = logging.getLogger(__name__)
+114 -40
View File
@@ -28,21 +28,41 @@ Scope of the guarantee — read this before citing it in a threat model:
the wrong inode by a path that changed underneath us. ``O_NOFOLLOW`` means a
symlink planted at the path fails the open outright rather than redirecting
the write.
* **Windows**: *not* enforced, and deliberately not claimed. Who may read an
NTFS file is decided by its ACL. ``os.chmod`` on Windows only toggles the
read-only attribute and leaves the ACL untouched, so ``chmod(0o600)`` returns
successfully while ``stat.S_IMODE`` still reports ``0666`` and the file stays
readable per the inherited ACL. Python ships no ACL API, so Headroom does not
pretend to set one: on Windows the log inherits the ACL of its parent
directory and :data:`OWNER_ONLY_SUPPORTED` is ``False``. Callers that create
sensitive files say so once in the log (see
``headroom.proxy.helpers._setup_file_logging``), and operators should treat
the log directory itself as the access-control boundary — keep it under the
user profile, and do not put it on a share.
* **Windows**: mode bits do not control read access there — who may read an
NTFS file is decided by its ACL, and ``os.chmod`` only toggles the
read-only attribute and leaves the ACL untouched, so ``chmod(0o600)``
returns successfully while ``stat.S_IMODE`` still reports ``0666``. That is
why :data:`OWNER_ONLY_SUPPORTED` — "mode bits enforce this" — is ``False``
on Windows and stays that way regardless of the rest of this paragraph.
:func:`restrict_fd_to_owner` and :func:`restrict_path_to_owner` nonetheless
restrict the log, its rotated backups, and the JSONL request log there too,
through :mod:`headroom._fileperms_windows`: a DACL with exactly one entry
(the calling user, full control), built fresh rather than merged with the
inherited entries that made the file readable in the first place, and
applied with ``PROTECTED_DACL_SECURITY_INFORMATION`` so those inherited
entries are dropped rather than left alongside it. Unlike the POSIX path
this can fail per-call (a non-NTFS volume, a missing privilege), so callers
that need to know whether it actually took effect call
:func:`verify_owner_only` rather than trusting the static flag — see
``headroom.proxy.helpers._warn_once_if_not_protected``, which warns only
when verification fails rather than unconditionally on Windows. Not
extended (yet) to the sqlite-backed memory/CCR stores
(:func:`ensure_private_file`/:func:`connect_private_sqlite`) or
:func:`private_dir` — those remain unenforced on Windows, same as before.
``O_NOFOLLOW`` does not exist on Windows either, so the symlink protection
there is the explicit :func:`is_symlink` check callers make before opening, not
a kernel-enforced one.
``O_NOFOLLOW`` does not exist on Windows, so the CRT ``os.open`` underneath
Python's own ``open()`` has no way to refuse a symlink/junction there — it
silently follows one to whatever it points at. :func:`open_owner_only` does
not route through that on Windows for this reason: it opens via
``headroom._fileperms_windows.open_no_follow``, which uses
``FILE_FLAG_OPEN_REPARSE_POINT`` to open the reparse point itself regardless
of create-or-open disposition, and refuses it outright if the resulting
handle's own attributes show it is one — closing the same gap ``O_NOFOLLOW``
closes on POSIX, checked on the handle rather than the path so there is
nothing for a race to redirect. :func:`restrict_path_to_owner` uses the same
flag for the same reason when narrowing a file it did not open itself
(rotated backups): because that path only ever touches the reparse point's
own DACL, never a target's, it is safe even without the attribute check.
"""
from __future__ import annotations
@@ -62,9 +82,14 @@ OWNER_ONLY_MODE = 0o600
OWNER_ONLY_DIR_MODE = 0o700
#: ``True`` only where the mode bits above actually decide who can read the
#: file. See the module docstring for why Windows is excluded.
#: file. See the module docstring for why Windows is excluded -- it has its
#: own, separately-verified mechanism instead, not reflected in this flag.
OWNER_ONLY_SUPPORTED = os.name == "posix"
_win: Any = None
if os.name == "nt":
from . import _fileperms_windows as _win
def _open_flags(*, truncate: bool = False) -> int:
flags = os.O_CREAT | os.O_WRONLY | (os.O_TRUNC if truncate else os.O_APPEND)
@@ -83,14 +108,17 @@ def restrict_fd_to_owner(fd: int) -> bool:
Acts on the descriptor, not the path, so there is no window in which the
mode could land on a different file, and no way for a symlink to move it.
Returns ``False`` on platforms where the mode bits do not carry the
guarantee rather than reporting a protection that was not established.
On Windows this goes through :mod:`headroom._fileperms_windows` instead
of mode bits (see the module docstring); returns ``False`` if that fails
too, rather than reporting a protection that was not established.
"""
if not OWNER_ONLY_SUPPORTED:
return False
if stat.S_IMODE(os.fstat(fd).st_mode) != OWNER_ONLY_MODE:
os.fchmod(fd, OWNER_ONLY_MODE)
return True
if OWNER_ONLY_SUPPORTED:
if stat.S_IMODE(os.fstat(fd).st_mode) != OWNER_ONLY_MODE:
os.fchmod(fd, OWNER_ONLY_MODE)
return True
if _win is not None:
return bool(_win.restrict_handle(fd))
return False
def restrict_path_to_owner(path: str | os.PathLike[str]) -> bool:
@@ -98,18 +126,43 @@ def restrict_path_to_owner(path: str | os.PathLike[str]) -> bool:
For files Headroom did not open itself — rotated log backups, and backups
left behind by an older unhardened run. A path that is a symlink is left
alone: the target is not ours to re-permission.
alone on every platform: the target is not ours to re-permission. On
Windows the ACL path (see the module docstring) adds
``FILE_FLAG_OPEN_REPARSE_POINT`` underneath that check as a second guard.
"""
if not OWNER_ONLY_SUPPORTED:
return False
try:
if os.path.islink(path) or not os.path.exists(path):
return False
if stat.S_IMODE(os.stat(path).st_mode) != OWNER_ONLY_MODE:
os.chmod(path, OWNER_ONLY_MODE)
if OWNER_ONLY_SUPPORTED:
if stat.S_IMODE(os.stat(path).st_mode) != OWNER_ONLY_MODE:
os.chmod(path, OWNER_ONLY_MODE)
return True
except OSError:
return False
return True
if _win is not None:
return bool(_win.restrict_path(os.fspath(path)))
return False
def verify_owner_only(path: str | os.PathLike[str]) -> bool:
"""Confirm *path* is restricted to its current owner right now.
Unlike :data:`OWNER_ONLY_SUPPORTED` (a static per-platform flag) or the
return value of :func:`restrict_fd_to_owner`/:func:`restrict_path_to_owner`
(whether the API calls *reported* success), this re-reads the file's
actual permissions. On Windows the ACL call can fail for reasons that
have nothing to do with Headroom's code -- a non-NTFS volume, a missing
privilege -- so a caller deciding whether to warn an operator should ask
what happened to *this* file, not assume from the platform.
"""
if OWNER_ONLY_SUPPORTED:
try:
return stat.S_IMODE(os.stat(path).st_mode) == OWNER_ONLY_MODE
except OSError:
return False
if _win is not None:
return bool(_win.verify_path(os.fspath(path)))
return False
def open_owner_only(
@@ -124,22 +177,43 @@ def open_owner_only(
Raises ``OSError`` — which every caller already treats as "logging is
unavailable, carry on" — if the path cannot be opened, including when it is
a symlink on a platform with ``O_NOFOLLOW``. Failing closed is deliberate:
a redirected sensitive log is worse than no log.
a symlink or junction. Failing closed is deliberate: a redirected sensitive
log is worse than no log.
On POSIX, ``O_NOFOLLOW`` makes the ``os.open`` below refuse a symlink at
the kernel level. Windows has no such flag -- plain ``os.open`` there
silently follows a planted symlink/junction to whatever it points at, so
a DACL applied afterward lands on the target, not the intended file; this
goes through :func:`headroom._fileperms_windows.open_no_follow` instead,
which opens the reparse point itself and verifies that before touching
anything, closing the one path/open gap ``O_NOFOLLOW`` closes on POSIX.
"""
if mode[:1] not in ("a", "w"):
raise ValueError(f"open_owner_only: mode must start with 'a' or 'w', got {mode!r}")
fd = os.open(path, _open_flags(truncate=mode.startswith("w")), OWNER_ONLY_MODE)
try:
restrict_fd_to_owner(fd)
return open(fd, mode, encoding=encoding, errors=errors, newline=newline, closefd=True)
except BaseException:
truncate = mode.startswith("w")
if OWNER_ONLY_SUPPORTED:
fd = os.open(path, _open_flags(truncate=truncate), OWNER_ONLY_MODE)
try:
os.close(fd)
except OSError:
# open() can have taken and closed the descriptor on its way out.
pass
raise
restrict_fd_to_owner(fd)
return open(fd, mode, encoding=encoding, errors=errors, newline=newline, closefd=True)
except BaseException:
try:
os.close(fd)
except OSError:
# open() can have taken and closed the descriptor on its way out.
pass
raise
if _win is not None:
fd = _win.open_no_follow(os.fspath(path), truncate=truncate)
try:
return open(fd, mode, encoding=encoding, errors=errors, newline=newline, closefd=True)
except BaseException:
try:
os.close(fd)
except OSError:
pass
raise
return open(path, mode, encoding=encoding, errors=errors, newline=newline)
def ensure_private_file(path: str | os.PathLike[str], *, what: str = "file") -> None:
+10 -6
View File
@@ -36,6 +36,7 @@ if TYPE_CHECKING:
# Import the enum from the dependency-free module so importing the compressor
# does not eagerly import trained_router (and thus torch/transformers) — that
# eager import crashed on Python 3.13+ (#2513).
from .decoder_guard import pillow_is_safe
from .image_types import ImageMemo, Technique
logger = logging.getLogger(__name__)
@@ -333,13 +334,11 @@ class ImageCompressor:
# Resize
resized = img.resize((new_width, new_height), Image.Resampling.LANCZOS)
# Convert to RGB if needed (for JPEG)
if resized.mode in ("RGBA", "P"):
resized = resized.convert("RGB")
# Save as JPEG for best compression
from .tile_optimizer import _jpeg_ready
buf = io.BytesIO()
resized.save(buf, format="JPEG", quality=quality, optimize=True)
_jpeg_ready(resized).save(buf, format="JPEG", quality=quality, optimize=True)
return buf.getvalue(), "image/jpeg"
def _estimate_tokens(self, image_data: bytes, detail: str = "high") -> int:
@@ -702,7 +701,12 @@ class ImageCompressor:
Returns:
Messages with compressed images
"""
if not self.has_images(messages):
# Reset first: the per-worker singleton (proxy/image_isolation.py) keeps
# one ImageCompressor for every request and reports last_result whenever
# it is not None, so a request we return early on below must not inherit
# the previous request's technique and token numbers.
self.last_result = None
if not self.has_images(messages) or not pillow_is_safe():
return messages
# Step 1: Tile-boundary optimization (always safe, pure math)
+39
View File
@@ -0,0 +1,39 @@
"""Never decode untrusted images with a Pillow that has known decoder bugs.
Pillow 13.0.0 is the only fix for ten decoder CVEs on untrusted images
(CVE-2026-112395, -112895 and others). uv.lock and the release image take 13, but the published
package metadata cannot require it: fastembed caps ``pillow<13``, so
``pip install headroom-ai[all]`` resolves 12.x, and Python 3.10 has no Pillow 13
at all. On those installs Headroom forwards images unchanged instead of opening
them. Remove this once fastembed allows Pillow 13 and the image extra requires it.
"""
from __future__ import annotations
import functools
import logging
logger = logging.getLogger(__name__)
FIXED_PILLOW_MAJOR = 13
@functools.cache
def pillow_is_safe() -> bool:
"""True when the imported Pillow has the decoder fixes; warns once if not."""
try:
import PIL
except ImportError:
return False # Nothing can decode; the image paths already skip.
installed = PIL.__version__
if int(installed.split(".")[0]) >= FIXED_PILLOW_MAJOR:
return True
logger.warning(
"Headroom will not decode images: Pillow %s has decoder vulnerabilities "
"fixed only in Pillow %d, so images are forwarded unchanged and not "
"compressed. Install pillow>=%d (Python 3.11+) to turn image compression on.",
installed,
FIXED_PILLOW_MAJOR,
FIXED_PILLOW_MAJOR,
)
return False
+24 -5
View File
@@ -167,6 +167,29 @@ def find_optimal_anthropic_dimensions(width: int, height: int) -> tuple[int, int
# ---------------------------------------------------------------------------
def _jpeg_ready(img: Any) -> Any:
"""Return ``img`` in a mode JPEG can store.
JPEG has no alpha, and ``convert("RGB")`` simply drops it, so transparent
pixels show their hidden colour (usually black). Composite them onto
white instead: alpha bands, palette transparency and PNG ``tRNS`` on RGB
or grayscale images alike. Palette, bilevel and CMYK/YCbCr images convert
to RGB. High-bit-depth modes (``I;16``, ``I``, ``F``) have no faithful
8-bit form, so they are returned as-is and the JPEG save fails as before,
which makes callers keep the original image.
"""
from PIL import Image
if img.has_transparency_data:
rgba = img.convert("RGBA")
flat = Image.new("RGB", rgba.size, (255, 255, 255))
flat.paste(rgba, mask=rgba.getchannel("A"))
return flat
if img.mode in ("1", "P", "CMYK", "YCbCr"):
return img.convert("RGB")
return img
def _resize_image_bytes(
image_data: bytes, target_width: int, target_height: int
) -> tuple[bytes, str]:
@@ -182,12 +205,8 @@ def _resize_image_bytes(
resized = img.resize((target_width, target_height), Image.Resampling.LANCZOS)
# Convert RGBA to RGB for JPEG
if resized.mode in ("RGBA", "P"):
resized = resized.convert("RGB")
buf = io.BytesIO()
resized.save(buf, format="JPEG", quality=85, optimize=True)
_jpeg_ready(resized).save(buf, format="JPEG", quality=85, optimize=True)
return buf.getvalue(), "image/jpeg"
+12
View File
@@ -160,6 +160,18 @@ def build_runtime_command(manifest: DeploymentManifest) -> list[str]:
container_home,
"--env",
f"HOME={container_home}",
# Docker creates the parent of every bind mount as root:root when it is
# absent from the image, so $HOME itself is NOT writable by the
# --user <host-uid> process (issue #4207). Anything that writes under
# $HOME outside the mounts then fails, which is what breaks the
# HuggingFace download of the Kompress model. Point the HuggingFace and
# XDG caches at the bind-mounted workspace instead: that directory
# belongs to the host user the container runs as, so it is writable,
# and it survives `docker rm` of the container.
"--env",
f"HF_HOME={container_home}/.headroom/cache/huggingface",
"--env",
f"XDG_CACHE_HOME={container_home}/.headroom/cache",
"--env",
"PYTHONUNBUFFERED=1",
# Canonical Headroom filesystem contract (issue #175).
+3
View File
@@ -27,7 +27,10 @@ from __future__ import annotations
import logging
from typing import Any
from headroom.offline import pin_crewai_telemetry_off
try:
pin_crewai_telemetry_off()
from crewai.tools.base_tool import BaseTool
CREWAI_AVAILABLE = True
+2 -1
View File
@@ -24,12 +24,13 @@ from headroom.integrations._compress_backend import ( # noqa: F401
_DEFAULT_CLOUD_URL,
CompressBackend,
)
from headroom.offline import guard_egress # noqa: F401
from headroom.offline import guard_egress, pin_litellm_cost_map_local # noqa: F401
logger = logging.getLogger(__name__)
try:
pin_litellm_cost_map_local()
from litellm.integrations.custom_logger import CustomLogger as _CustomLogger
except ImportError: # litellm not installed — fall back to plain object
_CustomLogger = object # type: ignore[assignment,misc]
+2
View File
@@ -25,6 +25,7 @@ import time
import typing
from headroom._subprocess import Popen, run
from headroom.offline import pin_litellm_cost_map_local
from .loops import LoopPattern, apply_loop_weighting, detect_loops, format_loops_for_digest
from .models import (
@@ -1095,6 +1096,7 @@ def _call_llm(
if model in _CLI_MODEL_IDS:
return _call_cli_llm(digest, model, on_progress=on_progress)
pin_litellm_cost_map_local()
import litellm
# Suppress LiteLLM's verbose logging
+51 -12
View File
@@ -16,7 +16,7 @@ from pathlib import Path
from headroom._subprocess import run
from ..managed_block import block_pattern, sanitize_block_text
from ..managed_block import sanitize_block_text
from ._shared import claude_config_dir
from .models import (
ProjectInfo,
@@ -29,7 +29,40 @@ from .models import (
# cannot close the block early (see headroom.managed_block).
_MARKER_START = "<!-- headroom:learn:start -->"
_MARKER_END = "<!-- headroom:learn:end -->"
_MARKER_PATTERN = block_pattern(_MARKER_START, _MARKER_END)
def _find_managed_block(text: str) -> tuple[int, int] | None:
"""Return the ``(start, end)`` offsets of the managed block, or None.
The block is a line that is exactly the start marker through the next line
that is exactly the end marker -- the shape ``_build_section`` writes. A
marker quoted inside prose (sharing its line with other text, or indented)
or inside a fenced code block (a Markdown example) is not a block
boundary, and a start marker with no end marker before the next start
marker is not a block. Every reader and writer of the block in
this module uses this one span, so the block that is parsed is the block
that is replaced (#4339). ``end`` stops after the end marker, before its
line break.
"""
offset = 0
start: int | None = None
fence: str | None = None # the open fence's run, e.g. "```" or "~~~~"
for line in text.splitlines(keepends=True):
bare = line.rstrip()
stripped = bare.lstrip(" ")
if len(bare) - len(stripped) <= 3 and stripped[:3] in ("```", "~~~"):
run = len(stripped) - len(stripped.lstrip(stripped[0]))
if fence is None:
fence = stripped[0] * run
elif stripped[0] == fence[0] and run >= len(fence) and not stripped[run:]:
fence = None
elif fence is None:
if bare == _MARKER_START:
start = offset
elif bare == _MARKER_END and start is not None:
return start, offset + len(bare)
offset += len(line)
return None
def _read_text_tolerant(file_path: Path) -> str:
@@ -258,8 +291,8 @@ def extract_marker_block(file_content: str) -> str | None:
(including the start/end markers) so it can be fed back to an LLM as
context without losing formatting. Returns None if no block is present.
"""
match = _MARKER_PATTERN.search(file_content)
return match.group(0) if match else None
span = _find_managed_block(file_content)
return file_content[span[0] : span[1]] if span else None
def _parse_prior_recommendations(existing: str) -> list[Recommendation]:
@@ -270,10 +303,10 @@ def _parse_prior_recommendations(existing: str) -> list[Recommendation]:
_build_section — target is set to a placeholder since the marker block
itself doesn't record it (blocks are always per-file and per-target).
"""
match = _MARKER_PATTERN.search(existing)
if not match:
span = _find_managed_block(existing)
if not span:
return []
inner = match.group(0)[len(_MARKER_START) : -len(_MARKER_END)]
inner = existing[span[0] + len(_MARKER_START) : span[1] - len(_MARKER_END)]
recs: list[Recommendation] = []
for part in re.split(r"\n### ", "\n" + inner)[1:]:
@@ -364,8 +397,12 @@ def _merge_into_file(file_path: Path, new_recommendations: list[Recommendation])
section = _build_section(merged)
if file_path.exists():
existing = _read_text_tolerant(file_path)
if _MARKER_START in existing:
return _MARKER_PATTERN.sub(lambda _match: section, existing)
# Replace only the managed block itself; marker strings quoted in
# prose on either side are hand-written text. No block (including a
# start marker without its end marker) -> append a fresh one (#4339).
span = _find_managed_block(existing)
if span:
return existing[: span[0]] + section + existing[span[1] :]
return existing.rstrip() + "\n\n" + section + "\n"
return section + "\n"
@@ -376,7 +413,9 @@ def _strip_marker_block(content: str) -> str:
Used when migrating a stale block out of the team-shared CLAUDE.md into the
personal CLAUDE.local.md. Returns "" if nothing but the block remained.
"""
cleaned = _MARKER_PATTERN.sub("", content)
cleaned = content
while span := _find_managed_block(cleaned):
cleaned = cleaned[: span[0]] + cleaned[span[1] :]
cleaned = re.sub(r"\n{3,}", "\n\n", cleaned).strip()
return cleaned + "\n" if cleaned else ""
@@ -562,11 +601,11 @@ class ClaudeCodeWriter(ContextWriter):
if target_path == legacy_path or not legacy_path.exists():
return []
legacy_text = _read_text_tolerant(legacy_path)
if _MARKER_START not in legacy_text:
if _find_managed_block(legacy_text) is None:
return []
# If the target already owns a block, it is the source of truth -- don't
# double-migrate or clobber accumulated learnings.
if target_path.exists() and _MARKER_START in _read_text_tolerant(target_path):
if target_path.exists() and _find_managed_block(_read_text_tolerant(target_path)):
return []
migrated = _parse_prior_recommendations(legacy_text)
+23 -17
View File
@@ -9,7 +9,6 @@ from __future__ import annotations
import json
import logging
import re
import shutil
from pathlib import Path
from typing import Any
@@ -29,25 +28,32 @@ from .base import (
logger = logging.getLogger(__name__)
def _strip_json_line_comments(text: str) -> str:
"""Strip ``//`` line comments from JSONC text.
Tries standard JSON first (via the caller) so URLs containing ``//`` are
never mangled; this is only invoked as a fallback once plain
``json.loads`` has already failed. Two-pass: (1) remove comment-only
lines, (2) strip inline trailing comments that follow a comma.
"""
cleaned = re.sub(r"^\s*//[^\n]*\n", "", text, flags=re.MULTILINE)
return re.sub(r",\s*//[^\n]*", ",", cleaned)
def _parse_json_loose(raw: str) -> dict[str, Any] | None:
"""Parse JSON or JSONC text, returning ``None`` if it can't be parsed as an object."""
"""Parse JSON or JSONC text, returning ``None`` if it can't be parsed as an object.
Standard JSON is tried first so URLs containing ``//`` are never touched.
The JSONC fallback reuses the OpenCode provider's string-aware stripping
of ``//`` and ``/* */`` comments and trailing commas, so this accepts the
same files ``headroom wrap``/``install`` already edit.
"""
try:
data = json.loads(raw)
except json.JSONDecodeError:
# Imported here: headroom.providers.opencode imports this package.
from headroom.providers.opencode.config import (
_strip_jsonc_comments,
_strip_jsonc_trailing_commas,
)
# The stripper treats an unterminated ``/*`` as running to EOF. That is
# malformed input, and accepting what precedes it would let the write
# path drop the rest of the file. A ``*/`` appended after a newline
# survives stripping unless it closes such a comment.
if not _strip_jsonc_comments(raw + "\n*/").endswith("*/"):
return None
cleaned = _strip_jsonc_trailing_commas(_strip_jsonc_comments(raw))
try:
data = json.loads(_strip_json_line_comments(raw))
data = json.loads(cleaned)
except json.JSONDecodeError:
return None
return data if isinstance(data, dict) else None
@@ -82,8 +88,8 @@ def _read_json_for_write(path: Path) -> dict[str, Any]:
"""Read a JSON/JSONC object for a subsequent full-file rewrite.
Returns ``{}`` only when the file is absent or empty (safe to start fresh).
``//`` line comments are stripped before parsing, matching the loose JSONC
handling used by the OpenCode provider-block writer — note the rewritten
JSONC comments and trailing commas are stripped before parsing, matching
the loose JSONC handling used by the OpenCode provider-block writer — note the rewritten
file loses any comments it had. If the file exists with content but still
does not parse as a JSON object, raise :class:`_MalformedConfigError` so
the caller aborts instead of overwriting unrelated user config — the
+97
View File
@@ -14,7 +14,9 @@ import asyncio
import logging
import os
import warnings
from collections.abc import Callable
from concurrent.futures import ThreadPoolExecutor
from copy import deepcopy
from functools import cached_property
from typing import TYPE_CHECKING, Any, cast
@@ -26,6 +28,8 @@ from headroom.onnx_runtime import create_cpu_session_options, hf_hub_download_lo
if TYPE_CHECKING:
from sentence_transformers import SentenceTransformer
from tokenizers import Tokenizer
from transformers import PreTrainedTokenizerBase
# Suppress HuggingFace Hub warnings about missing tokens and rate limits.
# These appear whenever hf_hub_download is called without HF_TOKEN set.
@@ -172,6 +176,48 @@ def _normalize_embeddings_batch(embeddings: np.ndarray) -> np.ndarray:
return result
def _fit_query_to_window(
user_text: str,
context: str,
max_tokens: int,
count_tokens: Callable[[str], int],
) -> str:
"""Reserve token space for both sources, retaining their recent tails."""
def tail(text: str, budget: int) -> str:
if budget <= 0:
return ""
if count_tokens(text) <= budget:
return text
low, high = 0, len(text)
while low < high:
middle = (low + high + 1) // 2
if count_tokens(text[-middle:]) <= budget:
low = middle
else:
high = middle - 1
return text[-low:] if low else ""
user_tokens, context_tokens = count_tokens(user_text), count_tokens(context)
available = max(0, max_tokens - (count_tokens("\n") if user_tokens and context_tokens else 0))
user_budget = min(user_tokens, (available + 1) // 2 if context_tokens else available)
context_budget = min(context_tokens, available - user_budget)
user_budget = min(user_tokens, available - context_budget)
while True:
rendered = "\n".join(
part for part in (tail(user_text, user_budget), tail(context, context_budget)) if part
)
excess = count_tokens(rendered) - max_tokens
if excess <= 0:
return rendered
# Retokenizing a suffix can change its first subword. Enforce the final
# joined window too, rather than assuming token counts are additive.
if user_budget >= context_budget and user_budget:
user_budget = max(0, user_budget - excess)
else:
context_budget = max(0, context_budget - excess)
# =============================================================================
# LocalEmbedder - sentence-transformers
# =============================================================================
@@ -219,6 +265,7 @@ class LocalEmbedder:
self._model_name = model_name or ML_MODEL_DEFAULTS.sentence_transformer
self._requested_device = device
self._model: SentenceTransformer | None = None
self._query_tokenizer: PreTrainedTokenizerBase | None = None
self._device: str | None = None
self._dimension: int | None = None
self._lock = asyncio.Lock()
@@ -328,6 +375,30 @@ class LocalEmbedder:
return _normalize_embedding(embedding)
async def prepare_query(self, user_text: str, context: str) -> str:
"""Fit both query sources with the configured model's tokenizer."""
async with self._lock:
if self._model is None:
await asyncio.get_event_loop().run_in_executor(None, self._load_model)
assert self._model is not None
if self._query_tokenizer is None:
self._query_tokenizer = deepcopy(self._model.tokenizer)
# Configure the private copy before concurrent query encodes.
self._query_tokenizer.encode("", add_special_tokens=False, truncation=False)
tokenizer = self._query_tokenizer
available = max(0, self._model.max_seq_length - tokenizer.num_special_tokens_to_add())
return await asyncio.get_event_loop().run_in_executor(
self._executor,
lambda: _fit_query_to_window(
user_text,
context,
available,
lambda text: len(
tokenizer.encode(text, add_special_tokens=False, truncation=False)
),
),
)
async def embed_batch(self, texts: list[str]) -> list[np.ndarray]:
"""Generate embeddings for multiple texts.
@@ -407,6 +478,7 @@ class LocalEmbedder:
self._executor.shutdown(wait=False)
self._executor = None
self._model = None
self._query_tokenizer = None
# =============================================================================
@@ -437,6 +509,7 @@ class OnnxLocalEmbedder:
self._max_length = max_length
self._session: Any = None
self._tokenizer: Any = None
self._query_tokenizer: Tokenizer | None = None
self._input_names: list[str] = []
self._lock = asyncio.Lock()
@@ -543,6 +616,29 @@ class OnnxLocalEmbedder:
embedding = await loop.run_in_executor(None, self._embed_single, text)
return cast(np.ndarray, embedding)
async def prepare_query(self, user_text: str, context: str) -> str:
"""Fit both query sources without mutating the inference tokenizer."""
from tokenizers import Tokenizer
async with self._lock:
if self._session is None:
await asyncio.get_event_loop().run_in_executor(None, self._load_model)
if self._query_tokenizer is None:
self._query_tokenizer = Tokenizer.from_str(self._tokenizer.to_str())
self._query_tokenizer.no_truncation()
self._query_tokenizer.no_padding()
tokenizer = self._query_tokenizer
available = max(0, self._max_length - tokenizer.num_special_tokens_to_add(False))
return await asyncio.get_event_loop().run_in_executor(
None,
lambda: _fit_query_to_window(
user_text,
context,
available,
lambda text: len(tokenizer.encode(text, add_special_tokens=False).ids),
),
)
async def embed_batch(self, texts: list[str]) -> list[np.ndarray]:
"""Generate embeddings for multiple texts."""
if not texts:
@@ -591,6 +687,7 @@ class OnnxLocalEmbedder:
"""Close resources."""
self._session = None
self._tokenizer = None
self._query_tokenizer = None
# =============================================================================
+14
View File
@@ -16,6 +16,7 @@ from __future__ import annotations
import asyncio
import logging
import uuid
from collections.abc import Awaitable, Callable
from dataclasses import dataclass, field
from pathlib import Path
from typing import TYPE_CHECKING, Any
@@ -405,6 +406,19 @@ class LocalBackend:
# Return primary memory
return primary_memory
async def prepare_search_query(self, user_text: str, context: str) -> str:
"""Apply the active local model's query window, including on cold backends."""
await self._ensure_initialized()
assert self._hierarchical_memory is not None
prepare: Callable[[str, str], Awaitable[str]] | None = getattr(
self._hierarchical_memory.embedder, "prepare_query", None
)
if prepare is not None:
return await prepare(user_text, context)
# Remote embedders do not expose their tokenizer; callers still supply
# character-bounded sources, without claiming a remote token guarantee.
return "\n".join(part for part in (user_text, context) if part)
async def search_memories(
self,
query: str,
+25 -13
View File
@@ -43,7 +43,7 @@ logger = logging.getLogger(__name__)
# Known prefixes that mark a working-directory line inside a client's
# ``<env>`` / ``<environment>`` system-prompt block. Ordered so that the
# most specific / most recent client format is tried first. Matched with
# literal ``str.find`` — no regex.
# literal line-start checks after trimming — no regex.
_CWD_PREFIXES: tuple[str, ...] = (
"Primary working directory:", # Claude Code (current)
"Working directory:", # Claude Code (older) / Codex
@@ -211,15 +211,15 @@ class ProjectResolver:
if not system_prompt:
return None
for prefix in _CWD_PREFIXES:
idx = system_prompt.find(prefix)
if idx < 0:
continue
start = idx + len(prefix)
end = system_prompt.find("\n", start)
chunk = system_prompt[start:] if end < 0 else system_prompt[start:end]
chunk = chunk.strip()
if chunk:
return chunk
for raw_line in system_prompt.split("\n"):
line = raw_line.strip()
if line.startswith("-"):
line = line[1:].lstrip()
if not line.startswith(prefix):
continue
chunk = line[len(prefix) :].strip()
if chunk:
return chunk
return None
@classmethod
@@ -248,9 +248,21 @@ class ProjectResolver:
except (OSError, ValueError):
normalised = cwd
normalised = normalised.rstrip(os.sep) or os.sep
# A path with no UTF-8 form cannot be hashed without a lossy encoding
# that could merge distinct directories onto one store. It reaches
# here either from the input (an unpaired surrogate, e.g. a
# JSON-decoded ``\ud800`` escape) or from ``realpath`` following a
# symlink to a non-UTF-8 filename, which POSIX returns as
# ``\udcXX`` surrogate escapes. Check after normalising so both are
# covered, and treat the cwd as unusable: resolution falls through to
# the next tier, or fails closed, instead of raising (#4162).
try:
encoded = normalised.encode("utf-8")
except UnicodeEncodeError:
return None
basename = os.path.basename(normalised) or "root"
safe_basename = cls._sanitize_basename(basename) or "project"
digest = hashlib.sha256(normalised.encode("utf-8")).hexdigest()[:16]
digest = hashlib.sha256(encoded).hexdigest()[:16]
key = f"{safe_basename}-{digest}"
return key, basename
@@ -481,7 +493,7 @@ def _first_user_text_with_cwd(messages: list[Any]) -> str:
continue
content = msg.get("content")
user_text = content if isinstance(content, str) else _text_from_blocks(content)
if user_text and any(prefix in user_text for prefix in _CWD_PREFIXES):
if user_text and ProjectResolver._extract_cwd_from_system_prompt(user_text) is not None:
return user_text
return ""
@@ -520,7 +532,7 @@ def extract_system_prompt(body: Mapping[str, Any]) -> str:
# redirect this request at another project's memory store by pasting
# its own ``cwd:`` line.
trusted = "\n".join(parts)
if not any(prefix in trusted for prefix in _CWD_PREFIXES):
if ProjectResolver._extract_cwd_from_system_prompt(trusted) is None:
cwd_text = _first_user_text_with_cwd(messages)
if cwd_text:
parts.append(cwd_text)
+84 -2
View File
@@ -8,8 +8,9 @@ deployment exists to carry.
Refused (this is not a sample — it is the rule, and the meta-test enforces it):
the telemetry beacon, the update check, the license/usage reporter, OTLP and
Langfuse export, HuggingFace/Kompress/fastembed model downloads, release-binary
downloads (codebase-memory-mcp among them), eval dataset downloads and the provider SDK
clients the eval harness drives, GitHub Copilot device-flow auth and token
downloads (codebase-memory-mcp among them), litellm's import-time pricing-table
refresh, CrewAI's import-time install tracking, eval dataset downloads and the
provider SDK clients the eval harness drives, GitHub Copilot device-flow auth and token
exchange, the Anthropic / Codex / Copilot subscription pollers, the OpenAI
embedders, both Headroom Cloud compression integrations, and the TLS
diagnostics (``doctor --network`` endpoint checks and the certificate-chain
@@ -101,6 +102,87 @@ def apply_offline_env() -> None:
os.environ.setdefault("TRANSFORMERS_OFFLINE", "1")
class _OfflineEnvPin:
"""An environment variable Headroom forces while ``HEADROOM_OFFLINE`` is
on, for a third-party library that dials out during its own import and
only listens to that variable.
Overwritten rather than ``setdefault``: these libraries accept only
``true``, so an operator ``1``, ``False`` or empty value would reopen a
connection the air-gap switch exists to refuse. The pin is Headroom's, so
it is also undone: called with the switch off, it puts back the value it
replaced, provided the variable still holds the pin. An operator's own
value is never touched outside offline mode.
"""
def __init__(self, name: str, value: str) -> None:
self.name = name
self.value = value
# Unset while no pin is in place; otherwise a 1-tuple of the value the
# pin replaced (None when the variable was absent).
self.before: tuple[str | None] | None = None
def __call__(self) -> None:
if is_offline():
if self.before is None:
self.before = (os.environ.get(self.name),)
os.environ[self.name] = self.value
elif self.before is not None:
(before,) = self.before
self.before = None
if os.environ.get(self.name) == self.value:
if before is None:
os.environ.pop(self.name, None)
else:
os.environ[self.name] = before
LITELLM_LOCAL_COST_MAP_ENV = "LITELLM_LOCAL_MODEL_COST_MAP"
_litellm_cost_map_pin = _OfflineEnvPin(LITELLM_LOCAL_COST_MAP_ENV, "True")
CREWAI_TELEMETRY_ENV = "CREWAI_DISABLE_TELEMETRY"
_crewai_telemetry_pin = _OfflineEnvPin(CREWAI_TELEMETRY_ENV, "true")
def pin_litellm_cost_map_local() -> None:
"""Keep litellm on its bundled pricing table under ``HEADROOM_OFFLINE``.
``import litellm`` fetches ``model_prices_and_context_window.json`` from
raw.githubusercontent.com at import time (three attempts) unless
``LITELLM_LOCAL_MODEL_COST_MAP`` is ``true``. That is not a client Headroom
builds, so no ``guard_egress`` site can dominate it; the only lever is the
env var, read once during that import. So every ``import litellm`` in
``headroom/`` calls this first, in the same scope, because the switch is
read when it is checked rather than when the package loads
(``create_app(ProxyConfig(offline=True))`` turns it on after import). The
chokepoint meta-test fails the build for an import that does not.
``headroom/__init__.py`` also calls it, which covers a host process that
imports litellm itself after importing Headroom; a host that imports
litellm *before* Headroom has made that fetch already and must set the
variable itself.
Forced and given back as described on :class:`_OfflineEnvPin`, so a
process that leaves offline mode before its first litellm import gets the
online pricing refresh again.
"""
_litellm_cost_map_pin()
def pin_crewai_telemetry_off() -> None:
"""Keep CrewAI's install tracking quiet under ``HEADROOM_OFFLINE``.
``import crewai`` starts a thread that requests a Scarf pixel from
api.scarf.sh unless ``CREWAI_DISABLE_TELEMETRY`` (or ``OTEL_SDK_DISABLED``
/ ``CREWAI_DISABLE_TRACKING``) is ``true``. Headroom imports CrewAI
whenever it is installed, through ``headroom.integrations``, so even a
LiteLLM callback import under the air-gap switch dialled out. As with
litellm, the variable is the only lever, so every ``crewai`` import in
``headroom/`` calls this first (the chokepoint meta-test enforces it), and
it is forced and given back as described on :class:`_OfflineEnvPin`.
"""
_crewai_telemetry_pin()
class OfflineEgressBlocked(BaseException):
"""Raised by :func:`guard_egress` when ``HEADROOM_OFFLINE`` is in force.
+2
View File
@@ -20,6 +20,7 @@ from datetime import datetime, timedelta
from pathlib import Path
from headroom import paths as _paths
from headroom.offline import pin_litellm_cost_map_local
from headroom.pricing.litellm_pricing import resolve_litellm_model
log = logging.getLogger(__name__)
@@ -74,6 +75,7 @@ _STAGE_TIMINGS_RE = re.compile(
# directly instead of maintaining our own pricing tables.
try:
pin_litellm_cost_map_local()
import litellm as _litellm
_LITELLM_AVAILABLE = True
+2
View File
@@ -63,6 +63,7 @@ from typing import Any
from headroom.cache_economics import CACHE_ECONOMICS
from headroom.log_safety import describe_exception, safe_id
from headroom.offline import pin_litellm_cost_map_local
from headroom.pricing.cache_ttl import CACHE_WRITE_MULTIPLIERS
logger = logging.getLogger(__name__)
@@ -338,6 +339,7 @@ def _litellm() -> Any | None:
deployments often run without it. Callers degrade to list pricing.
"""
try:
pin_litellm_cost_map_local()
import litellm
except Exception: # pragma: no cover - environment-dependent
return None
+6
View File
@@ -15,6 +15,7 @@ from dataclasses import dataclass
from datetime import datetime
from typing import Any
from headroom.offline import pin_litellm_cost_map_local
from headroom.pricing.deepseek_tiers import (
LEGACY_MODEL_IDS,
OFF_PEAK_RATES_PER_1M,
@@ -34,6 +35,11 @@ from headroom.pricing.litellm_model_resolution import (
# litellm added. The module itself is fully imported and cached in
# `sys.modules`; subsequent `import litellm` calls hit the cache and
# don't re-run the dotenv side effect.
#
# Under HEADROOM_OFFLINE, litellm must also stay on its bundled pricing table
# rather than fetch one from GitHub during that import.
pin_litellm_cost_map_local()
try:
import os as _os
+2
View File
@@ -25,6 +25,7 @@ from datetime import datetime
from typing import Any, cast
from headroom import paths as _paths
from headroom.offline import pin_litellm_cost_map_local
from headroom.pricing.deepseek_tiers import (
LEGACY_MODEL_IDS,
OFF_PEAK_RATES_PER_1M,
@@ -49,6 +50,7 @@ def _get_litellm_clients() -> tuple[Any | None, Any | None]:
return None, None
try:
pin_litellm_cost_map_local()
import litellm
litellm.suppress_debug_info = True
+2
View File
@@ -22,12 +22,14 @@ from datetime import date
from typing import Any
from headroom.log_safety import describe_exception, safe_id
from headroom.offline import pin_litellm_cost_map_local
from headroom.pricing.litellm_pricing import estimate_cost_from_tokens
from headroom.tokenizers import EstimatingTokenCounter
from .base import Provider, TokenCounter
try:
pin_litellm_cost_map_local()
import litellm
LITELLM_AVAILABLE = True
+13 -10
View File
@@ -208,18 +208,21 @@ def native_api_url_supported(*, environ: Mapping[str, str] | None = None) -> boo
if not os.path.isdir(root):
continue
for dirpath, _dirnames, filenames in os.walk(root):
if "app.js" not in filenames:
# Since Copilot CLI 1.0.93 app.js is a loader and the env read lives in cli-main.js.
names = [n for n in ("app.js", "cli-main.js") if n in filenames]
if not names:
continue
found_bundle = True
try:
with open(
os.path.join(dirpath, "app.js"), encoding="utf-8", errors="replace"
) as bundle:
while chunk := bundle.read(1 << 20):
if COPILOT_NATIVE_API_URL_ENV in chunk:
return True
except OSError:
continue
for name in names:
try:
with open(
os.path.join(dirpath, name), encoding="utf-8", errors="replace"
) as bundle:
while chunk := bundle.read(1 << 20):
if COPILOT_NATIVE_API_URL_ENV in chunk:
return True
except OSError:
continue
return False if found_bundle else None
+2
View File
@@ -26,6 +26,7 @@ from datetime import date
from typing import Any
from headroom.models.registry import ModelRegistry
from headroom.offline import pin_litellm_cost_map_local
from headroom.pricing.litellm_pricing import estimate_cost_from_tokens
from headroom.tokenizers import EstimatingTokenCounter
@@ -33,6 +34,7 @@ from .base import Provider, TokenCounter
# Check if litellm is available for pricing/context limit lookups
try:
pin_litellm_cost_map_local()
import litellm
LITELLM_AVAILABLE = True
+2
View File
@@ -25,6 +25,7 @@ import logging
import os
from typing import Any
from headroom.offline import pin_litellm_cost_map_local
from headroom.pricing.litellm_pricing import estimate_cost_from_tokens
from headroom.tokenizers import EstimatingTokenCounter
@@ -38,6 +39,7 @@ try:
# module-level suppression flags below can be set.
os.environ.setdefault("LITELLM_SUPPRESS_DEBUG_INFO", "True")
pin_litellm_cost_map_local()
import litellm
# Suppress litellm's startup banner ("Provider List: https://...") and
+2
View File
@@ -17,6 +17,7 @@ from typing import Any, cast
from headroom import paths as _paths
from headroom.log_safety import describe_exception, safe_id
from headroom.offline import pin_litellm_cost_map_local
from headroom.pricing.litellm_pricing import estimate_cost_from_tokens
from headroom.tokenizers.base import (
TokenCountCache,
@@ -49,6 +50,7 @@ def _get_litellm_module() -> Any | None:
return None
try:
pin_litellm_cost_map_local()
import litellm
except ImportError:
return None
File diff suppressed because it is too large Load Diff
+30 -5
View File
@@ -196,23 +196,48 @@ def _strip_jsonc_trailing_commas(text: str) -> str:
return "".join(output)
def _parse_json_loose(text: str) -> dict[str, Any]:
def _try_parse_json_loose(text: str) -> dict[str, Any] | None:
"""Parse JSON text and JSONC comments/trailing commas.
Standard JSON is tried first so URLs containing ``//`` remain untouched.
A leading UTF-8 BOM (written by some Windows editors) is ignored.
Returns ``None`` when the text is not a JSON object.
"""
text = text.lstrip("\ufeff")
try:
parsed = json.loads(text)
return parsed if isinstance(parsed, dict) else {}
return parsed if isinstance(parsed, dict) else None
except json.JSONDecodeError:
pass
cleaned = _strip_jsonc_comments(text)
cleaned = _strip_jsonc_trailing_commas(cleaned)
try:
parsed = json.loads(cleaned)
return parsed if isinstance(parsed, dict) else {}
return parsed if isinstance(parsed, dict) else None
except json.JSONDecodeError:
return None
def _parse_json_loose(text: str) -> dict[str, Any]:
"""Like :func:`_try_parse_json_loose`, but returns ``{}`` on failure."""
return _try_parse_json_loose(text) or {}
def load_user_opencode_config(content: str, config_file: Path) -> dict[str, Any]:
"""Parse the user's OpenCode config, refusing to treat unparseable text as empty.
Callers rewrite the whole file from the result, so ``{}`` for a non-empty
file we could not read would delete every user setting.
"""
data = _try_parse_json_loose(content)
if data is None:
if content.lstrip("\ufeff").strip():
raise click.ClickException(
f"could not parse OpenCode config at {config_file}; "
"leaving it unchanged. Fix the JSON/JSONC syntax and retry."
)
return {}
return data
def _inject_key_into_json(data: dict[str, Any], key: str, value: Any) -> dict[str, Any]:
@@ -248,7 +273,7 @@ def inject_opencode_provider_config(port: int, *, keep_user_entries: bool = Fals
if config_file.exists():
content = fsutil.read_text(config_file)
data = _parse_json_loose(content)
data = load_user_opencode_config(content, config_file)
else:
content = ""
data = {}
@@ -256,7 +281,7 @@ def inject_opencode_provider_config(port: int, *, keep_user_entries: bool = Fals
# Strip any prior Headroom-managed blocks before re-injecting.
if _PROVIDER_MARKER_START in content or _MCP_MARKER_START in content:
content = strip_opencode_headroom_blocks(content)
data = _parse_json_loose(content)
data = load_user_opencode_config(content, config_file)
# Merge provider into the JSON data structure.
entry = headroom_provider_entry(port)
@@ -50,6 +50,19 @@ function withShimEnv(env, proxyUrl2, excludeHosts) {
}
return nextEnv;
}
var PROCESS_ENV_KEYS = [PROXY_ENV, EXCLUDE_HOSTS_ENV, "NODE_OPTIONS"];
function snapshotProcessEnv() {
return Object.fromEntries(PROCESS_ENV_KEYS.map((key) => [key, process.env[key]]));
}
function restoreProcessEnv(saved) {
for (const key of PROCESS_ENV_KEYS) {
if (saved[key] === void 0) {
delete process.env[key];
} else {
process.env[key] = saved[key];
}
}
}
function installProcessEnv(proxyUrl2, excludeHosts) {
process.env[PROXY_ENV] = proxyUrl2;
withExcludeHostsEnv(process.env, excludeHosts);
@@ -379,7 +392,8 @@ function installHeadroomTransport(options) {
originalChildSpawn: childProcess.spawn,
originalChildExec: childProcess.exec,
originalChildExecFile: childProcess.execFile,
originalChildFork: childProcess.fork
originalChildFork: childProcess.fork,
originalEnv: snapshotProcessEnv()
};
setState(state);
installProcessEnv(options.proxyUrl, excludeHosts);
@@ -423,6 +437,7 @@ function uninstallHeadroomTransport() {
childProcess.exec = state.originalChildExec;
childProcess.execFile = state.originalChildExecFile;
childProcess.fork = state.originalChildFork;
restoreProcessEnv(state.originalEnv);
syncBuiltinESMExports();
setState(void 0);
}
+2 -1
View File
@@ -13,6 +13,7 @@ from headroom.install.paths import opencode_config_path
from .config import (
_inject_key_into_json,
_parse_json_loose,
load_user_opencode_config,
migrate_legacy_opencode_jsonc_backup,
snapshot_opencode_config_if_unwrapped,
strip_opencode_headroom_blocks,
@@ -40,7 +41,7 @@ def apply_provider_scope(manifest: DeploymentManifest) -> ManagedMutation | None
if config_file.exists():
content = fsutil.read_text(config_file)
data = _parse_json_loose(content)
data = load_user_opencode_config(content, config_file)
else:
data = {}
+31 -4
View File
@@ -6,6 +6,7 @@ import json
import logging
from dataclasses import dataclass
from pathlib import Path
from urllib.parse import urlsplit
from headroom.install.paths import zcode_config_dir
from headroom.providers.claude import proxy_base_url as _claude_proxy_base_url
@@ -40,11 +41,30 @@ def build_proxy_targets(port: int) -> ZCodeProxyTargets:
)
def detect_upstream(config_path: Path | None = None) -> ZCodeUpstream:
def _points_at_proxy(base_url: str, proxy_port: int | None) -> bool:
"""True when *base_url* names the Headroom proxy: its advertised host and port.
Policy: the proxy is advertised on ``127.0.0.1`` (see ``build_proxy_targets``)
and ``localhost`` is treated as that same host. ``[::1]`` is a different
socket, so an IPv6 provider on the same port is a real upstream, not the proxy.
"""
if proxy_port is None:
return False
try:
parts = urlsplit(base_url)
return parts.hostname in ("127.0.0.1", "localhost") and parts.port == proxy_port
except ValueError:
return False
def detect_upstream(
config_path: Path | None = None, proxy_port: int | None = None
) -> ZCodeUpstream:
"""Read ZCode config.json and find the enabled provider's upstream URL.
Resolution order:
1. First provider with ``enabled=True`` and a non-empty ``baseURL``.
1. First provider with ``enabled=True`` and a non-empty ``baseURL`` that
does not point at the Headroom proxy itself (``proxy_port``).
2. Fallback: Z.ai Anthropic endpoint.
Parameters
@@ -52,6 +72,10 @@ def detect_upstream(config_path: Path | None = None) -> ZCodeUpstream:
config_path:
Override for the config file path. When *None* the default
``~/.zcode/v2/config.json`` is used.
proxy_port:
Port of the local Headroom proxy. A provider whose ``baseURL`` is a
loopback URL on this port is skipped, because ZCode users are told to
point a provider at the proxy and using it as the upstream would loop.
"""
if config_path is None:
config_path = zcode_config_dir() / "v2" / "config.json"
@@ -83,8 +107,11 @@ def detect_upstream(config_path: Path | None = None) -> ZCodeUpstream:
opts = provider.get("options", {})
if not isinstance(opts, dict):
continue
base_url = opts.get("baseURL", "").strip()
if not base_url:
base_url = opts.get("baseURL")
if not isinstance(base_url, str):
continue
base_url = base_url.strip()
if not base_url or _points_at_proxy(base_url, proxy_port):
continue
kind = provider.get("kind", "anthropic")
name = provider.get("name", "ZCode provider")
+6 -2
View File
@@ -75,6 +75,10 @@ def savings_conversation_key(body: Any, *, session_id: str | None = None) -> str
top-level ``conversation_id``/``session_id``/``thread_id``, one of
those inside ``metadata``/``client_metadata``, or a transport-scoped
``session_id`` the caller vouches for (a WebSocket, a session header).
A ``thread_id`` wins over a ``session_id`` beside it: Codex sends both,
and its ``session_id`` is the root thread's on every request of the
session, so a guardian or subagent request would otherwise reset the
root's running total and make its next turn re-book its history.
Two things are deliberately NOT accepted. The holdout key's fallbacks
(the instructions prefix, the literal ``responses``): two independent
conversations with the same instructions would share a running total
@@ -101,7 +105,7 @@ def savings_conversation_key(body: Any, *, session_id: str | None = None) -> str
return None
identity = ""
for key in ("conversation_id", "session_id", "thread_id"):
for key in ("conversation_id", "thread_id", "session_id"):
value = _explicit_id(body.get(key))
if value:
identity = f"{key}:{value}"
@@ -114,8 +118,8 @@ def savings_conversation_key(body: Any, *, session_id: str | None = None) -> str
for key in (
"conversation_id",
"conversation_key",
"session_id",
"thread_id",
"session_id",
"codex_session_id",
):
value = _explicit_id(container.get(key))
+137 -43
View File
@@ -17,6 +17,7 @@ from typing import TYPE_CHECKING, Any, NamedTuple
from headroom.cache_economics import CACHE_ECONOMICS as _CACHE_ECONOMICS
from headroom.log_safety import WarnOnce, describe_exception, safe_id
from headroom.offline import pin_litellm_cost_map_local
from headroom.proxy.budget_basis_policy import (
BUDGET_BASIS_BLOCK,
BUDGET_BASIS_IGNORE,
@@ -27,6 +28,11 @@ from headroom.proxy.budget_basis_policy import (
resolve_estimated_basis_policy,
)
from headroom.proxy.modes import PROXY_MODE_CACHE
from headroom.proxy.persistent_metrics import (
MAX_TRACKED_MODELS,
OTHER_MODEL,
bounded_model_key,
)
if TYPE_CHECKING:
from headroom.proxy.prometheus_metrics import PrometheusMetrics
@@ -45,6 +51,7 @@ def _get_litellm_module() -> Any | None:
return litellm
try:
pin_litellm_cost_map_local()
import litellm as imported_litellm
except ImportError:
return None
@@ -89,7 +96,11 @@ _warned_estimated_basis_models: set[str] = set()
def _warn_estimated_basis_once(model: str) -> None:
"""Warn the first time ``model`` books a cost against Headroom's estimate."""
if model in _warned_estimated_basis_models:
# Process-wide cap: the set outlives any one tracker (reset_runtime), so the
# per-tracker key bound alone does not limit it.
if model in _warned_estimated_basis_models or (
len(_warned_estimated_basis_models) >= MAX_TRACKED_MODELS
):
return
_warned_estimated_basis_models.add(model)
logger.warning(
@@ -873,7 +884,9 @@ class CostTracker:
# the reporting history, while this deque evicts entries as soon as the
# configured hourly/daily/monthly window advances. Each entry is added
# and removed once, making expiry amortized O(1) instead of rescanning
# up to MAX_COST_ENTRIES before every request (#3367).
# up to MAX_COST_ENTRIES before every request (#3367). It is bounded by
# the period, not by MAX_COST_ENTRIES: evicting an in-period entry would
# drop spend that still counts against the budget (#4416).
self._budget_costs: deque[CostEntry] = deque()
self._budget_measured_usd = 0.0
self._budget_estimated_usd = 0.0
@@ -930,6 +943,14 @@ class CostTracker:
self._api_cache_write_5m_by_model: dict[str, int] = {}
self._api_cache_write_1h_by_model: dict[str, int] = {}
self._api_uncached_by_model: dict[str, int] = {}
# Priced dollars of requests whose model label was folded into ``other``:
# the read-time pass prices by label, and ``other`` has no price, so
# those dollars are priced once here, at record time.
self._folded_input_usd = 0.0
self._folded_output_usd = 0.0
self._folded_savings_usd = 0.0
self._folded_cache_aware_savings_usd = 0.0
self._folded_tool_savings_usd = 0.0
def reset_runtime(self) -> None:
"""Reset in-memory cost/token counters for local test/debug use."""
@@ -958,6 +979,11 @@ class CostTracker:
self._api_cache_write_5m_by_model.clear()
self._api_cache_write_1h_by_model.clear()
self._api_uncached_by_model.clear()
self._folded_input_usd = 0.0
self._folded_output_usd = 0.0
self._folded_savings_usd = 0.0
self._folded_cache_aware_savings_usd = 0.0
self._folded_tool_savings_usd = 0.0
def estimate_cost(
self,
@@ -1085,10 +1111,9 @@ class CostTracker:
model,
)
tokens_saved = 0
self._tokens_saved_by_model[model] = (
self._tokens_saved_by_model.get(model, 0) + tokens_saved
)
self._tool_saved_by_model[model] = self._tool_saved_by_model.get(model, 0) + max(
key = bounded_model_key(model, self._requests_by_model)
self._tokens_saved_by_model[key] = self._tokens_saved_by_model.get(key, 0) + tokens_saved
self._tool_saved_by_model[key] = self._tool_saved_by_model.get(key, 0) + max(
0, tool_schema_saved
)
# A request the provider reported no cache data for (or whose write
@@ -1126,7 +1151,7 @@ class CostTracker:
uncached_tokens=uncached_tokens,
region="live_zone",
)
wkey = (model, long_context)
wkey = (key, long_context)
self._saved_write_5m_by_tier[wkey] = self._saved_write_5m_by_tier.get(wkey, 0.0) + c_w5m
self._saved_write_1h_by_tier[wkey] = self._saved_write_1h_by_tier.get(wkey, 0.0) + c_w1h
self._saved_list_by_tier[wkey] = self._saved_list_by_tier.get(wkey, 0.0) + c_list
@@ -1145,46 +1170,54 @@ class CostTracker:
uncached_tokens=uncached_tokens,
region="prefix",
)
self._tool_saved_read_by_model[model] = (
self._tool_saved_read_by_model.get(model, 0.0) + read_part
self._tool_saved_read_by_model[key] = (
self._tool_saved_read_by_model.get(key, 0.0) + read_part
)
self._tool_saved_write_5m_by_model[model] = (
self._tool_saved_write_5m_by_model.get(model, 0.0) + w5m_part
self._tool_saved_write_5m_by_model[key] = (
self._tool_saved_write_5m_by_model.get(key, 0.0) + w5m_part
)
self._tool_saved_write_1h_by_model[model] = (
self._tool_saved_write_1h_by_model.get(model, 0.0) + w1h_part
self._tool_saved_write_1h_by_model[key] = (
self._tool_saved_write_1h_by_model.get(key, 0.0) + w1h_part
)
self._tool_saved_list_by_model[model] = (
self._tool_saved_list_by_model.get(model, 0.0) + list_part
self._tool_saved_list_by_model[key] = (
self._tool_saved_list_by_model.get(key, 0.0) + list_part
)
self._tokens_sent_by_model[model] = self._tokens_sent_by_model.get(model, 0) + tokens_sent
self._tokens_sent_by_model[key] = self._tokens_sent_by_model.get(key, 0) + tokens_sent
if provider_reported:
self._provider_tokens_sent_by_model[model] = (
self._provider_tokens_sent_by_model.get(model, 0) + tokens_sent
self._provider_tokens_sent_by_model[key] = (
self._provider_tokens_sent_by_model.get(key, 0) + tokens_sent
)
self._provider_requests_by_model[model] = (
self._provider_requests_by_model.get(model, 0) + 1
)
okey = (model, long_context)
self._provider_requests_by_model[key] = self._provider_requests_by_model.get(key, 0) + 1
okey = (key, long_context)
self._output_tokens_by_tier[okey] = self._output_tokens_by_tier.get(okey, 0) + max(
0, output_tokens
)
self._requests_by_model[model] = self._requests_by_model.get(model, 0) + 1
self._api_cache_read_by_model[model] = (
self._api_cache_read_by_model.get(model, 0) + cache_read_tokens
self._requests_by_model[key] = self._requests_by_model.get(key, 0) + 1
self._api_cache_read_by_model[key] = (
self._api_cache_read_by_model.get(key, 0) + cache_read_tokens
)
self._api_cache_write_by_model[model] = (
self._api_cache_write_by_model.get(model, 0) + write_eff
self._api_cache_write_by_model[key] = self._api_cache_write_by_model.get(key, 0) + write_eff
self._api_cache_write_5m_by_model[key] = (
self._api_cache_write_5m_by_model.get(key, 0) + write_5m_eff
)
self._api_cache_write_5m_by_model[model] = (
self._api_cache_write_5m_by_model.get(model, 0) + write_5m_eff
)
self._api_cache_write_1h_by_model[model] = (
self._api_cache_write_1h_by_model.get(model, 0) + write_1h_eff
)
self._api_uncached_by_model[model] = (
self._api_uncached_by_model.get(model, 0) + uncached_tokens
self._api_cache_write_1h_by_model[key] = (
self._api_cache_write_1h_by_model.get(key, 0) + write_1h_eff
)
self._api_uncached_by_model[key] = self._api_uncached_by_model.get(key, 0) + uncached_tokens
if key == OTHER_MODEL and model != OTHER_MODEL:
self._book_folded_usd(
model,
long_context=long_context,
tokens_saved=tokens_saved,
tokens_sent=tokens_sent,
cache_read=cache_read_tokens,
write=write_eff,
write_5m=write_5m_eff,
write_1h=write_1h_eff,
uncached=uncached_tokens,
output=output_tokens,
tool_schema_saved=tool_schema_saved,
)
# Populate _costs so check_budget() has real data to enforce against.
# When the call site had no API usage breakdown (all cache/uncached
@@ -1219,7 +1252,7 @@ class CostTracker:
if not (uncached_tokens or cache_read_tokens or cache_write_tokens):
input_tokens = tokens_sent
basis = COST_BASIS_ESTIMATED
_warn_estimated_basis_once(model)
_warn_estimated_basis_once(key)
cost = self.estimate_cost(
model=model,
input_tokens=input_tokens,
@@ -1266,8 +1299,6 @@ class CostTracker:
def _record_budget_cost(self, entry: CostEntry) -> None:
"""Add one entry to the current-period aggregate in amortized O(1)."""
self._refresh_budget_window(entry.timestamp)
if len(self._budget_costs) >= self.MAX_COST_ENTRIES:
self._subtract_budget_cost(self._budget_costs.popleft())
self._budget_costs.append(entry)
if entry.basis == COST_BASIS_ESTIMATED:
self._budget_estimated_usd += entry.cost_usd
@@ -1426,6 +1457,68 @@ class CostTracker:
w5m = total - w1h
return w5m * w5m_price + w1h * w1h_price
def _book_folded_usd(
self,
model: str,
*,
long_context: bool,
tokens_saved: int,
tokens_sent: int,
cache_read: int,
write: int,
write_5m: int,
write_1h: int,
uncached: int,
output: int,
tool_schema_saved: int,
) -> None:
"""Price one request whose label was folded, with the read-time formulas."""
prices = self._get_cache_prices(model)
if prices:
cr_price, w5_price, w1h_price, uncached_price = prices
if cache_read + write + uncached > 0:
w1h = min(max(0, write_1h), write)
self._folded_input_usd += (
cache_read * cr_price
+ (write - w1h) * w5_price
+ w1h * w1h_price
+ uncached * uncached_price
)
else:
self._folded_input_usd += tokens_sent * uncached_price
self._folded_savings_usd += tokens_saved * uncached_price
out_price = self._get_output_price(model, long_context=long_context)
if out_price:
self._folded_output_usd += max(0, output) * out_price
# Cache-aware compression and tool-schema savings: same buckets and
# same price lookups as the record-time maps and stats() use.
if tokens_saved > 0:
_r, c5, c1, cl = _bucket_by_cache_mix(
tokens_saved,
cache_read_tokens=0,
cache_write_tokens=write,
cache_write_5m_tokens=write_5m,
cache_write_1h_tokens=write_1h,
uncached_tokens=uncached,
region="live_zone",
)
ca = self._get_cache_prices(model, long_context=long_context, for_billing=False)
if ca:
self._folded_cache_aware_savings_usd += c5 * ca[1] + c1 * ca[2] + cl * ca[3]
if tool_schema_saved > 0:
rd, t5, t1, tl = _bucket_by_cache_mix(
tool_schema_saved,
cache_read_tokens=cache_read,
cache_write_tokens=write,
cache_write_5m_tokens=write_5m,
cache_write_1h_tokens=write_1h,
uncached_tokens=uncached,
region="prefix",
)
tp = self._get_cache_prices(model, for_billing=False)
if tp:
self._folded_tool_savings_usd += rd * tp[0] + t5 * tp[1] + t1 * tp[2] + tl * tp[3]
def _get_cache_prices(
self, model: str, *, long_context: bool = False, for_billing: bool = True
) -> tuple[float, float, float, float] | None:
@@ -1500,7 +1593,7 @@ class CostTracker:
)
else:
cost_with_headroom += sent * uncached_price
return total_input_tokens, round(cost_with_headroom, 4)
return total_input_tokens, round(cost_with_headroom + self._folded_input_usd, 4)
def stats(self) -> dict:
"""Get token statistics per model."""
@@ -1577,12 +1670,13 @@ class CostTracker:
cost_with_headroom += model_cost
total_billed_input_tokens += billed_tokens
cost_with_headroom += self._folded_input_usd
# Compression savings: price saved tokens at the model's list input price.
# This is simple, monotonic, and transparent — each saved token is valued
# at the published $/token rate for its model. Not affected by cache mix.
# Budget enforcement reads this figure, so it stays as-is; the
# cache-aware valuation below is reported alongside it.
savings_usd = 0.0
savings_usd = self._folded_savings_usd
for model in self._tokens_saved_by_model:
if model.startswith("passthrough:"):
continue
@@ -1597,7 +1691,7 @@ class CostTracker:
# Completion spend. The input-only figure above is what a budget and the
# per-model table want; a card that says "$X spent" has to include the
# tokens the model emitted, or the spend it shows isn't the bill.
output_cost_usd = 0.0
output_cost_usd = self._folded_output_usd
for (model, long_context), out_tokens in self._output_tokens_by_tier.items():
price = self._get_output_price(model, long_context=long_context)
if price:
@@ -1610,7 +1704,7 @@ class CostTracker:
# pricing (``savings_usd``) ignores both. Reported separately so budget
# enforcement keeps its monotonic list-priced basis; the dashboard's
# cost card prefers this one.
cache_aware_savings_usd = 0.0
cache_aware_savings_usd = self._folded_cache_aware_savings_usd
for key in (
set(self._saved_write_5m_by_tier)
| set(self._saved_write_1h_by_tier)
@@ -1645,7 +1739,7 @@ class CostTracker:
# multiplier. Reported as its OWN key rather than widening
# ``savings_usd``: that figure feeds budget enforcement, and the
# session summary widens the cost card from this key instead.
tool_savings_usd = 0.0
tool_savings_usd = self._folded_tool_savings_usd
tool_models = (
set(self._tool_saved_read_by_model)
| set(self._tool_saved_write_5m_by_model)
+11
View File
@@ -257,6 +257,15 @@ class NormalizedUsage:
return True
return self.cache_read is not None and self.cache_write is not None
def _merged_includes_cache(self, other: NormalizedUsage) -> bool:
"""Accounting dialect across rounds. A usage block without cache fields
carries no dialect (``normalize_usage`` defaults it to inclusive, which
is wrong for a cacheless Anthropic round), so the round that reported
cache fields decides; the latest such round wins."""
if other.has_cache_signal or not self.has_cache_signal:
return other.input_includes_cache
return self.input_includes_cache
def merged_with(self, other: NormalizedUsage) -> NormalizedUsage:
"""Sum the billed counters across re-drive rounds; cache fields come
from the latest round that carried them (the last provider call is the
@@ -272,6 +281,7 @@ class NormalizedUsage:
output_tokens=_sum(self.output_tokens, other.output_tokens),
cache_read=other.cache_read if other.has_cache_signal else self.cache_read,
cache_write=other.cache_write if other.has_cache_signal else self.cache_write,
input_includes_cache=self._merged_includes_cache(other),
)
def summed_with(self, other: NormalizedUsage) -> NormalizedUsage:
@@ -290,6 +300,7 @@ class NormalizedUsage:
output_tokens=_sum(self.output_tokens, other.output_tokens),
cache_read=_sum(self.cache_read, other.cache_read),
cache_write=_sum(self.cache_write, other.cache_write),
input_includes_cache=self._merged_includes_cache(other),
)
def as_anthropic(self) -> dict[str, int]:
+39 -10
View File
@@ -121,7 +121,7 @@ def _thinking_tokens_for(payload: object) -> ThinkingTokens:
Anthropic reports no thinking count in ``usage``, so the count is derived
from the response's own thinking blocks and marked inferred. Without the
split, reasoning-effort routing and verbosity steering move the same
split, thinking-budget changes and verbosity steering move the same
counter and neither can be attributed.
Never raises: token accounting is bookkeeping, and a failure here must
@@ -2742,7 +2742,9 @@ class AnthropicHandlerMixin:
# they can drive tool injection (issue #2836).
ccr_present_hashes = injector.verify_ownership()
if inject_system_instructions and injector.has_compressed_content:
optimized_messages = injector.inject_into_system_message(optimized_messages)
optimized_messages = injector.inject_into_system_message(
optimized_messages, tools=tools
)
# Sticky-on tool registration (PR-B7): always inject the
# retrieval tool once a session has done CCR, regardless
@@ -3028,7 +3030,7 @@ class AnthropicHandlerMixin:
query=user_query,
)
except Exception as e:
logger.warning(f"[{request_id}] Memory: Context injection failed: {e}")
logger.warning(f"[{request_id}] Memory: Context injection failed: {e!r}")
# Inject memory tools — PR-A7 (P0-6) routes through
# `apply_session_sticky_memory_tools` so tool list bytes
@@ -3648,8 +3650,7 @@ class AnthropicHandlerMixin:
logger.debug("consistency token re-count skipped", exc_info=True)
# Output shaping (opt-in via HEADROOM_OUTPUT_SHAPER): verbosity
# steering appended to the system-prompt tail + effort routing on
# mechanical tool_result continuations. Runs after every other
# steering appended to the system-prompt tail. Runs after every other
# body mutation so the turn classifier sees the final messages,
# and respects the same bypass header as compression.
if not _bypass:
@@ -4989,6 +4990,11 @@ class AnthropicHandlerMixin:
url=url,
request_id=request_id,
)
if not 200 <= continuation_response.status_code < 300:
raise RuntimeError(
"turn hook re-drive returned non-success status "
f"{continuation_response.status_code}"
)
continuation_json = continuation_response.json()
_hook_usage.record(continuation_json)
return continuation_json
@@ -5766,7 +5772,11 @@ class AnthropicHandlerMixin:
return capability_error
from headroom.ccr import CCRToolInjector
from headroom.proxy.helpers import MAX_REQUEST_BODY_SIZE, _read_request_json
from headroom.proxy.helpers import (
MAX_REQUEST_BODY_SIZE,
_headroom_bypass_enabled,
read_request_json_with_bytes,
)
from headroom.proxy.modes import is_cache_mode
from headroom.utils import extract_user_query
@@ -5789,7 +5799,7 @@ class AnthropicHandlerMixin:
# Parse request
try:
body = await _read_request_json(request)
body, original_body_bytes = await read_request_json_with_bytes(request)
except (json.JSONDecodeError, ValueError) as e:
return JSONResponse(
status_code=400,
@@ -5843,6 +5853,20 @@ class AnthropicHandlerMixin:
request_id=request_id,
)
# Same two gates the OpenAI and Google batch paths apply: the client's
# bypass/passthrough header, and the commercial gate (fails open when no
# reporter is configured or no license info exists yet).
_bypass = _headroom_bypass_enabled(request.headers)
license_ok = (
self.usage_reporter.should_compress if self.usage_reporter is not None else True
)
if _bypass:
logger.info(f"[{request_id}] Compression skipped: reason=bypass_header")
tags["passthrough_reason"] = "bypass_header"
elif not license_ok:
logger.info(f"[{request_id}] Compression skipped: reason=license_denied")
tags["passthrough_reason"] = "license_denied"
# Track compression stats across all batch requests
total_original_tokens = 0
total_optimized_tokens = 0
@@ -5870,6 +5894,10 @@ class AnthropicHandlerMixin:
model, original_messages, params.get("system")
)
if _bypass or not license_ok:
compressed_requests.append(batch_req)
continue
if not messages or not self.config.optimize:
# No messages or optimization disabled - pass through unchanged
compressed_requests.append(
@@ -6019,14 +6047,15 @@ class AnthropicHandlerMixin:
url = f"{self.ANTHROPIC_API_URL}/v1/messages/batches"
try:
# Body is always mutated for batch (compressed requests).
# Mutated unless bypassed: bypass forwards the client's exact bytes.
response = await self._retry_request(
"POST",
url,
headers,
body,
body_mutated=True,
mutation_reasons=["batch_compression"],
original_body_bytes=original_body_bytes if _bypass else None,
body_mutated=not _bypass,
mutation_reasons=[] if _bypass else ["batch_compression"],
request_id=request_id,
forwarder_name="anthropic_batch",
path_for_log="/v1/messages/batches",
+1 -1
View File
@@ -70,7 +70,7 @@ class BedrockHandlerMixin:
URL path (may contain ``.``, ``:`` and ``/``).
stream: ``True`` for ``invoke-with-response-stream``.
"""
from fastapi.responses import JSONResponse
from fastapi.responses import JSONResponse, Response
from headroom.proxy.auth_mode import classify_client
from headroom.proxy.helpers import (
+14 -2
View File
@@ -156,6 +156,10 @@ class GeminiHandlerMixin:
- thought / thoughtSignature: thinking parts, which must round-trip intact
- non-string text, which the text round trip cannot rebuild
The REST API accepts both the camelCase JSON names and the snake_case
proto field names (``inline_data``, ``function_call``, ...), so both
spellings are checked.
Args:
content: A single Gemini content entry with 'parts' list.
@@ -174,6 +178,13 @@ class GeminiHandlerMixin:
"codeExecutionResult",
"thought",
"thoughtSignature",
"inline_data",
"file_data",
"function_call",
"function_response",
"executable_code",
"code_execution_result",
"thought_signature",
)
):
return True
@@ -269,9 +280,10 @@ class GeminiHandlerMixin:
if include_function_responses:
for part in parts:
if "functionResponse" not in part:
function_response = part.get("functionResponse", part.get("function_response"))
if function_response is None:
continue
payload = self._function_response_text(part["functionResponse"])
payload = self._function_response_text(function_response)
if payload:
messages.append({"role": "tool", "content": payload})
+263 -28
View File
@@ -18,7 +18,7 @@ import ssl
import threading
import time
import uuid
from collections import OrderedDict
from collections import Counter, OrderedDict
from concurrent.futures import ThreadPoolExecutor, as_completed
from dataclasses import replace
from datetime import datetime
@@ -113,6 +113,7 @@ from headroom.proxy.buffered_ccr_response import (
from headroom.proxy.compression_decision import CompressionDecision
from headroom.proxy.cost import header_safe_transforms
from headroom.proxy.handlers._debug_dump import _debug_dump_mode, _redact_debug_value
from headroom.proxy.handlers.streaming import _stream_outcome_status
from headroom.proxy.image_isolation import run_image_compression_isolated
from headroom.proxy.outcome import RequestOutcome
from headroom.proxy.output_shaper import shaper_enabled_for, steering_allowed_for
@@ -742,6 +743,35 @@ def _openai_responses_result_with_cache_hit(result: Any) -> Any:
return replace(result, router_result=replace(router_result, cache_hit=True))
def _openai_responses_cached_ccr_markers_live(result: Any) -> bool:
"""Return whether CCR markers generated for a cached unit are still retrievable.
The unit-result cache outlives CCR entries: it has no TTL, while a CCR entry
expires after the CCR TTL and is written only when the unit is compressed.
Treat an expired generated entry as a miss so compression stores it again.
Inherited markers cannot be restored by recompressing the unit. A store that
cannot be consulted keeps the previous behaviour (reuse).
"""
compressed = getattr(result, "compressed", None)
if not isinstance(compressed, str):
return True
hashes = Counter(match.group(1).lower() for match in _CCR_HASH_RE.finditer(compressed))
original = getattr(result, "original", "")
if isinstance(original, str):
# Inherited markers are preserved byte-for-byte; extra occurrences are generated.
hashes -= Counter(match.group(1).lower() for match in _CCR_HASH_RE.finditer(original))
if not hashes:
return True
try:
from headroom.cache.compression_store import get_compression_store
store = get_compression_store()
return all(store.exists(hash_key) for hash_key in hashes)
except Exception:
logger.debug("CCR liveness check for a cached Responses unit failed")
return True
def _codex_ws_text_shape(text: str) -> str:
stripped = text.strip()
if not stripped:
@@ -831,7 +861,7 @@ def _shape_openai_responses_payload(
The Responses counterpart of the Anthropic handler's shaping block:
conversation-stable holdout assignment, stratum labelling for the
output-savings ledger, then verbosity steering on the ``instructions``
tail and ``reasoning.effort`` routing on mechanical continuations.
tail.
Returns ``(labels, mutated)``. ``labels`` are carried on the transforms
channel for both arms (the control arm's stratum label is what feeds the
@@ -1099,6 +1129,109 @@ def _ensure_chatgpt_responses_store_false(
return False
def _web_search_history_drop_enabled() -> bool:
from headroom.proxy import runtime_env
return (runtime_env.getenv("HEADROOM_WEB_SEARCH_HISTORY", "1") or "1").strip().lower() not in (
"0",
"false",
"no",
"off",
)
def _drop_undeclared_web_search_calls(
payload: dict[str, Any],
*,
request_id: str | None = None,
) -> int:
"""Drop hosted ``web_search_call`` items from a request that cannot search.
Workaround for an OpenAI backend behaviour, not a Headroom bug. Codex on a
custom model provider (how Headroom wraps it) compacts locally: it resends
the whole history to ``/v1/responses`` with ``tools: []``. When that
history holds a hosted ``web_search_call`` item, the ChatGPT backend
answers 200 and then the in-band error "response protection is
unavailable". Codex ignores in-band ``error`` events, reports "stream
closed before response.completed", retries, and runs the same compaction
before every later prompt, so the session never answers again. The same
body completes with the ``web_search_call`` items removed, or with a
web_search tool declared.
Only the search action (its query or URL) leaves the history; the results
were never in it, and the model's answer that followed is a separate
``message`` item that stays. A tool counts as declared in top-level
``tools`` or in a Codex ``additional_tools`` input item (Codex >= 0.149
sends tools that way), under any ``web_search*`` type spelling. A request
continuing ``previous_response_id`` is left alone: its declarations may
live server-side.
Mutates *payload* in place and returns the number of items dropped
(0 = untouched). Callers skip it for a bypass request
(``x-headroom-bypass: true``), which asked for its bytes untouched.
Disable with ``HEADROOM_WEB_SEARCH_HISTORY=0`` (a registered runtime-env
knob, so ``headroom wrap`` also pushes it to a reused proxy). Remove once
the backend accepts such a body.
"""
items = payload.get("input")
if not isinstance(items, list) or payload.get("previous_response_id"):
return 0
if not any(isinstance(item, dict) and item.get("type") == "web_search_call" for item in items):
return 0
tools = payload.get("tools")
declared = list(tools) if isinstance(tools, list) else []
for item in items:
if isinstance(item, dict) and item.get("type") == "additional_tools":
declared.extend(item["tools"] if isinstance(item.get("tools"), list) else [])
if any(
isinstance(tool, dict) and str(tool.get("type") or "").startswith("web_search")
for tool in declared
):
return 0
if not _web_search_history_drop_enabled():
return 0
kept = [
item
for item in items
if not (isinstance(item, dict) and item.get("type") == "web_search_call")
]
payload["input"] = kept
dropped = len(items) - len(kept)
logger.info(
"event=web_search_history request_id=%s dropped=%d reason=no_web_search_tool",
request_id or "-",
dropped,
)
return dropped
def _drop_undeclared_web_search_calls_from_frame(
raw_msg: str,
*,
request_id: str | None = None,
) -> str:
"""Apply :func:`_drop_undeclared_web_search_calls` to a WS ``response.create`` frame.
Returns *raw_msg* unchanged (same object) unless items were dropped. The
substring prescreen keeps every frame without a ``web_search_call`` from
paying a parse. JSON can spell the type with ``\\uXXXX`` escapes
(``"web_search\\u005fcall"``), and a letter or underscore can only be
escaped that way, so a frame holding any ``\\u`` is parsed too.
"""
if '"web_search_call"' not in raw_msg and "\\u" not in raw_msg:
return raw_msg
try:
frame = json.loads(raw_msg)
except (json.JSONDecodeError, TypeError, ValueError):
return raw_msg
if not isinstance(frame, dict) or frame.get("type") != "response.create":
return raw_msg
payload = frame["response"] if isinstance(frame.get("response"), dict) else frame
if not _drop_undeclared_web_search_calls(payload, request_id=request_id):
return raw_msg
return json.dumps(frame)
_RESPONSES_OUTPUT_ITEM_TYPES = frozenset(
{
"custom_tool_call_output",
@@ -1811,6 +1944,11 @@ class OpenAIHandlerMixin:
if result is None:
return None
cache.move_to_end(key)
if not _openai_responses_cached_ccr_markers_live(result):
with lock:
if cache.get(key) is result:
del cache[key]
return None
return _openai_responses_result_with_cache_hit(result)
def _store_openai_responses_cached_unit(self, key: str, result: Any) -> None:
@@ -4107,7 +4245,9 @@ class OpenAIHandlerMixin:
and not stream
and injector.has_compressed_content
):
optimized_messages = injector.inject_into_system_message(optimized_messages)
optimized_messages = injector.inject_into_system_message(
optimized_messages, tools=tools
)
if can_inject_ccr_tool:
from headroom.proxy.helpers import (
@@ -4254,25 +4394,29 @@ class OpenAIHandlerMixin:
apply_session_sticky_memory_tools as _apply_sticky_mem_tools,
)
memory_tool_defs = (
self.memory_handler.compute_memory_tool_definitions("openai")
if self.memory_handler.config.inject_tools
else []
)
tools, mem_tools_injected = _apply_sticky_mem_tools(
provider="openai",
session_id=openai_session_id,
request_id=request_id,
existing_tools=tools,
memory_tools_to_inject=memory_tool_defs,
inject_this_turn=bool(self.memory_handler.config.inject_tools),
client_declared_tools=bool(_original_tools),
)
if mem_tools_injected:
memory_tools_injected = True
logger.info(f"[{request_id}] Memory: Injected memory tools (openai)")
# Only the Anthropic stream path executes memory tool calls
# (streaming.py `memory_enabled`). Skip the whole call on a
# streamed turn: the sticky replay would re-add golden tools.
if not stream:
memory_tool_defs = (
self.memory_handler.compute_memory_tool_definitions("openai")
if self.memory_handler.config.inject_tools
else []
)
tools, mem_tools_injected = _apply_sticky_mem_tools(
provider="openai",
session_id=openai_session_id,
request_id=request_id,
existing_tools=tools,
memory_tools_to_inject=memory_tool_defs,
inject_this_turn=bool(self.memory_handler.config.inject_tools),
client_declared_tools=bool(_original_tools),
)
if mem_tools_injected:
memory_tools_injected = True
logger.info(f"[{request_id}] Memory: Injected memory tools (openai)")
except Exception as e:
logger.warning(f"[{request_id}] Memory injection failed: {e}")
logger.warning(f"[{request_id}] Memory injection failed: {e!r}")
if memory_context_injected or memory_tools_injected:
remembered_event = self.pipeline_extensions.emit(
@@ -5736,6 +5880,12 @@ class OpenAIHandlerMixin:
# minimal `messages` list purely for downstream memory injection and
# telemetry; list-typed `input` is consulted directly by the unit
# extraction helpers.
#
# Before anything reads `input`: drop web_search_call history from a
# request that declares no web_search tool (Codex local compaction).
# A bypass request asked for its bytes untouched, so it is left alone.
if not _bypass and _drop_undeclared_web_search_calls(body, request_id=request_id):
body_mutation_tracker.mark_mutated("responses_web_search_history")
input_data = body.get("input", "")
instructions = body.get("instructions")
@@ -5875,7 +6025,10 @@ class OpenAIHandlerMixin:
) or _client_can_receive_memory_tools(memory_client)
if _ensure_chatgpt_responses_store_false(body, is_chatgpt_auth=is_chatgpt_auth):
logger.info(f"[{request_id}] Responses: forced store=false for ChatGPT auth")
responses_memory_tools_allowed = _allow_responses_memory_tools(is_chatgpt_auth)
# Streamed Responses turns do not execute memory tool calls; keep tools off.
responses_memory_tools_allowed = (
_allow_responses_memory_tools(is_chatgpt_auth) and not stream
)
# PR-A6 (P5-50, preps P0-6): session-sticky `OpenAI-Beta` merge
# for /v1/responses. Compute a session_id off the same store the
@@ -6158,7 +6311,7 @@ class OpenAIHandlerMixin:
f"[{request_id}] Memory: Injected memory tools (openai/responses)"
)
except Exception as e:
logger.warning(f"[{request_id}] Memory injection failed (responses): {e}")
logger.warning(f"[{request_id}] Memory injection failed (responses): {e!r}")
elif self.memory_handler and memory_user_id and _bypass:
logger.info(
"[%s] Responses memory passthrough reason=bypass_header",
@@ -7638,6 +7791,14 @@ class OpenAIHandlerMixin:
model or "unknown",
)
# Resolved before the frame helpers below, which read it.
_ws_bypass = self._headroom_bypass_enabled(ws_headers)
if _ws_bypass:
logger.info(
"[%s] WS /v1/responses passthrough reason=bypass_header mutation=disabled",
request_id,
)
def _normalize_ws_response_create_for_upstream(raw_msg: str) -> str:
"""Optionally flatten Codex WS response.create frames for gateways.
@@ -7645,7 +7806,18 @@ class OpenAIHandlerMixin:
OpenAI-compatible gateways accept the WebSocket upgrade but expect
model/input/tools at the top level of response.create frames.
Preserve default upstream behavior unless explicitly enabled.
Every response.create frame headed upstream (first frame, which
the HTTP fallback also replays, later frames, memory
continuations) passes through here, so it also drops
web_search_call history the frame declares no tool for (see
``_drop_undeclared_web_search_calls``), except on a bypass
session, whose frames stay as the client sent them.
"""
if not _ws_bypass:
raw_msg = _drop_undeclared_web_search_calls_from_frame(
raw_msg, request_id=request_id
)
if os.environ.get(
"HEADROOM_OPENAI_WS_FLATTEN_RESPONSE_CREATE", ""
).strip().lower() not in (
@@ -8181,7 +8353,7 @@ class OpenAIHandlerMixin:
return json.dumps(frame_body)
except Exception as e:
logger.warning(f"[{request_id}] WS Memory injection failed: {e}")
logger.warning(f"[{request_id}] WS Memory injection failed: {e!r}")
return frame_raw
if first_frame_is_create:
@@ -10701,9 +10873,6 @@ class OpenAIHandlerMixin:
session_tracker = self.session_tracker_store.get_or_create(
_session_key, _tracker_provider
)
from headroom.cache.prefix_tracker import seed_restored_compression_cache
seed_restored_compression_cache(session_tracker, comp_cache)
# A claimed turn prepares its executor-side work here (tokenizer,
# hooks, scope binding) — CPU-bound parts run inside the closures
@@ -10764,6 +10933,21 @@ class OpenAIHandlerMixin:
"(a previous turn for this session is still running)"
)
try:
nonlocal session_tracker
from headroom.cache.prefix_tracker import seed_restored_compression_cache
shared = self.shared_compress_sessions
if shared is not None:
# Another replica may have served this session's last
# turn: take its tracker when it is newer than ours.
newer = shared.fetch(
self.session_tracker_store, _session_key, session_tracker
)
if newer is not None:
# The key is present (get_or_create above).
self.session_tracker_store.install(_session_key, newer)
session_tracker = newer
seed_restored_compression_cache(session_tracker, comp_cache)
prev_original = session_tracker.get_last_original_messages()
prev_returned = session_tracker.get_last_forwarded_messages()
prep = prepare_turn(
@@ -10838,6 +11022,8 @@ class OpenAIHandlerMixin:
# return time because whatever we hand back IS what the
# caller sends upstream.
session_tracker.record_returned(messages, final)
if shared is not None:
shared.publish(self.session_tracker_store, _session_key, session_tracker)
info = {
"id": session_id,
"frozen_message_count": session_frozen,
@@ -11149,6 +11335,40 @@ class OpenAIHandlerMixin:
# from here.
_session_key = f"compress\x00{session_id}"
tracker = self.session_tracker_store.peek(_session_key)
shared = self.shared_compress_sessions
if shared is not None:
# The session's last turn may have run on another replica. Fetched
# under the turn lock (a local turn in flight must finish first),
# installed here on the loop: the key may be new to this store.
_local = tracker
_lock_cache = self._peek_compression_cache(_session_key)
def _fetch():
lock = _lock_cache.session_turn_lock if _lock_cache is not None else None
if lock is not None and not lock.acquire(
timeout=_SESSION_TURN_LOCK_TIMEOUT_SECONDS
):
return None
try:
return shared.fetch(self.session_tracker_store, _session_key, _local)
finally:
if lock is not None:
lock.release()
try:
newer = await self._run_compression_in_executor(
_fetch, timeout=COMPRESSION_TIMEOUT_SECONDS
)
except TimeoutError:
newer = None # answer from this replica's state, as without the store
if newer is not None:
current = self.session_tracker_store.peek(_session_key)
if current is _local:
self.session_tracker_store.install(_session_key, newer)
tracker = newer
else:
# A local turn installed a tracker meanwhile: it is newer.
tracker = current
if tracker is None:
return self._compress_usage_unknown_session(session_id)
# No create, no LRU bump: the cache is only needed for its turn lock.
@@ -11195,6 +11415,8 @@ class OpenAIHandlerMixin:
messages=last_returned,
original_messages=tracker.get_last_original_messages(),
)
if shared is not None:
shared.publish(self.session_tracker_store, _session_key, tracker)
return tracker.get_frozen_message_count()
finally:
if lock is not None:
@@ -11709,10 +11931,20 @@ class OpenAIHandlerMixin:
)
yield chunk
finally:
completed_normally = True
buf = stream_state["sse_buffer"]
if len(buf) > 0:
buf.extend(b"\n\n")
_absorb_usage(self._parse_sse_usage_from_buffer(stream_state, stream_provider))
# A truncated stream can end inside a multi-byte character;
# the strict decoder then raises and would skip the outcome
# below. Keep the usage already parsed, drop the unusable
# tail, and report the stream as failed.
try:
_absorb_usage(
self._parse_sse_usage_from_buffer(stream_state, stream_provider)
)
except UnicodeDecodeError:
completed_normally = False
output_tokens = stream_state["output_tokens"] or 0
cache_read_tokens = stream_state["cache_read_input_tokens"] or 0
@@ -11753,6 +11985,9 @@ class OpenAIHandlerMixin:
total_latency_ms=(time.time() - start_time) * 1000,
ttfb_ms=stream_state["ttfb_ms"] or 0,
tags=tags,
status_code=_stream_outcome_status(
upstream_response.status_code, completed_normally
),
client=client,
)
)
+45 -27
View File
@@ -250,6 +250,9 @@ def capture_codex_wire_debug(
# prefix) is never mutated.
# - "disabled": Memory context lookup is skipped entirely; the request
# forwards untouched.
# - "tool": Auto-injection of context is off, but the memory tools are still
# registered; the agent calls them explicitly (``search_and_format_context``
# returns None in this mode).
#
# Configurable via HEADROOM_MEMORY_INJECTION_MODE env var. There is no
# "system_prompt" option — that path is permanently retired by I2 (cache hot
@@ -1862,22 +1865,26 @@ class _OwnerOnlyRotatingFileHandler(RotatingFileHandler):
_owner_only_warning_emitted = False
def _warn_once_if_owner_only_unsupported(log_path: Path) -> None:
"""Say plainly, once per process, when the file cannot be made owner-only.
def _warn_once_if_not_protected(log_path: Path) -> None:
"""Say plainly, once per process, when the file is not actually owner-only.
A security control that quietly does nothing on a supported platform is
worse than no control, so Windows gets told rather than left to assume the
0600 in the docs applies to it.
Checks the file itself (:func:`headroom.fileperms.verify_owner_only`)
rather than assuming from the platform: on Windows the ACL restriction
(:mod:`headroom._fileperms_windows`) usually succeeds, in which case this
stays silent, but it can fail for reasons that have nothing to do with
Headroom's own code — a non-NTFS volume, a missing privilege — and a
control that quietly does nothing is worse than no control.
"""
global _owner_only_warning_emitted
if _fileperms.OWNER_ONLY_SUPPORTED or _owner_only_warning_emitted:
if _owner_only_warning_emitted or _fileperms.verify_owner_only(log_path):
return
_owner_only_warning_emitted = True
logger.warning(
"Headroom cannot create %s owner-only on this platform: file modes do not "
"control read access here, and Headroom does not set an ACL. The runtime log "
"can contain request and response content (--log-messages, wire debug, "
"HEADROOM_LOG_PAYLOAD_PREVIEW) — protect the log directory itself.",
"Headroom could not restrict %s to the current user — other accounts "
"on this machine may be able to read it. The runtime log can contain "
"request and response content (--log-messages, wire debug, "
"HEADROOM_LOG_PAYLOAD_PREVIEW); move HEADROOM_WORKSPACE_DIR somewhere "
"only you can access, or restrict the containing directory yourself.",
log_path,
)
@@ -1971,7 +1978,6 @@ def _setup_file_logging(
log_path,
)
return
_warn_once_if_owner_only_unsupported(log_path)
# Attach to the headroom root logger so all sub-loggers are captured.
# Keep root propagation enabled for container stdout/stderr while
# this handler writes the separate port/worker-specific proxy log.
@@ -2011,6 +2017,11 @@ def _setup_file_logging(
headroom_logger.removeHandler(stale)
stale.close()
headroom_logger.addHandler(handler)
# After, not before: the handler's _open() is what actually attempts
# the protection (mode bits on POSIX, the ACL call on Windows), so
# only now is there something real to verify rather than a platform
# guess.
_warn_once_if_not_protected(log_path)
if level == logging.DEBUG:
logger.warning(
"Headroom debug logging is on (HEADROOM_LOG_LEVEL). %s now records "
@@ -2022,11 +2033,13 @@ def _setup_file_logging(
)
except OSError as exc:
# Non-fatal: can't write logs (read-only fs, permissions, etc.). Say so,
# or the missing proxy.log is the only clue. The OSError names the path.
# or the missing proxy.log is the only clue. str(exc) embeds repr(filename),
# which doubles backslashes on Windows -- exc.filename is the raw path.
logger.warning(
"Headroom runtime log disabled: cannot write the log file: %s. "
"Headroom runtime log disabled: cannot write the log file: %s: %s. "
"Point HEADROOM_WORKSPACE_DIR at a writable directory to restore proxy.log.",
exc,
exc.filename or log_dir,
exc.strerror or exc,
)
@@ -2896,27 +2909,20 @@ def apply_session_sticky_ccr_tool(
* Otherwise, inject only when this turn produced compressed content.
The first injection records the golden bytes for future turns.
Tools whose name already equals ``CCR_TOOL_NAME`` (e.g. the client
pre-registered it via MCP) are not re-appended; the client's bytes
win.
Tools registered under ``CCR_TOOL_NAME`` or a supported client/MCP alias
are not re-appended; the client's executable name and definition win.
Returns ``(updated_tools, was_injected)``. ``updated_tools`` is a
fresh list (caller-safe).
"""
from headroom.ccr.tool_injection import CCR_TOOL_NAME
from headroom.ccr.tool_calls import client_retrieval_tool_name
if provider not in ("anthropic", "openai", "google"):
raise ValueError(f"unsupported provider: {provider!r}")
tools_out: list[dict[str, Any]] = list(existing_tools) if existing_tools else []
existing_names: set[str] = set()
for t in tools_out:
n = _extract_tool_name(t)
if n:
existing_names.add(n)
# Client (or MCP) already provided a tool by this name — don't double up.
if CCR_TOOL_NAME in existing_names:
# Only default Headroom aliases claim ownership, not arbitrary MCP servers.
if client_retrieval_tool_name(tools_out):
log_tool_injection_decision(
provider=provider,
session_id=session_id,
@@ -4097,9 +4103,21 @@ def _warn_deferred_without_search_tool(tools: Any) -> None:
)
#: Non-Anthropic upstreams that accept the first-party deferred tool shape.
#: These bill deferred schemas compactly, so downgrading deferral for them
#: inlines the whole catalog and multiplies billed prompt tokens.
_DEFERRAL_CAPABLE_HOSTS: frozenset[str] = frozenset({"api.githubcopilot.com"})
def anthropic_first_party_tool_search_supported(api_base_url: str | None) -> bool:
"""Return whether Anthropic server-side tool search is valid for this upstream."""
from headroom.providers.claude.runtime import is_custom_anthropic_base_url
from headroom.providers.claude.runtime import (
_gate_view_host,
is_custom_anthropic_base_url,
)
if _gate_view_host((api_base_url or "").strip()) in _DEFERRAL_CAPABLE_HOSTS:
return True
return not is_custom_anthropic_base_url(api_base_url)
+1 -4
View File
@@ -20,9 +20,7 @@ Precedence (highest first):
2. ``no_handler`` — no memory backend configured
3. ``no_user_id`` — per-request user_id missing
4. ``mode_disabled`` — operator HEADROOM_MEMORY_INJECTION_MODE=disabled
5. ``mode_tool`` — operator HEADROOM_MEMORY_INJECTION_MODE=tool
(auto-inject off; the agent calls memory tools explicitly)
6. otherwise → ``inject=True``
5. otherwise → ``inject=True``
This module exposes one value type + one factory + one helper. Pure
function; same Rust-port shape as :class:`CompressionDecision`.
@@ -59,7 +57,6 @@ class MemoryDecision:
# * "no_handler" — no memory backend configured on the proxy
# * "no_user_id" — per-request user_id missing
# * "mode_disabled" — operator HEADROOM_MEMORY_INJECTION_MODE=disabled
# * "mode_tool" — operator HEADROOM_MEMORY_INJECTION_MODE=tool
# When ``inject`` is True, this is None.
skip_reason: str | None
-3
View File
@@ -42,9 +42,6 @@ def decide_memory_injection(
elif mode_name == "disabled":
reason = "mode_disabled"
inject = False
elif mode_name == "tool":
reason = "mode_tool"
inject = False
else:
reason = None
inject = True
+24 -19
View File
@@ -759,9 +759,12 @@ class MemoryHandler:
if not self.config.inject_context:
return None
from headroom.proxy.helpers import get_memory_injection_mode
# PR-B6: Tool mode disables auto-injection. The model calls
# ``memory_search`` to retrieve when it wants to.
if self.config.mode == MemoryMode.TOOL:
# ``memory_search`` to retrieve when it wants to. Selected by the
# handler config or by HEADROOM_MEMORY_INJECTION_MODE=tool.
if self.config.mode == MemoryMode.TOOL or get_memory_injection_mode() == "tool":
logger.info(
"event=memory_mode_skip mode=tool user_id=%s reason=tool_mode_no_auto_injection",
user_id,
@@ -797,18 +800,6 @@ class MemoryHandler:
)
return None
# Build the embedding query. When the handler provides a
# MemoryQuery, use its multi-source untruncated input; otherwise
# fall back to extracting from messages (kept for legacy callers
# / tests). Full fidelity in both paths.
if query is not None:
query_text = query.to_embedding_input()
else:
query_text = self._extract_user_query(messages)
if not query_text:
logger.debug("Memory: No query text for context search")
return None
# Compose the budget: explicit per-call wins; otherwise derive
# from self.config so existing top_k/min_similarity callers see
# no behaviour change.
@@ -822,6 +813,22 @@ class MemoryHandler:
)
try:
if query is not None:
from headroom.proxy.memory_query_policy import bounded_embedding_parts
parts = bounded_embedding_parts(
user_text=query.user_text,
recent_tool_outputs=query.recent_tool_outputs,
recent_assistant_turns=query.recent_assistant_turns,
)
prepare = getattr(backend, "prepare_search_query", None)
query_text = await prepare(*parts) if prepare is not None else "".join(parts)
else:
query_text = self._extract_user_query(messages)[-4096:]
if not query_text:
logger.debug("Memory: No query text for context search")
return None
# Search memories on the per-request resolved backend.
results = await backend.search_memories(
query=query_text,
@@ -868,7 +875,7 @@ class MemoryHandler:
memory_lines.append(f" (Related: {entities_str})")
except Exception as e:
logger.warning(f"Memory: Search failed for user {effective_user_id}: {e}")
logger.warning(f"Memory: Search failed for user {effective_user_id}: {e!r}")
return None
if not memory_lines:
@@ -901,10 +908,8 @@ pass that ID directly to memory_update or memory_delete — you do not need \
to call memory_search first to discover IDs. Use this context to inform \
your responses, not to drive new actions."""
# Apply the token-budget cap on the formatted block. Pre-this-
# PR there was no cap — up to ~4000 tokens could be injected
# per request. The budget bounds the output without touching
# the input query (which stays full-fidelity per MemoryQuery).
# The formatted output budget is separate from the embedding-input
# budget above; the original MemoryQuery remains full-fidelity.
context = effective_budget.apply_to_text(context)
# Track only memories that survived ranking, entry limits, and the
@@ -5,8 +5,8 @@ from __future__ import annotations
from typing import Literal, cast
MEMORY_INJECTION_MODE_ENV = "HEADROOM_MEMORY_INJECTION_MODE"
MEMORY_INJECTION_MODE_DEFAULT: Literal["live_zone_tail", "disabled"] = "live_zone_tail"
MemoryInjectionMode = Literal["live_zone_tail", "disabled"]
MEMORY_INJECTION_MODE_DEFAULT: Literal["live_zone_tail", "disabled", "tool"] = "live_zone_tail"
MemoryInjectionMode = Literal["live_zone_tail", "disabled", "tool"]
def resolve_memory_injection_mode(raw: str | None) -> MemoryInjectionMode:
@@ -14,9 +14,9 @@ def resolve_memory_injection_mode(raw: str | None) -> MemoryInjectionMode:
normalized = (raw or "").strip().lower()
if not normalized:
return MEMORY_INJECTION_MODE_DEFAULT
if normalized in ("live_zone_tail", "disabled"):
if normalized in ("live_zone_tail", "disabled", "tool"):
return cast(MemoryInjectionMode, normalized)
raise ValueError(
f"Invalid {MEMORY_INJECTION_MODE_ENV}={normalized!r}; "
"expected 'live_zone_tail' or 'disabled'"
"expected 'live_zone_tail', 'disabled' or 'tool'"
)
+16 -20
View File
@@ -1,10 +1,8 @@
"""``MemoryQuery``: multi-source, full-fidelity retrieval query.
Pre-this-PR, the retrieval query was "latest user message, truncated
to 500 chars" (memory_handler.py:807). The truncation was a real bug
— none of Letta / Mem0 / Cognee / Supermemory truncate the embedding
input. Tool outputs are often the strongest retrieval signal in
coding sessions, and they were ignored entirely.
Raw user messages and recent tool/assistant turns are retained for retrieval
strategies that need their full content. Time-limited proxy lookups can render
a separate bounded embedding input without mutating those sources.
This value type captures the query at full fidelity from three
sources:
@@ -13,10 +11,8 @@ sources:
* ``recent_tool_outputs`` — last N tool results
* ``recent_assistant_turns`` — last K assistant turns for intent
The embedding model handles its own context window (MiniLM 512 tok;
BGE-small 8K tok). Long inputs that exceed the model window become
the model's problem to mean-pool or chunk — they don't get
truncated upstream.
The default embedding representation preserves the full sources. A caller can
request a character budget when embedding latency must fit a request deadline.
"""
from __future__ import annotations
@@ -34,11 +30,9 @@ from .memory_query_policy import (
class MemoryQuery:
"""Frozen multi-source query for memory retrieval.
All fields preserve full input fidelity — no truncation, no
summarization. The caller assembles the sources; this type only
holds them. The retrieval backend decides how to embed
(mean-pool, chunk, model-side truncation, etc.) but cannot lose
information before it sees the data.
Raw fields preserve full input fidelity. Budgeted embedding rendering
produces a derived query without changing those fields; backends that
chunk or mean-pool full inputs can still use the original sources.
Tuples for the recent-* fields so the dataclass stays hashable
(frozen + value-equal).
@@ -49,18 +43,20 @@ class MemoryQuery:
recent_assistant_turns: tuple[str, ...]
conversation_id: str | None
def to_embedding_input(self) -> str:
"""Concatenate sources into a delimited embedding input.
def to_embedding_input(self, *, max_chars: int | None = None) -> str:
"""Render delimited embedding input, optionally within a character budget.
Order: prior assistant turns (oldest first) → tool outputs
(oldest first) → latest user text. User text last because the
embedder's positional weighting often emphasizes the tail of
the input.
By default, context is chronological and user text comes last.
With a character budget, user text comes first and recent context is
selected newest-first, then rendered chronologically so a tokenizer
can retain its newest tail. Proxy lookups separately reserve space
for both sources inside the active local model's token window.
"""
return render_embedding_input(
user_text=self.user_text,
recent_tool_outputs=self.recent_tool_outputs,
recent_assistant_turns=self.recent_assistant_turns,
max_chars=max_chars,
)
@classmethod
+50 -10
View File
@@ -17,18 +17,58 @@ def render_embedding_input(
user_text: str,
recent_tool_outputs: tuple[str, ...],
recent_assistant_turns: tuple[str, ...],
max_chars: int | None = None,
) -> str:
"""Concatenate memory query sources into a delimited embedding input."""
"""Render full sources, or a user-first query within an embedding budget."""
parts: list[str] = []
for asst in recent_assistant_turns:
if asst:
parts.append(ASSISTANT_DELIM + asst)
for tool_out in recent_tool_outputs:
if tool_out:
parts.append(TOOL_DELIM + tool_out)
if user_text:
parts.append(USER_DELIM + user_text)
return "".join(parts)
if max_chars is None:
for asst in recent_assistant_turns:
if asst:
parts.append(ASSISTANT_DELIM + asst)
for tool_out in recent_tool_outputs:
if tool_out:
parts.append(TOOL_DELIM + tool_out)
if user_text:
parts.append(USER_DELIM + user_text)
return "".join(parts)
return "".join(
bounded_embedding_parts(
user_text=user_text,
recent_tool_outputs=recent_tool_outputs,
recent_assistant_turns=recent_assistant_turns,
max_chars=max_chars,
)
)
def bounded_embedding_parts(
*,
user_text: str,
recent_tool_outputs: tuple[str, ...],
recent_assistant_turns: tuple[str, ...],
max_chars: int = 4096,
) -> tuple[str, str]:
"""Keep question and context separate so a tokenizer can budget both."""
remaining = max(0, max_chars)
user_chars = min(2048, max(0, remaining - len(USER_DELIM)))
question = USER_DELIM + user_text[-user_chars:] if user_text and user_chars else ""
remaining -= len(question) + bool(question)
parts: list[str] = []
for delimiter, sources in (
(TOOL_DELIM, recent_tool_outputs),
(ASSISTANT_DELIM, recent_assistant_turns),
):
for source in reversed(sources):
if not source:
continue
source_chars = min(512, remaining - len(delimiter))
if source_chars <= 0:
break
part = delimiter + source[-source_chars:]
parts.append(part)
remaining -= len(part)
return question, "".join(reversed(parts))
def extract_memory_query_sources(
+2 -2
View File
@@ -124,7 +124,7 @@ class RequestOutcome:
# ── Output composition ────────────────────────────────────────────
# ``output_tokens`` pools two quantities that different levers move in
# opposite directions: reasoning-effort routing cuts thinking, verbosity
# opposite directions: thinking-budget levers cut thinking, verbosity
# steering cuts visible text. Summed, neither can be attributed — a turn
# whose thinking dropped 4,000 tokens while its prose grew 200 is
# indistinguishable from one where nothing happened.
@@ -250,7 +250,7 @@ class RequestOutcome:
The quantity verbosity steering actually targets. Callers must handle
``None`` rather than defaulting it to ``output_tokens``: on a provider
that reports no thinking count, treating the whole output as visible
would credit steering with reductions that reasoning-effort routing
would credit steering with reductions that a lower thinking budget
produced.
Clamped at zero because an inferred count comes from Headroom's
+2 -16
View File
@@ -9,18 +9,7 @@ output tokens, so every lever here works by reshaping the request:
provider prefix cache is preserved). Five levels, from "no ceremony" to
full caveman.
2. Effort routing — agentic loops are mostly mechanical continuations (the
last message is a clean tool_result: a file read, a passing test). Thinking
bills as output tokens, and harnesses like Claude Code pin
``output_config.effort`` at ``xhigh`` for every turn. On turns classified
as mechanical we lower an explicitly-present effort; on errors or new user
asks we leave it alone. For legacy models still sending
``thinking.budget_tokens`` we clamp the budget to the API floor instead.
Safety rules (each prevents a concrete failure mode):
- Never INJECT ``output_config.effort`` where the client didn't send it —
models without effort support 400 on it. Lowering an existing value is
always valid.
- Never toggle ``thinking.type`` — disabling thinking while history carries
thinking blocks 400s on some models, and the toggle busts the messages
cache tier.
@@ -100,8 +89,7 @@ class OutputShaperSettings:
verbosity_level: int = DEFAULT_VERBOSITY_LEVEL
# False in ``mode="cache"``. Steering is the one lever that writes into the
# provider prefix-cache key (it appends to the system-prompt tail, and on a
# body with no system field it creates one); effort routing and the
# thinking budget sit outside the key and stay on. See
# body with no system field it creates one). See
# :func:`steering_allowed_for`.
steering_enabled: bool = True
@@ -193,9 +181,7 @@ def steering_allowed_for(config: Any) -> bool:
prefix-cache key byte-stable (see ``ProxyConfig.mode``). Verbosity steering
writes into that key, so a block that CHANGES there trades a large, certain
cache cost for a small, uncertain output saving — the wrong side of a
roughly 60x margin on a long context. Effort routing and the thinking
budget are unaffected: they ride request parameters outside the cache key,
so they keep saving in cache mode.
roughly 60x margin on a long context.
This is the gate for the sources that can change mid-conversation. It is
NOT the last word: :func:`resolve_verbosity_level` lets an explicitly
+38 -4
View File
@@ -14,6 +14,26 @@ MAX_STACK_VALUES = 64
MAX_TRACKED_MODELS = 200
MAX_EXPOSED_MODELS = 100
MAX_LABEL_LENGTH = 128
OTHER_MODEL = "other"
# ``CostTracker.stats()`` skips keys with this prefix; an overflowing
# passthrough name must keep it or it would enter the processed-traffic totals.
PASSTHROUGH_PREFIX = "passthrough:"
OTHER_PASSTHROUGH_MODEL = PASSTHROUGH_PREFIX + OTHER_MODEL
def bounded_model_key(model: str, tracked: Any) -> str:
"""Key under which a client-supplied model name may enter a per-model map.
``model`` comes from the request body, so it is clipped to
``MAX_LABEL_LENGTH`` and a new name past ``MAX_TRACKED_MODELS`` distinct
keys collapses into ``OTHER_MODEL`` (``OTHER_PASSTHROUGH_MODEL`` for a
``passthrough:`` name). ``tracked`` is the map being written.
"""
key = model[:MAX_LABEL_LENGTH]
if key in tracked or len(tracked) < MAX_TRACKED_MODELS:
return key
return OTHER_PASSTHROUGH_MODEL if key.startswith(PASSTHROUGH_PREFIX) else OTHER_MODEL
KNOWN_MISS_REASONS = frozenset({"ttl_expiry", "prefix_change", "unknown"})
# Mirrors RATE_LIMIT_SOURCES in prometheus_metrics: "headroom" is our own
@@ -63,6 +83,15 @@ def _coerce_float(value: Any) -> float:
return result if math.isfinite(result) and result >= 0 else 0.0
def _coerce_signed_float(value: Any) -> float:
"""_coerce_float without the zero floor, for compression savings that can lose."""
try:
result = float(value)
except (TypeError, ValueError, OverflowError):
return 0.0
return result if math.isfinite(result) else 0.0
def _label(value: Any) -> str:
if not isinstance(value, str):
return "other"
@@ -237,7 +266,10 @@ class PersistentMetricsState:
"compression_savings_list_usd",
"cache_savings_usd",
):
result["cost"][key] = round(_coerce_float(raw_cost.get(key)), 6)
coerce = (
_coerce_signed_float if key.startswith("compression_savings") else _coerce_float
)
result["cost"][key] = round(coerce(raw_cost.get(key)), 6)
# A state written before cache-aware pricing has no list column and its
# dollars WERE list-priced, so that one figure seeds both and the
# aggregate stays honestly labelled.
@@ -246,7 +278,7 @@ class PersistentMetricsState:
# column, and labelling that "list" would tell every new install its
# untouched $0.00 total was list-priced. Only a state that actually
# accumulated dollars has history to migrate.
has_priced_history = result["cost"]["compression_savings_usd"] > 0
has_priced_history = result["cost"]["compression_savings_usd"] != 0
if "compression_savings_list_usd" in raw_cost:
result["cost"]["savings_basis"] = str(raw_cost.get("savings_basis") or "unknown")
elif has_priced_history:
@@ -446,7 +478,7 @@ class PersistentMetricsState:
cost = self._state["cost"]
cost["input_usd"] = round(cost["input_usd"] + _coerce_float(input_usd), 6)
cost["compression_savings_usd"] = round(
cost["compression_savings_usd"] + _coerce_float(compression_savings_usd), 6
cost["compression_savings_usd"] + _coerce_signed_float(compression_savings_usd), 6
)
# Defaults to the cache-aware figure when a caller supplies no ceiling,
# which is the truthful reading of "these are the same number" for a
@@ -457,7 +489,9 @@ class PersistentMetricsState:
else compression_savings_list_usd
)
cost["compression_savings_list_usd"] = round(
_coerce_float(cost.get("compression_savings_list_usd")) + _coerce_float(list_delta), 6
_coerce_signed_float(cost.get("compression_savings_list_usd"))
+ _coerce_signed_float(list_delta),
6,
)
if savings_basis:
cost["savings_basis"] = _blend_savings_basis(cost.get("savings_basis"), savings_basis)

Some files were not shown because too many files have changed in this diff Show More