codex-ipc 0.1.0__tar.gz

codex_ipc-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,90 @@
+name: Python Package
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-latest
+          - macos-latest
+          - windows-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        run: python -m pip install --upgrade uv
+
+      - name: Run test suite
+        run: uv run --with pytest pytest tests/ -q
+
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    needs: test
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        run: python -m pip install --upgrade uv
+
+      - name: Build package
+        run: uv build
+
+      - name: Check distributions
+        run: uvx twine check --strict dist/*
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: build
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment:
+      name: pypi
+      url: https://pypi.org/project/codex-ipc/
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

codex_ipc-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+tmp/
+.codex
+.zed/

codex_ipc-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

codex_ipc-0.1.0/.vscode/launch.json

@@ -0,0 +1,19 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Demo",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "examples.demo",
+            "cwd": "${workspaceFolder}",
+            "env": {
+                "PYTHONPATH": "${workspaceFolder}/src"
+            },
+            "console": "integratedTerminal"
+        }
+    ]
+}

codex_ipc-0.1.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: codex-ipc
+Version: 0.1.0
+Summary: Add your description here
+Requires-Python: >=3.12
+Requires-Dist: pydantic>=2.12
+Provides-Extra: tui
+Requires-Dist: pillow>=12.2.0; extra == 'tui'
+Requires-Dist: rich>=15.0.0; extra == 'tui'
+Requires-Dist: textual>=8.2.5; extra == 'tui'
+Description-Content-Type: text/markdown
+
+# codex-ipc
+
+Python facade for running Codex app-server sessions and sharing their live
+conversation state over the Codex IPC owner/follower protocol.
+
+## Library usage
+
+```python
+from pathlib import Path
+
+from codex_ipc import CodexIpcConfig, CodexIpcSession
+
+
+async def main() -> None:
+    config = CodexIpcConfig(
+        codex_bin=Path("/opt/homebrew/bin/codex"),
+        host_id="local",
+        model="gpt-5.4",
+        reasoning_effort="high",
+    )
+
+    async with CodexIpcSession(config) as session:
+        thread = await session.start_new_thread()
+        print(f"started {thread.id}")
+
+        async for state in session.watch_state():
+            # Forward this raw conversation state to a browser over WebSocket.
+            print(state)
+
+
+async def resume_existing(thread_id: str) -> None:
+    async with CodexIpcSession(CodexIpcConfig(thread_id=thread_id)) as session:
+        await session.hydrate_initial_state()
+        await session.run_prompt("Summarize the current repo", wait_for_completion=True)
+```
+
+If `codex_bin` is omitted, the vendored app-server SDK uses its normal runtime
+resolver. Pass a `codex_app_server.AppServerConfig` as `app_server_config` when
+you need full control over app-server launch arguments.
+
+## TUI demo
+
+The TUI is a development tool and is kept out of the core dependency set:
+
+```bash
+uv run --extra tui codex-ipc-demo --codex-bin /opt/homebrew/bin/codex
+```
+
+Core imports such as `import codex_ipc` do not require `textual`, `rich`, or
+`pillow`.

codex_ipc-0.1.0/README.md

@@ -0,0 +1,50 @@
+# codex-ipc
+
+Python facade for running Codex app-server sessions and sharing their live
+conversation state over the Codex IPC owner/follower protocol.
+
+## Library usage
+
+```python
+from pathlib import Path
+
+from codex_ipc import CodexIpcConfig, CodexIpcSession
+
+
+async def main() -> None:
+    config = CodexIpcConfig(
+        codex_bin=Path("/opt/homebrew/bin/codex"),
+        host_id="local",
+        model="gpt-5.4",
+        reasoning_effort="high",
+    )
+
+    async with CodexIpcSession(config) as session:
+        thread = await session.start_new_thread()
+        print(f"started {thread.id}")
+
+        async for state in session.watch_state():
+            # Forward this raw conversation state to a browser over WebSocket.
+            print(state)
+
+
+async def resume_existing(thread_id: str) -> None:
+    async with CodexIpcSession(CodexIpcConfig(thread_id=thread_id)) as session:
+        await session.hydrate_initial_state()
+        await session.run_prompt("Summarize the current repo", wait_for_completion=True)
+```
+
+If `codex_bin` is omitted, the vendored app-server SDK uses its normal runtime
+resolver. Pass a `codex_app_server.AppServerConfig` as `app_server_config` when
+you need full control over app-server launch arguments.
+
+## TUI demo
+
+The TUI is a development tool and is kept out of the core dependency set:
+
+```bash
+uv run --extra tui codex-ipc-demo --codex-bin /opt/homebrew/bin/codex
+```
+
+Core imports such as `import codex_ipc` do not require `textual`, `rich`, or
+`pillow`.

codex_ipc-0.1.0/examples/demo.py

@@ -0,0 +1,451 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
+import contextlib
+import curses
+import json
+import sys
+import textwrap
+from pathlib import Path
+from typing import Any
+
+from codex_ipc.config import CodexIpcConfig
+from codex_ipc.session import CodexIpcSession
+from ipc.conversation_state import conversation_messages
+
+DEFAULT_HOST_ID = "local"
+
+
+class OptionalDependencyError(RuntimeError):
+    pass
+
+
+def safe_addstr(window: Any, y: int, x: int, text: str, attrs: int = 0) -> None:
+    try:
+        height, width = window.getmaxyx()
+        if y < 0 or y >= height or x >= width:
+            return
+        window.addstr(y, max(0, x), text[: max(0, width - max(0, x) - 1)], attrs)
+    except curses.error:
+        return
+
+
+class TerminalChatUI:
+    def __init__(self, session: Any) -> None:
+        self.session = session
+        self.input_buffer = ""
+        self.status_lines: list[str] = []
+        self._needs_render = True
+        self._running = True
+
+    def request_render(self) -> None:
+        self._needs_render = True
+
+    def set_status(self, message: str) -> None:
+        self.status_lines.append(message)
+        self.status_lines = self.status_lines[-3:]
+        self.request_render()
+
+    async def run(self) -> None:
+        stdscr = curses.initscr()
+        try:
+            curses.noecho()
+            curses.cbreak()
+            with contextlib.suppress(curses.error):
+                curses.curs_set(1)
+            stdscr.keypad(True)
+            stdscr.nodelay(True)
+
+            while self._running:
+                if self._needs_render:
+                    self._render(stdscr)
+                    self._needs_render = False
+
+                key = self._read_key(stdscr)
+                if key is not None:
+                    await self._handle_key(key)
+                    self.request_render()
+
+                await asyncio.sleep(0.03)
+        finally:
+            with contextlib.suppress(Exception):
+                stdscr.keypad(False)
+                curses.nocbreak()
+                curses.echo()
+                curses.endwin()
+
+    def _read_key(self, stdscr: Any) -> str | int | None:
+        try:
+            return stdscr.get_wch()
+        except curses.error:
+            return None
+
+    async def _handle_key(self, key: str | int) -> None:
+        if isinstance(key, str):
+            if key in {"\n", "\r"}:
+                await self._submit_input()
+                return
+            if key in {"\x03", "\x04"}:
+                self._running = False
+                return
+            if key in {"\x7f", "\b"}:
+                self.input_buffer = self.input_buffer[:-1]
+                return
+            if key.isprintable():
+                self.input_buffer += key
+                return
+
+        if key == curses.KEY_BACKSPACE:
+            self.input_buffer = self.input_buffer[:-1]
+        elif key == curses.KEY_RESIZE:
+            self.request_render()
+
+    async def _submit_input(self) -> None:
+        command = self.input_buffer.strip()
+        self.input_buffer = ""
+        if not command:
+            return
+
+        try:
+            await self._run_command(command)
+        except Exception as exc:
+            self.set_status(f"error: {exc}")
+
+    async def _run_command(self, command: str) -> None:
+        if command in {"/exit", "/quit"}:
+            self._running = False
+            return
+        if command == "/role":
+            self.set_status(json.dumps(self.session.stream_role, ensure_ascii=False))
+            return
+        if command == "/state":
+            self.set_status(
+                "state printed above is disabled in chat UI; use /role or inspect logs"
+            )
+            return
+        if command in ("/start-thread", "/new"):
+            thread = await self.session.start_new_thread()
+            self.set_status(
+                f"started thread {getattr(thread, 'id', self.session.thread_id)}"
+            )
+            return
+        if command == "/resume":
+            await self.session.ensure_owner()
+            self.set_status("resumed locally and became owner")
+            return
+        if command == "/archive":
+            await self.session.archive_thread()
+            self.set_status("archived current thread")
+            return
+        if command == "/unarchive":
+            await self.session.unarchive_thread()
+            self.set_status("unarchived current thread")
+            return
+        if command.startswith("/rename "):
+            await self.session.set_thread_name(command[8:].strip())
+            self.set_status("renamed current thread")
+            return
+        if command == "/compact":
+            await self.session.compact_thread()
+            self.set_status("compact requested")
+            return
+        if command == "/interrupt":
+            await self.session.interrupt_turn()
+            self.set_status("interrupt requested")
+            return
+        if command == "/wait":
+            await self.session.wait_until_idle()
+            self.set_status("conversation is idle")
+            return
+        if command.startswith("/steer "):
+            await self.session.steer_turn(command[7:].strip())
+            return
+        if command.startswith("/ask "):
+            await self.session.run_prompt(
+                command[5:].strip(), wait_for_completion=False
+            )
+            return
+
+        await self.session.run_prompt(command, wait_for_completion=False)
+
+    def _render(self, stdscr: Any) -> None:
+        height, width = stdscr.getmaxyx()
+        stdscr.erase()
+
+        role = self.session.stream_role or {"role": "none"}
+        role_text = json.dumps(role, ensure_ascii=False)
+        title = f"Codex IPC demo | thread={self.session.thread_id} | role={role_text}"
+        safe_addstr(stdscr, 0, 0, title, curses.A_BOLD)
+
+        status = (
+            self.status_lines[-1]
+            if self.status_lines
+            else "Type a message. Commands: /resume /role /compact /interrupt /wait /quit"
+        )
+        safe_addstr(stdscr, 1, 0, status[: max(1, width - 1)])
+
+        separator = "-" * max(0, width - 1)
+        safe_addstr(stdscr, max(0, height - 3), 0, separator)
+
+        input_prompt = "> "
+        input_line = f"{input_prompt}{self.input_buffer}"
+        safe_addstr(stdscr, max(0, height - 2), 0, input_line)
+        safe_addstr(
+            stdscr, max(0, height - 1), 0, "Enter sends. Plain text is a user message."
+        )
+
+        chat_top = 3
+        chat_bottom = max(chat_top, height - 4)
+        chat_height = max(0, chat_bottom - chat_top + 1)
+        rendered = self._rendered_chat_lines(width)
+        visible = rendered[-chat_height:]
+        for offset, (x, text, attrs) in enumerate(visible):
+            safe_addstr(stdscr, chat_top + offset, x, text, attrs)
+
+        cursor_x = min(width - 1, len(input_line))
+        with contextlib.suppress(curses.error):
+            stdscr.move(max(0, height - 2), cursor_x)
+        stdscr.refresh()
+
+    def _rendered_chat_lines(self, width: int) -> list[tuple[int, str, int]]:
+        lines: list[tuple[int, str, int]] = []
+        max_bubble_width = max(20, min(80, width - 8, int(width * 0.72)))
+
+        label_map = {
+            "user": "You",
+            "assistant": "AI",
+            "steer": "Steer",
+            "hookPrompt": "Hook Prompt",
+            "plan": "Plan",
+            "commandExecution": "Shell",
+            "dynamicToolCall": "Tool",
+            "fileChange": "Files",
+            "mcpToolCall": "MCP",
+            "collabAgentToolCall": "Agent",
+            "hook": "Hook",
+            "reasoning": "Reasoning",
+            "webSearch": "Search",
+            "imageView": "Image View",
+            "enteredReviewMode": "Review On",
+            "exitedReviewMode": "Review Off",
+            "contextCompaction": "Compaction",
+        }
+
+        for role, text in conversation_messages(self.session.state):
+            if lines:
+                lines.append((0, "", 0))
+
+            label = label_map.get(role, role)
+            attrs = curses.A_BOLD if role in {"user", "steer"} else 0
+            wrapped = self._wrap_text(text, max_bubble_width)
+            if role in {"user", "steer"}:
+                content_width = max(
+                    [len(label), *(len(line) for line in wrapped)], default=0
+                )
+                x = max(0, width - content_width - 2)
+                lines.append((x, label, attrs))
+                for line in wrapped:
+                    lines.append((max(0, width - len(line) - 2), line, attrs))
+            else:
+                lines.append((0, label, attrs))
+                for line in wrapped:
+                    lines.append((0, line, attrs))
+
+        if not lines:
+            lines.append(
+                (0, "No messages yet. Waiting for snapshot or local resume...", 0)
+            )
+        return lines
+
+    def _wrap_text(self, text: str, width: int) -> list[str]:
+        if not text:
+            return [""]
+
+        wrapped: list[str] = []
+        for paragraph in text.splitlines() or [""]:
+            if not paragraph:
+                wrapped.append("")
+                continue
+            wrapped.extend(
+                textwrap.wrap(
+                    paragraph,
+                    width=width,
+                    replace_whitespace=False,
+                    drop_whitespace=False,
+                )
+                or [""]
+            )
+        return wrapped
+
+
+class DemoApp:
+    def __init__(
+        self,
+        *,
+        host_id: str,
+        thread_id: str | None,
+        model: str,
+        reasoning_effort: str,
+        codex_bin: Path | None = None,
+    ) -> None:
+        self._ui: TerminalChatUI | None = None
+        self.session = CodexIpcSession(
+            CodexIpcConfig(
+                thread_id=thread_id,
+                host_id=host_id,
+                client_type="demo",
+                model=model,
+                reasoning_effort=reasoning_effort,
+                codex_bin=codex_bin,
+            ),
+            notify=self._notify,
+            state_listener=lambda _state: self._request_render(),
+        )
+
+    @property
+    def thread_id(self) -> str:
+        return self.session.thread_id
+
+    async def start(self) -> None:
+        await self.session.start()
+
+    async def stop(self) -> None:
+        await self.session.stop()
+
+    async def repl(self) -> None:
+        await self.session.hydrate_initial_state()
+        try:
+            from examples.tui import CodexWorkbenchApp
+        except ModuleNotFoundError as exc:
+            if exc.name in {"PIL", "rich", "textual"}:
+                raise OptionalDependencyError(
+                    "The demo TUI requires optional dependencies. "
+                    "Install with `codex-ipc[tui]`."
+                ) from exc
+            raise
+
+        ui = CodexWorkbenchApp(self)
+        self._ui = ui
+        try:
+            await ui.run_async()
+        finally:
+            self._ui = None
+
+    async def run_prompt(
+        self,
+        prompt: str,
+        *,
+        wait_for_completion: bool,
+        collaboration_mode: dict[str, Any] | None = None,
+    ) -> None:
+        await self.session.run_prompt(
+            prompt,
+            wait_for_completion=wait_for_completion,
+            collaboration_mode=collaboration_mode,
+        )
+
+    def plan_collaboration_mode(self) -> dict[str, Any]:
+        return self.session.plan_collaboration_mode()
+
+    async def set_collaboration_mode(
+        self,
+        collaboration_mode: dict[str, Any] | None,
+    ) -> None:
+        await self.session.set_collaboration_mode(collaboration_mode)
+
+    async def submit_user_input_response(
+        self,
+        request_id: str,
+        response: dict[str, Any],
+    ) -> bool:
+        return await self.session.submit_user_input_response(request_id, response)
+
+    async def steer_prompt(self, prompt: str) -> None:
+        await self.session.steer_prompt(prompt)
+
+    async def enqueue_followup(self, prompt: str) -> dict[str, Any]:
+        return await self.session.enqueue_followup(prompt)
+
+    async def remove_followup(self, message_id: str) -> None:
+        await self.session.remove_followup(message_id)
+
+    def is_turn_in_progress(self) -> bool:
+        return self.session.is_turn_in_progress()
+
+    def queued_followups(self) -> list[dict[str, Any]]:
+        return self.session.queued_followups
+
+    async def list_threads(self, params: dict[str, Any] | None = None) -> object:
+        return await self.session.list_threads(params)
+
+    async def activate_thread(self, thread_id: str) -> None:
+        await self.session.activate_thread(thread_id)
+        await self.session.hydrate_initial_state()
+
+    async def start_new_thread(self, params: dict[str, Any] | None = None) -> object:
+        return await self.session.start_new_thread(params)
+
+    def _notify(self, message: str) -> None:
+        if self._ui is not None:
+            self._ui.set_status(message)
+        else:
+            print(f"[ipc] {message}")
+
+    def _request_render(self) -> None:
+        if self._ui is not None:
+            self._ui.request_render()
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Codex IPC owner/follower demo")
+    parser.add_argument(
+        "--host-id",
+        default=DEFAULT_HOST_ID,
+        help=(
+            "Stable logical host ID shared by windows connected to the same "
+            "backend host. Use different values to simulate separate hosts."
+        ),
+    )
+    parser.add_argument("--thread-id")
+    parser.add_argument("--codex-bin", type=Path)
+    parser.add_argument("--model", default="gpt-5.4")
+    parser.add_argument("--reasoning-effort", default="high")
+    parser.add_argument("--prompt")
+    parser.add_argument("--wait", action="store_true")
+    parser.add_argument("--no-repl", action="store_true")
+    return parser.parse_args()
+
+
+async def main() -> None:
+    args = parse_args()
+    app = DemoApp(
+        host_id=args.host_id,
+        thread_id=args.thread_id,
+        model=args.model,
+        reasoning_effort=args.reasoning_effort,
+        codex_bin=Path("/opt/homebrew/bin/codex"),
+    )
+
+    try:
+        await app.start()
+        if args.prompt:
+            if not app.thread_id:
+                await app.start_new_thread()
+            await app.run_prompt(args.prompt, wait_for_completion=args.wait)
+        if not args.no_repl:
+            await app.repl()
+    finally:
+        await app.stop()
+
+
+def main_cli() -> None:
+    try:
+        asyncio.run(main())
+    except OptionalDependencyError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        raise SystemExit(1) from None
+
+
+if __name__ == "__main__":
+    main_cli()