ccx-native 0.0.1 → 0.2.0

package/ccx/codex/provenance.py

@@ -0,0 +1,105 @@
+"""CCX-owned client ids for the user messages CCX sends into Codex.
+
+Native Codex accepts an optional ``clientUserMessageId`` on ``turn/start`` and
+``turn/steer`` and persists it on the resulting ``userMessage`` item as
+``clientId``. That is the only durable, first-class way to tell — reading a
+thread back cold, possibly on another machine — which user messages CCX itself
+put there, and whether one started a turn or steered a running one.
+
+The id names the semantic user input, not a JSON-RPC attempt: an explicit
+overload retry re-sends the identical request and therefore reuses the same id,
+while a genuinely new input always gets a fresh one.
+
+Parsing is deliberately conservative. Only the exact format this module emits
+is recognized; an id written by another client, a malformed one, a legacy
+``null``, and anything CCX cannot prove it authored all stay unknown rather
+than being guessed at from position, text, or turn shape.
+"""
+
+from __future__ import annotations
+
+import re
+import uuid
+
+# Historical v1 native client message IDs remain immutable forensic facts.
+# Mint v2 only for new full-UUID owners; no rewrite of original operation IDs.
+FORMAT_VERSION = "v2"
+
+START = "start"
+STEER = "steer"
+KINDS = (START, STEER)
+
+_ORIGINS = {START: "ccx-start", STEER: "ccx-steer"}
+
+# Original short-keyed v1 native client IDs remain parseable but not
+# managed-worker addressing authority; v2 uses the complete owner UUID.
+_PATTERN = re.compile(
+    r"^ccx:"
+    r"v1:"
+    r"(?P<short>[0-9a-f]{8}):"
+    rf"(?P<kind>{START}|{STEER}):"
+    r"(?P<uuid>[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})$"
+)
+
+# Historical v1 IDs in existing native Codex threads remain forensic
+# provenance and are never rewritten. New full-UUID identities use v2
+# with one independent canonical full owner (no truncated alias).
+_PATTERN_V2 = re.compile(
+    r"^ccx:v2:"
+    r"(?P<workerId>[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}):"
+    rf"(?P<kind>{START}|{STEER}):"
+    r"(?P<uuid>[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})$"
+)
+
+
+def new_client_message_id(short: str, kind: str) -> str:
+    """Mint one id for a single semantic user input.
+
+    Carries no prompt text — an id ends up in a native thread CCX does not own
+    the retention of, so it must be pure provenance.
+    """
+    if kind not in KINDS:
+        raise ValueError(f"unknown client message kind: {kind!r}")
+    from ccx.store.identity import InvalidTarget, canonical_worker_id
+    try:
+        owner = canonical_worker_id(short)
+    except InvalidTarget as exc:
+        raise ValueError(
+            "new Codex clientUserMessageId requires canonical full CCX UUIDv4"
+        ) from exc
+    return f"ccx:{FORMAT_VERSION}:{owner}:{kind}:{uuid.uuid4()}"
+
+
+def parse_client_message_id(value: object) -> dict[str, str] | None:
+    """Decompose an id CCX can prove it authored, else ``None``."""
+    if not isinstance(value, str):
+        return None
+    match = _PATTERN_V2.match(value) or _PATTERN.match(value)
+    if match is None:
+        return None
+    parsed = match.groupdict()
+    # `uuid4()` produces the canonical lowercase form the pattern requires, so
+    # a value that parses but does not round-trip was not written by us.
+    if str(uuid.UUID(parsed["uuid"])) != parsed["uuid"]:
+        return None
+    return parsed
+
+
+def origin_of(value: object) -> str | None:
+    """``"ccx-start"``/``"ccx-steer"`` for a CCX id, ``None`` for anything else.
+
+    ``None`` is a real answer: the message exists and its origin is unknown.
+    """
+    parsed = parse_client_message_id(value)
+    return _ORIGINS[parsed["kind"]] if parsed else None
+
+
+__all__ = [
+    "FORMAT_VERSION",
+    "KINDS",
+    "START",
+    "STEER",
+    "new_client_message_id",
+    "origin_of",
+    "parse_client_message_id",
+]

package/ccx/codex/read.py

@@ -0,0 +1,29 @@
+"""Shared native Codex pending approval projection for CLI, WorkerClient and the public protocol."""
+from __future__ import annotations
+from typing import Any
+
+
+def pending_input(approvals: Any) -> dict[str, Any] | None:
+    """The cross-engine normalized pending-input object for Codex approvals.
+
+    The one projection ``peek``, ``WorkerClient`` and the public protocol share. A
+    Codex approval is never dressed up as a user question: Claude's
+    AskUserQuestion is a separate capability, so ``questions`` stays empty.
+    """
+    approvals = [value for value in approvals or [] if isinstance(value, dict)]
+    if not approvals:
+        return None
+    first = approvals[0]
+    message = first.get("reason") or first.get("command")
+    return {
+        "kind": "permission",
+        # Native request IDs may repeat after app-server restart. Only a real
+        # CCX gateId is actionable; historical previews cannot be decided.
+        "request_id": first.get("gateId") if isinstance(first.get("gateId"), str) else None,
+        "tool": first.get("kind"),
+        "message": message if isinstance(message, str) else (
+            None if message is None else str(message)
+        ),
+        "questions": [],
+        "native": {"pendingApprovals": approvals},
+    }

package/ccx/codex/records.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import time
+from typing import Any
+
+
+def now_ms() -> int:
+    return int(time.time() * 1000)
+
+
+def _uuid_codex_store():
+    """ACTIVE full-ID bootstrap before any Codex record filesystem operation."""
+    from ccx.constants import CCX_ROOT
+    from ccx.store.root import require_ccx_active
+    return require_ccx_active(CCX_ROOT)
+
+
+def read_record(target: str) -> dict[str, Any]:
+    """Read exact managed Codex full UUID, never short/name/thread alias."""
+    from ccx.store.identity import EngineMismatch
+    store = _uuid_codex_store()
+    owner = store.resolve(target)
+    if owner.engine != "codex":
+        raise EngineMismatch("Codex record lookup requires Codex full worker UUID")
+    return store.record(owner.worker)
+
+
+def write_record(record: dict[str, Any]) -> None:
+    """Require original exact whole-record revision, or refuse stale overwrite."""
+    from ccx.store.root import RecordConflict, StorageIntegrityError
+    if not isinstance(record, dict) or record.get("engine") != "codex":
+        raise StorageIntegrityError("Codex full-UUID record must preserve engine")
+    original_revision = record.get("recordRevision")
+    if type(original_revision) is not int or original_revision < 0:
+        raise RecordConflict(
+            "Codex whole-record snapshot needs current original recordRevision"
+        )
+    store = _uuid_codex_store()
+    updated = store.replace_record_if_revision(
+        f"codex:{record.get('workerId')}", record,
+        expected_revision=original_revision,
+    )
+    record.clear()
+    record.update(updated)
+
+
+def iter_records():
+    """Only full-UUID Codex global owners, not old codex/sessions short path."""
+    store = _uuid_codex_store()
+    for row in store.list_workers(engine="codex"):
+        yield store.record(row["worker"])

package/ccx/codex/reports.py

@@ -0,0 +1,177 @@
+"""Phase-aware selection of native Codex final assistant reports."""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+COMMENTARY_PHASE = "commentary"
+FINAL_ANSWER_PHASE = "final_answer"
+
+
+def native_timestamp_ms(value: Any) -> int | None:
+    """Convert a finite native Unix-seconds timestamp to integer milliseconds."""
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        try:
+            if math.isfinite(value):
+                return int(value * 1000)
+        except (OverflowError, ValueError):
+            pass
+    return None
+
+
+def report_from_item(
+    item: dict[str, Any] | None,
+    *,
+    turn_id: str | None,
+    completed_at: int | None = None,
+) -> dict[str, Any] | None:
+    """Return a report candidate for one completed native item.
+
+    Codex providers do not consistently populate ``phase``. A missing or null
+    phase is therefore deliberately accepted as the legacy compatibility
+    fallback, while explicit commentary is never a report.
+    """
+    if not isinstance(item, dict) or item.get("type") != "agentMessage":
+        return None
+    text = item.get("text")
+    if not text:
+        return None
+    phase = item.get("phase")
+    if phase == COMMENTARY_PHASE:
+        return None
+    if phase not in (None, FINAL_ANSWER_PHASE):
+        return None
+    return {
+        "text": str(text),
+        "turnId": turn_id,
+        "itemId": item.get("id"),
+        "phase": phase,
+        "completedAt": completed_at,
+    }
+
+
+def report_from_turn(turn: dict[str, Any] | None) -> dict[str, Any] | None:
+    """Select one completed turn's final answer, if it has one.
+
+    A strong ``final_answer`` candidate wins over every phase-less fallback in
+    the turn. Within either class, native item order determines the winner.
+    """
+    if not isinstance(turn, dict):
+        return None
+    turn_id = turn.get("id")
+    completed_at = native_timestamp_ms(turn.get("completedAt"))
+    strong = None
+    fallback = None
+    for item in turn.get("items") or []:
+        candidate = report_from_item(
+            item, turn_id=turn_id, completed_at=completed_at
+        )
+        if not candidate:
+            continue
+        if candidate["phase"] == FINAL_ANSWER_PHASE:
+            strong = candidate
+        else:
+            fallback = candidate
+    return strong or fallback
+
+
+def select_report_for_turn(
+    turn: dict[str, Any] | None, *,
+    live_report: dict[str, Any] | None = None,
+) -> dict[str, Any] | None:
+    """Prefer an exact-turn streamed final answer to a weaker history fallback.
+
+    Both codexd's live completion writer and its history observer use this
+    phase-aware rule; an unrelated turn's cached report is never borrowed.
+    """
+    selected = report_from_turn(turn)
+    turn_id = turn.get("id") if isinstance(turn, dict) else None
+    if (isinstance(live_report, dict)
+            and isinstance(turn_id, str) and turn_id
+            and live_report.get("turnId") == turn_id
+            and isinstance(live_report.get("text"), str)
+            and (selected is None or (
+                live_report.get("phase") == FINAL_ANSWER_PHASE
+                and selected.get("phase") != FINAL_ANSWER_PHASE))):
+        return live_report
+    return selected
+
+
+def report_from_thread(thread: dict[str, Any] | None) -> dict[str, Any] | None:
+    """Select the latest report candidate from completed native turns."""
+    if not isinstance(thread, dict):
+        return None
+    for turn in reversed(thread.get("turns") or []):
+        if not isinstance(turn, dict) or turn.get("status") != "completed":
+            continue
+        candidate = report_from_turn(turn)
+        if candidate:
+            return candidate
+    return None
+
+
+def should_replace_live_report(
+    current: dict[str, Any] | None,
+    candidate: dict[str, Any],
+) -> bool:
+    """Keep a strong final candidate ahead of a later legacy fallback."""
+    if not isinstance(current, dict):
+        return True
+    if candidate.get("phase") == FINAL_ANSWER_PHASE:
+        return True
+    return not (
+        current.get("turnId") == candidate.get("turnId")
+        and current.get("phase") == FINAL_ANSWER_PHASE
+    )
+
+
+def merge_report_cache(
+    existing: dict[str, Any] | None,
+    candidate: dict[str, Any],
+) -> dict[str, Any]:
+    """Merge historical evidence without degrading a precise live timestamp.
+
+    Item IDs remain native to their observation surface. Explicit final-answer
+    text and turn identity are the cross-surface evidence when those IDs differ.
+    """
+    if not isinstance(existing, dict):
+        return candidate
+    same_turn_and_text = (
+        existing.get("turnId") is not None
+        and candidate.get("turnId") is not None
+        and existing.get("turnId") == candidate.get("turnId")
+        and existing.get("text") == candidate.get("text")
+    )
+    same_item = (
+        existing.get("itemId") is not None
+        and candidate.get("itemId") is not None
+        and existing.get("itemId") == candidate.get("itemId")
+    )
+    same_explicit_final = (
+        existing.get("itemId") is not None
+        and candidate.get("itemId") is not None
+        and existing.get("phase") == FINAL_ANSWER_PHASE
+        and candidate.get("phase") == FINAL_ANSWER_PHASE
+    )
+    if (
+        same_turn_and_text
+        and (same_item or same_explicit_final)
+        and existing.get("phase") == candidate.get("phase")
+        and existing.get("completedAt") is not None
+    ):
+        return {**candidate, "completedAt": existing["completedAt"]}
+    return candidate
+
+
+__all__ = [
+    "COMMENTARY_PHASE",
+    "FINAL_ANSWER_PHASE",
+    "report_from_item",
+    "native_timestamp_ms",
+    "report_from_thread",
+    "report_from_turn",
+    "select_report_for_turn",
+    "merge_report_cache",
+    "should_replace_live_report",
+]