← Files Codex SecurityARCHIVED FILE

scripts/workbench_finding_workflows.py

14.7 KB · Nov 18, 2026 · 06:11 UTC

↓ Download file

See the change to this file →

"""Durable state for the opt-in local scan, publication, and dedupe workflow."""

from __future__ import annotations

import argparse
import hashlib
import json
import sqlite3
import stat
import sys
from pathlib import Path
from typing import Any

sys.path.insert(0, str(Path(__file__).resolve().parent))
from workbench_scan_usage import stored_scan_cost_fields
from workbench_target import (
    UnreadableLocalFile,
    UnsupportedLocalFileType,
    directory_content_digest,
    git_bytes,
    git_revision,
)
from workbench_validation import _valid_legacy_scan_cost

WORKFLOW_BINDINGS = {
    "repositoryPath": "repository_path",
    "scanRequestDigest": "scan_request_digest",
    "scanId": "scan_id",
    "scanDir": "scan_dir",
    "artifactDigest": "artifact_digest",
    "destination": "destination",
}
WORKFLOW_STAGES = ("scan", "publish", "dedupe")


def _usable_cost_range(value: Any) -> bool:
    if not isinstance(value, dict) or value.get("context") != "unknown" or "max" not in value:
        return False
    minimum, maximum = value.get("min"), value["max"]
    return (
        type(minimum) in (int, float)
        and 0 <= minimum <= sys.float_info.max
        and (
            maximum is None
            or type(maximum) in (int, float)
            and minimum <= maximum <= sys.float_info.max
        )
    )


def _recorded_cost(value: str | None) -> dict[str, Any] | None:
    """Recover the SDK cost fields that are usable from this historical receipt."""
    try:
        cost = stored_scan_cost_fields(value).get("cost")
    except (TypeError, ValueError, RecursionError):
        return None
    if not _valid_legacy_scan_cost(cost):
        return None

    fields = (
        "model",
        "inputTokens",
        "cachedInputTokens",
        "cacheWriteInputTokens",
        "outputTokens",
        "estimatedUsd",
    )
    result = {field: cost[field] for field in fields}
    if isinstance(cost.get("cacheWriteInputTokensReported"), bool):
        result["cacheWriteInputTokensReported"] = cost["cacheWriteInputTokensReported"]
    bounds = cost.get("estimatedUsdRange")
    if _usable_cost_range(bounds):
        result["estimatedUsdRange"] = {field: bounds[field] for field in ("min", "max", "context")}

    pricing = cost.get("pricing")
    if (
        isinstance(pricing, dict)
        and pricing.get("serviceTier") == "standard"
        and pricing.get("context") == "short"
        and isinstance(pricing.get("source"), str)
        and isinstance(pricing.get("asOf"), str)
    ):
        details = {field: pricing[field] for field in ("source", "asOf", "serviceTier", "context")}
        rate_keys = ("input", "cacheRead", "cacheWrite", "output")
        for field in ("usdPerMillionTokens", "longContextUsdPerMillionTokens"):
            rates = pricing.get(field)
            if isinstance(rates, dict) and all(
                type(rates.get(key)) in (int, float) and 0 <= rates[key] <= sys.float_info.max
                for key in rate_keys
            ):
                details[field] = {key: rates[key] for key in rate_keys}
        if "usdPerMillionTokens" in details:
            result["pricing"] = details
    return result


def read_workflow(connection: sqlite3.Connection, workflow_id: str) -> dict[str, Any] | None:
    """Return the stored stages, scope, and available scan cost, or None if the workflow ID is unknown."""
    row = connection.execute(
        """SELECT w.*, s.cost_json FROM finding_workflows AS w
           LEFT JOIN scans AS s ON s.id = w.scan_id AND s.scan_dir = w.scan_dir
                               AND s.status = 'complete'
           WHERE w.id = ?""",
        (workflow_id,),
    ).fetchone()
    if row is None:
        return None
    state = {"id": row["id"], "stages": {}}
    if (cost := _recorded_cost(row["cost_json"])) is not None:
        state["recordedCost"] = cost
    for field, column in WORKFLOW_BINDINGS.items():
        if row[column] is not None:
            state[field] = row[column]
    if row["scope_repository_id"] is not None:
        state["scope"] = {"repositoryId": row["scope_repository_id"]}
    elif row["scope_all_repositories"] is not None:
        state["scope"] = {"allRepositories": bool(row["scope_all_repositories"])}
    results = json.loads(row["results_json"])
    for stage in WORKFLOW_STAGES:
        current = {"status": row[f"{stage}_status"]}
        if row[f"{stage}_error"] is not None:
            current["error"] = row[f"{stage}_error"]
        if stage in results:
            current["result"] = results[stage]
        state["stages"][stage] = current
    if "dedupePendingWrite" in results:
        state["stages"]["dedupe"]["pendingWrite"] = results["dedupePendingWrite"]
    return state


def save_workflow(connection: sqlite3.Connection, state: dict[str, Any], timestamp: str) -> None:
    """Insert or update the workflow bindings, scope, stage statuses, and saved results in the caller’s connection."""
    values = {"id": state["id"]}
    values.update({column: state.get(field) for field, column in WORKFLOW_BINDINGS.items()})
    scope = state.get("scope", {})
    values.update(
        scope_repository_id=scope.get("repositoryId"),
        scope_all_repositories=scope.get("allRepositories"),
    )
    results = {}
    for stage in WORKFLOW_STAGES:
        current = state["stages"][stage]
        values[f"{stage}_status"] = current["status"]
        values[f"{stage}_error"] = current.get("error")
        if "result" in current:
            results[stage] = current["result"]
    if "pendingWrite" in state["stages"]["dedupe"]:
        results["dedupePendingWrite"] = state["stages"]["dedupe"]["pendingWrite"]
    values.update(
        results_json=json.dumps(results, allow_nan=False),
        created_at=timestamp,
        updated_at=timestamp,
    )
    updates = ", ".join(
        f"{column} = excluded.{column}" for column in values if column not in {"id", "created_at"}
    )
    connection.execute(
        f"INSERT INTO finding_workflows ({', '.join(values)}) "
        f"VALUES ({', '.join('?' for _ in values)}) ON CONFLICT(id) DO UPDATE SET {updates}",
        tuple(values.values()),
    )


def bind_workflow(state: dict[str, Any], binding: dict[str, Any]) -> None:
    """Add bindings to the supplied state in place, raising SystemExit for unknown or conflicting fields."""
    for field, value in binding.items():
        if field not in WORKFLOW_BINDINGS and field != "scope":
            raise SystemExit("Unknown workflow binding.")
        if field in state and state[field] != value:
            raise SystemExit(
                f"Workflow {state['id']} is already bound to a different {field}. "
                "Use another --workflow-id."
            )
        state[field] = value


def register_workflow_scan(
    connection: sqlite3.Connection, workflow_id: str, scan_id: str, scan_dir: str, timestamp: str
) -> None:
    """Called inside the scan-registration transaction, before model execution."""
    state = read_workflow(connection, workflow_id)
    if state is None:
        raise SystemExit("The workflow must be started before registering its scan.")
    if state["stages"]["scan"]["status"] == "completed":
        raise SystemExit("The workflow scan is already complete.")
    previous = state.get("scanId")
    if previous is not None:
        row = connection.execute(
            """SELECT saved.status, saved.recipe_json AS saved, attempt.recipe_json AS attempt
               FROM scans AS saved JOIN scans AS attempt ON attempt.id = ? WHERE saved.id = ?""",
            (scan_id, previous),
        ).fetchone()
        if row is not None:
            if row["status"] == "complete":
                raise SystemExit(
                    "Reuse the workflow's completed scan instead of registering another."
                )
            saved = json.loads(row["saved"] or "{}")
            attempt = json.loads(row["attempt"] or "{}")
            if saved.get("severityRubric") != attempt.get("severityRubric"):
                raise SystemExit(
                    "Another attempt registered a different severity rubric. Retry this workflow to reuse its saved rubric."
                )
    state["scanId"] = scan_id
    state["scanDir"] = scan_dir
    save_workflow(connection, state, timestamp)


def finding_workflow(
    connection: sqlite3.Connection, payload: dict[str, Any], timestamp: str
) -> dict[str, Any]:
    """Dispatch a workflow request by ID and return its state, source snapshot, or review as the action specifies."""
    workflow_id = payload["id"]
    if not isinstance(workflow_id, str) or not workflow_id.strip():
        raise SystemExit("workflowId must be a nonempty string.")
    if payload["action"] == "get":
        return {"workflow": read_workflow(connection, workflow_id)}
    if payload["action"] == "source":
        evidence = payload.get("evidence") is True
        if evidence:
            try:
                target = Path(payload["repository"])
                metadata = target.lstat()
                if (
                    not target.is_absolute()
                    or not stat.S_ISDIR(metadata.st_mode)
                    or getattr(metadata, "st_reparse_tag", 0) & 0x20000000
                    or target.resolve(strict=True) != target
                ):
                    raise UnreadableLocalFile("The validation evidence directory was replaced.")
            except (OSError, RuntimeError, UnreadableLocalFile):
                if payload.get("optional") is True:
                    return {"source": None}
                raise
        else:
            target = Path(payload["repository"]).resolve(strict=True)
        private_paths = payload.get("privateStatePaths", [])
        if not isinstance(private_paths, list) or any(
            not isinstance(path, str) or not Path(path).is_absolute() for path in private_paths
        ):
            raise SystemExit("Private runtime paths must be absolute paths.")
        excluded = tuple(sorted({Path(path).resolve() for path in private_paths}))
        excluded = tuple(path for path in excluded if path.is_relative_to(target))
        if target in excluded:
            raise SystemExit("Private runtime storage must not exclude the repository root.")
        try:
            content = directory_content_digest(
                target,
                excluded=excluded,
                include_ignored=True,
                include_git_metadata=evidence,
            )
        except (UnsupportedLocalFileType, UnreadableLocalFile, OSError):
            if payload.get("optional") is True:
                return {"source": None}
            raise
        return {
            "source": {
                "repository": str(target),
                "revision": (
                    "unversioned"
                    if evidence or payload.get("gitDisabled")
                    else git_revision(target)
                ),
                "refsDigest": hashlib.sha256(
                    b""
                    if evidence or payload.get("gitDisabled")
                    else (git_bytes(target, "show-ref") or b"").strip()
                ).hexdigest(),
                "content": content,
                **({"privateStatePaths": [str(path) for path in excluded]} if excluded else {}),
            }
        }
    if payload["action"] == "get-review":
        row = connection.execute(
            "SELECT result_json FROM finding_workflow_reviews WHERE workflow_id = ? AND review_key = ?",
            (workflow_id, payload["key"]),
        ).fetchone()
        return {"review": json.loads(row["result_json"]) if row is not None else None}
    if payload["action"] == "save-review":
        binding = payload["binding"]
        source = binding["source"]
        scope = binding["scope"]
        on_conflict = (
            "DO UPDATE SET result_json = excluded.result_json, created_at = excluded.created_at"
            if payload.get("replace") is True and binding.get("stage") == "scan-validation"
            else "DO NOTHING"
        )
        with connection:
            connection.execute(
                f"""INSERT INTO finding_workflow_reviews
                (workflow_id, review_key, review_contract_version, codex_version,
                 source_repository_path, source_revision, source_refs_digest, source_content_digest,
                 scope_repository_id, scope_all_repositories, model, effort, settings_digest,
                 prompt_digest, contract_digest, result_json, created_at)
                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
                ON CONFLICT(workflow_id, review_key) {on_conflict}""",
                (
                    workflow_id,
                    payload["key"],
                    binding["version"],
                    binding["codexVersion"],
                    source["repository"],
                    source["revision"],
                    source["refsDigest"],
                    source["content"],
                    scope.get("repositoryId"),
                    scope.get("allRepositories"),
                    binding["model"],
                    binding["effort"],
                    binding.get("settingsDigest"),
                    binding["promptDigest"],
                    binding["contractDigest"],
                    json.dumps(payload["result"], allow_nan=False),
                    timestamp,
                ),
            )
        return {}
    connection.execute("BEGIN IMMEDIATE")
    with connection:
        state = read_workflow(connection, workflow_id)
        if state is None:
            state = {
                "id": workflow_id,
                "stages": {stage: {"status": "pending"} for stage in WORKFLOW_STAGES},
            }
        bind_workflow(state, payload.get("binding", {}))
        action = payload["action"]
        if action != "bind":
            stage = payload["stage"]
            if stage not in state["stages"]:
                raise SystemExit("Unknown workflow stage.")
            current = state["stages"][stage]
            if current["status"] != "completed":
                if action == "begin":
                    current["status"] = "running"
                elif action == "complete":
                    state["stages"][stage] = {"status": "completed", "result": payload["result"]}
                elif action == "fail":
                    current.update(status="failed", error=payload["error"])
                    if "result" in payload:
                        current["result"] = payload["result"]
                elif action == "prepare-dedupe":
                    current.update(result=payload["result"], pendingWrite=payload["pendingWrite"])
                else:
                    raise SystemExit("Unknown workflow action.")
        save_workflow(connection, state, timestamp)
        return {"workflow": state}


if __name__ == "__main__":
    argparse.ArgumentParser(description=__doc__).parse_args()

SHA-256: 2d3914e553d5e5bf710a8d27bd25f878a023449270b2045db97a9752c1f7ba51