Add docs for session system

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)
+1. [CLI Startup Flags](#cli-startup-flags)
-2. [Queue System](#queue-system)
+2. [Parallel Execution](#parallel-execution)
-3. [Automation & Scripting](#automation--scripting)
+3. [Queue System](#queue-system)
-4. [Memory Management](#memory-management)
+4. [Automation & Scripting](#automation--scripting)
-5. [Workspace & Virtualization](#workspace--virtualization)
+5. [Memory Management](#memory-management)
-6. [CTF Workflows](#ctf-workflows)
+6. [Workspace & Virtualization](#workspace--virtualization)
-7. [Cost Management](#cost-management)
+7. [CTF Workflows](#ctf-workflows)
-8. [Configuration Management](#configuration-management)
+8. [Cost Management](#cost-management)
-9. [Integration Patterns](#integration-patterns)
+9. [Configuration Management](#configuration-management)
-10. [Troubleshooting](#troubleshooting)
+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).
 
 ---
 

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.

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.

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