codex-autorunner 0.1.2__py3-none-any.whl → 1.1.0__py3-none-any.whl

codex_autorunner/workspace/paths.py

@@ -0,0 +1,335 @@
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path, PurePosixPath
+from typing import Literal, cast
+
+from ..core import drafts as draft_utils
+from ..core.logging_utils import log_event
+
+WorkspaceDocKind = Literal["active_context", "decisions", "spec"]
+WORKSPACE_DOC_KINDS: tuple[WorkspaceDocKind, ...] = (
+    "active_context",
+    "decisions",
+    "spec",
+)
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class WorkspaceFile:
+    name: str
+    path: str  # path relative to the workspace directory (POSIX)
+    is_pinned: bool = False
+    modified_at: str | None = None
+
+
+def _normalize_kind(kind: str) -> WorkspaceDocKind:
+    key = (kind or "").strip().lower()
+    if key not in WORKSPACE_DOC_KINDS:
+        raise ValueError("invalid workspace doc kind")
+    return cast(WorkspaceDocKind, key)
+
+
+def workspace_dir(repo_root: Path) -> Path:
+    return repo_root / ".codex-autorunner" / "workspace"
+
+
+PINNED_DOC_FILENAMES = {f"{kind}.md" for kind in WORKSPACE_DOC_KINDS}
+
+
+@dataclass
+class WorkspaceNode:
+    name: str
+    path: str  # relative to workspace dir
+    type: Literal["file", "folder"]
+    is_pinned: bool = False
+    modified_at: str | None = None
+    size: int | None = None  # files only
+    children: list["WorkspaceNode"] | None = None  # folders only
+
+
+def normalize_workspace_rel_path(repo_root: Path, rel_path: str) -> tuple[Path, str]:
+    """Normalize a user-supplied workspace path and ensure it stays in-tree.
+
+    We accept POSIX-style relative paths only, then resolve the full path and
+    verify the result is still under the workspace directory. This guards
+    against ".." traversal and symlink escapes that CodeQL flagged.
+    """
+
+    base = workspace_dir(repo_root).resolve(strict=False)
+    base_real = base.resolve(strict=False)
+    cleaned = (rel_path or "").strip()
+    if not cleaned:
+        raise ValueError("invalid workspace file path")
+
+    relative = PurePosixPath(cleaned)
+    if relative.is_absolute() or ".." in relative.parts:
+        raise ValueError("invalid workspace file path")
+
+    candidate = (base / relative).resolve(strict=False)
+    try:
+        rel_posix = candidate.relative_to(base_real).as_posix()
+    except ValueError:
+        raise ValueError("invalid workspace file path") from None
+
+    return candidate, rel_posix
+
+
+def sanitize_workspace_filename(filename: str) -> str:
+    """Return a safe filename for workspace uploads.
+
+    We strip any directory components, collapse whitespace, and guard against
+    empty names. Caller is responsible for applying any per-workspace policy
+    (e.g., overwrite vs. reject).
+    """
+
+    cleaned = (filename or "").strip()
+    # Drop any path fragments that may be embedded in the upload
+    base = PurePosixPath(cleaned).name
+    # Remove remaining separators/backslashes that PurePosixPath.name could keep
+    base = base.replace("/", "").replace("\\", "")
+    if base in {".", ".."}:
+        base = ""
+    # Collapse whitespace to single spaces to keep names readable
+    base = " ".join(base.split())
+    if not base:
+        return "upload"
+    return base
+
+
+def workspace_doc_path(repo_root: Path, kind: str) -> Path:
+    key = _normalize_kind(kind)
+    return workspace_dir(repo_root) / f"{key}.md"
+
+
+def read_workspace_file(
+    repo_root: Path, rel_path: str
+) -> str:  # codeql[py/path-injection]
+    path, _ = normalize_workspace_rel_path(repo_root, rel_path)
+    if (
+        path.is_dir()
+    ):  # codeql[py/path-injection] validated by normalize_workspace_rel_path
+        raise ValueError("path points to a directory")
+    if (
+        not path.exists()
+    ):  # codeql[py/path-injection] validated by normalize_workspace_rel_path
+        return ""
+    return path.read_text(
+        encoding="utf-8"
+    )  # codeql[py/path-injection] validated by normalize_workspace_rel_path
+
+
+def write_workspace_file(  # codeql[py/path-injection]
+    repo_root: Path, rel_path: str, content: str
+) -> str:
+    path, rel_posix = normalize_workspace_rel_path(repo_root, rel_path)
+    if (
+        path.exists() and path.is_dir()
+    ):  # codeql[py/path-injection] validated by normalize_workspace_rel_path
+        raise ValueError("path points to a directory")
+    path.parent.mkdir(
+        parents=True, exist_ok=True
+    )  # codeql[py/path-injection] validated by normalize_workspace_rel_path
+    path.write_text(
+        content or "", encoding="utf-8"
+    )  # codeql[py/path-injection] validated by normalize_workspace_rel_path
+    rel = path.relative_to(repo_root).as_posix()
+    state_key = f"workspace_{rel_posix.replace('/', '_')}"
+    try:
+        draft_utils.invalidate_drafts_for_path(repo_root, rel)
+        draft_utils.remove_draft(repo_root, state_key)
+    except Exception as exc:
+        log_event(
+            logger,
+            logging.WARNING,
+            "workspace.draft_invalidation_failed",
+            repo_root=str(repo_root),
+            rel_path=rel_posix,
+            state_key=state_key,
+            exc=exc,
+        )
+        logger.debug(
+            "workspace draft invalidation failed for %s (repo_root=%s)",
+            rel_posix,
+            repo_root,
+            exc_info=True,
+        )
+    return path.read_text(encoding="utf-8")
+
+
+def read_workspace_doc(repo_root: Path, kind: str) -> str:
+    path = workspace_doc_path(repo_root, kind)
+    if not path.exists():
+        return ""
+    return path.read_text(encoding="utf-8")
+
+
+def write_workspace_doc(  # codeql[py/path-injection]
+    repo_root: Path, kind: str, content: str
+) -> str:
+    path = workspace_doc_path(repo_root, kind)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        content or "", encoding="utf-8"
+    )  # codeql[py/path-injection] workspace_doc_path is deterministic
+    rel = path.relative_to(repo_root).as_posix()
+    state_key = f"workspace_{rel.replace('/', '_')}"
+    try:
+        draft_utils.invalidate_drafts_for_path(repo_root, rel)
+        draft_utils.remove_draft(repo_root, state_key)
+    except Exception as exc:
+        log_event(
+            logger,
+            logging.WARNING,
+            "workspace.draft_invalidation_failed",
+            repo_root=str(repo_root),
+            rel_path=rel,
+            state_key=state_key,
+            kind=kind,
+            exc=exc,
+        )
+        logger.debug(
+            "workspace draft invalidation failed for %s (repo_root=%s kind=%s)",
+            rel,
+            repo_root,
+            kind,
+            exc_info=True,
+        )
+    return path.read_text(encoding="utf-8")
+
+
+def _format_mtime(path: Path) -> str | None:
+    if not path.exists():
+        return None
+    ts = datetime.fromtimestamp(path.stat().st_mtime, tz=timezone.utc)
+    return ts.isoformat()
+
+
+def list_workspace_files(
+    repo_root: Path,
+) -> list[WorkspaceFile]:  # codeql[py/path-injection]
+    base = workspace_dir(repo_root)
+    base.mkdir(parents=True, exist_ok=True)
+
+    pinned: list[WorkspaceFile] = []
+    for kind in WORKSPACE_DOC_KINDS:
+        path = workspace_doc_path(repo_root, kind)
+        rel = path.relative_to(base).as_posix()
+        pinned.append(
+            WorkspaceFile(
+                name=path.name,
+                path=rel,
+                is_pinned=True,
+                modified_at=_format_mtime(path),
+            )
+        )
+
+    others: list[WorkspaceFile] = []
+    if base.exists():
+        for file_path in base.rglob("*"):
+            if file_path.is_dir():
+                continue
+            try:
+                rel = file_path.relative_to(base).as_posix()
+            except ValueError:
+                continue
+            if any(rel == pinned_file.path for pinned_file in pinned):
+                continue
+            others.append(
+                WorkspaceFile(
+                    name=file_path.name,
+                    path=rel,
+                    is_pinned=False,
+                    modified_at=_format_mtime(file_path),
+                )
+            )
+
+    others.sort(key=lambda f: f.path)
+    return [*pinned, *others]
+
+
+def _sort_workspace_children(path: Path) -> tuple[int, str]:
+    # Folders first, then files, both alphabetized (case-insensitive)
+    return (0 if path.is_dir() else 1, path.name.lower())
+
+
+def _is_within_workspace(base_real: Path, candidate: Path) -> bool:
+    try:
+        candidate.resolve().relative_to(base_real)
+        return True
+    except Exception:
+        return False
+
+
+def _file_node(base: Path, path: Path, is_pinned: bool = False) -> WorkspaceNode:
+    rel = path.relative_to(base).as_posix()
+    size: int | None = None
+    if path.exists() and path.is_file():
+        try:
+            size = path.stat().st_size
+        except OSError:
+            size = None
+    return WorkspaceNode(
+        name=path.name,
+        path=rel,
+        type="file",
+        is_pinned=is_pinned,
+        modified_at=_format_mtime(path),
+        size=size,
+    )
+
+
+def _build_workspace_tree(base: Path, path: Path) -> WorkspaceNode:
+    is_symlink = path.is_symlink()
+    is_folder = path.is_dir() and not is_symlink
+    is_pinned = path.name in PINNED_DOC_FILENAMES and path.parent == base
+
+    if not is_folder:
+        return _file_node(base, path, is_pinned=is_pinned)
+
+    children: list[WorkspaceNode] = []
+    for child in sorted(path.iterdir(), key=_sort_workspace_children):
+        # Avoid duplicating pinned docs surfaced at the root list
+        if child.parent == base and child.name in PINNED_DOC_FILENAMES:
+            continue
+        # Skip symlink escapes that resolve outside the workspace
+        if child.is_symlink() and not _is_within_workspace(base.resolve(), child):
+            continue
+        children.append(_build_workspace_tree(base, child))
+
+    return WorkspaceNode(
+        name=path.name,
+        path=path.relative_to(base).as_posix(),
+        type="folder",
+        is_pinned=False,
+        modified_at=_format_mtime(path),
+        children=children,
+    )
+
+
+def list_workspace_tree(repo_root: Path) -> list[WorkspaceNode]:
+    """Return hierarchical workspace structure (folders + files)."""
+
+    base = workspace_dir(repo_root)
+    base.mkdir(parents=True, exist_ok=True)
+    base_real = base.resolve()
+
+    nodes: list[WorkspaceNode] = []
+
+    # Pinned docs first (even if missing)
+    for name in sorted(PINNED_DOC_FILENAMES):
+        pinned_path = base / name
+        nodes.append(_file_node(base, pinned_path, is_pinned=True))
+
+    for child in sorted(base.iterdir(), key=_sort_workspace_children):
+        if child.parent == base and child.name in PINNED_DOC_FILENAMES:
+            continue
+        if child.is_symlink() and not _is_within_workspace(base_real, child):
+            continue
+        nodes.append(_build_workspace_tree(base, child))
+
+    return nodes

codex_autorunner-1.1.0.dist-info/METADATA

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: codex-autorunner
+Version: 1.1.0
+Summary: Codex autorunner CLI per DESIGN-V1
+Author: Codex
+License: MIT License
+        
+        Copyright (c) 2025 David Zhang
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/Git-on-my-level/codex-autorunner
+Project-URL: Repository, https://github.com/Git-on-my-level/codex-autorunner
+Project-URL: Issues, https://github.com/Git-on-my-level/codex-autorunner/issues
+Keywords: codex,automation,agent,cli,fastapi
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.9
+Requires-Dist: click<8.2
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: fastapi>=0.111
+Requires-Dist: uvicorn[standard]>=0.30
+Requires-Dist: ptyprocess>=0.7
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: tenacity>=8.0
+Provides-Extra: dev
+Requires-Dist: black==25.11.0; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-timeout>=2.0; extra == "dev"
+Requires-Dist: ruff>=0.5.0; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+Provides-Extra: telegram
+Requires-Dist: httpx>=0.27; extra == "telegram"
+Provides-Extra: voice
+Requires-Dist: httpx>=0.27; extra == "voice"
+Requires-Dist: python-multipart>=0.0.9; extra == "voice"
+Provides-Extra: github
+Dynamic: license-file
+
+# CAR (codex-autorunner)
+[![PyPI](https://img.shields.io/pypi/v/codex-autorunner.svg)](https://pypi.org/project/codex-autorunner/)
+
+CAR provides a set of low-opinion agent coordination tools for you to run long complex implementations using the agents you already love.
+
+What this looks like in practice:
+- You write a plan, or generate a plan by chatting with your favorite AI
+- You convert the plan (or ask an AI to convert it for you) into CAR compatible tickets (markdown with some frontmatter)
+- Go off and do something else, no need to babysit the agents, they will notify you if they need your input
+
+![CAR Web Hub Screenshot](docs/screenshots/hub.png)
+
+## How it works
+CAR is very simple. At it's core, CAR is a state machine which checks to see if there are any incomplete tickets. If yes, pick the next one and run it against an agent. Tickets can be pre-populated by the user, but agents can also write tickets. _Tickets are the control plane for CAR_.
+
+When each agent wakes up, it gets knowledge about CAR and how to operate within CAR, a pre-defined set of context (workspace files), the current ticket, and optionally the final output of the previous agent. This simple loop ensures that agents know enough to use CAR while also focusing them on the task at hand.
+
+## Philosophy
+The philosophy behind CAR is to let the agents do what they do best, and get out of their way. CAR is _very bitter-lesson-pilled_. As models and agents get more powerful, CAR should serve as a form of leverage, and avoid constraining models and their harnesses. This is why we treat the filesystem as the first class data plane and utilize tools and languages the models are already very familiar with (git, python).
+
+CAR treats tickets as the control plane and models as the execution layer. This means that we rely on agents to follow the instructions written in the tickets. If you use a sufficiently weak model, CAR may not work well for you. CAR is an amplifier for agent capabilities. Agents who like to scope creep (create too many new tickets) or reward hack (mark a ticket as done despite it being incomplete) are not a good fit for CAR.
+
+## Interaction patterns
+CAR's core is a set of python functions surfaced as a CLI, operating on a file system. There are current 2 UIs built on top of this core.
+
+### Web UI
+The web UI is the main control plane for CAR. From here you can set up new repositories or clone existing ones, chat with agents using their TUI, and run the ticket autorunner. There are many quality-of-life features like Whisper integration, editing documents by chatting with AI (useful for mobile), viewing usage analytics, and much more. The Web UI is the most full featured user-facing interface and a good starting point for trying out CAR.
+
+I recommend serving the web UI over Tailscale. There is an auth token option but the system is not very battle tested.
+
+### Telegram
+Telegram is the "on-the-go" and notification hub for CAR. From here you can kick off and monitor existing tickets, set up new tickets, and chat with agents. Your primary UX here is asking the agent to do things for you rather than you doing it yourself like you would on the web UI. This is great for on-the-go work, but it doesn't have full feature parity with the web UI.
+
+## Quickstart
+
+The fastest way to get started is to pass [this setup guide](docs/AGENT_SETUP_GUIDE.md) to your favorite AI agent. The agent will walk you through installation and configuration interactively based on your environment.
+
+**TL;DR for the impatient:**
+
+# Install
+```
+pipx install codex-autorunner
+```
+# Initialize in your repo
+```
+cd /path/to/your/repo
+car init
+```
+# Verify setup
+```
+car doctor
+```
+# Create a ticket and run
+```
+car run
+```
+
+## Supported models
+CAR currently supports:
+- Codex
+- Opencode
+
+CAR is built to easily integrate any reasonable agent built for Agent Client Protocol (ACP). If you would like to see your agent supported, please reach out or open a PR.
+
+## Examples
+Build out complex features and products by providing a series of tickets assigned to various agents.
+![CAR Tickets in Progress Screenshot](docs/screenshots/tickets-in-progress.png)
+
+Tickets are just markdown files that both you and the agent can edit.
+![CAR Ticket Markdown Screenshot](docs/screenshots/ticket-markdown.png)
+
+You don't have to babysit the agents, they inbox you or ping you on Telegram.
+![CAR Inbox Screenshot](docs/screenshots/inbox.png)
+
+You can collaborate with the agents in a shared workspace, independent of the codebase. Drop context there, extract artifacts, it's like a shared scratchpad.
+![CAR Workspace Screenshot](docs/screenshots/workspace.png)
+
+All core workspace documents are also just markdown files, so you and the agent can easily edit them.
+![CAR Workspace New MD Screenshot](docs/screenshots/workspace-new-md.png)
+
+If you need to do something more custom or granular, you can use your favorite agent TUIs in the built-in terminal.
+![CAR Terminal Codex Screenshot](docs/screenshots/terminal-codex.png)
+![CAR Terminal Opencode Screenshot](docs/screenshots/terminal-opencode.png)
+
+On the go? The web UI is mobile responsive, or if you prefer you can type or voice chat with your agents on Telegram.
+![CAR Telegram Media Voice Screenshot](docs/screenshots/telegram-media-voice.PNG)
+![CAR Telegram Media Image Screenshot](docs/screenshots/telegram-media-image.PNG)
+
+## Star history
+[![Star History Chart](https://api.star-history.com/svg?repos=Git-on-my-level/codex-autorunner&type=Date)](https://star-history.com/#Git-on-my-level/codex-autorunner&Date)