@pellux/goodvibes-tui 0.18.4

package/src/adapters/signal/index.ts

@@ -0,0 +1,92 @@
+import { parseJsonRecord, readBearerOrHeaderToken, readTextBodyWithinLimit } from '@pellux/goodvibes-sdk/platform/adapters/helpers';
+import type { SurfaceAdapterContext } from '../types.ts';
+
+function readRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' ? value as Record<string, unknown> : null;
+}
+
+function readString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+export async function handleSignalSurfaceWebhook(req: Request, context: SurfaceAdapterContext): Promise<Response> {
+  const configuredToken =
+    String(context.configManager.get('surfaces.signal.token') ?? '')
+    || await context.serviceRegistry.resolveSecret('signal', 'primary')
+    || process.env.SIGNAL_BRIDGE_TOKEN
+    || '';
+  if (configuredToken) {
+    const providedToken = readBearerOrHeaderToken(req, 'x-goodvibes-signal-token');
+    if (providedToken !== configuredToken) {
+      return Response.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+  }
+  const rawBody = await readTextBodyWithinLimit(req);
+  if (rawBody instanceof Response) return rawBody;
+  const body = parseJsonRecord(rawBody);
+  if (body instanceof Response) return body;
+  const payload = readRecord(body);
+  if (!payload) return Response.json({ error: 'Invalid JSON body' }, { status: 400 });
+  const recipient = readString(payload.recipient) ?? readString(payload.source) ?? readString(payload.phoneNumber);
+  const message = readString(payload.message) ?? readString(payload.text) ?? '';
+  if (!recipient) return Response.json({ error: 'Missing recipient/source' }, { status: 400 });
+
+  const policy = await context.authorizeSurfaceIngress({
+    surface: 'signal',
+    userId: recipient,
+    channelId: recipient,
+    groupId: recipient,
+    threadId: readString(payload.threadId),
+    conversationKind: readString(payload.threadId) ? 'thread' : 'direct',
+    text: message,
+    mentioned: true,
+    metadata: payload,
+  });
+  if (!policy.allowed) {
+    return Response.json({ error: `Blocked by channel policy: ${policy.reason}` }, { status: 403 });
+  }
+
+  const binding = await context.routeBindings.upsertBinding({
+    kind: readString(payload.threadId) ? 'thread' : 'channel',
+    surfaceKind: 'signal',
+    surfaceId: readString(payload.account) ?? readString(context.configManager.get('surfaces.signal.account')) ?? 'signal',
+    externalId: readString(payload.threadId) ?? recipient,
+    channelId: recipient,
+    threadId: readString(payload.threadId),
+    title: recipient,
+    metadata: { ...payload },
+  });
+  if (!message) {
+    return Response.json({ acknowledged: true, queued: false, bindingId: binding.id });
+  }
+
+  const submission = await context.sessionBroker.submitMessage({
+    routeId: binding.id,
+    surfaceKind: 'signal',
+    surfaceId: binding.surfaceId,
+    externalId: binding.externalId,
+    threadId: binding.threadId ?? binding.channelId,
+    userId: recipient,
+    displayName: recipient,
+    title: recipient,
+    body: message,
+    metadata: payload,
+  });
+  if (submission.mode === 'continued-live') {
+    return Response.json({ acknowledged: true, continued: true, sessionId: submission.session.id, agentId: submission.activeAgentId ?? null });
+  }
+
+  const spawnResult = context.trySpawnAgent(
+    { mode: 'spawn', task: submission.task! },
+    'handleSignalSurfaceWebhook',
+    submission.session.id,
+  );
+  if (spawnResult instanceof Response) return spawnResult;
+  await context.sessionBroker.bindAgent(submission.session.id, spawnResult.id);
+  context.queueSurfaceReplyFromBinding(submission.routeBinding ?? binding, {
+    agentId: spawnResult.id,
+    task: message,
+    sessionId: submission.session.id,
+  });
+  return Response.json({ acknowledged: true, queued: true, bindingId: binding.id, sessionId: submission.session.id, agentId: spawnResult.id });
+}

package/src/adapters/slack/index.ts

@@ -0,0 +1,323 @@
+import { logger } from '@pellux/goodvibes-sdk/platform/utils/logger';
+import { SlackIntegration } from '../../integrations/index.ts';
+import type { SurfaceAdapterContext } from '../types.ts';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
+
+export async function handleSlackSurfaceWebhook(req: Request, context: SurfaceAdapterContext): Promise<Response> {
+  const contentLength = parseInt(req.headers.get('content-length') ?? '0', 10);
+  if (contentLength > 1_000_000) {
+    return Response.json({ error: 'Payload too large' }, { status: 413 });
+  }
+
+  const signingSecret =
+    await context.serviceRegistry.resolveSecret('slack', 'signingSecret')
+    ?? process.env.SLACK_SIGNING_SECRET;
+  if (!signingSecret) {
+    logger.warn('handleSlackSurfaceWebhook: SLACK_SIGNING_SECRET not set — rejecting');
+    return Response.json({ error: 'Webhook not configured' }, { status: 503 });
+  }
+
+  const timestamp = req.headers.get('x-slack-request-timestamp') ?? '';
+  const signature = req.headers.get('x-slack-signature') ?? '';
+  const rawBody = await req.text();
+
+  const slack = new SlackIntegration(
+    await context.serviceRegistry.resolveSecret('slack', 'webhookUrl') ?? process.env.SLACK_WEBHOOK_URL,
+    await context.serviceRegistry.resolveSecret('slack', 'primary') ?? process.env.SLACK_BOT_TOKEN,
+  );
+
+  if (!slack.verifySignature(rawBody, timestamp, signature, signingSecret)) {
+    logger.warn('handleSlackSurfaceWebhook: invalid signature');
+    return Response.json({ error: 'Invalid signature' }, { status: 401 });
+  }
+
+  let bodyRecord: Record<string, unknown>;
+  const contentType = req.headers.get('content-type') ?? '';
+  if (contentType.includes('application/json')) {
+    try {
+      bodyRecord = JSON.parse(rawBody) as Record<string, unknown>;
+    } catch {
+      return Response.json({ error: 'Invalid JSON body' }, { status: 400 });
+    }
+  } else {
+    bodyRecord = Object.fromEntries(new URLSearchParams(rawBody));
+  }
+
+  if (bodyRecord.type === 'url_verification') {
+    return Response.json({ challenge: bodyRecord.challenge });
+  }
+
+  return handleSlackSurfacePayload(bodyRecord, context, slack, req);
+}
+
+export async function handleSlackSurfacePayload(
+  bodyRecord: Record<string, unknown>,
+  context: SurfaceAdapterContext,
+  slack = new SlackIntegration(),
+  req: Request = new Request('http://goodvibes.local/webhook/slack', { method: 'POST' }),
+): Promise<Response> {
+  const event = slack.parseEvent(bodyRecord);
+  if (event.type === 'slash_command') {
+    const task = event.text.trim();
+    const policy = await context.authorizeSurfaceIngress({
+      surface: 'slack',
+      userId: event.userId,
+      channelId: event.channelId,
+      groupId: event.channelId,
+      conversationKind: 'channel',
+      text: task,
+      mentioned: true,
+      metadata: {
+        command: event.command,
+        userName: event.userName,
+      },
+    });
+    if (!policy.allowed) {
+      return Response.json({
+        response_type: 'ephemeral',
+        text: `Blocked by channel policy: ${policy.reason}`,
+      }, { status: 403 });
+    }
+
+    const binding = await context.routeBindings.upsertBinding({
+      kind: 'channel',
+      surfaceKind: 'slack',
+      surfaceId: event.teamId || 'slack',
+      externalId: event.channelId,
+      channelId: event.channelId,
+      title: event.channelName || event.command,
+      metadata: {
+        command: event.command,
+        userId: event.userId,
+        userName: event.userName,
+        responseUrl: event.responseUrl,
+      },
+    });
+    if (!task) {
+      return Response.json({
+        response_type: 'ephemeral',
+        text: 'Usage: `/goodvibes <your prompt>`',
+      });
+    }
+
+    const controlCommand = context.parseSurfaceControlCommand(task);
+    if (controlCommand) {
+      const message = await context.performSurfaceControlCommand(controlCommand);
+      return Response.json({
+        response_type: 'ephemeral',
+        text: message,
+      });
+    }
+
+    let responseUrl: string | undefined = event.responseUrl;
+    if (responseUrl && !responseUrl.startsWith('https://hooks.slack.com/')) {
+      logger.warn('handleSlackSurfaceWebhook: suspicious responseUrl, ignoring');
+      responseUrl = undefined;
+    }
+    setImmediate(() => {
+      void (async () => {
+        const submission = await context.sessionBroker.submitMessage({
+          routeId: binding.id,
+          surfaceKind: 'slack',
+          surfaceId: binding.surfaceId,
+          externalId: event.channelId,
+          threadId: event.channelId,
+          userId: event.userId,
+          displayName: event.userName,
+          title: event.channelName || event.command,
+          body: task,
+          metadata: {
+            command: event.command,
+            responseUrl,
+          },
+        });
+        if (submission.mode === 'continued-live') {
+          if (responseUrl) {
+            await fetch(responseUrl, {
+              method: 'POST',
+              headers: { 'Content-Type': 'application/json' },
+              body: JSON.stringify({
+                response_type: 'in_channel',
+                text: `Continuing session ${submission.session.id} via agent ${submission.activeAgentId}.`,
+              }),
+            }).catch(() => {});
+          }
+          return;
+        }
+
+        const spawnResult = context.trySpawnAgent(
+          { mode: 'spawn', task: submission.task! },
+          'handleSlackSurfaceWebhook',
+          submission.session.id,
+        );
+        if (spawnResult instanceof Response) {
+          const payload = await spawnResult.json() as { error?: string };
+          const message = payload.error ?? 'Agent spawn failed';
+          logger.error('handleSlackSurfaceWebhook: spawn failed', { error: message });
+          if (responseUrl) {
+            await fetch(responseUrl, {
+              method: 'POST',
+              headers: { 'Content-Type': 'application/json' },
+              body: JSON.stringify({
+                response_type: 'in_channel',
+                text: `Agent spawn failed: ${message}`,
+              }),
+            }).catch(() => {});
+          }
+          return;
+        }
+
+        await context.sessionBroker.bindAgent(submission.session.id, spawnResult.id);
+        context.queueSurfaceReplyFromBinding(submission.routeBinding ?? binding, {
+          agentId: spawnResult.id,
+          task,
+          sessionId: submission.session.id,
+        });
+        if (responseUrl) {
+          await fetch(responseUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+              response_type: 'in_channel',
+              blocks: slack.formatAgentResult(
+                spawnResult.id,
+                task,
+                `Session ${submission.session.id} active. Agent ${spawnResult.id} will reply in-channel when complete.`,
+              ),
+            }),
+          }).catch((error: unknown) => {
+            logger.warn('handleSlackSurfaceWebhook: follow-up post failed', {
+              error: summarizeError(error),
+            });
+          });
+        }
+      })();
+    });
+
+    return Response.json({
+      response_type: 'in_channel',
+      text: `Running: _${task}_`,
+    });
+  }
+
+  if (event.type === 'event_callback') {
+    if (event.eventType !== 'app_mention' && event.eventType !== 'message') {
+      return new Response(null, { status: 200 });
+    }
+    const task = event.text.trim();
+    if (!task) return new Response(null, { status: 200 });
+    const mentioned = event.eventType === 'app_mention' || /<@[A-Z0-9]+>/i.test(task);
+    const policy = await context.authorizeSurfaceIngress({
+      surface: 'slack',
+      userId: event.userId,
+      channelId: event.channelId,
+      groupId: event.channelId,
+      threadId: event.threadTs ?? event.eventTs,
+      workspaceId: event.teamId,
+      conversationKind: event.threadTs ? 'thread' : 'channel',
+      text: task,
+      mentioned,
+      metadata: {
+        eventType: event.eventType,
+        eventTs: event.eventTs,
+      },
+    });
+    if (!policy.allowed) {
+      return Response.json({ ok: false, error: `Blocked by channel policy: ${policy.reason}` }, { status: 403 });
+    }
+    const binding = await context.routeBindings.upsertBinding({
+      kind: event.threadTs ? 'thread' : 'channel',
+      surfaceKind: 'slack',
+      surfaceId: event.teamId || 'slack',
+      externalId: event.threadTs ?? event.channelId,
+      channelId: event.channelId,
+      threadId: event.threadTs,
+      title: `Slack ${event.eventType}`,
+      metadata: {
+        userId: event.userId,
+        eventType: event.eventType,
+        eventTs: event.eventTs,
+      },
+    });
+    const submission = await context.sessionBroker.submitMessage({
+      routeId: binding.id,
+      surfaceKind: 'slack',
+      surfaceId: binding.surfaceId,
+      externalId: binding.externalId,
+      threadId: binding.threadId ?? binding.channelId,
+      userId: event.userId,
+      displayName: event.userId,
+      title: `Slack ${event.eventType}`,
+      body: task,
+      metadata: {
+        eventType: event.eventType,
+        eventTs: event.eventTs,
+      },
+    });
+    if (submission.mode === 'continued-live') {
+      return Response.json({
+        ok: true,
+        continued: true,
+        sessionId: submission.session.id,
+        agentId: submission.activeAgentId,
+      });
+    }
+    const spawnResult = context.trySpawnAgent(
+      { mode: 'spawn', task: submission.task! },
+      'handleSlackSurfacePayload',
+      submission.session.id,
+    );
+    if (spawnResult instanceof Response) return spawnResult;
+    await context.sessionBroker.bindAgent(submission.session.id, spawnResult.id);
+    context.queueSurfaceReplyFromBinding(submission.routeBinding ?? binding, {
+      agentId: spawnResult.id,
+      task,
+      sessionId: submission.session.id,
+    });
+    return Response.json({
+      ok: true,
+      queued: true,
+      sessionId: submission.session.id,
+      agentId: spawnResult.id,
+    });
+  }
+
+  const actionPayload = event.payload;
+  const actionId = Array.isArray(actionPayload.actions)
+    ? (() => {
+        const first = actionPayload.actions[0] as Record<string, unknown> | undefined;
+        return typeof first?.action_id === 'string' ? first.action_id : '';
+      })()
+    : '';
+  if (actionId) {
+    const policy = await context.authorizeSurfaceIngress({
+      surface: 'slack',
+      userId: typeof (actionPayload.user as Record<string, unknown> | undefined)?.id === 'string'
+        ? (actionPayload.user as Record<string, unknown>).id as string
+        : undefined,
+      channelId: typeof (actionPayload.channel as Record<string, unknown> | undefined)?.id === 'string'
+        ? (actionPayload.channel as Record<string, unknown>).id as string
+        : undefined,
+      groupId: typeof (actionPayload.channel as Record<string, unknown> | undefined)?.id === 'string'
+        ? (actionPayload.channel as Record<string, unknown>).id as string
+        : undefined,
+      conversationKind: 'channel',
+      text: actionId,
+      mentioned: true,
+      metadata: { interactive: true },
+    });
+    if (!policy.allowed) {
+      return Response.json({
+        response_type: 'ephemeral',
+        text: `Blocked by channel policy: ${policy.reason}`,
+      }, { status: 403 });
+    }
+    const message = await context.performInteractiveSurfaceAction(actionId, 'slack', req);
+    return Response.json({
+      response_type: 'ephemeral',
+      text: message,
+    });
+  }
+
+  return new Response(null, { status: 200 });
+}

package/src/adapters/telegram/index.ts

@@ -0,0 +1,160 @@
+import type { SurfaceAdapterContext } from '../types.ts';
+
+function readRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' ? value as Record<string, unknown> : null;
+}
+
+function readString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+function readNumberString(value: unknown): string | undefined {
+  if (typeof value === 'number' && Number.isFinite(value)) return String(value);
+  return readString(value);
+}
+
+function extractTelegramTask(message: Record<string, unknown>, botUsername?: string): string {
+  const text = readString(message.text) ?? readString(message.caption) ?? '';
+  if (!text) return '';
+  const trimmed = text.trim();
+  const botHandle = botUsername ? botUsername.replace(/^@/, '') : '';
+  const commandPattern = botHandle
+    ? new RegExp(`^/goodvibes(?:@${botHandle})?\\s*`, 'i')
+    : /^\/goodvibes\s*/i;
+  return trimmed.replace(commandPattern, '').trim();
+}
+
+function telegramConversationKind(chatType?: string, threadId?: string): import('../../channels/index.ts').ChannelConversationKind {
+  if (threadId) return 'thread';
+  if (chatType === 'private') return 'direct';
+  if (chatType === 'channel') return 'channel';
+  return 'group';
+}
+
+export async function handleTelegramSurfaceWebhook(req: Request, context: SurfaceAdapterContext): Promise<Response> {
+  const contentLength = parseInt(req.headers.get('content-length') ?? '0', 10);
+  if (contentLength > 1_000_000) {
+    return Response.json({ error: 'Payload too large' }, { status: 413 });
+  }
+  const configuredSecret =
+    String(context.configManager.get('surfaces.telegram.webhookSecret') ?? '')
+    || await context.serviceRegistry.resolveSecret('telegram', 'signingSecret')
+    || process.env.TELEGRAM_WEBHOOK_SECRET
+    || '';
+  if (configuredSecret) {
+    const providedSecret = req.headers.get('x-telegram-bot-api-secret-token') ?? '';
+    if (providedSecret !== configuredSecret) {
+      return Response.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+  }
+  const body = await req.json().catch(() => null);
+  const payload = readRecord(body);
+  if (!payload) return Response.json({ error: 'Invalid JSON body' }, { status: 400 });
+
+  const message = readRecord(payload.message)
+    ?? readRecord(payload.edited_message)
+    ?? readRecord(payload.channel_post)
+    ?? readRecord(payload.edited_channel_post);
+  if (!message) {
+    return Response.json({ ok: true, ignored: true });
+  }
+
+  const chat = readRecord(message.chat);
+  const from = readRecord(message.from);
+  const chatId = readNumberString(chat?.id);
+  if (!chatId) return Response.json({ ok: true, ignored: true });
+  const threadId = readNumberString(message.message_thread_id);
+  const botUsername = readString(context.configManager.get('surfaces.telegram.botUsername'));
+  const task = extractTelegramTask(message, botUsername);
+  const text = readString(message.text) ?? readString(message.caption) ?? '';
+  const mentioned = Boolean(
+    (chat?.type === 'private')
+    || /^\/goodvibes\b/i.test(text)
+    || (botUsername && new RegExp(`@${botUsername.replace(/^@/, '')}\\b`, 'i').test(text)),
+  );
+  const policy = await context.authorizeSurfaceIngress({
+    surface: 'telegram',
+    userId: readNumberString(from?.id),
+    channelId: chatId,
+    groupId: chatId,
+    threadId,
+    workspaceId: readString(chat?.username),
+    conversationKind: telegramConversationKind(readString(chat?.type), threadId),
+    text: task || text,
+    mentioned,
+    metadata: {
+      updateId: readNumberString(payload.update_id),
+      chatType: readString(chat?.type),
+      chatTitle: readString(chat?.title),
+      fromUsername: readString(from?.username),
+    },
+  });
+  if (!policy.allowed) {
+    return Response.json({ ok: false, error: `Blocked by channel policy: ${policy.reason}` }, { status: 403 });
+  }
+
+  const binding = await context.routeBindings.upsertBinding({
+    kind: threadId ? 'thread' : 'channel',
+    surfaceKind: 'telegram',
+    surfaceId: botUsername || 'telegram',
+    externalId: threadId ?? chatId,
+    channelId: chatId,
+    threadId,
+    title: readString(chat?.title) ?? readString(chat?.username) ?? chatId,
+    metadata: {
+      chatType: readString(chat?.type),
+      fromId: readNumberString(from?.id),
+      fromUsername: readString(from?.username),
+      updateId: readNumberString(payload.update_id),
+    },
+  });
+
+  if (!task) {
+    return Response.json({ ok: true, acknowledged: true, bindingId: binding.id });
+  }
+
+  const controlCommand = context.parseSurfaceControlCommand(task);
+  if (controlCommand) {
+    const message = await context.performSurfaceControlCommand(controlCommand);
+    return Response.json({ ok: true, acknowledged: true, message });
+  }
+
+  const submission = await context.sessionBroker.submitMessage({
+    routeId: binding.id,
+    surfaceKind: 'telegram',
+    surfaceId: binding.surfaceId,
+    externalId: binding.externalId,
+    threadId: binding.threadId ?? binding.channelId,
+    userId: readNumberString(from?.id),
+    displayName: readString(from?.username) ?? readString(from?.first_name),
+    title: binding.title ?? 'Telegram',
+    body: task,
+    metadata: {
+      chatType: readString(chat?.type),
+      updateId: readNumberString(payload.update_id),
+    },
+  });
+  if (submission.mode === 'continued-live') {
+    return Response.json({ ok: true, continued: true, sessionId: submission.session.id, agentId: submission.activeAgentId ?? null });
+  }
+
+  const spawnResult = context.trySpawnAgent(
+    { mode: 'spawn', task: submission.task! },
+    'handleTelegramSurfaceWebhook',
+    submission.session.id,
+  );
+  if (spawnResult instanceof Response) return spawnResult;
+  await context.sessionBroker.bindAgent(submission.session.id, spawnResult.id);
+  context.queueSurfaceReplyFromBinding(submission.routeBinding ?? binding, {
+    agentId: spawnResult.id,
+    task,
+    sessionId: submission.session.id,
+  });
+  return Response.json({
+    ok: true,
+    queued: true,
+    bindingId: binding.id,
+    sessionId: submission.session.id,
+    agentId: spawnResult.id,
+  });
+}

package/src/adapters/types.ts

@@ -0,0 +1,97 @@
+import type { AgentManager } from '../tools/agent/index.ts';
+import type { AgentRecord } from '../tools/agent/index.ts';
+import type { AutomationRouteBinding } from '@pellux/goodvibes-sdk/platform/automation/routes';
+import type { AutomationSurfaceKind } from '@pellux/goodvibes-sdk/platform/automation/types';
+import type { ChannelConversationKind, ChannelPolicyDecision, RouteBindingManager } from '../channels/index.ts';
+import type { SharedSessionBroker } from '../control-plane/index.ts';
+import type { ServiceRegistry } from '../config/service-registry.ts';
+
+export interface SurfaceControlCommand {
+  readonly action: 'status' | 'cancel' | 'retry';
+  readonly id: string;
+}
+
+export interface QueueSurfaceReplyInput {
+  readonly agentId: string;
+  readonly task: string;
+  readonly sessionId?: string;
+}
+
+export type TrySpawnAgentInput = Parameters<AgentManager['spawn']>[0];
+export type TrySpawnAgentResult = AgentRecord | Response;
+export type TrySpawnAgentFn = (
+  input: TrySpawnAgentInput,
+  logLabel: string,
+  sessionId?: string,
+) => TrySpawnAgentResult;
+
+export interface SurfaceAdapterContext {
+  readonly serviceRegistry: ServiceRegistry;
+  readonly configManager: {
+    get(key: string): unknown;
+  };
+  readonly routeBindings: RouteBindingManager;
+  readonly sessionBroker: SharedSessionBroker;
+  readonly authorizeSurfaceIngress: (input: {
+    surface: Extract<AutomationSurfaceKind, 'slack' | 'discord' | 'ntfy' | 'telegram' | 'google-chat' | 'signal' | 'whatsapp' | 'imessage' | 'msteams' | 'bluebubbles' | 'mattermost' | 'matrix'>;
+    userId?: string;
+    channelId?: string;
+    groupId?: string;
+    threadId?: string;
+    workspaceId?: string;
+    conversationKind?: ChannelConversationKind;
+    hasAnyMention?: boolean;
+    text?: string;
+    controlCommand?: string;
+    mentioned?: boolean;
+    metadata?: Record<string, unknown>;
+  }) => Promise<ChannelPolicyDecision>;
+  readonly parseSurfaceControlCommand: (text: string) => SurfaceControlCommand | null;
+  readonly performSurfaceControlCommand: (command: SurfaceControlCommand) => Promise<string>;
+  readonly performInteractiveSurfaceAction: (
+    actionId: string,
+    surface: 'slack' | 'discord',
+    req: Request,
+  ) => Promise<string>;
+  readonly trySpawnAgent: TrySpawnAgentFn;
+  readonly queueSurfaceReplyFromBinding: (
+    binding: AutomationRouteBinding | undefined,
+    input: QueueSurfaceReplyInput,
+  ) => void;
+}
+
+export interface GenericWebhookReplyInput {
+  readonly agentId: string;
+  readonly task: string;
+  readonly sessionId?: string;
+  readonly routeId?: string;
+  readonly callbackUrl?: string;
+  readonly callbackCorrelationId?: string;
+  readonly callbackSignature?: 'shared-secret' | 'hmac-sha256';
+}
+
+export interface GenericWebhookAdapterContext {
+  readonly configManager: {
+    get(key: string): unknown;
+  };
+  readonly routeBindings: RouteBindingManager;
+  readonly sessionBroker: SharedSessionBroker;
+  readonly authorizeSurfaceIngress: (input: {
+    surface: Extract<AutomationSurfaceKind, 'webhook'>;
+    userId?: string;
+    channelId?: string;
+    groupId?: string;
+    threadId?: string;
+    workspaceId?: string;
+    conversationKind?: ChannelConversationKind;
+    hasAnyMention?: boolean;
+    text?: string;
+    controlCommand?: string;
+    mentioned?: boolean;
+    metadata?: Record<string, unknown>;
+  }) => Promise<ChannelPolicyDecision>;
+  readonly trySpawnAgent: TrySpawnAgentFn;
+  readonly surfaceDeliveryEnabled: (surface: Extract<AutomationSurfaceKind, 'webhook'>) => boolean;
+  readonly signWebhookPayload: (body: string, secret: string) => string;
+  readonly queueWebhookReply: (input: GenericWebhookReplyInput) => void;
+}