agent-decoder 0.3.2__py3-none-any.whl

clau_decode/pty_screen_state.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class PtyScreenClassification:
+    state: str
+    decoded_input_safe: bool
+
+
+# Strip ANSI / VT control sequences so substring matching sees readable text
+# rather than escape-laden bytes.
+_CSI = re.compile(r"\x1b\[[0-9;?]*[ -/]*[@-~]")
+_OSC = re.compile(r"\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)")
+_OTHER_ESC = re.compile(r"\x1b[@-Z\\-_]")
+
+
+def _normalize(text: str) -> str:
+    text = _OSC.sub("", text)
+    text = _CSI.sub("", text)
+    text = _OTHER_ESC.sub("", text)
+    # Replace remaining control chars (except newline) with spaces, then
+    # collapse runs of spaces/tabs. Keep newlines so line-oriented phrases
+    # survive.
+    text = "".join(c if (c == "\n" or c.isprintable()) else " " for c in text)
+    return re.sub(r"[ \t]+", " ", text).lower()
+
+
+def classify_screen(text: str) -> PtyScreenClassification:
+    """Best-effort classification of the live PTY screen for Native-View gating.
+
+    IMPORTANT: the input is the flattened output *ring* (a byte log with cursor
+    moves), not an emulator-rendered screen, so it is noisy and can contain
+    overwritten content. We therefore match only a small set of distinctive,
+    high-signal phrases and **err toward ``idle_chat_input`` (decoded input
+    safe) when unsure** — a false "native required" needlessly yanks the user
+    out of Decoded View and is the failure mode we most want to avoid. The
+    previous heuristics (bare ``allow`` + ``yes``/``no``, bare ``trust``,
+    ``?`` + ``select``) matched ordinary assistant output and caused exactly
+    those spurious switches. A fully robust state machine (slash palette, model
+    selector, etc.) would need real backend terminal emulation; that is out of
+    scope here.
+    """
+    s = _normalize(text)
+
+    # Auth/login — distinctive banners claude prints when not authenticated.
+    if "not logged in" in s or "please run /login" in s or "invalid api key" in s:
+        return PtyScreenClassification("login_required", False)
+
+    # Trust prompt — Claude Code: "Do you trust the files in this folder?"
+    if "do you trust the files" in s:
+        return PtyScreenClassification("trust_prompt", False)
+
+    # AskUserQuestion surfaced as a native prompt (tool name appears verbatim).
+    if "askuserquestion" in s:
+        return PtyScreenClassification("ask_user_question", False)
+
+    # Tool/permission prompt — Claude Code phrasings: "Do you want to proceed?"
+    # / "Do you want to allow ...". Specific enough to avoid prose false hits.
+    if "do you want to proceed" in s or "do you want to allow" in s:
+        return PtyScreenClassification("permission_prompt", False)
+
+    return PtyScreenClassification("idle_chat_input", True)

clau_decode/recap_runner.py

@@ -0,0 +1,230 @@
+"""Recap generation — drives a hidden PTY against a forked session.
+
+The recap path uses the same subscription-backed TUI behavior as chat submit,
+so it stays inside the no-additional-cost envelope.
+
+How it works:
+  1. The caller pre-mints a UUID for the fork and tombstones it in the
+     server's deleted-sessions set BEFORE invoking us — otherwise the
+     watcher would briefly index the fork JSONL into the sidebar between
+     file creation and our cleanup.
+  2. We spawn ``claude --session-id <fork> --resume <source> --fork-session
+     --model haiku --permission-mode dontAsk`` in a hidden PTY (no UI).
+  3. After the TUI signals ready, we write the recap prompt + Enter.
+  4. We poll the fork's JSONL for an assistant entry with ``stop_reason``
+     set (the canonical "turn complete" signal) and return its text.
+  5. The PTY is killed and the fork JSONL is deleted in the ``finally``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from pathlib import Path
+from typing import Optional
+
+from .pty_runner import DEFAULT_COLS, DEFAULT_ROWS, PtyChannel, _pty_env
+
+_log = logging.getLogger(__name__)
+
+
+async def generate_recap(
+    session_id: str,
+    *,
+    cwd: str,
+    bin_name: str,
+    prompt: str,
+    source_jsonl_path: Path,
+    fork_id: str,
+    timeout_seconds: float = 90.0,
+) -> Optional[str]:
+    """Drive a forked PTY against ``session_id`` to generate a recap.
+
+    Returns the assistant's text on success, or ``None`` on
+    spawn failure / readiness timeout / no assistant block within
+    ``timeout_seconds`` / non-text content.
+
+    The fork JSONL lives at ``source_jsonl_path.parent / f"{fork_id}.jsonl"``
+    (claude writes forks alongside the source) and is deleted on exit.
+    """
+    fork_jsonl = source_jsonl_path.parent / f"{fork_id}.jsonl"
+
+    # Note: we deliberately do NOT pass ``--model``. Earlier recap code forced
+    # ``haiku`` for cost reduction, but PTY-TUI turns are subscription-included
+    # so there's no per-call cost to minimise. Forcing a model alias also
+    # turned out to be brittle
+    # against cc-mirror profiles that map Claude aliases to their own
+    # backends (e.g. zai's GLM mapping silently dropped requests with
+    # ``--model haiku``). Letting the fork inherit the source session's
+    # model — what TUI does when ``--model`` is omitted — is both
+    # simpler and provider-agnostic.
+    argv = [
+        bin_name,
+        "--session-id",
+        fork_id,
+        "--resume",
+        session_id,
+        "--fork-session",
+        "--permission-mode",
+        "dontAsk",
+    ]
+    env = await _pty_env(DEFAULT_ROWS, DEFAULT_COLS, bin_name)
+
+    channel = PtyChannel(
+        session_id=f"recap-{fork_id}",
+        argv=argv,
+        cwd=cwd,
+        env=env,
+        # Skip the ownership sidecar — the fork JSONL doesn't exist yet
+        # and we're going to delete it on the way out, so there's nothing
+        # to lock or hand off.
+        jsonl_path=None,
+    )
+
+    try:
+        await channel.start()
+        ready = await channel.await_ready(timeout_s=5.0)
+        if not ready:
+            _log.warning(
+                "recap: TUI didn't signal ready within 5s (session %s, fork %s)",
+                session_id,
+                fork_id,
+            )
+            return None
+        # The fork has to load the source session's history before it can
+        # accept input — for sessions with 10+ KB of history the TUI is
+        # rendering its prompt box well before its input handler is
+        # actually attached. Settling 3 s post-ready is empirically
+        # reliable across the cwd-restore + permission-mode-banner
+        # bootstrap path observed against the zai TUI build.
+        await asyncio.sleep(3.0)
+        # Write the prompt one byte at a time with a small inter-byte
+        # delay. A single bulk ``os.write`` of the full prompt arrives
+        # faster than the fork's input loop drains it and the bytes
+        # appear to be discarded (no echo, no JSONL write, no error —
+        # zai TUI just sits at its prompt). Char-by-char mimics human
+        # typing and exercises the same input path interactive users
+        # take, so the fork picks the prompt up reliably.
+        body = prompt.replace("\n", "\x0a").encode("utf-8")
+        try:
+            for byte in body:
+                channel.write(bytes([byte]))
+                await asyncio.sleep(0.005)
+            channel.write(b"\r")
+        except Exception as exc:
+            _log.warning(
+                "recap: PTY write failed (session %s, fork %s): %s",
+                session_id,
+                fork_id,
+                exc,
+            )
+            return None
+        text = await _await_assistant_text(fork_jsonl, timeout_seconds)
+        if text is None:
+            _log.warning(
+                "recap: no assistant text in fork JSONL within %.1fs "
+                "(session %s, fork %s)",
+                timeout_seconds,
+                session_id,
+                fork_id,
+            )
+        return text
+    finally:
+        try:
+            await channel.kill()
+        except Exception as exc:  # pragma: no cover — defensive
+            _log.debug("recap: kill raised (fork %s): %s", fork_id, exc)
+        try:
+            fork_jsonl.unlink()
+        except FileNotFoundError:
+            pass
+        except OSError as exc:
+            _log.debug("recap: fork JSONL unlink failed (%s): %s", fork_jsonl, exc)
+
+
+async def _await_assistant_text(jsonl: Path, timeout_seconds: float) -> Optional[str]:
+    """Poll ``jsonl`` for an assistant entry with ``stop_reason`` set.
+
+    JSONL is the canonical channel (Phase 0 / Phase 1 findings) — TUI
+    ANSI output is fragile to parse. Returns the joined text content of
+    the final assistant block, or ``None`` on timeout.
+    """
+    loop = asyncio.get_running_loop()
+    deadline = loop.time() + timeout_seconds
+    last_size = 0
+    while loop.time() < deadline:
+        if jsonl.exists():
+            try:
+                content = jsonl.read_bytes()
+            except OSError:
+                content = b""
+            if len(content) > last_size:
+                last_size = len(content)
+                text = _final_assistant_text(content)
+                if text:
+                    return text
+        await asyncio.sleep(0.1)
+    return None
+
+
+def _final_assistant_text(content: bytes) -> Optional[str]:
+    """Return the assistant text for the *recap turn* — the assistant entry
+    written after the latest user entry.
+
+    A forked session's JSONL starts with the entire source conversation
+    copied in (that's how ``--fork-session`` works). Without anchoring on
+    "latest user entry", a naive reverse scan would return the source's
+    last assistant message and declare the recap done before the new turn
+    even started. We find the latest user entry first, then look for an
+    assistant entry after it whose ``stop_reason`` is set.
+    """
+    lines = content.decode("utf-8", errors="replace").splitlines()
+
+    # Index the latest user entry (the recap prompt we just wrote).
+    last_user_idx: Optional[int] = None
+    for i in range(len(lines) - 1, -1, -1):
+        line = lines[i].strip()
+        if not line:
+            continue
+        try:
+            d = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if d.get("type") == "user":
+            last_user_idx = i
+            break
+    if last_user_idx is None:
+        return None
+
+    # Now find the latest assistant entry AFTER that user line. Streaming
+    # writes emit several partial assistant entries before the final one;
+    # only the entry where ``stop_reason`` is set is the turn-complete
+    # signal we want.
+    for i in range(len(lines) - 1, last_user_idx, -1):
+        line = lines[i].strip()
+        if not line:
+            continue
+        try:
+            d = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if d.get("type") != "assistant":
+            continue
+        msg = d.get("message")
+        if not isinstance(msg, dict) or not msg.get("stop_reason"):
+            continue
+        parts: list[str] = []
+        c = msg.get("content")
+        if isinstance(c, list):
+            for block in c:
+                if (
+                    isinstance(block, dict)
+                    and block.get("type") == "text"
+                    and isinstance(block.get("text"), str)
+                ):
+                    parts.append(block["text"])
+        text = "\n".join(parts).strip()
+        if text:
+            return text
+    return None

clau_decode/reporter.py

@@ -0,0 +1,305 @@
+"""Reporting and export — JSON and Markdown session reports."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING
+
+from .analytics.cost import SessionCost
+from .analytics.pricing import ModelPricing
+from .analytics.service import TokenAnalyticsService
+from .models import Message, SessionDetail, TextBlock
+
+if TYPE_CHECKING:
+    pass
+
+
+def _text_content(message: Message) -> str:
+    """Extract plain text from a message's content blocks."""
+    parts: list[str] = []
+    for block in message.content_blocks:
+        if isinstance(block, TextBlock) and block.text:
+            parts.append(block.text)
+    return "\n".join(parts)
+
+
+def _truncate(text: str, max_len: int = 200) -> str:
+    if len(text) <= max_len:
+        return text
+    return text[: max_len - 3] + "..."
+
+
+_MIN_UTC = datetime.min.replace(tzinfo=timezone.utc)
+
+
+def _timestamp_sort_key(value: datetime | str | None) -> datetime:
+    """Return an aware UTC datetime for mixed JSONL/ephemeral timestamps."""
+    if value is None:
+        return _MIN_UTC
+    if isinstance(value, datetime):
+        dt = value
+    elif isinstance(value, str):
+        if not value:
+            return _MIN_UTC
+        try:
+            dt = datetime.fromisoformat(value.replace("Z", "+00:00"))
+        except ValueError:
+            return _MIN_UTC
+    else:
+        return _MIN_UTC
+
+    if dt.tzinfo is None:
+        # Legacy ephemeral rows were written with naive local datetime.now().
+        # astimezone() intentionally interprets naive values in the process
+        # local timezone before converting them to UTC.
+        return dt.astimezone(timezone.utc)
+    return dt.astimezone(timezone.utc)
+
+
+def export_json(
+    detail: SessionDetail,
+    cost: SessionCost | None = None,
+    prompts: list[dict] | None = None,
+    ephemerals: list[dict] | None = None,
+) -> dict:
+    """Produce a full structured JSON export of a session.
+
+    Args:
+        detail: SessionDetail with messages included.
+        cost: Optional SessionCost from the cost engine.
+        prompts: Optional list of PromptCost dicts from the analytics service.
+
+    Returns:
+        A dict ready for JSON serialization.
+    """
+    messages_out: list[dict] = []
+    for msg in detail.messages:
+        entry: dict = {
+            "id": msg.id,
+            "role": msg.role,
+            "timestamp": msg.timestamp.isoformat() if msg.timestamp else None,
+            "model": msg.model,
+            "text": _text_content(msg),
+        }
+        if msg.usage:
+            entry["usage"] = {
+                "input_tokens": msg.usage.input_tokens,
+                "output_tokens": msg.usage.output_tokens,
+                "cache_creation_input_tokens": msg.usage.cache_creation_input_tokens,
+                "cache_read_input_tokens": msg.usage.cache_read_input_tokens,
+            }
+        messages_out.append(entry)
+
+    result: dict = {
+        "session": {
+            "id": detail.id,
+            "title": detail.title,
+            "model": detail.model,
+            "started_at": detail.started_at.isoformat() if detail.started_at else None,
+            "updated_at": detail.updated_at.isoformat() if detail.updated_at else None,
+            "message_count": detail.message_count,
+            "cwd": detail.cwd,
+            "git_branch": detail.git_branch,
+        },
+        "messages": messages_out,
+    }
+
+    if cost:
+        result["cost"] = {
+            "model": cost.model,
+            "input_usd": float(cost.input_usd),
+            "output_usd": float(cost.output_usd),
+            "cache_write_usd": float(cost.cache_write_usd),
+            "cache_read_usd": float(cost.cache_read_usd),
+            "total_usd": float(cost.total_usd),
+            "pricing_known": cost.pricing is not None,
+        }
+
+    if prompts is not None:
+        result["prompts"] = prompts
+
+    # Always include the ephemerals array (empty list when none exist) so
+    # callers can reliably read result["ephemerals"] without key-checking.
+    result["ephemerals"] = ephemerals if ephemerals is not None else []
+
+    return result
+
+
+def export_markdown(
+    detail: SessionDetail,
+    cost: SessionCost | None = None,
+    prompts: list[dict] | None = None,
+    pricing: ModelPricing | None = None,
+    all_models_usage: list[dict] | None = None,
+    ephemerals: list[dict] | None = None,
+) -> str:
+    """Produce a Markdown report with executive summary.
+
+    Args:
+        detail: SessionDetail with messages included.
+        cost: Optional SessionCost from the cost engine.
+        prompts: Optional list of PromptCost dicts.
+        pricing: Optional ModelPricing for the model used.
+        all_models_usage: Optional list of model usage dicts.
+
+    Returns:
+        A Markdown string.
+    """
+    lines: list[str] = []
+    title = detail.title or "Untitled Session"
+    lines.append(f"# {title}")
+    lines.append("")
+
+    # Executive summary
+    lines.append("## Executive Summary")
+    lines.append("")
+
+    summary_items: list[str] = []
+    summary_items.append(f"- **Session ID:** `{detail.id}`")
+    if detail.model:
+        summary_items.append(f"- **Model:** {detail.model}")
+    if detail.started_at:
+        summary_items.append(
+            f"- **Started:** {detail.started_at.strftime('%Y-%m-%d %H:%M UTC')}"
+        )
+    if detail.updated_at:
+        summary_items.append(
+            f"- **Last activity:** {detail.updated_at.strftime('%Y-%m-%d %H:%M UTC')}"
+        )
+    summary_items.append(f"- **Messages:** {detail.message_count}")
+    if detail.cwd:
+        summary_items.append(f"- **Working directory:** `{detail.cwd}`")
+    if detail.git_branch:
+        summary_items.append(f"- **Git branch:** `{detail.git_branch}`")
+
+    # Token totals
+    analytics = TokenAnalyticsService()
+    totals = analytics.session_totals(detail.messages)
+    summary_items.append(f"- **Total tokens:** {totals.total:,}")
+    summary_items.append(f"  - Input: {totals.input_tokens:,}")
+    summary_items.append(f"  - Output: {totals.output_tokens:,}")
+    summary_items.append(f"  - Cache creation: {totals.cache_creation_tokens:,}")
+    summary_items.append(f"  - Cache read: {totals.cache_read_tokens:,}")
+
+    if cost:
+        summary_items.append(f"- **Estimated cost:** ${float(cost.total_usd):.4f}")
+        if cost.pricing is not None:
+            summary_items.append(f"  - Input: ${float(cost.input_usd):.4f}")
+            summary_items.append(f"  - Output: ${float(cost.output_usd):.4f}")
+            summary_items.append(f"  - Cache write: ${float(cost.cache_write_usd):.4f}")
+            summary_items.append(f"  - Cache read: ${float(cost.cache_read_usd):.4f}")
+
+    lines.extend(summary_items)
+    lines.append("")
+
+    # Per-million-token pricing table
+    if pricing:
+        lines.append("## Pricing Table (per 1M tokens)")
+        lines.append("")
+        lines.append("| Category | USD / 1M tokens |")
+        lines.append("|---|---|")
+        lines.append(f"| Input | ${float(pricing.input_per_mtok):.2f} |")
+        lines.append(f"| Output | ${float(pricing.output_per_mtok):.2f} |")
+        lines.append(f"| Cache write | ${float(pricing.cache_write_per_mtok):.2f} |")
+        lines.append(f"| Cache read | ${float(pricing.cache_read_per_mtok):.2f} |")
+        lines.append("")
+
+    # Model usage breakdown
+    if all_models_usage:
+        lines.append("## Model Usage")
+        lines.append("")
+        lines.append(
+            "| Model | Messages | Input tokens | Output tokens | Total tokens |"
+        )
+        lines.append("|---|---|---|---|---|")
+        for entry in all_models_usage:
+            model = entry.get("model", "unknown")
+            lines.append(
+                f"| {model} | {entry.get('message_count', 0):,} "
+                f"| {entry.get('input_tokens', 0):,} "
+                f"| {entry.get('output_tokens', 0):,} "
+                f"| {entry.get('total_tokens', 0):,} |"
+            )
+        lines.append("")
+
+    # Per-prompt cost table
+    if prompts:
+        lines.append("## Prompt Breakdown")
+        lines.append("")
+        lines.append("| # | Input | Output | Cache create | Cache read | Total |")
+        lines.append("|---|---|---|---|---|---|")
+        for i, p in enumerate(prompts, 1):
+            bd = p.get("breakdown", p)
+            lines.append(
+                f"| {i} "
+                f"| {bd.get('input_tokens', 0):,} "
+                f"| {bd.get('output_tokens', 0):,} "
+                f"| {bd.get('cache_creation_tokens', 0):,} "
+                f"| {bd.get('cache_read_tokens', 0):,} "
+                f"| {bd.get('total', 0):,} |"
+            )
+        lines.append("")
+
+    # Conversation log — regular messages and ephemeral pairs interleaved by
+    # timestamp so the export reads chronologically.
+    lines.append("## Conversation")
+    lines.append("")
+
+    # Build ephemeral pair index: user row id → (user_row, assistant_row | None).
+    # Pairs are keyed by the user row; assistant rows (responds_to != None) are
+    # looked up from the same list.  Unpaired user rows export without a reply.
+    eph_by_input_id: dict[int, dict] = {}
+    eph_response_by_responds_to: dict[int, dict] = {}
+    if ephemerals:
+        for row in ephemerals:
+            if row.get("responds_to") is None:
+                eph_by_input_id[row["id"]] = row
+            else:
+                eph_response_by_responds_to[row["responds_to"]] = row
+
+    # Collect regular messages and ephemeral user rows with normalized aware
+    # UTC sort keys. Legacy ephemerals may be naive local strings while JSONL
+    # message timestamps are UTC-aware datetimes.
+    # Sort everything by timestamp; None timestamps sort to the beginning.
+    timeline: list[tuple[datetime, str, object]] = []
+    for msg in detail.messages:
+        if msg.is_meta:
+            continue
+        timeline.append((_timestamp_sort_key(msg.timestamp), "message", msg))
+
+    for input_id, user_row in eph_by_input_id.items():
+        ts_key = _timestamp_sort_key(user_row.get("timestamp"))
+        timeline.append((ts_key, "ephemeral", user_row))
+
+    # Sort by timestamp ascending so the log reads in chronological order.
+    timeline.sort(key=lambda t: t[0])
+
+    for _, kind, obj in timeline:
+        if kind == "message":
+            msg = obj  # type: ignore[assignment]
+            role_label = "**User**" if msg.role == "user" else "**Assistant**"
+            ts = msg.timestamp.strftime("%H:%M:%S") if msg.timestamp else ""
+            lines.append(f"### {role_label} {f'({ts})' if ts else ''}".strip())
+            lines.append("")
+            text = _text_content(msg)
+            if text:
+                lines.append(_truncate(text, 500))
+                lines.append("")
+        else:
+            # Ephemeral pair: blockquote marker matching the existing ### style
+            # but visually distinguished so readers recognise /btw exchanges.
+            user_row = obj  # type: ignore[assignment]
+            user_ts = user_row.get("timestamp", "")
+            user_content = user_row.get("content", "")
+            eph_kind = user_row.get("kind", "btw")
+            resp_row = eph_response_by_responds_to.get(user_row["id"])
+
+            lines.append(f"> **[ephemeral · {eph_kind}]** {user_ts}")
+            lines.append(f"> {user_content}")
+            lines.append(">")
+            if resp_row:
+                resp_content = resp_row.get("content", "")
+                lines.append(f"> {resp_content}")
+            lines.append("")
+
+    return "\n".join(lines)