@practicalkit/plugin-sdk 0.0.2

package/src/llm/ToolRegistry.ts

@@ -0,0 +1,186 @@
+import { safeParse } from "valibot";
+import type { IFrameClient } from "../messages/IFrameClient.js";
+import {
+  LlmToolList,
+  LlmToolExecute,
+  LlmToolRegister,
+  LlmToolUnregister,
+  LlmToolCall,
+  type LlmToolDefinitionType,
+} from "../messages/index.js";
+
+/** Handler function for a registered tool */
+export type LlmToolHandler = (args: unknown) => unknown | Promise<unknown>;
+
+/** Options for registering an LLM tool */
+export interface LlmToolRegistration {
+  name: string;
+  description: string;
+  parameters: {
+    type: "object";
+    properties: Record<string, unknown>;
+    required?: string[];
+  };
+  timeoutMs?: number;
+  handler: LlmToolHandler;
+}
+
+/**
+ * Internal tool registry that manages LLM tool registration and execution.
+ * This class is not part of the public SDK API.
+ */
+export class ToolRegistry {
+  private readonly client: IFrameClient;
+  // Local storage for tool handlers (keyed by tool name)
+  private readonly toolHandlers: Map<string, LlmToolHandler> = new Map();
+  // Unsubscribe function for tool call listener
+  private toolCallUnsubscribe: (() => void) | null = null;
+
+  constructor(client: IFrameClient) {
+    this.client = client;
+  }
+
+  /**
+   * List all registered LLM tools from all plugins
+   */
+  async listTools(): Promise<LlmToolDefinitionType[]> {
+    const response = await this.client.sendAndWait(
+      "llm.tool.list",
+      {},
+      LlmToolList.Request,
+      LlmToolList.Response
+    );
+
+    if (!response.success) {
+      throw new Error(response.error || "Failed to list tools");
+    }
+
+    return response.tools;
+  }
+
+  /**
+   * Execute an LLM tool by ID
+   */
+  async executeTool(toolId: string, args: unknown): Promise<unknown> {
+    const response = await this.client.sendAndWait(
+      "llm.tool.execute",
+      { toolId, arguments: args },
+      LlmToolExecute.Request,
+      LlmToolExecute.Response
+    );
+
+    if (!response.success) {
+      throw new Error(response.error || "Failed to execute tool");
+    }
+
+    return response.result;
+  }
+
+  /**
+   * Register a tool that can be called by the LLM.
+   * The handler is stored locally and invoked when the host routes a tool call here.
+   */
+  async registerTool(registration: LlmToolRegistration): Promise<string> {
+    // Store handler locally
+    this.toolHandlers.set(registration.name, registration.handler);
+
+    // Ensure we're listening for tool calls
+    this.ensureToolCallListener();
+
+    // Register metadata with host
+    const response = await this.client.sendAndWait(
+      "llm.tool.register",
+      {
+        name: registration.name,
+        description: registration.description,
+        parameters: registration.parameters,
+        timeoutMs: registration.timeoutMs,
+      },
+      LlmToolRegister.Request,
+      LlmToolRegister.Response
+    );
+
+    if (!response.success || !response.toolId) {
+      this.toolHandlers.delete(registration.name);
+      throw new Error(response.error || "Failed to register tool");
+    }
+
+    return response.toolId;
+  }
+
+  /**
+   * Unregister a previously registered tool
+   */
+  async unregisterTool(name: string): Promise<void> {
+    const response = await this.client.sendAndWait(
+      "llm.tool.unregister",
+      { name },
+      LlmToolUnregister.Request,
+      LlmToolUnregister.Response
+    );
+
+    if (!response.success) {
+      throw new Error(response.error || "Failed to unregister tool");
+    }
+    this.toolHandlers.delete(name);
+  }
+
+  /**
+   * Ensure we have a listener for incoming tool call requests from the host.
+   * This is called automatically when registering a tool.
+   */
+  private ensureToolCallListener(): void {
+    if (this.toolCallUnsubscribe) {
+      return; // Already listening
+    }
+
+    this.toolCallUnsubscribe = this.client.subscribe(async (evt) => {
+      const { type } = evt.data || {};
+
+      if (type !== "llm.tool.call") {
+        return; // Not a tool call event
+      }
+
+      const result = safeParse(LlmToolCall.Request, evt.data);
+      if (result.success) {
+        const { toolName, arguments: args } = result.output.payload;
+        const requestId = result.output.payload.requestId;
+        const handler = this.toolHandlers.get(toolName);
+
+        if (handler) {
+          try {
+            const toolResult = await Promise.resolve(handler(args));
+            this.client.send({
+              type: "llm.tool.call.response",
+              payload: {
+                requestId,
+                success: true,
+                result: toolResult,
+              },
+            });
+          } catch (error) {
+            this.client.send({
+              type: "llm.tool.call.response",
+              payload: {
+                requestId,
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+              },
+            });
+          }
+        } else {
+          this.client.send({
+            type: "llm.tool.call.response",
+            payload: {
+              requestId,
+              success: false,
+              error: `No handler registered for tool: ${toolName}`,
+            },
+          });
+        }
+      } else {
+        console.error("[SDK] Invalid llm.tool.call payload:", result.issues);
+      }
+    });
+  }
+}

package/src/logs/channel/IFrameLogChannelAdapter.ts

@@ -0,0 +1,44 @@
+import {
+  LogsWrite,
+  type IFrameClient,
+  type LogLevel,
+} from "../../messages/index.js";
+import type { ILogChannelAdapter } from "./ILogChannelAdapter.js";
+
+export class IFrameLogChannelAdapter implements ILogChannelAdapter {
+  constructor(private readonly client: IFrameClient) {}
+
+  public writeLog(
+    channelName: string,
+    level: LogLevel,
+    ...args: unknown[]
+  ): void {
+    // just stringify the args for transmission
+    const messageString: string = args
+      .map((arg) => {
+        if (typeof arg === "string") {
+          return arg;
+        } else if (arg instanceof Error) {
+          return `Error: ${arg.message}\n${arg.stack}`;
+        } else {
+          try {
+            return JSON.stringify(arg);
+          } catch {
+            return String(arg);
+          }
+        }
+      })
+      .join(" ");
+
+    this.client
+      .sendAndWait(
+        "logs.write",
+        { level, channelName, args: [messageString] },
+        LogsWrite.Request,
+        LogsWrite.Response
+      )
+      .catch((error) => {
+        console.error("Failed to write log:", error);
+      });
+  }
+}

package/src/logs/channel/ILogChannelAdapter.ts

@@ -0,0 +1,5 @@
+import type { LogLevel } from "../../messages/index.js";
+
+export interface ILogChannelAdapter {
+  writeLog(channelName: string, level: LogLevel, ...args: unknown[]): void;
+}

package/src/logs/channel/LogChannel.ts

@@ -0,0 +1,49 @@
+/**
+ * A log channel for categorizing log messages.
+ * Created via `sdk.logs.createChannel("channelName")`.
+ */
+
+import { type LogLevel } from "../../messages/index.js";
+import type { ILogChannelAdapter } from "./ILogChannelAdapter.js";
+
+export class LogChannel {
+  constructor(
+    private readonly channelName: string,
+    private readonly logChannelAdapters: ILogChannelAdapter[]
+  ) {}
+
+  /** Write a log message at the specified level */
+  private writeLog(
+    channelName: string,
+    level: LogLevel,
+    args: unknown[]
+  ): void {
+    for (const logChannelAdapter of this.logChannelAdapters) {
+      try {
+        logChannelAdapter.writeLog(channelName, level, ...args);
+      } catch (error) {
+        console.error(`LogChannel failed to write log via adapter: ${error}`);
+      }
+    }
+  }
+
+  /** Log at debug level */
+  debug(...args: unknown[]): void {
+    this.writeLog(this.channelName, "debug", args);
+  }
+
+  /** Log at info level */
+  info(...args: unknown[]): void {
+    this.writeLog(this.channelName, "info", args);
+  }
+
+  /** Log at warn level */
+  warn(...args: unknown[]): void {
+    this.writeLog(this.channelName, "warn", args);
+  }
+
+  /** Log at error level */
+  error(...args: unknown[]): void {
+    this.writeLog(this.channelName, "error", args);
+  }
+}

package/src/logs/outputs/types.ts

@@ -0,0 +1,21 @@
+export type LogLine = {
+  timestamp: number;
+  message: string;
+  level: "info" | "warn" | "error" | "debug";
+};
+
+export type LogSource =
+  | {
+      owner: "host";
+      source: "frontend" | "backend";
+    }
+  | {
+      owner: "plugin";
+      pluginId: string;
+      channelName: string;
+    };
+
+export type LogCollection = {
+  source: LogSource;
+  lines: LogLine[];
+};

package/src/messages/IFrameClient.ts

@@ -0,0 +1,113 @@
+import { v4 } from "uuid";
+import { safeParse, type GenericSchema, type InferOutput } from "valibot";
+import { IFrameMessageBus } from "./IFrameMessageBus.js";
+
+/**
+ * A typed request/response client for iframe communication.
+ * Handles message correlation, schema validation, and async coordination.
+ */
+export class IFrameClient {
+  private messageBus: IFrameMessageBus;
+  private pendingRequests = new Map<string, (response: any) => void>();
+
+  constructor() {
+    this.messageBus = new IFrameMessageBus();
+  }
+
+  init() {
+    this.messageBus.init();
+    this.messageBus.subscribeToParentWindow(this.handleMessage);
+  }
+
+  destroy() {
+    this.messageBus.destroy();
+    this.pendingRequests.clear();
+  }
+
+  /**
+   * Subscribe to raw messages from the host.
+   * Used for event-based messages (not request/response).
+   */
+  subscribe(callback: (evt: MessageEvent) => void): () => void {
+    return this.messageBus.subscribeToParentWindow(callback);
+  }
+
+  /**
+   * Send a raw message to the host (no response expected).
+   */
+  send(message: any): void {
+    this.messageBus.sendToParentWindow(message);
+  }
+
+  /**
+   * Send a validated request and wait for a validated response.
+   *
+   * @param type - Message type (e.g., "vfs.readFile")
+   * @param payload - Request payload (without requestId)
+   * @param reqSchema - Valibot schema for request validation
+   * @param resSchema - Valibot schema for response validation
+   * @returns Promise resolving to the validated response payload
+   */
+  async sendAndWait<
+    TReqSchema extends GenericSchema<any, any>,
+    TResSchema extends GenericSchema<any, any>
+  >(
+    type: string,
+    payload: any,
+    reqSchema: TReqSchema,
+    resSchema: TResSchema
+  ): Promise<InferOutput<TResSchema>["payload"]> {
+    const requestId = v4();
+    const message = {
+      type,
+      payload: {
+        requestId,
+        ...payload,
+      },
+    };
+
+    console.log(`[SDK] Sending request ${type}:`, message);
+
+    // Validate Request
+    const reqResult = safeParse(reqSchema, message);
+    if (!reqResult.success) {
+      console.error(
+        `[SDK] Invalid request shape for ${type}:`,
+        reqResult.issues
+      );
+      throw new Error(`Invalid request shape for ${type}`);
+    }
+
+    return new Promise((resolve, reject) => {
+      this.pendingRequests.set(requestId, (response: any) => {
+        // Validate Response
+        const resResult = safeParse(resSchema, response);
+        if (!resResult.success) {
+          console.error(
+            `[SDK] Invalid response shape for ${type}:`,
+            resResult.issues
+          );
+          reject(new Error(`Invalid response shape for ${type}`));
+          return;
+        }
+        resolve(resResult.output.payload);
+      });
+
+      this.messageBus.sendToParentWindow(message);
+    });
+  }
+
+  private handleMessage = (evt: MessageEvent) => {
+    console.log("Received message:", evt.data);
+    const { type, payload } = evt.data || {};
+    if (!type) return;
+
+    if (type.endsWith(".response") && payload?.requestId) {
+      const resolve = this.pendingRequests.get(payload.requestId);
+      if (resolve) {
+        resolve({ type, payload });
+        this.pendingRequests.delete(payload.requestId);
+      }
+    }
+  };
+}

package/src/messages/IFrameMessageBus.ts

@@ -0,0 +1,28 @@
+export class IFrameMessageBus {
+  private subscribers = new Set<(evt: MessageEvent) => void>();
+  private handleMessage = (evt: MessageEvent) => {
+    this.subscribers.forEach((sub) => sub(evt));
+  };
+
+  constructor() {}
+
+  init() {
+    window.addEventListener("message", this.handleMessage);
+  }
+
+  destroy() {
+    window.removeEventListener("message", this.handleMessage);
+    this.subscribers.clear();
+  }
+
+  subscribeToParentWindow(callback: (evt: MessageEvent) => void) {
+    this.subscribers.add(callback);
+    return () => {
+      this.subscribers.delete(callback);
+    };
+  }
+
+  sendToParentWindow(message: any) {
+    window.parent.postMessage(message, "*");
+  }
+}

package/src/messages/base/index.ts

@@ -0,0 +1,16 @@
+import { object, string, literal, type ObjectEntries } from "valibot";
+
+export const respondableMessage = <
+  TType extends string,
+  T extends ObjectEntries
+>(
+  type: TType,
+  entries: T
+) =>
+  object({
+    type: literal(type),
+    payload: object({
+      requestId: string(),
+      ...entries,
+    }),
+  });

package/src/messages/document/index.ts

@@ -0,0 +1,4 @@
+export * from "./requestContent/message.schemas.js";
+export * from "./save/message.schemas.js";
+export * from "./saveRequested/message.schemas.js";
+export * from "./saved/message.schemas.js";

package/src/messages/document/requestContent/message.schemas.ts

@@ -0,0 +1,28 @@
+import * as v from "valibot";
+import { respondableMessage } from "../../base/index.js";
+
+/**
+ * document.requestContent - Plugin → Host
+ * Plugin requests initial content when ready.
+ */
+export const DocumentRequestContent = {
+  Request: respondableMessage("document.requestContent", {}),
+  Response: v.union([
+    respondableMessage("document.requestContent.response", {
+      success: v.literal(true),
+      content: v.string(),
+      hash: v.string(),
+    }),
+    respondableMessage("document.requestContent.response", {
+      success: v.literal(false),
+      error: v.string(),
+    }),
+  ]),
+};
+
+export type DocumentRequestContentRequest = v.InferOutput<
+  typeof DocumentRequestContent.Request
+>;
+export type DocumentRequestContentResponse = v.InferOutput<
+  typeof DocumentRequestContent.Response
+>;

package/src/messages/document/save/index.ts

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

package/src/messages/document/save/message.schemas.ts

@@ -0,0 +1,24 @@
+import { string, literal, union, type InferOutput } from "valibot";
+import { respondableMessage } from "../../base/index.js";
+
+/**
+ * document.save - Plugin → Host
+ * Plugin requests the host to save the current document.
+ * Used when user presses Ctrl+S inside the plugin iframe.
+ */
+export const DocumentSave = {
+  Request: respondableMessage("document.save", {}),
+  Response: union([
+    respondableMessage("document.save.response", {
+      success: literal(true),
+      hash: string(),
+    }),
+    respondableMessage("document.save.response", {
+      success: literal(false),
+      error: string(),
+    }),
+  ]),
+};
+
+export type DocumentSaveRequest = InferOutput<typeof DocumentSave.Request>;
+export type DocumentSaveResponse = InferOutput<typeof DocumentSave.Response>;

package/src/messages/document/saveRequested/message.schemas.ts

@@ -0,0 +1,35 @@
+import { string, literal, union, type InferOutput } from "valibot";
+import { respondableMessage } from "../../base/index.js";
+
+/**
+ * document.saveRequested - Host → Plugin
+ * Sent when the host wants to save the document.
+ * The plugin should respond with the current content.
+ */
+export const DocumentSaveRequested = {
+  /**
+   * Host sends this to request the current document content for saving.
+   */
+  Request: respondableMessage("document.saveRequested", {}),
+  /**
+   * Plugin responds with the current content to be saved.
+   */
+  Response: union([
+    respondableMessage("document.saveRequested.response", {
+      success: literal(true),
+      /** The current document content to save */
+      content: string(),
+    }),
+    respondableMessage("document.saveRequested.response", {
+      success: literal(false),
+      error: string(),
+    }),
+  ]),
+};
+
+export type DocumentSaveRequestedRequest = InferOutput<
+  typeof DocumentSaveRequested.Request
+>;
+export type DocumentSaveRequestedResponse = InferOutput<
+  typeof DocumentSaveRequested.Response
+>;

package/src/messages/document/saved/message.schemas.ts

@@ -0,0 +1,29 @@
+import { string, literal, union, type InferOutput } from "valibot";
+import { respondableMessage } from "../../base/index.js";
+
+/**
+ * document.saved - Host → Plugin
+ * Sent after the host has successfully saved the document.
+ * The plugin can use this to update its internal state (e.g., clear undo history marker).
+ */
+export const DocumentSaved = {
+  /**
+   * Host sends this to notify the plugin that the save was successful.
+   */
+  Request: respondableMessage("document.saved", {
+    /** The hash of the saved content */
+    hash: string(),
+  }),
+  Response: union([
+    respondableMessage("document.saved.response", {
+      success: literal(true),
+    }),
+    respondableMessage("document.saved.response", {
+      success: literal(false),
+      error: string(),
+    }),
+  ]),
+};
+
+export type DocumentSavedRequest = InferOutput<typeof DocumentSaved.Request>;
+export type DocumentSavedResponse = InferOutput<typeof DocumentSaved.Response>;

package/src/messages/editor/index.ts

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

package/src/messages/editor/openFile/message.schemas.ts

@@ -0,0 +1,22 @@
+import { string, type InferOutput, literal, union } from "valibot";
+import { respondableMessage } from "../../base/index.js";
+
+export const EditorOpenFile = {
+  Request: respondableMessage("editor.openFile", {
+    path: string(),
+  }),
+  Response: union([
+    respondableMessage("editor.openFile.response", {
+      success: literal(true),
+    }),
+    respondableMessage("editor.openFile.response", {
+      success: literal(false),
+      error: string(),
+    }),
+  ]),
+};
+
+export type EditorOpenFileRequest = InferOutput<typeof EditorOpenFile.Request>;
+export type EditorOpenFileResponse = InferOutput<
+  typeof EditorOpenFile.Response
+>;

package/src/messages/fs/fileChanged/message.schemas.ts

@@ -0,0 +1,12 @@
+import { string, type InferOutput, object, union, literal } from "valibot";
+
+// Broadcast message for file change events
+export const FsFileChangedSchema = object({
+  type: literal("fs.fileChanged"),
+  payload: object({
+    path: string(),
+    kind: union([literal("created"), literal("modified"), literal("deleted")]),
+  }),
+});
+
+export type FsFileChanged = InferOutput<typeof FsFileChangedSchema>;

package/src/messages/fs/index.ts

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

package/src/messages/fs/subscribe/message.schemas.ts

@@ -0,0 +1,33 @@
+import { string, type InferOutput, literal, union } from "valibot";
+import { respondableMessage } from "../../base/index.js";
+
+export const FsSubscribe = {
+  Request: respondableMessage("fs.subscribe", {}),
+  Response: union([
+    respondableMessage("fs.subscribe.response", {
+      success: literal(true),
+    }),
+    respondableMessage("fs.subscribe.response", {
+      success: literal(false),
+      error: string(),
+    }),
+  ]),
+};
+
+export const FsUnsubscribe = {
+  Request: respondableMessage("fs.unsubscribe", {}),
+  Response: union([
+    respondableMessage("fs.unsubscribe.response", {
+      success: literal(true),
+    }),
+    respondableMessage("fs.unsubscribe.response", {
+      success: literal(false),
+      error: string(),
+    }),
+  ]),
+};
+
+export type FsSubscribeRequest = InferOutput<typeof FsSubscribe.Request>;
+export type FsSubscribeResponse = InferOutput<typeof FsSubscribe.Response>;
+export type FsUnsubscribeRequest = InferOutput<typeof FsUnsubscribe.Request>;
+export type FsUnsubscribeResponse = InferOutput<typeof FsUnsubscribe.Response>;