bt-cli 0.4.64__tar.gz → 0.4.67__tar.gz

{bt_cli-0.4.64 → bt_cli-0.4.67}/CLAUDE.md

@@ -1,6 +1,6 @@
 # BT-CLI
 
-BeyondTrust Platform CLI for Password Safe, Entitle, PRA, EPM Windows, EPM Linux, and the BeyondTrust Secrets API. **Version: 0.4.64**
+BeyondTrust Platform CLI for Password Safe, Entitle, PRA, EPM Windows, EPM Linux, and the BeyondTrust Secrets API. **Version: 0.4.67**
 
 ## Setup
 
@@ -33,6 +33,7 @@ Use these slash commands for detailed product guidance:
 | `/epml` | EPM Linux - RBP roles/cmdgrps/usergrps, policy, test suites, transactions |
 | `/secrets` | Secrets API - folders, static, dynamic AWS credentials, leases, integrations |
 | `/pf` | Pathfinder platform - whoami, site/product access, PAT/MCP tokens, machines |
+| `/session-analysis` | Summarize a recorded RDP/SSH session from a `replay` dump (keyframe selection, keystroke focus, cost estimate) |
 
 ## Command Structure
 
@@ -88,7 +89,7 @@ PASSWORD=$(bt pws quick checkout -s server -a admin --raw)
 - **PWS `/Sessions` ignores `limit`/`offset`** and returns the full session *history* every call — never `paginate()` it (infinite loop); `list_sessions` does a single GET and `bt pws sessions list` caps display client-side. `Status` codes (live-confirmed): 0=Not started, 1=Active, 2=Completed, 5=Locked, 7=Terminated; `--active`=Status 1. Active sessions have `EndTime`==`StartTime` (placeholder, not null) — identify live sessions by Status, not timestamps. **`terminate` = `POST /Sessions/{id}/Terminate`** (symmetric w/ `/Lock`); `/Sessions/{id}` is GET/PUT only (DELETE → 405).
 - **PWS SSH/RDP session establishment = `POST /Requests/{id}/Sessions`** (`{"SessionType":"SSH"|"RDP"}`), NOT `POST /Sessions` (collection is GET-only → 405). Create the request with matching `AccessType` first. **SSH** returns a ready `Command` (`ssh -p 4422 <ticket>@<proxyhost>`) + `Link`; **RDP** returns `Host`/`Port`/`Ticket` only — the `.rdp` is built client-side (`full address` = proxy `Host:Port`, `username` = `Ticket`); there's no server-side launch file (`/Sessions/RDPFile` is audit-playback → 403). Ticket is the proxy username; password is proxy-injected. `bt pws quick checkout --access-type ssh|rdp` and `bt pws quick ssh`/`quick rdp` (with `--launch`); session commands do **not** auto-checkin.
 - **PWS session keystroke transcript = `GET /Sessions/{id}/Keystrokes`** → events `{KeystrokeID, TimeMarker (epoch ms), Type, Data}`. **Type 1 = user input** (typed keys; special keys as glyphs `⌫`/`→`/`↑`), **Type 2 = terminal output** (SSH stdout). SSH captures a full input+output transcript; **RDP is sparse** (typed keys / window events only, off by default → often empty). Surfaced as `bt pws sessions transcript <id>` (default = time-ordered readable transcript; `--input-only`; text/json/csv). Text trail, not the visual recording. (There is **no** `bt pws sessions export` — session *metadata* evidence is `bt pws audit export`.)
-- **PWS session recording download = headless replay under `/pbsm/replay`** (there is **no** video-export API — `?video/?mp4/?webm` return JSON, not media). Flow: `GET /Sessions/{id}` for `Token`+`RecordKey`+`Protocol` → `POST /pbsm/replay` `{id:Token, record_key, protocol:"RDP"|"SSH", headless:true}` → `PUT /pbsm/replay/{rid}` `{offset:<ms>}` (seek) → `GET /pbsm/replay/{rid}?png=<scale>` (one PNG per offset) → `DELETE /pbsm/replay/{rid}`. **Warm-up:** the first `PUT` 404s (`"no such file or directory"`) until the renderer loads — retry ~0.5s. The seek response is state `{offset, next, eof, duration}`; **`next` = next recorded frame's offset**, enabling event-driven stepping. Surfaced as `bt pws sessions replay <id>` (event-driven default; `--fps`/`--interval` fixed sampling; `--from/--to`, `--scale`, `--max-frames`; `--mp4` stitches via ffmpeg, else prints the command + install hint). Always `DELETE`s the replay in `finally`.
+- **PWS session recording download = headless replay under `/pbsm/replay`** (there is **no** video-export API — `?video/?mp4/?webm` return JSON, not media). Flow: `GET /Sessions/{id}` for `Token`+`RecordKey`+`Protocol` → `POST /pbsm/replay` `{id:Token, record_key, protocol:"RDP"|"SSH", headless:true}` → `PUT /pbsm/replay/{rid}` `{offset:<ms>}` (seek) → `GET /pbsm/replay/{rid}?png=<scale>` (one PNG per offset) → `DELETE /pbsm/replay/{rid}`. **Warm-up:** the first `PUT` 404s (`"no such file or directory"`) until the renderer loads — retry ~0.5s. The seek response is state `{offset, next, eof, duration}`; **`next` = next recorded frame's offset**, enabling event-driven stepping. **`bt pws sessions analyze <id>` (or `--dir`)** preps a replay dump for LLM analysis without calling an LLM: reads `index.json`, selects **keyframes** (RDP frames whose PNG byte-size changed ≥`--threshold`%, dependency-free — no Pillow, UNION the frame that renders each **typed keystroke burst**, anchored via the recording `StartTime` → each keyframe tagged `screen-change`/`after-typing` with the `typed` text, so the model reads targeted spots not every frame), and prints a token/USD **cost estimate** (`--model opus|sonnet|haiku`) for focused (keyframes) vs all-frames; writes `analysis.json`. SSH → recommends the transcript over frames. Consumed by the `/session-analysis` skill (interactive; the model reads only the keyframes). Surfaced as `bt pws sessions replay <id>`. **Default = even coverage + dedup**: ~60 evenly-spaced frames across the whole session (`--frames N`) with consecutive-identical frames skipped (`--dedup`, sha1-based) — because event-driven over-samples RDP (it records many deltas as the screen paints, so `next`-stepping clusters at the login and burns the frame budget before covering the timeline). Modes are mutually exclusive: `--frames` (default) / `--fps` / `--interval` / `--all-frames` (event-driven forensic). Also `--from/--to`, `--scale`, `--max-frames`, `--no-dedup`; `--mp4` stitches via ffmpeg, else prints the command + install hint. Always `DELETE`s the replay in `finally`.
 - Entitle permissions: Use server-side filters (`--resource`, `--user`, `--integration`) - dataset can be 20k+ records
 - Entitle users: Use `--all` flag only when needed - default fetches first page only
 - Windows builds: Rich must be pinned to `<14.0.0` (Rich 14 has PyInstaller unicode issues)

{bt_cli-0.4.64 → bt_cli-0.4.67}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bt-cli
-Version: 0.4.64
+Version: 0.4.67
 Summary: BeyondTrust Platform CLI (unofficial) - Password Safe, Entitle, PRA, EPM
 Author-email: Dave Grendysz <dgrendysz@beyondtrust.com>
 License: MIT

{bt_cli-0.4.64 → bt_cli-0.4.67}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bt-cli"
-version = "0.4.64"
+version = "0.4.67"
 description = "BeyondTrust Platform CLI (unofficial) - Password Safe, Entitle, PRA, EPM"
 readme = "README.md"
 requires-python = ">=3.9"

{bt_cli-0.4.64 → bt_cli-0.4.67}/src/bt_cli/__init__.py

@@ -1,3 +1,3 @@
 """BeyondTrust Unified Admin CLI."""
 
-__version__ = "0.4.64"
+__version__ = "0.4.67"

{bt_cli-0.4.64 → bt_cli-0.4.67}/src/bt_cli/cli.py

@@ -668,11 +668,15 @@ def skills(
     These skills help AI agents (like Claude Code) navigate bt-cli commands.
 
     Skills included:
-        /bt       - Cross-product commands (PASM workflows)
-        /pws      - Password Safe commands
-        /pra      - PRA commands
-        /entitle  - Entitle commands
-        /epmw     - EPM Windows commands
+        /bt                - Cross-product commands (PASM workflows)
+        /pws               - Password Safe commands
+        /pra               - PRA commands
+        /entitle           - Entitle commands
+        /epmw              - EPM Windows commands
+        /epml              - EPM Linux commands
+        /secrets           - Secrets API commands
+        /pf                - Pathfinder platform commands
+        /session-analysis  - Summarize a recorded RDP/SSH session from a replay dump
 
     Examples:
         bt skills              # Install to current directory

{bt_cli-0.4.64 → bt_cli-0.4.67}/src/bt_cli/data/skills/pws/SKILL.md

@@ -215,22 +215,31 @@ recording. For session *metadata* evidence, use `bt pws audit export`.
 
 ```bash
 # Download the VISUAL recording as PNG frames (RDP screen / SSH terminal)
-bt pws sessions replay <session_id>                    # event-driven frames + index.json
-bt pws sessions replay <session_id> --mp4              # also stitch an MP4 (needs ffmpeg)
+bt pws sessions replay <session_id>                    # ~60 frames across the session, deduped
+bt pws sessions replay <session_id> --frames 30        # ~30 evenly-spaced frames
 bt pws sessions replay <session_id> --fps 1 --to 120   # 1 fps for the first 2 minutes
-bt pws sessions replay <session_id> --out ./review --scale 1 --max-frames 500
+bt pws sessions replay <session_id> --all-frames --no-dedup   # every recorded frame, verbatim
+bt pws sessions replay <session_id> --mp4              # also stitch an MP4 (needs ffmpeg)
 ```
 
 `replay` drives the headless renderer at `/pbsm/replay` (there is **no**
 video-export API): create replay → seek by offset → pull one PNG per frame →
-delete. By default it steps **event-driven** (following the replay state's
-`next`/`eof` fields, one frame per recorded change); `--fps`/`--interval` force
-fixed-rate sampling. **It's one network round-trip per frame, so long sessions
-are slow** - bound them with `--fps`, `--from/--to`, or `--max-frames` (default
-3600). `--mp4` stitches with ffmpeg (H.264); if ffmpeg is missing it prints the
-exact command + install instructions and leaves the frames. Works for RDP
-(screen) and SSH (rendered terminal). Gotcha: the renderer needs ~0.5s warm-up
-(first seek 404s), handled automatically.
+delete. **By default it captures ~60 evenly-spaced frames across the whole
+session and skips identical frames** (`--dedup`), so you see the full timeline
+rather than just the busy start. Sampling modes are mutually exclusive:
+
+- `--frames N` (default, N=60) — N frames spread evenly across the session
+- `--fps F` / `--interval MS` — fixed-rate sampling
+- `--all-frames` — event-driven, one frame per recorded change (forensic; can be
+  huge — RDP records many deltas while the screen paints, which is why this
+  isn't the default)
+
+**One network round-trip per frame**, so bound long captures with `--frames`,
+`--from/--to`, or `--max-frames` (default 3600). `--no-dedup` keeps every
+sampled frame. `--mp4` stitches with ffmpeg (H.264); if ffmpeg is missing it
+prints the exact command + install instructions and leaves the frames. Works for
+RDP (screen) and SSH (rendered terminal). Gotcha: the renderer needs ~0.5s
+warm-up (first seek 404s), handled automatically.
 
 **Gotchas:**
 - `/Sessions` returns session **history**, not just active sessions, and **ignores `limit`/`offset`** (returns the full set every call - the client does a single GET, the CLI caps display client-side). Use `--active` for the live ones.

bt_cli-0.4.67/src/bt_cli/data/skills/session-analysis/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: session-analysis
+description: Analyze a dumped Password Safe session (replay frames + keystrokes) into a timeline summary with a cost estimate. Use when the user points at a `session-<id>-replay` folder or asks to summarize/analyze a recorded RDP or SSH session.
+---
+
+# Session Analysis
+
+Turn a bt-cli session dump into a **timeline summary of what happened**, efficiently, with a **cost estimate**. Works for RDP (screen recording → frames) and SSH (keystroke transcript). This is interactive analysis — *you* (the model) read the frames/transcript; there is no LLM call inside the CLI.
+
+## The one rule: never read every frame
+
+An RDP session sampled at ~1 frame per 2s is dozens of near-identical frames. Reading them all wastes tokens. Let the CLI pick the frames worth reading — the ones where the screen changed **and** the ones that render what the user typed — and read only those, guided by the per-frame `typed`/`reason` tags.
+
+## Recipe
+
+### 1. Prep with the CLI (does the heavy lifting)
+
+```bash
+# If the user has a replay folder already:
+bt pws sessions analyze --dir <folder>
+# If they have the session id (reads ./session-<id>-replay):
+bt pws sessions analyze <id> --model opus   # or --model sonnet for a cheaper estimate
+```
+
+`analyze` writes `analysis.json` into the folder and prints:
+- **RDP:** the **keyframes** to read (a handful, not all). Each keyframe is tagged with a **reason** — `screen-change` (the picture moved) and/or `after-typing` (it renders the result of something the user typed). `after-typing` frames also carry the exact `typed` text.
+- **SSH:** a pointer to the transcript (analyze it instead of frames).
+- **`typed_bursts`** — typed input grouped into phrases with recording-relative offsets (`@14.9s "powershell"`), already anchored to the keyframes above.
+- A **cost estimate**: `focused` (keyframes only) vs `all frames`.
+
+If the user only has a folder (no live API access), `analyze --dir` still works — keystrokes need session metadata (`StartTime`) to anchor, so offline it falls back to `screen-change` keyframes only, with a note. Keyframes + cost are still computed.
+
+### 2. Read the right inputs — targeted, in `analysis.json` order
+
+- **RDP:** `Read` only the keyframe PNGs the CLI listed. **Prioritize the `after-typing` frames** — they're where a user action produced a visible result (a launched app, a command's output, an EPM prompt). For each, the `typed` field tells you what to look for *before* you open the image, so you read with intent instead of scanning. The `screen-change`-only frames fill in transitions the keystrokes don't cover (mouse-driven actions: menus, service restarts, window closes). If a keyframe implies something happened between it and the next, that's fine — the summary is event-level, not frame-level.
+- **SSH:** run `bt pws sessions transcript <id>` and read that — it's the full input+output, far richer and cheaper than frames. Frames are rarely worth reading for SSH.
+
+### 3. Anchoring is already done
+
+The CLI has correlated keystrokes → frames for you (via the recording `StartTime`): the `typed` field on each keyframe and the `typed_bursts` list *are* the timeline anchors. Just narrate them — "at ~0:14 typed `powershell`, frame at 16s shows PowerShell 7 open". If RDP keystroke capture was off (bursts empty), fall back to reading the screen-change frames and inferring actions from the pictures alone.
+
+### 4. Write the summary
+
+Produce:
+- **Timeline table** — approximate time → event (app launched, window opened, command run, dialog shown, service changed, logoff).
+- **Highlights an auditor cares about** — EPM/Defendpoint elevation or justification prompts, privileged tools (`dsa.msc`, `services.msc`, PowerShell), AD/account/OU changes, service start/stop, file transfers.
+- **Security note** — explicitly state whether any credentials, passwords, tokens, or secret values were visible in the frames read.
+- **Cost** — report the estimate from `analysis.json` (and, if you want, the actual: images read × ~`(w*h)/750` tokens + output).
+
+## Efficiency notes
+
+- Two selection signals combine: PNG-size delta (`screen-change`, dependency-free) and keystroke anchoring (`after-typing`, when RDP keystroke capture is on). Anchoring is what makes the read *targeted* — it guarantees the frame that shows each typed action is included, even if its size barely moved. If a session looks under-sampled (transitions missed), re-run `analyze --threshold 1.5` for more keyframes; over-sampled → raise it.
+- Frame token cost ≈ `(width × height) / 750` per image (1024×768 ≈ ~1,050 tokens). The CLI's estimate already accounts for this.
+- Pricing (per 1M tokens, for the estimate): Opus 4.8 $5/$25, Sonnet 4.6 $3/$15, Haiku 4.5 $1/$5. Use the `claude-api` skill for current numbers.
+
+## Scaling up (optional, not built)
+
+For summarizing **many** sessions unattended, this interactive recipe doesn't scale — that would be a `bt pws sessions summarize` command calling the Claude API (vision) with the same keyframe/transcript inputs and the Batch API for volume. Mention it if the user wants automation; today, analysis is interactive.
+
+## Related
+
+- `bt pws sessions replay <id>` — produce the frames (defaults to even coverage + dedup).
+- `bt pws sessions transcript <id>` — the keystroke transcript (SSH gold; RDP sparse).
+- `/pws` skill — Password Safe command reference.

{bt_cli-0.4.64 → bt_cli-0.4.67}/src/bt_cli/pws/commands/sessions.py

@@ -1,5 +1,6 @@
 """CLI commands for managing active Password Safe sessions."""
 
+import hashlib
 import json
 import shutil
 import subprocess
@@ -10,6 +11,7 @@ from pathlib import Path
 import httpx
 import typer
 from rich.console import Console
+from rich.markup import escape as rich_escape
 from rich.table import Table
 
 from ...core.output import print_api_error, print_error, print_warning
@@ -365,8 +367,11 @@ def _warmup_seek(client, replay_id: str, offset_ms: int, quiet: bool, attempts:
 def session_replay(
     session_id: int = typer.Argument(..., help="Session ID (from `sessions list`)"),
     out: str = typer.Option(None, "--out", help="Output directory (default: ./session-<id>-replay)"),
-    fps: float = typer.Option(None, "--fps", help="Fixed sampling rate (frames/sec). Default: event-driven (one frame per recorded change)"),
-    interval: int = typer.Option(None, "--interval", help="Fixed sampling interval in ms (alternative to --fps)"),
+    frames: int = typer.Option(None, "--frames", help="Target number of evenly-spaced frames across the session (default: 60)"),
+    fps: float = typer.Option(None, "--fps", help="Fixed sampling rate in frames/sec (alternative to --frames)"),
+    interval: int = typer.Option(None, "--interval", help="Fixed sampling interval in ms (alternative to --frames)"),
+    all_frames: bool = typer.Option(False, "--all-frames", help="Capture every recorded frame change (event-driven; forensic, can be very large)"),
+    dedup: bool = typer.Option(True, "--dedup/--no-dedup", help="Skip consecutive identical frames (on by default)"),
     scale: int = typer.Option(1, "--scale", help="PNG scale factor (1 = full size)"),
     start: float = typer.Option(0, "--from", help="Start offset in seconds"),
     end: float = typer.Option(None, "--to", help="End offset in seconds (default: end of session)"),
@@ -381,21 +386,34 @@ def session_replay(
     Password Safe has no video-export API, so this drives the headless replay
     renderer: it seeks through the recording and pulls one PNG per frame, then
     (with --mp4) stitches them with ffmpeg. Works for RDP (screen) and SSH
-    (rendered terminal). Note: one network round-trip per frame, so long
-    sessions take a while - use --fps/--interval, --from/--to, or --max-frames.
+    (rendered terminal).
+
+    By default it captures ~60 evenly-spaced frames across the whole session
+    (so you see the full timeline, not just the busy start) and skips identical
+    frames (--dedup). Use --frames/--fps/--interval to change the sampling rate,
+    or --all-frames for the forensic every-recorded-change mode (can be huge -
+    RDP records many deltas while the screen paints). One network round-trip per
+    frame, so bound long captures with --frames, --from/--to, or --max-frames.
 
     Examples:
-        bt pws sessions replay 1460                       # event-driven frames + index
-        bt pws sessions replay 1460 --mp4                 # also build an MP4
+        bt pws sessions replay 1460                       # ~60 frames across the session, deduped
+        bt pws sessions replay 1460 --frames 30           # ~30 evenly-spaced frames
         bt pws sessions replay 1460 --fps 1 --to 120      # 1 fps for the first 2 minutes
-        bt pws sessions replay 1460 --out ./review --mp4 --mp4-fps 8
+        bt pws sessions replay 1460 --all-frames --no-dedup   # every recorded frame, verbatim
+        bt pws sessions replay 1460 --mp4                 # also build an MP4
     """
     quiet = output == "json"
-    fixed_interval = None
-    if fps is not None and interval is not None:
-        print_error("Use --fps or --interval, not both.")
+    # Resolve sampling mode (mutually exclusive). Default = even-coverage frames.
+    n_modes = sum(x is not None for x in (frames, fps, interval)) + int(all_frames)
+    if n_modes > 1:
+        print_error("Choose one of --frames / --fps / --interval / --all-frames.")
         raise typer.Exit(2)
-    if fps is not None:
+
+    fixed_interval = None       # set for fps/interval; computed later for frames mode
+    frames_target = None        # set for even-coverage frames mode
+    if all_frames:
+        pass                    # event-driven: fixed_interval stays None
+    elif fps is not None:
         if fps <= 0:
             print_error("--fps must be positive.")
             raise typer.Exit(2)
@@ -405,6 +423,11 @@ def session_replay(
             print_error("--interval must be positive.")
             raise typer.Exit(2)
         fixed_interval = interval
+    else:
+        frames_target = frames if frames is not None else 60
+        if frames_target <= 0:
+            print_error("--frames must be positive.")
+            raise typer.Exit(2)
 
     out_dir = Path(out) if out else Path(f"session-{session_id}-replay")
     replay_id = None
@@ -435,7 +458,15 @@ def session_replay(
             total_ms = state.get("duration") or int(duration_s * 1000)
             end_ms = int(end * 1000) if end is not None else total_ms
 
+            # Even-coverage mode: spread the target frame count across the span
+            # (endpoints included), then capture like a fixed interval.
+            if frames_target is not None:
+                span = max(0, end_ms - start_ms)
+                fixed_interval = max(1, span // frames_target) if frames_target > 1 else span + 1
+
             frames: list[dict] = []
+            deduped = 0
+            last_hash = None
             offset = start_ms
             settle = settle_ms / 1000.0
             while True:
@@ -450,13 +481,19 @@ def session_replay(
                     if fixed_interval is None:
                         break
                 else:
-                    idx = len(frames)
-                    fname = f"frame_{idx:04d}.png"
-                    (out_dir / fname).write_bytes(png)
-                    frames.append({"file": fname, "offset_ms": offset})
+                    digest = hashlib.sha1(png).digest()
+                    if dedup and digest == last_hash:
+                        deduped += 1  # identical to the previous kept frame - skip
+                    else:
+                        last_hash = digest
+                        idx = len(frames)
+                        fname = f"frame_{idx:04d}.png"
+                        (out_dir / fname).write_bytes(png)
+                        frames.append({"file": fname, "offset_ms": offset})
                     if not quiet:
                         pct = min(100, int(offset / total_ms * 100)) if total_ms else 0
-                        console.print(f"\r[cyan]  {len(frames)} frames  {offset/1000:.1f}s  ({pct}%)[/cyan]", end="")
+                        dd = f"  (-{deduped} dup)" if deduped else ""
+                        console.print(f"\r[cyan]  {len(frames)} frames  {offset/1000:.1f}s  ({pct}%){dd}[/cyan]", end="")
 
                 # Advance
                 if fixed_interval is not None:
@@ -515,13 +552,15 @@ def session_replay(
                 "protocol": protocol,
                 "output_dir": str(out_dir.resolve()),
                 "frame_count": len(frames),
+                "deduped": deduped,
                 "mp4": str(mp4_path.resolve()) if mp4_path else None,
             }, default=str))
         else:
             if not frames:
                 console.print(f"[yellow]No frames captured for session {session_id}.[/yellow]")
             else:
-                console.print(f"[green]Captured {len(frames)} frame(s).[/green]")
+                dd = f" ({deduped} duplicate(s) skipped)" if deduped else ""
+                console.print(f"[green]Captured {len(frames)} frame(s).{dd}[/green]")
                 console.print(f"  Frames: [cyan]{out_dir.resolve()}[/cyan]")
                 if mp4_path:
                     console.print(f"  MP4:    [cyan]{mp4_path.resolve()}[/cyan]")
@@ -548,6 +587,271 @@ def session_replay(
                 pass
 
 
+# Vision cost estimate: input/output USD per 1M tokens (from claude-api pricing).
+COST_MODELS = {
+    "opus": ("claude-opus-4-8", 5.0, 25.0),
+    "sonnet": ("claude-sonnet-4-6", 3.0, 15.0),
+    "haiku": ("claude-haiku-4-5", 1.0, 5.0),
+}
+
+
+def _png_dims(path: Path) -> tuple:
+    """Read (width, height) from a PNG IHDR without any image library."""
+    try:
+        head = path.read_bytes()[:24]
+        if head[:8] == b"\x89PNG\r\n\x1a\n":
+            return int.from_bytes(head[16:20], "big"), int.from_bytes(head[20:24], "big")
+    except Exception:
+        pass
+    return (1024, 768)
+
+
+def _image_tokens(w: int, h: int) -> int:
+    """Anthropic vision token estimate for an image (~(w*h)/750)."""
+    return (w * h + 749) // 750
+
+
+def _select_keyframes(folder: Path, frames: list[dict], threshold_pct: float) -> list[dict]:
+    """Pick frames whose PNG size differs from the previous kept frame by
+    >= threshold_pct. A new window/screen changes the encoded size sharply, so
+    this cheaply approximates 'the screen meaningfully changed' without decoding
+    pixels. First and last frames are always kept."""
+    keyframes: list[dict] = []
+    prev_size = None
+    for i, f in enumerate(frames):
+        try:
+            size = (folder / f["file"]).stat().st_size
+        except OSError:
+            continue
+        is_last = i == len(frames) - 1
+        if prev_size is None or is_last or abs(size - prev_size) / max(prev_size, 1) * 100 >= threshold_pct:
+            keyframes.append(f)
+            prev_size = size
+    return keyframes
+
+
+def _epoch_ms(value) -> int:
+    """Parse an ISO-8601 timestamp (or raw epoch ms) to epoch milliseconds.
+    Naive timestamps are treated as UTC. Returns None if unparseable."""
+    if value in (None, "", "-"):
+        return None
+    try:
+        return int(value)  # already epoch ms
+    except (TypeError, ValueError):
+        pass
+    try:
+        dt = datetime.fromisoformat(str(value).strip().replace("Z", "+00:00"))
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        return int(dt.timestamp() * 1000)
+    except (TypeError, ValueError):
+        return None
+
+
+def _keystroke_bursts(keystrokes: list[dict], start_epoch: int, gap_ms: int = 2500) -> list[dict]:
+    """Group typed-input keystrokes (Type 1) into bursts — one phrase the user
+    typed — each carrying `offset_ms` (ms from recording start) so it can be
+    anchored to a frame. Consecutive inputs within `gap_ms` join one burst.
+    Needs `start_epoch` (recording start, epoch ms) to convert the absolute
+    keystroke TimeMarkers into recording-relative offsets; returns [] without it
+    (e.g. offline `--dir` with no session metadata)."""
+    if start_epoch is None:
+        return []
+    inputs = sorted(
+        (k for k in keystrokes if k.get("Type") == 1 and k.get("TimeMarker") is not None),
+        key=lambda k: (k.get("TimeMarker", 0), k.get("KeystrokeID", 0)),
+    )
+    bursts: list[dict] = []
+    for k in inputs:
+        rel = int(k["TimeMarker"]) - start_epoch
+        data = k.get("Data", "")
+        if bursts and rel - bursts[-1]["offset_ms"] <= gap_ms:
+            bursts[-1]["text"] += data
+            bursts[-1]["offset_ms"] = rel
+        else:
+            bursts.append({"text": data, "offset_ms": rel})
+    return bursts
+
+
+def _frame_after(frames: list[dict], offset_ms: int) -> dict:
+    """The frame at or just after `offset_ms` — i.e. the screen state that
+    results from an action taken at that time. Falls back to the last frame."""
+    after = [f for f in frames if f.get("offset_ms", 0) >= offset_ms]
+    if after:
+        return min(after, key=lambda f: f.get("offset_ms", 0))
+    return frames[-1] if frames else None
+
+
+def _build_keyframes(
+    folder: Path, frames: list[dict], threshold_pct: float, bursts: list[dict]
+) -> list[dict]:
+    """Keyframes = screen-change frames (PNG-size delta) UNION the frame that
+    renders each typed burst, sorted by time. Each kept frame is annotated with
+    `reasons` (why it was picked) and, when applicable, `typed` (what the user
+    typed just before it) so the model reads each frame with intent instead of
+    scanning blindly."""
+    size_kfs = _select_keyframes(folder, frames, threshold_pct)
+    size_files = {f["file"] for f in size_kfs}
+    typed_by_file: dict[str, list[str]] = {}
+    for b in bursts:
+        fr = _frame_after(frames, b["offset_ms"])
+        if fr and b["text"].strip():
+            typed_by_file.setdefault(fr["file"], []).append(b["text"])
+
+    selected = {f["file"]: dict(f) for f in size_kfs}
+    for f in frames:
+        if f["file"] in typed_by_file and f["file"] not in selected:
+            selected[f["file"]] = dict(f)
+
+    keyframes = sorted(selected.values(), key=lambda f: f.get("offset_ms", 0))
+    for f in keyframes:
+        reasons = []
+        if f["file"] in size_files:
+            reasons.append("screen-change")
+        if f["file"] in typed_by_file:
+            reasons.append("after-typing")
+            f["typed"] = typed_by_file[f["file"]]
+        f["reasons"] = reasons
+    return keyframes
+
+
+@app.command("analyze")
+def session_analyze(
+    session_id: int = typer.Argument(None, help="Session ID (defaults to reading ./session-<id>-replay)"),
+    folder: str = typer.Option(None, "--dir", help="Replay folder (with index.json + frames). Default: ./session-<id>-replay"),
+    threshold: float = typer.Option(3.0, "--threshold", help="Keyframe sensitivity: min %% PNG-size change vs previous kept frame (RDP)"),
+    model: str = typer.Option("opus", "--model", help="Model for the cost estimate: opus | sonnet | haiku"),
+    output: str = typer.Option("text", "--output", "-o", help="Output format: text or json"),
+) -> None:
+    """Prep a dumped session for LLM analysis: pick keyframes, pull keystrokes, estimate cost.
+
+    Reads a `replay` folder (frames + index.json) and writes an `analysis.json`
+    manifest that a model can consume efficiently:
+      - RDP: selects keyframes (frames where the screen changed) so you read a
+        handful instead of every frame, and pulls the sparse typed-keystroke
+        metadata to focus the read.
+      - SSH: the keystroke transcript is the primary signal (cheap text) - frames
+        are rarely needed.
+    Also prints a token/cost estimate. It does NOT call an LLM itself - feed the
+    keyframes/transcript to Claude (see the session-analysis skill).
+
+    Examples:
+        bt pws sessions replay 1491 && bt pws sessions analyze 1491
+        bt pws sessions analyze --dir ./session-1491-replay
+        bt pws sessions analyze 1491 --model sonnet -o json
+    """
+    if model not in COST_MODELS:
+        print_error(f"Unknown --model '{model}'. Choose: {', '.join(COST_MODELS)}")
+        raise typer.Exit(2)
+
+    base = Path(folder) if folder else (Path(f"session-{session_id}-replay") if session_id else None)
+    if base is None:
+        print_error("Provide a session id or --dir.")
+        raise typer.Exit(2)
+    idx_path = base / "index.json"
+    if not idx_path.exists():
+        print_error(f"No index.json in {base} - run `bt pws sessions replay` first.")
+        raise typer.Exit(1)
+
+    idx = json.loads(idx_path.read_text())
+    protocol = idx.get("protocol", "RDP")
+    frames = idx.get("frames", [])
+    sid = session_id or idx.get("session_id")
+
+    # Pull keystrokes + session meta (best-effort; folder may be analyzed offline)
+    keystrokes: list[dict] = []
+    meta: dict = {}
+    if sid:
+        try:
+            with get_client() as client:
+                client.authenticate()
+                meta = client.get_session(sid)
+                keystrokes = client.get_keystrokes(sid)
+        except Exception as e:
+            if output != "json":
+                print_warning(f"Could not pull keystrokes for session {sid} ({e}); continuing with frames only.")
+
+    decoded_ks = [
+        {"time": _fmt_marker(k.get("TimeMarker")), "type": _keystroke_type(k.get("Type")), "data": k.get("Data", "")}
+        for k in sorted(keystrokes, key=lambda k: (k.get("TimeMarker", 0), k.get("KeystrokeID", 0)))
+    ]
+
+    w, h = _png_dims(base / frames[0]["file"]) if frames else (1024, 768)
+    per_img = _image_tokens(w, h)
+    ks_tokens = max(1, len(json.dumps(decoded_ks)) // 4)
+
+    # Correlate typed keystrokes to the recording timeline so we can target the
+    # frames that render each action (needs the recording's start time).
+    start_epoch = _epoch_ms(meta.get("StartTime"))
+    bursts = _keystroke_bursts(keystrokes, start_epoch)
+
+    # For SSH the transcript carries the session; frames are optional.
+    if protocol.upper() == "SSH":
+        keyframes = frames[:0]  # recommend transcript-first
+        recommended = "transcript"
+    else:
+        keyframes = _build_keyframes(base, frames, threshold, bursts)
+        recommended = "keyframes"
+
+    model_id, price_in, price_out = COST_MODELS[model]
+    overhead, out_tokens = 1500, 1000
+
+    def _cost(n_imgs: int) -> dict:
+        inp = n_imgs * per_img + ks_tokens + overhead
+        usd = inp / 1e6 * price_in + out_tokens / 1e6 * price_out
+        return {"images": n_imgs, "input_tokens": inp, "output_tokens": out_tokens, "usd": round(usd, 4)}
+
+    est_focused = _cost(len(keyframes))
+    est_all = _cost(len(frames))
+
+    manifest = {
+        "session_id": sid,
+        "protocol": protocol,
+        "frame_dims": [w, h],
+        "frame_count": len(frames),
+        "keyframe_count": len(keyframes),
+        "keyframes": keyframes,
+        "keystroke_count": len(decoded_ks),
+        "keystrokes": decoded_ks,
+        "typed_bursts": bursts,
+        "recommended_input": recommended,
+        "cost_estimate": {"model": model_id, "focused": est_focused, "all_frames": est_all},
+    }
+    (base / "analysis.json").write_text(json.dumps(manifest, indent=2))
+
+    if output == "json":
+        console.print_json(json.dumps(manifest, default=str))
+        return
+
+    acct = meta.get("ManagedAccountName", "?")
+    sysn = meta.get("AssetName", "?")
+    console.print(f"[bold]Session {sid}[/bold]  {protocol}  {acct}@{sysn}")
+    console.print(f"  Frames: {len(frames)} ({w}x{h})   Keystroke events: {len(decoded_ks)}")
+    if protocol.upper() == "SSH":
+        console.print("  [green]SSH → analyze the transcript[/green] (cheap, full input+output):")
+        console.print(f"    [cyan]bt pws sessions transcript {sid}[/cyan]")
+    else:
+        anchored = sum(1 for k in keyframes if "after-typing" in k.get("reasons", []))
+        hint = f" ([cyan]{anchored}[/cyan] anchored to typed input)" if anchored else ""
+        console.print(f"  [green]{len(keyframes)} keyframes[/green] (of {len(frames)}) — read these, not every frame{hint}:")
+        for k in keyframes:
+            typed_here = "  [yellow]⌨ " + rich_escape(" ".join(k["typed"])) + "[/yellow]" if k.get("typed") else ""
+            reasons = ",".join(k.get("reasons", [])) or "screen-change"
+            console.print(f"    {base / k['file']}   [dim]@ {k['offset_ms']/1000:.1f}s · {reasons}[/dim]{typed_here}")
+    if bursts:
+        console.print("  [green]Typed input[/green] (recording-relative — anchors above):")
+        for b in bursts[:12]:
+            console.print(f"    [dim]@ {b['offset_ms']/1000:.1f}s[/dim] {rich_escape(b['text'])}")
+    elif protocol.upper() != "SSH" and [k for k in decoded_ks if k["type"] == "input"]:
+        console.print("  [dim]Typed input present but no StartTime to anchor it to frames (offline?).[/dim]")
+    console.print(
+        f"\n  [bold]Cost estimate[/bold] ({model_id}): "
+        f"focused ≈ [green]${est_focused['usd']:.4f}[/green] ({est_focused['images']} imgs) · "
+        f"all frames ≈ ${est_all['usd']:.4f} ({est_all['images']} imgs)"
+    )
+    console.print(f"  [dim]Manifest: {base / 'analysis.json'}[/dim]")
+
+
 @app.command("suspend")
 def suspend_session(
     session_id: int = typer.Argument(..., help="Session ID to lock/suspend"),