# Technical Plan: Task Logging System (Separated Per-Task Logs)

**Feature Branch**: `018-task-logging-v2`
**Specification**: [`specs/018-task-logging-v2/spec.md`](specs/018-task-logging-v2/spec.md)
**Created**: 2026-02-07
**Status**: Draft

## 1. Architecture Overview

The system will transition from in-memory JSON logging to a persistent, source-attributed logging architecture.

### 1.1. Component Diagram

```mermaid
graph TD
    subgraph Backend
        P[Plugin] -->|uses| TC[TaskContext]
        TC -->|delegates| TL[TaskLogger]
        TL -->|calls| TM[TaskManager]
        TM -->|buffers| LB[LogBuffer]
        LB -->|periodic flush| LPS[LogPersistenceService]
        LPS -->|SQL| DB[(SQLite: task_logs)]
        TM -->|broadcast| WS[WebSocket Server]
    end
    subgraph Frontend
        WS -->|stream| TLP[TaskLogPanel]
        API[REST API] -->|fetch history| TLP
        TLP -->|render| UI[Log UI]
    end
```

## 2. Database Schema

A new table `task_logs` will be added to the primary database.

| Column | Type | Constraints |
|--------|------|-------------|
| `id` | Integer | Primary Key, Autoincrement |
| `task_id` | String | Foreign Key (tasks.id), Indexed |
| `timestamp` | DateTime | Not Null, Indexed |
| `level` | String(16) | Not Null (INFO, WARNING, ERROR, DEBUG) |
| `source` | String(64) | Not Null, Default: 'system' |
| `message` | Text | Not Null |
| `metadata_json` | Text | Nullable (JSON string) |

## 3. Backend Implementation Details

### 3.1. `TaskLogger` & `TaskContext`
- `TaskLogger`: A wrapper around `TaskManager._add_log` that carries `task_id` and `source`.
- `TaskContext`: A container passed to `plugin.execute()` providing the logger and other task-specific utilities.

### 3.2. `TaskManager` Enhancements
- **Log Buffer**: A dictionary mapping `task_id` to a list of pending `LogEntry` objects.
- **Flusher Thread**: A background daemon thread that flushes the buffer to the database every 2 seconds.
- **Backward Compatibility**: Use `inspect.signature` to detect if a plugin's `execute` method accepts the new `context` parameter.

### 3.3. API Endpoints
- `GET /api/tasks/{task_id}/logs`: Supports `level`, `source`, `search`, `offset`, and `limit`.
- `GET /api/tasks/{task_id}/logs/stats`: Returns counts by level and source.
- `GET /api/tasks/{task_id}/logs/sources`: Returns unique sources for the task.

## 4. Frontend Implementation Details

### 4.1. Components
- `TaskLogPanel`: Main container managing state and data fetching.
- `LogFilterBar`: UI for selecting filters.
- `LogEntryRow`: Optimized row rendering with color coding and progress bar support.

### 4.2. Data Fetching
- **Live Tasks**: Connect via WebSocket with filter parameters in the query string.
- **Completed Tasks**: Fetch via REST API with pagination.

## 5. Implementation Phases

### Phase 1: Foundation
- Database migration (new table).
- `LogPersistenceService` implementation.
- `TaskLogger` and `TaskContext` classes.

### Phase 2: Core Integration
- `TaskManager` buffer and flusher logic.
- API endpoint updates.
- WebSocket server-side filtering.

### Phase 3: Plugin Migration
- Update core plugins (Backup, Migration, Git) to use the new logger.
- Verify backward compatibility with un-migrated plugins.

### Phase 4: Frontend
- Implement new Svelte components.
- Integrate with updated API and WebSocket.

## 6. Verification Plan

- **Unit Tests**:
    - `TaskLogger` correctly routes to `TaskManager`.
    - `LogPersistenceService` handles batch inserts and complex filters.
    - `TaskManager` flushes logs on task completion.
- **Integration Tests**:
    - End-to-end flow from plugin log to frontend display.
    - Verification of log persistence after server restart.
- **Performance Tests**:
    - Measure overhead of batch logging under high load (1000+ logs/sec).