@practicalkit/plugin-sdk 0.0.2

package/src/messages/index.ts

@@ -0,0 +1,41 @@
+// Base
+export * from "./base/index.js";
+
+// VFS
+export * from "./vfs/index.js";
+
+// Editor
+export * from "./editor/index.js";
+
+// Document
+export * from "./document/index.js";
+
+// Workspace
+export * from "./workspace/index.js";
+
+// Native
+export * from "./native/index.js";
+
+// FS (file system subscriptions)
+export * from "./fs/index.js";
+
+// Plugin (intra-plugin messaging)
+export * from "./plugin/index.js";
+
+// Storage (secrets management)
+export * from "./storage/index.js";
+
+// Logs
+export * from "./logs/index.js";
+
+// LLM (tool registry)
+export * from "./llm/index.js";
+
+// UI (state)
+export * from "./ui/index.js";
+
+// Message Bus
+export * from "./IFrameMessageBus.js";
+
+// Client
+export * from "./IFrameClient.js";

package/src/messages/llm/index.ts

@@ -0,0 +1,158 @@
+import {
+  object,
+  string,
+  literal,
+  boolean,
+  optional,
+  number,
+  array,
+  unknown,
+  record,
+  type InferOutput,
+} from "valibot";
+import { respondableMessage } from "../base/index.js";
+
+// ============================================================================
+// JSON Schema type for tool parameters
+// Using 'record' for properties to match JSONSchema7's structure
+// ============================================================================
+export const JsonSchemaObject = object({
+  type: literal("object"),
+  properties: record(string(), unknown()),
+  required: optional(array(string())),
+});
+
+// ============================================================================
+// Tool definition as stored in the registry
+// ============================================================================
+export const LlmToolDefinition = object({
+  // Unique ID: "{pluginId}.{toolName}"
+  id: string(),
+  // Tool name (unique within plugin)
+  name: string(),
+  // Description for LLM
+  description: string(),
+  // JSON Schema for parameters
+  parameters: JsonSchemaObject,
+  // Provider info
+  provider: object({
+    pluginId: string(),
+    moduleId: string(),
+  }),
+  // Timeout in ms (default 30000, max 300000)
+  timeoutMs: optional(number()),
+});
+
+export type LlmToolDefinitionType = InferOutput<typeof LlmToolDefinition>;
+
+// ============================================================================
+// llm.tool.list - Get all registered tools
+// ============================================================================
+export namespace LlmToolList {
+  export const Request = respondableMessage("llm.tool.list", {});
+
+  export const Response = object({
+    type: literal("llm.tool.list.response"),
+    payload: object({
+      requestId: string(),
+      success: boolean(),
+      tools: array(LlmToolDefinition),
+      error: optional(string()),
+    }),
+  });
+
+  export type RequestType = InferOutput<typeof Request>;
+  export type ResponseType = InferOutput<typeof Response>;
+}
+
+// ============================================================================
+// llm.tool.execute - Execute a tool (called by chat plugin)
+// ============================================================================
+export namespace LlmToolExecute {
+  export const Request = respondableMessage("llm.tool.execute", {
+    toolId: string(), // "{pluginId}.{toolName}"
+    arguments: unknown(),
+  });
+
+  export const Response = object({
+    type: literal("llm.tool.execute.response"),
+    payload: object({
+      requestId: string(),
+      success: boolean(),
+      result: optional(unknown()),
+      error: optional(string()),
+    }),
+  });
+
+  export type RequestType = InferOutput<typeof Request>;
+  export type ResponseType = InferOutput<typeof Response>;
+}
+
+// ============================================================================
+// llm.tool.register - Register a tool (plugin -> host)
+// ============================================================================
+export namespace LlmToolRegister {
+  export const Request = respondableMessage("llm.tool.register", {
+    name: string(),
+    description: string(),
+    parameters: JsonSchemaObject,
+    timeoutMs: optional(number()),
+  });
+
+  export const Response = object({
+    type: literal("llm.tool.register.response"),
+    payload: object({
+      requestId: string(),
+      success: boolean(),
+      toolId: optional(string()), // Full tool ID assigned by host
+      error: optional(string()),
+    }),
+  });
+
+  export type RequestType = InferOutput<typeof Request>;
+  export type ResponseType = InferOutput<typeof Response>;
+}
+
+// ============================================================================
+// llm.tool.unregister - Unregister a tool (plugin -> host)
+// ============================================================================
+export namespace LlmToolUnregister {
+  export const Request = respondableMessage("llm.tool.unregister", {
+    name: string(),
+  });
+
+  export const Response = object({
+    type: literal("llm.tool.unregister.response"),
+    payload: object({
+      requestId: string(),
+      success: boolean(),
+      error: optional(string()),
+    }),
+  });
+
+  export type RequestType = InferOutput<typeof Request>;
+  export type ResponseType = InferOutput<typeof Response>;
+}
+
+// ============================================================================
+// llm.tool.call - Call a tool handler (host -> plugin)
+// ============================================================================
+export namespace LlmToolCall {
+  export const Request = respondableMessage("llm.tool.call", {
+    toolName: string(), // Just the name, not full ID
+    arguments: unknown(),
+  });
+
+  export const Response = object({
+    type: literal("llm.tool.call.response"),
+    payload: object({
+      requestId: string(),
+      success: boolean(),
+      result: optional(unknown()),
+      error: optional(string()),
+    }),
+  });
+
+  export type RequestType = InferOutput<typeof Request>;
+  export type ResponseType = InferOutput<typeof Response>;
+}

package/src/messages/logs/index.ts

@@ -0,0 +1,39 @@
+import {
+  object,
+  string,
+  literal,
+  boolean,
+  optional,
+  picklist,
+  type InferOutput,
+  array,
+  unknown,
+} from "valibot";
+import { respondableMessage } from "../base/index.js";
+
+// Log levels matching Rust LogLevel enum
+export const LogLevelSchema = picklist(["debug", "info", "warn", "error"]);
+export type LogLevel = InferOutput<typeof LogLevelSchema>;
+
+// ============================================================================
+// logs.write - Write a log entry from a plugin
+// ============================================================================
+export namespace LogsWrite {
+  export const Request = respondableMessage("logs.write", {
+    level: LogLevelSchema,
+    channelName: string(),
+    args: array(unknown()),
+  });
+
+  export const Response = object({
+    type: literal("logs.write.response"),
+    payload: object({
+      requestId: string(),
+      success: boolean(),
+      error: optional(string()),
+    }),
+  });
+
+  export type RequestType = InferOutput<typeof Request>;
+  export type ResponseType = InferOutput<typeof Response>;
+}

package/src/messages/native/call/message.schemas.ts

@@ -0,0 +1,25 @@
+import { string, type InferOutput, literal, union, unknown } from "valibot";
+import { respondableMessage } from "../../base/index.js";
+import { ModuleIdSchema, PluginIdSchema } from "@practicalkit/commons";
+
+export const NativeCall = {
+  Request: respondableMessage("native.call", {
+    pluginId: PluginIdSchema,
+    moduleId: ModuleIdSchema,
+    command: string(),
+    args: unknown(),
+  }),
+  Response: union([
+    respondableMessage("native.call.response", {
+      success: literal(true),
+      data: unknown(),
+    }),
+    respondableMessage("native.call.response", {
+      success: literal(false),
+      error: string(),
+    }),
+  ]),
+};
+
+export type NativeCallRequest = InferOutput<typeof NativeCall.Request>;
+export type NativeCallResponse = InferOutput<typeof NativeCall.Response>;

package/src/messages/native/index.ts

@@ -0,0 +1 @@
+export * from "./call/message.schemas.js";

package/src/messages/plugin/index.ts

@@ -0,0 +1,95 @@
+import {
+  object,
+  string,
+  literal,
+  boolean,
+  unknown,
+  optional,
+  type InferOutput,
+} from "valibot";
+import { respondableMessage } from "../base/index.js";
+
+// ============================================================================
+// plugin.sendMessage - Send a message to a specific sibling module
+// ============================================================================
+export namespace PluginSendMessage {
+  export const Request = respondableMessage("plugin.sendMessage", {
+    targetModuleId: string(),
+    message: unknown(),
+  });
+
+  export const Response = object({
+    type: literal("plugin.sendMessage.response"),
+    payload: object({
+      requestId: string(),
+      success: boolean(),
+      data: optional(unknown()),
+      error: optional(string()),
+    }),
+  });
+
+  export type RequestType = InferOutput<typeof Request>;
+  export type ResponseType = InferOutput<typeof Response>;
+}
+
+// ============================================================================
+// plugin.message - Incoming message from a sibling module (forwarded by host)
+// ============================================================================
+export namespace PluginMessage {
+  export const Request = respondableMessage("plugin.message", {
+    fromModuleId: string(),
+    message: unknown(),
+  });
+
+  export const Response = object({
+    type: literal("plugin.message.response"),
+    payload: object({
+      requestId: string(),
+      success: boolean(),
+      data: optional(unknown()),
+      error: optional(string()),
+    }),
+  });
+
+  export type RequestType = InferOutput<typeof Request>;
+  export type ResponseType = InferOutput<typeof Response>;
+  /** Payload type without requestId, for public API handlers */
+  export type HandlerPayload = Omit<RequestType["payload"], "requestId">;
+}
+
+// ============================================================================
+// plugin.sendBroadcast - Broadcast a message to all sibling modules
+// ============================================================================
+export namespace PluginSendBroadcast {
+  export const Request = respondableMessage("plugin.sendBroadcast", {
+    message: unknown(),
+  });
+
+  export const Response = object({
+    type: literal("plugin.sendBroadcast.response"),
+    payload: object({
+      requestId: string(),
+      success: boolean(),
+      error: optional(string()),
+    }),
+  });
+
+  export type RequestType = InferOutput<typeof Request>;
+  export type ResponseType = InferOutput<typeof Response>;
+}
+
+// ============================================================================
+// plugin.broadcast - Incoming broadcast from a sibling module (forwarded by host)
+// This is fire-and-forget, no response expected
+// ============================================================================
+export namespace PluginBroadcast {
+  export const Event = object({
+    type: literal("plugin.broadcast"),
+    payload: object({
+      fromModuleId: string(),
+      message: unknown(),
+    }),
+  });
+
+  export type EventType = InferOutput<typeof Event>;
+}

package/src/messages/storage/index.ts

@@ -0,0 +1,140 @@
+import {
+  object,
+  string,
+  literal,
+  boolean,
+  optional,
+  nullable,
+  type InferOutput,
+} from "valibot";
+import { respondableMessage } from "../base/index.js";
+
+// ============================================================================
+// storage.get - Get a value for this plugin (base64-encoded bytes)
+// ============================================================================
+export namespace StorageGet {
+  export const Request = respondableMessage("storage.get", {
+    key: string(),
+  });
+
+  export const Response = object({
+    type: literal("storage.get.response"),
+    payload: object({
+      requestId: string(),
+      success: boolean(),
+      value: nullable(string()), // base64-encoded bytes or null
+      error: optional(string()),
+    }),
+  });
+
+  export type RequestType = InferOutput<typeof Request>;
+  export type ResponseType = InferOutput<typeof Response>;
+}
+
+// ============================================================================
+// storage.set - Set a value for this plugin (base64-encoded bytes)
+// ============================================================================
+export namespace StorageSet {
+  export const Request = respondableMessage("storage.set", {
+    key: string(),
+    value: string(), // base64-encoded bytes
+  });
+
+  export const Response = object({
+    type: literal("storage.set.response"),
+    payload: object({
+      requestId: string(),
+      success: boolean(),
+      error: optional(string()),
+    }),
+  });
+
+  export type RequestType = InferOutput<typeof Request>;
+  export type ResponseType = InferOutput<typeof Response>;
+}
+
+// ============================================================================
+// storage.delete - Delete a value for this plugin
+// ============================================================================
+export namespace StorageDelete {
+  export const Request = respondableMessage("storage.delete", {
+    key: string(),
+  });
+
+  export const Response = object({
+    type: literal("storage.delete.response"),
+    payload: object({
+      requestId: string(),
+      success: boolean(),
+      error: optional(string()),
+    }),
+  });
+
+  export type RequestType = InferOutput<typeof Request>;
+  export type ResponseType = InferOutput<typeof Response>;
+}
+
+// ============================================================================
+// storage.getSecret - Get a secret value for this plugin (base64-encoded bytes)
+// ============================================================================
+export namespace StorageGetSecret {
+  export const Request = respondableMessage("storage.getSecret", {
+    key: string(),
+  });
+
+  export const Response = object({
+    type: literal("storage.getSecret.response"),
+    payload: object({
+      requestId: string(),
+      success: boolean(),
+      value: nullable(string()), // base64-encoded bytes or null
+      error: optional(string()),
+    }),
+  });
+
+  export type RequestType = InferOutput<typeof Request>;
+  export type ResponseType = InferOutput<typeof Response>;
+}
+
+// ============================================================================
+// storage.setSecret - Set a secret value for this plugin (base64-encoded bytes)
+// ============================================================================
+export namespace StorageSetSecret {
+  export const Request = respondableMessage("storage.setSecret", {
+    key: string(),
+    value: string(), // base64-encoded bytes
+  });
+
+  export const Response = object({
+    type: literal("storage.setSecret.response"),
+    payload: object({
+      requestId: string(),
+      success: boolean(),
+      error: optional(string()),
+    }),
+  });
+
+  export type RequestType = InferOutput<typeof Request>;
+  export type ResponseType = InferOutput<typeof Response>;
+}
+
+// ============================================================================
+// storage.deleteSecret - Delete a secret value for this plugin
+// ============================================================================
+export namespace StorageDeleteSecret {
+  export const Request = respondableMessage("storage.deleteSecret", {
+    key: string(),
+  });
+
+  export const Response = object({
+    type: literal("storage.deleteSecret.response"),
+    payload: object({
+      requestId: string(),
+      success: boolean(),
+      error: optional(string()),
+    }),
+  });
+
+  export type RequestType = InferOutput<typeof Request>;
+  export type ResponseType = InferOutput<typeof Response>;
+}

package/src/messages/ui/UiChannel.ts

@@ -0,0 +1,156 @@
+import { IFrameClient } from "../IFrameClient.js";
+import { safeParse } from "valibot";
+import type { UiTabsChangedEventPayload } from "../index.js";
+import {
+  UI_TABS_CHANGED_EVENT,
+  UiConfirm,
+  UiGetState,
+  UiSetCollapseState,
+  UiShowContextMenu,
+  UiShowNotification,
+  UiTabsChangedEventSchema,
+} from "../index.js";
+
+export interface TabInfo {
+  id: string;
+  title: string;
+  isActive: boolean;
+}
+
+export interface UiState {
+  openTabs: TabInfo[];
+}
+
+export class UiChannel {
+  constructor(private client: IFrameClient) {}
+
+  /**
+   * Get the current UI state including open tabs.
+   * Requires 'ui:read' permission.
+   */
+  async getState(): Promise<UiState> {
+    const response = await this.client.sendAndWait<
+      typeof UiGetState.Request,
+      typeof UiGetState.Response
+    >("ui.getState", {}, UiGetState.Request, UiGetState.Response);
+
+    return {
+      openTabs: response.openTabs,
+    };
+  }
+
+  /**
+   * Set the collapse state of this panel.
+   * @param collapsed - true to collapse the panel, false to expand it
+   */
+  async setCollapseState(collapsed: boolean): Promise<void> {
+    const response = await this.client.sendAndWait<
+      typeof UiSetCollapseState.Request,
+      typeof UiSetCollapseState.Response
+    >(
+      "ui.setCollapseState",
+      { collapsed },
+      UiSetCollapseState.Request,
+      UiSetCollapseState.Response
+    );
+
+    if (!response.success) {
+      throw new Error("Failed to set panel collapse state");
+    }
+  }
+
+  /**
+   * Show a context menu at the specified position.
+   * @param options - Menu configuration including position and items
+   * @returns The ID of the selected menu item, or null if cancelled
+   */
+  async showContextMenu(options: {
+    x: number;
+    y: number;
+    items: Array<
+      { type?: "item"; id: string; label: string } | { type: "separator" }
+    >;
+  }): Promise<{ selectedItemId: string | null }> {
+    const response = await this.client.sendAndWait<
+      typeof UiShowContextMenu.Request,
+      typeof UiShowContextMenu.Response
+    >(
+      "ui.showContextMenu",
+      options,
+      UiShowContextMenu.Request,
+      UiShowContextMenu.Response
+    );
+
+    return { selectedItemId: response.selectedItemId };
+  }
+
+  /**
+   * Show a notification message to the user.
+   * @param message - The message to display
+   * @param type - The type of notification (info, success, warning, error)
+   */
+  async showNotification(
+    message: string,
+    type: "info" | "success" | "warning" | "error" = "info"
+  ): Promise<void> {
+    const response = await this.client.sendAndWait<
+      typeof UiShowNotification.Request,
+      typeof UiShowNotification.Response
+    >(
+      "ui.showNotification",
+      { message, type },
+      UiShowNotification.Request,
+      UiShowNotification.Response
+    );
+
+    if (!response.success) {
+      throw new Error(response.error);
+    }
+  }
+
+  /**
+   * Show a native confirmation dialog.
+   * @param options - Dialog configuration
+   * @returns true if user confirmed, false if cancelled
+   */
+  async confirm(options: {
+    title: string;
+    message: string;
+    okLabel?: string;
+    cancelLabel?: string;
+  }): Promise<boolean> {
+    const response = await this.client.sendAndWait<
+      typeof UiConfirm.Request,
+      typeof UiConfirm.Response
+    >("ui.confirm", options, UiConfirm.Request, UiConfirm.Response);
+
+    return response.confirmed;
+  }
+
+  /**
+   * Listen for tab changes (tabs opened, closed, or switched).
+   * @param handler - Callback function that receives tab change events
+   * @returns Unsubscribe function
+   */
+  onTabsChanged(
+    handler: (event: { payload: UiTabsChangedEventPayload }) => void
+  ): () => void {
+    return this.client.subscribe((evt) => {
+      const { type, payload } = evt.data || {};
+      if (type === UI_TABS_CHANGED_EVENT) {
+        const result = safeParse(UiTabsChangedEventSchema, {
+          type,
+          payload,
+        });
+        if (result.success) {
+          handler({ payload: result.output.payload });
+        } else {
+          console.error(
+            `[SDK] Invalid ${UI_TABS_CHANGED_EVENT} payload:`,
+            result.issues
+          );
+        }
+      }
+    });
+  }
+}

package/src/messages/ui/confirm/index.ts

@@ -0,0 +1 @@
+export * from "./message.schemas.js";

package/src/messages/ui/confirm/message.schemas.ts

@@ -0,0 +1,36 @@
+import { string, object, type InferOutput, optional, boolean } from "valibot";
+import { respondableMessage } from "../../base/index.js";
+
+const UiConfirmRequestPayloadSchema = object({
+  requestId: string(),
+  title: string(),
+  message: string(),
+  okLabel: optional(string()),
+  cancelLabel: optional(string()),
+});
+
+const UiConfirmResponsePayloadSchema = object({
+  requestId: string(),
+  confirmed: boolean(),
+});
+
+export const UiConfirm = {
+  Request: respondableMessage("ui.confirm", {
+    title: string(),
+    message: string(),
+    okLabel: optional(string()),
+    cancelLabel: optional(string()),
+  }),
+  Response: respondableMessage("ui.confirm.response", {
+    confirmed: boolean(),
+  }),
+};
+
+export type UiConfirmRequest = InferOutput<typeof UiConfirm.Request>;
+export type UiConfirmResponse = InferOutput<typeof UiConfirm.Response>;
+export type UiConfirmRequestPayload = InferOutput<
+  typeof UiConfirmRequestPayloadSchema
+>;
+export type UiConfirmResponsePayload = InferOutput<
+  typeof UiConfirmResponsePayloadSchema
+>;