@pellux/goodvibes-tui 0.18.4

package/src/adapters/imessage/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 handleIMessageSurfaceWebhook(req: Request, context: SurfaceAdapterContext): Promise<Response> {
+  const configuredToken =
+    String(context.configManager.get('surfaces.imessage.token') ?? '')
+    || await context.serviceRegistry.resolveSecret('imessage', 'primary')
+    || process.env.IMESSAGE_BRIDGE_TOKEN
+    || '';
+  if (configuredToken) {
+    const providedToken = readBearerOrHeaderToken(req, 'x-goodvibes-imessage-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 chatId = readString(payload.chatId) ?? readString(payload.conversationId) ?? readString(payload.source);
+  const message = readString(payload.message) ?? readString(payload.text) ?? '';
+  if (!chatId) return Response.json({ error: 'Missing chatId' }, { status: 400 });
+
+  const policy = await context.authorizeSurfaceIngress({
+    surface: 'imessage',
+    userId: chatId,
+    channelId: chatId,
+    groupId: chatId,
+    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: 'imessage',
+    surfaceId: readString(payload.account) ?? readString(context.configManager.get('surfaces.imessage.account')) ?? 'imessage',
+    externalId: readString(payload.threadId) ?? chatId,
+    channelId: chatId,
+    threadId: readString(payload.threadId),
+    title: chatId,
+    metadata: { ...payload },
+  });
+  if (!message) {
+    return Response.json({ acknowledged: true, queued: false, bindingId: binding.id });
+  }
+
+  const submission = await context.sessionBroker.submitMessage({
+    routeId: binding.id,
+    surfaceKind: 'imessage',
+    surfaceId: binding.surfaceId,
+    externalId: binding.externalId,
+    threadId: binding.threadId ?? binding.channelId,
+    userId: chatId,
+    displayName: chatId,
+    title: chatId,
+    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! },
+    'handleIMessageSurfaceWebhook',
+    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/index.ts

@@ -0,0 +1,15 @@
+export * from './types.ts';
+export { handleSlackSurfacePayload, handleSlackSurfaceWebhook } from './slack/index.ts';
+export { handleDiscordGatewayDispatchPayload, handleDiscordInteractionPayload, handleDiscordSurfaceWebhook } from './discord/index.ts';
+export { handleNtfySurfacePayload, handleNtfySurfaceWebhook } from './ntfy/index.ts';
+export { handleTelegramSurfaceWebhook } from './telegram/index.ts';
+export { handleGoogleChatSurfaceWebhook } from './google-chat/index.ts';
+export { handleSignalSurfaceWebhook } from './signal/index.ts';
+export { handleWhatsAppSurfaceWebhook } from './whatsapp/index.ts';
+export { handleIMessageSurfaceWebhook } from './imessage/index.ts';
+export { handleMSTeamsSurfaceWebhook } from './msteams/index.ts';
+export { handleBlueBubblesSurfaceWebhook } from './bluebubbles/index.ts';
+export { handleMattermostSurfaceWebhook } from './mattermost/index.ts';
+export { handleMatrixSurfaceWebhook } from './matrix/index.ts';
+export { handleGenericWebhookSurface } from './webhook/index.ts';
+export { handleGitHubAutomationWebhook } from './github/index.ts';

package/src/adapters/matrix/index.ts

@@ -0,0 +1,116 @@
+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;
+}
+
+function readThreadId(content: Record<string, unknown> | null): string | undefined {
+  const relatesTo = readRecord(content?.['m.relates_to']);
+  const reply = readRecord(relatesTo?.['m.in_reply_to']);
+  return readString(relatesTo?.event_id) ?? readString(reply?.event_id);
+}
+
+export async function handleMatrixSurfaceWebhook(req: Request, context: SurfaceAdapterContext): Promise<Response> {
+  const configuredToken =
+    String(context.configManager.get('surfaces.matrix.accessToken') ?? '')
+    || await context.serviceRegistry.resolveSecret('matrix', 'primary')
+    || process.env.MATRIX_ACCESS_TOKEN
+    || '';
+  const providedToken = readBearerOrHeaderToken(req, 'x-goodvibes-matrix-token');
+  if (configuredToken && 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 event = readRecord(payload.event) ?? payload;
+  const content = readRecord(event.content);
+  const roomId = readString(event.room_id) ?? readString(payload.roomId);
+  const text = readString(content?.body) ?? readString(event.text) ?? readString(payload.text) ?? '';
+  if (!roomId) return Response.json({ error: 'Missing room id' }, { status: 400 });
+  const threadId = readThreadId(content);
+
+  const policy = await context.authorizeSurfaceIngress({
+    surface: 'matrix',
+    userId: readString(event.sender) ?? readString(payload.sender),
+    channelId: roomId,
+    groupId: roomId,
+    threadId,
+    workspaceId: readString(payload.homeserver) ?? readString(context.configManager.get('surfaces.matrix.homeserverUrl')),
+    conversationKind: threadId ? 'thread' : 'channel',
+    text,
+    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: threadId ? 'thread' : 'channel',
+    surfaceKind: 'matrix',
+    surfaceId: readString(context.configManager.get('surfaces.matrix.userId')) ?? 'matrix',
+    externalId: threadId ?? roomId,
+    channelId: roomId,
+    threadId,
+    title: roomId,
+    metadata: {
+      ...payload,
+      ...(readString(event.event_id) ? { eventId: readString(event.event_id) } : {}),
+      ...(readString(content?.msgtype) ? { msgtype: readString(content?.msgtype) } : {}),
+    },
+  });
+  if (!text) {
+    return Response.json({ ok: true, acknowledged: true, bindingId: binding.id });
+  }
+
+  const controlCommand = context.parseSurfaceControlCommand(text);
+  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: 'matrix',
+    surfaceId: binding.surfaceId,
+    externalId: binding.externalId,
+    threadId: binding.threadId ?? binding.channelId,
+    userId: readString(event.sender) ?? readString(payload.sender),
+    displayName: readString(payload.displayName) ?? readString(event.sender),
+    title: binding.title ?? 'Matrix',
+    body: text,
+    metadata: binding.metadata,
+  });
+  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! },
+    'handleMatrixSurfaceWebhook',
+    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: text,
+    sessionId: submission.session.id,
+  });
+  return Response.json({
+    ok: true,
+    queued: true,
+    bindingId: binding.id,
+    sessionId: submission.session.id,
+    agentId: spawnResult.id,
+  });
+}

package/src/adapters/mattermost/index.ts

@@ -0,0 +1,151 @@
+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;
+}
+
+async function readBody(req: Request): Promise<Record<string, unknown> | Response | null> {
+  const contentType = req.headers.get('content-type') ?? '';
+  if (contentType.includes('multipart/form-data')) {
+    const contentLength = parseInt(req.headers.get('content-length') ?? '0', 10);
+    if (Number.isFinite(contentLength) && contentLength > 1_000_000) {
+      return Response.json({ error: 'Payload too large' }, { status: 413 });
+    }
+    const form = await req.formData().catch(() => null);
+    if (!form) return null;
+    return Object.fromEntries(
+      [...form.entries()].map(([key, value]) => [key, typeof value === 'string' ? value : String(value)]),
+    );
+  }
+  const rawBody = await readTextBodyWithinLimit(req);
+  if (rawBody instanceof Response) return rawBody;
+  if (contentType.includes('application/x-www-form-urlencoded')) {
+    return Object.fromEntries(new URLSearchParams(rawBody));
+  }
+  const parsed = parseJsonRecord(rawBody);
+  return parsed instanceof Response ? null : readRecord(parsed);
+}
+
+export async function handleMattermostSurfaceWebhook(req: Request, context: SurfaceAdapterContext): Promise<Response> {
+  const body = await readBody(req);
+  if (body instanceof Response) return body;
+  if (!body) return Response.json({ error: 'Invalid webhook payload' }, { status: 400 });
+  const configuredToken =
+    String(context.configManager.get('surfaces.mattermost.botToken') ?? '')
+    || await context.serviceRegistry.resolveSecret('mattermost', 'primary')
+    || process.env.MATTERMOST_BOT_TOKEN
+    || '';
+  const providedToken = readBearerOrHeaderToken(req, 'x-goodvibes-mattermost-token')
+    ?? readString(body.token)
+    ?? '';
+  if (configuredToken && providedToken !== configuredToken) {
+    return Response.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+
+  const post = typeof body.post === 'string'
+    ? (() => {
+        try {
+          return readRecord(JSON.parse(body.post));
+        } catch {
+          return null;
+        }
+      })()
+    : readRecord(body.post);
+  const message = readString(post?.message) ?? readString(body.text) ?? '';
+  const channelId = readString(post?.channel_id) ?? readString(body.channel_id);
+  const threadId = readString(post?.root_id) ?? readString(body.root_id);
+  const userId = readString(post?.user_id) ?? readString(body.user_id);
+  const teamId = readString(post?.team_id) ?? readString(body.team_id);
+  if (!channelId) return Response.json({ error: 'Missing channel id' }, { status: 400 });
+
+  const task = readString(body.command) ? message : message;
+  const policy = await context.authorizeSurfaceIngress({
+    surface: 'mattermost',
+    userId,
+    channelId,
+    groupId: teamId ?? channelId,
+    threadId,
+    workspaceId: teamId,
+    conversationKind: threadId ? 'thread' : 'channel',
+    text: task,
+    mentioned: true,
+    metadata: {
+      ...body,
+      ...(post ? { post } : {}),
+    },
+  });
+  if (!policy.allowed) {
+    return Response.json({ error: `Blocked by channel policy: ${policy.reason}` }, { status: 403 });
+  }
+
+  const binding = await context.routeBindings.upsertBinding({
+    kind: threadId ? 'thread' : 'channel',
+    surfaceKind: 'mattermost',
+    surfaceId: teamId ?? 'mattermost',
+    externalId: threadId ?? channelId,
+    channelId,
+    threadId,
+    title: readString(body.channel_name) ?? channelId,
+    metadata: {
+      ...body,
+      ...(post ? { post } : {}),
+    },
+  });
+  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: 'mattermost',
+    surfaceId: binding.surfaceId,
+    externalId: binding.externalId,
+    threadId: binding.threadId ?? binding.channelId,
+    userId,
+    displayName: readString(body.user_name) ?? userId,
+    title: binding.title ?? 'Mattermost',
+    body: task,
+    metadata: binding.metadata,
+  });
+  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! },
+    'handleMattermostSurfaceWebhook',
+    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,
+  });
+
+  if ((req.headers.get('content-type') ?? '').includes('application/x-www-form-urlencoded')) {
+    return Response.json({
+      response_type: 'ephemeral',
+      text: 'GoodVibes accepted the request and is processing it.',
+    });
+  }
+  return Response.json({
+    ok: true,
+    queued: true,
+    bindingId: binding.id,
+    sessionId: submission.session.id,
+    agentId: spawnResult.id,
+  });
+}

package/src/adapters/msteams/index.ts

@@ -0,0 +1,180 @@
+import type { ChannelConversationKind } from '../../channels/index.ts';
+import { constantTimeEquals, 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;
+}
+
+function stripTeamsMarkup(text: string): string {
+  return text
+    .replace(/<at>.*?<\/at>/gi, ' ')
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/&nbsp;/gi, ' ')
+    .replace(/&amp;/gi, '&')
+    .replace(/&lt;/gi, '<')
+    .replace(/&gt;/gi, '>')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function teamsConversationKind(conversationType?: string, threadId?: string): ChannelConversationKind {
+  if (threadId) return 'thread';
+  if (conversationType === 'personal') return 'direct';
+  if (conversationType === 'channel') return 'channel';
+  return 'group';
+}
+
+function normalizeConversationId(raw?: string): string | undefined {
+  if (!raw) return undefined;
+  return raw.replace(/;messageid=[^;]+$/i, '');
+}
+
+export async function handleMSTeamsSurfaceWebhook(req: Request, context: SurfaceAdapterContext): Promise<Response> {
+  const configuredSecret =
+    String(context.configManager.get('surfaces.msteams.appPassword') ?? '')
+    || await context.serviceRegistry.resolveSecret('msteams', 'password')
+    || process.env.MSTEAMS_APP_PASSWORD
+    || '';
+  if (!configuredSecret) {
+    return Response.json({ error: 'Webhook not configured' }, { status: 503 });
+  }
+  const providedToken = readBearerOrHeaderToken(req, 'x-goodvibes-msteams-token');
+  if (!constantTimeEquals(configuredSecret, providedToken)) {
+    return Response.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+  const rawBody = await readTextBodyWithinLimit(req);
+  if (rawBody instanceof Response) return rawBody;
+  let body: unknown = null;
+  if (rawBody.trim().length > 0) {
+    try {
+      body = JSON.parse(rawBody);
+    } catch {
+      return Response.json({ error: 'Invalid JSON body' }, { status: 400 });
+    }
+  }
+  const activity = readRecord(body);
+  if (!activity) return Response.json({ error: 'Invalid JSON body' }, { status: 400 });
+  const activityType = readString(activity.type)?.toLowerCase();
+  if (activityType && activityType !== 'message' && activityType !== 'invoke') {
+    return Response.json({ ok: true, ignored: true, activityType });
+  }
+
+  const conversation = readRecord(activity.conversation);
+  const from = readRecord(activity.from);
+  const value = readRecord(activity.value);
+  const channelData = readRecord(activity.channelData);
+  const conversationId = normalizeConversationId(readString(conversation?.id));
+  if (!conversationId) return Response.json({ error: 'Missing conversation id' }, { status: 400 });
+  const replyToId = readString(activity.replyToId);
+  const serviceUrl = readString(activity.serviceUrl)
+    ?? (String(context.configManager.get('surfaces.msteams.serviceUrl') ?? '').trim() || undefined);
+  const text = stripTeamsMarkup(
+    readString(activity.text)
+    ?? readString(value?.text)
+    ?? readString(value?.command)
+    ?? '',
+  );
+  const conversationType = readString(conversation?.conversationType) ?? readString(channelData?.conversationType);
+  const channelId = readString(conversation?.id) ?? conversationId;
+  const team = readRecord(channelData?.team);
+  const channel = readRecord(channelData?.channel);
+  const tenant = readRecord(channelData?.tenant);
+  const teamId = readString(team?.['id']);
+  const channelEntryId = readString(channel?.['id']);
+  const tenantId = readString(tenant?.['id']);
+  const policy = await context.authorizeSurfaceIngress({
+    surface: 'msteams',
+    userId: readString(from?.id),
+    channelId,
+    groupId: channelEntryId ?? channelId,
+    threadId: replyToId,
+    workspaceId: teamId ?? tenantId,
+    conversationKind: teamsConversationKind(conversationType, replyToId),
+    text,
+    mentioned: conversationType === 'personal' || /goodvibes/i.test(text),
+    metadata: {
+      activityId: readString(activity.id),
+      conversationId,
+      conversationType,
+      replyToId,
+      serviceUrl,
+      teamId,
+      channelId: channelEntryId,
+      tenantId,
+    },
+  });
+  if (!policy.allowed) {
+    return Response.json({ error: `Blocked by channel policy: ${policy.reason}` }, { status: 403 });
+  }
+
+  const binding = await context.routeBindings.upsertBinding({
+    kind: replyToId ? 'thread' : 'channel',
+    surfaceKind: 'msteams',
+    surfaceId: readString(context.configManager.get('surfaces.msteams.botId'))
+      ?? readString(context.configManager.get('surfaces.msteams.appId'))
+      ?? 'msteams',
+    externalId: replyToId ?? conversationId,
+    channelId: channelId,
+    threadId: replyToId,
+    title: readString(conversation?.name) ?? readString(channel?.id) ?? conversationId,
+    metadata: {
+      ...activity,
+      conversationId,
+      serviceUrl,
+      conversationType,
+      replyToId,
+      teamId,
+      channelId: channelEntryId,
+    },
+  });
+  if (!text) {
+    return Response.json({ ok: true, acknowledged: true, bindingId: binding.id });
+  }
+
+  const controlCommand = context.parseSurfaceControlCommand(text);
+  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: 'msteams',
+    surfaceId: binding.surfaceId,
+    externalId: binding.externalId,
+    threadId: binding.threadId ?? binding.channelId,
+    userId: readString(from?.id),
+    displayName: readString(from?.name) ?? readString(from?.id),
+    title: binding.title ?? 'Microsoft Teams',
+    body: text,
+    metadata: binding.metadata,
+  });
+  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! },
+    'handleMSTeamsSurfaceWebhook',
+    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: text,
+    sessionId: submission.session.id,
+  });
+  return Response.json({
+    ok: true,
+    queued: true,
+    bindingId: binding.id,
+    sessionId: submission.session.id,
+    agentId: spawnResult.id,
+  });
+}

package/src/adapters/ntfy/index.ts

@@ -0,0 +1,118 @@
+import { parseJsonRecord, readBearerOrHeaderToken, readTextBodyWithinLimit } from '@pellux/goodvibes-sdk/platform/adapters/helpers';
+import type { SurfaceAdapterContext } from '../types.ts';
+
+export async function handleNtfySurfaceWebhook(req: Request, context: SurfaceAdapterContext): Promise<Response> {
+  const enabled = Boolean(context.configManager.get('surfaces.ntfy.enabled'));
+  const configuredToken =
+    String(context.configManager.get('surfaces.ntfy.token') ?? '')
+    || await context.serviceRegistry.resolveSecret('ntfy', 'primary')
+    || process.env.NTFY_ACCESS_TOKEN
+    || '';
+  if (!enabled || !configuredToken) {
+    return Response.json({ error: 'ntfy webhook ingress is not configured' }, { status: 503 });
+  }
+  const providedToken = req.headers.get('x-ntfy-token')
+    ?? readBearerOrHeaderToken(req, 'x-goodvibes-ntfy-token')
+    ?? '';
+  if (providedToken !== configuredToken) {
+    return Response.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+  const rawBody = await readTextBodyWithinLimit(req);
+  if (rawBody instanceof Response) return rawBody;
+  let body: Record<string, unknown> = {};
+  if ((req.headers.get('content-type') ?? '').includes('application/json')) {
+    const parsed = parseJsonRecord(rawBody);
+    if (parsed instanceof Response) return parsed;
+    body = parsed;
+  } else if (rawBody.trim().length > 0) {
+    body = { message: rawBody.trim() };
+  }
+
+  return handleNtfySurfacePayload(body, context, new URL(req.url));
+}
+
+export async function handleNtfySurfacePayload(
+  body: Record<string, unknown>,
+  context: SurfaceAdapterContext,
+  url?: URL,
+): Promise<Response> {
+  const topic = typeof body.topic === 'string'
+    ? body.topic
+    : url?.searchParams.get('topic') ?? '';
+  const message = typeof body.message === 'string'
+    ? body.message
+    : typeof body.text === 'string'
+      ? body.text
+      : '';
+  if (!topic) {
+    return Response.json({ error: 'Missing ntfy topic' }, { status: 400 });
+  }
+  const policy = await context.authorizeSurfaceIngress({
+    surface: 'ntfy',
+    channelId: topic,
+    groupId: topic,
+    conversationKind: 'channel',
+    text: message,
+    mentioned: true,
+    metadata: body,
+  });
+  if (!policy.allowed) {
+    return Response.json({ error: `Blocked by channel policy: ${policy.reason}` }, { status: 403 });
+  }
+
+  const binding = await context.routeBindings.upsertBinding({
+    kind: 'channel',
+    surfaceKind: 'ntfy',
+    surfaceId: 'ntfy',
+    externalId: topic,
+    channelId: topic,
+    title: typeof body.title === 'string' ? body.title : topic,
+    metadata: body,
+  });
+
+  if (!message) {
+    return Response.json({ acknowledged: true, queued: false, bindingId: binding.id });
+  }
+
+  const submission = await context.sessionBroker.submitMessage({
+    routeId: binding.id,
+    surfaceKind: 'ntfy',
+    surfaceId: binding.surfaceId,
+    externalId: topic,
+    threadId: topic,
+    title: typeof body.title === 'string' ? body.title : topic,
+    body: message,
+    metadata: body,
+  });
+  if (submission.mode === 'continued-live') {
+    return Response.json({
+      acknowledged: true,
+      queued: true,
+      continued: true,
+      bindingId: binding.id,
+      sessionId: submission.session.id,
+      agentId: submission.activeAgentId,
+    });
+  }
+
+  const spawnResult = context.trySpawnAgent(
+    { mode: 'spawn', task: submission.task! },
+    'handleNtfySurfaceWebhook',
+    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,
+    topic,
+    sessionId: submission.session.id,
+    agentId: spawnResult.id,
+  });
+}