DeerFlow 2.0 — TodoMiddleware & LangChain TodoListMiddleware

Two GitHub sources read together:

LangChain TodoListMiddleware (base class)

Data models

• Todo — TypedDict: content: str, status: "pending" | "in_progress" | "completed"
• PlanningState — extends AgentState; adds todos: list[Todo] (excluded from input)
• WriteTodosInput — Pydantic model validating write_todos tool input

write_todos tool

• Replaces the entire todo list atomically (no partial edits).
• Returns a Command updating todos in state and appending a ToolMessage with confirmation.
• Sync (_write_todos) and async (_awrite_todos) variants; both inject tool_call_id from ToolRuntime.

System prompt injection

wrap_model_call / awrap_model_call append guidance to every model request:

• When to use: complex multi-step tasks (≥ 3 steps), non-trivial objectives, explicit user request.
• When to skip: single straightforward tasks, trivial operations.
• Rules: mark in_progress before starting each task; mark completed immediately upon finishing; never call write_todos in parallel.

after_model enforcement

Detects when the model issues multiple parallel write_todos tool calls (ambiguous because the tool replaces the whole list). Returns error ToolMessages for each violating call.

DeerFlow TodoMiddleware (extends TodoListMiddleware)

Adds two new failure-mode mitigations on top of the base class.

Helper functions

before_model — context-loss recovery

When context is truncated (e.g. by summarization), the original write_todos call disappears from the window. The hook fires when:

1. todos is non-empty in state, AND
2. No write_todos call is visible in messages, AND
3. No todo_reminder already injected

Injects a HumanMessage(name="todo_reminder") with the current todo list inside <system_reminder> tags.

after_model — premature-exit prevention

Fires when the model produces a final AIMessage (no tool calls) but incomplete todos remain. Decorated with @hook_config(can_jump_to=["model"]).

• Cap: _MAX_COMPLETION_REMINDERS = 2 (avoids infinite loops).
• Injects HumanMessage(name="todo_completion_reminder") listing incomplete items.
• Returns {"jump_to": "model", "messages": [reminder]} to force another iteration.

Design notes

• Uses LangGraph's jump_to state field (standard middleware contract, not a hack).
• Both before_model and after_model are idempotent: repeated calls check for existing reminders before injecting.
• The retry cap is a hard upper bound; the base class's parallel-call check still applies via super().after_model().