stream_json.py 5.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111
  1. """``hermes chat -q … --format stream-json``: one JSON object per stdout line.
  2. CI runners and orchestrators consume a one-shot run without scraping human-formatted text:
  3. ``system/init`` → ``text`` deltas / ``tool_use`` / ``tool_result`` → one terminal ``result``
  4. envelope (exit code, final text, token stats). Diagnostics and ``session_id`` stay on stderr.
  5. """
  6. from __future__ import annotations
  7. import json
  8. import sys
  9. import time
  10. from typing import Any
  11. _TOOL_OUTPUT_CAP = 5000
  12. def stream_json_requested(args) -> bool:
  13. """True when ``--format stream-json`` was passed; exits 2 on the combinations the protocol forbids
  14. (no query to answer, or the interactive TUI transport) and forces quiet mode on ``args``."""
  15. if getattr(args, "output_format", "text") != "stream-json":
  16. return False
  17. if not (getattr(args, "query", None) or getattr(args, "query_file", None)):
  18. print("Error: --format stream-json requires -q/--query.", file=sys.stderr)
  19. raise SystemExit(2)
  20. if getattr(args, "tui", False):
  21. print("Error: --format stream-json cannot be used with --tui.", file=sys.stderr)
  22. raise SystemExit(2)
  23. args.quiet = True
  24. return True
  25. def _now_ms() -> int:
  26. return int(time.time() * 1000)
  27. class StreamJsonEmitter:
  28. """Agent-callback sink that writes JSONL events to stdout and flushes each line."""
  29. def __init__(self, model: str = "", session_id: str = ""):
  30. self._session_id = session_id
  31. self._start = time.time()
  32. self._tool_started: dict[str, float] = {}
  33. self._emit({"type": "system", "subtype": "init", "model": model, "session_id": session_id})
  34. def attach(self, agent) -> StreamJsonEmitter:
  35. """Route the agent's streaming/tool callbacks into this emitter (``init`` was already written at
  36. construction, before credentials/agent init, so a failed start still yields init + result)."""
  37. agent.stream_delta_callback = self.on_text_delta
  38. agent.tool_progress_callback = self.on_tool_progress
  39. return self
  40. def bind_session(self, session_id: str) -> None:
  41. """Record the id the gateway assigned after ``init`` was written, so an interrupted or failed
  42. run still reports which session holds the accepted work."""
  43. self._session_id = session_id or self._session_id
  44. def on_text_delta(self, text: str | None) -> None:
  45. # Only None/"" (the turn-end sentinel) is dropped: whitespace deltas are part of the text, and
  46. # a consumer concatenating ``text`` events must reproduce the answer byte for byte.
  47. if text:
  48. self._emit({"type": "text", "text": str(text)})
  49. def on_tool_progress(self, event_type: str, tool_name: str | None = None, preview: Any = None, args: Any = None,
  50. **kwargs: Any) -> None:
  51. """``tool.started`` → ``tool_use`` (with ``input`` when the args are a dict); ``tool.completed`` →
  52. ``tool_result``. Other progress events (reasoning, output risk) are not part of the protocol."""
  53. name = tool_name or "unknown"
  54. # Parallel same-name calls would clobber each other's start time under a name-only key.
  55. key = kwargs.get("tool_call_id") or name
  56. if event_type == "tool.started":
  57. self._tool_started[key] = time.time()
  58. payload: dict[str, Any] = {"type": "tool_use", "name": name}
  59. if kwargs.get("tool_call_id"):
  60. payload["tool_call_id"] = kwargs["tool_call_id"]
  61. if isinstance(args, dict):
  62. payload["input"] = args
  63. self._emit(payload)
  64. elif event_type == "tool.completed":
  65. duration = kwargs.get("duration") or (time.time() - self._tool_started.pop(key, time.time()))
  66. output = str(kwargs.get("result") or "")
  67. self._emit({"type": "tool_result", "name": name,
  68. **({"tool_call_id": kwargs["tool_call_id"]} if kwargs.get("tool_call_id") else {}),
  69. "output": output if len(output) <= _TOOL_OUTPUT_CAP else output[:_TOOL_OUTPUT_CAP] + "...",
  70. "duration_ms": int(float(duration) * 1000), "is_error": bool(kwargs.get("is_error", False))})
  71. def emit_result(self, result: Any, session_id: str = "", exit_code: int = 0) -> int:
  72. """Write the terminal ``result`` record (once) and return the process exit code it reports."""
  73. data = result if isinstance(result, dict) else {"final_response": "" if result is None else str(result)}
  74. exit_code = exit_code or (1 if data.get("failed") else 0)
  75. payload = {"type": "result", "session_id": session_id or self._session_id, "exit_code": exit_code,
  76. "text": data.get("final_response") or "",
  77. "tokens": {"input": data.get("input_tokens") or 0, "output": data.get("output_tokens") or 0,
  78. "total": data.get("total_tokens") or 0, "cache_read": data.get("cache_read_tokens") or 0,
  79. "cache_write": data.get("cache_write_tokens") or 0},
  80. "duration_ms": int((time.time() - self._start) * 1000)}
  81. if data.get("error"):
  82. payload["error"] = str(data["error"])
  83. if data.get("replay_gap"):
  84. # The viewer fell behind and re-attached: ``text`` events stopped there; ``text`` is the whole reply.
  85. payload["replay_gap"] = True
  86. self._emit(payload)
  87. print(f"\nsession_id: {session_id or self._session_id}", file=sys.stderr) # same stderr contract as -Q
  88. return exit_code
  89. def _emit(self, obj: dict) -> None:
  90. try:
  91. sys.stdout.write(json.dumps({**obj, "timestamp": _now_ms()}, ensure_ascii=False) + "\n")
  92. sys.stdout.flush()
  93. except (BrokenPipeError, OSError):
  94. pass # consumer closed the pipe — nothing left to report to