AGENTS.md

1### Python Extension System (Runtime and Distribution)
2 
3Third-party Python packages can expose an `install(registry, config)` function and be
4loaded, in deterministic order, from the startup-only top-level `plugins:` list in
5`config.yaml`. Keep this list out of `extensions_config.json`: the latter is writable
6through Gateway APIs, while importing Python entry points is an operator-controlled code
7execution boundary. A plugin marked `required: true` fails Gateway construction when it
8cannot load; optional plugins fail open with attributed diagnostics.
9 
10Packaged extensions use one PEP 621 entry point in the
11`deerflow.extensions` group, for example
12`example = "deerflow_extension_example:install"`. The operator CLI is dispatched from
13the existing `deerflow` console script to `extensions/cli.py` and exposes only these
14surfaces: `install SOURCE [--yes]`, `list`, `enable NAME`, `disable NAME`, and
15`remove NAME`. `NAME` resolves against the entry-point name, distribution name, or
16`module:install` value. The root `make extension-*` targets are convenience wrappers;
17because they execute from `backend/`, documentation should use absolute local source
18paths with `SOURCE=` unless backend-relative behavior is intentional.
19 
20`ExtensionManager` owns the package/config transaction. Install runs a controlled
21`uv add --project <backend> --group extensions --no-workspace --no-sync -- <source>`, updates the dedicated
22`[dependency-groups].extensions` list and `uv.lock`, discovers exactly one packaging entry
23point, and inserts or adopts one
24managed `plugins:` record with `name`, `package`, `use`, `enabled`, `required`, and
25private `config`. New records are written `required: false`, matching the loader default:
26`required: true` turns any later load failure — a broken wheel, a missing native library, a
27deleted snapshot — into a Gateway startup abort recoverable only through shell access, so
28it is an explicit `install --required` opt-in rather than the managed default. Adoption of
29an existing hand-written record preserves whatever `required` the operator already chose.
30Enable/disable changes only the host-level `enabled` flag and preserves
31private configuration. Remove runs `uv remove --group extensions`, removes the plugin
32record, and deletes its managed source snapshot. Install validates the selected config
33file before running any uv command, because `uv add`/`uv sync` execute the package's build
34backend: a config this manager could never write to must fail before that code runs, not
35afterwards through rollback.
36Failed install/remove operations restore `pyproject.toml` and `uv.lock` and resynchronize
37the restored environment; that second restore runs even when the recovery sync itself fails
38(a recovery sync without `--locked` writes a lock while resolving), and a failing recovery
39sync reports the original failure alongside it. The restore is deliberately not blanket:
40when recovery detects a concurrent external edit to the dependency files or the config it
41preserves that edit and raises instead, and `remove` leaves the plugin deactivated in that
42case rather than reviving a record whose package declaration may already be gone. A
43cancellation skips the recovery sync entirely — the declarations are already restored and
44the next locked startup sync reconciles the environment, whereas blocking an interrupt on a
45full dependency resolve invites a second interrupt that escapes the handler mid-transaction.
46Package mutation is deferred from environment mutation: after `uv add/remove`
47updates the declaration and lock, one `uv sync --locked --all-packages` preserves the same
48config-/environment-detected optional extras as normal startup. All three uv calls pin the
49backend project explicitly and discard UV environment overrides that could redirect the
50project, working directory, sync mode, lock policy, or target environment — including
51`UV_PYTHON`, which would swap the interpreter that then loads the extension entry point,
52and `UV_INSECURE_HOST`, which would remove the TLS validation the HTTPS-only source rule
53depends on; index, proxy, cache, and credential-provider settings remain available.
54The `--no-workspace` boundary requires uv 0.8.0 or newer. The stock Docker paths pin uv
550.11.1, and the manager fails before mutation when the host uv is older.
56All install/remove/enable/disable mutations for a checkout hold the cross-process
57`.deer-flow/extension-manager.lock`; remove deactivates config before changing the package
58declaration, and rollback preserves a concurrent external config edit instead of replacing
59it. The MVP has no in-place upgrade: operators retain private config, remove the old
60package, install the new source pin, and restore that config.
61 
62Local-directory installs are snapshots, not editable links. The manager validates the
63source, derives the destination from the normalized distribution name, and copies it to
64`backend/extensions/sources/<distribution>/`. It ignores Git metadata, virtual
65environments, Python caches, and bytecode; rejects symbolic links, path-escaping
66distribution names, and likely credential files; and the root `.dockerignore` explicitly
67re-includes the entire managed tree so package READMEs, native modules, and assets reach
68the backend builder. These checks prevent common packaging accidents, not malicious
69code. Both Python build hooks and imported extension code execute with Gateway
70privileges, so the CLI requires confirmation (or explicit `--yes`) and accepts only
71trusted operator sources; source URLs containing embedded credentials are rejected.
72Remote direct references are limited to HTTPS, and remote Git sources must use public
73Git-over-HTTPS (with loopback HTTP accepted for local tooling). SSH Git URLs are rejected
74because the stock Docker builder does not forward host SSH credentials; relative paths and
75local wheels must use the managed directory snapshot path instead. Git's SCP-like shorthand
76(`git@host:org/repo.git`) carries no URL scheme, so it is detected before the scheme rules
77and reported with the same public-HTTPS correction rather than the local-path message.
78Local wheel and `file://` sources are rejected because they cannot be reproduced inside the
79Docker build context; local code must enter through the directory-snapshot path. Stock
80production builds support public package indexes and public HTTPS Git sources reachable by
81the builder; authenticated source configuration must not be embedded in the recorded URL.
82Source validation alone cannot catch environment-driven resolution (for example a
83`UV_FIND_LINKS` wheelhouse turning a plain package requirement into a local wheel
84reference), so after every `uv add/remove` the manager audits the new lock before syncing
85or enabling anything. Any local reference that the stock backend image build cannot
86reproduce — absolute paths, `file:` URLs, or relative paths outside the project root, its
87exact workspace members, and the managed `extensions/sources/` snapshots — fails the whole
88transaction and rolls back the dependency files, config, snapshot, and environment. A
89loopback URL recorded in the lock is warned about rather than rolled back: `127.0.0.1`
90inside the image builder is a different machine, so the reference is just as
91non-reproducible, but unlike an environment-driven wheelhouse resolution it is a source the
92operator typed deliberately. A private-network index is left alone entirely — a builder on
93that network can reach it. A
94config with duplicate top-level `plugins:` keys is rejected outright rather than managed
95against one block while the Gateway reads another.
96 
97The managed `plugins:` block is rewritten in place, and both of its boundaries come from
98the YAML parser rather than a key-shaped pattern. `AppConfig` allows extra top-level keys,
99so a neighbouring section may be named anything YAML accepts (`my.key`, `2fa`, `$schema`, a
100non-ASCII word); a pattern that fails to recognize the next key does not fail loudly, it
101reports "no next section" and the rewrite replaces that neighbour and its whole subtree.
102Trailing comments below a file-final block are preserved for the same reason — the manager
103appends `plugins:` at end of file, so that is the steady-state shape.
104 
105Dependency synchronization has one lock authority: the manager's `uv add/remove` calls
106are the only extension workflow allowed to update `backend/uv.lock`, and each mutation is
107followed by the local-source audit described above. The `extensions`
108group is included in `[tool.uv].default-groups` alongside `dev`. Root/backend install
109targets use `uv sync --locked`; direct backend `make dev`/`make gateway` use
110`uv run --locked`; the local full-stack launcher and Docker-dev entrypoint perform one
111locked sync and then launch with `uv run --no-sync`; the production Docker builder syncs
112the same copied backend project and lock, and both image runtime commands use
113`--no-sync`. Thus production may download locked remote artifacts while building an
114image, but production container startup never resolves or installs an extension from the
115network. Local and Docker-dev pre-start syncs may fetch missing locked artifacts.
116`docker/dev-entrypoint.sh` retries a failed sync once after recreating `.venv`, but keeps
117`--locked` on the retry: that repairs a broken virtualenv, not a stale lock. A second
118failure aborts with recovery instructions instead of starting uvicorn against an
119environment that does not match the lock, because startup must never silently resolve
120dependencies.
121That discipline assumes the uv writing the lock and the uv reading it stay compatible, so
122uv is pinned rather than floating: `backend/Dockerfile`'s `UV_IMAGE` is the single source of
123truth, both compose defaults repeat it, and every `astral-sh/setup-uv` step pins the same
124version so CI exercises the manager against the binary production actually runs. Otherwise a
125newer uv can bump `uv.lock`'s `revision` (or make `uv lock --check` disagree with a lock
126generated elsewhere) while CI stays green, and the pinned uv in the production image then
127fails on the committed lock. `backend/tests/test_ci_uv_version_pin.py` keeps the four
128locations in step, which makes a uv upgrade one deliberate, reviewable change.
129Rebuild the Gateway image after changing the managed set. Every install, enable, disable,
130remove, or config mutation also requires a Gateway restart because plugin loading is
131startup-only.
132The root management wrappers bootstrap the checkout environment without the extension group
133via `uv run --frozen --no-group extensions`, so a broken or disappeared extension source cannot
134trigger project validation before the operator can list, disable, or remove it, while a
135fresh checkout can still install the non-extension environment from the existing lock. After CLI
136entry, the manager owns the controlled locked sync.
137 
138The public package is `packages/extension-api/` and must never import `deerflow` or carry
139framework dependencies. Extensions declare any FastAPI, LangChain, or LangGraph imports
140themselves. Its registry contract exposes five contribution kinds: middleware
141contributors, task-lifecycle contributors, system-model-call observers, Gateway-lifetime
142services, and eager routers. Middleware contributions declare lead/subagent scope, stable
143order, and a semantic placement (`MODEL_LOGICAL`, `MODEL_PHYSICAL`, `TOOL_VISIBLE`,
144`TOOL_RAW`, or `STANDARD`) rather than a fragile list index. `extensions/stack.py` is the
145single final composition point; do not inject inside
146the shared base builder because the lead builder appends more middleware afterward.
147`extensions/ordering.py` owns host ordering invariants and validates the final composed
148stack. Nothing under `extensions/` may import `agents.middlewares` at module scope: the
149middleware layer calls into this one, so a module-scope reference points the dependency
150backwards and closes a cycle as soon as any middleware imports something under
151`extensions/` at module level. Both tables that need middleware classes therefore resolve
152on first use — `ordering.py::core_ordering_constraints()` and `stack.py::_anchors()` —
153which is `assert_ordering` / composition time, already inside the middleware builder.
154Defer by deferring the *call*; do not fake a resolved value with a lazy container
155subclass, which reports one answer when iterated and another when measured.
156 
157Contributed middlewares are wrapped by `IsolatedMiddleware`: extension failures emit
158diagnostics and fail open without repeating a downstream model/tool side effect. The
159wrapper mirrors lifecycle hooks, tools, transformers, and state schema implemented by
160the inner middleware. LangChain treats each sync/async model or tool wrapper pair as one
161capability, so a single-sided wrapper receives a pass-through counterpart; implement
162both sides when the extension must observe both synchronous and asynchronous execution
163paths.
164 
165Lead runs and subagents allocate an `ExtensionData` task store only when middleware,
166task-lifecycle, or system-model observation is registered; services and routers are
167app-scoped and do not allocate one. Middleware and system-call sites recover the
168live store through `EXTENSION_TASK_STORE_KEY` / `task_store_from_runtime()`; lifecycle
169contributors receive that same store directly. Each task resolves the immutable
170loaded-extension snapshot once and binds that same object through task-store allocation,
171hooks, and synchronous agent construction, so a concurrent singleton replacement cannot
172mix two extension generations without changing the LangGraph graph-factory ABI. The
173graph-build binding is a ContextVar scoped to synchronous construction, so it has already
174exited by the time the lead agent delegates; the run worker therefore also publishes the
175snapshot on runtime context under the host-internal `EXTENSION_SNAPSHOT_CONTEXT_KEY`,
176`task_tool` reads it back through `resolve_run_extensions()` (type-checked — runtime
177context is caller-mergeable), and `SubagentExecutor` binds it at construction. That key is
178written after the caller merge and popped when the run has none, so a caller-supplied value
179is never authoritative. Absent the key — embedded `DeerFlowClient`, standalone LangGraph
180Server — the executor keeps its `get_loaded_extensions()` fallback.
181 
182The lead worker awaits `on_task_start` after the run has started and awaits `on_task_stop`
183after completion persistence/hooks but before clearing any active finalizing barrier or
184publishing the stream end. A subagent with a parent `run_id` wraps its execution with the
185same start/stop pair. Outcomes are conservative (`completed`, `aborted`, or `failed`),
186contributors run in registration order within one bounded budget, and notification failures
187are logged and fail open.
188 
189Fail-open is decided by the *origin* of a failure, not by its base class, because
190`CancelledError` reaches a contributor's `except` for two unrelated reasons. Only a genuine
191cancellation of the host task increments `asyncio.Task.cancelling()`, so `_notify_each`
192propagates on that and contains everything else: a contributor that lets a `CancelledError`
193escape — an extension implementing an internal timeout with cancellation, say — must not
194skip its successors, and must not reach the worker's deferred-interrupt path, which would
195end an otherwise successful run as cancelled. `KeyboardInterrupt` / `SystemExit` still
196propagate.
197 
198System-model-call observers cover DeerFlow-owned model invocations that do not pass
199through middleware model-call wrappers: goal evaluation, memory extraction, title
200generation, and summarization. They receive a request/result snapshot, duration, and the
201active task store when one exists; detached system work receives an isolated store. All
202three terminal paths are reported without changing the exception the host observes:
203success and failure are awaited inline, while cancellation — routine, since
204interrupt/rollback admission and shutdown both cancel the run task, with the provider
205tokens already spent — is submitted to the notify loop instead of awaited, because a
206repeated cancel would interrupt that await before any observer ran. A deployment with no
207registered notify loop drops the cancellation observation, exactly as the synchronous
208memory bridge does. `SystemModelRequest.messages` normalizes to a tuple at construction: goal and
209memory pass a message list while title and summarization pass one prompt string, and a
210bare `str` is already a `Sequence`, so without normalization an observer iterating it
211would walk characters. Normalizing also copies a live list, which is what makes the frozen
212snapshot immutable in fact rather than only by declaration. Gateway registers one canonical extension-notification loop. Awaited lifecycle
213hooks and async system observations are dispatched to that loop even when the caller is a
214subagent's isolated loop, while synchronous system callbacks submit fire-and-forget work
215there. Shutdown stops accepting detached observations before the memory shutdown flush and
216resets the loop only after in-flight run/subagent drain ordering is complete.
217 
218Gateway services start in registration order after the persistence engine and session
219factory are ready. Each receives the same `ExtensionRuntimeDeps` snapshot containing the
220app store, projected host policy, and session factory. Start failures are attributed and
221fail open. The runtime captures `app.state.extensions` once, registers cleanup before the
222start batch, and stops the attempted service prefix in reverse order after run/subagent
223drain but before store, checkpointer, and engine teardown. Each stop has an independent
224bounded timeout; failures do not starve later cleanup. A service-originated
225`CancelledError` fails open, while a new cancellation of the host task still propagates
226through the exit stack. Runtime diagnostics must be appended through
227`record_runtime_diagnostics()` so `app.state.extension_diagnostics` remains the canonical
228live list.
229 
230Routers are constructed eagerly during `install()` and mounted only after all host routes,
231so host handlers always win. The Gateway rejects a contributed router atomically when an
232earlier host or extension route provably covers one of its paths for the same HTTP method.
233The conservative matcher proves common shadows through normalized parameter names,
234static-vs-dynamic matching, known built-in-converter containment, supported compound
235segments, full-segment `path` catch-alls, and `Mount` descendants reducible to those same
236rules. Relationships requiring general regex-language inclusion are allowed rather than
237guessed. Host WebSocket routes do not collide with contributed HTTP routes, but contributed
238WebSocket routes are rejected until the host can supply authentication and Origin checks.
239Because `include_router()` recompiles contributed routes, preflight projects the converter
240registry at include time. Nonstandard converters fail closed against reserved security
241paths but otherwise prove a shadow only when their normalized matchers are identical.
242Host authentication- and CSRF-exempt paths are reserved, and contributed Mounts, unsupported
243route items, startup/shutdown hooks, and custom router lifespans are rejected; lifetime
244resources must use `ExtensionService`. Auth and CSRF classify
245`get_request_route_path(request)`, the same root-path-adjusted ASGI path Starlette routes
246match; do not switch those security predicates back to reconstructed `request.url.path`.
247That helper delegates to the private `starlette._utils.get_route_path` on purpose. Its
248requirement is not "strip `root_path` correctly" but "return exactly what the router is
249matching on", so importing the dispatcher's own implementation keeps the two in lockstep by
250construction. Do not vendor a local copy: a private import that disappears fails loudly at
251startup, while a stale copy diverges silently at a security boundary. `starlette` is
252therefore a declared, bounded direct dependency so the bump is visible in review, and
253`tests/test_gateway_request_path.py` pins the agreement independently of the mechanism.
254Any preflight, conflict, or include failure rolls back the whole router without preventing
255later routers from mounting. Do not introduce a framework-bound `RouterContributor`
256contract: the public registry accepts `Sequence[Any]`
257to keep extension-api dependency-free.
258 
259The memory kind reaches those observers through a different shape, and the difference is
260deliberate rather than an oversight to be "aligned" away. DeerMem must stay vendorable and
261cannot import the extension API, so it reports through the `MemoryCallbacks.on_memory_llm_result`
262host hook, which the DeerFlow-side callbacks translate into an observation and submit
263without awaiting. It also guards its provider call with `BaseException` rather than
264`Exception`, which is safe precisely because that whole path runs on a worker thread — the
265debounce timer, or the executor `update_memory` offloads to — where cancelling the awaiting
266side never interrupts the running thread, so `CancelledError` cannot arrive there at all.
267The host hook wrapper around the callback stays at `Exception`: only the hook's own failures
268are non-fatal, and an observability path must not swallow `SystemExit` / `KeyboardInterrupt`.
269 
270Gateway `create_app()` loads plugins once, stores the immutable registry on `app.state`
271and in the process-wide singleton, mounts contributed routers last, and installs one
272canonical live diagnostics list.
273Changing `plugins` requires a restart. Any future contribution kind must be added to the
274public contract and host runtime in the same slice; never accept a registration method
275that the current host silently ignores.
276 
277### Extension Manager Test Repositories
278 
279`test_extension_manager.py` creates temporary Git repositories for local extension sources.
280Temporary commits use an empty repository-local hook directory. They must not run developer or CI Git hooks.
281Tests for hook behavior must create and invoke their own hook fixtures.
282