Initial commit

offline-backend-20260512/backend/.gitignore

@@ -0,0 +1,28 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+.coverage
+.coverage.*
+.ruff_cache
+agent_history.gif
+static/browser_history/*.gif
+
+log/
+log/*
+
+# Virtual environments
+.venv
+venv/
+
+# User config file
+config.yaml
+
+# Langgraph
+.langgraph_api
+
+# Claude Code settings
+.claude/settings.local.json

offline-backend-20260512/backend/.python-version

@@ -0,0 +1 @@
+3.12

offline-backend-20260512/backend/AGENTS.md

@@ -0,0 +1,2 @@
+For the backend architecture and design patterns:
+@./CLAUDE.md

offline-backend-20260512/backend/CLAUDE.md

@@ -0,0 +1,571 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+DeerFlow is a LangGraph-based AI super agent system with a full-stack architecture. The backend provides a "super agent" with sandbox execution, persistent memory, subagent delegation, and extensible tool integration - all operating in per-thread isolated environments.
+
+**Architecture**:
+- **Gateway API** (port 8001): REST API plus embedded LangGraph-compatible agent runtime
+- **Frontend** (port 3000): Next.js web interface
+- **Nginx** (port 2026): Unified reverse proxy entry point
+- **Provisioner** (port 8002, optional in Docker dev): Started only when sandbox is configured for provisioner/Kubernetes mode
+
+**Runtime**:
+- `make dev`, Docker dev, and production all run the agent runtime in Gateway via `RunManager` + `run_agent()` + `StreamBridge` (`packages/harness/deerflow/runtime/`). Nginx exposes that runtime at `/api/langgraph/*` and rewrites it to Gateway's native `/api/*` routers.
+
+**Project Structure**:
+```
+deer-flow/
+├── Makefile                    # Root commands (check, install, dev, stop)
+├── config.yaml                 # Main application configuration
+├── extensions_config.json      # MCP servers and skills configuration
+├── backend/                    # Backend application (this directory)
+│   ├── Makefile               # Backend-only commands (dev, gateway, lint)
+│   ├── langgraph.json         # LangGraph Studio graph configuration
+│   ├── packages/
+│   │   └── harness/           # deerflow-harness package (import: deerflow.*)
+│   │       ├── pyproject.toml
+│   │       └── deerflow/
+│   │           ├── agents/            # LangGraph agent system
+│   │           │   ├── lead_agent/    # Main agent (factory + system prompt)
+│   │           │   ├── middlewares/   # 10 middleware components
+│   │           │   ├── memory/        # Memory extraction, queue, prompts
+│   │           │   └── thread_state.py # ThreadState schema
+│   │           ├── sandbox/           # Sandbox execution system
+│   │           │   ├── local/         # Local filesystem provider
+│   │           │   ├── sandbox.py     # Abstract Sandbox interface
+│   │           │   ├── tools.py       # bash, ls, read/write/str_replace
+│   │           │   └── middleware.py  # Sandbox lifecycle management
+│   │           ├── subagents/         # Subagent delegation system
+│   │           │   ├── builtins/      # general-purpose, bash agents
+│   │           │   ├── executor.py    # Background execution engine
+│   │           │   └── registry.py    # Agent registry
+│   │           ├── tools/builtins/    # Built-in tools (present_files, ask_clarification, view_image)
+│   │           ├── mcp/               # MCP integration (tools, cache, client)
+│   │           ├── models/            # Model factory with thinking/vision support
+│   │           ├── skills/            # Skills discovery, loading, parsing
+│   │           ├── config/            # Configuration system (app, model, sandbox, tool, etc.)
+│   │           ├── community/         # Community tools (tavily, jina_ai, firecrawl, image_search, aio_sandbox)
+│   │           ├── reflection/        # Dynamic module loading (resolve_variable, resolve_class)
+│   │           ├── utils/             # Utilities (network, readability)
+│   │           └── client.py          # Embedded Python client (DeerFlowClient)
+│   ├── app/                   # Application layer (import: app.*)
+│   │   ├── gateway/           # FastAPI Gateway API
+│   │   │   ├── app.py         # FastAPI application
+│   │   │   └── routers/       # FastAPI route modules (models, mcp, memory, skills, uploads, threads, artifacts, agents, suggestions, channels)
+│   │   └── channels/          # IM platform integrations
+│   ├── tests/                 # Test suite
+│   └── docs/                  # Documentation
+├── frontend/                   # Next.js frontend application
+└── skills/                     # Agent skills directory
+    ├── public/                # Public skills (committed)
+    └── custom/                # Custom skills (gitignored)
+```
+
+## Important Development Guidelines
+
+### Documentation Update Policy
+**CRITICAL: Always update README.md and CLAUDE.md after every code change**
+
+When making code changes, you MUST update the relevant documentation:
+- Update `README.md` for user-facing changes (features, setup, usage instructions)
+- Update `CLAUDE.md` for development changes (architecture, commands, workflows, internal systems)
+- Keep documentation synchronized with the codebase at all times
+- Ensure accuracy and timeliness of all documentation
+
+## Commands
+
+**Root directory** (for full application):
+```bash
+make check      # Check system requirements
+make install    # Install all dependencies (frontend + backend)
+make dev        # Start all services (Gateway + Frontend + Nginx), with config.yaml preflight
+make start      # Start production services locally
+make stop       # Stop all services
+```
+
+**Backend directory** (for backend development only):
+```bash
+make install    # Install backend dependencies
+make dev        # Run Gateway API with reload (port 8001)
+make gateway    # Run Gateway API only (port 8001)
+make test       # Run all backend tests
+make lint       # Lint with ruff
+make format     # Format code with ruff
+```
+
+Regression tests related to Docker/provisioner behavior:
+- `tests/test_docker_sandbox_mode_detection.py` (mode detection from `config.yaml`)
+- `tests/test_provisioner_kubeconfig.py` (kubeconfig file/directory handling)
+
+Boundary check (harness → app import firewall):
+- `tests/test_harness_boundary.py` — ensures `packages/harness/deerflow/` never imports from `app.*`
+
+CI runs these regression tests for every pull request via [.github/workflows/backend-unit-tests.yml](../.github/workflows/backend-unit-tests.yml).
+
+## Architecture
+
+### Harness / App Split
+
+The backend is split into two layers with a strict dependency direction:
+
+- **Harness** (`packages/harness/deerflow/`): Publishable agent framework package (`deerflow-harness`). Import prefix: `deerflow.*`. Contains agent orchestration, tools, sandbox, models, MCP, skills, config — everything needed to build and run agents.
+- **App** (`app/`): Unpublished application code. Import prefix: `app.*`. Contains the FastAPI Gateway API and IM channel integrations (Feishu, Slack, Telegram, DingTalk).
+
+**Dependency rule**: App imports deerflow, but deerflow never imports app. This boundary is enforced by `tests/test_harness_boundary.py` which runs in CI.
+
+**Import conventions**:
+```python
+# Harness internal
+from deerflow.agents import make_lead_agent
+from deerflow.models import create_chat_model
+
+# App internal
+from app.gateway.app import app
+from app.channels.service import start_channel_service
+
+# App → Harness (allowed)
+from deerflow.config import get_app_config
+
+# Harness → App (FORBIDDEN — enforced by test_harness_boundary.py)
+# from app.gateway.routers.uploads import ...  # ← will fail CI
+```
+
+### Agent System
+
+**Lead Agent** (`packages/harness/deerflow/agents/lead_agent/agent.py`):
+- Entry point: `make_lead_agent(config: RunnableConfig)` registered in `langgraph.json`
+- Dynamic model selection via `create_chat_model()` with thinking/vision support
+- Tools loaded via `get_available_tools()` - combines sandbox, built-in, MCP, community, and subagent tools
+- System prompt generated by `apply_prompt_template()` with skills, memory, and subagent instructions
+
+**ThreadState** (`packages/harness/deerflow/agents/thread_state.py`):
+- Extends `AgentState` with: `sandbox`, `thread_data`, `title`, `artifacts`, `todos`, `uploaded_files`, `viewed_images`
+- Uses custom reducers: `merge_artifacts` (deduplicate), `merge_viewed_images` (merge/clear)
+
+**Runtime Configuration** (via `config.configurable`):
+- `thinking_enabled` - Enable model's extended thinking
+- `model_name` - Select specific LLM model
+- `is_plan_mode` - Enable TodoList middleware
+- `subagent_enabled` - Enable task delegation tool
+
+### Middleware Chain
+
+Lead-agent middlewares are assembled in strict append order across `packages/harness/deerflow/agents/middlewares/tool_error_handling_middleware.py` (`build_lead_runtime_middlewares`) and `packages/harness/deerflow/agents/lead_agent/agent.py` (`_build_middlewares`):
+
+1. **ThreadDataMiddleware** - Creates per-thread directories under the user's isolation scope (`backend/.deer-flow/users/{user_id}/threads/{thread_id}/user-data/{workspace,uploads,outputs}`); resolves `user_id` via `get_effective_user_id()` (falls back to `"default"` in no-auth mode); Web UI thread deletion now follows LangGraph thread removal with Gateway cleanup of the local thread directory
+2. **UploadsMiddleware** - Tracks and injects newly uploaded files into conversation
+3. **SandboxMiddleware** - Acquires sandbox, stores `sandbox_id` in state
+4. **DanglingToolCallMiddleware** - Injects placeholder ToolMessages for AIMessage tool_calls that lack responses (e.g., due to user interruption), including raw provider tool-call payloads preserved only in `additional_kwargs["tool_calls"]`
+5. **LLMErrorHandlingMiddleware** - Normalizes provider/model invocation failures into recoverable assistant-facing errors before later middleware/tool stages run
+6. **GuardrailMiddleware** - Pre-tool-call authorization via pluggable `GuardrailProvider` protocol (optional, if `guardrails.enabled` in config). Evaluates each tool call and returns error ToolMessage on deny. Three provider options: built-in `AllowlistProvider` (zero deps), OAP policy providers (e.g. `aport-agent-guardrails`), or custom providers. See [docs/GUARDRAILS.md](docs/GUARDRAILS.md) for setup, usage, and how to implement a provider.
+7. **SandboxAuditMiddleware** - Audits sandboxed shell/file operations for security logging before tool execution continues
+8. **ToolErrorHandlingMiddleware** - Converts tool exceptions into error `ToolMessage`s so the run can continue instead of aborting
+9. **SummarizationMiddleware** - Context reduction when approaching token limits (optional, if enabled)
+10. **TodoListMiddleware** - Task tracking with `write_todos` tool (optional, if plan_mode)
+11. **TokenUsageMiddleware** - Records token usage metrics when token tracking is enabled (optional)
+12. **TitleMiddleware** - Auto-generates thread title after first complete exchange and normalizes structured message content before prompting the title model
+13. **MemoryMiddleware** - Queues conversations for async memory update (filters to user + final AI responses)
+14. **ViewImageMiddleware** - Injects base64 image data before LLM call (conditional on vision support)
+15. **DeferredToolFilterMiddleware** - Hides deferred tool schemas from the bound model until tool search is enabled (optional)
+16. **SubagentLimitMiddleware** - Truncates excess `task` tool calls from model response to enforce `MAX_CONCURRENT_SUBAGENTS` limit (optional, if `subagent_enabled`)
+17. **LoopDetectionMiddleware** - Detects repeated tool-call loops; hard-stop responses clear both structured `tool_calls` and raw provider tool-call metadata before forcing a final text answer
+18. **ClarificationMiddleware** - Intercepts `ask_clarification` tool calls, interrupts via `Command(goto=END)` (must be last)
+
+### Configuration System
+
+**Main Configuration** (`config.yaml`):
+
+Setup: Copy `config.example.yaml` to `config.yaml` in the **project root** directory.
+
+**Config Versioning**: `config.example.yaml` has a `config_version` field. On startup, `AppConfig.from_file()` compares user version vs example version and emits a warning if outdated. Missing `config_version` = version 0. Run `make config-upgrade` to auto-merge missing fields. When changing the config schema, bump `config_version` in `config.example.yaml`.
+
+**Config Caching**: `get_app_config()` caches the parsed config, but automatically reloads it when the resolved config path changes or the file's mtime increases. This keeps Gateway and LangGraph reads aligned with `config.yaml` edits without requiring a manual process restart.
+
+Configuration priority:
+1. Explicit `config_path` argument
+2. `DEER_FLOW_CONFIG_PATH` environment variable
+3. `config.yaml` in current directory (backend/)
+4. `config.yaml` in parent directory (project root - **recommended location**)
+
+Config values starting with `$` are resolved as environment variables (e.g., `$OPENAI_API_KEY`).
+`ModelConfig` also declares `use_responses_api` and `output_version` so OpenAI `/v1/responses` can be enabled explicitly while still using `langchain_openai:ChatOpenAI`.
+
+**Extensions Configuration** (`extensions_config.json`):
+
+MCP servers and skills are configured together in `extensions_config.json` in project root:
+
+Configuration priority:
+1. Explicit `config_path` argument
+2. `DEER_FLOW_EXTENSIONS_CONFIG_PATH` environment variable
+3. `extensions_config.json` in current directory (backend/)
+4. `extensions_config.json` in parent directory (project root - **recommended location**)
+
+### Gateway API (`app/gateway/`)
+
+FastAPI application on port 8001 with health check at `GET /health`. Set `GATEWAY_ENABLE_DOCS=false` to disable `/docs`, `/redoc`, and `/openapi.json` in production (default: enabled).
+
+**Routers**:
+
+| Router | Endpoints |
+|--------|-----------|
+| **Models** (`/api/models`) | `GET /` - list models; `GET /{name}` - model details |
+| **MCP** (`/api/mcp`) | `GET /config` - get config; `PUT /config` - update config (saves to extensions_config.json) |
+| **Skills** (`/api/skills`) | `GET /` - list skills; `GET /{name}` - details; `PUT /{name}` - update enabled; `POST /install` - install from .skill archive (accepts standard optional frontmatter like `version`, `author`, `compatibility`) |
+| **Memory** (`/api/memory`) | `GET /` - memory data; `POST /reload` - force reload; `GET /config` - config; `GET /status` - config + data |
+| **Agents** (`/api/agents`) | `GET /` - list built-in, owned, and published agents; `POST /` - create user-owned agent; `GET/PUT/DELETE /{id}` - read/update/delete by stable agent id; `GET /check` - validate non-empty display name (duplicates allowed) |
+| **Uploads** (`/api/threads/{id}/uploads`) | `POST /` - upload files (auto-converts PDF/PPT/Excel/Word); `GET /list` - list; `DELETE /{filename}` - delete |
+| **Threads** (`/api/threads/{id}`) | `DELETE /` - remove DeerFlow-managed local thread data after LangGraph thread deletion; unexpected failures are logged server-side and return a generic 500 detail |
+| **Artifacts** (`/api/threads/{id}/artifacts`) | `GET /{path}` - serve artifacts; active content types (`text/html`, `application/xhtml+xml`, `image/svg+xml`) are always forced as download attachments to reduce XSS risk; `?download=true` still forces download for other file types |
+| **Suggestions** (`/api/threads/{id}/suggestions`) | `POST /` - generate follow-up questions; rich list/block model content is normalized before JSON parsing |
+| **Thread Runs** (`/api/threads/{id}/runs`) | `POST /` - create background run; `POST /stream` - create + SSE stream; `POST /wait` - create + block; `GET /` - list runs; `GET /{rid}` - run details; `POST /{rid}/cancel` - cancel; `GET /{rid}/join` - join SSE; `GET /{rid}/messages` - paginated messages `{data, has_more}`; `GET /{rid}/events` - full event stream; `GET /../messages` - thread messages with feedback; `GET /../token-usage` - aggregate tokens |
+| **Feedback** (`/api/threads/{id}/runs/{rid}/feedback`) | `PUT /` - upsert feedback; `DELETE /` - delete user feedback; `POST /` - create feedback; `GET /` - list feedback; `GET /stats` - aggregate stats; `DELETE /{fid}` - delete specific |
+| **Runs** (`/api/runs`) | `POST /stream` - stateless run + SSE; `POST /wait` - stateless run + block; `GET /{rid}/messages` - paginated messages by run_id `{data, has_more}` (cursor: `after_seq`/`before_seq`); `GET /{rid}/feedback` - list feedback by run_id |
+
+Proxied through nginx: `/api/langgraph/*` → LangGraph, all other `/api/*` → Gateway.
+
+### Custom Agent Persistence
+
+Custom agent metadata lives in the `agents` ORM table (`deerflow.persistence.agents`). `agents.id` is the stable runtime id and the filesystem directory name under `.deer-flow/agents/{id}/`; `agents.name` is display-only, can contain Chinese characters, and is not unique. `user_id IS NULL` marks built-in agents, user-owned agents are visible only to their owner unless `published = true`, and update/delete operations require ownership. The runtime accepts `agent_id` in context/configurable, and non-default `assistant_id` values are treated as agent ids after visibility checks.
+
+### Sandbox System (`packages/harness/deerflow/sandbox/`)
+
+**Interface**: Abstract `Sandbox` with `execute_command`, `read_file`, `write_file`, `list_dir`
+**Provider Pattern**: `SandboxProvider` with `acquire`, `get`, `release` lifecycle
+**Implementations**:
+- `LocalSandboxProvider` - Singleton local filesystem execution with path mappings
+- `AioSandboxProvider` (`packages/harness/deerflow/community/`) - Docker-based isolation
+
+**Virtual Path System**:
+- Agent sees: `/mnt/user-data/{workspace,uploads,outputs}`, `/mnt/skills`
+- Physical: `backend/.deer-flow/users/{user_id}/threads/{thread_id}/user-data/...`, `deer-flow/skills/`
+- Translation: `replace_virtual_path()` / `replace_virtual_paths_in_command()`
+- Detection: `is_local_sandbox()` checks `sandbox_id == "local"`
+
+**Sandbox Tools** (in `packages/harness/deerflow/sandbox/tools.py`):
+- `bash` - Execute commands with path translation and error handling
+- `ls` - Directory listing (tree format, max 2 levels)
+- `read_file` - Read file contents with optional line range
+- `write_file` - Write/append to files, creates directories
+- `str_replace` - Substring replacement (single or all occurrences); same-path serialization is scoped to `(sandbox.id, path)` so isolated sandboxes do not contend on identical virtual paths inside one process
+
+### Subagent System (`packages/harness/deerflow/subagents/`)
+
+**Built-in Agents**: `general-purpose` (all tools except `task`) and `bash` (command specialist)
+**Execution**: Dual thread pool - `_scheduler_pool` (3 workers) + `_execution_pool` (3 workers)
+**Concurrency**: `MAX_CONCURRENT_SUBAGENTS = 3` enforced by `SubagentLimitMiddleware` (truncates excess tool calls in `after_model`), 15-minute timeout
+**Flow**: `task()` tool → `SubagentExecutor` → background thread → poll 5s → SSE events → result
+**Events**: `task_started`, `task_running`, `task_completed`/`task_failed`/`task_timed_out`
+
+### Tool System (`packages/harness/deerflow/tools/`)
+
+`get_available_tools(groups, include_mcp, model_name, subagent_enabled)` assembles:
+1. **Config-defined tools** - Resolved from `config.yaml` via `resolve_variable()`
+2. **MCP tools** - From enabled MCP servers (lazy initialized, cached with mtime invalidation)
+3. **Built-in tools**:
+   - `present_files` - Make output files visible to user (only `/mnt/user-data/outputs`)
+   - `ask_clarification` - Request clarification (intercepted by ClarificationMiddleware → interrupts)
+   - `view_image` - Read image as base64 (added only if model supports vision)
+4. **Subagent tool** (if enabled):
+   - `task` - Delegate to subagent (description, prompt, subagent_type, max_turns)
+
+**Community tools** (`packages/harness/deerflow/community/`):
+- `tavily/` - Web search (5 results default) and web fetch (4KB limit)
+- `jina_ai/` - Web fetch via Jina reader API with readability extraction
+- `firecrawl/` - Web scraping via Firecrawl API
+
+**ACP agent tools**:
+- `invoke_acp_agent` - Invokes external ACP-compatible agents from `config.yaml`
+- ACP launchers must be real ACP adapters. The standard `codex` CLI is not ACP-compatible by itself; configure a wrapper such as `npx -y @zed-industries/codex-acp` or an installed `codex-acp` binary
+- Missing ACP executables now return an actionable error message instead of a raw `[Errno 2]`
+- Each ACP agent uses a per-thread workspace at `{base_dir}/users/{user_id}/threads/{thread_id}/acp-workspace/`. The workspace is accessible to the lead agent via the virtual path `/mnt/acp-workspace/` (read-only). In docker sandbox mode, the directory is volume-mounted into the container at `/mnt/acp-workspace` (read-only); in local sandbox mode, path translation is handled by `tools.py`
+- `image_search/` - Image search via DuckDuckGo
+
+### MCP System (`packages/harness/deerflow/mcp/`)
+
+- Uses `langchain-mcp-adapters` `MultiServerMCPClient` for multi-server management
+- **Lazy initialization**: Tools loaded on first use via `get_cached_mcp_tools()`
+- **Cache invalidation**: Detects config file changes via mtime comparison
+- **Transports**: stdio (command-based), SSE, HTTP
+- **OAuth (HTTP/SSE)**: Supports token endpoint flows (`client_credentials`, `refresh_token`) with automatic token refresh + Authorization header injection
+- **Runtime updates**: Gateway API saves to extensions_config.json; LangGraph detects via mtime
+
+### Skills System (`packages/harness/deerflow/skills/`)
+
+- **Location**: `deer-flow/skills/{public,custom}/`
+- **Format**: Directory with `SKILL.md` (YAML frontmatter: name, description, license, allowed-tools)
+- **Loading**: `load_skills()` recursively scans `skills/{public,custom}` for `SKILL.md`, parses metadata, and reads enabled state from extensions_config.json
+- **Injection**: Enabled skills listed in agent system prompt with container paths
+- **Installation**: `POST /api/skills/install` extracts .skill ZIP archive to custom/ directory
+
+### Model Factory (`packages/harness/deerflow/models/factory.py`)
+
+- `create_chat_model(name, thinking_enabled)` instantiates LLM from config via reflection
+- Supports `thinking_enabled` flag with per-model `when_thinking_enabled` overrides
+- Supports vLLM-style thinking toggles via `when_thinking_enabled.extra_body.chat_template_kwargs.enable_thinking` for Qwen reasoning models, while normalizing legacy `thinking` configs for backward compatibility
+- Supports `supports_vision` flag for image understanding models
+- Config values starting with `$` resolved as environment variables
+- Missing provider modules surface actionable install hints from reflection resolvers (for example `uv add langchain-google-genai`)
+
+### vLLM Provider (`packages/harness/deerflow/models/vllm_provider.py`)
+
+- `VllmChatModel` subclasses `langchain_openai:ChatOpenAI` for vLLM 0.19.0 OpenAI-compatible endpoints
+- Preserves vLLM's non-standard assistant `reasoning` field on full responses, streaming deltas, and follow-up tool-call turns
+- Designed for configs that enable thinking through `extra_body.chat_template_kwargs.enable_thinking` on vLLM 0.19.0 Qwen reasoning models, while accepting the older `thinking` alias
+
+### IM Channels System (`app/channels/`)
+
+Bridges external messaging platforms (Feishu, Slack, Telegram, DingTalk) to the DeerFlow agent via the LangGraph Server.
+
+
+**Architecture**: Channels communicate with Gateway through the `langgraph-sdk` HTTP client (same as the frontend), ensuring threads are created and managed server-side. The internal SDK client injects process-local internal auth plus a matching CSRF cookie/header pair so Gateway accepts state-changing thread/run requests from channel workers without relying on browser session cookies.
+
+**Components**:
+- `message_bus.py` - Async pub/sub hub (`InboundMessage` → queue → dispatcher; `OutboundMessage` → callbacks → channels)
+- `store.py` - JSON-file persistence mapping `channel_name:chat_id[:topic_id]` → `thread_id` (keys are `channel:chat` for root conversations and `channel:chat:topic` for threaded conversations)
+- `manager.py` - Core dispatcher: creates threads via `client.threads.create()`, routes commands, keeps Slack/Telegram on `client.runs.wait()`, and uses `client.runs.stream(["messages-tuple", "values"])` for Feishu incremental outbound updates
+- `base.py` - Abstract `Channel` base class (start/stop/send lifecycle)
+- `service.py` - Manages lifecycle of all configured channels from `config.yaml`
+- `slack.py` / `feishu.py` / `telegram.py` / `dingtalk.py` - Platform-specific implementations (`feishu.py` tracks the running card `message_id` in memory and patches the same card in place; `dingtalk.py` optionally uses AI Card streaming for in-place updates when `card_template_id` is configured)
+
+**Message Flow**:
+1. External platform -> Channel impl -> `MessageBus.publish_inbound()`
+2. `ChannelManager._dispatch_loop()` consumes from queue
+3. For chat: look up/create thread through Gateway's LangGraph-compatible API
+4. Feishu chat: `runs.stream()` → accumulate AI text → publish multiple outbound updates (`is_final=False`) → publish final outbound (`is_final=True`)
+5. Slack/Telegram chat: `runs.wait()` → extract final response → publish outbound
+6. Feishu channel sends one running reply card up front, then patches the same card for each outbound update (card JSON sets `config.update_multi=true` for Feishu's patch API requirement)
+7. DingTalk AI Card mode (when `card_template_id` configured): `runs.stream()` → create card with initial text → stream updates via `PUT /v1.0/card/streaming` → finalize on `is_final=True`. Falls back to `sampleMarkdown` if card creation or streaming fails
+8. For commands (`/new`, `/status`, `/models`, `/memory`, `/help`): handle locally or query Gateway API
+9. Outbound → channel callbacks → platform reply
+
+**Configuration** (`config.yaml` -> `channels`):
+- `langgraph_url` - LangGraph-compatible Gateway API base URL (default: `http://localhost:8001/api`)
+- `gateway_url` - Gateway API URL for auxiliary commands (default: `http://localhost:8001`)
+- In Docker Compose, IM channels run inside the `gateway` container, so `localhost` points back to that container. Use `http://gateway:8001/api` for `langgraph_url` and `http://gateway:8001` for `gateway_url`, or set `DEER_FLOW_CHANNELS_LANGGRAPH_URL` / `DEER_FLOW_CHANNELS_GATEWAY_URL`.
+- Per-channel configs: `feishu` (app_id, app_secret), `slack` (bot_token, app_token), `telegram` (bot_token), `dingtalk` (client_id, client_secret, optional `card_template_id` for AI Card streaming)
+
+
+### Memory System (`packages/harness/deerflow/agents/memory/`)
+
+**Components**:
+- `updater.py` - LLM-based memory updates with fact extraction, whitespace-normalized fact deduplication (trims leading/trailing whitespace before comparing), and atomic file I/O
+- `queue.py` - Debounced update queue (per-thread deduplication, configurable wait time); captures `user_id` at enqueue time so it survives the `threading.Timer` boundary
+- `prompt.py` - Prompt templates for memory updates
+- `storage.py` - File-based storage with per-user isolation; cache keyed by `(user_id, agent_name)` tuple
+
+**Per-User Isolation**:
+- Memory is stored per-user at `{base_dir}/users/{user_id}/memory.json`
+- Per-agent per-user memory at `{base_dir}/users/{user_id}/agents/{agent_name}/memory.json`
+- `user_id` is resolved via `get_effective_user_id()` from `deerflow.runtime.user_context`
+- In no-auth mode, `user_id` defaults to `"default"` (constant `DEFAULT_USER_ID`)
+- Absolute `storage_path` in config opts out of per-user isolation
+- **Migration**: Run `PYTHONPATH=. python scripts/migrate_user_isolation.py` to move legacy `memory.json` and `threads/` into per-user layout; supports `--dry-run`
+
+**Data Structure** (stored in `{base_dir}/users/{user_id}/memory.json`):
+- **User Context**: `workContext`, `personalContext`, `topOfMind` (1-3 sentence summaries)
+- **History**: `recentMonths`, `earlierContext`, `longTermBackground`
+- **Facts**: Discrete facts with `id`, `content`, `category` (preference/knowledge/context/behavior/goal), `confidence` (0-1), `createdAt`, `source`
+
+**Workflow**:
+1. `MemoryMiddleware` filters messages (user inputs + final AI responses), captures `user_id` via `get_effective_user_id()`, and queues conversation with the captured `user_id`
+2. Queue debounces (30s default), batches updates, deduplicates per-thread
+3. Background thread invokes LLM to extract context updates and facts, using the stored `user_id` (not the contextvar, which is unavailable on timer threads)
+4. Applies updates atomically (temp file + rename) with cache invalidation, skipping duplicate fact content before append
+5. Next interaction injects top 15 facts + context into `<memory>` tags in system prompt
+
+Focused regression coverage for the updater lives in `backend/tests/test_memory_updater.py`.
+
+**Configuration** (`config.yaml` → `memory`):
+- `enabled` / `injection_enabled` - Master switches
+- `storage_path` - Path to memory.json (absolute path opts out of per-user isolation)
+- `debounce_seconds` - Wait time before processing (default: 30)
+- `model_name` - LLM for updates (null = default model)
+- `max_facts` / `fact_confidence_threshold` - Fact storage limits (100 / 0.7)
+- `max_injection_tokens` - Token limit for prompt injection (2000)
+
+### Reflection System (`packages/harness/deerflow/reflection/`)
+
+- `resolve_variable(path)` - Import module and return variable (e.g., `module.path:variable_name`)
+- `resolve_class(path, base_class)` - Import and validate class against base class
+
+### Config Schema
+
+**`config.yaml`** key sections:
+- `models[]` - LLM configs with `use` class path, `supports_thinking`, `supports_vision`, provider-specific fields
+- vLLM reasoning models should use `deerflow.models.vllm_provider:VllmChatModel`; for Qwen-style parsers prefer `when_thinking_enabled.extra_body.chat_template_kwargs.enable_thinking`, and DeerFlow will also normalize the older `thinking` alias
+- `tools[]` - Tool configs with `use` variable path and `group`
+- `tool_groups[]` - Logical groupings for tools
+- `sandbox.use` - Sandbox provider class path
+- `skills.path` / `skills.container_path` - Host and container paths to skills directory
+- `title` - Auto-title generation (enabled, max_words, max_chars, prompt_template)
+- `summarization` - Context summarization (enabled, trigger conditions, keep policy)
+- `subagents.enabled` - Master switch for subagent delegation
+- `memory` - Memory system (enabled, storage_path, debounce_seconds, model_name, max_facts, fact_confidence_threshold, injection_enabled, max_injection_tokens)
+
+**`extensions_config.json`**:
+- `mcpServers` - Map of server name → config (enabled, type, command, args, env, url, headers, oauth, description)
+- `skills` - Map of skill name → state (enabled)
+
+Both can be modified at runtime via Gateway API endpoints or `DeerFlowClient` methods.
+
+### Embedded Client (`packages/harness/deerflow/client.py`)
+
+`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.
+
+**Architecture**: Imports the same `deerflow` modules that Gateway API uses. Shares the same config files and data directories. No FastAPI dependency.
+
+**Agent Conversation**:
+- `chat(message, thread_id)` — synchronous, accumulates streaming deltas per message-id and returns the final AI text
+- `stream(message, thread_id)` — subscribes to LangGraph `stream_mode=["values", "messages", "custom"]` and yields `StreamEvent`:
+  - `"values"` — full state snapshot (title, messages, artifacts); AI text already delivered via `messages` mode is **not** re-synthesized here to avoid duplicate deliveries
+  - `"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
+  - `"custom"` — forwarded from `StreamWriter`
+  - `"end"` — stream finished (carries cumulative `usage` counted once per message id)
+- Agent created lazily via `create_agent()` + `_build_middlewares()`, same as `make_lead_agent`
+- Supports `checkpointer` parameter for state persistence across turns
+- `reset_agent()` forces agent recreation (e.g. after memory or skill changes)
+- 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
+
+**Gateway Equivalent Methods** (replaces Gateway API):
+
+| Category | Methods | Return format |
+|----------|---------|---------------|
+| Models | `list_models()`, `get_model(name)` | `{"models": [...]}`, `{name, display_name, ...}` |
+| MCP | `get_mcp_config()`, `update_mcp_config(servers)` | `{"mcp_servers": {...}}` |
+| Skills | `list_skills()`, `get_skill(name)`, `update_skill(name, enabled)`, `install_skill(path)` | `{"skills": [...]}` |
+| Memory | `get_memory()`, `reload_memory()`, `get_memory_config()`, `get_memory_status()` | dict |
+| Uploads | `upload_files(thread_id, files)`, `list_uploads(thread_id)`, `delete_upload(thread_id, filename)` | `{"success": true, "files": [...]}`, `{"files": [...], "count": N}` |
+| Artifacts | `get_artifact(thread_id, path)` → `(bytes, mime_type)` | tuple |
+
+**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.
+
+**Tests**: `tests/test_client.py` (77 unit tests including `TestGatewayConformance`), `tests/test_client_live.py` (live integration tests, requires config.yaml)
+
+**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`.
+
+## Development Workflow
+
+### Test-Driven Development (TDD) — MANDATORY
+
+**Every new feature or bug fix MUST be accompanied by unit tests. No exceptions.**
+
+- Write tests in `backend/tests/` following the existing naming convention `test_<feature>.py`
+- Run the full suite before and after your change: `make test`
+- Tests must pass before a feature is considered complete
+- For lightweight config/utility modules, prefer pure unit tests with no external dependencies
+- If a module causes circular import issues in tests, add a `sys.modules` mock in `tests/conftest.py` (see existing example for `deerflow.subagents.executor`)
+
+```bash
+# Run all tests
+make test
+
+# Run a specific test file
+PYTHONPATH=. uv run pytest tests/test_<feature>.py -v
+```
+
+### Running the Full Application
+
+From the **project root** directory:
+```bash
+make dev
+```
+
+This starts all services and makes the application available at `http://localhost:2026`.
+
+**All startup modes:**
+
+| | **Local Foreground** | **Local Daemon** | **Docker Dev** | **Docker Prod** |
+|---|---|---|---|---|
+| **Dev** | `./scripts/serve.sh --dev`<br/>`make dev` | `./scripts/serve.sh --dev --daemon`<br/>`make dev-daemon` | `./scripts/docker.sh start`<br/>`make docker-start` | — |
+| **Prod** | `./scripts/serve.sh --prod`<br/>`make start` | `./scripts/serve.sh --prod --daemon`<br/>`make start-daemon` | — | `./scripts/deploy.sh`<br/>`make up` |
+
+| Action | Local | Docker Dev | Docker Prod |
+|---|---|---|---|
+| **Stop** | `./scripts/serve.sh --stop`<br/>`make stop` | `./scripts/docker.sh stop`<br/>`make docker-stop` | `./scripts/deploy.sh down`<br/>`make down` |
+| **Restart** | `./scripts/serve.sh --restart [flags]` | `./scripts/docker.sh restart` | — |
+
+**Nginx routing**:
+- `/api/langgraph/*` → Gateway embedded runtime (8001), rewritten to `/api/*`
+- `/api/*` (other) → Gateway API (8001)
+- `/` (non-API) → Frontend (3000)
+
+### Running Backend Services Separately
+
+From the **backend** directory:
+
+```bash
+# Gateway API
+make gateway
+```
+
+Direct access (without nginx):
+- Gateway: `http://localhost:8001`
+
+### Frontend Configuration
+
+The frontend uses environment variables to connect to backend services:
+- `NEXT_PUBLIC_LANGGRAPH_BASE_URL` - Defaults to `/api/langgraph` (through nginx)
+- `NEXT_PUBLIC_BACKEND_BASE_URL` - Defaults to empty string (through nginx)
+
+When using `make dev` from root, the frontend automatically connects through nginx.
+
+## Key Features
+
+### File Upload
+
+Multi-file upload with automatic document conversion:
+- Endpoint: `POST /api/threads/{thread_id}/uploads`
+- Supports: PDF, PPT, Excel, Word documents (converted via `markitdown`)
+- Rejects directory inputs before copying so uploads stay all-or-nothing
+- Reuses one conversion worker per request when called from an active event loop
+- Files stored in thread-isolated directories
+- Agent receives uploaded file list via `UploadsMiddleware`
+
+See [docs/FILE_UPLOAD.md](docs/FILE_UPLOAD.md) for details.
+
+### Plan Mode
+
+TodoList middleware for complex multi-step tasks:
+- Controlled via runtime config: `config.configurable.is_plan_mode = True`
+- Provides `write_todos` tool for task tracking
+- One task in_progress at a time, real-time updates
+
+See [docs/plan_mode_usage.md](docs/plan_mode_usage.md) for details.
+
+### Context Summarization
+
+Automatic conversation summarization when approaching token limits:
+- Configured in `config.yaml` under `summarization` key
+- Trigger types: tokens, messages, or fraction of max input
+- Keeps recent messages while summarizing older ones
+
+See [docs/summarization.md](docs/summarization.md) for details.
+
+### Vision Support
+
+For models with `supports_vision: true`:
+- `ViewImageMiddleware` processes images in conversation
+- `view_image_tool` added to agent's toolset
+- Images automatically converted to base64 and injected into state
+
+## Code Style
+
+- Uses `ruff` for linting and formatting
+- Line length: 240 characters
+- Python 3.12+ with type hints
+- Double quotes, space indentation
+
+## Documentation
+
+See `docs/` directory for detailed documentation:
+- [CONFIGURATION.md](docs/CONFIGURATION.md) - Configuration options
+- [ARCHITECTURE.md](docs/ARCHITECTURE.md) - Architecture details
+- [API.md](docs/API.md) - API reference
+- [SETUP.md](docs/SETUP.md) - Setup guide
+- [FILE_UPLOAD.md](docs/FILE_UPLOAD.md) - File upload feature
+- [PATH_EXAMPLES.md](docs/PATH_EXAMPLES.md) - Path types and usage
+- [summarization.md](docs/summarization.md) - Context summarization
+- [plan_mode_usage.md](docs/plan_mode_usage.md) - Plan mode with TodoList

offline-backend-20260512/backend/CONTRIBUTING.md

@@ -0,0 +1,426 @@
+# Contributing to DeerFlow Backend
+
+Thank you for your interest in contributing to DeerFlow! This document provides guidelines and instructions for contributing to the backend codebase.
+
+## Table of Contents
+
+- [Getting Started](#getting-started)
+- [Development Setup](#development-setup)
+- [Project Structure](#project-structure)
+- [Code Style](#code-style)
+- [Making Changes](#making-changes)
+- [Testing](#testing)
+- [Pull Request Process](#pull-request-process)
+- [Architecture Guidelines](#architecture-guidelines)
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.12 or higher
+- [uv](https://docs.astral.sh/uv/) package manager
+- Git
+- Docker (optional, for Docker sandbox testing)
+
+### Fork and Clone
+
+1. Fork the repository on GitHub
+2. Clone your fork locally:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/deer-flow.git
+   cd deer-flow
+   ```
+
+## Development Setup
+
+### Install Dependencies
+
+```bash
+# From project root
+cp config.example.yaml config.yaml
+
+# Install backend dependencies
+cd backend
+make install
+```
+
+### Configure Environment
+
+Set up your API keys for testing:
+
+```bash
+export OPENAI_API_KEY="your-api-key"
+# Add other keys as needed
+```
+
+### Run the Development Server
+
+```bash
+# Terminal 1: LangGraph server
+make dev
+
+# Terminal 2: Gateway API
+make gateway
+```
+
+## Project Structure
+
+```
+backend/src/
+├── agents/                  # Agent system
+│   ├── lead_agent/         # Main agent implementation
+│   │   └── agent.py        # Agent factory and creation
+│   ├── middlewares/        # Agent middlewares
+│   │   ├── thread_data_middleware.py
+│   │   ├── sandbox_middleware.py
+│   │   ├── title_middleware.py
+│   │   ├── uploads_middleware.py
+│   │   ├── view_image_middleware.py
+│   │   └── clarification_middleware.py
+│   └── thread_state.py     # Thread state definition
+│
+├── gateway/                 # FastAPI Gateway
+│   ├── app.py              # FastAPI application
+│   └── routers/            # Route handlers
+│       ├── models.py       # /api/models endpoints
+│       ├── mcp.py          # /api/mcp endpoints
+│       ├── skills.py       # /api/skills endpoints
+│       ├── artifacts.py    # /api/threads/.../artifacts
+│       └── uploads.py      # /api/threads/.../uploads
+│
+├── sandbox/                 # Sandbox execution
+│   ├── __init__.py         # Sandbox interface
+│   ├── local.py            # Local sandbox provider
+│   └── tools.py            # Sandbox tools (bash, file ops)
+│
+├── tools/                   # Agent tools
+│   └── builtins/           # Built-in tools
+│       ├── present_file_tool.py
+│       ├── ask_clarification_tool.py
+│       └── view_image_tool.py
+│
+├── mcp/                     # MCP integration
+│   └── manager.py          # MCP server management
+│
+├── models/                  # Model system
+│   └── factory.py          # Model factory
+│
+├── skills/                  # Skills system
+│   └── loader.py           # Skills loader
+│
+├── config/                  # Configuration
+│   ├── app_config.py       # Main app config
+│   ├── extensions_config.py # Extensions config
+│   └── summarization_config.py
+│
+├── community/               # Community tools
+│   ├── tavily/             # Tavily web search
+│   ├── jina/               # Jina web fetch
+│   ├── firecrawl/          # Firecrawl scraping
+│   └── aio_sandbox/        # Docker sandbox
+│
+├── reflection/              # Dynamic loading
+│   └── __init__.py         # Module resolution
+│
+└── utils/                   # Utilities
+    └── __init__.py
+```
+
+## Code Style
+
+### Linting and Formatting
+
+We use `ruff` for both linting and formatting:
+
+```bash
+# Check for issues
+make lint
+
+# Auto-fix and format
+make format
+```
+
+### Style Guidelines
+
+- **Line length**: 240 characters maximum
+- **Python version**: 3.12+ features allowed
+- **Type hints**: Use type hints for function signatures
+- **Quotes**: Double quotes for strings
+- **Indentation**: 4 spaces (no tabs)
+- **Imports**: Group by standard library, third-party, local
+
+### Docstrings
+
+Use docstrings for public functions and classes:
+
+```python
+def create_chat_model(name: str, thinking_enabled: bool = False) -> BaseChatModel:
+    """Create a chat model instance from configuration.
+
+    Args:
+        name: The model name as defined in config.yaml
+        thinking_enabled: Whether to enable extended thinking
+
+    Returns:
+        A configured LangChain chat model instance
+
+    Raises:
+        ValueError: If the model name is not found in configuration
+    """
+    ...
+```
+
+## Making Changes
+
+### Branch Naming
+
+Use descriptive branch names:
+
+- `feature/add-new-tool` - New features
+- `fix/sandbox-timeout` - Bug fixes
+- `docs/update-readme` - Documentation
+- `refactor/config-system` - Code refactoring
+
+### Commit Messages
+
+Write clear, concise commit messages:
+
+```
+feat: add support for Claude 3.5 model
+
+- Add model configuration in config.yaml
+- Update model factory to handle Claude-specific settings
+- Add tests for new model
+```
+
+Prefix types:
+- `feat:` - New feature
+- `fix:` - Bug fix
+- `docs:` - Documentation
+- `refactor:` - Code refactoring
+- `test:` - Tests
+- `chore:` - Build/config changes
+
+## Testing
+
+### Running Tests
+
+```bash
+uv run pytest
+```
+
+### Writing Tests
+
+Place tests in the `tests/` directory mirroring the source structure:
+
+```
+tests/
+├── test_models/
+│   └── test_factory.py
+├── test_sandbox/
+│   └── test_local.py
+└── test_gateway/
+    └── test_models_router.py
+```
+
+Example test:
+
+```python
+import pytest
+from deerflow.models.factory import create_chat_model
+
+def test_create_chat_model_with_valid_name():
+    """Test that a valid model name creates a model instance."""
+    model = create_chat_model("gpt-4")
+    assert model is not None
+
+def test_create_chat_model_with_invalid_name():
+    """Test that an invalid model name raises ValueError."""
+    with pytest.raises(ValueError):
+        create_chat_model("nonexistent-model")
+```
+
+## Pull Request Process
+
+### Before Submitting
+
+1. **Ensure tests pass**: `uv run pytest`
+2. **Run linter**: `make lint`
+3. **Format code**: `make format`
+4. **Update documentation** if needed
+
+### PR Description
+
+Include in your PR description:
+
+- **What**: Brief description of changes
+- **Why**: Motivation for the change
+- **How**: Implementation approach
+- **Testing**: How you tested the changes
+
+### Review Process
+
+1. Submit PR with clear description
+2. Address review feedback
+3. Ensure CI passes
+4. Maintainer will merge when approved
+
+## Architecture Guidelines
+
+### Adding New Tools
+
+1. Create tool in `packages/harness/deerflow/tools/builtins/` or `packages/harness/deerflow/community/`:
+
+```python
+# packages/harness/deerflow/tools/builtins/my_tool.py
+from langchain_core.tools import tool
+
+@tool
+def my_tool(param: str) -> str:
+    """Tool description for the agent.
+
+    Args:
+        param: Description of the parameter
+
+    Returns:
+        Description of return value
+    """
+    return f"Result: {param}"
+```
+
+2. Register in `config.yaml`:
+
+```yaml
+tools:
+  - name: my_tool
+    group: my_group
+    use: deerflow.tools.builtins.my_tool:my_tool
+```
+
+### Adding New Middleware
+
+1. Create middleware in `packages/harness/deerflow/agents/middlewares/`:
+
+```python
+# packages/harness/deerflow/agents/middlewares/my_middleware.py
+from langchain.agents.middleware import BaseMiddleware
+from langchain_core.runnables import RunnableConfig
+
+class MyMiddleware(BaseMiddleware):
+    """Middleware description."""
+
+    def transform_state(self, state: dict, config: RunnableConfig) -> dict:
+        """Transform the state before agent execution."""
+        # Modify state as needed
+        return state
+```
+
+2. Register in `packages/harness/deerflow/agents/lead_agent/agent.py`:
+
+```python
+middlewares = [
+    ThreadDataMiddleware(),
+    SandboxMiddleware(),
+    MyMiddleware(),  # Add your middleware
+    TitleMiddleware(),
+    ClarificationMiddleware(),
+]
+```
+
+### Adding New API Endpoints
+
+1. Create router in `app/gateway/routers/`:
+
+```python
+# app/gateway/routers/my_router.py
+from fastapi import APIRouter
+
+router = APIRouter(prefix="/my-endpoint", tags=["my-endpoint"])
+
+@router.get("/")
+async def get_items():
+    """Get all items."""
+    return {"items": []}
+
+@router.post("/")
+async def create_item(data: dict):
+    """Create a new item."""
+    return {"created": data}
+```
+
+2. Register in `app/gateway/app.py`:
+
+```python
+from app.gateway.routers import my_router
+
+app.include_router(my_router.router)
+```
+
+### Configuration Changes
+
+When adding new configuration options:
+
+1. Update `packages/harness/deerflow/config/app_config.py` with new fields
+2. Add default values in `config.example.yaml`
+3. Document in `docs/CONFIGURATION.md`
+
+### MCP Server Integration
+
+To add support for a new MCP server:
+
+1. Add configuration in `extensions_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "enabled": true,
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@my-org/mcp-server"],
+      "description": "My MCP Server"
+    }
+  }
+}
+```
+
+2. Update `extensions_config.example.json` with the new server
+
+### Skills Development
+
+To create a new skill:
+
+1. Create directory in `skills/public/` or `skills/custom/`:
+
+```
+skills/public/my-skill/
+└── SKILL.md
+```
+
+2. Write `SKILL.md` with YAML front matter:
+
+```markdown
+---
+name: My Skill
+description: What this skill does
+license: MIT
+allowed-tools:
+  - read_file
+  - write_file
+  - bash
+---
+
+# My Skill
+
+Instructions for the agent when this skill is enabled...
+```
+
+## Questions?
+
+If you have questions about contributing:
+
+1. Check existing documentation in `docs/`
+2. Look for similar issues or PRs on GitHub
+3. Open a discussion or issue on GitHub
+
+Thank you for contributing to DeerFlow!

offline-backend-20260512/backend/Dockerfile

@@ -0,0 +1,91 @@
+# Backend Dockerfile — multi-stage build
+# Stage 1 (builder): compiles native Python extensions with build-essential
+# Stage 2 (dev):     retains toolchain for dev containers (uv sync at startup)
+# Stage 3 (runtime): clean image without compiler toolchain for production
+
+# UV source image (override for restricted networks that cannot reach ghcr.io)
+ARG UV_IMAGE=ghcr.io/astral-sh/uv:0.7.20
+FROM ${UV_IMAGE} AS uv-source
+
+# ── Stage 1: Builder ──────────────────────────────────────────────────────────
+FROM python:3.12-slim-bookworm AS builder
+
+ARG NODE_MAJOR=22
+ARG APT_MIRROR
+ARG UV_INDEX_URL
+# Optional extras to install (e.g. "postgres" for PostgreSQL support)
+# Usage: docker build --build-arg UV_EXTRAS=postgres ...
+ARG UV_EXTRAS
+
+# Optionally override apt mirror for restricted networks (e.g. APT_MIRROR=mirrors.aliyun.com)
+RUN if [ -n "${APT_MIRROR}" ]; then \
+      sed -i "s|deb.debian.org|${APT_MIRROR}|g" /etc/apt/sources.list.d/debian.sources 2>/dev/null || true; \
+      sed -i "s|deb.debian.org|${APT_MIRROR}|g" /etc/apt/sources.list 2>/dev/null || true; \
+    fi
+
+# Install build tools + Node.js (build-essential needed for native Python extensions)
+RUN apt-get update && apt-get install -y \
+    curl \
+    build-essential \
+    gnupg \
+    ca-certificates \
+    && mkdir -p /etc/apt/keyrings \
+    && curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg \
+    && echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_${NODE_MAJOR}.x nodistro main" > /etc/apt/sources.list.d/nodesource.list \
+    && apt-get update \
+    && apt-get install -y nodejs \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install uv (source image overridable via UV_IMAGE build arg)
+COPY --from=uv-source /uv /uvx /usr/local/bin/
+
+# Set working directory
+WORKDIR /app
+
+# Copy backend source code
+COPY backend ./backend
+
+# Install dependencies with cache mount
+# When UV_EXTRAS is set (e.g. "postgres"), installs optional dependencies.
+RUN --mount=type=cache,target=/root/.cache/uv \
+    sh -c "cd backend && UV_INDEX_URL=${UV_INDEX_URL:-https://pypi.org/simple} uv sync ${UV_EXTRAS:+--extra $UV_EXTRAS}"
+
+# ── Stage 2: Dev ──────────────────────────────────────────────────────────────
+# Retains compiler toolchain from builder so startup-time `uv sync` can build
+# source distributions in development containers.
+FROM builder AS dev
+
+# Install Docker CLI (for DooD: allows starting sandbox containers via host Docker socket)
+COPY --from=docker:cli /usr/local/bin/docker /usr/local/bin/docker
+
+EXPOSE 8001 2024
+
+CMD ["sh", "-c", "cd backend && PYTHONPATH=. uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001"]
+
+# ── Stage 3: Runtime ──────────────────────────────────────────────────────────
+# Clean image without build-essential — reduces size (~200 MB) and attack surface.
+FROM python:3.12-slim-bookworm
+
+# Copy Node.js runtime from builder (provides npx for MCP servers)
+COPY --from=builder /usr/bin/node /usr/bin/node
+COPY --from=builder /usr/lib/node_modules /usr/lib/node_modules
+RUN ln -s ../lib/node_modules/npm/bin/npm-cli.js /usr/bin/npm \
+    && ln -s ../lib/node_modules/npm/bin/npx-cli.js /usr/bin/npx
+
+# Install Docker CLI (for DooD: allows starting sandbox containers via host Docker socket)
+COPY --from=docker:cli /usr/local/bin/docker /usr/local/bin/docker
+
+# Install uv (source image overridable via UV_IMAGE build arg)
+COPY --from=uv-source /uv /uvx /usr/local/bin/
+
+# Set working directory
+WORKDIR /app
+
+# Copy backend with pre-built virtualenv from builder
+COPY --from=builder /app/backend ./backend
+
+# Expose ports (gateway: 8001, langgraph: 2024)
+EXPOSE 8001 2024
+
+# Default command (can be overridden in docker-compose)
+CMD ["sh", "-c", "cd backend && PYTHONPATH=. uv run --no-sync uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001"]

offline-backend-20260512/backend/Makefile

@@ -0,0 +1,18 @@
+install:
+	uv sync
+
+dev:
+	PYTHONPATH=. uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001 --reload
+
+gateway:
+	PYTHONPATH=. uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001
+
+test:
+	PYTHONPATH=. uv run pytest tests/ -v
+
+lint:
+	uvx ruff check .
+	uvx ruff format --check .
+
+format:
+	uvx ruff check . --fix && uvx ruff format .

offline-backend-20260512/backend/README.md

@@ -0,0 +1,424 @@
+# DeerFlow Backend
+
+DeerFlow is a LangGraph-based AI super agent with sandbox execution, persistent memory, and extensible tool integration. The backend enables AI agents to execute code, browse the web, manage files, delegate tasks to subagents, and retain context across conversations - all in isolated, per-thread environments.
+
+---
+
+## Architecture
+
+```
+                        ┌──────────────────────────────────────┐
+                        │          Nginx (Port 2026)           │
+                        │      Unified reverse proxy           │
+                        └───────┬──────────────────┬───────────┘
+                                │                  │
+              /api/langgraph/*  │                  │  /api/* (other)
+                                ▼                  ▼
+               ┌────────────────────┐  ┌────────────────────────┐
+               │ LangGraph Server   │  │   Gateway API (8001)   │
+               │    (Port 2024)     │  │   FastAPI REST         │
+               │                    │  │                        │
+               │ ┌────────────────┐ │  │ Models, MCP, Skills,   │
+               │ │  Lead Agent    │ │  │ Memory, Uploads,       │
+               │ │  ┌──────────┐  │ │  │ Artifacts              │
+               │ │  │Middleware│  │ │  └────────────────────────┘
+               │ │  │  Chain   │  │ │
+               │ │  └──────────┘  │ │
+               │ │  ┌──────────┐  │ │
+               │ │  │  Tools   │  │ │
+               │ │  └──────────┘  │ │
+               │ │  ┌──────────┐  │ │
+               │ │  │Subagents │  │ │
+               │ │  └──────────┘  │ │
+               │ └────────────────┘ │
+               └────────────────────┘
+```
+
+**Request Routing** (via Nginx):
+- `/api/langgraph/*` → LangGraph Server - agent interactions, threads, streaming
+- `/api/*` (other) → Gateway API - models, MCP, skills, memory, artifacts, uploads, thread-local cleanup
+- `/` (non-API) → Frontend - Next.js web interface
+
+---
+
+## Core Components
+
+### Lead Agent
+
+The single LangGraph agent (`lead_agent`) is the runtime entry point, created via `make_lead_agent(config)`. It combines:
+
+- **Dynamic model selection** with thinking and vision support
+- **Middleware chain** for cross-cutting concerns (9 middlewares)
+- **Tool system** with sandbox, MCP, community, and built-in tools
+- **Subagent delegation** for parallel task execution
+- **System prompt** with skills injection, memory context, and working directory guidance
+
+### Middleware Chain
+
+Middlewares execute in strict order, each handling a specific concern:
+
+| # | Middleware | Purpose |
+|---|-----------|---------|
+| 1 | **ThreadDataMiddleware** | Creates per-thread isolated directories (workspace, uploads, outputs) |
+| 2 | **UploadsMiddleware** | Injects newly uploaded files into conversation context |
+| 3 | **SandboxMiddleware** | Acquires sandbox environment for code execution |
+| 4 | **SummarizationMiddleware** | Reduces context when approaching token limits (optional) |
+| 5 | **TodoListMiddleware** | Tracks multi-step tasks in plan mode (optional) |
+| 6 | **TitleMiddleware** | Auto-generates conversation titles after first exchange |
+| 7 | **MemoryMiddleware** | Queues conversations for async memory extraction |
+| 8 | **ViewImageMiddleware** | Injects image data for vision-capable models (conditional) |
+| 9 | **ClarificationMiddleware** | Intercepts clarification requests and interrupts execution (must be last) |
+
+### Sandbox System
+
+Per-thread isolated execution with virtual path translation:
+
+- **Abstract interface**: `execute_command`, `read_file`, `write_file`, `list_dir`
+- **Providers**: `LocalSandboxProvider` (filesystem) and `AioSandboxProvider` (Docker, in community/)
+- **Virtual paths**: `/mnt/user-data/{workspace,uploads,outputs}` → thread-specific physical directories
+- **Skills path**: `/mnt/skills` → `deer-flow/skills/` directory
+- **Skills loading**: Recursively discovers nested `SKILL.md` files under `skills/{public,custom}` and preserves nested container paths
+- **File-write safety**: `str_replace` serializes read-modify-write per `(sandbox.id, path)` so isolated sandboxes keep concurrency even when virtual paths match
+- **Tools**: `bash`, `ls`, `read_file`, `write_file`, `str_replace` (`bash` is disabled by default when using `LocalSandboxProvider`; use `AioSandboxProvider` for isolated shell access)
+
+### Subagent System
+
+Async task delegation with concurrent execution:
+
+- **Built-in agents**: `general-purpose` (full toolset) and `bash` (command specialist, exposed only when shell access is available)
+- **Concurrency**: Max 3 subagents per turn, 15-minute timeout
+- **Execution**: Background thread pools with status tracking and SSE events
+- **Flow**: Agent calls `task()` tool → executor runs subagent in background → polls for completion → returns result
+
+### Memory System
+
+LLM-powered persistent context retention across conversations:
+
+- **Automatic extraction**: Analyzes conversations for user context, facts, and preferences
+- **Structured storage**: User context (work, personal, top-of-mind), history, and confidence-scored facts
+- **Debounced updates**: Batches updates to minimize LLM calls (configurable wait time)
+- **System prompt injection**: Top facts + context injected into agent prompts
+- **Storage**: JSON file with mtime-based cache invalidation
+
+### Tool Ecosystem
+
+| Category | Tools |
+|----------|-------|
+| **Sandbox** | `bash`, `ls`, `read_file`, `write_file`, `str_replace` |
+| **Built-in** | `present_files`, `ask_clarification`, `view_image`, `task` (subagent) |
+| **Community** | Tavily (web search), Jina AI (web fetch), Firecrawl (scraping), DuckDuckGo (image search) |
+| **MCP** | Any Model Context Protocol server (stdio, SSE, HTTP transports) |
+| **Skills** | Domain-specific workflows injected via system prompt |
+
+### Gateway API
+
+FastAPI application providing REST endpoints for frontend integration:
+
+| Route | Purpose |
+|-------|---------|
+| `GET /api/models` | List available LLM models |
+| `GET/PUT /api/mcp/config` | Manage MCP server configurations |
+| `GET/PUT /api/skills` | List and manage skills |
+| `POST /api/skills/install` | Install skill from `.skill` archive |
+| `GET/POST /api/agents` | List visible agents or create a user-owned agent |
+| `GET/PUT/DELETE /api/agents/{id}` | Read, update, or delete an id-addressed agent |
+| `GET /api/memory` | Retrieve memory data |
+| `POST /api/memory/reload` | Force memory reload |
+| `GET /api/memory/config` | Memory configuration |
+| `GET /api/memory/status` | Combined config + data |
+| `POST /api/threads/{id}/uploads` | Upload files (auto-converts PDF/PPT/Excel/Word to Markdown, rejects directory paths) |
+| `GET /api/threads/{id}/uploads/list` | List uploaded files |
+| `DELETE /api/threads/{id}` | Delete DeerFlow-managed local thread data after LangGraph thread deletion; unexpected failures are logged server-side and return a generic 500 detail |
+| `GET /api/threads/{id}/artifacts/{path}` | Serve generated artifacts |
+
+### Custom Agents
+
+Custom agents are indexed in the `agents` database table. The `id` column is the stable runtime identifier and filesystem directory name (`.deer-flow/agents/{id}/SOUL.md`); `name` is display-only, may be Chinese, and may be duplicated. Rows with `user_id = NULL` are built-in agents, user rows are private unless `published = true`, and users can only update or delete agents they created.
+
+### IM Channels
+
+The IM bridge supports Feishu, Slack, and Telegram. Slack and Telegram still use the final `runs.wait()` response path, while Feishu now streams through `runs.stream(["messages-tuple", "values"])` and updates a single in-thread card in place.
+
+For Feishu card updates, DeerFlow stores the running card's `message_id` per inbound message and patches that same card until the run finishes, preserving the existing `OK` / `DONE` reaction flow.
+
+---
+
+## Quick Start
+
+### Prerequisites
+
+- Python 3.12+
+- [uv](https://docs.astral.sh/uv/) package manager
+- API keys for your chosen LLM provider
+
+### Installation
+
+```bash
+cd deer-flow
+
+# Copy configuration files
+cp config.example.yaml config.yaml
+
+# Install backend dependencies
+cd backend
+make install
+```
+
+### Configuration
+
+Edit `config.yaml` in the project root:
+
+```yaml
+models:
+  - name: gpt-4o
+    display_name: GPT-4o
+    use: langchain_openai:ChatOpenAI
+    model: gpt-4o
+    api_key: $OPENAI_API_KEY
+    supports_thinking: false
+    supports_vision: true
+
+  - name: gpt-5-responses
+    display_name: GPT-5 (Responses API)
+    use: langchain_openai:ChatOpenAI
+    model: gpt-5
+    api_key: $OPENAI_API_KEY
+    use_responses_api: true
+    output_version: responses/v1
+    supports_vision: true
+```
+
+Set your API keys:
+
+```bash
+export OPENAI_API_KEY="your-api-key-here"
+```
+
+### Running
+
+**Full Application** (from project root):
+
+```bash
+make dev  # Starts LangGraph + Gateway + Frontend + Nginx
+```
+
+Access at: http://localhost:2026
+
+**Backend Only** (from backend directory):
+
+```bash
+# Terminal 1: LangGraph server
+make dev
+
+# Terminal 2: Gateway API
+make gateway
+```
+
+Direct access: LangGraph at http://localhost:2024, Gateway at http://localhost:8001
+
+---
+
+## Project Structure
+
+```
+backend/
+├── src/
+│   ├── agents/                  # Agent system
+│   │   ├── lead_agent/         # Main agent (factory, prompts)
+│   │   ├── middlewares/        # 9 middleware components
+│   │   ├── memory/             # Memory extraction & storage
+│   │   └── thread_state.py    # ThreadState schema
+│   ├── gateway/                # FastAPI Gateway API
+│   │   ├── app.py             # Application setup
+│   │   └── routers/           # 6 route modules
+│   ├── sandbox/                # Sandbox execution
+│   │   ├── local/             # Local filesystem provider
+│   │   ├── sandbox.py         # Abstract interface
+│   │   ├── tools.py           # bash, ls, read/write/str_replace
+│   │   └── middleware.py      # Sandbox lifecycle
+│   ├── subagents/              # Subagent delegation
+│   │   ├── builtins/          # general-purpose, bash agents
+│   │   ├── executor.py        # Background execution engine
+│   │   └── registry.py        # Agent registry
+│   ├── tools/builtins/         # Built-in tools
+│   ├── mcp/                    # MCP protocol integration
+│   ├── models/                 # Model factory
+│   ├── skills/                 # Skill discovery & loading
+│   ├── config/                 # Configuration system
+│   ├── community/              # Community tools & providers
+│   ├── reflection/             # Dynamic module loading
+│   └── utils/                  # Utilities
+├── docs/                       # Documentation
+├── tests/                      # Test suite
+├── langgraph.json              # LangGraph server configuration
+├── pyproject.toml              # Python dependencies
+├── Makefile                    # Development commands
+└── Dockerfile                  # Container build
+```
+
+---
+
+## Configuration
+
+### Main Configuration (`config.yaml`)
+
+Place in project root. Config values starting with `$` resolve as environment variables.
+
+Key sections:
+- `models` - LLM configurations with class paths, API keys, thinking/vision flags
+- `tools` - Tool definitions with module paths and groups
+- `tool_groups` - Logical tool groupings
+- `sandbox` - Execution environment provider
+- `skills` - Skills directory paths
+- `title` - Auto-title generation settings
+- `summarization` - Context summarization settings
+- `subagents` - Subagent system (enabled/disabled)
+- `memory` - Memory system settings (enabled, storage, debounce, facts limits)
+
+Provider note:
+- `models[*].use` references provider classes by module path (for example `langchain_openai:ChatOpenAI`).
+- If a provider module is missing, DeerFlow now returns an actionable error with install guidance (for example `uv add langchain-google-genai`).
+
+### Extensions Configuration (`extensions_config.json`)
+
+MCP servers and skill states in a single file:
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "enabled": true,
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {"GITHUB_TOKEN": "$GITHUB_TOKEN"}
+    },
+    "secure-http": {
+      "enabled": true,
+      "type": "http",
+      "url": "https://api.example.com/mcp",
+      "oauth": {
+        "enabled": true,
+        "token_url": "https://auth.example.com/oauth/token",
+        "grant_type": "client_credentials",
+        "client_id": "$MCP_OAUTH_CLIENT_ID",
+        "client_secret": "$MCP_OAUTH_CLIENT_SECRET"
+      }
+    }
+  },
+  "skills": {
+    "pdf-processing": {"enabled": true}
+  }
+}
+```
+
+### Environment Variables
+
+- `DEER_FLOW_CONFIG_PATH` - Override config.yaml location
+- `DEER_FLOW_EXTENSIONS_CONFIG_PATH` - Override extensions_config.json location
+- Model API keys: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `DEEPSEEK_API_KEY`, etc.
+- Tool API keys: `TAVILY_API_KEY`, `GITHUB_TOKEN`, etc.
+
+### LangSmith Tracing
+
+DeerFlow has built-in [LangSmith](https://smith.langchain.com) integration for observability. When enabled, all LLM calls, agent runs, tool executions, and middleware processing are traced and visible in the LangSmith dashboard.
+
+**Setup:**
+
+1. Sign up at [smith.langchain.com](https://smith.langchain.com) and create a project.
+2. Add the following to your `.env` file in the project root:
+
+```bash
+LANGSMITH_TRACING=true
+LANGSMITH_ENDPOINT=https://api.smith.langchain.com
+LANGSMITH_API_KEY=lsv2_pt_xxxxxxxxxxxxxxxx
+LANGSMITH_PROJECT=xxx
+```
+
+**Legacy variables:** The `LANGCHAIN_TRACING_V2`, `LANGCHAIN_API_KEY`, `LANGCHAIN_PROJECT`, and `LANGCHAIN_ENDPOINT` variables are also supported for backward compatibility. `LANGSMITH_*` variables take precedence when both are set.
+
+### Langfuse Tracing
+
+DeerFlow also supports [Langfuse](https://langfuse.com) observability for LangChain-compatible runs.
+
+Add the following to your `.env` file:
+
+```bash
+LANGFUSE_TRACING=true
+LANGFUSE_PUBLIC_KEY=pk-lf-xxxxxxxxxxxxxxxx
+LANGFUSE_SECRET_KEY=sk-lf-xxxxxxxxxxxxxxxx
+LANGFUSE_BASE_URL=https://cloud.langfuse.com
+```
+
+If you are using a self-hosted Langfuse deployment, set `LANGFUSE_BASE_URL` to your Langfuse host.
+
+### Dual Provider Behavior
+
+If both LangSmith and Langfuse are enabled, DeerFlow initializes and attaches both callbacks so the same run data is reported to both systems.
+
+If a provider is explicitly enabled but required credentials are missing, or the provider callback cannot be initialized, DeerFlow raises an error when tracing is initialized during model creation instead of silently disabling tracing.
+
+**Docker:** In `docker-compose.yaml`, tracing is disabled by default (`LANGSMITH_TRACING=false`). Set `LANGSMITH_TRACING=true` and/or `LANGFUSE_TRACING=true` in your `.env`, together with the required credentials, to enable tracing in containerized deployments.
+
+---
+
+## Development
+
+### Commands
+
+```bash
+make install    # Install dependencies
+make dev        # Run LangGraph server (port 2024)
+make gateway    # Run Gateway API (port 8001)
+make lint       # Run linter (ruff)
+make format     # Format code (ruff)
+```
+
+### Code Style
+
+- **Linter/Formatter**: `ruff`
+- **Line length**: 240 characters
+- **Python**: 3.12+ with type hints
+- **Quotes**: Double quotes
+- **Indentation**: 4 spaces
+
+### Testing
+
+```bash
+uv run pytest
+```
+
+---
+
+## Technology Stack
+
+- **LangGraph** (1.0.6+) - Agent framework and multi-agent orchestration
+- **LangChain** (1.2.3+) - LLM abstractions and tool system
+- **FastAPI** (0.115.0+) - Gateway REST API
+- **langchain-mcp-adapters** - Model Context Protocol support
+- **agent-sandbox** - Sandboxed code execution
+- **markitdown** - Multi-format document conversion
+- **tavily-python** / **firecrawl-py** - Web search and scraping
+
+---
+
+## Documentation
+
+- [Configuration Guide](docs/CONFIGURATION.md)
+- [Architecture Details](docs/ARCHITECTURE.md)
+- [API Reference](docs/API.md)
+- [File Upload](docs/FILE_UPLOAD.md)
+- [Path Examples](docs/PATH_EXAMPLES.md)
+- [Context Summarization](docs/summarization.md)
+- [Plan Mode](docs/plan_mode_usage.md)
+- [Setup Guide](docs/SETUP.md)
+
+---
+
+## License
+
+See the [LICENSE](../LICENSE) file in the project root.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.

offline-backend-20260512/backend/app/channels/__init__.py

@@ -0,0 +1,16 @@
+"""IM Channel integration for DeerFlow.
+
+Provides a pluggable channel system that connects external messaging platforms
+(Feishu/Lark, Slack, Telegram) to the DeerFlow agent via the ChannelManager,
+which uses ``langgraph-sdk`` to communicate with Gateway's LangGraph-compatible API.
+"""
+
+from app.channels.base import Channel
+from app.channels.message_bus import InboundMessage, MessageBus, OutboundMessage
+
+__all__ = [
+    "Channel",
+    "InboundMessage",
+    "MessageBus",
+    "OutboundMessage",
+]

offline-backend-20260512/backend/app/channels/base.py

@@ -0,0 +1,130 @@
+"""Abstract base class for IM channels."""
+
+from __future__ import annotations
+
+import logging
+from abc import ABC, abstractmethod
+from typing import Any
+
+from app.channels.message_bus import InboundMessage, InboundMessageType, MessageBus, OutboundMessage, ResolvedAttachment
+
+logger = logging.getLogger(__name__)
+
+
+class Channel(ABC):
+    """Base class for all IM channel implementations.
+
+    Each channel connects to an external messaging platform and:
+    1. Receives messages, wraps them as InboundMessage, publishes to the bus.
+    2. Subscribes to outbound messages and sends replies back to the platform.
+
+    Subclasses must implement ``start``, ``stop``, and ``send``.
+    """
+
+    def __init__(self, name: str, bus: MessageBus, config: dict[str, Any]) -> None:
+        self.name = name
+        self.bus = bus
+        self.config = config
+        self._running = False
+
+    @property
+    def is_running(self) -> bool:
+        return self._running
+
+    @property
+    def supports_streaming(self) -> bool:
+        return False
+
+    # -- lifecycle ---------------------------------------------------------
+
+    @abstractmethod
+    async def start(self) -> None:
+        """Start listening for messages from the external platform."""
+
+    @abstractmethod
+    async def stop(self) -> None:
+        """Gracefully stop the channel."""
+
+    # -- outbound ----------------------------------------------------------
+
+    @abstractmethod
+    async def send(self, msg: OutboundMessage) -> None:
+        """Send a message back to the external platform.
+
+        The implementation should use ``msg.chat_id`` and ``msg.thread_ts``
+        to route the reply to the correct conversation/thread.
+        """
+
+    async def send_file(self, msg: OutboundMessage, attachment: ResolvedAttachment) -> bool:
+        """Upload a single file attachment to the platform.
+
+        Returns True if the upload succeeded, False otherwise.
+        Default implementation returns False (no file upload support).
+        """
+        return False
+
+    # -- helpers -----------------------------------------------------------
+
+    def _make_inbound(
+        self,
+        chat_id: str,
+        user_id: str,
+        text: str,
+        *,
+        msg_type: InboundMessageType = InboundMessageType.CHAT,
+        thread_ts: str | None = None,
+        files: list[dict[str, Any]] | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> InboundMessage:
+        """Convenience factory for creating InboundMessage instances."""
+        return InboundMessage(
+            channel_name=self.name,
+            chat_id=chat_id,
+            user_id=user_id,
+            text=text,
+            msg_type=msg_type,
+            thread_ts=thread_ts,
+            files=files or [],
+            metadata=metadata or {},
+        )
+
+    async def _on_outbound(self, msg: OutboundMessage) -> None:
+        """Outbound callback registered with the bus.
+
+        Only forwards messages targeted at this channel.
+        Sends the text message first, then uploads any file attachments.
+        File uploads are skipped entirely when the text send fails to avoid
+        partial deliveries (files without accompanying text).
+        """
+        if msg.channel_name == self.name:
+            try:
+                await self.send(msg)
+            except Exception:
+                logger.exception("Failed to send outbound message on channel %s", self.name)
+                return  # Do not attempt file uploads when the text message failed
+
+            for attachment in msg.attachments:
+                try:
+                    success = await self.send_file(msg, attachment)
+                    if not success:
+                        logger.warning("[%s] file upload skipped for %s", self.name, attachment.filename)
+                except Exception:
+                    logger.exception("[%s] failed to upload file %s", self.name, attachment.filename)
+
+    async def receive_file(self, msg: InboundMessage, thread_id: str) -> InboundMessage:
+        """
+        Optionally process and materialize inbound file attachments for this channel.
+
+        By default, this method does nothing and simply returns the original message.
+        Subclasses (e.g. FeishuChannel) may override this to download files (images, documents, etc)
+        referenced in msg.files, save them to the sandbox, and update msg.text to include
+        the sandbox file paths for downstream model consumption.
+
+        Args:
+            msg: The inbound message, possibly containing file metadata in msg.files.
+            thread_id: The resolved DeerFlow thread ID for sandbox path context.
+
+        Returns:
+            The (possibly modified) InboundMessage, with text and/or files updated as needed.
+        """
+        return msg

offline-backend-20260512/backend/app/channels/commands.py

@@ -0,0 +1,20 @@
+"""Shared command definitions used by all channel implementations.
+
+Keeping the authoritative command set in one place ensures that channel
+parsers (e.g. Feishu) and the ChannelManager dispatcher stay in sync
+automatically — adding or removing a command here is the single edit
+required.
+"""
+
+from __future__ import annotations
+
+KNOWN_CHANNEL_COMMANDS: frozenset[str] = frozenset(
+    {
+        "/bootstrap",
+        "/new",
+        "/status",
+        "/models",
+        "/memory",
+        "/help",
+    }
+)

offline-backend-20260512/backend/app/channels/dingtalk.py

@@ -0,0 +1,740 @@
+"""DingTalk channel implementation."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import re
+import threading
+import time
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from app.channels.base import Channel
+from app.channels.commands import KNOWN_CHANNEL_COMMANDS
+from app.channels.message_bus import InboundMessage, InboundMessageType, MessageBus, OutboundMessage, ResolvedAttachment
+
+logger = logging.getLogger(__name__)
+
+DINGTALK_API_BASE = "https://api.dingtalk.com"
+
+_TOKEN_REFRESH_MARGIN_SECONDS = 300
+
+_CONVERSATION_TYPE_P2P = "1"
+_CONVERSATION_TYPE_GROUP = "2"
+
+_MAX_UPLOAD_SIZE_BYTES = 20 * 1024 * 1024
+
+
+def _normalize_conversation_type(raw: Any) -> str:
+    """Normalize ``conversationType`` to ``"1"`` (P2P) or ``"2"`` (group).
+
+    Stream payloads may send int or string values.
+    """
+    if raw is None:
+        return _CONVERSATION_TYPE_P2P
+    s = str(raw).strip()
+    if s == _CONVERSATION_TYPE_GROUP:
+        return _CONVERSATION_TYPE_GROUP
+    return _CONVERSATION_TYPE_P2P
+
+
+def _normalize_allowed_users(allowed_users: Any) -> set[str]:
+    if allowed_users is None:
+        return set()
+    if isinstance(allowed_users, str):
+        values = [allowed_users]
+    elif isinstance(allowed_users, (list, tuple, set)):
+        values = allowed_users
+    else:
+        logger.warning(
+            "DingTalk allowed_users should be a list of user IDs; treating %s as one string value",
+            type(allowed_users).__name__,
+        )
+        values = [allowed_users]
+    return {str(uid) for uid in values if str(uid)}
+
+
+def _is_dingtalk_command(text: str) -> bool:
+    if not text.startswith("/"):
+        return False
+    return text.split(maxsplit=1)[0].lower() in KNOWN_CHANNEL_COMMANDS
+
+
+def _extract_text_from_rich_text(rich_text_list: list) -> str:
+    parts: list[str] = []
+    for item in rich_text_list:
+        if isinstance(item, dict) and "text" in item:
+            parts.append(item["text"])
+    return " ".join(parts)
+
+
+_FENCED_CODE_BLOCK_RE = re.compile(r"```(\w*)\n(.*?)```", re.DOTALL)
+_INLINE_CODE_RE = re.compile(r"`([^`\n]+)`")
+_HORIZONTAL_RULE_RE = re.compile(r"^-{3,}$", re.MULTILINE)
+_TABLE_SEPARATOR_RE = re.compile(r"^\|[-:| ]+\|$", re.MULTILINE)
+
+
+def _convert_markdown_table(text: str) -> str:
+    # DingTalk sampleMarkdown does not render pipe-delimited tables.
+    lines = text.split("\n")
+    result: list[str] = []
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+        # Detect table: header row followed by separator row
+        if i + 1 < len(lines) and line.strip().startswith("|") and _TABLE_SEPARATOR_RE.match(lines[i + 1].strip()):
+            headers = [h.strip() for h in line.strip().strip("|").split("|")]
+            i += 2  # skip header + separator
+            while i < len(lines) and lines[i].strip().startswith("|"):
+                cells = [c.strip() for c in lines[i].strip().strip("|").split("|")]
+                for h, c in zip(headers, cells):
+                    result.append(f"> **{h}**: {c}")
+                result.append("")
+                i += 1
+        else:
+            result.append(line)
+            i += 1
+    return "\n".join(result)
+
+
+def _adapt_markdown_for_dingtalk(text: str) -> str:
+    """Adapt markdown for DingTalk's limited sampleMarkdown renderer."""
+
+    def _code_block_to_quote(match: re.Match) -> str:
+        lang = match.group(1)
+        code = match.group(2).rstrip("\n")
+        prefix = f"> **{lang}**\n" if lang else ""
+        quoted_lines = "\n".join(f"> {line}" for line in code.split("\n"))
+        return f"{prefix}{quoted_lines}\n"
+
+    text = _FENCED_CODE_BLOCK_RE.sub(_code_block_to_quote, text)
+    text = _INLINE_CODE_RE.sub(r"**\1**", text)
+    text = _convert_markdown_table(text)
+    text = _HORIZONTAL_RULE_RE.sub("───────────", text)
+    return text
+
+
+class DingTalkChannel(Channel):
+    """DingTalk IM channel using Stream Push (WebSocket, no public IP needed)."""
+
+    def __init__(self, bus: MessageBus, config: dict[str, Any]) -> None:
+        super().__init__(name="dingtalk", bus=bus, config=config)
+        self._thread: threading.Thread | None = None
+        self._main_loop: asyncio.AbstractEventLoop | None = None
+        self._client_id: str = ""
+        self._client_secret: str = ""
+        self._allowed_users: set[str] = _normalize_allowed_users(config.get("allowed_users"))
+        self._cached_token: str = ""
+        self._token_expires_at: float = 0.0
+        self._token_lock = asyncio.Lock()
+        self._card_template_id: str = config.get("card_template_id", "")
+        self._card_track_ids: dict[str, str] = {}
+        self._dingtalk_client: Any = None
+        self._stream_client: Any = None
+        self._incoming_messages: dict[str, Any] = {}
+        self._incoming_messages_lock = threading.Lock()
+        self._card_repliers: dict[str, Any] = {}
+
+    @property
+    def supports_streaming(self) -> bool:
+        return bool(self._card_template_id)
+
+    async def start(self) -> None:
+        if self._running:
+            return
+
+        try:
+            import dingtalk_stream  # noqa: F401
+        except ImportError:
+            logger.error("dingtalk-stream is not installed. Install it with: uv add dingtalk-stream")
+            return
+
+        client_id = self.config.get("client_id", "")
+        client_secret = self.config.get("client_secret", "")
+
+        if not client_id or not client_secret:
+            logger.error("DingTalk channel requires client_id and client_secret")
+            return
+
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self._main_loop = asyncio.get_running_loop()
+
+        if self._card_template_id:
+            logger.info("[DingTalk] AI Card mode enabled (template=%s)", self._card_template_id)
+
+        self._running = True
+        self.bus.subscribe_outbound(self._on_outbound)
+
+        self._thread = threading.Thread(
+            target=self._run_stream,
+            args=(client_id, client_secret),
+            daemon=True,
+        )
+        self._thread.start()
+        logger.info("DingTalk channel started")
+
+    async def stop(self) -> None:
+        self._running = False
+        self.bus.unsubscribe_outbound(self._on_outbound)
+
+        stream_client = self._stream_client
+        if stream_client is not None:
+            try:
+                if hasattr(stream_client, "disconnect"):
+                    stream_client.disconnect()
+            except Exception:
+                logger.debug("[DingTalk] error disconnecting stream client", exc_info=True)
+
+        self._dingtalk_client = None
+        self._stream_client = None
+        with self._incoming_messages_lock:
+            self._incoming_messages.clear()
+        self._card_repliers.clear()
+        self._card_track_ids.clear()
+        if self._thread:
+            self._thread.join(timeout=5)
+            self._thread = None
+        logger.info("DingTalk channel stopped")
+
+    def _resolve_routing(self, msg: OutboundMessage) -> tuple[str, str, str]:
+        """Return (conversation_type, sender_staff_id, conversation_id).
+
+        Uses msg.chat_id as the primary routing key; metadata as fallback.
+        """
+        conversation_type = _normalize_conversation_type(msg.metadata.get("conversation_type"))
+        sender_staff_id = msg.metadata.get("sender_staff_id", "")
+        conversation_id = msg.metadata.get("conversation_id", "")
+        if conversation_type == _CONVERSATION_TYPE_GROUP:
+            conversation_id = msg.chat_id or conversation_id
+        else:
+            sender_staff_id = msg.chat_id or sender_staff_id
+        return conversation_type, sender_staff_id, conversation_id
+
+    async def send(self, msg: OutboundMessage, *, _max_retries: int = 3) -> None:
+        conversation_type, sender_staff_id, conversation_id = self._resolve_routing(msg)
+        robot_code = self._client_id
+
+        # Card mode: stream update to existing AI card
+        source_key = self._make_card_source_key_from_outbound(msg)
+        out_track_id = self._card_track_ids.get(source_key)
+
+        # ``card_template_id`` enables ``runs.stream`` (non-final + final outbounds).
+        # If card creation failed, skip non-final chunks to avoid duplicate messages.
+        if self._card_template_id and not out_track_id and not msg.is_final:
+            return
+
+        if out_track_id:
+            try:
+                await self._stream_update_card(
+                    out_track_id,
+                    msg.text,
+                    is_finalize=msg.is_final,
+                )
+            except Exception:
+                logger.warning("[DingTalk] card stream failed, falling back to sampleMarkdown")
+                if msg.is_final:
+                    self._card_track_ids.pop(source_key, None)
+                    self._card_repliers.pop(out_track_id, None)
+                    await self._send_markdown_fallback(robot_code, conversation_type, sender_staff_id, conversation_id, msg.text)
+                    return
+            if msg.is_final:
+                self._card_track_ids.pop(source_key, None)
+                self._card_repliers.pop(out_track_id, None)
+            return
+
+        # Non-card mode: send sampleMarkdown with retry
+        last_exc: Exception | None = None
+        for attempt in range(_max_retries):
+            try:
+                if conversation_type == _CONVERSATION_TYPE_GROUP:
+                    await self._send_group_message(robot_code, conversation_id, msg.text, at_user_ids=[sender_staff_id] if sender_staff_id else None)
+                else:
+                    await self._send_p2p_message(robot_code, sender_staff_id, msg.text)
+                return
+            except Exception as exc:
+                last_exc = exc
+                if attempt < _max_retries - 1:
+                    delay = 2**attempt
+                    logger.warning(
+                        "[DingTalk] send failed (attempt %d/%d), retrying in %ds: %s",
+                        attempt + 1,
+                        _max_retries,
+                        delay,
+                        exc,
+                    )
+                    await asyncio.sleep(delay)
+
+        logger.error("[DingTalk] send failed after %d attempts: %s", _max_retries, last_exc)
+        if last_exc is None:
+            raise RuntimeError("DingTalk send failed without an exception from any attempt")
+        raise last_exc
+
+    async def _send_markdown_fallback(
+        self,
+        robot_code: str,
+        conversation_type: str,
+        sender_staff_id: str,
+        conversation_id: str,
+        text: str,
+    ) -> None:
+        try:
+            if conversation_type == _CONVERSATION_TYPE_GROUP:
+                await self._send_group_message(robot_code, conversation_id, text)
+            else:
+                await self._send_p2p_message(robot_code, sender_staff_id, text)
+        except Exception:
+            logger.exception("[DingTalk] markdown fallback also failed")
+            raise
+
+    async def send_file(self, msg: OutboundMessage, attachment: ResolvedAttachment) -> bool:
+        if attachment.size > _MAX_UPLOAD_SIZE_BYTES:
+            logger.warning("[DingTalk] file too large (%d bytes), skipping: %s", attachment.size, attachment.filename)
+            return False
+
+        conversation_type, sender_staff_id, conversation_id = self._resolve_routing(msg)
+        robot_code = self._client_id
+
+        try:
+            media_id = await self._upload_media(attachment.actual_path, "image" if attachment.is_image else "file")
+            if not media_id:
+                return False
+
+            if attachment.is_image:
+                msg_key = "sampleImageMsg"
+                msg_param = json.dumps({"photoURL": media_id})
+            else:
+                msg_key = "sampleFile"
+                msg_param = json.dumps(
+                    {
+                        "fileUrl": media_id,
+                        "fileName": attachment.filename,
+                        "fileSize": str(attachment.size),
+                    }
+                )
+
+            token = await self._get_access_token()
+            async with httpx.AsyncClient(timeout=httpx.Timeout(30.0)) as client:
+                if conversation_type == _CONVERSATION_TYPE_GROUP:
+                    response = await client.post(
+                        f"{DINGTALK_API_BASE}/v1.0/robot/groupMessages/send",
+                        headers=self._api_headers(token),
+                        json={
+                            "msgKey": msg_key,
+                            "msgParam": msg_param,
+                            "robotCode": robot_code,
+                            "openConversationId": conversation_id,
+                        },
+                    )
+                else:
+                    response = await client.post(
+                        f"{DINGTALK_API_BASE}/v1.0/robot/oToMessages/batchSend",
+                        headers=self._api_headers(token),
+                        json={
+                            "msgKey": msg_key,
+                            "msgParam": msg_param,
+                            "robotCode": robot_code,
+                            "userIds": [sender_staff_id],
+                        },
+                    )
+                response.raise_for_status()
+
+            logger.info("[DingTalk] file sent: %s", attachment.filename)
+            return True
+        except (httpx.HTTPError, OSError, ValueError, TypeError, AttributeError):
+            logger.exception("[DingTalk] failed to send file: %s", attachment.filename)
+            return False
+
+    # -- stream client (runs in dedicated thread) --------------------------
+
+    def _run_stream(self, client_id: str, client_secret: str) -> None:
+        try:
+            import dingtalk_stream
+
+            credential = dingtalk_stream.Credential(client_id, client_secret)
+            client = dingtalk_stream.DingTalkStreamClient(credential)
+            self._stream_client = client
+            client.register_callback_handler(
+                dingtalk_stream.chatbot.ChatbotMessage.TOPIC,
+                _DingTalkMessageHandler(self),
+            )
+            client.start_forever()
+        except Exception:
+            if self._running:
+                logger.exception("DingTalk Stream Push error")
+        finally:
+            self._stream_client = None
+
+    def _on_chatbot_message(self, message: Any) -> None:
+        if not self._running:
+            return
+        try:
+            sender_staff_id = message.sender_staff_id or ""
+            conversation_type = _normalize_conversation_type(message.conversation_type)
+            conversation_id = message.conversation_id or ""
+            msg_id = message.message_id or ""
+            sender_nick = message.sender_nick or ""
+
+            if self._allowed_users and sender_staff_id not in self._allowed_users:
+                logger.debug("[DingTalk] ignoring message from non-allowed user: %s", sender_staff_id)
+                return
+
+            text = self._extract_text(message)
+            if not text:
+                logger.info("[DingTalk] empty text, ignoring message")
+                return
+
+            logger.info(
+                "[DingTalk] parsed message: conv_type=%s, msg_id=%s, sender=%s(%s), text=%r",
+                conversation_type,
+                msg_id,
+                sender_staff_id,
+                sender_nick,
+                text[:100],
+            )
+
+            if _is_dingtalk_command(text):
+                msg_type = InboundMessageType.COMMAND
+            else:
+                msg_type = InboundMessageType.CHAT
+
+            # P2P: topic_id=None (single thread per user, like Telegram private chat)
+            # Group: topic_id=msg_id (each new message starts a new topic, like Feishu)
+            topic_id: str | None = msg_id if conversation_type == _CONVERSATION_TYPE_GROUP else None
+
+            # chat_id uses conversation_id for groups, sender_staff_id for P2P
+            chat_id = conversation_id if conversation_type == _CONVERSATION_TYPE_GROUP else sender_staff_id
+
+            inbound = self._make_inbound(
+                chat_id=chat_id,
+                user_id=sender_staff_id,
+                text=text,
+                msg_type=msg_type,
+                thread_ts=msg_id,
+                metadata={
+                    "conversation_type": conversation_type,
+                    "conversation_id": conversation_id,
+                    "sender_staff_id": sender_staff_id,
+                    "sender_nick": sender_nick,
+                    "message_id": msg_id,
+                },
+            )
+            inbound.topic_id = topic_id
+
+            if self._card_template_id:
+                source_key = self._make_card_source_key(inbound)
+                with self._incoming_messages_lock:
+                    self._incoming_messages[source_key] = message
+
+            if self._main_loop and self._main_loop.is_running():
+                logger.info("[DingTalk] publishing inbound message to bus (type=%s, msg_id=%s)", msg_type.value, msg_id)
+                fut = asyncio.run_coroutine_threadsafe(
+                    self._prepare_inbound(chat_id, inbound),
+                    self._main_loop,
+                )
+                fut.add_done_callback(lambda f, mid=msg_id: self._log_future_error(f, "prepare_inbound", mid))
+            else:
+                logger.warning("[DingTalk] main loop not running, cannot publish inbound message")
+        except Exception:
+            logger.exception("[DingTalk] error processing chatbot message")
+
+    @staticmethod
+    def _extract_text(message: Any) -> str:
+        msg_type = message.message_type
+        if msg_type == "text" and message.text:
+            return message.text.content.strip()
+        if msg_type == "richText" and message.rich_text_content:
+            return _extract_text_from_rich_text(message.rich_text_content.rich_text_list).strip()
+        return ""
+
+    async def _prepare_inbound(self, chat_id: str, inbound: InboundMessage) -> None:
+        # Running reply must finish before publish_inbound so AI card tracks are
+        # registered before the manager emits streaming outbounds.
+        await self._send_running_reply(chat_id, inbound)
+        await self.bus.publish_inbound(inbound)
+
+    async def _send_running_reply(self, chat_id: str, inbound: InboundMessage) -> None:
+        conversation_type = inbound.metadata.get("conversation_type", _CONVERSATION_TYPE_P2P)
+        sender_staff_id = inbound.metadata.get("sender_staff_id", "")
+        conversation_id = inbound.metadata.get("conversation_id", "")
+        text = "\u23f3 Working on it..."
+
+        try:
+            if self._card_template_id:
+                source_key = self._make_card_source_key(inbound)
+                with self._incoming_messages_lock:
+                    chatbot_message = self._incoming_messages.pop(source_key, None)
+                out_track_id = await self._create_and_deliver_card(
+                    text,
+                    chatbot_message=chatbot_message,
+                )
+                if out_track_id:
+                    self._card_track_ids[source_key] = out_track_id
+                    logger.info("[DingTalk] AI card running reply sent for chat=%s", chat_id)
+                    return
+
+            robot_code = self._client_id
+            if conversation_type == _CONVERSATION_TYPE_GROUP:
+                await self._send_text_message_to_group(robot_code, conversation_id, text)
+            else:
+                await self._send_text_message_to_user(robot_code, sender_staff_id, text)
+            logger.info("[DingTalk] 'Working on it...' reply sent for chat=%s", chat_id)
+        except Exception:
+            logger.exception("[DingTalk] failed to send running reply for chat=%s", chat_id)
+
+    # -- DingTalk API helpers ----------------------------------------------
+
+    async def _get_access_token(self) -> str:
+        if self._cached_token and time.monotonic() < self._token_expires_at:
+            return self._cached_token
+        async with self._token_lock:
+            if self._cached_token and time.monotonic() < self._token_expires_at:
+                return self._cached_token
+            async with httpx.AsyncClient(timeout=httpx.Timeout(10.0)) as client:
+                response = await client.post(
+                    f"{DINGTALK_API_BASE}/v1.0/oauth2/accessToken",
+                    json={"appKey": self._client_id, "appSecret": self._client_secret},  # DingTalk API field names
+                )
+                response.raise_for_status()
+                data = response.json()
+
+                if not isinstance(data, dict):
+                    raise ValueError(f"DingTalk access token response must be a JSON object, got {type(data).__name__}")
+
+                access_token = data.get("accessToken")
+                if not isinstance(access_token, str) or not access_token.strip():
+                    raise ValueError("DingTalk access token response did not contain a usable accessToken")
+
+                raw_expires_in = data.get("expireIn", 7200)
+                try:
+                    expires_in = int(raw_expires_in)
+                except (TypeError, ValueError):
+                    logger.warning("[DingTalk] invalid expireIn value %r, using default 7200s", raw_expires_in)
+                    expires_in = 7200
+
+                self._cached_token = access_token.strip()
+                self._token_expires_at = time.monotonic() + expires_in - _TOKEN_REFRESH_MARGIN_SECONDS
+                return self._cached_token
+
+    @staticmethod
+    def _api_headers(token: str) -> dict[str, str]:
+        return {
+            "x-acs-dingtalk-access-token": token,
+            "Content-Type": "application/json",
+        }
+
+    async def _send_text_message_to_user(self, robot_code: str, user_id: str, text: str) -> None:
+        token = await self._get_access_token()
+        async with httpx.AsyncClient(timeout=httpx.Timeout(30.0)) as client:
+            response = await client.post(
+                f"{DINGTALK_API_BASE}/v1.0/robot/oToMessages/batchSend",
+                headers=self._api_headers(token),
+                json={
+                    "msgKey": "sampleText",
+                    "msgParam": json.dumps({"content": text}),
+                    "robotCode": robot_code,
+                    "userIds": [user_id],
+                },
+            )
+            response.raise_for_status()
+
+    async def _send_text_message_to_group(self, robot_code: str, conversation_id: str, text: str) -> None:
+        token = await self._get_access_token()
+        async with httpx.AsyncClient(timeout=httpx.Timeout(30.0)) as client:
+            response = await client.post(
+                f"{DINGTALK_API_BASE}/v1.0/robot/groupMessages/send",
+                headers=self._api_headers(token),
+                json={
+                    "msgKey": "sampleText",
+                    "msgParam": json.dumps({"content": text}),
+                    "robotCode": robot_code,
+                    "openConversationId": conversation_id,
+                },
+            )
+            response.raise_for_status()
+
+    async def _send_p2p_message(self, robot_code: str, user_id: str, text: str) -> None:
+        text = _adapt_markdown_for_dingtalk(text)
+        token = await self._get_access_token()
+        async with httpx.AsyncClient(timeout=httpx.Timeout(30.0)) as client:
+            response = await client.post(
+                f"{DINGTALK_API_BASE}/v1.0/robot/oToMessages/batchSend",
+                headers=self._api_headers(token),
+                json={
+                    "msgKey": "sampleMarkdown",
+                    "msgParam": json.dumps({"title": "DeerFlow", "text": text}),
+                    "robotCode": robot_code,
+                    "userIds": [user_id],
+                },
+            )
+            response.raise_for_status()
+            data = response.json()
+            if data.get("processQueryKey"):
+                logger.info("[DingTalk] P2P message sent to user=%s", user_id)
+            else:
+                logger.warning("[DingTalk] P2P send response: %s", data)
+
+    async def _send_group_message(
+        self,
+        robot_code: str,
+        conversation_id: str,
+        text: str,
+        *,
+        at_user_ids: list[str] | None = None,  # noqa: ARG002
+    ) -> None:
+        # at_user_ids accepted for call-site compatibility but not passed to the API
+        # (sampleMarkdown does not support @mentions).
+        text = _adapt_markdown_for_dingtalk(text)
+        token = await self._get_access_token()
+
+        async with httpx.AsyncClient(timeout=httpx.Timeout(30.0)) as client:
+            response = await client.post(
+                f"{DINGTALK_API_BASE}/v1.0/robot/groupMessages/send",
+                headers=self._api_headers(token),
+                json={
+                    "msgKey": "sampleMarkdown",
+                    "msgParam": json.dumps({"title": "DeerFlow", "text": text}),
+                    "robotCode": robot_code,
+                    "openConversationId": conversation_id,
+                },
+            )
+            response.raise_for_status()
+            data = response.json()
+            if data.get("processQueryKey"):
+                logger.info("[DingTalk] group message sent to conversation=%s", conversation_id)
+            else:
+                logger.warning("[DingTalk] group send response: %s", data)
+
+    # -- AI Card streaming helpers -------------------------------------------
+
+    def _make_card_source_key(self, inbound: InboundMessage) -> str:
+        m = inbound.metadata
+        return f"{m.get('conversation_type', '')}:{m.get('sender_staff_id', '')}:{m.get('conversation_id', '')}:{m.get('message_id', '')}"
+
+    def _make_card_source_key_from_outbound(self, msg: OutboundMessage) -> str:
+        m = msg.metadata
+        correlation_id = m.get("message_id") or msg.thread_ts or ""
+        return f"{m.get('conversation_type', '')}:{m.get('sender_staff_id', '')}:{m.get('conversation_id', '')}:{correlation_id}"
+
+    async def _create_and_deliver_card(
+        self,
+        initial_text: str,
+        *,
+        chatbot_message: Any = None,
+    ) -> str | None:
+        if self._dingtalk_client is None or chatbot_message is None:
+            logger.warning("[DingTalk] SDK client or chatbot_message unavailable, skipping AI card")
+            return None
+
+        try:
+            from dingtalk_stream.card_replier import AICardReplier
+        except ImportError:
+            logger.warning("[DingTalk] dingtalk-stream card_replier not available")
+            return None
+
+        try:
+            replier = AICardReplier(self._dingtalk_client, chatbot_message)
+            card_instance_id = await replier.async_create_and_deliver_card(
+                card_template_id=self._card_template_id,
+                card_data={"content": initial_text},
+            )
+            if not card_instance_id:
+                return None
+
+            self._card_repliers[card_instance_id] = replier
+            logger.info("[DingTalk] AI card created: outTrackId=%s", card_instance_id)
+            return card_instance_id
+        except Exception:
+            logger.exception("[DingTalk] failed to create AI card")
+            return None
+
+    async def _stream_update_card(
+        self,
+        out_track_id: str,
+        content: str,
+        *,
+        is_finalize: bool = False,
+        is_error: bool = False,
+    ) -> None:
+        replier = self._card_repliers.get(out_track_id)
+        if not replier:
+            raise RuntimeError(f"No AICardReplier found for track ID {out_track_id}")
+
+        await replier.async_streaming(
+            card_instance_id=out_track_id,
+            content_key="content",
+            content_value=content,
+            append=False,
+            finished=is_finalize,
+            failed=is_error,
+        )
+
+    # -- media upload --------------------------------------------------------
+
+    async def _upload_media(self, file_path: str | Path, media_type: str) -> str | None:
+        try:
+            file_bytes = await asyncio.to_thread(Path(file_path).read_bytes)
+            token = await self._get_access_token()
+            async with httpx.AsyncClient(timeout=httpx.Timeout(60.0)) as client:
+                response = await client.post(
+                    f"{DINGTALK_API_BASE}/v1.0/files/upload",
+                    headers={"x-acs-dingtalk-access-token": token},
+                    files={"file": ("upload", file_bytes)},
+                    data={"type": media_type},
+                )
+                response.raise_for_status()
+                try:
+                    payload = response.json()
+                except json.JSONDecodeError:
+                    logger.exception("[DingTalk] failed to decode upload response JSON: %s", file_path)
+                    return None
+                if not isinstance(payload, dict):
+                    logger.warning("[DingTalk] unexpected upload response type %s for %s", type(payload).__name__, file_path)
+                    return None
+                return payload.get("mediaId")
+        except (httpx.HTTPError, OSError):
+            logger.exception("[DingTalk] failed to upload media: %s", file_path)
+            return None
+
+    @staticmethod
+    def _log_future_error(fut: Any, name: str, msg_id: str) -> None:
+        try:
+            exc = fut.exception()
+            if exc:
+                logger.error("[DingTalk] %s failed for msg_id=%s: %s", name, msg_id, exc)
+        except (asyncio.CancelledError, asyncio.InvalidStateError):
+            pass
+
+
+class _DingTalkMessageHandler:
+    """Callback handler registered with dingtalk-stream."""
+
+    def __init__(self, channel: DingTalkChannel) -> None:
+        self._channel = channel
+
+    def pre_start(self) -> None:
+        if hasattr(self, "dingtalk_client") and self.dingtalk_client is not None:
+            self._channel._dingtalk_client = self.dingtalk_client
+
+    async def raw_process(self, callback_message: Any) -> Any:
+        import dingtalk_stream
+        from dingtalk_stream.frames import Headers
+
+        code, message = await self.process(callback_message)
+        ack_message = dingtalk_stream.AckMessage()
+        ack_message.code = code
+        ack_message.headers.message_id = callback_message.headers.message_id
+        ack_message.headers.content_type = Headers.CONTENT_TYPE_APPLICATION_JSON
+        ack_message.data = {"response": message}
+        return ack_message
+
+    async def process(self, callback: Any) -> tuple[int, str]:
+        import dingtalk_stream
+
+        incoming_message = dingtalk_stream.ChatbotMessage.from_dict(callback.data)
+        self._channel._on_chatbot_message(incoming_message)
+        return dingtalk_stream.AckMessage.STATUS_OK, "OK"

offline-backend-20260512/backend/app/channels/discord.py

@@ -0,0 +1,273 @@
+"""Discord channel integration using discord.py."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import threading
+from typing import Any
+
+from app.channels.base import Channel
+from app.channels.message_bus import InboundMessageType, MessageBus, OutboundMessage, ResolvedAttachment
+
+logger = logging.getLogger(__name__)
+
+_DISCORD_MAX_MESSAGE_LEN = 2000
+
+
+class DiscordChannel(Channel):
+    """Discord bot channel.
+
+    Configuration keys (in ``config.yaml`` under ``channels.discord``):
+        - ``bot_token``: Discord Bot token.
+        - ``allowed_guilds``: (optional) List of allowed Discord guild IDs. Empty = allow all.
+    """
+
+    def __init__(self, bus: MessageBus, config: dict[str, Any]) -> None:
+        super().__init__(name="discord", bus=bus, config=config)
+        self._bot_token = str(config.get("bot_token", "")).strip()
+        self._allowed_guilds: set[int] = set()
+        for guild_id in config.get("allowed_guilds", []):
+            try:
+                self._allowed_guilds.add(int(guild_id))
+            except (TypeError, ValueError):
+                continue
+
+        self._client = None
+        self._thread: threading.Thread | None = None
+        self._discord_loop: asyncio.AbstractEventLoop | None = None
+        self._main_loop: asyncio.AbstractEventLoop | None = None
+        self._discord_module = None
+
+    async def start(self) -> None:
+        if self._running:
+            return
+
+        try:
+            import discord
+        except ImportError:
+            logger.error("discord.py is not installed. Install it with: uv add discord.py")
+            return
+
+        if not self._bot_token:
+            logger.error("Discord channel requires bot_token")
+            return
+
+        intents = discord.Intents.default()
+        intents.messages = True
+        intents.guilds = True
+        intents.message_content = True
+
+        client = discord.Client(
+            intents=intents,
+            allowed_mentions=discord.AllowedMentions.none(),
+        )
+        self._client = client
+        self._discord_module = discord
+        self._main_loop = asyncio.get_event_loop()
+
+        @client.event
+        async def on_message(message) -> None:
+            await self._on_message(message)
+
+        self._running = True
+        self.bus.subscribe_outbound(self._on_outbound)
+
+        self._thread = threading.Thread(target=self._run_client, daemon=True)
+        self._thread.start()
+        logger.info("Discord channel started")
+
+    async def stop(self) -> None:
+        self._running = False
+        self.bus.unsubscribe_outbound(self._on_outbound)
+
+        if self._client and self._discord_loop and self._discord_loop.is_running():
+            close_future = asyncio.run_coroutine_threadsafe(self._client.close(), self._discord_loop)
+            try:
+                await asyncio.wait_for(asyncio.wrap_future(close_future), timeout=10)
+            except TimeoutError:
+                logger.warning("[Discord] client close timed out after 10s")
+            except Exception:
+                logger.exception("[Discord] error while closing client")
+
+        if self._thread:
+            self._thread.join(timeout=10)
+            self._thread = None
+
+        self._client = None
+        self._discord_loop = None
+        self._discord_module = None
+        logger.info("Discord channel stopped")
+
+    async def send(self, msg: OutboundMessage) -> None:
+        target = await self._resolve_target(msg)
+        if target is None:
+            logger.error("[Discord] target not found for chat_id=%s thread_ts=%s", msg.chat_id, msg.thread_ts)
+            return
+
+        text = msg.text or ""
+        for chunk in self._split_text(text):
+            send_future = asyncio.run_coroutine_threadsafe(target.send(chunk), self._discord_loop)
+            await asyncio.wrap_future(send_future)
+
+    async def send_file(self, msg: OutboundMessage, attachment: ResolvedAttachment) -> bool:
+        target = await self._resolve_target(msg)
+        if target is None:
+            logger.error("[Discord] target not found for file upload chat_id=%s thread_ts=%s", msg.chat_id, msg.thread_ts)
+            return False
+
+        if self._discord_module is None:
+            return False
+
+        try:
+            fp = open(str(attachment.actual_path), "rb")  # noqa: SIM115
+            file = self._discord_module.File(fp, filename=attachment.filename)
+            send_future = asyncio.run_coroutine_threadsafe(target.send(file=file), self._discord_loop)
+            await asyncio.wrap_future(send_future)
+            logger.info("[Discord] file uploaded: %s", attachment.filename)
+            return True
+        except Exception:
+            logger.exception("[Discord] failed to upload file: %s", attachment.filename)
+            return False
+
+    async def _on_message(self, message) -> None:
+        if not self._running or not self._client:
+            return
+
+        if message.author.bot:
+            return
+
+        if self._client.user and message.author.id == self._client.user.id:
+            return
+
+        guild = message.guild
+        if self._allowed_guilds:
+            if guild is None or guild.id not in self._allowed_guilds:
+                return
+
+        text = (message.content or "").strip()
+        if not text:
+            return
+
+        if self._discord_module is None:
+            return
+
+        if isinstance(message.channel, self._discord_module.Thread):
+            chat_id = str(message.channel.parent_id or message.channel.id)
+            thread_id = str(message.channel.id)
+        else:
+            thread = await self._create_thread(message)
+            if thread is None:
+                return
+            chat_id = str(message.channel.id)
+            thread_id = str(thread.id)
+
+        msg_type = InboundMessageType.COMMAND if text.startswith("/") else InboundMessageType.CHAT
+        inbound = self._make_inbound(
+            chat_id=chat_id,
+            user_id=str(message.author.id),
+            text=text,
+            msg_type=msg_type,
+            thread_ts=thread_id,
+            metadata={
+                "guild_id": str(guild.id) if guild else None,
+                "channel_id": str(message.channel.id),
+                "message_id": str(message.id),
+            },
+        )
+        inbound.topic_id = thread_id
+
+        if self._main_loop and self._main_loop.is_running():
+            future = asyncio.run_coroutine_threadsafe(self.bus.publish_inbound(inbound), self._main_loop)
+            future.add_done_callback(lambda f: logger.exception("[Discord] publish_inbound failed", exc_info=f.exception()) if f.exception() else None)
+
+    def _run_client(self) -> None:
+        self._discord_loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(self._discord_loop)
+        try:
+            self._discord_loop.run_until_complete(self._client.start(self._bot_token))
+        except Exception:
+            if self._running:
+                logger.exception("Discord client error")
+        finally:
+            try:
+                if self._client and not self._client.is_closed():
+                    self._discord_loop.run_until_complete(self._client.close())
+            except Exception:
+                logger.exception("Error during Discord shutdown")
+
+    async def _create_thread(self, message):
+        try:
+            thread_name = f"deerflow-{message.author.display_name}-{message.id}"[:100]
+            return await message.create_thread(name=thread_name)
+        except Exception:
+            logger.exception("[Discord] failed to create thread for message=%s (threads may be disabled or missing permissions)", message.id)
+            try:
+                await message.channel.send("Could not create a thread for your message. Please check that threads are enabled in this channel.")
+            except Exception:
+                pass
+            return None
+
+    async def _resolve_target(self, msg: OutboundMessage):
+        if not self._client or not self._discord_loop:
+            return None
+
+        target_ids: list[str] = []
+        if msg.thread_ts:
+            target_ids.append(msg.thread_ts)
+        if msg.chat_id and msg.chat_id not in target_ids:
+            target_ids.append(msg.chat_id)
+
+        for raw_id in target_ids:
+            target = await self._get_channel_or_thread(raw_id)
+            if target is not None:
+                return target
+        return None
+
+    async def _get_channel_or_thread(self, raw_id: str):
+        if not self._client or not self._discord_loop:
+            return None
+
+        try:
+            target_id = int(raw_id)
+        except (TypeError, ValueError):
+            return None
+
+        get_future = asyncio.run_coroutine_threadsafe(self._fetch_channel(target_id), self._discord_loop)
+        try:
+            return await asyncio.wrap_future(get_future)
+        except Exception:
+            logger.exception("[Discord] failed to resolve target id=%s", raw_id)
+            return None
+
+    async def _fetch_channel(self, target_id: int):
+        if not self._client:
+            return None
+
+        channel = self._client.get_channel(target_id)
+        if channel is not None:
+            return channel
+
+        try:
+            return await self._client.fetch_channel(target_id)
+        except Exception:
+            return None
+
+    @staticmethod
+    def _split_text(text: str) -> list[str]:
+        if not text:
+            return [""]
+
+        chunks: list[str] = []
+        remaining = text
+        while len(remaining) > _DISCORD_MAX_MESSAGE_LEN:
+            split_at = remaining.rfind("\n", 0, _DISCORD_MAX_MESSAGE_LEN)
+            if split_at <= 0:
+                split_at = _DISCORD_MAX_MESSAGE_LEN
+            chunks.append(remaining[:split_at])
+            remaining = remaining[split_at:].lstrip("\n")
+
+        if remaining:
+            chunks.append(remaining)
+
+        return chunks

offline-backend-20260512/backend/app/channels/feishu.py

@@ -0,0 +1,698 @@
+"""Feishu/Lark channel — connects to Feishu via WebSocket (no public IP needed)."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import re
+import threading
+from typing import Any, Literal
+
+from app.channels.base import Channel
+from app.channels.commands import KNOWN_CHANNEL_COMMANDS
+from app.channels.message_bus import InboundMessage, InboundMessageType, MessageBus, OutboundMessage, ResolvedAttachment
+from deerflow.config.paths import VIRTUAL_PATH_PREFIX, get_paths
+from deerflow.runtime.user_context import get_effective_user_id
+from deerflow.sandbox.sandbox_provider import get_sandbox_provider
+
+logger = logging.getLogger(__name__)
+
+
+def _is_feishu_command(text: str) -> bool:
+    if not text.startswith("/"):
+        return False
+    return text.split(maxsplit=1)[0].lower() in KNOWN_CHANNEL_COMMANDS
+
+
+class FeishuChannel(Channel):
+    """Feishu/Lark IM channel using the ``lark-oapi`` WebSocket client.
+
+    Configuration keys (in ``config.yaml`` under ``channels.feishu``):
+        - ``app_id``: Feishu app ID.
+        - ``app_secret``: Feishu app secret.
+        - ``verification_token``: (optional) Event verification token.
+
+    The channel uses WebSocket long-connection mode so no public IP is required.
+
+    Message flow:
+        1. User sends a message → bot adds "OK" emoji reaction
+        2. Bot replies in thread: "Working on it......"
+        3. Agent processes the message and returns a result
+        4. Bot replies in thread with the result
+        5. Bot adds "DONE" emoji reaction to the original message
+    """
+
+    def __init__(self, bus: MessageBus, config: dict[str, Any]) -> None:
+        super().__init__(name="feishu", bus=bus, config=config)
+        self._thread: threading.Thread | None = None
+        self._main_loop: asyncio.AbstractEventLoop | None = None
+        self._api_client = None
+        self._CreateMessageReactionRequest = None
+        self._CreateMessageReactionRequestBody = None
+        self._Emoji = None
+        self._PatchMessageRequest = None
+        self._PatchMessageRequestBody = None
+        self._background_tasks: set[asyncio.Task] = set()
+        self._running_card_ids: dict[str, str] = {}
+        self._running_card_tasks: dict[str, asyncio.Task] = {}
+        self._CreateFileRequest = None
+        self._CreateFileRequestBody = None
+        self._CreateImageRequest = None
+        self._CreateImageRequestBody = None
+        self._GetMessageResourceRequest = None
+        self._thread_lock = threading.Lock()
+
+    @property
+    def supports_streaming(self) -> bool:
+        return True
+
+    async def start(self) -> None:
+        if self._running:
+            return
+
+        try:
+            import lark_oapi as lark
+            from lark_oapi.api.im.v1 import (
+                CreateFileRequest,
+                CreateFileRequestBody,
+                CreateImageRequest,
+                CreateImageRequestBody,
+                CreateMessageReactionRequest,
+                CreateMessageReactionRequestBody,
+                CreateMessageRequest,
+                CreateMessageRequestBody,
+                Emoji,
+                GetMessageResourceRequest,
+                PatchMessageRequest,
+                PatchMessageRequestBody,
+                ReplyMessageRequest,
+                ReplyMessageRequestBody,
+            )
+        except ImportError:
+            logger.error("lark-oapi is not installed. Install it with: uv add lark-oapi")
+            return
+
+        self._lark = lark
+        self._CreateMessageRequest = CreateMessageRequest
+        self._CreateMessageRequestBody = CreateMessageRequestBody
+        self._ReplyMessageRequest = ReplyMessageRequest
+        self._ReplyMessageRequestBody = ReplyMessageRequestBody
+        self._CreateMessageReactionRequest = CreateMessageReactionRequest
+        self._CreateMessageReactionRequestBody = CreateMessageReactionRequestBody
+        self._Emoji = Emoji
+        self._PatchMessageRequest = PatchMessageRequest
+        self._PatchMessageRequestBody = PatchMessageRequestBody
+        self._CreateFileRequest = CreateFileRequest
+        self._CreateFileRequestBody = CreateFileRequestBody
+        self._CreateImageRequest = CreateImageRequest
+        self._CreateImageRequestBody = CreateImageRequestBody
+        self._GetMessageResourceRequest = GetMessageResourceRequest
+
+        app_id = self.config.get("app_id", "")
+        app_secret = self.config.get("app_secret", "")
+        domain = self.config.get("domain", "https://open.feishu.cn")
+
+        if not app_id or not app_secret:
+            logger.error("Feishu channel requires app_id and app_secret")
+            return
+
+        self._api_client = lark.Client.builder().app_id(app_id).app_secret(app_secret).domain(domain).build()
+        logger.info("[Feishu] using domain: %s", domain)
+        self._main_loop = asyncio.get_event_loop()
+
+        self._running = True
+        self.bus.subscribe_outbound(self._on_outbound)
+
+        # Both ws.Client construction and start() must happen in a dedicated
+        # thread with its own event loop.  lark-oapi caches the running loop
+        # at construction time and later calls loop.run_until_complete(),
+        # which conflicts with an already-running uvloop.
+        self._thread = threading.Thread(
+            target=self._run_ws,
+            args=(app_id, app_secret, domain),
+            daemon=True,
+        )
+        self._thread.start()
+        logger.info("Feishu channel started")
+
+    def _run_ws(self, app_id: str, app_secret: str, domain: str) -> None:
+        """Construct and run the lark WS client in a thread with a fresh event loop.
+
+        The lark-oapi SDK captures a module-level event loop at import time
+        (``lark_oapi.ws.client.loop``).  When uvicorn uses uvloop, that
+        captured loop is the *main* thread's uvloop — which is already
+        running, so ``loop.run_until_complete()`` inside ``Client.start()``
+        raises ``RuntimeError``.
+
+        We work around this by creating a plain asyncio event loop for this
+        thread and patching the SDK's module-level reference before calling
+        ``start()``.
+        """
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+        try:
+            import lark_oapi as lark
+            import lark_oapi.ws.client as _ws_client_mod
+
+            # Replace the SDK's module-level loop so Client.start() uses
+            # this thread's (non-running) event loop instead of the main
+            # thread's uvloop.
+            _ws_client_mod.loop = loop
+
+            event_handler = lark.EventDispatcherHandler.builder("", "").register_p2_im_message_receive_v1(self._on_message).build()
+            ws_client = lark.ws.Client(
+                app_id=app_id,
+                app_secret=app_secret,
+                event_handler=event_handler,
+                log_level=lark.LogLevel.INFO,
+                domain=domain,
+            )
+            ws_client.start()
+        except Exception:
+            if self._running:
+                logger.exception("Feishu WebSocket error")
+
+    async def stop(self) -> None:
+        self._running = False
+        self.bus.unsubscribe_outbound(self._on_outbound)
+        for task in list(self._background_tasks):
+            task.cancel()
+        self._background_tasks.clear()
+        for task in list(self._running_card_tasks.values()):
+            task.cancel()
+        self._running_card_tasks.clear()
+        if self._thread:
+            self._thread.join(timeout=5)
+            self._thread = None
+        logger.info("Feishu channel stopped")
+
+    async def send(self, msg: OutboundMessage, *, _max_retries: int = 3) -> None:
+        if not self._api_client:
+            logger.warning("[Feishu] send called but no api_client available")
+            return
+
+        logger.info(
+            "[Feishu] sending reply: chat_id=%s, thread_ts=%s, text_len=%d",
+            msg.chat_id,
+            msg.thread_ts,
+            len(msg.text),
+        )
+
+        last_exc: Exception | None = None
+        for attempt in range(_max_retries):
+            try:
+                await self._send_card_message(msg)
+                return  # success
+            except Exception as exc:
+                last_exc = exc
+                if attempt < _max_retries - 1:
+                    delay = 2**attempt  # 1s, 2s
+                    logger.warning(
+                        "[Feishu] send failed (attempt %d/%d), retrying in %ds: %s",
+                        attempt + 1,
+                        _max_retries,
+                        delay,
+                        exc,
+                    )
+                    await asyncio.sleep(delay)
+
+        logger.error("[Feishu] send failed after %d attempts: %s", _max_retries, last_exc)
+        if last_exc is None:
+            raise RuntimeError("Feishu send failed without an exception from any attempt")
+        raise last_exc
+
+    async def send_file(self, msg: OutboundMessage, attachment: ResolvedAttachment) -> bool:
+        if not self._api_client:
+            return False
+
+        # Check size limits (image: 10MB, file: 30MB)
+        if attachment.is_image and attachment.size > 10 * 1024 * 1024:
+            logger.warning("[Feishu] image too large (%d bytes), skipping: %s", attachment.size, attachment.filename)
+            return False
+        if not attachment.is_image and attachment.size > 30 * 1024 * 1024:
+            logger.warning("[Feishu] file too large (%d bytes), skipping: %s", attachment.size, attachment.filename)
+            return False
+
+        try:
+            if attachment.is_image:
+                file_key = await self._upload_image(attachment.actual_path)
+                msg_type = "image"
+                content = json.dumps({"image_key": file_key})
+            else:
+                file_key = await self._upload_file(attachment.actual_path, attachment.filename)
+                msg_type = "file"
+                content = json.dumps({"file_key": file_key})
+
+            if msg.thread_ts:
+                request = self._ReplyMessageRequest.builder().message_id(msg.thread_ts).request_body(self._ReplyMessageRequestBody.builder().msg_type(msg_type).content(content).reply_in_thread(True).build()).build()
+                await asyncio.to_thread(self._api_client.im.v1.message.reply, request)
+            else:
+                request = self._CreateMessageRequest.builder().receive_id_type("chat_id").request_body(self._CreateMessageRequestBody.builder().receive_id(msg.chat_id).msg_type(msg_type).content(content).build()).build()
+                await asyncio.to_thread(self._api_client.im.v1.message.create, request)
+
+            logger.info("[Feishu] file sent: %s (type=%s)", attachment.filename, msg_type)
+            return True
+        except Exception:
+            logger.exception("[Feishu] failed to upload/send file: %s", attachment.filename)
+            return False
+
+    async def _upload_image(self, path) -> str:
+        """Upload an image to Feishu and return the image_key."""
+        with open(str(path), "rb") as f:
+            request = self._CreateImageRequest.builder().request_body(self._CreateImageRequestBody.builder().image_type("message").image(f).build()).build()
+            response = await asyncio.to_thread(self._api_client.im.v1.image.create, request)
+        if not response.success():
+            raise RuntimeError(f"Feishu image upload failed: code={response.code}, msg={response.msg}")
+        return response.data.image_key
+
+    async def _upload_file(self, path, filename: str) -> str:
+        """Upload a file to Feishu and return the file_key."""
+        suffix = path.suffix.lower() if hasattr(path, "suffix") else ""
+        if suffix in (".xls", ".xlsx", ".csv"):
+            file_type = "xls"
+        elif suffix in (".ppt", ".pptx"):
+            file_type = "ppt"
+        elif suffix == ".pdf":
+            file_type = "pdf"
+        elif suffix in (".doc", ".docx"):
+            file_type = "doc"
+        else:
+            file_type = "stream"
+
+        with open(str(path), "rb") as f:
+            request = self._CreateFileRequest.builder().request_body(self._CreateFileRequestBody.builder().file_type(file_type).file_name(filename).file(f).build()).build()
+            response = await asyncio.to_thread(self._api_client.im.v1.file.create, request)
+        if not response.success():
+            raise RuntimeError(f"Feishu file upload failed: code={response.code}, msg={response.msg}")
+        return response.data.file_key
+
+    async def receive_file(self, msg: InboundMessage, thread_id: str) -> InboundMessage:
+        """Download a Feishu file into the thread uploads directory.
+
+        Returns the sandbox virtual path when the image is persisted successfully.
+        """
+        if not msg.thread_ts:
+            logger.warning("[Feishu] received file message without thread_ts, cannot associate with conversation: %s", msg)
+            return msg
+        files = msg.files
+        if not files:
+            logger.warning("[Feishu] received message with no files: %s", msg)
+            return msg
+        text = msg.text
+        for file in files:
+            if file.get("image_key"):
+                virtual_path = await self._receive_single_file(msg.thread_ts, file["image_key"], "image", thread_id)
+                text = text.replace("[image]", virtual_path, 1)
+            elif file.get("file_key"):
+                virtual_path = await self._receive_single_file(msg.thread_ts, file["file_key"], "file", thread_id)
+                text = text.replace("[file]", virtual_path, 1)
+        msg.text = text
+        return msg
+
+    async def _receive_single_file(self, message_id: str, file_key: str, type: Literal["image", "file"], thread_id: str) -> str:
+        request = self._GetMessageResourceRequest.builder().message_id(message_id).file_key(file_key).type(type).build()
+
+        def inner():
+            return self._api_client.im.v1.message_resource.get(request)
+
+        try:
+            response = await asyncio.to_thread(inner)
+        except Exception:
+            logger.exception("[Feishu] resource get request failed for resource_key=%s type=%s", file_key, type)
+            return f"Failed to obtain the [{type}]"
+
+        if not response.success():
+            logger.warning(
+                "[Feishu] resource get failed: resource_key=%s, type=%s, code=%s, msg=%s, log_id=%s ",
+                file_key,
+                type,
+                response.code,
+                response.msg,
+                response.get_log_id(),
+            )
+            return f"Failed to obtain the [{type}]"
+
+        image_stream = getattr(response, "file", None)
+        if image_stream is None:
+            logger.warning("[Feishu] resource get returned no file stream: resource_key=%s, type=%s", file_key, type)
+            return f"Failed to obtain the [{type}]"
+
+        try:
+            content: bytes = await asyncio.to_thread(image_stream.read)
+        except Exception:
+            logger.exception("[Feishu] failed to read resource stream: resource_key=%s, type=%s", file_key, type)
+            return f"Failed to obtain the [{type}]"
+
+        if not content:
+            logger.warning("[Feishu] empty resource content: resource_key=%s, type=%s", file_key, type)
+            return f"Failed to obtain the [{type}]"
+
+        paths = get_paths()
+        user_id = get_effective_user_id()
+        paths.ensure_thread_dirs(thread_id, user_id=user_id)
+        uploads_dir = paths.sandbox_uploads_dir(thread_id, user_id=user_id).resolve()
+
+        ext = "png" if type == "image" else "bin"
+        raw_filename = getattr(response, "file_name", "") or f"feishu_{file_key[-12:]}.{ext}"
+
+        # Sanitize filename: preserve extension, replace path chars in name part
+        if "." in raw_filename:
+            name_part, ext = raw_filename.rsplit(".", 1)
+            name_part = re.sub(r"[./\\]", "_", name_part)
+            filename = f"{name_part}.{ext}"
+        else:
+            filename = re.sub(r"[./\\]", "_", raw_filename)
+        resolved_target = uploads_dir / filename
+
+        def down_load():
+            # use thread_lock to avoid filename conflicts when writing
+            with self._thread_lock:
+                resolved_target.write_bytes(content)
+
+        try:
+            await asyncio.to_thread(down_load)
+        except Exception:
+            logger.exception("[Feishu] failed to persist downloaded resource: %s, type=%s", resolved_target, type)
+            return f"Failed to obtain the [{type}]"
+
+        virtual_path = f"{VIRTUAL_PATH_PREFIX}/uploads/{resolved_target.name}"
+
+        try:
+            sandbox_provider = get_sandbox_provider()
+            sandbox_id = sandbox_provider.acquire(thread_id)
+            if sandbox_id != "local":
+                sandbox = sandbox_provider.get(sandbox_id)
+                if sandbox is None:
+                    logger.warning("[Feishu] sandbox not found for thread_id=%s", thread_id)
+                    return f"Failed to obtain the [{type}]"
+                sandbox.update_file(virtual_path, content)
+        except Exception:
+            logger.exception("[Feishu] failed to sync resource into non-local sandbox: %s", virtual_path)
+            return f"Failed to obtain the [{type}]"
+
+        logger.info("[Feishu] downloaded resource mapped: file_key=%s -> %s", file_key, virtual_path)
+        return virtual_path
+
+    # -- message formatting ------------------------------------------------
+
+    @staticmethod
+    def _build_card_content(text: str) -> str:
+        """Build a Feishu interactive card with markdown content.
+
+        Feishu's interactive card format natively renders markdown, including
+        headers, bold/italic, code blocks, lists, and links.
+        """
+        card = {
+            "config": {"wide_screen_mode": True, "update_multi": True},
+            "elements": [{"tag": "markdown", "content": text}],
+        }
+        return json.dumps(card)
+
+    # -- reaction helpers --------------------------------------------------
+
+    async def _add_reaction(self, message_id: str, emoji_type: str = "THUMBSUP") -> None:
+        """Add an emoji reaction to a message."""
+        if not self._api_client or not self._CreateMessageReactionRequest:
+            return
+        try:
+            request = self._CreateMessageReactionRequest.builder().message_id(message_id).request_body(self._CreateMessageReactionRequestBody.builder().reaction_type(self._Emoji.builder().emoji_type(emoji_type).build()).build()).build()
+            await asyncio.to_thread(self._api_client.im.v1.message_reaction.create, request)
+            logger.info("[Feishu] reaction '%s' added to message %s", emoji_type, message_id)
+        except Exception:
+            logger.exception("[Feishu] failed to add reaction '%s' to message %s", emoji_type, message_id)
+
+    async def _reply_card(self, message_id: str, text: str) -> str | None:
+        """Reply with an interactive card and return the created card message ID."""
+        if not self._api_client:
+            return None
+
+        content = self._build_card_content(text)
+        request = self._ReplyMessageRequest.builder().message_id(message_id).request_body(self._ReplyMessageRequestBody.builder().msg_type("interactive").content(content).reply_in_thread(True).build()).build()
+        response = await asyncio.to_thread(self._api_client.im.v1.message.reply, request)
+        response_data = getattr(response, "data", None)
+        return getattr(response_data, "message_id", None)
+
+    async def _create_card(self, chat_id: str, text: str) -> None:
+        """Create a new card message in the target chat."""
+        if not self._api_client:
+            return
+
+        content = self._build_card_content(text)
+        request = self._CreateMessageRequest.builder().receive_id_type("chat_id").request_body(self._CreateMessageRequestBody.builder().receive_id(chat_id).msg_type("interactive").content(content).build()).build()
+        await asyncio.to_thread(self._api_client.im.v1.message.create, request)
+
+    async def _update_card(self, message_id: str, text: str) -> None:
+        """Patch an existing card message in place."""
+        if not self._api_client or not self._PatchMessageRequest:
+            return
+
+        content = self._build_card_content(text)
+        request = self._PatchMessageRequest.builder().message_id(message_id).request_body(self._PatchMessageRequestBody.builder().content(content).build()).build()
+        await asyncio.to_thread(self._api_client.im.v1.message.patch, request)
+
+    def _track_background_task(self, task: asyncio.Task, *, name: str, msg_id: str) -> None:
+        """Keep a strong reference to fire-and-forget tasks and surface errors."""
+        self._background_tasks.add(task)
+        task.add_done_callback(lambda done_task, task_name=name, mid=msg_id: self._finalize_background_task(done_task, task_name, mid))
+
+    def _finalize_background_task(self, task: asyncio.Task, name: str, msg_id: str) -> None:
+        self._background_tasks.discard(task)
+        self._log_task_error(task, name, msg_id)
+
+    async def _create_running_card(self, source_message_id: str, text: str) -> str | None:
+        """Create the running card and cache its message ID when available."""
+        running_card_id = await self._reply_card(source_message_id, text)
+        if running_card_id:
+            self._running_card_ids[source_message_id] = running_card_id
+            logger.info("[Feishu] running card created: source=%s card=%s", source_message_id, running_card_id)
+        else:
+            logger.warning("[Feishu] running card creation returned no message_id for source=%s, subsequent updates will fall back to new replies", source_message_id)
+        return running_card_id
+
+    def _ensure_running_card_started(self, source_message_id: str, text: str = "Working on it...") -> asyncio.Task | None:
+        """Start running-card creation once per source message."""
+        running_card_id = self._running_card_ids.get(source_message_id)
+        if running_card_id:
+            return None
+
+        running_card_task = self._running_card_tasks.get(source_message_id)
+        if running_card_task:
+            return running_card_task
+
+        running_card_task = asyncio.create_task(self._create_running_card(source_message_id, text))
+        self._running_card_tasks[source_message_id] = running_card_task
+        running_card_task.add_done_callback(lambda done_task, mid=source_message_id: self._finalize_running_card_task(mid, done_task))
+        return running_card_task
+
+    def _finalize_running_card_task(self, source_message_id: str, task: asyncio.Task) -> None:
+        if self._running_card_tasks.get(source_message_id) is task:
+            self._running_card_tasks.pop(source_message_id, None)
+        self._log_task_error(task, "create_running_card", source_message_id)
+
+    async def _ensure_running_card(self, source_message_id: str, text: str = "Working on it...") -> str | None:
+        """Ensure the in-thread running card exists and track its message ID."""
+        running_card_id = self._running_card_ids.get(source_message_id)
+        if running_card_id:
+            return running_card_id
+
+        running_card_task = self._ensure_running_card_started(source_message_id, text)
+        if running_card_task is None:
+            return self._running_card_ids.get(source_message_id)
+        return await running_card_task
+
+    async def _send_running_reply(self, message_id: str) -> None:
+        """Reply to a message in-thread with a running card."""
+        try:
+            await self._ensure_running_card(message_id)
+        except Exception:
+            logger.exception("[Feishu] failed to send running reply for message %s", message_id)
+
+    async def _send_card_message(self, msg: OutboundMessage) -> None:
+        """Send or update the Feishu card tied to the current request."""
+        source_message_id = msg.thread_ts
+        if source_message_id:
+            running_card_id = self._running_card_ids.get(source_message_id)
+            awaited_running_card_task = False
+
+            if not running_card_id:
+                running_card_task = self._running_card_tasks.get(source_message_id)
+                if running_card_task:
+                    awaited_running_card_task = True
+                    running_card_id = await running_card_task
+
+            if running_card_id:
+                try:
+                    await self._update_card(running_card_id, msg.text)
+                except Exception:
+                    if not msg.is_final:
+                        raise
+                    logger.exception(
+                        "[Feishu] failed to patch running card %s, falling back to final reply",
+                        running_card_id,
+                    )
+                    await self._reply_card(source_message_id, msg.text)
+                else:
+                    logger.info("[Feishu] running card updated: source=%s card=%s", source_message_id, running_card_id)
+            elif msg.is_final:
+                await self._reply_card(source_message_id, msg.text)
+            elif awaited_running_card_task:
+                logger.warning(
+                    "[Feishu] running card task finished without message_id for source=%s, skipping duplicate non-final creation",
+                    source_message_id,
+                )
+            else:
+                await self._ensure_running_card(source_message_id, msg.text)
+
+            if msg.is_final:
+                self._running_card_ids.pop(source_message_id, None)
+                await self._add_reaction(source_message_id, "DONE")
+            return
+
+        await self._create_card(msg.chat_id, msg.text)
+
+    # -- internal ----------------------------------------------------------
+
+    @staticmethod
+    def _log_future_error(fut, name: str, msg_id: str) -> None:
+        """Callback for run_coroutine_threadsafe futures to surface errors."""
+        try:
+            exc = fut.exception()
+            if exc:
+                logger.error("[Feishu] %s failed for msg_id=%s: %s", name, msg_id, exc)
+        except Exception:
+            pass
+
+    @staticmethod
+    def _log_task_error(task: asyncio.Task, name: str, msg_id: str) -> None:
+        """Callback for background asyncio tasks to surface errors."""
+        try:
+            exc = task.exception()
+            if exc:
+                logger.error("[Feishu] %s failed for msg_id=%s: %s", name, msg_id, exc)
+        except asyncio.CancelledError:
+            logger.info("[Feishu] %s cancelled for msg_id=%s", name, msg_id)
+        except Exception:
+            pass
+
+    async def _prepare_inbound(self, msg_id: str, inbound) -> None:
+        """Kick off Feishu side effects without delaying inbound dispatch."""
+        reaction_task = asyncio.create_task(self._add_reaction(msg_id, "OK"))
+        self._track_background_task(reaction_task, name="add_reaction", msg_id=msg_id)
+        self._ensure_running_card_started(msg_id)
+        await self.bus.publish_inbound(inbound)
+
+    def _on_message(self, event) -> None:
+        """Called by lark-oapi when a message is received (runs in lark thread)."""
+        try:
+            logger.info("[Feishu] raw event received: type=%s", type(event).__name__)
+            message = event.event.message
+            chat_id = message.chat_id
+            msg_id = message.message_id
+            sender_id = event.event.sender.sender_id.open_id
+
+            # root_id is set when the message is a reply within a Feishu thread.
+            # Use it as topic_id so all replies share the same DeerFlow thread.
+            root_id = getattr(message, "root_id", None) or None
+
+            # Parse message content
+            content = json.loads(message.content)
+
+            # files_list store the any-file-key in feishu messages, which can be used to download the file content later
+            # In Feishu channel, image_keys are independent of file_keys.
+            # The file_key includes files, videos, and audio, but does not include stickers.
+            files_list = []
+
+            if "text" in content:
+                # Handle plain text messages
+                text = content["text"]
+            elif "file_key" in content:
+                file_key = content.get("file_key")
+                if isinstance(file_key, str) and file_key:
+                    files_list.append({"file_key": file_key})
+                    text = "[file]"
+                else:
+                    text = ""
+            elif "image_key" in content:
+                image_key = content.get("image_key")
+                if isinstance(image_key, str) and image_key:
+                    files_list.append({"image_key": image_key})
+                    text = "[image]"
+                else:
+                    text = ""
+            elif "content" in content and isinstance(content["content"], list):
+                # Handle rich-text messages with a top-level "content" list (e.g., topic groups/posts)
+                text_paragraphs: list[str] = []
+                for paragraph in content["content"]:
+                    if isinstance(paragraph, list):
+                        paragraph_text_parts: list[str] = []
+                        for element in paragraph:
+                            if isinstance(element, dict):
+                                # Include both normal text and @ mentions
+                                if element.get("tag") in ("text", "at"):
+                                    text_value = element.get("text", "")
+                                    if text_value:
+                                        paragraph_text_parts.append(text_value)
+                                elif element.get("tag") == "img":
+                                    image_key = element.get("image_key")
+                                    if isinstance(image_key, str) and image_key:
+                                        files_list.append({"image_key": image_key})
+                                        paragraph_text_parts.append("[image]")
+                                elif element.get("tag") in ("file", "media"):
+                                    file_key = element.get("file_key")
+                                    if isinstance(file_key, str) and file_key:
+                                        files_list.append({"file_key": file_key})
+                                        paragraph_text_parts.append("[file]")
+                        if paragraph_text_parts:
+                            # Join text segments within a paragraph with spaces to avoid "helloworld"
+                            text_paragraphs.append(" ".join(paragraph_text_parts))
+
+                # Join paragraphs with blank lines to preserve paragraph boundaries
+                text = "\n\n".join(text_paragraphs)
+            else:
+                text = ""
+            text = text.strip()
+
+            logger.info(
+                "[Feishu] parsed message: chat_id=%s, msg_id=%s, root_id=%s, sender=%s, text=%r",
+                chat_id,
+                msg_id,
+                root_id,
+                sender_id,
+                text[:100] if text else "",
+            )
+
+            if not (text or files_list):
+                logger.info("[Feishu] empty text, ignoring message")
+                return
+
+            # Only treat known slash commands as commands; absolute paths and
+            # other slash-prefixed text should be handled as normal chat.
+            if _is_feishu_command(text):
+                msg_type = InboundMessageType.COMMAND
+            else:
+                msg_type = InboundMessageType.CHAT
+
+            # topic_id: use root_id for replies (same topic), msg_id for new messages (new topic)
+            topic_id = root_id or msg_id
+
+            inbound = self._make_inbound(
+                chat_id=chat_id,
+                user_id=sender_id,
+                text=text,
+                msg_type=msg_type,
+                thread_ts=msg_id,
+                files=files_list,
+                metadata={"message_id": msg_id, "root_id": root_id},
+            )
+            inbound.topic_id = topic_id
+
+            # Schedule on the async event loop
+            if self._main_loop and self._main_loop.is_running():
+                logger.info("[Feishu] publishing inbound message to bus (type=%s, msg_id=%s)", msg_type.value, msg_id)
+                fut = asyncio.run_coroutine_threadsafe(self._prepare_inbound(msg_id, inbound), self._main_loop)
+                fut.add_done_callback(lambda f, mid=msg_id: self._log_future_error(f, "prepare_inbound", mid))
+            else:
+                logger.warning("[Feishu] main loop not running, cannot publish inbound message")
+        except Exception:
+            logger.exception("[Feishu] error processing message")

offline-backend-20260512/backend/app/channels/message_bus.py

@@ -0,0 +1,173 @@
+"""MessageBus — async pub/sub hub that decouples channels from the agent dispatcher."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from collections.abc import Callable, Coroutine
+from dataclasses import dataclass, field
+from enum import StrEnum
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Message types
+# ---------------------------------------------------------------------------
+
+
+class InboundMessageType(StrEnum):
+    """Types of messages arriving from IM channels."""
+
+    CHAT = "chat"
+    COMMAND = "command"
+
+
+@dataclass
+class InboundMessage:
+    """A message arriving from an IM channel toward the agent dispatcher.
+
+    Attributes:
+        channel_name: Name of the source channel (e.g. "feishu", "slack").
+        chat_id: Platform-specific chat/conversation identifier.
+        user_id: Platform-specific user identifier.
+        text: The message text.
+        msg_type: Whether this is a regular chat message or a command.
+        thread_ts: Optional platform thread identifier (for threaded replies).
+        topic_id: Conversation topic identifier used to map to a DeerFlow thread.
+            Messages sharing the same ``topic_id`` within a ``chat_id`` will
+            reuse the same DeerFlow thread.  When ``None``, each message
+            creates a new thread (one-shot Q&A).
+        files: Optional list of file attachments (platform-specific dicts).
+        metadata: Arbitrary extra data from the channel.
+        created_at: Unix timestamp when the message was created.
+    """
+
+    channel_name: str
+    chat_id: str
+    user_id: str
+    text: str
+    msg_type: InboundMessageType = InboundMessageType.CHAT
+    thread_ts: str | None = None
+    topic_id: str | None = None
+    files: list[dict[str, Any]] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+    created_at: float = field(default_factory=time.time)
+
+
+@dataclass
+class ResolvedAttachment:
+    """A file attachment resolved to a host filesystem path, ready for upload.
+
+    Attributes:
+        virtual_path: Original virtual path (e.g. /mnt/user-data/outputs/report.pdf).
+        actual_path: Resolved host filesystem path.
+        filename: Basename of the file.
+        mime_type: MIME type (e.g. "application/pdf").
+        size: File size in bytes.
+        is_image: True for image/* MIME types (platforms may handle images differently).
+    """
+
+    virtual_path: str
+    actual_path: Path
+    filename: str
+    mime_type: str
+    size: int
+    is_image: bool
+
+
+@dataclass
+class OutboundMessage:
+    """A message from the agent dispatcher back to a channel.
+
+    Attributes:
+        channel_name: Target channel name (used for routing).
+        chat_id: Target chat/conversation identifier.
+        thread_id: DeerFlow thread ID that produced this response.
+        text: The response text.
+        artifacts: List of artifact paths produced by the agent.
+        is_final: Whether this is the final message in the response stream.
+        thread_ts: Optional platform thread identifier for threaded replies.
+        metadata: Arbitrary extra data.
+        created_at: Unix timestamp.
+    """
+
+    channel_name: str
+    chat_id: str
+    thread_id: str
+    text: str
+    artifacts: list[str] = field(default_factory=list)
+    attachments: list[ResolvedAttachment] = field(default_factory=list)
+    is_final: bool = True
+    thread_ts: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+    created_at: float = field(default_factory=time.time)
+
+
+# ---------------------------------------------------------------------------
+# MessageBus
+# ---------------------------------------------------------------------------
+
+OutboundCallback = Callable[[OutboundMessage], Coroutine[Any, Any, None]]
+
+
+class MessageBus:
+    """Async pub/sub hub connecting channels and the agent dispatcher.
+
+    Channels publish inbound messages; the dispatcher consumes them.
+    The dispatcher publishes outbound messages; channels receive them
+    via registered callbacks.
+    """
+
+    def __init__(self) -> None:
+        self._inbound_queue: asyncio.Queue[InboundMessage] = asyncio.Queue()
+        self._outbound_listeners: list[OutboundCallback] = []
+
+    # -- inbound -----------------------------------------------------------
+
+    async def publish_inbound(self, msg: InboundMessage) -> None:
+        """Enqueue an inbound message from a channel."""
+        await self._inbound_queue.put(msg)
+        logger.info(
+            "[Bus] inbound enqueued: channel=%s, chat_id=%s, type=%s, queue_size=%d",
+            msg.channel_name,
+            msg.chat_id,
+            msg.msg_type.value,
+            self._inbound_queue.qsize(),
+        )
+
+    async def get_inbound(self) -> InboundMessage:
+        """Block until the next inbound message is available."""
+        return await self._inbound_queue.get()
+
+    @property
+    def inbound_queue(self) -> asyncio.Queue[InboundMessage]:
+        return self._inbound_queue
+
+    # -- outbound ----------------------------------------------------------
+
+    def subscribe_outbound(self, callback: OutboundCallback) -> None:
+        """Register an async callback for outbound messages."""
+        self._outbound_listeners.append(callback)
+
+    def unsubscribe_outbound(self, callback: OutboundCallback) -> None:
+        """Remove a previously registered outbound callback."""
+        self._outbound_listeners = [cb for cb in self._outbound_listeners if cb is not callback]
+
+    async def publish_outbound(self, msg: OutboundMessage) -> None:
+        """Dispatch an outbound message to all registered listeners."""
+        logger.info(
+            "[Bus] outbound dispatching: channel=%s, chat_id=%s, listeners=%d, text_len=%d",
+            msg.channel_name,
+            msg.chat_id,
+            len(self._outbound_listeners),
+            len(msg.text),
+        )
+        for callback in self._outbound_listeners:
+            try:
+                await callback(msg)
+            except Exception:
+                logger.exception("Error in outbound callback for channel=%s", msg.channel_name)

offline-backend-20260512/backend/app/channels/service.py

@@ -0,0 +1,230 @@
+"""ChannelService — manages the lifecycle of all IM channels."""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import TYPE_CHECKING, Any
+
+from app.channels.base import Channel
+from app.channels.manager import DEFAULT_GATEWAY_URL, DEFAULT_LANGGRAPH_URL, ChannelManager
+from app.channels.message_bus import MessageBus
+from app.channels.store import ChannelStore
+
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    from deerflow.config.app_config import AppConfig
+
+# Channel name → import path for lazy loading
+_CHANNEL_REGISTRY: dict[str, str] = {
+    "dingtalk": "app.channels.dingtalk:DingTalkChannel",
+    "discord": "app.channels.discord:DiscordChannel",
+    "feishu": "app.channels.feishu:FeishuChannel",
+    "slack": "app.channels.slack:SlackChannel",
+    "telegram": "app.channels.telegram:TelegramChannel",
+    "wechat": "app.channels.wechat:WechatChannel",
+    "wecom": "app.channels.wecom:WeComChannel",
+}
+
+# Keys that indicate a user has configured credentials for a channel.
+_CHANNEL_CREDENTIAL_KEYS: dict[str, list[str]] = {
+    "dingtalk": ["client_id", "client_secret"],
+    "discord": ["bot_token"],
+    "feishu": ["app_id", "app_secret"],
+    "slack": ["bot_token", "app_token"],
+    "telegram": ["bot_token"],
+    "wecom": ["bot_id", "bot_secret"],
+    "wechat": ["bot_token"],
+}
+
+_CHANNELS_LANGGRAPH_URL_ENV = "DEER_FLOW_CHANNELS_LANGGRAPH_URL"
+_CHANNELS_GATEWAY_URL_ENV = "DEER_FLOW_CHANNELS_GATEWAY_URL"
+
+
+def _resolve_service_url(config: dict[str, Any], config_key: str, env_key: str, default: str) -> str:
+    value = config.pop(config_key, None)
+    if isinstance(value, str) and value.strip():
+        return value
+    env_value = os.getenv(env_key, "").strip()
+    if env_value:
+        return env_value
+    return default
+
+
+class ChannelService:
+    """Manages the lifecycle of all configured IM channels.
+
+    Reads configuration from ``config.yaml`` under the ``channels`` key,
+    instantiates enabled channels, and starts the ChannelManager dispatcher.
+    """
+
+    def __init__(self, channels_config: dict[str, Any] | None = None) -> None:
+        self.bus = MessageBus()
+        self.store = ChannelStore()
+        config = dict(channels_config or {})
+        langgraph_url = _resolve_service_url(config, "langgraph_url", _CHANNELS_LANGGRAPH_URL_ENV, DEFAULT_LANGGRAPH_URL)
+        gateway_url = _resolve_service_url(config, "gateway_url", _CHANNELS_GATEWAY_URL_ENV, DEFAULT_GATEWAY_URL)
+        default_session = config.pop("session", None)
+        channel_sessions = {name: channel_config.get("session") for name, channel_config in config.items() if isinstance(channel_config, dict)}
+        self.manager = ChannelManager(
+            bus=self.bus,
+            store=self.store,
+            langgraph_url=langgraph_url,
+            gateway_url=gateway_url,
+            default_session=default_session if isinstance(default_session, dict) else None,
+            channel_sessions=channel_sessions,
+        )
+        self._channels: dict[str, Any] = {}  # name -> Channel instance
+        self._config = config
+        self._running = False
+
+    @classmethod
+    def from_app_config(cls, app_config: AppConfig | None = None) -> ChannelService:
+        """Create a ChannelService from the application config."""
+        if app_config is None:
+            from deerflow.config.app_config import get_app_config
+
+            app_config = get_app_config()
+        channels_config = {}
+        # extra fields are allowed by AppConfig (extra="allow")
+        extra = app_config.model_extra or {}
+        if "channels" in extra:
+            channels_config = extra["channels"]
+        return cls(channels_config=channels_config)
+
+    async def start(self) -> None:
+        """Start the manager and all enabled channels."""
+        if self._running:
+            return
+
+        await self.manager.start()
+
+        for name, channel_config in self._config.items():
+            if not isinstance(channel_config, dict):
+                continue
+            if not channel_config.get("enabled", False):
+                cred_keys = _CHANNEL_CREDENTIAL_KEYS.get(name, [])
+                has_creds = any(not isinstance(channel_config.get(k), bool) and channel_config.get(k) is not None and str(channel_config[k]).strip() for k in cred_keys)
+                if has_creds:
+                    logger.warning(
+                        "Channel '%s' has credentials configured but is disabled. Set enabled: true under channels.%s in config.yaml to activate it.",
+                        name,
+                        name,
+                    )
+                else:
+                    logger.info("Channel %s is disabled, skipping", name)
+                continue
+
+            await self._start_channel(name, channel_config)
+
+        self._running = True
+        logger.info("ChannelService started with channels: %s", list(self._channels.keys()))
+
+    async def stop(self) -> None:
+        """Stop all channels and the manager."""
+        for name, channel in list(self._channels.items()):
+            try:
+                await channel.stop()
+                logger.info("Channel %s stopped", name)
+            except Exception:
+                logger.exception("Error stopping channel %s", name)
+        self._channels.clear()
+
+        await self.manager.stop()
+        self._running = False
+        logger.info("ChannelService stopped")
+
+    async def restart_channel(self, name: str) -> bool:
+        """Restart a specific channel. Returns True if successful."""
+        if name in self._channels:
+            try:
+                await self._channels[name].stop()
+            except Exception:
+                logger.exception("Error stopping channel %s for restart", name)
+            del self._channels[name]
+
+        config = self._config.get(name)
+        if not config or not isinstance(config, dict):
+            logger.warning("No config for channel %s", name)
+            return False
+
+        return await self._start_channel(name, config)
+
+    async def _start_channel(self, name: str, config: dict[str, Any]) -> bool:
+        """Instantiate and start a single channel."""
+        import_path = _CHANNEL_REGISTRY.get(name)
+        if not import_path:
+            logger.warning("Unknown channel type: %s", name)
+            return False
+
+        try:
+            from deerflow.reflection import resolve_class
+
+            channel_cls = resolve_class(import_path, base_class=None)
+        except Exception:
+            logger.exception("Failed to import channel class for %s", name)
+            return False
+
+        try:
+            channel = channel_cls(bus=self.bus, config=config)
+            self._channels[name] = channel
+            await channel.start()
+            if not channel.is_running:
+                self._channels.pop(name, None)
+                logger.error("Channel %s did not enter a running state after start()", name)
+                return False
+            logger.info("Channel %s started", name)
+            return True
+        except Exception:
+            self._channels.pop(name, None)
+            logger.exception("Failed to start channel %s", name)
+            return False
+
+    def get_status(self) -> dict[str, Any]:
+        """Return status information for all channels."""
+        channels_status = {}
+        for name in _CHANNEL_REGISTRY:
+            config = self._config.get(name, {})
+            enabled = isinstance(config, dict) and config.get("enabled", False)
+            running = name in self._channels and self._channels[name].is_running
+            channels_status[name] = {
+                "enabled": enabled,
+                "running": running,
+            }
+        return {
+            "service_running": self._running,
+            "channels": channels_status,
+        }
+
+    def get_channel(self, name: str) -> Channel | None:
+        """Return a running channel instance by name when available."""
+        return self._channels.get(name)
+
+
+# -- singleton access -------------------------------------------------------
+
+_channel_service: ChannelService | None = None
+
+
+def get_channel_service() -> ChannelService | None:
+    """Get the singleton ChannelService instance (if started)."""
+    return _channel_service
+
+
+async def start_channel_service(app_config: AppConfig | None = None) -> ChannelService:
+    """Create and start the global ChannelService from app config."""
+    global _channel_service
+    if _channel_service is not None:
+        return _channel_service
+    _channel_service = ChannelService.from_app_config(app_config)
+    await _channel_service.start()
+    return _channel_service
+
+
+async def stop_channel_service() -> None:
+    """Stop the global ChannelService."""
+    global _channel_service
+    if _channel_service is not None:
+        await _channel_service.stop()
+        _channel_service = None

offline-backend-20260512/backend/app/channels/slack.py

@@ -0,0 +1,264 @@
+"""Slack channel — connects via Socket Mode (no public IP needed)."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+
+from markdown_to_mrkdwn import SlackMarkdownConverter
+
+from app.channels.base import Channel
+from app.channels.message_bus import InboundMessageType, MessageBus, OutboundMessage, ResolvedAttachment
+
+logger = logging.getLogger(__name__)
+
+_slack_md_converter = SlackMarkdownConverter()
+
+
+def _normalize_allowed_users(allowed_users: Any) -> set[str]:
+    if allowed_users is None:
+        return set()
+    if isinstance(allowed_users, str):
+        values = [allowed_users]
+    elif isinstance(allowed_users, list | tuple | set):
+        values = allowed_users
+    else:
+        logger.warning(
+            "Slack allowed_users should be a list of Slack user IDs or a single Slack user ID string; treating %s as one string value",
+            type(allowed_users).__name__,
+        )
+        values = [allowed_users]
+    return {str(user_id) for user_id in values if str(user_id)}
+
+
+class SlackChannel(Channel):
+    """Slack IM channel using Socket Mode (WebSocket, no public IP).
+
+    Configuration keys (in ``config.yaml`` under ``channels.slack``):
+        - ``bot_token``: Slack Bot User OAuth Token (xoxb-...).
+        - ``app_token``: Slack App-Level Token (xapp-...) for Socket Mode.
+        - ``allowed_users``: (optional) List of allowed Slack user IDs, or a
+          single Slack user ID string as shorthand. Empty = allow all. Other
+          scalar values are treated as a single string with a warning.
+    """
+
+    def __init__(self, bus: MessageBus, config: dict[str, Any]) -> None:
+        super().__init__(name="slack", bus=bus, config=config)
+        self._socket_client = None
+        self._web_client = None
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._allowed_users = _normalize_allowed_users(config.get("allowed_users", []))
+
+    async def start(self) -> None:
+        if self._running:
+            return
+
+        try:
+            from slack_sdk import WebClient
+            from slack_sdk.socket_mode import SocketModeClient
+            from slack_sdk.socket_mode.response import SocketModeResponse
+        except ImportError:
+            logger.error("slack-sdk is not installed. Install it with: uv add slack-sdk")
+            return
+
+        self._SocketModeResponse = SocketModeResponse
+
+        bot_token = self.config.get("bot_token", "")
+        app_token = self.config.get("app_token", "")
+
+        if not bot_token or not app_token:
+            logger.error("Slack channel requires bot_token and app_token")
+            return
+
+        self._web_client = WebClient(token=bot_token)
+        self._socket_client = SocketModeClient(
+            app_token=app_token,
+            web_client=self._web_client,
+        )
+        self._loop = asyncio.get_event_loop()
+
+        self._socket_client.socket_mode_request_listeners.append(self._on_socket_event)
+
+        self._running = True
+        self.bus.subscribe_outbound(self._on_outbound)
+
+        # Start socket mode in background thread
+        asyncio.get_event_loop().run_in_executor(None, self._socket_client.connect)
+        logger.info("Slack channel started")
+
+    async def stop(self) -> None:
+        self._running = False
+        self.bus.unsubscribe_outbound(self._on_outbound)
+        if self._socket_client:
+            self._socket_client.close()
+            self._socket_client = None
+        logger.info("Slack channel stopped")
+
+    async def send(self, msg: OutboundMessage, *, _max_retries: int = 3) -> None:
+        if not self._web_client:
+            return
+
+        kwargs: dict[str, Any] = {
+            "channel": msg.chat_id,
+            "text": _slack_md_converter.convert(msg.text),
+        }
+        if msg.thread_ts:
+            kwargs["thread_ts"] = msg.thread_ts
+
+        last_exc: Exception | None = None
+        for attempt in range(_max_retries):
+            try:
+                await asyncio.to_thread(self._web_client.chat_postMessage, **kwargs)
+                # Add a completion reaction to the thread root
+                if msg.thread_ts:
+                    await asyncio.to_thread(
+                        self._add_reaction,
+                        msg.chat_id,
+                        msg.thread_ts,
+                        "white_check_mark",
+                    )
+                return
+            except Exception as exc:
+                last_exc = exc
+                if attempt < _max_retries - 1:
+                    delay = 2**attempt  # 1s, 2s
+                    logger.warning(
+                        "[Slack] send failed (attempt %d/%d), retrying in %ds: %s",
+                        attempt + 1,
+                        _max_retries,
+                        delay,
+                        exc,
+                    )
+                    await asyncio.sleep(delay)
+
+        logger.error("[Slack] send failed after %d attempts: %s", _max_retries, last_exc)
+        # Add failure reaction on error
+        if msg.thread_ts:
+            try:
+                await asyncio.to_thread(
+                    self._add_reaction,
+                    msg.chat_id,
+                    msg.thread_ts,
+                    "x",
+                )
+            except Exception:
+                pass
+        if last_exc is None:
+            raise RuntimeError("Slack send failed without an exception from any attempt")
+        raise last_exc
+
+    async def send_file(self, msg: OutboundMessage, attachment: ResolvedAttachment) -> bool:
+        if not self._web_client:
+            return False
+
+        try:
+            kwargs: dict[str, Any] = {
+                "channel": msg.chat_id,
+                "file": str(attachment.actual_path),
+                "filename": attachment.filename,
+                "title": attachment.filename,
+            }
+            if msg.thread_ts:
+                kwargs["thread_ts"] = msg.thread_ts
+
+            await asyncio.to_thread(self._web_client.files_upload_v2, **kwargs)
+            logger.info("[Slack] file uploaded: %s to channel=%s", attachment.filename, msg.chat_id)
+            return True
+        except Exception:
+            logger.exception("[Slack] failed to upload file: %s", attachment.filename)
+            return False
+
+    # -- internal ----------------------------------------------------------
+
+    def _add_reaction(self, channel_id: str, timestamp: str, emoji: str) -> None:
+        """Add an emoji reaction to a message (best-effort, non-blocking)."""
+        if not self._web_client:
+            return
+        try:
+            self._web_client.reactions_add(
+                channel=channel_id,
+                timestamp=timestamp,
+                name=emoji,
+            )
+        except Exception as exc:
+            if "already_reacted" not in str(exc):
+                logger.warning("[Slack] failed to add reaction %s: %s", emoji, exc)
+
+    def _send_running_reply(self, channel_id: str, thread_ts: str) -> None:
+        """Send a 'Working on it......' reply in the thread (called from SDK thread)."""
+        if not self._web_client:
+            return
+        try:
+            self._web_client.chat_postMessage(
+                channel=channel_id,
+                text=":hourglass_flowing_sand: Working on it...",
+                thread_ts=thread_ts,
+            )
+            logger.info("[Slack] 'Working on it...' reply sent in channel=%s, thread_ts=%s", channel_id, thread_ts)
+        except Exception:
+            logger.exception("[Slack] failed to send running reply in channel=%s", channel_id)
+
+    def _on_socket_event(self, client, req) -> None:
+        """Called by slack-sdk for each Socket Mode event."""
+        try:
+            # Acknowledge the event
+            response = self._SocketModeResponse(envelope_id=req.envelope_id)
+            client.send_socket_mode_response(response)
+
+            event_type = req.type
+            if event_type != "events_api":
+                return
+
+            event = req.payload.get("event", {})
+            etype = event.get("type", "")
+
+            # Handle message events (DM or @mention)
+            if etype in ("message", "app_mention"):
+                self._handle_message_event(event)
+
+        except Exception:
+            logger.exception("Error processing Slack event")
+
+    def _handle_message_event(self, event: dict) -> None:
+        # Ignore bot messages
+        if event.get("bot_id") or event.get("subtype"):
+            return
+
+        user_id = event.get("user", "")
+
+        # Check allowed users
+        if self._allowed_users and user_id not in self._allowed_users:
+            logger.debug("Ignoring message from non-allowed user: %s", user_id)
+            return
+
+        text = event.get("text", "").strip()
+        if not text:
+            return
+
+        channel_id = event.get("channel", "")
+        thread_ts = event.get("thread_ts") or event.get("ts", "")
+
+        if text.startswith("/"):
+            msg_type = InboundMessageType.COMMAND
+        else:
+            msg_type = InboundMessageType.CHAT
+
+        # topic_id: use thread_ts as the topic identifier.
+        # For threaded messages, thread_ts is the root message ts (shared topic).
+        # For non-threaded messages, thread_ts is the message's own ts (new topic).
+        inbound = self._make_inbound(
+            chat_id=channel_id,
+            user_id=user_id,
+            text=text,
+            msg_type=msg_type,
+            thread_ts=thread_ts,
+        )
+        inbound.topic_id = thread_ts
+
+        if self._loop and self._loop.is_running():
+            # Acknowledge with an eyes reaction
+            self._add_reaction(channel_id, event.get("ts", thread_ts), "eyes")
+            # Send "running" reply first (fire-and-forget from SDK thread)
+            self._send_running_reply(channel_id, thread_ts)
+            asyncio.run_coroutine_threadsafe(self.bus.publish_inbound(inbound), self._loop)

offline-backend-20260512/backend/app/channels/store.py

@@ -0,0 +1,153 @@
+"""ChannelStore — persists IM chat-to-DeerFlow thread mappings."""
+
+from __future__ import annotations
+
+import json
+import logging
+import tempfile
+import threading
+import time
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class ChannelStore:
+    """JSON-file-backed store that maps IM conversations to DeerFlow threads.
+
+    Data layout (on disk)::
+
+        {
+            "<channel_name>:<chat_id>": {
+                "thread_id": "<uuid>",
+                "user_id": "<platform_user>",
+                "created_at": 1700000000.0,
+                "updated_at": 1700000000.0
+            },
+            ...
+        }
+
+    The store is intentionally simple — a single JSON file that is atomically
+    rewritten on every mutation. For production workloads with high concurrency,
+    this can be swapped for a proper database backend.
+    """
+
+    def __init__(self, path: str | Path | None = None) -> None:
+        if path is None:
+            from deerflow.config.paths import get_paths
+
+            path = Path(get_paths().base_dir) / "channels" / "store.json"
+        self._path = Path(path)
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        self._data: dict[str, dict[str, Any]] = self._load()
+        self._lock = threading.Lock()
+
+    # -- persistence -------------------------------------------------------
+
+    def _load(self) -> dict[str, dict[str, Any]]:
+        if self._path.exists():
+            try:
+                return json.loads(self._path.read_text(encoding="utf-8"))
+            except (json.JSONDecodeError, OSError):
+                logger.warning("Corrupt channel store at %s, starting fresh", self._path)
+        return {}
+
+    def _save(self) -> None:
+        fd = tempfile.NamedTemporaryFile(
+            mode="w",
+            dir=self._path.parent,
+            suffix=".tmp",
+            delete=False,
+        )
+        try:
+            json.dump(self._data, fd, indent=2)
+            fd.close()
+            Path(fd.name).replace(self._path)
+        except BaseException:
+            fd.close()
+            Path(fd.name).unlink(missing_ok=True)
+            raise
+
+    # -- key helpers -------------------------------------------------------
+
+    @staticmethod
+    def _key(channel_name: str, chat_id: str, topic_id: str | None = None) -> str:
+        if topic_id:
+            return f"{channel_name}:{chat_id}:{topic_id}"
+        return f"{channel_name}:{chat_id}"
+
+    # -- public API --------------------------------------------------------
+
+    def get_thread_id(self, channel_name: str, chat_id: str, topic_id: str | None = None) -> str | None:
+        """Look up the DeerFlow thread_id for a given IM conversation/topic."""
+        entry = self._data.get(self._key(channel_name, chat_id, topic_id))
+        return entry["thread_id"] if entry else None
+
+    def set_thread_id(
+        self,
+        channel_name: str,
+        chat_id: str,
+        thread_id: str,
+        *,
+        topic_id: str | None = None,
+        user_id: str = "",
+    ) -> None:
+        """Create or update the mapping for an IM conversation/topic."""
+        with self._lock:
+            key = self._key(channel_name, chat_id, topic_id)
+            now = time.time()
+            existing = self._data.get(key)
+            self._data[key] = {
+                "thread_id": thread_id,
+                "user_id": user_id,
+                "created_at": existing["created_at"] if existing else now,
+                "updated_at": now,
+            }
+            self._save()
+
+    def remove(self, channel_name: str, chat_id: str, topic_id: str | None = None) -> bool:
+        """Remove a mapping.
+
+        If ``topic_id`` is provided, only that specific conversation/topic mapping is removed.
+        If ``topic_id`` is omitted, all mappings whose key starts with
+        ``"<channel_name>:<chat_id>"`` (including topic-specific ones) are removed.
+
+        Returns True if at least one mapping was removed.
+        """
+        with self._lock:
+            # Remove a specific conversation/topic mapping.
+            if topic_id is not None:
+                key = self._key(channel_name, chat_id, topic_id)
+                if key in self._data:
+                    del self._data[key]
+                    self._save()
+                    return True
+                return False
+
+            # Remove all mappings for this channel/chat_id (base and any topic-specific keys).
+            prefix = self._key(channel_name, chat_id)
+            keys_to_delete = [k for k in self._data if k == prefix or k.startswith(prefix + ":")]
+            if not keys_to_delete:
+                return False
+
+            for k in keys_to_delete:
+                del self._data[k]
+            self._save()
+            return True
+
+    def list_entries(self, channel_name: str | None = None) -> list[dict[str, Any]]:
+        """List all stored mappings, optionally filtered by channel."""
+        results = []
+        for key, entry in self._data.items():
+            parts = key.split(":", 2)
+            ch = parts[0]
+            chat = parts[1] if len(parts) > 1 else ""
+            topic = parts[2] if len(parts) > 2 else None
+            if channel_name and ch != channel_name:
+                continue
+            item: dict[str, Any] = {"channel_name": ch, "chat_id": chat, **entry}
+            if topic is not None:
+                item["topic_id"] = topic
+            results.append(item)
+        return results

offline-backend-20260512/backend/app/channels/telegram.py

@@ -0,0 +1,317 @@
+"""Telegram channel — connects via long-polling (no public IP needed)."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import threading
+from typing import Any
+
+from app.channels.base import Channel
+from app.channels.message_bus import InboundMessage, InboundMessageType, MessageBus, OutboundMessage, ResolvedAttachment
+
+logger = logging.getLogger(__name__)
+
+
+class TelegramChannel(Channel):
+    """Telegram bot channel using long-polling.
+
+    Configuration keys (in ``config.yaml`` under ``channels.telegram``):
+        - ``bot_token``: Telegram Bot API token (from @BotFather).
+        - ``allowed_users``: (optional) List of allowed Telegram user IDs. Empty = allow all.
+    """
+
+    def __init__(self, bus: MessageBus, config: dict[str, Any]) -> None:
+        super().__init__(name="telegram", bus=bus, config=config)
+        self._application = None
+        self._thread: threading.Thread | None = None
+        self._tg_loop: asyncio.AbstractEventLoop | None = None
+        self._main_loop: asyncio.AbstractEventLoop | None = None
+        self._allowed_users: set[int] = set()
+        for uid in config.get("allowed_users", []):
+            try:
+                self._allowed_users.add(int(uid))
+            except (ValueError, TypeError):
+                pass
+        # chat_id -> last sent message_id for threaded replies
+        self._last_bot_message: dict[str, int] = {}
+
+    async def start(self) -> None:
+        if self._running:
+            return
+
+        try:
+            from telegram.ext import ApplicationBuilder, CommandHandler, MessageHandler, filters
+        except ImportError:
+            logger.error("python-telegram-bot is not installed. Install it with: uv add python-telegram-bot")
+            return
+
+        bot_token = self.config.get("bot_token", "")
+        if not bot_token:
+            logger.error("Telegram channel requires bot_token")
+            return
+
+        self._main_loop = asyncio.get_event_loop()
+        self._running = True
+        self.bus.subscribe_outbound(self._on_outbound)
+
+        # Build the application
+        app = ApplicationBuilder().token(bot_token).build()
+
+        # Command handlers
+        app.add_handler(CommandHandler("start", self._cmd_start))
+        app.add_handler(CommandHandler("new", self._cmd_generic))
+        app.add_handler(CommandHandler("status", self._cmd_generic))
+        app.add_handler(CommandHandler("models", self._cmd_generic))
+        app.add_handler(CommandHandler("memory", self._cmd_generic))
+        app.add_handler(CommandHandler("help", self._cmd_generic))
+
+        # General message handler
+        app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, self._on_text))
+
+        self._application = app
+
+        # Run polling in a dedicated thread with its own event loop
+        self._thread = threading.Thread(target=self._run_polling, daemon=True)
+        self._thread.start()
+        logger.info("Telegram channel started")
+
+    async def stop(self) -> None:
+        self._running = False
+        self.bus.unsubscribe_outbound(self._on_outbound)
+        if self._tg_loop and self._tg_loop.is_running():
+            self._tg_loop.call_soon_threadsafe(self._tg_loop.stop)
+        if self._thread:
+            self._thread.join(timeout=10)
+            self._thread = None
+        self._application = None
+        logger.info("Telegram channel stopped")
+
+    async def send(self, msg: OutboundMessage, *, _max_retries: int = 3) -> None:
+        if not self._application:
+            return
+
+        try:
+            chat_id = int(msg.chat_id)
+        except (ValueError, TypeError):
+            logger.error("Invalid Telegram chat_id: %s", msg.chat_id)
+            return
+
+        kwargs: dict[str, Any] = {"chat_id": chat_id, "text": msg.text}
+
+        # Reply to the last bot message in this chat for threading
+        reply_to = self._last_bot_message.get(msg.chat_id)
+        if reply_to:
+            kwargs["reply_to_message_id"] = reply_to
+
+        bot = self._application.bot
+        last_exc: Exception | None = None
+        for attempt in range(_max_retries):
+            try:
+                sent = await bot.send_message(**kwargs)
+                self._last_bot_message[msg.chat_id] = sent.message_id
+                return
+            except Exception as exc:
+                last_exc = exc
+                if attempt < _max_retries - 1:
+                    delay = 2**attempt  # 1s, 2s
+                    logger.warning(
+                        "[Telegram] send failed (attempt %d/%d), retrying in %ds: %s",
+                        attempt + 1,
+                        _max_retries,
+                        delay,
+                        exc,
+                    )
+                    await asyncio.sleep(delay)
+
+        logger.error("[Telegram] send failed after %d attempts: %s", _max_retries, last_exc)
+        if last_exc is None:
+            raise RuntimeError("Telegram send failed without an exception from any attempt")
+        raise last_exc
+
+    async def send_file(self, msg: OutboundMessage, attachment: ResolvedAttachment) -> bool:
+        if not self._application:
+            return False
+
+        try:
+            chat_id = int(msg.chat_id)
+        except (ValueError, TypeError):
+            logger.error("[Telegram] Invalid chat_id: %s", msg.chat_id)
+            return False
+
+        # Telegram limits: 10MB for photos, 50MB for documents
+        if attachment.size > 50 * 1024 * 1024:
+            logger.warning("[Telegram] file too large (%d bytes), skipping: %s", attachment.size, attachment.filename)
+            return False
+
+        bot = self._application.bot
+        reply_to = self._last_bot_message.get(msg.chat_id)
+
+        try:
+            if attachment.is_image and attachment.size <= 10 * 1024 * 1024:
+                with open(attachment.actual_path, "rb") as f:
+                    kwargs: dict[str, Any] = {"chat_id": chat_id, "photo": f}
+                    if reply_to:
+                        kwargs["reply_to_message_id"] = reply_to
+                    sent = await bot.send_photo(**kwargs)
+            else:
+                from telegram import InputFile
+
+                with open(attachment.actual_path, "rb") as f:
+                    input_file = InputFile(f, filename=attachment.filename)
+                    kwargs = {"chat_id": chat_id, "document": input_file}
+                    if reply_to:
+                        kwargs["reply_to_message_id"] = reply_to
+                    sent = await bot.send_document(**kwargs)
+
+            self._last_bot_message[msg.chat_id] = sent.message_id
+            logger.info("[Telegram] file sent: %s to chat=%s", attachment.filename, msg.chat_id)
+            return True
+        except Exception:
+            logger.exception("[Telegram] failed to send file: %s", attachment.filename)
+            return False
+
+    # -- helpers -----------------------------------------------------------
+
+    async def _send_running_reply(self, chat_id: str, reply_to_message_id: int) -> None:
+        """Send a 'Working on it...' reply to the user's message."""
+        if not self._application:
+            return
+        try:
+            bot = self._application.bot
+            await bot.send_message(
+                chat_id=int(chat_id),
+                text="Working on it...",
+                reply_to_message_id=reply_to_message_id,
+            )
+            logger.info("[Telegram] 'Working on it...' reply sent in chat=%s", chat_id)
+        except Exception:
+            logger.exception("[Telegram] failed to send running reply in chat=%s", chat_id)
+
+    # -- internal ----------------------------------------------------------
+    @staticmethod
+    def _log_future_error(fut, name: str, msg_id: str):
+        try:
+            exc = fut.exception()
+            if exc:
+                logger.error("[Telegram] %s failed for msg_id=%s: %s", name, msg_id, exc)
+        except Exception:
+            logger.exception("[Telegram] Failed to inspect future for %s (msg_id=%s)", name, msg_id)
+
+    def _run_polling(self) -> None:
+        """Run telegram polling in a dedicated thread."""
+        self._tg_loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(self._tg_loop)
+        try:
+            # Cannot use run_polling() because it calls add_signal_handler(),
+            # which only works in the main thread.  Instead, manually
+            # initialize the application and start the updater.
+            self._tg_loop.run_until_complete(self._application.initialize())
+            self._tg_loop.run_until_complete(self._application.start())
+            self._tg_loop.run_until_complete(self._application.updater.start_polling())
+            self._tg_loop.run_forever()
+        except Exception:
+            if self._running:
+                logger.exception("Telegram polling error")
+        finally:
+            # Graceful shutdown
+            try:
+                if self._application.updater.running:
+                    self._tg_loop.run_until_complete(self._application.updater.stop())
+                self._tg_loop.run_until_complete(self._application.stop())
+                self._tg_loop.run_until_complete(self._application.shutdown())
+            except Exception:
+                logger.exception("Error during Telegram shutdown")
+
+    def _check_user(self, user_id: int) -> bool:
+        if not self._allowed_users:
+            return True
+        return user_id in self._allowed_users
+
+    async def _cmd_start(self, update, context) -> None:
+        """Handle /start command."""
+        if not self._check_user(update.effective_user.id):
+            return
+        await update.message.reply_text("Welcome to DeerFlow! Send me a message to start a conversation.\nType /help for available commands.")
+
+    async def _process_incoming_with_reply(self, chat_id: str, msg_id: int, inbound: InboundMessage) -> None:
+        await self._send_running_reply(chat_id, msg_id)
+        await self.bus.publish_inbound(inbound)
+
+    async def _cmd_generic(self, update, context) -> None:
+        """Forward slash commands to the channel manager."""
+        if not self._check_user(update.effective_user.id):
+            return
+
+        text = update.message.text
+        chat_id = str(update.effective_chat.id)
+        user_id = str(update.effective_user.id)
+        msg_id = str(update.message.message_id)
+
+        # Use the same topic_id logic as _on_text so that commands
+        # like /new target the correct thread mapping.
+        if update.effective_chat.type == "private":
+            topic_id = None
+        else:
+            reply_to = update.message.reply_to_message
+            if reply_to:
+                topic_id = str(reply_to.message_id)
+            else:
+                topic_id = msg_id
+
+        inbound = self._make_inbound(
+            chat_id=chat_id,
+            user_id=user_id,
+            text=text,
+            msg_type=InboundMessageType.COMMAND,
+            thread_ts=msg_id,
+        )
+        inbound.topic_id = topic_id
+
+        if self._main_loop and self._main_loop.is_running():
+            fut = asyncio.run_coroutine_threadsafe(self._process_incoming_with_reply(chat_id, update.message.message_id, inbound), self._main_loop)
+            fut.add_done_callback(lambda f: self._log_future_error(f, "process_incoming_with_reply", update.message.message_id))
+        else:
+            logger.warning("[Telegram] Main loop not running. Cannot publish inbound message.")
+
+    async def _on_text(self, update, context) -> None:
+        """Handle regular text messages."""
+        if not self._check_user(update.effective_user.id):
+            return
+
+        text = update.message.text.strip()
+        if not text:
+            return
+
+        chat_id = str(update.effective_chat.id)
+        user_id = str(update.effective_user.id)
+        msg_id = str(update.message.message_id)
+
+        # topic_id determines which DeerFlow thread the message maps to.
+        # In private chats, use None so that all messages share a single
+        # thread (the store key becomes "channel:chat_id").
+        # In group chats, use the reply-to message id or the current
+        # message id to keep separate conversation threads.
+        if update.effective_chat.type == "private":
+            topic_id = None
+        else:
+            reply_to = update.message.reply_to_message
+            if reply_to:
+                topic_id = str(reply_to.message_id)
+            else:
+                topic_id = msg_id
+
+        inbound = self._make_inbound(
+            chat_id=chat_id,
+            user_id=user_id,
+            text=text,
+            msg_type=InboundMessageType.CHAT,
+            thread_ts=msg_id,
+        )
+        inbound.topic_id = topic_id
+
+        if self._main_loop and self._main_loop.is_running():
+            fut = asyncio.run_coroutine_threadsafe(self._process_incoming_with_reply(chat_id, update.message.message_id, inbound), self._main_loop)
+            fut.add_done_callback(lambda f: self._log_future_error(f, "process_incoming_with_reply", update.message.message_id))
+        else:
+            logger.warning("[Telegram] Main loop not running. Cannot publish inbound message.")

offline-backend-20260512/backend/app/channels/wecom.py

@@ -0,0 +1,398 @@
+from __future__ import annotations
+
+import asyncio
+import base64
+import hashlib
+import logging
+from collections.abc import Awaitable, Callable
+from typing import Any, cast
+
+from app.channels.base import Channel
+from app.channels.message_bus import (
+    InboundMessageType,
+    MessageBus,
+    OutboundMessage,
+    ResolvedAttachment,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class WeComChannel(Channel):
+    def __init__(self, bus: MessageBus, config: dict[str, Any]) -> None:
+        super().__init__(name="wecom", bus=bus, config=config)
+        self._bot_id: str | None = None
+        self._bot_secret: str | None = None
+        self._ws_client = None
+        self._ws_task: asyncio.Task | None = None
+        self._ws_frames: dict[str, dict[str, Any]] = {}
+        self._ws_stream_ids: dict[str, str] = {}
+        self._working_message = "Working on it..."
+
+    @property
+    def supports_streaming(self) -> bool:
+        return True
+
+    def _clear_ws_context(self, thread_ts: str | None) -> None:
+        if not thread_ts:
+            return
+        self._ws_frames.pop(thread_ts, None)
+        self._ws_stream_ids.pop(thread_ts, None)
+
+    async def _send_ws_upload_command(self, req_id: str, body: dict[str, Any], cmd: str) -> dict[str, Any]:
+        if not self._ws_client:
+            raise RuntimeError("WeCom WebSocket client is not available")
+
+        ws_manager = getattr(self._ws_client, "_ws_manager", None)
+        send_reply = getattr(ws_manager, "send_reply", None)
+        if not callable(send_reply):
+            raise RuntimeError("Installed wecom-aibot-python-sdk does not expose the WebSocket media upload API expected by DeerFlow. Use wecom-aibot-python-sdk==0.1.6 or update the adapter.")
+
+        send_reply_async = cast(Callable[[str, dict[str, Any], str], Awaitable[dict[str, Any]]], send_reply)
+        return await send_reply_async(req_id, body, cmd)
+
+    async def start(self) -> None:
+        if self._running:
+            return
+
+        bot_id = self.config.get("bot_id")
+        bot_secret = self.config.get("bot_secret")
+        working_message = self.config.get("working_message")
+
+        self._bot_id = bot_id if isinstance(bot_id, str) and bot_id else None
+        self._bot_secret = bot_secret if isinstance(bot_secret, str) and bot_secret else None
+        self._working_message = working_message if isinstance(working_message, str) and working_message else "Working on it..."
+
+        if not self._bot_id or not self._bot_secret:
+            logger.error("WeCom channel requires bot_id and bot_secret")
+            return
+
+        try:
+            from aibot import WSClient, WSClientOptions
+        except ImportError:
+            logger.error("wecom-aibot-python-sdk is not installed. Install it with: uv add wecom-aibot-python-sdk")
+            return
+        else:
+            self._ws_client = WSClient(WSClientOptions(bot_id=self._bot_id, secret=self._bot_secret, logger=logger))
+            self._ws_client.on("message.text", self._on_ws_text)
+            self._ws_client.on("message.mixed", self._on_ws_mixed)
+            self._ws_client.on("message.image", self._on_ws_image)
+            self._ws_client.on("message.file", self._on_ws_file)
+            self._ws_task = asyncio.create_task(self._ws_client.connect())
+
+            self._running = True
+            self.bus.subscribe_outbound(self._on_outbound)
+        logger.info("WeCom channel started")
+
+    async def stop(self) -> None:
+        self._running = False
+        self.bus.unsubscribe_outbound(self._on_outbound)
+        if self._ws_task:
+            try:
+                self._ws_task.cancel()
+            except Exception:
+                pass
+            self._ws_task = None
+        if self._ws_client:
+            try:
+                self._ws_client.disconnect()
+            except Exception:
+                pass
+        self._ws_client = None
+        self._ws_frames.clear()
+        self._ws_stream_ids.clear()
+        logger.info("WeCom channel stopped")
+
+    async def send(self, msg: OutboundMessage, *, _max_retries: int = 3) -> None:
+        if self._ws_client:
+            await self._send_ws(msg, _max_retries=_max_retries)
+            return
+        logger.warning("[WeCom] send called but WebSocket client is not available")
+
+    async def _on_outbound(self, msg: OutboundMessage) -> None:
+        if msg.channel_name != self.name:
+            return
+
+        try:
+            await self.send(msg)
+        except Exception:
+            logger.exception("Failed to send outbound message on channel %s", self.name)
+            if msg.is_final:
+                self._clear_ws_context(msg.thread_ts)
+            return
+
+        for attachment in msg.attachments:
+            try:
+                success = await self.send_file(msg, attachment)
+                if not success:
+                    logger.warning("[%s] file upload skipped for %s", self.name, attachment.filename)
+            except Exception:
+                logger.exception("[%s] failed to upload file %s", self.name, attachment.filename)
+
+        if msg.is_final:
+            self._clear_ws_context(msg.thread_ts)
+
+    async def send_file(self, msg: OutboundMessage, attachment: ResolvedAttachment) -> bool:
+        if not msg.is_final:
+            return True
+        if not self._ws_client:
+            return False
+        if not msg.thread_ts:
+            return False
+        frame = self._ws_frames.get(msg.thread_ts)
+        if not frame:
+            return False
+
+        media_type = "image" if attachment.is_image else "file"
+        size_limit = 2 * 1024 * 1024 if attachment.is_image else 20 * 1024 * 1024
+        if attachment.size > size_limit:
+            logger.warning(
+                "[WeCom] %s too large (%d bytes), skipping: %s",
+                media_type,
+                attachment.size,
+                attachment.filename,
+            )
+            return False
+
+        try:
+            media_id = await self._upload_media_ws(
+                media_type=media_type,
+                filename=attachment.filename,
+                path=str(attachment.actual_path),
+                size=attachment.size,
+            )
+            if not media_id:
+                return False
+
+            body = {media_type: {"media_id": media_id}, "msgtype": media_type}
+            await self._ws_client.reply(frame, body)
+            logger.debug("[WeCom] %s sent via ws: %s", media_type, attachment.filename)
+            return True
+        except Exception:
+            logger.exception("[WeCom] failed to upload/send file via ws: %s", attachment.filename)
+            return False
+
+    async def _on_ws_text(self, frame: dict[str, Any]) -> None:
+        body = frame.get("body", {}) or {}
+        text = ((body.get("text") or {}).get("content") or "").strip()
+        quote = body.get("quote", {}).get("text", {}).get("content", "").strip()
+        if not text and not quote:
+            return
+        await self._publish_ws_inbound(frame, text + (f"\nQuote message: {quote}" if quote else ""))
+
+    async def _on_ws_mixed(self, frame: dict[str, Any]) -> None:
+        body = frame.get("body", {}) or {}
+        mixed = body.get("mixed") or {}
+        items = mixed.get("msg_item") or []
+        parts: list[str] = []
+        files: list[dict[str, Any]] = []
+        for item in items:
+            item_type = (item or {}).get("msgtype")
+            if item_type == "text":
+                content = (((item or {}).get("text") or {}).get("content") or "").strip()
+                if content:
+                    parts.append(content)
+            elif item_type in ("image", "file"):
+                payload = (item or {}).get(item_type) or {}
+                url = payload.get("url")
+                aeskey = payload.get("aeskey")
+                if isinstance(url, str) and url:
+                    files.append(
+                        {
+                            "type": item_type,
+                            "url": url,
+                            "aeskey": (aeskey if isinstance(aeskey, str) and aeskey else None),
+                        }
+                    )
+        text = "\n\n".join(parts).strip()
+        if not text and not files:
+            return
+        if not text:
+            text = "（receive image/file）"
+        await self._publish_ws_inbound(frame, text, files=files)
+
+    async def _on_ws_image(self, frame: dict[str, Any]) -> None:
+        body = frame.get("body", {}) or {}
+        image = body.get("image") or {}
+        url = image.get("url")
+        aeskey = image.get("aeskey")
+        if not isinstance(url, str) or not url:
+            return
+        await self._publish_ws_inbound(
+            frame,
+            "（receive image ）",
+            files=[
+                {
+                    "type": "image",
+                    "url": url,
+                    "aeskey": aeskey if isinstance(aeskey, str) and aeskey else None,
+                }
+            ],
+        )
+
+    async def _on_ws_file(self, frame: dict[str, Any]) -> None:
+        body = frame.get("body", {}) or {}
+        file_obj = body.get("file") or {}
+        url = file_obj.get("url")
+        aeskey = file_obj.get("aeskey")
+        if not isinstance(url, str) or not url:
+            return
+        await self._publish_ws_inbound(
+            frame,
+            "（receive file）",
+            files=[
+                {
+                    "type": "file",
+                    "url": url,
+                    "aeskey": aeskey if isinstance(aeskey, str) and aeskey else None,
+                }
+            ],
+        )
+
+    async def _publish_ws_inbound(
+        self,
+        frame: dict[str, Any],
+        text: str,
+        *,
+        files: list[dict[str, Any]] | None = None,
+    ) -> None:
+        if not self._ws_client:
+            return
+        try:
+            from aibot import generate_req_id
+        except Exception:
+            return
+
+        body = frame.get("body", {}) or {}
+        msg_id = body.get("msgid")
+        if not msg_id:
+            return
+
+        user_id = (body.get("from") or {}).get("userid")
+
+        inbound_type = InboundMessageType.COMMAND if text.startswith("/") else InboundMessageType.CHAT
+        inbound = self._make_inbound(
+            chat_id=user_id,  # keep user's conversation in memory
+            user_id=user_id,
+            text=text,
+            msg_type=inbound_type,
+            thread_ts=msg_id,
+            files=files or [],
+            metadata={"aibotid": body.get("aibotid"), "chattype": body.get("chattype")},
+        )
+        inbound.topic_id = user_id  # keep the same thread
+
+        stream_id = generate_req_id("stream")
+        self._ws_frames[msg_id] = frame
+        self._ws_stream_ids[msg_id] = stream_id
+
+        try:
+            await self._ws_client.reply_stream(frame, stream_id, self._working_message, False)
+        except Exception:
+            pass
+
+        await self.bus.publish_inbound(inbound)
+
+    async def _send_ws(self, msg: OutboundMessage, *, _max_retries: int = 3) -> None:
+        if not self._ws_client:
+            return
+        try:
+            from aibot import generate_req_id
+        except Exception:
+            generate_req_id = None
+
+        if msg.thread_ts and msg.thread_ts in self._ws_frames:
+            frame = self._ws_frames[msg.thread_ts]
+            stream_id = self._ws_stream_ids.get(msg.thread_ts)
+            if not stream_id and generate_req_id:
+                stream_id = generate_req_id("stream")
+                self._ws_stream_ids[msg.thread_ts] = stream_id
+            if not stream_id:
+                return
+
+            last_exc: Exception | None = None
+            for attempt in range(_max_retries):
+                try:
+                    await self._ws_client.reply_stream(frame, stream_id, msg.text, bool(msg.is_final))
+                    return
+                except Exception as exc:
+                    last_exc = exc
+                    if attempt < _max_retries - 1:
+                        await asyncio.sleep(2**attempt)
+            if last_exc:
+                raise last_exc
+
+        body = {"msgtype": "markdown", "markdown": {"content": msg.text}}
+        last_exc = None
+        for attempt in range(_max_retries):
+            try:
+                await self._ws_client.send_message(msg.chat_id, body)
+                return
+            except Exception as exc:
+                last_exc = exc
+                if attempt < _max_retries - 1:
+                    await asyncio.sleep(2**attempt)
+        if last_exc:
+            raise last_exc
+
+    async def _upload_media_ws(
+        self,
+        *,
+        media_type: str,
+        filename: str,
+        path: str,
+        size: int,
+    ) -> str | None:
+        if not self._ws_client:
+            return None
+        try:
+            from aibot import generate_req_id
+        except Exception:
+            return None
+
+        chunk_size = 512 * 1024
+        total_chunks = (size + chunk_size - 1) // chunk_size
+        if total_chunks < 1 or total_chunks > 100:
+            logger.warning("[WeCom] invalid total_chunks=%d for %s", total_chunks, filename)
+            return None
+
+        md5_hasher = hashlib.md5()
+        with open(path, "rb") as f:
+            for chunk in iter(lambda: f.read(1024 * 1024), b""):
+                md5_hasher.update(chunk)
+        md5 = md5_hasher.hexdigest()
+
+        init_req_id = generate_req_id("aibot_upload_media_init")
+        init_body = {
+            "type": media_type,
+            "filename": filename,
+            "total_size": int(size),
+            "total_chunks": int(total_chunks),
+            "md5": md5,
+        }
+        init_ack = await self._send_ws_upload_command(init_req_id, init_body, "aibot_upload_media_init")
+        upload_id = (init_ack.get("body") or {}).get("upload_id")
+        if not upload_id:
+            logger.warning("[WeCom] upload init returned no upload_id: %s", init_ack)
+            return None
+
+        with open(path, "rb") as f:
+            for idx in range(total_chunks):
+                data = f.read(chunk_size)
+                if not data:
+                    break
+                chunk_req_id = generate_req_id("aibot_upload_media_chunk")
+                chunk_body = {
+                    "upload_id": upload_id,
+                    "chunk_index": int(idx),
+                    "base64_data": base64.b64encode(data).decode("utf-8"),
+                }
+                await self._send_ws_upload_command(chunk_req_id, chunk_body, "aibot_upload_media_chunk")
+
+        finish_req_id = generate_req_id("aibot_upload_media_finish")
+        finish_ack = await self._send_ws_upload_command(finish_req_id, {"upload_id": upload_id}, "aibot_upload_media_finish")
+        media_id = (finish_ack.get("body") or {}).get("media_id")
+        if not media_id:
+            logger.warning("[WeCom] upload finish returned no media_id: %s", finish_ack)
+            return None
+        return media_id

offline-backend-20260512/backend/app/gateway/__init__.py

@@ -0,0 +1,4 @@
+from .app import app, create_app
+from .config import GatewayConfig, get_gateway_config
+
+__all__ = ["app", "create_app", "GatewayConfig", "get_gateway_config"]

offline-backend-20260512/backend/app/gateway/app.py

@@ -0,0 +1,525 @@
+import asyncio
+import logging
+import os
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+
+from dotenv import load_dotenv
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+# Load .env BEFORE any module that reads os.environ at import time.
+# Without this, GATEWAY_CORS_ORIGINS / AUTH_JWT_SECRET / DEER_FLOW_AUTH_DISABLED
+# placed in /workspace/.env are silently ignored when the container is started
+# without explicit `-e` flags, leading to ephemeral JWT secrets, missing CORS
+# origins, and "Failed to fetch" in the browser.
+load_dotenv()
+
+from app.gateway.auth.disabled_mode import is_auth_disabled  # noqa: E402
+from app.gateway.auth_middleware import AuthMiddleware
+from app.gateway.config import get_gateway_config
+from app.gateway.csrf_middleware import CSRFMiddleware
+from app.gateway.deps import langgraph_runtime
+from app.gateway.routers import (
+    agents,
+    artifacts,
+    assistants_compat,
+    auth,
+    channels,
+    feedback,
+    mcp,
+    memory,
+    models,
+    runs,
+    scheduled_tasks,
+    skills,
+    suggestions,
+    thread_runs,
+    threads,
+    uploads,
+)
+from deerflow.config import app_config as deerflow_app_config
+from deerflow.config.app_config import apply_logging_level
+from deerflow.runtime.scheduler import ScheduledTaskService, set_scheduled_task_service
+
+AppConfig = deerflow_app_config.AppConfig
+get_app_config = deerflow_app_config.get_app_config
+
+# Default logging; lifespan overrides from config.yaml log_level.
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    datefmt="%Y-%m-%d %H:%M:%S",
+)
+
+logger = logging.getLogger(__name__)
+
+# Upper bound (seconds) each lifespan shutdown hook is allowed to run.
+# Bounds worker exit time so uvicorn's reload supervisor does not keep
+# firing signals into a worker that is stuck waiting for shutdown cleanup.
+_SHUTDOWN_HOOK_TIMEOUT_SECONDS = 5.0
+
+
+async def _ensure_admin_user(app: FastAPI) -> None:
+    """Startup hook: handle first boot and migrate orphan threads otherwise.
+
+    After admin creation, migrate orphan threads from the LangGraph
+    store (metadata.user_id unset) to the admin account. This is the
+    "no-auth → with-auth" upgrade path: users who ran DeerFlow without
+    authentication have existing LangGraph thread data that needs an
+    owner assigned.
+        First boot (no admin exists):
+            - Does NOT create any user accounts automatically.
+            - The operator must visit ``/setup`` to create the first admin.
+
+    Subsequent boots (admin already exists):
+      - Runs the one-time "no-auth → with-auth" orphan thread migration for
+        existing LangGraph thread metadata that has no owner_id.
+
+    No SQL persistence migration is needed: the four user_id columns
+    (threads_meta, runs, run_events, feedback) only come into existence
+    alongside the auth module via create_all, so freshly created tables
+    never contain NULL-owner rows.
+    """
+    from sqlalchemy import select
+
+    from app.gateway.deps import get_local_provider
+    from deerflow.persistence.engine import get_session_factory
+    from deerflow.persistence.user.model import UserRow
+
+    try:
+        provider = get_local_provider()
+    except RuntimeError:
+        # Auth persistence may not be initialized in some test/boot paths.
+        # Skip admin migration work rather than failing gateway startup.
+        logger.warning("Auth persistence not ready; skipping admin bootstrap check")
+        return
+
+    sf = get_session_factory()
+    if sf is None:
+        return
+
+    admin_count = await provider.count_admin_users()
+
+    if admin_count == 0:
+        logger.info("=" * 60)
+        logger.info("  First boot detected — no admin account exists.")
+        logger.info("  Visit /setup to complete admin account creation.")
+        logger.info("=" * 60)
+        return
+
+    # Admin already exists — run orphan thread migration for any
+    # LangGraph thread metadata that pre-dates the auth module.
+    async with sf() as session:
+        stmt = select(UserRow).where(UserRow.system_role == "admin").limit(1)
+        row = (await session.execute(stmt)).scalar_one_or_none()
+
+    if row is None:
+        return  # Should not happen (admin_count > 0 above), but be safe.
+
+    admin_id = str(row.id)
+
+    # LangGraph store orphan migration — non-fatal.
+    # This covers the "no-auth → with-auth" upgrade path for users
+    # whose existing LangGraph thread metadata has no user_id set.
+    store = getattr(app.state, "store", None)
+    if store is not None:
+        try:
+            migrated = await _migrate_orphaned_threads(store, admin_id)
+            if migrated:
+                logger.info("Migrated %d orphan LangGraph thread(s) to admin", migrated)
+        except Exception:
+            logger.exception("LangGraph thread migration failed (non-fatal)")
+
+
+async def _iter_store_items(store, namespace, *, page_size: int = 500):
+    """Paginated async iterator over a LangGraph store namespace.
+
+    Replaces the old hardcoded ``limit=1000`` call with a cursor-style
+    loop so that environments with more than one page of orphans do
+    not silently lose data. Terminates when a page is empty OR when a
+    short page arrives (indicating the last page).
+    """
+    offset = 0
+    while True:
+        batch = await store.asearch(namespace, limit=page_size, offset=offset)
+        if not batch:
+            return
+        for item in batch:
+            yield item
+        if len(batch) < page_size:
+            return
+        offset += page_size
+
+
+async def _migrate_orphaned_threads(store, admin_user_id: str) -> int:
+    """Migrate LangGraph store threads with no user_id to the given admin.
+
+    Uses cursor pagination so all orphans are migrated regardless of
+    count. Returns the number of rows migrated.
+    """
+    migrated = 0
+    async for item in _iter_store_items(store, ("threads",)):
+        metadata = item.value.get("metadata", {})
+        if not metadata.get("user_id"):
+            metadata["user_id"] = admin_user_id
+            item.value["metadata"] = metadata
+            await store.aput(("threads",), item.key, item.value)
+            migrated += 1
+    return migrated
+
+
+async def _run_db_migrations() -> None:
+    """Run Alembic migrations at startup so schema changes are applied automatically."""
+    import asyncio
+    from pathlib import Path
+
+    from alembic import command
+    from alembic.config import Config
+
+    import deerflow.persistence as _persistence_pkg
+    from deerflow.persistence.engine import get_engine
+
+    engine = get_engine()
+    if engine is None:
+        logger.info("Persistence backend=memory — skipping Alembic migrations")
+        return
+
+    db_url = str(engine.url)
+    migrations_dir = str(Path(_persistence_pkg.__file__).parent / "migrations")
+
+    def _run_sync() -> None:
+        cfg = Config()
+        cfg.set_main_option("script_location", migrations_dir)
+        cfg.set_main_option("sqlalchemy.url", db_url)
+        command.upgrade(cfg, "head")
+
+    try:
+        await asyncio.get_running_loop().run_in_executor(None, _run_sync)
+        logger.info("Database migrations applied (head)")
+    except Exception:
+        logger.exception("Database migration failed — schema may be out of date")
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
+    """Application lifespan handler."""
+
+    # Load config and check necessary environment variables at startup
+    try:
+        app.state.config = get_app_config()
+        apply_logging_level(app.state.config.log_level)
+        logger.info("Configuration loaded successfully")
+    except Exception as e:
+        error_msg = f"Failed to load configuration during gateway startup: {e}"
+        logger.exception(error_msg)
+        raise RuntimeError(error_msg) from e
+    config = get_gateway_config()
+    logger.info(f"Starting API Gateway on {config.host}:{config.port}")
+
+    # Initialize LangGraph runtime components (StreamBridge, RunManager, checkpointer, store)
+    async with langgraph_runtime(app):
+        logger.info("LangGraph runtime initialised")
+
+        # Run Alembic migrations before anything else touches the schema.
+        await _run_db_migrations()
+
+        # Ensure admin user exists (auto-create on first boot)
+        # Must run AFTER langgraph_runtime so app.state.store is available for thread migration
+        await _ensure_admin_user(app)
+
+        # Start IM channel service if any channels are configured
+        try:
+            from app.channels.service import start_channel_service
+
+            channel_service = await start_channel_service(app.state.config)
+            logger.info("Channel service started: %s", channel_service.get_status())
+        except Exception:
+            logger.exception("No IM channels configured or channel service failed to start")
+
+        scheduled_tasks_enabled = os.environ.get("SCHEDULED_TASKS_ENABLED", "true").strip().lower()
+        if scheduled_tasks_enabled in {"0", "false", "no", "off"}:
+            logger.info("Scheduled task service disabled by SCHEDULED_TASKS_ENABLED=%s", scheduled_tasks_enabled)
+        else:
+            try:
+                scheduled_task_store = getattr(app.state, "scheduled_task_store", None)
+                if scheduled_task_store is not None:
+                    scheduler_service = ScheduledTaskService(app, scheduled_task_store)
+                    app.state.scheduled_task_service = scheduler_service
+                    set_scheduled_task_service(scheduler_service)
+                    await scheduler_service.start()
+                    logger.info("Scheduled task service started")
+            except Exception:
+                logger.exception("Scheduled task service failed to start")
+
+        yield
+
+        try:
+            scheduler_service = getattr(app.state, "scheduled_task_service", None)
+            if scheduler_service is not None:
+                await scheduler_service.stop()
+        except Exception:
+            logger.exception("Failed to stop scheduled task service")
+        finally:
+            set_scheduled_task_service(None)
+
+        # Stop channel service on shutdown (bounded to prevent worker hang)
+        try:
+            from app.channels.service import stop_channel_service
+
+            await asyncio.wait_for(
+                stop_channel_service(),
+                timeout=_SHUTDOWN_HOOK_TIMEOUT_SECONDS,
+            )
+        except TimeoutError:
+            logger.warning(
+                "Channel service shutdown exceeded %.1fs; proceeding with worker exit.",
+                _SHUTDOWN_HOOK_TIMEOUT_SECONDS,
+            )
+        except Exception:
+            logger.exception("Failed to stop channel service")
+
+    logger.info("Shutting down API Gateway")
+
+
+def create_app() -> FastAPI:
+    """Create and configure the FastAPI application.
+
+    Returns:
+        Configured FastAPI application instance.
+    """
+    config = get_gateway_config()
+    docs_kwargs = {"docs_url": "/docs", "redoc_url": "/redoc", "openapi_url": "/openapi.json"} if config.enable_docs else {"docs_url": None, "redoc_url": None, "openapi_url": None}
+
+    app = FastAPI(
+        title="DeerFlow API Gateway",
+        description="""
+## DeerFlow API Gateway
+
+API Gateway for DeerFlow - A LangGraph-based AI agent backend with sandbox execution capabilities.
+
+### Features
+
+- **Models Management**: Query and retrieve available AI models
+- **MCP Configuration**: Manage Model Context Protocol (MCP) server configurations
+- **Memory Management**: Access and manage global memory data for personalized conversations
+- **Skills Management**: Query and manage skills and their enabled status
+- **Artifacts**: Access thread artifacts and generated files
+- **Health Monitoring**: System health check endpoints
+
+### Architecture
+
+LangGraph requests are handled by nginx reverse proxy.
+This gateway provides custom endpoints for models, MCP configuration, skills, and artifacts.
+        """,
+        version="0.1.0",
+        lifespan=lifespan,
+        **docs_kwargs,
+        openapi_tags=[
+            {
+                "name": "models",
+                "description": "Operations for querying available AI models and their configurations",
+            },
+            {
+                "name": "mcp",
+                "description": "Manage Model Context Protocol (MCP) server configurations",
+            },
+            {
+                "name": "memory",
+                "description": "Access and manage global memory data for personalized conversations",
+            },
+            {
+                "name": "skills",
+                "description": "Manage skills and their configurations",
+            },
+            {
+                "name": "artifacts",
+                "description": "Access and download thread artifacts and generated files",
+            },
+            {
+                "name": "uploads",
+                "description": "Upload and manage user files for threads",
+            },
+            {
+                "name": "threads",
+                "description": "Manage DeerFlow thread-local filesystem data",
+            },
+            {
+                "name": "agents",
+                "description": "Create and manage custom agents with per-agent config and prompts",
+            },
+            {
+                "name": "suggestions",
+                "description": "Generate follow-up question suggestions for conversations",
+            },
+            {
+                "name": "channels",
+                "description": "Manage IM channel integrations (Feishu, Slack, Telegram)",
+            },
+            {
+                "name": "assistants-compat",
+                "description": "LangGraph Platform-compatible assistants API (stub)",
+            },
+            {
+                "name": "runs",
+                "description": "LangGraph Platform-compatible runs lifecycle (create, stream, cancel)",
+            },
+            {
+                "name": "scheduled-tasks",
+                "description": "Create, manage, and execute user scheduled agent tasks",
+            },
+            {
+                "name": "health",
+                "description": "Health check and system status endpoints",
+            },
+        ],
+    )
+
+    # Auth: reject unauthenticated requests to non-public paths (fail-closed safety net)
+    app.add_middleware(AuthMiddleware)
+
+    # CSRF: Double Submit Cookie pattern for state-changing requests
+    app.add_middleware(CSRFMiddleware)
+
+    # CORS
+    if is_auth_disabled():
+        logger.warning(
+            "DEER_FLOW_AUTH_DISABLED is set — API authentication is bypassed. "
+            "Do not use this in production."
+        )
+
+    def _cors_allow_any_origin() -> bool:
+        """Mirror any browser Origin (works with credentials); cannot use literal '*'."""
+        v = os.environ.get("GATEWAY_CORS_ALLOW_ALL", "").strip().lower()
+        return v in ("1", "true", "yes", "on") or is_auth_disabled()
+
+    cors_origins_env = os.environ.get("GATEWAY_CORS_ORIGINS", "").strip()
+    cors_origins: list[str] = [o.strip() for o in cors_origins_env.split(",") if o.strip()] if cors_origins_env else []
+
+    # Headers the LangGraph SDK / browser clients need to read from cross-origin
+    # responses. Without exposing them, the SDK's `response.headers.get(...)` returns
+    # null on cross-origin streaming responses, breaking run-id extraction and reconnect.
+    cors_expose_headers = [
+        "Content-Disposition",
+        "Content-Location",
+        "Location",
+        "X-Run-Id",
+        "X-Thread-Id",
+    ]
+
+    if _cors_allow_any_origin():
+        logger.warning(
+            "Permissive CORS enabled — any Origin is echoed back (GATEWAY_CORS_ALLOW_ALL or "
+            "DEER_FLOW_AUTH_DISABLED). Do not expose publicly."
+        )
+        app.add_middleware(
+            CORSMiddleware,
+            allow_origins=[],
+            # fullmatch() on the Origin header; browsers send scheme://host[:port]
+            allow_origin_regex=r".+",
+            allow_credentials=True,
+            allow_methods=["*"],
+            allow_headers=["*"],
+            expose_headers=cors_expose_headers,
+        )
+    elif cors_origins:
+        if "*" in cors_origins:
+            logger.error(
+                "GATEWAY_CORS_ORIGINS contains '*' with allow_credentials=True — invalid. "
+                "Set GATEWAY_CORS_ALLOW_ALL=1 instead, or list explicit origins."
+            )
+            cors_origins = [o for o in cors_origins if o != "*"]
+        if cors_origins:
+            app.add_middleware(
+                CORSMiddleware,
+                allow_origins=cors_origins,
+                allow_credentials=True,
+                allow_methods=["*"],
+                allow_headers=["*"],
+                expose_headers=cors_expose_headers,
+            )
+    else:
+        # Safe-by-default fallback for local frontend development. Without any CORS
+        # middleware, browser preflight OPTIONS requests will hit routes directly and
+        # fail with 405, which blocks login and all JSON POST APIs.
+        dev_origins = [
+            "http://localhost:5173",
+            "http://127.0.0.1:5173",
+        ]
+        logger.warning(
+            "No CORS configuration found; enabling local dev origins only: %s. "
+            "Set GATEWAY_CORS_ORIGINS or GATEWAY_CORS_ALLOW_ALL for deployment.",
+            ", ".join(dev_origins),
+        )
+        app.add_middleware(
+            CORSMiddleware,
+            allow_origins=dev_origins,
+            allow_credentials=True,
+            allow_methods=["*"],
+            allow_headers=["*"],
+            expose_headers=cors_expose_headers,
+        )
+
+    # Include routers
+    # Models API is mounted at /api/models
+    app.include_router(models.router)
+
+    # MCP API is mounted at /api/mcp
+    app.include_router(mcp.router)
+
+    # Memory API is mounted at /api/memory
+    app.include_router(memory.router)
+
+    # Skills API is mounted at /api/skills
+    app.include_router(skills.router)
+
+    # Artifacts API is mounted at /api/threads/{thread_id}/artifacts
+    app.include_router(artifacts.router)
+
+    # Uploads API is mounted at /api/threads/{thread_id}/uploads
+    app.include_router(uploads.router)
+
+    # Thread cleanup API is mounted at /api/threads/{thread_id}
+    app.include_router(threads.router)
+
+    # Agents API is mounted at /api/agents
+    app.include_router(agents.router)
+
+    # Suggestions API is mounted at /api/threads/{thread_id}/suggestions
+    app.include_router(suggestions.router)
+
+    # Scheduled task API is mounted at /api/scheduled-tasks
+    app.include_router(scheduled_tasks.router)
+
+    # Channels API is mounted at /api/channels
+    app.include_router(channels.router)
+
+    # Assistants compatibility API (LangGraph Platform stub)
+    app.include_router(assistants_compat.router)
+
+    # Auth API is mounted at /api/v1/auth
+    app.include_router(auth.router)
+
+    # Feedback API is mounted at /api/threads/{thread_id}/runs/{run_id}/feedback
+    app.include_router(feedback.router)
+
+    # Thread Runs API (LangGraph Platform-compatible runs lifecycle)
+    app.include_router(thread_runs.router)
+
+    # Stateless Runs API (stream/wait without a pre-existing thread)
+    app.include_router(runs.router)
+
+    @app.get("/health", tags=["health"])
+    async def health_check() -> dict:
+        """Health check endpoint.
+
+        Returns:
+            Service health status information.
+        """
+        return {"status": "healthy", "service": "deer-flow-gateway"}
+
+    return app
+
+
+# Create app instance for uvicorn
+app = create_app()

offline-backend-20260512/backend/app/gateway/auth/__init__.py

@@ -0,0 +1,42 @@
+"""Authentication module for DeerFlow.
+
+This module provides:
+- JWT-based authentication
+- Provider Factory pattern for extensible auth methods
+- UserRepository interface for storage backends (SQLite)
+"""
+
+from app.gateway.auth.config import AuthConfig, get_auth_config, set_auth_config
+from app.gateway.auth.errors import AuthErrorCode, AuthErrorResponse, TokenError
+from app.gateway.auth.jwt import TokenPayload, create_access_token, decode_token
+from app.gateway.auth.local_provider import LocalAuthProvider
+from app.gateway.auth.models import User, UserResponse
+from app.gateway.auth.password import hash_password, verify_password
+from app.gateway.auth.providers import AuthProvider
+from app.gateway.auth.repositories.base import UserRepository
+
+__all__ = [
+    # Config
+    "AuthConfig",
+    "get_auth_config",
+    "set_auth_config",
+    # Errors
+    "AuthErrorCode",
+    "AuthErrorResponse",
+    "TokenError",
+    # JWT
+    "TokenPayload",
+    "create_access_token",
+    "decode_token",
+    # Password
+    "hash_password",
+    "verify_password",
+    # Models
+    "User",
+    "UserResponse",
+    # Providers
+    "AuthProvider",
+    "LocalAuthProvider",
+    # Repository
+    "UserRepository",
+]

offline-backend-20260512/backend/app/gateway/auth/config.py

@@ -0,0 +1,57 @@
+"""Authentication configuration for DeerFlow."""
+
+import logging
+import os
+import secrets
+
+from pydantic import BaseModel, Field
+
+logger = logging.getLogger(__name__)
+
+
+class AuthConfig(BaseModel):
+    """JWT and auth-related configuration. Parsed once at startup.
+
+    Note: the ``users`` table now lives in the shared persistence
+    database managed by ``deerflow.persistence.engine``. The old
+    ``users_db_path`` config key has been removed — user storage is
+    configured through ``config.database`` like every other table.
+    """
+
+    jwt_secret: str = Field(
+        ...,
+        description="Secret key for JWT signing. MUST be set via AUTH_JWT_SECRET.",
+    )
+    token_expiry_days: int = Field(default=7, ge=1, le=30)
+    oauth_github_client_id: str | None = Field(default=None)
+    oauth_github_client_secret: str | None = Field(default=None)
+
+
+_auth_config: AuthConfig | None = None
+
+
+def get_auth_config() -> AuthConfig:
+    """Get the global AuthConfig instance. Parses from env on first call."""
+    global _auth_config
+    if _auth_config is None:
+        from dotenv import load_dotenv
+
+        load_dotenv()
+        jwt_secret = os.environ.get("AUTH_JWT_SECRET")
+        if not jwt_secret:
+            jwt_secret = secrets.token_urlsafe(32)
+            os.environ["AUTH_JWT_SECRET"] = jwt_secret
+            logger.warning(
+                "⚠ AUTH_JWT_SECRET is not set — using an auto-generated ephemeral secret. "
+                "Sessions will be invalidated on restart. "
+                "For production, add AUTH_JWT_SECRET to your .env file: "
+                'python -c "import secrets; print(secrets.token_urlsafe(32))"'
+            )
+        _auth_config = AuthConfig(jwt_secret=jwt_secret)
+    return _auth_config
+
+
+def set_auth_config(config: AuthConfig) -> None:
+    """Set the global AuthConfig instance (for testing)."""
+    global _auth_config
+    _auth_config = config

offline-backend-20260512/backend/app/gateway/auth/credential_file.py

@@ -0,0 +1,48 @@
+"""Write initial admin credentials to a restricted file instead of logs.
+
+Logging secrets to stdout/stderr is a well-known CodeQL finding
+(py/clear-text-logging-sensitive-data) — in production those logs
+get collected into ELK/Splunk/etc and become a secret sprawl
+source. This helper writes the credential to a 0600 file that only
+the process user can read, and returns the path so the caller can
+log **the path** (not the password) for the operator to pick up.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from deerflow.config.paths import get_paths
+
+_CREDENTIAL_FILENAME = "admin_initial_credentials.txt"
+
+
+def write_initial_credentials(email: str, password: str, *, label: str = "initial") -> Path:
+    """Write the admin email + password to ``{base_dir}/admin_initial_credentials.txt``.
+
+    The file is created **atomically** with mode 0600 via ``os.open``
+    so the password is never world-readable, even for the single syscall
+    window between ``write_text`` and ``chmod``.
+
+    ``label`` distinguishes "initial" (fresh creation) from "reset"
+    (password reset) in the file header so an operator picking up the
+    file after a restart can tell which event produced it.
+
+    Returns the absolute :class:`Path` to the file.
+    """
+    target = get_paths().base_dir / _CREDENTIAL_FILENAME
+    target.parent.mkdir(parents=True, exist_ok=True)
+
+    content = (
+        f"# DeerFlow admin {label} credentials\n# This file is generated on first boot or password reset.\n# Change the password after login via Settings -> Account,\n# then delete this file.\n#\nemail: {email}\npassword: {password}\n"
+    )
+
+    # Atomic 0600 create-or-truncate. O_TRUNC (not O_EXCL) so the
+    # reset-password path can rewrite an existing file without a
+    # separate unlink-then-create dance.
+    fd = os.open(target, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w", encoding="utf-8") as fh:
+        fh.write(content)
+
+    return target.resolve()

offline-backend-20260512/backend/app/gateway/auth/disabled_mode.py

@@ -0,0 +1,75 @@
+"""Dev-only bypass when ``DEER_FLOW_AUTH_DISABLED`` is set.
+
+Never enable in production: all API and LangGraph routes run as an assumed user.
+"""
+
+from __future__ import annotations
+
+import os
+from datetime import UTC
+from uuid import UUID
+
+from sqlalchemy import select
+
+from app.gateway.auth.models import User
+from deerflow.persistence.engine import get_session_factory
+from deerflow.persistence.user.model import UserRow
+
+_FALLBACK_ADMIN_ID = UUID("00000000-0000-4000-8000-000000000001")
+# Must satisfy pydantic EmailStr (avoid reserved/special-use domains like .local).
+_FALLBACK_EMAIL = "anonymous@example.com"
+
+_cached_assumed_user: User | None = None
+
+
+def is_auth_disabled() -> bool:
+    """Return True when auth gate should be bypassed (development / local tooling)."""
+    return os.environ.get("DEER_FLOW_AUTH_DISABLED", "").strip().lower() in ("1", "true", "yes", "on")
+
+
+def _row_to_user(row: UserRow) -> User:
+    created = row.created_at
+    if created.tzinfo is None:
+        created = created.replace(tzinfo=UTC)
+    return User(
+        id=UUID(row.id),
+        email=row.email,
+        password_hash=row.password_hash,
+        system_role=row.system_role,  # type: ignore[arg-type]
+        created_at=created,
+        oauth_provider=row.oauth_provider,
+        oauth_id=row.oauth_id,
+        needs_setup=row.needs_setup,
+        token_version=row.token_version,
+    )
+
+
+async def get_assumed_user_for_disabled_auth() -> User:
+    """Resolve the user assumed for every request when auth is disabled.
+
+    Prefer the first admin row in the database so thread ownership matches an
+    existing account. If the DB is empty or unavailable, use a stable synthetic
+    admin (restart the gateway after creating a real admin to pick them up).
+    """
+    global _cached_assumed_user
+    if _cached_assumed_user is not None:
+        return _cached_assumed_user
+
+    sf = get_session_factory()
+    if sf is not None:
+        async with sf() as session:
+            stmt = select(UserRow).where(UserRow.system_role == "admin").limit(1)
+            row = (await session.execute(stmt)).scalar_one_or_none()
+        if row is not None:
+            _cached_assumed_user = _row_to_user(row)
+            return _cached_assumed_user
+
+    _cached_assumed_user = User(
+        id=_FALLBACK_ADMIN_ID,
+        email=_FALLBACK_EMAIL,
+        password_hash=None,
+        system_role="admin",
+        needs_setup=False,
+        token_version=0,
+    )
+    return _cached_assumed_user

offline-backend-20260512/backend/app/gateway/auth/errors.py

@@ -0,0 +1,45 @@
+"""Typed error definitions for auth module.
+
+AuthErrorCode: exhaustive enum of all auth failure conditions.
+TokenError: exhaustive enum of JWT decode failures.
+AuthErrorResponse: structured error payload for HTTP responses.
+"""
+
+from enum import StrEnum
+
+from pydantic import BaseModel
+
+
+class AuthErrorCode(StrEnum):
+    """Exhaustive list of auth error conditions."""
+
+    INVALID_CREDENTIALS = "invalid_credentials"
+    TOKEN_EXPIRED = "token_expired"
+    TOKEN_INVALID = "token_invalid"
+    USER_NOT_FOUND = "user_not_found"
+    EMAIL_ALREADY_EXISTS = "email_already_exists"
+    PROVIDER_NOT_FOUND = "provider_not_found"
+    NOT_AUTHENTICATED = "not_authenticated"
+    SYSTEM_ALREADY_INITIALIZED = "system_already_initialized"
+
+
+class TokenError(StrEnum):
+    """Exhaustive list of JWT decode failure reasons."""
+
+    EXPIRED = "expired"
+    INVALID_SIGNATURE = "invalid_signature"
+    MALFORMED = "malformed"
+
+
+class AuthErrorResponse(BaseModel):
+    """Structured error response — replaces bare `detail` strings."""
+
+    code: AuthErrorCode
+    message: str
+
+
+def token_error_to_code(err: TokenError) -> AuthErrorCode:
+    """Map TokenError to AuthErrorCode — single source of truth."""
+    if err == TokenError.EXPIRED:
+        return AuthErrorCode.TOKEN_EXPIRED
+    return AuthErrorCode.TOKEN_INVALID

offline-backend-20260512/backend/app/gateway/auth/jwt.py

@@ -0,0 +1,55 @@
+"""JWT token creation and verification."""
+
+from datetime import UTC, datetime, timedelta
+
+import jwt
+from pydantic import BaseModel
+
+from app.gateway.auth.config import get_auth_config
+from app.gateway.auth.errors import TokenError
+
+
+class TokenPayload(BaseModel):
+    """JWT token payload."""
+
+    sub: str  # user_id
+    exp: datetime
+    iat: datetime | None = None
+    ver: int = 0  # token_version — must match User.token_version
+
+
+def create_access_token(user_id: str, expires_delta: timedelta | None = None, token_version: int = 0) -> str:
+    """Create a JWT access token.
+
+    Args:
+        user_id: The user's UUID as string
+        expires_delta: Optional custom expiry, defaults to 7 days
+        token_version: User's current token_version for invalidation
+
+    Returns:
+        Encoded JWT string
+    """
+    config = get_auth_config()
+    expiry = expires_delta or timedelta(days=config.token_expiry_days)
+
+    now = datetime.now(UTC)
+    payload = {"sub": user_id, "exp": now + expiry, "iat": now, "ver": token_version}
+    return jwt.encode(payload, config.jwt_secret, algorithm="HS256")
+
+
+def decode_token(token: str) -> TokenPayload | TokenError:
+    """Decode and validate a JWT token.
+
+    Returns:
+        TokenPayload if valid, or a specific TokenError variant.
+    """
+    config = get_auth_config()
+    try:
+        payload = jwt.decode(token, config.jwt_secret, algorithms=["HS256"])
+        return TokenPayload(**payload)
+    except jwt.ExpiredSignatureError:
+        return TokenError.EXPIRED
+    except jwt.InvalidSignatureError:
+        return TokenError.INVALID_SIGNATURE
+    except jwt.PyJWTError:
+        return TokenError.MALFORMED

offline-backend-20260512/backend/app/gateway/auth/local_provider.py

@@ -0,0 +1,104 @@
+"""Local email/password authentication provider."""
+
+import logging
+
+from app.gateway.auth.models import User
+from app.gateway.auth.password import hash_password_async, needs_rehash, verify_password_async
+from app.gateway.auth.providers import AuthProvider
+from app.gateway.auth.repositories.base import UserRepository
+
+logger = logging.getLogger(__name__)
+
+
+class LocalAuthProvider(AuthProvider):
+    """Email/password authentication provider using local database."""
+
+    def __init__(self, repository: UserRepository):
+        """Initialize with a UserRepository.
+
+        Args:
+            repository: UserRepository implementation (SQLite)
+        """
+        self._repo = repository
+
+    async def authenticate(self, credentials: dict) -> User | None:
+        """Authenticate with email and password.
+
+        Args:
+            credentials: dict with 'email' and 'password' keys
+
+        Returns:
+            User if authentication succeeds, None otherwise
+        """
+        email = credentials.get("email")
+        password = credentials.get("password")
+
+        if not email or not password:
+            return None
+
+        user = await self._repo.get_user_by_email(email)
+        if user is None:
+            return None
+
+        if user.password_hash is None:
+            # OAuth user without local password
+            return None
+
+        if not await verify_password_async(password, user.password_hash):
+            return None
+
+        if needs_rehash(user.password_hash):
+            try:
+                user.password_hash = await hash_password_async(password)
+                await self._repo.update_user(user)
+            except Exception:
+                # Rehash is an opportunistic upgrade; a transient DB error must not
+                # prevent an otherwise-valid login from succeeding.
+                logger.warning("Failed to rehash password for user %s; login will still succeed", user.email, exc_info=True)
+
+        return user
+
+    async def get_user(self, user_id: str) -> User | None:
+        """Get user by ID."""
+        return await self._repo.get_user_by_id(user_id)
+
+    async def create_user(self, email: str, password: str | None = None, system_role: str = "user", needs_setup: bool = False) -> User:
+        """Create a new local user.
+
+        Args:
+            email: User email address
+            password: Plain text password (will be hashed)
+            system_role: Role to assign ("admin" or "user")
+            needs_setup: If True, user must complete setup on first login
+
+        Returns:
+            Created User instance
+        """
+        password_hash = await hash_password_async(password) if password else None
+        user = User(
+            email=email,
+            password_hash=password_hash,
+            system_role=system_role,
+            needs_setup=needs_setup,
+        )
+        return await self._repo.create_user(user)
+
+    async def get_user_by_oauth(self, provider: str, oauth_id: str) -> User | None:
+        """Get user by OAuth provider and ID."""
+        return await self._repo.get_user_by_oauth(provider, oauth_id)
+
+    async def count_users(self) -> int:
+        """Return total number of registered users."""
+        return await self._repo.count_users()
+
+    async def count_admin_users(self) -> int:
+        """Return number of admin users."""
+        return await self._repo.count_admin_users()
+
+    async def update_user(self, user: User) -> User:
+        """Update an existing user."""
+        return await self._repo.update_user(user)
+
+    async def get_user_by_email(self, email: str) -> User | None:
+        """Get user by email."""
+        return await self._repo.get_user_by_email(email)

offline-backend-20260512/backend/app/gateway/auth/models.py

@@ -0,0 +1,41 @@
+"""User Pydantic models for authentication."""
+
+from datetime import UTC, datetime
+from typing import Literal
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, ConfigDict, EmailStr, Field
+
+
+def _utc_now() -> datetime:
+    """Return current UTC time (timezone-aware)."""
+    return datetime.now(UTC)
+
+
+class User(BaseModel):
+    """Internal user representation."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: UUID = Field(default_factory=uuid4, description="Primary key")
+    email: EmailStr = Field(..., description="Unique email address")
+    password_hash: str | None = Field(None, description="bcrypt hash, nullable for OAuth users")
+    system_role: Literal["admin", "user"] = Field(default="user")
+    created_at: datetime = Field(default_factory=_utc_now)
+
+    # OAuth linkage (optional)
+    oauth_provider: str | None = Field(None, description="e.g. 'github', 'google'")
+    oauth_id: str | None = Field(None, description="User ID from OAuth provider")
+
+    # Auth lifecycle
+    needs_setup: bool = Field(default=False, description="True for auto-created admin until setup completes")
+    token_version: int = Field(default=0, description="Incremented on password change to invalidate old JWTs")
+
+
+class UserResponse(BaseModel):
+    """Response model for user info endpoint."""
+
+    id: str
+    email: str
+    system_role: Literal["admin", "user"]
+    needs_setup: bool = False

offline-backend-20260512/backend/app/gateway/auth/password.py

@@ -0,0 +1,81 @@
+"""Password hashing utilities with versioned hash format.
+
+Hash format: ``$dfv<N>$<bcrypt_hash>`` where ``<N>`` is the version.
+
+- **v1** (legacy): ``bcrypt(password)`` — plain bcrypt, susceptible to
+  72-byte silent truncation.
+- **v2** (current): ``bcrypt(b64(sha256(password)))`` — SHA-256 pre-hash
+  avoids the 72-byte truncation limit so the full password contributes
+  to the hash.
+
+Verification auto-detects the version and falls back to v1 for hashes
+without a prefix, so existing deployments upgrade transparently on next
+login.
+"""
+
+import asyncio
+import base64
+import hashlib
+
+import bcrypt
+
+_CURRENT_VERSION = 2
+_PREFIX_V2 = "$dfv2$"
+_PREFIX_V1 = "$dfv1$"
+
+
+def _pre_hash_v2(password: str) -> bytes:
+    """SHA-256 pre-hash to bypass bcrypt's 72-byte limit."""
+    return base64.b64encode(hashlib.sha256(password.encode("utf-8")).digest())
+
+
+def hash_password(password: str) -> str:
+    """Hash a password (current version: v2 — SHA-256 + bcrypt)."""
+    raw = bcrypt.hashpw(_pre_hash_v2(password), bcrypt.gensalt()).decode("utf-8")
+    return f"{_PREFIX_V2}{raw}"
+
+
+def verify_password(plain_password: str, hashed_password: str) -> bool:
+    """Verify a password, auto-detecting the hash version.
+
+    Accepts v2 (``$dfv2$…``), v1 (``$dfv1$…``), and bare bcrypt hashes
+    (treated as v1 for backward compatibility with pre-versioning data).
+    """
+    try:
+        if hashed_password.startswith(_PREFIX_V2):
+            bcrypt_hash = hashed_password[len(_PREFIX_V2) :]
+            return bcrypt.checkpw(_pre_hash_v2(plain_password), bcrypt_hash.encode("utf-8"))
+
+        if hashed_password.startswith(_PREFIX_V1):
+            bcrypt_hash = hashed_password[len(_PREFIX_V1) :]
+        else:
+            bcrypt_hash = hashed_password
+
+        return bcrypt.checkpw(plain_password.encode("utf-8"), bcrypt_hash.encode("utf-8"))
+    except ValueError:
+        # bcrypt raises ValueError for malformed or corrupt hashes (e.g., invalid salt).
+        # Fail closed rather than crashing the request.
+        return False
+
+
+def needs_rehash(hashed_password: str) -> bool:
+    """Return True if the hash uses an older version and should be rehashed."""
+    return not hashed_password.startswith(_PREFIX_V2)
+
+
+async def hash_password_async(password: str) -> str:
+    """Hash a password using bcrypt (non-blocking).
+
+    Wraps the blocking bcrypt operation in a thread pool to avoid
+    blocking the event loop during password hashing.
+    """
+    return await asyncio.to_thread(hash_password, password)
+
+
+async def verify_password_async(plain_password: str, hashed_password: str) -> bool:
+    """Verify a password against its hash (non-blocking).
+
+    Wraps the blocking bcrypt operation in a thread pool to avoid
+    blocking the event loop during password verification.
+    """
+    return await asyncio.to_thread(verify_password, plain_password, hashed_password)

offline-backend-20260512/backend/app/gateway/auth/providers.py

@@ -0,0 +1,24 @@
+"""Auth provider abstraction."""
+
+from abc import ABC, abstractmethod
+
+
+class AuthProvider(ABC):
+    """Abstract base class for authentication providers."""
+
+    @abstractmethod
+    async def authenticate(self, credentials: dict) -> "User | None":
+        """Authenticate user with given credentials.
+
+        Returns User if authentication succeeds, None otherwise.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    async def get_user(self, user_id: str) -> "User | None":
+        """Retrieve user by ID."""
+        raise NotImplementedError
+
+
+# Import User at runtime to avoid circular imports
+from app.gateway.auth.models import User  # noqa: E402

offline-backend-20260512/backend/app/gateway/auth/repositories/base.py

@@ -0,0 +1,102 @@
+"""User repository interface for abstracting database operations."""
+
+from abc import ABC, abstractmethod
+
+from app.gateway.auth.models import User
+
+
+class UserNotFoundError(LookupError):
+    """Raised when a user repository operation targets a non-existent row.
+
+    Subclass of :class:`LookupError` so callers that already catch
+    ``LookupError`` for "missing entity" can keep working unchanged,
+    while specific call sites can pin to this class to distinguish
+    "concurrent delete during update" from other lookups.
+    """
+
+
+class UserRepository(ABC):
+    """Abstract interface for user data storage.
+
+    Implement this interface to support different storage backends
+    (SQLite)
+    """
+
+    @abstractmethod
+    async def create_user(self, user: User) -> User:
+        """Create a new user.
+
+        Args:
+            user: User object to create
+
+        Returns:
+            Created User with ID assigned
+
+        Raises:
+            ValueError: If email already exists
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    async def get_user_by_id(self, user_id: str) -> User | None:
+        """Get user by ID.
+
+        Args:
+            user_id: User UUID as string
+
+        Returns:
+            User if found, None otherwise
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    async def get_user_by_email(self, email: str) -> User | None:
+        """Get user by email.
+
+        Args:
+            email: User email address
+
+        Returns:
+            User if found, None otherwise
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    async def update_user(self, user: User) -> User:
+        """Update an existing user.
+
+        Args:
+            user: User object with updated fields
+
+        Returns:
+            Updated User
+
+        Raises:
+            UserNotFoundError: If no row exists for ``user.id``. This is
+                a hard failure (not a no-op) so callers cannot mistake a
+                concurrent-delete race for a successful update.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    async def count_users(self) -> int:
+        """Return total number of registered users."""
+        raise NotImplementedError
+
+    @abstractmethod
+    async def count_admin_users(self) -> int:
+        """Return number of users with system_role == 'admin'."""
+        raise NotImplementedError
+
+    @abstractmethod
+    async def get_user_by_oauth(self, provider: str, oauth_id: str) -> User | None:
+        """Get user by OAuth provider and ID.
+
+        Args:
+            provider: OAuth provider name (e.g. 'github', 'google')
+            oauth_id: User ID from the OAuth provider
+
+        Returns:
+            User if found, None otherwise
+        """
+        raise NotImplementedError

offline-backend-20260512/backend/app/gateway/auth/repositories/sqlite.py

@@ -0,0 +1,127 @@
+"""SQLAlchemy-backed UserRepository implementation.
+
+Uses the shared async session factory from
+``deerflow.persistence.engine`` — the ``users`` table lives in the
+same database as ``threads_meta``, ``runs``, ``run_events``, and
+``feedback``.
+
+Constructor takes the session factory directly (same pattern as the
+other four repositories in ``deerflow.persistence.*``). Callers
+construct this after ``init_engine_from_config()`` has run.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC
+from uuid import UUID
+
+from sqlalchemy import func, select
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from app.gateway.auth.models import User
+from app.gateway.auth.repositories.base import UserNotFoundError, UserRepository
+from deerflow.persistence.user.model import UserRow
+
+
+class SQLiteUserRepository(UserRepository):
+    """Async user repository backed by the shared SQLAlchemy engine."""
+
+    def __init__(self, session_factory: async_sessionmaker[AsyncSession]) -> None:
+        self._sf = session_factory
+
+    # ── Converters ────────────────────────────────────────────────────
+
+    @staticmethod
+    def _row_to_user(row: UserRow) -> User:
+        return User(
+            id=UUID(row.id),
+            email=row.email,
+            password_hash=row.password_hash,
+            system_role=row.system_role,  # type: ignore[arg-type]
+            # SQLite loses tzinfo on read; reattach UTC so downstream
+            # code can compare timestamps reliably.
+            created_at=row.created_at if row.created_at.tzinfo else row.created_at.replace(tzinfo=UTC),
+            oauth_provider=row.oauth_provider,
+            oauth_id=row.oauth_id,
+            needs_setup=row.needs_setup,
+            token_version=row.token_version,
+        )
+
+    @staticmethod
+    def _user_to_row(user: User) -> UserRow:
+        return UserRow(
+            id=str(user.id),
+            email=user.email,
+            password_hash=user.password_hash,
+            system_role=user.system_role,
+            created_at=user.created_at,
+            oauth_provider=user.oauth_provider,
+            oauth_id=user.oauth_id,
+            needs_setup=user.needs_setup,
+            token_version=user.token_version,
+        )
+
+    # ── CRUD ──────────────────────────────────────────────────────────
+
+    async def create_user(self, user: User) -> User:
+        """Insert a new user. Raises ``ValueError`` on duplicate email."""
+        row = self._user_to_row(user)
+        async with self._sf() as session:
+            session.add(row)
+            try:
+                await session.commit()
+            except IntegrityError as exc:
+                await session.rollback()
+                raise ValueError(f"Email already registered: {user.email}") from exc
+        return user
+
+    async def get_user_by_id(self, user_id: str) -> User | None:
+        async with self._sf() as session:
+            row = await session.get(UserRow, user_id)
+            return self._row_to_user(row) if row is not None else None
+
+    async def get_user_by_email(self, email: str) -> User | None:
+        stmt = select(UserRow).where(UserRow.email == email)
+        async with self._sf() as session:
+            result = await session.execute(stmt)
+            row = result.scalar_one_or_none()
+            return self._row_to_user(row) if row is not None else None
+
+    async def update_user(self, user: User) -> User:
+        async with self._sf() as session:
+            row = await session.get(UserRow, str(user.id))
+            if row is None:
+                # Hard fail on concurrent delete: callers (reset_admin,
+                # password change handlers, _ensure_admin_user) all
+                # fetched the user just before this call, so a missing
+                # row here means the row vanished underneath us. Silent
+                # success would let the caller log "password reset" for
+                # a row that no longer exists.
+                raise UserNotFoundError(f"User {user.id} no longer exists")
+            row.email = user.email
+            row.password_hash = user.password_hash
+            row.system_role = user.system_role
+            row.oauth_provider = user.oauth_provider
+            row.oauth_id = user.oauth_id
+            row.needs_setup = user.needs_setup
+            row.token_version = user.token_version
+            await session.commit()
+        return user
+
+    async def count_users(self) -> int:
+        stmt = select(func.count()).select_from(UserRow)
+        async with self._sf() as session:
+            return await session.scalar(stmt) or 0
+
+    async def count_admin_users(self) -> int:
+        stmt = select(func.count()).select_from(UserRow).where(UserRow.system_role == "admin")
+        async with self._sf() as session:
+            return await session.scalar(stmt) or 0
+
+    async def get_user_by_oauth(self, provider: str, oauth_id: str) -> User | None:
+        stmt = select(UserRow).where(UserRow.oauth_provider == provider, UserRow.oauth_id == oauth_id)
+        async with self._sf() as session:
+            result = await session.execute(stmt)
+            row = result.scalar_one_or_none()
+            return self._row_to_user(row) if row is not None else None

offline-backend-20260512/backend/app/gateway/auth/reset_admin.py

@@ -0,0 +1,91 @@
+"""CLI tool to reset an admin password.
+
+Usage:
+    python -m app.gateway.auth.reset_admin
+    python -m app.gateway.auth.reset_admin --email admin@example.com
+
+Writes the new password to ``.deer-flow/admin_initial_credentials.txt``
+(mode 0600) instead of printing it, so CI / log aggregators never see
+the cleartext secret.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import secrets
+import sys
+
+from sqlalchemy import select
+
+from app.gateway.auth.credential_file import write_initial_credentials
+from app.gateway.auth.password import hash_password
+from app.gateway.auth.repositories.sqlite import SQLiteUserRepository
+from deerflow.persistence.user.model import UserRow
+
+
+async def _run(email: str | None) -> int:
+    from deerflow.config import get_app_config
+    from deerflow.persistence.engine import (
+        close_engine,
+        get_session_factory,
+        init_engine_from_config,
+    )
+
+    config = get_app_config()
+    await init_engine_from_config(config.database)
+    try:
+        sf = get_session_factory()
+        if sf is None:
+            print("Error: persistence engine not available (check config.database).", file=sys.stderr)
+            return 1
+
+        repo = SQLiteUserRepository(sf)
+
+        if email:
+            user = await repo.get_user_by_email(email)
+        else:
+            # Find first admin via direct SELECT — repository does not
+            # expose a "first admin" helper and we do not want to add
+            # one just for this CLI.
+            async with sf() as session:
+                stmt = select(UserRow).where(UserRow.system_role == "admin").limit(1)
+                row = (await session.execute(stmt)).scalar_one_or_none()
+            if row is None:
+                user = None
+            else:
+                user = await repo.get_user_by_id(row.id)
+
+        if user is None:
+            if email:
+                print(f"Error: user '{email}' not found.", file=sys.stderr)
+            else:
+                print("Error: no admin user found.", file=sys.stderr)
+            return 1
+
+        new_password = secrets.token_urlsafe(16)
+        user.password_hash = hash_password(new_password)
+        user.token_version += 1
+        user.needs_setup = True
+        await repo.update_user(user)
+
+        cred_path = write_initial_credentials(user.email, new_password, label="reset")
+        print(f"Password reset for: {user.email}")
+        print(f"Credentials written to: {cred_path} (mode 0600)")
+        print("Next login will require setup (new email + password).")
+        return 0
+    finally:
+        await close_engine()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Reset admin password")
+    parser.add_argument("--email", help="Admin email (default: first admin found)")
+    args = parser.parse_args()
+
+    exit_code = asyncio.run(_run(args.email))
+    sys.exit(exit_code)
+
+
+if __name__ == "__main__":
+    main()

offline-backend-20260512/backend/app/gateway/auth_middleware.py

@@ -0,0 +1,140 @@
+"""Global authentication middleware — fail-closed safety net.
+
+Rejects unauthenticated requests to non-public paths with 401. When a
+request passes the cookie check, resolves the JWT payload to a real
+``User`` object and stamps it into both ``request.state.user`` and the
+``deerflow.runtime.user_context`` contextvar so that repository-layer
+owner filtering works automatically via the sentinel pattern.
+
+Fine-grained permission checks remain in authz.py decorators.
+"""
+
+from collections.abc import Callable
+
+from fastapi import HTTPException, Request, Response
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.responses import JSONResponse
+from starlette.types import ASGIApp
+
+from app.gateway.auth.disabled_mode import get_assumed_user_for_disabled_auth, is_auth_disabled
+from app.gateway.auth.errors import AuthErrorCode, AuthErrorResponse
+from app.gateway.authz import _ALL_PERMISSIONS, AuthContext
+from app.gateway.internal_auth import INTERNAL_AUTH_HEADER_NAME, get_internal_user, is_valid_internal_auth_token
+from deerflow.runtime.user_context import reset_current_user, set_current_user
+
+# Paths that never require authentication.
+_PUBLIC_PATH_PREFIXES: tuple[str, ...] = (
+    "/health",
+    "/docs",
+    "/redoc",
+    "/openapi.json",
+)
+
+# Exact auth paths that are public (login/register/status check).
+# /api/v1/auth/me, /api/v1/auth/change-password etc. are NOT public.
+_PUBLIC_EXACT_PATHS: frozenset[str] = frozenset(
+    {
+        "/api/v1/auth/login/local",
+        "/api/v1/auth/login/username",
+        "/api/v1/auth/register",
+        "/api/v1/auth/logout",
+        "/api/v1/auth/setup-status",
+        "/api/v1/auth/initialize",
+    }
+)
+
+
+def _is_public(path: str) -> bool:
+    stripped = path.rstrip("/")
+    if stripped in _PUBLIC_EXACT_PATHS:
+        return True
+    return any(path.startswith(prefix) for prefix in _PUBLIC_PATH_PREFIXES)
+
+
+class AuthMiddleware(BaseHTTPMiddleware):
+    """Strict auth gate: reject requests without a valid session.
+
+    Two-stage check for non-public paths:
+
+    1. Cookie presence — return 401 NOT_AUTHENTICATED if missing
+    2. JWT validation via ``get_optional_user_from_request`` — return 401
+       TOKEN_INVALID if the token is absent, malformed, expired, or the
+       signed user does not exist / is stale
+
+    On success, stamps ``request.state.user`` and the
+    ``deerflow.runtime.user_context`` contextvar so that repository-layer
+    owner filters work downstream without every route needing a
+    ``@require_auth`` decorator. Routes that need per-resource
+    authorization (e.g. "user A cannot read user B's thread by guessing
+    the URL") should additionally use ``@require_permission(...,
+    owner_check=True)`` for explicit enforcement — but authentication
+    itself is fully handled here.
+    """
+
+    def __init__(self, app: ASGIApp) -> None:
+        super().__init__(app)
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        if _is_public(request.url.path):
+            return await call_next(request)
+
+        if is_auth_disabled():
+            user = await get_assumed_user_for_disabled_auth()
+            request.state.user = user
+            request.state.auth = AuthContext(user=user, permissions=_ALL_PERMISSIONS)
+            token = set_current_user(user)
+            try:
+                return await call_next(request)
+            finally:
+                reset_current_user(token)
+
+        internal_user = None
+        if is_valid_internal_auth_token(request.headers.get(INTERNAL_AUTH_HEADER_NAME)):
+            internal_user = get_internal_user()
+
+        # Non-public path: require session cookie
+        from app.gateway.deps import get_request_access_token
+
+        if internal_user is None and not get_request_access_token(request):
+            return JSONResponse(
+                status_code=401,
+                content={
+                    "detail": AuthErrorResponse(
+                        code=AuthErrorCode.NOT_AUTHENTICATED,
+                        message="Authentication required",
+                    ).model_dump()
+                },
+            )
+
+        # Strict JWT validation: reject junk/expired tokens with 401
+        # right here instead of silently passing through. This closes
+        # the "junk cookie bypass" gap (AUTH_TEST_PLAN test 7.5.8):
+        # without this, non-isolation routes like /api/models would
+        # accept any cookie-shaped string as authentication.
+        #
+        # We call the *strict* resolver so that fine-grained error
+        # codes (token_expired, token_invalid, user_not_found, …)
+        # propagate from AuthErrorCode, not get flattened into one
+        # generic code. BaseHTTPMiddleware doesn't let HTTPException
+        # bubble up, so we catch and render it as JSONResponse here.
+        from app.gateway.deps import get_current_user_from_request
+
+        if internal_user is not None:
+            user = internal_user
+        else:
+            try:
+                user = await get_current_user_from_request(request)
+            except HTTPException as exc:
+                return JSONResponse(status_code=exc.status_code, content={"detail": exc.detail})
+
+        # Stamp both request.state.user (for the contextvar pattern)
+        # and request.state.auth (so @require_permission's "auth is
+        # None" branch short-circuits instead of running the entire
+        # JWT-decode + DB-lookup pipeline a second time per request).
+        request.state.user = user
+        request.state.auth = AuthContext(user=user, permissions=_ALL_PERMISSIONS)
+        token = set_current_user(user)
+        try:
+            return await call_next(request)
+        finally:
+            reset_current_user(token)

offline-backend-20260512/backend/app/gateway/authz.py

@@ -0,0 +1,307 @@
+"""Authorization decorators and context for DeerFlow.
+
+Inspired by LangGraph Auth system: https://github.com/langchain-ai/langgraph/blob/main/libs/sdk-py/langgraph_sdk/auth/__init__.py
+
+**Usage:**
+
+1. Use ``@require_auth`` on routes that need authentication
+2. Use ``@require_permission("resource", "action", filter_key=...)`` for permission checks
+3. The decorator chain processes from bottom to top
+
+**Example:**
+
+    @router.get("/{thread_id}")
+    @require_auth
+    @require_permission("threads", "read", owner_check=True)
+    async def get_thread(thread_id: str, request: Request):
+        # User is authenticated and has threads:read permission
+        ...
+
+**Permission Model:**
+
+- threads:read   - View thread
+- threads:write  - Create/update thread
+- threads:delete - Delete thread
+- runs:create   - Run agent
+- runs:read     - View run
+- runs:cancel   - Cancel run
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+
+from app.gateway.auth.disabled_mode import get_assumed_user_for_disabled_auth, is_auth_disabled
+from collections.abc import Callable
+from types import SimpleNamespace
+from typing import TYPE_CHECKING, Any, ParamSpec, TypeVar
+
+from fastapi import HTTPException, Request
+
+if TYPE_CHECKING:
+    from app.gateway.auth.models import User
+
+P = ParamSpec("P")
+T = TypeVar("T")
+
+
+# Permission constants
+class Permissions:
+    """Permission constants for resource:action format."""
+
+    # Threads
+    THREADS_READ = "threads:read"
+    THREADS_WRITE = "threads:write"
+    THREADS_DELETE = "threads:delete"
+
+    # Runs
+    RUNS_CREATE = "runs:create"
+    RUNS_READ = "runs:read"
+    RUNS_CANCEL = "runs:cancel"
+
+
+class AuthContext:
+    """Authentication context for the current request.
+
+    Stored in request.state.auth after require_auth decoration.
+
+    Attributes:
+        user: The authenticated user, or None if anonymous
+        permissions: List of permission strings (e.g., "threads:read")
+    """
+
+    __slots__ = ("user", "permissions")
+
+    def __init__(self, user: User | None = None, permissions: list[str] | None = None):
+        self.user = user
+        self.permissions = permissions or []
+
+    @property
+    def is_authenticated(self) -> bool:
+        """Check if user is authenticated."""
+        return self.user is not None
+
+    def has_permission(self, resource: str, action: str) -> bool:
+        """Check if context has permission for resource:action.
+
+        Args:
+            resource: Resource name (e.g., "threads")
+            action: Action name (e.g., "read")
+
+        Returns:
+            True if user has permission
+        """
+        permission = f"{resource}:{action}"
+        return permission in self.permissions
+
+    def require_user(self) -> User:
+        """Get user or raise 401.
+
+        Raises:
+            HTTPException 401 if not authenticated
+        """
+        if not self.user:
+            raise HTTPException(status_code=401, detail="Authentication required")
+        return self.user
+
+
+def get_auth_context(request: Request) -> AuthContext | None:
+    """Get AuthContext from request state."""
+    return getattr(request.state, "auth", None)
+
+
+_ALL_PERMISSIONS: list[str] = [
+    Permissions.THREADS_READ,
+    Permissions.THREADS_WRITE,
+    Permissions.THREADS_DELETE,
+    Permissions.RUNS_CREATE,
+    Permissions.RUNS_READ,
+    Permissions.RUNS_CANCEL,
+]
+
+
+def _make_test_request_stub() -> Any:
+    """Create a minimal request-like object for direct unit calls.
+
+    Used when decorated route handlers are invoked without FastAPI's
+    request injection. Includes fields accessed by auth helpers.
+    """
+    return SimpleNamespace(state=SimpleNamespace(), cookies={}, _deerflow_test_bypass_auth=True)
+
+
+async def _authenticate(request: Request) -> AuthContext:
+    """Authenticate request and return AuthContext.
+
+    Delegates to deps.get_optional_user_from_request() for the JWT→User pipeline.
+    Returns AuthContext with user=None for anonymous requests.
+    """
+    if is_auth_disabled():
+        user = await get_assumed_user_for_disabled_auth()
+        return AuthContext(user=user, permissions=_ALL_PERMISSIONS)
+
+    from app.gateway.deps import get_optional_user_from_request
+
+    user = await get_optional_user_from_request(request)
+    if user is None:
+        return AuthContext(user=None, permissions=[])
+
+    # In future, permissions could be stored in user record
+    return AuthContext(user=user, permissions=_ALL_PERMISSIONS)
+
+
+def require_auth[**P, T](func: Callable[P, T]) -> Callable[P, T]:
+    """Decorator that authenticates the request and enforces authentication.
+
+    Independently raises HTTP 401 for unauthenticated requests, regardless of
+    whether ``AuthMiddleware`` is present in the ASGI stack. Sets the resolved
+    ``AuthContext`` on ``request.state.auth`` for downstream handlers.
+
+    Must be placed ABOVE other decorators (executes after them).
+
+    Usage:
+        @router.get("/{thread_id}")
+        @require_auth  # Bottom decorator (executes first after permission check)
+        @require_permission("threads", "read")
+        async def get_thread(thread_id: str, request: Request):
+            auth: AuthContext = request.state.auth
+            ...
+
+    Raises:
+        HTTPException: 401 if the request is unauthenticated.
+        ValueError: If 'request' parameter is missing.
+    """
+
+    @functools.wraps(func)
+    async def wrapper(*args: Any, **kwargs: Any) -> Any:
+        request = kwargs.get("request")
+        if request is None:
+            # Unit tests may call decorated handlers directly without a
+            # FastAPI Request object. Inject a minimal request stub when
+            # the wrapped function declares `request`.
+            if "request" in inspect.signature(func).parameters:
+                kwargs["request"] = _make_test_request_stub()
+            else:
+                raise ValueError("require_auth decorator requires 'request' parameter")
+            request = kwargs["request"]
+
+        if getattr(request, "_deerflow_test_bypass_auth", False):
+            return await func(*args, **kwargs)
+
+        # Authenticate and set context
+        auth_context = await _authenticate(request)
+        request.state.auth = auth_context
+
+        if not auth_context.is_authenticated:
+            raise HTTPException(status_code=401, detail="Authentication required")
+
+        return await func(*args, **kwargs)
+
+    return wrapper
+
+
+def require_permission(
+    resource: str,
+    action: str,
+    owner_check: bool = False,
+    require_existing: bool = False,
+) -> Callable[[Callable[P, T]], Callable[P, T]]:
+    """Decorator that checks permission for resource:action.
+
+    Must be used AFTER @require_auth.
+
+    Args:
+        resource: Resource name (e.g., "threads", "runs")
+        action: Action name (e.g., "read", "write", "delete")
+        owner_check: If True, validates that the current user owns the resource.
+                     Requires 'thread_id' path parameter and performs ownership check.
+        require_existing: Only meaningful with ``owner_check=True``. If True, a
+                          missing ``threads_meta`` row counts as a denial (404)
+                          instead of "untracked legacy thread, allow". Use on
+                          **destructive / mutating** routes (DELETE, PATCH,
+                          state-update) so a deleted thread can't be re-targeted
+                          by another user via the missing-row code path.
+
+    Usage:
+        # Read-style: legacy untracked threads are allowed
+        @require_permission("threads", "read", owner_check=True)
+        async def get_thread(thread_id: str, request: Request):
+            ...
+
+        # Destructive: thread row MUST exist and be owned by caller
+        @require_permission("threads", "delete", owner_check=True, require_existing=True)
+        async def delete_thread(thread_id: str, request: Request):
+            ...
+
+    Raises:
+        HTTPException 401: If authentication required but user is anonymous
+        HTTPException 403: If user lacks permission
+        HTTPException 404: If owner_check=True but user doesn't own the thread
+        ValueError: If owner_check=True but 'thread_id' parameter is missing
+    """
+
+    def decorator(func: Callable[P, T]) -> Callable[P, T]:
+        @functools.wraps(func)
+        async def wrapper(*args: Any, **kwargs: Any) -> Any:
+            request = kwargs.get("request")
+            if request is None:
+                # Unit tests may call decorated route handlers directly without
+                # constructing a FastAPI Request object. Inject a minimal stub
+                # when the wrapped function declares `request`.
+                if "request" in inspect.signature(func).parameters:
+                    kwargs["request"] = _make_test_request_stub()
+                else:
+                    return await func(*args, **kwargs)
+                request = kwargs["request"]
+
+            if getattr(request, "_deerflow_test_bypass_auth", False):
+                return await func(*args, **kwargs)
+
+            auth: AuthContext = getattr(request.state, "auth", None)
+            if auth is None:
+                auth = await _authenticate(request)
+                request.state.auth = auth
+
+            if not auth.is_authenticated:
+                raise HTTPException(status_code=401, detail="Authentication required")
+
+            # Check permission
+            if not auth.has_permission(resource, action):
+                raise HTTPException(
+                    status_code=403,
+                    detail=f"Permission denied: {resource}:{action}",
+                )
+
+            # Owner check for thread-specific resources.
+            #
+            # 2.0-rc moved thread metadata into the SQL persistence layer
+            # (``threads_meta`` table). We verify ownership via
+            # ``ThreadMetaStore.check_access``: it returns True for
+            # missing rows (untracked legacy thread) and for rows whose
+            # ``user_id`` is NULL (shared / pre-auth data), so this is
+            # strict-deny rather than strict-allow — only an *existing*
+            # row with a *different* user_id triggers 404.
+            if owner_check:
+                thread_id = kwargs.get("thread_id")
+                if thread_id is None:
+                    raise ValueError("require_permission with owner_check=True requires 'thread_id' parameter")
+
+                from app.gateway.deps import get_thread_store
+
+                thread_store = get_thread_store(request)
+                allowed = await thread_store.check_access(
+                    thread_id,
+                    str(auth.user.id),
+                    require_existing=require_existing,
+                )
+                if not allowed:
+                    raise HTTPException(
+                        status_code=404,
+                        detail=f"Thread {thread_id} not found",
+                    )
+
+            return await func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

offline-backend-20260512/backend/app/gateway/config.py

@@ -0,0 +1,29 @@
+import os
+
+from pydantic import BaseModel, Field
+
+
+class GatewayConfig(BaseModel):
+    """Configuration for the API Gateway."""
+
+    host: str = Field(default="0.0.0.0", description="Host to bind the gateway server")
+    port: int = Field(default=8001, description="Port to bind the gateway server")
+    cors_origins: list[str] = Field(default_factory=lambda: ["http://localhost:3000"], description="Allowed CORS origins")
+    enable_docs: bool = Field(default=True, description="Enable Swagger/ReDoc/OpenAPI endpoints")
+
+
+_gateway_config: GatewayConfig | None = None
+
+
+def get_gateway_config() -> GatewayConfig:
+    """Get gateway config, loading from environment if available."""
+    global _gateway_config
+    if _gateway_config is None:
+        cors_origins_str = os.getenv("CORS_ORIGINS", "http://localhost:3000")
+        _gateway_config = GatewayConfig(
+            host=os.getenv("GATEWAY_HOST", "0.0.0.0"),
+            port=int(os.getenv("GATEWAY_PORT", "8001")),
+            cors_origins=cors_origins_str.split(","),
+            enable_docs=os.getenv("GATEWAY_ENABLE_DOCS", "true").lower() == "true",
+        )
+    return _gateway_config

offline-backend-20260512/backend/app/gateway/csrf_middleware.py

@@ -0,0 +1,129 @@
+"""CSRF protection middleware for FastAPI.
+
+Per RFC-001:
+State-changing operations require CSRF protection.
+"""
+
+import secrets
+from collections.abc import Callable
+
+from app.gateway.auth.disabled_mode import is_auth_disabled
+from fastapi import Request, Response
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.responses import JSONResponse
+from starlette.types import ASGIApp
+
+CSRF_COOKIE_NAME = "csrf_token"
+CSRF_HEADER_NAME = "X-CSRF-Token"
+CSRF_TOKEN_LENGTH = 64  # bytes
+
+
+def is_secure_request(request: Request) -> bool:
+    """Detect whether the original client request was made over HTTPS."""
+    return request.headers.get("x-forwarded-proto", request.url.scheme) == "https"
+
+
+def generate_csrf_token() -> str:
+    """Generate a secure random CSRF token."""
+    return secrets.token_urlsafe(CSRF_TOKEN_LENGTH)
+
+
+def should_check_csrf(request: Request) -> bool:
+    """Determine if a request needs CSRF validation.
+
+    CSRF is checked for state-changing methods (POST, PUT, DELETE, PATCH).
+    GET, HEAD, OPTIONS, and TRACE are exempt per RFC 7231.
+    """
+    if request.method not in ("POST", "PUT", "DELETE", "PATCH"):
+        return False
+
+    path = request.url.path.rstrip("/")
+    # Exempt /api/v1/auth/me endpoint
+    if path == "/api/v1/auth/me":
+        return False
+    return True
+
+
+_AUTH_EXEMPT_PATHS: frozenset[str] = frozenset(
+    {
+        "/api/v1/auth/login/local",
+        "/api/v1/auth/login/username",
+        "/api/v1/auth/logout",
+        "/api/v1/auth/register",
+        "/api/v1/auth/initialize",
+    }
+)
+
+
+def is_auth_endpoint(request: Request) -> bool:
+    """Check if the request is to an auth endpoint.
+
+    Auth endpoints don't need CSRF validation on first call (no token).
+    """
+    return request.url.path.rstrip("/") in _AUTH_EXEMPT_PATHS
+
+
+def _has_bearer_auth(request: Request) -> bool:
+    """Return True when Authorization header carries a Bearer token."""
+    authorization = request.headers.get("authorization", "").strip()
+    if not authorization:
+        return False
+    scheme, _, token = authorization.partition(" ")
+    return scheme.lower() == "bearer" and bool(token.strip())
+
+
+class CSRFMiddleware(BaseHTTPMiddleware):
+    """Middleware that implements CSRF protection using Double Submit Cookie pattern."""
+
+    def __init__(self, app: ASGIApp) -> None:
+        super().__init__(app)
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        _is_auth = is_auth_endpoint(request)
+
+        if is_auth_disabled():
+            return await call_next(request)
+
+        # Double-submit-cookie CSRF applies to cookie-based browser sessions.
+        # API clients using explicit Bearer tokens are not CSRF-prone.
+        if should_check_csrf(request) and not _is_auth and not _has_bearer_auth(request):
+            cookie_token = request.cookies.get(CSRF_COOKIE_NAME)
+            header_token = request.headers.get(CSRF_HEADER_NAME)
+
+            if not cookie_token or not header_token:
+                return JSONResponse(
+                    status_code=403,
+                    content={"detail": "CSRF token missing. Include X-CSRF-Token header."},
+                )
+
+            if not secrets.compare_digest(cookie_token, header_token):
+                return JSONResponse(
+                    status_code=403,
+                    content={"detail": "CSRF token mismatch."},
+                )
+
+        response = await call_next(request)
+
+        # For auth endpoints that set up session, also set CSRF cookie
+        if _is_auth and request.method == "POST":
+            # Generate a new CSRF token for the session
+            csrf_token = generate_csrf_token()
+            is_https = is_secure_request(request)
+            response.set_cookie(
+                key=CSRF_COOKIE_NAME,
+                value=csrf_token,
+                httponly=False,  # Must be JS-readable for Double Submit Cookie pattern
+                secure=is_https,
+                samesite="strict",
+            )
+
+        return response
+
+
+def get_csrf_token(request: Request) -> str | None:
+    """Get the CSRF token from the current request's cookies.
+
+    This is useful for server-side rendering where you need to embed
+    token in forms or headers.
+    """
+    return request.cookies.get(CSRF_COOKIE_NAME)

offline-backend-20260512/backend/app/gateway/deps.py

@@ -0,0 +1,294 @@
+"""Centralized accessors for singleton objects stored on ``app.state``.
+
+**Getters** (used by routers): raise 503 when a required dependency is
+missing, except ``get_store`` which returns ``None``.
+
+Initialization is handled directly in ``app.py`` via :class:`AsyncExitStack`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator, Callable
+from contextlib import AsyncExitStack, asynccontextmanager
+from typing import TYPE_CHECKING, TypeVar, cast
+
+from fastapi import FastAPI, HTTPException, Request
+from langgraph.types import Checkpointer
+
+from deerflow.config.app_config import AppConfig
+from deerflow.persistence.feedback import FeedbackRepository
+from deerflow.runtime import RunContext, RunManager, StreamBridge
+from deerflow.runtime.events.store.base import RunEventStore
+from deerflow.runtime.runs.store.base import RunStore
+
+if TYPE_CHECKING:
+    from app.gateway.auth.local_provider import LocalAuthProvider
+    from app.gateway.auth.repositories.sqlite import SQLiteUserRepository
+    from deerflow.persistence.agents import AgentStore
+    from deerflow.persistence.scheduled_tasks import ScheduledTaskStore
+    from deerflow.persistence.thread_meta.base import ThreadMetaStore
+
+
+T = TypeVar("T")
+
+
+def get_config(request: Request) -> AppConfig:
+    """Return the app-scoped ``AppConfig`` stored on ``app.state``."""
+    config = getattr(request.app.state, "config", None)
+    if config is None:
+        raise HTTPException(status_code=503, detail="Configuration not available")
+    return config
+
+
+@asynccontextmanager
+async def langgraph_runtime(app: FastAPI) -> AsyncGenerator[None, None]:
+    """Bootstrap and tear down all LangGraph runtime singletons.
+
+    Usage in ``app.py``::
+
+        async with langgraph_runtime(app):
+            yield
+    """
+    from deerflow.persistence.engine import close_engine, get_session_factory, init_engine_from_config
+    from deerflow.runtime import make_store, make_stream_bridge
+    from deerflow.runtime.checkpointer.async_provider import make_checkpointer
+    from deerflow.runtime.events.store import make_run_event_store
+
+    async with AsyncExitStack() as stack:
+        config = getattr(app.state, "config", None)
+        if config is None:
+            raise RuntimeError("langgraph_runtime() requires app.state.config to be initialized")
+
+        app.state.stream_bridge = await stack.enter_async_context(make_stream_bridge(config))
+
+        # Initialize persistence engine BEFORE checkpointer so that
+        # auto-create-database logic runs first (postgres backend).
+        await init_engine_from_config(config.database)
+
+        app.state.checkpointer = await stack.enter_async_context(make_checkpointer(config))
+        app.state.store = await stack.enter_async_context(make_store(config))
+
+        # Initialize repositories — one get_session_factory() call for all.
+        sf = get_session_factory()
+        if sf is not None:
+            from deerflow.persistence.feedback import FeedbackRepository
+            from deerflow.persistence.run import RunRepository
+
+            app.state.run_store = RunRepository(sf)
+            app.state.feedback_repo = FeedbackRepository(sf)
+        else:
+            from deerflow.runtime.runs.store.memory import MemoryRunStore
+
+            app.state.run_store = MemoryRunStore()
+            app.state.feedback_repo = None
+
+        from deerflow.persistence.thread_meta import make_thread_store
+
+        app.state.thread_store = make_thread_store(sf, app.state.store)
+
+        from deerflow.persistence.scheduled_tasks import make_scheduled_task_store
+
+        app.state.scheduled_task_store = make_scheduled_task_store(sf)
+
+        from deerflow.persistence.agents import make_agent_store
+
+        app.state.agent_store = make_agent_store(sf)
+
+        # Run event store (has its own factory with config-driven backend selection)
+        run_events_config = getattr(config, "run_events", None)
+        app.state.run_event_store = make_run_event_store(run_events_config)
+
+        # RunManager with store backing for persistence
+        app.state.run_manager = RunManager(store=app.state.run_store)
+
+        try:
+            yield
+        finally:
+            await close_engine()
+
+
+# ---------------------------------------------------------------------------
+# Getters – called by routers per-request
+# ---------------------------------------------------------------------------
+
+
+def _require(attr: str, label: str) -> Callable[[Request], T]:
+    """Create a FastAPI dependency that returns ``app.state.<attr>`` or 503."""
+
+    def dep(request: Request) -> T:
+        val = getattr(request.app.state, attr, None)
+        if val is None:
+            raise HTTPException(status_code=503, detail=f"{label} not available")
+        return cast(T, val)
+
+    dep.__name__ = dep.__qualname__ = f"get_{attr}"
+    return dep
+
+
+get_stream_bridge: Callable[[Request], StreamBridge] = _require("stream_bridge", "Stream bridge")
+get_run_manager: Callable[[Request], RunManager] = _require("run_manager", "Run manager")
+get_checkpointer: Callable[[Request], Checkpointer] = _require("checkpointer", "Checkpointer")
+get_run_event_store: Callable[[Request], RunEventStore] = _require("run_event_store", "Run event store")
+get_feedback_repo: Callable[[Request], FeedbackRepository] = _require("feedback_repo", "Feedback")
+get_run_store: Callable[[Request], RunStore] = _require("run_store", "Run store")
+
+
+def get_store(request: Request):
+    """Return the global store (may be ``None`` if not configured)."""
+    return getattr(request.app.state, "store", None)
+
+
+def get_thread_store(request: Request) -> ThreadMetaStore:
+    """Return the thread metadata store (SQL or memory-backed)."""
+    val = getattr(request.app.state, "thread_store", None)
+    if val is None:
+        raise HTTPException(status_code=503, detail="Thread metadata store not available")
+    return val
+
+
+def get_scheduled_task_store(request: Request) -> ScheduledTaskStore:
+    """Return the scheduled-task store."""
+    val = getattr(request.app.state, "scheduled_task_store", None)
+    if val is None:
+        raise HTTPException(status_code=503, detail="Scheduled task store not available")
+    return val
+
+
+def get_agent_store(request: Request) -> AgentStore:
+    """Return the custom-agent store."""
+    val = getattr(request.app.state, "agent_store", None)
+    if val is None:
+        raise HTTPException(status_code=503, detail="Agent store not available")
+    return val
+
+
+def get_run_context(request: Request) -> RunContext:
+    """Build a :class:`RunContext` from ``app.state`` singletons.
+
+    Returns a *base* context with infrastructure dependencies.
+    """
+    config = get_config(request)
+    return RunContext(
+        checkpointer=get_checkpointer(request),
+        store=get_store(request),
+        event_store=get_run_event_store(request),
+        run_events_config=getattr(config, "run_events", None),
+        thread_store=get_thread_store(request),
+        app_config=config,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Auth helpers (used by authz.py and auth middleware)
+# ---------------------------------------------------------------------------
+
+# Cached singletons to avoid repeated instantiation per request
+_cached_local_provider: LocalAuthProvider | None = None
+_cached_repo: SQLiteUserRepository | None = None
+
+
+def get_request_access_token(request: Request) -> str | None:
+    """Extract access token from cookie or Authorization header.
+
+    Priority:
+    1. ``access_token`` cookie (browser session mode)
+    2. ``Authorization: Bearer <token>`` header (API client mode)
+    """
+    cookie_token = request.cookies.get("access_token")
+    if cookie_token:
+        return cookie_token
+
+    authorization = request.headers.get("authorization", "").strip()
+    if not authorization:
+        return None
+
+    scheme, _, token = authorization.partition(" ")
+    if scheme.lower() != "bearer":
+        return None
+
+    token = token.strip()
+    return token or None
+
+
+def get_local_provider() -> LocalAuthProvider:
+    """Get or create the cached LocalAuthProvider singleton.
+
+    Must be called after ``init_engine_from_config()`` — the shared
+    session factory is required to construct the user repository.
+    """
+    global _cached_local_provider, _cached_repo
+    if _cached_repo is None:
+        from app.gateway.auth.repositories.sqlite import SQLiteUserRepository
+        from deerflow.persistence.engine import get_session_factory
+
+        sf = get_session_factory()
+        if sf is None:
+            raise RuntimeError("get_local_provider() called before init_engine_from_config(); cannot access users table")
+        _cached_repo = SQLiteUserRepository(sf)
+    if _cached_local_provider is None:
+        from app.gateway.auth.local_provider import LocalAuthProvider
+
+        _cached_local_provider = LocalAuthProvider(repository=_cached_repo)
+    return _cached_local_provider
+
+
+async def get_current_user_from_request(request: Request):
+    """Get the current authenticated user from request token.
+
+    Raises HTTPException 401 if not authenticated.
+    """
+    from app.gateway.auth import decode_token
+    from app.gateway.auth.errors import AuthErrorCode, AuthErrorResponse, TokenError, token_error_to_code
+
+    access_token = get_request_access_token(request)
+    if not access_token:
+        raise HTTPException(
+            status_code=401,
+            detail=AuthErrorResponse(code=AuthErrorCode.NOT_AUTHENTICATED, message="Not authenticated").model_dump(),
+        )
+
+    payload = decode_token(access_token)
+    if isinstance(payload, TokenError):
+        raise HTTPException(
+            status_code=401,
+            detail=AuthErrorResponse(code=token_error_to_code(payload), message=f"Token error: {payload.value}").model_dump(),
+        )
+
+    provider = get_local_provider()
+    user = await provider.get_user(payload.sub)
+    if user is None:
+        raise HTTPException(
+            status_code=401,
+            detail=AuthErrorResponse(code=AuthErrorCode.USER_NOT_FOUND, message="User not found").model_dump(),
+        )
+
+    # Token version mismatch → password was changed, token is stale
+    if user.token_version != payload.ver:
+        raise HTTPException(
+            status_code=401,
+            detail=AuthErrorResponse(code=AuthErrorCode.TOKEN_INVALID, message="Token revoked (password changed)").model_dump(),
+        )
+
+    return user
+
+
+async def get_optional_user_from_request(request: Request):
+    """Get optional authenticated user from request.
+
+    Returns None if not authenticated.
+    """
+    try:
+        return await get_current_user_from_request(request)
+    except HTTPException:
+        return None
+
+
+async def get_current_user(request: Request) -> str | None:
+    """Extract user_id from request cookie, or None if not authenticated.
+
+    Thin adapter that returns the string id for callers that only need
+    identification (e.g., ``feedback.py``). Full-user callers should use
+    ``get_current_user_from_request`` or ``get_optional_user_from_request``.
+    """
+    user = await get_optional_user_from_request(request)
+    return str(user.id) if user else None

offline-backend-20260512/backend/app/gateway/internal_auth.py

@@ -0,0 +1,26 @@
+"""Process-local authentication for Gateway internal callers."""
+
+from __future__ import annotations
+
+import secrets
+from types import SimpleNamespace
+
+from deerflow.runtime.user_context import DEFAULT_USER_ID
+
+INTERNAL_AUTH_HEADER_NAME = "X-DeerFlow-Internal-Token"
+_INTERNAL_AUTH_TOKEN = secrets.token_urlsafe(32)
+
+
+def create_internal_auth_headers() -> dict[str, str]:
+    """Return headers that authenticate same-process Gateway internal calls."""
+    return {INTERNAL_AUTH_HEADER_NAME: _INTERNAL_AUTH_TOKEN}
+
+
+def is_valid_internal_auth_token(token: str | None) -> bool:
+    """Return True when *token* matches the process-local internal token."""
+    return bool(token) and secrets.compare_digest(token, _INTERNAL_AUTH_TOKEN)
+
+
+def get_internal_user():
+    """Return the synthetic user used for trusted internal channel calls."""
+    return SimpleNamespace(id=DEFAULT_USER_ID, system_role="internal")

offline-backend-20260512/backend/app/gateway/langgraph_auth.py

@@ -0,0 +1,122 @@
+"""LangGraph Server auth handler — shares JWT logic with Gateway.
+
+Loaded by LangGraph Server via langgraph.json ``auth.path``.
+Reuses the same ``decode_token`` / ``get_auth_config`` as Gateway,
+so both modes validate tokens with the same secret and rules.
+
+Two layers:
+  1. @auth.authenticate — validates JWT cookie, extracts user_id,
+     and enforces CSRF on state-changing methods (POST/PUT/DELETE/PATCH)
+  2. @auth.on — returns metadata filter so each user only sees own threads
+"""
+
+import secrets
+
+from langgraph_sdk import Auth
+
+from app.gateway.auth.disabled_mode import get_assumed_user_for_disabled_auth, is_auth_disabled
+from app.gateway.auth.errors import TokenError
+from app.gateway.auth.jwt import decode_token
+from app.gateway.deps import get_local_provider
+
+auth = Auth()
+
+# Methods that require CSRF validation (state-changing per RFC 7231).
+_CSRF_METHODS = frozenset({"POST", "PUT", "DELETE", "PATCH"})
+
+
+def _check_csrf(request) -> None:
+    """Enforce Double Submit Cookie CSRF check for state-changing requests.
+
+    Mirrors Gateway's CSRFMiddleware logic so that LangGraph routes
+    proxied directly by nginx have the same CSRF protection.
+    """
+    method = getattr(request, "method", "") or ""
+    if method.upper() not in _CSRF_METHODS:
+        return
+
+    authorization = request.headers.get("authorization", "").strip()
+    if authorization.lower().startswith("bearer "):
+        # CSRF protection is for cookie-auth browser flows.
+        return
+
+    cookie_token = request.cookies.get("csrf_token")
+    header_token = request.headers.get("x-csrf-token")
+
+    if not cookie_token or not header_token:
+        raise Auth.exceptions.HTTPException(
+            status_code=403,
+            detail="CSRF token missing. Include X-CSRF-Token header.",
+        )
+
+    if not secrets.compare_digest(cookie_token, header_token):
+        raise Auth.exceptions.HTTPException(
+            status_code=403,
+            detail="CSRF token mismatch.",
+        )
+
+
+@auth.authenticate
+async def authenticate(request):
+    """Validate the session cookie, decode JWT, and check token_version.
+
+    Same validation chain as Gateway's get_current_user_from_request:
+      cookie → decode JWT → DB lookup → token_version match
+    Also enforces CSRF on state-changing methods.
+    """
+    if is_auth_disabled():
+        user = await get_assumed_user_for_disabled_auth()
+        return str(user.id)
+
+    # CSRF check before authentication so forged cross-site requests
+    # are rejected early, even if the cookie carries a valid JWT.
+    _check_csrf(request)
+
+    token = request.cookies.get("access_token")
+    if not token:
+        authorization = request.headers.get("authorization", "").strip()
+        scheme, _, bearer_token = authorization.partition(" ")
+        if scheme.lower() == "bearer" and bearer_token.strip():
+            token = bearer_token.strip()
+
+    if not token:
+        raise Auth.exceptions.HTTPException(
+            status_code=401,
+            detail="Not authenticated",
+        )
+
+    payload = decode_token(token)
+    if isinstance(payload, TokenError):
+        raise Auth.exceptions.HTTPException(
+            status_code=401,
+            detail="Invalid token",
+        )
+
+    user = await get_local_provider().get_user(payload.sub)
+    if user is None:
+        raise Auth.exceptions.HTTPException(
+            status_code=401,
+            detail="User not found",
+        )
+    if user.token_version != payload.ver:
+        raise Auth.exceptions.HTTPException(
+            status_code=401,
+            detail="Token revoked (password changed)",
+        )
+
+    return payload.sub
+
+
+@auth.on
+async def add_owner_filter(ctx: Auth.types.AuthContext, value: dict):
+    """Inject user_id metadata on writes; filter by user_id on reads.
+
+    Gateway stores thread ownership as ``metadata.user_id``.
+    This handler ensures LangGraph Server enforces the same isolation.
+    """
+    # On create/update: stamp user_id into metadata
+    metadata = value.setdefault("metadata", {})
+    metadata["user_id"] = ctx.user.identity
+
+    # Return filter dict — LangGraph applies it to search/read/delete
+    return {"user_id": ctx.user.identity}

offline-backend-20260512/backend/app/gateway/path_utils.py

@@ -0,0 +1,29 @@
+"""Shared path resolution for thread virtual paths (e.g. mnt/user-data/outputs/...)."""
+
+from pathlib import Path
+
+from fastapi import HTTPException
+
+from deerflow.config.paths import get_paths
+from deerflow.runtime.user_context import get_effective_user_id
+
+
+def resolve_thread_virtual_path(thread_id: str, virtual_path: str) -> Path:
+    """Resolve a virtual path to the actual filesystem path under thread user-data.
+
+    Args:
+        thread_id: The thread ID.
+        virtual_path: The virtual path as seen inside the sandbox
+                      (e.g., /mnt/user-data/outputs/file.txt).
+
+    Returns:
+        The resolved filesystem path.
+
+    Raises:
+        HTTPException: If the path is invalid or outside allowed directories.
+    """
+    try:
+        return get_paths().resolve_virtual_path(thread_id, virtual_path, user_id=get_effective_user_id())
+    except ValueError as e:
+        status = 403 if "traversal" in str(e) else 400
+        raise HTTPException(status_code=status, detail=str(e))

offline-backend-20260512/backend/app/gateway/routers/__init__.py

@@ -0,0 +1,3 @@
+from . import artifacts, assistants_compat, mcp, models, skills, suggestions, thread_runs, threads, uploads
+
+__all__ = ["artifacts", "assistants_compat", "mcp", "models", "skills", "suggestions", "threads", "thread_runs", "uploads"]

offline-backend-20260512/backend/app/gateway/routers/agents.py

@@ -0,0 +1,449 @@
+"""CRUD API for custom agents."""
+
+from __future__ import annotations
+
+import logging
+import shutil
+from datetime import datetime
+from typing import Any
+from uuid import uuid4
+
+import yaml
+from fastapi import APIRouter, HTTPException, Request
+from pydantic import BaseModel, Field
+
+from app.gateway.deps import get_agent_store
+from deerflow.config.agents_api_config import get_agents_api_config
+from deerflow.config.agents_config import list_custom_agents, load_agent_config, load_agent_soul, validate_agent_id
+from deerflow.config.paths import get_paths
+from deerflow.persistence.agents import AgentStore
+from deerflow.runtime.user_context import get_effective_user_id
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/api", tags=["agents"])
+
+
+class AgentResponse(BaseModel):
+    """Response model for an agent."""
+
+    id: str = Field(..., description="Agent id used for routing and filesystem storage")
+    name: str = Field(..., description="Display name. Chinese and duplicate names are allowed.")
+    description: str = Field(default="", description="Agent description")
+    user_id: str | None = Field(default=None, description="Owner user id. Null means built-in.")
+    published: bool = Field(default=False, description="Whether a user-created agent is public")
+    builtin: bool = Field(default=False, description="True when user_id is null")
+    created_at: datetime | str | None = None
+    updated_at: datetime | str | None = None
+    soul: str | None = Field(default=None, description="SOUL.md content")
+
+    # Deprecated compatibility fields. Agent runtime configuration is no longer
+    # stored in the agents table, but older frontends may still read these keys.
+    model: str | None = None
+    tool_groups: list[str] | None = None
+    skills: list[str] | None = None
+
+
+class AgentsListResponse(BaseModel):
+    """Response model for listing all visible agents."""
+
+    agents: list[AgentResponse]
+
+
+class AgentCreateRequest(BaseModel):
+    """Request body for creating a custom agent."""
+
+    name: str = Field(..., description="Display name; Chinese and duplicate names are allowed")
+    description: str = Field(default="", description="Agent description")
+    soul: str = Field(default="", description="SOUL.md content - agent personality and behavioral guardrails")
+    published: bool = Field(default=False, description="Whether the new agent should be public")
+    skills: list[str] | None = Field(default=None, description="Skill whitelist persisted to the agent's config.yaml")
+    model: str | None = Field(default=None, description="Optional model override persisted to config.yaml")
+    tool_groups: list[str] | None = Field(default=None, description="Optional tool group whitelist persisted to config.yaml")
+
+
+class AgentUpdateRequest(BaseModel):
+    """Request body for updating a custom agent."""
+
+    name: str | None = Field(default=None, description="Updated display name")
+    description: str | None = Field(default=None, description="Updated description")
+    soul: str | None = Field(default=None, description="Updated SOUL.md content")
+    published: bool | None = Field(default=None, description="Updated publication state")
+    skills: list[str] | None = Field(default=None, description="Updated skill whitelist (config.yaml)")
+    model: str | None = Field(default=None, description="Updated model override (config.yaml)")
+    tool_groups: list[str] | None = Field(default=None, description="Updated tool group whitelist (config.yaml)")
+
+
+def _require_agents_api_enabled() -> None:
+    """Reject access unless the custom-agent management API is explicitly enabled."""
+    if not get_agents_api_config().enabled:
+        raise HTTPException(
+            status_code=403,
+            detail=("Custom-agent management API is disabled. Set agents_api.enabled=true to expose agent and user-profile routes over HTTP."),
+        )
+
+
+def _current_user_id(request: Request) -> str:
+    user = getattr(request.state, "user", None)
+    if user is not None:
+        return str(user.id)
+    return get_effective_user_id()
+
+
+def _validate_display_name(name: str) -> str:
+    normalized = name.strip()
+    if not normalized:
+        raise HTTPException(status_code=422, detail="Agent name cannot be empty")
+    return normalized
+
+
+def _validate_storage_id(agent_id: str) -> str:
+    try:
+        return validate_agent_id(agent_id) or agent_id
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+
+def _write_agent_config(
+    agent_id: str,
+    *,
+    name: str,
+    description: str,
+    skills: list[str] | None = None,
+    model: str | None = None,
+    tool_groups: list[str] | None = None,
+) -> None:
+    agent_dir = get_paths().agent_dir(agent_id)
+    agent_dir.mkdir(parents=True, exist_ok=True)
+    config_file = agent_dir / "config.yaml"
+    config_data: dict[str, Any] = {
+        "id": agent_id,
+        "name": name,
+        "description": description or "",
+    }
+    if skills is not None:
+        config_data["skills"] = skills
+    if model is not None:
+        config_data["model"] = model
+    if tool_groups is not None:
+        config_data["tool_groups"] = tool_groups
+    with open(config_file, "w", encoding="utf-8") as f:
+        yaml.dump(config_data, f, default_flow_style=False, allow_unicode=True)
+
+
+def _load_config_extras(agent_id: str) -> dict[str, Any]:
+    """Read skills/model/tool_groups from the agent's config.yaml, tolerant of missing files."""
+    try:
+        cfg = load_agent_config(agent_id)
+    except (FileNotFoundError, ValueError):
+        return {"skills": None, "model": None, "tool_groups": None}
+    if cfg is None:
+        return {"skills": None, "model": None, "tool_groups": None}
+    return {"skills": cfg.skills, "model": cfg.model, "tool_groups": cfg.tool_groups}
+
+
+def _write_agent_soul(agent_id: str, soul: str) -> None:
+    agent_dir = get_paths().agent_dir(agent_id)
+    agent_dir.mkdir(parents=True, exist_ok=True)
+    (agent_dir / "SOUL.md").write_text(soul, encoding="utf-8")
+
+
+async def _sync_legacy_agents(store: AgentStore) -> None:
+    """Import existing folder-backed agents as built-in DB records.
+
+    This preserves old deployments where agents already existed under
+    ``.deer-flow/agents/{name}`` before the agents table was introduced.
+    """
+    try:
+        for agent_cfg in list_custom_agents():
+            agent_id = agent_cfg.id or agent_cfg.name
+            if not agent_id:
+                continue
+            await store.ensure_builtin(
+                {
+                    "id": agent_id,
+                    "name": agent_cfg.name,
+                    "description": agent_cfg.description or "",
+                    "published": True,
+                }
+            )
+    except Exception:
+        logger.exception("Failed to sync legacy folder-backed agents")
+
+
+def _record_to_response(record: dict[str, Any], *, include_soul: bool = False) -> AgentResponse:
+    soul: str | None = None
+    if include_soul:
+        soul = load_agent_soul(record["id"]) or ""
+
+    extras = _load_config_extras(record["id"])
+
+    return AgentResponse(
+        id=record["id"],
+        name=record["name"],
+        description=record.get("description") or "",
+        user_id=record.get("user_id"),
+        published=bool(record.get("published", False)),
+        builtin=record.get("user_id") is None,
+        created_at=record.get("created_at"),
+        updated_at=record.get("updated_at"),
+        soul=soul,
+        model=extras["model"],
+        tool_groups=extras["tool_groups"],
+        skills=extras["skills"],
+    )
+
+
+async def _get_owned_or_raise(store: AgentStore, agent_id: str, user_id: str) -> dict[str, Any]:
+    owned = await store.get_owned(agent_id, user_id)
+    if owned is not None:
+        return owned
+    visible = await store.get_visible(agent_id, user_id)
+    if visible is None:
+        raise HTTPException(status_code=404, detail=f"Agent '{agent_id}' not found")
+    raise HTTPException(status_code=403, detail="You can only modify agents that you created")
+
+
+@router.get(
+    "/agents",
+    response_model=AgentsListResponse,
+    summary="List Agents",
+    description="List built-in agents, the current user's agents, and published agents.",
+)
+async def list_agents(request: Request) -> AgentsListResponse:
+    _require_agents_api_enabled()
+
+    try:
+        store = get_agent_store(request)
+        await _sync_legacy_agents(store)
+        user_id = _current_user_id(request)
+        agents = await store.list_visible(user_id)
+        return AgentsListResponse(agents=[_record_to_response(a, include_soul=True) for a in agents])
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error("Failed to list agents: %s", e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to list agents: {str(e)}") from e
+
+
+@router.get(
+    "/agents/check",
+    summary="Check Agent Name",
+    description="Validate an agent display name. Duplicate names are allowed.",
+)
+async def check_agent_name(name: str) -> dict[str, Any]:
+    _require_agents_api_enabled()
+    normalized = _validate_display_name(name)
+    return {"available": True, "name": normalized}
+
+
+@router.get(
+    "/agents/{agent_id}",
+    response_model=AgentResponse,
+    summary="Get Agent",
+    description="Retrieve details and SOUL.md content for a visible agent.",
+)
+async def get_agent(agent_id: str, request: Request) -> AgentResponse:
+    _require_agents_api_enabled()
+    agent_id = _validate_storage_id(agent_id)
+
+    try:
+        store = get_agent_store(request)
+        await _sync_legacy_agents(store)
+        record = await store.get_visible(agent_id, _current_user_id(request))
+        if record is None:
+            raise HTTPException(status_code=404, detail=f"Agent '{agent_id}' not found")
+        return _record_to_response(record, include_soul=True)
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error("Failed to get agent '%s': %s", agent_id, e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to get agent: {str(e)}") from e
+
+
+@router.post(
+    "/agents",
+    response_model=AgentResponse,
+    status_code=201,
+    summary="Create Agent",
+    description="Create a new user-owned agent. The display name can be Chinese and may duplicate existing names.",
+)
+async def create_agent_endpoint(request: AgentCreateRequest, http_request: Request) -> AgentResponse:
+    _require_agents_api_enabled()
+    name = _validate_display_name(request.name)
+    agent_id = uuid4().hex
+    agent_dir = get_paths().agent_dir(agent_id)
+
+    try:
+        store = get_agent_store(http_request)
+        if agent_dir.exists():
+            raise HTTPException(status_code=409, detail=f"Generated agent id '{agent_id}' already exists")
+
+        _write_agent_config(
+            agent_id,
+            name=name,
+            description=request.description or "",
+            skills=request.skills,
+            model=request.model,
+            tool_groups=request.tool_groups,
+        )
+        _write_agent_soul(agent_id, request.soul)
+
+        record = await store.create(
+            {
+                "id": agent_id,
+                "name": name,
+                "description": request.description or "",
+                "user_id": _current_user_id(http_request),
+                "published": request.published,
+            }
+        )
+        logger.info("Created agent '%s' (%s) at %s", name, agent_id, agent_dir)
+        return _record_to_response(record, include_soul=True)
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        if agent_dir.exists():
+            shutil.rmtree(agent_dir)
+        logger.error("Failed to create agent '%s': %s", request.name, e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to create agent: {str(e)}") from e
+
+
+@router.put(
+    "/agents/{agent_id}",
+    response_model=AgentResponse,
+    summary="Update Agent",
+    description="Update an existing user-owned agent.",
+)
+async def update_agent(agent_id: str, request: AgentUpdateRequest, http_request: Request) -> AgentResponse:
+    _require_agents_api_enabled()
+    agent_id = _validate_storage_id(agent_id)
+
+    try:
+        store = get_agent_store(http_request)
+        user_id = _current_user_id(http_request)
+        current = await _get_owned_or_raise(store, agent_id, user_id)
+
+        fields_set = request.model_fields_set
+        update_data: dict[str, Any] = {}
+        if "name" in fields_set:
+            update_data["name"] = _validate_display_name(request.name or "")
+        if "description" in fields_set:
+            update_data["description"] = request.description or ""
+        if "published" in fields_set:
+            update_data["published"] = bool(request.published)
+
+        next_name = update_data.get("name", current["name"])
+        next_description = update_data.get("description", current.get("description") or "")
+
+        existing_extras = _load_config_extras(agent_id)
+        next_skills = request.skills if "skills" in fields_set else existing_extras["skills"]
+        next_model = request.model if "model" in fields_set else existing_extras["model"]
+        next_tool_groups = request.tool_groups if "tool_groups" in fields_set else existing_extras["tool_groups"]
+
+        config_dirty = bool(update_data) or any(key in fields_set for key in ("skills", "model", "tool_groups"))
+        if config_dirty:
+            _write_agent_config(
+                agent_id,
+                name=next_name,
+                description=next_description,
+                skills=next_skills,
+                model=next_model,
+                tool_groups=next_tool_groups,
+            )
+        if request.soul is not None:
+            _write_agent_soul(agent_id, request.soul)
+
+        record = await store.update(agent_id, user_id, update_data) if update_data else current
+        if record is None:
+            raise HTTPException(status_code=404, detail=f"Agent '{agent_id}' not found")
+
+        logger.info("Updated agent '%s' (%s)", record["name"], agent_id)
+        return _record_to_response(record, include_soul=True)
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error("Failed to update agent '%s': %s", agent_id, e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to update agent: {str(e)}") from e
+
+
+class UserProfileResponse(BaseModel):
+    """Response model for the global user profile (USER.md)."""
+
+    content: str | None = Field(default=None, description="USER.md content, or null if not yet created")
+
+
+class UserProfileUpdateRequest(BaseModel):
+    """Request body for setting the global user profile."""
+
+    content: str = Field(default="", description="USER.md content - describes the user's background and preferences")
+
+
+@router.get(
+    "/user-profile",
+    response_model=UserProfileResponse,
+    summary="Get User Profile",
+    description="Read the global USER.md file that is injected into all custom agents.",
+)
+async def get_user_profile() -> UserProfileResponse:
+    _require_agents_api_enabled()
+
+    try:
+        user_md_path = get_paths().user_md_file
+        if not user_md_path.exists():
+            return UserProfileResponse(content=None)
+        raw = user_md_path.read_text(encoding="utf-8").strip()
+        return UserProfileResponse(content=raw or None)
+    except Exception as e:
+        logger.error("Failed to read user profile: %s", e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to read user profile: {str(e)}") from e
+
+
+@router.put(
+    "/user-profile",
+    response_model=UserProfileResponse,
+    summary="Update User Profile",
+    description="Write the global USER.md file that is injected into all custom agents.",
+)
+async def update_user_profile(request: UserProfileUpdateRequest) -> UserProfileResponse:
+    _require_agents_api_enabled()
+
+    try:
+        paths = get_paths()
+        paths.base_dir.mkdir(parents=True, exist_ok=True)
+        paths.user_md_file.write_text(request.content, encoding="utf-8")
+        logger.info("Updated USER.md at %s", paths.user_md_file)
+        return UserProfileResponse(content=request.content or None)
+    except Exception as e:
+        logger.error("Failed to update user profile: %s", e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to update user profile: {str(e)}") from e
+
+
+@router.delete(
+    "/agents/{agent_id}",
+    status_code=204,
+    summary="Delete Agent",
+    description="Delete a user-owned agent and all its files.",
+)
+async def delete_agent(agent_id: str, request: Request) -> None:
+    _require_agents_api_enabled()
+    agent_id = _validate_storage_id(agent_id)
+
+    try:
+        store = get_agent_store(request)
+        user_id = _current_user_id(request)
+        await _get_owned_or_raise(store, agent_id, user_id)
+        deleted = await store.delete(agent_id, user_id)
+        if not deleted:
+            raise HTTPException(status_code=404, detail=f"Agent '{agent_id}' not found")
+
+        agent_dir = get_paths().agent_dir(agent_id)
+        if agent_dir.exists():
+            shutil.rmtree(agent_dir)
+        logger.info("Deleted agent '%s' from %s", agent_id, agent_dir)
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error("Failed to delete agent '%s': %s", agent_id, e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to delete agent: {str(e)}") from e

offline-backend-20260512/backend/app/gateway/routers/artifacts.py

@@ -0,0 +1,183 @@
+import logging
+import mimetypes
+import zipfile
+from pathlib import Path
+from urllib.parse import quote
+
+from fastapi import APIRouter, HTTPException, Request
+from fastapi.responses import FileResponse, PlainTextResponse, Response
+
+from app.gateway.authz import require_permission
+from app.gateway.path_utils import resolve_thread_virtual_path
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api", tags=["artifacts"])
+
+ACTIVE_CONTENT_MIME_TYPES = {
+    "text/html",
+    "application/xhtml+xml",
+    "image/svg+xml",
+}
+
+
+def _build_content_disposition(disposition_type: str, filename: str) -> str:
+    """Build an RFC 5987 encoded Content-Disposition header value."""
+    return f"{disposition_type}; filename*=UTF-8''{quote(filename)}"
+
+
+def _build_attachment_headers(filename: str, extra_headers: dict[str, str] | None = None) -> dict[str, str]:
+    headers = {"Content-Disposition": _build_content_disposition("attachment", filename)}
+    if extra_headers:
+        headers.update(extra_headers)
+    return headers
+
+
+def is_text_file_by_content(path: Path, sample_size: int = 8192) -> bool:
+    """Check if file is text by examining content for null bytes."""
+    try:
+        with open(path, "rb") as f:
+            chunk = f.read(sample_size)
+            # Text files shouldn't contain null bytes
+            return b"\x00" not in chunk
+    except Exception:
+        return False
+
+
+def _extract_file_from_skill_archive(zip_path: Path, internal_path: str) -> bytes | None:
+    """Extract a file from a .skill ZIP archive.
+
+    Args:
+        zip_path: Path to the .skill file (ZIP archive).
+        internal_path: Path to the file inside the archive (e.g., "SKILL.md").
+
+    Returns:
+        The file content as bytes, or None if not found.
+    """
+    if not zipfile.is_zipfile(zip_path):
+        return None
+
+    try:
+        with zipfile.ZipFile(zip_path, "r") as zip_ref:
+            # List all files in the archive
+            namelist = zip_ref.namelist()
+
+            # Try direct path first
+            if internal_path in namelist:
+                return zip_ref.read(internal_path)
+
+            # Try with any top-level directory prefix (e.g., "skill-name/SKILL.md")
+            for name in namelist:
+                if name.endswith("/" + internal_path) or name == internal_path:
+                    return zip_ref.read(name)
+
+            # Not found
+            return None
+    except (zipfile.BadZipFile, KeyError):
+        return None
+
+
+@router.get(
+    "/threads/{thread_id}/artifacts/{path:path}",
+    summary="Get Artifact File",
+    description="Retrieve an artifact file generated by the AI agent. Text and binary files can be viewed inline, while active web content is always downloaded.",
+)
+@require_permission("threads", "read", owner_check=True)
+async def get_artifact(thread_id: str, path: str, request: Request, download: bool = False) -> Response:
+    """Get an artifact file by its path.
+
+    The endpoint automatically detects file types and returns appropriate content types.
+    Use the `download` query parameter to force file download for non-active content.
+
+    Args:
+        thread_id: The thread ID.
+        path: The artifact path with virtual prefix (e.g., mnt/user-data/outputs/file.txt).
+        request: FastAPI request object (automatically injected).
+
+    Returns:
+        The file content as a FileResponse with appropriate content type:
+        - Active content (HTML/XHTML/SVG): Served as download attachment
+        - Text files: Plain text with proper MIME type
+        - Binary files: Inline display with download option
+
+    Raises:
+        HTTPException:
+            - 400 if path is invalid or not a file
+            - 403 if access denied (path traversal detected)
+            - 404 if file not found
+
+    Query Parameters:
+        download (bool): If true, forces attachment download for file types that are
+            otherwise returned inline or as plain text. Active HTML/XHTML/SVG content
+            is always downloaded regardless of this flag.
+
+    Example:
+        - Get text file inline: `/api/threads/abc123/artifacts/mnt/user-data/outputs/notes.txt`
+        - Download file: `/api/threads/abc123/artifacts/mnt/user-data/outputs/data.csv?download=true`
+        - Active web content such as `.html`, `.xhtml`, and `.svg` artifacts is always downloaded
+    """
+    # Check if this is a request for a file inside a .skill archive (e.g., xxx.skill/SKILL.md)
+    if ".skill/" in path:
+        # Split the path at ".skill/" to get the ZIP file path and internal path
+        skill_marker = ".skill/"
+        marker_pos = path.find(skill_marker)
+        skill_file_path = path[: marker_pos + len(".skill")]  # e.g., "mnt/user-data/outputs/my-skill.skill"
+        internal_path = path[marker_pos + len(skill_marker) :]  # e.g., "SKILL.md"
+
+        actual_skill_path = resolve_thread_virtual_path(thread_id, skill_file_path)
+
+        if not actual_skill_path.exists():
+            raise HTTPException(status_code=404, detail=f"Skill file not found: {skill_file_path}")
+
+        if not actual_skill_path.is_file():
+            raise HTTPException(status_code=400, detail=f"Path is not a file: {skill_file_path}")
+
+        # Extract the file from the .skill archive
+        content = _extract_file_from_skill_archive(actual_skill_path, internal_path)
+        if content is None:
+            raise HTTPException(status_code=404, detail=f"File '{internal_path}' not found in skill archive")
+
+        # Determine MIME type based on the internal file
+        mime_type, _ = mimetypes.guess_type(internal_path)
+        # Add cache headers to avoid repeated ZIP extraction (cache for 5 minutes)
+        cache_headers = {"Cache-Control": "private, max-age=300"}
+        download_name = Path(internal_path).name or actual_skill_path.stem
+        if download or mime_type in ACTIVE_CONTENT_MIME_TYPES:
+            return Response(content=content, media_type=mime_type or "application/octet-stream", headers=_build_attachment_headers(download_name, cache_headers))
+
+        if mime_type and mime_type.startswith("text/"):
+            return PlainTextResponse(content=content.decode("utf-8"), media_type=mime_type, headers=cache_headers)
+
+        # Default to plain text for unknown types that look like text
+        try:
+            return PlainTextResponse(content=content.decode("utf-8"), media_type="text/plain", headers=cache_headers)
+        except UnicodeDecodeError:
+            return Response(content=content, media_type=mime_type or "application/octet-stream", headers=cache_headers)
+
+    actual_path = resolve_thread_virtual_path(thread_id, path)
+
+    logger.info(f"Resolving artifact path: thread_id={thread_id}, requested_path={path}, actual_path={actual_path}")
+
+    if not actual_path.exists():
+        raise HTTPException(status_code=404, detail=f"Artifact not found: {path}")
+
+    if not actual_path.is_file():
+        raise HTTPException(status_code=400, detail=f"Path is not a file: {path}")
+
+    mime_type, _ = mimetypes.guess_type(actual_path)
+
+    if download:
+        return FileResponse(path=actual_path, filename=actual_path.name, media_type=mime_type, headers=_build_attachment_headers(actual_path.name))
+
+    # Always force download for active content types to prevent script execution
+    # in the application origin when users open generated artifacts.
+    if mime_type in ACTIVE_CONTENT_MIME_TYPES:
+        return FileResponse(path=actual_path, filename=actual_path.name, media_type=mime_type, headers=_build_attachment_headers(actual_path.name))
+
+    if mime_type and mime_type.startswith("text/"):
+        return PlainTextResponse(content=actual_path.read_text(encoding="utf-8"), media_type=mime_type)
+
+    if is_text_file_by_content(actual_path):
+        return PlainTextResponse(content=actual_path.read_text(encoding="utf-8"), media_type=mime_type)
+
+    return Response(content=actual_path.read_bytes(), media_type=mime_type, headers={"Content-Disposition": _build_content_disposition("inline", actual_path.name)})

offline-backend-20260512/backend/app/gateway/routers/assistants_compat.py

@@ -0,0 +1,199 @@
+"""Assistants compatibility endpoints.
+
+Provides LangGraph Platform-compatible assistants API backed by the
+``langgraph.json`` graph registry and ``config.yaml`` agent definitions.
+
+This is a minimal stub that satisfies the ``useStream`` React hook's
+initialization requirements (``assistants.search()`` and ``assistants.get()``).
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import UTC, datetime
+from typing import Any
+
+from fastapi import APIRouter, HTTPException, Request
+from pydantic import BaseModel, Field
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/api/assistants", tags=["assistants-compat"])
+
+
+class AssistantResponse(BaseModel):
+    assistant_id: str
+    graph_id: str
+    name: str
+    config: dict[str, Any] = Field(default_factory=dict)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    description: str | None = None
+    created_at: str = ""
+    updated_at: str = ""
+    version: int = 1
+
+
+class AssistantSearchRequest(BaseModel):
+    graph_id: str | None = None
+    name: str | None = None
+    metadata: dict[str, Any] | None = None
+    limit: int = 10
+    offset: int = 0
+
+
+def _get_default_assistant() -> AssistantResponse:
+    """Return the default lead_agent assistant."""
+    now = datetime.now(UTC).isoformat()
+    return AssistantResponse(
+        assistant_id="lead_agent",
+        graph_id="lead_agent",
+        name="lead_agent",
+        config={},
+        metadata={"created_by": "system"},
+        description="DeerFlow lead agent",
+        created_at=now,
+        updated_at=now,
+        version=1,
+    )
+
+
+async def _sync_legacy_agents(store) -> None:
+    from deerflow.config.agents_config import list_custom_agents
+
+    for agent_cfg in list_custom_agents():
+        agent_id = agent_cfg.id or agent_cfg.name
+        if agent_id:
+            await store.ensure_builtin(
+                {
+                    "id": agent_id,
+                    "name": agent_cfg.name,
+                    "description": agent_cfg.description or "",
+                    "published": True,
+                }
+            )
+
+
+def _legacy_assistants() -> list[AssistantResponse]:
+    assistants: list[AssistantResponse] = []
+    try:
+        from deerflow.config.agents_config import list_custom_agents
+
+        for agent_cfg in list_custom_agents():
+            now = datetime.now(UTC).isoformat()
+            assistant_id = agent_cfg.id or agent_cfg.name
+            assistants.append(
+                AssistantResponse(
+                    assistant_id=assistant_id,
+                    graph_id="lead_agent",
+                    name=agent_cfg.name,
+                    config={},
+                    metadata={"created_by": "system", "agent_id": assistant_id},
+                    description=agent_cfg.description or "",
+                    created_at=now,
+                    updated_at=now,
+                    version=1,
+                )
+            )
+    except Exception:
+        logger.debug("Could not load legacy custom agents for assistants list")
+    return assistants
+
+
+async def _list_assistants(request: Request) -> list[AssistantResponse]:
+    """List all available assistants from config."""
+    assistants = [_get_default_assistant()]
+
+    try:
+        from app.gateway.deps import get_agent_store
+        from deerflow.runtime.user_context import get_effective_user_id
+
+        store = get_agent_store(request)
+        await _sync_legacy_agents(store)
+        for record in await store.list_visible(get_effective_user_id()):
+            created_at = str(record.get("created_at") or datetime.now(UTC).isoformat())
+            updated_at = str(record.get("updated_at") or created_at)
+            assistants.append(
+                AssistantResponse(
+                    assistant_id=record["id"],
+                    graph_id="lead_agent",  # All agents use the same graph
+                    name=record["name"],
+                    config={},
+                    metadata={
+                        "created_by": "system" if record.get("user_id") is None else "user",
+                        "agent_id": record["id"],
+                        "published": bool(record.get("published", False)),
+                    },
+                    description=record.get("description") or "",
+                    created_at=created_at,
+                    updated_at=updated_at,
+                    version=1,
+                )
+            )
+    except Exception:
+        logger.debug("Could not load DB-backed custom agents for assistants list")
+        assistants.extend(_legacy_assistants())
+
+    return assistants
+
+
+@router.post("/search", response_model=list[AssistantResponse])
+async def search_assistants(request: Request, body: AssistantSearchRequest | None = None) -> list[AssistantResponse]:
+    """Search assistants.
+
+    Returns all registered assistants (lead_agent + custom agents from config).
+    """
+    assistants = await _list_assistants(request)
+
+    if body and body.graph_id:
+        assistants = [a for a in assistants if a.graph_id == body.graph_id]
+    if body and body.name:
+        assistants = [a for a in assistants if body.name.lower() in a.name.lower()]
+
+    offset = body.offset if body else 0
+    limit = body.limit if body else 10
+    return assistants[offset : offset + limit]
+
+
+@router.get("/{assistant_id}", response_model=AssistantResponse)
+async def get_assistant_compat(assistant_id: str, request: Request) -> AssistantResponse:
+    """Get an assistant by ID."""
+    for a in await _list_assistants(request):
+        if a.assistant_id == assistant_id:
+            return a
+    raise HTTPException(status_code=404, detail=f"Assistant {assistant_id} not found")
+
+
+@router.get("/{assistant_id}/graph")
+async def get_assistant_graph(assistant_id: str, request: Request) -> dict:
+    """Get the graph structure for an assistant.
+
+    Returns a minimal graph description. Full graph introspection is
+    not supported in the Gateway — this stub satisfies SDK validation.
+    """
+    found = any(a.assistant_id == assistant_id for a in await _list_assistants(request))
+    if not found:
+        raise HTTPException(status_code=404, detail=f"Assistant {assistant_id} not found")
+
+    return {
+        "graph_id": "lead_agent",
+        "nodes": [],
+        "edges": [],
+    }
+
+
+@router.get("/{assistant_id}/schemas")
+async def get_assistant_schemas(assistant_id: str, request: Request) -> dict:
+    """Get JSON schemas for an assistant's input/output/state.
+
+    Returns empty schemas — full introspection not supported in Gateway.
+    """
+    found = any(a.assistant_id == assistant_id for a in await _list_assistants(request))
+    if not found:
+        raise HTTPException(status_code=404, detail=f"Assistant {assistant_id} not found")
+
+    return {
+        "graph_id": "lead_agent",
+        "input_schema": {},
+        "output_schema": {},
+        "state_schema": {},
+        "config_schema": {},
+    }

offline-backend-20260512/backend/app/gateway/routers/auth.py

@@ -0,0 +1,586 @@
+"""Authentication endpoints."""
+
+import logging
+import os
+import time
+from ipaddress import ip_address, ip_network
+from typing import Literal
+
+from fastapi import APIRouter, Depends, HTTPException, Request, Response, status
+from fastapi.security import OAuth2PasswordRequestForm
+from pydantic import BaseModel, EmailStr, Field, field_validator
+
+from app.gateway.auth import (
+    UserResponse,
+    create_access_token,
+)
+from app.gateway.auth.config import get_auth_config
+from app.gateway.auth.errors import AuthErrorCode, AuthErrorResponse
+from app.gateway.csrf_middleware import is_secure_request
+from app.gateway.deps import get_current_user_from_request, get_local_provider
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api/v1/auth", tags=["auth"])
+
+
+# ── Request/Response Models ──────────────────────────────────────────────
+
+
+class LoginResponse(BaseModel):
+    """Response model for login — token only lives in HttpOnly cookie."""
+
+    expires_in: int  # seconds
+    needs_setup: bool = False
+
+
+# Top common-password blocklist. Drawn from the public SecLists "10k worst
+# passwords" set, lowercased + length>=8 only (shorter ones already fail
+# the min_length check). Kept tight on purpose: this is the **lower bound**
+# defense, not a full HIBP / passlib check, and runs in-process per request.
+_COMMON_PASSWORDS: frozenset[str] = frozenset(
+    {
+        "password",
+        "password1",
+        "password12",
+        "password123",
+        "password1234",
+        "12345678",
+        "123456789",
+        "1234567890",
+        "qwerty12",
+        "qwertyui",
+        "qwerty123",
+        "abc12345",
+        "abcd1234",
+        "iloveyou",
+        "letmein1",
+        "welcome1",
+        "welcome123",
+        "admin123",
+        "administrator",
+        "passw0rd",
+        "p@ssw0rd",
+        "monkey12",
+        "trustno1",
+        "sunshine",
+        "princess",
+        "football",
+        "baseball",
+        "superman",
+        "batman123",
+        "starwars",
+        "dragon123",
+        "master123",
+        "shadow12",
+        "michael1",
+        "jennifer",
+        "computer",
+    }
+)
+
+
+def _password_is_common(password: str) -> bool:
+    """Case-insensitive blocklist check.
+
+    Lowercases the input so trivial mutations like ``Password`` /
+    ``PASSWORD`` are also rejected. Does not normalize digit substitutions
+    (``p@ssw0rd`` is included as a literal entry instead) — keeping the
+    rule cheap and predictable.
+    """
+    return password.lower() in _COMMON_PASSWORDS
+
+
+def _validate_strong_password(value: str) -> str:
+    """Pydantic field-validator body shared by Register + ChangePassword.
+
+    Constraint = function, not type-level mixin. The two request models
+    have no "is-a" relationship; they only share the password-strength
+    rule. Lifting it into a free function lets each model bind it via
+    ``@field_validator(field_name)`` without inheritance gymnastics.
+    """
+    if _password_is_common(value):
+        raise ValueError("Password is too common; choose a stronger password.")
+    return value
+
+
+class RegisterRequest(BaseModel):
+    """Request model for user registration."""
+
+    email: EmailStr
+    password: str = Field(..., min_length=8)
+
+    _strong_password = field_validator("password")(classmethod(lambda cls, v: _validate_strong_password(v)))
+
+
+class UsernameLoginRequest(BaseModel):
+    """Request model for passwordless username login.
+
+    Behavior:
+    - Existing user: direct login without password
+    - Missing user: auto-register and login without password
+    """
+
+    username: str = Field(..., min_length=1, max_length=128)
+
+
+class UsernameLoginResponse(BaseModel):
+    """Response model for passwordless username login.
+
+    Returns the access token directly in the body so non-browser clients
+    can use it as a Bearer credential, while a session cookie is still set
+    for browser-based callers.
+    """
+
+    access_token: str
+    token_type: str = "bearer"
+    expires_in: int
+    user_id: str
+    email: str
+    system_role: Literal["admin", "user"] = "user"
+    needs_setup: bool = False
+    created: bool = Field(default=False, description="True when the user was auto-registered by this call")
+
+
+class ChangePasswordRequest(BaseModel):
+    """Request model for password change (also handles setup flow)."""
+
+    current_password: str
+    new_password: str = Field(..., min_length=8)
+    new_email: EmailStr | None = None
+
+    _strong_password = field_validator("new_password")(classmethod(lambda cls, v: _validate_strong_password(v)))
+
+
+class MessageResponse(BaseModel):
+    """Generic message response."""
+
+    message: str
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────
+
+
+def _username_to_email(username: str) -> str:
+    """Map a frontend username to a valid email used by user storage.
+
+    - If username already looks like an email (`contains @`), use it directly.
+    - Otherwise generate `<normalized-username>@<domain>`.
+    """
+    raw = username.strip()
+    if not raw:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="username cannot be empty")
+
+    if "@" in raw:
+        return raw.lower()
+
+    normalized = "".join(ch if (ch.isalnum() or ch in "._-") else "-" for ch in raw.lower()).strip("._-")
+    if not normalized:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="username is invalid")
+
+    domain = os.getenv("DEER_FLOW_USERNAME_LOGIN_DOMAIN", "local.deerflow").strip().lower() or "local.deerflow"
+    return f"{normalized}@{domain}"
+
+
+def _set_session_cookie(response: Response, token: str, request: Request) -> None:
+    """Set the access_token HttpOnly cookie on the response."""
+    config = get_auth_config()
+    is_https = is_secure_request(request)
+    response.set_cookie(
+        key="access_token",
+        value=token,
+        httponly=True,
+        secure=is_https,
+        samesite="lax",
+        max_age=config.token_expiry_days * 24 * 3600 if is_https else None,
+    )
+
+
+# ── Rate Limiting ────────────────────────────────────────────────────────
+# In-process dict — not shared across workers.
+#
+# **Limitation**: with multi-worker deployments (e.g., gunicorn -w N), each
+# worker maintains its own lockout table, so an attacker effectively gets
+# N × _MAX_LOGIN_ATTEMPTS guesses before being locked out everywhere. For
+# production multi-worker setups, replace this with a shared store (Redis,
+# database-backed counter) to enforce a true per-IP limit.
+
+_MAX_LOGIN_ATTEMPTS = 5
+_LOCKOUT_SECONDS = 300  # 5 minutes
+
+# ip → (fail_count, lock_until_timestamp)
+_login_attempts: dict[str, tuple[int, float]] = {}
+
+
+def _trusted_proxies() -> list:
+    """Parse ``AUTH_TRUSTED_PROXIES`` env var into a list of ip_network objects.
+
+    Comma-separated CIDR or single-IP entries. Empty / unset = no proxy is
+    trusted (direct mode). Invalid entries are skipped with a logger warning.
+    Read live so env-var overrides take effect immediately and tests can
+    ``monkeypatch.setenv`` without poking a module-level cache.
+    """
+    raw = os.getenv("AUTH_TRUSTED_PROXIES", "").strip()
+    if not raw:
+        return []
+    nets = []
+    for entry in raw.split(","):
+        entry = entry.strip()
+        if not entry:
+            continue
+        try:
+            nets.append(ip_network(entry, strict=False))
+        except ValueError:
+            logger.warning("AUTH_TRUSTED_PROXIES: ignoring invalid entry %r", entry)
+    return nets
+
+
+def _get_client_ip(request: Request) -> str:
+    """Extract the real client IP for rate limiting.
+
+    Trust model:
+
+    - The TCP peer (``request.client.host``) is always the baseline. It is
+      whatever the kernel reports as the connecting socket — unforgeable
+      by the client itself.
+    - ``X-Real-IP`` is **only** honored if the TCP peer is in the
+      ``AUTH_TRUSTED_PROXIES`` allowlist (set via env var, comma-separated
+      CIDR or single IPs). When set, the gateway is assumed to be behind a
+      reverse proxy (nginx, Cloudflare, ALB, …) that overwrites
+      ``X-Real-IP`` with the original client address.
+    - With no ``AUTH_TRUSTED_PROXIES`` set, ``X-Real-IP`` is silently
+      ignored — closing the bypass where any client could rotate the
+      header to dodge per-IP rate limits in dev / direct-gateway mode.
+
+    ``X-Forwarded-For`` is intentionally NOT used because it is naturally
+    client-controlled at the *first* hop and the trust chain is harder to
+    audit per-request.
+    """
+    peer_host = request.client.host if request.client else None
+
+    trusted = _trusted_proxies()
+    if trusted and peer_host:
+        try:
+            peer_ip = ip_address(peer_host)
+            if any(peer_ip in net for net in trusted):
+                real_ip = request.headers.get("x-real-ip", "").strip()
+                if real_ip:
+                    return real_ip
+        except ValueError:
+            # peer_host wasn't a parseable IP (e.g. "unknown") — fall through
+            pass
+
+    return peer_host or "unknown"
+
+
+def _check_rate_limit(ip: str) -> None:
+    """Raise 429 if the IP is currently locked out."""
+    record = _login_attempts.get(ip)
+    if record is None:
+        return
+    fail_count, lock_until = record
+    if fail_count >= _MAX_LOGIN_ATTEMPTS:
+        if time.time() < lock_until:
+            raise HTTPException(
+                status_code=429,
+                detail="Too many login attempts. Try again later.",
+            )
+        del _login_attempts[ip]
+
+
+_MAX_TRACKED_IPS = 10000
+
+
+def _record_login_failure(ip: str) -> None:
+    """Record a failed login attempt for the given IP."""
+    # Evict expired lockouts when dict grows too large
+    if len(_login_attempts) >= _MAX_TRACKED_IPS:
+        now = time.time()
+        expired = [k for k, (c, t) in _login_attempts.items() if c >= _MAX_LOGIN_ATTEMPTS and now >= t]
+        for k in expired:
+            del _login_attempts[k]
+        # If still too large, evict cheapest-to-lose half: below-threshold
+        # IPs (lock_until=0.0) sort first, then earliest-expiring lockouts.
+        if len(_login_attempts) >= _MAX_TRACKED_IPS:
+            by_time = sorted(_login_attempts.items(), key=lambda kv: kv[1][1])
+            for k, _ in by_time[: len(by_time) // 2]:
+                del _login_attempts[k]
+
+    record = _login_attempts.get(ip)
+    if record is None:
+        _login_attempts[ip] = (1, 0.0)
+    else:
+        new_count = record[0] + 1
+        lock_until = time.time() + _LOCKOUT_SECONDS if new_count >= _MAX_LOGIN_ATTEMPTS else 0.0
+        _login_attempts[ip] = (new_count, lock_until)
+
+
+def _record_login_success(ip: str) -> None:
+    """Clear failure counter for the given IP on successful login."""
+    _login_attempts.pop(ip, None)
+
+
+# ── Endpoints ─────────────────────────────────────────────────────────────
+
+
+@router.post("/login/local", response_model=LoginResponse)
+async def login_local(
+    request: Request,
+    response: Response,
+    form_data: OAuth2PasswordRequestForm = Depends(),
+):
+    """Local email/password login."""
+    client_ip = _get_client_ip(request)
+    _check_rate_limit(client_ip)
+
+    user = await get_local_provider().authenticate({"email": form_data.username, "password": form_data.password})
+
+    if user is None:
+        _record_login_failure(client_ip)
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail=AuthErrorResponse(code=AuthErrorCode.INVALID_CREDENTIALS, message="Incorrect email or password").model_dump(),
+        )
+
+    _record_login_success(client_ip)
+    token = create_access_token(str(user.id), token_version=user.token_version)
+    _set_session_cookie(response, token, request)
+
+    return LoginResponse(
+        expires_in=get_auth_config().token_expiry_days * 24 * 3600,
+        needs_setup=user.needs_setup,
+    )
+
+
+@router.post("/login/username", response_model=UsernameLoginResponse)
+async def login_by_username(request: Request, response: Response, body: UsernameLoginRequest):
+    """Passwordless username login with auto-registration.
+
+    Rules:
+    - If mapped account exists, sign in directly (no password required).
+    - If account does not exist, create a regular user and sign in.
+
+    Returns the JWT access token in the response body and also sets it as
+    a session cookie for browser callers.
+    """
+    provider = get_local_provider()
+    email = _username_to_email(body.username)
+
+    created = False
+    user = await provider.get_user_by_email(email)
+    if user is None:
+        try:
+            user = await provider.create_user(email=email, password=None, system_role="user", needs_setup=False)
+            created = True
+            logger.info("Auto-registered passwordless user: %s", email)
+        except ValueError:
+            # Concurrent first login may create the same user in parallel.
+            user = await provider.get_user_by_email(email)
+            if user is None:
+                raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Failed to create or load user")
+
+    token = create_access_token(str(user.id), token_version=user.token_version)
+    _set_session_cookie(response, token, request)
+
+    return UsernameLoginResponse(
+        access_token=token,
+        token_type="bearer",
+        expires_in=get_auth_config().token_expiry_days * 24 * 3600,
+        user_id=str(user.id),
+        email=user.email,
+        system_role=user.system_role,
+        needs_setup=user.needs_setup,
+        created=created,
+    )
+
+
+@router.post("/register", response_model=UserResponse, status_code=status.HTTP_201_CREATED)
+async def register(request: Request, response: Response, body: RegisterRequest):
+    """Register a new user account (always 'user' role).
+
+    Admin is auto-created on first boot. This endpoint creates regular users.
+    Auto-login by setting the session cookie.
+    """
+    try:
+        user = await get_local_provider().create_user(email=body.email, password=body.password, system_role="user")
+    except ValueError:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=AuthErrorResponse(code=AuthErrorCode.EMAIL_ALREADY_EXISTS, message="Email already registered").model_dump(),
+        )
+
+    token = create_access_token(str(user.id), token_version=user.token_version)
+    _set_session_cookie(response, token, request)
+
+    return UserResponse(id=str(user.id), email=user.email, system_role=user.system_role)
+
+
+@router.post("/logout", response_model=MessageResponse)
+async def logout(request: Request, response: Response):
+    """Logout current user by clearing the cookie."""
+    response.delete_cookie(key="access_token", secure=is_secure_request(request), samesite="lax")
+    return MessageResponse(message="Successfully logged out")
+
+
+@router.post("/change-password", response_model=MessageResponse)
+async def change_password(request: Request, response: Response, body: ChangePasswordRequest):
+    """Change password for the currently authenticated user.
+
+    Also handles the first-boot setup flow:
+    - If new_email is provided, updates email (checks uniqueness)
+    - If user.needs_setup is True and new_email is given, clears needs_setup
+    - Always increments token_version to invalidate old sessions
+    - Re-issues session cookie with new token_version
+    """
+    from app.gateway.auth.password import hash_password_async, verify_password_async
+
+    user = await get_current_user_from_request(request)
+
+    if user.password_hash is None:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=AuthErrorResponse(code=AuthErrorCode.INVALID_CREDENTIALS, message="OAuth users cannot change password").model_dump())
+
+    if not await verify_password_async(body.current_password, user.password_hash):
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=AuthErrorResponse(code=AuthErrorCode.INVALID_CREDENTIALS, message="Current password is incorrect").model_dump())
+
+    provider = get_local_provider()
+
+    # Update email if provided
+    if body.new_email is not None:
+        existing = await provider.get_user_by_email(body.new_email)
+        if existing and str(existing.id) != str(user.id):
+            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=AuthErrorResponse(code=AuthErrorCode.EMAIL_ALREADY_EXISTS, message="Email already in use").model_dump())
+        user.email = body.new_email
+
+    # Update password + bump version
+    user.password_hash = await hash_password_async(body.new_password)
+    user.token_version += 1
+
+    # Clear setup flag if this is the setup flow
+    if user.needs_setup and body.new_email is not None:
+        user.needs_setup = False
+
+    await provider.update_user(user)
+
+    # Re-issue cookie with new token_version
+    token = create_access_token(str(user.id), token_version=user.token_version)
+    _set_session_cookie(response, token, request)
+
+    return MessageResponse(message="Password changed successfully")
+
+
+@router.get("/me", response_model=UserResponse)
+async def get_me(request: Request):
+    """Get current authenticated user info."""
+    user = await get_current_user_from_request(request)
+    return UserResponse(id=str(user.id), email=user.email, system_role=user.system_role, needs_setup=user.needs_setup)
+
+
+_SETUP_STATUS_COOLDOWN: dict[str, float] = {}
+_SETUP_STATUS_COOLDOWN_SECONDS = 60
+_MAX_TRACKED_SETUP_STATUS_IPS = 10000
+
+
+@router.get("/setup-status")
+async def setup_status(request: Request):
+    """Check if an admin account exists. Returns needs_setup=True when no admin exists."""
+    client_ip = _get_client_ip(request)
+    now = time.time()
+    last_check = _SETUP_STATUS_COOLDOWN.get(client_ip, 0)
+    elapsed = now - last_check
+    if elapsed < _SETUP_STATUS_COOLDOWN_SECONDS:
+        retry_after = max(1, int(_SETUP_STATUS_COOLDOWN_SECONDS - elapsed))
+        raise HTTPException(
+            status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+            detail="Setup status check is rate limited",
+            headers={"Retry-After": str(retry_after)},
+        )
+    # Evict stale entries when dict grows too large to bound memory usage.
+    if len(_SETUP_STATUS_COOLDOWN) >= _MAX_TRACKED_SETUP_STATUS_IPS:
+        cutoff = now - _SETUP_STATUS_COOLDOWN_SECONDS
+        stale = [k for k, t in _SETUP_STATUS_COOLDOWN.items() if t < cutoff]
+        for k in stale:
+            del _SETUP_STATUS_COOLDOWN[k]
+        # If still too large after evicting expired entries, remove oldest half.
+        if len(_SETUP_STATUS_COOLDOWN) >= _MAX_TRACKED_SETUP_STATUS_IPS:
+            by_time = sorted(_SETUP_STATUS_COOLDOWN.items(), key=lambda kv: kv[1])
+            for k, _ in by_time[: len(by_time) // 2]:
+                del _SETUP_STATUS_COOLDOWN[k]
+    _SETUP_STATUS_COOLDOWN[client_ip] = now
+    admin_count = await get_local_provider().count_admin_users()
+    return {"needs_setup": admin_count == 0}
+
+
+class InitializeAdminRequest(BaseModel):
+    """Request model for first-boot admin account creation."""
+
+    email: EmailStr
+    password: str = Field(..., min_length=8)
+
+    _strong_password = field_validator("password")(classmethod(lambda cls, v: _validate_strong_password(v)))
+
+
+@router.post("/initialize", response_model=UserResponse, status_code=status.HTTP_201_CREATED)
+async def initialize_admin(request: Request, response: Response, body: InitializeAdminRequest):
+    """Create the first admin account on initial system setup.
+
+    Only callable when no admin exists. Returns 409 Conflict if an admin
+    already exists.
+
+    On success, the admin account is created with ``needs_setup=False`` and
+    the session cookie is set.
+    """
+    admin_count = await get_local_provider().count_admin_users()
+    if admin_count > 0:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=AuthErrorResponse(code=AuthErrorCode.SYSTEM_ALREADY_INITIALIZED, message="System already initialized").model_dump(),
+        )
+
+    try:
+        user = await get_local_provider().create_user(email=body.email, password=body.password, system_role="admin", needs_setup=False)
+    except ValueError:
+        # DB unique-constraint race: another concurrent request beat us.
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=AuthErrorResponse(code=AuthErrorCode.SYSTEM_ALREADY_INITIALIZED, message="System already initialized").model_dump(),
+        )
+
+    token = create_access_token(str(user.id), token_version=user.token_version)
+    _set_session_cookie(response, token, request)
+
+    return UserResponse(id=str(user.id), email=user.email, system_role=user.system_role)
+
+
+# ── OAuth Endpoints (Future/Placeholder) ─────────────────────────────────
+
+
+@router.get("/oauth/{provider}")
+async def oauth_login(provider: str):
+    """Initiate OAuth login flow.
+
+    Redirects to the OAuth provider's authorization URL.
+    Currently a placeholder - requires OAuth provider implementation.
+    """
+    if provider not in ["github", "google"]:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Unsupported OAuth provider: {provider}",
+        )
+
+    raise HTTPException(
+        status_code=status.HTTP_501_NOT_IMPLEMENTED,
+        detail="OAuth login not yet implemented",
+    )
+
+
+@router.get("/callback/{provider}")
+async def oauth_callback(provider: str, code: str, state: str):
+    """OAuth callback endpoint.
+
+    Handles the OAuth provider's callback after user authorization.
+    Currently a placeholder.
+    """
+    raise HTTPException(
+        status_code=status.HTTP_501_NOT_IMPLEMENTED,
+        detail="OAuth callback not yet implemented",
+    )

offline-backend-20260512/backend/app/gateway/routers/channels.py

@@ -0,0 +1,52 @@
+"""Gateway router for IM channel management."""
+
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api/channels", tags=["channels"])
+
+
+class ChannelStatusResponse(BaseModel):
+    service_running: bool
+    channels: dict[str, dict]
+
+
+class ChannelRestartResponse(BaseModel):
+    success: bool
+    message: str
+
+
+@router.get("/", response_model=ChannelStatusResponse)
+async def get_channels_status() -> ChannelStatusResponse:
+    """Get the status of all IM channels."""
+    from app.channels.service import get_channel_service
+
+    service = get_channel_service()
+    if service is None:
+        return ChannelStatusResponse(service_running=False, channels={})
+    status = service.get_status()
+    return ChannelStatusResponse(**status)
+
+
+@router.post("/{name}/restart", response_model=ChannelRestartResponse)
+async def restart_channel(name: str) -> ChannelRestartResponse:
+    """Restart a specific IM channel."""
+    from app.channels.service import get_channel_service
+
+    service = get_channel_service()
+    if service is None:
+        raise HTTPException(status_code=503, detail="Channel service is not running")
+
+    success = await service.restart_channel(name)
+    if success:
+        logger.info("Channel %s restarted successfully", name)
+        return ChannelRestartResponse(success=True, message=f"Channel {name} restarted successfully")
+    else:
+        logger.warning("Failed to restart channel %s", name)
+        return ChannelRestartResponse(success=False, message=f"Failed to restart channel {name}")

offline-backend-20260512/backend/app/gateway/routers/feedback.py

@@ -0,0 +1,188 @@
+"""Feedback endpoints — create, list, stats, delete.
+
+Allows users to submit thumbs-up/down feedback on runs,
+optionally scoped to a specific message.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from fastapi import APIRouter, HTTPException, Request
+from pydantic import BaseModel, Field
+
+from app.gateway.authz import require_permission
+from app.gateway.deps import get_current_user, get_feedback_repo, get_run_store
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/api/threads", tags=["feedback"])
+
+
+# ---------------------------------------------------------------------------
+# Request / response models
+# ---------------------------------------------------------------------------
+
+
+class FeedbackCreateRequest(BaseModel):
+    rating: int = Field(..., description="Feedback rating: +1 (positive) or -1 (negative)")
+    comment: str | None = Field(default=None, description="Optional text feedback")
+    message_id: str | None = Field(default=None, description="Optional: scope feedback to a specific message")
+
+
+class FeedbackUpsertRequest(BaseModel):
+    rating: int = Field(..., description="Feedback rating: +1 (positive) or -1 (negative)")
+    comment: str | None = Field(default=None, description="Optional text feedback")
+
+
+class FeedbackResponse(BaseModel):
+    feedback_id: str
+    run_id: str
+    thread_id: str
+    user_id: str | None = None
+    message_id: str | None = None
+    rating: int
+    comment: str | None = None
+    created_at: str = ""
+
+
+class FeedbackStatsResponse(BaseModel):
+    run_id: str
+    total: int = 0
+    positive: int = 0
+    negative: int = 0
+
+
+# ---------------------------------------------------------------------------
+# Endpoints
+# ---------------------------------------------------------------------------
+
+
+@router.put("/{thread_id}/runs/{run_id}/feedback", response_model=FeedbackResponse)
+@require_permission("threads", "write", owner_check=True, require_existing=True)
+async def upsert_feedback(
+    thread_id: str,
+    run_id: str,
+    body: FeedbackUpsertRequest,
+    request: Request,
+) -> dict[str, Any]:
+    """Create or update feedback for a run (idempotent)."""
+    if body.rating not in (1, -1):
+        raise HTTPException(status_code=400, detail="rating must be +1 or -1")
+
+    user_id = await get_current_user(request)
+
+    run_store = get_run_store(request)
+    run = await run_store.get(run_id)
+    if run is None:
+        raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
+    if run.get("thread_id") != thread_id:
+        raise HTTPException(status_code=404, detail=f"Run {run_id} not found in thread {thread_id}")
+
+    feedback_repo = get_feedback_repo(request)
+    return await feedback_repo.upsert(
+        run_id=run_id,
+        thread_id=thread_id,
+        rating=body.rating,
+        user_id=user_id,
+        comment=body.comment,
+    )
+
+
+@router.delete("/{thread_id}/runs/{run_id}/feedback")
+@require_permission("threads", "delete", owner_check=True, require_existing=True)
+async def delete_run_feedback(
+    thread_id: str,
+    run_id: str,
+    request: Request,
+) -> dict[str, bool]:
+    """Delete the current user's feedback for a run."""
+    user_id = await get_current_user(request)
+    feedback_repo = get_feedback_repo(request)
+    deleted = await feedback_repo.delete_by_run(
+        thread_id=thread_id,
+        run_id=run_id,
+        user_id=user_id,
+    )
+    if not deleted:
+        raise HTTPException(status_code=404, detail="No feedback found for this run")
+    return {"success": True}
+
+
+@router.post("/{thread_id}/runs/{run_id}/feedback", response_model=FeedbackResponse)
+@require_permission("threads", "write", owner_check=True, require_existing=True)
+async def create_feedback(
+    thread_id: str,
+    run_id: str,
+    body: FeedbackCreateRequest,
+    request: Request,
+) -> dict[str, Any]:
+    """Submit feedback (thumbs-up/down) for a run."""
+    if body.rating not in (1, -1):
+        raise HTTPException(status_code=400, detail="rating must be +1 or -1")
+
+    user_id = await get_current_user(request)
+
+    # Validate run exists and belongs to thread
+    run_store = get_run_store(request)
+    run = await run_store.get(run_id)
+    if run is None:
+        raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
+    if run.get("thread_id") != thread_id:
+        raise HTTPException(status_code=404, detail=f"Run {run_id} not found in thread {thread_id}")
+
+    feedback_repo = get_feedback_repo(request)
+    return await feedback_repo.create(
+        run_id=run_id,
+        thread_id=thread_id,
+        rating=body.rating,
+        user_id=user_id,
+        message_id=body.message_id,
+        comment=body.comment,
+    )
+
+
+@router.get("/{thread_id}/runs/{run_id}/feedback", response_model=list[FeedbackResponse])
+@require_permission("threads", "read", owner_check=True)
+async def list_feedback(
+    thread_id: str,
+    run_id: str,
+    request: Request,
+) -> list[dict[str, Any]]:
+    """List all feedback for a run."""
+    feedback_repo = get_feedback_repo(request)
+    return await feedback_repo.list_by_run(thread_id, run_id)
+
+
+@router.get("/{thread_id}/runs/{run_id}/feedback/stats", response_model=FeedbackStatsResponse)
+@require_permission("threads", "read", owner_check=True)
+async def feedback_stats(
+    thread_id: str,
+    run_id: str,
+    request: Request,
+) -> dict[str, Any]:
+    """Get aggregated feedback stats (positive/negative counts) for a run."""
+    feedback_repo = get_feedback_repo(request)
+    return await feedback_repo.aggregate_by_run(thread_id, run_id)
+
+
+@router.delete("/{thread_id}/runs/{run_id}/feedback/{feedback_id}")
+@require_permission("threads", "delete", owner_check=True, require_existing=True)
+async def delete_feedback(
+    thread_id: str,
+    run_id: str,
+    feedback_id: str,
+    request: Request,
+) -> dict[str, bool]:
+    """Delete a feedback record."""
+    feedback_repo = get_feedback_repo(request)
+    # Verify feedback belongs to the specified thread/run before deleting
+    existing = await feedback_repo.get(feedback_id)
+    if existing is None:
+        raise HTTPException(status_code=404, detail=f"Feedback {feedback_id} not found")
+    if existing.get("thread_id") != thread_id or existing.get("run_id") != run_id:
+        raise HTTPException(status_code=404, detail=f"Feedback {feedback_id} not found in run {run_id}")
+    deleted = await feedback_repo.delete(feedback_id)
+    if not deleted:
+        raise HTTPException(status_code=404, detail=f"Feedback {feedback_id} not found")
+    return {"success": True}

offline-backend-20260512/backend/app/gateway/routers/mcp.py

@@ -0,0 +1,169 @@
+import json
+import logging
+from pathlib import Path
+from typing import Literal
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel, Field
+
+from deerflow.config.extensions_config import ExtensionsConfig, get_extensions_config, reload_extensions_config
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/api", tags=["mcp"])
+
+
+class McpOAuthConfigResponse(BaseModel):
+    """OAuth configuration for an MCP server."""
+
+    enabled: bool = Field(default=True, description="Whether OAuth token injection is enabled")
+    token_url: str = Field(default="", description="OAuth token endpoint URL")
+    grant_type: Literal["client_credentials", "refresh_token"] = Field(default="client_credentials", description="OAuth grant type")
+    client_id: str | None = Field(default=None, description="OAuth client ID")
+    client_secret: str | None = Field(default=None, description="OAuth client secret")
+    refresh_token: str | None = Field(default=None, description="OAuth refresh token")
+    scope: str | None = Field(default=None, description="OAuth scope")
+    audience: str | None = Field(default=None, description="OAuth audience")
+    token_field: str = Field(default="access_token", description="Token response field containing access token")
+    token_type_field: str = Field(default="token_type", description="Token response field containing token type")
+    expires_in_field: str = Field(default="expires_in", description="Token response field containing expires-in seconds")
+    default_token_type: str = Field(default="Bearer", description="Default token type when response omits token_type")
+    refresh_skew_seconds: int = Field(default=60, description="Refresh this many seconds before expiry")
+    extra_token_params: dict[str, str] = Field(default_factory=dict, description="Additional form params sent to token endpoint")
+
+
+class McpServerConfigResponse(BaseModel):
+    """Response model for MCP server configuration."""
+
+    enabled: bool = Field(default=True, description="Whether this MCP server is enabled")
+    type: str = Field(default="stdio", description="Transport type: 'stdio', 'sse', or 'http'")
+    command: str | None = Field(default=None, description="Command to execute to start the MCP server (for stdio type)")
+    args: list[str] = Field(default_factory=list, description="Arguments to pass to the command (for stdio type)")
+    env: dict[str, str] = Field(default_factory=dict, description="Environment variables for the MCP server")
+    url: str | None = Field(default=None, description="URL of the MCP server (for sse or http type)")
+    headers: dict[str, str] = Field(default_factory=dict, description="HTTP headers to send (for sse or http type)")
+    oauth: McpOAuthConfigResponse | None = Field(default=None, description="OAuth configuration for MCP HTTP/SSE servers")
+    description: str = Field(default="", description="Human-readable description of what this MCP server provides")
+
+
+class McpConfigResponse(BaseModel):
+    """Response model for MCP configuration."""
+
+    mcp_servers: dict[str, McpServerConfigResponse] = Field(
+        default_factory=dict,
+        description="Map of MCP server name to configuration",
+    )
+
+
+class McpConfigUpdateRequest(BaseModel):
+    """Request model for updating MCP configuration."""
+
+    mcp_servers: dict[str, McpServerConfigResponse] = Field(
+        ...,
+        description="Map of MCP server name to configuration",
+    )
+
+
+@router.get(
+    "/mcp/config",
+    response_model=McpConfigResponse,
+    summary="Get MCP Configuration",
+    description="Retrieve the current Model Context Protocol (MCP) server configurations.",
+)
+async def get_mcp_configuration() -> McpConfigResponse:
+    """Get the current MCP configuration.
+
+    Returns:
+        The current MCP configuration with all servers.
+
+    Example:
+        ```json
+        {
+            "mcp_servers": {
+                "github": {
+                    "enabled": true,
+                    "command": "npx",
+                    "args": ["-y", "@modelcontextprotocol/server-github"],
+                    "env": {"GITHUB_TOKEN": "ghp_xxx"},
+                    "description": "GitHub MCP server for repository operations"
+                }
+            }
+        }
+        ```
+    """
+    config = get_extensions_config()
+
+    return McpConfigResponse(mcp_servers={name: McpServerConfigResponse(**server.model_dump()) for name, server in config.mcp_servers.items()})
+
+
+@router.put(
+    "/mcp/config",
+    response_model=McpConfigResponse,
+    summary="Update MCP Configuration",
+    description="Update Model Context Protocol (MCP) server configurations and save to file.",
+)
+async def update_mcp_configuration(request: McpConfigUpdateRequest) -> McpConfigResponse:
+    """Update the MCP configuration.
+
+    This will:
+    1. Save the new configuration to the mcp_config.json file
+    2. Reload the configuration cache
+    3. Reset MCP tools cache to trigger reinitialization
+
+    Args:
+        request: The new MCP configuration to save.
+
+    Returns:
+        The updated MCP configuration.
+
+    Raises:
+        HTTPException: 500 if the configuration file cannot be written.
+
+    Example Request:
+        ```json
+        {
+            "mcp_servers": {
+                "github": {
+                    "enabled": true,
+                    "command": "npx",
+                    "args": ["-y", "@modelcontextprotocol/server-github"],
+                    "env": {"GITHUB_TOKEN": "$GITHUB_TOKEN"},
+                    "description": "GitHub MCP server for repository operations"
+                }
+            }
+        }
+        ```
+    """
+    try:
+        # Get the current config path (or determine where to save it)
+        config_path = ExtensionsConfig.resolve_config_path()
+
+        # If no config file exists, create one in the parent directory (project root)
+        if config_path is None:
+            config_path = Path.cwd().parent / "extensions_config.json"
+            logger.info(f"No existing extensions config found. Creating new config at: {config_path}")
+
+        # Load current config to preserve skills configuration
+        current_config = get_extensions_config()
+
+        # Convert request to dict format for JSON serialization
+        config_data = {
+            "mcpServers": {name: server.model_dump() for name, server in request.mcp_servers.items()},
+            "skills": {name: {"enabled": skill.enabled} for name, skill in current_config.skills.items()},
+        }
+
+        # Write the configuration to file
+        with open(config_path, "w", encoding="utf-8") as f:
+            json.dump(config_data, f, indent=2)
+
+        logger.info(f"MCP configuration updated and saved to: {config_path}")
+
+        # NOTE: No need to reload/reset cache here - LangGraph Server (separate process)
+        # will detect config file changes via mtime and reinitialize MCP tools automatically
+
+        # Reload the configuration and update the global cache
+        reloaded_config = reload_extensions_config()
+        return McpConfigResponse(mcp_servers={name: McpServerConfigResponse(**server.model_dump()) for name, server in reloaded_config.mcp_servers.items()})
+
+    except Exception as e:
+        logger.error(f"Failed to update MCP configuration: {e}", exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to update MCP configuration: {str(e)}")

offline-backend-20260512/backend/app/gateway/routers/memory.py

@@ -0,0 +1,531 @@
+"""Memory API router for retrieving and managing memory data.
+
+All endpoints accept an optional ``agent`` query parameter:
+
+- omitted / empty / ``"global"`` -> operate on the per-user **global**
+  memory file (``users/{uid}/memory.json``).
+- valid agent name -> operate on the **per-agent** memory file
+  (``users/{uid}/agents/{agent}/memory.json``).
+
+Without this parameter the API used to be silently global-only, so any
+memory written while chatting inside a custom agent (which is saved
+per-agent) was invisible from the settings page. See ``GET /api/memory/agents``
+for discovering which agent-scoped buckets the current user owns.
+"""
+
+import re
+
+from fastapi import APIRouter, HTTPException, Query
+from pydantic import BaseModel, Field
+
+from deerflow.agents.memory.updater import (
+    clear_memory_data,
+    create_memory_fact,
+    delete_memory_fact,
+    get_memory_data,
+    import_memory_data,
+    reload_memory_data,
+    update_memory_fact,
+)
+from deerflow.config.agents_config import AGENT_NAME_PATTERN
+from deerflow.config.memory_config import get_memory_config
+from deerflow.config.paths import get_paths
+from deerflow.runtime.user_context import get_effective_user_id
+
+router = APIRouter(prefix="/api", tags=["memory"])
+
+
+# Sentinel values that mean "the per-user global memory file" (no agent).
+# We accept several spellings so the frontend can model the dropdown choice
+# either by omitting the param or by sending an explicit "global"/"".
+_GLOBAL_AGENT_VALUES: frozenset[str] = frozenset({"", "global", "__global__"})
+
+
+def _resolve_agent_name(agent: str | None) -> str | None:
+    """Validate the ``agent`` query parameter and normalize the global sentinel.
+
+    Returns ``None`` for the global memory bucket, or the lowercased agent
+    name otherwise. Raises 400 if the supplied name fails the agent-name
+    pattern (mirrors :func:`FileMemoryStorage._validate_agent_name`, but
+    surfaces a clean HTTP error instead of letting the storage layer raise
+    ``ValueError`` via a 500).
+    """
+    if agent is None:
+        return None
+    stripped = agent.strip()
+    if stripped.lower() in _GLOBAL_AGENT_VALUES:
+        return None
+    if not AGENT_NAME_PATTERN.match(stripped):
+        raise HTTPException(
+            status_code=400,
+            detail=f"Invalid agent name {stripped!r}: must match {AGENT_NAME_PATTERN.pattern}",
+        )
+    return stripped.lower()
+
+
+_AgentQuery = Query(
+    None,
+    description=(
+        "Optional agent name. Omit (or pass 'global') to address the per-user "
+        "global memory bucket; pass a custom-agent name to address that "
+        "agent's per-user memory bucket."
+    ),
+    examples=["my-agent"],
+    pattern=r"^[A-Za-z0-9-]+$|^global$|^$",
+)
+
+
+class ContextSection(BaseModel):
+    """Model for context sections (user and history)."""
+
+    summary: str = Field(default="", description="Summary content")
+    updatedAt: str = Field(default="", description="Last update timestamp")
+
+
+class UserContext(BaseModel):
+    """Model for user context."""
+
+    workContext: ContextSection = Field(default_factory=ContextSection)
+    personalContext: ContextSection = Field(default_factory=ContextSection)
+    topOfMind: ContextSection = Field(default_factory=ContextSection)
+
+
+class HistoryContext(BaseModel):
+    """Model for history context."""
+
+    recentMonths: ContextSection = Field(default_factory=ContextSection)
+    earlierContext: ContextSection = Field(default_factory=ContextSection)
+    longTermBackground: ContextSection = Field(default_factory=ContextSection)
+
+
+class Fact(BaseModel):
+    """Model for a memory fact."""
+
+    id: str = Field(..., description="Unique identifier for the fact")
+    content: str = Field(..., description="Fact content")
+    category: str = Field(default="context", description="Fact category")
+    confidence: float = Field(default=0.5, description="Confidence score (0-1)")
+    createdAt: str = Field(default="", description="Creation timestamp")
+    source: str = Field(default="unknown", description="Source thread ID")
+    sourceError: str | None = Field(default=None, description="Optional description of the prior mistake or wrong approach")
+
+
+class MemoryResponse(BaseModel):
+    """Response model for memory data."""
+
+    version: str = Field(default="1.0", description="Memory schema version")
+    lastUpdated: str = Field(default="", description="Last update timestamp")
+    user: UserContext = Field(default_factory=UserContext)
+    history: HistoryContext = Field(default_factory=HistoryContext)
+    facts: list[Fact] = Field(default_factory=list)
+
+
+def _map_memory_fact_value_error(exc: ValueError) -> HTTPException:
+    """Convert updater validation errors into stable API responses."""
+    if exc.args and exc.args[0] == "confidence":
+        detail = "Invalid confidence value; must be between 0 and 1."
+    else:
+        detail = "Memory fact content cannot be empty."
+    return HTTPException(status_code=400, detail=detail)
+
+
+class FactCreateRequest(BaseModel):
+    """Request model for creating a memory fact."""
+
+    content: str = Field(..., min_length=1, description="Fact content")
+    category: str = Field(default="context", description="Fact category")
+    confidence: float = Field(default=0.5, ge=0.0, le=1.0, description="Confidence score (0-1)")
+
+
+class FactPatchRequest(BaseModel):
+    """PATCH request model that preserves existing values for omitted fields."""
+
+    content: str | None = Field(default=None, min_length=1, description="Fact content")
+    category: str | None = Field(default=None, description="Fact category")
+    confidence: float | None = Field(default=None, ge=0.0, le=1.0, description="Confidence score (0-1)")
+
+
+class MemoryConfigResponse(BaseModel):
+    """Response model for memory configuration."""
+
+    enabled: bool = Field(..., description="Whether memory is enabled")
+    storage_path: str = Field(..., description="Path to memory storage file")
+    debounce_seconds: int = Field(..., description="Debounce time for memory updates")
+    max_facts: int = Field(..., description="Maximum number of facts to store")
+    fact_confidence_threshold: float = Field(..., description="Minimum confidence threshold for facts")
+    injection_enabled: bool = Field(..., description="Whether memory injection is enabled")
+    max_injection_tokens: int = Field(..., description="Maximum tokens for memory injection")
+
+
+class MemoryStatusResponse(BaseModel):
+    """Response model for memory status."""
+
+    config: MemoryConfigResponse
+    data: MemoryResponse
+
+
+class MemoryAgentInfo(BaseModel):
+    """One per-agent memory bucket the current user owns."""
+
+    name: str = Field(..., description="Custom agent name (matches AGENT_NAME_PATTERN).")
+    factCount: int = Field(0, description="Number of facts stored for this agent.")
+    lastUpdated: str = Field("", description="lastUpdated field of the per-agent memory file, if any.")
+
+
+class MemoryAgentsResponse(BaseModel):
+    """Inventory of memory buckets visible to the current user."""
+
+    globalAvailable: bool = Field(..., description="Whether a per-user global memory file exists on disk.")
+    globalFactCount: int = Field(0, description="Facts in the per-user global memory file.")
+    globalLastUpdated: str = Field("", description="lastUpdated field of the global memory file, if any.")
+    agents: list[MemoryAgentInfo] = Field(default_factory=list, description="Sorted by name (case-insensitive).")
+
+
+@router.get(
+    "/memory/agents",
+    response_model=MemoryAgentsResponse,
+    summary="List Memory Buckets",
+    description=(
+        "Enumerate which memory buckets exist for the current user: the "
+        "per-user global file, plus every per-agent memory file the user "
+        "has accumulated by chatting inside custom agents. Drives the "
+        "agent-selector dropdown on the Memory settings page."
+    ),
+)
+async def list_memory_agents() -> MemoryAgentsResponse:
+    """Inspect the on-disk memory layout for the current user.
+
+    This intentionally walks the filesystem instead of querying the
+    custom-agents API: a user can have leftover per-agent memory for an
+    agent they later renamed/deleted, and we still want them to be able to
+    open it (or clear it) from the UI.
+    """
+    import json
+
+    user_id = get_effective_user_id()
+    paths = get_paths()
+    user_dir = paths.user_dir(user_id)
+
+    # Global bucket
+    global_file = paths.user_memory_file(user_id)
+    global_available = global_file.exists()
+    global_facts = 0
+    global_updated = ""
+    if global_available:
+        try:
+            with open(global_file, encoding="utf-8") as f:
+                data = json.load(f)
+            global_facts = len(data.get("facts", []) or [])
+            global_updated = data.get("lastUpdated", "") or ""
+        except (OSError, json.JSONDecodeError):
+            # Treat unreadable file as "exists but empty" — better than 500
+            # since this endpoint is purely informational.
+            pass
+
+    agents: list[MemoryAgentInfo] = []
+    agents_root = user_dir / "agents"
+    if agents_root.is_dir():
+        for entry in sorted(agents_root.iterdir(), key=lambda p: p.name.lower()):
+            if not entry.is_dir():
+                continue
+            mem_file = entry / "memory.json"
+            if not mem_file.exists():
+                continue
+            # Defensive: agent-dir name may have been hand-edited; keep only
+            # those that round-trip through AGENT_NAME_PATTERN so the UI
+            # never receives a value it can't echo back to us.
+            if not AGENT_NAME_PATTERN.match(entry.name):
+                continue
+            facts = 0
+            updated = ""
+            try:
+                with open(mem_file, encoding="utf-8") as f:
+                    data = json.load(f)
+                facts = len(data.get("facts", []) or [])
+                updated = data.get("lastUpdated", "") or ""
+            except (OSError, json.JSONDecodeError):
+                pass
+            agents.append(MemoryAgentInfo(name=entry.name, factCount=facts, lastUpdated=updated))
+
+    return MemoryAgentsResponse(
+        globalAvailable=global_available,
+        globalFactCount=global_facts,
+        globalLastUpdated=global_updated,
+        agents=agents,
+    )
+
+
+@router.get(
+    "/memory",
+    response_model=MemoryResponse,
+    response_model_exclude_none=True,
+    summary="Get Memory Data",
+    description=(
+        "Retrieve the current memory data including user context, history, and facts. "
+        "Pass ``?agent=<name>`` to read a per-agent bucket; omit it to read the per-user global bucket."
+    ),
+)
+async def get_memory(agent: str | None = _AgentQuery) -> MemoryResponse:
+    """Get the current memory data for the global or per-agent bucket.
+
+    Returns:
+        The current memory data with user context, history, and facts.
+
+    Example Response:
+        ```json
+        {
+            "version": "1.0",
+            "lastUpdated": "2024-01-15T10:30:00Z",
+            "user": {
+                "workContext": {"summary": "Working on DeerFlow project", "updatedAt": "..."},
+                "personalContext": {"summary": "Prefers concise responses", "updatedAt": "..."},
+                "topOfMind": {"summary": "Building memory API", "updatedAt": "..."}
+            },
+            "history": {
+                "recentMonths": {"summary": "Recent development activities", "updatedAt": "..."},
+                "earlierContext": {"summary": "", "updatedAt": ""},
+                "longTermBackground": {"summary": "", "updatedAt": ""}
+            },
+            "facts": [
+                {
+                    "id": "fact_abc123",
+                    "content": "User prefers TypeScript over JavaScript",
+                    "category": "preference",
+                    "confidence": 0.9,
+                    "createdAt": "2024-01-15T10:30:00Z",
+                    "source": "thread_xyz"
+                }
+            ]
+        }
+        ```
+    """
+    agent_name = _resolve_agent_name(agent)
+    memory_data = get_memory_data(agent_name, user_id=get_effective_user_id())
+    return MemoryResponse(**memory_data)
+
+
+@router.post(
+    "/memory/reload",
+    response_model=MemoryResponse,
+    response_model_exclude_none=True,
+    summary="Reload Memory Data",
+    description="Reload memory data from the storage file, refreshing the in-memory cache.",
+)
+async def reload_memory(agent: str | None = _AgentQuery) -> MemoryResponse:
+    """Reload memory data from file.
+
+    This forces a reload of the memory data from the storage file,
+    useful when the file has been modified externally.
+
+    Returns:
+        The reloaded memory data.
+    """
+    agent_name = _resolve_agent_name(agent)
+    memory_data = reload_memory_data(agent_name, user_id=get_effective_user_id())
+    return MemoryResponse(**memory_data)
+
+
+@router.delete(
+    "/memory",
+    response_model=MemoryResponse,
+    response_model_exclude_none=True,
+    summary="Clear All Memory Data",
+    description="Delete all saved memory data and reset the memory structure to an empty state.",
+)
+async def clear_memory(agent: str | None = _AgentQuery) -> MemoryResponse:
+    """Clear all persisted memory data for the requested bucket."""
+    agent_name = _resolve_agent_name(agent)
+    try:
+        memory_data = clear_memory_data(agent_name, user_id=get_effective_user_id())
+    except OSError as exc:
+        raise HTTPException(status_code=500, detail="Failed to clear memory data.") from exc
+
+    return MemoryResponse(**memory_data)
+
+
+@router.post(
+    "/memory/facts",
+    response_model=MemoryResponse,
+    response_model_exclude_none=True,
+    summary="Create Memory Fact",
+    description="Create a single saved memory fact manually.",
+)
+async def create_memory_fact_endpoint(
+    request: FactCreateRequest,
+    agent: str | None = _AgentQuery,
+) -> MemoryResponse:
+    """Create a single fact manually."""
+    agent_name = _resolve_agent_name(agent)
+    try:
+        memory_data = create_memory_fact(
+            content=request.content,
+            category=request.category,
+            confidence=request.confidence,
+            agent_name=agent_name,
+            user_id=get_effective_user_id(),
+        )
+    except ValueError as exc:
+        raise _map_memory_fact_value_error(exc) from exc
+    except OSError as exc:
+        raise HTTPException(status_code=500, detail="Failed to create memory fact.") from exc
+
+    return MemoryResponse(**memory_data)
+
+
+@router.delete(
+    "/memory/facts/{fact_id}",
+    response_model=MemoryResponse,
+    response_model_exclude_none=True,
+    summary="Delete Memory Fact",
+    description="Delete a single saved memory fact by its fact id.",
+)
+async def delete_memory_fact_endpoint(
+    fact_id: str,
+    agent: str | None = _AgentQuery,
+) -> MemoryResponse:
+    """Delete a single fact from memory by fact id."""
+    agent_name = _resolve_agent_name(agent)
+    try:
+        memory_data = delete_memory_fact(fact_id, agent_name, user_id=get_effective_user_id())
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail=f"Memory fact '{fact_id}' not found.") from exc
+    except OSError as exc:
+        raise HTTPException(status_code=500, detail="Failed to delete memory fact.") from exc
+
+    return MemoryResponse(**memory_data)
+
+
+@router.patch(
+    "/memory/facts/{fact_id}",
+    response_model=MemoryResponse,
+    response_model_exclude_none=True,
+    summary="Patch Memory Fact",
+    description="Partially update a single saved memory fact by its fact id while preserving omitted fields.",
+)
+async def update_memory_fact_endpoint(
+    fact_id: str,
+    request: FactPatchRequest,
+    agent: str | None = _AgentQuery,
+) -> MemoryResponse:
+    """Partially update a single fact manually."""
+    agent_name = _resolve_agent_name(agent)
+    try:
+        memory_data = update_memory_fact(
+            fact_id=fact_id,
+            content=request.content,
+            category=request.category,
+            confidence=request.confidence,
+            agent_name=agent_name,
+            user_id=get_effective_user_id(),
+        )
+    except ValueError as exc:
+        raise _map_memory_fact_value_error(exc) from exc
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail=f"Memory fact '{fact_id}' not found.") from exc
+    except OSError as exc:
+        raise HTTPException(status_code=500, detail="Failed to update memory fact.") from exc
+
+    return MemoryResponse(**memory_data)
+
+
+@router.get(
+    "/memory/export",
+    response_model=MemoryResponse,
+    response_model_exclude_none=True,
+    summary="Export Memory Data",
+    description="Export the current global memory data as JSON for backup or transfer.",
+)
+async def export_memory(agent: str | None = _AgentQuery) -> MemoryResponse:
+    """Export the current memory data."""
+    agent_name = _resolve_agent_name(agent)
+    memory_data = get_memory_data(agent_name, user_id=get_effective_user_id())
+    return MemoryResponse(**memory_data)
+
+
+@router.post(
+    "/memory/import",
+    response_model=MemoryResponse,
+    response_model_exclude_none=True,
+    summary="Import Memory Data",
+    description="Import and overwrite the current global memory data from a JSON payload.",
+)
+async def import_memory(
+    request: MemoryResponse,
+    agent: str | None = _AgentQuery,
+) -> MemoryResponse:
+    """Import and persist memory data."""
+    agent_name = _resolve_agent_name(agent)
+    try:
+        memory_data = import_memory_data(request.model_dump(), agent_name, user_id=get_effective_user_id())
+    except OSError as exc:
+        raise HTTPException(status_code=500, detail="Failed to import memory data.") from exc
+
+    return MemoryResponse(**memory_data)
+
+
+@router.get(
+    "/memory/config",
+    response_model=MemoryConfigResponse,
+    summary="Get Memory Configuration",
+    description="Retrieve the current memory system configuration.",
+)
+async def get_memory_config_endpoint() -> MemoryConfigResponse:
+    """Get the memory system configuration.
+
+    Returns:
+        The current memory configuration settings.
+
+    Example Response:
+        ```json
+        {
+            "enabled": true,
+            "storage_path": ".deer-flow/memory.json",
+            "debounce_seconds": 30,
+            "max_facts": 100,
+            "fact_confidence_threshold": 0.7,
+            "injection_enabled": true,
+            "max_injection_tokens": 2000
+        }
+        ```
+    """
+    config = get_memory_config()
+    return MemoryConfigResponse(
+        enabled=config.enabled,
+        storage_path=config.storage_path,
+        debounce_seconds=config.debounce_seconds,
+        max_facts=config.max_facts,
+        fact_confidence_threshold=config.fact_confidence_threshold,
+        injection_enabled=config.injection_enabled,
+        max_injection_tokens=config.max_injection_tokens,
+    )
+
+
+@router.get(
+    "/memory/status",
+    response_model=MemoryStatusResponse,
+    response_model_exclude_none=True,
+    summary="Get Memory Status",
+    description="Retrieve both memory configuration and current data in a single request.",
+)
+async def get_memory_status(agent: str | None = _AgentQuery) -> MemoryStatusResponse:
+    """Get the memory system status including configuration and data.
+
+    Returns:
+        Combined memory configuration and current data.
+    """
+    agent_name = _resolve_agent_name(agent)
+    config = get_memory_config()
+    memory_data = get_memory_data(agent_name, user_id=get_effective_user_id())
+
+    return MemoryStatusResponse(
+        config=MemoryConfigResponse(
+            enabled=config.enabled,
+            storage_path=config.storage_path,
+            debounce_seconds=config.debounce_seconds,
+            max_facts=config.max_facts,
+            fact_confidence_threshold=config.fact_confidence_threshold,
+            injection_enabled=config.injection_enabled,
+            max_injection_tokens=config.max_injection_tokens,
+        ),
+        data=MemoryResponse(**memory_data),
+    )

offline-backend-20260512/backend/app/gateway/routers/models.py

@@ -0,0 +1,132 @@
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel, Field
+
+from app.gateway.deps import get_config
+from deerflow.config.app_config import AppConfig
+
+router = APIRouter(prefix="/api", tags=["models"])
+
+
+class ModelResponse(BaseModel):
+    """Response model for model information."""
+
+    name: str = Field(..., description="Unique identifier for the model")
+    model: str = Field(..., description="Actual provider model identifier")
+    display_name: str | None = Field(None, description="Human-readable name")
+    description: str | None = Field(None, description="Model description")
+    supports_thinking: bool = Field(default=False, description="Whether model supports thinking mode")
+    supports_reasoning_effort: bool = Field(default=False, description="Whether model supports reasoning effort")
+
+
+class TokenUsageResponse(BaseModel):
+    """Token usage display configuration."""
+
+    enabled: bool = Field(default=False, description="Whether token usage display is enabled")
+
+
+class ModelsListResponse(BaseModel):
+    """Response model for listing all models."""
+
+    models: list[ModelResponse]
+    token_usage: TokenUsageResponse
+
+
+@router.get(
+    "/models",
+    response_model=ModelsListResponse,
+    summary="List All Models",
+    description="Retrieve a list of all available AI models configured in the system.",
+)
+async def list_models(config: AppConfig = Depends(get_config)) -> ModelsListResponse:
+    """List all available models from configuration.
+
+    Returns model information suitable for frontend display,
+    excluding sensitive fields like API keys and internal configuration.
+
+    Returns:
+        A list of all configured models with their metadata and token usage display settings.
+
+    Example Response:
+        ```json
+        {
+            "models": [
+                {
+                    "name": "gpt-4",
+                    "model": "gpt-4",
+                    "display_name": "GPT-4",
+                    "description": "OpenAI GPT-4 model",
+                    "supports_thinking": false,
+                    "supports_reasoning_effort": false
+                },
+                {
+                    "name": "claude-3-opus",
+                    "model": "claude-3-opus",
+                    "display_name": "Claude 3 Opus",
+                    "description": "Anthropic Claude 3 Opus model",
+                    "supports_thinking": true,
+                    "supports_reasoning_effort": false
+                }
+            ],
+            "token_usage": {
+                "enabled": true
+            }
+        }
+        ```
+    """
+    models = [
+        ModelResponse(
+            name=model.name,
+            model=model.model,
+            display_name=model.display_name,
+            description=model.description,
+            supports_thinking=model.supports_thinking,
+            supports_reasoning_effort=model.supports_reasoning_effort,
+        )
+        for model in config.models
+    ]
+    return ModelsListResponse(
+        models=models,
+        token_usage=TokenUsageResponse(enabled=config.token_usage.enabled),
+    )
+
+
+@router.get(
+    "/models/{model_name}",
+    response_model=ModelResponse,
+    summary="Get Model Details",
+    description="Retrieve detailed information about a specific AI model by its name.",
+)
+async def get_model(model_name: str, config: AppConfig = Depends(get_config)) -> ModelResponse:
+    """Get a specific model by name.
+
+    Args:
+        model_name: The unique name of the model to retrieve.
+
+    Returns:
+        Model information if found.
+
+    Raises:
+        HTTPException: 404 if model not found.
+
+    Example Response:
+        ```json
+        {
+            "name": "gpt-4",
+            "display_name": "GPT-4",
+            "description": "OpenAI GPT-4 model",
+            "supports_thinking": false
+        }
+        ```
+    """
+    model = config.get_model_config(model_name)
+    if model is None:
+        raise HTTPException(status_code=404, detail=f"Model '{model_name}' not found")
+
+    return ModelResponse(
+        name=model.name,
+        model=model.model,
+        display_name=model.display_name,
+        description=model.description,
+        supports_thinking=model.supports_thinking,
+        supports_reasoning_effort=model.supports_reasoning_effort,
+    )

offline-backend-20260512/backend/app/gateway/routers/runs.py

@@ -0,0 +1,169 @@
+"""Stateless runs endpoints -- stream and wait without a pre-existing thread.
+
+These endpoints auto-create a temporary thread when no ``thread_id`` is
+supplied in the request body.  When a ``thread_id`` **is** provided, it
+is reused so that conversation history is preserved across calls.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import uuid
+
+from fastapi import APIRouter, HTTPException, Query, Request
+from fastapi.responses import StreamingResponse
+
+from app.gateway.authz import require_permission
+from app.gateway.deps import get_checkpointer, get_feedback_repo, get_run_event_store, get_run_manager, get_run_store, get_stream_bridge
+from app.gateway.routers.thread_runs import RunCreateRequest
+from app.gateway.services import sse_consumer, start_run
+from deerflow.runtime import serialize_channel_values
+from deerflow.runtime.user_context import get_effective_user_id
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/api/runs", tags=["runs"])
+
+
+def _resolve_thread_id(body: RunCreateRequest) -> str:
+    """Return the thread_id from the request body, or generate a new one."""
+    thread_id = (body.config or {}).get("configurable", {}).get("thread_id")
+    if thread_id:
+        return str(thread_id)
+    return str(uuid.uuid4())
+
+
+def _has_requested_thread_id(body: RunCreateRequest) -> bool:
+    """Return True when caller explicitly provided configurable.thread_id."""
+    return bool((body.config or {}).get("configurable", {}).get("thread_id"))
+
+
+async def _enforce_thread_ownership_if_requested(body: RunCreateRequest, thread_id: str, request: Request) -> None:
+    """When reusing an existing thread_id, enforce owner access check.
+
+    Stateless run endpoints are allowed to auto-create new threads. But if the
+    caller explicitly targets a thread_id that already belongs to someone else,
+    reject it instead of letting the run write into that thread.
+    """
+    if not _has_requested_thread_id(body):
+        return
+
+    from app.gateway.deps import get_thread_store
+
+    thread_store = get_thread_store(request)
+    allowed = await thread_store.check_access(thread_id, get_effective_user_id(), require_existing=False)
+    if not allowed:
+        raise HTTPException(status_code=404, detail=f"Thread {thread_id} not found")
+
+
+@router.post("/stream")
+async def stateless_stream(body: RunCreateRequest, request: Request) -> StreamingResponse:
+    """Create a run and stream events via SSE.
+
+    If ``config.configurable.thread_id`` is provided, the run is created
+    on the given thread so that conversation history is preserved.
+    Otherwise a new temporary thread is created.
+    """
+    thread_id = _resolve_thread_id(body)
+    await _enforce_thread_ownership_if_requested(body, thread_id, request)
+    bridge = get_stream_bridge(request)
+    run_mgr = get_run_manager(request)
+    record = await start_run(body, thread_id, request)
+
+    return StreamingResponse(
+        sse_consumer(bridge, record, request, run_mgr),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+            "X-Accel-Buffering": "no",
+            "Content-Location": f"/api/threads/{thread_id}/runs/{record.run_id}",
+        },
+    )
+
+
+@router.post("/wait", response_model=dict)
+async def stateless_wait(body: RunCreateRequest, request: Request) -> dict:
+    """Create a run and block until completion.
+
+    If ``config.configurable.thread_id`` is provided, the run is created
+    on the given thread so that conversation history is preserved.
+    Otherwise a new temporary thread is created.
+    """
+    thread_id = _resolve_thread_id(body)
+    await _enforce_thread_ownership_if_requested(body, thread_id, request)
+    record = await start_run(body, thread_id, request)
+
+    if record.task is not None:
+        try:
+            await record.task
+        except asyncio.CancelledError:
+            pass
+
+    checkpointer = get_checkpointer(request)
+    config = {"configurable": {"thread_id": thread_id}}
+    try:
+        checkpoint_tuple = await checkpointer.aget_tuple(config)
+        if checkpoint_tuple is not None:
+            checkpoint = getattr(checkpoint_tuple, "checkpoint", {}) or {}
+            channel_values = checkpoint.get("channel_values", {})
+            return serialize_channel_values(channel_values)
+    except Exception:
+        logger.exception("Failed to fetch final state for run %s", record.run_id)
+
+    return {"status": record.status.value, "error": record.error}
+
+
+# ---------------------------------------------------------------------------
+# Run-scoped read endpoints
+# ---------------------------------------------------------------------------
+
+
+async def _resolve_run(run_id: str, request: Request) -> dict:
+    """Fetch run by run_id with user ownership check. Raises 404 if not found."""
+    run_store = get_run_store(request)
+    record = await run_store.get(run_id)  # user_id=AUTO filters by contextvar
+    if record is None:
+        raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
+    return record
+
+
+@router.get("/{run_id}/messages")
+@require_permission("runs", "read")
+async def run_messages(
+    run_id: str,
+    request: Request,
+    limit: int = Query(default=50, le=200, ge=1),
+    before_seq: int | None = Query(default=None),
+    after_seq: int | None = Query(default=None),
+) -> dict:
+    """Return paginated messages for a run (cursor-based).
+
+    Pagination:
+    - after_seq: messages with seq > after_seq (forward)
+    - before_seq: messages with seq < before_seq (backward)
+    - neither: latest messages
+
+    Response: { data: [...], has_more: bool }
+    """
+    run = await _resolve_run(run_id, request)
+    event_store = get_run_event_store(request)
+    rows = await event_store.list_messages_by_run(
+        run["thread_id"],
+        run_id,
+        limit=limit + 1,
+        before_seq=before_seq,
+        after_seq=after_seq,
+    )
+    has_more = len(rows) > limit
+    data = rows[:limit] if has_more else rows
+    return {"data": data, "has_more": has_more}
+
+
+@router.get("/{run_id}/feedback")
+@require_permission("runs", "read")
+async def run_feedback(run_id: str, request: Request) -> list[dict]:
+    """Return all feedback for a run."""
+    run = await _resolve_run(run_id, request)
+    feedback_repo = get_feedback_repo(request)
+    return await feedback_repo.list_by_run(run["thread_id"], run_id)

offline-backend-20260512/backend/app/gateway/routers/scheduled_tasks.py

@@ -0,0 +1,327 @@
+"""Scheduled task management API."""
+
+from __future__ import annotations
+
+import re
+import zipfile
+from io import BytesIO
+import mimetypes
+from pathlib import Path
+from typing import Any
+from urllib.parse import quote
+
+from fastapi import APIRouter, HTTPException, Request
+from fastapi.responses import FileResponse, Response, StreamingResponse
+from pydantic import BaseModel, Field
+
+from app.gateway.deps import get_current_user
+from deerflow.runtime.scheduler import get_scheduled_task_service
+
+router = APIRouter(prefix="/api/scheduled-tasks", tags=["scheduled-tasks"])
+
+
+class ScheduledTaskCreateRequest(BaseModel):
+    name: str = Field(default="Scheduled task")
+    prompt: str
+    schedule: str
+    timezone: str | None = None
+    execution_agent_name: str | None = None
+    execution_context: dict[str, Any] | None = None
+
+
+class ScheduledTaskUpdateRequest(BaseModel):
+    name: str | None = None
+    prompt: str | None = None
+    schedule: str | None = None
+    timezone: str | None = None
+    enabled: bool | None = None
+    execution_agent_name: str | None = None
+    execution_context: dict[str, Any] | None = None
+
+
+class ScheduledTaskDeliveryProfileUpdateRequest(BaseModel):
+    element_user_id: str | None = None
+
+
+async def _user_id(request: Request) -> str:
+    user_id = await get_current_user(request)
+    if not user_id:
+        raise HTTPException(status_code=401, detail="Authentication required")
+    return user_id
+
+
+def _safe_filename(value: str, default: str = "scheduled-task-result") -> str:
+    name = re.sub(r'[\\/:*?"<>|\r\n]+', "-", value).strip(" .")
+    return name or default
+
+
+def _result_download_name(result: dict[str, Any], *, extension: str = "md") -> str:
+    title = result.get("title") if isinstance(result, dict) else None
+    return f"{_safe_filename(str(title or 'scheduled-task-result'))}.{extension}"
+
+
+def _result_markdown(result: dict[str, Any]) -> str:
+    title = str(result.get("title") or "Scheduled Task Result")
+    content = str(result.get("content") or "")
+    return f"# {title}\n\n{content}".strip() + "\n"
+
+
+def _utf8_sig_bytes(content: str) -> bytes:
+    return content.encode("utf-8-sig")
+
+
+def _content_disposition(filename: str) -> str:
+    quoted = quote(filename)
+    return f"attachment; filename*=UTF-8''{quoted}"
+
+
+def _run_files(run: dict[str, Any]) -> list:
+    result = run.get("result") or {}
+    return result.get("files") if isinstance(result, dict) and isinstance(result.get("files"), list) else []
+
+
+def _run_file_path(run: dict[str, Any], file_index: int) -> tuple[dict[str, Any], Path]:
+    files = _run_files(run)
+    if file_index < 0 or file_index >= len(files):
+        raise HTTPException(status_code=404, detail="Result file not found")
+    item = files[file_index]
+    if not isinstance(item, dict) or not isinstance(item.get("path"), str):
+        raise HTTPException(status_code=404, detail="Result file not found")
+    path = Path(item["path"])
+    if not path.exists() or not path.is_file():
+        raise HTTPException(status_code=404, detail="Result file is no longer available")
+    return item, path
+
+
+def _is_text_previewable(path: Path, mime_type: str | None) -> bool:
+    if mime_type and (mime_type.startswith("text/") or mime_type in {"application/json", "application/xml"}):
+        return True
+    return path.suffix.lower() in {".md", ".markdown", ".txt", ".json", ".csv", ".xml", ".yaml", ".yml", ".log"}
+
+
+def _is_text_download(path: Path, mime_type: str | None) -> bool:
+    return _is_text_previewable(path, mime_type)
+
+
+def _read_text_download_bytes(path: Path) -> bytes:
+    try:
+        content = path.read_text(encoding="utf-8-sig")
+    except UnicodeDecodeError:
+        content = path.read_text(encoding="utf-8", errors="replace")
+    return _utf8_sig_bytes(content)
+
+
+@router.get("/thread")
+async def get_scheduler_thread(request: Request) -> dict:
+    service = get_scheduled_task_service()
+    user_id = await _user_id(request)
+    return await service.ensure_scheduler_thread(user_id)
+
+
+@router.get("")
+async def list_scheduled_tasks(request: Request) -> list[dict]:
+    service = get_scheduled_task_service()
+    user_id = await _user_id(request)
+    return await service.list_tasks(user_id)
+
+
+@router.get("/{task_id}/runs")
+async def list_scheduled_task_runs(task_id: str, request: Request, limit: int = 50) -> list[dict]:
+    service = get_scheduled_task_service()
+    user_id = await _user_id(request)
+    runs = await service.list_runs(user_id, task_id, limit=max(1, min(limit, 200)))
+    return runs
+
+
+@router.get("/runs/{run_id}")
+async def get_scheduled_task_run(run_id: str, request: Request) -> dict:
+    service = get_scheduled_task_service()
+    user_id = await _user_id(request)
+    run = await service.get_run(user_id, run_id)
+    if run is None:
+        raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
+    return run
+
+
+@router.delete("/runs/{run_id}")
+async def delete_scheduled_task_run(run_id: str, request: Request) -> dict:
+    service = get_scheduled_task_service()
+    user_id = await _user_id(request)
+    deleted = await service.delete_run(user_id, run_id)
+    if not deleted:
+        raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
+    return {"success": True}
+
+
+@router.get("/runs/{run_id}/files/{file_index}")
+async def get_scheduled_task_run_file(run_id: str, file_index: int, request: Request) -> dict:
+    service = get_scheduled_task_service()
+    user_id = await _user_id(request)
+    run = await service.get_run(user_id, run_id)
+    if run is None:
+        raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
+    item, path = _run_file_path(run, file_index)
+    mime_type = item.get("mime_type") or mimetypes.guess_type(path.name)[0]
+    previewable = _is_text_previewable(path, mime_type)
+    content = None
+    if previewable:
+        try:
+            content = path.read_text(encoding="utf-8")
+        except UnicodeDecodeError:
+            content = path.read_text(encoding="utf-8", errors="replace")
+    return {
+        "index": file_index,
+        "name": item.get("name") or path.name,
+        "mime_type": mime_type,
+        "kind": item.get("kind"),
+        "size": path.stat().st_size,
+        "previewable": previewable,
+        "content": content,
+    }
+
+
+@router.get("/runs/{run_id}/download")
+async def download_scheduled_task_run(run_id: str, request: Request):
+    service = get_scheduled_task_service()
+    user_id = await _user_id(request)
+    run = await service.get_run(user_id, run_id)
+    if run is None:
+        raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
+
+    result = run.get("result") or {}
+    if not isinstance(result, dict):
+        result = {}
+    files = result.get("files") if isinstance(result.get("files"), list) else []
+    accessible_files: list[tuple[str, Path]] = []
+    for item in files:
+        if not isinstance(item, dict):
+            continue
+        path_value = item.get("path")
+        if not isinstance(path_value, str) or not path_value:
+            continue
+        path = Path(path_value)
+        if path.exists() and path.is_file():
+            accessible_files.append((str(item.get("name") or path.name), path))
+
+    if not accessible_files:
+        body = _utf8_sig_bytes(_result_markdown(result))
+        return Response(
+            content=body,
+            media_type="text/markdown; charset=utf-8",
+            headers={"Content-Disposition": _content_disposition(_result_download_name(result))},
+        )
+
+    archive = BytesIO()
+    with zipfile.ZipFile(archive, mode="w", compression=zipfile.ZIP_DEFLATED) as zf:
+        zf.writestr("result.md", _utf8_sig_bytes(_result_markdown(result)))
+        for name, path in accessible_files:
+            arcname = _safe_filename(name, path.name)
+            mime_type = mimetypes.guess_type(path.name)[0]
+            if _is_text_download(path, mime_type):
+                zf.writestr(arcname, _read_text_download_bytes(path))
+            else:
+                zf.write(path, arcname=arcname)
+    archive.seek(0)
+    return StreamingResponse(
+        archive,
+        media_type="application/zip",
+        headers={"Content-Disposition": _content_disposition(_result_download_name(result, extension="zip"))},
+    )
+
+
+@router.get("/runs/{run_id}/files/{file_index}/download")
+async def download_scheduled_task_run_file(run_id: str, file_index: int, request: Request):
+    service = get_scheduled_task_service()
+    user_id = await _user_id(request)
+    run = await service.get_run(user_id, run_id)
+    if run is None:
+        raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
+    item, path = _run_file_path(run, file_index)
+    filename = _safe_filename(str(item.get("name") or path.name), path.name)
+    mime_type = item.get("mime_type") or mimetypes.guess_type(path.name)[0]
+    if _is_text_download(path, mime_type):
+        return Response(
+            content=_read_text_download_bytes(path),
+            media_type=f"{mime_type or 'text/plain'}; charset=utf-8",
+            headers={"Content-Disposition": _content_disposition(filename)},
+        )
+    return FileResponse(path, filename=filename, media_type=item.get("mime_type") or "application/octet-stream")
+
+
+@router.get("/delivery-profile")
+async def get_delivery_profile(request: Request) -> dict:
+    service = get_scheduled_task_service()
+    user_id = await _user_id(request)
+    return await service.get_delivery_profile(user_id)
+
+
+@router.put("/delivery-profile")
+async def update_delivery_profile(body: ScheduledTaskDeliveryProfileUpdateRequest, request: Request) -> dict:
+    service = get_scheduled_task_service()
+    user_id = await _user_id(request)
+    return await service.update_delivery_profile(user_id, body.model_dump(exclude_unset=True))
+
+
+@router.post("")
+async def create_scheduled_task(body: ScheduledTaskCreateRequest, request: Request) -> dict:
+    service = get_scheduled_task_service()
+    user_id = await _user_id(request)
+    return await service.create_task(
+        user_id=user_id,
+        name=body.name,
+        prompt=body.prompt,
+        schedule=body.schedule,
+        timezone=body.timezone,
+        execution_agent_name=body.execution_agent_name,
+        execution_context=body.execution_context,
+    )
+
+
+@router.patch("/{task_id}")
+async def update_scheduled_task(task_id: str, body: ScheduledTaskUpdateRequest, request: Request) -> dict:
+    service = get_scheduled_task_service()
+    user_id = await _user_id(request)
+    task = await service.update_task(user_id, task_id, body.model_dump(exclude_unset=True))
+    if task is None:
+        raise HTTPException(status_code=404, detail=f"Task {task_id} not found")
+    return task
+
+
+@router.delete("/{task_id}")
+async def delete_scheduled_task(task_id: str, request: Request) -> dict:
+    service = get_scheduled_task_service()
+    user_id = await _user_id(request)
+    deleted = await service.delete_task(user_id, task_id)
+    if not deleted:
+        raise HTTPException(status_code=404, detail=f"Task {task_id} not found")
+    return {"success": True}
+
+
+@router.post("/{task_id}/pause")
+async def pause_scheduled_task(task_id: str, request: Request) -> dict:
+    service = get_scheduled_task_service()
+    user_id = await _user_id(request)
+    task = await service.pause_task(user_id, task_id)
+    if task is None:
+        raise HTTPException(status_code=404, detail=f"Task {task_id} not found")
+    return task
+
+
+@router.post("/{task_id}/resume")
+async def resume_scheduled_task(task_id: str, request: Request) -> dict:
+    service = get_scheduled_task_service()
+    user_id = await _user_id(request)
+    task = await service.resume_task(user_id, task_id)
+    if task is None:
+        raise HTTPException(status_code=404, detail=f"Task {task_id} not found")
+    return task
+
+
+@router.post("/{task_id}/trigger")
+async def trigger_scheduled_task(task_id: str, request: Request) -> dict:
+    service = get_scheduled_task_service()
+    user_id = await _user_id(request)
+    task = await service.trigger_task(user_id, task_id)
+    if task is None:
+        raise HTTPException(status_code=404, detail=f"Task {task_id} not found")
+    return {"success": True, "task": task}

offline-backend-20260512/backend/app/gateway/routers/skills.py

@@ -0,0 +1,352 @@
+import json
+import logging
+from pathlib import Path
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel, Field
+
+from app.gateway.deps import get_config
+from app.gateway.path_utils import resolve_thread_virtual_path
+from deerflow.agents.lead_agent.prompt import refresh_skills_system_prompt_cache_async
+from deerflow.config.app_config import AppConfig
+from deerflow.config.extensions_config import ExtensionsConfig, SkillStateConfig, get_extensions_config, reload_extensions_config
+from deerflow.skills import Skill
+from deerflow.skills.installer import SkillAlreadyExistsError
+from deerflow.skills.security_scanner import scan_skill_content
+from deerflow.skills.storage import get_or_new_skill_storage
+from deerflow.skills.types import SKILL_MD_FILE, SkillCategory
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api", tags=["skills"])
+
+
+class SkillResponse(BaseModel):
+    """Response model for skill information."""
+
+    name: str = Field(..., description="Name of the skill")
+    description: str = Field(..., description="Description of what the skill does")
+    license: str | None = Field(None, description="License information")
+    category: SkillCategory = Field(..., description="Category of the skill (public or custom)")
+    enabled: bool = Field(default=True, description="Whether this skill is enabled")
+
+
+class SkillsListResponse(BaseModel):
+    """Response model for listing all skills."""
+
+    skills: list[SkillResponse]
+
+
+class SkillUpdateRequest(BaseModel):
+    """Request model for updating a skill."""
+
+    enabled: bool = Field(..., description="Whether to enable or disable the skill")
+
+
+class SkillInstallRequest(BaseModel):
+    """Request model for installing a skill from a .skill file."""
+
+    thread_id: str = Field(..., description="The thread ID where the .skill file is located")
+    path: str = Field(..., description="Virtual path to the .skill file (e.g., mnt/user-data/outputs/my-skill.skill)")
+
+
+class SkillInstallResponse(BaseModel):
+    """Response model for skill installation."""
+
+    success: bool = Field(..., description="Whether the installation was successful")
+    skill_name: str = Field(..., description="Name of the installed skill")
+    message: str = Field(..., description="Installation result message")
+
+
+class CustomSkillContentResponse(SkillResponse):
+    content: str = Field(..., description="Raw SKILL.md content")
+
+
+class CustomSkillUpdateRequest(BaseModel):
+    content: str = Field(..., description="Replacement SKILL.md content")
+
+
+class CustomSkillHistoryResponse(BaseModel):
+    history: list[dict]
+
+
+class SkillRollbackRequest(BaseModel):
+    history_index: int = Field(default=-1, description="History entry index to restore from, defaulting to the latest change.")
+
+
+def _skill_to_response(skill: Skill) -> SkillResponse:
+    """Convert a Skill object to a SkillResponse."""
+    return SkillResponse(
+        name=skill.name,
+        description=skill.description,
+        license=skill.license,
+        category=skill.category,
+        enabled=skill.enabled,
+    )
+
+
+@router.get(
+    "/skills",
+    response_model=SkillsListResponse,
+    summary="List All Skills",
+    description="Retrieve a list of all available skills from both public and custom directories.",
+)
+async def list_skills(config: AppConfig = Depends(get_config)) -> SkillsListResponse:
+    try:
+        skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
+        return SkillsListResponse(skills=[_skill_to_response(skill) for skill in skills])
+    except Exception as e:
+        logger.error(f"Failed to load skills: {e}", exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to load skills: {str(e)}")
+
+
+@router.post(
+    "/skills/install",
+    response_model=SkillInstallResponse,
+    summary="Install Skill",
+    description="Install a skill from a .skill file (ZIP archive) located in the thread's user-data directory.",
+)
+async def install_skill(request: SkillInstallRequest, config: AppConfig = Depends(get_config)) -> SkillInstallResponse:
+    try:
+        skill_file_path = resolve_thread_virtual_path(request.thread_id, request.path)
+        result = await get_or_new_skill_storage(app_config=config).ainstall_skill_from_archive(skill_file_path)
+        await refresh_skills_system_prompt_cache_async()
+        return SkillInstallResponse(**result)
+    except FileNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except SkillAlreadyExistsError as e:
+        raise HTTPException(status_code=409, detail=str(e))
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Failed to install skill: {e}", exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to install skill: {str(e)}")
+
+
+@router.get("/skills/custom", response_model=SkillsListResponse, summary="List Custom Skills")
+async def list_custom_skills(config: AppConfig = Depends(get_config)) -> SkillsListResponse:
+    try:
+        skills = [skill for skill in get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False) if skill.category == SkillCategory.CUSTOM]
+        return SkillsListResponse(skills=[_skill_to_response(skill) for skill in skills])
+    except Exception as e:
+        logger.error("Failed to list custom skills: %s", e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to list custom skills: {str(e)}")
+
+
+@router.get("/skills/custom/{skill_name}", response_model=CustomSkillContentResponse, summary="Get Custom Skill Content")
+async def get_custom_skill(skill_name: str, config: AppConfig = Depends(get_config)) -> CustomSkillContentResponse:
+    try:
+        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
+        skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
+        skill = next((s for s in skills if s.name == skill_name and s.category == SkillCategory.CUSTOM), None)
+        if skill is None:
+            raise HTTPException(status_code=404, detail=f"Custom skill '{skill_name}' not found")
+        return CustomSkillContentResponse(**_skill_to_response(skill).model_dump(), content=get_or_new_skill_storage(app_config=config).read_custom_skill(skill_name))
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error("Failed to get custom skill %s: %s", skill_name, e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to get custom skill: {str(e)}")
+
+
+@router.put("/skills/custom/{skill_name}", response_model=CustomSkillContentResponse, summary="Edit Custom Skill")
+async def update_custom_skill(skill_name: str, request: CustomSkillUpdateRequest, config: AppConfig = Depends(get_config)) -> CustomSkillContentResponse:
+    try:
+        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
+        storage = get_or_new_skill_storage(app_config=config)
+        storage.ensure_custom_skill_is_editable(skill_name)
+        storage.validate_skill_markdown_content(skill_name, request.content)
+        scan = await scan_skill_content(request.content, executable=False, location=f"{skill_name}/{SKILL_MD_FILE}", app_config=config)
+        if scan.decision == "block":
+            raise HTTPException(status_code=400, detail=f"Security scan blocked the edit: {scan.reason}")
+        prev_content = storage.read_custom_skill(skill_name)
+        storage.write_custom_skill(skill_name, SKILL_MD_FILE, request.content)
+        storage.append_history(
+            skill_name,
+            {
+                "action": "human_edit",
+                "author": "human",
+                "thread_id": None,
+                "file_path": SKILL_MD_FILE,
+                "prev_content": prev_content,
+                "new_content": request.content,
+                "scanner": {"decision": scan.decision, "reason": scan.reason},
+            },
+        )
+        await refresh_skills_system_prompt_cache_async()
+        return await get_custom_skill(skill_name, config)
+    except HTTPException:
+        raise
+    except FileNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        logger.error("Failed to update custom skill %s: %s", skill_name, e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to update custom skill: {str(e)}")
+
+
+@router.delete("/skills/custom/{skill_name}", summary="Delete Custom Skill")
+async def delete_custom_skill(skill_name: str, config: AppConfig = Depends(get_config)) -> dict[str, bool]:
+    try:
+        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
+        storage = get_or_new_skill_storage(app_config=config)
+        storage.delete_custom_skill(
+            skill_name,
+            history_meta={
+                "action": "human_delete",
+                "author": "human",
+                "thread_id": None,
+                "file_path": SKILL_MD_FILE,
+                "prev_content": None,
+                "new_content": None,
+                "scanner": {"decision": "allow", "reason": "Deletion requested."},
+            },
+        )
+        await refresh_skills_system_prompt_cache_async()
+        return {"success": True}
+    except FileNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        logger.error("Failed to delete custom skill %s: %s", skill_name, e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to delete custom skill: {str(e)}")
+
+
+@router.get("/skills/custom/{skill_name}/history", response_model=CustomSkillHistoryResponse, summary="Get Custom Skill History")
+async def get_custom_skill_history(skill_name: str, config: AppConfig = Depends(get_config)) -> CustomSkillHistoryResponse:
+    try:
+        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
+        storage = get_or_new_skill_storage(app_config=config)
+        if not storage.custom_skill_exists(skill_name) and not storage.get_skill_history_file(skill_name).exists():
+            raise HTTPException(status_code=404, detail=f"Custom skill '{skill_name}' not found")
+        return CustomSkillHistoryResponse(history=storage.read_history(skill_name))
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error("Failed to read history for %s: %s", skill_name, e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to read history: {str(e)}")
+
+
+@router.post("/skills/custom/{skill_name}/rollback", response_model=CustomSkillContentResponse, summary="Rollback Custom Skill")
+async def rollback_custom_skill(skill_name: str, request: SkillRollbackRequest, config: AppConfig = Depends(get_config)) -> CustomSkillContentResponse:
+    try:
+        storage = get_or_new_skill_storage(app_config=config)
+        if not storage.custom_skill_exists(skill_name) and not storage.get_skill_history_file(skill_name).exists():
+            raise HTTPException(status_code=404, detail=f"Custom skill '{skill_name}' not found")
+        history = storage.read_history(skill_name)
+        if not history:
+            raise HTTPException(status_code=400, detail=f"Custom skill '{skill_name}' has no history")
+        record = history[request.history_index]
+        target_content = record.get("prev_content")
+        if target_content is None:
+            raise HTTPException(status_code=400, detail="Selected history entry has no previous content to roll back to")
+        storage.validate_skill_markdown_content(skill_name, target_content)
+        scan = await scan_skill_content(target_content, executable=False, location=f"{skill_name}/{SKILL_MD_FILE}", app_config=config)
+        skill_file = storage.get_custom_skill_file(skill_name)
+        current_content = skill_file.read_text(encoding="utf-8") if skill_file.exists() else None
+        history_entry = {
+            "action": "rollback",
+            "author": "human",
+            "thread_id": None,
+            "file_path": SKILL_MD_FILE,
+            "prev_content": current_content,
+            "new_content": target_content,
+            "rollback_from_ts": record.get("ts"),
+            "scanner": {"decision": scan.decision, "reason": scan.reason},
+        }
+        if scan.decision == "block":
+            storage.append_history(skill_name, history_entry)
+            raise HTTPException(status_code=400, detail=f"Rollback blocked by security scanner: {scan.reason}")
+        storage.write_custom_skill(skill_name, SKILL_MD_FILE, target_content)
+        storage.append_history(skill_name, history_entry)
+        await refresh_skills_system_prompt_cache_async()
+        return await get_custom_skill(skill_name, config)
+    except HTTPException:
+        raise
+    except IndexError:
+        raise HTTPException(status_code=400, detail="history_index is out of range")
+    except FileNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        logger.error("Failed to roll back custom skill %s: %s", skill_name, e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to roll back custom skill: {str(e)}")
+
+
+@router.get(
+    "/skills/{skill_name}",
+    response_model=SkillResponse,
+    summary="Get Skill Details",
+    description="Retrieve detailed information about a specific skill by its name.",
+)
+async def get_skill(skill_name: str, config: AppConfig = Depends(get_config)) -> SkillResponse:
+    try:
+        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
+        skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
+        skill = next((s for s in skills if s.name == skill_name), None)
+
+        if skill is None:
+            raise HTTPException(status_code=404, detail=f"Skill '{skill_name}' not found")
+
+        return _skill_to_response(skill)
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Failed to get skill {skill_name}: {e}", exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to get skill: {str(e)}")
+
+
+@router.put(
+    "/skills/{skill_name}",
+    response_model=SkillResponse,
+    summary="Update Skill",
+    description="Update a skill's enabled status by modifying the extensions_config.json file.",
+)
+async def update_skill(skill_name: str, request: SkillUpdateRequest, config: AppConfig = Depends(get_config)) -> SkillResponse:
+    try:
+        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
+        skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
+        skill = next((s for s in skills if s.name == skill_name), None)
+
+        if skill is None:
+            raise HTTPException(status_code=404, detail=f"Skill '{skill_name}' not found")
+
+        config_path = ExtensionsConfig.resolve_config_path()
+        if config_path is None:
+            config_path = Path.cwd().parent / "extensions_config.json"
+            logger.info(f"No existing extensions config found. Creating new config at: {config_path}")
+
+        extensions_config = get_extensions_config()
+        extensions_config.skills[skill_name] = SkillStateConfig(enabled=request.enabled)
+
+        config_data = {
+            "mcpServers": {name: server.model_dump() for name, server in extensions_config.mcp_servers.items()},
+            "skills": {name: {"enabled": skill_config.enabled} for name, skill_config in extensions_config.skills.items()},
+        }
+
+        with open(config_path, "w", encoding="utf-8") as f:
+            json.dump(config_data, f, indent=2)
+
+        logger.info(f"Skills configuration updated and saved to: {config_path}")
+        reload_extensions_config()
+        await refresh_skills_system_prompt_cache_async()
+
+        skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
+        updated_skill = next((s for s in skills if s.name == skill_name), None)
+
+        if updated_skill is None:
+            raise HTTPException(status_code=500, detail=f"Failed to reload skill '{skill_name}' after update")
+
+        logger.info(f"Skill '{skill_name}' enabled status updated to {request.enabled}")
+        return _skill_to_response(updated_skill)
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Failed to update skill {skill_name}: {e}", exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to update skill: {str(e)}")

offline-backend-20260512/backend/app/gateway/routers/suggestions.py

@@ -0,0 +1,141 @@
+import json
+import logging
+
+from fastapi import APIRouter, Depends, Request
+from langchain_core.messages import HumanMessage, SystemMessage
+from pydantic import BaseModel, Field
+
+from app.gateway.authz import require_permission
+from app.gateway.deps import get_config
+from deerflow.config.app_config import AppConfig
+from deerflow.models import create_chat_model
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api", tags=["suggestions"])
+
+
+class SuggestionMessage(BaseModel):
+    role: str = Field(..., description="Message role: user|assistant")
+    content: str = Field(..., description="Message content as plain text")
+
+
+class SuggestionsRequest(BaseModel):
+    messages: list[SuggestionMessage] = Field(..., description="Recent conversation messages")
+    n: int = Field(default=3, ge=1, le=5, description="Number of suggestions to generate")
+    model_name: str | None = Field(default=None, description="Optional model override")
+
+
+class SuggestionsResponse(BaseModel):
+    suggestions: list[str] = Field(default_factory=list, description="Suggested follow-up questions")
+
+
+def _strip_markdown_code_fence(text: str) -> str:
+    stripped = text.strip()
+    if not stripped.startswith("```"):
+        return stripped
+    lines = stripped.splitlines()
+    if len(lines) >= 3 and lines[0].startswith("```") and lines[-1].startswith("```"):
+        return "\n".join(lines[1:-1]).strip()
+    return stripped
+
+
+def _parse_json_string_list(text: str) -> list[str] | None:
+    candidate = _strip_markdown_code_fence(text)
+    start = candidate.find("[")
+    end = candidate.rfind("]")
+    if start == -1 or end == -1 or end <= start:
+        return None
+    candidate = candidate[start : end + 1]
+    try:
+        data = json.loads(candidate)
+    except Exception:
+        return None
+    if not isinstance(data, list):
+        return None
+    out: list[str] = []
+    for item in data:
+        if not isinstance(item, str):
+            continue
+        s = item.strip()
+        if not s:
+            continue
+        out.append(s)
+    return out
+
+
+def _extract_response_text(content: object) -> str:
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts: list[str] = []
+        for block in content:
+            if isinstance(block, str):
+                parts.append(block)
+            elif isinstance(block, dict) and block.get("type") in {"text", "output_text"}:
+                text = block.get("text")
+                if isinstance(text, str):
+                    parts.append(text)
+        return "\n".join(parts) if parts else ""
+    if content is None:
+        return ""
+    return str(content)
+
+
+def _format_conversation(messages: list[SuggestionMessage]) -> str:
+    parts: list[str] = []
+    for m in messages:
+        role = m.role.strip().lower()
+        if role in ("user", "human"):
+            parts.append(f"User: {m.content.strip()}")
+        elif role in ("assistant", "ai"):
+            parts.append(f"Assistant: {m.content.strip()}")
+        else:
+            parts.append(f"{m.role}: {m.content.strip()}")
+    return "\n".join(parts).strip()
+
+
+@router.post(
+    "/threads/{thread_id}/suggestions",
+    response_model=SuggestionsResponse,
+    summary="Generate Follow-up Questions",
+    description="Generate short follow-up questions a user might ask next, based on recent conversation context.",
+)
+@require_permission("threads", "read", owner_check=True)
+async def generate_suggestions(
+    thread_id: str,
+    body: SuggestionsRequest,
+    request: Request,
+    config: AppConfig = Depends(get_config),
+) -> SuggestionsResponse:
+    if not body.messages:
+        return SuggestionsResponse(suggestions=[])
+
+    n = body.n
+    conversation = _format_conversation(body.messages)
+    if not conversation:
+        return SuggestionsResponse(suggestions=[])
+
+    system_instruction = (
+        "You are generating follow-up questions to help the user continue the conversation.\n"
+        f"Based on the conversation below, produce EXACTLY {n} short questions the user might ask next.\n"
+        "Requirements:\n"
+        "- Questions must be relevant to the preceding conversation.\n"
+        "- Questions must be written in the same language as the user.\n"
+        "- Keep each question concise (ideally <= 20 words / <= 40 Chinese characters).\n"
+        "- Do NOT include numbering, markdown, or any extra text.\n"
+        "- Output MUST be a JSON array of strings only.\n"
+    )
+    user_content = f"Conversation Context:\n{conversation}\n\nGenerate {n} follow-up questions"
+
+    try:
+        model = create_chat_model(name=body.model_name, thinking_enabled=False, app_config=config)
+        response = await model.ainvoke([SystemMessage(content=system_instruction), HumanMessage(content=user_content)], config={"run_name": "suggest_agent"})
+        raw = _extract_response_text(response.content)
+        suggestions = _parse_json_string_list(raw) or []
+        cleaned = [s.replace("\n", " ").strip() for s in suggestions if s.strip()]
+        cleaned = cleaned[:n]
+        return SuggestionsResponse(suggestions=cleaned)
+    except Exception as exc:
+        logger.exception("Failed to generate suggestions: thread_id=%s err=%s", thread_id, exc)
+        return SuggestionsResponse(suggestions=[])

offline-backend-20260512/backend/app/gateway/routers/thread_runs.py

@@ -0,0 +1,377 @@
+"""Runs endpoints — create, stream, wait, cancel.
+
+Implements the LangGraph Platform runs API on top of
+:class:`deerflow.agents.runs.RunManager` and
+:class:`deerflow.agents.stream_bridge.StreamBridge`.
+
+SSE format is aligned with the LangGraph Platform protocol so that
+the ``useStream`` React hook from ``@langchain/langgraph-sdk/react``
+works without modification.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any, Literal
+
+from fastapi import APIRouter, HTTPException, Query, Request
+from fastapi.responses import Response, StreamingResponse
+from pydantic import BaseModel, Field
+
+from app.gateway.authz import require_permission
+from app.gateway.deps import get_checkpointer, get_current_user, get_feedback_repo, get_run_event_store, get_run_manager, get_run_store, get_stream_bridge
+from app.gateway.services import sse_consumer, start_run
+from deerflow.runtime import RunRecord, serialize_channel_values
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/api/threads", tags=["runs"])
+
+
+# ---------------------------------------------------------------------------
+# Request / response models
+# ---------------------------------------------------------------------------
+
+
+class RunCreateRequest(BaseModel):
+    assistant_id: str | None = Field(default=None, description="Agent / assistant to use")
+    input: dict[str, Any] | None = Field(default=None, description="Graph input (e.g. {messages: [...]})")
+    command: dict[str, Any] | None = Field(default=None, description="LangGraph Command")
+    metadata: dict[str, Any] | None = Field(default=None, description="Run metadata")
+    config: dict[str, Any] | None = Field(default=None, description="RunnableConfig overrides")
+    context: dict[str, Any] | None = Field(default=None, description="DeerFlow context overrides (model_name, thinking_enabled, etc.)")
+    webhook: str | None = Field(default=None, description="Completion callback URL")
+    checkpoint_id: str | None = Field(default=None, description="Resume from checkpoint")
+    checkpoint: dict[str, Any] | None = Field(default=None, description="Full checkpoint object")
+    interrupt_before: list[str] | Literal["*"] | None = Field(default=None, description="Nodes to interrupt before")
+    interrupt_after: list[str] | Literal["*"] | None = Field(default=None, description="Nodes to interrupt after")
+    stream_mode: list[str] | str | None = Field(default=None, description="Stream mode(s)")
+    stream_subgraphs: bool = Field(default=False, description="Include subgraph events")
+    stream_resumable: bool | None = Field(default=None, description="SSE resumable mode")
+    on_disconnect: Literal["cancel", "continue"] = Field(default="cancel", description="Behaviour on SSE disconnect")
+    on_completion: Literal["delete", "keep"] = Field(default="keep", description="Delete temp thread on completion")
+    multitask_strategy: Literal["reject", "rollback", "interrupt", "enqueue"] = Field(default="reject", description="Concurrency strategy")
+    after_seconds: float | None = Field(default=None, description="Delayed execution")
+    if_not_exists: Literal["reject", "create"] = Field(default="create", description="Thread creation policy")
+    feedback_keys: list[str] | None = Field(default=None, description="LangSmith feedback keys")
+
+
+class RunResponse(BaseModel):
+    run_id: str
+    thread_id: str
+    assistant_id: str | None = None
+    status: str
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    kwargs: dict[str, Any] = Field(default_factory=dict)
+    multitask_strategy: str = "reject"
+    created_at: str = ""
+    updated_at: str = ""
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _record_to_response(record: RunRecord) -> RunResponse:
+    return RunResponse(
+        run_id=record.run_id,
+        thread_id=record.thread_id,
+        assistant_id=record.assistant_id,
+        status=record.status.value,
+        metadata=record.metadata,
+        kwargs=record.kwargs,
+        multitask_strategy=record.multitask_strategy,
+        created_at=record.created_at,
+        updated_at=record.updated_at,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Endpoints
+# ---------------------------------------------------------------------------
+
+
+@router.post("/{thread_id}/runs", response_model=RunResponse)
+@require_permission("runs", "create", owner_check=True, require_existing=True)
+async def create_run(thread_id: str, body: RunCreateRequest, request: Request) -> RunResponse:
+    """Create a background run (returns immediately)."""
+    record = await start_run(body, thread_id, request)
+    return _record_to_response(record)
+
+
+@router.post("/{thread_id}/runs/stream")
+@require_permission("runs", "create", owner_check=True, require_existing=True)
+async def stream_run(thread_id: str, body: RunCreateRequest, request: Request) -> StreamingResponse:
+    """Create a run and stream events via SSE.
+
+    The response includes a ``Content-Location`` header with the run's
+    resource URL, matching the LangGraph Platform protocol.  The
+    ``useStream`` React hook uses this to extract run metadata.
+    """
+    bridge = get_stream_bridge(request)
+    run_mgr = get_run_manager(request)
+    record = await start_run(body, thread_id, request)
+
+    return StreamingResponse(
+        sse_consumer(bridge, record, request, run_mgr),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+            "X-Accel-Buffering": "no",
+            # LangGraph Platform includes run metadata in this header.
+            # The SDK uses a greedy regex to extract the run id from this path,
+            # so it must point at the canonical run resource without extra suffixes.
+            "Content-Location": f"/api/threads/{thread_id}/runs/{record.run_id}",
+        },
+    )
+
+
+@router.post("/{thread_id}/runs/wait", response_model=dict)
+@require_permission("runs", "create", owner_check=True, require_existing=True)
+async def wait_run(thread_id: str, body: RunCreateRequest, request: Request) -> dict:
+    """Create a run and block until it completes, returning the final state."""
+    record = await start_run(body, thread_id, request)
+
+    if record.task is not None:
+        try:
+            await record.task
+        except asyncio.CancelledError:
+            pass
+
+    checkpointer = get_checkpointer(request)
+    config = {"configurable": {"thread_id": thread_id}}
+    try:
+        checkpoint_tuple = await checkpointer.aget_tuple(config)
+        if checkpoint_tuple is not None:
+            checkpoint = getattr(checkpoint_tuple, "checkpoint", {}) or {}
+            channel_values = checkpoint.get("channel_values", {})
+            return serialize_channel_values(channel_values)
+    except Exception:
+        logger.exception("Failed to fetch final state for run %s", record.run_id)
+
+    return {"status": record.status.value, "error": record.error}
+
+
+@router.get("/{thread_id}/runs", response_model=list[RunResponse])
+@require_permission("runs", "read", owner_check=True)
+async def list_runs(thread_id: str, request: Request) -> list[RunResponse]:
+    """List all runs for a thread."""
+    run_mgr = get_run_manager(request)
+    records = await run_mgr.list_by_thread(thread_id)
+    return [_record_to_response(r) for r in records]
+
+
+@router.get("/{thread_id}/runs/{run_id}", response_model=RunResponse)
+@require_permission("runs", "read", owner_check=True)
+async def get_run(thread_id: str, run_id: str, request: Request) -> RunResponse:
+    """Get details of a specific run."""
+    run_mgr = get_run_manager(request)
+    record = run_mgr.get(run_id)
+    if record is None or record.thread_id != thread_id:
+        raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
+    return _record_to_response(record)
+
+
+@router.post("/{thread_id}/runs/{run_id}/cancel")
+@require_permission("runs", "cancel", owner_check=True, require_existing=True)
+async def cancel_run(
+    thread_id: str,
+    run_id: str,
+    request: Request,
+    wait: bool = Query(default=False, description="Block until run completes after cancel"),
+    action: Literal["interrupt", "rollback"] = Query(default="interrupt", description="Cancel action"),
+) -> Response:
+    """Cancel a running or pending run.
+
+    - action=interrupt: Stop execution, keep current checkpoint (can be resumed)
+    - action=rollback: Stop execution, revert to pre-run checkpoint state
+    - wait=true: Block until the run fully stops, return 204
+    - wait=false: Return immediately with 202
+    """
+    run_mgr = get_run_manager(request)
+    record = run_mgr.get(run_id)
+    if record is None or record.thread_id != thread_id:
+        raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
+
+    cancelled = await run_mgr.cancel(run_id, action=action)
+    if not cancelled:
+        raise HTTPException(
+            status_code=409,
+            detail=f"Run {run_id} is not cancellable (status: {record.status.value})",
+        )
+
+    if wait and record.task is not None:
+        try:
+            await record.task
+        except asyncio.CancelledError:
+            pass
+        return Response(status_code=204)
+
+    return Response(status_code=202)
+
+
+@router.get("/{thread_id}/runs/{run_id}/join")
+@require_permission("runs", "read", owner_check=True)
+async def join_run(thread_id: str, run_id: str, request: Request) -> StreamingResponse:
+    """Join an existing run's SSE stream."""
+    bridge = get_stream_bridge(request)
+    run_mgr = get_run_manager(request)
+    record = run_mgr.get(run_id)
+    if record is None or record.thread_id != thread_id:
+        raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
+
+    return StreamingResponse(
+        sse_consumer(bridge, record, request, run_mgr),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+            "X-Accel-Buffering": "no",
+        },
+    )
+
+
+@router.api_route("/{thread_id}/runs/{run_id}/stream", methods=["GET", "POST"], response_model=None)
+@require_permission("runs", "read", owner_check=True)
+async def stream_existing_run(
+    thread_id: str,
+    run_id: str,
+    request: Request,
+    action: Literal["interrupt", "rollback"] | None = Query(default=None, description="Cancel action"),
+    wait: int = Query(default=0, description="Block until cancelled (1) or return immediately (0)"),
+):
+    """Join an existing run's SSE stream (GET), or cancel-then-stream (POST).
+
+    The LangGraph SDK's ``joinStream`` and ``useStream`` stop button both use
+    ``POST`` to this endpoint.  When ``action=interrupt`` or ``action=rollback``
+    is present the run is cancelled first; the response then streams any
+    remaining buffered events so the client observes a clean shutdown.
+    """
+    run_mgr = get_run_manager(request)
+    record = run_mgr.get(run_id)
+    if record is None or record.thread_id != thread_id:
+        raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
+
+    # Cancel if an action was requested (stop-button / interrupt flow)
+    if action is not None:
+        cancelled = await run_mgr.cancel(run_id, action=action)
+        if cancelled and wait and record.task is not None:
+            try:
+                await record.task
+            except (asyncio.CancelledError, Exception):
+                pass
+            return Response(status_code=204)
+
+    bridge = get_stream_bridge(request)
+    return StreamingResponse(
+        sse_consumer(bridge, record, request, run_mgr),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+            "X-Accel-Buffering": "no",
+        },
+    )
+
+
+# ---------------------------------------------------------------------------
+# Messages / Events / Token usage endpoints
+# ---------------------------------------------------------------------------
+
+
+@router.get("/{thread_id}/messages")
+@require_permission("runs", "read", owner_check=True)
+async def list_thread_messages(
+    thread_id: str,
+    request: Request,
+    limit: int = Query(default=50, le=200),
+    before_seq: int | None = Query(default=None),
+    after_seq: int | None = Query(default=None),
+) -> list[dict]:
+    """Return displayable messages for a thread (across all runs), with feedback attached."""
+    event_store = get_run_event_store(request)
+    messages = await event_store.list_messages(thread_id, limit=limit, before_seq=before_seq, after_seq=after_seq)
+
+    # Attach feedback to the last AI message of each run
+    feedback_repo = get_feedback_repo(request)
+    user_id = await get_current_user(request)
+    feedback_map = await feedback_repo.list_by_thread_grouped(thread_id, user_id=user_id)
+
+    # Find the last ai_message per run_id
+    last_ai_per_run: dict[str, int] = {}  # run_id -> index in messages list
+    for i, msg in enumerate(messages):
+        if msg.get("event_type") == "ai_message":
+            last_ai_per_run[msg["run_id"]] = i
+
+    # Attach feedback field
+    last_ai_indices = set(last_ai_per_run.values())
+    for i, msg in enumerate(messages):
+        if i in last_ai_indices:
+            run_id = msg["run_id"]
+            fb = feedback_map.get(run_id)
+            msg["feedback"] = (
+                {
+                    "feedback_id": fb["feedback_id"],
+                    "rating": fb["rating"],
+                    "comment": fb.get("comment"),
+                }
+                if fb
+                else None
+            )
+        else:
+            msg["feedback"] = None
+
+    return messages
+
+
+@router.get("/{thread_id}/runs/{run_id}/messages")
+@require_permission("runs", "read", owner_check=True)
+async def list_run_messages(
+    thread_id: str,
+    run_id: str,
+    request: Request,
+    limit: int = Query(default=50, le=200, ge=1),
+    before_seq: int | None = Query(default=None),
+    after_seq: int | None = Query(default=None),
+) -> dict:
+    """Return paginated messages for a specific run.
+
+    Response: { data: [...], has_more: bool }
+    """
+    event_store = get_run_event_store(request)
+    rows = await event_store.list_messages_by_run(
+        thread_id,
+        run_id,
+        limit=limit + 1,
+        before_seq=before_seq,
+        after_seq=after_seq,
+    )
+    has_more = len(rows) > limit
+    data = rows[:limit] if has_more else rows
+    return {"data": data, "has_more": has_more}
+
+
+@router.get("/{thread_id}/runs/{run_id}/events")
+@require_permission("runs", "read", owner_check=True)
+async def list_run_events(
+    thread_id: str,
+    run_id: str,
+    request: Request,
+    event_types: str | None = Query(default=None),
+    limit: int = Query(default=500, le=2000),
+) -> list[dict]:
+    """Return the full event stream for a run (debug/audit)."""
+    event_store = get_run_event_store(request)
+    types = event_types.split(",") if event_types else None
+    return await event_store.list_events(thread_id, run_id, event_types=types, limit=limit)
+
+
+@router.get("/{thread_id}/token-usage")
+@require_permission("threads", "read", owner_check=True)
+async def thread_token_usage(thread_id: str, request: Request) -> dict:
+    """Thread-level token usage aggregation."""
+    run_store = get_run_store(request)
+    agg = await run_store.aggregate_tokens_by_thread(thread_id)
+    return {"thread_id": thread_id, **agg}

offline-backend-20260512/backend/app/gateway/routers/threads.py

@@ -0,0 +1,622 @@
+"""Thread CRUD, state, and history endpoints.
+
+Combines the existing thread-local filesystem cleanup with LangGraph
+Platform-compatible thread management backed by the checkpointer.
+
+Channel values returned in state responses are serialized through
+:func:`deerflow.runtime.serialization.serialize_channel_values` to
+ensure LangChain message objects are converted to JSON-safe dicts
+matching the LangGraph Platform wire format expected by the
+``useStream`` React hook.
+"""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from typing import Any
+
+from fastapi import APIRouter, HTTPException, Request
+from langgraph.checkpoint.base import empty_checkpoint
+from pydantic import BaseModel, Field, field_validator
+
+from app.gateway.authz import require_permission
+from app.gateway.deps import get_checkpointer
+from app.gateway.utils import sanitize_log_param
+from deerflow.config.paths import Paths, get_paths
+from deerflow.runtime import serialize_channel_values
+from deerflow.runtime.user_context import get_effective_user_id
+from deerflow.utils.time import coerce_iso, now_iso
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/api/threads", tags=["threads"])
+
+
+# Metadata keys that the server controls; clients are not allowed to set
+# them. Pydantic ``@field_validator("metadata")`` strips them on every
+# inbound model below so a malicious client cannot reflect a forged
+# owner identity through the API surface. Defense-in-depth — the
+# row-level invariant is still ``threads_meta.user_id`` populated from
+# the auth contextvar; this list closes the metadata-blob echo gap.
+_SERVER_RESERVED_METADATA_KEYS: frozenset[str] = frozenset({"owner_id", "user_id"})
+
+
+def _strip_reserved_metadata(metadata: dict[str, Any] | None) -> dict[str, Any]:
+    """Return ``metadata`` with server-controlled keys removed."""
+    if not metadata:
+        return metadata or {}
+    return {k: v for k, v in metadata.items() if k not in _SERVER_RESERVED_METADATA_KEYS}
+
+
+# ---------------------------------------------------------------------------
+# Response / request models
+# ---------------------------------------------------------------------------
+
+
+class ThreadDeleteResponse(BaseModel):
+    """Response model for thread cleanup."""
+
+    success: bool
+    message: str
+
+
+class ThreadResponse(BaseModel):
+    """Response model for a single thread."""
+
+    thread_id: str = Field(description="Unique thread identifier")
+    status: str = Field(default="idle", description="Thread status: idle, busy, interrupted, error")
+    created_at: str = Field(default="", description="ISO timestamp")
+    updated_at: str = Field(default="", description="ISO timestamp")
+    metadata: dict[str, Any] = Field(default_factory=dict, description="Thread metadata")
+    values: dict[str, Any] = Field(default_factory=dict, description="Current state channel values")
+    interrupts: dict[str, Any] = Field(default_factory=dict, description="Pending interrupts")
+
+
+class ThreadCreateRequest(BaseModel):
+    """Request body for creating a thread."""
+
+    thread_id: str | None = Field(default=None, description="Optional thread ID (auto-generated if omitted)")
+    assistant_id: str | None = Field(default=None, description="Associate thread with an assistant")
+    metadata: dict[str, Any] = Field(default_factory=dict, description="Initial metadata")
+
+    _strip_reserved = field_validator("metadata")(classmethod(lambda cls, v: _strip_reserved_metadata(v)))
+
+
+class ThreadSearchRequest(BaseModel):
+    """Request body for searching threads."""
+
+    metadata: dict[str, Any] = Field(default_factory=dict, description="Metadata filter (exact match)")
+    limit: int = Field(default=100, ge=1, le=1000, description="Maximum results")
+    offset: int = Field(default=0, ge=0, description="Pagination offset")
+    status: str | None = Field(default=None, description="Filter by thread status")
+
+
+class ThreadStateResponse(BaseModel):
+    """Response model for thread state."""
+
+    values: dict[str, Any] = Field(default_factory=dict, description="Current channel values")
+    next: list[str] = Field(default_factory=list, description="Next tasks to execute")
+    metadata: dict[str, Any] = Field(default_factory=dict, description="Checkpoint metadata")
+    checkpoint: dict[str, Any] = Field(default_factory=dict, description="Checkpoint info")
+    checkpoint_id: str | None = Field(default=None, description="Current checkpoint ID")
+    parent_checkpoint_id: str | None = Field(default=None, description="Parent checkpoint ID")
+    created_at: str | None = Field(default=None, description="Checkpoint timestamp")
+    tasks: list[dict[str, Any]] = Field(default_factory=list, description="Interrupted task details")
+
+
+class ThreadPatchRequest(BaseModel):
+    """Request body for patching thread metadata."""
+
+    metadata: dict[str, Any] = Field(default_factory=dict, description="Metadata to merge")
+
+    _strip_reserved = field_validator("metadata")(classmethod(lambda cls, v: _strip_reserved_metadata(v)))
+
+
+class ThreadStateUpdateRequest(BaseModel):
+    """Request body for updating thread state (human-in-the-loop resume)."""
+
+    values: dict[str, Any] | None = Field(default=None, description="Channel values to merge")
+    checkpoint_id: str | None = Field(default=None, description="Checkpoint to branch from")
+    checkpoint: dict[str, Any] | None = Field(default=None, description="Full checkpoint object")
+    as_node: str | None = Field(default=None, description="Node identity for the update")
+
+
+class HistoryEntry(BaseModel):
+    """Single checkpoint history entry."""
+
+    checkpoint_id: str
+    parent_checkpoint_id: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    values: dict[str, Any] = Field(default_factory=dict)
+    created_at: str | None = None
+    next: list[str] = Field(default_factory=list)
+
+
+class ThreadHistoryRequest(BaseModel):
+    """Request body for checkpoint history."""
+
+    limit: int = Field(default=10, ge=1, le=100, description="Maximum entries")
+    before: str | None = Field(default=None, description="Cursor for pagination")
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _delete_thread_data(thread_id: str, paths: Paths | None = None, *, user_id: str | None = None) -> ThreadDeleteResponse:
+    """Delete local persisted filesystem data for a thread."""
+    path_manager = paths or get_paths()
+    try:
+        path_manager.delete_thread_dir(thread_id, user_id=user_id)
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    except FileNotFoundError:
+        # Not critical — thread data may not exist on disk
+        logger.debug("No local thread data to delete for %s", sanitize_log_param(thread_id))
+        return ThreadDeleteResponse(success=True, message=f"No local data for {thread_id}")
+    except Exception as exc:
+        logger.exception("Failed to delete thread data for %s", sanitize_log_param(thread_id))
+        raise HTTPException(status_code=500, detail="Failed to delete local thread data.") from exc
+
+    logger.info("Deleted local thread data for %s", sanitize_log_param(thread_id))
+    return ThreadDeleteResponse(success=True, message=f"Deleted local thread data for {thread_id}")
+
+
+def _derive_thread_status(checkpoint_tuple) -> str:
+    """Derive thread status from checkpoint metadata."""
+    if checkpoint_tuple is None:
+        return "idle"
+    pending_writes = getattr(checkpoint_tuple, "pending_writes", None) or []
+
+    # Check for error in pending writes
+    for pw in pending_writes:
+        if len(pw) >= 2 and pw[1] == "__error__":
+            return "error"
+
+    # Check for pending next tasks (indicates interrupt)
+    tasks = getattr(checkpoint_tuple, "tasks", None)
+    if tasks:
+        return "interrupted"
+
+    return "idle"
+
+
+# ---------------------------------------------------------------------------
+# Endpoints
+# ---------------------------------------------------------------------------
+
+
+@router.delete("/{thread_id}", response_model=ThreadDeleteResponse)
+@require_permission("threads", "delete", owner_check=True, require_existing=True)
+async def delete_thread_data(thread_id: str, request: Request) -> ThreadDeleteResponse:
+    """Delete local persisted filesystem data for a thread.
+
+    Cleans DeerFlow-managed thread directories, removes checkpoint data,
+    and removes the thread_meta row from the configured ThreadMetaStore
+    (sqlite or memory).
+    """
+    from app.gateway.deps import get_thread_store
+
+    # Clean local filesystem
+    response = _delete_thread_data(thread_id, user_id=get_effective_user_id())
+
+    # Remove checkpoints (best-effort)
+    checkpointer = getattr(request.app.state, "checkpointer", None)
+    if checkpointer is not None:
+        try:
+            if hasattr(checkpointer, "adelete_thread"):
+                await checkpointer.adelete_thread(thread_id)
+        except Exception:
+            logger.debug("Could not delete checkpoints for thread %s (not critical)", sanitize_log_param(thread_id))
+
+    # Remove thread_meta row (best-effort) — required for sqlite backend
+    # so the deleted thread no longer appears in /threads/search.
+    try:
+        thread_store = get_thread_store(request)
+        await thread_store.delete(thread_id)
+    except Exception:
+        logger.debug("Could not delete thread_meta for %s (not critical)", sanitize_log_param(thread_id))
+
+    return response
+
+
+@router.post("", response_model=ThreadResponse)
+async def create_thread(body: ThreadCreateRequest, request: Request) -> ThreadResponse:
+    """Create a new thread.
+
+    Writes a thread_meta record (so the thread appears in /threads/search)
+    and an empty checkpoint (so state endpoints work immediately).
+    Idempotent: returns the existing record when ``thread_id`` already exists.
+    """
+    from app.gateway.deps import get_thread_store
+
+    checkpointer = get_checkpointer(request)
+    thread_store = get_thread_store(request)
+    thread_id = body.thread_id or str(uuid.uuid4())
+    now = now_iso()
+    # ``body.metadata`` is already stripped of server-reserved keys by
+    # ``ThreadCreateRequest._strip_reserved`` — see the model definition.
+
+    # Idempotency: return existing record when already present
+    existing_record = await thread_store.get(thread_id)
+    if existing_record is not None:
+        return ThreadResponse(
+            thread_id=thread_id,
+            status=existing_record.get("status", "idle"),
+            created_at=coerce_iso(existing_record.get("created_at", "")),
+            updated_at=coerce_iso(existing_record.get("updated_at", "")),
+            metadata=existing_record.get("metadata", {}),
+        )
+
+    # Write thread_meta so the thread appears in /threads/search immediately
+    try:
+        await thread_store.create(
+            thread_id,
+            assistant_id=getattr(body, "assistant_id", None),
+            metadata=body.metadata,
+        )
+    except Exception:
+        logger.exception("Failed to write thread_meta for %s", sanitize_log_param(thread_id))
+        raise HTTPException(status_code=500, detail="Failed to create thread")
+
+    # Write an empty checkpoint so state endpoints work immediately
+    config = {"configurable": {"thread_id": thread_id, "checkpoint_ns": ""}}
+    try:
+        ckpt_metadata = {
+            "step": -1,
+            "source": "input",
+            "writes": None,
+            "parents": {},
+            **body.metadata,
+            "created_at": now,
+        }
+        await checkpointer.aput(config, empty_checkpoint(), ckpt_metadata, {})
+    except Exception:
+        logger.exception("Failed to create checkpoint for thread %s", sanitize_log_param(thread_id))
+        raise HTTPException(status_code=500, detail="Failed to create thread")
+
+    logger.info("Thread created: %s", sanitize_log_param(thread_id))
+    return ThreadResponse(
+        thread_id=thread_id,
+        status="idle",
+        created_at=now,
+        updated_at=now,
+        metadata=body.metadata,
+    )
+
+
+@router.post("/search", response_model=list[ThreadResponse])
+async def search_threads(body: ThreadSearchRequest, request: Request) -> list[ThreadResponse]:
+    """Search and list threads.
+
+    Delegates to the configured ThreadMetaStore implementation
+    (SQL-backed for sqlite/postgres, Store-backed for memory mode).
+    """
+    from app.gateway.deps import get_thread_store
+
+    repo = get_thread_store(request)
+    rows = await repo.search(
+        metadata=body.metadata or None,
+        status=body.status,
+        limit=body.limit,
+        offset=body.offset,
+    )
+    return [
+        ThreadResponse(
+            thread_id=r["thread_id"],
+            status=r.get("status", "idle"),
+            # ``coerce_iso`` heals legacy unix-second values that
+            # ``MemoryThreadMetaStore`` historically wrote with ``time.time()``;
+            # SQL-backed rows already arrive as ISO strings and pass through.
+            created_at=coerce_iso(r.get("created_at", "")),
+            updated_at=coerce_iso(r.get("updated_at", "")),
+            metadata=r.get("metadata", {}),
+            values={"title": r["display_name"]} if r.get("display_name") else {},
+            interrupts={},
+        )
+        for r in rows
+    ]
+
+
+@router.patch("/{thread_id}", response_model=ThreadResponse)
+@require_permission("threads", "write", owner_check=True, require_existing=True)
+async def patch_thread(thread_id: str, body: ThreadPatchRequest, request: Request) -> ThreadResponse:
+    """Merge metadata into a thread record."""
+    from app.gateway.deps import get_thread_store
+
+    thread_store = get_thread_store(request)
+    record = await thread_store.get(thread_id)
+    if record is None:
+        raise HTTPException(status_code=404, detail=f"Thread {thread_id} not found")
+
+    # ``body.metadata`` already stripped by ``ThreadPatchRequest._strip_reserved``.
+    try:
+        await thread_store.update_metadata(thread_id, body.metadata)
+    except Exception:
+        logger.exception("Failed to patch thread %s", sanitize_log_param(thread_id))
+        raise HTTPException(status_code=500, detail="Failed to update thread")
+
+    # Re-read to get the merged metadata + refreshed updated_at
+    record = await thread_store.get(thread_id) or record
+    return ThreadResponse(
+        thread_id=thread_id,
+        status=record.get("status", "idle"),
+        created_at=coerce_iso(record.get("created_at", "")),
+        updated_at=coerce_iso(record.get("updated_at", "")),
+        metadata=record.get("metadata", {}),
+    )
+
+
+@router.get("/{thread_id}", response_model=ThreadResponse)
+@require_permission("threads", "read", owner_check=True)
+async def get_thread(thread_id: str, request: Request) -> ThreadResponse:
+    """Get thread info.
+
+    Reads metadata from the ThreadMetaStore and derives the accurate
+    execution status from the checkpointer.  Falls back to the checkpointer
+    alone for threads that pre-date ThreadMetaStore adoption (backward compat).
+    """
+    from app.gateway.deps import get_thread_store
+
+    thread_store = get_thread_store(request)
+    checkpointer = get_checkpointer(request)
+
+    record: dict | None = await thread_store.get(thread_id)
+
+    # Derive accurate status from the checkpointer
+    config = {"configurable": {"thread_id": thread_id, "checkpoint_ns": ""}}
+    try:
+        checkpoint_tuple = await checkpointer.aget_tuple(config)
+    except Exception:
+        logger.exception("Failed to get checkpoint for thread %s", sanitize_log_param(thread_id))
+        raise HTTPException(status_code=500, detail="Failed to get thread")
+
+    if record is None and checkpoint_tuple is None:
+        raise HTTPException(status_code=404, detail=f"Thread {thread_id} not found")
+
+    # If the thread exists in the checkpointer but not in thread_meta (e.g.
+    # legacy data created before thread_meta adoption), synthesize a minimal
+    # record from the checkpoint metadata.
+    if record is None and checkpoint_tuple is not None:
+        ckpt_meta = getattr(checkpoint_tuple, "metadata", {}) or {}
+        record = {
+            "thread_id": thread_id,
+            "status": "idle",
+            "created_at": coerce_iso(ckpt_meta.get("created_at", "")),
+            "updated_at": coerce_iso(ckpt_meta.get("updated_at", ckpt_meta.get("created_at", ""))),
+            "metadata": {k: v for k, v in ckpt_meta.items() if k not in ("created_at", "updated_at", "step", "source", "writes", "parents")},
+        }
+
+    if record is None:
+        raise HTTPException(status_code=404, detail=f"Thread {thread_id} not found")
+
+    status = _derive_thread_status(checkpoint_tuple) if checkpoint_tuple is not None else record.get("status", "idle")
+    checkpoint = getattr(checkpoint_tuple, "checkpoint", {}) or {} if checkpoint_tuple is not None else {}
+    channel_values = checkpoint.get("channel_values", {})
+
+    return ThreadResponse(
+        thread_id=thread_id,
+        status=status,
+        created_at=coerce_iso(record.get("created_at", "")),
+        updated_at=coerce_iso(record.get("updated_at", "")),
+        metadata=record.get("metadata", {}),
+        values=serialize_channel_values(channel_values),
+    )
+
+
+# ---------------------------------------------------------------------------
+@router.get("/{thread_id}/state", response_model=ThreadStateResponse)
+@require_permission("threads", "read", owner_check=True)
+async def get_thread_state(thread_id: str, request: Request) -> ThreadStateResponse:
+    """Get the latest state snapshot for a thread.
+
+    Channel values are serialized to ensure LangChain message objects
+    are converted to JSON-safe dicts.
+    """
+    checkpointer = get_checkpointer(request)
+
+    config = {"configurable": {"thread_id": thread_id, "checkpoint_ns": ""}}
+    try:
+        checkpoint_tuple = await checkpointer.aget_tuple(config)
+    except Exception:
+        logger.exception("Failed to get state for thread %s", sanitize_log_param(thread_id))
+        raise HTTPException(status_code=500, detail="Failed to get thread state")
+
+    if checkpoint_tuple is None:
+        raise HTTPException(status_code=404, detail=f"Thread {thread_id} not found")
+
+    checkpoint = getattr(checkpoint_tuple, "checkpoint", {}) or {}
+    metadata = getattr(checkpoint_tuple, "metadata", {}) or {}
+    checkpoint_id = None
+    ckpt_config = getattr(checkpoint_tuple, "config", {})
+    if ckpt_config:
+        checkpoint_id = ckpt_config.get("configurable", {}).get("checkpoint_id")
+
+    channel_values = checkpoint.get("channel_values", {})
+
+    parent_config = getattr(checkpoint_tuple, "parent_config", None)
+    parent_checkpoint_id = None
+    if parent_config:
+        parent_checkpoint_id = parent_config.get("configurable", {}).get("checkpoint_id")
+
+    tasks_raw = getattr(checkpoint_tuple, "tasks", []) or []
+    next_tasks = [t.name for t in tasks_raw if hasattr(t, "name")]
+    tasks = [{"id": getattr(t, "id", ""), "name": getattr(t, "name", "")} for t in tasks_raw]
+
+    values = serialize_channel_values(channel_values)
+
+    return ThreadStateResponse(
+        values=values,
+        next=next_tasks,
+        metadata=metadata,
+        checkpoint={"id": checkpoint_id, "ts": coerce_iso(metadata.get("created_at", ""))},
+        checkpoint_id=checkpoint_id,
+        parent_checkpoint_id=parent_checkpoint_id,
+        created_at=coerce_iso(metadata.get("created_at", "")),
+        tasks=tasks,
+    )
+
+
+@router.post("/{thread_id}/state", response_model=ThreadStateResponse)
+@require_permission("threads", "write", owner_check=True, require_existing=True)
+async def update_thread_state(thread_id: str, body: ThreadStateUpdateRequest, request: Request) -> ThreadStateResponse:
+    """Update thread state (e.g. for human-in-the-loop resume or title rename).
+
+    Writes a new checkpoint that merges *body.values* into the latest
+    channel values, then syncs any updated ``title`` field through the
+    ThreadMetaStore abstraction so that ``/threads/search`` reflects the
+    change immediately in both sqlite and memory backends.
+    """
+    from app.gateway.deps import get_thread_store
+
+    checkpointer = get_checkpointer(request)
+    thread_store = get_thread_store(request)
+
+    # checkpoint_ns must be present in the config for aput — default to ""
+    # (the root graph namespace).  checkpoint_id is optional; omitting it
+    # fetches the latest checkpoint for the thread.
+    read_config: dict[str, Any] = {
+        "configurable": {
+            "thread_id": thread_id,
+            "checkpoint_ns": "",
+        }
+    }
+    if body.checkpoint_id:
+        read_config["configurable"]["checkpoint_id"] = body.checkpoint_id
+
+    try:
+        checkpoint_tuple = await checkpointer.aget_tuple(read_config)
+    except Exception:
+        logger.exception("Failed to get state for thread %s", sanitize_log_param(thread_id))
+        raise HTTPException(status_code=500, detail="Failed to get thread state")
+
+    if checkpoint_tuple is None:
+        raise HTTPException(status_code=404, detail=f"Thread {thread_id} not found")
+
+    # Work on mutable copies so we don't accidentally mutate cached objects.
+    checkpoint: dict[str, Any] = dict(getattr(checkpoint_tuple, "checkpoint", {}) or {})
+    metadata: dict[str, Any] = dict(getattr(checkpoint_tuple, "metadata", {}) or {})
+    channel_values: dict[str, Any] = dict(checkpoint.get("channel_values", {}))
+
+    if body.values:
+        channel_values.update(body.values)
+
+    checkpoint["channel_values"] = channel_values
+    metadata["updated_at"] = now_iso()
+
+    if body.as_node:
+        metadata["source"] = "update"
+        metadata["step"] = metadata.get("step", 0) + 1
+        metadata["writes"] = {body.as_node: body.values}
+
+    # aput requires checkpoint_ns in the config — use the same config used for the
+    # read (which always includes checkpoint_ns="").  Do NOT include checkpoint_id
+    # so that aput generates a fresh checkpoint ID for the new snapshot.
+    write_config: dict[str, Any] = {
+        "configurable": {
+            "thread_id": thread_id,
+            "checkpoint_ns": "",
+        }
+    }
+    try:
+        new_config = await checkpointer.aput(write_config, checkpoint, metadata, {})
+    except Exception:
+        logger.exception("Failed to update state for thread %s", sanitize_log_param(thread_id))
+        raise HTTPException(status_code=500, detail="Failed to update thread state")
+
+    new_checkpoint_id: str | None = None
+    if isinstance(new_config, dict):
+        new_checkpoint_id = new_config.get("configurable", {}).get("checkpoint_id")
+
+    # Sync title changes through the ThreadMetaStore abstraction so /threads/search
+    # reflects them immediately in both sqlite and memory backends.
+    if body.values and "title" in body.values:
+        new_title = body.values["title"]
+        if new_title:  # Skip empty strings and None
+            try:
+                await thread_store.update_display_name(thread_id, new_title)
+            except Exception:
+                logger.debug("Failed to sync title to thread_meta for %s (non-fatal)", sanitize_log_param(thread_id))
+
+    return ThreadStateResponse(
+        values=serialize_channel_values(channel_values),
+        next=[],
+        metadata=metadata,
+        checkpoint_id=new_checkpoint_id,
+        created_at=coerce_iso(metadata.get("created_at", "")),
+    )
+
+
+@router.post("/{thread_id}/history", response_model=list[HistoryEntry])
+@require_permission("threads", "read", owner_check=True)
+async def get_thread_history(thread_id: str, body: ThreadHistoryRequest, request: Request) -> list[HistoryEntry]:
+    """Get checkpoint history for a thread.
+
+    Messages are read from the checkpointer's channel values (the
+    authoritative source) and serialized via
+    :func:`~deerflow.runtime.serialization.serialize_channel_values`.
+    Only the latest (first) checkpoint carries the ``messages`` key to
+    avoid duplicating them across every entry.
+    """
+    checkpointer = get_checkpointer(request)
+
+    config: dict[str, Any] = {"configurable": {"thread_id": thread_id}}
+    if body.before:
+        config["configurable"]["checkpoint_id"] = body.before
+
+    entries: list[HistoryEntry] = []
+    is_latest_checkpoint = True
+    try:
+        async for checkpoint_tuple in checkpointer.alist(config, limit=body.limit):
+            ckpt_config = getattr(checkpoint_tuple, "config", {})
+            parent_config = getattr(checkpoint_tuple, "parent_config", None)
+            metadata = getattr(checkpoint_tuple, "metadata", {}) or {}
+            checkpoint = getattr(checkpoint_tuple, "checkpoint", {}) or {}
+
+            checkpoint_id = ckpt_config.get("configurable", {}).get("checkpoint_id", "")
+            parent_id = None
+            if parent_config:
+                parent_id = parent_config.get("configurable", {}).get("checkpoint_id")
+
+            channel_values = checkpoint.get("channel_values", {})
+
+            # Build values from checkpoint channel_values
+            values: dict[str, Any] = {}
+            if title := channel_values.get("title"):
+                values["title"] = title
+            if thread_data := channel_values.get("thread_data"):
+                values["thread_data"] = thread_data
+
+            # Attach messages only to the latest checkpoint entry.
+            if is_latest_checkpoint:
+                messages = channel_values.get("messages")
+                if messages:
+                    values["messages"] = serialize_channel_values({"messages": messages}).get("messages", [])
+            is_latest_checkpoint = False
+
+            # Derive next tasks
+            tasks_raw = getattr(checkpoint_tuple, "tasks", []) or []
+            next_tasks = [t.name for t in tasks_raw if hasattr(t, "name")]
+
+            # Strip LangGraph internal keys from metadata
+            user_meta = {k: v for k, v in metadata.items() if k not in ("created_at", "updated_at", "step", "source", "writes", "parents")}
+            # Keep step for ordering context
+            if "step" in metadata:
+                user_meta["step"] = metadata["step"]
+
+            entries.append(
+                HistoryEntry(
+                    checkpoint_id=checkpoint_id,
+                    parent_checkpoint_id=parent_id,
+                    metadata=user_meta,
+                    values=values,
+                    created_at=coerce_iso(metadata.get("created_at", "")),
+                    next=next_tasks,
+                )
+            )
+    except Exception:
+        logger.exception("Failed to get history for thread %s", sanitize_log_param(thread_id))
+        raise HTTPException(status_code=500, detail="Failed to get thread history")
+
+    return entries

offline-backend-20260512/backend/app/gateway/routers/uploads.py

@@ -0,0 +1,334 @@
+"""Upload router for handling file uploads."""
+
+import logging
+import os
+import stat
+
+from fastapi import APIRouter, Depends, File, HTTPException, Request, UploadFile
+from pydantic import BaseModel, Field
+
+from app.gateway.authz import require_permission
+from app.gateway.deps import get_config
+from deerflow.config.app_config import AppConfig
+from deerflow.config.paths import get_paths
+from deerflow.runtime.user_context import get_effective_user_id
+from deerflow.sandbox.sandbox_provider import SandboxProvider, get_sandbox_provider
+from deerflow.uploads.manager import (
+    PathTraversalError,
+    UnsafeUploadPathError,
+    delete_file_safe,
+    enrich_file_listing,
+    ensure_uploads_dir,
+    get_uploads_dir,
+    list_files_in_dir,
+    normalize_filename,
+    open_upload_file_no_symlink,
+    upload_artifact_url,
+    upload_virtual_path,
+)
+from deerflow.utils.file_conversion import CONVERTIBLE_EXTENSIONS, convert_file_to_markdown
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api/threads/{thread_id}/uploads", tags=["uploads"])
+
+UPLOAD_CHUNK_SIZE = 8192
+DEFAULT_MAX_FILES = 10
+DEFAULT_MAX_FILE_SIZE = 50 * 1024 * 1024
+DEFAULT_MAX_TOTAL_SIZE = 100 * 1024 * 1024
+
+
+class UploadResponse(BaseModel):
+    """Response model for file upload."""
+
+    success: bool
+    files: list[dict[str, str]]
+    message: str
+    skipped_files: list[str] = Field(default_factory=list)
+
+
+class UploadLimits(BaseModel):
+    """Application-level upload limits exposed to clients."""
+
+    max_files: int
+    max_file_size: int
+    max_total_size: int
+
+
+def _make_file_sandbox_writable(file_path: os.PathLike[str] | str) -> None:
+    """Ensure uploaded files remain writable when mounted into non-local sandboxes.
+
+    In AIO sandbox mode, the gateway writes the authoritative host-side file
+    first, then the sandbox runtime may rewrite the same mounted path. Granting
+    world-writable access here prevents permission mismatches between the
+    gateway user and the sandbox runtime user.
+    """
+    file_stat = os.lstat(file_path)
+    if stat.S_ISLNK(file_stat.st_mode):
+        logger.warning("Skipping sandbox chmod for symlinked upload path: %s", file_path)
+        return
+
+    writable_mode = stat.S_IMODE(file_stat.st_mode) | stat.S_IWUSR | stat.S_IWGRP | stat.S_IWOTH
+    chmod_kwargs = {"follow_symlinks": False} if os.chmod in os.supports_follow_symlinks else {}
+    os.chmod(file_path, writable_mode, **chmod_kwargs)
+
+
+def _uses_thread_data_mounts(sandbox_provider: SandboxProvider) -> bool:
+    return bool(getattr(sandbox_provider, "uses_thread_data_mounts", False))
+
+
+def _get_uploads_config_value(app_config: AppConfig, key: str, default: object) -> object:
+    """Read a value from the uploads config, supporting dict and attribute access."""
+    uploads_cfg = getattr(app_config, "uploads", None)
+    if isinstance(uploads_cfg, dict):
+        return uploads_cfg.get(key, default)
+    return getattr(uploads_cfg, key, default)
+
+
+def _get_upload_limit(app_config: AppConfig, key: str, default: int, *, legacy_key: str | None = None) -> int:
+    try:
+        value = _get_uploads_config_value(app_config, key, None)
+        if value is None and legacy_key is not None:
+            value = _get_uploads_config_value(app_config, legacy_key, None)
+        if value is None:
+            value = default
+        limit = int(value)
+        if limit <= 0:
+            raise ValueError
+        return limit
+    except Exception:
+        logger.warning("Invalid uploads.%s value; falling back to %d", key, default)
+        return default
+
+
+def _get_upload_limits(app_config: AppConfig) -> UploadLimits:
+    return UploadLimits(
+        max_files=_get_upload_limit(app_config, "max_files", DEFAULT_MAX_FILES, legacy_key="max_file_count"),
+        max_file_size=_get_upload_limit(app_config, "max_file_size", DEFAULT_MAX_FILE_SIZE, legacy_key="max_single_file_size"),
+        max_total_size=_get_upload_limit(app_config, "max_total_size", DEFAULT_MAX_TOTAL_SIZE),
+    )
+
+
+def _cleanup_uploaded_paths(paths: list[os.PathLike[str] | str]) -> None:
+    for path in reversed(paths):
+        try:
+            os.unlink(path)
+        except FileNotFoundError:
+            pass
+        except Exception:
+            logger.warning("Failed to clean up upload path after rejected request: %s", path, exc_info=True)
+
+
+async def _write_upload_file_with_limits(
+    file: UploadFile,
+    *,
+    uploads_dir: os.PathLike[str] | str,
+    display_filename: str,
+    max_single_file_size: int,
+    max_total_size: int,
+    total_size: int,
+) -> tuple[os.PathLike[str] | str, int, int]:
+    file_size = 0
+    file_path, fh = open_upload_file_no_symlink(uploads_dir, display_filename)
+    try:
+        while chunk := await file.read(UPLOAD_CHUNK_SIZE):
+            file_size += len(chunk)
+            total_size += len(chunk)
+            if file_size > max_single_file_size:
+                raise HTTPException(status_code=413, detail=f"File too large: {display_filename}")
+            if total_size > max_total_size:
+                raise HTTPException(status_code=413, detail="Total upload size too large")
+            fh.write(chunk)
+    except Exception:
+        fh.close()
+        try:
+            os.unlink(file_path)
+        except FileNotFoundError:
+            pass
+        raise
+    else:
+        fh.close()
+    return file_path, file_size, total_size
+
+
+def _auto_convert_documents_enabled(app_config: AppConfig) -> bool:
+    """Return whether automatic host-side document conversion is enabled.
+
+    The secure default is disabled unless an operator explicitly opts in via
+    uploads.auto_convert_documents in config.yaml.
+    """
+    try:
+        raw = _get_uploads_config_value(app_config, "auto_convert_documents", False)
+        if isinstance(raw, str):
+            return raw.strip().lower() in {"1", "true", "yes", "on"}
+        return bool(raw)
+    except Exception:
+        return False
+
+
+@router.post("", response_model=UploadResponse)
+@require_permission("threads", "write", owner_check=True, require_existing=False)
+async def upload_files(
+    thread_id: str,
+    request: Request,
+    files: list[UploadFile] = File(...),
+    config: AppConfig = Depends(get_config),
+) -> UploadResponse:
+    """Upload multiple files to a thread's uploads directory."""
+    if not files:
+        raise HTTPException(status_code=400, detail="No files provided")
+
+    limits = _get_upload_limits(config)
+    if len(files) > limits.max_files:
+        raise HTTPException(status_code=413, detail=f"Too many files: maximum is {limits.max_files}")
+
+    try:
+        uploads_dir = ensure_uploads_dir(thread_id)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    sandbox_uploads = get_paths().sandbox_uploads_dir(thread_id, user_id=get_effective_user_id())
+    uploaded_files = []
+    written_paths = []
+    sandbox_sync_targets = []
+    skipped_files = []
+    total_size = 0
+
+    sandbox_provider = get_sandbox_provider()
+    sync_to_sandbox = not _uses_thread_data_mounts(sandbox_provider)
+    sandbox = None
+    if sync_to_sandbox:
+        sandbox_id = sandbox_provider.acquire(thread_id)
+        sandbox = sandbox_provider.get(sandbox_id)
+        if sandbox is None:
+            raise HTTPException(status_code=500, detail="Failed to acquire sandbox")
+    auto_convert_documents = _auto_convert_documents_enabled(config)
+
+    for file in files:
+        if not file.filename:
+            continue
+
+        try:
+            safe_filename = normalize_filename(file.filename)
+        except ValueError:
+            logger.warning(f"Skipping file with unsafe filename: {file.filename!r}")
+            continue
+
+        try:
+            file_path, file_size, total_size = await _write_upload_file_with_limits(
+                file,
+                uploads_dir=uploads_dir,
+                display_filename=safe_filename,
+                max_single_file_size=limits.max_file_size,
+                max_total_size=limits.max_total_size,
+                total_size=total_size,
+            )
+            written_paths.append(file_path)
+
+            virtual_path = upload_virtual_path(safe_filename)
+
+            if sync_to_sandbox:
+                sandbox_sync_targets.append((file_path, virtual_path))
+
+            file_info = {
+                "filename": safe_filename,
+                "size": str(file_size),
+                "path": str(sandbox_uploads / safe_filename),
+                "virtual_path": virtual_path,
+                "artifact_url": upload_artifact_url(thread_id, safe_filename),
+            }
+
+            logger.info(f"Saved file: {safe_filename} ({file_size} bytes) to {file_info['path']}")
+
+            file_ext = file_path.suffix.lower()
+            if auto_convert_documents and file_ext in CONVERTIBLE_EXTENSIONS:
+                md_path = await convert_file_to_markdown(file_path)
+                if md_path:
+                    written_paths.append(md_path)
+                    md_virtual_path = upload_virtual_path(md_path.name)
+
+                    if sync_to_sandbox:
+                        sandbox_sync_targets.append((md_path, md_virtual_path))
+
+                    file_info["markdown_file"] = md_path.name
+                    file_info["markdown_path"] = str(sandbox_uploads / md_path.name)
+                    file_info["markdown_virtual_path"] = md_virtual_path
+                    file_info["markdown_artifact_url"] = upload_artifact_url(thread_id, md_path.name)
+
+            uploaded_files.append(file_info)
+
+        except HTTPException as e:
+            _cleanup_uploaded_paths(written_paths)
+            raise e
+        except UnsafeUploadPathError as e:
+            logger.warning("Skipping upload with unsafe destination %s: %s", file.filename, e)
+            skipped_files.append(safe_filename)
+            continue
+        except Exception as e:
+            logger.error(f"Failed to upload {file.filename}: {e}")
+            _cleanup_uploaded_paths(written_paths)
+            raise HTTPException(status_code=500, detail=f"Failed to upload {file.filename}: {str(e)}")
+
+    if sync_to_sandbox:
+        for file_path, virtual_path in sandbox_sync_targets:
+            _make_file_sandbox_writable(file_path)
+            sandbox.update_file(virtual_path, file_path.read_bytes())
+
+    message = f"Successfully uploaded {len(uploaded_files)} file(s)"
+    if skipped_files:
+        message += f"; skipped {len(skipped_files)} unsafe file(s)"
+
+    return UploadResponse(
+        success=not skipped_files,
+        files=uploaded_files,
+        message=message,
+        skipped_files=skipped_files,
+    )
+
+
+@router.get("/limits", response_model=UploadLimits)
+@require_permission("threads", "read", owner_check=True)
+async def get_upload_limits(
+    thread_id: str,
+    request: Request,
+    config: AppConfig = Depends(get_config),
+) -> UploadLimits:
+    """Return upload limits used by the gateway for this thread."""
+    return _get_upload_limits(config)
+
+
+@router.get("/list", response_model=dict)
+@require_permission("threads", "read", owner_check=True)
+async def list_uploaded_files(thread_id: str, request: Request) -> dict:
+    """List all files in a thread's uploads directory."""
+    try:
+        uploads_dir = get_uploads_dir(thread_id)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    result = list_files_in_dir(uploads_dir)
+    enrich_file_listing(result, thread_id)
+
+    # Gateway additionally includes the sandbox-relative path.
+    sandbox_uploads = get_paths().sandbox_uploads_dir(thread_id, user_id=get_effective_user_id())
+    for f in result["files"]:
+        f["path"] = str(sandbox_uploads / f["filename"])
+
+    return result
+
+
+@router.delete("/{filename}")
+@require_permission("threads", "delete", owner_check=True, require_existing=True)
+async def delete_uploaded_file(thread_id: str, filename: str, request: Request) -> dict:
+    """Delete a file from a thread's uploads directory."""
+    try:
+        uploads_dir = get_uploads_dir(thread_id)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    try:
+        return delete_file_safe(uploads_dir, filename, convertible_extensions=CONVERTIBLE_EXTENSIONS)
+    except FileNotFoundError:
+        raise HTTPException(status_code=404, detail=f"File not found: {filename}")
+    except PathTraversalError:
+        raise HTTPException(status_code=400, detail="Invalid path")
+    except Exception as e:
+        logger.error(f"Failed to delete {filename}: {e}")
+        raise HTTPException(status_code=500, detail=f"Failed to delete {filename}: {str(e)}")

offline-backend-20260512/backend/app/gateway/services.py

@@ -0,0 +1,423 @@
+"""Run lifecycle service layer.
+
+Centralizes the business logic for creating runs, formatting SSE
+frames, and consuming stream bridge events.  Router modules
+(``thread_runs``, ``runs``) are thin HTTP handlers that delegate here.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import re
+from collections.abc import Mapping
+from typing import Any
+
+from fastapi import HTTPException, Request
+from langchain_core.messages import HumanMessage
+
+from app.gateway.deps import get_run_context, get_run_manager, get_stream_bridge
+from app.gateway.utils import sanitize_log_param
+from deerflow.runtime import (
+    END_SENTINEL,
+    HEARTBEAT_SENTINEL,
+    ConflictError,
+    DisconnectMode,
+    RunManager,
+    RunRecord,
+    RunStatus,
+    StreamBridge,
+    UnsupportedStrategyError,
+    run_agent,
+)
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# SSE formatting
+# ---------------------------------------------------------------------------
+
+
+def format_sse(event: str, data: Any, *, event_id: str | None = None) -> str:
+    """Format a single SSE frame.
+
+    Field order: ``event:`` -> ``data:`` -> ``id:`` (optional) -> blank line.
+    This matches the LangGraph Platform wire format consumed by the
+    ``useStream`` React hook and the Python ``langgraph-sdk`` SSE decoder.
+    """
+    payload = json.dumps(data, default=str, ensure_ascii=False)
+    parts = [f"event: {event}", f"data: {payload}"]
+    if event_id:
+        parts.append(f"id: {event_id}")
+    parts.append("")
+    parts.append("")
+    return "\n".join(parts)
+
+
+# ---------------------------------------------------------------------------
+# Input / config helpers
+# ---------------------------------------------------------------------------
+
+
+def normalize_stream_modes(raw: list[str] | str | None) -> list[str]:
+    """Normalize the stream_mode parameter to a list.
+
+    Default matches what ``useStream`` expects: values + messages-tuple.
+    """
+    if raw is None:
+        return ["values"]
+    if isinstance(raw, str):
+        return [raw]
+    return raw if raw else ["values"]
+
+
+def normalize_input(raw_input: dict[str, Any] | None) -> dict[str, Any]:
+    """Convert LangGraph Platform input format to LangChain state dict."""
+    if raw_input is None:
+        return {}
+    messages = raw_input.get("messages")
+    if messages and isinstance(messages, list):
+        converted = []
+        for msg in messages:
+            if isinstance(msg, dict):
+                role = msg.get("role", msg.get("type", "user"))
+                content = msg.get("content", "")
+                if role in ("user", "human"):
+                    converted.append(HumanMessage(content=content))
+                else:
+                    # TODO: handle other message types (system, ai, tool)
+                    converted.append(HumanMessage(content=content))
+            else:
+                converted.append(msg)
+        return {**raw_input, "messages": converted}
+    return raw_input
+
+
+_DEFAULT_ASSISTANT_ID = "lead_agent"
+
+
+# Whitelist of run-context keys that the langgraph-compat layer forwards from
+# ``body.context`` into the run config. ``config["context"]`` exists in
+# LangGraph >=0.6, but these values must be written to both ``configurable``
+# (for legacy ``_get_runtime_config`` consumers) and ``context`` because
+# LangGraph >=1.1.9 no longer makes ``ToolRuntime.context`` fall back to
+# ``configurable`` for consumers like ``setup_agent``.
+_CONTEXT_CONFIGURABLE_KEYS: frozenset[str] = frozenset(
+    {
+        "agent_id",
+        "model_name",
+        "mode",
+        "thinking_enabled",
+        "reasoning_effort",
+        "is_plan_mode",
+        "subagent_enabled",
+        "max_concurrent_subagents",
+        "agent_name",
+        "is_bootstrap",
+    }
+)
+
+
+def merge_run_context_overrides(config: dict[str, Any], context: Mapping[str, Any] | None) -> None:
+    """Merge whitelisted keys from ``body.context`` into both ``config['configurable']``
+    and ``config['context']`` so they are visible to legacy configurable readers and
+    to LangGraph ``ToolRuntime.context`` consumers (e.g. the ``setup_agent`` tool —
+    see issue #2677)."""
+    if not context:
+        return
+    configurable = config.setdefault("configurable", {})
+    runtime_context = config.setdefault("context", {})
+    for key in _CONTEXT_CONFIGURABLE_KEYS:
+        if key in context:
+            if isinstance(configurable, dict):
+                configurable.setdefault(key, context[key])
+            if isinstance(runtime_context, dict):
+                runtime_context.setdefault(key, context[key])
+
+
+def resolve_agent_factory(assistant_id: str | None):
+    """Resolve the agent factory callable from config.
+
+    Custom agents are implemented as ``lead_agent`` + an ``agent_id``
+    injected into ``configurable`` or ``context`` — see
+    :func:`build_run_config`.  All ``assistant_id`` values therefore map to the
+    same factory; the routing happens inside ``make_lead_agent`` when it reads
+    ``cfg["agent_id"]``.
+    """
+    from deerflow.agents.lead_agent.agent import make_lead_agent
+
+    return make_lead_agent
+
+
+def build_run_config(
+    thread_id: str,
+    request_config: dict[str, Any] | None,
+    metadata: dict[str, Any] | None,
+    *,
+    assistant_id: str | None = None,
+) -> dict[str, Any]:
+    """Build a RunnableConfig dict for the agent.
+
+    When *assistant_id* refers to a custom agent (anything other than
+    ``"lead_agent"`` / ``None``), the id is forwarded as ``agent_id`` in
+    whichever runtime options container is active: ``context`` for
+    LangGraph >= 0.6.0 requests, otherwise ``configurable``.
+    ``make_lead_agent`` reads this key to load the matching
+    ``agents/<id>/SOUL.md`` and per-agent config — without it the agent
+    silently runs as the default lead agent.
+
+    This mirrors the channel manager's ``_resolve_run_params`` logic so that
+    the LangGraph Platform-compatible HTTP API and the IM channel path behave
+    identically.
+    """
+    config: dict[str, Any] = {"recursion_limit": 100}
+    if request_config:
+        # LangGraph >= 0.6.0 introduced ``context`` as the preferred way to
+        # pass thread-level data and rejects requests that include both
+        # ``configurable`` and ``context``.  If the caller already sends
+        # ``context``, honour it and skip our own ``configurable`` dict.
+        if "context" in request_config:
+            if "configurable" in request_config:
+                logger.warning(
+                    "build_run_config: client sent both 'context' and 'configurable'; preferring 'context' (LangGraph >= 0.6.0). thread_id=%s, caller_configurable keys=%s",
+                    thread_id,
+                    list(request_config.get("configurable", {}).keys()),
+                )
+            context_value = request_config["context"]
+            if context_value is None:
+                context = {}
+            elif isinstance(context_value, Mapping):
+                context = dict(context_value)
+            else:
+                raise ValueError("request config 'context' must be a mapping or null.")
+            config["context"] = context
+        else:
+            configurable = {"thread_id": thread_id}
+            configurable.update(request_config.get("configurable", {}))
+            config["configurable"] = configurable
+        for k, v in request_config.items():
+            if k not in ("configurable", "context"):
+                config[k] = v
+    else:
+        config["configurable"] = {"thread_id": thread_id}
+
+    # Inject custom agent id when the caller specified a non-default assistant.
+    # Honour an explicit agent_id in the active runtime options container.
+    if assistant_id and assistant_id != _DEFAULT_ASSISTANT_ID:
+        normalized = assistant_id.strip()
+        if not normalized or not re.fullmatch(r"[A-Za-z0-9_-]+", normalized):
+            raise ValueError(f"Invalid assistant_id {assistant_id!r}: must contain only letters, digits, hyphens, and underscores.")
+        if "configurable" in config:
+            target = config["configurable"]
+        elif "context" in config:
+            target = config["context"]
+        else:
+            target = config.setdefault("configurable", {})
+        if target is not None and "agent_id" not in target:
+            target["agent_id"] = normalized
+    if metadata:
+        config.setdefault("metadata", {}).update(metadata)
+    return config
+
+
+def _collect_requested_agent_ids(body: Any) -> set[str]:
+    """Collect agent ids from assistant_id/config/context for access checks."""
+    agent_ids: set[str] = set()
+    if body.assistant_id and body.assistant_id != _DEFAULT_ASSISTANT_ID:
+        agent_ids.add(str(body.assistant_id))
+
+    def collect(container: Mapping[str, Any] | None) -> None:
+        if not container:
+            return
+        for key in ("agent_id", "agent_name"):
+            value = container.get(key)
+            if value:
+                agent_ids.add(str(value))
+
+    context = getattr(body, "context", None)
+    if isinstance(context, Mapping):
+        collect(context)
+
+    config = body.config or {}
+    if isinstance(config, Mapping):
+        nested_context = config.get("context")
+        nested_configurable = config.get("configurable")
+        if isinstance(nested_context, Mapping):
+            collect(nested_context)
+        if isinstance(nested_configurable, Mapping):
+            collect(nested_configurable)
+
+    return agent_ids
+
+
+async def _sync_legacy_agent_records(store) -> None:
+    """Import existing folder-backed agents as built-in records."""
+    from deerflow.config.agents_config import list_custom_agents
+
+    for agent_cfg in list_custom_agents():
+        agent_id = agent_cfg.id or agent_cfg.name
+        if not agent_id:
+            continue
+        await store.ensure_builtin(
+            {
+                "id": agent_id,
+                "name": agent_cfg.name,
+                "description": agent_cfg.description or "",
+                "published": True,
+            }
+        )
+
+
+async def _enforce_agent_access(body: Any, request: Request) -> None:
+    agent_ids = _collect_requested_agent_ids(body)
+    if not agent_ids:
+        return
+
+    from app.gateway.deps import get_agent_store
+    from deerflow.config.agents_config import validate_agent_id
+    from deerflow.runtime.user_context import get_effective_user_id
+
+    store = get_agent_store(request)
+    await _sync_legacy_agent_records(store)
+    user_id = get_effective_user_id()
+    for agent_id in agent_ids:
+        try:
+            normalized = validate_agent_id(agent_id)
+        except ValueError as exc:
+            raise HTTPException(status_code=422, detail=str(exc)) from exc
+        if normalized is None:
+            continue
+        if await store.get_visible(normalized, user_id) is None:
+            raise HTTPException(status_code=404, detail=f"Agent {normalized} not found")
+
+
+# ---------------------------------------------------------------------------
+# Run lifecycle
+# ---------------------------------------------------------------------------
+
+
+async def start_run(
+    body: Any,
+    thread_id: str,
+    request: Request,
+) -> RunRecord:
+    """Create a RunRecord and launch the background agent task.
+
+    Parameters
+    ----------
+    body : RunCreateRequest
+        The validated request body (typed as Any to avoid circular import
+        with the router module that defines the Pydantic model).
+    thread_id : str
+        Target thread.
+    request : Request
+        FastAPI request — used to retrieve singletons from ``app.state``.
+    """
+    bridge = get_stream_bridge(request)
+    run_mgr = get_run_manager(request)
+    run_ctx = get_run_context(request)
+
+    disconnect = DisconnectMode.cancel if body.on_disconnect == "cancel" else DisconnectMode.continue_
+
+    await _enforce_agent_access(body, request)
+
+    try:
+        record = await run_mgr.create_or_reject(
+            thread_id,
+            body.assistant_id,
+            on_disconnect=disconnect,
+            metadata=body.metadata or {},
+            kwargs={"input": body.input, "config": body.config},
+            multitask_strategy=body.multitask_strategy,
+        )
+    except ConflictError as exc:
+        raise HTTPException(status_code=409, detail=str(exc)) from exc
+    except UnsupportedStrategyError as exc:
+        raise HTTPException(status_code=501, detail=str(exc)) from exc
+
+    # Upsert thread metadata so the thread appears in /threads/search,
+    # even for threads that were never explicitly created via POST /threads
+    # (e.g. stateless runs).
+    try:
+        existing = await run_ctx.thread_store.get(thread_id)
+        if existing is None:
+            await run_ctx.thread_store.create(
+                thread_id,
+                assistant_id=body.assistant_id,
+                metadata=body.metadata,
+            )
+        else:
+            await run_ctx.thread_store.update_status(thread_id, "running")
+    except Exception:
+        logger.warning("Failed to upsert thread_meta for %s (non-fatal)", sanitize_log_param(thread_id))
+
+    agent_factory = resolve_agent_factory(body.assistant_id)
+    graph_input = normalize_input(body.input)
+    config = build_run_config(thread_id, body.config, body.metadata, assistant_id=body.assistant_id)
+
+    # Merge DeerFlow-specific context overrides into both ``configurable`` and ``context``.
+    # The ``context`` field is a custom extension for the langgraph-compat layer
+    # that carries agent configuration (model_name, thinking_enabled, etc.).
+    # Only agent-relevant keys are forwarded; unknown keys (e.g. thread_id) are ignored.
+    merge_run_context_overrides(config, getattr(body, "context", None))
+
+    stream_modes = normalize_stream_modes(body.stream_mode)
+
+    task = asyncio.create_task(
+        run_agent(
+            bridge,
+            run_mgr,
+            record,
+            ctx=run_ctx,
+            agent_factory=agent_factory,
+            graph_input=graph_input,
+            config=config,
+            stream_modes=stream_modes,
+            stream_subgraphs=body.stream_subgraphs,
+            interrupt_before=body.interrupt_before,
+            interrupt_after=body.interrupt_after,
+        )
+    )
+    record.task = task
+
+    # Title sync is handled by worker.py's finally block which reads the
+    # title from the checkpoint and calls thread_store.update_display_name
+    # after the run completes.
+
+    return record
+
+
+async def sse_consumer(
+    bridge: StreamBridge,
+    record: RunRecord,
+    request: Request,
+    run_mgr: RunManager,
+):
+    """Async generator that yields SSE frames from the bridge.
+
+    The ``finally`` block implements ``on_disconnect`` semantics:
+    - ``cancel``: abort the background task on client disconnect.
+    - ``continue``: let the task run; events are discarded.
+    """
+    last_event_id = request.headers.get("Last-Event-ID")
+    try:
+        async for entry in bridge.subscribe(record.run_id, last_event_id=last_event_id):
+            if await request.is_disconnected():
+                break
+
+            if entry is HEARTBEAT_SENTINEL:
+                yield ": heartbeat\n\n"
+                continue
+
+            if entry is END_SENTINEL:
+                yield format_sse("end", None, event_id=entry.id or None)
+                return
+
+            yield format_sse(entry.event, entry.data, event_id=entry.id or None)
+
+    finally:
+        if record.status in (RunStatus.pending, RunStatus.running):
+            if record.on_disconnect == DisconnectMode.cancel:
+                await run_mgr.cancel(record.run_id)

offline-backend-20260512/backend/app/gateway/utils.py

@@ -0,0 +1,6 @@
+"""Shared utility helpers for the Gateway layer."""
+
+
+def sanitize_log_param(value: str) -> str:
+    """Strip control characters to prevent log injection."""
+    return value.replace("\n", "").replace("\r", "").replace("\x00", "")

offline-backend-20260512/backend/debug.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python
+"""
+Debug script for lead_agent.
+Run this file directly in VS Code with breakpoints.
+
+Requirements:
+    Run with `uv run` from the backend/ directory so that the uv workspace
+    resolves deerflow-harness and app packages correctly:
+
+        cd backend && PYTHONPATH=. uv run python debug.py
+
+Usage:
+    1. Set breakpoints in agent.py or other files
+    2. Press F5 or use "Run and Debug" panel
+    3. Input messages in the terminal to interact with the agent
+"""
+
+import asyncio
+import logging
+
+from dotenv import load_dotenv
+
+try:
+    from prompt_toolkit import PromptSession
+    from prompt_toolkit.history import InMemoryHistory
+
+    _HAS_PROMPT_TOOLKIT = True
+except ImportError:
+    _HAS_PROMPT_TOOLKIT = False
+
+load_dotenv()
+
+_LOG_FMT = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+_LOG_DATEFMT = "%Y-%m-%d %H:%M:%S"
+
+
+def _setup_logging(log_level: int = logging.INFO) -> None:
+    """Route logs to ``debug.log`` using *log_level* for the initial root/file setup.
+
+    This configures the root logger and the ``debug.log`` file handler so logs do
+    not print on the interactive console. It is idempotent: any pre-existing
+    handlers on the root logger (e.g. installed by ``logging.basicConfig`` in
+    transitively imported modules) are removed so the debug session output only
+    lands in ``debug.log``.
+
+    Note: later config-driven logging adjustments may change named logger
+    verbosity without raising the root logger or file-handler thresholds set
+    here, so the eventual contents of ``debug.log`` may not be filtered solely by
+    this function's ``log_level`` argument.
+    """
+    root = logging.root
+    for h in list(root.handlers):
+        root.removeHandler(h)
+        h.close()
+    root.setLevel(log_level)
+
+    file_handler = logging.FileHandler("debug.log", mode="a", encoding="utf-8")
+    file_handler.setLevel(log_level)
+    file_handler.setFormatter(logging.Formatter(_LOG_FMT, datefmt=_LOG_DATEFMT))
+    root.addHandler(file_handler)
+
+
+async def main():
+    # Install file logging first so warnings emitted while loading config do not
+    # leak onto the interactive terminal via Python's lastResort handler.
+    _setup_logging()
+
+    from deerflow.config import get_app_config
+    from deerflow.config.app_config import apply_logging_level
+
+    app_config = get_app_config()
+    apply_logging_level(app_config.log_level)
+
+    # Delay the rest of the deerflow imports until *after* logging is installed
+    # so that any import-time side effects (e.g. deerflow.agents starts a
+    # background skill-loader thread on import) emit logs to debug.log instead
+    # of leaking onto the interactive terminal via Python's lastResort handler.
+    from langchain_core.messages import HumanMessage
+    from langgraph.runtime import Runtime
+
+    from deerflow.agents import make_lead_agent
+    from deerflow.mcp import initialize_mcp_tools
+
+    # Initialize MCP tools at startup
+    try:
+        await initialize_mcp_tools()
+    except Exception as e:
+        print(f"Warning: Failed to initialize MCP tools: {e}")
+
+    # Create agent with default config
+    config = {
+        "configurable": {
+            "thread_id": "debug-thread-001",
+            "thinking_enabled": True,
+            "is_plan_mode": True,
+            # Uncomment to use a specific model
+            "model_name": "kimi-k2.5",
+        }
+    }
+
+    runtime = Runtime(context={"thread_id": config["configurable"]["thread_id"]})
+    config["configurable"]["__pregel_runtime"] = runtime
+
+    agent = make_lead_agent(config)
+
+    session = PromptSession(history=InMemoryHistory()) if _HAS_PROMPT_TOOLKIT else None
+
+    print("=" * 50)
+    print("Lead Agent Debug Mode")
+    print("Type 'quit' or 'exit' to stop")
+    print(f"Logs: debug.log (log_level={app_config.log_level})")
+    if not _HAS_PROMPT_TOOLKIT:
+        print("Tip: `uv sync --group dev` to enable arrow-key & history support")
+    print("=" * 50)
+
+    while True:
+        try:
+            if session:
+                user_input = (await session.prompt_async("\nYou: ")).strip()
+            else:
+                user_input = input("\nYou: ").strip()
+            if not user_input:
+                continue
+            if user_input.lower() in ("quit", "exit"):
+                print("Goodbye!")
+                break
+
+            # Invoke the agent
+            state = {"messages": [HumanMessage(content=user_input)]}
+            result = await agent.ainvoke(state, config=config)
+
+            # Print the response
+            if result.get("messages"):
+                last_message = result["messages"][-1]
+                print(f"\nAgent: {last_message.content}")
+
+        except (KeyboardInterrupt, EOFError):
+            print("\nGoodbye!")
+            break
+        except Exception as e:
+            print(f"\nError: {e}")
+            import traceback
+
+            traceback.print_exc()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

offline-backend-20260512/backend/docs/API.md

@@ -0,0 +1,655 @@
+# API Reference
+
+This document provides a complete reference for the DeerFlow backend APIs.
+
+## Overview
+
+DeerFlow backend exposes two sets of APIs:
+
+1. **LangGraph API** - Agent interactions, threads, and streaming (`/api/langgraph/*`)
+2. **Gateway API** - Models, MCP, skills, uploads, and artifacts (`/api/*`)
+
+All APIs are accessed through the Nginx reverse proxy at port 2026.
+
+## LangGraph API
+
+Base URL: `/api/langgraph`
+
+The LangGraph API is provided by the LangGraph server and follows the LangGraph SDK conventions.
+
+### Threads
+
+#### Create Thread
+
+```http
+POST /api/langgraph/threads
+Content-Type: application/json
+```
+
+**Request Body:**
+```json
+{
+  "metadata": {}
+}
+```
+
+**Response:**
+```json
+{
+  "thread_id": "abc123",
+  "created_at": "2024-01-15T10:30:00Z",
+  "metadata": {}
+}
+```
+
+#### Get Thread State
+
+```http
+GET /api/langgraph/threads/{thread_id}/state
+```
+
+**Response:**
+```json
+{
+  "values": {
+    "messages": [...],
+    "sandbox": {...},
+    "artifacts": [...],
+    "thread_data": {...},
+    "title": "Conversation Title"
+  },
+  "next": [],
+  "config": {...}
+}
+```
+
+### Runs
+
+#### Create Run
+
+Execute the agent with input.
+
+```http
+POST /api/langgraph/threads/{thread_id}/runs
+Content-Type: application/json
+```
+
+**Request Body:**
+```json
+{
+  "input": {
+    "messages": [
+      {
+        "role": "user",
+        "content": "Hello, can you help me?"
+      }
+    ]
+  },
+  "config": {
+    "recursion_limit": 100,
+    "configurable": {
+      "model_name": "gpt-4",
+      "thinking_enabled": false,
+      "is_plan_mode": false
+    }
+  },
+  "stream_mode": ["values", "messages-tuple", "custom"]
+}
+```
+
+**Stream Mode Compatibility:**
+- Use: `values`, `messages-tuple`, `custom`, `updates`, `events`, `debug`, `tasks`, `checkpoints`
+- Do not use: `tools` (deprecated/invalid in current `langgraph-api` and will trigger schema validation errors)
+
+**Recursion Limit:**
+
+`config.recursion_limit` caps the number of graph steps LangGraph will execute
+in a single run. The `/api/langgraph/*` endpoints go straight to the LangGraph
+server and therefore inherit LangGraph's native default of **25**, which is
+too low for plan-mode or subagent-heavy runs — the agent typically errors out
+with `GraphRecursionError` after the first round of subagent results comes
+back, before the lead agent can synthesize the final answer.
+
+DeerFlow's own Gateway and IM-channel paths mitigate this by defaulting to
+`100` in `build_run_config` (see `backend/app/gateway/services.py`), but
+clients calling the LangGraph API directly must set `recursion_limit`
+explicitly in the request body. `100` matches the Gateway default and is a
+safe starting point; increase it if you run deeply nested subagent graphs.
+
+**Configurable Options:**
+- `model_name` (string): Override the default model
+- `thinking_enabled` (boolean): Enable extended thinking for supported models
+- `is_plan_mode` (boolean): Enable TodoList middleware for task tracking
+
+**Response:** Server-Sent Events (SSE) stream
+
+```
+event: values
+data: {"messages": [...], "title": "..."}
+
+event: messages
+data: {"content": "Hello! I'd be happy to help.", "role": "assistant"}
+
+event: end
+data: {}
+```
+
+#### Get Run History
+
+```http
+GET /api/langgraph/threads/{thread_id}/runs
+```
+
+**Response:**
+```json
+{
+  "runs": [
+    {
+      "run_id": "run123",
+      "status": "success",
+      "created_at": "2024-01-15T10:30:00Z"
+    }
+  ]
+}
+```
+
+#### Stream Run
+
+Stream responses in real-time.
+
+```http
+POST /api/langgraph/threads/{thread_id}/runs/stream
+Content-Type: application/json
+```
+
+Same request body as Create Run. Returns SSE stream.
+
+---
+
+## Gateway API
+
+Base URL: `/api`
+
+### Models
+
+#### List Models
+
+Get all available LLM models from configuration.
+
+```http
+GET /api/models
+```
+
+**Response:**
+```json
+{
+  "models": [
+    {
+      "name": "gpt-4",
+      "display_name": "GPT-4",
+      "supports_thinking": false,
+      "supports_vision": true
+    },
+    {
+      "name": "claude-3-opus",
+      "display_name": "Claude 3 Opus",
+      "supports_thinking": false,
+      "supports_vision": true
+    },
+    {
+      "name": "deepseek-v3",
+      "display_name": "DeepSeek V3",
+      "supports_thinking": true,
+      "supports_vision": false
+    }
+  ]
+}
+```
+
+#### Get Model Details
+
+```http
+GET /api/models/{model_name}
+```
+
+**Response:**
+```json
+{
+  "name": "gpt-4",
+  "display_name": "GPT-4",
+  "model": "gpt-4",
+  "max_tokens": 4096,
+  "supports_thinking": false,
+  "supports_vision": true
+}
+```
+
+### MCP Configuration
+
+#### Get MCP Config
+
+Get current MCP server configurations.
+
+```http
+GET /api/mcp/config
+```
+
+**Response:**
+```json
+{
+  "mcpServers": {
+    "github": {
+      "enabled": true,
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_TOKEN": "***"
+      },
+      "description": "GitHub operations"
+    },
+    "filesystem": {
+      "enabled": false,
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem"],
+      "description": "File system access"
+    }
+  }
+}
+```
+
+#### Update MCP Config
+
+Update MCP server configurations.
+
+```http
+PUT /api/mcp/config
+Content-Type: application/json
+```
+
+**Request Body:**
+```json
+{
+  "mcpServers": {
+    "github": {
+      "enabled": true,
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_TOKEN": "$GITHUB_TOKEN"
+      },
+      "description": "GitHub operations"
+    }
+  }
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "message": "MCP configuration updated"
+}
+```
+
+### Skills
+
+#### List Skills
+
+Get all available skills.
+
+```http
+GET /api/skills
+```
+
+**Response:**
+```json
+{
+  "skills": [
+    {
+      "name": "pdf-processing",
+      "display_name": "PDF Processing",
+      "description": "Handle PDF documents efficiently",
+      "enabled": true,
+      "license": "MIT",
+      "path": "public/pdf-processing"
+    },
+    {
+      "name": "frontend-design",
+      "display_name": "Frontend Design",
+      "description": "Design and build frontend interfaces",
+      "enabled": false,
+      "license": "MIT",
+      "path": "public/frontend-design"
+    }
+  ]
+}
+```
+
+#### Get Skill Details
+
+```http
+GET /api/skills/{skill_name}
+```
+
+**Response:**
+```json
+{
+  "name": "pdf-processing",
+  "display_name": "PDF Processing",
+  "description": "Handle PDF documents efficiently",
+  "enabled": true,
+  "license": "MIT",
+  "path": "public/pdf-processing",
+  "allowed_tools": ["read_file", "write_file", "bash"],
+  "content": "# PDF Processing\n\nInstructions for the agent..."
+}
+```
+
+#### Enable Skill
+
+```http
+POST /api/skills/{skill_name}/enable
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "message": "Skill 'pdf-processing' enabled"
+}
+```
+
+#### Disable Skill
+
+```http
+POST /api/skills/{skill_name}/disable
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "message": "Skill 'pdf-processing' disabled"
+}
+```
+
+#### Install Skill
+
+Install a skill from a `.skill` file.
+
+```http
+POST /api/skills/install
+Content-Type: multipart/form-data
+```
+
+**Request Body:**
+- `file`: The `.skill` file to install
+
+**Response:**
+```json
+{
+  "success": true,
+  "message": "Skill 'my-skill' installed successfully",
+  "skill": {
+    "name": "my-skill",
+    "display_name": "My Skill",
+    "path": "custom/my-skill"
+  }
+}
+```
+
+### File Uploads
+
+#### Upload Files
+
+Upload one or more files to a thread.
+
+```http
+POST /api/threads/{thread_id}/uploads
+Content-Type: multipart/form-data
+```
+
+**Request Body:**
+- `files`: One or more files to upload
+
+**Response:**
+```json
+{
+  "success": true,
+  "files": [
+    {
+      "filename": "document.pdf",
+      "size": 1234567,
+      "path": ".deer-flow/threads/abc123/user-data/uploads/document.pdf",
+      "virtual_path": "/mnt/user-data/uploads/document.pdf",
+      "artifact_url": "/api/threads/abc123/artifacts/mnt/user-data/uploads/document.pdf",
+      "markdown_file": "document.md",
+      "markdown_path": ".deer-flow/threads/abc123/user-data/uploads/document.md",
+      "markdown_virtual_path": "/mnt/user-data/uploads/document.md",
+      "markdown_artifact_url": "/api/threads/abc123/artifacts/mnt/user-data/uploads/document.md"
+    }
+  ],
+  "message": "Successfully uploaded 1 file(s)"
+}
+```
+
+**Supported Document Formats** (auto-converted to Markdown):
+- PDF (`.pdf`)
+- PowerPoint (`.ppt`, `.pptx`)
+- Excel (`.xls`, `.xlsx`)
+- Word (`.doc`, `.docx`)
+
+#### List Uploaded Files
+
+```http
+GET /api/threads/{thread_id}/uploads/list
+```
+
+**Response:**
+```json
+{
+  "files": [
+    {
+      "filename": "document.pdf",
+      "size": 1234567,
+      "path": ".deer-flow/threads/abc123/user-data/uploads/document.pdf",
+      "virtual_path": "/mnt/user-data/uploads/document.pdf",
+      "artifact_url": "/api/threads/abc123/artifacts/mnt/user-data/uploads/document.pdf",
+      "extension": ".pdf",
+      "modified": 1705997600.0
+    }
+  ],
+  "count": 1
+}
+```
+
+#### Delete File
+
+```http
+DELETE /api/threads/{thread_id}/uploads/{filename}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "message": "Deleted document.pdf"
+}
+```
+
+### Thread Cleanup
+
+Remove DeerFlow-managed local thread files under `.deer-flow/threads/{thread_id}` after the LangGraph thread itself has been deleted.
+
+```http
+DELETE /api/threads/{thread_id}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "message": "Deleted local thread data for abc123"
+}
+```
+
+**Error behavior:**
+- `422` for invalid thread IDs
+- `500` returns a generic `{"detail": "Failed to delete local thread data."}` response while full exception details stay in server logs
+
+### Artifacts
+
+#### Get Artifact
+
+Download or view an artifact generated by the agent.
+
+```http
+GET /api/threads/{thread_id}/artifacts/{path}
+```
+
+**Path Examples:**
+- `/api/threads/abc123/artifacts/mnt/user-data/outputs/result.txt`
+- `/api/threads/abc123/artifacts/mnt/user-data/uploads/document.pdf`
+
+**Query Parameters:**
+- `download` (boolean): If `true`, force download with Content-Disposition header
+
+**Response:** File content with appropriate Content-Type
+
+---
+
+## Error Responses
+
+All APIs return errors in a consistent format:
+
+```json
+{
+  "detail": "Error message describing what went wrong"
+}
+```
+
+**HTTP Status Codes:**
+- `400` - Bad Request: Invalid input
+- `404` - Not Found: Resource not found
+- `422` - Validation Error: Request validation failed
+- `500` - Internal Server Error: Server-side error
+
+---
+
+## Authentication
+
+Currently, DeerFlow does not implement authentication. All APIs are accessible without credentials.
+
+Note: This is about DeerFlow API authentication. MCP outbound connections can still use OAuth for configured HTTP/SSE MCP servers.
+
+For production deployments, it is recommended to:
+1. Use Nginx for basic auth or OAuth integration
+2. Deploy behind a VPN or private network
+3. Implement custom authentication middleware
+
+---
+
+## Rate Limiting
+
+No rate limiting is implemented by default. For production deployments, configure rate limiting in Nginx:
+
+```nginx
+limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
+
+location /api/ {
+    limit_req zone=api burst=20 nodelay;
+    proxy_pass http://backend;
+}
+```
+
+---
+
+## WebSocket Support
+
+The LangGraph server supports WebSocket connections for real-time streaming. Connect to:
+
+```
+ws://localhost:2026/api/langgraph/threads/{thread_id}/runs/stream
+```
+
+---
+
+## SDK Usage
+
+### Python (LangGraph SDK)
+
+```python
+from langgraph_sdk import get_client
+
+client = get_client(url="http://localhost:2026/api/langgraph")
+
+# Create thread
+thread = await client.threads.create()
+
+# Run agent
+async for event in client.runs.stream(
+    thread["thread_id"],
+    "lead_agent",
+    input={"messages": [{"role": "user", "content": "Hello"}]},
+    config={"configurable": {"model_name": "gpt-4"}},
+    stream_mode=["values", "messages-tuple", "custom"],
+):
+    print(event)
+```
+
+### JavaScript/TypeScript
+
+```typescript
+// Using fetch for Gateway API
+const response = await fetch('/api/models');
+const data = await response.json();
+console.log(data.models);
+
+// Using EventSource for streaming
+const eventSource = new EventSource(
+  `/api/langgraph/threads/${threadId}/runs/stream`
+);
+eventSource.onmessage = (event) => {
+  console.log(JSON.parse(event.data));
+};
+```
+
+### cURL Examples
+
+```bash
+# List models
+curl http://localhost:2026/api/models
+
+# Get MCP config
+curl http://localhost:2026/api/mcp/config
+
+# Upload file
+curl -X POST http://localhost:2026/api/threads/abc123/uploads \
+  -F "files=@document.pdf"
+
+# Enable skill
+curl -X POST http://localhost:2026/api/skills/pdf-processing/enable
+
+# Create thread and run agent
+curl -X POST http://localhost:2026/api/langgraph/threads \
+  -H "Content-Type: application/json" \
+  -d '{}'
+
+curl -X POST http://localhost:2026/api/langgraph/threads/abc123/runs \
+  -H "Content-Type: application/json" \
+  -d '{
+    "input": {"messages": [{"role": "user", "content": "Hello"}]},
+    "config": {
+      "recursion_limit": 100,
+      "configurable": {"model_name": "gpt-4"}
+    }
+  }'
+```
+
+> The `/api/langgraph/*` endpoints bypass DeerFlow's Gateway and inherit
+> LangGraph's native `recursion_limit` default of 25, which is too low for
+> plan-mode or subagent runs. Set `config.recursion_limit` explicitly — see
+> the [Create Run](#create-run) section for details.

offline-backend-20260512/backend/docs/APPLE_CONTAINER.md

@@ -0,0 +1,238 @@
+# Apple Container Support
+
+DeerFlow now supports Apple Container as the preferred container runtime on macOS, with automatic fallback to Docker.
+
+## Overview
+
+Starting with this version, DeerFlow automatically detects and uses Apple Container on macOS when available, falling back to Docker when:
+- Apple Container is not installed
+- Running on non-macOS platforms
+
+This provides better performance on Apple Silicon Macs while maintaining compatibility across all platforms.
+
+## Benefits
+
+### On Apple Silicon Macs with Apple Container:
+- **Better Performance**: Native ARM64 execution without Rosetta 2 translation
+- **Lower Resource Usage**: Lighter weight than Docker Desktop
+- **Native Integration**: Uses macOS Virtualization.framework
+
+### Fallback to Docker:
+- Full backward compatibility
+- Works on all platforms (macOS, Linux, Windows)
+- No configuration changes needed
+
+## Requirements
+
+### For Apple Container (macOS only):
+- macOS 15.0 or later
+- Apple Silicon (M1/M2/M3/M4)
+- Apple Container CLI installed
+
+### Installation:
+```bash
+# Download from GitHub releases
+# https://github.com/apple/container/releases
+
+# Verify installation
+container --version
+
+# Start the service
+container system start
+```
+
+### For Docker (all platforms):
+- Docker Desktop or Docker Engine
+
+## How It Works
+
+### Automatic Detection
+
+The `AioSandboxProvider` automatically detects the available container runtime:
+
+1. On macOS: Try `container --version`
+   - Success → Use Apple Container
+   - Failure → Fall back to Docker
+
+2. On other platforms: Use Docker directly
+
+### Runtime Differences
+
+Both runtimes use nearly identical command syntax:
+
+**Container Startup:**
+```bash
+# Apple Container
+container run --rm -d -p 8080:8080 -v /host:/container -e KEY=value image
+
+# Docker
+docker run --rm -d -p 8080:8080 -v /host:/container -e KEY=value image
+```
+
+**Container Cleanup:**
+```bash
+# Apple Container (with --rm flag)
+container stop <id>  # Auto-removes due to --rm
+
+# Docker (with --rm flag)
+docker stop <id>     # Auto-removes due to --rm
+```
+
+### Implementation Details
+
+The implementation is in `backend/packages/harness/deerflow/community/aio_sandbox/aio_sandbox_provider.py`:
+
+- `_detect_container_runtime()`: Detects available runtime at startup
+- `_start_container()`: Uses detected runtime, skips Docker-specific options for Apple Container
+- `_stop_container()`: Uses appropriate stop command for the runtime
+
+## Configuration
+
+No configuration changes are needed! The system works automatically.
+
+However, you can verify the runtime in use by checking the logs:
+
+```
+INFO:deerflow.community.aio_sandbox.aio_sandbox_provider:Detected Apple Container: container version 0.1.0
+INFO:deerflow.community.aio_sandbox.aio_sandbox_provider:Starting sandbox container using container: ...
+```
+
+Or for Docker:
+```
+INFO:deerflow.community.aio_sandbox.aio_sandbox_provider:Apple Container not available, falling back to Docker
+INFO:deerflow.community.aio_sandbox.aio_sandbox_provider:Starting sandbox container using docker: ...
+```
+
+## Container Images
+
+Both runtimes use OCI-compatible images. The default image works with both:
+
+```yaml
+sandbox:
+  use: deerflow.community.aio_sandbox:AioSandboxProvider
+  image: enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest  # Default image
+```
+
+Make sure your images are available for the appropriate architecture:
+- ARM64 for Apple Container on Apple Silicon
+- AMD64 for Docker on Intel Macs
+- Multi-arch images work on both
+
+### Pre-pulling Images (Recommended)
+
+**Important**: Container images are typically large (500MB+) and are pulled on first use, which can cause a long wait time without clear feedback.
+
+**Best Practice**: Pre-pull the image during setup:
+
+```bash
+# From project root
+make setup-sandbox
+```
+
+This command will:
+1. Read the configured image from `config.yaml` (or use default)
+2. Detect available runtime (Apple Container or Docker)
+3. Pull the image with progress indication
+4. Verify the image is ready for use
+
+**Manual pre-pull**:
+
+```bash
+# Using Apple Container
+container image pull enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest
+
+# Using Docker
+docker pull enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest
+```
+
+If you skip pre-pulling, the image will be automatically pulled on first agent execution, which may take several minutes depending on your network speed.
+
+## Cleanup Scripts
+
+The project includes a unified cleanup script that handles both runtimes:
+
+**Script:** `scripts/cleanup-containers.sh`
+
+**Usage:**
+```bash
+# Clean up all DeerFlow sandbox containers
+./scripts/cleanup-containers.sh deer-flow-sandbox
+
+# Custom prefix
+./scripts/cleanup-containers.sh my-prefix
+```
+
+**Makefile Integration:**
+
+All cleanup commands in `Makefile` automatically handle both runtimes:
+```bash
+make stop   # Stops all services and cleans up containers
+make clean  # Full cleanup including logs
+```
+
+## Testing
+
+Test the container runtime detection:
+
+```bash
+cd backend
+python test_container_runtime.py
+```
+
+This will:
+1. Detect the available runtime
+2. Optionally start a test container
+3. Verify connectivity
+4. Clean up
+
+## Troubleshooting
+
+### Apple Container not detected on macOS
+
+1. Check if installed:
+   ```bash
+   which container
+   container --version
+   ```
+
+2. Check if service is running:
+   ```bash
+   container system start
+   ```
+
+3. Check logs for detection:
+   ```bash
+   # Look for detection message in application logs
+   grep "container runtime" logs/*.log
+   ```
+
+### Containers not cleaning up
+
+1. Manually check running containers:
+   ```bash
+   # Apple Container
+   container list
+
+   # Docker
+   docker ps
+   ```
+
+2. Run cleanup script manually:
+   ```bash
+   ./scripts/cleanup-containers.sh deer-flow-sandbox
+   ```
+
+### Performance issues
+
+- Apple Container should be faster on Apple Silicon
+- If experiencing issues, you can force Docker by temporarily renaming the `container` command:
+   ```bash
+   # Temporary workaround - not recommended for permanent use
+   sudo mv /opt/homebrew/bin/container /opt/homebrew/bin/container.bak
+   ```
+
+## References
+
+- [Apple Container GitHub](https://github.com/apple/container)
+- [Apple Container Documentation](https://github.com/apple/container/blob/main/docs/)
+- [OCI Image Spec](https://github.com/opencontainers/image-spec)

offline-backend-20260512/backend/docs/ARCHITECTURE.md

@@ -0,0 +1,484 @@
+# Architecture Overview
+
+This document provides a comprehensive overview of the DeerFlow backend architecture.
+
+## System Architecture
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│                              Client (Browser)                             │
+└─────────────────────────────────┬────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│                          Nginx (Port 2026)                               │
+│                    Unified Reverse Proxy Entry Point                      │
+│  ┌────────────────────────────────────────────────────────────────────┐  │
+│  │  /api/langgraph/*  →  LangGraph Server (2024)                      │  │
+│  │  /api/*            →  Gateway API (8001)                           │  │
+│  │  /*                →  Frontend (3000)                               │  │
+│  └────────────────────────────────────────────────────────────────────┘  │
+└─────────────────────────────────┬────────────────────────────────────────┘
+                                  │
+          ┌───────────────────────┼───────────────────────┐
+          │                       │                       │
+          ▼                       ▼                       ▼
+┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐
+│   LangGraph Server  │ │    Gateway API      │ │     Frontend        │
+│     (Port 2024)     │ │    (Port 8001)      │ │    (Port 3000)      │
+│                     │ │                     │ │                     │
+│  - Agent Runtime    │ │  - Models API       │ │  - Next.js App      │
+│  - Thread Mgmt      │ │  - MCP Config       │ │  - React UI         │
+│  - SSE Streaming    │ │  - Skills Mgmt      │ │  - Chat Interface   │
+│  - Checkpointing    │ │  - File Uploads     │ │                     │
+│                     │ │  - Thread Cleanup   │ │                     │
+│                     │ │  - Artifacts        │ │                     │
+└─────────────────────┘ └─────────────────────┘ └─────────────────────┘
+          │                       │
+          │     ┌─────────────────┘
+          │     │
+          ▼     ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│                         Shared Configuration                              │
+│  ┌─────────────────────────┐  ┌────────────────────────────────────────┐ │
+│  │      config.yaml        │  │      extensions_config.json            │ │
+│  │  - Models               │  │  - MCP Servers                         │ │
+│  │  - Tools                │  │  - Skills State                        │ │
+│  │  - Sandbox              │  │                                        │ │
+│  │  - Summarization        │  │                                        │ │
+│  └─────────────────────────┘  └────────────────────────────────────────┘ │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+## Component Details
+
+### LangGraph Server
+
+The LangGraph server is the core agent runtime, built on LangGraph for robust multi-agent workflow orchestration.
+
+**Entry Point**: `packages/harness/deerflow/agents/lead_agent/agent.py:make_lead_agent`
+
+**Key Responsibilities**:
+- Agent creation and configuration
+- Thread state management
+- Middleware chain execution
+- Tool execution orchestration
+- SSE streaming for real-time responses
+
+**Configuration**: `langgraph.json`
+
+```json
+{
+  "agent": {
+    "type": "agent",
+    "path": "deerflow.agents:make_lead_agent"
+  }
+}
+```
+
+### Gateway API
+
+FastAPI application providing REST endpoints for non-agent operations.
+
+**Entry Point**: `app/gateway/app.py`
+
+**Routers**:
+- `models.py` - `/api/models` - Model listing and details
+- `mcp.py` - `/api/mcp` - MCP server configuration
+- `skills.py` - `/api/skills` - Skills management
+- `uploads.py` - `/api/threads/{id}/uploads` - File upload
+- `threads.py` - `/api/threads/{id}` - Local DeerFlow thread data cleanup after LangGraph deletion
+- `artifacts.py` - `/api/threads/{id}/artifacts` - Artifact serving
+- `suggestions.py` - `/api/threads/{id}/suggestions` - Follow-up suggestion generation
+
+The web conversation delete flow is now split across both backend surfaces: LangGraph handles `DELETE /api/langgraph/threads/{thread_id}` for thread state, then the Gateway `threads.py` router removes DeerFlow-managed filesystem data via `Paths.delete_thread_dir()`.
+
+### Agent Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                           make_lead_agent(config)                        │
+└────────────────────────────────────┬────────────────────────────────────┘
+                                     │
+                                     ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│                            Middleware Chain                              │
+│  ┌──────────────────────────────────────────────────────────────────┐   │
+│  │ 1. ThreadDataMiddleware  - Initialize workspace/uploads/outputs  │   │
+│  │ 2. UploadsMiddleware     - Process uploaded files               │   │
+│  │ 3. SandboxMiddleware     - Acquire sandbox environment          │   │
+│  │ 4. SummarizationMiddleware - Context reduction (if enabled)     │   │
+│  │ 5. TitleMiddleware       - Auto-generate titles                 │   │
+│  │ 6. TodoListMiddleware    - Task tracking (if plan_mode)         │   │
+│  │ 7. ViewImageMiddleware   - Vision model support                 │   │
+│  │ 8. ClarificationMiddleware - Handle clarifications              │   │
+│  └──────────────────────────────────────────────────────────────────┘   │
+└────────────────────────────────────┬────────────────────────────────────┘
+                                     │
+                                     ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│                              Agent Core                                  │
+│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────────┐   │
+│  │      Model       │  │      Tools       │  │    System Prompt     │   │
+│  │  (from factory)  │  │  (configured +   │  │  (with skills)       │   │
+│  │                  │  │   MCP + builtin) │  │                      │   │
+│  └──────────────────┘  └──────────────────┘  └──────────────────────┘   │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### Thread State
+
+The `ThreadState` extends LangGraph's `AgentState` with additional fields:
+
+```python
+class ThreadState(AgentState):
+    # Core state from AgentState
+    messages: list[BaseMessage]
+
+    # DeerFlow extensions
+    sandbox: dict             # Sandbox environment info
+    artifacts: list[str]      # Generated file paths
+    thread_data: dict         # {workspace, uploads, outputs} paths
+    title: str | None         # Auto-generated conversation title
+    todos: list[dict]         # Task tracking (plan mode)
+    viewed_images: dict       # Vision model image data
+```
+
+### Sandbox System
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                           Sandbox Architecture                           │
+└─────────────────────────────────────────────────────────────────────────┘
+
+                      ┌─────────────────────────┐
+                      │    SandboxProvider      │ (Abstract)
+                      │  - acquire()            │
+                      │  - get()                │
+                      │  - release()            │
+                      └────────────┬────────────┘
+                                   │
+              ┌────────────────────┼────────────────────┐
+              │                                         │
+              ▼                                         ▼
+┌─────────────────────────┐              ┌─────────────────────────┐
+│  LocalSandboxProvider   │              │  AioSandboxProvider     │
+│  (packages/harness/deerflow/sandbox/local.py) │              │  (packages/harness/deerflow/community/)       │
+│                         │              │                         │
+│  - Singleton instance   │              │  - Docker-based         │
+│  - Direct execution     │              │  - Isolated containers  │
+│  - Development use      │              │  - Production use       │
+└─────────────────────────┘              └─────────────────────────┘
+
+                      ┌─────────────────────────┐
+                      │        Sandbox          │ (Abstract)
+                      │  - execute_command()    │
+                      │  - read_file()          │
+                      │  - write_file()         │
+                      │  - list_dir()           │
+                      └─────────────────────────┘
+```
+
+**Virtual Path Mapping**:
+
+| Virtual Path | Physical Path |
+|-------------|---------------|
+| `/mnt/user-data/workspace` | `backend/.deer-flow/threads/{thread_id}/user-data/workspace` |
+| `/mnt/user-data/uploads` | `backend/.deer-flow/threads/{thread_id}/user-data/uploads` |
+| `/mnt/user-data/outputs` | `backend/.deer-flow/threads/{thread_id}/user-data/outputs` |
+| `/mnt/skills` | `deer-flow/skills/` |
+
+### Tool System
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                            Tool Sources                                  │
+└─────────────────────────────────────────────────────────────────────────┘
+
+┌─────────────────────┐  ┌─────────────────────┐  ┌─────────────────────┐
+│   Built-in Tools    │  │  Configured Tools   │  │     MCP Tools       │
+│  (packages/harness/deerflow/tools/)       │  │  (config.yaml)      │  │  (extensions.json)  │
+├─────────────────────┤  ├─────────────────────┤  ├─────────────────────┤
+│ - present_files     │  │ - web_search        │  │ - github            │
+│ - ask_clarification │  │ - web_fetch         │  │ - filesystem        │
+│ - view_image        │  │ - bash              │  │ - postgres          │
+│                     │  │ - read_file         │  │ - brave-search      │
+│                     │  │ - write_file        │  │ - puppeteer         │
+│                     │  │ - str_replace       │  │ - ...               │
+│                     │  │ - ls                │  │                     │
+└─────────────────────┘  └─────────────────────┘  └─────────────────────┘
+           │                       │                       │
+           └───────────────────────┴───────────────────────┘
+                                   │
+                                   ▼
+                      ┌─────────────────────────┐
+                      │   get_available_tools() │
+                      │   (packages/harness/deerflow/tools/__init__)  │
+                      └─────────────────────────┘
+```
+
+### Model Factory
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                          Model Factory                                   │
+│                     (packages/harness/deerflow/models/factory.py)                              │
+└─────────────────────────────────────────────────────────────────────────┘
+
+config.yaml:
+┌─────────────────────────────────────────────────────────────────────────┐
+│ models:                                                                  │
+│   - name: gpt-4                                                         │
+│     display_name: GPT-4                                                 │
+│     use: langchain_openai:ChatOpenAI                                    │
+│     model: gpt-4                                                        │
+│     api_key: $OPENAI_API_KEY                                            │
+│     max_tokens: 4096                                                    │
+│     supports_thinking: false                                            │
+│     supports_vision: true                                               │
+└─────────────────────────────────────────────────────────────────────────┘
+                                   │
+                                   ▼
+                      ┌─────────────────────────┐
+                      │   create_chat_model()   │
+                      │  - name: str            │
+                      │  - thinking_enabled     │
+                      └────────────┬────────────┘
+                                   │
+                                   ▼
+                      ┌─────────────────────────┐
+                      │   resolve_class()       │
+                      │  (reflection system)    │
+                      └────────────┬────────────┘
+                                   │
+                                   ▼
+                      ┌─────────────────────────┐
+                      │   BaseChatModel         │
+                      │  (LangChain instance)   │
+                      └─────────────────────────┘
+```
+
+**Supported Providers**:
+- OpenAI (`langchain_openai:ChatOpenAI`)
+- Anthropic (`langchain_anthropic:ChatAnthropic`)
+- DeepSeek (`langchain_deepseek:ChatDeepSeek`)
+- Custom via LangChain integrations
+
+### MCP Integration
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                          MCP Integration                                 │
+│                        (packages/harness/deerflow/mcp/manager.py)                              │
+└─────────────────────────────────────────────────────────────────────────┘
+
+extensions_config.json:
+┌─────────────────────────────────────────────────────────────────────────┐
+│ {                                                                        │
+│   "mcpServers": {                                                       │
+│     "github": {                                                         │
+│       "enabled": true,                                                  │
+│       "type": "stdio",                                                  │
+│       "command": "npx",                                                 │
+│       "args": ["-y", "@modelcontextprotocol/server-github"],           │
+│       "env": {"GITHUB_TOKEN": "$GITHUB_TOKEN"}                          │
+│     }                                                                   │
+│   }                                                                     │
+│ }                                                                       │
+└─────────────────────────────────────────────────────────────────────────┘
+                                   │
+                                   ▼
+                      ┌─────────────────────────┐
+                      │  MultiServerMCPClient   │
+                      │  (langchain-mcp-adapters)│
+                      └────────────┬────────────┘
+                                   │
+              ┌────────────────────┼────────────────────┐
+              │                    │                    │
+              ▼                    ▼                    ▼
+       ┌───────────┐        ┌───────────┐        ┌───────────┐
+       │  stdio    │        │   SSE     │        │   HTTP    │
+       │ transport │        │ transport │        │ transport │
+       └───────────┘        └───────────┘        └───────────┘
+```
+
+### Skills System
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                          Skills System                                   │
+│                       (packages/harness/deerflow/skills/loader.py)                             │
+└─────────────────────────────────────────────────────────────────────────┘
+
+Directory Structure:
+┌─────────────────────────────────────────────────────────────────────────┐
+│ skills/                                                                  │
+│ ├── public/                        # Public skills (committed)           │
+│ │   ├── pdf-processing/                                                 │
+│ │   │   └── SKILL.md                                                    │
+│ │   ├── frontend-design/                                                │
+│ │   │   └── SKILL.md                                                    │
+│ │   └── ...                                                             │
+│ └── custom/                        # Custom skills (gitignored)          │
+│     └── user-installed/                                                 │
+│         └── SKILL.md                                                    │
+└─────────────────────────────────────────────────────────────────────────┘
+
+SKILL.md Format:
+┌─────────────────────────────────────────────────────────────────────────┐
+│ ---                                                                      │
+│ name: PDF Processing                                                     │
+│ description: Handle PDF documents efficiently                            │
+│ license: MIT                                                            │
+│ allowed-tools:                                                          │
+│   - read_file                                                           │
+│   - write_file                                                          │
+│   - bash                                                                │
+│ ---                                                                      │
+│                                                                          │
+│ # Skill Instructions                                                     │
+│ Content injected into system prompt...                                   │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### Request Flow
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         Request Flow Example                             │
+│                    User sends message to agent                           │
+└─────────────────────────────────────────────────────────────────────────┘
+
+1. Client → Nginx
+   POST /api/langgraph/threads/{thread_id}/runs
+   {"input": {"messages": [{"role": "user", "content": "Hello"}]}}
+
+2. Nginx → LangGraph Server (2024)
+   Proxied to LangGraph server
+
+3. LangGraph Server
+   a. Load/create thread state
+   b. Execute middleware chain:
+      - ThreadDataMiddleware: Set up paths
+      - UploadsMiddleware: Inject file list
+      - SandboxMiddleware: Acquire sandbox
+      - SummarizationMiddleware: Check token limits
+      - TitleMiddleware: Generate title if needed
+      - TodoListMiddleware: Load todos (if plan mode)
+      - ViewImageMiddleware: Process images
+      - ClarificationMiddleware: Check for clarifications
+
+   c. Execute agent:
+      - Model processes messages
+      - May call tools (bash, web_search, etc.)
+      - Tools execute via sandbox
+      - Results added to messages
+
+   d. Stream response via SSE
+
+4. Client receives streaming response
+```
+
+## Data Flow
+
+### File Upload Flow
+
+```
+1. Client uploads file
+   POST /api/threads/{thread_id}/uploads
+   Content-Type: multipart/form-data
+
+2. Gateway receives file
+   - Validates file
+   - Stores in .deer-flow/threads/{thread_id}/user-data/uploads/
+   - If document: converts to Markdown via markitdown
+
+3. Returns response
+   {
+     "files": [{
+       "filename": "doc.pdf",
+       "path": ".deer-flow/.../uploads/doc.pdf",
+       "virtual_path": "/mnt/user-data/uploads/doc.pdf",
+       "artifact_url": "/api/threads/.../artifacts/mnt/.../doc.pdf"
+     }]
+   }
+
+4. Next agent run
+   - UploadsMiddleware lists files
+   - Injects file list into messages
+   - Agent can access via virtual_path
+```
+
+### Thread Cleanup Flow
+
+```
+1. Client deletes conversation via LangGraph
+   DELETE /api/langgraph/threads/{thread_id}
+
+2. Web UI follows up with Gateway cleanup
+   DELETE /api/threads/{thread_id}
+
+3. Gateway removes local DeerFlow-managed files
+   - Deletes .deer-flow/threads/{thread_id}/ recursively
+   - Missing directories are treated as a no-op
+   - Invalid thread IDs are rejected before filesystem access
+```
+
+### Configuration Reload
+
+```
+1. Client updates MCP config
+   PUT /api/mcp/config
+
+2. Gateway writes extensions_config.json
+   - Updates mcpServers section
+   - File mtime changes
+
+3. MCP Manager detects change
+   - get_cached_mcp_tools() checks mtime
+   - If changed: reinitializes MCP client
+   - Loads updated server configurations
+
+4. Next agent run uses new tools
+```
+
+## Security Considerations
+
+### Sandbox Isolation
+
+- Agent code executes within sandbox boundaries
+- Local sandbox: Direct execution (development only)
+- Docker sandbox: Container isolation (production recommended)
+- Path traversal prevention in file operations
+
+### API Security
+
+- Thread isolation: Each thread has separate data directories
+- File validation: Uploads checked for path safety
+- Environment variable resolution: Secrets not stored in config
+
+### MCP Security
+
+- Each MCP server runs in its own process
+- Environment variables resolved at runtime
+- Servers can be enabled/disabled independently
+
+## Performance Considerations
+
+### Caching
+
+- MCP tools cached with file mtime invalidation
+- Configuration loaded once, reloaded on file change
+- Skills parsed once at startup, cached in memory
+
+### Streaming
+
+- SSE used for real-time response streaming
+- Reduces time to first token
+- Enables progress visibility for long operations
+
+### Context Management
+
+- Summarization middleware reduces context when limits approached
+- Configurable triggers: tokens, messages, or fraction
+- Preserves recent messages while summarizing older ones

offline-backend-20260512/backend/docs/AUTH_TEST_DOCKER_GAP.md

@@ -0,0 +1,77 @@
+# Docker Test Gap (Section 七 7.4)
+
+This file documents the only **un-executed** test cases from
+`backend/docs/AUTH_TEST_PLAN.md` after the full release validation pass.
+
+## Why this gap exists
+
+The release validation environment (sg_dev: `10.251.229.92`) **does not have
+a Docker daemon installed**. The TC-DOCKER cases are container-runtime
+behavior tests that need an actual Docker engine to spin up
+`docker/docker-compose.yaml` services.
+
+```bash
+$ ssh sg_dev "which docker; docker --version"
+# (empty)
+# bash: docker: command not found
+```
+
+All other test plan sections were executed against either:
+- The local dev box (Mac, all services running locally), or
+- The deployed sg_dev instance (gateway + frontend + nginx via SSH tunnel)
+
+## Cases not executed
+
+| Case | Title | What it covers | Why not run |
+|---|---|---|---|
+| TC-DOCKER-01 | `users.db` volume persistence | Verify the `DEER_FLOW_HOME` bind mount survives container restart | needs `docker compose up` |
+| TC-DOCKER-02 | Session persistence across container restart | `AUTH_JWT_SECRET` env var keeps cookies valid after `docker compose down && up` | needs `docker compose down/up` |
+| TC-DOCKER-03 | Per-worker rate limiter divergence | Confirms in-process `_login_attempts` dict doesn't share state across `gunicorn` workers (4 by default in the compose file); known limitation, documented | needs multi-worker container |
+| TC-DOCKER-04 | IM channels skip AuthMiddleware | Verify Feishu/Slack/Telegram dispatchers run in-container against `http://langgraph:2024` without going through nginx | needs `docker logs` |
+| TC-DOCKER-05 | Admin credentials surfacing | **Updated post-simplify** — was "log scrape", now "0600 credential file in `DEER_FLOW_HOME`". The file-based behavior is already validated by TC-1.1 + TC-UPG-13 on sg_dev (non-Docker), so the only Docker-specific gap is verifying the volume mount carries the file out to the host | needs container + host volume |
+| TC-DOCKER-06 | Gateway-mode Docker deploy | `./scripts/deploy.sh --gateway` produces a 3-container topology (no `langgraph` container); same auth flow as standard mode | needs `docker compose --profile gateway` |
+
+## Coverage already provided by non-Docker tests
+
+The **auth-relevant** behavior in each Docker case is already exercised by
+the test cases that ran on sg_dev or local:
+
+| Docker case | Auth behavior covered by |
+|---|---|
+| TC-DOCKER-01 (volume persistence) | TC-REENT-01 on sg_dev (admin row survives gateway restart) — same SQLite file, just no container layer between |
+| TC-DOCKER-02 (session persistence) | TC-API-02/03/06 (cookie roundtrip), plus TC-REENT-04 (multi-cookie) — JWT verification is process-state-free, container restart is equivalent to `pkill uvicorn && uv run uvicorn` |
+| TC-DOCKER-03 (per-worker rate limit) | TC-GW-04 + TC-REENT-09 (single-worker rate limit + 5min expiry). The cross-worker divergence is an architectural property of the in-memory dict; no auth code path differs |
+| TC-DOCKER-04 (IM channels skip auth) | Code-level only: `app/channels/manager.py` uses `langgraph_sdk` directly with no cookie handling. The langgraph_auth handler is bypassed by going through SDK, not HTTP |
+| TC-DOCKER-05 (credential surfacing) | TC-1.1 on sg_dev (file at `~/deer-flow/backend/.deer-flow/admin_initial_credentials.txt`, mode 0600, password 22 chars) — the only Docker-unique step is whether the bind mount projects this path onto the host, which is a `docker compose` config check, not a runtime behavior change |
+| TC-DOCKER-06 (gateway-mode container) | Section 七 7.2 covered by TC-GW-01..05 + Section 二 (gateway-mode auth flow on sg_dev) — same Gateway code, container is just a packaging change |
+
+## Reproduction steps when Docker becomes available
+
+Anyone with `docker` + `docker compose` installed can reproduce the gap by
+running the test plan section verbatim. Pre-flight:
+
+```bash
+# Required on the host
+docker --version           # >=24.x
+docker compose version     # plugin >=2.x
+
+# Required env var (otherwise sessions reset on every container restart)
+echo "AUTH_JWT_SECRET=$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')" \
+  >> .env
+
+# Optional: pin DEER_FLOW_HOME to a stable host path
+echo "DEER_FLOW_HOME=$HOME/deer-flow-data" >> .env
+```
+
+Then run TC-DOCKER-01..06 from the test plan as written.
+
+## Decision log
+
+- **Not blocking the release.** The auth-relevant behavior in every Docker
+  case has an already-validated equivalent on bare metal. The gap is purely
+  about *container packaging* details (bind mounts, multi-worker, log
+  collection), not about whether the auth code paths work.
+- **TC-DOCKER-05 was updated in place** in `AUTH_TEST_PLAN.md` to reflect
+  the post-simplify reality (credentials file → 0600 file, no log leak).
+  The old "grep 'Password:' in docker logs" expectation would have failed
+  silently and given a false sense of coverage.

offline-backend-20260512/backend/docs/AUTH_UPGRADE.md

@@ -0,0 +1,129 @@
+# Authentication Upgrade Guide
+
+DeerFlow 内置了认证模块。本文档面向从无认证版本升级的用户。
+
+## 核心概念
+
+认证模块采用**始终强制**策略：
+
+- 首次启动时自动创建 admin 账号，随机密码打印到控制台日志
+- 认证从一开始就是强制的，无竞争窗口
+- 历史对话（升级前创建的 thread）自动迁移到 admin 名下
+
+## 升级步骤
+
+### 1. 更新代码
+
+```bash
+git pull origin main
+cd backend && make install
+```
+
+### 2. 首次启动
+
+```bash
+make dev
+```
+
+控制台会输出：
+
+```
+============================================================
+  Admin account created on first boot
+  Email:    admin@deerflow.dev
+  Password: aB3xK9mN_pQ7rT2w
+  Change it after login: Settings → Account
+============================================================
+```
+
+如果未登录就重启了服务，不用担心——只要 setup 未完成，每次启动都会重置密码并重新打印到控制台。
+
+### 3. 登录
+
+访问 `http://localhost:2026/login`，使用控制台输出的邮箱和密码登录。
+
+### 4. 修改密码
+
+登录后进入 Settings → Account → Change Password。
+
+### 5. 添加用户（可选）
+
+其他用户通过 `/login` 页面注册，自动获得 **user** 角色。每个用户只能看到自己的对话。
+
+## 安全机制
+
+| 机制 | 说明 |
+|------|------|
+| JWT HttpOnly Cookie | Token 不暴露给 JavaScript，防止 XSS 窃取 |
+| CSRF Double Submit Cookie | 所有 POST/PUT/DELETE 请求需携带 `X-CSRF-Token` |
+| bcrypt 密码哈希 | 密码不以明文存储 |
+| 多租户隔离 | 用户只能访问自己的 thread |
+| HTTPS 自适应 | 检测 `x-forwarded-proto`，自动设置 `Secure` cookie 标志 |
+
+## 常见操作
+
+### 忘记密码
+
+```bash
+cd backend
+
+# 重置 admin 密码
+python -m app.gateway.auth.reset_admin
+
+# 重置指定用户密码
+python -m app.gateway.auth.reset_admin --email user@example.com
+```
+
+会输出新的随机密码。
+
+### 完全重置
+
+删除用户数据库，重启后自动创建新 admin：
+
+```bash
+rm -f backend/.deer-flow/users.db
+# 重启服务，控制台输出新密码
+```
+
+## 数据存储
+
+| 文件 | 内容 |
+|------|------|
+| `.deer-flow/users.db` | SQLite 用户数据库（密码哈希、角色） |
+| `.env` 中的 `AUTH_JWT_SECRET` | JWT 签名密钥（未设置时自动生成临时密钥，重启后 session 失效） |
+
+### 生产环境建议
+
+```bash
+# 生成持久化 JWT 密钥，避免重启后所有用户需重新登录
+python -c "import secrets; print(secrets.token_urlsafe(32))"
+# 将输出添加到 .env：
+# AUTH_JWT_SECRET=<生成的密钥>
+```
+
+## API 端点
+
+| 端点 | 方法 | 说明 |
+|------|------|------|
+| `/api/v1/auth/login/local` | POST | 邮箱密码登录（OAuth2 form） |
+| `/api/v1/auth/register` | POST | 注册新用户（user 角色） |
+| `/api/v1/auth/logout` | POST | 登出（清除 cookie） |
+| `/api/v1/auth/me` | GET | 获取当前用户信息 |
+| `/api/v1/auth/change-password` | POST | 修改密码 |
+| `/api/v1/auth/setup-status` | GET | 检查 admin 是否存在 |
+
+## 兼容性
+
+- **标准模式**（`make dev`）：完全兼容，admin 自动创建
+- **Gateway 模式**（`make dev-pro`）：完全兼容
+- **Docker 部署**：完全兼容，`.deer-flow/users.db` 需持久化卷挂载
+- **IM 渠道**（Feishu/Slack/Telegram）：通过 LangGraph SDK 通信，不经过认证层
+- **DeerFlowClient**（嵌入式）：不经过 HTTP，不受认证影响
+
+## 故障排查
+
+| 症状 | 原因 | 解决 |
+|------|------|------|
+| 启动后没看到密码 | admin 已存在（非首次启动） | 用 `reset_admin` 重置，或删 `users.db` |
+| 登录后 POST 返回 403 | CSRF token 缺失 | 确认前端已更新 |
+| 重启后需要重新登录 | `AUTH_JWT_SECRET` 未持久化 | 在 `.env` 中设置固定密钥 |

offline-backend-20260512/backend/docs/AUTO_TITLE_GENERATION.md

@@ -0,0 +1,258 @@
+# 自动 Thread Title 生成功能
+
+## 功能说明
+
+自动为对话线程生成标题，在用户首次提问并收到回复后自动触发。
+
+## 实现方式
+
+使用 `TitleMiddleware` 在 `after_model` 钩子中：
+1. 检测是否是首次对话（1个用户消息 + 1个助手回复）
+2. 检查 state 是否已有 title
+3. 调用 LLM 生成简洁的标题（默认最多6个词）
+4. 将 title 存储到 `ThreadState` 中（会被 checkpointer 持久化）
+
+TitleMiddleware 会先把 LangChain message content 里的结构化 block/list 内容归一化为纯文本，再拼到 title prompt 里，避免把 Python/JSON 的原始 repr 泄漏到标题生成模型。
+
+## ⚠️ 重要：存储机制
+
+### Title 存储位置
+
+Title 存储在 **`ThreadState.title`** 中，而非 thread metadata：
+
+```python
+class ThreadState(AgentState):
+    sandbox: SandboxState | None = None
+    title: str | None = None  # ✅ Title stored here
+```
+
+### 持久化说明
+
+| 部署方式 | 持久化 | 说明 |
+|---------|--------|------|
+| **LangGraph Studio (本地)** | ❌ 否 | 仅内存存储，重启后丢失 |
+| **LangGraph Platform** | ✅ 是 | 自动持久化到数据库 |
+| **自定义 + Checkpointer** | ✅ 是 | 需配置 PostgreSQL/SQLite checkpointer |
+
+### 如何启用持久化
+
+如果需要在本地开发时也持久化 title，需要配置 checkpointer：
+
+```python
+# 在 langgraph.json 同级目录创建 checkpointer.py
+from langgraph.checkpoint.postgres import PostgresSaver
+
+checkpointer = PostgresSaver.from_conn_string(
+    "postgresql://user:pass@localhost/dbname"
+)
+```
+
+然后在 `langgraph.json` 中引用：
+
+```json
+{
+  "graphs": {
+    "lead_agent": "deerflow.agents:lead_agent"
+  },
+  "checkpointer": "checkpointer:checkpointer"
+}
+```
+
+## 配置
+
+在 `config.yaml` 中添加（可选）：
+
+```yaml
+title:
+  enabled: true
+  max_words: 6
+  max_chars: 60
+  model_name: null  # 使用默认模型
+```
+
+或在代码中配置：
+
+```python
+from deerflow.config.title_config import TitleConfig, set_title_config
+
+set_title_config(TitleConfig(
+    enabled=True,
+    max_words=8,
+    max_chars=80,
+))
+```
+
+## 客户端使用
+
+### 获取 Thread Title
+
+```typescript
+// 方式1: 从 thread state 获取
+const state = await client.threads.getState(threadId);
+const title = state.values.title || "New Conversation";
+
+// 方式2: 监听 stream 事件
+for await (const chunk of client.runs.stream(threadId, assistantId, {
+  input: { messages: [{ role: "user", content: "Hello" }] }
+})) {
+  if (chunk.event === "values" && chunk.data.title) {
+    console.log("Title:", chunk.data.title);
+  }
+}
+```
+
+### 显示 Title
+
+```typescript
+// 在对话列表中显示
+function ConversationList() {
+  const [threads, setThreads] = useState([]);
+
+  useEffect(() => {
+    async function loadThreads() {
+      const allThreads = await client.threads.list();
+      
+      // 获取每个 thread 的 state 来读取 title
+      const threadsWithTitles = await Promise.all(
+        allThreads.map(async (t) => {
+          const state = await client.threads.getState(t.thread_id);
+          return {
+            id: t.thread_id,
+            title: state.values.title || "New Conversation",
+            updatedAt: t.updated_at,
+          };
+        })
+      );
+      
+      setThreads(threadsWithTitles);
+    }
+    loadThreads();
+  }, []);
+
+  return (
+    <ul>
+      {threads.map(thread => (
+        <li key={thread.id}>
+          <a href={`/chat/${thread.id}`}>{thread.title}</a>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+## 工作流程
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Client
+    participant LangGraph
+    participant TitleMiddleware
+    participant LLM
+    participant Checkpointer
+
+    User->>Client: 发送首条消息
+    Client->>LangGraph: POST /threads/{id}/runs
+    LangGraph->>Agent: 处理消息
+    Agent-->>LangGraph: 返回回复
+    LangGraph->>TitleMiddleware: after_agent()
+    TitleMiddleware->>TitleMiddleware: 检查是否需要生成 title
+    TitleMiddleware->>LLM: 生成 title
+    LLM-->>TitleMiddleware: 返回 title
+    TitleMiddleware->>LangGraph: return {"title": "..."}
+    LangGraph->>Checkpointer: 保存 state (含 title)
+    LangGraph-->>Client: 返回响应
+    Client->>Client: 从 state.values.title 读取
+```
+
+## 优势
+
+✅ **可靠持久化** - 使用 LangGraph 的 state 机制，自动持久化  
+✅ **完全后端处理** - 客户端无需额外逻辑  
+✅ **自动触发** - 首次对话后自动生成  
+✅ **可配置** - 支持自定义长度、模型等  
+✅ **容错性强** - 失败时使用 fallback 策略  
+✅ **架构一致** - 与现有 SandboxMiddleware 保持一致  
+
+## 注意事项
+
+1. **读取方式不同**：Title 在 `state.values.title` 而非 `thread.metadata.title`
+2. **性能考虑**：title 生成会增加约 0.5-1 秒延迟，可通过使用更快的模型优化
+3. **并发安全**：middleware 在 agent 执行后运行，不会阻塞主流程
+4. **Fallback 策略**：如果 LLM 调用失败，会使用用户消息的前几个词作为 title
+
+## 测试
+
+```python
+# 测试 title 生成
+import pytest
+from deerflow.agents.title_middleware import TitleMiddleware
+
+def test_title_generation():
+    # TODO: 添加单元测试
+    pass
+```
+
+## 故障排查
+
+### Title 没有生成
+
+1. 检查配置是否启用：`get_title_config().enabled == True`
+2. 检查日志：查找 "Generated thread title" 或错误信息
+3. 确认是首次对话：只有 1 个用户消息和 1 个助手回复时才会触发
+
+### Title 生成但客户端看不到
+
+1. 确认读取位置：应该从 `state.values.title` 读取，而非 `thread.metadata.title`
+2. 检查 API 响应：确认 state 中包含 title 字段
+3. 尝试重新获取 state：`client.threads.getState(threadId)`
+
+### Title 重启后丢失
+
+1. 检查是否配置了 checkpointer（本地开发需要）
+2. 确认部署方式：LangGraph Platform 会自动持久化
+3. 查看数据库：确认 checkpointer 正常工作
+
+## 架构设计
+
+### 为什么使用 State 而非 Metadata？
+
+| 特性 | State | Metadata |
+|------|-------|----------|
+| **持久化** | ✅ 自动（通过 checkpointer） | ⚠️ 取决于实现 |
+| **版本控制** | ✅ 支持时间旅行 | ❌ 不支持 |
+| **类型安全** | ✅ TypedDict 定义 | ❌ 任意字典 |
+| **可追溯** | ✅ 每次更新都记录 | ⚠️ 只有最新值 |
+| **标准化** | ✅ LangGraph 核心机制 | ⚠️ 扩展功能 |
+
+### 实现细节
+
+```python
+# TitleMiddleware 核心逻辑
+@override
+def after_agent(self, state: TitleMiddlewareState, runtime: Runtime) -> dict | None:
+    """Generate and set thread title after the first agent response."""
+    if self._should_generate_title(state, runtime):
+        title = self._generate_title(runtime)
+        print(f"Generated thread title: {title}")
+        
+        # ✅ 返回 state 更新，会被 checkpointer 自动持久化
+        return {"title": title}
+    
+    return None
+```
+
+## 相关文件
+
+- [`packages/harness/deerflow/agents/thread_state.py`](../packages/harness/deerflow/agents/thread_state.py) - ThreadState 定义
+- [`packages/harness/deerflow/agents/middlewares/title_middleware.py`](../packages/harness/deerflow/agents/middlewares/title_middleware.py) - TitleMiddleware 实现
+- [`packages/harness/deerflow/config/title_config.py`](../packages/harness/deerflow/config/title_config.py) - 配置管理
+- [`config.yaml`](../../config.example.yaml) - 配置文件
+- [`packages/harness/deerflow/agents/lead_agent/agent.py`](../packages/harness/deerflow/agents/lead_agent/agent.py) - Middleware 注册
+
+## 参考资料
+
+- [LangGraph Checkpointer 文档](https://langchain-ai.github.io/langgraph/concepts/persistence/)
+- [LangGraph State 管理](https://langchain-ai.github.io/langgraph/concepts/low_level/#state)
+- [LangGraph Middleware](https://langchain-ai.github.io/langgraph/concepts/middleware/)

offline-backend-20260512/backend/docs/CONFIGURATION.md

@@ -0,0 +1,376 @@
+# Configuration Guide
+
+This guide explains how to configure DeerFlow for your environment.
+
+## Config Versioning
+
+`config.example.yaml` contains a `config_version` field that tracks schema changes. When the example version is higher than your local `config.yaml`, the application emits a startup warning:
+
+```
+WARNING - Your config.yaml (version 0) is outdated — the latest version is 1.
+Run `make config-upgrade` to merge new fields into your config.
+```
+
+- **Missing `config_version`** in your config is treated as version 0.
+- Run `make config-upgrade` to auto-merge missing fields (your existing values are preserved, a `.bak` backup is created).
+- When changing the config schema, bump `config_version` in `config.example.yaml`.
+
+## Configuration Sections
+
+### Models
+
+Configure the LLM models available to the agent:
+
+```yaml
+models:
+  - name: gpt-4                    # Internal identifier
+    display_name: GPT-4            # Human-readable name
+    use: langchain_openai:ChatOpenAI  # LangChain class path
+    model: gpt-4                   # Model identifier for API
+    api_key: $OPENAI_API_KEY       # API key (use env var)
+    max_tokens: 4096               # Max tokens per request
+    temperature: 0.7               # Sampling temperature
+```
+
+**Supported Providers**:
+- OpenAI (`langchain_openai:ChatOpenAI`)
+- Anthropic (`langchain_anthropic:ChatAnthropic`)
+- DeepSeek (`langchain_deepseek:ChatDeepSeek`)
+- Claude Code OAuth (`deerflow.models.claude_provider:ClaudeChatModel`)
+- Codex CLI (`deerflow.models.openai_codex_provider:CodexChatModel`)
+- Any LangChain-compatible provider
+
+CLI-backed provider examples:
+
+```yaml
+models:
+  - name: gpt-5.4
+    display_name: GPT-5.4 (Codex CLI)
+    use: deerflow.models.openai_codex_provider:CodexChatModel
+    model: gpt-5.4
+    supports_thinking: true
+    supports_reasoning_effort: true
+
+  - name: claude-sonnet-4.6
+    display_name: Claude Sonnet 4.6 (Claude Code OAuth)
+    use: deerflow.models.claude_provider:ClaudeChatModel
+    model: claude-sonnet-4-6
+    max_tokens: 4096
+    supports_thinking: true
+```
+
+**Auth behavior for CLI-backed providers**:
+- `CodexChatModel` loads Codex CLI auth from `~/.codex/auth.json`
+- The Codex Responses endpoint currently rejects `max_tokens` and `max_output_tokens`, so `CodexChatModel` does not expose a request-level token cap
+- `ClaudeChatModel` accepts `CLAUDE_CODE_OAUTH_TOKEN`, `ANTHROPIC_AUTH_TOKEN`, `CLAUDE_CODE_OAUTH_TOKEN_FILE_DESCRIPTOR`, `CLAUDE_CODE_CREDENTIALS_PATH`, or plaintext `~/.claude/.credentials.json`
+- On macOS, DeerFlow does not probe Keychain automatically. Use `scripts/export_claude_code_oauth.py` to export Claude Code auth explicitly when needed
+
+To use OpenAI's `/v1/responses` endpoint with LangChain, keep using `langchain_openai:ChatOpenAI` and set:
+
+```yaml
+models:
+  - name: gpt-5-responses
+    display_name: GPT-5 (Responses API)
+    use: langchain_openai:ChatOpenAI
+    model: gpt-5
+    api_key: $OPENAI_API_KEY
+    use_responses_api: true
+    output_version: responses/v1
+```
+
+For OpenAI-compatible gateways (for example Novita or OpenRouter), keep using `langchain_openai:ChatOpenAI` and set `base_url`:
+
+```yaml
+models:
+  - name: novita-deepseek-v3.2
+    display_name: Novita DeepSeek V3.2
+    use: langchain_openai:ChatOpenAI
+    model: deepseek/deepseek-v3.2
+    api_key: $NOVITA_API_KEY
+    base_url: https://api.novita.ai/openai
+    supports_thinking: true
+    when_thinking_enabled:
+      extra_body:
+        thinking:
+          type: enabled
+
+  - name: minimax-m2.5
+    display_name: MiniMax M2.5
+    use: langchain_openai:ChatOpenAI
+    model: MiniMax-M2.5
+    api_key: $MINIMAX_API_KEY
+    base_url: https://api.minimax.io/v1
+    max_tokens: 4096
+    temperature: 1.0  # MiniMax requires temperature in (0.0, 1.0]
+    supports_vision: true
+
+  - name: minimax-m2.5-highspeed
+    display_name: MiniMax M2.5 Highspeed
+    use: langchain_openai:ChatOpenAI
+    model: MiniMax-M2.5-highspeed
+    api_key: $MINIMAX_API_KEY
+    base_url: https://api.minimax.io/v1
+    max_tokens: 4096
+    temperature: 1.0  # MiniMax requires temperature in (0.0, 1.0]
+    supports_vision: true
+  - name: openrouter-gemini-2.5-flash
+    display_name: Gemini 2.5 Flash (OpenRouter)
+    use: langchain_openai:ChatOpenAI
+    model: google/gemini-2.5-flash-preview
+    api_key: $OPENAI_API_KEY
+    base_url: https://openrouter.ai/api/v1
+```
+
+If your OpenRouter key lives in a different environment variable name, point `api_key` at that variable explicitly (for example `api_key: $OPENROUTER_API_KEY`).
+
+**Thinking Models**:
+Some models support "thinking" mode for complex reasoning:
+
+```yaml
+models:
+  - name: deepseek-v3
+    supports_thinking: true
+    when_thinking_enabled:
+      extra_body:
+        thinking:
+          type: enabled
+```
+
+**Gemini with thinking via OpenAI-compatible gateway**:
+
+When routing Gemini through an OpenAI-compatible proxy (Vertex AI OpenAI compat endpoint, AI Studio, or third-party gateways) with thinking enabled, the API attaches a `thought_signature` to each tool-call object returned in the response.  Every subsequent request that replays those assistant messages **must** echo those signatures back on the tool-call entries or the API returns:
+
+```
+HTTP 400 INVALID_ARGUMENT: function call `<tool>` in the N. content block is
+missing a `thought_signature`.
+```
+
+Standard `langchain_openai:ChatOpenAI` silently drops `thought_signature` when serialising messages.  Use `deerflow.models.patched_openai:PatchedChatOpenAI` instead — it re-injects the tool-call signatures (sourced from `AIMessage.additional_kwargs["tool_calls"]`) into every outgoing payload:
+
+```yaml
+models:
+  - name: gemini-2.5-pro-thinking
+    display_name: Gemini 2.5 Pro (Thinking)
+    use: deerflow.models.patched_openai:PatchedChatOpenAI
+    model: google/gemini-2.5-pro-preview   # model name as expected by your gateway
+    api_key: $GEMINI_API_KEY
+    base_url: https://<your-openai-compat-gateway>/v1
+    max_tokens: 16384
+    supports_thinking: true
+    supports_vision: true
+    when_thinking_enabled:
+      extra_body:
+        thinking:
+          type: enabled
+```
+
+For Gemini accessed **without** thinking (e.g. via OpenRouter where thinking is not activated), the plain `langchain_openai:ChatOpenAI` with `supports_thinking: false` is sufficient and no patch is needed.
+
+### Tool Groups
+
+Organize tools into logical groups:
+
+```yaml
+tool_groups:
+  - name: web          # Web browsing and search
+  - name: file:read    # Read-only file operations
+  - name: file:write   # Write file operations
+  - name: bash         # Shell command execution
+```
+
+### Tools
+
+Configure specific tools available to the agent:
+
+```yaml
+tools:
+  - name: web_search
+    group: web
+    use: deerflow.community.tavily.tools:web_search_tool
+    max_results: 5
+    # api_key: $TAVILY_API_KEY  # Optional
+```
+
+**Built-in Tools**:
+- `web_search` - Search the web (DuckDuckGo, Tavily, Exa, InfoQuest, Firecrawl)
+- `web_fetch` - Fetch web pages (Jina AI, Exa, InfoQuest, Firecrawl)
+- `ls` - List directory contents
+- `read_file` - Read file contents
+- `write_file` - Write file contents
+- `str_replace` - String replacement in files
+- `bash` - Execute bash commands
+
+### Sandbox
+
+DeerFlow supports multiple sandbox execution modes. Configure your preferred mode in `config.yaml`:
+
+**Local Execution** (runs sandbox code directly on the host machine):
+```yaml
+sandbox:
+   use: deerflow.sandbox.local:LocalSandboxProvider # Local execution
+   allow_host_bash: false # default; host bash is disabled unless explicitly re-enabled
+```
+
+**Docker Execution** (runs sandbox code in isolated Docker containers):
+```yaml
+sandbox:
+   use: deerflow.community.aio_sandbox:AioSandboxProvider # Docker-based sandbox
+```
+
+**Docker Execution with Kubernetes** (runs sandbox code in Kubernetes pods via provisioner service):
+
+This mode runs each sandbox in an isolated Kubernetes Pod on your **host machine's cluster**. Requires Docker Desktop K8s, OrbStack, or similar local K8s setup.
+
+```yaml
+sandbox:
+   use: deerflow.community.aio_sandbox:AioSandboxProvider
+   provisioner_url: http://provisioner:8002
+```
+
+When using Docker development (`make docker-start`), DeerFlow starts the `provisioner` service only if this provisioner mode is configured. In local or plain Docker sandbox modes, `provisioner` is skipped.
+
+See [Provisioner Setup Guide](../../docker/provisioner/README.md) for detailed configuration, prerequisites, and troubleshooting.
+
+Choose between local execution or Docker-based isolation:
+
+**Option 1: Local Sandbox** (default, simpler setup):
+```yaml
+sandbox:
+  use: deerflow.sandbox.local:LocalSandboxProvider
+  allow_host_bash: false
+```
+
+`allow_host_bash` is intentionally `false` by default. DeerFlow's local sandbox is a host-side convenience mode, not a secure shell isolation boundary. If you need `bash`, prefer `AioSandboxProvider`. Only set `allow_host_bash: true` for fully trusted single-user local workflows.
+
+**Option 2: Docker Sandbox** (isolated, more secure):
+```yaml
+sandbox:
+  use: deerflow.community.aio_sandbox:AioSandboxProvider
+  port: 8080
+  auto_start: true
+  container_prefix: deer-flow-sandbox
+
+  # Optional: Additional mounts
+  mounts:
+    - host_path: /path/on/host
+      container_path: /path/in/container
+      read_only: false
+```
+
+When you configure `sandbox.mounts`, DeerFlow exposes those `container_path` values in the agent prompt so the agent can discover and operate on mounted directories directly instead of assuming everything must live under `/mnt/user-data`.
+
+For bare-metal Docker sandbox runs that use localhost, DeerFlow binds the sandbox HTTP port to `127.0.0.1` by default so it is not exposed on every host interface. Docker-outside-of-Docker deployments that connect through `host.docker.internal` keep the broad legacy bind for compatibility. Set `DEER_FLOW_SANDBOX_BIND_HOST` explicitly if your deployment needs a different bind address.
+
+### Skills
+
+Configure the skills directory for specialized workflows:
+
+```yaml
+skills:
+  # Host path (optional, default: ../skills)
+  path: /custom/path/to/skills
+
+  # Container mount path (default: /mnt/skills)
+  container_path: /mnt/skills
+```
+
+**How Skills Work**:
+- Skills are stored in `deer-flow/skills/{public,custom}/`
+- Each skill has a `SKILL.md` file with metadata
+- Skills are automatically discovered and loaded
+- Available in both local and Docker sandbox via path mapping
+
+**Per-Agent Skill Filtering**:
+Custom agents can restrict which skills they load by defining a `skills` field in their `config.yaml` (located at `workspace/agents/<agent_name>/config.yaml`):
+- **Omitted or `null`**: Loads all globally enabled skills (default fallback).
+- **`[]` (empty list)**: Disables all skills for this specific agent.
+- **`["skill-name"]`**: Loads only the explicitly specified skills.
+
+### Title Generation
+
+Automatic conversation title generation:
+
+```yaml
+title:
+  enabled: true
+  max_words: 6
+  max_chars: 60
+  model_name: null  # Use first model in list
+```
+
+### GitHub API Token (Optional for GitHub Deep Research Skill)
+
+The default GitHub API rate limits are quite restrictive. For frequent project research, we recommend configuring a personal access token (PAT) with read-only permissions.
+
+**Configuration Steps**:
+1. Uncomment the `GITHUB_TOKEN` line in the `.env` file and add your personal access token
+2. Restart the DeerFlow service to apply changes
+
+## Environment Variables
+
+DeerFlow supports environment variable substitution using the `$` prefix:
+
+```yaml
+models:
+  - api_key: $OPENAI_API_KEY  # Reads from environment
+```
+
+**Common Environment Variables**:
+- `OPENAI_API_KEY` - OpenAI API key
+- `ANTHROPIC_API_KEY` - Anthropic API key
+- `DEEPSEEK_API_KEY` - DeepSeek API key
+- `NOVITA_API_KEY` - Novita API key (OpenAI-compatible endpoint)
+- `TAVILY_API_KEY` - Tavily search API key
+- `DEER_FLOW_PROJECT_ROOT` - Project root for relative runtime paths
+- `DEER_FLOW_CONFIG_PATH` - Custom config file path
+- `DEER_FLOW_EXTENSIONS_CONFIG_PATH` - Custom extensions config file path
+- `DEER_FLOW_HOME` - Runtime state directory (defaults to `.deer-flow` under the project root)
+- `DEER_FLOW_SKILLS_PATH` - Skills directory when `skills.path` is omitted
+- `GATEWAY_ENABLE_DOCS` - Set to `false` to disable Swagger UI (`/docs`), ReDoc (`/redoc`), and OpenAPI schema (`/openapi.json`) endpoints (default: `true`)
+
+## Configuration Location
+
+The configuration file should be placed in the **project root directory** (`deer-flow/config.yaml`). Set `DEER_FLOW_PROJECT_ROOT` when the process may start from another working directory, or set `DEER_FLOW_CONFIG_PATH` to point at a specific file.
+
+## Configuration Priority
+
+DeerFlow searches for configuration in this order:
+
+1. Path specified in code via `config_path` argument
+2. Path from `DEER_FLOW_CONFIG_PATH` environment variable
+3. `config.yaml` under `DEER_FLOW_PROJECT_ROOT`, or under the current working directory when `DEER_FLOW_PROJECT_ROOT` is unset
+4. Legacy backend/repository-root locations for monorepo compatibility
+
+## Best Practices
+
+1. **Place `config.yaml` in project root** - Set `DEER_FLOW_PROJECT_ROOT` if the runtime starts elsewhere
+2. **Never commit `config.yaml`** - It's already in `.gitignore`
+3. **Use environment variables for secrets** - Don't hardcode API keys
+4. **Keep `config.example.yaml` updated** - Document all new options
+5. **Test configuration changes locally** - Before deploying
+6. **Use Docker sandbox for production** - Better isolation and security
+
+## Troubleshooting
+
+### "Config file not found"
+- Ensure `config.yaml` exists in the **project root** directory (`deer-flow/config.yaml`)
+- If the runtime starts outside the project root, set `DEER_FLOW_PROJECT_ROOT`
+- Alternatively, set `DEER_FLOW_CONFIG_PATH` environment variable to custom location
+
+### "Invalid API key"
+- Verify environment variables are set correctly
+- Check that `$` prefix is used for env var references
+
+### "Skills not loading"
+- Check that `deer-flow/skills/` directory exists
+- Verify skills have valid `SKILL.md` files
+- Check `skills.path` or `DEER_FLOW_SKILLS_PATH` if using a custom path
+
+### "Docker sandbox fails to start"
+- Ensure Docker is running
+- Check port 8080 (or configured port) is available
+- Verify Docker image is accessible
+
+## Examples
+
+See `config.example.yaml` for complete examples of all configuration options.

offline-backend-20260512/backend/docs/FILE_UPLOAD.md

@@ -0,0 +1,314 @@
+# 文件上传功能
+
+## 概述
+
+DeerFlow 后端提供了完整的文件上传功能，支持多文件上传，并可选地将 Office 文档和 PDF 转换为 Markdown 格式。
+
+## 功能特性
+
+- ✅ 支持多文件同时上传
+- ✅ 可选地转换文档为 Markdown（PDF、PPT、Excel、Word）
+- ✅ 文件存储在线程隔离的目录中
+- ✅ Agent 自动感知已上传的文件
+- ✅ 支持文件列表查询和删除
+
+## API 端点
+
+### 1. 上传文件
+```
+POST /api/threads/{thread_id}/uploads
+```
+
+**请求体：** `multipart/form-data`
+- `files`: 一个或多个文件
+
+网关会在应用层限制上传规模，默认最多 10 个文件、单文件 50 MiB、单次请求总计 100 MiB。可通过 `config.yaml` 的 `uploads.max_files`、`uploads.max_file_size`、`uploads.max_total_size` 调整；前端会读取同一组限制并在选择文件时提示，超过限制时后端返回 `413 Payload Too Large`。
+
+**响应：**
+```json
+{
+  "success": true,
+  "files": [
+    {
+      "filename": "document.pdf",
+      "size": 1234567,
+      "path": ".deer-flow/threads/{thread_id}/user-data/uploads/document.pdf",
+      "virtual_path": "/mnt/user-data/uploads/document.pdf",
+      "artifact_url": "/api/threads/{thread_id}/artifacts/mnt/user-data/uploads/document.pdf",
+      "markdown_file": "document.md",
+      "markdown_path": ".deer-flow/threads/{thread_id}/user-data/uploads/document.md",
+      "markdown_virtual_path": "/mnt/user-data/uploads/document.md",
+      "markdown_artifact_url": "/api/threads/{thread_id}/artifacts/mnt/user-data/uploads/document.md"
+    }
+  ],
+  "message": "Successfully uploaded 1 file(s)"
+}
+```
+
+**路径说明：**
+- `path`: 实际文件系统路径（相对于 `backend/` 目录）
+- `virtual_path`: Agent 在沙箱中使用的虚拟路径
+- `artifact_url`: 前端通过 HTTP 访问文件的 URL
+
+### 2. 查询上传限制
+```
+GET /api/threads/{thread_id}/uploads/limits
+```
+
+返回网关当前生效的上传限制，供前端在用户选择文件前提示和拦截。
+
+**响应：**
+```json
+{
+  "max_files": 10,
+  "max_file_size": 52428800,
+  "max_total_size": 104857600
+}
+```
+
+### 3. 列出已上传文件
+```
+GET /api/threads/{thread_id}/uploads/list
+```
+
+**响应：**
+```json
+{
+  "files": [
+    {
+      "filename": "document.pdf",
+      "size": 1234567,
+      "path": ".deer-flow/threads/{thread_id}/user-data/uploads/document.pdf",
+      "virtual_path": "/mnt/user-data/uploads/document.pdf",
+      "artifact_url": "/api/threads/{thread_id}/artifacts/mnt/user-data/uploads/document.pdf",
+      "extension": ".pdf",
+      "modified": 1705997600.0
+    }
+  ],
+  "count": 1
+}
+```
+
+### 4. 删除文件
+```
+DELETE /api/threads/{thread_id}/uploads/{filename}
+```
+
+**响应：**
+```json
+{
+  "success": true,
+  "message": "Deleted document.pdf"
+}
+```
+
+## 支持的文档格式
+
+以下格式在显式启用 `uploads.auto_convert_documents: true` 时会自动转换为 Markdown：
+- PDF (`.pdf`)
+- PowerPoint (`.ppt`, `.pptx`)
+- Excel (`.xls`, `.xlsx`)
+- Word (`.doc`, `.docx`)
+
+转换后的 Markdown 文件会保存在同一目录下，文件名为原文件名 + `.md` 扩展名。
+
+默认情况下，自动转换是关闭的，以避免在网关主机上对不受信任的 Office/PDF 上传执行解析。只有在受信任部署中明确接受此风险时，才应将 `uploads.auto_convert_documents` 设置为 `true`。
+
+## Agent 集成
+
+### 自动文件列举
+
+Agent 在每次请求时会自动收到已上传文件的列表，格式如下：
+
+```xml
+<uploaded_files>
+The following files have been uploaded and are available for use:
+
+- document.pdf (1.2 MB)
+  Path: /mnt/user-data/uploads/document.pdf
+
+- document.md (45.3 KB)
+  Path: /mnt/user-data/uploads/document.md
+
+You can read these files using the `read_file` tool with the paths shown above.
+</uploaded_files>
+```
+
+### 使用上传的文件
+
+Agent 在沙箱中运行，使用虚拟路径访问文件。Agent 可以直接使用 `read_file` 工具读取上传的文件：
+
+```python
+# 读取原始 PDF（如果支持）
+read_file(path="/mnt/user-data/uploads/document.pdf")
+
+# 读取转换后的 Markdown（推荐）
+read_file(path="/mnt/user-data/uploads/document.md")
+```
+
+**路径映射关系：**
+- Agent 使用：`/mnt/user-data/uploads/document.pdf`（虚拟路径）
+- 实际存储：`backend/.deer-flow/threads/{thread_id}/user-data/uploads/document.pdf`
+- 前端访问：`/api/threads/{thread_id}/artifacts/mnt/user-data/uploads/document.pdf`（HTTP URL）
+
+上传流程采用“线程目录优先”策略：
+- 先写入 `backend/.deer-flow/threads/{thread_id}/user-data/uploads/` 作为权威存储
+- 本地沙箱（`sandbox_id=local`）直接使用线程目录内容
+- 非本地沙箱会额外同步到 `/mnt/user-data/uploads/*`，确保运行时可见
+
+## 测试示例
+
+### 使用 curl 测试
+
+```bash
+# 1. 上传单个文件
+curl -X POST http://localhost:2026/api/threads/test-thread/uploads \
+  -F "files=@/path/to/document.pdf"
+
+# 2. 上传多个文件
+curl -X POST http://localhost:2026/api/threads/test-thread/uploads \
+  -F "files=@/path/to/document.pdf" \
+  -F "files=@/path/to/presentation.pptx" \
+  -F "files=@/path/to/spreadsheet.xlsx"
+
+# 3. 列出已上传文件
+curl http://localhost:2026/api/threads/test-thread/uploads/list
+
+# 4. 删除文件
+curl -X DELETE http://localhost:2026/api/threads/test-thread/uploads/document.pdf
+```
+
+### 使用 Python 测试
+
+```python
+import requests
+
+thread_id = "test-thread"
+base_url = "http://localhost:2026"
+
+# 上传文件
+files = [
+    ("files", open("document.pdf", "rb")),
+    ("files", open("presentation.pptx", "rb")),
+]
+response = requests.post(
+    f"{base_url}/api/threads/{thread_id}/uploads",
+    files=files
+)
+print(response.json())
+
+# 列出文件
+response = requests.get(f"{base_url}/api/threads/{thread_id}/uploads/list")
+print(response.json())
+
+# 删除文件
+response = requests.delete(
+    f"{base_url}/api/threads/{thread_id}/uploads/document.pdf"
+)
+print(response.json())
+```
+
+## 文件存储结构
+
+```
+backend/.deer-flow/threads/
+└── {thread_id}/
+    └── user-data/
+        └── uploads/
+            ├── document.pdf          # 原始文件
+            ├── document.md           # 转换后的 Markdown
+            ├── presentation.pptx
+            ├── presentation.md
+            └── ...
+```
+
+## 限制
+
+- 最大文件大小：100MB（可在 nginx.conf 中配置 `client_max_body_size`）
+- 文件名安全性：系统会自动验证文件路径，防止目录遍历攻击
+- 线程隔离：每个线程的上传文件相互隔离，无法跨线程访问
+- 自动文档转换默认关闭；如需启用，需在 `config.yaml` 中显式设置 `uploads.auto_convert_documents: true`
+
+## 技术实现
+
+### 组件
+
+1. **Upload Router** (`app/gateway/routers/uploads.py`)
+   - 处理文件上传、列表、删除请求
+   - 使用 markitdown 转换文档
+
+2. **Uploads Middleware** (`packages/harness/deerflow/agents/middlewares/uploads_middleware.py`)
+   - 在每次 Agent 请求前注入文件列表
+   - 自动生成格式化的文件列表消息
+
+3. **Nginx 配置** (`nginx.conf`)
+   - 路由上传请求到 Gateway API
+   - 配置大文件上传支持
+
+### 依赖
+
+- `markitdown>=0.0.1a2` - 文档转换
+- `python-multipart>=0.0.20` - 文件上传处理
+
+## 故障排查
+
+### 文件上传失败
+
+1. 检查文件大小是否超过限制
+2. 检查 Gateway API 是否正常运行
+3. 检查磁盘空间是否充足
+4. 查看 Gateway 日志：`make gateway`
+
+### 文档转换失败
+
+1. 检查 markitdown 是否正确安装：`uv run python -c "import markitdown"`
+2. 查看日志中的具体错误信息
+3. 某些损坏或加密的文档可能无法转换，但原文件仍会保存
+
+### Agent 看不到上传的文件
+
+1. 确认 UploadsMiddleware 已在 agent.py 中注册
+2. 检查 thread_id 是否正确
+3. 确认文件确实已上传到 `backend/.deer-flow/threads/{thread_id}/user-data/uploads/`
+4. 非本地沙箱场景下，确认上传接口没有报错（需要成功完成 sandbox 同步）
+
+## 开发建议
+
+### 前端集成
+
+```typescript
+// 上传文件示例
+async function uploadFiles(threadId: string, files: File[]) {
+  const formData = new FormData();
+  files.forEach(file => {
+    formData.append('files', file);
+  });
+
+  const response = await fetch(
+    `/api/threads/${threadId}/uploads`,
+    {
+      method: 'POST',
+      body: formData,
+    }
+  );
+
+  return response.json();
+}
+
+// 列出文件
+async function listFiles(threadId: string) {
+  const response = await fetch(
+    `/api/threads/${threadId}/uploads/list`
+  );
+  return response.json();
+}
+```
+
+### 扩展功能建议
+
+1. **文件预览**：添加预览端点，支持在浏览器中直接查看文件
+2. **批量删除**：支持一次删除多个文件
+3. **文件搜索**：支持按文件名或类型搜索
+4. **版本控制**：保留文件的多个版本
+5. **压缩包支持**：自动解压 zip 文件
+6. **图片 OCR**：对上传的图片进行 OCR 识别

offline-backend-20260512/backend/docs/GUARDRAILS.md

@@ -0,0 +1,385 @@
+# Guardrails: Pre-Tool-Call Authorization
+
+> **Context:** [Issue #1213](https://github.com/bytedance/deer-flow/issues/1213) — DeerFlow has Docker sandboxing and human approval via `ask_clarification`, but no deterministic, policy-driven authorization layer for tool calls. An agent running autonomous multi-step tasks can execute any loaded tool with any arguments. Guardrails add a middleware that evaluates every tool call against a policy **before** execution.
+
+## Why Guardrails
+
+```
+Without guardrails:                      With guardrails:
+
+  Agent                                    Agent
+    │                                        │
+    ▼                                        ▼
+  ┌──────────┐                             ┌──────────┐
+  │ bash     │──▶ executes immediately     │ bash     │──▶ GuardrailMiddleware
+  │ rm -rf / │                             │ rm -rf / │        │
+  └──────────┘                             └──────────┘        ▼
+                                                         ┌──────────────┐
+                                                         │  Provider    │
+                                                         │  evaluates   │
+                                                         │  against     │
+                                                         │  policy      │
+                                                         └──────┬───────┘
+                                                                │
+                                                          ┌─────┴─────┐
+                                                          │           │
+                                                        ALLOW       DENY
+                                                          │           │
+                                                          ▼           ▼
+                                                      Tool runs   Agent sees:
+                                                      normally    "Guardrail denied:
+                                                                   rm -rf blocked"
+```
+
+- **Sandboxing** provides process isolation but not semantic authorization. A sandboxed `bash` can still `curl` data out.
+- **Human approval** (`ask_clarification`) requires a human in the loop for every action. Not viable for autonomous workflows.
+- **Guardrails** provide deterministic, policy-driven authorization that works without human intervention.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                        Middleware Chain                               │
+│                                                                      │
+│  1. ThreadDataMiddleware     ─── per-thread dirs                     │
+│  2. UploadsMiddleware        ─── file upload tracking                │
+│  3. SandboxMiddleware        ─── sandbox acquisition                 │
+│  4. DanglingToolCallMiddleware ── fix incomplete tool calls           │
+│  5. GuardrailMiddleware ◄──── EVALUATES EVERY TOOL CALL             │
+│  6. ToolErrorHandlingMiddleware ── convert exceptions to messages     │
+│  7-12. (Summarization, Title, Memory, Vision, Subagent, Clarify)    │
+│                                                                      │
+└─────────────────────────────────────────────────────────────────────┘
+                         │
+                         ▼
+           ┌──────────────────────────┐
+           │    GuardrailProvider     │  ◄── pluggable: any class
+           │    (configured in YAML)  │      with evaluate/aevaluate
+           └────────────┬─────────────┘
+                        │
+              ┌─────────┼──────────────┐
+              │         │              │
+              ▼         ▼              ▼
+         Built-in   OAP Passport    Custom
+         Allowlist  Provider        Provider
+         (zero dep) (open standard) (your code)
+                        │
+                  Any implementation
+                  (e.g. APort, or
+                   your own evaluator)
+```
+
+The `GuardrailMiddleware` implements `wrap_tool_call` / `awrap_tool_call` (the same `AgentMiddleware` pattern used by `ToolErrorHandlingMiddleware`). It:
+
+1. Builds a `GuardrailRequest` with tool name, arguments, and passport reference
+2. Calls `provider.evaluate(request)` on whatever provider is configured
+3. If **deny**: returns `ToolMessage(status="error")` with the reason -- agent sees the denial and adapts
+4. If **allow**: passes through to the actual tool handler
+5. If **provider error** and `fail_closed=true` (default): blocks the call
+6. `GraphBubbleUp` exceptions (LangGraph control signals) are always propagated, never caught
+
+## Three Provider Options
+
+### Option 1: Built-in AllowlistProvider (Zero Dependencies)
+
+The simplest option. Ships with DeerFlow. Block or allow tools by name. No external packages, no passport, no network.
+
+**config.yaml:**
+```yaml
+guardrails:
+  enabled: true
+  provider:
+    use: deerflow.guardrails.builtin:AllowlistProvider
+    config:
+      denied_tools: ["bash", "write_file"]
+```
+
+This blocks `bash` and `write_file` for all requests. All other tools pass through.
+
+You can also use an allowlist (only these tools are permitted):
+```yaml
+guardrails:
+  enabled: true
+  provider:
+    use: deerflow.guardrails.builtin:AllowlistProvider
+    config:
+      allowed_tools: ["web_search", "read_file", "ls"]
+```
+
+**Try it:**
+1. Add the config above to your `config.yaml`
+2. Start DeerFlow: `make dev`
+3. Ask the agent: "Use bash to run echo hello"
+4. The agent sees: `Guardrail denied: tool 'bash' was blocked (oap.tool_not_allowed)`
+
+### Option 2: OAP Passport Provider (Policy-Based)
+
+For policy enforcement based on the [Open Agent Passport (OAP)](https://github.com/aporthq/aport-spec) open standard. An OAP passport is a JSON document that declares an agent's identity, capabilities, and operational limits. Any provider that reads an OAP passport and returns OAP-compliant decisions works with DeerFlow.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    OAP Passport (JSON)                        │
+│                   (open standard, any provider)              │
+│  {                                                           │
+│    "spec_version": "oap/1.0",                                │
+│    "status": "active",                                       │
+│    "capabilities": [                                         │
+│      {"id": "system.command.execute"},                       │
+│      {"id": "data.file.read"},                               │
+│      {"id": "data.file.write"},                              │
+│      {"id": "web.fetch"},                                    │
+│      {"id": "mcp.tool.execute"}                              │
+│    ],                                                        │
+│    "limits": {                                               │
+│      "system.command.execute": {                             │
+│        "allowed_commands": ["git", "npm", "node", "ls"],     │
+│        "blocked_patterns": ["rm -rf", "sudo", "chmod 777"]   │
+│      }                                                       │
+│    }                                                         │
+│  }                                                           │
+└──────────────────────────┬──────────────────────────────────┘
+                           │
+               Any OAP-compliant provider
+          ┌────────────────┼────────────────┐
+          │                │                │
+     Your own         APort (ref.      Other future
+     evaluator        implementation)  implementations
+```
+
+**Creating a passport manually:**
+
+An OAP passport is just a JSON file. You can create one by hand following the [OAP specification](https://github.com/aporthq/aport-spec/blob/main/oap/oap-spec.md) and validate it against the [JSON schema](https://github.com/aporthq/aport-spec/blob/main/oap/passport-schema.json). See the [examples](https://github.com/aporthq/aport-spec/tree/main/oap/examples) directory for templates.
+
+**Using APort as a reference implementation:**
+
+[APort Agent Guardrails](https://github.com/aporthq/aport-agent-guardrails) is one open-source (Apache 2.0) implementation of an OAP provider. It handles passport creation, local evaluation, and optional hosted API evaluation.
+
+```bash
+pip install aport-agent-guardrails
+aport setup --framework deerflow
+```
+
+This creates:
+- `~/.aport/deerflow/config.yaml` -- evaluator config (local or API mode)
+- `~/.aport/deerflow/aport/passport.json` -- OAP passport with capabilities and limits
+
+**config.yaml (using APort as the provider):**
+```yaml
+guardrails:
+  enabled: true
+  provider:
+    use: aport_guardrails.providers.generic:OAPGuardrailProvider
+```
+
+**config.yaml (using your own OAP provider):**
+```yaml
+guardrails:
+  enabled: true
+  provider:
+    use: my_oap_provider:MyOAPProvider
+    config:
+      passport_path: ./my-passport.json
+```
+
+Any provider that accepts `framework` as a kwarg and implements `evaluate`/`aevaluate` works. The OAP standard defines the passport format and decision codes; DeerFlow doesn't care which provider reads them.
+
+**What the passport controls:**
+
+| Passport field | What it does | Example |
+|---|---|---|
+| `capabilities[].id` | Which tool categories the agent can use | `system.command.execute`, `data.file.write` |
+| `limits.*.allowed_commands` | Which commands are allowed | `["git", "npm", "node"]` or `["*"]` for all |
+| `limits.*.blocked_patterns` | Patterns always denied | `["rm -rf", "sudo", "chmod 777"]` |
+| `status` | Kill switch | `active`, `suspended`, `revoked` |
+
+**Evaluation modes (provider-dependent):**
+
+OAP providers may support different evaluation modes. For example, the APort reference implementation supports:
+
+| Mode | How it works | Network | Latency |
+|---|---|---|---|
+| **Local** | Evaluates passport locally (bash script). | None | ~300ms |
+| **API** | Sends passport + context to a hosted evaluator. Signed decisions. | Yes | ~65ms |
+
+A custom OAP provider can implement any evaluation strategy -- the DeerFlow middleware doesn't care how the provider reaches its decision.
+
+**Try it:**
+1. Install and set up as above
+2. Start DeerFlow and ask: "Create a file called test.txt with content hello"
+3. Then ask: "Now delete it using bash rm -rf"
+4. Guardrail blocks it: `oap.blocked_pattern: Command contains blocked pattern: rm -rf`
+
+### Option 3: Custom Provider (Bring Your Own)
+
+Any Python class with `evaluate(request)` and `aevaluate(request)` methods works. No base class or inheritance needed -- it's a structural protocol.
+
+```python
+# my_guardrail.py
+
+class MyGuardrailProvider:
+    name = "my-company"
+
+    def evaluate(self, request):
+        from deerflow.guardrails.provider import GuardrailDecision, GuardrailReason
+
+        # Example: block any bash command containing "delete"
+        if request.tool_name == "bash" and "delete" in str(request.tool_input):
+            return GuardrailDecision(
+                allow=False,
+                reasons=[GuardrailReason(code="custom.blocked", message="delete not allowed")],
+                policy_id="custom.v1",
+            )
+        return GuardrailDecision(allow=True, reasons=[GuardrailReason(code="oap.allowed")])
+
+    async def aevaluate(self, request):
+        return self.evaluate(request)
+```
+
+**config.yaml:**
+```yaml
+guardrails:
+  enabled: true
+  provider:
+    use: my_guardrail:MyGuardrailProvider
+```
+
+Make sure `my_guardrail.py` is on the Python path (e.g. in the backend directory or installed as a package).
+
+**Try it:**
+1. Create `my_guardrail.py` in the backend directory
+2. Add the config
+3. Start DeerFlow and ask: "Use bash to delete test.txt"
+4. Your provider blocks it
+
+## Implementing a Provider
+
+### Required Interface
+
+```
+┌──────────────────────────────────────────────────┐
+│              GuardrailProvider Protocol            │
+│                                                   │
+│  name: str                                        │
+│                                                   │
+│  evaluate(request: GuardrailRequest)              │
+│      -> GuardrailDecision                         │
+│                                                   │
+│  aevaluate(request: GuardrailRequest)   (async)   │
+│      -> GuardrailDecision                         │
+└──────────────────────────────────────────────────┘
+
+┌──────────────────────────┐    ┌──────────────────────────┐
+│     GuardrailRequest      │    │    GuardrailDecision      │
+│                           │    │                           │
+│  tool_name: str           │    │  allow: bool              │
+│  tool_input: dict         │    │  reasons: [GuardrailReason]│
+│  agent_id: str | None     │    │  policy_id: str | None    │
+│  thread_id: str | None    │    │  metadata: dict           │
+│  is_subagent: bool        │    │                           │
+│  timestamp: str           │    │  GuardrailReason:         │
+│                           │    │    code: str              │
+└──────────────────────────┘    │    message: str           │
+                                └──────────────────────────┘
+```
+
+### DeerFlow Tool Names
+
+These are the tool names your provider will see in `request.tool_name`:
+
+| Tool | What it does |
+|---|---|
+| `bash` | Shell command execution |
+| `write_file` | Create/overwrite a file |
+| `str_replace` | Edit a file (find and replace) |
+| `read_file` | Read file content |
+| `ls` | List directory |
+| `web_search` | Web search query |
+| `web_fetch` | Fetch URL content |
+| `image_search` | Image search |
+| `present_files` | Present file to user |
+| `view_image` | Display image |
+| `ask_clarification` | Ask user a question |
+| `task` | Delegate to subagent |
+| `mcp__*` | MCP tools (dynamic) |
+
+### OAP Reason Codes
+
+Standard codes used by the [OAP specification](https://github.com/aporthq/aport-spec):
+
+| Code | Meaning |
+|---|---|
+| `oap.allowed` | Tool call authorized |
+| `oap.tool_not_allowed` | Tool not in allowlist |
+| `oap.command_not_allowed` | Command not in allowed_commands |
+| `oap.blocked_pattern` | Command matches a blocked pattern |
+| `oap.limit_exceeded` | Operation exceeds a limit |
+| `oap.passport_suspended` | Passport status is suspended/revoked |
+| `oap.evaluator_error` | Provider crashed (fail-closed) |
+
+### Provider Loading
+
+DeerFlow loads providers via `resolve_variable()` -- the same mechanism used for models, tools, and sandbox providers. The `use:` field is a Python class path: `package.module:ClassName`.
+
+The provider is instantiated with `**config` kwargs if `config:` is set, plus `framework="deerflow"` is always injected. Accept `**kwargs` to stay forward-compatible:
+
+```python
+class YourProvider:
+    def __init__(self, framework: str = "generic", **kwargs):
+        # framework="deerflow" tells you which config dir to use
+        ...
+```
+
+## Configuration Reference
+
+```yaml
+guardrails:
+  # Enable/disable guardrail middleware (default: false)
+  enabled: true
+
+  # Block tool calls if provider raises an exception (default: true)
+  fail_closed: true
+
+  # Passport reference -- passed as request.agent_id to the provider.
+  # File path, hosted agent ID, or null (provider resolves from its config).
+  passport: null
+
+  # Provider: loaded by class path via resolve_variable
+  provider:
+    use: deerflow.guardrails.builtin:AllowlistProvider
+    config:  # optional kwargs passed to provider.__init__
+      denied_tools: ["bash"]
+```
+
+## Testing
+
+```bash
+cd backend
+uv run python -m pytest tests/test_guardrail_middleware.py -v
+```
+
+25 tests covering:
+- AllowlistProvider: allow, deny, both allowlist+denylist, async
+- GuardrailMiddleware: allow passthrough, deny with OAP codes, fail-closed, fail-open, passport forwarding, empty reasons fallback, empty tool name, protocol isinstance check
+- Async paths: awrap_tool_call for allow, deny, fail-closed, fail-open
+- GraphBubbleUp: LangGraph control signals propagate through (not caught)
+- Config: defaults, from_dict, singleton load/reset
+
+## Files
+
+```
+packages/harness/deerflow/guardrails/
+    __init__.py              # Public exports
+    provider.py              # GuardrailProvider protocol, GuardrailRequest, GuardrailDecision
+    middleware.py             # GuardrailMiddleware (AgentMiddleware subclass)
+    builtin.py               # AllowlistProvider (zero deps)
+
+packages/harness/deerflow/config/
+    guardrails_config.py     # GuardrailsConfig Pydantic model + singleton
+
+packages/harness/deerflow/agents/middlewares/
+    tool_error_handling_middleware.py  # Registers GuardrailMiddleware in chain
+
+config.example.yaml          # Three provider options documented
+tests/test_guardrail_middleware.py  # 25 tests
+docs/GUARDRAILS.md           # This file
+```

offline-backend-20260512/backend/docs/MCP_SERVER.md

@@ -0,0 +1,100 @@
+# MCP (Model Context Protocol) Configuration
+
+DeerFlow supports configurable MCP servers and skills to extend its capabilities, which are loaded from a dedicated `extensions_config.json` file in the project root directory.
+
+## Setup
+
+1. Copy `extensions_config.example.json` to `extensions_config.json` in the project root directory.
+   ```bash
+   # Copy example configuration
+   cp extensions_config.example.json extensions_config.json
+   ```
+   
+2. Enable the desired MCP servers or skills by setting `"enabled": true`.
+3. Configure each server’s command, arguments, and environment variables as needed.
+4. Restart the application to load and register MCP tools.
+
+## OAuth Support (HTTP/SSE MCP Servers)
+
+For `http` and `sse` MCP servers, DeerFlow supports OAuth token acquisition and automatic token refresh.
+
+- Supported grants: `client_credentials`, `refresh_token`
+- Configure per-server `oauth` block in `extensions_config.json`
+- Secrets should be provided via environment variables (for example: `$MCP_OAUTH_CLIENT_SECRET`)
+
+Example:
+
+```json
+{
+   "mcpServers": {
+      "secure-http-server": {
+         "enabled": true,
+         "type": "http",
+         "url": "https://api.example.com/mcp",
+         "oauth": {
+            "enabled": true,
+            "token_url": "https://auth.example.com/oauth/token",
+            "grant_type": "client_credentials",
+            "client_id": "$MCP_OAUTH_CLIENT_ID",
+            "client_secret": "$MCP_OAUTH_CLIENT_SECRET",
+            "scope": "mcp.read",
+            "refresh_skew_seconds": 60
+         }
+      }
+   }
+}
+```
+
+## Custom Tool Interceptors
+
+You can register custom interceptors that run before every MCP tool call. This is useful for injecting per-request headers (e.g., user auth tokens from the LangGraph execution context), logging, or metrics.
+
+Declare interceptors in `extensions_config.json` using the `mcpInterceptors` field:
+
+```json
+{
+  "mcpInterceptors": [
+    "my_package.mcp.auth:build_auth_interceptor"
+  ],
+  "mcpServers": { ... }
+}
+```
+
+Each entry is a Python import path in `module:variable` format (resolved via `resolve_variable`). The variable must be a **no-arg builder function** that returns an async interceptor compatible with `MultiServerMCPClient`’s `tool_interceptors` interface, or `None` to skip.
+
+Example interceptor that injects auth headers from LangGraph metadata:
+
+```python
+def build_auth_interceptor():
+    async def interceptor(request, handler):
+        from langgraph.config import get_config
+        metadata = get_config().get("metadata", {})
+        headers = dict(request.headers or {})
+        if token := metadata.get("auth_token"):
+            headers["X-Auth-Token"] = token
+        return await handler(request.override(headers=headers))
+    return interceptor
+```
+
+- A single string value is accepted and normalized to a one-element list.
+- Invalid paths or builder failures are logged as warnings without blocking other interceptors.
+- The builder return value must be `callable`; non-callable values are skipped with a warning.
+
+## How It Works
+
+MCP servers expose tools that are automatically discovered and integrated into DeerFlow’s agent system at runtime. Once enabled, these tools become available to agents without additional code changes.
+
+## Example Capabilities
+
+MCP servers can provide access to:
+
+- **File systems**
+- **Databases** (e.g., PostgreSQL)
+- **External APIs** (e.g., GitHub, Brave Search)
+- **Browser automation** (e.g., Puppeteer)
+- **Custom MCP server implementations**
+
+## Learn More
+
+For detailed documentation about the Model Context Protocol, visit:  
+https://modelcontextprotocol.io

offline-backend-20260512/backend/docs/MEMORY_IMPROVEMENTS.md

@@ -0,0 +1,65 @@
+# Memory System Improvements
+
+This document tracks memory injection behavior and roadmap status.
+
+## Status (As Of 2026-03-10)
+
+Implemented in `main`:
+- Accurate token counting via `tiktoken` in `format_memory_for_injection`.
+- Facts are injected into prompt memory context.
+- Facts are ranked by confidence (descending).
+- Injection respects `max_injection_tokens` budget.
+
+Planned / not yet merged:
+- TF-IDF similarity-based fact retrieval.
+- `current_context` input for context-aware scoring.
+- Configurable similarity/confidence weights (`similarity_weight`, `confidence_weight`).
+- Middleware/runtime wiring for context-aware retrieval before each model call.
+
+## Current Behavior
+
+Function today:
+
+```python
+def format_memory_for_injection(memory_data: dict[str, Any], max_tokens: int = 2000) -> str:
+```
+
+Current injection format:
+- `User Context` section from `user.*.summary`
+- `History` section from `history.*.summary`
+- `Facts` section from `facts[]`, sorted by confidence, appended until token budget is reached
+
+Token counting:
+- Uses `tiktoken` (`cl100k_base`) when available
+- Falls back to `len(text) // 4` if tokenizer import fails
+
+## Known Gap
+
+Previous versions of this document described TF-IDF/context-aware retrieval as if it were already shipped.
+That was not accurate for `main` and caused confusion.
+
+Issue reference: `#1059`
+
+## Roadmap (Planned)
+
+Planned scoring strategy:
+
+```text
+final_score = (similarity * 0.6) + (confidence * 0.4)
+```
+
+Planned integration shape:
+1. Extract recent conversational context from filtered user/final-assistant turns.
+2. Compute TF-IDF cosine similarity between each fact and current context.
+3. Rank by weighted score and inject under token budget.
+4. Fall back to confidence-only ranking if context is unavailable.
+
+## Validation
+
+Current regression coverage includes:
+- facts inclusion in memory injection output
+- confidence ordering
+- token-budget-limited fact inclusion
+
+Tests:
+- `backend/tests/test_memory_prompt_injection.py`

offline-backend-20260512/backend/docs/MEMORY_IMPROVEMENTS_SUMMARY.md

@@ -0,0 +1,38 @@
+# Memory System Improvements - Summary
+
+## Sync Note (2026-03-10)
+
+This summary is synchronized with the `main` branch implementation.
+TF-IDF/context-aware retrieval is **planned**, not merged yet.
+
+## Implemented
+
+- Accurate token counting with `tiktoken` in memory injection.
+- Facts are injected into `<memory>` prompt content.
+- Facts are ordered by confidence and bounded by `max_injection_tokens`.
+
+## Planned (Not Yet Merged)
+
+- TF-IDF cosine similarity recall based on recent conversation context.
+- `current_context` parameter for `format_memory_for_injection`.
+- Weighted ranking (`similarity` + `confidence`).
+- Runtime extraction/injection flow for context-aware fact selection.
+
+## Why This Sync Was Needed
+
+Earlier docs described TF-IDF behavior as already implemented, which did not match code in `main`.
+This mismatch is tracked in issue `#1059`.
+
+## Current API Shape
+
+```python
+def format_memory_for_injection(memory_data: dict[str, Any], max_tokens: int = 2000) -> str:
+```
+
+No `current_context` argument is currently available in `main`.
+
+## Verification Pointers
+
+- Implementation: `packages/harness/deerflow/agents/memory/prompt.py`
+- Prompt assembly: `packages/harness/deerflow/agents/lead_agent/prompt.py`
+- Regression tests: `backend/tests/test_memory_prompt_injection.py`

offline-backend-20260512/backend/docs/MEMORY_SETTINGS_REVIEW.md

@@ -0,0 +1,63 @@
+# Memory Settings Review
+
+Use this when reviewing the Memory Settings add/edit flow locally with the fewest possible manual steps.
+
+## Quick Review
+
+1. Start DeerFlow locally using any working development setup you already use.
+
+   Examples:
+
+   ```bash
+   make dev
+   ```
+
+   or
+
+   ```bash
+   make docker-start
+   ```
+
+   If you already have DeerFlow running locally, you can reuse that existing setup.
+
+2. Load the sample memory fixture.
+
+   ```bash
+   python scripts/load_memory_sample.py
+   ```
+
+3. Open `Settings > Memory`.
+
+   Default local URLs:
+   - App: `http://localhost:2026`
+   - Local frontend-only fallback: `http://localhost:3000`
+
+## Minimal Manual Test
+
+1. Click `Add fact`.
+2. Create a new fact with:
+   - Content: `Reviewer-added memory fact`
+   - Category: `testing`
+   - Confidence: `0.88`
+3. Confirm the new fact appears immediately and shows `Manual` as the source.
+4. Edit the sample fact `This sample fact is intended for edit testing.` and change it to:
+   - Content: `This sample fact was edited during manual review.`
+   - Category: `testing`
+   - Confidence: `0.91`
+5. Confirm the edited fact updates immediately.
+6. Refresh the page and confirm both the newly added fact and the edited fact still persist.
+
+## Optional Sanity Checks
+
+- Search `Reviewer-added` and confirm the new fact is matched.
+- Search `workflow` and confirm category text is searchable.
+- Switch between `All`, `Facts`, and `Summaries`.
+- Delete the disposable sample fact `Delete fact testing can target this disposable sample entry.` and confirm the list updates immediately.
+- Clear all memory and confirm the page enters the empty state.
+
+## Fixture Files
+
+- Sample fixture: `backend/docs/memory-settings-sample.json`
+- Default local runtime target: `backend/.deer-flow/memory.json`
+
+The loader script creates a timestamped backup automatically before overwriting an existing runtime memory file.

offline-backend-20260512/backend/docs/PATH_EXAMPLES.md

@@ -0,0 +1,289 @@
+# 文件路径使用示例
+
+## 三种路径类型
+
+DeerFlow 的文件上传系统返回三种不同的路径，每种路径用于不同的场景：
+
+### 1. 实际文件系统路径 (path)
+
+```
+.deer-flow/threads/{thread_id}/user-data/uploads/document.pdf
+```
+
+**用途：**
+- 文件在服务器文件系统中的实际位置
+- 相对于 `backend/` 目录
+- 用于直接文件系统访问、备份、调试等
+
+**示例：**
+```python
+# Python 代码中直接访问
+from pathlib import Path
+file_path = Path("backend/.deer-flow/threads/abc123/user-data/uploads/document.pdf")
+content = file_path.read_bytes()
+```
+
+### 2. 虚拟路径 (virtual_path)
+
+```
+/mnt/user-data/uploads/document.pdf
+```
+
+**用途：**
+- Agent 在沙箱环境中使用的路径
+- 沙箱系统会自动映射到实际路径
+- Agent 的所有文件操作工具都使用这个路径
+
+**示例：**
+Agent 在对话中使用：
+```python
+# Agent 使用 read_file 工具
+read_file(path="/mnt/user-data/uploads/document.pdf")
+
+# Agent 使用 bash 工具
+bash(command="cat /mnt/user-data/uploads/document.pdf")
+```
+
+### 3. HTTP 访问 URL (artifact_url)
+
+```
+/api/threads/{thread_id}/artifacts/mnt/user-data/uploads/document.pdf
+```
+
+**用途：**
+- 前端通过 HTTP 访问文件
+- 用于下载、预览文件
+- 可以直接在浏览器中打开
+
+**示例：**
+```typescript
+// 前端 TypeScript/JavaScript 代码
+const threadId = 'abc123';
+const filename = 'document.pdf';
+
+// 下载文件
+const downloadUrl = `/api/threads/${threadId}/artifacts/mnt/user-data/uploads/${filename}?download=true`;
+window.open(downloadUrl);
+
+// 在新窗口预览
+const viewUrl = `/api/threads/${threadId}/artifacts/mnt/user-data/uploads/${filename}`;
+window.open(viewUrl, '_blank');
+
+// 使用 fetch API 获取
+const response = await fetch(viewUrl);
+const blob = await response.blob();
+```
+
+## 完整使用流程示例
+
+### 场景：前端上传文件并让 Agent 处理
+
+```typescript
+// 1. 前端上传文件
+async function uploadAndProcess(threadId: string, file: File) {
+  // 上传文件
+  const formData = new FormData();
+  formData.append('files', file);
+
+  const uploadResponse = await fetch(
+    `/api/threads/${threadId}/uploads`,
+    {
+      method: 'POST',
+      body: formData
+    }
+  );
+
+  const uploadData = await uploadResponse.json();
+  const fileInfo = uploadData.files[0];
+
+  console.log('文件信息：', fileInfo);
+  // {
+  //   filename: "report.pdf",
+  //   path: ".deer-flow/threads/abc123/user-data/uploads/report.pdf",
+  //   virtual_path: "/mnt/user-data/uploads/report.pdf",
+  //   artifact_url: "/api/threads/abc123/artifacts/mnt/user-data/uploads/report.pdf",
+  //   markdown_file: "report.md",
+  //   markdown_path: ".deer-flow/threads/abc123/user-data/uploads/report.md",
+  //   markdown_virtual_path: "/mnt/user-data/uploads/report.md",
+  //   markdown_artifact_url: "/api/threads/abc123/artifacts/mnt/user-data/uploads/report.md"
+  // }
+
+  // 2. 发送消息给 Agent
+  await sendMessage(threadId, "请分析刚上传的 PDF 文件");
+
+  // Agent 会自动看到文件列表，包含：
+  // - report.pdf (虚拟路径: /mnt/user-data/uploads/report.pdf)
+  // - report.md (虚拟路径: /mnt/user-data/uploads/report.md)
+
+  // 3. 前端可以直接访问转换后的 Markdown
+  const mdResponse = await fetch(fileInfo.markdown_artifact_url);
+  const markdownContent = await mdResponse.text();
+  console.log('Markdown 内容：', markdownContent);
+
+  // 4. 或者下载原始 PDF
+  const downloadLink = document.createElement('a');
+  downloadLink.href = fileInfo.artifact_url + '?download=true';
+  downloadLink.download = fileInfo.filename;
+  downloadLink.click();
+}
+```
+
+## 路径转换表
+
+| 场景 | 使用的路径类型 | 示例 |
+|------|---------------|------|
+| 服务器后端代码直接访问 | `path` | `.deer-flow/threads/abc123/user-data/uploads/file.pdf` |
+| Agent 工具调用 | `virtual_path` | `/mnt/user-data/uploads/file.pdf` |
+| 前端下载/预览 | `artifact_url` | `/api/threads/abc123/artifacts/mnt/user-data/uploads/file.pdf` |
+| 备份脚本 | `path` | `.deer-flow/threads/abc123/user-data/uploads/file.pdf` |
+| 日志记录 | `path` | `.deer-flow/threads/abc123/user-data/uploads/file.pdf` |
+
+## 代码示例集合
+
+### Python - 后端处理
+
+```python
+from pathlib import Path
+from deerflow.agents.middlewares.thread_data_middleware import THREAD_DATA_BASE_DIR
+
+def process_uploaded_file(thread_id: str, filename: str):
+    # 使用实际路径
+    base_dir = Path.cwd() / THREAD_DATA_BASE_DIR / thread_id / "user-data" / "uploads"
+    file_path = base_dir / filename
+
+    # 直接读取
+    with open(file_path, 'rb') as f:
+        content = f.read()
+
+    return content
+```
+
+### JavaScript - 前端访问
+
+```javascript
+// 列出已上传的文件
+async function listUploadedFiles(threadId) {
+  const response = await fetch(`/api/threads/${threadId}/uploads/list`);
+  const data = await response.json();
+
+  // 为每个文件创建下载链接
+  data.files.forEach(file => {
+    console.log(`文件: ${file.filename}`);
+    console.log(`下载: ${file.artifact_url}?download=true`);
+    console.log(`预览: ${file.artifact_url}`);
+
+    // 如果是文档，还有 Markdown 版本
+    if (file.markdown_artifact_url) {
+      console.log(`Markdown: ${file.markdown_artifact_url}`);
+    }
+  });
+
+  return data.files;
+}
+
+// 删除文件
+async function deleteFile(threadId, filename) {
+  const response = await fetch(
+    `/api/threads/${threadId}/uploads/${filename}`,
+    { method: 'DELETE' }
+  );
+  return response.json();
+}
+```
+
+### React 组件示例
+
+```tsx
+import React, { useState, useEffect } from 'react';
+
+interface UploadedFile {
+  filename: string;
+  size: number;
+  path: string;
+  virtual_path: string;
+  artifact_url: string;
+  extension: string;
+  modified: number;
+  markdown_artifact_url?: string;
+}
+
+function FileUploadList({ threadId }: { threadId: string }) {
+  const [files, setFiles] = useState<UploadedFile[]>([]);
+
+  useEffect(() => {
+    fetchFiles();
+  }, [threadId]);
+
+  async function fetchFiles() {
+    const response = await fetch(`/api/threads/${threadId}/uploads/list`);
+    const data = await response.json();
+    setFiles(data.files);
+  }
+
+  async function handleUpload(event: React.ChangeEvent<HTMLInputElement>) {
+    const fileList = event.target.files;
+    if (!fileList) return;
+
+    const formData = new FormData();
+    Array.from(fileList).forEach(file => {
+      formData.append('files', file);
+    });
+
+    await fetch(`/api/threads/${threadId}/uploads`, {
+      method: 'POST',
+      body: formData
+    });
+
+    fetchFiles(); // 刷新列表
+  }
+
+  async function handleDelete(filename: string) {
+    await fetch(`/api/threads/${threadId}/uploads/${filename}`, {
+      method: 'DELETE'
+    });
+    fetchFiles(); // 刷新列表
+  }
+
+  return (
+    <div>
+      <input type="file" multiple onChange={handleUpload} />
+
+      <ul>
+        {files.map(file => (
+          <li key={file.filename}>
+            <span>{file.filename}</span>
+            <a href={file.artifact_url} target="_blank">预览</a>
+            <a href={`${file.artifact_url}?download=true`}>下载</a>
+            {file.markdown_artifact_url && (
+              <a href={file.markdown_artifact_url} target="_blank">Markdown</a>
+            )}
+            <button onClick={() => handleDelete(file.filename)}>删除</button>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+## 注意事项
+
+1. **路径安全性**
+   - 实际路径（`path`）包含线程 ID，确保隔离
+   - API 会验证路径，防止目录遍历攻击
+   - 前端不应直接使用 `path`，而应使用 `artifact_url`
+
+2. **Agent 使用**
+   - Agent 只能看到和使用 `virtual_path`
+   - 沙箱系统自动映射到实际路径
+   - Agent 不需要知道实际的文件系统结构
+
+3. **前端集成**
+   - 始终使用 `artifact_url` 访问文件
+   - 不要尝试直接访问文件系统路径
+   - 使用 `?download=true` 参数强制下载
+
+4. **Markdown 转换**
+   - 转换成功时，会返回额外的 `markdown_*` 字段
+   - 建议优先使用 Markdown 版本（更易处理）
+   - 原始文件始终保留

offline-backend-20260512/backend/docs/README.md

@@ -0,0 +1,55 @@
+# Documentation
+
+This directory contains detailed documentation for the DeerFlow backend.
+
+## Quick Links
+
+| Document | Description |
+|----------|-------------|
+| [ARCHITECTURE.md](ARCHITECTURE.md) | System architecture overview |
+| [API.md](API.md) | Complete API reference |
+| [CONFIGURATION.md](CONFIGURATION.md) | Configuration options |
+| [SETUP.md](SETUP.md) | Quick setup guide |
+
+## Feature Documentation
+
+| Document | Description |
+|----------|-------------|
+| [STREAMING.md](STREAMING.md) | Token-level streaming design: Gateway vs DeerFlowClient paths, `stream_mode` semantics, per-id dedup |
+| [FILE_UPLOAD.md](FILE_UPLOAD.md) | File upload functionality |
+| [PATH_EXAMPLES.md](PATH_EXAMPLES.md) | Path types and usage examples |
+| [summarization.md](summarization.md) | Context summarization feature |
+| [plan_mode_usage.md](plan_mode_usage.md) | Plan mode with TodoList |
+| [AUTO_TITLE_GENERATION.md](AUTO_TITLE_GENERATION.md) | Automatic title generation |
+
+## Development
+
+| Document | Description |
+|----------|-------------|
+| [TODO.md](TODO.md) | Planned features and known issues |
+
+## Getting Started
+
+1. **New to DeerFlow?** Start with [SETUP.md](SETUP.md) for quick installation
+2. **Configuring the system?** See [CONFIGURATION.md](CONFIGURATION.md)
+3. **Understanding the architecture?** Read [ARCHITECTURE.md](ARCHITECTURE.md)
+4. **Building integrations?** Check [API.md](API.md) for API reference
+
+## Document Organization
+
+```
+docs/
+├── README.md                  # This file
+├── ARCHITECTURE.md            # System architecture
+├── API.md                     # API reference
+├── CONFIGURATION.md           # Configuration guide
+├── SETUP.md                   # Setup instructions
+├── FILE_UPLOAD.md             # File upload feature
+├── PATH_EXAMPLES.md           # Path usage examples
+├── summarization.md           # Summarization feature
+├── plan_mode_usage.md         # Plan mode feature
+├── STREAMING.md               # Token-level streaming design
+├── AUTO_TITLE_GENERATION.md   # Title generation
+├── TITLE_GENERATION_IMPLEMENTATION.md  # Title implementation details
+└── TODO.md                    # Roadmap and issues
+```

offline-backend-20260512/backend/docs/SCHEDULED_TASK_CHANGE_AND_RELEASE_ZH.md

@@ -0,0 +1,548 @@
+# 定时任务与 Element 投递改动说明及内网发版文档
+
+本文档对应本次新增的「类 Hermes 任务调度」能力，包含两部分：
+
+- 修改说明：说明改了哪些位置，以及为什么这样设计。
+- 发版说明：基于现有 `start_backend.0509.sh` 的离线部署方式，说明如何重新发版到内网。
+
+## 1. 本次功能目标
+
+本次改动解决三个核心场景：
+
+1. 用户可以在任意智能体聊天中创建定时任务，例如「每天 9 点生成 AI 发展日报」。
+2. 定时任务执行结果统一发送到当前用户唯一的「定时任务助手」聊天框，避免和普通聊天混在一起。
+3. 用户可以在任务管理页面查看、修改、暂停、恢复、删除、立即触发自己的全部定时任务，并可以填写 Element/Matrix 用户 ID，让任务结果同步投递到 Element 私聊。
+
+## 2. 后端修改说明
+
+### 2.1 新增定时任务 API
+
+位置：
+
+- `app/gateway/routers/scheduled_tasks.py`
+- `app/gateway/app.py`
+
+作用：
+
+- 新增 `/api/scheduled-tasks` API。
+- 支持获取定时任务专属会话、任务列表、创建任务、修改任务、删除任务、暂停/恢复、立即触发。
+- 支持 `/api/scheduled-tasks/delivery-profile` 保存当前用户的 Element 用户 ID。
+
+为什么这样做：
+
+- 页面上的任务管理能力需要稳定的 CRUD API。
+- Element 用户 ID 是用户级配置，不应该写在系统环境变量里，所以单独做成用户投递配置。
+- 每个用户只保留一个定时任务会话，因此提供 `/thread` 接口让前端直接进入该会话。
+
+### 2.2 新增定时任务持久化
+
+位置：
+
+- `packages/harness/deerflow/persistence/scheduled_tasks/model.py`
+- `packages/harness/deerflow/persistence/scheduled_tasks/base.py`
+- `packages/harness/deerflow/persistence/scheduled_tasks/sql.py`
+- `packages/harness/deerflow/persistence/scheduled_tasks/memory.py`
+- `packages/harness/deerflow/persistence/scheduled_tasks/__init__.py`
+- `packages/harness/deerflow/persistence/models/__init__.py`
+- `app/gateway/deps.py`
+
+新增数据表：
+
+- `scheduler_threads`：记录每个用户唯一的定时任务聊天线程。
+- `scheduled_tasks`：记录定时任务本体，包括 prompt、cron、时区、下次执行时间、执行智能体上下文。
+- `scheduled_task_runs`：记录每次任务执行，避免重复执行同一计划时间。
+- `scheduled_task_delivery_profiles`：记录用户自己的 Element 用户 ID。
+
+为什么这样做：
+
+- 定时任务需要跨进程、跨重启保存，所以不能只存在内存里。
+- 单独记录 run 可以判断任务是否成功、失败，也可以防止同一计划时间被重复执行。
+- Element 投递目标是用户个人信息，和任务本体分开更清晰。
+
+### 2.3 新增调度运行服务
+
+位置：
+
+- `packages/harness/deerflow/runtime/scheduler/service.py`
+- `packages/harness/deerflow/runtime/scheduler/registry.py`
+- `packages/harness/deerflow/runtime/scheduler/__init__.py`
+- `app/gateway/app.py`
+
+作用：
+
+- 后端启动时创建 `ScheduledTaskService`。
+- 服务每 30 秒扫描一次到期任务。
+- 到期后把任务 prompt 投递到该用户的定时任务专属聊天线程。
+- 任务运行时会恢复创建任务时的智能体上下文，例如自定义智能体名、模型、思考模式等。
+- 定时任务执行期间禁用再次创建定时任务，避免任务递归创建任务。
+
+为什么这样做：
+
+- 用户希望「可以在智能体聊天中创建任务，并复用智能体技能生成日报」，因此任务必须保存创建时的 agent/context。
+- 所有结果集中到专属聊天线程，可以满足「任务结果从定时任务聊天框发给我」的交互要求。
+- 当前 RunManager 对同一 thread 的并发运行有限制，所以调度服务内部加了运行锁，避免多个报告同时写入同一个定时任务会话导致冲突。
+
+### 2.4 新增智能体工具 `scheduled_task`
+
+位置：
+
+- `packages/harness/deerflow/tools/builtins/scheduled_task_tool.py`
+- `packages/harness/deerflow/tools/builtins/__init__.py`
+- `packages/harness/deerflow/tools/tools.py`
+- `packages/harness/deerflow/agents/lead_agent/agent.py`
+
+作用：
+
+- 智能体可以通过工具创建、查询、更新、删除、暂停、恢复、触发定时任务。
+- 用户不需要进入「定时任务聊天框」也能创建任务，可以直接在普通聊天或智能体聊天中说需求。
+- 定时任务执行时不会暴露 `scheduled_task` 工具，避免任务运行中再次调度自身。
+
+为什么这样做：
+
+- 这是满足「我可能会使用智能体中的某一些技能去实现日报生成」的关键。
+- 如果只在任务管理页面创建任务，就无法自然复用智能体上下文和工具能力。
+
+### 2.5 新增 Element/Matrix 私聊投递
+
+位置：
+
+- `packages/harness/deerflow/runtime/scheduler/element.py`
+- `packages/harness/deerflow/runtime/scheduler/service.py`
+- `.env`
+
+作用：
+
+- 定时任务成功后，后端会读取当前用户保存的 `element_user_id`。
+- 如果系统启用了 Element 配置，则机器人会创建 Matrix DM 房间并发送文本结果。
+- 支持三种机器人认证方式：
+  - `ELEMENT_ACCESS_TOKEN`：直接使用已有 token，优先级最高。
+  - `ELEMENT_AUTO_REGISTER=true`：后端自动注册机器人用户，并缓存 token。
+  - `ELEMENT_BOT_USERNAME` + `ELEMENT_BOT_PASSWORD`：使用已有机器人账号登录。
+
+为什么这样做：
+
+- `default_room_id` 不适合这个需求，因为你要发到每个用户自己的私聊。
+- 用户在任务管理页面填写自己的 Element 用户 ID，后端机器人按用户发 DM，更符合多用户场景。
+- 自动注册适合内网环境快速启用；账号密码和 token 方式适合更严格的运维管理。
+
+### 2.6 新增运行依赖
+
+位置：
+
+- `pyproject.toml`
+
+新增：
+
+```toml
+croniter>=6.2.2
+```
+
+作用：
+
+- 用于根据 cron 表达式计算下一次执行时间。
+
+发版注意：
+
+- 本次可以继续使用 `deerflow-backend-offline:20260505` 原镜像。
+- 因为新增了 `croniter`，启动脚本会在容器启动时先检查该依赖；如果缺失，则从内网 Python 私服安装。
+- 只要内网容器能访问 Python 私服，就不需要重新构建或导入新镜像。
+
+## 3. 前端修改说明
+
+### 3.1 新增定时任务 API 与 hooks
+
+位置：
+
+- `frontend-web/src/core/scheduled-tasks/api.ts`
+- `frontend-web/src/core/scheduled-tasks/hooks.ts`
+- `frontend-web/src/core/scheduled-tasks/types.ts`
+- `frontend-web/src/core/scheduled-tasks/index.ts`
+
+作用：
+
+- 封装 `/api/scheduled-tasks` 后端接口。
+- 页面通过 React Query 自动加载任务列表和 Element 投递配置。
+
+为什么这样做：
+
+- 和现有前端数据请求方式保持一致。
+- 任务列表、任务操作、Element 配置保存都能统一刷新缓存。
+
+### 3.2 新增定时任务聊天页与任务管理页
+
+位置：
+
+- `frontend-web/src/pages/ScheduledChatPage.tsx`
+- `frontend-web/src/pages/ScheduledTasksPage.tsx`
+- `frontend-web/src/App.tsx`
+
+作用：
+
+- `/workspace/scheduled`：进入当前用户唯一的定时任务聊天框。
+- `/workspace/scheduled/tasks`：查看、编辑、删除、暂停、恢复、立即运行任务；填写 Element 用户 ID。
+
+为什么这样做：
+
+- 聊天结果和任务管理是两个不同工作流：一个看结果，一个管理规则。
+- 两个入口都挂在 workspace 下，用户不会离开原来的工作区。
+
+### 3.3 左侧栏入口与普通会话过滤
+
+位置：
+
+- `frontend-web/src/components/workspace/workspace-nav-chat-list.tsx`
+- `frontend-web/src/components/workspace/recent-chat-list.tsx`
+- `frontend-web/src/pages/ChatsPage.tsx`
+
+作用：
+
+- 左侧栏新增「定时任务」和「任务管理」入口。
+- 普通最近聊天列表中过滤 `metadata.thread_type === "scheduler"` 的系统会话。
+
+为什么这样做：
+
+- 定时任务会话是系统专用会话，不应该和普通用户聊天列表混在一起。
+- 用户仍然可以通过专门入口进入该会话查看报告。
+
+## 4. 配置说明
+
+运行时配置文件：
+
+- `offline-backend-20260505/bundle/.env`
+
+当前写入的是注释示例，默认不会启用 Element：
+
+```env
+# ELEMENT_ENABLED=true
+# ELEMENT_HOMESERVER_URL=http://your-element-homeserver:8008
+# ELEMENT_AUTO_REGISTER=true
+# ELEMENT_BOT_USERNAME=scheduled-bot
+# ELEMENT_STATE_FILE=.deer-flow/data/element-bot-token
+```
+
+内网启用时建议：
+
+```env
+ELEMENT_ENABLED=true
+ELEMENT_HOMESERVER_URL=http://你的内网Matrix地址:8008
+ELEMENT_AUTO_REGISTER=true
+ELEMENT_BOT_USERNAME=scheduled-bot
+ELEMENT_STATE_FILE=.deer-flow/data/element-bot-token
+```
+
+如果不允许自动注册：
+
+```env
+ELEMENT_ENABLED=true
+ELEMENT_HOMESERVER_URL=http://你的内网Matrix地址:8008
+ELEMENT_AUTO_REGISTER=false
+ELEMENT_BOT_USERNAME=scheduled-bot
+ELEMENT_BOT_PASSWORD=你的机器人密码
+ELEMENT_STATE_FILE=.deer-flow/data/element-bot-token
+```
+
+用户个人 Element ID 不写在 `.env`，由用户在任务管理页面填写，例如：
+
+```text
+@zhangsan:matrix.intranet.local
+```
+
+## 5. 内网发版方案
+
+### 5.1 推荐方案
+
+推荐发布一个新的增量包目录，例如：
+
+```text
+offline-backend-20260512-scheduler/
+```
+
+本次按你的原部署方式处理：继续使用 0509 原镜像，只复制或挂载代码 patch。新增依赖 `croniter` 由启动脚本通过内网 Python 私服安装。
+
+推荐产物：
+
+- `frontend-vite-20260512.zip`
+- `start_backend.scheduler.sh`
+- `stop_backend.sh`
+- `config.yaml.example`
+- `.env.example`
+- `extensions_config.json`
+- `skills/`
+- `data/`
+- `docs/SCHEDULED_TASK_CHANGE_AND_RELEASE_ZH.md`
+- `patch_20260512_scheduler/`
+
+### 5.2 后端发版文件清单
+
+需要进入新包或 patch 包的后端文件：
+
+```text
+backend/app/gateway/app.py
+backend/app/gateway/deps.py
+backend/app/gateway/routers/scheduled_tasks.py
+backend/packages/harness/deerflow/agents/lead_agent/agent.py
+backend/packages/harness/deerflow/persistence/models/__init__.py
+backend/packages/harness/deerflow/persistence/scheduled_tasks/
+backend/packages/harness/deerflow/runtime/scheduler/
+backend/packages/harness/deerflow/tools/builtins/__init__.py
+backend/packages/harness/deerflow/tools/builtins/scheduled_task_tool.py
+backend/packages/harness/deerflow/tools/tools.py
+backend/pyproject.toml
+backend/.env
+```
+
+注意：
+
+- 不建议把本地 `.deer-flow/data/deerflow.db*` 作为代码发版内容，它们是运行数据。
+- 内网环境自己的 `data/` 目录要保留，这是历史会话和任务数据所在位置。
+
+### 5.3 前端发版文件清单
+
+需要构建并发布新的前端静态资源。
+
+涉及源码：
+
+```text
+frontend-web/src/App.tsx
+frontend-web/src/core/scheduled-tasks/
+frontend-web/src/pages/ScheduledChatPage.tsx
+frontend-web/src/pages/ScheduledTasksPage.tsx
+frontend-web/src/components/workspace/workspace-nav-chat-list.tsx
+frontend-web/src/components/workspace/recent-chat-list.tsx
+frontend-web/src/pages/ChatsPage.tsx
+```
+
+构建命令：
+
+```bash
+cd frontend-web
+pnpm install --offline
+pnpm run build
+```
+
+产物：
+
+```text
+frontend-web/dist/
+```
+
+将 `dist/` 按你原来的方式打包成 `frontend-vite-20260512.zip` 或覆盖原静态资源目录。
+
+### 5.4 适配 `start_backend.0509.sh` 的部署方式
+
+0509 脚本核心逻辑是：
+
+- 使用老镜像 `deerflow-backend-offline:20260505`。
+- 通过 `patch_0509` bind-mount Python 文件覆盖镜像内代码。
+- 通过 `--env-file .env` 注入配置。
+- 通过 `-v data:/app/backend/.deer-flow` 保留运行数据。
+
+本次继续沿用这个模式，调整两点：
+
+1. `PATCH_BASE` 建议改成新的目录，例如 `patch_20260512_scheduler`。
+2. 启动脚本在容器启动前检查并安装 `croniter`，依赖来源使用内网 Python 私服。
+
+示例脚本差异：
+
+```bash
+IMAGE_TAG="${IMAGE_TAG:-deerflow-backend-offline:20260505}"
+PATCH_BASE="${SCRIPT_DIR}/patch_20260512_scheduler"
+SCHEDULER_INSTALL_DEPS="${SCHEDULER_INSTALL_DEPS:-1}"
+SCHEDULER_PIP_PACKAGES="${SCHEDULER_PIP_PACKAGES:-croniter>=6.2.2}"
+```
+
+容器启动命令中会执行：
+
+```bash
+uv run --no-sync python -c "import croniter" >/dev/null 2>&1 || uv pip install "${SCHEDULER_PIP_PACKAGES:-croniter>=6.2.2}"
+```
+
+### 5.5 Python 私服配置
+
+如果内网 Python 私服需要配置索引地址，可以写到 `bundle/.env` 中：
+
+```env
+UV_INDEX_URL=http://your-python-mirror/simple
+PIP_INDEX_URL=http://your-python-mirror/simple
+UV_TRUSTED_HOST=your-python-mirror
+PIP_TRUSTED_HOST=your-python-mirror
+```
+
+如果私服使用 HTTPS 且证书正常，一般不需要 `*_TRUSTED_HOST`。
+
+也可以在启动时临时覆盖安装包名：
+
+```bash
+SCHEDULER_PIP_PACKAGES='croniter>=6.2.2' ./start_backend.scheduler.sh
+```
+
+### 5.6 内网服务器部署步骤
+
+在内网服务器上：
+
+```bash
+cd /opt/deerflow/offline-backend-20260512-scheduler/bundle
+
+# 1. 备份旧配置和数据
+cp -a config.yaml config.yaml.bak.$(date +%Y%m%d%H%M%S)
+cp -a .env .env.bak.$(date +%Y%m%d%H%M%S)
+cp -a data data.bak.$(date +%Y%m%d%H%M%S)
+
+# 2. 合并配置
+# 保留原来的 AUTH_JWT_SECRET、模型 key、CORS 等配置。
+# 追加或打开 Element、Python 私服相关配置。
+vi .env
+
+# 3. 启动后端，继续使用原镜像 deerflow-backend-offline:20260505
+chmod +x start_backend.scheduler.sh stop_backend.sh
+./start_backend.scheduler.sh
+
+# 4. 查看日志
+docker logs -f deerflow-backend
+```
+
+本次已补充一个适配脚本：
+
+```text
+offline-backend-20260505/bundle/start_backend.scheduler.sh
+```
+
+它和 0509 脚本保持相同的 Docker 运行方式，同时支持：
+
+- 默认使用 `deerflow-backend-offline:20260505`。
+- 默认从 `patch_20260512_scheduler` 挂载 Python patch。
+- 允许通过环境变量覆盖 `IMAGE_TAG`、`PATCH_BASE`、`HOST_PORT`、`CONTAINER_NAME`。
+- 启动前自动检查并安装 `croniter`，可通过 `SCHEDULER_INSTALL_DEPS=0` 关闭。
+
+如果仍使用 0509 脚本名称，需要注意 0509 脚本里的 `PATCH_BASE` 是脚本内固定赋值，外部传环境变量不会生效。请直接编辑脚本里的：
+
+```bash
+PATCH_BASE="${SCRIPT_DIR}/patch_20260512_scheduler"
+```
+
+同时把镜像变量改成：
+
+```bash
+IMAGE_TAG="${IMAGE_TAG:-deerflow-backend-offline:20260505}"
+```
+
+### 5.7 数据库表创建说明
+
+本次新增的 SQLAlchemy model 会在后端启动初始化时注册。
+
+内网启动后检查日志：
+
+```bash
+docker logs deerflow-backend --tail 200
+```
+
+如果看到定时任务相关表不存在的错误，需要确认当前项目是否在启动时自动 `create_all`。
+
+手动验证 SQLite 数据库：
+
+```bash
+sqlite3 data/data/deerflow.db ".tables"
+```
+
+应能看到：
+
+```text
+scheduled_tasks
+scheduled_task_runs
+scheduled_task_delivery_profiles
+scheduler_threads
+```
+
+实际数据库路径以你当前 `DEER_FLOW_HOME` 和已有部署结构为准。0509 脚本中挂载的是：
+
+```text
+bundle/data -> /app/backend/.deer-flow
+```
+
+### 5.8 Element 联调步骤
+
+1. 确认内网 Matrix/Element homeserver 地址，例如：
+
+```text
+http://matrix.intranet.local:8008
+```
+
+2. 修改 `.env`：
+
+```env
+ELEMENT_ENABLED=true
+ELEMENT_HOMESERVER_URL=http://matrix.intranet.local:8008
+ELEMENT_AUTO_REGISTER=true
+ELEMENT_BOT_USERNAME=scheduled-bot
+ELEMENT_STATE_FILE=.deer-flow/data/element-bot-token
+```
+
+3. 重启后端：
+
+```bash
+./stop_backend.sh
+./start_backend.scheduler.sh
+```
+
+4. 用户进入前端任务管理页面，填写自己的 Element 用户 ID。
+
+5. 创建一个测试任务并点击「立即运行」。
+
+6. 检查：
+
+- 定时任务聊天框是否收到结果。
+- Element 私聊是否收到机器人消息。
+- 后端日志是否有 `Failed to deliver scheduled task`。
+
+## 6. 验证清单
+
+后端验证：
+
+```bash
+docker logs deerflow-backend --tail 200
+curl http://127.0.0.1:8001/openapi.json | grep scheduled-tasks
+```
+
+前端验证：
+
+- 左侧栏出现「定时任务」和「任务管理」。
+- 普通聊天列表不显示系统定时任务会话。
+- 在智能体聊天中输入「每天 9 点生成 AI 发展日报」可以创建任务。
+- 进入任务管理页可以看到任务，且可以修改、暂停、恢复、删除、立即运行。
+- 进入定时任务聊天框可以看到执行结果。
+
+Element 验证：
+
+- 未配置 `ELEMENT_HOMESERVER_URL` 时，任务仍然正常写入定时任务聊天框，不影响主流程。
+- 配置 Element 且用户填写 Element ID 后，任务成功时会发送 Matrix DM。
+
+## 7. 回滚方案
+
+后端回滚：
+
+```bash
+./stop_backend.sh
+docker load -i deerflow-backend-offline-image-20260505.tar
+IMAGE_TAG=deerflow-backend-offline:20260505 bash start_backend.sh
+```
+
+前端回滚：
+
+- 恢复上一版前端静态资源包。
+
+数据说明：
+
+- 新增表可以保留，不影响老版本读取原有聊天数据。
+- 如果需要彻底清理定时任务数据，请先备份数据库，再清理新增的四张表。
+
+## 8. 已验证事项
+
+本地已做过：
+
+- 前端 `npm run build` 通过。
+- 新增后端定时任务与 Element 文件做过 `python -m py_compile`。
+
+限制说明：
+
+- 本地全量后端 compileall 曾遇到项目中既有 Python 版本语法兼容问题，不是本次新增文件导致。
+- 当前工作区中的 `.deer-flow/data/deerflow.db*` 是本地运行数据变更，不建议纳入代码发版。

offline-backend-20260512/backend/docs/SETUP.md

@@ -0,0 +1,98 @@
+# Setup Guide
+
+Quick setup instructions for DeerFlow.
+
+## Configuration Setup
+
+DeerFlow uses a YAML configuration file that should be placed in the **project root directory**.
+
+### Steps
+
+1. **Navigate to project root**:
+   ```bash
+   cd /path/to/deer-flow
+   ```
+
+2. **Copy example configuration**:
+   ```bash
+   cp config.example.yaml config.yaml
+   ```
+
+3. **Edit configuration**:
+   ```bash
+   # Option A: Set environment variables (recommended)
+   export OPENAI_API_KEY="your-key-here"
+
+   # Optional: pin the project root when running from another directory
+   export DEER_FLOW_PROJECT_ROOT="/path/to/deer-flow"
+
+   # Option B: Edit config.yaml directly
+   vim config.yaml  # or your preferred editor
+   ```
+
+4. **Verify configuration**:
+   ```bash
+   cd backend
+   python -c "from deerflow.config import get_app_config; print('✓ Config loaded:', get_app_config().models[0].name)"
+   ```
+
+## Important Notes
+
+- **Location**: `config.yaml` should be in `deer-flow/` (project root)
+- **Git**: `config.yaml` is automatically ignored by git (contains secrets)
+- **Runtime root**: Set `DEER_FLOW_PROJECT_ROOT` if DeerFlow may start from outside the project root
+- **Runtime data**: State defaults to `.deer-flow` under the project root; set `DEER_FLOW_HOME` to move it
+- **Skills**: Skills default to `skills/` under the project root; set `DEER_FLOW_SKILLS_PATH` or `skills.path` to move them
+
+## Configuration File Locations
+
+The backend searches for `config.yaml` in this order:
+
+1. Explicit `config_path` argument from code
+2. `DEER_FLOW_CONFIG_PATH` environment variable (if set)
+3. `config.yaml` under `DEER_FLOW_PROJECT_ROOT`, or the current working directory when `DEER_FLOW_PROJECT_ROOT` is unset
+4. Legacy backend/repository-root locations for monorepo compatibility
+
+**Recommended**: Place `config.yaml` in project root (`deer-flow/config.yaml`).
+
+## Sandbox Setup (Optional but Recommended)
+
+If you plan to use Docker/Container-based sandbox (configured in `config.yaml` under `sandbox.use: deerflow.community.aio_sandbox:AioSandboxProvider`), it's highly recommended to pre-pull the container image:
+
+```bash
+# From project root
+make setup-sandbox
+```
+
+**Why pre-pull?**
+- The sandbox image (~500MB+) is pulled on first use, causing a long wait
+- Pre-pulling provides clear progress indication
+- Avoids confusion when first using the agent
+
+If you skip this step, the image will be automatically pulled on first agent execution, which may take several minutes depending on your network speed.
+
+## Troubleshooting
+
+### Config file not found
+
+```bash
+# Check where the backend is looking
+cd deer-flow/backend
+python -c "from deerflow.config.app_config import AppConfig; print(AppConfig.resolve_config_path())"
+```
+
+If it can't find the config:
+1. Ensure you've copied `config.example.yaml` to `config.yaml`
+2. Verify you're in the project root, or set `DEER_FLOW_PROJECT_ROOT`
+3. Check the file exists: `ls -la config.yaml`
+
+### Permission denied
+
+```bash
+chmod 600 ../config.yaml  # Protect sensitive configuration
+```
+
+## See Also
+
+- [Configuration Guide](CONFIGURATION.md) - Detailed configuration options
+- [Architecture Overview](../CLAUDE.md) - System architecture

offline-backend-20260512/backend/docs/STREAMING.md

@@ -0,0 +1,351 @@
+# DeerFlow 流式输出设计
+
+本文档解释 DeerFlow 是如何把 LangGraph agent 的事件流端到端送到两类消费者（HTTP 客户端、嵌入式 Python 调用方）的：两条路径为什么**必须**并存、它们各自的契约是什么、以及设计里那些 non-obvious 的不变式。
+
+---
+
+## TL;DR
+
+- DeerFlow 有**两条并行**的流式路径：**Gateway 路径**（async / HTTP SSE / JSON 序列化）服务浏览器和 IM 渠道；**DeerFlowClient 路径**（sync / in-process / 原生 LangChain 对象）服务 Jupyter、脚本、测试。它们**无法合并**——消费者模型不同。
+- 两条路径都从 `create_agent()` 工厂出发，核心都是订阅 LangGraph 的 `stream_mode=["values", "messages", "custom"]`。`values` 是节点级 state 快照，`messages` 是 LLM token 级 delta，`custom` 是显式 `StreamWriter` 事件。**这三种模式不是详细程度的梯度，是三个独立的事件源**，要 token 流就必须显式订阅 `messages`。
+- 嵌入式 client 为每个 `stream()` 调用维护三个 `set[str]`：`seen_ids` / `streamed_ids` / `counted_usage_ids`。三者看起来相似但管理**三个独立的不变式**，不能合并。
+
+---
+
+## 为什么有两条流式路径
+
+两条路径服务的消费者模型根本不同：
+
+| 维度 | Gateway 路径 | DeerFlowClient 路径 |
+|---|---|---|
+| 入口 | FastAPI `/runs/stream` endpoint | `DeerFlowClient.stream(message)` |
+| 触发层 | `runtime/runs/worker.py::run_agent` | `packages/harness/deerflow/client.py::DeerFlowClient.stream` |
+| 执行模型 | `async def` + `agent.astream()` | sync generator + `agent.stream()` |
+| 事件传输 | `StreamBridge`（asyncio Queue）+ `sse_consumer` | 直接 `yield` |
+| 序列化 | `serialize(chunk)` → 纯 JSON dict，匹配 LangGraph Platform wire 格式 | `StreamEvent.data`，携带原生 LangChain 对象 |
+| 消费者 | 前端 `useStream` React hook、飞书/Slack/Telegram channel、LangGraph SDK 客户端 | Jupyter notebook、集成测试、内部 Python 脚本 |
+| 生命周期管理 | `RunManager`：run_id 跟踪、disconnect 语义、multitask 策略、heartbeat | 无；函数返回即结束 |
+| 断连恢复 | `Last-Event-ID` SSE 重连 | 无需要 |
+
+**两条路径的存在是 DRY 的刻意妥协**：Gateway 的全部基础设施（async + Queue + JSON + RunManager）**都是为了跨网络边界把事件送给 HTTP 消费者**。当生产者（agent）和消费者（Python 调用栈）在同一个进程时，这整套东西都是纯开销。
+
+### 为什么不能让 DeerFlowClient 复用 Gateway
+
+曾经考虑过三种复用方案，都被否决：
+
+1. **让 `client.stream()` 变成 `async def client.astream()`**  
+   breaking change。用户用不上的 `async for` / `asyncio.run()` 要硬塞进 Jupyter notebook 和同步脚本。DeerFlowClient 的一大卖点（"把 agent 当普通函数调用"）直接消失。
+
+2. **在 `client.stream()` 内部起一个独立事件循环线程，用 `StreamBridge` 在 sync/async 之间做桥接**  
+   引入线程池、队列、信号量。为了"消除重复"，把**复杂度**代替代码行数引进来。是典型的"wrong abstraction"——开销高于复用收益。
+
+3. **让 `run_agent` 自己兼容 sync mode**  
+   给 Gateway 加一条用不到的死分支，污染 worker.py 的焦点。
+
+所以两条路径的事件处理逻辑会**相似但不共享**。这是刻意设计，不是疏忽。
+
+---
+
+## LangGraph `stream_mode` 三层语义
+
+LangGraph 的 `agent.stream(stream_mode=[...])` 是**多路复用**接口：一次订阅多个 mode，每个 mode 是一个独立的事件源。三种核心 mode：
+
+```mermaid
+flowchart LR
+    classDef values fill:#B8C5D1,stroke:#5A6B7A,color:#2C3E50
+    classDef messages fill:#C9B8A8,stroke:#7A6B5A,color:#2C3E50
+    classDef custom fill:#B5C4B1,stroke:#5A7A5A,color:#2C3E50
+
+    subgraph LG["LangGraph agent graph"]
+        direction TB
+        Node1["node: LLM call"]
+        Node2["node: tool call"]
+        Node3["node: reducer"]
+    end
+
+    LG -->|"每个节点完成后"| V["values: 完整 state 快照"]
+    Node1 -->|"LLM 每产生一个 token"| M["messages: (AIMessageChunk, meta)"]
+    Node1 -->|"StreamWriter.write()"| C["custom: 任意 dict"]
+
+    class V values
+    class M messages
+    class C custom
+```
+
+| Mode | 发射时机 | Payload | 粒度 |
+|---|---|---|---|
+| `values` | 每个 graph 节点完成后 | 完整 state dict（title、messages、artifacts）| 节点级 |
+| `messages` | LLM 每次 yield 一个 chunk；tool 节点完成时 | `(AIMessageChunk \| ToolMessage, metadata_dict)` | token 级 |
+| `custom` | 用户代码显式调用 `StreamWriter.write()` | 任意 dict | 应用定义 |
+
+### 两套命名的由来
+
+同一件事在**三个协议层**有三个名字：
+
+```
+Application                    HTTP / SSE                    LangGraph Graph
+┌──────────────┐               ┌──────────────┐              ┌──────────────┐
+│ frontend     │               │ LangGraph    │              │ agent.astream│
+│ useStream    │──"messages-   │ Platform SDK │──"messages"──│ graph.astream│
+│ Feishu IM    │   tuple"──────│ HTTP wire    │              │              │
+└──────────────┘               └──────────────┘              └──────────────┘
+```
+
+- **Graph 层**（`agent.stream` / `agent.astream`）：LangGraph Python 直接 API，mode 叫 **`"messages"`**。
+- **Platform SDK 层**（`langgraph-sdk` HTTP client）：跨进程 HTTP 契约，mode 叫 **`"messages-tuple"`**。
+- **Gateway worker** 显式做翻译：`if m == "messages-tuple": lg_modes.append("messages")`（`runtime/runs/worker.py:117-121`）。
+
+**后果**：`DeerFlowClient.stream()` 直接调 `agent.stream()`（Graph 层），所以必须传 `"messages"`。`app/channels/manager.py` 通过 `langgraph-sdk` 走 HTTP SDK，所以传 `"messages-tuple"`。**这两个字符串不能互相替代**，也不能抽成"一个共享常量"——它们是不同协议层的 type alias，共享只会让某一层说不是它母语的话。
+
+---
+
+## Gateway 路径：async + HTTP SSE
+
+```mermaid
+sequenceDiagram
+    participant Client as HTTP Client
+    participant API as FastAPI<br/>thread_runs.py
+    participant Svc as services.py<br/>start_run
+    participant Worker as worker.py<br/>run_agent (async)
+    participant Bridge as StreamBridge<br/>(asyncio.Queue)
+    participant Agent as LangGraph<br/>agent.astream
+    participant SSE as sse_consumer
+
+    Client->>API: POST /runs/stream
+    API->>Svc: start_run(body)
+    Svc->>Bridge: create bridge
+    Svc->>Worker: asyncio.create_task(run_agent(...))
+    Svc-->>API: StreamingResponse(sse_consumer)
+    API-->>Client: event-stream opens
+
+    par worker (producer)
+        Worker->>Agent: astream(stream_mode=lg_modes)
+        loop 每个 chunk
+            Agent-->>Worker: (mode, chunk)
+            Worker->>Bridge: publish(run_id, event, serialize(chunk))
+        end
+        Worker->>Bridge: publish_end(run_id)
+    and sse_consumer (consumer)
+        SSE->>Bridge: subscribe(run_id)
+        loop 每个 event
+            Bridge-->>SSE: StreamEvent
+            SSE-->>Client: "event: <name>\ndata: <json>\n\n"
+        end
+    end
+```
+
+关键组件：
+
+- `runtime/runs/worker.py::run_agent` — 在 `asyncio.Task` 里跑 `agent.astream()`，把每个 chunk 通过 `serialize(chunk, mode=mode)` 转成 JSON，再 `bridge.publish()`。
+- `runtime/stream_bridge` — 抽象 Queue。`publish/subscribe` 解耦生产者和消费者，支持 `Last-Event-ID` 重连、心跳、多订阅者 fan-out。
+- `app/gateway/services.py::sse_consumer` — 从 bridge 订阅，格式化为 SSE wire 帧。
+- `runtime/serialization.py::serialize` — mode-aware 序列化；`messages` mode 下 `serialize_messages_tuple` 把 `(chunk, metadata)` 转成 `[chunk.model_dump(), metadata]`。
+
+**`StreamBridge` 的存在价值**：当生产者（`run_agent` 任务）和消费者（HTTP 连接）在不同的 asyncio task 里运行时，需要一个可以跨 task 传递事件的中介。Queue 同时还承担断连重连的 buffer 和多订阅者的 fan-out。
+
+---
+
+## DeerFlowClient 路径：sync + in-process
+
+```mermaid
+sequenceDiagram
+    participant User as Python caller
+    participant Client as DeerFlowClient.stream
+    participant Agent as LangGraph<br/>agent.stream (sync)
+
+    User->>Client: for event in client.stream("hi"):
+    Client->>Agent: stream(stream_mode=["values","messages","custom"])
+    loop 每个 chunk
+        Agent-->>Client: (mode, chunk)
+        Client->>Client: 分发 mode<br/>构建 StreamEvent
+        Client-->>User: yield StreamEvent
+    end
+    Client-->>User: yield StreamEvent(type="end")
+```
+
+对比之下，sync 路径的每个环节都是显著更少的移动部件：
+
+- 没有 `RunManager` —— 一次 `stream()` 调用对应一次生命周期，无需 run_id。
+- 没有 `StreamBridge` —— 直接 `yield`，生产和消费在同一个 Python 调用栈，不需要跨 task 中介。
+- 没有 JSON 序列化 —— `StreamEvent.data` 直接装原生 LangChain 对象（`AIMessage.content`、`usage_metadata` 的 `UsageMetadata` TypedDict）。Jupyter 用户拿到的是真正的类型，不是匿名 dict。
+- 没有 asyncio —— 调用者可以直接 `for event in ...`，不必写 `async for`。
+
+---
+
+## 消费语义：delta vs cumulative
+
+LangGraph `messages` mode 给出的是 **delta**：每个 `AIMessageChunk.content` 只包含这一次新 yield 的 token，**不是**从头的累计文本。
+
+这个语义和 LangChain 的 `fs2 Stream` 风格一致：**上游发增量，下游负责累加**。Gateway 路径里前端 `useStream` React hook 自己维护累加器；DeerFlowClient 路径里 `chat()` 方法替调用者做累加。
+
+### `DeerFlowClient.chat()` 的 O(n) 累加器
+
+```python
+chunks: dict[str, list[str]] = {}
+last_id: str = ""
+for event in self.stream(message, thread_id=thread_id, **kwargs):
+    if event.type == "messages-tuple" and event.data.get("type") == "ai":
+        msg_id = event.data.get("id") or ""
+        delta = event.data.get("content", "")
+        if delta:
+            chunks.setdefault(msg_id, []).append(delta)
+            last_id = msg_id
+return "".join(chunks.get(last_id, ()))
+```
+
+**为什么不是 `buffers[id] = buffers.get(id,"") + delta`**：CPython 的字符串 in-place concat 优化仅在 refcount=1 且 LHS 是 local name 时生效；这里字符串存在 dict 里被 reassign，优化失效，每次都是 O(n) 拷贝 → 总体 O(n²)。实测 50 KB / 5000 chunk 的回复要 100-300ms 纯拷贝开销。用 `list` + `"".join()` 是 O(n)。
+
+---
+
+## 三个 id set 为什么不能合并
+
+`DeerFlowClient.stream()` 在一次调用生命周期内维护三个 `set[str]`：
+
+```python
+seen_ids: set[str] = set()           # values 路径内部 dedup
+streamed_ids: set[str] = set()       # messages → values 跨模式 dedup
+counted_usage_ids: set[str] = set()  # usage_metadata 幂等计数
+```
+
+乍看像是"三份几乎一样的东西"，实际每个管**不同的不变式**。
+
+| Set | 负责的不变式 | 被谁填充 | 被谁查询 |
+|---|---|---|---|
+| `seen_ids` | 连续两个 `values` 快照里同一条 message 只生成一个 `messages-tuple` 事件 | values 分支每处理一条消息就加入 | values 分支处理下一条消息前检查 |
+| `streamed_ids` | 如果一条消息已经通过 `messages` 模式 token 级流过，values 快照到达时**不要**再合成一次完整 `messages-tuple` | messages 分支每发一个 AI/tool 事件就加入 | values 分支看到消息时检查 |
+| `counted_usage_ids` | 同一个 `usage_metadata` 在 messages 末尾 chunk 和 values 快照的 final AIMessage 里各带一份，**累计总量只算一次** | `_account_usage()` 每次接受 usage 就加入 | `_account_usage()` 每次调用时检查 |
+
+### 为什么不能只用一个 set
+
+关键观察：**同一个 message id 在这三个 set 里的加入时机不同**。
+
+```mermaid
+sequenceDiagram
+    participant M as messages mode
+    participant V as values mode
+    participant SS as streamed_ids
+    participant SU as counted_usage_ids
+    participant SE as seen_ids
+
+    Note over M: 第一个 AI text chunk 到达
+    M->>SS: add(msg_id)
+    Note over M: 最后一个 chunk 带 usage
+    M->>SU: add(msg_id)
+    Note over V: snapshot 到达，包含同一条 AI message
+    V->>SE: add(msg_id)
+    V->>SS: 查询 → 已存在，跳过文本合成
+    V->>SU: 查询 → 已存在，不重复计数
+```
+
+- `seen_ids` **永远在 values 快照到达时**加入，所以它是 "values 已处理" 的标记。一条只出现在 messages 流里的消息（罕见但可能），`seen_ids` 里永远没有它。
+- `streamed_ids` **在 messages 流的第一个有效事件时**加入。一条只通过 values 快照到达的非 AI 消息（HumanMessage、被 truncate 的 tool 消息），`streamed_ids` 里永远没有它。
+- `counted_usage_ids` **只在看到非空 `usage_metadata` 时**加入。一条完全没有 usage 的消息（tool message、错误消息）永远不会进去。
+
+**集合包含关系**：`counted_usage_ids ⊆ (streamed_ids ∪ seen_ids)` 大致成立，但**不是严格子集**，因为一条消息可以在 messages 模式流完 text 但**在最后那个带 usage 的 chunk 之前**就被 values snapshot 赶上——此时它已经在 `streamed_ids` 里，但还不在 `counted_usage_ids` 里。把它们合并成一个 dict-of-flags 会让这个微妙的时序依赖**从类型系统里消失**，变成注释里的一句话。三个独立的 set 把不变式显式化了：每个 set 名对应一个可以口头回答的问题。
+
+---
+
+## 端到端：一次真实对话的事件时序
+
+假设调用 `client.stream("Count from 1 to 15")`，LLM 给出 "one\ntwo\n...\nfifteen"（88 字符），tokenizer 把它拆成 ~35 个 BPE chunk。下面是事件到达序列的精简版：
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant C as DeerFlowClient
+    participant A as LangGraph<br/>agent.stream
+
+    U->>C: stream("Count ... 15")
+    C->>A: stream(mode=["values","messages","custom"])
+
+    A-->>C: ("values", {messages: [HumanMessage]})
+    C-->>U: StreamEvent(type="values", ...)
+
+    Note over A,C: LLM 开始 yield token
+    loop 35 次，约 476ms
+        A-->>C: ("messages", (AIMessageChunk(content="ele"), meta))
+        C->>C: streamed_ids.add(ai-1)
+        C-->>U: StreamEvent(type="messages-tuple",<br/>data={type:ai, content:"ele", id:ai-1})
+    end
+
+    Note over A: LLM finish_reason=stop，最后一个 chunk 带 usage
+    A-->>C: ("messages", (AIMessageChunk(content="", usage_metadata={...}), meta))
+    C->>C: counted_usage_ids.add(ai-1)<br/>(无文本，不 yield)
+
+    A-->>C: ("values", {messages: [..., AIMessage(complete)]})
+    C->>C: ai-1 in streamed_ids → 跳过合成
+    C->>C: 捕获 usage (已在 counted_usage_ids，no-op)
+    C-->>U: StreamEvent(type="values", ...)
+
+    C-->>U: StreamEvent(type="end", data={usage:{...}})
+```
+
+关键观察：
+
+1. 用户看到 **35 个 messages-tuple 事件**，跨越约 476ms，每个事件带一个 token delta 和同一个 `id=ai-1`。
+2. 最后一个 `values` 快照里的 `AIMessage` **不会**再触发一个完整的 `messages-tuple` 事件——因为 `ai-1 in streamed_ids` 跳过了合成。
+3. `end` 事件里的 `usage` 正好等于那一份 cumulative usage，**不是它的两倍**——`counted_usage_ids` 在 messages 末尾 chunk 上已经吸收了，values 分支的重复访问是 no-op。
+4. 消费者拿到的 `content` 是**增量**："ele" 只包含 3 个字符，不是 "one\ntwo\n...ele"。想要完整文本要按 `id` 累加，`chat()` 已经帮你做了。
+
+---
+
+## 为什么这个设计容易出 bug，以及测试策略
+
+本文档的直接起因是 bytedance/deer-flow#1969：`DeerFlowClient.stream()` 原本只订阅 `["values", "custom"]`，**漏了 `"messages"`**。结果 `client.stream("hello")` 等价于一次性返回，视觉上和 `chat()` 没区别。
+
+这类 bug 有三个结构性原因：
+
+1. **多协议层命名**：`messages` / `messages-tuple` / HTTP SSE `messages` 是同一概念的三个名字。在其中一层出错不会在另外两层报错。
+2. **多消费者模型**：Gateway 和 DeerFlowClient 是两套独立实现，**没有单一的"订阅哪些 mode"的 single source of truth**。前者订阅对了不代表后者也订阅对了。
+3. **mock 测试绕开了真实路径**：老测试用 `agent.stream.return_value = iter([dict_chunk, ...])` 喂 values 形状的 dict 模拟 state 快照。这样构造的输入**永远不会进入 `messages` mode 分支**，所以即使 `stream_mode` 里少一个元素，CI 依然全绿。
+
+### 防御手段
+
+真正的防线是**显式断言 "messages" mode 被订阅 + 用真实 chunk shape mock**：
+
+```python
+# tests/test_client.py::test_messages_mode_emits_token_deltas
+agent.stream.return_value = iter([
+    ("messages", (AIMessageChunk(content="Hel", id="ai-1"), {})),
+    ("messages", (AIMessageChunk(content="lo ", id="ai-1"), {})),
+    ("messages", (AIMessageChunk(content="world!", id="ai-1"), {})),
+    ("values", {"messages": [HumanMessage(...), AIMessage(content="Hello world!", id="ai-1")]}),
+])
+# ...
+assert [e.data["content"] for e in ai_text_events] == ["Hel", "lo ", "world!"]
+assert len(ai_text_events) == 3  # values snapshot must NOT re-synthesize
+assert "messages" in agent.stream.call_args.kwargs["stream_mode"]
+```
+
+**为什么这比"抽一个共享常量"更有效**：共享常量只能保证"用它的人写对字符串"，但新增消费者的人可能根本不知道常量在哪。行为断言强制任何改动都要穿过**实际执行路径**，改回 `["values", "custom"]` 会立刻让 `assert "messages" in ...` 失败。
+
+### 活体信号：BPE 子词边界
+
+回归的最终验证是让真实 LLM 数 1-15，然后看是否能在输出里看到 tokenizer 的子词切分：
+
+```
+[5.460s] 'ele' / 'ven'      eleven 被拆成两个 token
+[5.508s] 'tw'  / 'elve'     twelve 拆两个
+[5.568s] 'th'  / 'irteen'   thirteen 拆两个
+[5.623s] 'four'/ 'teen'     fourteen 拆两个
+[5.677s] 'f'   / 'if' / 'teen'  fifteen 拆三个
+```
+
+子词切分是 tokenizer 的外部事实，**无法伪造**。能看到它就说明数据流**逐 chunk** 地穿过了整条管道，没有被任何中间层缓冲成整段。这种"活体信号"在流式系统里是比单元测试更高置信度的证据。
+
+---
+
+## 相关源码定位
+
+| 关心什么 | 看这里 |
+|---|---|
+| DeerFlowClient 嵌入式流 | `packages/harness/deerflow/client.py::DeerFlowClient.stream` |
+| `chat()` 的 delta 累加器 | `packages/harness/deerflow/client.py::DeerFlowClient.chat` |
+| Gateway async 流 | `packages/harness/deerflow/runtime/runs/worker.py::run_agent` |
+| HTTP SSE 帧输出 | `app/gateway/services.py::sse_consumer` / `format_sse` |
+| 序列化到 wire 格式 | `packages/harness/deerflow/runtime/serialization.py` |
+| LangGraph mode 命名翻译 | `packages/harness/deerflow/runtime/runs/worker.py:117-121` |
+| 飞书渠道的增量卡片更新 | `app/channels/manager.py::_handle_streaming_chat` |
+| Channels 自带的 delta/cumulative 防御性累加 | `app/channels/manager.py::_merge_stream_text` |
+| Frontend useStream 支持的 mode 集合 | `frontend/src/core/api/stream-mode.ts` |
+| 核心回归测试 | `backend/tests/test_client.py::TestStream::test_messages_mode_emits_token_deltas` |

offline-backend-20260512/backend/docs/TITLE_GENERATION_IMPLEMENTATION.md

@@ -0,0 +1,222 @@
+# 自动 Title 生成功能实现总结
+
+## ✅ 已完成的工作
+
+### 1. 核心实现文件
+
+#### [`packages/harness/deerflow/agents/thread_state.py`](../packages/harness/deerflow/agents/thread_state.py)
+- ✅ 添加 `title: str | None = None` 字段到 `ThreadState`
+
+#### [`packages/harness/deerflow/config/title_config.py`](../packages/harness/deerflow/config/title_config.py) (新建)
+- ✅ 创建 `TitleConfig` 配置类
+- ✅ 支持配置：enabled, max_words, max_chars, model_name, prompt_template
+- ✅ 提供 `get_title_config()` 和 `set_title_config()` 函数
+- ✅ 提供 `load_title_config_from_dict()` 从配置文件加载
+
+#### [`packages/harness/deerflow/agents/middlewares/title_middleware.py`](../packages/harness/deerflow/agents/middlewares/title_middleware.py) (新建)
+- ✅ 创建 `TitleMiddleware` 类
+- ✅ 实现 `_should_generate_title()` 检查是否需要生成
+- ✅ 实现 `_generate_title()` 调用 LLM 生成标题
+- ✅ 实现 `after_agent()` 钩子，在首次对话后自动触发
+- ✅ 包含 fallback 策略（LLM 失败时使用用户消息前几个词）
+
+#### [`packages/harness/deerflow/config/app_config.py`](../packages/harness/deerflow/config/app_config.py)
+- ✅ 导入 `load_title_config_from_dict`
+- ✅ 在 `from_file()` 中加载 title 配置
+
+#### [`packages/harness/deerflow/agents/lead_agent/agent.py`](../packages/harness/deerflow/agents/lead_agent/agent.py)
+- ✅ 导入 `TitleMiddleware`
+- ✅ 注册到 `middleware` 列表：`[SandboxMiddleware(), TitleMiddleware()]`
+
+### 2. 配置文件
+
+#### [`config.yaml`](../../config.example.yaml)
+- ✅ 添加 title 配置段：
+```yaml
+title:
+  enabled: true
+  max_words: 6
+  max_chars: 60
+  model_name: null
+```
+
+### 3. 文档
+
+#### [`docs/AUTO_TITLE_GENERATION.md`](../docs/AUTO_TITLE_GENERATION.md) (新建)
+- ✅ 完整的功能说明文档
+- ✅ 实现方式和架构设计
+- ✅ 配置说明
+- ✅ 客户端使用示例（TypeScript）
+- ✅ 工作流程图（Mermaid）
+- ✅ 故障排查指南
+- ✅ State vs Metadata 对比
+
+#### [`TODO.md`](TODO.md)
+- ✅ 添加功能完成记录
+
+### 4. 测试
+
+#### [`tests/test_title_generation.py`](../tests/test_title_generation.py) (新建)
+- ✅ 配置类测试
+- ✅ Middleware 初始化测试
+- ✅ TODO: 集成测试（需要 mock Runtime）
+
+---
+
+## 🎯 核心设计决策
+
+### 为什么使用 State 而非 Metadata？
+
+| 方面 | State (✅ 采用) | Metadata (❌ 未采用) |
+|------|----------------|---------------------|
+| **持久化** | 自动（通过 checkpointer） | 取决于实现，不可靠 |
+| **版本控制** | 支持时间旅行 | 不支持 |
+| **类型安全** | TypedDict 定义 | 任意字典 |
+| **标准化** | LangGraph 核心机制 | 扩展功能 |
+
+### 工作流程
+
+```
+用户发送首条消息
+  ↓
+Agent 处理并返回回复
+  ↓
+TitleMiddleware.after_agent() 触发
+  ↓
+检查：是否首次对话？是否已有 title？
+  ↓
+调用 LLM 生成 title
+  ↓
+返回 {"title": "..."} 更新 state
+  ↓
+Checkpointer 自动持久化（如果配置了）
+  ↓
+客户端从 state.values.title 读取
+```
+
+---
+
+## 📋 使用指南
+
+### 后端配置
+
+1. **启用/禁用功能**
+```yaml
+# config.yaml
+title:
+  enabled: true  # 设为 false 禁用
+```
+
+2. **自定义配置**
+```yaml
+title:
+  enabled: true
+  max_words: 8      # 标题最多 8 个词
+  max_chars: 80     # 标题最多 80 个字符
+  model_name: null  # 使用默认模型
+```
+
+3. **配置持久化（可选）**
+
+如果需要在本地开发时持久化 title：
+
+```python
+# checkpointer.py
+from langgraph.checkpoint.sqlite import SqliteSaver
+
+checkpointer = SqliteSaver.from_conn_string("deerflow.db")
+```
+
+```json
+// langgraph.json
+{
+  "graphs": {
+    "lead_agent": "deerflow.agents:lead_agent"
+  },
+  "checkpointer": "checkpointer:checkpointer"
+}
+```
+
+### 客户端使用
+
+```typescript
+// 获取 thread title
+const state = await client.threads.getState(threadId);
+const title = state.values.title || "New Conversation";
+
+// 显示在对话列表
+<li>{title}</li>
+```
+
+**⚠️ 注意**：Title 在 `state.values.title`，而非 `thread.metadata.title`
+
+---
+
+## 🧪 测试
+
+```bash
+# 运行测试
+pytest tests/test_title_generation.py -v
+
+# 运行所有测试
+pytest
+```
+
+---
+
+## 🔍 故障排查
+
+### Title 没有生成？
+
+1. 检查配置：`title.enabled = true`
+2. 查看日志：搜索 "Generated thread title"
+3. 确认是首次对话（1 个用户消息 + 1 个助手回复）
+
+### Title 生成但看不到？
+
+1. 确认读取位置：`state.values.title`（不是 `thread.metadata.title`）
+2. 检查 API 响应是否包含 title
+3. 重新获取 state
+
+### Title 重启后丢失？
+
+1. 本地开发需要配置 checkpointer
+2. LangGraph Platform 会自动持久化
+3. 检查数据库确认 checkpointer 工作正常
+
+---
+
+## 📊 性能影响
+
+- **延迟增加**：约 0.5-1 秒（LLM 调用）
+- **并发安全**：在 `after_agent` 中运行，不阻塞主流程
+- **资源消耗**：每个 thread 只生成一次
+
+### 优化建议
+
+1. 使用更快的模型（如 `gpt-3.5-turbo`）
+2. 减少 `max_words` 和 `max_chars`
+3. 调整 prompt 使其更简洁
+
+---
+
+## 🚀 下一步
+
+- [ ] 添加集成测试（需要 mock LangGraph Runtime）
+- [ ] 支持自定义 prompt template
+- [ ] 支持多语言 title 生成
+- [ ] 添加 title 重新生成功能
+- [ ] 监控 title 生成成功率和延迟
+
+---
+
+## 📚 相关资源
+
+- [完整文档](../docs/AUTO_TITLE_GENERATION.md)
+- [LangGraph Middleware](https://langchain-ai.github.io/langgraph/concepts/middleware/)
+- [LangGraph State 管理](https://langchain-ai.github.io/langgraph/concepts/low_level/#state)
+- [LangGraph Checkpointer](https://langchain-ai.github.io/langgraph/concepts/persistence/)
+
+---
+
+*实现完成时间: 2026-01-14*

offline-backend-20260512/backend/docs/TODO.md

@@ -0,0 +1,34 @@
+# TODO List
+
+## Completed Features
+
+- [x] Launch the sandbox only after the first file system or bash tool is called
+- [x] Add Clarification Process for the whole process
+- [x] Implement Context Summarization Mechanism to avoid context explosion
+- [x] Integrate MCP (Model Context Protocol) for extensible tools
+- [x] Add file upload support with automatic document conversion
+- [x] Implement automatic thread title generation
+- [x] Add Plan Mode with TodoList middleware
+- [x] Add vision model support with ViewImageMiddleware
+- [x] Skills system with SKILL.md format
+- [x] Replace `time.sleep(5)` with `asyncio.sleep()` in `packages/harness/deerflow/tools/builtins/task_tool.py` (subagent polling)
+
+## Planned Features
+
+- [ ] Pooling the sandbox resources to reduce the number of sandbox containers
+- [ ] Add authentication/authorization layer
+- [ ] Implement rate limiting
+- [ ] Add metrics and monitoring
+- [ ] Support for more document formats in upload
+- [ ] Skill marketplace / remote skill installation
+- [ ] Optimize async concurrency in agent hot path (IM channels multi-task scenario)
+- [ ] Replace `subprocess.run()` with `asyncio.create_subprocess_shell()` in `packages/harness/deerflow/sandbox/local/local_sandbox.py`
+  - Replace sync `requests` with `httpx.AsyncClient` in community tools (tavily, jina_ai, firecrawl, infoquest, image_search)
+  - [x] Replace sync `model.invoke()` with async `model.ainvoke()` in title_middleware and memory updater
+  - Consider `asyncio.to_thread()` wrapper for remaining blocking file I/O
+  - For production: use `langgraph up` (multi-worker) instead of `langgraph dev` (single-worker)
+
+## Resolved Issues
+
+- [x] Make sure that no duplicated files in `state.artifacts`
+- [x] Long thinking but with empty content (answer inside thinking process)

offline-backend-20260512/backend/docs/memory-settings-sample.json

@@ -0,0 +1,114 @@
+{
+  "version": "1.0",
+  "lastUpdated": "2026-03-28T10:30:00Z",
+  "user": {
+    "workContext": {
+      "summary": "Working on DeerFlow memory management UX, including local search, local filters, clear-all, and single-fact deletion in Settings > Memory.",
+      "updatedAt": "2026-03-28T10:30:00Z"
+    },
+    "personalContext": {
+      "summary": "Prefers Chinese during collaboration, but wants GitHub PR titles and bodies written in English with a Chinese translation provided alongside them.",
+      "updatedAt": "2026-03-28T10:28:00Z"
+    },
+    "topOfMind": {
+      "summary": "Wants reviewers to be able to reproduce the memory search and filter flow quickly with pre-populated sample data.",
+      "updatedAt": "2026-03-28T10:26:00Z"
+    }
+  },
+  "history": {
+    "recentMonths": {
+      "summary": "Recently contributed multiple DeerFlow pull requests covering memory, uploads, and compatibility fixes.",
+      "updatedAt": "2026-03-28T10:24:00Z"
+    },
+    "earlierContext": {
+      "summary": "Often prefers shipping smaller, reviewable changes with explicit validation notes.",
+      "updatedAt": "2026-03-28T10:22:00Z"
+    },
+    "longTermBackground": {
+      "summary": "Actively building open-source contribution experience and improving end-to-end delivery quality.",
+      "updatedAt": "2026-03-28T10:20:00Z"
+    }
+  },
+  "facts": [
+    {
+      "id": "fact_review_001",
+      "content": "User prefers Chinese for day-to-day collaboration.",
+      "category": "preference",
+      "confidence": 0.95,
+      "createdAt": "2026-03-28T09:50:00Z",
+      "source": "thread_pref_cn"
+    },
+    {
+      "id": "fact_review_002",
+      "content": "PR titles and bodies should be drafted in English and accompanied by a Chinese translation.",
+      "category": "workflow",
+      "confidence": 0.93,
+      "createdAt": "2026-03-28T09:52:00Z",
+      "source": "thread_pr_style"
+    },
+    {
+      "id": "fact_review_003",
+      "content": "User implemented memory search and filter improvements in the DeerFlow settings page.",
+      "category": "project",
+      "confidence": 0.91,
+      "createdAt": "2026-03-28T09:54:00Z",
+      "source": "thread_memory_filters"
+    },
+    {
+      "id": "fact_review_004",
+      "content": "User added clear-all memory support through the gateway memory API.",
+      "category": "project",
+      "confidence": 0.89,
+      "createdAt": "2026-03-28T09:56:00Z",
+      "source": "thread_memory_clear"
+    },
+    {
+      "id": "fact_review_005",
+      "content": "User added single-fact deletion support for persisted memory entries.",
+      "category": "project",
+      "confidence": 0.9,
+      "createdAt": "2026-03-28T09:58:00Z",
+      "source": "thread_memory_delete"
+    },
+    {
+      "id": "fact_review_006",
+      "content": "Reviewer can search for keyword memory to see multiple matching facts.",
+      "category": "testing",
+      "confidence": 0.84,
+      "createdAt": "2026-03-28T10:00:00Z",
+      "source": "thread_review_demo"
+    },
+    {
+      "id": "fact_review_007",
+      "content": "Reviewer can search for keyword Chinese to verify cross-category matching.",
+      "category": "testing",
+      "confidence": 0.82,
+      "createdAt": "2026-03-28T10:02:00Z",
+      "source": "thread_review_demo"
+    },
+    {
+      "id": "fact_review_008",
+      "content": "Reviewer can search for workflow to verify category text is included in local filtering.",
+      "category": "testing",
+      "confidence": 0.81,
+      "createdAt": "2026-03-28T10:04:00Z",
+      "source": "thread_review_demo"
+    },
+    {
+      "id": "fact_review_009",
+      "content": "Delete fact testing can target this disposable sample entry.",
+      "category": "testing",
+      "confidence": 0.78,
+      "createdAt": "2026-03-28T10:06:00Z",
+      "source": "thread_delete_demo"
+    },
+    {
+      "id": "fact_review_010",
+      "content": "This sample fact is intended for edit testing.",
+      "category": "testing",
+      "confidence": 0.8,
+      "createdAt": "2026-03-28T10:08:00Z",
+      "source": "manual"
+    }
+  ]
+}

offline-backend-20260512/backend/docs/middleware-execution-flow.md

@@ -0,0 +1,291 @@
+# Middleware 执行流程
+
+## Middleware 列表
+
+`create_deerflow_agent` 通过 `RuntimeFeatures` 组装的完整 middleware 链（默认全开时）：
+
+| # | Middleware | `before_agent` | `before_model` | `after_model` | `after_agent` | `wrap_tool_call` | 主 Agent | Subagent | 来源 |
+|---|-----------|:-:|:-:|:-:|:-:|:-:|:-:|:-:|------|
+| 0 | ThreadDataMiddleware | ✓ | | | | | ✓ | ✓ | `sandbox` |
+| 1 | UploadsMiddleware | ✓ | | | | | ✓ | ✗ | `sandbox` |
+| 2 | SandboxMiddleware | ✓ | | | ✓ | | ✓ | ✓ | `sandbox` |
+| 3 | DanglingToolCallMiddleware | | | ✓ | | | ✓ | ✗ | 始终开启 |
+| 4 | GuardrailMiddleware | | | | | ✓ | ✓ | ✓ | *Phase 2 纳入* |
+| 5 | ToolErrorHandlingMiddleware | | | | | ✓ | ✓ | ✓ | 始终开启 |
+| 6 | SummarizationMiddleware | | | ✓ | | | ✓ | ✗ | `summarization` |
+| 7 | TodoMiddleware | | | ✓ | | | ✓ | ✗ | `plan_mode` 参数 |
+| 8 | TitleMiddleware | | | ✓ | | | ✓ | ✗ | `auto_title` |
+| 9 | MemoryMiddleware | | | | ✓ | | ✓ | ✗ | `memory` |
+| 10 | ViewImageMiddleware | | ✓ | | | | ✓ | ✗ | `vision` |
+| 11 | SubagentLimitMiddleware | | | ✓ | | | ✓ | ✗ | `subagent` |
+| 12 | LoopDetectionMiddleware | | | ✓ | | | ✓ | ✗ | 始终开启 |
+| 13 | ClarificationMiddleware | | | ✓ | | | ✓ | ✗ | 始终最后 |
+
+主 agent **14 个** middleware（`make_lead_agent`），subagent **4 个**（ThreadData、Sandbox、Guardrail、ToolErrorHandling）。`create_deerflow_agent` Phase 1 实现 **13 个**（Guardrail 仅支持自定义实例，无内置默认）。
+
+## 执行流程
+
+LangChain `create_agent` 的规则：
+- **`before_*` 正序执行**（列表位置 0 → N）
+- **`after_*` 反序执行**（列表位置 N → 0）
+
+```mermaid
+graph TB
+    START(["invoke"]) --> TD
+
+    subgraph BA ["<b>before_agent</b> 正序 0→N"]
+        direction TB
+        TD["[0] ThreadData<br/>创建线程目录"] --> UL["[1] Uploads<br/>扫描上传文件"] --> SB["[2] Sandbox<br/>获取沙箱"]
+    end
+
+    subgraph BM ["<b>before_model</b> 正序 0→N"]
+        direction TB
+        VI["[10] ViewImage<br/>注入图片 base64"]
+    end
+
+    SB --> VI
+    VI --> M["<b>MODEL</b>"]
+
+    subgraph AM ["<b>after_model</b> 反序 N→0"]
+        direction TB
+        CL["[13] Clarification<br/>拦截 ask_clarification"] --> LD["[12] LoopDetection<br/>检测循环"] --> SL["[11] SubagentLimit<br/>截断多余 task"] --> TI["[8] Title<br/>生成标题"] --> SM["[6] Summarization<br/>上下文压缩"] --> DTC["[3] DanglingToolCall<br/>补缺失 ToolMessage"]
+    end
+
+    M --> CL
+
+    subgraph AA ["<b>after_agent</b> 反序 N→0"]
+        direction TB
+        SBR["[2] Sandbox<br/>释放沙箱"] --> MEM["[9] Memory<br/>入队记忆"]
+    end
+
+    DTC --> SBR
+    MEM --> END(["response"])
+
+    classDef beforeNode fill:#a0a8b5,stroke:#636b7a,color:#2d3239
+    classDef modelNode fill:#b5a8a0,stroke:#7a6b63,color:#2d3239
+    classDef afterModelNode fill:#b5a0a8,stroke:#7a636b,color:#2d3239
+    classDef afterAgentNode fill:#a0b5a8,stroke:#637a6b,color:#2d3239
+    classDef terminalNode fill:#a8b5a0,stroke:#6b7a63,color:#2d3239
+
+    class TD,UL,SB,VI beforeNode
+    class M modelNode
+    class CL,LD,SL,TI,SM,DTC afterModelNode
+    class SBR,MEM afterAgentNode
+    class START,END terminalNode
+```
+
+## 时序图
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant TD as ThreadDataMiddleware
+    participant UL as UploadsMiddleware
+    participant SB as SandboxMiddleware
+    participant VI as ViewImageMiddleware
+    participant M as MODEL
+    participant CL as ClarificationMiddleware
+    participant SL as SubagentLimitMiddleware
+    participant TI as TitleMiddleware
+    participant SM as SummarizationMiddleware
+    participant DTC as DanglingToolCallMiddleware
+    participant MEM as MemoryMiddleware
+
+    U ->> TD: invoke
+    activate TD
+    Note right of TD: before_agent 创建目录
+
+    TD ->> UL: before_agent
+    activate UL
+    Note right of UL: before_agent 扫描上传文件
+
+    UL ->> SB: before_agent
+    activate SB
+    Note right of SB: before_agent 获取沙箱
+
+    SB ->> VI: before_model
+    activate VI
+    Note right of VI: before_model 注入图片 base64
+
+    VI ->> M: messages + tools
+    activate M
+    M -->> CL: AI response
+    deactivate M
+
+    activate CL
+    Note right of CL: after_model 拦截 ask_clarification
+    CL -->> SL: after_model
+    deactivate CL
+
+    activate SL
+    Note right of SL: after_model 截断多余 task
+    SL -->> TI: after_model
+    deactivate SL
+
+    activate TI
+    Note right of TI: after_model 生成标题
+    TI -->> SM: after_model
+    deactivate TI
+
+    activate SM
+    Note right of SM: after_model 上下文压缩
+    SM -->> DTC: after_model
+    deactivate SM
+
+    activate DTC
+    Note right of DTC: after_model 补缺失 ToolMessage
+    DTC -->> VI: done
+    deactivate DTC
+
+    VI -->> SB: done
+    deactivate VI
+
+    Note right of SB: after_agent 释放沙箱
+    SB -->> UL: done
+    deactivate SB
+
+    UL -->> TD: done
+    deactivate UL
+
+    Note right of MEM: after_agent 入队记忆
+
+    TD -->> U: response
+    deactivate TD
+```
+
+## 洋葱模型
+
+列表位置决定在洋葱中的层级 — 位置 0 最外层，位置 N 最内层：
+
+```
+进入 before_*：   [0] → [1] → [2] → ... → [10] → MODEL
+退出 after_*：    MODEL → [13] → [11] → ... → [6] → [3] → [2] → [0]
+                          ↑ 最内层最先执行
+```
+
+> [!important] 核心规则
+> 列表最后的 middleware，其 `after_model` **最先执行**。
+> ClarificationMiddleware 在列表末尾，所以它第一个拦截 model 输出。
+
+## 对比：真正的洋葱 vs DeerFlow 的实际情况
+
+### 真正的洋葱（如 Koa/Express）
+
+每个 middleware 同时负责 before 和 after，形成对称嵌套：
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant A as AuthMiddleware
+    participant L as LogMiddleware
+    participant R as RateLimitMiddleware
+    participant H as Handler
+
+    U ->> A: request
+    activate A
+    Note right of A: before: 校验 token
+
+    A ->> L: next()
+    activate L
+    Note right of L: before: 记录请求时间
+
+    L ->> R: next()
+    activate R
+    Note right of R: before: 检查频率
+
+    R ->> H: next()
+    activate H
+    H -->> R: result
+    deactivate H
+
+    Note right of R: after: 更新计数器
+    R -->> L: result
+    deactivate R
+
+    Note right of L: after: 记录耗时
+    L -->> A: result
+    deactivate L
+
+    Note right of A: after: 清理上下文
+    A -->> U: response
+    deactivate A
+```
+
+> [!tip] 洋葱特征
+> 每个 middleware 都有 before/after 对称操作，`activate` 跨越整个内层执行，形成完美嵌套。
+
+### DeerFlow 的实际情况
+
+不是洋葱，是管道。大部分 middleware 只用一个钩子，不存在对称嵌套。多轮对话时 before_model / after_model 循环执行：
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant TD as ThreadData
+    participant UL as Uploads
+    participant SB as Sandbox
+    participant VI as ViewImage
+    participant M as MODEL
+    participant CL as Clarification
+    participant SL as SubagentLimit
+    participant TI as Title
+    participant SM as Summarization
+    participant MEM as Memory
+
+    U ->> TD: invoke
+    Note right of TD: before_agent 创建目录
+    TD ->> UL: .
+    Note right of UL: before_agent 扫描文件
+    UL ->> SB: .
+    Note right of SB: before_agent 获取沙箱
+
+    loop 每轮对话（tool call 循环）
+        SB ->> VI: .
+        Note right of VI: before_model 注入图片
+        VI ->> M: messages + tools
+        M -->> CL: AI response
+        Note right of CL: after_model 拦截 ask_clarification
+        CL -->> SL: .
+        Note right of SL: after_model 截断多余 task
+        SL -->> TI: .
+        Note right of TI: after_model 生成标题
+        TI -->> SM: .
+        Note right of SM: after_model 上下文压缩
+    end
+
+    Note right of SB: after_agent 释放沙箱
+    SB -->> MEM: .
+    Note right of MEM: after_agent 入队记忆
+    MEM -->> U: response
+```
+
+> [!warning] 不是洋葱
+> 14 个 middleware 中只有 SandboxMiddleware 有 before/after 对称（获取/释放）。其余都是单向的：要么只在 `before_*` 做事，要么只在 `after_*` 做事。`before_agent` / `after_agent` 只跑一次，`before_model` / `after_model` 每轮循环都跑。
+
+硬依赖只有 2 处：
+
+1. **ThreadData 在 Sandbox 之前** — sandbox 需要线程目录
+2. **Clarification 在列表最后** — `after_model` 反序时最先执行，第一个拦截 `ask_clarification`
+
+### 结论
+
+| | 真正的洋葱 | DeerFlow 实际 |
+|---|---|---|
+| 每个 middleware | before + after 对称 | 大多只用一个钩子 |
+| 激活条 | 嵌套（外长内短） | 不嵌套（串行） |
+| 反序的意义 | 清理与初始化配对 | 仅影响 after_model 的执行优先级 |
+| 典型例子 | Auth: 校验 token / 清理上下文 | ThreadData: 只创建目录，没有清理 |
+
+## 关键设计点
+
+### ClarificationMiddleware 为什么在列表最后？
+
+位置最后 = `after_model` 最先执行。它需要**第一个**看到 model 输出，检查是否有 `ask_clarification` tool call。如果有，立即中断（`Command(goto=END)`），后续 middleware 的 `after_model` 不再执行。
+
+### SandboxMiddleware 的对称性
+
+`before_agent`（正序第 3 个）获取沙箱，`after_agent`（反序第 1 个）释放沙箱。外层进入 → 外层退出，天然的洋葱对称。
+
+### 大部分 middleware 只用一个钩子
+
+14 个 middleware 中，只有 SandboxMiddleware 同时用了 `before_agent` + `after_agent`（获取/释放）。其余都只在一个阶段执行。洋葱模型的反序特性主要影响 `after_model` 阶段的执行顺序。

offline-backend-20260512/backend/docs/plan_mode_usage.md

@@ -0,0 +1,204 @@
+# Plan Mode with TodoList Middleware
+
+This document describes how to enable and use the Plan Mode feature with TodoList middleware in DeerFlow 2.0.
+
+## Overview
+
+Plan Mode adds a TodoList middleware to the agent, which provides a `write_todos` tool that helps the agent:
+- Break down complex tasks into smaller, manageable steps
+- Track progress as work progresses
+- Provide visibility to users about what's being done
+
+The TodoList middleware is built on LangChain's `TodoListMiddleware`.
+
+## Configuration
+
+### Enabling Plan Mode
+
+Plan mode is controlled via **runtime configuration** through the `is_plan_mode` parameter in the `configurable` section of `RunnableConfig`. This allows you to dynamically enable or disable plan mode on a per-request basis.
+
+```python
+from langchain_core.runnables import RunnableConfig
+from deerflow.agents.lead_agent.agent import make_lead_agent
+
+# Enable plan mode via runtime configuration
+config = RunnableConfig(
+    configurable={
+        "thread_id": "example-thread",
+        "thinking_enabled": True,
+        "is_plan_mode": True,  # Enable plan mode
+    }
+)
+
+# Create agent with plan mode enabled
+agent = make_lead_agent(config)
+```
+
+### Configuration Options
+
+- **is_plan_mode** (bool): Whether to enable plan mode with TodoList middleware. Default: `False`
+  - Pass via `config.get("configurable", {}).get("is_plan_mode", False)`
+  - Can be set dynamically for each agent invocation
+  - No global configuration needed
+
+## Default Behavior
+
+When plan mode is enabled with default settings, the agent will have access to a `write_todos` tool with the following behavior:
+
+### When to Use TodoList
+
+The agent will use the todo list for:
+1. Complex multi-step tasks (3+ distinct steps)
+2. Non-trivial tasks requiring careful planning
+3. When user explicitly requests a todo list
+4. When user provides multiple tasks
+
+### When NOT to Use TodoList
+
+The agent will skip using the todo list for:
+1. Single, straightforward tasks
+2. Trivial tasks (< 3 steps)
+3. Purely conversational or informational requests
+
+### Task States
+
+- **pending**: Task not yet started
+- **in_progress**: Currently working on (can have multiple parallel tasks)
+- **completed**: Task finished successfully
+
+## Usage Examples
+
+### Basic Usage
+
+```python
+from langchain_core.runnables import RunnableConfig
+from deerflow.agents.lead_agent.agent import make_lead_agent
+
+# Create agent with plan mode ENABLED
+config_with_plan_mode = RunnableConfig(
+    configurable={
+        "thread_id": "example-thread",
+        "thinking_enabled": True,
+        "is_plan_mode": True,  # TodoList middleware will be added
+    }
+)
+agent_with_todos = make_lead_agent(config_with_plan_mode)
+
+# Create agent with plan mode DISABLED (default)
+config_without_plan_mode = RunnableConfig(
+    configurable={
+        "thread_id": "another-thread",
+        "thinking_enabled": True,
+        "is_plan_mode": False,  # No TodoList middleware
+    }
+)
+agent_without_todos = make_lead_agent(config_without_plan_mode)
+```
+
+### Dynamic Plan Mode per Request
+
+You can enable/disable plan mode dynamically for different conversations or tasks:
+
+```python
+from langchain_core.runnables import RunnableConfig
+from deerflow.agents.lead_agent.agent import make_lead_agent
+
+def create_agent_for_task(task_complexity: str):
+    """Create agent with plan mode based on task complexity."""
+    is_complex = task_complexity in ["high", "very_high"]
+
+    config = RunnableConfig(
+        configurable={
+            "thread_id": f"task-{task_complexity}",
+            "thinking_enabled": True,
+            "is_plan_mode": is_complex,  # Enable only for complex tasks
+        }
+    )
+
+    return make_lead_agent(config)
+
+# Simple task - no TodoList needed
+simple_agent = create_agent_for_task("low")
+
+# Complex task - TodoList enabled for better tracking
+complex_agent = create_agent_for_task("high")
+```
+
+## How It Works
+
+1. When `make_lead_agent(config)` is called, it extracts `is_plan_mode` from `config.configurable`
+2. The config is passed to `_build_middlewares(config)`
+3. `_build_middlewares()` reads `is_plan_mode` and calls `_create_todo_list_middleware(is_plan_mode)`
+4. If `is_plan_mode=True`, a `TodoListMiddleware` instance is created and added to the middleware chain
+5. The middleware automatically adds a `write_todos` tool to the agent's toolset
+6. The agent can use this tool to manage tasks during execution
+7. The middleware handles the todo list state and provides it to the agent
+
+## Architecture
+
+```
+make_lead_agent(config)
+  │
+  ├─> Extracts: is_plan_mode = config.configurable.get("is_plan_mode", False)
+  │
+  └─> _build_middlewares(config)
+        │
+        ├─> ThreadDataMiddleware
+        ├─> SandboxMiddleware
+        ├─> SummarizationMiddleware (if enabled via global config)
+        ├─> TodoListMiddleware (if is_plan_mode=True) ← NEW
+        ├─> TitleMiddleware
+        └─> ClarificationMiddleware
+```
+
+## Implementation Details
+
+### Agent Module
+- **Location**: `packages/harness/deerflow/agents/lead_agent/agent.py`
+- **Function**: `_create_todo_list_middleware(is_plan_mode: bool)` - Creates TodoListMiddleware if plan mode is enabled
+- **Function**: `_build_middlewares(config: RunnableConfig)` - Builds middleware chain based on runtime config
+- **Function**: `make_lead_agent(config: RunnableConfig)` - Creates agent with appropriate middlewares
+
+### Runtime Configuration
+Plan mode is controlled via the `is_plan_mode` parameter in `RunnableConfig.configurable`:
+```python
+config = RunnableConfig(
+    configurable={
+        "is_plan_mode": True,  # Enable plan mode
+        # ... other configurable options
+    }
+)
+```
+
+## Key Benefits
+
+1. **Dynamic Control**: Enable/disable plan mode per request without global state
+2. **Flexibility**: Different conversations can have different plan mode settings
+3. **Simplicity**: No need for global configuration management
+4. **Context-Aware**: Plan mode decision can be based on task complexity, user preferences, etc.
+
+## Custom Prompts
+
+DeerFlow uses custom `system_prompt` and `tool_description` for the TodoListMiddleware that match the overall DeerFlow prompt style:
+
+### System Prompt Features
+- Uses XML tags (`<todo_list_system>`) for structure consistency with DeerFlow's main prompt
+- Emphasizes CRITICAL rules and best practices
+- Clear "When to Use" vs "When NOT to Use" guidelines
+- Focuses on real-time updates and immediate task completion
+
+### Tool Description Features
+- Detailed usage scenarios with examples
+- Strong emphasis on NOT using for simple tasks
+- Clear task state definitions (pending, in_progress, completed)
+- Comprehensive best practices section
+- Task completion requirements to prevent premature marking
+
+The custom prompts are defined in `_create_todo_list_middleware()` in `/Users/hetao/workspace/deer-flow/backend/packages/harness/deerflow/agents/lead_agent/agent.py:57`.
+
+## Notes
+
+- TodoList middleware uses LangChain's built-in `TodoListMiddleware` with **custom DeerFlow-style prompts**
+- Plan mode is **disabled by default** (`is_plan_mode=False`) to maintain backward compatibility
+- The middleware is positioned before `ClarificationMiddleware` to allow todo management during clarification flows
+- Custom prompts emphasize the same principles as DeerFlow's main system prompt (clarity, action-oriented, critical rules)

offline-backend-20260512/backend/docs/rfc-create-deerflow-agent.md

@@ -0,0 +1,503 @@
+# RFC: `create_deerflow_agent` — 纯参数的 SDK 工厂 API
+
+## 1. 问题
+
+当前 harness 的唯一公开入口是 `make_lead_agent(config: RunnableConfig)`。它内部：
+
+```
+make_lead_agent
+  ├─ get_app_config()          ← 读 config.yaml
+  ├─ _resolve_model_name()     ← 读 config.yaml
+  ├─ load_agent_config()       ← 读 agents/{name}/config.yaml
+  ├─ create_chat_model(name)   ← 读 config.yaml（反射加载 model class）
+  ├─ get_available_tools()     ← 读 config.yaml + extensions_config.json
+  ├─ apply_prompt_template()   ← 读 skills 目录 + memory.json
+  └─ _build_middlewares()      ← 读 config.yaml（summarization、model vision）
+```
+
+**6 处隐式 I/O** — 全部依赖文件系统。如果你想把 `deerflow-harness` 当 Python 库嵌入自己的应用，你必须准备 `config.yaml` + `extensions_config.json` + skills 目录。这对 SDK 用户是不可接受的。
+
+### 对比
+
+| | `langchain.create_agent` | `make_lead_agent` | `DeerFlowClient`（增强后） |
+|---|---|---|---|
+| 定位 | 底层原语 | 内部工厂 | **唯一公开 API** |
+| 配置来源 | 纯参数 | YAML 文件 | **参数优先，config fallback** |
+| 内置能力 | 无 | Sandbox/Memory/Skills/Subagent/... | **按需组合 + 管理 API** |
+| 用户接口 | `graph.invoke(state)` | 内部使用 | **`client.chat("hello")`** |
+| 适合谁 | 写 LangChain 的人 | 内部使用 | **所有 DeerFlow 用户** |
+
+## 2. 设计原则
+
+### Python 中的 DI 最佳实践
+
+1. **函数参数即注入** — 不读全局状态，所有依赖通过参数传入
+2. **Protocol 定义契约** — 不依赖具体类，依赖行为接口
+3. **合理默认值** — `sandbox=True` 等价于 `sandbox=LocalSandboxProvider()`
+4. **分层 API** — 简单用法一行搞定，复杂用法有逃生舱
+
+### 分层架构
+
+```
+    ┌──────────────────────┐
+    │   DeerFlowClient     │  ← 唯一公开 API（chat/stream + 管理）
+    └──────────┬───────────┘
+    ┌──────────▼───────────┐
+    │   make_lead_agent    │  ← 内部：配置驱动工厂
+    └──────────┬───────────┘
+    ┌──────────▼───────────┐
+    │  create_deerflow_agent   │  ← 内部：纯参数工厂
+    └──────────┬───────────┘
+    ┌──────────▼───────────┐
+    │ langchain.create_agent│  ← 底层原语
+    └──────────────────────┘
+```
+
+`DeerFlowClient` 是唯一公开 API。`create_deerflow_agent` 和 `make_lead_agent` 都是内部实现。
+
+用户通过 `DeerFlowClient` 三个参数控制行为：
+
+| 参数 | 类型 | 职责 |
+|------|------|------|
+| `config` | `dict` | 覆盖 config.yaml 的任意配置项 |
+| `features` | `RuntimeFeatures` | 替换内置 middleware 实现 |
+| `extra_middleware` | `list[AgentMiddleware]` | 新增用户 middleware |
+
+不传参数 → 读 config.yaml（现有行为，完全兼容）。
+
+### 核心约束
+
+- **配置覆盖** — `config` dict > config.yaml > 默认值
+- **三层不重叠** — config 传参数，features 传实例，extra_middleware 传新增
+- **向前兼容** — 现有 `DeerFlowClient()` 无参构造行为不变
+- **harness 边界合规** — 不 import `app.*`（`test_harness_boundary.py` 强制）
+
+## 3. API 设计
+
+### 3.1 `DeerFlowClient` — 唯一公开 API
+
+在现有构造函数上增加三个可选参数：
+
+```python
+from deerflow.client import DeerFlowClient
+from deerflow.agents.features import RuntimeFeatures
+
+client = DeerFlowClient(
+    # 1. config — 覆盖 config.yaml 的任意 key（结构和 yaml 一致）
+    config={
+        "models": [{"name": "gpt-4o", "use": "langchain_openai:ChatOpenAI", "model": "gpt-4o", "api_key": "sk-..."}],
+        "memory": {"max_facts": 50, "enabled": True},
+        "title": {"enabled": False},
+        "summarization": {"enabled": True, "trigger": [{"type": "tokens", "value": 10000}]},
+        "sandbox": {"use": "deerflow.sandbox.local:LocalSandboxProvider"},
+    },
+
+    # 2. features — 替换内置 middleware 实现
+    features=RuntimeFeatures(
+        memory=MyMemoryMiddleware(),
+        auto_title=MyTitleMiddleware(),
+    ),
+
+    # 3. extra_middleware — 新增用户 middleware
+    extra_middleware=[
+        MyAuditMiddleware(),       # @Next(SandboxMiddleware)
+        MyFilterMiddleware(),      # @Prev(ClarificationMiddleware)
+    ],
+)
+```
+
+三种典型用法：
+
+```python
+# 用法 1：全读 config.yaml（现有行为，不变）
+client = DeerFlowClient()
+
+# 用法 2：只改参数，不换实现
+client = DeerFlowClient(config={"memory": {"max_facts": 50}})
+
+# 用法 3：替换 middleware 实现
+client = DeerFlowClient(features=RuntimeFeatures(auto_title=MyTitleMiddleware()))
+
+# 用法 4：添加自定义 middleware
+client = DeerFlowClient(extra_middleware=[MyAuditMiddleware()])
+
+# 用法 5：纯 SDK（无 config.yaml）
+client = DeerFlowClient(config={
+    "models": [{"name": "gpt-4o", "use": "langchain_openai:ChatOpenAI", ...}],
+    "tools": [{"name": "bash", "use": "deerflow.sandbox.tools:bash_tool", "group": "bash"}],
+    "memory": {"enabled": True},
+})
+```
+
+内部实现：`final_config = deep_merge(file_config, code_config)`
+
+### 3.2 `create_deerflow_agent` — 内部工厂（不公开）
+
+```python
+def create_deerflow_agent(
+    model: BaseChatModel,
+    tools: list[BaseTool] | None = None,
+    *,
+    system_prompt: str | None = None,
+    middleware: list[AgentMiddleware] | None = None,
+    features: RuntimeFeatures | None = None,
+    state_schema: type | None = None,
+    checkpointer: BaseCheckpointSaver | None = None,
+    name: str = "default",
+) -> CompiledStateGraph:
+    ...
+```
+
+`DeerFlowClient` 内部调用此函数。
+
+### 3.3 `RuntimeFeatures` — 内置 Middleware 替换
+
+只做一件事：用自定义实例替换内置 middleware。不管配置参数（参数走 `config` dict）。
+
+```python
+@dataclass
+class RuntimeFeatures:
+    sandbox: bool | AgentMiddleware = True
+    memory: bool | AgentMiddleware = False
+    summarization: bool | AgentMiddleware = False
+    subagent: bool | AgentMiddleware = False
+    vision: bool | AgentMiddleware = False
+    auto_title: bool | AgentMiddleware = False
+```
+
+| 值 | 含义 |
+|---|---|
+| `True` | 使用默认 middleware（参数从 config 读） |
+| `False` | 关闭该功能 |
+| `AgentMiddleware` 实例 | 替换整个实现 |
+
+不再有 `MemoryOptions`、`TitleOptions` 等。参数调整走 `config` dict：
+
+```python
+# 改 memory 参数 → config
+client = DeerFlowClient(config={"memory": {"max_facts": 50}})
+
+# 换 memory 实现 → features
+client = DeerFlowClient(features=RuntimeFeatures(memory=MyMemoryMiddleware()))
+
+# 两者组合 — config 参数给默认 middleware，但 title 换实现
+client = DeerFlowClient(
+    config={"memory": {"max_facts": 50}},
+    features=RuntimeFeatures(auto_title=MyTitleMiddleware()),
+)
+```
+
+### 3.4 Middleware 链组装
+
+不使用 priority 数字排序。按固定顺序 append 构建列表：
+
+```python
+def _resolve(spec, default_cls):
+    """bool → 默认实现 / AgentMiddleware → 替换"""
+    if isinstance(spec, AgentMiddleware):
+        return spec
+    return default_cls()
+
+def _assemble_from_features(feat: RuntimeFeatures, config: AppConfig) -> tuple[list, list]:
+    chain = []
+    extra_tools = []
+
+    if feat.sandbox:
+        chain.append(_resolve(feat.sandbox, ThreadDataMiddleware))
+        chain.append(UploadsMiddleware())
+        chain.append(_resolve(feat.sandbox, SandboxMiddleware))
+
+    chain.append(DanglingToolCallMiddleware())
+    chain.append(ToolErrorHandlingMiddleware())
+
+    if feat.summarization:
+        chain.append(_resolve(feat.summarization, SummarizationMiddleware))
+    if config.title.enabled and feat.auto_title is not False:
+        chain.append(_resolve(feat.auto_title, TitleMiddleware))
+    if feat.memory:
+        chain.append(_resolve(feat.memory, MemoryMiddleware))
+    if feat.vision:
+        chain.append(ViewImageMiddleware())
+        extra_tools.append(view_image_tool)
+    if feat.subagent:
+        chain.append(_resolve(feat.subagent, SubagentLimitMiddleware))
+        extra_tools.append(task_tool)
+    if feat.loop_detection:
+        chain.append(_resolve(feat.loop_detection, LoopDetectionMiddleware))
+
+    # 插入 extra_middleware（按 @Next/@Prev 声明定位）
+    _insert_extra(chain, extra_middleware)
+
+    # Clarification 永远最后
+    chain.append(ClarificationMiddleware())
+    extra_tools.append(ask_clarification_tool)
+
+    return chain, extra_tools
+```
+
+### 3.6 Middleware 排序策略
+
+**两阶段排序：内置固定 + 外置插入**
+
+1. **内置链固定顺序** — 按代码中的 append 顺序确定，不参与 @Next/@Prev
+2. **外置 middleware 插入** — `extra_middleware` 中的 middleware 通过 @Next/@Prev 声明锚点，自由锚定任意 middleware（内置或其他外置均可）
+3. **冲突检测** — 两个外置 middleware 如果 @Next 或 @Prev 同一个目标 → `ValueError`
+
+**这不是全排序。** 内置链的顺序在代码中已确定，外置 middleware 只做插入操作。这样可以避免内置和外置同时竞争同一个位置的问题。
+
+### 3.7 `@Next` / `@Prev` 装饰器
+
+用户自定义 middleware 通过装饰器声明在链中的位置，类型安全：
+
+```python
+from deerflow.agents import Next, Prev
+
+@Next(SandboxMiddleware)
+class MyAuditMiddleware(AgentMiddleware):
+    """排在 SandboxMiddleware 后面"""
+    def before_agent(self, state, runtime):
+        ...
+
+@Prev(ClarificationMiddleware)
+class MyFilterMiddleware(AgentMiddleware):
+    """排在 ClarificationMiddleware 前面"""
+    def after_model(self, state, runtime):
+        ...
+```
+
+实现：
+
+```python
+def Next(anchor: type[AgentMiddleware]):
+    """装饰器：声明本 middleware 排在 anchor 的下一个位置。"""
+    def decorator(cls: type[AgentMiddleware]) -> type[AgentMiddleware]:
+        cls._next_anchor = anchor
+        return cls
+    return decorator
+
+def Prev(anchor: type[AgentMiddleware]):
+    """装饰器：声明本 middleware 排在 anchor 的前一个位置。"""
+    def decorator(cls: type[AgentMiddleware]) -> type[AgentMiddleware]:
+        cls._prev_anchor = anchor
+        return cls
+    return decorator
+```
+
+`_insert_extra` 算法：
+
+1. 遍历 `extra_middleware`，读取每个 middleware 的 `_next_anchor` / `_prev_anchor`
+2. **冲突检测**：如果两个外置 middleware 的锚点相同（同方向同目标），抛出 `ValueError`
+3. 有锚点的 middleware 插入到目标位置（@Next → 目标之后，@Prev → 目标之前）
+4. 无声明的 middleware 追加到 Clarification 之前
+
+## 4. Middleware 执行模型
+
+### LangChain 的执行规则
+
+```
+before_agent 正序 →  [0] → [1] → ... → [N]
+before_model 正序 →  [0] → [1] → ... → [N]  ← 每轮循环
+         MODEL
+after_model 反序 ←   [N] → [N-1] → ... → [0]  ← 每轮循环
+after_agent 反序 ←   [N] → [N-1] → ... → [0]
+```
+
+`before_agent` / `after_agent` 只跑一次。`before_model` / `after_model` 每轮 tool call 循环都跑。
+
+### DeerFlow 的实际情况
+
+**不是洋葱，是管道。** 11 个 middleware 中只有 SandboxMiddleware 有 before/after 对称（获取/释放），其余只用一个钩子。
+
+硬依赖只有 2 处：
+1. **ThreadData 在 Sandbox 之前** — sandbox 需要线程目录
+2. **Clarification 在列表最后** — after_model 反序时最先执行，第一个拦截 `ask_clarification`
+
+详见 [middleware-execution-flow.md](middleware-execution-flow.md)。
+
+## 5. 使用示例
+
+### 5.1 全读 config.yaml（现有行为不变）
+
+```python
+from deerflow.client import DeerFlowClient
+
+client = DeerFlowClient()
+response = client.chat("Hello")
+```
+
+### 5.2 覆盖配置参数
+
+```python
+client = DeerFlowClient(config={
+    "memory": {"max_facts": 50},
+    "title": {"enabled": False},
+    "summarization": {"trigger": [{"type": "tokens", "value": 10000}]},
+})
+```
+
+### 5.3 纯 SDK（无 config.yaml）
+
+```python
+client = DeerFlowClient(config={
+    "models": [{"name": "gpt-4o", "use": "langchain_openai:ChatOpenAI", "model": "gpt-4o", "api_key": "sk-..."}],
+    "tools": [
+        {"name": "bash", "group": "bash", "use": "deerflow.sandbox.tools:bash_tool"},
+        {"name": "web_search", "group": "web", "use": "deerflow.community.tavily.tools:web_search_tool"},
+    ],
+    "memory": {"enabled": True, "max_facts": 50},
+    "sandbox": {"use": "deerflow.sandbox.local:LocalSandboxProvider"},
+})
+```
+
+### 5.4 替换内置 middleware
+
+```python
+from deerflow.agents.features import RuntimeFeatures
+
+client = DeerFlowClient(
+    features=RuntimeFeatures(
+        memory=MyMemoryMiddleware(),       # 替换
+        auto_title=MyTitleMiddleware(),    # 替换
+        vision=False,                      # 关闭
+    ),
+)
+```
+
+### 5.5 插入自定义 middleware
+
+```python
+from deerflow.agents import Next, Prev
+from deerflow.sandbox.middleware import SandboxMiddleware
+from deerflow.agents.middlewares.clarification_middleware import ClarificationMiddleware
+
+@Next(SandboxMiddleware)
+class MyAuditMiddleware(AgentMiddleware):
+    def before_agent(self, state, runtime):
+        log_sandbox_acquired(state)
+
+@Prev(ClarificationMiddleware)
+class MyFilterMiddleware(AgentMiddleware):
+    def after_model(self, state, runtime):
+        filter_sensitive_output(state)
+
+client = DeerFlowClient(
+    extra_middleware=[MyAuditMiddleware(), MyFilterMiddleware()],
+)
+```
+
+## 6. Phase 1 限制
+
+当前实现中以下 middleware 内部仍读 `config.yaml`，SDK 用户需注意：
+
+| Middleware | 读取内容 | Phase 2 解决方案 |
+|------------|---------|-----------------|
+| TitleMiddleware | `get_title_config()` + `create_chat_model()` | `TitleOptions(model=...)` 参数覆盖 |
+| MemoryMiddleware | `get_memory_config()` | `MemoryOptions(...)` 参数覆盖 |
+| SandboxMiddleware | `get_sandbox_provider()` | `SandboxProvider` 实例直传 |
+
+Phase 1 中 `auto_title` 默认为 `False` 以避免无 config 时崩溃。其他有 config 依赖的 feature 默认也为 `False`。
+
+## 7. 迁移路径
+
+```
+Phase 1（当前 PR #1203）:
+  ✓ 新增 create_deerflow_agent + RuntimeFeatures（内部 API）
+  ✓ 不改 DeerFlowClient 和 make_lead_agent
+  ✗ middleware 内部仍读 config（已知限制）
+
+Phase 2（#1380）:
+  - DeerFlowClient 构造函数增加可选参数（model, tools, features, system_prompt）
+  - Options 参数覆盖 config（MemoryOptions, TitleOptions 等）
+  - @Next/@Prev 装饰器
+  - 补缺失 middleware（Guardrail, TokenUsage, DeferredToolFilter）
+  - make_lead_agent 改为薄壳调 create_deerflow_agent
+
+Phase 3:
+  - SDK 文档和示例
+  - deerflow.client 稳定 API
+```
+
+## 8. 设计决议
+
+| 问题 | 决议 | 理由 |
+|------|------|------|
+| 公开 API | `DeerFlowClient` 唯一入口 | 自顶向下，先改现有 API 再抽底层 |
+| create_deerflow_agent | 内部实现，不公开 | 用户不需要接触 CompiledStateGraph |
+| 配置覆盖 | `config` dict，和 config.yaml 结构一致 | 无新概念，deep merge 覆盖 |
+| middleware 替换 | `features=RuntimeFeatures(memory=MyMW())` | bool 开关 + 实例替换 |
+| middleware 扩展 | `extra_middleware` 独立参数 | 和内置 features 分开 |
+| middleware 定位 | `@Next/@Prev` 装饰器 | 类型安全，不暴露排序细节 |
+| 排序机制 | 顺序 append + @Next/@Prev | priority 数字无功能意义 |
+| 运行时开关 | 保留 `RunnableConfig` | plan_mode、thread_id 等按请求切换 |
+
+## 9. 附录：Middleware 链
+
+```mermaid
+graph TB
+    subgraph BA ["before_agent 正序"]
+        direction TB
+        TD["ThreadData<br/>创建目录"] --> UL["Uploads<br/>扫描文件"] --> SB["Sandbox<br/>获取沙箱"]
+    end
+
+    subgraph BM ["before_model 正序 每轮"]
+        direction TB
+        VI["ViewImage<br/>注入图片"]
+    end
+
+    SB --> VI
+    VI --> M["MODEL"]
+
+    subgraph AM ["after_model 反序 每轮"]
+        direction TB
+        CL["Clarification<br/>拦截中断"] --> LD["LoopDetection<br/>检测循环"] --> SL["SubagentLimit<br/>截断 task"] --> TI["Title<br/>生成标题"] --> DTC["DanglingToolCall<br/>补缺失消息"]
+    end
+
+    M --> CL
+
+    subgraph AA ["after_agent 反序"]
+        direction TB
+        SBR["Sandbox<br/>释放沙箱"] --> MEM["Memory<br/>入队记忆"]
+    end
+
+    DTC --> SBR
+
+    classDef beforeNode fill:#a0a8b5,stroke:#636b7a,color:#2d3239
+    classDef modelNode fill:#b5a8a0,stroke:#7a6b63,color:#2d3239
+    classDef afterModelNode fill:#b5a0a8,stroke:#7a636b,color:#2d3239
+    classDef afterAgentNode fill:#a0b5a8,stroke:#637a6b,color:#2d3239
+
+    class TD,UL,SB,VI beforeNode
+    class M modelNode
+    class CL,LD,SL,TI,DTC afterModelNode
+    class SBR,MEM afterAgentNode
+```
+
+硬依赖：
+- ThreadData → Uploads → Sandbox（before_agent 阶段）
+- Clarification 必须在列表最后（after_model 反序时最先执行）
+
+## 10. 主 Agent 与 Subagent 的 Middleware 差异
+
+主 agent 和 subagent 共享基础 middleware 链（`_build_runtime_middlewares`），subagent 在此基础上做精简：
+
+| Middleware | 主 Agent | Subagent | 说明 |
+|------------|:-------:|:--------:|------|
+| ThreadDataMiddleware | ✓ | ✓ | 共享：创建线程目录 |
+| UploadsMiddleware | ✓ | ✗ | 主 agent 独有：扫描上传文件 |
+| SandboxMiddleware | ✓ | ✓ | 共享：获取/释放沙箱 |
+| DanglingToolCallMiddleware | ✓ | ✗ | 主 agent 独有：补缺失 ToolMessage |
+| GuardrailMiddleware | ✓ | ✓ | 共享：工具调用授权（可选） |
+| ToolErrorHandlingMiddleware | ✓ | ✓ | 共享：工具异常处理 |
+| SummarizationMiddleware | ✓ | ✗ | |
+| TodoMiddleware | ✓ | ✗ | |
+| TitleMiddleware | ✓ | ✗ | |
+| MemoryMiddleware | ✓ | ✗ | |
+| ViewImageMiddleware | ✓ | ✗ | |
+| SubagentLimitMiddleware | ✓ | ✗ | |
+| LoopDetectionMiddleware | ✓ | ✗ | |
+| ClarificationMiddleware | ✓ | ✗ | |
+
+**设计原则**：
+- `RuntimeFeatures`、`@Next/@Prev`、排序机制只作用于**主 agent**
+- Subagent 链短且固定（4 个），不需要动态组装
+- `extra_middleware` 当前只影响主 agent，不传递给 subagent

offline-backend-20260512/backend/docs/rfc-extract-shared-modules.md

@@ -0,0 +1,190 @@
+# RFC: Extract Shared Skill Installer and Upload Manager into Harness
+
+## 1. Problem
+
+Gateway (`app/gateway/routers/skills.py`, `uploads.py`) and Client (`deerflow/client.py`) each independently implement the same business logic:
+
+### Skill Installation
+
+| Logic | Gateway (`skills.py`) | Client (`client.py`) |
+|-------|----------------------|---------------------|
+| Zip safety check | `_is_unsafe_zip_member()` | Inline `Path(info.filename).is_absolute()` |
+| Symlink filtering | `_is_symlink_member()` | `p.is_symlink()` post-extraction delete |
+| Zip bomb defence | `total_size += info.file_size` (declared) | `total_size > 100MB` (declared) |
+| macOS metadata filter | `_should_ignore_archive_entry()` | None |
+| Frontmatter validation | `_validate_skill_frontmatter()` | `_validate_skill_frontmatter()` |
+| Duplicate detection | `HTTPException(409)` | `ValueError` |
+
+**Two implementations, inconsistent behaviour**: Gateway streams writes and tracks real decompressed size; Client sums declared `file_size`. Gateway skips symlinks during extraction; Client extracts everything then walks and deletes symlinks.
+
+### Upload Management
+
+| Logic | Gateway (`uploads.py`) | Client (`client.py`) |
+|-------|----------------------|---------------------|
+| Directory access | `get_uploads_dir()` + `mkdir` | `_get_uploads_dir()` + `mkdir` |
+| Filename safety | Inline `Path(f).name` + manual checks | No checks, uses `src_path.name` directly |
+| Duplicate handling | None (overwrites) | None (overwrites) |
+| Listing | Inline `iterdir()` | Inline `os.scandir()` |
+| Deletion | Inline `unlink()` + traversal check | Inline `unlink()` + traversal check |
+| Path traversal | `resolve().relative_to()` | `resolve().relative_to()` |
+
+**The same traversal check is written twice** — any security fix must be applied to both locations.
+
+## 2. Design Principles
+
+### Dependency Direction
+
+```
+app.gateway.routers.skills  ──┐
+app.gateway.routers.uploads ──┤── calls ──→  deerflow.skills.installer
+deerflow.client             ──┘              deerflow.uploads.manager
+```
+
+- Shared modules live in the harness layer (`deerflow.*`), pure business logic, no FastAPI dependency
+- Gateway handles HTTP adaptation (`UploadFile` → bytes, exceptions → `HTTPException`)
+- Client handles local adaptation (`Path` → copy, exceptions → Python exceptions)
+- Satisfies `test_harness_boundary.py` constraint: harness never imports app
+
+### Exception Strategy
+
+| Shared Layer Exception | Gateway Maps To | Client |
+|----------------------|-----------------|--------|
+| `FileNotFoundError` | `HTTPException(404)` | Propagates |
+| `ValueError` | `HTTPException(400)` | Propagates |
+| `SkillAlreadyExistsError` | `HTTPException(409)` | Propagates |
+| `PermissionError` | `HTTPException(403)` | Propagates |
+
+Replaces stringly-typed routing (`"already exists" in str(e)`) with typed exception matching (`SkillAlreadyExistsError`).
+
+## 3. New Modules
+
+### 3.1 `deerflow.skills.installer`
+
+```python
+# Safety checks
+is_unsafe_zip_member(info: ZipInfo) -> bool     # Absolute path / .. traversal
+is_symlink_member(info: ZipInfo) -> bool         # Unix symlink detection
+should_ignore_archive_entry(path: Path) -> bool  # __MACOSX / dotfiles
+
+# Extraction
+safe_extract_skill_archive(zip_ref, dest_path, max_total_size=512MB)
+  # Streaming write, accumulates real bytes (vs declared file_size)
+  # Dual traversal check: member-level + resolve-level
+
+# Directory resolution
+resolve_skill_dir_from_archive(temp_path: Path) -> Path
+  # Auto-enters single directory, filters macOS metadata
+
+# Install entry point
+install_skill_from_archive(zip_path, *, skills_root=None) -> dict
+  # is_file() pre-check before extension validation
+  # SkillAlreadyExistsError replaces ValueError
+
+# Exception
+class SkillAlreadyExistsError(ValueError)
+```
+
+### 3.2 `deerflow.uploads.manager`
+
+```python
+# Directory management
+get_uploads_dir(thread_id: str) -> Path      # Pure path, no side effects
+ensure_uploads_dir(thread_id: str) -> Path   # Creates directory (for write paths)
+
+# Filename safety
+normalize_filename(filename: str) -> str
+  # Path.name extraction + rejects ".." / "." / backslash / >255 bytes
+deduplicate_filename(name: str, seen: set) -> str
+  # _N suffix increment for dedup, mutates seen in place
+
+# Path safety
+validate_path_traversal(path: Path, base: Path) -> None
+  # resolve().relative_to(), raises PermissionError on failure
+
+# File operations
+list_files_in_dir(directory: Path) -> dict
+  # scandir with stat inside context (no re-stat)
+  # follow_symlinks=False to prevent metadata leakage
+  # Non-existent directory returns empty list
+delete_file_safe(base_dir: Path, filename: str) -> dict
+  # Validates traversal first, then unlinks
+
+# URL helpers
+upload_artifact_url(thread_id, filename) -> str   # Percent-encoded for HTTP safety
+upload_virtual_path(filename) -> str               # Sandbox-internal path
+enrich_file_listing(result, thread_id) -> dict     # Adds URLs, stringifies sizes
+```
+
+## 4. Changes
+
+### 4.1 Gateway Slimming
+
+**`app/gateway/routers/skills.py`**:
+- Remove `_is_unsafe_zip_member`, `_is_symlink_member`, `_safe_extract_skill_archive`, `_should_ignore_archive_entry`, `_resolve_skill_dir_from_archive_root` (~80 lines)
+- `install_skill` route becomes a single call to `install_skill_from_archive(path)`
+- Exception mapping: `SkillAlreadyExistsError → 409`, `ValueError → 400`, `FileNotFoundError → 404`
+
+**`app/gateway/routers/uploads.py`**:
+- Remove inline `get_uploads_dir` (replaced by `ensure_uploads_dir`/`get_uploads_dir`)
+- `upload_files` uses `normalize_filename()` instead of inline safety checks
+- `list_uploaded_files` uses `list_files_in_dir()` + enrichment
+- `delete_uploaded_file` uses `delete_file_safe()` + companion markdown cleanup
+
+### 4.2 Client Slimming
+
+**`deerflow/client.py`**:
+- Remove `_get_uploads_dir` static method
+- Remove ~50 lines of inline zip handling in `install_skill`
+- `install_skill` delegates to `install_skill_from_archive()`
+- `upload_files` uses `deduplicate_filename()` + `ensure_uploads_dir()`
+- `list_uploads` uses `get_uploads_dir()` + `list_files_in_dir()`
+- `delete_upload` uses `get_uploads_dir()` + `delete_file_safe()`
+- `update_mcp_config` / `update_skill` now reset `_agent_config_key = None`
+
+### 4.3 Read/Write Path Separation
+
+| Operation | Function | Creates dir? |
+|-----------|----------|:------------:|
+| upload (write) | `ensure_uploads_dir()` | Yes |
+| list (read) | `get_uploads_dir()` | No |
+| delete (read) | `get_uploads_dir()` | No |
+
+Read paths no longer have `mkdir` side effects — non-existent directories return empty lists.
+
+## 5. Security Improvements
+
+| Improvement | Before | After |
+|-------------|--------|-------|
+| Zip bomb detection | Sum of declared `file_size` | Streaming write, accumulates real bytes |
+| Symlink handling | Gateway skips / Client deletes post-extract | Unified skip + log |
+| Traversal check | Member-level only | Member-level + `resolve().is_relative_to()` |
+| Filename backslash | Gateway checks / Client doesn't | Unified rejection |
+| Filename length | No check | Reject > 255 bytes (OS limit) |
+| thread_id validation | None | Reject unsafe filesystem characters |
+| Listing symlink leak | `follow_symlinks=True` (default) | `follow_symlinks=False` |
+| 409 status routing | `"already exists" in str(e)` | `SkillAlreadyExistsError` type match |
+| Artifact URL encoding | Raw filename in URL | `urllib.parse.quote()` |
+
+## 6. Alternatives Considered
+
+| Alternative | Why Not |
+|-------------|---------|
+| Keep logic in Gateway, Client calls Gateway via HTTP | Adds network dependency to embedded Client; defeats the purpose of `DeerFlowClient` as an in-process API |
+| Abstract base class with Gateway/Client subclasses | Over-engineered for what are pure functions; no polymorphism needed |
+| Move everything into `client.py` and have Gateway import it | Violates harness/app boundary — Client is in harness, but Gateway-specific models (Pydantic response types) should stay in app layer |
+| Merge Gateway and Client into one module | They serve different consumers (HTTP vs in-process) with different adaptation needs |
+
+## 7. Breaking Changes
+
+**None.** All public APIs (Gateway HTTP endpoints, `DeerFlowClient` methods) retain their existing signatures and return formats. The `SkillAlreadyExistsError` is a subclass of `ValueError`, so existing `except ValueError` handlers still catch it.
+
+## 8. Tests
+
+| Module | Test File | Count |
+|--------|-----------|:-----:|
+| `skills.installer` | `tests/test_skills_installer.py` | 22 |
+| `uploads.manager` | `tests/test_uploads_manager.py` | 20 |
+| `client` hardening | `tests/test_client.py` (new cases) | ~40 |
+| `client` e2e | `tests/test_client_e2e.py` (new file) | ~20 |
+
+Coverage: unsafe zip / symlink / zip bomb / frontmatter / duplicate / extension / macOS filter / normalize / deduplicate / traversal / list / delete / agent invalidation / upload lifecycle / thread isolation / URL encoding / config pollution.

offline-backend-20260512/backend/docs/rfc-grep-glob-tools.md

@@ -0,0 +1,446 @@
+# [RFC] 在 DeerFlow 中增加 `grep` 与 `glob` 文件搜索工具
+
+## Summary
+
+我认为这个方向是对的，而且值得做。
+
+如果 DeerFlow 想更接近 Claude Code 这类 coding agent 的实际工作流，仅有 `ls` / `read_file` / `write_file` / `str_replace` 还不够。模型在进入修改前，通常还需要两类能力：
+
+- `glob`: 快速按路径模式找文件
+- `grep`: 快速按内容模式找候选位置
+
+这两类工具的价值，不是“功能上 bash 也能做”，而是它们能以更低 token 成本、更强约束、更稳定的输出格式，替代模型频繁走 `bash find` / `bash grep` / `rg` 的习惯。
+
+但前提是实现方式要对：**它们应该是只读、结构化、受限、可审计的原生工具，而不是对 shell 命令的简单包装。**
+
+## Problem
+
+当前 DeerFlow 的文件工具层主要覆盖：
+
+- `ls`: 浏览目录结构
+- `read_file`: 读取文件内容
+- `write_file`: 写文件
+- `str_replace`: 做局部字符串替换
+- `bash`: 兜底执行命令
+
+这套能力能完成任务，但在代码库探索阶段效率不高。
+
+典型问题：
+
+1. 模型想找 “所有 `*.tsx` 的 page 文件” 时，只能反复 `ls` 多层目录，或者退回 `bash find`
+2. 模型想找 “某个 symbol / 文案 / 配置键在哪里出现” 时，只能逐文件 `read_file`，或者退回 `bash grep` / `rg`
+3. 一旦退回 `bash`，工具调用就失去结构化输出，结果也更难做裁剪、分页、审计和跨 sandbox 一致化
+4. 对没有开启 host bash 的本地模式，`bash` 甚至可能不可用，此时缺少足够强的只读检索能力
+
+结论：DeerFlow 现在缺的不是“再多一个 shell 命令”，而是**文件系统检索层**。
+
+## Goals
+
+- 为 agent 提供稳定的路径搜索和内容搜索能力
+- 减少对 `bash` 的依赖，特别是在仓库探索阶段
+- 保持与现有 sandbox 安全模型一致
+- 输出格式结构化，便于模型后续串联 `read_file` / `str_replace`
+- 让本地 sandbox、容器 sandbox、未来 MCP 文件系统工具都能遵守同一语义
+
+## Non-Goals
+
+- 不做通用 shell 兼容层
+- 不暴露完整 grep/find/rg CLI 语法
+- 不在第一版支持二进制检索、复杂 PCRE 特性、上下文窗口高亮渲染等重功能
+- 不把它做成“任意磁盘搜索”，仍然只允许在 DeerFlow 已授权的路径内执行
+
+## Why This Is Worth Doing
+
+参考 Claude Code 这一类 agent 的设计思路，`glob` 和 `grep` 的核心价值不是新能力本身，而是把“探索代码库”的常见动作从开放式 shell 降到受控工具层。
+
+这样有几个直接收益：
+
+1. **更低的模型负担**
+   模型不需要自己拼 `find`, `grep`, `rg`, `xargs`, quoting 等命令细节。
+
+2. **更稳定的跨环境行为**
+   本地、Docker、AIO sandbox 不必依赖容器里是否装了 `rg`，也不会因为 shell 差异导致行为漂移。
+
+3. **更强的安全与审计**
+   调用参数就是“搜索什么、在哪搜、最多返回多少”，天然比任意命令更容易审计和限流。
+
+4. **更好的 token 效率**
+   `grep` 返回的是命中摘要而不是整段文件，模型只对少数候选路径再调用 `read_file`。
+
+5. **对 `tool_search` 友好**
+   当 DeerFlow 持续扩展工具集时，`grep` / `glob` 会成为非常高频的基础工具，值得保留为 built-in，而不是让模型总是退回通用 bash。
+
+## Proposal
+
+增加两个 built-in sandbox tools：
+
+- `glob`
+- `grep`
+
+推荐继续放在：
+
+- `backend/packages/harness/deerflow/sandbox/tools.py`
+
+并在 `config.example.yaml` 中默认加入 `file:read` 组。
+
+### 1. `glob` 工具
+
+用途：按路径模式查找文件或目录。
+
+建议 schema：
+
+```python
+@tool("glob", parse_docstring=True)
+def glob_tool(
+    runtime: ToolRuntime[ContextT, ThreadState],
+    description: str,
+    pattern: str,
+    path: str,
+    include_dirs: bool = False,
+    max_results: int = 200,
+) -> str:
+    ...
+```
+
+参数语义：
+
+- `description`: 与现有工具保持一致
+- `pattern`: glob 模式，例如 `**/*.py`、`src/**/test_*.ts`
+- `path`: 搜索根目录，必须是绝对路径
+- `include_dirs`: 是否返回目录
+- `max_results`: 最大返回条数，防止一次性打爆上下文
+
+建议返回格式：
+
+```text
+Found 3 paths under /mnt/user-data/workspace
+1. /mnt/user-data/workspace/backend/app.py
+2. /mnt/user-data/workspace/backend/tests/test_app.py
+3. /mnt/user-data/workspace/scripts/build.py
+```
+
+如果后续想更适合前端消费，也可以改成 JSON 字符串；但第一版为了兼容现有工具风格，返回可读文本即可。
+
+### 2. `grep` 工具
+
+用途：按内容模式搜索文件，返回命中位置摘要。
+
+建议 schema：
+
+```python
+@tool("grep", parse_docstring=True)
+def grep_tool(
+    runtime: ToolRuntime[ContextT, ThreadState],
+    description: str,
+    pattern: str,
+    path: str,
+    glob: str | None = None,
+    literal: bool = False,
+    case_sensitive: bool = False,
+    max_results: int = 100,
+) -> str:
+    ...
+```
+
+参数语义：
+
+- `pattern`: 搜索词或正则
+- `path`: 搜索根目录，必须是绝对路径
+- `glob`: 可选路径过滤，例如 `**/*.py`
+- `literal`: 为 `True` 时按普通字符串匹配，不解释为正则
+- `case_sensitive`: 是否大小写敏感
+- `max_results`: 最大返回命中数，不是文件数
+
+建议返回格式：
+
+```text
+Found 4 matches under /mnt/user-data/workspace
+/mnt/user-data/workspace/backend/config.py:12: TOOL_GROUPS = [...]
+/mnt/user-data/workspace/backend/config.py:48: def load_tool_config(...):
+/mnt/user-data/workspace/backend/tools.py:91: "tool_groups"
+/mnt/user-data/workspace/backend/tests/test_config.py:22: assert "tool_groups" in data
+```
+
+第一版建议只返回：
+
+- 文件路径
+- 行号
+- 命中行摘要
+
+不返回上下文块，避免结果过大。模型如果需要上下文，再调用 `read_file(path, start_line, end_line)`。
+
+## Design Principles
+
+### A. 不做 shell wrapper
+
+不建议把 `grep` 实现为：
+
+```python
+subprocess.run("grep ...")
+```
+
+也不建议在容器里直接拼 `find` / `rg` 命令。
+
+原因：
+
+- 会引入 shell quoting 和注入面
+- 会依赖不同 sandbox 内镜像是否安装同一套命令
+- Windows / macOS / Linux 行为不一致
+- 很难稳定控制输出条数与格式
+
+正确方向是：
+
+- `glob` 使用 Python 标准库路径遍历
+- `grep` 使用 Python 逐文件扫描
+- 输出由 DeerFlow 自己格式化
+
+如果未来为了性能考虑要优先调用 `rg`，也应该封装在 provider 内部，并保证外部语义不变，而不是把 CLI 暴露给模型。
+
+### B. 继续沿用 DeerFlow 的路径权限模型
+
+这两个工具必须复用当前 `ls` / `read_file` 的路径校验逻辑：
+
+- 本地模式走 `validate_local_tool_path(..., read_only=True)`
+- 支持 `/mnt/skills/...`
+- 支持 `/mnt/acp-workspace/...`
+- 支持 thread workspace / uploads / outputs 的虚拟路径解析
+- 明确拒绝越权路径与 path traversal
+
+也就是说，它们属于 **file:read**，不是 `bash` 的替代越权入口。
+
+### C. 结果必须硬限制
+
+没有硬限制的 `glob` / `grep` 很容易炸上下文。
+
+建议第一版至少限制：
+
+- `glob.max_results` 默认 200，最大 1000
+- `grep.max_results` 默认 100，最大 500
+- 单行摘要最大长度，例如 200 字符
+- 二进制文件跳过
+- 超大文件跳过，例如单文件大于 1 MB 或按配置控制
+
+此外，命中数超过阈值时应返回：
+
+- 已展示的条数
+- 被截断的事实
+- 建议用户缩小搜索范围
+
+例如：
+
+```text
+Found more than 100 matches, showing first 100. Narrow the path or add a glob filter.
+```
+
+### D. 工具语义要彼此互补
+
+推荐模型工作流应该是：
+
+1. `glob` 找候选文件
+2. `grep` 找候选位置
+3. `read_file` 读局部上下文
+4. `str_replace` / `write_file` 执行修改
+
+这样工具边界清晰，也更利于 prompt 中教模型形成稳定习惯。
+
+## Implementation Approach
+
+## Option A: 直接在 `sandbox/tools.py` 实现第一版
+
+这是我推荐的起步方案。
+
+做法：
+
+- 在 `sandbox/tools.py` 新增 `glob_tool` 与 `grep_tool`
+- 在 local sandbox 场景直接使用 Python 文件系统 API
+- 在非 local sandbox 场景，优先也通过 DeerFlow 自己控制的路径访问层实现
+
+优点：
+
+- 改动小
+- 能尽快验证 agent 效果
+- 不需要先改 `Sandbox` 抽象
+
+缺点：
+
+- `tools.py` 会继续变胖
+- 如果未来想在 provider 侧做性能优化，需要再抽象一次
+
+## Option B: 先扩展 `Sandbox` 抽象
+
+例如新增：
+
+```python
+class Sandbox(ABC):
+    def glob(self, path: str, pattern: str, include_dirs: bool = False, max_results: int = 200) -> list[str]:
+        ...
+
+    def grep(
+        self,
+        path: str,
+        pattern: str,
+        *,
+        glob: str | None = None,
+        literal: bool = False,
+        case_sensitive: bool = False,
+        max_results: int = 100,
+    ) -> list[GrepMatch]:
+        ...
+```
+
+优点：
+
+- 抽象更干净
+- 容器 / 远程 sandbox 可以各自优化
+
+缺点：
+
+- 首次引入成本更高
+- 需要同步改所有 sandbox provider
+
+结论：
+
+**第一版建议走 Option A，等工具价值验证后再下沉到 `Sandbox` 抽象层。**
+
+## Detailed Behavior
+
+### `glob` 行为
+
+- 输入根目录不存在：返回清晰错误
+- 根路径不是目录：返回清晰错误
+- 模式非法：返回清晰错误
+- 结果为空：返回 `No files matched`
+- 默认忽略项应尽量与当前 `list_dir` 对齐，例如：
+  - `.git`
+  - `node_modules`
+  - `__pycache__`
+  - `.venv`
+  - 构建产物目录
+
+这里建议抽一个共享 ignore 集，避免 `ls` 与 `glob` 结果风格不一致。
+
+### `grep` 行为
+
+- 默认只扫描文本文件
+- 检测到二进制文件直接跳过
+- 对超大文件直接跳过或只扫前 N KB
+- regex 编译失败时返回参数错误
+- 输出中的路径继续使用虚拟路径，而不是暴露宿主真实路径
+- 建议默认按文件路径、行号排序，保持稳定输出
+
+## Prompting Guidance
+
+如果引入这两个工具，建议同步更新系统提示中的文件操作建议：
+
+- 查找文件名模式时优先用 `glob`
+- 查找代码符号、配置项、文案时优先用 `grep`
+- 只有在工具不足以完成目标时才退回 `bash`
+
+否则模型仍会习惯性先调用 `bash`。
+
+## Risks
+
+### 1. 与 `bash` 能力重叠
+
+这是事实，但不是问题。
+
+`ls` 和 `read_file` 也都能被 `bash` 替代，但我们仍然保留它们，因为结构化工具更适合 agent。
+
+### 2. 性能问题
+
+在大仓库上，纯 Python `grep` 可能比 `rg` 慢。
+
+缓解方式：
+
+- 第一版先加结果上限和文件大小上限
+- 路径上强制要求 root path
+- 提供 `glob` 过滤缩小扫描范围
+- 后续如有必要，在 provider 内部做 `rg` 优化，但保持同一 schema
+
+### 3. 忽略规则不一致
+
+如果 `ls` 能看到的路径，`glob` 却看不到，模型会困惑。
+
+缓解方式：
+
+- 统一 ignore 规则
+- 在文档里明确“默认跳过常见依赖和构建目录”
+
+### 4. 正则搜索过于复杂
+
+如果第一版就支持大量 grep 方言，边界会很乱。
+
+缓解方式：
+
+- 第一版只支持 Python `re`
+- 并提供 `literal=True` 的简单模式
+
+## Alternatives Considered
+
+### A. 不增加工具，完全依赖 `bash`
+
+不推荐。
+
+这会让 DeerFlow 在代码探索体验上持续落后，也削弱无 bash 或受限 bash 场景下的能力。
+
+### B. 只加 `glob`，不加 `grep`
+
+不推荐。
+
+只解决“找文件”，没有解决“找位置”。模型最终还是会退回 `bash grep`。
+
+### C. 只加 `grep`，不加 `glob`
+
+也不推荐。
+
+`grep` 缺少路径模式过滤时，扫描范围经常太大；`glob` 是它的天然前置工具。
+
+### D. 直接接入 MCP filesystem server 的搜索能力
+
+短期不推荐作为主路径。
+
+MCP 可以是补充，但 `glob` / `grep` 作为 DeerFlow 的基础 coding tool，最好仍然是 built-in，这样才能在默认安装中稳定可用。
+
+## Acceptance Criteria
+
+- `config.example.yaml` 中可默认启用 `glob` 与 `grep`
+- 两个工具归属 `file:read` 组
+- 本地 sandbox 下严格遵守现有路径权限
+- 输出不泄露宿主机真实路径
+- 大结果集会被截断并明确提示
+- 模型可以通过 `glob -> grep -> read_file -> str_replace` 完成典型改码流
+- 在禁用 host bash 的本地模式下，仓库探索能力明显提升
+
+## Rollout Plan
+
+1. 在 `sandbox/tools.py` 中实现 `glob_tool` 与 `grep_tool`
+2. 抽取与 `list_dir` 一致的 ignore 规则，避免行为漂移
+3. 在 `config.example.yaml` 默认加入工具配置
+4. 为本地路径校验、虚拟路径映射、结果截断、二进制跳过补测试
+5. 更新 README / backend docs / prompt guidance
+6. 收集实际 agent 调用数据，再决定是否下沉到 `Sandbox` 抽象
+
+## Suggested Config
+
+```yaml
+tools:
+  - name: glob
+    group: file:read
+    use: deerflow.sandbox.tools:glob_tool
+
+  - name: grep
+    group: file:read
+    use: deerflow.sandbox.tools:grep_tool
+```
+
+## Final Recommendation
+
+结论是：**可以加，而且应该加。**
+
+但我会明确卡三个边界：
+
+1. `grep` / `glob` 必须是 built-in 的只读结构化工具
+2. 第一版不要做 shell wrapper，不要把 CLI 方言直接暴露给模型
+3. 先在 `sandbox/tools.py` 验证价值，再考虑是否下沉到 `Sandbox` provider 抽象
+
+如果按这个方向做，它会明显提升 DeerFlow 在 coding / repo exploration 场景下的可用性，而且风险可控。

offline-backend-20260512/backend/docs/summarization.md

@@ -0,0 +1,381 @@
+# Conversation Summarization
+
+DeerFlow includes automatic conversation summarization to handle long conversations that approach model token limits. When enabled, the system automatically condenses older messages while preserving recent context.
+
+## Overview
+
+The summarization feature uses LangChain's `SummarizationMiddleware` to monitor conversation history and trigger summarization based on configurable thresholds. When activated, it:
+
+1. Monitors message token counts in real-time
+2. Triggers summarization when thresholds are met
+3. Keeps recent messages intact while summarizing older exchanges
+4. Maintains AI/Tool message pairs together for context continuity
+5. Injects the summary back into the conversation
+
+## Configuration
+
+Summarization is configured in `config.yaml` under the `summarization` key:
+
+```yaml
+summarization:
+  enabled: true
+  model_name: null  # Use default model or specify a lightweight model
+
+  # Trigger conditions (OR logic - any condition triggers summarization)
+  trigger:
+    - type: tokens
+      value: 4000
+    # Additional triggers (optional)
+    # - type: messages
+    #   value: 50
+    # - type: fraction
+    #   value: 0.8  # 80% of model's max input tokens
+
+  # Context retention policy
+  keep:
+    type: messages
+    value: 20
+
+  # Token trimming for summarization call
+  trim_tokens_to_summarize: 4000
+
+  # Custom summary prompt (optional)
+  summary_prompt: null
+
+  # Tool names treated as skill file reads for skill rescue
+  skill_file_read_tool_names:
+    - read_file
+    - read
+    - view
+    - cat
+```
+
+### Configuration Options
+
+#### `enabled`
+- **Type**: Boolean
+- **Default**: `false`
+- **Description**: Enable or disable automatic summarization
+
+#### `model_name`
+- **Type**: String or null
+- **Default**: `null` (uses default model)
+- **Description**: Model to use for generating summaries. Recommended to use a lightweight, cost-effective model like `gpt-4o-mini` or equivalent.
+
+#### `trigger`
+- **Type**: Single `ContextSize` or list of `ContextSize` objects
+- **Required**: At least one trigger must be specified when enabled
+- **Description**: Thresholds that trigger summarization. Uses OR logic - summarization runs when ANY threshold is met.
+
+**ContextSize Types:**
+
+1. **Token-based trigger**: Activates when token count reaches the specified value
+   ```yaml
+   trigger:
+     type: tokens
+     value: 4000
+   ```
+
+2. **Message-based trigger**: Activates when message count reaches the specified value
+   ```yaml
+   trigger:
+     type: messages
+     value: 50
+   ```
+
+3. **Fraction-based trigger**: Activates when token usage reaches a percentage of the model's maximum input tokens
+   ```yaml
+   trigger:
+     type: fraction
+     value: 0.8  # 80% of max input tokens
+   ```
+
+**Multiple Triggers:**
+```yaml
+trigger:
+  - type: tokens
+    value: 4000
+  - type: messages
+    value: 50
+```
+
+#### `keep`
+- **Type**: `ContextSize` object
+- **Default**: `{type: messages, value: 20}`
+- **Description**: Specifies how much recent conversation history to preserve after summarization.
+
+**Examples:**
+```yaml
+# Keep most recent 20 messages
+keep:
+  type: messages
+  value: 20
+
+# Keep most recent 3000 tokens
+keep:
+  type: tokens
+  value: 3000
+
+# Keep most recent 30% of model's max input tokens
+keep:
+  type: fraction
+  value: 0.3
+```
+
+#### `trim_tokens_to_summarize`
+- **Type**: Integer or null
+- **Default**: `4000`
+- **Description**: Maximum tokens to include when preparing messages for the summarization call itself. Set to `null` to skip trimming (not recommended for very long conversations).
+
+#### `summary_prompt`
+- **Type**: String or null
+- **Default**: `null` (uses LangChain's default prompt)
+- **Description**: Custom prompt template for generating summaries. The prompt should guide the model to extract the most important context.
+
+#### `preserve_recent_skill_count`
+- **Type**: Integer (≥ 0)
+- **Default**: `5`
+- **Description**: Number of most-recently-loaded skill files (tool results whose tool name is in `skill_file_read_tool_names` and whose target path is under `skills.container_path`, e.g. `/mnt/skills/...`) that are rescued from summarization. Prevents the agent from losing skill instructions after compression. Set to `0` to disable skill rescue entirely.
+
+#### `preserve_recent_skill_tokens`
+- **Type**: Integer (≥ 0)
+- **Default**: `25000`
+- **Description**: Total token budget reserved for rescued skill reads. Once this budget is exhausted, older skill bundles are allowed to be summarized.
+
+#### `preserve_recent_skill_tokens_per_skill`
+- **Type**: Integer (≥ 0)
+- **Default**: `5000`
+- **Description**: Per-skill token cap. Any individual skill read whose tool result exceeds this size is not rescued (it falls through to the summarizer like ordinary content).
+
+#### `skill_file_read_tool_names`
+- **Type**: List of strings
+- **Default**: `["read_file", "read", "view", "cat"]`
+- **Description**: Tool names treated as skill file reads during summarization rescue. A tool call is only eligible for skill rescue when its name appears in this list and its target path is under `skills.container_path`.
+
+**Default Prompt Behavior:**
+The default LangChain prompt instructs the model to:
+- Extract highest quality/most relevant context
+- Focus on information critical to the overall goal
+- Avoid repeating completed actions
+- Return only the extracted context
+
+## How It Works
+
+### Summarization Flow
+
+1. **Monitoring**: Before each model call, the middleware counts tokens in the message history
+2. **Trigger Check**: If any configured threshold is met, summarization is triggered
+3. **Message Partitioning**: Messages are split into:
+   - Messages to summarize (older messages beyond the `keep` threshold)
+   - Messages to preserve (recent messages within the `keep` threshold)
+4. **Summary Generation**: The model generates a concise summary of the older messages
+5. **Context Replacement**: The message history is updated:
+   - All old messages are removed
+   - A single summary message is added
+   - Recent messages are preserved
+6. **AI/Tool Pair Protection**: The system ensures AI messages and their corresponding tool messages stay together
+7. **Skill Rescue**: Before the summary is generated, the most recently loaded skill files (tool results whose tool name is in `skill_file_read_tool_names` and whose target path is under `skills.container_path`) are lifted out of the summarization set and prepended to the preserved tail. Selection walks newest-first under three budgets: `preserve_recent_skill_count`, `preserve_recent_skill_tokens`, and `preserve_recent_skill_tokens_per_skill`. The triggering AIMessage and all of its paired ToolMessages move together so tool_call ↔ tool_result pairing stays intact.
+
+### Token Counting
+
+- Uses approximate token counting based on character count
+- For Anthropic models: ~3.3 characters per token
+- For other models: Uses LangChain's default estimation
+- Can be customized with a custom `token_counter` function
+
+### Message Preservation
+
+The middleware intelligently preserves message context:
+
+- **Recent Messages**: Always kept intact based on `keep` configuration
+- **AI/Tool Pairs**: Never split - if a cutoff point falls within tool messages, the system adjusts to keep the entire AI + Tool message sequence together
+- **Summary Format**: Summary is injected as a HumanMessage with the format:
+  ```
+  Here is a summary of the conversation to date:
+
+  [Generated summary text]
+  ```
+
+## Best Practices
+
+### Choosing Trigger Thresholds
+
+1. **Token-based triggers**: Recommended for most use cases
+   - Set to 60-80% of your model's context window
+   - Example: For 8K context, use 4000-6000 tokens
+
+2. **Message-based triggers**: Useful for controlling conversation length
+   - Good for applications with many short messages
+   - Example: 50-100 messages depending on average message length
+
+3. **Fraction-based triggers**: Ideal when using multiple models
+   - Automatically adapts to each model's capacity
+   - Example: 0.8 (80% of model's max input tokens)
+
+### Choosing Retention Policy (`keep`)
+
+1. **Message-based retention**: Best for most scenarios
+   - Preserves natural conversation flow
+   - Recommended: 15-25 messages
+
+2. **Token-based retention**: Use when precise control is needed
+   - Good for managing exact token budgets
+   - Recommended: 2000-4000 tokens
+
+3. **Fraction-based retention**: For multi-model setups
+   - Automatically scales with model capacity
+   - Recommended: 0.2-0.4 (20-40% of max input)
+
+### Model Selection
+
+- **Recommended**: Use a lightweight, cost-effective model for summaries
+  - Examples: `gpt-4o-mini`, `claude-haiku`, or equivalent
+  - Summaries don't require the most powerful models
+  - Significant cost savings on high-volume applications
+
+- **Default**: If `model_name` is `null`, uses the default model
+  - May be more expensive but ensures consistency
+  - Good for simple setups
+
+### Optimization Tips
+
+1. **Balance triggers**: Combine token and message triggers for robust handling
+   ```yaml
+   trigger:
+     - type: tokens
+       value: 4000
+     - type: messages
+       value: 50
+   ```
+
+2. **Conservative retention**: Keep more messages initially, adjust based on performance
+   ```yaml
+   keep:
+     type: messages
+     value: 25  # Start higher, reduce if needed
+   ```
+
+3. **Trim strategically**: Limit tokens sent to summarization model
+   ```yaml
+   trim_tokens_to_summarize: 4000  # Prevents expensive summarization calls
+   ```
+
+4. **Monitor and iterate**: Track summary quality and adjust configuration
+
+## Troubleshooting
+
+### Summary Quality Issues
+
+**Problem**: Summaries losing important context
+
+**Solutions**:
+1. Increase `keep` value to preserve more messages
+2. Decrease trigger thresholds to summarize earlier
+3. Customize `summary_prompt` to emphasize key information
+4. Use a more capable model for summarization
+
+### Performance Issues
+
+**Problem**: Summarization calls taking too long
+
+**Solutions**:
+1. Use a faster model for summaries (e.g., `gpt-4o-mini`)
+2. Reduce `trim_tokens_to_summarize` to send less context
+3. Increase trigger thresholds to summarize less frequently
+
+### Token Limit Errors
+
+**Problem**: Still hitting token limits despite summarization
+
+**Solutions**:
+1. Lower trigger thresholds to summarize earlier
+2. Reduce `keep` value to preserve fewer messages
+3. Check if individual messages are very large
+4. Consider using fraction-based triggers
+
+## Implementation Details
+
+### Code Structure
+
+- **Configuration**: `packages/harness/deerflow/config/summarization_config.py`
+- **Integration**: `packages/harness/deerflow/agents/lead_agent/agent.py`
+- **Middleware**: Uses `langchain.agents.middleware.SummarizationMiddleware`
+
+### Middleware Order
+
+Summarization runs after ThreadData and Sandbox initialization but before Title and Clarification:
+
+1. ThreadDataMiddleware
+2. SandboxMiddleware
+3. **SummarizationMiddleware** ← Runs here
+4. TitleMiddleware
+5. ClarificationMiddleware
+
+### State Management
+
+- Summarization is stateless - configuration is loaded once at startup
+- Summaries are added as regular messages in the conversation history
+- The checkpointer persists the summarized history automatically
+
+## Example Configurations
+
+### Minimal Configuration
+```yaml
+summarization:
+  enabled: true
+  trigger:
+    type: tokens
+    value: 4000
+  keep:
+    type: messages
+    value: 20
+```
+
+### Production Configuration
+```yaml
+summarization:
+  enabled: true
+  model_name: gpt-4o-mini  # Lightweight model for cost efficiency
+  trigger:
+    - type: tokens
+      value: 6000
+    - type: messages
+      value: 75
+  keep:
+    type: messages
+    value: 25
+  trim_tokens_to_summarize: 5000
+```
+
+### Multi-Model Configuration
+```yaml
+summarization:
+  enabled: true
+  model_name: gpt-4o-mini
+  trigger:
+    type: fraction
+    value: 0.7  # 70% of model's max input
+  keep:
+    type: fraction
+    value: 0.3  # Keep 30% of max input
+  trim_tokens_to_summarize: 4000
+```
+
+### Conservative Configuration (High Quality)
+```yaml
+summarization:
+  enabled: true
+  model_name: gpt-4  # Use full model for high-quality summaries
+  trigger:
+    type: tokens
+    value: 8000
+  keep:
+    type: messages
+    value: 40  # Keep more context
+  trim_tokens_to_summarize: null  # No trimming
+```
+
+## References
+
+- [LangChain Summarization Middleware Documentation](https://docs.langchain.com/oss/python/langchain/middleware/built-in#summarization)
+- [LangChain Source Code](https://github.com/langchain-ai/langchain)

offline-backend-20260512/backend/docs/task_tool_improvements.md

@@ -0,0 +1,174 @@
+# Task Tool Improvements
+
+## Overview
+
+The task tool has been improved to eliminate wasteful LLM polling. Previously, when using background tasks, the LLM had to repeatedly call `task_status` to poll for completion, causing unnecessary API requests.
+
+## Changes Made
+
+### 1. Removed `run_in_background` Parameter
+
+The `run_in_background` parameter has been removed from the `task` tool. All subagent tasks now run asynchronously by default, but the tool handles completion automatically.
+
+**Before:**
+```python
+# LLM had to manage polling
+task_id = task(
+    subagent_type="bash",
+    prompt="Run tests",
+    description="Run tests",
+    run_in_background=True
+)
+# Then LLM had to poll repeatedly:
+while True:
+    status = task_status(task_id)
+    if completed:
+        break
+```
+
+**After:**
+```python
+# Tool blocks until complete, polling happens in backend
+result = task(
+    subagent_type="bash",
+    prompt="Run tests",
+    description="Run tests"
+)
+# Result is available immediately after the call returns
+```
+
+### 2. Backend Polling
+
+The `task_tool` now:
+- Starts the subagent task asynchronously
+- Polls for completion in the backend (every 2 seconds)
+- Blocks the tool call until completion
+- Returns the final result directly
+
+This means:
+- ✅ LLM makes only ONE tool call
+- ✅ No wasteful LLM polling requests
+- ✅ Backend handles all status checking
+- ✅ Timeout protection (5 minutes max)
+
+### 3. Removed `task_status` from LLM Tools
+
+The `task_status_tool` is no longer exposed to the LLM. It's kept in the codebase for potential internal/debugging use, but the LLM cannot call it.
+
+### 4. Updated Documentation
+
+- Updated `SUBAGENT_SECTION` in `prompt.py` to remove all references to background tasks and polling
+- Simplified usage examples
+- Made it clear that the tool automatically waits for completion
+
+## Implementation Details
+
+### Polling Logic
+
+Located in `packages/harness/deerflow/tools/builtins/task_tool.py`:
+
+```python
+# Start background execution
+task_id = executor.execute_async(prompt)
+
+# Poll for task completion in backend
+while True:
+    result = get_background_task_result(task_id)
+
+    # Check if task completed or failed
+    if result.status == SubagentStatus.COMPLETED:
+        return f"[Subagent: {subagent_type}]\n\n{result.result}"
+    elif result.status == SubagentStatus.FAILED:
+        return f"[Subagent: {subagent_type}] Task failed: {result.error}"
+
+    # Wait before next poll
+    time.sleep(2)
+
+    # Timeout protection (5 minutes)
+    if poll_count > 150:
+        return "Task timed out after 5 minutes"
+```
+
+### Execution Timeout
+
+In addition to polling timeout, subagent execution now has a built-in timeout mechanism:
+
+**Configuration** (`packages/harness/deerflow/subagents/config.py`):
+```python
+@dataclass
+class SubagentConfig:
+    # ...
+    timeout_seconds: int = 300  # 5 minutes default
+```
+
+**Thread Pool Architecture**:
+
+To avoid nested thread pools and resource waste, we use two dedicated thread pools:
+
+1. **Scheduler Pool** (`_scheduler_pool`):
+   - Max workers: 4
+   - Purpose: Orchestrates background task execution
+   - Runs `run_task()` function that manages task lifecycle
+
+2. **Execution Pool** (`_execution_pool`):
+   - Max workers: 8 (larger to avoid blocking)
+   - Purpose: Actual subagent execution with timeout support
+   - Runs `execute()` method that invokes the agent
+
+**How it works**:
+```python
+# In execute_async():
+_scheduler_pool.submit(run_task)  # Submit orchestration task
+
+# In run_task():
+future = _execution_pool.submit(self.execute, task)  # Submit execution
+exec_result = future.result(timeout=timeout_seconds)  # Wait with timeout
+```
+
+**Benefits**:
+- ✅ Clean separation of concerns (scheduling vs execution)
+- ✅ No nested thread pools
+- ✅ Timeout enforcement at the right level
+- ✅ Better resource utilization
+
+**Two-Level Timeout Protection**:
+1. **Execution Timeout**: Subagent execution itself has a 5-minute timeout (configurable in SubagentConfig)
+2. **Polling Timeout**: Tool polling has a 5-minute timeout (30 polls × 10 seconds)
+
+This ensures that even if subagent execution hangs, the system won't wait indefinitely.
+
+### Benefits
+
+1. **Reduced API Costs**: No more repeated LLM requests for polling
+2. **Simpler UX**: LLM doesn't need to manage polling logic
+3. **Better Reliability**: Backend handles all status checking consistently
+4. **Timeout Protection**: Two-level timeout prevents infinite waiting (execution + polling)
+
+## Testing
+
+To verify the changes work correctly:
+
+1. Start a subagent task that takes a few seconds
+2. Verify the tool call blocks until completion
+3. Verify the result is returned directly
+4. Verify no `task_status` calls are made
+
+Example test scenario:
+```python
+# This should block for ~10 seconds then return result
+result = task(
+    subagent_type="bash",
+    prompt="sleep 10 && echo 'Done'",
+    description="Test task"
+)
+# result should contain "Done"
+```
+
+## Migration Notes
+
+For users/code that previously used `run_in_background=True`:
+- Simply remove the parameter
+- Remove any polling logic
+- The tool will automatically wait for completion
+
+No other changes needed - the API is backward compatible (minus the removed parameter).

offline-backend-20260512/backend/langgraph.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://langgra.ph/schema.json",
+  "python_version": "3.12",
+  "dependencies": [
+    "."
+  ],
+  "env": ".env",
+  "graphs": {
+    "lead_agent": "deerflow.agents:make_lead_agent"
+  },
+  "auth": {
+    "path": "./app/gateway/langgraph_auth.py:auth"
+  },
+  "checkpointer": {
+    "path": "./packages/harness/deerflow/runtime/checkpointer/async_provider.py:make_checkpointer"
+  }
+}

offline-backend-20260512/backend/packages/harness/deerflow/agents/__init__.py

@@ -0,0 +1,20 @@
+from .factory import create_deerflow_agent
+from .features import Next, Prev, RuntimeFeatures
+from .lead_agent import make_lead_agent
+from .lead_agent.prompt import prime_enabled_skills_cache
+from .thread_state import SandboxState, ThreadState
+
+# LangGraph imports deerflow.agents when registering the graph. Prime the
+# enabled-skills cache here so the request path can usually read a warm cache
+# without forcing synchronous filesystem work during prompt module import.
+prime_enabled_skills_cache()
+
+__all__ = [
+    "create_deerflow_agent",
+    "RuntimeFeatures",
+    "Next",
+    "Prev",
+    "make_lead_agent",
+    "SandboxState",
+    "ThreadState",
+]

offline-backend-20260512/backend/packages/harness/deerflow/agents/factory.py

@@ -0,0 +1,374 @@
+"""Pure-argument factory for DeerFlow agents.
+
+``create_deerflow_agent`` accepts plain Python arguments — no YAML files, no
+global singletons.  It is the SDK-level entry point sitting between the raw
+``langchain.agents.create_agent`` primitive and the config-driven
+``make_lead_agent`` application factory.
+
+Note: the factory assembly itself is config-free, but some injected runtime
+components (e.g. ``task_tool`` for subagent) may still read global config at
+invocation time.  Full config-free runtime is a Phase 2 goal.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from langchain.agents import create_agent
+from langchain.agents.middleware import AgentMiddleware
+
+from deerflow.agents.features import RuntimeFeatures
+from deerflow.agents.middlewares.clarification_middleware import ClarificationMiddleware
+from deerflow.agents.middlewares.dangling_tool_call_middleware import DanglingToolCallMiddleware
+from deerflow.agents.middlewares.tool_error_handling_middleware import ToolErrorHandlingMiddleware
+from deerflow.agents.thread_state import ThreadState
+from deerflow.tools.builtins import ask_clarification_tool
+
+if TYPE_CHECKING:
+    from langchain_core.language_models import BaseChatModel
+    from langchain_core.tools import BaseTool
+    from langgraph.checkpoint.base import BaseCheckpointSaver
+    from langgraph.graph.state import CompiledStateGraph
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# TodoMiddleware prompts (minimal SDK version)
+# ---------------------------------------------------------------------------
+
+_TODO_SYSTEM_PROMPT = """
+<todo_list_system>
+You have access to the `write_todos` tool to help you manage and track complex multi-step objectives.
+
+**CRITICAL RULES:**
+- Mark todos as completed IMMEDIATELY after finishing each step - do NOT batch completions
+- Keep EXACTLY ONE task as `in_progress` at any time (unless tasks can run in parallel)
+- Update the todo list in REAL-TIME as you work - this gives users visibility into your progress
+- DO NOT use this tool for simple tasks (< 3 steps) - just complete them directly
+</todo_list_system>
+"""
+
+_TODO_TOOL_DESCRIPTION = "Use this tool to create and manage a structured task list for complex work sessions.  Only use for complex tasks (3+ steps)."
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def create_deerflow_agent(
+    model: BaseChatModel,
+    tools: list[BaseTool] | None = None,
+    *,
+    system_prompt: str | None = None,
+    middleware: list[AgentMiddleware] | None = None,
+    features: RuntimeFeatures | None = None,
+    extra_middleware: list[AgentMiddleware] | None = None,
+    plan_mode: bool = False,
+    state_schema: type | None = None,
+    checkpointer: BaseCheckpointSaver | None = None,
+    name: str = "default",
+) -> CompiledStateGraph:
+    """Create a DeerFlow agent from plain Python arguments.
+
+    The factory assembly itself reads no config files.  Some injected runtime
+    components (e.g. ``task_tool``) may still depend on global config at
+    invocation time — see Phase 2 roadmap for full config-free runtime.
+
+    Parameters
+    ----------
+    model:
+        Chat model instance.
+    tools:
+        User-provided tools.  Feature-injected tools are appended automatically.
+    system_prompt:
+        System message.  ``None`` uses a minimal default.
+    middleware:
+        **Full takeover** — if provided, this exact list is used.
+        Cannot be combined with *features* or *extra_middleware*.
+    features:
+        Declarative feature flags.  Cannot be combined with *middleware*.
+    extra_middleware:
+        Additional middlewares inserted into the auto-assembled chain via
+        ``@Next``/``@Prev`` positioning.  Cannot be used with *middleware*.
+    plan_mode:
+        Enable TodoMiddleware for task tracking.
+    state_schema:
+        LangGraph state type.  Defaults to ``ThreadState``.
+    checkpointer:
+        Optional persistence backend.
+    name:
+        Agent name (passed to middleware that cares, e.g. ``MemoryMiddleware``).
+
+    Raises
+    ------
+    ValueError
+        If both *middleware* and *features*/*extra_middleware* are provided.
+    """
+    if middleware is not None and features is not None:
+        raise ValueError("Cannot specify both 'middleware' and 'features'.  Use one or the other.")
+    if middleware is not None and extra_middleware:
+        raise ValueError("Cannot use 'extra_middleware' with 'middleware' (full takeover).")
+    if extra_middleware:
+        for mw in extra_middleware:
+            if not isinstance(mw, AgentMiddleware):
+                raise TypeError(f"extra_middleware items must be AgentMiddleware instances, got {type(mw).__name__}")
+
+    effective_tools: list[BaseTool] = list(tools or [])
+    effective_state = state_schema or ThreadState
+
+    if middleware is not None:
+        effective_middleware = list(middleware)
+    else:
+        feat = features or RuntimeFeatures()
+        effective_middleware, extra_tools = _assemble_from_features(
+            feat,
+            name=name,
+            plan_mode=plan_mode,
+            extra_middleware=extra_middleware or [],
+        )
+        # Deduplicate by tool name — user-provided tools take priority.
+        existing_names = {t.name for t in effective_tools}
+        for t in extra_tools:
+            if t.name not in existing_names:
+                effective_tools.append(t)
+                existing_names.add(t.name)
+
+    return create_agent(
+        model=model,
+        tools=effective_tools or None,
+        middleware=effective_middleware,
+        system_prompt=system_prompt,
+        state_schema=effective_state,
+        checkpointer=checkpointer,
+        name=name,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Internal: feature-driven middleware assembly
+# ---------------------------------------------------------------------------
+
+
+def _assemble_from_features(
+    feat: RuntimeFeatures,
+    *,
+    name: str = "default",
+    plan_mode: bool = False,
+    extra_middleware: list[AgentMiddleware] | None = None,
+) -> tuple[list[AgentMiddleware], list[BaseTool]]:
+    """Build an ordered middleware chain + extra tools from *feat*.
+
+    Middleware order matches ``make_lead_agent`` (14 middlewares):
+
+      0-2. Sandbox infrastructure (ThreadData → Uploads → Sandbox)
+      3.   DanglingToolCallMiddleware (always)
+      4.   GuardrailMiddleware (guardrail feature)
+      5.   ToolErrorHandlingMiddleware (always)
+      6.   SummarizationMiddleware (summarization feature)
+      7.   TodoMiddleware (plan_mode parameter)
+      8.   TitleMiddleware (auto_title feature)
+      9.   MemoryMiddleware (memory feature)
+      10.  ViewImageMiddleware (vision feature)
+      11.  SubagentLimitMiddleware (subagent feature)
+      12.  LoopDetectionMiddleware (always)
+      13.  ClarificationMiddleware (always last)
+
+    Two-phase ordering:
+      1. Built-in chain — fixed sequential append.
+      2. Extra middleware — inserted via @Next/@Prev.
+
+    Each feature value is handled as:
+      - ``False``: skip
+      - ``True``: create the built-in default middleware (not available for
+        ``summarization`` and ``guardrail`` — these require a custom instance)
+      - ``AgentMiddleware`` instance: use directly (custom replacement)
+    """
+    chain: list[AgentMiddleware] = []
+    extra_tools: list[BaseTool] = []
+
+    # --- [0-2] Sandbox infrastructure ---
+    if feat.sandbox is not False:
+        if isinstance(feat.sandbox, AgentMiddleware):
+            chain.append(feat.sandbox)
+        else:
+            from deerflow.agents.middlewares.thread_data_middleware import ThreadDataMiddleware
+            from deerflow.agents.middlewares.uploads_middleware import UploadsMiddleware
+            from deerflow.sandbox.middleware import SandboxMiddleware
+
+            chain.append(ThreadDataMiddleware(lazy_init=True))
+            chain.append(UploadsMiddleware())
+            chain.append(SandboxMiddleware(lazy_init=True))
+
+    # --- [3] DanglingToolCall (always) ---
+    chain.append(DanglingToolCallMiddleware())
+
+    # --- [4] Guardrail ---
+    if feat.guardrail is not False:
+        if isinstance(feat.guardrail, AgentMiddleware):
+            chain.append(feat.guardrail)
+        else:
+            raise ValueError("guardrail=True requires a custom AgentMiddleware instance (no built-in GuardrailMiddleware yet)")
+
+    # --- [5] ToolErrorHandling (always) ---
+    chain.append(ToolErrorHandlingMiddleware())
+
+    # --- [6] Summarization ---
+    if feat.summarization is not False:
+        if isinstance(feat.summarization, AgentMiddleware):
+            chain.append(feat.summarization)
+        else:
+            raise ValueError("summarization=True requires a custom AgentMiddleware instance (SummarizationMiddleware needs a model argument)")
+
+    # --- [7] TodoMiddleware (plan_mode) ---
+    if plan_mode:
+        from deerflow.agents.middlewares.todo_middleware import TodoMiddleware
+
+        chain.append(TodoMiddleware(system_prompt=_TODO_SYSTEM_PROMPT, tool_description=_TODO_TOOL_DESCRIPTION))
+
+    # --- [8] Auto Title ---
+    if feat.auto_title is not False:
+        if isinstance(feat.auto_title, AgentMiddleware):
+            chain.append(feat.auto_title)
+        else:
+            from deerflow.agents.middlewares.title_middleware import TitleMiddleware
+
+            chain.append(TitleMiddleware())
+
+    # --- [9] Memory ---
+    if feat.memory is not False:
+        if isinstance(feat.memory, AgentMiddleware):
+            chain.append(feat.memory)
+        else:
+            from deerflow.agents.middlewares.memory_middleware import MemoryMiddleware
+
+            chain.append(MemoryMiddleware(agent_name=name))
+
+    # --- [10] Vision ---
+    if feat.vision is not False:
+        if isinstance(feat.vision, AgentMiddleware):
+            chain.append(feat.vision)
+        else:
+            from deerflow.agents.middlewares.view_image_middleware import ViewImageMiddleware
+
+            chain.append(ViewImageMiddleware())
+
+        if feat.sandbox is not False:
+            from deerflow.tools.builtins import view_image_tool
+
+            extra_tools.append(view_image_tool)
+
+    # --- [11] Subagent ---
+    if feat.subagent is not False:
+        if isinstance(feat.subagent, AgentMiddleware):
+            chain.append(feat.subagent)
+        else:
+            from deerflow.agents.middlewares.subagent_limit_middleware import SubagentLimitMiddleware
+
+            chain.append(SubagentLimitMiddleware())
+        from deerflow.tools.builtins import task_tool
+
+        extra_tools.append(task_tool)
+
+    # --- [12] LoopDetection (always) ---
+    from deerflow.agents.middlewares.loop_detection_middleware import LoopDetectionMiddleware
+
+    chain.append(LoopDetectionMiddleware())
+
+    # --- [13] Clarification (always last among built-ins) ---
+    chain.append(ClarificationMiddleware())
+    extra_tools.append(ask_clarification_tool)
+
+    # --- Insert extra_middleware via @Next/@Prev ---
+    if extra_middleware:
+        _insert_extra(chain, extra_middleware)
+        # Invariant: ClarificationMiddleware must always be last.
+        # @Next(ClarificationMiddleware) could push it off the tail.
+        clar_idx = next(i for i, m in enumerate(chain) if isinstance(m, ClarificationMiddleware))
+        if clar_idx != len(chain) - 1:
+            chain.append(chain.pop(clar_idx))
+
+    return chain, extra_tools
+
+
+# ---------------------------------------------------------------------------
+# Internal: extra middleware insertion with @Next/@Prev
+# ---------------------------------------------------------------------------
+
+
+def _insert_extra(chain: list[AgentMiddleware], extras: list[AgentMiddleware]) -> None:
+    """Insert extra middlewares into *chain* using ``@Next``/``@Prev`` anchors.
+
+    Algorithm:
+      1. Validate: no middleware has both @Next and @Prev.
+      2. Conflict detection: two extras targeting same anchor (same or opposite direction) → error.
+      3. Insert unanchored extras before ClarificationMiddleware.
+      4. Insert anchored extras iteratively (supports cross-external anchoring).
+      5. If an anchor cannot be resolved after all rounds → error.
+    """
+    next_targets: dict[type, type] = {}
+    prev_targets: dict[type, type] = {}
+
+    anchored: list[tuple[AgentMiddleware, str, type]] = []
+    unanchored: list[AgentMiddleware] = []
+
+    for mw in extras:
+        next_anchor = getattr(type(mw), "_next_anchor", None)
+        prev_anchor = getattr(type(mw), "_prev_anchor", None)
+
+        if next_anchor and prev_anchor:
+            raise ValueError(f"{type(mw).__name__} cannot have both @Next and @Prev")
+
+        if next_anchor:
+            if next_anchor in next_targets:
+                raise ValueError(f"Conflict: {type(mw).__name__} and {next_targets[next_anchor].__name__} both @Next({next_anchor.__name__})")
+            if next_anchor in prev_targets:
+                raise ValueError(f"Conflict: {type(mw).__name__} @Next({next_anchor.__name__}) and {prev_targets[next_anchor].__name__} @Prev({next_anchor.__name__}) — use cross-anchoring between extras instead")
+            next_targets[next_anchor] = type(mw)
+            anchored.append((mw, "next", next_anchor))
+        elif prev_anchor:
+            if prev_anchor in prev_targets:
+                raise ValueError(f"Conflict: {type(mw).__name__} and {prev_targets[prev_anchor].__name__} both @Prev({prev_anchor.__name__})")
+            if prev_anchor in next_targets:
+                raise ValueError(f"Conflict: {type(mw).__name__} @Prev({prev_anchor.__name__}) and {next_targets[prev_anchor].__name__} @Next({prev_anchor.__name__}) — use cross-anchoring between extras instead")
+            prev_targets[prev_anchor] = type(mw)
+            anchored.append((mw, "prev", prev_anchor))
+        else:
+            unanchored.append(mw)
+
+    # Unanchored → before ClarificationMiddleware
+    clarification_idx = next(i for i, m in enumerate(chain) if isinstance(m, ClarificationMiddleware))
+    for mw in unanchored:
+        chain.insert(clarification_idx, mw)
+        clarification_idx += 1
+
+    # Anchored → iterative insertion (supports external-to-external anchoring)
+    pending = list(anchored)
+    max_rounds = len(pending) + 1
+    for _ in range(max_rounds):
+        if not pending:
+            break
+        remaining = []
+        for mw, direction, anchor in pending:
+            idx = next(
+                (i for i, m in enumerate(chain) if isinstance(m, anchor)),
+                None,
+            )
+            if idx is None:
+                remaining.append((mw, direction, anchor))
+                continue
+            if direction == "next":
+                chain.insert(idx + 1, mw)
+            else:
+                chain.insert(idx, mw)
+        if len(remaining) == len(pending):
+            names = [type(m).__name__ for m, _, _ in remaining]
+            anchor_types = {a for _, _, a in remaining}
+            remaining_types = {type(m) for m, _, _ in remaining}
+            circular = anchor_types & remaining_types
+            if circular:
+                raise ValueError(f"Circular dependency among extra middlewares: {', '.join(t.__name__ for t in circular)}")
+            raise ValueError(f"Cannot resolve positions for {', '.join(names)} — anchors {', '.join(a.__name__ for _, _, a in remaining)} not found in chain")
+        pending = remaining