diff options
Diffstat (limited to 'makima/docs/SPEC-resume-history-system.md')
| -rw-r--r-- | makima/docs/SPEC-resume-history-system.md | 1000 |
1 files changed, 1000 insertions, 0 deletions
diff --git a/makima/docs/SPEC-resume-history-system.md b/makima/docs/SPEC-resume-history-system.md new file mode 100644 index 0000000..7a19a90 --- /dev/null +++ b/makima/docs/SPEC-resume-history-system.md @@ -0,0 +1,1000 @@ +# Resume and History System Specification + +## Overview + +This specification defines a comprehensive system for viewing historical conversation data, resuming interrupted work, and rewinding/restoring to previous states in the Makima platform. The system integrates with the existing contract, task, supervisor, and checkpoint infrastructure. + +## Table of Contents + +1. [Current Infrastructure](#1-current-infrastructure) +2. [History Viewing Features](#2-history-viewing-features) +3. [Resume System](#3-resume-system) +4. [Rewind/Restore Features](#4-rewindrestore-features) +5. [Integration Points](#5-integration-points) +6. [Implementation Plan](#6-implementation-plan) + +--- + +## 1. Current Infrastructure + +### 1.1 Existing Database Tables + +The system builds upon these existing tables: + +#### `supervisor_states` +```sql +- id: UUID +- contract_id: UUID +- task_id: UUID +- conversation_history: JSONB -- Full Claude conversation history +- last_checkpoint_id: UUID +- pending_task_ids: UUID[] +- phase: VARCHAR +- last_activity: TIMESTAMP +- created_at: TIMESTAMP +- updated_at: TIMESTAMP +``` + +#### `task_checkpoints` +```sql +- id: UUID +- task_id: UUID +- checkpoint_number: INT +- commit_sha: VARCHAR +- branch_name: VARCHAR +- message: VARCHAR +- files_changed: JSONB -- [{path, action: 'A'|'M'|'D'}] +- lines_added: INT +- lines_removed: INT +- created_at: TIMESTAMP +``` + +#### `task_events` +```sql +- id: UUID +- task_id: UUID +- event_type: VARCHAR -- 'output', 'status_change', etc. +- previous_status: VARCHAR +- new_status: VARCHAR +- event_data: JSONB -- Contains full output data +- created_at: TIMESTAMP +``` + +#### `tasks` (relevant fields) +```sql +- conversation_state: JSONB -- Saved conversation context +- continue_from_task_id: UUID -- For worktree inheritance +- last_checkpoint_sha: VARCHAR +- checkpoint_count: INT +- checkpoint_message: VARCHAR +``` + +#### `mesh_chat_conversations` / `mesh_chat_messages` +```sql +-- Conversations for mesh chat +- id, owner_id, name, is_active, created_at, updated_at + +-- Messages +- id, conversation_id, role, content, context_type, context_task_id +- tool_calls: JSONB, pending_questions: JSONB, created_at +``` + +#### `contract_chat_conversations` / `contract_chat_messages` +```sql +-- Similar structure to mesh chat, scoped to contracts +``` + +### 1.2 Existing Repository Functions + +```rust +// Checkpoint functions +- list_task_checkpoints(pool, task_id) -> Vec<TaskCheckpoint> +- get_task_checkpoint(pool, id) -> Option<TaskCheckpoint> +- get_task_checkpoint_by_sha(pool, commit_sha) -> Option<TaskCheckpoint> + +// Supervisor state functions +- upsert_supervisor_state(pool, contract_id, task_id, conversation_history, pending_task_ids, phase) +- get_supervisor_state(pool, contract_id) -> Option<SupervisorState> +- get_supervisor_state_by_task(pool, task_id) -> Option<SupervisorState> +- update_supervisor_conversation(pool, contract_id, conversation_history) +- update_supervisor_pending_tasks(pool, contract_id, pending_task_ids) + +// Task output functions +- get_task_output(pool, task_id, limit) -> Vec<TaskEvent> +- list_task_events(pool, task_id, limit) -> Vec<TaskEvent> +``` + +### 1.3 Existing API Endpoints + +``` +GET /api/v1/mesh/tasks/{id}/output -- Task output history +GET /api/v1/mesh/tasks/{id}/events -- Task events +GET /api/v1/mesh/tasks/{id}/checkpoints -- List checkpoints +POST /api/v1/mesh/tasks/{id}/continue -- Continue interrupted task +POST /api/v1/mesh/tasks/{id}/reassign -- Reassign to new daemon +``` + +--- + +## 2. History Viewing Features + +### 2.1 Contract History Timeline + +View all activities across a contract's lifecycle, aggregating data from all phases and tasks. + +#### API Endpoint + +``` +GET /api/v1/contracts/{contract_id}/history +``` + +#### Query Parameters + +| Parameter | Type | Description | +|-----------|------|-------------| +| `phase` | string | Filter by phase (research, specify, plan, execute, review) | +| `event_types` | string[] | Filter by event types (task_created, task_completed, checkpoint, phase_change, chat) | +| `from` | datetime | Start of time range | +| `to` | datetime | End of time range | +| `limit` | int | Max results (default: 100) | +| `cursor` | string | Pagination cursor | + +#### Response Schema + +```typescript +interface ContractHistoryResponse { + contractId: string; + entries: HistoryEntry[]; + totalCount: number; + cursor?: string; +} + +interface HistoryEntry { + id: string; + timestamp: datetime; + entryType: 'task_event' | 'chat_message' | 'phase_change' | 'checkpoint' | 'file_change'; + phase: string; + + // Task event data (when entryType = 'task_event') + taskId?: string; + taskName?: string; + eventType?: string; + eventData?: any; + + // Chat message data (when entryType = 'chat_message') + conversationId?: string; + role?: string; + content?: string; + + // Checkpoint data (when entryType = 'checkpoint') + checkpointNumber?: number; + commitSha?: string; + message?: string; + filesChanged?: FileChange[]; + + // Phase change data (when entryType = 'phase_change') + previousPhase?: string; + newPhase?: string; +} +``` + +### 2.2 Task Conversation History + +View the complete conversation history for a specific task. + +#### API Endpoint + +``` +GET /api/v1/mesh/tasks/{task_id}/conversation +``` + +#### Query Parameters + +| Parameter | Type | Description | +|-----------|------|-------------| +| `include_tool_calls` | bool | Include tool call details (default: true) | +| `include_tool_results` | bool | Include tool results (default: true) | +| `limit` | int | Max messages (default: all) | + +#### Response Schema + +```typescript +interface TaskConversationResponse { + taskId: string; + taskName: string; + status: string; + messages: ConversationMessage[]; + totalTokens?: number; + totalCost?: number; +} + +interface ConversationMessage { + id: string; + role: 'user' | 'assistant' | 'system' | 'tool'; + content: string; + timestamp: datetime; + + // For assistant messages + toolCalls?: ToolCall[]; + + // For tool messages + toolName?: string; + toolInput?: any; + toolResult?: string; + isError?: boolean; + + // Cost tracking + tokenCount?: number; + costUsd?: number; +} +``` + +### 2.3 Supervisor Conversation History + +View the full conversation history for a contract's supervisor. + +#### API Endpoint + +``` +GET /api/v1/contracts/{contract_id}/supervisor/conversation +``` + +#### Response Schema + +```typescript +interface SupervisorConversationResponse { + contractId: string; + supervisorTaskId: string; + phase: string; + lastActivity: datetime; + pendingTaskIds: string[]; + + // Full conversation from supervisor_states.conversation_history + messages: ConversationMessage[]; + + // Tasks spawned during conversation + spawnedTasks: TaskReference[]; +} + +interface TaskReference { + taskId: string; + taskName: string; + status: string; + createdAt: datetime; + completedAt?: datetime; +} +``` + +### 2.4 Checkpoint History with Diffs + +View checkpoint history with Git diff information. + +#### API Endpoint + +``` +GET /api/v1/mesh/tasks/{task_id}/checkpoints/{checkpoint_id}/diff +``` + +#### Response Schema + +```typescript +interface CheckpointDiffResponse { + checkpoint: TaskCheckpoint; + diff: GitDiff; + previousCheckpoint?: TaskCheckpoint; +} + +interface GitDiff { + files: FileDiff[]; + stats: { + filesChanged: number; + insertions: number; + deletions: number; + }; +} + +interface FileDiff { + path: string; + action: 'added' | 'modified' | 'deleted'; + additions: number; + deletions: number; + hunks: DiffHunk[]; +} +``` + +### 2.5 Activity Timeline View + +Unified timeline showing all activities for a contract or task. + +#### API Endpoint + +``` +GET /api/v1/timeline +``` + +#### Query Parameters + +| Parameter | Type | Description | +|-----------|------|-------------| +| `contract_id` | UUID | Filter by contract | +| `task_id` | UUID | Filter by specific task | +| `include_subtasks` | bool | Include subtask activities | +| `from` | datetime | Start of time range | +| `to` | datetime | End of time range | + +--- + +## 3. Resume System + +### 3.1 Resume Interrupted Supervisor + +Resume a supervisor conversation that was interrupted (daemon disconnect, crash, etc.). + +#### API Endpoint + +``` +POST /api/v1/contracts/{contract_id}/supervisor/resume +``` + +#### Request Schema + +```typescript +interface ResumeSupervisorRequest { + // Optional: specify daemon to resume on + targetDaemonId?: string; + + // How to handle the resume + resumeMode: 'continue' | 'restart_phase' | 'from_checkpoint'; + + // For 'from_checkpoint' mode + checkpointId?: string; + + // Additional context to inject + additionalContext?: string; +} +``` + +#### Behavior + +1. **continue** (default): + - Load `supervisor_states.conversation_history` + - Prepend context summary to prompt + - Resume with full conversation context + +2. **restart_phase**: + - Start fresh for current phase + - Keep knowledge of completed work + - Don't replay old conversation + +3. **from_checkpoint**: + - Reset code to checkpoint state + - Clear conversation after checkpoint + - Resume from clean state + +#### Response Schema + +```typescript +interface ResumeSupervisorResponse { + supervisorTaskId: string; + daemonId: string; + resumedFrom: { + phase: string; + lastActivity: datetime; + messageCount: number; + }; + status: 'starting' | 'running'; +} +``` + +### 3.2 Resume Interrupted Task + +Resume a task that was interrupted mid-execution. + +#### API Endpoint (existing, enhanced) + +``` +POST /api/v1/mesh/tasks/{task_id}/continue +``` + +#### Enhanced Request Schema + +```typescript +interface ContinueTaskRequest { + targetDaemonId?: string; + + // NEW: Resume options + resumeMode?: 'with_context' | 'clean_restart' | 'from_checkpoint'; + checkpointSha?: string; + + // NEW: Context control + contextOptions?: { + maxMessages?: number; // Limit context size + includeToolCalls?: boolean; + includeToolResults?: boolean; + summaryMode?: boolean; // Use summarized context + }; +} +``` + +### 3.3 Resume from Specific Checkpoint + +Create a new task that starts from a specific checkpoint's code state. + +#### API Endpoint + +``` +POST /api/v1/mesh/tasks/{task_id}/checkpoints/{checkpoint_id}/resume +``` + +#### Request Schema + +```typescript +interface ResumeFromCheckpointRequest { + // Name for the new task + taskName?: string; + + // Plan/instructions for the resumed task + plan: string; + + // Whether to include conversation context up to checkpoint + includeConversation?: boolean; + + // Target daemon + targetDaemonId?: string; +} +``` + +#### Behavior + +1. Get checkpoint's commit SHA +2. Create new task with `checkpoint_sha` set +3. When daemon spawns task: + - Create worktree at checkpoint commit + - Optionally include conversation context +4. Task starts from checkpoint's code state + +#### Response Schema + +```typescript +interface ResumeFromCheckpointResponse { + newTaskId: string; + sourceTaskId: string; + checkpointUsed: { + number: number; + sha: string; + message: string; + }; + status: 'pending' | 'starting'; +} +``` + +### 3.4 Continue from Previous Task State + +Use existing `continue_from_task_id` field to inherit worktree state. + +#### API Endpoint (existing) + +``` +POST /api/v1/mesh/tasks +``` + +#### Relevant Fields + +```typescript +interface CreateTaskRequest { + // ... other fields ... + + // Copy worktree from this task + continueFromTaskId?: string; + + // Specific checkpoint SHA to branch from + checkpointSha?: string; + + // Files to copy from parent task's worktree + copyFiles?: string[]; +} +``` + +--- + +## 4. Rewind/Restore Features + +### 4.1 Rewind Code to Checkpoint + +Restore a task's worktree to a specific checkpoint's state. + +#### API Endpoint + +``` +POST /api/v1/mesh/tasks/{task_id}/rewind +``` + +#### Request Schema + +```typescript +interface RewindTaskRequest { + // Target checkpoint to rewind to + checkpointId?: string; + checkpointSha?: string; // Alternative: use SHA directly + + // What to do with current state + preserveMode: 'discard' | 'create_branch' | 'stash'; + + // For 'create_branch' mode + branchName?: string; +} +``` + +#### Behavior + +1. **discard**: Hard reset to checkpoint, lose current changes +2. **create_branch**: Create branch from current HEAD, then reset +3. **stash**: Git stash current changes, then reset + +#### Response Schema + +```typescript +interface RewindTaskResponse { + taskId: string; + rewindedTo: { + checkpointNumber: number; + sha: string; + message: string; + }; + preservedAs?: { + type: 'branch' | 'stash'; + reference: string; // Branch name or stash ref + }; +} +``` + +### 4.2 Rewind Conversation to Point + +Truncate conversation history to a specific point. + +#### API Endpoint + +``` +POST /api/v1/contracts/{contract_id}/supervisor/conversation/rewind +``` + +#### Request Schema + +```typescript +interface RewindConversationRequest { + // Rewind to message with this ID + toMessageId?: string; + + // OR rewind to messages before this timestamp + toTimestamp?: datetime; + + // OR rewind by N messages + byMessageCount?: number; + + // Whether to also rewind code to matching checkpoint + rewindCode?: boolean; +} +``` + +#### Behavior + +1. Identify the target point in `supervisor_states.conversation_history` +2. Truncate messages after that point +3. If `rewindCode` is true and there's a matching checkpoint, reset code +4. Update `supervisor_states` with truncated history + +### 4.3 Fork from Historical Point + +Create a new task/conversation branch from any point in history. + +#### API Endpoint + +``` +POST /api/v1/mesh/tasks/{task_id}/fork +``` + +#### Request Schema + +```typescript +interface ForkTaskRequest { + // Fork point specification + forkFrom: { + type: 'checkpoint' | 'timestamp' | 'message_id'; + value: string; + }; + + // New task configuration + newTask: { + name: string; + plan: string; + includeConversation?: boolean; // Include history up to fork point + }; + + // Git branching options + branchOptions?: { + createBranch?: boolean; + branchName?: string; + }; +} +``` + +#### Behavior + +1. Identify the fork point (checkpoint, timestamp, or message) +2. Create new task with: + - `checkpoint_sha` from fork point (or nearest checkpoint) + - Conversation context up to fork point (if requested) +3. Create git branch if requested +4. Start task in new direction + +#### Response Schema + +```typescript +interface ForkTaskResponse { + newTaskId: string; + sourceTaskId: string; + forkPoint: { + type: string; + checkpoint?: TaskCheckpoint; + timestamp: datetime; + }; + branchName?: string; + conversationIncluded: boolean; + messageCount?: number; +} +``` + +### 4.4 Create Branch from Checkpoint + +Create a new git branch from a specific checkpoint without starting a task. + +#### API Endpoint + +``` +POST /api/v1/mesh/tasks/{task_id}/checkpoints/{checkpoint_id}/branch +``` + +#### Request Schema + +```typescript +interface CreateBranchFromCheckpointRequest { + branchName: string; + checkout?: boolean; // Whether to checkout the new branch +} +``` + +--- + +## 5. Integration Points + +### 5.1 New CLI Commands + +#### History Commands + +```bash +# View contract history timeline +makima contract history [--phase <phase>] [--from <date>] [--to <date>] + +# View task conversation history +makima task history <task_id> [--limit <n>] [--no-tool-calls] + +# View task checkpoints +makima task checkpoints <task_id> [--with-diff] + +# View specific checkpoint diff +makima task checkpoint-diff <task_id> <checkpoint_number> +``` + +#### Resume Commands + +```bash +# Resume supervisor +makima supervisor resume [--mode <continue|restart|checkpoint>] [--checkpoint <id>] + +# Resume task +makima task resume <task_id> [--mode <context|clean|checkpoint>] [--checkpoint <sha>] + +# Resume from checkpoint +makima task resume-from <task_id> --checkpoint <number> --plan "continue with..." +``` + +#### Rewind Commands + +```bash +# Rewind code to checkpoint +makima task rewind <task_id> --checkpoint <number> [--preserve-branch <name>] + +# Rewind conversation +makima supervisor rewind-conversation --to-message <id> [--rewind-code] + +# Fork from checkpoint +makima task fork <task_id> --checkpoint <number> --name "alternate approach" --plan "..." +``` + +### 5.2 New API Endpoints Summary + +| Method | Path | Description | +|--------|------|-------------| +| GET | `/api/v1/contracts/{id}/history` | Contract history timeline | +| GET | `/api/v1/contracts/{id}/supervisor/conversation` | Supervisor conversation | +| POST | `/api/v1/contracts/{id}/supervisor/resume` | Resume supervisor | +| POST | `/api/v1/contracts/{id}/supervisor/conversation/rewind` | Rewind conversation | +| GET | `/api/v1/mesh/tasks/{id}/conversation` | Task conversation | +| GET | `/api/v1/mesh/tasks/{id}/checkpoints/{cid}/diff` | Checkpoint diff | +| POST | `/api/v1/mesh/tasks/{id}/checkpoints/{cid}/resume` | Resume from checkpoint | +| POST | `/api/v1/mesh/tasks/{id}/checkpoints/{cid}/branch` | Branch from checkpoint | +| POST | `/api/v1/mesh/tasks/{id}/rewind` | Rewind task code | +| POST | `/api/v1/mesh/tasks/{id}/fork` | Fork from history | +| GET | `/api/v1/timeline` | Unified timeline | + +### 5.3 Database Schema Changes + +#### New Table: `conversation_snapshots` + +Store conversation state at specific points for rewind capability. + +```sql +CREATE TABLE conversation_snapshots ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + task_id UUID NOT NULL REFERENCES tasks(id) ON DELETE CASCADE, + checkpoint_id UUID REFERENCES task_checkpoints(id) ON DELETE SET NULL, + snapshot_type VARCHAR(50) NOT NULL, -- 'auto', 'manual', 'checkpoint' + message_count INT NOT NULL, + conversation_state JSONB NOT NULL, -- Full conversation at this point + metadata JSONB, -- Additional context + created_at TIMESTAMPTZ DEFAULT NOW() +); + +CREATE INDEX idx_conversation_snapshots_task ON conversation_snapshots(task_id); +CREATE INDEX idx_conversation_snapshots_checkpoint ON conversation_snapshots(checkpoint_id); +``` + +#### New Table: `history_events` + +Unified event table for timeline views. + +```sql +CREATE TABLE history_events ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + owner_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE, + contract_id UUID REFERENCES contracts(id) ON DELETE CASCADE, + task_id UUID REFERENCES tasks(id) ON DELETE CASCADE, + event_type VARCHAR(50) NOT NULL, -- 'task', 'chat', 'checkpoint', 'phase', 'file' + event_subtype VARCHAR(50), -- Specific event type + phase VARCHAR(50), + event_data JSONB NOT NULL, + created_at TIMESTAMPTZ DEFAULT NOW() +); + +CREATE INDEX idx_history_events_contract ON history_events(contract_id, created_at DESC); +CREATE INDEX idx_history_events_task ON history_events(task_id, created_at DESC); +CREATE INDEX idx_history_events_owner ON history_events(owner_id, created_at DESC); +``` + +#### Table Modifications + +```sql +-- Add to task_checkpoints +ALTER TABLE task_checkpoints ADD COLUMN conversation_snapshot_id UUID + REFERENCES conversation_snapshots(id) ON DELETE SET NULL; + +-- Add to tasks +ALTER TABLE tasks ADD COLUMN forked_from_task_id UUID + REFERENCES tasks(id) ON DELETE SET NULL; +ALTER TABLE tasks ADD COLUMN forked_at_checkpoint_id UUID + REFERENCES task_checkpoints(id) ON DELETE SET NULL; +``` + +### 5.4 Frontend Integration + +#### New Components + +1. **ContractTimeline** - Visual timeline of contract activities +2. **ConversationViewer** - Display conversation history with syntax highlighting +3. **CheckpointBrowser** - Browse checkpoints with diff view +4. **RewindControls** - UI for rewind operations +5. **ForkDialog** - Modal for forking from history + +#### New Routes + +``` +/contracts/:id/history - Contract history timeline +/contracts/:id/supervisor - Supervisor conversation view +/tasks/:id/conversation - Task conversation view +/tasks/:id/checkpoints - Checkpoint browser +/tasks/:id/checkpoints/:cid - Checkpoint detail with diff +``` + +--- + +## 6. Implementation Plan + +### 6.1 Phase 1: Database & Models (Migration 20250116_history_tables) + +**Migrations:** + +1. Create `conversation_snapshots` table +2. Create `history_events` table +3. Add columns to `task_checkpoints` and `tasks` +4. Create indexes for efficient queries + +**Models (Rust):** + +1. `ConversationSnapshot` struct +2. `HistoryEvent` struct +3. `ConversationMessage` struct (unified format) +4. Update `TaskCheckpoint` with new fields + +### 6.2 Phase 2: Repository Functions + +**New Functions:** + +```rust +// Conversation snapshots +pub async fn create_conversation_snapshot(pool, task_id, checkpoint_id, state) -> ConversationSnapshot +pub async fn get_conversation_snapshot(pool, id) -> Option<ConversationSnapshot> +pub async fn get_conversation_at_checkpoint(pool, checkpoint_id) -> Option<ConversationSnapshot> +pub async fn list_conversation_snapshots(pool, task_id) -> Vec<ConversationSnapshot> + +// History events +pub async fn record_history_event(pool, event) -> HistoryEvent +pub async fn get_contract_history(pool, contract_id, filters) -> Vec<HistoryEvent> +pub async fn get_task_history(pool, task_id, filters) -> Vec<HistoryEvent> +pub async fn get_timeline(pool, owner_id, filters) -> Vec<HistoryEvent> + +// Conversation retrieval +pub async fn get_task_conversation(pool, task_id, options) -> Vec<ConversationMessage> +pub async fn get_supervisor_conversation(pool, contract_id) -> SupervisorConversation + +// Checkpoint operations +pub async fn get_checkpoint_diff(pool, checkpoint_id) -> CheckpointDiff +pub async fn create_checkpoint_with_snapshot(pool, task_id, message, conversation_state) -> TaskCheckpoint +``` + +### 6.3 Phase 3: API Endpoints + +**History Endpoints:** + +1. `GET /api/v1/contracts/{id}/history` +2. `GET /api/v1/contracts/{id}/supervisor/conversation` +3. `GET /api/v1/mesh/tasks/{id}/conversation` +4. `GET /api/v1/mesh/tasks/{id}/checkpoints/{cid}/diff` +5. `GET /api/v1/timeline` + +**Resume Endpoints:** + +1. `POST /api/v1/contracts/{id}/supervisor/resume` +2. `POST /api/v1/mesh/tasks/{id}/checkpoints/{cid}/resume` +3. Enhance existing `POST /api/v1/mesh/tasks/{id}/continue` + +**Rewind Endpoints:** + +1. `POST /api/v1/mesh/tasks/{id}/rewind` +2. `POST /api/v1/contracts/{id}/supervisor/conversation/rewind` +3. `POST /api/v1/mesh/tasks/{id}/fork` +4. `POST /api/v1/mesh/tasks/{id}/checkpoints/{cid}/branch` + +### 6.4 Phase 4: CLI Commands + +**New Commands:** + +1. `makima contract history` - View contract history +2. `makima task history` - View task conversation +3. `makima task checkpoints` - List checkpoints +4. `makima task checkpoint-diff` - View checkpoint diff +5. `makima supervisor resume` - Resume supervisor +6. `makima task resume` - Resume task +7. `makima task resume-from` - Resume from checkpoint +8. `makima task rewind` - Rewind code +9. `makima supervisor rewind-conversation` - Rewind conversation +10. `makima task fork` - Fork from history + +### 6.5 Phase 5: Daemon Integration + +**New Daemon Commands:** + +```rust +enum DaemonCommand { + // Existing... + + // New + RewindToCheckpoint { + task_id: Uuid, + checkpoint_sha: String, + preserve_mode: PreserveMode, + branch_name: Option<String>, + }, + CreateConversationSnapshot { + task_id: Uuid, + }, + RestoreFromSnapshot { + task_id: Uuid, + snapshot_id: Uuid, + }, +} +``` + +**Daemon Handlers:** + +1. Implement `handle_rewind_to_checkpoint` +2. Implement `handle_create_conversation_snapshot` +3. Update checkpoint creation to include conversation state +4. Update task spawning to handle fork/resume scenarios + +### 6.6 Phase 6: Frontend Components + +**Components:** + +1. ContractTimeline +2. ConversationViewer +3. CheckpointBrowser +4. DiffViewer +5. RewindControls +6. ForkDialog +7. ResumeDialog + +**Routes & Pages:** + +1. Contract history page +2. Supervisor conversation page +3. Task conversation page +4. Checkpoint detail page + +--- + +## 7. Security Considerations + +### 7.1 Access Control + +- All history/resume/rewind operations must verify owner_id +- Supervisor operations require tool key authentication +- Frontend operations require user authentication +- Prevent access to other users' conversation history + +### 7.2 Data Retention + +- Conversation snapshots may contain sensitive data +- Implement configurable retention policies +- Consider encryption for stored conversation data +- Provide data export/deletion capabilities + +### 7.3 Audit Trail + +- Log all rewind/restore operations +- Track who initiated changes +- Maintain original data before modifications + +--- + +## 8. Performance Considerations + +### 8.1 Pagination + +- All list endpoints support cursor-based pagination +- Limit maximum response sizes +- Use efficient queries with proper indexes + +### 8.2 Caching + +- Cache frequently accessed conversation history +- Invalidate cache on updates +- Consider read replicas for history queries + +### 8.3 Storage + +- Compress large conversation histories +- Consider archiving old snapshots +- Monitor database size growth + +--- + +## 9. Future Enhancements + +1. **Search within history** - Full-text search across conversations +2. **History comparison** - Diff between two points in time +3. **Replay mode** - Step through conversation history +4. **Export history** - Download conversation/checkpoint history +5. **History annotations** - Add notes to historical points +6. **Automatic snapshots** - Periodic conversation backups +7. **History sharing** - Share specific history ranges +8. **AI-powered summaries** - Generate summaries of historical periods |