openbot 0.3.2 → 0.3.4

package/README.md

@@ -120,7 +120,7 @@ Shared plugins can be placed in `~/.openbot/plugins` and referenced by agents.
 ## Project Layout
 
 - `src/app`: CLI, server, event types, and app config.
-- `src/harness`: agent harness, orchestration, process, and MCP runtime helpers.
+- `src/harness`: orchestration, process, and MCP runtime helpers.
 - `src/plugins`: built-in plugin implementations.
 - `src/services`: local storage service.
 - `src/registry`: plugin registry.

package/dist/app/cli.js

@@ -16,7 +16,7 @@ function checkNodeVersion() {
     }
 }
 checkNodeVersion();
-program.name('openbot').description('OpenBot CLI').version('0.3.1');
+program.name('openbot').description('OpenBot CLI').version('0.3.4');
 program
     .command('start')
     .description('Start the OpenBot harness')

package/dist/app/server.js

@@ -11,7 +11,7 @@ import { generateId } from 'melony';
 import { DEFAULT_BASE_DIR, loadConfig, resolvePath } from '../app/config.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';
 export async function startServer(options = {}) {
@@ -69,25 +69,39 @@ export async function startServer(options = {}) {
         });
     };
     const buildActiveRunsSnapshot = () => {
-        const byChannel = new Map();
+        const byBucket = new Map();
         for (const run of activeRuns.values()) {
-            const existing = byChannel.get(run.channelId) ?? {
-                activeCount: 0,
-                agentIds: new Set(),
-            };
-            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() };
+                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 = {
+                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 },
         };
     };
     app.use(cors());
@@ -178,19 +192,22 @@ export async function startServer(options = {}) {
                 event: chunk,
             });
             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) {
@@ -220,14 +237,15 @@ export async function startServer(options = {}) {
             events.push(chunk);
         };
         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) {

package/dist/harness/dispatcher.js

@@ -0,0 +1,267 @@
+import { ensureEventId } from '../app/utils.js';
+import { storageService } from '../services/storage.js';
+import { createAgentRuntime } from './runtime-factory.js';
+import { advanceAfterRun } from './todo-advance.js';
+const MAX_CHAIN_DEPTH = 20;
+const stopRequests = [];
+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) => {
+    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) {
+    const { event } = options;
+    ensureEventId(event);
+    if (event.type === 'action:agent_run_stop') {
+        await handleStop(event, options);
+        return;
+    }
+    const ctx = {
+        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, ctx, depth) {
+    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;
+    try {
+        state = await storageService.getOpenBotState({ ...target, event: step.event });
+    }
+    catch (error) {
+        if (error.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 = [];
+    const queuedAgentIds = new Set();
+    let lastAgentOutput;
+    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?.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;
+                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, agentId, ctx) {
+    let state;
+    try {
+        state = await storageService.getOpenBotState({
+            runId: ctx.runId,
+            agentId,
+            channelId: ctx.channelId,
+            threadId: ctx.threadId,
+            event,
+        });
+    }
+    catch (error) {
+        if (error.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, ctx) {
+    const rawContent = event.data?.content || '';
+    // The user-facing copy stored/streamed for the UI.
+    const userFacing = {
+        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,
+        type: 'agent:invoke',
+        data: { ...(event.data || {}), content: rawContent, role: 'user' },
+        meta: {
+            ...(event.meta || {}),
+            threadId: ctx.threadId || event.id,
+        },
+    };
+}
+function makeInvoke(content, threadId, baseMeta) {
+    return ensureEventId({
+        type: 'agent:invoke',
+        data: { role: 'user', content },
+        meta: { ...(baseMeta || {}), threadId },
+    });
+}
+async function handleStop(stopEvent, options) {
+    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/dist/harness/orchestrator.js

@@ -2,6 +2,30 @@ import { storageService } from '../services/storage.js';
 import { createAgentRuntime } from './runtime-factory.js';
 import { EventNormalizer } from './event-normalizer.js';
 import { QueueProcessor } from './queue-processor.js';
+const stopRequests = [];
+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 = (options) => {
+    pruneStopRequests();
+    return stopRequests.find((request) => {
+        if (request.runId !== options.runId)
+            return false;
+        if (request.agentId && request.agentId !== options.agentId)
+            return false;
+        if (request.channelId && request.channelId !== options.channelId)
+            return false;
+        if (request.threadId && request.threadId !== options.threadId)
+            return false;
+        return true;
+    });
+};
 export const orchestratorService = {
     /**
      * The primary entry point for all events coming into the system (e.g. from the API).
@@ -9,6 +33,33 @@ export const orchestratorService = {
      */
     dispatch: async (options) => {
         const { runId, channelId, threadId, onEvent } = options;
+        if (options.event.type === 'action:agent_run_stop') {
+            const stopEvent = options.event;
+            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: options.event,
+            });
+            await onEvent({
+                type: 'action:agent_run_stop:result',
+                data: {
+                    success: true,
+                    message: `Stop requested for run ${stopEvent.data.runId}.`,
+                },
+                meta: options.event.meta,
+            }, state);
+            return;
+        }
         // 1. Normalize incoming event
         const { finalEvent, finalAgentId } = await EventNormalizer.normalize(options.event, {
             runId,
@@ -24,6 +75,7 @@ export const orchestratorService = {
             threadId,
             onEvent,
             executeAgent: orchestratorService.executeAgent,
+            shouldStopRun: orchestratorService.shouldStopRun,
         });
         // 3. Enqueue initial event
         processor.enqueue({ agentId: finalAgentId, event: finalEvent });
@@ -59,9 +111,29 @@ export const orchestratorService = {
             throw error;
         }
         const agentRuntime = await createAgentRuntime(agentState);
+        const stopInfo = {
+            runId,
+            agentId,
+            channelId,
+            threadId,
+        };
         try {
             // RUN the agent runtime
             for await (const chunk of agentRuntime.run(event, { state: agentState, runId })) {
+                const stopRequest = findStopRequest(stopInfo);
+                if (stopRequest) {
+                    await onEvent({
+                        type: 'agent:run:stopped',
+                        data: {
+                            runId,
+                            agentId,
+                            channelId,
+                            threadId,
+                            reason: stopRequest.reason,
+                        },
+                    }, agentState);
+                    break;
+                }
                 chunk.meta = { ...chunk.meta, agentId };
                 await onEvent(chunk, agentState);
             }
@@ -70,4 +142,8 @@ export const orchestratorService = {
             console.error(`[orchestrator] Agent run failed: ${agentId}`, error);
         }
     },
+    shouldStopRun: (options) => {
+        const request = findStopRequest(options);
+        return request ? { shouldStop: true, reason: request.reason } : { shouldStop: false };
+    },
 };

package/dist/harness/queue-processor.js

@@ -28,6 +28,32 @@ export class QueueProcessor {
                 // Run items for the SAME agent sequentially to preserve event order and state consistency.
                 for (const item of items) {
                     const { event: currentEvent } = item;
+                    const stopCheck = this.options.shouldStopRun?.({
+                        runId: this.options.runId,
+                        agentId,
+                        channelId: this.options.channelId,
+                        threadId: this.currentThreadId,
+                    });
+                    if (stopCheck?.shouldStop) {
+                        const stoppedState = await storageService.getOpenBotState({
+                            runId: this.options.runId,
+                            agentId,
+                            channelId: this.options.channelId,
+                            threadId: this.currentThreadId,
+                            event: currentEvent,
+                        });
+                        await this.options.onEvent({
+                            type: 'agent:run:stopped',
+                            data: {
+                                runId: this.options.runId,
+                                agentId,
+                                channelId: this.options.channelId,
+                                threadId: this.currentThreadId,
+                                reason: stopCheck.reason,
+                            },
+                        }, stoppedState);
+                        continue;
+                    }
                     // Track handoff requests queued in this step to avoid accidental duplicates.
                     const queuedRequestKeys = new Set();
                     const queuedItems = [];

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,6 +1,6 @@
 {
   "name": "openbot",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "private": false,
   "type": "module",
   "engines": {

package/src/app/cli.ts

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