optio-codex 0.1.0__py3-none-any.whl

optio_codex/__init__.py

@@ -0,0 +1,66 @@
+"""optio-codex — run OpenAI Codex as an optio task."""
+
+import logging as _logging
+
+from optio_agents import HookContext, HookContextProtocol
+from optio_host import (
+    HostCommandError,
+    RunResult,
+    SSHConfig,
+)
+
+from optio_codex.seed_manifest import (
+    CODEX_CRED_MANIFEST,
+    CODEX_SEED_MANIFEST,
+    CODEX_SEED_SUFFIX,
+    delete_seed,
+    list_seeds,
+    purge_seed,
+)
+from optio_codex.session import create_codex_task, run_codex_session
+from optio_codex.types import (
+    AllowedDir,
+    ApprovalPolicy,
+    CodexTaskConfig,
+    ConversationMode,
+    DeliverableCallback,
+    HookCallback,
+    SandboxMode,
+    ToolVerbosity,
+    ThinkingVerbosity,
+    SeedProvider,
+    SeedUnavailableError,
+)
+from optio_codex.verify import verify_and_refresh_seed
+
+
+_logging.getLogger("asyncssh").setLevel(_logging.WARNING)
+
+
+__all__ = [
+    "create_codex_task",
+    "run_codex_session",
+    "AllowedDir",
+    "ApprovalPolicy",
+    "CodexTaskConfig",
+    "ConversationMode",
+    "DeliverableCallback",
+    "HookCallback",
+    "SandboxMode",
+    "ToolVerbosity",
+    "ThinkingVerbosity",
+    "SeedProvider",
+    "SeedUnavailableError",
+    "SSHConfig",
+    "HookContext",
+    "HookContextProtocol",
+    "HostCommandError",
+    "RunResult",
+    "CODEX_SEED_MANIFEST",
+    "CODEX_CRED_MANIFEST",
+    "CODEX_SEED_SUFFIX",
+    "delete_seed",
+    "list_seeds",
+    "purge_seed",
+    "verify_and_refresh_seed",
+]

optio_codex/conversation.py

@@ -0,0 +1,553 @@
+"""CodexConversation — engine-side driver for one headless Codex session over
+the app-server protocol: JSON-RPC 2.0 over the stdin/stdout of
+``codex app-server``.
+
+The session body launches ``codex app-server`` via
+``host.launch_subprocess(stdin=True, merge_stderr=False)``, attaches the
+handle here, starts ``run_reader()``, runs ``bootstrap()`` (the handshake),
+publishes this object via ``ctx.publish_result``, and waits until the
+subprocess ends.
+
+Event payloads are transparent: every parsed stdout JSON-RPC object is fanned
+out to ``on_event`` subscribers as a dict, unmodified. Synthetic events use
+the ``x-optio-`` type prefix. Structurally mirrors optio-grok's
+GrokConversation, but frames the codex app-server protocol instead of ACP.
+
+============================================================================
+APP-SERVER WIRE FACTS — pinned by a LIVE PROBE of the real ``codex
+app-server`` (codex-cli 0.142.5) plus the schema dump generated by that exact
+binary (``codex app-server generate-json-schema``). Evidence: the scratchpad
+``probe.py`` transcript + ``schema/{ClientRequest,ServerRequest,
+ServerNotification,ClientNotification}.json``. See the design doc
+"Conversation transport (Stage 6)".
+============================================================================
+
+FRAMING: newline-delimited JSON (JSONL); JSON-RPC 2.0 semantics with the
+``"jsonrpc"`` field OMITTED on the wire (both directions; probed). NO
+Content-Length headers. Backpressure: error ``-32001`` "Server overloaded;
+retry later." is retryable.
+
+Client -> server REQUESTS (have ``id``, expect a ``result``):
+  * ``initialize`` {clientInfo:{name,title,version}, capabilities?} ->
+    {userAgent, codexHome, platformFamily, platformOs}. We do NOT set
+    ``capabilities.experimentalApi`` (stable surface only);
+    ``optOutNotificationMethods`` suppresses exact-match notifications
+    (we opt out of the unrendered ``item/commandExecution/outputDelta``).
+    Followed by the ``initialized`` NOTIFICATION (no id). Any other request
+    first -> "Not initialized" error.
+  * ``account/read`` {refreshToken:false} -> {account|null,
+    requiresOpenaiAuth} — bootstrap auth sanity (warn-only, never fatal:
+    fakes and API-key setups may report no account).
+  * ``model/list`` {} -> {data:[{id, displayName, hidden, isDefault, …}],
+    nextCursor} — captured raw for the widget picker (models.py maps it).
+  * ``thread/start`` {cwd, sandbox, approvalPolicy, model?} ->
+    {thread:{id,…}, model, …} (+ a ``thread/started`` notification).
+    SCHEMA CATCH: on thread/start the field is ``sandbox`` with the
+    kebab-case enum "read-only"|"workspace-write"|"danger-full-access";
+    the camelCase ``sandboxPolicy`` OBJECT exists only on turn/start
+    (0.142.5 ThreadStartParams; the probe used sandbox:"read-only").
+    NOT ephemeral — the rollout file is the resume source (Plan B).
+  * ``thread/resume`` {threadId, …same overrides} — resume path; response
+    shape matches thread/start.
+  * ``turn/start`` {threadId, input:[{type:"text",text}], model?} ->
+    IMMEDIATE ACK {turn:{id, status:"inProgress", items:[]}} — the ACK is
+    NOT the turn end. Per-turn overrides (``model``) become the default for
+    subsequent turns on the thread == the INLINE model-switch seam
+    (request_model_change pins the next turn's model; no wire write).
+  * ``turn/interrupt`` {threadId, turnId} -> {} ACK; the completion signal
+    is the subsequent ``turn/completed`` with status "interrupted".
+
+Server -> client NOTIFICATIONS (no ``id``):
+  * ``turn/started`` {threadId, turn:{id,…}} — tracks current_turn_id.
+  * ``item/agentMessage/delta`` {threadId, turnId, itemId, delta} —
+    concatenated per itemId -> the turn's answer text.
+  * ``item/completed`` {…, item:{type,…}} — for item.type "agentMessage"
+    the item's ``text`` is authoritative for that itemId.
+  * ``item/started`` / ``item/reasoning/summaryTextDelta`` /
+    ``item/reasoning/textDelta`` / ``thread/tokenUsage/updated`` /
+    ``error`` {error:{message, codexErrorInfo?}, willRetry} / … — passed
+    through untouched to on_event (the UI reducer renders them).
+  * ``turn/completed`` {threadId, turn:{id, status, error?}} — THE TURN-END
+    SIGNAL, status ∈ "completed" | "interrupted" | "failed".
+
+Server -> client REQUESTS (have ``id`` AND ``method``, WE must respond):
+  * ``item/commandExecution/requestApproval`` {threadId, turnId, itemId,
+    command?, cwd?, reason?, …} and ``item/fileChange/requestApproval``
+    {threadId, turnId, itemId, reason?, grantRoot?} — the permission gate
+    seam. ANSWER with result {"decision": D}: optio allow -> "accept";
+    optio deny -> "decline" (the agent continues the turn — "cancel" would
+    also interrupt it, which is NOT what PermissionDecision deny means).
+    The full decision enums also carry "acceptForSession" and (commands
+    only) execpolicy/network amendment objects — unused here. A deny
+    *message* is not transmittable on this wire.
+  * Anything else (``item/tool/requestUserInput``, ``item/permissions/
+    requestApproval``, ``mcpServer/elicitation/request``, ``account/
+    chatgptAuthTokens/refresh``, ``attestation/generate``, legacy
+    ``applyPatchApproval``/``execCommandApproval``, ``item/tool/call``) —
+    answered with a JSON-RPC ``-32601`` error defensively (they only fire
+    for capabilities we don't advertise / flows we don't start).
+============================================================================
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+
+from optio_agents.conversation import (
+    ConversationClosed,
+    PermissionDecision,
+    PermissionRequest,
+)
+
+_LOG = logging.getLogger(__name__)
+
+# Server->client requests that ARE the permission gate; everything else with
+# an id+method gets a defensive -32601.
+_APPROVAL_METHODS = (
+    "item/commandExecution/requestApproval",
+    "item/fileChange/requestApproval",
+)
+
+
+class CodexConversation:
+    """Implements optio_agents.conversation.Conversation for Codex
+    (app-server)."""
+
+    def __init__(
+        self,
+        *,
+        cwd: str,
+        agent_label: str = "codex",
+        permission_gate: bool = False,
+        model: str | None = None,
+        sandbox: str = "workspace-write",
+        resume_thread_id: str | None = None,
+    ) -> None:
+        self._cwd = cwd
+        self._agent_label = agent_label
+        # When False, requestApproval is answered with a defensive deny
+        # instead of being queued for a handler.
+        self._permission_gate = permission_gate
+        self._model = model
+        self._sandbox = sandbox
+        # With the gate on codex must ask (on-request); without it, never.
+        self._approval_policy = "on-request" if permission_gate else "never"
+        self._resume_thread_id = resume_thread_id
+        self._handle = None
+        # Captured at bootstrap; Plan B's snapshot sessionId seam reads
+        # thread_id at capture time.
+        self.thread_id: str | None = None
+        self.current_turn_id: str | None = None
+        self.server_info: dict | None = None
+        self.account: dict | None = None
+        # Raw model/list result from bootstrap (models.parse_model_list maps
+        # it) so the session can populate the picker without a second probe.
+        self.model_list: dict | None = None
+        self.current_model_id: str | None = None
+        self._requested_model: str | None = None
+        self._pending = 0                    # user turns awaiting turn/completed
+        self._closed = asyncio.Event()
+        self._close_reason: str | None = None
+        # Cooperative-shutdown request towards the owning task body.
+        self.close_requested = asyncio.Event()
+        self._write_lock = asyncio.Lock()
+        self._event_queue: asyncio.Queue[dict] = asyncio.Queue()
+        self._event_handlers: list = []
+        self._message_handlers: list = []
+        self._permission_handler = None
+        self._queued_permission_requests: list[dict] = []
+        # JSON-RPC id bookkeeping.
+        self._next_id = 0
+        self._req_futures: dict[int, asyncio.Future] = {}   # handshake/interrupt
+        self._turn_req_ids: set[int] = set()                # turn/start ACKs
+        # Accumulates agentMessage text for the current turn, per itemId.
+        self._answer_order: list[str] = []
+        self._answer_texts: dict[str, str] = {}
+        self._dispatcher_task: asyncio.Task | None = None
+
+    # -- wiring ------------------------------------------------------------
+
+    def attach(self, handle) -> None:
+        """Attach the live ProcessHandle (must have been launched with
+        stdin=True)."""
+        if handle.stdin is None:
+            raise ValueError(
+                "CodexConversation.attach: handle has no stdin writer; launch "
+                "the subprocess with stdin=True"
+            )
+        self._handle = handle
+
+    async def bootstrap(self) -> None:
+        """Run the app-server handshake: ``initialize`` + ``initialized``,
+        then ``account/read`` (auth sanity, warn-only), ``model/list`` (the
+        picker source), and ``thread/start`` / ``thread/resume``.
+
+        Requires ``run_reader()`` to already be running (it routes the
+        responses back to the futures created here).
+        """
+        resp = await self._request("initialize", {
+            "clientInfo": {
+                "name": "optio_codex", "title": "Optio", "version": "0.1.0",
+            },
+            # Stable surface only (no experimentalApi). Opt out of the one
+            # high-volume stream nothing downstream renders.
+            "capabilities": {
+                "optOutNotificationMethods": [
+                    "item/commandExecution/outputDelta",
+                ],
+            },
+        })
+        self.server_info = (resp or {}).get("result") or {}
+        await self._write_json({"method": "initialized"})
+
+        resp = await self._request("account/read", {"refreshToken": False})
+        self.account = ((resp or {}).get("result") or {}).get("account")
+        if self.account is None:
+            _LOG.warning(
+                "codex conversation: account/read reports no active auth; "
+                "turns may fail until a seed/login provides credentials",
+            )
+
+        resp = await self._request("model/list", {})
+        self.model_list = (
+            (resp or {}).get("result") if "error" not in (resp or {}) else None
+        )
+
+        if self._resume_thread_id is not None:
+            method = "thread/resume"
+            params: dict = {"threadId": self._resume_thread_id}
+        else:
+            method = "thread/start"
+            params = {"cwd": self._cwd}
+        # thread/start takes `sandbox` (kebab-case enum) — NOT the turn-level
+        # `sandboxPolicy` object (see the module docstring's schema catch).
+        params["sandbox"] = self._sandbox
+        params["approvalPolicy"] = self._approval_policy
+        if self._model:
+            params["model"] = self._model
+        resp = await self._request(method, params)
+        if "error" in (resp or {}):
+            raise RuntimeError(
+                f"codex {method} failed: {(resp or {}).get('error')!r}"
+            )
+        result = (resp or {}).get("result") or {}
+        thread = result.get("thread") or {}
+        self.thread_id = thread.get("id")
+        if not self.thread_id:
+            raise RuntimeError(
+                f"codex {method} returned no thread id: {result!r}"
+            )
+        self.current_model_id = result.get("model") or self._model
+
+    async def run_reader(self) -> None:
+        """Drain stdout until EOF; route JSON-RPC messages. Owned by the
+        session body; ends when the subprocess ends."""
+        self._dispatcher_task = asyncio.create_task(self._dispatch_loop())
+        try:
+            async for raw in self._handle.stdout:
+                line = (
+                    raw.decode("utf-8", errors="replace")
+                    if isinstance(raw, bytes) else str(raw)
+                ).strip()
+                if not line:
+                    continue
+                try:
+                    obj = json.loads(line)
+                except ValueError:
+                    _LOG.warning("codex conversation: unparseable line: %.200s", line)
+                    self._event_queue.put_nowait(
+                        {"type": "x-optio-unparseable", "line": line},
+                    )
+                    continue
+                self._route(obj)
+        finally:
+            await self._finish("process ended")
+
+    def _route(self, obj: dict) -> None:
+        rid = obj.get("id")
+        method = obj.get("method")
+        if method is None and rid is not None and ("result" in obj or "error" in obj):
+            # Response to one of OUR requests.
+            if rid in self._req_futures:
+                fut = self._req_futures.pop(rid)
+                if not fut.done():
+                    fut.set_result(obj)
+            elif rid in self._turn_req_ids:
+                # turn/start ACK — NOT the turn end (that is turn/completed).
+                self._turn_req_ids.discard(rid)
+                if "error" in obj:
+                    # The turn never started; nothing further will arrive.
+                    _LOG.warning(
+                        "codex conversation: turn/start rejected: %r",
+                        obj.get("error"),
+                    )
+                    self._pending = max(0, self._pending - 1)
+                else:
+                    turn = ((obj.get("result") or {}).get("turn")) or {}
+                    if turn.get("id"):
+                        self.current_turn_id = turn["id"]
+        elif method is not None and rid is not None:
+            # Server -> client REQUEST that we must answer.
+            if method in _APPROVAL_METHODS:
+                self._on_permission(obj)
+            else:
+                asyncio.ensure_future(self._write_json({
+                    "id": rid,
+                    "error": {"code": -32601,
+                              "message": f"optio codex client does not implement {method}"},
+                }))
+        elif method is not None:
+            self._on_notification(method, obj)
+        self._event_queue.put_nowait(obj)
+
+    def _on_notification(self, method: str, obj: dict) -> None:
+        params = obj.get("params") or {}
+        if method == "item/agentMessage/delta":
+            item_id = str(params.get("itemId") or "")
+            delta = params.get("delta") or ""
+            if delta:
+                if item_id not in self._answer_texts:
+                    self._answer_order.append(item_id)
+                    self._answer_texts[item_id] = ""
+                self._answer_texts[item_id] += delta
+        elif method == "item/completed":
+            item = params.get("item") or {}
+            if item.get("type") == "agentMessage":
+                item_id = str(item.get("id") or "")
+                if item_id not in self._answer_texts:
+                    self._answer_order.append(item_id)
+                # The completed item's text is authoritative for its itemId
+                # (heals any lost/duplicated deltas).
+                self._answer_texts[item_id] = (
+                    item.get("text") or self._answer_texts.get(item_id, "")
+                )
+        elif method == "turn/started":
+            turn = params.get("turn") or {}
+            if turn.get("id"):
+                self.current_turn_id = turn["id"]
+        elif method == "turn/completed":
+            # THE turn-end signal (status completed | interrupted | failed).
+            self._pending = max(0, self._pending - 1)
+            self.current_turn_id = None
+            text = "".join(self._answer_texts[i] for i in self._answer_order)
+            self._answer_order = []
+            self._answer_texts = {}
+            self._fire_message(text)
+        # else: thread/started, item/started, reasoning deltas, tokenUsage,
+        # error, … — pass through to on_event only.
+
+    # -- event fan-out -----------------------------------------------------
+
+    async def _dispatch_loop(self) -> None:
+        while True:
+            obj = await self._event_queue.get()
+            for handler in list(self._event_handlers):
+                await self._call_handler(handler, obj, "on_event")
+
+    async def _call_handler(self, handler, arg, label: str) -> None:
+        try:
+            result = handler(arg)
+            if asyncio.iscoroutine(result):
+                await result
+        except Exception:  # noqa: BLE001 — subscriber bugs never kill the driver
+            _LOG.exception("codex conversation: %s handler raised", label)
+
+    def _fire_message(self, text: str) -> None:
+        for handler in list(self._message_handlers):
+            asyncio.ensure_future(self._call_handler(handler, text, "on_message"))
+
+    # -- permission gate ----------------------------------------------------
+
+    def _on_permission(self, obj: dict) -> None:
+        if not self._permission_gate:
+            _LOG.warning(
+                "codex conversation: %s received with permission_gate off; "
+                "denying defensively", obj.get("method"),
+            )
+            asyncio.ensure_future(self._answer_permission_decision(
+                obj, PermissionDecision(
+                    behavior="deny",
+                    message="optio harness: permission gate not enabled",
+                ),
+            ))
+            return
+        if self._permission_handler is None:
+            # Queue until a handler is registered; the turn blocks
+            # server-side, which closes the publish/registration race.
+            self._queued_permission_requests.append(obj)
+            return
+        asyncio.ensure_future(self._answer_permission(obj))
+
+    async def _answer_permission(self, obj: dict) -> None:
+        params = obj.get("params") or {}
+        if obj.get("method") == "item/commandExecution/requestApproval":
+            tool_name = str(params.get("command") or "command execution")
+        else:
+            tool_name = "file change"
+        request = PermissionRequest(
+            tool_name=tool_name,
+            input=params,
+            raw=obj,
+        )
+        try:
+            decision = await self._permission_handler(request)
+        except Exception:  # noqa: BLE001
+            _LOG.exception("codex conversation: permission handler raised; denying")
+            decision = PermissionDecision(
+                behavior="deny",
+                message="optio harness: permission handler failed",
+            )
+        await self._answer_permission_decision(obj, decision)
+
+    async def _answer_permission_decision(
+        self, obj: dict, decision: PermissionDecision,
+    ) -> None:
+        # allow -> accept; deny -> decline (the agent continues the turn —
+        # "cancel" would also interrupt it, which deny does not mean). The
+        # deny message is not transmittable on this wire.
+        decision_str = "accept" if decision.behavior == "allow" else "decline"
+        await self._write_json({
+            "id": obj.get("id"),
+            "result": {"decision": decision_str},
+        })
+
+    # -- Conversation protocol surface --------------------------------------
+
+    async def send(self, text: str) -> None:
+        if self._closed.is_set():
+            raise ConversationClosed(self._close_reason or "conversation closed")
+        if self.thread_id is None:
+            raise RuntimeError("CodexConversation.send before bootstrap() completed")
+        self._next_id += 1
+        rid = self._next_id
+        self._turn_req_ids.add(rid)
+        self._pending += 1
+        params: dict = {
+            "threadId": self.thread_id,
+            "input": [{"type": "text", "text": text}],
+        }
+        if self._requested_model is not None:
+            # Inline model switch: the override becomes the thread default
+            # for subsequent turns (app-server contract).
+            params["model"] = self._requested_model
+        try:
+            await self._write_json({
+                "id": rid, "method": "turn/start", "params": params,
+            })
+        except Exception:
+            self._turn_req_ids.discard(rid)
+            self._pending = max(0, self._pending - 1)
+            await self._finish("stdin write failed")
+            raise
+
+    def on_event(self, handler):
+        self._event_handlers.append(handler)
+        return lambda: self._event_handlers.remove(handler)
+
+    def on_message(self, handler):
+        self._message_handlers.append(handler)
+        return lambda: self._message_handlers.remove(handler)
+
+    def on_permission_request(self, handler):
+        self._permission_handler = handler
+        queued, self._queued_permission_requests = (
+            self._queued_permission_requests, [],
+        )
+        for obj in queued:
+            asyncio.ensure_future(self._answer_permission(obj))
+
+        def _unsub() -> None:
+            if self._permission_handler is handler:
+                self._permission_handler = None
+        return _unsub
+
+    def is_pending(self) -> bool:
+        return self._pending > 0
+
+    async def interrupt(self) -> None:
+        if self._closed.is_set():
+            raise ConversationClosed(self._close_reason or "conversation closed")
+        if (
+            self._pending == 0
+            or self.thread_id is None
+            or self.current_turn_id is None
+        ):
+            return
+        # turn/interrupt is a normal request; its {} ACK is NOT the
+        # completion signal — the in-flight turn ends via turn/completed
+        # with status "interrupted".
+        await self._request("turn/interrupt", {
+            "threadId": self.thread_id, "turnId": self.current_turn_id,
+        })
+
+    def request_model_change(self, model: str) -> None:
+        """Switch model mid-conversation INLINE — with NO wire write: a
+        ``model`` override on the next ``turn/start`` becomes the thread's
+        default for subsequent turns (app-server contract; see models.py).
+        Synchronous surface (the listener calls it without await)."""
+        if self._closed.is_set():
+            raise ConversationClosed(self._close_reason or "conversation closed")
+        if self.thread_id is None:
+            raise RuntimeError(
+                "CodexConversation.request_model_change before bootstrap() completed"
+            )
+        self._requested_model = model
+        self.current_model_id = model  # optimistic; the next turn pins it
+
+    async def close(self) -> None:
+        self.close_requested.set()
+
+    @property
+    def closed(self) -> bool:
+        return self._closed.is_set()
+
+    # -- internals -----------------------------------------------------------
+
+    async def _request(self, method: str, params: dict) -> dict:
+        """Send a client->server request and await its response (handshake +
+        turn/interrupt only; turn/start is tracked via _turn_req_ids)."""
+        self._next_id += 1
+        rid = self._next_id
+        fut: asyncio.Future = asyncio.get_event_loop().create_future()
+        self._req_futures[rid] = fut
+        await self._write_json({"id": rid, "method": method, "params": params})
+        return await fut
+
+    async def _write_json(self, obj: dict) -> None:
+        # The app-server wire omits the "jsonrpc" field (probed; README).
+        await self._write_bytes((json.dumps(obj) + "\n").encode("utf-8"))
+
+    async def _write_bytes(self, data: bytes) -> None:
+        async with self._write_lock:
+            stdin = self._handle.stdin
+            stdin.write(data)
+            drain = getattr(stdin, "drain", None)
+            if drain is not None:
+                await drain()
+
+    async def _finish(self, reason: str) -> None:
+        if self._closed.is_set():
+            return
+        self._closed.set()
+        self._close_reason = reason
+        # Fail any in-flight handshake/interrupt requests.
+        for fut in self._req_futures.values():
+            if not fut.done():
+                fut.set_exception(ConversationClosed(reason))
+        self._req_futures.clear()
+        self._event_queue.put_nowait({"type": "x-optio-closed", "reason": reason})
+        # Stop the dispatcher, then drain whatever it left so subscribers are
+        # guaranteed to see the final x-optio-closed event.
+        if self._dispatcher_task is not None:
+            self._dispatcher_task.cancel()
+            try:
+                await self._dispatcher_task
+            except asyncio.CancelledError:
+                pass
+            self._dispatcher_task = None
+        while not self._event_queue.empty():
+            obj = self._event_queue.get_nowait()
+            for handler in list(self._event_handlers):
+                await self._call_handler(handler, obj, "on_event")