@cursor/july 0.1.1

package/src/channels/github/binding.ts

@@ -0,0 +1,223 @@
+/**
+ * Rebuild GitHub API + thread handles for inbound hooks and stream events.
+ */
+
+import type { Octokit } from "@octokit/rest";
+import {
+  callGitHubApi,
+  createGitHubCommitStatus,
+  createGitHubIssueComment,
+  createGitHubOctokit,
+  createGitHubReaction,
+  createGitHubReviewCommentReply,
+  type GitHubApiMethod,
+  type GitHubApiOptions,
+  type GitHubApiResponse,
+  type GitHubJsonObject,
+  type GitHubPostedComment,
+  type GitHubReactionContent,
+} from "./api.js";
+import type {
+  GitHubChannelCredentials,
+  GitHubConversationKind,
+  GitHubRepositoryRef,
+} from "./types.js";
+
+/** Hidden marker on outbound GitHub comments so inbound dispatch ignores them. */
+export const GITHUB_OUTBOUND_MARKER = "<!-- agent-serve-github -->";
+
+export function formatGitHubOutboundComment(body: string): string {
+  if (body.includes(GITHUB_OUTBOUND_MARKER)) {
+    return body;
+  }
+  return `${body.trimEnd()}\n\n${GITHUB_OUTBOUND_MARKER}`;
+}
+
+export interface GitHubBindingConfig {
+  api?: GitHubApiOptions;
+  credentials?: GitHubChannelCredentials;
+}
+
+/** Serializable fields needed to rebuild handles. */
+export interface GitHubBindingState {
+  conversationKind: GitHubConversationKind;
+  installationId: number | null;
+  issueNumber: number | null;
+  owner: string;
+  pullRequestNumber: number | null;
+  repo: string;
+  repositoryId: number | null;
+  reviewCommentId: number | null;
+  reviewThreadRootCommentId: number | null;
+  triggeringCommentId: number | null;
+}
+
+/** GitHub operations exposed to hooks (`ctx.github`). */
+export interface GitHubHandle {
+  installationId: number | undefined;
+  repository: GitHubRepositoryRef;
+  /**
+   * Authenticated `@octokit/rest` client. Prefer typed `octokit.rest.*`
+   * methods for new code; keep {@link request} / {@link createStatus} for
+   * thin wrappers and host-side tasks.
+   */
+  getOctokit(): Promise<Octokit>;
+  /**
+   * Call an arbitrary GitHub REST path with channel auth (PAT / App /
+   * `gh auth token`). Prefer {@link getOctokit} for typed calls.
+   */
+  request<T = unknown>(input: {
+    body?: GitHubJsonObject;
+    method: GitHubApiMethod;
+    path: string;
+  }): Promise<GitHubApiResponse<T>>;
+  /** Create a commit status on `sha`. */
+  createStatus(input: {
+    sha: string;
+    state: "error" | "failure" | "pending" | "success";
+    context?: string;
+    description?: string;
+    targetUrl?: string;
+  }): Promise<GitHubApiResponse>;
+}
+
+/** Thread-scoped operations for the current conversation (`ctx.thread`). */
+export interface GitHubThread {
+  kind: GitHubConversationKind;
+  /** Post a reply on the issue/PR timeline or review thread. */
+  post(message: string): Promise<GitHubPostedComment>;
+  /**
+   * React to the triggering comment. No-ops when there is no comment to
+   * react to (e.g. a PR-opened delivery).
+   */
+  react(content: GitHubReactionContent): Promise<void>;
+}
+
+export function buildGitHubBinding(input: {
+  config: GitHubBindingConfig;
+  state: GitHubBindingState;
+}): { github: GitHubHandle; thread: GitHubThread } {
+  const { config, state } = input;
+  const repository: GitHubRepositoryRef = {
+    fullName: `${state.owner}/${state.repo}`,
+    url: `https://github.com/${state.owner}/${state.repo}`,
+    owner: state.owner,
+    name: state.repo,
+    ...(state.repositoryId === null ? {} : { id: state.repositoryId }),
+  };
+  const installationId = state.installationId ?? undefined;
+
+  let octokitPromise: Promise<Octokit> | undefined;
+  const getOctokit = (): Promise<Octokit> => {
+    octokitPromise ??= createGitHubOctokit({
+      api: config.api,
+      credentials: config.credentials,
+      installationId,
+    });
+    return octokitPromise;
+  };
+
+  const github: GitHubHandle = {
+    installationId,
+    repository,
+    getOctokit,
+    request(req) {
+      return callGitHubApi({
+        api: config.api,
+        body: req.body,
+        credentials: config.credentials,
+        installationId,
+        method: req.method,
+        path: req.path,
+      });
+    },
+    createStatus(status) {
+      return createGitHubCommitStatus({
+        api: config.api,
+        credentials: config.credentials,
+        installationId,
+        owner: state.owner,
+        repo: state.repo,
+        sha: status.sha,
+        state: status.state,
+        ...(status.context === undefined ? {} : { context: status.context }),
+        ...(status.description === undefined
+          ? {}
+          : { description: status.description }),
+        ...(status.targetUrl === undefined
+          ? {}
+          : { targetUrl: status.targetUrl }),
+      });
+    },
+  };
+
+  const thread: GitHubThread = {
+    kind: state.conversationKind,
+    post(message) {
+      if (state.conversationKind === "review_thread") {
+        return createGitHubReviewCommentReply({
+          api: config.api,
+          body: message,
+          commentId: requiredNumber(
+            state.reviewThreadRootCommentId ?? state.reviewCommentId,
+            "reviewThreadRootCommentId"
+          ),
+          credentials: config.credentials,
+          installationId,
+          owner: state.owner,
+          pullRequestNumber: requiredNumber(
+            state.pullRequestNumber,
+            "pullRequestNumber"
+          ),
+          repo: state.repo,
+        });
+      }
+      return createGitHubIssueComment({
+        api: config.api,
+        body: message,
+        credentials: config.credentials,
+        installationId,
+        issueNumber: requiredNumber(
+          state.issueNumber ?? state.pullRequestNumber,
+          "issueNumber"
+        ),
+        owner: state.owner,
+        repo: state.repo,
+      });
+    },
+    async react(content) {
+      const commentId =
+        state.conversationKind === "review_thread"
+          ? state.reviewCommentId
+          : state.triggeringCommentId;
+      if (commentId === null) {
+        return;
+      }
+      await createGitHubReaction({
+        api: config.api,
+        commentId,
+        content,
+        credentials: config.credentials,
+        installationId,
+        owner: state.owner,
+        repo: state.repo,
+        subject:
+          state.conversationKind === "review_thread"
+            ? "pull_request_review_comment"
+            : "issue_comment",
+      });
+    },
+  };
+
+  return { github, thread };
+}
+
+function requiredNumber(
+  value: number | null | undefined,
+  name: string
+): number {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  throw new Error(`githubChannel: missing ${name}.`);
+}

package/src/channels/github/defaults.ts

@@ -0,0 +1,111 @@
+/**
+ * Default stream-event handlers for the GitHub channel.
+ */
+
+import type { ChannelEventHandlers } from "../../types.js";
+import type { GitHubBindingConfig } from "./binding.js";
+import { buildGitHubBinding, formatGitHubOutboundComment } from "./binding.js";
+import type { GitHubChannelState } from "./state.js";
+
+export interface GitHubProgressConfig {
+  /** When false, skip the eyes reaction on turn.started. Defaults to true. */
+  reactions?: boolean;
+}
+
+export interface BuildDefaultGitHubEventsOptions extends GitHubBindingConfig {
+  progress?: GitHubProgressConfig;
+  /**
+   * When false, skip posting completed assistant messages back to GitHub.
+   * Defaults to true.
+   */
+  deliverReplies?: boolean;
+}
+
+/**
+ * Built-in delivery: eyes reaction on turn start, post assistant text on
+ * `message.completed`, and a short error comment on turn/session failure.
+ */
+export function buildDefaultGitHubEvents(
+  options: BuildDefaultGitHubEventsOptions = {}
+): ChannelEventHandlers<GitHubChannelState> {
+  const deliverReplies = options.deliverReplies !== false;
+
+  return {
+    async "turn.started"(_event, channel) {
+      if (options.progress?.reactions === false) {
+        return;
+      }
+      if (channel.state.owner === "" || channel.state.repo === "") {
+        return;
+      }
+      try {
+        const { thread } = buildGitHubBinding({
+          config: options,
+          state: channel.state,
+        });
+        await thread.react("eyes");
+      } catch {
+        // Soft-fail: missing token / no triggering comment is fine.
+      }
+    },
+
+    async "message.completed"(event, channel) {
+      if (!deliverReplies) {
+        return;
+      }
+      if (event.data.finishReason === "tool_call" || event.data.text === "") {
+        return;
+      }
+      if (channel.state.owner === "" || channel.state.repo === "") {
+        return;
+      }
+      try {
+        const { thread } = buildGitHubBinding({
+          config: options,
+          state: channel.state,
+        });
+        await thread.post(formatGitHubOutboundComment(event.data.text));
+      } catch {
+        // Soft-fail delivery so a missing token does not crash the session.
+      }
+    },
+
+    async "turn.failed"(event, channel) {
+      await postFailure(channel, options, event.data.message);
+    },
+
+    async "session.failed"(event, channel) {
+      await postFailure(channel, options, event.data.message);
+    },
+  };
+}
+
+async function postFailure(
+  channel: { state: GitHubChannelState },
+  options: BuildDefaultGitHubEventsOptions,
+  _error: string
+): Promise<void> {
+  if (options.deliverReplies === false) {
+    return;
+  }
+  if (channel.state.owner === "" || channel.state.repo === "") {
+    return;
+  }
+  try {
+    const { thread } = buildGitHubBinding({
+      config: options,
+      state: channel.state,
+    });
+    await thread.post(
+      formatGitHubOutboundComment(
+        [
+          "I hit an error while handling your request.",
+          "",
+          "Please try again, or reach out if it keeps failing.",
+        ].join("\n")
+      )
+    );
+  } catch {
+    // Soft-fail.
+  }
+}

package/src/channels/github/events.ts

@@ -0,0 +1,72 @@
+/**
+ * Webhook event derivation for the GitHub channel.
+ *
+ * `agent-serve github forward` reads the set of webhook events a channel is
+ * wired to dispatch (published as `meta.githubWebhookEvents`) so it can build
+ * `gh webhook forward --events=…` without the operator hand-listing them.
+ */
+
+import type { GitHubChannelOptions } from "./types.js";
+
+/** {@link ChannelMeta.kind} value used by {@link githubChannel}. */
+export const GITHUB_CHANNEL_KIND = "github";
+
+/**
+ * Events the channel always parses through its built-in defaults: the
+ * `pull_request` gate and the `@mention` comment gates exist even when no
+ * hook is declared.
+ */
+const BASE_WEBHOOK_EVENTS: readonly string[] = [
+  "pull_request",
+  "issue_comment",
+  "pull_request_review_comment",
+];
+
+/** Typed opt-in hooks and the webhook event each subscribes to. */
+const OPT_IN_HOOK_EVENTS: ReadonlyArray<{
+  option: keyof GitHubChannelOptions;
+  event: string;
+}> = [
+  { option: "onIssue", event: "issues" },
+  { option: "onCheckSuite", event: "check_suite" },
+  { option: "onCheckRun", event: "check_run" },
+  { option: "onWorkflowRun", event: "workflow_run" },
+  { option: "onStatus", event: "status" },
+];
+
+/**
+ * Common events that only reach the `onEvent` catch-all (no typed hook). When
+ * `onEvent` is declared we forward these too so review activity is delivered.
+ */
+const CATCH_ALL_EVENTS: readonly string[] = [
+  "pull_request_review",
+  "pull_request_review_thread",
+];
+
+/**
+ * Derive the webhook events a {@link githubChannel} dispatches on from its
+ * declared hooks. When {@link GitHubChannelOptions.webhookEvents} is set it is
+ * authoritative and returned verbatim (deduped, order preserved) — use it to
+ * pin an exact list (e.g. to add events only handled via `onEvent`).
+ */
+export function deriveGitHubWebhookEvents(
+  options: GitHubChannelOptions
+): string[] {
+  if (options.webhookEvents !== undefined) {
+    return dedupe(options.webhookEvents);
+  }
+  const events: string[] = [...BASE_WEBHOOK_EVENTS];
+  for (const { option, event } of OPT_IN_HOOK_EVENTS) {
+    if (options[option] !== undefined) {
+      events.push(event);
+    }
+  }
+  if (options.onEvent !== undefined) {
+    events.push(...CATCH_ALL_EVENTS);
+  }
+  return dedupe(events);
+}
+
+function dedupe(events: readonly string[]): string[] {
+  return [...new Set(events.map((event) => event.trim()).filter(Boolean))];
+}