@stina/extension-api 0.36.0 → 0.44.0

package/dist/{types.tools-BYgcVNP4.d.ts → types.tools-BZQrEs91.d.ts}

@@ -633,6 +633,17 @@ interface ProviderDefinition {
      * to call extension actions (e.g. OAuth, "Test connection").
      */
     configView?: ProviderConfigView;
+    /**
+     * Extra settings shown only for models that report
+     * `capabilities.voiceDuplex` — voice selection, transcription model, and
+     * whatever else is specific to this provider's realtime backend.
+     *
+     * Same DSL and same `$settings.<key>` binding as {@link configView}; the host
+     * renders it in its own section of the model editor and stores the values in
+     * the same settingsOverride. Keep general provider settings in `configView`
+     * so they stay visible for models without voice.
+     */
+    voiceConfigView?: ProviderConfigView;
 }
 /**
  * Component-tree-based configuration view for a provider.
@@ -741,6 +752,21 @@ interface AIProvider {
      * Optional: Generate embeddings
      */
     embed?(texts: string[]): Promise<number[][]>;
+    /**
+     * Optional: Open a duplex voice session for a model that reports
+     * `capabilities.voiceDuplex`.
+     *
+     * The provider is responsible for authenticating with its backend and
+     * returning everything the client needs to connect. Audio flows directly
+     * between the client and the provider — it never passes through Stina — but
+     * the session is configured here, on the server, so the instructions and
+     * tools cannot be tampered with client-side.
+     *
+     * Implementations must not put long-lived credentials in the returned
+     * descriptor. Either complete the handshake here (`webrtc`) or mint a
+     * short-lived secret (`websocket`).
+     */
+    createVoiceSession?(options: VoiceSessionOptions): Promise<VoiceSessionDescriptor>;
 }
 /**
  * Model information
@@ -754,6 +780,104 @@ interface ModelInfo {
     description?: string;
     /** Context window size */
     contextLength?: number;
+    /** What this model can do beyond plain text chat */
+    capabilities?: ModelCapabilities;
+}
+/**
+ * Optional model capabilities.
+ *
+ * Absent or `false` means "not supported" — a provider that says nothing keeps
+ * behaving exactly as before.
+ */
+interface ModelCapabilities {
+    /**
+     * The model can hold a real-time two-way voice conversation, with the user
+     * and the model able to speak at the same time.
+     *
+     * Report this per model *and* per auth mode: the same provider may support
+     * voice with one kind of credential and not another.
+     */
+    voiceDuplex?: boolean;
+}
+/**
+ * How the client wants to connect to the voice session.
+ *
+ * Clients ask for the transport they can actually implement — browsers do
+ * WebRTC, a native app may prefer a plain socket — and providers implement the
+ * ones their backend offers. A provider that is handed a transport it does not
+ * support should throw with a message naming the transports it does.
+ */
+type VoiceTransportRequest = 
+/** Client has created an offer and wants the provider to complete the handshake. */
+{
+    transport: 'webrtc';
+    sdpOffer: string;
+}
+/** Client will open a socket itself and needs a short-lived credential for it. */
+ | {
+    transport: 'websocket';
+};
+/**
+ * Everything the client needs to connect, and nothing it needs to decide.
+ *
+ * `sessionConfig` is the provider-shaped session object (instructions, tools,
+ * voice, transcription). The client forwards it verbatim once the connection is
+ * up — it is a transport, not a decision-maker.
+ */
+type VoiceSessionDescriptor = {
+    transport: 'webrtc';
+    /** Answer to the client's offer. */
+    sdpAnswer: string;
+    sessionConfig: unknown;
+    /** Provider-side ID for the call, useful for logging and teardown. */
+    providerSessionId?: string;
+} | {
+    transport: 'websocket';
+    /** Socket URL to connect to. */
+    url: string;
+    /** Short-lived credential. Must not be a long-lived API key. */
+    clientSecret: string;
+    /** ISO timestamp after which `clientSecret` stops working. */
+    expiresAt: string;
+    sessionConfig: unknown;
+    providerSessionId?: string;
+};
+/**
+ * Options for opening a voice session.
+ *
+ * Mirrors {@link ChatOptions} where it can, so a provider that already
+ * implements `chat` finds the same shapes here.
+ */
+interface VoiceSessionOptions {
+    /** How the client wants to connect */
+    transport: VoiceTransportRequest;
+    /** Model to use — must be one that reported `capabilities.voiceDuplex` */
+    model?: string;
+    /**
+     * System instructions for the session. This is how the assistant keeps her
+     * identity in voice mode; providers must pass it through unchanged.
+     */
+    instructions?: string;
+    /** Tools the model may call during the conversation */
+    tools?: ToolDefinition[];
+    /**
+     * The user's language as an ISO-639-1 code, when known.
+     *
+     * Pass it to the transcription model rather than letting it detect the
+     * language per utterance. Detection is unreliable on short or quiet audio and
+     * fails in a way that looks like nonsense rather than an error — a Swedish
+     * "hej" coming back as Indonesian, for instance.
+     */
+    language?: string;
+    /** Provider-specific settings from model configuration */
+    settings?: Record<string, unknown>;
+    /** Request context (user info, session metadata — not provider config) */
+    context?: {
+        userId?: string;
+        [key: string]: unknown;
+    };
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
 }
 /**
  * Chat message
@@ -1395,6 +1519,78 @@ interface UserAPI {
     getProfile(): Promise<UserProfile>;
     listIds(): Promise<string[]>;
 }
+/**
+ * Visual presentation for a conversation Stina starts proactively in response to
+ * an event reported by an extension.
+ *
+ * The extension owns the *chrome* of the list entry — icon, label, framing,
+ * accent and badge — while Stina authors the *content* (title and opening
+ * message). Every field is optional: omitted fields fall back to sensible
+ * defaults, and `icon` falls back to the reporting extension's manifest icon.
+ *
+ * Colour is intentionally a small set of theme tokens rather than free-form so
+ * the conversation list stays visually coherent across light/dark themes.
+ */
+interface ConversationPresentation {
+    /**
+     * Structural shape of the list entry — *what kind of thing* this is, not how
+     * urgent it is. Urgency is Stina's call alone (see `severityGuidance`).
+     * Defaults to `note`. Each variant renders a different set of fields:
+     * - `note` — icon, title and a two-line preview. The general-purpose default.
+     * - `event` — something happening at a point in time; renders `at` as a time
+     *   block with a countdown. Meetings, reminders, deadlines.
+     * - `message` — something a person or system sent; renders `sender` on its own
+     *   line with the subject as the title. Mail, chat, comments.
+     * - `digest` — several things collected into one entry; renders `items` as a
+     *   short bullet list with a count. Morning briefs, weekly summaries.
+     * - `status` — a transactional outcome; renders `statusLabel` as a pill and no
+     *   preview. Finished builds, deliveries, completed jobs.
+     * - `insight` — Stina's own observation or suggestion rather than an extension's
+     *   report. Rendered in her own voice with a soft accent panel.
+     */
+    variant?: 'note' | 'event' | 'message' | 'digest' | 'status' | 'insight';
+    /**
+     * Leading icon, as a Hugeicons name in lower case with hyphens (`sun-03`,
+     * `cloud-angled-rain`). Hugeicons documents its names in PascalCase; those are
+     * accepted and translated, but the hyphenated form is what the icon set uses.
+     * An unknown name falls back to a default rather than rendering blank.
+     * Falls back to the extension's manifest icon when omitted.
+     */
+    icon?: HugeIconName;
+    /** Small eyebrow label above the content, e.g. "Mail" or "Reminder". */
+    label?: LocalizedString;
+    /** Accent colour as a theme token. Defaults to `default`. */
+    accent?: 'default' | 'info' | 'warning' | 'success' | 'danger';
+    /** Optional short badge, e.g. the account a mail arrived in. */
+    badge?: LocalizedString;
+    /**
+     * When the event happens (ISO 8601). Only used by `variant: 'event'`, which
+     * renders it as a time block and derives a relative countdown from it.
+     */
+    at?: string;
+    /** Who sent it. Only used by `variant: 'message'`. */
+    sender?: LocalizedString;
+    /**
+     * The collected items. Only used by `variant: 'digest'`; at most three are
+     * rendered, and `count` reports the true total when there are more.
+     */
+    items?: LocalizedString[];
+    /** Total number of collected items, when it exceeds what `items` lists. */
+    count?: number;
+    /** Short outcome label for the pill, e.g. "Delivered". Only used by `variant: 'status'`. */
+    statusLabel?: LocalizedString;
+    /**
+     * Guidance to Stina on how to judge how much this deserves the user's attention
+     * — *not* a severity value. Extensions describe what would make an event
+     * important ("urgent when the sender is on the user's team, or the deadline is
+     * today"); Stina weighs that against everything else she knows and picks the
+     * level herself. She may disregard it entirely.
+     *
+     * Plain text in any language, one or two sentences. It is shown to Stina during
+     * her deliberation and never to the user.
+     */
+    severityGuidance?: string;
+}
 /**
  * Chat instruction message
  */
@@ -1402,6 +1598,24 @@ interface ChatInstructionMessage {
     text: string;
     conversationId?: string;
     userId?: string;
+    /**
+     * When true, the message is treated as a system event reported by the extension
+     * rather than a plain instruction. Instead of being appended to a conversation,
+     * Stina runs a hidden deliberation over it and decides herself whether to notify
+     * the user (by starting a new conversation via the `core_init_chat_session` tool).
+     */
+    deliberate?: boolean;
+    /**
+     * Identifier of the source that reported the event (typically the extension id).
+     * Used for logging/tracing of proactive decisions.
+     */
+    source?: string;
+    /**
+     * Optional visual presentation for the conversation Stina may start from this
+     * event. Only meaningful together with `deliberate: true`; ignored if Stina
+     * decides not to notify the user.
+     */
+    presentation?: ConversationPresentation;
 }
 /**
  * Chat API for appending instructions
@@ -1434,11 +1648,14 @@ interface ExtensionModule {
 /**
  * Restart policy for background tasks.
  * Controls how tasks are restarted after failures.
+ *
+ * A task that returns from its callback without having been aborted is
+ * considered finished on purpose and is never restarted, regardless of policy.
  */
 interface BackgroundRestartPolicy {
     /**
      * When to restart the task:
-     * - 'always': Always restart, regardless of exit reason
+     * - 'always': Restart if the task threw, or stopped without anyone asking it to
      * - 'on-failure': Only restart if the task threw an error
      * - 'never': Never restart automatically
      */
@@ -1519,6 +1736,11 @@ interface BackgroundTaskContext extends ExecutionContext {
  * Callback function for background tasks.
  * The function should run until the signal is aborted, then clean up and return.
  *
+ * Returning before the signal is aborted means the task has finished on purpose:
+ * it is marked as completed and is not restarted, whatever the restart policy says.
+ * A task that has nothing to do right now but wants to be retried later should
+ * therefore keep running (and wait on the signal) rather than return early.
+ *
  * @example
  * ```typescript
  * const callback: BackgroundTaskCallback = async (ctx) => {
@@ -1554,8 +1776,10 @@ interface BackgroundTaskHealth {
     userId: string;
     /**
      * Current task status.
+     * 'completed' means the task returned on its own and will not be restarted,
+     * while 'stopped' means someone asked it to stop.
      */
-    status: 'pending' | 'running' | 'stopped' | 'failed' | 'restarting';
+    status: 'pending' | 'running' | 'stopped' | 'completed' | 'failed' | 'restarting';
     /**
      * Number of times the task has been restarted.
      */
@@ -1681,4 +1905,4 @@ interface ActionResult {
     error?: string;
 }
 
-export { type StorageAPI as $, type ActionResult as A, type SchedulerAPI as B, type ChatMessage as C, type Disposable as D, type ExtensionContributions as E, type SchedulerJobRequest as F, type GetModelsOptions as G, type SchedulerSchedule as H, type UserProfile as I, type ChatAPI as J, type ChatInstructionMessage as K, type LocalizedString as L, type ModelInfo as M, type NetworkAPI as N, type LogAPI as O, type PanelDefinition as P, type BackgroundWorkersAPI as Q, type BackgroundTaskConfig as R, type SchedulerFirePayload as S, type ToolResult as T, type UserAPI as U, type BackgroundTaskCallback as V, type BackgroundTaskContext as W, type BackgroundTaskHealth as X, type BackgroundRestartPolicy as Y, type Query as Z, type QueryOptions as _, type ChatOptions as a, type SecretsAPI as a0, type StorageCollectionConfig as a1, type StorageContributions as a2, type AIProvider as a3, type ToolCall as a4, type Tool as a5, type Action as a6, type ExtensionModule as a7, type HugeIconName as a8, type AllowedCSSProperty as a9, type PanelAction as aA, type PanelProps as aB, type ToggleProps as aC, type CollapsibleProps as aD, type FrameVariant as aE, type FrameProps as aF, type ListProps as aG, type PillVariant as aH, type PillProps as aI, type CheckboxProps as aJ, type MarkdownProps as aK, type TextPreviewProps as aL, type ModalProps as aM, type ConditionalGroupProps as aN, type ExecutionContext as aO, type ExtensionComponentStyle as aa, type ExtensionComponentData as ab, type ExtensionComponentIterator as ac, type ExtensionComponentChildren as ad, type ExtensionActionCall as ae, type ExtensionActionRef as af, type ExtensionDataSource as ag, type ExtensionPanelDefinition as ah, type HeaderProps as ai, type LabelProps as aj, type ParagraphProps as ak, type ButtonProps as al, type TextInputProps as am, type PasswordInputProps as an, type NumberInputProps as ao, type TextAreaProps as ap, type DateTimeInputProps as aq, type SelectProps as ar, type IconPickerProps as as, type VerticalStackProps as at, type HorizontalStackProps as au, type GridProps as av, type DividerProps as aw, type IconProps as ax, type IconButtonType as ay, type IconButtonProps as az, type StreamEvent as b, type ToolSettingsViewDefinition as c, type ToolSettingsView as d, type ToolSettingsListView as e, type ToolSettingsListMapping as f, type ToolSettingsComponentView as g, type ToolSettingsActionDataSource as h, type PanelView as i, type PanelComponentView as j, type PanelActionDataSource as k, type PanelUnknownView as l, type ProviderDefinition as m, type ProviderConfigView as n, type PromptContribution as o, type PromptSection as p, type ToolDefinition as q, resolveLocalizedString as r, type ToolConfirmationConfig as s, type CommandDefinition as t, type ExtensionContext as u, type SettingsAPI as v, type ProvidersAPI as w, type ToolsAPI as x, type ActionsAPI as y, type EventsAPI as z };
+export { type BackgroundTaskHealth as $, type ActionResult as A, type EventsAPI as B, type ChatMessage as C, type Disposable as D, type ExtensionContributions as E, type SchedulerAPI as F, type GetModelsOptions as G, type HugeIconName as H, type SchedulerJobRequest as I, type SchedulerSchedule as J, type UserProfile as K, type LocalizedString as L, type ModelInfo as M, type NetworkAPI as N, type ChatAPI as O, type PanelDefinition as P, type ChatInstructionMessage as Q, type ConversationPresentation as R, type SchedulerFirePayload as S, type ToolResult as T, type UserAPI as U, type VoiceSessionOptions as V, type LogAPI as W, type BackgroundWorkersAPI as X, type BackgroundTaskConfig as Y, type BackgroundTaskCallback as Z, type BackgroundTaskContext as _, type ChatOptions as a, type BackgroundRestartPolicy as a0, type Query as a1, type QueryOptions as a2, type StorageAPI as a3, type SecretsAPI as a4, type StorageCollectionConfig as a5, type StorageContributions as a6, type AIProvider as a7, type ModelCapabilities as a8, type ToolCall as a9, type GridProps as aA, type DividerProps as aB, type IconProps as aC, type IconButtonType as aD, type IconButtonProps as aE, type PanelAction as aF, type PanelProps as aG, type ToggleProps as aH, type CollapsibleProps as aI, type FrameVariant as aJ, type FrameProps as aK, type ListProps as aL, type PillVariant as aM, type PillProps as aN, type CheckboxProps as aO, type MarkdownProps as aP, type TextPreviewProps as aQ, type ModalProps as aR, type ConditionalGroupProps as aS, type ExecutionContext as aT, type VoiceTransportRequest as aa, type Tool as ab, type Action as ac, type ExtensionModule as ad, type AllowedCSSProperty as ae, type ExtensionComponentStyle as af, type ExtensionComponentData as ag, type ExtensionComponentIterator as ah, type ExtensionComponentChildren as ai, type ExtensionActionCall as aj, type ExtensionActionRef as ak, type ExtensionDataSource as al, type ExtensionPanelDefinition as am, type HeaderProps as an, type LabelProps as ao, type ParagraphProps as ap, type ButtonProps as aq, type TextInputProps as ar, type PasswordInputProps as as, type NumberInputProps as at, type TextAreaProps as au, type DateTimeInputProps as av, type SelectProps as aw, type IconPickerProps as ax, type VerticalStackProps as ay, type HorizontalStackProps as az, type StreamEvent as b, type VoiceSessionDescriptor as c, type ToolSettingsViewDefinition as d, type ToolSettingsView as e, type ToolSettingsListView as f, type ToolSettingsListMapping as g, type ToolSettingsComponentView as h, type ToolSettingsActionDataSource as i, type PanelView as j, type PanelComponentView as k, type PanelActionDataSource as l, type PanelUnknownView as m, type ProviderDefinition as n, type ProviderConfigView as o, type PromptContribution as p, type PromptSection as q, resolveLocalizedString as r, type ToolDefinition as s, type ToolConfirmationConfig as t, type CommandDefinition as u, type ExtensionContext as v, type SettingsAPI as w, type ProvidersAPI as x, type ToolsAPI as y, type ActionsAPI as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stina/extension-api",
-  "version": "0.36.0",
+  "version": "0.44.0",
   "private": false,
   "repository": {
     "type": "git",

package/schema/extension-manifest.schema.json

@@ -30,6 +30,10 @@
           "minLength": 1,
           "description": "Short description"
         },
+        "icon": {
+          "type": "string",
+          "description": "Icon (Hugeicons name) representing the extension"
+        },
         "author": {
           "type": "object",
           "properties": {

package/src/background.test.ts

@@ -185,7 +185,8 @@ describe('WorkerBackgroundTaskManager', () => {
 
       expect(callback).toHaveBeenCalledTimes(1)
       expect(sendTaskStatus).toHaveBeenCalledWith('task-1', 'running')
-      expect(sendTaskStatus).toHaveBeenCalledWith('task-1', 'stopped')
+      expect(sendTaskStatus).toHaveBeenCalledWith('task-1', 'completed')
+      expect(sendTaskStatus).not.toHaveBeenCalledWith('task-1', 'stopped')
     })
 
     it('should abort previous execution if already running', async () => {
@@ -498,7 +499,7 @@ describe('WorkerBackgroundTaskManager', () => {
       expect(disposed).toBe(true)
     })
 
-    it('should handle stop before task starts', async () => {
+    it('should run a task that was stopped before it started', async () => {
       const config: BackgroundTaskConfig = {
         id: 'task-1',
         name: 'Test Task',
@@ -512,12 +513,12 @@ describe('WorkerBackgroundTaskManager', () => {
       manager.stop('task-1')
       sendTaskStatus.mockClear()
 
-      // Now start it
+      // Now start it - handleStart creates a fresh AbortController, so the
+      // earlier stop does not carry over into this run
       await manager.handleStart('task-1')
 
-      // Should immediately detect it's aborted
       expect(sendTaskStatus).toHaveBeenCalledWith('task-1', 'running')
-      expect(sendTaskStatus).toHaveBeenCalledWith('task-1', 'stopped')
+      expect(sendTaskStatus).toHaveBeenCalledWith('task-1', 'completed')
     })
 
     it('should handle multiple rapid start/stop cycles', async () => {

package/src/background.ts

@@ -27,7 +27,7 @@ interface RegisteredTask {
   config: BackgroundTaskConfig
   callback: BackgroundTaskCallback
   abortController: AbortController | null
-  status: 'pending' | 'running' | 'stopped' | 'failed'
+  status: 'pending' | 'running' | 'stopped' | 'completed' | 'failed'
   lastHealthStatus?: string
   lastHealthTime?: string
   error?: string
@@ -49,7 +49,11 @@ export interface WorkerBackgroundTaskManagerOptions {
     payload?: Record<string, unknown>
   ) => void
   /** Send status update to host */
-  sendTaskStatus: (taskId: string, status: 'running' | 'stopped' | 'failed', error?: string) => void
+  sendTaskStatus: (
+    taskId: string,
+    status: 'running' | 'stopped' | 'completed' | 'failed',
+    error?: string
+  ) => void
   /** Send health report to host */
   sendHealthReport: (taskId: string, status: string, timestamp: string) => void
   /** Create a log API for a task */
@@ -156,8 +160,11 @@ export class WorkerBackgroundTaskManager {
       task.abortController = null
     }
 
-    // Create new AbortController for this run
-    task.abortController = new AbortController()
+    // Create new AbortController for this run.
+    // Keep a local reference: stop() clears the field, so it cannot be used
+    // afterwards to tell an aborted run from one that returned on its own.
+    const abortController = new AbortController()
+    task.abortController = abortController
     task.status = 'running'
     task.error = undefined
 
@@ -171,14 +178,14 @@ export class WorkerBackgroundTaskManager {
       // Execute the callback
       await task.callback(context)
 
-      // Task completed normally (or was aborted)
-      if (task.abortController?.signal.aborted) {
+      if (abortController.signal.aborted) {
+        // The run was aborted - stop() has already reported the status
         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')
+        // The callback returned on its own: the task is done and must not be
+        // restarted, or a task with nothing to do would loop forever
+        task.status = 'completed'
+        this.options.sendTaskStatus(taskId, 'completed')
       }
     } catch (error) {
       // Task failed with an error

package/src/index.ts

@@ -61,6 +61,7 @@ export type {
   UserProfile,
   ChatAPI,
   ChatInstructionMessage,
+  ConversationPresentation,
   LogAPI,
 
   // Background workers
@@ -82,12 +83,18 @@ export type {
   // AI Provider
   AIProvider,
   ModelInfo,
+  ModelCapabilities,
   ChatMessage,
   ChatOptions,
   GetModelsOptions,
   StreamEvent,
   ToolCall,
 
+  // Duplex voice
+  VoiceSessionOptions,
+  VoiceSessionDescriptor,
+  VoiceTransportRequest,
+
   // Tools
   Tool,
   ToolResult,

package/src/messages.ts

@@ -11,6 +11,8 @@ import type {
   ActionResult,
   ModelInfo,
   SchedulerFirePayload,
+  VoiceSessionOptions,
+  VoiceSessionDescriptor,
 } from './types.js'
 
 // ============================================================================
@@ -24,6 +26,7 @@ export type HostToWorkerMessage =
   | SchedulerFireMessage
   | ProviderChatRequestMessage
   | ProviderModelsRequestMessage
+  | ProviderVoiceSessionRequestMessage
   | ToolExecuteRequestMessage
   | ActionExecuteRequestMessage
   | ResponseMessage
@@ -82,6 +85,20 @@ export interface ProviderModelsRequestMessage {
   }
 }
 
+export interface ProviderVoiceSessionRequestMessage {
+  type: 'provider-voice-session-request'
+  id: string
+  payload: {
+    providerId: string
+    /**
+     * `signal` is dropped on the way across: an AbortSignal cannot be
+     * structured-cloned into a worker. Cancellation is handled by the host
+     * rejecting the pending request instead.
+     */
+    options: Omit<VoiceSessionOptions, 'signal'>
+  }
+}
+
 export interface ToolExecuteRequestMessage {
   type: 'tool-execute-request'
   id: string
@@ -165,6 +182,7 @@ export type WorkerToHostMessage =
   | StreamEventMessage
   | LogMessage
   | ProviderModelsResponseMessage
+  | ProviderVoiceSessionResponseMessage
   | ToolExecuteResponseMessage
   | ActionExecuteResponseMessage
   | StreamingFetchAckMessage
@@ -289,6 +307,16 @@ export interface ProviderModelsResponseMessage {
   }
 }
 
+export interface ProviderVoiceSessionResponseMessage {
+  type: 'provider-voice-session-response'
+  payload: {
+    requestId: string
+    /** Absent when `error` is set. */
+    descriptor?: VoiceSessionDescriptor
+    error?: string
+  }
+}
+
 export interface ToolExecuteResponseMessage {
   type: 'tool-execute-response'
   payload: {
@@ -343,7 +371,7 @@ export interface BackgroundTaskStatusMessage {
   type: 'background-task-status'
   payload: {
     taskId: string
-    status: 'running' | 'stopped' | 'failed'
+    status: 'running' | 'stopped' | 'completed' | 'failed'
     error?: string
   }
 }

package/src/runtime.ts

@@ -34,6 +34,7 @@ import type {
   ChatMessage,
   ChatOptions,
   GetModelsOptions,
+  VoiceSessionOptions,
   BackgroundWorkersAPI,
   BackgroundTaskConfig,
   BackgroundTaskCallback,
@@ -190,6 +191,10 @@ async function handleHostMessage(message: HostToWorkerMessage): Promise<void> {
       await handleProviderModelsRequest(message.id, message.payload)
       break
 
+    case 'provider-voice-session-request':
+      await handleProviderVoiceSessionRequest(message.id, message.payload)
+      break
+
     case 'tool-execute-request':
       await handleToolExecuteRequest(message.id, message.payload)
       break
@@ -488,6 +493,37 @@ async function handleProviderModelsRequest(
   }
 }
 
+async function handleProviderVoiceSessionRequest(
+  requestId: string,
+  payload: { providerId: string; options: VoiceSessionOptions }
+): Promise<void> {
+  const respond = (error: string) =>
+    postMessage({ type: 'provider-voice-session-response', payload: { requestId, error } })
+
+  const provider = registeredProviders.get(payload.providerId)
+  if (!provider) {
+    respond(`Provider ${payload.providerId} not found`)
+    return
+  }
+
+  /*
+   * Voice is opt-in per provider, so a missing method is an ordinary outcome
+   * rather than a crash. Name the provider — the caller only knows it asked for
+   * a model, and a bare "not supported" leaves it guessing which part refused.
+   */
+  if (!provider.createVoiceSession) {
+    respond(`Provider ${payload.providerId} does not support voice sessions`)
+    return
+  }
+
+  try {
+    const descriptor = await provider.createVoiceSession(payload.options)
+    postMessage({ type: 'provider-voice-session-response', payload: { requestId, descriptor } })
+  } catch (error) {
+    respond(error instanceof Error ? error.message : String(error))
+  }
+}
+
 async function handleToolExecuteRequest(
   requestId: string,
   payload: { toolId: string; params: Record<string, unknown>; userId?: string }
@@ -967,6 +1003,10 @@ export type {
   ChatMessage,
   ChatOptions,
   GetModelsOptions,
+  ModelCapabilities,
+  VoiceSessionOptions,
+  VoiceSessionDescriptor,
+  VoiceTransportRequest,
   StreamEvent,
   // Storage and secrets
   StorageAPI,

package/src/schemas/manifest.schema.ts

@@ -50,6 +50,10 @@ export const ExtensionManifestSchema = z
       .regex(/^\d+\.\d+\.\d+/, 'Must be semver format (e.g., "1.0.0")')
       .describe('Version string (semver)'),
     description: z.string().min(1).describe('Short description'),
+    // Optional icon (Hugeicons name) used as the default icon for proactive
+    // conversation list entries this extension triggers. Kept optional so the
+    // field is preserved (not stripped) when a manifest is parsed at load time.
+    icon: z.string().optional().describe('Icon (Hugeicons name) representing the extension'),
     author: AuthorSchema.describe('Author information'),
     repository: z.string().url().optional().describe('Repository URL'),
     license: z.string().optional().describe('License identifier'),