openbot 0.2.14 → 0.3.1

package/dist/agents/openbot/index.js

@@ -0,0 +1,76 @@
+import { readFileSync } from 'node:fs';
+import { openBotRuntime } from './runtime.js';
+import { shellPlugin, shellToolDefinitions } from './tools/shell.js';
+import { mcpPlugin, mcpToolDefinitions } from './tools/mcp.js';
+import { uiPlugin, uiToolDefinitions } from './tools/ui.js';
+import { delegationPlugin, delegationToolDefinitions } from './tools/delegation.js';
+import { storageToolDefinitions } from './tools/storage.js';
+import { approvalPlugin } from './middleware/approval.js';
+import { DEFAULT_OPENBOT_APPROVAL_RULES, OPENBOT_SYSTEM_PROMPT } from './system-prompt.js';
+const OPENBOT_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;
+    }
+})();
+const composeMelonyPlugin = (...plugins) => {
+    return (builder) => {
+        for (const plugin of plugins) {
+            plugin(builder);
+        }
+    };
+};
+/**
+ * OpenBot — the first-party orchestrator agent package.
+ *
+ * Treats the bus as a peer environment: registers a runtime that owns
+ * `agent:invoke`, exposes a curated tool set (delegation, storage, MCP, shell,
+ * UI widgets), and wires approval middleware for protected actions.
+ *
+ * Other agents (Codex, Claude Code, Gemini, custom Coder/Researcher) are
+ * separate AgentPackages with their own runtime + tool composition.
+ */
+export const openBotAgentPackage = {
+    id: 'openbot',
+    name: 'OpenBot',
+    description: 'First-party orchestration agent for OpenBot. Coordinates other agents via handoff and delegation.',
+    image: OPENBOT_ICON_DATA_URL,
+    defaultInstructions: OPENBOT_SYSTEM_PROMPT,
+    configSchema: {
+        type: 'object',
+        properties: {
+            model: {
+                type: 'string',
+                description: 'Provider model string, e.g. openai/gpt-4o-mini, anthropic/claude-3-5-sonnet-20240620',
+                default: 'openai/gpt-4o-mini',
+            },
+        },
+    },
+    factory: ({ agentDetails, config, storage }) => {
+        const model = typeof config.model === 'string' && config.model
+            ? config.model
+            : 'openai/gpt-4o-mini';
+        const toolDefinitions = {
+            ...delegationToolDefinitions,
+            ...storageToolDefinitions,
+            ...mcpToolDefinitions,
+            ...shellToolDefinitions,
+            // Re-enable when the dashboard renders widgets:
+            // ...uiToolDefinitions,
+        };
+        const systemPrompt = agentDetails.instructions || OPENBOT_SYSTEM_PROMPT;
+        return composeMelonyPlugin(openBotRuntime({
+            model,
+            system: systemPrompt,
+            storage,
+            toolDefinitions,
+        }), approvalPlugin({ rules: DEFAULT_OPENBOT_APPROVAL_RULES }), delegationPlugin(), shellPlugin(), mcpPlugin(), uiPlugin());
+    },
+};
+// Suppress unused warning while UI widget tools are not wired into the LLM tool list.
+void uiToolDefinitions;

package/dist/agents/openbot/middleware/approval.js

@@ -0,0 +1,132 @@
+import { storageService } from '../../../services/storage.js';
+const asRecord = (value) => value && typeof value === 'object' && !Array.isArray(value)
+    ? value
+    : {};
+const getApprovalsFromState = (state) => {
+    const source = state.threadDetails?.state ?? state.channelDetails?.state;
+    const stateRecord = asRecord(source);
+    return asRecord(stateRecord.approvals);
+};
+const persistApprovals = async (state, approvals) => {
+    if (state.threadId) {
+        await storageService.patchThreadState({
+            channelId: state.channelId,
+            threadId: state.threadId,
+            state: { approvals },
+        });
+        return;
+    }
+    await storageService.patchChannelState({
+        channelId: state.channelId,
+        state: { approvals },
+    });
+};
+export const approvalPlugin = (options = {}) => (builder) => {
+    const rules = options.rules || [];
+    for (const rule of rules) {
+        builder.on(rule.action, async function* (event, context) {
+            const meta = asRecord(event.meta);
+            if (meta.approvalStatus === 'approved')
+                return;
+            const eventData = asRecord(event.data);
+            const eventMeta = meta;
+            const approvalId = `approval_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+            const widgetId = `widget_${approvalId}`;
+            const executeEvent = rule.executeEvent || rule.action;
+            const denyEvent = rule.denyEvent || `${rule.action}:result`;
+            const denyData = rule.denyData || {};
+            const hiddenKeys = new Set(rule.hiddenKeys || []);
+            const detailKeys = rule.detailKeys || Object.keys(eventData);
+            const details = detailKeys
+                .filter((key) => !hiddenKeys.has(key))
+                .map((key) => `- ${key}: ${String(eventData[key] ?? '')}`)
+                .join('\n');
+            const pendingApprovals = getApprovalsFromState(context.state);
+            pendingApprovals[approvalId] = {
+                id: approvalId,
+                action: rule.action,
+                executeEvent,
+                denyEvent,
+                denyData,
+                payload: eventData,
+                meta: eventMeta,
+                message: rule.message || `Approval required for ${rule.action}.`,
+                createdAt: new Date().toISOString(),
+                status: 'pending',
+            };
+            await persistApprovals(context.state, pendingApprovals);
+            yield {
+                type: 'client:ui:widget',
+                data: {
+                    kind: 'choice',
+                    widgetId,
+                    title: 'Approval Required',
+                    body: `${rule.message || 'A protected action requires approval.'}${details ? `\n\n${details}` : ''}`,
+                    metadata: { type: 'approval:request', approvalId, action: rule.action },
+                    actions: [
+                        { id: 'approve', label: 'Approve', variant: 'primary' },
+                        { id: 'deny', label: 'Deny', variant: 'danger' },
+                    ],
+                },
+                meta: { ...(event.meta || {}), agentId: context.state.agentId },
+            };
+            yield {
+                type: 'agent:output',
+                data: { content: `Waiting for approval before running \`${rule.action}\`.` },
+                meta: { ...(event.meta || {}), agentId: context.state.agentId },
+            };
+            context.suspend();
+        });
+    }
+    builder.on('client:ui:widget:response', async function* (event, context) {
+        const metadata = asRecord(event.data?.metadata);
+        if (metadata.type !== 'approval:request')
+            return;
+        const approvalId = String(metadata.approvalId || '');
+        if (!approvalId)
+            return;
+        const approvals = getApprovalsFromState(context.state);
+        const approval = approvals[approvalId];
+        if (!approval || approval.status !== 'pending') {
+            yield {
+                type: 'agent:output',
+                data: { content: 'Approval request not found or already resolved.' },
+                meta: { ...(event.meta || {}), agentId: context.state.agentId },
+            };
+            return;
+        }
+        const approved = event.data.actionId === 'approve';
+        approvals[approvalId] = {
+            ...approval,
+            status: approved ? 'approved' : 'denied',
+        };
+        await persistApprovals(context.state, approvals);
+        if (approved) {
+            yield {
+                type: approval.executeEvent,
+                data: approval.payload,
+                meta: {
+                    ...(approval.meta || {}),
+                    approvalId,
+                    approvalStatus: 'approved',
+                },
+            };
+            return;
+        }
+        yield {
+            type: approval.denyEvent,
+            data: {
+                success: false,
+                approved: false,
+                error: 'Action denied by user approval.',
+                ...approval.denyData,
+            },
+            meta: { ...(approval.meta || {}), approvalId },
+        };
+        yield {
+            type: 'agent:output',
+            data: { content: 'Action denied by user approval.' },
+            meta: { ...(event.meta || {}), agentId: context.state.agentId },
+        };
+    });
+};

package/dist/agents/openbot/runtime.js

@@ -0,0 +1,289 @@
+import { generateText } from 'ai';
+import { openai } from '@ai-sdk/openai';
+import { anthropic } from '@ai-sdk/anthropic';
+import { createDefaultContextEngine } from '../../harness/context.js';
+function resolveModel(modelString) {
+    const [provider, ...rest] = modelString.split('/');
+    const modelId = rest.join('/');
+    if (!modelId) {
+        throw new Error(`Invalid model string: "${modelString}". Expected "provider/model-id".`);
+    }
+    switch (provider) {
+        case 'openai':
+            return openai(modelId);
+        case 'anthropic':
+            return anthropic(modelId);
+        default:
+            throw new Error(`Unsupported AI provider: "${provider}"`);
+    }
+}
+const asRecord = (value) => value && typeof value === 'object' && !Array.isArray(value)
+    ? value
+    : {};
+const readPersistedShortTermMessages = (state) => {
+    const source = state.threadDetails?.state ?? state.channelDetails?.state;
+    const record = asRecord(source);
+    const raw = record.shortTermMessages;
+    return Array.isArray(raw) ? raw : [];
+};
+const persistShortTermMessages = async (state, storage) => {
+    if (!storage)
+        return;
+    const shortTermMessages = state.shortTermMessages ?? [];
+    if (state.threadId) {
+        await storage.patchThreadState({
+            channelId: state.channelId,
+            threadId: state.threadId,
+            state: { shortTermMessages },
+        });
+        return;
+    }
+    await storage.patchChannelState({
+        channelId: state.channelId,
+        state: { shortTermMessages },
+    });
+};
+async function buildSystemPrompt(state, system, context, storage, contextEngine) {
+    const sections = [];
+    if (system && typeof system === 'string')
+        sections.push(system);
+    if (system && typeof system === 'function' && context)
+        sections.push(await system(context));
+    if (contextEngine)
+        sections.push(await contextEngine.buildContext(state, storage));
+    return sections.join('\n\n');
+}
+/**
+ * The ai-sdk based runtime that drives OpenBot's first-party agent.
+ *
+ * It owns `agent:invoke`, runs the LLM, emits tool-call events and stitches
+ * tool results back into the conversation. The runtime is intentionally
+ * agent-package-internal: it is not a generic OpenBot abstraction.
+ */
+export const openBotRuntime = (options) => (builder) => {
+    const { model: modelString = 'openai/gpt-4o-mini', system, storage, contextEngine = createDefaultContextEngine(), toolDefinitions = {}, } = options;
+    const model = resolveModel(modelString);
+    const ensureShortTermMessages = (state) => {
+        if (!state.shortTermMessages || state.shortTermMessages.length === 0) {
+            state.shortTermMessages = readPersistedShortTermMessages(state);
+        }
+    };
+    const mapToCoreMessages = (messages) => {
+        return messages.map((m) => {
+            if (m.role === 'assistant' && m.toolCalls) {
+                return {
+                    role: 'assistant',
+                    content: [
+                        { type: 'text', text: m.content || '' },
+                        ...m.toolCalls.map((tc) => ({
+                            type: 'tool-call',
+                            toolCallId: tc.id,
+                            toolName: tc.function.name,
+                            input: JSON.parse(tc.function.arguments),
+                        })),
+                    ],
+                };
+            }
+            if (m.role === 'assistant') {
+                return { role: 'assistant', content: m.content || '' };
+            }
+            if (m.role === 'tool') {
+                return {
+                    role: 'tool',
+                    content: [
+                        {
+                            type: 'tool-result',
+                            toolCallId: m.toolCallId,
+                            toolName: m.toolName,
+                            output: { type: 'text', value: JSON.stringify(m.content) },
+                        },
+                    ],
+                };
+            }
+            return m;
+        });
+    };
+    const runLLM = async function* (context, threadId) {
+        ensureShortTermMessages(context.state);
+        const systemPrompt = await buildSystemPrompt(context.state, system, context, storage, contextEngine);
+        const coreMessages = mapToCoreMessages(context.state.shortTermMessages || []);
+        try {
+            const result = await generateText({
+                model,
+                system: systemPrompt,
+                messages: coreMessages,
+                tools: toolDefinitions,
+            });
+            const toolCalls = result.toolCalls ?? [];
+            if (toolCalls.length > 0) {
+                context.state.shortTermMessages = [
+                    ...(context.state.shortTermMessages ?? []),
+                    {
+                        role: 'assistant',
+                        content: result.text || '',
+                        toolCalls: toolCalls.map((tc) => ({
+                            id: tc.toolCallId,
+                            type: 'function',
+                            function: {
+                                name: tc.toolName,
+                                arguments: JSON.stringify(tc.input),
+                            },
+                        })),
+                    },
+                ];
+                await persistShortTermMessages(context.state, storage);
+                for (const toolCall of toolCalls) {
+                    yield {
+                        type: `action:${toolCall.toolName}`,
+                        data: toolCall.input,
+                        meta: {
+                            toolCallId: toolCall.toolCallId,
+                            agentId: context.state.agentId,
+                            threadId,
+                        },
+                    };
+                }
+            }
+            if (result.text) {
+                if (toolCalls.length === 0) {
+                    context.state.shortTermMessages = [
+                        ...(context.state.shortTermMessages ?? []),
+                        { role: 'assistant', content: result.text },
+                    ];
+                    await persistShortTermMessages(context.state, storage);
+                }
+                yield {
+                    type: 'agent:output',
+                    data: { content: result.text },
+                    meta: { agentId: context.state.agentId, threadId },
+                };
+            }
+        }
+        catch (error) {
+            const errorMessage = error?.message || String(error);
+            const isApiKeyError = errorMessage.includes('API key') ||
+                errorMessage.includes('401') ||
+                errorMessage.includes('Unauthorized') ||
+                errorMessage.includes('authentication');
+            if (isApiKeyError) {
+                const provider = modelString.split('/')[0];
+                const envVar = provider === 'openai' ? 'OPENAI_API_KEY' : 'ANTHROPIC_API_KEY';
+                yield {
+                    type: 'client:ui:widget',
+                    data: {
+                        kind: 'form',
+                        widgetId: `api_key_request_${Date.now()}`,
+                        title: `${provider.toUpperCase()} API Key Required`,
+                        description: `The ${provider} API returned an authentication error. Please provide a valid API key to continue. The key never leaves your local runtime.`,
+                        fields: [
+                            {
+                                id: 'apiKey',
+                                label: 'API Key',
+                                type: 'text',
+                                placeholder: `sk-...`,
+                                required: true,
+                            },
+                        ],
+                        submitLabel: 'Save API Key',
+                        metadata: {
+                            type: 'api_key_request',
+                            provider,
+                            envVar,
+                        },
+                    },
+                    meta: { agentId: context.state.agentId, threadId },
+                };
+                return;
+            }
+            throw error;
+        }
+    };
+    builder.on('agent:invoke', async function* (event, context) {
+        const routedTo = event.data?.agentId;
+        if (typeof routedTo === 'string' && routedTo && routedTo !== context.state.agentId) {
+            return;
+        }
+        const threadId = event.meta?.threadId || context.state.threadId;
+        ensureShortTermMessages(context.state);
+        context.state.shortTermMessages = [
+            ...(context.state.shortTermMessages ?? []),
+            {
+                role: event.data?.role || 'user',
+                content: event?.data?.content || '',
+            },
+        ];
+        await persistShortTermMessages(context.state, storage);
+        yield* runLLM(context, threadId);
+    });
+    builder.on('*', async function* (event, context) {
+        if (!event.type.endsWith(':result'))
+            return;
+        if (event.meta?.agentId !== context.state.agentId)
+            return;
+        const toolCallId = event.meta?.toolCallId;
+        if (!toolCallId)
+            return;
+        ensureShortTermMessages(context.state);
+        const toolName = event.type.replace(/^action:/, '').replace(/:result$/, '');
+        const resultData = event.data;
+        const content = typeof resultData === 'string' ? resultData : JSON.stringify(resultData);
+        context.state.shortTermMessages = [
+            ...(context.state.shortTermMessages ?? []),
+            { role: 'tool', content, toolCallId, toolName },
+        ];
+        await persistShortTermMessages(context.state, storage);
+        const lastAssistant = [...(context.state.shortTermMessages ?? [])]
+            .reverse()
+            .find((m) => m.role === 'assistant' && m.toolCalls && m.toolCalls.length > 0);
+        if (lastAssistant && lastAssistant.toolCalls) {
+            const allFulfilled = lastAssistant.toolCalls.every((tc) => context.state.shortTermMessages?.some((m) => m.role === 'tool' && m.toolCallId === tc.id));
+            if (allFulfilled) {
+                // handoff terminates the current agent path; the orchestrator continues with the target agent.
+                if (toolName === 'handoff')
+                    return;
+                const threadId = event.meta?.threadId || context.state.threadId;
+                yield* runLLM(context, threadId);
+            }
+        }
+    });
+    builder.on('client:ui:widget:response', async function* (event, context) {
+        const { metadata, values } = event.data;
+        if (metadata?.type === 'api_key_request' && values?.apiKey) {
+            const key = metadata.envVar;
+            const value = values.apiKey;
+            if (storage) {
+                try {
+                    await storage.createVariable({ key, value, secret: true });
+                    yield {
+                        type: 'agent:output',
+                        data: {
+                            content: `Successfully saved ${metadata.provider} API key to workspace variables.`,
+                        },
+                        meta: { agentId: context.state.agentId },
+                    };
+                    yield {
+                        type: 'client:ui:widget',
+                        data: {
+                            widgetId: event.data.widgetId,
+                            kind: 'message',
+                            title: 'API Key Saved',
+                            body: `Successfully saved ${metadata.provider} API key. You can now continue your conversation.`,
+                            state: 'submitted',
+                            actions: [{ id: 'ok', label: 'Got it', variant: 'primary' }],
+                        },
+                        meta: { agentId: context.state.agentId },
+                    };
+                }
+                catch (error) {
+                    yield {
+                        type: 'agent:output',
+                        data: {
+                            content: `Failed to save API key: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                        },
+                        meta: { agentId: context.state.agentId },
+                    };
+                }
+            }
+        }
+    });
+};

package/dist/agents/openbot/system-prompt.js

@@ -0,0 +1,32 @@
+export const OPENBOT_SYSTEM_PROMPT = '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**: Use `handoff` when you want another agent to take over. ' +
+    'Use `delegate` when you want another agent to return results so you can continue.\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' +
+    '- **Handoff/Delegation**: Use handoff for ownership transfer and delegation for ' +
+    'subtask-return patterns. Reference the relevant Task ID from thread state and update ' +
+    'task status with `patch_thread_details` as progress is made.\n\n' +
+    'If you need to know what agents or packages are installed, I can help you find that information.';
+export const DEFAULT_OPENBOT_APPROVAL_RULES = [
+    {
+        action: 'action:shell_exec',
+        denyEvent: 'action:shell_exec:result',
+        message: 'The agent wants to run a terminal command.',
+        detailKeys: ['command', 'cwd', 'shell', 'timeoutMs'],
+        hiddenKeys: ['env'],
+        denyData: {
+            exitCode: null,
+            stdout: '',
+            stderr: 'Command execution was denied by the user.',
+            timedOut: false,
+        },
+    },
+];

package/dist/agents/openbot/tools/delegation.js

@@ -0,0 +1,78 @@
+import z from 'zod';
+/**
+ * Tool definitions for the OpenBot orchestrator's delegation/handoff capability.
+ *
+ * The actual cross-agent routing lives in the bus's queue processor: when this
+ * plugin yields `handoff:request` / `delegation:request` events, the orchestrator
+ * intercepts them and dispatches an `agent:invoke` to the target agent.
+ */
+export const delegationToolDefinitions = {
+    handoff: {
+        description: 'Transfer control to another agent. The target agent continues the task and you do not wait for a tool result.',
+        inputSchema: z.object({
+            agentId: z.string().describe('The ID of the target agent.'),
+            content: z.string().describe('The message or task to hand off.'),
+        }),
+    },
+    delegate: {
+        description: 'Delegate a subtask to another agent and wait for its result so you can continue.',
+        inputSchema: z.object({
+            agentId: z.string().describe('The ID of the target agent.'),
+            content: z.string().describe('The subtask you want the target agent to execute.'),
+        }),
+    },
+};
+export const delegationPlugin = () => (builder) => {
+    builder.on('action:handoff', async function* (event, context) {
+        const { agentId, content } = event.data;
+        yield {
+            type: 'agent:output',
+            data: { content: `Handing off to **${agentId}**: ${content}` },
+            meta: { ...(event.meta || {}), agentId: context.state.agentId },
+        };
+        yield {
+            type: 'handoff:request',
+            data: { agentId, content },
+            meta: { ...(event.meta || {}), agentId: context.state.agentId },
+        };
+        if (event.meta?.toolCallId) {
+            yield {
+                type: 'action:handoff:result',
+                data: { success: true, agentId, accepted: true },
+                meta: { ...(event.meta || {}), agentId: context.state.agentId },
+            };
+        }
+    });
+    builder.on('action:delegate', async function* (event, context) {
+        const { agentId, content } = event.data;
+        const widgetId = event.meta?.toolCallId
+            ? `delegate_${event.meta.toolCallId}`
+            : `delegate_${Date.now()}`;
+        yield {
+            type: 'client:ui:widget',
+            data: {
+                kind: 'message',
+                widgetId,
+                title: `Delegation started: ${agentId}`,
+                body: `Running delegated task in background.\n\n${content}`,
+                state: 'open',
+                metadata: {
+                    type: 'delegation:status',
+                    phase: 'started',
+                    delegatedAgentId: agentId,
+                },
+            },
+            meta: { ...(event.meta || {}), agentId: context.state.agentId },
+        };
+        yield {
+            type: 'delegation:request',
+            data: { agentId, content },
+            meta: {
+                ...(event.meta || {}),
+                parentAgentId: context.state.agentId,
+                delegationWidgetId: widgetId,
+                agentId: context.state.agentId,
+            },
+        };
+    });
+};