@clawpump/claw-agent 0.1.5 → 0.1.7

package/agent/tools/process_registry.py

@@ -100,6 +100,8 @@ class ProcessSession:
     started_at: float = 0.0                     # time.time() of spawn
     exited: bool = False                        # Whether the process has finished
     exit_code: Optional[int] = None             # Exit code (None if still running)
+    completion_reason: str = "exited"           # exited|killed|lost|failed_start|already_exited
+    termination_source: str = ""                # process.kill|kill_all|backend_lost|failed_start
     output_buffer: str = ""                     # Rolling output (last MAX_OUTPUT_CHARS)
     max_output_chars: int = MAX_OUTPUT_CHARS
     detached: bool = False                      # True if recovered from crash (no pipe)
@@ -129,6 +131,7 @@ class ProcessSession:
     _watch_cooldown_until: float = field(default=0.0, repr=False)
     _watch_strike_candidate: bool = field(default=False, repr=False)
     _watch_consecutive_strikes: int = field(default=0, repr=False)
+    _completion_event: threading.Event = field(default_factory=threading.Event, repr=False)
     _lock: threading.Lock = field(default_factory=threading.Lock)
     _reader_thread: Optional[threading.Thread] = field(default=None, repr=False)
     _pty: Any = field(default=None, repr=False)  # ptyprocess handle (when use_pty=True)
@@ -472,6 +475,7 @@ class ProcessRegistry:
                     text=True,
                     timeout=10,
                     creationflags=windows_hide_flags(),
+                    stdin=subprocess.DEVNULL,
                 )
             except (FileNotFoundError, subprocess.TimeoutExpired, OSError):
                 try:
@@ -718,10 +722,14 @@ class ProcessRegistry:
                 session.exit_code = int(result.get("returncode", -1))
                 if session.exit_code == 0:
                     session.exit_code = -1
+                session.completion_reason = "failed_start"
+                session.termination_source = "failed_start"
                 session.output_buffer = result.get("output", "").strip()
         except Exception as e:
             session.exited = True
             session.exit_code = -1
+            session.completion_reason = "failed_start"
+            session.termination_source = "failed_start"
             session.output_buffer = f"Failed to start: {e}"
 
         if not session.exited:
@@ -772,7 +780,9 @@ class ProcessRegistry:
             except Exception as e:
                 logger.debug("Process wait timed out or failed: %s", e)
             session.exited = True
-            session.exit_code = session.process.returncode
+            if session.completion_reason != "killed":
+                session.exit_code = session.process.returncode
+                session.completion_reason = "exited"
             self._move_to_finished(session)
 
     def _env_poller_loop(
@@ -818,6 +828,8 @@ class ProcessRegistry:
                     except (ValueError, IndexError):
                         session.exit_code = -1
                     session.exited = True
+                    if session.completion_reason != "killed":
+                        session.completion_reason = "exited"
                     self._move_to_finished(session)
                     return
 
@@ -825,6 +837,8 @@ class ProcessRegistry:
                 # Environment might be gone (sandbox reaped, etc.)
                 session.exited = True
                 session.exit_code = -1
+                session.completion_reason = "lost"
+                session.termination_source = "backend_lost"
                 self._move_to_finished(session)
                 return
 
@@ -856,7 +870,9 @@ class ProcessRegistry:
         except Exception as e:
             logger.debug("PTY wait timed out or failed: %s", e)
         session.exited = True
-        session.exit_code = pty.exitstatus if hasattr(pty, 'exitstatus') else -1
+        if session.completion_reason != "killed":
+            session.exit_code = pty.exitstatus if hasattr(pty, 'exitstatus') else -1
+            session.completion_reason = "exited"
         self._move_to_finished(session)
 
     def _move_to_finished(self, session: ProcessSession):
@@ -869,6 +885,7 @@ class ProcessRegistry:
         with self._lock:
             was_running = self._running.pop(session.id, None) is not None
             self._finished[session.id] = session
+        session._completion_event.set()
         self._write_checkpoint()
 
         # Only enqueue completion notification on the FIRST move.  Without
@@ -883,6 +900,8 @@ class ProcessRegistry:
                 "session_key": session.session_key,
                 "command": session.command,
                 "exit_code": session.exit_code,
+                "completion_reason": session.completion_reason,
+                "termination_source": session.termination_source,
                 "output": output_tail,
             })
 
@@ -982,7 +1001,9 @@ class ProcessRegistry:
                 if len(session.output_buffer) > session.max_output_chars:
                     session.output_buffer = session.output_buffer[-session.max_output_chars:]
             session.exited = True
-            session.exit_code = rc
+            if session.completion_reason != "killed":
+                session.exit_code = rc
+                session.completion_reason = "exited"
         logger.info(
             "Reconciled session %s: direct child exited with code %s but reader "
             "was still blocked (orphaned pipe). Flipped to exited.",
@@ -1015,6 +1036,8 @@ class ProcessRegistry:
         }
         if session.exited:
             result["exit_code"] = session.exit_code
+            result["completion_reason"] = session.completion_reason
+            result["termination_source"] = session.termination_source
             self._completion_consumed.add(session_id)
         if session.detached:
             result["detached"] = True
@@ -1092,6 +1115,8 @@ class ProcessRegistry:
 
         while time.monotonic() < deadline:
             session = self._refresh_detached_session(session)
+            if session is None:
+                return {"status": "not_found", "error": f"No process with ID {session_id}"}
             # Reconcile against real child state — guards against orphaned-
             # pipe reader hangs where the reader is blocked but the direct
             # child has already exited (issue #17327).
@@ -1101,6 +1126,8 @@ class ProcessRegistry:
                 result = {
                     "status": "exited",
                     "exit_code": session.exit_code,
+                    "completion_reason": session.completion_reason,
+                    "termination_source": session.termination_source,
                     "output": strip_ansi(session.output_buffer[-2000:]),
                 }
                 if timeout_note:
@@ -1117,7 +1144,10 @@ class ProcessRegistry:
                     result["timeout_note"] = timeout_note
                 return result
 
-            time.sleep(1)
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                break
+            session._completion_event.wait(timeout=min(1.0, remaining))
 
         result = {
             "status": "timeout",
@@ -1129,7 +1159,7 @@ class ProcessRegistry:
             result["timeout_note"] = f"Waited {effective_timeout}s, process still running"
         return result
 
-    def kill_process(self, session_id: str) -> dict:
+    def kill_process(self, session_id: str, *, source: str = "process.kill") -> dict:
         """Kill a background process."""
         session = self.get(session_id)
         if session is None:
@@ -1193,9 +1223,16 @@ class ProcessRegistry:
                 }
             session.exited = True
             session.exit_code = -15  # SIGTERM
+            session.completion_reason = "killed"
+            session.termination_source = source
             self._move_to_finished(session)
             self._write_checkpoint()
-            return {"status": "killed", "session_id": session.id}
+            return {
+                "status": "killed",
+                "session_id": session.id,
+                "completion_reason": session.completion_reason,
+                "termination_source": session.termination_source,
+            }
         except Exception as e:
             return {"status": "error", "error": str(e)}
 
@@ -1207,10 +1244,14 @@ class ProcessRegistry:
         if session.exited:
             return {"status": "already_exited", "error": "Process has already finished"}
 
-        # PTY mode -- write through pty handle (expects bytes)
+        # PTY mode -- write through pty handle.
         if hasattr(session, '_pty') and session._pty:
             try:
-                pty_data = data.encode("utf-8") if isinstance(data, str) else data
+                # pywinpty expects str on Windows; ptyprocess expects bytes on POSIX.
+                if _IS_WINDOWS:
+                    pty_data = data.decode("utf-8") if isinstance(data, bytes) else str(data)
+                else:
+                    pty_data = data.encode("utf-8") if isinstance(data, str) else data
                 session._pty.write(pty_data)
                 return {"status": "ok", "bytes_written": len(data)}
             except Exception as e:
@@ -1335,7 +1376,7 @@ class ProcessRegistry:
 
         killed = 0
         for session in targets:
-            result = self.kill_process(session.id)
+            result = self.kill_process(session.id, source="kill_all")
             if result.get("status") in {"killed", "already_exited"}:
                 killed += 1
         return killed
@@ -1490,6 +1531,91 @@ class ProcessRegistry:
 process_registry = ProcessRegistry()
 
 
+def _format_age(seconds: float) -> str:
+    """Human-friendly elapsed string ('18m', '2h3m', '45s')."""
+    try:
+        s = int(max(0, seconds))
+    except (TypeError, ValueError):
+        return "?"
+    if s < 60:
+        return f"{s}s"
+    m, s = divmod(s, 60)
+    if m < 60:
+        return f"{m}m" if s == 0 else f"{m}m{s}s"
+    h, m = divmod(m, 60)
+    return f"{h}h" if m == 0 else f"{h}h{m}m"
+
+
+def _format_async_delegation(evt: dict) -> str:
+    """Format an async-delegation completion into a self-contained re-injection.
+
+    Carries the FULL original task source (goal, the context the parent
+    supplied, toolsets, role, model) plus dispatch time, status, and the
+    complete result summary. When this re-enters the conversation the agent
+    may be deep in unrelated context and won't remember why the subagent
+    existed, so the block is written to stand entirely on its own — enough to
+    use the result OR re-dispatch if the world has moved on.
+    """
+    import time as _time
+
+    deleg_id = evt.get("delegation_id", "unknown")
+    goal = evt.get("goal", "") or ""
+    context = evt.get("context")
+    toolsets = evt.get("toolsets")
+    role = evt.get("role") or "leaf"
+    model = evt.get("model") or "?"
+    status = evt.get("status") or "completed"
+    summary = evt.get("summary")
+    error = evt.get("error")
+    api_calls = evt.get("api_calls", 0)
+    duration = evt.get("duration_seconds", "?")
+    dispatched_at = evt.get("dispatched_at")
+    completed_at = evt.get("completed_at") or _time.time()
+
+    age = ""
+    if isinstance(dispatched_at, (int, float)):
+        age = f" ({_format_age(completed_at - dispatched_at)} ago)"
+
+    lines = [
+        f"[ASYNC DELEGATION COMPLETE — {deleg_id}]",
+        "A background subagent you dispatched earlier has finished. You may "
+        "have moved on since dispatching it; the full task source is below so "
+        "you can act on the result or re-dispatch if things have changed.",
+        "",
+    ]
+    if isinstance(dispatched_at, (int, float)):
+        ts = _time.strftime("%Y-%m-%d %H:%M:%S", _time.localtime(dispatched_at))
+        lines.append(f"Dispatched: {ts}{age}")
+    lines.append(f"Original goal: {goal}")
+    if context:
+        lines.append(f"Context you provided: {context}")
+    if toolsets:
+        lines.append(f"Toolsets: {', '.join(toolsets)}")
+    lines.append(f"Role: {role}   Model: {model}")
+    lines.append(f"Status: {status}   API calls: {api_calls}   Duration: {duration}s")
+    lines.append("--- RESULT ---")
+    if status in ("completed", "success") and summary:
+        lines.append(summary)
+    elif status == "interrupted":
+        lines.append(
+            "The subagent was interrupted before completing"
+            + (f": {error}" if error else ".")
+        )
+        if summary:
+            lines.append("Partial output:")
+            lines.append(summary)
+    else:
+        # error / timeout / failed
+        lines.append(
+            f"The subagent did not complete successfully (status={status})."
+            + (f"\n{error}" if error else "")
+        )
+        if summary:
+            lines.append("Partial output:")
+            lines.append(summary)
+    return "\n".join(lines)
+
+
 def format_process_notification(evt: dict) -> "str | None":
     """Format a process notification event into a [IMPORTANT: ...] message.
 
@@ -1518,11 +1644,29 @@ def format_process_notification(evt: dict) -> "str | None":
         text += "]"
         return text
 
+    if evt_type == "async_delegation":
+        return _format_async_delegation(evt)
+
     _exit = evt.get("exit_code", "?")
     _out = evt.get("output", "")
+    _reason = evt.get("completion_reason") or "exited"
+    _source = evt.get("termination_source") or ""
+    _signal = ""
+    if _exit in {-15, 143, "-15", "143"}:
+        _signal = ", SIGTERM"
+    if _reason == "killed":
+        _status = f"terminated by {_source or 'Hermes'}"
+    elif _reason == "lost":
+        _status = "marked lost because the process backend disappeared"
+    elif _reason == "failed_start":
+        _status = "failed to start"
+    elif _exit == 0:
+        _status = "completed normally"
+    else:
+        _status = "exited"
     return (
-        f"[IMPORTANT: Background process {_sid} completed "
-        f"(exit code {_exit}).\n"
+        f"[IMPORTANT: Background process {_sid} {_status} "
+        f"(exit code {_exit}{_signal}).\n"
         f"Command: {_cmd}\n"
         f"Output:\n{_out}]"
     )

package/agent/tools/read_extract.py

@@ -0,0 +1,248 @@
+"""Stdlib document-to-text extraction for ``read_file``.
+
+Supports Jupyter notebooks, DOCX, and XLSX without adding hard dependencies.
+Malformed documents raise :class:`ExtractionError`; callers can then fall back to
+normal text/binary handling.
+"""
+
+from __future__ import annotations
+
+import json
+import posixpath
+import zipfile
+from pathlib import Path
+from xml.etree import ElementTree as ET
+
+__all__ = ["EXTRACTABLE_EXTENSIONS", "ExtractionError", "extract_document_text", "is_extractable_document"]
+
+EXTRACTABLE_EXTENSIONS = frozenset({".ipynb", ".docx", ".xlsx"})
+MAX_XLSX_BYTES = 50 * 1024 * 1024
+_MAX_XLSX_ROWS_PER_SHEET = 5000
+_MAX_XLSX_COLS = 256
+
+_NS_W = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+_NS_S = "http://schemas.openxmlformats.org/spreadsheetml/2006/main"
+_NS_REL = "http://schemas.openxmlformats.org/officeDocument/2006/relationships"
+_NS_PKG_REL = "http://schemas.openxmlformats.org/package/2006/relationships"
+
+
+class ExtractionError(Exception):
+    """Raised when a supported-looking document cannot be rendered as text."""
+
+
+def _extension(path: str) -> str:
+    ext = Path(path).suffix.lower()
+    return ext if ext in EXTRACTABLE_EXTENSIONS else ""
+
+
+def is_extractable_document(path: str) -> bool:
+    return bool(_extension(path))
+
+
+def extract_document_text(path: str) -> str:
+    ext = _extension(path)
+    if ext == ".ipynb":
+        return _extract_notebook(path)
+    if ext == ".docx":
+        return _extract_docx(path)
+    if ext == ".xlsx":
+        return _extract_xlsx(path)
+    raise ExtractionError(f"Unsupported document type: {path!r}")
+
+
+def _source_text(source) -> str:
+    if isinstance(source, str):
+        return source
+    if isinstance(source, list):
+        return "".join(item for item in source if isinstance(item, str))
+    return ""
+
+
+def _extract_notebook(path: str) -> str:
+    try:
+        with open(path, encoding="utf-8", errors="replace") as fh:
+            nb = json.load(fh)
+    except (OSError, ValueError, json.JSONDecodeError) as exc:
+        raise ExtractionError(f"Not a valid notebook: {exc}") from exc
+    if not isinstance(nb, dict):
+        raise ExtractionError("Notebook root is not an object")
+
+    cells = nb.get("cells")
+    if not isinstance(cells, list):
+        cells = [
+            cell
+            for ws in nb.get("worksheets", [])
+            if isinstance(ws, dict)
+            for cell in ws.get("cells", [])
+        ]
+    if not cells:
+        raise ExtractionError("Notebook contains no cells")
+
+    counts = {"markdown": 0, "code": 0, "raw": 0}
+    labels = {"markdown": "Markdown", "code": "Code", "raw": "Raw"}
+    out: list[str] = []
+    for cell in cells:
+        if not isinstance(cell, dict):
+            continue
+        typ = cell.get("cell_type")
+        if typ not in labels:
+            continue
+        counts[typ] += 1
+        suffix = f" {counts[typ]}" if typ != "raw" else ""
+        out.extend((f"# ── {labels[typ]} cell{suffix} ──", _source_text(cell.get("source", "")).rstrip("\n"), ""))
+    if not out:
+        raise ExtractionError("Notebook contains no readable cells")
+    return "\n".join(out).rstrip("\n") + "\n"
+
+
+def _zip_xml(zf: zipfile.ZipFile, name: str) -> ET.Element:
+    try:
+        return ET.fromstring(zf.read(name))
+    except KeyError as exc:
+        raise ExtractionError(f"Missing {name}") from exc
+    except ET.ParseError as exc:
+        raise ExtractionError(f"Malformed XML in {name}: {exc}") from exc
+
+
+def _extract_docx(path: str) -> str:
+    try:
+        with zipfile.ZipFile(path) as zf:
+            root = _zip_xml(zf, "word/document.xml")
+    except zipfile.BadZipFile as exc:
+        raise ExtractionError(f"Not a valid DOCX: {exc}") from exc
+    except OSError as exc:
+        raise ExtractionError(str(exc)) from exc
+
+    w = f"{{{_NS_W}}}"
+    lines: list[str] = []
+    for para in root.iter(f"{w}p"):
+        buf: list[str] = []
+        for node in para.iter():
+            if node.tag == f"{w}t":
+                buf.append(node.text or "")
+            elif node.tag == f"{w}tab":
+                buf.append("\t")
+            elif node.tag in {f"{w}br", f"{w}cr"}:
+                buf.append("\n")
+        lines.extend("".join(buf).split("\n"))
+    if not any(line.strip() for line in lines):
+        raise ExtractionError("DOCX contains no extractable text")
+    return "\n".join(lines).rstrip("\n") + "\n"
+
+
+def _extract_xlsx(path: str) -> str:
+    try:
+        with zipfile.ZipFile(path) as zf:
+            names = set(zf.namelist())
+            shared = _shared_strings(zf, names)
+            sheets = _workbook_sheets(zf)
+            rels = _workbook_rels(zf, names)
+            out: list[str] = []
+            for name, state, rid in sheets:
+                if state in {"hidden", "veryHidden"}:
+                    continue
+                part = _sheet_part(rels.get(rid, ""))
+                if part not in names:
+                    continue
+                try:
+                    rows = _sheet_rows(zf.read(part), shared)
+                except ET.ParseError:
+                    continue
+                out.append(f"# ── Sheet: {name} ──")
+                out.extend("\t".join(row) for row in rows)
+                if not rows:
+                    out.append("(empty)")
+                out.append("")
+    except zipfile.BadZipFile as exc:
+        raise ExtractionError(f"Not a valid XLSX: {exc}") from exc
+    except OSError as exc:
+        raise ExtractionError(str(exc)) from exc
+
+    if not out:
+        raise ExtractionError("XLSX has no visible sheets with content")
+    return "\n".join(out).rstrip("\n") + "\n"
+
+
+def _shared_strings(zf: zipfile.ZipFile, names: set[str]) -> list[str]:
+    if "xl/sharedStrings.xml" not in names:
+        return []
+    try:
+        root = ET.fromstring(zf.read("xl/sharedStrings.xml"))
+    except ET.ParseError:
+        return []
+    s = f"{{{_NS_S}}}"
+    return ["".join(t.text or "" for t in item.iter(f"{s}t")) for item in root.iter(f"{s}si")]
+
+
+def _workbook_sheets(zf: zipfile.ZipFile) -> list[tuple[str, str, str]]:
+    root = _zip_xml(zf, "xl/workbook.xml")
+    s, r = f"{{{_NS_S}}}", f"{{{_NS_REL}}}"
+    return [
+        (sheet.get("name", "Sheet"), sheet.get("state", "visible"), sheet.get(f"{r}id", ""))
+        for sheet in root.iter(f"{s}sheet")
+    ]
+
+
+def _workbook_rels(zf: zipfile.ZipFile, names: set[str]) -> dict[str, str]:
+    rels_path = "xl/_rels/workbook.xml.rels"
+    if rels_path not in names:
+        return {}
+    try:
+        root = ET.fromstring(zf.read(rels_path))
+    except ET.ParseError:
+        return {}
+    rel_tag = f"{{{_NS_PKG_REL}}}Relationship"
+    return {rel.get("Id", ""): rel.get("Target", "") for rel in root.iter(rel_tag) if rel.get("Id")}
+
+
+def _sheet_part(target: str) -> str:
+    target = target.lstrip("/")
+    return posixpath.normpath(target if target.startswith("xl/") else f"xl/{target}")
+
+
+def _col_index(ref: str) -> int:
+    idx = 0
+    for ch in ref:
+        if not ch.isalpha():
+            break
+        idx = idx * 26 + ord(ch.upper()) - ord("A") + 1
+    return max(idx - 1, 0)
+
+
+def _sheet_rows(xml_bytes: bytes, shared: list[str]) -> list[list[str]]:
+    root = ET.fromstring(xml_bytes)
+    s = f"{{{_NS_S}}}"
+    rows: list[list[str]] = []
+    for row in root.iter(f"{s}row"):
+        if len(rows) >= _MAX_XLSX_ROWS_PER_SHEET:
+            break
+        cells: dict[int, str] = {}
+        max_col = -1
+        for cell in row.iter(f"{s}c"):
+            col = _col_index(cell.get("r", "")) if cell.get("r") else max_col + 1
+            if col >= _MAX_XLSX_COLS:
+                continue
+            cells[col] = _cell_value(cell, shared, s)
+            max_col = max(max_col, col)
+        rows.append([cells.get(i, "") for i in range(max_col + 1)] if max_col >= 0 else [])
+    while rows and not any(value.strip() for value in rows[-1]):
+        rows.pop()
+    return rows
+
+
+def _cell_value(cell: ET.Element, shared: list[str], s: str) -> str:
+    value = cell.findtext(f"{s}v") or ""
+    typ = cell.get("t", "")
+    if typ == "s":
+        try:
+            return shared[int(value)]
+        except (ValueError, IndexError):
+            return ""
+    if typ == "inlineStr":
+        inline = cell.find(f"{s}is")
+        return "" if inline is None else "".join(t.text or "" for t in inline.iter(f"{s}t"))
+    if typ == "b":
+        return "TRUE" if value.strip() in {"1", "true", "TRUE"} else "FALSE"
+    if typ == "e":
+        return value or "#ERROR"
+    return value

package/agent/tools/read_terminal_tool.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""Read the in-app terminal pane in the Hermes desktop GUI.
+
+The embedded terminal's buffer lives in the desktop renderer (xterm.js), so this
+tool round-trips through the gateway's blocking-prompt bridge — the same one
+`clarify` uses: tui_gateway emits ``terminal.read.request``, the renderer answers
+with ``terminal.read.respond``. This module is just schema + a thin dispatcher
+over the platform-injected callback.
+"""
+
+import json
+import os
+from typing import Callable, Optional
+
+from tools.registry import registry, tool_error
+
+
+def read_terminal_tool(
+    start_line: Optional[int] = None,
+    count: Optional[int] = None,
+    callback: Optional[Callable] = None,
+) -> str:
+    """Return the in-app terminal's contents (+ line metadata) as a JSON string."""
+    if callback is None:
+        return tool_error("read_terminal is only available in the Hermes desktop app.")
+
+    try:
+        window = {
+            key: max(floor, int(val))
+            for key, val, floor in (("start", start_line, 0), ("count", count, 1))
+            if val is not None
+        }
+    except (TypeError, ValueError):
+        return tool_error("start_line and count must be integers.")
+
+    try:
+        raw = callback(**window)
+    except Exception as exc:
+        return tool_error(f"Failed to read terminal: {exc}")
+
+    if not raw:
+        return tool_error("No in-app terminal is open, or the read timed out.")
+
+    # Desktop answers with a JSON object; pass it through, else wrap the raw text.
+    try:
+        return json.dumps(json.loads(raw), ensure_ascii=False)
+    except (TypeError, ValueError):
+        return json.dumps({"text": str(raw)}, ensure_ascii=False)
+
+
+def check_read_terminal_requirements() -> bool:
+    """Desktop GUI only — HERMES_DESKTOP is set on the gateway the app spawns."""
+    return (os.getenv("HERMES_DESKTOP") or "").strip().lower() in ("1", "true", "yes")
+
+
+READ_TERMINAL_SCHEMA = {
+    "name": "read_terminal",
+    "description": (
+        "Read what's currently shown in the in-app terminal pane of the Hermes "
+        "desktop GUI (the embedded shell beside this chat). Call with no arguments "
+        "to get the visible screen plus the total line count (`total_lines`). To "
+        "page through scrollback, pass `start_line` (0 = oldest line) and `count`; "
+        "valid lines are [0, total_lines). Returns JSON: "
+        "{total_lines, start, end, viewport_rows, cursor_row, text}."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "start_line": {
+                "type": "integer",
+                "description": "0-indexed first line (0 = oldest). Omit for the visible screen.",
+            },
+            "count": {
+                "type": "integer",
+                "description": "Lines to read from start_line. Defaults to the visible row count.",
+            },
+        },
+    },
+}
+
+
+registry.register(
+    name="read_terminal",
+    toolset="terminal",
+    schema=READ_TERMINAL_SCHEMA,
+    handler=lambda args, **kw: read_terminal_tool(
+        start_line=args.get("start_line"),
+        count=args.get("count"),
+        callback=kw.get("callback"),
+    ),
+    check_fn=check_read_terminal_requirements,
+    emoji="🖥️",
+)