ss-tools/specs/018-task-logging-v2/plan.md

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

Feature Branch: 018-task-logging-v2 Specification: 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

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).