@stina/extension-api 0.36.0 → 0.51.0

package/dist/{types.tools-BYgcVNP4.d.cts → types.tools-XpXCoPrJ.d.cts}

@@ -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,113 @@ 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;
+    /**
+     * The model can be shown images alongside the text of a message.
+     *
+     * Report this per model *and* per auth mode, like `voiceDuplex`: the same
+     * provider often serves both a vision model and a text-only one, and a picture
+     * sent to the latter is at best ignored and at worst an error mid-conversation.
+     * Stina uses it to decide whether the paperclip is offered at all.
+     */
+    vision?: 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
@@ -761,11 +894,37 @@ interface ModelInfo {
 interface ChatMessage {
     role: 'user' | 'assistant' | 'system' | 'tool';
     content: string;
+    /**
+     * Images the user attached to this message, already decoded and ready to send.
+     *
+     * Additive: a provider that ignores the field behaves exactly as it did before,
+     * which is why the text is still in `content` rather than being moved into a
+     * parts array. A provider that supports vision should report
+     * `capabilities.vision` and fold these into whatever multimodal shape its API
+     * expects.
+     *
+     * Only ever `image/jpeg` or `image/png` — see `ChatAttachmentDTO` for why.
+     */
+    images?: ChatImage[];
     /** For assistant messages: tool calls made by the model */
     tool_calls?: ToolCall[];
     /** For tool messages: the ID of the tool call this is a response to */
     tool_call_id?: string;
 }
+/**
+ * One image on a chat message, carried as bytes rather than as a URL.
+ *
+ * A URL would have to be reachable *from the provider*, and Stina commonly runs
+ * on a home server talking to a model on the same LAN or on the machine next to
+ * it. There is no address that is both private enough and reachable enough, so
+ * the bytes travel with the request.
+ */
+interface ChatImage {
+    /** `image/jpeg` or `image/png`. */
+    mime: string;
+    /** The image itself, base64 with no data-URI prefix. */
+    data: string;
+}
 /**
  * A tool call made by the model
  */
@@ -1395,6 +1554,97 @@ 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.
+     *
+     * The variant also picks how the entry is decorated, so that two kinds of card
+     * never resolve to the same picture: `note`, `message` and `status` are drawn
+     * light, on an accent rail, while `event`, `digest` and `insight` sit on a
+     * filled plate. Severity governs how strongly that decoration is drawn, never
+     * which of the two it is.
+     */
+    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 domain the message came from, which lets the list show the sender's own
+     * icon in place of their initials. Only used by `variant: 'message'`.
+     *
+     * Report it in whatever form you hold it — `plex.tv`, `no-reply@plex.tv`, or
+     * `Plex <no-reply@plex.tv>` all work, and the domain is taken out and
+     * normalised for you. Never localised: it is an identifier, not a label.
+     *
+     * Stina fetches the icon herself, from her own server, and caches it. Nothing
+     * about the message is sent anywhere, and no third-party icon service is
+     * consulted; a domain that has no icon simply falls back to the initials.
+     */
+    senderDomain?: string;
+    /**
+     * 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 +1652,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 +1702,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 +1790,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 +1830,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 +1959,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 ChatImage as a9, type HorizontalStackProps as aA, type GridProps as aB, type DividerProps as aC, type IconProps as aD, type IconButtonType as aE, type IconButtonProps as aF, type PanelAction as aG, type PanelProps as aH, type ToggleProps as aI, type CollapsibleProps as aJ, type FrameVariant as aK, type FrameProps as aL, type ListProps as aM, type PillVariant as aN, type PillProps as aO, type CheckboxProps as aP, type MarkdownProps as aQ, type TextPreviewProps as aR, type ModalProps as aS, type ConditionalGroupProps as aT, type ExecutionContext as aU, type ToolCall as aa, type VoiceTransportRequest as ab, type Tool as ac, type Action as ad, type ExtensionModule as ae, type AllowedCSSProperty as af, type ExtensionComponentStyle as ag, type ExtensionComponentData as ah, type ExtensionComponentIterator as ai, type ExtensionComponentChildren as aj, type ExtensionActionCall as ak, type ExtensionActionRef as al, type ExtensionDataSource as am, type ExtensionPanelDefinition as an, type HeaderProps as ao, type LabelProps as ap, type ParagraphProps as aq, type ButtonProps as ar, type TextInputProps as as, type PasswordInputProps as at, type NumberInputProps as au, type TextAreaProps as av, type DateTimeInputProps as aw, type SelectProps as ax, type IconPickerProps as ay, type VerticalStackProps 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 };