AGENTS.md

1## Service Startup Contracts
2 
3The root `PORT` value configures Docker's published nginx ingress only; local
4orchestration pins Next.js to `3000`. Runtime commands launch from the already
5synchronized environment with `uv run --no-sync`. Production Compose probes
6Gateway `/health`, and `deploy.sh` waits for all services before reporting
7success; failures print Compose status and recent Gateway logs.
8 
9## Backend Static Analysis Commands
10 
11The root `detect-thread-boundaries` target statically inventories execution
12boundaries under `backend/app/` and `backend/packages/harness/deerflow/`. It
13prints a concise count by execution domain and writes the complete, versioned
14JSON payload to `.deer-flow/thread-boundary-inventory.json`. Every finding has
15a stable `boundary_kind`: `asyncio_default_executor`, `dedicated_executor`,
16`anyio_worker_thread`, `direct_event_loop_blocking`, `separate_event_loop`, or
17`unresolved_dynamic_boundary`.
18 
19The AST inventory covers `asyncio.to_thread`, default and explicit
20`run_in_executor` submissions, imported aliases, simple same-module helper
21wrappers (after pre-registering dedicated executor targets), `set_default_executor`,
22`ThreadPoolExecutor` construction/submission,
23additional event loops, synchronous LangChain tools, and direct
24`BaseChatModel` fallback inheritance. It remains read-only and does not alter
25executor routing or sizing.
26 
27To supplement the static scan with configured runtime types, run:
28 
29```bash
30python scripts/detect_thread_boundaries.py \
31  --runtime-config config.yaml \
32  --json-output .deer-flow/thread-boundary-inventory.json
33```
34 
35Runtime inspection imports configured tool objects and model classes so it can
36record concrete tool names/types/modules, sync functions, async coroutines,
37and `_agenerate`/`_astream` ownership. It does not invoke tools, instantiate
38models, or call external services; import failures remain in the JSON as
39`unresolved_dynamic_boundary` records. The detector implementation and focused
40coverage live in `tests/support/detectors/thread_boundaries.py` and
41`tests/test_detect_thread_boundaries.py`.
42 
43The `detect-blocking-io` target parses `app/`, `packages/harness/deerflow/`,
44and `scripts/` with AST. By default it reports only blocking IO candidates that
45are inside async code, reachable from async code in the same file, or reachable
46from sync-only `AgentMiddleware` before/after hooks that LangGraph can execute
47on the async graph path. It prints a concise summary and writes complete JSON
48findings to `.deer-flow/blocking-io-findings.json` at the repository root
49(both `make detect-blocking-io` from the repo root and `cd backend && make
50detect-blocking-io` resolve to the same repo-root path). JSON findings include
51`priority`, `location`, `blocking_call`, `event_loop_exposure`, `reason`, and
52`code` for model-assisted or manual review. `priority` is a deterministic
53review ordering from operation type, not proof of a bug. Bare-name same-file
54calls are resolved by function name, so duplicate helper names in one file can
55conservatively over-report async reachability. The call graph also resolves
56multi-hop `self.`/`cls.` attribute chains (`self.store.flush()`) and local
57variables or parameters traced back — within the same function only — to a
58`self.`/`cls.` attribute (`store = self.store; store.flush()`); both fall back
59to the same bare-method-name resolution as an unresolvable receiver, so they
60share its over-report risk rather than adding a new kind. Deeper cross-function
61or cross-module aliasing is out of scope and stays an unreported false
62negative.
63 
64That same-function alias tracing is deliberately narrower than the symbolic
65names `dotted_name()` builds for blocking-call pattern matching elsewhere in
66this module: receiver/alias extraction uses a restricted extractor that only
67recognizes `Name`/`Attribute` chains, so a `Call` or `Subscript` result (e.g.
68`factory().flush()`, or `client = factory(); client.flush()` /
69`client = clients[0]; client.flush()`) is never treated as inheriting its
70base's alias-worthiness — including when the unsupported node is buried
71deeper in the chain (`factory().client.flush()`, `clients[0].client.flush()`):
72an unrecognized shape anywhere in the chain makes the whole receiver
73unresolved, it never falls back to just the chain's trailing attribute name,
74or that name alone could still collide with an unrelated traced parameter or
75local alias. Reassigning a traced name to a non-traceable value (anything
76other than a `self.`/`cls.` attribute or an already-traced name) kills its
77alias instead of leaving it traceable, so a stale alias from an earlier
78assignment cannot keep exposing an unrelated same-named method after the
79variable is reassigned to something else; the assignment's right-hand side is
80always analyzed against the alias state as it stood *before* this kill-or-add
81update, matching Python's own evaluate-then-bind order, so
82`client = client.flush()` still resolves that call against `client`'s prior
83(pre-reassignment) alias instead of the state after it's gone. `if`/`else`
84branches get isolated alias state — an alias added in one branch cannot leak
85into the other — and the state after the whole `if` is the union of what each
86branch produced (a conservative may-alias join), so the result no longer
87depends on which branch is textually `body` vs. `orelse`. This branch
88isolation is deliberately scoped to `ast.If` only; `ast.Try`/`ast.Match` have
89different, more complex control-flow semantics and keep the older unisolated
90traversal. Finally, a function's decorators and parameter defaults are
91analyzed in the *enclosing* scope rather than the new function's own, and
92parameter/return annotations get the same enclosing-scope treatment unless
93the module postpones annotation evaluation (`from __future__ import
94annotations`), in which case they are skipped entirely, in either scope —
95those expressions run at definition time, before the function has ever been
96called (or, when postponed, never run at all), so a call there is never
97attributed to the function being defined (it moves to whatever scope actually
98contains the `def`, e.g. the enclosing function, or disappears if that scope
99is module/class level and therefore never async-reachable). PEP 695
100type-parameter bounds are not visited in either scope: CPython evaluates each
101one lazily, in its own hidden function, only if something like `T.__bound__`
102is actually accessed, never as part of running the `def` statement itself.
103A `lambda`'s body and a bare generator expression's element/filters/later
104`for` clauses are excluded from traversal ONLY while walking another
105function's own definition-time expressions (decorators, parameter defaults/
106annotations, return annotation): there, we know structurally that the
107enclosing `def` statement is executing right now, and neither a lambda body
108nor a generator's element runs just because the lambda/generator object is
109created — only a lambda's own parameter defaults and a generator's
110outermost iterable are genuinely eager at that moment. This exclusion is
111absolute and has no exceptions: even a lambda that is immediately invoked at
112its own definition site (`(lambda: ...)()`), or a generator passed directly
113to an eager-consuming builtin, is still excluded when it appears inside
114another function's decorator/default/annotation — a narrow, intentional
115limitation given how rarely a definition-time expression contains an
116executed call at all, preferred over special-casing specific shapes there.
117 
118Everywhere else — module level, class bodies, and ordinary function-body
119statements — a lambda body or generator expression's element is scanned
120unconditionally, the same conservative, over-report-rather-than-infer stance
121this file already takes for reachability elsewhere (the `ast.If` may-alias
122union, the bare-name call-graph resolution). This file does not attempt to
123distinguish a lambda that is invoked immediately, invoked later through a
124stored variable, passed as a callback, or never called at all, nor a
125generator that is consumed by an eager builtin (`list`, `sum`, `any`, etc.),
126wrapped in another lazy iterator (`map`, `filter`), or never consumed —
127telling these apart in the general case would mean inferring evaluation
128order and consumption across arbitrary code rather than reading a fixed,
129structural fact, so none of them are special-cased; all are scanned the
130same way. This is intentionally informational and is not run from CI in
131this round.
132 
133For a diff-scoped view of the same findings, `scripts/scan_changed_blocking_io.py`
134(repo root) reports findings on the added lines of `git diff <base>...HEAD`
135plus findings new versus the merge base (so a new async caller exposing an
136untouched sync helper in the same file is still reported) — used by the
137`blocking-io-guard` skill (`.agent/skills/blocking-io-guard/`) as the
138deterministic scope step before routing each candidate to a fix and/or a
139`tests/blocking_io/` runtime anchor.
140 
141Regression tests related to Docker/provisioner behavior:
142- `tests/test_docker_sandbox_mode_detection.py` (mode detection from `config.yaml`)
143- `tests/test_provisioner_kubeconfig.py` (kubeconfig file/directory handling)
144- `tests/test_provisioner_request_threading.py` (keeps provisioner sandbox CRUD
145  endpoints as sync FastAPI handlers so synchronous K8s client calls run in the
146  Starlette worker pool instead of on the ASGI event loop)
147 
148Blocking-IO runtime gate (`tests/blocking_io/`):
149- Wraps every item under `tests/blocking_io/` with a strict Blockbuster
150  context scoped to `app.*` and `deerflow.*` (see
151  `tests/support/detectors/blocking_io_runtime.py`). Any sync blocking IO
152  call whose stack passes through DeerFlow business code while running on
153  the asyncio event loop raises `BlockingError` and fails the test.
154- Regression anchors live there: `test_skills_load.py` (locks the
155  `asyncio.to_thread` offload around `LocalSkillStorage.load_skills`, fix
156  for #1917); `test_sqlite_lifespan.py` (locks the offload around
157  SQLite path resolution plus `ensure_sqlite_parent_dir`, fix for #1912);
158  `test_jsonl_run_event_store.py` (locks `JsonlRunEventStore`'s async
159  API — including idempotent singleton-event writes — offloading its file IO
160  via `asyncio.to_thread`); `test_run_journal_callbacks.py` (locks
161  `RunJournal.run_inline` tool callbacks to in-memory/event-loop-safe work);
162  `test_integrations_router.py` (locks Lark integration install and auth
163  completion route handlers offloading archive filesystem work and `lark-cli`
164  subprocesses);
165  `test_uploads_middleware.py` (locks `UploadsMiddleware.abefore_agent`
166  offloading the uploads-directory scan off the event loop);
167  `test_uploads_router.py` (locks Gateway upload/list/delete endpoints
168  offloading upload directory creation, staged writes, chmod/cleanup,
169  directory scans/deletes, and remote sandbox sync off the event loop);
170  `test_feishu_receive_file.py` (locks Feishu attachment path preparation and
171  persistence plus remote sandbox acquisition/sync off the event loop, and
172  skips redundant sandbox sync when thread data is already mounted);
173  `test_channel_outbound_files.py` (locks Feishu, Telegram, and WeCom outbound
174  attachment open/read/hash work off the event loop);
175  `test_openviking_memory_backend.py` (locks the official OpenViking backend's
176  async add/context/search entrypoints offloading synchronous SDK and cursor
177  filesystem IO); and
178  `test_workspace_changes_recorder.py` (locks the offload around the snapshot
179  text cache lifecycle — roots resolution, `mkdtemp`, and the `shutil.rmtree`
180  on both the capture-failure branch and `record_workspace_changes`' `finally`).
181- `test_gate_smoke.py` is a meta-test asserting the gate actually catches
182  unoffloaded blocking IO and that the `@pytest.mark.allow_blocking_io`
183  opt-out works.
184- Coverage boundary: the gate only sees code that test execution actually
185  touches. Static AST coverage is a separate concern (out of scope for
186  this PR).
187- CI: runs on every PR via `.github/workflows/backend-blocking-io-tests.yml`,
188  hard-fail.
189 
190Boundary check (harness → app import firewall):
191- `tests/test_harness_boundary.py` — ensures `packages/harness/deerflow/` never imports from `app.*`
192 
193Memory backend async boundary:
194- `MemoryMiddleware.aafter_agent` calls `MemoryManager.aadd`; network-backed
195  managers must override their `a*` methods to offload or use native async I/O.
196- The mem0 backend requires an HTTPS `base_url` by default because requests
197  carry an API token. Plain HTTP requires the explicit
198  `backend_config.allow_insecure_http: true` local-development opt-in.
199- Gateway memory routes offload the synchronous management contract with
200  `asyncio.to_thread`, so backend file or HTTP I/O does not run on the ASGI
201  event loop. Gateway startup and shutdown also resolve the manager off-loop,
202  because a backend's `from_config` may perform a fail-fast connectivity check.
203- A backend may set `requires_passive_writes_in_tool_mode = True` when tool-mode
204  search is supported but durable writes still depend on conversation-level
205  extraction. Such backends receive memory tools and retain `MemoryMiddleware`.
206- Prompt recall rethrows `MemoryManagerError` only when backend config declares
207  `failure_policy.read: fail_closed`; other recall errors preserve the existing
208  log-and-empty-context behavior.
209 
210CI runs these regression tests for every pull request via [.github/workflows/backend-unit-tests.yml](../.github/workflows/backend-unit-tests.yml).
211 
212Agentic browser sessions are process-local. The Gateway startup safety gate rejects
213`GATEWAY_WORKERS > 1` when `browser_navigate` is configured, because ordinary
214uvicorn worker dispatch does not provide thread affinity for browser tools, REST
215navigation, and the Live WebSocket.
216 
217Browser Live screenshots remain JPEG bytes inside the harness and the Gateway's
218bounded, drop-oldest frame queue. WebSocket clients that request
219`frame_format=binary` receive binary messages; control metadata remains JSON.
220The legacy no-parameter protocol still base64-encodes frames into JSON at the
221Gateway boundary for backward compatibility. Unknown `frame_format` values
222receive a JSON error and close code 1008.
223