openbot 0.3.3 → 0.3.5

package/src/harness/dispatcher.ts

@@ -0,0 +1,379 @@
+import {
+  AgentInvokeEvent,
+  HandoffRequestEvent,
+  OpenBotEvent,
+  OpenBotState,
+  StopAgentRunEvent,
+} from '../app/types.js';
+import { ensureEventId } from '../app/utils.js';
+import { storageService } from '../services/storage.js';
+import { createAgentRuntime } from './runtime-factory.js';
+import { advanceAfterRun } from './todo-advance.js';
+
+/**
+ * Single entry point for every event arriving at the bus.
+ *
+ * Three flavors of dispatch:
+ *
+ *   1. `action:agent_run_stop` — record a stop signal, ack, done.
+ *   2. `user:input` / `agent:invoke` — *agent step*: normalize, emit user-facing
+ *      copy, then run the target agent with `run:start`/`run:end` bracketing,
+ *      handoff routing, and a single `advanceAfterRun` pass that can chain the
+ *      next assignee. Recursive, depth-bounded.
+ *   3. Everything else — *bus pass-through*: run the event through the targeted
+ *      agent's runtime once and forward emitted chunks. No `run:start`/`run:end`,
+ *      no todo advance, no handoff. This is what backs `/api/state` queries and
+ *      out-of-band action events posted to `/api/publish`.
+ */
+
+export interface DispatchOptions {
+  runId: string;
+  agentId?: string;
+  event: OpenBotEvent;
+  channelId: string;
+  threadId?: string;
+  onEvent: (chunk: OpenBotEvent, state: OpenBotState) => Promise<boolean | void>;
+}
+
+interface StepContext {
+  runId: string;
+  channelId: string;
+  /** Mutable: a `create_thread:result` mid-chain rebinds the rest of the chain. */
+  threadId?: string;
+  onEvent: DispatchOptions['onEvent'];
+}
+
+interface FollowUp {
+  agentId: string;
+  event: AgentInvokeEvent;
+}
+
+const MAX_CHAIN_DEPTH = 20;
+
+// ---------------------------------------------------------------------------
+// Stop requests
+// ---------------------------------------------------------------------------
+
+type StopRequest = {
+  runId: string;
+  agentId?: string;
+  channelId?: string;
+  threadId?: string;
+  reason?: string;
+  requestedAt: number;
+};
+
+const stopRequests: StopRequest[] = [];
+const STOP_REQUEST_TTL_MS = 30 * 60 * 1000;
+
+const pruneStopRequests = () => {
+  const now = Date.now();
+  for (let i = stopRequests.length - 1; i >= 0; i -= 1) {
+    if (now - stopRequests[i].requestedAt > STOP_REQUEST_TTL_MS) {
+      stopRequests.splice(i, 1);
+    }
+  }
+};
+
+const findStopRequest = (target: {
+  runId: string;
+  agentId: string;
+  channelId: string;
+  threadId?: string;
+}): StopRequest | undefined => {
+  pruneStopRequests();
+  return stopRequests.find((r) => {
+    if (r.runId !== target.runId) return false;
+    if (r.agentId && r.agentId !== target.agentId) return false;
+    if (r.channelId && r.channelId !== target.channelId) return false;
+    if (r.threadId && r.threadId !== target.threadId) return false;
+    return true;
+  });
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export async function dispatch(options: DispatchOptions): Promise<void> {
+  const { event } = options;
+  ensureEventId(event);
+
+  if (event.type === 'action:agent_run_stop') {
+    await handleStop(event as StopAgentRunEvent, options);
+    return;
+  }
+
+  const ctx: StepContext = {
+    runId: options.runId,
+    channelId: options.channelId,
+    threadId: options.threadId,
+    onEvent: options.onEvent,
+  };
+
+  if (event.type === 'user:input' || event.type === 'agent:invoke') {
+    const invoke = await normalizeUserInput(event, ctx);
+    await runStep({ agentId: options.agentId || 'system', event: invoke }, ctx, 0);
+    return;
+  }
+
+  // Bus pass-through: route to the targeted agent's runtime once. No agent step,
+  // no advance, no follow-ups. Keeps queries (`/api/state`) cheap and idempotent.
+  await runBusEvent(event, options.agentId || 'system', ctx);
+}
+
+// ---------------------------------------------------------------------------
+// Agent step: run:start -> runtime -> run:end -> advance -> chain
+// ---------------------------------------------------------------------------
+
+async function runStep(step: FollowUp, ctx: StepContext, depth: number): Promise<void> {
+  if (depth >= MAX_CHAIN_DEPTH) {
+    console.warn(`[dispatcher] Reached MAX_CHAIN_DEPTH (${MAX_CHAIN_DEPTH}); stopping chain.`);
+    return;
+  }
+
+  const target = {
+    runId: ctx.runId,
+    agentId: step.agentId,
+    channelId: ctx.channelId,
+    threadId: ctx.threadId,
+  };
+
+  const preStop = findStopRequest(target);
+  if (preStop) {
+    const state = await storageService.getOpenBotState({ ...target, event: step.event });
+    await ctx.onEvent(
+      { type: 'agent:run:stopped', data: { ...target, reason: preStop.reason } },
+      state,
+    );
+    return;
+  }
+
+  let state: OpenBotState;
+  try {
+    state = await storageService.getOpenBotState({ ...target, event: step.event });
+  } catch (error) {
+    if ((error as Error & { code?: string }).code === 'AGENT_NOT_FOUND') {
+      const fallback = await storageService.getOpenBotState({
+        ...target,
+        agentId: 'system',
+        event: step.event,
+      });
+      await ctx.onEvent(
+        {
+          type: 'agent:output',
+          data: { content: `⚠️ Agent **${step.agentId}** does not exist. Please check the agent ID and try again.` },
+          meta: { agentId: 'system', threadId: ctx.threadId },
+        },
+        fallback,
+      );
+      return;
+    }
+    throw error;
+  }
+
+  await ctx.onEvent({ type: 'agent:run:start', data: { ...target } }, state);
+
+  const followUps: FollowUp[] = [];
+  const queuedAgentIds = new Set<string>();
+  let lastAgentOutput: string | undefined;
+
+  try {
+    const runtime = await createAgentRuntime(state);
+
+    for await (const chunk of runtime.run(step.event, { state, runId: ctx.runId })) {
+      const stop = findStopRequest(target);
+      if (stop) {
+        await ctx.onEvent(
+          { type: 'agent:run:stopped', data: { ...target, reason: stop.reason } },
+          state,
+        );
+        break;
+      }
+
+      if (chunk.id === step.event.id && chunk.type === step.event.type) continue;
+
+      if (chunk.type === 'action:create_thread:result' && chunk.data.success) {
+        ctx.threadId = chunk.data.threadId || ctx.threadId;
+      }
+
+      if (
+        chunk.type === 'agent:output' &&
+        (chunk.meta as { agentId?: string } | undefined)?.agentId === step.agentId
+      ) {
+        const content = chunk.data?.content;
+        if (typeof content === 'string' && content.trim()) lastAgentOutput = content.trim();
+      }
+
+      // Handoff requests are internal: queue a follow-up step instead of forwarding.
+      if (chunk.type === 'handoff:request') {
+        const req = chunk as HandoffRequestEvent;
+        const targetAgent = req.data?.agentId;
+        if (targetAgent && targetAgent !== step.agentId && !queuedAgentIds.has(targetAgent)) {
+          queuedAgentIds.add(targetAgent);
+          followUps.push({
+            agentId: targetAgent,
+            event: makeInvoke(req.data.content, ctx.threadId, req.meta),
+          });
+        }
+        continue;
+      }
+
+      chunk.meta = { ...chunk.meta, agentId: step.agentId };
+      await ctx.onEvent(chunk, state);
+    }
+  } catch (error) {
+    console.error(`[dispatcher] Agent run failed: ${step.agentId}`, error);
+  } finally {
+    const endState = await storageService.getOpenBotState({ ...target, event: step.event });
+    await ctx.onEvent({ type: 'agent:run:end', data: { ...target } }, endState);
+  }
+
+  // Autonomous todo advance: single trigger point, runs once per `agent:run:end`.
+  try {
+    const handoff = await advanceAfterRun({
+      storage: storageService,
+      channelId: ctx.channelId,
+      threadId: ctx.threadId,
+      endedAgentId: step.agentId,
+      lastAgentOutput,
+    });
+    if (handoff && !queuedAgentIds.has(handoff.agentId)) {
+      queuedAgentIds.add(handoff.agentId);
+      followUps.push({
+        agentId: handoff.agentId,
+        event: makeInvoke(handoff.content, ctx.threadId),
+      });
+    }
+  } catch (error) {
+    console.warn('[dispatcher] todo advance failed', error);
+  }
+
+  for (const next of followUps) {
+    await runStep(next, ctx, depth + 1);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Bus pass-through: run an event through the targeted agent's runtime, forward
+// chunks. No run:start/end, no advance, no follow-ups.
+// ---------------------------------------------------------------------------
+
+async function runBusEvent(
+  event: OpenBotEvent,
+  agentId: string,
+  ctx: StepContext,
+): Promise<void> {
+  let state: OpenBotState;
+  try {
+    state = await storageService.getOpenBotState({
+      runId: ctx.runId,
+      agentId,
+      channelId: ctx.channelId,
+      threadId: ctx.threadId,
+      event,
+    });
+  } catch (error) {
+    if ((error as Error & { code?: string }).code === 'AGENT_NOT_FOUND') {
+      // Silently drop: bus pass-through has no UI surface to warn into.
+      return;
+    }
+    throw error;
+  }
+
+  try {
+    const runtime = await createAgentRuntime(state);
+    for await (const chunk of runtime.run(event, { state, runId: ctx.runId })) {
+      if (chunk.id === event.id && chunk.type === event.type) continue;
+      chunk.meta = { ...chunk.meta, agentId };
+      await ctx.onEvent(chunk, state);
+    }
+  } catch (error) {
+    console.error(`[dispatcher] Bus event failed: ${event.type} (${agentId})`, error);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+async function normalizeUserInput(
+  event: OpenBotEvent,
+  ctx: StepContext,
+): Promise<AgentInvokeEvent> {
+  const rawContent = (event as { data?: { content?: string } }).data?.content || '';
+
+  // The user-facing copy stored/streamed for the UI.
+  const userFacing: 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,
+    },
+  };
+
+  const initialState = await storageService.getOpenBotState({
+    runId: ctx.runId,
+    agentId: 'system',
+    channelId: ctx.channelId,
+    threadId: ctx.threadId,
+    event: userFacing,
+  });
+  await ctx.onEvent(userFacing, initialState);
+
+  // The event actually fed to the target agent. Carries the input threadId (or the
+  // message id, used as the anchor for Slack-style new threads).
+  return {
+    ...(event as AgentInvokeEvent),
+    type: 'agent:invoke',
+    data: { ...((event as AgentInvokeEvent).data || {}), content: rawContent, role: 'user' },
+    meta: {
+      ...(event.meta || {}),
+      threadId: ctx.threadId || event.id,
+    },
+  };
+}
+
+function makeInvoke(
+  content: string,
+  threadId?: string,
+  baseMeta?: Record<string, unknown>,
+): AgentInvokeEvent {
+  return ensureEventId({
+    type: 'agent:invoke',
+    data: { role: 'user', content },
+    meta: { ...(baseMeta || {}), threadId },
+  } satisfies AgentInvokeEvent) as AgentInvokeEvent;
+}
+
+async function handleStop(stopEvent: StopAgentRunEvent, options: DispatchOptions): Promise<void> {
+  const { runId, channelId, threadId, onEvent } = options;
+  stopRequests.push({
+    runId: stopEvent.data.runId,
+    agentId: stopEvent.data.agentId,
+    channelId: stopEvent.data.channelId || channelId,
+    threadId: stopEvent.data.threadId || threadId,
+    reason: stopEvent.data.reason,
+    requestedAt: Date.now(),
+  });
+
+  const state = await storageService.getOpenBotState({
+    runId,
+    agentId: options.agentId || 'system',
+    channelId,
+    threadId,
+    event: stopEvent,
+  });
+  await onEvent(
+    {
+      type: 'action:agent_run_stop:result',
+      data: { success: true, message: `Stop requested for run ${stopEvent.data.runId}.` },
+      meta: stopEvent.meta,
+    },
+    state,
+  );
+}

package/src/services/storage.ts

@@ -9,7 +9,9 @@ import {
   VARIABLES_FILE,
 } from '../app/config.js';
 import fs from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import crypto from 'node:crypto';
 import matter from 'gray-matter';
 import {
@@ -28,7 +30,6 @@ import { listBuiltInPlugins, parsePluginModule } from '../registry/plugins.js';
 import { OpenBotEvent, OpenBotState } from '../app/types.js';
 import { processService } from '../harness/process.js';
 import { memoryService } from './memory.js';
-import { pathToFileURL } from 'node:url';
 
 const resolveBaseDir = () => {
   const config = loadConfig();
@@ -40,6 +41,24 @@ const ENTITY_SVG_CANDIDATE_NAMES = ['avatar.svg', 'icon.svg', 'image.svg', 'logo
 const toSvgDataUrl = (svg: string) =>
   `data:image/svg+xml;base64,${Buffer.from(svg, 'utf-8').toString('base64')}`;
 
+let bundledSystemAgentImage: string | undefined;
+let bundledSystemAgentImageLoaded = false;
+
+/** OpenBot mark from `src/assets/icon.svg` (also copied to `dist/assets` at build). */
+function getBundledSystemAgentImage(): string | undefined {
+  if (bundledSystemAgentImageLoaded) return bundledSystemAgentImage;
+  bundledSystemAgentImageLoaded = true;
+  try {
+    const iconPath = path.join(path.dirname(fileURLToPath(import.meta.url)), '../assets/icon.svg');
+    const trimmed = readFileSync(iconPath, 'utf-8').trim();
+    if (!trimmed.startsWith('<svg')) return undefined;
+    bundledSystemAgentImage = toSvgDataUrl(trimmed);
+  } catch {
+    bundledSystemAgentImage = undefined;
+  }
+  return bundledSystemAgentImage;
+}
+
 const tryReadSvgDataUrl = async (filePath: string): Promise<string | null> => {
   try {
     const svg = await fs.readFile(filePath, 'utf-8');
@@ -101,7 +120,7 @@ function getSystemAgentDetails(overrides?: Partial<AgentDetails>): AgentDetails
   const defaults: AgentDetails = {
     id: SYSTEM_AGENT_ID,
     name: 'OpenBot',
-    image: undefined,
+    image: getBundledSystemAgentImage(),
     description:
       'First-party orchestration agent for OpenBot. Coordinates other agents via handoff.',
     instructions: AI_SDK_SYSTEM_PROMPT,
@@ -440,7 +459,7 @@ export const storageService = {
     await fs.writeFile(
       specPath,
       spec?.trim() ||
-        `# ${normalizedChannelId}\n\nDefine the goals and rules for this channel here.\n`,
+      `# ${normalizedChannelId}\n\nDefine the goals and rules for this channel here.\n`,
     );
     await fs.writeFile(statePath, JSON.stringify(finalState, null, 2));
   },
@@ -764,6 +783,10 @@ export const storageService = {
       const stats = await fs.stat(agentMdPath);
 
       const pluginRefs = parsePluginRefs(data.plugins);
+      const frontmatterImage =
+        typeof data.image === 'string' && data.image.trim() !== ''
+          ? data.image.trim()
+          : undefined;
 
       diskDetails = {
         id: agentId,
@@ -772,7 +795,7 @@ export const storageService = {
         plugins: pluginRefs.map((ref) => ref.id),
         pluginRefs,
         description: typeof data.description === 'string' ? data.description : '',
-        image: discoveredImage || undefined,
+        image: frontmatterImage || discoveredImage || undefined,
         createdAt: stats.birthtime,
         updatedAt: stats.mtime,
       };
@@ -802,12 +825,14 @@ export const storageService = {
     agentId,
     name,
     description = '',
+    image,
     instructions,
     plugins,
   }: {
     agentId: string;
     name: string;
     description?: string;
+    image?: string;
     instructions: string;
     plugins: PluginRef[];
   }): Promise<void> => {
@@ -836,6 +861,9 @@ export const storageService = {
       description,
       plugins: serializePluginRefs(plugins),
     };
+    if (typeof image === 'string' && image.trim() !== '') {
+      data.image = image.trim();
+    }
 
     const body = matter.stringify(`${instructions.trim()}\n`, data);
     await fs.writeFile(agentMdPath, body, 'utf-8');
@@ -844,12 +872,14 @@ export const storageService = {
     agentId,
     name,
     description,
+    image,
     instructions,
     plugins,
   }: {
     agentId: string;
     name?: string;
     description?: string;
+    image?: string;
     instructions?: string;
     plugins?: PluginRef[];
   }): Promise<void> => {
@@ -874,6 +904,13 @@ export const storageService = {
     if (name !== undefined) nextData.name = name;
     if (description !== undefined) nextData.description = description;
     if (plugins !== undefined) nextData.plugins = serializePluginRefs(plugins);
+    if (image !== undefined) {
+      if (typeof image === 'string' && image.trim() !== '') {
+        nextData.image = image.trim();
+      } else {
+        delete nextData.image;
+      }
+    }
 
     const nextContent = instructions !== undefined ? instructions : parsed.content;
     const body = matter.stringify(`${String(nextContent).trim()}\n`, nextData);

package/src/harness/agent-harness.ts

@@ -1,58 +0,0 @@
-import { Runtime } from 'melony';
-import { OpenBotEvent, OpenBotState } from '../app/types.js';
-import { Harness, HarnessOptions } from './types.js';
-import { orchestratorService } from './orchestrator.js';
-import { ensureEventId } from '../app/utils.js';
-
-/**
- * Standard implementation of the Agent Harness.
- * It wraps the orchestrator logic into a clean, stateful container.
- */
-export class AgentHarness implements Harness {
-  public readonly runId: string;
-  public readonly agentId: string;
-  public readonly channelId: string;
-  public threadId?: string;
-  private eventCallbacks: ((event: OpenBotEvent, state: OpenBotState) => Promise<void>)[] = [];
-
-  constructor(options: HarnessOptions) {
-    this.runId = options.runId;
-    this.agentId = options.agentId;
-    this.channelId = options.channelId;
-    this.threadId = options.threadId;
-    if (options.onEvent) {
-      this.eventCallbacks.push(options.onEvent);
-    }
-  }
-
-  /**
-   * Dispatches an event to the agent within this harness.
-   */
-  async dispatch(event: OpenBotEvent): Promise<void> {
-    ensureEventId(event);
-
-    await orchestratorService.dispatch({
-      runId: this.runId,
-      agentId: this.agentId,
-      event,
-      channelId: this.channelId,
-      threadId: this.threadId,
-      onEvent: async (chunk, state) => {
-        // Update internal thread state if it changes (e.g. thread creation)
-        if (chunk.type === 'action:create_thread:result' && chunk.data.success) {
-          this.threadId = chunk.data.threadId || this.threadId;
-        }
-
-        // Notify all observers
-        await Promise.all(this.eventCallbacks.map(cb => cb(chunk, state)));
-      }
-    });
-  }
-
-  /**
-   * Adds an event listener to the harness.
-   */
-  onEvent(callback: (event: OpenBotEvent, state: OpenBotState) => Promise<void>): void {
-    this.eventCallbacks.push(callback);
-  }
-}

package/src/harness/event-normalizer.ts

@@ -1,82 +0,0 @@
-import { AgentInvokeEvent, OpenBotEvent, OpenBotState } from '../app/types.js';
-import { ensureEventId } from '../app/utils.js';
-import { storageService } from '../services/storage.js';
-
-export interface NormalizedEventResult {
-  finalEvent: OpenBotEvent;
-  finalAgentId: string;
-}
-
-export const EventNormalizer = {
-  /**
-   * Normalizes incoming events, converting raw inputs like user:input to agent:invoke.
-   * Also handles initial state storage and event bus propagation for user inputs.
-   */
-  normalize: async (
-    event: OpenBotEvent,
-    options: {
-      runId: string;
-      agentId?: string;
-      channelId: string;
-      threadId?: string;
-      onEvent: (chunk: OpenBotEvent, state: OpenBotState) => Promise<boolean | void>;
-    }
-  ): Promise<NormalizedEventResult> => {
-    const { runId, agentId, channelId, threadId, onEvent } = options;
-
-    // 0. Ensure the incoming event has a unique ID immediately
-    ensureEventId(event);
-
-    let finalAgentId = agentId || 'system';
-    let finalEvent = event;
-
-    // 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: threadId,
-        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: threadId || finalEvent.id,
-        },
-      };
-    }
-
-    return { finalEvent, finalAgentId };
-  },
-};