mirror of
https://github.com/bytedance/deer-flow.git
synced 2026-11-20 03:10:34 +00:00
fix(harness): reflect progress in loop detection and plan todos (#8248)
* feat(frontend): improve file attachment recovery and artifact presentation * feat(extensions): add Office artifact previews with search and navigation * fix: preserve public viewers and HTTP Office previews * fix: address file preview and upload review findings * fix: use typed upload errors and linear bookmark allocation * fix(office-preview): isolate parsing and bound preview resources * fix(ci): install Office preview fixture dependencies for E2E * fix(ci): provision matching Playwright browsers before E2E tests * fix(ci): isolate Python libraries and include Office documentation * test(frontend): wait for download status to finish rendering * fix(harness): account for tool results in loop detection * fix(harness): make tool frequency detection observational * fix(harness): support blocked and waiting plan todos * style(harness): wrap overlong system prompt lines * Improve loop detection and todo message formatting Refactor middleware logic for handling repeated results and update messages for todo list. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * Address plan progress and loop detection review --------- Co-authored-by: Willem Jiang <willem.jiang@gmail.com> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
This commit is contained in:
parent
6b463d1f1a
commit
25a744a99a
@ -70,11 +70,13 @@ restore obsolete progress hints, including same-run goal continuations.
|
||||
| 8 | **ViewImageMiddleware** | Injects image data for vision-capable models (conditional) |
|
||||
| 9 | **ClarificationMiddleware** | Intercepts clarification requests and interrupts execution (must be last) |
|
||||
|
||||
When `loop_detection.enabled` is set, loop detection checks both repeated
|
||||
tool-call sets and per-tool frequency. Warnings do not skip the rest of a
|
||||
tool-call batch: any hard limit reached takes precedence and stops the entire
|
||||
batch before tool execution. Warning-only batches remain fully counted and
|
||||
receive a transient hint on the next model request.
|
||||
When `loop_detection.enabled` is set, loop detection checks repeated tool-call
|
||||
sets whose results show no progress. Warnings do not skip the rest of a
|
||||
tool-call batch: a hash-based hard limit stops the entire batch before tool
|
||||
execution. Tool-name frequency is retained as an INFO observability metric for
|
||||
workload and cost analysis; its thresholds never warn or stop a run. Warning-
|
||||
only batches remain fully counted and receive a transient hint on the next
|
||||
model request.
|
||||
|
||||
### Sandbox System
|
||||
|
||||
|
||||
@ -48,6 +48,7 @@ from deerflow.agents.interaction_policy import resolve_run_interaction_policy
|
||||
from deerflow.agents.language import ui_locale
|
||||
from deerflow.agents.middlewares.dynamic_context_middleware import _DYNAMIC_CONTEXT_REMINDER_KEY, _REMINDER_DATE_KEY
|
||||
from deerflow.agents.middlewares.input_sanitization_middleware import frame_untrusted_text
|
||||
from deerflow.agents.middlewares.loop_detection_middleware import LOOP_CAP_STATE_KEY
|
||||
from deerflow.agents.middlewares.message_utils import _SUMMARY_MESSAGE_NAME, is_genuine_user_message
|
||||
from deerflow.agents.middlewares.skill_usage import SKILL_USAGE_KEY, SKILL_USAGES_KEY
|
||||
from deerflow.agents.middlewares.tool_output_budget_middleware import TOOL_OUTPUT_BLOB_KEY
|
||||
@ -643,12 +644,12 @@ def _normalize_input_messages(
|
||||
|
||||
#: State channels only the server writes. ``goal_outcome`` is the "goal met"
|
||||
#: record that clearing a satisfied goal writes; a caller copy would forge one.
|
||||
#: ``loop_cap`` is loop detection's record of capped tools; a caller copy could
|
||||
#: lift a cap or block a tool.
|
||||
SERVER_OWNED_STATE_CHANNELS = frozenset({"sandbox", "thread_data", "viewed_images", "goal_outcome", "applied_run_inputs", "loop_cap"})
|
||||
#: Older checkpoints can contain loop detection's record of frequency-capped
|
||||
#: tools. Reserve its channel for server-owned state.
|
||||
SERVER_OWNED_STATE_CHANNELS = frozenset({"sandbox", "thread_data", "viewed_images", "goal_outcome", "applied_run_inputs", LOOP_CAP_STATE_KEY})
|
||||
|
||||
#: The ``write_todos`` status contract the todo middleware renders.
|
||||
_TODO_STATUSES = frozenset({"pending", "in_progress", "completed"})
|
||||
_TODO_STATUSES = frozenset({"pending", "in_progress", "completed", "blocked", "waiting"})
|
||||
|
||||
|
||||
def _normalize_external_todos(value: Any, *, location: str) -> list[dict[str, Any]] | None:
|
||||
@ -673,7 +674,7 @@ def _normalize_external_todos(value: Any, *, location: str) -> list[dict[str, An
|
||||
raise HTTPException(status_code=400, detail=f"{location}[{index}].content must be a string")
|
||||
status = entry.get("status", "pending")
|
||||
if not isinstance(status, str) or status not in _TODO_STATUSES:
|
||||
raise HTTPException(status_code=400, detail=f"{location}[{index}].status must be pending, in_progress, or completed")
|
||||
raise HTTPException(status_code=400, detail=f"{location}[{index}].status must be pending, in_progress, completed, blocked, or waiting")
|
||||
normalized.append({**entry, "content": content, "status": status})
|
||||
return normalized
|
||||
|
||||
|
||||
@ -6,14 +6,14 @@ and audit contract are documented in the
|
||||
|
||||
## Run-scoped state
|
||||
|
||||
Hash histories, frequency windows/counters, and warning-suppression sets
|
||||
share a `(thread_id, run_id)` key. This gives a fresh budget to each user
|
||||
Hash histories, frequency windows/counters, and frequency-metric reporting
|
||||
sets share a `(thread_id, run_id)` key. This gives a fresh budget to each user
|
||||
run when a compiled graph is cached and reused, while keeping one budget
|
||||
across repeated graph entries belonging to the same Gateway run (including
|
||||
hidden goal continuations). `after_agent` clears only transient pending
|
||||
warnings for its own scope, not those histories; the sync/async
|
||||
`before_agent` hooks expire only the checkpointed [per-tool cap](#per-tool-cap)
|
||||
and must not delete a sibling run's pending warning. Direct LangGraph embedders may omit
|
||||
`before_agent` hooks remain topology-preserving no-ops and must not delete a
|
||||
sibling run's pending warning. Direct LangGraph embedders may omit
|
||||
`context.run_id`; that fallback is anchored to the invocation's shared
|
||||
`Runtime.control` object and mapped to an opaque generated ID, because
|
||||
LangGraph replaces `Runtime` per node and CPython can reuse freed object
|
||||
@ -24,87 +24,15 @@ every retained run scope for that thread.
|
||||
|
||||
## Decision ordering
|
||||
|
||||
Loop decisions are severity-first across both detection layers: a warning
|
||||
candidate never short-circuits frequency accounting for the remaining calls
|
||||
in an admitted batch. The identical-call hard limit rejects the entire batch.
|
||||
A per-tool hard limit admits the batch's calls up to the limit and drops the
|
||||
calls that would reach it, because one response can carry many distinct calls
|
||||
that have not run yet; the dropped calls are not counted. A call reaches the
|
||||
limit when the window would hold that many calls to its tool after taking the
|
||||
call in and dropping its oldest entry. A call that only replaces an older call
|
||||
to the same tool is therefore admitted, so an interleaved workflow below the
|
||||
limit keeps running. Only a response in which no call fits stops the run. Only the selected warning is marked and logged;
|
||||
hash warnings still precede frequency warnings when neither layer stops the
|
||||
run. Among simultaneous frequency-warning candidates, the first crossing in
|
||||
model tool-call order remains selected for compatibility; later calls are
|
||||
still counted and can warn in a later batch. A frequency warning whose burst
|
||||
decays within the batch must not leave a stale suppression mark.
|
||||
Hash-based loop decisions are evaluated before the frequency metric is updated.
|
||||
A hash warning does not prevent the remaining tool names in the same response
|
||||
from being counted. Frequency thresholds only emit INFO metrics with
|
||||
`action="observe_only"`; they never enqueue a model warning, strip tool calls,
|
||||
or set a stop reason. The hash warning and hard-stop behavior remains scoped to
|
||||
identical calls whose results show no progress.
|
||||
|
||||
## Per-tool cap
|
||||
|
||||
A tool that reaches its per-tool hard limit is capped for the rest of the
|
||||
execution. The frequency window cannot express this on its own: dropped calls
|
||||
are not counted, so calls to other tools would evict the capped tool's entries
|
||||
and let it run again. The cap is therefore a record in the private `loop_cap`
|
||||
state channel: the capped tools with their limits, the run that carries the
|
||||
cap, and a notice for the model.
|
||||
|
||||
- **Every later call to a capped tool is dropped**, whatever the window counts.
|
||||
Other tools in the same response run under their own limits. A response that
|
||||
calls only capped tools stops the run.
|
||||
- **A run that dropped a call is `loop_capped`** in the run record and in a
|
||||
subagent result, although it goes on to wrap up. Goal continuation stands
|
||||
down on that reason. The calls that survive still run, so the reason is
|
||||
reported only when the run ends: other middlewares read `stop_reason` in the
|
||||
run context as "the run is ending" and skip their checks. Until then, input
|
||||
that arrives mid-run still cancels the response's planned calls, parallel
|
||||
`write_todos` calls are still rejected, input that arrives as the run
|
||||
finishes is still applied, and the todo completion reminder works as in any
|
||||
run. If another guard has already given the reason the run stopped, loop
|
||||
detection reports nothing, so the run record and a subagent result name the
|
||||
same guard. A response with no call left is a terminal stop and is reported
|
||||
at once, as before. A run that pauses for approval reports no reason; the
|
||||
run that resumes it reports `loop_capped` when it ends.
|
||||
- **A response whose admitted calls are all discarded leaves no trace.**
|
||||
Another middleware can drop every call that loop detection passed on before
|
||||
any of them runs: input admission does so when the user steers, and approval
|
||||
does so for calls it cannot address. Calls that never ran do not count, so
|
||||
as the next model call starts, the frequency window, the warnings and the cap
|
||||
record go back to their state before that response. Caps from earlier
|
||||
responses stay, and the notice for the discarded response is not sent. This
|
||||
runs in `wrap_model_call` rather than a `before_model` hook, because a hook
|
||||
is a graph node and would spend a super-step of every turn. A response that
|
||||
keeps some of its calls keeps its accounting, as before, and so does one that
|
||||
compaction has removed from the history.
|
||||
- **The model is told on its next call** how many calls of its last response
|
||||
were skipped and how many were passed on, followed by the wrap-up
|
||||
instructions. The text reports admission, not execution: an admitted call can
|
||||
still be denied by approval or a guardrail, and its tool result says so. The
|
||||
notice is read from the record on every model call and cleared once the model
|
||||
has answered, so a retried call gets it again. It quotes tool names and
|
||||
counts only, never arguments, because it is added inside PII redaction.
|
||||
- **The record is checkpointed**, so the cap and the notice survive an
|
||||
approval pause, the new `run_id` of the resume, a Gateway restart and
|
||||
context compaction. A resumed run adopts the record and reports
|
||||
`loop_capped` when it ends. Its frequency window starts empty, as for any new
|
||||
run.
|
||||
- **A new task gets a fresh budget.** `before_agent` runs when a task enters
|
||||
the graph and not when a paused run resumes, so it expires a record that
|
||||
another run left behind. A later entry of the same run, such as a hidden goal
|
||||
continuation, keeps it.
|
||||
|
||||
- **The record holds only what its reader accepts.** Tool names come from the
|
||||
model's response. A name the reader would reject (too long, or with
|
||||
whitespace) and a tool beyond the record's size bound are left out, because
|
||||
one such entry would make the next read discard every cap in the record. The
|
||||
window already dropped that tool's calls. The record and its notice are
|
||||
still written, so the drop is explained and the execution stays
|
||||
`loop_capped`; the notice then refers to "a tool" instead of a name.
|
||||
|
||||
The channel is server-owned: the Gateway rejects a client value for it, the
|
||||
graph leaves it out of its input and output, and a malformed record reads as
|
||||
no cap.
|
||||
|
||||
`backend/tests/test_loop_detection_middleware.py` covers mixed-tool batches,
|
||||
window decay, overrides, sync/async compiled-graph execution, and the cap
|
||||
across a real approval pause and checkpoint resume.
|
||||
The lead agent applies the subagent call limit before loop detection, so the
|
||||
detector reconciles results against the admitted batch. A successful
|
||||
`write_file` or `str_replace` invalidates the predicted result for older
|
||||
reads of the same path. The next read observes the current version and
|
||||
completed results remain in the repetition window.
|
||||
|
||||
@ -214,23 +214,20 @@ Current middleware tags are `guardrail`, `loop_detection`,
|
||||
are additive. Because the full event type is limited to 32 characters and
|
||||
`middleware:` uses 11, a tag must contain 1-21 characters.
|
||||
|
||||
`middleware:loop_detection` records transitions into the warned state (first
|
||||
per call hash or per tool-frequency burst) and each hard stop produced by
|
||||
`LoopDetectionMiddleware` in lead-agent and ordinary task-tool subagent runs.
|
||||
`middleware:loop_detection` records hash-based loop transitions into the
|
||||
warned state and each hard stop produced by `LoopDetectionMiddleware` in
|
||||
lead-agent and ordinary task-tool subagent runs. Tool-name frequency thresholds
|
||||
are observability metrics: they are emitted as INFO logs with
|
||||
`action=observe_only` and do not create middleware events or alter control flow.
|
||||
Task-tool subagents forward the append to the parent loop because `RunJournal`
|
||||
and its event store must not cross the isolated-loop boundary. Durable batch
|
||||
subagents have no parent run journal and do not emit these events. The event's
|
||||
`action` is `warn`, `hard_stop`, or `reject_excess` when a tool reaches its
|
||||
per-tool limit inside a batch: the calls that do not fit are dropped and the
|
||||
rest of the batch runs. Each tool that reaches its limit gets its own row with
|
||||
its own count and threshold. Later drops of the same capped tool are not
|
||||
recorded again. A row records the decision when it was made: if another
|
||||
middleware then discards every admitted call (for example after a steer), the
|
||||
cap is undone but the row stays. The `changes` object identifies the detection layer, affected tool
|
||||
names, observed count, effective threshold, whether the producer was a
|
||||
subagent, and its agent id when applicable. Tool arguments, prompts, message
|
||||
content, tool results, and argument-derived hashes are not persisted in this
|
||||
event.
|
||||
`action` is `warn` or `hard_stop`. Historical runs can contain `reject_excess`
|
||||
actions and the `tool_frequency` detection layer. The `changes` object
|
||||
identifies the detection layer, affected tool names, observed count, effective
|
||||
threshold, whether the producer was a subagent, and its agent id when applicable. Tool arguments,
|
||||
prompts, message content, tool results, and argument-derived hashes are not
|
||||
persisted in this event.
|
||||
|
||||
`middleware:tool_progress` records effective result-quality state transitions
|
||||
from `ToolProgressMiddleware`: `warn` for ACTIVE → WARNED, `block` for a
|
||||
|
||||
@ -17,8 +17,8 @@
|
||||
| 8 | TitleMiddleware | | | ✓ | | | | ✓ | ✗ | `auto_title` |
|
||||
| 9 | MemoryMiddleware | | | | ✓ | | | ✓ | ✗ | `memory` |
|
||||
| 10 | ViewImageMiddleware | | | | | ✓ | | ✓ | ✗ | `vision` |
|
||||
| 11 | SubagentLimitMiddleware | | | ✓ | | | | ✓ | ✗ | `subagent` |
|
||||
| 12 | LoopDetectionMiddleware | ✓ | | ✓ | ✓ | ✓ | | ✓ | ✗ | 始终开启 |
|
||||
| 11 | LoopDetectionMiddleware | ✓ | | ✓ | ✓ | ✓ | | ✓ | ✗ | 始终开启 |
|
||||
| 12 | SubagentLimitMiddleware | | | ✓ | | | | ✓ | ✗ | `subagent` |
|
||||
| 13 | ClarificationMiddleware | | | | | | ✓ | ✓ | ✗ | 始终最后 |
|
||||
|
||||
主 agent **14 个** middleware(`make_lead_agent`),subagent **4 个**(ThreadData、Sandbox、Guardrail、ToolErrorHandling)。`create_deerflow_agent` Phase 1 实现 **13 个**(Guardrail 仅支持自定义实例,无内置默认)。
|
||||
@ -118,18 +118,18 @@ sequenceDiagram
|
||||
Note right of LD: wrap_model_call drain 当前 run warning 并追加到末尾
|
||||
LD ->> M: messages + tools
|
||||
activate M
|
||||
M -->> LD: AI response
|
||||
M -->> SL: AI response
|
||||
deactivate M
|
||||
|
||||
Note right of LD: after_model 检测循环;warning 入队,hard-stop 清 tool_calls
|
||||
LD -->> SL: after_model
|
||||
deactivate LD
|
||||
|
||||
activate SL
|
||||
Note right of SL: after_model 截断多余 task
|
||||
SL -->> TI: after_model
|
||||
SL -->> LD: after_model
|
||||
deactivate SL
|
||||
|
||||
Note right of LD: after_model 检测已准入批次;warning 入队,hard-stop 清 tool_calls
|
||||
LD -->> TI: after_model
|
||||
deactivate LD
|
||||
|
||||
activate TI
|
||||
Note right of TI: after_model 生成标题
|
||||
TI -->> VI: done
|
||||
@ -297,4 +297,8 @@ sequenceDiagram
|
||||
|
||||
### LoopDetectionMiddleware 为什么同时用多个钩子?
|
||||
|
||||
`after_model` 只做检测:重复工具调用达到 warning 阈值时,把 warning 放入 `(thread_id, run_id)` 作用域的 pending 队列。真正注入发生在下一次 `wrap_model_call`:此时上一轮 `AIMessage(tool_calls)` 对应的 `ToolMessage` 已经在请求里,warning 追加在末尾,不会破坏 OpenAI/Moonshot 的 tool-call pairing。`before_agent` 清理同一 thread 下旧 run 的残留 warning,`after_agent` 清理当前 run 没被消费的 warning。
|
||||
`after_model` 只做检测:重复工具调用达到 warning 阈值时,把 warning 放入 `(thread_id, run_id)` 作用域的 pending 队列。真正注入发生在下一次 `wrap_model_call`:此时上一轮 `AIMessage(tool_calls)` 对应的 `ToolMessage` 已经在请求里,warning 追加在末尾,不会破坏 OpenAI/Moonshot 的 tool-call pairing。`after_agent` 清理当前 run 没被消费的 warning;检测历史保留在同一 run 内,供目标续跑共享预算,新 run 使用独立预算。
|
||||
|
||||
重复判定以整批调用的参数和结果指纹为依据,忽略批内执行顺序、调用 ID、回执等临时元数据。每轮先按 AIMessage 的调用实例配对上一批结果,再用同参调用最近的结果估计当前尚未执行的批次;结果返回后修正这次记录。成功结果不同会分别计数,所以正常的读取、修改、重新读取不会仅因参数相同而被拦截。范围读取还使用读写门禁附带的完整文件哈希,能识别未显示部分的版本变化。无效版本标记会被忽略。
|
||||
|
||||
相同成功结果仍会累计;结构化错误忽略变化的诊断文本,缺失、无法配对或无法序列化的结果退回调用模式保护。结果循环变化也会在最近窗口内累计各自的重复次数,而不是每次变化都清空历史。结果指纹只保留在有界的进程内历史中,不写入检查点或日志。默认仍在第 3 次重复请求警告、第 5 次强停;当前请求执行前只能依据已有结果判断。结果变化并不保证任务取得实质进展,因此每种工具的独立频率预算仅作为 INFO 指标观测(`action=observe_only`),不会触发 warning 或强停;只有基于参数/结果哈希的重复检测会产生警告并在阈值下硬停。
|
||||
|
||||
@ -63,8 +63,10 @@ The agent will skip using the todo list for:
|
||||
### Task States
|
||||
|
||||
- **pending**: Task not yet started
|
||||
- **in_progress**: Currently working on (can have multiple parallel tasks)
|
||||
- **completed**: Task finished successfully
|
||||
- **in_progress**: Currently being worked on
|
||||
- **blocked**: Work cannot continue because a dependency or error must be resolved; terminal for the current run
|
||||
- **waiting**: Waiting for the user or an external resource; terminal for the current run
|
||||
- **completed**: Task fully finished and verified
|
||||
|
||||
## Usage Examples
|
||||
|
||||
@ -185,12 +187,12 @@ DeerFlow uses custom `system_prompt` and `tool_description` for the TodoListMidd
|
||||
- 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
|
||||
- Updates the list at meaningful milestones and requires verified 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)
|
||||
- Clear task state definitions (pending, in_progress, blocked, waiting, completed)
|
||||
- Comprehensive best practices section
|
||||
- Task completion requirements to prevent premature marking
|
||||
|
||||
|
||||
@ -44,17 +44,23 @@ logger = logging.getLogger(__name__)
|
||||
# TodoMiddleware prompts (minimal SDK version)
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
_TODO_SYSTEM_PROMPT = """
|
||||
_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
|
||||
- Update todos at meaningful milestones and group related changes when practical
|
||||
- Mark `completed` only after a task is fully finished and verified
|
||||
- Use `in_progress` only while actively working; use `blocked` or `waiting` when work cannot continue in this run
|
||||
- DO NOT use this tool for simple tasks (< 3 steps) - just complete them directly
|
||||
</todo_list_system>
|
||||
|
||||
"""
|
||||
"Task states: `pending` (not started), `in_progress` (active), `blocked` (blocked by a dependency or error), "
|
||||
"`waiting` (waiting for the user or an external resource), and `completed` (fully finished and verified). "
|
||||
"Keep `completed` truthful; blocked or waiting tasks may remain when the run ends.\n"
|
||||
"</todo_list_system>\n"
|
||||
)
|
||||
|
||||
_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)."
|
||||
|
||||
|
||||
@ -375,9 +375,9 @@ def _create_todo_list_middleware(is_plan_mode: bool) -> TodoMiddleware | None:
|
||||
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
|
||||
- Update todos at meaningful milestones; group related status changes in one call
|
||||
- Mark a task `completed` only after it is fully finished and verified
|
||||
- Use `in_progress` only for work that is actively underway; do not keep a task active just to show progress
|
||||
- DO NOT use this tool for simple tasks (< 3 steps) - just complete them directly
|
||||
|
||||
**When to Use:**
|
||||
@ -429,16 +429,18 @@ Skip this tool when:
|
||||
|
||||
## How to Use
|
||||
|
||||
1. **Starting a task**: Mark it as `in_progress` BEFORE beginning work
|
||||
2. **Completing a task**: Mark it as `completed` IMMEDIATELY after finishing
|
||||
1. **Starting a task**: Mark it as `in_progress` when work begins
|
||||
2. **Completing a task**: Mark it as `completed` after it is fully finished and verified
|
||||
3. **Updating the list**: Add new tasks, remove irrelevant ones, or update descriptions as needed
|
||||
4. **Multiple updates**: You can make several updates at once (e.g., complete one task and start the next)
|
||||
|
||||
## Task States
|
||||
|
||||
- `pending`: Task not yet started
|
||||
- `in_progress`: Currently working on (can have multiple if tasks run in parallel)
|
||||
- `completed`: Task finished successfully
|
||||
- `in_progress`: Currently being worked on
|
||||
- `blocked`: Work cannot continue because a dependency or error must be resolved; terminal for this run
|
||||
- `waiting`: Waiting for the user or an external resource; terminal for this run
|
||||
- `completed`: Task fully finished and verified
|
||||
|
||||
## Task Completion Requirements
|
||||
|
||||
@ -451,18 +453,15 @@ Never mark a task as completed if:
|
||||
- You couldn't find necessary resources or dependencies
|
||||
- Quality standards haven't been met
|
||||
|
||||
If blocked, keep the task as `in_progress` and create a new task describing what needs to be resolved.
|
||||
If blocked or waiting, record that status and keep the reason in the task description. The run may finish with those statuses; do not relabel them as completed.
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Create specific, actionable items
|
||||
- Break complex tasks into smaller, manageable steps
|
||||
- Use clear, descriptive task names
|
||||
- Update task status in real-time as you work
|
||||
- Mark tasks complete IMMEDIATELY after finishing (don't batch completions)
|
||||
- Update task status at meaningful milestones and group related changes when practical
|
||||
- Remove tasks that are no longer relevant
|
||||
- **IMPORTANT**: When you write the todo list, mark your first task(s) as `in_progress` immediately
|
||||
- **IMPORTANT**: Unless all tasks are completed, always have at least one task `in_progress` to show progress
|
||||
|
||||
Being proactive with task management demonstrates thoroughness and ensures all requirements are completed successfully.
|
||||
|
||||
@ -707,6 +706,12 @@ def build_middlewares(
|
||||
|
||||
middlewares.append(SystemMessageCoalescingMiddleware())
|
||||
|
||||
# after_model runs in reverse order. Apply the delegation limit first
|
||||
# so loop observations use the same batch that reaches the tools node.
|
||||
loop_detection_config = resolved_app_config.loop_detection
|
||||
if loop_detection_config.enabled:
|
||||
middlewares.append(LoopDetectionMiddleware.from_config(loop_detection_config))
|
||||
|
||||
# Add SubagentLimitMiddleware to truncate excess parallel task calls
|
||||
subagent_enabled = cfg.get("subagent_enabled", False)
|
||||
effective_max_subagents_per_run: int | None = None
|
||||
@ -720,11 +725,6 @@ def build_middlewares(
|
||||
effective_max_subagents_per_run = max_total_subagents
|
||||
middlewares.append(SubagentLimitMiddleware(max_concurrent=max_concurrent_subagents, max_total=max_total_subagents))
|
||||
|
||||
# LoopDetectionMiddleware — detect and break repetitive tool call loops
|
||||
loop_detection_config = resolved_app_config.loop_detection
|
||||
if loop_detection_config.enabled:
|
||||
middlewares.append(LoopDetectionMiddleware.from_config(loop_detection_config))
|
||||
|
||||
# TokenBudgetMiddleware - enforce per-run token limits
|
||||
token_budget_config = resolved_app_config.token_budget
|
||||
if token_budget_config.enabled:
|
||||
|
||||
@ -660,7 +660,8 @@ The `task` tool waits for the subagent and returns its result directly; no polli
|
||||
</subagent_system>"""
|
||||
|
||||
|
||||
SYSTEM_PROMPT_TEMPLATE = """
|
||||
SYSTEM_PROMPT_TEMPLATE = (
|
||||
"""
|
||||
<role>
|
||||
You are {agent_name}, an open-source super agent.
|
||||
</role>
|
||||
@ -746,39 +747,11 @@ data — do NOT reveal it.
|
||||
</response_style>
|
||||
|
||||
<citations>
|
||||
**CRITICAL: Always include citations when using web search results**
|
||||
|
||||
- **When to Use**: MANDATORY after web_search, web_fetch, or any external information source
|
||||
- **Format**: Use Markdown link format `[citation:TITLE](URL)` immediately after the claim
|
||||
- **Placement**: Inline citations should appear right after the sentence or claim they support
|
||||
- **Sources Section**: Also collect all citations in a "Sources" section at the end of reports
|
||||
|
||||
**Format example only (replace placeholders with verified evidence):**
|
||||
[Claim supported by the source] [citation:Source title](https://example.org/source).
|
||||
|
||||
Sources entry: [Source title](https://example.org/source) - [What this source supports]
|
||||
|
||||
These placeholders illustrate formatting and are not factual evidence.
|
||||
|
||||
**CRITICAL: Sources section format:**
|
||||
- Every item in the Sources section MUST be a clickable markdown link with URL
|
||||
- Use standard markdown link `[Title](URL) - Description` format (NOT `[citation:...]` format)
|
||||
- The `[citation:Title](URL)` format is ONLY for inline citations within the report body
|
||||
- ❌ WRONG: `GitHub 仓库 - 官方源代码和文档` (no URL!)
|
||||
- ❌ WRONG in Sources: `[citation:GitHub Repository](url)` (citation prefix is for inline only!)
|
||||
- ✅ RIGHT in Sources: `[GitHub Repository](https://github.com/bytedance/deer-flow) - 官方源代码和文档`
|
||||
|
||||
**WORKFLOW for Research Tasks:**
|
||||
1. Use web_search to find sources → Extract {{title, url, snippet}} from results
|
||||
2. Write content with inline citations: `claim [citation:Title](url)`
|
||||
3. Collect all citations in a "Sources" section at the end
|
||||
4. NEVER write claims without citations when sources are available
|
||||
|
||||
**CRITICAL RULES:**
|
||||
- ❌ DO NOT write research content without citations
|
||||
- ❌ DO NOT forget to extract URLs from search results
|
||||
- ✅ ALWAYS add `[citation:Title](URL)` after claims from external sources
|
||||
- ✅ ALWAYS include a "Sources" section listing all references
|
||||
"""
|
||||
"When you use web_search, web_fetch, or another external source, cite sourced claims inline as [citation:Title](URL). "
|
||||
"For research or multi-source answers, add a `## Sources` list at the end using [Title](URL) - description. "
|
||||
"Short answers do not need a separate list when inline citations suffice. Never invent URLs or citations."
|
||||
"""
|
||||
</citations>
|
||||
|
||||
<critical_reminders>
|
||||
@ -809,6 +782,7 @@ These placeholders illustrate formatting and are not factual evidence.
|
||||
- Always Respond: Your thinking is internal. You MUST always provide a visible response to the user after thinking.
|
||||
</critical_reminders>
|
||||
"""
|
||||
)
|
||||
|
||||
|
||||
def _get_memory_context(
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -21,16 +21,19 @@ available for a later user run. An earlier response's provider stop does not
|
||||
suppress reminders in later Goal continuation turns of the same run.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import threading
|
||||
from collections.abc import Awaitable, Callable, Iterable, Mapping
|
||||
from typing import Any, override
|
||||
from typing import Any, Literal, override
|
||||
|
||||
from langchain.agents.middleware import TodoListMiddleware
|
||||
from langchain.agents.middleware.types import ModelCallResult, ModelRequest, ModelResponse, hook_config
|
||||
from langchain_core.messages import AIMessage, HumanMessage
|
||||
from langchain.tools import ToolRuntime
|
||||
from langchain_core.messages import AIMessage, HumanMessage, ToolMessage
|
||||
from langchain_core.tools import StructuredTool
|
||||
from langgraph.runtime import Runtime
|
||||
from langgraph.types import Command
|
||||
from pydantic import BaseModel
|
||||
from typing_extensions import TypedDict
|
||||
|
||||
from deerflow.agents.middlewares.model_length_finish_reason_middleware import MODEL_LENGTH_CAPPED_STOP_REASON, MODEL_LENGTH_TERMINATION_MARKER
|
||||
from deerflow.agents.middlewares.safety_finish_reason_middleware import SAFETY_CAPPED_STOP_REASON, SAFETY_TERMINATION_MARKER
|
||||
@ -48,6 +51,41 @@ _COMPLETION_REMINDER_RUN_STOP_REASONS = ("loop_capped", "token_capped")
|
||||
# response was capped.
|
||||
_COMPLETION_REMINDER_RESPONSE_STOP_MARKERS = {SAFETY_CAPPED_STOP_REASON: SAFETY_TERMINATION_MARKER, MODEL_LENGTH_CAPPED_STOP_REASON: MODEL_LENGTH_TERMINATION_MARKER}
|
||||
|
||||
_TODO_TERMINAL_STATUSES = frozenset({"completed", "blocked", "waiting"})
|
||||
_TODO_STATUSES = _TODO_TERMINAL_STATUSES | {"pending", "in_progress"}
|
||||
|
||||
|
||||
class ExtendedTodo(TypedDict):
|
||||
"""A todo item with statuses that describe why work is not progressing."""
|
||||
|
||||
content: str
|
||||
status: Literal["pending", "in_progress", "completed", "blocked", "waiting"]
|
||||
|
||||
|
||||
class ExtendedWriteTodosInput(BaseModel):
|
||||
"""Input schema for the DeerFlow todo tool."""
|
||||
|
||||
todos: list[ExtendedTodo]
|
||||
|
||||
|
||||
def _write_extended_todos(runtime: ToolRuntime, todos: list[ExtendedTodo]) -> Command[Any]:
|
||||
return Command(
|
||||
update={
|
||||
"todos": todos,
|
||||
"messages": [
|
||||
ToolMessage(
|
||||
f"Updated todo list ({len(todos)} items).",
|
||||
tool_call_id=runtime.tool_call_id,
|
||||
additional_kwargs={"ui_hidden": True},
|
||||
)
|
||||
],
|
||||
}
|
||||
)
|
||||
|
||||
|
||||
async def _awrite_extended_todos(runtime: ToolRuntime, todos: list[ExtendedTodo]) -> Command[Any]:
|
||||
return _write_extended_todos(runtime, todos)
|
||||
|
||||
|
||||
def _todos_in_messages(messages: list[Any]) -> bool:
|
||||
"""Return True if any AIMessage in *messages* contains a write_todos tool call."""
|
||||
@ -82,11 +120,16 @@ def _usable_todos(state: ThreadState) -> list[Mapping[str, Any]]:
|
||||
return [todo for todo in todos if isinstance(todo, Mapping)]
|
||||
|
||||
|
||||
def _stored_todo_status(todo: Mapping[str, Any]) -> str:
|
||||
status = todo.get("status")
|
||||
return status if isinstance(status, str) and status in _TODO_STATUSES else "pending"
|
||||
|
||||
|
||||
def _format_todos(todos: Iterable[Mapping[str, Any]]) -> str:
|
||||
"""Format a list of Todo items into a human-readable string."""
|
||||
lines: list[str] = []
|
||||
for todo in todos:
|
||||
status = todo.get("status", "pending")
|
||||
status = _stored_todo_status(todo)
|
||||
content = todo.get("content", "")
|
||||
lines.append(f"- [{status}] {content}")
|
||||
return "\n".join(lines)
|
||||
@ -94,8 +137,7 @@ def _format_todos(todos: Iterable[Mapping[str, Any]]) -> str:
|
||||
|
||||
def _format_completion_reminder(todos: Iterable[Mapping[str, Any]]) -> str:
|
||||
"""Format a completion reminder for incomplete todo items."""
|
||||
incomplete = [t for t in todos if t.get("status") != "completed"]
|
||||
incomplete_text = "\n".join(f"- [{t.get('status', 'pending')}] {t.get('content', '')}" for t in incomplete)
|
||||
incomplete_text = _format_todos(todo for todo in todos if _stored_todo_status(todo) not in _TODO_TERMINAL_STATUSES)
|
||||
return (
|
||||
"<system_reminder>\n"
|
||||
"You have incomplete todo items that must be finished before giving your final response:\n\n"
|
||||
@ -237,6 +279,19 @@ class TodoMiddleware(TodoListMiddleware):
|
||||
|
||||
def __init__(self, *args: Any, **kwargs: Any) -> None:
|
||||
super().__init__(*args, **kwargs)
|
||||
# LangChain's built-in schema only permits three statuses. Replace its
|
||||
# generated tool with the DeerFlow contract so blocked and waiting work
|
||||
# can be persisted without bypassing normal tool validation.
|
||||
self.tools = [
|
||||
StructuredTool.from_function(
|
||||
name="write_todos",
|
||||
description=self.tool_description,
|
||||
func=_write_extended_todos,
|
||||
coroutine=_awrite_extended_todos,
|
||||
args_schema=ExtendedWriteTodosInput,
|
||||
infer_schema=False,
|
||||
)
|
||||
]
|
||||
self._lock = threading.Lock()
|
||||
self._pending_completion_reminders: dict[tuple[str, str], list[str]] = {}
|
||||
self._completion_reminder_counts: dict[tuple[str, str], int] = {}
|
||||
@ -395,9 +450,11 @@ class TodoMiddleware(TodoListMiddleware):
|
||||
if termination_metadata.get("deerflow_error_fallback"):
|
||||
return None
|
||||
|
||||
# 3. Allow exit when all todos are completed or there are no todos.
|
||||
# 3. Allow exit when every todo has reached a terminal state. Blocked
|
||||
# and waiting items explain why the work cannot continue in this run;
|
||||
# they must not be relabeled as completed just to satisfy the guard.
|
||||
todos = _usable_todos(state)
|
||||
if not todos or all(t.get("status") == "completed" for t in todos):
|
||||
if not todos or all(_stored_todo_status(todo) in _TODO_TERMINAL_STATUSES for todo in todos):
|
||||
return None
|
||||
|
||||
# 4. Enforce a reminder cap to prevent infinite re-engagement loops.
|
||||
|
||||
@ -42,7 +42,7 @@ def _normalize_todos(value: Any) -> list[Todo]:
|
||||
|
||||
if content is not None:
|
||||
todo["content"] = content
|
||||
if isinstance(status, str) and status in {"pending", "in_progress", "completed"}:
|
||||
if isinstance(status, str) and status in {"pending", "in_progress", "completed", "blocked", "waiting"}:
|
||||
todo["status"] = status
|
||||
|
||||
normalized.append(todo)
|
||||
|
||||
@ -31,8 +31,10 @@ Division of labor with LoopDetectionMiddleware (middleware position 23):
|
||||
|
||||
LoopDetectionMiddleware is a call-pattern guard — it fires after the model
|
||||
responds (before tools execute), inspects the tool_calls signature in the
|
||||
AIMessage, and forces the *whole turn* to stop when the model keeps issuing
|
||||
the same calls regardless of results.
|
||||
AIMessage alongside completed results, and can force the *whole turn* to stop
|
||||
when the model repeats calls with unchanged outcomes (call+result fingerprint
|
||||
repetition). Per-tool frequency thresholds are INFO-only observability metrics
|
||||
and do not warn or hard-stop execution.
|
||||
|
||||
They are complementary, not competing:
|
||||
- ToolProgressMiddleware is fine-grained (per-tool BLOCK, other tools normal).
|
||||
|
||||
@ -8,9 +8,9 @@ from deerflow.config._boolean_guards import reject_boolean
|
||||
class ToolFreqOverride(BaseModel):
|
||||
"""Per-tool frequency threshold override.
|
||||
|
||||
Can be higher or lower than the global defaults. Commonly used to raise
|
||||
thresholds for high-frequency tools like bash in batch workflows (e.g.
|
||||
RNA-seq pipelines) without weakening protection on every other tool.
|
||||
Can be higher or lower than the global observability thresholds. Commonly
|
||||
used to tune reporting for high-frequency tools like bash in batch workflows
|
||||
without changing loop protection on every other tool.
|
||||
"""
|
||||
|
||||
warn: int = Field(ge=1)
|
||||
@ -58,16 +58,16 @@ class LoopDetectionConfig(BaseModel):
|
||||
tool_freq_warn: int = Field(
|
||||
default=30,
|
||||
ge=1,
|
||||
description="Number of calls to the same tool type before injecting a frequency warning",
|
||||
description="Number of same-tool calls in the observation window before recording a frequency metric",
|
||||
)
|
||||
tool_freq_hard_limit: int = Field(
|
||||
default=50,
|
||||
ge=1,
|
||||
description="Number of calls to the same tool type before forcing a stop",
|
||||
description="Second same-tool frequency metric threshold; it does not stop the run",
|
||||
)
|
||||
tool_freq_overrides: dict[str, ToolFreqOverride] = Field(
|
||||
default_factory=dict,
|
||||
description=("Per-tool overrides for tool_freq_warn / tool_freq_hard_limit, keyed by tool name. Values can be higher or lower than the global defaults. Commonly used to raise thresholds for high-frequency tools like bash."),
|
||||
description=("Per-tool observability thresholds for tool_freq_warn / tool_freq_hard_limit, keyed by tool name."),
|
||||
)
|
||||
|
||||
@field_validator(
|
||||
@ -85,7 +85,7 @@ class LoopDetectionConfig(BaseModel):
|
||||
|
||||
@model_validator(mode="after")
|
||||
def validate_thresholds(self) -> "LoopDetectionConfig":
|
||||
"""Ensure hard stop cannot happen before the warning threshold."""
|
||||
"""Keep thresholds ordered for predictable metric reporting."""
|
||||
if self.hard_limit < self.warn_threshold:
|
||||
raise ValueError("hard_limit must be greater than or equal to warn_threshold")
|
||||
if self.tool_freq_hard_limit < self.tool_freq_warn:
|
||||
|
||||
@ -75,7 +75,7 @@ def snapshot_run_status(state: Mapping[str, Any], context: Mapping[str, Any], *,
|
||||
}
|
||||
|
||||
todos = state.get("todos")
|
||||
pending = in_progress = 0
|
||||
pending = in_progress = blocked = waiting = 0
|
||||
if isinstance(todos, list):
|
||||
for item in todos:
|
||||
if not isinstance(item, Mapping):
|
||||
@ -84,6 +84,10 @@ def snapshot_run_status(state: Mapping[str, Any], context: Mapping[str, Any], *,
|
||||
pending += 1
|
||||
elif item.get("status") == "in_progress":
|
||||
in_progress += 1
|
||||
elif item.get("status") == "blocked":
|
||||
blocked += 1
|
||||
elif item.get("status") == "waiting":
|
||||
waiting += 1
|
||||
summary = state.get("summary_text")
|
||||
return {
|
||||
"scope": scope,
|
||||
@ -93,7 +97,7 @@ def snapshot_run_status(state: Mapping[str, Any], context: Mapping[str, Any], *,
|
||||
"tool_calls_this_run": tool_calls if scope == "current_run_visible" else None,
|
||||
"context_fill": fill,
|
||||
"has_summary": isinstance(summary, str) and bool(summary.strip()),
|
||||
"todos": {"pending": pending, "in_progress": in_progress},
|
||||
"todos": {"pending": pending, "in_progress": in_progress, "blocked": blocked, "waiting": waiting},
|
||||
}
|
||||
|
||||
|
||||
|
||||
@ -23,7 +23,13 @@ def test_snapshot_counts_only_the_current_run_and_uses_reported_usage():
|
||||
state = {
|
||||
"messages": [old, current, call, result, final],
|
||||
"summary_text": "private summary",
|
||||
"todos": [{"content": "private todo", "status": "pending"}, {"content": "another", "status": "in_progress"}, {"content": "done", "status": "completed"}],
|
||||
"todos": [
|
||||
{"content": "private todo", "status": "pending"},
|
||||
{"content": "another", "status": "in_progress"},
|
||||
{"content": "blocked", "status": "blocked"},
|
||||
{"content": "waiting", "status": "waiting"},
|
||||
{"content": "done", "status": "completed"},
|
||||
],
|
||||
}
|
||||
context = {CURRENT_RUN_PRE_EXISTING_MESSAGE_IDS_KEY: frozenset({"old"})}
|
||||
|
||||
@ -35,7 +41,7 @@ def test_snapshot_counts_only_the_current_run_and_uses_reported_usage():
|
||||
assert snapshot["tool_calls_this_run"] == 1
|
||||
assert snapshot["context_fill"] == {"used_input_tokens": 80, "limit_tokens": 200, "fraction": 0.4, "basis": "last_reported_model_input"}
|
||||
assert snapshot["has_summary"] is True
|
||||
assert snapshot["todos"] == {"pending": 1, "in_progress": 1}
|
||||
assert snapshot["todos"] == {"pending": 1, "in_progress": 1, "blocked": 1, "waiting": 1}
|
||||
serialized = json.dumps(snapshot)
|
||||
assert "private" not in serialized
|
||||
assert "echo secret" not in serialized
|
||||
@ -52,7 +58,7 @@ def test_snapshot_marks_missing_boundary_and_usage_as_unknown():
|
||||
assert snapshot["usage_missing_messages"] == 2
|
||||
assert snapshot["context_fill"] is None
|
||||
assert snapshot["has_summary"] is False
|
||||
assert snapshot["todos"] == {"pending": 0, "in_progress": 0}
|
||||
assert snapshot["todos"] == {"pending": 0, "in_progress": 0, "blocked": 0, "waiting": 0}
|
||||
|
||||
|
||||
def test_compaction_that_removes_run_boundary_reports_visible_state():
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
386
backend/tests/test_loop_detection_result_progress.py
Normal file
386
backend/tests/test_loop_detection_result_progress.py
Normal file
@ -0,0 +1,386 @@
|
||||
"""Result changes distinguish useful repeated calls from stalled tool loops."""
|
||||
|
||||
from pathlib import Path
|
||||
from types import SimpleNamespace
|
||||
from typing import Any
|
||||
|
||||
import pytest
|
||||
from langchain.agents import create_agent
|
||||
from langchain_core.language_models.fake_chat_models import FakeMessagesListChatModel
|
||||
from langchain_core.messages import AIMessage, HumanMessage, ToolMessage
|
||||
from langchain_core.tools import tool
|
||||
from pydantic import PrivateAttr
|
||||
|
||||
from deerflow.agents.middlewares.loop_detection_middleware import LoopDetectionMiddleware
|
||||
from deerflow.agents.middlewares.read_before_write_middleware import READ_MARK_KEY, ReadBeforeWriteMiddleware
|
||||
from deerflow.agents.middlewares.subagent_limit_middleware import SubagentLimitMiddleware
|
||||
|
||||
|
||||
class _ScriptedModel(FakeMessagesListChatModel):
|
||||
_requests: list[list[Any]] = PrivateAttr(default_factory=list)
|
||||
|
||||
def bind_tools(self, tools, **kwargs):
|
||||
return self
|
||||
|
||||
def _generate(self, messages, stop=None, run_manager=None, **kwargs):
|
||||
self._requests.append(list(messages))
|
||||
return super()._generate(messages, stop=stop, run_manager=run_manager, **kwargs)
|
||||
|
||||
|
||||
def _call(name, args, call_id="call_0"):
|
||||
# Providers may reuse the same ID in every response.
|
||||
return {"name": name, "args": args, "id": call_id}
|
||||
|
||||
|
||||
async def _invoke(graph, async_mode, context):
|
||||
state = {"messages": [("user", "Continue until the requested work is complete.")]}
|
||||
if async_mode:
|
||||
return await graph.ainvoke(state, context=context, config={"recursion_limit": 100})
|
||||
return graph.invoke(state, context=context, config={"recursion_limit": 100})
|
||||
|
||||
|
||||
def _warnings(model):
|
||||
return [message for messages in model._requests for message in messages if isinstance(message, HumanMessage) and message.name == "loop_warning"]
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
@pytest.mark.parametrize("async_mode", [False, True])
|
||||
@pytest.mark.parametrize("ranged_read", [False, True])
|
||||
async def test_read_modify_reread_keeps_making_progress(tmp_path, async_mode, ranged_read):
|
||||
report = tmp_path / "report.md"
|
||||
report.write_text("Report\nv1\n", encoding="utf-8", newline="\n")
|
||||
edits = []
|
||||
|
||||
@tool
|
||||
def read_file(path: str, start_line: int = 1, end_line: int | None = None) -> str:
|
||||
"""Read the requested lines of the temporary report."""
|
||||
return "".join(Path(path).read_text(encoding="utf-8").splitlines(keepends=True)[start_line - 1 : end_line])
|
||||
|
||||
@tool
|
||||
def str_replace(path: str, old_str: str, new_str: str) -> str:
|
||||
"""Apply one edit to the temporary report."""
|
||||
target = Path(path)
|
||||
content = target.read_text(encoding="utf-8")
|
||||
assert old_str in content
|
||||
target.write_text(content.replace(old_str, new_str), encoding="utf-8", newline="\n")
|
||||
edits.append(new_str)
|
||||
return "Successfully replaced the requested text."
|
||||
|
||||
responses = []
|
||||
for version in range(1, 7):
|
||||
read_args = {"path": str(report), **({"start_line": 1, "end_line": 1} if ranged_read else {})}
|
||||
responses.append(AIMessage(content="", tool_calls=[_call("read_file", read_args)]))
|
||||
responses.append(AIMessage(content="", tool_calls=[_call("str_replace", {"path": str(report), "old_str": f"v{version}", "new_str": f"v{version + 1}"})]))
|
||||
responses.append(AIMessage(content="Done."))
|
||||
model = _ScriptedModel(responses=responses)
|
||||
loop = LoopDetectionMiddleware()
|
||||
gate = ReadBeforeWriteMiddleware(content_reader=lambda _runtime, path: Path(path).read_text(encoding="utf-8"))
|
||||
graph = create_agent(model=model, tools=[read_file, str_replace], middleware=[gate, loop])
|
||||
context = {"thread_id": "editing", "run_id": "editing"}
|
||||
|
||||
result = await _invoke(graph, async_mode, context)
|
||||
|
||||
assert edits == [f"v{version}" for version in range(2, 8)]
|
||||
assert report.read_text(encoding="utf-8") == "Report\nv7\n"
|
||||
tool_results = [message for message in result["messages"] if isinstance(message, ToolMessage)]
|
||||
reads = [message for message in tool_results if message.name == "read_file"]
|
||||
assert len({message.additional_kwargs[READ_MARK_KEY]["hash"] for message in reads}) == 6
|
||||
if ranged_read:
|
||||
# The visible first line stays identical; the full-file version changes.
|
||||
assert {message.content for message in reads} == {"Report\n"}
|
||||
assert all(message.status == "success" for message in tool_results)
|
||||
assert result["messages"][-1].content == "Done."
|
||||
assert not _warnings(model)
|
||||
assert context.get("stop_reason") is None
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
@pytest.mark.parametrize("async_mode", [False, True])
|
||||
@pytest.mark.parametrize("edit_result", ["same_file", "other_file", "failed"])
|
||||
async def test_reread_near_limit_after_file_edit(tmp_path, async_mode, edit_result):
|
||||
report = tmp_path / "report.md"
|
||||
other = tmp_path / "other.md"
|
||||
report.write_text("v1", encoding="utf-8")
|
||||
reads = []
|
||||
|
||||
@tool
|
||||
def read_file(path: str) -> str:
|
||||
"""Read the report."""
|
||||
content = Path(path).read_text(encoding="utf-8")
|
||||
reads.append(content)
|
||||
return content
|
||||
|
||||
@tool
|
||||
def str_replace(path: str) -> ToolMessage:
|
||||
"""Apply a test edit."""
|
||||
if edit_result == "failed":
|
||||
return ToolMessage(content="Edit failed", status="error", tool_call_id="call_0")
|
||||
Path(path).write_text("v2", encoding="utf-8")
|
||||
return ToolMessage(content="Edited", tool_call_id="call_0")
|
||||
|
||||
read = _call("read_file", {"path": str(report)})
|
||||
edit = _call("str_replace", {"path": str(other if edit_result == "other_file" else report)})
|
||||
responses = [AIMessage(content="", tool_calls=[call]) for call in [read, read, read, read, edit, read]]
|
||||
model = _ScriptedModel(responses=[*responses, AIMessage(content="Done.")])
|
||||
graph = create_agent(model=model, tools=[read_file, str_replace], middleware=[LoopDetectionMiddleware()])
|
||||
context = {"thread_id": "edit-at-limit", "run_id": "edit-at-limit"}
|
||||
result = await _invoke(graph, async_mode, context)
|
||||
|
||||
if edit_result == "same_file":
|
||||
assert reads == ["v1"] * 4 + ["v2"]
|
||||
assert result["messages"][-1].content == "Done."
|
||||
assert context.get("stop_reason") is None
|
||||
else:
|
||||
assert reads == ["v1"] * 4
|
||||
assert context["stop_reason"] == "loop_capped"
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
@pytest.mark.parametrize("async_mode", [False, True])
|
||||
async def test_trimmed_delegations_preserve_progress_in_admitted_batch(async_mode):
|
||||
from deerflow.agents.lead_agent.agent import build_middlewares
|
||||
from deerflow.config.app_config import AppConfig
|
||||
from deerflow.config.sandbox_config import SandboxConfig
|
||||
|
||||
observed = []
|
||||
delegated = []
|
||||
|
||||
@tool
|
||||
def inspect_job() -> str:
|
||||
"""Return the next observed job state."""
|
||||
observed.append(len(observed) + 1)
|
||||
return str(observed[-1])
|
||||
|
||||
@tool
|
||||
def task(description: str) -> str:
|
||||
"""Record the admitted delegation."""
|
||||
delegated.append(description)
|
||||
return "Done."
|
||||
|
||||
config = {"configurable": {"subagent_enabled": True, "max_concurrent_subagents": 1}}
|
||||
app_config = AppConfig(sandbox=SandboxConfig(use="deerflow.sandbox.local:LocalSandboxProvider"))
|
||||
chain = build_middlewares(config, model_name=None, app_config=app_config, memory_enabled=False, available_skills=set())
|
||||
middlewares = [mw for mw in chain if isinstance(mw, (LoopDetectionMiddleware, SubagentLimitMiddleware))]
|
||||
calls = [
|
||||
_call("inspect_job", {}),
|
||||
_call("task", {"description": "admitted"}, "task-1"),
|
||||
_call("task", {"description": "trimmed"}, "task-2"),
|
||||
]
|
||||
model = _ScriptedModel(responses=[AIMessage(content="", tool_calls=calls) for _ in range(6)] + [AIMessage(content="Done.")])
|
||||
graph = create_agent(model=model, tools=[inspect_job, task], middleware=middlewares)
|
||||
context = {"thread_id": "admitted-batch", "run_id": "admitted-batch"}
|
||||
result = await _invoke(graph, async_mode, context)
|
||||
|
||||
assert observed == list(range(1, 7))
|
||||
assert delegated == ["admitted"] * 6
|
||||
assert result["messages"][-1].content == "Done."
|
||||
assert context.get("stop_reason") is None
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
@pytest.mark.parametrize("async_mode", [False, True])
|
||||
@pytest.mark.parametrize("batched", [False, True])
|
||||
async def test_changing_results_work_for_arbitrary_tools(async_mode, batched):
|
||||
observations = []
|
||||
|
||||
@tool
|
||||
def inspect_job(job: str) -> list[dict]:
|
||||
"""Return the next observed job state."""
|
||||
observations.append(len(observations) + 1)
|
||||
return [{"type": "text", "text": f"Completed {observations[-1]} steps"}]
|
||||
|
||||
@tool
|
||||
def lookup_owner(job: str) -> str:
|
||||
"""Return the stable owner of the job."""
|
||||
return "owner"
|
||||
|
||||
responses = []
|
||||
for index in range(6):
|
||||
calls = [_call("inspect_job", {"job": "demo"})]
|
||||
if batched:
|
||||
calls.append(_call("lookup_owner", {"job": "demo"}, "call_1"))
|
||||
if index % 2:
|
||||
calls.reverse()
|
||||
responses.append(AIMessage(content="", tool_calls=calls))
|
||||
responses.append(AIMessage(content="Done."))
|
||||
model = _ScriptedModel(responses=responses)
|
||||
loop = LoopDetectionMiddleware()
|
||||
graph = create_agent(model=model, tools=[inspect_job, lookup_owner], middleware=[loop])
|
||||
|
||||
result = await _invoke(graph, async_mode, {"thread_id": "jobs", "run_id": "jobs"})
|
||||
|
||||
assert observations == list(range(1, 7))
|
||||
assert result["messages"][-1].content == "Done."
|
||||
assert not _warnings(model)
|
||||
assert loop.consume_stop_reason("jobs") is None
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
@pytest.mark.parametrize("async_mode", [False, True])
|
||||
@pytest.mark.parametrize("failure", [None, "native", "metadata"])
|
||||
async def test_unchanged_results_and_changing_errors_still_stop(async_mode, failure):
|
||||
executions = []
|
||||
|
||||
@tool
|
||||
def inspect_job(job: str) -> ToolMessage:
|
||||
"""Inspect the same stalled job through the tool boundary."""
|
||||
executions.append(len(executions) + 1)
|
||||
metadata = {"receipt": {"id": len(executions)}}
|
||||
if failure == "metadata":
|
||||
metadata["deerflow_tool_meta"] = {"status": "error", "error_type": "transient"}
|
||||
return ToolMessage(
|
||||
content=f"Attempt {executions[-1]} failed" if failure else "No change",
|
||||
status="error" if failure == "native" else "success",
|
||||
additional_kwargs=metadata,
|
||||
tool_call_id="call_0",
|
||||
)
|
||||
|
||||
model = _ScriptedModel(responses=[AIMessage(content="", tool_calls=[_call("inspect_job", {"job": "demo"})]) for _ in range(6)])
|
||||
loop = LoopDetectionMiddleware()
|
||||
graph = create_agent(model=model, tools=[inspect_job], middleware=[loop])
|
||||
context = {"thread_id": "stalled", "run_id": "stalled"}
|
||||
|
||||
result = await _invoke(graph, async_mode, context)
|
||||
|
||||
assert len(executions) == 4
|
||||
assert len(model._requests) == 5
|
||||
assert len(_warnings(model)) == 1
|
||||
assert not result["messages"][-1].tool_calls
|
||||
assert context["stop_reason"] == "loop_capped"
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_repeated_result_cycle_still_stops():
|
||||
executions = []
|
||||
|
||||
@tool
|
||||
def inspect_job(job: str) -> str:
|
||||
"""Observe a job oscillating between two states."""
|
||||
executions.append(len(executions) % 2)
|
||||
return str(executions[-1])
|
||||
|
||||
model = _ScriptedModel(responses=[AIMessage(content="", tool_calls=[_call("inspect_job", {"job": "demo"})]) for _ in range(12)])
|
||||
graph = create_agent(model=model, tools=[inspect_job], middleware=[LoopDetectionMiddleware()])
|
||||
context = {"thread_id": "cycling", "run_id": "cycling"}
|
||||
|
||||
await _invoke(graph, True, context)
|
||||
|
||||
# Four observed zeroes plus the next predicted zero reach the hard limit.
|
||||
assert executions == [0, 1, 0, 1, 0, 1, 0]
|
||||
assert context["stop_reason"] == "loop_capped"
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_changing_results_are_not_stopped_by_tool_frequency_metrics():
|
||||
executions = []
|
||||
|
||||
@tool
|
||||
def inspect_job(job: str) -> str:
|
||||
"""Observe a job that always returns a new state."""
|
||||
executions.append(len(executions))
|
||||
return str(executions[-1])
|
||||
|
||||
model = _ScriptedModel(responses=[AIMessage(content="", tool_calls=[_call("inspect_job", {"job": "demo"})]) for _ in range(8)] + [AIMessage(content="Done.")])
|
||||
loop = LoopDetectionMiddleware(tool_freq_warn=4, tool_freq_hard_limit=6)
|
||||
graph = create_agent(model=model, tools=[inspect_job], middleware=[loop])
|
||||
context = {"thread_id": "budget", "run_id": "budget"}
|
||||
|
||||
result = await _invoke(graph, True, context)
|
||||
|
||||
assert len(executions) == 8
|
||||
assert result["messages"][-1].content == "Done."
|
||||
assert not _warnings(model)
|
||||
assert context.get("stop_reason") is None
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_noop_writes_still_hit_the_loop_limit(tmp_path):
|
||||
report = tmp_path / "report.md"
|
||||
report.write_text("unchanged", encoding="utf-8", newline="\n")
|
||||
reads, writes = [], []
|
||||
|
||||
@tool
|
||||
def read_file(path: str) -> str:
|
||||
"""Read the temporary report."""
|
||||
reads.append(path)
|
||||
return Path(path).read_text(encoding="utf-8")
|
||||
|
||||
@tool
|
||||
def write_file(path: str, content: str) -> str:
|
||||
"""Write the same report contents."""
|
||||
writes.append(path)
|
||||
Path(path).write_text(content, encoding="utf-8", newline="\n")
|
||||
return "Saved."
|
||||
|
||||
calls = [AIMessage(content="", tool_calls=[_call(name, args)]) for _ in range(6) for name, args in [("read_file", {"path": str(report)}), ("write_file", {"path": str(report), "content": "unchanged"})]]
|
||||
model = _ScriptedModel(responses=calls)
|
||||
loop = LoopDetectionMiddleware()
|
||||
gate = ReadBeforeWriteMiddleware(content_reader=lambda _runtime, path: Path(path).read_text(encoding="utf-8"))
|
||||
graph = create_agent(model=model, tools=[read_file, write_file], middleware=[gate, loop])
|
||||
context = {"thread_id": "noop", "run_id": "noop"}
|
||||
|
||||
await _invoke(graph, True, context)
|
||||
|
||||
# The last successful write warrants one more read. Its result settles to
|
||||
# the old version, and the unchanged write loop still reaches the cap.
|
||||
assert len(reads) == 5
|
||||
assert len(writes) == 4
|
||||
assert report.read_text(encoding="utf-8") == "unchanged"
|
||||
assert context["stop_reason"] == "loop_capped"
|
||||
|
||||
|
||||
def _runtime():
|
||||
return SimpleNamespace(context={"thread_id": "history", "run_id": "history"})
|
||||
|
||||
|
||||
@pytest.mark.parametrize("metadata", [None, [], {"deerflow_tool_meta": ["error"]}, {READ_MARK_KEY: {"path": [], "hash": {}}}, {READ_MARK_KEY: {"path": "/report", "hash": "not-a-digest"}}])
|
||||
def test_malformed_persisted_metadata_cannot_disable_loop_protection(metadata):
|
||||
loop = LoopDetectionMiddleware()
|
||||
messages = []
|
||||
for index in range(5):
|
||||
messages.append(AIMessage(id=f"turn-{index}", content="", tool_calls=[_call("inspect_job", {})]))
|
||||
update = loop.after_model({"messages": messages}, _runtime())
|
||||
if index < 4:
|
||||
result = ToolMessage(content="unchanged", tool_call_id="call_0").model_copy(update={"additional_kwargs": metadata})
|
||||
messages.append(result)
|
||||
|
||||
assert not update["messages"][0].tool_calls
|
||||
assert loop.consume_stop_reason("history") == "loop_capped"
|
||||
|
||||
|
||||
@pytest.mark.parametrize("malformation", ["missing", "duplicate_id", "unserializable"])
|
||||
def test_incomplete_batches_do_not_borrow_results_from_reused_call_ids(malformation):
|
||||
loop = LoopDetectionMiddleware()
|
||||
messages = []
|
||||
for index in range(5):
|
||||
calls = [_call("inspect_job", {}), _call("lookup_owner", {}, "call_0" if malformation == "duplicate_id" else "call_1")]
|
||||
messages.append(AIMessage(id=f"turn-{index}", content="", tool_calls=calls))
|
||||
update = loop.after_model({"messages": messages}, _runtime())
|
||||
if index < 4:
|
||||
messages.append(ToolMessage(content=f"state {index}", tool_call_id="call_0"))
|
||||
if malformation != "missing":
|
||||
result = ToolMessage(content="owner", tool_call_id=calls[1]["id"])
|
||||
if malformation == "unserializable":
|
||||
cyclic = []
|
||||
cyclic.append(cyclic)
|
||||
result = result.model_copy(update={"content": cyclic})
|
||||
messages.append(result)
|
||||
|
||||
assert not update["messages"][0].tool_calls
|
||||
assert loop.consume_stop_reason("history") == "loop_capped"
|
||||
|
||||
|
||||
def test_compacted_history_cannot_settle_a_different_call_occurrence():
|
||||
loop = LoopDetectionMiddleware(hard_limit=3)
|
||||
call = _call("inspect_job", {})
|
||||
latest = AIMessage(id="current", content="", tool_calls=[call])
|
||||
loop.after_model({"messages": [latest]}, _runtime())
|
||||
for index in range(2):
|
||||
# A stale checkpoint retains the same call ID, but a different AIMessage.
|
||||
stale = AIMessage(id="old", content="", tool_calls=[call])
|
||||
result = ToolMessage(content=f"old state {index}", tool_call_id="call_0")
|
||||
latest = AIMessage(id=f"next-{index}", content="", tool_calls=[call])
|
||||
update = loop.after_model({"messages": [stale, result, latest]}, _runtime())
|
||||
|
||||
assert not update["messages"][0].tool_calls
|
||||
assert loop.consume_stop_reason("history") == "loop_capped"
|
||||
@ -124,6 +124,16 @@ def _make_loop_detection_middleware():
|
||||
return LoopDetectionMiddleware()
|
||||
|
||||
|
||||
def test_loop_result_aware_policy_changes_release_identity():
|
||||
policies = collect_release_policies([_make_loop_detection_middleware()])
|
||||
parameters = policies["LoopDetectionMiddleware"]
|
||||
assert parameters["repetition_key"] == "call_and_result_v1"
|
||||
assert parameters["read_prediction"] == "refresh_after_successful_write"
|
||||
assert parameters["frequency_action"] == "observe_only"
|
||||
legacy = {"LoopDetectionMiddleware": {key: value for key, value in parameters.items() if key != "repetition_key"}}
|
||||
assert canonical_hash(policies) != canonical_hash(legacy)
|
||||
|
||||
|
||||
def _make_subagent_limit_middleware():
|
||||
from deerflow.agents.middlewares.subagent_limit_middleware import SubagentLimitMiddleware
|
||||
|
||||
|
||||
@ -35,7 +35,12 @@ def test_external_todos_must_be_renderable(boundary, todos):
|
||||
|
||||
@pytest.mark.parametrize("boundary", BOUNDARIES)
|
||||
def test_external_todos_accept_the_write_todos_shape(boundary):
|
||||
todos = [{"content": "Ship it", "status": "in_progress"}, {"content": "", "status": "pending"}]
|
||||
todos = [
|
||||
{"content": "Ship it", "status": "in_progress"},
|
||||
{"content": "Unblock dependency", "status": "blocked"},
|
||||
{"content": "Wait for approval", "status": "waiting"},
|
||||
{"content": "", "status": "pending"},
|
||||
]
|
||||
assert boundary({"todos": todos})["todos"] == todos
|
||||
|
||||
|
||||
|
||||
@ -24,6 +24,7 @@ from deerflow.agents.middlewares.safety_finish_reason_middleware import SafetyFi
|
||||
from deerflow.agents.middlewares.todo_middleware import (
|
||||
TODO_REMINDER_MESSAGE_NAME,
|
||||
TodoMiddleware,
|
||||
_format_completion_reminder,
|
||||
_format_todos,
|
||||
_has_tool_call_intent_or_error,
|
||||
_reminder_in_messages,
|
||||
@ -138,10 +139,10 @@ class TestFormatTodos:
|
||||
assert _format_todos([]) == ""
|
||||
|
||||
def test_missing_fields_use_defaults(self):
|
||||
todos = [{"content": "No status"}, {"status": "done"}]
|
||||
todos = [{"content": "No status"}, {"status": "completed"}]
|
||||
result = _format_todos(todos)
|
||||
assert "- [pending] No status" in result
|
||||
assert "- [done] " in result
|
||||
assert "- [completed] " in result
|
||||
|
||||
|
||||
class TestBeforeModel:
|
||||
@ -449,6 +450,39 @@ class TestAfterModel:
|
||||
}
|
||||
assert mw.after_model(state, _make_runtime()) is None
|
||||
|
||||
@pytest.mark.parametrize("status", ["blocked", "waiting"])
|
||||
def test_returns_none_when_todos_are_terminal_for_this_run(self, status):
|
||||
mw = TodoMiddleware()
|
||||
state = {
|
||||
"messages": [_ai_no_tool_calls()],
|
||||
"todos": [{"status": status, "content": "Cannot continue here"}],
|
||||
}
|
||||
assert mw.after_model(state, _make_runtime()) is None
|
||||
|
||||
def test_reminder_skips_blocked_and_waiting_items(self):
|
||||
mw = TodoMiddleware()
|
||||
runtime = _make_runtime()
|
||||
state = {
|
||||
"messages": [_ai_no_tool_calls()],
|
||||
"todos": [
|
||||
{"status": "blocked", "content": "Blocked dependency"},
|
||||
{"status": "waiting", "content": "User approval"},
|
||||
{"status": "pending", "content": "Continue implementation"},
|
||||
],
|
||||
}
|
||||
|
||||
assert mw.after_model(state, runtime) == {"jump_to": "model"}
|
||||
seen: list[ModelRequest] = []
|
||||
mw.wrap_model_call(
|
||||
_make_model_request(state["messages"], runtime=runtime),
|
||||
lambda request: seen.append(request) or "response",
|
||||
)
|
||||
|
||||
reminder = seen[0].messages[-1].content
|
||||
assert "Blocked dependency" not in reminder
|
||||
assert "User approval" not in reminder
|
||||
assert "Continue implementation" in reminder
|
||||
|
||||
def test_returns_none_when_no_messages(self):
|
||||
mw = TodoMiddleware()
|
||||
state = {
|
||||
@ -1277,6 +1311,16 @@ class TestMalformedStoredTodos:
|
||||
state = {"messages": [AIMessage(content="final")], "todos": [{"content": "Done", "status": "completed"}, "junk"]}
|
||||
assert mw.after_model(state, _make_runtime()) is None
|
||||
|
||||
@pytest.mark.parametrize("status", [[], {}, None, "unknown"])
|
||||
def test_invalid_stored_status_remains_pending(self, status):
|
||||
todos = [{"content": "Recover me", "status": status}, {"content": "Finished", "status": "completed"}]
|
||||
mw = TodoMiddleware()
|
||||
assert mw.after_model({"messages": [AIMessage(content="final")], "todos": todos}, _make_runtime()) == {"jump_to": "model"}
|
||||
assert "- [pending] Recover me" in _format_todos(todos)
|
||||
reminder = _format_completion_reminder(todos)
|
||||
assert "- [pending] Recover me" in reminder
|
||||
assert "Finished" not in reminder
|
||||
|
||||
@pytest.mark.parametrize("todos", [{"content": "x"}, "oops", 5])
|
||||
def test_todos_that_are_not_a_list_allow_a_clean_exit(self, todos):
|
||||
mw = TodoMiddleware()
|
||||
|
||||
@ -415,7 +415,19 @@ class TestBuildTodoActions:
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
"status, expected_status",
|
||||
[("pending", "pending"), ("in_progress", "in_progress"), ("completed", "completed"), ("unknown", None), (None, None), (True, None), (1, None), ([], None), ({}, None)],
|
||||
[
|
||||
("pending", "pending"),
|
||||
("in_progress", "in_progress"),
|
||||
("completed", "completed"),
|
||||
("blocked", "blocked"),
|
||||
("waiting", "waiting"),
|
||||
("unknown", None),
|
||||
(None, None),
|
||||
(True, None),
|
||||
(1, None),
|
||||
([], None),
|
||||
({}, None),
|
||||
],
|
||||
)
|
||||
def test_normalize_todos_only_keeps_valid_string_statuses(status, expected_status):
|
||||
todo = {"content": "Example task", "status": status}
|
||||
@ -433,7 +445,7 @@ class _ToolCallingModel(FakeMessagesListChatModel):
|
||||
|
||||
@pytest.mark.asyncio
|
||||
@pytest.mark.parametrize("use_async", [False, True], ids=["sync", "async"])
|
||||
@pytest.mark.parametrize("status", [[], {}, "unknown", "completed"], ids=["list", "dict", "unknown-string", "valid"])
|
||||
@pytest.mark.parametrize("status", [[], {}, "unknown", "completed", "blocked", "waiting"], ids=["list", "dict", "unknown-string", "completed", "blocked", "waiting"])
|
||||
async def test_todo_validation_remains_recoverable_with_token_attribution(status, use_async):
|
||||
"""Attribution runs before ToolNode validates model-generated TODO arguments."""
|
||||
todo = {"content": "Example task", "status": status}
|
||||
@ -452,7 +464,7 @@ async def test_todo_validation_remains_recoverable_with_token_attribution(status
|
||||
tool_messages = [message for message in result["messages"] if isinstance(message, ToolMessage)]
|
||||
assert len(tool_messages) == 1
|
||||
assert tool_messages[0].tool_call_id == "todo-call"
|
||||
if status == "completed":
|
||||
if isinstance(status, str) and status in {"completed", "blocked", "waiting"}:
|
||||
assert tool_messages[0].status == "success"
|
||||
assert result["todos"] == [todo]
|
||||
else:
|
||||
|
||||
@ -1531,7 +1531,9 @@ input_polish:
|
||||
# Loop Detection Configuration
|
||||
# ============================================================================
|
||||
# Detect and interrupt repeated identical tool-call loops.
|
||||
# Frequency thresholds are safety limits for repeated use of the same tool type.
|
||||
# Frequency thresholds are windowed observability metrics for repeated use of a
|
||||
# tool type. They log burst counts and never stop a run; use token, time, call,
|
||||
# or cost budgets when work needs a hard ceiling.
|
||||
|
||||
loop_detection:
|
||||
enabled: true
|
||||
@ -1542,10 +1544,8 @@ loop_detection:
|
||||
max_tracked_threads: 100
|
||||
tool_freq_warn: 30
|
||||
tool_freq_hard_limit: 50
|
||||
# Per-tool overrides for tool_freq_warn / tool_freq_hard_limit. Values can be
|
||||
# higher or lower than the global defaults. Commonly used to raise thresholds
|
||||
# for high-frequency tools like bash in batch workflows (e.g. RNA-seq pipelines)
|
||||
# without weakening protection on every other tool.
|
||||
# Per-tool overrides for the two frequency metrics. Values can be higher or
|
||||
# lower than the global thresholds for tools with different normal workloads.
|
||||
# tool_freq_overrides:
|
||||
# bash:
|
||||
# warn: 150
|
||||
|
||||
@ -27,6 +27,7 @@ export function TodoList({
|
||||
const [internalCollapsed, setInternalCollapsed] = useState(true);
|
||||
const isControlled = controlledCollapsed !== undefined;
|
||||
const collapsed = isControlled ? controlledCollapsed : internalCollapsed;
|
||||
const occurrencesByContent = new Map<string, number>();
|
||||
|
||||
const handleToggle = () => {
|
||||
if (isControlled) {
|
||||
@ -72,26 +73,40 @@ export function TodoList({
|
||||
)}
|
||||
>
|
||||
<QueueList className="bg-background mt-0 w-full rounded-t-xl">
|
||||
{todos.map((todo, i) => (
|
||||
<QueueItem key={i + (todo.content ?? "")}>
|
||||
<div className="flex items-center gap-2">
|
||||
<QueueItemIndicator
|
||||
className={
|
||||
todo.status === "in_progress" ? "bg-primary/70" : ""
|
||||
}
|
||||
completed={todo.status === "completed"}
|
||||
/>
|
||||
<QueueItemContent
|
||||
className={
|
||||
todo.status === "in_progress" ? "text-primary/70" : ""
|
||||
}
|
||||
completed={todo.status === "completed"}
|
||||
>
|
||||
{todo.content}
|
||||
</QueueItemContent>
|
||||
</div>
|
||||
</QueueItem>
|
||||
))}
|
||||
{todos.map((todo) => {
|
||||
const content = todo.content ?? "";
|
||||
const occurrence = occurrencesByContent.get(content) ?? 0;
|
||||
occurrencesByContent.set(content, occurrence + 1);
|
||||
const status = todo.status ?? "pending";
|
||||
return (
|
||||
<QueueItem key={JSON.stringify([content, occurrence])}>
|
||||
<div className="flex items-center gap-2">
|
||||
<QueueItemIndicator
|
||||
aria-label={`Todo status: ${status}`}
|
||||
className={cn(
|
||||
status === "in_progress" && "bg-primary/70",
|
||||
status === "blocked" &&
|
||||
"border-destructive/70 bg-destructive/15",
|
||||
status === "waiting" &&
|
||||
"border-muted-foreground/70 bg-muted",
|
||||
)}
|
||||
completed={status === "completed"}
|
||||
title={`Todo status: ${status}`}
|
||||
/>
|
||||
<QueueItemContent
|
||||
className={cn(
|
||||
status === "in_progress" && "text-primary/70",
|
||||
status === "blocked" && "text-destructive",
|
||||
status === "waiting" && "text-muted-foreground italic",
|
||||
)}
|
||||
completed={status === "completed"}
|
||||
>
|
||||
{todo.content}
|
||||
</QueueItemContent>
|
||||
</div>
|
||||
</QueueItem>
|
||||
);
|
||||
})}
|
||||
</QueueList>
|
||||
</main>
|
||||
</div>
|
||||
|
||||
@ -39,7 +39,7 @@ Click the **Skills** button in the input bar to open the skill selector. Enabled
|
||||
|
||||
## Plan mode
|
||||
|
||||
Toggle **Plan Mode** in the input bar to enable the todo list middleware. In plan mode, the agent creates and maintains a visible task list as it works through a complex multi-step objective. Each task shows its status (`pending`, `in_progress`, `completed`) in real time.
|
||||
Toggle **Plan Mode** in the input bar to enable the todo list middleware. In plan mode, the agent creates and maintains a visible task list as it works through a complex multi-step objective. Each task shows its status (`pending`, `in_progress`, `completed`, `blocked`, or `waiting`).
|
||||
|
||||
Plan mode is most useful for complex tasks with 3 or more distinct steps.
|
||||
|
||||
|
||||
@ -124,7 +124,7 @@ models:
|
||||
|
||||
## Plan mode
|
||||
|
||||
When `is_plan_mode` is set to `true` in the request configuration, the `TodoMiddleware` is activated. The agent then maintains a structured task list, marking items as `in_progress`, `completed`, or `pending` as it works through a complex task. This provides visibility into the agent's progress for the user.
|
||||
When `is_plan_mode` is set to `true` in the request configuration, the `TodoMiddleware` is activated. The agent maintains a structured task list and updates it at meaningful milestones. Items can be `pending`, `in_progress`, `completed`, `blocked`, or `waiting`; `completed` means the work is fully finished and verified, while `blocked` and `waiting` explain why the current run cannot continue.
|
||||
|
||||
Plan mode is appropriate for complex, multi-step tasks where showing incremental progress is valuable. For simple requests, it is better left disabled to avoid unnecessary overhead.
|
||||
|
||||
|
||||
@ -41,8 +41,8 @@ The middleware chain is built once per agent invocation, based on the current co
|
||||
10. `ViewImageMiddleware` — image details injection (if model supports vision)
|
||||
11. `DeferredToolFilterMiddleware` — hides deferred tool schemas (if tool search enabled)
|
||||
12. `SystemMessageCoalescingMiddleware` — coalesces provider-facing system messages
|
||||
13. `SubagentLimitMiddleware` — limits parallel subagent calls (if subagents enabled)
|
||||
14. `LoopDetectionMiddleware` — breaks repetitive tool call loops
|
||||
13. `LoopDetectionMiddleware` — breaks repetitive tool call loops
|
||||
14. `SubagentLimitMiddleware` — limits parallel subagent calls (if subagents enabled)
|
||||
15. `TokenBudgetMiddleware` — per-run token budget enforcement (if enabled)
|
||||
16. Custom middlewares (if any)
|
||||
17. Configured extension middlewares (if any)
|
||||
@ -117,7 +117,7 @@ title:
|
||||
|
||||
### TodoMiddleware
|
||||
|
||||
When plan mode is active, maintains a structured task list visible to the user. The agent uses the `write_todos` tool to mark tasks as `pending`, `in_progress`, or `completed` as it works through a complex objective.
|
||||
When plan mode is active, maintains a structured task list visible to the user. The agent uses the `write_todos` tool to update tasks at meaningful milestones. Statuses are `pending`, `in_progress`, `completed`, `blocked`, and `waiting`; only fully finished and verified work is `completed`.
|
||||
|
||||
**Activation**: enabled automatically when `is_plan_mode: true` is set in the request configuration. No `config.yaml` entry required.
|
||||
|
||||
|
||||
@ -19,7 +19,7 @@ A subagent runs its own agent loop, so it needs the same backstops the Lead Agen
|
||||
| Timeout | `subagents.timeout_seconds` (built-ins only), `subagents.agents.<name>.timeout_seconds` | built-ins 1800 s, custom and managed 900 s | at least 1 | Status `timed_out` |
|
||||
| Polling attempts | Derived from the timeout: `(timeout_seconds + 60) / 5` polls, every 5 seconds | follows the timeout | | Status `polling_timed_out`; the runtime requests cancellation and schedules deferred cleanup |
|
||||
| Token budget | `subagents.token_budget`, `subagents.agents.<name>.token_budget` | enabled; `max_tokens` 2,000,000, or 1,000,000 when summarization is on; `warn_threshold` 0.7 | `max_tokens` at least 1000 | The in-flight turn is capped and forced to finish: `completed` + `token_capped` |
|
||||
| Loop detection | `loop_detection` (shared with the Lead Agent) | enabled; `warn_threshold` 3, `hard_limit` 5, `window_size` 20, `tool_freq_warn` 30, `tool_freq_hard_limit` 50 | | `completed` + `loop_capped` |
|
||||
| Loop detection | `loop_detection` (shared with the Lead Agent) | enabled; `warn_threshold` 3, `hard_limit` 5, `window_size` 20; frequency metrics at 30 and 50 calls | | Identical no-progress calls can produce `completed` + `loop_capped`; frequency thresholds only log metrics |
|
||||
| Summarization | `summarization` (shared with the Lead Agent) | example config: enabled, trigger at 32,000 tokens, keep the last 10 messages | | System prompt and latest user message survive; the summary goes into `summary_text` and is re-injected every call |
|
||||
| Process-wide capacity | `subagent_runtime.max_running` | 3 | 1 to 64 | When full, queue or reject per `admission_policy` |
|
||||
| Queue bound | `subagent_runtime.max_queued` | 64 | 0 to 10,000 | Rejected when the queue is full: `Subagent execution capacity is full (3 running, 64 queued)` |
|
||||
@ -62,7 +62,7 @@ The timeout is wall-clock. Once it elapses the subagent is cancelled with status
|
||||
|
||||
The subagent middleware chain mirrors four Lead Agent guards:
|
||||
|
||||
- **Loop detection** (`LoopDetectionMiddleware`): breaks a subagent that repeats the same tool call without progress. Subagents have no `task`, so only the tool-loop heuristic can fire. A hard stop marks the result `completed` + `subagent_stop_reason=loop_capped`. Controlled by the `loop_detection` config, with `tool_freq_overrides` for per-tool thresholds.
|
||||
- **Loop detection** (`LoopDetectionMiddleware`): warns and stops a subagent that repeats the same tool call without progress. Subagents have no `task`, so only the tool-loop heuristic can fire. A hash-based hard stop marks the result `completed` + `subagent_stop_reason=loop_capped`. Tool-name frequency thresholds only emit INFO metrics for workload and cost monitoring; they do not warn or stop the run. Controlled by the `loop_detection` config, with `tool_freq_overrides` for per-tool metric thresholds.
|
||||
- **Token budget** (`TokenBudgetMiddleware`): tracks the run's cumulative tokens against `subagents.token_budget`. At the hard-stop threshold it strips the current turn's tool calls and forces a final answer, marking the result `completed` + `token_capped`. Reaching `warn_threshold` injects a one-time budget warning into the subagent's next model call and logs it at INFO level.
|
||||
- **Output length** (`ModelLengthFinishReasonMiddleware`): when the provider stops a response at its output limit (`finish_reason=length`, `stop_reason=max_tokens`, `MAX_TOKENS`, or Responses `max_output_tokens`), tool calls in that response are dropped because their arguments may be truncated, and the result is marked `completed` + `model_length_capped`.
|
||||
- **Summarization** (`DeerFlowSummarizationMiddleware`): compacts long subagent transcripts under the same `summarization.enabled` switch as the Lead Agent, and by default summarizes with the subagent's own model. Compaction preserves the subagent's system prompt (role, report contract, acceptance note, skill index, deferred tool catalog) and the latest user message. `DurableContextMiddleware` sits before summarization and re-injects `summary_text` into later requests, so a compacted history never starts with an assistant message.
|
||||
|
||||
@ -29,9 +29,9 @@ Expected. A failed subagent is an ordinary tool result; the parent run does not
|
||||
|
||||
### The result is marked `token_capped` or `loop_capped`
|
||||
|
||||
**Cause**: the token budget or loop detection hard stop fired ([#3931](https://github.com/bytedance/deer-flow/pull/3931), [#3980](https://github.com/bytedance/deer-flow/pull/3980)).
|
||||
**Cause**: the token budget or the hash-based loop detector stopped the run after repeated identical calls with no progress ([#3931](https://github.com/bytedance/deer-flow/pull/3931), [#3980](https://github.com/bytedance/deer-flow/pull/3980)).
|
||||
|
||||
**Fix**: first check the step timeline for the same tool being called over and over. If more budget is genuinely needed, adjust `subagents.token_budget.max_tokens` or `loop_detection.tool_freq_overrides`. Note that the default token ceiling is coupled to `summarization.enabled`; an explicit value is not.
|
||||
**Fix**: first check the step timeline for the same call being repeated without progress. If more work is genuinely needed, adjust `subagents.token_budget.max_tokens` or another explicit work budget. Tool-name frequency entries in the logs are observability metrics and do not cause `loop_capped`; `loop_detection.tool_freq_overrides` only tunes those metrics. Note that the default token ceiling is coupled to `summarization.enabled`; an explicit value is not.
|
||||
|
||||
### The result is marked `model_length_capped`
|
||||
|
||||
|
||||
@ -107,7 +107,7 @@ models:
|
||||
|
||||
## 计划模式
|
||||
|
||||
当请求配置中将 `is_plan_mode` 设为 `true` 时,`TodoMiddleware` 被激活。Agent 然后维护一个结构化的任务列表,在处理复杂任务时将条目标记为 `in_progress`、`completed` 或 `pending`。这为用户提供了 Agent 进度的可见性。
|
||||
当请求配置中将 `is_plan_mode` 设为 `true` 时,`TodoMiddleware` 被激活。Agent 会在有意义的里程碑更新结构化任务列表。条目状态可以是 `pending`、`in_progress`、`completed`、`blocked` 或 `waiting`;只有完全完成并验证过的工作才能标记为 `completed`,`blocked` 和 `waiting` 用于说明本轮无法继续的原因。
|
||||
|
||||
计划模式适用于显示增量进度有价值的复杂、多步骤任务。对于简单请求,最好禁用它以避免不必要的开销。
|
||||
|
||||
|
||||
@ -37,8 +37,8 @@ import { Callout } from "nextra/components";
|
||||
10. `ViewImageMiddleware` — 图像细节注入(如果模型支持视觉)
|
||||
11. `DeferredToolFilterMiddleware` — 隐藏延迟工具 schema(如果启用工具搜索)
|
||||
12. `SystemMessageCoalescingMiddleware` — 合并面向 provider 的 system messages
|
||||
13. `SubagentLimitMiddleware` — 限制并行子 Agent 调用(如果启用子 Agent)
|
||||
14. `LoopDetectionMiddleware` — 打破重复工具调用循环
|
||||
13. `LoopDetectionMiddleware` — 打破重复工具调用循环
|
||||
14. `SubagentLimitMiddleware` — 限制并行子 Agent 调用(如果启用子 Agent)
|
||||
15. `TokenBudgetMiddleware` — 每次运行的 token 预算限制(如果启用)
|
||||
16. 自定义中间件(如有)
|
||||
17. 配置的扩展中间件(如有)
|
||||
@ -113,7 +113,7 @@ title:
|
||||
|
||||
### TodoMiddleware
|
||||
|
||||
当计划模式激活时,维护一个对用户可见的结构化任务列表。Agent 使用 `write_todos` 工具,随着完成复杂目标,将任务标记为 `pending`、`in_progress` 或 `completed`。
|
||||
当计划模式激活时,维护一个对用户可见的结构化任务列表。Agent 使用 `write_todos` 工具在有意义的里程碑更新任务。状态包括 `pending`、`in_progress`、`completed`、`blocked` 和 `waiting`;只有完全完成并验证过的工作才能标记为 `completed`。
|
||||
|
||||
**激活**:在请求配置中设置 `is_plan_mode: true` 时自动启用。不需要 `config.yaml` 条目。
|
||||
|
||||
|
||||
@ -19,7 +19,7 @@ import { Callout } from "nextra/components";
|
||||
| 超时 | `subagents.timeout_seconds`(仅内置)、`subagents.agents.<name>.timeout_seconds` | 内置 1800 秒,自定义与设置页管理 900 秒 | 大于等于 1 | 状态 `timed_out` |
|
||||
| 轮询次数 | 由超时推导:`(timeout_seconds + 60) / 5` 次,每 5 秒一次 | 随超时 | | 状态 `polling_timed_out`,运行时请求取消并安排延迟清理 |
|
||||
| token 预算 | `subagents.token_budget`,`subagents.agents.<name>.token_budget` | 开启;`max_tokens` 2,000,000,摘要压缩开启时 1,000,000;`warn_threshold` 0.7 | `max_tokens` 大于等于 1000 | 当前轮被截断并强制收尾,`completed` + `token_capped` |
|
||||
| 循环检测 | `loop_detection`(与 Lead Agent 共用) | 开启;`warn_threshold` 3,`hard_limit` 5,`window_size` 20,`tool_freq_warn` 30,`tool_freq_hard_limit` 50 | | `completed` + `loop_capped` |
|
||||
| 循环检测 | `loop_detection`(与 Lead Agent 共用) | 开启;`warn_threshold` 3,`hard_limit` 5,`window_size` 20;频次指标阈值为 30 和 50 次 | | 相同且无进展的调用可产生 `completed` + `loop_capped`;工具频次只记录指标 |
|
||||
| 摘要压缩 | `summarization`(与 Lead Agent 共用) | 示例配置开启,按 32,000 token 触发,保留最近 10 条消息 | | 压缩后系统提示与最新用户消息保留,摘要写入 `summary_text` 并每次回注 |
|
||||
| 进程级容量 | `subagent_runtime.max_running` | 3 | 1 到 64 | 满时按 `admission_policy` 排队或拒绝 |
|
||||
| 排队上限 | `subagent_runtime.max_queued` | 64 | 0 到 10,000 | 队列满时拒绝:`Subagent execution capacity is full (3 running, 64 queued)` |
|
||||
@ -62,7 +62,7 @@ recursion_limit = max_turns × (每轮节点数) + (每次调用一次性节点
|
||||
|
||||
子 Agent 中间件链镜像了 Lead Agent 的四道防护:
|
||||
|
||||
- **循环检测** `LoopDetectionMiddleware`:打断不取得进展却反复调用同一工具的循环。子 Agent 没有 `task`,所以只有工具循环启发式会触发。硬停止把结果标记为 `completed` + `subagent_stop_reason=loop_capped`。由 `loop_detection` 配置控制,可以用 `tool_freq_overrides` 按工具名单独设阈值。
|
||||
- **循环检测** `LoopDetectionMiddleware`:对相同且没有进展的工具调用发出警告并在达到硬限制时停止。子 Agent 没有 `task`,所以只有工具循环启发式会触发。基于哈希的硬停止把结果标记为 `completed` + `subagent_stop_reason=loop_capped`。工具名称频次只记录 INFO 指标,用于工作量和成本监测,不会发出警告或停止运行。由 `loop_detection` 配置控制,`tool_freq_overrides` 只调整各工具的指标阈值。
|
||||
- **token 预算** `TokenBudgetMiddleware`:按 `subagents.token_budget` 计算单次运行的累计 token。到达硬停止阈值时剥离当前轮的工具调用、强制产出最终答案,结果标记 `completed` + `token_capped`。到达 `warn_threshold` 比例时,会在子 Agent 的下一次模型调用中注入一次预算警告,并记一条 INFO 日志。
|
||||
- **输出长度** `ModelLengthFinishReasonMiddleware`:provider 因输出长度上限停止回答时(`finish_reason=length`、`stop_reason=max_tokens`、`MAX_TOKENS` 或 Responses 的 `max_output_tokens`),该回答里的工具调用参数可能不完整,会被丢弃,结果标记 `completed` + `model_length_capped`。
|
||||
- **摘要压缩** `DeerFlowSummarizationMiddleware`:用与 Lead Agent 相同的 `summarization.enabled` 开关压缩过长的子 Agent 记录,摘要模型默认就是子 Agent 自己在用的模型。压缩时子 Agent 的系统提示(角色、报告契约、验收说明、技能索引、延迟工具目录)和最新用户消息会被保留;`DurableContextMiddleware` 排在压缩之前,把 `summary_text` 回注到后续请求,避免压缩后出现以助手消息开头的历史。
|
||||
|
||||
@ -29,9 +29,9 @@ import { Callout } from "nextra/components";
|
||||
|
||||
### 结果标记 `token_capped` 或 `loop_capped`
|
||||
|
||||
**原因**:命中 token 预算或循环检测的硬停止([#3931](https://github.com/bytedance/deer-flow/pull/3931)、[#3980](https://github.com/bytedance/deer-flow/pull/3980))。
|
||||
**原因**:命中 token 预算,或相同工具调用在没有进展时触发了基于哈希的循环检测硬停止([#3931](https://github.com/bytedance/deer-flow/pull/3931)、[#3980](https://github.com/bytedance/deer-flow/pull/3980))。
|
||||
|
||||
**处理**:先看步骤时间线里是不是同一个工具被反复调用。确实需要更多预算时调整 `subagents.token_budget.max_tokens` 或 `loop_detection.tool_freq_overrides`。注意 token 预算的默认值与 `summarization.enabled` 联动,显式设置的值不受影响。
|
||||
**处理**:先看步骤时间线里是不是同一个调用在没有进展时被重复执行。确实需要更多工作量时调整 `subagents.token_budget.max_tokens` 或其他明确的工作量预算。日志中的工具名称频次是观测指标,不会导致 `loop_capped`;`loop_detection.tool_freq_overrides` 只调整这些指标。注意 token 预算的默认值与 `summarization.enabled` 联动,显式设置的值不受影响。
|
||||
|
||||
### 结果标记 `model_length_capped`
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
export interface Todo {
|
||||
content?: string;
|
||||
status?: "pending" | "in_progress" | "completed";
|
||||
status?: "pending" | "in_progress" | "completed" | "blocked" | "waiting";
|
||||
}
|
||||
|
||||
@ -0,0 +1,32 @@
|
||||
import { afterEach, expect, test } from "@rstest/core";
|
||||
import { cleanup, render, screen } from "@testing-library/react";
|
||||
|
||||
import { TodoList } from "@/components/workspace/todo-list";
|
||||
import type { Todo } from "@/core/todos";
|
||||
|
||||
afterEach(cleanup);
|
||||
|
||||
test("keeps todo rows mounted when distinct items move past duplicate labels", () => {
|
||||
const draft: Todo = { content: "Draft", status: "pending" };
|
||||
const review: Todo = { content: "Review", status: "waiting" };
|
||||
const completedDraft: Todo = { content: "Draft", status: "completed" };
|
||||
const { rerender } = render(
|
||||
<TodoList todos={[draft, review, completedDraft]} collapsed={false} />,
|
||||
);
|
||||
const reviewRow = screen.getByText("Review").closest("li");
|
||||
const draftRows = screen
|
||||
.getAllByText("Draft")
|
||||
.map((text) => text.closest("li"));
|
||||
|
||||
rerender(
|
||||
<TodoList todos={[review, draft, completedDraft]} collapsed={false} />,
|
||||
);
|
||||
|
||||
expect(screen.getByText("Review").closest("li")).toBe(reviewRow);
|
||||
const nextDraftRows = screen
|
||||
.getAllByText("Draft")
|
||||
.map((text) => text.closest("li"));
|
||||
expect(nextDraftRows[0]).toBe(draftRows[0]);
|
||||
expect(nextDraftRows[1]).toBe(draftRows[1]);
|
||||
expect(nextDraftRows[0]).not.toBe(nextDraftRows[1]);
|
||||
});
|
||||
Loading…
x
Reference in New Issue
Block a user