optio-codex 0.1.0__py3-none-any.whl

optio_codex/verify.py

@@ -0,0 +1,352 @@
+"""Codex seed verify + refresh via OpenAI's OIDC token endpoint (host-free,
+non-billable) — with the agent probe kept as a documented fallback.
+
+Primary path: read the seed's ``auth.json`` and, for a ChatGPT-mode seed whose
+token is stale (codex refreshes proactively after 8 days — TOKEN_REFRESH_INTERVAL),
+perform a standard OIDC ``refresh_token`` grant against codex's hardcoded
+refresh URL (_REFRESH_URL; NOT the OIDC discovery token_endpoint — see the facts
+block below), writing the rotated tokens back into the seed. No codex process,
+no model inference — mirrors optio-claudecode's direct-endpoint ``oauth.py`` and
+optio-grok's ``verify.py`` (grok's discovery token_endpoint IS its refresh URL;
+codex's is not — the one divergence in this path).
+
+Fallback (codex-specific divergence from grok, which removed its probe): when
+OIDC discovery is unreachable (no usable ``token_endpoint`` in the response —
+used only to confirm reachability), fall back to the billable
+agent probe (``codex exec --json … '<challenge>'``) — the previous behavior —
+so a seed is still verifiable if the endpoint is unreachable.
+
+OpenAI OIDC facts (pinned Task 0, 2026-07-03, codex-cli 0.142.5):
+  issuer            = https://auth.openai.com
+  discovery         = <issuer>/.well-known/openid-configuration
+  discovery.token_endpoint = https://auth.openai.com/api/accounts/oauth/token
+                      -- an account-management surface; NOT codex's refresh URL.
+                      Used here ONLY as a reachability signal (discovery down
+                      -> agent-probe fallback), never as the refresh endpoint.
+  refresh_url       = https://auth.openai.com/oauth/token   (codex hardcodes
+                      this; env override CODEX_REFRESH_TOKEN_URL_OVERRIDE)
+  public client_id  = app_EMoamEEZ73f0CkXaXp7hrann   (login OAuth URL; no secret)
+  auth.json shape   = {"OPENAI_API_KEY": null|str, "auth_mode": <str>,
+                       "tokens": {"id_token","access_token","refresh_token",
+                                  "account_id"} | null,
+                       "last_refresh": <RFC3339 (nanosecond) / epoch>}
+A refresh rotates tokens.access_token + tokens.refresh_token (+ tokens.id_token
+if returned) and stamps last_refresh; account_id, auth_mode and OPENAI_API_KEY
+are preserved (only tokens + last_refresh are mutated). API-key seeds
+(OPENAI_API_KEY set, tokens null) carry no rotating token — alive-by-presence,
+no refresh.
+
+NOTE: endpoint/grant/public-client/shape are pinned above; the exact request
+headers want one confirmation against a live seed (a wrong guess fails CLOSED:
+a 4xx marks the seed dead; a network/discovery error is inconclusive and never
+retires a healthy seed).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import io
+import json
+import logging
+import os
+import re
+import tarfile
+import urllib.parse
+import urllib.request
+import uuid
+from datetime import datetime, timedelta, timezone
+from typing import Callable
+from urllib.error import HTTPError, URLError
+
+from optio_host.paths import task_dir
+
+from optio_agents import seeds
+from optio_codex import host_actions
+from optio_codex.seed_manifest import CODEX_SEED_MANIFEST, CODEX_SEED_SUFFIX
+
+_LOG = logging.getLogger(__name__)
+
+_ISSUER = "https://auth.openai.com"
+_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann"
+# Codex hardcodes its ChatGPT refresh URL (manager.rs) — it is NOT the OIDC
+# discovery `token_endpoint` (…/api/accounts/oauth/token), which is a separate
+# account-management surface. Honor codex's own env override.
+_REFRESH_URL = os.environ.get(
+    "CODEX_REFRESH_TOKEN_URL_OVERRIDE", "https://auth.openai.com/oauth/token"
+)
+_AUTH_RELPATH = "home/.codex/auth.json"
+_AUTH_MEMBER = ".codex/auth.json"
+_HTTP_TIMEOUT_S = 20
+_USER_AGENT = "optio-codex-seed-verify/1"
+# codex refreshes proactively after 8 days (manager.rs TOKEN_REFRESH_INTERVAL).
+_REFRESH_AFTER = timedelta(days=8)
+
+# Sentinel: the refresh endpoint returned a 4xx (invalid_grant) — the refresh
+# token lineage is definitively spent/revoked → mark the seed dead. Distinct
+# from ``None`` (a network/transport failure → inconclusive, never mark dead).
+_DEAD = "__dead__"
+
+# Agent-probe fallback (discovery unavailable) — the previous behavior. The
+# answer token ("paris") must NOT appear in the prompt so a prompt-echoing error
+# path can never false-positive.
+PROBE_PROMPT = "What is the capital of France? Answer with the city name."
+PROBE_ANSWER_RE = re.compile(r"paris", re.IGNORECASE)
+
+
+# --- synchronous HTTP (run in an executor; no host, no codex) ----------------
+
+def _discover_sync(issuer: str) -> "dict | None":
+    url = issuer.rstrip("/") + "/.well-known/openid-configuration"
+    try:
+        req = urllib.request.Request(
+            url, headers={"User-Agent": _USER_AGENT, "Accept": "application/json"},
+            method="GET",
+        )
+        with urllib.request.urlopen(req, timeout=_HTTP_TIMEOUT_S) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except (HTTPError, URLError, OSError, ValueError):
+        return None
+
+
+def _refresh_sync(refresh_url: str, refresh_token: str, client_id: str) -> "dict | str | None":
+    """OIDC refresh_token grant against codex's hardcoded refresh URL (NOT the
+    discovery token_endpoint — see module docstring). Returns the token response
+    dict on success, ``_DEAD`` on a 4xx (dead lineage), or ``None`` on a
+    transport error."""
+    body = urllib.parse.urlencode({
+        "grant_type": "refresh_token",
+        "refresh_token": refresh_token,
+        "client_id": client_id,
+    }).encode("utf-8")
+    req = urllib.request.Request(
+        refresh_url, data=body, method="POST",
+        headers={
+            "User-Agent": _USER_AGENT,
+            "Content-Type": "application/x-www-form-urlencoded",
+            "Accept": "application/json",
+        },
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=_HTTP_TIMEOUT_S) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except HTTPError:
+        return _DEAD  # invalid_grant / 4xx → the refresh token is spent
+    except (URLError, OSError, ValueError):
+        return None  # network/transport → inconclusive
+
+
+async def _in_executor(fn, *args):
+    return await asyncio.get_event_loop().run_in_executor(None, fn, *args)
+
+
+# --- helpers -----------------------------------------------------------------
+
+def _parse_last_refresh(value) -> "datetime | None":
+    """Parse codex's ``last_refresh`` — an RFC3339 string (possibly ``Z`` /
+    sub-second/nanosecond) or an epoch number. None when unparseable/absent (→
+    treated as stale, i.e. refresh)."""
+    if isinstance(value, (int, float)):
+        ts = value / 1000 if value > 1e12 else value
+        try:
+            return datetime.fromtimestamp(ts, tz=timezone.utc)
+        except (ValueError, OSError, OverflowError):
+            return None
+    if isinstance(value, str) and value.strip():
+        s = value.strip()
+        if s.endswith("Z"):
+            s = s[:-1] + "+00:00"
+        s = re.sub(r"\.(\d{6})\d+", r".\1", s)  # nanoseconds → microseconds
+        try:
+            dt = datetime.fromisoformat(s)
+        except ValueError:
+            return None
+        return dt if dt.tzinfo else dt.replace(tzinfo=timezone.utc)
+    return None
+
+
+def _read_auth(blob_plain: bytes) -> "dict | None":
+    """The codex auth.json dict from the seed tar, or None if absent/malformed."""
+    try:
+        with tarfile.open(fileobj=io.BytesIO(blob_plain), mode="r:gz") as tar:
+            f = tar.extractfile(_AUTH_MEMBER)
+            if f is None:
+                return None
+            auth = json.loads(f.read().decode("utf-8"))
+    except (tarfile.TarError, KeyError, ValueError, UnicodeDecodeError):
+        return None
+    return auth if isinstance(auth, dict) else None
+
+
+# --- public API --------------------------------------------------------------
+
+async def verify_and_refresh_seed(
+    db,
+    *,
+    prefix: str,
+    suffix: str = CODEX_SEED_SUFFIX,
+    seed_id: str,
+    ssh=None,
+    install_dir: str | None = None,
+    encrypt: "Callable[[bytes], bytes] | None" = None,
+    decrypt: "Callable[[bytes], bytes] | None" = None,
+) -> bool:
+    """Verify a codex seed host-free via OpenAI's OIDC token endpoint; refresh
+    the rotating token in place. Falls back to the billable agent probe only
+    when OIDC discovery is unavailable.
+
+    Returns True iff the seed is alive. Never raises for a dead seed. Marks pool
+    status ``dead`` ONLY on a definitive dead signal (no refresh token,
+    malformed auth, or a 4xx invalid_grant); a transport/discovery failure is
+    inconclusive and leaves status untouched. Call only on a FREE seed or one
+    whose lease the caller holds (a refresh rotates the single-use token).
+    """
+    from motor.motor_asyncio import AsyncIOMotorGridFSBucket
+
+    doc = await seeds.load_seed(db, prefix=prefix, suffix=suffix, seed_id=seed_id)
+    if doc is None:
+        return False
+
+    async def _finish(alive: bool, *, mark_dead: bool) -> bool:
+        await seeds.declare_metadata(
+            db, prefix=prefix, suffix=suffix, seed_id=seed_id,
+            metadata={"verify": {"alive": alive, "checkedAt": datetime.now(timezone.utc)}},
+        )
+        if alive:
+            await seeds.mark_seed_status(db, prefix=prefix, suffix=suffix, seed_id=seed_id, status="alive")
+        elif mark_dead:
+            await seeds.mark_seed_status(db, prefix=prefix, suffix=suffix, seed_id=seed_id, status="dead")
+        return alive
+
+    buf = io.BytesIO()
+    await AsyncIOMotorGridFSBucket(db).download_to_stream(doc["blobId"], buf)
+    dec = decrypt or (lambda b: b)
+    auth = _read_auth(dec(buf.getvalue()))
+    if auth is None:
+        return await _finish(False, mark_dead=True)
+
+    tokens = auth.get("tokens")
+    # API-key seed: no rotating token → alive by presence.
+    if not tokens:
+        if auth.get("OPENAI_API_KEY"):
+            return await _finish(True, mark_dead=False)
+        return await _finish(False, mark_dead=True)  # neither tokens nor key
+
+    refresh_token = tokens.get("refresh_token") if isinstance(tokens, dict) else None
+    if not refresh_token:
+        return await _finish(False, mark_dead=True)
+
+    # Discovery is a REACHABILITY gate only: if OpenAI's OIDC surface is
+    # unreachable we fall back to the agent probe. We deliberately do NOT use
+    # disco["token_endpoint"] as the refresh URL — for codex that is a different
+    # (account-management) surface; codex refreshes against the hardcoded
+    # _REFRESH_URL (see module docstring / Task 0 facts).
+    disco = await _in_executor(_discover_sync, _ISSUER)
+    if not isinstance(disco, dict) or not disco.get("token_endpoint"):
+        _LOG.warning(
+            "seed %s: OIDC discovery unavailable — falling back to the agent probe",
+            seed_id,
+        )
+        return await _verify_via_probe(
+            db, prefix=prefix, suffix=suffix, seed_id=seed_id, ssh=ssh,
+            install_dir=install_dir, encrypt=encrypt, decrypt=decrypt,
+            finish=_finish,
+        )
+
+    now = datetime.now(timezone.utc)
+    last = _parse_last_refresh(auth.get("last_refresh"))
+    need_refresh = last is None or (now - last) >= _REFRESH_AFTER
+    if not need_refresh:
+        # Fresh (codex hasn't hit its proactive-refresh window) → trust alive,
+        # do not rotate. (Codex tokens carry no cheap userinfo scope like grok;
+        # freshness is the liveness signal — documented divergence.)
+        return await _finish(True, mark_dead=False)
+
+    resp = await _in_executor(_refresh_sync, _REFRESH_URL, refresh_token, _CLIENT_ID)
+    if resp is _DEAD:
+        return await _finish(False, mark_dead=True)
+    if not isinstance(resp, dict) or not resp.get("access_token"):
+        return await _finish(False, mark_dead=False)  # transport → inconclusive
+
+    tokens["access_token"] = resp["access_token"]
+    if resp.get("refresh_token"):
+        tokens["refresh_token"] = resp["refresh_token"]
+    if resp.get("id_token"):
+        tokens["id_token"] = resp["id_token"]
+    auth["tokens"] = tokens
+    auth["last_refresh"] = now.isoformat().replace("+00:00", "Z")
+    try:
+        await seeds.overwrite_seed_member(
+            db, prefix=prefix, suffix=suffix, seed_id=seed_id,
+            member_path=_AUTH_MEMBER, content=json.dumps(auth).encode("utf-8"),
+            encrypt=encrypt, decrypt=decrypt,
+        )
+    except Exception:  # noqa: BLE001 — save-back failed; the refresh still rotated
+        _LOG.exception("seed %s: refreshed auth save-back failed", seed_id)
+    return await _finish(True, mark_dead=False)
+
+
+async def _verify_via_probe(
+    db, *, prefix, suffix, seed_id, ssh, install_dir, encrypt, decrypt, finish,
+) -> bool:
+    """Fallback: plant the seed and run one billable ``codex exec`` challenge
+    probe; verdict from stdout, rotated auth.json saved back. The previous
+    behavior, retained for when OIDC discovery is unavailable.
+
+    The probe scrubs OPENAI_API_KEY from its environment
+    (``host_actions._PROBE_SCRUB_ENV_KEYS``), so an ambient provider key on the
+    verifying host cannot authenticate the probe via codex's API-key fallback
+    and mask a dead ChatGPT-mode seed."""
+    taskdir = task_dir(
+        ssh=ssh, process_id=f"seed-verify-{uuid.uuid4().hex[:12]}",
+        consumer_name="optio-codex",
+    )
+    host = host_actions.build_host(ssh, taskdir)
+    await host.connect()
+    try:
+        await host.setup_workdir()
+        codex_exec = await host_actions.resolve_codex(
+            host, install_dir=install_dir, install_if_missing=False,
+        )
+        await seeds.plant_seed(
+            db, host, prefix=prefix, seed_id=seed_id,
+            manifest=CODEX_SEED_MANIFEST, suffix=suffix, decrypt=decrypt,
+        )
+        stdout, exit_code = await host_actions.run_codex_probe(
+            host, codex_executable=codex_exec, prompt=PROBE_PROMPT,
+        )
+        # Verdict: stdout-only. The exit code carries zero verdict bits (answer
+        # present proves the full chain regardless) — diagnostics only.
+        alive = PROBE_ANSWER_RE.search(stdout) is not None
+        if not alive:
+            _LOG.info(
+                "seed %s: probe dead (exit=%s, stdout[:200]=%r)",
+                seed_id, exit_code, stdout[:200],
+            )
+        # Write back the (possibly rotated) auth.json — valid files only (tokens
+        # or OPENAI_API_KEY non-null).
+        workdir = host.workdir.rstrip("/")
+        try:
+            auth_raw = await host.fetch_bytes_from_host(f"{workdir}/{_AUTH_RELPATH}")
+            auth = json.loads(auth_raw.decode("utf-8"))
+            if isinstance(auth, dict) and (
+                auth.get("tokens") is not None or auth.get("OPENAI_API_KEY") is not None
+            ):
+                await seeds.overwrite_seed_member(
+                    db, prefix=prefix, suffix=suffix, seed_id=seed_id,
+                    member_path=_AUTH_MEMBER, content=auth_raw,
+                    encrypt=encrypt, decrypt=decrypt,
+                )
+        except (FileNotFoundError, ValueError, UnicodeDecodeError):
+            _LOG.warning("seed %s: no valid auth.json after probe; skipping write-back", seed_id)
+        # Probe failure is a definitive dead signal (the seed's own creds were
+        # exercised end-to-end), so mark_dead=True here (unlike a transport error).
+        return await finish(alive, mark_dead=not alive)
+    finally:
+        try:
+            await host.cleanup_taskdir(aggressive=True)
+        except Exception:  # noqa: BLE001
+            _LOG.exception("verify: cleanup_taskdir failed")
+        try:
+            await host.disconnect()
+        except Exception:  # noqa: BLE001
+            _LOG.exception("verify: host.disconnect failed")

optio_codex-0.1.0.dist-info/METADATA

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: optio-codex
+Version: 0.1.0
+Summary: Run OpenAI Codex as an optio task; local subprocess; ttyd-served TUI iframe.
+Author-email: Kristof Csillag <kristof.csillag@deai-labs.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/deai-network/optio
+Project-URL: Repository, https://github.com/deai-network/optio
+Project-URL: Issues, https://github.com/deai-network/optio/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Framework :: AsyncIO
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: optio-core<0.4,>=0.3
+Requires-Dist: optio-host<0.3,>=0.2
+Requires-Dist: optio-agents<0.4,>=0.3
+Requires-Dist: asyncssh>=2.14
+Requires-Dist: aiohttp>=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+
+# optio-codex
+
+Run OpenAI Codex as an `optio` task — either as the interactive TUI embedded
+in the optio dashboard via an iframe widget served by `ttyd`, or in
+conversation mode (codex app-server over stdio) rendered by the
+`optio-conversation-ui` widget. Local or remote (SSH) workers.
+
+## Install
+
+```bash
+pip install optio-codex
+```
+
+Requires Python 3.11+. Pulls `optio-core`, `optio-host`, `optio-agents`,
+`asyncssh`, and `aiohttp`.
+
+## What it does
+
+optio-codex launches `codex` inside a detached tmux session, serves the
+TUI over `ttyd`, and coordinates with the host harness through the
+`optio.log` keyword channel (STATUS / DELIVERABLE / DONE / ERROR). The
+agent reads its task from an `AGENTS.md` file planted in the workdir.
+The tmux+ttyd machinery follows the optio-claudecode pattern, including
+browser handling: `redirect` — `codex login` opens the loopback OAuth URL
+via `xdg-open`, which the redirect shim captures as a `BROWSER:` marker so
+the harness surfaces it to the operator (who completes the sign-in),
+instead of silently swallowing it.
+
+### Isolation
+
+Each task runs under an isolated `HOME` (`<workdir>/home`, created at
+prepare time) with `CODEX_HOME` pointing at `<workdir>/home/.codex`, so
+the operator's real `~/.codex` identity and config do not leak into the
+session. The codex binary is launched via a per-task path
+(`<workdir>/home/.local/bin/codex`), so teardown only ever kills this
+task's process.
+
+### Filesystem sandbox
+
+Beyond the per-task `HOME`, every codex tool subprocess is confined by
+codex's **own native sandbox** — kernel-enforced (bundled bubblewrap
+primary, Landlock+seccomp fallback on Linux), covering all shell/tool
+commands the agent runs. optio-codex does **not** vendor claustrum for
+this; it renders one resolved sandbox posture (`fs_allowlist.py` SSOT)
+onto every launch surface: the interactive TUI argv, the `codex exec`
+probe flags, and the `codex app-server` command line (`-c
+sandbox_workspace_write.*` overrides; the sandbox *mode* is selected
+out-of-band via `thread/start`'s `sandbox` enum — the 0.142.5 app-server
+schema has no `thread/start.sandboxPolicy` object).
+
+`fs_isolation=True` (the default) selects codex `workspace-write`: writes
+are confined to the task workdir, `/tmp`, and any `rw` grants; **reads are
+not restricted**. That read-open behaviour is a deliberate divergence from
+optio-grok/optio-claudecode (whose sandboxes also deny reads) — so
+`AllowedDir("…", "ro")` is a *documented no-op* on codex (an additive grant
+that is already trivially satisfied), kept only for cross-wrapper config
+portability. Only `AllowedDir("…", "rw")` changes behaviour, becoming a
+`sandbox_workspace_write.writable_roots` entry (`~/` expands against the
+real host home at launch). Network access is **OFF** by default (stricter
+than the other wrappers, whose fs sandboxes never touch the network);
+`network_access=True` relaxes it. `fs_isolation=False` runs codex
+unconfined (`danger-full-access`).
+
+Extra grants and the mode are cross-validated at config time — e.g.
+`fs_isolation=True` with `sandbox="danger-full-access"`, or an `rw` grant
+under an explicit `read-only` mode, raise `ValueError` rather than silently
+mis-configuring the sandbox.
+
+**No optio-side enforcement guard is needed.** codex fails **closed**: on a
+host with no working sandbox mechanism (bubblewrap or Landlock), codex
+errors or panics and the model's command never runs — it never falls back
+to running unconfined (the only unconfined path is the explicit
+`--dangerously-bypass-approvals-and-sandbox` opt-out, which optio-codex
+never emits). This was verified empirically against codex-cli 0.142.5 (see
+the Stage-8 probe verdict in `docs/2026-07-02-optio-codex-design.md`), so
+optio-codex relies on that fail-closed guarantee instead of a launch-time
+probe. As a free hardening bonus, `.codex/` and `.git/` under a writable
+root stay read-only to the agent's shell, so the sandboxed agent cannot
+rewrite its own per-task `auth.json` even though `CODEX_HOME` lives inside
+the workdir.
+
+### Authentication
+
+The primary mechanism is **seeds**: log in once, reuse the identity for
+every later task. Run the setup task and log into codex interactively in
+the embedded terminal (`codex login --device-auth`, or `codex login
+--with-api-key`); on teardown the session's `home/.codex` (`auth.json` +
+`config.toml`) is captured as a reusable seed and surfaced through the
+`on_seed_saved` callback. A later task started with
+`CodexTaskConfig(seed_id=…)` merges that stored identity into its fresh
+workdir before launch, so codex starts already logged-in — and the new
+workdir is pre-trusted automatically (`[projects."<workdir>"] trust_level =
+"trusted"` appended to `config.toml`), so codex never prompts about an
+untrusted directory. `seed_id` also accepts a `SeedProvider` callable that
+leases a seed from a pool (the task's `process_id` is the lease holder).
+
+Store-binding CRUD helpers (`list_seeds` / `delete_seed` / `purge_seed`)
+operate over the `{prefix}_codex_seeds` collection.
+
+**Credential rotation (why a seeded session does more than merge-once):**
+codex's ChatGPT-mode `auth.json` carries a *single-use rotating* refresh
+token (openai/codex#15410) — codex proactively refreshes it after 8 days
+and on any 401, rewriting `auth.json` in place, and a used refresh token
+invalidates every other copy. So a seeded session runs an in-session
+**credential watcher** that saves the rotated `auth.json` back into the
+seed (plus a final teardown backstop); pooled seeds take a **lease** (one
+live lineage per seed — the watcher renews it and aborts the session on
+lease loss); and `verify_and_refresh_seed` refreshes idle pooled seeds
+**host-free** — a direct OpenAI OIDC `refresh_token` grant (no codex
+process, no model turn, non-billable) that persists a fresh token before
+the 8-day cliff, falling back to a headless `codex exec` probe only when
+OIDC discovery is unreachable.
+
+Fallbacks without a seed: pass an API key into the session env
+(`CodexTaskConfig(env={"OPENAI_API_KEY": …})`) or log in interactively
+(`codex login`) inside the embedded terminal.
+
+### Binary provisioning
+
+The codex binary is resolved through an optio-owned, evictable cache on the
+worker — `OPTIO_CODEX_CACHE_DIR`, else
+`${XDG_CACHE_HOME:-~/.cache}/optio-codex/bin` — resolved host-side, so it is
+correct on a remote SSH worker and never lives under a task workdir or the
+operator's `~/.codex`. On a cache miss the cache is seeded from a host
+`codex` on `PATH` (`cp -L` deref → a stable copy), or, when none exists, the
+pinned release is auto-downloaded (`rust-v0.142.5`, static musl,
+`{x86_64,aarch64}-unknown-linux-musl`). The per-task launch symlink
+(`<workdir>/home/.local/bin/codex`) is preserved and points into the cache,
+so task-scoped teardown stays unaffected.
+
+## Status — Stages 0–8 (feature-complete against the Appendix-A parity bar)
+
+Verified against `docs/writing-agent-wrappers.md` Appendix A — 28 of 29 items
+green (see `docs/2026-07-02-optio-codex-parity-audit.md` for per-item
+`file:line` evidence). Suite: 188 passed, 4 skipped (the skips are the opt-in
+real-binary tests, env-gated, never in the default suite).
+
+Shipped:
+
+- **Two run modes** — iframe/ttyd interactive TUI *and* conversation mode
+  (codex app-server over stdio) with a conversation-ui widget
+  (`optio-conversation-ui`, `widgetData.protocol = "codex"` → `CodexView`)
+- `optio.log` keyword-protocol coordination + exit-status DONE/ERROR channel
+- per-task `HOME` / `CODEX_HOME` isolation (tree provisioned at prepare)
+- **filesystem isolation** via codex's native sandbox — default-ON
+  `fs_isolation` (`workspace-write`), `extra_allowed_dirs` (`rw` grants →
+  `writable_roots`), `network_access` (OFF by default); fail-closed, no
+  optio-side guard needed (see the Filesystem sandbox section above)
+- task-scoped teardown (per-task codex path; orphan-ttyd reap = crash-orphan
+  rescue)
+- `create_codex_task`, `run_codex_session`, `CodexTaskConfig`
+- remote SSH workers (`ssh=SSHConfig(...)` routes to `RemoteHost`; verified
+  end-to-end against a docker-sshd harness)
+- resume / workdir snapshots: session-id-keyed relaunch (`codex resume <id>`,
+  never `resume --last`), Mongo snapshot store (retention 5, single workdir
+  GridFS blob carrying `home/.codex/sessions`), `resume.log` + AGENTS.md
+  resume section synced to the snapshot exclude list
+  (`workdir_exclude`; defaults drop `home/.codex/packages`, `*.sqlite*`,
+  caches — never `home/.codex/sessions`); auto-resume-on-restart via
+  optio-core (`supports_resume=True`)
+- seeds: log-in-once capture (`on_seed_saved`) + `seed_id` consume with
+  automatic workdir pre-trust; store-binding CRUD (`list_seeds` /
+  `delete_seed` / `purge_seed`) over `{prefix}_codex_seeds`
+- pool leases + in-session credential save-back (single-use rotating
+  refresh token) with a teardown backstop; lease loss aborts the session
+- host-free `verify_and_refresh_seed` — primary path is a direct OpenAI OIDC
+  `refresh_token` grant (non-billable, no codex process) with rotated-token
+  write-back and pool-status stamping; falls back to a headless `codex exec`
+  probe (stdout-only verdict) only when OIDC discovery is unreachable
+- optio-owned evictable binary cache (`OPTIO_CODEX_CACHE_DIR`), seeded from a
+  host binary (`cp -L`) or real GitHub-release auto-download (pinned
+  `rust-v0.142.5`, musl); per-task launch symlink preserved
+- conversation-ui surface: permission gate, **inline** model switching, file
+  upload/download (`optio-file:`), tool verbosity
+- demo trio: seed-setup + seed-pinned iframe + seed-pinned conversation tasks
+  (auto-appear via `fw.resync()`)
+
+Remaining opt gaps (deliberate — see the parity audit):
+
+- **session restore / rebase (scripted transcript reconstruction):** not
+  shipped. codex's resume story is snapshot + `codex resume <id>` (shipped
+  above); claudecode's scripted `transcript.py` rebase is engine-specific and
+  has no codex analogue. optio-grok and optio-opencode also omit it — parity,
+  not a regression.
+- **at-rest encryption of the session blob:** the `encrypt`/`decrypt` seam is
+  plumbed through but not activated (sessions pass `encrypt=None`) — identical
+  posture to every other optio wrapper.
+
+Not yet published to PyPI (first release is a separate, user-approved step).

optio_codex-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+optio_codex/__init__.py,sha256=7H3gMx-YDBwDmoqrGzTlxSUnYMwA6Lp6Vnna_Z2zRaY,1412
+optio_codex/conversation.py,sha256=Pa7PEuU_MYGNuS3EWEX2n7UexIIA9nkV0ExgcKCSfB8,24795
+optio_codex/conversation_listener.py,sha256=_0ocQ6AhM2fUqIeFttrqJHew5BNrlhwATNX-ONPpmT8,14295
+optio_codex/cred_watcher.py,sha256=N8Ie1yj1JL47UHtaqWO-zAB2kdIBXrg1JlxMmuYQFbQ,5246
+optio_codex/fs_allowlist.py,sha256=mnrhBkeEHpB11Yq8O_cyOSBpJvb-OcA_Zq9qwKdfH6g,6680
+optio_codex/host_actions.py,sha256=nh2N5kIjJs24XQc9Crvk6i_qGrxUladb0XB_y_GY158,41520
+optio_codex/models.py,sha256=TTBTvuKB2Wo7dGcIQsSxmO67_0an9AxpIk0u6p3_LEI,2776
+optio_codex/prompt.py,sha256=Ornbe1pEfQSO5v885_WXGoc7dzR6ir3ZBKv05iyE5Do,7610
+optio_codex/seed_manifest.py,sha256=Cnj2jFEP-0vk4_a4QxIwu8TbOs4-RjB-hiNZiO4KkRE,3889
+optio_codex/session.py,sha256=-f56icy1oep47zzhpcKkJA52XpS8QULt3m24yjUVJF4,32929
+optio_codex/snapshots.py,sha256=_lomxFocn4064PL_TL81WqXq_LnA2mMQGWzR04H_29A,5518
+optio_codex/types.py,sha256=YaHDiOeeXhgrZm-jCGdmPhrPiYA5yi2iBYVSGiw3Te4,15125
+optio_codex/verify.py,sha256=KIRmdRBXX6rr2Zv9jm_eHiCLmxxkMlafkDX2b3jBAZQ,15762
+optio_codex-0.1.0.dist-info/METADATA,sha256=PXS4E0RE9T55h6ZC7Q0fQDecQq2qG7bgMyWTiHJ3GN8,11679
+optio_codex-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+optio_codex-0.1.0.dist-info/top_level.txt,sha256=zR3_V-kB42Rped033T8CESbRT-qh9uarmfzC8WP1C7I,12
+optio_codex-0.1.0.dist-info/RECORD,,

optio_codex-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

optio_codex-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+optio_codex