Background Jobs

Each job creates a background_jobs row in SQLite with these fields:

• id (TEXT PRIMARY KEY): UUID for the job.
• session_id (TEXT NOT NULL, FK): References sessions.id with CASCADE DELETE.
• task_type (TEXT DEFAULT 'unknown'): Processor identifier (e.g., implementation_plan, text_improvement, root_folder_selection).
• status (TEXT): Current state with CHECK constraint for valid values.
• prompt (TEXT NOT NULL): Full text sent to the LLM, stored for audit.
• response (TEXT): LLM output or error message.
• error_message (TEXT): Detailed error information on failure.
• tokens_sent (INTEGER DEFAULT 0): Input token count from provider response.
• tokens_received (INTEGER DEFAULT 0): Output token count.
• cache_read_tokens (INTEGER DEFAULT 0): Tokens read from provider cache (Anthropic).
• cache_write_tokens (INTEGER DEFAULT 0): Tokens written to cache.
• model_used (TEXT): Model identifier used for the request.
• actual_cost (REAL): Computed cost based on token usage and model pricing.
• metadata (TEXT): JSON with task-specific data, workflow IDs, stage names.
• system_prompt_template (TEXT): Template identifier used for the system prompt.
• server_request_id (TEXT): Links to server-side usage tracking.
• created_at, updated_at, start_time, end_time (INTEGER): Timestamps.
• is_finalized (INTEGER DEFAULT 0): Whether final cost/usage has been recorded.

Multi-stage workflows are managed by WorkflowOrchestrator in desktop/src-tauri/src/jobs/workflow_orchestrator/:

Workflows use WorkflowIntermediateData (defined in workflow_types.rs) to pass outputs between stages: directoryTreeContent, selectedRoots, rawRegexPatterns, locallyFilteredFiles, aiFilteredFiles, verifiedPaths, unverifiedPaths.

Each task_type maps to a processor in desktop/src-tauri/src/jobs/processors/:

• implementation_plan_processor.rs: Loads selected file contents, builds structured prompt with directory tree, streams XML plan to UI. Uses generic_llm_stream_processor for streaming.
• text_improvement_processor.rs: Wraps selection in XML tags, sends non-streaming request, returns improved text. Runs via LlmTaskRunner.
• root_folder_selection_processor.rs: Sends directory tree to LLM, parses JSON array response of selected directories.
• RegexFileFilterProcessor (in processors/mod.rs): Generates regex patterns from task, applies to git file list, filters binaries.
• FileRelevanceAssessmentProcessor: Chunks file contents by token limit, scores relevance in batches, aggregates relevant paths.
• ExtendedPathFinderProcessor (path_finder_types.rs): Analyzes imports/dependencies, suggests related files, validates paths exist.
• web_search_prompts_generator_processor.rs: Generates research_task XML blocks for deep research.
• web_search_executor_processor.rs: Executes research prompts in parallel via server search API.
• generic_llm_stream_processor.rs: Reusable streaming processor that handles chunk accumulation, event emission, and response finalization.

Jobs transition through well-defined statuses tracked in the database:

Transitions are enforced in background_job_repository/worker.rs. Invalid transitions are rejected. Status changes emit job:status-changed Tauri events.

Job progress emits Tauri events consumed by the React UI:

• job:status-changed: Payload {jobId, status, error?}. Emitted on every status transition.
• job:stream-progress: Payload {jobId, content, tokensReceived}. Emitted for each streaming chunk.
• job:completed: Payload {jobId, response, tokensTotal, cost}. Emitted on successful completion.
• workflow-status: Payload {workflowId, status, currentStage?}. Workflow-level status updates.
• workflow-stage: Payload {workflowId, stageName, status}. Individual stage status.

Job retry and cancellation mechanisms:

Cancellation sets a flag checked between streaming chunks in generic_llm_stream_processor.rs. Server-side cancellation sends /api/llm/cancel with request_id.

Job inputs and outputs are fully persisted for audit:

• prompt: Complete LLM prompt including system prompt and user content.
• response: Full LLM response text or streaming accumulation.
• metadata: JSON with task-specific data (original text for improvements, file lists, workflow context).
• system_prompt_template: Identifier linking to server-side prompt template version.
• Token counts and cost: Captured from provider response for billing and analysis.

• desktop/src-tauri/src/jobs/mod.rs - Job system entry point
• desktop/src-tauri/src/jobs/queue.rs - Priority queue (8 workers)
• desktop/src-tauri/src/jobs/dispatcher.rs - Job execution
• desktop/src-tauri/src/jobs/types.rs - Job and payload types
• desktop/src-tauri/src/jobs/processors/ - All processor implementations
• desktop/src-tauri/src/jobs/workflow_orchestrator/ - Multi-stage workflows
• desktop/src-tauri/src/jobs/streaming_handler.rs - LLM stream handling