cc-transcript 12.0.0__tar.gz → 12.1.0__tar.gz

{cc_transcript-12.0.0 → cc_transcript-12.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cc-transcript
-Version: 12.0.0
+Version: 12.1.0
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers

{cc_transcript-12.0.0 → cc_transcript-12.1.0}/cc_transcript/cli.py

@@ -26,11 +26,14 @@ from cc_transcript.builders import (
 )
 from cc_transcript.corrections_cli import corrections
 from cc_transcript.discovery import CLAUDE_PROJECTS_DIR, TranscriptDiscovery, find_transcript_sync
-from cc_transcript.filterspec import ASSISTANTS, USERS, EventKind, event_kind, keep, tool_names
+from cc_transcript.facts import command_prefix_counts, mcp_summary, tool_facts
+from cc_transcript.filterspec import ASSISTANTS, USERS, EventKind, event_kind, event_meta, keep, tool_names
 from cc_transcript.ids import SessionId, tool_digest
 from cc_transcript.models import AssistantEvent, ToolResultBlock, ToolUseBlock, UserEvent
 from cc_transcript.parser import TranscriptParser
 from cc_transcript.render import (
+    BLANK_TIME,
+    TAGS,
     WHERE_ALL,
     Budget,
     collect_stats,
@@ -39,6 +42,7 @@ from cc_transcript.render import (
     denial_line,
     display_path,
     event_dict,
+    event_payload,
     fact_dict,
     fact_line,
     haystack,
@@ -49,9 +53,10 @@ from cc_transcript.render import (
     render_tool_call,
     stats_dict,
     transcript_header,
+    truncate,
 )
-from cc_transcript.facts import command_prefix_counts, mcp_summary, tool_facts
 from cc_transcript.tools import file_path_of, parse_tool_call, tool_name_matches
+from cc_transcript.watch import watch
 
 if TYPE_CHECKING:
     from collections.abc import Iterable, Mapping, Sequence
@@ -61,6 +66,7 @@ if TYPE_CHECKING:
     from cc_transcript.facts import ToolFact
     from cc_transcript.filterspec import FilterSpec
     from cc_transcript.models import EntryMeta, ToolUseId, TranscriptEvent
+    from cc_transcript.watch import WatchEvent
 
     type Row = tuple[int, TranscriptEvent]
 
@@ -280,6 +286,29 @@ def slice_line(meta: EntryMeta, block: ToolUseBlock) -> dict[str, Any]:
     }
 
 
+
+def watch_dict(item: WatchEvent) -> dict[str, Any]:
+    meta = event_meta(item.event)
+    kind = event_kind(item.event)
+    return {
+        "path": str(item.path),
+        "session_id": item.session_id,
+        "is_sidechain": item.is_sidechain,
+        "uuid": meta.uuid if meta is not None else None,
+        "kind": kind,
+        "role": kind if kind in ("user", "assistant") else None,
+        "preview": truncate(event_payload(item.event, names={}, width=120, thinking=False), 120),
+    }
+
+
+def watch_line(item: WatchEvent) -> str:
+    meta = event_meta(item.event)
+    time = meta.timestamp.strftime("%H:%M:%S") if meta is not None else BLANK_TIME
+    tag = TAGS[event_kind(item.event)] + ("*" if item.is_sidechain else "")
+    payload = event_payload(item.event, names={}, width=100, thinking=False)
+    return f"{time} {item.session_id[:8]} {tag:<5} {payload}".rstrip()
+
+
 @click.group()
 @click.version_option(package_name="cc-transcript")
 def cli() -> None:
@@ -672,3 +701,28 @@ def digest(check: Path | None) -> None:
             ),
         )
     )
+@cli.command("watch")
+@click.option(
+    "--root",
+    "roots",
+    multiple=True,
+    type=click.Path(file_okay=False, path_type=Path),
+    help="Projects directory to tail; repeatable [default: ~/.claude/projects].",
+)
+@click.option("--poll", default=1.0, show_default=True, help="Seconds between filesystem polls.")
+@click.option("--from-start", is_flag=True, help="Replay preexisting transcript content instead of tailing from EOF.")
+@click.option("--json", "as_json", is_flag=True, help="Emit one NDJSON object per event.")
+def watch_(roots: tuple[Path, ...], poll: float, from_start: bool, as_json: bool) -> None:
+    """Tail transcripts live, one line per newly appended event, until interrupted."""
+
+    async def run() -> None:
+        async for item in watch(roots or (CLAUDE_PROJECTS_DIR,), poll=poll, from_start=from_start):
+            click.echo(orjson.dumps(watch_dict(item)) if as_json else watch_line(item))
+
+    try:
+        anyio.run(run)
+    except KeyboardInterrupt:
+        return
+    except BrokenPipeError:
+        os.dup2(os.open(os.devnull, os.O_WRONLY), sys.stdout.fileno())
+        raise SystemExit(0) from None

{cc_transcript-12.0.0 → cc_transcript-12.1.0}/cc_transcript/discovery.py

@@ -151,6 +151,15 @@ async def find_transcript(session_id: SessionId, *, root: Path | None = None) ->
     return await anyio.to_thread.run_sync(partial(find_transcript_sync, session_id, root=root))
 
 
+def is_subagent_path(path: Path) -> bool:
+    """Whether ``path`` names a subagent sidechain transcript.
+
+    Matches the ``agent-<tool_use_id>.jsonl`` naming convention that
+    :func:`subagent_paths` discovers.
+    """
+    return path.suffix == ".jsonl" and path.name.startswith("agent-")
+
+
 def subagent_paths(path: Path) -> tuple[Path, ...]:
     """Sidechain transcript files spawned by the session transcript at ``path``.
 

{cc_transcript-12.0.0 → cc_transcript-12.1.0}/cc_transcript/mining/__init__.py

@@ -65,6 +65,7 @@ from cc_transcript.mining.formats import (
     StructuredFormat,
     extract_structured,
 )
+from cc_transcript.mining.sampling import sample_windows
 from cc_transcript.mining.signals import (
     MiningSignal,
     mine,

cc_transcript-12.1.0/cc_transcript/mining/sampling.py

@@ -0,0 +1,109 @@
+"""Deterministic negative-window sampling over a session's completed turns.
+
+:func:`sample_windows` draws "the user did not steer here" negatives: durable
+:class:`~cc_transcript.context.ContextWindow` captures anchored on completed
+turns, reproducible for a given seed and session, kept clear of known
+positives by an exclusion radius. Negative windows carry no trigger — the
+sampled turn folds into ``before`` — so they render byte-compatibly with
+positive steering windows, whose user-steer trigger is likewise excluded from
+model input: both shapes read as the turns up to the moment being judged.
+"""
+
+from __future__ import annotations
+
+import random
+from dataclasses import replace
+from typing import TYPE_CHECKING
+
+from cc_transcript.context import capture_window
+from cc_transcript.filterspec import event_meta
+from cc_transcript.ids import EventRef
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from cc_transcript.activity import SessionActivity, Turn
+    from cc_transcript.context import ContextWindow
+
+
+def sample_windows(
+    activity: SessionActivity,
+    *,
+    n: int,
+    exclude: Iterable[EventRef] = (),
+    exclusion_radius: int = 6,
+    seed: int = 0,
+    before: int = 6,
+    after: int = 2,
+    preview_chars: int = 200,
+) -> list[ContextWindow]:
+    """Sample up to ``n`` triggerless context windows as steering negatives.
+
+    Each window anchors on a completed turn — the agent acted and the user's
+    next prompt was not a steer we know about — and folds that turn into the
+    window's context: ``trigger`` is None, ``before`` ends at the sampled
+    turn and keeps at most ``before`` turns, and ``after`` is unchanged. The
+    ``anchor`` stays the sampled turn's first meta-bearing event, so
+    consumers key negatives exactly like positives.
+
+    Candidates are every turn carrying at least one event with resolvable
+    meta (the anchor), except the session's final turn, which may still be in
+    flight. Every candidate in the ``exclusion_radius`` turns leading up to an
+    ``exclude`` ref's turn is dropped; refs that no longer resolve are
+    ignored. Sampling is deterministic:
+    ``random.Random(f"{seed}:{session_id}")`` draws from the candidates in
+    turn order, so one seed always yields the same windows for a session.
+
+    Args:
+        activity: The lifted session to sample from.
+        n: The maximum number of windows to return.
+        exclude: Anchors of known positives to keep clear of.
+        exclusion_radius: How many turns before each excluded turn to drop
+            (the excluded turn itself included). Turns after an excluded turn
+            stay eligible — once the user has steered, letting the agent run
+            again is a genuine negative; only the pre-steer approach, which
+            positive-window rewinds occupy, is label-conflicted.
+        seed: The determinism seed, mixed with the session id.
+        before: How many turns each window's folded ``before`` keeps, ending
+            at the sampled turn.
+        after: How many turns after each sampled turn to capture.
+        preview_chars: The per-chunk preview budget persisted on each window.
+
+    Returns:
+        The sampled windows, sorted by sampled turn index.
+    """
+    excluded = {turn.index for ref in exclude if (turn := activity.turn_of(ref)) is not None}
+    candidates = [
+        (turn.index, anchor)
+        for turn in activity.turns[:-1]
+        if all(not (0 <= index - turn.index <= exclusion_radius) for index in excluded)
+        if (anchor := turn_anchor(turn)) is not None
+    ]
+    rng = random.Random(f"{seed}:{activity.session_id}")
+    chosen = rng.sample(candidates, min(n, len(candidates)))
+    return [
+        fold_trigger(
+            capture_window(activity, anchor, before=before, after=after, preview_chars=preview_chars),
+            keep=before,
+        )
+        for _, anchor in sorted(chosen, key=lambda pair: pair[0])
+    ]
+
+
+def fold_trigger(window: ContextWindow, *, keep: int) -> ContextWindow:
+    """Fold ``window``'s trigger into ``before`` — the negative shape has none.
+
+    Returns:
+        The window with ``trigger`` None and ``before`` ending at the old
+        trigger, truncated to the last ``keep`` turns.
+    """
+    folded = (*window.before, *(() if window.trigger is None else (window.trigger,)))
+    return replace(window, before=folded[-keep:] if keep > 0 else (), trigger=None)
+
+
+def turn_anchor(turn: Turn) -> EventRef | None:
+    """The reference to ``turn``'s first meta-bearing event, or None without one."""
+    return next(
+        (EventRef(meta.session_id, meta.uuid) for event in turn.events if (meta := event_meta(event)) is not None),
+        None,
+    )

cc_transcript-12.1.0/cc_transcript/watch.py

@@ -0,0 +1,235 @@
+"""Live transcript tailing: poll the projects tree, yield each appended event once.
+
+A byte-offset tailer over the ``*.jsonl`` transcripts: every file gets a
+:class:`TailCursor`, each poll reads only what appended since the last one
+(open-read-close, never holding a descriptor), complete lines decode through
+the parser's per-line decode, and a bounded per-file uuid set keeps compaction
+rewrites and replays from double-firing. All progression lives in
+:func:`tick` — one deterministic step over a :class:`TailState`, directly
+drivable by tests and embedders — and :func:`watch` is the thin poll-forever
+loop over it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import anyio
+import anyio.to_thread
+
+from cc_transcript.discovery import CLAUDE_PROJECTS_DIR, is_subagent_path
+from cc_transcript.filterspec import event_meta
+from cc_transcript.ids import SessionId
+from cc_transcript.models import ModeEvent
+from cc_transcript.parser import decode_line
+
+if TYPE_CHECKING:
+    import os
+    from collections.abc import AsyncIterator, Sequence
+
+    from cc_transcript.ids import EventUuid
+    from cc_transcript.models import TranscriptEvent
+
+SEEN_LIMIT = 4096
+"""How many yielded event uuids each file's dedupe set retains."""
+
+
+@dataclass(frozen=True, slots=True)
+class WatchEvent:
+    """One transcript event freshly appended to a watched file.
+
+    Attributes:
+        path: The transcript file the event was read from.
+        session_id: The session the event belongs to — from the event's own
+            envelope when it carries one, else the file's last-known session,
+            else derived from the transcript path.
+        is_sidechain: Whether the file is a subagent sidechain transcript.
+        event: The parsed transcript event.
+    """
+
+    path: Path
+    session_id: SessionId
+    is_sidechain: bool
+    event: TranscriptEvent
+
+
+@dataclass(slots=True)
+class TailCursor:
+    """One watched file's tail progress.
+
+    Attributes:
+        offset: Bytes consumed so far — always the end of the last complete
+            line, so a partial trailing line stays unconsumed until its
+            newline arrives.
+        size: The file size at the last processed stat.
+        mtime: The file mtime at the last processed stat.
+        session_id: The session id cached from the first decoded event that
+            carried one.
+        seen: Event uuids already yielded, insertion-ordered and bounded at
+            :data:`SEEN_LIMIT`.
+    """
+
+    offset: int
+    size: int
+    mtime: float
+    session_id: SessionId | None = None
+    seen: dict[EventUuid, None] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class TailState:
+    """The tailer's whole mutable state: one cursor per discovered file.
+
+    Attributes:
+        cursors: Tail progress per transcript file.
+        primed: Whether the initial discovery pass has run — files first seen
+            on that pass are history, files appearing later are new content.
+    """
+
+    cursors: dict[Path, TailCursor] = field(default_factory=dict)
+    primed: bool = False
+
+
+async def watch(
+    roots: Sequence[Path] = (CLAUDE_PROJECTS_DIR,),
+    *,
+    poll: float = 1.0,
+    from_start: bool = False,
+) -> AsyncIterator[WatchEvent]:
+    """Tail every transcript under ``roots`` forever, yielding appended events.
+
+    An async generator that never returns on its own: each iteration drains
+    one :func:`tick` and sleeps ``poll`` seconds. Content predating the first
+    tick is skipped unless ``from_start``; everything appended afterwards is
+    yielded exactly once, with sidechain transcripts flagged on the event.
+    """
+    state = TailState()
+    while True:
+        for event in await tick(state, roots, from_start=from_start):
+            yield event
+        await anyio.sleep(poll)
+
+
+async def tick(state: TailState, roots: Sequence[Path], *, from_start: bool = False) -> list[WatchEvent]:
+    """Run one poll step: discover changes under ``roots`` and drain them.
+
+    A file is re-read only when its size or mtime changed — both are compared,
+    because mtime granularity can hide rapid appends. A file first seen on the
+    priming pass starts at end-of-file unless ``from_start``, so daemon starts
+    never replay history; a file appearing on a later pass starts at byte 0,
+    since its whole content is new. A file whose size fell below the cursor
+    was rewritten (compaction): the cursor resets to 0 and its dedupe set
+    clears. The cursor only ever advances past the last complete line — a
+    partial trailing line waits, and lines the decoder rejects are skipped.
+
+    Returns:
+        The newly appended events, files in path order, lines in file order.
+    """
+    stats = await scan(roots)
+    priming = not state.primed
+    state.primed = True
+    events: list[WatchEvent] = []
+    for path in sorted(stats):
+        stat = stats[path]
+        if (cursor := state.cursors.get(path)) is None:
+            skip_history = priming and not from_start
+            cursor = state.cursors[path] = TailCursor(
+                offset=stat.st_size if skip_history else 0,
+                size=stat.st_size if skip_history else -1,
+                mtime=stat.st_mtime if skip_history else -1.0,
+            )
+        if stat.st_size < cursor.offset:
+            cursor.offset = 0
+            cursor.seen.clear()
+        elif stat.st_size == cursor.size and stat.st_mtime == cursor.mtime:
+            continue
+        try:
+            chunk = await anyio.to_thread.run_sync(read_from, path, cursor.offset)
+        except OSError:
+            continue
+        cursor.size, cursor.mtime = stat.st_size, stat.st_mtime
+        complete, _, partial = chunk.rpartition(b"\n")
+        cursor.offset += len(chunk) - len(partial)
+        for line in complete.split(b"\n"):
+            if (event := decode(line)) is None:
+                continue
+            if (meta := event_meta(event)) is not None:
+                if meta.uuid in cursor.seen:
+                    continue
+                remember(cursor, meta.uuid)
+            events.append(
+                WatchEvent(
+                    path=path,
+                    session_id=session_of(cursor, path, event),
+                    is_sidechain=is_subagent_path(path),
+                    event=event,
+                )
+            )
+    return events
+
+
+async def scan(roots: Sequence[Path]) -> dict[Path, os.stat_result]:
+    """Stat every transcript under ``roots``, skipping macOS resource forks."""
+    found: dict[Path, os.stat_result] = {}
+    for root in roots:
+        base = anyio.Path(root)
+        if not await base.exists():
+            continue
+        async for entry in base.rglob("*.jsonl"):
+            if entry.name.startswith("._"):
+                continue
+            try:
+                found[Path(entry)] = await entry.stat()
+            except OSError:
+                continue
+    return found
+
+
+def read_from(path: Path, offset: int) -> bytes:
+    with path.open("rb") as handle:
+        handle.seek(offset)
+        return handle.read()
+
+
+def decode(line: bytes) -> TranscriptEvent | None:
+    """Decode one complete line, treating any malformed payload as garbage."""
+    if not line.strip():
+        return None
+    try:
+        return decode_line(line)
+    except (KeyError, ValueError, TypeError):
+        return None
+
+
+def remember(cursor: TailCursor, uuid: EventUuid) -> None:
+    cursor.seen[uuid] = None
+    while len(cursor.seen) > SEEN_LIMIT:
+        del cursor.seen[next(iter(cursor.seen))]
+
+
+def session_of(cursor: TailCursor, path: Path, event: TranscriptEvent) -> SessionId:
+    """The session ``event`` belongs to, cached on the file's cursor.
+
+    Prefers the event's own envelope — meta-bearing events and
+    :class:`~cc_transcript.models.ModeEvent` carry the session id — then the
+    cursor's cached value, then the path convention: the
+    ``<session_id>.jsonl`` stem, or the ``<session_id>/subagents/`` parent
+    directory for sidechain files.
+    """
+    session = event_session(event) or cursor.session_id or path_session_id(path)
+    cursor.session_id = session
+    return session
+
+
+def event_session(event: TranscriptEvent) -> SessionId | None:
+    match event:
+        case ModeEvent(session_id=session_id):
+            return session_id
+        case _:
+            return meta.session_id if (meta := event_meta(event)) is not None else None
+
+
+def path_session_id(path: Path) -> SessionId:
+    return SessionId(path.parent.parent.name if is_subagent_path(path) else path.stem)

{cc_transcript-12.0.0 → cc_transcript-12.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cc-transcript"
-version = "12.0.0"
+version = "12.1.0"
 description = "Grep every Claude Code session you've ever run."
 readme = "README.md"
 license = "PolyForm-Noncommercial-1.0.0"