From 229e8118e62bbec1e62f0b1d309d5104a9aae2c9 Mon Sep 17 00:00:00 2001
From: luijait <60628803+luijait@users.noreply.github.com>
Date: Tue, 13 Jan 2026 08:53:24 +0100
Subject: [PATCH] Add docs for session system (#398)

---
 docs/cli/advanced_usage.md | 108 +++++++++--
 docs/continue_mode.md      |  23 +++
 docs/session_resume.md     | 355 +++++++++++++++++++++++++++++++++++++
 mkdocs.yml                 |   1 +
 4 files changed, 477 insertions(+), 10 deletions(-)
 create mode 100644 docs/session_resume.md

diff --git a/docs/cli/advanced_usage.md b/docs/cli/advanced_usage.md
index aa515520..4072c59c 100644
--- a/docs/cli/advanced_usage.md
+++ b/docs/cli/advanced_usage.md
@@ -6,16 +6,104 @@ This guide covers advanced features, automation, scripting, and power-user techn
 
 ## Table of Contents
 
-1. [Parallel Execution](#parallel-execution)
-2. [Queue System](#queue-system)
-3. [Automation & Scripting](#automation--scripting)
-4. [Memory Management](#memory-management)
-5. [Workspace & Virtualization](#workspace--virtualization)
-6. [CTF Workflows](#ctf-workflows)
-7. [Cost Management](#cost-management)
-8. [Configuration Management](#configuration-management)
-9. [Integration Patterns](#integration-patterns)
-10. [Troubleshooting](#troubleshooting)
+1. [CLI Startup Flags](#cli-startup-flags)
+2. [Parallel Execution](#parallel-execution)
+3. [Queue System](#queue-system)
+4. [Automation & Scripting](#automation--scripting)
+5. [Memory Management](#memory-management)
+6. [Workspace & Virtualization](#workspace--virtualization)
+7. [CTF Workflows](#ctf-workflows)
+8. [Cost Management](#cost-management)
+9. [Configuration Management](#configuration-management)
+10. [Integration Patterns](#integration-patterns)
+11. [Troubleshooting](#troubleshooting)
+
+---
+
+## CLI Startup Flags
+
+CAI provides powerful command-line flags for session management and autonomous operation.
+
+### Session Resume Flags
+
+Resume previous sessions to continue where you left off:
+
+```bash
+# Resume the last session
+cai --resume
+
+# Resume with interactive session selector
+cai --resume list
+
+# Resume a specific session by ID
+cai --resume abc12345
+
+# Resume from a specific log file
+cai --resume /path/to/session.jsonl
+
+# Resume from custom logs directory
+cai --resume list --logpath ~/custom_logs/
+```
+
+### Continue Mode Flag
+
+Enable autonomous operation where the agent continues working without waiting for user input:
+
+```bash
+# Start with continue mode
+cai --continue --prompt "perform security audit"
+
+# Short form
+cai -c --prompt "analyze vulnerabilities"
+```
+
+### Combining Resume and Continue
+
+The most powerful combination - resume a session AND continue autonomously:
+
+```bash
+# Resume last session and continue working
+cai --resume --continue
+
+# Resume specific session and continue
+cai --resume abc12345 --continue
+
+# Short form
+cai --resume -c
+```
+
+This is ideal for:
+- Resuming interrupted long-running tasks
+- Continuing security audits after a break
+- Picking up penetration tests where you left off
+
+### Other Useful Flags
+
+```bash
+# Start with initial prompt
+cai --prompt "your task here"
+cai -p "your task here"
+
+# Use specific agent type
+cai --agent redteam_agent
+cai -a bug_bounter_agent
+
+# Use specific model
+cai --model alias1
+cai -m gpt-4o
+
+# Load YAML configuration
+cai --yaml config.yaml
+
+# Check version
+cai --version
+
+# Update CAI
+cai --update
+```
+
+For detailed documentation on session resume, see [Session Resume](../session_resume.md).
+For continue mode details, see [Continue Mode](../continue_mode.md).
 
 ---
 
diff --git a/docs/continue_mode.md b/docs/continue_mode.md
index 36493359..4b3d7e2e 100644
--- a/docs/continue_mode.md
+++ b/docs/continue_mode.md
@@ -321,12 +321,35 @@ These examples demonstrate:
 - Graceful interruption with Ctrl+C
 - Practical security use cases
 
+## Combining with Session Resume
+
+The `--continue` flag works seamlessly with `--resume` to continue interrupted sessions autonomously:
+
+```bash
+# Resume last session and continue working autonomously
+cai --resume --continue
+
+# Resume specific session and continue
+cai --resume abc12345 --continue
+
+# Resume from interactive selector and continue
+cai --resume list --continue
+```
+
+This powerful combination:
+1. **Restores your previous session** with full conversation history
+2. **Automatically generates a continuation prompt** based on where you left off
+3. **Continues working autonomously** without waiting for user input
+
+For more details on session resume capabilities, see the [Session Resume](session_resume.md) documentation.
+
 ## Summary
 
 The `--continue` flag transforms CAI into an autonomous cybersecurity assistant capable of:
 - Working independently on complex tasks
 - Recovering from errors intelligently
 - Maintaining context across multiple operations
+- Resuming and continuing interrupted sessions with `--resume --continue`
 - Providing entertainment with continuous jokes
 
 Whether you're conducting security audits, hunting for bugs, or just want some cybersecurity humor, continue mode keeps your agent working until the job is done.
\ No newline at end of file
diff --git a/docs/session_resume.md b/docs/session_resume.md
new file mode 100644
index 00000000..c7c3948e
--- /dev/null
+++ b/docs/session_resume.md
@@ -0,0 +1,355 @@
+# Session Resume
+
+## Overview
+
+CAI provides powerful session resume capabilities that allow you to continue where you left off. Whether you were in the middle of a security audit, bug bounty session, or complex analysis, you can seamlessly restore your conversation history and pick up exactly where you stopped.
+
+The session resume system automatically saves all your interactions to JSONL log files and provides multiple ways to restore them:
+
+- **`--resume`**: Resume from specific session or interactive selector
+- **`--resume --continue`**: Resume AND continue autonomously
+- **Interactive Selector**: Visual session browser with pagination
+
+## Quick Start
+
+```bash
+# Resume the last session
+cai --resume
+
+# Resume the last session and continue autonomously
+cai --resume --continue
+
+# Interactive session selector
+cai --resume list
+
+# Resume a specific session by ID
+cai --resume abc12345
+
+# Resume from a specific log file
+cai --resume /path/to/session.jsonl
+```
+
+## Session Resume Options
+
+### Resume Last Session
+
+```bash
+cai --resume
+# or
+cai --resume last
+```
+
+This automatically finds and loads the most recent session that contains messages. Empty sessions are skipped.
+
+### Interactive Session Selector
+
+```bash
+cai --resume list
+```
+
+Opens an interactive menu with:
+
+- **Arrow key navigation** (`↑`/`↓` or `j`/`k`)
+- **Page navigation** (`←`/`→` or `h`/`l`)
+- **Session preview** showing last assistant response
+- **Cost and token tracking** per session
+- **Model information** for each session
+
+```
+╭──────────────────────────────────────────────────────────────────────────────╮
+│  ↻ Select a session to resume                                                │
+│  ↑/↓/j/k navigate  │  ←/→/h/l pages  │  Enter select  │  q/Esc cancel       │
+╰──────────────────────────────────────────────────────────────────────────────╯
+
+   Page 1+ │ 10 sessions │ → next
+
+   ID       │ Date       │ Model        │ Msgs    │ Cost
+   ─────────┼────────────┼──────────────┼─────────┼────────
+ ❯ abc12345 │ 01-12 15:30 │ claude-sonnet │  42 msgs │   $2.35 ★ LATEST
+   def67890 │ 01-12 14:15 │ gpt-4         │  28 msgs │   $1.80
+   ghi11223 │ 01-11 20:00 │ claude-opus   │ 156 msgs │  $12.50
+
+   ──────────────────────────────────────────────────────────────────
+   Preview:
+   The vulnerability analysis is complete. I found 3 critical issues:
+   1. SQL injection in user.py line 45...
+```
+
+### Resume with Continue Mode
+
+```bash
+cai --resume --continue
+# or
+cai --resume -c
+```
+
+This powerful combination:
+1. **Restores your previous session** with full conversation history
+2. **Automatically generates a continuation prompt** based on context
+3. **Continues working autonomously** without waiting for user input
+
+Perfect for:
+- Resuming long-running security audits
+- Continuing interrupted penetration tests
+- Picking up complex analysis tasks
+
+### Resume Specific Session
+
+```bash
+# By session ID (first 8 characters)
+cai --resume abc12345
+
+# By full log file path
+cai --resume logs/cai_20240112_153045.jsonl
+
+# From custom logs directory
+cai --resume my_session --logpath ~/custom_logs/
+```
+
+## What Gets Restored
+
+When you resume a session, CAI restores:
+
+| Component | Description |
+|-----------|-------------|
+| **Message History** | All user messages and agent responses |
+| **Tool Calls** | Complete record of tools used and their outputs |
+| **Agent Context** | The agent's understanding of the task |
+| **Session Statistics** | Total cost, tokens used, active time |
+| **Parallel Agent Config** | Multi-agent configurations (if applicable) |
+
+### Session Statistics Display
+
+```
+↻ Resuming session
+claude-sonnet │ Tokens: 45,230in/12,450out │ $3.45 │ 25.3s active
+
+[Session content displayed here...]
+
+Session restored. Continue where you left off.
+Restored session stats: $3.4500, 45230in/12450out tokens
+Loaded 156 messages into agent history
+```
+
+## Custom Logs Directory
+
+Use `--logpath` to work with sessions stored in custom directories:
+
+```bash
+# Resume from custom directory
+cai --resume list --logpath ~/projects/security_audits/logs/
+
+# Resume last session from custom directory
+cai --resume --logpath /shared/team_sessions/
+```
+
+The `--logpath` option:
+- Recursively searches all subdirectories for `.jsonl` files
+- Works with both `--resume list` and `--resume last`
+- Supports absolute and relative paths
+
+## Parallel Agent Sessions
+
+When resuming a session that used multiple parallel agents, CAI automatically detects and offers to restore the parallel configuration:
+
+```
+The session used 3 parallel agents:
+  - CTF agent
+  - Code Analyzer agent
+  - Security Researcher agent
+
+Set up the same parallel agent configuration? (y/n):
+```
+
+If you choose yes, the parallel agent configuration is restored and you can continue working with the same multi-agent setup.
+
+## Session Log Format
+
+Sessions are stored as JSONL (JSON Lines) files in the `logs/` directory:
+
+```
+logs/
+├── last -> cai_20240112_153045.jsonl  # Symlink to most recent
+├── cai_20240112_153045.jsonl
+├── cai_20240112_140000.jsonl
+└── cai_20240111_200000.jsonl
+```
+
+Each log file contains:
+- Session metadata (ID, timestamps, model info)
+- Complete message history
+- Tool calls and responses
+- Token usage and cost tracking
+- Timing metrics (active/idle time)
+
+## Environment Variables
+
+```bash
+# Custom default logs directory
+export CAI_LOGS_DIR=~/my_logs
+
+# Enable debug output for resume operations
+export CAI_DEBUG=2
+```
+
+## Programmatic Usage
+
+### Python API
+
+```python
+from cai.repl.session_resume import (
+    resume_session,
+    find_last_session_log,
+    interactive_session_selector,
+    load_session_into_agent
+)
+
+# Find and display session
+log_path = find_last_session_log()
+messages, used_path, parallel_agents = resume_session(log_path)
+
+# Load into agent
+from cai.agents import get_agent_by_name
+agent = get_agent_by_name("ctf_agent")
+load_session_into_agent(agent, messages, log_path=used_path)
+```
+
+### List Recent Sessions
+
+```python
+from cai.repl.session_resume import list_recent_sessions
+
+sessions = list_recent_sessions(limit=10)
+for session in sessions:
+    print(f"{session['session_id'][:8]} - {session['model']} - ${session['total_cost']:.2f}")
+```
+
+## Best Practices
+
+### 1. Regular Session Checkpoints
+
+For long-running tasks, the session is automatically saved after each interaction. You can safely interrupt with `Ctrl+C` and resume later.
+
+### 2. Descriptive Initial Prompts
+
+When starting a session you plan to resume later, use descriptive prompts that provide context:
+
+```bash
+# Good - Clear context for resumption
+cai --prompt "Security audit of user authentication in project X, focusing on SQL injection and XSS"
+
+# Less helpful for resumption
+cai --prompt "check auth"
+```
+
+### 3. Use Resume + Continue for Autonomous Work
+
+```bash
+# Start a long task
+cai --continue --prompt "comprehensive security audit of the entire codebase"
+
+# Later, resume and let it continue working
+cai --resume --continue
+```
+
+### 4. Organize Sessions with Custom Paths
+
+```bash
+# Keep different projects separate
+cai --prompt "audit project A" --logpath ~/logs/project_a/
+cai --prompt "audit project B" --logpath ~/logs/project_b/
+
+# Resume specific project
+cai --resume --logpath ~/logs/project_a/
+```
+
+## Troubleshooting
+
+### Issue: "No previous session found"
+
+**Cause**: No valid session logs exist in the logs directory.
+
+**Solutions**:
+- Check the `logs/` directory exists and contains `.jsonl` files
+- Use `--logpath` to specify a custom directory
+- Ensure previous sessions completed at least one interaction
+
+### Issue: Session loads but context seems lost
+
+**Cause**: The model's context window may be exceeded.
+
+**Solutions**:
+- Resume with a model that has a larger context window
+- The session will work but older messages may be truncated by the model
+
+### Issue: Parallel agents not detected
+
+**Cause**: The original session may not have used the parallel agent format.
+
+**Solutions**:
+- Manually configure parallel agents with `/parallel` command after resuming
+- Check that the original session used proper parallel agent configuration
+
+### Issue: Cost tracking shows $0.00 after resume
+
+**Cause**: Session stats couldn't be restored from the log file.
+
+**Solutions**:
+- This is cosmetic; the actual costs are still in the log file
+- Check log file format is valid JSONL
+
+## Technical Details
+
+### Session Resume Flow
+
+```mermaid
+graph TD
+    A[cai --resume] --> B{Resume type?}
+    B -->|last| C[Find last session log]
+    B -->|list| D[Interactive selector]
+    B -->|path/id| E[Find specific session]
+
+    C --> F[Load messages from JSONL]
+    D --> F
+    E --> F
+
+    F --> G[Display session content]
+    G --> H[Restore session stats]
+    H --> I[Load into agent history]
+
+    I --> J{--continue flag?}
+    J -->|Yes| K[Generate continuation prompt]
+    J -->|No| L[Wait for user input]
+
+    K --> M[Auto-continue working]
+```
+
+### Core Components
+
+| File | Purpose |
+|------|---------|
+| `src/cai/repl/session_resume.py` | Main resume functionality |
+| `src/cai/sdk/agents/run_to_jsonl.py` | JSONL parsing and token stats |
+| `src/cai/cli.py` | CLI integration and `--resume` handling |
+
+### Log File Structure
+
+```json
+{"event": "session_start", "session_id": "abc12345", "timestamp": "2024-01-12T15:30:45Z"}
+{"object": "chat.completion", "model": "claude-sonnet", "messages": [...], "agent_name": "CTF agent"}
+{"event": "tool_call", "name": "generic_linux_command", "arguments": {...}}
+{"event": "session_end", "cost": {"total_cost": 3.45}, "timing_metrics": {...}}
+```
+
+## Summary
+
+Session resume in CAI provides:
+
+- **Seamless continuation** of interrupted work
+- **Full context restoration** including tools and agent state
+- **Interactive session browsing** with preview and filtering
+- **Autonomous resumption** with `--resume --continue`
+- **Multi-agent support** for parallel session restoration
+- **Flexible log management** with custom directories
+
+Whether you're conducting security audits, running penetration tests, or performing complex analysis, session resume ensures you never lose your progress.
diff --git a/mkdocs.yml b/mkdocs.yml
index 7c73c78d..22cbd872 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -105,6 +105,7 @@ nav:
   - Guides:
       - Running Agents: running_agents.md
       - Continue Mode: continue_mode.md
+      - Session Resume: session_resume.md
       - Working with Results: results.md
       - Streaming: streaming.md
       - Tracing & Debugging: tracing.md