@stina/extension-api 0.5.0

package/dist/types-Brv9O9NY.d.ts

@@ -0,0 +1,540 @@
+/**
+ * Extension manifest format (manifest.json)
+ */
+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
+ */
+interface ExtensionContributions {
+    /** User-configurable settings */
+    settings?: SettingDefinition[];
+    /** Tool settings views for UI */
+    toolSettings?: ToolSettingsViewDefinition[];
+    /** AI providers */
+    providers?: ProviderDefinition[];
+    /** Tools for Stina to use */
+    tools?: ToolDefinition[];
+    /** Slash commands */
+    commands?: CommandDefinition[];
+    /** Prompt contributions for the system prompt */
+    prompts?: PromptContribution[];
+}
+/**
+ * Setting definition for the UI
+ */
+interface SettingDefinition {
+    /** Setting ID (namespaced automatically) */
+    id: string;
+    /** Display title */
+    title: string;
+    /** Help text */
+    description?: string;
+    /** Setting type */
+    type: 'string' | 'number' | 'boolean' | 'select';
+    /** Default value */
+    default?: unknown;
+    /** For select type: available options */
+    options?: {
+        value: string;
+        label: string;
+    }[];
+    /** Validation rules */
+    validation?: {
+        required?: boolean;
+        min?: number;
+        max?: number;
+        pattern?: string;
+    };
+}
+/**
+ * Tool settings view definition (UI schema)
+ */
+interface ToolSettingsViewDefinition {
+    /** Unique view ID within the extension */
+    id: string;
+    /** Display title */
+    title: string;
+    /** Help text */
+    description?: string;
+    /** View configuration */
+    view: ToolSettingsView;
+    /** Fields for create/edit forms (uses SettingDefinition) */
+    fields?: SettingDefinition[];
+}
+/**
+ * Tool settings view types
+ */
+type ToolSettingsView = ToolSettingsListView;
+/**
+ * List view backed by tools
+ */
+interface ToolSettingsListView {
+    /** View kind */
+    kind: 'list';
+    /** Tool ID for listing items */
+    listToolId: string;
+    /** Tool ID for fetching details (optional) */
+    getToolId?: string;
+    /** Tool ID for creating/updating items (optional) */
+    upsertToolId?: string;
+    /** Tool ID for deleting items (optional) */
+    deleteToolId?: string;
+    /** Mapping from tool data to UI fields */
+    mapping: ToolSettingsListMapping;
+    /** Param name for search query (default: "query") */
+    searchParam?: string;
+    /** Param name for limit (default: "limit") */
+    limitParam?: string;
+    /** Param name for get/delete ID (default: "id") */
+    idParam?: string;
+    /** Static params always sent to list tool */
+    listParams?: Record<string, unknown>;
+}
+/**
+ * Mapping from tool list data to UI fields
+ */
+interface ToolSettingsListMapping {
+    /** Key for items array in tool result data */
+    itemsKey: string;
+    /** Key for total count in tool result data */
+    countKey?: string;
+    /** Key for item ID */
+    idKey: string;
+    /** Key for item label */
+    labelKey: string;
+    /** Key for item description */
+    descriptionKey?: string;
+    /** Key for secondary label */
+    secondaryKey?: string;
+}
+/**
+ * Provider definition (metadata only, implementation in code)
+ */
+interface ProviderDefinition {
+    /** Provider ID */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Description */
+    description?: string;
+    /** Suggested default model when creating a new model configuration */
+    suggestedDefaultModel?: string;
+    /** Default settings for this provider (e.g., { url: "http://localhost:11434" }) */
+    defaultSettings?: Record<string, unknown>;
+    /** 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.
+ */
+interface ProviderConfigSchema {
+    /** Property definitions */
+    properties: Record<string, ProviderConfigProperty>;
+    /** Display order of properties in UI (optional, defaults to object key order) */
+    order?: string[];
+}
+/**
+ * Property types for provider configuration
+ */
+type ProviderConfigPropertyType = 'string' | 'number' | 'boolean' | 'select' | 'password' | 'url';
+/**
+ * Single property in a provider configuration schema.
+ * Defines how a setting should be rendered and validated in the UI.
+ */
+interface ProviderConfigProperty {
+    /** Property type - determines UI control */
+    type: ProviderConfigPropertyType;
+    /** Display label */
+    title: string;
+    /** Help text shown below the input */
+    description?: string;
+    /** Default value */
+    default?: unknown;
+    /** Whether the field is required */
+    required?: boolean;
+    /** Placeholder text for input fields */
+    placeholder?: string;
+    /** For 'select' type: static options */
+    options?: ProviderConfigSelectOption[];
+    /** Validation rules */
+    validation?: ProviderConfigValidation;
+}
+/**
+ * Option for select-type properties
+ */
+interface ProviderConfigSelectOption {
+    /** Value stored in settings */
+    value: string;
+    /** Display label */
+    label: string;
+}
+/**
+ * Validation rules for a property
+ */
+interface ProviderConfigValidation {
+    /** Regex pattern the value must match */
+    pattern?: string;
+    /** Minimum string length */
+    minLength?: number;
+    /** Maximum string length */
+    maxLength?: number;
+    /** Minimum number value */
+    min?: number;
+    /** Maximum number value */
+    max?: number;
+}
+/**
+ * Tool definition (metadata only, implementation in code)
+ */
+interface ToolDefinition {
+    /** Tool ID */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Description for Stina */
+    description: string;
+    /** Parameter schema (JSON Schema) */
+    parameters?: Record<string, unknown>;
+}
+/**
+ * Command definition
+ */
+interface CommandDefinition {
+    /** Command ID (e.g., "weather" for /weather) */
+    id: string;
+    /** Display name */
+    name: string;
+    /** 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' | 'settings.register' | 'commands.register';
+/** System permissions */
+type SystemPermission = 'files.read' | 'files.write' | 'clipboard.read' | 'clipboard.write';
+/**
+ * Disposable resource that can be cleaned up
+ */
+interface Disposable {
+    dispose(): void;
+}
+/**
+ * Context provided to extension's activate function
+ */
+interface ExtensionContext {
+    /** Extension metadata */
+    readonly extension: {
+        readonly id: string;
+        readonly version: string;
+        readonly storagePath: string;
+    };
+    /** Network access (if permitted) */
+    readonly network?: NetworkAPI;
+    /** Settings access (if permitted) */
+    readonly settings?: SettingsAPI;
+    /** Provider registration (if permitted) */
+    readonly providers?: ProvidersAPI;
+    /** Tool registration (if permitted) */
+    readonly tools?: ToolsAPI;
+    /** Database access (if permitted) */
+    readonly database?: DatabaseAPI;
+    /** Local storage (if permitted) */
+    readonly storage?: StorageAPI;
+    /** Logging (always available) */
+    readonly log: LogAPI;
+}
+/**
+ * Network API for making HTTP requests
+ */
+interface NetworkAPI {
+    /**
+     * Fetch a URL (permissions are enforced by host)
+     */
+    fetch(url: string, options?: RequestInit): Promise<Response>;
+}
+/**
+ * Settings API for reading/writing extension settings
+ */
+interface SettingsAPI {
+    /**
+     * Get all settings for this extension
+     */
+    getAll<T extends Record<string, unknown>>(): Promise<T>;
+    /**
+     * Get a specific setting value
+     */
+    get<T>(key: string): Promise<T | undefined>;
+    /**
+     * Set a setting value
+     */
+    set(key: string, value: unknown): Promise<void>;
+    /**
+     * Listen for setting changes
+     */
+    onChange(callback: (key: string, value: unknown) => void): Disposable;
+}
+/**
+ * Providers API for registering AI providers
+ */
+interface ProvidersAPI {
+    /**
+     * Register an AI provider
+     */
+    register(provider: AIProvider): Disposable;
+}
+/**
+ * Tools API for registering tools
+ */
+interface ToolsAPI {
+    /**
+     * Register a tool that Stina can use
+     */
+    register(tool: Tool): Disposable;
+}
+/**
+ * Database API for extension-specific tables
+ */
+interface DatabaseAPI {
+    /**
+     * Execute a SQL query (only extension's prefixed tables allowed)
+     */
+    execute<T = unknown>(sql: string, params?: unknown[]): Promise<T[]>;
+}
+/**
+ * Simple key-value storage API
+ */
+interface StorageAPI {
+    /**
+     * Get a value by key
+     */
+    get<T>(key: string): Promise<T | undefined>;
+    /**
+     * Set a value
+     */
+    set(key: string, value: unknown): Promise<void>;
+    /**
+     * Delete a key
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Get all keys
+     */
+    keys(): Promise<string[]>;
+}
+/**
+ * Logging API
+ */
+interface LogAPI {
+    debug(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+}
+/**
+ * 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;
+};
+/**
+ * Tool implementation
+ */
+interface Tool {
+    /** Tool ID (must match manifest) */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Description for Stina */
+    description: string;
+    /** Parameter schema (JSON Schema) */
+    parameters?: Record<string, unknown>;
+    /**
+     * Execute the tool
+     */
+    execute(params: Record<string, unknown>): Promise<ToolResult>;
+}
+/**
+ * Tool execution result
+ */
+interface ToolResult {
+    /** Whether the tool succeeded */
+    success: boolean;
+    /** Result data (for Stina to use) */
+    data?: unknown;
+    /** Human-readable message */
+    message?: string;
+    /** 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 { DatabaseAPI as A, StorageAPI as B, ChatMessage as C, Disposable as D, ExtensionManifest as E, AIProvider as F, GetModelsOptions as G, ToolCall as H, Tool as I, ExtensionModule as J, LogAPI as L, ModelInfo as M, NetworkPermission as N, Platform as P, StreamEvent as S, ToolResult as T, UserDataPermission as U, ChatOptions as a, ExtensionContributions as b, SettingDefinition as c, ToolSettingsViewDefinition as d, ToolSettingsView as e, ToolSettingsListView as f, ToolSettingsListMapping as g, ProviderDefinition as h, PromptContribution as i, PromptSection as j, ToolDefinition as k, CommandDefinition as l, ProviderConfigSchema as m, ProviderConfigProperty as n, ProviderConfigPropertyType as o, ProviderConfigSelectOption as p, ProviderConfigValidation as q, Permission as r, StoragePermission as s, CapabilityPermission as t, SystemPermission as u, ExtensionContext as v, NetworkAPI as w, SettingsAPI as x, ProvidersAPI as y, ToolsAPI as z };

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@stina/extension-api",
+  "version": "0.5.0",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.ts",
+      "import": "./dist/runtime.js",
+      "require": "./dist/runtime.cjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,92 @@
+/**
+ * @stina/extension-api
+ *
+ * Types and utilities for building Stina extensions.
+ *
+ * Extensions should import from this package for type definitions.
+ * The runtime (worker-side code) should import from '@stina/extension-api/runtime'.
+ */
+
+// Types
+export type {
+  // Manifest
+  ExtensionManifest,
+  Platform,
+  ExtensionContributions,
+  SettingDefinition,
+  ToolSettingsViewDefinition,
+  ToolSettingsView,
+  ToolSettingsListView,
+  ToolSettingsListMapping,
+  ProviderDefinition,
+  PromptContribution,
+  PromptSection,
+  ToolDefinition,
+  CommandDefinition,
+
+  // Provider Configuration Schema
+  ProviderConfigSchema,
+  ProviderConfigProperty,
+  ProviderConfigPropertyType,
+  ProviderConfigSelectOption,
+  ProviderConfigValidation,
+
+  // Permissions
+  Permission,
+  NetworkPermission,
+  StoragePermission,
+  UserDataPermission,
+  CapabilityPermission,
+  SystemPermission,
+
+  // Context
+  ExtensionContext,
+  Disposable,
+  NetworkAPI,
+  SettingsAPI,
+  ProvidersAPI,
+  ToolsAPI,
+  DatabaseAPI,
+  StorageAPI,
+  LogAPI,
+
+  // AI Provider
+  AIProvider,
+  ModelInfo,
+  ChatMessage,
+  ChatOptions,
+  GetModelsOptions,
+  StreamEvent,
+  ToolCall,
+
+  // Tools
+  Tool,
+  ToolResult,
+
+  // Entry point
+  ExtensionModule,
+} from './types.js'
+
+// Messages (for host implementation)
+export type {
+  HostToWorkerMessage,
+  WorkerToHostMessage,
+  ActivateMessage,
+  DeactivateMessage,
+  SettingsChangedMessage,
+  ProviderChatRequestMessage,
+  ProviderModelsRequestMessage,
+  ToolExecuteRequestMessage,
+  ToolExecuteResponseMessage,
+  ResponseMessage,
+  ReadyMessage,
+  RequestMessage,
+  RequestMethod,
+  ProviderRegisteredMessage,
+  ToolRegisteredMessage,
+  StreamEventMessage,
+  LogMessage,
+  PendingRequest,
+} from './messages.js'
+
+export { generateMessageId } from './messages.js'