codex-autorunner 1.2.1__py3-none-any.whl → 1.3.0__py3-none-any.whl

codex_autorunner/bootstrap.py

@@ -188,11 +188,18 @@ 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())
+    docs_dir = pma_dir / "docs"
+    docs_dir.mkdir(parents=True, exist_ok=True)
+    seeds = (
+        ("prompt.md", pma_prompt_content),
+        ("ABOUT_CAR.md", pma_about_content),
+        ("AGENTS.md", pma_agents_content),
+        ("active_context.md", pma_active_context_content),
+        ("context_log.md", pma_context_log_content),
+    )
+    for filename, content_fn in seeds:
+        _seed_doc(pma_dir / filename, force, content_fn())
+        _seed_doc(docs_dir / filename, force, content_fn())
 
 
 def seed_hub_files(hub_root: Path, force: bool = False) -> None:
@@ -308,6 +315,20 @@ Do NOT copy `.codex-autorunner/` between worktrees:
 
 - User uploads arrive in `.codex-autorunner/pma/inbox/`.
 - Send user-facing files by writing to `.codex-autorunner/pma/outbox/`.
+
+## PMA dispatches (user attention)
+
+- Create PMA dispatches by writing Markdown files to:
+  `.codex-autorunner/pma/dispatches/<timestamp>_<id>.md`
+- File format: YAML frontmatter + markdown body.
+- Required frontmatter fields:
+  - `title`: short summary
+  - `priority`: `info` | `warn` | `action`
+  - `created_at`: ISO 8601 timestamp
+  - `source_turn_id`: PMA turn id (for notifications)
+  - `links`: optional list of `{label, href}` objects
+  - `resolved_at`: leave empty/omit until resolved
+- The web UI lists unresolved dispatches; resolve via UI or set `resolved_at`.
 """
 
 

codex_autorunner/core/config.py

@@ -6,7 +6,7 @@ import os
 import shlex
 from os import PathLike
 from pathlib import Path
-from typing import IO, Any, Dict, List, Mapping, Optional, Union, cast
+from typing import IO, Any, Dict, List, Mapping, Optional, Tuple, Type, Union, cast
 
 import yaml
 
@@ -174,6 +174,9 @@ DEFAULT_REPO_CONFIG: Dict[str, Any] = {
             "restart_backoff_max_seconds": 30.0,
             "restart_backoff_jitter_ratio": 0.1,
         },
+        "output": {
+            "policy": "final_only",
+        },
         "prompts": {
             # NOTE: These keys are legacy names kept for config compatibility.
             # The workspace cutover uses tickets + workspace docs + unified file chat; only
@@ -486,6 +489,15 @@ DEFAULT_HUB_CONFIG: Dict[str, Any] = {
         "docs_max_chars": 12_000,
         "active_context_max_lines": 200,
         "context_log_tail_lines": 120,
+        "reactive_enabled": True,
+        "reactive_event_types": [
+            "flow_paused",
+            "flow_failed",
+            "flow_completed",
+            "dispatch_created",
+        ],
+        "reactive_debounce_seconds": 300,
+        "reactive_origin_blocklist": ["pma"],
     },
     "templates": {
         "enabled": True,
@@ -827,6 +839,11 @@ class AppServerClientConfig:
     restart_backoff_jitter_ratio: float
 
 
+@dataclasses.dataclass
+class AppServerOutputConfig:
+    policy: str
+
+
 @dataclasses.dataclass
 class AppServerConfig:
     command: List[str]
@@ -840,6 +857,7 @@ class AppServerConfig:
     turn_stall_recovery_min_interval_seconds: Optional[float]
     request_timeout: Optional[float]
     client: AppServerClientConfig
+    output: AppServerOutputConfig
     prompts: AppServerPromptsConfig
 
 
@@ -864,6 +882,10 @@ class PmaConfig:
     active_context_max_lines: int = 200
     context_log_tail_lines: int = 120
     dispatch_interception_enabled: bool = False
+    reactive_enabled: bool = True
+    reactive_event_types: List[str] = dataclasses.field(default_factory=list)
+    reactive_debounce_seconds: int = 300
+    reactive_origin_blocklist: List[str] = dataclasses.field(default_factory=list)
 
 
 @dataclasses.dataclass
@@ -1218,6 +1240,24 @@ def _parse_app_server_prompts_config(
     )
 
 
+_APP_SERVER_OUTPUT_POLICIES = {"final_only", "all_agent_messages"}
+
+
+def _parse_app_server_output_config(
+    cfg: Optional[Dict[str, Any]],
+    defaults: Optional[Dict[str, Any]],
+) -> AppServerOutputConfig:
+    cfg = cfg if isinstance(cfg, dict) else {}
+    defaults = defaults if isinstance(defaults, dict) else {}
+    policy_raw = cfg.get("policy", defaults.get("policy"))
+    policy = str(policy_raw).strip().lower() if policy_raw is not None else ""
+    if policy not in _APP_SERVER_OUTPUT_POLICIES:
+        policy = str(defaults.get("policy") or "final_only").strip().lower()
+    if policy not in _APP_SERVER_OUTPUT_POLICIES:
+        policy = "final_only"
+    return AppServerOutputConfig(policy=policy)
+
+
 def _parse_app_server_config(
     cfg: Optional[Dict[str, Any]],
     root: Path,
@@ -1316,6 +1356,9 @@ def _parse_app_server_config(
             value = float(client_defaults.get(key) or 0.0)
         return value
 
+    output_defaults = defaults.get("output")
+    output_cfg_raw = cfg.get("output")
+    output = _parse_app_server_output_config(output_cfg_raw, output_defaults)
     prompt_defaults = defaults.get("prompts")
     prompts = _parse_app_server_prompts_config(cfg.get("prompts"), prompt_defaults)
     return AppServerConfig(
@@ -1341,6 +1384,7 @@ def _parse_app_server_config(
                 "restart_backoff_jitter_ratio", allow_zero=True
             ),
         ),
+        output=output,
         prompts=prompts,
     )
 
@@ -1418,6 +1462,41 @@ def _parse_pma_config(
             defaults.get("dispatch_interception_enabled", False),
         )
     )
+    reactive_enabled = bool(
+        cfg.get("reactive_enabled", defaults.get("reactive_enabled", True))
+    )
+    reactive_event_types_raw = cfg.get(
+        "reactive_event_types", defaults.get("reactive_event_types", [])
+    )
+    if isinstance(reactive_event_types_raw, list):
+        reactive_event_types = [
+            str(value).strip()
+            for value in reactive_event_types_raw
+            if str(value).strip()
+        ]
+    else:
+        reactive_event_types = []
+    reactive_debounce_seconds_raw = cfg.get(
+        "reactive_debounce_seconds", defaults.get("reactive_debounce_seconds", 300)
+    )
+    try:
+        reactive_debounce_seconds = int(reactive_debounce_seconds_raw)
+    except (ValueError, TypeError):
+        reactive_debounce_seconds = 300
+    if reactive_debounce_seconds < 0:
+        reactive_debounce_seconds = 0
+    reactive_origin_blocklist_raw = cfg.get(
+        "reactive_origin_blocklist",
+        defaults.get("reactive_origin_blocklist", ["pma"]),
+    )
+    if isinstance(reactive_origin_blocklist_raw, list):
+        reactive_origin_blocklist = [
+            str(value).strip()
+            for value in reactive_origin_blocklist_raw
+            if str(value).strip()
+        ]
+    else:
+        reactive_origin_blocklist = []
     return PmaConfig(
         enabled=enabled,
         default_agent=default_agent,
@@ -1431,6 +1510,10 @@ def _parse_pma_config(
         active_context_max_lines=active_context_max_lines,
         context_log_tail_lines=context_log_tail_lines,
         dispatch_interception_enabled=dispatch_interception_enabled,
+        reactive_enabled=reactive_enabled,
+        reactive_event_types=reactive_event_types,
+        reactive_debounce_seconds=reactive_debounce_seconds,
+        reactive_origin_blocklist=reactive_origin_blocklist,
     )
 
 
@@ -2645,34 +2728,62 @@ def _validate_hub_config(cfg: Dict[str, Any], *, root: Path) -> None:
     _validate_telegram_bot_config(cfg)
 
 
+def _validate_optional_type(
+    mapping: Dict[str, Any],
+    key: str,
+    expected: Union[Type, Tuple[Type, ...]],
+    *,
+    path: str,
+    allow_none: bool = False,
+) -> None:
+    if key in mapping:
+        value = mapping.get(key)
+        if value is None and allow_none:
+            return
+        if isinstance(value, expected):
+            return
+        type_name = (
+            " or ".join(t.__name__ for t in expected)
+            if isinstance(expected, tuple)
+            else expected.__name__
+        )
+        raise ConfigError(f"{path}.{key} must be {type_name} if provided")
+
+
+def _validate_optional_int_ge(
+    mapping: Dict[str, Any], key: str, min_value: int, *, path: str
+) -> None:
+    if key in mapping:
+        value = mapping.get(key)
+        if isinstance(value, int) and value < min_value:
+            if min_value == 0:
+                raise ConfigError(f"{path}.{key} must be >= 0")
+            elif min_value == 1:
+                raise ConfigError(f"{path}.{key} must be > 0")
+            else:
+                raise ConfigError(f"{path}.{key} must be >= {min_value}")
+
+
 def _validate_housekeeping_config(cfg: Dict[str, Any]) -> None:
     housekeeping_cfg = cfg.get("housekeeping")
     if housekeeping_cfg is None:
         return
     if not isinstance(housekeeping_cfg, dict):
         raise ConfigError("housekeeping section must be a mapping if provided")
-    if "enabled" in housekeeping_cfg and not isinstance(
-        housekeeping_cfg.get("enabled"), bool
-    ):
-        raise ConfigError("housekeeping.enabled must be boolean")
-    if "interval_seconds" in housekeeping_cfg and not isinstance(
-        housekeeping_cfg.get("interval_seconds"), int
-    ):
-        raise ConfigError("housekeeping.interval_seconds must be an integer")
-    interval_seconds = housekeeping_cfg.get("interval_seconds")
-    if isinstance(interval_seconds, int) and interval_seconds <= 0:
-        raise ConfigError("housekeeping.interval_seconds must be greater than 0")
-    if "min_file_age_seconds" in housekeeping_cfg and not isinstance(
-        housekeeping_cfg.get("min_file_age_seconds"), int
-    ):
-        raise ConfigError("housekeeping.min_file_age_seconds must be an integer")
-    min_file_age_seconds = housekeeping_cfg.get("min_file_age_seconds")
-    if isinstance(min_file_age_seconds, int) and min_file_age_seconds < 0:
-        raise ConfigError("housekeeping.min_file_age_seconds must be >= 0")
-    if "dry_run" in housekeeping_cfg and not isinstance(
-        housekeeping_cfg.get("dry_run"), bool
-    ):
-        raise ConfigError("housekeeping.dry_run must be boolean")
+    _validate_optional_type(housekeeping_cfg, "enabled", bool, path="housekeeping")
+    _validate_optional_type(
+        housekeeping_cfg, "interval_seconds", int, path="housekeeping"
+    )
+    _validate_optional_int_ge(
+        housekeeping_cfg, "interval_seconds", 1, path="housekeeping"
+    )
+    _validate_optional_type(
+        housekeeping_cfg, "min_file_age_seconds", int, path="housekeeping"
+    )
+    _validate_optional_int_ge(
+        housekeeping_cfg, "min_file_age_seconds", 0, path="housekeeping"
+    )
+    _validate_optional_type(housekeeping_cfg, "dry_run", bool, path="housekeeping")
     rules = housekeeping_cfg.get("rules")
     if rules is not None and not isinstance(rules, list):
         raise ConfigError("housekeeping.rules must be a list if provided")
@@ -2682,10 +2793,9 @@ def _validate_housekeeping_config(cfg: Dict[str, Any]) -> None:
                 raise ConfigError(
                     f"housekeeping.rules[{idx}] must be a mapping if provided"
                 )
-            if "name" in rule and not isinstance(rule.get("name"), str):
-                raise ConfigError(
-                    f"housekeeping.rules[{idx}].name must be a string if provided"
-                )
+            _validate_optional_type(
+                rule, "name", str, path=f"housekeeping.rules[{idx}]"
+            )
             if "kind" in rule:
                 kind = rule.get("kind")
                 if not isinstance(kind, str):
@@ -2696,8 +2806,6 @@ def _validate_housekeeping_config(cfg: Dict[str, Any]) -> None:
                     raise ConfigError(
                         f"housekeeping.rules[{idx}].kind must be 'directory' or 'file'"
                     )
-            if "path" in rule and not isinstance(rule.get("path"), str):
-                raise ConfigError(f"housekeeping.rules[{idx}].path must be a string")
             if "path" in rule:
                 path_value = rule.get("path")
                 if not isinstance(path_value, str) or not path_value:
@@ -2713,14 +2821,12 @@ def _validate_housekeeping_config(cfg: Dict[str, Any]) -> None:
                     raise ConfigError(
                         f"housekeeping.rules[{idx}].path must not contain '..' segments"
                     )
-            if "glob" in rule and not isinstance(rule.get("glob"), str):
-                raise ConfigError(
-                    f"housekeeping.rules[{idx}].glob must be a string if provided"
-                )
-            if "recursive" in rule and not isinstance(rule.get("recursive"), bool):
-                raise ConfigError(
-                    f"housekeeping.rules[{idx}].recursive must be boolean if provided"
-                )
+            _validate_optional_type(
+                rule, "glob", str, path=f"housekeeping.rules[{idx}]"
+            )
+            _validate_optional_type(
+                rule, "recursive", bool, path=f"housekeeping.rules[{idx}]"
+            )
             for key in (
                 "max_files",
                 "max_total_bytes",
@@ -2728,13 +2834,12 @@ def _validate_housekeeping_config(cfg: Dict[str, Any]) -> None:
                 "max_bytes",
                 "max_lines",
             ):
-                if key in rule and not isinstance(rule.get(key), int):
-                    raise ConfigError(
-                        f"housekeeping.rules[{idx}].{key} must be an integer if provided"
-                    )
-                value = rule.get(key)
-                if isinstance(value, int) and value < 0:
-                    raise ConfigError(f"housekeeping.rules[{idx}].{key} must be >= 0")
+                _validate_optional_type(
+                    rule, key, int, path=f"housekeeping.rules[{idx}]"
+                )
+                _validate_optional_int_ge(
+                    rule, key, 0, path=f"housekeeping.rules[{idx}]"
+                )
 
 
 def _validate_static_assets_config(cfg: Dict[str, Any], scope: str) -> None:
@@ -2743,21 +2848,33 @@ def _validate_static_assets_config(cfg: Dict[str, Any], scope: str) -> None:
         return
     if not isinstance(static_cfg, dict):
         raise ConfigError(f"{scope}.static_assets must be a mapping if provided")
-    cache_root = static_cfg.get("cache_root")
-    if cache_root is not None and not isinstance(cache_root, str):
-        raise ConfigError(f"{scope}.static_assets.cache_root must be a string")
-    max_entries = static_cfg.get("max_cache_entries")
-    if max_entries is not None and not isinstance(max_entries, int):
-        raise ConfigError(f"{scope}.static_assets.max_cache_entries must be an integer")
-    if isinstance(max_entries, int) and max_entries < 0:
-        raise ConfigError(f"{scope}.static_assets.max_cache_entries must be >= 0")
-    max_age_days = static_cfg.get("max_cache_age_days")
-    if max_age_days is not None and not isinstance(max_age_days, int):
-        raise ConfigError(
-            f"{scope}.static_assets.max_cache_age_days must be an integer or null"
-        )
-    if isinstance(max_age_days, int) and max_age_days < 0:
-        raise ConfigError(f"{scope}.static_assets.max_cache_age_days must be >= 0")
+    _validate_optional_type(
+        static_cfg,
+        "cache_root",
+        str,
+        path=f"{scope}.static_assets",
+        allow_none=True,
+    )
+    _validate_optional_type(
+        static_cfg,
+        "max_cache_entries",
+        int,
+        path=f"{scope}.static_assets",
+        allow_none=True,
+    )
+    _validate_optional_int_ge(
+        static_cfg, "max_cache_entries", 0, path=f"{scope}.static_assets"
+    )
+    _validate_optional_type(
+        static_cfg,
+        "max_cache_age_days",
+        int,
+        path=f"{scope}.static_assets",
+        allow_none=True,
+    )
+    _validate_optional_int_ge(
+        static_cfg, "max_cache_age_days", 0, path=f"{scope}.static_assets"
+    )
 
 
 def _validate_telegram_bot_config(cfg: Dict[str, Any]) -> None:

codex_autorunner/core/filesystem.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+
+def copy_path(src: Path, dst: Path) -> None:
+    """Copy a file or directory to a destination.
+
+    If src is a directory, copy it recursively using copytree.
+    If src is a file, copy it using copy2 after ensuring parent directory exists.
+
+    Args:
+        src: Source path to copy from
+        dst: Destination path to copy to
+
+    Raises:
+        OSError: If the copy operation fails
+    """
+    if src.is_dir():
+        shutil.copytree(src, dst)
+    else:
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(src, dst)

codex_autorunner/core/flows/controller.py

@@ -4,6 +4,7 @@ import uuid
 from pathlib import Path
 from typing import Any, AsyncGenerator, Callable, Dict, Optional, Set
 
+from ...manifest import ManifestError, load_manifest
 from ..lifecycle_events import LifecycleEventEmitter
 from ..utils import find_repo_root
 from .definition import FlowDefinition
@@ -46,16 +47,30 @@ class FlowController:
         self.artifacts_root = artifacts_root
         self.store = FlowStore(db_path, durable=durable)
         self._event_listeners: Set[Callable[[FlowEvent], None]] = set()
-        self._lifecycle_event_listeners: Set[Callable[[str, str, str, dict], None]] = (
-            set()
-        )
+        self._lifecycle_event_listeners: Set[
+            Callable[[str, str, str, dict, str], None]
+        ] = set()
         self._lock = asyncio.Lock()
         self._lifecycle_emitter: Optional[LifecycleEventEmitter] = None
+        self._repo_id = ""
         if hub_root is None:
             hub_root = _find_hub_root(db_path.parent.parent if db_path else None)
         if hub_root is not None:
             self._lifecycle_emitter = LifecycleEventEmitter(hub_root)
             self.add_lifecycle_event_listener(self._emit_to_lifecycle_store)
+            self._repo_id = self._resolve_repo_id(hub_root)
+
+    def _resolve_repo_id(self, hub_root: Path) -> str:
+        repo_root = self.db_path.parent.parent if self.db_path else None
+        if repo_root is None:
+            return ""
+        manifest_path = hub_root / ".codex-autorunner" / "manifest.yml"
+        try:
+            manifest = load_manifest(manifest_path, hub_root)
+        except ManifestError:
+            return ""
+        entry = manifest.get_by_path(hub_root, repo_root)
+        return entry.id if entry else ""
 
     def initialize(self) -> None:
         self.artifacts_root.mkdir(parents=True, exist_ok=True)
@@ -209,38 +224,61 @@ class FlowController:
         self._event_listeners.discard(listener)
 
     def add_lifecycle_event_listener(
-        self, listener: Callable[[str, str, str, dict], None]
+        self, listener: Callable[[str, str, str, dict, str], None]
     ) -> None:
         self._lifecycle_event_listeners.add(listener)
 
     def remove_lifecycle_event_listener(
-        self, listener: Callable[[str, str, str, dict], None]
+        self, listener: Callable[[str, str, str, dict, str], None]
     ) -> None:
         self._lifecycle_event_listeners.discard(listener)
 
     def _emit_lifecycle(
-        self, event_type: str, repo_id: str, run_id: str, data: Dict[str, Any]
+        self,
+        event_type: str,
+        repo_id: str,
+        run_id: str,
+        data: Dict[str, Any],
+        origin: str,
     ) -> None:
+        resolved_repo_id = self._repo_id or repo_id
+        payload = data
+        if resolved_repo_id and data.get("repo_id") != resolved_repo_id:
+            payload = dict(data)
+            payload["repo_id"] = resolved_repo_id
         for listener in self._lifecycle_event_listeners:
             try:
-                listener(event_type, repo_id, run_id, data)
+                listener(event_type, resolved_repo_id, run_id, payload, origin)
             except Exception as e:
                 _logger.exception("Error in lifecycle event listener: %s", e)
 
     def _emit_to_lifecycle_store(
-        self, event_type: str, repo_id: str, run_id: str, data: Dict[str, Any]
+        self,
+        event_type: str,
+        repo_id: str,
+        run_id: str,
+        data: Dict[str, Any],
+        origin: str,
     ) -> None:
         if self._lifecycle_emitter is None:
             return
         try:
             if event_type == "flow_paused":
-                self._lifecycle_emitter.emit_flow_paused(repo_id, run_id, data=data)
+                self._lifecycle_emitter.emit_flow_paused(
+                    repo_id, run_id, data=data, origin=origin
+                )
             elif event_type == "flow_completed":
-                self._lifecycle_emitter.emit_flow_completed(repo_id, run_id, data=data)
+                self._lifecycle_emitter.emit_flow_completed(
+                    repo_id, run_id, data=data, origin=origin
+                )
             elif event_type == "flow_failed":
-                self._lifecycle_emitter.emit_flow_failed(repo_id, run_id, data=data)
+                self._lifecycle_emitter.emit_flow_failed(
+                    repo_id, run_id, data=data, origin=origin
+                )
             elif event_type == "flow_stopped":
-                self._lifecycle_emitter.emit_flow_stopped(repo_id, run_id, data=data)
+                self._lifecycle_emitter.emit_flow_stopped(
+                    repo_id, run_id, data=data, origin=origin
+                )
         except Exception as exc:
             _logger.exception("Error emitting to lifecycle store: %s", exc)
 

codex_autorunner/core/flows/runtime.py

@@ -11,7 +11,7 @@ from .store import FlowStore, now_iso
 _logger = logging.getLogger(__name__)
 
 
-LifecycleEventCallback = Optional[Callable[[str, str, str, Dict[str, Any]], None]]
+LifecycleEventCallback = Optional[Callable[[str, str, str, Dict[str, Any], str], None]]
 
 
 class FlowRuntime:
@@ -29,11 +29,16 @@ class FlowRuntime:
         self._stop_check_interval = 0.5
 
     def _emit_lifecycle(
-        self, event_type: str, repo_id: str, run_id: str, data: Dict[str, Any]
+        self,
+        event_type: str,
+        repo_id: str,
+        run_id: str,
+        data: Dict[str, Any],
+        origin: str = "runner",
     ) -> None:
         if self.emit_lifecycle_event:
             try:
-                self.emit_lifecycle_event(event_type, repo_id, run_id, data)
+                self.emit_lifecycle_event(event_type, repo_id, run_id, data, origin)
             except Exception as exc:
                 _logger.exception("Error emitting lifecycle event: %s", exc)