openbot 0.4.6 → 0.5.4

package/dist/plugins/storage/service.js

@@ -1,5 +1,6 @@
 import { ORCHESTRATOR_AGENT_ID, STATE_AGENT_ID } from '../../app/agent-ids.js';
-import { DEFAULT_PLUGINS_DIR, DEFAULT_AGENTS_DIR, DEFAULT_BASE_DIR, DEFAULT_CHANNELS_DIR, getDefaultChannelCwd, loadConfig, resolvePath, VARIABLES_FILE, } from '../../app/config.js';
+import { assertCloudSystemAgentPluginsMutable, CLOUD_SYSTEM_MODEL, isCloudMode, } from '../../app/cloud-mode.js';
+import { DEFAULT_PLUGINS_DIR, DEFAULT_AGENTS_DIR, DEFAULT_CHANNELS_DIR, getBaseDir, getDefaultChannelCwd, resolvePath, VARIABLES_FILE, } from '../../app/config.js';
 import fs from 'node:fs/promises';
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
@@ -8,13 +9,11 @@ import crypto from 'node:crypto';
 import matter from 'gray-matter';
 import { openbotPlugin } from '../openbot/index.js';
 import { listBuiltInPlugins, parsePluginModule } from '../../services/plugins/registry.js';
+import { enrichOpenbotPluginDescriptor, listRegistryModelOptions, } from '../../services/plugins/model-registry.js';
 import { processService } from '../../services/process.js';
 import { memoryService } from '../memory/service.js';
 import { guessMimeType, resolveChannelFile, statChannelFile, } from './files.js';
-const resolveBaseDir = () => {
-    const config = loadConfig();
-    return resolvePath(config.baseDir || DEFAULT_BASE_DIR);
-};
+const resolveBaseDir = () => getBaseDir();
 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;
@@ -85,11 +84,37 @@ const SYSTEM_DEFAULT_PLUGINS = [
         config: {
             model: 'openai/gpt-5.4-mini',
             approval: {
-                actions: ['action:bash', 'action:create_channel', 'action:delete_channel'],
+                actions: ['action:shell_exec', 'action:create_channel', 'action:delete_channel'],
+            },
+        },
+    },
+];
+const CLOUD_SYSTEM_DEFAULT_PLUGINS = [
+    {
+        id: 'openbot',
+        config: {
+            model: CLOUD_SYSTEM_MODEL,
+            approval: {
+                actions: ['action:shell_exec', 'action:create_channel', 'action:delete_channel'],
             },
         },
     },
 ];
+function mergeCloudSystemPluginRefs(defaults, diskRefs) {
+    const defaultOpenbot = defaults.find((ref) => ref.id === 'openbot');
+    const diskOpenbot = diskRefs.find((ref) => ref.id === 'openbot');
+    if (!defaultOpenbot)
+        return defaults;
+    return [
+        {
+            ...defaultOpenbot,
+            config: {
+                ...defaultOpenbot.config,
+                ...diskOpenbot?.config,
+            },
+        },
+    ];
+}
 /** No `openbot` / `bash` — storage-side effects and infra plugins only. */
 const STATE_DEFAULT_PLUGINS = [
     { id: 'storage' },
@@ -97,24 +122,41 @@ const STATE_DEFAULT_PLUGINS = [
 ];
 const STATE_AGENT_INSTRUCTIONS = 'Built-in infra agent for deterministic state reads. No conversational model is attached; handle storage, approvals, memory, and plugin marketplace events.';
 function getSystemAgentDetails(overrides) {
+    const defaultPlugins = isCloudMode() ? CLOUD_SYSTEM_DEFAULT_PLUGINS : SYSTEM_DEFAULT_PLUGINS;
     const defaults = {
         id: SYSTEM_AGENT_ID,
         name: 'OpenBot',
         image: getBundledSystemAgentImage(),
         description: 'First-party orchestration agent for OpenBot.',
         instructions: '',
-        plugins: SYSTEM_DEFAULT_PLUGINS.map((ref) => ref.id),
-        pluginRefs: SYSTEM_DEFAULT_PLUGINS,
+        plugins: defaultPlugins.map((ref) => ref.id),
+        pluginRefs: defaultPlugins,
         createdAt: new Date(),
         updatedAt: new Date(),
     };
     if (!overrides)
         return defaults;
+    const diskInstructions = overrides.instructions?.trim();
+    const instructions = diskInstructions && diskInstructions.length > 0 ? diskInstructions : defaults.instructions;
+    if (isCloudMode()) {
+        const diskRefs = overrides.pluginRefs && overrides.pluginRefs.length > 0 ? overrides.pluginRefs : undefined;
+        const refs = diskRefs
+            ? mergeCloudSystemPluginRefs(defaults.pluginRefs, diskRefs)
+            : defaults.pluginRefs;
+        return {
+            ...defaults,
+            ...overrides,
+            id: SYSTEM_AGENT_ID,
+            instructions,
+            image: overrides.image || defaults.image,
+            plugins: refs.map((ref) => ref.id),
+            pluginRefs: refs,
+            updatedAt: new Date(),
+        };
+    }
     const refs = overrides.pluginRefs && overrides.pluginRefs.length > 0
         ? overrides.pluginRefs
         : defaults.pluginRefs;
-    const diskInstructions = overrides.instructions?.trim();
-    const instructions = diskInstructions && diskInstructions.length > 0 ? diskInstructions : defaults.instructions;
     return {
         ...defaults,
         ...overrides,
@@ -775,11 +817,13 @@ export const storageService = {
         return Array.from(deduped.values()).filter((agent) => !agent.hidden);
     },
     getPlugins: async () => {
-        const [builtIn, fromDisk] = await Promise.all([
+        const [builtIn, fromDisk, modelOptions] = await Promise.all([
             listBuiltInPluginDescriptors(),
             listPluginsFromDisk(),
+            listRegistryModelOptions(),
         ]);
-        const merged = [...builtIn, ...fromDisk];
+        const enrichedBuiltIn = builtIn.map((plugin) => enrichOpenbotPluginDescriptor(plugin, modelOptions));
+        const merged = [...enrichedBuiltIn, ...fromDisk];
         const deduped = new Map();
         for (const plugin of merged) {
             if (!deduped.has(plugin.id)) {
@@ -839,6 +883,7 @@ export const storageService = {
     },
     createAgent: async ({ agentId, name, description = '', image, hidden, instructions, plugins, }) => {
         assertAgentIdFormat(agentId);
+        assertCloudSystemAgentPluginsMutable(agentId, plugins);
         const agentDir = resolvePath(path.join(getAgentsRootDir(), agentId));
         const agentMdPath = path.join(agentDir, 'AGENT.md');
         try {
@@ -874,6 +919,7 @@ export const storageService = {
     },
     updateAgent: async ({ agentId, name, description, image, hidden, instructions, plugins, }) => {
         assertAgentIdFormat(agentId);
+        assertCloudSystemAgentPluginsMutable(agentId, plugins);
         const agentDir = resolvePath(path.join(getAgentsRootDir(), agentId));
         const agentMdPath = path.join(agentDir, 'AGENT.md');
         let raw;

package/dist/plugins/todo/index.js

@@ -1,53 +1,146 @@
 import z from 'zod';
-const todoStatus = z.enum(['pending', 'in_progress', 'done', 'cancelled']);
+import { todoService } from './service.js';
+/**
+ * `todo` — thread-scoped task checklist for multi-step agent work.
+ *
+ * Persisted at `~/.openbot/channels/<channelId>/threads/<threadId>/todos.json`.
+ * The agent replaces the full list via `todo_write`; the runtime injects the
+ * current list into context each turn.
+ */
+/** Map todo statuses onto UI list-item status label + variant. */
+function toWidgetItemStatus(status) {
+    switch (status) {
+        case 'pending':
+            return { status: 'Pending', statusVariant: 'default' };
+        case 'in_progress':
+            return { status: 'In progress', statusVariant: 'info' };
+        case 'completed':
+            return { status: 'Done', statusVariant: 'success' };
+        case 'cancelled':
+            return { status: 'Cancelled', statusVariant: 'danger' };
+    }
+}
+function formatTodoOutput(list) {
+    if (list.items.length === 0)
+        return 'Todo list is empty.';
+    const lines = list.items.map((t) => `- [${t.status}] (${t.id}) ${t.content}`);
+    return `Todos (${list.items.length}):\n${lines.join('\n')}`;
+}
+function todoListWidget(args) {
+    const items = args.list.items.map((t) => ({
+        id: t.id,
+        label: t.content,
+        ...toWidgetItemStatus(t.status),
+    }));
+    return {
+        type: 'client:ui:widget',
+        data: {
+            // One widget per agent run — repeated todo_write calls update in place.
+            widgetId: `todos:${args.runId}`,
+            kind: 'list',
+            title: 'Todos',
+            description: args.list.items.length === 0
+                ? 'No todos'
+                : `${args.list.items.filter((t) => t.status === 'completed').length}/${args.list.items.length} completed`,
+            items,
+            display: 'expanded',
+            state: 'open',
+        },
+        meta: {},
+    };
+}
+const todoItemSchema = z.object({
+    id: z.string().min(1).describe('Stable todo id (e.g. "1", "setup-repo").'),
+    content: z.string().min(1).describe('Short imperative description of the step.'),
+    status: z
+        .enum(['pending', 'in_progress', 'completed', 'cancelled'])
+        .describe('Todo status. At most one item may be in_progress.'),
+});
 const todoToolDefinitions = {
     todo_write: {
-        description: 'Manage the shared todo list (create, update, append, remove).',
+        description: 'Replace the current thread todo list with the provided items. Use for multi-step tasks: write the plan first, keep exactly one item in_progress while working, mark items completed immediately after finishing, and when done leave all items as completed (do not clear the list). Pass the full intended list each call (not a partial patch).',
         inputSchema: z.object({
-            todos: z
-                .array(z.object({
-                id: z
-                    .string()
-                    .optional()
-                    .describe('Stable id. Reuse existing ids to update; omit to create.'),
-                content: z.string().min(1).optional().describe('What needs to be done.'),
-                status: todoStatus.optional().describe('Defaults to `pending`.'),
-                assignee: z
-                    .string()
-                    .optional()
-                    .describe('Suggested agent id for this step (plain id, no @ prefix).'),
-                deleted: z.boolean().optional().describe('If true, remove this item.'),
-            }))
-                .describe('List of todo items to write or patch.'),
-            merge: z
-                .boolean()
-                .optional()
-                .describe('If true (default), patches existing items by id and appends new ones. If false, replaces the entire list.'),
+            items: z
+                .array(todoItemSchema)
+                .max(20)
+                .describe('Full todo list for this thread (max 20). Replaces any previous list.'),
         }),
     },
-    delegate_to_agent: {
-        description: 'Run a worker agent on a self-contained task and return their output. ' +
-            'Call when a todo step should be executed by a participant; review the result and update todos before delegating again or replying to the user.',
-        inputSchema: z.object({
-            agentId: z
-                .string()
-                .min(1)
-                .describe('Worker agent id from channel participants (plain id, no @ prefix).'),
-            task: z
-                .string()
-                .min(1)
-                .describe('Complete instruction for the worker — they do not see the full todo plan.'),
-            todoId: z.string().optional().describe('Optional todo id this step relates to.'),
-        }),
+    todo_read: {
+        description: 'Read the current thread todo list. Usually unnecessary — the list is already injected into context each turn. Use only if you need an explicit refresh after an external change.',
+        inputSchema: z.object({}),
     },
 };
 export const todoPlugin = {
     id: 'todo',
     name: 'Todo',
-    description: 'Shared todo list and worker delegation for multi-step orchestration.',
+    description: 'Thread-scoped todo checklist for multi-step task tracking (todo_write / todo_read).',
     toolDefinitions: todoToolDefinitions,
-    factory: () => () => {
-        // Handlers live in bus/services.ts.
+    factory: () => (builder) => {
+        builder.on('action:todo_write', async function* (event, context) {
+            const resultMeta = { ...(event.meta || {}), agentId: context.state.agentId };
+            try {
+                const channelId = context.state.channelId;
+                const threadId = context.state.threadId;
+                if (!channelId || !threadId) {
+                    throw new Error('Missing channelId or threadId for todo_write');
+                }
+                const items = event.data.items;
+                const list = await todoService.writeTodos({ channelId, threadId, items });
+                const runId = context.state.runId;
+                if (!runId) {
+                    throw new Error('Missing runId for todo_write widget');
+                }
+                const widget = todoListWidget({ runId, list });
+                widget.meta = { ...resultMeta, threadId, runId };
+                yield widget;
+                yield {
+                    type: 'action:todo_write:result',
+                    data: { success: true, list, output: formatTodoOutput(list) },
+                    meta: resultMeta,
+                };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : 'Unknown error';
+                yield {
+                    type: 'action:todo_write:result',
+                    data: {
+                        success: false,
+                        error: message,
+                        output: message,
+                    },
+                    meta: resultMeta,
+                };
+            }
+        });
+        builder.on('action:todo_read', async function* (event, context) {
+            const resultMeta = { ...(event.meta || {}), agentId: context.state.agentId };
+            try {
+                const channelId = context.state.channelId;
+                const threadId = context.state.threadId;
+                if (!channelId || !threadId) {
+                    throw new Error('Missing channelId or threadId for todo_read');
+                }
+                const list = await todoService.getTodos({ channelId, threadId });
+                yield {
+                    type: 'action:todo_read:result',
+                    data: { success: true, list, output: formatTodoOutput(list) },
+                    meta: resultMeta,
+                };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : 'Unknown error';
+                yield {
+                    type: 'action:todo_read:result',
+                    data: {
+                        success: false,
+                        error: message,
+                        output: message,
+                    },
+                    meta: resultMeta,
+                };
+            }
+        });
     },
 };
 export default todoPlugin;

package/dist/plugins/todo/service.js

@@ -0,0 +1,93 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { DEFAULT_CHANNELS_DIR, getBaseDir, resolvePath } from '../../app/config.js';
+export const MAX_TODO_ITEMS = 20;
+const TODO_STATUSES = new Set([
+    'pending',
+    'in_progress',
+    'completed',
+    'cancelled',
+]);
+const getThreadDir = (channelId, threadId) => {
+    const base = resolvePath(path.join(getBaseDir(), DEFAULT_CHANNELS_DIR, channelId));
+    return path.join(base, 'threads', threadId);
+};
+const getTodosPath = (channelId, threadId) => path.join(getThreadDir(channelId, threadId), 'todos.json');
+const emptyList = () => ({
+    items: [],
+    updatedAt: new Date().toISOString(),
+});
+/**
+ * Validate and normalize a todo list write. Throws on invalid input.
+ * Enforces: non-empty content, known statuses, unique ids, max size,
+ * and at most one `in_progress` item.
+ */
+export function validateTodoItems(items) {
+    if (!Array.isArray(items)) {
+        throw new Error('todos must be an array');
+    }
+    if (items.length > MAX_TODO_ITEMS) {
+        throw new Error(`At most ${MAX_TODO_ITEMS} todos allowed`);
+    }
+    const seen = new Set();
+    let inProgressCount = 0;
+    const normalized = [];
+    for (const raw of items) {
+        if (!raw || typeof raw !== 'object') {
+            throw new Error('Each todo must be an object');
+        }
+        const id = typeof raw.id === 'string' ? raw.id.trim() : '';
+        const content = typeof raw.content === 'string' ? raw.content.trim() : '';
+        const status = raw.status;
+        if (!id)
+            throw new Error('Each todo requires a non-empty id');
+        if (!content)
+            throw new Error(`Todo "${id}" requires non-empty content`);
+        if (!TODO_STATUSES.has(status)) {
+            throw new Error(`Todo "${id}" has invalid status "${String(status)}"; expected pending|in_progress|completed|cancelled`);
+        }
+        if (seen.has(id))
+            throw new Error(`Duplicate todo id "${id}"`);
+        seen.add(id);
+        if (status === 'in_progress')
+            inProgressCount += 1;
+        normalized.push({ id, content, status: status });
+    }
+    if (inProgressCount > 1) {
+        throw new Error('At most one todo may be in_progress');
+    }
+    return normalized;
+}
+export const todoService = {
+    getTodos: async (args) => {
+        const filePath = getTodosPath(args.channelId, args.threadId);
+        try {
+            const raw = await fs.readFile(filePath, 'utf-8');
+            const parsed = JSON.parse(raw);
+            const items = Array.isArray(parsed.items) ? parsed.items : [];
+            return {
+                items,
+                updatedAt: typeof parsed.updatedAt === 'string' ? parsed.updatedAt : new Date().toISOString(),
+            };
+        }
+        catch (e) {
+            if (e?.code === 'ENOENT')
+                return emptyList();
+            throw e;
+        }
+    },
+    writeTodos: async (args) => {
+        const items = validateTodoItems(args.items);
+        const list = {
+            items,
+            updatedAt: new Date().toISOString(),
+        };
+        const threadDir = getThreadDir(args.channelId, args.threadId);
+        await fs.mkdir(threadDir, { recursive: true });
+        const filePath = getTodosPath(args.channelId, args.threadId);
+        const tmp = `${filePath}.tmp`;
+        await fs.writeFile(tmp, `${JSON.stringify(list, null, 2)}\n`, 'utf-8');
+        await fs.rename(tmp, filePath);
+        return list;
+    },
+};

package/dist/plugins/ui/index.js

@@ -36,7 +36,14 @@ export const uiPlugin = {
                     id: z.string(),
                     label: z.string(),
                     description: z.string().optional(),
-                    status: z.enum(['pending', 'in_progress', 'done', 'error', 'cancelled']).optional(),
+                    status: z
+                        .string()
+                        .optional()
+                        .describe('Status label shown on the item (e.g. "Pending", "Shipped").'),
+                    statusVariant: z
+                        .enum(['default', 'success', 'warning', 'danger', 'info'])
+                        .optional()
+                        .describe('Semantic hint for status badge coloring in the client.'),
                     metadata: z.record(z.string(), z.any()).optional()
                 })).optional().describe('Required for kind="list". List of items to display.'),
                 submitLabel: z.string().optional().describe('Label for the primary action button (e.g. "Submit", "Save").')

package/dist/services/plugins/model-registry.js

@@ -0,0 +1,101 @@
+import { DEFAULT_MARKETPLACE_REGISTRY_URL, loadConfig, } from '../../app/config.js';
+import { isCloudMode } from '../../app/cloud-mode.js';
+let cachedRegistry = null;
+let cacheUrl = null;
+function getRegistryUrl() {
+    const { marketplaceRegistryUrl } = loadConfig();
+    return marketplaceRegistryUrl?.trim() || DEFAULT_MARKETPLACE_REGISTRY_URL;
+}
+export async function resolveModelRegistry() {
+    const url = getRegistryUrl();
+    if (cachedRegistry && cacheUrl === url)
+        return cachedRegistry;
+    try {
+        const res = await fetch(url, {
+            headers: { Accept: 'application/json' },
+            signal: AbortSignal.timeout(15000),
+        });
+        if (!res.ok) {
+            throw new Error(`Registry HTTP ${res.status} ${res.statusText}`);
+        }
+        cachedRegistry = (await res.json());
+        cacheUrl = url;
+        return cachedRegistry;
+    }
+    catch (err) {
+        console.warn('[model-registry] fetch failed:', err instanceof Error ? err.message : err);
+        return { providers: {} };
+    }
+}
+export function listModelOptionsFromRegistry(registry) {
+    const providers = registry.providers ?? {};
+    const out = [];
+    for (const [providerId, provider] of Object.entries(providers)) {
+        for (const model of provider.models ?? []) {
+            out.push({
+                value: `${providerId}/${model.id}`,
+                label: `${provider.label} — ${model.label}`,
+                description: model.description,
+                provider: providerId,
+            });
+        }
+    }
+    return out;
+}
+export async function listRegistryModelOptions() {
+    const registry = await resolveModelRegistry();
+    return listModelOptionsFromRegistry(registry);
+}
+export function listApiKeyProvidersFromRegistry(registry) {
+    const providers = registry.providers ?? {};
+    return Object.entries(providers).map(([id, provider]) => ({
+        id,
+        label: provider.label,
+    }));
+}
+function pickDefaultModelValue(options) {
+    if (options.length === 0)
+        return undefined;
+    const values = options.map((option) => option.value);
+    const preferred = isCloudMode()
+        ? values.find((value) => value.startsWith('openbot/'))
+        : values.find((value) => value.startsWith('openai/'));
+    return preferred ?? values[0];
+}
+export function enrichOpenbotPluginDescriptor(descriptor, modelOptions) {
+    if (descriptor.id !== 'openbot' || !descriptor.configSchema)
+        return descriptor;
+    const modelProperty = descriptor.configSchema.properties.model;
+    if (!modelProperty)
+        return descriptor;
+    const values = modelOptions.map((option) => option.value);
+    const staticDefault = typeof modelProperty.default === 'string' ? modelProperty.default : undefined;
+    const defaultModel = staticDefault && values.includes(staticDefault)
+        ? staticDefault
+        : pickDefaultModelValue(modelOptions) ?? staticDefault;
+    const nextModelProperty = {
+        ...modelProperty,
+        description: 'Model from the hosted marketplace registry.',
+    };
+    if (values.length > 0) {
+        nextModelProperty.enum = values;
+        nextModelProperty.options = modelOptions.map((option) => ({
+            label: option.label,
+            value: option.value,
+            description: option.description,
+        }));
+    }
+    if (defaultModel) {
+        nextModelProperty.default = defaultModel;
+    }
+    return {
+        ...descriptor,
+        configSchema: {
+            ...descriptor.configSchema,
+            properties: {
+                ...descriptor.configSchema.properties,
+                model: nextModelProperty,
+            },
+        },
+    };
+}

package/dist/services/plugins/registry.js

@@ -6,10 +6,12 @@ import { bashPlugin } from '../../plugins/bash/index.js';
 import { storagePlugin } from '../../plugins/storage/index.js';
 import { approvalPlugin } from '../../plugins/approval/index.js';
 import { memoryPlugin } from '../../plugins/memory/index.js';
+import { todoPlugin } from '../../plugins/todo/index.js';
 import { delegationPlugin } from '../../plugins/delegation/index.js';
 import { uiPlugin } from '../../plugins/ui/index.js';
 import { pluginManagerPlugin } from '../../plugins/plugin-manager/index.js';
-import { DEFAULT_PLUGINS_DIR, DEFAULT_BASE_DIR, loadConfig, resolvePath } from '../../app/config.js';
+import { previewPlugin } from '../../plugins/preview/index.js';
+import { DEFAULT_PLUGINS_DIR, getBaseDir } from '../../app/config.js';
 import { invalidatePlugin as clearResolvedPluginEntry, loadedCommunityPlugins, resolvedPluginCache, } from './plugin-cache.js';
 let pluginsDir = null;
 const BUILT_IN = {
@@ -18,9 +20,11 @@ const BUILT_IN = {
     [storagePlugin.id]: storagePlugin,
     [approvalPlugin.id]: approvalPlugin,
     [memoryPlugin.id]: memoryPlugin,
+    [todoPlugin.id]: todoPlugin,
     [delegationPlugin.id]: delegationPlugin,
     [uiPlugin.id]: uiPlugin,
     [pluginManagerPlugin.id]: pluginManagerPlugin,
+    [previewPlugin.id]: previewPlugin,
 };
 /** Normalize a dynamically imported plugin module. Supports `plugin`, `default`. */
 export function parsePluginModule(module) {
@@ -51,9 +55,7 @@ export function initPlugins(dir) {
         pluginsDir = dir;
     }
     else {
-        const config = loadConfig();
-        const baseDir = config.baseDir || DEFAULT_BASE_DIR;
-        pluginsDir = path.join(resolvePath(baseDir), DEFAULT_PLUGINS_DIR);
+        pluginsDir = path.join(getBaseDir(), DEFAULT_PLUGINS_DIR);
     }
 }
 /**

package/dist/services/plugins/service.js

@@ -3,7 +3,7 @@ import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { exec } from 'node:child_process';
 import { promisify } from 'node:util';
-import { DEFAULT_PLUGINS_DIR, DEFAULT_BASE_DIR, DEFAULT_MARKETPLACE_REGISTRY_URL, loadConfig, resolvePath, } from '../../app/config.js';
+import { DEFAULT_PLUGINS_DIR, DEFAULT_MARKETPLACE_REGISTRY_URL, getBaseDir, loadConfig, } from '../../app/config.js';
 import { invalidatePlugin } from './plugin-cache.js';
 const execAsync = promisify(exec);
 const DEFAULT_MARKETPLACE_AGENTS = [];
@@ -136,11 +136,7 @@ export async function resolveMarketplaceAgentList() {
     const registry = await resolveMarketplaceRegistry();
     return registry.agents;
 }
-const getPluginsDir = () => {
-    const config = loadConfig();
-    const baseDir = resolvePath(config.baseDir || DEFAULT_BASE_DIR);
-    return path.join(baseDir, DEFAULT_PLUGINS_DIR);
-};
+const getPluginsDir = () => path.join(getBaseDir(), DEFAULT_PLUGINS_DIR);
 /**
  * Lifecycle for community-built plugins distributed via npm.
  * Each plugin is installed to `<plugins>/<npm-name>/` and is identified

package/docs/agents.md

@@ -36,8 +36,8 @@ 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:
 
 - `openbot` — the standard, opinionated OpenBot agent runtime. It is
-  **batteries-included** and provides inbuilt tools (bash, memory, storage,
-  delegation, and approval).
+  **batteries-included** and provides inbuilt tools (bash, memory, todo,
+  storage, delegation, and approval).
 - `claude-code` — runs Claude inside the Claude Agent SDK with its own tools.
 - `gemini-cli` — spawns Google's `gemini` CLI in headless mode.
 
@@ -66,6 +66,24 @@ On every LLM turn the runtime injects matching memories into the system prompt
 via the `MemoryProvider` in the context engine, so the model treats remembered
 facts as ground truth without needing to call `recall` first.
 
+## Todos
+
+The `todo` plugin gives agents `todo_write` and `todo_read` for thread-scoped
+multi-step task tracking. The list is stored at
+`~/.openbot/channels/<channelId>/threads/<threadId>/todos.json`.
+
+Rules enforced by the runtime:
+
+- At most 20 items
+- At most one item may be `in_progress`
+- Each `todo_write` replaces the full list
+
+On every LLM turn the current list is injected into context as `## TODOS`, so
+the model usually does not need `todo_read`. Each successful `todo_write` also
+emits a `client:ui:widget` list (`widgetId` `todos:<runId>`, stable for the
+agent run so multiple `todo_write` calls update one widget), and both tools return
+`data.output` for model feedback.
+
 ## Installing community agents
 
 Marketplace entries reference plugin ids (built-in or npm package names).

package/docs/architecture.md

@@ -5,7 +5,7 @@ OpenBot is an orchestration platform built on a modular, event-driven architectu
 ## Core Components
 
 ### 1. Orchestrator & routing
-The orchestrator is the execution entry point for agent work: it normalizes incoming events, runs the queue processor (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:
+The orchestrator is the execution entry point for agent work: it normalizes incoming events, 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.