@stina/extension-api 0.36.0 → 0.44.0

package/src/types.context.ts

@@ -8,6 +8,8 @@ import type { AIProvider } from './types.provider.js'
 import type { Tool, ToolResult, Action } from './types.tools.js'
 import type { ToolDefinition } from './types.contributions.js'
 import type { StorageAPI, SecretsAPI } from './types.storage.js'
+import type { LocalizedString } from './types.localization.js'
+import type { HugeIconName } from './types.components.js'
 
 /**
  * Disposable resource that can be cleaned up
@@ -322,6 +324,79 @@ export interface UserAPI {
   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.
+ */
+export 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
  */
@@ -329,6 +404,24 @@ export 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
 }
 
 /**
@@ -371,11 +464,14 @@ export 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.
  */
 export 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
    */
@@ -469,6 +565,11 @@ export 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) => {
@@ -508,8 +609,10 @@ export interface BackgroundTaskHealth {
 
   /**
    * 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.

package/src/types.contributions.ts

@@ -234,6 +234,17 @@ export 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
 }
 
 /**

package/src/types.manifest.ts

@@ -6,6 +6,7 @@
 
 import type { Permission } from './types.permissions.js'
 import type { ExtensionContributions } from './types.contributions.js'
+import type { HugeIconName } from './types.components.js'
 
 /**
  * Extension manifest format (manifest.json)
@@ -19,6 +20,12 @@ export interface ExtensionManifest {
   version: string
   /** Short description */
   description: string
+  /**
+   * Optional icon (Hugeicons name) representing the extension. Used as the default
+   * icon for proactive conversation list entries this extension triggers, and as a
+   * general visual identity for the extension in the UI.
+   */
+  icon?: HugeIconName
   /** Author information */
   author: {
     name: string

package/src/types.provider.ts

@@ -33,6 +33,22 @@ export 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>
 }
 
 /**
@@ -47,6 +63,102 @@ export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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
 }
 
 /**

package/src/types.ts

@@ -55,11 +55,15 @@ export type { ExtensionManifest, Platform } from './types.manifest.js'
 export type {
   AIProvider,
   ModelInfo,
+  ModelCapabilities,
   ChatMessage,
   ToolCall,
   ChatOptions,
   GetModelsOptions,
   StreamEvent,
+  VoiceSessionOptions,
+  VoiceSessionDescriptor,
+  VoiceTransportRequest,
 } from './types.provider.js'
 
 // Tools and Actions
@@ -83,6 +87,7 @@ export type {
   UserProfile,
   UserAPI,
   ChatInstructionMessage,
+  ConversationPresentation,
   ChatAPI,
   LogAPI,
   ExtensionModule,

package/dist/chunk-K53YNG2W.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  | BackgroundTaskStartMessage\n  | BackgroundTaskStopMessage\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 * Message sent from host to worker to start a registered background task.\n */\nexport interface BackgroundTaskStartMessage {\n  type: 'background-task-start'\n  id: string\n  payload: {\n    taskId: string\n  }\n}\n\n/**\n * Message sent from host to worker to stop a running background task.\n */\nexport interface BackgroundTaskStopMessage {\n  type: 'background-task-stop'\n  id: string\n  payload: {\n    taskId: 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  | BackgroundTaskRegisteredMessage\n  | BackgroundTaskStatusMessage\n  | BackgroundTaskHealthMessage\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  | 'user.listIds'\n  | 'events.emit'\n  | 'scheduler.schedule'\n  | 'scheduler.cancel'\n  | 'scheduler.reportFireResult'\n  | 'chat.appendInstruction'\n  | 'database.execute'\n  // Simple key-value storage methods\n  | 'storage.set'\n  | 'storage.keys'\n  | 'storage.setForUser'\n  | 'storage.keysForUser'\n  // Collection-based storage methods\n  | 'storage.put'\n  | 'storage.get'\n  | 'storage.delete'\n  | 'storage.find'\n  | 'storage.findOne'\n  | 'storage.count'\n  | 'storage.putMany'\n  | 'storage.deleteMany'\n  | 'storage.dropCollection'\n  | 'storage.listCollections'\n  | 'storage.putForUser'\n  | 'storage.getForUser'\n  | 'storage.deleteForUser'\n  | 'storage.findForUser'\n  | 'storage.findOneForUser'\n  | 'storage.countForUser'\n  | 'storage.putManyForUser'\n  | 'storage.deleteManyForUser'\n  | 'storage.dropCollectionForUser'\n  | 'storage.listCollectionsForUser'\n  // Secrets methods\n  | 'secrets.set'\n  | 'secrets.get'\n  | 'secrets.delete'\n  | 'secrets.list'\n  | 'secrets.setForUser'\n  | 'secrets.getForUser'\n  | 'secrets.deleteForUser'\n  | 'secrets.listForUser'\n  // Tools cross-extension methods\n  | 'tools.list'\n  | 'tools.execute'\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 * Message sent from worker to host when a background task is registered.\n */\nexport interface BackgroundTaskRegisteredMessage {\n  type: 'background-task-registered'\n  payload: {\n    taskId: string\n    name: string\n    userId: string\n    restartPolicy: {\n      type: 'always' | 'on-failure' | 'never'\n      maxRestarts?: number\n      initialDelayMs?: number\n      maxDelayMs?: number\n      backoffMultiplier?: number\n    }\n    payload?: Record<string, unknown>\n  }\n}\n\n/**\n * Message sent from worker to host with background task status updates.\n */\nexport interface BackgroundTaskStatusMessage {\n  type: 'background-task-status'\n  payload: {\n    taskId: string\n    status: 'running' | 'stopped' | 'failed'\n    error?: string\n  }\n}\n\n/**\n * Message sent from worker to host with background task health reports.\n */\nexport interface BackgroundTaskHealthMessage {\n  type: 'background-task-health'\n  payload: {\n    taskId: string\n    status: string\n    timestamp: string\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":";AAuXO,SAAS,oBAA4B;AAC1C,SAAO,GAAG,KAAK,IAAI,CAAC,IAAI,KAAK,OAAO,EAAE,SAAS,EAAE,EAAE,MAAM,GAAG,EAAE,CAAC;AACjE;","names":[]}