Skip to content

OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security

fix(cost): enforce scan budgets from verified usage (#465)

Michael D'Angeloc9cb6b4bca13
diff --git a/plugins/codex-security/mcp-app/tests/test_workbench_database.ts b/plugins/codex-security/mcp-app/tests/test_workbench_database.ts
index ac108f1a4..ffad1b5c9 100644
--- a/plugins/codex-security/mcp-app/tests/test_workbench_database.ts
+++ b/plugins/codex-security/mcp-app/tests/test_workbench_database.ts
@@ -199,7 +199,7 @@ for (const previewVersion of [58, 59]) {
}
for (const { missingVersions, legacyCheckpoint, mainReader } of [
- { missingVersions: [57, 58, 59, 60], legacyCheckpoint: 0, mainReader: false },
+ { missingVersions: [57], legacyCheckpoint: 0, mainReader: false },
{ missingVersions: [], legacyCheckpoint: 47, mainReader: false },
{ missingVersions: [], legacyCheckpoint: 47, mainReader: true },
{ missingVersions: [], legacyCheckpoint: 48, mainReader: false },
@@ -227,6 +227,7 @@ for (const { missingVersions, legacyCheckpoint, mainReader } of [
migrations
.filter(
({ version }) =>
+ version <= 57 &&
!missingVersions.includes(version) &&
!(firstMissing && version >= firstMissing && version <= 56),
)
@@ -365,8 +366,7 @@ for (const { missingVersions, legacyCheckpoint, mainReader } of [
});
}
-test("worker thread history survives retry, replay, and worker retirement", (t) => {
- const database = memory(t, 49);
+function insertRunningWorker(database: DatabaseSync) {
insertScan(database);
database.exec(`
INSERT INTO deep_scan_runs (
@@ -379,6 +379,30 @@ test("worker thread history survives retry, replay, and worker retirement", (t)
) VALUES ('worker', 'scan', 'discovery', 'running', '/synthetic/prompt.md',
'/synthetic/output', 1, 'first-thread', 'created', 'updated');
`);
+}
+
+test("legacy retries can reuse a recorded thread and still verify usage", (t) => {
+ for (const thread of ["first-thread", "retry-thread", null]) {
+ const database = memory(t, 62);
+ insertRunningWorker(database);
+ database
+ .prepare(
+ "UPDATE deep_scan_workers SET attempt = 3, started_at = 'started', sdk_thread_id = ?",
+ )
+ .run(thread);
+ if (thread === null) database.exec("DELETE FROM deep_scan_worker_threads");
+ applyMigrations(database);
+ assert.equal(
+ database.prepare("SELECT worker_usage_gap FROM deep_scan_runs").get()
+ ?.worker_usage_gap,
+ thread === null ? 1 : 0,
+ );
+ }
+});
+
+test("worker thread history survives retry, replay, and worker retirement", (t) => {
+ const database = memory(t, 49);
+ insertRunningWorker(database);
applyMigrations(database);
database.exec(`
UPDATE deep_scan_workers SET sdk_thread_id = 'retry-thread', attempt = 2;
diff --git a/plugins/codex-security/requirements-test.txt b/plugins/codex-security/requirements-test.txt
index e005b00f3..1790db5ab 100644
--- a/plugins/codex-security/requirements-test.txt
+++ b/plugins/codex-security/requirements-test.txt
@@ -1,4 +1,5 @@
# Development test and lint dependencies; install from the repository root.
+backports.zstd==1.8.0; python_version < "3.14"
jsonschema==4.26.0
packaging==26.3
pytest==9.2.0
diff --git a/plugins/codex-security/scripts/deep_scan_workbench.py b/plugins/codex-security/scripts/deep_scan_workbench.py
index 635963ca3..77beac07d 100644
--- a/plugins/codex-security/scripts/deep_scan_workbench.py
+++ b/plugins/codex-security/scripts/deep_scan_workbench.py
@@ -1327,11 +1327,14 @@ def upsert_deep_scan_worker(
if error_message is None and args.status != "succeeded":
error_message = existing["error_message"]
started_at = existing["started_at"] or (timestamp if args.status == "running" else None)
+ thread_id = optional_text(args.sdk_thread_id, maximum=512)
+ if thread_id is None and attempt == existing["attempt"]:
+ thread_id = existing["sdk_thread_id"]
connection.execute(
"""
UPDATE deep_scan_workers
SET status = ?, result_manifest_path = ?, attempt = ?,
- sdk_thread_id = COALESCE(?, sdk_thread_id),
+ sdk_thread_id = ?,
completion_sequence = ?, merge_state = ?,
error_message = ?,
started_at = ?, completed_at = ?, updated_at = ?
@@ -1341,7 +1344,7 @@ def upsert_deep_scan_worker(
args.status,
result_manifest_path or existing["result_manifest_path"],
attempt,
- optional_text(args.sdk_thread_id, maximum=512),
+ thread_id,
completion_sequence,
merge_state,
error_message,
diff --git a/plugins/codex-security/scripts/workbench_cli.py b/plugins/codex-security/scripts/workbench_cli.py
index acd772c35..5c1c532bb 100644
--- a/plugins/codex-security/scripts/workbench_cli.py
+++ b/plugins/codex-security/scripts/workbench_cli.py
@@ -199,6 +199,9 @@ def parse_args(description: str, *, inspection_only: bool = False) -> argparse.N
add_command("rename-scan", "--scan-id", "--name")
+ read_scan_usage = add_command("read-scan-usage", "--scan-id", "--thread-id")
+ read_scan_usage.add_argument("--validation-thread-id")
+
add_command("get-scan-feedback", "--scan-id")
update_scan_context = add_command("update-scan-context", "--scan-id")
diff --git a/plugins/codex-security/scripts/workbench_db.py b/plugins/codex-security/scripts/workbench_db.py
index e1661a406..d1936c4ec 100644
--- a/plugins/codex-security/scripts/workbench_db.py
+++ b/plugins/codex-security/scripts/workbench_db.py
@@ -1030,6 +1030,17 @@ def complete_scan(
)
+def read_scan_usage(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
+ # Validation can finish after the scan's recorded completion timestamp.
+ return scan_usage.collect_scan_usage(
+ connection,
+ require_scan(connection, args.scan_id),
+ thread_id=args.thread_id,
+ validation_thread_id=args.validation_thread_id,
+ completed_at=now(),
+ )
+
+
def finalize_scan_usage(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
scan_id = require_uuid(args.scan_id, "scan-id")
with scan_completion_lock(scan_id):
@@ -3210,7 +3221,9 @@ def main(*, before_archive: Callable[[], None] | None = None) -> None:
print(json.dumps(result, allow_nan=False, sort_keys=True))
return
with closing(
- connect(deferred=args.command in {"get-scan", "list-scans", "database-info"})
+ connect(
+ deferred=args.command in {"get-scan", "read-scan-usage", "list-scans", "database-info"}
+ )
) as connection:
remediation_state.require_available(connection, args, require_scan)
handlers = {
@@ -3230,6 +3243,7 @@ def main(*, before_archive: Callable[[], None] | None = None) -> None:
"register-cli-scan": partial(register_cli_scan, before_archive=before_archive),
"set-scan-thread": set_scan_thread,
"set-scan-cost-limit": set_scan_cost_limit,
+ "read-scan-usage": read_scan_usage,
"finalize-scan-usage": finalize_scan_usage,
"list-global-findings": native_indexes.list_global_findings,
"list-repositories": native_indexes.list_repositories,
diff --git a/plugins/codex-security/scripts/workbench_scan_usage.py b/plugins/codex-security/scripts/workbench_scan_usage.py
index 01b4d6e64..04eef1c1b 100644
--- a/plugins/codex-security/scripts/workbench_scan_usage.py
+++ b/plugins/codex-security/scripts/workbench_scan_usage.py
@@ -10,10 +10,11 @@ import re
import sqlite3
import sys
import uuid
+from contextlib import contextmanager
from dataclasses import dataclass
from datetime import datetime, timezone
from pathlib import Path
-from typing import Any, Mapping
+from typing import Any, BinaryIO, Iterator, Mapping
from urllib.parse import quote
TOKEN_FIELDS = {
@@ -90,6 +91,7 @@ def collect_scan_usage(
scan: sqlite3.Row,
*,
thread_id: str | None = None,
+ validation_thread_id: str | None = None,
completed_at: str | None = None,
completed_turn_id: str | None = None,
) -> dict[str, Any]:
@@ -102,7 +104,11 @@ def collect_scan_usage(
roots = _scan_root_thread_ids(connection, scan, thread_id)
parent_ids = set(_scan_root_thread_ids(connection, scan, thread_id, include_workers=False))
- worker_directories = _scan_worker_directories(connection, scan)
+ if validation_thread_id:
+ roots.append(validation_thread_id)
+ parent_ids.add(validation_thread_id)
+ warnings: set[str] = set()
+ worker_directories = _scan_worker_directories(connection, scan, warnings)
if not roots and not worker_directories:
return _unavailable_usage("scan_thread_unavailable")
@@ -116,7 +122,6 @@ def collect_scan_usage(
if started_at is None:
return _unavailable_usage("scan_window_unavailable")
- warnings: set[str] = set()
try:
sessions, missing_thread_ids = _discover_rollout_sessions(
state_database,
@@ -177,7 +182,7 @@ def collect_scan_usage(
for key, snapshot in usage.rate_limits.items():
if key not in rate_limits or snapshot["observedAt"] > rate_limits[key]["observedAt"]:
rate_limits[key] = snapshot
- if "token_usage_unavailable" in usage.warnings:
+ if usage.warnings & {"token_usage_unavailable", "token_breakdown_unavailable"}:
missing_thread_ids.add(session.thread_id)
continue
role = by_role["parent" if session.thread_id in parent_ids else "workers"]
@@ -192,9 +197,12 @@ def collect_scan_usage(
return _unavailable_usage("scan_thread_unavailable", warnings=warnings)
thread_count = sum(role["threadCount"] for role in by_role.values())
if not thread_count:
- return _unavailable_usage(
- "token_usage_unavailable", warnings=warnings, rate_limits=rate_limits
+ reason = (
+ "token_breakdown_unavailable"
+ if "token_breakdown_unavailable" in warnings
+ else "token_usage_unavailable"
)
+ return _unavailable_usage(reason, warnings=warnings, rate_limits=rate_limits)
if any(
usage["cachedInputTokens"] + usage["cacheWriteInputTokens"] > usage["inputTokens"]
@@ -276,19 +284,35 @@ def _scan_execution_thread_ids(connection: sqlite3.Connection, scan: sqlite3.Row
)
-def _scan_worker_directories(connection: sqlite3.Connection, scan: sqlite3.Row) -> set[str]:
+def _scan_worker_directories(
+ connection: sqlite3.Connection, scan: sqlite3.Row, warnings: set[str]
+) -> dict[str, bool]:
if scan["mode"] != "deep":
- return set()
+ return {}
+ if connection.execute(
+ "SELECT 1 FROM deep_scan_runs WHERE scan_id = ? AND worker_usage_gap = 1", (scan["id"],)
+ ).fetchone():
+ warnings.add("worker_thread_unavailable")
artifacts = Path(scan["scan_dir"]) / "artifacts"
- # Finding comparisons start independent sessions before the batch checkpoint is saved.
- return {str(artifacts / "deep_discovery")} | {
- row["artifact_dir"] if row["kind"] == "discovery" else str(artifacts)
- for row in connection.execute(
- "SELECT kind, artifact_dir FROM deep_scan_workers "
- "WHERE scan_id = ? AND kind IN ('discovery', 'dedup')",
- (scan["id"],),
- )
- }
+ # Comparison turns run in this directory without a discovery worker row.
+ directories = {str(artifacts / "deep_discovery"): False}
+ for row in connection.execute(
+ "SELECT kind, artifact_dir, started_at, sdk_thread_id, attempt FROM deep_scan_workers "
+ "WHERE scan_id = ? AND kind IN ('discovery', 'dedup')",
+ (scan["id"],),
+ ):
+ if row["kind"] == "discovery":
+ if row["sdk_thread_id"] and row["attempt"] == 1:
+ continue # The first attempt already has an exact thread identity.
+ # An attempt that started without a saved ID must be found by its assigned cwd.
+ missing_thread = bool(row["started_at"] and not row["sdk_thread_id"])
+ directories[row["artifact_dir"]] = missing_thread
+ else:
+ directories[str(artifacts)] = False
+ if row["attempt"] > 1 and row["started_at"] and not row["sdk_thread_id"]:
+ # Retries share a cwd. A rollout from an older attempt cannot prove the new one.
+ warnings.add("worker_thread_unavailable")
+ return directories
def _codex_state_database() -> Path | None:
@@ -333,7 +357,7 @@ def _discover_rollout_sessions(
roots: list[str],
warnings: set[str],
*,
- worker_directories: set[str],
+ worker_directories: dict[str, bool],
scan_directory: Path | None = None,
started_at: datetime,
completed_at: datetime | None,
@@ -354,11 +378,11 @@ def _discover_rollout_sessions(
if not required.issubset(columns):
raise ValueError("Codex state graph does not expose the required thread columns.")
if table == "threads" and worker_directories and not {"cwd", "created_at"} <= columns:
- worker_directories = set()
+ worker_directories = {}
warnings.add("worker_directories_unavailable")
sessions: dict[str, RolloutSession] = {}
missing_thread_ids: set[str] = set()
- root_ids = dict.fromkeys(roots)
+ root_ids: dict[str, str | None] = dict.fromkeys(roots)
started_millisecond = started_at.replace(microsecond=started_at.microsecond // 1000 * 1000)
completed_timestamp = int(completed_at.timestamp()) if completed_at is not None else None
directory_expression = "cwd"
@@ -369,9 +393,14 @@ def _discover_rollout_sessions(
"codex_security_path_key", 1, _normalized_windows_path, deterministic=True
)
directory_expression = "codex_security_path_key(cwd)"
- worker_directories = {_normalized_windows_path(value) for value in worker_directories}
+ worker_directories = {
+ _normalized_windows_path(path): required
+ for path, required in worker_directories.items()
+ }
if scan_directory is not None:
scan_directory = Path(_normalized_windows_path(scan_directory))
+ unmatched = {path for path, required in worker_directories.items() if required}
+ directory_sources = {path: {path} for path in worker_directories}
if worker_directories and scan_directory and ".previous-" in scan_directory.name:
# Archived files move, but session working directories describe where execution ran.
# Confirm the original output with an already-bound session before including peers.
@@ -384,7 +413,7 @@ def _discover_rollout_sessions(
)
}
relatives = {
- Path(path).relative_to(scan_directory)
+ Path(path).relative_to(scan_directory): path
for path in worker_directories
if Path(path).is_relative_to(scan_directory)
}
@@ -392,23 +421,24 @@ def _discover_rollout_sessions(
if marker.start() == 0:
continue
original = scan_directory.with_name(scan_directory.name[: marker.start()])
- candidates = {original / relative for relative in relatives}
+ candidates = {original / relative: path for relative, path in relatives.items()}
# Older archives kept absolute discovery paths in their original directory.
if (
original in bound_directories
- or candidates & bound_directories
+ or candidates.keys() & bound_directories
or any(Path(path).is_relative_to(original) for path in worker_directories)
):
- worker_directories = worker_directories | {str(path) for path in candidates}
- for directory in sorted(worker_directories):
+ for candidate, path in candidates.items():
+ directory_sources.setdefault(str(candidate), set()).add(path)
+ for directory in sorted(directory_sources):
for row in database.execute(
"SELECT id FROM threads WHERE cwd IS NOT NULL "
f"AND {directory_expression} = ? AND created_at >= ? "
"AND (? IS NULL OR created_at <= ?) ORDER BY id",
(directory, int(started_at.timestamp()), completed_timestamp, completed_timestamp),
):
- root_ids[row["id"]] = None
- for root in root_ids:
+ root_ids[row["id"]] = directory
+ for root, directory in root_ids.items():
row = database.execute(
"SELECT id, rollout_path FROM threads WHERE id = ?",
(root,),
@@ -424,7 +454,7 @@ def _discover_rollout_sessions(
continue
if root not in roots:
try:
- with path.open("rb") as source:
+ with _open_rollout(path) as source:
metadata = json.loads(source.readline())
except (OSError, ValueError):
missing_thread_ids.add(root)
@@ -443,6 +473,8 @@ def _discover_rollout_sessions(
)
):
continue
+ if directory is not None:
+ unmatched.difference_update(directory_sources[directory])
sessions[root] = RolloutSession(root, None, path)
descendants = database.execute(
"""
@@ -500,6 +532,8 @@ def _discover_rollout_sessions(
warnings.add("rollout_unavailable")
continue
sessions[child_id] = RolloutSession(child_id, parent_id, path)
+ if unmatched:
+ warnings.add("worker_thread_unavailable")
return list(sessions.values()), missing_thread_ids
finally:
database.close()
@@ -512,6 +546,13 @@ def _rollout_path(value: object) -> Path | None:
if not candidate.is_absolute():
return None
try:
+ try:
+ candidate.lstat()
+ except FileNotFoundError:
+ # Native cold storage may compress an indexed JSONL file in place.
+ if candidate.suffix != ".jsonl":
+ return None
+ candidate = candidate.with_suffix(".jsonl.zst")
resolved = candidate.resolve(strict=True)
if not resolved.is_file():
return None
@@ -528,6 +569,32 @@ def _rollout_path(value: object) -> Path | None:
return None
+@contextmanager
+def _open_rollout(path: Path, *, verify_end: bool = False) -> Iterator[BinaryIO]:
+ if path.suffix != ".zst":
+ with path.open("rb") as source:
+ yield source
+ return
+ try:
+ from compression import zstd # Python 3.14+
+ except ImportError:
+ try:
+ from backports import zstd
+ except ImportError:
+ raise OSError(
+ "Compressed Codex rollouts require Python 3.14+ or backports.zstd."
+ ) from None
+ try:
+ with zstd.open(path, "rb") as source:
+ yield source
+ # A requested completion turn may stop parsing before the frame checksum.
+ if verify_end:
+ while source.read(64 * 1024):
+ pass
+ except (zstd.ZstdError, EOFError) as error:
+ raise ValueError("Invalid compressed Codex rollout.") from error
+
+
def _read_rollout_usage(
session: RolloutSession,
*,
@@ -540,8 +607,13 @@ def _read_rollout_usage(
total = result.tokens
warnings = result.warnings
previous = _empty_token_usage()
+ previous_cache_writes_reported = True
+ prefix_unclassified = 0
+ prefix_missing_cache: set[str] = set()
+ ambiguous_legacy_cache = False
boundary_reached = False
legacy_usage = _empty_token_usage()
+ completed_legacy_usage = _empty_token_usage()
response_usage: dict[str, int] | None = None
observed_response_usage = _empty_token_usage()
response_ids: set[str] = set()
@@ -561,7 +633,7 @@ def _read_rollout_usage(
and (completed_turn_id is None or turn_id != completed_turn_id)
)
- with session.path.open("rb") as source:
+ with _open_rollout(session.path, verify_end=True) as source:
for line_number, raw_line in enumerate(source, start=1):
if not raw_line.endswith(b"\n"):
warnings.add("rollout_record_incomplete")
@@ -623,7 +695,14 @@ def _read_rollout_usage(
elif event.get("type") == "event_msg" and payload.get("type") == "token_count":
inherited_usage = _token_snapshot(payload)
if inherited_usage is not None:
- previous = inherited_usage
+ missing_cache = _missing_cache_fields(payload)
+ baseline = _retain_cache_baseline(previous, inherited_usage, missing_cache)
+ if baseline is None:
+ warnings.add("token_breakdown_unavailable")
+ else:
+ previous = baseline
+ prefix_unclassified = _uncached_input(baseline)
+ prefix_missing_cache = missing_cache
if not boundary_reached:
continue
if event.get("type") == "event_msg" and payload.get("type") == "task_started":
@@ -641,6 +720,11 @@ def _read_rollout_usage(
_add_token_usage(
total, response_usage if response_usage is not None else legacy_usage
)
+ if response_usage is None:
+ _add_token_usage(completed_legacy_usage, legacy_usage)
+ if ambiguous_legacy_cache:
+ warnings.add("token_breakdown_unavailable")
+ ambiguous_legacy_cache = False
legacy_usage = _empty_token_usage()
response_usage = None
if payload.get("turn_id") != current_turn_id:
@@ -759,25 +843,91 @@ def _read_rollout_usage(
if timestamp is None or snapshot is None:
warnings.add("token_record_invalid")
continue
+ reset = snapshot["totalTokens"] < previous["totalTokens"]
+ if reset:
+ prefix_unclassified = 0
+ missing_cache = _missing_cache_fields(payload)
+ cache_writes_reported = "cacheWriteInputTokens" not in missing_cache
+ baseline = _retain_cache_baseline(previous, snapshot, missing_cache)
+ if baseline is None:
+ if not past_scan_end(timestamp, current_turn_id):
+ warnings.add("token_breakdown_unavailable")
+ continue
+ if baseline is previous:
+ cache_writes_reported = previous_cache_writes_reported and cache_writes_reported
+ refines_classification = (
+ baseline["inputTokens"] >= previous["inputTokens"]
+ and baseline["outputTokens"] >= previous["outputTokens"]
+ and baseline["cachedInputTokens"] >= previous["cachedInputTokens"]
+ and baseline["cacheWriteInputTokens"] >= previous["cacheWriteInputTokens"]
+ and (
+ (not previous_cache_writes_reported and cache_writes_reported)
+ or baseline["cachedInputTokens"] > previous["cachedInputTokens"]
+ or baseline["cacheWriteInputTokens"] > previous["cacheWriteInputTokens"]
+ )
+ )
+ previous_cache_writes_reported = cache_writes_reported
delta = {
- key: value - previous[key] if value >= previous[key] else value
+ key: value if reset or value < previous[key] else value - previous[key]
for key, value in snapshot.items()
}
- previous = snapshot
+ previous = baseline
if past_scan_end(timestamp, current_turn_id):
continue
if isinstance(current_turn_id, str):
measured_turns.add(current_turn_id)
if timestamp < started_at:
+ prefix_unclassified = _uncached_input(baseline)
+ prefix_missing_cache = missing_cache
continue
if completed_turn_id is not None and current_turn_id == completed_turn_id:
completed_turn_measured = True
result.tokens_updated_at = max(result.tokens_updated_at or timestamp, timestamp)
- if delta["totalTokens"] <= 0:
+ delta["totalTokens"] = delta["inputTokens"] + delta["outputTokens"]
+ if delta["totalTokens"] <= 0 and not refines_classification:
continue
+ cache_write_capacity = (
+ _uncached_input(legacy_usage) + delta["inputTokens"]
+ if refines_classification
+ else delta["inputTokens"]
+ )
+ # Late cumulative cache details can classify an earlier legacy turn.
+ completed_capacity = (
+ _uncached_input(completed_legacy_usage)
+ if refines_classification and response_usage is None
+ else 0
+ )
+ if (
+ prefix_unclassified > 0
+ and refines_classification
+ and (
+ any(delta[key] > 0 for key in prefix_missing_cache)
+ # Even explicit counters can revise earlier input when the
+ # newly classified tokens exceed all in-scan capacity.
+ or delta["cachedInputTokens"] + delta["cacheWriteInputTokens"]
+ > cache_write_capacity + completed_capacity
+ )
+ ):
+ # The newly classified tokens could have occurred before this scan.
+ ambiguous_legacy_cache = True
+ for key in ("cacheWriteInputTokens", "cachedInputTokens"):
+ current = min(delta[key], cache_write_capacity)
+ completed = min(delta[key] - current, completed_capacity)
+ if completed and ambiguous_legacy_cache:
+ warnings.add("token_breakdown_unavailable")
+ delta[key] = current
+ cache_write_capacity -= current
+ completed_capacity -= completed
+ completed_legacy_usage[key] += completed
+ total[key] += completed
+ delta["reasoningOutputTokens"] = min(
+ delta["reasoningOutputTokens"], delta["outputTokens"]
+ )
_add_token_usage(legacy_usage, delta)
_add_token_usage(total, response_usage if response_usage is not None else legacy_usage)
+ if response_usage is None and ambiguous_legacy_cache:
+ warnings.add("token_breakdown_unavailable")
if not boundary_reached:
warnings.add("thread_ownership_unavailable")
elif result.tokens_updated_at is None and not direct_control_session:
@@ -848,6 +998,47 @@ def valid_account_rate_limit(value: object) -> bool:
return True
+def _missing_cache_fields(payload: Mapping[str, Any]) -> set[str]:
+ usage = payload["info"]["total_token_usage"]
+ missing: set[str] = set()
+ if "cached_input_tokens" not in usage:
+ missing.add("cachedInputTokens")
+ if "cache_write_input_tokens" not in usage and "cache_write_tokens" not in usage:
+ missing.add("cacheWriteInputTokens")
+ return missing
+
+
+def _uncached_input(usage: dict[str, int]) -> int:
+ return usage["inputTokens"] - usage["cachedInputTokens"] - usage["cacheWriteInputTokens"]
+
+
+def _retain_cache_baseline(
+ previous: dict[str, int], snapshot: dict[str, int], missing: set[str]
+) -> dict[str, int] | None:
+ baseline = snapshot
+ if (
+ missing
+ and snapshot["inputTokens"] >= previous["inputTokens"]
+ and snapshot["outputTokens"] >= previous["outputTokens"]
+ ):
+ baseline = {**snapshot, **{key: previous[key] for key in missing}}
+ if (
+ baseline["cachedInputTokens"] + baseline["cacheWriteInputTokens"]
+ > baseline["inputTokens"]
+ ):
+ return None
+ if (
+ baseline["inputTokens"] == previous["inputTokens"]
+ and baseline["outputTokens"] == previous["outputTokens"]
+ and (
+ baseline["cachedInputTokens"] < previous["cachedInputTokens"]
+ or baseline["cacheWriteInputTokens"] < previous["cacheWriteInputTokens"]
+ )
+ ):
+ return previous
+ return baseline
+
+
def _session_parent_thread_id(payload: Mapping[str, Any]) -> str | None:
source = payload.get("source")
if isinstance(source, dict):
diff --git a/plugins/codex-security/shared/workbench-migrations.json b/plugins/codex-security/shared/workbench-migrations.json
index 3ad24c4fb..987ff1e61 100644
--- a/plugins/codex-security/shared/workbench-migrations.json
+++ b/plugins/codex-security/shared/workbench-migrations.json
@@ -508,5 +508,14 @@
"UPDATE scans SET launch_plugin_version = json_extract(recipe_json, '$.pluginVersion')\nWHERE launch_plugin_version IS NULL AND CASE WHEN json_valid(recipe_json) THEN\n json_type(recipe_json, '$.pluginVersion') = 'text'\n AND trim(json_extract(recipe_json, '$.pluginVersion'), char(9, 10, 11, 12, 13, 32)) <> ''\nEND;",
"CREATE VIEW scan_lifecycles AS\nSELECT scans.id AS scan_id, json_object(\n 'scanId', scans.id,\n 'mode', CASE WHEN launch_kind = 'import' THEN 'import' ELSE scans.mode END,\n 'startedAt', scans.started_at,\n 'status', CASE WHEN canceled_at IS NOT NULL THEN 'canceled'\n WHEN scans.status = 'complete' THEN 'completed' ELSE scans.status END,\n 'finishedAt', COALESCE(canceled_at, completed_at),\n 'hasReportableFindings', json(CASE\n WHEN scans.status = 'complete' AND canceled_at IS NULL\n THEN (SELECT CASE WHEN reportable_findings_count > 0 THEN 'true' ELSE 'false' END\n FROM scan_progress WHERE scan_id = scans.id) END),\n 'surface', launch_surface,\n 'packageVersion', launch_package_version,\n 'pluginVersion', launch_plugin_version,\n 'mock', json(CASE WHEN launch_kind = 'mock' THEN 'true'\n WHEN launch_kind IS NOT NULL THEN 'false' END)\n) AS snapshot\nFROM scans;"
]
+ },
+ {
+ "version": 63,
+ "name": "retain unverified Deep Scan worker attempts",
+ "statements": [
+ "ALTER TABLE deep_scan_runs ADD COLUMN worker_usage_gap INTEGER NOT NULL DEFAULT 0 CHECK (worker_usage_gap IN (0, 1));",
+ "UPDATE deep_scan_runs SET worker_usage_gap = 1\nWHERE scan_id IN (\n SELECT w.scan_id FROM deep_scan_workers AS w\n WHERE w.kind IN ('discovery', 'dedup') AND w.attempt > 1\n AND w.started_at IS NOT NULL AND w.sdk_thread_id IS NULL\n AND NOT EXISTS (SELECT 1 FROM deep_scan_worker_threads AS t\n WHERE t.scan_id = w.scan_id AND t.worker_id = w.id)\n);",
+ "CREATE TRIGGER retain_unverified_deep_scan_worker_attempt\nAFTER UPDATE OF attempt ON deep_scan_workers\nWHEN NEW.attempt > OLD.attempt AND OLD.started_at IS NOT NULL\n AND OLD.sdk_thread_id IS NULL AND OLD.kind IN ('discovery', 'dedup')\nBEGIN\n UPDATE deep_scan_runs SET worker_usage_gap = 1 WHERE scan_id = OLD.scan_id;\nEND;"
+ ]
}
]
diff --git a/plugins/codex-security/tests/test_checkpoint_schema.py b/plugins/codex-security/tests/test_checkpoint_schema.py
index 5d9121c61..c66456c2d 100644
--- a/plugins/codex-security/tests/test_checkpoint_schema.py
+++ b/plugins/codex-security/tests/test_checkpoint_schema.py
@@ -59,7 +59,8 @@ def test_frozen_checkpoint_head_migration_preserves_scan_state(
if legacy_checkpoint and version == 57
else (version, name, sql)
for version, name, sql in migrations
- if version not in omitted_versions
+ if version <= 57
+ and version not in omitted_versions
and not (legacy_checkpoint and version in (54, 55, 56))
and not (legacy_checkpoint in (47, 48, 50, 52, 53) and version in (52, 53))
and not (legacy_checkpoint in (47, 48, 50) and version in (50, 51))
@@ -120,12 +121,11 @@ def test_frozen_checkpoint_head_migration_preserves_scan_state(
migrate(connection, migrations)
after = [dict(row) for row in connection.execute("SELECT * FROM scans ORDER BY id")]
for original, updated in zip(before, after, strict=True):
- retained_heads = updated.pop("retained_checkpoint_heads_json")
- assert retained_heads == original.get("retained_checkpoint_heads_json")
- original.pop("retained_checkpoint_heads_json", None)
- if "source_scopes_json" not in original:
- source_scopes = updated.pop("source_scopes_json")
- assert source_scopes is None
+ # Existing scan values survive the upgrade. Later nullable columns
+ # have no launch or recovery metadata to backfill for these rows.
+ for column in updated.keys() - original.keys():
+ added_value = updated.pop(column)
+ assert added_value is None
assert updated == original
connection.execute(
diff --git a/plugins/codex-security/tests/test_workbench_deep_scan.py b/plugins/codex-security/tests/test_workbench_deep_scan.py
index 7b44c6bd3..7210c92b7 100644
--- a/plugins/codex-security/tests/test_workbench_deep_scan.py
+++ b/plugins/codex-security/tests/test_workbench_deep_scan.py
@@ -127,6 +127,8 @@ def test_target_admission_reads_one_entry_without_looking_up_its_type(
def restore_v53_schema(state_dir: Path) -> None:
with sqlite3.connect(state_dir / "workbench.sqlite3") as connection:
+ connection.execute("DROP TRIGGER retain_unverified_deep_scan_worker_attempt")
+ connection.execute("ALTER TABLE deep_scan_runs DROP COLUMN worker_usage_gap")
connection.execute("DROP TRIGGER classify_legacy_scan_recipe")
connection.execute("DROP VIEW scan_lifecycles")
connection.execute("ALTER TABLE scans DROP COLUMN launch_kind")
diff --git a/plugins/codex-security/tests/test_workbench_scan_usage.py b/plugins/codex-security/tests/test_workbench_scan_usage.py
index 22343b250..bc51ee690 100644
--- a/plugins/codex-security/tests/test_workbench_scan_usage.py
+++ b/plugins/codex-security/tests/test_workbench_scan_usage.py
@@ -923,6 +923,193 @@ def test_completion_includes_cached_and_cache_write_tokens(
)
+ "cache_field", ["cached_input_tokens", "cache_write_input_tokens", "cache_write_tokens"]
+)
+ ("snapshots", "expected_input", "expected_cache"),
+ [
+ ([(100, 50), (100, None), (100, 50)], 100, 50),
+ ([(100, 100), (200, None), (200, 100)], 200, 100),
+ ([(100, 40), (200, None), (300, 60)], 300, 60),
+ ([(100, 40), (20, None), (100, 20)], 200, 60),
+ ([(100, 40), (200, 20), (300, 30)], 300, 70),
+ ([(100, None), (100, 50)], 100, 50),
+ ],
+ ids=[
+ "same-total",
+ "increasing",
+ "new-writes",
+ "epoch-reset",
+ "explicit-decrease",
+ "initial-omission",
+ ],
+)
+def test_completion_retains_cache_baseline_across_omissions(
+ tmp_path: Path,
+ cache_field: str,
+ snapshots: list[tuple[int, int | None]],
+ expected_input: int,
+ expected_cache: int,
+) -> None:
+ fixture = _start_scan(tmp_path)
+ counted = fixture.started_at + timedelta(microseconds=1)
+ events = []
+ is_cache_read = cache_field == "cached_input_tokens"
+ for input_tokens, cache_tokens in snapshots:
+ event = _token_event(counted, input_tokens, 0)
+ reported = event["payload"]["info"]["total_token_usage"]
+ reported.pop("cached_input_tokens" if is_cache_read else "cache_write_input_tokens")
+ if cache_tokens is not None:
+ reported[cache_field] = cache_tokens
+ events.append(event)
+ parent = _rollout(tmp_path, "scan-parent", events)
+ _state_graph(fixture.environment, {"scan-parent": parent}, [])
+
+ usage = _complete_scan(fixture)["scan"]["usage"]
+
+ assert (
+ usage.items()
+ >= {
+ "coverage": "complete",
+ "source": "codex_rollout",
+ **_counts(
+ expected_input,
+ expected_cache if is_cache_read else 0,
+ 0,
+ cache_write_input_tokens=0 if is_cache_read else expected_cache,
+ ),
+ "threadCount": 1,
+ }.items()
+ )
+
+
[email protected]("recovered", [False, True])
+def test_inconsistent_partial_cache_snapshot_cannot_establish_a_baseline(
+ scan_usage, tmp_path: Path, recovered: bool
+) -> None:
+ started = datetime.fromisoformat("2026-01-01T00:00:00+00:00")
+ initial = _token_event(started, 100, 0, cached_input_tokens=80)
+ partial = _token_event(started, 100, 0)
+ partial_usage = partial["payload"]["info"]["total_token_usage"]
+ del partial_usage["cached_input_tokens"]
+ partial_usage["cache_write_input_tokens"] = 50
+ events = [initial, partial]
+ if recovered:
+ latest = _token_event(started, 140, 0, cached_input_tokens=80)
+ latest["payload"]["info"]["total_token_usage"]["cache_write_input_tokens"] = 60
+ events.append(latest)
+ result = _measure_rollout(
+ scan_usage, _rollout(tmp_path, "scan-parent", events), started, started
+ )
+ assert result.warnings == {"token_breakdown_unavailable"}
+ assert result.tokens == _counts(
+ 140 if recovered else 100, 80, 0, cache_write_input_tokens=60 if recovered else 0
+ )
+
+
[email protected]("category", ["cached_input_tokens", "cache_write_input_tokens"])
[email protected]("missing", [None, "refined", "other"])
[email protected]("new_input", [0, 1000])
+def test_late_cache_classification_only_excludes_ambiguous_categories(
+ tmp_path: Path, category: str, missing: str | None, new_input: int
+) -> None:
+ fixture = _start_scan(tmp_path)
+ counted = fixture.started_at + timedelta(microseconds=1)
+ prefix = _token_event(fixture.started_at - timedelta(seconds=1), 1000, 0)
+ owned = _token_event(counted, 2000, 0)
+ refined = _token_event(counted, 2000 + new_input, 0)
+ if missing is not None:
+ other = (
+ "cache_write_input_tokens"
+ if category == "cached_input_tokens"
+ else "cached_input_tokens"
+ )
+ absent = category if missing == "refined" else other
+ for event in (prefix, owned, refined):
+ del event["payload"]["info"]["total_token_usage"][absent]
+ refined["payload"]["info"]["total_token_usage"][category] = 1000
+ _state_graph(
+ fixture.environment,
+ {
+ "scan-parent": _rollout(tmp_path, "scan-parent", [prefix, owned, refined]),
+ "child": _rollout(
+ tmp_path, "child", [_token_event(counted, 30, 5)], parent_thread_id="scan-parent"
+ ),
+ },
+ [("scan-parent", "child")],
+ )
+ usage = fixture.command("read-scan-usage", "--thread-id", "scan-parent")
+ ambiguous = missing == "refined"
+ assert usage["coverage"] == ("partial" if ambiguous else "complete")
+ assert usage["totalTokens"] == (35 if ambiguous else 1035 + new_input)
+ assert usage["byRole"]["parent"]["threadCount"] == (0 if ambiguous else 1)
+ assert usage.get("warnings", []) == (["token_breakdown_unavailable"] if ambiguous else [])
+
+
[email protected]("previous_native", [False, True])
[email protected]("current_native", [False, True])
+def test_legacy_cache_refinement_survives_turn_boundaries(
+ scan_usage, tmp_path: Path, previous_native: bool, current_native: bool
+) -> None:
+ started = datetime.fromisoformat("2026-01-01T00:00:00+00:00")
+ initial = _token_event(started, 100, 10)
+ initial["payload"]["info"]["total_token_usage"].pop("cache_write_input_tokens")
+ refined = _token_event(started, 100, 10, cached_input_tokens=20)
+ refined["payload"]["info"]["total_token_usage"]["cache_write_input_tokens"] = 30
+ later = _token_event(started, 150, 20, cached_input_tokens=20)
+ later["payload"]["info"]["total_token_usage"]["cache_write_input_tokens"] = 30
+ events = [
+ _event(started, "event_msg", {"type": "task_started", "turn_id": "previous"}),
+ initial,
+ ]
+ if previous_native:
+ events.append(
+ _response_event(
+ started,
+ "scan-parent",
+ "previous",
+ 100,
+ 10,
+ turn_id="previous",
+ cached_input_tokens=7,
+ )
+ )
+ events.extend(
+ [
+ _event(started, "event_msg", {"type": "task_started", "turn_id": "current"}),
+ refined,
+ ]
+ )
+ if current_native:
+ events.append(
+ _response_event(
+ started,
+ "scan-parent",
+ "current",
+ 50,
+ 10,
+ turn_id="current",
+ cached_input_tokens=5,
+ )
+ )
+ events.append(later)
+ events.extend(
+ _event(started, "event_msg", {"type": "task_complete", "turn_id": turn})
+ for turn in ("previous", "current")
+ )
+ parent = _rollout(tmp_path, "scan-parent", events)
+ result = _measure_rollout(scan_usage, parent, started, started)
+
+ assert result.tokens == _counts(
+ 150,
+ (7 if previous_native else 20) + (5 if current_native else 0),
+ 20,
+ cache_write_input_tokens=0 if previous_native else 30,
+ )
+ assert result.warnings == set()
+
+
def test_completion_excludes_separately_inherited_worker_snapshots(tmp_path: Path) -> None:
fixture = _start_scan(tmp_path)
counted = fixture.started_at + timedelta(microseconds=1)
@@ -1231,6 +1418,7 @@ def test_completion_counts_deep_worker_retries_and_descendants(tmp_path: Path) -
fixture.environment,
{
"scan-parent": _rollout(tmp_path, "scan-parent", [_token_event(counted, 10, 3)]),
+ "comparison": _rollout(tmp_path, "comparison", [_token_event(counted, 50, 5)]),
"sdk-worker": _rollout(tmp_path, "sdk-worker", [_token_event(counted, 20, 5)]),
"sdk-child": _rollout(
tmp_path,
@@ -1242,14 +1430,19 @@ def test_completion_counts_deep_worker_retries_and_descendants(tmp_path: Path) -
},
[("sdk-worker", "sdk-child")],
)
+ with sqlite3.connect(Path(fixture.environment["CODEX_SQLITE_HOME"]) / "state_5.sqlite") as db:
+ db.execute(
+ "UPDATE threads SET cwd = ?, created_at = ? WHERE id = 'comparison'",
+ (str(fixture.scan_dir / "artifacts" / "deep_discovery"), int(counted.timestamp())),
+ )
usage = _complete_scan(fixture)["scan"]["usage"]
assert (
usage.items()
>= {
"coverage": "complete",
"source": "codex_rollout",
- **_counts(67, 0, 13),
- "threadCount": 4,
+ **_counts(117, 0, 18),
+ "threadCount": 5,
}.items()
)
@@ -1498,12 +1691,149 @@ def test_metadata_only_deep_owner_requires_direct_control_originator(
}
-def test_usage_has_no_separate_workbench_command(workbench_api, monkeypatch, capsys) -> None:
- monkeypatch.setattr(sys, "argv", ["workbench_db.py", "get-scan-usage"])
- with pytest.raises(SystemExit) as rejected:
- workbench_api["parse_args"]("workbench")
- assert rejected.value.code == 2
- assert "invalid choice: 'get-scan-usage'" in capsys.readouterr().err
+def test_budget_keeps_measured_totals_when_a_started_worker_has_no_thread(tmp_path: Path) -> None:
+ fixture = _start_scan(tmp_path, mode="deep")
+ counted = fixture.started_at + timedelta(microseconds=1)
+ fixture.write_parent_rollout([_token_event(counted, 100, 10)])
+ artifact = fixture.scan_dir / "artifacts" / "worker"
+ artifact.mkdir(parents=True)
+ prompt = artifact / "prompt.md"
+ prompt.write_text("Review the fixture.\n", encoding="utf-8")
+ upsert_deep_worker(
+ fixture.state_dir,
+ fixture.scan_id,
+ str(uuid.uuid4()),
+ "discovery",
+ "running",
+ str(prompt),
+ str(artifact),
+ "--attempt",
+ "1",
+ environment=fixture.environment,
+ )
+ usage = fixture.command("read-scan-usage", "--thread-id", "scan-parent")
+ assert usage["coverage"] == "partial"
+ assert usage["totalTokens"] == 110
+ assert "worker_thread_unavailable" in usage["warnings"]
+
+
[email protected]("resume", [False, True])
+def test_budget_distinguishes_fresh_retry_from_resumed_worker(tmp_path: Path, resume: bool) -> None:
+ fixture = _start_scan(tmp_path, mode="deep")
+ counted = fixture.started_at + timedelta(microseconds=1)
+ worker = str(uuid.uuid4())
+ artifact = fixture.scan_dir / "artifacts" / "worker"
+ artifact.mkdir(parents=True)
+ prompt = artifact / "prompt.md"
+ prompt.write_text("Review the fixture.", encoding="utf-8")
+ parent = _rollout(tmp_path, "scan-parent", [_token_event(counted, 10, 0)])
+ earlier = _rollout(tmp_path, "earlier", [_token_event(counted, 100, 0)])
+ later = _rollout(tmp_path, "later", [_token_event(counted, 5, 0)])
+ _state_graph(
+ fixture.environment, {"scan-parent": parent, "earlier": earlier, "later": later}, []
+ )
+ with sqlite3.connect(Path(fixture.environment["CODEX_SQLITE_HOME"]) / "state_5.sqlite") as db:
+ db.execute(
+ "UPDATE threads SET cwd = ?, created_at = ? WHERE id = 'earlier'",
+ (str(artifact), int(counted.timestamp())),
+ )
+
+ def running(attempt: str, *thread: str) -> None:
+ upsert_deep_worker(
+ fixture.state_dir,
+ fixture.scan_id,
+ worker,
+ "discovery",
+ "running",
+ str(prompt),
+ str(artifact),
+ "--attempt",
+ attempt,
+ *thread,
+ environment=fixture.environment,
+ )
+
+ running("1", "--sdk-thread-id", "earlier")
+ running("2", *(["--sdk-thread-id", "earlier"] if resume else []))
+ # Repeat an update without the optional ID, as the worker runner does after an error.
+ running("2")
+
+ def assert_usage(total: int) -> None:
+ usage = fixture.command("read-scan-usage", "--thread-id", "scan-parent")
+ assert usage["coverage"] == ("complete" if resume else "partial")
+ assert usage["totalTokens"] == total
+ assert ("worker_thread_unavailable" in usage.get("warnings", [])) == (not resume)
+
+ assert_usage(110)
+ running("3", "--sdk-thread-id", "later")
+ assert_usage(115)
+
+
[email protected]("truncated", [False, True])
[email protected]("indexed_archive", [False, True])
+def test_budget_counts_compressed_comparison_or_reports_partial_usage(
+ tmp_path: Path, truncated: bool, indexed_archive: bool
+) -> None:
+ try:
+ from compression import zstd
+ except ImportError:
+ zstd = pytest.importorskip("backports.zstd")
+ fixture = _start_scan(tmp_path, mode="deep")
+ counted = fixture.started_at + timedelta(microseconds=1)
+ parent = _rollout(tmp_path, "scan-parent", [_token_event(counted, 100, 10)])
+ comparison = _rollout(tmp_path, "comparison", [_token_event(counted, 10, 5)])
+ archive = comparison.with_suffix(".jsonl.zst")
+ frames = zstd.compress(comparison.read_bytes()) + zstd.compress(b"")
+ archive.write_bytes(frames[:-1] if truncated else frames)
+ comparison.unlink()
+ _state_graph(
+ fixture.environment,
+ {"scan-parent": parent, "comparison": archive if indexed_archive else comparison},
+ [],
+ )
+ with sqlite3.connect(Path(fixture.environment["CODEX_SQLITE_HOME"]) / "state_5.sqlite") as db:
+ db.execute(
+ "UPDATE threads SET cwd = ?, created_at = ? WHERE id = 'comparison'",
+ (str(fixture.scan_dir / "artifacts" / "deep_discovery"), int(counted.timestamp())),
+ )
+ usage = fixture.command("read-scan-usage", "--thread-id", "scan-parent")
+ assert usage["coverage"] == ("partial" if truncated else "complete")
+ assert usage["totalTokens"] == (110 if truncated else 125)
+
+
[email protected]("missing_child", [False, True])
+def test_budget_usage_includes_final_receipts_and_validation_after_completion(
+ tmp_path: Path, missing_child: bool
+) -> None:
+ fixture = _start_scan(tmp_path)
+ stored = _complete_scan(fixture)["scan"]["usage"]
+ after = datetime.now(fixture.started_at.tzinfo)
+ _state_graph(
+ fixture.environment,
+ {
+ "scan-parent": _rollout(tmp_path, "scan-parent", [_token_event(after, 8, 2)]),
+ "validation": _rollout(tmp_path, "validation", [_token_event(after, 40, 10)]),
+ "validation-child": (
+ tmp_path / "missing.jsonl"
+ if missing_child
+ else _rollout(
+ tmp_path,
+ "validation-child",
+ [_token_event(after, 20, 5)],
+ parent_thread_id="validation",
+ )
+ ),
+ },
+ [("validation", "validation-child")],
+ )
+ usage = fixture.command(
+ "read-scan-usage", "--thread-id", "scan-parent", "--validation-thread-id", "validation"
+ )
+ assert usage["coverage"] == ("partial" if missing_child else "complete")
+ assert usage["totalTokens"] == (60 if missing_child else 85)
+ assert usage["byRole"]["parent"]["threadCount"] == 2
+ assert fixture.command("get-scan")["scan"]["usage"] == stored
@pytest.mark.parametrize("native", [False, True])
@@ -1995,7 +2325,7 @@ def test_worker_discovery_matches_platform_path_spelling(
state_database,
["current-worker"],
warnings,
- worker_directories={directory},
+ worker_directories={directory: False},
started_at=started,
completed_at=started + timedelta(seconds=1),
)
diff --git a/plugins/codex-security/tests/test_workbench_setup_and_migrations.py b/plugins/codex-security/tests/test_workbench_setup_and_migrations.py
index 69566b80a..426494965 100644
--- a/plugins/codex-security/tests/test_workbench_setup_and_migrations.py
+++ b/plugins/codex-security/tests/test_workbench_setup_and_migrations.py
@@ -107,6 +107,7 @@ EXPECTED_MIGRATIONS = [
(60, "record classification rubric provenance"),
(61, "record scan launch attribution"),
(62, "project scan lifecycle snapshots"),
+ (63, "retain unverified Deep Scan worker attempts"),
]
diff --git a/sdk/typescript/README.md b/sdk/typescript/README.md
index 5652a2193..8e4608cec 100644
--- a/sdk/typescript/README.md
+++ b/sdk/typescript/README.md
@@ -477,7 +477,8 @@ coordinator has finished.
Costs estimate API-equivalent model usage, not your bill or ChatGPT subscription
allowance. Use `cost.estimatedUsdRange` for reporting. `maxCostUsd` uses the
short-context estimate; in-flight requests can exceed it. Post-scan prompts run
-outside that limit. Matching earlier findings can also make model calls.
+outside that limit. With a cost limit, completing the scan requires verifiable
+usage for the scan and its workers. Matching earlier findings can also make model calls.
See [progress and cost](docs/cli.md#progress-and-cost) for accounting and budget callbacks.
### Validate an existing finding
diff --git a/sdk/typescript/docs/cli.md b/sdk/typescript/docs/cli.md
index 589a3fc96..c41b51bcb 100644
--- a/sdk/typescript/docs/cli.md
+++ b/sdk/typescript/docs/cli.md
@@ -1159,7 +1159,14 @@ attempt. Post-scan prompts run after cost tracking and are outside this limit.
Automatic history matching gets at most one extra call with a limit; if more
work is needed, the scan is preserved and you can run `scans match --all`.
-When Deep discovery has finished at a cost stop, the scan returns a sealed
+A scan with a cost limit requires complete token usage for its recorded scan,
+worker, and custom validation sessions before the SDK returns a completed result.
+Verifying compressed `.jsonl.zst` sessions requires Python 3.14 or later, or
+`backports.zstd` installed in the selected Python environment.
+Missing or unreadable usage fails budget verification. Without a limit, usage
+reporting remains best effort.
+
+When Deep discovery has finished at a cost stop and usage is verified, the scan returns a sealed
report and lists unvalidated candidates as follow-up work. Reaching a configured
limit with a valid finalized report returns `0` by default, or `1` if findings
meet a configured failure threshold.
diff --git a/sdk/typescript/src/api.ts b/sdk/typescript/src/api.ts
index 55e226bd4..81ff82efd 100644
--- a/sdk/typescript/src/api.ts
+++ b/sdk/typescript/src/api.ts
@@ -102,6 +102,7 @@ import {
} from "./config.js";
import {
estimateScanCost,
+ readScanBudgetUsage,
ScanCostTracker,
type ScanCost,
type ParentProgressSource,
@@ -2043,6 +2044,7 @@ export class CodexSecurity {
status: "pending" as "pending" | "running" | "complete",
};
let completionCost: ScanCost | null = null;
+ let validationThreadId: string | undefined;
let nativeTurnFailure: string | undefined;
let scanTurnStatus: "in_progress" | "completed" | "failed" | null = null;
let budgetRecovery: {
@@ -2281,9 +2283,7 @@ export class CodexSecurity {
);
const sqliteHome = workerRuntimeConfig["sqlite_home"];
const sqliteEnvironment: Record<string, string> =
- mode === "deep" && typeof sqliteHome === "string"
- ? { CODEX_SQLITE_HOME: sqliteHome }
- : {};
+ typeof sqliteHome === "string" ? { CODEX_SQLITE_HOME: sqliteHome } : {};
const workerSnapshot: JsonObject = {
...workerRuntimeConfig,
responses_api_metadata: codexSecurityRequestContext(effectiveConfig, {
@@ -2457,11 +2457,7 @@ export class CodexSecurity {
notifyObserver(options, "onWorkerStatus")(status);
};
const reportedInaccessibleSessionLogs = new Set<string>();
- const reportTrackingError = (error: unknown): void => {
- if (options.maxCostUsd !== undefined) {
- costAbortController.abort(error);
- return;
- }
+ const warnTrackingError = (error: unknown): void => {
if (
isRecord(error) &&
(error["code"] === "EACCES" || error["code"] === "EPERM") &&
@@ -2477,12 +2473,35 @@ export class CodexSecurity {
"onWarning",
)(`Could not track scan activity: ${errorMessage(error)}`);
};
+ const reportTrackingError = (error: unknown): void => {
+ if (options.maxCostUsd !== undefined) costAbortController.abort(error);
+ else warnTrackingError(error);
+ };
const tracker = new ScanCostTracker({
+ onObservationError: warnTrackingError,
codexHome: runtime.codexHome,
model,
repository: repo,
scanDirectory: scanDir,
maxCostUsd: options.maxCostUsd,
+ readBudgetUsage:
+ options.maxCostUsd === undefined
+ ? undefined
+ : (threadId) =>
+ readScanBudgetUsage(
+ (args) =>
+ workbench(
+ {
+ ...workbenchOptions,
+ signal: signal.aborted ? undefined : signal,
+ },
+ args,
+ ),
+ scanId,
+ threadId,
+ validationThreadId,
+ directDeepScan,
+ ),
onUsage:
options.onUsage === undefined
? undefined
@@ -2733,6 +2752,7 @@ export class CodexSecurity {
pluginRoot: runtime.plugin.pluginRoot,
environment: {
...environmentWithGit(git.environment, git),
+ CODEX_HOME: runtime.codexHome,
...sqliteEnvironment,
CODEX_SECURITY_STATE_DIR: stateDirectory,
},
@@ -2808,7 +2828,7 @@ export class CodexSecurity {
});
// The registered recipe now owns the private snapshot, including after completion.
savedProviderProfile = undefined;
- const scanId = registration["scanId"];
+ const registeredScanId = registration["scanId"];
const resumeThreadId =
options.resumeScanId === undefined
? undefined
@@ -2816,7 +2836,7 @@ export class CodexSecurity {
if (options.resumeScanId !== undefined) {
const savedRecipe = registration["recipe"];
if (
- scanId !== options.resumeScanId ||
+ registeredScanId !== options.resumeScanId ||
!isRecord(savedRecipe) ||
savedRecipe["repository"] !== repo ||
typeof resumeThreadId !== "string" ||
@@ -2837,7 +2857,7 @@ export class CodexSecurity {
savedSession.workingDirectory !== scanDir
) {
throw new CodexSecurityError(
- `The original Codex session for scan ${scanId} is unavailable. Restore its session logs in the original Codex Security state directory before resuming.`,
+ `The original Codex session for scan ${registeredScanId} is unavailable. Restore its session logs in the original Codex Security state directory before resuming.`,
);
}
if (typeof registration["sealedProducerVersion"] === "string") {
@@ -2882,7 +2902,7 @@ export class CodexSecurity {
: undefined;
const registeredRevision = registration["targetRevision"];
if (
- typeof scanId !== "string" ||
+ typeof registeredScanId !== "string" ||
typeof targetId !== "string" ||
registration["scanDir"] !== scanDir ||
typeof targetKind !== "string" ||
@@ -2902,6 +2922,7 @@ export class CodexSecurity {
"The Codex Security workbench returned an invalid scan registration.",
);
}
+ const scanId = registeredScanId;
const targetRevision =
registeredRevision === "unversioned" ? null : registeredRevision;
const registeredFileCount = registration["scopeFileCount"];
@@ -3375,6 +3396,13 @@ export class CodexSecurity {
outputSchema,
})
).events,
+ onEvent: (event) => {
+ if (
+ event.type === "thread.started" &&
+ typeof event["thread_id"] === "string"
+ )
+ validationThreadId = event["thread_id"];
+ },
onReconnect: (message, attempts) =>
notifyObserver(options, "onReconnect")(
...attempts,
@@ -3388,6 +3416,13 @@ export class CodexSecurity {
"The custom validation turn did not complete.",
);
budgetAbortController.abort();
+ if (turn.threadId === null && maxCostUsd !== undefined) {
+ runPostScan = null;
+ throw new CodexSecurityError(
+ "Could not verify the cost of the custom validation turn.",
+ );
+ }
+ validationThreadId = turn.threadId ?? undefined;
tracker.recordUsage(turn.usage, turn.threadId);
await tracker.refresh().catch(reportTrackingError);
checkOpen();
@@ -3398,17 +3433,18 @@ export class CodexSecurity {
}
budgetAbortController.abort();
const snapshot = await tracker.stop(usage).catch((error: unknown) => {
- if (options.maxCostUsd !== undefined) throw error;
+ if (options.maxCostUsd !== undefined) {
+ runPostScan = null;
+ throw error;
+ }
reportTrackingError(error);
return { usage, cost: estimateScanCost(model, usage) };
});
throwIfAborted(signal, scanDir);
- if (options.maxCostUsd !== undefined && snapshot.cost === null) {
- notifyObserver(
- options,
- "onWarning",
- )(
- "Scan completed, but its cost limit could not be verified because model pricing or token usage is unavailable.",
+ if (maxCostUsd !== undefined && snapshot.cost === null) {
+ runPostScan = null;
+ throw new IncompleteScanError(
+ "Could not verify the requested scan cost limit because scan-owned token usage is incomplete.",
);
}
completionCost = snapshot.cost;
@@ -3724,6 +3760,10 @@ export class CodexSecurity {
}
if (
failure instanceof ScanCostLimitExceededError &&
+ snapshot?.cost &&
+ snapshot.cost.estimatedUsd > failure.maxCostUsd &&
+ (customValidation.status !== "running" ||
+ validationThreadId !== undefined) &&
budgetRecovery !== null &&
budgetRecovery.threadId !== null &&
activeScan !== null &&
@@ -3737,7 +3777,7 @@ export class CodexSecurity {
"--scan-id",
activeScan.id,
"--cost-json",
- JSON.stringify(snapshot?.cost ?? failure.cost),
+ JSON.stringify(snapshot.cost),
`--message=${failure.message}`,
],
);
@@ -3755,7 +3795,7 @@ export class CodexSecurity {
{
status: "completed",
model: budgetRecovery.model,
- usage: snapshot?.usage ?? null,
+ usage: snapshot.usage,
},
budgetRecovery.threadId,
scanDir,
@@ -3849,7 +3889,9 @@ export class CodexSecurity {
: priorTurnFailure === undefined &&
explicitlyCanceled(callerCancellation),
priorTurnFailure ?? failure,
- snapshot?.cost,
+ failure instanceof ScanCostLimitExceededError
+ ? failure.cost
+ : snapshot?.cost,
);
activeScan = null;
} catch {}
diff --git a/sdk/typescript/src/cost.ts b/sdk/typescript/src/cost.ts
index 20b58e365..0de6591c4 100644
--- a/sdk/typescript/src/cost.ts
+++ b/sdk/typescript/src/cost.ts
@@ -1,4 +1,6 @@
import { parseJson } from "./value.js";
+import type { JsonObject } from "./config.js";
+import { workbenchArgs } from "./workbench-arguments.js";
import { createHash } from "node:crypto";
import { open, readdir, stat } from "node:fs/promises";
import { join } from "node:path";
@@ -30,6 +32,47 @@ import {
export { estimateScanCost, formatUsd, type ScanCost } from "./cost-model.js";
+export async function readScanBudgetUsage(
+ workbench: (args: readonly string[]) => Promise<JsonObject>,
+ scanId: string,
+ threadId: string,
+ validationThreadId?: string,
+ requireWorkerUsage = false,
+) {
+ const result = await workbench(
+ workbenchArgs("read-scan-usage", { scanId, threadId, validationThreadId }),
+ );
+ const counts = {
+ input_tokens: result["inputTokens"],
+ cached_input_tokens: result["cachedInputTokens"],
+ cache_write_input_tokens: result["cacheWriteInputTokens"],
+ output_tokens: result["outputTokens"],
+ reasoning_output_tokens: result["reasoningOutputTokens"],
+ };
+ const usage = Object.values(counts).every(Number.isSafeInteger)
+ ? tokenUsage(counts)
+ : null;
+ const roles = result["byRole"];
+ const workers = isRecord(roles) ? roles["workers"] : undefined;
+ const coverage = result["coverage"];
+ if (
+ (coverage !== "complete" && coverage !== "partial") ||
+ usage === null ||
+ usage.total_tokens !== result["totalTokens"]
+ )
+ return { usage: null, complete: false };
+
+ const hasWorkers =
+ isRecord(workers) &&
+ typeof workers["threadCount"] === "number" &&
+ workers["threadCount"] > 0;
+ // The workbench sums known cache writes but does not record which receipts omitted them.
+ return {
+ usage: { ...usage, cache_write_input_tokens_reported: false },
+ complete: coverage === "complete" && (!requireWorkerUsage || hasWorkers),
+ };
+}
+
export interface ScanAccountRateLimitWindow {
readonly usedPercent: number;
readonly windowMinutes: number | null;
@@ -244,6 +287,9 @@ interface ScanCostTrackerOptions {
repository?: string;
scanDirectory?: string;
maxCostUsd?: number;
+ readBudgetUsage?: (
+ threadId: string,
+ ) => ReturnType<typeof readScanBudgetUsage>;
expectedFilesTotal?: number;
/** Incomplete costs are measured subtotals, usable for spending limits only. */
onCost?: (cost: Readonly<ScanCost>, complete: boolean) => void;
@@ -254,6 +300,7 @@ interface ScanCostTrackerOptions {
onSessionEvent?: (event: ScanSessionEvent) => void;
onWorkerEvent?: (event: ScanWorkerEvent) => void;
onError?: (error: unknown) => void;
+ onObservationError?: (error: unknown) => void;
}
interface ScanCostSnapshot {
@@ -316,6 +363,7 @@ function createSessionUsage(observeUsage: boolean) {
export class ScanCostTracker {
readonly #options: ScanCostTrackerOptions;
+ #lastBudgetPoll = -Infinity;
readonly #sessions = new Map<string, SessionUsage>();
readonly #receipts = new Map<string, ScanTokenUsage | null>();
readonly #workers = new Map<string, number>();
@@ -2219,7 +2267,7 @@ export class ScanCostTracker {
return;
}
polling = true;
- void this.refresh()
+ void this.refresh(true)
.catch((error: unknown) => {
this.#options.onError?.(error);
})
@@ -2236,9 +2284,28 @@ export class ScanCostTracker {
poll();
}
- public async refresh(): Promise<ScanCostSnapshot> {
+ public async refresh(polling = false): Promise<ScanCostSnapshot> {
const update = this.#pending.then(async () => {
- await this.#readSessions();
+ const { readBudgetUsage } = this.#options;
+ if (readBudgetUsage === undefined) return this.#readSessions();
+ if (this.#threadId === null) return;
+ if (
+ this.#options.onActivity ||
+ this.#options.onProgress ||
+ this.#options.onWorkerEvent ||
+ this.#options.onSessionEvent ||
+ this.#options.onUsageObservation
+ ) {
+ await this.#readSessions().catch((error) =>
+ this.#options.onObservationError?.(error),
+ );
+ }
+ // Reading the indexed graph is more expensive than tailing session activity.
+ // Always get fresh usage when stopping, even after a recent live poll.
+ if (polling && performance.now() - this.#lastBudgetPoll < 1_000) return;
+ const measured = await readBudgetUsage(this.#threadId);
+ this.#lastBudgetPoll = performance.now();
+ this.#updateCost(measured.usage, measured.complete);
});
this.#pending = update.catch(() => {});
await update;
@@ -2254,7 +2321,11 @@ export class ScanCostTracker {
} finally {
this.#observingWorkers = false;
}
- if (this.#receipts.size > 0 || this.#snapshot.usage !== null)
+ if (
+ this.#options.readBudgetUsage ||
+ this.#receipts.size > 0 ||
+ this.#snapshot.usage !== null
+ )
return this.#snapshot;
const cost = estimateScanCost(this.#options.model, fallbackUsage);
this.#snapshot = { usage: fallbackUsage ?? null, cost };
@@ -2486,6 +2557,11 @@ export class ScanCostTracker {
usage = addTokenUsage(usage, value);
}
if (observeUsage) this.#reportUsageObservation(usages, complete);
+ if (this.#options.readBudgetUsage === undefined)
+ this.#updateCost(usage, complete);
+ }
+
+ #updateCost(usage: ScanTokenUsage | null, complete: boolean): void {
if (!complete) this.#snapshot = { usage: null, cost: null };
if (usage === null) return;
const cost = estimateScanCost(this.#options.model, usage);
diff --git a/sdk/typescript/tests-ts/api-usage.test.ts b/sdk/typescript/tests-ts/api-usage.test.ts
index f2c5f15e5..a7f9b9417 100644
--- a/sdk/typescript/tests-ts/api-usage.test.ts
+++ b/sdk/typescript/tests-ts/api-usage.test.ts
@@ -4,17 +4,26 @@ import { appendFile, mkdir } from "node:fs/promises";
import { join } from "node:path";
import { setImmediate } from "node:timers/promises";
import type { ThreadEvent } from "@openai/codex-sdk";
-import { ScanCostTracker } from "../src/cost.js";
+import { readScanBudgetUsage, ScanCostTracker } from "../src/cost.js";
import { ScanCostLimitExceededError } from "../src/errors.js";
import { copyCompletedScan } from "./plugin-root.js";
import {
+ completedCodex,
completedEvents,
runEvents,
scanRuntimeDependencies,
} from "./support/api-events.js";
-import { mockWorkbench, TestClient } from "./support/api-client.js";
+import {
+ measuredScanUsage,
+ mockWorkbench,
+ TestClient,
+} from "./support/api-client.js";
import { createApiTestFixtures } from "./support/temporary-directories.js";
-import { writeSession } from "./support/usage-rollout.js";
+import {
+ ownedPythonUsage,
+ ownedSdkUsage,
+ writeSession,
+} from "./support/usage-rollout.js";
const { temporaryDirectory, cleanup } = createApiTestFixtures();
afterEach(cleanup);
@@ -81,8 +90,9 @@ test.each([false, true])(
parent: "scan-thread",
},
);
+ let measured = raiseLimit ? 900 : 3_000;
const parent = await writeSession(codexHome, "scan-thread", {
- input_tokens: raiseLimit ? 900 : 3_000,
+ input_tokens: measured,
output_tokens: 0,
});
const limitSaved = Promise.withResolvers<void>();
@@ -92,6 +102,9 @@ test.each([false, true])(
const client = TestClient.withDependencies({
...scanRuntimeDependencies(codexHome, scanDir),
runWorkbench: async (_options, args, input) => {
+ if (args[0] === "read-scan-usage") {
+ return { ...measuredScanUsage(measured, 0, 0), coverage: "partial" };
+ }
if (args[0] === "set-scan-cost-limit") limitSaved.resolve();
return mockWorkbench(args, input);
},
@@ -105,6 +118,7 @@ test.each([false, true])(
await limitSaved.promise;
// Resume after the caller adopts the saved limit.
await setImmediate();
+ measured = 3_000;
await appendFile(
parent,
JSON.stringify({
@@ -152,3 +166,108 @@ test.each([false, true])(
}
},
);
+
+test.each([false, true])(
+ "completes with an unmeasured worker only when no budget was requested (budgeted=%p)",
+ async (budgeted) => {
+ const root = await temporaryDirectory();
+ const repository = join(root, "repository");
+ const codexHome = join(root, "codex-home");
+ const scanDir = join(root, "scan");
+ await mkdir(repository);
+ await writeSession(codexHome, "worker", {}, { parent: "thread-1" });
+ const commands: string[] = [];
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ createCodex: completedCodex(root),
+ runWorkbench: async (_options, args, input) => {
+ commands.push(args[0]!);
+ if (args[0] === "read-scan-usage") {
+ expect(args).toEqual([
+ "read-scan-usage",
+ "--scan-id",
+ "scan_example_001",
+ "--thread-id",
+ "thread-1",
+ ]);
+ return { coverage: "partial", missingThreadCount: 1 };
+ }
+ return mockWorkbench(args, input);
+ },
+ });
+ try {
+ // The completed parent supplies a receipt; its worker supplies none.
+ const run = client.run(repository, budgeted ? { maxCostUsd: 1 } : {});
+ if (budgeted) {
+ await expect(run).rejects.toThrow(/cost limit|usage/i);
+ expect(commands).not.toContain("prepare-scan-completion");
+ expect(commands).toContain("fail-scan");
+ } else {
+ expect((await run).cost).toBeNull();
+ }
+ expect(commands.includes("complete-scan")).toBe(!budgeted);
+ } finally {
+ await client.close();
+ }
+ },
+);
+
+test("a direct scan needs measured workers in addition to its control thread", async () => {
+ let workerCount = 0;
+ const workbench = async () => ({
+ ...ownedPythonUsage,
+ coverage: "complete",
+ byRole: { workers: { threadCount: workerCount } },
+ });
+ const read = () =>
+ readScanBudgetUsage(workbench, "scan", "controller", undefined, true);
+ expect((await read()).complete).toBe(false);
+ workerCount = 1;
+ expect(await read()).toEqual({
+ complete: true,
+ usage: { ...ownedSdkUsage, cache_write_input_tokens_reported: false },
+ });
+});
+
+test("a worker-shaped directory alone cannot exhaust a scan budget", async () => {
+ const root = await temporaryDirectory();
+ const repository = join(root, "repository");
+ const scanDir = join(root, "scan");
+ const codexHome = join(root, "codex-home");
+ await mkdir(repository);
+ await writeSession(
+ codexHome,
+ "thread-1",
+ { input_tokens: 10, output_tokens: 3 },
+ {
+ cwd: scanDir,
+ timestamp: "2026-07-26T10:00:00Z",
+ },
+ );
+ await writeSession(
+ codexHome,
+ "unrelated",
+ { input_tokens: 1_000_000, output_tokens: 0 },
+ {
+ cwd: join(
+ scanDir,
+ "artifacts",
+ "deep_discovery",
+ "workers",
+ "other",
+ "output",
+ ),
+ timestamp: "2026-07-26T10:00:01Z",
+ },
+ );
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ createCodex: completedCodex(root),
+ });
+ try {
+ const result = await client.run(repository, { maxCostUsd: 1 });
+ expect(result.cost).toMatchObject({ inputTokens: 10, outputTokens: 3 });
+ } finally {
+ await client.close();
+ }
+});
diff --git a/sdk/typescript/tests-ts/api.test.ts b/sdk/typescript/tests-ts/api.test.ts
index 1c16f4ea8..7fdfbb4cf 100644
--- a/sdk/typescript/tests-ts/api.test.ts
+++ b/sdk/typescript/tests-ts/api.test.ts
@@ -88,6 +88,7 @@ import {
} from "./plugin-root.js";
import {
EXTERNAL_PROVIDER_CASES,
+ measuredScanUsage,
mockScanRegistration,
mockWorkbench,
shellEnvironmentReference,
@@ -3861,13 +3862,12 @@ if __name__ == "__main__":
["without", false],
["with", true],
] as const)(
- "handles a session-tracking failure %s an explicit cost limit",
+ "warns about unreadable activity logs %s an explicit cost limit",
async (_description, enforceCostLimit) => {
const { root, repository, codexHome, scanDir } = await scanDirectories();
await writeFile(join(codexHome, "sessions"), "not a directory");
const commands: string[] = [];
const warnings: string[] = [];
- let savedFailure: string | undefined;
const client = TestClient.withDependencies({
...scanRuntimeDependencies(codexHome, scanDir),
runWorkbench: async (
@@ -3876,7 +3876,6 @@ if __name__ == "__main__":
input?: string,
): Promise<JsonObject> => {
commands.push(args[0]!);
- if (args[0] === "fail-scan") savedFailure = args[3];
return mockWorkbench(args, input);
},
createCodex: completedCodex(root),
@@ -3887,18 +3886,13 @@ if __name__ == "__main__":
onActivity: () => {},
onWarning: (warning) => warnings.push(warning),
});
- if (enforceCostLimit) {
- await expect(scan).rejects.toThrow("interrupted");
- expect(commands).toContain("fail-scan");
- expect(savedFailure).toContain("sessions");
- expect(commands).not.toContain("cancel-scan");
- } else {
- await expect(scan).resolves.toMatchObject({ threadId: "thread-1" });
- expect(warnings).toContainEqual(
- expect.stringContaining("Could not track scan activity:"),
- );
- expect(commands).toContain("complete-scan");
- }
+ await expect(scan).resolves.toMatchObject({ threadId: "thread-1" });
+ expect(warnings).toContainEqual(
+ expect.stringContaining("Could not track scan activity:"),
+ );
+ expect(commands.includes("read-scan-usage")).toBe(enforceCostLimit);
+ expect(commands).toContain("complete-scan");
+ expect(commands).not.toContain("cancel-scan");
await client.close();
},
);
@@ -14369,7 +14363,7 @@ if __name__ == "__main__":
}
});
const prices = [
- { model: "gpt-6-astra", min: 0.000232, max: 0.000389 },
+ { model: "gpt-6-astra", min: 0.000232, max: 0.000429 },
{ model: "gpt-5.6-cyber", min: 0.0003275, max: null },
];
test.each(prices)("tracks live and saved $model costs", async (price) => {
@@ -14415,7 +14409,7 @@ if __name__ == "__main__":
estimatedUsdRange: { min, max, context: "unknown" },
pricing: { serviceTier: "standard", context: "short" },
});
- expect([result.cost]).toEqual(costs);
+ expect(result.cost).toEqual(costs.at(-1)!);
const completion = commands.find((args) => args[0] === "complete-scan");
expect(completion).toBeDefined();
@@ -14555,6 +14549,8 @@ if __name__ == "__main__":
resumeThread: () => thread,
}),
runWorkbench: async (_options, args, input): Promise<JsonObject> => {
+ if (args[0] === "read-scan-usage")
+ return measuredScanUsage(2_000, 0, 0);
if (args[0] === "get-cli-scan-resume")
return {
scanId,
@@ -14790,6 +14786,7 @@ if __name__ == "__main__":
{
...scanRuntimeDependencies(codexHome, scanDir),
prepareRuntime: async () => prepared,
+ runWorkbench: recordingWorkbench([], measuredScanUsage(900, 0, 0)),
createCodex: codexFactory(
async (_input: string, { signal }: { signal: AbortSignal }) => {
scanSignal = signal;
@@ -14900,6 +14897,7 @@ if __name__ == "__main__":
const secondApproval = new Promise<void>((resolve) =>
approvals.set(0.016, resolve),
);
+ let measured = 0;
const requests: number[] = [];
const commands: Array<readonly string[]> = [];
const startThread = mock(() => {
@@ -14918,9 +14916,12 @@ if __name__ == "__main__":
{ input_tokens: 100, output_tokens: 0 },
{ parent: "scan-thread", parentField: "parent_thread_id" },
);
+ measured = 900;
await firstApproval;
await appendUsage(path, 1_700);
+ measured = 1_800;
await secondApproval;
+ measured = 2_600;
await copyCompletedScan(root);
yield {
type: "turn.completed",
@@ -14940,16 +14941,19 @@ if __name__ == "__main__":
let budgetSignal: AbortSignal | undefined;
const client = TestClient.withDependencies({
...scanRuntimeDependencies(codexHome, scanDir),
- runWorkbench: recordingWorkbench(commands),
+ runWorkbench: recordingWorkbench(commands, () =>
+ measuredScanUsage(measured, 0, 0),
+ ),
createCodex: () => ({
startThread,
}),
});
- const keepAlive = setTimeout(() => {}, 10_000);
+ const guard = new AbortController();
+ const guardTimer = setTimeout(() => guard.abort(), 15_000);
try {
const result = await client.run(repository, {
maxCostUsd: 0.004,
- signal: AbortSignal.timeout(5_000),
+ signal: guard.signal,
onBudgetApproaching: ({ maxCostUsd, signal }) => {
requests.push(maxCostUsd);
budgetSignal = signal;
@@ -14973,7 +14977,7 @@ if __name__ == "__main__":
expect(commands.some(([command]) => command === "fail-scan")).toBe(false);
expect(budgetSignal?.aborted).toBe(true);
} finally {
- clearTimeout(keepAlive);
+ clearTimeout(guardTimer);
await client.close();
}
});
@@ -14998,6 +15002,7 @@ if __name__ == "__main__":
const controller = new AbortController();
const commands: Array<readonly string[]> = [];
const warnings: string[] = [];
+ let measured = 900;
let requestCount = 0;
const onCost = mock((cost: ScanCost, _limit: number | undefined) => {
if (cost.inputTokens === 950) nextCost.resolve();
@@ -15007,6 +15012,8 @@ if __name__ == "__main__":
...scanRuntimeDependencies(codexHome, scanDir),
runWorkbench: async (_options, args, input) => {
commands.push(args);
+ if (args[0] === "read-scan-usage")
+ return measuredScanUsage(measured, 0, 0);
if (scenario === "save-failed" && args[0] === "set-scan-cost-limit")
throw new Error("Synthetic save failure");
if (scenario === "saving" && args[0] === "set-scan-cost-limit")
@@ -15037,10 +15044,15 @@ if __name__ == "__main__":
return;
}
await appendUsage(path, 950);
+ measured = 950;
await nextCost.promise;
if (scenario === "canceled") controller.abort();
- else await appendUsage(path, 1_200);
+ else {
+ measured = 1_200;
+ await appendUsage(path, 1_200);
+ }
await (signal.aborted ? undefined : once(signal, "abort"));
+ measured = 2_000;
await appendUsage(path, 2_000);
throw new DOMException("aborted", "AbortError");
}
@@ -15146,7 +15158,10 @@ if __name__ == "__main__":
})!;
const client = TestClient.withDependencies({
...scanRuntimeDependencies(codexHome, scanDir),
- runWorkbench: recordingWorkbench(commands),
+ runWorkbench: recordingWorkbench(
+ commands,
+ measuredScanUsage(1_250, 200, 30),
+ ),
createCodex: codexFactory(runStreamed),
});
@@ -15184,8 +15199,12 @@ if __name__ == "__main__":
"--thread-id",
"scan-thread",
]);
- expect(commands[3]).toEqual(["get-scan", "--scan-id", "scan_example_001"]);
- expect(commands[4]).toEqual([
+ expect(commands.at(-2)).toEqual([
+ "get-scan",
+ "--scan-id",
+ "scan_example_001",
+ ]);
+ expect(commands.at(-1)).toEqual([
"fail-scan",
"--scan-id",
"scan_example_001",
@@ -15256,6 +15275,8 @@ if __name__ == "__main__":
return { ...mockWorkbench(args, input), lifecycle: registration };
}
if (args[0] === "fail-scan") return { scan: { lifecycle: terminal } };
+ if (args[0] === "read-scan-usage")
+ return measuredScanUsage(1_250, 200, 30);
if (args[0] !== "complete-budget-exhausted-scan") {
return mockWorkbench(args, input);
}
@@ -15371,14 +15392,13 @@ if __name__ == "__main__":
},
);
- test("saves a budgeted scan with a warning when token usage is unavailable", async () => {
+ test("fails a budgeted scan before sealing when token usage is unavailable", async () => {
const { root, repository, codexHome, scanDir } = await scanDirectories();
- const warnings = mock((_warning: string) => {});
const commands: Array<readonly string[]> = [];
let threads = 0;
const client = TestClient.withDependencies({
...scanRuntimeDependencies(codexHome, scanDir),
- runWorkbench: recordingWorkbench(commands),
+ runWorkbench: recordingWorkbench(commands, { coverage: "unavailable" }),
createCodex: (options: CodexOptions) => ({
startThread(threadOptions: Parameters<Codex["startThread"]>[0]) {
threads++;
@@ -15402,26 +15422,22 @@ if __name__ == "__main__":
}),
});
- const result = await client.run(repository, {
- maxCostUsd: 1,
- ownerSuggestions: true,
- onWarning: warnings,
- });
- expect(result.threadId).toBe("scan-thread");
- expect(result.cost).toBeNull();
+ await expect(
+ client.run(repository, { maxCostUsd: 1, ownerSuggestions: true }),
+ ).rejects.toThrow(/could not verify.*cost limit/i);
expect(threads).toBe(1);
- expect(warnings.mock.calls.map(([value]) => value)).toContain(
- "Scan completed, but its cost limit could not be verified because model pricing or token usage is unavailable.",
- );
- expect(commands.map(([command]) => command)).toEqual([
+ expect(commands.some(([name]) => name === "read-scan-usage")).toBe(true);
+ expect(
+ commands
+ .map(([name]) => name)
+ .filter((name) => name !== "read-scan-usage"),
+ ).toEqual([
"register-cli-scan",
"get-scan-feedback",
"set-scan-thread",
- "prepare-scan-completion",
- "complete-scan",
- "list-global-findings",
+ "get-scan",
+ "fail-scan",
]);
- expect(commands.some((args) => args[0] === "fail-scan")).toBe(false);
await client.close();
});
@@ -18242,13 +18258,18 @@ setInterval(() => {}, 1000);
}, 30_000);
});
-function recordingWorkbench(commands: Array<readonly string[]>) {
+function recordingWorkbench(
+ commands: Array<readonly string[]>,
+ usage?: JsonObject | (() => JsonObject),
+) {
return async (
_options: unknown,
args: readonly string[],
input?: string,
): Promise<JsonObject> => {
commands.push(args);
+ if (usage && args[0] === "read-scan-usage")
+ return typeof usage === "function" ? usage() : usage;
return mockWorkbench(args, input);
};
}
diff --git a/sdk/typescript/tests-ts/cost.test.ts b/sdk/typescript/tests-ts/cost.test.ts
index 0f80fc295..aaf880f1d 100644
--- a/sdk/typescript/tests-ts/cost.test.ts
+++ b/sdk/typescript/tests-ts/cost.test.ts
@@ -61,6 +61,34 @@ async function waitFor(check: () => boolean): Promise<void> {
afterEach(cleanup);
+test("a partial owned subtotal includes spending absent from local session logs", async () => {
+ const home = await codexHome();
+ const observed: Array<[number, boolean]> = [];
+ let complete = false;
+ const tracker = new ScanCostTracker({
+ codexHome: home,
+ model: "gpt-5.6-sol",
+ maxCostUsd: 1,
+ readBudgetUsage: async () => ({
+ usage: { ...ownedSdkUsage, cache_write_input_tokens_reported: false },
+ complete,
+ }),
+ onCost: (cost, coverage) => observed.push([cost.inputTokens, coverage]),
+ });
+ tracker.start("primary");
+ try {
+ await tracker.refresh();
+ expect(observed).toEqual([[ownedSdkUsage.input_tokens, false]]);
+ complete = true;
+ // The SDK's parent receipt omits the detached worker's usage.
+ const final = await tracker.stop({ input_tokens: 1, output_tokens: 1 });
+ expect(final.cost?.inputTokens).toBe(ownedSdkUsage.input_tokens);
+ expect(observed.at(-1)).toEqual([ownedSdkUsage.input_tokens, true]);
+ } finally {
+ await tracker.stop();
+ }
+});
+
let costModuleBundle: Promise<string> | undefined;
function bundledCostModule(): Promise<string> {
costModuleBundle ??= Bun.build({
diff --git a/sdk/typescript/tests-ts/support/api-client.ts b/sdk/typescript/tests-ts/support/api-client.ts
index 30586a6ad..d67c080f4 100644
--- a/sdk/typescript/tests-ts/support/api-client.ts
+++ b/sdk/typescript/tests-ts/support/api-client.ts
@@ -125,6 +125,24 @@ export function mockScanRegistration(
};
}
+export function measuredScanUsage(
+ inputTokens: number,
+ cachedInputTokens: number,
+ outputTokens: number,
+ reasoningOutputTokens = 0,
+): JsonObject {
+ return {
+ coverage: "complete",
+ inputTokens,
+ cachedInputTokens,
+ cacheWriteInputTokens: 0,
+ outputTokens,
+ reasoningOutputTokens,
+ totalTokens: inputTokens + outputTokens,
+ byRole: { workers: { threadCount: 0 } },
+ };
+}
+
export function mockWorkbench(
args: readonly string[],
input?: string,
@@ -132,6 +150,7 @@ export function mockWorkbench(
if (args[0] === "register-cli-scan") {
return mockScanRegistration(args, input);
}
+ if (args[0] === "read-scan-usage") return measuredScanUsage(10, 2, 3, 1);
if (args[0] === "get-scan-feedback") {
return {
scanId: "scan_example_001",