openbot 0.3.6 → 0.4.0

package/dist/harness/runtime.js

@@ -0,0 +1,57 @@
+import { melony } from 'melony';
+import { resolvePlugin } from '../registry/plugins.js';
+import { storageService } from '../services/storage.js';
+import { busServicesPlugin } from '../bus/services.js';
+const composeMelonyPlugin = (...plugins) => {
+    return (builder) => {
+        for (const plugin of plugins) {
+            plugin(builder);
+        }
+    };
+};
+/** Build the Melony runtime for a single agent turn. */
+export async function createAgentRuntime(state) {
+    const runtime = melony({
+        initialState: state,
+    });
+    runtime.use(busServicesPlugin({ storage: storageService }));
+    const refs = state.agentDetails?.pluginRefs || [];
+    if (refs.length === 0) {
+        console.warn(`[harness] Agent "${state.agentId}" has no plugins; only bus services will be active.`);
+        return runtime.build();
+    }
+    const resolved = [];
+    for (const ref of refs) {
+        const plugin = await resolvePlugin(ref.id);
+        if (!plugin) {
+            console.warn(`[harness] Plugin "${ref.id}" for agent "${state.agentId}" could not be resolved.`);
+            continue;
+        }
+        resolved.push({ ref, plugin });
+    }
+    const tools = {};
+    for (const { plugin } of resolved) {
+        if (!plugin.toolDefinitions)
+            continue;
+        for (const [name, def] of Object.entries(plugin.toolDefinitions)) {
+            if (tools[name]) {
+                console.warn(`[harness] Tool name collision for "${name}" while loading plugin "${plugin.id}"; keeping first registration.`);
+                continue;
+            }
+            tools[name] = def;
+        }
+    }
+    const pluginPlugins = [];
+    for (const { ref, plugin } of resolved) {
+        const context = {
+            agentId: state.agentId,
+            agentDetails: state.agentDetails,
+            config: ref.config || {},
+            storage: storageService,
+            tools,
+        };
+        pluginPlugins.push(plugin.factory(context));
+    }
+    runtime.use(composeMelonyPlugin(...pluginPlugins));
+    return runtime.build();
+}

package/dist/harness/todo-dispatch.js

@@ -0,0 +1,51 @@
+import { ORCHESTRATOR_AGENT_ID } from './context.js';
+import { hasOpenTodos, readTodosFromState } from './todos.js';
+export const ORCHESTRATOR_REVIEW_PREFIX = '[Orchestrator review]';
+export const ORCHESTRATOR_KICKOFF_PREFIX = '[Orchestrator kickoff]';
+/** After a specialist finishes — decide what's next. */
+export const ORCHESTRATOR_REVIEW_PROMPT = [
+    ORCHESTRATOR_REVIEW_PREFIX,
+    'A specialist agent just finished a step in this thread.',
+    'Review the shared todo list in your context.',
+    'Use `todo_write` to update statuses or capture results.',
+    'If more work remains, call `delegate` with a clear briefing for the right participant.',
+    'If the plan is complete, summarize outcomes for the user.',
+].join(' ');
+/** After the orchestrator wrote a plan but did not delegate — start execution. */
+export const ORCHESTRATOR_KICKOFF_PROMPT = [
+    ORCHESTRATOR_KICKOFF_PREFIX,
+    'The thread has open todos but no specialist is running yet.',
+    'Pick the next actionable item, mark it `in_progress` with `todo_write`,',
+    'and call `delegate` to the assignee (or best participant) with a concrete briefing.',
+    'Use reasonable defaults when the user did not specify a preference — do not stop at planning.',
+].join(' ');
+export function isInternalOrchestratorInvoke(content) {
+    const text = content?.trim() ?? '';
+    return (text.startsWith(ORCHESTRATOR_REVIEW_PREFIX) ||
+        text.startsWith(ORCHESTRATOR_KICKOFF_PREFIX));
+}
+export async function planOrchestratorReview(options) {
+    const { storage, channelId, threadId, endedAgentId, invokeContent, hasQueuedFollowUps, orchestratorKickoffUsed, } = options;
+    if (!threadId || hasQueuedFollowUps)
+        return { review: false };
+    if (isInternalOrchestratorInvoke(invokeContent))
+        return { review: false };
+    const details = await storage.getThreadDetails({ channelId, threadId });
+    const todos = readTodosFromState(details?.state);
+    if (!hasOpenTodos(todos))
+        return { review: false };
+    if (endedAgentId === ORCHESTRATOR_AGENT_ID) {
+        if (orchestratorKickoffUsed)
+            return { review: false };
+        return {
+            review: true,
+            reason: 'plan_not_started',
+            prompt: ORCHESTRATOR_KICKOFF_PROMPT,
+        };
+    }
+    return {
+        review: true,
+        reason: 'specialist_finished',
+        prompt: ORCHESTRATOR_REVIEW_PROMPT,
+    };
+}

package/dist/harness/todos.js

@@ -0,0 +1,5 @@
+export const readTodosFromState = (state) => {
+    const raw = state?.todos;
+    return Array.isArray(raw) ? raw : [];
+};
+export const hasOpenTodos = (todos) => todos.some((t) => t.status === 'pending' || t.status === 'in_progress');

package/dist/harness/turn.js

@@ -0,0 +1,79 @@
+import { ensureEventId } from '../app/utils.js';
+import { storageService } from '../services/storage.js';
+import { createAgentRuntime } from './runtime-factory.js';
+export function makeInternalInvoke(content, threadId) {
+    return ensureEventId({
+        type: 'agent:invoke',
+        data: { role: 'user', content },
+        meta: { threadId, internal: true },
+    });
+}
+/**
+ * Run one agent turn. Yields all runtime events for persistence/streaming;
+ * returns the last non-empty `agent:output` text from the target agent.
+ */
+export async function* runTurn(options) {
+    const { runId, channelId, threadId, agentId, event, lifecycle = true, stream = true, shouldStop, onThreadId, } = options;
+    const target = { runId, agentId, channelId, threadId };
+    let state;
+    try {
+        state = await storageService.getOpenBotState({ ...target, event });
+    }
+    catch (error) {
+        if (error.code === 'AGENT_NOT_FOUND') {
+            return undefined;
+        }
+        throw error;
+    }
+    if (lifecycle && stream) {
+        yield {
+            type: 'agent:run:start',
+            data: { ...target },
+            meta: { agentId, threadId },
+        };
+    }
+    let lastAgentOutput;
+    try {
+        const runtime = await createAgentRuntime(state);
+        for await (const chunk of runtime.run(event, { state, runId })) {
+            const stop = shouldStop?.();
+            if (stop) {
+                yield {
+                    type: 'agent:run:stopped',
+                    data: { ...target, reason: stop.reason },
+                };
+                break;
+            }
+            if (chunk.id === event.id && chunk.type === event.type)
+                continue;
+            if (chunk.type === 'action:create_thread:result' && chunk.data.success) {
+                const newThreadId = chunk.data.threadId;
+                if (newThreadId)
+                    onThreadId?.(newThreadId);
+            }
+            if (chunk.type === 'agent:output') {
+                const content = chunk.data?.content;
+                if (typeof content === 'string' && content.trim()) {
+                    lastAgentOutput = content.trim();
+                }
+            }
+            if (stream) {
+                chunk.meta = { ...chunk.meta, agentId: chunk.meta?.agentId ?? agentId };
+                yield chunk;
+            }
+        }
+    }
+    catch (error) {
+        console.error(`[turn] Agent run failed: ${agentId}`, error);
+    }
+    finally {
+        if (lifecycle && stream) {
+            yield {
+                type: 'agent:run:end',
+                data: { ...target },
+                meta: { agentId, threadId },
+            };
+        }
+    }
+    return lastAgentOutput;
+}

package/dist/plugins/approval/index.js

@@ -1,159 +1,115 @@
-import { storageService } from '../../services/storage.js';
-export const DEFAULT_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,
-        },
-    },
-];
-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 },
-    });
-};
-const buildApprovalPlugin = (rules) => (builder) => {
-    for (const rule of rules) {
-        builder.on(rule.action, async function* (event, context) {
-            const meta = asRecord(event.meta);
-            if (meta.approvalStatus === 'approved')
+import { randomUUID } from 'node:crypto';
+/**
+ * `approval` — gates protected tool calls behind a UI confirmation widget.
+ *
+ * This is a simplified version that intercepts specified actions (default: shell_exec)
+ * and requires user approval before they are allowed to proceed.
+ */
+// In-memory tracking for pending approval IDs with TTL (shared across plugin instances)
+const pendingApprovals = new Map();
+const TTL_MS = 4 * 60 * 60 * 1000; // 4 hours
+export const approvalPlugin = {
+    id: 'approval',
+    name: 'Approval',
+    description: 'Gate protected tool calls behind a UI confirmation widget.',
+    factory: ({ config }) => (builder) => {
+        // Actions that require approval. Defaults to shell_exec.
+        const actionsToApprove = config.actions || ['action:shell_exec'];
+        for (const action of actionsToApprove) {
+            builder.intercept(action, (event, context) => {
+                // If already approved in this flow, let it pass to the actual handler
+                if (event.meta?.approvalStatus === 'approved')
+                    return event;
+                // Otherwise, intercept and ask for approval via a UI widget
+                const displayData = action === 'action:shell_exec'
+                    ? `\`\`\`bash\n${event.data.command}\n\`\`\``
+                    : `\`\`\`json\n${JSON.stringify(event.data, null, 2)}\n\`\`\``;
+                const widgetId = randomUUID();
+                pendingApprovals.set(widgetId, Date.now());
+                context.suspend({
+                    type: 'client:ui:widget',
+                    data: {
+                        widgetId,
+                        kind: 'message',
+                        title: `The agent wants to perform \`${action}\``,
+                        body: displayData,
+                        metadata: {
+                            type: 'approval:request',
+                            originalEvent: event,
+                        },
+                        actions: [
+                            { id: 'approve', label: 'Approve', variant: 'primary' },
+                            { id: 'deny', label: 'Deny', variant: 'danger' },
+                        ],
+                    },
+                    meta: { agentId: context.state.agentId, threadId: context.state.threadId },
+                });
+            });
+        }
+        // Handle the user's response from the UI widget
+        builder.on('client:ui:widget:response', async function* (event, context) {
+            const { widgetId, actionId } = event.data;
+            const metadata = event.data?.metadata;
+            if (metadata?.type !== 'approval:request')
                 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);
+            // Verify the widget is still pending and hasn't expired
+            if (!widgetId || !pendingApprovals.has(widgetId)) {
+                console.warn(`[approval] Received response for unknown or already handled widget: ${widgetId}`);
+                return;
+            }
+            const timestamp = pendingApprovals.get(widgetId);
+            if (Date.now() - timestamp > TTL_MS) {
+                pendingApprovals.delete(widgetId);
+                console.warn(`[approval] Received response for expired widget: ${widgetId}`);
+                return;
+            }
+            // Mark as handled
+            pendingApprovals.delete(widgetId);
+            const originalEvent = metadata.originalEvent;
+            const approved = actionId === 'approve';
+            // Yield a "responded" widget update to the UI
             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' },
-                    ],
+                    kind: 'message',
+                    title: `Action ${approved ? 'Approved' : 'Denied'}`,
+                    body: `The request for \`${originalEvent.type}\` was ${approved ? 'approved' : 'denied'}.`,
+                    state: approved ? 'submitted' : 'cancelled',
+                    display: 'collapsed',
+                    disabled: true,
+                    actions: [], // Clear actions to disable buttons in UI
                 },
-                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 },
+                meta: { agentId: context.state.agentId, threadId: context.state.threadId },
             };
-            context.suspend();
+            if (approved) {
+                // Re-emit the original event with approved status so the actual handler can run
+                yield {
+                    ...originalEvent,
+                    meta: {
+                        ...(originalEvent.meta || {}),
+                        approvalStatus: 'approved',
+                    },
+                };
+            }
+            else {
+                // Emit a failure result event for the denied action
+                // yield {
+                //   type: `${originalEvent.type}:result` as OpenBotEvent['type'],
+                //   data: {
+                //     success: false,
+                //     error: 'Action denied by user.',
+                //     stderr: 'Action denied by user.',
+                //   },
+                //   meta: originalEvent.meta,
+                // } as OpenBotEvent;
+                yield {
+                    type: 'agent:output',
+                    data: { content: `Action \`${originalEvent.type}\` was denied.` },
+                    meta: { agentId: context.state.agentId },
+                };
+            }
         });
-    }
-    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 },
-        };
-    });
-};
-const readRules = (config) => {
-    const raw = config.rules;
-    if (!Array.isArray(raw))
-        return DEFAULT_APPROVAL_RULES;
-    return raw.filter((entry) => !!entry && typeof entry === 'object' && typeof entry.action === 'string');
-};
-export const approvalPlugin = {
-    id: 'approval',
-    name: 'Approval',
-    description: 'Gate protected tool calls (e.g. shell_exec) behind a UI confirmation prompt.',
-    factory: ({ config }) => buildApprovalPlugin(readRules(config)),
+    },
 };
 export default approvalPlugin;

package/dist/plugins/delegation/index.js

@@ -1,40 +1,127 @@
-import z from 'zod';
-const handoffToolDefinitions = {
-    handoff: {
-        description: 'Transfer control to another agent. The target agent continues the task in this thread.',
+import { z } from 'zod';
+import { generateId } from 'melony';
+import { runAgent } from '../../harness/index.js';
+/**
+ * `delegation` — allows agents to delegate tasks to other agents.
+ *
+ * Only the 'system' agent is allowed to delegate by default.
+ * It uses runAgent to execute the delegated agent in its own isolated runtime,
+ * bridging events back to the caller's stream.
+ */
+const delegationToolDefinitions = {
+    delegate_task: {
+        description: 'Delegate a specific task or question to another specialized agent.',
         inputSchema: z.object({
-            agentId: z.string().describe('The ID of the target agent.'),
-            content: z.string().describe('The message or task to hand off.'),
+            agentId: z.string().describe('The ID of the agent to delegate to (e.g., "researcher", "coder").'),
+            prompt: z.string().describe('The instructions or question for the delegated agent.'),
         }),
     },
 };
-const handoffPluginRuntime = () => (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 },
-            };
-        }
-    });
-};
 export const delegationPlugin = {
     id: 'delegation',
-    name: 'Handoff',
-    description: 'Hand off tasks to other agents on the bus.',
-    toolDefinitions: handoffToolDefinitions,
-    factory: () => handoffPluginRuntime(),
+    name: 'Delegation',
+    description: 'Allows agents to call upon other agents to solve sub-tasks.',
+    toolDefinitions: delegationToolDefinitions,
+    factory: () => (builder) => {
+        // Handle the tool execution
+        builder.on('action:delegate_task', async function* (event, context) {
+            const delegateEvent = event;
+            // POLICY: Only the 'system' agent can delegate
+            if (context.state.agentId !== 'system') {
+                yield {
+                    type: 'action:delegate_task:result',
+                    data: {
+                        success: false,
+                        error: 'Only the system agent can delegate.'
+                    },
+                    meta: delegateEvent.meta,
+                };
+                return;
+            }
+            const { agentId, prompt } = delegateEvent.data;
+            const toolCallId = delegateEvent.meta?.toolCallId;
+            if (!toolCallId)
+                return;
+            const runId = `dg_${generateId()}`;
+            let lastAgentOutput = '';
+            // Queue to bridge the async onEvent callback to this generator
+            const eventQueue = [];
+            let resolveNext = null;
+            let isFinished = false;
+            // Start the delegated agent in its own runtime.
+            // We don't await this immediately so we can yield events as they arrive.
+            const runPromise = runAgent({
+                runId,
+                agentId,
+                event: {
+                    type: 'agent:invoke',
+                    data: {
+                        role: 'user',
+                        content: prompt,
+                        agentId: agentId,
+                    },
+                    meta: {
+                        threadId: context.state.threadId,
+                        parentAgentId: context.state.agentId,
+                        parentToolCallId: toolCallId,
+                    },
+                },
+                channelId: context.state.channelId,
+                threadId: context.state.threadId,
+                onEvent: async (outEvent) => {
+                    // Enrich events with parent metadata so the UI can track the hierarchy
+                    const enrichedEvent = {
+                        ...outEvent,
+                        meta: {
+                            ...outEvent.meta,
+                            parentAgentId: context.state.agentId,
+                            parentToolCallId: toolCallId,
+                        }
+                    };
+                    eventQueue.push(enrichedEvent);
+                    if (outEvent.type === 'agent:output') {
+                        lastAgentOutput = outEvent.data.content;
+                    }
+                    // Wake up the generator loop if it's waiting
+                    if (resolveNext) {
+                        resolveNext();
+                        resolveNext = null;
+                    }
+                }
+            }).catch(error => {
+                console.error(`[delegation] Error in delegated run ${runId}:`, error);
+            }).finally(() => {
+                isFinished = true;
+                if (resolveNext) {
+                    resolveNext();
+                    resolveNext = null;
+                }
+            });
+            // Yield events from the delegated agent as they arrive
+            while (!isFinished || eventQueue.length > 0) {
+                if (eventQueue.length === 0) {
+                    await new Promise(r => { resolveNext = r; });
+                }
+                while (eventQueue.length > 0) {
+                    yield eventQueue.shift();
+                }
+            }
+            // Ensure the run is fully complete (though isFinished already implies this)
+            await runPromise;
+            // Yield the result back to our own LLM runtime.
+            yield {
+                type: 'action:delegate_task:result',
+                data: {
+                    success: true,
+                    output: lastAgentOutput,
+                },
+                meta: {
+                    ...delegateEvent.meta,
+                    agentId: context.state.agentId,
+                    toolCallId: toolCallId,
+                },
+            };
+        });
+    },
 };
 export default delegationPlugin;