openbot 0.2.11 → 0.2.13

package/.prettierrc

@@ -0,0 +1,8 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false
+}

package/AGENTS.md

@@ -0,0 +1,68 @@
+# AGENTS.md
+
+## Purpose
+
+This file gives coding agents persistent project context and working rules for OpenBot.
+Use it as the default guidance for all tasks in this repository.
+
+## Main Goal
+
+To solve agent fragmentation and communication problems.
+
+## Project Snapshot
+
+OpenBot is a local-first platform for multi-agent orchestration and coordination.
+
+- `src/`: event-driven orchestration engine built on Melony.
+- Persistence is local-file based (no mandatory cloud datastore by default).
+- API surface is intentionally minimal: only `GET /api/events`, `POST /api/publish`, and `GET /api/state`.
+
+## Product Mental Model
+
+- **Orchestration**: The platform manages the lifecycle and communication of multiple specialized agents.
+- **Agents**: Specialized participants (bots/personas) that users can delegate tasks to via command prefixes or direct interaction.
+- **Channels**: Shared context spaces where multiple agents collaborate to solve complex problems.
+- **Event-Driven**: The system is entirely event-stream oriented: the orchestrator and agents communicate via events, and the UI renders the evolving state.
+
+## Architecture Rules
+
+1. Favor event-based integration over tightly coupled imperative calls.
+2. Keep storage local-first unless a task explicitly requests remote persistence.
+3. Make incremental, composable changes rather than broad rewrites.
+
+## Server Guidance
+
+- The server is event-first: treat HTTP routes as entry points into the event pipeline.
+- Follow Melony's event flow: `Event -> Handler -> Events`.
+- Keep the public API constrained to the three existing endpoints: `GET /api/events`, `POST /api/publish`, `GET /api/state`. Never introduce new endpoints; all functionality must be modeled through the event system.
+- Plugin changes belong in `src/plugins/*`.
+- Agent behavior and orchestration belong in agent/runtime layers, not UI code.
+- For tool-calling flows, ensure completion/result events are emitted consistently.
+- Avoid introducing hidden side effects in handlers; keep event output explicit.
+
+## Code Quality Expectations
+
+- Make small, reviewable diffs with clear intent.
+- Reuse existing utilities and conventions before adding new ones.
+- Do not add dependencies unless necessary and justified by the task.
+- Add/update tests when behavior changes in non-trivial ways.
+- Run relevant checks for touched areas whenever possible.
+
+## Safe Change Policy
+
+- Do not remove or rewrite unrelated user changes.
+- Do not run destructive git operations unless explicitly requested.
+- If encountering unexpected modified files, pause and confirm next step.
+
+## Useful Repo Context
+
+- Detailed architecture: `docs/architecture.md`
+- Plugin docs: `docs/plugins.md`
+- Agent docs: `docs/agents.md`
+- Cursor rules: `.cursor/rules/*.mdc`
+
+## Task Completion Checklist
+
+- Changes align with local-first + event-driven design.
+- Multi-agent/channel model is preserved.
+- Any new behavior is documented where appropriate.

package/CONTRIBUTING.md

@@ -0,0 +1,74 @@
+# Contributing to OpenBot 🤖
+
+Thank you for your interest in contributing to OpenBot! We're building the future of local-first, multi-agent AI assistants, and we'd love for you to join us.
+
+---
+
+## 🗺️ Project Overview
+
+OpenBot is a monorepo consisting of:
+- **`server/`**: The core Node.js/TypeScript backend that orchestrates agents and handles the Melony event bus.
+- **`web/`**: A React-based dashboard for interacting with your OpenBot instance.
+- **`docs/`**: Detailed documentation on architecture, plugins, and agents.
+
+## 🚀 Getting Started
+
+### Prerequisites
+- [Node.js](https://nodejs.org/) (v18 or higher)
+- [npm](https://www.npmjs.com/)
+
+### Development Setup
+
+1.  **Clone the repository**:
+    ```bash
+    git clone https://github.com/meetopenbot/openbot.git
+    cd openbot
+    ```
+
+2.  **Install dependencies**:
+    We use a root-level script to install dependencies for both the server and the web dashboard:
+    ```bash
+    npm run install-all
+    ```
+
+3.  **Run in development mode**:
+    To start both the server and the web dashboard concurrently:
+    ```bash
+    npm run dev
+    ```
+    The server typically runs on `http://localhost:4001` and the web dashboard on `http://localhost:5173`.
+
+## 🛠️ How to Contribute
+
+### Reporting Bugs or Requesting Features
+- Check the [Issues](https://github.com/meetopenbot/openbot/issues) to see if it's already being discussed.
+- If not, feel free to open a new issue with a clear description and steps to reproduce.
+
+### Submitting a Pull Request
+1.  **Fork the repository** and create your branch from `main`.
+2.  **Make your changes**. If you're adding a new feature, please include relevant documentation in the `docs/` folder or update the READMEs.
+3.  **Ensure your code builds**:
+    ```bash
+    cd server && npm run build
+    ```
+4.  **Create a Pull Request** with a clear title and description of your changes.
+
+## 🎨 Coding Standards
+
+- **TypeScript**: We use TypeScript for both the server and the web dashboard. Please ensure your code is type-safe.
+- **Linting**: Before submitting a PR, please run the linters:
+  ```bash
+  npm run lint --prefix web
+  ```
+- **Functional & Event-Driven**: Since OpenBot is built on the [Melony](https://github.com/meetopenbot/melony) framework, try to stick to event-driven patterns when extending core functionality.
+
+## 🧩 Extending OpenBot
+
+OpenBot is designed to be extensible. You can contribute in several ways:
+- **New Plugins**: Add new capabilities (tools) to the `server/src/plugins/` directory.
+- **Built-in Agents**: Define new specialized agents in `server/src/agents/`.
+- **UI Enhancements**: Improve the React dashboard in the `web/` directory.
+
+---
+
+We appreciate every contribution, big or small! If you have any questions, feel free to reach out via GitHub issues. Happy coding! 🚀

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenBot Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,32 +1,135 @@
-# 👋 Meet OpenBot
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="logo-white.svg">
+    <img src="logo-black.svg" width="200" alt="OpenBot Logo" />
+  </picture>
+</p>
 
-OpenBot is your personal AI assistant that's always ready to help! Built with **Melony**, it can chat, browse the web, and manage files—giving you a powerful, real-time sidekick right in your terminal.
+<h1 align="center">OpenBot</h1>
 
-## Get Started in Seconds
+<p align="center">
+  <a href="https://www.npmjs.com/package/openbot"><img src="https://img.shields.io/npm/v/openbot" alt="npm version" /></a>
+  <a href="https://github.com/meetopenbot/openbot/blob/main/LICENSE"><img src="https://img.shields.io/github/license/meetopenbot/openbot" alt="license" /></a>
+</p>
 
-Installing your new assistant is easy:
+OpenBot is a local-first harness for running AI agents. It is built around a small event API, local file storage, and a Melony-powered runtime that routes events to agents and plugins.
+
+## What It Does
+
+- Runs a local agent server.
+- Stores channels, threads, agents, plugins, config, and variables under `~/.openbot`.
+- Ships with a built-in `system` agent named Lolly.
+- Loads custom agents from `~/.openbot/agents/<agent-id>/AGENT.md`.
+- Loads shared plugins from `~/.openbot/plugins`.
+- Streams events to clients with Server-Sent Events.
+
+## Quick Start
+
+Requires Node.js `>=20.12.0`.
 
 ```bash
 npm i -g openbot
+openbot start
+```
+
+The server listens on `http://localhost:4132` by default. Set a different port with:
+
+```bash
+openbot start --port 3000
 ```
 
-To start your assistant's server, just run:
+For local development:
 
 ```bash
-openbot server
+npm install
+npm run dev
 ```
 
-OpenBot will start listening for you at `http://localhost:4001`.
+## API
 
-## Say Hello
+OpenBot intentionally keeps the public API small:
 
-You can talk to OpenBot using a simple POST request:
+- `GET /api/events` opens an SSE stream for a channel or thread.
+- `POST /api/publish` publishes an event into the harness.
+- `GET /api/state` runs an event and returns the resulting events without opening a stream.
+
+Example:
 
 ```bash
-curl -N \
-  -H "Content-Type: application/json" \
-  -d '{"event":{"type":"agent:input","data":{"content":"Hello!"}}}' \
-  http://localhost:4001/api/chat
+curl -X POST http://localhost:4132/api/publish \
+  -H "content-type: application/json" \
+  -d '{"type":"user:input","data":{"content":"hello"}}'
+```
+
+Useful context can be passed as headers, query params, or body fields:
+
+- `channelId`
+- `threadId`
+- `agentId`
+- `runId`
+
+## Configuration
+
+OpenBot reads config from `~/.openbot/config.json`.
+
+```json
+{
+  "port": 4132,
+  "baseDir": "~/.openbot",
+  "model": "openai/gpt-4o-mini",
+  "mcpServers": []
+}
 ```
 
-That's it! OpenBot will stream its response right back to you. 🚀
+Variables are read from `~/.openbot/variables.json` and applied to the server process environment on startup.
+
+## Agents
+
+The built-in `system` agent is always available. Add a custom agent by creating `~/.openbot/agents/<agent-id>/AGENT.md`:
+
+```markdown
+---
+name: Researcher
+description: Helps collect and summarize information.
+runtime:
+  name: ai-sdk
+  config:
+    model: openai/gpt-4o-mini
+plugins:
+  - name: storage
+---
+
+You are a careful research assistant.
+Summarize findings clearly and cite sources when available.
+```
+
+Agents are discovered from disk when the server starts.
+
+## Plugins
+
+Built-in plugins include:
+
+- `storage`
+- `delegation`
+- `mcp`
+- `ui`
+- `ai-sdk`
+
+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/plugins`: built-in plugin implementations.
+- `src/services`: local storage service.
+- `src/registry`: plugin registry.
+- `docs`: architecture, agents, and plugin notes.
+
+## Learn More
+
+- [Architecture](./docs/architecture.md)
+- [Agents](./docs/agents.md)
+- [Plugins](./docs/plugins.md)
+
+Need help or want to share feedback? Join the community on Discord: https://discord.gg/XYYXvN2ebB

package/dist/agents/system.js

@@ -0,0 +1,106 @@
+import { delegationToolDefinitions } from '../plugins/delegation.js';
+import { storageToolDefinitions } from '../plugins/storage.js';
+import { mcpToolDefinitions } from '../plugins/mcp.js';
+import { uiToolDefinitions } from '../plugins/ui.js';
+import { storageService } from '../services/storage.js';
+import { readFileSync } from 'node:fs';
+const SYSTEM_ICON_DATA_URL = (() => {
+    try {
+        const svg = readFileSync(new URL('../assets/icon.svg', import.meta.url), 'utf-8').trim();
+        if (!svg.startsWith('<svg'))
+            return undefined;
+        return `data:image/svg+xml;base64,${Buffer.from(svg, 'utf-8').toString('base64')}`;
+    }
+    catch {
+        return undefined;
+    }
+})();
+export const getSystemAgentDetails = (overrides) => {
+    const defaults = {
+        id: 'system',
+        name: 'Lolly',
+        image: SYSTEM_ICON_DATA_URL,
+        instructions: 'You are OpenBot, the primary AI assistant and orchestrator of this workspace. Your goal is to help users onboard, answer questions about the system, and suggest specialized agents for specific tasks.\n\n' +
+            '### How to use OpenBot:\n' +
+            '1. **General Chat**: Just type your message here, and I will help you.\n' +
+            '2. **Specialized Agents**: You can delegate tasks to specialized agents for specific tasks. For example, use the `delegate` tool to invoke the `os` agent for terminal commands and file operations.\n' +
+            '3. **Channels**: Channels are shared spaces where multiple agents can participate. You can create new channels for different topics.\n' +
+            '4. **Local-First**: OpenBot runs entirely on your machine. Your data stays private and local.\n\n' +
+            '### Workflow Guidelines:\n' +
+            '- **Todo Schema**: Keep todo items simple. Each item should have a short `id`, a clear `task` description, and a `status` (e.g., "pending", "in_progress", "done").\n' +
+            '- **Interactive Widgets**: Use `render_ui_widget` to give the user a visual progress bar (`kind: "todo_list"`), request permissions (`kind: "approval"`), or gather structured data (`kind: "form"`).\n' +
+            '- **Delegation**: When delegating to another agent, reference the relevant Task ID from the thread state. Update the task status (e.g., using `patch_thread_details`) as progress is made.\n\n' +
+            'If you need to know what agents or plugins are installed, I can help you find that information.',
+        runtime: {
+            name: 'ai-sdk',
+            config: {
+                model: 'openai/gpt-4o-mini',
+                toolDefinitions: {
+                    ...delegationToolDefinitions,
+                    ...storageToolDefinitions,
+                    ...mcpToolDefinitions,
+                    ...uiToolDefinitions,
+                },
+            },
+        },
+        plugins: [
+            { name: 'storage', config: { storage: storageService } },
+            { name: 'delegation', config: {} },
+            { name: 'mcp', config: {} },
+            { name: 'ui', config: {} },
+        ],
+        description: 'System coordinator agent',
+        createdAt: new Date(),
+        updatedAt: new Date(),
+    };
+    if (!overrides)
+        return defaults;
+    // Merge logic:
+    // - Simple fields: override if present
+    // - Runtime: merge config/model, but preserve toolDefinitions unless explicitly overridden
+    // - Plugins: merge by name (user plugins override defaults)
+    const mergedRuntime = {
+        ...(typeof defaults.runtime === 'object' ? defaults.runtime : {}),
+        ...(typeof overrides.runtime === 'object' ? overrides.runtime : {}),
+        name: (typeof overrides.runtime === 'object' ? overrides.runtime.name : overrides.runtime) ||
+            (typeof defaults.runtime === 'object' ? defaults.runtime.name : defaults.runtime) ||
+            'ai-sdk',
+        config: {
+            ...(defaults.runtime && typeof defaults.runtime !== 'string' ? defaults.runtime.config : {}),
+            ...(overrides.runtime && typeof overrides.runtime !== 'string' ? overrides.runtime.config : {}),
+            toolDefinitions: {
+                ...(defaults.runtime && typeof defaults.runtime !== 'string'
+                    ? defaults.runtime.config?.toolDefinitions
+                    : {}),
+                ...(overrides.runtime && typeof overrides.runtime !== 'string'
+                    ? overrides.runtime.config?.toolDefinitions
+                    : {}),
+            },
+        },
+    };
+    const mergedPlugins = [...(defaults.plugins || [])];
+    if (overrides.plugins) {
+        for (const p of overrides.plugins) {
+            const name = typeof p === 'string' ? p : p.name;
+            const index = mergedPlugins.findIndex((existing) => {
+                const existingName = typeof existing === 'string' ? existing : existing.name;
+                return existingName === name;
+            });
+            if (index !== -1) {
+                mergedPlugins[index] = p;
+            }
+            else {
+                mergedPlugins.push(p);
+            }
+        }
+    }
+    return {
+        ...defaults,
+        ...overrides,
+        id: 'system', // Always enforce 'system' ID
+        image: overrides.image || defaults.image, // Ensure image is preserved if not explicitly overridden
+        runtime: mergedRuntime,
+        plugins: mergedPlugins,
+        updatedAt: new Date(),
+    };
+};

package/dist/app/cli.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { startServer } from './server.js';
+const program = new Command();
+const REQUIRED_NODE_VERSION = '20.12.0';
+function checkNodeVersion() {
+    const [major, minor, patch] = process.versions.node.split('.').map(Number);
+    const [reqMajor, reqMinor, reqPatch] = REQUIRED_NODE_VERSION.split('.').map(Number);
+    const isOld = major < reqMajor ||
+        (major === reqMajor && minor < reqMinor) ||
+        (major === reqMajor && minor === reqMinor && patch < reqPatch);
+    if (isOld) {
+        console.warn(`\n⚠️  WARNING: You are using Node.js ${process.version}.`);
+        console.warn(`   OpenBot works best with Node.js >=${REQUIRED_NODE_VERSION}.`);
+        console.warn(`   You may encounter "ERR_REQUIRE_ESM" or other compatibility issues on older versions.\n`);
+    }
+}
+checkNodeVersion();
+program.name('openbot').description('OpenBot CLI').version('0.2.13');
+program
+    .command('start')
+    .description('Start the OpenBot harness')
+    .option('-p, --port <number>', 'Port to listen on')
+    .action(async (options) => {
+    await startServer(options);
+});
+program.parse();

package/dist/app/config.js

@@ -0,0 +1,64 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+export const DEFAULT_BASE_DIR = '~/.openbot';
+export const DEFAULT_PLUGINS_DIR = 'plugins';
+export const DEFAULT_AGENTS_DIR = 'agents';
+export const DEFAULT_CHANNELS_DIR = 'channels';
+export const CONFIG_FILE = 'config.json';
+export const VARIABLES_FILE = 'variables.json';
+export function resolvePath(p) {
+    return p.startsWith('~/') ? path.join(os.homedir(), p.slice(2)) : path.resolve(p);
+}
+export function loadConfig() {
+    const configPath = path.join(os.homedir(), '.openbot', CONFIG_FILE);
+    if (fs.existsSync(configPath)) {
+        try {
+            return JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+        }
+        catch (error) {
+            console.error(`Warning: Failed to parse config at ${configPath}`, error);
+        }
+    }
+    return {};
+}
+export function saveConfig(config) {
+    const configDir = resolvePath(DEFAULT_BASE_DIR);
+    const configPath = path.join(configDir, CONFIG_FILE);
+    if (!fs.existsSync(configDir)) {
+        fs.mkdirSync(configDir, { recursive: true, mode: 0o700 });
+    }
+    const currentConfig = loadConfig();
+    const newConfig = { ...currentConfig, ...config };
+    fs.writeFileSync(configPath, JSON.stringify(newConfig, null, 2), { mode: 0o600 });
+}
+export function isConfigured() {
+    const configPath = path.join(resolvePath(DEFAULT_BASE_DIR), CONFIG_FILE);
+    return fs.existsSync(configPath);
+}
+export function loadVariables() {
+    const variablesPath = path.join(resolvePath(DEFAULT_BASE_DIR), VARIABLES_FILE);
+    if (fs.existsSync(variablesPath)) {
+        return JSON.parse(fs.readFileSync(variablesPath, 'utf-8'));
+    }
+    return { version: 1, variables: [] };
+}
+export const DEFAULT_AGENT_MD = `---
+description: A specialized AI agent
+---
+
+# Agent Profile
+
+You are a specialized AI agent within the OpenBot system.
+Your role is defined by your configuration and the tools you have access to.
+
+## Persona
+- Helpful and precise
+- Focused on my specific domain
+- Professional in all interactions
+`;
+export const DEFAULT_USER_MD = `# About Me
+
+<!-- OpenBot reads this file to understand who you are and how you like to work. -->
+<!-- Edit it here or just chat — agents can update it with the "remember" tool. -->
+`;