mirror of
https://github.com/bytedance/deer-flow.git
synced 2026-08-13 08:18:57 +00:00
1f792d0f4b
* feat(extensions): add middleware plugin foundation * fix(extensions): stop config resolution from masking extension loading `create_app()` resolved the configured plugin list inside the fail-open guard around `load_extensions()`. CI has no `config.yaml` (gitignored and never generated by the workflow), so `get_app_config()` raised `FileNotFoundError` there and was swallowed as an extension failure -- `load_extensions()` never ran at all, and the four `create_app()` tests in `test_extension_app_loading.py` passed locally but failed on every runner. Resolve the plugin list before the guard. Only an absent `config.yaml` is tolerated, mirroring `_resolve_trace_enabled_for_app_construction()`: `create_app()` runs at import time, and lifespan still performs strict config loading before serving. A `config.yaml` that exists but fails to parse or validate now propagates instead of being reported as an extension failure -- reporting it as the latter silently dropped a `required: true` extension rather than failing the boot. Make the tests config-independent with an autouse `stub_app_config` fixture, following the existing pattern in `test_gateway_lifespan_shutdown.py`, and cover both new branches of the config-resolution boundary. * fix(extensions): bind the run's extension snapshot through subagent delegation The lead-agent path resolves one immutable loaded-extension snapshot per run and binds it through task-store allocation and graph construction, but the subagent path re-read the process-wide singleton at execution time. In production both are the same object, yet a `set_loaded_extensions()` between the lead run's start and a subagent's execution (test teardown, a future hot-reload path) would let one run mix two extension generations — exactly what the documented invariant exists to prevent. The graph-build binding is a ContextVar scoped to synchronous construction, so it has already exited by the time a tool delegates; the snapshot has to travel through runtime context instead. The run worker publishes it under the host-internal `EXTENSION_SNAPSHOT_CONTEXT_KEY` (written after the caller merge, popped when the run has none, so a caller-supplied value is never authoritative), `task_tool` reads it back through the type-checking `resolve_run_extensions()`, and `SubagentExecutor` binds it at construction. Callers outside the Gateway run path — embedded `DeerFlowClient`, standalone LangGraph Server — install no snapshot and keep the existing `get_loaded_extensions()` fallback. * refactor(extensions): defer the ordering table by call, not by a lying tuple `CORE_ORDERING_CONSTRAINTS` was a `tuple` subclass that overrode only `__iter__` and resolved into a class-level `_resolved` side channel. A tuple cannot populate its own storage after construction, so the instance stayed the empty tuple it was built as: `len()` was 0, `bool()` was False, `in` was always False, indexing raised, slicing and `reversed()` came back empty, and it compared unequal to the plain tuples tests substitute for it — all while iteration yielded the real constraints. Only `assert_ordering` consumed it, and only by iterating, so the split went unnoticed. The sibling `_AnchorTable(dict)` uses the same idea soundly because dict is mutable: `self.update()` fills the real storage, making every inherited operation correct. That trick does not survive the port to an immutable type. Replace it with `core_ordering_constraints()`, matching how `stack.py` defers the same kind of table via `_anchors()`. The deferral is kept — it is about dependency direction, not just cycles: `extensions/` is the layer the middleware layer calls into, so a module-scope `agents.middlewares` import here points the dependency backwards and closes a cycle as soon as any middleware imports something under `extensions/` at module level. Resolution stays at `assert_ordering` time, which already runs inside the middleware builder. Tests pin both halves: the returned value is a plain tuple whose len/bool/ membership/indexing/reversal/equality agree with iteration, and a subprocess probe asserts importing `extensions.ordering` does not load the middleware layer while calling the function does.
71 lines
2.4 KiB
Python
71 lines
2.4 KiB
Python
"""Where an extension's middleware sits in the host's middleware stack.
|
|
|
|
Placement is declared as a *semantic guarantee* ("I need to observe the raw
|
|
tool return") rather than as a structural position ("put me in layer 3"). A
|
|
middleware occupies one index in the list, but that index only has meaning on
|
|
the hook chain it actually implements — so "outermost" means different things
|
|
on the model axis and the tool axis. Declaring by axis-and-end removes that
|
|
ambiguity and keeps the host free to restructure its stack.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
from dataclasses import dataclass, field
|
|
from enum import Flag, StrEnum, auto
|
|
from typing import Any
|
|
|
|
from deerflow_extension_api.contracts import HostPolicySnapshot
|
|
|
|
|
|
class Placement(StrEnum):
|
|
MODEL_LOGICAL = "model_logical"
|
|
"""Model axis, outer end. Guarantee: outer of retry and error handling.
|
|
Fires once per logical decision regardless of how many times the host
|
|
retries underneath."""
|
|
|
|
MODEL_PHYSICAL = "model_physical"
|
|
"""Model axis, inner end. Guarantee: inner of every request-transforming
|
|
middleware. Fires once per physical provider call; retries re-enter it."""
|
|
|
|
TOOL_VISIBLE = "tool_visible"
|
|
"""Tool axis, outer end. Guarantee: outer of truncation, sanitization and
|
|
error wrapping. Observes what the model finally sees."""
|
|
|
|
TOOL_RAW = "tool_raw"
|
|
"""Tool axis, inner end. Guarantee: adjacent to the real callable
|
|
boundary. Observes the tool's raw return before any processing."""
|
|
|
|
STANDARD = "standard"
|
|
"""No before/after-processing requirement. Relative order against other
|
|
STANDARD contributors is not guaranteed."""
|
|
|
|
|
|
class AgentScope(Flag):
|
|
LEAD = auto()
|
|
SUBAGENT = auto()
|
|
BOTH = LEAD | SUBAGENT
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class AgentBuildContext:
|
|
"""What an extension may know while deciding what to contribute."""
|
|
|
|
scope: AgentScope
|
|
agent_name: str | None = None
|
|
model_name: str | None = None
|
|
policy: HostPolicySnapshot = field(default_factory=HostPolicySnapshot)
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class MiddlewarePlacement:
|
|
"""One middleware plus where it needs to sit.
|
|
|
|
``middleware`` is typed ``Any`` rather than ``AgentMiddleware`` so this
|
|
module stays import-light; the host validates the type at injection time.
|
|
"""
|
|
|
|
middleware: Any
|
|
placement: Placement
|
|
scope: AgentScope = AgentScope.BOTH
|
|
order: int = 0
|