dulus 0.2.0__py3-none-any.whl

checkpoint/store.py

@@ -0,0 +1,314 @@
+"""Checkpoint store: file-level backup + snapshot persistence.
+
+Directory layout:
+    ~/.dulus/checkpoints/<session_id>/
+        snapshots.json       # list of Snapshot metadata
+        backups/
+            <hash>@v<N>      # actual file copies
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import shutil
+import time
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+from .types import FileBackup, Snapshot, MAX_SNAPSHOTS
+
+# Max file size to back up (1 MB)
+_MAX_FILE_SIZE = 1 * 1024 * 1024
+
+# Per-file version counters (reset per session)
+_file_versions: dict[str, int] = {}
+
+
+def _checkpoints_root() -> Path:
+    return Path.home() / ".dulus" / "checkpoints"
+
+
+def _session_dir(session_id: str) -> Path:
+    return _checkpoints_root() / session_id
+
+
+def _backups_dir(session_id: str) -> Path:
+    d = _session_dir(session_id) / "backups"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def _snapshots_file(session_id: str) -> Path:
+    d = _session_dir(session_id)
+    d.mkdir(parents=True, exist_ok=True)
+    return d / "snapshots.json"
+
+
+def _path_hash(file_path: str) -> str:
+    """Deterministic short hash from file path (not content)."""
+    return hashlib.sha256(file_path.encode()).hexdigest()[:16]
+
+
+def _next_version(file_path: str) -> int:
+    v = _file_versions.get(file_path, 0) + 1
+    _file_versions[file_path] = v
+    return v
+
+
+# ── Load / save snapshots JSON ──────────────────────────────────────────────
+
+def _load_snapshots(session_id: str) -> list[Snapshot]:
+    f = _snapshots_file(session_id)
+    if not f.exists():
+        return []
+    try:
+        data = json.loads(f.read_text(encoding="utf-8"))
+        return [Snapshot.from_dict(s) for s in data]
+    except Exception:
+        return []
+
+
+def _save_snapshots(session_id: str, snapshots: list[Snapshot]) -> None:
+    f = _snapshots_file(session_id)
+    f.parent.mkdir(parents=True, exist_ok=True)
+    data = [s.to_dict() for s in snapshots]
+    f.write_text(json.dumps(data, indent=2, ensure_ascii=False), encoding="utf-8")
+
+
+# ── Public API ───────────────────────────────────────────────────────────────
+
+def track_file_edit(session_id: str, file_path: str) -> str | None:
+    """Back up a file before it is edited (first-write-wins per snapshot interval).
+
+    Returns the backup filename, or None if the file doesn't exist yet.
+    """
+    p = Path(file_path)
+    bdir = _backups_dir(session_id)
+
+    if not p.exists():
+        # File doesn't exist — record that so restore can delete it
+        return None
+
+    # Size guard
+    try:
+        size = p.stat().st_size
+    except OSError:
+        return None
+    if size > _MAX_FILE_SIZE:
+        print(f"[checkpoint] skipping large file ({size} bytes): {file_path}")
+        return None
+
+    # Copy file to backups/
+    version = _next_version(file_path)
+    backup_name = f"{_path_hash(file_path)}@v{version}"
+    backup_path = bdir / backup_name
+    try:
+        shutil.copy2(str(p), str(backup_path))
+    except Exception as e:
+        print(f"[checkpoint] backup failed for {file_path}: {e}")
+        return None
+
+    return backup_name
+
+
+def make_snapshot(
+    session_id: str,
+    state: Any,
+    config: dict,
+    user_prompt: str,
+    tracked_edits: dict[str, str | None] | None = None,
+) -> Snapshot | None:
+    """Create a snapshot after a user prompt has been processed.
+
+    tracked_edits: dict mapping file_path → backup_filename (or None if new file).
+                   Populated by hooks.py during the turn.
+    """
+    snapshots = _load_snapshots(session_id)
+
+    # Build file_backups: merge previous snapshot's backups with new edits
+    prev_backups: dict[str, FileBackup] = {}
+    if snapshots:
+        prev_backups = dict(snapshots[-1].file_backups)
+
+    now = datetime.now().isoformat()
+    new_backups: dict[str, FileBackup] = {}
+
+    # Carry forward unchanged files from previous snapshot
+    for path, fb in prev_backups.items():
+        new_backups[path] = fb
+
+    # Add/update files that were edited this turn — back up their CURRENT state
+    if tracked_edits:
+        for path in tracked_edits:
+            p = Path(path)
+            if p.exists():
+                try:
+                    size = p.stat().st_size
+                except OSError:
+                    continue
+                if size > _MAX_FILE_SIZE:
+                    continue
+                version = _next_version(path)
+                backup_name = f"{_path_hash(path)}@v{version}"
+                bdir = _backups_dir(session_id)
+                try:
+                    shutil.copy2(str(p), str(bdir / backup_name))
+                except Exception:
+                    continue
+                new_backups[path] = FileBackup(
+                    backup_filename=backup_name,
+                    version=version,
+                    backup_time=now,
+                )
+            else:
+                # File was deleted during the turn (unlikely but possible)
+                new_backups[path] = FileBackup(
+                    backup_filename=None,
+                    version=_file_versions.get(path, 0),
+                    backup_time=now,
+                )
+
+    next_id = (snapshots[-1].id + 1) if snapshots else 1
+
+    snapshot = Snapshot(
+        id=next_id,
+        session_id=session_id,
+        created_at=now,
+        turn_count=getattr(state, "turn_count", 0),
+        message_index=len(getattr(state, "messages", [])),
+        user_prompt_preview=user_prompt[:80] if user_prompt else "",
+        token_snapshot={
+            "input": getattr(state, "total_input_tokens", 0),
+            "output": getattr(state, "total_output_tokens", 0),
+        },
+        file_backups=new_backups,
+    )
+
+    snapshots.append(snapshot)
+
+    # Sliding window: keep only the last MAX_SNAPSHOTS
+    if len(snapshots) > MAX_SNAPSHOTS:
+        snapshots = snapshots[-MAX_SNAPSHOTS:]
+
+    _save_snapshots(session_id, snapshots)
+    return snapshot
+
+
+def list_snapshots(session_id: str) -> list[dict]:
+    """Return lightweight summaries of all snapshots."""
+    snapshots = _load_snapshots(session_id)
+    result = []
+    for s in snapshots:
+        result.append({
+            "id": s.id,
+            "turn_count": s.turn_count,
+            "message_index": s.message_index,
+            "created_at": s.created_at,
+            "user_prompt_preview": s.user_prompt_preview,
+            "file_count": len(s.file_backups),
+        })
+    return result
+
+
+def get_snapshot(session_id: str, snapshot_id: int) -> Snapshot | None:
+    snapshots = _load_snapshots(session_id)
+    for s in snapshots:
+        if s.id == snapshot_id:
+            return s
+    return None
+
+
+def rewind_files(session_id: str, snapshot_id: int) -> list[str]:
+    """Restore files to their state at the given snapshot.
+
+    Returns list of restored/deleted file paths.
+    """
+    snapshot = get_snapshot(session_id, snapshot_id)
+    if snapshot is None:
+        return []
+
+    bdir = _backups_dir(session_id)
+    restored: list[str] = []
+
+    for file_path, fb in snapshot.file_backups.items():
+        try:
+            if fb.backup_filename is None:
+                # File didn't exist at snapshot time → delete it
+                p = Path(file_path)
+                if p.exists():
+                    p.unlink()
+                    restored.append(f"deleted: {file_path}")
+            else:
+                # Restore from backup
+                backup_path = bdir / fb.backup_filename
+                if backup_path.exists():
+                    p = Path(file_path)
+                    p.parent.mkdir(parents=True, exist_ok=True)
+                    shutil.copy2(str(backup_path), str(p))
+                    restored.append(f"restored: {file_path}")
+                else:
+                    restored.append(f"backup missing: {file_path}")
+        except Exception as e:
+            restored.append(f"error restoring {file_path}: {e}")
+
+    return restored
+
+
+def files_changed_since(session_id: str, snapshot_id: int) -> list[str]:
+    """List files that have been changed in snapshots after the given one."""
+    snapshots = _load_snapshots(session_id)
+    target = None
+    for s in snapshots:
+        if s.id == snapshot_id:
+            target = s
+            break
+    if target is None:
+        return []
+
+    changed: set[str] = set()
+    for s in snapshots:
+        if s.id <= snapshot_id:
+            continue
+        for path in s.file_backups:
+            if path not in target.file_backups or \
+               s.file_backups[path].version != target.file_backups[path].version:
+                changed.add(path)
+    return sorted(changed)
+
+
+def delete_session_checkpoints(session_id: str) -> bool:
+    """Delete all checkpoints for a session."""
+    d = _session_dir(session_id)
+    if d.exists():
+        shutil.rmtree(str(d), ignore_errors=True)
+        return True
+    return False
+
+
+def cleanup_old_sessions(max_age_days: int = 30) -> int:
+    """Remove checkpoint sessions older than max_age_days. Returns count removed."""
+    root = _checkpoints_root()
+    if not root.exists():
+        return 0
+    cutoff = time.time() - (max_age_days * 86400)
+    removed = 0
+    try:
+        for d in root.iterdir():
+            if d.is_dir():
+                try:
+                    mtime = d.stat().st_mtime
+                    if mtime < cutoff:
+                        shutil.rmtree(str(d), ignore_errors=True)
+                        removed += 1
+                except OSError:
+                    pass
+    except OSError:
+        pass
+    return removed
+
+
+def reset_file_versions() -> None:
+    """Reset per-file version counters (for testing)."""
+    _file_versions.clear()

checkpoint/types.py

@@ -0,0 +1,80 @@
+"""Checkpoint system types: FileBackup and Snapshot dataclasses."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+MAX_SNAPSHOTS = 100
+
+
+@dataclass
+class FileBackup:
+    """A single file's backup reference within a snapshot.
+
+    backup_filename: hash@vN name in the backups/ dir, or None if the file
+                     did not exist before (meaning restore = delete).
+    version: monotonically increasing per-file version counter.
+    backup_time: ISO timestamp of when the backup was created.
+    """
+    backup_filename: str | None
+    version: int
+    backup_time: str
+
+    def to_dict(self) -> dict:
+        return {
+            "backup_filename": self.backup_filename,
+            "version": self.version,
+            "backup_time": self.backup_time,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> FileBackup:
+        return cls(
+            backup_filename=data.get("backup_filename"),
+            version=data.get("version", 0),
+            backup_time=data.get("backup_time", ""),
+        )
+
+
+@dataclass
+class Snapshot:
+    """A checkpoint snapshot — metadata about conversation + file state."""
+    id: int
+    session_id: str
+    created_at: str
+    turn_count: int
+    message_index: int              # len(state.messages) at snapshot time
+    user_prompt_preview: str        # first 80 chars of the triggering prompt
+    token_snapshot: dict[str, int]  # {"input": N, "output": N}
+    file_backups: dict[str, FileBackup] = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "session_id": self.session_id,
+            "created_at": self.created_at,
+            "turn_count": self.turn_count,
+            "message_index": self.message_index,
+            "user_prompt_preview": self.user_prompt_preview,
+            "token_snapshot": self.token_snapshot,
+            "file_backups": {
+                path: fb.to_dict() for path, fb in self.file_backups.items()
+            },
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> Snapshot:
+        backups = {}
+        for path, fb_data in data.get("file_backups", {}).items():
+            backups[path] = FileBackup.from_dict(fb_data)
+        return cls(
+            id=data["id"],
+            session_id=data.get("session_id", ""),
+            created_at=data.get("created_at", ""),
+            turn_count=data.get("turn_count", 0),
+            message_index=data.get("message_index", 0),
+            user_prompt_preview=data.get("user_prompt_preview", ""),
+            token_snapshot=data.get("token_snapshot", {}),
+            file_backups=backups,
+        )

claude_code_watcher.py

@@ -0,0 +1,214 @@
+#!/usr/bin/env python3
+"""
+claude_code_watcher.py
+
+Watches a Claude Code session JSONL file and extracts assistant responses
+in real time. Can print to stdout or POST to a Dulus/webhook endpoint.
+
+v2: Groups multi-part assistant turns (text + tool_use + text) into one
+    complete message before sending. Fixes the bug where text after a
+    tool call was sent as a separate/missing message.
+
+Usage:
+    python claude_code_watcher.py
+    python claude_code_watcher.py --session <path_to.jsonl>
+    python claude_code_watcher.py --post http://localhost:5000/claude_code_response
+"""
+
+import json
+import sys
+import time
+import os
+import argparse
+from pathlib import Path
+
+
+SESSION_DIR = Path.home() / ".claude" / "projects" / "C--Users-Admin-Desktop-DULUSV2"
+
+# How long to wait (seconds) with no new assistant entries before flushing
+# the accumulated turn as complete.
+FLUSH_TIMEOUT = 2.5
+
+
+def find_latest_session() -> Path | None:
+    """Find the most recently modified JSONL session file."""
+    files = list(SESSION_DIR.glob("*.jsonl"))
+    if not files:
+        return None
+    return max(files, key=lambda f: f.stat().st_mtime)
+
+
+def extract_text_blocks(entry: dict) -> list[str]:
+    """Return all text strings from an assistant entry's content blocks."""
+    msg = entry.get("message", {})
+    if msg.get("role") != "assistant":
+        return []
+    content = msg.get("content", "")
+    if isinstance(content, str):
+        t = content.strip()
+        return [t] if t else []
+    if isinstance(content, list):
+        parts = []
+        for block in content:
+            if isinstance(block, dict) and block.get("type") == "text":
+                t = block.get("text", "").strip()
+                if t:
+                    parts.append(t)
+        return parts
+    return []
+
+
+def has_tool_use(entry: dict) -> bool:
+    """True if this entry contains a tool_use block (mid-turn, more may follow)."""
+    msg = entry.get("message", {})
+    if msg.get("role") != "assistant":
+        return False
+    content = msg.get("content", "")
+    if isinstance(content, list):
+        return any(b.get("type") == "tool_use" for b in content if isinstance(b, dict))
+    return False
+
+
+def is_assistant(entry: dict) -> bool:
+    return entry.get("message", {}).get("role") == "assistant"
+
+
+def post_message(text: str, post_url: str):
+    try:
+        import urllib.request
+        payload = json.dumps({
+            "role": "assistant",
+            "source": "claude-code",
+            "text": text,
+        }).encode("utf-8")
+        req = urllib.request.Request(
+            post_url,
+            data=payload,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        urllib.request.urlopen(req, timeout=5)
+    except Exception as e:
+        print(f"[watcher] POST failed: {e}", flush=True)
+
+
+def watch(session_path: Path, post_url: str | None = None, poll_interval: float = 0.5):
+    """Tail the JSONL file and emit complete assistant turns."""
+    print(f"[watcher] Watching: {session_path}", flush=True)
+    print(f"[watcher] Post URL: {post_url or 'stdout only'}", flush=True)
+    print(f"[watcher] Flush timeout: {FLUSH_TIMEOUT}s after last assistant entry", flush=True)
+
+    seen_uuids: set = set()
+
+    # Seed existing entries
+    try:
+        with open(session_path, "r", encoding="utf-8", errors="ignore") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    entry = json.loads(line)
+                    uid = entry.get("uuid") or entry.get("id")
+                    if uid:
+                        seen_uuids.add(uid)
+                except Exception:
+                    pass
+        print(f"[watcher] Seeded {len(seen_uuids)} existing entries.", flush=True)
+    except Exception as e:
+        print(f"[watcher] Could not seed: {e}", flush=True)
+
+    # Accumulator for the current in-progress assistant turn
+    pending_texts: list[str] = []
+    pending_has_tool: bool = False
+    last_assistant_time: float = 0.0
+
+    while True:
+        try:
+            with open(session_path, "r", encoding="utf-8", errors="ignore") as f:
+                for line in f:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        entry = json.loads(line)
+                        uid = entry.get("uuid") or entry.get("id")
+                        if uid in seen_uuids:
+                            continue
+                        seen_uuids.add(uid)
+
+                        if not is_assistant(entry):
+                            # Non-assistant entry (user / tool_result) — if we have
+                            # pending text that ended with a tool_use, keep accumulating.
+                            # We'll flush on timeout or when the next text-only turn arrives.
+                            continue
+
+                        texts = extract_text_blocks(entry)
+                        tool = has_tool_use(entry)
+
+                        if texts:
+                            pending_texts.extend(texts)
+                            last_assistant_time = time.time()
+
+                        if tool:
+                            pending_has_tool = True
+                            last_assistant_time = time.time()
+
+                        # If this entry has ONLY tool_use (no text) it means we're
+                        # mid-turn — keep accumulating.
+                        # If this entry has text AND no tool_use, it MIGHT be the
+                        # final piece of the turn. We'll let the timeout decide.
+
+                    except Exception:
+                        pass
+
+        except Exception as e:
+            print(f"[watcher] Read error: {e}", flush=True)
+
+        # Flush if we have accumulated text and the turn has been quiet for FLUSH_TIMEOUT
+        if pending_texts and last_assistant_time > 0:
+            elapsed = time.time() - last_assistant_time
+            if elapsed >= FLUSH_TIMEOUT:
+                full_text = "\n\n".join(pending_texts)
+                print(f"\n[CLAUDE-CODE] {full_text[:300]}{'...' if len(full_text) > 300 else ''}", flush=True)
+
+                if post_url:
+                    post_message(full_text, post_url)
+
+                # Reset accumulator
+                pending_texts = []
+                pending_has_tool = False
+                last_assistant_time = 0.0
+
+        time.sleep(poll_interval)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Watch Claude Code session for new assistant messages.")
+    parser.add_argument("--session", type=str, default=None, help="Path to .jsonl session file")
+    parser.add_argument("--post", type=str, default=None, help="POST new messages to this URL")
+    parser.add_argument("--interval", type=float, default=0.5, help="Poll interval in seconds (default 0.5)")
+    parser.add_argument("--flush-timeout", type=float, default=FLUSH_TIMEOUT,
+                        help=f"Seconds of silence before flushing turn (default {FLUSH_TIMEOUT})")
+    args = parser.parse_args()
+
+    global FLUSH_TIMEOUT
+    FLUSH_TIMEOUT = args.flush_timeout
+
+    if args.session:
+        session_path = Path(args.session)
+    else:
+        session_path = find_latest_session()
+
+    if not session_path or not session_path.exists():
+        print(f"[watcher] Session file not found. Pass --session <path>")
+        sys.exit(1)
+
+    try:
+        watch(session_path, post_url=args.post, poll_interval=args.interval)
+    except KeyboardInterrupt:
+        print("\n[watcher] Stopped.")
+
+
+if __name__ == "__main__":
+    main()