@stina/extension-api 0.19.1 → 0.21.0

package/dist/{types-CvfONPis.d.ts → types.tools-BQrCW_wq.d.ts}

@@ -1,3 +1,31 @@
+/**
+ * Localization Types
+ *
+ * Types and utilities for localized strings in extensions.
+ */
+/**
+ * A string that can be either a simple string or a map of language codes to localized strings.
+ * When a simple string is provided, it's used as the default/fallback value.
+ * When a map is provided, the appropriate language is selected at runtime.
+ *
+ * @example
+ * // Simple string (backwards compatible)
+ * name: "Get Weather"
+ *
+ * @example
+ * // Localized strings
+ * name: { en: "Get Weather", sv: "Hämta väder", de: "Wetter abrufen" }
+ */
+type LocalizedString = string | Record<string, string>;
+/**
+ * Resolves a LocalizedString to an actual string value.
+ * @param value The LocalizedString to resolve
+ * @param lang The preferred language code (e.g., "sv", "en")
+ * @param fallbackLang The fallback language code (defaults to "en")
+ * @returns The resolved string value
+ */
+declare function resolveLocalizedString(value: LocalizedString, lang: string, fallbackLang?: string): string;
+
 /**
  * Allowed CSS property names for extension component styling.
  * Only safe properties that cannot be used for UI spoofing,
@@ -306,64 +334,33 @@ interface ModalProps extends ExtensionComponentData {
     /** Action to call when the modal is closed. */
     onCloseAction?: ExtensionActionRef;
 }
-
 /**
- * A string that can be either a simple string or a map of language codes to localized strings.
- * When a simple string is provided, it's used as the default/fallback value.
- * When a map is provided, the appropriate language is selected at runtime.
- *
- * @example
- * // Simple string (backwards compatible)
- * name: "Get Weather"
- *
- * @example
- * // Localized strings
- * name: { en: "Get Weather", sv: "Hämta väder", de: "Wetter abrufen" }
+ * The extension API properties for the ConditionalGroup component.
+ * Renders children only when the condition evaluates to true.
  */
-type LocalizedString = string | Record<string, string>;
-/**
- * Resolves a LocalizedString to an actual string value.
- * @param value The LocalizedString to resolve
- * @param lang The preferred language code (e.g., "sv", "en")
- * @param fallbackLang The fallback language code (defaults to "en")
- * @returns The resolved string value
- */
-declare function resolveLocalizedString(value: LocalizedString, lang: string, fallbackLang?: string): string;
+interface ConditionalGroupProps extends ExtensionComponentData {
+    component: 'ConditionalGroup';
+    /**
+     * Condition expression to evaluate.
+     * Supports:
+     * - Comparison: ==, !=
+     * - Logical: && (and), || (or)
+     * - Values: $references, 'strings', numbers, true, false, null
+     *
+     * @example "$form.provider == 'imap'"
+     * @example "$form.provider == 'gmail' || $form.provider == 'outlook'"
+     */
+    condition: string;
+    /** Children to render when condition is true. */
+    children: ExtensionComponentChildren;
+}
+
 /**
- * Extension manifest format (manifest.json)
+ * Contribution Types
+ *
+ * Types for extension contributions: settings, panels, providers, tools, commands, prompts.
  */
-interface ExtensionManifest {
-    /** Unique identifier (e.g., "ollama-provider") */
-    id: string;
-    /** Human-readable name */
-    name: string;
-    /** Version string (semver) */
-    version: string;
-    /** Short description */
-    description: string;
-    /** Author information */
-    author: {
-        name: string;
-        url?: string;
-    };
-    /** Repository URL */
-    repository?: string;
-    /** License identifier */
-    license?: string;
-    /** Minimum Stina version required */
-    engines?: {
-        stina: string;
-    };
-    /** Supported platforms */
-    platforms?: Platform[];
-    /** Entry point file (relative to extension root) */
-    main: string;
-    /** Required permissions */
-    permissions: Permission[];
-    /** What the extension contributes */
-    contributes?: ExtensionContributions;
-}
-type Platform = 'web' | 'electron' | 'tui';
+
 /**
  * What an extension can contribute to Stina
  */
@@ -595,21 +592,6 @@ interface ProviderDefinition {
     /** Schema for provider-specific configuration UI */
     configSchema?: ProviderConfigSchema;
 }
-type PromptSection = 'system' | 'behavior' | 'tools';
-interface PromptContribution {
-    /** Unique ID within the extension */
-    id: string;
-    /** Optional title for the prompt chunk */
-    title?: string;
-    /** Prompt section placement */
-    section?: PromptSection;
-    /** Plain text prompt content */
-    text?: string;
-    /** Optional localized prompt content (keyed by locale, e.g. "en", "sv") */
-    i18n?: Record<string, string>;
-    /** Optional ordering hint (lower comes first) */
-    order?: number;
-}
 /**
  * Schema for provider-specific configuration.
  * Used to generate UI forms for configuring provider settings.
@@ -704,17 +686,145 @@ interface CommandDefinition {
     /** Description */
     description: string;
 }
-type Permission = NetworkPermission | StoragePermission | UserDataPermission | CapabilityPermission | SystemPermission;
-/** Network access permissions */
-type NetworkPermission = 'network:*' | `network:localhost` | `network:localhost:${number}` | `network:${string}`;
-/** Storage permissions */
-type StoragePermission = 'database.own' | 'storage.local';
-/** User data permissions */
-type UserDataPermission = 'user.profile.read' | 'user.location.read' | 'chat.history.read' | 'chat.current.read';
-/** Capability permissions */
-type CapabilityPermission = 'provider.register' | 'tools.register' | 'actions.register' | 'settings.register' | 'commands.register' | 'panels.register' | 'events.emit' | 'scheduler.register' | 'chat.message.write';
-/** System permissions */
-type SystemPermission = 'files.read' | 'files.write' | 'clipboard.read' | 'clipboard.write';
+type PromptSection = 'system' | 'behavior' | 'tools';
+interface PromptContribution {
+    /** Unique ID within the extension */
+    id: string;
+    /** Optional title for the prompt chunk */
+    title?: string;
+    /** Prompt section placement */
+    section?: PromptSection;
+    /** Plain text prompt content */
+    text?: string;
+    /** Optional localized prompt content (keyed by locale, e.g. "en", "sv") */
+    i18n?: Record<string, string>;
+    /** Optional ordering hint (lower comes first) */
+    order?: number;
+}
+
+/**
+ * AI Provider Types
+ *
+ * Types for AI providers, models, and chat interactions.
+ */
+
+/**
+ * AI provider implementation
+ */
+interface AIProvider {
+    /** Provider ID (must match manifest) */
+    id: string;
+    /** Display name */
+    name: string;
+    /**
+     * Get available models from this provider
+     * @param options Optional settings for the provider (e.g., URL)
+     */
+    getModels(options?: GetModelsOptions): Promise<ModelInfo[]>;
+    /**
+     * Chat completion with streaming
+     */
+    chat(messages: ChatMessage[], options: ChatOptions): AsyncGenerator<StreamEvent, void, unknown>;
+    /**
+     * Optional: Generate embeddings
+     */
+    embed?(texts: string[]): Promise<number[][]>;
+}
+/**
+ * Model information
+ */
+interface ModelInfo {
+    /** Model ID */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Description */
+    description?: string;
+    /** Context window size */
+    contextLength?: number;
+}
+/**
+ * Chat message
+ */
+interface ChatMessage {
+    role: 'user' | 'assistant' | 'system' | 'tool';
+    content: string;
+    /** 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;
+}
+/**
+ * A tool call made by the model
+ */
+interface ToolCall {
+    /** Unique ID for this tool call */
+    id: string;
+    /** Tool name/ID to invoke */
+    name: string;
+    /** Arguments for the tool (as parsed object) */
+    arguments: Record<string, unknown>;
+}
+/**
+ * Options for chat completion
+ */
+interface ChatOptions {
+    /** Model to use */
+    model?: string;
+    /** Temperature (0-1) */
+    temperature?: number;
+    /** Maximum tokens to generate */
+    maxTokens?: number;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+    /** Provider-specific settings from model configuration */
+    settings?: Record<string, unknown>;
+    /** Available tools for this request */
+    tools?: ToolDefinition[];
+}
+/**
+ * Options for getModels
+ */
+interface GetModelsOptions {
+    /** Provider-specific settings (e.g., URL for Ollama) */
+    settings?: Record<string, unknown>;
+}
+/**
+ * Streaming events from chat
+ */
+type StreamEvent = {
+    type: 'content';
+    text: string;
+} | {
+    type: 'thinking';
+    text: string;
+} | {
+    type: 'tool_start';
+    name: string;
+    input: unknown;
+    toolCallId: string;
+} | {
+    type: 'tool_end';
+    name: string;
+    output: unknown;
+    toolCallId: string;
+} | {
+    type: 'done';
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+} | {
+    type: 'error';
+    message: string;
+};
+
+/**
+ * Extension Context Types
+ *
+ * Types for extension context and available APIs.
+ */
+
 /**
  * Disposable resource that can be cleaned up
  */
@@ -722,17 +832,18 @@ interface Disposable {
     dispose(): void;
 }
 /**
- * Context provided to extension's activate function.
+ * Request-scoped execution context for tool, action, and scheduler operations.
  *
- * ## User ID Context
+ * This context is passed to every tool and action execute() call, providing
+ * request-specific information without relying on global mutable state.
  *
- * The `userId` field provides the current user context for extensions. It is set when:
- * - A tool is executed by a user
- * - An action is executed by a user
- * - A scheduled job fires (if the job was created with a userId)
+ * ## Why Request-Scoped Context?
  *
- * For extension activation, `userId` is undefined since activation happens at system level.
- * Extensions should check for `userId` in their tool/action handlers to access user-specific data.
+ * Using request-scoped context instead of global state:
+ * - Eliminates race conditions (no global userId that can change mid-execution)
+ * - Provides cleaner architecture with explicit data flow
+ * - Makes code easier to reason about and debug
+ * - Allows scheduler jobs to create context for the correct user
  *
  * @example
  * ```typescript
@@ -742,9 +853,31 @@ interface Disposable {
  *     // User-specific logic
  *     const userData = await storage.getForUser(context.userId, 'preferences')
  *   }
+ *   // Access extension metadata
+ *   console.log(`Running in extension ${context.extension.id}`)
  * }
  * ```
  */
+interface ExecutionContext {
+    /**
+     * User ID for the current request.
+     * Undefined only for system/global operations during extension activation.
+     * Always defined for tool executions, action executions, and scheduler callbacks.
+     */
+    readonly userId?: string;
+    /** Extension metadata */
+    readonly extension: {
+        readonly id: string;
+        readonly version: string;
+        readonly storagePath: string;
+    };
+}
+/**
+ * Context provided to extension's activate function.
+ *
+ * Note: This context is for extension activation only. For tool/action execution,
+ * use the ExecutionContext parameter passed to execute() methods.
+ */
 interface ExtensionContext {
     /** Extension metadata */
     readonly extension: {
@@ -752,11 +885,6 @@ interface ExtensionContext {
         readonly version: string;
         readonly storagePath: string;
     };
-    /**
-     * Current user ID if in a user context, undefined for global/system operations.
-     * Set when tools or actions are executed by a user, or when a user-scoped job fires.
-     */
-    readonly userId?: string;
     /** Network access (if permitted) */
     readonly network?: NetworkAPI;
     /** Settings access (if permitted) */
@@ -891,11 +1019,11 @@ interface SchedulerJobRequest {
     payload?: Record<string, unknown>;
     misfire?: 'run_once' | 'skip';
     /**
-     * Optional user ID for user-scoped jobs.
-     * If set, the job is associated with a specific user and the userId
-     * will be passed to the extension when the job fires.
+     * User ID for the job owner.
+     * All scheduled jobs must be associated with a user. The userId
+     * will be passed to the extension when the job fires via ExecutionContext.
      */
-    userId?: string;
+    userId: string;
 }
 /**
  * Scheduler fire payload
@@ -906,8 +1034,8 @@ interface SchedulerFirePayload {
     scheduledFor: string;
     firedAt: string;
     delayMs: number;
-    /** User ID if this is a user-scoped job, undefined if global */
-    userId?: string;
+    /** User ID for the job owner */
+    userId: string;
 }
 /**
  * Scheduler API for registering jobs
@@ -915,7 +1043,12 @@ interface SchedulerFirePayload {
 interface SchedulerAPI {
     schedule(job: SchedulerJobRequest): Promise<void>;
     cancel(jobId: string): Promise<void>;
-    onFire(callback: (payload: SchedulerFirePayload) => void | Promise<void>): Disposable;
+    /**
+     * Register a callback for when scheduled jobs fire.
+     * The callback receives both the fire payload and an ExecutionContext
+     * with userId if the job was created with a userId.
+     */
+    onFire(callback: (payload: SchedulerFirePayload, context: ExecutionContext) => void | Promise<void>): Disposable;
 }
 /**
  * User profile data
@@ -1032,115 +1165,25 @@ interface LogAPI {
     error(message: string, data?: Record<string, unknown>): void;
 }
 /**
- * AI provider implementation
+ * Extension entry point interface
  */
-interface AIProvider {
-    /** Provider ID (must match manifest) */
-    id: string;
-    /** Display name */
-    name: string;
-    /**
-     * Get available models from this provider
-     * @param options Optional settings for the provider (e.g., URL)
-     */
-    getModels(options?: GetModelsOptions): Promise<ModelInfo[]>;
+interface ExtensionModule {
     /**
-     * Chat completion with streaming
+     * Called when extension is activated
      */
-    chat(messages: ChatMessage[], options: ChatOptions): AsyncGenerator<StreamEvent, void, unknown>;
+    activate(context: ExtensionContext): void | Disposable | Promise<void | Disposable>;
     /**
-     * Optional: Generate embeddings
+     * Called when extension is deactivated
      */
-    embed?(texts: string[]): Promise<number[][]>;
-}
-/**
- * Model information
- */
-interface ModelInfo {
-    /** Model ID */
-    id: string;
-    /** Display name */
-    name: string;
-    /** Description */
-    description?: string;
-    /** Context window size */
-    contextLength?: number;
-}
-/**
- * Chat message
- */
-interface ChatMessage {
-    role: 'user' | 'assistant' | 'system' | 'tool';
-    content: string;
-    /** 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;
-}
-/**
- * A tool call made by the model
- */
-interface ToolCall {
-    /** Unique ID for this tool call */
-    id: string;
-    /** Tool name/ID to invoke */
-    name: string;
-    /** Arguments for the tool (as parsed object) */
-    arguments: Record<string, unknown>;
-}
-/**
- * Options for chat completion
- */
-interface ChatOptions {
-    /** Model to use */
-    model?: string;
-    /** Temperature (0-1) */
-    temperature?: number;
-    /** Maximum tokens to generate */
-    maxTokens?: number;
-    /** Abort signal for cancellation */
-    signal?: AbortSignal;
-    /** Provider-specific settings from model configuration */
-    settings?: Record<string, unknown>;
-    /** Available tools for this request */
-    tools?: ToolDefinition[];
-}
-/**
- * Options for getModels
- */
-interface GetModelsOptions {
-    /** Provider-specific settings (e.g., URL for Ollama) */
-    settings?: Record<string, unknown>;
+    deactivate?(): void | Promise<void>;
 }
+
 /**
- * Streaming events from chat
+ * Tool and Action Types
+ *
+ * Types for tool and action implementations.
  */
-type StreamEvent = {
-    type: 'content';
-    text: string;
-} | {
-    type: 'thinking';
-    text: string;
-} | {
-    type: 'tool_start';
-    name: string;
-    input: unknown;
-    toolCallId: string;
-} | {
-    type: 'tool_end';
-    name: string;
-    output: unknown;
-    toolCallId: string;
-} | {
-    type: 'done';
-    usage?: {
-        inputTokens: number;
-        outputTokens: number;
-    };
-} | {
-    type: 'error';
-    message: string;
-};
+
 /**
  * Tool implementation
  */
@@ -1155,8 +1198,10 @@ interface Tool {
     parameters?: Record<string, unknown>;
     /**
      * Execute the tool
+     * @param params Tool parameters from the AI
+     * @param context Request-scoped execution context with userId and extension metadata
      */
-    execute(params: Record<string, unknown>): Promise<ToolResult>;
+    execute(params: Record<string, unknown>, context: ExecutionContext): Promise<ToolResult>;
 }
 /**
  * Tool execution result
@@ -1181,8 +1226,9 @@ interface Action {
     /**
      * Execute the action
      * @param params Parameters from the UI component (with $-values already resolved)
+     * @param context Request-scoped execution context with userId and extension metadata
      */
-    execute(params: Record<string, unknown>): Promise<ActionResult>;
+    execute(params: Record<string, unknown>, context: ExecutionContext): Promise<ActionResult>;
 }
 /**
  * Action execution result
@@ -1195,18 +1241,5 @@ interface ActionResult {
     /** Error message if failed */
     error?: string;
 }
-/**
- * Extension entry point interface
- */
-interface ExtensionModule {
-    /**
-     * Called when extension is activated
-     */
-    activate(context: ExtensionContext): void | Disposable | Promise<void | Disposable>;
-    /**
-     * Called when extension is deactivated
-     */
-    deactivate?(): void | Promise<void>;
-}
 
-export { type SchedulerSchedule as $, type ActionResult as A, type ProviderConfigSelectOption as B, type ChatMessage as C, type ProviderConfigValidation as D, type ExtensionManifest as E, type Permission as F, type GetModelsOptions as G, type StoragePermission as H, type CapabilityPermission as I, type SystemPermission as J, type ExtensionContext as K, type LocalizedString as L, type ModelInfo as M, type NetworkPermission as N, type Disposable as O, type Platform as P, type NetworkAPI as Q, type SettingsAPI as R, type SchedulerFirePayload as S, type ToolResult as T, type UserDataPermission as U, type ProvidersAPI as V, type ToolsAPI as W, type ActionsAPI as X, type EventsAPI as Y, type SchedulerAPI as Z, type SchedulerJobRequest as _, type ChatOptions as a, type UserAPI as a0, type UserProfile as a1, type ChatAPI as a2, type ChatInstructionMessage as a3, type DatabaseAPI as a4, type StorageAPI as a5, type LogAPI as a6, type AIProvider as a7, type ToolCall as a8, type Tool as a9, type PanelProps as aA, type ToggleProps as aB, type CollapsibleProps as aC, type PillVariant as aD, type PillProps as aE, type CheckboxProps as aF, type MarkdownProps as aG, type ModalProps as aH, type Action as aa, type ExtensionModule as ab, type AllowedCSSProperty as ac, type ExtensionComponentStyle as ad, type ExtensionComponentData as ae, type ExtensionComponentIterator as af, type ExtensionComponentChildren as ag, type ExtensionActionCall as ah, type ExtensionActionRef as ai, type ExtensionDataSource as aj, type ExtensionPanelDefinition as ak, type HeaderProps as al, type LabelProps as am, type ParagraphProps as an, type ButtonProps as ao, type TextInputProps as ap, type DateTimeInputProps as aq, type SelectProps as ar, type VerticalStackProps as as, type HorizontalStackProps as at, type GridProps as au, type DividerProps as av, type IconProps as aw, type IconButtonType as ax, type IconButtonProps as ay, type PanelAction as az, type StreamEvent as b, type ExtensionContributions as c, type SettingDefinition as d, type SettingOptionsMapping as e, type SettingCreateMapping as f, type ToolSettingsViewDefinition as g, type ToolSettingsView as h, type ToolSettingsListView as i, type ToolSettingsListMapping as j, type ToolSettingsComponentView as k, type ToolSettingsActionDataSource as l, type PanelDefinition as m, type PanelView as n, type PanelComponentView as o, type PanelActionDataSource as p, type PanelUnknownView as q, resolveLocalizedString as r, type ProviderDefinition as s, type PromptContribution as t, type PromptSection as u, type ToolDefinition as v, type CommandDefinition as w, type ProviderConfigSchema as x, type ProviderConfigProperty as y, type ProviderConfigPropertyType as z };
+export { type AIProvider as $, type ActionResult as A, type ExtensionContext as B, type ChatMessage as C, type Disposable as D, type ExtensionContributions as E, type SettingsAPI as F, type GetModelsOptions as G, type ProvidersAPI as H, type ToolsAPI as I, type ActionsAPI as J, type EventsAPI as K, type LocalizedString as L, type ModelInfo as M, type NetworkAPI as N, type SchedulerAPI as O, type PanelDefinition as P, type SchedulerJobRequest as Q, type SchedulerSchedule as R, type SchedulerFirePayload as S, type ToolResult as T, type UserAPI as U, type UserProfile as V, type ChatAPI as W, type ChatInstructionMessage as X, type DatabaseAPI as Y, type StorageAPI as Z, type LogAPI as _, type ChatOptions as a, type ToolCall as a0, type Tool as a1, type Action as a2, type ExtensionModule as a3, type AllowedCSSProperty as a4, type ExtensionComponentStyle as a5, type ExtensionComponentData as a6, type ExtensionComponentIterator as a7, type ExtensionComponentChildren as a8, type ExtensionActionCall as a9, type ConditionalGroupProps as aA, type ExecutionContext as aB, type ExtensionActionRef as aa, type ExtensionDataSource as ab, type ExtensionPanelDefinition as ac, type HeaderProps as ad, type LabelProps as ae, type ParagraphProps as af, type ButtonProps as ag, type TextInputProps as ah, type DateTimeInputProps as ai, type SelectProps as aj, type VerticalStackProps as ak, type HorizontalStackProps as al, type GridProps as am, type DividerProps as an, type IconProps as ao, type IconButtonType as ap, type IconButtonProps as aq, type PanelAction as ar, type PanelProps as as, type ToggleProps as at, type CollapsibleProps as au, type PillVariant as av, type PillProps as aw, type CheckboxProps as ax, type MarkdownProps as ay, type ModalProps as az, type StreamEvent as b, type SettingDefinition as c, type SettingOptionsMapping as d, type SettingCreateMapping as e, type ToolSettingsViewDefinition as f, type ToolSettingsView as g, type ToolSettingsListView as h, type ToolSettingsListMapping as i, type ToolSettingsComponentView as j, type ToolSettingsActionDataSource as k, type PanelView as l, type PanelComponentView as m, type PanelActionDataSource as n, type PanelUnknownView as o, type ProviderDefinition as p, type PromptContribution as q, resolveLocalizedString as r, type PromptSection as s, type ToolDefinition as t, type CommandDefinition as u, type ProviderConfigSchema as v, type ProviderConfigProperty as w, type ProviderConfigPropertyType as x, type ProviderConfigSelectOption as y, type ProviderConfigValidation as z };

package/package.json

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

package/src/index.ts

@@ -161,4 +161,5 @@ export type {
   CheckboxProps,
   MarkdownProps,
   ModalProps,
+  ConditionalGroupProps,
 } from './types.components.js'