shikiru-cli 0.2.0__py3-none-any.whl

shikiru/plugins/agents/codex/__init__.py

@@ -0,0 +1,5 @@
+"""Codex agent plugin."""
+
+from shikiru.plugins.agents.codex.agent import CodexAgent, create
+
+__all__ = ["CodexAgent", "create"]

shikiru/plugins/agents/codex/agent.py

@@ -0,0 +1,486 @@
+"""Codex headless turn plugin."""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from collections.abc import Mapping
+from pathlib import Path
+from typing import TYPE_CHECKING, cast
+
+from pydantic import ValidationError
+
+from shikiru.agents.contracts import (
+    BILLING_SOURCE_OPERATOR_CONFIG,
+    DOCTOR_TIMEOUT_SECONDS,
+    UNKNOWN_BILLING_DECLARATION,
+    BillingDeclaration,
+    CheckResult,
+    ModelCatalog,
+)
+from shikiru.agents.sdk.reset_time import ResetTimeParser
+from shikiru.agents.sdk.turn import StreamingTurn
+from shikiru.clock import from_local
+from shikiru.errors import CommandFailed, ConfigError, ShikiruError
+from shikiru.plugins.agents.codex.headless import CodexHeadless
+from shikiru.plugins.agents.codex.home import codex_home
+from shikiru.plugins.agents.codex.model_catalog import (
+    parse_bundled_context_windows,
+    parse_catalog,
+)
+from shikiru.plugins.agents.codex.options import (
+    CODEX_BUNDLED_MODELS_ARGV,
+    CODEX_COMMAND,
+    CODEX_HOME_ENV_VAR,
+    CODEX_MODEL_CATALOG_ARGV,
+    CODEX_SETTINGS,
+    CONFIG_FLAG,
+    CONFIG_LONG_FLAG,
+    EFFORT_LONG_FLAG,
+    GIT_DIRS_ARGV,
+    GIT_DIRS_TIMEOUT_SECONDS,
+    LOGIN_STATUS_ARGV,
+    MODEL_CATALOG_ARGS_DETAIL,
+    MODEL_CONFIG_OVERRIDE,
+    MODEL_FLAG,
+    MODEL_LONG_FLAG,
+    MODEL_OVERRIDE,
+    NO_DAEMON_FLAG,
+    PROFILE_FLAG,
+    REASONING_EFFORT_CONFIG,
+    RESUME_SUBCOMMAND,
+    TESTED_CODEX_VERSION,
+    VERSION_ARGV,
+    CodexOptions,
+)
+from shikiru.plugins.agents.codex.quota import CodexQuotaProbe
+from shikiru.plugins.agents.codex.sandbox_probe import CodexSandboxProbe
+from shikiru.plugins.agents.codex.turn import CodexTurnSequence, context_window
+from shikiru.plugins.agents.shared_settings import options_error
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from datetime import datetime
+
+    from shikiru.agents.contracts import (
+        AgentContext,
+        HeadlessAgent,
+        QuotaReading,
+        Rung,
+        Turn,
+        TurnSpec,
+    )
+    from shikiru.agents.settings import AgentSetting
+    from shikiru.clock import Clock
+    from shikiru.process import SubprocessRunner
+
+_AUTH_NOT_LOGGED_IN_TEXT = "not logged in"
+_AUTH_LOGGED_IN_TEXTS = ("logged in", "authenticated")
+_CODEX_CONFIG_FILENAME = "config.toml"
+_MODEL_PROVIDER_FIELD = "model_provider"
+_MODEL_PROVIDERS_FIELD = "model_providers"
+_OPENAI_BASE_URL_FIELD = "openai_base_url"
+_PROFILES_FIELD = "profiles"
+_PROFILE_FIELD = "profile"
+_PARTITION_VALUE_INDEX = 2
+_CONTEXT_WINDOW_CHECK = "context_window"
+_UNTESTED_VERSION_DETAIL = "{version} (warning: verified with {tested}; re-check the sandbox probe)"
+_UNKNOWN_WINDOW_DETAIL = (
+    "no positive context window for {models} in models_cache.json or Codex CLI's bundled "
+    "model catalog; compaction at compact_at_pct cannot be applied"
+)
+_MODELS_CACHE_SOURCE = "models_cache.json"
+_BUNDLED_CATALOG_SOURCE = "Codex CLI bundled model catalog"
+_CURRENT_CATALOG_SOURCE = "Codex CLI current model catalog"
+_CUSTOM_PROVIDER_ACCESS_DETAIL = (
+    "custom provider configured; provider credentials are not verified by doctor"
+)
+
+
+class CodexAgent:
+    """Build Codex turn processes and health checks."""
+
+    name = "codex"
+
+    def __init__(self, runner: SubprocessRunner, clock: Clock, options: CodexOptions) -> None:
+        self._runner = runner
+        self._clock = clock
+        self._options = options
+        self._reset_time = ResetTimeParser(clock, resolve_local=from_local)
+        self._billing_declaration = (
+            BillingDeclaration(options.billing_mode, BILLING_SOURCE_OPERATOR_CONFIG)
+            if options.billing_mode is not None
+            else UNKNOWN_BILLING_DECLARATION
+        )
+        self._codex_home = codex_home()
+        self._quota_probe = CodexQuotaProbe(self._codex_home, clock, self._reset_time)
+        self._sandbox_probe = CodexSandboxProbe(runner)
+        self._catalog_context_windows: dict[str, int] = {}
+        self._bundled_context_windows: dict[str, int] = {}
+        self._cached_model_catalog: ModelCatalog | None = None
+
+    @property
+    def billing_declaration(self) -> BillingDeclaration:
+        """Return the explicit plugin option or the unknown declaration."""
+        return self._billing_declaration
+
+    def read_quota(self, since: datetime) -> QuotaReading | None:
+        """Return the newest Codex-bucket reading in this account's rollouts after `since`."""
+        return self._quota_probe.latest_reading(since)
+
+    async def model_catalog(self) -> ModelCatalog:
+        """Return choices from Codex CLI's refreshed current model catalog."""
+        if self._cached_model_catalog is None:
+            self._cached_model_catalog = await self._read_model_catalog()
+        return self._cached_model_catalog
+
+    async def start_turn(self, spec: TurnSpec) -> Turn:
+        """Start one Codex process-per-turn exchange."""
+        model_context_windows = await self._context_windows_for_turn(spec)
+        git_dirs = await self._git_dirs_for_turn(spec)
+        sequence = self.process_sequence(
+            spec, git_dirs=git_dirs, model_context_windows=model_context_windows
+        )
+        return await StreamingTurn.start(spec, self._runner, sequence)
+
+    def process_sequence(
+        self,
+        spec: TurnSpec,
+        *,
+        git_dirs: Sequence[Path],
+        model_context_windows: Mapping[str, int] | None = None,
+    ) -> CodexTurnSequence:
+        """Build Codex's prompt and context-failure retry sequence for `spec`."""
+        home = Path(spec.env.get(CODEX_HOME_ENV_VAR, str(self._codex_home)))
+        return CodexTurnSequence(
+            spec,
+            args=self._options.args,
+            environment=self._turn_environment,
+            clock=self._clock,
+            reset_time=self._reset_time,
+            home=home,
+            git_dirs=git_dirs,
+            compact_at_pct=self._options.compact_at_pct,
+            model_context_windows=(
+                self._bundled_context_windows
+                if model_context_windows is None
+                else model_context_windows
+            ),
+        )
+
+    def interactive_command(self, session_id: str, run_dir: Path, rung: Rung) -> Sequence[str]:
+        """Return Codex's interactive resume command for a headless session and rung."""
+        del run_dir
+        argv = [
+            CODEX_COMMAND,
+            RESUME_SUBCOMMAND,
+            NO_DAEMON_FLAG,
+            session_id,
+            MODEL_FLAG,
+            rung.model,
+        ]
+        if rung.effort is not None:
+            argv.extend((CONFIG_FLAG, f'{REASONING_EFFORT_CONFIG}="{rung.effort}"'))
+        argv.extend(self._options.args)
+        return tuple(argv)
+
+    async def doctor(self, models: Sequence[str]) -> list[CheckResult]:
+        """Check Codex's binary, version, native access and each model's context window."""
+        binary = await self._check_binary()
+        if not binary.ok:
+            unavailable = "binary unavailable"
+            return [
+                binary,
+                CheckResult("version", False, unavailable),
+                CheckResult("login", False, unavailable),
+            ]
+        checks = [
+            binary,
+            await self._check_version(),
+            await self._check_login(),
+            await self._sandbox_probe.check(),
+        ]
+        if models:
+            checks.append(await self._check_context_windows(models))
+        return checks
+
+    async def _check_context_windows(self, models: Sequence[str]) -> CheckResult:
+        cached_windows = {model: context_window(self._codex_home, model) for model in models}
+        missing_from_catalog = [
+            model
+            for model, window in cached_windows.items()
+            if window is None and model not in self._catalog_context_windows
+        ]
+        if missing_from_catalog:
+            catalog_result = await self._read_bundled_model_catalog(missing_from_catalog)
+            if isinstance(catalog_result, CheckResult):
+                return catalog_result
+            self._bundled_context_windows = catalog_result
+            self._catalog_context_windows.update(catalog_result)
+        windows = {
+            model: cached_windows[model]
+            if cached_windows[model] is not None
+            else self._catalog_context_windows.get(model)
+            for model in models
+        }
+        unknown = [model for model, window in windows.items() if window is None]
+        if unknown:
+            return CheckResult(
+                _CONTEXT_WINDOW_CHECK,
+                False,
+                _UNKNOWN_WINDOW_DETAIL.format(models=", ".join(unknown)),
+            )
+        known_parts: list[str] = []
+        for model, window in windows.items():
+            if cached_windows[model] is not None:
+                source = _MODELS_CACHE_SOURCE
+            elif model in self._bundled_context_windows:
+                source = _BUNDLED_CATALOG_SOURCE
+            else:
+                source = _CURRENT_CATALOG_SOURCE
+            known_parts.append(f"{model}: {window} ({source})")
+        known = ", ".join(known_parts)
+        return CheckResult(_CONTEXT_WINDOW_CHECK, True, known)
+
+    async def _read_model_catalog(self) -> ModelCatalog:
+        if _model_catalog_args_are_ambiguous(self._options.args):
+            return ModelCatalog(error=MODEL_CATALOG_ARGS_DETAIL)
+        return await self._query_model_catalog()
+
+    async def _query_model_catalog(self) -> ModelCatalog:
+        try:
+            result = await self._runner.run(
+                CODEX_MODEL_CATALOG_ARGV,
+                timeout=DOCTOR_TIMEOUT_SECONDS,
+                env=self._subprocess_environment(),
+                check=False,
+            )
+        except (FileNotFoundError, ShikiruError) as error:
+            detail = str(error) or type(error).__name__
+            return ModelCatalog(error=f"could not read Codex CLI's current model catalog: {detail}")
+        if result.returncode != 0:
+            detail = result.stderr.strip() or "no diagnostic output"
+            return ModelCatalog(
+                error=(
+                    f"Codex CLI's current model catalog command failed with exit code "
+                    f"{result.returncode}: {detail}"
+                )
+            )
+        try:
+            choices, windows = parse_catalog(result.stdout)
+        except TypeError as error:
+            return ModelCatalog(error=f"could not parse Codex CLI's current model catalog: {error}")
+        self._catalog_context_windows.update(windows)
+        return ModelCatalog(models=choices, complete=True)
+
+    async def _read_bundled_model_catalog(
+        self,
+        models: Sequence[str],
+        *,
+        environment: Mapping[str, str] | None = None,
+    ) -> dict[str, int] | CheckResult:
+        model_names = ", ".join(models)
+        try:
+            result = await self._runner.run(
+                CODEX_BUNDLED_MODELS_ARGV,
+                timeout=DOCTOR_TIMEOUT_SECONDS,
+                env=(self._subprocess_environment() if environment is None else environment),
+                check=False,
+            )
+        except (FileNotFoundError, ShikiruError) as error:
+            return CheckResult(
+                _CONTEXT_WINDOW_CHECK,
+                False,
+                f"could not read Codex CLI's bundled model catalog for {model_names}: {error}",
+            )
+        if result.returncode != 0:
+            detail = result.stderr.strip() or result.stdout.strip()
+            return CheckResult(
+                _CONTEXT_WINDOW_CHECK,
+                False,
+                f"Codex CLI's bundled model catalog command failed for {model_names} with exit "
+                f"code {result.returncode}: {detail or 'no diagnostic output'}",
+            )
+        try:
+            return parse_bundled_context_windows(result.stdout)
+        except TypeError as error:
+            return CheckResult(
+                _CONTEXT_WINDOW_CHECK,
+                False,
+                f"could not parse Codex CLI's bundled model catalog for {model_names}: {error}",
+            )
+
+    async def _context_windows_for_turn(self, spec: TurnSpec) -> Mapping[str, int]:
+        home = Path(spec.env.get(CODEX_HOME_ENV_VAR, str(self._codex_home)))
+        model = spec.rung.model
+        if context_window(home, model, spec.session_id) is not None:
+            return self._bundled_context_windows
+        if model in self._bundled_context_windows:
+            return self._bundled_context_windows
+        catalog = await self._read_bundled_model_catalog(
+            (model,), environment=self._turn_environment(spec)
+        )
+        if isinstance(catalog, CheckResult):
+            raise ConfigError(catalog.detail)
+        self._bundled_context_windows = catalog
+        if model not in catalog:
+            raise ConfigError(_UNKNOWN_WINDOW_DETAIL.format(models=model))
+        return catalog
+
+    def settings(self) -> tuple[AgentSetting, ...]:
+        """Return the options worth writing to the project config."""
+        return CODEX_SETTINGS
+
+    def headless(self) -> HeadlessAgent | None:
+        """Return Codex's schema-constrained headless client."""
+        return CodexHeadless(self._runner, self._subprocess_environment())
+
+    def _subprocess_environment(self) -> dict[str, str]:
+        return dict(os.environ)
+
+    def _turn_environment(self, spec: TurnSpec) -> dict[str, str]:
+        environment = dict(os.environ)
+        environment.update(spec.env)
+        return environment
+
+    async def _git_dirs_for_turn(self, spec: TurnSpec) -> tuple[Path, ...]:
+        result = await self._runner.run(
+            GIT_DIRS_ARGV,
+            timeout=GIT_DIRS_TIMEOUT_SECONDS,
+            cwd=spec.cwd,
+            check=False,
+        )
+        values = result.stdout.split()
+        if result.returncode != 0 or not values:
+            message = (
+                f"could not resolve the Codex workspace git directories: {result.stderr.strip()}"
+            )
+            raise ConfigError(message)
+        return tuple(Path(value) for value in values)
+
+    async def _check_binary(self) -> CheckResult:
+        try:
+            result = await self._runner.run(
+                VERSION_ARGV,
+                timeout=DOCTOR_TIMEOUT_SECONDS,
+                env=self._subprocess_environment(),
+                check=False,
+            )
+        except (FileNotFoundError, CommandFailed, ShikiruError) as error:
+            return CheckResult("binary", False, str(error))
+        if result.returncode != 0:
+            return CheckResult("binary", False, result.stderr.strip())
+        return CheckResult("binary", True, CODEX_COMMAND)
+
+    async def _check_version(self) -> CheckResult:
+        try:
+            result = await self._runner.run(
+                VERSION_ARGV,
+                timeout=DOCTOR_TIMEOUT_SECONDS,
+                env=self._subprocess_environment(),
+                check=False,
+            )
+        except (FileNotFoundError, ShikiruError) as error:
+            return CheckResult("version", False, str(error))
+        detail = result.stdout.strip() or result.stderr.strip()
+        if result.returncode == 0 and TESTED_CODEX_VERSION not in detail:
+            detail = _UNTESTED_VERSION_DETAIL.format(version=detail, tested=TESTED_CODEX_VERSION)
+        return CheckResult("version", result.returncode == 0, detail)
+
+    async def _check_login(self) -> CheckResult:
+        configured_provider = _custom_provider_check(self._codex_home)
+        if configured_provider is not None:
+            return configured_provider
+        try:
+            result = await self._runner.run(
+                LOGIN_STATUS_ARGV,
+                timeout=DOCTOR_TIMEOUT_SECONDS,
+                env=self._subprocess_environment(),
+                check=False,
+            )
+        except (FileNotFoundError, ShikiruError) as error:
+            return CheckResult("login", False, str(error))
+        lowered = f"{result.stdout}\n{result.stderr}".lower()
+        logged_in = (
+            result.returncode == 0
+            and _AUTH_NOT_LOGGED_IN_TEXT not in lowered
+            and any(text in lowered for text in _AUTH_LOGGED_IN_TEXTS)
+        )
+        detail = "authenticated" if logged_in else "not authenticated"
+        return CheckResult("login", logged_in, detail)
+
+
+def _custom_provider_check(home: Path) -> CheckResult | None:
+    path = home / _CODEX_CONFIG_FILENAME
+    if not path.is_file():
+        return None
+    try:
+        config = cast("Mapping[str, object]", tomllib.loads(path.read_text(encoding="utf-8")))
+    except (OSError, tomllib.TOMLDecodeError) as error:
+        return CheckResult("login", False, f"could not inspect Codex config: {error}")
+    profile_name = config.get(_PROFILE_FIELD)
+    profiles_value = config.get(_PROFILES_FIELD)
+    profiles: Mapping[str, object] = (
+        cast("Mapping[str, object]", profiles_value) if isinstance(profiles_value, Mapping) else {}
+    )
+    profile_value: object | None = (
+        profiles.get(profile_name) if isinstance(profile_name, str) else None
+    )
+    profile: Mapping[str, object] = (
+        cast("Mapping[str, object]", profile_value) if isinstance(profile_value, Mapping) else {}
+    )
+    provider_name: object = profile.get(_MODEL_PROVIDER_FIELD, config.get(_MODEL_PROVIDER_FIELD))
+    providers_value = config.get(_MODEL_PROVIDERS_FIELD)
+    providers: Mapping[str, object] = (
+        cast("Mapping[str, object]", providers_value)
+        if isinstance(providers_value, Mapping)
+        else {}
+    )
+    custom_provider = isinstance(provider_name, str) and isinstance(
+        providers.get(provider_name), Mapping
+    )
+    base_url: object = profile.get(_OPENAI_BASE_URL_FIELD, config.get(_OPENAI_BASE_URL_FIELD))
+    custom_base_url = isinstance(base_url, str) and bool(base_url.strip())
+    if custom_provider or custom_base_url:
+        return CheckResult("login", True, _CUSTOM_PROVIDER_ACCESS_DETAIL)
+    return None
+
+
+def _model_catalog_args_are_ambiguous(args: Sequence[str]) -> bool:
+    return any(
+        _catalog_argument_is_ambiguous(args, index, argument) for index, argument in enumerate(args)
+    )
+
+
+def _catalog_argument_is_ambiguous(args: Sequence[str], index: int, argument: str) -> bool:
+    selector_flags = (MODEL_FLAG, MODEL_LONG_FLAG, EFFORT_LONG_FLAG, PROFILE_FLAG)
+    selector_prefixes = (f"{MODEL_LONG_FLAG}=", f"{PROFILE_FLAG}=", f"{EFFORT_LONG_FLAG}=")
+    if argument in selector_flags or argument.startswith(selector_prefixes):
+        return True
+    if argument.startswith(MODEL_FLAG) and argument != MODEL_FLAG:
+        return True
+    if argument in (CONFIG_FLAG, CONFIG_LONG_FLAG):
+        return _config_override_is_ambiguous(args, index + 1)
+    if argument.startswith(f"{CONFIG_LONG_FLAG}="):
+        return _config_value_is_ambiguous(argument.partition("=")[_PARTITION_VALUE_INDEX])
+    if argument.startswith(CONFIG_FLAG) and argument != CONFIG_FLAG:
+        return _config_value_is_ambiguous(argument[len(CONFIG_FLAG) :])
+    return False
+
+
+def _config_override_is_ambiguous(args: Sequence[str], index: int) -> bool:
+    return index >= len(args) or _config_value_is_ambiguous(args[index])
+
+
+def _config_value_is_ambiguous(value: str) -> bool:
+    key = value.partition("=")[0].strip()
+    return key in (MODEL_CONFIG_OVERRIDE, MODEL_OVERRIDE, REASONING_EFFORT_CONFIG)
+
+
+def create(context: AgentContext) -> CodexAgent:
+    """Build the Codex plugin from validated `AgentContext.options`."""
+    try:
+        options = CodexOptions.model_validate(context.options)
+    except ValidationError as error:
+        raise options_error(CODEX_COMMAND, error) from error
+    return CodexAgent(context.runner, context.clock, options)

shikiru/plugins/agents/codex/headless.py

@@ -0,0 +1,166 @@
+"""Codex schema-constrained one-shot calls."""
+
+from __future__ import annotations
+
+import json
+import tempfile
+from collections.abc import Mapping
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, cast
+
+from shikiru.errors import HeadlessOutputError
+from shikiru.plugins.agents.codex.options import (
+    CODEX_COMMAND,
+    CONFIG_FLAG,
+    EPHEMERAL_FLAG,
+    EXEC_SUBCOMMAND,
+    JSON_FLAG,
+    MODEL_FLAG,
+    OUTPUT_SCHEMA_FLAG,
+    READ_ONLY_SANDBOX,
+    REASONING_EFFORT_CONFIG,
+    SANDBOX_FLAG,
+    SKIP_GIT_REPO_CHECK_FLAG,
+)
+
+if TYPE_CHECKING:
+    from datetime import timedelta
+
+    from shikiru.process import SubprocessRunner
+
+_AGENT_MESSAGE_TYPE = "agent_message"
+_ITEM_COMPLETED_TYPE = "item.completed"
+_TYPE_FIELD = "type"
+_ITEM_FIELD = "item"
+_TEXT_FIELD = "text"
+_CONTENT_FIELD = "content"
+_SCHEMA_TYPE_FIELD = "type"
+_OBJECT_TYPE = "object"
+_ADDITIONAL_PROPERTIES_FIELD = "additionalProperties"
+_STRICT_SCHEMA_VALUE = False
+_INVALID_JSON_MESSAGE = "Codex headless output was not valid JSON"
+_INVALID_OBJECT_MESSAGE = "Codex headless output was not an object"
+_MISSING_AGENT_MESSAGE = "Codex headless output had no agent_message"
+_STDIN_LINE_ENDING = "\n"
+
+
+class CodexHeadless:
+    """Runs Codex's ephemeral JSON structured-output mode."""
+
+    def __init__(self, runner: SubprocessRunner, environment: Mapping[str, str]) -> None:
+        """Use `runner` and the Operator-provided environment."""
+        self._runner = runner
+        self._environment = dict(environment)
+
+    async def ask(
+        self,
+        prompt: str,
+        schema: Mapping[str, Any],
+        model: str,
+        effort: str | None,
+        cwd: Path,
+        timeout: timedelta,
+    ) -> Mapping[str, Any]:
+        """Return Codex's schema-constrained final `agent_message` value."""
+        with tempfile.TemporaryDirectory(prefix="shikiru-codex-") as directory:
+            schema_path = Path(directory) / "output-schema.json"
+            schema_path.write_text(
+                json.dumps(_strict_schema(schema), separators=(",", ":")), encoding="utf-8"
+            )
+            argv = [
+                CODEX_COMMAND,
+                EXEC_SUBCOMMAND,
+                EPHEMERAL_FLAG,
+                JSON_FLAG,
+                OUTPUT_SCHEMA_FLAG,
+                str(schema_path),
+                MODEL_FLAG,
+                model,
+            ]
+            if effort is not None:
+                argv.extend([CONFIG_FLAG, f'{REASONING_EFFORT_CONFIG}="{effort}"'])
+            argv.extend(
+                [
+                    SANDBOX_FLAG,
+                    READ_ONLY_SANDBOX,
+                    SKIP_GIT_REPO_CHECK_FLAG,
+                ]
+            )
+            result = await self._runner.run(
+                argv,
+                timeout=timeout.total_seconds(),
+                cwd=cwd,
+                env=self._environment,
+                input_text=prompt
+                if prompt.endswith(_STDIN_LINE_ENDING)
+                else prompt + _STDIN_LINE_ENDING,
+                check=True,
+            )
+        return _parse_agent_message(result.stdout)
+
+
+def _strict_schema(value: object) -> object:
+    if isinstance(value, Mapping):
+        typed_value = cast("Mapping[str, object]", value)
+        schema = {key: _strict_schema(item) for key, item in typed_value.items()}
+        if schema.get(_SCHEMA_TYPE_FIELD) == _OBJECT_TYPE:
+            schema.setdefault(_ADDITIONAL_PROPERTIES_FIELD, _STRICT_SCHEMA_VALUE)
+        return schema
+    if isinstance(value, list):
+        return [_strict_schema(item) for item in cast("list[object]", value)]
+    return value
+
+
+def _parse_agent_message(stdout: str) -> Mapping[str, Any]:
+    final_message: str | None = None
+    for line in stdout.splitlines():
+        try:
+            raw = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if not isinstance(raw, Mapping):
+            continue
+        payload = cast("Mapping[str, Any]", raw)
+        message = _message_from_payload(payload)
+        if message is None:
+            continue
+        final_message = message
+    if final_message is None:
+        raise HeadlessOutputError(_MISSING_AGENT_MESSAGE)
+    try:
+        decoded = json.loads(final_message)
+    except json.JSONDecodeError as error:
+        raise HeadlessOutputError(_INVALID_JSON_MESSAGE) from error
+    if not isinstance(decoded, Mapping):
+        raise HeadlessOutputError(_INVALID_OBJECT_MESSAGE)
+    return cast("Mapping[str, Any]", decoded)
+
+
+def _message_from_payload(payload: Mapping[str, Any]) -> str | None:
+    if payload.get(_TYPE_FIELD) != _ITEM_COMPLETED_TYPE:
+        return None
+    item = payload.get(_ITEM_FIELD)
+    if isinstance(item, Mapping):
+        typed_item = cast("Mapping[str, Any]", item)
+        if typed_item.get(_TYPE_FIELD) == _AGENT_MESSAGE_TYPE:
+            return _text(typed_item)
+    return None
+
+
+def _text(payload: Mapping[str, Any]) -> str | None:
+    value = payload.get(_TEXT_FIELD)
+    if isinstance(value, str):
+        return value
+    content = payload.get(_CONTENT_FIELD)
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts: list[str] = []
+        for item in cast("list[object]", content):
+            if isinstance(item, Mapping):
+                part = cast("Mapping[str, Any]", item).get(_TEXT_FIELD)
+                if isinstance(part, str):
+                    parts.append(part)
+        text = "".join(parts)
+        return text or None
+    return None

shikiru/plugins/agents/codex/home.py

@@ -0,0 +1,14 @@
+"""Codex's local session data directory."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from shikiru.plugins.agents.codex.options import CODEX_HOME_ENV_VAR
+
+
+def codex_home() -> Path:
+    """Return the Codex home used for rollout discovery."""
+    configured = os.environ.get(CODEX_HOME_ENV_VAR)
+    return Path(configured) if configured else Path.home() / ".codex"