openbot 0.3.5 → 0.4.0

package/dist/harness/run-harness.js

@@ -0,0 +1,154 @@
+import { ensureEventId } from '../app/utils.js';
+import { storageService } from '../services/storage.js';
+import { createAgentRuntime } from './runtime-factory.js';
+const stopRequests = [];
+const STOP_TTL_MS = 30 * 60 * 1000;
+const pruneStops = () => {
+    const cutoff = Date.now() - STOP_TTL_MS;
+    for (let i = stopRequests.length - 1; i >= 0; i -= 1) {
+        if (stopRequests[i].requestedAt < cutoff)
+            stopRequests.splice(i, 1);
+    }
+};
+const findStop = (target) => {
+    pruneStops();
+    return stopRequests.find((r) => r.runId === target.runId &&
+        (!r.agentId || r.agentId === target.agentId) &&
+        (!r.channelId || r.channelId === target.channelId) &&
+        (!r.threadId || r.threadId === target.threadId));
+};
+const target = (ctx, agentId) => ({ ...ctx, agentId });
+const loadState = (t, event) => storageService.getOpenBotState({ ...t, event });
+export async function runHarness(options) {
+    const { event } = options;
+    ensureEventId(event);
+    if (event.type === 'action:agent_run_stop') {
+        await handleStop(event, options);
+        return;
+    }
+    const ctx = {
+        runId: options.runId,
+        channelId: options.channelId,
+        threadId: options.threadId,
+        onEvent: options.onEvent,
+    };
+    const agentId = options.agentId || 'system';
+    if (event.type === 'user:input' || event.type === 'agent:invoke') {
+        await runStep(ctx, agentId, await prepareInvoke(event, ctx));
+        return;
+    }
+    await runPassThrough(ctx, agentId, event);
+}
+async function runStep(ctx, agentId, event) {
+    const t = target(ctx, agentId);
+    const early = findStop(t);
+    if (early) {
+        const state = await loadState(t, event);
+        await ctx.onEvent({ type: 'agent:run:stopped', data: { ...t, reason: early.reason } }, state);
+        return;
+    }
+    let state;
+    try {
+        state = await loadState(t, event);
+    }
+    catch (error) {
+        if (error.code !== 'AGENT_NOT_FOUND')
+            throw error;
+        const fallback = await loadState(target(ctx, 'system'), event);
+        await ctx.onEvent({
+            type: 'agent:output',
+            data: {
+                content: `⚠️ Agent **${agentId}** does not exist. Please check the agent ID and try again.`,
+            },
+            meta: { agentId: 'system', threadId: ctx.threadId },
+        }, fallback);
+        return;
+    }
+    await ctx.onEvent({ type: 'agent:run:start', data: { ...t } }, state);
+    try {
+        await streamEvents(ctx, t, event, state, true);
+    }
+    catch (error) {
+        console.error(`[run-harness] Agent run failed: ${agentId}`, error);
+    }
+    finally {
+        const after = await loadState(t, event);
+        await ctx.onEvent({ type: 'agent:run:end', data: { ...t } }, after);
+    }
+}
+async function runPassThrough(ctx, agentId, event) {
+    const t = target(ctx, agentId);
+    let state;
+    try {
+        state = await loadState(t, event);
+    }
+    catch (error) {
+        if (error.code === 'AGENT_NOT_FOUND')
+            return;
+        throw error;
+    }
+    try {
+        await streamEvents(ctx, t, event, state, false);
+    }
+    catch (error) {
+        console.error(`[run-harness] Event failed: ${event.type} (${agentId})`, error);
+    }
+}
+async function streamEvents(ctx, t, event, state, step) {
+    const runtime = await createAgentRuntime(state);
+    for await (const chunk of runtime.run(event, { state, runId: ctx.runId })) {
+        if (step) {
+            const stop = findStop(t);
+            if (stop) {
+                await ctx.onEvent({ type: 'agent:run:stopped', data: { ...t, reason: stop.reason } }, state);
+                break;
+            }
+        }
+        if (chunk.id === event.id && chunk.type === event.type)
+            continue;
+        if (step && chunk.type === 'action:create_thread:result' && chunk.data.success) {
+            ctx.threadId = chunk.data.threadId || ctx.threadId;
+        }
+        chunk.meta = { ...chunk.meta, agentId: t.agentId };
+        await ctx.onEvent(chunk, state);
+    }
+}
+async function prepareInvoke(event, ctx) {
+    const rawContent = event.data?.content || '';
+    const userFacing = {
+        type: 'agent:invoke',
+        id: event.id,
+        data: { content: rawContent, role: 'user' },
+        meta: {
+            agentId: 'system',
+            userId: event.meta?.userId,
+            userName: event.meta?.userName,
+            userAvatarUrl: event.meta?.userAvatarUrl,
+        },
+    };
+    const initialState = await loadState(target(ctx, 'system'), userFacing);
+    await ctx.onEvent(userFacing, initialState);
+    return {
+        ...event,
+        type: 'agent:invoke',
+        data: { ...(event.data || {}), content: rawContent, role: 'user' },
+        meta: { ...(event.meta || {}), threadId: ctx.threadId || event.id },
+    };
+}
+async function handleStop(stopEvent, options) {
+    const { runId, channelId, threadId, onEvent } = options;
+    stopRequests.push({
+        runId: stopEvent.data.runId,
+        agentId: stopEvent.data.agentId,
+        channelId: stopEvent.data.channelId || channelId,
+        threadId: stopEvent.data.threadId || threadId,
+        reason: stopEvent.data.reason,
+        requestedAt: Date.now(),
+    });
+    const state = await loadState({ runId, channelId, threadId, onEvent, agentId: options.agentId || 'system' }, stopEvent);
+    await onEvent({
+        type: 'action:agent_run_stop:result',
+        data: { success: true, message: `Stop requested for run ${stopEvent.data.runId}.` },
+        meta: stopEvent.meta,
+    }, state);
+}

package/dist/harness/run.js

@@ -0,0 +1,98 @@
+import { ensureEventId } from '../app/utils.js';
+import { storageService } from '../services/storage.js';
+import { createAgentRuntime } from './runtime.js';
+const TODO_RESULT_MAX_CHARS = 12000;
+const readTodos = (state) => {
+    const raw = state.threadDetails?.state?.todos;
+    return Array.isArray(raw) ? raw : [];
+};
+function truncateTodoResult(text, maxChars = TODO_RESULT_MAX_CHARS) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return undefined;
+    if (trimmed.length <= maxChars)
+        return trimmed;
+    return `${trimmed.slice(0, maxChars)}\n…[truncated]`;
+}
+function resolveTodoIdForWorker(todos, workerId, delegationTodoId) {
+    if (delegationTodoId && todos.some((t) => t.id === delegationTodoId)) {
+        return delegationTodoId;
+    }
+    const inProgress = todos.find((t) => t.status === 'in_progress' && t.assignee === workerId);
+    if (inProgress)
+        return inProgress.id;
+    const assigned = todos.find((t) => (t.status === 'pending' || t.status === 'in_progress') && t.assignee === workerId);
+    return assigned?.id;
+}
+async function recordWorkerTodoResult(state, workerId, output, delegationTodoId) {
+    if (!state.threadId)
+        return;
+    const result = truncateTodoResult(output ?? '');
+    if (!result)
+        return;
+    const todos = readTodos(state);
+    if (todos.length === 0)
+        return;
+    const todoId = resolveTodoIdForWorker(todos, workerId, delegationTodoId);
+    if (!todoId)
+        return;
+    const prior = todos.find((t) => t.id === todoId);
+    if (prior?.result === result)
+        return;
+    const now = Date.now();
+    const next = todos.map((t) => (t.id === todoId ? { ...t, result, updatedAt: now } : t));
+    await storageService.patchThreadState({
+        channelId: state.channelId,
+        threadId: state.threadId,
+        state: { todos: next },
+    });
+}
+export function makeInternalInvoke(content, threadId) {
+    return ensureEventId({
+        type: 'agent:invoke',
+        data: { role: 'user', content },
+        meta: { threadId, internal: true },
+    });
+}
+/**
+ * Run one agent turn. Yields runtime events for persistence/streaming;
+ * returns the last non-empty `agent:output` text when used as a worker.
+ */
+export async function* runTurn(options) {
+    const { runId, channelId, threadId, agentId, event, delegationTodoId } = 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;
+    }
+    yield { type: 'agent:run:start', data: { ...target } };
+    let lastAgentOutput;
+    try {
+        const runtime = await createAgentRuntime(state);
+        for await (const chunk of runtime.run(event, { state, runId })) {
+            if (chunk.id === event.id && chunk.type === event.type)
+                continue;
+            if (chunk.type === 'agent:output' &&
+                chunk.meta?.agentId === agentId) {
+                const content = chunk.data?.content;
+                if (typeof content === 'string' && content.trim()) {
+                    lastAgentOutput = content.trim();
+                }
+            }
+            chunk.meta = { ...chunk.meta, agentId };
+            yield chunk;
+        }
+    }
+    finally {
+        const stateAfterRun = await storageService.getOpenBotState({ ...target, event });
+        yield { type: 'agent:run:end', data: { ...target } };
+        await recordWorkerTodoResult(stateAfterRun, agentId, lastAgentOutput, delegationTodoId);
+    }
+    return lastAgentOutput;
+}

package/dist/harness/runtime-factory.js

@@ -2,39 +2,6 @@ import { melony } from 'melony';
 import { resolvePlugin } from '../registry/plugins.js';
 import { storageService } from '../services/storage.js';
 import { busServicesPlugin } from '../bus/services.js';
-/**
- * Enhances the agent's instructions with a list of other available agents the
- * orchestrator can hand off to. Agents that include the `delegation` plugin
- * will surface peers; agents without it can ignore this.
- */
-export async function enhanceInstructions(state) {
-    const { agentId, agentDetails } = state;
-    if (!agentDetails)
-        return;
-    try {
-        const agents = await storageService.getAgents();
-        const otherAgents = agents.filter((a) => a.id !== agentId);
-        if (otherAgents.length === 0)
-            return;
-        const agentsList = otherAgents
-            .map((a) => `- **${a.id}**${a.description ? `: ${a.description}` : ''}`)
-            .join('\n');
-        const header = '### Available Agents:';
-        if (!agentDetails.instructions.includes(header)) {
-            const hasHandoff = (agentDetails.pluginRefs || []).some((r) => r.id === 'delegation');
-            const hasTodo = (agentDetails.pluginRefs || []).some((r) => r.id === 'todo');
-            const usage = hasTodo
-                ? 'Use these ids as `assignee` when calling `todo_write` to plan multi-agent work.'
-                : hasHandoff
-                    ? 'Use `handoff` to transfer control to another agent in this thread.'
-                    : '';
-            agentDetails.instructions += `\n\n${header}\n${agentsList}${usage ? `\n\n${usage}` : ''}`;
-        }
-    }
-    catch (error) {
-        console.warn('[agent] Failed to enhance instructions', error);
-    }
-}
 const composeMelonyPlugin = (...plugins) => {
     return (builder) => {
         for (const plugin of plugins) {
@@ -57,7 +24,6 @@ const composeMelonyPlugin = (...plugins) => {
  * Tool name collisions across plugins log a warning; the first plugin wins.
  */
 export async function createAgentRuntime(state) {
-    await enhanceInstructions(state);
     const runtime = melony({
         initialState: state,
     });

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;
+}