deer-flow/backend/tests/test_extension_subagent_lifecycle.py
Bas Cancrinus 3751eb8daf
feat(extensions): pass a task's final status, error, goal verdict and run metadata to on_task_stop (#8304)
* feat(extensions): pass a task's final status, error, goal verdict and run metadata to on_task_stop

A lead run's final status is decided after the graph has ended: a model
that fails after retries ends the graph normally, so callback-based
tracing reports the run as OK. on_task_stop runs after the status is
persisted but only received completed | failed | aborted.

Additive, so existing contributors keep working:
- TaskInfo.metadata: a read-only copy of the run's metadata (scheduled
  runs carry scheduled_task_id, scheduled_task_run_id, scheduled_trigger);
  empty for subagents.
- TaskInfo.stop: a new TaskStopDetail (status, error, goal_verdict), set
  only on the info passed to on_task_stop.
- deerflow-extension-api 0.2.13.

Refs #8303

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(subagents): compare stop identity without the stop detail; assert its status

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(extensions): keep TaskInfo identity and serialization; flag unconfirmed stop status

Review follow-up for #8304:
- Exclude TaskInfo.stop and .metadata from equality and hashing
  (compare=False), so the stop info finds state keyed by the start info.
- Replace MappingProxyType with ReadOnlyDict, a dict subclass that rejects
  mutation and freezes nested mappings (lists become tuples). asdict(),
  deepcopy, pickle and json.dumps work again; observers sharing one
  snapshot can no longer change nested values for the next observer.
- TaskStopDetail.persisted: False when the run store did not confirm the
  terminal write or the worker lost ownership, so a staged status is not
  reported as final.
- Document waiting_for_input as a resumable pause (outcome failed) and the
  persisted flag (en/zh observers and reference).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Nan Gao <thunderggnn@gmail.com>
2026-11-17 19:57:40 +08:00

261 lines
9.3 KiB
Python

"""Subagents expose the same task lifecycle contract as lead runs."""
from __future__ import annotations
import sys
from dataclasses import replace
from types import ModuleType, SimpleNamespace
from unittest.mock import MagicMock
import pytest
from deerflow_extension_api import EXTENSION_TASK_STORE_KEY, ExtensionData, TaskInfo, TaskOutcome, TaskStopDetail
from langchain_core.messages import AIMessage
from deerflow.extensions import reset_loaded_extensions, set_loaded_extensions
from deerflow.extensions.registry import ExtensionRegistry
_MOCKED_MODULE_NAMES = (
"deerflow.agents",
"deerflow.agents.thread_state",
"deerflow.agents.middlewares",
"deerflow.agents.middlewares.thread_data_middleware",
"deerflow.sandbox",
"deerflow.sandbox.middleware",
"deerflow.sandbox.security",
"deerflow.models",
"deerflow.skills.storage",
)
@pytest.fixture
def env():
"""Import the real executor behind conftest's cycle-breaking mock."""
reset_loaded_extensions()
original_modules = {name: sys.modules.get(name) for name in _MOCKED_MODULE_NAMES}
original_executor = sys.modules.get("deerflow.subagents.executor")
subagents_pkg = sys.modules.get("deerflow.subagents")
missing = object()
original_executor_attr = getattr(subagents_pkg, "executor", missing) if subagents_pkg is not None else missing
sys.modules.pop("deerflow.subagents.executor", None)
if subagents_pkg is not None and hasattr(subagents_pkg, "executor"):
delattr(subagents_pkg, "executor")
try:
for name in _MOCKED_MODULE_NAMES:
sys.modules[name] = MagicMock()
storage_module = ModuleType("deerflow.skills.storage")
storage_module.get_or_new_skill_storage = lambda **kwargs: SimpleNamespace(load_skills=lambda *, enabled_only: [])
storage_module.get_or_new_user_skill_storage = lambda user_id, **kwargs: SimpleNamespace(load_skills=lambda *, enabled_only: [])
sys.modules["deerflow.skills.storage"] = storage_module
from deerflow.subagents.config import SubagentConfig
from deerflow.subagents.executor import (
SubagentExecutor,
SubagentResult,
SubagentStatus,
)
sys.modules["deerflow.subagents.executor"].get_app_config = lambda: SimpleNamespace(
tool_search=SimpleNamespace(enabled=False),
authorization=SimpleNamespace(enabled=False),
)
yield SimpleNamespace(
SubagentConfig=SubagentConfig,
SubagentExecutor=SubagentExecutor,
SubagentResult=SubagentResult,
SubagentStatus=SubagentStatus,
)
finally:
reset_loaded_extensions()
for name, original in original_modules.items():
if original is None:
sys.modules.pop(name, None)
else:
sys.modules[name] = original
if original_executor is None:
sys.modules.pop("deerflow.subagents.executor", None)
else:
sys.modules["deerflow.subagents.executor"] = original_executor
subagents_pkg = sys.modules.get("deerflow.subagents")
if subagents_pkg is not None:
if original_executor_attr is missing:
if hasattr(subagents_pkg, "executor"):
delattr(subagents_pkg, "executor")
else:
setattr(subagents_pkg, "executor", original_executor_attr)
class _Recorder:
def __init__(self) -> None:
self.starts: list[TaskInfo] = []
self.stops: list[tuple[TaskInfo, TaskOutcome]] = []
self.stores: list[ExtensionData] = []
async def on_task_start(self, app_store, task_store, info):
self.starts.append(info)
self.stores.append(task_store)
async def on_task_stop(self, app_store, task_store, info, outcome):
self.stops.append((info, outcome))
self.stores.append(task_store)
def _loaded(recorder):
registry = ExtensionRegistry()
with registry.attributed_to("demo:install"):
registry.task_lifecycle(recorder)
return registry.build()
def _executor(env, **overrides):
config = env.SubagentConfig(
name="researcher",
description="d",
system_prompt="p",
tools=[],
)
kwargs = {"run_id": "run-1", "thread_id": "thread-1"}
kwargs.update(overrides)
return env.SubagentExecutor(config=config, tools=[], **kwargs)
class _CompletingAgent:
def __init__(self, seen: dict | None = None) -> None:
self.seen = seen
async def astream(self, *args, **kwargs):
if self.seen is not None:
self.seen["context"] = kwargs.get("context")
yield {"messages": [AIMessage(content="done")]}
async def _noop_initial_state(self, task):
return ({}, [], None)
def _create_agent_stub(seen: dict | None = None):
"""Async stand-in for SubagentExecutor._create_agent (the real one is async)."""
async def _create(self, tools, **kwargs):
return _CompletingAgent(seen)
return _create
@pytest.mark.asyncio
async def test_subagent_success_emits_shaped_start_and_completed_stop(monkeypatch, env):
recorder = _Recorder()
set_loaded_extensions(_loaded(recorder))
executor = _executor(env)
seen: dict = {}
monkeypatch.setattr(env.SubagentExecutor, "_build_initial_state", _noop_initial_state)
monkeypatch.setattr(env.SubagentExecutor, "_create_agent", _create_agent_stub(seen))
result = await executor._aexecute("do the thing")
assert result.status is env.SubagentStatus.COMPLETED
[info] = recorder.starts
assert info == TaskInfo(
task_id=result.task_id,
run_id="run-1",
thread_id="thread-1",
kind="subagent",
parent_task_id="run-1",
agent_name="researcher",
)
assert info.stop is None
assert recorder.stops == [(replace(info, stop=TaskStopDetail(status="completed")), TaskOutcome.COMPLETED)]
assert recorder.stores[0] is recorder.stores[1]
assert seen["context"][EXTENSION_TASK_STORE_KEY] is recorder.stores[0]
@pytest.mark.asyncio
async def test_subagent_failure_and_cancellation_map_to_distinct_outcomes(monkeypatch, env):
recorder = _Recorder()
set_loaded_extensions(_loaded(recorder))
executor = _executor(env)
async def _fail_before_agent(self, task):
raise RuntimeError("build failed")
monkeypatch.setattr(env.SubagentExecutor, "_build_initial_state", _fail_before_agent)
failed = await executor._aexecute("fail")
assert failed.status is env.SubagentStatus.FAILED
assert recorder.stops[-1][1] is TaskOutcome.FAILED
assert recorder.stops[-1][0].stop == TaskStopDetail(status="failed", error="build failed")
monkeypatch.setattr(env.SubagentExecutor, "_build_initial_state", _noop_initial_state)
monkeypatch.setattr(env.SubagentExecutor, "_create_agent", _create_agent_stub())
holder = env.SubagentResult(
task_id="cancel-me",
trace_id="trace",
status=env.SubagentStatus.RUNNING,
)
holder.cancel_event.set()
cancelled = await executor._aexecute("cancel", holder)
assert cancelled.status is env.SubagentStatus.CANCELLED
assert recorder.stops[-1][1] is TaskOutcome.ABORTED
assert recorder.stops[-1][0].task_id == "cancel-me"
assert recorder.stops[-1][0].stop.status == "cancelled"
@pytest.mark.asyncio
async def test_subagent_base_exception_still_emits_failed_stop(monkeypatch, env):
recorder = _Recorder()
set_loaded_extensions(_loaded(recorder))
executor = _executor(env)
async def _hard_stop(self, task):
raise KeyboardInterrupt("host shutdown")
monkeypatch.setattr(env.SubagentExecutor, "_build_initial_state", _hard_stop)
with pytest.raises(KeyboardInterrupt):
await executor._aexecute("stop")
assert recorder.stops[0][1] is TaskOutcome.FAILED
@pytest.mark.asyncio
async def test_subagent_without_parent_run_skips_lifecycle_but_keeps_task_store(monkeypatch, env):
recorder = _Recorder()
set_loaded_extensions(_loaded(recorder))
executor = _executor(env, run_id=None)
seen: dict = {}
monkeypatch.setattr(env.SubagentExecutor, "_build_initial_state", _noop_initial_state)
monkeypatch.setattr(env.SubagentExecutor, "_create_agent", _create_agent_stub(seen))
result = await executor._aexecute("direct")
assert recorder.starts == []
assert recorder.stops == []
assert seen["context"][EXTENSION_TASK_STORE_KEY].scope_id == result.task_id
@pytest.mark.asyncio
async def test_subagent_keeps_one_snapshot_across_build_context_and_hooks(monkeypatch, env):
first = _Recorder()
second = _Recorder()
snapshot = _loaded(first)
set_loaded_extensions(snapshot)
executor = _executor(env)
seen: dict = {}
async def _switch_singleton(self, task):
set_loaded_extensions(_loaded(second))
return ({}, [], None)
async def _capture_agent(self, tools, *, deferred_setup=None, extensions=None):
seen["extensions"] = extensions
return _CompletingAgent(seen)
monkeypatch.setattr(env.SubagentExecutor, "_build_initial_state", _switch_singleton)
monkeypatch.setattr(env.SubagentExecutor, "_create_agent", _capture_agent)
await executor._aexecute("snapshot")
assert seen["extensions"] is snapshot
assert len(first.starts) == len(first.stops) == 1
assert second.starts == second.stops == []
assert seen["context"][EXTENSION_TASK_STORE_KEY] is first.stores[0]