@cursor/bdk 0.2.3 → 0.2.5

package/src/channels/github/index.ts

@@ -1,54 +0,0 @@
-/**
- * GitHub webhook channel pack for agent-serve (Eve-compatible dispatch).
- *
- * ```ts
- * import { defaultGitHubAuth, githubChannel } from "@cursor/bdk/channels/github";
- *
- * export default githubChannel({
- *   botName: "my-agent",
- *   // Reuses `agent-sdk login` for events, ctx.github, ctx.host.github, and gh.
- *   cursorAccount: { repos: ["owner/repo"] },
- *   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 "./checks.js";
-export * from "./defaults.js";
-export * from "./events.js";
-export * from "./forward.js";
-export * from "./github-channel.js";
-export * from "./progress.js";
-export * from "./replay.js";
-export * from "./state.js";
-export * from "./types.js";

package/src/channels/github/progress.ts

@@ -1,365 +0,0 @@
-/**
- * Opt-in PR progress surfaces: Checks API run + sticky banner comment.
- */
-
-import {
-  createGitHubCheckRun,
-  createGitHubIssueComment,
-  GitHubApiError,
-  type GitHubCheckRunWriteInput,
-  updateGitHubCheckRun,
-  updateGitHubIssueComment,
-} from "./api.js";
-import type { GitHubBindingConfig } from "./binding.js";
-import { formatGitHubOutboundComment } from "./binding.js";
-import type { GitHubChannelState } from "./state.js";
-
-/** Merge-box check titles stay short; GitHub allows 1024, we clip to 140. */
-const STATUS_DESCRIPTION_MAX = 140;
-
-export type GitHubProgressPhase = "pending" | "success" | "failure";
-
-export interface GitHubProgressPhaseCopy {
-  pending?: string;
-  success?: string;
-  failure?: string;
-}
-
-export interface GitHubCommitStatusProgress extends GitHubProgressPhaseCopy {
-  /** Check run name (unique per check in the merge box). */
-  context: string;
-  /**
-   * Check Details URL for this session. When it resolves, it is written as
-   * `details_url` and (with {@link summaryLinkText}) appended to the summary.
-   */
-  detailsUrl?: (sessionId: string) => string | undefined;
-  /**
-   * `output.title` source. `"phase"` (default) uses the pending/success/
-   * failure copy. `"context"` uses the check name — the dashboard automation
-   * shape (`Cursor Security Agent: …`).
-   */
-  outputTitle?: "phase" | "context";
-  /**
-   * Markdown link label appended to the summary when {@link detailsUrl}
-   * resolves, e.g. `"View agent"`.
-   */
-  summaryLinkText?: string;
-  /**
-   * Conclusion for the failure phase. Default `"failure"`. Use `"neutral"`
-   * when a red merge-box check must not gate merge (findings live on the PR).
-   */
-  failureConclusion?: "failure" | "neutral";
-}
-
-export type GitHubBannerProgress = GitHubProgressPhaseCopy;
-
-export interface GitHubProgressConfig {
-  /** When false, skip the eyes reaction on turn.started. Defaults to true. */
-  reactions?: boolean;
-  /**
-   * Top-level tools that must each finish successfully before a completed
-   * turn is reported as successful. A missing, stubbed, or ultimately failed
-   * tool reports failure instead. Later successful retries replace an earlier
-   * failure for the same tool.
-   */
-  requireSuccessfulTools?: readonly string[];
-  /**
-   * Opt-in Checks API run on the PR head. Omit or `false` keeps today's
-   * behavior (no check from default events). With `cursorAccount`, enabling
-   * this opts the minted token up to `permissions: "contents-write"` so the
-   * hosted github-proxy lease includes `checks:write`.
-   */
-  commitStatus?: false | GitHubCommitStatusProgress;
-  /**
-   * Opt-in sticky PR/issue timeline comment. Created on first pending,
-   * PATCHed on later phases. Omit or `false` disables.
-   */
-  banner?: false | GitHubBannerProgress;
-}
-
-export interface GitHubProgressOptions extends GitHubBindingConfig {
-  botName?: string;
-  progress?: GitHubProgressConfig;
-}
-
-export function resolveCommitStatusProgress(
-  progress: GitHubProgressConfig | undefined,
-): GitHubCommitStatusProgress | null {
-  if (progress?.commitStatus === undefined || progress.commitStatus === false) {
-    return null;
-  }
-  return progress.commitStatus;
-}
-
-export function resolveBannerProgress(
-  progress: GitHubProgressConfig | undefined,
-): GitHubBannerProgress | null {
-  if (progress?.banner === undefined || progress.banner === false) {
-    return null;
-  }
-  return progress.banner;
-}
-
-export function progressPhaseCopy(input: {
-  copy: GitHubProgressPhaseCopy | undefined;
-  phase: GitHubProgressPhase;
-  label: string;
-}): string {
-  const custom = input.copy?.[input.phase];
-  if (custom !== undefined && custom.trim() !== "") {
-    return custom;
-  }
-  switch (input.phase) {
-    case "pending":
-      return `${input.label} running`;
-    case "success":
-      return `${input.label} finished`;
-    case "failure":
-      return `${input.label} failed`;
-  }
-}
-
-function clipStatusDescription(text: string): string {
-  if (text.length <= STATUS_DESCRIPTION_MAX) {
-    return text;
-  }
-  return `${text.slice(0, STATUS_DESCRIPTION_MAX - 1)}…`;
-}
-
-function progressLabel(options: GitHubProgressOptions, context?: string): string {
-  const bot = options.botName?.trim();
-  if (bot !== undefined && bot !== "") {
-    return bot;
-  }
-  if (context !== undefined && context.trim() !== "") {
-    return context;
-  }
-  return "Agent";
-}
-
-/**
- * Post or update opt-in progress surfaces for a turn phase.
- * Soft-fails on API errors (same posture as eyes / reply delivery).
- */
-export async function applyGitHubProgress(input: {
-  phase: GitHubProgressPhase;
-  sessionId?: string;
-  channel: { state: GitHubChannelState };
-  options: GitHubProgressOptions;
-}): Promise<void> {
-  const configured = resolveCommitStatusProgress(input.options.progress);
-  const banner = resolveBannerProgress(input.options.progress);
-  if (configured === null && banner === null) {
-    return;
-  }
-  const override = input.channel.state.progressCheckName?.trim();
-  const commitStatus =
-    configured === null || override === undefined || override === ""
-      ? configured
-      : { ...configured, context: override };
-
-  const tasks: Array<Promise<void>> = [];
-  if (commitStatus !== null) {
-    tasks.push(
-      postProgressCheckRun({
-        phase: input.phase,
-        sessionId: input.sessionId,
-        channel: input.channel,
-        options: input.options,
-        commitStatus,
-      }),
-    );
-  }
-  if (banner !== null) {
-    tasks.push(
-      upsertBanner({
-        phase: input.phase,
-        channel: input.channel,
-        options: input.options,
-        banner,
-        context: commitStatus?.context,
-      }),
-    );
-  }
-  await Promise.all(tasks);
-}
-
-function resolveProgressDetailsUrl(input: {
-  sessionId: string | undefined;
-  commitStatus: GitHubCommitStatusProgress;
-}): string | undefined {
-  if (input.sessionId === undefined || input.commitStatus.detailsUrl === undefined) {
-    return undefined;
-  }
-  const url = input.commitStatus.detailsUrl(input.sessionId)?.trim();
-  return url === "" ? undefined : url;
-}
-
-function appendSummaryLink(summary: string, detailsUrl?: string, linkText?: string): string {
-  const label = linkText?.trim();
-  if (detailsUrl === undefined || label === undefined || label === "") {
-    return summary;
-  }
-  return `${summary}\n\n[${label}](${detailsUrl})`;
-}
-
-async function postProgressCheckRun(input: {
-  phase: GitHubProgressPhase;
-  sessionId?: string;
-  channel: { state: GitHubChannelState };
-  options: GitHubProgressOptions;
-  commitStatus: GitHubCommitStatusProgress;
-}): Promise<void> {
-  const state = input.channel.state;
-  if (state.owner === "" || state.repo === "" || state.headSha === null || state.headSha === "") {
-    return;
-  }
-  const sha = state.headSha;
-  const phaseCopy = progressPhaseCopy({
-    copy: input.commitStatus,
-    phase: input.phase,
-    label: progressLabel(input.options, input.commitStatus.context),
-  });
-  const title = clipStatusDescription(
-    input.commitStatus.outputTitle === "context" ? input.commitStatus.context : phaseCopy,
-  );
-  const detailsUrl = resolveProgressDetailsUrl({
-    sessionId: input.sessionId,
-    commitStatus: input.commitStatus,
-  });
-  const write: GitHubCheckRunWriteInput = {
-    name: input.commitStatus.context,
-    ...checkRunPhaseFields(input.phase, input.commitStatus.failureConclusion),
-    ...(detailsUrl === undefined ? {} : { detailsUrl }),
-    output: {
-      title,
-      summary: appendSummaryLink(phaseCopy, detailsUrl, input.commitStatus.summaryLinkText),
-    },
-  };
-  const resource = {
-    api: input.options.api,
-    credentials: input.options.credentials,
-    installationId: state.installationId ?? undefined,
-    owner: state.owner,
-    repo: state.repo,
-  };
-  const reuseId =
-    state.progressCheckRunId !== null && state.progressCheckRunSha === sha
-      ? state.progressCheckRunId
-      : null;
-  // Completed runs cannot go back to in_progress. GitHub often 200s and
-  // leaves the run completed (sometimes 422). Create a new run so a later
-  // turn on the same SHA shows pending again.
-  const completedBlocksReuse =
-    write.status === "in_progress" && state.progressCheckRunCompleted === true;
-  try {
-    if (reuseId !== null && !completedBlocksReuse) {
-      try {
-        await updateGitHubCheckRun({
-          ...resource,
-          ...write,
-          checkRunId: reuseId,
-        });
-        state.progressCheckRunCompleted = write.status === "completed";
-        return;
-      } catch (error) {
-        if (!shouldRecreateCheckRun(error, write.status)) {
-          return;
-        }
-        state.progressCheckRunId = null;
-        state.progressCheckRunSha = null;
-        state.progressCheckRunCompleted = false;
-      }
-    }
-    const created = await createGitHubCheckRun({
-      ...resource,
-      ...write,
-      sha,
-    });
-    state.progressCheckRunId = created.id;
-    state.progressCheckRunSha = sha;
-    state.progressCheckRunCompleted = write.status === "completed";
-  } catch {
-    // Soft-fail: missing token / permission is fine.
-  }
-}
-
-function shouldRecreateCheckRun(
-  error: unknown,
-  status: GitHubCheckRunWriteInput["status"],
-): boolean {
-  if (!(error instanceof GitHubApiError)) {
-    return false;
-  }
-  if (error.status === 404) {
-    return true;
-  }
-  return error.status === 422 && status === "in_progress";
-}
-
-function checkRunPhaseFields(
-  phase: GitHubProgressPhase,
-  failureConclusion: "failure" | "neutral" = "failure",
-): Pick<GitHubCheckRunWriteInput, "conclusion" | "status"> {
-  if (phase === "pending") {
-    return { status: "in_progress" };
-  }
-  return {
-    status: "completed",
-    conclusion: phase === "success" ? "success" : failureConclusion,
-  };
-}
-
-async function upsertBanner(input: {
-  phase: GitHubProgressPhase;
-  channel: { state: GitHubChannelState };
-  options: GitHubProgressOptions;
-  banner: GitHubBannerProgress;
-  context?: string;
-}): Promise<void> {
-  const state = input.channel.state;
-  const issueNumber = state.issueNumber ?? state.pullRequestNumber;
-  if (state.owner === "" || state.repo === "" || issueNumber === null) {
-    return;
-  }
-  const body = formatGitHubOutboundComment(
-    progressPhaseCopy({
-      copy: input.banner,
-      phase: input.phase,
-      label: progressLabel(input.options, input.context),
-    }),
-  );
-  const resource = {
-    api: input.options.api,
-    credentials: input.options.credentials,
-    installationId: state.installationId ?? undefined,
-    owner: state.owner,
-    repo: state.repo,
-  };
-  try {
-    if (state.progressBannerCommentId !== null) {
-      try {
-        await updateGitHubIssueComment({
-          ...resource,
-          body,
-          commentId: state.progressBannerCommentId,
-        });
-        return;
-      } catch (error) {
-        if (!(error instanceof GitHubApiError) || error.status !== 404) {
-          return;
-        }
-        // Comment gone; clear sticky id and recreate below.
-        state.progressBannerCommentId = null;
-      }
-    }
-    const posted = await createGitHubIssueComment({
-      ...resource,
-      body,
-      issueNumber,
-    });
-    state.progressBannerCommentId = posted.id;
-  } catch {
-    // Soft-fail.
-  }
-}