@cursor/july 0.1.101 → 0.1.103

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/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).
  *

package/src/channels/github/state.ts

@@ -37,6 +37,7 @@ export function emptyGitHubChannelState(
     pullRequestNumber: null,
     repo: "",
     repositoryId: null,
+    repositoryUrl: null,
     reviewCommentId: null,
     reviewThreadRootCommentId: null,
     triggeringCommentId: null,
@@ -60,6 +61,8 @@ export function githubBindingStateForEvent(input: {
   repo: string;
   number: number;
   repositoryId?: number;
+  /** `repository.html_url` (GHES host lives here). */
+  repositoryUrl?: string;
   installationId?: number;
   triggeringCommentId?: number;
   reviewCommentId?: number;
@@ -74,6 +77,7 @@ export function githubBindingStateForEvent(input: {
       pullRequestNumber: null,
       repo: input.repo,
       repositoryId: input.repositoryId ?? null,
+      repositoryUrl: input.repositoryUrl ?? null,
       reviewCommentId: null,
       reviewThreadRootCommentId: null,
       triggeringCommentId: input.triggeringCommentId ?? null,
@@ -88,6 +92,7 @@ export function githubBindingStateForEvent(input: {
       pullRequestNumber: input.number,
       repo: input.repo,
       repositoryId: input.repositoryId ?? null,
+      repositoryUrl: input.repositoryUrl ?? null,
       reviewCommentId: input.reviewCommentId ?? null,
       reviewThreadRootCommentId:
         input.reviewThreadRootCommentId ??
@@ -105,6 +110,7 @@ export function githubBindingStateForEvent(input: {
     pullRequestNumber: input.number,
     repo: input.repo,
     repositoryId: input.repositoryId ?? null,
+    repositoryUrl: input.repositoryUrl ?? null,
     reviewCommentId: null,
     reviewThreadRootCommentId: null,
     triggeringCommentId: input.triggeringCommentId ?? null,

package/src/channels/github/types.ts

@@ -1,4 +1,4 @@
-import type { ContinuationIdentity } from "../../continuation.js";
+import type { ContinuationIdentity } from "../../internal/continuation-identity.js";
 import type {
   AgentCloudOptions,
   ArtifactsApi,
@@ -61,9 +61,6 @@ export interface GitHubChannelCredentials {
   privateKey?: GitHubCredentialValue;
 }
 
-/** @deprecated Prefer {@link GitHubChannelCredentials}. */
-export type GitHubCredentials = GitHubChannelCredentials;
-
 export type GitHubPullRequestAction =
   | "opened"
   | "reopened"
@@ -525,7 +522,7 @@ export interface GitHubChannelOptions {
   /** Route path under `/v1/channels/<name>`. Defaults to `/`. */
   path?: string;
   /**
-   * Webhook events advertised to `agent-serve github forward` (published as
+   * Webhook events advertised to `agent-sdk 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`.