codex-partner 0.0.1__py3-none-any.whl

codex_partner/__init__.py

@@ -0,0 +1,4 @@
+"""Codex Partner application package."""
+
+APP_NAME = "Codex Partner"
+APP_VERSION = "0.0.1"

codex_partner/__main__.py

@@ -0,0 +1,6 @@
+"""Run Codex Partner with ``python -m codex_partner``."""
+
+from .cli import main
+
+
+main()

codex_partner/app_server.py

@@ -0,0 +1,150 @@
+"""Shared JSON-RPC transport for one Codex app-server process."""
+
+import asyncio
+import json
+from typing import Any, Awaitable, Callable, Optional
+
+
+NotificationHandler = Callable[[str, dict], Awaitable[None]]
+
+
+class AppServerClient:
+    """Own one app-server process and fan out protocol messages to the runtime."""
+
+    def __init__(
+        self,
+        env: dict[str, str],
+        key: str,
+        *,
+        command: Optional[list[str]] = None,
+        local: bool = True,
+        require_codex: Optional[Callable[[], None]] = None,
+        notification_handler: Optional[NotificationHandler] = None,
+        server_request_handler: Optional[NotificationHandler] = None,
+        thread_bindings: Optional[dict[str, tuple[str, str, str]]] = None,
+        turn_waiters: Optional[dict[str, asyncio.Future]] = None,
+        client_name: str = "codex-partner",
+        client_version: str = "0.0.0",
+    ):
+        self.env, self.key = env, key
+        self.command = command or ["codex", "app-server", "--stdio"]
+        self.local = local
+        self.require_codex = require_codex
+        self.notification_handler = notification_handler
+        self.server_request_handler = server_request_handler
+        # Preserve the runtime's empty-but-shared mappings; ``or {}`` would
+        # silently replace them and break app-server exit recovery.
+        self.thread_bindings = thread_bindings if thread_bindings is not None else {}
+        self.turn_waiters = turn_waiters if turn_waiters is not None else {}
+        self.client_name = client_name
+        self.client_version = client_version
+        self.process: Optional[asyncio.subprocess.Process] = None
+        self.reader_task: Optional[asyncio.Task] = None
+        self.write_lock = asyncio.Lock()
+        self.pending: dict[int, asyncio.Future] = {}
+        self.next_id = 1
+
+    async def start(self) -> None:
+        if self.local and self.require_codex:
+            self.require_codex()
+        if self.process and self.process.returncode is None and self.reader_task and not self.reader_task.done():
+            return
+        if self.process and self.process.returncode is None:
+            try:
+                self.process.terminate()
+                await asyncio.wait_for(self.process.wait(), 1)
+            except Exception:
+                pass
+        self.process = await asyncio.create_subprocess_exec(
+            *self.command,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.DEVNULL,
+            env=self.env,
+            limit=64 * 1024 * 1024,
+        )
+        self.reader_task = asyncio.create_task(self._reader())
+        await self.request(
+            "initialize",
+            {
+                "clientInfo": {"name": self.client_name, "version": self.client_version},
+                "capabilities": {"experimentalApi": True},
+            },
+        )
+        await self.notify("initialized")
+
+    async def _reader(self) -> None:
+        assert self.process and self.process.stdout
+        try:
+            async for raw in self.process.stdout:
+                try:
+                    message = json.loads(raw.decode(errors="replace"))
+                except json.JSONDecodeError:
+                    continue
+                request_id = message.get("id")
+                if request_id is not None and request_id in self.pending:
+                    future = self.pending.pop(request_id)
+                    if not future.done():
+                        if "error" in message:
+                            future.set_exception(RuntimeError(json.dumps(message["error"], ensure_ascii=False)))
+                        else:
+                            future.set_result(message.get("result"))
+                elif self.notification_handler:
+                    try:
+                        if "id" in message and "method" in message and "params" in message:
+                            if self.server_request_handler:
+                                await self.server_request_handler(self.key, message)
+                        else:
+                            await self.notification_handler(self.key, message)
+                    except Exception:
+                        # One malformed notification must not strand every browser task.
+                        continue
+        except asyncio.CancelledError:
+            return
+        finally:
+            error = RuntimeError("Codex app-server exited")
+            for future in self.pending.values():
+                if not future.done():
+                    future.set_exception(error)
+            self.pending.clear()
+            for task_id, (key, thread_id, _session_id) in list(self.thread_bindings.items()):
+                if key != self.key:
+                    continue
+                waiter = self.turn_waiters.pop(thread_id, None)
+                if waiter and not waiter.done():
+                    waiter.set_exception(error)
+
+    async def notify(self, method: str, params: Any = None) -> None:
+        message = {"method": method}
+        if params is not None:
+            message["params"] = params
+        async with self.write_lock:
+            if not self.process or not self.process.stdin:
+                raise RuntimeError("Codex app-server is not running")
+            self.process.stdin.write((json.dumps(message, ensure_ascii=False) + "\n").encode())
+            await self.process.stdin.drain()
+
+    async def request(self, method: str, params: Any) -> Any:
+        async with self.write_lock:
+            if not self.process or not self.process.stdin:
+                raise RuntimeError("Codex app-server is not running")
+            request_id = self.next_id
+            self.next_id += 1
+            future = asyncio.get_running_loop().create_future()
+            self.pending[request_id] = future
+            self.process.stdin.write((json.dumps({"id": request_id, "method": method, "params": params}, ensure_ascii=False) + "\n").encode())
+            await self.process.stdin.drain()
+        return await asyncio.wait_for(future, timeout=120)
+
+    async def close(self) -> None:
+        if self.process and self.process.returncode is None:
+            self.process.terminate()
+            try:
+                await asyncio.wait_for(self.process.wait(), 2)
+            except asyncio.TimeoutError:
+                self.process.kill()
+                await self.process.wait()
+        if self.reader_task and not self.reader_task.done():
+            self.reader_task.cancel()
+        if self.reader_task:
+            await asyncio.gather(self.reader_task, return_exceptions=True)

codex_partner/cli.py

@@ -0,0 +1,35 @@
+"""Command-line entry point for an installed Codex Partner package."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+from . import APP_VERSION
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="codex-partner", description="Start the Codex Partner web service.")
+    parser.add_argument("--host", help="Override CODEX_DASHBOARD_HOST.")
+    parser.add_argument("--port", type=int, help="Override CODEX_DASHBOARD_PORT.")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {APP_VERSION}")
+    args = parser.parse_args()
+
+    # An installed CLI reads configuration from the directory it is launched in.
+    load_dotenv(Path.cwd() / ".env", override=False)
+
+    import uvicorn
+
+    from app import DASHBOARD_HOST, DASHBOARD_PORT, app
+
+    host = args.host or DASHBOARD_HOST
+    port = args.port or DASHBOARD_PORT
+    if not 1 <= port <= 65535:
+        parser.error("port must be between 1 and 65535")
+    uvicorn.run(app, host=host, port=port)
+
+
+if __name__ == "__main__":
+    main()

codex_partner/commands.py

@@ -0,0 +1,77 @@
+"""Browser slash-command catalog and input parsing."""
+
+import shlex
+
+from fastapi import HTTPException
+
+
+SLASH_COMMANDS = [
+    {"name": "model", "args": "[model] [effort]", "description": "选择模型和推理强度", "category": "session"},
+    {"name": "fast", "args": "[on|off]", "description": "切换快速服务层", "category": "session"},
+    {"name": "ide", "args": "[path]", "description": "打开当前网页工作区上下文", "category": "context"},
+    {"name": "permissions", "aliases": ["approvals", "yolo"], "args": "[yolo|controlled|profile]", "description": "选择 Codex 权限和 YOLO 模式", "category": "session"},
+    {"name": "keymap", "args": "", "description": "查看浏览器输入快捷键", "category": "browser"},
+    {"name": "vim", "args": "[on|off]", "description": "切换输入框 Vim 模式标记", "category": "browser"},
+    {"name": "experimental", "args": "[feature] [on|off]", "description": "查看或切换实验功能", "category": "codex"},
+    {"name": "approve", "args": "", "description": "重试最近一次自动审查拒绝", "category": "thread"},
+    {"name": "memories", "aliases": ["memory"], "args": "[on|off|status]", "description": "配置当前线程记忆或打开记忆面板", "category": "context"},
+    {"name": "skills", "args": "[reload]", "description": "列出可用 Skills", "category": "context"},
+    {"name": "import", "args": "", "description": "检测可导入的外部 Agent 配置", "category": "codex"},
+    {"name": "hooks", "args": "", "description": "列出当前工作区 Hooks", "category": "codex"},
+    {"name": "review", "args": "[instructions]", "description": "在当前线程发起代码审查", "category": "thread"},
+    {"name": "rename", "args": "<name>", "description": "重命名当前线程", "category": "thread"},
+    {"name": "new", "args": "[first message]", "description": "新建默认 YOLO 会话", "category": "thread"},
+    {"name": "archive", "args": "", "description": "归档当前会话", "category": "thread", "destructive": True},
+    {"name": "unarchive", "args": "", "description": "恢复已归档会话", "category": "thread"},
+    {"name": "delete", "args": "", "description": "将当前会话移到回收站", "category": "thread", "destructive": True},
+    {"name": "resume", "args": "[message]", "description": "继续当前会话", "category": "thread"},
+    {"name": "fork", "args": "[message]", "description": "派生当前会话", "category": "thread"},
+    {"name": "init", "args": "", "description": "在工作区创建 AGENTS.md 指令文件", "category": "context"},
+    {"name": "compact", "args": "", "description": "压缩当前线程上下文", "category": "thread"},
+    {"name": "plan", "args": "[on|off]", "description": "切换 Plan 协作模式", "category": "session"},
+    {"name": "goal", "args": "[objective|clear|status|budget]", "description": "设置、查看和控制长期 Goal", "category": "goal"},
+    {"name": "agent", "args": "", "description": "查看当前线程的 Agent 活动", "category": "thread"},
+    {"name": "side", "args": "[message]", "description": "派生一个侧边会话", "category": "thread"},
+    {"name": "copy", "args": "", "description": "复制最近一条 Codex 回复", "category": "browser"},
+    {"name": "raw", "args": "[on|off]", "description": "切换原始工具事件显示", "category": "browser"},
+    {"name": "diff", "args": "", "description": "显示工作区 Git 变更", "category": "context"},
+    {"name": "mention", "args": "[path]", "description": "把工作区文件加入下一条消息", "category": "context"},
+    {"name": "status", "aliases": ["account"], "args": "", "description": "显示线程配置、Goal 和账号状态", "category": "session"},
+    {"name": "title", "args": "[on|off]", "description": "切换浏览器标题中的会话名", "category": "browser"},
+    {"name": "statusline", "args": "", "description": "打开会话状态检查器", "category": "browser"},
+    {"name": "theme", "args": "[dark|light]", "description": "切换浏览器主题", "category": "browser"},
+    {"name": "mcp", "args": "[verbose]", "description": "列出已配置 MCP 工具", "category": "codex"},
+    {"name": "plugins", "aliases": ["apps"], "args": "", "description": "列出 Codex 插件和 Apps", "category": "codex"},
+    {"name": "logout", "args": "", "description": "退出 Codex 账号", "category": "account", "destructive": True},
+    {"name": "exit", "aliases": ["quit"], "args": "", "description": "断开当前网页实时连接", "category": "browser"},
+    {"name": "feedback", "args": "[message]", "description": "显示反馈入口信息", "category": "codex"},
+    {"name": "ps", "args": "", "description": "列出当前线程后台终端", "category": "thread"},
+    {"name": "stop", "args": "", "description": "停止当前 turn 或后台终端", "category": "thread", "destructive": True},
+    {"name": "clear", "args": "", "description": "清空当前视图并新建默认 YOLO 会话", "category": "thread", "destructive": True},
+    {"name": "personality", "args": "[none|friendly|pragmatic]", "description": "选择 Codex 沟通风格", "category": "session"},
+    {"name": "subagents", "args": "", "description": "查看当前线程的子 Agent 活动", "category": "thread"},
+    {"name": "help", "args": "[command]", "description": "显示网页支持的斜杠命令", "category": "browser"},
+]
+
+SLASH_COMMAND_BY_NAME = {command["name"]: command for command in SLASH_COMMANDS}
+SLASH_ALIASES = {
+    alias: command["name"]
+    for command in SLASH_COMMANDS
+    for alias in command.get("aliases", [])
+}
+
+
+def parse_slash_command(raw: str) -> tuple[str, str, list[str]]:
+    """Normalize aliases and parse shell-style command arguments."""
+    text = raw.strip()
+    if not text.startswith("/"):
+        raise HTTPException(400, "Slash commands must start with /")
+    head, _, arg_text = text[1:].partition(" ")
+    name = SLASH_ALIASES.get(head.strip().lower(), head.strip().lower())
+    if name not in SLASH_COMMAND_BY_NAME:
+        raise HTTPException(400, f"Unknown slash command: /{head}")
+    try:
+        args = shlex.split(arg_text)
+    except ValueError as exc:
+        raise HTTPException(400, f"Invalid command arguments: {exc}") from exc
+    return name, arg_text.strip(), args

codex_partner/database.py

@@ -0,0 +1,206 @@
+"""SQLite persistence and forward-only schema migrations for Codex Partner."""
+
+import sqlite3
+import threading
+from pathlib import Path
+from typing import Callable, Optional
+
+
+class Database:
+    """Small thread-safe SQLite gateway used by async route handlers."""
+
+    def __init__(self, path: Path, clock: Callable[[], str]):
+        self.path = str(path)
+        self.clock = clock
+        self.lock = threading.RLock()
+        self.initialize()
+        try:
+            Path(self.path).chmod(0o600)
+        except OSError:
+            pass
+
+    def connect(self) -> sqlite3.Connection:
+        connection = sqlite3.connect(self.path, check_same_thread=False)
+        connection.row_factory = sqlite3.Row
+        connection.execute("PRAGMA journal_mode=WAL")
+        connection.execute("PRAGMA foreign_keys=ON")
+        return connection
+
+    def initialize(self) -> None:
+        with self.lock, self.connect() as connection:
+            connection.executescript(
+                """
+                CREATE TABLE IF NOT EXISTS tasks (
+                  id TEXT PRIMARY KEY, name TEXT NOT NULL, prompt TEXT NOT NULL,
+                  goal TEXT DEFAULT '', workspace TEXT NOT NULL,
+                  status TEXT NOT NULL DEFAULT 'queued', yolo INTEGER NOT NULL DEFAULT 1,
+                  max_retries INTEGER NOT NULL DEFAULT 3, retry_count INTEGER NOT NULL DEFAULT 0,
+                  retry_forever INTEGER NOT NULL DEFAULT 0,
+                  retry_explicit INTEGER NOT NULL DEFAULT 0,
+                  provider_id TEXT, model TEXT DEFAULT '', context TEXT DEFAULT '',
+                  created_at TEXT NOT NULL, updated_at TEXT NOT NULL,
+                  last_error TEXT DEFAULT '', active_session_id TEXT, codex_session_id TEXT DEFAULT '',
+                  goal_status TEXT DEFAULT 'active', goal_tokens_used INTEGER DEFAULT 0,
+                  native INTEGER NOT NULL DEFAULT 0,
+                  archived INTEGER NOT NULL DEFAULT 0,
+                  trashed INTEGER NOT NULL DEFAULT 0,
+                  trashed_at TEXT,
+                  memory_mode TEXT DEFAULT 'enabled',
+                  execution_source TEXT DEFAULT '',
+                  execution_turn_id TEXT DEFAULT ''
+                );
+                CREATE TABLE IF NOT EXISTS sessions (
+                  id TEXT PRIMARY KEY, task_id TEXT NOT NULL, status TEXT NOT NULL,
+                  attempt INTEGER NOT NULL, provider_id TEXT, command TEXT NOT NULL,
+                  started_at TEXT NOT NULL, finished_at TEXT, exit_code INTEGER,
+                  summary TEXT DEFAULT '', codex_session_id TEXT DEFAULT '',
+                  FOREIGN KEY(task_id) REFERENCES tasks(id) ON DELETE CASCADE
+                );
+                CREATE TABLE IF NOT EXISTS events (
+                  id INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT NOT NULL,
+                  task_id TEXT, ts TEXT NOT NULL, stream TEXT NOT NULL, payload TEXT NOT NULL,
+                  FOREIGN KEY(session_id) REFERENCES sessions(id) ON DELETE CASCADE
+                );
+                CREATE TABLE IF NOT EXISTS skills (
+                  id TEXT PRIMARY KEY, name TEXT NOT NULL UNIQUE, description TEXT DEFAULT '',
+                  content TEXT NOT NULL, enabled INTEGER NOT NULL DEFAULT 1,
+                  created_at TEXT NOT NULL, updated_at TEXT NOT NULL
+                );
+                CREATE TABLE IF NOT EXISTS providers (
+                  id TEXT PRIMARY KEY, name TEXT NOT NULL, kind TEXT NOT NULL DEFAULT 'codex',
+                  model TEXT DEFAULT '', profile TEXT DEFAULT '', api_key_env TEXT DEFAULT '',
+                  api_key TEXT DEFAULT '', base_url TEXT DEFAULT '', enabled INTEGER NOT NULL DEFAULT 1,
+                  priority INTEGER NOT NULL DEFAULT 100, created_at TEXT NOT NULL, updated_at TEXT NOT NULL,
+                  model_provider TEXT DEFAULT '', native INTEGER NOT NULL DEFAULT 0,
+                  health_status TEXT DEFAULT 'unchecked', health_detail TEXT DEFAULT '',
+                  health_checked_at TEXT, health_latency_ms INTEGER,
+                  success_count INTEGER NOT NULL DEFAULT 0, failure_count INTEGER NOT NULL DEFAULT 0,
+                  last_success_at TEXT, last_failure_at TEXT
+                );
+                CREATE TABLE IF NOT EXISTS task_messages (
+                  id TEXT PRIMARY KEY, task_id TEXT NOT NULL, body TEXT NOT NULL,
+                  status TEXT NOT NULL DEFAULT 'queued', created_at TEXT NOT NULL,
+                  started_at TEXT, finished_at TEXT, session_id TEXT, error TEXT DEFAULT '',
+                  FOREIGN KEY(task_id) REFERENCES tasks(id) ON DELETE CASCADE
+                );
+                CREATE TABLE IF NOT EXISTS ssh_saved_hosts (
+                  alias TEXT PRIMARY KEY, created_at TEXT NOT NULL
+                );
+                CREATE INDEX IF NOT EXISTS idx_sessions_task_attempt ON sessions(task_id, attempt DESC);
+                CREATE INDEX IF NOT EXISTS idx_sessions_task_id ON sessions(task_id, id);
+                CREATE INDEX IF NOT EXISTS idx_events_session_id ON events(session_id, id);
+                CREATE INDEX IF NOT EXISTS idx_events_session_ts_id ON events(session_id, ts DESC, id DESC);
+                CREATE INDEX IF NOT EXISTS idx_events_stream_id_session ON events(stream, id DESC, session_id);
+                CREATE INDEX IF NOT EXISTS idx_task_messages_task_status ON task_messages(task_id, status, created_at);
+                """
+            )
+            self._migrate(connection)
+            self._recover_interrupted_work(connection)
+            connection.commit()
+
+    def _migrate(self, connection: sqlite3.Connection) -> None:
+        session_columns = {row[1] for row in connection.execute("PRAGMA table_info(sessions)")}
+        if "codex_session_id" not in session_columns:
+            connection.execute("ALTER TABLE sessions ADD COLUMN codex_session_id TEXT DEFAULT ''")
+
+        event_columns = {row[1] for row in connection.execute("PRAGMA table_info(events)")}
+        if "task_id" not in event_columns:
+            connection.execute("ALTER TABLE events ADD COLUMN task_id TEXT")
+        connection.execute(
+            "UPDATE events SET task_id=(SELECT task_id FROM sessions WHERE sessions.id=events.session_id) "
+            "WHERE task_id IS NULL"
+        )
+        connection.execute("CREATE INDEX IF NOT EXISTS idx_events_task_ts_id ON events(task_id, ts DESC, id DESC)")
+        connection.execute("CREATE INDEX IF NOT EXISTS idx_events_task_stream_id ON events(task_id, stream, id DESC)")
+        connection.execute(
+            "CREATE TRIGGER IF NOT EXISTS trg_events_fill_task_id AFTER INSERT ON events "
+            "WHEN NEW.task_id IS NULL BEGIN "
+            "UPDATE events SET task_id=(SELECT task_id FROM sessions WHERE id=NEW.session_id) WHERE id=NEW.id; END"
+        )
+
+        task_columns = {row[1] for row in connection.execute("PRAGMA table_info(tasks)")}
+        task_migrations = {
+            "codex_session_id": "TEXT DEFAULT ''",
+            "retry_forever": "INTEGER NOT NULL DEFAULT 0",
+            "retry_explicit": "INTEGER NOT NULL DEFAULT 0",
+            "goal_status": "TEXT DEFAULT 'active'",
+            "goal_tokens_used": "INTEGER DEFAULT 0",
+            "native": "INTEGER NOT NULL DEFAULT 0",
+            "archived": "INTEGER NOT NULL DEFAULT 0",
+            "trashed": "INTEGER NOT NULL DEFAULT 0",
+            "trashed_at": "TEXT",
+            "memory_mode": "TEXT DEFAULT 'enabled'",
+            "reasoning_effort": "TEXT DEFAULT ''",
+            "service_tier": "TEXT DEFAULT ''",
+            "personality": "TEXT DEFAULT ''",
+            "collaboration_mode": "TEXT DEFAULT 'default'",
+            "permission_profile": "TEXT DEFAULT ''",
+            "execution_source": "TEXT DEFAULT ''",
+            "execution_turn_id": "TEXT DEFAULT ''",
+            "ssh_host": "TEXT DEFAULT ''",
+        }
+        for column, definition in task_migrations.items():
+            if column not in task_columns:
+                connection.execute(f"ALTER TABLE tasks ADD COLUMN {column} {definition}")
+
+        provider_columns = {row[1] for row in connection.execute("PRAGMA table_info(providers)")}
+        provider_migrations = {
+            "model_provider": "TEXT DEFAULT ''",
+            "native": "INTEGER NOT NULL DEFAULT 0",
+            "health_status": "TEXT DEFAULT 'unchecked'",
+            "health_detail": "TEXT DEFAULT ''",
+            "health_checked_at": "TEXT",
+            "health_latency_ms": "INTEGER",
+            "success_count": "INTEGER NOT NULL DEFAULT 0",
+            "failure_count": "INTEGER NOT NULL DEFAULT 0",
+            "last_success_at": "TEXT",
+            "last_failure_at": "TEXT",
+            "api_key": "TEXT DEFAULT ''",
+        }
+        for column, definition in provider_migrations.items():
+            if column not in provider_columns:
+                connection.execute(f"ALTER TABLE providers ADD COLUMN {column} {definition}")
+
+    def _recover_interrupted_work(self, connection: sqlite3.Connection) -> None:
+        """Recover only dashboard-owned turns; terminal turns are rediscovered separately."""
+        stamp = self.clock()
+        connection.execute(
+            "UPDATE tasks SET execution_source='dashboard' "
+            "WHERE status IN ('running','retrying') AND active_session_id IN "
+            "(SELECT id FROM sessions WHERE status IN ('running','retrying')) "
+            "AND COALESCE(execution_source,'')!='terminal'"
+        )
+        connection.execute(
+            "UPDATE sessions SET status='interrupted', finished_at=?, "
+            "summary='Dashboard restarted while session was running' WHERE status='running'",
+            (stamp,),
+        )
+        connection.execute(
+            "UPDATE task_messages SET status='queued', started_at=NULL, session_id=NULL, "
+            "error='Dashboard restarted before delivery' WHERE status='running'"
+        )
+        connection.execute(
+            "UPDATE tasks SET status='queued', last_error='Dashboard restarted; task queued for resume', updated_at=? "
+            "WHERE status IN ('running','retrying') AND execution_source='dashboard'",
+            (stamp,),
+        )
+        connection.execute(
+            "UPDATE tasks SET status=CASE WHEN archived=1 THEN 'archived' ELSE 'stopped' END, "
+            "execution_source='',execution_turn_id='',last_error='',updated_at=? "
+            "WHERE status IN ('running','retrying') AND COALESCE(execution_source,'')!='dashboard'",
+            (stamp,),
+        )
+
+    def one(self, sql: str, args: tuple = ()) -> Optional[dict]:
+        with self.lock, self.connect() as connection:
+            row = connection.execute(sql, args).fetchone()
+            return dict(row) if row else None
+
+    def all(self, sql: str, args: tuple = ()) -> list[dict]:
+        with self.lock, self.connect() as connection:
+            return [dict(row) for row in connection.execute(sql, args).fetchall()]
+
+    def execute(self, sql: str, args: tuple = ()) -> None:
+        with self.lock, self.connect() as connection:
+            connection.execute(sql, args)
+            connection.commit()

codex_partner/discovery.py

@@ -0,0 +1,136 @@
+"""Codex and npm executable discovery without application state."""
+
+import os
+import re
+import shlex
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Callable, Optional
+
+
+def executable_works(candidate: str) -> bool:
+    path = Path(candidate).expanduser()
+    if not path.is_file() or not os.access(path, os.X_OK):
+        return False
+    try:
+        result = subprocess.run(
+            [str(path), "--version"],
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            timeout=5,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return False
+    return result.returncode == 0
+
+
+def vscode_candidates(home: Optional[Path] = None) -> list[str]:
+    home = (home or Path.home()).expanduser()
+    roots = (
+        home / ".vscode/extensions",
+        home / ".vscode-server/extensions",
+        home / ".vscode-insiders/extensions",
+        home / ".vscode-server-insiders/extensions",
+    )
+    candidates: list[tuple[tuple[int, ...], float, str]] = []
+    for root in roots:
+        if not root.is_dir():
+            continue
+        for extension in root.glob("openai.chatgpt-*"):
+            version = tuple(int(value) for value in re.findall(r"\d+", extension.name))
+            try:
+                modified = extension.stat().st_mtime
+            except OSError:
+                modified = 0.0
+            for pattern in ("bin/*/codex", "bin/*/codex.exe"):
+                for binary in extension.glob(pattern):
+                    candidates.append((version, modified, str(binary.resolve())))
+    candidates.sort(reverse=True)
+    return [candidate for _version, _modified, candidate in candidates]
+
+
+def official_candidates(codex_home: Path, home: Optional[Path] = None) -> list[str]:
+    home = (home or Path.home()).expanduser()
+    candidates = [
+        codex_home / "bin/codex",
+        home / ".local/bin/codex",
+        home / ".npm-global/bin/codex",
+        home / ".npm/bin/codex",
+        Path("/usr/local/bin/codex"),
+        Path("/opt/homebrew/bin/codex"),
+        Path("/home/linuxbrew/.linuxbrew/bin/codex"),
+        Path("/usr/bin/codex"),
+    ]
+    candidates[4:4] = sorted((home / ".nvm/versions/node").glob("*/bin/codex"), reverse=True)
+    if os.name == "nt":
+        local = Path(os.getenv("LOCALAPPDATA", str(home / "AppData/Local")))
+        candidates[:0] = [local / "CodexPartner/npm/codex.cmd", local / "CodexDashboard/npm/codex.cmd", local / "npm/codex.cmd"]
+    return [str(candidate.expanduser().resolve()) for candidate in candidates]
+
+
+def find_codex(
+    requested: str,
+    vscode: list[str],
+    official: list[str],
+    usable: Callable[[str], bool],
+) -> dict:
+    """Apply the documented PATH, VS Code, then official-path precedence."""
+    checked: list[str] = []
+    direct = shutil.which(requested)
+    if direct:
+        direct = str(Path(direct).expanduser().resolve())
+        checked.append(direct)
+        if usable(direct):
+            return {"available": True, "path": direct, "source": "path", "checked": checked}
+    for source, candidates in (("vscode", vscode), ("official", official)):
+        for candidate in candidates:
+            if candidate in checked:
+                continue
+            checked.append(candidate)
+            if usable(candidate):
+                return {"available": True, "path": candidate, "source": source, "checked": checked}
+    return {"available": False, "path": "", "source": "missing", "checked": checked}
+
+
+def find_npm() -> str:
+    names = ("npm.cmd", "npm") if os.name == "nt" else ("npm",)
+    for name in names:
+        if found := shutil.which(name):
+            return str(Path(found).expanduser().resolve())
+    home = Path.home()
+    candidates = [
+        Path("/usr/local/nodejs/bin/npm"),
+        Path("/usr/local/bin/npm"),
+        Path("/opt/homebrew/bin/npm"),
+        Path("/home/linuxbrew/.linuxbrew/bin/npm"),
+        home / ".local/bin/npm",
+    ]
+    candidates += sorted((home / ".nvm/versions/node").glob("*/bin/npm"), reverse=True)
+    return next((str(path.resolve()) for path in candidates if path.is_file() and os.access(path, os.X_OK)), "")
+
+
+def install_plan(system: str, npm: str, package: str) -> dict:
+    supported = system in {"Linux", "Darwin", "Windows"}
+    if system == "Windows":
+        prefix = Path(os.getenv("LOCALAPPDATA", str(Path.home() / "AppData/Local"))) / "CodexPartner/npm"
+    else:
+        prefix = Path.home() / ".local"
+    command = [npm, "install", "--global", "--prefix", str(prefix), package] if npm else []
+    if not supported:
+        reason = f"暂不支持在 {system} 上自动安装 Codex"
+    elif not npm:
+        reason = "未找到 npm；请先安装 Node.js LTS（Windows 建议在 WSL 中运行 Codex Partner），然后重试"
+    else:
+        reason = ""
+    display = subprocess.list2cmdline(command) if os.name == "nt" else shlex.join(command)
+    return {
+        "supported": bool(supported and npm),
+        "os": system,
+        "package": package,
+        "prefix": str(prefix),
+        "command": display,
+        "reason": reason,
+    }