claude-dev-env 2.36.0 → 4.1.0

package/_shared/advisor/scripts/codex_astra_preflight.py

@@ -0,0 +1,115 @@
+"""Evaluate Codex usage before an Astra advisor request."""
+
+from __future__ import annotations
+
+import importlib
+import json
+import math
+import subprocess
+import sys
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+from advisor_scripts_constants.astra_advisor_constants import (
+    ASTRA_FALLBACK_KIND_BROKEN,
+    ASTRA_FALLBACK_KIND_DECLINED,
+    ASTRA_PREFLIGHT_FAILURE_REASON,
+    ASTRA_PROBE_TIMEOUT_REASON,
+    ASTRA_USAGE_PROBE_TIMEOUT_SECONDS,
+)
+
+
+@dataclass(frozen=True)
+class AstraPreflight:
+    eligible: bool
+    percent_left: float | None
+    reason: str
+    fallback_kind: str | None = None
+
+
+def _preflight_fallback(
+    reason: str, percent_left: float | None, fallback_kind: str
+) -> AstraPreflight:
+    return AstraPreflight(False, percent_left, reason, fallback_kind)
+
+
+def _load_usage_gate(probe_path: Path) -> Callable[[float], bool]:
+    probe_directory = str(probe_path.parent)
+    if probe_directory not in sys.path:
+        sys.path.insert(0, probe_directory)
+    return importlib.import_module("codex_usage_probe").is_codex_review_required
+
+
+def _parse_probe_percent(stdout_text: str) -> tuple[float | None, str | None]:
+    try:
+        report = json.loads(stdout_text)
+    except (TypeError, json.JSONDecodeError):
+        return None, "usage report is malformed"
+    if not isinstance(report, dict):
+        return None, "usage report is malformed"
+    raw_percent = report.get("percent_left")
+    if isinstance(raw_percent, bool) or not isinstance(raw_percent, (int, float)):
+        return None, "usage meter is unknown" if raw_percent is None else "usage meter is malformed"
+    percent_left = float(raw_percent)
+    if not math.isfinite(percent_left):
+        return None, "usage meter is malformed"
+    return percent_left, None
+
+
+def _run_probe(
+    probe_path: Path,
+    process_runner: Callable[..., subprocess.CompletedProcess[str]],
+) -> subprocess.CompletedProcess[str]:
+    return process_runner(
+        [sys.executable, str(probe_path)],
+        capture_output=True,
+        text=True,
+        check=False,
+        shell=False,
+        timeout=ASTRA_USAGE_PROBE_TIMEOUT_SECONDS,
+    )
+
+
+def _preflight_from_probe(
+    probe_path: Path, completed: subprocess.CompletedProcess[str]
+) -> AstraPreflight:
+    if completed.returncode != 0:
+        reason = f"{ASTRA_PREFLIGHT_FAILURE_REASON}: probe exit {completed.returncode}"
+        return _preflight_fallback(reason, None, ASTRA_FALLBACK_KIND_BROKEN)
+    percent_left, parse_reason = _parse_probe_percent(completed.stdout)
+    if parse_reason is not None or percent_left is None:
+        reason = f"{ASTRA_PREFLIGHT_FAILURE_REASON}: {parse_reason or 'usage meter is unknown'}"
+        return _preflight_fallback(reason, None, ASTRA_FALLBACK_KIND_BROKEN)
+    if not _load_usage_gate(probe_path)(percent_left):
+        reason = f"{ASTRA_PREFLIGHT_FAILURE_REASON}: usage meter is at or below the gate"
+        return _preflight_fallback(reason, percent_left, ASTRA_FALLBACK_KIND_DECLINED)
+    return AstraPreflight(True, percent_left, "usage meter is above the Astra gate")
+
+
+def run_astra_preflight(
+    probe_path: Path,
+    process_runner: Callable[..., subprocess.CompletedProcess[str]],
+) -> AstraPreflight:
+    """Run the usage probe and decide whether Astra may bind.
+
+    Args:
+        probe_path: Path to the installed usage probe.
+        process_runner: Callable that runs the probe.
+
+    Returns:
+        Eligibility, remaining usage percent, reason, and fallback kind.
+    """
+    try:
+        completed = _run_probe(probe_path, process_runner)
+        return _preflight_from_probe(probe_path, completed)
+    except subprocess.TimeoutExpired as error:
+        return _preflight_fallback(
+            f"{ASTRA_PROBE_TIMEOUT_REASON}: {error}", None, ASTRA_FALLBACK_KIND_BROKEN
+        )
+    except (OSError, subprocess.SubprocessError, ImportError, AttributeError, TypeError, ValueError) as error:
+        return _preflight_fallback(
+            f"{ASTRA_PREFLIGHT_FAILURE_REASON}: {error}",
+            None,
+            ASTRA_FALLBACK_KIND_BROKEN,
+        )

package/_shared/advisor/scripts/codex_astra_reply.py

@@ -0,0 +1,159 @@
+"""Parse Codex JSONL and build Astra advisor replies."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+
+from advisor_scripts_constants.advisor_route_constants import (
+    ADVISOR_FALLBACK_RESULT,
+    ADVISOR_FALLBACK_TIER,
+    ADVISOR_MODEL_TIER,
+    ALL_ADVISOR_GUIDANCE_SIGNALS,
+    CODEX_BIND_SUCCESS_TOKEN,
+)
+from advisor_scripts_constants.astra_advisor_constants import (
+    ASTRA_FALLBACK_KIND_BROKEN,
+    ASTRA_INVALID_SIGNAL_REASON,
+    ASTRA_MALFORMED_JSONL_REASON,
+    ASTRA_MISSING_SESSION_REASON,
+    ASTRA_REPLY_FAILURE_REASON,
+)
+
+
+@dataclass(frozen=True)
+class CodexAstraAdvisorReply:
+    session_id: str | None
+    guidance: str | None
+    successful: bool
+    reason: str | None
+    is_fallback: bool
+    signal: str | None
+    astra_enabled: bool
+    selected_tier: str
+    outcome: str
+    fallback_kind: str | None
+
+
+def build_fallback_reply(
+    reason: str,
+    is_astra_enabled: bool,
+    fallback_kind: str | None = ASTRA_FALLBACK_KIND_BROKEN,
+) -> CodexAstraAdvisorReply:
+    """Build a failed advisor reply.
+
+    Args:
+        reason: Why the request fell back.
+        is_astra_enabled: True when the Astra flag was on.
+        fallback_kind: Kind of fallback.
+
+    Returns:
+        Failed reply with no session or guidance.
+    """
+    return CodexAstraAdvisorReply(
+        None,
+        None,
+        False,
+        reason,
+        True,
+        None,
+        is_astra_enabled,
+        ADVISOR_FALLBACK_TIER,
+        ADVISOR_FALLBACK_RESULT,
+        fallback_kind,
+    )
+
+
+def build_success_reply(
+    session_id: str, guidance: str, signal: str
+) -> CodexAstraAdvisorReply:
+    """Build a successful advisor reply.
+
+    Args:
+        session_id: Codex session id.
+        guidance: Advisor text.
+        signal: First-line guidance signal.
+
+    Returns:
+        Successful reply with Astra enabled.
+    """
+    return CodexAstraAdvisorReply(
+        session_id,
+        guidance,
+        True,
+        None,
+        False,
+        signal,
+        True,
+        ADVISOR_MODEL_TIER,
+        CODEX_BIND_SUCCESS_TOKEN,
+        None,
+    )
+
+
+def _guidance_signal(guidance: str) -> str | None:
+    for each_line in guidance.splitlines():
+        candidate = each_line.strip()
+        if candidate:
+            return candidate if candidate in ALL_ADVISOR_GUIDANCE_SIGNALS else None
+    return None
+
+
+def _parse_event_line(each_line: str) -> tuple[str | None, str | None]:
+    event = json.loads(each_line)
+    if not isinstance(event, dict):
+        raise TypeError("event must be an object")
+    discovered_session_id: str | None = None
+    discovered_guidance: str | None = None
+    if event.get("type") == "thread.started":
+        raw_session = event.get("thread_id")
+        if isinstance(raw_session, str) and raw_session.strip():
+            discovered_session_id = raw_session.strip()
+    completed_event = event.get("item")
+    if event.get("type") == "item.completed" and isinstance(completed_event, dict):
+        message_text = completed_event.get("text")
+        if completed_event.get("type") == "agent_message" and isinstance(message_text, str):
+            discovered_guidance = message_text.strip()
+    return discovered_session_id, discovered_guidance
+
+
+def _collect_reply_parts(jsonl_text: str) -> tuple[str | None, str | None]:
+    session_id: str | None = None
+    guidance: str | None = None
+    for each_line in jsonl_text.splitlines():
+        if each_line.strip():
+            discovered_session_id, discovered_guidance = _parse_event_line(each_line)
+            session_id = discovered_session_id or session_id
+            guidance = discovered_guidance or guidance
+    return session_id, guidance
+
+
+def parse_codex_jsonl_reply(
+    jsonl_text: str,
+    existing_session_id: str | None,
+    is_astra_enabled: bool,
+    fallback_kind: str | None = None,
+) -> CodexAstraAdvisorReply:
+    """Parse Codex JSONL into an Astra advisor reply.
+
+    Args:
+        jsonl_text: JSONL from Codex stdout.
+        existing_session_id: Session expected on resume, or None on bind.
+        is_astra_enabled: True when the Astra flag was on.
+        fallback_kind: Kind of fallback on a failed reply.
+
+    Returns:
+        Advisor reply, or a fallback.
+    """
+    try:
+        session_id, guidance = _collect_reply_parts(jsonl_text)
+    except (TypeError, json.JSONDecodeError):
+        return build_fallback_reply(ASTRA_MALFORMED_JSONL_REASON, is_astra_enabled, fallback_kind)
+    if session_id is None or (existing_session_id is not None and session_id != existing_session_id):
+        return build_fallback_reply(ASTRA_MISSING_SESSION_REASON, is_astra_enabled, fallback_kind)
+    if not guidance:
+        return build_fallback_reply(ASTRA_REPLY_FAILURE_REASON, is_astra_enabled, fallback_kind)
+    signal = _guidance_signal(guidance)
+    if signal is None:
+        return build_fallback_reply(ASTRA_INVALID_SIGNAL_REASON, is_astra_enabled, fallback_kind)
+    return build_success_reply(session_id, guidance, signal)

package/_shared/advisor/scripts/config/advisor_scripts_constants/advisor_route_constants.py

@@ -1,9 +1,9 @@
-"""Shared advisor_route_constants for advisor selection and replies."""
+"""Shared constants for advisor selection and replies."""
 
 from __future__ import annotations
 
-ADVISOR_MODEL_TIER: str = "Sol"
-ADVISOR_CODEX_MODEL_ID: str = "gpt-5.6-sol"
+ADVISOR_MODEL_TIER: str = "Astra"
+ADVISOR_CODEX_MODEL_ID: str = "gpt-6-astra"
 ADVISOR_FALLBACK_TIER: str = "Fable"
 ADVISOR_FALLBACK_RESULT: str = "fable"
 ADVISOR_EFFORT_ENV_VAR: str = "ADVISOR_EFFORT"

package/_shared/advisor/scripts/config/advisor_scripts_constants/astra_advisor_constants.py

@@ -0,0 +1,38 @@
+"""Constants for the optional Codex Astra advisor bind."""
+
+from __future__ import annotations
+
+CODEX_EXECUTABLE: str = "codex"
+ADVISOR_CODEX_EXECUTABLE_ENV_VAR: str = "ADVISOR_CODEX_EXECUTABLE"
+CODEX_READ_ONLY_SANDBOX: str = "read-only"
+CODEX_JSON_FLAG: str = "--json"
+CODEX_MODEL_FLAG: str = "--model"
+CODEX_CONFIG_FLAG: str = "--config"
+CODEX_REASONING_CONFIG_TEMPLATE: str = 'model_reasoning_effort="{effort}"'
+CODEX_PROMPT_FROM_STDIN: str = "-"
+CODEX_EXEC_SUBCOMMAND: str = "exec"
+CODEX_RESUME_SUBCOMMAND: str = "resume"
+CODEX_SANDBOX_FLAG: str = "--sandbox"
+CLAUDE_CONFIG_DIRECTORY_NAME: str = ".claude"
+USAGE_PROBE_SHARED_DIRECTORY_NAME: str = "_shared"
+USAGE_PROBE_PACKAGE_DIRECTORY_NAME: str = "pr-loop"
+USAGE_PROBE_SCRIPTS_DIRECTORY_NAME: str = "scripts"
+USAGE_PROBE_FILENAME: str = "codex_usage_probe.py"
+ASTRA_SESSION_ID_METAVAR: str = "SESSION_ID"
+ASTRA_CODEX_TIMEOUT_SECONDS: float = 120.0
+ASTRA_USAGE_PROBE_TIMEOUT_SECONDS: float = 30.0
+ASTRA_ENV_VAR: str = "ADVISOR_ASTRA"
+ALL_ASTRA_TRUTHY_VALUES: frozenset[str] = frozenset({"1", "true", "yes", "on"})
+ASTRA_PREFLIGHT_FAILURE_REASON: str = "astra preflight did not establish an eligible Codex meter"
+ASTRA_BIND_FAILURE_REASON: str = "Codex Astra bind failed"
+ASTRA_REPLY_FAILURE_REASON: str = "Codex Astra returned no advisor guidance"
+ASTRA_PROBE_TIMEOUT_REASON: str = "Codex Astra meter check timed out"
+ASTRA_CODEX_TIMEOUT_REASON: str = "Codex Astra request timed out"
+ASTRA_MALFORMED_JSONL_REASON: str = "Codex Astra returned malformed JSONL"
+ASTRA_MISSING_SESSION_REASON: str = "Codex Astra returned no session id"
+ASTRA_INVALID_SIGNAL_REASON: str = "Codex Astra returned an invalid guidance signal"
+ASTRA_EXECUTABLE_NOT_FOUND_REASON: str = "Codex Astra could not find the codex executable on PATH"
+ASTRA_FALLBACK_KIND_DECLINED: str = "declined"
+ASTRA_FALLBACK_KIND_BROKEN: str = "broken"
+ASTRA_ENABLE_FLAG: str = "--enable-astra"
+ASTRA_EFFORT_FLAG: str = "--effort"

package/_shared/advisor/scripts/model_tier_run_validator.py

@@ -1,8 +1,7 @@
 """Mechanically validate a model-tier spawn-walk log.
 
 The advisor protocol's Model floor section emits a structured spawn-walk log.
-This validator reads that log back and checks its invariants. A run is judged
-from data, not inferred from a transcript.
+This validator reads that log back and checks its invariants.
 
 ::
 
@@ -24,12 +23,12 @@ from data, not inferred from a transcript.
 
     codex_bind = ModelTierRun(
         own_tier="Opus",
-        candidate_tiers=["Sol"],
-        attempts=[{"tier": "Sol", "result": "spawned"}],
-        selected_tier="Sol",
+        candidate_tiers=["Astra"],
+        attempts=[{"tier": "Astra", "result": "spawned"}],
+        selected_tier="Astra",
         host_profile="Codex",
     )
-    validate_model_tier_run(codex_bind)  # ok: Codex in-session Sol spawn
+    validate_model_tier_run(codex_bind)  # ok: Codex in-session Astra spawn
 
 A run whose selected_tier is not the first successful bind fails.
 On any broken invariant, validate_model_tier_run raises ModelTierRunError.
@@ -93,7 +92,7 @@ class ModelTierRun:
     attempts: list[dict[str, str]]
     selected_tier: str | None
     fallback_reason: str | None = None
-    is_sol_enabled: bool = False
+    is_astra_enabled: bool = False
     host_profile: str = HOST_PROFILE_CLAUDE
 
 
@@ -113,7 +112,7 @@ def _canonical_tier_list(all_tier_names: list[str]) -> list[str] | None:
 
 def _expected_candidate_tiers(
     own_tier: str,
-    is_sol_enabled: bool = False,
+    is_astra_enabled: bool = False,
     host_profile: str = HOST_PROFILE_CLAUDE,
 ) -> list[str]:
     maybe_canonical_own_tier = canonical_tier_name(own_tier)
@@ -127,7 +126,7 @@ def _expected_candidate_tiers(
     if maybe_canonical_host == HOST_PROFILE_CODEX:
         return [ADVISOR_MODEL_TIER]
     all_expected_candidates = [ADVISOR_FALLBACK_TIER]
-    if is_sol_enabled:
+    if is_astra_enabled:
         all_expected_candidates.append(ADVISOR_MODEL_TIER)
     return all_expected_candidates
 
@@ -164,11 +163,11 @@ def validate_model_tier_run(run: ModelTierRun) -> None:
         validate_model_tier_run(cli_bind)     # ok: CLI Claude-chain bind
         validate_model_tier_run(broken_log)   # flag: ModelTierRunError
 
-    Candidate tiers are Fable, plus Sol when ``is_sol_enabled`` is true, on
-    Claude and ThirdParty hosts. A Codex host walks Sol only. Consumer
-    ``own_tier`` is recorded and must be a known tier; it does not add Opus
+    Candidate tiers are Fable, plus Astra when ``is_astra_enabled`` is true, on
+    Claude and ThirdParty hosts. A Codex host walks Astra only. Consumer
+    ``own_tier`` is recorded and must be a known tier. It does not add Opus
     to the advisor walk. Tries walk that list in order. Early stop only
-    after ``spawned``, ``cli``, or Sol ``codex`` (and Sol ``spawned`` on a
+    after ``spawned``, ``cli``, or Astra ``codex`` (and Astra ``spawned`` on a
     Codex host). A null selected_tier requires a full walk plus
     fallback_reason.
 
@@ -183,7 +182,7 @@ def validate_model_tier_run(run: ModelTierRun) -> None:
     """
     all_expected_candidates = _expected_candidate_tiers(
         run.own_tier,
-        is_sol_enabled=run.is_sol_enabled,
+        is_astra_enabled=run.is_astra_enabled,
         host_profile=run.host_profile,
     )
     maybe_canonical_candidates = _canonical_tier_list(run.candidate_tiers)
@@ -257,9 +256,9 @@ def load_model_tier_run_from_json_path(from_path: Path) -> ModelTierRun:
         TypeError: When a field has the wrong shape.
     """
     parsed_payload = json.loads(from_path.read_text(encoding="utf-8"))
-    raw_sol_enabled = parsed_payload.get("sol_enabled", False)
-    if not isinstance(raw_sol_enabled, bool):
-        raise TypeError("sol_enabled must be a boolean")
+    raw_astra_enabled = parsed_payload.get("astra_enabled", False)
+    if not isinstance(raw_astra_enabled, bool):
+        raise TypeError("astra_enabled must be a boolean")
     raw_host_profile = parsed_payload.get(HOST_PROFILE_JSON_KEY, HOST_PROFILE_CLAUDE)
     if not isinstance(raw_host_profile, str):
         raise TypeError(HOST_PROFILE_MUST_BE_STRING_MESSAGE)
@@ -269,7 +268,7 @@ def load_model_tier_run_from_json_path(from_path: Path) -> ModelTierRun:
         attempts=list(parsed_payload["attempts"]),
         selected_tier=parsed_payload.get("selected_tier"),
         fallback_reason=parsed_payload.get("fallback_reason"),
-        is_sol_enabled=raw_sol_enabled,
+        is_astra_enabled=raw_astra_enabled,
         host_profile=raw_host_profile,
     )