ccx-native 0.0.1 → 0.2.0

package/ccx/ops/background.py

@@ -0,0 +1,115 @@
+"""A small engine-neutral recorded snapshot of background work.
+
+Producers own these facts; consumers only read the saved summary/event.
+"""
+from __future__ import annotations
+
+import re
+import time
+
+KINDS = ("command", "monitor", "subagent", "notification")
+OPEN = {"running", "pending"}
+LABEL_LIMIT = 120
+EVENT_LIMIT = 1000
+ITEM_LIMIT = 100
+
+
+def label(value: object, fallback: str) -> str:
+    text = re.sub(r"\s+", " ", str(value)) if isinstance(value, str) else ""
+    text = "".join(ch for ch in text if ch.isprintable()).strip()
+    return text[:LABEL_LIMIT] or fallback
+
+
+def bounded_event(value: object) -> str | None:
+    """Bound one sanitized Monitor notification; labels remain much shorter."""
+    if not isinstance(value, str):
+        return None
+    return re.sub(r"\s+", " ", value).strip()[:EVENT_LIMIT]
+
+
+
+def summary(items: list[dict], *, as_of_ms: int | None = None,
+            available: bool = True) -> dict:
+    if as_of_ms is None:
+        as_of_ms = int(time.time() * 1000)
+    if not available:
+        return {
+            "running_count": None, "pending_count": None, "by_kind": None,
+            "items": [], "items_truncated": 0,
+            "as_of_ms": as_of_ms, "available": False,
+        }
+    active = [dict(item) for item in items
+              if item.get("status") in OPEN and item.get("kind") in KINDS]
+    by_kind = {kind: sum(item["kind"] == kind for item in active) for kind in KINDS}
+    # Sort once, before applying the display bound. Unknown start times are
+    # after known starts, then every item is ordered by stable ID.
+    active.sort(key=lambda item: (
+        item.get("started_at_ms") if type(item.get("started_at_ms")) is int
+        else float("inf"), item["id"]))
+    # Keep snapshots small and deterministic; avoid leaking native content.
+    preview = [{key: (bounded_event(item[key]) if key == "event" else item[key])
+                for key in ("id", "kind", "status", "label", "event", "event_count",
+                            "expires_at_ms", "notification_id", "delivery_id")
+                if key in item} for item in active[:ITEM_LIMIT]]
+    return {
+        "running_count": sum(by_kind[kind] for kind in KINDS if kind != "notification"),
+        "pending_count": by_kind["notification"],
+        "by_kind": by_kind, "items": preview,
+        "items_truncated": max(0, len(active) - len(preview)),
+        "as_of_ms": as_of_ms, "available": True,
+    }
+
+
+def materially_changed(previous: dict | None, current: dict) -> bool:
+    if previous is None:
+        return True
+    return {key: value for key, value in previous.items() if key != "as_of_ms"} != {
+        key: value for key, value in current.items() if key != "as_of_ms"}
+
+
+def claude_task_item(task: dict) -> dict | None:
+    task_id = task.get("task_id")
+    if not isinstance(task_id, str) or not task_id:
+        return None  # launching tool-result has not yet proved native task identity
+    native_kind = task.get("kind")
+    kind = "command" if native_kind == "bash" else native_kind
+    if kind not in ("command", "monitor", "subagent"):
+        return None
+    item = {
+        "id": f"{kind}:{task_id}", "kind": kind,
+        "status": task.get("status") or "unknown",
+        "label": label(task.get("description"), f"background {kind}"),
+        "tool_use_id": task.get("tool_use_id"),
+        "started_at_ms": task.get("launched_at"),
+    }
+    if kind == "monitor":
+        launched, timeout = task.get("launched_at"), task.get("timeout_ms")
+        item["expires_at_ms"] = (launched + timeout if type(launched) is int
+                                 and type(timeout) is int and timeout > 0 else None)
+        item["event_count"] = task.get("event_count") or 0
+        if task.get("last_event"):
+            item["event"] = bounded_event(task["last_event"])
+    if task.get("exit_code") is not None:
+        item["exit_code"] = task["exit_code"]
+    return item
+
+
+def diff_items(before: list[dict], after: list[dict]) -> list[tuple[str, dict]]:
+    """One source-row transition, never a second invented native observation."""
+    old = {item["id"]: item for item in before}
+    out = []
+    for item in after:
+        prior = old.get(item["id"])
+        if item == prior:
+            continue
+        status = item.get("status")
+        if prior is None or (prior.get("status") not in OPEN and status in OPEN):
+            transition = "reopened" if prior is not None else "started"
+        elif status not in OPEN and (prior is None or prior.get("status") in OPEN):
+            transition = {"completed": "finished", "failed": "failed",
+                          "stopped": "stopped"}.get(status, "event")
+        else:
+            transition = "event"
+        out.append((transition, item))
+    return out
+

package/ccx/ops/cancel.py

@@ -0,0 +1,296 @@
+from __future__ import annotations
+import time
+from typing import Any
+from ccx.errors import (
+    DeliveryRejected,
+    InvalidRequest,
+    OperationConflict,
+    SessionUnavailable,
+)
+from ccx.ops.common import split_target
+from ccx.ops.wait import reconcile_turn
+
+
+def _cancel_live_turn(handle: str, engine: str, worker_id: str,
+                      *, timeout: float = 0.5) -> tuple[bool, str | None]:
+    """Authenticated exact active turn, or UNKNOWN (never inferred from absence)."""
+    if engine == "claude":
+        from ccx.rpc.rpc import _rpc
+        reply = _rpc(handle, {"op": "status"}, timeout=timeout)
+        if reply.get("ok") is True and "activeTurnRef" in reply:
+            return True, reply["activeTurnRef"]
+        return False, None
+    from ccx.codex.runtime import daemon_rpc
+    from ccx.constants import CODEXD_RPC_GENERATION
+    reply = daemon_rpc({"op": "status", "short": worker_id,
+                        "rpcGeneration": CODEXD_RPC_GENERATION}, timeout=timeout)
+    if (reply.get("ok") is True and reply.get("loaded") is True
+            and "activeTurnId" in reply):
+        return True, ("ccx-turn:codex:v1:" + reply["activeTurnId"]
+                      if isinstance(reply["activeTurnId"], str) else None)
+    return False, None
+
+
+def cancel_turn(
+    target: str, *, cancellation_id: str, turn_ref: str,
+    timeout: float | None = 90,
+    expected_generation: str | None = None,
+) -> dict[str, Any]:
+    """Request one exact full-UUID turn interrupt, never replay its native write.
+
+    protocol cancellation_id is caller-owned. The existing GenerationStore 'cancel'
+    intent is the only ledger, independent of legacy short-keyed turn_cancel.
+    A native ACK means requested, not that model activity stopped.
+    """
+    from math import isfinite
+    from ccx import constants
+    from ccx.store.root import NativeEffectIndeterminate, require_ccx_active
+    from ccx.store.store import _digest
+    from ccx.store.identity import canonical_worker_id
+    from ccx.codex.delivery import receipt_for_turn as codex_receipt_for_turn
+
+    if (not isinstance(cancellation_id, str) or not cancellation_id
+            or len(cancellation_id) > 128 or "\x00" in cancellation_id):
+        raise InvalidRequest("cancellation_id must be nonempty and <=128 characters")
+    if (timeout is not None and (type(timeout) not in (int, float)
+                                 or not isfinite(timeout) or timeout <= 0)):
+        raise InvalidRequest("cancel timeout must be positive finite seconds")
+    handle, engine, worker_id = split_target(target)
+    canonical_worker_id(worker_id)
+    prefix = f"ccx-turn:{engine}:v1:"
+    if not isinstance(turn_ref, str) or not turn_ref.startswith(prefix) or not turn_ref[len(prefix):]:
+        raise InvalidRequest("turn_ref must name an exact managed turn for the selected engine")
+    native_turn_id = turn_ref[len(prefix):] if engine == "codex" else None
+    store = require_ccx_active(constants.CCX_ROOT,
+                               expected_generation=expected_generation)
+    rec = store.record(handle)
+    source = rec.get("native") or {}
+    if (engine == "claude" and not isinstance(source.get("sessionId"), str)) or (
+        engine == "codex" and (not isinstance(source.get("threadId"), str)
+        or source.get("threadSource") != store.codex_source(handle))
+    ):
+        raise SessionUnavailable("original native worker binding is not verified")
+    identity = _digest({"workerId": worker_id, "engine": engine,
+                        "turnRef": turn_ref, "operation": "cancel"})
+    prior = store.read_receipt(handle, "cancel", cancellation_id)
+    if prior is not None and prior.get("intentSha256") != identity:
+        raise OperationConflict("cancellation_id already names a different turn",
+                                short=worker_id[:8], worker_id=worker_id)
+    # In particular, an invented native id is never a cancel capability.
+    if engine == "codex":
+        from ccx.codex.delivery import DeliveryReceiptError
+        try:
+            opening = codex_receipt_for_turn(handle, native_turn_id)
+        except DeliveryReceiptError:
+            # A damaged receipt somewhere proves nothing about this turn;
+            # the live exact turn below still decides, as with no receipt.
+            opening = None
+    else:
+        from ccx.claude.delivery import iter_receipts
+        opening = next((row for row in iter_receipts(handle)
+                        if row.get("turnRef") == turn_ref
+                        and row.get("route") == "new_turn"), None)
+    if prior is None and (not isinstance(opening, dict)
+                          or opening.get("state") != "accepted"):
+        # Some genuine turns start without a CCX delivery receipt: human input
+        # on the shared managed Claude PTY, or a parent notification on Codex.
+        # Do not fabricate one: the live authenticated runtime's exact active
+        # turn is sufficient to request a one-shot native interrupt, under the
+        # same durable cancel intent. An absent/invented/stale turn is refused.
+        known, active = _cancel_live_turn(handle, engine, worker_id)
+        store.revalidate()
+        if not known or active != turn_ref:
+            raise DeliveryRejected("exact active turn has no original accepted delivery receipt",
+                                   short=worker_id[:8])
+    deadline = None if timeout is None else time.monotonic() + timeout
+
+    def public(state: str, *, outcome=None, reason=None, owned=False,
+               receipt=None) -> dict[str, Any]:
+        return {
+            "worker": {"worker": handle, "worker_id": worker_id,
+                       "engine": engine, "short": worker_id[:8]},
+            "cancellation_id": cancellation_id, "turn_ref": turn_ref,
+            "status": state, "confirmed": state == "confirmed",
+            "owned": owned, "accepted": bool(receipt and receipt.get("state") == "accepted"),
+            "recommended_action": ("retry_same_id" if state == "prepared"
+                                   else "wait" if state == "submitted" else "none"),
+            "outcome": outcome, "reason": reason,
+            "receipt": receipt,
+        }
+
+    def observe(receipt: dict) -> dict | None:
+        # Original semantic receipt is the only proof of completed assistant
+        # text. A changed live ref proves INACTIVITY, not why the turn stopped.
+        def exact_claude_terminal() -> dict | None:
+            last = store.record(handle).get("lastSettledTurn") or {}
+            if (last.get("turnRef") == turn_ref
+                    and last.get("outcome") in {"interrupted", "completed", "failed"}):
+                return public("confirmed", outcome=last["outcome"],
+                              owned=True, receipt=receipt)
+            return None
+
+        if engine == "codex":
+            from ccx.codex.delivery import DeliveryReceiptError
+            try:
+                seen = reconcile_turn(handle, turn_id=native_turn_id,
+                                      expected_generation=store.generation)
+            except DeliveryReceiptError:
+                seen = {}  # no receipt evidence; the live turn below decides
+            if seen.get("status") == "settled":
+                return public("confirmed", outcome="completed", owned=True,
+                              receipt=receipt)
+            if seen.get("native_status") in ("interrupted", "cancelled"):
+                return public("confirmed", outcome="interrupted", owned=True,
+                              receipt=receipt)
+        else:
+            from ccx.claude.delivery import read_receipt
+            latest = read_receipt(handle, opening["deliveryId"]) if opening else None
+            if (latest and latest.get("turnRef") == turn_ref
+                    and isinstance(latest.get("settlement"), dict)):
+                return public("confirmed", outcome="completed", owned=True,
+                              receipt=receipt)
+            # Positive completed-answer receipt wins above. Otherwise the
+            # exact original host finalizer proves this turn's outcome for
+            # both human and receipt-backed cancellations; it does not invent
+            # an opening delivery receipt or completed assistant text.
+            terminal = exact_claude_terminal()
+            if terminal is not None:
+                return terminal
+        known, active = _cancel_live_turn(handle, engine, worker_id)
+        store.revalidate()
+        if known and active != turn_ref:
+            if engine == "claude":
+                # The terminal CAS can land between our first record read and
+                # the host status RPC. Reread the same exact source before
+                # falling back to unknown; never report an invented outcome.
+                terminal = exact_claude_terminal()
+                if terminal is not None:
+                    return terminal
+            return public("confirmed", outcome="unknown", owned=True,
+                          receipt=receipt)
+        return None
+
+    # No preflight can replace the provider's expected-turn check, but an
+    # observed IDLE/other turn can reject without any native effect at all.
+    if prior is None or prior.get("state") == "prepared":
+        store.authorize_native_action(handle, "cancel")
+        known, active = _cancel_live_turn(handle, engine, worker_id)
+        if not known:
+            return public("prepared", reason="live active turn not proven")
+        if active != turn_ref:
+            return public("rejected", reason="active turn changed or no active turn")
+        attempt = store.begin_native_intent(
+            handle, family="cancel", action="cancel", operation_id=cancellation_id,
+            intent_sha256=identity,
+        )
+        if attempt.replayed:
+            prior = store.read_receipt(handle, "cancel", cancellation_id)
+        else:
+            from ccx.constants import CODEXD_RPC_GENERATION
+            from ccx.codex.runtime import daemon_rpc
+            from ccx.rpc.rpc import _rpc
+            budget = min(2., max(.01, deadline - time.monotonic())) if deadline else 2.
+            def submit(seconds):
+                if engine == "claude":
+                    return _rpc(handle, {"op": "interrupt",
+                                         "expected_turn_ref": turn_ref}, timeout=seconds)
+                return daemon_rpc({"op": "interrupt", "short": worker_id,
+                                   "expectedTurnId": native_turn_id,
+                                   "rpcGeneration": CODEXD_RPC_GENERATION}, timeout=seconds)
+            try:
+                reply = store.dispatch_native_intent_once(
+                    attempt, bounded_submit=submit, dispatch_budget_s=budget)
+            except NativeEffectIndeterminate:
+                # Durable submitted-unknown; a same-ID caller only observes.
+                prior = store.read_receipt(handle, "cancel", cancellation_id)
+                return public("submitted", reason="original interrupt reply unknown",
+                              owned=True, receipt=prior)
+            if (reply.get("ok") is True and
+                    (engine == "codex" and reply.get("turnId") == native_turn_id
+                     or engine == "claude" and reply.get("turnRef") == turn_ref
+                     and (reply.get("sent") is True or
+                          (reply.get("sent") is False and
+                           reply.get("already_observing") is True)))):
+                # A prior same-turn Escape is accepted, never proof of completion.
+                state = "accepted"
+            elif reply.get("ok") is False and reply.get("definitive") is True:
+                state = "rejected"
+            else:
+                prior = store.read_receipt(handle, "cancel", cancellation_id)
+                return public("submitted", reason="native interrupt not positively acknowledged",
+                              owned=True, receipt=prior)
+            prior = store.settle_native_intent(
+                attempt, state=state, native_evidence_sha256=_digest({
+                    "workerId": worker_id, "turnRef": turn_ref, "reply": reply,
+                }),
+            )
+            if state == "rejected":
+                return public("rejected", reason=str(reply.get("error")), receipt=prior)
+    if prior is None:
+        prior = store.read_receipt(handle, "cancel", cancellation_id)
+    if prior.get("state") == "rejected":
+        return public("rejected", reason="original native interrupt refused", receipt=prior)
+    # Acceptance and caller timeout do not mutate the durable native effect:
+    # a later same-ID call may still observe terminality, but cannot re-dispatch.
+    while True:
+        store.revalidate()
+        try:
+            verified = observe(prior)
+        except (SessionUnavailable, OSError):
+            store.revalidate()  # changed ACTIVE is not a temporary daemon loss
+            verified = None  # temporary runtime loss is NOT changed-turn proof
+        if verified is not None:
+            return verified
+        if deadline is not None and time.monotonic() >= deadline:
+            return public("unknown", reason="exact target terminality not proven",
+                          owned=True, receipt=prior)
+        time.sleep(.2 if deadline is None else
+                   min(.2, max(0., deadline-time.monotonic())))
+
+
+def stop_worker(
+    target: str, *, timeout: float | None = 1.0,
+    expected_turn_ref: str | None = None,
+    expected_generation: str | None = None,
+) -> dict[str, Any]:
+    """One explicit stop request, fresh ID, exact ref; acceptance is not completion."""
+    from uuid import uuid4
+    from ccx import constants
+    from ccx.errors import TurnIncomplete
+    from ccx.store.root import require_ccx_active
+
+    handle, engine, worker_id = split_target(target)
+    store = require_ccx_active(constants.CCX_ROOT,
+                               expected_generation=expected_generation)
+    if expected_turn_ref is None:
+        known, active = _cancel_live_turn(handle, engine, worker_id)
+        store.revalidate()
+        if not known:
+            raise SessionUnavailable("stop: active turn could not be observed",
+                                     short=worker_id[:8])
+        if not active:
+            raise DeliveryRejected("stop: worker has no active turn",
+                                   short=worker_id[:8])
+    else:
+        active = expected_turn_ref  # cancel_turn validates the exact ref.
+    result = cancel_turn(handle, cancellation_id=str(uuid4()),
+                         turn_ref=active, timeout=timeout,
+                         expected_generation=store.generation)
+    if result["status"] == "rejected":
+        raise DeliveryRejected(result.get("reason") or "active turn changed",
+                               short=worker_id[:8],
+                               operation_id=result["cancellation_id"])
+    if result["status"] == "prepared":
+        raise SessionUnavailable("stop: original interrupt not submitted",
+                                 short=worker_id[:8])
+    if not result.get("accepted"):
+        error = TurnIncomplete(
+            "stop: native interrupt acceptance unconfirmed; "
+            "reconcile the original cancellation ID, do not repeat it",
+            short=worker_id[:8], turn_status=result["status"],
+        )
+        error.cancellation_id = result["cancellation_id"]
+        error.turn_ref = result["turn_ref"]
+        error.worker_id = worker_id
+        raise error
+    return result

package/ccx/ops/codex_import.py

@@ -0,0 +1,96 @@
+"""Fork a user-owned native Codex thread into a separate ordinary CCX worker."""
+from __future__ import annotations
+
+import time
+from uuid import UUID
+
+from ccx.errors import InvalidRequest, SessionUnavailable
+from ccx.ops.creation_steps import validated_create_spec
+from ccx.ops.creation import create
+from ccx.store.identity import mint_worker_id
+from ccx.constants import DEFAULT_IDLE_TIMEOUT_S
+
+
+def import_thread(
+    thread_id: str, *, source: dict | None = None,
+    model: str | None = None, effort: str | None = None,
+) -> dict:
+    """Only the child is native-mutated; the original may remain open in Codex.
+
+    Importing a second time intentionally forks a second independent child.
+    """
+    if not isinstance(thread_id, str):
+        raise InvalidRequest("Codex import needs an exact native thread UUID")
+    try:
+        if str(UUID(thread_id)) != thread_id:
+            raise ValueError("noncanonical")
+    except (ValueError, TypeError, AttributeError) as exc:
+        raise InvalidRequest("Codex import needs an exact native thread UUID") from exc
+    if any(value is not None and (not isinstance(value, str) or not value.strip())
+           for value in (model, effort)):
+        raise InvalidRequest("import model/effort overrides must be nonempty strings")
+    if source is None:
+        from ccx.codex.runtime import read_import_source
+        source = read_import_source(thread_id)
+    thread = source.get("thread") if isinstance(source, dict) else None
+    last = source.get("lastTurn") if isinstance(source, dict) else None
+    if not isinstance(thread, dict) or thread.get("id") != thread_id:
+        raise SessionUnavailable("Codex import native thread ID was not confirmed")
+    status = thread.get("status")
+    status = status.get("type") if isinstance(status, dict) else status
+    if status not in (None, "idle", "notLoaded"):
+        raise SessionUnavailable("Codex source has an active turn; wait for it to finish")
+    if (not isinstance(last, dict) or not isinstance(last.get("id"), str)
+            or not last["id"] or last.get("status") != "completed"):
+        raise SessionUnavailable(
+            "Codex import needs a latest completed native turn; no worker created"
+        )
+    cwd = thread.get("cwd")
+    if not isinstance(cwd, str) or not cwd:
+        raise SessionUnavailable("Codex source has no recorded workspace")
+    # Native metadata may omit the latest model context. Never infer it from
+    # prose/rollout files; leave omitted settings at the normal CCX defaults.
+    native_model = last.get("model") or thread.get("model")
+    native_effort = (last.get("reasoningEffort") or last.get("effort")
+                     or thread.get("reasoningEffort"))
+    chosen_model = model if model is not None else (
+        native_model if isinstance(native_model, str) and native_model.strip() else None
+    )
+    chosen_effort = effort if effort is not None else (
+        native_effort if isinstance(native_effort, str) and native_effort.strip() else None
+    )
+    directory, args = validated_create_spec(
+        engine="codex", cwd=cwd, model=chosen_model, effort=chosen_effort,
+        idle_timeout=DEFAULT_IDLE_TIMEOUT_S, permissions="full",
+        sandbox=None, approval_policy=None, agent=None,
+        append_system_prompt=None, allowed_tools=None, disallowed_tools=None,
+        add_dir=None, permission_mode=None,
+    )
+    from ccx.codex.runtime import validate_model
+    if model is not None:
+        validate_model(model, cwd=directory)
+    name = thread.get("name") or thread.get("title")
+    if not isinstance(name, str) or not name.strip():
+        name = None
+    completed_at = last.get("completedAt")
+    last_at = (int(completed_at * 1000)
+               if type(completed_at) in (float, int) and completed_at > 0 else None)
+    worker_id = mint_worker_id()
+    anchor = {
+        "engine": "codex", "sourceKind": "codex-thread",
+        "sourceWorkerId": None, "sourceNativeThreadId": thread_id,
+        "lastTurnId": last["id"], "cwd": directory,
+        "createArgs": args,
+        # The newest page cannot attest the historical total; zero here
+        # counts managed submissions, NOT all source turns.
+        "seed": {"stats": {"turns": 0}, "lastTurnAt": last_at,
+                 "lastTurn": {"turnId": last["id"], "status": "completed"}},
+        "overrides": {"model": model, "effort": effort},
+        "forkedAtMs": int(time.time() * 1000),
+    }
+    return create(
+        engine="codex", cwd=directory, worker_id=worker_id, name=name,
+        model=chosen_model, effort=chosen_effort,
+        permissions="full", idle_timeout=DEFAULT_IDLE_TIMEOUT_S,
+        created_via="import", _fork_anchor=anchor, start_timeout=90,
+    )