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

codex_autorunner/agents/opencode/client.py

@@ -21,6 +21,7 @@ class OpenCodeApiProfile:
 
     supports_prompt_async: bool = True
     supports_global_endpoints: bool = True
+    max_text_chars: Optional[int] = None
     spec_fetched: bool = False
 
 
@@ -83,6 +84,7 @@ class OpenCodeClient:
         *,
         auth: Optional[tuple[str, str]] = None,
         timeout: Optional[float] = None,
+        max_text_chars: Optional[int] = None,
         logger: Optional[logging.Logger] = None,
     ) -> None:
         self._client = httpx.AsyncClient(
@@ -93,6 +95,10 @@ class OpenCodeClient:
         self._logger = logger or logging.getLogger(__name__)
         self._api_profile: Optional[OpenCodeApiProfile] = None
         self._api_profile_lock = asyncio.Lock()
+        self._max_text_chars_override = (
+            int(max_text_chars) if isinstance(max_text_chars, int) else None
+        )
+        self._max_text_chars_cache: Optional[int] = None
 
     async def close(self) -> None:
         await self._client.aclose()
@@ -121,6 +127,7 @@ class OpenCodeClient:
                     profile.supports_global_endpoints = self.has_endpoint(
                         spec, "get", "/global/health"
                     ) or self.has_endpoint(spec, "get", "/global/event")
+                    profile.max_text_chars = self._extract_max_text_chars(spec)
 
                 log_event(
                     self._logger,
@@ -147,6 +154,103 @@ class OpenCodeClient:
             return OpenCodeApiProfile()
         return self._api_profile
 
+    @staticmethod
+    def _extract_max_text_chars(spec: dict[str, Any]) -> Optional[int]:
+        if not isinstance(spec, dict):
+            return None
+        components = spec.get("components")
+        if not isinstance(components, dict):
+            return None
+        schemas = components.get("schemas")
+        if not isinstance(schemas, dict):
+            return None
+        candidates: list[int] = []
+        for schema in schemas.values():
+            max_len = OpenCodeClient._find_text_max_length(schema)
+            if isinstance(max_len, int) and max_len > 0:
+                candidates.append(max_len)
+        return min(candidates) if candidates else None
+
+    @staticmethod
+    def _find_text_max_length(schema: Any) -> Optional[int]:
+        if not isinstance(schema, dict):
+            return None
+        candidates: list[int] = []
+        properties = schema.get("properties")
+        if isinstance(properties, dict) and "text" in properties:
+            text_schema = properties.get("text")
+            if isinstance(text_schema, dict):
+                max_len = text_schema.get("maxLength")
+                if isinstance(max_len, int) and max_len > 0:
+                    candidates.append(max_len)
+        for key in ("allOf", "anyOf", "oneOf"):
+            seq = schema.get(key)
+            if isinstance(seq, list):
+                for item in seq:
+                    item_len = OpenCodeClient._find_text_max_length(item)
+                    if isinstance(item_len, int) and item_len > 0:
+                        candidates.append(item_len)
+        return min(candidates) if candidates else None
+
+    def set_max_text_chars(self, value: Optional[int]) -> None:
+        self._max_text_chars_override = int(value) if isinstance(value, int) else None
+        self._max_text_chars_cache = None
+
+    async def _resolve_max_text_chars(
+        self, profile: Optional[OpenCodeApiProfile] = None
+    ) -> Optional[int]:
+        if self._max_text_chars_cache is not None:
+            return self._max_text_chars_cache
+        if profile is None:
+            profile = await self.detect_api_shape()
+        detected = (
+            profile.max_text_chars
+            if isinstance(profile.max_text_chars, int) and profile.max_text_chars > 0
+            else None
+        )
+        override = (
+            self._max_text_chars_override
+            if isinstance(self._max_text_chars_override, int)
+            and self._max_text_chars_override > 0
+            else None
+        )
+        if override is None:
+            resolved = detected
+        elif detected is None:
+            resolved = override
+        else:
+            resolved = min(override, detected)
+        self._max_text_chars_cache = resolved
+        return resolved
+
+    @staticmethod
+    def _split_text(text: str, max_chars: int) -> list[str]:
+        if max_chars <= 0 or len(text) <= max_chars:
+            return [text]
+        parts: list[str] = []
+        start = 0
+        length = len(text)
+        while start < length:
+            end = min(start + max_chars, length)
+            if end < length:
+                split = text.rfind("\n", start, end)
+                if split <= start:
+                    split = text.rfind(" ", start, end)
+                if split > start:
+                    end = split + 1
+            parts.append(text[start:end])
+            start = end
+        return [part for part in parts if part]
+
+    async def _build_text_parts(
+        self, message: str, profile: Optional[OpenCodeApiProfile] = None
+    ) -> list[dict[str, str]]:
+        limit = await self._resolve_max_text_chars(profile)
+        if limit is None:
+            return [{"type": "text", "text": message}]
+        chunks = self._split_text(message, limit)
+        return [{"type": "text", "text": chunk} for chunk in chunks]
+
     def _dir_params(self, directory: Optional[str]) -> dict[str, str]:
         return {"directory": directory} if directory else {}
 
@@ -275,8 +379,10 @@ class OpenCodeClient:
         model: Optional[dict[str, str]] = None,
         variant: Optional[str] = None,
     ) -> Any:
+        profile = await self.detect_api_shape()
+        parts = await self._build_text_parts(message, profile)
         payload: dict[str, Any] = {
-            "parts": [{"type": "text", "text": message}],
+            "parts": parts,
         }
         if agent:
             payload["agent"] = agent
@@ -300,8 +406,10 @@ class OpenCodeClient:
         model: Optional[dict[str, str]] = None,
         variant: Optional[str] = None,
     ) -> Any:
+        profile = await self.detect_api_shape()
+        parts = await self._build_text_parts(message, profile)
         payload: dict[str, Any] = {
-            "parts": [{"type": "text", "text": message}],
+            "parts": parts,
         }
         if agent:
             payload["agent"] = agent
@@ -310,7 +418,6 @@ class OpenCodeClient:
         if variant:
             payload["variant"] = variant
 
-        profile = await self.detect_api_shape()
         if profile.supports_prompt_async:
             return await self._request(
                 "POST",
@@ -335,8 +442,10 @@ class OpenCodeClient:
         model: Optional[dict[str, str]] = None,
         variant: Optional[str] = None,
     ) -> Any:
+        profile = await self.detect_api_shape()
+        parts = await self._build_text_parts(message, profile)
         payload: dict[str, Any] = {
-            "parts": [{"type": "text", "text": message}],
+            "parts": parts,
         }
         if agent:
             payload["agent"] = agent

codex_autorunner/agents/opencode/supervisor.py

@@ -55,6 +55,7 @@ class OpenCodeSupervisor:
         base_url: Optional[str] = None,
         subagent_models: Optional[Mapping[str, str]] = None,
         session_stall_timeout_seconds: Optional[float] = None,
+        max_text_chars: Optional[int] = None,
     ) -> None:
         self._command = [str(arg) for arg in command]
         self._logger = logger or logging.getLogger(__name__)
@@ -70,6 +71,7 @@ class OpenCodeSupervisor:
         self._base_env = base_env
         self._base_url = base_url
         self._subagent_models = subagent_models or {}
+        self._max_text_chars = max_text_chars
         self._handles: dict[str, OpenCodeHandle] = {}
         self._lock: Optional[asyncio.Lock] = None
 
@@ -275,6 +277,7 @@ class OpenCodeSupervisor:
                 base_url,
                 auth=self._auth,
                 timeout=self._request_timeout,
+                max_text_chars=self._max_text_chars,
                 logger=self._logger,
             )
             try:
@@ -344,6 +347,7 @@ class OpenCodeSupervisor:
                 base_url,
                 auth=self._auth,
                 timeout=self._request_timeout,
+                max_text_chars=self._max_text_chars,
                 logger=self._logger,
             )
             try:

codex_autorunner/agents/registry.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import importlib.metadata
 import logging
+import threading
 from dataclasses import dataclass
 from typing import Any, Callable, Iterable, Literal, Optional
 
@@ -102,6 +103,9 @@ _BUILTIN_AGENTS: dict[str, AgentDescriptor] = {
 # Lazy-loaded cache of built-in + plugin agents.
 _AGENT_CACHE: Optional[dict[str, AgentDescriptor]] = None
 
+# Lock to protect cache initialization and reload from concurrent access.
+_AGENT_CACHE_LOCK = threading.Lock()
+
 
 def _select_entry_points(group: str) -> Iterable[importlib.metadata.EntryPoint]:
     """Compatibility wrapper for `importlib.metadata.entry_points()` across py versions."""
@@ -164,10 +168,13 @@ def _load_agent_plugins() -> dict[str, AgentDescriptor]:
             continue
 
         api_version_raw = getattr(descriptor, "plugin_api_version", None)
-        try:
-            api_version = int(api_version_raw)
-        except Exception:
+        if api_version_raw is None:
             api_version = None
+        else:
+            try:
+                api_version = int(api_version_raw)
+            except Exception:
+                api_version = None
         if api_version is None:
             _logger.warning(
                 "Ignoring agent plugin %s: invalid api_version %s",
@@ -215,9 +222,11 @@ def _load_agent_plugins() -> dict[str, AgentDescriptor]:
 def _all_agents() -> dict[str, AgentDescriptor]:
     global _AGENT_CACHE
     if _AGENT_CACHE is None:
-        agents = _BUILTIN_AGENTS.copy()
-        agents.update(_load_agent_plugins())
-        _AGENT_CACHE = agents
+        with _AGENT_CACHE_LOCK:
+            if _AGENT_CACHE is None:
+                agents = _BUILTIN_AGENTS.copy()
+                agents.update(_load_agent_plugins())
+                _AGENT_CACHE = agents
     return _AGENT_CACHE
 
 
@@ -228,7 +237,8 @@ def reload_agents() -> dict[str, AgentDescriptor]:
     """
 
     global _AGENT_CACHE
-    _AGENT_CACHE = None
+    with _AGENT_CACHE_LOCK:
+        _AGENT_CACHE = None
     return get_registered_agents()
 
 

codex_autorunner/bootstrap.py

@@ -1,8 +1,14 @@
+import sys
 from pathlib import Path
+from typing import Optional
 
 import yaml
 
-from .core.about_car import ensure_about_car_file_for_repo
+from .core.about_car import (
+    ensure_about_car_file_for_repo,
+    ensure_ticket_flow_quickstart_file_for_repo,
+    ensure_tickets_agents_file_for_repo,
+)
 from .core.config import (
     CONFIG_FILENAME,
     DEFAULT_HUB_CONFIG,
@@ -18,6 +24,9 @@ from .manifest import load_manifest
 
 GITIGNORE_CONTENT = "*"
 GENERATED_CONFIG_HEADER = "# GENERATED by CAR - DO NOT EDIT\n"
+HUB_CAR_SHIM_MARKER = "# CAR:HUB_CLI_SHIM"
+HUB_CAR_SHIM_REL_PATH = Path(".codex-autorunner/bin/car")
+HUB_CAR_SHIM_ROOT_BASENAME = "car"
 
 
 def sample_todo() -> str:
@@ -69,6 +78,58 @@ def write_hub_config(hub_root: Path, force: bool = False) -> Path:
     return config_path
 
 
+def _build_hub_car_shim(python_executable: str) -> str:
+    content = (
+        "#!/bin/sh\n"
+        f"{HUB_CAR_SHIM_MARKER}\n"
+        "# Generated by CAR. Safe to overwrite.\n"
+        f'exec "{python_executable}" -m codex_autorunner.cli "$@"\n'
+    )
+    return content
+
+
+def _should_refresh_shim(path: Path, content: str, *, force: bool) -> bool:
+    if force or not path.exists():
+        return True
+    try:
+        existing = path.read_text(encoding="utf-8")
+    except OSError:
+        return True
+    if HUB_CAR_SHIM_MARKER not in existing:
+        return False
+    return existing != content
+
+
+def ensure_hub_car_shim(
+    hub_root: Path,
+    *,
+    python_executable: Optional[str] = None,
+    force: bool = False,
+) -> list[Path]:
+    """Ensure a hub-local car shim points at the current runtime."""
+    python_executable = python_executable or sys.executable
+    content = _build_hub_car_shim(python_executable)
+    if content and not content.endswith("\n"):
+        content += "\n"
+    targets = [
+        hub_root / HUB_CAR_SHIM_ROOT_BASENAME,
+        hub_root / HUB_CAR_SHIM_REL_PATH,
+    ]
+    written: list[Path] = []
+    for path in targets:
+        if not _should_refresh_shim(path, content, force=force):
+            continue
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content, encoding="utf-8")
+        try:
+            mode = path.stat().st_mode
+            path.chmod(mode | 0o111)
+        except OSError:
+            pass
+        written.append(path)
+    return written
+
+
 def seed_repo_files(
     repo_root: Path, force: bool = False, git_required: bool = True
 ) -> None:
@@ -117,10 +178,23 @@ def seed_repo_files(
         },
         force=force,
     )
+    ensure_ticket_flow_quickstart_file_for_repo(repo_root, force=force)
+    ensure_tickets_agents_file_for_repo(repo_root, force=force)
     ensure_ticket_linter(repo_root, force=force)
     ensure_ticket_manager(repo_root, force=force)
 
 
+def ensure_pma_docs(hub_root: Path, force: bool = False) -> None:
+    ca_dir = hub_root / ".codex-autorunner"
+    pma_dir = ca_dir / "pma"
+    pma_dir.mkdir(parents=True, exist_ok=True)
+    _seed_doc(pma_dir / "prompt.md", force, pma_prompt_content())
+    _seed_doc(pma_dir / "ABOUT_CAR.md", force, pma_about_content())
+    _seed_doc(pma_dir / "AGENTS.md", force, pma_agents_content())
+    _seed_doc(pma_dir / "active_context.md", force, pma_active_context_content())
+    _seed_doc(pma_dir / "context_log.md", force, pma_context_log_content())
+
+
 def seed_hub_files(hub_root: Path, force: bool = False) -> None:
     """
     Initialize a hub workspace with defaults and a manifest.
@@ -134,6 +208,9 @@ def seed_hub_files(hub_root: Path, force: bool = False) -> None:
 
     write_hub_config(hub_root, force=force)
 
+    ensure_pma_docs(hub_root, force=force)
+    ensure_hub_car_shim(hub_root, force=force)
+
     manifest_path = hub_root / DEFAULT_HUB_CONFIG["hub"]["manifest"]
     load_manifest(manifest_path, hub_root)
 
@@ -143,3 +220,144 @@ def seed_hub_files(hub_root: Path, force: bool = False) -> None:
             hub_state_path,
             '{\n  "last_scan_at": null,\n  "repos": []\n}\n',
         )
+
+
+def pma_prompt_content() -> str:
+    return """# Project Management Agent (PMA)
+
+You are the hub-level Project Management Agent (PMA), the user's primary interface for coordinating work across repos.
+
+## Role
+
+You are an **abstraction layer, not an executor**. Coordinate tickets and flows across multiple repos by delegating to repo agents.
+
+## Guidance
+
+- Use CAR-native artifacts (tickets, ticket_flow, dispatch, PMA inbox/outbox).
+- Ask questions when requirements are ambiguous; keep updates concise.
+- Treat this prompt as code: keep it short and stable.
+- See `.codex-autorunner/pma/ABOUT_CAR.md` for operational how-to.
+
+## Worktrees (hub-managed)
+
+- Prefer hub-owned worktrees:
+  - Hub UI: “New Worktree”
+  - CLI: `car hub worktree create <base_repo_id> <branch> [--start-point <ref>]`
+- If a worktree was created manually (e.g. `git worktree add`), it MUST be registered:
+  - `car hub scan --path <hub_root>`
+- Never copy `.codex-autorunner/` between worktrees. Each worktree has its own CAR state/docs.
+
+## PMA durable workspace
+
+Prefer writing durable guidance and recurring best-practices to `.codex-autorunner/pma/AGENTS.md`.
+Keep short-lived working context in `.codex-autorunner/pma/active_context.md` and prune it when it grows.
+When pruning, append the prior context to `.codex-autorunner/pma/context_log.md` with a timestamp.
+"""
+
+
+def pma_notes_content() -> str:
+    return """# PMA Operations Guide
+
+## Tickets (create/modify)
+
+- Tickets live per repo at `<repo>/.codex-autorunner/tickets/`.
+- Create or edit `TICKET-###*.md` files directly; keep diffs small and single-purpose.
+- Set `done: true` in the ticket frontmatter only when the ticket is complete.
+
+## Ticket flow (start/resume)
+
+- Bootstrap (creates TICKET-001 if missing):
+  `car flow ticket_flow bootstrap --repo <path>`
+- Start/resume:
+  `car flow ticket_flow start --repo <path>`
+  `car flow ticket_flow resume --repo <path> [--run-id <uuid>]`
+- Status/stop:
+  `car flow ticket_flow status --repo <path> [--run-id <uuid>]`
+  `car flow ticket_flow stop --repo <path> [--run-id <uuid>]`
+- See `<repo>/.codex-autorunner/TICKET_FLOW_QUICKSTART.md` for CLI entrypoints + gotchas.
+
+## Worktrees 101 (Hub-managed)
+
+Canonical worktree creation:
+- Hub UI: “New Worktree”
+- CLI (from hub root):
+  `car hub worktree create <base_repo_id> <branch> [--start-point <ref>]`
+
+Registering a manually-created worktree:
+- If you used `git worktree add`, run:
+  `car hub scan --path <hub_root>`
+- Worktrees should live under the hub’s configured worktrees root and be shallow (depth=1) discoverable.
+
+Naming / grouping:
+- Prefer worktree directory names like:
+  `<base_repo_id>--<branch>`
+- This enables `worktree_of` inference during scan and grouping in the hub UI.
+
+Do NOT copy `.codex-autorunner/` between worktrees:
+- Each worktree is a full repo with its own `.codex-autorunner/` state/docs.
+- Copying can introduce stale locks and confusing run metadata.
+
+## Dispatch pauses (handle)
+
+- Paused runs appear in the hub inbox snapshot with `repo_id`, `run_id`, and `open_url`.
+- Read the latest dispatch, respond to the user, then resume the run.
+- Dispatch history lives under:
+  `<repo>/.codex-autorunner/runs/<run_id>/dispatch_history/####/DISPATCH.md`
+
+## PMA file handoff
+
+- User uploads arrive in `.codex-autorunner/pma/inbox/`.
+- Send user-facing files by writing to `.codex-autorunner/pma/outbox/`.
+"""
+
+
+def pma_about_content() -> str:
+    return pma_notes_content()
+
+
+def pma_agents_content() -> str:
+    return """# PMA AGENTS (durable guidance + defaults)
+
+This document is jointly maintained by the user and PMA.
+
+## What belongs here
+
+- Durable best-practices you want PMA to apply repeatedly ("defaults").
+- Stable preferences (how to structure tickets, review habits, PR conventions).
+- Template shortcuts / references that PMA should re-use.
+
+## What does NOT belong here
+
+- Temporary work-in-progress details (put those in `active_context.md`).
+- Long transcripts.
+
+## Template shortcuts (optional)
+
+- Add references to frequently used ticket templates here (repo/path/ref) and when to apply them.
+
+## Defaults (examples)
+
+- After implementation work, add a final review ticket, then a ticket to open a PR.
+"""
+
+
+def pma_active_context_content() -> str:
+    return """# PMA active context (short-lived)
+
+Use this file for the current working set: active projects, open questions, links, and immediate next steps.
+
+Pruning guidance:
+- Keep this file compact (prefer bullet points).
+- When it grows too large, summarize older items and move durable guidance to `AGENTS.md`.
+- Before a major prune, append a timestamped snapshot to `context_log.md`.
+"""
+
+
+def pma_context_log_content() -> str:
+    return """# PMA context log (append-only)
+
+This file is an append-only history of past `active_context.md` snapshots.
+
+- Add a new section with an ISO timestamp when you perform a major prune.
+- Keep entries concise; the goal is searchability and historical recall.
+"""

codex_autorunner/core/__init__.py

@@ -1,5 +1,21 @@
 """Core runtime primitives."""
 
 from .archive import ArchiveResult, archive_worktree_snapshot
+from .context_awareness import CAR_AWARENESS_BLOCK, format_file_role_addendum
+from .lifecycle_events import (
+    LifecycleEvent,
+    LifecycleEventEmitter,
+    LifecycleEventStore,
+    LifecycleEventType,
+)
 
-__all__ = ["ArchiveResult", "archive_worktree_snapshot"]
+__all__ = [
+    "ArchiveResult",
+    "archive_worktree_snapshot",
+    "CAR_AWARENESS_BLOCK",
+    "format_file_role_addendum",
+    "LifecycleEvent",
+    "LifecycleEventEmitter",
+    "LifecycleEventStore",
+    "LifecycleEventType",
+]