openbot 0.3.5 → 0.4.0

package/src/plugins/openbot/context.ts

@@ -0,0 +1,91 @@
+import { OpenBotState } from '../../app/types.js';
+import { Storage } from '../../services/plugins/domain.js';
+
+export const DEFAULT_CONTEXT_BUDGET = 8000;
+
+/**
+ * Returns the known context window budget (in tokens) for a given model string.
+ */
+export const getContextBudgetForModel = (modelString: string): number => {
+  const budgets: Record<string, number> = {
+    'openai/gpt-4o': 128000,
+    'openai/gpt-4o-mini': 128000,
+    'openai/o1-preview': 128000,
+    'openai/o1-mini': 128000,
+    'anthropic/claude-3-5-sonnet-20240620': 200000,
+    'anthropic/claude-3-5-sonnet-latest': 200000,
+    'anthropic/claude-3-opus-20240229': 200000,
+    'anthropic/claude-3-sonnet-20240229': 200000,
+    'anthropic/claude-3-haiku-20240307': 200000,
+  };
+
+  return budgets[modelString] || DEFAULT_CONTEXT_BUDGET;
+};
+
+/** Built-in orchestrator agent id. */
+export const ORCHESTRATOR_AGENT_ID = 'system';
+
+/**
+ * Check if a channel is a solo DM (only the agent is present).
+ */
+export function isDmSoloChannel(participants: string[], agentId: string): boolean {
+  return participants.length === 0 || (participants.length === 1 && participants[0] === agentId);
+}
+
+/**
+ * Simplified context builder for MVP.
+ */
+export async function buildContext(state: OpenBotState, storage?: Storage): Promise<string> {
+  const { channelId, threadId, channelDetails, agentId, threadDetails, agentDetails } = state;
+  const participants = channelDetails?.participants || [];
+  const isDm = isDmSoloChannel(participants, agentId);
+
+  const sections: string[] = [];
+
+  // 1. Environment
+  let env = '## ENVIRONMENT\n';
+  if (isDm) {
+    env += '- Mode: Direct Message (Solo)\n';
+  } else {
+    const channelName = channelDetails?.name || channelId;
+    env += `- Mode: Channel (#${channelName})\n`;
+    if (threadId) {
+      env += `- Thread: ${threadDetails?.name || threadId}\n`;
+    }
+    const peerIds = participants.filter((id: string) => id !== agentId);
+    if (peerIds.length > 0) {
+      env += `- Participants: ${peerIds.join(', ')}\n`;
+    }
+  }
+  sections.push(env);
+
+  // 2. Channel Spec
+  const spec = channelDetails?.spec?.trim();
+  if (spec) {
+    sections.push(`## CHANNEL SPECIFICATION\n${spec}`);
+  }
+
+  // 3. Agent Instructions
+  if (agentDetails?.instructions) {
+    sections.push(`## AGENT: ${agentDetails?.name}\n${agentDetails.instructions}`);
+  }
+
+  // 4. Memories
+  if (storage?.listMemories) {
+    try {
+      const scopes = ['global', `agent:${agentId}`];
+      if (channelId) scopes.push(`channel:${channelId}`);
+      const records = await storage.listMemories({ scopes, limit: 20 });
+      if (records.length > 0) {
+        const formatted = records
+          .map((r: any) => `- (${r.scope}) ${r.content}`)
+          .join('\n');
+        sections.push(`## MEMORIES\n${formatted}`);
+      }
+    } catch (error) {
+      console.warn('[context] Failed to fetch memories:', error);
+    }
+  }
+
+  return sections.join('\n\n');
+}

package/src/plugins/openbot/history.ts

@@ -0,0 +1,107 @@
+import { OpenBotEvent } from '../../app/types.js';
+import { ToolResultPart, type ModelMessage } from 'ai';
+
+/**
+ * Converts a raw event log into a valid chain of ModelMessages for the AI SDK.
+ * 
+ * This is a basic implementation that maps events to messages and filters out
+ * events from sub-processes (delegation) to avoid duplication in history.
+ */
+export function eventsToModelMessages(events: OpenBotEvent[]): ModelMessage[] {
+  const messages: ModelMessage[] = [];
+
+  for (const event of events) {
+    // Skip events that belong to a sub-process (like delegation)
+    // so they don't pollute the main conversation history.
+    if (event.meta?.parentToolCallId) {
+      continue;
+    }
+
+    switch (event.type) {
+      case 'agent:output': {
+        const last = messages[messages.length - 1];
+        if (last && last.role === 'assistant' && typeof last.content === 'string') {
+          last.content += event.data.content;
+        } else {
+          messages.push({ role: 'assistant', content: event.data.content });
+        }
+        break;
+      }
+
+      case 'agent:invoke': {
+        const invokeEvent = event as any;
+        if (invokeEvent.data?.content && invokeEvent.data?.role) {
+          messages.push({
+            role: invokeEvent.data.role,
+            content: invokeEvent.data.content
+          } as ModelMessage);
+        }
+        break;
+      }
+
+      default:
+        // Handle tool calls (action:*)
+        if (event.type.startsWith('action:') && !event.type.endsWith(':result')) {
+
+
+          const toolName = event.type.slice(7);
+          const toolCallId = event.meta?.toolCallId;
+          if (!toolCallId) break;
+
+          const toolCall = {
+            type: 'tool-call' as const,
+            toolCallId,
+            toolName,
+            input: (event as any).data,
+          };
+
+          const last = messages[messages.length - 1];
+
+          if (last && last.role === 'assistant') {
+            if (typeof last.content === 'string') {
+              last.content = [
+                { type: 'text', text: last.content },
+                toolCall,
+              ];
+            } else if (Array.isArray(last.content)) {
+              (last.content as any[]).push(toolCall);
+            }
+          } else {
+            messages.push({
+              role: 'assistant',
+              content: [toolCall],
+            });
+          }
+        }
+        // Handle tool results (action:*:result)
+        else if (event.type.startsWith('action:') && event.type.endsWith(':result')) {
+          const toolName = event.type.slice(7, -7);
+          const toolCallId = event.meta?.toolCallId;
+          if (!toolCallId) break;
+
+          const toolResult: ToolResultPart = {
+            type: 'tool-result' as const,
+            toolCallId,
+            toolName,
+            output: {
+              type: 'text',
+              value: (event as any)?.data?.output || "No output", // ?.output is from delegation result
+            },
+          };
+
+          const last = messages[messages.length - 1];
+          if (last && last.role === 'tool' && Array.isArray(last.content)) {
+            (last.content as any[]).push(toolResult);
+          } else {
+            messages.push({
+              role: 'tool',
+              content: [toolResult],
+            });
+          }
+        }
+        break;
+    }
+  }
+
+  return messages;
+}

package/src/plugins/openbot/index.ts

@@ -0,0 +1,37 @@
+import type { Plugin } from '../../services/plugins/types.js';
+import { openbotRuntime } from './runtime.js';
+
+/**
+ * `openbot` — the standard, opinionated OpenBot agent runtime.
+ *
+ * This is the canonical execution loop for OpenBot agents. It handles
+ * `agent:invoke`, manages short-term memory, assembles context, and
+ * orchestrates tool calls.
+ */
+export const openbotPlugin: Plugin = {
+  id: 'openbot',
+  name: 'OpenBot Agent',
+  description:
+    'The standard, opinionated OpenBot agent runtime. Handles the core execution loop and tool orchestration.',
+  configSchema: {
+    type: 'object',
+    properties: {
+      model: {
+        type: 'string',
+        description:
+          'Provider model string, e.g. openai/gpt-4o-mini, anthropic/claude-3-5-sonnet-20240620',
+        default: 'openai/gpt-4o-mini',
+      },
+    },
+  },
+  factory: ({ config, storage, tools }) => {
+
+    return openbotRuntime({
+      model: config?.model as string,
+      storage,
+      toolDefinitions: tools,
+    });
+  },
+};
+
+export default openbotPlugin;

package/src/plugins/openbot/runtime.ts

@@ -0,0 +1,384 @@
+import { MelonyPlugin, RuntimeContext } from 'melony';
+import { generateText, type LanguageModel } from 'ai';
+import { openai } from '@ai-sdk/openai';
+import { anthropic } from '@ai-sdk/anthropic';
+import { OpenBotEvent, OpenBotState, AgentInvokeEvent } from '../../app/types.js';
+import { eventsToModelMessages } from './history.js';
+import { Storage } from '../../services/plugins/domain.js';
+import type { ToolDefinition } from '../../services/plugins/types.js';
+import {
+  ORCHESTRATOR_AGENT_ID,
+  getContextBudgetForModel,
+  buildContext,
+} from './context.js';
+import { saveConfig } from '../../app/config.js';
+import { API_KEY_SETUP_MESSAGE, OPENBOT_SYSTEM_PROMPT } from './system-prompt.js';
+
+export interface OpenBotRuntimeOptions {
+  /** Provider model string (e.g. `openai/gpt-4o-mini`, `anthropic/claude-3-5-sonnet-20240620`). */
+  model?: string;
+  storage?: Storage;
+  /** Tool definitions merged from all tool plugins attached to this agent. */
+  toolDefinitions?: Record<string, ToolDefinition>;
+}
+
+function resolveModel(modelString: string): LanguageModel {
+  const [provider, ...rest] = modelString.split('/');
+  const modelId = rest.join('/');
+  if (!modelId) {
+    throw new Error(`Invalid model string: "${modelString}". Expected "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,
+  storage: Storage | undefined,
+): Promise<string> {
+  const context = await buildContext(state, storage);
+
+  const instructions =
+    state.agentId === ORCHESTRATOR_AGENT_ID
+      ? (state.agentDetails?.instructions?.trim() || OPENBOT_SYSTEM_PROMPT)
+      : OPENBOT_SYSTEM_PROMPT;
+
+  const sections = [instructions, '', context];
+
+  // Hardcoded naming hint logic
+  const threadState = state.threadDetails?.state as any;
+  if (!threadState?.isSmartNamed) {
+    sections.push(
+      '',
+      '## SYSTEM HINT',
+      'This thread is unnamed. Please use the `patch_thread_details` tool to set a concise, descriptive, and regular `name` (e.g., "Project Brainstorming" instead of "project-brainstorm") in the thread state and set `isSmartNamed: true` in the same patch. Only do this once.',
+    );
+  }
+
+  return sections.join('\n');
+}
+
+/**
+ * Tracks tool-call IDs from one LLM turn until matching `:result` events arrive.
+ *
+ * Melony runs yielded `action:*` events depth-first, so parallel tool calls from
+ * a single `generateText` response execute one-by-one. We must wait for every ID
+ * in the batch before calling the LLM again — not after the first result.
+ */
+function createToolBatchTracker() {
+  let pending: Set<string> | null = null;
+
+  return {
+    startBatch(toolCallIds: string[]) {
+      pending = new Set(toolCallIds);
+    },
+    clear() {
+      pending = null;
+    },
+    /** Returns true when this result completes the batch (time to call the LLM again). */
+    recordResult(toolCallId: string): boolean {
+      if (!pending?.has(toolCallId)) return false;
+      pending.delete(toolCallId);
+      if (pending.size > 0) return false;
+      pending = null;
+      return true;
+    },
+  };
+}
+
+/**
+ * OpenBot agent runtime.
+ *
+ * - One `generateText` call per `runLLM` (tools have no `execute`; SDK stops at 1 step).
+ * - Tool calls become `action:*` events; plugins emit `:result` when done.
+ * - When a full batch of results is in, `runLLM` runs again with updated history.
+ */
+export const openbotRuntime =
+  (options: OpenBotRuntimeOptions): MelonyPlugin<OpenBotState, OpenBotEvent> =>
+    (builder) => {
+      const {
+        model: modelString = 'openai/gpt-4o-mini',
+        storage,
+        toolDefinitions = {},
+      } = options;
+
+      let currentModelString = modelString;
+      let model = resolveModel(currentModelString);
+      const toolBatch = createToolBatchTracker();
+
+      const runLLM = async function* (
+        context: RuntimeContext<OpenBotState, OpenBotEvent>,
+        threadId?: string,
+        trigger?: AgentInvokeEvent,
+      ): AsyncGenerator<OpenBotEvent> {
+        if (!storage) return;
+
+        // Capture parent metadata for event enrichment
+        const triggerEvent = trigger || context.state.triggerEvent;
+        const parentAgentId = triggerEvent?.meta?.parentAgentId;
+        const parentToolCallId = triggerEvent?.meta?.parentToolCallId;
+
+        context.state.model = currentModelString;
+
+        const systemPrompt = await buildSystemPrompt(context.state, storage);
+
+        const events = await storage.getEvents({
+          channelId: context.state.channelId,
+          threadId: context.state.threadId,
+        });
+
+        const messages = eventsToModelMessages(events);
+
+        // console.log('systemPrompt:::::::\n', systemPrompt);
+        // console.log('messages:::::::\n', JSON.stringify(messages, null, 2));
+        // console.log('toolDefinitions:::::::\n', JSON.stringify(toolDefinitions, null, 2));
+
+        try {
+          // Single LLM request — tool execution happens externally via action:* handlers.
+          const result = await generateText({
+            model,
+            system: systemPrompt,
+            messages,
+            tools: toolDefinitions as Record<string, { description: string; inputSchema: any }>,
+            stopWhen: ({ steps }) => steps.length === 1,
+            allowSystemInMessages: true,
+          });
+
+          const toolCalls = result.toolCalls ?? [];
+
+          // if (result.usage) {
+          //   const usage = result.usage;
+          //   yield {
+          //     type: 'agent:usage',
+          //     data: {
+          //       usage: {
+          //         promptTokens: usage.inputTokens,
+          //         completionTokens: usage.outputTokens,
+          //         totalTokens: usage.totalTokens,
+          //         currentContextTokens: usage.inputTokens,
+          //         contextBudget: getContextBudgetForModel(currentModelString),
+          //       },
+          //       model: currentModelString,
+          //     },
+          //     meta: {
+          //       agentId: context.state.agentId,
+          //       threadId,
+          //       runId: context.state.runId,
+          //     },
+          //   } as OpenBotEvent;
+          // }
+
+          const outputMeta = {
+            agentId: context.state.agentId,
+            threadId,
+            parentAgentId,
+            parentToolCallId,
+          };
+
+          // Text before actions so history/UI show the model's intent first.
+          if (result.text) {
+            yield {
+              type: 'agent:output',
+              data: { content: result.text },
+              meta: outputMeta,
+            };
+          }
+
+          if (toolCalls.length > 0) {
+            // when multiple tool calls are made, Melony runtime handles them one by one, thats why we need to start a new batch
+            toolBatch.startBatch(toolCalls.map((tc) => tc.toolCallId));
+
+            for (const toolCall of toolCalls) {
+              yield {
+                type: `action:${toolCall.toolName}` as OpenBotEvent['type'],
+                data: toolCall.input,
+                meta: {
+                  toolCallId: toolCall.toolCallId,
+                  ...outputMeta,
+                },
+              } as unknown as OpenBotEvent;
+            }
+          } else {
+            // clear the tool batch if there are no tool calls
+            toolBatch.clear();
+          }
+        } catch (error: unknown) {
+          const errorMessage = error instanceof Error ? error.message : String(error);
+          const isApiKeyError =
+            errorMessage.includes('API key') ||
+            errorMessage.includes('401') ||
+            errorMessage.includes('Unauthorized') ||
+            errorMessage.includes('authentication');
+
+          if (isApiKeyError) {
+            const [currentProvider, ...rest] = currentModelString.split('/');
+            const currentModelId = rest.join('/');
+
+            yield {
+              type: 'client:ui:widget',
+              data: {
+                kind: 'form',
+                widgetId: `api_key_request_${Date.now()}`,
+                title: `AI Provider API Key Required`,
+                description: API_KEY_SETUP_MESSAGE,
+                fields: [
+                  {
+                    id: 'provider',
+                    label: 'Provider',
+                    type: 'select',
+                    required: true,
+                    options: [
+                      { label: 'OpenAI', value: 'openai' },
+                      { label: 'Anthropic', value: 'anthropic' },
+                    ],
+                    defaultValue: currentProvider === 'anthropic' ? 'anthropic' : 'openai',
+                  },
+                  {
+                    id: 'model',
+                    label: 'Model',
+                    type: 'text',
+                    description:
+                      'Model name without the provider prefix (e.g. `gpt-4o-mini` or `claude-3-5-sonnet-20240620`).',
+                    placeholder: 'gpt-4o-mini',
+                    required: true,
+                    defaultValue: currentModelId,
+                  },
+                  {
+                    id: 'apiKey',
+                    label: 'API Key',
+                    type: 'text',
+                    placeholder: `sk-...`,
+                    required: true,
+                  },
+                ],
+                submitLabel: 'Save & Continue',
+                metadata: {
+                  type: 'api_key_request',
+                },
+              },
+              meta: { agentId: context.state.agentId, threadId },
+            } as OpenBotEvent;
+            return;
+          }
+
+          throw error;
+        }
+      };
+
+      builder.on('agent:invoke', async function* (event, context) {
+        const routedTo = (event as { data?: { agentId?: string } }).data?.agentId;
+        if (typeof routedTo === 'string' && routedTo && routedTo !== context.state.agentId) {
+          return;
+        }
+
+        // clear the tool batch if the agent is invoked
+        // this is to prevent the tool batch from being used for a new agent invocation
+        toolBatch.clear();
+
+        const threadId = event.meta?.threadId || context.state.threadId;
+        yield* runLLM(context, threadId, event as AgentInvokeEvent);
+      });
+
+      // this is to handle the tool results from the tool calls
+      // because Melony runtime handles them one by one, thats why we need to record the result
+      builder.on('*', async function* (event, context) {
+        if (!event.type.endsWith(':result')) return;
+        if (event.meta?.agentId !== context.state.agentId) return;
+
+        const toolCallId = event.meta?.toolCallId;
+        // record the result of the tool call
+        if (!toolCallId || !toolBatch.recordResult(toolCallId)) return;
+
+        const threadId = event.meta?.threadId || context.state.threadId;
+        yield* runLLM(context, threadId);
+      });
+
+      builder.on('client:ui:widget:response', async function* (event, context) {
+        const { metadata, values } = event.data;
+        if (metadata?.type !== 'api_key_request') return;
+        if (!values?.apiKey || !values?.provider || !values?.model) return;
+
+        const provider = String(values.provider);
+        const modelId = String(values.model).trim();
+        const apiKey = String(values.apiKey);
+
+        if (provider !== 'openai' && provider !== 'anthropic') {
+          yield {
+            type: 'agent:output',
+            data: { content: `Unsupported provider: ${provider}` },
+            meta: { agentId: context.state.agentId },
+          };
+          return;
+        }
+
+        const envVar = provider === 'openai' ? 'OPENAI_API_KEY' : 'ANTHROPIC_API_KEY';
+        const newModelString = `${provider}/${modelId}`;
+
+        if (!storage) return;
+        try {
+          await storage.createVariable({ key: envVar, value: apiKey, secret: true });
+          process.env[envVar] = apiKey;
+
+          currentModelString = newModelString;
+          model = resolveModel(currentModelString);
+          try {
+            saveConfig({ model: currentModelString });
+
+            // Also update the agent's AGENT.md if it has an openbot plugin config
+            const details = await storage.getAgentDetails({ agentId: context.state.agentId });
+            const updatedPlugins = details.pluginRefs.map((ref) => {
+              if (ref.id === 'openbot') {
+                return {
+                  ...ref,
+                  config: { ...ref.config, model: currentModelString },
+                };
+              }
+              return ref;
+            });
+
+            await storage.updateAgent({
+              agentId: context.state.agentId,
+              plugins: updatedPlugins,
+            });
+          } catch {
+            // best-effort: config persistence failure shouldn't block the conversation
+          }
+
+          yield {
+            type: 'agent:output',
+            data: {
+              content: `Saved ${provider} API key and set model to \`${newModelString}\`.`,
+            },
+            meta: { agentId: context.state.agentId },
+          };
+
+          yield {
+            type: 'client:ui:widget',
+            data: {
+              widgetId: event.data.widgetId,
+              kind: 'message',
+              title: 'API Key Saved',
+              body: `Successfully saved ${provider} API key and selected model \`${newModelString}\`. You can now continue your conversation.`,
+              state: 'submitted',
+              actions: [{ id: 'ok', label: 'Got it', variant: 'primary' }],
+            },
+            meta: { agentId: context.state.agentId },
+          };
+        } catch (error) {
+          yield {
+            type: 'agent:output',
+            data: {
+              content: `Failed to save API key: ${error instanceof Error ? error.message : 'Unknown error'
+                }`,
+            },
+            meta: { agentId: context.state.agentId },
+          };
+        }
+      });
+    };

package/src/plugins/openbot/system-prompt.ts

@@ -0,0 +1,7 @@
+export const OPENBOT_SYSTEM_PROMPT = [
+  'You are a helpful AI assistant for your human. Your job is to help the user with their questions and tasks.',
+].join('\n');
+
+/** Shown in the API key setup form when no provider credentials are configured. */
+export const API_KEY_SETUP_MESSAGE =
+  'OpenBot runs AI agents locally with tools, memory, and delegation. Bring your own OpenAI or Anthropic key — it stays on your machine. Use the form below to get started.';