chore(codex-security): sync public projection

  - [codex] track scan costs and enforce scan budgets (#11885...

GitOrigin-Timestamp=2026-07-26T15:03:53-07:00
GitOrigin-RevId: d90e2acf1a5e04c91e45f41c0dfedd7534045e7e

Author: ianw-oai

sdk/typescript/README.md

@@ -104,6 +104,7 @@ npx codex-security scan /path/to/repository --output-dir /path/outside/repositor
 npx codex-security scan /path/to/repository --output-dir /path/outside/repository/results --archive-existing
 npx codex-security scan /path/to/repository --dry-run
 npx codex-security scan /path/to/repository --fail-on-severity high
+npx codex-security scan /path/to/repository --max-cost 5
 npx codex-security bulk-scan
 npx codex-security bulk-scan repositories.csv --output-dir /path/outside/repositories/security-scans --workers 4
 npx codex-security scans list /path/to/repository
@@ -159,9 +160,19 @@ options for other Codex settings, such as
 Scan progress identifies the requested paths and reports actual ranking,
 file-review, validation, and attack-path phases as they become available.
 Completion summarizes findings, severity, coverage, elapsed time, available
-token and worker counts, the results directory, and the next useful command.
+token and worker counts, estimated cost, the results directory, and the next
+useful command.
 Progress and summaries use stderr; structured scan results remain on stdout.
 
+Each scan records its model, tokens, and estimated cost in its JSON result,
+scan history, and bulk-scan receipt. Estimates use
+[standard API token prices](https://developers.openai.com/api/docs/models/compare),
+including cached input and cache writes; fees and surcharges are not included.
+
+Use `--max-cost USD` to stop a scan, including its delegated workers, when its
+running cost exceeds the limit. Partial results are preserved. Requests
+already in progress can finish above the limit.
+
 Run `npx codex-security scan --help` or `npx codex-security bulk-scan --help`
 for the complete CLI references.
 

sdk/typescript/_bundled_plugin/scripts/workbench_cli.py

@@ -208,6 +208,7 @@ def parse_args(description: str) -> argparse.Namespace:
     complete_scan = subparsers.add_parser("complete-scan")
     complete_scan.add_argument("--scan-id", required=True)
     complete_scan.add_argument("--claim-token")
+    complete_scan.add_argument("--cost-json")
 
     cancel_scan = subparsers.add_parser("cancel-scan")
     cancel_scan.add_argument("--scan-id", required=True)
@@ -217,6 +218,7 @@ def parse_args(description: str) -> argparse.Namespace:
     fail_scan.add_argument("--scan-id", required=True)
     fail_scan.add_argument("--message", required=True)
     fail_scan.add_argument("--claim-token")
+    fail_scan.add_argument("--cost-json")
 
     mark_handoff_delivered = subparsers.add_parser("mark-handoff-delivered")
     mark_handoff_delivered.add_argument("--scan-id", required=True)

sdk/typescript/_bundled_plugin/scripts/workbench_db.py

@@ -106,6 +106,7 @@
     capability_preflight_input,
     capability_preflight_json,
     optional_text,
+    parse_scan_cost,
     require_occurrence,
     require_uuid,
 )
@@ -1453,12 +1454,16 @@ def pin_legacy_manifest_digest(
 
 def complete_scan(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
     scan_id = require_uuid(args.scan_id, "scan-id")
+    cost_json = parse_scan_cost(args.cost_json)
     with scan_completion_lock(scan_id):
-        return complete_scan_locked(connection, scan_id, args.claim_token)
+        return complete_scan_locked(connection, scan_id, args.claim_token, cost_json)
 
 
 def complete_scan_locked(
-    connection: sqlite3.Connection, scan_id: str, claim_token: str | None
+    connection: sqlite3.Connection,
+    scan_id: str,
+    claim_token: str | None,
+    cost_json: str | None,
 ) -> dict[str, Any]:
     scan = require_scan(connection, scan_id)
     if scan["status"] == "complete":
@@ -1551,10 +1556,10 @@ def complete_scan_locked(
             """
             UPDATE scans
             SET status = 'complete', phase = 'reporting', completed_at = ?, updated_at = ?,
-                seal_manifest_digest = ?
+                seal_manifest_digest = ?, cost_json = ?
             WHERE id = ? AND status = 'running'
             """,
-            (timestamp, timestamp, manifest_digest, scan["id"]),
+            (timestamp, timestamp, manifest_digest, cost_json, scan["id"]),
         )
         if updated.rowcount != 1:
             raise SystemExit("Only a running scan can be completed.")
@@ -1750,6 +1755,7 @@ def coverage_for_comparison(scan: sqlite3.Row) -> dict[str, Any]:
 
 def fail_scan(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
     scan_id = require_uuid(args.scan_id, "scan-id")
+    cost_json = parse_scan_cost(args.cost_json)
     connection.execute("BEGIN IMMEDIATE")
     try:
         timestamp = now()
@@ -1767,10 +1773,17 @@ def fail_scan(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[
         updated = connection.execute(
             """
             UPDATE scans
-            SET status = 'failed', failure_message = ?, completed_at = ?, updated_at = ?
+            SET status = 'failed', failure_message = ?, completed_at = ?, updated_at = ?,
+                cost_json = ?
             WHERE id = ? AND status = 'running'
             """,
-            (optional_text(args.message, maximum=2400), timestamp, timestamp, scan["id"]),
+            (
+                optional_text(args.message, maximum=2400),
+                timestamp,
+                timestamp,
+                cost_json,
+                scan["id"],
+            ),
         )
         if updated.rowcount != 1:
             raise SystemExit("Only a running scan can be marked failed.")
@@ -3025,6 +3038,11 @@ def scan_result(
     return {
         "artifacts": artifacts,
         "canceledAt": scan["canceled_at"],
+        **(
+            {"cost": json.loads(scan["cost_json"], parse_constant=reject_non_finite_json)}
+            if scan["cost_json"] is not None
+            else {}
+        ),
         "contract": scan_contract(scan),
         "continuationThreadId": scan["continuation_thread_id"],
         "failureMessage": scan["failure_message"],

sdk/typescript/_bundled_plugin/scripts/workbench_scan_history.py

@@ -216,6 +216,7 @@ def list_scans(
             {
                 "completedAt": row["completed_at"],
                 "continuationThreadId": row["continuation_thread_id"],
+                **({"cost": json.loads(row["cost_json"])} if row["cost_json"] else {}),
                 "findingCount": row["finding_count"],
                 "handoffStatus": row["handoff_status"],
                 "mode": row["mode"],

sdk/typescript/_bundled_plugin/scripts/workbench_schema.py

@@ -595,6 +595,13 @@
         ON scan_comparison_matches(after_occurrence_id);
         """,
     ),
+    (
+        24,
+        "persist scan cost estimates",
+        """
+        ALTER TABLE scans ADD COLUMN cost_json TEXT;
+        """,
+    ),
 )
 
 

sdk/typescript/_bundled_plugin/scripts/workbench_validation.py

@@ -36,6 +36,32 @@ def reject_nonstandard_json_number(value: str) -> None:
     raise ValueError(f"invalid JSON number {value}")
 
 
+def parse_scan_cost(value: str | None) -> str | None:
+    if value is None:
+        return None
+    if len(value.encode("utf-8")) > 8192:
+        raise SystemExit("Scan cost must be no larger than 8 KiB.")
+    try:
+        cost = json.loads(value, parse_constant=reject_nonstandard_json_number)
+    except (TypeError, UnicodeError, ValueError) as exc:
+        raise SystemExit("Scan cost must be a valid JSON object.") from exc
+    token_keys = ("inputTokens", "cachedInputTokens", "cacheWriteInputTokens", "outputTokens")
+    if (
+        not isinstance(cost, dict)
+        or not isinstance(cost.get("model"), str)
+        or not cost["model"]
+        or any(type(cost.get(key)) is not int or cost[key] < 0 for key in token_keys)
+        or cost["cachedInputTokens"] + cost["cacheWriteInputTokens"] > cost["inputTokens"]
+        or type(cost.get("estimatedUsd")) not in (int, float)
+        or not math.isfinite(cost["estimatedUsd"])
+        or cost["estimatedUsd"] < 0
+    ):
+        raise SystemExit(
+            "Scan cost must include a model, nonnegative token counts, and an estimated USD amount."
+        )
+    return json.dumps(cost, separators=(",", ":"), allow_nan=False)
+
+
 def capability_preflight_json(
     value: str | None,
     *,

sdk/typescript/package.json

@@ -46,7 +46,7 @@
     "generate:models": "node scripts/generate-models.cjs",
     "generate:models:check": "node scripts/generate-models.cjs --check",
     "lint": "tsc --noEmit",
-    "test": "bun test --timeout 30000 tests-ts/api.test.ts tests-ts/auth.test.ts tests-ts/bulk-scan-discovery.test.ts tests-ts/cli-export.test.ts tests-ts/cli.test.ts tests-ts/config.test.ts tests-ts/contract.test.ts tests-ts/knowledge-base.test.ts tests-ts/multiscan.test.ts tests-ts/result.test.ts tests-ts/runtime.test.ts tests-ts/scan-comparison.test.ts tests-ts/scan-history-renderer.test.ts tests-ts/skeleton.test.ts tests-ts/targets.test.ts tests-ts/trusted-executable.test.ts tests-ts/worker-progress.test.ts",
+    "test": "bun test --timeout 30000 tests-ts/api.test.ts tests-ts/auth.test.ts tests-ts/bulk-scan-discovery.test.ts tests-ts/cli-export.test.ts tests-ts/cli.test.ts tests-ts/config.test.ts tests-ts/contract.test.ts tests-ts/cost.test.ts tests-ts/knowledge-base.test.ts tests-ts/multiscan.test.ts tests-ts/result.test.ts tests-ts/runtime.test.ts tests-ts/scan-comparison.test.ts tests-ts/scan-history-renderer.test.ts tests-ts/skeleton.test.ts tests-ts/targets.test.ts tests-ts/trusted-executable.test.ts tests-ts/worker-progress.test.ts",
     "types": "pnpm run generate:models:check && tsc --noEmit"
   },
   "dependencies": {

sdk/typescript/scripts/check-package.mjs

@@ -140,6 +140,7 @@ const distFiles = new Set(
     "cli",
     "config",
     "contract",
+    "cost",
     "errors",
     "index",
     "knowledge-base",