[Review Required]feat: support client context capabilities

[BlairLeng]

概要

这个 PR 增加了一个轻量的 context.client 机制，使自定义前端可以把客户端能力和偏好传入 DeerFlow runtime。

目标是让 agent 和 skill 能够根据当前请求来源的客户端做出更合适的输出决策，例如判断是否支持 artifact、CSV 下载、图表，或者是否只能返回纯文本结果。

改动

• 增加 context.client 的安全裁剪和 prompt 渲染 helper
• 将 gateway run request 中经过安全裁剪的 context.client 转发到 runtime.context
• 将简洁的隐藏 client context reminder 注入到 agent 的动态上下文中
• 为前端 thread context 增加 client context 类型定义
• 补充 context.client 的请求格式文档
• 增加针对安全裁剪、gateway 转发、动态上下文注入的回归测试

示例

{
  "context": {
    "client": {
      "name": "custom-analytics-frontend",
      "capabilities": {
        "artifacts": true,
        "csv_download": true,
        "charts": true
      },
      "preferences": {
        "csv": "present",
        "chart": "present"
      }
    }
  }
}

Closes #3105

[BlairLeng]

DeerFlow 团队好，再次感谢你们维护这个项目。

这个 PR 是关于 client context 讨论的一个小型后续实现。改动范围我尽量控制得比较小：主要是把经过安全裁剪的 context.client 传入 runtime context，并以简洁的隐藏上下文形式暴露给 agent，同时补充了测试和文档。

我已经在本地完整跑过检查：

• 后端 make format
• 后端 make test
• 前端 pnpm format:write
• 前端 make test
• 前端 make test-e2e

有时间的话，期待你们帮忙 review，也欢迎指出这个方向是否需要调整。

@WillemJiang @jimma Thank you very much

[CLAassistant]

All committers have signed the CLA.

[WillemJiang]

@BlairLeng, thanks for your contribution. Please update your GitHub profile->emails with the email of your git commit author to address the complaint of the CLA assistant.

[Copilot]

Pull request overview

This PR introduces a lightweight context.client mechanism so custom frontends can pass client capabilities/preferences through the Gateway into runtime.context, and (optionally) into a compact hidden <client_context> reminder for agent/skill output shaping.

Changes:

• Add backend sanitization + prompt rendering helpers for context.client, and forward sanitized client context into runtime.context from the Gateway.
• Extend DynamicContextMiddleware to inject/update client context reminders alongside existing memory/date reminders.
• Add frontend typings, API docs, and regression tests covering sanitization, forwarding, and reminder injection behavior.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
frontend/src/core/threads/types.ts	Adds AgentClientContext typing and exposes it on AgentThreadContext.
backend/app/gateway/services.py	Sanitizes + forwards context.client into config["context"] (runtime-only).
backend/app/gateway/routers/thread_runs.py	Documents that context may include context.client.
backend/packages/harness/deerflow/runtime/client_context.py	New sanitization + prompt rendering utilities for client context.
backend/packages/harness/deerflow/agents/middlewares/dynamic_context_middleware.py	Injects rendered client context into hidden system reminders and supports same-day updates.
backend/docs/API.md	Documents request format and semantics for top-level context.client.
backend/tests/test_client_context.py	Adds unit tests for sanitization + rendering behavior.
backend/tests/test_gateway_services.py	Adds tests ensuring sanitized client context is runtime-only and respects explicit config precedence.
backend/tests/test_dynamic_context_middleware.py	Adds tests for reminder injection/update/clearing behavior for client context.
backend/tests/test_runtime_lifecycle_e2e.py	Improves cancellation test determinism by waiting until the fake agent is actually blocked.

Comments suppressed due to low confidence (1)

backend/packages/harness/deerflow/runtime/client_context.py:97

• Same issue for preferences: list(raw_preferences.items())[:_MAX_CLIENT_CONTEXT_ITEMS] builds a full list before slicing. Consider iterating and stopping after _MAX_CLIENT_CONTEXT_ITEMS to avoid unnecessary allocations on large client-provided payloads.

    raw_preferences = raw_client.get("preferences")
    if isinstance(raw_preferences, Mapping):
        preferences: dict[str, str | int | float | bool] = {}
        for raw_key, raw_value in list(raw_preferences.items())[:_MAX_CLIENT_CONTEXT_ITEMS]:
            key = _clean_key(raw_key)
            value = _clean_preference_value(raw_value)
            if key is None or value is None:
                continue
            preferences[key] = value

[BlairLeng]

@BlairLeng, thanks for your contribution. Please update your GitHub profile->emails with the email of your git commit author to address the complaint of the CLA assistant.

@WillemJiang Thanks for the reminder.

I have added and verified both email addresses in my GitHub profile:

• ziang.leng@centurygame.com
• zaleng@bu.edu

I also rewrote and rebased the PR branch earlier so the current commits are authored by:

Blair Leng <25675774+BlairLeng@users.noreply.github.com>

Both current commits are linked to my GitHub account @BlairLeng, and the latest CLA assistant check is passing with:

All committers have signed the CLA.

I am not fully sure why CLA assistant left two comments in the PR timeline. My understanding is that the earlier failure comment was from the old commit author identity before I rewrote the branch, and the later comment reflects the current passing status.

Please let me know if there is anything else I should adjust.

[WillemJiang]

@BlairLeng, please take some time to address Copilot's review comments.
BTW, the CLA assistant complaint was addressed.