cjm-harness-transcripts 0.0.1__tar.gz

cjm_harness_transcripts-0.0.1/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: cjm-harness-transcripts
+Version: 0.0.1
+Summary: The harness-transcript extraction lib (DEC e8b2f397 increment ii; the d774d311 build item): parse agent-harness session transcripts (Claude Code JSONL first) into their append-only record DAG, walk the active path, extract user-facing prose both sides, and derive the transcript <-> on-graph session-key mapping. Pure-parse, zero graph dependencies — one extraction truth for the live scratchpad pull, the archive-absorb instrument, and the housekeeping miner. Born on-graph.
+Author-email: "Christian J. Mills" <9126128+cj-mills@users.noreply.github.com>
+License: Apache-2.0
+Project-URL: Repository, https://github.com/cj-mills/cjm-harness-transcripts
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# cjm-harness-transcripts
+
+<!-- generated from the context graph by `cjm-context-graph readme` — do not edit by hand; edit the graph (the urge to hand-edit = move it on-graph) -->
+
+Harness-transcript extraction library: reads Claude Code session transcripts (JSONL DAGs), walks the active path, and extracts the user-facing prose — assistant markdown bodies, cleaned user prompts, and curated tool-parameter prose (e.g. SendUserFile captions) — as ExtractedMessages ready to mint onto a context-graph session spine.
+
+## Modules
+
+- **`cjm_harness_transcripts`** — cjm-harness-transcripts: parse agent-harness session transcripts (Claude Code
+- **`cjm_harness_transcripts.extract`** — User-facing prose extraction — both sides, one truth.
+- **`cjm_harness_transcripts.mapping`** — Transcript ↔ session-key mapping, derived at pull time.
+- **`cjm_harness_transcripts.records`** — The transcript record layer: tolerant JSONL loading + the append-only DAG.
+
+## API
+
+### `cjm_harness_transcripts.extract`
+
+- `ExtractedMessage` _class_ — One user-facing message off the active path, ready to become a Message node.
+- `clean_user_text` _function_ — Strip harness wrapper blocks from a user prompt; collapse the scar tissue.
+- `extract_messages` _function_ — The active path's user-facing messages, chronological.
+
+### `cjm_harness_transcripts.mapping`
+
+- `BootInfo` _class_ — The first user prose of a transcript — the mapping's evidence.
+- `TranscriptMatch` _class_ — One ranked candidate pairing for a session key.
+- `find_transcripts_for_key` _function_ — All plausible transcripts for a session key, best first.
+- `parse_record_timestamp` _function_ — A transcript record timestamp (ISO-8601, trailing Z) as an aware datetime.
+- `parse_session_key` _function_ — A session key (local start timestamp, e.g. 2026-08-20_17-05-20) as an aware datetime.
+- `read_boot_info` _function_ — The transcript's first user record bearing prose, or None (empty/tool-only file).
+
+### `cjm_harness_transcripts.records`
+
+- `TranscriptDag` _class_ — The uuid-addressable view of a transcript: parent edges, forks, active path.
+- `TranscriptRecord` _class_ — One JSONL record, uuid-addressable or not, with the raw dict preserved.
+- `load_records` _function_ — Load a transcript JSONL tolerantly, in file order.
+
+## Dependencies
+
+**Used by:** `cjm-context-graph-projection`

cjm_harness_transcripts-0.0.1/README.md

@@ -0,0 +1,39 @@
+# cjm-harness-transcripts
+
+<!-- generated from the context graph by `cjm-context-graph readme` — do not edit by hand; edit the graph (the urge to hand-edit = move it on-graph) -->
+
+Harness-transcript extraction library: reads Claude Code session transcripts (JSONL DAGs), walks the active path, and extracts the user-facing prose — assistant markdown bodies, cleaned user prompts, and curated tool-parameter prose (e.g. SendUserFile captions) — as ExtractedMessages ready to mint onto a context-graph session spine.
+
+## Modules
+
+- **`cjm_harness_transcripts`** — cjm-harness-transcripts: parse agent-harness session transcripts (Claude Code
+- **`cjm_harness_transcripts.extract`** — User-facing prose extraction — both sides, one truth.
+- **`cjm_harness_transcripts.mapping`** — Transcript ↔ session-key mapping, derived at pull time.
+- **`cjm_harness_transcripts.records`** — The transcript record layer: tolerant JSONL loading + the append-only DAG.
+
+## API
+
+### `cjm_harness_transcripts.extract`
+
+- `ExtractedMessage` _class_ — One user-facing message off the active path, ready to become a Message node.
+- `clean_user_text` _function_ — Strip harness wrapper blocks from a user prompt; collapse the scar tissue.
+- `extract_messages` _function_ — The active path's user-facing messages, chronological.
+
+### `cjm_harness_transcripts.mapping`
+
+- `BootInfo` _class_ — The first user prose of a transcript — the mapping's evidence.
+- `TranscriptMatch` _class_ — One ranked candidate pairing for a session key.
+- `find_transcripts_for_key` _function_ — All plausible transcripts for a session key, best first.
+- `parse_record_timestamp` _function_ — A transcript record timestamp (ISO-8601, trailing Z) as an aware datetime.
+- `parse_session_key` _function_ — A session key (local start timestamp, e.g. 2026-08-20_17-05-20) as an aware datetime.
+- `read_boot_info` _function_ — The transcript's first user record bearing prose, or None (empty/tool-only file).
+
+### `cjm_harness_transcripts.records`
+
+- `TranscriptDag` _class_ — The uuid-addressable view of a transcript: parent edges, forks, active path.
+- `TranscriptRecord` _class_ — One JSONL record, uuid-addressable or not, with the raw dict preserved.
+- `load_records` _function_ — Load a transcript JSONL tolerantly, in file order.
+
+## Dependencies
+
+**Used by:** `cjm-context-graph-projection`

cjm_harness_transcripts-0.0.1/cjm_harness_transcripts/__init__.py

@@ -0,0 +1,6 @@
+"""cjm-harness-transcripts: parse agent-harness session transcripts (Claude Code
+JSONL first) — the record DAG, the active path, user-facing prose both sides,
+and the transcript ↔ session-key mapping. Pure-parse; the graph-minting half
+of the pull path lives with the projection verbs, which import this lib."""
+
+__version__ = "0.0.1"

cjm_harness_transcripts-0.0.1/cjm_harness_transcripts/extract.py

@@ -0,0 +1,156 @@
+"""User-facing prose extraction — both sides, one truth.
+
+Filters a transcript's active path down to what the humans actually read:
+assistant text blocks (no thinking, no tool calls/results), user prompts
+(minus harness wrappers — caveat blocks, system reminders, command noise),
+and the curated tool parameters the client renders as discourse
+(TOOL_PARAM_PROSE — a SendUserFile caption is prose living in tool_use
+input; finding 60d719fe).
+The transcript stores assistant messages as RAW MARKDOWN SOURCE (rendering is
+client-layered — verified DEC 671e9b11 point 9), so extracted text is the
+authoritative body for a Message node, not a rendering of it.
+
+This module is consumed identically by the live scratchpad pull, the
+archive-absorb instrument, and the housekeeping miner (DEC e8b2f397 point 2).
+"""
+
+import re
+from dataclasses import dataclass
+
+from .records import TranscriptDag, TranscriptRecord
+
+# Harness-injected wrapper blocks that are not the user's own prose.
+_WRAPPER_TAGS = (
+    "local-command-caveat",
+    "system-reminder",
+    "command-name",
+    "command-message",
+    "command-args",
+    "command-contents",
+    "local-command-stdout",
+    "local-command-stderr",
+)
+_WRAPPER_RE = re.compile(
+    "|".join(rf"<{t}>.*?</{t}>" for t in _WRAPPER_TAGS), re.DOTALL
+)
+
+# Tool parameters that carry user-facing prose (finding 60d719fe): the client
+# renders these as discourse (a SendUserFile caption rides the file card), but
+# the record holds only a tool_use block, so text-block extraction misses them.
+# Curated allowlist: tool name -> dotted paths into the tool_use input.
+TOOL_PARAM_PROSE: dict[str, tuple[str, ...]] = {
+    "SendUserFile": ("caption",),
+}
+
+# The birth-class facet stamped on tool-param messages (one label, many sources
+# — DEC 91c47b4a pt 1; graph-side consumers mirror the literal).
+TOOL_PARAM_SOURCE = "cc-tool-param"
+
+
+@dataclass
+class ExtractedMessage:
+    """One user-facing message off the active path, ready to become a Message node."""
+    role: str            # "user" | "assistant"
+    text: str            # Cleaned prose; raw markdown source on the assistant side
+    timestamp: str | None    # ISO-8601 as recorded
+    uuid: str            # Transcript identity (tool-param entries: the tool_use block id)
+    parent_uuid: str | None  # DAG ancestry (NEXT edges mirror this succession)
+    source: str | None = None  # Birth-class facet; None = plain transcript prose
+
+
+def clean_user_text(text: str) -> str:
+    """Strip harness wrapper blocks from a user prompt; collapse the scar tissue."""
+    text = _WRAPPER_RE.sub("", text)
+    text = re.sub(r"\n{3,}", "\n\n", text)
+    return text.strip()
+
+
+def _user_prose(rec: TranscriptRecord) -> str | None:
+    """A user record's own prose, or None when the record is tool/housekeeping traffic."""
+    content = rec.raw.get("message", {}).get("content")
+    if isinstance(content, str):
+        text = content
+    elif isinstance(content, list):
+        parts = [b.get("text", "") for b in content
+                 if isinstance(b, dict) and b.get("type") == "text"]
+        if not parts:
+            return None  # tool_result-only record
+        text = "\n\n".join(parts)
+    else:
+        return None
+    cleaned = clean_user_text(text)
+    return cleaned or None
+
+
+def _assistant_prose(rec: TranscriptRecord) -> str | None:
+    """An assistant record's text blocks (raw markdown), or None on tool-only records."""
+    content = rec.raw.get("message", {}).get("content")
+    if not isinstance(content, list):
+        return None
+    parts = [b.get("text", "") for b in content
+             if isinstance(b, dict) and b.get("type") == "text" and b.get("text")]
+    text = "\n\n".join(parts).strip()
+    return text or None
+
+
+def _tool_param_messages(
+    rec: TranscriptRecord,
+    table: dict[str, tuple[str, ...]],  # tool name -> dotted paths into tool_use input
+) -> list[ExtractedMessage]:
+    """Messages for user-facing prose carried in tool parameters (finding 60d719fe).
+
+    One message per prose-bearing (tool_use block, path) hit, block order.
+    Identity is the block id (the carrier record may also bear its own text
+    message, so the record uuid is taken); ancestry points at the carrier."""
+    content = rec.raw.get("message", {}).get("content")
+    if not isinstance(content, list):
+        return []
+    out: list[ExtractedMessage] = []
+    for i, block in enumerate(content):
+        if not (isinstance(block, dict) and block.get("type") == "tool_use"):
+            continue
+        for path in table.get(block.get("name", ""), ()):
+            value = block.get("input")
+            for part in path.split("."):
+                value = value.get(part) if isinstance(value, dict) else None
+            if not (isinstance(value, str) and value.strip()):
+                continue
+            out.append(ExtractedMessage(
+                role="assistant", text=value.strip(), timestamp=rec.timestamp,
+                uuid=block.get("id") or f"{rec.uuid}#tp{i}", parent_uuid=rec.uuid,
+                source=TOOL_PARAM_SOURCE,
+            ))
+    return out
+
+
+def extract_messages(
+    dag: TranscriptDag,
+    *,
+    tool_params: dict[str, tuple[str, ...]] | None = None,  # None = the curated TOOL_PARAM_PROSE table; {} disables
+) -> list[ExtractedMessage]:
+    """The active path's user-facing messages, chronological.
+
+    One ExtractedMessage per prose-bearing record: an assistant turn that
+    interleaves status prose between tool calls yields one message per text
+    record, exactly as the client displayed them. Prose the client renders out
+    of tool_use parameters (the curated table — finding 60d719fe) extracts as
+    its own TOOL_PARAM_SOURCE-faceted message after the record's text."""
+    table = TOOL_PARAM_PROSE if tool_params is None else tool_params
+    messages: list[ExtractedMessage] = []
+    for rec in dag.active_path():
+        if rec.type == "user":
+            text, extras = _user_prose(rec), []
+        elif rec.type == "assistant":
+            text, extras = _assistant_prose(rec), _tool_param_messages(rec, table)
+        else:
+            continue
+        if text is not None:
+            messages.append(ExtractedMessage(
+                role=rec.type,
+                text=text,
+                timestamp=rec.timestamp,
+                uuid=rec.uuid,
+                parent_uuid=rec.parent_uuid,
+            ))
+        messages.extend(extras)
+    return messages

cjm_harness_transcripts-0.0.1/cjm_harness_transcripts/mapping.py

@@ -0,0 +1,108 @@
+"""Transcript ↔ session-key mapping, derived at pull time.
+
+The workbench cannot record the pairing at mint: the Claude Code session
+starts strictly AFTER the on-graph Shift+S mint, so the CC session UUID does
+not exist yet (DEC fc6a0cdc point 1, superseding the record-at-mint variant).
+What IS derivable: the minted session's boot prompt carries the
+minted-in-workbench resume signal, session keys are local start timestamps,
+and every transcript record is UTC-stamped. So: scan the project's transcript
+dir, prefer boot records carrying the mint signal, and rank candidates by how
+closely their boot time follows the key. The caller records the winning
+pairing as a fact on the Session node — derived once, read thereafter.
+
+Multiple transcripts may legitimately follow one key (a Claude Code restart
+resumes the same on-graph session), so this module returns ALL candidates
+ranked, never a single guess.
+"""
+
+import re
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+
+from .records import load_records
+
+# The boot-prompt signal the session-start ritual includes for minted sessions
+# — a PREFIX, substring-matched, so every minting seat qualifies ("…minted
+# in-workbench", "…minted in-scratchpad") and every legacy boot still carries it.
+MINT_SIGNAL = "New session minted in-"
+
+_KEY_RE = re.compile(r"^\d{4}-\d{2}-\d{2}_\d{2}-\d{2}-\d{2}$")
+
+# Boot-time slack: the boot record must not predate the mint by more than this
+# (small negative tolerance absorbs sub-second clock jitter, nothing more).
+_SLACK_SECONDS = 60.0
+
+
+def parse_session_key(key: str) -> datetime:
+    """A session key (local start timestamp, e.g. 2026-08-20_17-05-20) as an aware datetime."""
+    if not _KEY_RE.match(key):
+        raise ValueError(f"not a session key: {key!r}")
+    naive = datetime.strptime(key, "%Y-%m-%d_%H-%M-%S")
+    return naive.astimezone()  # interpret in the local timezone, the key's home
+
+
+def parse_record_timestamp(ts: str) -> datetime:
+    """A transcript record timestamp (ISO-8601, trailing Z) as an aware datetime."""
+    return datetime.fromisoformat(ts.replace("Z", "+00:00"))
+
+
+@dataclass
+class BootInfo:
+    """The first user prose of a transcript — the mapping's evidence."""
+    text: str
+    timestamp: datetime
+    has_mint_signal: bool
+
+
+def read_boot_info(path: str | Path) -> BootInfo | None:
+    """The transcript's first user record bearing prose, or None (empty/tool-only file)."""
+    for rec in load_records(path):
+        if rec.type != "user" or rec.is_sidechain or rec.timestamp is None:
+            continue
+        content = rec.raw.get("message", {}).get("content")
+        if not isinstance(content, str):
+            continue
+        return BootInfo(
+            text=content,
+            timestamp=parse_record_timestamp(rec.timestamp),
+            has_mint_signal=MINT_SIGNAL in content,
+        )
+    return None
+
+
+@dataclass
+class TranscriptMatch:
+    """One ranked candidate pairing for a session key."""
+    path: Path
+    cc_session_uuid: str     # The transcript's filename stem IS the CC session UUID
+    boot: BootInfo
+    delay_seconds: float     # Boot time minus mint time; small = started right after mint
+
+
+def find_transcripts_for_key(
+    transcript_dir: str | Path, session_key: str, *, require_signal: bool = True,
+) -> list[TranscriptMatch]:
+    """All plausible transcripts for a session key, best first.
+
+    A transcript qualifies when its boot prose follows the mint time (within
+    slack) — and, by default, carries the mint signal; pass
+    ``require_signal=False`` to also rank signal-less candidates (resumed or
+    manually booted sessions). Ordering: signal-bearing first, then smallest
+    delay after the mint."""
+    key_dt = parse_session_key(session_key)
+    matches: list[TranscriptMatch] = []
+    for path in Path(transcript_dir).glob("*.jsonl"):
+        boot = read_boot_info(path)
+        if boot is None:
+            continue
+        delay = (boot.timestamp - key_dt).total_seconds()
+        if delay < -_SLACK_SECONDS:
+            continue  # booted before the mint — a different session
+        if require_signal and not boot.has_mint_signal:
+            continue
+        matches.append(TranscriptMatch(
+            path=path, cc_session_uuid=path.stem, boot=boot, delay_seconds=delay,
+        ))
+    matches.sort(key=lambda m: (not m.boot.has_mint_signal, m.delay_seconds))
+    return matches

cjm_harness_transcripts-0.0.1/cjm_harness_transcripts/records.py

@@ -0,0 +1,109 @@
+"""The transcript record layer: tolerant JSONL loading + the append-only DAG.
+
+A Claude Code transcript is an append-only DAG, never a linear log: every
+addressable record carries a ``parentUuid``, a rewind never truncates the file
+(post-rewind records append with an EARLIER parent, creating a fork), and
+timestamps strictly increase — no regression signal exists. The ACTIVE path is
+therefore a derived view: walk back from the tip (the newest main-chain
+record is always on it). Empirical basis: the 2026-08-20 walkthrough sitting's
+59-transcript scan (793 fork points) — DEC 671e9b11 point 8.
+
+Loading is deliberately tolerant: the live transcript is appended by the
+harness while a session runs, so a partially flushed final line is expected
+and skipped, and non-addressable housekeeping records (``file-history-snapshot``,
+``ai-title``, ``mode``, ...) are carried as raw records but excluded from the DAG.
+"""
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class TranscriptRecord:
+    """One JSONL record, uuid-addressable or not, with the raw dict preserved."""
+    type: str            # Record type: user / assistant / system / housekeeping kinds
+    uuid: str | None     # Addressable identity (None on housekeeping records)
+    parent_uuid: str | None  # The DAG edge; None on roots and housekeeping records
+    timestamp: str | None    # ISO-8601 as recorded (UTC, trailing Z)
+    is_sidechain: bool   # True on embedded sub-agent traffic — excluded from the main DAG
+    raw: dict            # The full record, untouched
+
+
+def load_records(path: str | Path) -> list[TranscriptRecord]:
+    """Load a transcript JSONL tolerantly, in file order.
+
+    Skips unparseable lines (the live file's partially flushed tail) and
+    non-dict payloads; never raises on malformed content."""
+    records: list[TranscriptRecord] = []
+    with open(path, encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                rec = json.loads(line)
+            except json.JSONDecodeError:
+                continue  # partially flushed tail line of a live transcript
+            if not isinstance(rec, dict):
+                continue
+            records.append(TranscriptRecord(
+                type=rec.get("type", ""),
+                uuid=rec.get("uuid"),
+                parent_uuid=rec.get("parentUuid"),
+                timestamp=rec.get("timestamp"),
+                is_sidechain=bool(rec.get("isSidechain")),
+                raw=rec,
+            ))
+    return records
+
+
+@dataclass
+class TranscriptDag:
+    """The uuid-addressable view of a transcript: parent edges, forks, active path."""
+    records: list[TranscriptRecord]
+    by_uuid: dict[str, TranscriptRecord] = field(init=False)
+    children: dict[str, list[TranscriptRecord]] = field(init=False)
+
+    def __post_init__(self):
+        self.by_uuid = {}
+        self.children = {}
+        for rec in self.records:
+            if rec.uuid is None or rec.is_sidechain:
+                continue
+            self.by_uuid[rec.uuid] = rec
+            if rec.parent_uuid is not None:
+                self.children.setdefault(rec.parent_uuid, []).append(rec)
+
+    @classmethod
+    def load(cls, path: str | Path) -> "TranscriptDag":
+        """Build the DAG straight from a transcript file."""
+        return cls(load_records(path))
+
+    def tip(self) -> TranscriptRecord | None:
+        """The newest main-chain record — by construction always on the active path."""
+        for rec in reversed(self.records):
+            if rec.uuid is not None and not rec.is_sidechain:
+                return rec
+        return None
+
+    def active_path(self) -> list[TranscriptRecord]:
+        """The live conversation line, chronological: tip ancestry, forks excluded.
+
+        Records down abandoned (rewound) branches are real discourse events and
+        stay loaded — they are simply not on this walk. A cycle or a dangling
+        parent ends the walk rather than raising (defensive: the file is
+        external input)."""
+        path: list[TranscriptRecord] = []
+        seen: set[str] = set()
+        rec = self.tip()
+        while rec is not None and rec.uuid not in seen:
+            seen.add(rec.uuid)
+            path.append(rec)
+            rec = self.by_uuid.get(rec.parent_uuid) if rec.parent_uuid else None
+        path.reverse()
+        return path
+
+    def fork_points(self) -> dict[str, list[TranscriptRecord]]:
+        """Parents with more than one child — rewind points and turn-internal forks."""
+        return {p: kids for p, kids in self.children.items() if len(kids) > 1}

cjm_harness_transcripts-0.0.1/cjm_harness_transcripts.egg-info/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: cjm-harness-transcripts
+Version: 0.0.1
+Summary: The harness-transcript extraction lib (DEC e8b2f397 increment ii; the d774d311 build item): parse agent-harness session transcripts (Claude Code JSONL first) into their append-only record DAG, walk the active path, extract user-facing prose both sides, and derive the transcript <-> on-graph session-key mapping. Pure-parse, zero graph dependencies — one extraction truth for the live scratchpad pull, the archive-absorb instrument, and the housekeeping miner. Born on-graph.
+Author-email: "Christian J. Mills" <9126128+cj-mills@users.noreply.github.com>
+License: Apache-2.0
+Project-URL: Repository, https://github.com/cj-mills/cjm-harness-transcripts
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# cjm-harness-transcripts
+
+<!-- generated from the context graph by `cjm-context-graph readme` — do not edit by hand; edit the graph (the urge to hand-edit = move it on-graph) -->
+
+Harness-transcript extraction library: reads Claude Code session transcripts (JSONL DAGs), walks the active path, and extracts the user-facing prose — assistant markdown bodies, cleaned user prompts, and curated tool-parameter prose (e.g. SendUserFile captions) — as ExtractedMessages ready to mint onto a context-graph session spine.
+
+## Modules
+
+- **`cjm_harness_transcripts`** — cjm-harness-transcripts: parse agent-harness session transcripts (Claude Code
+- **`cjm_harness_transcripts.extract`** — User-facing prose extraction — both sides, one truth.
+- **`cjm_harness_transcripts.mapping`** — Transcript ↔ session-key mapping, derived at pull time.
+- **`cjm_harness_transcripts.records`** — The transcript record layer: tolerant JSONL loading + the append-only DAG.
+
+## API
+
+### `cjm_harness_transcripts.extract`
+
+- `ExtractedMessage` _class_ — One user-facing message off the active path, ready to become a Message node.
+- `clean_user_text` _function_ — Strip harness wrapper blocks from a user prompt; collapse the scar tissue.
+- `extract_messages` _function_ — The active path's user-facing messages, chronological.
+
+### `cjm_harness_transcripts.mapping`
+
+- `BootInfo` _class_ — The first user prose of a transcript — the mapping's evidence.
+- `TranscriptMatch` _class_ — One ranked candidate pairing for a session key.
+- `find_transcripts_for_key` _function_ — All plausible transcripts for a session key, best first.
+- `parse_record_timestamp` _function_ — A transcript record timestamp (ISO-8601, trailing Z) as an aware datetime.
+- `parse_session_key` _function_ — A session key (local start timestamp, e.g. 2026-08-20_17-05-20) as an aware datetime.
+- `read_boot_info` _function_ — The transcript's first user record bearing prose, or None (empty/tool-only file).
+
+### `cjm_harness_transcripts.records`
+
+- `TranscriptDag` _class_ — The uuid-addressable view of a transcript: parent edges, forks, active path.
+- `TranscriptRecord` _class_ — One JSONL record, uuid-addressable or not, with the raw dict preserved.
+- `load_records` _function_ — Load a transcript JSONL tolerantly, in file order.
+
+## Dependencies
+
+**Used by:** `cjm-context-graph-projection`

cjm_harness_transcripts-0.0.1/cjm_harness_transcripts.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+cjm_harness_transcripts/__init__.py
+cjm_harness_transcripts/extract.py
+cjm_harness_transcripts/mapping.py
+cjm_harness_transcripts/records.py
+cjm_harness_transcripts.egg-info/PKG-INFO
+cjm_harness_transcripts.egg-info/SOURCES.txt
+cjm_harness_transcripts.egg-info/dependency_links.txt
+cjm_harness_transcripts.egg-info/top_level.txt
+tests/test_extract.py
+tests/test_mapping.py
+tests/test_records.py

cjm_harness_transcripts-0.0.1/cjm_harness_transcripts.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

cjm_harness_transcripts-0.0.1/cjm_harness_transcripts.egg-info/top_level.txt

@@ -0,0 +1 @@
+cjm_harness_transcripts

cjm_harness_transcripts-0.0.1/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cjm-harness-transcripts"
+version = "0.0.1"
+description = "The harness-transcript extraction lib (DEC e8b2f397 increment ii; the d774d311 build item): parse agent-harness session transcripts (Claude Code JSONL first) into their append-only record DAG, walk the active path, extract user-facing prose both sides, and derive the transcript <-> on-graph session-key mapping. Pure-parse, zero graph dependencies — one extraction truth for the live scratchpad pull, the archive-absorb instrument, and the housekeeping miner. Born on-graph."
+readme = "README.md"
+requires-python = ">=3.12"
+license = {text = "Apache-2.0"}
+authors = [{name = "Christian J. Mills", email = "9126128+cj-mills@users.noreply.github.com"}]
+classifiers = ["Programming Language :: Python :: 3", "Programming Language :: Python :: 3 :: Only"]
+dependencies = []
+
+[project.urls]
+Repository = "https://github.com/cj-mills/cjm-harness-transcripts"
+
+[tool.setuptools.packages.find]
+include = ["cjm_harness_transcripts*"]

cjm_harness_transcripts-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cjm_harness_transcripts-0.0.1/tests/test_extract.py

@@ -0,0 +1,109 @@
+"""Extraction: user-facing prose both sides, wrappers stripped, tool traffic dropped."""
+
+from cjm_harness_transcripts.extract import (
+    TOOL_PARAM_SOURCE, clean_user_text, extract_messages)
+from cjm_harness_transcripts.records import TranscriptDag
+
+from conftest import rec
+
+
+def test_clean_user_text_strips_harness_wrappers():
+    raw = (
+        "<local-command-caveat>Caveat: local commands.</local-command-caveat>\n"
+        "Real question here.\n\n"
+        "<system-reminder>\nbackground noise\n</system-reminder>\n"
+    )
+    assert clean_user_text(raw) == "Real question here."
+
+
+def test_clean_user_text_strips_command_wrappers():
+    raw = "<command-name>/foo</command-name>\n<command-args>bar</command-args>\n"
+    assert clean_user_text(raw) == ""
+
+
+def test_extract_keeps_both_sides_and_drops_tool_traffic(make_transcript):
+    path = make_transcript([
+        rec("user", "u1", None, ts="2026-08-20T22:00:00.000Z",
+            content="<system-reminder>ctx</system-reminder>\nHello there"),
+        rec("assistant", "a1", "u1", ts="2026-08-20T22:00:03.000Z",
+            content=[{"type": "text", "text": "Looking now."},
+                     {"type": "tool_use", "name": "Bash", "input": {}}]),
+        rec("user", "t1", "a1", ts="2026-08-20T22:00:04.000Z",
+            content=[{"type": "tool_result", "content": "output"}]),
+        rec("assistant", "a2", "t1", ts="2026-08-20T22:00:08.000Z",
+            content=[{"type": "thinking", "thinking": "private"},
+                     {"type": "text", "text": "**Found it.**"}]),
+    ])
+    messages = extract_messages(TranscriptDag.load(path))
+    assert [(m.role, m.text) for m in messages] == [
+        ("user", "Hello there"),
+        ("assistant", "Looking now."),
+        ("assistant", "**Found it.**"),  # raw markdown source, verbatim
+    ]
+    assert messages[0].uuid == "u1" and messages[0].parent_uuid is None
+
+
+def test_extract_skips_abandoned_branch_messages(make_transcript):
+    path = make_transcript([
+        rec("user", "u1", None, ts="2026-08-20T22:00:00.000Z", content="q"),
+        rec("user", "u2a", "u1", ts="2026-08-20T22:01:00.000Z", content="retracted"),
+        rec("user", "u2b", "u1", ts="2026-08-20T22:02:00.000Z", content="final form"),
+    ])
+    messages = extract_messages(TranscriptDag.load(path))
+    assert [m.text for m in messages] == ["q", "final form"]
+
+
+def test_tool_only_and_empty_records_yield_nothing(make_transcript):
+    path = make_transcript([
+        rec("user", "u1", None, ts="2026-08-20T22:00:00.000Z",
+            content="<local-command-caveat>only wrapper</local-command-caveat>"),
+        rec("assistant", "a1", "u1", ts="2026-08-20T22:00:03.000Z",
+            content=[{"type": "tool_use", "name": "Bash", "input": {}}]),
+    ])
+    assert extract_messages(TranscriptDag.load(path)) == []
+
+
+def test_tool_param_prose_extracts_as_faceted_message(make_transcript):
+    # The finding-60d719fe class: a SendUserFile caption is user-facing prose
+    # living in tool_use input — it becomes its own message, block-id identity,
+    # cc-tool-param facet, after the carrier record's own text.
+    path = make_transcript([
+        rec("user", "u1", None, ts="2026-08-21T21:00:00.000Z", content="ship it"),
+        rec("assistant", "a1", "u1", ts="2026-08-21T21:00:05.000Z",
+            content=[{"type": "text", "text": "Exporting now."},
+                     {"type": "tool_use", "id": "toolu_1", "name": "SendUserFile",
+                      "input": {"files": ["report.md"],
+                                "caption": "Here's the exported report."}}]),
+    ])
+    messages = extract_messages(TranscriptDag.load(path))
+    assert [(m.role, m.text) for m in messages] == [
+        ("user", "ship it"),
+        ("assistant", "Exporting now."),
+        ("assistant", "Here's the exported report."),
+    ]
+    caption = messages[-1]
+    assert caption.uuid == "toolu_1" and caption.parent_uuid == "a1"
+    assert caption.source == TOOL_PARAM_SOURCE
+    assert messages[0].source is None and messages[1].source is None
+
+
+def test_tool_param_table_is_curated_and_optional(make_transcript):
+    # Blank/absent params and unlisted tools yield nothing; tool_params={}
+    # disables the lane outright.
+    quiet = make_transcript([
+        rec("assistant", "a1", None, ts="2026-08-21T21:00:00.000Z",
+            content=[{"type": "tool_use", "id": "t1", "name": "SendUserFile",
+                      "input": {"files": ["x"], "caption": "  "}},
+                     {"type": "tool_use", "id": "t2", "name": "Bash",
+                      "input": {"command": "ls"}},
+                     {"type": "tool_use", "id": "t3", "name": "SendUserFile",
+                      "input": {"files": ["y"]}}]),
+    ])
+    assert extract_messages(TranscriptDag.load(quiet)) == []
+    captioned = make_transcript([
+        rec("assistant", "a1", None, ts="2026-08-21T21:00:09.000Z",
+            content=[{"type": "tool_use", "id": "t4", "name": "SendUserFile",
+                      "input": {"caption": "real"}}]),
+    ], name="bbbb1111-2222-3333-4444-555566667777.jsonl")
+    assert [m.text for m in extract_messages(TranscriptDag.load(captioned))] == ["real"]
+    assert extract_messages(TranscriptDag.load(captioned), tool_params={}) == []

cjm_harness_transcripts-0.0.1/tests/test_mapping.py

@@ -0,0 +1,67 @@
+"""Mapping: session keys, boot info, and ranked transcript candidates."""
+
+from datetime import timedelta, timezone
+
+import pytest
+
+from cjm_harness_transcripts.mapping import (
+    MINT_SIGNAL,
+    find_transcripts_for_key,
+    parse_session_key,
+    read_boot_info,
+)
+
+from conftest import rec, write_jsonl
+
+KEY = "2026-08-20_17-05-20"
+
+
+def iso_after(key, seconds):
+    """A UTC record timestamp `seconds` after the (local) session key."""
+    dt = parse_session_key(key) + timedelta(seconds=seconds)
+    return dt.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.000Z")
+
+
+def boot_transcript(tmp_path, name, key, delay, signal=True, text="Resume the project."):
+    prose = f"{text} {MINT_SIGNAL}." if signal else text
+    return write_jsonl(tmp_path / name, [
+        {"type": "file-history-snapshot", "snapshot": {}},
+        rec("user", "u1", None, ts=iso_after(key, delay), content=prose),
+    ])
+
+
+def test_parse_session_key_is_local_and_strict():
+    dt = parse_session_key(KEY)
+    assert dt.tzinfo is not None
+    assert (dt.year, dt.hour, dt.second) == (2026, 17, 20)
+    with pytest.raises(ValueError):
+        parse_session_key("2026-08-20 17:05:20")
+
+
+def test_read_boot_info_finds_first_user_prose(tmp_path):
+    path = boot_transcript(tmp_path, "aaaa.jsonl", KEY, 90)
+    boot = read_boot_info(path)
+    assert boot.has_mint_signal and MINT_SIGNAL in boot.text
+
+
+def test_candidates_ranked_by_delay_signal_first(tmp_path):
+    boot_transcript(tmp_path, "11111111-aaaa-aaaa-aaaa-aaaaaaaaaaaa.jsonl", KEY, 3600)
+    boot_transcript(tmp_path, "22222222-bbbb-bbbb-bbbb-bbbbbbbbbbbb.jsonl", KEY, 90)
+    boot_transcript(tmp_path, "33333333-cccc-cccc-cccc-cccccccccccc.jsonl", KEY, -7200)  # before mint
+    boot_transcript(tmp_path, "44444444-dddd-dddd-dddd-dddddddddddd.jsonl", KEY, 30, signal=False)
+
+    matches = find_transcripts_for_key(tmp_path, KEY)
+    assert [m.cc_session_uuid[:8] for m in matches] == ["22222222", "11111111"]
+    assert matches[0].delay_seconds == pytest.approx(90, abs=1)
+
+    loose = find_transcripts_for_key(tmp_path, KEY, require_signal=False)
+    assert [m.cc_session_uuid[:8] for m in loose] == ["22222222", "11111111", "44444444"]
+
+
+def test_mint_signal_prefix_matches_every_minting_seat():
+    # has_mint_signal is a substring check, so the seat-agnostic PREFIX must
+    # sit inside both minting seats' boot phrases — legacy workbench boots
+    # keep matching, scratchpad-minted sessions start matching.
+    from cjm_harness_transcripts.mapping import MINT_SIGNAL
+    assert MINT_SIGNAL in "New session minted in-workbench"
+    assert MINT_SIGNAL in "New session minted in-scratchpad"

cjm_harness_transcripts-0.0.1/tests/test_records.py

@@ -0,0 +1,62 @@
+"""The record layer: tolerant loading + DAG walks over rewind forks."""
+
+from cjm_harness_transcripts.records import TranscriptDag, load_records
+
+from conftest import rec
+
+
+def test_load_tolerates_garbage_and_partial_tail(make_transcript):
+    path = make_transcript(
+        [rec("user", "u1", None, ts="2026-08-20T22:00:00.000Z", content="hi")],
+        tail='{"type": "assistant", "uuid": "trunc',  # live-file partially flushed line
+    )
+    path.write_text(path.read_text() + "\nnot json at all\n[1, 2, 3]\n", encoding="utf-8")
+    records = load_records(path)
+    assert [r.uuid for r in records] == ["u1"]
+
+
+def test_housekeeping_records_load_but_stay_off_the_dag(make_transcript):
+    path = make_transcript([
+        {"type": "file-history-snapshot", "snapshot": {}},
+        rec("user", "u1", None, ts="2026-08-20T22:00:00.000Z", content="hi"),
+        {"type": "ai-title", "title": "x"},
+    ])
+    dag = TranscriptDag.load(path)
+    assert len(dag.records) == 3
+    assert set(dag.by_uuid) == {"u1"}
+
+
+def test_active_path_follows_tip_ancestry_past_a_rewind(make_transcript):
+    # u1 -> a1 -> u2a (abandoned) ; rewind: u2b appends later with parent a1
+    path = make_transcript([
+        rec("user", "u1", None, ts="2026-08-20T22:00:00.000Z", content="q"),
+        rec("assistant", "a1", "u1", ts="2026-08-20T22:00:05.000Z", content=[{"type": "text", "text": "r"}]),
+        rec("user", "u2a", "a1", ts="2026-08-20T22:01:00.000Z", content="first try"),
+        rec("assistant", "a2a", "u2a", ts="2026-08-20T22:01:05.000Z", content=[{"type": "text", "text": "dead"}]),
+        rec("user", "u2b", "a1", ts="2026-08-20T22:02:00.000Z", content="second try"),
+        rec("assistant", "a2b", "u2b", ts="2026-08-20T22:02:05.000Z", content=[{"type": "text", "text": "live"}]),
+    ])
+    dag = TranscriptDag.load(path)
+    assert dag.tip().uuid == "a2b"
+    assert [r.uuid for r in dag.active_path()] == ["u1", "a1", "u2b", "a2b"]
+    assert set(dag.fork_points()) == {"a1"}
+
+
+def test_sidechain_records_never_become_tip_or_path(make_transcript):
+    path = make_transcript([
+        rec("user", "u1", None, ts="2026-08-20T22:00:00.000Z", content="q"),
+        rec("assistant", "a1", "u1", ts="2026-08-20T22:00:05.000Z", content=[{"type": "text", "text": "r"}]),
+        rec("user", "s1", "a1", ts="2026-08-20T22:00:06.000Z", content="agent brief", sidechain=True),
+        rec("assistant", "s2", "s1", ts="2026-08-20T22:00:07.000Z", content=[{"type": "text", "text": "agent reply"}], sidechain=True),
+    ])
+    dag = TranscriptDag.load(path)
+    assert dag.tip().uuid == "a1"
+    assert [r.uuid for r in dag.active_path()] == ["u1", "a1"]
+
+
+def test_dangling_parent_ends_walk_instead_of_raising(make_transcript):
+    path = make_transcript([
+        rec("assistant", "a9", "missing-parent", ts="2026-08-20T22:00:00.000Z",
+            content=[{"type": "text", "text": "orphan"}]),
+    ])
+    assert [r.uuid for r in TranscriptDag.load(path).active_path()] == ["a9"]