| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437 |
- """Subagent result post-processing: summary budget/spill, tool-trace summaries, lifecycle hooks and cost rollup."""
- from __future__ import annotations
- import logging
- import json
- import threading
- from typing import Any, Dict, List, Optional
- from urllib.parse import urlsplit, urlunsplit
- from tools.delegation_redaction import (
- parent_copy, redact_child_result, redact_child_text, redact_child_value, redact_summary,
- )
- logger = logging.getLogger("tools.delegate_tool") # log-record parity with the origin module
- def _stringify_tool_content(content: Any) -> str:
- """Stable text for tool-result content. Some OpenAI-compatible paths return
- content-block lists; observability must never crash on them."""
- if content is None:
- return ""
- if isinstance(content, str):
- return content
- if isinstance(content, list):
- return "\n".join(
- item["text"] if isinstance(item, dict) and isinstance(item.get("text"), str)
- else json.dumps(item, ensure_ascii=False, default=str) if isinstance(item, dict)
- else str(item)
- for item in content
- )
- if isinstance(content, dict):
- return json.dumps(content, ensure_ascii=False, default=str)
- return str(content)
- def _looks_like_error_output(content: Any) -> bool:
- """Conservative error detector for tool-result previews: structured JSON with
- an ``error`` key or an error/failed ``status``, or a first line starting with a
- classic error marker. (Substring "error" alone painted normal output red.)"""
- content = _stringify_tool_content(content)
- if not content:
- return False
- if content.lstrip().startswith(("{", "[")):
- try:
- parsed = json.loads(content)
- except Exception:
- parsed = None
- if isinstance(parsed, dict) and (
- parsed.get("error") or str(parsed.get("status") or "").strip().lower() in {"error", "failed", "failure", "timeout"}
- ):
- return True
- first = content.splitlines()[0].strip().lower() if content.splitlines() else ""
- return first.startswith(("error:", "failed:", "traceback ", "exception:"))
- def _extract_output_tail(result: dict[str, Any], *, max_entries: int = 12, max_chars: int = 8000) -> list[dict[str, Any]]:
- """Last N tool-call results ``{tool, preview, is_error}`` from a child's conversation (the overlay's "Output"
- section), chronological order. Content blocks are flattened first so a block-wrapped "Error: ..." is still
- flagged; line structure is preserved (capped at ``max_chars``) so the overlay shows real output rather than a
- whitespace-collapsed blob."""
- messages = result.get("messages") if isinstance(result, dict) else None
- if not isinstance(messages, list):
- return []
- name_by_call_id = {
- tc["id"]: str((tc.get("function") or {}).get("name") or "tool")
- for msg in messages if isinstance(msg, dict) and msg.get("role") == "assistant"
- for tc in msg.get("tool_calls") or [] if tc.get("id")
- }
- tail: list[dict[str, Any]] = []
- for msg in reversed(messages): # newest first, then restore order below
- if len(tail) >= max_entries:
- break
- if not isinstance(msg, dict) or msg.get("role") != "tool":
- continue
- # Live progress (subagent.complete overlay): honours security.redact_secrets=false.
- content = redact_child_text(_stringify_tool_content(msg.get("content") or ""), force=False)
- tool_name = name_by_call_id.get(msg.get("tool_call_id") or "", "tool")
- tail.append({"tool": tool_name, "preview": content[:max_chars], "is_error": _looks_like_error_output(content)})
- tail.reverse()
- return tail
- _TOOL_INPUT_TARGET_KEYS = frozenset({
- "cwd", "destination_path", "directory", "dst", "endpoint", "file_path", "new_path", "old_path", "path",
- "source_path", "src", "target_path", "url", "urls",
- })
- _TOOL_INPUT_URL_KEYS = frozenset({"endpoint", "url", "urls"})
- def _sanitize_tool_target(key: str, value: Any, force: bool = True) -> Any:
- """Keep bounded side-effect targets while dropping URL secrets."""
- if isinstance(value, list):
- cleaned = [item for item in (_sanitize_tool_target(key, item, force) for item in value[:16]) if item is not None]
- return cleaned or None
- if not isinstance(value, str) or not value:
- return None
- bounded = redact_child_text(value, force=force)[:1024]
- if key in _TOOL_INPUT_URL_KEYS:
- try:
- parsed = urlsplit(bounded)
- if parsed.scheme and parsed.netloc:
- hostname = parsed.hostname
- if not hostname:
- return None
- # ``SplitResult.netloc`` includes ``user:password@``. Rebuild the authority from parsed host/port so
- # hook-visible history cannot carry URL credentials. Bracket IPv6 literals before appending a
- # validated port.
- host = f"[{hostname}]" if ":" in hostname else hostname
- netloc = f"{host}:{parsed.port}" if parsed.port is not None else host
- return urlunsplit((parsed.scheme, netloc, parsed.path, "", ""))
- except ValueError:
- return None
- return bounded
- def _sanitize_targets(mapping: dict[str, Any], force: bool = True) -> dict[str, Any]:
- """Keep only known side-effect target keys, each sanitized (URL secrets dropped)."""
- targets: dict[str, Any] = {}
- for raw_key, value in mapping.items():
- key = str(raw_key).lower()
- if key in _TOOL_INPUT_TARGET_KEYS:
- cleaned = _sanitize_tool_target(key, value, force)
- if cleaned is not None:
- targets[key] = cleaned
- return targets
- def _input_summary(keys: Any, targets: Any, force: bool = True) -> dict[str, Any]:
- """``{argument_keys, targets}`` with bounded, sanitized contents (empty on bad shapes). ``force=False`` for the
- parent's own tool_trace copy (honours the opt-out); lifecycle hooks re-sanitize with ``force=True``."""
- return {
- "argument_keys": [redact_child_text(str(key), force=force)[:128] for key in keys[:64]] if isinstance(keys, list) else [],
- "targets": _sanitize_targets(targets, force) if isinstance(targets, dict) else {},
- }
- def _summarize_tool_arguments(arguments: Any) -> dict[str, Any]:
- """Summarize argument names and side-effect targets without raw payloads."""
- try:
- parsed = json.loads(arguments) if isinstance(arguments, str) else None
- except (TypeError, ValueError):
- parsed = None
- if not isinstance(parsed, dict):
- return _input_summary([], {})
- return _input_summary(sorted(str(key) for key in parsed), parsed, force=False)
- def _subagent_stop_tool_call_history(tool_trace: Any) -> list[dict[str, Any]]:
- """Detached, metadata-only tool history for lifecycle hooks (input summaries re-sanitized)."""
- if not isinstance(tool_trace, list):
- return []
- def _byte_count(item, key: str) -> int:
- value = item.get(key, 0)
- return max(0, int(value)) if isinstance(value, (int, float)) and not isinstance(value, bool) else 0
- history: list[dict[str, Any]] = []
- for item in tool_trace:
- if not isinstance(item, dict):
- continue
- status = str(item.get("status") or "unknown").lower()
- summary = item.get("input_summary")
- summary = summary if isinstance(summary, dict) else {}
- history.append({
- "tool_name": str(item.get("tool") or "unknown")[:256],
- "tool_input": _input_summary(summary.get("argument_keys"), summary.get("targets")),
- "input_bytes": _byte_count(item, "args_bytes"), "output_bytes": _byte_count(item, "result_bytes"),
- "status": status if status in {"ok", "error"} else "unknown",
- })
- return history
- # Hard per-summary character ceiling layered on top of the dynamic headroom budget (see _apply_summary_budget):
- # belt-and-suspenders for models that ignore "be concise". 0 disables the ceiling.
- DEFAULT_MAX_SUMMARY_CHARS = 24000
- # Fraction of the parent's *remaining* context headroom the whole batch of summaries may consume, split per summary,
- # so N children can't collectively blow the parent's window (the compression/429 death spiral).
- _SUMMARY_HEADROOM_FRACTION = 0.5
- # Floor so a single summary always gets a usable slice even when the parent is
- # already nearly full — below this we'd be truncating to noise.
- _MIN_SUMMARY_CHARS = 2000
- def _spill_summary_to_file(task_index: int, summary: str) -> Optional[str]:
- """Write the full summary under ``cache/delegation`` (mounted read-only into remote backends via
- ``credential_files._CACHE_DIRS``, so the parent's terminal/``read_file`` can page it on any backend). Absolute
- path, or None on failure — the trimmed head+tail is still returned regardless."""
- try:
- from hermes_constants import get_hermes_dir
- import datetime as _dt
- cache_dir = get_hermes_dir("cache/delegation", "delegation_cache")
- cache_dir.mkdir(parents=True, exist_ok=True)
- path = cache_dir / f"subagent-summary-{task_index}-{_dt.datetime.now().strftime('%Y%m%d_%H%M%S_%f')}.txt"
- from tools.spill_safety import write_text_exclusive
- # Exclusive symlink-refusing create; not private because cache/delegation is bind-mounted read-only into
- # remote backends whose container UID must be able to read it.
- # ``summary`` is already the forced, structure-preserving projection (_trim_summary_with_footer); a
- # second whole-text pass here would eat JSON delimiters and corrupt a valid structured answer.
- write_text_exclusive(path, getattr(summary, "forced", summary), private=False)
- return str(path)
- except Exception as exc:
- logger.debug("Failed to spill subagent summary to file: %s", exc)
- return None
- def _trim_summary_with_footer(summary: str, cap: int, task_index: int) -> tuple[str, Optional[str]]:
- """``(model_text, spill_path)`` for one over-budget summary: a ~75% head / ~25% tail window snapped to line
- boundaries (so the opening AND the closing outcomes/files-changed/issues both survive), the full text spilled
- to disk, and a footer giving the exact ``read_file offset=`` for the omitted middle."""
- # ``summary`` is the parent's copy (scrubbed per the user's setting in _finalize_child_results), carrying the
- # forced projection of the COMPLETE output. The spill file and the forced (memory/hook/ledger) excerpt are cut
- # from that projection: trimming the opt-out copy first can drop a PEM BEGIN marker and leave an unrecognizable
- # key body behind. Direct callers pass plain text: project it here (idempotent on already-forced text).
- forced = redact_child_text(summary) if hasattr(summary, "forced") else redact_summary(summary, True, True)
- spill_path = _spill_summary_to_file(task_index, forced)
- if spill_path:
- # Agent-visible path: the parent's read_file runs inside the active backend (#81984, #77015).
- from tools.credential_files import to_agent_visible_cache_path
- spill_path = to_agent_visible_cache_path(spill_path)
- model_text = _head_tail_with_footer(str(summary), cap, spill_path)
- return parent_copy(model_text, _head_tail_with_footer(forced, cap, spill_path)), spill_path
- def _head_tail_with_footer(summary: str, cap: int, spill_path: Optional[str]) -> str:
- original_len = len(summary)
- head_budget = int(cap * 0.75)
- tail_budget = cap - head_budget
- head, tail = summary[:head_budget], summary[-tail_budget:]
- nl = head.rfind("\n")
- if nl > head_budget * 0.5:
- head = head[:nl]
- nl = tail.find("\n")
- if 0 <= nl < tail_budget * 0.5:
- tail = tail[nl + 1:]
- footer_lines = [
- "", "─" * 8 + " [SUMMARY TRUNCATED] " + "─" * 8,
- f"Showing {len(head):,} chars (head) + {len(tail):,} chars (tail) "
- f"of {original_len:,} total — trimmed to protect the parent's context window.",
- ]
- if spill_path:
- # read_file is 1-indexed; +2 moves past the last head line shown.
- footer_lines.append(f"Full subagent output saved to: {spill_path}")
- footer_lines.append(
- f'To read the omitted middle: read_file path="{spill_path}" '
- f"offset={head.count(chr(10)) + 2} limit=200 (the file is the complete "
- f"summary; raise/lower offset to page through it)."
- )
- else:
- footer_lines.append("Full output could not be stored to disk; the head+tail above is all that was preserved.")
- footer_lines.append("─" * 37)
- return head + "\n\n[... middle omitted — see footer ...]\n\n" + tail + "\n".join(footer_lines)
- def _parent_prompt_size_tokens(parent_agent) -> Optional[int]:
- """The parent's current prompt size: the aggregator's own last ``prompt_tokens`` (pre-MoA-fold), else
- the last provider usage. ``None`` when no request has completed yet: the caller then applies the
- static ceiling only. Treating "no usage yet" as zero handed a 190K/200K parent a 384K-char budget."""
- size = getattr(parent_agent, "_last_prompt_size_tokens", None)
- if isinstance(size, (int, float)) and size > 0:
- return int(size)
- last_usage = getattr(parent_agent, "_last_turn_usage", None) or {}
- used = last_usage.get("prompt_tokens") if isinstance(last_usage, dict) else None
- if isinstance(used, (int, float)) and used > 0:
- return int(used)
- return None
- def _parent_summary_char_budget(parent_agent, n_summaries: int) -> Optional[int]:
- """Per-summary char budget from the parent's *remaining* context headroom (context length − the parent's
- current prompt size − the compressor's output reserve), a fraction of it split across the batch at ~4
- chars/token. None when the parent's context state is unknown — caller then uses the static ceiling only.
- "Current prompt size" is the last API call's ``prompt_tokens`` (``_last_turn_usage``), never
- ``session_prompt_tokens``: that field is the running SUM over every call in the session, so after a
- few hundred calls it exceeds any context window and every summary collapsed to the 2,000-char floor
- (measured: all 1,393 child summaries in one run, each spilled to disk, the orchestrator working from
- the stub)."""
- try:
- compressor = getattr(parent_agent, "context_compressor", None)
- context_length = getattr(compressor, "context_length", None)
- if not isinstance(context_length, int) or context_length <= 0:
- return None
- used_tokens = _parent_prompt_size_tokens(parent_agent)
- if used_tokens is None:
- return None # no usage yet and nothing to estimate from: static ceiling only, never "zero context"
- headroom_tokens = context_length - int(used_tokens) - int(getattr(compressor, "max_tokens", 0) or 0)
- if headroom_tokens <= 0:
- return _MIN_SUMMARY_CHARS # parent already over budget: floor only
- per_summary_tokens = int(headroom_tokens * _SUMMARY_HEADROOM_FRACTION) // max(1, n_summaries)
- return max(_MIN_SUMMARY_CHARS, per_summary_tokens * 4)
- except Exception:
- logger.debug("Summary budget computation failed", exc_info=True)
- return None
- def _apply_summary_budget(results: list[dict[str, Any]], parent_agent) -> None:
- """Trim subagent summaries in-place so a batch can't overflow the parent's context window (full text spilled to
- disk). Per-summary cap = MIN(dynamic headroom budget, static ``delegation.max_summary_chars`` ceiling; 0 =
- disabled); over-cap summaries become head+tail plus a pointer to the spill file."""
- from tools.delegate_tool import _load_config
- summaries = [r for r in results if isinstance(r, dict) and isinstance(r.get("summary"), str) and r["summary"]]
- if not summaries:
- return
- try:
- static_ceiling = int(_load_config().get("max_summary_chars", DEFAULT_MAX_SUMMARY_CHARS))
- except (TypeError, ValueError):
- static_ceiling = DEFAULT_MAX_SUMMARY_CHARS
- candidates = [c for c in (static_ceiling, _parent_summary_char_budget(parent_agent, len(summaries))) if c and c > 0]
- if not candidates:
- return # both disabled / unknown → leave summaries untouched
- cap = min(candidates)
- for entry in summaries:
- summary = entry["summary"]
- if len(summary) <= cap:
- continue
- model_text, spill_path = _trim_summary_with_footer(summary, cap, entry.get("task_index", -1))
- entry["summary"] = model_text
- entry["summary_truncated"] = True
- if spill_path:
- entry["summary_full_path"] = spill_path
- logger.debug(
- "[subagent-%s] summary trimmed %d → ~%d chars (spill=%s)", entry.get("task_index", "?"), len(summary), cap,
- spill_path or "none",
- )
- _PARENT_FINALIZATION_LOCK_GUARD = threading.Lock()
- _PARENT_FINALIZATION_FALLBACK_LOCK = threading.RLock()
- _CHILD_CONSTRUCTION_LOCK = threading.RLock()
- def _build_child_preserving_parent_tools(**kwargs):
- """Build a child without leaking its resolved toolset into the parent."""
- from tools.delegate_tool import _build_child_agent
- import model_tools
- with _CHILD_CONSTRUCTION_LOCK:
- parent_tool_names = list(model_tools._last_resolved_tool_names)
- try:
- child = _build_child_agent(**kwargs)
- finally:
- model_tools._last_resolved_tool_names = parent_tool_names
- child._delegate_saved_tool_names = parent_tool_names
- return child
- def _parent_finalization_lock(parent_agent) -> threading.RLock:
- """Per-parent lock serializing lifecycle side effects (created once under the guard)."""
- if parent_agent is None:
- return _PARENT_FINALIZATION_FALLBACK_LOCK
- lock = getattr(parent_agent, "_subagent_finalization_lock", None)
- if lock is not None:
- return lock
- with _PARENT_FINALIZATION_LOCK_GUARD:
- lock = getattr(parent_agent, "_subagent_finalization_lock", None)
- if lock is None:
- lock = threading.RLock()
- try:
- parent_agent._subagent_finalization_lock = lock
- except Exception:
- return _PARENT_FINALIZATION_FALLBACK_LOCK
- return lock
- def _notify_memory_manager(results, task_list, child_by_index, parent_agent) -> None:
- memory = getattr(parent_agent, "_memory_manager", None) if parent_agent else None
- if not memory:
- return
- for entry in results:
- try:
- task_index = entry.get("task_index", -1)
- in_range = isinstance(task_index, int) and 0 <= task_index < len(task_list)
- memory.on_delegation(
- task=task_list[task_index]["goal"] if in_range else "",
- result=redact_child_text(entry.get("summary", "") or "", force=True), # memory providers persist
- child_session_id=getattr(child_by_index.get(task_index), "session_id", ""),
- )
- except Exception:
- pass
- def _fire_subagent_stop_hooks(results, child_by_index, parent_agent) -> float:
- """Pop the model-hidden ``_child_role`` / ``_child_cost_usd`` fields from every
- entry, fire ``subagent_stop`` per child, and return the summed child cost."""
- try:
- from hermes_cli.plugins import invoke_hook
- except Exception:
- invoke_hook = None
- children_cost_total = 0.0
- for entry in results:
- child_role = entry.pop("_child_role", None)
- child_cost = entry.pop("_child_cost_usd", 0.0)
- try:
- if child_cost:
- children_cost_total += float(child_cost)
- except (TypeError, ValueError):
- pass
- if invoke_hook is None:
- continue
- try:
- child = child_by_index.get(entry.get("task_index", -1))
- invoke_hook(
- "subagent_stop", parent_session_id=getattr(parent_agent, "session_id", None),
- parent_turn_id=getattr(parent_agent, "_current_turn_id", "") or "",
- child_session_id=getattr(child, "session_id", None), child_role=child_role,
- child_summary=redact_child_value(entry.get("summary")), # forced: plugins leave the process
- child_status=entry.get("status"),
- tool_call_history=_subagent_stop_tool_call_history(entry.get("tool_trace")),
- duration_ms=int((entry.get("duration_seconds") or 0) * 1000),
- )
- except Exception:
- logger.debug("subagent_stop hook invocation failed", exc_info=True)
- return children_cost_total
- def _rollup_children_cost(parent_agent, children_cost_total: float) -> None:
- """Fold the children's spend into the parent's session cost (source/status
- only set when the parent had none of its own)."""
- if children_cost_total <= 0.0:
- return
- try:
- current = float(getattr(parent_agent, "session_estimated_cost_usd", 0.0) or 0.0)
- parent_agent.session_estimated_cost_usd = current + children_cost_total
- if getattr(parent_agent, "session_cost_source", "none") in {None, "", "none"}:
- parent_agent.session_cost_source = "subagent"
- if getattr(parent_agent, "session_cost_status", "unknown") in {None, "", "unknown"}:
- parent_agent.session_cost_status = "estimated"
- except Exception:
- logger.debug("Subagent cost rollup failed", exc_info=True)
- def _finalize_child_results(
- results: list[dict[str, Any]], task_list: list[dict[str, Any]], children: list[tuple[int, dict[str, Any], Any]],
- parent_agent,
- ) -> None:
- """Apply host-owned summary, memory, hook, and cost contracts once."""
- with _parent_finalization_lock(parent_agent):
- child_by_index = {index: child for index, _task, child in children}
- for entry in results:
- schema = getattr(child_by_index.get(entry.get("task_index")), "_delegate_output_schema", None)
- # Fork the forced, structure-preserving projection from the COMPLETE output before the parent budget
- # trims anything; spill/memory/hooks/the durable row read it. The parent's own copy honours
- # security.redact_secrets=false.
- summary = entry.get("summary")
- forced = redact_summary(summary, isinstance(schema, dict) or "schema_valid" in entry, True)
- entry.update(redact_child_result(entry, schema, force=False))
- if isinstance(summary, str) and isinstance(entry.get("summary"), str):
- entry["summary"] = parent_copy(entry["summary"], forced)
- _apply_summary_budget(results, parent_agent)
- _notify_memory_manager(results, task_list, child_by_index, parent_agent)
- _rollup_children_cost(parent_agent, _fire_subagent_stop_hooks(results, child_by_index, parent_agent))
- def _run_child_lifecycle(task_index: int, goal: str, child=None, parent_agent=None) -> dict[str, Any]:
- """Run one child and apply the same host lifecycle used by delegate_task."""
- from tools.delegate_tool import _run_single_child
- result = _run_single_child(task_index, goal, child, parent_agent)
- result.setdefault("task_index", task_index)
- task = {"goal": goal}
- _finalize_child_results([result], [{"goal": ""} for _ in range(task_index)] + [task], [(task_index, task, child)], parent_agent)
- return result
|