openbot 0.2.12 → 0.2.13

package/dist/app/server.js

@@ -0,0 +1,237 @@
+import 'dotenv/config';
+import express from 'express';
+import cors from 'cors';
+import z from 'zod';
+import path from 'path';
+import fs from 'fs/promises';
+import { generateId } from 'melony';
+import { DEFAULT_BASE_DIR, loadConfig, loadVariables, 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 { initPlugins } from '../registry/plugins.js';
+import { ensureEventId, openBotEventFromQuery } from './utils.js';
+export async function startServer(options = {}) {
+    const publishEventSchema = z
+        .object({
+        id: z.string().optional(),
+        type: z.string().min(1, 'Event type is required'),
+        data: z.unknown().optional(),
+        meta: z.unknown().optional(),
+    })
+        .passthrough();
+    const config = loadConfig();
+    const variables = loadVariables();
+    processService.applyVariablesToProcessEnv(variables.variables);
+    const baseDir = config.baseDir || DEFAULT_BASE_DIR;
+    const openBotDir = resolvePath(baseDir);
+    const PORT = Number(options.port ?? config.port ?? process.env.PORT ?? 4132);
+    const app = express();
+    const clients = new Map();
+    const GLOBAL_CHANNEL_ID = '__global__';
+    const activeRuns = new Map();
+    const agentsDir = path.join(openBotDir, 'agents');
+    const pluginsDir = path.join(openBotDir, 'plugins');
+    await fs.mkdir(agentsDir, { recursive: true });
+    await fs.mkdir(pluginsDir, { recursive: true });
+    initPlugins(pluginsDir);
+    const getContext = (req) => {
+        const channelId = req.get('x-openbot-channel-id') || req.query.channelId || (req.body && req.body.channelId);
+        const threadId = req.get('x-openbot-thread-id') || req.query.threadId || (req.body && req.body.threadId);
+        const agentId = req.get('x-openbot-agent-id') || req.query.agentId || (req.body && req.body.agentId);
+        const runId = req.get('x-openbot-run-id') ||
+            req.query.runId ||
+            (req.body && req.body.runId) ||
+            `run_${generateId()}`;
+        const responseType = req.get('x-openbot-response-type') ||
+            req.query.responseType ||
+            (req.body && req.body.responseType);
+        return {
+            channelId: (channelId || (threadId ? 'general' : 'general')), // Default to general if none
+            threadId: threadId,
+            agentId: agentId,
+            runId: runId,
+            responseType: responseType,
+        };
+    };
+    const getClientKey = (channelId, threadId) => threadId ? `${channelId}:${threadId}` : channelId;
+    const sendToClientKey = (clientKey, chunk) => {
+        const threadClients = clients.get(clientKey);
+        if (!threadClients)
+            return;
+        threadClients.forEach((client) => {
+            if (!client.writableEnded) {
+                client.write(`data: ${JSON.stringify(chunk)}\n\n`);
+            }
+        });
+    };
+    const buildActiveRunsSnapshot = () => {
+        const byChannel = 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);
+        }
+        return {
+            type: 'agent:active-runs:snapshot',
+            data: {
+                channels: Array.from(byChannel.entries()).map(([channelId, value]) => ({
+                    channelId,
+                    activeCount: value.activeCount,
+                    agentIds: Array.from(value.agentIds),
+                })),
+            },
+        };
+    };
+    app.use(cors());
+    app.use(express.json({ limit: '20mb' }));
+    app.get('/api/events', (req, res) => {
+        const { channelId, threadId } = getContext(req);
+        const clientKey = getClientKey(channelId, threadId);
+        // SSE response headers: keep the HTTP connection open and unbuffered.
+        res.setHeader('Content-Type', 'text/event-stream');
+        res.setHeader('Cache-Control', 'no-cache');
+        res.setHeader('Connection', 'keep-alive');
+        // Helpful behind proxies (for example nginx) to avoid response buffering.
+        res.setHeader('X-Accel-Buffering', 'no');
+        // Flush headers immediately so the browser moves from "connecting" to "open".
+        res.flushHeaders();
+        // Tell EventSource clients how long to wait before reconnecting.
+        res.write('retry: 3000\n');
+        // Initial comment frame so the stream has activity right after subscribe.
+        res.write(': connected\n\n');
+        // Track all active SSE subscribers for fan-out in /api/publish.
+        if (!clients.has(clientKey)) {
+            clients.set(clientKey, []);
+        }
+        clients.get(clientKey).push(res);
+        if (channelId === GLOBAL_CHANNEL_ID) {
+            const snapshot = buildActiveRunsSnapshot();
+            ensureEventId(snapshot);
+            res.write(`data: ${JSON.stringify(snapshot)}\n\n`);
+        }
+        // Keep connection alive through intermediaries that close idle streams.
+        const heartbeat = setInterval(() => {
+            if (!res.writableEnded) {
+                res.write(': keepalive\n\n');
+            }
+        }, 25000);
+        req.on('close', () => {
+            // Cleanup heartbeat + subscriber when the client disconnects.
+            clearInterval(heartbeat);
+            const threadClients = clients.get(clientKey);
+            if (threadClients) {
+                const index = threadClients.indexOf(res);
+                if (index !== -1) {
+                    threadClients.splice(index, 1);
+                }
+                if (threadClients.length === 0) {
+                    clients.delete(clientKey);
+                }
+            }
+        });
+    });
+    app.post('/api/publish', async (req, res) => {
+        const parseResult = publishEventSchema.safeParse(req.body);
+        if (!parseResult.success) {
+            res.status(400).json({
+                error: 'Invalid publish event payload',
+                details: parseResult.error.issues.map((issue) => issue.message),
+            });
+            return;
+        }
+        const event = parseResult.data;
+        const { channelId, threadId, agentId, runId } = getContext(req);
+        if (!channelId || !channelId.trim()) {
+            res.status(400).json({ error: 'channelId is required' });
+            return;
+        }
+        const onEvent = async (chunk, state) => {
+            ensureEventId(chunk);
+            const targetChannelId = state?.channelId || channelId;
+            const targetThreadId = state?.threadId || threadId;
+            const targetClientKey = getClientKey(targetChannelId, targetThreadId);
+            if (chunk.type === 'agent:run:start') {
+                activeRuns.set(chunk.data.runId, {
+                    runId: chunk.data.runId,
+                    channelId: chunk.data.channelId,
+                    threadId: chunk.data.threadId,
+                    agentId: chunk.data.agentId,
+                });
+            }
+            else if (chunk.type === 'agent:run:end') {
+                activeRuns.delete(chunk.data.runId);
+            }
+            await storageService.storeEvent({
+                channelId: targetChannelId,
+                threadId: targetThreadId,
+                event: chunk,
+            });
+            sendToClientKey(targetClientKey, chunk);
+            if (chunk.type === 'agent:run:start' || chunk.type === 'agent:run:end') {
+                sendToClientKey(GLOBAL_CHANNEL_ID, chunk);
+            }
+        };
+        try {
+            const harness = new AgentHarness({
+                runId,
+                agentId: agentId || 'system',
+                channelId,
+                threadId,
+                onEvent,
+            });
+            await harness.dispatch(event);
+            res.sendStatus(200);
+        }
+        catch (error) {
+            console.error('[publish] Failed to dispatch event', {
+                runId,
+                channelId,
+                threadId,
+                eventType: event.type,
+                error,
+            });
+            res.status(500).json({ error: 'Failed to process publish event' });
+        }
+    });
+    app.get('/api/state', async (req, res) => {
+        let event;
+        try {
+            event = openBotEventFromQuery(req.query);
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : 'Invalid query';
+            res.status(400).json({ error: message });
+            return;
+        }
+        const { channelId, threadId, agentId, runId } = getContext(req);
+        const events = [];
+        const onEvent = async (chunk) => {
+            events.push(chunk);
+        };
+        try {
+            const harness = new AgentHarness({
+                runId,
+                agentId: agentId || 'system',
+                channelId,
+                threadId,
+                onEvent,
+            });
+            await harness.dispatch(event);
+            res.json({ events });
+        }
+        catch (error) {
+            res.status(500).json({ error: 'Failed to process state request' });
+        }
+    });
+    app.listen(PORT, () => {
+        console.log(`\x1b[32mOpenBot server listening at http://localhost:${PORT}\x1b[0m`);
+        console.log(`  - Events endpoint: GET /events (SSE)`);
+        console.log(`  - Publish endpoint: POST /publish`);
+        console.log(`  - State endpoint: GET /state`);
+    });
+}

package/dist/app/utils.js

@@ -0,0 +1,35 @@
+import crypto from 'node:crypto';
+/** Express query values are always strings; parse JSON `data` for typed events. */
+export function openBotEventFromQuery(query) {
+    const typeRaw = query.type;
+    const type = typeof typeRaw === 'string'
+        ? typeRaw
+        : Array.isArray(typeRaw) && typeof typeRaw[0] === 'string'
+            ? typeRaw[0]
+            : '';
+    const dataRaw = query.data;
+    const dataStr = typeof dataRaw === 'string'
+        ? dataRaw
+        : Array.isArray(dataRaw) && typeof dataRaw[0] === 'string'
+            ? dataRaw[0]
+            : undefined;
+    if (dataStr === undefined || dataStr.trim() === '') {
+        return { type };
+    }
+    try {
+        const data = JSON.parse(dataStr);
+        return { type, data };
+    }
+    catch {
+        throw new Error('Query parameter "data" must be valid JSON when provided');
+    }
+}
+/**
+ * Ensures the event has a unique ID.
+ */
+export function ensureEventId(event) {
+    if (!event.id) {
+        event.id = crypto.randomUUID();
+    }
+    return event;
+}

package/dist/harness/agent-harness.js

@@ -0,0 +1,45 @@
+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 {
+    constructor(options) {
+        this.eventCallbacks = [];
+        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) {
+        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) {
+        this.eventCallbacks.push(callback);
+    }
+}

package/dist/harness/mcp.js

@@ -0,0 +1,61 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { loadConfig } from '../app/config.js';
+class MCPService {
+    constructor() {
+        this.clients = new Map();
+        this.transports = new Map();
+    }
+    getServerConfig(serverId) {
+        const config = loadConfig();
+        const server = (config.mcpServers || []).find((s) => s.id === serverId);
+        if (!server) {
+            throw new Error(`MCP server "${serverId}" is not configured`);
+        }
+        return server;
+    }
+    async getClient(serverId) {
+        const existing = this.clients.get(serverId);
+        if (existing) {
+            return existing;
+        }
+        const server = this.getServerConfig(serverId);
+        const client = new Client({
+            name: 'openbot-v2',
+            version: '0.1.0',
+        }, {
+            capabilities: {},
+        });
+        const transport = new StdioClientTransport({
+            command: server.command,
+            args: server.args || [],
+            env: server.env,
+            cwd: server.cwd,
+        });
+        await client.connect(transport);
+        this.clients.set(serverId, client);
+        this.transports.set(serverId, transport);
+        return client;
+    }
+    async listServers() {
+        const config = loadConfig();
+        return (config.mcpServers || []).map((server) => server.id);
+    }
+    async listTools(serverId) {
+        const client = await this.getClient(serverId);
+        const result = await client.listTools();
+        return (result.tools || []).map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+        }));
+    }
+    async callTool(serverId, toolName, args) {
+        const client = await this.getClient(serverId);
+        return client.callTool({
+            name: toolName,
+            arguments: args,
+        });
+    }
+}
+export const mcpService = new MCPService();

package/dist/harness/orchestrator.js

@@ -0,0 +1,273 @@
+import { melony } from 'melony';
+import { resolvePlugin } from '../registry/plugins.js';
+import { storageService } from '../services/storage.js';
+import { ensureEventId } from '../app/utils.js';
+import { loadConfig } from '../app/config.js';
+/**
+ * Enhances agent instructions with a list of other available agents.
+ */
+export async function enhanceInstructions(state) {
+    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) {
+    // 1. Prepare instructions
+    await enhanceInstructions(state);
+    // 2. Initialize runtime with the agent plugin
+    const runtime = melony({
+        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, agentSpecs) {
+    const specsByName = new Map();
+    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()];
+}
+export const orchestratorService = {
+    /**
+     * The primary entry point for all events coming into the system (e.g. from the API).
+     * Handles routing and initial UI message creation.
+     */
+    dispatch: async (options) => {
+        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.data?.content || '';
+        if (event.type === 'user:input' || event.type === 'agent:invoke') {
+            const normalizedInvokeEvent = {
+                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.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: 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();
+            const delegations = [];
+            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 = null;
+                    let targetEvent = 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.`);
+        }
+    },
+    /**
+     * Executes a single agent runtime.
+     */
+    executeAgent: async (options) => {
+        const { runId, agentId, event, channelId, threadId, onEvent } = options;
+        let agentState;
+        try {
+            agentState = await storageService.getOpenBotState(options);
+        }
+        catch (error) {
+            if (error.code === 'AGENT_NOT_FOUND') {
+                const fallbackState = await storageService.getOpenBotState({
+                    runId,
+                    agentId: 'system',
+                    channelId,
+                    threadId,
+                    event,
+                });
+                const warning = `⚠️ Agent **${agentId}** does not exist. Please check the agent ID and try again.`;
+                await onEvent({
+                    type: 'agent:output',
+                    data: { content: warning },
+                    meta: { agentId: 'system', threadId },
+                }, fallbackState);
+                return;
+            }
+            throw error;
+        }
+        const agentRuntime = await createAgentRuntime(agentState);
+        let hasProducedOutput = false;
+        await onEvent({
+            type: 'agent:run:start',
+            data: {
+                runId,
+                agentId,
+                channelId,
+                threadId,
+            },
+        }, 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;
+                }
+                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);
+        }
+    },
+};

package/dist/harness/process.js

@@ -0,0 +1,7 @@
+export const processService = {
+    applyVariablesToProcessEnv: (variables) => {
+        for (const variable of variables) {
+            process.env[variable.key] = variable.value;
+        }
+    },
+};