@stina/extension-api 0.7.1 → 0.8.1

package/src/types.ts

@@ -43,6 +43,8 @@ export interface ExtensionContributions {
   settings?: SettingDefinition[]
   /** Tool settings views for UI */
   toolSettings?: ToolSettingsViewDefinition[]
+  /** Right panel contributions */
+  panels?: PanelDefinition[]
   /** AI providers */
   providers?: ProviderDefinition[]
   /** Tools for Stina to use */
@@ -69,6 +71,22 @@ export interface SettingDefinition {
   default?: unknown
   /** For select type: available options */
   options?: { value: string; label: string }[]
+  /** For select type: load options from tool */
+  optionsToolId?: string
+  /** Params for options tool */
+  optionsParams?: Record<string, unknown>
+  /** Mapping for options tool response */
+  optionsMapping?: SettingOptionsMapping
+  /** Tool ID for creating a new option */
+  createToolId?: string
+  /** Label for create action */
+  createLabel?: string
+  /** Fields for create form */
+  createFields?: SettingDefinition[]
+  /** Static params always sent to create tool */
+  createParams?: Record<string, unknown>
+  /** Mapping for create tool response */
+  createMapping?: SettingCreateMapping
   /** Validation rules */
   validation?: {
     required?: boolean
@@ -78,6 +96,30 @@ export interface SettingDefinition {
   }
 }
 
+/**
+ * Mapping for select field options from tool response
+ */
+export interface SettingOptionsMapping {
+  /** Key for items array in tool result data */
+  itemsKey: string
+  /** Key for option value */
+  valueKey: string
+  /** Key for option label */
+  labelKey: string
+  /** Optional key for description */
+  descriptionKey?: string
+}
+
+/**
+ * Mapping for create tool response
+ */
+export interface SettingCreateMapping {
+  /** Key for result data object */
+  resultKey?: string
+  /** Key for option value (defaults to "id") */
+  valueKey: string
+}
+
 /**
  * Tool settings view definition (UI schema)
  */
@@ -143,6 +185,57 @@ export interface ToolSettingsListMapping {
   secondaryKey?: string
 }
 
+/**
+ * Panel definition for right panel views
+ */
+export interface PanelDefinition {
+  /** Unique panel ID within the extension */
+  id: string
+  /** Display title */
+  title: string
+  /** Icon name (from huge-icons) */
+  icon?: string
+  /** Panel view schema */
+  view: PanelView
+}
+
+/**
+ * Panel view schema (declarative)
+ */
+export type PanelView = PanelComponentView | PanelUnknownView
+
+export interface PanelUnknownView {
+  /** View kind */
+  kind: string
+  /** Additional view configuration */
+  [key: string]: unknown
+}
+
+/**
+ * Action-based data source for declarative panels.
+ * Uses actions (not tools) to fetch data.
+ */
+export interface PanelActionDataSource {
+  /** Action ID to call for fetching data */
+  action: string
+  /** Parameters to pass to the action */
+  params?: Record<string, unknown>
+  /** Event names that should trigger a refresh of this data */
+  refreshOn?: string[]
+}
+
+/**
+ * Component-based panel view using the declarative DSL.
+ * Data is fetched via actions, content is rendered via ExtensionComponent.
+ */
+export interface PanelComponentView {
+  kind: 'component'
+  /** Data sources available in the panel. Keys become variable names (e.g., "$projects"). */
+  data?: Record<string, PanelActionDataSource>
+  /** Root component to render */
+  content: import('./types.components.js').ExtensionComponentData
+}
+
 /**
  * Provider definition (metadata only, implementation in code)
  */
@@ -315,8 +408,13 @@ export type UserDataPermission =
 export type CapabilityPermission =
   | 'provider.register'
   | 'tools.register'
+  | 'actions.register'
   | 'settings.register'
   | 'commands.register'
+  | 'panels.register'
+  | 'events.emit'
+  | 'scheduler.register'
+  | 'chat.message.write'
 
 /** System permissions */
 export type SystemPermission =
@@ -359,6 +457,21 @@ export interface ExtensionContext {
   /** Tool registration (if permitted) */
   readonly tools?: ToolsAPI
 
+  /** Action registration (if permitted) */
+  readonly actions?: ActionsAPI
+
+  /** Event emission (if permitted) */
+  readonly events?: EventsAPI
+
+  /** Scheduler access (if permitted) */
+  readonly scheduler?: SchedulerAPI
+
+  /** User data access (if permitted) */
+  readonly user?: UserAPI
+
+  /** Chat access (if permitted) */
+  readonly chat?: ChatAPI
+
   /** Database access (if permitted) */
   readonly database?: DatabaseAPI
 
@@ -424,6 +537,96 @@ export interface ToolsAPI {
   register(tool: Tool): Disposable
 }
 
+/**
+ * Actions API for registering UI actions
+ */
+export interface ActionsAPI {
+  /**
+   * Register an action that UI components can invoke
+   */
+  register(action: Action): Disposable
+}
+
+/**
+ * Events API for notifying the host
+ */
+export interface EventsAPI {
+  /**
+   * Emit a named event with optional payload
+   */
+  emit(name: string, payload?: Record<string, unknown>): Promise<void>
+}
+
+/**
+ * Scheduler schedule types
+ */
+export type SchedulerSchedule =
+  | { type: 'at'; at: string }
+  | { type: 'cron'; cron: string; timezone?: string }
+  | { type: 'interval'; everyMs: number }
+
+/**
+ * Scheduler job request
+ */
+export interface SchedulerJobRequest {
+  id: string
+  schedule: SchedulerSchedule
+  payload?: Record<string, unknown>
+  misfire?: 'run_once' | 'skip'
+}
+
+/**
+ * Scheduler fire payload
+ */
+export interface SchedulerFirePayload {
+  id: string
+  payload?: Record<string, unknown>
+  scheduledFor: string
+  firedAt: string
+  delayMs: number
+}
+
+/**
+ * Scheduler API for registering jobs
+ */
+export interface SchedulerAPI {
+  schedule(job: SchedulerJobRequest): Promise<void>
+  cancel(jobId: string): Promise<void>
+  onFire(callback: (payload: SchedulerFirePayload) => void): Disposable
+}
+
+/**
+ * User profile data
+ */
+export interface UserProfile {
+  firstName?: string
+  nickname?: string
+  language?: string
+  timezone?: string
+}
+
+/**
+ * User API for profile access
+ */
+export interface UserAPI {
+  getProfile(): Promise<UserProfile>
+}
+
+/**
+ * Chat instruction message
+ */
+export interface ChatInstructionMessage {
+  text: string
+  conversationId?: string
+}
+
+/**
+ * Chat API for appending instructions
+ */
+export interface ChatAPI {
+  appendInstruction(message: ChatInstructionMessage): Promise<void>
+}
+
 /**
  * Database API for extension-specific tables
  */
@@ -614,6 +817,37 @@ export interface ToolResult {
   error?: string
 }
 
+// ============================================================================
+// Action Types (for UI interactions, separate from Tools)
+// ============================================================================
+
+/**
+ * Action implementation for UI interactions.
+ * Actions are invoked by UI components, not by Stina (AI).
+ */
+export interface Action {
+  /** Action ID (unique within the extension) */
+  id: string
+
+  /**
+   * Execute the action
+   * @param params Parameters from the UI component (with $-values already resolved)
+   */
+  execute(params: Record<string, unknown>): Promise<ActionResult>
+}
+
+/**
+ * Action execution result
+ */
+export interface ActionResult {
+  /** Whether the action succeeded */
+  success: boolean
+  /** Result data (returned to UI) */
+  data?: unknown
+  /** Error message if failed */
+  error?: string
+}
+
 // ============================================================================
 // Extension Entry Point
 // ============================================================================

package/dist/chunk-SS4D3JYX.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 { ChatMessage, ChatOptions, GetModelsOptions, StreamEvent, ToolResult, ModelInfo } from './types.js'\n\n// ============================================================================\n// Host → Worker Messages\n// ============================================================================\n\nexport type HostToWorkerMessage =\n  | ActivateMessage\n  | DeactivateMessage\n  | SettingsChangedMessage\n  | ProviderChatRequestMessage\n  | ProviderModelsRequestMessage\n  | ToolExecuteRequestMessage\n  | ResponseMessage\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 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  }\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// Worker → Host Messages\n// ============================================================================\n\nexport type WorkerToHostMessage =\n  | ReadyMessage\n  | RequestMessage\n  | ProviderRegisteredMessage\n  | ToolRegisteredMessage\n  | StreamEventMessage\n  | LogMessage\n  | ProviderModelsResponseMessage\n  | ToolExecuteResponseMessage\n\nexport interface ReadyMessage {\n  type: 'ready'\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  | 'settings.getAll'\n  | 'settings.get'\n  | 'settings.set'\n  | 'database.execute'\n  | 'storage.get'\n  | 'storage.set'\n  | 'storage.delete'\n  | 'storage.keys'\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 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 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// 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":";;;;;;;;AA0LO,SAAS,oBAA4B;AAC1C,SAAO,GAAG,KAAK,IAAI,CAAC,IAAI,KAAK,OAAO,EAAE,SAAS,EAAE,EAAE,MAAM,GAAG,EAAE,CAAC;AACjE;","names":[]}