Skip to content

AutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.

feat(backend/copilot): AutoPilot says what its task has left and wraps up before it runs out (#14393)

Reinier van der Leerbe590199182e
diff --git a/autogpt_platform/backend/backend/copilot/baseline/service.py b/autogpt_platform/backend/backend/copilot/baseline/service.py
index f71551d9f9..54a981ba91 100644
--- a/autogpt_platform/backend/backend/copilot/baseline/service.py
+++ b/autogpt_platform/backend/backend/copilot/baseline/service.py
@@ -39,6 +39,7 @@ from backend.copilot.baseline.reasoning import (
reasoning_extra_body,
)
from backend.copilot.baseline.tool_persistence import BaselineToolPersistence
+from backend.copilot.budget_signal import build_turn_budget_block
from backend.copilot.builder_context import (
build_builder_context_turn_prefix,
build_builder_system_prompt_suffix,
@@ -2054,6 +2055,18 @@ async def stream_chat_completion_baseline(
for pm in drained_at_start_pending:
openai_messages.append(format_pending_as_user_message(pm))
+ # Live budget, every turn — the first-turn ``<budget_context>`` above is
+ # stale from turn two onward and says nothing about the tree. After the
+ # pending fold so it lands on the message the model reads last, and never
+ # on ``user_message_for_transcript``: that would persist one stale figure
+ # per turn, the same trap the warm-context injection below names.
+ budget_status = await build_turn_budget_block(envelope, user_id)
+ if budget_status:
+ for msg in reversed(openai_messages):
+ if msg["role"] == "user":
+ msg["content"] = budget_status + str(msg.get("content") or "")
+ break
+
# Inject Graphiti warm context into the current turn's user message (not
# the system prompt) so the system prompt stays static and cacheable.
# warm_ctx is already wrapped in <temporal_context>.
diff --git a/autogpt_platform/backend/backend/copilot/budget_signal.py b/autogpt_platform/backend/backend/copilot/budget_signal.py
new file mode 100644
index 0000000000..0468a8a6f4
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/budget_signal.py
@@ -0,0 +1,165 @@
+"""What a turn's model is told about the budget it is spending.
+
+Three signals, one wording, so both engines and all three spawn tools agree.
+Every number comes from the tree ledger (:mod:`backend.copilot.tree`) and the
+per-user rate limit; this module is the phrasing and the thresholds.
+
+- ``<budget_status>`` — one line prepended to every turn's message: what the
+ tree has left, how many sub-sessions it may still start, what the account
+ has left today. Live, so it is right from turn two onward.
+- The wrap-up checkpoint — appended to that block once per tree, the first
+ turn the tree crosses ``tree_wrapup_threshold`` of its ceiling.
+- The spawn-result note — the same tree state on every spawn tool result, so
+ the parent decides its next spawn from numbers rather than a guess.
+
+Nothing here may fail a turn: every entry point returns ``""`` on any error,
+and returns ``""`` unconditionally when the feature is off or the turn has no
+tree envelope, which keeps the prompt byte-identical to what it was before.
+"""
+
+import logging
+
+from backend.copilot.config import ChatConfig
+from backend.copilot.context import get_current_envelope
+from backend.copilot.rate_limit import get_global_rate_limits, get_remaining_usd_budget
+from backend.copilot.tree import (
+ TurnEnvelope,
+ get_tree_ledger,
+ resolve_root_ceiling_microdollars,
+)
+
+logger = logging.getLogger(__name__)
+config = ChatConfig()
+
+CHECKPOINT_INSTRUCTION = (
+ "Most of this task's budget is spent. Checkpoint now: finish the current "
+ "step, then list up to 3 short bullets of the most impactful remaining "
+ "work. Start no new sub-sessions."
+)
+
+
+async def build_turn_budget_block(
+ envelope: TurnEnvelope | None, user_id: str | None
+) -> str:
+ """The ``<budget_status>`` block for this turn, or ``""``.
+
+ Prepended to the turn's message rather than the system prompt: the system
+ prompt must stay identical across users for the cross-session prefix cache
+ (see ``get_sdk_supplement``). Not persisted either — a budget line is true
+ of one turn, and a replayed transcript would carry a stale one.
+ """
+ if not config.tree_budget_signal_enabled or envelope is None:
+ return ""
+ try:
+ ceiling, spent, nodes, max_nodes = await _tree_state(envelope, user_id)
+ line = _budget_line(ceiling, spent, nodes, max_nodes)
+ daily = await _remaining_daily_usd(user_id)
+ if daily is not None:
+ line += f" This account has ${daily:.2f} of today's budget left."
+ if await _crossed_wrapup(envelope, ceiling, spent):
+ line += f"\n{CHECKPOINT_INSTRUCTION}"
+ return f"<budget_status>\n{line}\n</budget_status>\n\n"
+ except Exception:
+ logger.warning("[budget] turn block unavailable", exc_info=True)
+ return ""
+
+
+async def build_spawn_state_note() -> str:
+ """The tree's state after a spawn, for the spawn tool's own result.
+
+ Reads the envelope off the contextvar rather than a parameter: the running
+ turn is the spawner, so its ``tree_id`` is the tree the child just charged.
+ """
+ envelope = get_current_envelope()
+ if not config.tree_budget_signal_enabled or envelope is None:
+ return ""
+ try:
+ ledger = await get_tree_ledger()
+ snapshot = await ledger.snapshot(envelope.tree_id)
+ if not snapshot:
+ return ""
+ ceiling = snapshot.get("ceiling", 0)
+ spent = snapshot.get("spent", 0)
+ nodes = snapshot.get("nodes", 0)
+ max_nodes = snapshot.get("max_nodes", 0)
+ return (
+ f" Task budget: ${_usd(spent)} spent of ${_usd(ceiling)} "
+ f"(${_usd(ceiling - spent)} left); {nodes} of {max_nodes} "
+ f"sub-sessions used ({max(0, max_nodes - nodes)} left)."
+ )
+ except Exception:
+ logger.warning("[budget] spawn state unavailable", exc_info=True)
+ return ""
+
+
+def _budget_line(ceiling: int, spent: int, nodes: int, max_nodes: int) -> str:
+ """A tier that may not spend is not offered sub-sessions it would then be
+ refused; ``_spend_refusal`` says the same on the way out."""
+ if ceiling <= 0:
+ return (
+ "This account has no subscription, so this task cannot start "
+ "sub-sessions."
+ )
+ return (
+ f"This task has ${_usd(ceiling - spent)} of its ${_usd(ceiling)} "
+ f"budget left and can start {max(0, max_nodes - nodes)} more "
+ f"sub-sessions."
+ )
+
+
+async def _tree_state(
+ envelope: TurnEnvelope, user_id: str | None
+) -> tuple[int, int, int, int]:
+ """``(ceiling, spent, nodes, max_nodes)`` in microdollars and counts.
+
+ A tree that has not spawned yet has no ledger, so its ceiling is resolved
+ the same way ``open()`` will resolve it — the model gets the real number
+ on the turn it is deciding whether to spawn at all, not the turn after.
+ """
+ ledger = await get_tree_ledger()
+ snapshot = await ledger.snapshot(envelope.tree_id)
+ if snapshot:
+ return (
+ snapshot.get("ceiling", 0),
+ snapshot.get("spent", 0),
+ snapshot.get("nodes", 0),
+ snapshot.get("max_nodes", 0),
+ )
+ return (
+ await resolve_root_ceiling_microdollars(user_id),
+ 0,
+ 1,
+ config.tree_max_nodes,
+ )
+
+
+async def _remaining_daily_usd(user_id: str | None) -> float | None:
+ """``None`` rather than ``$0.00`` when the figure is unknowable — an
+ unlimited account, or a Redis brown-out that already fails the turn's
+ pre-gate closed."""
+ if not user_id:
+ return None
+ daily, weekly, _tier = await get_global_rate_limits(
+ user_id,
+ config.daily_cost_limit_microdollars,
+ config.weekly_cost_limit_microdollars,
+ )
+ remaining = await get_remaining_usd_budget(
+ user_id=user_id,
+ daily_cost_limit=daily,
+ weekly_cost_limit=weekly,
+ # Negative is the "Redis said nothing" floor; a real $0.00 comes back
+ # as 0.0 and is the one figure worth telling the model.
+ floor_usd=-1.0,
+ )
+ return None if remaining < 0 or remaining == float("inf") else remaining
+
+
+async def _crossed_wrapup(envelope: TurnEnvelope, ceiling: int, spent: int) -> bool:
+ if ceiling <= 0 or spent < config.tree_wrapup_threshold * ceiling:
+ return False
+ return await (await get_tree_ledger()).claim_wrapup(envelope.tree_id)
+
+
+def _usd(microdollars: int) -> str:
+ return f"{max(0, microdollars) / 1_000_000:.2f}"
diff --git a/autogpt_platform/backend/backend/copilot/budget_signal_test.py b/autogpt_platform/backend/backend/copilot/budget_signal_test.py
new file mode 100644
index 0000000000..09c9f07d8b
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/budget_signal_test.py
@@ -0,0 +1,256 @@
+"""Tests for the budget signals a turn's model reads.
+
+The ledger is exercised through the same in-memory Redis ``tree_test`` uses,
+so the two suites cannot drift on hash semantics.
+"""
+
+from __future__ import annotations
+
+import ast
+import asyncio
+import inspect
+import textwrap
+from typing import cast
+
+import pytest
+
+from backend.data.redis_client import AsyncRedisClient
+
+from . import budget_signal
+from .budget_signal import (
+ CHECKPOINT_INSTRUCTION,
+ build_spawn_state_note,
+ build_turn_budget_block,
+)
+from .tree import TreeLedger, root_envelope
+from .tree_test import BrokenRedis, FakeRedis
+
+ENVELOPE = root_envelope("t")
+
+
+def ledger(monkeypatch) -> TreeLedger:
+ """A ledger on fake Redis, wired into both module entry points."""
+ live = TreeLedger(cast(AsyncRedisClient, FakeRedis()))
+
+ async def _get() -> TreeLedger:
+ return live
+
+ monkeypatch.setattr(budget_signal, "get_tree_ledger", _get)
+
+ async def _limits(_uid, _d, _w):
+ return 1_000_000, 7_000_000, "BASIC"
+
+ async def _remaining(**_kw):
+ return 0.58
+
+ monkeypatch.setattr(budget_signal, "get_global_rate_limits", _limits)
+ monkeypatch.setattr(budget_signal, "get_remaining_usd_budget", _remaining)
+ return live
+
+
+ "envelope, flag",
+ [(None, True), (ENVELOPE, False)],
+ ids=["no-envelope", "flag-off"],
+)
+async def test_the_prompt_is_untouched_when_the_signal_does_not_apply(
+ ledger, monkeypatch, envelope, flag
+) -> None:
+ """Empty output alone would not prove the guard: the module swallows every
+ error, so a guard removed and a guard held both return ``""``. What
+ separates them is whether the ledger was read at all."""
+ monkeypatch.setattr(budget_signal.config, "tree_budget_signal_enabled", flag)
+ reads: list[int] = []
+
+ async def _counted() -> TreeLedger:
+ reads.append(1)
+ raise AssertionError("read the ledger for a turn that has no signal")
+
+ monkeypatch.setattr(budget_signal, "get_tree_ledger", _counted)
+
+ assert await build_turn_budget_block(envelope, "u") == ""
+ assert not reads
+
+
+async def test_the_block_states_both_budgets_and_the_seats_left(ledger) -> None:
+ await ledger.open("t", ceiling_microdollars=500_000, max_nodes=8, initial_nodes=3)
+ await ledger.charge("t", 190_000)
+
+ block = await build_turn_budget_block(ENVELOPE, "u")
+
+ assert block.startswith("<budget_status>\n")
+ assert block.endswith("</budget_status>\n\n")
+ assert "$0.31 of its $0.50 budget left" in block
+ assert "5 more sub-sessions" in block
+ assert "$0.58 of today's budget left" in block
+ assert CHECKPOINT_INSTRUCTION not in block
+
+
+async def test_a_tree_that_has_not_spawned_yet_shows_its_prospective_ceiling(
+ ledger, monkeypatch
+) -> None:
+ async def _ceiling(_user_id):
+ return 500_000
+
+ monkeypatch.setattr(budget_signal, "resolve_root_ceiling_microdollars", _ceiling)
+ monkeypatch.setattr(budget_signal.config, "tree_max_nodes", 8)
+
+ block = await build_turn_budget_block(ENVELOPE, "u")
+
+ assert "$0.50 of its $0.50 budget left" in block
+ assert "7 more sub-sessions" in block
+
+
+async def test_a_tier_that_may_not_spend_is_not_offered_sub_sessions(ledger) -> None:
+ """A zero ceiling is a tier that may not spend at all, so a line offering
+ seats contradicts the refusal the spawn would hit in the same turn."""
+ await ledger.open("t", ceiling_microdollars=0, max_nodes=8, initial_nodes=1)
+
+ block = await build_turn_budget_block(ENVELOPE, "u")
+
+ assert "no subscription" in block
+ assert "more sub-sessions" not in block
+ assert "$0.00 of its $0.00" not in block
+
+
+async def test_the_daily_line_is_dropped_when_there_is_no_user(ledger) -> None:
+ await ledger.open("t", ceiling_microdollars=500_000, max_nodes=8, initial_nodes=1)
+ assert "today's budget" not in await build_turn_budget_block(ENVELOPE, None)
+
+
+async def test_the_checkpoint_fires_once_per_tree_and_not_before_the_threshold(
+ ledger,
+) -> None:
+ await ledger.open("t", ceiling_microdollars=500_000, max_nodes=8, initial_nodes=2)
+ await ledger.charge("t", 390_000)
+ assert CHECKPOINT_INSTRUCTION not in await build_turn_budget_block(ENVELOPE, "u")
+
+ await ledger.charge("t", 10_000)
+ assert CHECKPOINT_INSTRUCTION in await build_turn_budget_block(ENVELOPE, "u")
+ assert CHECKPOINT_INSTRUCTION not in await build_turn_budget_block(ENVELOPE, "u")
+
+
+async def test_two_turns_crossing_at_once_still_get_one_checkpoint(ledger) -> None:
+ await ledger.open("t", ceiling_microdollars=500_000, max_nodes=8, initial_nodes=2)
+ await ledger.charge("t", 400_000)
+
+ blocks = await asyncio.gather(
+ build_turn_budget_block(ENVELOPE, "u"),
+ build_turn_budget_block(ENVELOPE, "u"),
+ )
+
+ assert sum(CHECKPOINT_INSTRUCTION in b for b in blocks) == 1
+
+
+async def test_a_brownout_drops_the_daily_line_and_a_real_zero_still_states_it(
+ ledger, monkeypatch
+) -> None:
+ """``get_remaining_usd_budget`` answers a brown-out with the floor it was
+ handed, so a caller asking for ``0.0`` cannot tell "unknown" from "spent to
+ the last cent" — and the second is the one worth telling the model."""
+ await ledger.open("t", ceiling_microdollars=500_000, max_nodes=8, initial_nodes=1)
+
+ async def _brownout(*, floor_usd: float, **_kw) -> float:
+ return floor_usd
+
+ monkeypatch.setattr(budget_signal, "get_remaining_usd_budget", _brownout)
+ assert "today's budget" not in await build_turn_budget_block(ENVELOPE, "u")
+
+ async def _spent_out(**_kw) -> float:
+ return 0.0
+
+ monkeypatch.setattr(budget_signal, "get_remaining_usd_budget", _spent_out)
+ assert "$0.00 of today's budget left" in await build_turn_budget_block(
+ ENVELOPE, "u"
+ )
+
+
+async def test_a_dead_ledger_never_fails_the_turn(monkeypatch) -> None:
+ async def _get() -> TreeLedger:
+ return TreeLedger(cast(AsyncRedisClient, BrokenRedis()))
+
+ monkeypatch.setattr(budget_signal, "get_tree_ledger", _get)
+ assert await build_turn_budget_block(ENVELOPE, "u") == ""
+ monkeypatch.setattr(budget_signal, "get_current_envelope", lambda: ENVELOPE)
+ assert await build_spawn_state_note() == ""
+
+
+async def test_the_spawn_note_carries_what_was_spent_and_what_remains(
+ ledger, monkeypatch
+) -> None:
+ monkeypatch.setattr(budget_signal, "get_current_envelope", lambda: ENVELOPE)
+ await ledger.open("t", ceiling_microdollars=500_000, max_nodes=8, initial_nodes=1)
+ await ledger.charge("t", 420_000)
+ await ledger.admit(ENVELOPE)
+
+ note = await build_spawn_state_note()
+
+ assert "$0.42 spent of $0.50" in note
+ assert "$0.08 left" in note
+ assert "2 of 8 sub-sessions used (6 left)" in note
+
+
+async def test_the_spawn_note_is_empty_without_a_tree(ledger, monkeypatch) -> None:
+ monkeypatch.setattr(budget_signal, "get_current_envelope", lambda: None)
+ assert await build_spawn_state_note() == ""
+ # An envelope whose tree never opened a ledger has nothing to report.
+ monkeypatch.setattr(budget_signal, "get_current_envelope", lambda: ENVELOPE)
+ assert await build_spawn_state_note() == ""
+
+
+# ── engine wiring ──────────────────────────────────────────────────────
+# Both stream functions need a live database, a model route and an LLM to
+# reach their injection point, so the seam is pinned by inspection — the
+# pattern ``markers_test`` already uses on the same two functions.
+
+
+def _stream_sources() -> dict[str, str]:
+ from backend.copilot.baseline.service import stream_chat_completion_baseline
+ from backend.copilot.sdk.service import stream_chat_completion_sdk
+
+ return {
+ "baseline": inspect.getsource(stream_chat_completion_baseline),
+ "sdk": inspect.getsource(stream_chat_completion_sdk),
+ }
+
+
[email protected]("engine", ["baseline", "sdk"])
+def test_both_engines_build_the_block_every_turn(engine: str) -> None:
+ assert "build_turn_budget_block(" in _stream_sources()[engine]
+
+
+ ("engine", "transcribed"),
+ [("baseline", "user_message_for_transcript"), ("sdk", "current_message")],
+)
+def test_the_block_never_reaches_the_variable_the_transcript_records(
+ engine: str, transcribed: str
+) -> None:
+ """The transcript is replayed on the next turn; one stale figure per turn
+ is what folding the block into it would leave behind. Both engines reach
+ the block through a ``budget_status`` local, so naming only the builder
+ would miss every regression that actually folds it in."""
+ tree = ast.parse(textwrap.dedent(_stream_sources()[engine]))
+ for node in ast.walk(tree):
+ if not isinstance(node, ast.Assign):
+ continue
+ targets = {t.id for t in node.targets if isinstance(t, ast.Name)}
+ if transcribed not in targets:
+ continue
+ folded = ast.unparse(node.value)
+ for carrier in ("build_turn_budget_block", "budget_status"):
+ assert (
+ carrier not in folded
+ ), f"{engine}: {carrier} was assigned into {transcribed}"
diff --git a/autogpt_platform/backend/backend/copilot/config.py b/autogpt_platform/backend/backend/copilot/config.py
index 34ddb765a6..86b9df995c 100644
--- a/autogpt_platform/backend/backend/copilot/config.py
+++ b/autogpt_platform/backend/backend/copilot/config.py
@@ -471,7 +471,9 @@ class ChatConfig(BaseSettings):
description="Absolute cap on a tree ceiling, in microdollars ($10.00), "
"applied after the tier-scaled fraction and the floor. The effective "
"ceiling is min(remaining budget, max(fraction x tier daily, floor), "
- "this cap). Checked at turn start, so overshoot is at most one turn.",
+ "this cap). Admission reads settled spend, so a tree can overshoot by "
+ "up to (max_nodes - 1) concurrently admitted turns; the node cap is "
+ "what bounds it.",
)
tree_max_nodes: int = Field(
default=8,
@@ -479,6 +481,21 @@ class ChatConfig(BaseSettings):
description="Max turns (root included) one root turn may spawn, "
"counted per tree rather than per node so it is enforceable atomically.",
)
+ tree_budget_signal_enabled: bool = Field(
+ default=True,
+ description="Prepend a one-line <budget_status> block to every turn's "
+ "message, and the wrap-up checkpoint once the tree crosses "
+ "``tree_wrapup_threshold``. Off, or on a turn with no tree envelope, "
+ "the prompt is byte-identical to what it was before.",
+ )
+ tree_wrapup_threshold: float = Field(
+ default=0.8,
+ ge=0.0,
+ le=1.0,
+ description="Share of a tree's ceiling at which the wrap-up checkpoint "
+ "is injected, once per tree. Below 1.0 on purpose: the instruction is "
+ "only useful while there is still budget to act on it.",
+ )
claude_agent_context_window: int = Field(
default=200_000,
ge=100_000,
diff --git a/autogpt_platform/backend/backend/copilot/rate_limit.py b/autogpt_platform/backend/backend/copilot/rate_limit.py
index a9117a81c1..93b607d890 100644
--- a/autogpt_platform/backend/backend/copilot/rate_limit.py
+++ b/autogpt_platform/backend/backend/copilot/rate_limit.py
@@ -545,10 +545,11 @@ async def get_remaining_usd_budget(
default); when both windows are uncapped the result is ``inf``.
Failure modes:
- * Redis brown-out → ``floor_usd`` (so callers using the value
- as a soft hint don't pretend the user has full budget; the
- pre-turn gate has already failed closed at 503 in this case,
- so we only land here from observability paths).
+ * Redis brown-out → ``floor_usd``, on every tier (so callers using
+ the value as a soft hint don't pretend the user has full budget;
+ the pre-turn gate has already failed closed at 503 in this case,
+ so we only land here from observability paths). A caller that
+ must tell "unknown" from "$0.00 left" passes a negative floor.
Args:
user_id: The user's ID.
@@ -577,7 +578,7 @@ async def get_remaining_usd_budget(
weekly_used = int(weekly_raw or 0)
except (RedisError, RedisClusterException, ConnectionError, OSError, ValueError):
logger.warning("Redis unavailable for remaining-budget lookup, returning floor")
- return 0.0 if trial else floor_usd
+ return floor_usd
# ``>= 0`` (not ``> 0``): a limit of 0 is "no spend allowed", so the
# remaining is 0 on that window. Mirrors check_rate_limit's semantics:
diff --git a/autogpt_platform/backend/backend/copilot/rate_limit_test.py b/autogpt_platform/backend/backend/copilot/rate_limit_test.py
index b36469b698..396a2c20f1 100644
--- a/autogpt_platform/backend/backend/copilot/rate_limit_test.py
+++ b/autogpt_platform/backend/backend/copilot/rate_limit_test.py
@@ -6,6 +6,8 @@ from unittest.mock import AsyncMock, MagicMock, patch
import pytest
from redis.exceptions import RedisClusterException, RedisError
+from backend.data.subscription_trial import TrialState
+
from .rate_limit import (
_DEFAULT_TIER_MULTIPLIERS,
_DEFAULT_TIER_WORKSPACE_STORAGE_MB,
@@ -2880,6 +2882,32 @@ class TestGetRemainingUsdBudget:
)
assert result == 0.5
+ @pytest.mark.asyncio
+ async def test_an_active_trial_gets_the_same_failure_sentinel(self, mocker):
+ """Every tier answers a brown-out with ``floor_usd``. A trial that
+ returned a hardcoded 0.0 instead was indistinguishable from a trial
+ that had genuinely spent its last cent."""
+ trial = MagicMock(spec=TrialState)
+ trial.active = True
+ store = MagicMock()
+ store.get_subscription_trial = AsyncMock(return_value=trial)
+ mocker.patch("backend.copilot.rate_limit.credit_db", return_value=store)
+ mocker.patch(
+ "backend.copilot.rate_limit._fetch_user_tier",
+ new=AsyncMock(return_value=SubscriptionTier.TRIAL),
+ )
+ with patch(
+ "backend.copilot.rate_limit.get_redis_async",
+ side_effect=RedisError("boom"),
+ ):
+ result = await get_remaining_usd_budget(
+ _USER,
+ daily_cost_limit=10_000_000,
+ weekly_cost_limit=50_000_000,
+ floor_usd=-1.0,
+ )
+ assert result == -1.0
+
@pytest.mark.asyncio
async def test_daily_drives_when_weekly_is_loose(self):
"""Both limits constrain; whichever leaves less budget wins. Here a
diff --git a/autogpt_platform/backend/backend/copilot/sdk/service.py b/autogpt_platform/backend/backend/copilot/sdk/service.py
index 004af86eb7..ac4df0cfbd 100644
--- a/autogpt_platform/backend/backend/copilot/sdk/service.py
+++ b/autogpt_platform/backend/backend/copilot/sdk/service.py
@@ -48,6 +48,7 @@ from backend.copilot.model_router import (
resolve_codex_model_route,
resolve_model_route,
)
+from backend.copilot.budget_signal import build_turn_budget_block
from backend.copilot.graphiti.context import fetch_warm_context
from backend.copilot.markers import append_error_marker
from backend.copilot.provider_failure import ProviderFailure
@@ -5302,8 +5303,15 @@ async def stream_chat_completion_sdk( # pyright: ignore[reportGeneralTypeIssues
for ev in compaction.emit_pre_query_start(forecast.tokens_before):
yield ev
+ # Live budget, every turn — the CLI's own ``max_budget_usd`` reminder is
+ # per-query and knows nothing of the tree. Prepended to the query only,
+ # never to ``current_message``: that is what the transcript records and
+ # the next turn replays, and it must not accumulate one stale figure
+ # per turn.
+ budget_status = await build_turn_budget_block(envelope, user_id)
+
query_message, compaction_stats = await _build_query_message(
- current_message,
+ budget_status + current_message,
session,
use_resume,
transcript_msg_count,
@@ -5506,11 +5514,13 @@ async def stream_chat_completion_sdk( # pyright: ignore[reportGeneralTypeIssues
# falls back to full session.messages[:-1] from DB — the authoritative
# source. transcript+gap is an optimisation for the first attempt only;
# on retry the extra overhead of full-DB context is acceptable.
+ # Keep the ``budget_status +`` prefix through any reflow of this
+ # call: dropping it silently un-ships the retry path's budget line.
(
state.query_message,
state.compaction_stats,
) = await _build_query_message(
- current_message,
+ budget_status + current_message,
session,
state.use_resume,
state.transcript_msg_count,
diff --git a/autogpt_platform/backend/backend/copilot/tools/delegate_to_expert.py b/autogpt_platform/backend/backend/copilot/tools/delegate_to_expert.py
index 22a9303389..a4ca84456a 100644
--- a/autogpt_platform/backend/backend/copilot/tools/delegate_to_expert.py
+++ b/autogpt_platform/backend/backend/copilot/tools/delegate_to_expert.py
@@ -33,6 +33,7 @@ import time
from typing import Any
from backend.api.features.experts.models import Expert
+from backend.copilot.budget_signal import build_spawn_state_note
from backend.copilot.context import get_current_permissions
from backend.copilot.model import (
ChatSession,
@@ -216,16 +217,18 @@ class DelegateToExpertTool(BaseTool):
if outcome == "completed"
else None
)
+ delegated = response_from_outcome(
+ outcome=outcome,
+ result=result,
+ inner_session_id=inner_session_id,
+ parent_session_id=session.session_id,
+ elapsed=elapsed,
+ workspace_files=workspace_files,
+ actor=target.name,
+ )
+ delegated.message += await build_spawn_state_note()
return apply_delegated_expert(
- response_from_outcome(
- outcome=outcome,
- result=result,
- inner_session_id=inner_session_id,
- parent_session_id=session.session_id,
- elapsed=elapsed,
- workspace_files=workspace_files,
- actor=target.name,
- ),
+ delegated,
DelegatedExpertInfo(
id=target.id,
name=target.name,
diff --git a/autogpt_platform/backend/backend/copilot/tools/delegate_to_expert_test.py b/autogpt_platform/backend/backend/copilot/tools/delegate_to_expert_test.py
index 15b9aa8a77..9f80e4ae47 100644
--- a/autogpt_platform/backend/backend/copilot/tools/delegate_to_expert_test.py
+++ b/autogpt_platform/backend/backend/copilot/tools/delegate_to_expert_test.py
@@ -393,6 +393,24 @@ class TestDelegation:
)
assert mock_sessions[0].dry_run is True
+ @pytest.mark.asyncio
+ async def test_the_result_carries_the_tree_state(
+ self, monkeypatch, roster, mock_turn, mock_sessions
+ ):
+ """The parent decides its next spawn from numbers, not a guess."""
+ monkeypatch.setattr(
+ "backend.copilot.tools.delegate_to_expert.build_spawn_state_note",
+ AsyncMock(return_value=" TREE-STATE"),
+ )
+ r = await DelegateToExpertTool()._execute(
+ user_id="alice",
+ session=_session(),
+ expert_id="expert-b",
+ prompt="hi",
+ wait_for_result=0,
+ )
+ assert r.message.endswith(" TREE-STATE")
+
@pytest.mark.asyncio
async def test_handoff_message_names_the_delegating_expert(
self, roster, mock_turn, mock_sessions
diff --git a/autogpt_platform/backend/backend/copilot/tools/handoff_to_expert.py b/autogpt_platform/backend/backend/copilot/tools/handoff_to_expert.py
index 07f397edb7..fb12a8cce2 100644
--- a/autogpt_platform/backend/backend/copilot/tools/handoff_to_expert.py
+++ b/autogpt_platform/backend/backend/copilot/tools/handoff_to_expert.py
@@ -26,6 +26,7 @@ from typing import Any
from backend.api.features.experts.models import Expert
from backend.copilot.active_turns import running_turn_limit_message
+from backend.copilot.budget_signal import build_spawn_state_note
from backend.copilot.context import get_current_permissions
from backend.copilot.model import (
ChatSession,
@@ -198,12 +199,14 @@ class HandoffToExpertTool(BaseTool):
_refused_transfer_message(target.name, outcome, result.refusal),
session,
)
+ transferred = _transferred_response(
+ inner_session_id=inner.session_id,
+ parent_session_id=session.session_id,
+ target_name=target.name,
+ )
+ transferred.message += await build_spawn_state_note()
return apply_delegated_expert(
- _transferred_response(
- inner_session_id=inner.session_id,
- parent_session_id=session.session_id,
- target_name=target.name,
- ),
+ transferred,
# Identity for the ToolChain card, so it names the new owner.
DelegatedExpertInfo(
id=target.id,
diff --git a/autogpt_platform/backend/backend/copilot/tools/handoff_to_expert_test.py b/autogpt_platform/backend/backend/copilot/tools/handoff_to_expert_test.py
index 7a2a3610fd..552a1ba476 100644
--- a/autogpt_platform/backend/backend/copilot/tools/handoff_to_expert_test.py
+++ b/autogpt_platform/backend/backend/copilot/tools/handoff_to_expert_test.py
@@ -433,6 +433,23 @@ class TestTransfer:
)
assert mock_sessions[0].metadata.origin == expected
+ @pytest.mark.asyncio
+ async def test_the_result_carries_the_tree_state(
+ self, monkeypatch, roster, mock_turn, mock_sessions
+ ):
+ """The parent decides its next spawn from numbers, not a guess."""
+ monkeypatch.setattr(
+ "backend.copilot.tools.handoff_to_expert.build_spawn_state_note",
+ AsyncMock(return_value=" TREE-STATE"),
+ )
+ r = await HandoffToExpertTool()._execute(
+ user_id="alice",
+ session=_session(expert_id="expert-a"),
+ expert_id="expert-b",
+ prompt="own the weekly summary",
+ )
+ assert r.message.endswith(" TREE-STATE")
+
@pytest.mark.asyncio
async def test_never_waits_for_a_result(self, roster, mock_turn, mock_sessions):
await HandoffToExpertTool()._execute(
diff --git a/autogpt_platform/backend/backend/copilot/tools/run_sub_session.py b/autogpt_platform/backend/backend/copilot/tools/run_sub_session.py
index a99bb0e4a8..f350889738 100644
--- a/autogpt_platform/backend/backend/copilot/tools/run_sub_session.py
+++ b/autogpt_platform/backend/backend/copilot/tools/run_sub_session.py
@@ -29,6 +29,7 @@ import time
from typing import Any
from backend.copilot.active_turns import running_turn_limit_message
+from backend.copilot.budget_signal import build_spawn_state_note
from backend.copilot.constants import MAX_TOOL_WAIT_SECONDS
from backend.copilot.context import get_current_permissions, get_workspace_manager
from backend.copilot.model import (
@@ -287,6 +288,7 @@ class RunSubSessionTool(BaseTool):
elapsed=elapsed,
workspace_files=workspace_files,
)
+ outcome_response.message += await build_spawn_state_note()
if discarded:
# The row is gone, so its id and link would send the model to poll
# a sub-session that no longer exists. Keep the reason, drop the
diff --git a/autogpt_platform/backend/backend/copilot/tools/sub_session_test.py b/autogpt_platform/backend/backend/copilot/tools/sub_session_test.py
index 56cb5d9017..496857d8e9 100644
--- a/autogpt_platform/backend/backend/copilot/tools/sub_session_test.py
+++ b/autogpt_platform/backend/backend/copilot/tools/sub_session_test.py
@@ -244,6 +244,23 @@ class TestRunSubSession:
assert "is not a session you own" in r.message
mock_queue["enqueue_turn"].assert_not_awaited()
+ @pytest.mark.asyncio
+ async def test_the_result_carries_the_tree_state(
+ self, monkeypatch, mock_queue, mock_waiter, mock_model
+ ):
+ """The parent decides its next spawn from numbers, not a guess."""
+ monkeypatch.setattr(
+ "backend.copilot.tools.run_sub_session.build_spawn_state_note",
+ AsyncMock(return_value=" TREE-STATE"),
+ )
+ r = await RunSubSessionTool()._execute(
+ user_id="alice",
+ session=_session("alice"),
+ prompt="hi",
+ wait_for_result=0,
+ )
+ assert r.message.endswith(" TREE-STATE")
+
@pytest.mark.asyncio
async def test_propagates_dry_run_to_sub(self, mock_queue, mock_waiter, mock_model):
"""Fresh sub-session must inherit the parent's dry_run flag."""
diff --git a/autogpt_platform/backend/backend/copilot/tree.py b/autogpt_platform/backend/backend/copilot/tree.py
index b15e21b9aa..43089f91a7 100644
--- a/autogpt_platform/backend/backend/copilot/tree.py
+++ b/autogpt_platform/backend/backend/copilot/tree.py
@@ -122,6 +122,16 @@ end
return 0
"""
+# ``HEXISTS`` then ``HSETNX`` is two round-trips, and a ledger expiring between
+# them leaves the second recreating the hash with only ``wrapup`` and no TTL —
+# a tree every later ``admit`` reads as closed and nothing ever reaps.
+_CLAIM_WRAPUP_SCRIPT = """
+if redis.call("HEXISTS", KEYS[1], "ceiling") == 0 then
+ return 0
+end
+return redis.call("HSETNX", KEYS[1], "wrapup", "1")
+"""
+
class TreeRefusal(Exception):
"""A turn may not start; ``message`` is written for the model."""
@@ -322,10 +332,7 @@ class TreeLedger:
# so concurrent admits can overshoot by up to ``max_nodes`` turns — see
# the module docstring; the node cap is the bound that holds.
if envelope.depth > 0 and int(spent) >= int(ceiling):
- raise TreeRefusal(
- "This task has spent its budget; report what you have instead "
- "of starting more work."
- )
+ raise TreeRefusal(_spend_refusal(int(spent), int(ceiling)))
nodes = await self._hincrby(key, "nodes", 1)
if nodes > int(max_nodes):
await self._hincrby(key, "nodes", -1)
@@ -348,6 +355,20 @@ class TreeLedger:
return
await self._hincrby(key, "spent", microdollars)
+ async def claim_wrapup(self, tree_id: str) -> bool:
+ """True for the one turn that first crosses the wrap-up threshold.
+
+ ``HSETNX`` is what makes it once-per-tree under concurrent turns; the
+ ``ceiling`` check rides in the same script so a tree that never spawned
+ — or whose ledger has expired — is not conjured back without a TTL.
+ """
+ return bool(
+ await cast(
+ Awaitable[int],
+ self._redis.eval(_CLAIM_WRAPUP_SCRIPT, 1, self.key(tree_id)),
+ )
+ )
+
async def snapshot(self, tree_id: str) -> dict[str, int]:
raw = await cast(
Awaitable[dict[str, str]], self._redis.hgetall(self.key(tree_id))
@@ -373,6 +394,26 @@ class TreeLedger:
return int(value)
+def _spend_refusal(spent: int, ceiling: int) -> str:
+ """Say what is left and what to do instead — an error the model can act on.
+
+ A zero ceiling is not an empty wallet: it is a tier that may not spend at
+ all, and telling that model to "wrap up with what you have" hides why.
+ """
+ if ceiling <= 0:
+ return (
+ "This account has no subscription, so it cannot start sub-sessions. "
+ "Complete the remaining work directly with your tools, or wrap up "
+ "with the results you already have. Do not retry."
+ )
+ return (
+ f"Budget limit reached (${spent / 1_000_000:.2f} spent of the "
+ f"${ceiling / 1_000_000:.2f} maximum for this task). New sub-sessions "
+ "cannot be started. Complete the remaining work directly with your "
+ "tools, or wrap up with the results you already have. Do not retry."
+ )
+
+
async def get_tree_ledger() -> TreeLedger:
return TreeLedger(await get_redis_async())
diff --git a/autogpt_platform/backend/backend/copilot/tree_test.py b/autogpt_platform/backend/backend/copilot/tree_test.py
index f3a7a838a7..541b5f238c 100644
--- a/autogpt_platform/backend/backend/copilot/tree_test.py
+++ b/autogpt_platform/backend/backend/copilot/tree_test.py
@@ -19,6 +19,8 @@ from backend.data.redis_client import AsyncRedisClient
from . import tree
from .tree import (
+ _CLAIM_WRAPUP_SCRIPT,
+ _OPEN_TREE_SCRIPT,
DESCENT_DENIED_TOOLS,
ISOLATE_DENIED_TOOLS,
MAX_DEPTH,
@@ -72,8 +74,14 @@ class FakeRedis:
return _FakePipeline(self)
async def eval(self, script: str, numkeys: int, *args: Any) -> int:
- """Emulate the one Lua script the ledger uses (all-or-nothing open)."""
+ """Emulate the ledger's Lua scripts, dispatching on the script itself
+ so a new one cannot silently inherit another's emulation."""
key = str(args[0])
+ if script == _CLAIM_WRAPUP_SCRIPT:
+ if "ceiling" not in self.hashes.get(key, {}):
+ return 0
+ return await self.hsetnx(key, "wrapup", "1")
+ assert script == _OPEN_TREE_SCRIPT, "unemulated Lua script"
ceiling, max_nodes, nodes, ttl = (str(a) for a in args[1:5])
if key in self.hashes:
return 0
@@ -107,6 +115,17 @@ class _FakePipeline:
return [await getattr(self._redis, name)(*args) for name, args in self._queued]
+class ExpiringRedis(FakeRedis):
+ """A ledger whose TTL fires between two round-trips: the only way to hold
+ an interleaving still in an in-memory fake is to expire on the read."""
+
+ async def hexists(self, key: str, field: str) -> bool:
+ present = await super().hexists(key, field)
+ self.hashes.pop(key, None)
+ self.ttls.pop(key, None)
+ return present
+
+
class BrokenRedis:
def __getattr__(self, name: str):
async def _fail(*_a: Any, **_k: Any) -> None:
@@ -334,6 +353,57 @@ async def test_spend_ceiling_refuses_children_but_not_the_root() -> None:
assert (await ledger.snapshot("t"))["spent"] == 600_000
+async def test_the_spend_refusal_states_the_numbers_and_the_way_out() -> None:
+ ledger = TreeLedger(cast(AsyncRedisClient, FakeRedis()))
+ await ledger.open("t", ceiling_microdollars=500_000, max_nodes=10)
+ root = root_envelope("t")
+ await ledger.charge("t", 520_000)
+ with pytest.raises(TreeRefusal) as refused:
+ await ledger.admit(_child(root))
+ assert "$0.52 spent of the $0.50 maximum" in refused.value.message
+ assert "Complete the remaining work directly with your tools" in (
+ refused.value.message
+ )
+
+
+async def test_a_tier_that_may_not_spend_is_told_so_not_told_it_is_broke() -> None:
+ ledger = TreeLedger(cast(AsyncRedisClient, FakeRedis()))
+ await ledger.open("t", ceiling_microdollars=0, max_nodes=10)
+ with pytest.raises(TreeRefusal) as refused:
+ await ledger.admit(_child(root_envelope("t")))
+ assert "no subscription" in refused.value.message
+ assert "budget" not in refused.value.message.lower()
+
+
+async def test_the_wrap_up_is_claimable_once_and_never_conjures_a_tree() -> None:
+ redis = FakeRedis()
+ ledger = TreeLedger(cast(AsyncRedisClient, redis))
+ assert not await ledger.claim_wrapup("ghost")
+ assert "copilot:tree:ghost" not in redis.hashes
+ await ledger.open("t", ceiling_microdollars=500_000, max_nodes=10)
+ assert await ledger.claim_wrapup("t")
+ assert not await ledger.claim_wrapup("t")
+
+
+async def test_a_wrap_up_claim_never_resurrects_an_expired_ledger() -> None:
+ """Claiming across a separate existence check recreates the hash with only
+ ``wrapup`` and no TTL, which every later admit reads as a closed tree and
+ nothing ever reaps. One round-trip has no point to expire at."""
+ redis = ExpiringRedis()
+ ledger = TreeLedger(cast(AsyncRedisClient, redis))
+ await ledger.open("t", ceiling_microdollars=500_000, max_nodes=10)
+
+ await ledger.claim_wrapup("t")
+
+ key = "copilot:tree:t"
+ assert "ceiling" in redis.hashes.get(key, {}), "claim left a ledger stub"
+ assert key in redis.ttls, "claim left a hash that never expires"
+
+
@pytest.mark.asyncio
async def test_charge_to_unknown_tree_is_ignored() -> None:
redis = FakeRedis()