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

{bt_cli-0.4.65 → 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.65**
+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>`. **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.67}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bt-cli
-Version: 0.4.65
+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.65 → bt_cli-0.4.67}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bt-cli"
-version = "0.4.65"
+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.65 → bt_cli-0.4.67}/src/bt_cli/__init__.py

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

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

@@ -11,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
@@ -586,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"),

{bt_cli-0.4.65 → bt_cli-0.4.67}/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."""