ouroboros-ai 0.42.2.dev2__tar.gz → 0.42.2.dev4__tar.gz

{ouroboros_ai-0.42.2.dev2 → ouroboros_ai-0.42.2.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.42.2.dev2
+Version: 0.42.2.dev4
 Summary: Specification-first workflow engine for AI coding agents. Works with Claude Code and Codex CLI.
 Author-email: Q00 <jqyu.lee@gmail.com>
 License-File: LICENSE

{ouroboros_ai-0.42.2.dev2 → ouroboros_ai-0.42.2.dev4}/src/ouroboros/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.42.2.dev2'
-__version_tuple__ = version_tuple = (0, 42, 2, 'dev2')
+__version__ = version = '0.42.2.dev4'
+__version_tuple__ = version_tuple = (0, 42, 2, 'dev4')
 
 __commit_id__ = commit_id = None

{ouroboros_ai-0.42.2.dev2 → ouroboros_ai-0.42.2.dev4}/src/ouroboros/config/__init__.py

@@ -29,6 +29,7 @@ from ouroboros.config.loader import (
     credentials_file_secure,
     ensure_config_dir,
     get_agent_permission_mode,
+    get_agent_reasoning_effort,
     get_agent_runtime_backend,
     get_assertion_extraction_model,
     get_clarification_model,
@@ -127,6 +128,7 @@ __all__ = [
     "credentials_file_secure",
     "get_agent_runtime_backend",
     "get_agent_permission_mode",
+    "get_agent_reasoning_effort",
     "get_assertion_extraction_model",
     "get_llm_backend",
     "get_llm_backend_for_role",

{ouroboros_ai-0.42.2.dev2 → ouroboros_ai-0.42.2.dev4}/src/ouroboros/config/loader.py

@@ -248,9 +248,20 @@ _UNTRUSTED_ENV_DENYLIST = frozenset(
         # is therefore an approval-gate-bypass sink — same class as the
         # permission-mode overrides above.
         "OUROBOROS_TOOL_CAPABILITIES",
+        # Execution-cost/behavior dial — an untrusted repo .env must not be able
+        # to force a higher (or invalid) reasoning-effort level for every AC,
+        # which changes runtime cost and behavior. Follows the same trusted-source
+        # policy as the runtime/permission overrides above (RFC #1405).
+        "OUROBOROS_AGENT_REASONING_EFFORT",
     }
 )
 
+# The reasoning-effort vocabulary every native runtime accepts (mirrors
+# OrchestratorConfig.reasoning_effort). A value outside this set — Codex-only
+# ``minimal``, Claude-only ``max``, or a typo — must never reach a runtime, so the
+# env override is validated against it before use.
+_VALID_REASONING_EFFORT_LEVELS = frozenset({"low", "medium", "high", "xhigh"})
+
 
 def _is_untrusted_env_denied_key(key: str) -> bool:
     """Return whether an untrusted .env key may alter execution routing."""
@@ -755,6 +766,31 @@ def get_agent_permission_mode(backend: str | None = None) -> str:
         return "bypassPermissions" if _uses_opencode_backend(backend) else "acceptEdits"
 
 
+def get_agent_reasoning_effort() -> str | None:
+    """Get the base reasoning-effort level for AC execution (RFC #1405).
+
+    Priority:
+        1. OUROBOROS_AGENT_REASONING_EFFORT environment variable
+        2. config.yaml orchestrator.reasoning_effort
+        3. None (effort routing stays dormant — no behavior change)
+
+    The env override is validated against the native-shared vocabulary; an invalid
+    value is ignored (falls through to config) rather than forwarded to a runtime
+    that would reject it. From an untrusted project ``.env`` the key is denylisted
+    entirely, so it is only honored from a trusted source.
+    """
+    env_effort = os.environ.get("OUROBOROS_AGENT_REASONING_EFFORT", "").strip()
+    if env_effort in _VALID_REASONING_EFFORT_LEVELS:
+        return env_effort
+    # A set but invalid env value (Codex-only ``minimal``, Claude-only ``max``, or a
+    # typo) is dropped rather than forwarded to a runtime that would reject it; fall
+    # through to the schema-validated config value.
+    try:
+        return load_config().orchestrator.reasoning_effort
+    except ConfigError:
+        return None
+
+
 def _parse_max_parallel_workers(value: Any, *, config_key: str) -> int:
     """Parse a worker-cap setting without validating unrelated config keys."""
     if isinstance(value, bool):

{ouroboros_ai-0.42.2.dev2 → ouroboros_ai-0.42.2.dev4}/src/ouroboros/config/models.py

@@ -511,6 +511,14 @@ class OrchestratorConfig(BaseModel, frozen=True):
     opencode_permission_mode: Literal["default", "acceptEdits", "bypassPermissions"] = (
         "bypassPermissions"
     )
+    # Effort-first investment dial (RFC #1405): base reasoning-effort level for
+    # full-strength AC execution. Decomposed children run one notch lower. The
+    # level is ENFORCED on runtimes with a native per-call knob (Claude Agent SDK,
+    # Codex) and advised elsewhere. ``None`` leaves effort routing dormant.
+    # Restricted to the vocabulary every native runtime accepts: Codex-only
+    # ``minimal`` and Claude-only ``max`` are excluded so a single global value is
+    # never forwarded as an invalid level to whichever runtime executes the AC.
+    reasoning_effort: Literal["low", "medium", "high", "xhigh"] | None = None
     # OpenCode integration mode. Written by `ouroboros setup --opencode-mode`.
     # None = unset (legacy installs); gate treats None as NOT plugin (safe
     # default — require explicit opt-in via setup --opencode-mode=plugin).

{ouroboros_ai-0.42.2.dev2 → ouroboros_ai-0.42.2.dev4}/src/ouroboros/orchestrator/parallel_executor.py

@@ -5535,6 +5535,39 @@ Files present:
                 effort_mode=effort_decision.mode,
                 backend=getattr(self._adapter, "runtime_backend", None),
             )
+            # Record the routing decision as a first-class, queryable event so the
+            # frugality proof can join per-AC (effort_level x effort_mode) against
+            # token attribution and the TraceGuard verdict. Only ``enforced`` rows
+            # count toward the deterministic proof; advised rows are recorded but
+            # excluded — which is exactly the distinction effort_mode carries here.
+            #
+            # This is auxiliary proof telemetry, not a runtime dependency: route it
+            # through ``_safe_emit_event`` so a degraded event store degrades to a
+            # warning (matching the adjacent observe-only executor events) instead of
+            # aborting the AC before runtime dispatch. ``execution_context_id``
+            # (execution_id or session_id) keeps the payload scope aligned with the
+            # aggregate id even on direct/fallback callers that pass no execution_id.
+            from ouroboros.events.base import BaseEvent
+
+            await self._safe_emit_event(
+                BaseEvent(
+                    type="execution.ac.effort_routed",
+                    aggregate_type=runtime_identity.runtime_scope.aggregate_type,
+                    aggregate_id=runtime_identity.session_scope_id,
+                    data={
+                        **runtime_identity.to_metadata(),
+                        "ac_id": runtime_identity.ac_id,
+                        "execution_id": execution_context_id,
+                        "session_id": session_id,
+                        "ac_index": ac_index,
+                        "is_decomposed_child": is_sub_ac,
+                        "effort_level": effort_decision.level,
+                        "effort_mode": effort_decision.mode,
+                        "base_reasoning_effort": self._reasoning_effort,
+                        "runtime_backend": getattr(self._adapter, "runtime_backend", None),
+                    },
+                )
+            )
         # Only forward the level to runtimes that ENFORCE it (declared NATIVE and
         # thus accept the kwarg — Claude SDK, Codex). Advised runtimes ignore it
         # anyway and do not accept the parameter, so passing it would break them;

{ouroboros_ai-0.42.2.dev2 → ouroboros_ai-0.42.2.dev4}/src/ouroboros/orchestrator/runner.py

@@ -2827,6 +2827,8 @@ class OrchestratorRunner:
             )
 
         # Execute in parallel
+        from ouroboros.config import get_agent_reasoning_effort
+
         parallel_executor = ParallelACExecutor(
             adapter=self._adapter,
             event_store=self._event_store,
@@ -2839,6 +2841,7 @@ class OrchestratorRunner:
             checkpoint_store=self._checkpoint_store,
             execution_profile=execution_profile,
             fat_harness_mode=self._fat_harness_mode,
+            reasoning_effort=get_agent_reasoning_effort(),
         )
 
         # Check for cancellation before starting parallel execution

{ouroboros_ai-0.42.2.dev2 → ouroboros_ai-0.42.2.dev4}/tests/unit/config/test_loader.py

@@ -1845,3 +1845,70 @@ def test_get_goose_cli_path_ignores_stale_env_and_config(
         patch("ouroboros.config.loader.shutil.which", return_value=None),
     ):
         assert get_goose_cli_path() is None
+
+
+class TestGetAgentReasoningEffort:
+    """Env/config resolution + validation for the RFC #1405 effort dial."""
+
+    def test_valid_env_overrides_config(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        from ouroboros.config.loader import get_agent_reasoning_effort
+
+        monkeypatch.setenv("OUROBOROS_AGENT_REASONING_EFFORT", "high")
+        with patch(
+            "ouroboros.config.loader.load_config",
+            return_value=OuroborosConfig(orchestrator=OrchestratorConfig(reasoning_effort="low")),
+        ):
+            assert get_agent_reasoning_effort() == "high"
+
+    def test_invalid_env_is_ignored_and_falls_back_to_config(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        # Codex-only ``minimal`` is invalid for the native-shared global dial and
+        # must never be forwarded to a runtime; fall through to the config value.
+        from ouroboros.config.loader import get_agent_reasoning_effort
+
+        monkeypatch.setenv("OUROBOROS_AGENT_REASONING_EFFORT", "minimal")
+        with patch(
+            "ouroboros.config.loader.load_config",
+            return_value=OuroborosConfig(
+                orchestrator=OrchestratorConfig(reasoning_effort="medium")
+            ),
+        ):
+            assert get_agent_reasoning_effort() == "medium"
+
+    def test_garbage_env_is_ignored(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        from ouroboros.config.loader import get_agent_reasoning_effort
+
+        monkeypatch.setenv("OUROBOROS_AGENT_REASONING_EFFORT", "turbo")
+        with patch(
+            "ouroboros.config.loader.load_config",
+            return_value=OuroborosConfig(orchestrator=OrchestratorConfig()),
+        ):
+            assert get_agent_reasoning_effort() is None
+
+    def test_config_value_used_when_no_env(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        from ouroboros.config.loader import get_agent_reasoning_effort
+
+        monkeypatch.delenv("OUROBOROS_AGENT_REASONING_EFFORT", raising=False)
+        with patch(
+            "ouroboros.config.loader.load_config",
+            return_value=OuroborosConfig(orchestrator=OrchestratorConfig(reasoning_effort="xhigh")),
+        ):
+            assert get_agent_reasoning_effort() == "xhigh"
+
+    def test_dormant_by_default(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        from ouroboros.config.loader import get_agent_reasoning_effort
+
+        monkeypatch.delenv("OUROBOROS_AGENT_REASONING_EFFORT", raising=False)
+        with patch(
+            "ouroboros.config.loader.load_config",
+            return_value=OuroborosConfig(orchestrator=OrchestratorConfig()),
+        ):
+            assert get_agent_reasoning_effort() is None
+
+    def test_minimal_rejected_by_config_schema(self) -> None:
+        # The global dial is restricted to the native-shared vocabulary.
+        import pydantic
+
+        with pytest.raises(pydantic.ValidationError):
+            OrchestratorConfig(reasoning_effort="minimal")

{ouroboros_ai-0.42.2.dev2 → ouroboros_ai-0.42.2.dev4}/tests/unit/config/test_loader_env.py

@@ -118,6 +118,8 @@ def test_denylist_covers_known_execution_routing_keys() -> None:
         "OUROBOROS_RUNTIME_PROFILE",
         "OUROBOROS_AGENT_PERMISSION_MODE",
         "OUROBOROS_TOOL_CAPABILITIES",
+        # Execution-cost/behavior dial — must not be forced from an untrusted repo.
+        "OUROBOROS_AGENT_REASONING_EFFORT",
     }
     missing = required - _UNTRUSTED_ENV_DENYLIST
     assert not missing, f"denylist regressed, missing: {sorted(missing)}"

ouroboros_ai-0.42.2.dev4/tests/unit/orchestrator/test_effort_routed_event.py

@@ -0,0 +1,245 @@
+"""The effort-routing decision is emitted as a queryable event.
+
+The deterministic frugality proof reads ``execution.ac.effort_routed`` events to
+join per-AC (effort_level x effort_mode) with token attribution and the TraceGuard
+verdict. Only ``enforced`` rows count toward the proof, so the event must carry the
+honest mode — that is what these tests pin.
+"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from datetime import UTC, datetime
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from ouroboros.orchestrator.adapter import (
+    FULL_CAPABILITIES,
+    AgentMessage,
+    ParamSupport,
+    RuntimeHandle,
+)
+from ouroboros.orchestrator.parallel_executor import ParallelACExecutor
+
+
+def _capturing_event_store() -> tuple[AsyncMock, list]:
+    store = AsyncMock()
+    events: list = []
+
+    async def _append(event):
+        events.append(event)
+
+    store.append.side_effect = _append
+    return store, events
+
+
+class _EnforcedRuntime:
+    """A runtime that declares NATIVE effort support and accepts the kwarg."""
+
+    _runtime_handle_backend = "claude"
+
+    def __init__(self) -> None:
+        self.received_effort: str | None = "UNSET"
+
+    @property
+    def runtime_backend(self) -> str:
+        return self._runtime_handle_backend
+
+    @property
+    def working_directory(self) -> str | None:
+        return "/tmp/project"
+
+    @property
+    def permission_mode(self) -> str | None:
+        return "acceptEdits"
+
+    @property
+    def capabilities(self):
+        return replace(FULL_CAPABILITIES, reasoning_effort_support=ParamSupport.NATIVE)
+
+    async def execute_task(
+        self,
+        prompt: str,
+        tools: list[str] | None = None,
+        system_prompt: str | None = None,
+        resume_handle: RuntimeHandle | None = None,
+        resume_session_id: str | None = None,
+        reasoning_effort: str | None = None,
+    ):
+        self.received_effort = reasoning_effort
+        yield AgentMessage(
+            type="result",
+            content="[TASK_COMPLETE]",
+            data={"subtype": "success"},
+            resume_handle=resume_handle,
+        )
+
+
+class _AdvisedRuntime:
+    """A runtime with no capability declaration and no effort kwarg (the default)."""
+
+    _runtime_handle_backend = "opencode"
+
+    @property
+    def runtime_backend(self) -> str:
+        return self._runtime_handle_backend
+
+    @property
+    def working_directory(self) -> str | None:
+        return "/tmp/project"
+
+    @property
+    def permission_mode(self) -> str | None:
+        return "acceptEdits"
+
+    async def execute_task(
+        self,
+        prompt: str,
+        tools: list[str] | None = None,
+        system_prompt: str | None = None,
+        resume_handle: RuntimeHandle | None = None,
+        resume_session_id: str | None = None,
+    ):
+        yield AgentMessage(
+            type="result",
+            content="[TASK_COMPLETE]",
+            data={"subtype": "success"},
+            resume_handle=resume_handle,
+        )
+
+
+def _effort_events(events: list) -> list:
+    return [e for e in events if getattr(e, "type", None) == "execution.ac.effort_routed"]
+
+
+async def _run_one_ac(executor: ParallelACExecutor, *, is_sub_ac: bool):
+    return await executor._execute_atomic_ac(
+        ac_index=1,
+        ac_content="Implement a thing",
+        session_id="sess_effort",
+        tools=["Read"],
+        system_prompt="system",
+        seed_goal="Ship it",
+        depth=0,
+        start_time=datetime.now(UTC),
+        execution_id="exec_effort",
+        is_sub_ac=is_sub_ac,
+        parent_ac_index=0 if is_sub_ac else None,
+        sub_ac_index=0 if is_sub_ac else None,
+    )
+
+
+@pytest.mark.asyncio
+async def test_enforced_runtime_emits_enforced_event_and_passes_kwarg() -> None:
+    store, events = _capturing_event_store()
+    runtime = _EnforcedRuntime()
+    executor = ParallelACExecutor(
+        adapter=runtime,
+        event_store=store,
+        console=MagicMock(),
+        enable_decomposition=False,
+        reasoning_effort="high",
+    )
+
+    await _run_one_ac(executor, is_sub_ac=False)
+
+    routed = _effort_events(events)
+    assert len(routed) == 1
+    assert routed[0].data["effort_mode"] == "enforced"
+    assert routed[0].data["effort_level"] == "high"
+    # NATIVE runtime actually received the level.
+    assert runtime.received_effort == "high"
+
+
+@pytest.mark.asyncio
+async def test_decomposed_child_runs_one_notch_lower() -> None:
+    store, events = _capturing_event_store()
+    runtime = _EnforcedRuntime()
+    executor = ParallelACExecutor(
+        adapter=runtime,
+        event_store=store,
+        console=MagicMock(),
+        enable_decomposition=False,
+        reasoning_effort="high",
+    )
+
+    await _run_one_ac(executor, is_sub_ac=True)
+
+    routed = _effort_events(events)
+    assert routed[0].data["effort_level"] == "medium"  # high -> one notch lower
+    assert routed[0].data["is_decomposed_child"] is True
+    assert runtime.received_effort == "medium"
+
+
+@pytest.mark.asyncio
+async def test_advised_runtime_records_advised_and_does_not_pass_kwarg() -> None:
+    store, events = _capturing_event_store()
+    runtime = _AdvisedRuntime()  # no capabilities, no effort kwarg
+    executor = ParallelACExecutor(
+        adapter=runtime,
+        event_store=store,
+        console=MagicMock(),
+        enable_decomposition=False,
+        reasoning_effort="high",
+    )
+
+    # Must not raise even though execute_task has no reasoning_effort parameter.
+    await _run_one_ac(executor, is_sub_ac=False)
+
+    routed = _effort_events(events)
+    assert len(routed) == 1
+    assert routed[0].data["effort_mode"] == "advised"
+    assert routed[0].data["effort_level"] == "high"
+
+
+@pytest.mark.asyncio
+async def test_effort_event_store_failure_does_not_abort_ac() -> None:
+    """A degraded event store degrades the proof event to a warning, not an AC failure.
+
+    The routing event is auxiliary proof telemetry — it is emitted through
+    ``_safe_emit_event``, so a persistently failing ``event_store.append`` must NOT
+    propagate out of ``_execute_atomic_ac`` and abort the AC before runtime dispatch.
+    """
+    store = AsyncMock()
+    effort_append_attempts = 0
+
+    async def _append(event):
+        nonlocal effort_append_attempts
+        if getattr(event, "type", None) == "execution.ac.effort_routed":
+            effort_append_attempts += 1
+            raise RuntimeError("event store unavailable")
+
+    store.append.side_effect = _append
+    runtime = _EnforcedRuntime()
+    executor = ParallelACExecutor(
+        adapter=runtime,
+        event_store=store,
+        console=MagicMock(),
+        enable_decomposition=False,
+        reasoning_effort="high",
+    )
+
+    # Must not raise even though the proof-event append fails; the AC still dispatches.
+    await _run_one_ac(executor, is_sub_ac=False)
+
+    # The runtime was reached and received the enforced level despite telemetry loss.
+    assert runtime.received_effort == "high"
+    # The proof append was attempted (and retried) rather than silently skipped.
+    assert effort_append_attempts >= 1
+
+
+@pytest.mark.asyncio
+async def test_dormant_when_no_base_effort_emits_no_event() -> None:
+    store, events = _capturing_event_store()
+    executor = ParallelACExecutor(
+        adapter=_EnforcedRuntime(),
+        event_store=store,
+        console=MagicMock(),
+        enable_decomposition=False,
+        # reasoning_effort defaults None -> dormant
+    )
+
+    await _run_one_ac(executor, is_sub_ac=False)
+
+    assert _effort_events(events) == []