diff --git a/agentdescent/mcp.py b/agentdescent/mcp.py index 6321bb80..9c178b83 100644 --- a/agentdescent/mcp.py +++ b/agentdescent/mcp.py @@ -33,7 +33,7 @@ import json import os import secrets -from typing import Annotated, Any, Dict, Optional, Sequence, Tuple +from typing import Annotated, Any, Dict, List, Optional, Sequence, Tuple from . import __version__, runstore from .cli import (NESTED_ENV, NESTED_REFUSAL, apply_with_target, demo_payload, @@ -432,8 +432,9 @@ def _with_probe(payload: Dict[str, Any], spec: EvolveSpec) -> Dict[str, Any]: def _call_limit_payload(max_calls: Optional[int], max_usd: Optional[float], - usd_per_call: Optional[float]) -> Optional[Dict[str, Any]]: - """The run-level cap an MCP ``plan`` / ``start`` will enforce, or ``None`` (#1184). + usd_per_call: Optional[float], *, + spent: int = 0) -> Optional[Dict[str, Any]]: + """The cap an MCP ``plan`` / ``start`` will enforce, or ``None`` (#1184, #1082). Validated by the same :func:`~agentdescent.evolvespec.build_call_limit` the CLI and the run store use: the reason is the same, while the actionable hint @@ -447,6 +448,13 @@ def _call_limit_payload(max_calls: Optional[int], max_usd: Optional[float], binds, the same distinction ``AGENTDESCENT_MAX_CALLS_REQUESTED`` carries into the child: without them a host cannot tell "the ceiling lowered your 9 to 2" from "you asked for 2". + + ``spent`` is what this Ticket's earlier runs already charged (``#1082`` + row 2). The ceiling is a Ticket budget, not a per-run number the worker can + ask for again: the second run of one worker session is clamped to what is + left, and ``ticket`` reports the arithmetic so the host can show it. A + worker that runs outside an MCP server -- a plain CLI ``evolve`` -- passes + no ``spent`` and keeps the per-run ceiling ``runstore.launch`` applies. """ limit = build_call_limit(max_calls=max_calls, max_usd=max_usd, usd_per_call=usd_per_call, @@ -457,13 +465,22 @@ def _call_limit_payload(max_calls: Optional[int], max_usd: Optional[float], enforced = None if limit is None else limit.max_calls payload: Dict[str, Any] = {"max_calls": enforced, "max_usd": None if limit is None else limit.max_usd} - if ceiling is not None and (enforced is None or ceiling < enforced): - # A run that names no cap still gets the ceiling -- and then the reply - # has to say so, or `start` would look unbounded while it is capped. - payload["max_calls"] = ceiling - payload["source"] = runstore.OPERATOR_MAX_CALLS_ENV - if max_calls is not None: - payload["max_calls_requested"] = int(max_calls) + if ceiling is not None: + remaining = max(0, int(ceiling) - max(0, int(spent))) + if spent > 0: + # Shape stability: a fresh session's first run hears exactly what it + # heard before this key existed; only a Ticket with earlier spend + # reports the arithmetic nobody could otherwise see. + payload["ticket"] = {"ceiling": int(ceiling), "spent": int(spent), + "remaining": remaining} + if enforced is None or remaining < enforced: + # A run that names no cap still gets the ceiling -- and then the + # reply has to say so, or `start` would look unbounded while it is + # capped. Same for what earlier runs of this Ticket left. + payload["max_calls"] = remaining + payload["source"] = runstore.OPERATOR_MAX_CALLS_ENV + if max_calls is not None: + payload["max_calls_requested"] = int(max_calls) return payload @@ -504,6 +521,10 @@ def __init__(self, store: Optional[str] = None, *, #: The host's own CLI (`claude_code`, `codex`, `dsh`, `opencode`), from #: the name it sent at `initialize`. The fallback route for `host_model`. self.host_cli: Optional[str] = None + #: Runs this server started: one worker session is one Ticket, so the + #: operator ceiling is spent across them instead of re-granted per run + #: (#1082 row 2). Empty on a fresh server. + self._ticket_runs: List[str] = [] def host_model_env(self) -> Dict[str, str]: """What a launched run needs to reach the host's model, by either route. @@ -521,6 +542,26 @@ def host_model_env(self) -> Dict[str, str]: return {HOST_CLI_ENV: self.host_cli} return {} + def _ticket_spent(self) -> int: + """Model calls this Ticket's earlier runs already charged (#1082 row 2). + + One worker session is one Ticket (``docs/dsh-super-agent.md``), so the + operator ceiling is that session's budget: a second ``start`` hears the + remainder, not the ceiling again. ``pending_calls`` counts as spent + while a run is still in flight -- work already started is not budget + the next run may hand out twice. A run whose status cannot be read + counts as 0, so a store that lost one run does not make the Ticket + unstartable forever. + """ + spent = 0 + for run_id in self._ticket_runs: + try: + st = runstore.get(run_id, store=self.store).status() + except (runstore.RunStoreError, ValueError, OSError): + continue + spent += int(st.calls) + int(st.pending_calls) + return spent + # -- read-only ------------------------------------------------------------- def demo(self, algorithm: Optional[str] = None, @@ -717,7 +758,8 @@ def plan(self, spec: Dict[str, Any], usd_per_call: Optional[float] = None, es = EvolveSpec.from_dict(spec).absolutise() payload = plan_payload(es, usd_per_call=usd_per_call, budget_usd=budget_usd) - limit = _call_limit_payload(max_calls, max_usd, usd_per_call) + limit = _call_limit_payload(max_calls, max_usd, usd_per_call, + spent=self._ticket_spent()) except SpecError as e: return {"ok": False, "error": str(e)} except runstore.RunStoreError as e: @@ -772,11 +814,28 @@ def start(self, spec: Dict[str, Any], budget_usd: Optional[float] = None, runstore.require_budget_pair(budget_usd, usd_per_call) # A bad cap is a refusal too, not a run whose log.txt explains it # later; same sentence the CLI prints (#1184). - limit = _call_limit_payload(max_calls, max_usd, usd_per_call) + limit = _call_limit_payload(max_calls, max_usd, usd_per_call, + spent=self._ticket_spent()) except SpecError as e: return {"ok": False, "error": str(e)} except runstore.RunStoreError as e: return {"ok": False, "error": str(e)} + ticket = (limit or {}).get("ticket") or {} + if ticket.get("remaining") == 0: + # The ceiling is spent: refuse before a run exists, with the + # arithmetic in the sentence, instead of starting one that cannot + # charge a single call or, worse, one that treats 0 as "no cap". + # A caller's own `max_calls=0` is not this case and keeps its + # existing path. + return {"ok": False, "error": ( + f"{runstore.OPERATOR_MAX_CALLS_ENV}={ticket['ceiling']} is " + f"already spent by this worker's Ticket ({ticket['spent']} " + f"call{'s' if ticket['spent'] != 1 else ''} over " + f"{len(self._ticket_runs)} run" + f"{'s' if len(self._ticket_runs) != 1 else ''}); no run may " + "start. Start the next Ticket in a new server session, or " + "raise the ceiling."), + "call_limit": limit} if os.environ.get(NESTED_ENV): # This server is running inside a worker of another run (the plugin # that hosts it is being evolved). The transcript should still show @@ -816,6 +875,9 @@ def start(self, spec: Dict[str, Any], budget_usd: Optional[float] = None, env=self.host_model_env()) except runstore.RunStoreError as e: return {"ok": False, "error": str(e), "run_id": rd.run_id, "dir": rd.path} + # The Ticket's spend is read from the store, so this only has to name + # the runs it may count; a resumed or CLI-started run is not one. + self._ticket_runs.append(rd.run_id) out = {"ok": True, "run_id": rd.run_id, "state": st.state, "pid": st.pid, "dir": rd.path, "notes": rd.status().notes, # Whether a `host_model` reference in this spec can work. A run diff --git a/changelog.d/1082-ticket-call-cap.md b/changelog.d/1082-ticket-call-cap.md new file mode 100644 index 00000000..b85d5caf --- /dev/null +++ b/changelog.d/1082-ticket-call-cap.md @@ -0,0 +1,5 @@ +Fixed +`AGENTDESCENT_MAX_CALLS` is now a budget for one worker session, not a number +each run may ask for again: an MCP `start` after earlier runs is clamped to +what the Ticket has left, reports `call_limit.ticket` with ceiling/spent/ +remaining, and refuses outright once the ceiling is spent (#1082). diff --git a/docs/dsh-super-agent.md b/docs/dsh-super-agent.md index 9aa4fdbc..13e26341 100644 --- a/docs/dsh-super-agent.md +++ b/docs/dsh-super-agent.md @@ -108,6 +108,12 @@ your tree, under the operator's write allowlist). the Ticket. - `plan` is the budget line: it estimates cost without executing. Read it before `start`, and put the number in the Ticket. +- A Ticket's ceiling is the session's, not the run's. With + `AGENTDESCENT_MAX_CALLS` set, the server spends it across the runs it starts: + a second `start` is clamped to the remainder, its reply says + `ticket: {ceiling, spent, remaining}`, and once the ceiling is spent `start` + refuses. Start the next Ticket in a new server session (or raise the + ceiling) rather than reusing the spent one (#1082). - A detached run no longer inherits the worker session: `launch` drops the host-session markers it lists, except the four host config roots it keeps (`DETACHED_KEEP_VARS`: `CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `DSH_HOME`, diff --git a/docs/plugin-design.md b/docs/plugin-design.md index 20eb1e56..a6e5c159 100644 --- a/docs/plugin-design.md +++ b/docs/plugin-design.md @@ -604,7 +604,12 @@ Two guards keep this from folding in on itself: the environment, not by review. The MCP surface takes the same numbers — `plan` / `start` accept `max_calls` / `max_usd` and report `call_limit` with what was asked for and what will be enforced, so a host sees a request of 9 - come back as 2 with `source: AGENTDESCENT_MAX_CALLS` (#1184). + come back as 2 with `source: AGENTDESCENT_MAX_CALLS` (#1184). One worker + session is one Ticket, so the server does not hand the ceiling out again per + run: a second `start` is clamped to what the Ticket has left, `call_limit` + then carries `ticket: {ceiling, spent, remaining}`, and a spent Ticket + refuses another `start` instead of launching a run that cannot charge a + single call (#1082). * **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_mcp_ticket_cap.py b/tests/test_mcp_ticket_cap.py new file mode 100644 index 00000000..2487f075 --- /dev/null +++ b/tests/test_mcp_ticket_cap.py @@ -0,0 +1,115 @@ +"""One worker session is one Ticket: the operator ceiling is spent, not re-granted (#1082). + +``AGENTDESCENT_MAX_CALLS`` caps a *run* in ``runstore.launch`` / ``execute``. A +host worker that starts a second run from the same MCP server asks again and +gets the same ceiling back, so one Ticket spends twice the number the operator +set: with ``AGENTDESCENT_MAX_CALLS=1`` two ``start`` calls each run one model +call and the Ticket bills two. The server process is the worker's session -- +one Ticket in ``docs/dsh-super-agent.md`` -- so the ceiling has to hold across +the runs that server starts, and a spent Ticket refuses another start instead +of silently starting an uncapped one. +""" + +from __future__ import annotations + +import time + +import pytest + +from agentdescent import runstore +from agentdescent.mcp import Tools + +from tests.test_evolvespec import _dir_spec # noqa: F401 + + +@pytest.fixture +def store(tmp_path, monkeypatch): + monkeypatch.setenv("AGENTDESCENT_HOME", str(tmp_path / "home")) + monkeypatch.setenv("AGENTDESCENT_SURFACE_WRITE_DIRS", str(tmp_path)) + return str(tmp_path / "runs") + + +def _wait(rd, timeout=120): + deadline = time.time() + timeout + while time.time() < deadline: + st = rd.status() + if st.state in ("done", "failed", "cancelled"): + return st + time.sleep(0.2) + raise AssertionError(rd.status()) + + +def _start_in(tmp_path, tools, name, **kwargs): + sub = tmp_path / name + sub.mkdir() + started = tools.start(_dir_spec(str(sub)).to_dict(), **kwargs) + assert started["ok"] is True, started + return started + + +def test_second_run_is_clamped_to_what_the_ticket_has_left(store, tmp_path, monkeypatch): + monkeypatch.setenv("AGENTDESCENT_MAX_CALLS", "2") + tools = Tools(store) + first = _start_in(tmp_path, tools, "t0", max_calls=1) + st = _wait(runstore.get(first["run_id"], store=store)) + assert st.state == "done", st + assert st.calls == 1, st + + second = _start_in(tmp_path, tools, "t1", max_calls=5) + # One call is already spent, so the Ticket has one left -- not five, and + # not the untouched ceiling of two the run-level clamp would hand back. + assert second["call_limit"]["max_calls"] == 1, second["call_limit"] + assert second["call_limit"]["source"] == runstore.OPERATOR_MAX_CALLS_ENV + assert second["call_limit"]["max_calls_requested"] == 5 + assert second["call_limit"]["ticket"] == {"ceiling": 2, "spent": 1, "remaining": 1} + _wait(runstore.get(second["run_id"], store=store)) + + +def test_a_spent_ticket_refuses_another_start(store, tmp_path, monkeypatch): + monkeypatch.setenv("AGENTDESCENT_MAX_CALLS", "1") + tools = Tools(store) + first = _start_in(tmp_path, tools, "t0", max_calls=1) + st = _wait(runstore.get(first["run_id"], store=store)) + assert st.state == "done", st + assert st.calls == 1, st + + sub = tmp_path / "t1" + sub.mkdir() + refused = tools.start(_dir_spec(str(sub)).to_dict()) + assert refused["ok"] is False, refused + assert "AGENTDESCENT_MAX_CALLS" in refused["error"], refused["error"] + assert "1" in refused["error"], refused["error"] + # Nothing was created: a spent Ticket is refused before the run exists. + assert len(runstore.list_runs(store=store)) == 1 + + +def test_plan_reports_what_the_ticket_has_left(store, tmp_path, monkeypatch): + monkeypatch.setenv("AGENTDESCENT_MAX_CALLS", "3") + tools = Tools(store) + first = _start_in(tmp_path, tools, "t0", max_calls=1) + st = _wait(runstore.get(first["run_id"], store=store)) + assert st.calls == 1, st + + sub = tmp_path / "t1" + sub.mkdir() + plan = tools.plan(_dir_spec(str(sub)).to_dict(), max_calls=9) + assert plan["ok"] is True, plan + # What `start` would enforce, so the host shows the number the user agrees + # to -- 1 call left of 3, not the ceiling of 3 or the requested 9. + assert plan["call_limit"]["max_calls"] == 2, plan["call_limit"] + assert plan["call_limit"]["ticket"] == {"ceiling": 3, "spent": 1, + "remaining": 2} + + +def test_a_callers_own_zero_cap_is_not_the_spent_ticket_refusal(store, tmp_path, monkeypatch): + monkeypatch.setenv("AGENTDESCENT_MAX_CALLS", "2") + tools = Tools(store) + sub = tmp_path / "t0" + sub.mkdir() + plan = tools.plan(_dir_spec(str(sub)).to_dict(), max_calls=0) + assert plan["ok"] is True, plan + # The caller asked for zero calls with a ceiling that is untouched: that is + # its own number, not "the Ticket is spent", so it must not carry the + # ticket arithmetic or the refusal. + assert plan["call_limit"]["max_calls"] == 0, plan["call_limit"] + assert "ticket" not in plan["call_limit"], plan["call_limit"]