openbot 0.5.8 → 0.5.10

package/CLAUDE.md

@@ -31,7 +31,7 @@ OpenBot is a local-first, event-driven harness for running AI agents, built on t
 
 Core built-ins: `storage` (infra handlers for `/api/state`), `plugin-manager` (marketplace + npm plugin install). The default agent runtime is **`@meetopenbot/openbot`**, a community npm package installed to `~/.openbot/plugins/@meetopenbot/openbot/` on first boot (`ensureDefaultStack`). Disk-installed plugins take precedence over built-ins in `resolvePlugin`.
 
-A `Plugin`'s `factory(context)` returns a `MelonyPlugin`; `PluginContext` carries `agentId`, `agentDetails`, per-agent `config` (from `AGENT.md` frontmatter), the shared `storage` service, the merged `tools` map, `publicBaseUrl`, the run's `abortSignal`, and `host` (platform hooks: `runAgent`, cloud auth, model registry, config).
+A `Plugin`'s `factory(context)` returns a `MelonyPlugin`; `PluginContext` carries `agentId`, `agentDetails`, per-agent `config` (from `AGENT.md` frontmatter), the shared `storage` service, the merged `tools` map, `publicBaseUrl`, the run's `abortSignal`, and `host` (platform hooks: `runAgent`, cloud auth, config).
 
 ### Agents
 

package/dist/app/active-runs.js

@@ -0,0 +1,70 @@
+export function getRunKey(runId, agentId, channelId, threadId) {
+    return `${runId}:${agentId}:${channelId}:${threadId || ''}`;
+}
+export class ActiveRunsTracker {
+    constructor() {
+        this.runs = new Map();
+    }
+    trackStart(data) {
+        this.runs.set(getRunKey(data.runId, data.agentId, data.channelId, data.threadId), data);
+    }
+    trackEnd(data) {
+        this.runs.delete(getRunKey(data.runId, data.agentId, data.channelId, data.threadId));
+    }
+    buildSnapshot() {
+        const byBucket = new Map();
+        for (const run of this.runs.values()) {
+            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 },
+        };
+    }
+    /**
+     * Drop every tracked run for a channel/thread. Returns the purged records so
+     * callers can emit synthetic `agent:run:end` events to SSE clients.
+     */
+    purgeForThread(channelId, threadId) {
+        const target = threadId || undefined;
+        const removed = [];
+        for (const [key, run] of this.runs) {
+            if (run.channelId === channelId && (run.threadId || undefined) === target) {
+                removed.push(run);
+                this.runs.delete(key);
+            }
+        }
+        return removed;
+    }
+}

package/dist/app/cli.js

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

package/dist/app/lifecycle-events.js

@@ -0,0 +1,27 @@
+import { storageService } from '../plugins/storage/service.js';
+import { ensureEventId } from './utils.js';
+export function 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,
+        });
+    });
+}
+export function broadcastLifecycleEvent(event, channelId, threadId, deps, options) {
+    ensureEventId(event);
+    if (options?.persist !== false) {
+        persistLifecycleEvent(event, channelId, threadId);
+    }
+    deps.sendToClientKey(deps.getClientKey(channelId, threadId), event);
+    deps.sendToClientKey(deps.globalChannelId, event);
+}

package/dist/app/run-event-handler.js

@@ -0,0 +1,37 @@
+const LIFECYCLE_RUN_TYPES = new Set(['agent:run:start', 'agent:run:end', 'agent:run:stopped']);
+export function createRunEventHandler(deps) {
+    return async (chunk, state) => {
+        if (chunk.type === 'action:webhook:http-response' && deps.onWebhookHttpResponse) {
+            deps.onWebhookHttpResponse(chunk.data);
+            return;
+        }
+        const targetChannelId = state?.channelId || deps.defaultChannelId;
+        const targetThreadId = state?.threadId || deps.defaultThreadId;
+        if (chunk.type === 'agent:run:start' && chunk.data.channelId) {
+            deps.activeRuns.trackStart({
+                runId: chunk.data.runId,
+                channelId: chunk.data.channelId,
+                threadId: chunk.data.threadId,
+                agentId: chunk.data.agentId,
+            });
+        }
+        else if (chunk.type === 'agent:run:end' && chunk.data.channelId) {
+            deps.activeRuns.trackEnd({
+                runId: chunk.data.runId,
+                channelId: chunk.data.channelId,
+                threadId: chunk.data.threadId,
+                agentId: chunk.data.agentId,
+            });
+        }
+        else if (chunk.type === 'agent:run:stopped' && chunk.data.channelId) {
+            deps.onRunStopped?.(chunk.data.channelId, chunk.data.threadId);
+        }
+        if (targetChannelId) {
+            const targetClientKey = deps.getClientKey(targetChannelId, targetThreadId);
+            deps.sendToClientKey(targetClientKey, chunk);
+        }
+        if (LIFECYCLE_RUN_TYPES.has(chunk.type)) {
+            deps.sendToClientKey(deps.globalChannelId, chunk);
+        }
+    };
+}

package/dist/app/server.js

@@ -10,6 +10,9 @@ const pkg = require('../../package.json');
 import { generateId } from 'melony';
 import { getBaseDir, loadConfig } from '../app/config.js';
 import { isCloudMode } from './cloud-mode.js';
+import { ActiveRunsTracker } from './active-runs.js';
+import { broadcastLifecycleEvent } from './lifecycle-events.js';
+import { createRunEventHandler } from './run-event-handler.js';
 import { processService } from '../services/process.js';
 import { runAgent, STATE_AGENT_ID, ORCHESTRATOR_AGENT_ID } from '../harness/index.js';
 import { initPlugins } from '../services/plugins/registry.js';
@@ -18,7 +21,8 @@ import { buildWorkspaceFileUrl, getPublicBaseUrl, openChannelFileStream, } from
 import { ensureEventId, openBotEventFromQuery } from './utils.js';
 import { abortRegistry, abortKey } from '../services/abort.js';
 import { resolvePublishTargetAgentId, resolveRespondingAgentId } from './responding-agent.js';
-import { DEFAULT_UNCATEGORIZED_SPEC, UNCATEGORIZED_CHANNEL_ID, } from './channel-ids.js';
+import { DEFAULT_UNCATEGORIZED_SPEC, UNCATEGORIZED_CHANNEL_ID } from './channel-ids.js';
+import { pickWebhookHeaders, resolveWebhookAgentId, respondAgentDispatchError, sendWebhookHttpResponse, } from './webhook-routing.js';
 export async function startServer(options = {}) {
     const publishEventSchema = z
         .object({
@@ -38,19 +42,21 @@ export async function startServer(options = {}) {
     const app = express();
     const clients = new Map();
     const GLOBAL_CHANNEL_ID = '__global__';
-    const activeRuns = new Map();
+    const activeRunsTracker = new ActiveRunsTracker();
     const agentsDir = path.join(openBotDir, 'agents');
     const pluginsDir = path.join(openBotDir, 'plugins');
     await fs.mkdir(agentsDir, { recursive: true });
     await fs.mkdir(pluginsDir, { recursive: true });
     initPlugins(pluginsDir);
     // Pre-warm caches for agents and plugins to speed up first UI load
-    storageService.getAgents().catch((err) => console.warn('[server] Failed to pre-warm agents cache', err));
-    storageService.getPlugins().catch((err) => console.warn('[server] Failed to pre-warm plugins cache', err));
+    storageService
+        .getAgents()
+        .catch((err) => console.warn('[server] Failed to pre-warm agents cache', err));
+    storageService
+        .getPlugins()
+        .catch((err) => console.warn('[server] Failed to pre-warm plugins cache', err));
     const getRawChannelId = (req) => {
-        const raw = req.get('x-openbot-channel-id') ||
-            req.query.channelId ||
-            (req.body && req.body.channelId);
+        const raw = req.get('x-openbot-channel-id') || req.query.channelId || (req.body && req.body.channelId);
         if (typeof raw !== 'string')
             return undefined;
         const trimmed = raw.trim();
@@ -77,7 +83,6 @@ export async function startServer(options = {}) {
         };
     };
     const getClientKey = (channelId, threadId) => threadId ? `${channelId}:${threadId}` : channelId;
-    const getRunKey = (runId, agentId, channelId, threadId) => `${runId}:${agentId}:${channelId}:${threadId || ''}`;
     const sendToClientKey = (clientKey, chunk) => {
         const threadClients = clients.get(clientKey);
         if (!threadClients || threadClients.length === 0)
@@ -87,7 +92,9 @@ export async function startServer(options = {}) {
             const parts = clientKey.split(':');
             const channelId = parts[0];
             const threadId = parts[1]; // undefined if no ":"
-            storageService.setLastRead({ channelId, threadId, lastReadEventId: chunk.id }).catch(() => { });
+            storageService
+                .setLastRead({ channelId, threadId, lastReadEventId: chunk.id })
+                .catch(() => { });
         }
         threadClients.forEach((client) => {
             if (!client.writableEnded) {
@@ -95,64 +102,16 @@ export async function startServer(options = {}) {
             }
         });
     };
-    const buildActiveRunsSnapshot = () => {
-        const byBucket = new Map();
-        for (const run of activeRuns.values()) {
-            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 },
-        };
+    const lifecycleDeps = {
+        sendToClientKey,
+        getClientKey,
+        globalChannelId: GLOBAL_CHANNEL_ID,
     };
     const broadcastActiveRunsSnapshot = () => {
-        const snapshot = buildActiveRunsSnapshot();
+        const snapshot = activeRunsTracker.buildSnapshot();
         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
@@ -160,15 +119,7 @@ export async function startServer(options = {}) {
     // `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) {
+        for (const run of activeRunsTracker.purgeForThread(channelId, threadId)) {
             const endEvent = {
                 type: 'agent:run:end',
                 data: {
@@ -178,12 +129,13 @@ export async function startServer(options = {}) {
                     threadId: run.threadId,
                 },
             };
-            ensureEventId(endEvent);
-            persistLifecycleEvent(endEvent, run.channelId, run.threadId);
-            sendToClientKey(getClientKey(run.channelId, run.threadId), endEvent);
-            sendToClientKey(GLOBAL_CHANNEL_ID, endEvent);
+            broadcastLifecycleEvent(endEvent, run.channelId, run.threadId, lifecycleDeps);
         }
     };
+    const handleRunStopped = (channelId, threadId) => {
+        purgeActiveRunsForThread(channelId, threadId);
+        broadcastActiveRunsSnapshot();
+    };
     // Support for Chrome's Private Network Access (PNA)
     // https://developer.chrome.com/blog/private-network-access-preflight/
     app.use((req, res, next) => {
@@ -200,7 +152,9 @@ export async function startServer(options = {}) {
     const gatewayToken = process.env.OPENBOT_GATEWAY_TOKEN?.trim();
     if (gatewayToken) {
         app.use((req, res, next) => {
-            if (req.path === '/api/health' || req.method === 'OPTIONS') {
+            if (req.path === '/api/health' ||
+                req.method === 'OPTIONS' ||
+                req.path.startsWith('/api/webhooks/')) {
                 next();
                 return;
             }
@@ -217,8 +171,9 @@ export async function startServer(options = {}) {
         const isWorkspaceUpload = req.method === 'POST' &&
             req.path === '/api/publish' &&
             req.get('x-openbot-event-type') === 'action:storage:upload-file';
-        if (isWorkspaceUpload) {
-            express.raw({ type: () => true, limit: '100mb' })(req, res, next);
+        const isWebhook = req.method === 'POST' && req.path.startsWith('/api/webhooks/');
+        if (isWorkspaceUpload || isWebhook) {
+            express.raw({ type: () => true, limit: isWebhook ? '5mb' : '100mb' })(req, res, next);
             return;
         }
         express.json({ limit: '20mb' })(req, res, next);
@@ -259,7 +214,7 @@ export async function startServer(options = {}) {
                 .catch(() => { });
         }
         if (channelId === GLOBAL_CHANNEL_ID) {
-            const snapshot = buildActiveRunsSnapshot();
+            const snapshot = activeRunsTracker.buildSnapshot();
             ensureEventId(snapshot);
             res.write(`data: ${JSON.stringify(snapshot)}\n\n`);
         }
@@ -429,38 +384,19 @@ export async function startServer(options = {}) {
                 },
             };
             ensureEventId(stoppedEvent);
-            persistLifecycleEvent(stoppedEvent, targetChannelId, targetThreadId);
-            sendToClientKey(getClientKey(targetChannelId, targetThreadId), stoppedEvent);
-            sendToClientKey(GLOBAL_CHANNEL_ID, stoppedEvent);
+            broadcastLifecycleEvent(stoppedEvent, targetChannelId, targetThreadId, lifecycleDeps);
             res.json({ success: stopped });
             return;
         }
-        const onEvent = async (chunk, state) => {
-            const targetChannelId = state?.channelId || channelId;
-            const targetThreadId = state?.threadId || threadId;
-            const targetClientKey = getClientKey(targetChannelId, targetThreadId);
-            if (chunk.type === 'agent:run:start') {
-                activeRuns.set(getRunKey(chunk.data.runId, chunk.data.agentId, chunk.data.channelId, chunk.data.threadId), {
-                    runId: chunk.data.runId,
-                    channelId: chunk.data.channelId,
-                    threadId: chunk.data.threadId,
-                    agentId: chunk.data.agentId,
-                });
-            }
-            else if (chunk.type === 'agent:run:end') {
-                activeRuns.delete(getRunKey(chunk.data.runId, chunk.data.agentId, chunk.data.channelId, chunk.data.threadId));
-            }
-            else if (chunk.type === 'agent:run:stopped') {
-                purgeActiveRunsForThread(chunk.data.channelId, chunk.data.threadId);
-                broadcastActiveRunsSnapshot();
-            }
-            sendToClientKey(targetClientKey, chunk);
-            if (chunk.type === 'agent:run:start' ||
-                chunk.type === 'agent:run:end' ||
-                chunk.type === 'agent:run:stopped') {
-                sendToClientKey(GLOBAL_CHANNEL_ID, chunk);
-            }
-        };
+        const onEvent = createRunEventHandler({
+            defaultChannelId: channelId,
+            defaultThreadId: threadId,
+            activeRuns: activeRunsTracker,
+            sendToClientKey,
+            getClientKey,
+            globalChannelId: GLOBAL_CHANNEL_ID,
+            onRunStopped: handleRunStopped,
+        });
         try {
             ensureEventId(event);
             const isUserConversationStart = event.type === 'agent:invoke' &&
@@ -490,20 +426,16 @@ export async function startServer(options = {}) {
             await runAgent({
                 runId,
                 agentId: target.agentId,
-                event,
-                channelId,
-                threadId,
+                event: {
+                    ...event,
+                    meta: { ...event.meta, channelId, threadId },
+                },
                 publicBaseUrl: resolvePublicBaseUrl(),
                 onEvent,
             });
             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,
@@ -511,11 +443,82 @@ export async function startServer(options = {}) {
                 eventType: event.type,
                 error,
             });
-            if (isUnknownAgent) {
-                res.status(400).json({ error: message });
+            respondAgentDispatchError(res, error, 'Failed to process publish event');
+        }
+    });
+    const WEBHOOK_TIMEOUT_MS = Number(process.env.OPENBOT_WEBHOOK_TIMEOUT_MS ?? 30000);
+    app.post('/api/webhooks/:provider', async (req, res) => {
+        const provider = req.params.provider?.trim();
+        if (!provider || !/^[a-z0-9][a-z0-9_-]*$/i.test(provider)) {
+            res.status(400).json({ error: 'Invalid webhook provider' });
+            return;
+        }
+        const rawBody = Buffer.isBuffer(req.body) ? req.body : Buffer.alloc(0);
+        const runId = `run_${generateId()}`;
+        const agentId = await resolveWebhookAgentId(provider);
+        let httpResponse = null;
+        const onEvent = createRunEventHandler({
+            activeRuns: activeRunsTracker,
+            sendToClientKey,
+            getClientKey,
+            globalChannelId: GLOBAL_CHANNEL_ID,
+            onRunStopped: handleRunStopped,
+            onWebhookHttpResponse: (response) => {
+                httpResponse = response;
+            },
+        });
+        const event = {
+            type: 'action:webhook',
+            data: {
+                provider,
+                rawBody: rawBody.toString('base64'),
+                headers: pickWebhookHeaders(req),
+                query: req.query,
+            },
+        };
+        try {
+            ensureEventId(event);
+            console.log('runAgent', {
+                runId,
+                agentId,
+                event,
+                persistEvents: true,
+                publicBaseUrl: resolvePublicBaseUrl(),
+                onEvent,
+            });
+            const runPromise = runAgent({
+                runId,
+                agentId,
+                event,
+                persistEvents: true,
+                publicBaseUrl: resolvePublicBaseUrl(),
+                onEvent,
+            });
+            let timeoutId;
+            const timeoutPromise = new Promise((_, reject) => {
+                timeoutId = setTimeout(() => reject(new Error('webhook_timeout')), WEBHOOK_TIMEOUT_MS);
+            });
+            try {
+                await Promise.race([runPromise, timeoutPromise]);
+            }
+            finally {
+                if (timeoutId)
+                    clearTimeout(timeoutId);
+            }
+            sendWebhookHttpResponse(res, httpResponse ?? { status: 200, body: {} });
+        }
+        catch (error) {
+            const isTimeout = error instanceof Error && error.message === 'webhook_timeout';
+            console.error('[webhook] Failed to process inbound webhook', {
+                provider,
+                agentId,
+                error,
+            });
+            if (isTimeout) {
+                res.status(504).json({ error: 'Webhook handler timed out' });
                 return;
             }
-            res.status(500).json({ error: 'Failed to process publish event' });
+            respondAgentDispatchError(res, error, 'Failed to process webhook');
         }
     });
     app.get('/api/state', async (req, res) => {
@@ -531,7 +534,7 @@ export async function startServer(options = {}) {
         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();
+            const snapshot = activeRunsTracker.buildSnapshot();
             ensureEventId(snapshot);
             res.json({ events: [snapshot] });
             return;
@@ -572,9 +575,10 @@ export async function startServer(options = {}) {
             await runAgent({
                 runId,
                 agentId: agentId || STATE_AGENT_ID,
-                event,
-                channelId,
-                threadId,
+                event: {
+                    ...event,
+                    meta: { ...event.meta, channelId, threadId },
+                },
                 persistEvents: false,
                 publicBaseUrl: resolvePublicBaseUrl(),
                 onEvent,

package/dist/app/slack-webhook.js

@@ -0,0 +1,81 @@
+/** Webhook provider id for `POST /api/webhooks/slack`. */
+export const SLACK_WEBHOOK_PROVIDER = 'slack';
+const SLACK_CHANNEL_ID_PREFIX = 'slack-';
+/** Map a Slack `channel` id to a stable OpenBot channel id. */
+export function slackChannelToOpenBotChannelId(slackChannelId) {
+    const normalized = slackChannelId.trim();
+    if (!normalized) {
+        throw new Error('slackChannelId is required');
+    }
+    return `${SLACK_CHANNEL_ID_PREFIX}${normalized}`;
+}
+const isRecord = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const readString = (value) => {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed || undefined;
+};
+/**
+ * Best-effort parse of a Slack Events API payload for routing and plugin handling.
+ * Returns `null` when the body is not JSON or not a recognized Slack envelope.
+ */
+export function parseSlackWebhookPayload(rawBody) {
+    if (rawBody.length === 0)
+        return null;
+    let payload;
+    try {
+        payload = JSON.parse(rawBody.toString('utf-8'));
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(payload))
+        return null;
+    const envelopeType = readString(payload.type);
+    if (envelopeType === 'url_verification') {
+        const challenge = readString(payload.challenge);
+        if (!challenge)
+            return null;
+        return { kind: 'url_verification', challenge };
+    }
+    if (envelopeType !== 'event_callback')
+        return null;
+    const event = payload.event;
+    if (!isRecord(event))
+        return null;
+    const eventType = readString(event.type);
+    if (eventType !== 'message') {
+        return { kind: 'ignored', reason: `unsupported_event_type:${eventType || 'unknown'}` };
+    }
+    const subtype = readString(event.subtype);
+    if (subtype && subtype !== 'file_share') {
+        return { kind: 'ignored', reason: `message_subtype:${subtype}` };
+    }
+    if (readString(event.bot_id) || readString(event.bot_profile)) {
+        return { kind: 'ignored', reason: 'bot_message' };
+    }
+    const slackChannelId = readString(event.channel);
+    if (!slackChannelId) {
+        return { kind: 'ignored', reason: 'missing_channel' };
+    }
+    const text = readString(event.text) || (subtype === 'file_share' ? '[file shared]' : undefined);
+    if (!text) {
+        return { kind: 'ignored', reason: 'empty_text' };
+    }
+    return {
+        kind: 'message',
+        slackChannelId,
+        threadTs: readString(event.thread_ts),
+        messageTs: readString(event.ts),
+        userId: readString(event.user),
+        text,
+    };
+}
+/** Resolve the OpenBot thread id for a Slack message (`thread_ts` or root `ts`). */
+export function slackMessageToOpenBotThreadId(message) {
+    return message.threadTs || message.messageTs;
+}
+export function slackChannelSpec(slackChannelId) {
+    return `# Slack ${slackChannelId}\n\nInbound messages from Slack channel \`${slackChannelId}\`.`;
+}

package/dist/app/webhook-routing.js

@@ -0,0 +1,52 @@
+import { ORCHESTRATOR_AGENT_ID } from '../harness/index.js';
+import { storageService } from '../plugins/storage/service.js';
+/** Default agent when no `agents/<provider>/AGENT.md` exists. */
+export const WEBHOOK_AGENT_FALLBACK_ID = ORCHESTRATOR_AGENT_ID;
+export const isAgentNotFound = (error) => error instanceof Error &&
+    (error.code === 'AGENT_NOT_FOUND' ||
+        error.message.includes('does not exist'));
+export function respondAgentDispatchError(res, error, fallbackMessage) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (isAgentNotFound(error) || message.includes('does not exist')) {
+        res.status(400).json({ error: message });
+        return;
+    }
+    res.status(500).json({ error: fallbackMessage });
+}
+/**
+ * Routes `POST /api/webhooks/:provider` to agent `<provider>` when that agent exists,
+ * otherwise falls back to {@link WEBHOOK_AGENT_FALLBACK_ID}.
+ */
+export async function resolveWebhookAgentId(provider) {
+    try {
+        await storageService.getAgentDetails({ agentId: provider });
+        return provider;
+    }
+    catch (error) {
+        if (isAgentNotFound(error)) {
+            return WEBHOOK_AGENT_FALLBACK_ID;
+        }
+        throw error;
+    }
+}
+/** Copy request headers for plugin-side signature verification. */
+export function pickWebhookHeaders(req) {
+    return { ...req.headers };
+}
+export function sendWebhookHttpResponse(res, out) {
+    if (out.headers) {
+        for (const [key, value] of Object.entries(out.headers)) {
+            res.setHeader(key, value);
+        }
+    }
+    const status = out.status;
+    if (out.body === undefined) {
+        res.sendStatus(status);
+        return;
+    }
+    if (typeof out.body === 'string') {
+        res.status(status).send(out.body);
+        return;
+    }
+    res.status(status).json(out.body);
+}