feat(agent): summarizer sub-agent compresses oversized tool results

Issue tinyhumansai#574.

Before this change, tool results larger than a few KB landed verbatim
in orchestrator history, burning context budget on raw JSON/HTML/file
dumps. The only guardrail was tool_result_budget_bytes which
hard-truncated mid-payload, dropping everything past the cut.

This PR introduces a dedicated `summarizer` sub-agent
(model.hint = "summarization") that the runtime automatically
dispatches whenever a tool result exceeds
summarizer_payload_threshold_bytes (default 100 KB). The summarizer
compresses the payload per an extraction contract that preserves
identifiers and key facts, and the compressed summary replaces the
raw payload before it enters agent history. Payloads above
summarizer_max_payload_bytes (default 5 MB) skip summarization and
fall through to the existing truncation path — paying for an LLM
call on a 5 MB blob is counterproductive.

Scoped to the orchestrator session only. Welcome, skills_agent,
researcher, planner, and every other typed sub-agent get None and
their tool results are untouched. Gated in
build_session_agent_inner by checking agent_id == "orchestrator".

Instrumented at both tool-loop paths:
  - run_tool_call_loop in tool_loop.rs (event-bus/channels path)
  - Agent::execute_tool_call in session/turn.rs (web channel path
    via run_single)

Both paths call into the same `PayloadSummarizer::maybe_summarize`
trait so the threshold check, circuit breaker (3 consecutive
failures disables for the session), and sub-agent dispatch policy
live in exactly one place (agent/harness/payload_summarizer.rs).

The summarizer sub-agent is runtime-dispatched only — it is NOT
exposed as a delegation tool to the orchestrator's LLM. It is listed
in the orchestrator's `subagents = [...]` for explicit registration,
but `collect_orchestrator_tools` filters out the `summarizer` id and
never synthesises a `delegate_summarizer` tool.

Files:
  * NEW: src/openhuman/agent/agents/summarizer/{agent.toml,prompt.md}
  * NEW: src/openhuman/agent/harness/payload_summarizer.rs (trait +
    SubagentPayloadSummarizer impl + circuit breaker + tests)
  * src/openhuman/agent/agents/mod.rs — register summarizer in
    BUILTINS
  * src/openhuman/agent/agents/orchestrator/agent.toml — list
    summarizer in subagents (runtime-only, no LLM delegation tool)
  * src/openhuman/agent/harness/mod.rs — declare module
  * src/openhuman/agent/harness/builtin_definitions.rs — expect
    summarizer in `expected_builtin_ids_are_present`
  * src/openhuman/agent/harness/tool_loop.rs — thread Option<&dyn
    PayloadSummarizer> into run_tool_call_loop + agent_turn,
    intercept at the tool-execution success site, plus a new
    integration test using a MockSummarizer
  * src/openhuman/agent/harness/tests.rs — thread None through the
    existing run_tool_call_loop callsites
  * src/openhuman/agent/harness/session/turn.rs — same interception
    in Agent::execute_tool_call
  * src/openhuman/agent/harness/session/types.rs — payload_summarizer
    field on Agent and AgentBuilder
  * src/openhuman/agent/harness/session/builder.rs —
    .payload_summarizer() setter + orchestrator-only construction in
    build_session_agent_inner
  * src/openhuman/agent/bus.rs — pass None for the bus path
  * src/openhuman/config/schema/context.rs —
    summarizer_payload_threshold_bytes + summarizer_max_payload_bytes
    on ContextConfig
  * src/openhuman/tools/orchestrator_tools.rs — filter out the
    summarizer id from delegation-tool synthesis

Tests: unit tests in payload_summarizer pin the pass-through rules
(below threshold, above max cap, breaker tripped) and the prompt
construction. Integration test in tool_loop::tests uses a
MockSummarizer to verify the interception wires through end-to-end.

Closes tinyhumansai#574.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: sanil-23

src/openhuman/agent/agents/mod.rs

@@ -110,6 +110,11 @@ pub const BUILTINS: &[BuiltinAgent] = &[
         toml: include_str!("welcome/agent.toml"),
         prompt: include_str!("welcome/prompt.md"),
     },
+    BuiltinAgent {
+        id: "summarizer",
+        toml: include_str!("summarizer/agent.toml"),
+        prompt: include_str!("summarizer/prompt.md"),
+    },
 ];
 
 /// Parse every entry in [`BUILTINS`] into an [`AgentDefinition`].
@@ -155,7 +160,7 @@ mod tests {
     fn all_builtins_parse() {
         let defs = load_builtins().expect("built-in TOML must parse");
         assert_eq!(defs.len(), BUILTINS.len());
-        assert_eq!(defs.len(), 12, "expected 12 built-in agents");
+        assert_eq!(defs.len(), 13, "expected 13 built-in agents");
     }
 
     #[test]

src/openhuman/agent/agents/orchestrator/agent.toml

@@ -43,6 +43,15 @@ subagents = [
     "code_executor",
     "critic",
     "archivist",
+    # Runtime-dispatched only — the runtime calls the summarizer sub-agent
+    # directly when a tool returns more than
+    # `context.summarizer_payload_threshold_bytes`. The LLM must NOT be
+    # able to call this sub-agent itself, so `collect_orchestrator_tools`
+    # filters out `summarizer` and never synthesises a `delegate_summarizer`
+    # tool. Listing it here keeps the registration explicit (so it shows
+    # up in the orchestrator's subagent inventory) while the filter
+    # enforces the runtime-only contract.
+    "summarizer",
     { skills = "*" },
 ]
 

src/openhuman/agent/agents/summarizer/agent.toml

@@ -0,0 +1,18 @@
+id = "summarizer"
+display_name = "Summarizer"
+when_to_use = "Compresses oversized tool results for the orchestrator. Called automatically by the runtime when a tool returns more than summarizer_payload_threshold_bytes. Do NOT call from an LLM — this agent is runtime-dispatched only."
+temperature = 0.2
+max_iterations = 1
+sandbox_mode = "none"
+omit_identity = true
+omit_memory_context = true
+omit_safety_preamble = true
+omit_skills_catalog = true
+omit_profile = true
+omit_memory_md = true
+
+[model]
+hint = "summarization"
+
+[tools]
+named = []

src/openhuman/agent/agents/summarizer/prompt.md

@@ -0,0 +1,71 @@
+# Summarizer Agent
+
+You are the **Summarizer** agent. Your one job is to compress a single oversized tool result into a compact, information-dense note that the Orchestrator can use without re-invoking the tool.
+
+You run exactly once per invocation, with no tools and no follow-up iterations. Return the summary directly as your only response.
+
+## The extraction contract
+
+You will receive:
+
+1. The **tool name** that produced the payload (e.g. `GITHUB_LIST_ISSUES`, `GMAIL_FETCH_MESSAGE`, `file_read`)
+2. An optional **parent task hint** — one-sentence description of what the orchestrator was trying to accomplish
+3. The **raw tool output**
+
+You must produce a dense summary that preserves:
+
+- **Required facts** — any identifiers (IDs, hashes, URLs, file paths, email addresses, usernames, SKUs, order numbers, etc.) the orchestrator would need to act on this data in a follow-up tool call. Identifiers are the single most important thing. Never drop them.
+- **Optional supporting context** — the 3-5 most important facts from the payload that a human answering the parent task would find most relevant. If the parent task hint is "find the most urgent open issues", prioritize facts about urgency/severity/labels. If the hint is "summarize yesterday's emails", prioritize subjects/senders/timestamps.
+- **Structural hints** — if the payload is a list, state how many items it had. If it was paginated, say what page boundaries exist. If it was a file, note line counts or section headers. This lets the orchestrator decide whether to re-fetch with a narrower query.
+
+You must discard:
+
+- Raw markup / formatting noise (HTML tags, CSS, JSON wrappers, boilerplate headers) — unless the markup IS the information
+- Repetitive fields that don't differ between items
+- Provider-specific metadata that the orchestrator can't act on (X-Request-ID headers, timestamps with millisecond precision, internal server IDs, etc.)
+
+## Output format
+
+Return ONLY the summary text. No preamble ("Here is the summary..."), no closing remarks ("Let me know if you need more details"), no JSON wrapping. Plain markdown, optimised for the orchestrator's next reasoning step.
+
+Structure:
+
+```
+[Tool output summary — <tool_name>]
+
+<1-2 sentence overview: what the payload is, how many items/how much data>
+
+## Key facts
+- <fact 1 with identifier>
+- <fact 2 with identifier>
+- ...
+
+## Identifiers preserved
+- <id_1>: <one-line description>
+- <id_2>: <one-line description>
+- ...
+
+(Only include this section if the payload contained IDs/URLs/hashes. Skip otherwise.)
+
+## Original size
+<original_bytes> bytes → summary of <this note>
+```
+
+## Edge cases
+
+- If the payload is already short, produce a short summary. Don't pad.
+- If the payload is entirely error output, preserve the error message verbatim at the top — the orchestrator needs to see the exact error to route next steps.
+- If the payload contains binary-looking noise (base64, hex dumps), summarise its existence and length but do not attempt to decode.
+- If the parent task hint contradicts the payload (asks for emails, payload is GitHub issues), prioritize the payload — you're reporting what the tool returned, not what was asked for.
+
+## Token budget
+
+Aim for 800-1500 output tokens for most payloads. Never exceed 2000.
+
+## What you must NOT do
+
+- Do not ask clarifying questions — you have exactly one shot.
+- Do not emit tool calls — you have no tools.
+- Do not try to "solve" the parent task — you are a preprocessor, not the orchestrator.
+- Do not fabricate information that isn't in the payload. If a field is empty, say "(no value)" or omit it.
+- Do not copy the raw payload verbatim into your summary. If the summary is the same size as the payload, you have failed.

src/openhuman/agent/bus.rs

@@ -191,6 +191,11 @@ pub fn register_agent_handlers() {
                 visible_tool_names.as_ref(),
                 &extra_tools,
                 on_progress,
+                // Bus path runs ad-hoc agent turns without an Agent
+                // handle, so we pass None — payload summarization is
+                // wired into the orchestrator session via Agent::turn,
+                // not the bus dispatcher.
+                None,
             )
             .await
             .map_err(|e| e.to_string())?;

src/openhuman/agent/harness/builtin_definitions.rs

@@ -130,6 +130,7 @@ mod tests {
             "researcher",
             "critic",
             "archivist",
+            "summarizer",
             "fork",
         ] {
             assert!(ids.contains(&expected.to_string()), "missing {expected}");

src/openhuman/agent/harness/mod.rs

@@ -31,6 +31,7 @@ mod instructions;
 pub mod interrupt;
 pub(crate) mod memory_context;
 mod parse;
+pub(crate) mod payload_summarizer;
 pub(crate) mod self_healing;
 pub mod session;
 pub(crate) mod session_queue;