openbot 0.4.3 → 0.4.5

package/dist/app/cli.js

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

package/dist/app/responding-agent.js

@@ -0,0 +1,48 @@
+import { ORCHESTRATOR_AGENT_ID } from './agent-ids.js';
+import { storageService } from '../plugins/storage/service.js';
+/** Thread `state.json` key for the sticky responding agent id. */
+export const THREAD_RESPONDING_AGENT_ID_KEY = 'respondingAgentId';
+const readBoundAgentId = (state) => {
+    if (!state || typeof state !== 'object')
+        return undefined;
+    const value = state[THREAD_RESPONDING_AGENT_ID_KEY];
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed || undefined;
+};
+/**
+ * Resolves which agent should handle a thread-scoped publish.
+ * Once `respondingAgentId` is stored on the thread, that value wins over request overrides.
+ */
+export async function resolveRespondingAgentId(options) {
+    const { channelId, threadId, requestedAgentId, bindIfUnbound = false } = options;
+    const requested = requestedAgentId?.trim() || undefined;
+    const fallback = requested || ORCHESTRATOR_AGENT_ID;
+    if (!threadId) {
+        return { agentId: fallback, bound: false, overridden: false };
+    }
+    const details = await storageService.getThreadDetails({ channelId, threadId });
+    const bound = readBoundAgentId(details.state);
+    if (bound) {
+        const overridden = !!requested && requested !== bound;
+        if (overridden) {
+            console.warn('[publish] Ignoring agentId override; thread is bound to responding agent', {
+                threadId,
+                bound,
+                requested,
+            });
+        }
+        return { agentId: bound, bound: true, overridden };
+    }
+    if (!bindIfUnbound) {
+        return { agentId: fallback, bound: false, overridden: false };
+    }
+    await storageService.getAgentDetails({ agentId: fallback });
+    await storageService.patchThreadState({
+        channelId,
+        threadId,
+        state: { [THREAD_RESPONDING_AGENT_ID_KEY]: fallback },
+    });
+    return { agentId: fallback, bound: true, overridden: false };
+}

package/dist/app/server.js

@@ -16,6 +16,7 @@ import { storageService } from '../plugins/storage/service.js';
 import { buildWorkspaceFileUrl, getPublicBaseUrl, openChannelFileStream, } from '../plugins/storage/files.js';
 import { ensureEventId, openBotEventFromQuery } from './utils.js';
 import { abortRegistry, abortKey } from '../services/abort.js';
+import { resolveRespondingAgentId } from './responding-agent.js';
 export async function startServer(options = {}) {
     const publishEventSchema = z
         .object({
@@ -116,19 +117,71 @@ export async function startServer(options = {}) {
             data: { channels },
         };
     };
+    const broadcastActiveRunsSnapshot = () => {
+        const snapshot = buildActiveRunsSnapshot();
+        ensureEventId(snapshot);
+        sendToClientKey(GLOBAL_CHANNEL_ID, snapshot);
+    };
+    const persistLifecycleEvent = (event, targetChannelId, targetThreadId) => {
+        ensureEventId(event);
+        storageService
+            .storeEvent({
+            channelId: targetChannelId,
+            threadId: targetThreadId,
+            event,
+        })
+            .catch((error) => {
+            console.error('[server] Failed to persist lifecycle event', {
+                type: event.type,
+                channelId: targetChannelId,
+                threadId: targetThreadId,
+                error,
+            });
+        });
+    };
     // Drop every tracked run for a channel/thread. A stop aborts the whole
     // chain (parent + delegated sub-agents), but the sub-agents' `agent:run:end`
     // events can be swallowed when the parent run loop breaks on abort, leaving
-    // orphaned entries that keep a channel falsely "active". Purging by
-    // channel/thread guarantees the snapshot self-heals after a stop.
+    // orphaned entries that keep a channel falsely "active". Emit explicit
+    // `agent:run:end` for each purged run and refresh the global snapshot so
+    // clients stay in sync even when the parent harness stops yielding.
     const purgeActiveRunsForThread = (channelId, threadId) => {
         const target = threadId || undefined;
+        const removed = [];
         for (const [key, run] of activeRuns) {
             if (run.channelId === channelId && (run.threadId || undefined) === target) {
+                removed.push(run);
                 activeRuns.delete(key);
             }
         }
+        for (const run of removed) {
+            const endEvent = {
+                type: 'agent:run:end',
+                data: {
+                    runId: run.runId,
+                    agentId: run.agentId,
+                    channelId: run.channelId,
+                    threadId: run.threadId,
+                },
+            };
+            ensureEventId(endEvent);
+            persistLifecycleEvent(endEvent, run.channelId, run.threadId);
+            sendToClientKey(getClientKey(run.channelId, run.threadId), endEvent);
+            sendToClientKey(GLOBAL_CHANNEL_ID, endEvent);
+        }
     };
+    // Support for Chrome's Private Network Access (PNA)
+    // https://developer.chrome.com/blog/private-network-access-preflight/
+    app.use((req, res, next) => {
+        if (req.headers['access-control-request-private-network'] === 'true') {
+            res.setHeader('Access-Control-Allow-Private-Network', 'true');
+        }
+        // If it's a preflight request, we should also ensure the Vary header is set
+        if (req.method === 'OPTIONS') {
+            res.setHeader('Vary', 'Access-Control-Request-Private-Network');
+        }
+        next();
+    });
     app.use(cors());
     const resolvePublicBaseUrl = () => getPublicBaseUrl(PORT, config.publicUrl);
     app.use((req, res, next) => {
@@ -316,19 +369,38 @@ export async function startServer(options = {}) {
             const data = (event.data ?? {});
             const targetChannelId = data.channelId || channelId;
             const targetThreadId = data.threadId || threadId;
+            let resolvedStopAgentId = data.agentId || agentId || ORCHESTRATOR_AGENT_ID;
+            try {
+                const resolved = await resolveRespondingAgentId({
+                    channelId: targetChannelId,
+                    threadId: targetThreadId,
+                    requestedAgentId: data.agentId || agentId,
+                });
+                resolvedStopAgentId = resolved.agentId;
+            }
+            catch (error) {
+                console.warn('[publish] Failed to resolve responding agent for stop request', {
+                    channelId: targetChannelId,
+                    threadId: targetThreadId,
+                    error,
+                });
+            }
             const stopped = abortRegistry.abort(abortKey(targetChannelId, targetThreadId));
             purgeActiveRunsForThread(targetChannelId, targetThreadId);
+            // Resync global clients even when nothing was tracked server-side.
+            broadcastActiveRunsSnapshot();
             const stoppedEvent = {
                 type: 'agent:run:stopped',
                 data: {
                     runId: data.runId || runId,
-                    agentId: data.agentId || agentId || ORCHESTRATOR_AGENT_ID,
+                    agentId: resolvedStopAgentId,
                     channelId: targetChannelId,
                     threadId: targetThreadId,
                     reason: data.reason,
                 },
             };
             ensureEventId(stoppedEvent);
+            persistLifecycleEvent(stoppedEvent, targetChannelId, targetThreadId);
             sendToClientKey(getClientKey(targetChannelId, targetThreadId), stoppedEvent);
             sendToClientKey(GLOBAL_CHANNEL_ID, stoppedEvent);
             res.json({ success: stopped });
@@ -351,6 +423,7 @@ export async function startServer(options = {}) {
             }
             else if (chunk.type === 'agent:run:stopped') {
                 purgeActiveRunsForThread(chunk.data.channelId, chunk.data.threadId);
+                broadcastActiveRunsSnapshot();
             }
             sendToClientKey(targetClientKey, chunk);
             if (chunk.type === 'agent:run:start' ||
@@ -361,9 +434,16 @@ export async function startServer(options = {}) {
         };
         try {
             ensureEventId(event);
+            const bindIfUnbound = event.type === 'agent:invoke';
+            const resolved = await resolveRespondingAgentId({
+                channelId,
+                threadId,
+                requestedAgentId: agentId,
+                bindIfUnbound,
+            });
             await runAgent({
                 runId,
-                agentId: agentId || ORCHESTRATOR_AGENT_ID,
+                agentId: resolved.agentId,
                 event,
                 channelId,
                 threadId,
@@ -373,6 +453,11 @@ export async function startServer(options = {}) {
             res.sendStatus(200);
         }
         catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const isUnknownAgent = (error instanceof Error &&
+                (error.code === 'AGENT_NOT_FOUND' ||
+                    error.message.includes('does not exist'))) ||
+                message.includes('does not exist');
             console.error('[publish] Failed to dispatch event', {
                 runId,
                 channelId,
@@ -380,6 +465,10 @@ export async function startServer(options = {}) {
                 eventType: event.type,
                 error,
             });
+            if (isUnknownAgent) {
+                res.status(400).json({ error: message });
+                return;
+            }
             res.status(500).json({ error: 'Failed to process publish event' });
         }
     });
@@ -394,6 +483,13 @@ export async function startServer(options = {}) {
             return;
         }
         const { channelId, threadId, agentId, runId } = getContext(req);
+        // In-memory active runs (not persisted). Mirrors the initial SSE frame on __global__.
+        if (channelId === GLOBAL_CHANNEL_ID && event.type === 'action:storage:get-active-runs') {
+            const snapshot = buildActiveRunsSnapshot();
+            ensureEventId(snapshot);
+            res.json({ events: [snapshot] });
+            return;
+        }
         if (event.type === 'action:storage:serve-file') {
             const filePath = event.data?.path;
             if (!channelId?.trim()) {

package/dist/plugins/storage/service.js

@@ -614,7 +614,7 @@ export const storageService = {
             id: threadId,
             name: threadName || threadId,
             channelId,
-            state,
+            state: (isRecord(state) ? state : {}),
         };
     },
     getChannelDetails: async ({ channelId }) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openbot",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "private": false,
   "type": "module",
   "engines": {

package/src/app/cli.ts

@@ -25,7 +25,7 @@ function checkNodeVersion() {
 
 checkNodeVersion();
 
-program.name('openbot').description('OpenBot CLI').version('0.4.3');
+program.name('openbot').description('OpenBot CLI').version('0.4.5');
 
 program
   .command('start')

package/src/app/responding-agent.ts

@@ -0,0 +1,74 @@
+import { ORCHESTRATOR_AGENT_ID } from './agent-ids.js';
+import { storageService } from '../plugins/storage/service.js';
+
+/** Thread `state.json` key for the sticky responding agent id. */
+export const THREAD_RESPONDING_AGENT_ID_KEY = 'respondingAgentId';
+
+export type ResolveRespondingAgentOptions = {
+  channelId: string;
+  threadId?: string;
+  requestedAgentId?: string;
+  /** When true, persist `respondingAgentId` on the first unbound thread touch. */
+  bindIfUnbound?: boolean;
+};
+
+export type ResolveRespondingAgentResult = {
+  agentId: string;
+  /** True when the thread already had or now has a persisted responding agent. */
+  bound: boolean;
+  /** True when the request asked for a different agent than the bound one. */
+  overridden: boolean;
+};
+
+const readBoundAgentId = (state: unknown): string | undefined => {
+  if (!state || typeof state !== 'object') return undefined;
+  const value = (state as Record<string, unknown>)[THREAD_RESPONDING_AGENT_ID_KEY];
+  if (typeof value !== 'string') return undefined;
+  const trimmed = value.trim();
+  return trimmed || undefined;
+};
+
+/**
+ * Resolves which agent should handle a thread-scoped publish.
+ * Once `respondingAgentId` is stored on the thread, that value wins over request overrides.
+ */
+export async function resolveRespondingAgentId(
+  options: ResolveRespondingAgentOptions,
+): Promise<ResolveRespondingAgentResult> {
+  const { channelId, threadId, requestedAgentId, bindIfUnbound = false } = options;
+  const requested = requestedAgentId?.trim() || undefined;
+  const fallback = requested || ORCHESTRATOR_AGENT_ID;
+
+  if (!threadId) {
+    return { agentId: fallback, bound: false, overridden: false };
+  }
+
+  const details = await storageService.getThreadDetails({ channelId, threadId });
+  const bound = readBoundAgentId(details.state);
+
+  if (bound) {
+    const overridden = !!requested && requested !== bound;
+    if (overridden) {
+      console.warn('[publish] Ignoring agentId override; thread is bound to responding agent', {
+        threadId,
+        bound,
+        requested,
+      });
+    }
+    return { agentId: bound, bound: true, overridden };
+  }
+
+  if (!bindIfUnbound) {
+    return { agentId: fallback, bound: false, overridden: false };
+  }
+
+  await storageService.getAgentDetails({ agentId: fallback });
+
+  await storageService.patchThreadState({
+    channelId,
+    threadId,
+    state: { [THREAD_RESPONDING_AGENT_ID_KEY]: fallback },
+  });
+
+  return { agentId: fallback, bound: true, overridden: false };
+}

package/src/app/server.ts

@@ -21,6 +21,7 @@ import {
 } from '../plugins/storage/files.js';
 import { ensureEventId, openBotEventFromQuery } from './utils.js';
 import { abortRegistry, abortKey } from '../services/abort.js';
+import { resolveRespondingAgentId } from './responding-agent.js';
 
 type Bucket = { channelId: string; threadId?: string; activeCount: number; agentIds: Set<string> };
 
@@ -150,20 +151,86 @@ export async function startServer(options: ServerOptions = {}) {
     };
   };
 
+  const broadcastActiveRunsSnapshot = (): void => {
+    const snapshot = buildActiveRunsSnapshot();
+    ensureEventId(snapshot);
+    sendToClientKey(GLOBAL_CHANNEL_ID, snapshot);
+  };
+
+  const persistLifecycleEvent = (
+    event: OpenBotEvent,
+    targetChannelId: string,
+    targetThreadId?: string,
+  ): void => {
+    ensureEventId(event);
+    storageService
+      .storeEvent({
+        channelId: targetChannelId,
+        threadId: targetThreadId,
+        event,
+      })
+      .catch((error) => {
+        console.error('[server] Failed to persist lifecycle event', {
+          type: event.type,
+          channelId: targetChannelId,
+          threadId: targetThreadId,
+          error,
+        });
+      });
+  };
+
   // Drop every tracked run for a channel/thread. A stop aborts the whole
   // chain (parent + delegated sub-agents), but the sub-agents' `agent:run:end`
   // events can be swallowed when the parent run loop breaks on abort, leaving
-  // orphaned entries that keep a channel falsely "active". Purging by
-  // channel/thread guarantees the snapshot self-heals after a stop.
+  // orphaned entries that keep a channel falsely "active". Emit explicit
+  // `agent:run:end` for each purged run and refresh the global snapshot so
+  // clients stay in sync even when the parent harness stops yielding.
   const purgeActiveRunsForThread = (channelId: string, threadId?: string): void => {
     const target = threadId || undefined;
+    const removed: Array<{
+      runId: string;
+      channelId: string;
+      threadId?: string;
+      agentId: string;
+    }> = [];
+
     for (const [key, run] of activeRuns) {
       if (run.channelId === channelId && (run.threadId || undefined) === target) {
+        removed.push(run);
         activeRuns.delete(key);
       }
     }
+
+    for (const run of removed) {
+      const endEvent: OpenBotEvent = {
+        type: 'agent:run:end',
+        data: {
+          runId: run.runId,
+          agentId: run.agentId,
+          channelId: run.channelId,
+          threadId: run.threadId,
+        },
+      } as OpenBotEvent;
+      ensureEventId(endEvent);
+      persistLifecycleEvent(endEvent, run.channelId, run.threadId);
+      sendToClientKey(getClientKey(run.channelId, run.threadId), endEvent);
+      sendToClientKey(GLOBAL_CHANNEL_ID, endEvent);
+    }
   };
 
+  // Support for Chrome's Private Network Access (PNA)
+  // https://developer.chrome.com/blog/private-network-access-preflight/
+  app.use((req, res, next) => {
+    if (req.headers['access-control-request-private-network'] === 'true') {
+      res.setHeader('Access-Control-Allow-Private-Network', 'true');
+    }
+    // If it's a preflight request, we should also ensure the Vary header is set
+    if (req.method === 'OPTIONS') {
+      res.setHeader('Vary', 'Access-Control-Request-Private-Network');
+    }
+    next();
+  });
+
   app.use(cors());
 
   const resolvePublicBaseUrl = () => getPublicBaseUrl(PORT, config.publicUrl);
@@ -388,20 +455,38 @@ export async function startServer(options: ServerOptions = {}) {
       };
       const targetChannelId = data.channelId || channelId;
       const targetThreadId = data.threadId || threadId;
+      let resolvedStopAgentId = data.agentId || agentId || ORCHESTRATOR_AGENT_ID;
+      try {
+        const resolved = await resolveRespondingAgentId({
+          channelId: targetChannelId,
+          threadId: targetThreadId,
+          requestedAgentId: data.agentId || agentId,
+        });
+        resolvedStopAgentId = resolved.agentId;
+      } catch (error) {
+        console.warn('[publish] Failed to resolve responding agent for stop request', {
+          channelId: targetChannelId,
+          threadId: targetThreadId,
+          error,
+        });
+      }
       const stopped = abortRegistry.abort(abortKey(targetChannelId, targetThreadId));
       purgeActiveRunsForThread(targetChannelId, targetThreadId);
+      // Resync global clients even when nothing was tracked server-side.
+      broadcastActiveRunsSnapshot();
 
       const stoppedEvent: OpenBotEvent = {
         type: 'agent:run:stopped',
         data: {
           runId: data.runId || runId,
-          agentId: data.agentId || agentId || ORCHESTRATOR_AGENT_ID,
+          agentId: resolvedStopAgentId,
           channelId: targetChannelId,
           threadId: targetThreadId,
           reason: data.reason,
         },
       } as OpenBotEvent;
       ensureEventId(stoppedEvent);
+      persistLifecycleEvent(stoppedEvent, targetChannelId, targetThreadId);
       sendToClientKey(getClientKey(targetChannelId, targetThreadId), stoppedEvent);
       sendToClientKey(GLOBAL_CHANNEL_ID, stoppedEvent);
 
@@ -430,6 +515,7 @@ export async function startServer(options: ServerOptions = {}) {
         );
       } else if (chunk.type === 'agent:run:stopped') {
         purgeActiveRunsForThread(chunk.data.channelId, chunk.data.threadId);
+        broadcastActiveRunsSnapshot();
       }
 
       sendToClientKey(targetClientKey, chunk);
@@ -446,9 +532,17 @@ export async function startServer(options: ServerOptions = {}) {
     try {
       ensureEventId(event);
 
+      const bindIfUnbound = event.type === 'agent:invoke';
+      const resolved = await resolveRespondingAgentId({
+        channelId,
+        threadId,
+        requestedAgentId: agentId,
+        bindIfUnbound,
+      });
+
       await runAgent({
         runId,
-        agentId: agentId || ORCHESTRATOR_AGENT_ID,
+        agentId: resolved.agentId,
         event,
         channelId,
         threadId,
@@ -457,6 +551,13 @@ export async function startServer(options: ServerOptions = {}) {
       });
       res.sendStatus(200);
     } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      const isUnknownAgent =
+        (error instanceof Error &&
+          ((error as Error & { code?: string }).code === 'AGENT_NOT_FOUND' ||
+            error.message.includes('does not exist'))) ||
+        message.includes('does not exist');
+
       console.error('[publish] Failed to dispatch event', {
         runId,
         channelId,
@@ -464,6 +565,12 @@ export async function startServer(options: ServerOptions = {}) {
         eventType: event.type,
         error,
       });
+
+      if (isUnknownAgent) {
+        res.status(400).json({ error: message });
+        return;
+      }
+
       res.status(500).json({ error: 'Failed to process publish event' });
     }
   });
@@ -480,6 +587,14 @@ export async function startServer(options: ServerOptions = {}) {
 
     const { channelId, threadId, agentId, runId } = getContext(req);
 
+    // In-memory active runs (not persisted). Mirrors the initial SSE frame on __global__.
+    if (channelId === GLOBAL_CHANNEL_ID && event.type === 'action:storage:get-active-runs') {
+      const snapshot = buildActiveRunsSnapshot();
+      ensureEventId(snapshot);
+      res.json({ events: [snapshot] });
+      return;
+    }
+
     if (event.type === 'action:storage:serve-file') {
       const filePath = (event.data as { path?: string })?.path;
       if (!channelId?.trim()) {

package/src/app/types.ts

@@ -141,6 +141,10 @@ export type GetEventsResultEvent = BaseEvent & {
   };
 };
 
+export type GetActiveRunsEvent = BaseEvent & {
+  type: 'action:storage:get-active-runs';
+};
+
 export type GetAgentDetailsEvent = BaseEvent & {
   type: 'action:storage:get-agent-details';
   data: {
@@ -1059,6 +1063,7 @@ export type OpenBotEvent =
   | DeleteAgentResultEvent
   | GetEventsEvent
   | GetEventsResultEvent
+  | GetActiveRunsEvent
   | StreamThreadEvent
   | GetVariablesEvent
   | GetVariablesResultEvent

package/src/plugins/storage/service.ts

@@ -24,6 +24,7 @@ import {
   PluginDescriptor,
   Thread,
   ThreadDetails,
+  ThreadState,
 } from '../../services/plugins/domain.js';
 import type { PluginRef } from '../../services/plugins/types.js';
 import { openbotPlugin } from '../openbot/index.js';
@@ -771,7 +772,7 @@ export const storageService = {
       id: threadId,
       name: threadName || threadId,
       channelId,
-      state,
+      state: (isRecord(state) ? state : {}) as ThreadState,
     };
   },
   getChannelDetails: async ({ channelId }: { channelId: string }): Promise<ChannelDetails> => {

package/src/services/plugins/domain.ts

@@ -81,11 +81,25 @@ export type Thread = {
   hasUnseenMessages?: boolean;
 };
 
+/** Persisted thread `state.json` fields (additional keys are allowed). */
+export type ThreadState = {
+  name?: string;
+  /** Sticky agent id for this thread (`system` = orchestrator). Set once, then enforced on publish. */
+  respondingAgentId?: string;
+  pendingToolCallIds?: string[];
+  usage?: {
+    promptTokens?: number;
+    completionTokens?: number;
+    totalTokens?: number;
+  };
+  [key: string]: unknown;
+};
+
 export type ThreadDetails = {
   id: string;
   name: string;
   channelId: string;
-  state: unknown;
+  state: ThreadState;
 };
 
 export type ChannelDetails = {