@stina/extension-api 0.21.0 → 0.22.1

package/src/background.ts

@@ -0,0 +1,261 @@
+/**
+ * Background Task Manager (Worker-side)
+ *
+ * Manages background tasks running inside the extension worker.
+ * Handles task execution, AbortController management, and health reporting.
+ */
+
+import type {
+  BackgroundTaskConfig,
+  BackgroundTaskCallback,
+  BackgroundTaskContext,
+  BackgroundTaskHealth,
+  Disposable,
+  LogAPI,
+} from './types.js'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Internal representation of a registered task
+ */
+interface RegisteredTask {
+  config: BackgroundTaskConfig
+  callback: BackgroundTaskCallback
+  abortController: AbortController | null
+  status: 'pending' | 'running' | 'stopped' | 'failed'
+  lastHealthStatus?: string
+  lastHealthTime?: string
+  error?: string
+}
+
+/**
+ * Options for the WorkerBackgroundTaskManager
+ */
+export interface WorkerBackgroundTaskManagerOptions {
+  extensionId: string
+  extensionVersion: string
+  storagePath: string
+  /** Send a message to the host */
+  sendTaskRegistered: (
+    taskId: string,
+    name: string,
+    userId: string,
+    restartPolicy: BackgroundTaskConfig['restartPolicy'],
+    payload?: Record<string, unknown>
+  ) => void
+  /** Send status update to host */
+  sendTaskStatus: (taskId: string, status: 'running' | 'stopped' | 'failed', error?: string) => void
+  /** Send health report to host */
+  sendHealthReport: (taskId: string, status: string, timestamp: string) => void
+  /** Create a log API for a task */
+  createLogAPI: (taskId: string) => LogAPI
+}
+
+// ============================================================================
+// WorkerBackgroundTaskManager
+// ============================================================================
+
+/**
+ * Manages background tasks within the extension worker.
+ */
+export class WorkerBackgroundTaskManager {
+  private readonly tasks = new Map<string, RegisteredTask>()
+  private readonly options: WorkerBackgroundTaskManagerOptions
+
+  constructor(options: WorkerBackgroundTaskManagerOptions) {
+    this.options = options
+  }
+
+  /**
+   * Register and start a background task.
+   * @returns A disposable that stops the task when disposed
+   */
+  async start(config: BackgroundTaskConfig, callback: BackgroundTaskCallback): Promise<Disposable> {
+    const { id: taskId } = config
+
+    if (this.tasks.has(taskId)) {
+      throw new Error(`Background task with id '${taskId}' is already registered`)
+    }
+
+    const task: RegisteredTask = {
+      config,
+      callback,
+      abortController: null,
+      status: 'pending',
+    }
+
+    this.tasks.set(taskId, task)
+
+    // Notify host about the registration
+    this.options.sendTaskRegistered(
+      taskId,
+      config.name,
+      config.userId,
+      config.restartPolicy,
+      config.payload
+    )
+
+    // Return a disposable that stops the task
+    // Task removal should be coordinated with the host to avoid race conditions
+    return {
+      dispose: () => {
+        this.stop(taskId)
+        // Don't immediately delete - let the task finish aborting
+        // The task will be cleaned up when the extension is deactivated
+      },
+    }
+  }
+
+  /**
+   * Stop a running task.
+   */
+  stop(taskId: string): void {
+    const task = this.tasks.get(taskId)
+    if (!task) {
+      return
+    }
+
+    // Abort the task if it's running
+    if (task.abortController) {
+      task.abortController.abort()
+      task.abortController = null
+    }
+
+    task.status = 'stopped'
+
+    // Notify host that the task has been stopped
+    this.options.sendTaskStatus(taskId, 'stopped')
+  }
+
+  /**
+   * Handle start message from host.
+   * This is called when the host tells us to actually run the task.
+   */
+  async handleStart(taskId: string): Promise<void> {
+    const task = this.tasks.get(taskId)
+    if (!task) {
+      return
+    }
+
+    // If there's already an execution running, abort it first
+    if (task.abortController) {
+      task.abortController.abort()
+      task.abortController = null
+    }
+
+    // Create new AbortController for this run
+    task.abortController = new AbortController()
+    task.status = 'running'
+    task.error = undefined
+
+    // Build the task context
+    const context = this.buildTaskContext(task)
+
+    // Notify host that we're running
+    this.options.sendTaskStatus(taskId, 'running')
+
+    try {
+      // Execute the callback
+      await task.callback(context)
+
+      // Task completed normally (or was aborted)
+      if (task.abortController?.signal.aborted) {
+        task.status = 'stopped'
+        this.options.sendTaskStatus(taskId, 'stopped')
+      } else {
+        // Task finished without being aborted - treat as stopped
+        task.status = 'stopped'
+        this.options.sendTaskStatus(taskId, 'stopped')
+      }
+    } catch (error) {
+      // Task failed with an error
+      const errorMessage = error instanceof Error ? error.message : String(error)
+      task.status = 'failed'
+      task.error = errorMessage
+      this.options.sendTaskStatus(taskId, 'failed', errorMessage)
+    } finally {
+      task.abortController = null
+    }
+  }
+
+  /**
+   * Handle stop message from host.
+   */
+  handleStop(taskId: string): void {
+    this.stop(taskId)
+  }
+
+  /**
+   * Build the execution context for a task.
+   */
+  private buildTaskContext(task: RegisteredTask): BackgroundTaskContext {
+    const { config, abortController } = task
+    const signal = abortController!.signal
+
+    const log = this.options.createLogAPI(config.id)
+
+    const context: BackgroundTaskContext = {
+      userId: config.userId,
+      extension: {
+        id: this.options.extensionId,
+        version: this.options.extensionVersion,
+        storagePath: this.options.storagePath,
+      },
+      signal,
+      reportHealth: (status: string) => {
+        const timestamp = new Date().toISOString()
+        task.lastHealthStatus = status
+        task.lastHealthTime = timestamp
+        this.options.sendHealthReport(config.id, status, timestamp)
+      },
+      log,
+    }
+
+    return context
+  }
+
+  /**
+   * Get the status of all tasks.
+   */
+  getStatus(): BackgroundTaskHealth[] {
+    const result: BackgroundTaskHealth[] = []
+
+    for (const task of this.tasks.values()) {
+      result.push({
+        taskId: task.config.id,
+        name: task.config.name,
+        userId: task.config.userId,
+        status: task.status,
+        restartCount: 0, // Worker doesn't track restarts, host does
+        lastHealthStatus: task.lastHealthStatus,
+        lastHealthTime: task.lastHealthTime,
+        error: task.error,
+      })
+    }
+
+    return result
+  }
+
+  /**
+   * Check if a task exists.
+   */
+  hasTask(taskId: string): boolean {
+    return this.tasks.has(taskId)
+  }
+
+  /**
+   * Clean up all tasks.
+   * Called during extension deactivation.
+   */
+  dispose(): void {
+    for (const task of this.tasks.values()) {
+      if (task.abortController) {
+        task.abortController.abort()
+      }
+    }
+    this.tasks.clear()
+  }
+}

package/src/index.ts

@@ -73,6 +73,14 @@ export type {
   StorageAPI,
   LogAPI,
 
+  // Background workers
+  BackgroundWorkersAPI,
+  BackgroundTaskConfig,
+  BackgroundTaskCallback,
+  BackgroundTaskContext,
+  BackgroundTaskHealth,
+  BackgroundRestartPolicy,
+
   // AI Provider
   AIProvider,
   ModelInfo,
@@ -117,6 +125,12 @@ export type {
   StreamEventMessage,
   LogMessage,
   PendingRequest,
+  // Background task messages
+  BackgroundTaskStartMessage,
+  BackgroundTaskStopMessage,
+  BackgroundTaskRegisteredMessage,
+  BackgroundTaskStatusMessage,
+  BackgroundTaskHealthMessage,
 } from './messages.js'
 
 export { generateMessageId } from './messages.js'

package/src/messages.ts

@@ -28,6 +28,8 @@ export type HostToWorkerMessage =
   | ActionExecuteRequestMessage
   | ResponseMessage
   | StreamingFetchChunkMessage
+  | BackgroundTaskStartMessage
+  | BackgroundTaskStopMessage
 
 export interface ActivateMessage {
   type: 'activate'
@@ -128,6 +130,28 @@ export interface StreamingFetchChunkMessage {
   }
 }
 
+/**
+ * Message sent from host to worker to start a registered background task.
+ */
+export interface BackgroundTaskStartMessage {
+  type: 'background-task-start'
+  id: string
+  payload: {
+    taskId: string
+  }
+}
+
+/**
+ * Message sent from host to worker to stop a running background task.
+ */
+export interface BackgroundTaskStopMessage {
+  type: 'background-task-stop'
+  id: string
+  payload: {
+    taskId: string
+  }
+}
+
 // ============================================================================
 // Worker → Host Messages
 // ============================================================================
@@ -144,6 +168,9 @@ export type WorkerToHostMessage =
   | ToolExecuteResponseMessage
   | ActionExecuteResponseMessage
   | StreamingFetchAckMessage
+  | BackgroundTaskRegisteredMessage
+  | BackgroundTaskStatusMessage
+  | BackgroundTaskHealthMessage
 
 export interface ReadyMessage {
   type: 'ready'
@@ -257,6 +284,50 @@ export interface LogMessage {
   }
 }
 
+/**
+ * Message sent from worker to host when a background task is registered.
+ */
+export interface BackgroundTaskRegisteredMessage {
+  type: 'background-task-registered'
+  payload: {
+    taskId: string
+    name: string
+    userId: string
+    restartPolicy: {
+      type: 'always' | 'on-failure' | 'never'
+      maxRestarts?: number
+      initialDelayMs?: number
+      maxDelayMs?: number
+      backoffMultiplier?: number
+    }
+    payload?: Record<string, unknown>
+  }
+}
+
+/**
+ * Message sent from worker to host with background task status updates.
+ */
+export interface BackgroundTaskStatusMessage {
+  type: 'background-task-status'
+  payload: {
+    taskId: string
+    status: 'running' | 'stopped' | 'failed'
+    error?: string
+  }
+}
+
+/**
+ * Message sent from worker to host with background task health reports.
+ */
+export interface BackgroundTaskHealthMessage {
+  type: 'background-task-health'
+  payload: {
+    taskId: string
+    status: string
+    timestamp: string
+  }
+}
+
 // ============================================================================
 // Utility Types
 // ============================================================================

package/src/runtime.ts

@@ -32,8 +32,14 @@ import type {
   ChatMessage,
   ChatOptions,
   GetModelsOptions,
+  BackgroundWorkersAPI,
+  BackgroundTaskConfig,
+  BackgroundTaskCallback,
+  BackgroundTaskHealth,
 } from './types.js'
 
+import { WorkerBackgroundTaskManager } from './background.js'
+
 import type {
   HostToWorkerMessage,
   WorkerToHostMessage,
@@ -88,6 +94,7 @@ const messagePort = getMessagePort()
 let extensionModule: ExtensionModule | null = null
 let extensionDisposable: Disposable | null = null
 let extensionContext: ExtensionContext | null = null
+let backgroundTaskManager: WorkerBackgroundTaskManager | null = null
 
 const pendingRequests = new Map<string, PendingRequest>()
 const registeredProviders = new Map<string, AIProvider>()
@@ -188,6 +195,14 @@ async function handleHostMessage(message: HostToWorkerMessage): Promise<void> {
     case 'streaming-fetch-chunk':
       handleStreamingFetchChunk(message.payload)
       break
+
+    case 'background-task-start':
+      await handleBackgroundTaskStart(message.payload.taskId)
+      break
+
+    case 'background-task-stop':
+      handleBackgroundTaskStop(message.payload.taskId)
+      break
   }
 }
 
@@ -284,12 +299,16 @@ async function handleDeactivate(): Promise<void> {
     if (extensionDisposable) {
       extensionDisposable.dispose()
     }
+    if (backgroundTaskManager) {
+      backgroundTaskManager.dispose()
+    }
   } catch (error) {
     console.error('Error during deactivation:', error)
   } finally {
     extensionModule = null
     extensionDisposable = null
     extensionContext = null
+    backgroundTaskManager = null
     registeredProviders.clear()
     registeredTools.clear()
     registeredActions.clear()
@@ -332,6 +351,26 @@ async function handleSchedulerFire(payload: SchedulerFirePayload): Promise<void>
   })
 }
 
+// ============================================================================
+// Background Task Handlers
+// ============================================================================
+
+async function handleBackgroundTaskStart(taskId: string): Promise<void> {
+  if (!backgroundTaskManager) {
+    console.error('Background task manager not initialized')
+    return
+  }
+  await backgroundTaskManager.handleStart(taskId)
+}
+
+function handleBackgroundTaskStop(taskId: string): void {
+  if (!backgroundTaskManager) {
+    console.error('Background task manager not initialized')
+    return
+  }
+  backgroundTaskManager.handleStop(taskId)
+}
+
 // ============================================================================
 // Provider / Tool Requests
 // ============================================================================
@@ -826,6 +865,73 @@ function buildContext(
     ;(context as { storage: StorageAPI }).storage = storageApi
   }
 
+  // Add background workers API if permitted
+  if (hasPermission('background.workers')) {
+    // Initialize the background task manager if not already done
+    if (!backgroundTaskManager) {
+      backgroundTaskManager = new WorkerBackgroundTaskManager({
+        extensionId,
+        extensionVersion,
+        storagePath,
+        sendTaskRegistered: (taskId, name, userId, restartPolicy, payload) => {
+          postMessage({
+            type: 'background-task-registered',
+            payload: {
+              taskId,
+              name,
+              userId,
+              restartPolicy,
+              payload,
+            },
+          })
+        },
+        sendTaskStatus: (taskId, status, error) => {
+          postMessage({
+            type: 'background-task-status',
+            payload: {
+              taskId,
+              status,
+              error,
+            },
+          })
+        },
+        sendHealthReport: (taskId, status, timestamp) => {
+          postMessage({
+            type: 'background-task-health',
+            payload: {
+              taskId,
+              status,
+              timestamp,
+            },
+          })
+        },
+        createLogAPI: (taskId) => ({
+          debug: (message, data) =>
+            postMessage({ type: 'log', payload: { level: 'debug', message: `[${taskId}] ${message}`, data } }),
+          info: (message, data) =>
+            postMessage({ type: 'log', payload: { level: 'info', message: `[${taskId}] ${message}`, data } }),
+          warn: (message, data) =>
+            postMessage({ type: 'log', payload: { level: 'warn', message: `[${taskId}] ${message}`, data } }),
+          error: (message, data) =>
+            postMessage({ type: 'log', payload: { level: 'error', message: `[${taskId}] ${message}`, data } }),
+        }),
+      })
+    }
+
+    const backgroundWorkersApi: BackgroundWorkersAPI = {
+      async start(config: BackgroundTaskConfig, callback: BackgroundTaskCallback): Promise<Disposable> {
+        return backgroundTaskManager!.start(config, callback)
+      },
+      async stop(taskId: string): Promise<void> {
+        backgroundTaskManager!.stop(taskId)
+      },
+      async getStatus(): Promise<BackgroundTaskHealth[]> {
+        return backgroundTaskManager!.getStatus()
+      },
+    }
+    ;(context as { backgroundWorkers: BackgroundWorkersAPI }).backgroundWorkers = backgroundWorkersApi
+  }
+
   return context
 }
 
@@ -871,4 +977,11 @@ export type {
   ChatOptions,
   GetModelsOptions,
   StreamEvent,
+  // Background workers
+  BackgroundWorkersAPI,
+  BackgroundTaskConfig,
+  BackgroundTaskCallback,
+  BackgroundTaskContext,
+  BackgroundTaskHealth,
+  BackgroundRestartPolicy,
 } from './types.js'