mirror of
https://github.com/bytedance/deer-flow.git
synced 2026-11-20 03:10:34 +00:00
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>
This commit is contained in:
parent
c2b29f118d
commit
3751eb8daf
@ -36,6 +36,7 @@ from deerflow_extension_api.contracts import (
|
||||
ExtensionService,
|
||||
HostPolicySnapshot,
|
||||
MiddlewareContributor,
|
||||
ReadOnlyDict,
|
||||
SystemModelCallObserver,
|
||||
SystemModelRequest,
|
||||
SystemModelResult,
|
||||
@ -43,6 +44,7 @@ from deerflow_extension_api.contracts import (
|
||||
TaskInfo,
|
||||
TaskLifecycleContributor,
|
||||
TaskOutcome,
|
||||
TaskStopDetail,
|
||||
extension,
|
||||
)
|
||||
from deerflow_extension_api.host_capabilities import HostCapabilityError
|
||||
@ -102,7 +104,7 @@ from deerflow_extension_api.state import ExtensionData
|
||||
|
||||
#: Contract version. Before 1.0, minors may break and patches are additive.
|
||||
#: From 1.0 on, bump the major for breaking changes.
|
||||
API_VERSION = "0.2.12"
|
||||
API_VERSION = "0.2.13"
|
||||
|
||||
__all__ = [
|
||||
"AGENT_RUNS_CONTEXT_KEY",
|
||||
@ -174,6 +176,7 @@ __all__ = [
|
||||
"InvalidRunEvidenceCursor",
|
||||
"MessageProvenance",
|
||||
"MiddlewareContributor",
|
||||
"ReadOnlyDict",
|
||||
"MiddlewareDescriptor",
|
||||
"MiddlewarePlacement",
|
||||
"Placement",
|
||||
@ -193,6 +196,7 @@ __all__ = [
|
||||
"TaskInfo",
|
||||
"TaskLifecycleContributor",
|
||||
"TaskOutcome",
|
||||
"TaskStopDetail",
|
||||
"ToolDescriptor",
|
||||
"canonical_hash",
|
||||
"canonical_json",
|
||||
|
||||
@ -53,12 +53,82 @@ class HostPolicySnapshot:
|
||||
# --- Task lifecycle ---------------------------------------------------------
|
||||
|
||||
|
||||
def _freeze(value: Any) -> Any:
|
||||
if isinstance(value, Mapping):
|
||||
return value if isinstance(value, ReadOnlyDict) else ReadOnlyDict(value)
|
||||
if isinstance(value, list | tuple):
|
||||
return tuple(_freeze(item) for item in value)
|
||||
if isinstance(value, set | frozenset):
|
||||
return frozenset(_freeze(item) for item in value)
|
||||
return value
|
||||
|
||||
|
||||
def _read_only(self: ReadOnlyDict, *args: Any, **kwargs: Any) -> Any:
|
||||
raise TypeError("ReadOnlyDict does not support item assignment or deletion")
|
||||
|
||||
|
||||
class ReadOnlyDict(dict[str, Any]):
|
||||
"""A detached, deeply read-only dict the host hands to extensions.
|
||||
|
||||
Nested mappings become ``ReadOnlyDict`` and lists become tuples, so one
|
||||
observer cannot change what the next one reads. Being a ``dict`` keeps
|
||||
``dataclasses.asdict()``, ``copy.deepcopy()``, pickling and ``json.dumps()``
|
||||
working; ``dict(value)`` or ``value.copy()`` returns a mutable copy.
|
||||
"""
|
||||
|
||||
__slots__ = ()
|
||||
|
||||
def __init__(self, *args: Any, **kwargs: Any) -> None:
|
||||
super().__init__((key, _freeze(item)) for key, item in dict(*args, **kwargs).items())
|
||||
|
||||
__setitem__ = __delitem__ = __ior__ = _read_only
|
||||
clear = pop = popitem = setdefault = update = _read_only
|
||||
|
||||
def __reduce__(self) -> tuple[Any, ...]:
|
||||
return (type(self), (dict(self),))
|
||||
|
||||
def __copy__(self) -> ReadOnlyDict:
|
||||
return self
|
||||
|
||||
def __deepcopy__(self, memo: dict[int, Any]) -> ReadOnlyDict:
|
||||
return self
|
||||
|
||||
def __repr__(self) -> str:
|
||||
return f"ReadOnlyDict({dict.__repr__(self)})"
|
||||
|
||||
|
||||
class TaskOutcome(StrEnum):
|
||||
COMPLETED = "completed"
|
||||
ABORTED = "aborted"
|
||||
FAILED = "failed"
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class TaskStopDetail:
|
||||
"""The final state the host recorded for a task, passed to ``on_task_stop``.
|
||||
|
||||
``TaskOutcome`` stays the coarse, stable classification; this carries the
|
||||
detail behind it. A lead run's status is decided after the graph has ended
|
||||
(a model failing after retries ends the graph normally), so callback-based
|
||||
observers cannot see it; ``on_task_stop`` runs after it is persisted.
|
||||
"""
|
||||
|
||||
# Lead run: the RunStatus value (``success``, ``error``, ``timeout``,
|
||||
# ``interrupted``, or ``waiting_for_input`` for a resumable pause).
|
||||
# Subagent: the SubagentStatus value (``completed``, ``failed``,
|
||||
# ``cancelled``, ``timed_out``).
|
||||
status: str
|
||||
# The short error message the host stored for the task, if any.
|
||||
error: str | None = None
|
||||
# Lead run with a goal: the goal evaluator's verdict (for example
|
||||
# ``satisfied``, ``blocker``, ``stand_down_reason``), a read-only copy.
|
||||
goal_verdict: Mapping[str, Any] | None = field(default=None, hash=False)
|
||||
# Lead run: False when the host could not confirm the terminal write (the
|
||||
# run store rejected it or the worker lost ownership). ``status`` is then
|
||||
# the worker's staged status and the stored run may still say otherwise.
|
||||
persisted: bool = True
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class TaskInfo:
|
||||
"""Identity of one lead-agent or subagent execution."""
|
||||
@ -70,6 +140,14 @@ class TaskInfo:
|
||||
parent_task_id: str | None = None
|
||||
agent_name: str | None = None
|
||||
resumed: bool = False
|
||||
# Lead run: a read-only copy of the run's metadata (for a scheduled run,
|
||||
# ``scheduled_task_id``, ``scheduled_task_run_id`` and ``scheduled_trigger``).
|
||||
# Empty for subagents.
|
||||
# Descriptive, not identity: excluded from equality and hashing, so the
|
||||
# ``info`` passed at stop equals the one passed at start.
|
||||
metadata: Mapping[str, Any] = field(default_factory=lambda: ReadOnlyDict(), compare=False)
|
||||
# Set only on the ``info`` passed to ``on_task_stop``; ``None`` at start.
|
||||
stop: TaskStopDetail | None = field(default=None, compare=False)
|
||||
|
||||
|
||||
class TaskLifecycleContributor(Protocol):
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
[project]
|
||||
name = "deerflow-extension-api"
|
||||
version = "0.2.12"
|
||||
version = "0.2.13"
|
||||
description = "Public contracts for DeerFlow extensions"
|
||||
requires-python = ">=3.12"
|
||||
# Keep the contract package import-light and independent from the host. Public
|
||||
|
||||
@ -4,6 +4,7 @@ from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import concurrent.futures
|
||||
import copy
|
||||
import dataclasses
|
||||
import logging
|
||||
import threading
|
||||
@ -15,11 +16,13 @@ from deerflow_extension_api import (
|
||||
EXTENSION_TASK_STORE_KEY,
|
||||
CompactionEvent,
|
||||
ExtensionData,
|
||||
ReadOnlyDict,
|
||||
SystemModelRequest,
|
||||
SystemModelResult,
|
||||
SystemOperationKind,
|
||||
TaskInfo,
|
||||
TaskOutcome,
|
||||
TaskStopDetail,
|
||||
)
|
||||
|
||||
from deerflow.extensions.registry import LoadedExtensions
|
||||
@ -51,6 +54,35 @@ def subagent_task_outcome(*, cancelled: bool, succeeded: bool) -> TaskOutcome:
|
||||
return TaskOutcome.FAILED
|
||||
|
||||
|
||||
def read_only_copy(value: Mapping[str, Any] | None) -> Mapping[str, Any]:
|
||||
"""Detach host-owned run data before handing it to extensions.
|
||||
|
||||
Every nested level is frozen, so observers that share one snapshot cannot
|
||||
change what the next observer reads.
|
||||
"""
|
||||
return ReadOnlyDict(copy.deepcopy(dict(value or {})))
|
||||
|
||||
|
||||
def stopped_task_info(
|
||||
info: TaskInfo,
|
||||
*,
|
||||
status: str,
|
||||
error: str | None = None,
|
||||
goal_verdict: Mapping[str, Any] | None = None,
|
||||
persisted: bool = True,
|
||||
) -> TaskInfo:
|
||||
"""Return ``info`` carrying the task's final state, for ``on_task_stop``."""
|
||||
return dataclasses.replace(
|
||||
info,
|
||||
stop=TaskStopDetail(
|
||||
status=status,
|
||||
error=error,
|
||||
goal_verdict=read_only_copy(goal_verdict) if goal_verdict is not None else None,
|
||||
persisted=persisted,
|
||||
),
|
||||
)
|
||||
|
||||
|
||||
def _host_is_cancelling() -> bool:
|
||||
"""Whether the host task itself is being cancelled.
|
||||
|
||||
|
||||
@ -1052,6 +1052,8 @@ async def run_agent(
|
||||
lead_task_outcome,
|
||||
notify_task_start,
|
||||
notify_task_stop,
|
||||
read_only_copy,
|
||||
stopped_task_info,
|
||||
)
|
||||
|
||||
extensions = ctx.extensions if ctx.extensions is not None else get_loaded_extensions()
|
||||
@ -1274,6 +1276,7 @@ async def run_agent(
|
||||
thread_id=thread_id,
|
||||
kind="lead",
|
||||
agent_name=record.assistant_id,
|
||||
metadata=read_only_copy(record.metadata),
|
||||
)
|
||||
task_store = ExtensionData(task_id)
|
||||
# Seed the identity for every hook handed this store, not only
|
||||
@ -2328,7 +2331,13 @@ async def run_agent(
|
||||
notify_task_stop(
|
||||
extensions,
|
||||
task_store,
|
||||
task_info,
|
||||
stopped_task_info(
|
||||
task_info,
|
||||
status=record.status.value,
|
||||
error=record.error,
|
||||
goal_verdict=record.goal_verdict,
|
||||
persisted=not record.ownership_lost and getattr(record, "terminal_status_persisted", True),
|
||||
),
|
||||
lead_task_outcome(
|
||||
aborted=(record.abort_event.is_set() or record.status == RunStatus.interrupted),
|
||||
succeeded=record.status == RunStatus.success,
|
||||
|
||||
@ -1857,6 +1857,7 @@ class SubagentExecutor:
|
||||
lead_task_id,
|
||||
notify_task_start,
|
||||
notify_task_stop,
|
||||
stopped_task_info,
|
||||
subagent_task_outcome,
|
||||
)
|
||||
|
||||
@ -2299,7 +2300,11 @@ class SubagentExecutor:
|
||||
await notify_task_stop(
|
||||
loaded_extensions,
|
||||
task_store,
|
||||
task_info,
|
||||
stopped_task_info(
|
||||
task_info,
|
||||
status=result.status.value,
|
||||
error=result.error,
|
||||
),
|
||||
subagent_task_outcome(
|
||||
cancelled=result.status is SubagentStatus.CANCELLED,
|
||||
succeeded=result.status is SubagentStatus.COMPLETED,
|
||||
|
||||
@ -13,7 +13,7 @@ dependencies = [
|
||||
# the contract version it implements, extensions declare ranges. A range
|
||||
# here would let pip resolve a newer contract package than this harness
|
||||
# implements, making newer extensions look supported at runtime.
|
||||
"deerflow-extension-api==0.2.12",
|
||||
"deerflow-extension-api==0.2.13",
|
||||
"dotenv>=0.9.9",
|
||||
"exa-py>=1.0.0",
|
||||
"httpx>=0.28.0",
|
||||
|
||||
@ -342,7 +342,7 @@ def test_runtime_api_version_matches_the_installed_contract_package():
|
||||
"""Every additive contract slice bumps both gates together."""
|
||||
from importlib.metadata import version
|
||||
|
||||
assert API_VERSION == "0.2.12"
|
||||
assert API_VERSION == "0.2.13"
|
||||
assert API_VERSION == version("deerflow-extension-api")
|
||||
|
||||
|
||||
|
||||
@ -3,11 +3,12 @@
|
||||
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
|
||||
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
|
||||
@ -163,7 +164,8 @@ async def test_subagent_success_emits_shaped_start_and_completed_stop(monkeypatc
|
||||
parent_task_id="run-1",
|
||||
agent_name="researcher",
|
||||
)
|
||||
assert recorder.stops == [(info, TaskOutcome.COMPLETED)]
|
||||
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]
|
||||
|
||||
@ -181,6 +183,7 @@ async def test_subagent_failure_and_cancellation_map_to_distinct_outcomes(monkey
|
||||
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())
|
||||
@ -194,6 +197,7 @@ async def test_subagent_failure_and_cancellation_map_to_distinct_outcomes(monkey
|
||||
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
|
||||
|
||||
@ -608,3 +608,74 @@ async def test_lead_stop_cancellation_is_deferred_rather_than_swallowed():
|
||||
|
||||
assert record.finalizing is False
|
||||
bridge.publish_end.assert_awaited_once_with(record.run_id)
|
||||
|
||||
|
||||
def test_stopped_task_info_detaches_goal_verdict_and_keeps_identity():
|
||||
from deerflow_extension_api import TaskStopDetail
|
||||
|
||||
from deerflow.extensions.notify import stopped_task_info
|
||||
|
||||
verdict = {"satisfied": False, "blocker": "missing_input", "stand_down_reason": "no data"}
|
||||
info = _info()
|
||||
stopped = stopped_task_info(info, status="success", goal_verdict=verdict)
|
||||
|
||||
assert stopped.task_id == info.task_id and stopped.metadata == info.metadata
|
||||
assert info.stop is None
|
||||
assert stopped.stop == TaskStopDetail(status="success", goal_verdict=verdict)
|
||||
verdict["satisfied"] = True
|
||||
assert stopped.stop.goal_verdict["satisfied"] is False
|
||||
with pytest.raises(TypeError):
|
||||
stopped.stop.goal_verdict["satisfied"] = True # type: ignore[index]
|
||||
assert hash(stopped) == hash(info)
|
||||
assert stopped == info
|
||||
assert {info: "span"}[stopped] == "span"
|
||||
|
||||
|
||||
def test_task_info_with_read_only_data_survives_asdict_deepcopy_and_pickle():
|
||||
import copy
|
||||
import dataclasses
|
||||
import json
|
||||
import pickle
|
||||
|
||||
from deerflow.extensions.notify import read_only_copy, stopped_task_info
|
||||
|
||||
info = dataclasses.replace(_info(), metadata=read_only_copy({"scheduled_task_id": "t1", "labels": {"team": ["a", "b"]}}))
|
||||
stopped = stopped_task_info(info, status="success", goal_verdict={"satisfied": True, "evidence": [{"k": "v"}]})
|
||||
|
||||
for value in (TaskInfo(task_id="t", run_id="r", thread_id="th", kind="lead"), info, stopped):
|
||||
exported = dataclasses.asdict(value)
|
||||
json.dumps(exported)
|
||||
assert copy.deepcopy(value) == value
|
||||
assert pickle.loads(pickle.dumps(value)) == value
|
||||
exported = dataclasses.asdict(stopped)
|
||||
assert exported["metadata"] == {"scheduled_task_id": "t1", "labels": {"team": ("a", "b")}}
|
||||
assert exported["stop"]["goal_verdict"]["evidence"][0] == {"k": "v"}
|
||||
assert pickle.loads(pickle.dumps(stopped)).stop == stopped.stop
|
||||
|
||||
|
||||
def test_read_only_copy_freezes_nested_values():
|
||||
from deerflow.extensions.notify import read_only_copy
|
||||
|
||||
source = {"labels": {"team": "a"}, "items": [{"k": "v"}]}
|
||||
snapshot = read_only_copy(source)
|
||||
source["labels"]["team"] = "b"
|
||||
assert snapshot["labels"]["team"] == "a"
|
||||
for mutate in (
|
||||
lambda: snapshot.__setitem__("x", 1),
|
||||
lambda: snapshot["labels"].pop("team"),
|
||||
lambda: snapshot["labels"].update(team="b"),
|
||||
lambda: snapshot["items"][0].clear(),
|
||||
lambda: snapshot.setdefault("x", 1),
|
||||
):
|
||||
with pytest.raises(TypeError):
|
||||
mutate()
|
||||
with pytest.raises(AttributeError):
|
||||
snapshot["items"].append({}) # type: ignore[attr-defined]
|
||||
assert snapshot == {"labels": {"team": "a"}, "items": ({"k": "v"},)}
|
||||
|
||||
|
||||
def test_stopped_task_info_carries_persisted_flag():
|
||||
from deerflow.extensions.notify import stopped_task_info
|
||||
|
||||
assert stopped_task_info(_info(), status="success").stop.persisted is True
|
||||
assert stopped_task_info(_info(), status="success", persisted=False).stop.persisted is False
|
||||
|
||||
@ -1972,6 +1972,122 @@ async def test_run_agent_marks_llm_error_fallback_as_error_status():
|
||||
bridge.publish_end.assert_awaited_once_with(record.run_id)
|
||||
|
||||
|
||||
@pytest.mark.anyio
|
||||
async def test_task_stop_carries_final_status_error_and_run_metadata_for_llm_error_fallback():
|
||||
"""The graph ends normally, so only on_task_stop can see that the run failed."""
|
||||
from deerflow_extension_api import TaskOutcome
|
||||
|
||||
from deerflow.extensions.registry import ExtensionRegistry
|
||||
|
||||
run_manager = RunManager()
|
||||
scheduled = {"scheduled_task_id": "task-1", "scheduled_task_run_id": "occurrence-1", "scheduled_trigger": "scheduled"}
|
||||
record = await run_manager.create("thread-1", "researcher", metadata=dict(scheduled))
|
||||
bridge = SimpleNamespace(publish=AsyncMock(), publish_end=AsyncMock(), cleanup=AsyncMock())
|
||||
|
||||
class DummyAgent:
|
||||
async def astream(self, graph_input, config=None, stream_mode=None, subgraphs=False):
|
||||
yield {
|
||||
"messages": [
|
||||
AIMessage(
|
||||
content="The configured LLM provider is temporarily unavailable after multiple retries.",
|
||||
additional_kwargs={"deerflow_error_fallback": True, "error_detail": "Connection error."},
|
||||
)
|
||||
]
|
||||
}
|
||||
|
||||
class Recorder:
|
||||
def __init__(self):
|
||||
self.starts = []
|
||||
self.stops = []
|
||||
|
||||
async def on_task_start(self, _app_store, _task_store, info):
|
||||
self.starts.append(info)
|
||||
|
||||
async def on_task_stop(self, _app_store, _task_store, info, outcome):
|
||||
self.stops.append((info, outcome))
|
||||
|
||||
recorder = Recorder()
|
||||
registry = ExtensionRegistry()
|
||||
with registry.attributed_to("test:task-stop-detail"):
|
||||
registry.task_lifecycle(recorder)
|
||||
|
||||
await run_agent(
|
||||
bridge,
|
||||
run_manager,
|
||||
record,
|
||||
ctx=RunContext(checkpointer=None, extensions=registry.build()),
|
||||
agent_factory=lambda *, config: DummyAgent(),
|
||||
graph_input={},
|
||||
config={},
|
||||
)
|
||||
|
||||
[start] = recorder.starts
|
||||
assert start.stop is None
|
||||
assert {key: start.metadata[key] for key in scheduled} == scheduled
|
||||
with pytest.raises(TypeError):
|
||||
start.metadata["scheduled_task_id"] = "other" # type: ignore[index]
|
||||
[(info, outcome)] = recorder.stops
|
||||
assert outcome is TaskOutcome.FAILED
|
||||
assert info.stop is not None
|
||||
assert info.stop.status == "error"
|
||||
assert info.stop.error == "Connection error."
|
||||
assert info.stop.goal_verdict is None
|
||||
assert info.metadata == start.metadata
|
||||
assert info.stop.persisted is True
|
||||
assert info == start
|
||||
|
||||
|
||||
@pytest.mark.anyio
|
||||
async def test_task_stop_flags_a_staged_status_the_run_store_did_not_confirm(monkeypatch):
|
||||
"""A rejected terminal write must not reach observers as a confirmed final status."""
|
||||
from deerflow_extension_api import TaskOutcome
|
||||
|
||||
from deerflow.extensions.registry import ExtensionRegistry
|
||||
|
||||
run_manager = RunManager()
|
||||
record = await run_manager.create("thread-1", "researcher")
|
||||
bridge = SimpleNamespace(publish=AsyncMock(), publish_end=AsyncMock(), cleanup=AsyncMock())
|
||||
original_persist = run_manager._persist_status
|
||||
|
||||
async def reject_terminal_writes(rec, status, **kwargs):
|
||||
if status not in (RunStatus.pending, RunStatus.running):
|
||||
return False
|
||||
return await original_persist(rec, status, **kwargs)
|
||||
|
||||
monkeypatch.setattr(run_manager, "_persist_status", reject_terminal_writes)
|
||||
|
||||
class DummyAgent:
|
||||
async def astream(self, graph_input, config=None, stream_mode=None, subgraphs=False):
|
||||
yield {"messages": [AIMessage(content="done")]}
|
||||
|
||||
stops = []
|
||||
|
||||
class Recorder:
|
||||
async def on_task_stop(self, _app_store, _task_store, info, outcome):
|
||||
stops.append((info, outcome))
|
||||
|
||||
registry = ExtensionRegistry()
|
||||
with registry.attributed_to("test:task-stop-unconfirmed"):
|
||||
registry.task_lifecycle(Recorder())
|
||||
|
||||
await run_agent(
|
||||
bridge,
|
||||
run_manager,
|
||||
record,
|
||||
ctx=RunContext(checkpointer=None, extensions=registry.build()),
|
||||
agent_factory=lambda *, config: DummyAgent(),
|
||||
graph_input={},
|
||||
config={},
|
||||
)
|
||||
|
||||
assert record.terminal_status_persisted is False
|
||||
[(info, outcome)] = stops
|
||||
assert outcome is TaskOutcome.COMPLETED
|
||||
assert info.stop is not None
|
||||
assert info.stop.status == "success"
|
||||
assert info.stop.persisted is False
|
||||
|
||||
|
||||
@pytest.mark.anyio
|
||||
async def test_run_agent_rolls_back_failed_edit_replay_and_publishes_restored_values():
|
||||
run_manager = RunManager()
|
||||
|
||||
@ -7621,22 +7621,26 @@ class TestSubagentFinalizationCancellation:
|
||||
class TestSubagentCancellationLifecycle:
|
||||
@pytest.fixture
|
||||
def lifecycle(self):
|
||||
from dataclasses import replace
|
||||
|
||||
from deerflow.extensions.registry import ExtensionRegistry
|
||||
|
||||
starts, stops = [], []
|
||||
starts, stops, stop_details = [], [], []
|
||||
stopped = threading.Event()
|
||||
|
||||
async def on_start(app_store, task_store, info):
|
||||
starts.append(info)
|
||||
|
||||
async def on_stop(app_store, task_store, info, outcome):
|
||||
stops.append((info, outcome))
|
||||
# Identity as at start; the final state is recorded separately.
|
||||
stops.append((replace(info, stop=None), outcome))
|
||||
stop_details.append(info.stop)
|
||||
stopped.set()
|
||||
|
||||
registry = ExtensionRegistry()
|
||||
with registry.attributed_to("test:lifecycle"):
|
||||
registry.task_lifecycle(SimpleNamespace(on_task_start=on_start, on_task_stop=on_stop))
|
||||
return SimpleNamespace(extensions=registry.build(), starts=starts, stops=stops, stopped=stopped)
|
||||
return SimpleNamespace(extensions=registry.build(), starts=starts, stops=stops, stop_details=stop_details, stopped=stopped)
|
||||
|
||||
@pytest.mark.parametrize("shared_holder", [False, True])
|
||||
@pytest.mark.parametrize("stage", ["setup", "stream"])
|
||||
@ -7819,6 +7823,7 @@ class TestSubagentCancellationLifecycle:
|
||||
assert mode == "setup_cancel" or closed.is_set()
|
||||
assert len(lifecycle.starts) == 1
|
||||
assert lifecycle.stops == [(lifecycle.starts[0], expected_outcome)]
|
||||
assert [detail.status for detail in lifecycle.stop_details] == [expected_status.value]
|
||||
finally:
|
||||
cooperative_cancel.set()
|
||||
module.request_cancel_background_task(execution_id)
|
||||
|
||||
2
backend/uv.lock
generated
2
backend/uv.lock
generated
@ -975,7 +975,7 @@ extensions = []
|
||||
|
||||
[[package]]
|
||||
name = "deerflow-extension-api"
|
||||
version = "0.2.12"
|
||||
version = "0.2.13"
|
||||
source = { editable = "packages/extension-api" }
|
||||
|
||||
[[package]]
|
||||
|
||||
@ -63,6 +63,10 @@ Both hooks share the 3-second notification budget described in [Runtime Model](/
|
||||
| `parent_task_id` | `None` | The parent run id, which is the lead task's `task_id` |
|
||||
| `agent_name` | The assistant or custom agent id | The subagent name, such as `general-purpose` |
|
||||
| `resumed` | `False` | `False` |
|
||||
| `metadata` | A read-only copy of the run's metadata | Empty |
|
||||
| `stop` | `None` at start; a `TaskStopDetail` at stop | `None` at start; a `TaskStopDetail` at stop |
|
||||
|
||||
For a scheduled run, `metadata` carries `scheduled_task_id`, `scheduled_task_run_id` and `scheduled_trigger`, so an observer can tell it from an interactive run.
|
||||
|
||||
<Callout type="info">
|
||||
`resumed` is part of the contract but the current host never sets it to
|
||||
@ -83,6 +87,23 @@ A subagent whose executor has no `run_id`, which happens under a standalone Lang
|
||||
|
||||
The mapping is deliberately conservative. A subagent that hit its token or turn budget can still be `completed`.
|
||||
|
||||
### TaskStopDetail
|
||||
|
||||
`info.stop` carries the detail behind the outcome. The host decides a lead run's status after the graph has ended (a model that fails after retries ends the graph normally), so callback-based tracing cannot see it; `on_task_stop` runs after the host has tried to persist it.
|
||||
|
||||
| Field | Lead run | Subagent |
|
||||
| -------------- | ------------------------------------------------------------------------ | --------------------------------------------------------- |
|
||||
| `status` | The run status: `success`, `error`, `timeout`, `interrupted` or `waiting_for_input` | `completed`, `failed`, `cancelled` or `timed_out` |
|
||||
| `error` | The short error message stored on the run, if any | The execution's error message, if any |
|
||||
| `goal_verdict` | A read-only copy of the goal evaluator's verdict when a goal was evaluated | `None` |
|
||||
| `persisted` | `False` when the host could not confirm the terminal write | `True` |
|
||||
|
||||
`waiting_for_input` is a resumable pause, not a terminal failure: the run stopped for an approval or a question to the user, and its outcome is the coarse `failed`. Read `stop.status` to tell the two apart; answering the request starts a new run with its own start and stop.
|
||||
|
||||
With `persisted=False`, the run store rejected the terminal write or the worker lost ownership of the run. `status` is then the worker's staged status, and the stored run may still say `running` or carry another worker's result. Release your per-task state as usual, but do not report the status as final.
|
||||
|
||||
A scheduled run with a goal objective counts as unmet when its status is `success` but `goal_verdict` is missing or not `satisfied`. `stop` is set only on the `info` passed to `on_task_stop`; the `TaskInfo` in the task store keeps `stop=None`. `stop` and `metadata` are excluded from equality and hashing, so the stop `info` finds state you stored under the start `info`. Both are `ReadOnlyDict` snapshots: nested mappings are read-only and lists become tuples, and `dataclasses.asdict()` and `json.dumps()` work on them.
|
||||
|
||||
### Example
|
||||
|
||||
```python
|
||||
|
||||
@ -154,6 +154,23 @@ Frozen dataclass. The host also stores it in every task store it allocates (for
|
||||
| `parent_task_id` | `str \| None` | `None` |
|
||||
| `agent_name` | `str \| None` | `None` |
|
||||
| `resumed` | `bool` | `False` |
|
||||
| `metadata` | `Mapping[str, Any]` | empty, read-only |
|
||||
| `stop` | `TaskStopDetail \| None` | `None` |
|
||||
|
||||
### `TaskStopDetail`
|
||||
|
||||
Frozen dataclass, set on the `TaskInfo` passed to `on_task_stop`.
|
||||
|
||||
| Field | Type | Default |
|
||||
| -------------- | --------------------------- | -------- |
|
||||
| `status` | `str` | required |
|
||||
| `error` | `str \| None` | `None` |
|
||||
| `goal_verdict` | `Mapping[str, Any] \| None` | `None` |
|
||||
| `persisted` | `bool` | `True` |
|
||||
|
||||
### `ReadOnlyDict`
|
||||
|
||||
The type of `TaskInfo.metadata` and `TaskStopDetail.goal_verdict`: a `dict` subclass that rejects item assignment and deletion. Nested mappings are `ReadOnlyDict` too and lists become tuples. `dataclasses.asdict()`, `copy.deepcopy()`, pickling and `json.dumps()` work; `dict(value)` returns a mutable copy.
|
||||
|
||||
### `TaskOutcome`
|
||||
|
||||
|
||||
@ -63,6 +63,10 @@ class TaskLifecycleContributor(Protocol):
|
||||
| `parent_task_id` | `None` | 父运行 id,也就是 Lead 任务的 `task_id` |
|
||||
| `agent_name` | assistant 或自定义 Agent id | 子 Agent 名称,例如 `general-purpose` |
|
||||
| `resumed` | `False` | `False` |
|
||||
| `metadata` | 运行 metadata 的只读副本 | 空 |
|
||||
| `stop` | 开始时为 `None`;停止时为 `TaskStopDetail` | 开始时为 `None`;停止时为 `TaskStopDetail` |
|
||||
|
||||
对定时运行,`metadata` 中包含 `scheduled_task_id`、`scheduled_task_run_id` 和 `scheduled_trigger`,观察者可据此区分定时运行和交互式运行。
|
||||
|
||||
<Callout type="info">
|
||||
`resumed` 属于契约的一部分,但当前宿主从不把它设为 `True`。暂时不要依赖它来识别续跑。
|
||||
@ -82,6 +86,23 @@ class TaskLifecycleContributor(Protocol):
|
||||
|
||||
这个映射刻意偏保守。触达 token 或轮次预算的子 Agent 仍可能是 `completed`。
|
||||
|
||||
### TaskStopDetail
|
||||
|
||||
`info.stop` 携带结果背后的细节。Lead 运行的状态在图结束后才由宿主决定(模型重试后仍失败时,图会正常结束),因此基于回调的追踪看不到它;`on_task_stop` 在宿主尝试持久化状态之后运行。
|
||||
|
||||
| 字段 | Lead 运行 | 子 Agent |
|
||||
| -------------- | --------------------------------------------------- | ---------------------------------------------- |
|
||||
| `status` | 运行状态:`success`、`error`、`timeout`、`interrupted` 或 `waiting_for_input` | `completed`、`failed`、`cancelled` 或 `timed_out` |
|
||||
| `error` | 运行上保存的简短错误信息(如有) | 执行的错误信息(如有) |
|
||||
| `goal_verdict` | 评估过目标时,目标评估器结论的只读副本 | `None` |
|
||||
| `persisted` | 宿主无法确认终态写入时为 `False` | `True` |
|
||||
|
||||
`waiting_for_input` 是可恢复的暂停,而非终态失败:运行因审批或向用户提问而停下,其粗粒度结果为 `failed`。请读取 `stop.status` 区分两者;回应请求会启动一个新的运行,并有各自的开始与停止。
|
||||
|
||||
`persisted=False` 表示运行存储拒绝了终态写入,或 worker 失去了运行的所有权。此时 `status` 是 worker 暂存的状态,存储中的运行可能仍为 `running` 或带有其他 worker 的结果。请照常释放按任务保存的状态,但不要把该状态当作最终结果上报。
|
||||
|
||||
带目标的定时运行,在状态为 `success` 但 `goal_verdict` 缺失或未 `satisfied` 时记为未达成(unmet)。`stop` 只设置在传给 `on_task_stop` 的 `info` 上;任务存储中的 `TaskInfo` 保持 `stop=None`。`stop` 与 `metadata` 不参与相等比较和哈希,因此停止时的 `info` 能找到以开始时的 `info` 为键保存的状态。两者都是 `ReadOnlyDict` 快照:嵌套映射为只读,列表转为元组,`dataclasses.asdict()` 和 `json.dumps()` 均可使用。
|
||||
|
||||
### 示例
|
||||
|
||||
```python
|
||||
|
||||
@ -154,6 +154,23 @@ class TaskLifecycleContributor(Protocol):
|
||||
| `parent_task_id` | `str \| None` | `None` |
|
||||
| `agent_name` | `str \| None` | `None` |
|
||||
| `resumed` | `bool` | `False` |
|
||||
| `metadata` | `Mapping[str, Any]` | 空,只读 |
|
||||
| `stop` | `TaskStopDetail \| None` | `None` |
|
||||
|
||||
### `TaskStopDetail`
|
||||
|
||||
冻结的 dataclass,设置在传给 `on_task_stop` 的 `TaskInfo` 上。
|
||||
|
||||
| 字段 | 类型 | 默认值 |
|
||||
| -------------- | --------------------------- | ------ |
|
||||
| `status` | `str` | 必填 |
|
||||
| `error` | `str \| None` | `None` |
|
||||
| `goal_verdict` | `Mapping[str, Any] \| None` | `None` |
|
||||
| `persisted` | `bool` | `True` |
|
||||
|
||||
### `ReadOnlyDict`
|
||||
|
||||
`TaskInfo.metadata` 与 `TaskStopDetail.goal_verdict` 的类型:拒绝条目赋值和删除的 `dict` 子类。嵌套映射同样是 `ReadOnlyDict`,列表转为元组。`dataclasses.asdict()`、`copy.deepcopy()`、pickle 和 `json.dumps()` 均可使用;`dict(value)` 返回可变副本。
|
||||
|
||||
### `TaskOutcome`
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user