5518a96f53
- Add context-discovery.md with dynamic context loading and manifest indexing - Add session-management.md with lazy initialization and cleanup policies - Implement keyword search and delegation patterns for context files - Define session isolation and error handling strategies
144 lines
3.9 KiB
Markdown
144 lines
3.9 KiB
Markdown
# Session Management
|
|
|
|
## Lazy Initialization
|
|
|
|
**Only create session when first context file needed**
|
|
|
|
- Don't create sessions for simple questions or direct execution
|
|
- Initialize on first delegation that requires context file
|
|
- Session ID format: `{timestamp}-{random-4-chars}`
|
|
- Example: `20250118-143022-a4f2`
|
|
|
|
## Session Structure
|
|
|
|
```
|
|
.tmp/sessions/{session-id}/
|
|
├── .manifest.json
|
|
├── features/
|
|
│ └── {task-name}-context.md
|
|
├── documentation/
|
|
│ └── {task-name}-context.md
|
|
├── code/
|
|
│ └── {task-name}-context.md
|
|
├── tasks/
|
|
│ └── {task-name}-tasks.md
|
|
└── general/
|
|
└── {task-name}-context.md
|
|
```
|
|
|
|
## Session Isolation
|
|
|
|
**Each session has unique ID - prevents concurrent agent conflicts**
|
|
|
|
✅ Multiple agent instances can run simultaneously
|
|
✅ No file conflicts between sessions
|
|
✅ Each session tracks only its own files
|
|
✅ Safe cleanup - only deletes own session folder
|
|
|
|
## Manifest Structure
|
|
|
|
**Location**: `.tmp/sessions/{session-id}/.manifest.json`
|
|
|
|
```json
|
|
{
|
|
"session_id": "20250118-143022-a4f2",
|
|
"created_at": "2025-01-18T14:30:22Z",
|
|
"last_activity": "2025-01-18T14:35:10Z",
|
|
"context_files": {
|
|
"features/user-auth-context.md": {
|
|
"created": "2025-01-18T14:30:22Z",
|
|
"for": "@subagents/core/task-manager",
|
|
"keywords": ["user-auth", "authentication", "features"]
|
|
},
|
|
"tasks/user-auth-tasks.md": {
|
|
"created": "2025-01-18T14:32:15Z",
|
|
"for": "@subagents/core/task-manager",
|
|
"keywords": ["user-auth", "tasks", "breakdown"]
|
|
}
|
|
},
|
|
"context_index": {
|
|
"user-auth": [
|
|
"features/user-auth-context.md",
|
|
"tasks/user-auth-tasks.md"
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
## Activity Tracking
|
|
|
|
**Update timestamp after each context file creation or delegation**
|
|
|
|
- Update `last_activity` field in manifest
|
|
- Used for stale session detection
|
|
- Helps identify active vs abandoned sessions
|
|
|
|
## Cleanup Policy
|
|
|
|
### Manual Cleanup (Preferred)
|
|
**Ask user confirmation before cleanup**
|
|
|
|
After task completion:
|
|
1. Ask: "Should I clean up temporary session files at `.tmp/sessions/{session-id}/`?"
|
|
2. Wait for user confirmation
|
|
3. Only delete files tracked in current session's manifest
|
|
4. Remove entire session folder: `.tmp/sessions/{session-id}/`
|
|
|
|
### Safety Rules
|
|
- **NEVER** delete files outside current session
|
|
- **ONLY** delete files tracked in manifest
|
|
- **ALWAYS** confirm with user before cleanup
|
|
|
|
### Stale Session Cleanup
|
|
**Auto-remove sessions >24 hours old**
|
|
|
|
- Check `last_activity` timestamp in manifest
|
|
- Safe to run periodically (see `scripts/cleanup-stale-sessions.sh`)
|
|
- Won't affect active sessions
|
|
|
|
## Error Handling
|
|
|
|
### Subagent Failure
|
|
- Report error to user
|
|
- Ask if should retry or abort
|
|
- Don't auto-retry without approval
|
|
|
|
### Context File Error
|
|
- Fall back to inline context in delegation prompt
|
|
- Warn user that context file creation failed
|
|
- Continue with task if possible
|
|
|
|
### Session Creation Error
|
|
- Continue without session
|
|
- Warn user
|
|
- Use inline context for delegation
|
|
- Don't block task execution
|
|
|
|
## Best Practices
|
|
|
|
1. **Lazy Init**: Only create session when actually needed
|
|
2. **Track Everything**: Add all context files to manifest
|
|
3. **Update Activity**: Touch `last_activity` on each operation
|
|
4. **Clean Promptly**: Remove files after task completion
|
|
5. **Isolate Sessions**: Never access files from other sessions
|
|
6. **Confirm Cleanup**: Always ask user before deleting
|
|
|
|
## Example Workflow
|
|
|
|
```bash
|
|
# User: "Build user authentication system"
|
|
# → Complex task, needs context file
|
|
# → Create session: 20250118-143022-a4f2
|
|
# → Create: .tmp/sessions/20250118-143022-a4f2/features/user-auth-context.md
|
|
# → Delegate to @task-manager
|
|
|
|
# User: "Implement login component"
|
|
# → Same session, add context
|
|
# → Create: .tmp/sessions/20250118-143022-a4f2/code/login-context.md
|
|
# → Delegate to @coder-agent
|
|
|
|
# Task complete
|
|
# → Ask: "Clean up session files?"
|
|
# → User confirms
|
|
# → Delete: .tmp/sessions/20250118-143022-a4f2/
|
|
```
|