Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 14 additions & 4 deletions agentdescent/budget.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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)

Expand All @@ -112,10 +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:
# 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)
if stop is not None:
Expand Down
84 changes: 83 additions & 1 deletion agentdescent/runstore.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -99,6 +99,78 @@ 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"

#: 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]:
"""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 _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).

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
requested, present = _requested_calls()
# 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:
"""``$AGENTDESCENT_HOME/runs`` or ``~/.agentdescent/runs``.

Expand Down Expand Up @@ -681,6 +753,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``.
"""
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:
Expand Down Expand Up @@ -708,6 +782,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():
Expand Down Expand Up @@ -837,6 +915,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
Expand All @@ -854,6 +933,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).
Expand Down
8 changes: 8 additions & 0 deletions changelog.d/1082-operator-run-cap.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
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, 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).
10 changes: 10 additions & 0 deletions docs/plugin-design.md
Original file line number Diff line number Diff line change
Expand Up @@ -592,6 +592,16 @@ 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. 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
Expand Down
Loading
Loading