13f0a7f263
* feat(extensions): let an out-of-tree extension observe what the agent did
DeerFlow's extension system can contribute middleware, services and routes,
but an extension cannot answer basic questions about a run without reaching
into host internals. Several of the facts it would need are destroyed by the
operations that produce them:
* The middleware chain injects and rewrites a lot of context — date
reminders, recalled memory, compaction summaries, durable-context data,
image payloads, activated skill bodies. Downstream, none of it is
attributable: at the model-call boundary an injected HumanMessage is
indistinguishable from the user's own, and anything wanting to tell them
apart has to pattern-match prompt wording, which breaks on the next copy
edit.
* Two runs of "the same agent" are only comparable if the chain enforced the
same limits, prompts and thresholds. Recovering that from outside means
reading private attributes and guessing which of them change behaviour — a
guess that rots silently as middlewares gain fields.
* The lead-agent factory resolves a model after runtime overrides, renders a
prompt, filters tools through authorization and composes a stack, all
inside one synchronous call, and none of it survives: a middleware sees its
neighbours but not the prompt, the run worker sees a graph but not what
went into it.
* Summarization is destructive by design. N messages leave the context and
one summary enters it; afterwards only the summary exists, so "which
messages became this?" is not reconstructible.
This adds seven neutral facilities so those facts are recorded where they are
still true, and releases the contract package as 0.2.0.
Message provenance
Producers stamp `deerflow_content_kind` / `deerflow_producer_kind` onto the
messages they inject or rewrite. Stamping is unconditional — a fact whose
presence depends on whether an observer is installed is not a fact — and the
keys are server-owned, so provenance cannot be forged from a request.
Middleware self-description
Twelve middlewares declare their own behaviour-affecting parameters through
a duck-typed `release_policy_parameters()`. Long text is hashed rather than
embedded: a declaration is an identity, not a copy of the prompt.
Agent assembly descriptor
`assemble_lead_agent()` returns the graph plus a descriptor whose fingerprint
answers "did anything about this agent change between these two runs?".
`make_lead_agent()` keeps its graph-only signature — it is the LangGraph
Server ABI declared in langgraph.json. Tools and skills are sorted before
hashing because their assembly order is incidental; middlewares are not,
because stack order decides what wraps what. Host build identity is reported
but excluded from the fingerprint, so a redeploy does not invalidate every
agent's identity.
Context compaction observation
Summarization emits the content hashes of the messages it is about to remove
joined to the summary that replaced them. Content is the only identity
available at that seam: the summary does not become a message, and what later
projects it into a request renders it bounded and escaped rather than
verbatim.
Neutral policy, transform and MCP-source facts
Guardrail decisions are published to runtime context under a `__`-prefixed
key; result-rewriting middlewares append a declared, ordered transform trail;
MCP tools carry their credential-free logical origin.
Extension route identity
Contributed routes are session-authenticated and cannot opt out, but
"logged in" and "administrator" are different questions. Extensions get a
neutral projection of the caller rather than the host's auth context, and
`require_admin` fails closed when identity cannot be determined.
Extension-owned tables
An extension that persists data owns its own MetaData and migration chain, so
its tables are absent from Base.metadata and `alembic revision --autogenerate`
proposes dropping them. Extensions declare a table prefix, which is rejected
at registration if it would shadow a host table.
The contract package stays dependency-free and imports no host code; every new
Protocol method has a default so later additions remain additive. The loader's
pre-1.0 rule requires an exact major.minor match, so extensions written against
0.1 are now refused at startup with an actionable install hint rather than
loading into a host that implements a different surface.
uv.lock records the contract package's new version, so `uv sync --locked` still
resolves on a fresh checkout.
* fix(backend): sort gateway service imports
DeerFlow extension example
This directory is a compact, standalone Python package showing all five DeerFlow
extension contribution kinds. It depends on the public
deerflow-extension-api contract and never imports deerflow.* or app.*.
The contract package intentionally has no framework dependencies. An extension
must therefore declare every framework it imports itself; this example explicitly
depends on FastAPI, LangChain, and LangGraph in pyproject.toml.
What it demonstrates
| Contribution | Example behavior |
|---|---|
| Middleware | Counts tool calls through one TOOL_VISIBLE middleware for lead agents and subagents |
| Task lifecycle | Creates task-scoped stats on start and folds them into app scope on stop |
| System-model observer | Counts DeerFlow-owned model calls, including failures |
| Service | Binds ExtensionRuntimeDeps only while the Gateway is running |
| Router | Eagerly declares GET /api/extension-example/stats during install() |
The middleware reads task scope only through task_store_from_runtime(). It
passes through unchanged when no task store exists. The router and service use
the same ExampleService object: its FastAPI dependency returns 503 before
start(), after stop(), or when no app store was bound. This keeps the route
topology stable while runtime capabilities arrive later.
Run the package tests
deerflow-extension-api is currently sourced from this checkout. Install it
first, then install this independent package:
cd examples/deerflow-extension-example
uv venv --python 3.12
uv pip install -e ../../backend/packages/extension-api
uv pip install -e ".[dev]"
uv run --no-project pytest -q
uv run --no-project ruff check .
uv run --no-project ruff format --check .
The tests use only the public contract plus this package's declared dependencies; the DeerFlow harness and Gateway application are not imported.
Install and load it in DeerFlow
From the DeerFlow checkout root, install this directory through the extension
manager. Use an absolute path because the Make wrapper invokes the manager from
backend/:
make extension-install SOURCE="$PWD/examples/deerflow-extension-example"
make extension-list
After the trust prompt is accepted, the manager:
- copies a deployable snapshot to
backend/extensions/sources/deerflow-extension-example/; - adds that snapshot to
backend/pyproject.toml'sextensionsdependency group and updatesbackend/uv.lock; - installs the locked environment; and
- adds and enables this startup-only entry in the selected
config.yaml.
plugins:
- name: example
package: deerflow-extension-example
use: deerflow_extension_example:install
enabled: true
required: false
config: {}
Start or restart DeerFlow after installation:
make dev
The Gateway imports extensions only while constructing the application. Install,
enable, disable, remove, and manual plugins: changes therefore take effect only
after a restart. These commands manage the example afterward:
make extension-disable NAME=example
make extension-enable NAME=example
make extension-remove NAME=example
The manager can also install a PyPI requirement or a pinned public HTTPS Git
URL. SSH Git URLs are rejected because the stock Docker builder does not
forward host SSH credentials. The direct CLI surface, run from backend/, is:
uv run --frozen --no-group extensions deerflow extensions install <source> [--yes] [--required]
uv run --frozen --no-group extensions deerflow extensions list
uv run --frozen --no-group extensions deerflow extensions enable <name>
uv run --frozen --no-group extensions deerflow extensions disable <name>
uv run --frozen --no-group extensions deerflow extensions remove <name>
--yes is intended only for automation that has already reviewed and trusted
the source: extension build hooks and runtime code execute with Gateway
privileges. --required records required: true, which turns any later load
failure into a Gateway startup abort; leave it off unless the application is
wrong without this extension.
The local snapshot is included in Docker builds. Local make dev, Docker dev,
and the production Gateway image all consume the same backend/uv.lock.
Development launchers may download missing locked artifacts before handing off
to the Gateway; a built production container does not. Rebuild the production
image with make up after changing the installed set.
After one or more runs, request the extension route:
curl -s http://localhost:2026/api/extension-example/stats
The response contains aggregated task outcomes, tool-call counts, system-model call counts, the app scope id, and a small projection of the host policy. The route passes through the Gateway's normal authentication middleware; use an authenticated browser session when authentication is enabled.
Packaging entry point
Managed packages expose exactly one standard PEP 621 entry point in the
deerflow.extensions group. This example declares:
[project.entry-points."deerflow.extensions"]
example = "deerflow_extension_example:install"
The entry-point name (example) is the stable operator-facing name accepted by
enable, disable, and remove; those commands also accept the distribution
name or the module:install value.
Package layout
deerflow_extension_example/
├── __init__.py # version-stamped install() entry point
└── plugin.py # state plus all five small contribution implementations
tests/
├── test_entry_point.py
└── test_plugin.py