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): per-tree envelope and ledger for spawned turns (#14244)
Reinier van der Leerd22381f98b6e
diff --git a/autogpt_platform/backend/backend/blocks/autopilot.py b/autogpt_platform/backend/backend/blocks/autopilot.pyindex 8353bf53b1..f3641e096f 100644--- a/autogpt_platform/backend/backend/blocks/autopilot.py+++ b/autogpt_platform/backend/backend/blocks/autopilot.py@@ -437,6 +437,10 @@ class AutoPilotBlock(Block):permissions=effective_permissions,tool_call_id=_AUTOPILOT_TOOL_CALL_ID,tool_name=_AUTOPILOT_TOOL_NAME,+ # Never ride an in-flight turn: the prompt would execute under+ # THAT turn's envelope and permissions, dropping this block's+ # own filter. Same hole the three spawn tools close.+ allow_queue=False,)if outcome == "rejected_concurrent_turn_cap":# No session record / transcript was created — the slot@@ -454,6 +458,11 @@ class AutoPilotBlock(Block):f"{_AUTOPILOT_BLOCK_MAX_WAIT_SECONDS}s — session "f"{session_id}")+ if outcome == "refused":+ # Terminal, like the branches above: nothing ran, so the+ # SessionResult carries only the refusal and its empty+ # response_text would otherwise render as a successful turn.+ raise RuntimeError(result.refusal or "AutoPilot turn was refused")# Build a lightweight conversation summary from the aggregated data.# When ``result.queued`` is True the prompt rode on an already-@@ -846,6 +855,7 @@ async def _enqueue_for_recovery(enqueue_copilot_turn,)from backend.copilot.model import get_chat_session+ from backend.copilot.tree import root_envelopesession = await get_chat_session(session_id, user_id)if session is None:@@ -855,14 +865,21 @@ async def _enqueue_for_recovery()return+ recovery_turn_id = str(uuid.uuid4())await asyncio.wait_for(enqueue_copilot_turn(session_id=session_id,user_id=user_id,message=message,- turn_id=str(uuid.uuid4()),+ turn_id=recovery_turn_id,llm_auth_provider=session.metadata.llm_auth_provider,llm_credential_id=session.metadata.llm_credential_id,+ # The orphaned turn's envelope died with its worker and is not+ # recoverable, so this re-dispatch roots a fresh tree — which+ # is what an AutoPilotBlock turn already gets, the graph+ # executor being a separate process.+ # TODO(#14244-f5): revisit together with run_agent's tree reset.+ envelope=root_envelope(recovery_turn_id),),timeout=10,)diff --git a/autogpt_platform/backend/backend/blocks/autopilot_refusal_test.py b/autogpt_platform/backend/backend/blocks/autopilot_refusal_test.pynew file mode 100644index 0000000000..ae1207e668--- /dev/null+++ b/autogpt_platform/backend/backend/blocks/autopilot_refusal_test.py@@ -0,0 +1,51 @@+"""AutoPilotBlock must treat a refused turn as terminal.++``allow_queue=False`` (autopilot.py) made ``refused`` reachable for this block:+``run_copilot_turn_via_queue`` returns it when the target session already has a+turn in flight, and when the tree ledger refuses the spawn. Without a branch for+it the block falls through and renders an empty ``SessionResult`` as a+successful turn, dropping the refusal.+"""++from unittest.mock import AsyncMock, patch++import pytest++from backend.blocks.autopilot import AutoPilotBlock+from backend.copilot.sdk.session_waiter import SessionResult+++async def test_a_refused_turn_raises_instead_of_returning_an_empty_success():+ refusal = "That session already has a turn in flight."++ with patch(+ "backend.copilot.sdk.session_waiter.run_copilot_turn_via_queue",+ new=AsyncMock(return_value=("refused", SessionResult(refusal=refusal))),+ ):+ with pytest.raises(RuntimeError, match="already has a turn in flight"):+ await AutoPilotBlock().execute_copilot(+ prompt="do the thing",+ system_context="",+ session_id="sess-busy",+ max_recursion_depth=3,+ user_id="u1",+ )+++async def test_a_refusal_with_no_message_still_raises():+ """``SessionResult.refusal`` is optional, so the fallback must not turn an+ empty refusal back into a silent success."""+ with patch(+ "backend.copilot.sdk.session_waiter.run_copilot_turn_via_queue",+ new=AsyncMock(return_value=("refused", SessionResult())),+ ):+ with pytest.raises(RuntimeError, match="refused"):+ await AutoPilotBlock().execute_copilot(+ prompt="do the thing",+ system_context="",+ session_id="sess-busy",+ max_recursion_depth=3,+ user_id="u1",+ )diff --git a/autogpt_platform/backend/backend/copilot/baseline/service.py b/autogpt_platform/backend/backend/copilot/baseline/service.pyindex 051c5b5fda..2c68deff9d 100644--- a/autogpt_platform/backend/backend/copilot/baseline/service.py+++ b/autogpt_platform/backend/backend/copilot/baseline/service.py@@ -160,6 +160,7 @@ from backend.util.tool_call_loop import (if TYPE_CHECKING:from backend.copilot.permissions import CopilotPermissions+ from backend.copilot.tree import TurnEnvelopelogger = logging.getLogger(__name__)@@ -1648,6 +1649,7 @@ async def stream_chat_completion_baseline(session: ChatSession | None = None,file_ids: list[str] | None = None,permissions: "CopilotPermissions | None" = None,+ envelope: "TurnEnvelope | None" = None,context: dict[str, str] | None = None,model: CopilotLLMModel | None = None,request_arrival_at: float = 0.0,@@ -2097,6 +2099,7 @@ async def stream_chat_completion_baseline(sandbox=e2b_sandbox,sdk_cwd=working_dir,permissions=permissions,+ envelope=envelope,)# --- File attachments (feature parity with SDK path) ---diff --git a/autogpt_platform/backend/backend/copilot/config.py b/autogpt_platform/backend/backend/copilot/config.pyindex 5135a376d2..f7479c8eda 100644--- a/autogpt_platform/backend/backend/copilot/config.py+++ b/autogpt_platform/backend/backend/copilot/config.py@@ -430,11 +430,46 @@ class ChatConfig(BaseSettings):default=10.0,ge=0.01,le=1000.0,- description="Maximum spend in USD per SDK query. The CLI attempts "- "to wrap up gracefully when this budget is reached. "- "Set to $10 to allow most tasks to complete (p50=$5.37, p75=$13.07). "+ description="Maximum spend in USD per SDK query — a backstop, not a "+ "target: it sits ~10x above the observed per-TURN p90. Measured over "+ "60 days ending 2026-09-02, one PlatformCostLog row = one turn: "+ "sonnet-5 p50 $0.28 / p75 $0.46 / p90 $0.93 (n=707); "+ "opus-4-8 p50 $0.49 / p90 $1.34 (n=18). Note request < turn < session: "+ "over half of all rows are near-zero utility calls (flash-lite, haiku, "+ "sonar), so unfiltered aggregates understate a real turn. ""Override via CHAT_CLAUDE_AGENT_MAX_BUDGET_USD env var.",)+ tree_ceiling_fraction_of_daily: float = Field(+ default=0.5,+ ge=0.0,+ le=1.0,+ description="Share of the user's tier-scaled DAILY limit that one tree "+ "(a root turn plus everything it spawns) may consume. Scaling off the "+ "tier rather than a flat number keeps the ceiling proportionate: a "+ "NO_TIER user (multiplier 0.0) gets 0, i.e. no spawns at all.",+ )+ tree_ceiling_floor_microdollars: int = Field(+ default=500_000,+ ge=0,+ description="Lower bound on a tree ceiling, in microdollars ($0.50), so "+ "a small daily limit still affords a tree at least one real turn — "+ "per-SESSION spend is p50 $0.49 / p75 $1.14 / p90 $3.25 (n=319, "+ "60 days ending 2026-09-02).",+ )+ tree_ceiling_microdollars: int = Field(+ default=10_000_000,+ ge=0,+ 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.",+ )+ tree_max_nodes: int = Field(+ default=8,+ ge=1,+ description="Max turns (root included) one root turn may spawn, "+ "counted per tree rather than per node so it is enforceable atomically.",+ )claude_agent_context_window: int = Field(default=200_000,ge=100_000,diff --git a/autogpt_platform/backend/backend/copilot/context.py b/autogpt_platform/backend/backend/copilot/context.pyindex 6b3f4cab0a..9ac7532de0 100644--- a/autogpt_platform/backend/backend/copilot/context.py+++ b/autogpt_platform/backend/backend/copilot/context.py@@ -19,6 +19,7 @@ if TYPE_CHECKING:from e2b import AsyncSandboxfrom backend.copilot.permissions import CopilotPermissions+ from backend.copilot.tree import TurnEnvelope# Allowed base directory for the Read tool. Public so service.py can use it@@ -53,6 +54,12 @@ _current_permissions: "ContextVar[CopilotPermissions | None]" = ContextVar("_current_permissions", default=None)+# The running turn's tree envelope. Spawn tools derive a child's envelope+# from this — never from a session row — so a child can only ever narrow it.+_current_envelope: "ContextVar[TurnEnvelope | None]" = ContextVar(+ "_current_envelope", default=None+)+def encode_cwd_for_cli(cwd: str) -> str:"""Encode a working directory path the same way the Claude CLI does.@@ -74,6 +81,7 @@ def set_execution_context(sandbox: "AsyncSandbox | None" = None,sdk_cwd: str | None = None,permissions: "CopilotPermissions | None" = None,+ envelope: "TurnEnvelope | None" = None,) -> None:"""Set per-turn context variables used by file-resolution tool handlers."""_current_user_id.set(user_id)@@ -82,6 +90,7 @@ def set_execution_context(_current_sdk_cwd.set(sdk_cwd or "")_current_project_dir.set(_encode_cwd_for_cli(sdk_cwd) if sdk_cwd else "")_current_permissions.set(permissions)+ _current_envelope.set(envelope)def get_execution_context() -> tuple[str | None, ChatSession | None]:@@ -94,6 +103,11 @@ def get_current_permissions() -> "CopilotPermissions | None":return _current_permissions.get()+def get_current_envelope() -> "TurnEnvelope | None":+ """The running turn's tree envelope; None outside an executor turn."""+ return _current_envelope.get()++def get_current_sandbox() -> "AsyncSandbox | None":"""Return the E2B sandbox for the current session, or None if not active."""return _current_sandbox.get()diff --git a/autogpt_platform/backend/backend/copilot/context_test.py b/autogpt_platform/backend/backend/copilot/context_test.pyindex 0c594bc6b2..c04dcdcd6f 100644--- a/autogpt_platform/backend/backend/copilot/context_test.py+++ b/autogpt_platform/backend/backend/copilot/context_test.py@@ -295,3 +295,64 @@ class TestSdkToolResultRedirectHint:# echoes an empty fragment.msg = sdk_tool_result_redirect_hint("")assert "Offending fragment: ''" in msg+++class TestEnvelopeDoesNotEscapeItsTurn:+ """The turn envelope must not outlive the turn that set it.++ ``mark_session_completed`` → ``dispatch_next_for_user`` → ``dispatch_turn``+ runs inside the driver stream's own ``finally``. If the finished turn's+ envelope were still visible there, the user's *queued* message would be+ promoted as a depth-1 child and silently lose the descent-denied tools.++ What prevents it is that the driver is consumed inside+ ``asyncio.create_task`` (``stream_heartbeat``), which copies the context so+ a ``ContextVar.set`` inside the generator cannot propagate to the caller.+ That is load-bearing and non-obvious — inline the wrapper and every queued+ turn quietly becomes a narrowed child — so it is pinned here.+ """++ @staticmethod+ async def _drive(gen) -> None:+ async for _ in gen:+ pass++ @pytest.mark.asyncio+ async def test_envelope_set_inside_a_task_driven_stream_does_not_leak(self):+ import asyncio++ from backend.copilot.context import get_current_envelope, set_execution_context+ from backend.copilot.tree import root_envelope++ async def driver():+ set_execution_context(None, None, envelope=root_envelope("inner-turn"))+ yield 1++ assert get_current_envelope() is None+ # The task boundary is what isolates it — same shape as stream_heartbeat.+ await asyncio.create_task(self._drive(driver()))+ assert get_current_envelope() is None, (+ "the envelope escaped its turn; a queued user message would now be "+ "promoted as a narrowed child"+ )++ @pytest.mark.asyncio+ async def test_control_generator_driven_without_a_task_does_leak(self):+ """The control that makes the test above meaningful: drive the same+ generator with no task boundary and the envelope *does* escape."""+ from backend.copilot.context import get_current_envelope, set_execution_context+ from backend.copilot.tree import root_envelope++ async def driver():+ set_execution_context(None, None, envelope=root_envelope("leaked"))+ yield 1++ assert get_current_envelope() is None+ try:+ await self._drive(driver())+ leaked = get_current_envelope()+ assert leaked is not None and leaked.tree_id == "leaked"+ finally:+ # An assertion failure here must not cascade into the sibling+ # test: this generator leaks the contextvar deliberately.+ set_execution_context(None, None, envelope=None)diff --git a/autogpt_platform/backend/backend/copilot/executor/entry_points_test.py b/autogpt_platform/backend/backend/copilot/executor/entry_points_test.pynew file mode 100644index 0000000000..ebbd92d102--- /dev/null+++ b/autogpt_platform/backend/backend/copilot/executor/entry_points_test.py@@ -0,0 +1,111 @@+"""Every path that starts a copilot turn must produce an enforced envelope.++The whole per-tree design rests on one property: a turn that reaches the+executor carries a :class:`TurnEnvelope`. A turn without one is unenforced end+to end — ``BaseTool.execute`` no-ops and its first spawn is minted as a fresh+root — and that is invisible to every other test, because such a turn behaves+exactly like a pre-feature turn.++These tests guard the property structurally rather than by listing known+callers, so a new entry point added later cannot quietly opt out.+"""++from __future__ import annotations++import ast+import inspect+import pathlib++from backend.copilot.executor.utils import enqueue_copilot_turn++# .../backend/backend — the package root the sweep walks.+_PACKAGE_ROOT = pathlib.Path(__file__).resolve().parents[2]+++def test_enqueue_requires_an_envelope_argument() -> None:+ """Required and keyword-only, so omitting it is a TypeError at the call+ site rather than a silently unenforced turn at runtime."""+ parameter = inspect.signature(enqueue_copilot_turn).parameters["envelope"]+ assert parameter.default is inspect.Parameter.empty+ assert parameter.kind is inspect.Parameter.KEYWORD_ONLY+++def test_no_call_site_enqueues_a_turn_without_an_envelope() -> None:+ """AST sweep of the whole backend: every call to ``enqueue_copilot_turn``+ passes ``envelope=`` explicitly (or forwards ``**kwargs``)."""+ offenders: list[str] = []+ for path in _PACKAGE_ROOT.rglob("*.py"):+ try:+ tree = ast.parse(path.read_text(), filename=str(path))+ except SyntaxError: # not ours to police+ continue+ for node in ast.walk(tree):+ if not isinstance(node, ast.Call):+ continue+ func = node.func+ name = (+ func.attr+ if isinstance(func, ast.Attribute)+ else func.id if isinstance(func, ast.Name) else None+ )+ if name != "enqueue_copilot_turn":+ continue+ if not _passes_a_real_envelope(node):+ offenders.append(f"{path.relative_to(_PACKAGE_ROOT)}:{node.lineno}")+ assert not offenders, (+ "these call sites start a turn with no envelope, which leaves it "+ f"unenforced and mints its first spawn as a root: {offenders}"+ )+++def test_no_engine_re_entry_drops_the_envelope() -> None:+ """The engines re-enter themselves (auto-continue), and those calls are a+ second way to produce an unenforced turn: the parameter defaults to None,+ which clears the contextvar for the rest of the turn even though the turn+ genuinely has an envelope. Swept for the same reason as the enqueue sites.+ """+ offenders: list[str] = []+ targets = {"stream_chat_completion_sdk", "stream_chat_completion_baseline"}+ for path in _PACKAGE_ROOT.rglob("*.py"):+ if path.name.endswith("_test.py"):+ continue+ try:+ tree = ast.parse(path.read_text(), filename=str(path))+ except SyntaxError:+ continue+ for node in ast.walk(tree):+ if not isinstance(node, ast.Call):+ continue+ func = node.func+ name = (+ func.attr+ if isinstance(func, ast.Attribute)+ else func.id if isinstance(func, ast.Name) else None+ )+ if name not in targets:+ continue+ if not _passes_a_real_envelope(node):+ offenders.append(f"{path.relative_to(_PACKAGE_ROOT)}:{node.lineno}")+ assert not offenders, (+ "these engine calls omit envelope=, which defaults to None and leaves "+ f"the rest of the turn unenforced: {offenders}"+ )+++def _passes_a_real_envelope(node: ast.Call) -> bool:+ """A literal ``envelope=None`` is the unenforced turn these sweeps exist+ to prevent, so it does not count as deciding. ``**kwargs`` forwarding does+ — the decision is then the caller's."""+ for kw in node.keywords:+ if kw.arg == "envelope":+ return not (isinstance(kw.value, ast.Constant) and kw.value.value is None)+ # Only once no explicit envelope= was found: ``f(**kw, envelope=None)`` is+ # still the unenforced call, whatever ``kw`` happens to hold.+ return any(kw.arg is None for kw in node.keywords)+++def test_chat_platform_turns_are_rooted_and_born_tainted() -> None:+ """A chat-platform message is authored off-platform by someone who need+ not be the account owner, so its turn roots a tree and carries taint."""+ source = (_PACKAGE_ROOT / "platform_linking" / "chat.py").read_text()+ assert "envelope=root_envelope(turn_id, tainted=True)" in sourcediff --git a/autogpt_platform/backend/backend/copilot/executor/processor.py b/autogpt_platform/backend/backend/copilot/executor/processor.pyindex 10b4056a9e..782c5a308f 100644--- a/autogpt_platform/backend/backend/copilot/executor/processor.py+++ b/autogpt_platform/backend/backend/copilot/executor/processor.py@@ -44,6 +44,7 @@ from .utils import CoPilotExecutionEntry, CoPilotLogMetadataif TYPE_CHECKING:from backend.copilot.model import ChatSession+ from backend.copilot.tree import TurnEnvelopelogger = TruncatedLogger(logging.getLogger(__name__), prefix="[CoPilotExecutor]")@@ -134,6 +135,21 @@ def sync_fail_close_session(log.warning(f"sync fail-close mark_session_completed failed: {e}")+def taint_for_source_platform(+ envelope: "TurnEnvelope | None", session: "ChatSession"+) -> "TurnEnvelope | None":+ """Mark a turn tainted when its prompt came from a chat platform.++ Those prompts are authored off-platform by someone who need not be the+ account owner, so anything the turn spawns must inherit the bit. Taint+ only ever rises, and a turn with no envelope stays that way rather than+ having one invented for it.+ """+ if envelope is None or not session.metadata.source_platform or envelope.tainted:+ return envelope+ return envelope.model_copy(update={"tainted": True})++# ============ Mode Routing ============ #@@ -625,6 +641,7 @@ class CoPilotProcessor:# publishing so subscribers on the session Redis stream# (e.g. wait_for_session_result, SSE clients) receive the# same events as they are produced.+ envelope = taint_for_source_platform(entry.envelope, session)raw_stream = stream_fn(session_id=entry.session_id,message=entry.message or None,@@ -634,6 +651,7 @@ class CoPilotProcessor:file_ids=entry.file_ids,model=entry.model,permissions=entry.permissions,+ envelope=envelope,request_arrival_at=entry.request_arrival_at,organization_id=(session.organization_iddiff --git a/autogpt_platform/backend/backend/copilot/executor/processor_test.py b/autogpt_platform/backend/backend/copilot/executor/processor_test.pyindex ed766933c7..43633f74ed 100644--- a/autogpt_platform/backend/backend/copilot/executor/processor_test.py+++ b/autogpt_platform/backend/backend/copilot/executor/processor_test.py@@ -1407,3 +1407,28 @@ class TestBuildingModeForcesSdk:new=AsyncMock(return_value=session),):assert await _building_mode_forces_sdk(session.session_id) is True+++def test_a_chat_platform_session_promotes_its_envelope_to_tainted():+ """A chat-platform prompt is authored off-platform by someone who need not+ be the account owner, so the turn's envelope must carry taint. This is the+ taint bit's only producer today and nothing asserted it.+ """+ from backend.copilot.executor.processor import taint_for_source_platform+ from backend.copilot.tree import root_envelope++ clean = root_envelope("turn-1")+ assert clean.tainted is False++ web = MagicMock()+ web.metadata.source_platform = None+ assert taint_for_source_platform(clean, web) is clean++ slack = MagicMock()+ slack.metadata.source_platform = "slack"+ promoted = taint_for_source_platform(clean, slack)+ assert promoted.tainted is True+ assert promoted.tree_id == clean.tree_id++ # No envelope (a legacy queue entry) stays None rather than inventing one.+ assert taint_for_source_platform(None, slack) is Nonediff --git a/autogpt_platform/backend/backend/copilot/executor/utils.py b/autogpt_platform/backend/backend/copilot/executor/utils.pyindex 07696cd087..e0eb7d565c 100644--- a/autogpt_platform/backend/backend/copilot/executor/utils.py+++ b/autogpt_platform/backend/backend/copilot/executor/utils.py@@ -18,7 +18,17 @@ from backend.copilot.active_turns import (inflight_turn_limit_message,)from backend.copilot.config import CopilotLlmAuthProvider, CopilotLLMModel+from backend.copilot.context import get_current_envelopefrom backend.copilot.permissions import CopilotPermissions+from backend.copilot.tree import (+ SpawnRequest,+ TreeRefusal,+ TurnEnvelope,+ admit_turn,+ derive_child_envelope,+ release_turn,+ root_envelope,+)from backend.data.rabbitmq import Exchange, ExchangeType, Queue, RabbitMQConfigfrom backend.util.logging import TruncatedLogger, is_structured_logging_enabled@@ -220,6 +230,11 @@ class CoPilotExecutionEntry(BaseModel):forwards its parent's permissions so the sub can't escalate). ``None``means the worker applies no filter."""+ envelope: TurnEnvelope | None = None+ """The turn's tree envelope (depth, tool ceiling, taint, deadline), derived+ at dispatch from the spawning turn's. ``None`` only for entries queued+ before the field existed."""+request_arrival_at: float = 0.0"""Unix-epoch seconds (server clock) when the originating HTTP``/stream`` request arrived. The executor's turn-start drain uses@@ -255,9 +270,19 @@ async def enqueue_copilot_turn(llm_credential_id: str | None = None,permissions: CopilotPermissions | None = None,request_arrival_at: float = 0.0,+ *,+ envelope: TurnEnvelope,) -> None:"""Enqueue a CoPilot task for processing by the executor service.+ ``envelope`` is required and keyword-only on purpose. Every turn belongs to+ a tree, and a turn that arrives without one is unenforced end to end: the+ ``BaseTool.execute`` check no-ops and its first spawn is minted as a fresh+ root. Making the parameter mandatory means a new entry point has to decide+ which tree its turn belongs to rather than silently opting out.+ ``CoPilotExecutionEntry.envelope`` stays optional so a message enqueued by+ an older worker still decodes.+Args:session_id: Chat session ID (also used for dedup/locking)user_id: User ID (may be None for anonymous users)@@ -288,6 +313,7 @@ async def enqueue_copilot_turn(llm_credential_id=llm_credential_id,permissions=permissions,request_arrival_at=request_arrival_at,+ envelope=envelope,)queue_client = await get_async_copilot_queue()@@ -316,6 +342,7 @@ async def schedule_turn(llm_credential_id: str | None = None,permissions: CopilotPermissions | None = None,request_arrival_at: float = 0.0,+ spawn: SpawnRequest | None = None,) -> None:"""End-to-end "start a copilot turn": reserve a per-user concurrencyslot, register the session in the stream registry, then publish the@@ -381,6 +408,7 @@ async def schedule_turn(llm_credential_id=llm_credential_id,permissions=permissions,request_arrival_at=request_arrival_at,+ spawn=spawn,)@@ -403,11 +431,17 @@ async def dispatch_turn(llm_credential_id: str | None = None,permissions: CopilotPermissions | None = None,request_arrival_at: float = 0.0,+ spawn: SpawnRequest | None = None,) -> None:"""Within an already-held turn slot, register the session in thestream registry, publish the work to the executor queue, andtransfer slot ownership to ``mark_session_completed``.+ This is the one chokepoint every turn passes — HTTP chat, scheduler,+ ``AutoPilotBlock``, and the three spawn tools — so it is where the+ turn's tree envelope is derived and admitted. A spawned turn that the+ tree refuses raises :class:`TreeRefusal` before any side effect.+Caller is responsible for acquiring ``slot`` via:func:`acquire_turn_slot`. This function is the post-acquire dispatchglue — extracted so the HTTP chat route (which needs to save the@@ -423,14 +457,13 @@ async def dispatch_turn(# COPILOT_CONSUMER_TIMEOUT_SECONDS constant) → top-level circular.from backend.copilot import stream_registry- await stream_registry.create_session(- session_id=session_id,- user_id=user_id,- tool_call_id=tool_call_id,- tool_name=tool_name,- turn_id=turn_id,- )+ envelope = await _admitted_turn_envelope(turn_id, user_id, permissions, spawn)+ # Everything after the admit above runs inside the try: the tree's node+ # counter is already incremented, so an exception from ``create_session``+ # (a Redis blip) would otherwise leak a node for the key's whole TTL, and+ # a handful of those exhaust a tree that never ran anything.+ ## Once ``create_session`` has written Redis meta, EVERY exit path# from this point on must either (a) commit the turn (``slot.keep()``# + RabbitMQ message enqueued) or (b) tear the Redis meta down — or@@ -440,6 +473,17 @@ async def dispatch_turn(# happy path from any failure / cancellation.committed = Falsetry:+ # Inside the try on purpose: the admit above already incremented the+ # tree's node count, so anything that can raise between there and the+ # finally must be covered by ``release_turn``.+ permissions = _narrow_permissions(permissions, envelope)+ await stream_registry.create_session(+ session_id=session_id,+ user_id=user_id,+ tool_call_id=tool_call_id,+ tool_name=tool_name,+ turn_id=turn_id,+ )await enqueue_copilot_turn(session_id=session_id,user_id=user_id,@@ -455,11 +499,13 @@ async def dispatch_turn(llm_credential_id=llm_credential_id,permissions=permissions,request_arrival_at=request_arrival_at,+ envelope=envelope,)slot.keep()committed = Truefinally:if not committed:+ await release_turn(envelope)try:await stream_registry.delete_session_meta(session_id)except BaseException:@@ -471,6 +517,68 @@ async def dispatch_turn()+async def _admitted_turn_envelope(+ turn_id: str,+ user_id: str | None,+ permissions: CopilotPermissions | None,+ spawn: SpawnRequest | None,+) -> TurnEnvelope:+ """Derive this turn's envelope from the running turn's (a child) or mint+ a root, then admit it against the tree ledger.++ The spawner's envelope comes from the executor contextvar, so a caller+ outside any turn — the HTTP route, the scheduler, a graph block — is a+ root by construction rather than by declaration.+ """+ spawner = get_current_envelope()+ if spawn is not None and spawner is None:+ # A caller that passed a SpawnRequest is by construction a spawn tool+ # running inside a turn, so a missing spawner envelope means the+ # context was lost — a pre-deploy queue entry, or a refactor that+ # dropped it. Minting a root there would hand the child FULL+ # authority, which is the opposite of what the caller asked for, so+ # refuse instead. This also makes the stream_heartbeat task boundary+ # belt-and-braces rather than load-bearing.+ raise TreeRefusal(+ "This task's context was lost, so its limits cannot be carried "+ "over. Start it again from the top."+ )+ if spawner is None:+ envelope = root_envelope(turn_id)+ else:+ envelope = derive_child_envelope(+ spawner, spawn or SpawnRequest(), spawner_permissions=permissions+ )+ await admit_turn(envelope, user_id=user_id)+ return envelope+++def _narrow_permissions(+ permissions: CopilotPermissions | None, envelope: TurnEnvelope+) -> CopilotPermissions | None:+ """The envelope's tool set as the turn's whitelist, keeping any block+ filter the caller passed. Hides the tools from the model; the refusal+ itself lives in ``BaseTool.execute``."""+ narrowed = envelope.as_permissions()+ if narrowed is None:+ return permissions+ if permissions is None:+ return narrowed+ # The caller's ``_parent`` is dropped on purpose: it belongs to the+ # spawner's turn, and the envelope is already the narrower bound.+ #+ # ``tools_exclude`` is carried, never hardcoded: an empty envelope encodes+ # deny-all as a blacklist of every tool, and forcing ``False`` here would+ # reread that as a whitelist of every tool — the exact inversion the+ # encoding exists to prevent.+ return CopilotPermissions(+ tools=narrowed.tools,+ tools_exclude=narrowed.tools_exclude,+ blocks=permissions.blocks,+ blocks_exclude=permissions.blocks_exclude,+ )++async def schedule_chat_turn(*,session_id: str,diff --git a/autogpt_platform/backend/backend/copilot/executor/utils_test.py b/autogpt_platform/backend/backend/copilot/executor/utils_test.pyindex 91369cdf12..db0129f222 100644--- a/autogpt_platform/backend/backend/copilot/executor/utils_test.py+++ b/autogpt_platform/backend/backend/copilot/executor/utils_test.py@@ -15,7 +15,9 @@ from backend.copilot.executor.utils import (CoPilotLogMetadata,create_copilot_queue_config,)+from backend.copilot.permissions import CopilotPermissionsfrom backend.copilot.prompting import VOICE_TURN_TAG+from backend.copilot.tree import ALL_TOOL_NAMES, root_envelope@pytest.mark.asyncio@@ -245,3 +247,37 @@ async def test_schedule_chat_turn_leaves_an_already_saved_message_alone() -> Non)assert dispatch.await_args.kwargs["message"] == "kick it off"+++class TestNarrowPermissions:+ """The envelope's tool set becomes the turn's whitelist. The encoding of+ "no tools at all" is the trap: it is a blacklist of every tool, and a+ merge that hardcodes the whitelist flag reads it back as its opposite.+ """++ def test_a_locked_envelope_stays_locked_when_merged_with_a_block_filter(+ self,+ ) -> None:+ locked = root_envelope("t").model_copy(update={"tools": frozenset()})+ caller = CopilotPermissions(blocks=["some-block"], blocks_exclude=False)++ merged = utils._narrow_permissions(caller, locked)++ assert merged is not None+ # Deny-all is encoded as "blacklist everything"; flipping the flag+ # would turn the same list into "whitelist everything".+ assert merged.tools_exclude is True+ assert merged.effective_allowed_tools(ALL_TOOL_NAMES) == set()+ assert merged.blocks == ["some-block"]++ def test_a_narrowed_envelope_merges_as_a_whitelist(self) -> None:+ narrowed = root_envelope("t").model_copy(+ update={"tools": frozenset({"read_workspace_file"})}+ )+ caller = CopilotPermissions(blocks=["some-block"], blocks_exclude=False)++ merged = utils._narrow_permissions(caller, narrowed)++ assert merged is not None+ assert merged.tools_exclude is False+ assert merged.effective_allowed_tools(ALL_TOOL_NAMES) == {"read_workspace_file"}diff --git a/autogpt_platform/backend/backend/copilot/permissions.py b/autogpt_platform/backend/backend/copilot/permissions.pyindex 846f023514..92fab31429 100644--- a/autogpt_platform/backend/backend/copilot/permissions.py+++ b/autogpt_platform/backend/backend/copilot/permissions.py@@ -489,8 +489,13 @@ def apply_tool_permissions(elif short in TOOL_REGISTRY:names.append(f"{MCP_TOOL_PREFIX}{short}")elif short in _SDK_TO_MCP:- # Map SDK built-in file tool to its MCP equivalent.+ # Offer BOTH spellings and let the ``base_allowed`` filter below+ # pick the one this mode registers: outside E2B only ``read_file``+ # has an MCP wrapper, and the MCP spelling of Write/Edit is not in+ # ``base_allowed``, so mapping them solely to it drops them from+ # every filtered turn.names.append(f"{MCP_TOOL_PREFIX}{_SDK_TO_MCP[short]}")+ names.append(short)else:names.append(short) # SDK built-in — used as-isreturn namesdiff --git a/autogpt_platform/backend/backend/copilot/permissions_test.py b/autogpt_platform/backend/backend/copilot/permissions_test.pyindex a9153826e3..53d3ff7141 100644--- a/autogpt_platform/backend/backend/copilot/permissions_test.py+++ b/autogpt_platform/backend/backend/copilot/permissions_test.py@@ -715,3 +715,55 @@ class TestDreamPermissionsPreset:"memory_forget_confirm",})+++class TestApplyToolPermissionsIsLossless:+ """A filter that permits everything must be indistinguishable from no+ filter. It was not: outside E2B only ``read_file`` has an MCP wrapper, so+ mapping ``Write``/``Edit`` solely to their MCP names dropped them from+ every filtered turn — silently, since an absent tool just never gets+ called. Children are the only turns that carry a filter, so this removed+ file editing from every spawned agent on non-E2B deployments."""++ @pytest.mark.parametrize("use_e2b", [False, True])+ def test_identity_whitelist_equals_no_filter(self, use_e2b: bool) -> None:+ from backend.copilot.permissions import (+ ALL_TOOL_NAMES,+ CopilotPermissions,+ apply_tool_permissions,+ )++ identity = CopilotPermissions(tools=sorted(ALL_TOOL_NAMES), tools_exclude=False)+ allowed_identity, _ = apply_tool_permissions(identity, use_e2b=use_e2b)+ allowed_unfiltered, _ = apply_tool_permissions(+ CopilotPermissions(), use_e2b=use_e2b+ )+ assert set(allowed_identity) == set(allowed_unfiltered)++ @pytest.mark.parametrize("use_e2b", [False, True])+ def test_a_child_keeps_its_file_tools(self, use_e2b: bool) -> None:+ from backend.copilot.permissions import (+ CopilotPermissions,+ apply_tool_permissions,+ )+ from backend.copilot.tree import (+ DESCENT_DENIED_TOOLS,+ SpawnRequest,+ derive_child_envelope,+ root_envelope,+ )++ child = derive_child_envelope(root_envelope("t"), SpawnRequest(may_spawn=True))+ child_permissions = child.as_permissions()+ assert child_permissions is not None+ allowed_child, _ = apply_tool_permissions(child_permissions, use_e2b=use_e2b)+ allowed_unfiltered, _ = apply_tool_permissions(+ CopilotPermissions(), use_e2b=use_e2b+ )+ lost = set(allowed_unfiltered) - set(allowed_child)+ # A child loses exactly the descent-denied set — nothing else.+ assert lost == {+ name+ for name in allowed_unfiltered+ if name.rsplit("__", 1)[-1] in DESCENT_DENIED_TOOLS+ }diff --git a/autogpt_platform/backend/backend/copilot/sdk/service.py b/autogpt_platform/backend/backend/copilot/sdk/service.pyindex 31e757fff2..8954cd6cd3 100644--- a/autogpt_platform/backend/backend/copilot/sdk/service.py+++ b/autogpt_platform/backend/backend/copilot/sdk/service.py@@ -23,6 +23,7 @@ from typing import TYPE_CHECKING, Any, NamedTuple, NotRequired, castif TYPE_CHECKING:from ..permissions import CopilotPermissions+ from ..tree import TurnEnvelopefrom claude_agent_sdk import (AssistantMessage,@@ -4458,6 +4459,7 @@ async def stream_chat_completion_sdk( # pyright: ignore[reportGeneralTypeIssuessession: ChatSession | None = None,file_ids: list[str] | None = None,permissions: "CopilotPermissions | None" = None,+ envelope: "TurnEnvelope | None" = None,model: CopilotLLMModel | None = None,request_arrival_at: float = 0.0,organization_id: str | None = None,@@ -4830,6 +4832,7 @@ async def stream_chat_completion_sdk( # pyright: ignore[reportGeneralTypeIssuessandbox=e2b_sandbox,sdk_cwd=sdk_cwd,permissions=permissions,+ envelope=envelope,)if (@@ -6319,6 +6322,11 @@ async def stream_chat_completion_sdk( # pyright: ignore[reportGeneralTypeIssuessession=session,file_ids=None,permissions=permissions,+ # Same turn continuing, so it keeps its envelope. Omitting+ # it would default to None and clear the contextvar for the+ # remainder of the turn: tool enforcement off, spend+ # uncharged, and the next spawn minted as an unbounded root.+ envelope=envelope,model=model,organization_id=organization_id,team_id=team_id,diff --git a/autogpt_platform/backend/backend/copilot/sdk/session_waiter.py b/autogpt_platform/backend/backend/copilot/sdk/session_waiter.pyindex 992c175f87..8143d96107 100644--- a/autogpt_platform/backend/backend/copilot/sdk/session_waiter.py+++ b/autogpt_platform/backend/backend/copilot/sdk/session_waiter.py@@ -32,6 +32,7 @@ from backend.copilot.pending_message_helpers import (queue_user_message,)from backend.copilot.response_model import StreamError, StreamFinish+from backend.copilot.tree import SpawnRequest, TreeRefusalfrom .stream_accumulator import EventAccumulator, ToolCallEntry, process_event@@ -47,6 +48,7 @@ SessionOutcome = Literal["running","queued","rejected_concurrent_turn_cap",+ "refused",]@@ -69,6 +71,9 @@ class SessionResult:total_tokens: int = 0queued: bool = Falsepending_buffer_length: int = 0+ # Why the turn never started, when the outcome is ``refused``. Written+ # for the model: it names the bound that was hit.+ refusal: str = ""async def wait_for_session_result(@@ -137,9 +142,23 @@ async def run_copilot_turn_via_queue(permissions: "CopilotPermissions | None" = None,tool_call_id: str,tool_name: str,+ spawn: SpawnRequest | None = None,+ allow_queue: bool = True,) -> tuple[SessionOutcome, SessionResult]:"""Dispatch a copilot turn onto the queue and wait for its result.+ ``spawn`` is what the caller asks for the child's tree envelope; the+ chokepoint clamps it. ``allow_queue=False`` refuses the in-flight+ fallback below: a spawn tool must never append its prompt into a turn+ that is already running under a different envelope.++ That is a deliberate behaviour change, not just a new flag. Continuing a+ delegation to a teammate who is still working (``delegate_to_expert`` with+ ``delegated_session_id``) used to queue into their running turn; it now+ returns ``refused`` with a message telling the caller to wait or start+ fresh. ``AutoPilotBlock`` passes no ``spawn``, but it does pass+ ``allow_queue=False`` for the same reason, and raises on ``refused``.+The canonical invocation path shared by ``run_sub_session`` (thecopilot tool), ``AutoPilotBlock`` (the graph block), and any futurecaller that needs to run a copilot turn without occupying its own@@ -178,6 +197,14 @@ async def run_copilot_turn_via_queue(raise RuntimeError("copilot_session_not_found")if await is_turn_in_flight(session_id):+ if not allow_queue:+ return "refused", SessionResult(+ refusal=(+ "That session already has a turn in flight, so this task "+ "cannot be handed to it right now. Wait for it to finish, "+ "or start a fresh one."+ )+ )logger.info("[queue] session=%s has a turn in flight; queueing message ""(tool=%s) into pending buffer instead of starting a new turn",@@ -223,7 +250,10 @@ async def run_copilot_turn_via_queue(llm_auth_provider=session.metadata.llm_auth_provider,llm_credential_id=session.metadata.llm_credential_id,permissions=permissions,+ spawn=spawn,)+ except TreeRefusal as refused:+ return "refused", SessionResult(refusal=refused.message)except ConcurrentTurnLimitError:# Sub-AutoPilot / run_sub_session caller is at the cap (this is# the graph-block / tool path, not the HTTP route). Use adiff --git a/autogpt_platform/backend/backend/copilot/sdk/session_waiter_test.py b/autogpt_platform/backend/backend/copilot/sdk/session_waiter_test.pyindex 358ab76059..9c1e4d7ddb 100644--- a/autogpt_platform/backend/backend/copilot/sdk/session_waiter_test.py+++ b/autogpt_platform/backend/backend/copilot/sdk/session_waiter_test.py@@ -246,3 +246,66 @@ async def test_idle_session_concurrent_turn_cap_returns_rejected_outcome():create_session.assert_not_awaited()enqueue.assert_not_awaited()wait_result.assert_not_awaited()+++async def test_in_flight_session_with_allow_queue_false_is_refused():+ """``allow_queue=False`` must refuse an in-flight target rather than+ append to its buffer — a spawn's prompt would otherwise execute inside+ another turn's envelope and permissions. Covered directly, because the+ only other coverage is through mocked callers, so deleting the guard+ would leave those green."""+ queue_message = AsyncMock()++ with (+ patch(+ "backend.copilot.sdk.session_waiter.is_turn_in_flight",+ new=AsyncMock(return_value=True),+ ),+ patch(+ "backend.copilot.sdk.session_waiter.queue_user_message",+ new=queue_message,+ ),+ ):+ outcome, result = await run_copilot_turn_via_queue(+ session_id="sess-busy",+ user_id="u1",+ message="do the thing",+ timeout=5,+ tool_call_id="autopilot_block",+ tool_name="autopilot_block",+ allow_queue=False,+ )++ assert outcome == "refused"+ assert result.refusal, "a refusal must carry a message the model can act on"+ queue_message.assert_not_awaited()+++async def test_a_tree_refusal_becomes_the_refused_outcome():+ """A ledger refusal (budget or node cap) reaches the caller as+ ``refused`` carrying the ledger's own message, not as ``failed``."""+ from backend.copilot.tree import TreeRefusal++ with (+ patch(+ "backend.copilot.sdk.session_waiter.is_turn_in_flight",+ new=AsyncMock(return_value=False),+ ),+ patch(+ "backend.copilot.sdk.session_waiter.schedule_turn",+ new=AsyncMock(side_effect=TreeRefusal("This task's tree has closed.")),+ ),+ ):+ outcome, result = await run_copilot_turn_via_queue(+ session_id="sess-idle",+ user_id="u1",+ message="spawn",+ timeout=5,+ tool_call_id="sub:parent",+ tool_name="run_sub_session",+ )++ assert outcome == "refused"+ assert result.refusal == "This task's tree has closed."diff --git a/autogpt_platform/backend/backend/copilot/sdk/tool_adapter.py b/autogpt_platform/backend/backend/copilot/sdk/tool_adapter.pyindex 90362b5238..047756e800 100644--- a/autogpt_platform/backend/backend/copilot/sdk/tool_adapter.py+++ b/autogpt_platform/backend/backend/copilot/sdk/tool_adapter.py@@ -18,6 +18,7 @@ from claude_agent_sdk import create_sdk_mcp_server, toolfrom mcp.types import ToolAnnotationsfrom backend.copilot.context import (+ _current_envelope,_current_permissions,_current_project_dir,_current_sandbox,@@ -61,6 +62,7 @@ if TYPE_CHECKING:from e2b import AsyncSandboxfrom backend.copilot.permissions import CopilotPermissions+ from backend.copilot.tree import TurnEnvelopelogger = logging.getLogger(__name__)@@ -128,6 +130,7 @@ def set_execution_context(sandbox: "AsyncSandbox | None" = None,sdk_cwd: str | None = None,permissions: "CopilotPermissions | None" = None,+ envelope: "TurnEnvelope | None" = None,) -> None:"""Set the execution context for tool calls.@@ -140,6 +143,7 @@ def set_execution_context(sandbox: Optional E2B sandbox; when set, bash_exec routes commands there.sdk_cwd: SDK working directory; used to scope tool-results reads.permissions: Optional capability filter restricting tools/blocks.+ envelope: The turn's tree envelope; spawn tools derive children from it."""_current_user_id.set(user_id)_current_session.set(session)@@ -147,6 +151,7 @@ def set_execution_context(_current_sdk_cwd.set(sdk_cwd or "")_current_project_dir.set(_encode_cwd_for_cli(sdk_cwd) if sdk_cwd else "")_current_permissions.set(permissions)+ _current_envelope.set(envelope)_pending_tool_outputs.set({})_stash_event.set(asyncio.Event())_consecutive_tool_failures.set({})diff --git a/autogpt_platform/backend/backend/copilot/token_tracking.py b/autogpt_platform/backend/backend/copilot/token_tracking.pyindex 872db7d4c9..0930e5a1c1 100644--- a/autogpt_platform/backend/backend/copilot/token_tracking.py+++ b/autogpt_platform/backend/backend/copilot/token_tracking.py@@ -21,8 +21,10 @@ from backend.copilot.trial_cost_context import get_trial_cost_contextfrom backend.data.db_accessors import platform_cost_dbfrom backend.data.platform_cost import PlatformCostEntry, usd_to_microdollars+from .context import get_current_envelopefrom .model import ChatSession, Usagefrom .rate_limit import record_cost_usage+from .tree import charge_turnlogger = logging.getLogger(__name__)@@ -222,15 +224,23 @@ async def persist_and_record_usage(cost_microdollars = usd_to_microdollars(cost_float)- if user_id and cost_microdollars is not None and cost_microdollars > 0:- # record_cost_usage() owns its fail-open handling for Redis/network- # errors. Don't wrap with a broad except here — unexpected accounting- # bugs should surface instead of being silently logged as warnings.- await record_cost_usage(- user_id=user_id,- cost_microdollars=cost_microdollars,- skip_daily=skip_daily,- )+ if cost_microdollars is not None and cost_microdollars > 0:+ if user_id:+ # record_cost_usage() owns its fail-open handling for Redis/network+ # errors. Don't wrap with a broad except here — unexpected accounting+ # bugs should surface instead of being silently logged as warnings.+ await record_cost_usage(+ user_id=user_id,+ cost_microdollars=cost_microdollars,+ skip_daily=skip_daily,+ )+ # Same charge, second ledger: the tree this turn belongs to. A tree is+ # identified by its root turn, not by a user, so this must not sit+ # behind the user_id guard — an anonymous turn still spends its tree's+ # budget.+ envelope = get_current_envelope()+ if envelope is not None:+ await charge_turn(envelope, cost_microdollars)# Log to PlatformCostLog for admin cost dashboard.# Include entries where cost_usd is set even if token count is 0diff --git a/autogpt_platform/backend/backend/copilot/token_tracking_test.py b/autogpt_platform/backend/backend/copilot/token_tracking_test.pyindex 6238bce7ab..aa1c7374ea 100644--- a/autogpt_platform/backend/backend/copilot/token_tracking_test.py+++ b/autogpt_platform/backend/backend/copilot/token_tracking_test.py@@ -613,3 +613,35 @@ class TestPlatformCostLogging:# Negative cost rejected — falls back to token-based trackingassert entry.cost_microdollars is Noneassert entry.metadata["tracking_type"] == "tokens"+++async def test_usage_charges_the_tree_ledger(monkeypatch):+ """The tree charge is the only thing that makes the spend ceiling bind;+ nothing asserted it was reached, or with what amount."""+ from backend.copilot import token_tracking+ from backend.copilot.context import set_execution_context+ from backend.copilot.tree import TurnEnvelope++ charged: list[tuple[str, int]] = []++ async def _charge(envelope, microdollars):+ charged.append((envelope.tree_id, microdollars))++ monkeypatch.setattr(token_tracking, "charge_turn", _charge)+ monkeypatch.setattr(token_tracking, "record_cost_usage", AsyncMock())+ monkeypatch.setattr(token_tracking, "_schedule_cost_log", lambda entry: None)++ set_execution_context("u1", None, envelope=TurnEnvelope(tree_id="tree-9", depth=1))+ try:+ await token_tracking.persist_and_record_usage(+ session=None,+ user_id="u1",+ prompt_tokens=10,+ completion_tokens=5,+ cost_usd=0.25,+ )+ finally:+ set_execution_context(None, None, envelope=None)++ assert charged == [("tree-9", 250_000)]diff --git a/autogpt_platform/backend/backend/copilot/tools/base.py b/autogpt_platform/backend/backend/copilot/tools/base.pyindex ceb6406a77..450b6ff93d 100644--- a/autogpt_platform/backend/backend/copilot/tools/base.py+++ b/autogpt_platform/backend/backend/copilot/tools/base.py@@ -7,6 +7,7 @@ from typing import Anyfrom openai.types.chat import ChatCompletionToolParam+from backend.copilot.context import get_current_envelopefrom backend.copilot.model import ChatSessionfrom backend.copilot.response_model import StreamToolOutputAvailablefrom backend.data.activity_event import ActivityEventDraft@@ -395,6 +396,29 @@ class BaseTool:success=False,)+ # Hiding a tool from the schema is presentation; this is the boundary.+ # A spawned turn's envelope can only ever be narrower than its spawner's.+ envelope = get_current_envelope()+ if envelope is not None and not envelope.permits(self.name):+ logger.warning(+ "Refusing tool outside turn envelope: tool=%s session=%s depth=%s",+ self.name,+ session.session_id,+ envelope.depth,+ )+ return StreamToolOutputAvailable(+ toolCallId=tool_call_id,+ toolName=self.name,+ output=ErrorResponse(+ message=(+ f"{self.name} is not available in this delegated turn. "+ "If the task needs it, say so in your report instead."+ ),+ session_id=session.session_id,+ ).model_dump_json(),+ success=False,+ )+try:result = await self._execute(user_id, session, **kwargs)if user_id:diff --git a/autogpt_platform/backend/backend/copilot/tools/base_test.py b/autogpt_platform/backend/backend/copilot/tools/base_test.pyindex e9a9e96283..6230699efe 100644--- a/autogpt_platform/backend/backend/copilot/tools/base_test.py+++ b/autogpt_platform/backend/backend/copilot/tools/base_test.py@@ -20,6 +20,7 @@ from backend.copilot.tools.base import (from backend.copilot.tools.models import (BlockDetails,BlockDetailsResponse,+ ErrorResponse,ResponseType,ToolResponseBase,)@@ -507,3 +508,95 @@ class TestOutline:_, outline = _outline_of(data, 600)assert "more nodes not shown" in outlineassert len(outline) <= 600+++class TestEnvelopeEnforcement:+ """`BaseTool.execute` must REFUSE a tool outside the turn's envelope.++ Hiding a tool from the model's schema is presentation; this is the+ boundary. Without this test the enforcement block can be deleted and the+ whole suite stays green.+ """++ @pytest.mark.asyncio+ async def test_a_tool_outside_the_envelope_is_refused_and_never_executed(+ self, monkeypatch+ ):+ from backend.copilot.context import set_execution_context+ from backend.copilot.tree import TurnEnvelope++ class _Spy(BaseTool):+ def __init__(self) -> None:+ self.ran = False++ @property+ def name(self) -> str:+ return "delete_preset"++ @property+ def description(self) -> str:+ return "spy"++ @property+ def parameters(self) -> dict:+ return {"type": "object", "properties": {}}++ async def _execute(self, user_id, session, **kwargs):+ self.ran = True+ raise AssertionError("_execute must not run for a denied tool")++ tool = _Spy()+ session = MagicMock(session_id="s1")+ set_execution_context(+ "u1",+ None,+ envelope=TurnEnvelope(+ tree_id="t", depth=1, tools=frozenset({"read_workspace_file"})+ ),+ )+ try:+ result = await tool.execute("u1", session, "call-1")+ finally:+ set_execution_context(None, None, envelope=None)++ assert result.success is False+ assert tool.ran is False, "the denied tool's body executed anyway"++ @pytest.mark.asyncio+ async def test_a_permitted_tool_still_runs(self, monkeypatch):+ from backend.copilot.context import set_execution_context+ from backend.copilot.tree import TurnEnvelope++ class _Ok(BaseTool):+ def __init__(self) -> None:+ self.ran = False++ @property+ def name(self) -> str:+ return "read_workspace_file"++ @property+ def description(self) -> str:+ return "ok"++ @property+ def parameters(self) -> dict:+ return {"type": "object", "properties": {}}++ async def _execute(self, user_id, session, **kwargs):+ self.ran = True+ return ErrorResponse(message="fine", session_id="s1")++ tool = _Ok()+ set_execution_context(+ "u1",+ None,+ envelope=TurnEnvelope(+ tree_id="t", depth=1, tools=frozenset({"read_workspace_file"})+ ),+ )+ try:+ await tool.execute("u1", MagicMock(session_id="s1"), "call-2")+ finally:+ set_execution_context(None, None, envelope=None)+ assert tool.ran is Truediff --git a/autogpt_platform/backend/backend/copilot/tools/delegate_to_expert.py b/autogpt_platform/backend/backend/copilot/tools/delegate_to_expert.pyindex 131992ea12..a8e83095f7 100644--- a/autogpt_platform/backend/backend/copilot/tools/delegate_to_expert.py+++ b/autogpt_platform/backend/backend/copilot/tools/delegate_to_expert.py@@ -41,6 +41,7 @@ from backend.copilot.model import (get_chat_session,)from backend.copilot.sdk.session_waiter import run_copilot_turn_via_queue+from backend.copilot.tree import SpawnRequestfrom backend.data.db_accessors import experts_dbfrom .base import BaseTool@@ -54,6 +55,7 @@ from .models import DelegatedExpertInfo, ErrorResponse, ToolResponseBasefrom .run_sub_session import (MAX_SUB_SESSION_WAIT_SECONDS,apply_delegated_expert,+ discard_unused_sub_session,list_sub_workspace_files,response_from_outcome,)@@ -193,8 +195,22 @@ class DelegateToExpertTool(BaseTool):f"delegate:{session.session_id}" if session.session_id else "delegate"),tool_name="delegate_to_expert",+ # A teammate keeps their own teammates; depth still bounds the chain.+ spawn=SpawnRequest(may_spawn=True),+ allow_queue=False,)elapsed = time.monotonic() - started_at+ discarded = (+ not delegated_session_id.strip()+ and await discard_unused_sub_session(inner_session_id, user_id, outcome)+ )+ if discarded:+ # The thread is gone; handing back its id would send the model to+ # poll a delegation that no longer exists.+ return self._error(+ result.refusal or f"{target.name} could not start this task.",+ session,+ )workspace_files = (await list_sub_workspace_files(user_id, inner_session_id)if outcome == "completed"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.pyindex 015c5d324e..b09bab3664 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@@ -828,3 +828,74 @@ class TestCallerNameFraming:)assert "from a teammate," in mock_turn.await_args.kwargs["message"]+++class TestRefusedDelegationCleanup:+ """A delegation refused after its session row exists would otherwise show+ the teammate an empty thread for work that never started."""++ async def test_a_refused_delegation_deletes_the_thread_it_opened(+ self, roster, mock_turn, mock_sessions, monkeypatch+ ):+ deleted = AsyncMock()+ # The helper is defined in run_sub_session, so the binding it calls+ # lives there, not in the module under test.+ monkeypatch.setattr(+ "backend.copilot.tools.run_sub_session.delete_chat_session", deleted+ )+ mock_turn.return_value = ("refused", SessionResult(refusal="over budget"))++ await DelegateToExpertTool()._execute(+ user_id="alice",+ session=_session(expert_id="expert-a"),+ expert_id="expert-b",+ prompt="draft the ops update",+ )++ deleted.assert_awaited_once_with("inner-1", "alice")++ async def test_a_refused_delegation_returns_no_handle_to_the_deleted_thread(+ self, roster, mock_turn, mock_sessions, monkeypatch+ ):+ monkeypatch.setattr(+ "backend.copilot.tools.run_sub_session.delete_chat_session", AsyncMock()+ )+ mock_turn.return_value = ("refused", SessionResult(refusal="over budget"))++ result = await DelegateToExpertTool()._execute(+ user_id="alice",+ session=_session(expert_id="expert-a"),+ expert_id="expert-b",+ prompt="draft the ops update",+ )++ assert isinstance(result, ErrorResponse)+ assert "inner-1" not in result.model_dump_json()++ async def test_a_refused_resume_keeps_the_prior_thread(+ self, roster, mock_turn, mock_sessions, monkeypatch+ ):+ deleted = AsyncMock()+ monkeypatch.setattr(+ "backend.copilot.tools.run_sub_session.delete_chat_session", deleted+ )+ caller = _session(expert_id="expert-a")+ await DelegateToExpertTool()._execute(+ user_id="alice",+ session=caller,+ expert_id="expert-b",+ prompt="draft the ops update",+ wait_for_result=0,+ )+ mock_turn.return_value = ("refused", SessionResult(refusal="over budget"))++ await DelegateToExpertTool()._execute(+ user_id="alice",+ session=caller,+ expert_id="expert-b",+ prompt="one more thing",+ delegated_session_id="inner-1",+ )++ deleted.assert_not_awaited()diff --git a/autogpt_platform/backend/backend/copilot/tools/expert_delegation.py b/autogpt_platform/backend/backend/copilot/tools/expert_delegation.pyindex 8e53513e89..a2c0069d81 100644--- a/autogpt_platform/backend/backend/copilot/tools/expert_delegation.py+++ b/autogpt_platform/backend/backend/copilot/tools/expert_delegation.py@@ -16,6 +16,7 @@ import loggingfrom backend.api.features.experts.models import Expertfrom backend.copilot.model import ChatSession, get_chat_session+from backend.copilot.tree import MAX_DEPTHfrom backend.data.db_accessors import experts_dblogger = logging.getLogger(__name__)@@ -25,10 +26,9 @@ logger = logging.getLogger(__name__)CALLER_NAME_LIMIT = 80# How many hops a single task may travel between experts, whether delegated or-# handed over. Each hop is a fresh session with a fresh delegator, so without-# this nothing downstream would ever notice a chain — or a loop — sustaining-# itself on the user's credits.-MAX_DELEGATION_DEPTH = 3+# handed over. The turn envelope enforces the same bound for every spawn kind;+# this walk stays as the loop check and as belt-and-braces on the depth.+MAX_DELEGATION_DEPTH = MAX_DEPTH# The preamble delimits itself with square brackets, so a name containing them# can close the framing early and open a block of its own.diff --git a/autogpt_platform/backend/backend/copilot/tools/get_sub_session_result.py b/autogpt_platform/backend/backend/copilot/tools/get_sub_session_result.pyindex 160eb1e955..66e23ea3f8 100644--- a/autogpt_platform/backend/backend/copilot/tools/get_sub_session_result.py+++ b/autogpt_platform/backend/backend/copilot/tools/get_sub_session_result.py@@ -270,6 +270,12 @@ def _in_caller_scope(sub: ChatSession, session: ChatSession) -> bool:and nobody else — poll across the boundary. A hand-off transfersownership for good (the caller gets no result back), so it grants nosuch capability: only the receiving expert's own scope can read it.++ Subs carry the same provenance, but scope equality stays the first+ test: a same-scope sub is the caller's own assistant, and the+ receiving expert must be able to read a task handed to it. The creator+ restriction that stops a session steering a sub it did not open lives on+ the resume path in ``run_sub_session``, where the prompt is written."""if sub.expert_id == session.expert_id:return Truediff --git a/autogpt_platform/backend/backend/copilot/tools/handoff_to_expert.py b/autogpt_platform/backend/backend/copilot/tools/handoff_to_expert.pyindex 783bbe7d31..54cffa7f06 100644--- a/autogpt_platform/backend/backend/copilot/tools/handoff_to_expert.py+++ b/autogpt_platform/backend/backend/copilot/tools/handoff_to_expert.py@@ -35,8 +35,10 @@ from backend.copilot.model import ()from backend.copilot.sdk.session_waiter import (SessionOutcome,+ SessionResult,run_copilot_turn_via_queue,)+from backend.copilot.tree import SpawnRequestfrom backend.data.db_accessors import experts_dbfrom .base import BaseTool@@ -176,7 +178,7 @@ class HandoffToExpertTool(BaseTool):handed_off_from_expert_id=session.expert_id,origin=child_session_origin(session.metadata),)- outcome = await self._queue_task(+ outcome, result = await self._queue_task(user_id, session, inner.session_id, prompt, context)if outcome not in _OWNERSHIP_TAKEN:@@ -192,7 +194,10 @@ class HandoffToExpertTool(BaseTool):inner.session_id,exc_info=True,)- return self._error(_refused_transfer_message(target.name, outcome), session)+ return self._error(+ _refused_transfer_message(target.name, outcome, result.refusal),+ session,+ )return apply_delegated_expert(_transferred_response(inner_session_id=inner.session_id,@@ -216,10 +221,10 @@ class HandoffToExpertTool(BaseTool):inner_session_id: str,prompt: str,context: str,- ) -> SessionOutcome:+ ) -> tuple[SessionOutcome, SessionResult]:"""Push the framed task onto the target's session. Never waits."""caller = await self._caller_name(user_id, session.expert_id)- outcome, _result = await run_copilot_turn_via_queue(+ return await run_copilot_turn_via_queue(session_id=inner_session_id,user_id=user_id,message=_transfer_message(caller, context, prompt),@@ -229,8 +234,9 @@ class HandoffToExpertTool(BaseTool):f"handoff:{session.session_id}" if session.session_id else "handoff"),tool_name="handoff_to_expert",+ spawn=SpawnRequest(may_spawn=True),+ allow_queue=False,)- return outcomedef _error(self, message: str, session: ChatSession) -> ErrorResponse:return ErrorResponse(message=message, session_id=session.session_id)@@ -327,7 +333,9 @@ def _transferred_response()-def _refused_transfer_message(target_name: str, outcome: SessionOutcome) -> str:+def _refused_transfer_message(+ target_name: str, outcome: SessionOutcome, refusal: str = ""+) -> str:"""Say plainly that nothing moved, so the model doesn't announce a handoffthat never happened and then drop the task."""if outcome == "rejected_concurrent_turn_cap":@@ -335,6 +343,11 @@ def _refused_transfer_message(target_name: str, outcome: SessionOutcome) -> str:f"The handoff to {target_name} did not happen — the task is still "f"yours. {running_turn_limit_message()}")+ if outcome == "refused" and refusal:+ return (+ f"The handoff to {target_name} did not happen — the task is still "+ f"yours. {refusal}"+ )return (f"The handoff to {target_name} did not happen — their session could not ""take the task, so it is still yours. Do it yourself or try again."diff --git a/autogpt_platform/backend/backend/copilot/tools/run_sub_session.py b/autogpt_platform/backend/backend/copilot/tools/run_sub_session.pyindex 85902cbb58..39a8544951 100644--- a/autogpt_platform/backend/backend/copilot/tools/run_sub_session.py+++ b/autogpt_platform/backend/backend/copilot/tools/run_sub_session.py@@ -31,13 +31,19 @@ from typing import Anyfrom backend.copilot.active_turns import running_turn_limit_messagefrom backend.copilot.constants import MAX_TOOL_WAIT_SECONDSfrom backend.copilot.context import get_current_permissions, get_workspace_manager-from backend.copilot.model import ChatSession, create_chat_session, get_chat_session+from backend.copilot.model import (+ ChatSession,+ create_chat_session,+ delete_chat_session,+ get_chat_session,+)from backend.copilot.sdk.session_waiter import (SessionOutcome,SessionResult,run_copilot_turn_via_queue,)from backend.copilot.sdk.stream_accumulator import ToolCallEntry+from backend.copilot.tree import SpawnRequestfrom .base import BaseToolfrom .models import (@@ -164,6 +170,28 @@ class RunSubSessionTool(BaseTool):),session_id=session.session_id,)+ # Only the session that opened a sub may steer it: same scope is+ # not enough, or any sibling — or the sub itself — could queue a+ # prompt into it under its envelope rather than their own.+ #+ # Subs created before this tool started recording provenance have+ # ``None`` here and cannot satisfy the check. Refusing them would+ # strand every in-flight sub at deploy, so they fall back to the+ # scope + origin rules that governed them when they were made —+ # the group is closed (nothing new joins it) and ages out with the+ # 6h turn lifetime.+ if (+ owned.metadata.delegated_by_session_id is not None+ and owned.metadata.delegated_by_session_id != session.session_id+ ):+ return ErrorResponse(+ message=(+ f"sub_autopilot_session_id {sub_session_param} was not "+ "started by this session. Leave empty to start a fresh "+ "sub."+ ),+ session_id=session.session_id,+ )# Subs are created as automations below, so only a sub may be# resumed as one. Otherwise this tool would run a model-authored# prompt inside an interactive session the caller happens to own,@@ -195,6 +223,7 @@ class RunSubSessionTool(BaseTool):session_id=session.session_id,)inner_session_id = sub_session_param+ opened_here = Falseelse:new_session = await create_chat_session(user_id,@@ -204,6 +233,14 @@ class RunSubSessionTool(BaseTool):llm_auth_provider=session.metadata.llm_auth_provider,llm_credential_id=session.metadata.llm_credential_id,expert_id=session.expert_id,+ # Provenance doubles as the resume capability above and as+ # the poll capability in get_sub_session_result. It also makes+ # subs visible to ``chain_refusal``'s walk, which is intended:+ # a sub hop spends delegation budget like any other hop (both+ # bounds refuse the same 4th hop), and a sub delegating back+ # to its own parent expert is seen as the loop it is.+ delegated_by_expert_id=session.expert_id,+ delegated_by_session_id=session.session_id,# A sub is machine-driven whatever opened it: its prompt is# written by the parent model, not typed by the user, and no# tool restriction applies to it. Inheriting an "interactive"@@ -212,6 +249,7 @@ class RunSubSessionTool(BaseTool):origin="automation",)inner_session_id = new_session.session_id+ opened_here = Trueeffective_prompt = promptif system_context.strip():@@ -227,14 +265,21 @@ class RunSubSessionTool(BaseTool):permissions=get_current_permissions(),tool_call_id=(f"sub:{session.session_id}" if session.session_id else "sub"),tool_name="run_sub_session",+ # An isolate shares its spawner's memory namespace, so it must not+ # write to it; depth bounds how far it may spawn onward.+ spawn=SpawnRequest(may_spawn=True, shares_memory=True),+ allow_queue=False,)elapsed = time.monotonic() - started_at+ discarded = opened_here and await discard_unused_sub_session(+ inner_session_id, user_id, outcome+ )workspace_files = (await list_sub_workspace_files(user_id, inner_session_id)if outcome == "completed"else None)- return response_from_outcome(+ outcome_response = response_from_outcome(outcome=outcome,result=result,inner_session_id=inner_session_id,@@ -242,6 +287,14 @@ class RunSubSessionTool(BaseTool):elapsed=elapsed,workspace_files=workspace_files,)+ 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+ # handles — the same shape handoff_to_expert returns on refusal.+ return ErrorResponse(+ message=outcome_response.message, session_id=session.session_id+ )+ return outcome_responsedef apply_delegated_expert(@@ -389,6 +442,39 @@ def _as_payload(output: Any) -> dict[str, Any] | None:return None+# Outcomes meaning the turn never reached the sub's session, so the row we+# opened for it holds nothing. Notably NOT ``failed``: there the turn ran and+# errored, and its thread is the only record of that.+_NOTHING_QUEUED: frozenset[SessionOutcome] = frozenset(+ {"refused", "rejected_concurrent_turn_cap"}+)+++async def discard_unused_sub_session(+ session_id: str, user_id: str, outcome: SessionOutcome+) -> bool:+ """Drop a thread opened for a turn that was then refused, reporting+ whether it is gone.++ A tree refusal or the concurrent-turn cap rejects the turn after the+ session row exists, leaving an empty conversation the user can open from+ their history. Callers use the return value to withhold the sub-session+ handles, which would otherwise point at a row that no longer exists.+ Best-effort by contract: a failed cleanup must not turn a refusal into an+ error, so it reports False and the handles stay valid.+ """+ if outcome not in _NOTHING_QUEUED:+ return False+ try:+ await delete_chat_session(session_id, user_id)+ except Exception:+ logger.warning(+ "Failed to clean up unused sub-session %s", session_id, exc_info=True+ )+ return False+ return True++def response_from_outcome(*,outcome: SessionOutcome,@@ -452,6 +538,18 @@ def response_from_outcome(elapsed_seconds=round(elapsed, 2),)+ if outcome == "refused":+ # The turn never started; the tree or the target said why.+ return SubSessionStatusResponse(+ message=result.refusal or f"{actor} could not start this task.",+ session_id=parent_session_id,+ status="error",+ sub_session_id=inner_session_id,+ sub_autopilot_session_id=inner_session_id,+ sub_autopilot_session_link=link,+ elapsed_seconds=round(elapsed, 2),+ )+if outcome == "rejected_concurrent_turn_cap":# No sub-session record / transcript exists yet — the per-user# concurrent-turn cap rejected before ``create_session`` ran.diff --git a/autogpt_platform/backend/backend/copilot/tools/sub_session_test.py b/autogpt_platform/backend/backend/copilot/tools/sub_session_test.pyindex b85db893da..77267d89bb 100644--- a/autogpt_platform/backend/backend/copilot/tools/sub_session_test.py+++ b/autogpt_platform/backend/backend/copilot/tools/sub_session_test.py@@ -49,6 +49,10 @@ def _session(sess.metadata.llm_auth_provider = "platform"sess.metadata.llm_credential_id = Nonesess.metadata.origin = origin+ # Explicit: a bare MagicMock attribute is "not None", which would make a+ # legacy sub look like one with provenance and fail the creator check.+ sess.metadata.delegated_by_session_id = None+ sess.metadata.handed_off_from_expert_id = Nonesess.expert_id = expert_idreturn sess@@ -154,10 +158,15 @@ def mock_model(monkeypatch):llm_credential_id: str | None = None,expert_id: str | None = None,origin: str = "interactive",+ delegated_by_expert_id: str | None = None,+ delegated_by_session_id: str | None = None,):sess = MagicMock()sess.session_id = f"inner-{len(created) + 1}"sess.metadata.origin = origin+ sess.metadata.delegated_by_expert_id = delegated_by_expert_id+ sess.metadata.delegated_by_session_id = delegated_by_session_id+ sess.metadata.handed_off_from_expert_id = Nonesess.user_id = user_idsess.dry_run = dry_runsess.organization_id = organization_id@@ -322,6 +331,8 @@ class TestRunSubSession:``autopilot_session_guard`` lets reach the staffing tools."""interactive_sub = _session("alice", "other-session", origin="interactive")+ # Passes the creator check so the origin check is what refuses.+ interactive_sub.metadata.delegated_by_session_id = "s1"async def fake_get(_session_id: str):return interactive_sub@@ -354,6 +365,9 @@ class TestRunSubSession:"""legacy_sub = _session("alice", "other-session", origin=None)legacy_sub.messages = []+ # Deliberately no provenance: this is the pre-provenance sub the+ # resume path has to keep accepting at deploy.+ assert legacy_sub.metadata.delegated_by_session_id is Noneasync def fake_get(_session_id: str):return legacy_sub@@ -373,6 +387,47 @@ class TestRunSubSession:assert not isinstance(result, ErrorResponse)assert mock_waiter.await_args.kwargs["session_id"] == "other-session"+ @pytest.mark.asyncio+ async def test_resume_requires_the_creating_session(+ self, monkeypatch, mock_queue, mock_waiter+ ):+ """Same scope is not enough: a sibling (or the sub itself) must not be+ able to queue a prompt into a sub it did not open."""+ someone_elses_sub = _session("alice", "other-session", origin="automation")+ someone_elses_sub.metadata.delegated_by_session_id = "sibling-session"++ async def fake_get(_session_id: str):+ return someone_elses_sub++ monkeypatch.setattr(+ "backend.copilot.tools.run_sub_session.get_chat_session", fake_get+ )++ result = await RunSubSessionTool()._execute(+ user_id="alice",+ session=_session("alice", "s1", origin="automation"),+ prompt="continue",+ sub_autopilot_session_id="other-session",+ )++ assert isinstance(result, ErrorResponse)+ assert "not started by this session" in result.message+ mock_queue["enqueue_turn"].assert_not_awaited()++ @pytest.mark.asyncio+ async def test_fresh_sub_records_its_creator(+ self, mock_queue, mock_waiter, mock_model+ ):+ await RunSubSessionTool()._execute(+ user_id="alice",+ session=_session("alice", "s1", expert_id="expert-a"),+ prompt="do it",+ wait_for_result=0,+ )+ created = mock_model["created"][0]+ assert created.metadata.delegated_by_session_id == "s1"+ assert created.metadata.delegated_by_expert_id == "expert-a"+@pytest.mark.asyncioasync def test_forwards_parent_permissions_to_queue(self, monkeypatch, mock_queue, mock_waiter, mock_model@@ -642,6 +697,7 @@ class TestGetSubSessionResult:@pytest.mark.asyncioasync def test_wait_returns_running(self, monkeypatch, mock_waiter):sub = MagicMock(user_id="alice", expert_id=None, messages=[])+ sub.metadata.delegated_by_session_id = Noneasync def fake_get(_sid):return sub@@ -676,6 +732,7 @@ class TestGetSubSessionResult:sub = MagicMock(user_id="alice", expert_id=None, messages=[]) # not terminal-looking+ sub.metadata.delegated_by_session_id = Noneasync def fake_get(_sid):return sub@@ -713,6 +770,7 @@ class TestGetSubSessionResult:wait_for_session_result — it rebuilds the response from thepersisted message instead."""sub = MagicMock(user_id="alice", expert_id=None)+ sub.metadata.delegated_by_session_id = Noneassistant = MagicMock()assistant.role = "assistant"assistant.content = "already done"@@ -759,6 +817,7 @@ class TestGetSubSessionResult:prior.content = "OLD stale result"prior.tool_calls = Nonesub = MagicMock(user_id="alice", expert_id=None, messages=[prior])+ sub.metadata.delegated_by_session_id = Noneasync def fake_get(_sid):return sub@@ -798,6 +857,7 @@ class TestGetSubSessionResult:"""cancel=true fans out a CancelCoPilotEvent and returns 'cancelled'without waiting for the sub to finish (the worker will finalise)."""sub = MagicMock(user_id="alice", expert_id=None, messages=[])+ sub.metadata.delegated_by_session_id = Noneasync def fake_get(_sid):return sub@@ -828,6 +888,7 @@ class TestGetSubSessionResult:populated from the authoritative workspace listing."""sub = MagicMock(user_id="alice", expert_id=None)+ sub.metadata.delegated_by_session_id = Noneassistant = MagicMock()assistant.role = "assistant"assistant.content = "done — see the docs I wrote"@@ -1063,3 +1124,102 @@ class TestActorParameter:result = apply_delegated_expert(response, expert)assert result.message == response.messageassert "Sub-AutoPilot" not in (result.message or "")+++class TestSpawnEnvelopeArguments:+ """The spawn shape each tool asks for is a security property, not a+ detail: flipping shares_memory to False silently regrants an isolate+ memory_store under the parent's identity, and allow_queue=True lets a+ prompt run under another turn's envelope. Neither was asserted anywhere.+ """++ @pytest.mark.asyncio+ async def test_run_sub_session_spawns_a_memory_sharing_isolate_and_never_queues(+ self, mock_queue, mock_waiter, mock_model+ ):+ await RunSubSessionTool()._execute(+ user_id="alice",+ session=_session("alice", "s1"),+ prompt="do it",+ wait_for_result=0,+ )+ kwargs = mock_waiter.await_args.kwargs+ assert kwargs["allow_queue"] is False+ assert kwargs["spawn"].shares_memory is True+ assert kwargs["spawn"].may_spawn is True+++class TestRefusedSpawnCleanup:+ """A refusal arrives after the sub's session row exists. Without cleanup+ the user's history fills with empty threads for turns that never ran.+ """++ async def test_a_refused_spawn_deletes_the_thread_it_opened(+ self, mock_queue, mock_waiter, mock_model, monkeypatch+ ):+ deleted = AsyncMock()+ monkeypatch.setattr(+ "backend.copilot.tools.run_sub_session.delete_chat_session", deleted+ )+ mock_waiter.return_value = ("refused", SessionResult(refusal="over budget"))++ await RunSubSessionTool()._execute(+ user_id="alice", session=_session("alice", "s1"), prompt="do it"+ )++ deleted.assert_awaited_once_with("inner-1", "alice")++ async def test_a_refused_spawn_returns_no_handle_to_the_deleted_thread(+ self, mock_queue, mock_waiter, mock_model, monkeypatch+ ):+ monkeypatch.setattr(+ "backend.copilot.tools.run_sub_session.delete_chat_session", AsyncMock()+ )+ mock_waiter.return_value = ("refused", SessionResult(refusal="over budget"))++ result = await RunSubSessionTool()._execute(+ user_id="alice", session=_session("alice", "s1"), prompt="do it"+ )++ assert isinstance(result, ErrorResponse)+ assert "over budget" in result.message+ assert "inner-1" not in result.model_dump_json()++ async def test_a_failed_turn_keeps_its_thread(+ self, mock_queue, mock_waiter, mock_model, monkeypatch+ ):+ deleted = AsyncMock()+ monkeypatch.setattr(+ "backend.copilot.tools.run_sub_session.delete_chat_session", deleted+ )+ # The turn ran and errored, so the thread is the only record of it.+ mock_waiter.return_value = ("failed", SessionResult())++ await RunSubSessionTool()._execute(+ user_id="alice", session=_session("alice", "s1"), prompt="do it"+ )++ deleted.assert_not_awaited()++ async def test_a_refused_resume_keeps_the_prior_thread(+ self, mock_queue, mock_waiter, mock_model, monkeypatch+ ):+ deleted = AsyncMock()+ monkeypatch.setattr(+ "backend.copilot.tools.run_sub_session.delete_chat_session", deleted+ )+ parent = _session("alice", "s1")+ await RunSubSessionTool()._execute(+ user_id="alice", session=parent, prompt="first", wait_for_result=0+ )+ mock_waiter.return_value = ("refused", SessionResult(refusal="over budget"))++ await RunSubSessionTool()._execute(+ user_id="alice",+ session=parent,+ prompt="again",+ sub_autopilot_session_id="inner-1",+ )++ deleted.assert_not_awaited()diff --git a/autogpt_platform/backend/backend/copilot/tools/tool_schema_test.py b/autogpt_platform/backend/backend/copilot/tools/tool_schema_test.pyindex 413c2e2492..d85e4d1a4f 100644--- a/autogpt_platform/backend/backend/copilot/tools/tool_schema_test.py+++ b/autogpt_platform/backend/backend/copilot/tools/tool_schema_test.py@@ -126,6 +126,10 @@ from backend.copilot.tools import TOOL_REGISTRY# both look correct: each one's CI only measures its own delta against dev, while# the budget has to cover what every in-flight PR adds together. Taking the# incoming side lowers a ceiling that has already ejected a green PR.+#+# Measure it the way this test does — one json.dumps over the whole list —+# not by summing per-tool lengths, which misses ~142 chars of array+# separators and overstates the headroom._CHAR_BUDGET = 65_000diff --git a/autogpt_platform/backend/backend/copilot/tree.py b/autogpt_platform/backend/backend/copilot/tree.pynew file mode 100644index 0000000000..75b24d24cc--- /dev/null+++ b/autogpt_platform/backend/backend/copilot/tree.py@@ -0,0 +1,468 @@+"""Per-tree bounds for spawned copilot turns.++Every copilot turn belongs to a *tree* rooted in a turn nobody spawned — a+human typing, a schedule firing, an ``AutoPilotBlock``. A turn that a tool+spawns (``run_sub_session``, ``delegate_to_expert``, ``handoff_to_expert``)+is a child in its spawner's tree. Two objects carry the bounds:++- :class:`TurnEnvelope` — per turn, immutable, travels on the queue entry.+ Derived by :func:`derive_child_envelope` from the *spawning turn's*+ envelope by operations that can only narrow (depth + 1 toward a cap, tool+ set intersected, deadline min, taint or-ed). Nothing a model supplies can+ widen it, and nothing reads it off a session row.+- :class:`TreeLedger` — per tree, mutable, one Redis hash. A turn is admitted+ at ``dispatch_turn`` only while the tree's metered spend is under its+ ceiling and its node count under its cap. Cost is charged after each turn+ by the same path that feeds the per-user rate limit.++The ledger meters; it does not reserve. That is deliberate: the SDK's+``max_budget_usd`` is a per-query stop that floors upward and does not exist+on the Codex transport, so a reservation could never be enforced — a counter+checked at the one seam every turn passes through can.++What that costs, stated accurately: admission reads spend recorded by turns+that have *finished*, so turns admitted concurrently do not see each other's+cost. A tree can therefore overshoot its ceiling by up to ``max_nodes``+in-flight turns, not by one. The node cap is what bounds it — which is the+reason the two limits are enforced together and why ``max_nodes`` is small.++Reachable surface, stated plainly so nobody reads more into this module than+it currently does. Live today: ``depth``, ``tools`` via the descent/isolate+defaults and ``grant``, the node cap and the spend ceiling. Carried but not+yet driven by any tool: ``tainted`` (propagated and tested, but no consumer+reads it until the auto-mode gate lands), ``SpawnRequest.max_seconds`` (so+``deadline_at`` is always ``None``), ``SpawnRequest.tools`` (the exact-set pin+— which means the read-only quarantine shape is expressible here but not+selectable from any tool yet), and ``may_spawn=False`` (all three spawn tools+pass ``True``, so no leaf is created in production).+"""++import logging+from collections.abc import Awaitable+from datetime import UTC, datetime, timedelta+from typing import cast++from pydantic import BaseModel, ConfigDict, Field++from backend.copilot.active_turns import MAX_TURN_LIFETIME_SECONDS+from backend.copilot.config import ChatConfig+from backend.copilot.permissions import ALL_TOOL_NAMES, CopilotPermissions+from backend.copilot.rate_limit import get_global_rate_limits, get_remaining_usd_budget+from backend.data.redis_client import AsyncRedisClient, get_redis_async++logger = logging.getLogger(__name__)+config = ChatConfig()++# One bound for every spawn kind; ``expert_delegation`` re-exports it as the+# chain bound. The provenance walk there only counts cross-expert hops — this+# counts isolates too.+MAX_DEPTH = 3++SPAWN_TOOLS: frozenset[str] = frozenset(+ {"run_sub_session", "delegate_to_expert", "handoff_to_expert"}+)++# Denied to EVERY spawned child by default: irreversible deletes, and actions+# that bind the user's account (connect an integration, register a trigger,+# staff the team). None is part of a delegated expert's normal job, so+# withholding them does not break a working delegation — it removes reach a+# spawned turn should never have silently. The staffing tools are already+# denied to expert sessions by their tool group; listing them keeps the+# guarantee even for a plain-AutoPilot child.+DESCENT_DENIED_TOOLS: frozenset[str] = frozenset(+ {+ "connect_integration",+ "setup_agent_webhook_trigger",+ "update_preset",+ "delete_folder",+ "delete_preset",+ "delete_schedule",+ "delete_skill",+ "delete_workspace_file",+ "hire_expert",+ "raise_expert",+ "update_expert",+ "confirm_expert_change",+ }+)++# Additionally denied to an isolate — a child that shares its spawner's memory+# namespace and identity (``run_sub_session``). It is scratch space: posting+# outward, scheduling, calling an MCP server, or persisting a skill under the+# parent's identity is not its role, and a memory write it makes is read back+# by the parent next turn as the parent's own. A *delegated* expert runs under+# its own identity, namespace and budget and keeps all of these — its job is+# to do real work.+ISOLATE_DENIED_TOOLS: frozenset[str] = frozenset(+ {+ "post_to_chat_platform",+ "schedule_followup",+ "run_mcp_tool",+ "store_skill",+ "memory_store",+ "add_understanding",+ }+)++_LEDGER_KEY_PREFIX = "copilot:tree:"++# All-or-nothing tree creation. ``HSETNX`` per field is not equivalent: it+# leaves a window where another caller sees some fields and not others, and+# ``admit`` cannot tell that from a tree that has closed.+_OPEN_TREE_SCRIPT = """+if redis.call("EXISTS", KEYS[1]) == 0 then+ redis.call("HSET", KEYS[1],+ "ceiling", ARGV[1],+ "max_nodes", ARGV[2],+ "nodes", ARGV[3],+ "spent", 0)+ redis.call("EXPIRE", KEYS[1], ARGV[4])+ return 1+end+return 0+"""+++class TreeRefusal(Exception):+ """A turn may not start; ``message`` is written for the model."""++ def __init__(self, message: str) -> None:+ super().__init__(message)+ self.message = message+++class TurnEnvelope(BaseModel):+ tree_id: str+ depth: int = 0+ tainted: bool = False+ # None = unrestricted root. A child always carries a concrete set.+ tools: frozenset[str] | None = None+ deadline_at: datetime | None = None++ def permits(self, tool_name: str) -> bool:+ return self.tools is None or tool_name in self.tools++ def as_permissions(self) -> CopilotPermissions | None:+ """The tool set as a whitelist, so the engines hide what this turn+ may not call. Hiding is presentation; ``BaseTool.execute`` enforces."""+ if self.tools is None:+ return None+ if not self.tools:+ # An empty whitelist reads back through effective_allowed_tools as+ # "no filter at all", which would show a fully-locked child every+ # tool. Deny-everything is the honest encoding of the same thing.+ return CopilotPermissions(tools=sorted(ALL_TOOL_NAMES), tools_exclude=True)+ return CopilotPermissions(tools=sorted(self.tools), tools_exclude=False)+++class SpawnRequest(BaseModel):+ """What a spawner asks for its child. Every field is clamped, never raised.++ ``extra="forbid"``: on a model whose job is narrowing a security envelope,+ a mistyped field name must fail loudly rather than silently yield the+ widest possible narrowing.+ """++ model_config = ConfigDict(extra="forbid")++ # Exact set (a quarantine preset), or None for the default: everything+ # the spawner holds minus the denial lists.+ #+ # There is deliberately no "grant" escape hatch. Denials are absolute, so+ # anything a grant could legitimately add is already in the default set,+ # and anything it could not add must stay denied — a grant parameter can+ # only ever be a no-op or a violation. A child that genuinely needs a+ # denied tool is a human-approval case.+ tools: list[str] | None = None+ may_spawn: bool = False+ shares_memory: bool = False+ max_seconds: int | None = Field(default=None, ge=1)+ born_tainted: bool = False+++def root_envelope(turn_id: str, *, tainted: bool = False) -> TurnEnvelope:+ return TurnEnvelope(tree_id=turn_id, depth=0, tainted=tainted)+++def derive_child_envelope(+ spawner: TurnEnvelope,+ request: SpawnRequest,+ *,+ spawner_permissions: CopilotPermissions | None = None,+ now: datetime | None = None,+) -> TurnEnvelope:+ """The child's envelope. Raises :class:`TreeRefusal`. Pure given ``now``.++ ``spawner_permissions`` is the spawning turn's own capability filter+ (an ``AutoPilotBlock`` whitelist, say). It lives beside the envelope+ rather than in it today, so it is folded in here to keep the ceiling+ honest.+ """+ now = now or datetime.now(UTC)+ depth = spawner.depth + 1+ if depth > MAX_DEPTH:+ raise TreeRefusal(+ f"This task is already {spawner.depth} hops deep; do as much as you "+ "can yourself instead of passing it on again."+ )+ if spawner.deadline_at is not None and spawner.deadline_at <= now:+ raise TreeRefusal("This turn's deadline has passed; report what you have.")+ if not any(spawner.permits(t) for t in SPAWN_TOOLS):+ raise TreeRefusal("This turn may not spawn further work.")++ # Two rules, both enforced below, and the result is+ # ``child ⊆ (spawner_effective − denied)``:+ #+ # 1. An explicit descent denial is absolute. Nothing reaches a child that+ # is on the denied list — not via ``request.tools``, not via ``grant``,+ # not even from a spawner that holds the tool itself. A child that+ # genuinely needs one of these is a human-approval case, not a grant.+ # 2. Otherwise no amplification: an agent cannot authorize a tool it is+ # not itself authorized to use.+ ceiling = spawner.tools if spawner.tools is not None else ALL_TOOL_NAMES+ if spawner_permissions is not None:+ ceiling = ceiling & spawner_permissions.effective_allowed_tools(ALL_TOOL_NAMES)+ denied = DESCENT_DENIED_TOOLS+ if request.shares_memory:+ denied = denied | ISOLATE_DENIED_TOOLS+ requested = (+ frozenset(request.tools)+ if request.tools is not None+ else ALL_TOOL_NAMES - denied+ )+ # ``- denied`` last, so no request shape can route around rule 1 above.+ tools = (ceiling & requested) - denied+ if not request.may_spawn:+ tools = tools - SPAWN_TOOLS++ deadline_at = spawner.deadline_at+ if request.max_seconds is not None:+ candidate = now + timedelta(seconds=request.max_seconds)+ deadline_at = candidate if deadline_at is None else min(deadline_at, candidate)++ return TurnEnvelope(+ tree_id=spawner.tree_id,+ depth=depth,+ tainted=spawner.tainted or request.born_tainted,+ tools=tools,+ deadline_at=deadline_at,+ )+++class TreeLedger:+ """One Redis hash per tree: ``ceiling``, ``spent``, ``nodes``, ``max_nodes``.++ Admission is increment-then-check with rollback, the same non-locked+ pattern ``acquire_turn_slot`` uses: two racing spawns can both pass by+ one, and that over-admit is the bound's stated slack.++ Spend is metered, not reserved: ``spent`` only advances when a turn ends+ (``token_tracking``), so children dispatched in one round all read the+ same figure and are all admitted. The ceiling therefore bounds how much a+ tree may *start* spending against, not its total — the worst case is+ ``(max_nodes - 1) x`` the per-turn cap, i.e. every remaining node+ admitted at ``spent == 0`` and each running to its own limit. The node+ cap is what keeps that finite. Reserving at admit and reconciling at+ charge is the fix, and needs the SDK to report a per-query spend the+ Codex transport does not currently expose.+ """++ def __init__(self, redis: AsyncRedisClient) -> None:+ self._redis = redis++ @staticmethod+ def key(tree_id: str) -> str:+ return f"{_LEDGER_KEY_PREFIX}{tree_id}"++ async def exists(self, tree_id: str) -> bool:+ return await cast(+ Awaitable[bool], self._redis.hexists(self.key(tree_id), "ceiling")+ )++ async def open(+ self,+ tree_id: str,+ *,+ ceiling_microdollars: int,+ max_nodes: int,+ initial_nodes: int = 0,+ ) -> None:+ """Open the tree, all fields and the TTL or none of them.++ Field-by-field ``HSETNX`` left a window where a second first-child+ could see ``ceiling`` written but ``spent``/``max_nodes`` still+ missing, and ``admit`` reads a partial hash as a closed tree — a+ spurious refusal of a perfectly valid spawn. One script closes it,+ and stays idempotent: the racing loser finds the key populated and+ changes nothing.+ """+ await cast(+ Awaitable[int],+ self._redis.eval(+ _OPEN_TREE_SCRIPT,+ 1,+ self.key(tree_id),+ str(max(0, ceiling_microdollars)),+ str(max(1, max_nodes)),+ str(max(0, initial_nodes)),+ str(MAX_TURN_LIFETIME_SECONDS),+ ),+ )++ async def admit(self, envelope: TurnEnvelope) -> None:+ key = self.key(envelope.tree_id)+ ceiling, spent, max_nodes = await cast(+ Awaitable[list[str | None]],+ self._redis.hmget(key, ["ceiling", "spent", "max_nodes"]),+ )+ if ceiling is None or spent is None or max_nodes is None:+ raise TreeRefusal("This task's tree has closed; nothing more can start.")+ # A root is gated by the per-user rate limit before it gets here; the+ # spend check is for what the root spawns. It reads settled spend only,+ # 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."+ )+ nodes = await self._hincrby(key, "nodes", 1)+ if nodes > int(max_nodes):+ await self._hincrby(key, "nodes", -1)+ raise TreeRefusal(+ f"This task has already used its {max_nodes} agents — that is a "+ "lifetime budget for this request, not a concurrency limit, so "+ "waiting will not free one. Finish the remaining work yourself."+ )++ async def release(self, tree_id: str) -> None:+ """Undo an admit whose dispatch never happened."""+ if await self.exists(tree_id):+ await self._hincrby(self.key(tree_id), "nodes", -1)++ async def charge(self, tree_id: str, microdollars: int) -> None:+ if microdollars <= 0:+ return+ key = self.key(tree_id)+ if not await cast(Awaitable[bool], self._redis.hexists(key, "ceiling")):+ return+ await self._hincrby(key, "spent", microdollars)++ async def snapshot(self, tree_id: str) -> dict[str, int]:+ raw = await cast(+ Awaitable[dict[str, str]], self._redis.hgetall(self.key(tree_id))+ )+ return {k: int(v) for k, v in raw.items()}++ # redis-py types the async client's hash commands as ``Awaitable[T] | T``;+ # the narrowing cast is the pattern the rest of the backend uses.+ async def _hincrby(self, key: str, field: str, amount: int) -> int:+ """Always re-arm the TTL.++ ``HINCRBY`` on a key whose TTL fired in the meantime *recreates* it,+ and only ``open()`` ever issued ``EXPIRE`` — so a charge or release+ landing in that window left a ``copilot:tree:*`` hash with no+ expiry, i.e. a permanent leak. Re-arming is idempotent, and the+ MULTI/EXEC keeps the increment and the TTL in one round-trip so a+ crash between them cannot leave the key unexpiring.+ """+ pipe = self._redis.pipeline(transaction=True)+ pipe.hincrby(key, field, amount)+ pipe.expire(key, MAX_TURN_LIFETIME_SECONDS)+ value, _ = await cast(Awaitable[list], pipe.execute())+ return int(value)+++async def get_tree_ledger() -> TreeLedger:+ return TreeLedger(await get_redis_async())+++async def resolve_root_ceiling_microdollars(user_id: str | None) -> int:+ """What one tree may spend:++ min( remaining_budget,+ max( fraction_of_daily * tier_daily_limit, floor ),+ absolute_cap )++ Scaling off the caller's *tier-scaled* daily limit rather than a flat+ constant is what makes the number proportionate — and it is why a+ NO_TIER user (multiplier 0.0) resolves to 0: a tier that may not spend+ may not spawn either. The floor keeps a modest daily limit from+ producing a tree too small to fund one real turn; the cap keeps a+ generous one from handing a single tree the whole day.+ """+ cap = config.tree_ceiling_microdollars+ if not user_id:+ # Fail closed: without a user there is no tier to scale from, and+ # handing out the full cap is the one fail-open branch this module+ # would otherwise contain.+ return 0+ daily, weekly, _ = await get_global_rate_limits(+ user_id,+ config.daily_cost_limit_microdollars,+ config.weekly_cost_limit_microdollars,+ )+ # ``daily`` is already tier-scaled by get_global_rate_limits.+ scaled = int(config.tree_ceiling_fraction_of_daily * daily)+ # A zero tier allowance means no spend at all; the floor must not+ # resurrect it, so it only applies to a tier that may spend.+ allowance = max(scaled, config.tree_ceiling_floor_microdollars) if daily > 0 else 0+ ceiling = min(allowance, cap)++ remaining_usd = await get_remaining_usd_budget(+ user_id=user_id, daily_cost_limit=daily, weekly_cost_limit=weekly, floor_usd=0.0+ )+ if remaining_usd == float("inf"):+ return max(0, ceiling)+ remaining = int(round(remaining_usd * 1_000_000))+ return max(0, min(remaining, ceiling))+++async def admit_turn(+ envelope: TurnEnvelope, *, user_id: str | None, ledger: TreeLedger | None = None+) -> None:+ """Admit a spawned turn against its tree, opening the tree on first use.++ Roots never touch the ledger: the per-user rate limit already gates+ them, and the tree only needs to exist once something is spawned. So+ the HTTP route, the scheduler and ``AutoPilotBlock`` pay nothing here,+ and a spawned turn fails closed when the ledger is unreachable.+ """+ if envelope.depth == 0:+ return+ try:+ ledger = ledger or await get_tree_ledger()+ if not await ledger.exists(envelope.tree_id):+ await ledger.open(+ envelope.tree_id,+ ceiling_microdollars=await resolve_root_ceiling_microdollars(user_id),+ max_nodes=config.tree_max_nodes,+ # The root is a node of its own tree.+ initial_nodes=1,+ )+ await ledger.admit(envelope)+ except TreeRefusal:+ raise+ except Exception as e:+ logger.warning(f"Tree ledger unavailable; refusing spawn: {e}")+ raise TreeRefusal(+ "Could not account for this work right now; try again shortly."+ ) from e+++async def release_turn(envelope: TurnEnvelope) -> None:+ if envelope.depth == 0:+ return+ try:+ await (await get_tree_ledger()).release(envelope.tree_id)+ except Exception as e:+ logger.warning(f"Tree ledger release failed for {envelope.tree_id}: {e}")+++async def charge_turn(envelope: TurnEnvelope, microdollars: int) -> None:+ """Charge a turn's cost to its tree. A root whose tree never opened (no+ spawns) has nothing to charge, and ``charge`` ignores unknown trees."""+ try:+ await (await get_tree_ledger()).charge(envelope.tree_id, microdollars)+ except Exception as e:+ logger.warning(f"Tree ledger charge failed for {envelope.tree_id}: {e}")diff --git a/autogpt_platform/backend/backend/copilot/tree_test.py b/autogpt_platform/backend/backend/copilot/tree_test.pynew file mode 100644index 0000000000..f2b7b8233c--- /dev/null+++ b/autogpt_platform/backend/backend/copilot/tree_test.py@@ -0,0 +1,534 @@+"""Tests for the per-tree bounds on spawned copilot turns.++The envelope derivation is pure and is tested for the property that matters:+every field can only narrow on descent. The ledger is tested against a+minimal in-memory Redis that mirrors the hash operations it uses.+"""++from __future__ import annotations++import asyncio+from datetime import UTC, datetime, timedelta+from typing import Any, cast++import pytest+from pydantic import ValidationError++from backend.copilot.permissions import ALL_TOOL_NAMES, CopilotPermissions+from backend.data.redis_client import AsyncRedisClient++from . import tree+from .tree import (+ DESCENT_DENIED_TOOLS,+ ISOLATE_DENIED_TOOLS,+ MAX_DEPTH,+ SPAWN_TOOLS,+ SpawnRequest,+ TreeLedger,+ TreeRefusal,+ TurnEnvelope,+ admit_turn,+ derive_child_envelope,+ root_envelope,+)+++class FakeRedis:+ """Just the hash operations ``TreeLedger`` uses, with redis-py semantics+ under ``decode_responses=True``."""++ def __init__(self) -> None:+ self.hashes: dict[str, dict[str, str]] = {}+ self.ttls: dict[str, int] = {}++ async def hsetnx(self, key: str, field: str, value: Any) -> int:+ bucket = self.hashes.setdefault(key, {})+ if field in bucket:+ return 0+ bucket[field] = str(value)+ return 1++ async def hmget(self, key: str, fields: list[str]) -> list[str | None]:+ bucket = self.hashes.get(key, {})+ return [bucket.get(f) for f in fields]++ async def hincrby(self, key: str, field: str, amount: int) -> int:+ bucket = self.hashes.setdefault(key, {})+ value = int(bucket.get(field, "0")) + amount+ bucket[field] = str(value)+ return value++ async def hexists(self, key: str, field: str) -> bool:+ return field in self.hashes.get(key, {})++ async def hgetall(self, key: str) -> dict[str, str]:+ return dict(self.hashes.get(key, {}))++ async def expire(self, key: str, seconds: int) -> int:+ self.ttls[key] = seconds+ return 1++ def pipeline(self, transaction: bool = True) -> "_FakePipeline":+ 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)."""+ key = str(args[0])+ ceiling, max_nodes, nodes, ttl = (str(a) for a in args[1:5])+ if key in self.hashes:+ return 0+ self.hashes[key] = {+ "ceiling": ceiling,+ "max_nodes": max_nodes,+ "nodes": nodes,+ "spent": "0",+ }+ self.ttls[key] = int(ttl)+ return 1+++class _FakePipeline:+ """Queues commands and applies them in order on ``execute``, like redis-py:+ the command methods are synchronous and only ``execute`` is awaited."""++ def __init__(self, redis: "FakeRedis") -> None:+ self._redis = redis+ self._queued: list[tuple[str, tuple[Any, ...]]] = []++ def hincrby(self, key: str, field: str, amount: int) -> "_FakePipeline":+ self._queued.append(("hincrby", (key, field, amount)))+ return self++ def expire(self, key: str, seconds: int) -> "_FakePipeline":+ self._queued.append(("expire", (key, seconds)))+ return self++ async def execute(self) -> list[Any]:+ return [await getattr(self._redis, name)(*args) for name, args in self._queued]+++class BrokenRedis:+ def __getattr__(self, name: str):+ async def _fail(*_a: Any, **_k: Any) -> None:+ raise ConnectionError("redis down")++ return _fail+++def _child(spawner: TurnEnvelope, **request: Any) -> TurnEnvelope:+ return derive_child_envelope(spawner, SpawnRequest(**request))+++# ── derivation ─────────────────────────────────────────────────────────+++def test_root_is_unrestricted_and_depth_zero() -> None:+ root = root_envelope("turn-1")+ assert root.depth == 0+ assert root.tools is None+ assert root.permits("run_agent")+ assert root.as_permissions() is None+++def test_delegate_default_drops_only_account_tools_keeps_its_job() -> None:+ # A delegate runs under its own identity: it keeps the tools it works with.+ child = _child(root_envelope("t"))+ assert child.depth == 1+ assert child.tools is not None+ assert child.tools.isdisjoint(DESCENT_DENIED_TOOLS)+ assert child.tools.isdisjoint(SPAWN_TOOLS)+ assert "read_workspace_file" in child.tools+ assert ISOLATE_DENIED_TOOLS <= child.tools # post/schedule/memory_store kept+ assert child.as_permissions() == CopilotPermissions(+ tools=sorted(child.tools), tools_exclude=False+ )+++def test_isolate_also_drops_outward_and_memory_write_tools() -> None:+ isolate = _child(root_envelope("t"), shares_memory=True, may_spawn=True)+ assert isolate.tools is not None+ assert isolate.tools.isdisjoint(ISOLATE_DENIED_TOOLS)+ assert isolate.tools.isdisjoint(DESCENT_DENIED_TOOLS)+ assert "memory_search" in isolate.tools # reading is fine; writing is not+++def test_there_is_no_grant_escape_hatch() -> None:+ """Denials are absolute, so a grant parameter could only ever be a no-op+ or a violation. It was removed; this pins that it stays removed.++ It existed briefly and was dead on every path: the derivation applies+ ``- denied`` last, so a granted denied tool was stripped again, and a+ granted non-denied tool was already in the default set.+ """+ with pytest.raises(ValidationError):+ SpawnRequest(grant=["post_to_chat_platform"]) # type: ignore[call-arg]+++def test_spawn_request_rejects_unknown_fields() -> None:+ """A typo in a narrowing request must fail loudly, not silently widen."""+ with pytest.raises(ValidationError):+ SpawnRequest(shares_memmory=True) # type: ignore[call-arg]+++def test_may_spawn_keeps_spawn_tools_but_nothing_denied() -> None:+ child = _child(root_envelope("t"), may_spawn=True)+ assert child.tools is not None+ assert SPAWN_TOOLS <= child.tools+ assert child.tools.isdisjoint(DESCENT_DENIED_TOOLS)+++def test_pinning_a_tool_set_still_respects_the_denials() -> None:+ child = _child(root_envelope("t"), tools=["post_to_chat_platform"])+ assert child.tools == frozenset({"post_to_chat_platform"})+ # …but a descent-denied tool is refused even when pinned by name.+ denied = _child(root_envelope("t"), tools=["connect_integration"])+ assert denied.tools == frozenset()+++def test_child_cannot_regain_a_tool_its_spawner_lacks() -> None:+ parent = _child(+ root_envelope("t"),+ tools=["read_workspace_file", "run_sub_session"],+ may_spawn=True,+ )+ assert parent.tools == frozenset({"read_workspace_file", "run_sub_session"})+ grandchild = derive_child_envelope(+ parent, SpawnRequest(tools=["read_workspace_file", "run_agent", "bash_exec"])+ )+ assert grandchild.tools == frozenset({"read_workspace_file"})+++def test_leaf_cannot_spawn() -> None:+ leaf = _child(root_envelope("t"))+ with pytest.raises(TreeRefusal):+ derive_child_envelope(leaf, SpawnRequest())+++def test_depth_is_bounded_for_every_spawn_kind() -> None:+ node = root_envelope("t")+ for _ in range(MAX_DEPTH):+ node = derive_child_envelope(node, SpawnRequest(may_spawn=True))+ assert node.depth == MAX_DEPTH+ with pytest.raises(TreeRefusal):+ derive_child_envelope(node, SpawnRequest(may_spawn=True))+++def test_spawner_permissions_narrow_the_ceiling() -> None:+ perms = CopilotPermissions(+ tools=["read_workspace_file", "web_fetch"], tools_exclude=False+ )+ child = derive_child_envelope(+ root_envelope("t"),+ SpawnRequest(tools=["web_fetch", "bash_exec"]),+ spawner_permissions=perms,+ )+ assert child.tools == frozenset({"web_fetch"})+++def test_taint_only_ever_rises() -> None:+ clean = root_envelope("t")+ assert not _child(clean).tainted+ assert _child(clean, born_tainted=True).tainted+ tainted = root_envelope("t", tainted=True)+ assert _child(tainted, born_tainted=False).tainted+++def test_deadline_is_the_minimum() -> None:+ now = datetime(2026, 1, 1, tzinfo=UTC)+ parent = derive_child_envelope(+ root_envelope("t"), SpawnRequest(max_seconds=600, may_spawn=True), now=now+ )+ assert parent.deadline_at == now + timedelta(seconds=600)+ child = derive_child_envelope(parent, SpawnRequest(max_seconds=3600), now=now)+ assert child.deadline_at == parent.deadline_at+ later = derive_child_envelope(parent, SpawnRequest(max_seconds=60), now=now)+ assert later.deadline_at == now + timedelta(seconds=60)+++def test_expired_spawner_cannot_spawn() -> None:+ now = datetime(2026, 1, 1, tzinfo=UTC)+ parent = derive_child_envelope(+ root_envelope("t"), SpawnRequest(max_seconds=10, may_spawn=True), now=now+ )+ with pytest.raises(TreeRefusal):+ derive_child_envelope(parent, SpawnRequest(), now=now + timedelta(seconds=11))+++def test_tree_id_and_tenancy_free_fields_never_change() -> None:+ root = root_envelope("turn-9")+ node = root+ for _ in range(MAX_DEPTH):+ node = derive_child_envelope(node, SpawnRequest(may_spawn=True))+ assert node.tree_id == "turn-9"+++def test_envelope_round_trips_through_the_queue() -> None:+ child = _child(root_envelope("t"), tools=["read_workspace_file"])+ restored = TurnEnvelope.model_validate_json(child.model_dump_json())+ assert restored == child+ assert isinstance(restored.tools, frozenset)+++# ── ledger ─────────────────────────────────────────────────────────────+++async def test_root_opens_tree_and_children_count_against_it() -> None:+ redis = FakeRedis()+ ledger = TreeLedger(cast(AsyncRedisClient, redis))+ root = root_envelope("t")+ await ledger.open("t", ceiling_microdollars=1_000_000, max_nodes=3)+ await ledger.admit(root)+ await ledger.admit(_child(root))+ await ledger.admit(_child(root))+ with pytest.raises(TreeRefusal):+ await ledger.admit(_child(root))+ assert (await ledger.snapshot("t"))["nodes"] == 3+++async def test_over_admit_is_rolled_back() -> None:+ redis = FakeRedis()+ ledger = TreeLedger(cast(AsyncRedisClient, redis))+ await ledger.open("t", ceiling_microdollars=1_000_000, max_nodes=1)+ await ledger.admit(root_envelope("t"))+ with pytest.raises(TreeRefusal):+ await ledger.admit(_child(root_envelope("t")))+ assert (await ledger.snapshot("t"))["nodes"] == 1+ await ledger.release("t")+ assert (await ledger.snapshot("t"))["nodes"] == 0+++async def test_concurrent_admits_never_exceed_the_cap() -> None:+ redis = FakeRedis()+ ledger = TreeLedger(cast(AsyncRedisClient, redis))+ await ledger.open("t", ceiling_microdollars=1_000_000, max_nodes=8)+ root = root_envelope("t")+ await ledger.admit(root)++ async def try_admit() -> bool:+ try:+ await ledger.admit(_child(root))+ return True+ except TreeRefusal:+ return False++ results = await asyncio.gather(*(try_admit() for _ in range(30)))+ assert sum(results) == 7+ assert (await ledger.snapshot("t"))["nodes"] == 8+++async def test_spend_ceiling_refuses_children_but_not_the_root() -> None:+ redis = FakeRedis()+ ledger = TreeLedger(cast(AsyncRedisClient, redis))+ await ledger.open("t", ceiling_microdollars=500_000, max_nodes=10)+ root = root_envelope("t")+ await ledger.admit(root)+ await ledger.charge("t", 300_000)+ await ledger.admit(_child(root))+ await ledger.charge("t", 300_000)+ with pytest.raises(TreeRefusal):+ await ledger.admit(_child(root))+ assert (await ledger.snapshot("t"))["spent"] == 600_000+++async def test_charge_to_unknown_tree_is_ignored() -> None:+ redis = FakeRedis()+ await TreeLedger(cast(AsyncRedisClient, redis)).charge("ghost", 1)+ assert "copilot:tree:ghost" not in redis.hashes+++async def test_child_of_a_closed_tree_is_refused() -> None:+ with pytest.raises(TreeRefusal):+ await TreeLedger(cast(AsyncRedisClient, FakeRedis())).admit(+ _child(root_envelope("gone"))+ )+++async def test_admit_turn_fails_closed_for_children_open_for_roots(monkeypatch) -> None:+ async def _ceiling(_user_id):+ return 1_000_000++ monkeypatch.setattr(tree, "resolve_root_ceiling_microdollars", _ceiling)+ broken = TreeLedger(cast(AsyncRedisClient, BrokenRedis()))+ # A root never touches the ledger, so a dead Redis cannot block a chat.+ await admit_turn(root_envelope("t"), user_id="u", ledger=broken)+ with pytest.raises(TreeRefusal):+ await admit_turn(_child(root_envelope("t")), user_id="u", ledger=broken)+++async def test_first_spawn_opens_the_tree_with_the_root_counted(monkeypatch) -> None:+ async def _ceiling(_user_id):+ return 42++ monkeypatch.setattr(tree, "resolve_root_ceiling_microdollars", _ceiling)+ monkeypatch.setattr(tree.config, "tree_max_nodes", 2)+ redis = FakeRedis()+ ledger = TreeLedger(cast(AsyncRedisClient, redis))+ root = root_envelope("t")+ await admit_turn(root, user_id="u", ledger=ledger)+ assert "copilot:tree:t" not in redis.hashes+ await admit_turn(_child(root), user_id="u", ledger=ledger)+ snapshot = await ledger.snapshot("t")+ assert snapshot == {"ceiling": 42, "spent": 0, "nodes": 2, "max_nodes": 2}+ assert redis.ttls["copilot:tree:t"] > 0+ with pytest.raises(TreeRefusal):+ await admit_turn(_child(root), user_id="u", ledger=ledger)+++def test_all_tool_names_cover_the_denied_set() -> None:+ # A denied name that is not a real tool would be a silent no-op.+ assert DESCENT_DENIED_TOOLS <= ALL_TOOL_NAMES+ assert SPAWN_TOOLS <= ALL_TOOL_NAMES+++# ── ceiling formula (finding 3) ────────────────────────────────────────+++def _ceiling(daily: int, remaining_usd: float, monkeypatch) -> int:+ """Drive resolve_root_ceiling_microdollars with a fixed tier + balance."""++ async def _limits(_uid, _d, _w):+ return daily, daily * 5, "TIER"++ async def _remaining(**_kw):+ return remaining_usd++ monkeypatch.setattr(tree, "get_global_rate_limits", _limits)+ monkeypatch.setattr(tree, "get_remaining_usd_budget", _remaining)+ return asyncio.run(tree.resolve_root_ceiling_microdollars("u"))+++def test_ceiling_is_a_fraction_of_the_tier_daily_limit(monkeypatch) -> None:+ monkeypatch.setattr(tree.config, "tree_ceiling_fraction_of_daily", 0.5)+ monkeypatch.setattr(tree.config, "tree_ceiling_floor_microdollars", 500_000)+ monkeypatch.setattr(tree.config, "tree_ceiling_microdollars", 10_000_000)+ # 0.5 x $8.00 = $4.00, under both floor and cap.+ assert _ceiling(8_000_000, 999.0, monkeypatch) == 4_000_000+++def test_ceiling_floor_applies_to_a_small_tier(monkeypatch) -> None:+ monkeypatch.setattr(tree.config, "tree_ceiling_fraction_of_daily", 0.5)+ monkeypatch.setattr(tree.config, "tree_ceiling_floor_microdollars", 500_000)+ monkeypatch.setattr(tree.config, "tree_ceiling_microdollars", 10_000_000)+ # 0.5 x $0.20 = $0.10, raised to the $0.50 floor so a tree can fund a turn.+ assert _ceiling(200_000, 999.0, monkeypatch) == 500_000+++def test_ceiling_cap_applies_to_a_large_tier(monkeypatch) -> None:+ monkeypatch.setattr(tree.config, "tree_ceiling_fraction_of_daily", 0.5)+ monkeypatch.setattr(tree.config, "tree_ceiling_floor_microdollars", 500_000)+ monkeypatch.setattr(tree.config, "tree_ceiling_microdollars", 10_000_000)+ assert _ceiling(400_000_000, 999.0, monkeypatch) == 10_000_000+++def test_no_tier_yields_no_budget_and_therefore_no_spawns(monkeypatch) -> None:+ """A NO_TIER user's multiplier is 0.0, so the daily limit resolves to 0.+ The floor must not resurrect a tier that may not spend at all."""+ monkeypatch.setattr(tree.config, "tree_ceiling_floor_microdollars", 500_000)+ assert _ceiling(0, 0.0, monkeypatch) == 0+++def test_remaining_budget_clamps_the_ceiling(monkeypatch) -> None:+ monkeypatch.setattr(tree.config, "tree_ceiling_fraction_of_daily", 0.5)+ monkeypatch.setattr(tree.config, "tree_ceiling_floor_microdollars", 500_000)+ monkeypatch.setattr(tree.config, "tree_ceiling_microdollars", 10_000_000)+ # Formula would allow $4.00; only $0.75 is left today.+ assert _ceiling(8_000_000, 0.75, monkeypatch) == 750_000+++def test_isolate_denied_names_are_real_tools() -> None:+ # DESCENT and SPAWN are asserted above; ISOLATE was the gap.+ assert ISOLATE_DENIED_TOOLS <= ALL_TOOL_NAMES+++# ── no amplification (finding 4) ───────────────────────────────────────+++def _spawners_lacking(tool: str) -> list[tuple[str, TurnEnvelope]]:+ """Every shape of spawner that does not hold *tool*.++ Which shapes qualify depends on the tool: a delegate keeps the+ isolate-denied set, so it is only a valid "lacking" spawner for a+ descent-denied tool.+ """+ root = root_envelope("t")+ candidates = [+ (+ "explicit pin",+ derive_child_envelope(+ root,+ SpawnRequest(+ tools=["read_workspace_file", "run_sub_session"], may_spawn=True+ ),+ ),+ ),+ (+ "isolate default",+ derive_child_envelope(+ root, SpawnRequest(shares_memory=True, may_spawn=True)+ ),+ ),+ (+ "delegate default",+ derive_child_envelope(root, SpawnRequest(may_spawn=True)),+ ),+ ]+ lacking = [(label, env) for label, env in candidates if not env.permits(tool)]+ assert lacking, f"no spawner shape lacks {tool}"+ return lacking++[email protected]("tool", ["post_to_chat_platform", "connect_integration"])+def test_a_spawner_can_never_grant_a_tool_it_does_not_hold(tool: str) -> None:+ """An agent cannot authorize use of a tool it is not itself authorized to+ use — for every combination of the request's tool inputs."""+ requests = [+ SpawnRequest(tools=[tool], may_spawn=True),+ SpawnRequest(tools=[tool, "read_workspace_file"], may_spawn=True),+ SpawnRequest(tools=None, may_spawn=True),+ ]+ for label, spawner in _spawners_lacking(tool):+ assert not spawner.permits(tool), label+ for request in requests:+ child = derive_child_envelope(spawner, request)+ assert not child.permits(tool), f"{label} amplified via {request}"+ assert child.tools is not None+ assert child.tools <= (spawner.tools or ALL_TOOL_NAMES), label++[email protected]("tool", sorted(DESCENT_DENIED_TOOLS))+def test_no_spawner_can_ever_pass_on_an_explicitly_denied_tool(tool: str) -> None:+ """Even a spawner that holds the tool — a root holds everything — cannot+ hand a descent-denied tool to a child, by any mechanism."""+ root = root_envelope("t")+ assert root.permits(tool)+ for request in (+ SpawnRequest(tools=[tool], may_spawn=True),+ SpawnRequest(tools=[tool, "read_workspace_file"], may_spawn=True),+ SpawnRequest(tools=None, shares_memory=True),+ ):+ assert not derive_child_envelope(root, request).permits(tool)+++def test_a_non_denied_tool_still_reaches_a_child_by_default() -> None:+ """Removing grant must not remove ordinary inheritance: a delegate still+ gets the isolate-denied set, because those are only denied to isolates."""+ child = derive_child_envelope(root_envelope("t"), SpawnRequest())+ assert child.permits("post_to_chat_platform")+ assert not child.permits("delete_preset")+++def test_an_empty_tool_set_denies_rather_than_reading_as_no_filter() -> None:+ """An empty whitelist round-trips through effective_allowed_tools as "no+ filter", which would show a fully-locked child every tool."""+ locked = TurnEnvelope(tree_id="t", depth=1, tools=frozenset())+ perms = locked.as_permissions()+ assert perms is not None+ assert perms.effective_allowed_tools(ALL_TOOL_NAMES) == frozenset()diff --git a/autogpt_platform/backend/backend/platform_linking/chat.py b/autogpt_platform/backend/backend/platform_linking/chat.pyindex a3f1aad6f7..3027688566 100644--- a/autogpt_platform/backend/backend/platform_linking/chat.py+++ b/autogpt_platform/backend/backend/platform_linking/chat.py@@ -23,6 +23,7 @@ from backend.copilot.rate_limit import (is_user_paywalled,)from backend.copilot.transports import resolve_default_chat_route+from backend.copilot.tree import root_envelopefrom backend.data.db_accessors import orgs_db, platform_linking_db, workspace_dbfrom backend.util.exceptions import DuplicateChatMessageError, NotFoundErrorfrom backend.util.settings import Settings@@ -395,6 +396,10 @@ async def start_chat_turn(request: BotChatRequest) -> ChatTurnHandle:file_ids=request.file_ids or None,llm_auth_provider=session.metadata.llm_auth_provider,llm_credential_id=session.metadata.llm_credential_id,+ # Roots its own tree, and born tainted: the message was written on a+ # chat platform by someone who need not be the account owner, so+ # anything this turn spawns inherits the bit.+ envelope=root_envelope(turn_id, tainted=True),)logger.info(diff --git a/autogpt_platform/backend/scripts/tree_fanout_demo.py b/autogpt_platform/backend/scripts/tree_fanout_demo.pynew file mode 100644index 0000000000..1bdc806b3a--- /dev/null+++ b/autogpt_platform/backend/scripts/tree_fanout_demo.py@@ -0,0 +1,171 @@+"""Demonstrate the per-tree bounds on spawned copilot turns, with no LLM.++Builds one root turn and fans out thirty spawn requests through the same+derivation and ledger the executor's chokepoint uses, then asserts the+structural claims from AGENT_COLLABORATION_ARCHITECTURE.md §9:++- every child's tool set is a subset of its spawner's minus the descent-+ denied tools, and a leaf cannot spawn;+- depth never exceeds MAX_DEPTH through an isolate → delegate → isolate chain;+- the (max_nodes + 1)th node is refused, and concurrent admits still respect it;+- once metered spend crosses the ceiling, no further turn in the tree starts.++Run: poetry run python scripts/tree_fanout_demo.py+"""++from __future__ import annotations++import asyncio+from typing import Any, cast++from backend.copilot.tree import (+ DESCENT_DENIED_TOOLS,+ MAX_DEPTH,+ SPAWN_TOOLS,+ SpawnRequest,+ TreeLedger,+ TreeRefusal,+ TurnEnvelope,+ derive_child_envelope,+ root_envelope,+)+from backend.data.redis_client import AsyncRedisClient+++class InMemoryRedis:+ def __init__(self) -> None:+ self.hashes: dict[str, dict[str, str]] = {}++ async def hsetnx(self, key: str, field: str, value: Any) -> int:+ bucket = self.hashes.setdefault(key, {})+ if field in bucket:+ return 0+ bucket[field] = str(value)+ return 1++ async def hmget(self, key: str, fields: list[str]) -> list[str | None]:+ bucket = self.hashes.get(key, {})+ return [bucket.get(f) for f in fields]++ async def hincrby(self, key: str, field: str, amount: int) -> int:+ bucket = self.hashes.setdefault(key, {})+ bucket[field] = str(int(bucket.get(field, "0")) + amount)+ return int(bucket[field])++ async def hexists(self, key: str, field: str) -> bool:+ return field in self.hashes.get(key, {})++ async def hgetall(self, key: str) -> dict[str, str]:+ return dict(self.hashes.get(key, {}))++ async def expire(self, key: str, seconds: int) -> int:+ return 1++ async def eval(self, script: str, numkeys: int, *args: Any) -> int:+ key = str(args[0])+ ceiling, max_nodes, nodes, _ttl = (str(a) for a in args[1:5])+ if key in self.hashes:+ return 0+ self.hashes[key] = {+ "ceiling": ceiling,+ "max_nodes": max_nodes,+ "nodes": nodes,+ "spent": "0",+ }+ return 1+++async def spawn(+ ledger: TreeLedger, spawner: TurnEnvelope, request: SpawnRequest+) -> TurnEnvelope | str:+ try:+ child = derive_child_envelope(spawner, request)+ await ledger.admit(child)+ return child+ except TreeRefusal as refused:+ return refused.message+++async def main() -> None:+ ledger = TreeLedger(cast(AsyncRedisClient, InMemoryRedis()))+ root = root_envelope("root-turn")+ await ledger.open("root-turn", ceiling_microdollars=1_000_000, max_nodes=8)+ await ledger.admit(root)+ print(f"root: depth={root.depth} tools=unrestricted ceiling=$1.00 max_nodes=8")++ # 1. Fan out thirty leaves concurrently; only max_nodes - 1 may start.+ quarantine = SpawnRequest(tools=["read_workspace_file"])+ results = await asyncio.gather(+ *(spawn(ledger, root, quarantine) for _ in range(30))+ )+ admitted = [r for r in results if isinstance(r, TurnEnvelope)]+ refused = [r for r in results if isinstance(r, str)]+ print(f"fan-out: {len(admitted)} admitted, {len(refused)} refused")+ assert len(admitted) == 7, len(admitted)+ for leaf in admitted:+ assert leaf.tools == frozenset({"read_workspace_file"})+ assert leaf.depth == 1+ assert not any(leaf.permits(t) for t in SPAWN_TOOLS | DESCENT_DENIED_TOOLS)+ print(+ f" every leaf: tools={sorted(admitted[0].tools or ())}, cannot spawn, cannot act outward"+ )+ print(f" 8th node refused with: {refused[0]!r}")++ # 2. A leaf cannot spawn, whatever it asks for.+ leaf_attempt = await spawn(ledger, admitted[0], SpawnRequest(tools=["bash_exec"]))+ assert isinstance(leaf_attempt, str)+ print(f"leaf spawn attempt refused: {leaf_attempt!r}")++ # 3. Depth bounds an isolate → delegate → isolate chain even with room.+ deep_ledger = TreeLedger(cast(AsyncRedisClient, InMemoryRedis()))+ await deep_ledger.open("deep", ceiling_microdollars=1_000_000, max_nodes=100)+ node: TurnEnvelope = root_envelope("deep")+ await deep_ledger.admit(node)+ kinds = ["isolate", "delegate", "isolate", "delegate"]+ for hop, kind in enumerate(kinds, start=1):+ outcome = await spawn(deep_ledger, node, SpawnRequest(may_spawn=True))+ if isinstance(outcome, str):+ print(f"hop {hop} ({kind}) refused at depth {node.depth}: {outcome!r}")+ assert node.depth == MAX_DEPTH+ break+ node = outcome+ print(f"hop {hop} ({kind}) admitted at depth {node.depth}")+ else:+ raise AssertionError("depth bound never fired")++ # 4. Default child tools shrink monotonically along the chain.+ default_child = await spawn(+ deep_ledger, root_envelope("deep"), SpawnRequest(may_spawn=True)+ )+ assert isinstance(default_child, TurnEnvelope) and default_child.tools is not None+ assert default_child.tools.isdisjoint(DESCENT_DENIED_TOOLS)+ # connect_integration is descent-denied, so default_child does not hold it+ # and cannot pass it on even when a grandchild asks by name.+ narrower = derive_child_envelope(+ default_child,+ SpawnRequest(tools=["read_workspace_file", "connect_integration"]),+ )+ assert narrower.tools == frozenset({"read_workspace_file"})+ print("a child asking for a tool its spawner lacks does not get it")++ # 5. Metered spend closes the tree.+ spend_ledger = TreeLedger(cast(AsyncRedisClient, InMemoryRedis()))+ await spend_ledger.open("spend", ceiling_microdollars=500_000, max_nodes=50)+ spend_root = root_envelope("spend")+ await spend_ledger.admit(spend_root)+ started = 0+ while True:+ outcome = await spawn(spend_ledger, spend_root, SpawnRequest())+ if isinstance(outcome, str):+ print(f"after {started} charged turns the tree refused: {outcome!r}")+ break+ started += 1+ await spend_ledger.charge("spend", 120_000)+ snapshot = await spend_ledger.snapshot("spend")+ assert snapshot["spent"] >= snapshot["ceiling"]+ print(f"ledger: {snapshot}")+ print("all structural claims hold")+++if __name__ == "__main__":+ asyncio.run(main())diff --git a/docs/integrations/block-integrations/misc.md b/docs/integrations/block-integrations/misc.mdindex fb5aa5d224..ce0bd5e9d4 100644--- a/docs/integrations/block-integrations/misc.md+++ b/docs/integrations/block-integrations/misc.md@@ -59,7 +59,7 @@ Tool and block identifiers provided in `tools` and `blocks` are validated at run| transport | Run on platform credits, or on your connected ChatGPT subscription if supported by your plan. | "platform" \| "codex_app_server" | No || session_id | Session ID to continue an existing autopilot conversation. Leave empty to start a new session. Use the session_id output from a previous run to continue. | str | No || max_recursion_depth | Maximum nesting depth when the autopilot calls this block recursively (sub-agent pattern). Prevents infinite loops. | int | No |-| tools | Tool names to filter. Works with tools_exclude to form an allow-list or deny-list. Leave empty to apply no tool filter. | List["add_understanding" \| "ask_question" \| "bash_exec" \| "browser_act" \| "browser_navigate" \| "browser_screenshot" \| "confirm_expert_change" \| "confirm_expert_soul_update" \| "connect_integration" \| "continue_run_block" \| "create_agent" \| "create_feature_request" \| "create_folder" \| "customize_agent" \| "decompose_goal" \| "delegate_to_expert" \| "delete_folder" \| "delete_preset" \| "delete_schedule" \| "delete_skill" \| "delete_workspace_file" \| "edit_agent" \| "enter_agent_building_mode" \| "find_agent" \| "find_block" \| "find_library_agent" \| "fix_agent_graph" \| "get_agent_building_guide" \| "get_doc_page" \| "get_mcp_guide" \| "get_platform_info" \| "get_sub_session_result" \| "handoff_to_expert" \| "hire_expert" \| "list_agent_triggers" \| "list_chat_platform_channels" \| "list_folders" \| "list_presets" \| "list_schedules" \| "list_skills" \| "list_team" \| "list_workspace_files" \| "memory_forget_confirm" \| "memory_forget_search" \| "memory_search" \| "memory_store" \| "move_agents_to_folder" \| "move_folder" \| "post_to_chat_platform" \| "raise_expert" \| "read_skill" \| "read_workspace_file" \| "run_agent" \| "run_block" \| "run_mcp_tool" \| "run_sub_session" \| "schedule_followup" \| "search_docs" \| "search_feature_requests" \| "setup_agent_webhook_trigger" \| "store_skill" \| "update_expert" \| "update_expert_soul" \| "update_folder" \| "update_preset" \| "validate_agent_graph" \| "view_agent_output" \| "web_fetch" \| "web_search" \| "write_workspace_file" \| "Agent" \| "Edit" \| "Glob" \| "Grep" \| "Read" \| "Task" \| "TodoWrite" \| "WebSearch" \| "Write"] | No |+| tools | Tool names to filter. Works with tools_exclude to form an allow-list or deny-list. Leave empty to apply no tool filter. | List["add_understanding" \| "ask_question" \| "bash_exec" \| "browser_act" \| "browser_navigate" \| "browser_screenshot" \| "confirm_expert_change" \| "confirm_expert_soul_update" \| "connect_integration" \| "continue_run_block" \| "create_agent" \| "create_feature_request" \| "create_folder" \| "customize_agent" \| "decompose_goal" \| "delegate_to_expert" \| "delete_folder" \| "delete_preset" \| "delete_schedule" \| "delete_skill" \| "delete_workspace_file" \| "edit_agent" \| "enter_agent_building_mode" \| "find_agent" \| "find_block" \| "find_library_agent" \| "fix_agent_graph" \| "get_agent_building_guide" \| "get_doc_page" \| "get_mcp_guide" \| "get_platform_info" \| "get_sub_session_result" \| "handoff_to_expert" \| "hire_expert" \| "list_agent_triggers" \| "list_chat_platform_channels" \| "list_expert_chats" \| "list_folders" \| "list_presets" \| "list_schedules" \| "list_skills" \| "list_team" \| "list_workspace_files" \| "memory_forget_confirm" \| "memory_forget_search" \| "memory_search" \| "memory_store" \| "move_agents_to_folder" \| "move_folder" \| "post_to_chat_platform" \| "raise_expert" \| "read_expert_chat" \| "read_skill" \| "read_workspace_file" \| "run_agent" \| "run_block" \| "run_mcp_tool" \| "run_sub_session" \| "schedule_followup" \| "search_docs" \| "search_feature_requests" \| "setup_agent_webhook_trigger" \| "store_skill" \| "update_expert" \| "update_expert_soul" \| "update_folder" \| "update_preset" \| "validate_agent_graph" \| "view_agent_output" \| "web_fetch" \| "web_search" \| "write_workspace_file" \| "Agent" \| "Edit" \| "Glob" \| "Grep" \| "Read" \| "Task" \| "TodoWrite" \| "WebSearch" \| "Write"] | No || tools_exclude | Controls how the 'tools' list is interpreted. True (default): 'tools' is a deny-list — listed tools are blocked, all others are allowed. An empty 'tools' list means allow everything. False: 'tools' is an allow-list — only listed tools are permitted. | bool | No || blocks | Block identifiers to filter when the copilot uses run_block. Each entry can be: a block name (e.g. 'HTTP Request'), a full block UUID, or the first 8 hex characters of the UUID (e.g. 'c069dc6b'). Works with blocks_exclude. Leave empty to apply no block filter. | List[str] | No || blocks_exclude | Controls how the 'blocks' list is interpreted. True (default): 'blocks' is a deny-list — listed blocks are blocked, all others are allowed. An empty 'blocks' list means allow everything. False: 'blocks' is an allow-list — only listed blocks are permitted. | bool | No |diff --git a/docs/platform/SUMMARY.md b/docs/platform/SUMMARY.mdindex 5fe5cbcf57..d6af31c552 100644--- a/docs/platform/SUMMARY.md+++ b/docs/platform/SUMMARY.md@@ -53,6 +53,7 @@## Contributing* [Managing LLM Models](contributing/managing-llm-models.md)+* [Agent Collaboration Architecture](contributing/agent-collaboration-architecture.md)## Changelogdiff --git a/docs/platform/contributing/agent-collaboration-architecture.md b/docs/platform/contributing/agent-collaboration-architecture.mdnew file mode 100644index 0000000000..8de6faada0--- /dev/null+++ b/docs/platform/contributing/agent-collaboration-architecture.md@@ -0,0 +1,473 @@+# Agent collaboration architecture++When AutoPilot works on a request, it can hand part of the job to another+agent — a teammate expert, or a fresh copy of itself with a clean context.+That agent can hand off part of *its* job in turn. This document describes+the limits that apply to everything started that way: which tools a+handed-off job may use, how deep the chain may go, how many agents one+request may use, and how much they may spend between them.++The short version: **a spawned agent can never do more than the agent that+spawned it, and everything one request starts shares one budget and one+head-count.** Both limits are enforced in one place in the code, and a job+that would exceed either is refused before it starts, with a message the+calling agent can act on.++The implementation is `autogpt_platform/backend/backend/copilot/tree.py`.++---++## A worked example++A user asks AutoPilot to draft a customer reply. AutoPilot delegates the+research to an Ops expert and the tone pass to a Growth expert:++```+user types ──▶ AutoPilot turn ← the root; one tree opens here+ ├──▶ delegate → Ops ← depth 1+ └──▶ delegate → Growth ← depth 1+ └──▶ sub-session ← depth 2+```++Four agents, one tree. Ops and Growth each get every tool AutoPilot has+except the ones no delegated job should hold — connecting an integration,+deleting things, hiring another expert. The sub-session Growth starts is+narrower still, because it runs under Growth's own identity and shares its+memory. All four turns draw on one spend ceiling and one allowance of eight+agents: a fourth hop of depth would be refused, so would a ninth agent, and so+would any turn starting after the ceiling is reached.++None of that is visible to the user unless a limit is hit, and then what+they see is the agent finishing with what it has rather than an error.++---++## The vocabulary++Five words carry the rest of the document, plus two for the two+shapes a spawn can take.++A **turn** is one agent doing one round of work: it reads a request, calls+tools, and produces a response. A copilot session is a series of turns.++A **root** turn is one that no other agent started — a human typing, a+schedule firing, an `AutoPilotBlock` inside a graph, a message arriving from+a chat platform.++A **child** turn is one that a tool started: `run_sub_session`,+`delegate_to_expert` or `handoff_to_expert`. Every child has exactly one+parent.++A **tree** is a root turn plus every turn descended from it. The tree is the+unit that gets a budget and a head-count. It is keyed on the root turn, not+on the session, so a long-running expert thread opens a fresh tree with a+fresh budget on every human message.++An **envelope** is the set of limits one turn carries: which tree it belongs+to, how deep it sits, which tools it may call, whether its input is+untrusted, and when it must stop. Each turn has its own, and a child's is+computed from its parent's.++The two shapes get different treatment throughout:++- A **delegate** runs as a *different* expert — its own identity, its own+ memory, its own voice. `delegate_to_expert` and `handoff_to_expert` create+ delegates.+- An **isolate** runs as the *same* identity as its parent, with a clean+ context. `run_sub_session` creates isolates. Because an isolate shares its+ parent's memory and name, anything it stores the parent reads back next+ turn as its own, and anything it posts goes out under the parent's name.++---++## What a child may do++A child's tool set is computed from its parent's, and the computation can+only take tools away:++```+child.tools = (parent's tools ∩ what the spawn asked for) − denied+```++`derive_child_envelope` (`tree.py:187`) is the only function that produces+one. Nothing a model writes reaches it: the parent's own set comes from the+turn that is running, not from a database row, and the subtraction of the+denied list happens last, so no request shape can route around it.++**Every child loses these**, whatever kind it is (`DESCENT_DENIED_TOOLS`,+`tree.py:72`):++| tool | why |+|---|---|+| `connect_integration` | binds the user's account to a third party |+| `setup_agent_webhook_trigger` | registers a trigger that outlives the request |+| `update_preset` | edits saved configuration |+| `delete_folder`, `delete_preset`, `delete_schedule`, `delete_skill`, `delete_workspace_file` | irreversible |+| `hire_expert`, `raise_expert`, `update_expert`, `confirm_expert_change` | staffs the user's team |++None of these is part of a delegated job, so withholding them breaks nothing+that worked, and it removes reach a spawned agent should never quietly have.++**An isolate additionally loses these** (`ISOLATE_DENIED_TOOLS`,+`tree.py:96`): `post_to_chat_platform`, `schedule_followup`, `run_mcp_tool`,+`store_skill`, `memory_store`, `add_understanding`.++The asymmetry is the point. A delegate keeps all six, because it runs under+its own identity and its own memory — storing what it learned and posting a+scheduled update are its job. An isolate is scratch space under someone+else's name, so a memory it writes becomes the parent's memory and a message+it posts appears to come from the parent.++**There is no way to grant a denied tool back.** The subtraction is last and+absolute, so a parent that holds `post_to_chat_platform` still cannot pass it+to an isolate. A job that genuinely needs a denied tool is one a human+approves, not one an agent grants itself.++Two enforcement points, and the difference matters. The envelope's tool set+is turned into a permission filter so the model is not *shown* tools it may+not call, and `BaseTool.execute` (`tools/base.py:232`) *refuses* a call to+anything outside the envelope. Hiding is presentation; the refusal is the+control, and it covers both engines and every registered tool.++---++## How deep and how wide a tree gets++Depth is capped at **3 hops** (`MAX_DEPTH`, `tree.py:59`) and counts every+spawn kind, isolates included. A fourth hop is refused with "This task is+already 3 hops deep; do as much as you can yourself instead of passing it on+again."++Head-count is capped at **8 turns per tree, the root included**+(`tree_max_nodes`, `config.py:467`), so one request may start seven agents.+This is a lifetime budget for the request, not a concurrency limit — the+refusal says so, because an agent that reads "limit" assumes waiting will+free a slot, and here it will not.++Both are enforced at `dispatch_turn` (`executor/utils.py`), which is the one+function every turn passes through: the HTTP chat route, the scheduler,+`AutoPilotBlock`, and all three spawn tools. A turn that is refused there+never has any side effect — no session row, no queue message.++---++## What a tree can spend++A tree's spend ceiling is set when its first spawn opens it, from the user's+subscription plan:++```+ceiling = min( the user's remaining daily/weekly budget,+ max( ½ × the plan's daily allowance, $0.50 ),+ $10.00 )+```++`resolve_root_ceiling_microdollars` (`tree.py:380`) computes it; the three+constants are `tree_ceiling_fraction_of_daily`,+`tree_ceiling_floor_microdollars` and `tree_ceiling_microdollars`+(`config.py:442-466`). Scaling off the plan rather than a flat number is what+keeps the ceiling proportionate, and it is why a user with no subscription+gets zero: a plan that may not spend may not delegate.++On the code defaults, which is what production serves today — the two+LaunchDarkly flags that can override the base limits and the tier multipliers+(`copilot-cost-limits`, `copilot-tier-multipliers`) are both off there:++| Plan | Daily allowance | Per-tree ceiling | Per-turn cap |+|---|---:|---:|---:|+| NO_TIER | $0.00 | $0.00 | — |+| BASIC | $1.00 | $0.50 | $1.00 |+| PRO | $5.00 | $2.50 | $5.00 |+| MAX | $20.00 | $10.00 | $10.00 |+| BUSINESS | $60.00 | $10.00 | $10.00 |+| ENTERPRISE | $60.00 | $10.00 | $10.00 |++Allowances are the `ChatConfig` base of $1.00/day times the plan's tier+multiplier (`rate_limit.py:108`). The per-turn cap is a separate, older+control — `min($10.00, the user's remaining budget)`, floored at $0.50+(`sdk/service.py:255`) — that bounds a single turn on the Claude/OpenRouter+path. Ceilings are what a user who has spent nothing yet gets; they shrink+through the day, because remaining budget is the first term of the `min`.++**Roots never touch the ledger.** A tree only exists once something is+spawned, so the HTTP route, the scheduler and `AutoPilotBlock` are unchanged+by any of this and pay nothing for it.++### Spend is counted, not reserved++The ledger is a Redis hash per tree — `copilot:tree:<tree_id>`, holding+`ceiling`, `spent`, `nodes` and `max_nodes` — and `spent` only advances when+a turn *ends*, from the same code path that feeds the per-user rate limit+(`token_tracking.py:236`).++The consequence: **turns admitted at the same moment do not see each other's+cost**, so a wide fan-out can overshoot. Seven children dispatched in one+round all read `spent` before any of them has charged anything, and all seven+are admitted. The worst case is therefore seven turns each running to its own+per-turn cap — $7.00 on BASIC, $70.00 on MAX and above — not one turn's+overshoot. The head-count cap is what makes that finite, which is why the two+limits are enforced together and why eight is a small number.++Reserving at admission and reconciling at charge would fix it. It needs a+per-query spend figure the Codex transport does not report, so it is not+possible today: the SDK's own `max_budget_usd` is a per-query stop that+rounds upward and does not exist on that transport at all.++### When the ledger is unreachable++Spawns fail closed and roots are unaffected. If Redis cannot be reached, a+child turn is refused with "Could not account for this work right now; try+again shortly"; the user's own turn runs, exactly as it does when the+per-user rate limit degrades.++---++## Who may talk to whom++A child has exactly two edges: the request coming in from its parent, and+its report going back. Nothing else can address it, and it can address+nothing but its parent and its own children. Siblings never talk; if two+children need the same data, the parent gives it to both.++There are no sibling, peer or broadcast edges, and that is a choice rather+than an oversight. Two agents that can each wait on the other can deadlock,+and the sub-session resume path could form exactly that shape before the+creator rule below closed it. Every lateral edge is also a second place to+enforce a limit the parent already enforces once.++`handoff_to_expert` is the one edge that moves ownership: the handoff turn+is the last turn of the parent's tree, and every human message typed into the+handed-off thread afterwards is a new root with a new tree and a new ceiling.++Three rules keep that shape honest:++- **Only the creator may resume, poll or cancel a child.** Each spawn writes+ `delegated_by_session_id`, and the resume path requires it to match. A+ session cannot resume itself and siblings cannot resume each other, which+ removes a self- and mutual-deadlock. Reading is deliberately looser — it+ keeps its existing scope-equality rule, because a same-scope reader is the+ same identity under the same user, and narrowing it broke a sub reporting+ progress and a handed-off expert reading its own task.+- **A spawn never queues into a turn already in flight.** That path appends+ the message to the running turn's buffer, which would execute a child's+ prompt inside another session's turn under *that* turn's permissions. All+ three spawn tools pass `allow_queue=False`, as does `AutoPilotBlock`; a busy+ target is refused and the caller is told to wait or start fresh.+- **A question goes to the parent, not to the human.** Only a root has a+ human attached, so escalation travels the same edges as reports, in the+ same direction, and lands once.++---++## What inherits, and what does not++Three classes, and which one a parameter falls into decides its rule.++**Ceilings** can only narrow on the way down: the tool set, depth, the tree's+spend and head-count, the taint bit, the deadline, and the tenancy and+billing route (which must be identical, never merely narrower). A request+that asks to change one of these is clamped or refused, never granted.++**Identity-bound** state comes from *which* expert the child is, never from+its parent: the expert's soul and voice, its memory namespace, its+integrations and workflows, and its own weekly budget. A delegate writes to+its own memory namespace, not its parent's — memory crossing between+teammates is bounded by who was delegated to, not by the tree.++**Free within the ceiling** is the caller's choice: model, thinking effort,+how long to wait for a result. Model tier deliberately does not inherit. A+child that needs a stronger model for its narrow job should have one; what+must not widen is the spend, and the ledger bounds that whatever model runs.+Making tier monotone would push callers to over-provision the root so their+children could be capable, which raises spend — the thing being bounded.++The expert's own weekly budget stays separate from the tree ledger on+purpose. It is a per-identity guardrail its owner configured ("this expert+may not burn more than X a week on schedules"); the ledger is a per-request+spend bound. A breach pauses that expert's schedules everywhere, which is+what the guardrail means, and folding it into the tree would hide it.++---++## Untrusted input++The envelope carries a **taint** bit: an agent is tainted if its parent was,+or if it was started on untrusted input. It never clears — a new session id+does not wash it, because the bit lives on the turn rather than on the+session.++Taint flows down by inheritance and up by report. A parent that reads a+tainted child's report is reading attacker-influenceable text and is tainted+from that point. What confining a child buys is not a clean parent; it is+that the *action surface* of the agent that touched the untrusted input can+be made empty.++That is the case for pointing a narrow child at untrusted input: an agent+with `read_workspace_file` and nothing effectful has no tool an injection can+steer, and the worst it can produce is a misleading report — a bounded+artefact the parent reads as data. One agent reading the same page itself+gets steered mid-turn, before anyone sees anything.++**The guarantee belongs to the explicit read-only tool set, never to the+default.** A child that merely inherited the default narrowing still holds+`run_agent`, and `run_block`/`run_agent` reach outward-effecting blocks —+including arbitrary HTTP through `SendWebRequestBlock` — most of which carry+no sensitive-action flag. A descent-denied child is not an outward-safe+child, and nothing here should be read as saying it is.++Today nothing in the merged code *sets* the taint bit except chat-platform+sessions. The propagation exists ahead of the auto-mode approval gate — a+separate, unlanded change that decides when a turn needs a human's approval —+so that when it lands, a spawn cannot launder a tainted turn into a clean one.++---++## When a limit is hit++None of these produces an error page. Each returns a sentence to the calling+agent, which reports to the user in its own words.++| situation | what happens |+|---|---|+| Tree reaches its spend ceiling | The next spawn in that tree is refused: "This task has spent its budget; report what you have instead of starting more work." The turn already running continues and reports honestly. |+| Tree reaches 8 agents | Refused, saying explicitly that this is a lifetime budget for the request and waiting will not free a slot. |+| Fourth hop of depth | Refused: do as much as you can yourself instead of passing it on again. |+| A child crashes mid-turn | Existing behaviour — the stream errors and the turn is `failed`. Its recorded cost is charged to the tree; nothing was reserved, so nothing leaks. |+| Parent fans out past the per-user in-flight cap (15) | Existing behaviour — the spawn is rejected before any side effect and the tree's head-count is decremented. Children are rejected, never queued behind a parent waiting on them. |+| Two spawns race | Both hit the ledger; the second either fits or is refused. Admission is increment-then-check with rollback, so a race can over-admit by one — that is the bound's stated slack. |+| A session tries to resume or poll a child it did not create | Refused; the creator record does not match. |+| Target session already has a turn in flight | Refused as busy, rather than appending to the running turn's buffer. |+| Redis unreachable | Spawns fail closed; roots run. |+| A pre-existing child with no creator record | Cannot be resumed under the creator rule. A deliberate break: resuming it would mean resuming a child whose creator is unknown. |++---++## What changes for flows that work today++| flow | before | after |+|---|---|---|+| A delegated or handed-off expert posts to a chat platform, schedules a follow-up, calls an MCP tool, stores a skill or stores memory | inherited from the parent | **unchanged** — a delegate runs under its own identity, namespace and budget, so these stay in its default set |+| A delegated or handed-off expert connects an integration, sets up a webhook trigger, edits a preset, or deletes a folder, preset, schedule, skill or file | inherited | **refused** — binds the account or is irreversible; rare, visible, and recoverable, never silent data loss |+| A `run_sub_session` isolate posts outward, schedules, calls MCP, stores a skill, or writes memory | inherited | **refused** — this is the shared-namespace leak the design exists to close, and the change most likely to be noticed |+| A chain that used isolates to go past three hops | unbounded through isolates | **stops at depth 3** — isolates now count. A single isolate under a shallow chain is unaffected |+| Continuing a delegation to a teammate who is still working | queued into their running turn | **refused**, telling the caller to wait or start fresh |+| A sub-session's unanswered question | surfaced on Home | goes to its parent instead — sub-sessions now record their creator, and Home excludes delegated threads |++Whether the isolate memory-write default is too aggressive is a maintainer+call; loosening it is removing two entries from `ISOLATE_DENIED_TOOLS`.++---++## What this deliberately does not do++- No orchestrator, planner, router or manager agent, and no message bus, task+ board or work-item model beyond the queue that exists.+- No lateral edges — no sibling, peer or broadcast communication.+- No shared memory or team-wide context; memory scoping is untouched.+- No voting, debate or multi-round negotiation.+- No budget *reservation*: the ledger counts, so nothing has to be returned.+- No per-file workspace permissions. The workspace is user-scoped and flat,+ and the storage layer cannot back a per-file capability; what a child gets+ is a path to read, not a permission.+- No cross-user spawning of any kind.++---++## Limits worth knowing about++**`run_agent` starts a fresh tree.** `run_agent` is not on the denied list,+so a narrowed child keeps it, and it dispatches into the graph-executor+process where the envelope does not exist. If that graph contains an+`AutoPilotBlock`, the turn it starts is a *root*: unrestricted tools, depth+0, untainted, and a new tree with its own ceiling and head-count. A child's+narrowing, its place under the depth bound and its share of the tree's budget+are all reset. Nothing regresses against the previous behaviour, where+spawned turns had no envelope at all.+[#14265](https://github.com/Significant-Gravitas/AutoGPT/pull/14265) closes it by+carrying the tree through `ExecutionContext` into the executor process, the same+way expert identity already rides it for billing. Adding `run_agent` to the+denied list is the one-line alternative, at the cost of every delegate's ability+to run a graph.++**Graph spend is not on the ledger.** A graph run a child starts with+`run_agent` is charged in credits to the user's wallet and to the expert's+weekly budget, not to the tree. The ledger bounds LLM spend across the tree;+the wallet and the weekly budget bound graph spend; they are not yet one+number.++**Memory and the workspace are not tree-scoped.** Memory is shared along+identity — an isolate shares its parent's namespace, and every AutoPilot turn+for one user shares that user's. The workspace is user-wide. Neither can be+made a tree property without rebuilding the storage layer, so the design+closes the *write* side instead: isolates lose memory writes, and confining+workspace writes to the writing session's own folder is a named follow-up+below. A child can still read what its identity or its user can read.++**A tree bounds spend, not concurrency.** How many agents exist at once is+still governed by the per-user in-flight cap of 15. Across an organisation+that means total spend is bounded by the sum of users' own caps plus each+tree's overshoot, with nothing summing across trees — but "3000 agents" means+3000 experts across many users and schedules, not 3000 sessions running at+once under one root.++---++## Carried in the code but not reachable from any tool++So the shipped surface is not read as wider than it is:++- `tainted` propagates and is tested, but nothing reads it until the+ auto-mode gate lands.+- `SpawnRequest.max_seconds` has no caller, so `deadline_at` is always+ `None` and no deadline ever fires. There is no watcher either — the cancel+ function exists, nothing calls it on a timer.+- `SpawnRequest.tools` (the exact-set pin) has no caller, so the read-only+ quarantine shape described above is expressible in code but not selectable+ from any tool.+- `may_spawn=False` has no caller — all three spawn tools pass `True` — so no+ leaf is created in production.++---++## Designed, not built++The shape of what crosses an edge is settled and unimplemented. Today a spawn+carries free text plus the existing preamble; `SpawnRequest` carries only+`tools`, `may_spawn`, `shares_memory`, `max_seconds` and `born_tainted`. The+intended request is a **brief** with named slots — the task written for+someone who cannot see this thread, an inline payload for a child with no+tool to read a reference, workspace paths as references, what the child may+commit to, and what "done" looks like — and the intended response is a+**report** with a status, a summary, findings that carry a verbatim quote+each, the paths it wrote, and its taint bit.++Two slots earn a note. Saying what the child may commit to turns its boundary+decisions into closed questions instead of guesses: in an internal evaluation,+adding that list to an otherwise byte-identical prompt moved it from 9 correct+verdicts out of 18 to 15. Findings that carry a quote are what make a report+*checkable* rather than merely readable, which is what lets a parent audit a+child without re-doing its work.++Also named and not built: the deadline watcher; block filters in the envelope+(tools only today — `CopilotPermissions._parent` is a private attribute and+is dropped when the queue entry is serialised); workspace write confinement;+withholding the team roster from children that cannot spawn, which matters+because injecting the full roster is the one part of session creation that+grows with the number of experts.++---++## Where the code is++| what | where |+|---|---|+| Envelope, derivation, ledger, ceiling | `copilot/tree.py` |+| The one seam every turn passes | `copilot/executor/utils.py::dispatch_turn` |+| Tool refusal | `copilot/tools/base.py::BaseTool.execute` |+| Charging a turn to its tree | `copilot/token_tracking.py` |+| The running turn's envelope | `copilot/context.py::get_current_envelope` |+| Per-user daily/weekly caps and tier multipliers | `copilot/rate_limit.py` |+| Per-turn spend cap | `copilot/sdk/service.py::_resolve_dynamic_max_budget_usd` |+| The three spawn tools | `copilot/tools/{run_sub_session,delegate_to_expert,handoff_to_expert}.py` |+| Cross-expert chain check (loop detection) | `copilot/tools/expert_delegation.py::chain_refusal` |+| Tests | `copilot/tree_test.py`, `copilot/tools/sub_session_test.py` |