Skip to content

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

feat(platform/copilot): Agent-Building Mode - compaction-proof guide + automatic engine switch (#13601)

Reinier van der Leerd44962cfdaf7
diff --git a/autogpt_platform/backend/backend/copilot/baseline/engine_switch_exit_test.py b/autogpt_platform/backend/backend/copilot/baseline/engine_switch_exit_test.py
new file mode 100644
index 0000000000..6a70421229
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/baseline/engine_switch_exit_test.py
@@ -0,0 +1,42 @@
+"""Tests for the baseline turn's engine-switch exit behavior.
+
+The tool loop breaks at the iteration boundary when a switch is pending
+(engine_switch.is_pending), and the stream's terminal events tell the
+frontend to flip its mode picker before StreamFinish.
+"""
+
+from backend.copilot import engine_switch
+from backend.copilot.baseline.service import _engine_switch_finish_events
+from backend.copilot.response_model import StreamModeChanged, StreamStatus
+
+
+def _register(session_id: str) -> None:
+ engine_switch.request_switch(session_id, user_id="user-1")
+
+
+def test_no_events_without_pending_switch():
+ assert _engine_switch_finish_events("sess-none") == []
+
+
+def test_pending_switch_emits_mode_change_then_status():
+ _register("sess-exit-1")
+ try:
+ events = _engine_switch_finish_events("sess-exit-1")
+ assert isinstance(events[0], StreamModeChanged)
+ assert events[0].mode == "extended_thinking"
+ assert isinstance(events[1], StreamStatus)
+ assert "Thinking" in events[1].message
+ finally:
+ engine_switch.pop_switch("sess-exit-1")
+
+
+def test_loop_exit_predicate_matches_registry_state():
+ """The tool loop breaks on the same predicate the finish events use —
+ pending after register, cleared after pop."""
+ assert engine_switch.is_pending("sess-exit-2") is False
+ _register("sess-exit-2")
+ try:
+ assert engine_switch.is_pending("sess-exit-2") is True
+ finally:
+ engine_switch.pop_switch("sess-exit-2")
+ assert engine_switch.is_pending("sess-exit-2") is False
diff --git a/autogpt_platform/backend/backend/copilot/baseline/service.py b/autogpt_platform/backend/backend/copilot/baseline/service.py
index 8f9d740755..984bc2ad78 100644
--- a/autogpt_platform/backend/backend/copilot/baseline/service.py
+++ b/autogpt_platform/backend/backend/copilot/baseline/service.py
@@ -28,6 +28,7 @@ from openai.types import CompletionUsage
from openai.types.chat import ChatCompletionMessageParam, ChatCompletionToolParam
from opentelemetry import trace as otel_trace
+from backend.copilot import engine_switch
from backend.copilot.anthropic_rate_card import (
compute_anthropic_cost_usd,
get_max_output_tokens,
@@ -75,8 +76,10 @@ from backend.copilot.response_model import (
StreamError,
StreamFinish,
StreamFinishStep,
+ StreamModeChanged,
StreamStart,
StreamStartStep,
+ StreamStatus,
StreamTextDelta,
StreamTextEnd,
StreamTextStart,
@@ -2126,6 +2129,18 @@ async def stream_chat_completion_baseline(
last_iteration_message=_LAST_ITERATION_HINT,
):
loop_result_holder[0] = loop_result
+ # Engine switch requested (enter_agent_building_mode): end
+ # the loop at this iteration boundary — the round's tool
+ # results are already folded into the conversation, so the
+ # tool-call rows persist and the processor's derived
+ # building-mode signal holds. The processor dispatches the
+ # SDK continuation turn after the slot is released.
+ if engine_switch.is_pending(session_id):
+ logger.info(
+ f"[Baseline] Engine switch pending for "
+ f"{session_id[:12]} — ending tool loop"
+ )
+ break
# Inject any messages the user queued while the turn was
# running. ``tool_call_loop`` mutates ``openai_messages``
# in-place, so appending here means the model sees the new
@@ -2546,4 +2561,21 @@ async def stream_chat_completion_baseline(
cache_creation_tokens=state.turn_cache_creation_tokens,
)
+ for event in _engine_switch_finish_events(session_id):
+ yield event
yield StreamFinish()
+
+
+def _engine_switch_finish_events(session_id: str) -> "list[StreamBaseResponse]":
+ """Terminal events for a turn that registered an engine switch.
+
+ Emitted right before StreamFinish so the frontend flips its mode picker
+ (StreamModeChanged) and narrates the handoff (StreamStatus) exactly once,
+ at the turn boundary where the baseline loop stopped.
+ """
+ if not engine_switch.is_pending(session_id):
+ return []
+ return [
+ StreamModeChanged(mode="extended_thinking"),
+ StreamStatus(message="Switching to Thinking mode for agent building…"),
+ ]
diff --git a/autogpt_platform/backend/backend/copilot/builder_context.py b/autogpt_platform/backend/backend/copilot/builder_context.py
index 19e44fe806..e485d78970 100644
--- a/autogpt_platform/backend/backend/copilot/builder_context.py
+++ b/autogpt_platform/backend/backend/copilot/builder_context.py
@@ -10,6 +10,7 @@ from backend.copilot.model import ChatSession, ChatSessionInfo
from backend.copilot.permissions import CopilotPermissions
from backend.copilot.tools.agent_generator import get_agent_as_json
from backend.copilot.tools.get_agent_building_guide import _load_guide
+from backend.copilot.tools.helpers import session_entered_building_mode
logger = logging.getLogger(__name__)
@@ -178,13 +179,25 @@ def _format_links(
async def build_builder_system_prompt_suffix(session: ChatSession) -> str:
- """Return the cacheable system-prompt suffix for a builder session.
-
- Holds only static content (dispatch guidance + building guide) so the
- bytes are identical across turns AND across sessions for different
- graphs — the live id/name/version ride on the per-turn prefix.
+ """Return the cacheable system-prompt suffix for a building session.
+
+ Two cases include the full agent-building guide in the system prompt so
+ it lives in the cached static prefix instead of the compactable
+ conversation tail:
+
+ - **Builder-bound sessions** additionally get the builder tool/dispatch
+ guidance (existing behaviour).
+ - **Building sessions** — a regular session where the guide was loaded
+ (tool or skill) in a *prior* turn — get the guide alone. Detection is
+ derived from persisted message history, so no session-metadata write
+ is needed and the suffix stays byte-identical across the rest of the
+ session (one prompt-cache re-write when the mode first activates).
+
+ Holds only static content so the bytes are identical across turns AND
+ across sessions — live graph id/name/version ride on the per-turn prefix.
"""
- if not session.metadata.builder_graph_id:
+ is_builder = bool(session.metadata.builder_graph_id)
+ if not is_builder and not session_entered_building_mode(session):
return ""
try:
@@ -195,7 +208,14 @@ async def build_builder_system_prompt_suffix(session: ChatSession) -> str:
# The guide is trusted server-side content (read from disk). We do NOT
# escape it — the LLM needs the raw markdown to make sense of block ids,
- # code fences, and example JSON.
+ # code fences, and example JSON. INVARIANT: _load_guide()'s source must
+ # stay server-controlled; if it ever becomes user- or store-influenced,
+ # escape or sandbox the content before it enters the system prompt.
+ guide_block = (
+ f"<building_guide>\n{_BUILDING_GUIDE_PREAMBLE}\n\n{guide}\n</building_guide>"
+ )
+ if not is_builder:
+ return f"\n\n{guide_block}"
return (
f"\n\n<{BUILDER_SESSION_TAG}>\n"
f"<tool_usage>\n"
@@ -204,11 +224,19 @@ async def build_builder_system_prompt_suffix(session: ChatSession) -> str:
f"<run_agent_dispatch_mode>\n"
f"{_BUILDER_RUN_AGENT_GUIDANCE}\n"
f"</run_agent_dispatch_mode>\n"
- f"<building_guide>\n{guide}\n</building_guide>\n"
+ f"{guide_block}\n"
f"</{BUILDER_SESSION_TAG}>"
)
+_BUILDING_GUIDE_PREAMBLE = (
+ "The complete agent-building guide is included below and stays available "
+ "for the rest of this session — refer to it directly. Do NOT call "
+ 'get_agent_building_guide or read the "agent_building_guide" skill '
+ "again, including after context compaction."
+)
+
+
async def build_builder_context_turn_prefix(
session: ChatSession,
user_id: str | None,
diff --git a/autogpt_platform/backend/backend/copilot/builder_context_test.py b/autogpt_platform/backend/backend/copilot/builder_context_test.py
index ac2547d345..b2afdcdbb5 100644
--- a/autogpt_platform/backend/backend/copilot/builder_context_test.py
+++ b/autogpt_platform/backend/backend/copilot/builder_context_test.py
@@ -21,7 +21,7 @@ from backend.copilot.builder_context import (
build_builder_context_turn_prefix,
build_builder_system_prompt_suffix,
)
-from backend.copilot.model import ChatSession
+from backend.copilot.model import ChatMessage, ChatSession
def _session(
@@ -360,3 +360,63 @@ async def test_turn_prefix_xml_escaping_in_node_names():
# The raw closing tag must never appear inside the block content —
# escaping stops a user-controlled name from breaking out of the block.
assert "&lt;/builder_context&gt;" in block
+
+
+async def test_system_prompt_suffix_for_building_session():
+ """A non-builder session with a prior-turn guide read gets the guide
+ (and only the guide) in the system-prompt suffix."""
+ session = _session(None)
+ session.messages = [
+ ChatMessage(
+ role="assistant",
+ content="",
+ tool_calls=[{"function": {"name": "get_agent_building_guide"}}],
+ )
+ ]
+ with patch(
+ "backend.copilot.builder_context._load_guide",
+ return_value="# Guide body",
+ ):
+ result = await build_builder_system_prompt_suffix(session)
+
+ assert "<building_guide>" in result
+ assert "# Guide body" in result
+ assert "<builder_session>" not in result
+ assert "do not call" in result.lower()
+
+
+async def test_system_prompt_suffix_empty_without_prior_guide_read():
+ session = _session(None)
+ session.messages = [
+ ChatMessage(
+ role="assistant",
+ content="",
+ tool_calls=[{"function": {"name": "find_block"}}],
+ )
+ ]
+ result = await build_builder_system_prompt_suffix(session)
+ assert result == ""
+
+
+async def test_system_prompt_suffix_for_enter_building_mode_call():
+ """The enter_agent_building_mode call (preferred path) also activates
+ the building-session suffix."""
+ session = _session(None)
+ session.messages = [
+ ChatMessage(
+ role="assistant",
+ content="",
+ tool_calls=[{"function": {"name": "enter_agent_building_mode"}}],
+ )
+ ]
+ with patch(
+ "backend.copilot.builder_context._load_guide",
+ return_value="# Guide body",
+ ):
+ result = await build_builder_system_prompt_suffix(session)
+
+ assert "<building_guide>" in result
+ assert "# Guide body" in result
diff --git a/autogpt_platform/backend/backend/copilot/engine_switch.py b/autogpt_platform/backend/backend/copilot/engine_switch.py
new file mode 100644
index 0000000000..848cbead6c
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/engine_switch.py
@@ -0,0 +1,77 @@
+"""In-process registry for baseline→SDK engine switches.
+
+``enter_agent_building_mode``, when called on a baseline turn of an
+SDK-capable deployment, registers the session here. The baseline service
+ends its tool loop at the next iteration boundary; the executor MANAGER —
+in the turn future's done-callback, after the turn thread has fully
+finished (fail-close ran, RMQ message acked, cluster lock released,
+active_tasks cleaned) — pops the entry and dispatches a continuation turn
+on the SDK engine. Dispatching any earlier trips the turn-scoped
+fail-close CAS and the RMQ same-session duplicate rejection.
+
+Process-local by design: registration (baseline service) and consumption
+(manager done-callback) both run inside the same executor process, so the
+dict never needs to cross process boundaries. If the backend restarts
+between registration and dispatch, the continuation is lost, but the
+session still switches engines on the next user message via the
+processor's derived building-mode check — graceful degradation, no
+persistence needed. Entries cannot go stale: every registered turn ends in
+its own done-callback, which pops unconditionally.
+"""
+
+import threading
+
+from pydantic import BaseModel, ConfigDict
+
+# Dispatched as the continuation turn's message with is_user_message=False,
+# so it persists as an assistant row and renders as AutoPilot narration —
+# phrase it in assistant voice (it doubles as the model's continuation
+# prompt; the guide itself arrives via the system prompt). Sibling of the
+# SDK in-turn restart prompt (_BUILDING_MODE_CONTINUATION in sdk/service.py)
+# — keep the two aligned when rewording.
+CONTINUATION_MESSAGE = (
+ "Building mode is active — the agent-building guide is loaded. "
+ "Continuing with the request."
+)
+
+
+class SwitchRequest(BaseModel):
+ """Tenancy context needed to dispatch the continuation turn."""
+
+ model_config = ConfigDict(frozen=True)
+
+ user_id: str
+ organization_id: str | None = None
+ team_id: str | None = None
+
+
+_lock = threading.Lock()
+_pending: dict[str, SwitchRequest] = {}
+
+
+def request_switch(
+ session_id: str,
+ *,
+ user_id: str,
+ organization_id: str | None = None,
+ team_id: str | None = None,
+) -> None:
+ """Register *session_id* for an engine-switch continuation."""
+ with _lock:
+ _pending[session_id] = SwitchRequest(
+ user_id=user_id,
+ organization_id=organization_id,
+ team_id=team_id,
+ )
+
+
+def is_pending(session_id: str) -> bool:
+ """True when a switch is registered for *session_id* (non-consuming)."""
+ with _lock:
+ return session_id in _pending
+
+
+def pop_switch(session_id: str) -> SwitchRequest | None:
+ """Consume the pending switch for *session_id*, or None."""
+ with _lock:
+ return _pending.pop(session_id, None)
diff --git a/autogpt_platform/backend/backend/copilot/executor/manager.py b/autogpt_platform/backend/backend/copilot/executor/manager.py
index 8f1f0281cc..5b790b7d93 100644
--- a/autogpt_platform/backend/backend/copilot/executor/manager.py
+++ b/autogpt_platform/backend/backend/copilot/executor/manager.py
@@ -17,6 +17,8 @@ from pika.exceptions import AMQPChannelError, AMQPConnectionError
from pika.spec import Basic, BasicProperties
from prometheus_client import Gauge, start_http_server
+from backend.copilot import engine_switch
+from backend.copilot.executor.utils import schedule_turn
from backend.data import redis_client as redis
from backend.data.rabbitmq import SyncRabbitMQ
from backend.executor.cluster_lock import ClusterLock
@@ -459,6 +461,7 @@ class CoPilotExecutor(AppProcess):
self._task_locks[session_id].release()
del self._task_locks[session_id]
self._cleanup_completed_tasks()
+ _maybe_dispatch_engine_switch(session_id, error_msg)
future.add_done_callback(on_run_done)
@@ -559,3 +562,112 @@ class CoPilotExecutor(AppProcess):
if self._run_client is None:
self._run_client = SyncRabbitMQ(create_copilot_queue_config())
return self._run_client
+
+
+def _maybe_dispatch_engine_switch(session_id: str, error_msg: str | None) -> None:
+ """Consume a pending engine switch after the turn fully finished.
+
+ Called from the turn future's done-callback: dispatch the SDK
+ continuation only NOW — the turn thread has fully finished (fail-close
+ ran, message acked, cluster lock released, active_tasks cleaned), so
+ neither the fail-close CAS nor the RMQ same-session duplicate rejection
+ can kill the new turn.
+ """
+ switch = engine_switch.pop_switch(session_id)
+ if switch is None:
+ return
+ if error_msg is not None:
+ # Turn failed — the persisted history (and thus the derived
+ # building-mode signal) can't be trusted, so no continuation fires.
+ # Not silent: the session is idle and the user's next message
+ # re-resolves the engine.
+ logger.info(
+ f"Engine-switch continuation for {session_id} not "
+ f"dispatched — turn ended with error: {error_msg}"
+ )
+ return
+ # Dispatch on a dedicated short-lived thread: the async RabbitMQ client
+ # is @thread_cached and loop-bound, so asyncio.run() on this pool thread
+ # would reuse a client created under a previous (now-closed) event loop.
+ # A fresh thread gets a fresh loop AND a fresh thread-cached client, so
+ # nothing crosses loops.
+ threading.Thread(
+ target=_dispatch_engine_switch_continuation,
+ args=(session_id, switch),
+ name=f"engine-switch-{session_id[:8]}",
+ daemon=True,
+ ).start()
+
+
+_SWITCH_DISPATCH_ATTEMPTS = 3
+
+
+def _dispatch_engine_switch_continuation(
+ session_id: str, switch: engine_switch.SwitchRequest
+) -> None:
+ """Dispatch the SDK continuation turn after an engine switch.
+
+ Runs on its own thread with its own event loop so the thread-cached
+ async queue client is created fresh and never reused across loops.
+
+ Best-effort with bounded retry (transient queue/redis blips): if all
+ attempts fail, the session is left idle (not stranded) with a
+ user-visible marker — building mode is derived from persisted message
+ history, so the user's next message still lands on the SDK engine with
+ the guide in the prefix.
+ """
+ for attempt in range(1, _SWITCH_DISPATCH_ATTEMPTS + 1):
+ try:
+ asyncio.run(
+ schedule_turn(
+ session_id=session_id,
+ user_id=switch.user_id,
+ turn_id=str(uuid.uuid4()),
+ message=engine_switch.CONTINUATION_MESSAGE,
+ is_user_message=False,
+ mode="extended_thinking",
+ organization_id=switch.organization_id,
+ team_id=switch.team_id,
+ )
+ )
+ logger.info(f"Dispatched engine-switch continuation for {session_id}")
+ return
+ except Exception as switch_err:
+ logger.error(
+ f"Engine-switch continuation dispatch failed for {session_id} "
+ f"(attempt {attempt}/{_SWITCH_DISPATCH_ATTEMPTS}): {switch_err}"
+ )
+ if attempt < _SWITCH_DISPATCH_ATTEMPTS:
+ time.sleep(attempt)
+ _persist_switch_failure_marker(session_id)
+
+
+def _persist_switch_failure_marker(session_id: str) -> None:
+ """Leave a user-visible error in the session when every dispatch attempt
+ failed — the user was told building continues automatically, so a silent
+ drop would strand them on that promise. Best-effort: building mode
+ itself survives (derived from history), so their next message recovers.
+ """
+ # Lazy imports: manager must stay importable without the model chain.
+ from backend.copilot.constants import COPILOT_ERROR_PREFIX
+ from backend.copilot.model import ChatMessage, append_and_save_message
+
+ try:
+ asyncio.run(
+ append_and_save_message(
+ session_id,
+ ChatMessage(
+ role="assistant",
+ content=(
+ f"{COPILOT_ERROR_PREFIX} Could not start the "
+ "agent-building engine automatically. Building mode "
+ "is still active — send a message to continue."
+ ),
+ ),
+ )
+ )
+ except Exception as marker_err:
+ logger.error(
+ f"Failed to persist engine-switch failure marker for "
+ f"{session_id}: {marker_err}"
+ )
diff --git a/autogpt_platform/backend/backend/copilot/executor/manager_test.py b/autogpt_platform/backend/backend/copilot/executor/manager_test.py
new file mode 100644
index 0000000000..459e2e799f
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/executor/manager_test.py
@@ -0,0 +1,140 @@
+"""Tests for the engine-switch continuation dispatch in the copilot manager.
+
+The dispatch is the handoff between a finished baseline turn and the
+server-initiated SDK continuation turn — the highest-risk link in the
+engine-switch flow (see ``backend.copilot.engine_switch``). These tests
+pin its retry/give-up contract.
+"""
+
+from unittest.mock import AsyncMock, patch
+
+from backend.copilot.engine_switch import CONTINUATION_MESSAGE, SwitchRequest
+
+from .manager import (
+ _SWITCH_DISPATCH_ATTEMPTS,
+ _dispatch_engine_switch_continuation,
+ _maybe_dispatch_engine_switch,
+ _persist_switch_failure_marker,
+)
+
+_SWITCH = SwitchRequest(user_id="user-1", organization_id="org-1", team_id=None)
+
+
+def test_dispatch_succeeds_first_try():
+ with (
+ patch(
+ "backend.copilot.executor.manager.schedule_turn", new_callable=AsyncMock
+ ) as mock_schedule,
+ ):
+ _dispatch_engine_switch_continuation("sess-1", _SWITCH)
+
+ assert mock_schedule.await_count == 1
+ kwargs = mock_schedule.call_args.kwargs
+ assert kwargs["session_id"] == "sess-1"
+ assert kwargs["user_id"] == "user-1"
+ assert kwargs["organization_id"] == "org-1"
+ assert kwargs["message"] == CONTINUATION_MESSAGE
+ assert kwargs["is_user_message"] is False
+ assert kwargs["mode"] == "extended_thinking"
+
+
+def test_dispatch_retries_until_success():
+ with (
+ patch(
+ "backend.copilot.executor.manager.schedule_turn",
+ new_callable=AsyncMock,
+ side_effect=[RuntimeError("rmq down"), RuntimeError("rmq down"), None],
+ ) as mock_schedule,
+ patch("backend.copilot.executor.manager.time.sleep") as mock_sleep,
+ ):
+ _dispatch_engine_switch_continuation("sess-1", _SWITCH)
+
+ assert mock_schedule.await_count == 3
+ assert mock_sleep.call_count == 2
+
+
+def test_dispatch_gives_up_after_bounded_attempts_with_user_visible_marker():
+ with (
+ patch(
+ "backend.copilot.executor.manager.schedule_turn",
+ new_callable=AsyncMock,
+ side_effect=RuntimeError("rmq down"),
+ ) as mock_schedule,
+ patch("backend.copilot.executor.manager.time.sleep"),
+ patch(
+ "backend.copilot.executor.manager._persist_switch_failure_marker"
+ ) as mock_marker,
+ ):
+ _dispatch_engine_switch_continuation("sess-1", _SWITCH)
+
+ assert mock_schedule.await_count == _SWITCH_DISPATCH_ATTEMPTS
+ mock_marker.assert_called_once_with("sess-1")
+
+
+def test_no_failure_marker_on_success():
+ with (
+ patch("backend.copilot.executor.manager.schedule_turn", new_callable=AsyncMock),
+ patch(
+ "backend.copilot.executor.manager._persist_switch_failure_marker"
+ ) as mock_marker,
+ ):
+ _dispatch_engine_switch_continuation("sess-1", _SWITCH)
+
+ mock_marker.assert_not_called()
+
+
+def test_failure_marker_persists_error_row():
+ with patch(
+ "backend.copilot.model.append_and_save_message", new_callable=AsyncMock
+ ) as mock_append:
+ _persist_switch_failure_marker("sess-1")
+
+ assert mock_append.await_count == 1
+ session_id, message = mock_append.call_args.args
+ assert session_id == "sess-1"
+ assert message.role == "assistant"
+ assert "Could not start the agent-building engine" in message.content
+
+
+def test_turn_done_with_pending_switch_dispatches_on_success():
+ with (
+ patch(
+ "backend.copilot.executor.manager.engine_switch.pop_switch",
+ return_value=_SWITCH,
+ ),
+ patch("backend.copilot.executor.manager.threading.Thread") as mock_thread,
+ ):
+ _maybe_dispatch_engine_switch("sess-1", error_msg=None)
+
+ mock_thread.assert_called_once()
+ kwargs = mock_thread.call_args.kwargs
+ assert kwargs["target"] is _dispatch_engine_switch_continuation
+ assert kwargs["args"] == ("sess-1", _SWITCH)
+ mock_thread.return_value.start.assert_called_once()
+
+
+def test_turn_done_with_error_skips_dispatch_but_consumes_switch():
+ with (
+ patch(
+ "backend.copilot.executor.manager.engine_switch.pop_switch",
+ return_value=_SWITCH,
+ ) as mock_pop,
+ patch("backend.copilot.executor.manager.threading.Thread") as mock_thread,
+ ):
+ _maybe_dispatch_engine_switch("sess-1", error_msg="boom")
+
+ mock_pop.assert_called_once_with("sess-1")
+ mock_thread.assert_not_called()
+
+
+def test_turn_done_without_switch_is_noop():
+ with (
+ patch(
+ "backend.copilot.executor.manager.engine_switch.pop_switch",
+ return_value=None,
+ ),
+ patch("backend.copilot.executor.manager.threading.Thread") as mock_thread,
+ ):
+ _maybe_dispatch_engine_switch("sess-1", error_msg=None)
+
+ mock_thread.assert_not_called()
diff --git a/autogpt_platform/backend/backend/copilot/executor/processor.py b/autogpt_platform/backend/backend/copilot/executor/processor.py
index d09d11ceb1..bb2d484791 100644
--- a/autogpt_platform/backend/backend/copilot/executor/processor.py
+++ b/autogpt_platform/backend/backend/copilot/executor/processor.py
@@ -11,6 +11,7 @@ import os
import subprocess
import threading
import time
+from typing import Callable, cast
from backend.copilot import stream_registry
from backend.copilot.baseline import stream_chat_completion_baseline
@@ -189,6 +190,24 @@ async def resolve_use_sdk_for_mode(
_tls = threading.local()
+async def _building_mode_forces_sdk(session_id: str) -> bool:
+ """True when the session's history shows it entered agent-building mode.
+
+ Building-mode sessions are pinned to the SDK engine (guide-in-prompt +
+ in-turn restart live there) regardless of the requested mode — derived
+ from message history, so it survives stale frontend mode pickers.
+ ``get_chat_session`` is Redis-cached: one cache hit, not a DB round-trip.
+ """
+ # Lazy imports: pulling these at module level drags the full tools/model
+ # chain into processor import, which reconfigures logging at import time
+ # and breaks caplog in tests.
+ from backend.copilot.model import get_chat_session
+ from backend.copilot.tools.helpers import session_entered_building_mode
+
+ session = await get_chat_session(session_id)
+ return session is not None and session_entered_building_mode(session)
+
+
def execute_copilot_turn(
entry: CoPilotExecutionEntry,
cancel: threading.Event,
@@ -281,7 +300,7 @@ class CoPilotProcessor:
)
self._prewarm_cli(cli_path=cli_path or None)
- logger.info(f"[CoPilotExecutor] Worker {self.tid} started")
+ logger.info(f"Worker {self.tid} started")
def _prewarm_cli(self, cli_path: str | None = None) -> None:
"""Run the Claude Code CLI binary once to warm OS page caches.
@@ -300,7 +319,13 @@ class CoPilotProcessor:
SubprocessCLITransport,
)
- cli_path = SubprocessCLITransport._find_bundled_cli(None) # type: ignore[arg-type]
+ # _find_bundled_cli is an instance method that never touches
+ # self (pure __file__-based lookup) — safe to call unbound.
+ finder = cast(
+ Callable[[object], str | None],
+ SubprocessCLITransport._find_bundled_cli,
+ )
+ cli_path = finder(None)
if cli_path:
result = subprocess.run(
[cli_path, "-v"],
@@ -308,15 +333,13 @@ class CoPilotProcessor:
timeout=10,
)
if result.returncode == 0:
- logger.info(f"[CoPilotExecutor] CLI pre-warm done: {cli_path}")
+ logger.info(f"CLI pre-warm done: {cli_path}")
else:
logger.warning(
- "[CoPilotExecutor] CLI pre-warm failed (rc=%d): %s",
- result.returncode, # type: ignore[reportCallIssue]
- cli_path,
+ f"CLI pre-warm failed (rc={result.returncode}): {cli_path}"
)
except Exception as e:
- logger.debug(f"[CoPilotExecutor] CLI pre-warm skipped: {e}")
+ logger.debug(f"CLI pre-warm skipped: {e}")
def cleanup(self):
"""Clean up event-loop-bound resources before the loop is destroyed.
@@ -336,14 +359,12 @@ class CoPilotProcessor:
except Exception as e:
coro.close() # Prevent "coroutine was never awaited" warning
error_msg = str(e) or type(e).__name__
- logger.warning(
- f"[CoPilotExecutor] Worker {self.tid} cleanup error: {error_msg}"
- )
+ logger.warning(f"Worker {self.tid} cleanup error: {error_msg}")
# Stop the event loop
self.execution_loop.call_soon_threadsafe(self.execution_loop.stop)
self.execution_thread.join(timeout=5)
- logger.info(f"[CoPilotExecutor] Worker {self.tid} cleaned up")
+ logger.info(f"Worker {self.tid} cleaned up")
@error_logged(swallow=False)
def execute(
@@ -518,6 +539,17 @@ class CoPilotProcessor:
config_default=config.use_claude_agent_sdk,
thinking_available=config.thinking_available,
)
+ # Building-mode sessions are pinned to the SDK engine
+ # (guide-in-prompt + in-turn restart live there). Derived
+ # from message history — survives stale frontend mode
+ # pickers. get_chat_session is Redis-cached, so this is
+ # one cache hit, not a DB round-trip.
+ if not use_sdk and config.thinking_available:
+ if await _building_mode_forces_sdk(entry.session_id):
+ use_sdk = True
+ log.info(
+ "Forcing SDK engine: session is in agent building mode"
+ )
stream_fn = (
sdk_service.stream_chat_completion_sdk
if use_sdk
diff --git a/autogpt_platform/backend/backend/copilot/executor/processor_test.py b/autogpt_platform/backend/backend/copilot/executor/processor_test.py
index 609999f85f..5d88db377a 100644
--- a/autogpt_platform/backend/backend/copilot/executor/processor_test.py
+++ b/autogpt_platform/backend/backend/copilot/executor/processor_test.py
@@ -155,7 +155,11 @@ class TestResolveUseSdkForMode:
)
is False
)
- warnings = [r for r in caplog.records if r.levelname == "WARNING"]
+ # Compare levelno, not levelname: the FancyConsoleFormatter
+ # colorizes record.levelname IN PLACE when a console handler is
+ # installed in the test process, so string comparison breaks
+ # depending on logging-config import order.
+ warnings = [r for r in caplog.records if r.levelno == logging.WARNING]
assert len(warnings) == 1
assert "extended_thinking" in warnings[0].message
@@ -645,3 +649,73 @@ class TestExecuteSafetyNet:
assert finished.wait(timeout=5)
finally:
pool.shutdown(wait=True)
+
+
+class TestBuildingModeForcesSdk:
+ """Engine pinning: a session whose history shows building mode must run
+ on the SDK engine even when the request asked for Fast."""
+
+ @pytest.mark.asyncio
+ async def test_forces_sdk_when_history_shows_building_mode(self):
+ from backend.copilot.executor.processor import _building_mode_forces_sdk
+
+ session = MagicMock()
+ with (
+ patch(
+ "backend.copilot.model.get_chat_session",
+ new=AsyncMock(return_value=session),
+ ),
+ patch(
+ "backend.copilot.tools.helpers.session_entered_building_mode",
+ return_value=True,
+ ),
+ ):
+ assert await _building_mode_forces_sdk("sess-1") is True
+
+ @pytest.mark.asyncio
+ async def test_no_force_without_building_history(self):
+ from backend.copilot.executor.processor import _building_mode_forces_sdk
+
+ session = MagicMock()
+ with (
+ patch(
+ "backend.copilot.model.get_chat_session",
+ new=AsyncMock(return_value=session),
+ ),
+ patch(
+ "backend.copilot.tools.helpers.session_entered_building_mode",
+ return_value=False,
+ ),
+ ):
+ assert await _building_mode_forces_sdk("sess-1") is False
+
+ @pytest.mark.asyncio
+ async def test_missing_session_does_not_force(self):
+ from backend.copilot.executor.processor import _building_mode_forces_sdk
+
+ with patch(
+ "backend.copilot.model.get_chat_session",
+ new=AsyncMock(return_value=None),
+ ):
+ assert await _building_mode_forces_sdk("sess-1") is False
+
+ @pytest.mark.asyncio
+ async def test_real_session_with_enter_call_forces_sdk(self):
+ """End-to-end through the real helper: a real ChatSession whose
+ history carries the enter_agent_building_mode call pins the engine."""
+ from backend.copilot.executor.processor import _building_mode_forces_sdk
+ from backend.copilot.model import ChatMessage, ChatSession
+
+ session = ChatSession.new(user_id="user-1", dry_run=False)
+ session.messages = [
+ ChatMessage(
+ role="assistant",
+ content="",
+ tool_calls=[{"function": {"name": "enter_agent_building_mode"}}],
+ )
+ ]
+ with patch(
+ "backend.copilot.model.get_chat_session",
+ new=AsyncMock(return_value=session),
+ ):
+ assert await _building_mode_forces_sdk(session.session_id) is True
diff --git a/autogpt_platform/backend/backend/copilot/model.py b/autogpt_platform/backend/backend/copilot/model.py
index 1821ef9ba0..6e7da14ebb 100644
--- a/autogpt_platform/backend/backend/copilot/model.py
+++ b/autogpt_platform/backend/backend/copilot/model.py
@@ -309,6 +309,27 @@ class ChatSession(ChatSessionInfo):
# list of argument dicts (one entry per dispatched call).
_inflight_tool_call_args: dict[str, list[dict]] = PrivateAttr(default_factory=dict)
+ guide_in_system_prompt: bool = Field(default=False, exclude=True)
+ """Per-turn runtime flag: True when this turn's system prompt includes the
+ agent-building guide (builder-bound session, or a building session detected
+ from a prior-turn guide read / mode switch). Set by the SDK service at turn
+ start after the system prompt is assembled; never persisted — recomputed
+ every turn. The guide gate and ``get_agent_building_guide`` consult it to
+ skip redundant guide round-trips."""
+
+ sdk_turn_active: bool = Field(default=False, exclude=True)
+ """Per-turn runtime flag: True while the SDK service is running this
+ turn (set at turn start, never persisted). Lets shared tools branch on
+ the execution path — e.g. enter_agent_building_mode restarts in-turn on
+ SDK but degrades gracefully on the baseline path."""
+
+ building_mode_requested: bool = Field(default=False, exclude=True)
+ """Per-turn runtime flag set by ``enter_agent_building_mode``: asks the
+ SDK service to restart the in-flight attempt with the agent-building
+ guide in the system prompt. Cleared by the restart handler; never
+ persisted — the durable mode signal is the tool call in message
+ history."""
+
@classmethod
def new(
cls,
diff --git a/autogpt_platform/backend/backend/copilot/permissions.py b/autogpt_platform/backend/backend/copilot/permissions.py
index 3581d8ca8b..b22d1d5f43 100644
--- a/autogpt_platform/backend/backend/copilot/permissions.py
+++ b/autogpt_platform/backend/backend/copilot/permissions.py
@@ -88,6 +88,7 @@ ToolName = Literal[
"delete_skill",
"delete_workspace_file",
"edit_agent",
+ "enter_agent_building_mode",
"find_agent",
"find_block",
"find_library_agent",
diff --git a/autogpt_platform/backend/backend/copilot/response_model.py b/autogpt_platform/backend/backend/copilot/response_model.py
index b93e9aa2af..b2a835b2ee 100644
--- a/autogpt_platform/backend/backend/copilot/response_model.py
+++ b/autogpt_platform/backend/backend/copilot/response_model.py
@@ -8,7 +8,7 @@ See: https://ai-sdk.dev/docs/ai-sdk-ui/stream-protocol
import json
import logging
from enum import Enum
-from typing import Any
+from typing import Any, Literal
from pydantic import BaseModel, Field
@@ -61,6 +61,7 @@ class ResponseType(str, Enum):
# buffer at a tool boundary. Lets the client promote queued chips to
# bubbles immediately instead of waiting for its backstop poll.
PENDING_DRAINED = "data-pending-drained"
+ MODE_CHANGED = "data-mode-changed"
class StreamBaseResponse(BaseModel):
@@ -336,6 +337,28 @@ class StreamCursor(StreamBaseResponse):
return f"data: {json.dumps(data)}\n\n"
+class StreamModeChanged(StreamBaseResponse):
+ """The backend switched the session's engine/mode server-side.
+
+ Emitted when a baseline turn registers an engine switch (agent building
+ mode) so the frontend can sync its Thinking/Fast mode picker to the
+ engine the session will actually run on.
+ """
+
+ type: ResponseType = ResponseType.MODE_CHANGED
+ mode: Literal["extended_thinking", "fast"] = Field(
+ ..., description="New effective mode"
+ )
+
+ def to_sse(self) -> str:
+ """Emit as an AI SDK v5 data part."""
+ data = {
+ "type": self.type.value,
+ "data": {"mode": self.mode},
+ }
+ return f"data: {json.dumps(data)}\n\n"
+
+
class StreamStatus(StreamBaseResponse):
"""Transient status notification shown to the user during long operations.
diff --git a/autogpt_platform/backend/backend/copilot/response_model_test.py b/autogpt_platform/backend/backend/copilot/response_model_test.py
new file mode 100644
index 0000000000..07837d5717
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/response_model_test.py
@@ -0,0 +1,17 @@
+"""Tests for SSE serialization of copilot stream events."""
+
+import json
+
+from backend.copilot.response_model import StreamModeChanged
+
+
+def test_mode_changed_serializes_as_ai_sdk_data_part():
+ """The frontend reads ``dataPart.data.mode`` — mode must be nested under
+ ``data``, not serialized as a top-level sibling of ``type``."""
+ sse = StreamModeChanged(mode="extended_thinking").to_sse()
+ assert sse.startswith("data: ")
+ payload = json.loads(sse[len("data: ") :])
+ assert payload == {
+ "type": "data-mode-changed",
+ "data": {"mode": "extended_thinking"},
+ }
diff --git a/autogpt_platform/backend/backend/copilot/sdk/building_mode_restart_test.py b/autogpt_platform/backend/backend/copilot/sdk/building_mode_restart_test.py
new file mode 100644
index 0000000000..60c804f7c1
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/sdk/building_mode_restart_test.py
@@ -0,0 +1,141 @@
+"""Tests for the building-mode restart boundary gate.
+
+``enter_agent_building_mode`` on an SDK turn requests an in-turn restart
+with the guide in the system prompt. The restart may only fire at a clean
+message boundary — interrupting mid-tool-call would strand ``tool_use``
+blocks without results and leave the CLI session file unresumable.
+"""
+
+from unittest.mock import MagicMock
+
+import pytest
+
+from backend.copilot.model import ChatSession
+
+from .service import _ready_for_building_mode_restart
+
+
+def _session(*, requested: bool = True, guide_loaded: bool = False) -> ChatSession:
+ session = ChatSession.new(user_id="user-1", dry_run=False)
+ session.building_mode_requested = requested
+ session.guide_in_system_prompt = guide_loaded
+ return session
+
+
+def _adapter(*, unresolved: bool) -> MagicMock:
+ adapter = MagicMock()
+ adapter.has_unresolved_tool_calls = unresolved
+ return adapter
+
+
+def test_fires_at_clean_boundary():
+ assert (
+ _ready_for_building_mode_restart(_session(), _adapter(unresolved=False)) is True
+ )
+
+
+def test_must_not_fire_mid_tool_call():
+ assert (
+ _ready_for_building_mode_restart(_session(), _adapter(unresolved=True)) is False
+ )
+
+
+def test_noop_without_request():
+ assert (
+ _ready_for_building_mode_restart(
+ _session(requested=False), _adapter(unresolved=False)
+ )
+ is False
+ )
+
+
+def test_noop_once_guide_already_loaded():
+ assert (
+ _ready_for_building_mode_restart(
+ _session(guide_loaded=True), _adapter(unresolved=False)
+ )
+ is False
+ )
+
+
+class TestApplyBuildingModeRestart:
+ """Execution tests for the restart application: prompt rebuild, resume
+ wiring, flag transitions, and adapter carry-over."""
+
+ def _state(self, *, prior_emitted: bool, thinking_reprompted: bool):
+ state = MagicMock()
+ state.thinking_only_reprompted = thinking_reprompted
+ state.adapter = MagicMock()
+ state.adapter.emitted_real_content_to_wire = prior_emitted
+ return state
+
+ async def _run(
+ self,
+ mocker,
+ *,
+ suffix: str = "\n\n<building_guide>GUIDE</building_guide>",
+ prior_emitted: bool = False,
+ thinking_reprompted: bool = False,
+ ):
+ from backend.copilot.sdk.service import (
+ _BUILDING_MODE_CONTINUATION,
+ _apply_building_mode_restart,
+ )
+
+ mocker.patch(
+ "backend.copilot.sdk.service.build_builder_system_prompt_suffix",
+ new=mocker.AsyncMock(return_value=suffix),
+ )
+ session = _session(requested=True, guide_loaded=False)
+ state = self._state(
+ prior_emitted=prior_emitted, thinking_reprompted=thinking_reprompted
+ )
+ sdk_options = MagicMock()
+ status = await _apply_building_mode_restart(
+ session=session,
+ state=state,
+ sdk_options=sdk_options,
+ base_system_prompt="BASE",
+ graphiti_supplement="",
+ use_e2b=False,
+ session_id="sess-1",
+ message_id="msg-1",
+ log_prefix="[test]",
+ )
+ return session, state, status, _BUILDING_MODE_CONTINUATION
+
+ @pytest.mark.asyncio
+ async def test_flags_resume_and_prompt_wiring(self, mocker):
+ session, state, status, continuation = await self._run(mocker)
+
+ assert session.building_mode_requested is False
+ assert session.guide_in_system_prompt is True
+ assert state.options.resume == "sess-1"
+ assert state.options.session_id is None
+ assert state.use_resume is True
+ assert state.resume_file == "sess-1"
+ assert state.query_message == continuation
+ assert "building mode" in status.message.lower()
+
+ @pytest.mark.asyncio
+ async def test_empty_suffix_degrades_without_prompt_upgrade(self, mocker):
+ session, state, _, _ = await self._run(mocker, suffix="")
+
+ assert session.building_mode_requested is False
+ assert session.guide_in_system_prompt is False
+ # The restart still proceeds — resume wiring is unconditional.
+ assert state.use_resume is True
+
+ @pytest.mark.asyncio
+ async def test_adapter_carry_over(self, mocker):
+ _, state, _, _ = await self._run(
+ mocker, prior_emitted=True, thinking_reprompted=True
+ )
+ assert state.adapter.thinking_only_reprompted is True
+ assert state.adapter.prior_attempt_emitted_visible_content is True
+
+ @pytest.mark.asyncio
+ async def test_no_carry_over_without_prior_content(self, mocker):
+ _, state, _, _ = await self._run(mocker)
+ assert state.adapter.thinking_only_reprompted is False
+ assert state.adapter.prior_attempt_emitted_visible_content is False
diff --git a/autogpt_platform/backend/backend/copilot/sdk/service.py b/autogpt_platform/backend/backend/copilot/sdk/service.py
index 27347045bb..9a44eef195 100644
--- a/autogpt_platform/backend/backend/copilot/sdk/service.py
+++ b/autogpt_platform/backend/backend/copilot/sdk/service.py
@@ -101,6 +101,7 @@ from ..response_model import (
StreamFinish,
StreamFinishStep,
StreamHeartbeat,
+ StreamModeChanged,
StreamReasoningDelta,
StreamReasoningEnd,
StreamReasoningStart,
@@ -808,10 +809,39 @@ async def _consume_sdk_until_done(
loop_state.last_flush_time = now
loop_state.msgs_since_flush = 0
+ # --- Building-mode switch (enter_agent_building_mode) ---
+ # Restart the attempt with the guide in the system prompt.
+ if _ready_for_building_mode_restart(ctx.session, state.adapter):
+ logger.info(
+ f"{ctx.log_prefix} Building mode requested — interrupting "
+ f"for prompt upgrade"
+ )
+ try:
+ await client.interrupt()
+ except Exception as exc:
+ # Best-effort: client close in the caller's finally is the
+ # fallback shutdown path (same as transient retries).
+ logger.warning(
+ f"{ctx.log_prefix} Interrupt for building-mode restart "
+ f"failed: {exc}"
+ )
+ raise _BuildingModeRestart()
+
if acc.stream_completed:
break
+# Continuation query sent when relaunching an attempt after the
+# building-mode switch — the CLI session already holds the original user
+# message and all partial work, so this only needs to orient the model.
+# Sibling of the baseline engine-switch continuation prompt
+# (engine_switch.CONTINUATION_MESSAGE) — keep the two aligned when rewording.
+_BUILDING_MODE_CONTINUATION = (
+ "Building mode is now active — the complete agent-building guide is in "
+ "your system prompt (<building_guide>) and survives context compaction. "
+ "Continue working on the user's request from where you left off."
+)
+
# Synthetic message injected when a turn ends with extended thinking but no
# visible TextBlock. Bounded to one re-prompt per turn — if the model still
# returns thinking-only the adapter promotes the last thinking block to
@@ -1504,6 +1534,89 @@ class _InterruptedAttempt:
return events
+async def _apply_building_mode_restart(
+ *,
+ session: "ChatSession",
+ state: "_RetryState",
+ sdk_options: "ClaudeAgentOptions",
+ base_system_prompt: str,
+ graphiti_supplement: str,
+ use_e2b: bool,
+ session_id: str,
+ message_id: str,
+ log_prefix: str,
+) -> StreamStatus:
+ """Reconfigure *state* to relaunch the attempt with the guide in the
+ system prompt, returning the status event to yield.
+
+ Not an error, not a rollback — everything produced so far stands, so the
+ fresh adapter only carries over the transient-retry flags. Detection
+ cannot re-fire: guide_in_system_prompt flips True on success,
+ building_mode_requested flips False either way.
+ """
+ session.building_mode_requested = False
+ building_suffix = await build_builder_system_prompt_suffix(session)
+ session.guide_in_system_prompt = bool(building_suffix)
+ if not building_suffix:
+ logger.error(
+ f"{log_prefix} Building-mode restart: guide suffix "
+ f"empty — continuing without prompt upgrade"
+ )
+ system_prompt = (
+ base_system_prompt
+ + get_sdk_supplement(use_e2b=use_e2b)
+ + graphiti_supplement
+ + building_suffix
+ )
+ sdk_options_restart = copy(sdk_options)
+ sdk_options_restart.system_prompt = _build_system_prompt_value(
+ system_prompt,
+ cross_user_cache=config.claude_agent_cross_user_prompt_cache,
+ )
+ # Resume the CLI session the interrupted run was writing —
+ # spike-verified: --resume accepts a changed append and the
+ # new content is live on the resumed turn.
+ sdk_options_restart.resume = session_id
+ sdk_options_restart.session_id = None
+ state.options = sdk_options_restart
+ state.use_resume = True
+ state.resume_file = session_id
+ state.query_message = _BUILDING_MODE_CONTINUATION
+ # Fresh adapter, same carry-over rules as a transient retry.
+ # NOTE: the transcript builder is NOT restored — its partial
+ # entries are real; the relaunched run's `append_user` adds
+ # the original message once more, which only surfaces in the
+ # rare CLI-file-loss fallback path (cosmetic duplicate).
+ prior_adapter = state.adapter
+ state.adapter = SDKResponseAdapter(
+ message_id=message_id,
+ session_id=session_id,
+ render_reasoning_in_ui=config.render_reasoning_in_ui,
+ )
+ state.adapter.thinking_only_reprompted = state.thinking_only_reprompted
+ if prior_adapter.emitted_real_content_to_wire:
+ state.adapter.prior_attempt_emitted_visible_content = True
+ return StreamStatus(message="Entering building mode — loading the agent guide…")
+
+
+def _ready_for_building_mode_restart(
+ session: "ChatSession",
+ adapter: "SDKResponseAdapter",
+) -> bool:
+ """True when the attempt may restart for the building-mode prompt upgrade.
+
+ Requires a clean message boundary — no unresolved tool calls — so the
+ CLI session file is orphan-free and cleanly resumable; firing mid-tool-
+ call would strand ``tool_use`` blocks without results. No-op once the
+ guide is already in the system prompt (restart already happened).
+ """
+ return (
+ session.building_mode_requested
+ and not session.guide_in_system_prompt
+ and not adapter.has_unresolved_tool_calls
+ )
+
+
def _flush_orphan_tool_uses_to_session(
session: "ChatSession | None",
state: "_RetryState | None",
@@ -3161,6 +3274,17 @@ def _dispatch_response(
return response
+class _BuildingModeRestart(Exception):
+ """Raised by ``_consume_sdk_until_done`` when ``enter_agent_building_mode``
+ was called: the outer loop relaunches this attempt with the agent-building
+ guide in the system prompt (``--resume`` on the same CLI session).
+
+ NOT an error and NOT a rollback — everything the attempt produced so far
+ (tool calls, results, text) stands, in the client stream, the session
+ history, and the CLI session file.
+ """
+
+
class _HandledStreamError(Exception):
"""Raised by `_run_stream_attempt` when an attempt fails and the outer
retry loop must roll back session state.
@@ -4071,6 +4195,11 @@ async def stream_chat_completion_sdk( # pyright: ignore[reportGeneralTypeIssues
# prompt cache keeps the ~20KB guide warm for the whole session.
# Empty string for non-builder sessions preserves cross-user caching.
builder_session_suffix = await build_builder_system_prompt_suffix(session)
+ # Per-turn runtime flag (never persisted): lets the guide gate and
+ # get_agent_building_guide skip redundant guide round-trips when the
+ # guide is already in this turn's cached system prompt.
+ session.sdk_turn_active = True
+ session.guide_in_system_prompt = bool(builder_session_suffix)
system_prompt = (
base_system_prompt
+ get_sdk_supplement(use_e2b=use_e2b)
@@ -4087,6 +4216,13 @@ async def stream_chat_completion_sdk( # pyright: ignore[reportGeneralTypeIssues
yield StreamStart(messageId=message_id, sessionId=session_id)
+ if mode == "fast":
+ # The request asked for Fast but this turn runs on the SDK
+ # engine (building-mode pin or engine-switch continuation).
+ # Tell stale pickers — a client that missed the original
+ # data-mode-changed (reload, second tab) re-syncs here.
+ yield StreamModeChanged(mode="extended_thinking")
+
set_execution_context(
user_id,
session,
@@ -4113,9 +4249,16 @@ async def stream_chat_completion_sdk( # pyright: ignore[reportGeneralTypeIssues
# hiding is meant to eliminate (CLI returns "Permission to use ...
# has been denied", which the model narrates as a fake Allow/Deny
# prompt).
- hidden_tools = _hidden_short_names_for_permissions(
- permissions
- ) | tool_names_in_groups(disabled_tool_groups)
+ # get_agent_building_guide is redundant on the SDK path —
+ # enter_agent_building_mode puts the same guide compaction-proof
+ # into the system prompt. Hiding it removes the tempting-but-worse
+ # fallback; read_skill("agent_building_guide") remains as escape
+ # hatch. The baseline path (no prompt machinery) keeps the tool.
+ hidden_tools = (
+ _hidden_short_names_for_permissions(permissions)
+ | tool_names_in_groups(disabled_tool_groups)
+ | {"get_agent_building_guide"}
+ )
mcp_server = create_copilot_mcp_server(
use_e2b=use_e2b, hidden_tool_names=hidden_tools
)
@@ -4721,6 +4864,26 @@ async def stream_chat_completion_sdk( # pyright: ignore[reportGeneralTypeIssues
_MAX_STREAM_ATTEMPTS,
)
raise
+ except _BuildingModeRestart:
+ # enter_agent_building_mode: relaunch this attempt with the
+ # agent-building guide in the system prompt. Not an error,
+ # not a rollback — everything produced so far stands (client
+ # stream, session history, CLI session file), so no
+ # interrupted.capture / snapshot restore here. Detection
+ # cannot re-fire: guide_in_system_prompt flips True on
+ # success, building_mode_requested flips False either way.
+ yield await _apply_building_mode_restart(
+ session=session,
+ state=state,
+ sdk_options=sdk_options,
+ base_system_prompt=base_system_prompt,
+ graphiti_supplement=graphiti_supplement,
+ use_e2b=use_e2b,
+ session_id=session_id,
+ message_id=message_id,
+ log_prefix=log_prefix,
+ )
+ continue
except _HandledStreamError as exc:
# _run_stream_attempt already yielded a StreamError and
# appended an error marker. We only need to rollback
diff --git a/autogpt_platform/backend/backend/copilot/stream_registry.py b/autogpt_platform/backend/backend/copilot/stream_registry.py
index 74b516e661..54e5a1e224 100644
--- a/autogpt_platform/backend/backend/copilot/stream_registry.py
+++ b/autogpt_platform/backend/backend/copilot/stream_registry.py
@@ -47,6 +47,7 @@ from .response_model import (
StreamFinish,
StreamFinishStep,
StreamHeartbeat,
+ StreamModeChanged,
StreamPendingDrained,
StreamReasoningDelta,
StreamReasoningEnd,
@@ -1169,6 +1170,7 @@ def _reconstruct_chunk(chunk_data: dict) -> StreamBaseResponse | None:
ResponseType.STATUS.value: StreamStatus,
ResponseType.DREAM_OPERATIONS.value: StreamDreamOperations,
ResponseType.PENDING_DRAINED.value: StreamPendingDrained,
+ ResponseType.MODE_CHANGED.value: StreamModeChanged,
}
chunk_type = chunk_data.get("type")
diff --git a/autogpt_platform/backend/backend/copilot/stream_registry_test.py b/autogpt_platform/backend/backend/copilot/stream_registry_test.py
index d259472f3a..7f19eae38a 100644
--- a/autogpt_platform/backend/backend/copilot/stream_registry_test.py
+++ b/autogpt_platform/backend/backend/copilot/stream_registry_test.py
@@ -534,3 +534,17 @@ def test_reconstruct_chunk_round_trips_pending_drained():
assert isinstance(chunk, StreamPendingDrained)
assert chunk.drainedCount == 3
+
+
+def test_reconstruct_mode_changed_chunk():
+ """Regression: MODE_CHANGED was missing from the reconstruction map, so
+ the picker-sync event was silently dropped after the Redis stream."""
+ from backend.copilot.response_model import StreamModeChanged
+ from backend.copilot.stream_registry import _reconstruct_chunk
+
+ chunk = _reconstruct_chunk(
+ {"type": "data-mode-changed", "mode": "extended_thinking"}
+ )
+ assert isinstance(chunk, StreamModeChanged)
+ assert chunk.mode == "extended_thinking"
+ assert '"data"' in chunk.to_sse()
diff --git a/autogpt_platform/backend/backend/copilot/tools/__init__.py b/autogpt_platform/backend/backend/copilot/tools/__init__.py
index 258bba3da7..be19067cd5 100644
--- a/autogpt_platform/backend/backend/copilot/tools/__init__.py
+++ b/autogpt_platform/backend/backend/copilot/tools/__init__.py
@@ -20,6 +20,7 @@ from .create_agent import CreateAgentTool
from .customize_agent import CustomizeAgentTool
from .decompose_goal import DecomposeGoalTool
from .edit_agent import EditAgentTool
+from .enter_building_mode import EnterAgentBuildingModeTool
from .feature_requests import CreateFeatureRequestTool, SearchFeatureRequestsTool
from .find_agent import FindAgentTool
from .find_block import FindBlockTool
@@ -117,6 +118,7 @@ TOOL_REGISTRY: dict[str, BaseTool] = {
"view_agent_output": AgentOutputTool(),
"search_docs": SearchDocsTool(),
"get_doc_page": GetDocPageTool(),
+ "enter_agent_building_mode": EnterAgentBuildingModeTool(),
"get_agent_building_guide": GetAgentBuildingGuideTool(),
# Skills (self-distilled procedure registry; see tools/skills.py).
# Defaults seed the agent-building / MCP guides so the registry is
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
index 1270332f00..bbc5ba5ad4 100644
--- a/autogpt_platform/backend/backend/copilot/tools/agent_guide_gate_test.py
+++ b/autogpt_platform/backend/backend/copilot/tools/agent_guide_gate_test.py
@@ -319,3 +319,43 @@ def test_announce_inflight_captures_dict_arguments():
session.announce_inflight_tool_call("read_skill", {"name": "mcp_tool_guide"})
args = session.get_inflight_tool_call_args("read_skill")
assert args == [{"name": "mcp_tool_guide"}]
+
+
+def test_guide_in_system_prompt_flag_gate_passes():
+ """When this turn's system prompt carries the guide (building session),
+ the gate passes without any guide tool call in history."""
+ session = _session_with_messages([])
+ session.guide_in_system_prompt = True
+ assert require_guide_read(session, "create_agent") is None
+
+
+def _enter_call_message() -> ChatMessage:
+ return ChatMessage(
+ role="assistant",
+ content="",
+ tool_calls=[{"function": {"name": "enter_agent_building_mode"}}],
+ )
+
+
+def test_pending_switch_tells_model_to_end_turn(mocker):
+ """Baseline turn on an SDK-capable deployment: the enter call registers
+ an engine switch; further build tools must wait for the continuation."""
+ mocker.patch(
+ "backend.copilot.tools.helpers.chat_config",
+ mocker.MagicMock(transport=mocker.MagicMock(supports_sdk=True)),
+ )
+ session = _session_with_messages([_enter_call_message()])
+ result = require_guide_read(session, "create_agent")
+ assert isinstance(result, ErrorResponse)
+ assert "engine switch is pending" in result.message
+
+
+def test_enter_call_satisfies_gate_on_sdk_less_deployment(mocker):
+ """Without SDK support the enter tool served the guide inline — the
+ gate must pass instead of stranding the model."""
+ mocker.patch(
+ "backend.copilot.tools.helpers.chat_config",
+ mocker.MagicMock(transport=mocker.MagicMock(supports_sdk=False)),
+ )
+ session = _session_with_messages([_enter_call_message()])
+ assert require_guide_read(session, "create_agent") is None
diff --git a/autogpt_platform/backend/backend/copilot/tools/enter_building_mode.py b/autogpt_platform/backend/backend/copilot/tools/enter_building_mode.py
new file mode 100644
index 0000000000..fea2cba19c
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/tools/enter_building_mode.py
@@ -0,0 +1,118 @@
+"""EnterAgentBuildingModeTool - switches the session into building mode.
+
+Building mode moves the agent-building guide into the (prompt-cached) system
+prompt, where it survives context compaction — instead of living in the
+conversation as a ~9K-token tool result that every compaction evicts and the
+model then re-fetches. On the SDK path, calling this tool triggers an
+in-turn restart with the upgraded system prompt (see
+``_BuildingModeRestart`` in ``backend.copilot.sdk.service``); the tool call
+itself, persisted in message history, is the durable mode signal for all
+later turns.
+"""
+
+from typing import Any
+
+from backend.copilot import engine_switch
+from backend.copilot.model import ChatSession
+from backend.copilot.sdk.env import config as chat_config
+
+from .base import BaseTool
+from .get_agent_building_guide import load_guide_for_user
+from .models import ResponseType, ToolResponseBase
+
+
+class BuildingModeResponse(ToolResponseBase):
+ """Response for enter_agent_building_mode."""
+
+ # Reuses AGENT_BUILDER_GUIDE for all branches (status strings AND the
+ # SDK-less inline guide) so every frontend/history consumer that already
+ # renders guide responses handles this tool uniformly.
+ type: ResponseType = ResponseType.AGENT_BUILDER_GUIDE
+ content: str = ""
+
+
+class EnterAgentBuildingModeTool(BaseTool):
+ """Switches the session into agent-building mode."""
+
+ @property
+ def name(self) -> str:
+ return "enter_agent_building_mode"
+
+ @property
+ def description(self) -> str:
+ return (
+ "Enter agent-building mode: loads the building guide into "
+ "your system prompt, compaction-proof. Call BEFORE "
+ "designing or building an agent."
+ )
+
+ @property
+ def parameters(self) -> dict[str, Any]:
+ return {"type": "object", "properties": {}, "required": []}
+
+ @property
+ def requires_auth(self) -> bool:
+ return False
+
+ async def _execute(
+ self,
+ user_id: str | None,
+ session: ChatSession,
+ **kwargs,
+ ) -> ToolResponseBase:
+ session_id = session.session_id
+ if session.guide_in_system_prompt:
+ return BuildingModeResponse(
+ message="Building mode is already active.",
+ content=(
+ "Building mode is already active — the agent-building "
+ "guide is in your system prompt (see <building_guide>)."
+ ),
+ session_id=session_id,
+ )
+ if session.sdk_turn_active:
+ session.building_mode_requested = True
+ return BuildingModeResponse(
+ message="Entering agent building mode…",
+ content=(
+ "Building mode requested. Your context is being upgraded "
+ "— the complete agent-building guide will appear in your "
+ "system prompt as <building_guide> momentarily. Continue "
+ "with the user's request once it arrives; do NOT call "
+ "get_agent_building_guide."
+ ),
+ session_id=session_id,
+ )
+ if chat_config.transport.supports_sdk:
+ # Baseline turn on an SDK-capable deployment: register the
+ # switch — the baseline loop ends this turn at the next
+ # iteration boundary and the processor dispatches an SDK
+ # continuation turn. The tool call in message history also
+ # pins all later turns to SDK (resolve_use_sdk_for_mode).
+ engine_switch.request_switch(
+ session_id,
+ # The session owner is the authoritative identity — the
+ # tool-level user_id param is Optional only because
+ # BaseTool serves unauthenticated tools too.
+ user_id=session.user_id,
+ organization_id=session.organization_id,
+ team_id=session.team_id,
+ )
+ return BuildingModeResponse(
+ message="Switching to the agent-building engine…",
+ content=(
+ "Building mode registered — this turn ends now and the "
+ "session switches to the agent-building engine, with "
+ "the building guide loaded. Building continues "
+ "automatically; do not call any more tools."
+ ),
+ session_id=session_id,
+ )
+ # SDK-less deployment (local LLM): no engine to switch to — degrade
+ # to serving the guide inline, exactly like get_agent_building_guide.
+ content = await load_guide_for_user(user_id)
+ return BuildingModeResponse(
+ message="Agent building guide loaded.",
+ content=content,
+ session_id=session_id,
+ )
diff --git a/autogpt_platform/backend/backend/copilot/tools/fix_agent.py b/autogpt_platform/backend/backend/copilot/tools/fix_agent.py
index bc2ed1c3a9..965d769fa8 100644
--- a/autogpt_platform/backend/backend/copilot/tools/fix_agent.py
+++ b/autogpt_platform/backend/backend/copilot/tools/fix_agent.py
@@ -23,11 +23,10 @@ class FixAgentGraphTool(BaseTool):
@property
def description(self) -> str:
return (
- "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. "
- "Requires get_agent_building_guide first (refuses otherwise)."
+ "Auto-fix common agent JSON issues (invalid UUIDs, brace "
+ "escaping, block prerequisites, credentials, model defaults, "
+ "type mismatches). Returns fixed JSON + fixes applied. "
+ "Requires the building guide first (refuses otherwise)."
)
@property
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 3d263a7930..1609747759 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
@@ -50,10 +50,9 @@ class GetAgentBuildingGuideTool(BaseTool):
@property
def description(self) -> str:
return (
- "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."
+ "Returns the agent JSON building guide (incl. dry-run loop) "
+ "inline. Fallback — prefer enter_agent_building_mode "
+ "(compaction-proof)."
)
@property
@@ -75,17 +74,22 @@ class GetAgentBuildingGuideTool(BaseTool):
**kwargs, # no tool-specific params; accepts kwargs for forward-compat
) -> ToolResponseBase:
session_id = session.session_id if session else None
- try:
- content = _load_guide()
- triggers_enabled = (
- await is_feature_enabled(
- Flag.GENERIC_TRIGGER_AGENTS, user_id, default=False
- )
- if user_id
- else False
+ if session is not None and session.guide_in_system_prompt:
+ # The guide already rides in this turn's (cached) system prompt —
+ # returning it again would duplicate ~9K tokens in the
+ # compactable conversation tail.
+ return AgentBuildingGuideResponse(
+ message="Agent building guide already loaded.",
+ content=(
+ "The complete agent-building guide is already included in "
+ "your system prompt (see <building_guide>). Refer to it "
+ "directly — it stays available for the rest of this "
+ "session, including after context compaction."
+ ),
+ session_id=session_id,
)
- if not triggers_enabled:
- content = _strip_h3_section(content, _TRIGGER_AGENTS_HEADING)
+ try:
+ content = await load_guide_for_user(user_id)
return AgentBuildingGuideResponse(
message="Agent building guide loaded.",
content=content,
@@ -121,3 +125,21 @@ def _strip_h3_section(guide: str, heading: str) -> str:
if not skipping:
out.append(line)
return "\n".join(out)
+
+
+async def load_guide_for_user(user_id: str | None) -> str:
+ """Load the guide with per-user feature gating applied.
+
+ Shared by get_agent_building_guide and enter_agent_building_mode (its
+ SDK-less inline fallback) so the trigger-section gating and heading
+ sentinel cannot drift between the two.
+ """
+ content = _load_guide()
+ triggers_enabled = (
+ await is_feature_enabled(Flag.GENERIC_TRIGGER_AGENTS, user_id, default=False)
+ if user_id
+ else False
+ )
+ if not triggers_enabled:
+ content = _strip_h3_section(content, _TRIGGER_AGENTS_HEADING)
+ return content
diff --git a/autogpt_platform/backend/backend/copilot/tools/get_agent_building_guide_test.py b/autogpt_platform/backend/backend/copilot/tools/get_agent_building_guide_test.py
index e22ea45398..950486771f 100644
--- a/autogpt_platform/backend/backend/copilot/tools/get_agent_building_guide_test.py
+++ b/autogpt_platform/backend/backend/copilot/tools/get_agent_building_guide_test.py
@@ -3,8 +3,10 @@
import pytest
from backend.copilot.model import ChatSession
+from backend.copilot.tools.enter_building_mode import BuildingModeResponse
from backend.copilot.tools.get_agent_building_guide import (
_TRIGGER_AGENTS_HEADING,
+ AgentBuildingGuideResponse,
GetAgentBuildingGuideTool,
_load_guide,
_strip_h3_section,
@@ -98,8 +100,9 @@ async def test_guide_includes_trigger_section_when_flag_enabled(mocker):
)
tool = GetAgentBuildingGuideTool()
result = await tool._execute(user_id="user-1", session=_make_session())
+ assert isinstance(result, AgentBuildingGuideResponse)
assert result.type == ResponseType.AGENT_BUILDER_GUIDE
- assert "Building Trigger Agents" in result.content # type: ignore[attr-defined]
+ assert "Building Trigger Agents" in result.content
@pytest.mark.asyncio
@@ -110,10 +113,11 @@ async def test_guide_strips_trigger_section_when_flag_disabled(mocker):
)
tool = GetAgentBuildingGuideTool()
result = await tool._execute(user_id="user-1", session=_make_session())
+ assert isinstance(result, AgentBuildingGuideResponse)
assert result.type == ResponseType.AGENT_BUILDER_GUIDE
- assert "Building Trigger Agents" not in result.content # type: ignore[attr-defined]
+ assert "Building Trigger Agents" not in result.content
# Pre-trigger content (e.g. block-ID examples) must still be present.
- assert "AgentExecutorBlock" in result.content # type: ignore[attr-defined]
+ assert "AgentExecutorBlock" in result.content
@pytest.mark.asyncio
@@ -127,5 +131,167 @@ async def test_guide_strips_trigger_section_when_no_user_id(mocker):
)
tool = GetAgentBuildingGuideTool()
result = await tool._execute(user_id=None, session=_make_session())
- assert "Building Trigger Agents" not in result.content # type: ignore[attr-defined]
+ assert isinstance(result, AgentBuildingGuideResponse)
+ assert "Building Trigger Agents" not in result.content
spy.assert_not_called()
+
+
+async def test_guide_stubbed_when_already_in_system_prompt():
+ """Building sessions carry the guide in the cached system prompt — the
+ tool returns a pointer instead of duplicating ~9K tokens in context."""
+ tool = GetAgentBuildingGuideTool()
+ session = _make_session()
+ session.guide_in_system_prompt = True
+
+ result = await tool._execute(user_id="user-1", session=session)
+ assert isinstance(result, AgentBuildingGuideResponse)
+
+ assert result.type == ResponseType.AGENT_BUILDER_GUIDE
+ assert "system prompt" in result.content
+ assert len(result.content) < 500
+
+
+async def test_guide_returned_in_full_without_flag(mocker):
+ mocker.patch(
+ "backend.copilot.tools.get_agent_building_guide.is_feature_enabled",
+ new=mocker.AsyncMock(return_value=True),
+ )
+ tool = GetAgentBuildingGuideTool()
+ session = _make_session()
+
+ result = await tool._execute(user_id="user-1", session=session)
+ assert isinstance(result, AgentBuildingGuideResponse)
+
+ assert result.type == ResponseType.AGENT_BUILDER_GUIDE
+ assert len(result.content) > 10_000
+
+
+async def test_enter_building_mode_sets_request_flag():
+ from backend.copilot.tools.enter_building_mode import EnterAgentBuildingModeTool
+
+ tool = EnterAgentBuildingModeTool()
+ session = _make_session()
+ session.sdk_turn_active = True
+
+ result = await tool._execute(user_id="user-1", session=session)
+ assert isinstance(result, BuildingModeResponse)
+
+ assert session.building_mode_requested is True
+ assert "upgraded" in result.content
+
+
+async def test_enter_building_mode_noop_when_already_active():
+ from backend.copilot.tools.enter_building_mode import EnterAgentBuildingModeTool
+
+ tool = EnterAgentBuildingModeTool()
+ session = _make_session()
+ session.guide_in_system_prompt = True
+
+ result = await tool._execute(user_id="user-1", session=session)
+ assert isinstance(result, BuildingModeResponse)
+
+ assert session.building_mode_requested is False
+ assert "already active" in result.content
+
+
+def test_enter_building_mode_available_on_baseline():
+ """enter_agent_building_mode is offered on the baseline path too — it
+ branches per path (SDK restart / engine switch / inline guide on
+ SDK-less deployments)."""
+ from backend.copilot.tools import get_available_tools
+
+ names = {t["function"]["name"] for t in get_available_tools()}
+ assert "enter_agent_building_mode" in names
+ assert "get_agent_building_guide" in names
+
+
+async def test_enter_building_mode_baseline_switch_message(mocker):
+ """Baseline turn + SDK-capable deployment: tool registers the switch and
+ instructs the model to end its turn."""
+ from unittest.mock import MagicMock
+
+ from backend.copilot.tools.enter_building_mode import EnterAgentBuildingModeTool
+
+ mocker.patch(
+ "backend.copilot.tools.enter_building_mode.chat_config",
+ MagicMock(transport=MagicMock(supports_sdk=True)),
+ )
+ tool = EnterAgentBuildingModeTool()
+ session = _make_session()
+
+ result = await tool._execute(user_id="user-1", session=session)
+ assert isinstance(result, BuildingModeResponse)
+
+ assert session.building_mode_requested is False
+ assert "switches to the agent-building engine" in result.content
+
+
+async def test_enter_building_mode_local_degrades_to_guide(mocker):
+ """SDK-less deployment: tool serves the full guide inline."""
+ from unittest.mock import MagicMock
+
+ from backend.copilot.tools.enter_building_mode import EnterAgentBuildingModeTool
+
+ mocker.patch(
+ "backend.copilot.tools.enter_building_mode.chat_config",
+ MagicMock(transport=MagicMock(supports_sdk=False)),
+ )
+ mocker.patch(
+ "backend.copilot.tools.get_agent_building_guide.is_feature_enabled",
+ new=mocker.AsyncMock(return_value=True),
+ )
+ tool = EnterAgentBuildingModeTool()
+ session = _make_session()
+
+ result = await tool._execute(user_id="user-1", session=session)
+ assert isinstance(result, BuildingModeResponse)
+
+ assert len(result.content) > 10_000
+
+
+async def test_enter_building_mode_sdk_turn_requests_restart():
+ from backend.copilot.tools.enter_building_mode import EnterAgentBuildingModeTool
+
+ tool = EnterAgentBuildingModeTool()
+ session = _make_session()
+ session.sdk_turn_active = True
+
+ result = await tool._execute(user_id="user-1", session=session)
+ assert isinstance(result, BuildingModeResponse)
+
+ assert session.building_mode_requested is True
+ assert "upgraded" in result.content
+
+
+async def test_enter_building_mode_baseline_registers_engine_switch(mocker):
+ from unittest.mock import MagicMock
+
+ from backend.copilot import engine_switch
+ from backend.copilot.tools.enter_building_mode import EnterAgentBuildingModeTool
+
+ mocker.patch(
+ "backend.copilot.tools.enter_building_mode.chat_config",
+ MagicMock(transport=MagicMock(supports_sdk=True)),
+ )
+ tool = EnterAgentBuildingModeTool()
+ session = _make_session()
+ session.organization_id = "org-9"
+ session.team_id = "team-9"
+
+ await tool._execute(user_id="user-1", session=session)
+
+ switch = engine_switch.pop_switch(session.session_id)
+ assert switch is not None and switch.user_id == "user-1"
+ # Full tenancy tuple must be captured — a dropped org/team would break
+ # continuations for org users and only surface as a dispatch refusal.
+ assert switch.organization_id == "org-9"
+ assert switch.team_id == "team-9"
+ assert engine_switch.pop_switch(session.session_id) is None # pop-once
diff --git a/autogpt_platform/backend/backend/copilot/tools/helpers.py b/autogpt_platform/backend/backend/copilot/tools/helpers.py
index 3ac0bebf32..f21e60ca83 100644
--- a/autogpt_platform/backend/backend/copilot/tools/helpers.py
+++ b/autogpt_platform/backend/backend/copilot/tools/helpers.py
@@ -19,6 +19,7 @@ from backend.copilot.constants import (
MAX_TOOL_WAIT_SECONDS,
)
from backend.copilot.model import ChatSession
+from backend.copilot.sdk.env import config as chat_config
from backend.copilot.sdk.file_ref import FileRefExpansionError, expand_file_refs_in_args
from backend.data.credit import UsageTransactionMetadata
from backend.data.db_accessors import credit_db, review_db, user_db, workspace_db
@@ -927,6 +928,36 @@ _AGENT_GUIDE_TOOL_NAME = "get_agent_building_guide"
_AGENT_GUIDE_SKILL_NAME = "agent_building_guide"
+_ENTER_BUILDING_MODE_TOOL_NAME = "enter_agent_building_mode"
+
+
+def session_entered_building_mode(session: ChatSession) -> bool:
+ """True when this session is in agent-building mode.
+
+ Any of these signals counts: an ``enter_agent_building_mode`` call
+ (preferred path), a ``get_agent_building_guide`` call, or a
+ ``read_skill(name="agent_building_guide")`` call. All are durable —
+ derived from message history, no session-metadata write needed. Called
+ at turn start (by the system-prompt builder) this reflects prior turns
+ only; called mid-turn (by the building-mode restart) it also sees the
+ current turn's in-flight calls.
+ """
+ return session.has_tool_been_called(
+ _ENTER_BUILDING_MODE_TOOL_NAME
+ ) or session_read_building_guide(session)
+
+
+def session_read_building_guide(session: ChatSession) -> bool:
+ """True when the agent-building guide was loaded in this session.
+
+ Accepts either the ``get_agent_building_guide`` tool call or a
+ ``read_skill(name="agent_building_guide")`` call.
+ """
+ return session.has_tool_been_called(
+ _AGENT_GUIDE_TOOL_NAME
+ ) or _read_skill_called_for(session, _AGENT_GUIDE_SKILL_NAME)
+
+
def _read_skill_called_for(session: ChatSession, skill_name: str) -> bool:
"""Return True iff the model has called ``read_skill(name=skill_name)``
in this session (durable history or current-turn in-flight calls).
@@ -999,16 +1030,34 @@ def require_guide_read(session: ChatSession, tool_name: str):
# requiring one would waste a round-trip every turn.
if session.metadata.builder_graph_id:
return None
- if session.has_tool_been_called(_AGENT_GUIDE_TOOL_NAME):
+ # Building sessions get the guide in the (cached) system prompt — see
+ # ``build_builder_system_prompt_suffix``.
+ if session.guide_in_system_prompt:
return None
- if _read_skill_called_for(session, _AGENT_GUIDE_SKILL_NAME):
+ if session_read_building_guide(session):
return None
+ if session.has_tool_been_called(_ENTER_BUILDING_MODE_TOOL_NAME):
+ if not chat_config.transport.supports_sdk:
+ # SDK-less deployment: the enter tool served the guide inline.
+ return None
+ return ErrorResponse(
+ message=(
+ "The engine switch is pending — building continues "
+ "automatically on the next turn with the guide loaded. End "
+ f"your turn now with a brief note; do not retry {tool_name} "
+ "in this turn."
+ ),
+ session_id=session.session_id,
+ )
return ErrorResponse(
message=(
- 'Call get_agent_building_guide (or read_skill(name="agent_building_guide")) '
- f"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."
+ f"Call enter_agent_building_mode first, then retry {tool_name}. "
+ "It loads the agent-building guide into your system prompt where "
+ "it survives context compaction. (get_agent_building_guide or "
+ 'read_skill(name="agent_building_guide") also satisfy this gate.) '
+ "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/frontend/src/app/(platform)/copilot/__tests__/autopilot-mode-switch.test.tsx b/autogpt_platform/frontend/src/app/(platform)/copilot/__tests__/autopilot-mode-switch.test.tsx
new file mode 100644
index 0000000000..4c8cf0a60f
--- /dev/null
+++ b/autogpt_platform/frontend/src/app/(platform)/copilot/__tests__/autopilot-mode-switch.test.tsx
@@ -0,0 +1,175 @@
+import { server } from "@/mocks/mock-server";
+import {
+ copilotResumeHandler,
+ copilotStreamHandler,
+} from "@/tests/integrations/copilot-sse";
+import { screen, waitFor } from "@testing-library/react";
+import type { UIMessageChunk } from "ai";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { resetCopilotChatRegistry } from "../copilotChatRegistry";
+import { useCopilotUIStore } from "../store";
+import {
+ renderHost,
+ sessionHandler,
+ TEST_BACKEND_BASE_URL,
+ TEST_SESSION_ID,
+ typeAndSend,
+} from "./sse-helpers";
+
+vi.mock("@/services/environment", async (importActual) => {
+ const actual = await importActual<typeof import("@/services/environment")>();
+ return {
+ ...actual,
+ environment: {
+ ...actual.environment,
+ getAGPTServerBaseUrl: () => TEST_BACKEND_BASE_URL,
+ },
+ };
+});
+
+vi.mock("../helpers", async (importActual) => {
+ const actual = await importActual<typeof import("../helpers")>();
+ return {
+ ...actual,
+ getCopilotAuthHeaders: async () => ({ "x-test-auth": "yes" }),
+ };
+});
+
+vi.mock("@/lib/supabase/hooks/useSupabase", () => ({
+ useSupabase: () => ({ isUserLoading: false, isLoggedIn: true }),
+}));
+
+vi.mock("@/services/feature-flags/use-get-flag", () => ({
+ Flag: {
+ ARTIFACTS: "ARTIFACTS",
+ CHAT_MODE_OPTION: "CHAT_MODE_OPTION",
+ ENABLE_PLATFORM_PAYMENT: "ENABLE_PLATFORM_PAYMENT",
+ },
+ useGetFlag: () => false,
+}));
+
+beforeEach(() => {
+ resetCopilotChatRegistry();
+ useCopilotUIStore.getState().setCopilotChatMode("fast");
+ useCopilotUIStore.getState().clearCopilotModePin();
+});
+
+afterEach(() => {
+ resetCopilotChatRegistry();
+});
+
+describe("AutoPilot streaming — server-initiated engine switch", () => {
+ it("flips the chat mode when the stream emits data-mode-changed", async () => {
+ server.use(
+ copilotStreamHandler({
+ baseUrl: TEST_BACKEND_BASE_URL,
+ sessionId: TEST_SESSION_ID,
+ chunks: [
+ { type: "start", messageId: "msg-1" },
+ { type: "text-start", id: "t1" },
+ { type: "text-delta", id: "t1", delta: "Switching to Thinking…" },
+ { type: "text-end", id: "t1" },
+ {
+ type: "data-mode-changed",
+ data: { mode: "extended_thinking" },
+ } as unknown as UIMessageChunk,
+ { type: "finish" },
+ ],
+ }),
+ );
+
+ renderHost();
+ await typeAndSend("build me an agent");
+
+ await waitFor(
+ () => {
+ expect(useCopilotUIStore.getState().copilotChatMode).toBe(
+ "extended_thinking",
+ );
+ },
+ { timeout: 5000 },
+ );
+ // Session-scoped pin: the toggle locks, and the user's persisted
+ // default must NOT have been rewritten by the server-forced switch.
+ expect(useCopilotUIStore.getState().copilotModePinned).toBe(true);
+ });
+
+ it("keeps the selected mode on streams without a mode change", async () => {
+ server.use(
+ copilotStreamHandler({
+ baseUrl: TEST_BACKEND_BASE_URL,
+ sessionId: TEST_SESSION_ID,
+ chunks: [
+ { type: "start", messageId: "msg-1" },
+ { type: "text-start", id: "t1" },
+ { type: "text-delta", id: "t1", delta: "Hi." },
+ { type: "text-end", id: "t1" },
+ { type: "finish" },
+ ],
+ }),
+ );
+
+ renderHost();
+ await typeAndSend("hi");
+
+ await waitFor(() => {
+ expect(useCopilotUIStore.getState().copilotChatMode).toBe("fast");
+ });
+ expect(useCopilotUIStore.getState().copilotModePinned).toBe(false);
+ });
+});
+
+describe("AutoPilot streaming — continuation reconnect probe", () => {
+ it("probes after a mode-switch turn and attaches the server-dispatched continuation", async () => {
+ server.use(
+ copilotStreamHandler({
+ baseUrl: TEST_BACKEND_BASE_URL,
+ sessionId: TEST_SESSION_ID,
+ chunks: [
+ { type: "start", messageId: "msg-1" },
+ { type: "text-start", id: "t1" },
+ { type: "text-delta", id: "t1", delta: "Switching to Thinking…" },
+ { type: "text-end", id: "t1" },
+ {
+ type: "data-mode-changed",
+ data: { mode: "extended_thinking" },
+ } as unknown as UIMessageChunk,
+ { type: "finish" },
+ ],
+ }),
+ copilotResumeHandler({
+ baseUrl: TEST_BACKEND_BASE_URL,
+ sessionId: TEST_SESSION_ID,
+ chunks: [
+ { type: "start", messageId: "msg-2" },
+ { type: "text-start", id: "t2" },
+ { type: "text-delta", id: "t2", delta: "Continuing the build." },
+ { type: "text-end", id: "t2" },
+ { type: "finish" },
+ ],
+ }),
+ );
+
+ renderHost();
+ await typeAndSend("build me an agent");
+ expect(await screen.findByText("Switching to Thinking…")).toBeDefined();
+
+ // The continuation turn registers its stream server-side; the probe's
+ // session refetch (armed by data-mode-changed, up to 8×500ms) must see
+ // it and reconnect via the GET resume route.
+ server.use(
+ sessionHandler({
+ active_stream: {
+ turn_id: "turn-2",
+ last_message_id: "msg-2",
+ },
+ }),
+ );
+
+ expect(
+ await screen.findByText("Continuing the build.", undefined, {
+ timeout: 8000,
+ }),
+ ).toBeDefined();
+ }, 15000);
+});
diff --git a/autogpt_platform/frontend/src/app/(platform)/copilot/__tests__/copilotChatRegistry.test.ts b/autogpt_platform/frontend/src/app/(platform)/copilot/__tests__/copilotChatRegistry.test.ts
new file mode 100644
index 0000000000..7579198c6e
--- /dev/null
+++ b/autogpt_platform/frontend/src/app/(platform)/copilot/__tests__/copilotChatRegistry.test.ts
@@ -0,0 +1,75 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("@ai-sdk/react", () => ({
+ Chat: vi.fn().mockImplementation(function (
+ this: { options: unknown },
+ options: unknown,
+ ) {
+ this.options = options;
+ }),
+}));
+
+vi.mock("../copilotStreamTransport", () => ({
+ createCopilotTransport: vi.fn(() => ({})),
+}));
+
+import { Chat } from "@ai-sdk/react";
+import {
+ getOrCreateCopilotChatRuntime,
+ resetCopilotChatRegistry,
+} from "../copilotChatRegistry";
+
+const mockChat = vi.mocked(Chat);
+
+function chatOptions() {
+ const call = mockChat.mock.calls.at(-1);
+ if (!call) throw new Error("Chat was not constructed");
+ return call[0] as {
+ onData?: (dataPart: { type: string; data?: unknown }) => void;
+ };
+}
+
+describe("copilotChatRegistry onData wiring", () => {
+ beforeEach(() => {
+ resetCopilotChatRegistry();
+ mockChat.mockClear();
+ });
+
+ it("forwards chat data parts to the registered handler", () => {
+ const runtime = getOrCreateCopilotChatRuntime("s1");
+ const handler = vi.fn();
+ runtime.onData = handler;
+
+ const part = { type: "data-mode-changed", data: { mode: "fast" } };
+ chatOptions().onData?.(part);
+
+ expect(handler).toHaveBeenCalledWith(part);
+ expect(runtime.onData).toBe(handler);
+ });
+
+ it("ignores data parts when no handler is registered", () => {
+ getOrCreateCopilotChatRuntime("s1");
+ expect(() =>
+ chatOptions().onData?.({ type: "data-mode-changed" }),
+ ).not.toThrow();
+ });
+
+ it("stops forwarding after the handler is cleared", () => {
+ const runtime = getOrCreateCopilotChatRuntime("s1");
+ const handler = vi.fn();
+ runtime.onData = handler;
+ runtime.onData = undefined;
+
+ chatOptions().onData?.({ type: "data-mode-changed" });
+
+ expect(handler).not.toHaveBeenCalled();
+ expect(runtime.onData).toBeUndefined();
+ });
+
+ it("reuses the runtime (and its handler slot) per session", () => {
+ const first = getOrCreateCopilotChatRuntime("s1");
+ const second = getOrCreateCopilotChatRuntime("s1");
+ expect(second).toBe(first);
+ expect(mockChat).toHaveBeenCalledTimes(1);
+ });
+});
diff --git a/autogpt_platform/frontend/src/app/(platform)/copilot/__tests__/helpers.test.ts b/autogpt_platform/frontend/src/app/(platform)/copilot/__tests__/helpers.test.ts
index bd579fd4d7..f27516d3f5 100644
--- a/autogpt_platform/frontend/src/app/(platform)/copilot/__tests__/helpers.test.ts
+++ b/autogpt_platform/frontend/src/app/(platform)/copilot/__tests__/helpers.test.ts
@@ -10,6 +10,7 @@ import {
getCopilotAuthHeaders,
getSendSuppressionReason,
parseSessionIDs,
+ resolveModeChangedMode,
resolveSessionDryRun,
shouldDebounceReconnect,
shouldSuppressDuplicateSend,
@@ -681,3 +682,39 @@ describe("getCopilotAuthHeaders", () => {
);
});
});
+
+describe("resolveModeChangedMode", () => {
+ it("returns the mode for a data-mode-changed part with a known mode", () => {
+ expect(
+ resolveModeChangedMode({
+ type: "data-mode-changed",
+ data: { mode: "extended_thinking" },
+ }),
+ ).toBe("extended_thinking");
+ expect(
+ resolveModeChangedMode({
+ type: "data-mode-changed",
+ data: { mode: "fast" },
+ }),
+ ).toBe("fast");
+ });
+
+ it("returns null for other data part types", () => {
+ expect(
+ resolveModeChangedMode({ type: "data-status", data: { mode: "fast" } }),
+ ).toBeNull();
+ });
+
+ it("returns null for unknown or missing modes", () => {
+ expect(
+ resolveModeChangedMode({
+ type: "data-mode-changed",
+ data: { mode: "turbo" },
+ }),
+ ).toBeNull();
+ expect(resolveModeChangedMode({ type: "data-mode-changed" })).toBeNull();
+ expect(
+ resolveModeChangedMode({ type: "data-mode-changed", data: "fast" }),
+ ).toBeNull();
+ });
+});
diff --git a/autogpt_platform/frontend/src/app/(platform)/copilot/components/ChatInput/ChatInput.tsx b/autogpt_platform/frontend/src/app/(platform)/copilot/components/ChatInput/ChatInput.tsx
index 3dce192ae1..c20bc12a27 100644
--- a/autogpt_platform/frontend/src/app/(platform)/copilot/components/ChatInput/ChatInput.tsx
+++ b/autogpt_platform/frontend/src/app/(platform)/copilot/components/ChatInput/ChatInput.tsx
@@ -78,6 +78,7 @@ export function ChatInput({
}: Props) {
const {
copilotChatMode,
+ copilotModePinned,
setCopilotChatMode,
copilotLlmModel,
setCopilotLlmModel,
@@ -91,6 +92,14 @@ export function ChatInput({
const [isPickerOpen, setIsPickerOpen] = useState(false);
function handleToggleMode() {
+ if (copilotModePinned) {
+ toast({
+ title: "Mode is locked while building an agent",
+ description:
+ "This session switched to Extended Thinking for agent building — building sessions stay on that engine.",
+ });
+ return;
+ }
const next =
copilotChatMode === "extended_thinking" ? "fast" : "extended_thinking";
setCopilotChatMode(next);
@@ -317,6 +326,7 @@ export function ChatInput({
<ModeToggleButton
mode={copilotChatMode}
onToggle={handleToggleMode}
+ pinned={copilotModePinned}
/>
)}
{showModeToggle && !isStreaming && (
diff --git a/autogpt_platform/frontend/src/app/(platform)/copilot/components/ChatInput/__tests__/ChatInput.test.tsx b/autogpt_platform/frontend/src/app/(platform)/copilot/components/ChatInput/__tests__/ChatInput.test.tsx
index a270859204..648f69f519 100644
--- a/autogpt_platform/frontend/src/app/(platform)/copilot/components/ChatInput/__tests__/ChatInput.test.tsx
+++ b/autogpt_platform/frontend/src/app/(platform)/copilot/components/ChatInput/__tests__/ChatInput.test.tsx
@@ -23,6 +23,7 @@ vi.mock("@/app/api/__generated__/endpoints/chat/chat", () => ({
}));
let mockCopilotMode = "extended_thinking";
+let mockCopilotModePinned = false;
const mockSetCopilotChatMode = vi.fn((mode: string) => {
mockCopilotMode = mode;
});
@@ -43,6 +44,7 @@ vi.mock("@/app/(platform)/copilot/store", () => ({
setCopilotMode: mockSetCopilotChatMode,
copilotChatMode: mockCopilotMode,
setCopilotChatMode: mockSetCopilotChatMode,
+ copilotModePinned: mockCopilotModePinned,
copilotLlmModel: mockCopilotLlmModel,
setCopilotLlmModel: mockSetCopilotLlmModel,
isDryRun: false,
@@ -226,6 +228,18 @@ describe("ChatInput mode toggle", () => {
expect(screen.getByText("Fast")).toBeDefined();
});
+ it("keeps the mode locked while pinned (building mode)", () => {
+ mockFlagValue = true;
+ mockCopilotMode = "extended_thinking";
+ mockCopilotModePinned = true;
+ render(<ChatInput onSend={mockOnSend} />);
+ const button = screen.getByLabelText(/mode locked to extended thinking/i);
+ expect(button.getAttribute("aria-disabled")).toBe("true");
+ fireEvent.click(button);
+ expect(mockSetCopilotChatMode).not.toHaveBeenCalled();
+ mockCopilotModePinned = false;
+ });
+
it("toggles from extended_thinking to fast on click", () => {
mockFlagValue = true;
mockCopilotMode = "extended_thinking";
diff --git a/autogpt_platform/frontend/src/app/(platform)/copilot/components/ChatInput/components/ModeToggleButton.tsx b/autogpt_platform/frontend/src/app/(platform)/copilot/components/ChatInput/components/ModeToggleButton.tsx
index 144e131d61..53f2e3f697 100644
--- a/autogpt_platform/frontend/src/app/(platform)/copilot/components/ChatInput/components/ModeToggleButton.tsx
+++ b/autogpt_platform/frontend/src/app/(platform)/copilot/components/ChatInput/components/ModeToggleButton.tsx
@@ -1,7 +1,7 @@
"use client";
import { cn } from "@/lib/utils";
-import { Brain, Lightning } from "@phosphor-icons/react";
+import { Brain, Lightning, Lock } from "@phosphor-icons/react";
import {
Tooltip,
TooltipContent,
@@ -12,14 +12,17 @@ import type { CopilotMode } from "../../../store";
interface Props {
mode: CopilotMode;
onToggle: () => void;
+ pinned?: boolean;
}
-export function ModeToggleButton({ mode, onToggle }: Props) {
+export function ModeToggleButton({ mode, onToggle, pinned = false }: Props) {
const isExtended = mode === "extended_thinking";
- const tooltipText = isExtended
- ? "Extended Thinking — deeper reasoning (click to switch to Fast)"
- : "Fast mode — quicker responses (click to switch to Thinking)";
+ const tooltipText = pinned
+ ? "Locked to Extended Thinking — building sessions stay on this engine"
+ : isExtended
+ ? "Extended Thinking — deeper reasoning (click to switch to Fast)"
+ : "Fast mode — quicker responses (click to switch to Thinking)";
return (
<Tooltip>
@@ -27,18 +30,27 @@ export function ModeToggleButton({ mode, onToggle }: Props) {
<button
type="button"
aria-pressed={isExtended}
+ aria-disabled={pinned}
onClick={onToggle}
className={cn(
"ml-2 inline-flex h-9 min-w-[6rem] items-center justify-center gap-1 rounded-full border border-neutral-200 bg-white px-2.5 text-xs font-medium shadow-sm transition-colors hover:bg-neutral-50",
isExtended ? "text-purple-500" : "text-orange-600",
+ pinned && "cursor-not-allowed opacity-70 hover:bg-white",
)}
aria-label={
- isExtended
- ? "Switch to Fast mode"
- : "Switch to Extended Thinking mode"
+ pinned
+ ? "Mode locked to Extended Thinking while building an agent"
+ : isExtended
+ ? "Switch to Fast mode"
+ : "Switch to Extended Thinking mode"
}
>
- {isExtended ? (
+ {pinned ? (
+ <>
+ <Lock size={14} />
+ Thinking
+ </>
+ ) : isExtended ? (
<>
<Brain size={14} />
Thinking
diff --git a/autogpt_platform/frontend/src/app/(platform)/copilot/copilotChatRegistry.ts b/autogpt_platform/frontend/src/app/(platform)/copilot/copilotChatRegistry.ts
index 9156bdf2cb..e2650dd970 100644
--- a/autogpt_platform/frontend/src/app/(platform)/copilot/copilotChatRegistry.ts
+++ b/autogpt_platform/frontend/src/app/(platform)/copilot/copilotChatRegistry.ts
@@ -18,6 +18,7 @@ interface CopilotChatRuntime {
isAbort?: boolean;
}) => void | Promise<void>;
onError?: (error: Error) => void;
+ onData?: (dataPart: { type: string; data?: unknown }) => void;
}
interface CopilotChatRuntimeStore {
@@ -78,7 +79,8 @@ export function getOrCreateCopilotChatRuntime(sessionId: string) {
const copilotModelRef: MutableValue<CopilotLlmModel | undefined> = {
current: undefined,
};
- const callbacks: Pick<CopilotChatRuntime, "onFinish" | "onError"> = {};
+ const callbacks: Pick<CopilotChatRuntime, "onFinish" | "onError" | "onData"> =
+ {};
const chat = new Chat<UIMessage>({
id: sessionId,
transport: createCopilotTransport({
@@ -98,11 +100,20 @@ export function getOrCreateCopilotChatRuntime(sessionId: string) {
}
return callbacks.onError?.(error);
},
+ onData: (dataPart) => {
+ callbacks.onData?.(dataPart);
+ },
});
const runtime = {
chat,
copilotModeRef,
copilotModelRef,
+ get onData() {
+ return callbacks.onData;
+ },
+ set onData(value: CopilotChatRuntime["onData"]) {
+ callbacks.onData = value;
+ },
get onFinish() {
return callbacks.onFinish;
},
diff --git a/autogpt_platform/frontend/src/app/(platform)/copilot/helpers.ts b/autogpt_platform/frontend/src/app/(platform)/copilot/helpers.ts
index ae6ad1f65c..2b1a4c1f01 100644
--- a/autogpt_platform/frontend/src/app/(platform)/copilot/helpers.ts
+++ b/autogpt_platform/frontend/src/app/(platform)/copilot/helpers.ts
@@ -399,3 +399,12 @@ export function deduplicateMessages(messages: UIMessage[]): UIMessage[] {
return true;
});
}
+
+export function resolveModeChangedMode(dataPart: {
+ type: string;
+ data?: unknown;
+}): "extended_thinking" | "fast" | null {
+ if (dataPart.type !== "data-mode-changed") return null;
+ const mode = (dataPart.data as { mode?: string } | undefined)?.mode;
+ return mode === "extended_thinking" || mode === "fast" ? mode : null;
+}
diff --git a/autogpt_platform/frontend/src/app/(platform)/copilot/store.ts b/autogpt_platform/frontend/src/app/(platform)/copilot/store.ts
index 87352b0ac9..5ac5d6ad1c 100644
--- a/autogpt_platform/frontend/src/app/(platform)/copilot/store.ts
+++ b/autogpt_platform/frontend/src/app/(platform)/copilot/store.ts
@@ -177,6 +177,9 @@ interface CopilotUIState {
/** Autopilot mode: 'extended_thinking' (default) or 'fast'. */
copilotChatMode: CopilotMode;
setCopilotChatMode: (mode: CopilotMode) => void;
+ copilotModePinned: boolean;
+ applyServerModeChange: (mode: CopilotMode) => void;
+ clearCopilotModePin: () => void;
/** Model tier: 'standard' (default) or 'advanced' (highest-capability). */
copilotLlmModel: CopilotLlmModel;
@@ -484,6 +487,13 @@ export const useCopilotUIStore = create<CopilotUIState>((set, get) => ({
storage.set(Key.COPILOT_MODE, mode);
set({ copilotChatMode: mode });
},
+ copilotModePinned: false,
+ applyServerModeChange: (mode) => {
+ set({ copilotChatMode: mode, copilotModePinned: true });
+ },
+ clearCopilotModePin: () => {
+ set({ copilotModePinned: false });
+ },
copilotLlmModel: (() => {
const saved = isClient ? storage.get(Key.COPILOT_MODEL) : null;
diff --git a/autogpt_platform/frontend/src/app/(platform)/copilot/useCopilotStream.ts b/autogpt_platform/frontend/src/app/(platform)/copilot/useCopilotStream.ts
index 06a8d15298..022e98cd1d 100644
--- a/autogpt_platform/frontend/src/app/(platform)/copilot/useCopilotStream.ts
+++ b/autogpt_platform/frontend/src/app/(platform)/copilot/useCopilotStream.ts
@@ -24,6 +24,7 @@ import {
hasActiveBackendStream,
hasInProgressAssistantParts,
hasVisibleAssistantContent,
+ resolveModeChangedMode,
} from "./helpers";
import { useCopilotUIStore } from "./store";
import type { CopilotLlmModel, CopilotMode } from "./store";
@@ -41,6 +42,15 @@ import { useWakeResync } from "./useWakeResync";
* `active_stream=true`, triggering unnecessary reconnect cycles.
*/
const FINISH_REFETCH_SETTLE_MS = 500;
+// Server-initiated continuation turns (e.g. the engine switch after
+// enter_agent_building_mode) are dispatched via RabbitMQ right after the
+// previous turn completes — one 500ms check can outrun the dispatch, so the
+// post-finish active-stream probe retries before giving up. Ordinary turns
+// keep a single probe; the extended window only runs when this turn emitted
+// a data-mode-changed part (a continuation is actually pending), and it
+// brackets the backend's dispatch retry ceiling (3 attempts, ~3s backoff).
+const FINISH_REFETCH_ATTEMPTS_DEFAULT = 1;
+const FINISH_REFETCH_ATTEMPTS_PENDING_SWITCH = 8;
/**
* Batch AI SDK message updates into ~30 ms paints. The smoothing transform in
@@ -97,6 +107,7 @@ export function useCopilotStream({
// mount (= this session), so a boolean is enough; cross-session scoping
// is no longer needed because the parent remounts on session switch.
const isUserStoppingRef = useRef(false);
+ const pendingEngineSwitchRef = useRef(false);
// State mirror of ``isUserStoppingRef`` — the ref is read synchronously
// inside SDK callbacks, the state drives UI so a click on the stop button
// immediately overrides ``isStreaming`` regardless of whether AI SDK has
@@ -153,12 +164,19 @@ export function useCopilotStream({
return;
}
- await new Promise((r) => setTimeout(r, FINISH_REFETCH_SETTLE_MS));
- if (!isMountedRef.current) return;
- const result = await refetchSession();
- if (!isMountedRef.current) return;
- if (hasActiveBackendStream(result)) {
- handleReconnectRef.current();
+ const attempts = pendingEngineSwitchRef.current
+ ? FINISH_REFETCH_ATTEMPTS_PENDING_SWITCH
+ : FINISH_REFETCH_ATTEMPTS_DEFAULT;
+ pendingEngineSwitchRef.current = false;
+ for (let attempt = 0; attempt < attempts; attempt++) {
+ await new Promise((r) => setTimeout(r, FINISH_REFETCH_SETTLE_MS));
+ if (!isMountedRef.current) return;
+ const result = await refetchSession();
+ if (!isMountedRef.current) return;
+ if (hasActiveBackendStream(result)) {
+ handleReconnectRef.current();
+ return;
+ }
}
}
@@ -203,13 +221,30 @@ export function useCopilotStream({
});
}
+ function handleData(dataPart: { type: string; data?: unknown }) {
+ const mode = resolveModeChangedMode(dataPart);
+ if (mode) {
+ pendingEngineSwitchRef.current = true;
+ // Server-forced switch: session-scoped UI state only — must not
+ // persist to localStorage and rewrite the user's global default.
+ // The pin locks the toggle for the rest of this session (the
+ // backend overrides a manual flip anyway).
+ useCopilotUIStore.getState().applyServerModeChange(mode);
+ }
+ }
+
chatRuntime.onFinish = handleFinish;
chatRuntime.onError = handleError;
+ chatRuntime.onData = handleData;
return () => {
if (chatRuntime.onFinish === handleFinish) {
chatRuntime.onFinish = undefined;
}
+ if (chatRuntime.onData === handleData) {
+ chatRuntime.onData = undefined;
+ useCopilotUIStore.getState().clearCopilotModePin();
+ }
if (chatRuntime.onError === handleError) {
chatRuntime.onError = undefined;
}