openbot 0.3.3 → 0.3.5

package/dist/services/storage.js

@@ -1,6 +1,8 @@
 import { DEFAULT_PLUGINS_DIR, DEFAULT_AGENTS_DIR, DEFAULT_BASE_DIR, DEFAULT_CHANNELS_DIR, loadConfig, resolvePath, 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 { aiSdkPlugin } from '../plugins/ai-sdk/index.js';
@@ -8,13 +10,31 @@ import { AI_SDK_SYSTEM_PROMPT } from '../plugins/ai-sdk/system-prompt.js';
 import { listBuiltInPlugins, parsePluginModule } from '../registry/plugins.js';
 import { processService } from '../harness/process.js';
 import { memoryService } from './memory.js';
-import { pathToFileURL } from 'node:url';
 const resolveBaseDir = () => {
     const config = loadConfig();
     return resolvePath(config.baseDir || DEFAULT_BASE_DIR);
 };
 const ENTITY_SVG_CANDIDATE_NAMES = ['avatar.svg', 'icon.svg', 'image.svg', 'logo.svg'];
 const toSvgDataUrl = (svg) => `data:image/svg+xml;base64,${Buffer.from(svg, 'utf-8').toString('base64')}`;
+let bundledSystemAgentImage;
+let bundledSystemAgentImageLoaded = false;
+/** OpenBot mark from `src/assets/icon.svg` (also copied to `dist/assets` at build). */
+function getBundledSystemAgentImage() {
+    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) => {
     try {
         const svg = await fs.readFile(filePath, 'utf-8');
@@ -72,7 +92,7 @@ function getSystemAgentDetails(overrides) {
     const defaults = {
         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,
         plugins: SYSTEM_DEFAULT_PLUGINS.map((ref) => ref.id),
@@ -599,6 +619,9 @@ export const storageService = {
             const discoveredImage = await resolveEntityImageDataUrl(agentDir);
             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,
                 name: typeof data.name === 'string' ? data.name : agentId,
@@ -606,7 +629,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,
             };
@@ -630,7 +653,7 @@ export const storageService = {
         }
         return diskDetails;
     },
-    createAgent: async ({ agentId, name, description = '', instructions, plugins, }) => {
+    createAgent: async ({ agentId, name, description = '', image, instructions, plugins, }) => {
         assertValidDiskAgentId(agentId);
         const agentDir = resolvePath(path.join(getAgentsRootDir(), agentId));
         const agentMdPath = path.join(agentDir, 'AGENT.md');
@@ -656,10 +679,13 @@ 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');
     },
-    updateAgent: async ({ agentId, name, description, instructions, plugins, }) => {
+    updateAgent: async ({ agentId, name, description, image, instructions, plugins, }) => {
         assertValidDiskAgentId(agentId);
         const agentDir = resolvePath(path.join(getAgentsRootDir(), agentId));
         const agentMdPath = path.join(agentDir, 'AGENT.md');
@@ -683,6 +709,14 @@ export const storageService = {
             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);
         await fs.writeFile(agentMdPath, body, 'utf-8');

package/docs/architecture.md

@@ -1,14 +1,11 @@
 # Architecture
 
-OpenBot is an orchestration platform built on a modular, event-driven architecture. It leverages the `melony` framework to coordinate interactions between multiple specialized agents via a standardized **Agent Harness**.
+OpenBot is an orchestration platform built on a modular, event-driven architecture. It leverages the `melony` framework to coordinate interactions between multiple specialized agents through a central **orchestrator** (HTTP handlers call it directly).
 
 ## Core Components
 
-### 1. Agent Harness
-The Harness is the execution environment for agents. It provides the necessary "plumbing" (storage, communication, tools) so the agent can focus on reasoning. It handles event routing and state management.
-
-### 2. Agent Orchestration & Routing
-The orchestrator is the central dispatcher within the harness. It receives user input and determines how to delegate tasks across the agent network using the following logic:
+### 1. Orchestrator & routing
+The orchestrator is the execution entry point for agent work: it normalizes incoming events, runs the queue processor (handoffs and todo-driven assignees), builds per-agent Melony runtimes, and streams emitted events back to callers (for example storage and SSE). Routing across the agent network uses:
 
 1. **Command Prefix** — Explicit delegation to a specific agent (e.g., `/os list files`).
 2. **DM context** — Direct communication with a specific agent.
@@ -20,10 +17,10 @@ A dynamic registry that manages all available agents. Agents can be:
 - **YAML-based**: Rapidly defined agents in `~/.openbot/agents/*/AGENT.md`.
 - **TS Packages**: Advanced agents with custom logic in `~/.openbot/agents/*/index.ts`.
 
-### 3. Plugin Registry
+### 3. Plugin registry
 The "capability layer" that provides tools and logic shared across the platform. Plugins (like `shell`, `file-system`, or `mcp`) define the actions agents can perform.
 
-### 4. Orchestration Layer (Melony)
+### 4. Orchestration layer (Melony)
 The underlying event bus that handles all communication. It ensures that agents can collaborate asynchronously, share context, and emit real-time updates to the UI.
 
 ## Multi-Agent Workflow

package/package.json

@@ -1,16 +1,11 @@
 {
   "name": "openbot",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "private": false,
   "type": "module",
   "engines": {
     "node": ">=20.12.0"
   },
-  "scripts": {
-    "dev": "tsx watch src/app/cli.ts start",
-    "build": "tsc",
-    "start": "node dist/app/cli.js start"
-  },
   "bin": {
     "openbot": "./dist/app/cli.js"
   },
@@ -36,5 +31,10 @@
     "@types/node": "^20.10.1",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "dev": "tsx watch src/app/cli.ts start",
+    "build": "tsc && mkdir -p dist/assets && cp src/assets/icon.svg dist/assets/icon.svg",
+    "start": "node dist/app/cli.js start"
   }
-}
+}

package/src/app/cli.ts

@@ -25,7 +25,7 @@ function checkNodeVersion() {
 
 checkNodeVersion();
 
-program.name('openbot').description('OpenBot CLI').version('0.3.3');
+program.name('openbot').description('OpenBot CLI').version('0.3.4');
 
 program
   .command('start')

package/src/app/server.ts

@@ -12,10 +12,12 @@ import { DEFAULT_BASE_DIR, loadConfig, resolvePath } from '../app/config.js';
 import { ActiveRunsSnapshotEvent, OpenBotEvent, OpenBotState } from './types.js';
 import { processService } from '../harness/process.js';
 import { storageService } from '../services/storage.js';
-import { AgentHarness } from '../harness/agent-harness.js';
+import { dispatch } from '../harness/dispatcher.js';
 import { initPlugins } from '../registry/plugins.js';
 import { ensureEventId, openBotEventFromQuery } from './utils.js';
 
+type Bucket = { channelId: string; threadId?: string; activeCount: number; agentIds: Set<string> };
+
 export interface ServerOptions {
   port?: number;
 }
@@ -94,25 +96,38 @@ export async function startServer(options: ServerOptions = {}) {
   };
 
   const buildActiveRunsSnapshot = (): ActiveRunsSnapshotEvent => {
-    const byChannel = new Map<string, { activeCount: number; agentIds: Set<string> }>();
+    const byBucket = new Map<string, Bucket>();
     for (const run of activeRuns.values()) {
-      const existing = byChannel.get(run.channelId) ?? {
-        activeCount: 0,
-        agentIds: new Set<string>(),
-      };
-      existing.activeCount += 1;
-      existing.agentIds.add(run.agentId);
-      byChannel.set(run.channelId, existing);
+      const threadId = run.threadId || undefined;
+      const key = JSON.stringify([run.channelId, threadId ?? null]);
+      let bucket = byBucket.get(key);
+      if (!bucket) {
+        bucket = { channelId: run.channelId, threadId, activeCount: 0, agentIds: new Set<string>() };
+        byBucket.set(key, bucket);
+      }
+      bucket.activeCount += 1;
+      bucket.agentIds.add(run.agentId);
     }
+    const channels = Array.from(byBucket.values())
+      .sort((a, b) => {
+        const c = a.channelId.localeCompare(b.channelId);
+        if (c !== 0) return c;
+        return (a.threadId ?? '').localeCompare(b.threadId ?? '');
+      })
+      .map(({ channelId, threadId, activeCount, agentIds }) => {
+        const row: ActiveRunsSnapshotEvent['data']['channels'][number] = {
+          channelId,
+          activeCount,
+          agentIds: Array.from(agentIds),
+        };
+        if (threadId !== undefined) {
+          row.threadId = threadId;
+        }
+        return row;
+      });
     return {
       type: 'agent:active-runs:snapshot',
-      data: {
-        channels: Array.from(byChannel.entries()).map(([channelId, value]) => ({
-          channelId,
-          activeCount: value.activeCount,
-          agentIds: Array.from(value.agentIds),
-        })),
-      },
+      data: { channels },
     };
   };
 
@@ -149,6 +164,7 @@ export async function startServer(options: ServerOptions = {}) {
 
     if (channelId === GLOBAL_CHANNEL_ID) {
       const snapshot = buildActiveRunsSnapshot();
+
       ensureEventId(snapshot);
       res.write(`data: ${JSON.stringify(snapshot)}\n\n`);
     }
@@ -206,10 +222,10 @@ export async function startServer(options: ServerOptions = {}) {
         activeRuns.set(
           getRunKey(chunk.data.runId, chunk.data.agentId, chunk.data.channelId, chunk.data.threadId),
           {
-          runId: chunk.data.runId,
-          channelId: chunk.data.channelId,
-          threadId: chunk.data.threadId,
-          agentId: chunk.data.agentId,
+            runId: chunk.data.runId,
+            channelId: chunk.data.channelId,
+            threadId: chunk.data.threadId,
+            agentId: chunk.data.agentId,
           },
         );
       } else if (chunk.type === 'agent:run:end') {
@@ -226,21 +242,26 @@ export async function startServer(options: ServerOptions = {}) {
 
       sendToClientKey(targetClientKey, chunk);
 
-      if (chunk.type === 'agent:run:start' || chunk.type === 'agent:run:end') {
+      if (
+        chunk.type === 'agent:run:start' ||
+        chunk.type === 'agent:run:end' ||
+        chunk.type === 'agent:run:stopped'
+      ) {
         sendToClientKey(GLOBAL_CHANNEL_ID, chunk);
       }
     };
 
     try {
-      const harness = new AgentHarness({
+      ensureEventId(event);
+
+      await dispatch({
         runId,
         agentId: agentId || 'system',
+        event,
         channelId,
         threadId,
         onEvent,
       });
-
-      await harness.dispatch(event);
       res.sendStatus(200);
     } catch (error) {
       console.error('[publish] Failed to dispatch event', {
@@ -272,15 +293,16 @@ export async function startServer(options: ServerOptions = {}) {
     };
 
     try {
-      const harness = new AgentHarness({
+      ensureEventId(event);
+
+      await dispatch({
         runId,
         agentId: agentId || 'system',
+        event,
         channelId,
         threadId,
         onEvent,
       });
-
-      await harness.dispatch(event);
       res.json({ events });
     } catch (error) {
       res.status(500).json({ error: 'Failed to process state request' });

package/src/app/types.ts

@@ -143,6 +143,7 @@ export type CreateAgentEvent = BaseEvent & {
     agentId: string;
     name: string;
     description?: string;
+    image?: string;
     instructions: string;
     plugins: PluginRef[];
   };
@@ -162,6 +163,7 @@ export type UpdateAgentEvent = BaseEvent & {
     agentId: string;
     name?: string;
     description?: string;
+    image?: string;
     instructions?: string;
     plugins?: PluginRef[];
   };
@@ -365,17 +367,48 @@ export type AgentRunEndEvent = BaseEvent & {
   };
 };
 
+export type AgentRunStoppedEvent = BaseEvent & {
+  type: 'agent:run:stopped';
+  data: {
+    runId: string;
+    agentId: string;
+    channelId: string;
+    threadId?: string;
+    reason?: string;
+  };
+};
+
 export type ActiveRunsSnapshotEvent = BaseEvent & {
   type: 'agent:active-runs:snapshot';
   data: {
     channels: Array<{
       channelId: string;
+      threadId?: string;
       activeCount: number;
       agentIds: string[];
     }>;
   };
 };
 
+export type StopAgentRunEvent = BaseEvent & {
+  type: 'action:agent_run_stop';
+  data: {
+    runId: string;
+    agentId?: string;
+    channelId?: string;
+    threadId?: string;
+    reason?: string;
+  };
+};
+
+export type StopAgentRunResultEvent = BaseEvent & {
+  type: 'action:agent_run_stop:result';
+  data: {
+    success: boolean;
+    message?: string;
+  };
+};
+
 export type CreateThreadEvent = BaseEvent & {
   type: 'action:create_thread';
   data: {
@@ -714,6 +747,7 @@ export type InstallAgentEvent = BaseEvent & {
     agentId: string;
     name: string;
     description?: string;
+    image?: string;
     instructions: string;
     plugins: PluginRef[];
   };
@@ -860,7 +894,10 @@ export type OpenBotEvent =
   | AgentOutputEvent
   | AgentRunStartEvent
   | AgentRunEndEvent
+  | AgentRunStoppedEvent
   | ActiveRunsSnapshotEvent
+  | StopAgentRunEvent
+  | StopAgentRunResultEvent
   | GetChannelsEvent
   | GetChannelsResultEvent
   | GetThreadsEvent

package/src/bus/services.ts

@@ -550,8 +550,8 @@ export const busServicesPlugin =
 
       builder.on('action:storage:create-agent', async function* (event) {
         try {
-          const { agentId, name, description, instructions, plugins } = event.data;
-          await storage.createAgent({ agentId, name, description, instructions, plugins });
+          const { agentId, name, description, image, instructions, plugins } = event.data;
+          await storage.createAgent({ agentId, name, description, image, instructions, plugins });
           yield { type: 'action:storage:create-agent-result', data: { success: true } };
         } catch (error) {
           yield {
@@ -566,8 +566,8 @@ export const busServicesPlugin =
 
       builder.on('action:storage:update-agent', async function* (event) {
         try {
-          const { agentId, name, description, instructions, plugins } = event.data;
-          await storage.updateAgent({ agentId, name, description, instructions, plugins });
+          const { agentId, name, description, image, instructions, plugins } = event.data;
+          await storage.updateAgent({ agentId, name, description, image, instructions, plugins });
           yield { type: 'action:storage:update-agent-result', data: { success: true } };
         } catch (error) {
           yield {
@@ -858,7 +858,7 @@ export const busServicesPlugin =
 
       builder.on('action:agent:install', async function* (event) {
         try {
-          const { agentId, name, description, instructions, plugins } = event.data;
+          const { agentId, name, description, image, instructions, plugins } = event.data;
 
           // Ensure each plugin is available locally. Built-in ids resolve
           // immediately; npm-name ids are fetched on demand.
@@ -881,6 +881,7 @@ export const busServicesPlugin =
             agentId,
             name,
             description,
+            image,
             instructions,
             plugins,
           });

package/src/bus/types.ts

@@ -113,6 +113,8 @@ export interface Storage {
     agentId: string;
     name: string;
     description?: string;
+    /** Avatar/logo URL or data URI; persisted in AGENT.md frontmatter. */
+    image?: string;
     instructions: string;
     plugins: PluginRef[];
   }) => Promise<void>;
@@ -120,6 +122,8 @@ export interface Storage {
     agentId: string;
     name?: string;
     description?: string;
+    /** Omit to leave unchanged; empty string removes stored image. */
+    image?: string;
     instructions?: string;
     plugins?: PluginRef[];
   }) => Promise<void>;