hermes-trace/_state.py

451 lines
15 KiB
Python

from __future__ import annotations
import json
import logging
import os
import sqlite3
import threading
import time
from typing import Any
logger = logging.getLogger(__name__)
_TEXT_ITEM_TYPES = {"text", "input_text", "output_text"}
def _env_int(
name: str,
default: int,
min_val: int,
max_val: int | None = None,
) -> int:
"""Parse an integer from an env var with validation and fallback."""
raw = os.environ.get(name)
if raw is None:
return default
try:
val = int(raw)
except ValueError:
logger.warning("Invalid %s=%r, falling back to %d", name, raw, default)
return default
if val < min_val or (max_val is not None and val > max_val):
logger.warning(
"%s=%d out of range [%d, %s], falling back to %d",
name,
val,
min_val,
max_val or "∞",
default,
)
return default
return val
def _preview_text(content: Any) -> str:
"""Normalize message content to a plain-text preview string."""
if content is None:
return ""
if isinstance(content, str):
return content
if isinstance(content, list):
parts = [
str(part.get("text", ""))
for part in content
if isinstance(part, dict) and part.get("text")
]
return "\n".join(parts) or json.dumps(content, ensure_ascii=False, default=str)
return str(content)
def _responses_reasoning_summary(item: dict[str, Any]) -> str:
"""Extract readable summary text from a Responses reasoning item."""
summary = item.get("summary")
if isinstance(summary, str):
return summary
if not isinstance(summary, list):
return ""
parts = [
str(part.get("text", ""))
for part in summary
if isinstance(part, dict) and part.get("text")
]
return "\n".join(parts)
def _merge_assistant_item(
messages: list[dict[str, Any]],
item: dict[str, Any],
) -> None:
"""Merge contiguous Responses assistant items into one chat-style message."""
if not messages or messages[-1].get("role") != "assistant":
messages.append(item)
return
target = messages[-1]
content = item.get("content")
if content not in (None, ""):
existing = target.get("content")
target["content"] = (
f"{existing}\n{content}" if existing not in (None, "") else content
)
reasoning_content = item.get("reasoning_content")
if reasoning_content:
existing_reasoning = target.get("reasoning_content")
target["reasoning_content"] = (
f"{existing_reasoning}\n{reasoning_content}"
if existing_reasoning
else reasoning_content
)
if item.get("reasoning_details"):
target.setdefault("reasoning_details", []).extend(item["reasoning_details"])
if item.get("tool_calls"):
target.setdefault("tool_calls", []).extend(item["tool_calls"])
for key, value in item.items():
if (
key
not in {
"role",
"content",
"reasoning_content",
"reasoning_details",
"tool_calls",
}
and key not in target
):
target[key] = value
def _convert_codex_input_to_standard_messages(
codex_input: list[dict[str, Any]],
) -> list[dict[str, Any]]:
"""Convert Responses API input items to a chat-style transcript.
Responses keeps messages, reasoning state, function calls, and function
outputs as separate input items. This projection groups contiguous
assistant-side items so the telemetry view resembles Chat Completions while
retaining encrypted reasoning items in ``reasoning_details``.
Args:
codex_input: List of Responses API input item dicts.
Returns:
Equivalent list of chat-style message dicts.
"""
messages: list[dict[str, Any]] = []
for item in codex_input:
if "type" not in item:
if item.get("role") == "assistant":
_merge_assistant_item(messages, item)
else:
messages.append(item)
continue
item_type = item.get("type", "")
if item_type == "message":
raw_content = item.get("content")
if isinstance(raw_content, list):
text_parts = [
part.get("text", "")
for part in raw_content
if isinstance(part, dict) and part.get("type") in _TEXT_ITEM_TYPES
]
text = (
"\n".join(text_parts)
if text_parts
else json.dumps(raw_content, ensure_ascii=False)
)
else:
text = str(raw_content) if raw_content else ""
message = {
"role": item.get("role", "assistant"),
"content": text,
}
if message["role"] == "assistant":
_merge_assistant_item(messages, message)
else:
messages.append(message)
elif item_type == "reasoning":
message: dict[str, Any] = {
"role": "assistant",
"content": None,
"reasoning_details": [item],
}
summary = _responses_reasoning_summary(item)
if summary:
message["reasoning_content"] = summary
_merge_assistant_item(messages, message)
elif item_type == "function_call":
_merge_assistant_item(
messages,
{
"role": "assistant",
"content": None,
"tool_calls": [
{
"id": item.get("call_id", ""),
"type": "function",
"function": {
"name": item.get("name", ""),
"arguments": item.get("arguments", ""),
},
}
],
},
)
elif item_type == "function_call_output":
messages.append(
{
"role": "tool",
"tool_call_id": item.get("call_id", ""),
"content": item.get("output", ""),
}
)
else:
messages.append(item)
return messages
def _convert_hermes_history_to_standard_messages(
history: list[dict[str, Any]],
) -> list[dict[str, Any]]:
"""Project Hermes canonical history onto the chat-style telemetry shape.
Hermes keeps provider-neutral assistant reasoning on ``reasoning`` and
``reasoning_content`` even when a provider adapter removes thinking blocks
from the wire payload (notably third-party Anthropic-compatible endpoints).
"""
messages: list[dict[str, Any]] = []
for original in history:
if not isinstance(original, dict):
continue
role = original.get("role")
if not role or role == "system":
continue
message: dict[str, Any] = {
"role": role,
"content": original.get("content"),
}
for key in ("name", "tool_call_id", "tool_calls"):
if key in original:
message[key] = original[key]
if role == "assistant":
reasoning_content = original.get("reasoning_content")
if not reasoning_content:
reasoning = original.get("reasoning")
if isinstance(reasoning, str) and reasoning:
reasoning_content = reasoning
else:
details = original.get("reasoning_details")
if isinstance(details, list):
thinking_parts = [
detail.get("thinking")
for detail in details
if isinstance(detail, dict)
and detail.get("type") == "thinking"
and isinstance(detail.get("thinking"), str)
and detail.get("thinking")
]
if thinking_parts:
reasoning_content = "\n\n".join(thinking_parts)
if reasoning_content:
message["reasoning_content"] = reasoning_content
if original.get("reasoning_details"):
message["reasoning_details"] = original["reasoning_details"]
messages.append(message)
return messages
def _convert_anthropic_messages_to_standard_messages(
anthropic_messages: list[dict[str, Any]],
) -> list[dict[str, Any]]:
"""Convert Anthropic assistant content blocks to chat-style messages.
Anthropic stores thinking, visible text, and tool use as sibling blocks in
``assistant.content``. The telemetry UI is easier to compare across
providers when those blocks are projected onto the familiar chat fields.
Opaque thinking blocks are retained in ``reasoning_details``.
"""
messages: list[dict[str, Any]] = []
for original in anthropic_messages:
if original.get("role") != "assistant" or not isinstance(
original.get("content"), list
):
messages.append(dict(original))
continue
message = {k: v for k, v in original.items() if k != "content"}
text_parts: list[str] = []
reasoning_parts: list[str] = []
reasoning_details: list[dict[str, Any]] = []
tool_calls: list[dict[str, Any]] = []
other_blocks: list[Any] = []
for block in original["content"]:
if not isinstance(block, dict):
other_blocks.append(block)
continue
block_type = block.get("type")
if block_type == "text":
text = block.get("text")
if isinstance(text, str) and text:
text_parts.append(text)
elif block_type == "thinking":
thinking = block.get("thinking")
if isinstance(thinking, str) and thinking:
reasoning_parts.append(thinking)
reasoning_details.append(block)
elif block_type == "redacted_thinking":
reasoning_details.append(block)
elif block_type == "tool_use":
tool_calls.append(
{
"id": block.get("id", ""),
"type": "function",
"function": {
"name": block.get("name", ""),
"arguments": json.dumps(
block.get("input", {}),
ensure_ascii=False,
default=str,
),
},
}
)
else:
other_blocks.append(block)
if text_parts:
message["content"] = "\n".join(text_parts)
elif other_blocks:
message["content"] = other_blocks
else:
message["content"] = None
if reasoning_parts:
message["reasoning_content"] = "\n\n".join(reasoning_parts)
if reasoning_details:
message["reasoning_details"] = reasoning_details
if tool_calls:
message["tool_calls"] = tool_calls
messages.append(message)
return messages
def _get_system_prompt_from_state_db(session_id: str) -> str | None:
"""Read system prompt from Hermes session state DB.
Session DB stores the assembled system prompt in ``sessions.system_prompt``.
This is the only reliable fallback for Codex/Responses API transport,
where the system prompt lives in ``api_kwargs[\"instructions\"]`` (extracted
from messages, not in the input items) and the sanitised ``request`` payload
is routinely truncated at 50 KB by ``_sanitize_hook_payload``.
"""
try:
from hermes_constants import (
get_hermes_home as _get_home, # type: ignore[reportMissingImports]
)
db_path = _get_home() / "state.db"
if not db_path.exists():
return None
conn = sqlite3.connect(
f"file:{db_path.resolve()}?mode=ro",
uri=True,
timeout=1.0,
)
try:
row = conn.execute(
"SELECT system_prompt FROM sessions WHERE id = ?",
(session_id,),
).fetchone()
return row[0] if row else None
finally:
conn.close()
except Exception:
logger.debug(
"Failed to read system_prompt from state DB for session %s",
session_id,
exc_info=True,
)
return None
# ---------------------------------------------------------------------------
# Defaults (can be overridden via environment variables)
# ---------------------------------------------------------------------------
_DEFAULT_HOST: str = "127.0.0.1"
_DEFAULT_PORT: int = 7788
_DEFAULT_RETENTION_DAYS: int = 7
# ---------------------------------------------------------------------------
# Module-level state
# ---------------------------------------------------------------------------
#: Per API-call/turn transient state. Keys produced by _state_key().
#: ``_session_state[key]`` is a dict with keys:
#:
#: * ``session_id`` — the Hermes session identifier
#: * ``task_id`` — the Hermes task identifier
#: * ``turn_id`` — the Hermes turn identifier
#: * ``api_request_id`` — the Hermes API request identifier
#: * ``latest_turn_id`` — the DB primary key of the most recently written turn
#: * ``tool_call_counter`` — how many tool calls have been recorded for the
#: current turn (used as ``call_order``)
#: * ``expected_tool_calls`` — number of tool calls expected for this turn
#: * ``request_preview`` — captured by ``on_pre_api_request``
#: * ``full_request`` — captured by ``on_pre_api_request``
_session_state: dict[str, dict[str, Any]] = {}
_STATE_LOCK = threading.Lock()
_STATE_TTL: float = 3600.0 # 1 hour — evict stale hook state entries
def _evict_stale_state() -> None:
"""Remove session state entries older than ``_STATE_TTL``."""
now = time.monotonic()
with _STATE_LOCK:
stale = [
key
for key, state in _session_state.items()
if now - state.get("_created_at", 0) > _STATE_TTL
]
for key in stale:
_session_state.pop(key, None)
def _state_key(
session_id: str,
*,
turn_id: str = "",
task_id: str = "",
api_request_id: str = "",
) -> str:
"""Build a transient state key for one Hermes API-call scope.
Uses Hermes-provided correlation identifiers to prevent cross-thread
clobbering when spawned subagents share the parent's session_id.
Falls back to ``task_id`` then bare ``session_id`` for backward
compatibility when ``turn_id`` is unavailable.
"""
if turn_id:
return f"{session_id}:turn:{turn_id}"
if task_id:
return f"{session_id}:task:{task_id}"
if api_request_id:
return f"{session_id}:api:{api_request_id}"
return session_id
#: Resolved at plugin startup — shared by all hook handlers.
_telemetry_host: str = _DEFAULT_HOST
_telemetry_db_path: str = ""
_telemetry_port: int = _DEFAULT_PORT
_telemetry_retention_days: int = _DEFAULT_RETENTION_DAYS
_LOCK_PATH: str = "" # resolved in register()