Update background jobs

[alvinunreal]

Summary

Changes

[greptile-apps]

Greptile Overview

Greptile Summary

This PR simplifies background task notifications by removing the notifyOnComplete configuration option and making notifications always enabled.

Key Changes

• Background task notifications are now always sent - The optional notifyOnComplete parameter has been removed from the background task configuration, tool parameters, and launch options. Parent sessions will always receive completion notifications when background tasks finish.

• Configuration simplified - BackgroundTaskConfigSchema no longer includes notifyOnComplete, and the BackgroundTaskConfig interface in task objects has been simplified to only include maxConcurrentStarts.

• Tool descriptions improved - The background_task, background_output, and background_cancel tool descriptions have been rewritten to be clearer and more concise, with better guidance on usage patterns.

• Code cleanup - Unused parameters and imports removed from createBackgroundTools function (marked with underscore prefix), and import ordering improved in multiple files.

• Tests updated - Test cases adjusted to reflect the new behavior where notifications are always sent, with the test name changed from "notifyOnComplete sends notification" to "always sends notification to parent session on completion".

Impact

This is a behavioral change that affects all background tasks. Previously, users could opt-in to notifications; now notifications are always sent. This improves user experience by ensuring they're always informed when background tasks complete, but may result in more notifications for users who previously had this disabled.

Confidence Score: 5/5

• This PR is safe to merge with no issues found
• The changes are well-implemented with complete test coverage, proper cleanup of all references to the removed feature, and clear improvements to code quality. The refactoring is internally consistent across all affected files.
• No files require special attention

Important Files Changed

Filename	Overview
src/background/background-manager.ts	Removed notifyOnComplete config option, notifications now always sent to parent session on task completion
src/config/schema.ts	Removed notifyOnComplete field from BackgroundTaskConfigSchema
src/tools/background.ts	Removed notifyOnComplete parameter from tool, cleaned up unused imports and parameters, improved tool descriptions
src/background/background-manager.test.ts	Updated tests to reflect removal of notifyOnComplete config, test now verifies notifications always sent

Sequence Diagram

sequenceDiagram
    participant User
    participant Agent
    participant BackgroundTool as background_task tool
    participant Manager as BackgroundTaskManager
    participant ParentSession as Parent Session
    participant BackgroundSession as Background Session

    User->>Agent: Request background task
    Agent->>BackgroundTool: Call background_task(agent, prompt, description)
    BackgroundTool->>Manager: launch(opts)
    Manager->>Manager: Create task (status: pending)
    Manager-->>BackgroundTool: Return task with task_id
    BackgroundTool-->>Agent: Task launched (task_id)
    Agent-->>User: Background task started

    Note over Manager: Fire-and-forget execution
    Manager->>Manager: enqueueStart(task)
    Manager->>Manager: processQueue()
    Manager->>Manager: startTask(task) [async]
    Manager->>BackgroundSession: Create session
    BackgroundSession-->>Manager: session_id
    Manager->>Manager: Update task (status: running)
    Manager->>BackgroundSession: Send prompt

    Note over BackgroundSession: Agent processes task

    BackgroundSession->>Manager: session.status event (idle)
    Manager->>Manager: handleSessionStatus()
    Manager->>BackgroundSession: Fetch messages
    BackgroundSession-->>Manager: Return assistant messages
    Manager->>Manager: extractAndCompleteTask()
    Manager->>Manager: completeTask(task, 'completed', result)
    Manager->>ParentSession: sendCompletionNotification()
    Note over Manager,ParentSession: Always sends notification (no config needed)
    ParentSession-->>User: [Background task "description" completed]

Loading