AGENTS.md

1### Request Trace Context (`packages/harness/deerflow/trace_context.py`)
2 
3Request trace correlation is controlled by `logging.enhance.enabled` at **both** entry points, gated through the shared helper `deerflow.config.app_config.is_trace_correlation_enabled` so the Gateway and embedded paths cannot drift:
4 
5- **Gateway HTTP**: `app.gateway.trace_middleware.TraceMiddleware` binds one request-level trace id per HTTP request, inheriting inbound `X-Trace-Id` when present or generating a new id otherwise. A **valid** inbound header also marks the request so `runtime/runs/worker.py` prefers that id over `config.metadata.deerflow_trace_id`, keeping logs, response headers, Langfuse, and runtime context aligned when callers send both. The middleware writes the final value to every HTTP response at `http.response.start`, which covers SSE / streaming responses without consuming the body.
6- **Embedded / TUI / CLI**: `DeerFlowClient.stream()` mints (or inherits) a request-level trace id per turn only when the flag is on. When it is off, no fresh id is minted — a caller that explicitly wraps `stream()` in `request_trace_context(...)` still opts in, because the downstream `get_current_trace_id()` read propagates that value into Langfuse metadata regardless of the flag. Because `stream()` is a sync generator (which shares the caller's context), the id binding is set/reset around each `next()` step rather than around `yield from`: this keeps LangGraph node execution and its log records inside the binding, while returning control to the caller with the ContextVar restored — avoids cross-request leak between yields and `ValueError: <Token> was created in a different Context` on GC-driven close of an abandoned generator (regression pinned by `tests/test_client_langfuse_metadata.py::test_stream_does_not_leak_trace_id_to_caller_context_between_yields` and `::test_stream_abandoned_generator_close_does_not_raise_cross_context`).
7 
8The same ContextVar value is injected into enhanced log records as `trace_id` and into Langfuse metadata as `deerflow_trace_id`.
9 
10`logging` is registered as a **restart-required** field
11(`STARTUP_ONLY_FIELDS["logging"]`): `configure_logging()` installs the trace-context
12filter and enhanced formatter on root handlers only during app.py lifespan startup,
13and `TraceMiddleware` captures `logging.enhance.enabled` once when the FastAPI app
14is constructed (via `resolve_trace_enabled(get_app_config())` in `create_app()`,
15itself a thin alias for `is_trace_correlation_enabled`). This keeps the response
16`X-Trace-Id` header, log `trace_id` fields, and Langfuse `deerflow_trace_id`
17coherent — a runtime `config.yaml` edit to `logging.enhance.*` needs a Gateway
18restart to take effect. The `deerflow_trace_id` chain inherits this guarantee
19transitively because every injection point ultimately reads the same
20`trace_context` ContextVar that the middleware alone populates. `DeerFlowClient`
21reads its own `self._app_config` snapshot (captured at `__init__`) through the
22same helper for the embedded gate.
23 
24`deerflow_trace_id` is a DeerFlow correlation metadata key, not Langfuse's native
25trace id and not a DeerFlow `run_id`. Keep the existing subagent `trace_id` field
26separate: that short id is still only for subagent execution logs/status.
27 
28### Embedded Client (`packages/harness/deerflow/client.py`)
29 
30`DeerFlowClient` provides direct in-process access to all DeerFlow capabilities without HTTP services. All return types align with the Gateway API response schemas, so consumer code works identically in HTTP and embedded modes.
31 
32**Architecture**: Imports the same `deerflow` modules that Gateway API uses. Shares the same config files and data directories. No FastAPI dependency.
33 
34**Agent Conversation**:
35- `chat(message, thread_id)` — synchronous, accumulates streaming deltas per message-id and returns the final AI text
36- `stream(message, thread_id)` — subscribes to LangGraph `stream_mode=["values", "messages", "custom"]` and yields `StreamEvent`:
37  - `"values"` — full state snapshot (title, messages, artifacts); AI text already delivered via `messages` mode is **not** re-synthesized here to avoid duplicate deliveries; serialized `ToolMessage` entries preserve a non-`None` native `artifact`
38  - `"messages-tuple"` — per-chunk update: for AI text this is a **delta** (concat per `id` to rebuild the full message); tool calls and tool results are emitted once each, and tool results preserve a non-`None` native `artifact`
39  - `"custom"` — forwarded from `StreamWriter`; DeerFlow-built-in custom events are dual-emitted through `deerflow.utils.custom_events`, so `astream_events(version="v2")` consumers also receive one `on_custom_event` with `name=payload["type"]` and the unchanged payload as `data`
40  - `"end"` — stream finished (carries cumulative `usage` counted once per message id)
41- **Custom-event invariant** — production DeerFlow emitters must use `emit_custom_event` / `aemit_custom_event`, not call `StreamWriter` alone. Every built-in payload must carry a non-empty string `type`; typeless payloads remain writer-only and are intentionally absent from `astream_events`. The writer runs first and remains authoritative for Gateway, Web UI, and embedded-client compatibility; callback dispatch is best-effort and must not break that path. Async graph hooks must await the async helper rather than invoking synchronous dispatch on a running event loop.
42- Agent created lazily via `create_agent()` + `build_middlewares()`, same as `make_lead_agent`
43- Supports `checkpointer` parameter for state persistence across turns
44- `reset_agent()` forces agent recreation (e.g. after memory or skill changes)
45- See [docs/STREAMING.md](../../../docs/STREAMING.md) for the full design: why Gateway and DeerFlowClient are parallel paths, LangGraph's `stream_mode` semantics, the per-id dedup invariants, and regression testing strategy
46 
47**Gateway Equivalent Methods** (replaces Gateway API):
48 
49| Category | Methods | Return format |
50|----------|---------|---------------|
51| Models | `list_models()`, `get_model(name)` | `{"models": [...]}`, `{name, display_name, ...}` |
52| MCP | `get_mcp_config()`, `update_mcp_config(servers)` | `{"mcp_servers": {...}}` |
53| Skills | `list_skills()`, `get_skill(name)`, `update_skill(name, enabled)`, `install_skill(path)` | `{"skills": [...]}` |
54| Goals | `get_goal(thread_id)`, `set_goal(thread_id, objective, max_continuations=8)`, `clear_goal(thread_id)` | `{"goal": {...}}` or `{"goal": None}` |
55| Memory | `get_memory()`, `reload_memory()`, `get_memory_config()`, `get_memory_status()` | dict |
56| Uploads | `upload_files(thread_id, files)`, `list_uploads(thread_id)`, `delete_upload(thread_id, filename)` | `{"success": true, "files": [...]}`, `{"files": [...], "count": N}` |
57| Artifacts | `get_artifact(thread_id, path)` → `(bytes, mime_type)` | tuple |
58 
59**Key difference from Gateway**: Upload accepts local `Path` objects instead of HTTP `UploadFile`, rejects directory paths before copying, and reuses a single worker when document conversion must run inside an active event loop. Artifact returns `(bytes, mime_type)` instead of HTTP Response. The new Gateway-only thread cleanup route deletes `.deer-flow/threads/{thread_id}` after LangGraph thread deletion; there is no matching `DeerFlowClient` method yet. `update_mcp_config()` and `update_skill()` automatically invalidate the cached agent.
60 
61**Tests**: `tests/test_client.py` (offline unit tests including
62`TestGatewayConformance`), `tests/test_client_live.py` (live integration tests,
63requires a root `config.yaml`, valid API credentials, and explicit opt-in via
64`make test-live` or `DEER_FLOW_RUN_LIVE_TESTS=1`). The live suite calls real
65external APIs and may incur API costs or create local sandboxes, artifacts, and
66files. It is marked `live`, excluded from `make test`, and skipped in default
67CI.
68 
69**Gateway Conformance Tests** (`TestGatewayConformance`): Validate that every dict-returning client method conforms to the corresponding Gateway Pydantic response model. Each test parses the client output through the Gateway model — if Gateway adds a required field that the client doesn't provide, Pydantic raises `ValidationError` and CI catches the drift. Covers: `ModelsListResponse`, `ModelResponse`, `SkillsListResponse`, `SkillResponse`, `SkillInstallResponse`, `McpConfigResponse`, `UploadResponse`, `MemoryConfigResponse`, `MemoryStatusResponse`.
70