optio-codex 0.1.0__py3-none-any.whl

optio_codex/models.py

@@ -0,0 +1,68 @@
+"""Available-model list for the codex conversation widget's model picker.
+
+============================================================================
+MODEL-SWITCH MECHANISM — pinned from the app-server contract (codex-cli
+0.142.5 schema dump + upstream README; see the conversation docstring).
+============================================================================
+
+Decision: **INLINE** (opencode/grok-style), NOT restart (claudecode-style) —
+and codex needs NO dedicated set-model request at all: a ``model`` override
+on ``turn/start`` "become[s] the default for subsequent turns" (README,
+turn/start). So ``CodexConversation.request_model_change()`` just pins the
+model sent with the next ``turn/start``; the session body needs no
+model_change_requested restart loop.
+
+MODEL LIST source: the ``model/list`` request, answered in-session
+(``{data:[Model], nextCursor}``; ``Model`` carries ``id``, ``displayName``,
+``hidden``, ``isDefault``). The conversation captures the raw result at
+bootstrap; this module maps it to the widget shape. There is no CLI listing
+tier (unlike grok) — live result → static fallback, nothing in between.
+"""
+from __future__ import annotations
+
+# Shown when the live model/list is unavailable (fake agents, offline, error
+# response). Version-sensitive vendor strings; update alongside the pinned
+# codex-cli version.
+FALLBACK_MODELS: dict = {
+    "models": [
+        {"id": "gpt-5.5", "label": "GPT-5.5", "disabled": False},
+        {"id": "gpt-5.4-mini", "label": "GPT-5.4 Mini", "disabled": False},
+    ],
+    "default": "gpt-5.5",
+}
+
+
+def parse_model_list(result: "dict | None") -> dict:
+    """Map a raw ``model/list`` result to the widget shape
+    ``{models:[{id,label,disabled}], default}``.
+
+    Hidden models are omitted; ``default`` is the ``isDefault`` entry's id
+    (None when absent). Missing / malformed input returns the static
+    fallback (never raises, never falsely empties the picker).
+    """
+    if not isinstance(result, dict):
+        return _copy_fallback()
+    data = result.get("data")
+    if not isinstance(data, list):
+        return _copy_fallback()
+    out: list[dict] = []
+    default: str | None = None
+    for m in data:
+        if not isinstance(m, dict):
+            continue
+        mid = m.get("id")
+        if not isinstance(mid, str) or not mid or m.get("hidden"):
+            continue
+        out.append({"id": mid, "label": m.get("displayName") or mid, "disabled": False})
+        if m.get("isDefault"):
+            default = mid
+    if not out:
+        return _copy_fallback()
+    return {"models": out, "default": default}
+
+
+def _copy_fallback() -> dict:
+    return {
+        "models": [dict(m) for m in FALLBACK_MODELS["models"]],
+        "default": FALLBACK_MODELS["default"],
+    }

optio_codex/prompt.py

@@ -0,0 +1,184 @@
+"""AGENTS.md composition for optio-codex.
+
+Codex reads an ``AGENTS.md`` file in its workdir. The shared framing and
+the keyword-protocol documentation are owned by ``optio-agents`` (the
+prompt SSOT); this module threads codex's protocol mode through and owns
+the codex-specific resume-awareness section (Stage 2), rendered from the
+EFFECTIVE snapshot exclude list so its preservation claims never drift
+from what the snapshot actually keeps.
+"""
+
+from optio_agents.prompt import compose_agents_md as _compose_agents_md_host
+from optio_agents.prompt import downloadables_block
+from optio_agents.protocol import ProtocolFeatures, build_log_channel_prompt
+
+from optio_codex.snapshots import effective_workdir_exclude
+
+
+# Self-contained System: explainer for sessions without the keyword-protocol
+# docs (which normally explain the convention). Per-wrapper copy is the
+# established pattern (claudecode/opencode/grok each carry their own).
+_SYSTEM_PREFIX_EXPLAINER = """\
+(Messages prefixed `System:` on your input channel originate from the
+harness coordinating this session, not from the human user.)
+"""
+
+
+RESUME_SECTION_TEMPLATE = """## Resumes
+
+This harness may pause your session, save your context to a database,
+terminate the underlying process, and later rehydrate it. From your
+point of view the conversation is fully continuous — you keep your
+prior context and will not "notice" the resume.
+
+**A resume can happen at any point, not only at the start.** The host
+environment may have changed across a resume — different host,
+different running processes, files outside this workdir gone — even
+though your context remembers everything as alive and well.
+
+**The workdir (this directory) is preserved across resumes, with two
+caveats:**
+
+- {excludes_clause}
+- **Anything outside the workdir is not preserved.**
+
+- **Your `home/.codex/` directory — the codex session store (rollout
+  files under `home/.codex/sessions`, auth, config) — IS preserved
+  across resumes** (minus the excluded paths above), so your history
+  travels with you even when the underlying process and host change.
+
+{outside_clause}
+
+### Detecting a resume: `resume.log`
+
+Each session start (fresh or resumed) appends one line to
+`./resume.log`. Line format:
+
+```
+<ISO 8601 UTC timestamp>[ REFRESHED:<comma-separated filenames>]
+```
+
+The very first line is the original launch timestamp; each subsequent
+line is a resume. The optional `REFRESHED:` suffix signals that the
+harness rewrote the listed files on that resume (e.g.
+`2026-05-28T13:15:42Z REFRESHED:AGENTS.md`) — your in-memory copy of
+those files is stale and must be re-read before continuing.
+
+**At the start of every new incoming user message, read
+`./resume.log` first.** Compare the latest line to the value you
+remembered last time you checked. If a new line has appeared, treat
+the situation as a resume:
+
+- Verify any tools, processes, or files you previously gathered
+  outside the workdir are still where you left them.
+- Re-establish anything that's gone (re-launch a server, re-fetch a
+  file, etc.) before continuing.
+- **If the latest line carries a `REFRESHED:` suffix, re-read each
+  listed file** (e.g. `cat ./AGENTS.md`) — the harness updated it
+  since your last context snapshot and the version you remember is
+  out of date.
+- Then resume the work you were doing.
+
+If a resume slips past unnoticed, a failing tool call is the
+next-best signal — re-check `./resume.log` then.
+
+You may also be notified of a resume by a `System:` message on your input
+channel; when you see one, follow the `resume.log` procedure above.
+"""
+
+
+def _render_resume_section(workdir_exclude: list[str] | None) -> str:
+    """Render RESUME_SECTION_TEMPLATE with the EFFECTIVE exclude list.
+
+    ``effective_workdir_exclude`` is the same resolver the snapshot archive
+    uses (``None`` → the codex defaults), so what this section claims is
+    preserved is exactly what the snapshot preserves.
+    """
+    effective = effective_workdir_exclude(workdir_exclude)
+    if not effective:
+        excludes_clause = (
+            "**No paths are excluded** — every file in the workdir is preserved."
+        )
+        outside_clause = (
+            "If you need to stash large data, place it outside the workdir "
+            "(e.g. `/tmp/`) — but remember it may be missing when you next look."
+        )
+    else:
+        excludes_str = ", ".join(f"`{p}`" for p in effective)
+        excludes_clause = (
+            f"**Paths matching the snapshot exclude list are NOT preserved**, "
+            f"even inside the workdir. The current exclude list is: {excludes_str}."
+        )
+        outside_clause = (
+            "If you need to stash large data, place it outside the workdir "
+            "(e.g. `/tmp/`) or inside an excluded subdirectory — but remember "
+            "any such location may be missing when you next look."
+        )
+    return RESUME_SECTION_TEMPLATE.format(
+        excludes_clause=excludes_clause,
+        outside_clause=outside_clause,
+    )
+
+
+def compose_agents_md(
+    consumer_instructions: str,
+    *,
+    documentation: str | None = None,
+    host_protocol: bool = True,
+    workdir_exclude: list[str] | None = None,
+    supports_resume: bool = True,
+    file_download: bool = False,
+) -> str:
+    """Build the full AGENTS.md body.
+
+    ``documentation`` is the keyword-protocol block; the session passes
+    ``get_protocol(browser="redirect").documentation``. Defaults (for unit
+    tests / standalone callers) to codex's ``redirect`` docs. It must
+    always come from the session's ``Protocol`` where one exists — never
+    rebuild features at a second site.
+
+    ``host_protocol=False`` omits the keyword-protocol documentation and
+    instead includes a self-contained ``System:`` message explainer
+    (guide Part 2D); iframe mode always runs with ``host_protocol=True``
+    (validated in ``CodexTaskConfig``), the False branch serves
+    conversation mode in a later stage.
+
+    ``supports_resume=True`` (default) appends the resume-awareness section
+    so the agent watches ``resume.log`` and knows ``home/.codex`` (minus
+    ``workdir_exclude``) survives across resumes. ``workdir_exclude`` is
+    this task's snapshot exclude list (None → the codex defaults), used to
+    keep the section's claims in sync with what is actually preserved.
+
+    ``file_download=True`` appends the downloadables instruction block so
+    codex offers files to the human via the ``optio-file:`` sentinel link
+    (conversation_ui file-download feature); the wording is comparative when
+    the keyword protocol is active (``host_protocol``).
+    """
+    if file_download:
+        consumer_instructions = (
+            consumer_instructions.rstrip()
+            + downloadables_block(comparative=host_protocol)
+        )
+    if host_protocol:
+        if documentation is None:
+            documentation = build_log_channel_prompt(
+                ProtocolFeatures(browser="redirect")
+            )
+    else:
+        documentation = None
+    resume_section: str | None = (
+        _render_resume_section(workdir_exclude) if supports_resume else None
+    )
+    if not host_protocol:
+        # The protocol docs normally explain the `System:` convention;
+        # without them the composed prompt carries its own explainer.
+        resume_section = (
+            resume_section + _SYSTEM_PREFIX_EXPLAINER
+            if resume_section
+            else _SYSTEM_PREFIX_EXPLAINER
+        )
+    return _compose_agents_md_host(
+        consumer_instructions,
+        documentation=documentation,
+        resume_section=resume_section,
+    )

optio_codex/seed_manifest.py

@@ -0,0 +1,91 @@
+"""codex adopter of the generic optio-agents seed engine.
+
+Defines the codex seed manifest (HOME layout + capture-time include triage),
+the Mongo collection suffix, and ergonomic ``delete_seed`` / ``list_seeds`` /
+``purge_seed`` wrappers that bind the suffix for consuming apps.
+
+A codex *seed* carries the logged-in identity that lives under ``CODEX_HOME``
+(``<workdir>/home/.codex``): ``auth.json`` (ChatGPT mode: ``auth_mode`` +
+``tokens{id_token, access_token, refresh_token}`` + ``last_refresh``; API-key
+mode: ``OPENAI_API_KEY``) plus ``config.toml``. Replanting it into a fresh
+workdir is the answer to headless login.
+
+The include list is an allowlist, which is also the exclusion mechanism:
+``packages/`` (the ~286MB binary cache), ``*.sqlite*`` (absolute
+rollout-path poison; rebuilt from rollouts), ``sessions/``, ``cache/``,
+``tmp/``, logs etc. are simply never members.
+
+Like grok/opencode (and unlike claudecode), codex needs no consume-time
+rekey: auth/config are cwd-independent, so ``consume_transform`` is None.
+The one cwd-dependent consume step — pre-trusting the new workdir via a
+``[projects."<workdir>"]`` entry in config.toml — is deliberately a
+post-merge edit in the session's ``_prepare`` (see
+``host_actions.ensure_workdir_trusted``), NOT a manifest transform: codex
+rewrites config.toml itself at runtime, so optio's edit must stay a
+minimal, idempotent append against the *planted* file, applied exactly at
+the point the workdir is known.
+
+Path note: the engine roots capture/extract at ``host.workdir + "/" +
+home_subdir`` (see ``SeedManifest.home_subdir``). CODEX_HOME is
+``<workdir>/home/.codex``, so the manifest uses ``home_subdir="home"`` with
+``.codex/`` prefixes on the include paths (mirroring grok's ``.grok/…``).
+"""
+
+from __future__ import annotations
+
+from optio_agents import seeds
+
+CODEX_SEED_SUFFIX = "_codex_seeds"
+CODEX_SEED_MANIFEST_VERSION = 1
+
+
+# Credential-only manifest for in-session save-back (the write-back analog
+# of the full CODEX_SEED_MANIFEST; mirrors grok's GROK_CRED_MANIFEST and
+# opencode's OPENCODE_CRED_MANIFEST). Only auth.json is re-captured — the
+# seed's config.toml is never touched by save-back.
+CODEX_CRED_MANIFEST = seeds.SeedManifest(
+    home_subdir="home",
+    include=[".codex/auth.json"],
+    version=CODEX_SEED_MANIFEST_VERSION,
+    consume_transform=None,
+)
+
+
+CODEX_SEED_MANIFEST = seeds.SeedManifest(
+    home_subdir="home",
+    include=CODEX_CRED_MANIFEST.include + [
+        ".codex/config.toml",
+    ],
+    version=CODEX_SEED_MANIFEST_VERSION,
+    consume_transform=None,  # no cwd-rekey for codex (pre-trust is in _prepare)
+)
+
+
+async def delete_seed(store, seed_id: str):
+    """Delete a codex seed doc; returns its GridFS blobId (or None).
+
+    Takes an optio store binding (``optio.mongo_store`` — exposes ``db`` and
+    ``prefix``) as-is, so consuming apps hand over the whole namespace handle
+    instead of threading db+prefix (or knowing the collection suffix). The
+    caller still removes the returned blob from GridFS.
+    """
+    return await seeds.delete_seed(
+        store.db, prefix=store.prefix, suffix=CODEX_SEED_SUFFIX, seed_id=seed_id,
+    )
+
+
+async def list_seeds(store) -> list[dict]:
+    """List codex seeds as [{seedId, createdAt}, ...]. Takes an optio store
+    binding (``optio.mongo_store``) as-is."""
+    return await seeds.list_seeds(store.db, prefix=store.prefix, suffix=CODEX_SEED_SUFFIX)
+
+
+async def purge_seed(store, seed_id: str) -> None:
+    """Fully expunge a codex seed (doc + its GridFS blob); raises KeyError if
+    absent. Takes an optio store binding (``optio.mongo_store``) as-is.
+
+    Mirrors ``optio_grok.purge_seed`` / ``optio_claudecode.purge_seed``; a
+    thin re-export of the ``optio_agents.seeds.purge_seed`` engine."""
+    return await seeds.purge_seed(
+        store.db, prefix=store.prefix, suffix=CODEX_SEED_SUFFIX, seed_id=seed_id,
+    )