diff --git a/backend/packages/extension-api/deerflow_extension_api/__init__.py b/backend/packages/extension-api/deerflow_extension_api/__init__.py index dc5f6d4820..a0b71fb9b2 100644 --- a/backend/packages/extension-api/deerflow_extension_api/__init__.py +++ b/backend/packages/extension-api/deerflow_extension_api/__init__.py @@ -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", diff --git a/backend/packages/extension-api/deerflow_extension_api/contracts.py b/backend/packages/extension-api/deerflow_extension_api/contracts.py index b139e11294..20428c8288 100644 --- a/backend/packages/extension-api/deerflow_extension_api/contracts.py +++ b/backend/packages/extension-api/deerflow_extension_api/contracts.py @@ -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): diff --git a/backend/packages/extension-api/pyproject.toml b/backend/packages/extension-api/pyproject.toml index 713276e1ed..972fa86d19 100644 --- a/backend/packages/extension-api/pyproject.toml +++ b/backend/packages/extension-api/pyproject.toml @@ -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 diff --git a/backend/packages/harness/deerflow/extensions/notify.py b/backend/packages/harness/deerflow/extensions/notify.py index 02af39363c..7350f7efa6 100644 --- a/backend/packages/harness/deerflow/extensions/notify.py +++ b/backend/packages/harness/deerflow/extensions/notify.py @@ -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. diff --git a/backend/packages/harness/deerflow/runtime/runs/worker.py b/backend/packages/harness/deerflow/runtime/runs/worker.py index bfc6dae3a6..c3ef54803d 100644 --- a/backend/packages/harness/deerflow/runtime/runs/worker.py +++ b/backend/packages/harness/deerflow/runtime/runs/worker.py @@ -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, diff --git a/backend/packages/harness/deerflow/subagents/executor.py b/backend/packages/harness/deerflow/subagents/executor.py index 59d50cf570..a3ab514bbe 100644 --- a/backend/packages/harness/deerflow/subagents/executor.py +++ b/backend/packages/harness/deerflow/subagents/executor.py @@ -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, diff --git a/backend/packages/harness/pyproject.toml b/backend/packages/harness/pyproject.toml index dd03e1e7ef..eca5cbc2d7 100644 --- a/backend/packages/harness/pyproject.toml +++ b/backend/packages/harness/pyproject.toml @@ -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", diff --git a/backend/tests/test_extension_api_contracts.py b/backend/tests/test_extension_api_contracts.py index 9e7f3e892e..a7c50381a6 100644 --- a/backend/tests/test_extension_api_contracts.py +++ b/backend/tests/test_extension_api_contracts.py @@ -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") diff --git a/backend/tests/test_extension_subagent_lifecycle.py b/backend/tests/test_extension_subagent_lifecycle.py index f2b8af8ad9..5ca15a114d 100644 --- a/backend/tests/test_extension_subagent_lifecycle.py +++ b/backend/tests/test_extension_subagent_lifecycle.py @@ -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 diff --git a/backend/tests/test_extension_task_lifecycle.py b/backend/tests/test_extension_task_lifecycle.py index c6f2c86835..59702dcbdd 100644 --- a/backend/tests/test_extension_task_lifecycle.py +++ b/backend/tests/test_extension_task_lifecycle.py @@ -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 diff --git a/backend/tests/test_run_worker_rollback.py b/backend/tests/test_run_worker_rollback.py index 95c1173058..7049a3bebc 100644 --- a/backend/tests/test_run_worker_rollback.py +++ b/backend/tests/test_run_worker_rollback.py @@ -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() diff --git a/backend/tests/test_subagent_executor.py b/backend/tests/test_subagent_executor.py index 92570ce1c2..572f305649 100644 --- a/backend/tests/test_subagent_executor.py +++ b/backend/tests/test_subagent_executor.py @@ -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) diff --git a/backend/uv.lock b/backend/uv.lock index 94966e469a..16d21d01b0 100644 --- a/backend/uv.lock +++ b/backend/uv.lock @@ -975,7 +975,7 @@ extensions = [] [[package]] name = "deerflow-extension-api" -version = "0.2.12" +version = "0.2.13" source = { editable = "packages/extension-api" } [[package]] diff --git a/frontend/src/content/en/harness/extensions/observers.mdx b/frontend/src/content/en/harness/extensions/observers.mdx index 12ac377287..1ec591306d 100644 --- a/frontend/src/content/en/harness/extensions/observers.mdx +++ b/frontend/src/content/en/harness/extensions/observers.mdx @@ -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. `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 diff --git a/frontend/src/content/en/harness/extensions/reference.mdx b/frontend/src/content/en/harness/extensions/reference.mdx index 5a0ed43fcd..91813aca50 100644 --- a/frontend/src/content/en/harness/extensions/reference.mdx +++ b/frontend/src/content/en/harness/extensions/reference.mdx @@ -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` diff --git a/frontend/src/content/zh/harness/extensions/observers.mdx b/frontend/src/content/zh/harness/extensions/observers.mdx index 8d21fbcc7a..08347f95e8 100644 --- a/frontend/src/content/zh/harness/extensions/observers.mdx +++ b/frontend/src/content/zh/harness/extensions/observers.mdx @@ -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`,观察者可据此区分定时运行和交互式运行。 `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 diff --git a/frontend/src/content/zh/harness/extensions/reference.mdx b/frontend/src/content/zh/harness/extensions/reference.mdx index 4a05bce2c8..fc9f517211 100644 --- a/frontend/src/content/zh/harness/extensions/reference.mdx +++ b/frontend/src/content/zh/harness/extensions/reference.mdx @@ -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`