openbot 0.2.12 → 0.2.13

package/src/harness/orchestrator.ts

@@ -0,0 +1,342 @@
+import { melony, Runtime } from 'melony';
+import { AgentInvokeEvent, OpenBotEvent, OpenBotState } from '../app/types.js';
+import { resolvePlugin } from '../registry/plugins.js';
+import { storageService } from '../services/storage.js';
+import { ensureEventId } from '../app/utils.js';
+import { loadConfig, PluginSpec } from '../app/config.js';
+
+export interface ExecuteAgentOptions {
+  runId: string;
+  agentId: string;
+  event: OpenBotEvent;
+  channelId: string;
+  threadId?: string;
+  onEvent: (chunk: OpenBotEvent, state: OpenBotState) => Promise<void>;
+}
+
+export interface DispatchOptions {
+  runId: string;
+  agentId?: string;
+  event: OpenBotEvent;
+  channelId: string;
+  threadId?: string;
+  onEvent: (chunk: OpenBotEvent, state: OpenBotState) => Promise<void>;
+}
+
+/**
+ * Enhances agent instructions with a list of other available agents.
+ */
+export async function enhanceInstructions(state: OpenBotState) {
+  const { agentId, agentDetails } = state;
+  if (!agentDetails) return;
+
+  try {
+    const agents = await storageService.getAgents();
+    const otherAgents = agents.filter((a) => a.id !== agentId);
+    if (otherAgents.length === 0) return;
+
+    const agentsList = otherAgents
+      .map((a) => `- **${a.id}**${a.description ? `: ${a.description}` : ''}`)
+      .join('\n');
+
+    const header = '### Available Agents for Delegation:';
+    if (!agentDetails.instructions.includes(header)) {
+      agentDetails.instructions += `\n\n${header}\n${agentsList}\n\nYou can use the \`delegate\` tool to task these agents. Use their ID (the bold part) when delegating.`;
+    }
+  } catch (error) {
+    console.warn('[agent] Failed to enhance instructions', error);
+  }
+}
+
+/**
+ * Factory for creating an OpenBot Melony Runtime.
+ */
+async function createAgentRuntime(
+  state: OpenBotState,
+): Promise<Runtime<OpenBotState, OpenBotEvent>> {
+  // 1. Prepare instructions
+  await enhanceInstructions(state);
+
+  // 2. Initialize runtime with the agent plugin
+  const runtime = melony<OpenBotState, OpenBotEvent>({
+    initialState: state,
+  });
+
+  // 3. Normalize plugin specs:
+  // - runtime can be a single spec or an array (for backward/forward compatibility)
+  // - plugins remains supported as additional specs
+  const runtimeSpecs = Array.isArray(state.agentDetails?.runtime)
+    ? state.agentDetails.runtime
+    : state.agentDetails?.runtime
+      ? [state.agentDetails.runtime]
+      : [];
+  const { globalPlugins = [] } = loadConfig();
+  const agentSpecs = [...runtimeSpecs, ...(state.agentDetails?.plugins || [])];
+  const pluginSpecs = mergePluginSpecs(globalPlugins, agentSpecs);
+
+  // 4. Load normalized plugins
+  for (const p of pluginSpecs) {
+    const name = typeof p === 'string' ? p : p?.name;
+    if (!name || typeof name !== 'string') {
+      continue;
+    }
+
+    const config = typeof p === 'string' ? {} : { ...(p.config || {}) };
+    const plugin = await resolvePlugin(name, config);
+    if (plugin) {
+      runtime.use(plugin);
+    }
+  }
+
+  return runtime.build();
+}
+
+function mergePluginSpecs(globalSpecs: PluginSpec[], agentSpecs: PluginSpec[]): PluginSpec[] {
+  const specsByName = new Map<string, PluginSpec>();
+
+  for (const spec of globalSpecs) {
+    const name = typeof spec === 'string' ? spec : spec?.name;
+    if (!name || typeof name !== 'string') continue;
+    specsByName.set(name, spec);
+  }
+
+  // Agent-defined plugins override global ones with the same name.
+  for (const spec of agentSpecs) {
+    const name = typeof spec === 'string' ? spec : spec?.name;
+    if (!name || typeof name !== 'string') continue;
+    specsByName.set(name, spec);
+  }
+
+  return [...specsByName.values()];
+}
+
+export const orchestratorService = {
+  /**
+   * The primary entry point for all events coming into the system (e.g. from the API).
+   * Handles routing and initial UI message creation.
+   */
+  dispatch: async (options: DispatchOptions): Promise<void> => {
+    const { runId, agentId, event, channelId, threadId, onEvent } = options;
+
+    // 0. Ensure the incoming event has a unique ID immediately
+    ensureEventId(event);
+
+    let finalAgentId = agentId || 'system';
+    let finalEvent = event;
+    let currentThreadId = threadId;
+
+    // 1. Convert user:input (or other raw inputs) to agent:invoke
+    const rawContent = (event as any).data?.content || '';
+    if (event.type === 'user:input' || event.type === 'agent:invoke') {
+      const normalizedInvokeEvent: AgentInvokeEvent = {
+        type: 'agent:invoke',
+        id: event.id,
+        data: {
+          content: rawContent,
+          role: 'user',
+        },
+        meta: {
+          agentId: 'system',
+          userId: event.meta?.userId,
+          userName: event.meta?.userName,
+          userAvatarUrl: event.meta?.userAvatarUrl,
+        },
+      };
+      finalEvent = normalizedInvokeEvent;
+
+      // 1. Store the user's input in the current context (main channel or existing thread)
+      const initialState = await storageService.getOpenBotState({
+        runId,
+        agentId: 'system',
+        channelId,
+        threadId: currentThreadId,
+        event: finalEvent,
+      });
+
+      // 2. Propagate the user's input to the event bus
+      await onEvent(finalEvent, initialState);
+
+      // 3. Prepare the event for the target agent
+      finalEvent = {
+        ...event,
+        type: 'agent:invoke',
+        data: {
+          ...((event as any).data || {}),
+          content: rawContent,
+        },
+        meta: {
+          ...(event.meta || {}),
+          // The threadId in meta is the anchor for new threads (Slack-style)
+          threadId: currentThreadId || finalEvent.id,
+        },
+      };
+    }
+
+    // 4. Linear Execution Loop
+    // Instead of recursion, we use a queue to process agents one after another.
+    const queue: { agentId: string; event: OpenBotEvent }[] = [
+      { agentId: finalAgentId, event: finalEvent },
+    ];
+
+    // Safety check to prevent infinite loops
+    let iterations = 0;
+    const MAX_ITERATIONS = 20;
+
+    while (queue.length > 0 && iterations < MAX_ITERATIONS) {
+      iterations++;
+      const { agentId, event: currentEvent } = queue.shift()!;
+
+      // Track agents queued in this step to avoid double-runs (e.g. from tool delegation)
+      const queuedAgents = new Set<string>();
+      const delegations: { agentId: string; event: OpenBotEvent }[] = [];
+
+      await orchestratorService.executeAgent({
+        runId,
+        agentId,
+        event: currentEvent,
+        channelId,
+        threadId: currentThreadId,
+        onEvent: async (chunk, state) => {
+          // 0. Filter out echoed input events to prevent duplication in the UI/storage
+          if (chunk.type === currentEvent.type && chunk.id === currentEvent.id) {
+            return;
+          }
+
+          // 1. Detect if a new thread was created and update the context for the rest of the loop
+          if (chunk.type === 'action:create_thread:result' && chunk.data.success) {
+            currentThreadId = chunk.data.threadId || currentThreadId;
+          }
+
+          // 2. Detect delegations to queue them for the next iteration
+          let targetAgentId: string | null = null;
+          let targetEvent: OpenBotEvent | null = null;
+
+          if (
+            chunk.type === 'agent:invoke' &&
+            chunk.data.agentId &&
+            chunk.data.agentId !== agentId
+          ) {
+            targetAgentId = chunk.data.agentId;
+            targetEvent = {
+              ...chunk,
+              meta: {
+                ...(chunk.meta || {}),
+                threadId: currentThreadId,
+              },
+            };
+          }
+
+          // 3. Queue only if not already queued in this step
+          if (targetAgentId && targetEvent && !queuedAgents.has(targetAgentId)) {
+            queuedAgents.add(targetAgentId);
+            delegations.push({
+              agentId: targetAgentId,
+              event: targetEvent,
+            });
+          }
+
+          // Propagate all events
+          await onEvent(chunk, state);
+        },
+      });
+
+      // Add found delegations to the queue
+      queue.push(...delegations);
+    }
+
+    if (iterations >= MAX_ITERATIONS) {
+      console.warn(`[orchestrator] Reached MAX_ITERATIONS (${MAX_ITERATIONS}). Stopping execution.`);
+    }
+  },
+
+  /**
+   * Executes a single agent runtime.
+   */
+  executeAgent: async (options: ExecuteAgentOptions): Promise<void> => {
+    const { runId, agentId, event, channelId, threadId, onEvent } = options;
+
+    let agentState: OpenBotState;
+    try {
+      agentState = await storageService.getOpenBotState(options);
+    } catch (error) {
+      if ((error as Error & { code?: string }).code === 'AGENT_NOT_FOUND') {
+        const fallbackState = await storageService.getOpenBotState({
+          runId,
+          agentId: 'system',
+          channelId,
+          threadId,
+          event,
+        });
+        const warning = `⚠️ Agent **${agentId}** does not exist. Please check the agent ID and try again.`;
+
+        await onEvent(
+          {
+            type: 'agent:output',
+            data: { content: warning },
+            meta: { agentId: 'system', threadId },
+          },
+          fallbackState,
+        );
+
+        return;
+      }
+      throw error;
+    }
+    const agentRuntime = await createAgentRuntime(agentState);
+
+    let hasProducedOutput = false;
+
+    await onEvent(
+      {
+        type: 'agent:run:start',
+        data: {
+          runId,
+          agentId,
+          channelId,
+          threadId,
+        },
+      },
+      agentState,
+    );
+
+    try {
+      // RUN the agent runtime
+      for await (const chunk of agentRuntime.run(event, { state: agentState, runId })) {
+        if (chunk.type === 'agent:output') {
+          hasProducedOutput = true;
+          chunk.meta = { ...chunk.meta, agentId };
+        } else if (chunk.type.startsWith('action:')) {
+          hasProducedOutput = true;
+        }
+        await onEvent(chunk, agentState);
+      }
+    } finally {
+      await onEvent(
+        {
+          type: 'agent:run:end',
+          data: {
+            runId,
+            agentId,
+            channelId,
+            threadId,
+          },
+        },
+        agentState,
+      );
+    }
+
+    // Fallback for agents that don't produce output (e.g. misconfigured or silent)
+    if (event.type === 'agent:invoke' && !hasProducedOutput) {
+      const warning = `⚠️ **${agentId}** is not configured to handle inputs. Please check its plugin configuration.`;
+
+      await onEvent(
+        {
+          type: 'agent:output',
+          data: { content: warning },
+          meta: { agentId },
+        },
+        agentState,
+      );
+    }
+  },
+};

package/src/harness/process.ts

@@ -0,0 +1,9 @@
+import { StoredVariable } from '../app/config.js';
+
+export const processService = {
+  applyVariablesToProcessEnv: (variables: StoredVariable[]) => {
+    for (const variable of variables) {
+      process.env[variable.key] = variable.value;
+    }
+  },
+};

package/src/harness/types.ts

@@ -0,0 +1,34 @@
+import { OpenBotEvent, OpenBotState } from '../app/types.js';
+
+/**
+ * The Harness is the environment in which an agent operates.
+ * it provides the necessary "plumbing" (storage, communication, tools) 
+ * so the agent can focus on reasoning.
+ */
+export interface Harness {
+  readonly runId: string;
+  readonly channelId: string;
+  readonly threadId?: string;
+  
+  /**
+   * Dispatches an event into the harness.
+   * This is the primary way to interact with the agent.
+   */
+  dispatch(event: OpenBotEvent): Promise<void>;
+
+  /**
+   * Observes events emitted by the harness.
+   */
+  onEvent(callback: (event: OpenBotEvent, state: OpenBotState) => Promise<void>): void;
+}
+
+/**
+ * Options for creating a new Agent Harness instance.
+ */
+export interface HarnessOptions {
+  runId: string;
+  agentId: string;
+  channelId: string;
+  threadId?: string;
+  onEvent: (event: OpenBotEvent, state: OpenBotState) => Promise<void>;
+}

package/src/plugins/ai-sdk.ts

@@ -0,0 +1,197 @@
+import { MelonyPlugin, RuntimeContext } from 'melony';
+import { generateText, ModelMessage, type LanguageModel } from 'ai';
+import { openai } from '@ai-sdk/openai';
+import { anthropic } from '@ai-sdk/anthropic';
+import { z } from 'zod';
+import { OpenBotEvent, OpenBotState, ShortTermMessage } from '../app/types.js';
+import { Storage } from './storage.js';
+
+export interface AISDKPluginOptions {
+  /**
+   * Provider model as a standardized string (e.g. `openai/gpt-4o-mini`, `anthropic/claude-3-5-sonnet-20240620`).
+   * Default: `openai/gpt-4o-mini`
+   */
+  model?: string;
+  system?: string | ((context: RuntimeContext) => string | Promise<string>);
+  storage?: Storage;
+  toolDefinitions?: Record<
+    string,
+    {
+      description: string;
+      inputSchema: z.ZodType<any>;
+    }
+  >;
+}
+
+/**
+ * Resolves a standardized model string to an AI SDK LanguageModel.
+ */
+function resolveModel(modelString: string): LanguageModel {
+  const [provider, ...rest] = modelString.split('/');
+  const modelId = rest.join('/');
+
+  if (!modelId) {
+    throw new Error(`Invalid model string: "${modelString}". Expected format: "provider/model-id"`);
+  }
+
+  switch (provider) {
+    case 'openai':
+      return openai(modelId);
+    case 'anthropic':
+      return anthropic(modelId);
+    default:
+      throw new Error(`Unsupported AI provider: "${provider}"`);
+  }
+}
+
+async function buildSystemPrompt(
+  state: OpenBotState,
+  system?: string | ((context: RuntimeContext) => string | Promise<string>),
+  context?: RuntimeContext,
+  storage?: Storage,
+): Promise<string> {
+  const sections: string[] = [];
+
+  if (state.agentDetails) {
+    sections.push(`## AGENT NAME\n${state.agentDetails.name}`);
+    sections.push(`## AGENT SPECIFICATION\n${state.agentDetails.instructions}`);
+  }
+
+  if (state.channelDetails) {
+    sections.push(`## CHANNEL NAME\n${state.channelDetails.name}`);
+    sections.push(`## CHANNEL SPECIFICATION\n${state.channelDetails.spec}`);
+    // sections.push(`## CHANNEL STATE\n${JSON.stringify(state.channelDetails.state, null, 2)}`);
+
+    if (storage) {
+      try {
+        const channelEvents = await storage.getEvents({ channelId: state.channelId });
+        if (channelEvents.length > 0) {
+          const formattedEvents = channelEvents
+            .slice(-20)
+            .map((e) => `- ${e.type}: ${JSON.stringify((e as any).data || {})}`)
+            .join('\n');
+          sections.push(`## CHANNEL RECENT ACTIVITIES (events)\n${formattedEvents}`);
+        }
+      } catch (error) {
+        console.warn(`[ai-sdk] Failed to fetch channel events for ${state.channelId}`, error);
+      }
+    }
+  }
+
+  if (state.threadDetails) {
+    sections.push(`## THREAD NAME\n${state.threadDetails.name}`);
+    sections.push(`## THREAD SPECIFICATION\n${state.threadDetails.spec}`);
+    // sections.push(`## THREAD STATE\n${JSON.stringify(state.threadDetails.state, null, 2)}`);
+
+    if (storage && state.threadId) {
+      try {
+        const threadEvents = await storage.getEvents({
+          channelId: state.channelId,
+          threadId: state.threadId,
+        });
+        if (threadEvents.length > 0) {
+          const formattedEvents = threadEvents
+            .slice(-20)
+            .map((e) => `- ${e.type}: ${JSON.stringify((e as any).data || {})}`)
+            .join('\n');
+          sections.push(`## THREAD RECENT ACTIVITIES (events)\n${formattedEvents}`);
+        }
+      } catch (error) {
+        console.warn(
+          `[ai-sdk] Failed to fetch thread events for channel ${state.channelId} thread ${state.threadId}`,
+          error,
+        );
+      }
+    }
+  }
+
+  if (system && typeof system === 'string') {
+    sections.push(`## SYSTEM INSTRUCTIONS\n${system}`);
+  }
+
+  if (system && typeof system === 'function' && context) {
+    sections.push(await system(context));
+  }
+
+  return sections.join('\n\n');
+}
+
+/**
+ * AI SDK Plugin for Melony.
+ * Automatically handles text events and routes them through an AI SDK using Vercel AI SDK.
+ * It can also automatically trigger events based on tool calls.
+ */
+export const aiSdkPlugin =
+  (options: AISDKPluginOptions): MelonyPlugin<OpenBotState, OpenBotEvent> =>
+  (builder) => {
+    const {
+      model: modelString = 'openai/gpt-4o-mini',
+      system,
+      storage,
+      toolDefinitions = {},
+    } = options;
+
+    const model = resolveModel(modelString);
+
+    builder.on('agent:invoke', async function* (event, context) {
+      // extract threadId if model decides to reply in a thread
+      const threadId = event.meta?.threadId || context.state.threadId;
+      const systemPrompt = await buildSystemPrompt(context.state, system, context, storage);
+
+      context.state.shortTermMessages = [
+        ...(context.state.shortTermMessages ?? []),
+        {
+          role: event.data?.role || 'user',
+          content: (event as any)?.data?.content || '',
+        },
+      ];
+
+      const result = await generateText({
+        model,
+        system: systemPrompt,
+        messages: context.state.shortTermMessages,
+        tools: toolDefinitions,
+      });
+
+      const toolCalls = result.toolCalls ?? [];
+
+      if (toolCalls.length > 0) {
+        for (const toolCall of toolCalls) {
+          const toolEvent = {
+            type: `action:${toolCall.toolName}` as OpenBotEvent['type'],
+            data: toolCall.input,
+            meta: {
+              toolCallId: toolCall.toolCallId,
+              agentId: context.state.agentId,
+              threadId,
+            },
+          } as unknown as OpenBotEvent;
+          yield toolEvent;
+        }
+      }
+
+      if (result.text) {
+        context.state.shortTermMessages = [
+          ...(context.state.shortTermMessages ?? []),
+          { role: 'assistant', content: result.text },
+        ];
+
+        yield {
+          type: 'agent:output',
+          data: {
+            content: result.text,
+          },
+          meta: {
+            agentId: context.state.agentId,
+          },
+        };
+      }
+    });
+  };
+
+export const plugin = {
+  name: 'ai-sdk',
+  description: 'Built-in AI SDK plugin',
+  kind: 'runtime' as const,
+  factory: aiSdkPlugin,
+};

package/src/plugins/delegation.ts

@@ -0,0 +1,60 @@
+import { MelonyPlugin } from 'melony';
+import { OpenBotEvent, OpenBotState } from '../app/types.js';
+import z from 'zod';
+
+/**
+ * Delegation Plugin for Melony.
+ * Automatically handles delegation events and routes them through the storage service.
+ */
+export const delegationPlugin = (): MelonyPlugin<OpenBotState, OpenBotEvent> => (builder) => {
+  builder.on('action:delegate', async function* (event, context) {
+    const { agentId, content } = event.data;
+
+    // 1. Show the delegation in the UI
+    yield {
+      type: 'agent:output',
+      data: {
+        content: `Delegating to **${agentId}**: ${content}`,
+      },
+      meta: {
+        ...(event.meta || {}),
+        agentId: context.state.agentId,
+      },
+    };
+
+    // 2. Trigger the linear execution loop in orchestratorService
+    yield {
+      type: 'agent:invoke',
+      data: {
+        agentId,
+        content,
+      },
+      meta: {
+        ...(event.meta || {}),
+        agentId: context.state.agentId,
+      },
+    };
+  });
+};
+
+export const delegationToolDefinitions = {
+  delegate: {
+    description:
+      'Delegate a task to another agent. The agent will run independently and feed results back to you. Call at most once per step.',
+    inputSchema: z.object({
+      agentId: z.string().describe('The ID of the agent (e.g. "os", "browser", "tavily").'),
+      content: z.string().describe('The message or task for the agent.'),
+    }),
+  },
+};
+
+export const plugin = {
+  name: 'delegation',
+  description: 'Delegation plugin',
+  version: '1.0.0',
+  author: 'OpenBot',
+  license: 'MIT',
+  website: 'https://openbot.one',
+  factory: delegationPlugin,
+  toolDefinitions: delegationToolDefinitions,
+};