@cursor/july 0.1.102 → 0.1.104

package/src/channels/github/github-channel.ts

@@ -7,11 +7,19 @@ import {
   loopbackGitHubDev,
   POST,
 } from "../../channels.js";
+import {
+  acknowledgeTask,
+  acknowledgeTurn,
+  isTaskDispatch,
+  scheduleAfterAck,
+  skipped,
+  turnStarted,
+  withPropagatingBackgroundErrors,
+} from "../../internal/channel-dispatch.js";
 import {
   continuationSource,
   normalizeIdentity,
 } from "../../internal/continuation-identity.js";
-import { isDeferredChannelSession } from "../../internal/deferred-channel-session.js";
 import { isDevMode } from "../../internal/dev-mode.js";
 import { attachHostedAdmissionAdapter } from "../../internal/hosted-admission-adapter.js";
 import { bindLocalIngressSend } from "../../internal/local-ingress.js";
@@ -55,7 +63,6 @@ import type {
   GitHubComment,
   GitHubConversationKind,
   GitHubCredentialValue,
-  GitHubDispatch,
   GitHubEventContext,
   GitHubIssueEvent,
   GitHubPullRequestAction,
@@ -64,7 +71,6 @@ import type {
   GitHubRawEvent,
   GitHubRepositoryRef,
   GitHubStatusEvent,
-  GitHubTaskDispatch,
   GitHubTurnDispatch,
   GitHubUser,
   GitHubWorkflowRunEvent,
@@ -227,24 +233,10 @@ export function parseGitHubPrContinuationKey(
   };
 }
 
-/** @deprecated Prefer {@link githubContinuationKey}. */
-export function githubPullRequestContinuationKey(
-  ctx: GitHubParsedContext
-): string {
-  return githubContinuationKey(ctx);
-}
-
 export function defaultGitHubTitle(ctx: GitHubParsedContext): string {
   return `GitHub ${ctx.repository.fullName}#${ctx.conversation.number}`;
 }
 
-/** @deprecated Prefer {@link defaultGitHubTitle}. */
-export function defaultGitHubPullRequestTitle(
-  ctx: GitHubParsedContext
-): string {
-  return defaultGitHubTitle(ctx);
-}
-
 export function defaultGitHubPullRequestMessage(
   ctx: GitHubParsedContext,
   pullRequest: GitHubPullRequestEvent
@@ -303,12 +295,6 @@ export function defaultOnComment(
   return { auth: defaultGitHubAuth(ctx) };
 }
 
-function isTaskDispatch(
-  dispatch: GitHubDispatch
-): dispatch is GitHubTaskDispatch {
-  return "task" in dispatch;
-}
-
 export function shouldDispatchGitHubComment(args: {
   body: string;
   author?: GitHubUser;
@@ -439,98 +425,17 @@ function verifyWebhookSha256Signature(args: {
 }
 
 /**
- * GitHub webhook channel (Eve-compatible dispatch surface). Point a GitHub App
- * or repository webhook at `/<agent>/v1/channels/github` and declare inbound
- * hooks:
- *
- * ```ts
- * import { defaultGitHubAuth, githubChannel } from "@cursor/july/channels/github";
- *
- * export default githubChannel({
- *   botName: "my-agent",
- *   credentials: { webhookSecret: () => process.env.GITHUB_WEBHOOK_SECRET },
- *   // Replaces the @mention gate. Prefer typed Octokit via getOctokit().
- *   onComment: (ctx, comment) => ({ auth: defaultGitHubAuth(ctx) }),
- *   onPullRequest: (ctx, pr) =>
- *     pr.action === "opened" ? { auth: defaultGitHubAuth(ctx) } : null,
- *   onStatus: (ctx, status) =>
- *     status.state === "failure"
- *       ? {
- *           task: async () => {
- *             const octokit = await ctx.github.getOctokit();
- *             await octokit.rest.repos.createCommitStatus({
- *               owner: ctx.repository.owner,
- *               repo: ctx.repository.name,
- *               sha: status.sha,
- *               state: "pending",
- *               context: "agent/triage",
- *             });
- *           },
- *         }
- *       : null,
- *   onEvent: (ctx, event) =>
- *     event.eventName === "label" ? { auth: defaultGitHubAuth(ctx) } : null,
- * });
- * ```
- */
-/**
- * Core GitHub webhook dispatch used by {@link githubChannel} routes and by
- * {@link handleAgentServeTrigger} fan-out. Signature verification is the
- * caller's responsibility (HTTP route verifies; internal fan-out skips).
- */
-/**
- * Run authored GitHub hooks and `send()`. Does not extract a v2 mailbox —
- * the local CP (or hosted verified ingress) stamps before this runs.
+ * Run the authored hooks for one GitHub delivery and `send()` the turn.
+ * Callers own delivery auth: the HTTP route verifies the HMAC; trigger
+ * fan-out and hosted admission arrive verified. The v2 mailbox is stamped
+ * upstream (local CP or hosted ingress), never here.
  */
-export type GitHubDispatchOutcome = "skip" | "send" | "task";
-
-const dispatchOutcomeByResponse = new WeakMap<
-  Response,
-  GitHubDispatchOutcome
->();
-
-function withDispatchOutcome(
-  response: Response,
-  outcome: GitHubDispatchOutcome
-): Response {
-  dispatchOutcomeByResponse.set(response, outcome);
-  return response;
-}
-
-export function getGitHubDispatchOutcome(
-  response: Response
-): GitHubDispatchOutcome | undefined {
-  return dispatchOutcomeByResponse.get(response);
-}
-
-const PROPAGATE_BACKGROUND_ERRORS = Symbol("propagateBackgroundErrors");
-
-type GitHubHandlerArgs = ChannelHandlerArgs & {
-  [PROPAGATE_BACKGROUND_ERRORS]?: true;
-};
-
-export function withPropagatingGitHubBackgroundErrors(
-  args: ChannelHandlerArgs
-): ChannelHandlerArgs {
-  return Object.assign(args, { [PROPAGATE_BACKGROUND_ERRORS]: true as const });
-}
-
 export async function dispatchGitHubWebhook(input: {
   options: GitHubChannelOptions;
   eventName: string | null;
   payload: unknown;
   deliveryId?: string;
   args: ChannelHandlerArgs;
-}): Promise<Response> {
-  return dispatchGitHubWebhookInner(input);
-}
-
-async function dispatchGitHubWebhookInner(input: {
-  options: GitHubChannelOptions;
-  eventName: string | null;
-  payload: unknown;
-  deliveryId?: string;
-  args: ChannelHandlerArgs;
 }): Promise<Response> {
   const { options, eventName, payload, deliveryId, args } = input;
   const botName = options.botName ?? process.env.GITHUB_APP_SLUG;
@@ -621,12 +526,7 @@ async function dispatchGitHubWebhookInner(input: {
           args,
         });
       }
-      return Response.json({
-        ok: true,
-        skipped: true,
-        reason: "unsupported_event",
-        event: eventName,
-      });
+      return skipped("unsupported_event", { event: eventName });
   }
 }
 
@@ -701,6 +601,41 @@ export function getGitHubChannelOptions(
   return githubChannelOptionsByDefinition.get(definition);
 }
 
+/**
+ * GitHub webhook channel (Eve-compatible dispatch surface). Point a GitHub App
+ * or repository webhook at `/<agent>/v1/channels/github` and declare inbound
+ * hooks:
+ *
+ * ```ts
+ * import { defaultGitHubAuth, githubChannel } from "@cursor/july/channels/github";
+ *
+ * export default githubChannel({
+ *   botName: "my-agent",
+ *   credentials: { webhookSecret: () => process.env.GITHUB_WEBHOOK_SECRET },
+ *   // Replaces the @mention gate. Prefer typed Octokit via getOctokit().
+ *   onComment: (ctx, comment) => ({ auth: defaultGitHubAuth(ctx) }),
+ *   onPullRequest: (ctx, pr) =>
+ *     pr.action === "opened" ? { auth: defaultGitHubAuth(ctx) } : null,
+ *   onStatus: (ctx, status) =>
+ *     status.state === "failure"
+ *       ? {
+ *           task: async () => {
+ *             const octokit = await ctx.github.getOctokit();
+ *             await octokit.rest.repos.createCommitStatus({
+ *               owner: ctx.repository.owner,
+ *               repo: ctx.repository.name,
+ *               sha: status.sha,
+ *               state: "pending",
+ *               context: "agent/triage",
+ *             });
+ *           },
+ *         }
+ *       : null,
+ *   onEvent: (ctx, event) =>
+ *     event.eventName === "label" ? { auth: defaultGitHubAuth(ctx) } : null,
+ * });
+ * ```
+ */
 export function githubChannel(
   options: GitHubChannelOptions = {}
 ): ChannelDefinition<GitHubChannelState> {
@@ -807,7 +742,7 @@ export function githubChannel(
   githubChannelOptionsByDefinition.set(definition, channelOptions);
   attachHostedAdmissionAdapter(definition, {
     kind: GITHUB_CHANNEL_KIND,
-    prepareArgs: withPropagatingGitHubBackgroundErrors,
+    prepareArgs: withPropagatingBackgroundErrors,
     dispatch: ({ eventType, payload, deliveryId, args }) =>
       dispatchGitHubWebhook({
         options: channelOptions,
@@ -816,10 +751,6 @@ export function githubChannel(
         deliveryId,
         args,
       }),
-    getOutcome: (response) => {
-      const outcome = getGitHubDispatchOutcome(response);
-      return outcome === "skip" || outcome === "task" ? outcome : undefined;
-    },
   });
   if (cursorCredentials !== undefined) {
     registerGithubCursorAccountRuntime(definition, {
@@ -868,6 +799,7 @@ async function handlePullRequest(input: {
     repo: parsed.ctx.repository.name,
     number: parsed.ctx.conversation.number,
     repositoryId: parsed.ctx.repository.id,
+    repositoryUrl: parsed.ctx.repository.url,
     installationId,
   });
   const ctx = enrichEventContext({
@@ -888,7 +820,7 @@ async function handlePullRequest(input: {
   }
 
   if (isTaskDispatch(dispatch)) {
-    return acknowledgeTask(input.args, dispatch, {
+    return acknowledgeTask(input.args, GITHUB_CHANNEL_KIND, dispatch, {
       action: pullRequest.action,
       prUrl: pullRequest.url,
       headSha: pullRequest.headSha,
@@ -961,6 +893,7 @@ async function handleIssueComment(input: {
     repo: parsed.ctx.repository.name,
     number: parsed.ctx.conversation.number,
     repositoryId: parsed.ctx.repository.id,
+    repositoryUrl: parsed.ctx.repository.url,
     installationId,
     triggeringCommentId: parsed.comment.id,
   });
@@ -984,7 +917,7 @@ async function handleIssueComment(input: {
     return skipped("not_dispatched");
   }
   if (isTaskDispatch(dispatch)) {
-    return acknowledgeTask(input.args, dispatch, {
+    return acknowledgeTask(input.args, GITHUB_CHANNEL_KIND, dispatch, {
       event: "issue_comment",
       action: parsed.action,
     });
@@ -1052,6 +985,7 @@ async function handleReviewComment(input: {
     repo: parsed.ctx.repository.name,
     number: parsed.ctx.conversation.number,
     repositoryId: parsed.ctx.repository.id,
+    repositoryUrl: parsed.ctx.repository.url,
     installationId,
     triggeringCommentId: parsed.comment.id,
     reviewCommentId: parsed.comment.id,
@@ -1077,7 +1011,7 @@ async function handleReviewComment(input: {
     return skipped("not_dispatched");
   }
   if (isTaskDispatch(dispatch)) {
-    return acknowledgeTask(input.args, dispatch, {
+    return acknowledgeTask(input.args, GITHUB_CHANNEL_KIND, dispatch, {
       event: "pull_request_review_comment",
       action: parsed.action,
     });
@@ -1137,6 +1071,7 @@ async function handleIssue(input: {
     repo: parsed.ctx.repository.name,
     number: parsed.ctx.conversation.number,
     repositoryId: parsed.ctx.repository.id,
+    repositoryUrl: parsed.ctx.repository.url,
     installationId,
   });
   const ctx = enrichEventContext({
@@ -1153,7 +1088,7 @@ async function handleIssue(input: {
     return skipped("not_dispatched", { action: parsed.issue.action });
   }
   if (isTaskDispatch(dispatch)) {
-    return acknowledgeTask(input.args, dispatch, {
+    return acknowledgeTask(input.args, GITHUB_CHANNEL_KIND, dispatch, {
       event: "issues",
       action: parsed.issue.action,
       issueNumber: parsed.issue.number,
@@ -1213,7 +1148,7 @@ async function handleCheckSuite(input: {
       parsed.checkSuite
     );
     if (dispatch !== null && isTaskDispatch(dispatch)) {
-      return acknowledgeTask(input.args, dispatch, {
+      return acknowledgeTask(input.args, GITHUB_CHANNEL_KIND, dispatch, {
         event: "check_suite",
         action: parsed.checkSuite.action,
         checkSuiteId: parsed.checkSuite.checkSuiteId,
@@ -1227,6 +1162,7 @@ async function handleCheckSuite(input: {
     repo: parsed.ctx.repository.name,
     number: parsed.ctx.conversation.number,
     repositoryId: parsed.ctx.repository.id,
+    repositoryUrl: parsed.ctx.repository.url,
     installationId,
   });
   const ctx = enrichEventContext({
@@ -1243,7 +1179,7 @@ async function handleCheckSuite(input: {
     return skipped("not_dispatched", { action: parsed.checkSuite.action });
   }
   if (isTaskDispatch(dispatch)) {
-    return acknowledgeTask(input.args, dispatch, {
+    return acknowledgeTask(input.args, GITHUB_CHANNEL_KIND, dispatch, {
       event: "check_suite",
       action: parsed.checkSuite.action,
       checkSuiteId: parsed.checkSuite.checkSuiteId,
@@ -1308,7 +1244,7 @@ async function handleCheckRun(input: {
       parsed.checkRun
     );
     if (dispatch !== null && isTaskDispatch(dispatch)) {
-      return acknowledgeTask(input.args, dispatch, {
+      return acknowledgeTask(input.args, GITHUB_CHANNEL_KIND, dispatch, {
         event: "check_run",
         action: parsed.checkRun.action,
         checkRunId: parsed.checkRun.checkRunId,
@@ -1322,6 +1258,7 @@ async function handleCheckRun(input: {
     repo: parsed.ctx.repository.name,
     number: parsed.ctx.conversation.number,
     repositoryId: parsed.ctx.repository.id,
+    repositoryUrl: parsed.ctx.repository.url,
     installationId,
   });
   const ctx = enrichEventContext({
@@ -1338,7 +1275,7 @@ async function handleCheckRun(input: {
     return skipped("not_dispatched", { action: parsed.checkRun.action });
   }
   if (isTaskDispatch(dispatch)) {
-    return acknowledgeTask(input.args, dispatch, {
+    return acknowledgeTask(input.args, GITHUB_CHANNEL_KIND, dispatch, {
       event: "check_run",
       action: parsed.checkRun.action,
       checkRunId: parsed.checkRun.checkRunId,
@@ -1399,7 +1336,7 @@ async function handleWorkflowRun(input: {
       parsed.workflowRun
     );
     if (dispatch !== null && isTaskDispatch(dispatch)) {
-      return acknowledgeTask(input.args, dispatch, {
+      return acknowledgeTask(input.args, GITHUB_CHANNEL_KIND, dispatch, {
         event: "workflow_run",
         action: parsed.workflowRun.action,
         workflowRunId: parsed.workflowRun.workflowRunId,
@@ -1413,6 +1350,7 @@ async function handleWorkflowRun(input: {
     repo: parsed.ctx.repository.name,
     number: parsed.ctx.conversation.number,
     repositoryId: parsed.ctx.repository.id,
+    repositoryUrl: parsed.ctx.repository.url,
     installationId,
   });
   const ctx = enrichEventContext({
@@ -1429,7 +1367,7 @@ async function handleWorkflowRun(input: {
     return skipped("not_dispatched", { action: parsed.workflowRun.action });
   }
   if (isTaskDispatch(dispatch)) {
-    return acknowledgeTask(input.args, dispatch, {
+    return acknowledgeTask(input.args, GITHUB_CHANNEL_KIND, dispatch, {
       event: "workflow_run",
       action: parsed.workflowRun.action,
       workflowRunId: parsed.workflowRun.workflowRunId,
@@ -1487,6 +1425,7 @@ async function handleStatus(input: {
     repo: parsed.ctx.repository.name,
     number: parsed.ctx.conversation.number,
     repositoryId: parsed.ctx.repository.id,
+    repositoryUrl: parsed.ctx.repository.url,
     installationId,
   });
   const ctx = enrichEventContext({
@@ -1506,7 +1445,7 @@ async function handleStatus(input: {
     });
   }
   if (isTaskDispatch(dispatch)) {
-    return acknowledgeTask(input.args, dispatch, {
+    return acknowledgeTask(input.args, GITHUB_CHANNEL_KIND, dispatch, {
       event: "status",
       state: parsed.status.state,
       sha: parsed.status.sha,
@@ -1563,6 +1502,7 @@ async function handleGenericEvent(input: {
     repo: parsed.ctx.repository.name,
     number: parsed.ctx.conversation.number,
     repositoryId: parsed.ctx.repository.id,
+    repositoryUrl: parsed.ctx.repository.url,
     installationId,
   });
   const ctx = enrichEventContext({
@@ -1579,7 +1519,7 @@ async function handleGenericEvent(input: {
     return skipped("not_dispatched", { event: input.eventName });
   }
   if (isTaskDispatch(dispatch)) {
-    return acknowledgeTask(input.args, dispatch, {
+    return acknowledgeTask(input.args, GITHUB_CHANNEL_KIND, dispatch, {
       event: input.eventName,
       ...(parsed.event.action === undefined
         ? {}
@@ -1637,101 +1577,13 @@ async function startTurn(input: {
   };
 
   if (lazy) {
-    scheduleAfterAck(input.args, async () => {
+    scheduleAfterAck(input.args, GITHUB_CHANNEL_KIND, async () => {
       await sendTurn();
     });
     return acknowledgeTurn();
   }
 
-  const session = await sendTurn();
-  if (isDeferredChannelSession(session)) {
-    // Hosted admission captured the send; the control plane allocates the
-    // session after acknowledgement, so there is nothing to report yet.
-    return acknowledgeTurn();
-  }
-  return withDispatchOutcome(
-    Response.json({
-      ok: true,
-      sessionId: session.id,
-      isNew: session.isNew,
-      continuationToken: session.continuationToken,
-    }),
-    "send"
-  );
-}
-
-function scheduleAfterAck(
-  args: ChannelHandlerArgs,
-  work: () => void | Promise<void>
-): void {
-  // Defer past the current turn so the 202 can flush before work starts
-  // (and so tests can assert scheduling without racing microtasks).
-  args.waitUntil(
-    new Promise<void>((resolve, reject) => {
-      setImmediate(() => {
-        Promise.resolve()
-          .then(work)
-          .then(
-            () => resolve(),
-            (error: unknown) => {
-              if (
-                (args as GitHubHandlerArgs)[PROPAGATE_BACKGROUND_ERRORS] ===
-                true
-              ) {
-                reject(error);
-                return;
-              }
-              const detail =
-                error instanceof Error
-                  ? (error.stack ?? error.message)
-                  : String(error);
-              console.error(`[github] background dispatch failed: ${detail}`);
-              resolve();
-            }
-          );
-      });
-    })
-  );
-}
-
-/** 202 ack for a turn whose send completes after the response flushes. */
-function acknowledgeTurn(): Response {
-  return withDispatchOutcome(
-    Response.json(
-      { ok: true, dispatched: true, mode: "turn" },
-      { status: 202 }
-    ),
-    "send"
-  );
-}
-
-function acknowledgeTask(
-  args: ChannelHandlerArgs,
-  dispatch: GitHubTaskDispatch,
-  extra: Record<string, unknown>
-): Response {
-  // Hand the task the per-delivery send/waitUntil so hosted admission can
-  // capture task-initiated sends; startup-captured sends bypass capture.
-  scheduleAfterAck(args, () =>
-    dispatch.task({ send: args.send, waitUntil: args.waitUntil })
-  );
-  return withDispatchOutcome(
-    Response.json(
-      { ok: true, dispatched: true, mode: "task", ...extra },
-      { status: 202 }
-    ),
-    "task"
-  );
-}
-
-function skipped(
-  reason: string,
-  extra: Record<string, unknown> = {}
-): Response {
-  return withDispatchOutcome(
-    Response.json({ ok: true, skipped: true, reason, ...extra }),
-    "skip"
-  );
+  return turnStarted(await sendTurn());
 }
 
 function formatCiMessage(
@@ -2538,6 +2390,7 @@ function enrichCiContext(input: {
     repo: input.ctx.repository.name,
     number: input.ctx.conversation.number,
     repositoryId: input.ctx.repository.id,
+    repositoryUrl: input.ctx.repository.url,
     installationId: input.installationId,
   });
   return enrichEventContext({

package/src/channels/github/progress.ts

@@ -28,6 +28,27 @@ export interface GitHubProgressPhaseCopy {
 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;
@@ -125,6 +146,7 @@ function progressLabel(
  */
 export async function applyGitHubProgress(input: {
   phase: GitHubProgressPhase;
+  sessionId?: string;
   channel: { state: GitHubChannelState };
   options: GitHubProgressOptions;
 }): Promise<void> {
@@ -139,6 +161,7 @@ export async function applyGitHubProgress(input: {
     tasks.push(
       postProgressCheckRun({
         phase: input.phase,
+        sessionId: input.sessionId,
         channel: input.channel,
         options: input.options,
         commitStatus,
@@ -159,8 +182,35 @@ export async function applyGitHubProgress(input: {
   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;
@@ -175,17 +225,32 @@ async function postProgressCheckRun(input: {
     return;
   }
   const sha = state.headSha;
-  const description = clipStatusDescription(
-    progressPhaseCopy({
-      copy: input.commitStatus,
-      phase: input.phase,
-      label: progressLabel(input.options, input.commitStatus.context),
-    })
+  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),
-    output: { title: description, summary: description },
+    ...checkRunPhaseFields(input.phase, input.commitStatus.failureConclusion),
+    ...(detailsUrl === undefined ? {} : { detailsUrl }),
+    output: {
+      title,
+      summary: appendSummaryLink(
+        phaseCopy,
+        detailsUrl,
+        input.commitStatus.summaryLinkText
+      ),
+    },
   };
   const resource = {
     api: input.options.api,
@@ -249,14 +314,15 @@ function shouldRecreateCheckRun(
 }
 
 function checkRunPhaseFields(
-  phase: GitHubProgressPhase
+  phase: GitHubProgressPhase,
+  failureConclusion: "failure" | "neutral" = "failure"
 ): Pick<GitHubCheckRunWriteInput, "conclusion" | "status"> {
   if (phase === "pending") {
     return { status: "in_progress" };
   }
   return {
     status: "completed",
-    conclusion: phase === "success" ? "success" : "failure",
+    conclusion: phase === "success" ? "success" : failureConclusion,
   };
 }
 

package/src/channels/github/replay.ts

@@ -1,6 +1,6 @@
 /**
  * Synthesize GitHub webhook payloads from data you can *read* about a PR, so
- * `agent-serve github replay` can exercise a `githubChannel()` without repo
+ * `agent-sdk github replay` can exercise a `githubChannel()` without repo
  * admin, without the `gh webhook forward` relay, and deterministically (great
  * for hillclimbing).
  *