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:
Bas Cancrinus 2026-11-17 12:57:40 +01:00 committed by GitHub
parent c2b29f118d
commit 3751eb8daf
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
17 changed files with 412 additions and 12 deletions

View File

@ -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",

View File

@ -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):

View File

@ -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

View File

@ -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.

View File

@ -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,

View File

@ -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,

View File

@ -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",

View File

@ -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")

View File

@ -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

View File

@ -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

View File

@ -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()

View File

@ -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
View File

@ -975,7 +975,7 @@ extensions = []
[[package]]
name = "deerflow-extension-api"
version = "0.2.12"
version = "0.2.13"
source = { editable = "packages/extension-api" }
[[package]]

View File

@ -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

View File

@ -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`

View File

@ -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

View File

@ -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`