@stina/extension-api 0.20.0 → 0.22.0

package/src/types.context.ts

@@ -104,6 +104,9 @@ export interface ExtensionContext {
   /** Local storage (if permitted) */
   readonly storage?: StorageAPI
 
+  /** Background workers (if permitted) */
+  readonly backgroundWorkers?: BackgroundWorkersAPI
+
   /** Logging (always available) */
   readonly log: LogAPI
 }
@@ -397,3 +400,217 @@ export interface ExtensionModule {
    */
   deactivate?(): void | Promise<void>
 }
+
+// ============================================================================
+// Background Workers API
+// ============================================================================
+
+/**
+ * Restart policy for background tasks.
+ * Controls how tasks are restarted after failures.
+ */
+export interface BackgroundRestartPolicy {
+  /**
+   * When to restart the task:
+   * - 'always': Always restart, regardless of exit reason
+   * - 'on-failure': Only restart if the task threw an error
+   * - 'never': Never restart automatically
+   */
+  type: 'always' | 'on-failure' | 'never'
+
+  /**
+   * Maximum number of restarts before giving up.
+   * 0 means unlimited restarts.
+   * @default 0
+   */
+  maxRestarts?: number
+
+  /**
+   * Initial delay in milliseconds before first restart.
+   * @default 1000
+   */
+  initialDelayMs?: number
+
+  /**
+   * Maximum delay in milliseconds between restarts.
+   * @default 60000
+   */
+  maxDelayMs?: number
+
+  /**
+   * Multiplier for exponential backoff.
+   * @default 2
+   */
+  backoffMultiplier?: number
+}
+
+/**
+ * Configuration for a background task.
+ */
+export interface BackgroundTaskConfig {
+  /**
+   * Unique identifier for the task within the extension.
+   * Used to reference the task for stopping or checking status.
+   */
+  id: string
+
+  /**
+   * Human-readable name for observability and logging.
+   */
+  name: string
+
+  /**
+   * User ID that owns this task.
+   * Background tasks are always user-scoped.
+   */
+  userId: string
+
+  /**
+   * Policy for restarting the task after failures.
+   */
+  restartPolicy: BackgroundRestartPolicy
+
+  /**
+   * Optional payload data passed to the task callback.
+   */
+  payload?: Record<string, unknown>
+}
+
+/**
+ * Context provided to background task callbacks.
+ * Extends ExecutionContext with task-specific functionality.
+ */
+export interface BackgroundTaskContext extends ExecutionContext {
+  /**
+   * AbortSignal that is triggered when the task should stop.
+   * Check this signal regularly and exit gracefully when aborted.
+   */
+  readonly signal: AbortSignal
+
+  /**
+   * Report the current health status of the task.
+   * Use this to provide observability into what the task is doing.
+   *
+   * @param status Human-readable status message
+   */
+  reportHealth(status: string): void
+
+  /**
+   * Task-specific logging API.
+   * Messages are tagged with the task ID for easier debugging.
+   */
+  readonly log: LogAPI
+}
+
+/**
+ * Callback function for background tasks.
+ * The function should run until the signal is aborted, then clean up and return.
+ *
+ * @example
+ * ```typescript
+ * const callback: BackgroundTaskCallback = async (ctx) => {
+ *   const connection = await createConnection()
+ *   try {
+ *     while (!ctx.signal.aborted) {
+ *       ctx.reportHealth('Waiting for messages...')
+ *       const message = await connection.receive({ signal: ctx.signal })
+ *       await processMessage(message)
+ *     }
+ *   } finally {
+ *     await connection.close()
+ *   }
+ * }
+ * ```
+ */
+export type BackgroundTaskCallback = (context: BackgroundTaskContext) => Promise<void>
+
+/**
+ * Health status of a background task.
+ */
+export interface BackgroundTaskHealth {
+  /**
+   * Unique task identifier within the extension.
+   */
+  taskId: string
+
+  /**
+   * Human-readable task name.
+   */
+  name: string
+
+  /**
+   * User ID that owns this task.
+   */
+  userId: string
+
+  /**
+   * Current task status.
+   */
+  status: 'pending' | 'running' | 'stopped' | 'failed' | 'restarting'
+
+  /**
+   * Number of times the task has been restarted.
+   */
+  restartCount: number
+
+  /**
+   * Last health status message reported by the task.
+   */
+  lastHealthStatus?: string
+
+  /**
+   * Timestamp of the last health report.
+   */
+  lastHealthTime?: string
+
+  /**
+   * Error message if the task failed.
+   */
+  error?: string
+}
+
+/**
+ * API for managing background workers.
+ * Background workers are long-running tasks that can be automatically restarted.
+ *
+ * @example
+ * ```typescript
+ * const task = await context.backgroundWorkers.start({
+ *   id: 'my-task',
+ *   name: 'My Background Task',
+ *   userId: 'user-123',
+ *   restartPolicy: { type: 'always', maxRestarts: 0 }
+ * }, async (ctx) => {
+ *   while (!ctx.signal.aborted) {
+ *     // Do work...
+ *   }
+ * })
+ *
+ * // Later, to stop the task:
+ * task.dispose()
+ * ```
+ */
+export interface BackgroundWorkersAPI {
+  /**
+   * Start a new background task.
+   *
+   * @param config Task configuration
+   * @param callback Function to execute as the background task
+   * @returns Disposable that stops the task when disposed
+   */
+  start(config: BackgroundTaskConfig, callback: BackgroundTaskCallback): Promise<Disposable>
+
+  /**
+   * Stop a running background task.
+   *
+   * @param taskId The task ID to stop
+   */
+  stop(taskId: string): Promise<void>
+
+  /**
+   * Get the health status of all background tasks for this extension.
+   *
+   * @returns Array of task health statuses
+   */
+  getStatus(): Promise<BackgroundTaskHealth[]>
+}

package/src/types.permissions.ts

@@ -39,6 +39,7 @@ export type CapabilityPermission =
   | 'events.emit'
   | 'scheduler.register'
   | 'chat.message.write'
+  | 'background.workers'
 
 /** System permissions */
 export type SystemPermission =

package/src/types.ts

@@ -95,4 +95,11 @@ export type {
   StorageAPI,
   LogAPI,
   ExtensionModule,
+  // Background workers
+  BackgroundRestartPolicy,
+  BackgroundTaskConfig,
+  BackgroundTaskContext,
+  BackgroundTaskCallback,
+  BackgroundTaskHealth,
+  BackgroundWorkersAPI,
 } from './types.context.js'

package/dist/chunk-WIDGIYRV.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/messages.ts"],"sourcesContent":["/**\n * Message protocol between Extension Host and Extension Workers\n */\n\nimport type {\n  ChatMessage,\n  ChatOptions,\n  GetModelsOptions,\n  StreamEvent,\n  ToolResult,\n  ActionResult,\n  ModelInfo,\n  SchedulerFirePayload,\n} from './types.js'\n\n// ============================================================================\n// Host → Worker Messages\n// ============================================================================\n\nexport type HostToWorkerMessage =\n  | ActivateMessage\n  | DeactivateMessage\n  | SettingsChangedMessage\n  | SchedulerFireMessage\n  | ProviderChatRequestMessage\n  | ProviderModelsRequestMessage\n  | ToolExecuteRequestMessage\n  | ActionExecuteRequestMessage\n  | ResponseMessage\n  | StreamingFetchChunkMessage\n\nexport interface ActivateMessage {\n  type: 'activate'\n  id: string\n  payload: {\n    extensionId: string\n    extensionVersion: string\n    storagePath: string\n    permissions: string[]\n    settings: Record<string, unknown>\n  }\n}\n\nexport interface DeactivateMessage {\n  type: 'deactivate'\n  id: string\n}\n\nexport interface SettingsChangedMessage {\n  type: 'settings-changed'\n  id: string\n  payload: {\n    key: string\n    value: unknown\n  }\n}\n\nexport interface SchedulerFireMessage {\n  type: 'scheduler-fire'\n  id: string\n  payload: SchedulerFirePayload\n}\n\nexport interface ProviderChatRequestMessage {\n  type: 'provider-chat-request'\n  id: string\n  payload: {\n    providerId: string\n    messages: ChatMessage[]\n    options: ChatOptions\n  }\n}\n\nexport interface ProviderModelsRequestMessage {\n  type: 'provider-models-request'\n  id: string\n  payload: {\n    providerId: string\n    options?: GetModelsOptions\n  }\n}\n\nexport interface ToolExecuteRequestMessage {\n  type: 'tool-execute-request'\n  id: string\n  payload: {\n    toolId: string\n    params: Record<string, unknown>\n    /** User ID if the tool is executed in a user context */\n    userId?: string\n  }\n}\n\nexport interface ActionExecuteRequestMessage {\n  type: 'action-execute-request'\n  id: string\n  payload: {\n    actionId: string\n    params: Record<string, unknown>\n    /** User ID if the action is executed in a user context */\n    userId?: string\n  }\n}\n\nexport interface ResponseMessage {\n  type: 'response'\n  id: string\n  payload: {\n    requestId: string\n    success: boolean\n    data?: unknown\n    error?: string\n  }\n}\n\n/**\n * Message sent from host to worker with streaming fetch data chunks.\n * Used for streaming network responses (e.g., NDJSON streams from Ollama).\n */\nexport interface StreamingFetchChunkMessage {\n  type: 'streaming-fetch-chunk'\n  id: string\n  payload: {\n    requestId: string\n    chunk: string\n    done: boolean\n    error?: string\n  }\n}\n\n// ============================================================================\n// Worker → Host Messages\n// ============================================================================\n\nexport type WorkerToHostMessage =\n  | ReadyMessage\n  | RequestMessage\n  | ProviderRegisteredMessage\n  | ToolRegisteredMessage\n  | ActionRegisteredMessage\n  | StreamEventMessage\n  | LogMessage\n  | ProviderModelsResponseMessage\n  | ToolExecuteResponseMessage\n  | ActionExecuteResponseMessage\n  | StreamingFetchAckMessage\n\nexport interface ReadyMessage {\n  type: 'ready'\n}\n\n/**\n * Message sent from worker to host to acknowledge receipt of a streaming fetch chunk.\n * This enables backpressure control to prevent unbounded memory growth.\n */\nexport interface StreamingFetchAckMessage {\n  type: 'streaming-fetch-ack'\n  payload: {\n    requestId: string\n  }\n}\n\nexport interface RequestMessage {\n  type: 'request'\n  id: string\n  method: RequestMethod\n  payload: unknown\n}\n\nexport type RequestMethod =\n  | 'network.fetch'\n  | 'network.fetch-stream'\n  | 'settings.getAll'\n  | 'settings.get'\n  | 'settings.set'\n  | 'user.getProfile'\n  | 'events.emit'\n  | 'scheduler.schedule'\n  | 'scheduler.cancel'\n  | 'chat.appendInstruction'\n  | 'database.execute'\n  | 'storage.get'\n  | 'storage.set'\n  | 'storage.delete'\n  | 'storage.keys'\n  | 'storage.getForUser'\n  | 'storage.setForUser'\n  | 'storage.deleteForUser'\n  | 'storage.keysForUser'\n\nexport interface ProviderRegisteredMessage {\n  type: 'provider-registered'\n  payload: {\n    id: string\n    name: string\n  }\n}\n\nexport interface ToolRegisteredMessage {\n  type: 'tool-registered'\n  payload: {\n    id: string\n    name: string\n    description: string\n    parameters?: Record<string, unknown>\n  }\n}\n\nexport interface ActionRegisteredMessage {\n  type: 'action-registered'\n  payload: {\n    id: string\n  }\n}\n\nexport interface StreamEventMessage {\n  type: 'stream-event'\n  payload: {\n    requestId: string\n    event: StreamEvent\n  }\n}\n\nexport interface ProviderModelsResponseMessage {\n  type: 'provider-models-response'\n  payload: {\n    requestId: string\n    models: ModelInfo[]\n    error?: string\n  }\n}\n\nexport interface ToolExecuteResponseMessage {\n  type: 'tool-execute-response'\n  payload: {\n    requestId: string\n    result: ToolResult\n    error?: string\n  }\n}\n\nexport interface ActionExecuteResponseMessage {\n  type: 'action-execute-response'\n  payload: {\n    requestId: string\n    result: ActionResult\n    error?: string\n  }\n}\n\nexport interface LogMessage {\n  type: 'log'\n  payload: {\n    level: 'debug' | 'info' | 'warn' | 'error'\n    message: string\n    data?: Record<string, unknown>\n  }\n}\n\n// ============================================================================\n// Utility Types\n// ============================================================================\n\nexport interface PendingRequest<T = unknown> {\n  resolve: (value: T) => void\n  reject: (error: Error) => void\n  timeout: ReturnType<typeof setTimeout>\n}\n\n/**\n * Generate a unique message ID\n */\nexport function generateMessageId(): string {\n  return `${Date.now()}-${Math.random().toString(36).slice(2, 11)}`\n}\n"],"mappings":";;;;;;;;AAgRO,SAAS,oBAA4B;AAC1C,SAAO,GAAG,KAAK,IAAI,CAAC,IAAI,KAAK,OAAO,EAAE,SAAS,EAAE,EAAE,MAAM,GAAG,EAAE,CAAC;AACjE;","names":[]}