openbot 0.2.13 → 0.3.0

package/src/harness/orchestrator.ts

@@ -1,9 +1,8 @@
-import { melony, Runtime } from 'melony';
-import { AgentInvokeEvent, OpenBotEvent, OpenBotState } from '../app/types.js';
-import { resolvePlugin } from '../registry/plugins.js';
+import { OpenBotEvent, OpenBotState } from '../app/types.js';
 import { storageService } from '../services/storage.js';
-import { ensureEventId } from '../app/utils.js';
-import { loadConfig, PluginSpec } from '../app/config.js';
+import { createAgentRuntime } from './runtime-factory.js';
+import { EventNormalizer } from './event-normalizer.js';
+import { QueueProcessor } from './queue-processor.js';
 
 export interface ExecuteAgentOptions {
   runId: string;
@@ -11,7 +10,7 @@ export interface ExecuteAgentOptions {
   event: OpenBotEvent;
   channelId: string;
   threadId?: string;
-  onEvent: (chunk: OpenBotEvent, state: OpenBotState) => Promise<void>;
+  onEvent: (chunk: OpenBotEvent, state: OpenBotState) => Promise<boolean | void>;
 }
 
 export interface DispatchOptions {
@@ -20,94 +19,7 @@ export interface DispatchOptions {
   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()];
+  onEvent: (chunk: OpenBotEvent, state: OpenBotState) => Promise<boolean | void>;
 }
 
 export const orchestratorService = {
@@ -116,137 +28,31 @@ export const orchestratorService = {
    * 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.`);
-    }
+    const { runId, channelId, threadId, onEvent } = options;
+
+    // 1. Normalize incoming event
+    const { finalEvent, finalAgentId } = await EventNormalizer.normalize(options.event, {
+      runId,
+      agentId: options.agentId,
+      channelId,
+      threadId,
+      onEvent,
+    });
+
+    // 2. Initialize Queue Processor
+    const processor = new QueueProcessor({
+      runId,
+      channelId,
+      threadId,
+      onEvent,
+      executeAgent: orchestratorService.executeAgent,
+    });
+
+    // 3. Enqueue initial event
+    processor.enqueue({ agentId: finalAgentId, event: finalEvent });
+
+    // 4. Run execution loop
+    await processor.run();
   },
 
   /**
@@ -282,61 +88,17 @@ export const orchestratorService = {
       }
       throw error;
     }
-    const agentRuntime = await createAgentRuntime(agentState);
-
-    let hasProducedOutput = false;
 
-    await onEvent(
-      {
-        type: 'agent:run:start',
-        data: {
-          runId,
-          agentId,
-          channelId,
-          threadId,
-        },
-      },
-      agentState,
-    );
+    const agentRuntime = await createAgentRuntime(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;
-        }
+        chunk.meta = { ...chunk.meta, agentId };
         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,
-      );
+    } catch (error) {
+      console.error(`[orchestrator] Agent run failed: ${agentId}`, error);
     }
   },
 };

package/src/harness/process.ts

@@ -1,9 +1,33 @@
-import { StoredVariable } from '../app/config.js';
+import { loadVariables, StoredVariable } from '../app/config.js';
+
+/** Keys last applied from workspace `variables.json` (used to unset removed entries). */
+let lastWorkspaceVariableKeys = new Set<string>();
+
+function applyVariablesList(variables: StoredVariable[]) {
+  const nextKeys = new Set(variables.map((v) => v.key));
+  for (const key of lastWorkspaceVariableKeys) {
+    if (!nextKeys.has(key)) {
+      delete process.env[key];
+    }
+  }
+  for (const variable of variables) {
+    process.env[variable.key] = variable.value;
+  }
+  lastWorkspaceVariableKeys = nextKeys;
+}
 
 export const processService = {
+  /**
+   * Reload workspace variables from disk into `process.env`.
+   * Call after server start and whenever `variables.json` changes.
+   */
+  syncWorkspaceVariablesToProcessEnv: () => {
+    const { variables } = loadVariables();
+    applyVariablesList(variables);
+  },
+
+  /** Apply a variable list directly (same unset semantics as sync). Prefer `syncWorkspaceVariablesToProcessEnv` when reading from disk. */
   applyVariablesToProcessEnv: (variables: StoredVariable[]) => {
-    for (const variable of variables) {
-      process.env[variable.key] = variable.value;
-    }
+    applyVariablesList(variables);
   },
 };

package/src/harness/queue-processor.ts

@@ -0,0 +1,309 @@
+import {
+  AgentInvokeEvent,
+  DelegateResultEvent,
+  DelegationRequestEvent,
+  HandoffRequestEvent,
+  OpenBotEvent,
+  OpenBotState,
+} from '../app/types.js';
+import { ensureEventId } from '../app/utils.js';
+import { storageService } from '../services/storage.js';
+
+export interface QueueItem {
+  agentId: string;
+  event: OpenBotEvent;
+  delegationContext?: {
+    parentAgentId: string;
+    toolCallId: string;
+    delegationWidgetId?: string;
+  };
+}
+
+export interface QueueProcessorOptions {
+  runId: string;
+  channelId: string;
+  threadId?: string;
+  onEvent: (chunk: OpenBotEvent, state: OpenBotState) => Promise<boolean | void>;
+  executeAgent: (options: {
+    runId: string;
+    agentId: string;
+    event: OpenBotEvent;
+    channelId: string;
+    threadId?: string;
+    onEvent: (chunk: OpenBotEvent, state: OpenBotState) => Promise<boolean | void>;
+  }) => Promise<void>;
+}
+
+export class QueueProcessor {
+  private currentQueue: QueueItem[] = [];
+  private currentThreadId?: string;
+  private readonly MAX_ITERATIONS = 20;
+
+  constructor(private options: QueueProcessorOptions) {
+    this.currentThreadId = options.threadId;
+  }
+
+  enqueue(item: QueueItem) {
+    this.currentQueue.push(item);
+  }
+
+  async run() {
+    let iterations = 0;
+
+    while (this.currentQueue.length > 0 && iterations < this.MAX_ITERATIONS) {
+      iterations++;
+
+      // Group by agentId to avoid parallel state corruption for the same agent.
+      const groups = new Map<string, QueueItem[]>();
+      for (const item of this.currentQueue) {
+        const list = groups.get(item.agentId) || [];
+        list.push(item);
+        groups.set(item.agentId, list);
+      }
+
+      const nextQueue: QueueItem[] = [];
+
+      // Run each agent group in parallel
+      await Promise.all(
+        Array.from(groups.entries()).map(async ([agentId, items]) => {
+          // Run items for the SAME agent sequentially to preserve event order and state consistency.
+          for (const item of items) {
+            const { event: currentEvent, delegationContext } = item;
+
+            // Track delegation/handoff requests queued in this step to avoid accidental duplicates.
+            const queuedRequestKeys = new Set<string>();
+            const queuedItems: QueueItem[] = [];
+            const runOutputs: string[] = [];
+
+            const runOnEvent = async (chunk: OpenBotEvent, state: OpenBotState) => {
+              // 0. Filter out echoed input events to prevent duplication in the UI/storage
+              if (chunk.type === currentEvent.type && chunk.id === currentEvent.id) {
+                return false;
+              }
+
+              // 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) {
+                this.currentThreadId = chunk.data.threadId || this.currentThreadId;
+              }
+
+              // 2. Internal routing (handoff/delegation requests are internal — not forwarded)
+              if (chunk.type === 'handoff:request' || chunk.type === 'delegation:request') {
+                const isHandoff = chunk.type === 'handoff:request';
+                const request = isHandoff
+                  ? (chunk as HandoffRequestEvent)
+                  : (chunk as DelegationRequestEvent);
+                const targetAgentId = request.data?.agentId;
+                const toolCallId =
+                  typeof request.meta?.toolCallId === 'string'
+                    ? request.meta.toolCallId
+                    : undefined;
+                const requestKey = isHandoff
+                  ? `handoff:${targetAgentId}:${request.data?.content ?? ''}`
+                  : `delegate:${toolCallId ?? 'missing'}:${targetAgentId}:${request.data?.content ?? ''}`;
+                
+                if (
+                  targetAgentId &&
+                  targetAgentId !== agentId &&
+                  !queuedRequestKeys.has(requestKey)
+                ) {
+                  queuedRequestKeys.add(requestKey);
+                  const targetEvent = ensureEventId({
+                    type: 'agent:invoke',
+                    data: {
+                      role: 'user',
+                      content: request.data.content,
+                    },
+                    meta: {
+                      ...(request.meta || {}),
+                      threadId: this.currentThreadId,
+                    },
+                  } satisfies AgentInvokeEvent) as AgentInvokeEvent;
+
+                  if (isHandoff) {
+                    queuedItems.push({ agentId: targetAgentId, event: targetEvent });
+                  } else {
+                    if (!toolCallId) {
+                      // Emit error output (this triggers run start if not already started)
+                      await runOnEvent(
+                        ensureEventId({
+                          type: 'agent:output',
+                          data: {
+                            content:
+                              'Delegation request ignored: missing toolCallId. Please retry delegation.',
+                          },
+                          meta: {
+                            agentId,
+                            threadId: this.currentThreadId,
+                          },
+                        } as OpenBotEvent),
+                        state,
+                      );
+                      return true;
+                    }
+                    const parentAgentId =
+                      typeof request.meta?.parentAgentId === 'string'
+                        ? request.meta.parentAgentId
+                        : agentId;
+                    const delegationWidgetId =
+                      typeof request.meta?.delegationWidgetId === 'string'
+                        ? request.meta.delegationWidgetId
+                        : undefined;
+                    queuedItems.push({
+                      agentId: targetAgentId,
+                      event: targetEvent,
+                      delegationContext: {
+                        parentAgentId,
+                        toolCallId,
+                        delegationWidgetId,
+                      },
+                    });
+                  }
+                }
+                return false;
+              }
+
+              if (chunk.type === 'agent:output') {
+                const content = chunk.data?.content;
+                if (typeof content === 'string' && content.trim().length > 0) {
+                  runOutputs.push(content.trim());
+                }
+              }
+
+              // For delegate mode, child agent execution is internal:
+              // capture outputs for parent tool result, but don't stream child events to clients/storage.
+              if (delegationContext) {
+                return false;
+              }
+
+              // If we get here, the event is accepted and should be emitted.
+              await this.options.onEvent(chunk, state);
+              return true;
+            };
+
+            const startState = await storageService.getOpenBotState({
+              runId: this.options.runId,
+              agentId,
+              channelId: this.options.channelId,
+              threadId: this.currentThreadId,
+              event: currentEvent,
+            });
+
+            await this.options.onEvent(
+              {
+                type: 'agent:run:start',
+                data: { 
+                  runId: this.options.runId, 
+                  agentId, 
+                  channelId: this.options.channelId, 
+                  threadId: this.currentThreadId 
+                },
+              },
+              startState,
+            );
+
+            try {
+              await this.options.executeAgent({
+                runId: this.options.runId,
+                agentId,
+                event: currentEvent,
+                channelId: this.options.channelId,
+                threadId: this.currentThreadId,
+                onEvent: runOnEvent,
+              });
+            } finally {
+              const endState = await storageService.getOpenBotState({
+                runId: this.options.runId,
+                agentId,
+                channelId: this.options.channelId,
+                threadId: this.currentThreadId,
+                event: currentEvent,
+              });
+              await this.options.onEvent(
+                {
+                  type: 'agent:run:end',
+                  data: { 
+                    runId: this.options.runId, 
+                    agentId, 
+                    channelId: this.options.channelId, 
+                    threadId: this.currentThreadId 
+                  },
+                },
+                endState,
+              );
+            }
+
+            if (delegationContext) {
+              const summary =
+                runOutputs.length > 0
+                  ? runOutputs.join('\n\n').slice(0, 4000)
+                  : `Delegated agent "${agentId}" completed with no textual output.`;
+              
+              const delegateResultEvent: DelegateResultEvent = ensureEventId({
+                type: 'action:delegate:result',
+                data: {
+                  success: true,
+                  agentId,
+                  summary,
+                },
+                meta: {
+                  toolCallId: delegationContext.toolCallId,
+                  agentId: delegationContext.parentAgentId,
+                  threadId: this.currentThreadId,
+                },
+              } satisfies DelegateResultEvent) as DelegateResultEvent;
+
+              if (delegationContext.delegationWidgetId) {
+                await this.options.onEvent(
+                  ensureEventId({
+                    type: 'client:ui:widget',
+                    data: {
+                      kind: 'message',
+                      widgetId: delegationContext.delegationWidgetId,
+                      title: `Delegation complete: ${agentId}`,
+                      body:
+                        runOutputs.length > 0
+                          ? 'Delegated task finished. Parent agent is preparing final response.'
+                          : 'Delegated task finished with no textual output. Parent agent will continue.',
+                      state: 'submitted',
+                      metadata: {
+                        type: 'delegation:status',
+                        phase: 'completed',
+                        delegatedAgentId: agentId,
+                      },
+                    },
+                    meta: {
+                      agentId: delegationContext.parentAgentId,
+                      threadId: this.currentThreadId,
+                    },
+                  } as OpenBotEvent),
+                  await storageService.getOpenBotState({
+                    runId: this.options.runId,
+                    agentId: delegationContext.parentAgentId,
+                    channelId: this.options.channelId,
+                    threadId: this.currentThreadId,
+                    event: delegateResultEvent,
+                  }),
+                );
+              }
+
+              nextQueue.push({
+                agentId: delegationContext.parentAgentId,
+                event: delegateResultEvent,
+              });
+            }
+
+            nextQueue.push(...queuedItems);
+          }
+        }),
+      );
+
+      this.currentQueue = nextQueue;
+    }
+
+    if (iterations >= this.MAX_ITERATIONS) {
+      console.warn(
+        `[orchestrator] Reached MAX_ITERATIONS (${this.MAX_ITERATIONS}). Stopping execution.`,
+      );
+    }
+  }
+}