mirror of
https://github.com/bytedance/deer-flow.git
synced 2026-06-09 17:12:01 +00:00
8d2e55a05f
* fix(subagent): structured subagent_status field over text parsing Closes #3146. ## Why The frontend used to derive subtask card state by string-matching the leading text of the `task` tool's result. That contract surface was fragile — `#3107` BUG-007 and the `#3131` review both surfaced cases where new backend wording (`Task cancelled by user.`, `Task polling timed out after N minutes`, `ToolErrorHandlingMiddleware` exception wrappers) silently broke the card lifecycle. The frontend fallback kept growing more prefixes; any future rewording would break it again. ## Design 1. **Backend → frontend contract**: `ToolMessage.additional_kwargs` carries `subagent_status` (one of `completed | failed | cancelled | timed_out | polling_timed_out`) and an optional `subagent_error` blob. The frontend prefers it over parsing `content`. 2. **Centralised stamping, not 8 sprinkled stamps**: rather than have each of `task_tool.py`'s 5 normal-return + 3 pre-execution `Error:` paths remember to set `additional_kwargs`, `ToolErrorHandlingMiddleware` stamps the field after every task-tool call. Adding a new return path in `task_tool.py` cannot now skip the stamp. 3. **Cross-language contract fixture**: the prefix→status mapping is the one piece both sides must agree on. The shared fixture at `contracts/subagent_status_contract.json` lists every backend return string, the expected status, and what the error substring should contain. Backend test (`backend/tests/test_subagent_status_contract.py`) and frontend test (`frontend/tests/unit/core/tasks/subtask-result.test.ts`) both load that fixture and assert the same cases. A wording drift on either side fails the matching language's test. 4. **Round-trip serialisation pinned**: the round-trip test asserts `ToolMessage.model_dump_json()` → `model_validate_json()` preserves `additional_kwargs.subagent_status`. Catches the case where a future LangChain or Pydantic upgrade silently strips unknown kwargs. 5. **Frontend status collapse documented**: the backend has five status values, the frontend card has three (`completed | failed | in_progress`). `cancelled` / `timed_out` / `polling_timed_out` all collapse to `failed` with the original status preserved in `error`. `parseSubtaskResult` returns `in_progress` for unknown values so a backend that ships a new enum variant before the frontend upgrades degrades to the legacy prefix fallback instead of getting pinned. ## Changes Backend: - `deerflow.subagents.status_contract` — new module exporting `SUBAGENT_STATUS_KEY`, `SUBAGENT_ERROR_KEY`, `SUBAGENT_STATUS_VALUES`, `extract_subagent_status(content)`, and `make_subagent_additional_kwargs(status, error)`. - `ToolErrorHandlingMiddleware`: new `_stamp_task_subagent_status` helper centralises the stamp; `wrap_tool_call` / `awrap_tool_call` stamp on the success path; `_build_error_message` stamps on the wrapper path (carrying `ExcClass: detail` into `subagent_error`). Non-task tools are untouched. - New tests: `test_subagent_status_contract.py` (19 cases from the shared fixture + status-enum / blank-error / unknown-status rejection) and `test_tool_error_handling_subagent_stamp.py` (middleware integration: terminal-content stamps, non-terminal doesn't, non-task tools untouched, async path mirrors sync, existing additional_kwargs survive, JSON round-trip preserved). Frontend: - `parseSubtaskResult(text, additionalKwargs?)` — prefers the structured stamp; falls back to the legacy prefix matcher for historical threads / unknown future status values. - `STRUCTURED_STATUS_TO_SUBTASK` documents the five→three collapse. - `message-list.tsx` passes `message.additional_kwargs` through. - `subtask-result.test.ts` adds a structured-status block + a fixture-driven contract block; legacy prefix tests stay green for the fallback path. Contract: - `contracts/subagent_status_contract.json` — single source of truth both languages load. Whitespace variants, varied N for polling timeouts, the 3 pre-execution `Error:` returns task_tool produces, and the middleware wrapper shape are all in there. ## Test plan - `make lint` clean (backend + frontend). - `pytest tests/test_subagent_status_contract.py tests/test_tool_error_handling_subagent_stamp.py` → 37 passed. - `pnpm test --run` → 103 passed (was 76, +27 new). ## Migration / fallback retirement The text-prefix fallback stays in place until backend telemetry shows the frontend never hits it for newly produced messages. At that point a follow-up PR can drop the prefix branches and keep only the structured-status branch. Refs: bytedance/deer-flow#3138 (split summary), #3107 (origin), #3131 (prior prefix-only fix), #3146 (this issue). * fix(subtask): back-fill result/error from text when structured status present Three follow-ups on the PR #3154 review: 1. `readStructuredStatus` no longer short-circuits the prefix parse. The backend currently stamps only the `subagent_status` enum value; the human-facing `result` body and wrapped-error message still live in `ToolMessage.content`. Dropping the text parse meant successful tasks rendered empty completed pills and wrapped failures lost their diagnostic. Now both shapes get composed: structured status wins, `result`/`error` come from text when both sides agree, and a lying success body under a `failed` stamp is dropped instead of leaking. 2. Replace the ESM-incompatible `__dirname` fixture lookup in subtask-result.test.ts with `fileURLToPath(new URL(..., import.meta.url))`. The frontend package is `"type": "module"`, so the previous path would have thrown at runtime if anything ever changed under the contract directory. 3. Drop the `$schema` reference from contracts/subagent_status_contract.json pointing at a file that doesn't exist in the tree. Three new tests cover the structured + text composition: completed back-fills the success body, failed back-fills the wrapper text, and unrecognised content under a `failed` stamp stays empty rather than echoing noise.
99 lines
3.8 KiB
JSON
99 lines
3.8 KiB
JSON
{
|
|
"version": 1,
|
|
"description": "Cross-language contract test fixture for the subagent status field. The backend stamps ToolMessage.additional_kwargs.subagent_status using these prefixes; the frontend reads the structured field and falls back to the same prefixes. Both sides' tests load this file and must agree.",
|
|
"valid_status_values": ["completed", "failed", "cancelled", "timed_out", "polling_timed_out"],
|
|
"cases": [
|
|
{
|
|
"name": "succeeded",
|
|
"origin": "task_tool.py succeeded path",
|
|
"content": "Task Succeeded. Result: investigated and produced a 3-page report",
|
|
"expected_status": "completed",
|
|
"expected_error_contains": null
|
|
},
|
|
{
|
|
"name": "failed",
|
|
"origin": "task_tool.py failed path",
|
|
"content": "Task failed. Error: underlying tool raised RuntimeError",
|
|
"expected_status": "failed",
|
|
"expected_error_contains": "RuntimeError"
|
|
},
|
|
{
|
|
"name": "cancelled",
|
|
"origin": "task_tool.py cancelled path",
|
|
"content": "Task cancelled by user.",
|
|
"expected_status": "cancelled",
|
|
"expected_error_contains": null
|
|
},
|
|
{
|
|
"name": "timed_out",
|
|
"origin": "task_tool.py timed_out path",
|
|
"content": "Task timed out. Error: 900 seconds",
|
|
"expected_status": "timed_out",
|
|
"expected_error_contains": "900"
|
|
},
|
|
{
|
|
"name": "polling_timed_out",
|
|
"origin": "task_tool.py polling timeout safety-net path",
|
|
"content": "Task polling timed out after 15 minutes. This may indicate the background task is stuck. Status: RUNNING",
|
|
"expected_status": "polling_timed_out",
|
|
"expected_error_contains": "15"
|
|
},
|
|
{
|
|
"name": "polling_timed_out_other_n",
|
|
"origin": "varied N coverage",
|
|
"content": "Task polling timed out after 1 minutes. Status: RUNNING",
|
|
"expected_status": "polling_timed_out",
|
|
"expected_error_contains": null
|
|
},
|
|
{
|
|
"name": "pre_unknown_subagent",
|
|
"origin": "task_tool.py pre-execution Error path (unknown subagent type)",
|
|
"content": "Error: Unknown subagent type 'foo'. Available: bash, general-purpose",
|
|
"expected_status": "failed",
|
|
"expected_error_contains": "Unknown subagent"
|
|
},
|
|
{
|
|
"name": "pre_bash_disabled",
|
|
"origin": "task_tool.py pre-execution Error path (host bash disabled)",
|
|
"content": "Error: Host bash subagent is disabled by configuration",
|
|
"expected_status": "failed",
|
|
"expected_error_contains": "disabled"
|
|
},
|
|
{
|
|
"name": "pre_task_disappeared",
|
|
"origin": "task_tool.py pre-execution Error path (background task disappeared)",
|
|
"content": "Error: Task 1234 disappeared from background tasks",
|
|
"expected_status": "failed",
|
|
"expected_error_contains": "disappeared"
|
|
},
|
|
{
|
|
"name": "wrapper_error",
|
|
"origin": "ToolErrorHandlingMiddleware wrap on tool exception",
|
|
"content": "Error: Tool 'task' failed with TypeError: 'AsyncCallbackManager' object is not iterable. Continue with available context, or choose an alternative tool.",
|
|
"expected_status": "failed",
|
|
"expected_error_contains": "TypeError"
|
|
},
|
|
{
|
|
"name": "streaming_chunk_unknown",
|
|
"origin": "non-terminal chunk reaching parser",
|
|
"content": "Investigating ...",
|
|
"expected_status": null,
|
|
"expected_error_contains": null
|
|
},
|
|
{
|
|
"name": "succeeded_with_surrounding_whitespace",
|
|
"origin": "streaming sometimes prepends/appends newlines",
|
|
"content": " Task Succeeded. Result: ok ",
|
|
"expected_status": "completed",
|
|
"expected_error_contains": "ok"
|
|
},
|
|
{
|
|
"name": "cancelled_with_surrounding_whitespace",
|
|
"origin": "streaming whitespace coverage",
|
|
"content": " Task cancelled by user.\n",
|
|
"expected_status": "cancelled",
|
|
"expected_error_contains": null
|
|
}
|
|
]
|
|
}
|