openbot 0.2.14 → 0.3.1

package/src/plugins/approval/index.ts

@@ -0,0 +1,228 @@
+import { MelonyPlugin } from 'melony';
+import type { Plugin } from '../../bus/plugin.js';
+import { OpenBotEvent, OpenBotState } from '../../app/types.js';
+import { storageService } from '../../services/storage.js';
+
+/**
+ * `approval` — gates protected tool calls behind a UI confirmation widget.
+ *
+ * Configuration is read from the per-agent plugin config in AGENT.md:
+ * ```yaml
+ * plugins:
+ *   - id: approval
+ *     config:
+ *       rules:
+ *         - action: action:shell_exec
+ *           message: The agent wants to run a terminal command.
+ *           detailKeys: [command, cwd, shell, timeoutMs]
+ * ```
+ */
+
+export type ApprovalRule = {
+  action: string;
+  message?: string;
+  detailKeys?: string[];
+  hiddenKeys?: string[];
+  executeEvent?: string;
+  denyEvent?: string;
+  denyData?: Record<string, unknown>;
+};
+
+export const DEFAULT_APPROVAL_RULES: ApprovalRule[] = [
+  {
+    action: 'action:shell_exec',
+    denyEvent: 'action:shell_exec:result',
+    message: 'The agent wants to run a terminal command.',
+    detailKeys: ['command', 'cwd', 'shell', 'timeoutMs'],
+    hiddenKeys: ['env'],
+    denyData: {
+      exitCode: null,
+      stdout: '',
+      stderr: 'Command execution was denied by the user.',
+      timedOut: false,
+    },
+  },
+];
+
+type PendingApproval = {
+  id: string;
+  action: string;
+  executeEvent: string;
+  denyEvent: string;
+  denyData: Record<string, unknown>;
+  payload: Record<string, unknown>;
+  meta?: Record<string, unknown>;
+  message: string;
+  createdAt: string;
+  status: 'pending' | 'approved' | 'denied';
+};
+
+const asRecord = (value: unknown): Record<string, unknown> =>
+  value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+
+const getApprovalsFromState = (state: OpenBotState): Record<string, PendingApproval> => {
+  const source = state.threadDetails?.state ?? state.channelDetails?.state;
+  const stateRecord = asRecord(source);
+  return asRecord(stateRecord.approvals) as Record<string, PendingApproval>;
+};
+
+const persistApprovals = async (
+  state: OpenBotState,
+  approvals: Record<string, PendingApproval>,
+): Promise<void> => {
+  if (state.threadId) {
+    await storageService.patchThreadState({
+      channelId: state.channelId,
+      threadId: state.threadId,
+      state: { approvals },
+    });
+    return;
+  }
+  await storageService.patchChannelState({
+    channelId: state.channelId,
+    state: { approvals },
+  });
+};
+
+const buildApprovalPlugin =
+  (rules: ApprovalRule[]): MelonyPlugin<OpenBotState, OpenBotEvent> =>
+  (builder) => {
+    for (const rule of rules) {
+      builder.on(rule.action as OpenBotEvent['type'], async function* (event, context) {
+        const meta = asRecord(event.meta);
+        if (meta.approvalStatus === 'approved') return;
+
+        const eventData = asRecord((event as { data?: unknown }).data);
+        const eventMeta = meta;
+
+        const approvalId = `approval_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+        const widgetId = `widget_${approvalId}`;
+        const executeEvent = rule.executeEvent || rule.action;
+        const denyEvent = rule.denyEvent || `${rule.action}:result`;
+        const denyData = rule.denyData || {};
+        const hiddenKeys = new Set(rule.hiddenKeys || []);
+        const detailKeys = rule.detailKeys || Object.keys(eventData);
+        const details = detailKeys
+          .filter((key) => !hiddenKeys.has(key))
+          .map((key) => `- ${key}: ${String(eventData[key] ?? '')}`)
+          .join('\n');
+
+        const pendingApprovals = getApprovalsFromState(context.state);
+        pendingApprovals[approvalId] = {
+          id: approvalId,
+          action: rule.action,
+          executeEvent,
+          denyEvent,
+          denyData,
+          payload: eventData,
+          meta: eventMeta,
+          message: rule.message || `Approval required for ${rule.action}.`,
+          createdAt: new Date().toISOString(),
+          status: 'pending',
+        };
+        await persistApprovals(context.state, pendingApprovals);
+
+        yield {
+          type: 'client:ui:widget',
+          data: {
+            kind: 'choice',
+            widgetId,
+            title: 'Approval Required',
+            body: `${rule.message || 'A protected action requires approval.'}${
+              details ? `\n\n${details}` : ''
+            }`,
+            metadata: { type: 'approval:request', approvalId, action: rule.action },
+            actions: [
+              { id: 'approve', label: 'Approve', variant: 'primary' },
+              { id: 'deny', label: 'Deny', variant: 'danger' },
+            ],
+          },
+          meta: { ...(event.meta || {}), agentId: context.state.agentId },
+        } as OpenBotEvent;
+
+        yield {
+          type: 'agent:output',
+          data: { content: `Waiting for approval before running \`${rule.action}\`.` },
+          meta: { ...(event.meta || {}), agentId: context.state.agentId },
+        } as OpenBotEvent;
+
+        context.suspend();
+      });
+    }
+
+    builder.on('client:ui:widget:response', async function* (event, context) {
+      const metadata = asRecord(event.data?.metadata);
+      if (metadata.type !== 'approval:request') return;
+
+      const approvalId = String(metadata.approvalId || '');
+      if (!approvalId) return;
+
+      const approvals = getApprovalsFromState(context.state);
+      const approval = approvals[approvalId];
+      if (!approval || approval.status !== 'pending') {
+        yield {
+          type: 'agent:output',
+          data: { content: 'Approval request not found or already resolved.' },
+          meta: { ...(event.meta || {}), agentId: context.state.agentId },
+        } as OpenBotEvent;
+        return;
+      }
+
+      const approved = event.data.actionId === 'approve';
+      approvals[approvalId] = {
+        ...approval,
+        status: approved ? 'approved' : 'denied',
+      };
+      await persistApprovals(context.state, approvals);
+
+      if (approved) {
+        yield {
+          type: approval.executeEvent as OpenBotEvent['type'],
+          data: approval.payload,
+          meta: {
+            ...(approval.meta || {}),
+            approvalId,
+            approvalStatus: 'approved',
+          },
+        } as OpenBotEvent;
+        return;
+      }
+
+      yield {
+        type: approval.denyEvent as OpenBotEvent['type'],
+        data: {
+          success: false,
+          approved: false,
+          error: 'Action denied by user approval.',
+          ...approval.denyData,
+        },
+        meta: { ...(approval.meta || {}), approvalId },
+      } as OpenBotEvent;
+
+      yield {
+        type: 'agent:output',
+        data: { content: 'Action denied by user approval.' },
+        meta: { ...(event.meta || {}), agentId: context.state.agentId },
+      } as OpenBotEvent;
+    });
+  };
+
+const readRules = (config: Record<string, unknown>): ApprovalRule[] => {
+  const raw = config.rules;
+  if (!Array.isArray(raw)) return DEFAULT_APPROVAL_RULES;
+  return raw.filter(
+    (entry): entry is ApprovalRule =>
+      !!entry && typeof entry === 'object' && typeof (entry as { action?: unknown }).action === 'string',
+  );
+};
+
+export const approvalPlugin: Plugin = {
+  id: 'approval',
+  name: 'Approval',
+  description: 'Gate protected tool calls (e.g. shell_exec) behind a UI confirmation prompt.',
+  factory: ({ config }) => buildApprovalPlugin(readRules(config)),
+};
+
+export default approvalPlugin;

package/src/plugins/delegation/index.ts

@@ -0,0 +1,94 @@
+import { MelonyPlugin } from 'melony';
+import z from 'zod';
+import type { Plugin } from '../../bus/plugin.js';
+import { OpenBotEvent, OpenBotState } from '../../app/types.js';
+
+const delegationToolDefinitions = {
+  handoff: {
+    description:
+      'Transfer control to another agent. The target agent continues the task and you do not wait for a tool result.',
+    inputSchema: z.object({
+      agentId: z.string().describe('The ID of the target agent.'),
+      content: z.string().describe('The message or task to hand off.'),
+    }),
+  },
+  delegate: {
+    description:
+      'Delegate a subtask to another agent and wait for its result so you can continue.',
+    inputSchema: z.object({
+      agentId: z.string().describe('The ID of the target agent.'),
+      content: z.string().describe('The subtask you want the target agent to execute.'),
+    }),
+  },
+};
+
+const delegationPluginRuntime = (): MelonyPlugin<OpenBotState, OpenBotEvent> => (builder) => {
+  builder.on('action:handoff', async function* (event, context) {
+    const { agentId, content } = event.data;
+
+    yield {
+      type: 'agent:output',
+      data: { content: `Handing off to **${agentId}**: ${content}` },
+      meta: { ...(event.meta || {}), agentId: context.state.agentId },
+    };
+
+    yield {
+      type: 'handoff:request',
+      data: { agentId, content },
+      meta: { ...(event.meta || {}), agentId: context.state.agentId },
+    };
+
+    if (event.meta?.toolCallId) {
+      yield {
+        type: 'action:handoff:result',
+        data: { success: true, agentId, accepted: true },
+        meta: { ...(event.meta || {}), agentId: context.state.agentId },
+      };
+    }
+  });
+
+  builder.on('action:delegate', async function* (event, context) {
+    const { agentId, content } = event.data;
+    const widgetId = event.meta?.toolCallId
+      ? `delegate_${event.meta.toolCallId}`
+      : `delegate_${Date.now()}`;
+
+    yield {
+      type: 'client:ui:widget',
+      data: {
+        kind: 'message',
+        widgetId,
+        title: `Delegation started: ${agentId}`,
+        body: `Running delegated task in background.\n\n${content}`,
+        state: 'open',
+        metadata: {
+          type: 'delegation:status',
+          phase: 'started',
+          delegatedAgentId: agentId,
+        },
+      },
+      meta: { ...(event.meta || {}), agentId: context.state.agentId },
+    };
+
+    yield {
+      type: 'delegation:request',
+      data: { agentId, content },
+      meta: {
+        ...(event.meta || {}),
+        parentAgentId: context.state.agentId,
+        delegationWidgetId: widgetId,
+        agentId: context.state.agentId,
+      },
+    };
+  });
+};
+
+export const delegationPlugin: Plugin = {
+  id: 'delegation',
+  name: 'Delegation',
+  description: 'Hand off or delegate sub-tasks to other agents on the bus.',
+  toolDefinitions: delegationToolDefinitions,
+  factory: () => delegationPluginRuntime(),
+};
+
+export default delegationPlugin;

package/src/plugins/mcp/index.ts

@@ -0,0 +1,128 @@
+import { MelonyPlugin } from 'melony';
+import z from 'zod';
+import type { Plugin } from '../../bus/plugin.js';
+import { OpenBotEvent, OpenBotState } from '../../app/types.js';
+import { mcpService } from '../../harness/mcp.js';
+
+function stringifyResult(value: unknown): string {
+  if (typeof value === 'string') return value;
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return String(value);
+  }
+}
+
+const mcpToolDefinitions = {
+  mcp_list_tools: {
+    description:
+      'List available tools from a configured MCP server. Use this first before calling tools on an unknown server.',
+    inputSchema: z.object({
+      serverId: z.string().describe('Configured MCP server id (e.g. github, notion, linear).'),
+    }),
+  },
+  mcp_call: {
+    description:
+      'Call a tool on a configured MCP server. Provide tool arguments as a JSON object. Use mcp_list_tools first when uncertain.',
+    inputSchema: z.object({
+      serverId: z.string().describe('Configured MCP server id.'),
+      toolName: z.string().describe('Exact MCP tool name from mcp_list_tools.'),
+      args: z
+        .record(z.string(), z.unknown())
+        .default({})
+        .describe('Tool arguments as a JSON object.'),
+    }),
+  },
+};
+
+const mcpPluginRuntime = (): MelonyPlugin<OpenBotState, OpenBotEvent> => (builder) => {
+  builder.on('action:mcp_list_tools', async function* (event, context) {
+    const serverId = (event.data as { serverId?: string })?.serverId as string;
+
+    try {
+      const tools = await mcpService.listTools(serverId);
+      const toolNames = tools.map(
+        (tool) => `- ${tool.name}${tool.description ? `: ${tool.description}` : ''}`,
+      );
+
+      yield {
+        type: 'action:mcp_list_tools:result',
+        data: { success: true, serverId, tools },
+        meta: event.meta,
+      } as OpenBotEvent;
+
+      yield {
+        type: 'agent:output',
+        data: {
+          content:
+            toolNames.length > 0
+              ? `MCP tools available on \`${serverId}\`:\n${toolNames.join('\n')}`
+              : `MCP server \`${serverId}\` has no tools.`,
+        },
+        meta: { ...(event.meta || {}), agentId: context.state.agentId },
+      } as OpenBotEvent;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Unknown MCP error';
+      yield {
+        type: 'action:mcp_list_tools:result',
+        data: { success: false, serverId, tools: [], error: message },
+        meta: event.meta,
+      } as OpenBotEvent;
+      yield {
+        type: 'agent:output',
+        data: { content: `Failed to list MCP tools for \`${serverId}\`: ${message}` },
+        meta: { ...(event.meta || {}), agentId: context.state.agentId },
+      } as OpenBotEvent;
+    }
+  });
+
+  builder.on('action:mcp_call', async function* (event, context) {
+    const data = event.data as {
+      serverId?: string;
+      toolName?: string;
+      args?: Record<string, unknown>;
+    };
+    const serverId = data?.serverId as string;
+    const toolName = data?.toolName as string;
+    const args = (data?.args || {}) as Record<string, unknown>;
+
+    try {
+      const result = await mcpService.callTool(serverId, toolName, args);
+      const rendered = stringifyResult(result);
+
+      yield {
+        type: 'action:mcp_call:result',
+        data: { success: true, serverId, toolName, result },
+        meta: event.meta,
+      } as OpenBotEvent;
+
+      yield {
+        type: 'agent:output',
+        data: { content: `MCP \`${serverId}.${toolName}\` result:\n\n${rendered}` },
+        meta: { ...(event.meta || {}), agentId: context.state.agentId },
+      } as OpenBotEvent;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Unknown MCP error';
+      yield {
+        type: 'action:mcp_call:result',
+        data: { success: false, serverId, toolName, error: message },
+        meta: event.meta,
+      } as OpenBotEvent;
+      yield {
+        type: 'agent:output',
+        data: { content: `MCP call failed for \`${serverId}.${toolName}\`: ${message}` },
+        meta: { ...(event.meta || {}), agentId: context.state.agentId },
+      } as OpenBotEvent;
+    }
+  });
+};
+
+export const mcpPlugin: Plugin = {
+  id: 'mcp',
+  name: 'MCP',
+  description: 'Connect to Model Context Protocol servers and call their tools.',
+  toolDefinitions: mcpToolDefinitions,
+  factory: () => mcpPluginRuntime(),
+};
+
+export default mcpPlugin;

package/src/plugins/memory/index.ts

@@ -0,0 +1,85 @@
+import z from 'zod';
+import type { Plugin } from '../../bus/plugin.js';
+
+/**
+ * `memory` — exposes the global memory store as agent tools.
+ *
+ * The actual handlers live in `bus/services.ts` because memory is platform
+ * infrastructure (shared across every agent on the bus); this plugin only
+ * contributes the tool definitions so a runtime plugin (e.g. `ai-sdk`) can
+ * surface them to the LLM.
+ *
+ * Scopes
+ * ------
+ * - `global`  (default) — visible to every agent and channel.
+ * - `agent`   — visible only to the agent that wrote it.
+ * - `channel` — visible only inside the active channel.
+ */
+const memoryToolDefinitions = {
+  remember: {
+    description:
+      'Persist a durable fact, preference, or note to long-term memory so it can be recalled in future turns and runs. Use for stable information (user preferences, project conventions, contact details, decisions); avoid using it for transient chatter or per-step scratch state — that belongs in thread state. Keep entries short and self-contained.',
+    inputSchema: z.object({
+      content: z
+        .string()
+        .min(1)
+        .describe(
+          'The fact to remember, written so it makes sense out of context (e.g. "User prefers TypeScript over JavaScript.").',
+        ),
+      scope: z
+        .enum(['global', 'agent', 'channel'])
+        .optional()
+        .describe(
+          'Visibility: `global` (default, all agents everywhere), `agent` (only this agent), `channel` (only this channel).',
+        ),
+      tags: z
+        .array(z.string())
+        .optional()
+        .describe('Optional tags for filtering with `recall`.'),
+    }),
+  },
+  recall: {
+    description:
+      'Search long-term memory for facts you previously stored with `remember`. Returns up to `limit` matching records with their ids so you can `forget` stale ones.',
+    inputSchema: z.object({
+      query: z
+        .string()
+        .optional()
+        .describe('Case-insensitive substring filter against memory content.'),
+      tag: z.string().optional().describe('Only return memories that include this tag.'),
+      scope: z
+        .enum(['global', 'agent', 'channel', 'all'])
+        .optional()
+        .describe(
+          'Restrict the search to a single scope. Default `all` returns global + this agent + this channel.',
+        ),
+      limit: z
+        .number()
+        .int()
+        .positive()
+        .max(50)
+        .optional()
+        .describe('Maximum records to return (default 20, max 50).'),
+    }),
+  },
+  forget: {
+    description:
+      'Delete a memory by id. Use after the user asks to forget something or when a previously remembered fact is now wrong. Get ids from `recall`.',
+    inputSchema: z.object({
+      id: z.string().describe('The memory record id (returned by `recall`/`remember`).'),
+    }),
+  },
+};
+
+export const memoryPlugin: Plugin = {
+  id: 'memory',
+  name: 'Memory',
+  description:
+    'Global long-term memory: remember/recall/forget facts across runs and agents.',
+  toolDefinitions: memoryToolDefinitions,
+  factory: () => () => {
+    // Handlers live in bus/services.ts; this plugin only contributes tool definitions.
+  },
+};
+
+export default memoryPlugin;

package/src/plugins/shell/index.ts

@@ -0,0 +1,123 @@
+import { MelonyPlugin } from 'melony';
+import { z } from 'zod';
+import { spawn } from 'node:child_process';
+import type { Plugin } from '../../bus/plugin.js';
+import { OpenBotEvent, OpenBotState } from '../../app/types.js';
+
+const shellToolDefinitions = {
+  shell_exec: {
+    description:
+      'Execute a shell command in the terminal. Use this for file operations, running scripts, or system tasks.',
+    inputSchema: z.object({
+      command: z.string().describe('The shell command to execute.'),
+      cwd: z
+        .string()
+        .optional()
+        .describe(
+          'Working directory. Defaults to the channel cwd or workspace root. Leave empty unless the user requests a specific directory.',
+        ),
+      shell: z.enum(['bash', 'sh', 'zsh']).optional().describe('Shell to use. Defaults to bash.'),
+      timeoutMs: z
+        .number()
+        .optional()
+        .default(30000)
+        .describe('Maximum execution time in milliseconds. Defaults to 30000 (30s).'),
+    }),
+  },
+};
+
+const shellPluginRuntime = (): MelonyPlugin<OpenBotState, OpenBotEvent> => (builder) => {
+  builder.on('action:shell_exec', async function* (event, context) {
+    const { command, cwd, shell = 'bash', timeoutMs = 30000 } = event.data;
+
+    const actualTimeout = Math.max(1000, Math.min(timeoutMs, 60000));
+    const actualCwd = cwd || context.state.channelDetails?.cwd || process.cwd();
+
+    try {
+      const result = await new Promise<{
+        exitCode: number | null;
+        stdout: string;
+        stderr: string;
+        timedOut: boolean;
+      }>((resolve) => {
+        const child = spawn(command, {
+          shell,
+          cwd: actualCwd,
+          env: { ...process.env },
+        });
+
+        let stdout = '';
+        let stderr = '';
+        let timedOut = false;
+
+        const timer = setTimeout(() => {
+          timedOut = true;
+          child.kill();
+        }, actualTimeout);
+
+        child.stdout.on('data', (data) => {
+          stdout += data.toString();
+          if (stdout.length > 100000) {
+            stdout = stdout.substring(0, 100000) + '\n... [output truncated]';
+            child.kill();
+          }
+        });
+
+        child.stderr.on('data', (data) => {
+          stderr += data.toString();
+          if (stderr.length > 100000) {
+            stderr = stderr.substring(0, 100000) + '\n... [output truncated]';
+          }
+        });
+
+        child.on('close', (code) => {
+          clearTimeout(timer);
+          resolve({ exitCode: code, stdout, stderr, timedOut });
+        });
+
+        child.on('error', (err) => {
+          clearTimeout(timer);
+          resolve({ exitCode: -1, stdout, stderr: stderr + err.message, timedOut: false });
+        });
+      });
+
+      const success = result.exitCode === 0 && !result.timedOut;
+
+      yield {
+        type: 'action:shell_exec:result',
+        data: {
+          success,
+          exitCode: result.exitCode,
+          stdout: result.stdout,
+          stderr: result.stderr,
+          timedOut: result.timedOut,
+        },
+        meta: event.meta,
+      } as OpenBotEvent;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Unknown shell error';
+      yield {
+        type: 'action:shell_exec:result',
+        data: {
+          success: false,
+          exitCode: -1,
+          stdout: '',
+          stderr: message,
+          timedOut: false,
+          error: message,
+        },
+        meta: event.meta,
+      } as OpenBotEvent;
+    }
+  });
+};
+
+export const shellPlugin: Plugin = {
+  id: 'shell',
+  name: 'Shell',
+  description: 'Execute shell commands in the channel workspace.',
+  toolDefinitions: shellToolDefinitions,
+  factory: () => shellPluginRuntime(),
+};
+
+export default shellPlugin;