@cursor/july 0.1.55 → 0.1.61

package/src/channels/origin/origin-channel.ts

@@ -0,0 +1,784 @@
+import { z } from "zod";
+import {
+  allowAll,
+  defineChannel,
+  localDevStrict,
+  loopbackOnly,
+  POST,
+} from "../../channels.js";
+import { isDevMode } from "../../internal/dev-mode.js";
+import type {
+  AgentCloudOptions,
+  AuthContext,
+  ChannelDefinition,
+  ChannelHandlerArgs,
+} from "../../types.js";
+import {
+  parseCursorOriginRepoScope,
+  registerOriginCursorAccountRuntime,
+} from "./cursor-account.js";
+import { deriveOriginWebhookEvents, ORIGIN_CHANNEL_KIND } from "./events.js";
+import {
+  DEFAULT_ORIGIN_API_BASE_URL,
+  type OriginWebhookHeaders,
+  verifyOriginWebhook,
+} from "./origin-webhook.js";
+import type {
+  OriginActor,
+  OriginChannelOptions,
+  OriginComment,
+  OriginDispatch,
+  OriginEventContext,
+  OriginPullRequestEvent,
+  OriginRepositoryRef,
+  OriginReview,
+  OriginTaskDispatch,
+  OriginTurnDispatch,
+  OriginWebhookEnvelope,
+} from "./types.js";
+
+/**
+ * Default dispatch gate when no `onPullRequest` hook is declared: the common
+ * review triggers start a turn as the delivery's actor.
+ */
+const DEFAULT_PULL_REQUEST_TYPES: ReadonlySet<string> = new Set([
+  "pull_request.created",
+  "pull_request.published",
+  "pull_request.head_ref.pushed",
+  "pull_request.base_ref.updated",
+]);
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function asNonEmptyString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() !== ""
+    ? value.trim()
+    : undefined;
+}
+
+function asPositiveInt(value: unknown): number | undefined {
+  if (typeof value === "number" && Number.isInteger(value) && value > 0) {
+    return value;
+  }
+  if (typeof value === "string" && /^[1-9]\d*$/.test(value)) {
+    return Number(value);
+  }
+  return undefined;
+}
+
+function asBoolean(value: unknown): boolean | undefined {
+  return typeof value === "boolean" ? value : undefined;
+}
+
+function originActor(value: unknown): OriginActor | undefined {
+  const record = asRecord(value);
+  if (record === undefined) return undefined;
+  const nestedUser = asRecord(record.user);
+  const nestedApp = asRecord(record.app);
+  const id =
+    asNonEmptyString(nestedUser?.id) ??
+    asNonEmptyString(nestedApp?.id) ??
+    asNonEmptyString(asRecord(record.serviceAccount)?.id) ??
+    asNonEmptyString(record.id);
+  if (id === undefined) return undefined;
+  const kind = asNonEmptyString(record.kind);
+  return kind === undefined ? { id } : { id, kind };
+}
+
+function originHeaders(request: Request): OriginWebhookHeaders {
+  return {
+    "webhook-id": request.headers.get("webhook-id") ?? undefined,
+    "webhook-timestamp": request.headers.get("webhook-timestamp") ?? undefined,
+    "webhook-signature": request.headers.get("webhook-signature") ?? undefined,
+  };
+}
+
+function skipOriginVerify(): boolean {
+  return process.env.AGENT_SERVE_ORIGIN_SKIP_VERIFY?.trim() === "1";
+}
+
+/**
+ * Direct Origin HTTP deliveries verify v1ed. `--dev` and
+ * `AGENT_SERVE_ORIGIN_SKIP_VERIFY=1` skip that so local fixtures work, matching
+ * GitHub's unsigned loopback posture when no webhook secret is set.
+ */
+function shouldSkipOriginVerify(): boolean {
+  return skipOriginVerify() || isDevMode();
+}
+
+function asIdList(value: string | readonly string[] | undefined): string[] {
+  if (value === undefined) return [];
+  const items = typeof value === "string" ? [value] : [...value];
+  return [...new Set(items.map((id) => id.trim()).filter(Boolean))];
+}
+
+/** `AGENT_SERVE_ORIGIN_APP_ID` fallback for {@link OriginChannelOptions.appId}. */
+export function envOriginAppId(): string | undefined {
+  const value = process.env.AGENT_SERVE_ORIGIN_APP_ID?.trim();
+  return value === undefined || value === "" ? undefined : value;
+}
+
+function configuredOriginAppIds(
+  options: OriginChannelOptions
+): readonly string[] {
+  const fromOptions = asIdList(options.appId);
+  if (fromOptions.length > 0) return fromOptions;
+  const fromEnv = envOriginAppId();
+  return fromEnv === undefined ? [] : [fromEnv];
+}
+
+function configuredOriginInstallationIds(
+  options: OriginChannelOptions
+): readonly string[] {
+  return asIdList(options.installationId);
+}
+
+/**
+ * Repo allowlist for HTTP and trigger fan-out. `undefined` means no extra
+ * repo gate (the bound Origin app's installations still bound what Origin
+ * will send).
+ */
+function configuredOriginRepoAllowlist(
+  options: OriginChannelOptions
+): ReadonlySet<string> | undefined {
+  const repos: string[] = [];
+  if (options.repos !== undefined) {
+    repos.push(...parseCursorOriginRepoScope(options.repos).repos);
+  }
+  if (typeof options.cursorAccount === "object") {
+    repos.push(
+      ...parseCursorOriginRepoScope(options.cursorAccount.repos).repos
+    );
+  }
+  return repos.length === 0 ? undefined : new Set(repos);
+}
+
+/**
+ * v1ed proves Origin signed the body. Channel auth is the signed
+ * `envelope.appId` matching this channel's configured Origin app (the GitHub
+ * webhook-secret analogue). Cursor-internal documents the same gap.
+ */
+function originHttpBindingError(
+  options: OriginChannelOptions,
+  envelope: OriginWebhookEnvelope
+): string | undefined {
+  const allowedApps = configuredOriginAppIds(options);
+  if (allowedApps.length === 0) {
+    return "unbound_origin_app";
+  }
+  const deliveredAppId = envelope.appId?.trim();
+  if (deliveredAppId === undefined || deliveredAppId === "") {
+    return "invalid_app";
+  }
+  if (!allowedApps.includes(deliveredAppId)) {
+    return "invalid_app";
+  }
+  const allowedInstalls = configuredOriginInstallationIds(options);
+  if (allowedInstalls.length === 0) {
+    return undefined;
+  }
+  const deliveredInstallationId = envelope.installationId?.trim();
+  if (
+    deliveredInstallationId === undefined ||
+    deliveredInstallationId === "" ||
+    !allowedInstalls.includes(deliveredInstallationId)
+  ) {
+    return "invalid_installation";
+  }
+  return undefined;
+}
+
+function resolveApiBaseUrl(options: OriginChannelOptions): string {
+  const authored =
+    typeof options.apiBaseUrl === "function"
+      ? options.apiBaseUrl()
+      : options.apiBaseUrl;
+  const trimmed = authored?.trim();
+  return trimmed === undefined || trimmed === ""
+    ? DEFAULT_ORIGIN_API_BASE_URL
+    : trimmed;
+}
+
+const originEnvelopeSchema: z.ZodType<OriginWebhookEnvelope> = z.object({
+  deliveryId: z.string().optional(),
+  appId: z.string().optional(),
+  installationId: z.string().optional(),
+  sender: z
+    .object({
+      id: z.string().min(1),
+      kind: z.string().optional(),
+    })
+    .optional(),
+  event: z.object({
+    id: z.string().optional(),
+    type: z.string().min(1),
+    eventTime: z.string().optional(),
+    payload: z.unknown().optional(),
+  }),
+});
+
+export function parseOriginWebhookEnvelope(
+  payload: unknown
+): OriginWebhookEnvelope | null {
+  const parsed = originEnvelopeSchema.safeParse(payload);
+  return parsed.success ? parsed.data : null;
+}
+
+function originRepoFromPayload(
+  payload: Record<string, unknown>
+): OriginRepositoryRef | undefined {
+  const repository =
+    asRecord(payload.repository) ??
+    asRecord(asRecord(payload.pullRequest)?.repository);
+  const owner = asNonEmptyString(asRecord(repository?.owner)?.slug);
+  const name = asNonEmptyString(repository?.name);
+  if (owner === undefined || name === undefined) return undefined;
+  return { owner, name, fullName: `${owner}/${name}` };
+}
+
+function originPrUrl(
+  repository: OriginRepositoryRef,
+  number: number,
+  explicit?: string
+): string {
+  return (
+    explicit ??
+    `https://cursor.com/codebase/${repository.owner}/${repository.name}/pull/${number}`
+  );
+}
+
+function originSender(
+  envelope: OriginWebhookEnvelope,
+  payload: Record<string, unknown>
+): OriginActor | undefined {
+  return (
+    envelope.sender ??
+    originActor(payload.actor) ??
+    originActor(payload.pusher) ??
+    originActor(asRecord(payload.review)?.author) ??
+    originActor(asRecord(payload.comment)?.author) ??
+    originActor(asRecord(payload.pullRequest)?.author)
+  );
+}
+
+export function parseOriginPullRequestEvent(input: {
+  envelope: OriginWebhookEnvelope;
+}): {
+  ctx: Omit<OriginEventContext, "host" | "artifacts">;
+  pullRequest: OriginPullRequestEvent;
+  payload: Record<string, unknown>;
+} | null {
+  const payload = asRecord(input.envelope.event.payload) ?? {};
+  const repository = originRepoFromPayload(payload);
+  const pullRequest = asRecord(payload.pullRequest);
+  const number = asPositiveInt(pullRequest?.number);
+  if (repository === undefined || number === undefined) {
+    return null;
+  }
+  const eventType = input.envelope.event.type;
+  const url = originPrUrl(
+    repository,
+    number,
+    asNonEmptyString(pullRequest?.url)
+  );
+  const head = asRecord(pullRequest?.head);
+  const base = asRecord(pullRequest?.base);
+  const version = asRecord(pullRequest?.version);
+  const author = originActor(pullRequest?.author);
+  return {
+    payload,
+    ctx: {
+      deliveryId: input.envelope.deliveryId,
+      eventType,
+      repository,
+      pullRequestNumber: number,
+      pullRequestUrl: url,
+      sender: originSender(input.envelope, payload),
+    },
+    pullRequest: {
+      type: eventType,
+      number,
+      url,
+      title: asNonEmptyString(pullRequest?.title),
+      body:
+        pullRequest?.body === null
+          ? null
+          : (asNonEmptyString(pullRequest?.body) ??
+            (typeof pullRequest?.body === "string"
+              ? pullRequest.body
+              : undefined)),
+      draft: asBoolean(pullRequest?.draft),
+      merged:
+        eventType === "pull_request.merged" || asBoolean(pullRequest?.merged),
+      authorId: author?.id,
+      headRef: asNonEmptyString(head?.ref),
+      headSha:
+        asNonEmptyString(head?.sha) ?? asNonEmptyString(version?.headSha),
+      baseRef: asNonEmptyString(base?.ref),
+      baseSha:
+        asNonEmptyString(base?.sha) ?? asNonEmptyString(version?.baseSha),
+    },
+  };
+}
+
+/**
+ * Derive the turn's auth from the actor that triggered the delivery — the
+ * standard `{ auth: defaultOriginAuth(ctx) }` dispatch from an inbound hook.
+ * The subscriber's Cursor identity is not the turn principal (same pattern
+ * as {@link defaultGitHubAuth}).
+ */
+export function defaultOriginAuth(
+  ctx: Omit<OriginEventContext, "host" | "artifacts">
+): AuthContext {
+  const senderId = ctx.sender?.id;
+  return {
+    authenticator: "origin-webhook",
+    principalId: senderId ?? "origin",
+    principalType: ctx.sender?.kind === "app" ? "service" : "user",
+    attributes: {
+      conversation_kind: "pull_request",
+      repository: ctx.repository.fullName,
+      ...(ctx.deliveryId === undefined ? {} : { delivery_id: ctx.deliveryId }),
+      ...(senderId === undefined ? {} : { subject: senderId }),
+      ...(ctx.sender?.kind === undefined ? {} : { user_type: ctx.sender.kind }),
+      issuer: `origin:${ctx.repository.owner}`,
+    },
+  };
+}
+
+export function originContinuationKey(
+  ctx: Pick<OriginEventContext, "repository" | "pullRequestNumber">
+): string {
+  return `origin-pr:${ctx.repository.fullName}#${ctx.pullRequestNumber}`;
+}
+
+export function defaultOriginTitle(
+  ctx: Pick<OriginEventContext, "repository" | "pullRequestNumber">
+): string {
+  return `Origin ${ctx.repository.fullName}#${ctx.pullRequestNumber}`;
+}
+
+export function defaultOriginPullRequestMessage(
+  ctx: Omit<OriginEventContext, "host" | "artifacts">,
+  pullRequest: OriginPullRequestEvent
+): string {
+  const head =
+    pullRequest.headRef !== undefined && pullRequest.headSha !== undefined
+      ? `Head: ${pullRequest.headRef} (${pullRequest.headSha})`
+      : undefined;
+  return [
+    `Origin pull request trigger: ${ctx.repository.fullName}#${pullRequest.number}`,
+    `Event: ${pullRequest.type}`,
+    `URL: ${pullRequest.url}`,
+    ...(pullRequest.title === undefined ? [] : [`Title: ${pullRequest.title}`]),
+    ...(head === undefined ? [] : [head]),
+    "Handle this pull request event.",
+  ].join("\n");
+}
+
+export function defaultOriginPullRequestDispatch(
+  ctx: Omit<OriginEventContext, "host" | "artifacts">,
+  pullRequest: OriginPullRequestEvent
+): OriginTurnDispatch | null {
+  if (!DEFAULT_PULL_REQUEST_TYPES.has(pullRequest.type)) {
+    return null;
+  }
+  return { auth: defaultOriginAuth(ctx) };
+}
+
+function isTaskDispatch(
+  dispatch: OriginDispatch
+): dispatch is OriginTaskDispatch {
+  return "task" in dispatch;
+}
+
+function enrichEventContext(input: {
+  ctx: Omit<OriginEventContext, "host" | "artifacts">;
+  args: ChannelHandlerArgs;
+}): OriginEventContext {
+  return {
+    ...input.ctx,
+    host: input.args.host,
+    artifacts: input.args.artifacts,
+  };
+}
+
+function skipped(
+  reason: string,
+  extra: Record<string, unknown> = {}
+): Response {
+  return Response.json({ ok: true, skipped: true, reason, ...extra });
+}
+
+function acknowledgeTask(
+  args: ChannelHandlerArgs,
+  dispatch: OriginTaskDispatch,
+  extra: Record<string, unknown>
+): Response {
+  args.waitUntil(
+    new Promise<void>((resolve, reject) => {
+      setImmediate(() => {
+        Promise.resolve()
+          .then(dispatch.task)
+          .then(() => resolve(), reject);
+      });
+    })
+  );
+  return Response.json(
+    { ok: true, dispatched: true, mode: "task", ...extra },
+    { status: 202 }
+  );
+}
+
+async function startTurn(input: {
+  args: ChannelHandlerArgs;
+  ctx: OriginEventContext;
+  message: string;
+  dispatch: OriginTurnDispatch;
+  cloud?: AgentCloudOptions;
+}): Promise<Response> {
+  const session = await input.args.send(input.message, {
+    auth: input.dispatch.auth,
+    continuationToken: originContinuationKey(input.ctx),
+    title: input.dispatch.title ?? defaultOriginTitle(input.ctx),
+    ...(input.cloud === undefined ? {} : { cloud: input.cloud }),
+  });
+  return Response.json({
+    ok: true,
+    sessionId: session.id,
+    isNew: session.isNew,
+    continuationToken: session.continuationToken,
+  });
+}
+
+async function resolveCloudOptions(
+  cloud: OriginChannelOptions["cloud"],
+  ctx: OriginEventContext,
+  pullRequest: OriginPullRequestEvent
+): Promise<AgentCloudOptions | undefined> {
+  if (cloud === undefined || cloud === false) {
+    return undefined;
+  }
+  if (cloud === true) {
+    return {
+      repos: [
+        {
+          url: `https://cursor.com/codebase/${ctx.repository.fullName}`,
+          prUrl: pullRequest.url,
+          startingRef: pullRequest.headSha,
+        },
+      ],
+    };
+  }
+  if (typeof cloud === "function") {
+    return await cloud(ctx, pullRequest);
+  }
+  return cloud;
+}
+
+async function applyDispatch(input: {
+  args: ChannelHandlerArgs;
+  ctx: OriginEventContext;
+  dispatch: OriginDispatch | null;
+  extra: Record<string, unknown>;
+  message: string;
+  cloud?: AgentCloudOptions;
+}): Promise<Response> {
+  if (input.dispatch === null) {
+    return skipped("not_dispatched", input.extra);
+  }
+  if (isTaskDispatch(input.dispatch)) {
+    return acknowledgeTask(input.args, input.dispatch, input.extra);
+  }
+  const message = [
+    input.dispatch.message ?? input.message,
+    ...(input.dispatch.context ?? []),
+  ].join("\n");
+  return startTurn({
+    args: input.args,
+    ctx: input.ctx,
+    message,
+    dispatch: input.dispatch,
+    cloud: input.cloud,
+  });
+}
+
+/**
+ * Core Origin webhook dispatch used by {@link originChannel} routes and by
+ * {@link handleAgentServeTrigger} fan-out. Signature verification is the
+ * caller's responsibility (HTTP route verifies; internal fan-out skips).
+ */
+export async function dispatchOriginWebhook(input: {
+  options: OriginChannelOptions;
+  envelope: OriginWebhookEnvelope;
+  args: ChannelHandlerArgs;
+}): Promise<Response> {
+  const eventType = input.envelope.event.type;
+  const parsed = parseOriginPullRequestEvent({ envelope: input.envelope });
+  if (parsed === null) {
+    return Response.json(
+      { ok: false, error: "invalid_origin_payload" },
+      { status: 400 }
+    );
+  }
+  const ctx = enrichEventContext({ ctx: parsed.ctx, args: input.args });
+  const { pullRequest, payload } = parsed;
+  const repoAllowlist = configuredOriginRepoAllowlist(input.options);
+  if (
+    repoAllowlist !== undefined &&
+    !repoAllowlist.has(ctx.repository.fullName.toLowerCase())
+  ) {
+    return skipped("repo_not_allowed", { repo: ctx.repository.fullName });
+  }
+
+  if (eventType.startsWith("pull_request.comment.")) {
+    if (input.options.onComment === undefined) {
+      return skipped("no_handler", { event: eventType });
+    }
+    const commentRecord = asRecord(payload.comment);
+    const commentId = asNonEmptyString(commentRecord?.id);
+    const commentBody =
+      typeof commentRecord?.body === "string" ? commentRecord.body : undefined;
+    if (commentId === undefined || commentBody === undefined) {
+      return Response.json(
+        { ok: false, error: "invalid_origin_comment_payload" },
+        { status: 400 }
+      );
+    }
+    const comment: OriginComment = {
+      id: commentId,
+      body: commentBody,
+      author: originActor(commentRecord?.author),
+    };
+    const dispatch = await input.options.onComment(ctx, comment);
+    return applyDispatch({
+      args: input.args,
+      ctx,
+      dispatch,
+      extra: { event: eventType },
+      message: `Origin comment on ${ctx.repository.fullName}#${ctx.pullRequestNumber}`,
+    });
+  }
+
+  if (eventType.startsWith("pull_request.review.")) {
+    if (input.options.onReview === undefined) {
+      return skipped("no_handler", { event: eventType });
+    }
+    const reviewRecord = asRecord(payload.review) ?? {};
+    const review: OriginReview = {
+      id: asNonEmptyString(reviewRecord.id),
+      verdict: asNonEmptyString(reviewRecord.verdict),
+      author: originActor(reviewRecord.author),
+    };
+    const dispatch = await input.options.onReview(ctx, review);
+    return applyDispatch({
+      args: input.args,
+      ctx,
+      dispatch,
+      extra: { event: eventType },
+      message: `Origin review on ${ctx.repository.fullName}#${ctx.pullRequestNumber}`,
+    });
+  }
+
+  if (eventType.startsWith("pull_request.")) {
+    const dispatch =
+      input.options.onPullRequest === undefined
+        ? defaultOriginPullRequestDispatch(ctx, pullRequest)
+        : await input.options.onPullRequest(ctx, pullRequest);
+    const cloud = await resolveCloudOptions(
+      input.options.cloud,
+      ctx,
+      pullRequest
+    );
+    return applyDispatch({
+      args: input.args,
+      ctx,
+      dispatch,
+      extra: { event: eventType },
+      message: defaultOriginPullRequestMessage(ctx, pullRequest),
+      cloud,
+    });
+  }
+
+  if (input.options.onEvent !== undefined) {
+    const dispatch = await input.options.onEvent(ctx, {
+      eventType,
+      payload,
+    });
+    return applyDispatch({
+      args: input.args,
+      ctx,
+      dispatch,
+      extra: { event: eventType },
+      message: `Origin ${eventType} event`,
+    });
+  }
+
+  return skipped("unsupported_event", { event: eventType });
+}
+
+/**
+ * HTTP entry for a single agent's Origin channel: optional v1ed verify, then
+ * app-id bind, then {@link dispatchOriginWebhook}.
+ */
+export async function handleOriginWebhookRequest(input: {
+  options: OriginChannelOptions;
+  request: Request;
+  args: ChannelHandlerArgs;
+  /** When true, skip v1ed even though Origin HTTP deliveries are signed. */
+  skipSignatureVerification?: boolean;
+}): Promise<Response> {
+  const bodyText = await input.request.text();
+  const requireHttpBinding =
+    input.skipSignatureVerification !== true &&
+    shouldSkipOriginVerify() !== true;
+  if (requireHttpBinding) {
+    try {
+      await verifyOriginWebhook(bodyText, originHeaders(input.request), {
+        apiBaseUrl: resolveApiBaseUrl(input.options),
+      });
+    } catch {
+      return Response.json(
+        { ok: false, error: "invalid_signature" },
+        { status: 401 }
+      );
+    }
+  }
+
+  let payload: unknown;
+  try {
+    payload = JSON.parse(bodyText) as unknown;
+  } catch {
+    return Response.json({ ok: false, error: "invalid_json" }, { status: 400 });
+  }
+  const envelope = parseOriginWebhookEnvelope(payload);
+  if (envelope === null) {
+    return Response.json(
+      { ok: false, error: "invalid_origin_payload" },
+      { status: 400 }
+    );
+  }
+  if (requireHttpBinding) {
+    const bindingError = originHttpBindingError(input.options, envelope);
+    if (bindingError !== undefined) {
+      return Response.json({ ok: false, error: bindingError }, { status: 401 });
+    }
+  }
+  return dispatchOriginWebhook({
+    options: input.options,
+    envelope,
+    args: input.args,
+  });
+}
+
+const originChannelOptionsByDefinition = new WeakMap<
+  object,
+  OriginChannelOptions
+>();
+
+export function getOriginChannelOptions(
+  definition: object
+): OriginChannelOptions | undefined {
+  return originChannelOptionsByDefinition.get(definition);
+}
+
+export function originChannel(
+  options: OriginChannelOptions = {}
+): ChannelDefinition {
+  const usesCursorAccount =
+    options.cursorAccount === true || typeof options.cursorAccount === "object";
+  const cursorScope =
+    typeof options.cursorAccount === "object"
+      ? parseCursorOriginRepoScope(options.cursorAccount.repos)
+      : undefined;
+  if (options.repos !== undefined) {
+    parseCursorOriginRepoScope(options.repos);
+  }
+
+  const routePath = options.path ?? "/";
+  // v1ed + configured app id is the request auth (allowAll), matching GitHub
+  // HMAC + webhookSecret. Without an app id, prod stays loopback-strict so a
+  // reachable URL cannot be driven by any Origin-signed delivery. `--dev`
+  // / skip-verify admits loopback only.
+  const auth = options.auth ?? [
+    (request, info) =>
+      (shouldSkipOriginVerify()
+        ? loopbackOnly()
+        : configuredOriginAppIds(options).length > 0
+          ? allowAll()
+          : localDevStrict())(request, info),
+  ];
+
+  const definition = defineChannel({
+    auth,
+    onStart: options.onStart,
+    onStop: options.onStop,
+    meta: {
+      kind: ORIGIN_CHANNEL_KIND,
+      originWebhookEvents: deriveOriginWebhookEvents(options),
+    },
+    routes: [
+      POST(routePath, {
+        bodySchema: z.unknown(),
+        description: "Origin webhook ingress",
+        handler: async (request, args) =>
+          handleOriginWebhookRequest({
+            options,
+            request,
+            args,
+          }),
+      }),
+    ],
+  });
+  originChannelOptionsByDefinition.set(definition, options);
+  if (usesCursorAccount) {
+    registerOriginCursorAccountRuntime(definition, {
+      options,
+      scope: cursorScope,
+    });
+  }
+  return definition;
+}
+
+/** Minimal mount shape shared by `serve` / trigger fan-out. */
+export interface OriginAgentMountLike {
+  slug: string;
+  project: {
+    channels: Array<{
+      id: string;
+      definition: {
+        meta?: { kind?: string; originWebhookEvents?: readonly string[] };
+      };
+    }>;
+  };
+}
+
+export interface OriginChannelTarget {
+  slug: string;
+  channelId: string;
+  events: string[];
+}
+
+export function findOriginChannelTargets(
+  mounts: ReadonlyArray<OriginAgentMountLike>
+): OriginChannelTarget[] {
+  const targets: OriginChannelTarget[] = [];
+  for (const { slug, project } of mounts) {
+    for (const channel of project.channels) {
+      const meta = channel.definition.meta;
+      if (meta?.kind !== ORIGIN_CHANNEL_KIND) {
+        continue;
+      }
+      targets.push({
+        slug,
+        channelId: channel.id,
+        events: [...(meta.originWebhookEvents ?? [])],
+      });
+    }
+  }
+  return targets;
+}