ccx-native 0.1.0 → 0.2.0

package/ccx/ops/report.py

@@ -417,12 +417,14 @@ def report_worker(
                     if engine == "codex" else claude_delivery.iter_receipts(handle))
     from ccx.ops import turn_reports
     native_turn = turn_reports._ref_id(turn_ref, engine=engine)
+    # A Codex steer only joins a turn it did not open and never gets that
+    # turn's settlement, so it is no claim on the turn's report: without an
+    # opening receipt, the turn is reported from its exact native history.
     has_receipt = any(
-        row.get("turnRef") == turn_ref
-        or (engine == "claude" and row.get("targetTurnRef") == turn_ref)
-        or (engine == "codex" and native_turn in (
-            row.get("turnId"), row.get("targetTurnId")
-        ))
+        (row.get("turnRef") == turn_ref
+         or (engine == "claude" and row.get("targetTurnRef") == turn_ref)
+         or (engine == "codex" and row.get("turnId") == native_turn))
+        and not (engine == "codex" and codex_delivery.route(row) == "steer")
         for row in receipts
     )
     if not has_receipt:
@@ -466,6 +468,7 @@ def report_worker(
         for candidate in receipts:
             if (candidate.get("state") == "accepted"
                     and not candidate.get("settlement")
+                    and codex_delivery.route(candidate) != "steer"
                     and candidate.get("turnRef") == turn_ref):
                 reconcile_turn(
                     handle, delivery_id=candidate["deliveryId"],

package/ccx/ops/turn_reports.py

@@ -167,6 +167,34 @@ def codex_native_turn_evidence(
     return {"status": terminals[0]["status"], "error": terminals[0].get("error")}
 
 
+def _codex_journal_contradicts(
+    child: str, record: dict, thread_id: str, turn_id: str,
+) -> bool:
+    """Does the local journal say anything against R being a completed turn?
+
+    Missing evidence (a gap elsewhere in the journal, or none for R) is not a
+    contradiction; another thread, a compaction or a non-completed terminal is.
+    """
+    from ccx.codex.evidence import build_index, read_journal
+
+    if ((record.get("activeCompact") or {}).get("turnId") == turn_id
+            or (record.get("lastCompact") or {}).get("turnId") == turn_id):
+        return True
+    journal = read_journal(child)
+    index = build_index(journal, health=record.get("evidence"))
+    if any(item.get("itemType") == "contextCompaction"
+           for item in index["items"].get(turn_id, {}).values()):
+        return True
+    events = [event for event in journal.events if event.get("turnId") == turn_id]
+    if any(event.get("threadId") != thread_id for event in events):
+        return True
+    return any(
+        not isinstance(turn, dict) or turn.get("id") != turn_id
+        or turn.get("status") != "completed"
+        for turn in ((event.get("params") or {}).get("turn") for event in events
+                     if event.get("method") == "turn/completed"))
+
+
 def codex_source_report(
     thread: dict, worker_id: str, thread_id: str, turn_id: str,
     *, expected_source: str,
@@ -177,7 +205,9 @@ def codex_source_report(
         raise SessionUnavailable("Codex conversation belongs to another worker; check the worker")
     turns = [turn for turn in (thread.get("turns") or [])
              if isinstance(turn, dict) and turn.get("id") == turn_id]
-    if len(turns) != 1 or turns[0].get("status") != "completed":
+    if (len(turns) != 1 or turns[0].get("status") != "completed"
+            or any(isinstance(item, dict) and item.get("type") == "contextCompaction"
+                   for item in turns[0].get("items") or [])):
         raise SessionUnavailable("Completed Codex turn is unavailable; inspect worker status")
     selected = report_from_turn(turns[0])
     return {
@@ -287,10 +317,22 @@ def exact_report(
         result["completed_at"] = terminal.get("settledAtMs")
     elif owner.engine == "codex":
         proof = codex_native_turn_evidence(child, record, original, turn_id)
-        if proof is None:
-            raise SessionUnavailable("Codex completion record is missing; check status")
-        if proof["status"] is None:
-            raise OperationConflict("Codex turn is not complete; wait before reporting")
+        if proof is None or proof["status"] is None:
+            # The local journal cannot prove R: a gap elsewhere in it, or R's
+            # completion was missed. Unless it contradicts R, the exact
+            # source-verified native history decides: codex_source_report
+            # needs R itself completed there, and says so when it is not.
+            started = proof is not None
+            native_done = isinstance(thread, dict) and any(
+                isinstance(turn, dict) and turn.get("id") == turn_id
+                and turn.get("status") == "completed"
+                for turn in thread.get("turns") or [])
+            if (thread is None or (started and not native_done)
+                    or _codex_journal_contradicts(child, record, original, turn_id)):
+                if started:
+                    raise OperationConflict("Codex turn is not complete; wait before reporting")
+                raise SessionUnavailable("Codex completion record is missing; check status")
+            proof = {"status": "completed"}
         if proof["status"] != "completed":
             raise SessionUnavailable("Codex turn ended without completion; inspect worker status")
         if thread is None:

package/ccx/ops/worker_events.py

@@ -491,7 +491,7 @@ def _recorded_state(store: GenerationStore, target: str) -> dict:
 def wait_full_uuid_event_page(
     store: GenerationStore, target: str, *, after: str | None = None,
     tail: int | None = None, limit: int = 200, kinds: list[str] | None = None,
-    wait: float = 0.0, native: bool = False,
+    wait: float = 0.0, native: bool = False, seen_live: bool = False,
 ) -> dict:
     """One same-generation held page; stat the owned journal before re-hashing.
 
@@ -510,6 +510,9 @@ def wait_full_uuid_event_page(
         native=native,
     )
     observer = RuntimeObserver(store, target)
+    # A follow that last reported live: a runtime gone before this read's
+    # first sample is still a change, reported at once.
+    observer.seen_live = seen_live
     observer.sample()
 
     def done(current: dict, gap, timed_out: bool) -> dict:
@@ -605,6 +608,7 @@ def follow_full_uuid_events(
             page = wait_full_uuid_event_page(
                 store, target, after=cursor, kinds=kinds,
                 limit=MAX_PAGE_EVENTS, wait=duration, native=native,
+                seen_live=runtime == "live",
             )
             # Presence comes from the held read only; an unheld page is one sample.
             changed, runtime = page["runtime"] != runtime, page["runtime"]

package/ccx/store/paths.py

@@ -142,10 +142,6 @@ def record_path(short: str) -> pathlib.Path:
     return _owner_path(short, "record.json")
 
 
-def transcript_json_path(short: str) -> pathlib.Path:
-    return _owner_path(short, "transcript.json")
-
-
 def statusline_json_path(short: str) -> pathlib.Path:
     return _owner_path(short, "statusline.json")
 

package/ccx/store/root.py

@@ -298,32 +298,17 @@ def _read_json(fd: int, name: str, *, max_bytes: int = _FILE_LIMIT) -> dict | No
     return val
 
 
-def _write_json(
-    fd: int, name: str, value: Mapping, *, rendered_transcript: bool = False,
-) -> None:
+def _write_json(fd: int, name: str, value: Mapping) -> None:
     """Fsync new 0600 inode, same-directory atomic replace and directory fsync.
 
-    A cleaned Claude transcript is the one legacy JSON exception: its public
-    schema retains indented turns and may exceed the generic 4 MiB metadata
-    limit. Keep this explicit filename-scoped producer mode; all other store
-    writes retain their original byte format and strict metadata bound. The
-    runtime sidecar reader remains independently bounded to 4 MiB.
+    Every owned JSON file is compact and bounded to 4 MiB.
     """
     if not name or "/" in name or name in (".", ".."):
         raise StorageIntegrityError("unsafe owned output basename")
-    if rendered_transcript:
-        if name != "transcript.json":
-            raise StorageIntegrityError("pretty unlimited JSON only allowed for owned transcript")
-        # The previous renderer used json.dumps(..., indent=2)'s default
-        # ensure_ascii=True. Preserve its surrogate-safe escaping and Unicode
-        # roundtrip; only this rendered-transcript branch changes, not the
-        # generic compact metadata writer below.
-        raw = json.dumps(value, indent=2, ensure_ascii=True, allow_nan=False).encode("utf-8")
-    else:
-        raw = (json.dumps(value, sort_keys=True, separators=(",", ":"),
-                          ensure_ascii=False, allow_nan=False) + "\n").encode("utf-8")
-        if len(raw) > _FILE_LIMIT:
-            raise StorageIntegrityError("owned JSON exceeds bounded writer size")
+    raw = (json.dumps(value, sort_keys=True, separators=(",", ":"),
+                      ensure_ascii=False, allow_nan=False) + "\n").encode("utf-8")
+    if len(raw) > _FILE_LIMIT:
+        raise StorageIntegrityError("owned JSON exceeds bounded writer size")
     name_tmp = ".new-" + uuid4().hex
     output_fd = os.open(
         name_tmp, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW | os.O_CLOEXEC,

package/ccx/store/store.py

@@ -663,7 +663,7 @@ class GenerationStore:
         Host/client readers use this rather than opening an unpinned
         pathname returned by worker_path().
         """
-        if filename not in ("record.json", "settings.json", "transcript.json",
+        if filename not in ("record.json", "settings.json",
                             "statusline.json", "compact.json",
                             "context-observation.json"):
             raise StorageIntegrityError("unsupported CCX-owned JSON worker sidecar")
@@ -673,7 +673,7 @@ class GenerationStore:
                 return _read_json(dir_fd, filename)
 
     def worker_path(self, target: str, filename: str = "record.json") -> Path:
-        if filename not in ("record.json", "settings.json", "transcript.json",
+        if filename not in ("record.json", "settings.json",
                             "statusline.json", "events.ndjson",
                             "evidence.jsonl", "compact.json", "context-observation.json"):
             raise StorageIntegrityError("unknown worker sidecar family")

package/ccx/system/private_json.py

@@ -0,0 +1,54 @@
+"""Private JSON files shared by account-level caches and settings."""
+
+from __future__ import annotations
+
+import errno
+import json
+import os
+from pathlib import Path
+import stat
+import tempfile
+
+
+def _open_private_file(path: Path) -> int:
+    """Do not trust a symlink, another owner's file, or a readable private record."""
+    fd = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
+    st = os.fstat(fd)
+    if not stat.S_ISREG(st.st_mode) or st.st_uid != os.getuid() or st.st_mode & 0o077:
+        os.close(fd)
+        raise PermissionError(f"not a private regular file owned by this user: {path}")
+    return fd
+
+
+def _read_private_json(path: Path) -> dict | None:
+    with os.fdopen(_open_private_file(path), "rb") as handle:
+        value = json.load(handle)
+    return value if isinstance(value, dict) else None
+
+
+def _atomic_private_json(path: Path, value: dict) -> None:
+    path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    tmp = None
+    try:
+        fd, tmp = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+        with os.fdopen(fd, "w", encoding="utf-8") as out:
+            json.dump(value, out, separators=(",", ":"), allow_nan=False)
+            out.flush()
+            os.fsync(out.fileno())
+        # Never overwrite a planted symlink/foreign file at the final path.
+        try:
+            existing = _open_private_file(path)
+        except FileNotFoundError:
+            pass
+        except OSError as exc:
+            # Replacing a planted symlink itself is safe: os.replace never
+            # follows the destination. Its target is neither read nor written.
+            if exc.errno != errno.ELOOP:
+                raise
+        else:
+            os.close(existing)
+        os.replace(tmp, path)
+        tmp = None
+    finally:
+        if tmp is not None:
+            os.unlink(tmp)

package/ccx/types.py

@@ -634,6 +634,108 @@ class Event:
         )
 
 
+@dataclass(frozen=True)
+class ModelInfo:
+    """One selectable model name and its engine-neutral capabilities."""
+
+    id: str
+    resolved: str | None
+    display_name: str
+    description: str | None
+    alias: bool
+    default: bool
+    efforts: list[str] = field(default_factory=list)
+    default_effort: str | None = None
+    features: dict[str, bool] = field(default_factory=dict)
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "resolved": self.resolved,
+            "displayName": self.display_name,
+            "description": self.description,
+            "alias": self.alias,
+            "default": self.default,
+            "efforts": list(self.efforts),
+            "defaultEffort": self.default_effort,
+            "features": dict(self.features),
+        }
+
+    @classmethod
+    def from_dict(cls, value: dict) -> "ModelInfo":
+        ident = value.get("id")
+        resolved = value.get("resolved")
+        name = value.get("displayName")
+        if (not isinstance(ident, str) or not ident
+                or (resolved is not None and not isinstance(resolved, str))
+                or not isinstance(name, str) or not name):
+            raise ValueError("invalid cached model")
+        efforts = value.get("efforts")
+        features = value.get("features")
+        return cls(
+            id=ident,
+            resolved=resolved,
+            display_name=name,
+            description=(value.get("description")
+                         if isinstance(value.get("description"), str) else None),
+            alias=(ident != resolved),
+            default=value.get("default") is True,
+            efforts=([s for s in efforts if isinstance(s, str)]
+                     if isinstance(efforts, list) else []),
+            default_effort=(value.get("defaultEffort")
+                            if isinstance(value.get("defaultEffort"), str) else None),
+            features=({
+                key: features[key] for key in ("fast", "auto", "thinkingOff")
+                if type(features.get(key)) is bool
+            } if isinstance(features, dict) else {}),
+        )
+
+
+@dataclass(frozen=True)
+class ModelCatalog:
+    """One engine's model list, with freshness and failure provenance."""
+
+    engine: str
+    engine_version: str | None
+    source: str
+    fetched_at: str
+    note: str | None
+    models: list[ModelInfo] = field(default_factory=list)
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "engine": self.engine,
+            "engineVersion": self.engine_version,
+            "source": self.source,
+            "fetchedAt": self.fetched_at,
+            "note": self.note,
+            "models": [model.as_dict() for model in self.models],
+        }
+
+    @classmethod
+    def from_dict(cls, value: dict) -> "ModelCatalog":
+        engine = value.get("engine")
+        fetched_at = value.get("fetchedAt")
+        models = value.get("models")
+        if (engine not in ("claude", "codex")
+                or not isinstance(fetched_at, str)
+                or not isinstance(models, list)):
+            raise ValueError("invalid cached model catalog")
+        entries = [ModelInfo.from_dict(item) for item in models
+                   if isinstance(item, dict)]
+        if not entries:
+            raise ValueError("empty cached model catalog")
+        version = value.get("engineVersion")
+        return cls(
+            engine=engine,
+            engine_version=version if isinstance(version, str) else None,
+            source="live",
+            fetched_at=fetched_at,
+            note=None,
+            models=entries,
+        )
+
+
 @dataclass(frozen=True)
 class Usage:
     """Live quota utilization plus provider-normalized session-reset status.
@@ -700,6 +802,8 @@ __all__ = [
     "SteerResult",
     "WaitResult",
     "Event",
+    "ModelInfo",
+    "ModelCatalog",
     "Usage",
     "FiveHourReset",
 ]

package/ccx/workers.py

@@ -6,7 +6,6 @@ CCX worker UUIDs independently of provider-native identifiers."""
 from __future__ import annotations
 import ccx.cli.commands.read as commands_read
 
-import json
 import os
 import signal
 import time
@@ -44,7 +43,7 @@ from .errors import (
     worker_not_found,
 )
 from ccx.store.liveness import pid_alive, recorded_host_loaded
-from ccx.store.paths import sock_path, statusline_json_path
+from ccx.store.paths import sock_path
 from ccx.store.records import merge_lifecycle
 from ccx.rpc.rpc import _respawn, _respawn_failure_message, _rpc
 from ccx.ops.semantics import KIND_ELICITATION, pending_input_kind
@@ -178,6 +177,43 @@ def _codex_record(short: str) -> dict:
 
 
 
+def _mark_recent_window(document: dict, limit: int, warning: str) -> None:
+    """Label a document that holds only the newest part of a history.
+
+    A bounded tail cannot claim global 1-based turn numbers, nor pretend to
+    describe the complete native history.
+    """
+    for turn in document["turns"]:
+        turn["sequence"] = None
+    complete = document["completeness"]
+    complete["sourceLimited"] = True
+    if complete.get("status") != "partial":  # partial outranks source-limited
+        complete["status"] = "source-limited"
+    complete["warnings"] = [*(complete.get("warnings") or []), warning]
+    document["peekHistoryWindow"] = {"kind": "recent", "limit": limit}
+
+
+def _note_history_db(document: dict, thread: dict) -> None:
+    """Say what a document read from Codex's local history database can't vouch for."""
+    from ccx.codex.history_store import VERIFIED_SCHEMA_VERSION
+
+    complete = document["completeness"]
+    warnings = list(complete.get("warnings") or [])
+    version = thread.get("historyDbVersion")
+    if version != VERIFIED_SCHEMA_VERSION:
+        warnings.append(
+            f"read from Codex's local history database, schema version {version} "
+            f"(checked against {VERIFIED_SCHEMA_VERSION})")
+    if any((t or {}).get("status") == "inProgress" for t in thread.get("turns") or []):
+        # The database is a projection of the rollout and can lag a running turn.
+        complete["sourceLimited"] = True
+        if complete.get("status") != "partial":
+            complete["status"] = "source-limited"
+        warnings.append("a turn is still running; Codex's local history database "
+                        "may not have its latest items yet")
+    complete["warnings"] = warnings
+
+
 def _background_task_block_for_worker(store, owner) -> dict:
     """Bound the original background-task facts for facade wait and report."""
     from ccx.ops.common import background_task_block, recorded_background_facts
@@ -325,44 +361,6 @@ def _unsupported(engine: str, capability: str, detail: str) -> CapabilityUnsuppo
     )
 
 
-def _claude_observed_model(rec: dict) -> str | None:
-    """The model Claude actually answered with, from the rendered transcript.
-
-    Never falls back to the requested model, and never accepts ``<synthetic>``
-    (the pseudo-model on API-error replies). Reads the already-rendered document
-    so this stays cheap enough for ``status``.
-    """
-    path = rec.get("transcriptJson")
-    if not path:
-        return None
-    try:
-        with open(path, encoding="utf-8") as handle:
-            doc = json.load(handle)
-    except (OSError, ValueError):
-        return None
-    for turn in reversed(doc.get("turns") or []):
-        model = turn.get("model")
-        if isinstance(model, str) and model and model != "<synthetic>":
-            return model
-    return None
-
-
-def _claude_statusline_model(short: str) -> str | None:
-    """Last model Claude reported through the compact statusline sidecar.
-
-    Unlike context freshness, a settled worker's last observed model does not
-    expire.  This is a read-only fallback for inventory summaries when the
-    cleaned transcript cache has not been rendered yet.
-    """
-    try:
-        doc = json.loads(statusline_json_path(short).read_text())
-    except (OSError, ValueError):
-        return None
-    model = doc.get("model") if isinstance(doc, dict) else None
-    value = model.get("id") if isinstance(model, dict) else None
-    return value if isinstance(value, str) and value and value != "<synthetic>" else None
-
-
 def _summary_context(block: dict | None, *, has_turn: bool, codex: bool) -> dict:
     """Normalize persisted context without rendering either engine transcript."""
     if not has_turn:
@@ -1789,8 +1787,14 @@ class WorkerClient:
     def _open_full_conversation(self, worker, *, max_tool_result_bytes,
                                 timeout, include_native=False,
                                 codex_recent_turns: int | None = None,
-                                claude_recent_turns: int | None = None):
-        """Build once from the original owner, retaining its native source until exit."""
+                                claude_recent_turns: int | None = None,
+                                codex_history_db: bool = False):
+        """Build once from the original owner, retaining its native source until exit.
+
+        ``codex_history_db`` reads a Codex thread from Codex's local history
+        database first (``ccx.codex.history_store``), falling back to
+        app-server when that read declines.
+        """
         from ccx.codex import runtime as codex_runtime
         from ccx.codex import telemetry as codex_telemetry
         from ccx.claude.transcript import open_original_claude_source, PinnedNativeSource
@@ -1848,6 +1852,11 @@ class WorkerClient:
                         max_tool_result_bytes=max_tool_result_bytes,
                         before_offset=end_offset, after_offset=after_offset,
                     )
+                    if after_offset > 0:
+                        _mark_recent_window(
+                            document, claude_recent_turns,
+                            f"showing only the turns since the last {claude_recent_turns} "
+                            "user prompts")
                     # Public reference names the verified original pathname;
                     # export uses the still-open native descriptor, not that path.
                     document["nativeArtifacts"][0]["path"] = str(original_path)
@@ -1862,10 +1871,15 @@ class WorkerClient:
                                     "warnings": [*(evidence.get("warnings") or []),
                                                  "excluded native evidence from a foreign thread"]}
                     known_empty = rec.get("historyKnownEmpty") is True
+                    thread = None
+                    if codex_history_db and not known_empty and codex_recent_turns is None:
+                        # Codex's local history database; None means fall back.
+                        from ccx.codex.history_store import read_thread_db
+                        thread = read_thread_db(thread_id)
                     if known_empty:
                         thread = {"id": thread_id, "threadSource": store.codex_source(owner.worker),
                                   "turns": []}
-                    else:
+                    elif thread is None:
                         # Only rich Codex peek requests a bounded recent window.
                         # Ordinary full conversation, logs and export retain
                         # their unmodified source-read argument contract.
@@ -1883,22 +1897,13 @@ class WorkerClient:
                         worker=owner.worker,
                         max_tool_result_bytes=max_tool_result_bytes, evidence=evidence,
                     )
+                    if thread.get("historySource") == "codex-history-db":
+                        _note_history_db(document, thread)
                     if (codex_recent_turns is not None
                             and len(thread.get("turns") or []) >= codex_recent_turns):
-                        # A bounded tail cannot claim global 1-based turn numbers,
-                        # nor pretend to describe the complete native history.
-                        for turn in document["turns"]:
-                            turn["sequence"] = None
-                        complete = document["completeness"]
-                        complete["sourceLimited"] = True
-                        complete["status"] = "source-limited"
-                        complete["warnings"] = [
-                            *(complete.get("warnings") or []),
-                            f"showing only the most recent {codex_recent_turns} native turns",
-                        ]
-                        document["peekHistoryWindow"] = {
-                            "kind": "recent", "limit": codex_recent_turns,
-                        }
+                        _mark_recent_window(
+                            document, codex_recent_turns,
+                            f"showing only the most recent {codex_recent_turns} native turns")
                     # A proven empty history is a synthetic normalization view,
                     # never evidence that a native thread/read actually occurred.
                     native_source = None if known_empty else thread
@@ -1931,7 +1936,8 @@ class WorkerClient:
     def conversation(self, worker, *, max_tool_result_bytes: int | None = None,
                      timeout: float | None = None,
                      _recent_codex_turns: int | None = None,
-                     _recent_claude_turns: int | None = None) -> dict:
+                     _recent_claude_turns: int | None = None,
+                     _codex_history_db: bool = False) -> dict:
         """Read a normalized full history from this original full-UUID owner.
 
         Claude reads a pinned native JSONL complete-line snapshot; Codex reads
@@ -1942,6 +1948,7 @@ class WorkerClient:
             worker, max_tool_result_bytes=max_tool_result_bytes,
             timeout=timeout, codex_recent_turns=_recent_codex_turns,
             claude_recent_turns=_recent_claude_turns,
+            codex_history_db=_codex_history_db,
         ) as (_owner, document, _native, _files):
             return document
 
@@ -1977,6 +1984,11 @@ class WorkerClient:
 
     # -- account usage ------------------------------------------------------
 
+    def models(self, engine: str | None = None, *, refresh: bool = False) -> list[dict]:
+        """The models one or both engines offer, as ``ccx models --json``."""
+        from ccx.models import read_models
+        return [catalog.as_dict() for catalog in read_models(engine=engine, refresh=refresh)]
+
     def usage(self, engine: str | None = None, *, include_tokens: bool = False,
               timeout: float = 30) -> dict:
         """Account-scoped quota utilization for one or both providers.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ccx-native",
-  "version": "0.1.0",
-  "description": "Control and monitor native Claude Code and Codex sessions from the CLI, Python or RPC, on your own subscriptions.",
+  "version": "0.2.0",
+  "description": "Native Claude Code and Codex sessions shared by your agents, scripts and terminals. Works with your own Claude and ChatGPT subscriptions.",
   "author": "Fernando <ccx@delega.ai>",
   "license": "MIT",
   "bin": {

package/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ccx-native"
-version = "0.1.0"
-description = "Control and monitor native Claude Code and Codex sessions from the CLI, Python or RPC, on your own subscriptions."
+version = "0.2.0"
+description = "Native Claude Code and Codex sessions shared by your agents, scripts and terminals. Works with your own Claude and ChatGPT subscriptions."
 readme = "README.md"
 requires-python = ">=3.11"
 license = "MIT"

package/skills/ccx/SKILL.md

@@ -61,7 +61,15 @@ ccx send "$W" "Now add a regression test."
 - `ccx peek TARGET`: state, latest messages, tools and errors. Start here.
   `ccx peek A B --status` checks several workers at once.
 - `ccx report TARGET`: the last reply.
-- `ccx logs TARGET`: conversation JSON when the report isn't enough.
+- `ccx history TARGET...`: earlier turns as text. Lines carry addresses
+  (`#184.0`); `--turns 184.0` prints one message whole, `--turns 180-186` the
+  exchange. Search the workers you name with `--grep RE`, `--cmd pytest` or
+  `--errors` (the newest 20 hits each); `--view map` gives a long history at a
+  glance.
+- After a compaction, read what you lost with `ccx history` on yourself
+  (`$CCX_SELF_WORKER_ID`), not the raw transcript. See
+  [references/history.md](references/history.md).
+- `ccx logs TARGET`: the whole conversation as JSON, for programs.
 - `ccx list`: find workers by name, state or folder.
 
 ## Permissions
@@ -153,3 +161,6 @@ More in [references/troubleshooting.md](references/troubleshooting.md).
 - `ccx attach TARGET` opens the worker in a terminal; Ctrl-Z detaches.
 - `--cap-5h PCT` or `--cap-7d PCT` on `new` or `send` stops that turn when
   account usage reaches PCT%. `ccx usage` shows the current levels.
+- `ccx models` lists each engine's models and the efforts each supports. A
+  Claude alias such as `opus` can point to a newer model after a Claude Code
+  update; pass the full id from the Resolved column to stay on one model.