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

213 lines
6.0 KiB
Python

"""Public contracts for DeerFlow extensions.
This package MUST NOT import `deerflow`. Every host contract an extension
needs lives here, while framework imports remain direct extension dependencies;
extensions can therefore be released independently of the host.
"""
from __future__ import annotations
from deerflow_extension_api.agent_runs import AGENT_RUNS_CONTEXT_KEY, AGENT_RUNS_RESOLVER_KEY, AgentRun, AgentRunError, AgentRuns, ExecutionFence, require_agent_runs, resolve_agent_runs
from deerflow_extension_api.assembly import (
AgentAssemblyDescriptor,
AgentAssemblyObserver,
MiddlewareDescriptor,
ToolDescriptor,
)
from deerflow_extension_api.auth import (
EXTENSION_PLUGIN_AUTHZ_RESOLVER_ASYNC_KEY,
EXTENSION_PLUGIN_AUTHZ_RESOLVER_KEY,
EXTENSION_PRINCIPAL_RESOLVER_KEY,
ExtensionPrincipal,
arequire_plugin_management,
require_admin,
require_plugin_management,
resolve_principal,
)
from deerflow_extension_api.compaction import (
CompactionEvent,
ContextCompactionObserver,
)
from deerflow_extension_api.completed_run_evidence import CompletedRunEvent, CompletedRunEventPage, CompletedRunEvidenceReader, CompletedRunSnapshot, EvidenceLimits
from deerflow_extension_api.contracts import (
ExtensionInstall,
ExtensionRegistry,
ExtensionRuntimeDeps,
ExtensionService,
HostPolicySnapshot,
MiddlewareContributor,
ReadOnlyDict,
SystemModelCallObserver,
SystemModelRequest,
SystemModelResult,
SystemOperationKind,
TaskInfo,
TaskLifecycleContributor,
TaskOutcome,
TaskStopDetail,
extension,
)
from deerflow_extension_api.host_capabilities import HostCapabilityError
from deerflow_extension_api.model_invocation import (
ModelInvocationError,
ModelInvocationFailed,
ModelInvocationRequest,
ModelInvocationResult,
ModelInvocationUnauthorized,
ModelInvocationUnavailable,
ModelInvoker,
ModelMessage,
ModelOutputValidationError,
ModelUsage,
)
from deerflow_extension_api.placement import (
AgentBuildContext,
AgentScope,
MiddlewarePlacement,
Placement,
)
from deerflow_extension_api.plugins import ActionContext, BackendAction, BrowserAssets, BrowserModule, ModelTool, PluginContribution, PluginToolResult, ToolContext
from deerflow_extension_api.provenance import (
MESSAGE_CONTENT_KIND_KEY,
MESSAGE_PRODUCER_ENTITY_ID_KEY,
MESSAGE_PRODUCER_KIND_KEY,
PROVENANCE_KEYS,
ContentKind,
MessageProvenance,
provenance_kwargs,
read_provenance,
)
from deerflow_extension_api.release import (
ReleasePolicyProvider,
canonical_hash,
canonical_json,
collect_release_policies,
)
from deerflow_extension_api.run_evidence import (
RUN_EVIDENCE_READER_RESOLVER_KEY,
InvalidRunEvidenceCursor,
RunEventPage,
RunEventView,
RunEvidenceReader,
RunPage,
RunStatusView,
require_run_evidence_reader,
resolve_run_evidence_reader,
)
from deerflow_extension_api.runtime_bridge import (
EXTENSION_TASK_STORE_KEY,
task_store_from_runtime,
)
from deerflow_extension_api.settings import SettingsField
from deerflow_extension_api.skill_mutations import AssessmentRef, AssetRevision, BundleFile, HostCheckResult, MutationCapabilities, Operation, Proposal, ProposalBundle, SkillMutationService, SkillRevisionView
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.13"
__all__ = [
"AGENT_RUNS_CONTEXT_KEY",
"AGENT_RUNS_RESOLVER_KEY",
"AgentRun",
"AgentRunError",
"AgentRuns",
"ExecutionFence",
"require_agent_runs",
"resolve_agent_runs",
"ModelInvocationError",
"ModelInvocationFailed",
"ModelInvocationRequest",
"ModelInvocationResult",
"ModelInvocationUnauthorized",
"ModelInvocationUnavailable",
"ModelInvoker",
"ModelMessage",
"ModelOutputValidationError",
"ModelUsage",
"ActionContext",
"BackendAction",
"BrowserAssets",
"BrowserModule",
"ModelTool",
"PluginToolResult",
"PluginContribution",
"SettingsField",
"ToolContext",
"CompletedRunEvent",
"CompletedRunEventPage",
"CompletedRunEvidenceReader",
"CompletedRunSnapshot",
"EvidenceLimits",
"HostCapabilityError",
"AssessmentRef",
"AssetRevision",
"BundleFile",
"HostCheckResult",
"MutationCapabilities",
"Operation",
"Proposal",
"ProposalBundle",
"SkillMutationService",
"SkillRevisionView",
"API_VERSION",
"EXTENSION_PLUGIN_AUTHZ_RESOLVER_ASYNC_KEY",
"EXTENSION_PLUGIN_AUTHZ_RESOLVER_KEY",
"EXTENSION_PRINCIPAL_RESOLVER_KEY",
"EXTENSION_TASK_STORE_KEY",
"MESSAGE_CONTENT_KIND_KEY",
"MESSAGE_PRODUCER_ENTITY_ID_KEY",
"MESSAGE_PRODUCER_KIND_KEY",
"PROVENANCE_KEYS",
"AgentAssemblyDescriptor",
"AgentAssemblyObserver",
"AgentBuildContext",
"AgentScope",
"CompactionEvent",
"ContentKind",
"ContextCompactionObserver",
"ExtensionData",
"ExtensionInstall",
"ExtensionPrincipal",
"ExtensionRegistry",
"ExtensionRuntimeDeps",
"ExtensionService",
"HostPolicySnapshot",
"InvalidRunEvidenceCursor",
"MessageProvenance",
"MiddlewareContributor",
"ReadOnlyDict",
"MiddlewareDescriptor",
"MiddlewarePlacement",
"Placement",
"ReleasePolicyProvider",
"RunEvidenceReader",
"RUN_EVIDENCE_READER_RESOLVER_KEY",
"RunEventPage",
"RunEventView",
"RunPage",
"RunStatusView",
"require_run_evidence_reader",
"resolve_run_evidence_reader",
"SystemModelCallObserver",
"SystemModelRequest",
"SystemModelResult",
"SystemOperationKind",
"TaskInfo",
"TaskLifecycleContributor",
"TaskOutcome",
"TaskStopDetail",
"ToolDescriptor",
"canonical_hash",
"canonical_json",
"collect_release_policies",
"arequire_plugin_management",
"extension",
"provenance_kwargs",
"read_provenance",
"require_admin",
"require_plugin_management",
"resolve_principal",
"task_store_from_runtime",
]