vrr/agent-zero
2
0
Fork 0
mirror of https://github.com/agent0ai/agent-zero.git synced 2026-10-19 07:23:51 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1
agent-zero/plugins/_context_doctor/AGENTS.md
linkliti 093b9106ef Tighten context doctor usable-response detection 
Guard empty/whitespace LLM responses so context_doctor defers to _20_empty_response instead of polluting history with {thoughts:[]}. Require looks_like_tool_call to find at least one A0 key with a usable non-empty value (non-empty list of non-empty strings for thoughts, non-empty string for headline/tool_name, non-empty dict for tool_args). Update AGENTS.md contract and add regression tests for empty/blank/wrong-type rejections.
2026-09-04 18:33:01 +03:00

3 KiB
Raw Blame History

Context Doctor Plugin DOX

Purpose

  • Repair malformed Agent Zero tool-call JSON and preserve raw output as compact thoughts JSON when repair cannot produce a tool call.

Ownership

  • helpers/context_doctor.py transforms output and refreshes log fields.
  • hooks.py installs the exact root-pinned repair dependency in the framework runtime.
  • extensions/python/startup_migration/ prepares that dependency after startup and self-update.
  • extensions/python/message_loop_result/ normalizes completed model output before default processing.
  • prompts/ owns fallback warning texts (fw.msg_thoughts_fallback.md, fw.msg_thoughts_fallback_response.md).
  • webui/config.html exposes debug and repair-strategy settings.

Local Contracts

  • Repaired and fallback JSON is always minified.
  • Nonempty non-tool output becomes {"thoughts":[raw]}; XML-like output becomes {} only when suppression is enabled.
  • Blank-line-separated thoughts expand into separate entries after repair when the split strategy is enabled (default on). This rewrites model-authored thoughts for every repaired turn by design, not only the raw-text fallback branch.
  • looks_like_tool_call returns True only when the transformed output is a dict containing at least one A0 key (thoughts/headline/tool_name/tool_args) with a usable non-empty value: non-empty list of non-empty strings for thoughts, non-empty string for headline/tool_name, non-empty dict for tool_args. Empty dicts, missing keys, or keys with empty/blank values fall through to the raw-text fallback branch.
  • A raw-text fallback conversion must emit a fw.msg_thoughts_fallback.md history warning and a separate fw.msg_thoughts_fallback_response.md user notice, refresh the generating log and response item with the transformed thoughts JSON, and set skip_default_processing so the retry advances the unusable-response counter.
  • The fallback passes the repaired llm_result to hist_add_ai_response, which owns Responses-API state advancement (_remember_llm_result_state); do not call the state method directly. The fallback turn's response_id is recorded so the next turn's previous_response_id chain stays intact.
  • The fallback warning is counted by the core stop-unusable-response loop alongside fw.msg_misformat.md, fw.msg_repeat.md, fw.msg_empty_response.md, and fw.msg_reasoning_only.md.
  • Log kvps retain streamed reasoning only; update_log_item does not restore thoughts from current kvps. update_log controls only View Details content.
  • A repaired response tool call refreshes the response log item when streaming did not create it.
  • Runtime setup reads the json_repair pin from root requirements.txt; do not duplicate its version in plugin code.

Work Guidance

  • Keep repair scoped to complete tool-call JSON.
  • Use framework-installed json_repair; apply plugin-local parser patch before repair. Do not vendor dependencies.

Verification

  • Run pytest plugins/_context_doctor/tests.

Child DOX Index

No child DOX files.