tool_activity.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_chat/core/tool_activity.py
 
"""
The one process-level record of what a running tool call is doing.
 
Purpose
-------
A tool cannot reach a presenter. Tools are invoked as ``tool_fn(**args)`` with
the model's arguments and nothing else (``react_loop._dispatch_tool``), so a
child process that has been printing for four minutes has no way to say so to
the terminal. Plan 279 gives it one narrow channel: the react-loop opens a
record around every tool call, the tool's subprocess runner notes each output
line on it, and the status bar reads it on every render pass.
 
Why a module-level object and not a ``ContextVar``: the multi-tool dispatch path
runs its calls in a :class:`~concurrent.futures.ThreadPoolExecutor`, and a
``ContextVar`` set in the react-loop does not propagate into those workers. The
precedent this follows is
:func:`oc_chat.core.cancellation.tool_cancel_requested`, the other process-wide
flag a tool in a worker thread has to be able to see.
 
The record is TERMINAL-ONLY. Nothing here is published to the event bus, written
to the session, logged to the JSONL presenter log, or returned to the model —
the tool result, the events and the logs are byte-identical to what they were
before this module existed.
 
Responsibilities
----------------
- :class:`ToolActivitySnapshot` — a frozen, self-consistent view of one
  in-flight call: its label, when it started, and the last line it printed.
- :class:`ToolActivity` — the thread-safe record: :meth:`~ToolActivity.begin`,
  :meth:`~ToolActivity.note_line`, :meth:`~ToolActivity.end`,
  :meth:`~ToolActivity.snapshot`.
- :data:`TOOL_ACTIVITY` — the one instance. Nothing else in the process holds
  tool-progress state.
 
Diagnostics
-----------
Domain: OC_CHAT.TOOLS
Levels:
    L2 — a call's record opening and closing, with how long it ran
    L3 — the first output line of a call (when a child started producing)
    L4 — module load
 
Per-line tracing is deliberately absent: ``note_line`` runs once per line of a
child's output, which for a full test suite is tens of thousands of calls, so
only the FIRST line of each call is traced.
 
Contracts
---------
- A snapshot is published as ONE atomic attribute assignment under the lock, so
  a reader never sees a name from one call beside a line from another. The read
  side takes no lock at all, because it runs on Rich's refresh thread fifteen
  times a second and must never contend with a child's output.
- ``note_line`` outside a call is inert: a line arriving from a child that has
  already been ended cannot resurrect a tail on the bar.
- ``end`` is idempotent; the bracket's ``finally`` may run it more than once.
- Calls do not nest. The react-loop's bracket wraps the whole dispatch, and the
  confirmation resolvers re-dispatch strictly after it has closed.
- **Redaction is the CALLER's job, and it is not optional.** ``run_command``
  and the ``oct`` wrappers pass each line through a per-stream
  ``_sandbox.LineRedactor`` before it reaches :meth:`~ToolActivity.note_line`,
  so the bar can never show what the tool result would have hidden. Since plan
  287 that filter tracks PEM private-key armor across lines — it remembers that
  it is inside a block, which the table's one multi-line pattern cannot see line
  by line — so no key body line reaches this record for even one frame, on
  either stream, and a BEGIN whose END never arrives keeps redacting to the end
  of that stream. The residual that remains is the pattern table's, not this
  filter's: a key printed as a SINGLE line inside another format (JSON-escaped
  with ``\\n``, say) is caught only if one of the single-line patterns covers it.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
"""
from __future__ import annotations
 
import threading
import time
from dataclasses import dataclass, replace
 
from oc_diagnostics import _dbg
 
_dbg("OC_CHAT.TOOLS", "module", "loaded", 4)
 
 
@dataclass(frozen=True, slots=True)
class ToolActivitySnapshot:
    """One self-consistent view of the tool call currently in flight."""
 
    name: str
    """What is running, as the terminal names it — in practice the presenter's
    busy label (``running run_command…`` / ``running 3 tools…``)."""
    started_monotonic: float
    """``time.monotonic()`` at :meth:`ToolActivity.begin`. Monotonic, so the
    elapsed time it feeds cannot go backwards when the wall clock is adjusted."""
    last_line: "str | None" = None
    """The most recent output line, already redacted by the caller, or ``None``
    when the call has printed nothing yet."""
 
    def elapsed_ms(self, now: "float | None" = None) -> int:
        """Milliseconds since the call began, for :func:`format_duration`."""
        current = time.monotonic() if now is None else now
        return int((current - self.started_monotonic) * 1000)
 
 
class ToolActivity:
    """The process-wide record of the tool call in flight, or of nothing."""
 
    def __init__(self) -> None:
        self._lock = threading.Lock()
        self._current: "ToolActivitySnapshot | None" = None
 
    def begin(self, name: str) -> None:
        """Open a record for *name*, starting its clock and clearing any tail."""
        func = "begin"
        _dbg("OC_CHAT.TOOLS", func, f"opened {name!r}", 2)
        with self._lock:
            self._current = ToolActivitySnapshot(
                name=name, started_monotonic=time.monotonic(), last_line=None)
 
    def note_line(self, line: str) -> None:
        """Record *line* as the call's most recent output. Inert outside a call.
 
        *line* must already have been through the caller's redaction filter —
        see this module's Contracts.
        """
        func = "note_line"
        with self._lock:
            current = self._current
            if current is None:
                return
            first = current.last_line is None
            self._current = replace(current, last_line=line)
        if first:
            # Outside the lock: the one trace per call, not one per line.
            _dbg("OC_CHAT.TOOLS", func,
                 f"{current.name!r} produced its first line after "
                 f"{current.elapsed_ms()}ms", 3)
 
    def end(self) -> None:
        """Close the record. Idempotent."""
        func = "end"
        with self._lock:
            current = self._current
            if current is None:
                return
            self._current = None
        _dbg("OC_CHAT.TOOLS", func,
             f"closed {current.name!r} after {current.elapsed_ms()}ms", 2)
 
    def snapshot(self) -> "ToolActivitySnapshot | None":
        """The current record, or ``None`` when no tool call is in flight.
 
        Lock-free on purpose: the value is only ever replaced by one whole
        object under the lock, so a bare read is already atomic and consistent.
        """
        return self._current
 
 
#: The one record. Nothing else in the process holds tool-progress state.
TOOL_ACTIVITY = ToolActivity()
 
 
__all__ = ["TOOL_ACTIVITY", "ToolActivity", "ToolActivitySnapshot"]