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

codex_autorunner/core/pma_transcripts.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+import json
+import logging
+import re
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Optional
+
+from .time_utils import now_iso
+from .utils import atomic_write
+
+logger = logging.getLogger(__name__)
+
+PMA_TRANSCRIPTS_DIRNAME = "transcripts"
+PMA_TRANSCRIPT_VERSION = 1
+PMA_TRANSCRIPT_PREVIEW_CHARS = 400
+
+
+def default_pma_transcripts_dir(hub_root: Path) -> Path:
+    return hub_root / ".codex-autorunner" / "pma" / PMA_TRANSCRIPTS_DIRNAME
+
+
+def _safe_segment(value: str) -> str:
+    cleaned = re.sub(r"[^A-Za-z0-9._-]+", "-", (value or "").strip())
+    cleaned = cleaned.strip("-._")
+    if not cleaned:
+        return "unknown"
+    return cleaned[:120]
+
+
+def _stamp_now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+
+
+def _read_preview(path: Path) -> str:
+    if not path.exists():
+        return ""
+    try:
+        with open(path, "r", encoding="utf-8") as handle:
+            text = handle.read(PMA_TRANSCRIPT_PREVIEW_CHARS + 1)
+    except OSError as exc:
+        logger.warning("Failed to read PMA transcript content at %s: %s", path, exc)
+        return ""
+    text = text.strip()
+    if len(text) <= PMA_TRANSCRIPT_PREVIEW_CHARS:
+        return text
+    return text[:PMA_TRANSCRIPT_PREVIEW_CHARS].rstrip() + "..."
+
+
+@dataclass(frozen=True)
+class PmaTranscriptPointer:
+    turn_id: str
+    metadata_path: str
+    content_path: str
+    created_at: str
+
+
+class PmaTranscriptStore:
+    def __init__(self, hub_root: Path) -> None:
+        self._root = hub_root
+        self._dir = default_pma_transcripts_dir(hub_root)
+
+    @property
+    def dir(self) -> Path:
+        return self._dir
+
+    def write_transcript(
+        self,
+        *,
+        turn_id: str,
+        metadata: dict[str, Any],
+        assistant_text: str,
+    ) -> PmaTranscriptPointer:
+        safe_turn_id = _safe_segment(turn_id)
+        stamp = _stamp_now()
+        base = f"{stamp}_{safe_turn_id}"
+        json_path = self._dir / f"{base}.json"
+        md_path = self._dir / f"{base}.md"
+
+        payload = dict(metadata)
+        payload.setdefault("version", PMA_TRANSCRIPT_VERSION)
+        payload.setdefault("turn_id", turn_id)
+        payload.setdefault("created_at", now_iso())
+        payload["metadata_path"] = str(json_path)
+        payload["content_path"] = str(md_path)
+        payload["assistant_text_chars"] = len(assistant_text or "")
+
+        self._dir.mkdir(parents=True, exist_ok=True)
+        atomic_write(md_path, (assistant_text or "") + "\n")
+        atomic_write(json_path, json.dumps(payload, indent=2) + "\n")
+
+        return PmaTranscriptPointer(
+            turn_id=turn_id,
+            metadata_path=str(json_path),
+            content_path=str(md_path),
+            created_at=payload["created_at"],
+        )
+
+    def list_recent(self, *, limit: int = 50) -> list[dict[str, Any]]:
+        if limit <= 0:
+            return []
+        if not self._dir.exists():
+            return []
+        entries: list[dict[str, Any]] = []
+        for path in sorted(self._dir.glob("*.json"), reverse=True):
+            try:
+                raw = path.read_text(encoding="utf-8")
+                data = json.loads(raw)
+            except (OSError, json.JSONDecodeError) as exc:
+                logger.warning(
+                    "Failed to read PMA transcript metadata at %s: %s", path, exc
+                )
+                continue
+            if not isinstance(data, dict):
+                continue
+            content_path = Path(str(data.get("content_path") or ""))
+            if not content_path.is_absolute():
+                content_path = (path.parent / content_path).resolve()
+            data = dict(data)
+            data["preview"] = _read_preview(content_path)
+            entries.append(data)
+            if len(entries) >= limit:
+                break
+        return entries
+
+    def read_transcript(self, turn_id: str) -> Optional[dict[str, Any]]:
+        match = self._find_metadata(turn_id)
+        if not match:
+            return None
+        meta, meta_path = match
+        content_path = Path(str(meta.get("content_path") or ""))
+        if not content_path.is_absolute():
+            content_path = (meta_path.parent / content_path).resolve()
+        try:
+            content = content_path.read_text(encoding="utf-8")
+        except OSError as exc:
+            logger.warning(
+                "Failed to read PMA transcript content at %s: %s", content_path, exc
+            )
+            content = ""
+        return {"metadata": meta, "content": content}
+
+    def _find_metadata(self, turn_id: str) -> Optional[tuple[dict[str, Any], Path]]:
+        if not self._dir.exists():
+            return None
+        safe_turn_id = _safe_segment(turn_id)
+        candidates = sorted(self._dir.glob(f"*_{safe_turn_id}.json"), reverse=True)
+        for path in candidates:
+            meta = self._read_metadata(path)
+            if meta and str(meta.get("turn_id")) == turn_id:
+                return meta, path
+        if candidates:
+            meta = self._read_metadata(candidates[0])
+            if meta:
+                return meta, candidates[0]
+        for path in sorted(self._dir.glob("*.json"), reverse=True):
+            meta = self._read_metadata(path)
+            if meta and str(meta.get("turn_id")) == turn_id:
+                return meta, path
+        return None
+
+    def _read_metadata(self, path: Path) -> Optional[dict[str, Any]]:
+        try:
+            raw = path.read_text(encoding="utf-8")
+            data = json.loads(raw)
+        except (OSError, json.JSONDecodeError) as exc:
+            logger.warning(
+                "Failed to read PMA transcript metadata at %s: %s", path, exc
+            )
+            return None
+        return data if isinstance(data, dict) else None
+
+
+__all__ = [
+    "PMA_TRANSCRIPTS_DIRNAME",
+    "PMA_TRANSCRIPT_PREVIEW_CHARS",
+    "PMA_TRANSCRIPT_VERSION",
+    "PmaTranscriptPointer",
+    "PmaTranscriptStore",
+    "default_pma_transcripts_dir",
+]

codex_autorunner/core/safe_paths.py

@@ -0,0 +1,117 @@
+"""Safe path validation utilities for web endpoints.
+
+This module provides utilities for validating user-controlled paths to prevent
+directory traversal attacks and other path-based security issues.
+"""
+
+from pathlib import PurePosixPath
+from typing import Optional
+
+
+class SafePathError(Exception):
+    """Raised when a path fails safety validation."""
+
+    def __init__(self, message: str, path: Optional[str] = None) -> None:
+        super().__init__(message)
+        self.path = path
+
+
+def validate_relative_posix_path(raw: str) -> PurePosixPath:
+    """Validate a user-provided path string and return a PurePosixPath.
+
+    This function validates that:
+    1. The path is not absolute
+    2. The path does not contain '..' segments (parent directory traversal)
+    3. The path does not contain backslashes (Windows separators)
+    4. The path is not empty, '.', or only slashes
+
+    Args:
+        raw: The user-provided path string (typically from a URL path parameter)
+
+    Returns:
+        A validated PurePosixPath object
+
+    Raises:
+        SafePathError: If the path fails validation
+
+    Examples:
+        >>> validate_relative_posix_path("file.txt")
+        PurePosixPath('file.txt')
+
+        >>> validate_relative_posix_path("a/b/c.txt")
+        PurePosixPath('a/b/c.txt')
+
+        >>> validate_relative_posix_path("../etc/passwd")
+        SafePathError: Invalid path: '..' not allowed
+
+        >>> validate_relative_posix_path("/etc/passwd")
+        SafePathError: Absolute paths not allowed
+    """
+    if not raw or raw.strip() == "" or raw == ".":
+        raise SafePathError("Invalid path: empty or '.'", path=raw)
+
+    # Reject backslashes early (Windows separators)
+    if "\\" in raw:
+        raise SafePathError("Invalid path: backslashes not allowed", path=raw)
+
+    # Reject '..' in the raw path before PurePosixPath normalizes it
+    # We need to check the raw string because PurePosixPath("a/../b")
+    # normalizes to "b", which would bypass the later parts check
+    if ".." in raw:
+        raise SafePathError("Invalid path: '..' not allowed", path=raw)
+
+    # Parse with PurePosixPath to ensure POSIX semantics
+    try:
+        file_rel = PurePosixPath(raw)
+    except Exception as exc:
+        raise SafePathError(f"Invalid path: {exc}", path=raw) from exc
+
+    # Reject absolute paths
+    if file_rel.is_absolute():
+        raise SafePathError("Absolute paths not allowed", path=raw)
+
+    # Double-check '..' traversal segments after parsing (for edge cases)
+    if ".." in file_rel.parts:
+        raise SafePathError("Invalid path: '..' not allowed", path=raw)
+
+    return file_rel
+
+
+def validate_single_filename(raw: str) -> str:
+    """Validate that a path string represents only a single filename (no subpaths).
+
+    This is a stricter version of validate_relative_posix_path that only allows
+    a single filename component, not subdirectories.
+
+    Args:
+        raw: The user-provided path string
+
+    Returns:
+        The validated filename
+
+    Raises:
+        SafePathError: If the path contains slashes or is otherwise invalid
+
+    Examples:
+        >>> validate_single_filename("file.txt")
+        'file.txt'
+
+        >>> validate_single_filename("a/b.txt")
+        SafePathError: Subpaths not allowed: only single filenames permitted
+
+        >>> validate_single_filename("../etc/passwd")
+        SafePathError: Subpaths not allowed: only single filenames permitted
+    """
+    file_rel = validate_relative_posix_path(raw)
+
+    # Ensure only a single component (no subpaths)
+    if len(file_rel.parts) != 1:
+        raise SafePathError(
+            "Subpaths not allowed: only single filenames permitted", path=raw
+        )
+
+    # Return the string representation of the filename
+    return str(file_rel)
+
+
+__all__ = ["SafePathError", "validate_relative_posix_path", "validate_single_filename"]

codex_autorunner/housekeeping.py

@@ -8,6 +8,8 @@ from collections import deque
 from pathlib import Path
 from typing import Any, Iterable, Optional, Protocol, cast
 
+_MAX_ERROR_SAMPLES = 5
+
 
 @dataclasses.dataclass(frozen=True)
 class HousekeepingRule:
@@ -42,6 +44,7 @@ class HousekeepingRuleResult:
     deleted_bytes: int = 0
     truncated_bytes: int = 0
     errors: int = 0
+    error_samples: list[str] = dataclasses.field(default_factory=list)
     duration_ms: int = 0
 
 
@@ -136,21 +139,26 @@ def run_housekeeping_once(
             continue
         results.append(result)
         if logger is not None:
+            log_fields: dict[str, Any] = {
+                "name": result.name,
+                "kind": result.kind,
+                "scanned_count": result.scanned_count,
+                "eligible_count": result.eligible_count,
+                "deleted_count": result.deleted_count,
+                "deleted_bytes": result.deleted_bytes,
+                "truncated_bytes": result.truncated_bytes,
+                "errors": result.errors,
+                "duration_ms": result.duration_ms,
+                "dry_run": config.dry_run,
+                "root": str(root),
+            }
+            if result.errors > 0 and result.error_samples:
+                log_fields["error_samples"] = result.error_samples
             _log_event(
                 logger,
                 logging.INFO,
                 "housekeeping.rule",
-                name=result.name,
-                kind=result.kind,
-                scanned_count=result.scanned_count,
-                eligible_count=result.eligible_count,
-                deleted_count=result.deleted_count,
-                deleted_bytes=result.deleted_bytes,
-                truncated_bytes=result.truncated_bytes,
-                errors=result.errors,
-                duration_ms=result.duration_ms,
-                dry_run=config.dry_run,
-                root=str(root),
+                **log_fields,
             )
     if logger is not None:
         _log_event(
@@ -174,7 +182,7 @@ def _apply_directory_rule(
         return result
     now = time.time()
     min_age = max(config.min_file_age_seconds, 0)
-    files = _collect_files(base, rule)
+    files = _collect_files(base, rule, result)
     result.scanned_count = len(files)
     if not files:
         result.duration_ms = int((time.monotonic() - start) * 1000)
@@ -192,8 +200,9 @@ def _apply_directory_rule(
         if not config.dry_run:
             try:
                 entry.path.unlink()
-            except OSError:
+            except OSError as e:
                 errors += 1
+                _add_error_sample(result, "unlink", entry.path, e)
                 return
         deleted.add(entry.path)
         deleted_bytes += entry.size
@@ -254,8 +263,9 @@ def _apply_file_rule(
         return result
     try:
         stat = path.stat()
-    except OSError:
+    except OSError as e:
         result.errors = 1
+        _add_error_sample(result, "stat", path, e)
         return result
     if not path.is_file():
         return result
@@ -271,6 +281,7 @@ def _apply_file_rule(
             path,
             rule.max_lines,
             dry_run=config.dry_run,
+            result=result,
         )
         result.truncated_bytes += truncated
     if rule.max_bytes is not None:
@@ -278,13 +289,16 @@ def _apply_file_rule(
             path,
             rule.max_bytes,
             dry_run=config.dry_run,
+            result=result,
         )
         result.truncated_bytes += truncated
     result.duration_ms = int((time.monotonic() - start) * 1000)
     return result
 
 
-def _collect_files(base: Path, rule: HousekeepingRule) -> list[_FileInfo]:
+def _collect_files(
+    base: Path, rule: HousekeepingRule, result: Optional[HousekeepingRuleResult] = None
+) -> list[_FileInfo]:
     results: list[_FileInfo] = []
     glob_pattern = rule.glob or "*"
     iterator = base.rglob(glob_pattern) if rule.recursive else base.glob(glob_pattern)
@@ -293,7 +307,9 @@ def _collect_files(base: Path, rule: HousekeepingRule) -> list[_FileInfo]:
             if not path.is_file():
                 continue
             stat = path.stat()
-        except OSError:
+        except OSError as e:
+            if result is not None:
+                _add_error_sample(result, "stat", path, e)
             continue
         results.append(_FileInfo(path=path, size=stat.st_size, mtime=stat.st_mtime))
     return results
@@ -310,12 +326,21 @@ def _is_absolute_path(path: str) -> bool:
     return Path(path).expanduser().is_absolute()
 
 
-def _truncate_bytes(path: Path, max_bytes: int, *, dry_run: bool) -> int:
+def _truncate_bytes(
+    path: Path,
+    max_bytes: int,
+    *,
+    dry_run: bool,
+    result: Optional[HousekeepingRuleResult] = None,
+) -> int:
     if max_bytes <= 0:
         return 0
     try:
         size = path.stat().st_size
-    except OSError:
+    except OSError as e:
+        if result is not None:
+            result.errors += 1
+            _add_error_sample(result, "truncate_bytes", path, e)
         return 0
     if size <= max_bytes:
         return 0
@@ -328,23 +353,38 @@ def _truncate_bytes(path: Path, max_bytes: int, *, dry_run: bool) -> int:
             payload = handle.read()
         _atomic_write_bytes(path, payload)
         return truncated
-    except OSError:
+    except OSError as e:
+        if result is not None:
+            result.errors += 1
+            _add_error_sample(result, "truncate_bytes", path, e)
         return 0
 
 
-def _truncate_lines(path: Path, max_lines: int, *, dry_run: bool) -> int:
+def _truncate_lines(
+    path: Path,
+    max_lines: int,
+    *,
+    dry_run: bool,
+    result: Optional[HousekeepingRuleResult] = None,
+) -> int:
     if max_lines <= 0:
         return 0
     try:
         size = path.stat().st_size
-    except OSError:
+    except OSError as e:
+        if result is not None:
+            result.errors += 1
+            _add_error_sample(result, "truncate_lines", path, e)
         return 0
     lines: deque[bytes] = deque(maxlen=max_lines)
     try:
         with path.open("rb") as handle:
             for line in handle:
                 lines.append(line)
-    except OSError:
+    except OSError as e:
+        if result is not None:
+            result.errors += 1
+            _add_error_sample(result, "truncate_lines", path, e)
         return 0
     payload = b"".join(lines)
     if len(payload) >= size:
@@ -353,7 +393,10 @@ def _truncate_lines(path: Path, max_lines: int, *, dry_run: bool) -> int:
         return size - len(payload)
     try:
         _atomic_write_bytes(path, payload)
-    except OSError:
+    except OSError as e:
+        if result is not None:
+            result.errors += 1
+            _add_error_sample(result, "truncate_lines", path, e)
         return 0
     return size - len(payload)
 
@@ -379,6 +422,17 @@ def _prune_empty_dirs(base: Path) -> None:
                 continue
 
 
+def _add_error_sample(
+    result: HousekeepingRuleResult, operation: str, path: Path, exc: OSError
+) -> None:
+    if len(result.error_samples) >= _MAX_ERROR_SAMPLES:
+        return
+    exc_info = f"{type(exc).__name__}"
+    if exc.strerror:
+        exc_info += f": {exc.strerror}"
+    result.error_samples.append(f"{operation} {path}: {exc_info}")
+
+
 def _int_or_none(value: object) -> Optional[int]:
     if value is None:
         return None

codex_autorunner/integrations/agents/codex_backend.py

@@ -47,6 +47,7 @@ class CodexAppServerBackend(AgentBackend):
         restart_backoff_initial_seconds: Optional[float] = None,
         restart_backoff_max_seconds: Optional[float] = None,
         restart_backoff_jitter_ratio: Optional[float] = None,
+        output_policy: str = "final_only",
         notification_handler: Optional[NotificationHandler] = None,
         logger: Optional[logging.Logger] = None,
     ):
@@ -71,6 +72,7 @@ class CodexAppServerBackend(AgentBackend):
         self._restart_backoff_initial_seconds = restart_backoff_initial_seconds
         self._restart_backoff_max_seconds = restart_backoff_max_seconds
         self._restart_backoff_jitter_ratio = restart_backoff_jitter_ratio
+        self._output_policy = output_policy
         self._notification_handler = notification_handler
         self._logger = logger or _logger
 
@@ -102,6 +104,7 @@ class CodexAppServerBackend(AgentBackend):
                 restart_backoff_initial_seconds=self._restart_backoff_initial_seconds,
                 restart_backoff_max_seconds=self._restart_backoff_max_seconds,
                 restart_backoff_jitter_ratio=self._restart_backoff_jitter_ratio,
+                output_policy=self._output_policy,
                 logger=self._logger,
             )
             await self._client.start()
@@ -201,16 +204,18 @@ class CodexAppServerBackend(AgentBackend):
         yield AgentEvent.stream_delta(content=message, delta_type="user_message")
 
         result = await handle.wait(timeout=self._turn_timeout_seconds)
-
-        for msg in result.agent_messages:
-            yield AgentEvent.stream_delta(content=msg, delta_type="assistant_message")
+        final_text = str(getattr(result, "final_message", "") or "")
+        if not final_text.strip():
+            final_text = "\n\n".join(
+                msg.strip()
+                for msg in getattr(result, "agent_messages", [])
+                if isinstance(msg, str) and msg.strip()
+            )
 
         for event_data in result.raw_events:
             yield self._parse_raw_event(event_data)
 
-        yield AgentEvent.message_complete(
-            final_message="\n".join(result.agent_messages)
-        )
+        yield AgentEvent.message_complete(final_message=final_text)
 
     async def run_turn_events(
         self, session_id: str, message: str
@@ -283,11 +288,12 @@ class CodexAppServerBackend(AgentBackend):
                     if get_task in pending_set:
                         get_task.cancel()
                     result = wait_task.result()
-                    for msg in result.agent_messages:
-                        yield OutputDelta(
-                            timestamp=now_iso(),
-                            content=msg,
-                            delta_type="assistant_message",
+                    final_text = str(getattr(result, "final_message", "") or "")
+                    if not final_text.strip():
+                        final_text = "\n\n".join(
+                            msg.strip()
+                            for msg in getattr(result, "agent_messages", [])
+                            if isinstance(msg, str) and msg.strip()
                         )
                     # raw_events already contain the same notifications we streamed
                     # through _event_queue; skipping here avoids double-emitting.
@@ -297,7 +303,7 @@ class CodexAppServerBackend(AgentBackend):
                             yield extra
                     yield Completed(
                         timestamp=now_iso(),
-                        final_message="\n".join(result.agent_messages),
+                        final_message=final_text,
                     )
                     break
 

codex_autorunner/integrations/agents/wiring.py

@@ -106,6 +106,7 @@ class AgentBackendFactory:
                     restart_backoff_initial_seconds=self._config.app_server.client.restart_backoff_initial_seconds,
                     restart_backoff_max_seconds=self._config.app_server.client.restart_backoff_max_seconds,
                     restart_backoff_jitter_ratio=self._config.app_server.client.restart_backoff_jitter_ratio,
+                    output_policy=self._config.app_server.output.policy,
                     notification_handler=notification_handler,
                     logger=self._logger,
                 )
@@ -267,6 +268,7 @@ def build_app_server_supervisor_factory(
             restart_backoff_initial_seconds=config.app_server.client.restart_backoff_initial_seconds,
             restart_backoff_max_seconds=config.app_server.client.restart_backoff_max_seconds,
             restart_backoff_jitter_ratio=config.app_server.client.restart_backoff_jitter_ratio,
+            output_policy=config.app_server.output.policy,
         )
 
     return factory

codex_autorunner/integrations/app_server/client.py

@@ -62,6 +62,8 @@ _TURN_STALL_POLL_INTERVAL_SECONDS = 2.0
 _TURN_STALL_RECOVERY_MIN_INTERVAL_SECONDS = 10.0
 _MAX_TURN_RAW_EVENTS = 200
 _INVALID_JSON_PREVIEW_BYTES = 200
+_DEFAULT_OUTPUT_POLICY = "final_only"
+_OUTPUT_POLICIES = {"final_only", "all_agent_messages"}
 
 # Track live clients so tests/cleanup can cancel any background restart tasks.
 _CLIENT_INSTANCES: weakref.WeakSet = weakref.WeakSet()
@@ -108,6 +110,7 @@ class CodexAppServerProtocolError(CodexAppServerError, PermanentError):
 class TurnResult:
     turn_id: str
     status: Optional[str]
+    final_message: str
     agent_messages: list[str]
     errors: list[str]
     raw_events: list[Dict[str, Any]]
@@ -163,6 +166,7 @@ class CodexAppServerClient:
         restart_backoff_initial_seconds: Optional[float] = None,
         restart_backoff_max_seconds: Optional[float] = None,
         restart_backoff_jitter_ratio: Optional[float] = None,
+        output_policy: str = _DEFAULT_OUTPUT_POLICY,
         notification_handler: Optional[NotificationHandler] = None,
         logger: Optional[logging.Logger] = None,
     ) -> None:
@@ -217,6 +221,7 @@ class CodexAppServerClient:
             and restart_backoff_jitter_ratio >= 0
             else _RESTART_BACKOFF_JITTER_RATIO
         )
+        self._output_policy = _normalize_output_policy(output_policy)
 
         self._process: Optional[asyncio.subprocess.Process] = None
         self._reader_task: Optional[asyncio.Task] = None
@@ -558,6 +563,9 @@ class CodexAppServerClient:
             state.future.set_result(
                 TurnResult(
                     turn_id=state.turn_id,
+                    final_message=_final_message_for_result(
+                        state, policy=self._output_policy
+                    ),
                     agent_messages=_agent_messages_for_result(state),
                     errors=list(state.errors),
                     raw_events=list(state.raw_events),
@@ -1269,6 +1277,9 @@ class CodexAppServerClient:
                 TurnResult(
                     turn_id=target.turn_id,
                     status=target.status,
+                    final_message=_final_message_for_result(
+                        target, policy=self._output_policy
+                    ),
                     agent_messages=_agent_messages_for_result(target),
                     errors=list(target.errors),
                     raw_events=list(target.raw_events),
@@ -1366,6 +1377,9 @@ class CodexAppServerClient:
                 TurnResult(
                     turn_id=state.turn_id,
                     status=state.status,
+                    final_message=_final_message_for_result(
+                        state, policy=self._output_policy
+                    ),
                     agent_messages=_agent_messages_for_result(state),
                     errors=list(state.errors),
                     raw_events=list(state.raw_events),
@@ -1701,6 +1715,23 @@ def _agent_messages_for_result(state: _TurnState) -> list[str]:
     return _agent_message_deltas_as_list(state.agent_message_deltas)
 
 
+def _normalize_output_policy(policy: Optional[str]) -> str:
+    candidate = str(policy or "").strip().lower()
+    if candidate in _OUTPUT_POLICIES:
+        return candidate
+    return _DEFAULT_OUTPUT_POLICY
+
+
+def _final_message_for_result(state: _TurnState, *, policy: str) -> str:
+    messages = _agent_messages_for_result(state)
+    cleaned = [msg.strip() for msg in messages if isinstance(msg, str) and msg.strip()]
+    if not cleaned:
+        return ""
+    if policy == "all_agent_messages":
+        return "\n\n".join(cleaned)
+    return cleaned[-1]
+
+
 def _extract_status_value(value: Any) -> Optional[str]:
     if isinstance(value, str):
         return value