bt-cli 0.4.65__tar.gz → 0.4.68__tar.gz

{bt_cli-0.4.65 → bt_cli-0.4.68}/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.65**
+BeyondTrust Platform CLI for Password Safe, Entitle, PRA, EPM Windows, EPM Linux, and the BeyondTrust Secrets API. **Version: 0.4.68**
 
 ## 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>`. **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`.
+- **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.65 → bt_cli-0.4.68}/PKG-INFO

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

{bt_cli-0.4.65 → bt_cli-0.4.68}/pyproject.toml

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

{bt_cli-0.4.65 → bt_cli-0.4.68}/src/bt_cli/__init__.py

@@ -1,3 +1,3 @@
 """BeyondTrust Unified Admin CLI."""
 
-__version__ = "0.4.65"
+__version__ = "0.4.68"

{bt_cli-0.4.65 → bt_cli-0.4.68}/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.65 → bt_cli-0.4.68}/src/bt_cli/data/skills/pws/SKILL.md

@@ -189,6 +189,11 @@ bt pws sessions list --active        # only live sessions (started, not ended)
 bt pws sessions list --all -o json   # full history
 bt pws sessions get <session_id>
 
+# "The session from today" — date filters match on StartTime (client-side)
+bt pws sessions list --today
+bt pws sessions list --on 2026-07-02
+bt pws sessions list --since 2026-06-01 --until 2026-06-30   # a range (e.g. "this week")
+
 # Suspend = lock (user disconnected, session can be resumed)
 bt pws sessions suspend <session_id>
 
@@ -241,6 +246,27 @@ 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.
 
+### "What happened in this session?" — summarize efficiently
+
+`replay` only *downloads* frames. To turn a session into a **timeline summary of
+what the user did**, don't read every frame — use the analysis pipeline:
+
+```bash
+bt pws sessions replay <session_id>       # 1. download the frames
+bt pws sessions analyze <session_id>      # 2. pick keyframes + anchor keystrokes + estimate cost
+```
+
+`analyze` is deterministic prep (no LLM): it selects the handful of frames worth
+reading — screen-change frames **plus** the frames that render what the user
+typed (keystroke-anchored, tagged `after-typing` with the `typed` text) — pulls
+the transcript, and prints a token/USD cost estimate. Then **invoke the
+`/session-analysis` skill**, which tells you (the agent) to read only those
+keyframes (after-typing first) and produce a timeline + auditor highlights (EPM
+elevation prompts, privileged tools, service/account changes) + a secrets-exposure
+note. For **SSH**, skip frames entirely — `analyze` points you at the transcript,
+which is the full input+output and far cheaper. This is the intended path for
+"show me / summarize the session from today".
+
 **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.
 - `Status` codes confirmed live: **0 = Not started, 1 = Active, 2 = Completed, 5 = Locked, 7 = Terminated** (3/9 are other terminal states). `--active` filters on Status == 1.

bt_cli-0.4.68/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.65 → bt_cli-0.4.68}/src/bt_cli/pws/commands/sessions.py

@@ -5,12 +5,13 @@ import json
 import shutil
 import subprocess
 import time
-from datetime import datetime, timezone
+from datetime import date, datetime, timezone
 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
@@ -34,6 +35,41 @@ SESSION_STATUS = {
 }
 
 
+def _norm_date(value: str) -> str:
+    """Validate a YYYY-MM-DD (or ISO) date arg and return its date portion."""
+    try:
+        datetime.strptime(value.strip()[:10], "%Y-%m-%d")
+    except (ValueError, AttributeError):
+        print_error(f"Invalid date '{value}'. Use YYYY-MM-DD.")
+        raise typer.Exit(2)
+    return value.strip()[:10]
+
+
+def _resolve_date_window(today: bool, on: str, since: str, until: str) -> tuple:
+    """Collapse the date flags into an inclusive (lo, hi) date window (YYYY-MM-DD
+    strings, either may be None). --today/--on pin both ends to one day."""
+    if today:
+        d = date.today().isoformat()
+        return d, d
+    if on:
+        d = _norm_date(on)
+        return d, d
+    return (_norm_date(since) if since else None, _norm_date(until) if until else None)
+
+
+def _started_in_window(s: dict, lo: str, hi: str) -> bool:
+    """True if the session's StartTime date falls within [lo, hi] (ISO date
+    strings sort lexicographically, so string compare on the date is correct)."""
+    d = (s.get("StartTime") or "")[:10]
+    if not d:
+        return False
+    if lo and d < lo:
+        return False
+    if hi and d > hi:
+        return False
+    return True
+
+
 def is_active(s: dict) -> bool:
     """A session is live (suspend/terminate-able) when Status == 1.
 
@@ -98,6 +134,10 @@ def list_sessions(
     system: int = typer.Option(None, "--system", help="Filter by managed system ID"),
     active: bool = typer.Option(False, "--active", help="Show only active (started, not ended) sessions"),
     status: str = typer.Option(None, "--status", "-s", help="Filter by raw numeric status code"),
+    today: bool = typer.Option(False, "--today", help="Only sessions that started today"),
+    on: str = typer.Option(None, "--on", help="Only sessions that started on this date (YYYY-MM-DD)"),
+    since: str = typer.Option(None, "--since", help="Only sessions on/after this date (YYYY-MM-DD)"),
+    until: str = typer.Option(None, "--until", help="Only sessions on/before this date (YYYY-MM-DD)"),
     limit: int = typer.Option(25, "--limit", "-l", help="Max rows to show (most recent first)"),
     fetch_all: bool = typer.Option(False, "--all", help="Show all sessions (the endpoint returns full history)"),
     output: str = typer.Option("table", "--output", "-o", help="Output format: table or json"),
@@ -109,11 +149,17 @@ def list_sessions(
     suspend/terminate), or --all to see everything. Output is newest-first and
     capped at --limit by default.
 
+    Date filters (--today/--on/--since/--until) match on StartTime's date and are
+    applied client-side (the endpoint returns the full history every call).
+
     Examples:
         bt pws sessions list --active
+        bt pws sessions list --today
+        bt pws sessions list --since 2026-06-01 --until 2026-06-30
         bt pws sessions list --system 13
         bt pws sessions list --all -o json
     """
+    lo, hi = _resolve_date_window(today, on, since, until)
     try:
         with get_client() as client:
             client.authenticate()
@@ -121,6 +167,8 @@ def list_sessions(
 
         if active:
             sessions = [s for s in sessions if is_active(s)]
+        if lo or hi:
+            sessions = [s for s in sessions if _started_in_window(s, lo, hi)]
 
         total = len(sessions)
         shown = sessions if fetch_all else sessions[:limit]
@@ -586,6 +634,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"),

{bt_cli-0.4.65 → bt_cli-0.4.68}/tests/pws/test_commands.py

@@ -488,6 +488,63 @@ class TestPWSSessionsReplay:
         assert offsets[0] == 0
         assert offsets[-1] >= 2400
 
+    @staticmethod
+    def _write_dump(tmp_path, protocol, sizes):
+        """Create a fake replay folder: index.json + PNG frames of given byte sizes."""
+        folder = tmp_path / "dump"
+        folder.mkdir()
+        frames = []
+        for i, size in enumerate(sizes):
+            hdr = b"\x89PNG\r\n\x1a\n" + b"\x00\x00\x00\x0dIHDR" + (1024).to_bytes(4, "big") + (768).to_bytes(4, "big")
+            (folder / f"frame_{i:04d}.png").write_bytes(hdr + b"\x00" * max(0, size - len(hdr)))
+            frames.append({"file": f"frame_{i:04d}.png", "offset_ms": i * 1000})
+        (folder / "index.json").write_text(json.dumps(
+            {"session_id": 77, "protocol": protocol, "frames": frames, "frame_count": len(frames)}
+        ))
+        return folder
+
+    def _mock_session_meta(self, keystrokes=None):
+        mock_auth_endpoints()
+        respx.get("https://mock-pws.example.com/api/v3/Sessions/77").mock(
+            return_value=httpx.Response(200, json={"SessionID": 77, "AssetName": "win", "ManagedAccountName": "admin"})
+        )
+        respx.get("https://mock-pws.example.com/api/v3/Sessions/77/Keystrokes").mock(
+            return_value=httpx.Response(200, json=keystrokes or [])
+        )
+
+    @respx.mock
+    def test_analyze_rdp_selects_keyframes(self, runner, mock_pws_config, tmp_path):
+        """RDP analyze picks keyframes on size change and writes analysis.json + cost."""
+        folder = self._write_dump(tmp_path, "RDP", sizes=[1000, 1000, 2000, 2000, 1000])
+        self._mock_session_meta()
+        with patch("bt_cli.pws.client.base.load_pws_config", return_value=mock_pws_config):
+            result = runner.invoke(app, ["pws", "sessions", "analyze", "--dir", str(folder), "-o", "json"])
+
+        assert result.exit_code == 0, result.output
+        manifest = json.loads(result.output[result.output.index("{"):])
+        # keyframes: first(0), the jump to 2000(idx2), and last(idx4) -> 3
+        assert manifest["keyframe_count"] == 3
+        assert manifest["frame_count"] == 5
+        assert manifest["cost_estimate"]["focused"]["images"] == 3
+        assert manifest["cost_estimate"]["all_frames"]["images"] == 5
+        assert (folder / "analysis.json").exists()
+
+    @respx.mock
+    def test_analyze_ssh_recommends_transcript(self, runner, mock_pws_config, tmp_path):
+        """SSH analyze recommends the transcript and selects no keyframes."""
+        folder = self._write_dump(tmp_path, "SSH", sizes=[1000, 1000])
+        self._mock_session_meta(keystrokes=[
+            {"KeystrokeID": 1, "TimeMarker": 1782999904000, "Type": 1, "Data": "id"},
+        ])
+        with patch("bt_cli.pws.client.base.load_pws_config", return_value=mock_pws_config):
+            result = runner.invoke(app, ["pws", "sessions", "analyze", "--dir", str(folder), "-o", "json"])
+
+        assert result.exit_code == 0, result.output
+        manifest = json.loads(result.output[result.output.index("{"):])
+        assert manifest["recommended_input"] == "transcript"
+        assert manifest["keyframe_count"] == 0
+        assert manifest["keystroke_count"] == 1
+
     @respx.mock
     def test_replay_no_recording(self, runner, mock_pws_config):
         """A session without a recording (no Token/RecordKey) exits 1."""