openbot 0.2.13 → 0.3.0

package/docs/agents.md

@@ -1,83 +1,56 @@
 # Agents
 
-Agents are specialized entities within the OpenBot platform, each designed to handle specific domains or tasks. The platform orchestrates these agents to solve complex problems through collaboration.
+Agents are participants on the OpenBot bus. An agent is just a markdown file
+(`AGENT.md`) that lists which **plugins** compose it. Plugins provide both the
+LLM runtime and the tools the agent can call.
 
-## Built-in Agents
+## Authoring an agent
 
-### Orchestrator Agent (Default)
-The central intelligence of the platform. It manages the conversation flow, handles long-term memory, and coordinates other agents.
+You define an agent with a YAML-fronted markdown file at
+`~/.openbot/agents/<agentId>/AGENT.md`. The folder name is the agent id.
 
-### OS Agent (`os`)
-Specialized in low-level system interactions. It uses the `shell` and `file-system` plugins to execute commands and manage files. (Implementation: `src/agents/system.ts`)
-
-### Topic Agent (`topic`)
-A utility agent that observes completions and automatically generates concise titles for conversations to keep the workspace organized.
-
-### Codex Agent (`codex`)
-A world-class software engineer agent. It assists with architectural decisions, refactoring, and debugging, with full access to the development environment.
-
-## YAML Agents
-
-You can define custom agents using YAML files in `~/.openbot/agents/`.
-
-### Installing Agents
-
-You can easily install official agents using the CLI:
-
-```bash
-openbot add codex
-```
-
-This will automatically download the agent and install it into your local agents directory.
-
-Example `codex.yaml`:
 ```yaml
-name: codex
-description: "A specialized agent for writing and refactoring code"
+---
+name: Researcher
+description: Web research and synthesis specialist.
 plugins:
-  - name: file-system
-  - name: shell
-prompt: |
-  You are an expert software engineer. 
-  You use the provided tools to write high-quality code.
+  - id: ai-sdk
+    config:
+      model: anthropic/claude-3-5-sonnet-20240620
+  - id: mcp
+  - id: shell
+  - id: delegation
+---
+
+You are a web research specialist. Use the available tools to gather and
+synthesize information. Be concise and cite sources where relevant.
 ```
 
-YAML agents are automatically discovered and registered by OpenBot on startup.
-
-## TS Agents (Packages)
+The body below the frontmatter is the system prompt passed to the runtime
+plugin as `agentDetails.instructions`.
 
-For more advanced use cases, you can create a full TypeScript package as an agent. This is useful if you need custom logic, additional event handlers, or private plugins that you don't want to expose globally.
+### Required: at least one runtime plugin
 
-Place these in `~/.openbot/agents/my-ts-agent/`.
+A runtime plugin is one that handles `agent:invoke` (the LLM loop). Without
+one, the agent will not respond to user input. Built-in runtime plugins:
 
-### Structure
+- `ai-sdk` — generic LLM runtime (Vercel AI SDK). Consumes tools from other
+  plugins listed alongside it.
+- `claude-code` — runs Claude inside the Claude Agent SDK with its own tools.
+- `gemini-cli` — spawns Google's `gemini` CLI in headless mode.
 
-- `package.json`: Standard npm package configuration.
-- `index.ts`: The entry point that exports a `TSAgentDefinition`.
+`claude-code` and `gemini-cli` own their own tool loops, so attaching tool
+plugins like `shell` or `mcp` to them has no effect. Pair tool plugins with
+`ai-sdk`.
 
-### Example `index.ts`
+## Built-in agent
 
-```typescript
-import { TSAgentDefinition } from "openbot";
+OpenBot ships a built-in `system` agent (the orchestrator) with the
+`ai-sdk` runtime plus the standard tool plugins (storage, shell, mcp,
+delegation, ui, approval). It cannot be deleted.
 
-export const agent: TSAgentDefinition = {
-  name: "my-ts-agent",
-  description: "An agent with custom TypeScript logic.",
-  factory: ({ model }) => (builder) => {
-    // 1. You can use standard plugins
-    // 2. Or implement custom event handling logic here
-    // 3. Finally, wire up an LLM loop for it
-    builder.use(llmPlugin({
-      model,
-      system: "You are a specialized TS Agent...",
-      toolDefinitions: { /* custom tools */ },
-      // I/O defaults to standardized: user:input / agent:output
-    }));
-  },
-  capabilities: {
-    "do_something": "Performs a custom TS-driven action"
-  }
-};
-```
+## Installing community agents
 
-TS agents are automatically compiled and loaded on startup.
+Marketplace entries reference plugin ids (built-in or npm package names).
+Installing an agent ensures every referenced plugin is available locally,
+fetching unknown ids from npm into `~/.openbot/plugins/<id>/` on first use.

package/docs/architecture.md

@@ -16,7 +16,7 @@ The orchestrator is the central dispatcher within the harness. It receives user
 
 ### 2. Agent Registry
 A dynamic registry that manages all available agents. Agents can be:
-- **Built-in**: Core agents compiled into the platform (e.g., `src/agents/system.ts`).
+- **Built-in**: Core agent packages shipped with the repo (e.g. `src/agents/openbot/`).
 - **YAML-based**: Rapidly defined agents in `~/.openbot/agents/*/AGENT.md`.
 - **TS Packages**: Advanced agents with custom logic in `~/.openbot/agents/*/index.ts`.
 

package/docs/plugins.md

@@ -1,77 +1,89 @@
 # Plugins
 
-Plugins are the building blocks of the OpenBot platform's capabilities. They provide the tools and logic that the orchestrator and specialized agents use to interact with the world.
+A **Plugin** is the single extension unit on the OpenBot bus. Every agent is
+just a list of plugins. The bus does not distinguish between "runtime" and
+"tool" plugins — those are roles defined entirely by which events a plugin
+subscribes to and emits.
 
-## Built-in Plugins
+- **Runtime plugins** handle `agent:invoke` and run an LLM loop. They may
+  consume tools contributed by other plugins via `PluginContext.tools`.
+- **Tool plugins** expose `toolDefinitions` and handle the corresponding
+  `action:<tool>` events.
+- **Middleware plugins** observe events and re-emit them with extra logic
+  (e.g. the `approval` plugin gates protected actions).
 
-- **ai-sdk**: Integration with AI providers (OpenAI, Anthropic, etc.).
-- **storage**: Local file-based persistence for events and state.
-- **mcp**: Model Context Protocol integration.
-- **delegation**: Allows agents to delegate tasks to other agents.
-- **ui**: Server-driven UI components.
+## Plugin contract
 
-## In-depth: Approval Plugin
-
-The `approval` plugin is a safety layer that can be added to any agent. It intercepts specified actions and suspends execution until a user manually approves or denies the action via the UI.
-
-### Configuration
-
-Add it to your `AGENT.md` frontmatter:
+```ts
+export interface Plugin {
+  id: string;
+  name: string;
+  description: string;
+  image?: string;
+  defaultInstructions?: string;
+  configSchema?: ConfigSchema;
+  toolDefinitions?: Record<string, ToolDefinition>;
+  factory: (context: PluginContext) => MelonyPlugin;
+}
 
-```yaml
-plugins:
-  - name: approval
-    config:
-      rules:
-        - action: "action:executeCommand"
-          message: "The agent wants to execute a terminal command."
-          detailKeys: ["command", "cwd"]
-          hiddenKeys: ["env"]
-        - action: "action:writeFile"
-          message: "The agent wants to modify a file."
-          detailKeys: ["path"]
+export interface PluginContext {
+  agentId: string;
+  agentDetails: AgentDetails;
+  config: Record<string, unknown>;   // from AGENT.md plugins[].config
+  storage: Storage;
+  tools: Record<string, ToolDefinition>; // merged from all tool plugins
+}
 ```
 
-- `action`: The event type prefix to intercept (e.g., `action:executeCommand`).
-- `message`: Optional custom message to display in the approval UI.
-- `detailKeys`: Optional ordered list of event data keys to show in the compact details block.
-- `hiddenKeys`: Optional list of keys to redact from details and full payload.
+The agent loader collects `toolDefinitions` from every plugin attached to the
+same agent into a single map and passes it to every plugin via `context.tools`.
+Runtime plugins read it; tool plugins ignore it. First plugin wins on tool
+name collisions.
 
-### Approval UI Details Payload
+## Built-in plugins
 
-The approval card keeps the same visual widget but now renders structured details for clearer decisions.
+| Id              | Role       | Notes                                                     |
+| --------------- | ---------- | --------------------------------------------------------- |
+| `ai-sdk`        | Runtime    | Generic LLM loop on Vercel AI SDK; consumes external tools |
+| `claude-code`   | Runtime    | Claude Agent SDK; owns its own tool loop                  |
+| `gemini-cli`    | Runtime    | Google `gemini` CLI in headless mode                      |
+| `shell`         | Tool       | `shell_exec`                                              |
+| `mcp`           | Tool       | `mcp_list_tools`, `mcp_call`                              |
+| `delegation`    | Tool       | `handoff`, `delegate`                                     |
+| `storage-tools` | Tool       | `create_channel`, `patch_*`, `create_variable`, ...       |
+| `ui`            | Tool       | `render_ui_widget`                                        |
+| `approval`      | Middleware | Gates protected actions behind a UI confirmation widget   |
 
-Payload shape sent to the widget:
+## Community plugins
 
-```ts
-{
-  summary: string;
-  details?: Array<{ label: string; value: string }>;
-  rawPayload?: string;
-}
-```
-
-What users now see before approving:
-- Action label and event type.
-- A compact details list based on `detailKeys` (or auto-derived keys if omitted).
-- A sanitized full action payload (sensitive keys are redacted and very large values are truncated).
+A community plugin is just an npm package whose default export matches the
+`Plugin` interface. Reference it by its npm package name in AGENT.md:
 
-## Shared Plugins
+```yaml
+plugins:
+  - id: openbot-plugin-search
+    config:
+      provider: tavily
+```
 
-Shared plugins are community-contributed or user-defined plugins that can be installed into `~/.openbot/plugins/`. Once installed, they are automatically registered in the Plugin Registry and become available to any agent that references them.
+On first use OpenBot installs the package into
+`~/.openbot/plugins/<npm-name>/` (scoped packages live under
+`~/.openbot/plugins/@scope/<name>/`).
 
-### Installing a Plugin
+## Approval plugin
 
-For official plugins, you can use the `add` command:
+The `approval` plugin reads its rules from per-agent config:
 
-```bash
-openbot add search
+```yaml
+plugins:
+  - id: approval
+    config:
+      rules:
+        - action: action:shell_exec
+          message: The agent wants to run a terminal command.
+          detailKeys: [command, cwd, shell, timeoutMs]
+          hiddenKeys: [env]
 ```
 
-## Creating a Plugin
-
-A plugin is typically a Node.js package that exports:
-- `name`: Unique identifier.
-- `description`: What the plugin does.
-- `toolDefinitions`: Zod-based definitions for the tools it provides.
-- `factory`: A function that initializes the plugin logic.
+If `rules` is omitted, sensible defaults are applied (currently: gate
+`action:shell_exec`).

package/docs/templates/AGENT.example.md

@@ -0,0 +1,57 @@
+---
+# OpenBot agent profile (YAML frontmatter)
+#
+# File location: ~/.openbot/agents/<agentId>/AGENT.md
+# The agent id is the folder name (<agentId>), not a field in this file.
+#
+name: Example Agent
+description: One-line description shown in agent pickers and lists.
+
+# Plugins compose the agent. Order matters for tool collisions (first wins).
+# At least one plugin must handle `agent:invoke` (a "runtime" plugin like
+# `ai-sdk`, `claude-code`, or `gemini-cli`). Tool plugins like `shell`, `mcp`,
+# `delegation`, `storage-tools`, and `ui` contribute tools to whichever runtime
+# plugin can consume them.
+#
+# Built-in plugin ids: ai-sdk, claude-code, gemini-cli, shell, mcp, delegation,
+# storage-tools, ui, approval.
+#
+# Community plugins are referenced by their npm package name (e.g.
+# `openbot-plugin-search` or `@scope/openbot-plugin-foo`) and are auto-installed
+# on first use into ~/.openbot/plugins/<id>/.
+plugins:
+  - id: ai-sdk
+    config:
+      model: openai/gpt-4o-mini
+  - id: shell
+  - id: mcp
+  - id: delegation
+  - id: storage-tools
+  - id: ui
+  - id: approval
+    config:
+      rules:
+        - action: action:shell_exec
+          message: The agent wants to run a terminal command.
+          detailKeys: [command, cwd, shell, timeoutMs]
+          hiddenKeys: [env]
+---
+
+<!--
+  Everything below the closing --- is the agent instructions (system prompt body).
+  It is stored as markdown and passed to runtime plugins as agentDetails.instructions.
+-->
+
+# Role
+
+You are **Example Agent**, a specialist for [describe domain here].
+
+## Behaviour
+
+- Be concise unless the user asks for depth.
+- When unsure, ask a clarifying question instead of guessing.
+
+## Scope
+
+- **In scope:** [list what you handle]
+- **Out of scope:** [defer to another agent for…]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openbot",
-  "version": "0.2.13",
+  "version": "0.3.0",
   "private": false,
   "type": "module",
   "engines": {
@@ -12,11 +12,12 @@
     "start": "node dist/app/cli.js start"
   },
   "bin": {
-    "openbot": "./dist/app/cli.js start"
+    "openbot": "./dist/app/cli.js"
   },
   "dependencies": {
     "@ai-sdk/anthropic": "^3.0.33",
     "@ai-sdk/openai": "^3.0.13",
+    "@anthropic-ai/claude-agent-sdk": "^0.2.138",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@types/cors": "^2.8.19",
     "ai": "^6.0.42",

package/src/app/cli.ts

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

package/src/app/config.ts

@@ -10,11 +10,13 @@ export interface OpenBotconfig {
   baseDir?: string;
   port?: number;
   mcpServers?: MCPServerConfig[];
-  globalPlugins?: PluginSpec[];
+  /**
+   * Overrides the default public marketplace registry URL. If omitted or blank,
+   * {@link DEFAULT_MARKETPLACE_REGISTRY_URL} is used.
+   */
+  marketplaceRegistryUrl?: string;
 }
 
-export type PluginSpec = string | { name: string; config?: Record<string, unknown> };
-
 export interface MCPServerConfig {
   id: string;
   command: string;
@@ -36,6 +38,10 @@ export const DEFAULT_CHANNELS_DIR = 'channels';
 export const CONFIG_FILE = 'config.json';
 export const VARIABLES_FILE = 'variables.json';
 
+/** Public agent registry used when `marketplaceRegistryUrl` is not set. */
+export const DEFAULT_MARKETPLACE_REGISTRY_URL =
+  'https://raw.githubusercontent.com/meetopenbot/openbot-registry/main/registry.json';
+
 export function resolvePath(p: string) {
   return p.startsWith('~/') ? path.join(os.homedir(), p.slice(2)) : path.resolve(p);
 }
@@ -72,7 +78,11 @@ export function isConfigured(): boolean {
 }
 
 export function loadVariables(): { version: number; variables: StoredVariable[] } {
-  const variablesPath = path.join(resolvePath(DEFAULT_BASE_DIR), VARIABLES_FILE);
+  const config = loadConfig();
+  const variablesPath = path.join(
+    resolvePath(config.baseDir || DEFAULT_BASE_DIR),
+    VARIABLES_FILE,
+  );
   if (fs.existsSync(variablesPath)) {
     return JSON.parse(fs.readFileSync(variablesPath, 'utf-8')) as {
       version: number;

package/src/app/server.ts

@@ -4,8 +4,11 @@ import cors from 'cors';
 import z from 'zod';
 import path from 'path';
 import fs from 'fs/promises';
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+const pkg = require('../../package.json');
 import { generateId } from 'melony';
-import { DEFAULT_BASE_DIR, loadConfig, loadVariables, resolvePath } from '../app/config.js';
+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';
@@ -28,9 +31,7 @@ export async function startServer(options: ServerOptions = {}) {
     .passthrough();
 
   const config = loadConfig();
-  const variables = loadVariables();
-
-  processService.applyVariablesToProcessEnv(variables.variables);
+  processService.syncWorkspaceVariablesToProcessEnv();
 
   const baseDir = config.baseDir || DEFAULT_BASE_DIR;
   const openBotDir = resolvePath(baseDir);
@@ -79,6 +80,8 @@ export async function startServer(options: ServerOptions = {}) {
 
   const getClientKey = (channelId: string, threadId?: string) =>
     threadId ? `${channelId}:${threadId}` : channelId;
+  const getRunKey = (runId: string, agentId: string, channelId: string, threadId?: string) =>
+    `${runId}:${agentId}:${channelId}:${threadId || ''}`;
 
   const sendToClientKey = (clientKey: string, chunk: OpenBotEvent) => {
     const threadClients = clients.get(clientKey);
@@ -116,6 +119,10 @@ export async function startServer(options: ServerOptions = {}) {
   app.use(cors());
   app.use(express.json({ limit: '20mb' }));
 
+  app.get('/api/health', (req, res) => {
+    res.json({ status: 'ok', version: pkg.version });
+  });
+
   app.get('/api/events', (req, res) => {
     const { channelId, threadId } = getContext(req);
     const clientKey = getClientKey(channelId, threadId);
@@ -196,14 +203,19 @@ export async function startServer(options: ServerOptions = {}) {
       const targetClientKey = getClientKey(targetChannelId, targetThreadId);
 
       if (chunk.type === 'agent:run:start') {
-        activeRuns.set(chunk.data.runId, {
+        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,
-        });
+          },
+        );
       } else if (chunk.type === 'agent:run:end') {
-        activeRuns.delete(chunk.data.runId);
+        activeRuns.delete(
+          getRunKey(chunk.data.runId, chunk.data.agentId, chunk.data.channelId, chunk.data.threadId),
+        );
       }
 
       await storageService.storeEvent({
@@ -277,8 +289,9 @@ export async function startServer(options: ServerOptions = {}) {
 
   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`);
+    console.log(`  - Health endpoint: GET /health`);
+    console.log(`  - Events endpoint: GET /api/events (SSE)`);
+    console.log(`  - Publish endpoint: POST /api/publish`);
+    console.log(`  - State endpoint: GET /api/state`);
   });
 }