Skip to content
Draft
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
86 changes: 74 additions & 12 deletions agentdescent/mcp.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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
Expand All @@ -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,
Expand All @@ -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


Expand Down Expand Up @@ -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.
Expand All @@ -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,
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
5 changes: 5 additions & 0 deletions changelog.d/1082-ticket-call-cap.md
Original file line number Diff line number Diff line change
@@ -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).
6 changes: 6 additions & 0 deletions docs/dsh-super-agent.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`,
Expand Down
7 changes: 6 additions & 1 deletion docs/plugin-design.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
115 changes: 115 additions & 0 deletions tests/test_mcp_ticket_cap.py
Original file line number Diff line number Diff line change
@@ -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"]
Loading