@cursor/july 0.1.1

package/src/channels/github/types.ts

@@ -0,0 +1,490 @@
+import type {
+  AgentCloudOptions,
+  AuthContext,
+  AuthPolicy,
+  ChannelEventHandlers,
+  ChannelStartArgs,
+  HostContext,
+} from "../../types.js";
+import type { GitHubApiOptions } from "./api.js";
+import type { GitHubHandle, GitHubThread } from "./binding.js";
+import type { GitHubProgressConfig } from "./defaults.js";
+import type { GitHubChannelState } from "./state.js";
+
+/** A credential value: a literal or a lazy resolver fetched on demand. */
+export type GitHubCredentialValue =
+  | string
+  | (() => string | undefined | Promise<string | undefined>);
+
+/**
+ * GitHub webhook + API credentials. Every field falls back to an env var
+ * (or `gh auth token` for API calls), so you can drop the `credentials`
+ * block entirely once these are set:
+ *
+ * ```bash
+ * GITHUB_WEBHOOK_SECRET=...        # verifies the webhook signature
+ * GITHUB_APP_ID=...                # App JWT path (preferred in production)
+ * GITHUB_APP_PRIVATE_KEY=...
+ * GITHUB_APP_INSTALLATION_ID=...   # host / non-webhook App auth
+ * GITHUB_APP_SLUG=...              # supplies botName when it is not set in config
+ * GITHUB_TOKEN=...                 # local PAT fallback (or GH_TOKEN / `gh auth`)
+ * ```
+ *
+ * API auth prefers App installation tokens when App credentials are set,
+ * then falls back to `GITHUB_TOKEN` / `GH_TOKEN` / `gh auth token` for local
+ * testing.
+ */
+export interface GitHubChannelCredentials {
+  /**
+   * Webhook secret used to verify `X-Hub-Signature-256` before parsing the
+   * payload. Falls back to `GITHUB_WEBHOOK_SECRET`.
+   */
+  webhookSecret?: GitHubCredentialValue;
+  /**
+   * Explicit bearer token for GitHub REST calls. Prefer this only when you
+   * intentionally override ambient auth (e.g. tests). Falls back to App
+   * installation tokens, then `GITHUB_TOKEN` / `GH_TOKEN` / `gh auth token`.
+   */
+  token?: GitHubCredentialValue;
+  /**
+   * Pre-resolved installation access token (Connect-style). Same effect as
+   * {@link token} for API calls; skips App JWT exchange.
+   */
+  installationToken?: GitHubCredentialValue;
+  /** GitHub App id for installation-token minting. Falls back to `GITHUB_APP_ID`. */
+  appId?: GitHubCredentialValue | number;
+  /** GitHub App private key (PEM). Falls back to `GITHUB_APP_PRIVATE_KEY`. */
+  privateKey?: GitHubCredentialValue;
+}
+
+/** @deprecated Prefer {@link GitHubChannelCredentials}. */
+export type GitHubCredentials = GitHubChannelCredentials;
+
+export type GitHubPullRequestAction =
+  | "opened"
+  | "reopened"
+  | "synchronize"
+  | "ready_for_review"
+  | "edited"
+  | "closed"
+  | "labeled"
+  | "unlabeled"
+  | "assigned"
+  | "unassigned"
+  | "review_requested"
+  | "review_request_removed"
+  | "converted_to_draft";
+
+export type GitHubIssueAction =
+  | "opened"
+  | "edited"
+  | "closed"
+  | "reopened"
+  | "labeled"
+  | "unlabeled"
+  | "assigned"
+  | "unassigned";
+
+export type GitHubConversationKind = "issue" | "pull_request" | "review_thread";
+
+export type GitHubCiAction =
+  | "created"
+  | "completed"
+  | "rerequested"
+  | "requested_action";
+
+export type GitHubCiConclusion =
+  | "success"
+  | "failure"
+  | "neutral"
+  | "cancelled"
+  | "timed_out"
+  | "action_required"
+  | "stale"
+  | "skipped"
+  | null;
+
+export type GitHubCiStatus =
+  | "queued"
+  | "in_progress"
+  | "completed"
+  | "waiting"
+  | "requested"
+  | "pending"
+  | string;
+
+/** Normalized actor on a delivery. */
+export interface GitHubUser {
+  login: string;
+  id?: number;
+  type?: "User" | "Bot" | "Organization" | string;
+}
+
+/** Normalized repository on a delivery. */
+export interface GitHubRepositoryRef {
+  fullName: string;
+  url: string;
+  owner: string;
+  name: string;
+  id?: number;
+}
+
+/**
+ * Wire shape of the `pull_request` webhook payload, narrowed to the fields
+ * the channel consumes.
+ */
+export type GitHubPullRequestPayload = {
+  action: string;
+  repository: {
+    id?: number;
+    full_name: string;
+    html_url: string;
+    name?: string;
+    owner?: { login?: string };
+  };
+  pull_request: {
+    number: number;
+    html_url: string;
+    title: string;
+    body?: string | null;
+    draft?: boolean;
+    user?: {
+      login?: string;
+      id?: number;
+      type?: string;
+    } | null;
+    head: {
+      ref: string;
+      sha: string;
+    };
+    base: {
+      ref: string;
+      sha?: string;
+    };
+  };
+  sender?: {
+    login?: string;
+    id?: number;
+    type?: string;
+  } | null;
+  installation?: { id?: number } | null;
+};
+
+/** Normalized `pull_request` event handed to {@link GitHubPullRequestHook}. */
+export interface GitHubPullRequestEvent {
+  action: GitHubPullRequestAction | string;
+  number: number;
+  url: string;
+  title: string;
+  body?: string;
+  headRef: string;
+  headSha: string;
+  baseRef: string;
+  baseSha?: string;
+  draft: boolean;
+  authorLogin?: string;
+}
+
+/** Normalized `issues` event. */
+export interface GitHubIssueEvent {
+  action: GitHubIssueAction | string;
+  number: number;
+  url: string;
+  title: string;
+  body?: string;
+  authorLogin?: string;
+}
+
+/** Normalized comment on an issue, PR timeline, or review thread. */
+export interface GitHubComment {
+  id: number;
+  body: string;
+  url: string;
+  htmlUrl: string;
+  author?: GitHubUser;
+  /** Present for inline review comments. */
+  path?: string;
+  line?: number | null;
+  pullRequestReviewId?: number | null;
+  /** Root or parent review comment when this comment is a thread reply. */
+  inReplyToId?: number;
+}
+
+/** Shared CI fields across check_suite / check_run / workflow_run. */
+export interface GitHubCiPullRequestRef {
+  number: number;
+  url?: string;
+}
+
+export interface GitHubCiAppRef {
+  slug?: string;
+  name?: string;
+}
+
+export interface GitHubCiBase {
+  action: GitHubCiAction | string;
+  status?: GitHubCiStatus;
+  conclusion?: GitHubCiConclusion;
+  headSha: string;
+  app: GitHubCiAppRef;
+  pullRequests: GitHubCiPullRequestRef[];
+}
+
+export interface GitHubCheckSuiteEvent extends GitHubCiBase {
+  checkSuiteId: number;
+}
+
+export interface GitHubCheckRunEvent extends GitHubCiBase {
+  checkRunId: number;
+  name?: string;
+  checkSuiteId?: number;
+}
+
+export interface GitHubWorkflowRunEvent extends GitHubCiBase {
+  workflowRunId: number;
+  name?: string;
+  workflowId?: number;
+  htmlUrl?: string;
+}
+
+/**
+ * Legacy commit `status` webhook (Statuses API). Distinct from Checks /
+ * Actions events — use {@link GitHubChannelOptions.onStatus}.
+ */
+export interface GitHubStatusEvent {
+  state: "pending" | "success" | "failure" | "error" | string;
+  context: string;
+  description?: string | null;
+  targetUrl?: string | null;
+  sha: string;
+  name?: string;
+  branches: Array<{ name: string; commit?: { sha?: string } }>;
+  commit?: { sha?: string; htmlUrl?: string };
+  raw: unknown;
+}
+
+/**
+ * Raw webhook envelope for {@link GitHubChannelOptions.onEvent}. Prefer
+ * typed hooks (`onComment`, `onPullRequest`, …) when possible.
+ */
+export interface GitHubRawEvent {
+  eventName: string;
+  deliveryId?: string;
+  action?: string;
+  payload: unknown;
+}
+
+/**
+ * Per-delivery context shared by every inbound hook: where the event landed,
+ * who triggered it, delivery-scoped GitHub helpers (`github` / `thread`), and
+ * shared host services (`host`) for MCP / host GitHub / Slack.
+ */
+export interface GitHubEventContext {
+  /** `X-GitHub-Delivery` header, when present. */
+  deliveryId?: string;
+  /** `X-GitHub-Event` header. */
+  eventName: string;
+  repository: GitHubRepositoryRef;
+  /** The thread the session is anchored to. */
+  conversation: {
+    kind: GitHubConversationKind;
+    number: number;
+    url: string;
+  };
+  /** Login of the actor that triggered the delivery. */
+  senderLogin?: string;
+  sender?: GitHubUser;
+  /** Installation id from the webhook payload, when present. */
+  installationId?: number;
+  /** Authenticated GitHub helpers (`getOctokit`, `request`, `createStatus`). */
+  github: GitHubHandle;
+  /** Post / react on the conversation thread. */
+  thread: GitHubThread;
+  /** Shared host services (MCP / host GitHub / Slack). Same as tool `ctx.host`. */
+  host: HostContext;
+}
+
+/**
+ * A hook's decision to handle an inbound event. Return `null` from the hook
+ * to ignore the delivery instead.
+ */
+export type GitHubDispatch = GitHubTurnDispatch | GitHubTaskDispatch;
+
+/** Start (or resume) a model turn for the event. */
+export interface GitHubTurnDispatch {
+  /** Who the turn runs as. Use `defaultGitHubAuth(ctx)` to derive it from the actor. */
+  auth: AuthContext | null;
+  /** Extra prompt lines appended to the default event message. */
+  context?: readonly string[];
+  /** Optional message override (comment hooks use the comment body by default). */
+  message?: string;
+  /** Optional session title override. */
+  title?: string;
+}
+
+/**
+ * Run a host-side handler for the event instead of a model turn. The task
+ * runs in the background (`waitUntil`) after the webhook is acknowledged
+ * with a 202, so it can outlive GitHub's ~10s delivery timeout.
+ */
+export interface GitHubTaskDispatch {
+  task: () => void | Promise<void>;
+}
+
+export type GitHubDispatchResult =
+  | GitHubDispatch
+  | null
+  | Promise<GitHubDispatch | null>;
+
+/**
+ * Inbound `pull_request` hook. Return `{ auth }` to dispatch a turn,
+ * `{ task }` to run a host-side handler, or `null` to ignore the delivery.
+ * Without this hook the channel keeps the agent-serve default action gate
+ * (opened / reopened / synchronize / ready_for_review). Eve has no default —
+ * declare the hook for Eve-style opt-in dispatch.
+ */
+export type GitHubPullRequestHook = (
+  ctx: GitHubEventContext,
+  pullRequest: GitHubPullRequestEvent
+) => GitHubDispatchResult;
+
+/**
+ * Invoked for every `@mention` of the bot in an issue/PR timeline comment or
+ * an inline review comment; `ctx.conversation.kind` distinguishes the surface.
+ * Return `{ auth }` to dispatch or `null` to ignore. Replaces the default
+ * mention gate when declared.
+ */
+export type GitHubCommentHook = (
+  ctx: GitHubEventContext,
+  comment: GitHubComment
+) => GitHubDispatchResult;
+
+/** Opt-in `issues` webhook hook. No default dispatch. */
+export type GitHubIssueHook = (
+  ctx: GitHubEventContext,
+  issue: GitHubIssueEvent
+) => GitHubDispatchResult;
+
+/** Opt-in `check_suite` webhook hook. No default dispatch. */
+export type GitHubCheckSuiteHook = (
+  ctx: GitHubEventContext,
+  checkSuite: GitHubCheckSuiteEvent
+) => GitHubDispatchResult;
+
+/** Opt-in `check_run` webhook hook. No default dispatch. */
+export type GitHubCheckRunHook = (
+  ctx: GitHubEventContext,
+  checkRun: GitHubCheckRunEvent
+) => GitHubDispatchResult;
+
+/** Opt-in `workflow_run` webhook hook. No default dispatch. */
+export type GitHubWorkflowRunHook = (
+  ctx: GitHubEventContext,
+  workflowRun: GitHubWorkflowRunEvent
+) => GitHubDispatchResult;
+
+/**
+ * Opt-in legacy commit `status` webhook hook. No default dispatch. Turns are
+ * only started when the hook returns a dispatch *and* a PR can be resolved
+ * from the payload (otherwise use `{ task }` for host-side work).
+ */
+export type GitHubStatusHook = (
+  ctx: GitHubEventContext,
+  status: GitHubStatusEvent
+) => GitHubDispatchResult;
+
+/**
+ * Catch-all for any webhook event (including ones with typed hooks). Runs
+ * after the typed handler path when the typed hook is absent or returns
+ * undefined-as-no-handler; for events with no typed hook, this is the only
+ * dispatch path. Return `null` to ignore.
+ */
+export type GitHubEventHook = (
+  ctx: GitHubEventContext,
+  event: GitHubRawEvent
+) => GitHubDispatchResult;
+
+export type GitHubCloudOptionsResolver = (
+  ctx: GitHubEventContext,
+  pullRequest: GitHubPullRequestEvent
+) => AgentCloudOptions | undefined | Promise<AgentCloudOptions | undefined>;
+
+export interface GitHubChannelOptions {
+  /**
+   * Bot / App slug used by the default `@mention` gate on comments.
+   * Falls back to `GITHUB_APP_SLUG`.
+   */
+  botName?: string;
+  /**
+   * Webhook + API credentials. When the resolved webhook secret is set, the
+   * channel verifies `X-Hub-Signature-256` before parsing the payload.
+   * API calls prefer App installation tokens, then local PAT / `gh auth`.
+   */
+  credentials?: GitHubChannelCredentials;
+  /** Optional GitHub API transport overrides (`apiBaseUrl`, `fetch`). */
+  api?: GitHubApiOptions;
+  /**
+   * Route auth chain. Defaults to strict loopback auth without a webhook
+   * secret, and allow-all with one because the GitHub HMAC is the request
+   * auth.
+   */
+  auth?: AuthPolicy[];
+  /** Route path under `/v1/channels/<name>`. Defaults to `/`. */
+  path?: string;
+  /**
+   * Webhook events advertised to `agent-serve github forward` (published as
+   * `meta.githubWebhookEvents`). Defaults to the set derived from the declared
+   * hooks. Set this to pin an exact list — e.g. to include events only handled
+   * through {@link onEvent} such as `pull_request_review`.
+   */
+  webhookEvents?: readonly string[];
+  /**
+   * Decide whether an inbound `pull_request` event starts a turn. Return
+   * `{ auth: defaultGitHubAuth(ctx) }` to dispatch, `null` to ignore.
+   * Without this hook the channel dispatches on opened, reopened,
+   * synchronize, and ready_for_review (agent-serve default; Eve is opt-in).
+   */
+  onPullRequest?: GitHubPullRequestHook;
+  /**
+   * `@mention` gate for `issue_comment` and `pull_request_review_comment`.
+   * Without this hook, comments that `@mention` {@link botName} dispatch.
+   */
+  onComment?: GitHubCommentHook;
+  /** Opt-in `issues` webhook handler. No default dispatch. */
+  onIssue?: GitHubIssueHook;
+  /** Opt-in `check_suite` webhook handler. No default dispatch. */
+  onCheckSuite?: GitHubCheckSuiteHook;
+  /** Opt-in `check_run` webhook handler. No default dispatch. */
+  onCheckRun?: GitHubCheckRunHook;
+  /** Opt-in `workflow_run` webhook handler. No default dispatch. */
+  onWorkflowRun?: GitHubWorkflowRunHook;
+  /** Opt-in legacy commit `status` webhook handler. No default dispatch. */
+  onStatus?: GitHubStatusHook;
+  /**
+   * Catch-all webhook handler. Invoked for events without a typed hook, and
+   * as a fallback when a typed hook is not declared. Prefer typed hooks when
+   * the event is known.
+   */
+  onEvent?: GitHubEventHook;
+  /**
+   * Override / extend default stream-event handlers (eyes reaction, reply
+   * posting). Handlers you provide replace the matching defaults.
+   */
+  events?: ChannelEventHandlers<GitHubChannelState>;
+  /** Acknowledgement progress surfaces (reactions). */
+  progress?: GitHubProgressConfig;
+  /**
+   * When false, skip posting assistant / error comments back to GitHub.
+   * Defaults to true.
+   */
+  deliverReplies?: boolean;
+  /**
+   * Per-session cloud options. Pass `true` to attach the PR repo using the
+   * pull request URL, or a resolver for custom cloud options.
+   */
+  cloud?: boolean | AgentCloudOptions | GitHubCloudOptionsResolver;
+  /** Called once when the server mounts this channel. */
+  onStart?: (args: ChannelStartArgs) => void | Promise<void>;
+  /** Called when the server shuts down. */
+  onStop?: () => void | Promise<void>;
+}