cc-transcript 9.0.0__tar.gz → 9.1.0__tar.gz

{cc_transcript-9.0.0 → cc_transcript-9.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cc-transcript
-Version: 9.0.0
+Version: 9.1.0
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -47,7 +47,7 @@ Project-URL: Repository, https://github.com/yasyf/cc-transcript
 
 [![CI](https://github.com/yasyf/cc-transcript/actions/workflows/ci.yml/badge.svg)](https://github.com/yasyf/cc-transcript/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/cc-transcript.svg)](https://pypi.org/project/cc-transcript/)
-[![License: PolyForm Noncommercial](https://img.shields.io/badge/license-PolyForm--Noncommercial--1.0.0-blue)](https://github.com/yasyf/cc-transcript/blob/main/LICENSE)
+[![License PolyForm Noncommercial](https://img.shields.io/badge/license-PolyForm--Noncommercial--1.0.0-blue)](https://github.com/yasyf/cc-transcript/blob/main/LICENSE)
 
 ## Get started
 
@@ -55,9 +55,9 @@ Project-URL: Repository, https://github.com/yasyf/cc-transcript
 uvx cc-transcript list
 ```
 
-Every session is already on disk under `~/.claude/projects` — `list` finds them newest first, and `stats` collapses one into a screenful:
+Every session is already on disk under `~/.claude/projects`. `list` finds them newest first, and `stats` collapses one into a screenful:
 
-<img src="https://github.com/yasyf/cc-transcript/raw/main/docs/assets/demo.png" alt="Terminal running 'uvx cc-transcript stats' — a 1,023-event session summarized as counts, kinds, models, and tool names" width="700">
+<img src="https://github.com/yasyf/cc-transcript/raw/main/docs/assets/demo.png" alt="Terminal running 'uvx cc-transcript stats' — one session summarized as counts, kinds, models, and tool names" width="700">
 
 Driving with an agent? Paste this:
 
@@ -66,7 +66,7 @@ Driving with an agent? Paste this:
 /plugin install cc-transcript@cc-transcript
 ```
 
-The plugin's skill teaches Claude to answer "what did I ask you yesterday?" from its own history, funneling through the CLI instead of reading raw JSONL.
+The plugin's skill teaches Claude to answer "what did I ask you yesterday" from its own history, funneling through the CLI instead of reading raw JSONL.
 
 <details>
 <summary>No Claude Code? Point any agent at the CLI</summary>
@@ -92,7 +92,7 @@ Yesterday's session is a megabyte of JSONL, and pasting it into a chat blows the
 uvx cc-transcript show --signal --tail 20 ~/.claude/projects/<project>/<session>.jsonl
 ```
 
-`--signal` keeps only the substantive user and assistant turns — one line per event, a few hundred tokens for the whole exchange. With the plugin installed, skip the command: ask Claude directly and its skill runs this funnel for you.
+`--signal` keeps only the substantive user and assistant turns. One line per event, a few hundred tokens for the whole exchange. With the plugin installed, skip the command and ask Claude directly; its skill runs this funnel for you.
 
 ### Find the session where you fixed that bug
 
@@ -102,7 +102,7 @@ The fix happened weeks ago, in one of a few hundred transcripts. Search them all
 uvx cc-transcript grep "TranscriptExpiredError" --project cc-transcript
 ```
 
-Hits print under their transcript's path, each line carrying its raw event index — feed an index back into `show --range` to re-read the conversation around the fix. `grep` searches your newest 50 transcripts by default; `--all` takes it to every session on disk, and a no-match run exits 1 so it scripts cleanly.
+Hits print under their transcript's path, each line carrying its raw event index; feed an index back into `show --range` to re-read the conversation around the fix. `grep` searches your newest 50 transcripts by default; `--all` takes it to every session on disk, and a no-match run exits 1 so it scripts cleanly.
 
 ### Debug a token blowup from transcript evidence
 
@@ -112,16 +112,16 @@ A session burned through the context window and you want the culprit, not a gues
 uvx cc-transcript stats --per-file --project myapp
 ```
 
-Each block reports text, thinking, and tool-io bytes plus per-tool call counts — the blowup stands out as an outsized `tool io` line. Then `grep --tool <name> --with-result` pins it to the exact calls.
+Each block reports text, thinking, and tool-io bytes plus per-tool call counts; the blowup stands out as an outsized `tool io` line. Then `grep --tool <name> --with-result` pins it to the exact calls.
 
 ## More in the docs
 
-- **The Python library** — raw JSONL bytes to typed events, a composed filter, and a score in a dozen lines — [getting started](https://yasyf.github.io/cc-transcript/docs/getting-started/index.html)
-- **Filtering events** — composable clauses, specs, and the ready-made `NOISE_SPEC` — [builder catalog](https://yasyf.github.io/cc-transcript/docs/guide/filtering-events.html)
-- **Sentiment scoring** — bucket conversations and score them around any inference engine — [score specs](https://yasyf.github.io/cc-transcript/docs/guide/scoring-sentiment.html)
-- **Feedback mining** — detectors, confidence calibration, and LLM verdict passes over your corpus — [mine your sessions](https://yasyf.github.io/cc-transcript/docs/guide/mining-feedback.html)
-- **Two backends, one protocol** — a Rust fast path and a Python reference, parity-asserted against each other — [how parity works](https://yasyf.github.io/cc-transcript/docs/guide/backends-and-parity.html)
-- **API reference** — the complete typed surface, from `TranscriptEvent` to `SessionActivity` — [reference](https://yasyf.github.io/cc-transcript/reference/index.html)
+- [The Python library](https://yasyf.github.io/cc-transcript/docs/getting-started/index.html) turns raw JSONL bytes into typed events, a composed filter, and a score in a dozen lines.
+- [Filtering events](https://yasyf.github.io/cc-transcript/docs/guide/filtering-events.html) covers composable clauses, specs, and the ready-made `NOISE_SPEC`.
+- [Sentiment scoring](https://yasyf.github.io/cc-transcript/docs/guide/scoring-sentiment.html) buckets conversations and scores them around any inference engine.
+- [Feedback mining](https://yasyf.github.io/cc-transcript/docs/guide/mining-feedback.html) runs detectors, confidence calibration, and LLM verdict passes over your corpus.
+- [Two backends, one protocol](https://yasyf.github.io/cc-transcript/docs/guide/backends-and-parity.html) pairs a Rust fast path with a Python reference, parity-asserted against each other.
+- [API reference](https://yasyf.github.io/cc-transcript/reference/index.html) documents the complete typed surface, from `TranscriptEvent` to `SessionActivity`.
 
 Read the [docs](https://yasyf.github.io/cc-transcript/) for the full guide. Licensed under [PolyForm Noncommercial 1.0.0](https://github.com/yasyf/cc-transcript/blob/main/LICENSE).
 

{cc_transcript-9.0.0 → cc_transcript-9.1.0}/README.md

@@ -4,7 +4,7 @@
 
 [![CI](https://github.com/yasyf/cc-transcript/actions/workflows/ci.yml/badge.svg)](https://github.com/yasyf/cc-transcript/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/cc-transcript.svg)](https://pypi.org/project/cc-transcript/)
-[![License: PolyForm Noncommercial](https://img.shields.io/badge/license-PolyForm--Noncommercial--1.0.0-blue)](https://github.com/yasyf/cc-transcript/blob/main/LICENSE)
+[![License PolyForm Noncommercial](https://img.shields.io/badge/license-PolyForm--Noncommercial--1.0.0-blue)](https://github.com/yasyf/cc-transcript/blob/main/LICENSE)
 
 ## Get started
 
@@ -12,9 +12,9 @@
 uvx cc-transcript list
 ```
 
-Every session is already on disk under `~/.claude/projects` — `list` finds them newest first, and `stats` collapses one into a screenful:
+Every session is already on disk under `~/.claude/projects`. `list` finds them newest first, and `stats` collapses one into a screenful:
 
-<img src="https://github.com/yasyf/cc-transcript/raw/main/docs/assets/demo.png" alt="Terminal running 'uvx cc-transcript stats' — a 1,023-event session summarized as counts, kinds, models, and tool names" width="700">
+<img src="https://github.com/yasyf/cc-transcript/raw/main/docs/assets/demo.png" alt="Terminal running 'uvx cc-transcript stats' — one session summarized as counts, kinds, models, and tool names" width="700">
 
 Driving with an agent? Paste this:
 
@@ -23,7 +23,7 @@ Driving with an agent? Paste this:
 /plugin install cc-transcript@cc-transcript
 ```
 
-The plugin's skill teaches Claude to answer "what did I ask you yesterday?" from its own history, funneling through the CLI instead of reading raw JSONL.
+The plugin's skill teaches Claude to answer "what did I ask you yesterday" from its own history, funneling through the CLI instead of reading raw JSONL.
 
 <details>
 <summary>No Claude Code? Point any agent at the CLI</summary>
@@ -49,7 +49,7 @@ Yesterday's session is a megabyte of JSONL, and pasting it into a chat blows the
 uvx cc-transcript show --signal --tail 20 ~/.claude/projects/<project>/<session>.jsonl
 ```
 
-`--signal` keeps only the substantive user and assistant turns — one line per event, a few hundred tokens for the whole exchange. With the plugin installed, skip the command: ask Claude directly and its skill runs this funnel for you.
+`--signal` keeps only the substantive user and assistant turns. One line per event, a few hundred tokens for the whole exchange. With the plugin installed, skip the command and ask Claude directly; its skill runs this funnel for you.
 
 ### Find the session where you fixed that bug
 
@@ -59,7 +59,7 @@ The fix happened weeks ago, in one of a few hundred transcripts. Search them all
 uvx cc-transcript grep "TranscriptExpiredError" --project cc-transcript
 ```
 
-Hits print under their transcript's path, each line carrying its raw event index — feed an index back into `show --range` to re-read the conversation around the fix. `grep` searches your newest 50 transcripts by default; `--all` takes it to every session on disk, and a no-match run exits 1 so it scripts cleanly.
+Hits print under their transcript's path, each line carrying its raw event index; feed an index back into `show --range` to re-read the conversation around the fix. `grep` searches your newest 50 transcripts by default; `--all` takes it to every session on disk, and a no-match run exits 1 so it scripts cleanly.
 
 ### Debug a token blowup from transcript evidence
 
@@ -69,15 +69,15 @@ A session burned through the context window and you want the culprit, not a gues
 uvx cc-transcript stats --per-file --project myapp
 ```
 
-Each block reports text, thinking, and tool-io bytes plus per-tool call counts — the blowup stands out as an outsized `tool io` line. Then `grep --tool <name> --with-result` pins it to the exact calls.
+Each block reports text, thinking, and tool-io bytes plus per-tool call counts; the blowup stands out as an outsized `tool io` line. Then `grep --tool <name> --with-result` pins it to the exact calls.
 
 ## More in the docs
 
-- **The Python library** — raw JSONL bytes to typed events, a composed filter, and a score in a dozen lines — [getting started](https://yasyf.github.io/cc-transcript/docs/getting-started/index.html)
-- **Filtering events** — composable clauses, specs, and the ready-made `NOISE_SPEC` — [builder catalog](https://yasyf.github.io/cc-transcript/docs/guide/filtering-events.html)
-- **Sentiment scoring** — bucket conversations and score them around any inference engine — [score specs](https://yasyf.github.io/cc-transcript/docs/guide/scoring-sentiment.html)
-- **Feedback mining** — detectors, confidence calibration, and LLM verdict passes over your corpus — [mine your sessions](https://yasyf.github.io/cc-transcript/docs/guide/mining-feedback.html)
-- **Two backends, one protocol** — a Rust fast path and a Python reference, parity-asserted against each other — [how parity works](https://yasyf.github.io/cc-transcript/docs/guide/backends-and-parity.html)
-- **API reference** — the complete typed surface, from `TranscriptEvent` to `SessionActivity` — [reference](https://yasyf.github.io/cc-transcript/reference/index.html)
+- [The Python library](https://yasyf.github.io/cc-transcript/docs/getting-started/index.html) turns raw JSONL bytes into typed events, a composed filter, and a score in a dozen lines.
+- [Filtering events](https://yasyf.github.io/cc-transcript/docs/guide/filtering-events.html) covers composable clauses, specs, and the ready-made `NOISE_SPEC`.
+- [Sentiment scoring](https://yasyf.github.io/cc-transcript/docs/guide/scoring-sentiment.html) buckets conversations and scores them around any inference engine.
+- [Feedback mining](https://yasyf.github.io/cc-transcript/docs/guide/mining-feedback.html) runs detectors, confidence calibration, and LLM verdict passes over your corpus.
+- [Two backends, one protocol](https://yasyf.github.io/cc-transcript/docs/guide/backends-and-parity.html) pairs a Rust fast path with a Python reference, parity-asserted against each other.
+- [API reference](https://yasyf.github.io/cc-transcript/reference/index.html) documents the complete typed surface, from `TranscriptEvent` to `SessionActivity`.
 
 Read the [docs](https://yasyf.github.io/cc-transcript/) for the full guide. Licensed under [PolyForm Noncommercial 1.0.0](https://github.com/yasyf/cc-transcript/blob/main/LICENSE).

{cc_transcript-9.0.0 → cc_transcript-9.1.0}/cc_transcript/__init__.py

@@ -158,6 +158,7 @@ EXPORTS: dict[str, str] = {
             "capture_window",
         ),
         "cc_transcript.render": ("Budget", "render_session", "render_tool_call", "render_turn"),
+        "cc_transcript.notifications": ("Notifications",),
         "cc_transcript.query": ("FileRef", "Session", "SubagentIndex", "SubagentSession", "ToolCallQuery"),
         "cc_transcript.decisions": ("DECISIONS_DDL", "Action", "Decision", "DecisionLog"),
         "cc_transcript.disktruth": (
@@ -554,6 +555,7 @@ if TYPE_CHECKING:
     from cc_transcript.models import (
         tool_uses as tool_uses,
     )
+    from cc_transcript.notifications import Notifications as Notifications
     from cc_transcript.parser import (
         TranscriptParser as TranscriptParser,
     )

{cc_transcript-9.0.0 → cc_transcript-9.1.0}/cc_transcript/judge/llm.py

@@ -11,6 +11,7 @@ needs no extra installed.
 
 from __future__ import annotations
 
+import json
 from functools import cache
 from typing import TYPE_CHECKING
 
@@ -69,7 +70,7 @@ def structured_judge[M: BaseModel](
     async def judge(prompt: str) -> M:
         try:
             return await extract(prompt, response_model, backend=default_backend(), model=tier, timeout=timeout)
-        except (BackendCallError, BackendUnavailable, TimeoutError, ValidationError) as error:
+        except (BackendCallError, BackendUnavailable, TimeoutError, ValidationError, json.JSONDecodeError) as error:
             raise JudgeError(str(error)) from error
 
     return judge

cc_transcript-9.1.0/cc_transcript/notifications.py

@@ -0,0 +1,115 @@
+"""The harness notification-delivery queue, replayed from a transcript.
+
+Claude Code enqueues background-task notifications (and queued user commands)
+into a FIFO, then drains it as each item reaches the agent, recording every
+``enqueue``/``dequeue``/``remove``/``popAll`` as a ``queue-operation`` audit
+entry. :class:`Notifications` replays that audit trail over a session's events
+to model which notifications are still queued, which were delivered, and which
+ever passed through — so a hook can ask whether a given background tool call has
+already been reported to the agent.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from cc_transcript.models import OtherEvent, UserEvent
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from cc_transcript.models import TranscriptEvent
+
+NOTIFICATION_MARKER = "<task-notification>"
+
+
+def tool_use_marker(tool_use_id: str) -> str:
+    return f"<tool-use-id>{tool_use_id}</tool-use-id>"
+
+
+def delivered_text(event: TranscriptEvent) -> str | None:
+    match event:
+        case UserEvent(text=text) if NOTIFICATION_MARKER in text:
+            return text
+        case OtherEvent(type="attachment", raw=raw) if (attachment := raw.get("attachment") or {}).get(
+            "type"
+        ) == "queued_command":
+            return str(attachment.get("prompt", ""))
+        case _:
+            return None
+
+
+def replay_queue(events: Sequence[TranscriptEvent]) -> tuple[tuple[str, ...], tuple[str, ...]]:
+    queued: list[str] = []
+    enqueued: list[str] = []
+    for event in events:
+        if not (isinstance(event, OtherEvent) and event.type == "queue-operation"):
+            continue
+        match event.raw.get("operation"):
+            case "enqueue":
+                enqueued.append(content := str(event.raw.get("content", "")))
+                queued.append(content)
+            case "dequeue" | "remove" if queued:
+                queued.pop(0)
+            case "popAll":
+                content = str(event.raw.get("content", ""))
+                queued = [item for item in queued if item not in content]
+    return tuple(queued), tuple(enqueued)
+
+
+@dataclass(frozen=True, slots=True)
+class Notifications:
+    """The modeled state of a session's harness notification-delivery queue.
+
+    Reconstructed by replaying the transcript's ``queue-operation`` audit
+    records in order: each ``enqueue`` appends its content to a FIFO, each
+    ``dequeue``/``remove`` drops the head, and each ``popAll`` subtracts every
+    queued item whose text is contained in the operation's content — a queued
+    user command drains without taking an unrelated notification with it.
+
+    Attributes:
+        queued: The enqueue contents still in the modeled FIFO, undelivered.
+        delivered: The notification texts that actually reached the agent —
+            user turns carrying a ``<task-notification>`` plus every queued
+            command replayed to the model.
+        enqueued: Every enqueue content ever observed, in order.
+
+    Example:
+        >>> session.notifications.completed("toolu_01XVXcp6yKvn2xbmPxdf1a3z")
+        True
+    """
+
+    queued: tuple[str, ...]
+    delivered: tuple[str, ...]
+    enqueued: tuple[str, ...]
+
+    @classmethod
+    def from_events(cls, events: Sequence[TranscriptEvent]) -> Notifications:
+        """Replays the notification queue over ``events``, in order."""
+        queued, enqueued = replay_queue(events)
+        return cls(
+            queued=queued,
+            delivered=tuple(text for event in events if (text := delivered_text(event)) is not None),
+            enqueued=enqueued,
+        )
+
+    def completed(self, tool_use_id: str) -> bool:
+        """Whether the tool call's notification has reached the agent.
+
+        True when the notification was delivered, or when it was enqueued at
+        some point yet no longer sits undelivered in the queue.
+        """
+        marker = tool_use_marker(tool_use_id)
+        return any(marker in text for text in self.delivered) or (
+            any(marker in text for text in self.enqueued) and not any(marker in text for text in self.queued)
+        )
+
+    def pending(self, tool_use_id: str) -> bool:
+        """Whether the tool call's notification is still queued for delivery."""
+        return any(tool_use_marker(tool_use_id) in text for text in self.queued)
+
+    @property
+    def has_pending(self) -> bool:
+        """Whether any queued item is an undelivered task notification."""
+        return any(NOTIFICATION_MARKER in text for text in self.queued)

{cc_transcript-9.0.0 → cc_transcript-9.1.0}/cc_transcript/query.py

@@ -22,6 +22,7 @@ from cc_transcript.discovery import TranscriptExpiredError, find_transcript, sub
 from cc_transcript.filterspec import event_meta, session_id_of
 from cc_transcript.ids import SessionId
 from cc_transcript.models import AssistantEvent, SystemEvent, ToolResultBlock, UserEvent
+from cc_transcript.notifications import Notifications
 from cc_transcript.parser import parse_events_async, parse_events_from_bytes
 from cc_transcript.tools import BashCall, SkillCall, TaskCall, file_path_of, hunks_of, tool_name_matches
 
@@ -288,6 +289,11 @@ class Session:
         """The window's tool calls as a chainable query."""
         return ToolCallQuery(tuple(use for turn in self.turns for use in turn.tool_uses))
 
+    @property
+    def notifications(self) -> Notifications:
+        """The harness notification-delivery queue replayed over the window's events."""
+        return Notifications.from_events(self.events)
+
     @property
     def subagents(self) -> SubagentIndex:
         """The window's Task dispatches whose sidechain transcripts exist on disk."""

{cc_transcript-9.0.0 → cc_transcript-9.1.0}/pyproject.toml

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