mirror of https://github.com/aliasrobotics/cai.git
Add docs for session system (#398)
This commit is contained in:
luijait
GitHub
parent
559de8fcbc
commit
229e8118e6
|
|
@ -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).
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue