openbot 0.3.3 → 0.3.5

package/README.md

@@ -120,7 +120,7 @@ Shared plugins can be placed in `~/.openbot/plugins` and referenced by agents.
 ## Project Layout
 
 - `src/app`: CLI, server, event types, and app config.
-- `src/harness`: agent harness, orchestration, process, and MCP runtime helpers.
+- `src/harness`: orchestration, process, and MCP runtime helpers.
 - `src/plugins`: built-in plugin implementations.
 - `src/services`: local storage service.
 - `src/registry`: plugin registry.

package/dist/app/cli.js

@@ -16,7 +16,7 @@ function checkNodeVersion() {
     }
 }
 checkNodeVersion();
-program.name('openbot').description('OpenBot CLI').version('0.3.3');
+program.name('openbot').description('OpenBot CLI').version('0.3.4');
 program
     .command('start')
     .description('Start the OpenBot harness')

package/dist/app/server.js

@@ -11,7 +11,7 @@ import { generateId } from 'melony';
 import { DEFAULT_BASE_DIR, loadConfig, resolvePath } from '../app/config.js';
 import { processService } from '../harness/process.js';
 import { storageService } from '../services/storage.js';
-import { AgentHarness } from '../harness/agent-harness.js';
+import { dispatch } from '../harness/dispatcher.js';
 import { initPlugins } from '../registry/plugins.js';
 import { ensureEventId, openBotEventFromQuery } from './utils.js';
 export async function startServer(options = {}) {
@@ -69,25 +69,39 @@ export async function startServer(options = {}) {
         });
     };
     const buildActiveRunsSnapshot = () => {
-        const byChannel = new Map();
+        const byBucket = new Map();
         for (const run of activeRuns.values()) {
-            const existing = byChannel.get(run.channelId) ?? {
-                activeCount: 0,
-                agentIds: new Set(),
-            };
-            existing.activeCount += 1;
-            existing.agentIds.add(run.agentId);
-            byChannel.set(run.channelId, existing);
+            const threadId = run.threadId || undefined;
+            const key = JSON.stringify([run.channelId, threadId ?? null]);
+            let bucket = byBucket.get(key);
+            if (!bucket) {
+                bucket = { channelId: run.channelId, threadId, activeCount: 0, agentIds: new Set() };
+                byBucket.set(key, bucket);
+            }
+            bucket.activeCount += 1;
+            bucket.agentIds.add(run.agentId);
         }
+        const channels = Array.from(byBucket.values())
+            .sort((a, b) => {
+            const c = a.channelId.localeCompare(b.channelId);
+            if (c !== 0)
+                return c;
+            return (a.threadId ?? '').localeCompare(b.threadId ?? '');
+        })
+            .map(({ channelId, threadId, activeCount, agentIds }) => {
+            const row = {
+                channelId,
+                activeCount,
+                agentIds: Array.from(agentIds),
+            };
+            if (threadId !== undefined) {
+                row.threadId = threadId;
+            }
+            return row;
+        });
         return {
             type: 'agent:active-runs:snapshot',
-            data: {
-                channels: Array.from(byChannel.entries()).map(([channelId, value]) => ({
-                    channelId,
-                    activeCount: value.activeCount,
-                    agentIds: Array.from(value.agentIds),
-                })),
-            },
+            data: { channels },
         };
     };
     app.use(cors());
@@ -178,19 +192,22 @@ export async function startServer(options = {}) {
                 event: chunk,
             });
             sendToClientKey(targetClientKey, chunk);
-            if (chunk.type === 'agent:run:start' || chunk.type === 'agent:run:end') {
+            if (chunk.type === 'agent:run:start' ||
+                chunk.type === 'agent:run:end' ||
+                chunk.type === 'agent:run:stopped') {
                 sendToClientKey(GLOBAL_CHANNEL_ID, chunk);
             }
         };
         try {
-            const harness = new AgentHarness({
+            ensureEventId(event);
+            await dispatch({
                 runId,
                 agentId: agentId || 'system',
+                event,
                 channelId,
                 threadId,
                 onEvent,
             });
-            await harness.dispatch(event);
             res.sendStatus(200);
         }
         catch (error) {
@@ -220,14 +237,15 @@ export async function startServer(options = {}) {
             events.push(chunk);
         };
         try {
-            const harness = new AgentHarness({
+            ensureEventId(event);
+            await dispatch({
                 runId,
                 agentId: agentId || 'system',
+                event,
                 channelId,
                 threadId,
                 onEvent,
             });
-            await harness.dispatch(event);
             res.json({ events });
         }
         catch (error) {

package/dist/assets/icon.svg

@@ -0,0 +1,4 @@
+<svg width="60.2" height="58.1" viewBox="262.8 360.5 84.2 82.1" fill="#9333EA" xmlns="http://www.w3.org/2000/svg">
+<path d="M301.841 380.896C302.069 380.893 302.297 380.889 302.531 380.885C304.636 380.853 306.741 380.836 308.845 380.822C310.26 380.813 311.675 380.8 313.09 380.775C314.456 380.752 315.822 380.739 317.189 380.735C317.71 380.731 318.231 380.724 318.752 380.712C322.824 380.626 322.824 380.626 323.909 381.43C324.315 382.025 324.561 382.569 324.8 383.246C324.965 383.518 325.13 383.789 325.301 384.068C325.519 384.445 325.519 384.445 325.741 384.83C325.909 385.118 326.077 385.407 326.249 385.704C326.336 385.854 326.423 386.004 326.513 386.159C328.304 389.25 330.137 392.314 332.004 395.361C332.482 396.144 332.957 396.929 333.431 397.715C333.631 398.035 333.631 398.035 333.835 398.361C334.546 399.544 334.969 400.367 334.7 401.777C334.24 402.838 333.683 403.834 333.113 404.839C332.867 405.285 332.621 405.73 332.375 406.176C332.125 406.626 331.874 407.075 331.622 407.525C330.952 408.724 330.296 409.931 329.639 411.137C329.518 411.359 329.397 411.58 329.272 411.807C328.303 413.581 327.349 415.362 326.398 417.144C324.53 420.642 322.621 424.107 320.611 427.525C320.282 428.088 319.962 428.655 319.644 429.224C319.215 429.954 319.215 429.954 318.708 430.462C317.978 430.557 317.978 430.557 317.185 430.462C316.049 429.578 315.42 428.258 314.71 427.035C313.685 425.291 312.637 423.6 311.454 421.96C311.024 421.203 310.906 420.668 310.838 419.8C311.092 419.081 311.092 419.081 311.491 418.343C311.707 417.937 311.707 417.937 311.927 417.522C312.081 417.242 312.235 416.963 312.393 416.675C312.615 416.26 312.615 416.26 312.841 415.836C314.003 413.671 314.003 413.671 314.549 412.797C315.269 411.676 315.269 411.676 315.308 410.387C314.801 409.466 314.268 408.575 313.694 407.695C313.466 407.335 313.238 406.976 313.011 406.616C312.845 406.353 312.845 406.353 312.676 406.085C312.247 405.402 311.829 404.713 311.425 404.014C311.304 403.806 311.183 403.598 311.058 403.384C310.786 402.65 310.848 402.26 311.092 401.523C311.6 401.015 311.6 401.015 312.57 400.967C312.988 400.97 313.407 400.975 313.826 400.982C314.281 400.981 314.737 400.981 315.192 400.98C315.911 400.98 316.629 400.984 317.348 400.995C318.041 401.005 318.733 401.002 319.427 400.998C319.641 401.004 319.854 401.011 320.075 401.017C320.695 401.007 321.171 400.974 321.754 400.762C322.329 400.154 322.665 399.481 323.023 398.731C323.171 398.49 323.318 398.248 323.47 398C323.899 397.287 324.326 396.573 324.752 395.859C324.904 395.608 325.056 395.357 325.212 395.099C325.355 394.859 325.498 394.618 325.646 394.371C325.841 394.045 325.841 394.045 326.04 393.713C326.38 393.138 326.38 393.138 326.323 392.385C326.167 392.384 326.011 392.383 325.85 392.383C322.054 392.368 318.257 392.349 314.461 392.325C312.625 392.313 310.789 392.303 308.953 392.297C307.352 392.291 305.752 392.282 304.152 392.271C303.305 392.265 302.458 392.26 301.61 392.258C300.664 392.256 299.719 392.249 298.773 392.241C298.351 392.241 298.351 392.241 297.921 392.242C297.663 392.238 297.406 392.235 297.14 392.232C296.916 392.231 296.693 392.23 296.462 392.228C295.73 392.109 295.379 391.879 294.846 391.369C294.591 389.978 295.187 388.999 295.837 387.818C295.938 387.63 296.038 387.441 296.142 387.246C296.464 386.646 296.789 386.049 297.115 385.451C297.333 385.045 297.551 384.638 297.769 384.231C299.545 380.925 299.545 380.925 301.841 380.896Z" fill="#9333EA"/>
+<path d="M291.476 372.547C292.795 373.009 293.243 374.055 293.942 375.218C294.23 375.684 294.519 376.15 294.807 376.615C294.945 376.84 295.082 377.065 295.223 377.297C295.544 377.813 295.875 378.314 296.225 378.811C296.388 379.044 296.551 379.277 296.718 379.518C296.856 379.711 296.994 379.903 297.137 380.102C297.492 380.97 297.407 381.615 297.131 382.485C296.704 383.459 296.209 384.39 295.703 385.325C295.497 385.714 295.497 385.714 295.287 386.111C294.44 387.702 293.559 389.255 292.565 390.759C292.217 391.585 292.351 392.026 292.562 392.892C292.955 393.665 292.955 393.665 293.466 394.431C293.555 394.572 293.644 394.713 293.736 394.858C294.019 395.304 294.305 395.748 294.592 396.192C294.971 396.778 295.346 397.365 295.719 397.953C295.886 398.212 296.053 398.471 296.225 398.738C296.646 399.535 296.848 400.115 296.877 401.015C296.559 401.435 296.559 401.435 296.115 401.777C295.364 401.849 294.663 401.877 293.911 401.871C293.467 401.876 293.023 401.88 292.579 401.885C291.879 401.887 291.18 401.888 290.48 401.888C289.804 401.888 289.129 401.895 288.453 401.903C288.244 401.901 288.036 401.899 287.82 401.897C286.637 401.91 286.637 401.91 285.616 402.466C284.844 403.543 284.229 404.69 283.598 405.854C283.455 406.11 283.312 406.365 283.165 406.628C283.031 406.873 282.897 407.118 282.76 407.371C282.637 407.594 282.515 407.818 282.389 408.048C282.071 408.656 282.071 408.656 282.408 409.392C282.559 409.393 282.71 409.394 282.865 409.395C286.539 409.416 290.213 409.439 293.886 409.465C295.663 409.478 297.439 409.49 299.216 409.499C300.929 409.509 302.642 409.521 304.356 409.534C305.011 409.539 305.665 409.543 306.32 409.546C307.235 409.55 308.15 409.557 309.064 409.565C309.473 409.566 309.473 409.566 309.89 409.567C310.139 409.57 310.388 409.573 310.644 409.576C310.861 409.577 311.077 409.578 311.3 409.58C311.854 409.646 311.854 409.646 312.615 410.154C312.797 411.581 312.41 412.577 311.745 413.808C311.656 413.979 311.567 414.15 311.475 414.326C311.288 414.685 311.099 415.042 310.908 415.399C310.616 415.946 310.329 416.495 310.042 417.045C309.859 417.394 309.676 417.743 309.492 418.092C309.363 418.337 309.363 418.337 309.231 418.588C308.881 419.242 308.574 419.78 308.046 420.308C307.364 420.361 306.707 420.382 306.024 420.382C305.815 420.383 305.606 420.385 305.391 420.387C304.698 420.392 304.005 420.392 303.312 420.393C302.832 420.395 302.351 420.396 301.871 420.398C300.862 420.401 299.854 420.402 298.845 420.402C297.552 420.402 296.259 420.409 294.966 420.417C293.973 420.423 292.98 420.424 291.987 420.424C291.51 420.424 291.034 420.427 290.557 420.431C289.89 420.436 289.224 420.434 288.557 420.431C288.36 420.434 288.163 420.437 287.959 420.44C287.061 420.429 286.569 420.386 285.852 419.824C285.47 419.314 285.137 418.817 284.831 418.259C284.718 418.056 284.605 417.852 284.488 417.643C284.367 417.423 284.246 417.203 284.121 416.976C282.907 414.808 281.638 412.679 280.329 410.566C280.156 410.286 279.982 410.006 279.803 409.717C279.469 409.176 279.134 408.636 278.799 408.096C277.871 406.592 276.959 405.077 276.062 403.554C275.968 403.409 275.874 403.264 275.777 403.114C275.143 402.097 274.834 401.442 275.046 400.254C275.425 399.337 275.889 398.475 276.363 397.604C276.568 397.22 276.568 397.22 276.777 396.828C278.005 394.541 279.284 392.283 280.569 390.029C282.224 387.119 283.868 384.197 285.327 381.184C289.509 372.654 289.509 372.654 291.476 372.547Z" fill="#9333EA"/>
+</svg>

package/dist/bus/services.js

@@ -455,8 +455,8 @@ export const busServicesPlugin = (options) => (builder) => {
     });
     builder.on('action:storage:create-agent', async function* (event) {
         try {
-            const { agentId, name, description, instructions, plugins } = event.data;
-            await storage.createAgent({ agentId, name, description, instructions, plugins });
+            const { agentId, name, description, image, instructions, plugins } = event.data;
+            await storage.createAgent({ agentId, name, description, image, instructions, plugins });
             yield { type: 'action:storage:create-agent-result', data: { success: true } };
         }
         catch (error) {
@@ -471,8 +471,8 @@ export const busServicesPlugin = (options) => (builder) => {
     });
     builder.on('action:storage:update-agent', async function* (event) {
         try {
-            const { agentId, name, description, instructions, plugins } = event.data;
-            await storage.updateAgent({ agentId, name, description, instructions, plugins });
+            const { agentId, name, description, image, instructions, plugins } = event.data;
+            await storage.updateAgent({ agentId, name, description, image, instructions, plugins });
             yield { type: 'action:storage:update-agent-result', data: { success: true } };
         }
         catch (error) {
@@ -758,7 +758,7 @@ export const busServicesPlugin = (options) => (builder) => {
     });
     builder.on('action:agent:install', async function* (event) {
         try {
-            const { agentId, name, description, instructions, plugins } = event.data;
+            const { agentId, name, description, image, instructions, plugins } = event.data;
             // Ensure each plugin is available locally. Built-in ids resolve
             // immediately; npm-name ids are fetched on demand.
             for (const ref of plugins) {
@@ -780,6 +780,7 @@ export const busServicesPlugin = (options) => (builder) => {
                 agentId,
                 name,
                 description,
+                image,
                 instructions,
                 plugins,
             });

package/dist/harness/dispatcher.js

@@ -0,0 +1,267 @@
+import { ensureEventId } from '../app/utils.js';
+import { storageService } from '../services/storage.js';
+import { createAgentRuntime } from './runtime-factory.js';
+import { advanceAfterRun } from './todo-advance.js';
+const MAX_CHAIN_DEPTH = 20;
+const stopRequests = [];
+const STOP_REQUEST_TTL_MS = 30 * 60 * 1000;
+const pruneStopRequests = () => {
+    const now = Date.now();
+    for (let i = stopRequests.length - 1; i >= 0; i -= 1) {
+        if (now - stopRequests[i].requestedAt > STOP_REQUEST_TTL_MS) {
+            stopRequests.splice(i, 1);
+        }
+    }
+};
+const findStopRequest = (target) => {
+    pruneStopRequests();
+    return stopRequests.find((r) => {
+        if (r.runId !== target.runId)
+            return false;
+        if (r.agentId && r.agentId !== target.agentId)
+            return false;
+        if (r.channelId && r.channelId !== target.channelId)
+            return false;
+        if (r.threadId && r.threadId !== target.threadId)
+            return false;
+        return true;
+    });
+};
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+export async function dispatch(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,
+    };
+    if (event.type === 'user:input' || event.type === 'agent:invoke') {
+        const invoke = await normalizeUserInput(event, ctx);
+        await runStep({ agentId: options.agentId || 'system', event: invoke }, ctx, 0);
+        return;
+    }
+    // Bus pass-through: route to the targeted agent's runtime once. No agent step,
+    // no advance, no follow-ups. Keeps queries (`/api/state`) cheap and idempotent.
+    await runBusEvent(event, options.agentId || 'system', ctx);
+}
+// ---------------------------------------------------------------------------
+// Agent step: run:start -> runtime -> run:end -> advance -> chain
+// ---------------------------------------------------------------------------
+async function runStep(step, ctx, depth) {
+    if (depth >= MAX_CHAIN_DEPTH) {
+        console.warn(`[dispatcher] Reached MAX_CHAIN_DEPTH (${MAX_CHAIN_DEPTH}); stopping chain.`);
+        return;
+    }
+    const target = {
+        runId: ctx.runId,
+        agentId: step.agentId,
+        channelId: ctx.channelId,
+        threadId: ctx.threadId,
+    };
+    const preStop = findStopRequest(target);
+    if (preStop) {
+        const state = await storageService.getOpenBotState({ ...target, event: step.event });
+        await ctx.onEvent({ type: 'agent:run:stopped', data: { ...target, reason: preStop.reason } }, state);
+        return;
+    }
+    let state;
+    try {
+        state = await storageService.getOpenBotState({ ...target, event: step.event });
+    }
+    catch (error) {
+        if (error.code === 'AGENT_NOT_FOUND') {
+            const fallback = await storageService.getOpenBotState({
+                ...target,
+                agentId: 'system',
+                event: step.event,
+            });
+            await ctx.onEvent({
+                type: 'agent:output',
+                data: { content: `⚠️ Agent **${step.agentId}** does not exist. Please check the agent ID and try again.` },
+                meta: { agentId: 'system', threadId: ctx.threadId },
+            }, fallback);
+            return;
+        }
+        throw error;
+    }
+    await ctx.onEvent({ type: 'agent:run:start', data: { ...target } }, state);
+    const followUps = [];
+    const queuedAgentIds = new Set();
+    let lastAgentOutput;
+    try {
+        const runtime = await createAgentRuntime(state);
+        for await (const chunk of runtime.run(step.event, { state, runId: ctx.runId })) {
+            const stop = findStopRequest(target);
+            if (stop) {
+                await ctx.onEvent({ type: 'agent:run:stopped', data: { ...target, reason: stop.reason } }, state);
+                break;
+            }
+            if (chunk.id === step.event.id && chunk.type === step.event.type)
+                continue;
+            if (chunk.type === 'action:create_thread:result' && chunk.data.success) {
+                ctx.threadId = chunk.data.threadId || ctx.threadId;
+            }
+            if (chunk.type === 'agent:output' &&
+                chunk.meta?.agentId === step.agentId) {
+                const content = chunk.data?.content;
+                if (typeof content === 'string' && content.trim())
+                    lastAgentOutput = content.trim();
+            }
+            // Handoff requests are internal: queue a follow-up step instead of forwarding.
+            if (chunk.type === 'handoff:request') {
+                const req = chunk;
+                const targetAgent = req.data?.agentId;
+                if (targetAgent && targetAgent !== step.agentId && !queuedAgentIds.has(targetAgent)) {
+                    queuedAgentIds.add(targetAgent);
+                    followUps.push({
+                        agentId: targetAgent,
+                        event: makeInvoke(req.data.content, ctx.threadId, req.meta),
+                    });
+                }
+                continue;
+            }
+            chunk.meta = { ...chunk.meta, agentId: step.agentId };
+            await ctx.onEvent(chunk, state);
+        }
+    }
+    catch (error) {
+        console.error(`[dispatcher] Agent run failed: ${step.agentId}`, error);
+    }
+    finally {
+        const endState = await storageService.getOpenBotState({ ...target, event: step.event });
+        await ctx.onEvent({ type: 'agent:run:end', data: { ...target } }, endState);
+    }
+    // Autonomous todo advance: single trigger point, runs once per `agent:run:end`.
+    try {
+        const handoff = await advanceAfterRun({
+            storage: storageService,
+            channelId: ctx.channelId,
+            threadId: ctx.threadId,
+            endedAgentId: step.agentId,
+            lastAgentOutput,
+        });
+        if (handoff && !queuedAgentIds.has(handoff.agentId)) {
+            queuedAgentIds.add(handoff.agentId);
+            followUps.push({
+                agentId: handoff.agentId,
+                event: makeInvoke(handoff.content, ctx.threadId),
+            });
+        }
+    }
+    catch (error) {
+        console.warn('[dispatcher] todo advance failed', error);
+    }
+    for (const next of followUps) {
+        await runStep(next, ctx, depth + 1);
+    }
+}
+// ---------------------------------------------------------------------------
+// Bus pass-through: run an event through the targeted agent's runtime, forward
+// chunks. No run:start/end, no advance, no follow-ups.
+// ---------------------------------------------------------------------------
+async function runBusEvent(event, agentId, ctx) {
+    let state;
+    try {
+        state = await storageService.getOpenBotState({
+            runId: ctx.runId,
+            agentId,
+            channelId: ctx.channelId,
+            threadId: ctx.threadId,
+            event,
+        });
+    }
+    catch (error) {
+        if (error.code === 'AGENT_NOT_FOUND') {
+            // Silently drop: bus pass-through has no UI surface to warn into.
+            return;
+        }
+        throw error;
+    }
+    try {
+        const runtime = await createAgentRuntime(state);
+        for await (const chunk of runtime.run(event, { state, runId: ctx.runId })) {
+            if (chunk.id === event.id && chunk.type === event.type)
+                continue;
+            chunk.meta = { ...chunk.meta, agentId };
+            await ctx.onEvent(chunk, state);
+        }
+    }
+    catch (error) {
+        console.error(`[dispatcher] Bus event failed: ${event.type} (${agentId})`, error);
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+async function normalizeUserInput(event, ctx) {
+    const rawContent = event.data?.content || '';
+    // The user-facing copy stored/streamed for the UI.
+    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 storageService.getOpenBotState({
+        runId: ctx.runId,
+        agentId: 'system',
+        channelId: ctx.channelId,
+        threadId: ctx.threadId,
+        event: userFacing,
+    });
+    await ctx.onEvent(userFacing, initialState);
+    // The event actually fed to the target agent. Carries the input threadId (or the
+    // message id, used as the anchor for Slack-style new threads).
+    return {
+        ...event,
+        type: 'agent:invoke',
+        data: { ...(event.data || {}), content: rawContent, role: 'user' },
+        meta: {
+            ...(event.meta || {}),
+            threadId: ctx.threadId || event.id,
+        },
+    };
+}
+function makeInvoke(content, threadId, baseMeta) {
+    return ensureEventId({
+        type: 'agent:invoke',
+        data: { role: 'user', content },
+        meta: { ...(baseMeta || {}), threadId },
+    });
+}
+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 storageService.getOpenBotState({
+        runId,
+        agentId: options.agentId || 'system',
+        channelId,
+        threadId,
+        event: 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/orchestrator.js

@@ -2,6 +2,30 @@ import { storageService } from '../services/storage.js';
 import { createAgentRuntime } from './runtime-factory.js';
 import { EventNormalizer } from './event-normalizer.js';
 import { QueueProcessor } from './queue-processor.js';
+const stopRequests = [];
+const STOP_REQUEST_TTL_MS = 30 * 60 * 1000;
+const pruneStopRequests = () => {
+    const now = Date.now();
+    for (let i = stopRequests.length - 1; i >= 0; i -= 1) {
+        if (now - stopRequests[i].requestedAt > STOP_REQUEST_TTL_MS) {
+            stopRequests.splice(i, 1);
+        }
+    }
+};
+const findStopRequest = (options) => {
+    pruneStopRequests();
+    return stopRequests.find((request) => {
+        if (request.runId !== options.runId)
+            return false;
+        if (request.agentId && request.agentId !== options.agentId)
+            return false;
+        if (request.channelId && request.channelId !== options.channelId)
+            return false;
+        if (request.threadId && request.threadId !== options.threadId)
+            return false;
+        return true;
+    });
+};
 export const orchestratorService = {
     /**
      * The primary entry point for all events coming into the system (e.g. from the API).
@@ -9,6 +33,33 @@ export const orchestratorService = {
      */
     dispatch: async (options) => {
         const { runId, channelId, threadId, onEvent } = options;
+        if (options.event.type === 'action:agent_run_stop') {
+            const stopEvent = options.event;
+            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 storageService.getOpenBotState({
+                runId,
+                agentId: options.agentId || 'system',
+                channelId,
+                threadId,
+                event: options.event,
+            });
+            await onEvent({
+                type: 'action:agent_run_stop:result',
+                data: {
+                    success: true,
+                    message: `Stop requested for run ${stopEvent.data.runId}.`,
+                },
+                meta: options.event.meta,
+            }, state);
+            return;
+        }
         // 1. Normalize incoming event
         const { finalEvent, finalAgentId } = await EventNormalizer.normalize(options.event, {
             runId,
@@ -24,6 +75,7 @@ export const orchestratorService = {
             threadId,
             onEvent,
             executeAgent: orchestratorService.executeAgent,
+            shouldStopRun: orchestratorService.shouldStopRun,
         });
         // 3. Enqueue initial event
         processor.enqueue({ agentId: finalAgentId, event: finalEvent });
@@ -59,9 +111,29 @@ export const orchestratorService = {
             throw error;
         }
         const agentRuntime = await createAgentRuntime(agentState);
+        const stopInfo = {
+            runId,
+            agentId,
+            channelId,
+            threadId,
+        };
         try {
             // RUN the agent runtime
             for await (const chunk of agentRuntime.run(event, { state: agentState, runId })) {
+                const stopRequest = findStopRequest(stopInfo);
+                if (stopRequest) {
+                    await onEvent({
+                        type: 'agent:run:stopped',
+                        data: {
+                            runId,
+                            agentId,
+                            channelId,
+                            threadId,
+                            reason: stopRequest.reason,
+                        },
+                    }, agentState);
+                    break;
+                }
                 chunk.meta = { ...chunk.meta, agentId };
                 await onEvent(chunk, agentState);
             }
@@ -70,4 +142,8 @@ export const orchestratorService = {
             console.error(`[orchestrator] Agent run failed: ${agentId}`, error);
         }
     },
+    shouldStopRun: (options) => {
+        const request = findStopRequest(options);
+        return request ? { shouldStop: true, reason: request.reason } : { shouldStop: false };
+    },
 };

package/dist/harness/queue-processor.js

@@ -28,6 +28,32 @@ export class QueueProcessor {
                 // Run items for the SAME agent sequentially to preserve event order and state consistency.
                 for (const item of items) {
                     const { event: currentEvent } = item;
+                    const stopCheck = this.options.shouldStopRun?.({
+                        runId: this.options.runId,
+                        agentId,
+                        channelId: this.options.channelId,
+                        threadId: this.currentThreadId,
+                    });
+                    if (stopCheck?.shouldStop) {
+                        const stoppedState = await storageService.getOpenBotState({
+                            runId: this.options.runId,
+                            agentId,
+                            channelId: this.options.channelId,
+                            threadId: this.currentThreadId,
+                            event: currentEvent,
+                        });
+                        await this.options.onEvent({
+                            type: 'agent:run:stopped',
+                            data: {
+                                runId: this.options.runId,
+                                agentId,
+                                channelId: this.options.channelId,
+                                threadId: this.currentThreadId,
+                                reason: stopCheck.reason,
+                            },
+                        }, stoppedState);
+                        continue;
+                    }
                     // Track handoff requests queued in this step to avoid accidental duplicates.
                     const queuedRequestKeys = new Set();
                     const queuedItems = [];