@cursor/bdk 0.2.1

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

@@ -0,0 +1,815 @@
+import { z } from "zod";
+import { allowAll, defineChannel, localDevStrict, loopbackOnly, POST } from "../../channels.js";
+import {
+  acknowledgeTask,
+  isTaskDispatch,
+  skipped,
+  turnStarted,
+  withPropagatingBackgroundErrors,
+} from "../../internal/channel-dispatch.js";
+import { continuationSource, normalizeIdentity } from "../../internal/continuation-identity.js";
+import { isDevMode } from "../../internal/dev-mode.js";
+import { attachHostedAdmissionAdapter } from "../../internal/hosted-admission-adapter.js";
+import { bindLocalIngressSend } from "../../internal/local-ingress.js";
+import type {
+  AgentCloudOptions,
+  AuthContext,
+  ChannelDefinition,
+  ChannelEventHandlers,
+  ChannelHandlerArgs,
+  JsonValue,
+} from "../../types.js";
+import { buildOriginBinding } from "./binding.js";
+import {
+  parseCursorOriginRepoScope,
+  registerOriginCursorAccountRuntime,
+} from "./cursor-account.js";
+import { buildDefaultOriginEvents } from "./defaults.js";
+import { deriveOriginWebhookEvents, ORIGIN_CHANNEL_KIND } from "./events.js";
+import {
+  DEFAULT_ORIGIN_API_BASE_URL,
+  OriginJwksUnavailableError,
+  type OriginWebhookHeaders,
+  verifyOriginWebhook,
+} from "./origin-webhook.js";
+import {
+  emptyOriginChannelState,
+  type OriginChannelState,
+  originChannelStateForEvent,
+} from "./state.js";
+import type {
+  OriginActor,
+  OriginChannelOptions,
+  OriginComment,
+  OriginDispatch,
+  OriginEventContext,
+  OriginPullRequestEvent,
+  OriginRepositoryRef,
+  OriginReview,
+  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 nestedActors = [
+    ["user", asRecord(record.user)],
+    ["app", asRecord(record.app)],
+    ["service_account", asRecord(record.serviceAccount)],
+  ] as const;
+  for (const [kind, actor] of nestedActors) {
+    const id = asNonEmptyString(actor?.id);
+    if (id !== undefined) {
+      return { id, kind };
+    }
+  }
+
+  const 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" | "origin">;
+  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,
+      eventTime: input.envelope.event.eventTime,
+      installationId: input.envelope.installationId,
+      repository,
+      pullRequestNumber: number,
+      pullRequestUrl: url,
+      pullRequestAuthor: author,
+      payload,
+      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" | "origin">,
+): AuthContext {
+  const senderId = ctx.sender?.id;
+  const senderKind = ctx.sender?.kind;
+  return {
+    authenticator: "origin-webhook",
+    principalId: senderId ?? "origin",
+    principalType: senderKind === "app" || senderKind === "service_account" ? "service" : "user",
+    attributes: {
+      conversation_kind: "pull_request",
+      repository: ctx.repository.fullName,
+      ...(ctx.deliveryId === undefined ? {} : { delivery_id: ctx.deliveryId }),
+      ...(senderId === undefined ? {} : { subject: senderId }),
+      ...(senderKind === undefined ? {} : { user_type: senderKind }),
+      issuer: `origin:${ctx.repository.owner}`,
+    },
+  };
+}
+
+export function originContinuationKey(
+  ctx: Pick<OriginEventContext, "repository" | "pullRequestNumber">,
+): string {
+  return `origin-pr:${ctx.repository.fullName}#${ctx.pullRequestNumber}`;
+}
+
+/** Payload shape local/hosted CP extract expects (`fullName` + number). */
+export function originIngressExtractPayload(envelope: OriginWebhookEnvelope): unknown {
+  const parsed = parseOriginPullRequestEvent({ envelope });
+  if (parsed === null) {
+    return envelope.event.payload;
+  }
+  return {
+    pullRequest: { number: parsed.ctx.pullRequestNumber },
+    repository: { fullName: parsed.ctx.repository.fullName },
+  };
+}
+
+export function defaultOriginTitle(
+  ctx: Pick<OriginEventContext, "repository" | "pullRequestNumber">,
+): string {
+  return `Origin ${ctx.repository.fullName}#${ctx.pullRequestNumber}`;
+}
+
+export function defaultOriginPullRequestMessage(
+  ctx: Omit<OriginEventContext, "host" | "artifacts" | "origin">,
+  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" | "origin">,
+  pullRequest: OriginPullRequestEvent,
+): OriginTurnDispatch | null {
+  if (!DEFAULT_PULL_REQUEST_TYPES.has(pullRequest.type)) {
+    return null;
+  }
+  return { auth: defaultOriginAuth(ctx) };
+}
+
+function enrichEventContext(input: {
+  ctx: Omit<OriginEventContext, "host" | "artifacts" | "origin">;
+  args: ChannelHandlerArgs;
+  options: OriginChannelOptions;
+}): OriginEventContext {
+  return {
+    ...input.ctx,
+    host: input.args.host,
+    artifacts: input.args.artifacts,
+    send: input.args.send,
+    origin: buildOriginBinding({
+      repository: input.ctx.repository,
+      installationId: input.ctx.installationId,
+      executionId: input.ctx.deliveryId,
+      cursorAccount:
+        input.options.cursorAccount !== undefined && input.options.cursorAccount !== false,
+      app: input.options.app,
+    }),
+  };
+}
+
+async function startTurn(input: {
+  options: OriginChannelOptions;
+  args: ChannelHandlerArgs;
+  ctx: OriginEventContext;
+  message: string;
+  dispatch: OriginTurnDispatch;
+  cloud?: AgentCloudOptions;
+  state: OriginChannelState;
+}): Promise<Response> {
+  const source = continuationSource(input.options.continuation, "origin");
+  const cloud = input.dispatch.cloud ?? input.cloud;
+  const state = { ...input.dispatch.state, ...input.state };
+  const session = await input.args.send(input.message, {
+    auth: input.dispatch.auth,
+    ...(source === "engine" ? { continuationToken: originContinuationKey(input.ctx) } : {}),
+    title: input.dispatch.title ?? defaultOriginTitle(input.ctx),
+    cloud,
+    state: state as unknown as JsonValue,
+    // Resume must refresh the triggering comment / delivery identifiers so
+    // reply delivery targets the latest wake, not the session's first.
+    refreshState: state as unknown as JsonValue,
+  });
+  return turnStarted(session);
+}
+
+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: {
+  options: OriginChannelOptions;
+  args: ChannelHandlerArgs;
+  ctx: OriginEventContext;
+  dispatch: OriginDispatch | null;
+  extra: Record<string, unknown>;
+  message: string;
+  cloud?: AgentCloudOptions;
+  /** Comment id that woke this dispatch (comment events only). */
+  triggeringCommentId?: string;
+}): Promise<Response> {
+  if (input.dispatch === null) {
+    return skipped("not_dispatched", input.extra);
+  }
+  if (isTaskDispatch(input.dispatch)) {
+    return acknowledgeTask(input.args, ORIGIN_CHANNEL_KIND, input.dispatch, input.extra);
+  }
+  const message = [input.dispatch.message ?? input.message, ...(input.dispatch.context ?? [])].join(
+    "\n",
+  );
+  return startTurn({
+    options: input.options,
+    args: input.args,
+    ctx: input.ctx,
+    message,
+    dispatch: input.dispatch,
+    cloud: input.cloud,
+    state: originChannelStateForEvent({
+      repository: input.ctx.repository,
+      pullRequestNumber: input.ctx.pullRequestNumber,
+      installationId: input.ctx.installationId,
+      deliveryId: input.ctx.deliveryId,
+      eventType: input.ctx.eventType,
+      triggeringCommentId: input.triggeringCommentId,
+    }),
+  });
+}
+
+/**
+ * Run the authored hooks for one Origin delivery and `send()` the turn.
+ * Callers own delivery auth: the HTTP route verifies v1ed and binds the app
+ * id; trigger fan-out and hosted admission arrive verified. The v2 mailbox
+ * is stamped upstream (local CP or hosted ingress), never here.
+ */
+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 args = input.args;
+  const ctx = enrichEventContext({
+    ctx: parsed.ctx,
+    args,
+    options: input.options,
+  });
+  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({
+      options: input.options,
+      args,
+      ctx,
+      dispatch,
+      extra: { event: eventType },
+      message:
+        commentBody.trim() === ""
+          ? `Origin comment on ${ctx.repository.fullName}#${ctx.pullRequestNumber}`
+          : commentBody.trim(),
+      triggeringCommentId: commentId,
+    });
+  }
+
+  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({
+      options: input.options,
+      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({
+      options: input.options,
+      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({
+      options: input.options,
+      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 (error) {
+      // A JWKS outage means the delivery was never checked: answer 503 so
+      // Origin's delivery worker retries. Only a real signature mismatch
+      // is the terminal 401.
+      if (error instanceof OriginJwksUnavailableError) {
+        return Response.json(
+          { ok: false, error: "signature_verification_unavailable" },
+          { status: 503 },
+        );
+      }
+      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: bindLocalIngressSend(input.args, {
+      identity: input.options.continuation,
+      kind: "origin",
+      eventType: envelope.event.type,
+      payload: originIngressExtractPayload(envelope),
+    }),
+  });
+}
+
+const originChannelOptionsByDefinition = new WeakMap<object, OriginChannelOptions>();
+
+export function getOriginChannelOptions(definition: object): OriginChannelOptions | undefined {
+  return originChannelOptionsByDefinition.get(definition);
+}
+
+export function originChannel(
+  options: OriginChannelOptions = {},
+): ChannelDefinition<OriginChannelState> {
+  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 channelOptions: OriginChannelOptions = {
+    ...options,
+  };
+  if (channelOptions.continuation !== undefined) {
+    channelOptions.continuation = normalizeIdentity(channelOptions.continuation, "origin");
+  }
+
+  const events: ChannelEventHandlers<OriginChannelState> = {
+    ...buildDefaultOriginEvents({
+      cursorAccount: channelOptions.cursorAccount,
+      app: channelOptions.app,
+      deliverReplies: channelOptions.deliverReplies,
+    }),
+    ...options.events,
+  };
+
+  const definition = defineChannel({
+    auth,
+    state: emptyOriginChannelState(),
+    events,
+    onStart: options.onStart,
+    onStop: options.onStop,
+    meta: {
+      kind: ORIGIN_CHANNEL_KIND,
+      originWebhookEvents: deriveOriginWebhookEvents(channelOptions),
+    },
+    routes: [
+      POST(routePath, {
+        bodySchema: z.unknown(),
+        description: "Origin webhook ingress",
+        handler: async (request, args) =>
+          handleOriginWebhookRequest({
+            options: channelOptions,
+            request,
+            args,
+          }),
+      }),
+    ],
+  });
+  originChannelOptionsByDefinition.set(definition, channelOptions);
+  attachHostedAdmissionAdapter(definition, {
+    kind: ORIGIN_CHANNEL_KIND,
+    prepareArgs: withPropagatingBackgroundErrors,
+    dispatch: async ({ payload, args }) => {
+      const envelope = parseOriginWebhookEnvelope(payload);
+      if (envelope === null) {
+        return Response.json({ ok: false, error: "invalid_origin_payload" }, { status: 400 });
+      }
+      return dispatchOriginWebhook({
+        options: channelOptions,
+        envelope,
+        args,
+      });
+    },
+  });
+  if (usesCursorAccount) {
+    registerOriginCursorAccountRuntime(definition, {
+      options: channelOptions,
+      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;
+}