@cursor/july 0.1.1

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

@@ -0,0 +1,2270 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { z } from "zod";
+import {
+  allowAll,
+  defineChannel,
+  localDevStrict,
+  loopbackGitHubDev,
+  POST,
+} from "../../channels.js";
+import { isDevMode } from "../../internal/dev-mode.js";
+import type {
+  AgentCloudOptions,
+  AuthContext,
+  ChannelDefinition,
+  ChannelEventHandlers,
+  ChannelHandlerArgs,
+  HostContext,
+  JsonValue,
+} from "../../types.js";
+import { resolveCredentialValue } from "./auth.js";
+import {
+  buildGitHubBinding,
+  type GitHubBindingConfig,
+  type GitHubBindingState,
+} from "./binding.js";
+import { buildDefaultGitHubEvents } from "./defaults.js";
+import { deriveGitHubWebhookEvents, GITHUB_CHANNEL_KIND } from "./events.js";
+import {
+  emptyGitHubChannelState,
+  type GitHubChannelState,
+  githubBindingStateForEvent,
+} from "./state.js";
+import type {
+  GitHubChannelOptions,
+  GitHubCheckRunEvent,
+  GitHubCheckSuiteEvent,
+  GitHubCiAppRef,
+  GitHubCiPullRequestRef,
+  GitHubComment,
+  GitHubConversationKind,
+  GitHubCredentialValue,
+  GitHubDispatch,
+  GitHubEventContext,
+  GitHubIssueEvent,
+  GitHubPullRequestAction,
+  GitHubPullRequestEvent,
+  GitHubPullRequestPayload,
+  GitHubRawEvent,
+  GitHubRepositoryRef,
+  GitHubStatusEvent,
+  GitHubTaskDispatch,
+  GitHubTurnDispatch,
+  GitHubUser,
+  GitHubWorkflowRunEvent,
+} from "./types.js";
+
+/**
+ * Inbound context as produced by the payload parsers, before the GitHub API +
+ * thread handles are attached. {@link enrichEventContext} adds `github`,
+ * `thread`, and `host` to make a full {@link GitHubEventContext} for hooks.
+ */
+type GitHubParsedContext = Omit<
+  GitHubEventContext,
+  "github" | "thread" | "host"
+>;
+
+const DEFAULT_PULL_REQUEST_ACTIONS: ReadonlySet<string> = new Set([
+  "opened",
+  "reopened",
+  "synchronize",
+  "ready_for_review",
+]);
+
+const repositorySchema = z.object({
+  id: z.number().optional(),
+  full_name: z.string().min(1),
+  html_url: z.string().url(),
+  name: z.string().optional(),
+  owner: z
+    .object({
+      login: z.string().optional(),
+    })
+    .optional(),
+});
+
+const senderSchema = z
+  .object({
+    login: z.string().min(1).optional(),
+    id: z.number().optional(),
+    type: z.string().optional(),
+  })
+  .nullable()
+  .optional();
+
+const installationSchema = z
+  .object({
+    id: z.number().optional(),
+  })
+  .nullable()
+  .optional();
+
+const githubPullRequestPayloadSchema: z.ZodType<GitHubPullRequestPayload> =
+  z.object({
+    action: z.string().min(1),
+    repository: repositorySchema,
+    pull_request: z.object({
+      number: z.number().int().positive(),
+      html_url: z.string().url(),
+      title: z.string(),
+      body: z.string().nullable().optional(),
+      draft: z.boolean().optional(),
+      user: z
+        .object({
+          login: z.string().min(1).optional(),
+          id: z.number().optional(),
+          type: z.string().optional(),
+        })
+        .nullable()
+        .optional(),
+      head: z.object({
+        ref: z.string().min(1),
+        sha: z.string().min(1),
+      }),
+      base: z.object({
+        ref: z.string().min(1),
+        sha: z.string().optional(),
+      }),
+    }),
+    sender: senderSchema,
+    installation: installationSchema,
+  });
+
+/**
+ * Derive the turn's auth from the actor that triggered the delivery — the
+ * standard `{ auth: defaultGitHubAuth(ctx) }` dispatch from an inbound hook.
+ */
+export function defaultGitHubAuth(ctx: GitHubParsedContext): AuthContext {
+  const senderId = ctx.sender?.id;
+  return {
+    authenticator: "github-webhook",
+    principalId:
+      senderId !== undefined
+        ? `github:${senderId}`
+        : (ctx.senderLogin ?? "github"),
+    principalType: ctx.sender?.type === "Bot" ? "service" : "user",
+    attributes: {
+      conversation_kind: ctx.conversation.kind,
+      ...(ctx.deliveryId === undefined ? {} : { delivery_id: ctx.deliveryId }),
+      ...(ctx.installationId === undefined
+        ? {}
+        : { installation_id: String(ctx.installationId) }),
+      repository: ctx.repository.fullName,
+      ...(ctx.repository.id === undefined
+        ? {}
+        : { repository_id: String(ctx.repository.id) }),
+      ...(ctx.senderLogin === undefined ? {} : { user_login: ctx.senderLogin }),
+      ...(ctx.sender?.type === undefined ? {} : { user_type: ctx.sender.type }),
+      ...(ctx.repository.owner === ""
+        ? {}
+        : { issuer: `github:${ctx.repository.owner}` }),
+      ...(ctx.senderLogin === undefined ? {} : { subject: ctx.senderLogin }),
+    },
+  };
+}
+
+export function githubContinuationKey(ctx: GitHubParsedContext): string {
+  const kind = ctx.conversation.kind === "issue" ? "github-issue" : "github-pr";
+  return `${kind}:${ctx.repository.fullName}#${ctx.conversation.number}`;
+}
+
+/** @deprecated Prefer {@link githubContinuationKey}. */
+export function githubPullRequestContinuationKey(
+  ctx: GitHubParsedContext
+): string {
+  return githubContinuationKey(ctx);
+}
+
+export function defaultGitHubTitle(ctx: GitHubParsedContext): string {
+  return `GitHub ${ctx.repository.fullName}#${ctx.conversation.number}`;
+}
+
+/** @deprecated Prefer {@link defaultGitHubTitle}. */
+export function defaultGitHubPullRequestTitle(
+  ctx: GitHubParsedContext
+): string {
+  return defaultGitHubTitle(ctx);
+}
+
+export function defaultGitHubPullRequestMessage(
+  ctx: GitHubParsedContext,
+  pullRequest: GitHubPullRequestEvent
+): string {
+  return [
+    `GitHub pull request trigger: ${ctx.repository.fullName}#${pullRequest.number}`,
+    `Action: ${pullRequest.action}`,
+    `PR: ${pullRequest.url}`,
+    `Title: ${pullRequest.title}`,
+    `Head: ${pullRequest.headRef} (${pullRequest.headSha})`,
+    `Base: ${pullRequest.baseRef}`,
+    ...(pullRequest.authorLogin === undefined
+      ? []
+      : [`Author: ${pullRequest.authorLogin}`]),
+    ...(ctx.senderLogin === undefined ? [] : [`Sender: ${ctx.senderLogin}`]),
+    "",
+    "Handle this pull request event.",
+  ].join("\n");
+}
+
+/**
+ * Default dispatch gate when no `onPullRequest` hook is declared: the common
+ * review triggers start a turn as the delivery's actor.
+ *
+ * Eve has no default for `onPullRequest` (opt-in only). Agent-serve keeps this
+ * gate for backward compatibility with existing demos.
+ */
+export function defaultGitHubPullRequestDispatch(
+  ctx: GitHubParsedContext,
+  pullRequest: GitHubPullRequestEvent
+): GitHubTurnDispatch | null {
+  if (!DEFAULT_PULL_REQUEST_ACTIONS.has(pullRequest.action)) {
+    return null;
+  }
+  return { auth: defaultGitHubAuth(ctx) };
+}
+
+/**
+ * Default comment hook (Eve-compatible): dispatch only when the comment
+ * `@mention`s {@link botName}.
+ */
+export function defaultOnComment(
+  ctx: GitHubParsedContext,
+  comment: GitHubComment,
+  options: { botName?: string }
+): GitHubTurnDispatch | null {
+  if (
+    !shouldDispatchGitHubComment({
+      body: comment.body,
+      author: comment.author,
+      botName: options.botName,
+    })
+  ) {
+    return null;
+  }
+  return { auth: defaultGitHubAuth(ctx) };
+}
+
+function isTaskDispatch(
+  dispatch: GitHubDispatch
+): dispatch is GitHubTaskDispatch {
+  return "task" in dispatch;
+}
+
+export function shouldDispatchGitHubComment(args: {
+  body: string;
+  author?: GitHubUser;
+  botName?: string;
+}): boolean {
+  const botName = args.botName?.trim();
+  if (botName === undefined || botName === "") {
+    return false;
+  }
+  if (isGitHubAppBotAuthor(args.author, botName)) {
+    return false;
+  }
+  const mention = new RegExp(`(^|\\W)@${escapeRegExp(botName)}\\b`, "i");
+  return mention.test(args.body);
+}
+
+export function extractGitHubCommentTrigger(args: {
+  body: string;
+  botName?: string;
+}): { message: string } | undefined {
+  const botName = args.botName?.trim();
+  if (botName === undefined || botName === "") {
+    const trimmed = args.body.trim();
+    return trimmed === "" ? undefined : { message: trimmed };
+  }
+  const mention = new RegExp(`@${escapeRegExp(botName)}\\b[,:]?\\s*`, "i");
+  const stripped = args.body.replace(mention, "").trim();
+  if (stripped === "") {
+    return { message: args.body.trim() };
+  }
+  return { message: stripped };
+}
+
+export function parseGitHubPullRequestEvent(args: {
+  payload: unknown;
+  deliveryId?: string;
+}): { ctx: GitHubParsedContext; pullRequest: GitHubPullRequestEvent } | null {
+  const parsed = githubPullRequestPayloadSchema.safeParse(args.payload);
+  if (!parsed.success) {
+    return null;
+  }
+  const payload = parsed.data;
+  const repository = toRepositoryRef(payload.repository);
+  const sender = toUser(payload.sender);
+  const installationId = payload.installation?.id;
+  const ctx: GitHubParsedContext = {
+    ...(args.deliveryId === undefined ? {} : { deliveryId: args.deliveryId }),
+    eventName: "pull_request",
+    repository,
+    conversation: {
+      kind: "pull_request",
+      number: payload.pull_request.number,
+      url: payload.pull_request.html_url,
+    },
+    ...(sender === undefined ? {} : { sender, senderLogin: sender.login }),
+    ...(installationId === undefined ? {} : { installationId }),
+  };
+  const pullRequest: GitHubPullRequestEvent = {
+    action: payload.action as GitHubPullRequestAction,
+    number: payload.pull_request.number,
+    url: payload.pull_request.html_url,
+    title: payload.pull_request.title,
+    ...(payload.pull_request.body === undefined ||
+    payload.pull_request.body === null
+      ? {}
+      : { body: payload.pull_request.body }),
+    headRef: payload.pull_request.head.ref,
+    headSha: payload.pull_request.head.sha,
+    baseRef: payload.pull_request.base.ref,
+    ...(payload.pull_request.base.sha === undefined
+      ? {}
+      : { baseSha: payload.pull_request.base.sha }),
+    draft: payload.pull_request.draft ?? false,
+    ...(payload.pull_request.user?.login === undefined
+      ? {}
+      : { authorLogin: payload.pull_request.user.login }),
+  };
+  return { ctx, pullRequest };
+}
+
+export async function verifyGitHubWebhookSignature(args: {
+  body: string;
+  signatureHeader: string | null;
+  secret: GitHubCredentialValue | undefined;
+}): Promise<"verified" | "missing_secret" | "missing_signature" | "mismatch"> {
+  const secret = await resolveCredentialValue(args.secret);
+  if (secret === undefined || secret === "") {
+    return "missing_secret";
+  }
+  if (args.signatureHeader === null) {
+    return "missing_signature";
+  }
+  const isVerified = verifyWebhookSha256Signature({
+    secret,
+    body: args.body,
+    signatureHeader: args.signatureHeader,
+  });
+  return isVerified ? "verified" : "mismatch";
+}
+
+function verifyWebhookSha256Signature(args: {
+  secret: string;
+  body: string;
+  signatureHeader: string;
+}): boolean {
+  const prefix = "sha256=";
+  if (!args.signatureHeader.startsWith(prefix)) {
+    return false;
+  }
+
+  const receivedHex = args.signatureHeader.slice(prefix.length);
+  if (!/^[0-9a-f]+$/i.test(receivedHex) || receivedHex.length % 2 !== 0) {
+    return false;
+  }
+
+  const expected = createHmac("sha256", args.secret).update(args.body).digest();
+  const received = Buffer.from(receivedHex, "hex");
+  return (
+    received.length === expected.length && timingSafeEqual(received, expected)
+  );
+}
+
+/**
+ * GitHub webhook channel (Eve-compatible dispatch surface). Point a GitHub App
+ * or repository webhook at `/<agent>/v1/channels/github` and declare inbound
+ * hooks:
+ *
+ * ```ts
+ * import { defaultGitHubAuth, githubChannel } from "@anysphere/agent-serve/channels/github";
+ *
+ * export default githubChannel({
+ *   botName: "my-agent",
+ *   credentials: { webhookSecret: () => process.env.GITHUB_WEBHOOK_SECRET },
+ *   // Replaces the @mention gate. Prefer typed Octokit via getOctokit().
+ *   onComment: (ctx, comment) => ({ auth: defaultGitHubAuth(ctx) }),
+ *   onPullRequest: (ctx, pr) =>
+ *     pr.action === "opened" ? { auth: defaultGitHubAuth(ctx) } : null,
+ *   onStatus: (ctx, status) =>
+ *     status.state === "failure"
+ *       ? {
+ *           task: async () => {
+ *             const octokit = await ctx.github.getOctokit();
+ *             await octokit.rest.repos.createCommitStatus({
+ *               owner: ctx.repository.owner,
+ *               repo: ctx.repository.name,
+ *               sha: status.sha,
+ *               state: "pending",
+ *               context: "agent/triage",
+ *             });
+ *           },
+ *         }
+ *       : null,
+ *   onEvent: (ctx, event) =>
+ *     event.eventName === "label" ? { auth: defaultGitHubAuth(ctx) } : null,
+ * });
+ * ```
+ */
+/**
+ * Core GitHub webhook dispatch used by {@link githubChannel} routes and by
+ * {@link handleAgentServeTrigger} fan-out. Signature verification is the
+ * caller's responsibility (HTTP route verifies; internal fan-out skips).
+ */
+export async function dispatchGitHubWebhook(input: {
+  options: GitHubChannelOptions;
+  eventName: string | null;
+  payload: unknown;
+  deliveryId?: string;
+  args: ChannelHandlerArgs;
+}): Promise<Response> {
+  const { options, eventName, payload, deliveryId, args } = input;
+  const botName = options.botName ?? process.env.GITHUB_APP_SLUG;
+  const bindingConfig: GitHubBindingConfig = {
+    api: options.api,
+    credentials: options.credentials,
+  };
+
+  if (eventName === "ping") {
+    return Response.json({ ok: true, event: "ping" });
+  }
+
+  switch (eventName) {
+    case "pull_request":
+      return handlePullRequest({
+        options,
+        bindingConfig,
+        payload,
+        deliveryId,
+        args,
+      });
+    case "issue_comment":
+      return handleIssueComment({
+        options,
+        bindingConfig,
+        botName,
+        payload,
+        deliveryId,
+        args,
+      });
+    case "pull_request_review_comment":
+      return handleReviewComment({
+        options,
+        bindingConfig,
+        botName,
+        payload,
+        deliveryId,
+        args,
+      });
+    case "issues":
+      return handleIssue({
+        options,
+        bindingConfig,
+        payload,
+        deliveryId,
+        args,
+      });
+    case "check_suite":
+      return handleCheckSuite({
+        options,
+        bindingConfig,
+        payload,
+        deliveryId,
+        args,
+      });
+    case "check_run":
+      return handleCheckRun({
+        options,
+        bindingConfig,
+        payload,
+        deliveryId,
+        args,
+      });
+    case "workflow_run":
+      return handleWorkflowRun({
+        options,
+        bindingConfig,
+        payload,
+        deliveryId,
+        args,
+      });
+    case "status":
+      return handleStatus({
+        options,
+        bindingConfig,
+        payload,
+        deliveryId,
+        args,
+      });
+    default:
+      if (options.onEvent !== undefined && eventName !== null) {
+        return handleGenericEvent({
+          options,
+          bindingConfig,
+          eventName,
+          payload,
+          deliveryId,
+          args,
+        });
+      }
+      return Response.json({
+        ok: true,
+        skipped: true,
+        reason: "unsupported_event",
+        event: eventName,
+      });
+  }
+}
+
+/**
+ * HTTP entry for a single agent's GitHub channel: optional HMAC verify, then
+ * {@link dispatchGitHubWebhook}.
+ */
+export async function handleGitHubWebhookRequest(input: {
+  options: GitHubChannelOptions;
+  request: Request;
+  args: ChannelHandlerArgs;
+  /** When true, skip HMAC even if a webhook secret is configured. */
+  skipSignatureVerification?: boolean;
+}): Promise<Response> {
+  const bodyText = await input.request.text();
+  const webhookSecret =
+    input.options.credentials?.webhookSecret ?? envWebhookSecret();
+
+  if (webhookSecret !== undefined && input.skipSignatureVerification !== true) {
+    const signatureResult = await verifyGitHubWebhookSignature({
+      body: bodyText,
+      signatureHeader: input.request.headers.get("x-hub-signature-256"),
+      secret: webhookSecret,
+    });
+    if (signatureResult !== "verified") {
+      return Response.json(
+        { ok: false, error: signatureResult },
+        { status: 401 }
+      );
+    }
+  }
+
+  let payload: unknown;
+  try {
+    payload = JSON.parse(bodyText) as unknown;
+  } catch {
+    return Response.json({ ok: false, error: "invalid_json" }, { status: 400 });
+  }
+
+  return dispatchGitHubWebhook({
+    options: input.options,
+    eventName: input.request.headers.get("x-github-event"),
+    payload,
+    deliveryId: input.request.headers.get("x-github-delivery") ?? undefined,
+    args: input.args,
+  });
+}
+
+/** Options used to construct a github channel — for host-level fan-out. */
+const githubChannelOptionsByDefinition = new WeakMap<
+  object,
+  GitHubChannelOptions
+>();
+
+/**
+ * Recover the {@link GitHubChannelOptions} used to build a channel definition,
+ * if it was created via {@link githubChannel}.
+ */
+export function getGitHubChannelOptions(
+  definition: object
+): GitHubChannelOptions | undefined {
+  return githubChannelOptionsByDefinition.get(definition);
+}
+
+export function githubChannel(
+  options: GitHubChannelOptions = {}
+): ChannelDefinition<GitHubChannelState> {
+  const routePath = options.path ?? "/";
+  const webhookSecret =
+    options.credentials?.webhookSecret ?? envWebhookSecret();
+  // With a secret the HMAC is the request auth (allowAll). Without one, prod
+  // stays loopback-strict; dev admits unsigned deliveries from a loopback peer
+  // only (loopbackGitHubDev) — not the LAN. Admits `gh webhook forward`
+  // deliveries (loopback peer + GitHub forwarding/delivery headers) while
+  // rejecting loopback tunnels that relay unsigned traffic without
+  // `X-GitHub-Event`.
+  //
+  // Evaluate `isDevMode()` per request (not at channel construction): channel
+  // modules call `githubChannel()` at import, and discovery may cache the
+  // definition across serve() calls. `serve()` sets the flag before discovery,
+  // but request-time lookup stays correct if that ordering ever drifts.
+  const auth =
+    options.auth ??
+    (webhookSecret !== undefined
+      ? [allowAll()]
+      : [
+          (request, info) =>
+            (isDevMode() ? loopbackGitHubDev() : localDevStrict())(
+              request,
+              info
+            ),
+        ]);
+
+  const events: ChannelEventHandlers<GitHubChannelState> = {
+    ...buildDefaultGitHubEvents({ ...options }),
+    ...options.events,
+  };
+
+  const definition = defineChannel({
+    auth,
+    state: emptyGitHubChannelState(),
+    events,
+    meta: {
+      kind: GITHUB_CHANNEL_KIND,
+      githubWebhookEvents: deriveGitHubWebhookEvents(options),
+    },
+    onStart: options.onStart,
+    onStop: options.onStop,
+    routes: [
+      POST(routePath, {
+        // Webhook payloads vary by `X-GitHub-Event`; event-specific Zod
+        // parsing happens inside the dispatcher. Require a schema at the
+        // route boundary so /v1/info + Try always have something to show.
+        bodySchema: z.unknown(),
+        description: "GitHub webhook ingress",
+        handler: async (request, args) =>
+          handleGitHubWebhookRequest({ options, request, args }),
+      }),
+    ],
+  });
+  githubChannelOptionsByDefinition.set(definition, options);
+  return definition;
+}
+
+async function handlePullRequest(input: {
+  options: GitHubChannelOptions;
+  bindingConfig: GitHubBindingConfig;
+  payload: unknown;
+  deliveryId?: string;
+  args: ChannelHandlerArgs;
+}): Promise<Response> {
+  const parsed = parseGitHubPullRequestEvent({
+    payload: input.payload,
+    deliveryId: input.deliveryId,
+  });
+  if (parsed === null) {
+    return Response.json(
+      { ok: false, error: "invalid_pull_request_payload" },
+      { status: 400 }
+    );
+  }
+  const { pullRequest } = parsed;
+  const installationId =
+    readInstallationId(input.payload) ?? parsed.ctx.installationId;
+  const binding = githubBindingStateForEvent({
+    kind: parsed.ctx.conversation.kind,
+    owner: parsed.ctx.repository.owner,
+    repo: parsed.ctx.repository.name,
+    number: parsed.ctx.conversation.number,
+    repositoryId: parsed.ctx.repository.id,
+    installationId,
+  });
+  const ctx = enrichEventContext({
+    bindingConfig: input.bindingConfig,
+    ctx: parsed.ctx,
+    bindingState: binding,
+    installationId,
+    host: input.args.host,
+  });
+  const dispatch =
+    input.options.onPullRequest === undefined
+      ? defaultGitHubPullRequestDispatch(ctx, pullRequest)
+      : await input.options.onPullRequest(ctx, pullRequest);
+  if (dispatch === null) {
+    return skipped("not_dispatched", { action: pullRequest.action });
+  }
+
+  if (isTaskDispatch(dispatch)) {
+    return acknowledgeTask(input.args, dispatch, {
+      action: pullRequest.action,
+      prUrl: pullRequest.url,
+      headSha: pullRequest.headSha,
+    });
+  }
+
+  const message = [
+    dispatch.message ?? defaultGitHubPullRequestMessage(ctx, pullRequest),
+    ...(dispatch.context ?? []),
+  ].join("\n");
+  const cloud = await resolveCloudOptions(
+    input.options.cloud,
+    ctx,
+    pullRequest
+  );
+  return startTurn({
+    args: input.args,
+    ctx,
+    message,
+    dispatch,
+    cloud,
+    state: sessionStateFromBinding({
+      binding,
+      deliveryId: ctx.deliveryId,
+      eventName: ctx.eventName,
+      headSha: pullRequest.headSha,
+      baseRef: pullRequest.baseRef,
+      headRef: pullRequest.headRef,
+    }),
+  });
+}
+
+async function handleIssueComment(input: {
+  options: GitHubChannelOptions;
+  bindingConfig: GitHubBindingConfig;
+  botName?: string;
+  payload: unknown;
+  deliveryId?: string;
+  args: ChannelHandlerArgs;
+}): Promise<Response> {
+  const parsed = parseIssueCommentEvent({
+    payload: input.payload,
+    deliveryId: input.deliveryId,
+  });
+  if (parsed === null) {
+    return Response.json(
+      { ok: false, error: "invalid_issue_comment_payload" },
+      { status: 400 }
+    );
+  }
+  if (parsed.action !== "created") {
+    return skipped("not_dispatched", { action: parsed.action });
+  }
+  if (
+    isIgnoredInboundComment(
+      parsed.comment.body,
+      parsed.comment.author,
+      input.botName
+    )
+  ) {
+    return skipped("ignored_comment");
+  }
+
+  const installationId =
+    readInstallationId(input.payload) ?? parsed.ctx.installationId;
+  const binding = githubBindingStateForEvent({
+    kind: parsed.ctx.conversation.kind,
+    owner: parsed.ctx.repository.owner,
+    repo: parsed.ctx.repository.name,
+    number: parsed.ctx.conversation.number,
+    repositoryId: parsed.ctx.repository.id,
+    installationId,
+    triggeringCommentId: parsed.comment.id,
+  });
+  const ctx = enrichEventContext({
+    bindingConfig: input.bindingConfig,
+    ctx: parsed.ctx,
+    bindingState: binding,
+    installationId,
+    host: input.args.host,
+  });
+
+  const dispatch =
+    input.options.onComment === undefined
+      ? defaultOnComment(ctx, parsed.comment, {
+          botName: input.botName,
+        })
+      : await input.options.onComment(ctx, parsed.comment);
+  if (dispatch === null) {
+    return skipped("not_dispatched");
+  }
+  if (isTaskDispatch(dispatch)) {
+    return acknowledgeTask(input.args, dispatch, {
+      event: "issue_comment",
+      action: parsed.action,
+    });
+  }
+
+  const trigger = extractGitHubCommentTrigger({
+    body: parsed.comment.body,
+    botName: input.botName,
+  });
+  const message = [
+    dispatch.message ?? trigger?.message ?? parsed.comment.body.trim(),
+    ...(dispatch.context ?? []),
+  ].join("\n");
+
+  return startTurn({
+    args: input.args,
+    ctx,
+    message,
+    dispatch,
+    state: sessionStateFromBinding({
+      binding,
+      deliveryId: ctx.deliveryId,
+      eventName: ctx.eventName,
+    }),
+  });
+}
+
+async function handleReviewComment(input: {
+  options: GitHubChannelOptions;
+  bindingConfig: GitHubBindingConfig;
+  botName?: string;
+  payload: unknown;
+  deliveryId?: string;
+  args: ChannelHandlerArgs;
+}): Promise<Response> {
+  const parsed = parseReviewCommentEvent({
+    payload: input.payload,
+    deliveryId: input.deliveryId,
+  });
+  if (parsed === null) {
+    return Response.json(
+      { ok: false, error: "invalid_review_comment_payload" },
+      { status: 400 }
+    );
+  }
+  if (parsed.action !== "created") {
+    return skipped("not_dispatched", { action: parsed.action });
+  }
+  if (
+    isIgnoredInboundComment(
+      parsed.comment.body,
+      parsed.comment.author,
+      input.botName
+    )
+  ) {
+    return skipped("ignored_comment");
+  }
+
+  const installationId =
+    readInstallationId(input.payload) ?? parsed.ctx.installationId;
+  const binding = githubBindingStateForEvent({
+    kind: parsed.ctx.conversation.kind,
+    owner: parsed.ctx.repository.owner,
+    repo: parsed.ctx.repository.name,
+    number: parsed.ctx.conversation.number,
+    repositoryId: parsed.ctx.repository.id,
+    installationId,
+    triggeringCommentId: parsed.comment.id,
+    reviewCommentId: parsed.comment.id,
+    reviewThreadRootCommentId: parsed.comment.inReplyToId ?? parsed.comment.id,
+  });
+  const ctx = enrichEventContext({
+    bindingConfig: input.bindingConfig,
+    ctx: parsed.ctx,
+    bindingState: binding,
+    installationId,
+    host: input.args.host,
+  });
+
+  const dispatch =
+    input.options.onComment === undefined
+      ? defaultOnComment(ctx, parsed.comment, {
+          botName: input.botName,
+        })
+      : await input.options.onComment(ctx, parsed.comment);
+  if (dispatch === null) {
+    return skipped("not_dispatched");
+  }
+  if (isTaskDispatch(dispatch)) {
+    return acknowledgeTask(input.args, dispatch, {
+      event: "pull_request_review_comment",
+      action: parsed.action,
+    });
+  }
+
+  const trigger = extractGitHubCommentTrigger({
+    body: parsed.comment.body,
+    botName: input.botName,
+  });
+  const message = [
+    dispatch.message ?? trigger?.message ?? parsed.comment.body.trim(),
+    ...(dispatch.context ?? []),
+  ].join("\n");
+
+  return startTurn({
+    args: input.args,
+    ctx,
+    message,
+    dispatch,
+    state: sessionStateFromBinding({
+      binding,
+      deliveryId: ctx.deliveryId,
+      eventName: ctx.eventName,
+    }),
+  });
+}
+
+async function handleIssue(input: {
+  options: GitHubChannelOptions;
+  bindingConfig: GitHubBindingConfig;
+  payload: unknown;
+  deliveryId?: string;
+  args: ChannelHandlerArgs;
+}): Promise<Response> {
+  if (input.options.onIssue === undefined) {
+    return skipped("no_handler", { event: "issues" });
+  }
+  const parsed = parseIssueEvent({
+    payload: input.payload,
+    deliveryId: input.deliveryId,
+  });
+  if (parsed === null) {
+    return Response.json(
+      { ok: false, error: "invalid_issues_payload" },
+      { status: 400 }
+    );
+  }
+  const installationId =
+    readInstallationId(input.payload) ?? parsed.ctx.installationId;
+  const binding = githubBindingStateForEvent({
+    kind: parsed.ctx.conversation.kind,
+    owner: parsed.ctx.repository.owner,
+    repo: parsed.ctx.repository.name,
+    number: parsed.ctx.conversation.number,
+    repositoryId: parsed.ctx.repository.id,
+    installationId,
+  });
+  const ctx = enrichEventContext({
+    bindingConfig: input.bindingConfig,
+    ctx: parsed.ctx,
+    bindingState: binding,
+    installationId,
+    host: input.args.host,
+  });
+  const dispatch = await input.options.onIssue(ctx, parsed.issue);
+  if (dispatch === null) {
+    return skipped("not_dispatched", { action: parsed.issue.action });
+  }
+  if (isTaskDispatch(dispatch)) {
+    return acknowledgeTask(input.args, dispatch, {
+      event: "issues",
+      action: parsed.issue.action,
+      issueNumber: parsed.issue.number,
+    });
+  }
+  const message = [
+    dispatch.message ??
+      `Issue ${parsed.issue.action}: #${parsed.issue.number} ${parsed.issue.title}`,
+    ...(dispatch.context ?? []),
+  ].join("\n");
+  return startTurn({
+    args: input.args,
+    ctx,
+    message,
+    dispatch,
+    state: sessionStateFromBinding({
+      binding,
+      deliveryId: ctx.deliveryId,
+      eventName: ctx.eventName,
+    }),
+  });
+}
+
+async function handleCheckSuite(input: {
+  options: GitHubChannelOptions;
+  bindingConfig: GitHubBindingConfig;
+  payload: unknown;
+  deliveryId?: string;
+  args: ChannelHandlerArgs;
+}): Promise<Response> {
+  if (input.options.onCheckSuite === undefined) {
+    return skipped("no_handler", { event: "check_suite" });
+  }
+  const parsed = parseCheckSuiteEvent({
+    payload: input.payload,
+    deliveryId: input.deliveryId,
+  });
+  if (parsed === null) {
+    return Response.json(
+      { ok: false, error: "invalid_check_suite_payload" },
+      { status: 400 }
+    );
+  }
+  const installationId =
+    readInstallationId(input.payload) ?? parsed.unanchoredCtx.installationId;
+  if (parsed.ctx === null) {
+    const dispatch = await input.options.onCheckSuite(
+      enrichCiContext({
+        bindingConfig: input.bindingConfig,
+        ctx: parsed.unanchoredCtx,
+        installationId,
+        host: input.args.host,
+      }),
+      parsed.checkSuite
+    );
+    if (dispatch !== null && isTaskDispatch(dispatch)) {
+      return acknowledgeTask(input.args, dispatch, {
+        event: "check_suite",
+        action: parsed.checkSuite.action,
+        checkSuiteId: parsed.checkSuite.checkSuiteId,
+      });
+    }
+    return skipped("no_pull_request", { event: "check_suite" });
+  }
+  const binding = githubBindingStateForEvent({
+    kind: parsed.ctx.conversation.kind,
+    owner: parsed.ctx.repository.owner,
+    repo: parsed.ctx.repository.name,
+    number: parsed.ctx.conversation.number,
+    repositoryId: parsed.ctx.repository.id,
+    installationId,
+  });
+  const ctx = enrichEventContext({
+    bindingConfig: input.bindingConfig,
+    ctx: parsed.ctx,
+    bindingState: binding,
+    installationId,
+    host: input.args.host,
+  });
+  const dispatch = await input.options.onCheckSuite(ctx, parsed.checkSuite);
+  if (dispatch === null) {
+    return skipped("not_dispatched", { action: parsed.checkSuite.action });
+  }
+  if (isTaskDispatch(dispatch)) {
+    return acknowledgeTask(input.args, dispatch, {
+      event: "check_suite",
+      action: parsed.checkSuite.action,
+      checkSuiteId: parsed.checkSuite.checkSuiteId,
+    });
+  }
+  const message = [
+    dispatch.message ??
+      formatCiMessage(
+        "Check suite",
+        parsed.checkSuite.checkSuiteId,
+        parsed.checkSuite
+      ),
+    ...(dispatch.context ?? []),
+  ].join("\n");
+  return startTurn({
+    args: input.args,
+    ctx,
+    message,
+    dispatch,
+    state: sessionStateFromBinding({
+      binding,
+      deliveryId: ctx.deliveryId,
+      eventName: ctx.eventName,
+      headSha: parsed.checkSuite.headSha,
+    }),
+  });
+}
+
+async function handleCheckRun(input: {
+  options: GitHubChannelOptions;
+  bindingConfig: GitHubBindingConfig;
+  payload: unknown;
+  deliveryId?: string;
+  args: ChannelHandlerArgs;
+}): Promise<Response> {
+  if (input.options.onCheckRun === undefined) {
+    return skipped("no_handler", { event: "check_run" });
+  }
+  const parsed = parseCheckRunEvent({
+    payload: input.payload,
+    deliveryId: input.deliveryId,
+  });
+  if (parsed === null) {
+    return Response.json(
+      { ok: false, error: "invalid_check_run_payload" },
+      { status: 400 }
+    );
+  }
+  const installationId =
+    readInstallationId(input.payload) ?? parsed.unanchoredCtx.installationId;
+  if (parsed.ctx === null) {
+    const dispatch = await input.options.onCheckRun(
+      enrichCiContext({
+        bindingConfig: input.bindingConfig,
+        ctx: parsed.unanchoredCtx,
+        installationId,
+        host: input.args.host,
+      }),
+      parsed.checkRun
+    );
+    if (dispatch !== null && isTaskDispatch(dispatch)) {
+      return acknowledgeTask(input.args, dispatch, {
+        event: "check_run",
+        action: parsed.checkRun.action,
+        checkRunId: parsed.checkRun.checkRunId,
+      });
+    }
+    return skipped("no_pull_request", { event: "check_run" });
+  }
+  const binding = githubBindingStateForEvent({
+    kind: parsed.ctx.conversation.kind,
+    owner: parsed.ctx.repository.owner,
+    repo: parsed.ctx.repository.name,
+    number: parsed.ctx.conversation.number,
+    repositoryId: parsed.ctx.repository.id,
+    installationId,
+  });
+  const ctx = enrichEventContext({
+    bindingConfig: input.bindingConfig,
+    ctx: parsed.ctx,
+    bindingState: binding,
+    installationId,
+    host: input.args.host,
+  });
+  const dispatch = await input.options.onCheckRun(ctx, parsed.checkRun);
+  if (dispatch === null) {
+    return skipped("not_dispatched", { action: parsed.checkRun.action });
+  }
+  if (isTaskDispatch(dispatch)) {
+    return acknowledgeTask(input.args, dispatch, {
+      event: "check_run",
+      action: parsed.checkRun.action,
+      checkRunId: parsed.checkRun.checkRunId,
+    });
+  }
+  const message = [
+    dispatch.message ??
+      formatCiMessage("Check run", parsed.checkRun.checkRunId, parsed.checkRun),
+    ...(dispatch.context ?? []),
+  ].join("\n");
+  return startTurn({
+    args: input.args,
+    ctx,
+    message,
+    dispatch,
+    state: sessionStateFromBinding({
+      binding,
+      deliveryId: ctx.deliveryId,
+      eventName: ctx.eventName,
+      headSha: parsed.checkRun.headSha,
+    }),
+  });
+}
+
+async function handleWorkflowRun(input: {
+  options: GitHubChannelOptions;
+  bindingConfig: GitHubBindingConfig;
+  payload: unknown;
+  deliveryId?: string;
+  args: ChannelHandlerArgs;
+}): Promise<Response> {
+  if (input.options.onWorkflowRun === undefined) {
+    return skipped("no_handler", { event: "workflow_run" });
+  }
+  const parsed = parseWorkflowRunEvent({
+    payload: input.payload,
+    deliveryId: input.deliveryId,
+  });
+  if (parsed === null) {
+    return Response.json(
+      { ok: false, error: "invalid_workflow_run_payload" },
+      { status: 400 }
+    );
+  }
+  const installationId =
+    readInstallationId(input.payload) ?? parsed.unanchoredCtx.installationId;
+  if (parsed.ctx === null) {
+    const dispatch = await input.options.onWorkflowRun(
+      enrichCiContext({
+        bindingConfig: input.bindingConfig,
+        ctx: parsed.unanchoredCtx,
+        installationId,
+        host: input.args.host,
+      }),
+      parsed.workflowRun
+    );
+    if (dispatch !== null && isTaskDispatch(dispatch)) {
+      return acknowledgeTask(input.args, dispatch, {
+        event: "workflow_run",
+        action: parsed.workflowRun.action,
+        workflowRunId: parsed.workflowRun.workflowRunId,
+      });
+    }
+    return skipped("no_pull_request", { event: "workflow_run" });
+  }
+  const binding = githubBindingStateForEvent({
+    kind: parsed.ctx.conversation.kind,
+    owner: parsed.ctx.repository.owner,
+    repo: parsed.ctx.repository.name,
+    number: parsed.ctx.conversation.number,
+    repositoryId: parsed.ctx.repository.id,
+    installationId,
+  });
+  const ctx = enrichEventContext({
+    bindingConfig: input.bindingConfig,
+    ctx: parsed.ctx,
+    bindingState: binding,
+    installationId,
+    host: input.args.host,
+  });
+  const dispatch = await input.options.onWorkflowRun(ctx, parsed.workflowRun);
+  if (dispatch === null) {
+    return skipped("not_dispatched", { action: parsed.workflowRun.action });
+  }
+  if (isTaskDispatch(dispatch)) {
+    return acknowledgeTask(input.args, dispatch, {
+      event: "workflow_run",
+      action: parsed.workflowRun.action,
+      workflowRunId: parsed.workflowRun.workflowRunId,
+    });
+  }
+  const message = [
+    dispatch.message ??
+      formatCiMessage(
+        "Workflow run",
+        parsed.workflowRun.workflowRunId,
+        parsed.workflowRun
+      ),
+    ...(dispatch.context ?? []),
+  ].join("\n");
+  return startTurn({
+    args: input.args,
+    ctx,
+    message,
+    dispatch,
+    state: sessionStateFromBinding({
+      binding,
+      deliveryId: ctx.deliveryId,
+      eventName: ctx.eventName,
+      headSha: parsed.workflowRun.headSha,
+    }),
+  });
+}
+
+async function handleStatus(input: {
+  options: GitHubChannelOptions;
+  bindingConfig: GitHubBindingConfig;
+  payload: unknown;
+  deliveryId?: string;
+  args: ChannelHandlerArgs;
+}): Promise<Response> {
+  if (input.options.onStatus === undefined) {
+    return skipped("no_handler", { event: "status" });
+  }
+  const parsed = parseStatusEvent({
+    payload: input.payload,
+    deliveryId: input.deliveryId,
+  });
+  if (parsed === null) {
+    return Response.json(
+      { ok: false, error: "invalid_status_payload" },
+      { status: 400 }
+    );
+  }
+  const installationId =
+    readInstallationId(input.payload) ?? parsed.ctx.installationId;
+  const binding = githubBindingStateForEvent({
+    kind: parsed.ctx.conversation.kind,
+    owner: parsed.ctx.repository.owner,
+    repo: parsed.ctx.repository.name,
+    number: parsed.ctx.conversation.number,
+    repositoryId: parsed.ctx.repository.id,
+    installationId,
+  });
+  const ctx = enrichEventContext({
+    bindingConfig: input.bindingConfig,
+    ctx: parsed.ctx,
+    bindingState: binding,
+    installationId,
+    host: input.args.host,
+  });
+  const dispatch = await input.options.onStatus(ctx, parsed.status);
+  if (dispatch === null) {
+    return skipped("not_dispatched", {
+      event: "status",
+      state: parsed.status.state,
+    });
+  }
+  if (isTaskDispatch(dispatch)) {
+    return acknowledgeTask(input.args, dispatch, {
+      event: "status",
+      state: parsed.status.state,
+      sha: parsed.status.sha,
+    });
+  }
+  // A turn needs a thread to anchor to; commit statuses often have no PR.
+  if (ctx.conversation.number === 0) {
+    return skipped("no_pull_request", { event: "status" });
+  }
+  const message = [
+    dispatch.message ??
+      `Commit status ${parsed.status.state} for ${parsed.status.context} at ${parsed.status.sha}`,
+    ...(dispatch.context ?? []),
+  ].join("\n");
+  return startTurn({
+    args: input.args,
+    ctx,
+    message,
+    dispatch,
+    state: sessionStateFromBinding({
+      binding,
+      deliveryId: ctx.deliveryId,
+      eventName: ctx.eventName,
+      headSha: parsed.status.sha,
+    }),
+  });
+}
+
+async function handleGenericEvent(input: {
+  options: GitHubChannelOptions;
+  bindingConfig: GitHubBindingConfig;
+  eventName: string;
+  payload: unknown;
+  deliveryId?: string;
+  args: ChannelHandlerArgs;
+}): Promise<Response> {
+  if (input.options.onEvent === undefined) {
+    return skipped("no_handler", { event: input.eventName });
+  }
+  const parsed = parseGenericEvent({
+    eventName: input.eventName,
+    payload: input.payload,
+    deliveryId: input.deliveryId,
+  });
+  if (parsed === null) {
+    return skipped("unsupported_event", { event: input.eventName });
+  }
+  const installationId =
+    readInstallationId(input.payload) ?? parsed.ctx.installationId;
+  const binding = githubBindingStateForEvent({
+    kind: parsed.ctx.conversation.kind,
+    owner: parsed.ctx.repository.owner,
+    repo: parsed.ctx.repository.name,
+    number: parsed.ctx.conversation.number,
+    repositoryId: parsed.ctx.repository.id,
+    installationId,
+  });
+  const ctx = enrichEventContext({
+    bindingConfig: input.bindingConfig,
+    ctx: parsed.ctx,
+    bindingState: binding,
+    installationId,
+    host: input.args.host,
+  });
+  const dispatch = await input.options.onEvent(ctx, parsed.event);
+  if (dispatch === null) {
+    return skipped("not_dispatched", { event: input.eventName });
+  }
+  if (isTaskDispatch(dispatch)) {
+    return acknowledgeTask(input.args, dispatch, {
+      event: input.eventName,
+      ...(parsed.event.action === undefined
+        ? {}
+        : { action: parsed.event.action }),
+    });
+  }
+  if (ctx.conversation.number === 0) {
+    return skipped("no_conversation", { event: input.eventName });
+  }
+  const message = [
+    dispatch.message ?? `GitHub ${input.eventName} event`,
+    ...(dispatch.context ?? []),
+  ].join("\n");
+  return startTurn({
+    args: input.args,
+    ctx,
+    message,
+    dispatch,
+    state: sessionStateFromBinding({
+      binding,
+      deliveryId: ctx.deliveryId,
+      eventName: ctx.eventName,
+    }),
+  });
+}
+
+async function startTurn(input: {
+  args: ChannelHandlerArgs;
+  ctx: GitHubEventContext;
+  message: string;
+  dispatch: GitHubTurnDispatch;
+  cloud?: AgentCloudOptions;
+  state: GitHubChannelState;
+}): Promise<Response> {
+  const session = await input.args.send(input.message, {
+    auth: input.dispatch.auth,
+    continuationToken: githubContinuationKey(input.ctx),
+    title: input.dispatch.title ?? defaultGitHubTitle(input.ctx),
+    ...(input.cloud === undefined ? {} : { cloud: input.cloud }),
+    state: input.state as unknown as JsonValue,
+  });
+  return Response.json({
+    ok: true,
+    sessionId: session.id,
+    isNew: session.isNew,
+    continuationToken: session.continuationToken,
+  });
+}
+
+function acknowledgeTask(
+  args: ChannelHandlerArgs,
+  dispatch: GitHubTaskDispatch,
+  extra: Record<string, unknown>
+): Response {
+  // Defer the task past the current turn so the 202 can flush before work
+  // starts (and so tests can assert scheduling without racing microtasks).
+  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 }
+  );
+}
+
+function skipped(
+  reason: string,
+  extra: Record<string, unknown> = {}
+): Response {
+  return Response.json({ ok: true, skipped: true, reason, ...extra });
+}
+
+function formatCiMessage(
+  label: string,
+  id: number,
+  event: { action: string; status?: string; conclusion?: string | null }
+): string {
+  const outcome = event.conclusion ?? event.status;
+  return `${label} ${event.action}: ${id}${outcome ? ` (${outcome})` : ""}`;
+}
+
+function isIgnoredInboundComment(
+  body: string,
+  author: GitHubUser | undefined,
+  botName: string | undefined
+): boolean {
+  if (body.includes("<!-- agent-serve-github -->")) {
+    return true;
+  }
+  if (isGitHubAppBotAuthor(author, botName)) {
+    return true;
+  }
+  return false;
+}
+
+/** Match GitHub App bot actors (`slug` config vs `slug[bot]` login). */
+export function isGitHubAppBotAuthor(
+  author: GitHubUser | undefined,
+  botName: string | undefined
+): boolean {
+  const normalizedBot = botName?.trim();
+  if (normalizedBot === undefined || normalizedBot === "") {
+    return false;
+  }
+  if (author?.type !== "Bot") {
+    return false;
+  }
+  const login = author.login;
+  const stripBotSuffix = (value: string): string =>
+    value.replace(/\[bot\]$/i, "").toLowerCase();
+  return (
+    login.toLowerCase() === normalizedBot.toLowerCase() ||
+    stripBotSuffix(login) === stripBotSuffix(normalizedBot)
+  );
+}
+
+function parseIssueCommentEvent(args: {
+  payload: unknown;
+  deliveryId?: string;
+}): {
+  action: string;
+  ctx: GitHubParsedContext;
+  comment: GitHubComment;
+} | null {
+  const schema = z.object({
+    action: z.string().min(1),
+    repository: repositorySchema,
+    issue: z.object({
+      number: z.number().int().positive(),
+      html_url: z.string().url(),
+      pull_request: z.unknown().optional(),
+    }),
+    comment: z.object({
+      id: z.number(),
+      body: z.string(),
+      html_url: z.string().url(),
+      url: z.string().url().optional(),
+      user: z
+        .object({
+          login: z.string().optional(),
+          id: z.number().optional(),
+          type: z.string().optional(),
+        })
+        .nullable()
+        .optional(),
+    }),
+    sender: senderSchema,
+    installation: installationSchema,
+  });
+  const parsed = schema.safeParse(args.payload);
+  if (!parsed.success) return null;
+  const payload = parsed.data;
+  const kind: GitHubConversationKind =
+    payload.issue.pull_request === undefined ? "issue" : "pull_request";
+  const repository = toRepositoryRef(payload.repository);
+  const sender = toUser(payload.sender);
+  const author = toUser(payload.comment.user);
+  const installationId = payload.installation?.id;
+  const ctx: GitHubParsedContext = {
+    ...(args.deliveryId === undefined ? {} : { deliveryId: args.deliveryId }),
+    eventName: "issue_comment",
+    repository,
+    conversation: {
+      kind,
+      number: payload.issue.number,
+      url: payload.issue.html_url,
+    },
+    ...(sender === undefined ? {} : { sender, senderLogin: sender.login }),
+    ...(installationId === undefined ? {} : { installationId }),
+  };
+  const comment: GitHubComment = {
+    id: payload.comment.id,
+    body: payload.comment.body,
+    htmlUrl: payload.comment.html_url,
+    url: payload.comment.url ?? payload.comment.html_url,
+    ...(author === undefined ? {} : { author }),
+  };
+  return { action: payload.action, ctx, comment };
+}
+
+function parseReviewCommentEvent(args: {
+  payload: unknown;
+  deliveryId?: string;
+}): {
+  action: string;
+  ctx: GitHubParsedContext;
+  comment: GitHubComment;
+} | null {
+  const schema = z.object({
+    action: z.string().min(1),
+    repository: repositorySchema,
+    pull_request: z.object({
+      number: z.number().int().positive(),
+      html_url: z.string().url(),
+    }),
+    comment: z.object({
+      id: z.number(),
+      body: z.string(),
+      html_url: z.string().url(),
+      url: z.string().url().optional(),
+      path: z.string().optional(),
+      line: z.number().nullable().optional(),
+      pull_request_review_id: z.number().nullable().optional(),
+      in_reply_to_id: z.number().optional(),
+      user: z
+        .object({
+          login: z.string().optional(),
+          id: z.number().optional(),
+          type: z.string().optional(),
+        })
+        .nullable()
+        .optional(),
+    }),
+    sender: senderSchema,
+    installation: installationSchema,
+  });
+  const parsed = schema.safeParse(args.payload);
+  if (!parsed.success) return null;
+  const payload = parsed.data;
+  const repository = toRepositoryRef(payload.repository);
+  const sender = toUser(payload.sender);
+  const author = toUser(payload.comment.user);
+  const installationId = payload.installation?.id;
+  const ctx: GitHubParsedContext = {
+    ...(args.deliveryId === undefined ? {} : { deliveryId: args.deliveryId }),
+    eventName: "pull_request_review_comment",
+    repository,
+    conversation: {
+      kind: "review_thread",
+      number: payload.pull_request.number,
+      url: payload.pull_request.html_url,
+    },
+    ...(sender === undefined ? {} : { sender, senderLogin: sender.login }),
+    ...(installationId === undefined ? {} : { installationId }),
+  };
+  const comment: GitHubComment = {
+    id: payload.comment.id,
+    body: payload.comment.body,
+    htmlUrl: payload.comment.html_url,
+    url: payload.comment.url ?? payload.comment.html_url,
+    ...(author === undefined ? {} : { author }),
+    ...(payload.comment.path === undefined
+      ? {}
+      : { path: payload.comment.path }),
+    ...(payload.comment.line === undefined
+      ? {}
+      : { line: payload.comment.line }),
+    ...(payload.comment.pull_request_review_id === undefined
+      ? {}
+      : { pullRequestReviewId: payload.comment.pull_request_review_id }),
+    ...(payload.comment.in_reply_to_id === undefined
+      ? {}
+      : { inReplyToId: payload.comment.in_reply_to_id }),
+  };
+  return { action: payload.action, ctx, comment };
+}
+
+function parseIssueEvent(args: {
+  payload: unknown;
+  deliveryId?: string;
+}): { ctx: GitHubParsedContext; issue: GitHubIssueEvent } | null {
+  const schema = z.object({
+    action: z.string().min(1),
+    repository: repositorySchema,
+    issue: z.object({
+      number: z.number().int().positive(),
+      html_url: z.string().url(),
+      title: z.string(),
+      body: z.string().nullable().optional(),
+      user: z
+        .object({
+          login: z.string().optional(),
+        })
+        .nullable()
+        .optional(),
+    }),
+    sender: senderSchema,
+    installation: installationSchema,
+  });
+  const parsed = schema.safeParse(args.payload);
+  if (!parsed.success) return null;
+  const payload = parsed.data;
+  const repository = toRepositoryRef(payload.repository);
+  const sender = toUser(payload.sender);
+  const installationId = payload.installation?.id;
+  const ctx: GitHubParsedContext = {
+    ...(args.deliveryId === undefined ? {} : { deliveryId: args.deliveryId }),
+    eventName: "issues",
+    repository,
+    conversation: {
+      kind: "issue",
+      number: payload.issue.number,
+      url: payload.issue.html_url,
+    },
+    ...(sender === undefined ? {} : { sender, senderLogin: sender.login }),
+    ...(installationId === undefined ? {} : { installationId }),
+  };
+  const issue: GitHubIssueEvent = {
+    action: payload.action,
+    number: payload.issue.number,
+    url: payload.issue.html_url,
+    title: payload.issue.title,
+    ...(payload.issue.body === undefined || payload.issue.body === null
+      ? {}
+      : { body: payload.issue.body }),
+    ...(payload.issue.user?.login === undefined
+      ? {}
+      : { authorLogin: payload.issue.user.login }),
+  };
+  return { ctx, issue };
+}
+
+function parseCheckSuiteEvent(args: {
+  payload: unknown;
+  deliveryId?: string;
+}): {
+  ctx: GitHubParsedContext | null;
+  unanchoredCtx: GitHubParsedContext;
+  checkSuite: GitHubCheckSuiteEvent;
+} | null {
+  const schema = z.object({
+    action: z.string().min(1),
+    repository: repositorySchema,
+    check_suite: z.object({
+      id: z.number(),
+      head_sha: z.string().min(1),
+      status: z.string().optional(),
+      conclusion: z.string().nullable().optional(),
+      app: z
+        .object({
+          slug: z.string().optional(),
+          name: z.string().optional(),
+        })
+        .nullable()
+        .optional(),
+      pull_requests: z
+        .array(
+          z.object({
+            number: z.number(),
+            url: z.string().optional(),
+            html_url: z.string().optional(),
+          })
+        )
+        .optional(),
+    }),
+    sender: senderSchema,
+    installation: installationSchema,
+  });
+  const parsed = schema.safeParse(args.payload);
+  if (!parsed.success) return null;
+  const payload = parsed.data;
+  const repository = toRepositoryRef(payload.repository);
+  const sender = toUser(payload.sender);
+  const installationId = payload.installation?.id;
+  const pullRequests = toCiPullRequests(payload.check_suite.pull_requests);
+  const checkSuite: GitHubCheckSuiteEvent = {
+    action: payload.action,
+    checkSuiteId: payload.check_suite.id,
+    headSha: payload.check_suite.head_sha,
+    ...(payload.check_suite.status === undefined
+      ? {}
+      : { status: payload.check_suite.status }),
+    conclusion: (payload.check_suite.conclusion ??
+      null) as GitHubCheckSuiteEvent["conclusion"],
+    app: toCiApp(payload.check_suite.app),
+    pullRequests,
+  };
+  const unanchoredCtx = unanchoredEventContext({
+    deliveryId: args.deliveryId,
+    eventName: "check_suite",
+    repository,
+    sender,
+    installationId,
+  });
+  const first = pullRequests[0];
+  if (first === undefined) {
+    return { ctx: null, unanchoredCtx, checkSuite };
+  }
+  return {
+    ctx: {
+      ...unanchoredCtx,
+      conversation: {
+        kind: "pull_request",
+        number: first.number,
+        url: first.url ?? `${repository.url}/pull/${first.number}`,
+      },
+    },
+    unanchoredCtx,
+    checkSuite,
+  };
+}
+
+function parseCheckRunEvent(args: { payload: unknown; deliveryId?: string }): {
+  ctx: GitHubParsedContext | null;
+  unanchoredCtx: GitHubParsedContext;
+  checkRun: GitHubCheckRunEvent;
+} | null {
+  const schema = z.object({
+    action: z.string().min(1),
+    repository: repositorySchema,
+    check_run: z.object({
+      id: z.number(),
+      name: z.string().optional(),
+      head_sha: z.string().min(1),
+      status: z.string().optional(),
+      conclusion: z.string().nullable().optional(),
+      html_url: z.string().optional(),
+      check_suite: z
+        .object({
+          id: z.number().optional(),
+        })
+        .optional(),
+      app: z
+        .object({
+          slug: z.string().optional(),
+          name: z.string().optional(),
+        })
+        .nullable()
+        .optional(),
+      pull_requests: z
+        .array(
+          z.object({
+            number: z.number(),
+            url: z.string().optional(),
+            html_url: z.string().optional(),
+          })
+        )
+        .optional(),
+    }),
+    sender: senderSchema,
+    installation: installationSchema,
+  });
+  const parsed = schema.safeParse(args.payload);
+  if (!parsed.success) return null;
+  const payload = parsed.data;
+  const repository = toRepositoryRef(payload.repository);
+  const sender = toUser(payload.sender);
+  const installationId = payload.installation?.id;
+  const pullRequests = toCiPullRequests(payload.check_run.pull_requests);
+  const checkRun: GitHubCheckRunEvent = {
+    action: payload.action,
+    checkRunId: payload.check_run.id,
+    headSha: payload.check_run.head_sha,
+    ...(payload.check_run.name === undefined
+      ? {}
+      : { name: payload.check_run.name }),
+    ...(payload.check_run.check_suite?.id === undefined
+      ? {}
+      : { checkSuiteId: payload.check_run.check_suite.id }),
+    ...(payload.check_run.status === undefined
+      ? {}
+      : { status: payload.check_run.status }),
+    conclusion: (payload.check_run.conclusion ??
+      null) as GitHubCheckRunEvent["conclusion"],
+    app: toCiApp(payload.check_run.app),
+    pullRequests,
+  };
+  const unanchoredCtx = unanchoredEventContext({
+    deliveryId: args.deliveryId,
+    eventName: "check_run",
+    repository,
+    sender,
+    installationId,
+  });
+  const first = pullRequests[0];
+  if (first === undefined) {
+    return { ctx: null, unanchoredCtx, checkRun };
+  }
+  return {
+    ctx: {
+      ...unanchoredCtx,
+      conversation: {
+        kind: "pull_request",
+        number: first.number,
+        url: first.url ?? `${repository.url}/pull/${first.number}`,
+      },
+    },
+    unanchoredCtx,
+    checkRun,
+  };
+}
+
+function parseWorkflowRunEvent(args: {
+  payload: unknown;
+  deliveryId?: string;
+}): {
+  ctx: GitHubParsedContext | null;
+  unanchoredCtx: GitHubParsedContext;
+  workflowRun: GitHubWorkflowRunEvent;
+} | null {
+  const schema = z.object({
+    action: z.string().min(1),
+    repository: repositorySchema,
+    workflow_run: z.object({
+      id: z.number(),
+      name: z.string().nullable().optional(),
+      workflow_id: z.number().optional(),
+      head_sha: z.string().min(1),
+      status: z.string().optional(),
+      conclusion: z.string().nullable().optional(),
+      html_url: z.string().optional(),
+      pull_requests: z
+        .array(
+          z.object({
+            number: z.number(),
+            url: z.string().optional(),
+            html_url: z.string().optional(),
+          })
+        )
+        .optional(),
+    }),
+    sender: senderSchema,
+    installation: installationSchema,
+  });
+  const parsed = schema.safeParse(args.payload);
+  if (!parsed.success) return null;
+  const payload = parsed.data;
+  const repository = toRepositoryRef(payload.repository);
+  const sender = toUser(payload.sender);
+  const installationId = payload.installation?.id;
+  const pullRequests = toCiPullRequests(payload.workflow_run.pull_requests);
+  const workflowRun: GitHubWorkflowRunEvent = {
+    action: payload.action,
+    workflowRunId: payload.workflow_run.id,
+    headSha: payload.workflow_run.head_sha,
+    ...(payload.workflow_run.name === undefined ||
+    payload.workflow_run.name === null
+      ? {}
+      : { name: payload.workflow_run.name }),
+    ...(payload.workflow_run.workflow_id === undefined
+      ? {}
+      : { workflowId: payload.workflow_run.workflow_id }),
+    ...(payload.workflow_run.html_url === undefined
+      ? {}
+      : { htmlUrl: payload.workflow_run.html_url }),
+    ...(payload.workflow_run.status === undefined
+      ? {}
+      : { status: payload.workflow_run.status }),
+    conclusion: (payload.workflow_run.conclusion ??
+      null) as GitHubWorkflowRunEvent["conclusion"],
+    // workflow_run is GitHub Actions-only (Eve semantics).
+    app: { slug: "github-actions", name: "GitHub Actions" },
+    pullRequests,
+  };
+  const unanchoredCtx = unanchoredEventContext({
+    deliveryId: args.deliveryId,
+    eventName: "workflow_run",
+    repository,
+    sender,
+    installationId,
+  });
+  const first = pullRequests[0];
+  if (first === undefined) {
+    return { ctx: null, unanchoredCtx, workflowRun };
+  }
+  return {
+    ctx: {
+      ...unanchoredCtx,
+      conversation: {
+        kind: "pull_request",
+        number: first.number,
+        url: first.url ?? `${repository.url}/pull/${first.number}`,
+      },
+    },
+    unanchoredCtx,
+    workflowRun,
+  };
+}
+
+function parseStatusEvent(args: {
+  payload: unknown;
+  deliveryId?: string;
+}): { ctx: GitHubParsedContext; status: GitHubStatusEvent } | null {
+  const schema = z.object({
+    state: z.string().min(1),
+    sha: z.string().min(1),
+    context: z.string().optional(),
+    description: z.string().nullable().optional(),
+    target_url: z.string().nullable().optional(),
+    name: z.string().optional(),
+    branches: z
+      .array(
+        z.object({
+          name: z.string(),
+          commit: z.object({ sha: z.string().optional() }).optional(),
+        })
+      )
+      .optional(),
+    commit: z
+      .object({
+        sha: z.string().optional(),
+        html_url: z.string().optional(),
+      })
+      .optional(),
+    repository: repositorySchema,
+    sender: senderSchema,
+    installation: installationSchema,
+    pull_requests: z
+      .array(
+        z.object({
+          number: z.number(),
+          url: z.string().optional(),
+          html_url: z.string().optional(),
+        })
+      )
+      .optional(),
+  });
+  const parsed = schema.safeParse(args.payload);
+  if (!parsed.success) return null;
+  const payload = parsed.data;
+  const repository = toRepositoryRef(payload.repository);
+  const sender = toUser(payload.sender);
+  const installationId = payload.installation?.id;
+  const pullRequests = toCiPullRequests(payload.pull_requests);
+  const first = pullRequests[0];
+  const status: GitHubStatusEvent = {
+    state: payload.state,
+    context: payload.context ?? "",
+    ...(payload.description === undefined
+      ? {}
+      : { description: payload.description }),
+    ...(payload.target_url === undefined
+      ? {}
+      : { targetUrl: payload.target_url }),
+    sha: payload.sha,
+    ...(payload.name === undefined ? {} : { name: payload.name }),
+    branches: (payload.branches ?? []).map((branch) => ({
+      name: branch.name,
+      ...(branch.commit === undefined ? {} : { commit: branch.commit }),
+    })),
+    ...(payload.commit === undefined
+      ? {}
+      : {
+          commit: {
+            ...(payload.commit.sha === undefined
+              ? {}
+              : { sha: payload.commit.sha }),
+            ...(payload.commit.html_url === undefined
+              ? {}
+              : { htmlUrl: payload.commit.html_url }),
+          },
+        }),
+    raw: args.payload,
+  };
+  const ctx: GitHubParsedContext = {
+    ...(args.deliveryId === undefined ? {} : { deliveryId: args.deliveryId }),
+    eventName: "status",
+    repository,
+    conversation: {
+      kind: "pull_request",
+      number: first?.number ?? 0,
+      url: first?.url ?? repository.url,
+    },
+    ...(sender === undefined ? {} : { sender, senderLogin: sender.login }),
+    ...(installationId === undefined ? {} : { installationId }),
+  };
+  return { ctx, status };
+}
+
+function parseGenericEvent(args: {
+  eventName: string;
+  payload: unknown;
+  deliveryId?: string;
+}): { ctx: GitHubParsedContext; event: GitHubRawEvent } | null {
+  const schema = z.object({
+    action: z.string().optional(),
+    repository: repositorySchema.optional(),
+    sender: senderSchema,
+    installation: installationSchema,
+    issue: z
+      .object({
+        number: z.number().int().positive(),
+        html_url: z.string().url().optional(),
+        pull_request: z.unknown().optional(),
+      })
+      .optional(),
+    pull_request: z
+      .object({
+        number: z.number().int().positive(),
+        html_url: z.string().url().optional(),
+      })
+      .optional(),
+  });
+  const parsed = schema.safeParse(args.payload);
+  if (!parsed.success) {
+    return null;
+  }
+  const payload = parsed.data;
+  if (payload.repository === undefined) {
+    return null;
+  }
+  const repository = toRepositoryRef(payload.repository);
+  const sender = toUser(payload.sender);
+  const installationId = payload.installation?.id;
+  const kind: GitHubConversationKind =
+    payload.issue?.pull_request !== undefined
+      ? "pull_request"
+      : payload.issue !== undefined
+        ? "issue"
+        : "pull_request";
+  const number = payload.issue?.number ?? payload.pull_request?.number ?? 0;
+  const url =
+    payload.issue?.html_url ?? payload.pull_request?.html_url ?? repository.url;
+  const event: GitHubRawEvent = {
+    eventName: args.eventName,
+    ...(args.deliveryId === undefined ? {} : { deliveryId: args.deliveryId }),
+    ...(payload.action === undefined ? {} : { action: payload.action }),
+    payload: args.payload,
+  };
+  const ctx: GitHubParsedContext = {
+    ...(args.deliveryId === undefined ? {} : { deliveryId: args.deliveryId }),
+    eventName: args.eventName,
+    repository,
+    conversation: { kind, number, url },
+    ...(sender === undefined ? {} : { sender, senderLogin: sender.login }),
+    ...(installationId === undefined ? {} : { installationId }),
+  };
+  return { ctx, event };
+}
+
+function unanchoredEventContext(args: {
+  deliveryId?: string;
+  eventName: string;
+  repository: GitHubRepositoryRef;
+  sender?: GitHubUser;
+  installationId?: number;
+}): GitHubParsedContext {
+  return {
+    ...(args.deliveryId === undefined ? {} : { deliveryId: args.deliveryId }),
+    eventName: args.eventName,
+    repository: args.repository,
+    conversation: {
+      kind: "pull_request",
+      number: 0,
+      url: args.repository.url,
+    },
+    ...(args.sender === undefined
+      ? {}
+      : { sender: args.sender, senderLogin: args.sender.login }),
+    ...(args.installationId === undefined
+      ? {}
+      : { installationId: args.installationId }),
+  };
+}
+
+function toRepositoryRef(repo: {
+  id?: number;
+  full_name: string;
+  html_url: string;
+  name?: string;
+  owner?: { login?: string };
+}): GitHubRepositoryRef {
+  const [ownerFromName, nameFromFull] = repo.full_name.split("/");
+  return {
+    fullName: repo.full_name,
+    url: repo.html_url,
+    owner: repo.owner?.login ?? ownerFromName ?? "",
+    name: repo.name ?? nameFromFull ?? repo.full_name,
+    ...(repo.id === undefined ? {} : { id: repo.id }),
+  };
+}
+
+function toUser(
+  raw:
+    | {
+        login?: string;
+        id?: number;
+        type?: string;
+      }
+    | null
+    | undefined
+): GitHubUser | undefined {
+  if (raw?.login === undefined || raw.login === "") return undefined;
+  return {
+    login: raw.login,
+    ...(raw.id === undefined ? {} : { id: raw.id }),
+    ...(raw.type === undefined ? {} : { type: raw.type }),
+  };
+}
+
+function toCiPullRequests(
+  raw: Array<{ number: number; url?: string; html_url?: string }> | undefined
+): GitHubCiPullRequestRef[] {
+  return (raw ?? []).map((pr) => ({
+    number: pr.number,
+    ...(pr.html_url !== undefined
+      ? { url: pr.html_url }
+      : pr.url !== undefined
+        ? { url: pr.url }
+        : {}),
+  }));
+}
+
+function toCiApp(
+  raw: { slug?: string; name?: string } | null | undefined
+): GitHubCiAppRef {
+  return {
+    ...(raw?.slug === undefined ? {} : { slug: raw.slug }),
+    ...(raw?.name === undefined ? {} : { name: raw.name }),
+  };
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Attach the GitHub API + thread handles to a parsed context, producing the
+ * full {@link GitHubEventContext} handed to inbound hooks.
+ */
+function enrichEventContext(input: {
+  bindingConfig: GitHubBindingConfig;
+  ctx: Omit<GitHubEventContext, "github" | "thread" | "host"> &
+    Partial<Pick<GitHubEventContext, "github" | "thread">>;
+  bindingState: GitHubBindingState;
+  installationId?: number;
+  host: HostContext;
+}): GitHubEventContext {
+  const { github, thread } = buildGitHubBinding({
+    config: input.bindingConfig,
+    state: input.bindingState,
+  });
+  return {
+    ...input.ctx,
+    ...(input.installationId === undefined
+      ? {}
+      : { installationId: input.installationId }),
+    github,
+    thread,
+    host: input.host,
+  };
+}
+
+/**
+ * Enrich an unanchored CI context (`conversation.number === 0`). The binding
+ * still resolves `github`, but `thread.post` throws until a PR is attached.
+ */
+function enrichCiContext(input: {
+  bindingConfig: GitHubBindingConfig;
+  ctx: GitHubParsedContext;
+  installationId?: number;
+  host: HostContext;
+}): GitHubEventContext {
+  const binding = githubBindingStateForEvent({
+    kind: input.ctx.conversation.kind,
+    owner: input.ctx.repository.owner,
+    repo: input.ctx.repository.name,
+    number: input.ctx.conversation.number,
+    repositoryId: input.ctx.repository.id,
+    installationId: input.installationId,
+  });
+  return enrichEventContext({
+    bindingConfig: input.bindingConfig,
+    ctx: input.ctx,
+    bindingState: binding,
+    installationId: input.installationId,
+    host: input.host,
+  });
+}
+
+/** Build the durable per-session channel state stored with the turn. */
+function sessionStateFromBinding(input: {
+  binding: GitHubBindingState;
+  deliveryId?: string;
+  eventName: string;
+  headSha?: string;
+  baseRef?: string;
+  headRef?: string;
+}): GitHubChannelState {
+  return emptyGitHubChannelState({
+    ...input.binding,
+    deliveryId: input.deliveryId ?? null,
+    eventName: input.eventName,
+    headSha: input.headSha ?? null,
+    baseRef: input.baseRef ?? null,
+    headRef: input.headRef ?? null,
+  });
+}
+
+/** Read `installation.id` from a raw webhook payload when present. */
+function readInstallationId(payload: unknown): number | undefined {
+  if (typeof payload !== "object" || payload === null) return undefined;
+  const installation = (payload as { installation?: { id?: number } })
+    .installation;
+  return typeof installation?.id === "number" ? installation.id : undefined;
+}
+
+function envWebhookSecret(): GitHubCredentialValue | undefined {
+  if (
+    process.env.GITHUB_WEBHOOK_SECRET === undefined ||
+    process.env.GITHUB_WEBHOOK_SECRET === ""
+  ) {
+    return undefined;
+  }
+  return () => process.env.GITHUB_WEBHOOK_SECRET;
+}
+
+async function resolveCloudOptions(
+  cloud: GitHubChannelOptions["cloud"],
+  ctx: GitHubEventContext,
+  pullRequest: GitHubPullRequestEvent
+): Promise<AgentCloudOptions | undefined> {
+  if (cloud === undefined || cloud === false) {
+    return undefined;
+  }
+  if (cloud === true) {
+    return {
+      repos: [
+        {
+          url: ctx.repository.url,
+          prUrl: pullRequest.url,
+          startingRef: pullRequest.headSha,
+        },
+      ],
+    };
+  }
+  if (typeof cloud === "function") {
+    return await cloud(ctx, pullRequest);
+  }
+  return cloud;
+}