Skip to content

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

refactor(backend/copilot): unified queue-backed copilot turns + async sub-AutoPilot + guide-read gate (#12841)

Zamil Majdyfcaebd1bb76c
diff --git a/.claude/skills/pr-test/SKILL.md b/.claude/skills/pr-test/SKILL.md
index 10b3b3efdc..b368fb7f0d 100644
--- a/.claude/skills/pr-test/SKILL.md
+++ b/.claude/skills/pr-test/SKILL.md
@@ -5,7 +5,7 @@ user-invocable: true
argument-hint: "[worktree path or PR number] — tests the PR in the given worktree. Optional flags: --fix (auto-fix issues found)"
metadata:
author: autogpt-team
- version: "2.0.0"
+ version: "2.1.0"
---
# Manual E2E Test
@@ -180,6 +180,94 @@ Based on the PR analysis, write a test plan to `$RESULTS_DIR/test-plan.md`:
**Be critical** — include edge cases, error paths, and security checks. Every scenario MUST specify what screenshots to take and what state to verify.
+## Step 3.0: Claim the testing lock (coordinate parallel agents)
+
+Multiple worktrees share the same host — Docker infra (postgres, redis, clamav), app ports (3000/8006/…), and the test user. Two agents running `/pr-test` concurrently will corrupt each other's state (connection-pool exhaustion, port binds failing silently, cross-test assertions). Use the root-worktree lock file to take turns.
+
+### Lock file contract
+
+Path (**always** the root worktree so all siblings see it): `/Users/majdyz/Code/AutoGPT/.ign.testing.lock`
+
+Body (one `key=value` per line):
+```
+holder=<pr-XXXXX-purpose>
+pid=<pid-or-"self">
+started=<iso8601>
+heartbeat=<iso8601, updated every ~2 min>
+worktree=<full path>
+branch=<branch name>
+intent=<one-line description + rough duration>
+```
+
+### Claim
+
+```bash
+LOCK=/Users/majdyz/Code/AutoGPT/.ign.testing.lock
+NOW=$(date -u +%Y-%m-%dT%H:%MZ)
+STALE_AFTER_MIN=5
+
+if [ -f "$LOCK" ]; then
+ HB=$(grep '^heartbeat=' "$LOCK" | cut -d= -f2)
+ HB_EPOCH=$(date -j -f '%Y-%m-%dT%H:%MZ' "$HB" +%s 2>/dev/null || date -d "$HB" +%s 2>/dev/null || echo 0)
+ AGE_MIN=$(( ( $(date -u +%s) - HB_EPOCH ) / 60 ))
+ if [ "$AGE_MIN" -gt "$STALE_AFTER_MIN" ]; then
+ echo "WARN: stale lock (${AGE_MIN}m old) — reclaiming"
+ cat "$LOCK" | sed 's/^/ stale: /'
+ else
+ echo "Another agent holds the lock:"; cat "$LOCK"
+ echo "Wait until released or resume after $((STALE_AFTER_MIN - AGE_MIN))m."
+ exit 1
+ fi
+fi
+
+cat > "$LOCK" <<EOF
+holder=pr-${PR_NUMBER}-e2e
+pid=self
+started=$NOW
+heartbeat=$NOW
+worktree=$WORKTREE_PATH
+branch=$(cd $WORKTREE_PATH && git branch --show-current)
+intent=E2E test PR #${PR_NUMBER}, native mode, ~60min
+EOF
+echo "Lock claimed"
+```
+
+### Heartbeat (MUST run in background during the whole test)
+
+Without a heartbeat a crashed agent keeps the lock forever. Run this as a background process right after claim:
+
+```bash
+(while true; do
+ sleep 120
+ [ -f "$LOCK" ] || exit 0 # lock released → exit heartbeat
+ perl -i -pe "s/^heartbeat=.*/heartbeat=$(date -u +%Y-%m-%dT%H:%MZ)/" "$LOCK"
+ done) &
+HEARTBEAT_PID=$!
+echo "$HEARTBEAT_PID" > /tmp/pr-test-heartbeat.pid
+```
+
+### Release (always — even on failure)
+
+```bash
+kill "$HEARTBEAT_PID" 2>/dev/null
+rm -f "$LOCK" /tmp/pr-test-heartbeat.pid
+echo "$(date -u +%Y-%m-%dT%H:%MZ) [pr-${PR_NUMBER}] released lock" \
+ >> /Users/majdyz/Code/AutoGPT/.ign.testing.log
+```
+
+Use a `trap` so release runs even on `exit 1`:
+```bash
+trap 'kill "$HEARTBEAT_PID" 2>/dev/null; rm -f "$LOCK"' EXIT INT TERM
+```
+
+### Shared status log
+
+`/Users/majdyz/Code/AutoGPT/.ign.testing.log` is an append-only channel any agent can read/write. Use it for "I'm waiting", "I'm done, resources free", or post-run notes:
+```bash
+echo "$(date -u +%Y-%m-%dT%H:%MZ) [pr-${PR_NUMBER}] <message>" \
+ >> /Users/majdyz/Code/AutoGPT/.ign.testing.log
+```
+
## Step 3: Environment setup
### 3a. Copy .env files from the root worktree
@@ -248,7 +336,87 @@ docker ps --format "{{.Names}}" | grep -E "rest_server|executor|copilot|websocke
done
```
-### 3e. Build and start
+**Native mode also:** when running the app natively (see 3e-native), kill any stray host processes and free the app ports before starting — otherwise `poetry run app` and `pnpm dev` will fail to bind.
+
+```bash
+# Kill stray native app processes from prior runs
+pkill -9 -f "python.*backend" 2>/dev/null || true
+pkill -9 -f "poetry run app" 2>/dev/null || true
+pkill -9 -f "next-server|next dev" 2>/dev/null || true
+
+# Free app ports (errors per port are ignored — port may simply be unused)
+for port in 3000 8006 8001 8002 8005 8008; do
+ lsof -ti :$port -sTCP:LISTEN | xargs -r kill -9 2>/dev/null || true
+done
+```
+
+### 3e-native. Run the app natively (PREFERRED for iterative dev)
+
+Native mode runs infra (postgres, supabase, redis, rabbitmq, clamav) in docker but runs the backend and frontend directly on the host. This avoids the 3-8 minute `docker compose build` cycle on every backend change — code edits are picked up on process restart (seconds) instead of a full image rebuild.
+
+**When to prefer native mode (default for this skill):**
+- Iterative dev/debug loops where you're editing backend or frontend code between test runs
+- Any PR that touches Python/TS source but not Dockerfiles, compose config, or infra images
+- Fast repro of a failing scenario — restart `poetry run app` in a couple of seconds
+
+**When to prefer docker mode (3e fallback):**
+- Testing changes to `Dockerfile`, `docker-compose.yml`, or base images
+- Production-parity smoke tests (exact container env, networking, volumes)
+- CI-equivalent runs where you need the exact image that'll ship
+
+**Note on 3b (copilot auth):** no npm install anywhere. `poetry install` pulls in `claude_agent_sdk`, which ships its own Claude CLI binary — available on `PATH` whenever you run commands via `poetry run` (native) OR whenever the copilot_executor container is built from its Poetry lockfile (docker). The OAuth token extraction still applies (same `refresh_claude_token.sh` call).
+
+**Preamble:** before starting native, run the kill-stray + free-ports block from 3c's "Native mode also" subsection.
+
+**1. Start infra only (one-time per session):**
+
+```bash
+cd $PLATFORM_DIR && docker compose --profile local up deps --detach --remove-orphans --build
+```
+
+This brings up postgres/supabase/redis/rabbitmq/clamav and skips all app services.
+
+**2. Start the backend natively:**
+
+```bash
+cd $BACKEND_DIR && (poetry run app 2>&1 | tee .ign.application.logs) &
+```
+
+`poetry run app` spawns **all** app subprocesses — `rest_server`, `executor`, `copilot_executor`, `websocket`, `scheduler`, `notification_server`, `database_manager` — inside ONE parent process. No separate containers, no separate terminals. The `.ign.application.logs` prefix is already gitignored.
+
+**3. Wait for the backend on :8006 BEFORE starting the frontend.** This ordering matters — the frontend's `pnpm dev` startup invokes `generate-api-queries`, which fetches `/openapi.json` from the backend. If the backend isn't listening yet, `pnpm dev` fails immediately.
+
+```bash
+for i in $(seq 1 60); do
+ if [ "$(curl -s -o /dev/null -w '%{http_code}' http://localhost:8006/docs 2>/dev/null)" = "200" ]; then
+ echo "Backend ready"
+ break
+ fi
+ sleep 2
+done
+```
+
+**4. Start the frontend natively:**
+
+```bash
+cd $FRONTEND_DIR && (pnpm dev 2>&1 | tee .ign.frontend.logs) &
+```
+
+**5. Wait for the frontend on :3000:**
+
+```bash
+for i in $(seq 1 60); do
+ if [ "$(curl -s -o /dev/null -w '%{http_code}' http://localhost:3000 2>/dev/null)" = "200" ]; then
+ echo "Frontend ready"
+ break
+ fi
+ sleep 2
+done
+```
+
+Once both are up, skip 3e/3f and go straight to **3g/3h** (feature flags / test user creation).
+
+### 3e. Build and start (docker — fallback)
```bash
cd $PLATFORM_DIR && docker compose build --no-cache 2>&1 | tail -20
@@ -442,6 +610,22 @@ agent-browser --session-name pr-test snapshot | grep "text:"
### Checking logs
+**Native mode:** when running via `poetry run app` + `pnpm dev`, all app logs stream to the `.ign.*.logs` files written by the `tee` pipes in 3e-native. `rest_server`, `executor`, `copilot_executor`, `websocket`, `scheduler`, `notification_server`, and `database_manager` are all subprocesses of the single `poetry run app` parent, so their output is interleaved in `.ign.application.logs`.
+
+```bash
+# Backend (all app subprocesses interleaved)
+tail -f $BACKEND_DIR/.ign.application.logs
+
+# Frontend (Next.js dev server)
+tail -f $FRONTEND_DIR/.ign.frontend.logs
+
+# Filter for errors across either log
+grep -iE "error|exception|traceback" $BACKEND_DIR/.ign.application.logs | tail -20
+grep -iE "error|exception|traceback" $FRONTEND_DIR/.ign.frontend.logs | tail -20
+```
+
+**Docker mode:**
+
```bash
# Backend REST server
docker logs autogpt_platform-rest_server-1 2>&1 | tail -30
@@ -876,9 +1060,15 @@ test scenario → find issue (bug OR UX problem) → screenshot broken state
### Problem: Frontend shows cookie banner blocking interaction
**Fix:** `agent-browser click 'text=Accept All'` before other interactions.
-### Problem: Container loses npm packages after rebuild
-**Cause:** `docker compose up --build` rebuilds the image, losing runtime installs.
-**Fix:** Add packages to the Dockerfile instead of installing at runtime.
+### Problem: Claude CLI not found in copilot_executor container
+**Symptom:** Copilot logs say `claude: command not found` or similar when starting an SDK turn.
+**Cause:** Image was built without `poetry install` (stale base layer, or Dockerfile bypass). The SDK CLI ships inside the `claude_agent_sdk` Poetry dep — it is NOT an npm package.
+**Fix:** Rebuild the image cleanly: `docker compose build --no-cache copilot_executor && docker compose up -d copilot_executor`. Do NOT `docker exec ... npm install -g @anthropic-ai/claude-code` — that is outdated guidance and will pollute the container with a second CLI that the SDK won't use.
+
+### Problem: agent-browser screenshot hangs / times out
+**Symptom:** `agent-browser screenshot` exits with code 124 even on `about:blank`.
+**Cause:** Stuck CDP connection or Chromium process tree. Seen on macOS when a prior `/pr-test` left a zombie Chrome for Testing.
+**Fix:** `pkill -9 -f "agent-browser|chromium|Chrome for Testing" && sleep 2`, then reopen the browser with a fresh `--session-name`. If still failing, verify via `agent-browser eval` + `agent-browser snapshot` (DOM state) instead of relying on PNGs — the feature under test is the same.
### Problem: Services not starting after `docker compose up`
**Fix:** Wait and check health: `docker compose ps`. Common cause: migration hasn't finished. Check: `docker logs autogpt_platform-migrate-1 2>&1 | tail -5`. If supabase-db isn't healthy: `docker restart supabase-db && sleep 10`.
diff --git a/autogpt_platform/backend/backend/blocks/autopilot.py b/autogpt_platform/backend/backend/blocks/autopilot.py
index af783b0757..3a556d286c 100644
--- a/autogpt_platform/backend/backend/blocks/autopilot.py
+++ b/autogpt_platform/backend/backend/blocks/autopilot.py
@@ -23,6 +23,7 @@ from backend.copilot.permissions import (
validate_block_identifiers,
)
from backend.data.model import SchemaField
+from backend.util.exceptions import BlockExecutionError
if TYPE_CHECKING:
from backend.data.execution import ExecutionContext
@@ -32,9 +33,36 @@ logger = logging.getLogger(__name__)
# Block ID shared between autopilot.py and copilot prompting.py.
AUTOPILOT_BLOCK_ID = "c069dc6b-c3ed-4c12-b6e5-d47361e64ce6"
+# Identifiers used when registering an AutoPilotBlock turn with the
+# stream registry — distinguishes block-originated turns from sub-session
+# or HTTP SSE turns in logs / observability.
+_AUTOPILOT_TOOL_CALL_ID = "autopilot_block"
+_AUTOPILOT_TOOL_NAME = "autopilot_block"
-class SubAgentRecursionError(RuntimeError):
- """Raised when the sub-agent nesting depth limit is exceeded."""
+# Ceiling on how long AutoPilotBlock.execute_copilot will wait for the
+# enqueued turn's terminal event. Graph blocks run synchronously from
+# the caller's perspective so we wait effectively as long as needed; 6h
+# matches the previous abandoned-task cap and is much longer than any
+# legitimate AutoPilot turn.
+_AUTOPILOT_BLOCK_MAX_WAIT_SECONDS = 6 * 60 * 60 # 6 hours
+
+
+class SubAgentRecursionError(BlockExecutionError):
+ """Raised when the AutoPilot sub-agent nesting depth limit is exceeded.
+
+ Inherits :class:`BlockExecutionError` — this is a known, handled
+ runtime failure at the block level (caller nested AutoPilotBlocks
+ beyond the configured limit). Surfaces with the block_name /
+ block_id the block framework expects, instead of being wrapped in
+ ``BlockUnknownError``.
+ """
+
+ def __init__(self, message: str) -> None:
+ super().__init__(
+ message=message,
+ block_name="AutoPilotBlock",
+ block_id=AUTOPILOT_BLOCK_ID,
+ )
class ToolCallEntry(TypedDict):
@@ -268,11 +296,15 @@ class AutoPilotBlock(Block):
user_id: str,
permissions: "CopilotPermissions | None" = None,
) -> tuple[str, list[ToolCallEntry], str, str, TokenUsage]:
- """Invoke the copilot and collect all stream results.
+ """Invoke the copilot on the copilot_executor queue and aggregate the
+ result.
- Delegates to :func:`collect_copilot_response` — the shared helper that
- consumes ``stream_chat_completion_sdk`` without wrapping it in an
- ``asyncio.timeout`` (the SDK manages its own heartbeat-based timeouts).
+ Delegates to :func:`run_copilot_turn_via_queue` — the shared
+ primitive used by ``run_sub_session`` too — which creates the
+ stream_registry meta record, enqueues the job, and waits on the
+ Redis stream for the terminal event. Any available
+ copilot_executor worker picks up the job, so this call survives
+ the graph-executor worker dying mid-turn (RabbitMQ redelivers).
Args:
prompt: The user task/instruction.
@@ -285,8 +317,8 @@ class AutoPilotBlock(Block):
Returns:
A tuple of (response_text, tool_calls, history_json, session_id, usage).
"""
- from backend.copilot.sdk.collect import (
- collect_copilot_response, # avoid circular import
+ from backend.copilot.sdk.session_waiter import (
+ run_copilot_turn_via_queue, # avoid circular import
)
tokens = _check_recursion(max_recursion_depth)
@@ -299,14 +331,31 @@ class AutoPilotBlock(Block):
if system_context:
effective_prompt = f"[System Context: {system_context}]\n\n{prompt}"
- result = await collect_copilot_response(
+ outcome, result = await run_copilot_turn_via_queue(
session_id=session_id,
- message=effective_prompt,
user_id=user_id,
+ message=effective_prompt,
+ # Graph block execution is synchronous from the caller's
+ # perspective — wait effectively as long as needed. The
+ # SDK enforces its own idle-based timeout inside the
+ # stream_registry pipeline.
+ timeout=_AUTOPILOT_BLOCK_MAX_WAIT_SECONDS,
permissions=effective_permissions,
+ tool_call_id=_AUTOPILOT_TOOL_CALL_ID,
+ tool_name=_AUTOPILOT_TOOL_NAME,
)
+ if outcome == "failed":
+ raise RuntimeError(
+ "AutoPilot turn failed — see the session's transcript"
+ )
+ if outcome == "running":
+ raise RuntimeError(
+ "AutoPilot turn did not complete within "
+ f"{_AUTOPILOT_BLOCK_MAX_WAIT_SECONDS}s — session "
+ f"{session_id}"
+ )
- # Build a lightweight conversation summary from streamed data.
+ # Build a lightweight conversation summary from the aggregated data.
turn_messages: list[dict[str, Any]] = [
{"role": "user", "content": effective_prompt},
]
@@ -315,7 +364,7 @@ class AutoPilotBlock(Block):
{
"role": "assistant",
"content": result.response_text,
- "tool_calls": result.tool_calls,
+ "tool_calls": [tc.model_dump() for tc in result.tool_calls],
}
)
else:
@@ -326,11 +375,11 @@ class AutoPilotBlock(Block):
tool_calls: list[ToolCallEntry] = [
{
- "tool_call_id": tc["tool_call_id"],
- "tool_name": tc["tool_name"],
- "input": tc["input"],
- "output": tc["output"],
- "success": tc["success"],
+ "tool_call_id": tc.tool_call_id,
+ "tool_name": tc.tool_name,
+ "input": tc.input,
+ "output": tc.output,
+ "success": tc.success,
}
for tc in result.tool_calls
]
diff --git a/autogpt_platform/backend/backend/copilot/constants.py b/autogpt_platform/backend/backend/copilot/constants.py
index aa6d1e2d65..9a7388ab1b 100644
--- a/autogpt_platform/backend/backend/copilot/constants.py
+++ b/autogpt_platform/backend/backend/copilot/constants.py
@@ -27,6 +27,24 @@ COMPACTION_DONE_MSG = "Earlier messages were summarized to fit within context li
COMPACTION_TOOL_NAME = "context_compaction"
+# ---------------------------------------------------------------------------
+# Tool / stream timing budget
+# ---------------------------------------------------------------------------
+# Max seconds any single MCP tool call may block the stream before returning
+# a "still running" handle. Shared by run_agent (wait_for_result),
+# view_agent_output (wait_if_running), run_sub_session (wait_for_result),
+# get_sub_session_result (wait_if_running), and run_block (hard cap).
+#
+# Chosen so the stream idle timeout (2× this) always has headroom — a tool
+# that returns right at the cap can't race the idle watchdog.
+MAX_TOOL_WAIT_SECONDS = 5 * 60 # 5 minutes
+
+# Idle-stream watchdog: abort the SDK stream if no meaningful event arrives
+# for this long. Derived from MAX_TOOL_WAIT_SECONDS so the invariant
+# "no tool blocks >= idle_timeout" holds by construction.
+STREAM_IDLE_TIMEOUT_SECONDS = MAX_TOOL_WAIT_SECONDS * 2 # 10 minutes
+
+
def is_copilot_synthetic_id(id_value: str) -> bool:
"""Check if an ID is a CoPilot synthetic ID (not from a real graph execution)."""
return id_value.startswith(COPILOT_SYNTHETIC_ID_PREFIX)
diff --git a/autogpt_platform/backend/backend/copilot/executor/processor.py b/autogpt_platform/backend/backend/copilot/executor/processor.py
index 0266e57806..adcb35a3dd 100644
--- a/autogpt_platform/backend/backend/copilot/executor/processor.py
+++ b/autogpt_platform/backend/backend/copilot/executor/processor.py
@@ -222,6 +222,10 @@ class CoPilotProcessor:
Shuts down the workspace storage instance that belongs to this
worker's event loop, ensuring ``aiohttp.ClientSession.close()``
runs on the same loop that created the session.
+
+ Sub-AutoPilots are enqueued on the copilot_execution queue, so
+ rolling deploys survive via RabbitMQ redelivery — no bespoke
+ shutdown notifier needed.
"""
coro = shutdown_workspace_storage()
try:
@@ -352,6 +356,7 @@ class CoPilotProcessor:
file_ids=entry.file_ids,
mode=effective_mode,
model=entry.model,
+ permissions=entry.permissions,
)
async for chunk in stream_registry.stream_and_publish(
session_id=entry.session_id,
diff --git a/autogpt_platform/backend/backend/copilot/executor/utils.py b/autogpt_platform/backend/backend/copilot/executor/utils.py
index 3256f94869..29ef58a7be 100644
--- a/autogpt_platform/backend/backend/copilot/executor/utils.py
+++ b/autogpt_platform/backend/backend/copilot/executor/utils.py
@@ -10,6 +10,7 @@ import logging
from pydantic import BaseModel
from backend.copilot.config import CopilotLlmModel, CopilotMode
+from backend.copilot.permissions import CopilotPermissions
from backend.data.rabbitmq import Exchange, ExchangeType, Queue, RabbitMQConfig
from backend.util.logging import TruncatedLogger, is_structured_logging_enabled
@@ -163,6 +164,11 @@ class CoPilotExecutionEntry(BaseModel):
model: CopilotLlmModel | None = None
"""Per-request model tier: 'standard' or 'advanced'. None = server default."""
+ permissions: CopilotPermissions | None = None
+ """Capability filter inherited from a parent run (e.g. ``run_sub_session``
+ forwards its parent's permissions so the sub can't escalate). ``None``
+ means the worker applies no filter."""
+
class CancelCoPilotEvent(BaseModel):
"""Event to cancel a CoPilot operation."""
@@ -184,6 +190,7 @@ async def enqueue_copilot_turn(
file_ids: list[str] | None = None,
mode: CopilotMode | None = None,
model: CopilotLlmModel | None = None,
+ permissions: CopilotPermissions | None = None,
) -> None:
"""Enqueue a CoPilot task for processing by the executor service.
@@ -197,6 +204,8 @@ async def enqueue_copilot_turn(
file_ids: Optional workspace file IDs attached to the user's message
mode: Autopilot mode override ('fast' or 'extended_thinking'). None = server default.
model: Per-request model tier ('standard' or 'advanced'). None = server default.
+ permissions: Capability filter inherited from a parent run (sub-AutoPilot).
+ None = no filter.
"""
from backend.util.clients import get_async_copilot_queue
@@ -210,6 +219,7 @@ async def enqueue_copilot_turn(
file_ids=file_ids,
mode=mode,
model=model,
+ permissions=permissions,
)
queue_client = await get_async_copilot_queue()
diff --git a/autogpt_platform/backend/backend/copilot/permissions.py b/autogpt_platform/backend/backend/copilot/permissions.py
index a30ee282f7..a87cad1e9b 100644
--- a/autogpt_platform/backend/backend/copilot/permissions.py
+++ b/autogpt_platform/backend/backend/copilot/permissions.py
@@ -87,6 +87,7 @@ ToolName = Literal[
"get_agent_building_guide",
"get_doc_page",
"get_mcp_guide",
+ "get_sub_session_result",
"list_folders",
"list_workspace_files",
"memory_forget_confirm",
@@ -99,6 +100,7 @@ ToolName = Literal[
"run_agent",
"run_block",
"run_mcp_tool",
+ "run_sub_session",
"search_docs",
"search_feature_requests",
"update_folder",
diff --git a/autogpt_platform/backend/backend/copilot/prompting.py b/autogpt_platform/backend/backend/copilot/prompting.py
index ed436733dd..3ec75e8bbe 100644
--- a/autogpt_platform/backend/backend/copilot/prompting.py
+++ b/autogpt_platform/backend/backend/copilot/prompting.py
@@ -8,11 +8,10 @@ handling the distinction between:
from functools import cache
-from backend.blocks.autopilot import AUTOPILOT_BLOCK_ID
from backend.copilot.tools import TOOL_REGISTRY
# Shared technical notes that apply to both SDK and baseline modes
-_SHARED_TOOL_NOTES = f"""\
+_SHARED_TOOL_NOTES = """\
### Sharing files
After `write_workspace_file`, embed the `download_url` in Markdown:
@@ -68,13 +67,13 @@ that would be corrupted by text encoding.
Example — committing an image file to GitHub:
```json
-{{
- "files": [{{
+{
+ "files": [{
"path": "docs/hero.png",
"content": "workspace://abc123#image/png",
"operation": "upsert"
- }}]
-}}
+ }]
+}
```
### Writing large files — CRITICAL (causes production failures)
@@ -149,20 +148,27 @@ When the user asks to interact with a service or API, follow this order:
All tasks must run in the foreground.
### Delegating to another autopilot (sub-autopilot pattern)
-Use the **AutoPilotBlock** (`run_block` with block_id
-`{AUTOPILOT_BLOCK_ID}`) to delegate a task to a fresh
-autopilot instance. The sub-autopilot has its own full tool set and can
-perform multi-step work autonomously.
-
-- **Input**: `prompt` (required) — the task description.
- Optional: `system_context` to constrain behavior, `session_id` to
- continue a previous conversation, `max_recursion_depth` (default 3).
-- **Output**: `response` (text), `tool_calls` (list), `session_id`
- (for continuation), `conversation_history`, `token_usage`.
+Use the **`run_sub_session`** tool to delegate a task to a fresh
+sub-AutoPilot. The sub has its own full tool set and can perform
+multi-step work autonomously.
+
+- `prompt` (required): the task description.
+- `system_context` (optional): extra context prepended to the prompt.
+- `sub_autopilot_session_id` (optional): continue an existing
+ sub-AutoPilot — pass the `sub_autopilot_session_id` returned by a
+ previous completed run.
+- `wait_for_result` (default 60, max 300): seconds to wait inline. If
+ the sub isn't done by then you get `status="running"` + a
+ `sub_session_id` — call **`get_sub_session_result`** with that id
+ (wait up to 300s more per call) until it returns `completed` or
+ `error`. Works across turns — safe to reconnect in a later message.
Use this when a task is complex enough to benefit from a separate
autopilot context, e.g. "research X and write a report" while the
-parent autopilot handles orchestration.
+parent autopilot handles orchestration. Do NOT invoke `AutoPilotBlock`
+via `run_block` — it's hidden from `run_block` by design because the
+dedicated tool handles the async lifecycle correctly.
+
"""
# E2B-only notes — E2B has full internet access so gh CLI works there.
diff --git a/autogpt_platform/backend/backend/copilot/sdk/collect.py b/autogpt_platform/backend/backend/copilot/sdk/collect.py
index 50952d6aaf..175b344d78 100644
--- a/autogpt_platform/backend/backend/copilot/sdk/collect.py
+++ b/autogpt_platform/backend/backend/copilot/sdk/collect.py
@@ -16,18 +16,12 @@ from typing import TYPE_CHECKING, Any
if TYPE_CHECKING:
from backend.copilot.permissions import CopilotPermissions
-from pydantic import BaseModel, Field
+from pydantic import BaseModel
from redis.exceptions import RedisError
from .. import stream_registry
-from ..response_model import (
- StreamError,
- StreamTextDelta,
- StreamToolInputAvailable,
- StreamToolOutputAvailable,
- StreamUsage,
-)
from .service import stream_chat_completion_sdk
+from .stream_accumulator import EventAccumulator, process_event
logger = logging.getLogger(__name__)
@@ -111,61 +105,6 @@ async def _registry_session(
)
-class _ToolCallEntry(BaseModel):
- """A single tool call observed during stream consumption."""
-
- tool_call_id: str
- tool_name: str
- input: Any
- output: Any = None
- success: bool | None = None
-
-
-class _EventAccumulator(BaseModel):
- """Mutable accumulator for stream events."""
-
- response_parts: list[str] = Field(default_factory=list)
- tool_calls: list[_ToolCallEntry] = Field(default_factory=list)
- tool_calls_by_id: dict[str, _ToolCallEntry] = Field(default_factory=dict)
- prompt_tokens: int = 0
- completion_tokens: int = 0
- total_tokens: int = 0
-
-
-def _process_event(event: object, acc: _EventAccumulator) -> str | None:
- """Process a single stream event and return error_msg if StreamError.
-
- Uses structural pattern matching for dispatch per project guidelines.
- """
- match event:
- case StreamTextDelta(delta=delta):
- acc.response_parts.append(delta)
- case StreamToolInputAvailable() as e:
- entry = _ToolCallEntry(
- tool_call_id=e.toolCallId,
- tool_name=e.toolName,
- input=e.input,
- )
- acc.tool_calls.append(entry)
- acc.tool_calls_by_id[e.toolCallId] = entry
- case StreamToolOutputAvailable() as e:
- if tc := acc.tool_calls_by_id.get(e.toolCallId):
- tc.output = e.output
- tc.success = e.success
- else:
- logger.debug(
- "Received tool output for unknown tool_call_id: %s",
- e.toolCallId,
- )
- case StreamUsage() as e:
- acc.prompt_tokens += e.prompt_tokens
- acc.completion_tokens += e.completion_tokens
- acc.total_tokens += e.total_tokens
- case StreamError(errorText=err):
- return err
- return None
-
-
async def collect_copilot_response(
*,
session_id: str,
@@ -210,9 +149,9 @@ async def collect_copilot_response(
stream=raw_stream,
)
- acc = _EventAccumulator()
+ acc = EventAccumulator()
async for event in published_stream:
- if err := _process_event(event, acc):
+ if err := process_event(event, acc):
handle.error_msg = err
# stream_and_publish skips StreamError events, so
# mark_session_completed must publish the error to Redis.
diff --git a/autogpt_platform/backend/backend/copilot/sdk/file_ref_integration_test.py b/autogpt_platform/backend/backend/copilot/sdk/file_ref_integration_test.py
index 117dcfc02d..949269e1cb 100644
--- a/autogpt_platform/backend/backend/copilot/sdk/file_ref_integration_test.py
+++ b/autogpt_platform/backend/backend/copilot/sdk/file_ref_integration_test.py
@@ -84,9 +84,10 @@ async def test_resolve_file_ref_local_path_with_line_range():
async def test_resolve_file_ref_rejects_path_outside_sdk_cwd():
"""resolve_file_ref raises ValueError for paths outside sdk_cwd."""
with tempfile.TemporaryDirectory() as sdk_cwd:
- with patch("backend.copilot.context._current_sdk_cwd") as mock_cwd_var, patch(
- "backend.copilot.context._current_sandbox"
- ) as mock_sandbox_var:
+ with (
+ patch("backend.copilot.context._current_sdk_cwd") as mock_cwd_var,
+ patch("backend.copilot.context._current_sandbox") as mock_sandbox_var,
+ ):
mock_cwd_var.get.return_value = sdk_cwd
mock_sandbox_var.get.return_value = None
@@ -387,11 +388,13 @@ async def test_read_file_handler_local_file():
with open(test_file, "w") as f:
f.writelines(lines)
- with patch("backend.copilot.context._current_sdk_cwd") as mock_cwd_var, patch(
- "backend.copilot.context._current_project_dir"
- ) as mock_proj_var, patch(
- "backend.copilot.sdk.tool_adapter.get_execution_context",
- return_value=("user-1", _make_session()),
+ with (
+ patch("backend.copilot.context._current_sdk_cwd") as mock_cwd_var,
+ patch("backend.copilot.context._current_project_dir") as mock_proj_var,
+ patch(
+ "backend.copilot.sdk.tool_adapter.get_execution_context",
+ return_value=("user-1", _make_session()),
+ ),
):
mock_cwd_var.get.return_value = sdk_cwd
# No project_dir set — so is_sdk_tool_path returns False for sdk_cwd paths
@@ -413,12 +416,15 @@ async def test_read_file_handler_workspace_uri():
mock_manager = AsyncMock()
mock_manager.read_file_by_id.return_value = b"workspace file content\nline two\n"
- with patch(
- "backend.copilot.sdk.tool_adapter.get_execution_context",
- return_value=("user-1", mock_session),
- ), patch(
- "backend.copilot.sdk.file_ref.get_workspace_manager",
- new=AsyncMock(return_value=mock_manager),
+ with (
+ patch(
+ "backend.copilot.sdk.tool_adapter.get_execution_context",
+ return_value=("user-1", mock_session),
+ ),
+ patch(
+ "backend.copilot.sdk.file_ref.get_workspace_manager",
+ new=AsyncMock(return_value=mock_manager),
+ ),
):
result = await _read_file_handler(
{"file_path": "workspace://file-id-abc", "offset": 0, "limit": 10}
@@ -446,11 +452,13 @@ async def test_read_file_handler_workspace_uri_no_session():
@pytest.mark.asyncio
async def test_read_file_handler_access_denied():
"""_read_file_handler rejects paths outside allowed locations."""
- with patch("backend.copilot.context._current_sdk_cwd") as mock_cwd, patch(
- "backend.copilot.context._current_sandbox"
- ) as mock_sandbox, patch(
- "backend.copilot.sdk.tool_adapter.get_execution_context",
- return_value=("user-1", _make_session()),
+ with (
+ patch("backend.copilot.context._current_sdk_cwd") as mock_cwd,
+ patch("backend.copilot.context._current_sandbox") as mock_sandbox,
+ patch(
+ "backend.copilot.sdk.tool_adapter.get_execution_context",
+ return_value=("user-1", _make_session()),
+ ),
):
mock_cwd.get.return_value = "/tmp/safe-dir"
mock_sandbox.get.return_value = None
@@ -490,11 +498,11 @@ async def test_read_file_bytes_e2b_sandbox_branch():
mock_sandbox = AsyncMock()
mock_sandbox.files.read.return_value = bytearray(b"sandbox content")
- with patch("backend.copilot.context._current_sdk_cwd") as mock_cwd, patch(
- "backend.copilot.context._current_sandbox"
- ) as mock_sandbox_var, patch(
- "backend.copilot.context._current_project_dir"
- ) as mock_proj:
+ with (
+ patch("backend.copilot.context._current_sdk_cwd") as mock_cwd,
+ patch("backend.copilot.context._current_sandbox") as mock_sandbox_var,
+ patch("backend.copilot.context._current_project_dir") as mock_proj,
+ ):
mock_cwd.get.return_value = ""
mock_sandbox_var.get.return_value = mock_sandbox
mock_proj.get.return_value = ""
@@ -513,11 +521,11 @@ async def test_read_file_bytes_e2b_path_escapes_sandbox_raises():
session = _make_session()
mock_sandbox = AsyncMock()
- with patch("backend.copilot.context._current_sdk_cwd") as mock_cwd, patch(
- "backend.copilot.context._current_sandbox"
- ) as mock_sandbox_var, patch(
- "backend.copilot.context._current_project_dir"
- ) as mock_proj:
+ with (
+ patch("backend.copilot.context._current_sdk_cwd") as mock_cwd,
+ patch("backend.copilot.context._current_sandbox") as mock_sandbox_var,
+ patch("backend.copilot.context._current_project_dir") as mock_proj,
+ ):
mock_cwd.get.return_value = ""
mock_sandbox_var.get.return_value = mock_sandbox
mock_proj.get.return_value = ""
diff --git a/autogpt_platform/backend/backend/copilot/sdk/file_ref_test.py b/autogpt_platform/backend/backend/copilot/sdk/file_ref_test.py
index 8ace09b9b8..03b0701cce 100644
--- a/autogpt_platform/backend/backend/copilot/sdk/file_ref_test.py
+++ b/autogpt_platform/backend/backend/copilot/sdk/file_ref_test.py
@@ -1394,11 +1394,7 @@ async def test_e2e_toml_dict_with_list_value_to_concat_block():
"""TOML dict with a list value → List[List[Any]] block: extracts list
values, ignoring scalar values like 'title'."""
toml_content = (
- 'title = "Fruits"\n'
- "[[fruits]]\n"
- 'name = "apple"\n'
- "[[fruits]]\n"
- 'name = "banana"\n'
+ 'title = "Fruits"\n[[fruits]]\nname = "apple"\n[[fruits]]\nname = "banana"\n'
)
async def _resolve(ref, *a, **kw): # noqa: ARG001
@@ -1692,12 +1688,15 @@ async def test_media_file_field_passthrough_workspace_uri():
},
}
- with patch(
- "backend.copilot.sdk.file_ref.resolve_file_ref",
- new=AsyncMock(side_effect=AssertionError("should not read file content")),
- ), patch(
- "backend.copilot.sdk.file_ref.read_file_bytes",
- new=AsyncMock(side_effect=AssertionError("should not read file bytes")),
+ with (
+ patch(
+ "backend.copilot.sdk.file_ref.resolve_file_ref",
+ new=AsyncMock(side_effect=AssertionError("should not read file content")),
+ ),
+ patch(
+ "backend.copilot.sdk.file_ref.read_file_bytes",
+ new=AsyncMock(side_effect=AssertionError("should not read file bytes")),
+ ),
):
result = await expand_file_refs_in_args(
{"image": "@@agptfile:workspace://img123"},
diff --git a/autogpt_platform/backend/backend/copilot/sdk/response_adapter.py b/autogpt_platform/backend/backend/copilot/sdk/response_adapter.py
index 3c80081ebe..e43524197a 100644
--- a/autogpt_platform/backend/backend/copilot/sdk/response_adapter.py
+++ b/autogpt_platform/backend/backend/copilot/sdk/response_adapter.py
@@ -305,7 +305,7 @@ class SDKResponseAdapter:
self.resolved_tool_calls.add(tool_id)
flushed = True
logger.info(
- "[SDK] [%s] Flushed stashed output for %s " "(call %s, %d chars)",
+ "[SDK] [%s] Flushed stashed output for %s (call %s, %d chars)",
sid,
tool_name,
tool_id[:12],
diff --git a/autogpt_platform/backend/backend/copilot/sdk/service.py b/autogpt_platform/backend/backend/copilot/sdk/service.py
index 9cef40ba7a..a670249f72 100644
--- a/autogpt_platform/backend/backend/copilot/sdk/service.py
+++ b/autogpt_platform/backend/backend/copilot/sdk/service.py
@@ -49,6 +49,7 @@ from ..constants import (
COPILOT_RETRYABLE_ERROR_PREFIX,
COPILOT_SYSTEM_PREFIX,
FRIENDLY_TRANSIENT_MSG,
+ STREAM_IDLE_TIMEOUT_SECONDS,
is_transient_api_error,
)
from ..context import encode_cwd_for_cli, get_workspace_manager
@@ -162,9 +163,13 @@ _CIRCUIT_BREAKER_ERROR_MSG = (
)
# Idle timeout: abort the stream if no meaningful SDK message (only heartbeats)
-# arrives for this many seconds. This catches hung tool calls (e.g. WebSearch
-# hanging on a search provider that never responds).
-_IDLE_TIMEOUT_SECONDS = 10 * 60 # 10 minutes
+# arrives for this many seconds. Derived from MAX_TOOL_WAIT_SECONDS so the
+# invariant "no single tool blocks close to this long" holds by construction —
+# long-running tools use the async "start + poll" pattern (initial tool returns
+# with a handle, polling tool waits in ≤MAX_TOOL_WAIT_SECONDS chunks), so an
+# idle of 2× that genuinely means the SDK itself is stuck.
+_IDLE_TIMEOUT_SECONDS = STREAM_IDLE_TIMEOUT_SECONDS
+
# Event types that are ephemeral / cosmetic and must NOT be counted toward
# ``events_yielded`` in the transient-retry loop. Counting them would prevent
@@ -1932,20 +1937,19 @@ async def _run_stream_attempt(
yield ev
yield StreamHeartbeat()
- # Idle timeout: if no real SDK message for too long, a tool
- # call is likely hung (e.g. WebSearch provider not responding).
+ # Idle timeout: abort if the SDK has been silent for too long.
+ # Long-running tools use the async "start + poll" pattern so
+ # the MCP handler never blocks longer than the poll cap (5 min)
+ # — a 10-min gap here means the SDK itself is stuck.
idle_seconds = time.monotonic() - _last_real_msg_time
if idle_seconds >= _IDLE_TIMEOUT_SECONDS:
logger.error(
- "%s Idle timeout after %.0fs with no SDK message — "
- "aborting stream (likely hung tool call)",
+ "%s Idle timeout after %.0fs — aborting stream",
ctx.log_prefix,
idle_seconds,
)
stream_error_msg = (
- "A tool call appears to be stuck "
- "(no response for 10 minutes). "
- "Please try again."
+ "The session has been idle for too long. Please try again."
)
stream_error_code = "idle_timeout"
_append_error_marker(ctx.session, stream_error_msg, retryable=True)
diff --git a/autogpt_platform/backend/backend/copilot/sdk/service_test.py b/autogpt_platform/backend/backend/copilot/sdk/service_test.py
index 7bade391d3..f7ebe766f6 100644
--- a/autogpt_platform/backend/backend/copilot/sdk/service_test.py
+++ b/autogpt_platform/backend/backend/copilot/sdk/service_test.py
@@ -11,6 +11,7 @@ import pytest
from backend.copilot import config as cfg_mod
from .service import (
+ _IDLE_TIMEOUT_SECONDS,
_build_system_prompt_value,
_is_sdk_disconnect_error,
_normalize_model_name,
@@ -719,3 +720,13 @@ class TestSystemPromptPreset:
use_claude_code_subscription=False,
)
assert cfg.claude_agent_cross_user_prompt_cache is False
+
+
+class TestIdleTimeoutConstant:
+ """SECRT-2247: long-running work now uses async start+poll pattern
+ (run_sub_session / run_agent), so no single MCP tool call ever blocks
+ the stream close to the idle limit. The plain 10-min cap from the
+ original code is restored."""
+
+ def test_idle_timeout_is_10_min(self):
+ assert _IDLE_TIMEOUT_SECONDS == 10 * 60
diff --git a/autogpt_platform/backend/backend/copilot/sdk/session_waiter.py b/autogpt_platform/backend/backend/copilot/sdk/session_waiter.py
new file mode 100644
index 0000000000..847d4d4970
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/sdk/session_waiter.py
@@ -0,0 +1,201 @@
+"""Cross-process helpers: dispatch + await a copilot session turn.
+
+The sub-AutoPilot tools (``run_sub_session``, ``get_sub_session_result``)
+and ``AutoPilotBlock`` all delegate a copilot turn to the
+``copilot_executor`` queue and then wait on the shared
+``stream_registry`` for the terminal event. This module is the
+centralised primitive so every caller agrees on the dispatch shape,
+the event aggregation, and the cleanup contract.
+
+Two wait modes:
+
+* :func:`wait_for_session_completion` — cheap "did it finish?" when the
+ caller only needs a ``SessionOutcome`` (``running`` / ``completed`` /
+ ``failed``). Used by ``get_sub_session_result`` when it only needs to
+ decide between returning the final ChatSession state or "still busy".
+* :func:`wait_for_session_result` — accumulates stream events into an
+ :class:`EventAccumulator` so the caller also gets back
+ ``response_text`` / ``tool_calls`` / token usage in memory, without
+ an extra DB round-trip. Used by the full-result callers
+ (``run_sub_session`` completed path, ``AutoPilotBlock.execute_copilot``).
+
+Plus :func:`run_copilot_turn_via_queue` — the one-shot "create session
+meta → enqueue → wait for result" sequence that every caller uses.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import uuid
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Literal
+
+from backend.copilot import stream_registry
+from backend.copilot.executor.utils import enqueue_copilot_turn
+from backend.copilot.response_model import StreamError, StreamFinish
+
+from .stream_accumulator import EventAccumulator, ToolCallEntry, process_event
+
+if TYPE_CHECKING:
+ from backend.copilot.permissions import CopilotPermissions
+
+logger = logging.getLogger(__name__)
+
+
+SessionOutcome = Literal["completed", "failed", "running"]
+
+
+@dataclass
+class SessionResult:
+ """Aggregated result from a copilot session turn observed via
+ ``stream_registry``. Mirrors :class:`collect.CopilotResult` so both
+ in-process and cross-process consumers get the same shape."""
+
+ response_text: str = ""
+ tool_calls: list[ToolCallEntry] = field(default_factory=list)
+ prompt_tokens: int = 0
+ completion_tokens: int = 0
+ total_tokens: int = 0
+ error_text: str | None = None
+
+
+async def wait_for_session_completion(
+ *,
+ session_id: str,
+ user_id: str | None,
+ timeout: float,
+) -> SessionOutcome:
+ """Return the outcome of the latest turn on *session_id* within *timeout*.
+
+ Light-weight variant of :func:`wait_for_session_result` — drops the
+ event aggregation so callers that only need to decide between "still
+ running" and "terminal" don't pay for building an accumulator.
+ """
+ outcome, _ = await _drain_until_terminal(
+ session_id=session_id,
+ user_id=user_id,
+ timeout=timeout,
+ accumulate=False,
+ )
+ return outcome
+
+
+async def wait_for_session_result(
+ *,
+ session_id: str,
+ user_id: str | None,
+ timeout: float,
+) -> tuple[SessionOutcome, SessionResult]:
+ """Drain the session's stream events, aggregate them into a result.
+
+ Returns whatever has been observed at the cap (``running`` + partial
+ result) or at the terminal event (``completed`` / ``failed`` + full
+ result). Cleans up the subscriber listener on every exit path so
+ long-running polls don't leak listeners (sentry r3105348640).
+ """
+ outcome, acc = await _drain_until_terminal(
+ session_id=session_id,
+ user_id=user_id,
+ timeout=timeout,
+ accumulate=True,
+ )
+ result = SessionResult()
+ if acc is not None:
+ result.response_text = "".join(acc.response_parts)
+ result.tool_calls = list(acc.tool_calls)
+ result.prompt_tokens = acc.prompt_tokens
+ result.completion_tokens = acc.completion_tokens
+ result.total_tokens = acc.total_tokens
+ return outcome, result
+
+
+async def _drain_until_terminal(
+ *,
+ session_id: str,
+ user_id: str | None,
+ timeout: float,
+ accumulate: bool,
+) -> tuple[SessionOutcome, EventAccumulator | None]:
+ """Shared drain loop used by both wait helpers."""
+ queue = await stream_registry.subscribe_to_session(
+ session_id=session_id,
+ user_id=user_id,
+ )
+ if queue is None:
+ # Session meta not in Redis yet, or the caller doesn't own it.
+ # ``subscribe_to_session`` already retried with backoff before
+ # returning None.
+ return "running", (EventAccumulator() if accumulate else None)
+
+ acc = EventAccumulator() if accumulate else None
+ try:
+ loop = asyncio.get_event_loop()
+ deadline = loop.time() + max(timeout, 0)
+ while True:
+ remaining = deadline - loop.time()
+ if remaining <= 0:
+ return "running", acc
+ event = await asyncio.wait_for(queue.get(), timeout=remaining)
+ if accumulate and acc is not None:
+ process_event(event, acc)
+ if isinstance(event, StreamFinish):
+ return "completed", acc
+ if isinstance(event, StreamError):
+ return "failed", acc
+ except asyncio.TimeoutError:
+ return "running", acc
+ finally:
+ await stream_registry.unsubscribe_from_session(
+ session_id=session_id,
+ subscriber_queue=queue,
+ )
+
+
+async def run_copilot_turn_via_queue(
+ *,
+ session_id: str,
+ user_id: str,
+ message: str,
+ timeout: float,
+ permissions: "CopilotPermissions | None" = None,
+ tool_call_id: str,
+ tool_name: str,
+) -> tuple[SessionOutcome, SessionResult]:
+ """Dispatch a copilot turn onto the queue and wait for its result.
+
+ The canonical invocation path shared by ``run_sub_session`` (the
+ copilot tool), ``AutoPilotBlock`` (the graph block), and any future
+ caller that needs to run a copilot turn without occupying its own
+ worker with the SDK stream:
+
+ 1. Create a ``stream_registry`` session meta record for the turn.
+ 2. Enqueue a ``CoPilotExecutionEntry`` on the copilot_execution
+ exchange. Any idle copilot_executor worker claims it.
+ 3. Subscribe to the session's Redis stream and drain events until
+ ``StreamFinish`` / ``StreamError`` or the cap fires.
+
+ ``tool_call_id`` / ``tool_name`` disambiguate who originated the
+ turn in observability / replay (e.g. ``"sub:<parent>"`` for a
+ sub-session, ``"autopilot_block"`` for an AutoPilotBlock run).
+ """
+ turn_id = str(uuid.uuid4())
+ 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,
+ message=message,
+ turn_id=turn_id,
+ permissions=permissions,
+ )
+ return await wait_for_session_result(
+ session_id=session_id,
+ user_id=user_id,
+ timeout=timeout,
+ )
diff --git a/autogpt_platform/backend/backend/copilot/sdk/stream_accumulator.py b/autogpt_platform/backend/backend/copilot/sdk/stream_accumulator.py
new file mode 100644
index 0000000000..a61e0827e0
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/sdk/stream_accumulator.py
@@ -0,0 +1,88 @@
+"""Stream event → aggregated result accumulator.
+
+Consumes the same ``StreamBaseResponse`` events that fly over
+``stream_registry`` (text deltas, tool i/o, usage, errors) and folds
+them into a single :class:`EventAccumulator` state. Two consumers:
+
+* :func:`collect.collect_copilot_response` — drives the SDK stream
+ directly on the worker that's running the turn.
+* :func:`session_waiter.wait_for_session_result` — reads the same
+ events from a Redis Stream subscription, so a different process can
+ obtain the same aggregated result for a session it didn't run.
+
+Keeping the dispatch in one place means both entry points agree on
+what "response_text", "tool_calls", and token counts mean without
+drifting apart as new event types are added.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from ..response_model import (
+ StreamError,
+ StreamTextDelta,
+ StreamToolInputAvailable,
+ StreamToolOutputAvailable,
+ StreamUsage,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class ToolCallEntry(BaseModel):
+ """A single tool call observed during stream consumption."""
+
+ tool_call_id: str
+ tool_name: str
+ input: Any
+ output: Any = None
+ success: bool | None = None
+
+
+class EventAccumulator(BaseModel):
+ """Mutable accumulator fed by :func:`process_event`."""
+
+ response_parts: list[str] = Field(default_factory=list)
+ tool_calls: list[ToolCallEntry] = Field(default_factory=list)
+ tool_calls_by_id: dict[str, ToolCallEntry] = Field(default_factory=dict)
+ prompt_tokens: int = 0
+ completion_tokens: int = 0
+ total_tokens: int = 0
+
+
+def process_event(event: object, acc: EventAccumulator) -> str | None:
+ """Fold *event* into *acc*. Returns the error text on ``StreamError``.
+
+ Uses structural pattern matching for dispatch per project guidelines.
+ """
+ match event:
+ case StreamTextDelta(delta=delta):
+ acc.response_parts.append(delta)
+ case StreamToolInputAvailable() as e:
+ entry = ToolCallEntry(
+ tool_call_id=e.toolCallId,
+ tool_name=e.toolName,
+ input=e.input,
+ )
+ acc.tool_calls.append(entry)
+ acc.tool_calls_by_id[e.toolCallId] = entry
+ case StreamToolOutputAvailable() as e:
+ if tc := acc.tool_calls_by_id.get(e.toolCallId):
+ tc.output = e.output
+ tc.success = e.success
+ else:
+ logger.debug(
+ "Received tool output for unknown tool_call_id: %s",
+ e.toolCallId,
+ )
+ case StreamUsage() as e:
+ acc.prompt_tokens += e.prompt_tokens
+ acc.completion_tokens += e.completion_tokens
+ acc.total_tokens += e.total_tokens
+ case StreamError(errorText=err):
+ return err
+ return None
diff --git a/autogpt_platform/backend/backend/copilot/sdk/tool_adapter.py b/autogpt_platform/backend/backend/copilot/sdk/tool_adapter.py
index 2a64c84d64..5b2a80fb5b 100644
--- a/autogpt_platform/backend/backend/copilot/sdk/tool_adapter.py
+++ b/autogpt_platform/backend/backend/copilot/sdk/tool_adapter.py
@@ -248,7 +248,14 @@ async def _execute_tool_sync(
session: ChatSession,
args: dict[str, Any],
) -> dict[str, Any]:
- """Execute a tool synchronously and return MCP-formatted response."""
+ """Execute a tool inline and return an MCP-formatted response.
+
+ The call runs to completion — no per-handler timeout, no parking. The
+ stream-level idle timer in ``_run_stream_attempt`` pauses while a tool
+ is pending, so a long sub-AutoPilot / graph execution doesn't trip the
+ 30-min idle safety net (SECRT-2247). A genuine hang is handled by the
+ broader session lifecycle (user closes the tab / cancel endpoint).
+ """
effective_id = f"sdk-{uuid.uuid4().hex[:12]}"
result = await base_tool.execute(
user_id=user_id,
diff --git a/autogpt_platform/backend/backend/copilot/sdk/tool_adapter_test.py b/autogpt_platform/backend/backend/copilot/sdk/tool_adapter_test.py
index 6629363c2f..a9a9671b9f 100644
--- a/autogpt_platform/backend/backend/copilot/sdk/tool_adapter_test.py
+++ b/autogpt_platform/backend/backend/copilot/sdk/tool_adapter_test.py
@@ -251,7 +251,10 @@ class TestTruncationAndStashIntegration:
# ---------------------------------------------------------------------------
-def _make_mock_tool(name: str, output: str = "result") -> MagicMock:
+def _make_mock_tool(
+ name: str,
+ output: str = "result",
+) -> MagicMock:
"""Return a BaseTool mock that returns a successful StreamToolOutputAvailable."""
tool = MagicMock()
tool.name = name
@@ -336,6 +339,38 @@ class TestCreateToolHandler:
assert mock_tool.execute.await_count == 2
+class TestToolInlineExecution:
+ """Tools run inline to completion — no per-handler timeout, no parking."""
+
+ @pytest.fixture(autouse=True)
+ def _init(self):
+ _init_ctx(session=_make_mock_session())
+
+ @pytest.mark.asyncio
+ async def test_tool_runs_to_completion_regardless_of_duration(self):
+ """A tool that takes a while still runs inline; the handler does not
+ park, cancel, or wrap it in a timeout. The stream-level idle timer
+ (in _run_stream_attempt) is what pauses while tool calls are pending."""
+
+ async def slow_but_completes(*_args, **_kwargs):
+ await asyncio.sleep(0.1)
+ return StreamToolOutputAvailable(
+ toolCallId="t1",
+ output="final-result",
+ toolName="slow_tool",
+ success=True,
+ )
+
+ mock_tool = _make_mock_tool("slow_tool")
+ mock_tool.execute = AsyncMock(side_effect=slow_but_completes)
+
+ handler = create_tool_handler(mock_tool)
+ result = await handler({})
+
+ assert result["isError"] is False
+ assert "final-result" in result["content"][0]["text"]
+
+
# ---------------------------------------------------------------------------
# Regression tests: bugs fixed by removing pre-launch mechanism
#
@@ -873,7 +908,9 @@ class TestStripLlmFields:
"""
dry_run_session = MagicMock()
dry_run_session.dry_run = True
- set_execution_context(user_id="test", session=dry_run_session, sandbox=None, sdk_cwd="/tmp/test") # type: ignore[arg-type]
+ set_execution_context(
+ user_id="test", session=dry_run_session, sandbox=None, sdk_cwd="/tmp/test"
+ ) # type: ignore[arg-type]
full_payload = '{"message": "done", "is_dry_run": true}'
@@ -906,7 +943,9 @@ class TestStripLlmFields:
"""
normal_session = MagicMock()
normal_session.dry_run = False
- set_execution_context(user_id="test", session=normal_session, sandbox=None, sdk_cwd="/tmp/test") # type: ignore[arg-type]
+ set_execution_context(
+ user_id="test", session=normal_session, sandbox=None, sdk_cwd="/tmp/test"
+ ) # type: ignore[arg-type]
full_payload = '{"message": "simulated", "is_dry_run": true}'
diff --git a/autogpt_platform/backend/backend/copilot/tools/__init__.py b/autogpt_platform/backend/backend/copilot/tools/__init__.py
index 75a0a8f4e4..9ba050b79a 100644
--- a/autogpt_platform/backend/backend/copilot/tools/__init__.py
+++ b/autogpt_platform/backend/backend/copilot/tools/__init__.py
@@ -26,6 +26,7 @@ from .fix_agent import FixAgentGraphTool
from .get_agent_building_guide import GetAgentBuildingGuideTool
from .get_doc_page import GetDocPageTool
from .get_mcp_guide import GetMCPGuideTool
+from .get_sub_session_result import GetSubSessionResultTool
from .graphiti_forget import MemoryForgetConfirmTool, MemoryForgetSearchTool
from .graphiti_search import MemorySearchTool
from .graphiti_store import MemoryStoreTool
@@ -40,6 +41,7 @@ from .manage_folders import (
from .run_agent import RunAgentTool
from .run_block import RunBlockTool
from .run_mcp_tool import RunMCPToolTool
+from .run_sub_session import RunSubSessionTool
from .search_docs import SearchDocsTool
from .validate_agent import ValidateAgentGraphTool
from .web_fetch import WebFetchTool
@@ -81,6 +83,8 @@ TOOL_REGISTRY: dict[str, BaseTool] = {
"run_agent": RunAgentTool(),
"run_block": RunBlockTool(),
"continue_run_block": ContinueRunBlockTool(),
+ "run_sub_session": RunSubSessionTool(),
+ "get_sub_session_result": GetSubSessionResultTool(),
"run_mcp_tool": RunMCPToolTool(),
"get_mcp_guide": GetMCPGuideTool(),
"view_agent_output": AgentOutputTool(),
diff --git a/autogpt_platform/backend/backend/copilot/tools/_test_data.py b/autogpt_platform/backend/backend/copilot/tools/_test_data.py
index cff4e23416..f94666bfef 100644
--- a/autogpt_platform/backend/backend/copilot/tools/_test_data.py
+++ b/autogpt_platform/backend/backend/copilot/tools/_test_data.py
@@ -12,7 +12,7 @@ from backend.api.features.store import db as store_db
from backend.blocks.firecrawl.scrape import FirecrawlScrapeBlock
from backend.blocks.io import AgentInputBlock, AgentOutputBlock
from backend.blocks.llm import AITextGeneratorBlock
-from backend.copilot.model import ChatSession
+from backend.copilot.model import ChatMessage, ChatSession
from backend.data import db as db_module
from backend.data.db import prisma
from backend.data.graph import Graph, Link, Node, create_graph
@@ -42,11 +42,28 @@ async def _ensure_db_connected() -> None:
await db_module.connect()
-def make_session(user_id: str):
+def make_session(user_id: str, *, guide_read: bool = True):
+ """Build a fake ChatSession for tool tests.
+
+ ``guide_read=True`` (default) pre-populates the session with a
+ ``get_agent_building_guide`` tool-call history entry so the agent-
+ generation gate (see ``helpers.require_guide_read``) lets through any
+ subsequent ``create_agent`` / ``edit_agent`` / ``validate_agent_graph``
+ / ``fix_agent_graph`` call.
+ """
+ messages: list[ChatMessage] = []
+ if guide_read:
+ messages.append(
+ ChatMessage(
+ role="assistant",
+ content="",
+ tool_calls=[{"function": {"name": "get_agent_building_guide"}}],
+ )
+ )
return ChatSession(
session_id=str(uuid.uuid4()),
user_id=user_id,
- messages=[],
+ messages=messages,
usage=[],
started_at=datetime.now(UTC),
updated_at=datetime.now(UTC),
diff --git a/autogpt_platform/backend/backend/copilot/tools/agent_generator/fixer.py b/autogpt_platform/backend/backend/copilot/tools/agent_generator/fixer.py
index adebd89bf1..d84a426720 100644
--- a/autogpt_platform/backend/backend/copilot/tools/agent_generator/fixer.py
+++ b/autogpt_platform/backend/backend/copilot/tools/agent_generator/fixer.py
@@ -1325,7 +1325,7 @@ class AgentFixer:
"""
if not library_agents:
logger.debug(
- "fix_agent_executor_blocks: No library_agents provided, " "skipping"
+ "fix_agent_executor_blocks: No library_agents provided, skipping"
)
return agent
@@ -1390,7 +1390,7 @@ class AgentFixer:
if "user_id" not in input_default:
input_default["user_id"] = ""
self.add_fix_log(
- f"Fixed AgentExecutorBlock {node_id}: Added missing " f"user_id"
+ f"Fixed AgentExecutorBlock {node_id}: Added missing user_id"
)
# Ensure inputs is present
@@ -1689,8 +1689,7 @@ class AgentFixer:
if field not in input_default or input_default[field] is None:
input_default[field] = default_value
self.add_fix_log(
- f"OrchestratorBlock {node_id}: "
- f"Set {field}={default_value!r}"
+ f"OrchestratorBlock {node_id}: Set {field}={default_value!r}"
)
return agent
diff --git a/autogpt_platform/backend/backend/copilot/tools/agent_guide_gate_test.py b/autogpt_platform/backend/backend/copilot/tools/agent_guide_gate_test.py
new file mode 100644
index 0000000000..6a122b7324
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/tools/agent_guide_gate_test.py
@@ -0,0 +1,119 @@
+"""Tests for the ``require_guide_read`` gate on agent-generation tools.
+
+The agent-building guide carries block ids, link semantics, and
+AgentExecutorBlock / MCPToolBlock conventions that the agent needs before
+producing agent JSON. Without the gate, agents often skip the guide to save
+tokens and then produce JSON that fails validation — wasting turns on
+auto-fix loops.
+"""
+
+from unittest.mock import MagicMock
+
+import pytest
+
+from backend.copilot.model import ChatMessage, ChatSession
+
+from .helpers import require_guide_read
+from .models import ErrorResponse
+
+
+def _session_with_messages(messages: list[ChatMessage]) -> ChatSession:
+ """Build a minimal ChatSession whose ``messages`` matches *messages*."""
+ session = MagicMock(spec=ChatSession)
+ session.session_id = "test-session"
+ session.messages = messages
+ return session
+
+
+def test_no_messages_gate_fires():
+ session = _session_with_messages([])
+ result = require_guide_read(session, "create_agent")
+ assert isinstance(result, ErrorResponse)
+ assert "get_agent_building_guide" in result.message
+ assert "create_agent" in result.message
+
+
+def test_user_message_only_gate_fires():
+ session = _session_with_messages(
+ [ChatMessage(role="user", content="build an agent")]
+ )
+ assert isinstance(require_guide_read(session, "create_agent"), ErrorResponse)
+
+
+def test_assistant_without_tool_calls_gate_fires():
+ session = _session_with_messages(
+ [ChatMessage(role="assistant", content="sure!", tool_calls=None)]
+ )
+ assert isinstance(require_guide_read(session, "create_agent"), ErrorResponse)
+
+
+def test_unrelated_tool_call_gate_fires():
+ session = _session_with_messages(
+ [
+ ChatMessage(
+ role="assistant",
+ content="",
+ tool_calls=[{"function": {"name": "find_block"}}],
+ )
+ ]
+ )
+ assert isinstance(require_guide_read(session, "create_agent"), ErrorResponse)
+
+
+def test_guide_called_via_openai_shape_gate_passes():
+ """OpenAI/Anthropic wrap names under 'function': {'name': ...}."""
+ session = _session_with_messages(
+ [
+ ChatMessage(
+ role="assistant",
+ content="",
+ tool_calls=[
+ {"function": {"name": "get_agent_building_guide"}},
+ ],
+ )
+ ]
+ )
+ assert require_guide_read(session, "create_agent") is None
+
+
+def test_guide_called_via_flat_shape_gate_passes():
+ """Some callers log tool calls with a flat {'name': ...} shape."""
+ session = _session_with_messages(
+ [
+ ChatMessage(
+ role="assistant",
+ content="",
+ tool_calls=[{"name": "get_agent_building_guide"}],
+ )
+ ]
+ )
+ assert require_guide_read(session, "create_agent") is None
+
+
+def test_guide_earlier_in_history_still_passes():
+ """A guide call earlier in the session keeps the gate open for subsequent
+ create/edit/validate/fix calls — the agent doesn't need to re-read it."""
+ session = _session_with_messages(
+ [
+ ChatMessage(role="user", content="build X"),
+ ChatMessage(
+ role="assistant",
+ content="",
+ tool_calls=[{"function": {"name": "get_agent_building_guide"}}],
+ ),
+ ChatMessage(role="user", content="also Y"),
+ ChatMessage(role="assistant", content="working on it"),
+ ]
+ )
+ assert require_guide_read(session, "edit_agent") is None
+
+
+ "tool_name",
+ ["create_agent", "edit_agent", "validate_agent_graph", "fix_agent_graph"],
+)
+def test_tool_name_surfaced_in_error(tool_name: str):
+ session = _session_with_messages([])
+ result = require_guide_read(session, tool_name)
+ assert isinstance(result, ErrorResponse)
+ assert tool_name in result.message
diff --git a/autogpt_platform/backend/backend/copilot/tools/agent_output.py b/autogpt_platform/backend/backend/copilot/tools/agent_output.py
index f0aedb9fb3..21c62bd9ce 100644
--- a/autogpt_platform/backend/backend/copilot/tools/agent_output.py
+++ b/autogpt_platform/backend/backend/copilot/tools/agent_output.py
@@ -8,6 +8,7 @@ from typing import Any
from pydantic import BaseModel, Field, field_validator
from backend.api.features.library.model import LibraryAgent
+from backend.copilot.constants import MAX_TOOL_WAIT_SECONDS
from backend.copilot.model import ChatSession
from backend.data.db_accessors import execution_db, library_db
from backend.data.execution import (
@@ -39,7 +40,7 @@ class AgentOutputInput(BaseModel):
store_slug: str = ""
execution_id: str = ""
run_time: str = "latest"
- wait_if_running: int = Field(default=0, ge=0, le=300)
+ wait_if_running: int = Field(default=0, ge=0, le=MAX_TOOL_WAIT_SECONDS)
show_execution_details: bool = False
@field_validator(
@@ -148,9 +149,13 @@ class AgentOutputTool(BaseTool):
},
"wait_if_running": {
"type": "integer",
- "description": "Max seconds to wait if still running (0-300). Returns current state on timeout.",
+ "description": (
+ "Max seconds to wait if still running "
+ f"(0-{MAX_TOOL_WAIT_SECONDS}). "
+ "Returns current state on timeout."
+ ),
"minimum": 0,
- "maximum": 300,
+ "maximum": MAX_TOOL_WAIT_SECONDS,
},
"show_execution_details": {
"type": "boolean",
diff --git a/autogpt_platform/backend/backend/copilot/tools/bash_exec_test.py b/autogpt_platform/backend/backend/copilot/tools/bash_exec_test.py
index 714b8196ed..47b0570960 100644
--- a/autogpt_platform/backend/backend/copilot/tools/bash_exec_test.py
+++ b/autogpt_platform/backend/backend/copilot/tools/bash_exec_test.py
@@ -35,12 +35,15 @@ class TestBashExecE2BTokenInjection:
sandbox = _make_sandbox(stdout="ok")
env_vars = {"GH_TOKEN": "gh-secret", "GITHUB_TOKEN": "gh-secret"}
- with patch(
- "backend.copilot.tools.bash_exec.get_integration_env_vars",
- new=AsyncMock(return_value=env_vars),
- ) as mock_get_env, patch(
- "backend.copilot.tools.bash_exec.get_github_user_git_identity",
- new=AsyncMock(return_value=None),
+ with (
+ patch(
+ "backend.copilot.tools.bash_exec.get_integration_env_vars",
+ new=AsyncMock(return_value=env_vars),
+ ) as mock_get_env,
+ patch(
+ "backend.copilot.tools.bash_exec.get_github_user_git_identity",
+ new=AsyncMock(return_value=None),
+ ),
):
result = await tool._execute_on_e2b(
sandbox=sandbox,
@@ -69,12 +72,15 @@ class TestBashExecE2BTokenInjection:
"GIT_COMMITTER_EMAIL": "[email protected]",
}
- with patch(
- "backend.copilot.tools.bash_exec.get_integration_env_vars",
- new=AsyncMock(return_value={}),
- ), patch(
- "backend.copilot.tools.bash_exec.get_github_user_git_identity",
- new=AsyncMock(return_value=identity),
+ with (
+ patch(
+ "backend.copilot.tools.bash_exec.get_integration_env_vars",
+ new=AsyncMock(return_value={}),
+ ),
+ patch(
+ "backend.copilot.tools.bash_exec.get_github_user_git_identity",
+ new=AsyncMock(return_value=identity),
+ ),
):
await tool._execute_on_e2b(
sandbox=sandbox,
@@ -97,12 +103,15 @@ class TestBashExecE2BTokenInjection:
session = make_session(user_id=_USER)
sandbox = _make_sandbox(stdout="ok")
- with patch(
- "backend.copilot.tools.bash_exec.get_integration_env_vars",
- new=AsyncMock(return_value={}),
- ), patch(
- "backend.copilot.tools.bash_exec.get_github_user_git_identity",
- new=AsyncMock(return_value=None),
+ with (
+ patch(
+ "backend.copilot.tools.bash_exec.get_integration_env_vars",
+ new=AsyncMock(return_value={}),
+ ),
+ patch(
+ "backend.copilot.tools.bash_exec.get_github_user_git_identity",
+ new=AsyncMock(return_value=None),
+ ),
):
await tool._execute_on_e2b(
sandbox=sandbox,
@@ -123,13 +132,16 @@ class TestBashExecE2BTokenInjection:
session = make_session(user_id=_USER)
sandbox = _make_sandbox(stdout="ok")
- with patch(
- "backend.copilot.tools.bash_exec.get_integration_env_vars",
- new=AsyncMock(return_value={"GH_TOKEN": "should-not-appear"}),
- ) as mock_get_env, patch(
- "backend.copilot.tools.bash_exec.get_github_user_git_identity",
- new=AsyncMock(return_value=None),
- ) as mock_get_identity:
+ with (
+ patch(
+ "backend.copilot.tools.bash_exec.get_integration_env_vars",
+ new=AsyncMock(return_value={"GH_TOKEN": "should-not-appear"}),
+ ) as mock_get_env,
+ patch(
+ "backend.copilot.tools.bash_exec.get_github_user_git_identity",
+ new=AsyncMock(return_value=None),
+ ) as mock_get_identity,
+ ):
result = await tool._execute_on_e2b(
sandbox=sandbox,
command="echo hi",
diff --git a/autogpt_platform/backend/backend/copilot/tools/create_agent.py b/autogpt_platform/backend/backend/copilot/tools/create_agent.py
index 7710cbafca..a27392fc8e 100644
--- a/autogpt_platform/backend/backend/copilot/tools/create_agent.py
+++ b/autogpt_platform/backend/backend/copilot/tools/create_agent.py
@@ -8,6 +8,7 @@ from backend.copilot.model import ChatSession
from .agent_generator.pipeline import fetch_library_agents, fix_validate_and_save
from .base import BaseTool
+from .helpers import require_guide_read
from .models import ErrorResponse, ToolResponseBase
logger = logging.getLogger(__name__)
@@ -23,8 +24,9 @@ class CreateAgentTool(BaseTool):
@property
def description(self) -> str:
return (
- "Create a new agent from JSON (nodes + links). Validates, auto-fixes, and saves. "
- "If you haven't already, call get_agent_building_guide first."
+ "Create a new agent from JSON (nodes + links). Validates, "
+ "auto-fixes, and saves. "
+ "Requires get_agent_building_guide first (refuses otherwise)."
)
@property
@@ -70,6 +72,10 @@ class CreateAgentTool(BaseTool):
) -> ToolResponseBase:
session_id = session.session_id if session else None
+ guide_gate = require_guide_read(session, "create_agent")
+ if guide_gate is not None:
+ return guide_gate
+
if not agent_json:
return ErrorResponse(
message=(
diff --git a/autogpt_platform/backend/backend/copilot/tools/edit_agent.py b/autogpt_platform/backend/backend/copilot/tools/edit_agent.py
index 0282070453..086896cc79 100644
--- a/autogpt_platform/backend/backend/copilot/tools/edit_agent.py
+++ b/autogpt_platform/backend/backend/copilot/tools/edit_agent.py
@@ -8,6 +8,7 @@ from backend.copilot.model import ChatSession
from .agent_generator import get_agent_as_json
from .agent_generator.pipeline import fetch_library_agents, fix_validate_and_save
from .base import BaseTool
+from .helpers import require_guide_read
from .models import ErrorResponse, ToolResponseBase
logger = logging.getLogger(__name__)
@@ -24,7 +25,7 @@ class EditAgentTool(BaseTool):
def description(self) -> str:
return (
"Edit an existing agent. Validates, auto-fixes, and saves. "
- "If you haven't already, call get_agent_building_guide first."
+ "Requires get_agent_building_guide first (refuses otherwise)."
)
@property
@@ -73,6 +74,10 @@ class EditAgentTool(BaseTool):
library_agent_ids = []
session_id = session.session_id if session else None
+ guide_gate = require_guide_read(session, "edit_agent")
+ if guide_gate is not None:
+ return guide_gate
+
if not agent_id:
return ErrorResponse(
message="Please provide the agent ID to edit.",
diff --git a/autogpt_platform/backend/backend/copilot/tools/find_block.py b/autogpt_platform/backend/backend/copilot/tools/find_block.py
index 130e26562b..aab54daac3 100644
--- a/autogpt_platform/backend/backend/copilot/tools/find_block.py
+++ b/autogpt_platform/backend/backend/copilot/tools/find_block.py
@@ -42,6 +42,10 @@ COPILOT_EXCLUDED_BLOCK_IDS = {
# OrchestratorBlock - dynamically discovers downstream blocks via graph topology;
# usable in agent graphs (guide hardcodes its ID) but cannot run standalone.
"3b191d9f-356f-482d-8238-ba04b6d18381",
+ # AutoPilotBlock - has dedicated run_sub_session tool with async start +
+ # poll lifecycle. Calling it via run_block would block the parent stream
+ # for the sub-AutoPilot's entire runtime (15-45+ min typical).
+ "c069dc6b-c3ed-4c12-b6e5-d47361e64ce6",
}
diff --git a/autogpt_platform/backend/backend/copilot/tools/fix_agent.py b/autogpt_platform/backend/backend/copilot/tools/fix_agent.py
index 81f36e8a7d..bc2ed1c3a9 100644
--- a/autogpt_platform/backend/backend/copilot/tools/fix_agent.py
+++ b/autogpt_platform/backend/backend/copilot/tools/fix_agent.py
@@ -7,6 +7,7 @@ from backend.copilot.model import ChatSession
from .agent_generator.validation import AgentFixer, AgentValidator, get_blocks_as_dicts
from .base import BaseTool
+from .helpers import require_guide_read
from .models import ErrorResponse, FixResultResponse, ToolResponseBase
logger = logging.getLogger(__name__)
@@ -25,7 +26,8 @@ class FixAgentGraphTool(BaseTool):
"Auto-fix common agent JSON issues: missing/invalid UUIDs, StoreValueBlock prerequisites, "
"double curly brace escaping, AddToList/AddToDictionary prerequisites, credentials, "
"node spacing, AI model defaults, link static properties, and type mismatches. "
- "Returns fixed JSON and list of fixes applied."
+ "Returns fixed JSON and list of fixes applied. "
+ "Requires get_agent_building_guide first (refuses otherwise)."
)
@property
@@ -56,6 +58,10 @@ class FixAgentGraphTool(BaseTool):
) -> ToolResponseBase:
session_id = session.session_id if session else None
+ guide_gate = require_guide_read(session, "fix_agent_graph")
+ if guide_gate is not None:
+ return guide_gate
+
if not agent_json or not isinstance(agent_json, dict):
return ErrorResponse(
message="Please provide a valid agent JSON object.",
diff --git a/autogpt_platform/backend/backend/copilot/tools/get_agent_building_guide.py b/autogpt_platform/backend/backend/copilot/tools/get_agent_building_guide.py
index 0db8e0453c..c11dff2d7d 100644
--- a/autogpt_platform/backend/backend/copilot/tools/get_agent_building_guide.py
+++ b/autogpt_platform/backend/backend/copilot/tools/get_agent_building_guide.py
@@ -43,8 +43,10 @@ class GetAgentBuildingGuideTool(BaseTool):
@property
def description(self) -> str:
return (
- "Get the agent JSON building guide (nodes, links, AgentExecutorBlock, MCPToolBlock usage, "
- "and the create->dry-run->fix iterative workflow). Call before generating agent JSON."
+ "Agent JSON building guide (nodes, links, AgentExecutorBlock, "
+ "MCPToolBlock, iterative create->dry-run->fix flow). REQUIRED "
+ "before create_agent / edit_agent / validate_agent_graph / "
+ "fix_agent_graph — they refuse until called once per session."
)
@property
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.py
new file mode 100644
index 0000000000..1b85c4f22f
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/tools/get_sub_session_result.py
@@ -0,0 +1,305 @@
+"""Poll / wait on / cancel a sub-AutoPilot started by ``run_sub_session``.
+
+Companion to :mod:`run_sub_session`. Operates on the sub's
+``ChatSession`` directly — there is no separate registry. Ownership is
+re-verified on every call by loading the ChatSession and comparing its
+``user_id`` against the authenticated caller.
+
+* **Wait** — subscribe to ``stream_registry`` for the session and drain
+ until ``StreamFinish`` / ``StreamError`` (terminal) or the per-call
+ cap fires. On terminal, the aggregated :class:`SessionResult` comes
+ back in memory — no DB round-trip for the response content.
+* **Just check** — ``wait_if_running=0`` skips the subscription. If the
+ sub's last assistant message already looks terminal, returns
+ ``completed`` with that content.
+* **Cancel** — fan out a ``CancelCoPilotEvent`` on the shared cancel
+ exchange. Whichever worker is running the sub breaks out of its
+ stream and finalises the session as ``failed``.
+"""
+
+import json
+import logging
+import time
+from typing import Any
+
+from backend.copilot import stream_registry
+from backend.copilot.executor.utils import enqueue_cancel_task
+from backend.copilot.model import ChatSession, get_chat_session
+from backend.copilot.sdk.session_waiter import (
+ SessionOutcome,
+ SessionResult,
+ wait_for_session_result,
+)
+from backend.copilot.sdk.stream_accumulator import ToolCallEntry
+
+from .base import BaseTool
+from .models import (
+ ErrorResponse,
+ SubSessionProgressSnapshot,
+ SubSessionStatusResponse,
+ ToolResponseBase,
+)
+from .run_sub_session import (
+ MAX_SUB_SESSION_WAIT_SECONDS,
+ _sub_session_link,
+ response_from_outcome,
+)
+
+logger = logging.getLogger(__name__)
+
+# Cap on how many recent messages we echo back in a progress snapshot.
+_PROGRESS_MESSAGE_LIMIT = 5
+_PROGRESS_CONTENT_PREVIEW_CHARS = 400
+
+
+class GetSubSessionResultTool(BaseTool):
+ """Wait for, inspect, or cancel a sub-AutoPilot."""
+
+ @property
+ def name(self) -> str:
+ return "get_sub_session_result"
+
+ @property
+ def requires_auth(self) -> bool:
+ return True
+
+ @property
+ def description(self) -> str:
+ return (
+ "Poll / wait / cancel a sub-AutoPilot from run_sub_session. "
+ f"Waits up to wait_if_running sec (max {MAX_SUB_SESSION_WAIT_SECONDS}); "
+ "cancel=true aborts; include_progress=true returns recent messages "
+ "from the still-running sub. Works across turns."
+ )
+
+ @property
+ def parameters(self) -> dict[str, Any]:
+ return {
+ "type": "object",
+ "properties": {
+ "sub_session_id": {
+ "type": "string",
+ "description": (
+ "The sub's session_id returned by run_sub_session "
+ "(also accepted: sub_autopilot_session_id — same value)."
+ ),
+ },
+ "wait_if_running": {
+ "type": "integer",
+ "description": (
+ f"Seconds to wait. 0 = just check. Clamped to "
+ f"{MAX_SUB_SESSION_WAIT_SECONDS}."
+ ),
+ "default": 60,
+ },
+ "cancel": {
+ "type": "boolean",
+ "description": (
+ "Cancel the sub; takes precedence over wait_if_running."
+ ),
+ "default": False,
+ },
+ "include_progress": {
+ "type": "boolean",
+ "description": (
+ "Populate progress.last_messages when status=running."
+ ),
+ "default": False,
+ },
+ },
+ "required": ["sub_session_id"],
+ }
+
+ async def _execute(
+ self,
+ user_id: str | None,
+ session: ChatSession,
+ *,
+ sub_session_id: str = "",
+ wait_if_running: int = 60,
+ cancel: bool = False,
+ include_progress: bool = False,
+ **kwargs,
+ ) -> ToolResponseBase:
+ inner_session_id = sub_session_id.strip()
+ if not inner_session_id:
+ return ErrorResponse(
+ message="sub_session_id is required",
+ session_id=session.session_id,
+ )
+ if user_id is None:
+ return ErrorResponse(
+ message="Authentication required",
+ session_id=session.session_id,
+ )
+
+ # Ownership check on every call — loads the ChatSession and
+ # confirms the caller owns it. Returning the same "not found"
+ # shape for "doesn't exist" and "belongs to someone else" avoids
+ # leaking session existence.
+ sub = await get_chat_session(inner_session_id)
+ if sub is None or sub.user_id != user_id:
+ return ErrorResponse(
+ message=(
+ f"No sub-session with id {inner_session_id}. It may have "
+ "never existed or belongs to another user."
+ ),
+ session_id=session.session_id,
+ )
+
+ started_at = time.monotonic()
+
+ if cancel:
+ # Fan out the cancel event. Whichever worker is running the
+ # sub will break out of its stream and finalise the session
+ # as failed. Return "cancelled" immediately; the sub may
+ # still emit a little more output before the worker notices,
+ # but the agent doesn't need to wait for that.
+ await enqueue_cancel_task(inner_session_id)
+ return SubSessionStatusResponse(
+ message="Sub-AutoPilot cancel requested.",
+ session_id=session.session_id,
+ status="cancelled",
+ sub_session_id=inner_session_id,
+ sub_autopilot_session_id=inner_session_id,
+ sub_autopilot_session_link=_sub_session_link(inner_session_id),
+ elapsed_seconds=0.0,
+ )
+
+ # If a turn is currently running for this session (stream registry
+ # meta shows status=running), we can NOT short-circuit on the
+ # persisted last assistant message — that message belongs to a
+ # PRIOR turn, and surfacing it here would hand the caller stale
+ # data while the new turn is mid-flight (sentry r3105409601).
+ # Only short-circuit when there's no active turn AND the last
+ # persisted message already looks terminal.
+ effective_wait = max(0, min(wait_if_running, MAX_SUB_SESSION_WAIT_SECONDS))
+ registry_session = await stream_registry.get_session(inner_session_id)
+ turn_in_flight = registry_session is not None and (
+ getattr(registry_session, "status", "") == "running"
+ )
+ terminal_result = None if turn_in_flight else _already_terminal_result(sub)
+ outcome: SessionOutcome
+ result: SessionResult
+ if terminal_result is not None:
+ outcome, result = "completed", terminal_result
+ elif effective_wait > 0:
+ outcome, result = await wait_for_session_result(
+ session_id=inner_session_id,
+ user_id=user_id,
+ timeout=effective_wait,
+ )
+ else:
+ outcome, result = "running", SessionResult()
+
+ elapsed = time.monotonic() - started_at
+
+ if outcome == "running" and include_progress:
+ # Running + caller wants progress — hand-assemble the response
+ # with the progress snapshot attached. response_from_outcome
+ # doesn't carry progress, so we build the response here.
+ progress = await _build_progress_snapshot(inner_session_id)
+ link = _sub_session_link(inner_session_id)
+ return SubSessionStatusResponse(
+ message=(
+ f"Sub-AutoPilot still running after {elapsed:.0f}s."
+ f"{f' Watch live at {link}.' if link else ''} "
+ "Call again to keep waiting, or cancel=true to abort."
+ ),
+ session_id=session.session_id,
+ status="running",
+ sub_session_id=inner_session_id,
+ sub_autopilot_session_id=inner_session_id,
+ sub_autopilot_session_link=link,
+ elapsed_seconds=round(elapsed, 2),
+ progress=progress,
+ )
+
+ return response_from_outcome(
+ outcome=outcome,
+ result=result,
+ inner_session_id=inner_session_id,
+ parent_session_id=session.session_id,
+ elapsed=elapsed,
+ )
+
+
+def _already_terminal_result(sub: ChatSession) -> SessionResult | None:
+ """Rebuild the aggregated result from the sub's persisted last turn,
+ when the last message is a terminal assistant message.
+
+ Lets ``get_sub_session_result`` short-circuit the subscribe+wait
+ when the agent polls well after the sub actually finished (a common
+ case when the user pauses and later asks "what's the result?").
+ Returns ``None`` if the last message isn't terminal.
+ """
+ if not sub.messages:
+ return None
+ last = sub.messages[-1]
+ if last.role != "assistant":
+ return None
+ if not last.content and not last.tool_calls:
+ return None
+ result = SessionResult()
+ result.response_text = last.content or ""
+ # Persisted tool calls are OpenAI-shape dicts; translate to
+ # ToolCallEntry so the downstream ``response_from_outcome`` can
+ # ``.model_dump()`` them uniformly with the live-drain path.
+ for tc in last.tool_calls or []:
+ fn = tc.get("function") or {}
+ result.tool_calls.append(
+ ToolCallEntry(
+ tool_call_id=tc.get("id", ""),
+ tool_name=fn.get("name") or tc.get("name") or "",
+ input=fn.get("arguments") or tc.get("arguments") or tc.get("input"),
+ output=tc.get("output"),
+ success=tc.get("success"),
+ )
+ )
+ return result
+
+
+async def _build_progress_snapshot(
+ inner_session_id: str | None,
+) -> SubSessionProgressSnapshot | None:
+ """Read the sub's ChatSession and return a preview of recent messages.
+
+ Returns ``None`` silently on lookup failure — progress is best-effort;
+ missing progress shouldn't abort the normal ``still running`` response.
+ """
+ if not inner_session_id:
+ return None
+ try:
+ sub = await get_chat_session(inner_session_id)
+ if sub is None:
+ return None
+ messages = list(sub.messages)
+ except Exception as exc: # best-effort peek
+ logger.debug(
+ "Progress snapshot unavailable for sub %s: %s",
+ inner_session_id,
+ exc,
+ )
+ return None
+
+ tail = messages[-_PROGRESS_MESSAGE_LIMIT:]
+ previews: list[dict[str, Any]] = []
+ for msg in tail:
+ content = getattr(msg, "content", "") or ""
+ if not isinstance(content, str):
+ try:
+ content = json.dumps(content, default=str)
+ except (TypeError, ValueError):
+ content = str(content)
+ if len(content) > _PROGRESS_CONTENT_PREVIEW_CHARS:
+ content = content[:_PROGRESS_CONTENT_PREVIEW_CHARS] + "…"
+ previews.append(
+ {
+ "role": getattr(msg, "role", "unknown"),
+ "content": content,
+ }
+ )
+ return SubSessionProgressSnapshot(
+ message_count=len(messages),
+ last_messages=previews,
+ )
diff --git a/autogpt_platform/backend/backend/copilot/tools/helpers.py b/autogpt_platform/backend/backend/copilot/tools/helpers.py
index cc45a3f63e..8ec31ee43e 100644
--- a/autogpt_platform/backend/backend/copilot/tools/helpers.py
+++ b/autogpt_platform/backend/backend/copilot/tools/helpers.py
@@ -1,5 +1,6 @@
"""Shared helpers for chat tools."""
+import asyncio
import logging
import uuid
from collections import defaultdict
@@ -14,6 +15,7 @@ from backend.copilot.constants import (
COPILOT_NODE_EXEC_ID_SEPARATOR,
COPILOT_NODE_PREFIX,
COPILOT_SESSION_PREFIX,
+ MAX_TOOL_WAIT_SECONDS,
)
from backend.copilot.model import ChatSession
from backend.copilot.sdk.file_ref import FileRefExpansionError, expand_file_refs_in_args
@@ -85,6 +87,71 @@ def get_inputs_from_schema(
return results
+async def _charge_block_credits(
+ _credit_db: Any,
+ *,
+ user_id: str,
+ block_name: str,
+ block_id: str,
+ node_exec_id: str,
+ cost: int,
+ cost_filter: dict[str, Any],
+ synthetic_graph_id: str,
+ synthetic_node_id: str,
+) -> None:
+ """Charge credits for a block execution and log any billing leak.
+
+ Centralised so the normal-path charge and the cancellation-recovery charge
+ (see ``execute_block``'s finally) use the same metadata and the same
+ leak-logging contract.
+ """
+ try:
+ await _credit_db.spend_credits(
+ user_id=user_id,
+ cost=cost,
+ metadata=UsageTransactionMetadata(
+ graph_exec_id=synthetic_graph_id,
+ graph_id=synthetic_graph_id,
+ node_id=synthetic_node_id,
+ node_exec_id=node_exec_id,
+ block_id=block_id,
+ block=block_name,
+ input=cost_filter,
+ reason="copilot_block_execution",
+ ),
+ )
+ except Exception as e:
+ # Block already executed (with possible side effects). Never
+ # return ErrorResponse here — the user received output and
+ # deserves it. Log the billing failure for reconciliation.
+ leak_type = (
+ "INSUFFICIENT_BALANCE"
+ if isinstance(e, InsufficientBalanceError)
+ else "UNEXPECTED_ERROR"
+ )
+ logger.error(
+ "BILLING_LEAK[%s]: block executed but credit charge failed — "
+ "user_id=%s, block_id=%s, node_exec_id=%s, cost=%s: %s",
+ leak_type,
+ user_id,
+ block_id,
+ node_exec_id,
+ cost,
+ e,
+ extra={
+ "json_fields": {
+ "billing_leak": True,
+ "leak_type": leak_type,
+ "user_id": user_id,
+ "cost": str(cost),
+ }
+ },
+ )
+ # Intentionally swallow. Block already executed with possible side
+ # effects; the caller must still return BlockOutputResponse. The
+ # BILLING_LEAK log above is the signal for reconciliation.
+
+
async def execute_block(
*,
block: AnyBlockSchema,
@@ -210,67 +277,97 @@ async def execute_block(
session_id=session_id,
)
- # Execute the block and collect outputs
+ # Execute the block under the shared MCP wait cap. A block is
+ # expected to finish in MAX_TOOL_WAIT_SECONDS; if it doesn't, the
+ # MCP handler would block the stream close to the idle timeout.
+ # wait_for cancels the generator on timeout, but the finally below
+ # still settles billing via asyncio.shield — external side effects
+ # may already have landed and the user should be charged for them.
outputs: dict[str, list[Any]] = defaultdict(list)
- async for output_name, output_data in block.execute(
- input_data,
- **exec_kwargs,
- ):
- outputs[output_name].append(output_data)
+ charge_handled = False
+ try:
+ await asyncio.wait_for(
+ _collect_block_outputs(block, input_data, exec_kwargs, outputs),
+ timeout=MAX_TOOL_WAIT_SECONDS,
+ )
- # Charge credits for block execution
- if has_cost:
- try:
- await _credit_db.spend_credits(
- user_id=user_id,
- cost=cost,
- metadata=UsageTransactionMetadata(
- graph_exec_id=synthetic_graph_id,
- graph_id=synthetic_graph_id,
- node_id=synthetic_node_id,
- node_exec_id=node_exec_id,
+ # Normal (non-cancelled) path. Mark charge_handled BEFORE the
+ # await so an outer cancellation landing mid-charge can't race
+ # the finally block into a double-charge. asyncio.shield keeps
+ # the spend running to completion even if the outer awaitable
+ # is cancelled.
+ if has_cost:
+ charge_handled = True
+ await asyncio.shield(
+ _charge_block_credits(
+ _credit_db,
+ user_id=user_id,
+ block_name=block.name,
block_id=block_id,
- block=block.name,
- input=cost_filter,
- reason="copilot_block_execution",
- ),
- )
- except Exception as e:
- # Block already executed (with possible side effects). Never
- # return ErrorResponse here — the user received output and
- # deserves it. Log the billing failure for reconciliation.
- leak_type = (
- "INSUFFICIENT_BALANCE"
- if isinstance(e, InsufficientBalanceError)
- else "UNEXPECTED_ERROR"
- )
- logger.error(
- "BILLING_LEAK[%s]: block executed but credit charge failed — "
- "user_id=%s, block_id=%s, node_exec_id=%s, cost=%s: %s",
- leak_type,
- user_id,
- block_id,
- node_exec_id,
- cost,
- e,
- extra={
- "json_fields": {
- "billing_leak": True,
- "leak_type": leak_type,
- "user_id": user_id,
- "cost": str(cost),
- }
- },
+ node_exec_id=node_exec_id,
+ cost=cost,
+ cost_filter=cost_filter,
+ synthetic_graph_id=synthetic_graph_id,
+ synthetic_node_id=synthetic_node_id,
+ )
)
- return BlockOutputResponse(
- message=f"Block '{block.name}' executed successfully",
- block_id=block_id,
- block_name=block.name,
- outputs=dict(outputs),
- success=True,
- session_id=session_id,
- )
+ return BlockOutputResponse(
+ message=f"Block '{block.name}' executed successfully",
+ block_id=block_id,
+ block_name=block.name,
+ outputs=dict(outputs),
+ success=True,
+ session_id=session_id,
+ )
+ except asyncio.TimeoutError:
+ # Structured record of tool-call timeouts (SECRT-2247 part 3).
+ # Grep prod logs for `copilot_tool_timeout` to find tools that
+ # keep hitting the cap — candidates for prompt tuning or
+ # escalation to the async start+poll pattern.
+ logger.warning(
+ "copilot_tool_timeout tool=run_block block=%s block_id=%s "
+ "input_keys=%s user=%s session=%s cap_s=%d",
+ block.name,
+ block_id,
+ sorted(input_data.keys()),
+ user_id,
+ session_id,
+ MAX_TOOL_WAIT_SECONDS,
+ )
+ return ErrorResponse(
+ message=(
+ f"Block '{block.name}' exceeded the "
+ f"{MAX_TOOL_WAIT_SECONDS}s single-tool wait cap and was "
+ "cancelled. Long-running work should go through run_agent "
+ "(graph executions) or run_sub_session (sub-AutoPilot "
+ "tasks) — those use async start+poll so nothing blocks "
+ "the chat stream."
+ ),
+ session_id=session_id,
+ )
+ finally:
+ # Sentry r3105079148: asyncio.wait_for raises CancelledError into
+ # the generator. Normal `except Exception` doesn't catch it, so
+ # without this finally a cancelled block would skip credit
+ # charging entirely while external side effects still landed.
+ # Only run when the normal-path charge was NOT reached (the flag
+ # is set before the await, so any cancellation during charge still
+ # sets it and avoids double-billing — r3105216985).
+ if has_cost and outputs and not charge_handled:
+ await asyncio.shield(
+ _charge_block_credits(
+ _credit_db,
+ user_id=user_id,
+ block_name=block.name,
+ block_id=block_id,
+ node_exec_id=node_exec_id,
+ cost=cost,
+ cost_filter=cost_filter,
+ synthetic_graph_id=synthetic_graph_id,
+ synthetic_node_id=synthetic_node_id,
+ )
+ )
except BlockError as e:
logger.warning("Block execution failed: %s", e)
@@ -288,6 +385,23 @@ async def execute_block(
)
+async def _collect_block_outputs(
+ block: AnyBlockSchema,
+ input_data: dict[str, Any],
+ exec_kwargs: dict[str, Any],
+ outputs: dict[str, list[Any]],
+) -> None:
+ """Drive ``block.execute`` and append each emitted pair to *outputs*.
+
+ Extracted so ``asyncio.wait_for`` can wrap exactly the generator-
+ consumption step; callers read ``outputs`` afterwards (including from
+ the cancellation path) to decide whether the block produced enough
+ side-effects to warrant billing.
+ """
+ async for output_name, output_data in block.execute(input_data, **exec_kwargs):
+ outputs[output_name].append(output_data)
+
+
async def resolve_block_credentials(
user_id: str,
block: AnyBlockSchema,
@@ -655,3 +769,51 @@ def _resolve_discriminated_credentials(
resolved[field_name] = effective_field_info
return resolved
+
+
+# ---------------------------------------------------------------------------
+# Agent-generation gate
+# ---------------------------------------------------------------------------
+#
+# Tools that produce or modify agent JSON (create_agent, edit_agent,
+# validate_agent_graph, fix_agent_graph) require the parent agent to have
+# read the agent-building guide first — otherwise it tends to generate
+# JSON that doesn't match the current block schemas, link semantics, or
+# AgentExecutorBlock conventions, then waste turns fixing validation
+# errors. ``require_guide_read`` returns an ``ErrorResponse`` the caller
+# should short-circuit with, or ``None`` when the guide has been read.
+
+
+_AGENT_GUIDE_TOOL_NAME = "get_agent_building_guide"
+
+
+def _guide_read_in_session(session: ChatSession) -> bool:
+ """True if this session's assistant messages include a guide tool call."""
+ for msg in reversed(session.messages):
+ if msg.role != "assistant" or not msg.tool_calls:
+ continue
+ for tc in msg.tool_calls:
+ name = tc.get("function", {}).get("name") or tc.get("name")
+ if name == _AGENT_GUIDE_TOOL_NAME:
+ return True
+ return False
+
+
+def require_guide_read(session: ChatSession, tool_name: str):
+ """Return an ErrorResponse if the guide hasn't been loaded this session.
+
+ Import inline to keep ``helpers.py`` free of tool-response imports.
+ """
+ from .models import ErrorResponse # noqa: PLC0415 — avoid circular import
+
+ if _guide_read_in_session(session):
+ return None
+ return ErrorResponse(
+ message=(
+ f"Call get_agent_building_guide first, then retry {tool_name}. "
+ "The guide documents required block ids, input/output schemas, "
+ "link semantics, and AgentExecutorBlock / MCPToolBlock usage — "
+ "generating agent JSON without it produces schema mismatches."
+ ),
+ session_id=session.session_id,
+ )
diff --git a/autogpt_platform/backend/backend/copilot/tools/models.py b/autogpt_platform/backend/backend/copilot/tools/models.py
index 90aa3d51db..645d6468ef 100644
--- a/autogpt_platform/backend/backend/copilot/tools/models.py
+++ b/autogpt_platform/backend/backend/copilot/tools/models.py
@@ -259,6 +259,85 @@ class ErrorResponse(ToolResponseBase):
details: dict[str, Any] | None = None
+class SubSessionProgressSnapshot(BaseModel):
+ """Mid-flight snapshot of a running sub-AutoPilot.
+
+ Returned under ``progress`` on :class:`SubSessionStatusResponse` when the
+ caller passes ``include_progress=true`` while the sub is still running.
+ """
+
+ message_count: int = Field(
+ description="Total messages in the sub's ChatSession so far.",
+ )
+ last_messages: list[dict[str, Any]] = Field(
+ default_factory=list,
+ description=(
+ "Up to the last 5 messages (role + truncated content) from the "
+ "sub's ChatSession — lets the agent report intermediate progress."
+ ),
+ )
+
+
+class SubSessionStatusResponse(ToolResponseBase):
+ """Status / result of a sub-AutoPilot run started by ``run_sub_session``.
+
+ Returned by both ``run_sub_session`` (synchronously when the sub finishes
+ within ``wait_for_result``, else with ``status='running'``) and
+ ``get_sub_session_result`` when the agent polls.
+ """
+
+ type: ResponseType = ResponseType.MCP_TOOL_OUTPUT
+ status: Literal["running", "completed", "cancelled", "error"] = Field(
+ description="Current state of the sub-AutoPilot run.",
+ )
+ sub_session_id: str = Field(
+ description=(
+ "Opaque id for this run. Pass to ``get_sub_session_result`` or "
+ "``run_sub_session(cancel=true, ...)`` to interact with it."
+ ),
+ )
+ response: str | None = Field(
+ default=None,
+ description="Assistant response text when status=completed.",
+ )
+ sub_autopilot_session_id: str | None = Field(
+ default=None,
+ description=(
+ "The session_id of the sub-AutoPilot conversation. Use with "
+ "``run_sub_session(..., sub_autopilot_session_id=<this>)`` "
+ "to continue it."
+ ),
+ )
+ sub_autopilot_session_link: str | None = Field(
+ default=None,
+ description=(
+ "Relative URL the user can click to open the sub-AutoPilot "
+ "conversation in the CoPilot UI. Always set when "
+ "``sub_autopilot_session_id`` is set."
+ ),
+ )
+ tool_calls: list[dict[str, Any]] | None = Field(
+ default=None,
+ description="Tool calls made during the sub-AutoPilot run.",
+ )
+ error: str | None = Field(
+ default=None,
+ description="Error message when status=error.",
+ )
+ elapsed_seconds: float | None = Field(
+ default=None,
+ description="How long the sub-AutoPilot has been running (or took).",
+ )
+ progress: SubSessionProgressSnapshot | None = Field(
+ default=None,
+ description=(
+ "Mid-flight progress snapshot. Populated only when "
+ "get_sub_session_result is called with include_progress=true "
+ "and the sub is still running."
+ ),
+ )
+
+
class InputValidationErrorResponse(ToolResponseBase):
"""Response when run_agent receives unknown input fields."""
diff --git a/autogpt_platform/backend/backend/copilot/tools/run_agent.py b/autogpt_platform/backend/backend/copilot/tools/run_agent.py
index d29869c3fe..9be26a3311 100644
--- a/autogpt_platform/backend/backend/copilot/tools/run_agent.py
+++ b/autogpt_platform/backend/backend/copilot/tools/run_agent.py
@@ -6,6 +6,7 @@ from typing import Any
from pydantic import BaseModel, Field, field_validator
from backend.copilot.config import ChatConfig
+from backend.copilot.constants import MAX_TOOL_WAIT_SECONDS
from backend.copilot.model import ChatSession
from backend.copilot.tracking import track_agent_run_success, track_agent_scheduled
from backend.data.db_accessors import graph_db, library_db, user_db
@@ -71,7 +72,7 @@ class RunAgentInput(BaseModel):
schedule_name: str = ""
cron: str = ""
timezone: str = "UTC"
- wait_for_result: int = Field(default=0, ge=0, le=300)
+ wait_for_result: int = Field(default=0, ge=0, le=MAX_TOOL_WAIT_SECONDS)
dry_run: bool = Field(default=False)
@field_validator(
@@ -150,9 +151,12 @@ class RunAgentTool(BaseTool):
},
"wait_for_result": {
"type": "integer",
- "description": "Max seconds to wait for completion (0-300).",
+ "description": (
+ "Max seconds to wait for completion "
+ f"(0-{MAX_TOOL_WAIT_SECONDS})."
+ ),
"minimum": 0,
- "maximum": 300,
+ "maximum": MAX_TOOL_WAIT_SECONDS,
},
"dry_run": {
"type": "boolean",
diff --git a/autogpt_platform/backend/backend/copilot/tools/run_block_test.py b/autogpt_platform/backend/backend/copilot/tools/run_block_test.py
index 98edc2315b..7fbf1f0b34 100644
--- a/autogpt_platform/backend/backend/copilot/tools/run_block_test.py
+++ b/autogpt_platform/backend/backend/copilot/tools/run_block_test.py
@@ -140,7 +140,9 @@ class TestRunBlockFiltering:
async def test_block_denied_by_permissions_returns_error(self):
"""A block denied by CopilotPermissions returns an ErrorResponse."""
session = make_session(user_id=_TEST_USER_ID)
- block_id = "c069dc6b-c3ed-4c12-b6e5-d47361e64ce6"
+ # NB: must not match any id in COPILOT_EXCLUDED_BLOCK_IDS — we want
+ # the permissions guard to fire, not the exclusion guard.
+ block_id = "11111111-2222-3333-4444-555555555555"
standard_block = make_mock_block(block_id, "HTTP Request", BlockType.STANDARD)
perms = CopilotPermissions(blocks=[block_id], blocks_exclude=True)
@@ -645,3 +647,230 @@ class TestRunBlockSensitiveAction:
assert isinstance(response, BlockOutputResponse)
assert response.success is True
+
+
+class TestExecuteBlockTimeout:
+ """``execute_block`` caps the block's generator consumption at
+ MAX_TOOL_WAIT_SECONDS and must:
+ 1. Return an actionable ErrorResponse pointing at run_agent / run_sub_session.
+ 2. Log a ``copilot_tool_timeout`` warning (SECRT-2247 part 3).
+ 3. Still charge credits when outputs were produced before the timeout
+ (sentry r3105079148 — cancellation must not leak billing)."""
+
+ @pytest.mark.asyncio(loop_scope="session")
+ async def test_timeout_returns_error_and_logs(self, caplog):
+ import asyncio
+ import logging
+
+ from backend.copilot.tools.helpers import execute_block
+
+ mock_block = MagicMock()
+ mock_block.name = "SlowBlock"
+ mock_block.id = "slow-block-id"
+ mock_block.input_schema = MagicMock()
+ mock_block.input_schema.jsonschema.return_value = {
+ "properties": {},
+ "required": [],
+ }
+ mock_block.input_schema.get_credentials_fields.return_value = {}
+
+ async def _hang(_input, **_kwargs):
+ await asyncio.sleep(10)
+ yield "never", "never"
+
+ mock_block.execute = _hang
+
+ mock_workspace_db = MagicMock()
+ mock_workspace_db.get_or_create_workspace = AsyncMock(
+ return_value=MagicMock(id="ws-1")
+ )
+
+ with (
+ patch(
+ "backend.copilot.tools.helpers.workspace_db",
+ return_value=mock_workspace_db,
+ ),
+ patch(
+ "backend.copilot.tools.helpers.block_usage_cost",
+ return_value=(0, {}),
+ ),
+ patch(
+ "backend.copilot.tools.helpers.MAX_TOOL_WAIT_SECONDS",
+ 0.05,
+ ),
+ caplog.at_level(logging.WARNING, logger="backend.copilot.tools.helpers"),
+ ):
+ response = await execute_block(
+ block=mock_block,
+ block_id="slow-block-id",
+ input_data={"x": 1},
+ user_id="u-1",
+ session_id="s-1",
+ node_exec_id="n-1",
+ matched_credentials={},
+ dry_run=False,
+ )
+
+ assert isinstance(response, ErrorResponse)
+ assert "single-tool wait cap" in response.message
+ assert "run_agent" in response.message
+ assert any(
+ "copilot_tool_timeout" in record.getMessage() for record in caplog.records
+ ), "timeout must emit a grep-friendly log line for SECRT-2247 part 3"
+
+ @pytest.mark.asyncio(loop_scope="session")
+ async def test_cancellation_after_output_still_charges_credits(self):
+ """Regression for sentry r3105079148 — wait_for's CancelledError
+ bypassed credit charging; fix uses a shielded finally. One output
+ emitted, then timeout: spend_credits must still be called once."""
+ import asyncio
+
+ from backend.copilot.tools.helpers import execute_block
+
+ mock_block = MagicMock()
+ mock_block.name = "CostlyBlock"
+ mock_block.id = "costly-block-id"
+ mock_block.input_schema = MagicMock()
+ mock_block.input_schema.jsonschema.return_value = {
+ "properties": {},
+ "required": [],
+ }
+ mock_block.input_schema.get_credentials_fields.return_value = {}
+
+ # Generator: emit ONE output (simulating a side-effectful API call),
+ # then hang — execute_block's internal wait_for cancels us.
+ async def _one_output_then_hang(_input, **_kw):
+ yield "result", "side effect happened"
+ await asyncio.sleep(10)
+ yield "extra", "should never arrive"
+
+ mock_block.execute = _one_output_then_hang
+
+ charged: dict[str, object] = {}
+
+ class _FakeCreditDB:
+ async def get_credits(self, _user_id: str) -> int:
+ return 10_000
+
+ async def spend_credits(self, **kwargs):
+ charged["last"] = kwargs
+
+ mock_workspace_db = MagicMock()
+ mock_workspace_db.get_or_create_workspace = AsyncMock(
+ return_value=MagicMock(id="ws-1")
+ )
+
+ with (
+ patch(
+ "backend.copilot.tools.helpers.workspace_db",
+ return_value=mock_workspace_db,
+ ),
+ patch(
+ "backend.copilot.tools.helpers.credit_db",
+ return_value=_FakeCreditDB(),
+ ),
+ patch(
+ "backend.copilot.tools.helpers.block_usage_cost",
+ return_value=(5, {}),
+ ),
+ patch(
+ "backend.copilot.tools.helpers.MAX_TOOL_WAIT_SECONDS",
+ 0.2,
+ ),
+ ):
+ response = await execute_block(
+ block=mock_block,
+ block_id="costly-block-id",
+ input_data={},
+ user_id="u-42",
+ session_id="s-42",
+ node_exec_id="n-42",
+ matched_credentials={},
+ dry_run=False,
+ )
+
+ # Cap fired → response is the timeout ErrorResponse
+ assert isinstance(response, ErrorResponse)
+ assert "single-tool wait cap" in response.message
+
+ # Critical: billing ran via the shielded finally despite the cancellation
+ assert charged.get("last") is not None, (
+ "Credits were NOT charged after cancellation — billing leak "
+ "(sentry r3105079148)"
+ )
+ assert charged["last"]["user_id"] == "u-42"
+ assert charged["last"]["cost"] == 5
+
+ @pytest.mark.asyncio(loop_scope="session")
+ async def test_no_double_charge_on_cancellation_during_charge(self):
+ """Regression for sentry r3105216985 — if the caller cancels during
+ the normal-path credit charge, the finally must NOT charge a second
+ time. The fix marks charge_handled BEFORE awaiting spend_credits."""
+ import asyncio
+
+ from backend.copilot.tools.helpers import execute_block
+
+ mock_block = MagicMock()
+ mock_block.name = "OnceOnlyBlock"
+ mock_block.id = "once-only-id"
+ mock_block.input_schema = MagicMock()
+ mock_block.input_schema.jsonschema.return_value = {
+ "properties": {},
+ "required": [],
+ }
+ mock_block.input_schema.get_credentials_fields.return_value = {}
+
+ async def _one_then_done(_input, **_kw):
+ yield "result", "done"
+
+ mock_block.execute = _one_then_done
+
+ spend_calls: list[dict] = []
+
+ class _CountingCreditDB:
+ async def get_credits(self, _user_id: str) -> int:
+ return 10_000
+
+ async def spend_credits(self, **kwargs):
+ # Cooperative suspension so an outer cancellation can
+ # theoretically interleave — shield should still make this
+ # complete exactly once.
+ await asyncio.sleep(0)
+ spend_calls.append(kwargs)
+
+ mock_workspace_db = MagicMock()
+ mock_workspace_db.get_or_create_workspace = AsyncMock(
+ return_value=MagicMock(id="ws-1")
+ )
+
+ with (
+ patch(
+ "backend.copilot.tools.helpers.workspace_db",
+ return_value=mock_workspace_db,
+ ),
+ patch(
+ "backend.copilot.tools.helpers.credit_db",
+ return_value=_CountingCreditDB(),
+ ),
+ patch(
+ "backend.copilot.tools.helpers.block_usage_cost",
+ return_value=(7, {}),
+ ),
+ ):
+ response = await execute_block(
+ block=mock_block,
+ block_id="once-only-id",
+ input_data={},
+ user_id="u-single",
+ session_id="s-single",
+ node_exec_id="n-single",
+ matched_credentials={},
+ dry_run=False,
+ )
+
+ assert isinstance(response, BlockOutputResponse)
+ assert response.success is True
+ assert len(spend_calls) == 1, (
+ f"spend_credits must be called exactly once, got {len(spend_calls)} "
+ "(double-charge — sentry r3105216985)"
+ )
diff --git a/autogpt_platform/backend/backend/copilot/tools/run_sub_session.py b/autogpt_platform/backend/backend/copilot/tools/run_sub_session.py
new file mode 100644
index 0000000000..a972335606
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/tools/run_sub_session.py
@@ -0,0 +1,240 @@
+"""Start a sub-AutoPilot conversation via the copilot_executor queue.
+
+Mirror-image of ``run_agent`` + ``view_agent_output`` for copilot turns:
+
+1. The tool creates (or validates ownership of) an inner ``ChatSession``
+ and calls :func:`run_copilot_turn_via_queue` — the shared primitive
+ that creates the stream-registry session meta, enqueues a
+ ``CoPilotExecutionEntry``, and waits on the Redis stream until the
+ terminal event arrives or the cap fires.
+2. Any available ``copilot_executor`` worker claims the job, runs
+ ``collect_copilot_response`` to completion, and publishes the final
+ ``StreamFinish`` event on the session's Redis stream.
+3. If the terminal event arrives in the wait window, the aggregated
+ :class:`SessionResult` (response text, tool calls, usage) comes back
+ in memory — no DB round-trip. Otherwise the tool returns
+ ``status="running"`` + the sub's ``session_id`` and the agent polls
+ via :mod:`get_sub_session_result`.
+
+Compared to the prior in-process ``asyncio.Task`` implementation this
+gives us deploy/crash resilience, natural load balancing across
+workers, and a uniform conversation model — a sub is just another
+copilot turn routed through the same queue and event bus as every
+other turn.
+"""
+
+import logging
+import time
+from typing import Any
+
+from backend.copilot.constants import MAX_TOOL_WAIT_SECONDS
+from backend.copilot.context import get_current_permissions
+from backend.copilot.model import ChatSession, create_chat_session, get_chat_session
+from backend.copilot.sdk.session_waiter import (
+ SessionOutcome,
+ SessionResult,
+ run_copilot_turn_via_queue,
+)
+
+from .base import BaseTool
+from .models import ErrorResponse, SubSessionStatusResponse, ToolResponseBase
+
+logger = logging.getLogger(__name__)
+
+
+# Max wait for a single run_sub_session / get_sub_session_result call.
+# Shared with every other long-running tool so the stream idle timeout's
+# 2x headroom holds uniformly.
+MAX_SUB_SESSION_WAIT_SECONDS = MAX_TOOL_WAIT_SECONDS
+
+
+class RunSubSessionTool(BaseTool):
+ """Delegate a task to a fresh sub-AutoPilot via the copilot_executor queue."""
+
+ @property
+ def name(self) -> str:
+ return "run_sub_session"
+
+ @property
+ def requires_auth(self) -> bool:
+ return True
+
+ @property
+ def description(self) -> str:
+ return (
+ "Delegate a task to a fresh sub-AutoPilot. Runs on the copilot "
+ "executor queue — survives tab-close AND worker restarts. Waits "
+ f"up to wait_for_result sec (max {MAX_SUB_SESSION_WAIT_SECONDS}). "
+ "If not done, returns status=running + sub_session_id — poll via "
+ "get_sub_session_result."
+ )
+
+ @property
+ def parameters(self) -> dict[str, Any]:
+ return {
+ "type": "object",
+ "properties": {
+ "prompt": {
+ "type": "string",
+ "description": "The task for the sub-AutoPilot to execute.",
+ },
+ "system_context": {
+ "type": "string",
+ "description": "Optional context prepended to the prompt.",
+ "default": "",
+ },
+ "sub_autopilot_session_id": {
+ "type": "string",
+ "description": (
+ "Continue a prior sub via its session_id; empty = new."
+ ),
+ "default": "",
+ },
+ "wait_for_result": {
+ "type": "integer",
+ "description": (
+ "Seconds to wait inline. 0 = return immediately. "
+ f"Clamped to {MAX_SUB_SESSION_WAIT_SECONDS}."
+ ),
+ "default": 60,
+ },
+ },
+ "required": ["prompt"],
+ }
+
+ async def _execute(
+ self,
+ user_id: str | None,
+ session: ChatSession,
+ *,
+ prompt: str = "",
+ system_context: str = "",
+ sub_autopilot_session_id: str = "",
+ wait_for_result: int = 60,
+ **kwargs,
+ ) -> ToolResponseBase:
+ if not prompt.strip():
+ return ErrorResponse(
+ message="prompt is required",
+ session_id=session.session_id,
+ )
+ if user_id is None:
+ return ErrorResponse(
+ message="Authentication required",
+ session_id=session.session_id,
+ )
+
+ # Resolve the sub's ChatSession id — either resume an owned one or
+ # create a fresh session that inherits the parent's dry_run so a
+ # sub spawned inside a dry-run conversation doesn't silently
+ # escalate to a live run.
+ sub_session_param = sub_autopilot_session_id.strip()
+ if sub_session_param:
+ owned = await get_chat_session(sub_session_param)
+ if owned is None or owned.user_id != user_id:
+ return ErrorResponse(
+ message=(
+ f"sub_autopilot_session_id {sub_session_param} is not "
+ "a session you own. Leave empty to start a fresh sub, "
+ "or pass a session_id returned by a previous "
+ "run_sub_session call of yours."
+ ),
+ session_id=session.session_id,
+ )
+ inner_session_id = sub_session_param
+ else:
+ new_session = await create_chat_session(user_id, dry_run=session.dry_run)
+ inner_session_id = new_session.session_id
+
+ effective_prompt = prompt
+ if system_context.strip():
+ effective_prompt = f"[System Context: {system_context.strip()}]\n\n{prompt}"
+
+ cap = max(0, min(wait_for_result, MAX_SUB_SESSION_WAIT_SECONDS))
+ started_at = time.monotonic()
+ outcome, result = await run_copilot_turn_via_queue(
+ session_id=inner_session_id,
+ user_id=user_id,
+ message=effective_prompt,
+ timeout=cap,
+ permissions=get_current_permissions(),
+ tool_call_id=(f"sub:{session.session_id}" if session.session_id else "sub"),
+ tool_name="run_sub_session",
+ )
+ elapsed = time.monotonic() - started_at
+ return response_from_outcome(
+ outcome=outcome,
+ result=result,
+ inner_session_id=inner_session_id,
+ parent_session_id=session.session_id,
+ elapsed=elapsed,
+ )
+
+
+def _sub_session_link(inner_session_id: str | None) -> str | None:
+ """Build the CoPilot UI URL for a sub-AutoPilot session.
+
+ Kept in one place so the format stays consistent across the
+ running/completed/error paths, and so the frontend only has one
+ contract to honour.
+ """
+ if not inner_session_id:
+ return None
+ return f"/copilot?sessionId={inner_session_id}"
+
+
+def response_from_outcome(
+ *,
+ outcome: SessionOutcome,
+ result: SessionResult,
+ inner_session_id: str,
+ parent_session_id: str | None,
+ elapsed: float,
+) -> SubSessionStatusResponse:
+ """Translate a ``(SessionOutcome, SessionResult)`` tuple into the
+ ``SubSessionStatusResponse`` contract the LLM sees.
+
+ ``completed`` surfaces the aggregated response text + tool calls.
+ ``failed`` returns the error marker with the same handles.
+ ``running`` returns just the polling handles so the agent can resume.
+ """
+ link = _sub_session_link(inner_session_id)
+ if outcome == "running":
+ return SubSessionStatusResponse(
+ message=(
+ f"Sub-AutoPilot is still running after {elapsed:.0f}s."
+ f"{f' Watch live at {link}.' if link else ''} "
+ "Call get_sub_session_result (optionally with "
+ "include_progress=true) to wait, poll, or inspect progress."
+ ),
+ session_id=parent_session_id,
+ status="running",
+ 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 == "failed":
+ return SubSessionStatusResponse(
+ message="Sub-AutoPilot failed. See the sub's transcript for details.",
+ 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),
+ )
+
+ # completed
+ return SubSessionStatusResponse(
+ message=f"Sub-AutoPilot completed.{f' View at {link}.' if link else ''}",
+ session_id=parent_session_id,
+ status="completed",
+ sub_session_id=inner_session_id,
+ sub_autopilot_session_id=inner_session_id,
+ sub_autopilot_session_link=link,
+ response=result.response_text,
+ tool_calls=[tc.model_dump() for tc in result.tool_calls],
+ elapsed_seconds=round(elapsed, 2),
+ )
diff --git a/autogpt_platform/backend/backend/copilot/tools/sub_session_test.py b/autogpt_platform/backend/backend/copilot/tools/sub_session_test.py
new file mode 100644
index 0000000000..7ff2b60f50
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/tools/sub_session_test.py
@@ -0,0 +1,500 @@
+"""Tests for run_sub_session + get_sub_session_result (queue-backed flow).
+
+Sub-AutoPilots are enqueued on the copilot_execution RabbitMQ queue and
+executed by any copilot_executor worker. The tools wait for completion
+by subscribing to ``stream_registry`` for the sub's ChatSession. These
+tests patch the three integration seams — ``enqueue_copilot_turn``,
+``wait_for_session_completion``, and ``stream_registry.create_session``
+— to exercise the tool logic without needing RabbitMQ or Redis.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from .get_sub_session_result import GetSubSessionResultTool
+from .models import ErrorResponse, SubSessionStatusResponse
+from .run_sub_session import MAX_SUB_SESSION_WAIT_SECONDS, RunSubSessionTool
+
+
+def _session(user_id: str = "u", session_id: str = "s1") -> MagicMock:
+ sess = MagicMock()
+ sess.session_id = session_id
+ sess.dry_run = False
+ return sess
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+def mock_queue(monkeypatch):
+ """Patch the enqueue helpers + the stream-registry session creator at
+ the source modules (session_waiter / get_sub_session_result) so tests
+ don't need RabbitMQ or Redis. Returns a dict of the mocks so
+ individual tests can assert on them.
+ """
+ enqueue_turn = AsyncMock()
+ enqueue_cancel = AsyncMock()
+ create_session = AsyncMock()
+
+ # run_sub_session calls enqueue_copilot_turn via session_waiter's
+ # run_copilot_turn_via_queue helper — patch at the helper's source.
+ monkeypatch.setattr(
+ "backend.copilot.sdk.session_waiter.enqueue_copilot_turn",
+ enqueue_turn,
+ )
+ monkeypatch.setattr(
+ "backend.copilot.tools.get_sub_session_result.enqueue_cancel_task",
+ enqueue_cancel,
+ )
+ monkeypatch.setattr(
+ "backend.copilot.sdk.session_waiter.stream_registry.create_session",
+ create_session,
+ )
+ return {
+ "enqueue_turn": enqueue_turn,
+ "enqueue_cancel": enqueue_cancel,
+ "create_session": create_session,
+ }
+
+
+def mock_waiter(monkeypatch):
+ """Patch the queue-backed primitive and the lightweight waiter so
+ tests can drive outcome + result deterministically. Returns the
+ ``run_copilot_turn_via_queue`` mock (used by run_sub_session) and
+ the ``wait_for_session_result`` mock (used by get_sub_session_result)
+ wired to return ``("running", SessionResult())`` by default."""
+ from backend.copilot.sdk.session_waiter import SessionResult
+
+ turn_mock = AsyncMock(return_value=("running", SessionResult()))
+ result_mock = AsyncMock(return_value=("running", SessionResult()))
+ monkeypatch.setattr(
+ "backend.copilot.tools.run_sub_session.run_copilot_turn_via_queue",
+ turn_mock,
+ )
+ monkeypatch.setattr(
+ "backend.copilot.tools.get_sub_session_result.wait_for_session_result",
+ result_mock,
+ )
+ # Single handle with both attrs for tests that only care about one.
+ turn_mock.result_mock = result_mock
+ return turn_mock
+
+
+def mock_model(monkeypatch):
+ """Patch the model-layer helpers the tools call for session CRUD +
+ ownership checks. The create side returns a fake ChatSession with a
+ fresh uuid each call."""
+ created: list[MagicMock] = []
+
+ async def fake_create(user_id: str, *, dry_run: bool):
+ sess = MagicMock()
+ sess.session_id = f"inner-{len(created) + 1}"
+ sess.user_id = user_id
+ sess.dry_run = dry_run
+ sess.messages = []
+ created.append(sess)
+ return sess
+
+ async def fake_get(session_id: str):
+ for s in created:
+ if s.session_id == session_id:
+ return s
+ return None
+
+ # The tool modules bind these names at import time, so patch the
+ # local module bindings (not the source in backend.copilot.model).
+ monkeypatch.setattr(
+ "backend.copilot.tools.run_sub_session.create_chat_session", fake_create
+ )
+ monkeypatch.setattr(
+ "backend.copilot.tools.run_sub_session.get_chat_session", fake_get
+ )
+ monkeypatch.setattr(
+ "backend.copilot.tools.get_sub_session_result.get_chat_session", fake_get
+ )
+ return {"created": created, "get": fake_get}
+
+
+# ---------------------------------------------------------------------------
+# RunSubSessionTool
+# ---------------------------------------------------------------------------
+
+
+class TestRunSubSession:
+ @pytest.mark.asyncio
+ async def test_missing_prompt_returns_error(self):
+ r = await RunSubSessionTool()._execute(
+ user_id="u", session=_session(), prompt=""
+ )
+ assert isinstance(r, ErrorResponse)
+
+ @pytest.mark.asyncio
+ async def test_no_user_returns_error(self):
+ r = await RunSubSessionTool()._execute(
+ user_id=None, session=_session(), prompt="hi"
+ )
+ assert isinstance(r, ErrorResponse)
+
+ @pytest.mark.asyncio
+ async def test_resume_with_other_users_session_id_rejected(
+ self, monkeypatch, mock_queue, mock_waiter
+ ):
+ """Ownership must be re-verified when the caller passes a resume id."""
+ foreign = MagicMock(session_id="alien-sess", user_id="not-caller", messages=[])
+
+ async def fake_get(session_id: str):
+ if session_id == "alien-sess":
+ return foreign
+ return None
+
+ monkeypatch.setattr(
+ "backend.copilot.tools.run_sub_session.get_chat_session", fake_get
+ )
+
+ r = await RunSubSessionTool()._execute(
+ user_id="alice",
+ session=_session("alice"),
+ prompt="continue",
+ sub_autopilot_session_id="alien-sess",
+ )
+ assert isinstance(r, ErrorResponse)
+ assert "is not a session you own" in r.message
+ mock_queue["enqueue_turn"].assert_not_awaited()
+
+ @pytest.mark.asyncio
+ async def test_propagates_dry_run_to_sub(self, mock_queue, mock_waiter, mock_model):
+ """Fresh sub-session must inherit the parent's dry_run flag."""
+ parent = _session("alice")
+ parent.dry_run = True
+ await RunSubSessionTool()._execute(
+ user_id="alice",
+ session=parent,
+ prompt="hi",
+ wait_for_result=0, # skip the wait helper for this assertion
+ )
+ assert mock_model["created"], "create_chat_session was never awaited"
+ assert mock_model["created"][0].dry_run is True
+
+ @pytest.mark.asyncio
+ async def test_forwards_parent_permissions_to_queue(
+ self, monkeypatch, mock_queue, mock_waiter, mock_model
+ ):
+ """The parent's CopilotPermissions must be passed through to the
+ queue primitive so the worker applies the same filter."""
+ from backend.copilot.permissions import CopilotPermissions
+
+ perms = CopilotPermissions(tools=["run_block"], tools_exclude=False)
+ monkeypatch.setattr(
+ "backend.copilot.tools.run_sub_session.get_current_permissions",
+ lambda: perms,
+ )
+ await RunSubSessionTool()._execute(
+ user_id="alice",
+ session=_session("alice"),
+ prompt="hi",
+ wait_for_result=0,
+ )
+ mock_waiter.assert_awaited_once()
+ assert mock_waiter.await_args.kwargs["permissions"] is perms
+
+ @pytest.mark.asyncio
+ async def test_wait_for_result_zero_returns_running(
+ self, mock_queue, mock_waiter, mock_model
+ ):
+ """wait_for_result=0 still dispatches the job (so the sub starts)
+ but the primitive returns 'running' immediately because timeout=0,
+ and the tool surfaces that to the caller."""
+ r = await RunSubSessionTool()._execute(
+ user_id="alice",
+ session=_session("alice"),
+ prompt="hi",
+ wait_for_result=0,
+ )
+ assert isinstance(r, SubSessionStatusResponse)
+ assert r.status == "running"
+ assert r.sub_session_id == r.sub_autopilot_session_id == "inner-1"
+ assert r.sub_autopilot_session_link == "/copilot?sessionId=inner-1"
+ mock_waiter.assert_awaited_once()
+ assert mock_waiter.await_args.kwargs["timeout"] == 0
+
+ @pytest.mark.asyncio
+ async def test_wait_for_result_completed_returns_final_response(
+ self, mock_queue, mock_waiter, mock_model
+ ):
+ """When the queue primitive returns 'completed' + a SessionResult,
+ the tool surfaces response_text + tool_calls directly — no DB
+ round-trip needed for the content."""
+ from backend.copilot.sdk.session_waiter import SessionResult
+ from backend.copilot.sdk.stream_accumulator import ToolCallEntry
+
+ res = SessionResult()
+ res.response_text = "the answer"
+ res.tool_calls = [
+ ToolCallEntry(
+ tool_call_id="tc-1",
+ tool_name="foo",
+ input={"x": 1},
+ output="ok",
+ success=True,
+ )
+ ]
+ mock_waiter.return_value = ("completed", res)
+
+ r = await RunSubSessionTool()._execute(
+ user_id="alice",
+ session=_session("alice"),
+ prompt="hi",
+ wait_for_result=60,
+ )
+ assert isinstance(r, SubSessionStatusResponse)
+ assert r.status == "completed"
+ assert r.response == "the answer"
+ assert r.tool_calls is not None and len(r.tool_calls) == 1
+ assert r.tool_calls[0]["tool_name"] == "foo"
+ mock_waiter.assert_awaited_once()
+
+ @pytest.mark.asyncio
+ async def test_wait_clamps_above_maximum(self, mock_queue, mock_waiter, mock_model):
+ """wait_for_result values above the cap are clamped before being
+ passed to the queue primitive."""
+ await RunSubSessionTool()._execute(
+ user_id="alice",
+ session=_session("alice"),
+ prompt="hi",
+ wait_for_result=MAX_SUB_SESSION_WAIT_SECONDS + 999,
+ )
+ mock_waiter.assert_awaited_once()
+ assert mock_waiter.await_args.kwargs["timeout"] == MAX_SUB_SESSION_WAIT_SECONDS
+
+
+# ---------------------------------------------------------------------------
+# GetSubSessionResultTool
+# ---------------------------------------------------------------------------
+
+
+class TestGetSubSessionResult:
+ @pytest.mark.asyncio
+ async def test_missing_id_returns_error(self):
+ r = await GetSubSessionResultTool()._execute(
+ user_id="u", session=_session(), sub_session_id=""
+ )
+ assert isinstance(r, ErrorResponse)
+
+ @pytest.mark.asyncio
+ async def test_unknown_id_returns_error(self, monkeypatch):
+ async def none_get(_sid):
+ return None
+
+ monkeypatch.setattr(
+ "backend.copilot.tools.get_sub_session_result.get_chat_session",
+ none_get,
+ )
+ r = await GetSubSessionResultTool()._execute(
+ user_id="u", session=_session(), sub_session_id="missing"
+ )
+ assert isinstance(r, ErrorResponse)
+ assert "No sub-session with id missing" in r.message
+
+ @pytest.mark.asyncio
+ async def test_other_user_cannot_access(self, monkeypatch):
+ """Cross-user lookups are indistinguishable from 'not found'."""
+ foreign = MagicMock(user_id="bob", messages=[])
+
+ async def foreign_get(_sid):
+ return foreign
+
+ monkeypatch.setattr(
+ "backend.copilot.tools.get_sub_session_result.get_chat_session",
+ foreign_get,
+ )
+ r = await GetSubSessionResultTool()._execute(
+ user_id="alice", session=_session("alice"), sub_session_id="bobs-sess"
+ )
+ assert isinstance(r, ErrorResponse)
+ assert "No sub-session" in r.message
+
+ @pytest.mark.asyncio
+ async def test_wait_returns_running(self, monkeypatch, mock_waiter):
+ sub = MagicMock(user_id="alice", messages=[])
+
+ async def fake_get(_sid):
+ return sub
+
+ async def no_active_session(_sid):
+ return None
+
+ monkeypatch.setattr(
+ "backend.copilot.tools.get_sub_session_result.get_chat_session",
+ fake_get,
+ )
+ monkeypatch.setattr(
+ "backend.copilot.tools.get_sub_session_result.stream_registry.get_session",
+ no_active_session,
+ )
+
+ r = await GetSubSessionResultTool()._execute(
+ user_id="alice",
+ session=_session("alice"),
+ sub_session_id="inner-7",
+ wait_if_running=30,
+ )
+ assert isinstance(r, SubSessionStatusResponse)
+ assert r.status == "running"
+ assert r.sub_session_id == "inner-7"
+ mock_waiter.result_mock.assert_awaited_once()
+
+ @pytest.mark.asyncio
+ async def test_wait_returns_completed_with_response(self, monkeypatch, mock_waiter):
+ """'completed' outcome surfaces the SessionResult directly."""
+ from backend.copilot.sdk.session_waiter import SessionResult
+
+ sub = MagicMock(user_id="alice", messages=[]) # not terminal-looking
+
+ async def fake_get(_sid):
+ return sub
+
+ async def no_active_session(_sid):
+ return None
+
+ monkeypatch.setattr(
+ "backend.copilot.tools.get_sub_session_result.get_chat_session",
+ fake_get,
+ )
+ monkeypatch.setattr(
+ "backend.copilot.tools.get_sub_session_result.stream_registry.get_session",
+ no_active_session,
+ )
+
+ res = SessionResult()
+ res.response_text = "done"
+ mock_waiter.result_mock.return_value = ("completed", res)
+
+ r = await GetSubSessionResultTool()._execute(
+ user_id="alice",
+ session=_session("alice"),
+ sub_session_id="inner-3",
+ wait_if_running=30,
+ )
+ assert isinstance(r, SubSessionStatusResponse)
+ assert r.status == "completed"
+ assert r.response == "done"
+
+ @pytest.mark.asyncio
+ async def test_already_terminal_skips_waiter(self, monkeypatch, mock_waiter):
+ """If the sub's last message is already terminal AND no turn is
+ in flight, the tool returns 'completed' without ever calling
+ wait_for_session_result — it rebuilds the response from the
+ persisted message instead."""
+ sub = MagicMock(user_id="alice")
+ assistant = MagicMock()
+ assistant.role = "assistant"
+ assistant.content = "already done"
+ assistant.tool_calls = None
+ sub.messages = [assistant]
+
+ async def fake_get(_sid):
+ return sub
+
+ async def no_active_session(_sid):
+ return None
+
+ monkeypatch.setattr(
+ "backend.copilot.tools.get_sub_session_result.get_chat_session",
+ fake_get,
+ )
+ monkeypatch.setattr(
+ "backend.copilot.tools.get_sub_session_result.stream_registry.get_session",
+ no_active_session,
+ )
+
+ r = await GetSubSessionResultTool()._execute(
+ user_id="alice",
+ session=_session("alice"),
+ sub_session_id="inner-9",
+ wait_if_running=30,
+ )
+ assert isinstance(r, SubSessionStatusResponse)
+ assert r.status == "completed"
+ assert r.response == "already done"
+ mock_waiter.result_mock.assert_not_awaited()
+
+ @pytest.mark.asyncio
+ async def test_resume_turn_in_flight_does_not_return_stale(
+ self, monkeypatch, mock_waiter
+ ):
+ """Regression for sentry r3105409601: on a resumed session whose
+ stream_registry status is 'running' (new turn is mid-flight) the
+ tool must NOT short-circuit to the prior turn's terminal message.
+ It subscribes to the stream like a normal running-session poll."""
+ # DB state reflects the PREVIOUS turn's terminal assistant message.
+ prior = MagicMock()
+ prior.role = "assistant"
+ prior.content = "OLD stale result"
+ prior.tool_calls = None
+ sub = MagicMock(user_id="alice", messages=[prior])
+
+ async def fake_get(_sid):
+ return sub
+
+ running_meta = MagicMock(status="running")
+
+ async def active_registry(_sid):
+ return running_meta
+
+ monkeypatch.setattr(
+ "backend.copilot.tools.get_sub_session_result.get_chat_session",
+ fake_get,
+ )
+ monkeypatch.setattr(
+ "backend.copilot.tools.get_sub_session_result.stream_registry.get_session",
+ active_registry,
+ )
+
+ r = await GetSubSessionResultTool()._execute(
+ user_id="alice",
+ session=_session("alice"),
+ sub_session_id="inner-11",
+ wait_if_running=30,
+ )
+ # The waiter must have been awaited — stale short-circuit was skipped.
+ mock_waiter.result_mock.assert_awaited_once()
+ assert isinstance(r, SubSessionStatusResponse)
+ # Default mock_waiter.result_mock.return_value = ("running", SessionResult())
+ assert r.status == "running"
+ # And crucially NOT the stale content.
+ assert r.response is None or r.response == ""
+
+ @pytest.mark.asyncio
+ async def test_cancel_publishes_cancel_event(
+ self, monkeypatch, mock_queue, mock_waiter
+ ):
+ """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", messages=[])
+
+ async def fake_get(_sid):
+ return sub
+
+ monkeypatch.setattr(
+ "backend.copilot.tools.get_sub_session_result.get_chat_session",
+ fake_get,
+ )
+
+ r = await GetSubSessionResultTool()._execute(
+ user_id="alice",
+ session=_session("alice"),
+ sub_session_id="inner-5",
+ cancel=True,
+ )
+ assert isinstance(r, SubSessionStatusResponse)
+ assert r.status == "cancelled"
+ mock_queue["enqueue_cancel"].assert_awaited_once_with("inner-5")
+ mock_waiter.result_mock.assert_not_awaited()
diff --git a/autogpt_platform/backend/backend/copilot/tools/test_dry_run.py b/autogpt_platform/backend/backend/copilot/tools/test_dry_run.py
index 81321fcded..9cf7b17b44 100644
--- a/autogpt_platform/backend/backend/copilot/tools/test_dry_run.py
+++ b/autogpt_platform/backend/backend/copilot/tools/test_dry_run.py
@@ -754,15 +754,15 @@ async def test_run_agent_session_dry_run_overrides_kwargs():
captured_params["dry_run"] = params.dry_run
return {}, None
- with patch(
- "backend.copilot.tools.run_agent.fetch_graph_from_store_slug",
- new_callable=AsyncMock,
- return_value=(graph, None),
- ), patch.object(
- tool, "_check_prerequisites", side_effect=capture_prerequisites
- ), patch.object(
- tool, "_run_agent", new_callable=AsyncMock
- ) as mock_run_agent:
+ with (
+ patch(
+ "backend.copilot.tools.run_agent.fetch_graph_from_store_slug",
+ new_callable=AsyncMock,
+ return_value=(graph, None),
+ ),
+ patch.object(tool, "_check_prerequisites", side_effect=capture_prerequisites),
+ patch.object(tool, "_run_agent", new_callable=AsyncMock) as mock_run_agent,
+ ):
mock_run_agent.return_value = MagicMock()
# Pass dry_run=False in kwargs — session.dry_run=True should win.
@@ -796,15 +796,15 @@ async def test_run_agent_session_dry_run_false_allows_scheduling():
captured_params["dry_run"] = params.dry_run
return {}, None
- with patch(
- "backend.copilot.tools.run_agent.fetch_graph_from_store_slug",
- new_callable=AsyncMock,
- return_value=(graph, None),
- ), patch.object(
- tool, "_check_prerequisites", side_effect=capture_prerequisites
- ), patch.object(
- tool, "_schedule_agent", new_callable=AsyncMock
- ) as mock_schedule:
+ with (
+ patch(
+ "backend.copilot.tools.run_agent.fetch_graph_from_store_slug",
+ new_callable=AsyncMock,
+ return_value=(graph, None),
+ ),
+ patch.object(tool, "_check_prerequisites", side_effect=capture_prerequisites),
+ patch.object(tool, "_schedule_agent", new_callable=AsyncMock) as mock_schedule,
+ ):
mock_schedule.return_value = MagicMock()
await tool._execute(
@@ -840,15 +840,15 @@ async def test_run_agent_session_dry_run_false_allows_llm_dry_run_true():
captured_params["dry_run"] = params.dry_run
return {}, None
- with patch(
- "backend.copilot.tools.run_agent.fetch_graph_from_store_slug",
- new_callable=AsyncMock,
- return_value=(graph, None),
- ), patch.object(
- tool, "_check_prerequisites", side_effect=capture_prerequisites
- ), patch.object(
- tool, "_run_agent", new_callable=AsyncMock
- ) as mock_run_agent:
+ with (
+ patch(
+ "backend.copilot.tools.run_agent.fetch_graph_from_store_slug",
+ new_callable=AsyncMock,
+ return_value=(graph, None),
+ ),
+ patch.object(tool, "_check_prerequisites", side_effect=capture_prerequisites),
+ patch.object(tool, "_run_agent", new_callable=AsyncMock) as mock_run_agent,
+ ):
mock_run_agent.return_value = MagicMock()
# LLM passes dry_run=True; normal session must NOT override it to False
diff --git a/autogpt_platform/backend/backend/copilot/tools/validate_agent.py b/autogpt_platform/backend/backend/copilot/tools/validate_agent.py
index fe329af7b0..401e842204 100644
--- a/autogpt_platform/backend/backend/copilot/tools/validate_agent.py
+++ b/autogpt_platform/backend/backend/copilot/tools/validate_agent.py
@@ -7,6 +7,7 @@ from backend.copilot.model import ChatSession
from .agent_generator.validation import AgentValidator, get_blocks_as_dicts
from .base import BaseTool
+from .helpers import require_guide_read
from .models import ErrorResponse, ToolResponseBase, ValidationResultResponse
logger = logging.getLogger(__name__)
@@ -24,7 +25,8 @@ class ValidateAgentGraphTool(BaseTool):
return (
"Validate agent JSON for correctness: block_ids, links, required fields, "
"type compatibility, nested sink notation, prompt brace escaping, "
- "and AgentExecutorBlock configs. On failure, use fix_agent_graph to auto-fix."
+ "and AgentExecutorBlock configs. On failure, use fix_agent_graph to auto-fix. "
+ "Requires get_agent_building_guide first (refuses otherwise)."
)
@property
@@ -53,6 +55,10 @@ class ValidateAgentGraphTool(BaseTool):
) -> ToolResponseBase:
session_id = session.session_id if session else None
+ guide_gate = require_guide_read(session, "validate_agent_graph")
+ if guide_gate is not None:
+ return guide_gate
+
if not agent_json or not isinstance(agent_json, dict):
return ErrorResponse(
message="Please provide a valid agent JSON object.",
diff --git a/autogpt_platform/frontend/src/app/(platform)/copilot/tools/GenericTool/__tests__/helpers.test.ts b/autogpt_platform/frontend/src/app/(platform)/copilot/tools/GenericTool/__tests__/helpers.test.ts
index 753bc8133a..cc8bcc8afb 100644
--- a/autogpt_platform/frontend/src/app/(platform)/copilot/tools/GenericTool/__tests__/helpers.test.ts
+++ b/autogpt_platform/frontend/src/app/(platform)/copilot/tools/GenericTool/__tests__/helpers.test.ts
@@ -36,6 +36,23 @@ describe("formatToolName", () => {
it("handles already capitalized names", () => {
expect(formatToolName("WebSearch")).toBe("WebSearch");
});
+
+ it("uses friendly display name for sub-AutoPilot tools", () => {
+ expect(formatToolName("run_sub_session")).toBe("Sub-AutoPilot");
+ expect(formatToolName("get_sub_session_result")).toBe(
+ "Sub-AutoPilot result",
+ );
+ });
+
+ it("uses the 'Action' label for run_block (frontend parlance)", () => {
+ expect(formatToolName("run_block")).toBe("Action");
+ });
+
+ it("strips redundant 'run_' prefix for other run_* tools", () => {
+ // "Running Run agent" reads awkwardly — the override produces
+ // "Running Agent".
+ expect(formatToolName("run_agent")).toBe("Agent");
+ });
});
describe("getToolCategory", () => {
diff --git a/autogpt_platform/frontend/src/app/(platform)/copilot/tools/GenericTool/helpers.ts b/autogpt_platform/frontend/src/app/(platform)/copilot/tools/GenericTool/helpers.ts
index 3cdc559522..f0a1cd6853 100644
--- a/autogpt_platform/frontend/src/app/(platform)/copilot/tools/GenericTool/helpers.ts
+++ b/autogpt_platform/frontend/src/app/(platform)/copilot/tools/GenericTool/helpers.ts
@@ -16,8 +16,24 @@ export function extractToolName(part: ToolUIPart): string {
return part.type.replace(/^tool-/, "");
}
+// Specific-case labels for tools whose auto-formatted name reads awkwardly
+// alongside a "Running …" prefix (e.g. avoid "Running Run sub session").
+const TOOL_DISPLAY_NAMES: Record<string, string> = {
+ run_sub_session: "Sub-AutoPilot",
+ get_sub_session_result: "Sub-AutoPilot result",
+ run_agent: "Agent",
+ view_agent_output: "Agent output",
+ run_block: "Action",
+ run_mcp_tool: "MCP tool",
+ get_agent_building_guide: "Agent building guide",
+};
+
export function formatToolName(name: string): string {
- return name.replace(/_/g, " ").replace(/^\w/, (c) => c.toUpperCase());
+ const override = TOOL_DISPLAY_NAMES[name];
+ if (override) return override;
+ // Drop a redundant "run_" prefix so "Running Run agent" → "Running agent".
+ const stripped = name.startsWith("run_") ? name.slice(4) : name;
+ return stripped.replace(/_/g, " ").replace(/^\w/, (c) => c.toUpperCase());
}
/* ------------------------------------------------------------------ */
diff --git a/docs/integrations/block-integrations/misc.md b/docs/integrations/block-integrations/misc.md
index c494903c38..2a7d07402b 100644
--- a/docs/integrations/block-integrations/misc.md
+++ b/docs/integrations/block-integrations/misc.md
@@ -58,7 +58,7 @@ Tool and block identifiers provided in `tools` and `blocks` are validated at run
| system_context | Optional additional context prepended to the prompt. Use this to constrain autopilot behavior, provide domain context, or set output format requirements. | str | 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" \| "connect_integration" \| "continue_run_block" \| "create_agent" \| "create_feature_request" \| "create_folder" \| "customize_agent" \| "delete_folder" \| "delete_workspace_file" \| "edit_agent" \| "find_agent" \| "find_block" \| "find_library_agent" \| "fix_agent_graph" \| "get_agent_building_guide" \| "get_doc_page" \| "get_mcp_guide" \| "list_folders" \| "list_workspace_files" \| "memory_forget_confirm" \| "memory_forget_search" \| "memory_search" \| "memory_store" \| "move_agents_to_folder" \| "move_folder" \| "read_workspace_file" \| "run_agent" \| "run_block" \| "run_mcp_tool" \| "search_docs" \| "search_feature_requests" \| "update_folder" \| "validate_agent_graph" \| "view_agent_output" \| "web_fetch" \| "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" \| "connect_integration" \| "continue_run_block" \| "create_agent" \| "create_feature_request" \| "create_folder" \| "customize_agent" \| "delete_folder" \| "delete_workspace_file" \| "edit_agent" \| "find_agent" \| "find_block" \| "find_library_agent" \| "fix_agent_graph" \| "get_agent_building_guide" \| "get_doc_page" \| "get_mcp_guide" \| "get_sub_session_result" \| "list_folders" \| "list_workspace_files" \| "memory_forget_confirm" \| "memory_forget_search" \| "memory_search" \| "memory_store" \| "move_agents_to_folder" \| "move_folder" \| "read_workspace_file" \| "run_agent" \| "run_block" \| "run_mcp_tool" \| "run_sub_session" \| "search_docs" \| "search_feature_requests" \| "update_folder" \| "validate_agent_graph" \| "view_agent_output" \| "web_fetch" \| "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 |