openbot 0.2.13 → 0.3.0

package/src/plugins/ui/index.ts

@@ -0,0 +1,227 @@
+import { MelonyPlugin } from 'melony';
+import z from 'zod';
+import type { Plugin } from '../../bus/plugin.js';
+import {
+  OpenBotEvent,
+  OpenBotState,
+  RenderUIWidgetData,
+  UIWidgetField,
+  UIWidgetListItem,
+  UIWidgetSpec,
+} from '../../app/types.js';
+
+const actionSchema = z.object({
+  id: z.string().describe('Stable action ID returned by client:ui:widget:response.'),
+  label: z.string().describe('Human-readable button label.'),
+  value: z.unknown().optional().describe('Optional machine-readable value for this action.'),
+  variant: z.enum(['primary', 'secondary', 'danger']).optional(),
+  disabled: z.boolean().optional(),
+});
+
+const optionSchema = z.object({
+  label: z.string(),
+  value: z.string(),
+});
+
+const fieldSchema = z.object({
+  id: z.string().describe('Stable field ID used as the submitted value key.'),
+  label: z.string(),
+  type: z.enum(['text', 'textarea', 'number', 'boolean', 'select', 'multiselect', 'date']),
+  description: z.string().optional(),
+  placeholder: z.string().optional(),
+  required: z.boolean().optional(),
+  options: z.array(optionSchema).optional(),
+  defaultValue: z.unknown().optional(),
+});
+
+const listItemSchema = z.object({
+  id: z.string(),
+  label: z.string(),
+  description: z.string().optional(),
+  status: z.enum(['pending', 'in_progress', 'done', 'error', 'cancelled']).optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+});
+
+const widgetBaseSchema = {
+  widgetId: z.string().optional().describe('Stable widget ID. Defaults from toolCallId.'),
+  title: z.string().optional(),
+  description: z.string().optional(),
+  body: z.string().optional(),
+  state: z.enum(['open', 'submitted', 'cancelled', 'error']).optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+};
+
+const renderWidgetSchema = z.union([
+  z.object({
+    ...widgetBaseSchema,
+    kind: z.literal('message'),
+    actions: z.array(actionSchema).optional(),
+  }),
+  z.object({
+    ...widgetBaseSchema,
+    kind: z.literal('choice'),
+    actions: z.array(actionSchema).min(1),
+  }),
+  z.object({
+    ...widgetBaseSchema,
+    kind: z.literal('form'),
+    fields: z.array(fieldSchema).optional(),
+    submitLabel: z.string().optional(),
+    actions: z.array(actionSchema).optional(),
+    props: z.record(z.string(), z.unknown()).optional(),
+  }),
+  z.object({
+    ...widgetBaseSchema,
+    kind: z.literal('list'),
+    items: z.array(listItemSchema).optional(),
+    actions: z.array(actionSchema).optional(),
+  }),
+  z.object({
+    kind: z.enum(['approval', 'todo_list']).describe('Legacy preset. Prefer choice or list.'),
+    widgetId: z.string().optional(),
+    title: z.string().optional(),
+    props: z.record(z.string(), z.unknown()).optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+  }),
+]);
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  !!value && typeof value === 'object' && !Array.isArray(value);
+
+const readString = (value: unknown): string | undefined =>
+  typeof value === 'string' && value.trim() ? value : undefined;
+
+const asFields = (value: unknown): UIWidgetField[] | undefined =>
+  Array.isArray(value) ? (value as UIWidgetField[]) : undefined;
+
+const asListItems = (value: unknown): UIWidgetListItem[] | undefined =>
+  Array.isArray(value) ? (value as UIWidgetListItem[]) : undefined;
+
+const todoToListItem = (todo: unknown, index: number): UIWidgetListItem => {
+  if (!isRecord(todo)) {
+    return { id: `todo_${index + 1}`, label: String(todo) };
+  }
+  return {
+    id: readString(todo.id) || `todo_${index + 1}`,
+    label:
+      readString(todo.label) ||
+      readString(todo.task) ||
+      readString(todo.title) ||
+      `Todo ${index + 1}`,
+    description: readString(todo.description),
+    status: readString(todo.status) as UIWidgetListItem['status'],
+    metadata: todo,
+  };
+};
+
+const createWidgetId = (data: RenderUIWidgetData, toolCallId?: string): string => {
+  if ('widgetId' in data && data.widgetId) return data.widgetId;
+  if (toolCallId) return `widget_${toolCallId}`;
+  return `widget_${Date.now()}`;
+};
+
+const normalizeWidget = (
+  data: RenderUIWidgetData,
+  state: OpenBotState,
+  toolCallId?: string,
+): UIWidgetSpec => {
+  const widgetId = createWidgetId(data, toolCallId);
+
+  if (data.kind === 'approval') {
+    const props = data.props || {};
+    return {
+      widgetId,
+      kind: 'choice',
+      title: data.title || 'Approval Required',
+      body:
+        readString(props.message) ||
+        readString(props.summary) ||
+        'Please approve or deny this action.',
+      metadata: {
+        ...(data.metadata || {}),
+        legacyKind: 'approval',
+        actionId: props.actionId,
+      },
+      actions: [
+        { id: 'approve', label: 'Approve', value: props.actionId || 'approve', variant: 'primary' },
+        { id: 'deny', label: 'Deny', value: props.actionId || 'deny', variant: 'danger' },
+      ],
+    };
+  }
+
+  if (data.kind === 'todo_list') {
+    const props = data.props || {};
+    const stateTodos = isRecord(state.threadDetails?.state)
+      ? (state.threadDetails.state as Record<string, unknown>).todos
+      : undefined;
+    const todos = asListItems(props.todos) || asListItems(stateTodos) || [];
+    return {
+      widgetId,
+      kind: 'list',
+      title: data.title || readString(props.title) || 'Task List',
+      description: readString(props.description),
+      metadata: { ...(data.metadata || {}), legacyKind: 'todo_list' },
+      items: todos.map(todoToListItem),
+    };
+  }
+
+  if (data.kind === 'form') {
+    const propsSource = (data as unknown as { props?: unknown }).props;
+    const props = isRecord(propsSource) ? propsSource : {};
+    return {
+      widgetId,
+      kind: 'form',
+      title: data.title || 'Details Required',
+      description: data.description,
+      body: data.body,
+      state: data.state,
+      metadata: data.metadata,
+      fields: data.fields || asFields(props.schema) || [],
+      submitLabel: data.submitLabel || readString(props.submitLabel),
+      actions: data.actions,
+    };
+  }
+
+  if (data.kind === 'list') {
+    return { ...data, widgetId, title: data.title || 'Task List', items: data.items || [] };
+  }
+
+  if (data.kind === 'choice') {
+    return { ...data, widgetId, title: data.title || 'Choose an Option' };
+  }
+
+  if (data.kind === 'message') {
+    return { ...data, widgetId, title: data.title || 'Message' };
+  }
+
+  throw new Error(`Unsupported UI widget kind: ${(data as { kind?: string }).kind || 'unknown'}`);
+};
+
+const uiToolDefinitions = {
+  render_ui_widget: {
+    description:
+      'Render a small server-driven UI widget in the conversation. Prefer primitive kinds: message, choice, form, or list. Legacy presets approval and todo_list are accepted.',
+    inputSchema: renderWidgetSchema,
+  },
+};
+
+const uiPluginRuntime = (): MelonyPlugin<OpenBotState, OpenBotEvent> => (builder) => {
+  builder.on('action:render_ui_widget', async function* (event, context) {
+    const widget = normalizeWidget(event.data, context.state, event.meta?.toolCallId);
+    yield {
+      type: 'client:ui:widget',
+      data: widget,
+      meta: event.meta,
+    };
+  });
+};
+
+export const uiPlugin: Plugin = {
+  id: 'ui',
+  name: 'UI Widgets',
+  description: 'Render server-driven UI widgets (messages, choices, forms, lists) in the conversation.',
+  toolDefinitions: uiToolDefinitions,
+  factory: () => uiPluginRuntime(),
+};
+
+export default uiPlugin;

package/src/registry/plugins.ts

@@ -1,85 +1,136 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { MelonyPlugin } from 'melony';
-import { OpenBotEvent, OpenBotState } from '../app/types.js';
-import { aiSdkPlugin } from '../plugins/ai-sdk.js';
-import { storagePlugin } from '../plugins/storage.js';
-import { storageService } from '../services/storage.js';
-import { DEFAULT_BASE_DIR, loadConfig, resolvePath } from '../app/config.js';
-import { delegationPlugin } from '../plugins/delegation.js';
-import { mcpPlugin } from '../plugins/mcp.js';
-import { uiPlugin } from '../plugins/ui.js';
-import { orchestratorService } from '../harness/orchestrator.js';
+import type { Plugin } from '../bus/plugin.js';
+import { aiSdkPlugin } from '../plugins/ai-sdk/index.js';
+import { shellPlugin } from '../plugins/shell/index.js';
+import { mcpPlugin } from '../plugins/mcp/index.js';
+import { delegationPlugin } from '../plugins/delegation/index.js';
+import { storageToolsPlugin } from '../plugins/storage-tools/index.js';
+import { uiPlugin } from '../plugins/ui/index.js';
+import { approvalPlugin } from '../plugins/approval/index.js';
+import { DEFAULT_PLUGINS_DIR, DEFAULT_BASE_DIR, loadConfig, resolvePath } from '../app/config.js';
 
 let pluginsDir: string | null = null;
 const loadedPlugins = new Set<string>();
+const cache = new Map<string, Plugin>();
+
+const BUILT_IN: Record<string, Plugin> = {
+  [aiSdkPlugin.id]: aiSdkPlugin,
+  [shellPlugin.id]: shellPlugin,
+  [mcpPlugin.id]: mcpPlugin,
+  [delegationPlugin.id]: delegationPlugin,
+  [storageToolsPlugin.id]: storageToolsPlugin,
+  [uiPlugin.id]: uiPlugin,
+  [approvalPlugin.id]: approvalPlugin,
+};
 
 /**
- * Initializes the plugins directory.
+ * Parsed shape of a community plugin module. The `id` is intentionally omitted:
+ * the canonical id is the npm package name (== folder under `plugins/`),
+ * assigned by the caller.
  */
+export type ParsedPluginModule = Omit<Plugin, 'id'>;
+
+/** Normalize a dynamically imported plugin module. Supports `plugin`, `default`. */
+export function parsePluginModule(
+  module: Record<string, unknown>,
+): ParsedPluginModule | null {
+  const raw =
+    (module.plugin as Record<string, unknown> | undefined) ??
+    (module.default as Record<string, unknown> | undefined);
+
+  if (!raw || typeof raw !== 'object') return null;
+
+  const factory = raw.factory;
+  if (typeof factory !== 'function') return null;
+
+  const name = typeof raw.name === 'string' ? raw.name : '';
+  const description = typeof raw.description === 'string' ? raw.description : '';
+  const image = typeof raw.image === 'string' ? raw.image : undefined;
+  const defaultInstructions =
+    typeof raw.defaultInstructions === 'string' ? raw.defaultInstructions : undefined;
+  const configSchema = raw.configSchema as Plugin['configSchema'];
+  const toolDefinitions = raw.toolDefinitions as Plugin['toolDefinitions'];
+
+  return {
+    name,
+    description,
+    image,
+    defaultInstructions,
+    configSchema,
+    toolDefinitions,
+    factory: factory as Plugin['factory'],
+  };
+}
+
+/** Initialize the on-disk plugins directory (defaults to ~/.openbot/plugins). */
 export function initPlugins(dir?: string) {
   if (dir) {
     pluginsDir = dir;
   } else {
     const config = loadConfig();
     const baseDir = config.baseDir || DEFAULT_BASE_DIR;
-    pluginsDir = path.join(resolvePath(baseDir), 'plugins');
+    pluginsDir = path.join(resolvePath(baseDir), DEFAULT_PLUGINS_DIR);
   }
 }
 
 /**
- * Resolves a plugin from its name and config.
+ * Resolve a Plugin by id. The id is either:
+ *   - a built-in id (e.g. "ai-sdk", "shell"), or
+ *   - an npm package name (e.g. "openbot-plugin-foo" or "@scope/foo"),
+ *     in which case the folder layout is `plugins/<id>/dist/index.js`.
  */
-export async function resolvePlugin(
-  pluginName: string,
-  config: any = {},
-): Promise<MelonyPlugin<OpenBotState, OpenBotEvent> | null> {
-  // 1. Built-in plugins
-  switch (pluginName) {
-    case 'storage':
-      return storagePlugin({ storage: storageService, ...config });
-    case 'ai-sdk':
-      return aiSdkPlugin({
-        storage: storageService,
-        ...config,
-      });
-    case 'delegation':
-      return delegationPlugin();
-    case 'mcp':
-      return mcpPlugin();
-    case 'ui':
-      return uiPlugin();
+export async function resolvePlugin(id: string): Promise<Plugin | null> {
+  if (cache.has(id)) return cache.get(id)!;
+  if (BUILT_IN[id]) {
+    cache.set(id, BUILT_IN[id]);
+    return BUILT_IN[id];
   }
 
-  // 2. Search for external plugins in the initialized plugins directory
   if (!pluginsDir) {
     initPlugins();
   }
+  if (!pluginsDir) return null;
+
+  const distPath = path.join(pluginsDir, id, 'dist', 'index.js');
 
-  if (pluginsDir) {
-    const pluginDir = path.resolve(pluginsDir, pluginName);
-    const distPath = path.join(pluginDir, 'dist', 'index.js');
-
-    if (fs.existsSync(distPath)) {
-      try {
-        // Dynamic import needs file:// URL for absolute paths
-        const module = await import(pathToFileURL(distPath).href);
-        const factory = module.plugin.factory;
-
-        if (typeof factory === 'function') {
-          if (!loadedPlugins.has(pluginName)) {
-            console.log(`[plugins] Loaded community plugin "${pluginName}" from ${distPath}`);
-            loadedPlugins.add(pluginName);
-          }
-          return factory(config);
-        }
-      } catch (e) {
-        console.warn(`[plugins] Failed to load plugin "${pluginName}" from ${distPath}:`, e);
-      }
+  if (!fs.existsSync(distPath)) {
+    console.warn(`[plugins] Plugin "${id}" not found at ${distPath}.`);
+    return null;
+  }
+
+  try {
+    const module = await import(pathToFileURL(distPath).href);
+    const parsed = parsePluginModule(module as Record<string, unknown>);
+    if (!parsed) {
+      console.warn(`[plugins] Plugin "${id}" at ${distPath} has no recognizable export.`);
+      return null;
     }
+    const plugin: Plugin = { id, ...parsed, name: parsed.name || id };
+    cache.set(id, plugin);
+    if (!loadedPlugins.has(id)) {
+      console.log(`[plugins] Loaded community plugin "${id}" from ${distPath}`);
+      loadedPlugins.add(id);
+    }
+    return plugin;
+  } catch (e) {
+    console.warn(`[plugins] Failed to load plugin "${id}" from ${distPath}:`, e);
+    return null;
   }
+}
+
+/** Drop a single id from the in-memory cache (e.g. after fresh install). */
+export function invalidatePlugin(id: string): void {
+  cache.delete(id);
+  loadedPlugins.delete(id);
+}
+
+/** List built-in plugins (for marketplace/registry views). */
+export function listBuiltInPlugins(): Plugin[] {
+  return Object.values(BUILT_IN);
+}
 
-  console.warn(`[plugins] Plugin "${pluginName}" not found in registry or external directory.`);
-  return null;
+export function getPluginsDir(): string | null {
+  return pluginsDir;
 }

package/src/services/plugins.ts

@@ -0,0 +1,133 @@
+import fs from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+import {
+  DEFAULT_PLUGINS_DIR,
+  DEFAULT_BASE_DIR,
+  loadConfig,
+  resolvePath,
+} from '../app/config.js';
+import { invalidatePlugin } from '../registry/plugins.js';
+
+const execAsync = promisify(exec);
+
+export interface InstallOptions {
+  packageName: string;
+  version?: string;
+}
+
+export interface InstalledPlugin {
+  /** npm package name; doubles as the plugin id used everywhere else. */
+  name: string;
+  version: string;
+}
+
+const getPluginsDir = (): string => {
+  const config = loadConfig();
+  const baseDir = resolvePath(config.baseDir || DEFAULT_BASE_DIR);
+  return path.join(baseDir, DEFAULT_PLUGINS_DIR);
+};
+
+/**
+ * Lifecycle for community-built plugins distributed via npm.
+ * Each plugin is installed to `<plugins>/<npm-name>/` and is identified
+ * everywhere (AGENT.md `plugins[].id`, registry, runtime resolution) by its
+ * npm name. Scoped packages (`@scope/foo`) live under `<plugins>/@scope/foo/`.
+ */
+export const pluginService = {
+  isInstalled: async (packageName: string): Promise<boolean> => {
+    const finalPath = path.join(getPluginsDir(), packageName);
+    return existsSync(path.join(finalPath, 'dist', 'index.js'));
+  },
+
+  install: async ({ packageName, version }: InstallOptions): Promise<InstalledPlugin> => {
+    const pluginsDir = getPluginsDir();
+    await fs.mkdir(pluginsDir, { recursive: true });
+
+    const finalPath = path.join(pluginsDir, packageName);
+
+    if (existsSync(path.join(finalPath, 'package.json'))) {
+      try {
+        const pkgJson = JSON.parse(
+          await fs.readFile(path.join(finalPath, 'package.json'), 'utf-8'),
+        );
+        if (!version || pkgJson.version === version) {
+          console.log(
+            `[plugins] ${packageName}${version ? `@${version}` : ''} is already installed.`,
+          );
+          return { name: pkgJson.name, version: pkgJson.version };
+        }
+      } catch {
+        // corrupted; reinstall below
+      }
+    }
+
+    const target = version ? `${packageName}@${version}` : packageName;
+    console.log(`[plugins] Installing ${target} to ${pluginsDir}...`);
+
+    const tempDir = path.join(pluginsDir, '.tmp_' + Date.now());
+    try {
+      await fs.mkdir(tempDir, { recursive: true });
+      await execAsync(`npm install ${target} --no-save --prefix "${tempDir}"`);
+
+      const installedPath = path.join(tempDir, 'node_modules', packageName);
+      if (!existsSync(installedPath)) {
+        throw new Error(`npm did not produce ${installedPath}`);
+      }
+
+      await fs.mkdir(path.dirname(finalPath), { recursive: true });
+      await fs.rm(finalPath, { recursive: true, force: true });
+      await fs.rename(installedPath, finalPath);
+
+      console.log(`[plugins] Running npm install in ${finalPath}...`);
+      try {
+        await execAsync(`npm install`, { cwd: finalPath });
+        console.log(`[plugins] npm install completed in ${finalPath}`);
+      } catch (e) {
+        console.warn(`[plugins] Failed to run npm install in ${finalPath}:`, e);
+      }
+
+      const pkgJson = JSON.parse(
+        await fs.readFile(path.join(finalPath, 'package.json'), 'utf-8'),
+      );
+
+      invalidatePlugin(packageName);
+      return { name: pkgJson.name, version: pkgJson.version };
+    } catch (error) {
+      console.error(`[plugins] Failed to install ${packageName}:`, error);
+      throw new Error(
+        `Failed to install plugin ${packageName}: ${(error as Error).message}`,
+      );
+    } finally {
+      await fs.rm(tempDir, { recursive: true, force: true }).catch(() => {});
+    }
+  },
+
+  uninstall: async (packageName: string): Promise<void> => {
+    const pluginsDir = getPluginsDir();
+    const pluginPath = path.join(pluginsDir, packageName);
+
+    try {
+      await fs.rm(pluginPath, { recursive: true, force: true });
+      invalidatePlugin(packageName);
+      console.log(`[plugins] Uninstalled plugin ${packageName}`);
+
+      if (packageName.startsWith('@')) {
+        const scopeDir = path.dirname(pluginPath);
+        try {
+          const remaining = await fs.readdir(scopeDir);
+          if (remaining.length === 0) await fs.rmdir(scopeDir);
+        } catch {
+          // ignore
+        }
+      }
+    } catch (error) {
+      console.error(`[plugins] Failed to uninstall ${packageName}:`, error);
+      throw new Error(
+        `Failed to uninstall plugin ${packageName}: ${(error as Error).message}`,
+      );
+    }
+  },
+};