@cursor/july 0.1.20 → 0.1.21

package/src/channels/github/github.test.ts

@@ -0,0 +1,937 @@
+import { createHmac } from "node:crypto";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { scmMetadataToGitHubPayload } from "../../internal/cursor-event-relay.js";
+import type {
+  ChannelHandlerArgs,
+  ChannelRouteHandler,
+  ChannelSession,
+  SendMessageFn,
+} from "../../types.js";
+import { formatGitHubOutboundComment } from "./binding.js";
+import {
+  clearGitHubAuthCaches,
+  defaultGitHubAuth,
+  defaultGitHubPullRequestMessage,
+  defaultOnComment,
+  type GitHubEventContext,
+  type GitHubRawEvent,
+  githubChannel,
+  githubPullRequestContinuationKey,
+  isGitHubAppBotAuthor,
+  parseGitHubPullRequestEvent,
+  shouldDispatchGitHubComment,
+  verifyGitHubWebhookSignature,
+} from "./index.js";
+
+describe("parseGitHubPullRequestEvent", () => {
+  it("normalizes a GitHub pull_request payload", () => {
+    const parsed = parseGitHubPullRequestEvent({
+      deliveryId: "delivery-1",
+      payload: pullRequestPayload(),
+    });
+
+    expect(parsed).toEqual({
+      ctx: {
+        deliveryId: "delivery-1",
+        eventName: "pull_request",
+        repository: {
+          fullName: "acme/widgets",
+          url: "https://github.com/acme/widgets",
+          owner: "acme",
+          name: "widgets",
+        },
+        conversation: {
+          kind: "pull_request",
+          number: 42,
+          url: "https://github.com/acme/widgets/pull/42",
+        },
+        senderLogin: "sender",
+        sender: { login: "sender" },
+      },
+      pullRequest: {
+        action: "opened",
+        number: 42,
+        url: "https://github.com/acme/widgets/pull/42",
+        title: "Add widgets",
+        body: "PR body",
+        headRef: "feature/widgets",
+        headSha: "abc123",
+        baseRef: "main",
+        draft: false,
+        merged: false,
+        authorLogin: "octocat",
+      },
+    });
+  });
+
+  it("rejects malformed payloads", () => {
+    expect(
+      parseGitHubPullRequestEvent({
+        payload: { action: "opened" },
+      })
+    ).toBeNull();
+  });
+});
+
+describe("GitHub pull request prompt helpers", () => {
+  it("builds stable continuation keys and context-rich messages", () => {
+    const parsed = parseGitHubPullRequestEvent({
+      payload: pullRequestPayload(),
+    });
+    expect(parsed).not.toBeNull();
+    if (parsed === null) {
+      return;
+    }
+
+    expect(githubPullRequestContinuationKey(parsed.ctx)).toBe(
+      "github-pr:acme/widgets#42"
+    );
+    const message = defaultGitHubPullRequestMessage(
+      parsed.ctx,
+      parsed.pullRequest
+    );
+    expect(message).toContain("GitHub pull request trigger: acme/widgets#42");
+    expect(message).toContain("Head: feature/widgets (abc123)");
+  });
+
+  it("derives the turn auth from the delivery actor", () => {
+    const parsed = parseGitHubPullRequestEvent({
+      payload: pullRequestPayload(),
+    });
+    expect(parsed).not.toBeNull();
+    if (parsed === null) {
+      return;
+    }
+
+    expect(defaultGitHubAuth(parsed.ctx)).toEqual({
+      authenticator: "github-webhook",
+      principalId: "sender",
+      principalType: "user",
+      attributes: expect.objectContaining({ repository: "acme/widgets" }),
+    });
+  });
+});
+
+describe("defaultOnComment / mention gate", () => {
+  it("dispatches only when the bot is @mentioned", () => {
+    expect(
+      shouldDispatchGitHubComment({
+        body: "hey @my-agent please look",
+        botName: "my-agent",
+      })
+    ).toBe(true);
+    expect(
+      shouldDispatchGitHubComment({
+        body: "no mention here",
+        botName: "my-agent",
+      })
+    ).toBe(false);
+    expect(
+      shouldDispatchGitHubComment({
+        body: "@my-agent hi",
+        botName: undefined,
+      })
+    ).toBe(false);
+  });
+
+  it("ignores comments from the GitHub App bot actor", () => {
+    expect(
+      shouldDispatchGitHubComment({
+        body: "hey @my-agent please look",
+        author: { login: "my-agent[bot]", type: "Bot" },
+        botName: "my-agent",
+      })
+    ).toBe(false);
+    expect(
+      isGitHubAppBotAuthor({ login: "my-agent[bot]", type: "Bot" }, "my-agent")
+    ).toBe(true);
+  });
+
+  it("returns auth when mentioned", () => {
+    const ctx = {
+      eventName: "issue_comment",
+      repository: {
+        fullName: "acme/widgets",
+        url: "https://github.com/acme/widgets",
+        owner: "acme",
+        name: "widgets",
+      },
+      conversation: {
+        kind: "pull_request" as const,
+        number: 42,
+        url: "https://github.com/acme/widgets/pull/42",
+      },
+      senderLogin: "sender",
+    };
+    expect(
+      defaultOnComment(
+        ctx,
+        {
+          id: 1,
+          body: "@my-agent triage this",
+          url: "https://github.com/acme/widgets/issues/42#issuecomment-1",
+          htmlUrl: "https://github.com/acme/widgets/issues/42#issuecomment-1",
+        },
+        { botName: "my-agent" }
+      )
+    ).toEqual({ auth: defaultGitHubAuth(ctx) });
+  });
+});
+
+describe("verifyGitHubWebhookSignature", () => {
+  it("accepts a valid sha256 signature", async () => {
+    const body = JSON.stringify(pullRequestPayload());
+    const signature = `sha256=${createHmac("sha256", "secret")
+      .update(body)
+      .digest("hex")}`;
+
+    await expect(
+      verifyGitHubWebhookSignature({
+        body,
+        signatureHeader: signature,
+        secret: "secret",
+      })
+    ).resolves.toBe("verified");
+  });
+
+  it("rejects mismatched signatures", async () => {
+    await expect(
+      verifyGitHubWebhookSignature({
+        body: "{}",
+        signatureHeader: "sha256=bad",
+        secret: "secret",
+      })
+    ).resolves.toBe("mismatch");
+  });
+});
+
+describe("githubChannel", () => {
+  let priorWebhookSecret: string | undefined;
+
+  beforeEach(() => {
+    priorWebhookSecret = process.env.GITHUB_WEBHOOK_SECRET;
+    delete process.env.GITHUB_WEBHOOK_SECRET;
+  });
+
+  afterEach(() => {
+    if (priorWebhookSecret === undefined) {
+      delete process.env.GITHUB_WEBHOOK_SECRET;
+    } else {
+      process.env.GITHUB_WEBHOOK_SECRET = priorWebhookSecret;
+    }
+  });
+
+  it("dispatches default review triggers as the delivery actor", async () => {
+    const body = JSON.stringify(pullRequestPayload());
+    const send = vi.fn<SendMessageFn>(async () => fakeSession());
+    const response = await routeHandler(
+      githubChannel({
+        auth: [],
+        cloud: true,
+      })
+    )(
+      new Request("http://127.0.0.1:3000/v1/channels/github", {
+        method: "POST",
+        headers: {
+          "x-github-event": "pull_request",
+          "x-github-delivery": "delivery-1",
+          "content-type": "application/json",
+        },
+        body,
+      }),
+      handlerArgs(send)
+    );
+
+    await expect(response.json()).resolves.toEqual({
+      ok: true,
+      sessionId: "session-1",
+      isNew: true,
+      continuationToken: "github-pr:acme/widgets#42",
+    });
+    expect(send).toHaveBeenCalledExactlyOnceWith(
+      expect.stringContaining("GitHub pull request trigger: acme/widgets#42"),
+      expect.objectContaining({
+        auth: expect.objectContaining({
+          authenticator: "github-webhook",
+          principalId: "sender",
+          principalType: "user",
+        }),
+        continuationToken: "github-pr:acme/widgets#42",
+        title: "GitHub acme/widgets#42",
+        cloud: {
+          repos: [
+            {
+              url: "https://github.com/acme/widgets",
+              prUrl: "https://github.com/acme/widgets/pull/42",
+              startingRef: "abc123",
+            },
+          ],
+        },
+      })
+    );
+  });
+
+  it("ignores actions outside the default gate without starting a session", async () => {
+    const send = vi.fn<SendMessageFn>(async () => fakeSession());
+    const response = await routeHandler(githubChannel({ auth: [] }))(
+      new Request("http://127.0.0.1:3000/v1/channels/github", {
+        method: "POST",
+        headers: { "x-github-event": "pull_request" },
+        body: JSON.stringify(pullRequestPayload({ action: "closed" })),
+      }),
+      handlerArgs(send)
+    );
+
+    await expect(response.json()).resolves.toEqual({
+      ok: true,
+      skipped: true,
+      reason: "not_dispatched",
+      action: "closed",
+    });
+    expect(send).not.toHaveBeenCalled();
+  });
+
+  it("replaces the default gate with the onPullRequest hook", async () => {
+    const send = vi.fn<SendMessageFn>(async () => fakeSession());
+    const handler = routeHandler(
+      githubChannel({
+        auth: [],
+        onPullRequest: (ctx, pr) =>
+          pr.action === "synchronize"
+            ? { auth: defaultGitHubAuth(ctx), context: ["Focus on the diff."] }
+            : null,
+      })
+    );
+
+    const ignored = await handler(
+      new Request("http://127.0.0.1:3000/v1/channels/github", {
+        method: "POST",
+        headers: { "x-github-event": "pull_request" },
+        body: JSON.stringify(pullRequestPayload({ action: "opened" })),
+      }),
+      handlerArgs(send)
+    );
+    await expect(ignored.json()).resolves.toEqual({
+      ok: true,
+      skipped: true,
+      reason: "not_dispatched",
+      action: "opened",
+    });
+    expect(send).not.toHaveBeenCalled();
+
+    const dispatched = await handler(
+      new Request("http://127.0.0.1:3000/v1/channels/github", {
+        method: "POST",
+        headers: { "x-github-event": "pull_request" },
+        body: JSON.stringify(pullRequestPayload({ action: "synchronize" })),
+      }),
+      handlerArgs(send)
+    );
+    await expect(dispatched.json()).resolves.toMatchObject({ ok: true });
+    expect(send).toHaveBeenCalledExactlyOnceWith(
+      expect.stringContaining("Focus on the diff."),
+      expect.anything()
+    );
+  });
+
+  it("dispatches @mention issue comments via the default onComment gate", async () => {
+    const send = vi.fn<SendMessageFn>(async () => fakeSession());
+    const response = await routeHandler(
+      githubChannel({
+        auth: [],
+        botName: "my-agent",
+      })
+    )(
+      new Request("http://127.0.0.1:3000/v1/channels/github", {
+        method: "POST",
+        headers: {
+          "x-github-event": "issue_comment",
+          "x-github-delivery": "delivery-comment",
+        },
+        body: JSON.stringify(issueCommentPayload("@my-agent please triage")),
+      }),
+      handlerArgs(send)
+    );
+
+    await expect(response.json()).resolves.toMatchObject({ ok: true });
+    expect(send).toHaveBeenCalledExactlyOnceWith(
+      "please triage",
+      expect.objectContaining({
+        continuationToken: "github-pr:acme/widgets#42",
+        auth: expect.objectContaining({ principalId: "sender" }),
+      })
+    );
+  });
+
+  it("dispatches relay-stubbed issue_comment payloads (scm-events metadata)", async () => {
+    // Regression guard for the /v0/scm-events comment gap: a metadata-only
+    // envelope with a comment snapshot must clear the issue_comment Zod
+    // schema and dispatch, without a payload round-trip to GitHub.
+    const send = vi.fn<SendMessageFn>(async () => fakeSession());
+    const response = await routeHandler(
+      githubChannel({ auth: [], botName: "my-agent" })
+    )(
+      new Request("http://127.0.0.1:3000/v1/channels/github", {
+        method: "POST",
+        headers: {
+          "x-github-event": "issue_comment",
+          "x-github-delivery": "delivery-relay-comment",
+        },
+        body: JSON.stringify(
+          scmMetadataToGitHubPayload({
+            repo: "acme/widgets",
+            action: "created",
+            prNumber: 42,
+            prUrl: "https://github.com/acme/widgets/pull/42",
+            comment: {
+              id: 7,
+              body: "@my-agent please triage",
+              htmlUrl: "https://github.com/acme/widgets/pull/42#issuecomment-7",
+              authorLogin: "sender",
+            },
+          })
+        ),
+      }),
+      handlerArgs(send)
+    );
+
+    await expect(response.json()).resolves.toMatchObject({ ok: true });
+    expect(send).toHaveBeenCalledExactlyOnceWith(
+      "please triage",
+      expect.objectContaining({
+        continuationToken: "github-pr:acme/widgets#42",
+        auth: expect.objectContaining({ principalId: "sender" }),
+      })
+    );
+  });
+
+  it("skips relay-stubbed comments from the agent's own bot (self/bot-loop gate)", async () => {
+    // Regression guard: the relay stub must carry user.type through so
+    // isGitHubAppBotAuthor keeps failing CLOSED for the agent's own
+    // comments on the scm-events path. Without it, a bot comment that
+    // @mentions the agent would wake it again (self-wake loop).
+    const send = vi.fn<SendMessageFn>(async () => fakeSession());
+    const response = await routeHandler(
+      githubChannel({ auth: [], botName: "my-agent" })
+    )(
+      new Request("http://127.0.0.1:3000/v1/channels/github", {
+        method: "POST",
+        headers: {
+          "x-github-event": "issue_comment",
+          "x-github-delivery": "delivery-relay-bot-comment",
+        },
+        body: JSON.stringify(
+          scmMetadataToGitHubPayload({
+            repo: "acme/widgets",
+            action: "created",
+            prNumber: 42,
+            prUrl: "https://github.com/acme/widgets/pull/42",
+            comment: {
+              id: 8,
+              body: "@my-agent looks done to me",
+              htmlUrl: "https://github.com/acme/widgets/pull/42#issuecomment-8",
+              authorLogin: "my-agent[bot]",
+              authorType: "Bot",
+            },
+          })
+        ),
+      }),
+      handlerArgs(send)
+    );
+
+    await expect(response.json()).resolves.toEqual({
+      ok: true,
+      skipped: true,
+      reason: "ignored_comment",
+    });
+    expect(send).not.toHaveBeenCalled();
+  });
+
+  it("skips issue comments without an @mention", async () => {
+    const send = vi.fn<SendMessageFn>(async () => fakeSession());
+    const response = await routeHandler(
+      githubChannel({ auth: [], botName: "my-agent" })
+    )(
+      new Request("http://127.0.0.1:3000/v1/channels/github", {
+        method: "POST",
+        headers: { "x-github-event": "issue_comment" },
+        body: JSON.stringify(issueCommentPayload("no bot here")),
+      }),
+      handlerArgs(send)
+    );
+    await expect(response.json()).resolves.toEqual({
+      ok: true,
+      skipped: true,
+      reason: "not_dispatched",
+    });
+    expect(send).not.toHaveBeenCalled();
+  });
+
+  it("dispatches failed check_suite via onCheckSuite when a PR is attached", async () => {
+    const send = vi.fn<SendMessageFn>(async () => fakeSession());
+    const response = await routeHandler(
+      githubChannel({
+        auth: [],
+        onCheckSuite: (ctx, suite) =>
+          suite.action === "completed" &&
+          suite.conclusion === "failure" &&
+          suite.app.slug === "github-actions" &&
+          suite.pullRequests.length > 0
+            ? {
+                auth: defaultGitHubAuth(ctx),
+                context: [
+                  `Triage failed check suite ${suite.checkSuiteId} at ${suite.headSha}.`,
+                ],
+              }
+            : null,
+      })
+    )(
+      new Request("http://127.0.0.1:3000/v1/channels/github", {
+        method: "POST",
+        headers: { "x-github-event": "check_suite" },
+        body: JSON.stringify(checkSuitePayload()),
+      }),
+      handlerArgs(send)
+    );
+
+    await expect(response.json()).resolves.toMatchObject({ ok: true });
+    expect(send).toHaveBeenCalledExactlyOnceWith(
+      expect.stringContaining("Triage failed check suite 99 at deadbeef"),
+      expect.objectContaining({
+        continuationToken: "github-pr:acme/widgets#42",
+      })
+    );
+  });
+
+  it("requires a valid signature when a webhook secret is configured", async () => {
+    const send = vi.fn<SendMessageFn>(async () => fakeSession());
+    const response = await routeHandler(
+      githubChannel({
+        credentials: { webhookSecret: "secret" },
+      })
+    )(
+      new Request("http://127.0.0.1:3000/v1/channels/github", {
+        method: "POST",
+        headers: { "x-github-event": "pull_request" },
+        body: JSON.stringify(pullRequestPayload()),
+      }),
+      handlerArgs(send)
+    );
+
+    expect(response.status).toBe(401);
+    await expect(response.json()).resolves.toEqual({
+      ok: false,
+      error: "missing_signature",
+    });
+    expect(send).not.toHaveBeenCalled();
+  });
+
+  it("returns 202 and schedules waitUntil for task dispatch", async () => {
+    const send = vi.fn<SendMessageFn>(async () => fakeSession());
+    const waitUntil = vi.fn();
+    const task = vi.fn(async () => {});
+    const response = await routeHandler(
+      githubChannel({
+        auth: [],
+        onPullRequest: async () => ({ task }),
+      })
+    )(
+      new Request("http://127.0.0.1:3000/v1/channels/github", {
+        method: "POST",
+        headers: { "x-github-event": "pull_request" },
+        body: JSON.stringify(pullRequestPayload()),
+      }),
+      { ...handlerArgs(send), waitUntil }
+    );
+
+    expect(response.status).toBe(202);
+    await expect(response.json()).resolves.toEqual({
+      ok: true,
+      dispatched: true,
+      mode: "task",
+      action: "opened",
+      prUrl: "https://github.com/acme/widgets/pull/42",
+      headSha: "abc123",
+    });
+    expect(waitUntil).toHaveBeenCalledTimes(1);
+    expect(task).not.toHaveBeenCalled();
+    expect(send).not.toHaveBeenCalled();
+
+    const scheduled = waitUntil.mock.calls[0]?.[0] as Promise<unknown>;
+    await scheduled;
+    expect(task).toHaveBeenCalledTimes(1);
+  });
+
+  it("exposes ctx.github and ctx.thread to inbound hooks", async () => {
+    const send = vi.fn<SendMessageFn>(async () => fakeSession());
+    let captured: GitHubEventContext | undefined;
+    await routeHandler(
+      githubChannel({
+        auth: [],
+        onPullRequest: (ctx, pr) => {
+          captured = ctx;
+          return pr.action === "opened"
+            ? { auth: defaultGitHubAuth(ctx) }
+            : null;
+        },
+      })
+    )(
+      new Request("http://127.0.0.1:3000/v1/channels/github", {
+        method: "POST",
+        headers: { "x-github-event": "pull_request" },
+        body: JSON.stringify(pullRequestPayload()),
+      }),
+      handlerArgs(send)
+    );
+
+    expect(captured).toBeDefined();
+    expect(typeof captured?.github.request).toBe("function");
+    expect(typeof captured?.github.createStatus).toBe("function");
+    expect(typeof captured?.github.getOctokit).toBe("function");
+    expect(typeof captured?.thread.post).toBe("function");
+    expect(captured?.thread.kind).toBe("pull_request");
+    expect(captured?.github.repository.fullName).toBe("acme/widgets");
+  });
+
+  it("runs onStatus task dispatch with ctx.github.createStatus", async () => {
+    clearGitHubAuthCaches();
+    const fetchMock = vi.fn(
+      async () => new Response(JSON.stringify({}), { status: 201 })
+    );
+    const send = vi.fn<SendMessageFn>(async () => fakeSession());
+    const waitUntil = vi.fn();
+    const response = await routeHandler(
+      githubChannel({
+        auth: [],
+        credentials: { token: "test-token" },
+        api: { fetch: fetchMock as unknown as typeof fetch },
+        onStatus: (ctx, status) =>
+          status.state === "failure"
+            ? {
+                task: async () => {
+                  await ctx.github.createStatus({
+                    sha: status.sha,
+                    state: "pending",
+                    context: "agent/triage",
+                  });
+                },
+              }
+            : null,
+      })
+    )(
+      new Request("http://127.0.0.1:3000/v1/channels/github", {
+        method: "POST",
+        headers: { "x-github-event": "status" },
+        body: JSON.stringify(statusPayload()),
+      }),
+      { ...handlerArgs(send), waitUntil }
+    );
+
+    expect(response.status).toBe(202);
+    await expect(response.json()).resolves.toMatchObject({
+      ok: true,
+      dispatched: true,
+      mode: "task",
+      event: "status",
+      state: "failure",
+      sha: "deadbeef",
+    });
+    expect(send).not.toHaveBeenCalled();
+
+    const scheduled = waitUntil.mock.calls[0]?.[0] as Promise<unknown>;
+    await scheduled;
+    expect(fetchMock).toHaveBeenCalledOnce();
+    const call = fetchMock.mock.calls[0];
+    expect(call).toBeDefined();
+    const [url, init] = call as unknown as [unknown, RequestInit | undefined];
+    expect(String(url)).toContain("/repos/acme/widgets/statuses/deadbeef");
+    expect(init?.method).toBe("POST");
+  });
+
+  it("dispatches unknown events through onEvent", async () => {
+    const send = vi.fn<SendMessageFn>(async () => fakeSession());
+    let capturedEvent: GitHubRawEvent | undefined;
+    const response = await routeHandler(
+      githubChannel({
+        auth: [],
+        onEvent: (ctx, event) => {
+          capturedEvent = event;
+          return event.eventName === "label"
+            ? { auth: defaultGitHubAuth(ctx) }
+            : null;
+        },
+      })
+    )(
+      new Request("http://127.0.0.1:3000/v1/channels/github", {
+        method: "POST",
+        headers: {
+          "x-github-event": "label",
+          "x-github-delivery": "delivery-label",
+        },
+        body: JSON.stringify(labelPayload()),
+      }),
+      handlerArgs(send)
+    );
+
+    await expect(response.json()).resolves.toMatchObject({ ok: true });
+    expect(capturedEvent?.eventName).toBe("label");
+    expect(capturedEvent?.action).toBe("created");
+    expect(send).toHaveBeenCalledExactlyOnceWith(
+      expect.stringContaining("GitHub label event"),
+      expect.objectContaining({
+        continuationToken: "github-issue:acme/widgets#42",
+      })
+    );
+  });
+
+  it("schedules task dispatch for unanchored check_suite events", async () => {
+    const send = vi.fn<SendMessageFn>(async () => fakeSession());
+    const waitUntil = vi.fn();
+    const task = vi.fn(async () => {});
+    const response = await routeHandler(
+      githubChannel({
+        auth: [],
+        onCheckSuite: async () => ({ task }),
+      })
+    )(
+      new Request("http://127.0.0.1:3000/v1/channels/github", {
+        method: "POST",
+        headers: { "x-github-event": "check_suite" },
+        body: JSON.stringify({
+          ...checkSuitePayload(),
+          check_suite: {
+            ...(checkSuitePayload().check_suite as Record<string, unknown>),
+            pull_requests: [],
+          },
+        }),
+      }),
+      { ...handlerArgs(send), waitUntil }
+    );
+
+    expect(response.status).toBe(202);
+    await expect(response.json()).resolves.toMatchObject({
+      ok: true,
+      dispatched: true,
+      mode: "task",
+      event: "check_suite",
+    });
+    expect(send).not.toHaveBeenCalled();
+    const scheduled = waitUntil.mock.calls[0]?.[0] as Promise<unknown>;
+    await scheduled;
+    expect(task).toHaveBeenCalledTimes(1);
+  });
+
+  it("ignores outbound comments stamped with the agent marker", async () => {
+    const send = vi.fn<SendMessageFn>(async () => fakeSession());
+    const response = await routeHandler(
+      githubChannel({
+        auth: [],
+        botName: "my-agent",
+      })
+    )(
+      new Request("http://127.0.0.1:3000/v1/channels/github", {
+        method: "POST",
+        headers: { "x-github-event": "issue_comment" },
+        body: JSON.stringify(
+          issueCommentPayload(
+            formatGitHubOutboundComment("Thanks @my-agent for the help!")
+          )
+        ),
+      }),
+      handlerArgs(send)
+    );
+
+    await expect(response.json()).resolves.toEqual({
+      ok: true,
+      skipped: true,
+      reason: "ignored_comment",
+    });
+    expect(send).not.toHaveBeenCalled();
+  });
+});
+
+function routeHandler(
+  channel: ReturnType<typeof githubChannel>
+): ChannelRouteHandler {
+  const route = channel.routes?.[0];
+  if (route === undefined) {
+    throw new Error("expected github channel route");
+  }
+  return route.handler;
+}
+
+function handlerArgs(send: SendMessageFn): ChannelHandlerArgs {
+  return {
+    params: {},
+    requestIp: "127.0.0.1",
+    auth: null,
+    host: {
+      mcp: {
+        names: () => [],
+        listTools: async () => [],
+        callTool: async () => ({ content: [] }),
+      },
+      github: {
+        getOctokit: async () => {
+          throw new Error("github client not configured in test");
+        },
+      },
+      slack: {
+        getClient: async () => {
+          throw new Error("slack client not configured in test");
+        },
+      },
+      kv: {
+        get: async () => undefined,
+        put: async () => {},
+        delete: async () => {},
+      },
+    },
+    send,
+    getSession: async () => null,
+    receive: async () => fakeSession(),
+    callTool: async (toolName) => ({
+      toolName,
+      callId: "call-1",
+      isError: false,
+      result: null,
+      durationMs: 0,
+    }),
+    waitUntil: () => {},
+    sessionUrls: (_request, sessionId) => ({
+      playgroundUrl: `http://127.0.0.1:3000/playground?sessionId=${sessionId}`,
+      traceUrl: `http://127.0.0.1:3000/v1/session/${sessionId}/events`,
+    }),
+  };
+}
+
+function fakeSession(): ChannelSession {
+  return {
+    id: "session-1",
+    isNew: true,
+    continuationToken: "github-pr:acme/widgets#42",
+    info: {
+      id: "session-1",
+      channelId: "github",
+      mode: "chat",
+      auth: null,
+      sdkAgentId: undefined,
+      title: "GitHub acme/widgets#42",
+    },
+    getEventStream: async () => new ReadableStream<Uint8Array>(),
+    waitForCompletion: async () => ({ status: "finished", result: "done" }),
+    setContinuationToken: async () => {},
+  };
+}
+
+function pullRequestPayload(
+  overrides: { action?: string } = {}
+): Record<string, unknown> {
+  return {
+    action: overrides.action ?? "opened",
+    repository: {
+      full_name: "acme/widgets",
+      html_url: "https://github.com/acme/widgets",
+    },
+    pull_request: {
+      number: 42,
+      html_url: "https://github.com/acme/widgets/pull/42",
+      title: "Add widgets",
+      body: "PR body",
+      draft: false,
+      user: { login: "octocat" },
+      head: {
+        ref: "feature/widgets",
+        sha: "abc123",
+      },
+      base: {
+        ref: "main",
+      },
+    },
+    sender: { login: "sender" },
+  };
+}
+
+function issueCommentPayload(body: string): Record<string, unknown> {
+  return {
+    action: "created",
+    repository: {
+      full_name: "acme/widgets",
+      html_url: "https://github.com/acme/widgets",
+    },
+    issue: {
+      number: 42,
+      html_url: "https://github.com/acme/widgets/pull/42",
+      pull_request: {},
+    },
+    comment: {
+      id: 7,
+      body,
+      html_url: "https://github.com/acme/widgets/pull/42#issuecomment-7",
+      url: "https://api.github.com/repos/acme/widgets/issues/comments/7",
+      user: { login: "sender", type: "User" },
+    },
+    sender: { login: "sender", type: "User" },
+  };
+}
+
+function statusPayload(): Record<string, unknown> {
+  return {
+    state: "failure",
+    sha: "deadbeef",
+    context: "ci/build",
+    description: "Build failed",
+    target_url: "https://ci.example.com/build/1",
+    name: "acme/widgets",
+    branches: [{ name: "main", commit: { sha: "deadbeef" } }],
+    commit: {
+      sha: "deadbeef",
+      html_url: "https://github.com/acme/widgets/commit/deadbeef",
+    },
+    repository: {
+      full_name: "acme/widgets",
+      html_url: "https://github.com/acme/widgets",
+    },
+    sender: { login: "ci-bot", type: "Bot" },
+  };
+}
+
+function labelPayload(): Record<string, unknown> {
+  return {
+    action: "created",
+    label: { name: "bug", color: "ff0000" },
+    repository: {
+      full_name: "acme/widgets",
+      html_url: "https://github.com/acme/widgets",
+    },
+    issue: {
+      number: 42,
+      html_url: "https://github.com/acme/widgets/issues/42",
+    },
+    sender: { login: "sender", type: "User" },
+  };
+}
+
+function checkSuitePayload(): Record<string, unknown> {
+  return {
+    action: "completed",
+    repository: {
+      full_name: "acme/widgets",
+      html_url: "https://github.com/acme/widgets",
+    },
+    check_suite: {
+      id: 99,
+      head_sha: "deadbeef",
+      status: "completed",
+      conclusion: "failure",
+      app: { slug: "github-actions", name: "GitHub Actions" },
+      pull_requests: [
+        {
+          number: 42,
+          html_url: "https://github.com/acme/widgets/pull/42",
+        },
+      ],
+    },
+    sender: { login: "github-actions[bot]", type: "Bot" },
+  };
+}