Agent Zero AI framework
Consolidate Responses prompt bookkeeping outside Agent
Alessandro8f184abedea9
diff --git a/AGENTS.md b/AGENTS.mdindex 1165e958d..ff274ae6f 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -36,7 +36,7 @@- Embedding wrappers expose batch-shaped `embed(inputs)` for provider-ready inputs; keep `embed_documents` and `embed_query` as LangChain compatibility adapters.- Embedding requests never forward the chat-only `a0_api_mode` control to providers.- Prompt Markdown may retain fenced JSON examples for readability; final system-prompt rendering removes only their JSON fence markers before model calls and preserves non-JSON fences.-- System section owners populate request-only `LoopData.responses_prompt_replacements`; prompt construction resets them each time. Responses applies them to copied input, preserving original Chat/fallback messages and stored history.+- System section owners register request-only alternatives with `helpers.responses_tools`; `helpers.responses_history` owns their per-build state and prepared-history capture in existing loop parameters. Responses applies them to copied input, preserving original Chat/fallback messages and stored history.- Copy live core-plugin changes back into tracked source under `plugins/`.- Develop new custom plugins under ignored `usr/plugins/`; tracked bundled plugins live under `plugins/`.- Use the framework runtime for backend and plugin-hook verification, not the separate agent execution runtime.diff --git a/agent.py b/agent.pyindex 7088b21f6..31a240b92 100644--- a/agent.py+++ b/agent.py@@ -343,9 +343,6 @@ class LoopData:def __init__(self, **kwargs):self.iteration = -1self.system = []- self.responses_prompt_replacements: dict[str, str] = {}- self.responses_prepared_text = ""- self.responses_history_prefix: list[BaseMessage] = []self.user_message: history.Message | None = Noneself.history_output: list[history.OutputMessage] = []self.protocol_temporary: OrderedDict[str, history.MessageContent] = OrderedDict()@@ -574,7 +571,7 @@ class Agent:)# set system prompt and message history- loop_data.responses_prompt_replacements.clear()+ responses_history.start_prompt(loop_data)loop_data.system = await self.get_system_prompt(self.loop_data)loop_data.history_output = self.history.output()@@ -615,11 +612,7 @@ class Agent:*history_langchain,]full_text = ChatPromptTemplate.from_messages(full_prompt).format()- loop_data.responses_prepared_text = full_text- loop_data.responses_history_prefix = [- SystemMessage(content=system_text),- *history.output_langchain(protocol + loop_data.history_output),- ]+ responses_history.remember_prompt(loop_data, full_text, full_prompt[0], protocol)# store as last context window contentself.set_data(@@ -958,7 +951,6 @@ class Agent:"background": background,"explicit_caching": explicit_caching,"a0_responses_function_tools": response_tools,- "responses_prompt_replacements": dict(self.loop_data.responses_prompt_replacements),}previous_state = self._responses_state_for_model(model)@@ -978,10 +970,8 @@ class Agent:"chat_model_call_before", self, call_data=call_data)- call_data["responses_history_context"] = self._responses_history_context(- call_data["model"], call_data["messages"]- )turn_kwargs = {+ **responses_history.prepare_call(self, call_data),"a0_responses_function_tools": call_data.get("a0_responses_function_tools"),@@ -990,8 +980,6 @@ class Agent:),}for key in (- "responses_history_context",- "responses_prompt_replacements","responses_builtin_tools","responses_state","previous_response_id",@@ -1076,31 +1064,6 @@ class Agent:converted = model._convert_messages(messages)return ResponsesTransport.input_from_messages(converted)- def _responses_history_context(self, model: Any, messages: list[BaseMessage]):- prepared = getattr(self.loop_data, "responses_prepared_text", "")- if (- not prepared or not hasattr(model, "_convert_messages")- or any(message.additional_kwargs or getattr(message, "tool_calls", None) for message in messages)- or ChatPromptTemplate.from_messages(messages).format() != prepared- ):- return None- from helpers.secrets import get_secrets_manager-- def render(record):- rendered = self._responses_prompt_input_items(- model, history.output_langchain([{**record, "ai": False}])- )- return rendered[0].get("content") if len(rendered) == 1 else None-- return {- "prompt": self._responses_prompt_input_items(model, messages),- "prefix": self._responses_prompt_input_items(model, self.loop_data.responses_history_prefix),- "groups": responses_history.prepare_groups(- self.loop_data.history_output, render,- get_secrets_manager(self.context).mask_values,- ),- }-def _remember_llm_result_state(self, llm_result: LLMResult, history_message: history.Message) -> None:diff --git a/extensions/python/system_prompt/AGENTS.md b/extensions/python/system_prompt/AGENTS.mdindex 699ae3118..bd410b7aa 100644--- a/extensions/python/system_prompt/AGENTS.md+++ b/extensions/python/system_prompt/AGENTS.md@@ -12,7 +12,7 @@## Local Contracts- Preserve ordering where sections depend on earlier context.-- Main, local-tool and MCP section owners register `LoopData.responses_prompt_replacements` while retaining normal text prompts. Responses applies these request-only substitutions when native A0 definitions are present; Chat and fallback keep the text protocol. MCP native framing preserves allowed-server context.+- Main, local-tool and MCP section owners identify their sections to `helpers.responses_tools.register_prompt` while retaining normal text prompts. That helper owns alternate protocol templates; Chat and fallback keep the text protocol. MCP supplies policy-filtered server context independently of endpoint mode.- Keep secret-related prompt sections masked and scoped.- Prompt additions must be bounded and compatible with tool-call contracts.- Keep non-tool sections free of configurable capability guidance; tool-owneddiff --git a/extensions/python/system_prompt/_10_main_prompt.py b/extensions/python/system_prompt/_10_main_prompt.pyindex 87deaed89..f36121b40 100644--- a/extensions/python/system_prompt/_10_main_prompt.py+++ b/extensions/python/system_prompt/_10_main_prompt.py@@ -1,5 +1,6 @@from typing import Any+from helpers import responses_toolsfrom helpers.extension import Extension, extensiblefrom agent import Agent, LoopData@@ -16,11 +17,7 @@ class MainPrompt(Extension):returnprompt = await build_prompt(self.agent)system_prompt.append(prompt)- communication = self.agent.read_prompt("agent.system.main.communication.md")- if communication in prompt:- loop_data.responses_prompt_replacements[communication] = self.agent.read_prompt(- "agent.system.main.communication.native.md"- )+ responses_tools.register_prompt(self.agent, loop_data, "main", prompt)@extensiblediff --git a/extensions/python/system_prompt/_11_tools_prompt.py b/extensions/python/system_prompt/_11_tools_prompt.pyindex 71b65cfc8..e86fa8d9e 100644--- a/extensions/python/system_prompt/_11_tools_prompt.py+++ b/extensions/python/system_prompt/_11_tools_prompt.py@@ -1,6 +1,7 @@import osfrom typing import Any+from helpers import responses_toolsfrom helpers.extension import Extension, extensiblefrom helpers import files, subagents, tool_policyfrom helpers.print_style import PrintStyle@@ -22,7 +23,7 @@ class ToolsPrompt(Extension):returnprompt = await build_prompt(self.agent)system_prompt.append(prompt)- loop_data.responses_prompt_replacements[prompt] = ""+ responses_tools.register_prompt(self.agent, loop_data, "tools", prompt)@extensiblediff --git a/extensions/python/system_prompt/_12_mcp_prompt.py b/extensions/python/system_prompt/_12_mcp_prompt.pyindex 876d5749b..4aabee27e 100644--- a/extensions/python/system_prompt/_12_mcp_prompt.py+++ b/extensions/python/system_prompt/_12_mcp_prompt.py@@ -1,5 +1,6 @@from typing import Any+from helpers import responses_toolsfrom helpers.extension import Extension, extensiblefrom helpers.mcp_handler import MCPConfigfrom agent import Agent, LoopData@@ -18,9 +19,7 @@ class MCPToolsPrompt(Extension):prompt = await build_prompt(self.agent)if prompt:system_prompt.append(prompt)- loop_data.responses_prompt_replacements[prompt] = (- MCPConfig.get_for_agent(self.agent).get_tools_prompt(agent=self.agent, native=True)- )+ responses_tools.register_prompt(self.agent, loop_data, "mcp", prompt)@extensiblediff --git a/helpers/litellm_transport.py b/helpers/litellm_transport.pyindex fd2928262..5c0594680 100644--- a/helpers/litellm_transport.py+++ b/helpers/litellm_transport.py@@ -185,7 +185,6 @@ class LiteLLMTransport:last_request_state: str = field(init=False, default=RESPONSES_STATE_PROVIDER)explicit_prompt_caching: bool = field(init=False, default=False)history_prefix_hash: str = field(init=False, default="")- native_history_calls: int = field(init=False, default=0)def __post_init__(self) -> None:self.kwargs = _without_stream_kwarg(dict(self.kwargs))@@ -393,7 +392,6 @@ class LiteLLMTransport:self.kwargs.get("responses_state"))self.history_prefix_hash = ""- self.native_history_calls = 0context = self.kwargs.get("responses_history_context")if (self.last_request_state == RESPONSES_STATE_LOCAL@@ -410,9 +408,6 @@ class LiteLLMTransport:response_kwargs["input"] = responses_history.project_history(prompt, context.get("groups", []), scope,)- self.native_history_calls = sum(- item.get("type") == "function_call" for item in response_kwargs["input"]- )return {"model": self.model,"stream": stream,@@ -503,8 +498,7 @@ class LiteLLMTransport:"state": self.policy.state,"cache_key": self.policy.cache_key,**(- {responses_history.PREFIX_HASH: self.history_prefix_hash,- "native_history_calls": self.native_history_calls}+ {responses_history.PREFIX_HASH: self.history_prefix_hash}if self.policy.using_responses and self.history_prefix_hash else {}),"fallback_error": _exception_text(self.policy.fallback_error)diff --git a/helpers/mcp_handler.py b/helpers/mcp_handler.pyindex 8771946a0..0b4fd21bf 100644--- a/helpers/mcp_handler.py+++ b/helpers/mcp_handler.py@@ -1150,7 +1150,7 @@ class MCPConfig(BaseModel):tools.append({f"{server.name}.{tool['name']}": tool_copy})return tools- def get_tools_prompt(self, server_name: str = "", agent: Any | None = None, *, native: bool = False) -> str:+ def get_tools_prompt(self, server_name: str = "", agent: Any | None = None, *, include_tools: bool = True) -> str:"""Get a prompt for all tools"""# just to wait for pending initialization@@ -1196,7 +1196,7 @@ class MCPConfig(BaseModel):_policy=policy,).allowed:continue- if native:+ if not include_tools:tool_prompts.append("")continueinput_schema = (@@ -1223,10 +1223,10 @@ class MCPConfig(BaseModel):if not server_prompts:return ""- return render(- "agent.system.mcp_tools.native.md" if native else "agent.system.mcp_tools.md",- tools="\n".join(server_prompts),- ) + "\n"+ servers = "\n".join(server_prompts)+ if not include_tools:+ return servers+ return render("agent.system.mcp_tools.md", tools=servers) + "\n"def has_tool(self, tool_name: str) -> bool:"""Check if a tool is available"""diff --git a/helpers/mcp_handler.py.dox.md b/helpers/mcp_handler.py.dox.mdindex 7faa2f347..2efbe51dd 100644--- a/helpers/mcp_handler.py.dox.md+++ b/helpers/mcp_handler.py.dox.md@@ -86,7 +86,7 @@policy, and `MCPTool.execute()` rechecks the same policy with the explicit MCPcanonical ID before invocation. Prompt construction uses one fresh policysnapshot and omits server sections when none of their tools are allowed.- `get_tools_prompt(native=True)` retains server context and restrictive operation guidance without duplicating native function schemas or text envelopes; blocked-only servers remain absent.+ `get_tools_prompt(include_tools=False)` returns policy-filtered server context without tool details or an outer protocol wrapper. Responses owns its own framing; blocked-only servers remain absent.Server headings are explicitly non-callable groups; each tool heading exposesthe exact qualified name that Chat Completions must call. Prompt guidancetreats each allowed-operation description as exhaustive and rejects inferringdiff --git a/helpers/responses_history.py b/helpers/responses_history.pyindex 252b15a22..56cae50fa 100644--- a/helpers/responses_history.py+++ b/helpers/responses_history.py@@ -11,6 +11,55 @@ from helpers.llm_result import result_from_metadataPREFIX_HASH = "history_prefix_hash"+def start_prompt(loop_data: Any) -> None:+ loop_data.params_temporary.pop("responses_prompt_replacements", None)+ loop_data.params_temporary.pop("responses_history", None)+++def remember_prompt(loop_data: Any, text: str, system_message: Any, protocol: list[dict]) -> None:+ from helpers import history++ loop_data.params_temporary["responses_history"] = {+ "text": text,+ "prefix": [system_message, *history.output_langchain(protocol + loop_data.history_output)],+ }+++def prepare_call(agent: Any, call_data: dict) -> dict:+ from langchain_core.prompts import ChatPromptTemplate+ from helpers import history+ from helpers.secrets import get_secrets_manager++ model, messages = call_data["model"], call_data["messages"]+ params = agent.loop_data.params_temporary+ kwargs = {"responses_prompt_replacements": call_data.get(+ "responses_prompt_replacements", params.get("responses_prompt_replacements", {}),+ )}+ prepared = params.get("responses_history", {})+ if (+ not prepared or not hasattr(model, "_convert_messages")+ or any(message.additional_kwargs or getattr(message, "tool_calls", None) for message in messages)+ or ChatPromptTemplate.from_messages(messages).format() != prepared["text"]+ ):+ return kwargs++ def render(record):+ rendered = agent._responses_prompt_input_items(+ model, history.output_langchain([{**record, "ai": False}]),+ )+ return rendered[0].get("content") if len(rendered) == 1 else None++ kwargs["responses_history_context"] = {+ "prompt": agent._responses_prompt_input_items(model, messages),+ "prefix": agent._responses_prompt_input_items(model, prepared["prefix"]),+ "groups": prepare_groups(+ agent.loop_data.history_output, render,+ get_secrets_manager(agent.context).mask_values,+ ),+ }+ return kwargs++def _json_bytes(value: Any) -> bytes:return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":")).encode()diff --git a/helpers/responses_history.py.dox.md b/helpers/responses_history.py.dox.mdindex 1b7cbeb75..6df15b473 100644--- a/helpers/responses_history.py.dox.md+++ b/helpers/responses_history.py.dox.md@@ -2,12 +2,14 @@## Purpose and Ownership-- Project eligible local Responses call/result groups within complete prepared input. Agent owns rendering and secret masking; the transport owns affinity, tool scope and request selection.+- Project eligible local Responses call/result groups within complete prepared input. Agent supplies the completed prompt boundary; this helper owns per-build replay state and rendering/masking adaptation. The transport owns affinity, tool scope and request selection.- `prepare_groups` reads visible rendered records and durable result metadata without changing stored history. `project_history` replaces only exact prepared spans. `prefix_hashes` binds stable visible prefixes to transport/tool scope in linear input size.+- `start_prompt`, `remember_prompt`, and `prepare_call` keep replay bookkeeping in existing `LoopData.params_temporary`, without adding transport fields to `LoopData`. Capture after prompt construction and validate after model-call hooks; retain explicit prompt-replacement overrides.+## Contracts-- Persist `history_prefix_hash` and the derived `native_history_calls` count in existing result capability metadata, never copies of old prompt inputs. The count reports what the actual request projected, for cache/continuation diagnosis. Hash system, protocol and prepared history; retain freshly prepared extras in each request.+- Persist only `history_prefix_hash` in existing result capability metadata, never copies of old prompt inputs or a diagnostic replay counter. Hash system, protocol and prepared history; retain freshly prepared extras in each request.- Require canonical visible arguments, original unique call IDs, immediately paired result records, compatible local Responses state and unchanged prefix/scope. Legacy records without digests stay as text.- Replay only function calls and encrypted reasoning, with original provider items. Reject known unmasked secrets, textual follow-ups, unsupported items, incomplete pairs and non-text result layouts.- Build tool outputs from visible rendered result content, preserving additional fields. Never restore raw tool output metadata or invent a final response-tool result.diff --git a/helpers/responses_tools.py b/helpers/responses_tools.pyindex b6c9ba8bb..72cc3b05d 100644--- a/helpers/responses_tools.py+++ b/helpers/responses_tools.py@@ -109,6 +109,22 @@ BUNDLED_TOOL_PARAMETERS: dict[str, dict[str, Any]] = {}+def register_prompt(agent: Any, loop_data: Any, section: str, prompt: str) -> None:+ """Record request-only alternatives without changing the rendered text prompt."""+ replacements = loop_data.params_temporary.setdefault("responses_prompt_replacements", {})+ if section == "main":+ communication = agent.read_prompt("agent.system.main.communication.md")+ if communication in prompt:+ replacements[communication] = agent.read_prompt("agent.system.main.communication.native.md")+ elif section == "tools":+ replacements[prompt] = ""+ elif section == "mcp" and prompt:+ from helpers.mcp_handler import MCPConfig++ servers = MCPConfig.get_for_agent(agent).get_tools_prompt(agent=agent, include_tools=False)+ replacements[prompt] = agent.read_prompt("agent.system.mcp_tools.native.md", tools=servers) if servers else ""++def build_responses_function_tools(agent: Any) -> tuple[list[dict[str, Any]], dict[str, str]]:"""Build Responses function tools from available implementations and prompt/MCP schemas."""diff --git a/helpers/responses_tools.py.dox.md b/helpers/responses_tools.py.dox.mdindex 9c0081de4..70ddae909 100644--- a/helpers/responses_tools.py.dox.md+++ b/helpers/responses_tools.py.dox.md@@ -31,6 +31,8 @@- `project_system_prompt` applies build-local substitutions only to system/developer input on a copy. Match rendered JSON-fence normalization; preserve user/history content and unrelated blocks. Chat inputs remain untouched for fallback.- Connector remote tools are advertised only when `_a0_connector` runtime metadata says the matching connected CLI capability is currently available.+- `register_prompt` owns request-only alternatives for main, tools, and MCP sections. Section builders identify their section and retain the original text; only this helper selects Responses templates. MCP supplies policy-filtered server context without knowing the endpoint mode.+## Work Guidance- Do not silently truncate local or MCP instructions; prompt owners control their guidance budget.diff --git a/tests/test_prompt_protocol.py b/tests/test_prompt_protocol.pyindex 66a1d2e25..d3379619c 100644--- a/tests/test_prompt_protocol.py+++ b/tests/test_prompt_protocol.py@@ -200,7 +200,7 @@ async def test_native_communication_projection_preserves_custom_main_sections():assert sections == [original]rendered = files.remove_code_fences(original, language='json')result = responses_tools.project_system_prompt(- [{'role':'system','content':rendered}], loop_data.responses_prompt_replacements,+ [{'role':'system','content':rendered}], loop_data.params_temporary["responses_prompt_replacements"],)[0]['content']assert result.startswith('Custom role instructions.')assert result.endswith('Custom project constraints.')diff --git a/tests/test_responses_history.py b/tests/test_responses_history.pyindex 3f5e509e1..6a7032662 100644--- a/tests/test_responses_history.py+++ b/tests/test_responses_history.py@@ -70,11 +70,39 @@ def test_native_replay_uses_visible_results_and_retains_current_extras():assert "DO NOT REPLAY RAW OUTPUT" not in json.dumps(request)assert "Old extras" not in json.dumps(request)assert "responses_history_context" not in request- assert replay._capability_metadata()["native_history_calls"] == 1assert records == originalassert prompt == prompt_for(records)+def test_prepared_context_lifecycle_and_post_hook_changes(monkeypatch):+ from types import SimpleNamespace+ from langchain_core.messages import SystemMessage, HumanMessage+ from langchain_core.prompts import ChatPromptTemplate+ from agent import Agent, LoopData+ from models import LiteLLMChatWrapper+ from helpers import secrets++ agent = object.__new__(Agent)+ agent.context = SimpleNamespace()+ agent.loop_data = LoopData()+ model = LiteLLMChatWrapper(model="test", provider="openai", model_config=None)+ prompt = [SystemMessage("Rules"), HumanMessage("Question")]+ monkeypatch.setattr(secrets, "get_secrets_manager", lambda _: SimpleNamespace(mask_values=lambda text: text))+ history.remember_prompt(agent.loop_data, ChatPromptTemplate.from_messages(prompt).format(), prompt[0], [])+ call = {"model": model, "messages": prompt, "responses_prompt_replacements": {"Rules": "Override"}}+ prepared = history.prepare_call(agent, call)+ assert prepared["responses_history_context"]["prompt"] == BASE+ assert prepared["responses_prompt_replacements"] == {"Rules": "Override"}+ for changed in (+ [SystemMessage("Changed by hook"), prompt[1]],+ [SystemMessage("Rules", additional_kwargs={"provider_control": True}), prompt[1]],+ ):+ assert "responses_history_context" not in history.prepare_call(agent, {**call, "messages": changed})+ agent.loop_data.params_temporary["responses_prompt_replacements"] = {"stale": "value"}+ history.start_prompt(agent.loop_data)+ assert history.prepare_call(agent, {"model": model, "messages": prompt}) == {"responses_prompt_replacements": {}}++@pytest.mark.parametrize("change", ["summary", "arguments", "missing_output", "wrong_id", "attachments", "commentary", "unencrypted", "legacy", "secret"])def test_ineligible_history_stays_in_prepared_text(change):result = completed_call(transport(BASE, BASE))@@ -104,7 +132,6 @@ def test_ineligible_history_stays_in_prepared_text(change):replay = transport(prompt, prompt)replay.kwargs["responses_history_context"]["groups"] = groupsassert replay._responses_request(stream=False)["input"] == prompt- assert replay.native_history_calls == 0@pytest.mark.parametrize("kwargs", [@@ -116,7 +143,6 @@ def test_replay_is_bound_to_current_model_endpoint_and_tool_scope(kwargs):prompt = prompt_for(records)replay = transport(prompt, prompt, records, **kwargs)assert replay._responses_request(stream=False)["input"] == prompt- assert replay.native_history_calls == 0def test_final_response_call_without_result_is_never_fabricated():@@ -154,7 +180,6 @@ def test_multiple_groups_preserve_history_order_without_duplicate_native_ids(duprequest = replay._responses_request(stream=False)calls = [item for item in request["input"] if item.get("type") == "function_call"]assert [item["call_id"] for item in calls] == (["call_1"] if duplicate else ["call_1", "call_2"])- assert replay.native_history_calls == len(calls)assert request["input"][-1]["content"].endswith("Current extras")diff --git a/tests/test_tool_policy.py b/tests/test_tool_policy.pyindex f133d9081..13af5be99 100644--- a/tests/test_tool_policy.py+++ b/tests/test_tool_policy.py@@ -785,7 +785,12 @@ def test_mcp_prompt_and_native_schema_omit_blocked_tool(assert len(restricted_schemas) == 1assert set(allowed_name_map.values()) == {"docs.read", "docs.write"}assert name_map[restricted_schemas[0]["name"]] == "docs.read"- native_prompt = config.get_tools_prompt(agent=restricted_agent, native=True)+ server_context = config.get_tools_prompt(agent=restricted_agent, include_tools=False)+ assert "Context only: Documentation" in server_context+ loop_data = SimpleNamespace(params_temporary={})+ monkeypatch.setattr(mcp_handler.MCPConfig, "get_for_agent", lambda agent: config)+ responses_tools.register_prompt(restricted_agent, loop_data, "mcp", restricted_prompt)+ native_prompt = loop_data.params_temporary["responses_prompt_replacements"][restricted_prompt]assert "Context only: Documentation" in native_promptassert "Server descriptions are context, not callable capabilities" in native_promptassert "tool_args" not in native_prompt and "docs.write" not in native_prompt@@ -802,7 +807,7 @@ def test_mcp_prompt_and_native_schema_omit_blocked_tool(assert config.get_tools_prompt(agent=_Agent(tmp_path)) == ""assert reads == 1- assert config.get_tools_prompt(agent=_Agent(tmp_path), native=True) == ""+ assert config.get_tools_prompt(agent=_Agent(tmp_path), include_tools=False) == ""assert reads == 2