From ac82e72fa18e58a7323da53f773dadab5445ea64 Mon Sep 17 00:00:00 2001 From: HugoXK Date: Fri, 20 Nov 2026 05:44:23 +0000 Subject: [PATCH 1/4] feat(runstore): an operator call ceiling the caller cannot raise (#1082) --- agentdescent/budget.py | 18 ++++-- agentdescent/runstore.py | 42 ++++++++++++- changelog.d/1082-operator-run-cap.md | 7 +++ docs/plugin-design.md | 7 +++ tests/test_operator_run_cap.py | 89 ++++++++++++++++++++++++++++ 5 files changed, 157 insertions(+), 6 deletions(-) create mode 100644 changelog.d/1082-operator-run-cap.md create mode 100644 tests/test_operator_run_cap.py diff --git a/agentdescent/budget.py b/agentdescent/budget.py index 6dd080ce..826a6923 100644 --- a/agentdescent/budget.py +++ b/agentdescent/budget.py @@ -63,18 +63,23 @@ class BudgetStop(Exception): stop. """ - def __init__(self, limit: str, observed: float, cap: float) -> None: + def __init__(self, limit: str, observed: float, cap: float, + source: Optional[str] = None) -> None: self.limit = limit self.observed = observed self.cap = cap + #: The knob that set the cap, when it is worth naming in ``status`` + #: (the operator's environment ceiling, #1082); ``None`` for a flag. + self.source = source super().__init__(f"{limit}={cap} reached") def detail(self) -> str: """One line for ``status``: which limit fired and what was spent.""" + name = f"{self.limit} ({self.source})" if self.source else self.limit if self.limit == "max_calls": - return (f"max_calls: {int(self.observed)} call(s) made, " + return (f"{name}: {int(self.observed)} call(s) made, " f"cap {int(self.cap)}") - return f"max_usd: ${self.observed:.4f} spent, cap ${self.cap:.4f}" + return f"{name}: ${self.observed:.4f} spent, cap ${self.cap:.4f}" @dataclass @@ -99,6 +104,8 @@ class CallLimit: _lock: threading.Lock = field(default_factory=threading.Lock, repr=False, compare=False) _taken: int = field(default=0, init=False, repr=False, compare=False) + #: Names the knob in the refusal when it is not the caller's flag (#1082). + source: Optional[str] = None _stopped: Optional[BudgetStop] = field(default=None, init=False, repr=False, compare=False) @@ -112,12 +119,13 @@ def reserve(self) -> None: n = self._taken + 1 stop: Optional[BudgetStop] = None if self.max_calls is not None and n > self.max_calls: - stop = BudgetStop("max_calls", self._taken, self.max_calls) + stop = BudgetStop("max_calls", self._taken, self.max_calls, + self.source) elif self.max_usd is not None and self.usd_per_call: # Tolerance: 3 x 0.01 must not exceed 0.03 through float noise. if n * self.usd_per_call > self.max_usd + 1e-9: stop = BudgetStop("max_usd", self._taken * self.usd_per_call, - self.max_usd) + self.max_usd, self.source) if stop is not None: if self._stopped is None: self._stopped = stop diff --git a/agentdescent/runstore.py b/agentdescent/runstore.py index 18889fca..4ed2b5c5 100644 --- a/agentdescent/runstore.py +++ b/agentdescent/runstore.py @@ -48,7 +48,7 @@ import uuid import warnings from dataclasses import dataclass, field, asdict -from typing import Any, Dict, Iterator, List, Optional, Sequence +from typing import (Any, Dict, Iterator, List, Mapping, Optional, Sequence, Tuple) from .evolution import EvolutionResult, RoundInfo from .surface_common import scrub_host_env @@ -99,6 +99,41 @@ def require_budget_pair(budget_usd: Optional[float], raise RunStoreError(_BUDGET_NEEDS_PRICE) +#: The operator's per-run model-call ceiling (#1082): every run this process +#: starts -- foreground or detached -- is clamped to it. A caller's +#: ``--max-calls`` may lower it, never raise it. Calls only: a dollar ceiling +#: needs a per-call price, and `require_budget_pair` already refuses an +#: un-priced dollar budget rather than guessing one. +OPERATOR_MAX_CALLS_ENV = "AGENTDESCENT_MAX_CALLS" + + +def operator_max_calls(environ: Optional[Mapping[str, str]] = None + ) -> Optional[int]: + """The operator's per-run call ceiling, or ``None`` when unset (#1082).""" + env = os.environ if environ is None else environ + raw = env.get(OPERATOR_MAX_CALLS_ENV) + if raw is None or not str(raw).strip(): + return None + try: + value = int(str(raw).strip()) + except ValueError: + value = -1 + if value < 0: + raise RunStoreError( + f"{OPERATOR_MAX_CALLS_ENV} must be a non-negative integer, got {raw!r}") + return value + + +def _clamped_max_calls(max_calls: Optional[int]) -> Tuple[Optional[int], bool]: + """``(max_calls, whether the operator's ceiling is what bound it)`` (#1082).""" + cap = operator_max_calls() + if cap is None: + return max_calls, False + if max_calls is None or cap < max_calls: + return cap, True + return max_calls, False + + def root() -> str: """``$AGENTDESCENT_HOME/runs`` or ``~/.agentdescent/runs``. @@ -681,6 +716,7 @@ def launch(rd: RunDir, *, budget_usd: Optional[float] = None, reaped when it ends instead of lingering as a zombie that still looks alive). Its stdout and stderr go to ``log.txt``. """ + max_calls, _ = _clamped_max_calls(max_calls) require_budget_pair(budget_usd, usd_per_call) from .evolvespec import SpecError, build_call_limit try: @@ -837,6 +873,7 @@ def execute(rd: RunDir, *, budget_usd: Optional[float] = None, # live run that later "ended without reporting". try: require_budget_pair(budget_usd, usd_per_call) + max_calls, operator_bound = _clamped_max_calls(max_calls) except RunStoreError as e: rd.update_status(state="failed", finished=time.time(), error=str(e)[:2000]) raise @@ -854,6 +891,9 @@ def execute(rd: RunDir, *, budget_usd: Optional[float] = None, # running, the same shape as a missing usd_per_call above. rd.update_status(state="failed", finished=time.time(), error=str(e)[:2000]) raise RunStoreError(str(e)) from None + if limit is not None and operator_bound: + # So `status` says which ceiling stopped the run, not just "max_calls". + limit.source = OPERATOR_MAX_CALLS_ENV def _progress() -> None: # Mid-call rewrite so CLI/MCP status shows work in flight (#358). diff --git a/changelog.d/1082-operator-run-cap.md b/changelog.d/1082-operator-run-cap.md new file mode 100644 index 00000000..6bb77630 --- /dev/null +++ b/changelog.d/1082-operator-run-cap.md @@ -0,0 +1,7 @@ +Added +An operator can set `AGENTDESCENT_MAX_CALLS` as a ceiling on the model calls +every run in this process may make. A caller's `--max-calls` lowers it but +cannot raise it, and a run that names no call cap still gets it; a run that +reaches the ceiling ends `done` with `stop_reason="budget"` and a +`stop_detail` naming the variable. Calls only: a dollar ceiling needs a +per-call price, which an un-priced run does not have (#1082). diff --git a/docs/plugin-design.md b/docs/plugin-design.md index 8758b299..cb652b07 100644 --- a/docs/plugin-design.md +++ b/docs/plugin-design.md @@ -592,6 +592,13 @@ Two guards keep this from folding in on itself: running; the CLI refuses too — `evolve` exits 2 with `reason: nested-run` before it reads the spec or creates a run — and `doctor` reports nested mode plus the guard (`nested`, `nested_guard`). +* **An operator ceiling on model calls.** `AGENTDESCENT_MAX_CALLS`, when the + operator sets it, caps the calls **every** run this process starts -- the + foreground `evolve` and the detached one alike. A caller's `--max-calls` can + lower the ceiling but never raise it, and a run that names no cap of its own + still gets it; reaching it ends the run `done` with `stop_reason="budget"` + and a `stop_detail` naming the variable. So "a worker asked for an unbounded + run" is answered by the environment, not by review. * **The controller never hot-swaps itself.** A self-evolved plugin reaches the user's real installation only through `apply`, which is a human decision on a diff, after an L1 oracle gate, with a backup. The loop can improve its own diff --git a/tests/test_operator_run_cap.py b/tests/test_operator_run_cap.py new file mode 100644 index 00000000..d7045e35 --- /dev/null +++ b/tests/test_operator_run_cap.py @@ -0,0 +1,89 @@ +"""An operator's per-run call ceiling the caller cannot raise (#1082). + +``--max-calls`` is the caller's cap. This is the operator's, read from +``AGENTDESCENT_MAX_CALLS`` and clamped into the run store's two run paths: +``launch`` (detached) and ``execute`` (foreground). The clamp is a min -- a +caller may ask for fewer calls than the ceiling, never more, and a run that +passes no ``max_calls`` at all still gets the ceiling. +""" + +from __future__ import annotations + +import subprocess + +import pytest + +from agentdescent import runstore +from agentdescent.evolvespec import EvolveSpec + +#: One entry per model call the spec's agent actually makes. +CALLS = [] + + +def counting_agent(*, usage=None, tag="agent"): + """A spec-nameable model factory that records each call.""" + + def complete(prompt): + CALLS.append(tag) + return "ok" + + return complete + + +def _spec(): + model = {"ref": "tests.test_operator_run_cap:counting_agent", "tag": "agent"} + return EvolveSpec( + kind="text", target="You are a helpful assistant.", + data={"inline": [{"prompt": f"q{i}", "gold": f"a{i}"} for i in range(8)]}, + agent=model, reflect=model, allow=["tests."], + evolve={"rounds": 4, "n_workers": 4, "seed": 0, "patience": 10}) + + +def _run(tmp_path, **limits): + CALLS.clear() + rd = runstore.create(_spec().to_dict(), store=str(tmp_path / "runs")) + result = runstore.execute(rd, **limits) + return rd, rd.status(), result + + +def test_the_operator_ceiling_lowers_a_callers_larger_cap(tmp_path, monkeypatch): + monkeypatch.setenv("AGENTDESCENT_MAX_CALLS", "2") + rd, st, result = _run(tmp_path, max_calls=50) + assert len(CALLS) == 2, f"the ceiling let {len(CALLS)} calls through" + assert st.state == "done", st + assert st.stop_reason == "budget", st + assert "AGENTDESCENT_MAX_CALLS" in (st.stop_detail or ""), st.stop_detail + assert result.stop_reason == "budget" + + +def test_the_operator_ceiling_applies_with_no_caller_cap(tmp_path, monkeypatch): + monkeypatch.setenv("AGENTDESCENT_MAX_CALLS", "2") + rd, st, _ = _run(tmp_path) + assert len(CALLS) == 2, f"the ceiling let {len(CALLS)} calls through" + assert st.stop_reason == "budget", st + assert "AGENTDESCENT_MAX_CALLS" in (st.stop_detail or ""), st.stop_detail + + +def test_a_loose_operator_ceiling_never_loosens_the_callers_cap(tmp_path, monkeypatch): + monkeypatch.setenv("AGENTDESCENT_MAX_CALLS", "50") + rd, st, _ = _run(tmp_path, max_calls=1) + assert len(CALLS) == 1, f"the caller's cap let {len(CALLS)} calls through" + assert st.stop_reason == "budget", st + assert "max_calls" in (st.stop_detail or ""), st.stop_detail + # The caller's own cap fired, so the operator's name has no business here. + assert "AGENTDESCENT_MAX_CALLS" not in (st.stop_detail or ""), st.stop_detail + + +def test_a_detached_run_carries_the_operator_ceiling(tmp_path, monkeypatch): + monkeypatch.setenv("AGENTDESCENT_MAX_CALLS", "2") + rd = runstore.create(_spec().to_dict(), store=str(tmp_path / "runs")) + seen = {} + + def fake_run(argv, **kwargs): + seen["argv"] = argv + return subprocess.CompletedProcess(argv, 0, stdout="4242", stderr="") + + monkeypatch.setattr(runstore.subprocess, "run", fake_run) + runstore.launch(rd, max_calls=50) + argv = seen["argv"] + assert argv[argv.index("--max-calls") + 1] == "2", argv From 0e84778c4e961a1e66c4c2201594ffd1b1748e55 Mon Sep 17 00:00:00 2001 From: HugoXK Date: Fri, 20 Nov 2026 06:15:34 +0000 Subject: [PATCH 2/4] fix(runstore): keep the USD stop silent about the call ceiling; label the detached stop (#1082) --- agentdescent/budget.py | 4 +- agentdescent/runstore.py | 43 ++++++++++++++++++-- changelog.d/1082-operator-run-cap.md | 5 ++- docs/plugin-design.md | 7 +++- tests/test_operator_run_cap.py | 59 ++++++++++++++++++++++++++++ 5 files changed, 110 insertions(+), 8 deletions(-) diff --git a/agentdescent/budget.py b/agentdescent/budget.py index 826a6923..72e35a60 100644 --- a/agentdescent/budget.py +++ b/agentdescent/budget.py @@ -124,8 +124,10 @@ def reserve(self) -> None: elif self.max_usd is not None and self.usd_per_call: # Tolerance: 3 x 0.01 must not exceed 0.03 through float noise. if n * self.usd_per_call > self.max_usd + 1e-9: + # No ``source``: a dollar cap has no operator ceiling behind + # it (an un-priced one is refused before the run starts). stop = BudgetStop("max_usd", self._taken * self.usd_per_call, - self.max_usd, self.source) + self.max_usd) if stop is not None: if self._stopped is None: self._stopped = stop diff --git a/agentdescent/runstore.py b/agentdescent/runstore.py index 4ed2b5c5..6432e7ed 100644 --- a/agentdescent/runstore.py +++ b/agentdescent/runstore.py @@ -106,6 +106,12 @@ def require_budget_pair(budget_usd: Optional[float], #: un-priced dollar budget rather than guessing one. OPERATOR_MAX_CALLS_ENV = "AGENTDESCENT_MAX_CALLS" +#: What the caller asked for, carried across the detach boundary (#1082). The +#: child is started with the clamped ``--max-calls``, so without this its +#: ``status`` cannot tell "the ceiling bound the run" from "the caller asked +#: for exactly this". Label only: it never changes what is enforced. +OPERATOR_MAX_CALLS_REQUESTED_ENV = "AGENTDESCENT_MAX_CALLS_REQUESTED" + def operator_max_calls(environ: Optional[Mapping[str, str]] = None ) -> Optional[int]: @@ -124,14 +130,40 @@ def operator_max_calls(environ: Optional[Mapping[str, str]] = None return value +def _requested_calls() -> Tuple[Optional[int], bool]: + """``(what the caller asked for, whether the parent recorded it)`` (#1082). + + Label only. A malformed or negative value is ignored rather than refused: + the child was already started with the clamped argv, and this variable must + not be able to change anything but the wording of ``stop_detail``. A + present-but-empty value means "the caller named no cap of its own". + """ + raw = os.environ.get(OPERATOR_MAX_CALLS_REQUESTED_ENV) + if raw is None: + return None, False + if not str(raw).strip(): + return None, True + try: + value = int(str(raw).strip()) + except ValueError: + return None, False + return (value, True) if value >= 0 else (None, False) + + def _clamped_max_calls(max_calls: Optional[int]) -> Tuple[Optional[int], bool]: - """``(max_calls, whether the operator's ceiling is what bound it)`` (#1082).""" + """``(max_calls, whether the operator's ceiling is what bound it)`` (#1082). + + In the detached child ``max_calls`` is already the clamped argv value, so + the parent's record of what the caller asked for is what decides whether + the ceiling bound the run. + """ cap = operator_max_calls() if cap is None: return max_calls, False if max_calls is None or cap < max_calls: return cap, True - return max_calls, False + requested, present = _requested_calls() + return max_calls, present and (requested is None or requested > cap) def root() -> str: @@ -716,7 +748,8 @@ def launch(rd: RunDir, *, budget_usd: Optional[float] = None, reaped when it ends instead of lingering as a zombie that still looks alive). Its stdout and stderr go to ``log.txt``. """ - max_calls, _ = _clamped_max_calls(max_calls) + requested_calls = max_calls + max_calls, operator_bound = _clamped_max_calls(max_calls) require_budget_pair(budget_usd, usd_per_call) from .evolvespec import SpecError, build_call_limit try: @@ -744,6 +777,10 @@ def launch(rd: RunDir, *, budget_usd: Optional[float] = None, # prefix, so it survives either way. child_env = scrub_host_env({**os.environ, "PYTHONPATH": _child_pythonpath(), **(env or {})}) + if operator_bound: + # After the scrub, so it survives; label only, nothing here is enforced. + child_env[OPERATOR_MAX_CALLS_REQUESTED_ENV] = ( + "" if requested_calls is None else str(requested_calls)) boot = subprocess.run([_python(), "-c", _BOOTSTRAP, rd.log_path, *argv], capture_output=True, text=True, cwd=rd.path, env=child_env) if boot.returncode != 0 or not boot.stdout.strip().isdigit(): diff --git a/changelog.d/1082-operator-run-cap.md b/changelog.d/1082-operator-run-cap.md index 6bb77630..044b248c 100644 --- a/changelog.d/1082-operator-run-cap.md +++ b/changelog.d/1082-operator-run-cap.md @@ -3,5 +3,6 @@ An operator can set `AGENTDESCENT_MAX_CALLS` as a ceiling on the model calls every run in this process may make. A caller's `--max-calls` lowers it but cannot raise it, and a run that names no call cap still gets it; a run that reaches the ceiling ends `done` with `stop_reason="budget"` and a -`stop_detail` naming the variable. Calls only: a dollar ceiling needs a -per-call price, which an un-priced run does not have (#1082). +`stop_detail` naming the variable, whether the run is foreground or detached. +Calls only: a dollar ceiling needs a per-call price, which an un-priced run +does not have (#1082). diff --git a/docs/plugin-design.md b/docs/plugin-design.md index cb652b07..d55449c7 100644 --- a/docs/plugin-design.md +++ b/docs/plugin-design.md @@ -597,8 +597,11 @@ Two guards keep this from folding in on itself: foreground `evolve` and the detached one alike. A caller's `--max-calls` can lower the ceiling but never raise it, and a run that names no cap of its own still gets it; reaching it ends the run `done` with `stop_reason="budget"` - and a `stop_detail` naming the variable. So "a worker asked for an unbounded - run" is answered by the environment, not by review. + and a `stop_detail` naming the variable. A detached run reads the same: the + child starts with the clamped `--max-calls` and learns what the caller asked + for through an internal label-only variable, so `status` says which knob bound + it from either path. So "a worker asked for an unbounded run" is answered by + the environment, not by review. * **The controller never hot-swaps itself.** A self-evolved plugin reaches the user's real installation only through `apply`, which is a human decision on a diff, after an L1 oracle gate, with a backup. The loop can improve its own diff --git a/tests/test_operator_run_cap.py b/tests/test_operator_run_cap.py index d7045e35..f43ac483 100644 --- a/tests/test_operator_run_cap.py +++ b/tests/test_operator_run_cap.py @@ -87,3 +87,62 @@ def fake_run(argv, **kwargs): runstore.launch(rd, max_calls=50) argv = seen["argv"] assert argv[argv.index("--max-calls") + 1] == "2", argv + + +def test_a_dollar_stop_never_names_the_call_ceiling(tmp_path, monkeypatch): + """The two caps are independent: a USD stop must not blame the call knob. + + A run can carry both the operator's call ceiling and the caller's + ``--max-usd``. The USD refusal happens before any call, so the call ceiling + never bound it -- naming it in ``stop_detail`` would point the reader at a + knob that did nothing. + """ + monkeypatch.setenv("AGENTDESCENT_MAX_CALLS", "2") + rd, st, _ = _run(tmp_path, max_usd=0.01, usd_per_call=0.01) + assert st.stop_reason == "budget", st + detail = st.stop_detail or "" + assert "max_usd" in detail, detail + assert "AGENTDESCENT_MAX_CALLS" not in detail, detail + + +def test_the_detached_child_learns_what_the_caller_asked(tmp_path, monkeypatch): + """The child sees the clamped argv, so the label travels separately (#1082). + + ``launch`` starts the child with ``--max-calls 2`` (the ceiling), which on its + own is indistinguishable from a caller who asked for 2. The requested number + rides in an internal variable so the child's ``status`` can still say which + knob bound the run; it never changes what is enforced. + """ + monkeypatch.setenv("AGENTDESCENT_MAX_CALLS", "2") + rd = runstore.create(_spec().to_dict(), store=str(tmp_path / "runs")) + seen = {} + + def fake_run(argv, **kwargs): + seen["argv"] = argv + seen["env"] = kwargs["env"] + return subprocess.CompletedProcess(argv, 0, stdout="4242", stderr="") + + monkeypatch.setattr(runstore.subprocess, "run", fake_run) + runstore.launch(rd, max_calls=50) + argv = seen["argv"] + assert argv[argv.index("--max-calls") + 1] == "2", argv + assert seen["env"].get("AGENTDESCENT_MAX_CALLS_REQUESTED") == "50", seen["env"] + + +def test_the_detached_run_names_the_ceiling_the_parent_applied(tmp_path, monkeypatch): + """The child's own view: requested 50, ceiling 2, argv capped at 2.""" + monkeypatch.setenv("AGENTDESCENT_MAX_CALLS", "2") + monkeypatch.setenv("AGENTDESCENT_MAX_CALLS_REQUESTED", "50") + rd, st, _ = _run(tmp_path, max_calls=2) + assert len(CALLS) == 2, f"the ceiling let {len(CALLS)} calls through" + assert st.stop_reason == "budget", st + assert "AGENTDESCENT_MAX_CALLS" in (st.stop_detail or ""), st.stop_detail + + +def test_an_equal_cap_does_not_name_the_ceiling(tmp_path, monkeypatch): + """Caller asked for exactly the ceiling: the caller's number bound it.""" + monkeypatch.setenv("AGENTDESCENT_MAX_CALLS", "2") + monkeypatch.setenv("AGENTDESCENT_MAX_CALLS_REQUESTED", "2") + rd, st, _ = _run(tmp_path, max_calls=2) + assert st.stop_reason == "budget", st + assert "AGENTDESCENT_MAX_CALLS" not in (st.stop_detail or ""), st.stop_detail From fff1abb5059a06e274102e3744d19839a7037563 Mon Sep 17 00:00:00 2001 From: HugoXK Date: Fri, 20 Nov 2026 06:24:25 +0000 Subject: [PATCH 3/4] fix(runstore): only name the ceiling when the applied cap is the ceiling (#1082) `_clamped_max_calls` returned `operator_bound=True` from the recorded request alone, so a hand-set or inherited `AGENTDESCENT_MAX_CALLS_REQUESTED=50` under a looser ceiling (5) with a caller cap of 2 printed `max_calls (AGENTDESCENT_MAX_CALLS): 2 call(s) made, cap 2` -- blaming a ceiling that never bound the run. The label now requires the applied value to *be* the ceiling. The detached child still names it, because its clamped argv is the ceiling; anywhere the applied `--max-calls` sits below the ceiling the detail stays bare. Enforcement is untouched: argv, the CallLimit value and the exit codes are the same. Red at `0e84778c`: the new row printed the ceiling name. Green here: 9 passed. --- agentdescent/runstore.py | 7 ++++++- tests/test_operator_run_cap.py | 19 +++++++++++++++++++ 2 files changed, 25 insertions(+), 1 deletion(-) diff --git a/agentdescent/runstore.py b/agentdescent/runstore.py index 6432e7ed..daa628fa 100644 --- a/agentdescent/runstore.py +++ b/agentdescent/runstore.py @@ -163,7 +163,12 @@ def _clamped_max_calls(max_calls: Optional[int]) -> Tuple[Optional[int], bool]: if max_calls is None or cap < max_calls: return cap, True requested, present = _requested_calls() - return max_calls, present and (requested is None or requested > cap) + # The label follows the clamp, not the variable: only a run whose applied + # value *is* the ceiling can say the ceiling bound it, so a hand-set or + # stale request cannot blame a ceiling that never bit (#1082). + return (max_calls, + present and max_calls == cap + and (requested is None or requested > cap)) def root() -> str: diff --git a/tests/test_operator_run_cap.py b/tests/test_operator_run_cap.py index f43ac483..0b55725d 100644 --- a/tests/test_operator_run_cap.py +++ b/tests/test_operator_run_cap.py @@ -146,3 +146,22 @@ def test_an_equal_cap_does_not_name_the_ceiling(tmp_path, monkeypatch): rd, st, _ = _run(tmp_path, max_calls=2) assert st.stop_reason == "budget", st assert "AGENTDESCENT_MAX_CALLS" not in (st.stop_detail or ""), st.stop_detail + + + +def test_a_hand_set_request_does_not_blame_a_looser_ceiling(tmp_path, monkeypatch): + """The label follows the clamp: caller 2, ceiling 5, a stale request of 50. + + The variable only exists so a detached child can report what the caller + asked for. A hand-set or inherited value must not make the run blame a + ceiling that never bound it, and it must not change what is enforced: the + caller's cap of 2 still stops the run at 2 calls. + """ + monkeypatch.setenv("AGENTDESCENT_MAX_CALLS", "5") + monkeypatch.setenv("AGENTDESCENT_MAX_CALLS_REQUESTED", "50") + rd, st, _ = _run(tmp_path, max_calls=2) + assert len(CALLS) == 2, f"the caller's cap let {len(CALLS)} calls through" + assert st.stop_reason == "budget", st + detail = st.stop_detail or "" + assert "max_calls" in detail, detail + assert "AGENTDESCENT_MAX_CALLS" not in detail, detail From 9cf109d9c5c15de69601af40b3ef18f3c8a75b9f Mon Sep 17 00:00:00 2001 From: HugoXK Date: Fri, 20 Nov 2026 06:27:26 +0000 Subject: [PATCH 4/4] test(runstore): cover both hand-set request cases and the empty-string branch (#1082) Reviewer asked for the two branches the guard created: - a hand-set `AGENTDESCENT_MAX_CALLS_REQUESTED` below the ceiling (ceiling 2, caller 1) must stay bare -- red at `0e84778c` with `max_calls (AGENTDESCENT_MAX_CALLS): 1 call(s) made, cap 1`; - the detached run that names no caller cap: `launch` records the empty string and the child still attributes the stop to the ceiling, which is the one `_requested_calls` branch with no row. --- tests/test_operator_run_cap.py | 42 ++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/tests/test_operator_run_cap.py b/tests/test_operator_run_cap.py index 0b55725d..a58866f3 100644 --- a/tests/test_operator_run_cap.py +++ b/tests/test_operator_run_cap.py @@ -165,3 +165,45 @@ def test_a_hand_set_request_does_not_blame_a_looser_ceiling(tmp_path, monkeypatc detail = st.stop_detail or "" assert "max_calls" in detail, detail assert "AGENTDESCENT_MAX_CALLS" not in detail, detail + + +def test_a_hand_set_request_below_the_ceiling_stays_bare(tmp_path, monkeypatch): + """Same class as the row above, from the other side of the ceiling. + + Ceiling 2, caller cap 1, a stale request of 50: the applied value is the + caller's, so the ceiling never bound the run and must not be named. + """ + monkeypatch.setenv("AGENTDESCENT_MAX_CALLS", "2") + monkeypatch.setenv("AGENTDESCENT_MAX_CALLS_REQUESTED", "50") + rd, st, _ = _run(tmp_path, max_calls=1) + assert len(CALLS) == 1, f"the caller's cap let {len(CALLS)} calls through" + assert st.stop_reason == "budget", st + assert "AGENTDESCENT_MAX_CALLS" not in (st.stop_detail or ""), st.stop_detail + + +def test_a_detached_run_with_no_caller_cap_still_names_the_ceiling(tmp_path, + monkeypatch): + """The empty-string branch: the caller named no cap, so the ceiling did. + + The parent records "no caller cap" as an empty value rather than omitting + the variable, which is the one ``_requested_calls`` branch with no other + row: the child must still attribute the stop to the ceiling. + """ + monkeypatch.setenv("AGENTDESCENT_MAX_CALLS", "2") + rd = runstore.create(_spec().to_dict(), store=str(tmp_path / "runs")) + seen = {} + + def fake_run(argv, **kwargs): + seen["env"] = kwargs["env"] + return subprocess.CompletedProcess(argv, 0, stdout="4242", stderr="") + + monkeypatch.setattr(runstore.subprocess, "run", fake_run) + runstore.launch(rd) + assert seen["env"].get("AGENTDESCENT_MAX_CALLS_REQUESTED") == "" + + # The child's own view: the empty value plus the clamped argv. + monkeypatch.setenv("AGENTDESCENT_MAX_CALLS_REQUESTED", "") + rd2, st, _ = _run(tmp_path, max_calls=2) + assert len(CALLS) == 2, f"the ceiling let {len(CALLS)} calls through" + assert st.stop_reason == "budget", st + assert "AGENTDESCENT_MAX_CALLS" in (st.stop_detail or ""), st.stop_detail