@cursor/july 0.1.1

package/src/channels/github/index.ts

@@ -0,0 +1,52 @@
+/**
+ * GitHub webhook channel pack for agent-serve (Eve-compatible dispatch).
+ *
+ * ```ts
+ * import { defaultGitHubAuth, githubChannel } from "@anysphere/agent-serve/channels/github";
+ *
+ * export default githubChannel({
+ *   botName: "my-agent",
+ *   // API auth: App installation (preferred) → GITHUB_TOKEN / GH_TOKEN → `gh auth`
+ *   credentials: { webhookSecret: () => process.env.GITHUB_WEBHOOK_SECRET },
+ *   onComment: (ctx, comment) => ({ auth: defaultGitHubAuth(ctx) }),
+ *   onPullRequest: (ctx, pr) =>
+ *     pr.action === "opened" ? { auth: defaultGitHubAuth(ctx) } : null,
+ *   onCheckSuite: (ctx, suite) =>
+ *     suite.conclusion === "failure" && suite.pullRequests.length > 0
+ *       ? { auth: defaultGitHubAuth(ctx) }
+ *       : null,
+ *   // Legacy commit statuses
+ *   onStatus: (ctx, status) =>
+ *     status.state === "failure"
+ *       ? {
+ *           task: () =>
+ *             ctx.github.createStatus({
+ *               sha: status.sha,
+ *               state: "pending",
+ *               context: "agent/triage",
+ *             }),
+ *         }
+ *       : null,
+ *   // Catch-all for other webhook events
+ *   onEvent: (ctx, event) =>
+ *     event.eventName === "label" ? { auth: defaultGitHubAuth(ctx) } : null,
+ * });
+ * ```
+ *
+ * Inbound hooks receive `ctx.github` (`getOctokit`, `request`, `createStatus`)
+ * and `ctx.thread` (`post`, `react`). Prefer typed Octokit methods via
+ * `await ctx.github.getOctokit()` for new code. Without `onPullRequest`,
+ * agent-serve keeps a backward-compatible default gate (opened / reopened /
+ * synchronize / ready_for_review). Eve itself is opt-in for that hook.
+ */
+
+export * from "./api.js";
+export * from "./auth.js";
+export * from "./binding.js";
+export * from "./defaults.js";
+export * from "./events.js";
+export * from "./forward.js";
+export * from "./github-channel.js";
+export * from "./replay.js";
+export * from "./state.js";
+export * from "./types.js";

package/src/channels/github/replay.ts

@@ -0,0 +1,387 @@
+/**
+ * Synthesize GitHub webhook payloads from data you can *read* about a PR, so
+ * `agent-serve github replay` can exercise a `githubChannel()` without repo
+ * admin, without the `gh webhook forward` relay, and deterministically (great
+ * for hillclimbing).
+ *
+ * Payloads are shaped to satisfy the channel's parsers (see `github-channel.ts`);
+ * `undefined` fields are dropped by `JSON.stringify` before delivery.
+ */
+
+import { createHmac } from "node:crypto";
+
+/** A parsed PR reference. */
+export interface GitHubPrRef {
+  owner: string;
+  repo: string;
+  number: number;
+  /** `https://github.com/owner/repo/pull/N`. */
+  url: string;
+  /** `owner/repo#N`. */
+  label: string;
+}
+
+/** Parse a PR URL or `owner/repo#N`. Returns undefined when neither matches. */
+export function parseGitHubPrRef(raw: string): GitHubPrRef | undefined {
+  const text = raw.trim();
+  const url = text.match(
+    /https?:\/\/(?:www\.)?github\.com\/([\w.-]+)\/([\w.-]+)\/pull\/(\d+)/i
+  );
+  const hash = url ?? text.match(/^([\w.-]+)\/([\w.-]+)#(\d+)$/);
+  if (hash === null) {
+    return undefined;
+  }
+  const owner = hash[1] as string;
+  const repo = hash[2] as string;
+  const number = Number(hash[3]);
+  return {
+    owner,
+    repo,
+    number,
+    url: `https://github.com/${owner}/${repo}/pull/${number}`,
+    label: `${owner}/${repo}#${number}`,
+  };
+}
+
+// Minimal shapes read from `gh api` (extra fields are ignored/passed through).
+export interface ReplayRepo {
+  id?: number;
+  name?: string;
+  full_name: string;
+  html_url: string;
+  default_branch?: string;
+  owner?: { login?: string };
+}
+
+export interface ReplayUser {
+  login: string;
+  id?: number;
+  type?: string;
+}
+
+export interface ReplayPull {
+  number: number;
+  html_url: string;
+  title: string;
+  body?: string | null;
+  draft?: boolean;
+  merged?: boolean;
+  user?: ReplayUser | null;
+  head: { ref: string; sha: string; repo?: { id?: number; name?: string } };
+  base: { ref: string; sha?: string };
+}
+
+/** Optional real CI check to mirror (app slug / name / conclusion). */
+export interface ReplayCheck {
+  id?: number;
+  name?: string;
+  conclusion?: string | null;
+  app?: { slug?: string; name?: string } | null;
+}
+
+/** Webhook events replay knows how to synthesize. */
+export const SYNTHESIZABLE_EVENTS = [
+  "pull_request",
+  "issue_comment",
+  "pull_request_review_comment",
+  "check_run",
+  "check_suite",
+  "workflow_run",
+  "status",
+] as const;
+
+export type SynthesizableEvent = (typeof SYNTHESIZABLE_EVENTS)[number];
+
+export function isSynthesizableEvent(
+  event: string
+): event is SynthesizableEvent {
+  return (SYNTHESIZABLE_EVENTS as readonly string[]).includes(event);
+}
+
+export interface SynthesizeInput {
+  event: string;
+  repo: ReplayRepo;
+  pull: ReplayPull;
+  /** Actor on the delivery (defaults to the PR author for PR/comment events). */
+  sender?: ReplayUser;
+  /** Override the event action (e.g. `opened`, `synchronize`). */
+  action?: string;
+  /** CI conclusion for check_run/check_suite/workflow_run (default `failure`). */
+  conclusion?: string;
+  /** Commit-status state (default derived from conclusion, else `failure`). */
+  state?: string;
+  /** Commit-status context (default `buildkite/build`). */
+  context?: string;
+  /** Comment body for issue_comment / review comment (required for those). */
+  comment?: string;
+  /** Real check to mirror (app slug / conclusion) for CI events. */
+  check?: ReplayCheck;
+}
+
+export interface SynthesizedEvent {
+  eventName: string;
+  action?: string;
+  payload: Record<string, unknown>;
+}
+
+export type SynthesizeResult = SynthesizedEvent | { error: string };
+
+/** Build a webhook payload for `input.event` from the PR data. */
+export function synthesizeGitHubEvent(
+  input: SynthesizeInput
+): SynthesizeResult {
+  const { repo, pull } = input;
+  const author = pull.user ?? undefined;
+  const actor = input.sender ?? author ?? { login: "agent-serve-replay" };
+  const repository = repoPayload(repo);
+  const apiPrUrl = `https://api.github.com/repos/${repo.full_name}/pulls/${pull.number}`;
+  const prRefs = [
+    { number: pull.number, url: apiPrUrl, html_url: pull.html_url },
+  ];
+
+  switch (input.event) {
+    case "pull_request":
+      return {
+        eventName: "pull_request",
+        action: input.action ?? "synchronize",
+        payload: {
+          action: input.action ?? "synchronize",
+          number: pull.number,
+          repository,
+          sender: userPayload(actor),
+          pull_request: pullRequestPayload(pull, author),
+        },
+      };
+
+    case "issue_comment": {
+      if (input.comment === undefined || input.comment === "") {
+        return { error: "issue_comment needs --comment" };
+      }
+      const id = commentId(pull.number, 1);
+      return {
+        eventName: "issue_comment",
+        action: "created",
+        payload: {
+          action: "created",
+          repository,
+          sender: userPayload(actor),
+          issue: {
+            number: pull.number,
+            html_url: pull.html_url,
+            pull_request: { url: apiPrUrl, html_url: pull.html_url },
+          },
+          comment: {
+            id,
+            body: input.comment,
+            html_url: `${pull.html_url}#issuecomment-${id}`,
+            user: userPayload(actor),
+          },
+        },
+      };
+    }
+
+    case "pull_request_review_comment": {
+      if (input.comment === undefined || input.comment === "") {
+        return { error: "pull_request_review_comment needs --comment" };
+      }
+      const id = commentId(pull.number, 2);
+      return {
+        eventName: "pull_request_review_comment",
+        action: "created",
+        payload: {
+          action: "created",
+          repository,
+          sender: userPayload(actor),
+          pull_request: { number: pull.number, html_url: pull.html_url },
+          comment: {
+            id,
+            body: input.comment,
+            html_url: `${pull.html_url}#discussion_r${id}`,
+            path: "README.md",
+            line: 1,
+            user: userPayload(actor),
+          },
+        },
+      };
+    }
+
+    case "check_run":
+      return {
+        eventName: "check_run",
+        action: input.action ?? "completed",
+        payload: {
+          action: input.action ?? "completed",
+          repository,
+          sender: ciSender(input.check),
+          check_run: {
+            id: input.check?.id ?? commentId(pull.number, 3),
+            name: input.check?.name ?? "ci",
+            head_sha: pull.head.sha,
+            status: "completed",
+            conclusion:
+              input.conclusion ?? input.check?.conclusion ?? "failure",
+            app: ciApp(input.check),
+            check_suite: { id: commentId(pull.number, 4) },
+            pull_requests: prRefs,
+          },
+        },
+      };
+
+    case "check_suite":
+      return {
+        eventName: "check_suite",
+        action: input.action ?? "completed",
+        payload: {
+          action: input.action ?? "completed",
+          repository,
+          sender: ciSender(input.check),
+          check_suite: {
+            id: input.check?.id ?? commentId(pull.number, 4),
+            head_sha: pull.head.sha,
+            status: "completed",
+            conclusion:
+              input.conclusion ?? input.check?.conclusion ?? "failure",
+            app: ciApp(input.check),
+            pull_requests: prRefs,
+          },
+        },
+      };
+
+    case "workflow_run":
+      return {
+        eventName: "workflow_run",
+        action: input.action ?? "completed",
+        payload: {
+          action: input.action ?? "completed",
+          repository,
+          sender: ciSender(input.check),
+          workflow_run: {
+            id: input.check?.id ?? commentId(pull.number, 5),
+            name: input.check?.name ?? "CI",
+            head_sha: pull.head.sha,
+            status: "completed",
+            conclusion: input.conclusion ?? "failure",
+            pull_requests: prRefs,
+          },
+        },
+      };
+
+    case "status": {
+      const state = input.state ?? input.conclusion ?? "failure";
+      return {
+        eventName: "status",
+        payload: {
+          state,
+          sha: pull.head.sha,
+          context: input.context ?? "buildkite/build",
+          description: `Replayed ${state} status`,
+          target_url: null,
+          repository,
+          sender: ciSender(input.check),
+          branches: [{ name: pull.head.ref, commit: { sha: pull.head.sha } }],
+          commit: { sha: pull.head.sha, html_url: pull.html_url },
+          pull_requests: prRefs,
+        },
+      };
+    }
+
+    default:
+      return { error: `cannot synthesize unsupported event: ${input.event}` };
+  }
+}
+
+/** Hex HMAC-SHA256 for the `X-Hub-Signature-256` header (`sha256=<hex>`). */
+export function signGitHubWebhookBody(options: {
+  secret: string;
+  body: string | Buffer;
+}): string {
+  return createHmac("sha256", options.secret)
+    .update(options.body)
+    .digest("hex");
+}
+
+/**
+ * Resolve the events to replay: explicit list (validated), `*` → the channel's
+ * declared events intersected with what replay can synthesize, or the default
+ * (`pull_request`).
+ */
+export function selectReplayEvents(
+  requested: readonly string[] | undefined,
+  channelEvents: readonly string[]
+): { events: string[]; unsupported: string[] } {
+  if (requested === undefined || requested.length === 0) {
+    return { events: ["pull_request"], unsupported: [] };
+  }
+  if (requested.length === 1 && requested[0] === "*") {
+    const events = channelEvents.filter(isSynthesizableEvent);
+    return {
+      events: events.length > 0 ? events : ["pull_request"],
+      unsupported: [],
+    };
+  }
+  const events: string[] = [];
+  const unsupported: string[] = [];
+  for (const event of requested) {
+    if (isSynthesizableEvent(event)) {
+      events.push(event);
+    } else {
+      unsupported.push(event);
+    }
+  }
+  return { events, unsupported };
+}
+
+function repoPayload(repo: ReplayRepo): Record<string, unknown> {
+  const [ownerFromName, nameFromFull] = repo.full_name.split("/");
+  return {
+    id: repo.id,
+    name: repo.name ?? nameFromFull,
+    full_name: repo.full_name,
+    html_url: repo.html_url,
+    default_branch: repo.default_branch,
+    owner: { login: repo.owner?.login ?? ownerFromName },
+  };
+}
+
+function pullRequestPayload(
+  pull: ReplayPull,
+  author: ReplayUser | undefined
+): Record<string, unknown> {
+  return {
+    number: pull.number,
+    html_url: pull.html_url,
+    title: pull.title,
+    body: pull.body ?? null,
+    draft: pull.draft ?? false,
+    merged: pull.merged ?? false,
+    user: author === undefined ? undefined : userPayload(author),
+    head: {
+      ref: pull.head.ref,
+      sha: pull.head.sha,
+      repo: pull.head.repo,
+    },
+    base: { ref: pull.base.ref, sha: pull.base.sha },
+  };
+}
+
+function userPayload(user: ReplayUser): Record<string, unknown> {
+  return { login: user.login, id: user.id, type: user.type ?? "User" };
+}
+
+function ciSender(check: ReplayCheck | undefined): Record<string, unknown> {
+  const slug = check?.app?.slug;
+  const login = slug === undefined ? "github-actions[bot]" : `${slug}[bot]`;
+  return { login, type: "Bot" };
+}
+
+function ciApp(check: ReplayCheck | undefined): Record<string, unknown> {
+  return {
+    slug: check?.app?.slug ?? "github-actions",
+    name: check?.app?.name ?? "GitHub Actions",
+  };
+}
+
+/** Stable, PR-scoped synthetic id so re-runs are reproducible. */
+function commentId(prNumber: number, kind: number): number {
+  return prNumber * 100 + kind;
+}

package/src/channels/github/state.ts

@@ -0,0 +1,95 @@
+/**
+ * Durable per-session GitHub channel state.
+ */
+
+import type { GitHubBindingState } from "./binding.js";
+import type { GitHubConversationKind } from "./types.js";
+
+export interface GitHubChannelState extends GitHubBindingState {
+  deliveryId: string | null;
+  eventName: string | null;
+  headSha: string | null;
+  baseRef: string | null;
+  headRef: string | null;
+}
+
+export function emptyGitHubChannelState(
+  overrides: Partial<GitHubChannelState> = {}
+): GitHubChannelState {
+  return {
+    conversationKind: "pull_request",
+    installationId: null,
+    issueNumber: null,
+    owner: "",
+    pullRequestNumber: null,
+    repo: "",
+    repositoryId: null,
+    reviewCommentId: null,
+    reviewThreadRootCommentId: null,
+    triggeringCommentId: null,
+    deliveryId: null,
+    eventName: null,
+    headSha: null,
+    baseRef: null,
+    headRef: null,
+    ...overrides,
+  };
+}
+
+/** Build binding fields for an inbound conversation. */
+export function githubBindingStateForEvent(input: {
+  kind: GitHubConversationKind;
+  owner: string;
+  repo: string;
+  number: number;
+  repositoryId?: number;
+  installationId?: number;
+  triggeringCommentId?: number;
+  reviewCommentId?: number;
+  reviewThreadRootCommentId?: number;
+}): GitHubBindingState {
+  if (input.kind === "issue") {
+    return {
+      conversationKind: "issue",
+      installationId: input.installationId ?? null,
+      issueNumber: input.number,
+      owner: input.owner,
+      pullRequestNumber: null,
+      repo: input.repo,
+      repositoryId: input.repositoryId ?? null,
+      reviewCommentId: null,
+      reviewThreadRootCommentId: null,
+      triggeringCommentId: input.triggeringCommentId ?? null,
+    };
+  }
+  if (input.kind === "review_thread") {
+    return {
+      conversationKind: "review_thread",
+      installationId: input.installationId ?? null,
+      issueNumber: null,
+      owner: input.owner,
+      pullRequestNumber: input.number,
+      repo: input.repo,
+      repositoryId: input.repositoryId ?? null,
+      reviewCommentId: input.reviewCommentId ?? null,
+      reviewThreadRootCommentId:
+        input.reviewThreadRootCommentId ??
+        input.reviewCommentId ??
+        input.triggeringCommentId ??
+        null,
+      triggeringCommentId: input.triggeringCommentId ?? null,
+    };
+  }
+  return {
+    conversationKind: "pull_request",
+    installationId: input.installationId ?? null,
+    issueNumber: null,
+    owner: input.owner,
+    pullRequestNumber: input.number,
+    repo: input.repo,
+    repositoryId: input.repositoryId ?? null,
+    reviewCommentId: null,
+    reviewThreadRootCommentId: null,
+    triggeringCommentId: input.triggeringCommentId ?? null,
+  };
+}