@cursor/july 0.1.55 → 0.1.62

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

@@ -70,7 +70,7 @@ import type {
  */
 type GitHubParsedContext = Omit<
   GitHubEventContext,
-  "github" | "thread" | "host" | "artifacts"
+  "github" | "thread" | "host" | "artifacts" | "payload"
 >;
 
 const DEFAULT_PULL_REQUEST_ACTIONS: ReadonlySet<string> = new Set([
@@ -136,6 +136,16 @@ const githubPullRequestPayloadSchema: z.ZodType<GitHubPullRequestPayload> =
         sha: z.string().optional(),
       }),
     }),
+    changes: z
+      .object({
+        base: z
+          .object({
+            ref: z.object({ from: z.string().min(1).optional() }).optional(),
+          })
+          .optional(),
+      })
+      .nullable()
+      .optional(),
     sender: senderSchema,
     installation: installationSchema,
     label: z
@@ -184,6 +194,32 @@ export function githubContinuationKey(ctx: GitHubParsedContext): string {
   return `${kind}:${ctx.repository.fullName}#${ctx.conversation.number}`;
 }
 
+export interface GitHubPullRequestRef {
+  owner: string;
+  repo: string;
+  number: number;
+}
+
+/**
+ * Parse a pull-request continuation key minted by
+ * {@link githubContinuationKey} back into its repo + number. Undefined for
+ * issue keys and non-GitHub sessions — lets a server tool recover which PR
+ * its session is pinned to without trusting model-provided identifiers.
+ */
+export function parseGitHubPrContinuationKey(
+  key: string
+): GitHubPullRequestRef | undefined {
+  const match = /^github-pr:([^/#\s]+)\/([^#\s]+)#(\d+)$/.exec(key);
+  if (match === null) {
+    return undefined;
+  }
+  return {
+    owner: match[1]!,
+    repo: match[2]!,
+    number: Number(match[3]!),
+  };
+}
+
 /** @deprecated Prefer {@link githubContinuationKey}. */
 export function githubPullRequestContinuationKey(
   ctx: GitHubParsedContext
@@ -338,6 +374,9 @@ export function parseGitHubPullRequestEvent(args: {
     ...(payload.pull_request.base.sha === undefined
       ? {}
       : { baseSha: payload.pull_request.base.sha }),
+    ...(payload.changes?.base?.ref?.from === undefined
+      ? {}
+      : { baseRefChangedFrom: payload.changes.base.ref.from }),
     draft: payload.pull_request.draft ?? false,
     merged: payload.pull_request.merged === true,
     ...(payload.pull_request.user?.login === undefined
@@ -748,6 +787,7 @@ async function handlePullRequest(input: {
   const ctx = enrichEventContext({
     bindingConfig: input.bindingConfig,
     ctx: parsed.ctx,
+    payload: input.payload,
     bindingState: binding,
     installationId,
     host: input.args.host,
@@ -840,6 +880,7 @@ async function handleIssueComment(input: {
   const ctx = enrichEventContext({
     bindingConfig: input.bindingConfig,
     ctx: parsed.ctx,
+    payload: input.payload,
     bindingState: binding,
     installationId,
     host: input.args.host,
@@ -931,6 +972,7 @@ async function handleReviewComment(input: {
   const ctx = enrichEventContext({
     bindingConfig: input.bindingConfig,
     ctx: parsed.ctx,
+    payload: input.payload,
     bindingState: binding,
     installationId,
     host: input.args.host,
@@ -1011,6 +1053,7 @@ async function handleIssue(input: {
   const ctx = enrichEventContext({
     bindingConfig: input.bindingConfig,
     ctx: parsed.ctx,
+    payload: input.payload,
     bindingState: binding,
     installationId,
     host: input.args.host,
@@ -1072,6 +1115,7 @@ async function handleCheckSuite(input: {
       enrichCiContext({
         bindingConfig: input.bindingConfig,
         ctx: parsed.unanchoredCtx,
+        payload: input.payload,
         installationId,
         host: input.args.host,
         artifacts: input.args.artifacts,
@@ -1098,6 +1142,7 @@ async function handleCheckSuite(input: {
   const ctx = enrichEventContext({
     bindingConfig: input.bindingConfig,
     ctx: parsed.ctx,
+    payload: input.payload,
     bindingState: binding,
     installationId,
     host: input.args.host,
@@ -1164,6 +1209,7 @@ async function handleCheckRun(input: {
       enrichCiContext({
         bindingConfig: input.bindingConfig,
         ctx: parsed.unanchoredCtx,
+        payload: input.payload,
         installationId,
         host: input.args.host,
         artifacts: input.args.artifacts,
@@ -1190,6 +1236,7 @@ async function handleCheckRun(input: {
   const ctx = enrichEventContext({
     bindingConfig: input.bindingConfig,
     ctx: parsed.ctx,
+    payload: input.payload,
     bindingState: binding,
     installationId,
     host: input.args.host,
@@ -1252,6 +1299,7 @@ async function handleWorkflowRun(input: {
       enrichCiContext({
         bindingConfig: input.bindingConfig,
         ctx: parsed.unanchoredCtx,
+        payload: input.payload,
         installationId,
         host: input.args.host,
         artifacts: input.args.artifacts,
@@ -1278,6 +1326,7 @@ async function handleWorkflowRun(input: {
   const ctx = enrichEventContext({
     bindingConfig: input.bindingConfig,
     ctx: parsed.ctx,
+    payload: input.payload,
     bindingState: binding,
     installationId,
     host: input.args.host,
@@ -1350,6 +1399,7 @@ async function handleStatus(input: {
   const ctx = enrichEventContext({
     bindingConfig: input.bindingConfig,
     ctx: parsed.ctx,
+    payload: input.payload,
     bindingState: binding,
     installationId,
     host: input.args.host,
@@ -1424,6 +1474,7 @@ async function handleGenericEvent(input: {
   const ctx = enrichEventContext({
     bindingConfig: input.bindingConfig,
     ctx: parsed.ctx,
+    payload: input.payload,
     bindingState: binding,
     installationId,
     host: input.args.host,
@@ -1469,15 +1520,34 @@ async function startTurn(input: {
   cloud?: AgentCloudOptions;
   state: GitHubChannelState;
 }): Promise<Response> {
-  const session = await input.args.send(input.message, {
-    auth: input.dispatch.auth,
-    continuationToken: githubContinuationKey(input.ctx),
-    title: input.dispatch.title ?? defaultGitHubTitle(input.ctx),
-    ...(input.cloud === undefined ? {} : { cloud: input.cloud }),
-    state: input.state as unknown as JsonValue,
-    // Resume must refresh headSha / refs without wiping sticky banner id.
-    refreshState: input.state as unknown as JsonValue,
-  });
+  const files = input.dispatch.workspaceFiles;
+  const lazy = typeof files === "function";
+
+  const sendTurn = async () => {
+    const workspaceFiles = lazy ? await files() : files;
+    return input.args.send(input.message, {
+      auth: input.dispatch.auth,
+      continuationToken: githubContinuationKey(input.ctx),
+      title: input.dispatch.title ?? defaultGitHubTitle(input.ctx),
+      ...(input.cloud === undefined ? {} : { cloud: input.cloud }),
+      ...(workspaceFiles === undefined ? {} : { workspaceFiles }),
+      state: input.state as unknown as JsonValue,
+      // Resume must refresh headSha / refs without wiping sticky banner id.
+      refreshState: input.state as unknown as JsonValue,
+    });
+  };
+
+  if (lazy) {
+    scheduleAfterAck(input.args, async () => {
+      await sendTurn();
+    });
+    return Response.json(
+      { ok: true, dispatched: true, mode: "turn" },
+      { status: 202 }
+    );
+  }
+
+  const session = await sendTurn();
   return Response.json({
     ok: true,
     sessionId: session.id,
@@ -1486,22 +1556,41 @@ async function startTurn(input: {
   });
 }
 
-function acknowledgeTask(
+function reportBackgroundFailure(error: unknown): void {
+  const detail =
+    error instanceof Error ? (error.stack ?? error.message) : String(error);
+  console.error(`[github] background dispatch failed: ${detail}`);
+}
+
+function scheduleAfterAck(
   args: ChannelHandlerArgs,
-  dispatch: GitHubTaskDispatch,
-  extra: Record<string, unknown>
-): Response {
-  // Defer the task past the current turn so the 202 can flush before work
-  // starts (and so tests can assert scheduling without racing microtasks).
+  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) => {
+    new Promise<void>((resolve) => {
       setImmediate(() => {
         Promise.resolve()
-          .then(dispatch.task)
-          .then(() => resolve(), reject);
+          .then(work)
+          .then(
+            () => resolve(),
+            (error: unknown) => {
+              reportBackgroundFailure(error);
+              resolve();
+            }
+          );
       });
     })
   );
+}
+
+function acknowledgeTask(
+  args: ChannelHandlerArgs,
+  dispatch: GitHubTaskDispatch,
+  extra: Record<string, unknown>
+): Response {
+  scheduleAfterAck(args, dispatch.task);
   return Response.json(
     { ok: true, dispatched: true, mode: "task", ...extra },
     { status: 202 }
@@ -2276,10 +2365,11 @@ function escapeRegExp(value: string): string {
  */
 function enrichEventContext(input: {
   bindingConfig: GitHubBindingConfig;
-  ctx: Omit<GitHubEventContext, "github" | "thread" | "host" | "artifacts"> &
+  ctx: GitHubParsedContext &
     Partial<Pick<GitHubEventContext, "github" | "thread">>;
   bindingState: GitHubBindingState;
   installationId?: number;
+  payload: unknown;
   host: HostContext;
   artifacts: ArtifactsApi;
 }): GitHubEventContext {
@@ -2289,6 +2379,7 @@ function enrichEventContext(input: {
   });
   return {
     ...input.ctx,
+    payload: input.payload,
     ...(input.installationId === undefined
       ? {}
       : { installationId: input.installationId }),
@@ -2307,6 +2398,7 @@ function enrichCiContext(input: {
   bindingConfig: GitHubBindingConfig;
   ctx: GitHubParsedContext;
   installationId?: number;
+  payload: unknown;
   host: HostContext;
   artifacts: ArtifactsApi;
 }): GitHubEventContext {
@@ -2323,6 +2415,7 @@ function enrichCiContext(input: {
     ctx: input.ctx,
     bindingState: binding,
     installationId: input.installationId,
+    payload: input.payload,
     host: input.host,
     artifacts: input.artifacts,
   });

package/src/channels/github/types.ts

@@ -6,6 +6,7 @@ import type {
   ChannelEventHandlers,
   ChannelStartArgs,
   HostContext,
+  SendMessageOptions,
 } from "../../types.js";
 import type { GitHubApiOptions } from "./api.js";
 import type { GitHubHandle, GitHubThread } from "./binding.js";
@@ -165,6 +166,13 @@ export type GitHubPullRequestPayload = {
       sha?: string;
     };
   };
+  /**
+   * Present on `edited` deliveries; `changes.base.ref.from` carries the
+   * previous base branch when the PR was retargeted.
+   */
+  changes?: {
+    base?: { ref?: { from?: string } };
+  } | null;
   sender?: {
     login?: string;
     id?: number;
@@ -186,6 +194,13 @@ export interface GitHubPullRequestEvent {
   headSha: string;
   baseRef: string;
   baseSha?: string;
+  /**
+   * On `edited` deliveries where the PR base was retargeted, the previous
+   * base branch (`changes.base.ref.from`). Undefined for every other edit
+   * (title / body), so `action === "edited" && baseRefChangedFrom` gates
+   * base-retarget handling without waking on prose edits.
+   */
+  baseRefChangedFrom?: string;
   draft: boolean;
   /** True when the PR was merged (from the webhook payload). */
   merged: boolean;
@@ -305,6 +320,8 @@ export interface GitHubEventContext {
   sender?: GitHubUser;
   /** Installation id from the webhook payload, when present. */
   installationId?: number;
+  /** Verified webhook body for this delivery. */
+  payload: unknown;
   /** Authenticated GitHub helpers (`getOctokit`, `request`, `createStatus`). */
   github: GitHubHandle;
   /** Post / react on the conversation thread. */
@@ -324,6 +341,11 @@ export interface GitHubEventContext {
  */
 export type GitHubDispatch = GitHubTurnDispatch | GitHubTaskDispatch;
 
+/** Files seeded into the session workspace before the turn. */
+export type GitHubWorkspaceFiles = NonNullable<
+  SendMessageOptions["workspaceFiles"]
+>;
+
 /** 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. */
@@ -334,6 +356,17 @@ export interface GitHubTurnDispatch {
   message?: string;
   /** Optional session title override. */
   title?: string;
+  /**
+   * Seeded into the session workspace before the turn (`send`'s
+   * `workspaceFiles`). A function runs after the webhook is
+   * acknowledged (202) so fetch I/O can outlive GitHub's ~10s window.
+   */
+  workspaceFiles?:
+    | GitHubWorkspaceFiles
+    | (() =>
+        | GitHubWorkspaceFiles
+        | undefined
+        | Promise<GitHubWorkspaceFiles | undefined>);
 }
 
 /**

package/src/channels/origin/cursor-account.ts

@@ -0,0 +1,64 @@
+/**
+ * Cursor-account mode for Origin channels.
+ *
+ * Origin identity is the signed-in Cursor user (no third-party OAuth). The
+ * channel declares repos at definition time; the serve host subscribes
+ * `/v0/scm-events` with `provider: "origin"` as that user. Unlike GitHub,
+ * there is no installation token to mint — outbound Origin API calls already
+ * authenticate as the Cursor principal.
+ */
+
+import type { OriginChannelOptions } from "./types.js";
+
+export const CURSOR_ORIGIN_MAX_REPOS = 20;
+const CURSOR_ORIGIN_REPO_PATTERN = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+
+export interface CursorOriginRepoScope {
+  repos: readonly string[];
+}
+
+export interface OriginCursorAccountRuntime {
+  options: OriginChannelOptions;
+  scope: CursorOriginRepoScope | undefined;
+}
+
+const runtimeByDefinition = new WeakMap<object, OriginCursorAccountRuntime>();
+
+export function parseCursorOriginRepoScope(
+  values: readonly string[]
+): CursorOriginRepoScope {
+  const repos = [
+    ...new Set(values.map((repo) => repo.trim().toLowerCase()).filter(Boolean)),
+  ];
+  if (repos.length === 0) {
+    throw new Error(
+      "originChannel({ cursorAccount }) requires at least one repository."
+    );
+  }
+  if (repos.length > CURSOR_ORIGIN_MAX_REPOS) {
+    throw new Error(
+      `originChannel({ cursorAccount }) supports at most ${CURSOR_ORIGIN_MAX_REPOS} repositories.`
+    );
+  }
+  for (const repo of repos) {
+    if (!CURSOR_ORIGIN_REPO_PATTERN.test(repo) || repo.includes("..")) {
+      throw new Error(
+        `Invalid Origin repository "${repo}"; expected owner/repo.`
+      );
+    }
+  }
+  return { repos };
+}
+
+export function registerOriginCursorAccountRuntime(
+  definition: object,
+  runtime: OriginCursorAccountRuntime
+): void {
+  runtimeByDefinition.set(definition, runtime);
+}
+
+export function getOriginCursorAccountRuntime(
+  definition: object
+): OriginCursorAccountRuntime | undefined {
+  return runtimeByDefinition.get(definition);
+}

package/src/channels/origin/events.ts

@@ -0,0 +1,41 @@
+/** {@link ChannelMeta.kind} value used by {@link originChannel}. */
+export const ORIGIN_CHANNEL_KIND = "origin";
+
+const BASE_WEBHOOK_EVENTS: readonly string[] = [
+  "pull_request.created",
+  "pull_request.published",
+  "pull_request.head_ref.pushed",
+  "pull_request.base_ref.updated",
+  "pull_request.closed",
+  "pull_request.merged",
+];
+
+const COMMENT_EVENTS: readonly string[] = ["pull_request.comment.created"];
+const REVIEW_EVENTS: readonly string[] = ["pull_request.review.submitted"];
+
+export interface OriginWebhookEventOptions {
+  webhookEvents?: readonly string[];
+  onComment?: unknown;
+  onReview?: unknown;
+  onEvent?: unknown;
+}
+
+export function deriveOriginWebhookEvents(
+  options: OriginWebhookEventOptions
+): string[] {
+  if (options.webhookEvents !== undefined) {
+    return [
+      ...new Set(
+        options.webhookEvents.map((event) => event.trim()).filter(Boolean)
+      ),
+    ];
+  }
+  const events: string[] = [...BASE_WEBHOOK_EVENTS];
+  if (options.onComment !== undefined) {
+    events.push(...COMMENT_EVENTS);
+  }
+  if (options.onReview !== undefined) {
+    events.push(...REVIEW_EVENTS);
+  }
+  return [...new Set(events)];
+}

package/src/channels/origin/index.ts

@@ -0,0 +1,29 @@
+/**
+ * Origin webhook channel pack for agent-serve.
+ *
+ * ```ts
+ * import { defaultOriginAuth, originChannel } from "@cursor/july/channels/origin";
+ *
+ * export default originChannel({
+ *   cursorAccount: { repos: ["owner/repo"] },
+ *   onPullRequest: (ctx) => ({ auth: defaultOriginAuth(ctx) }),
+ *   onComment: (ctx) => ({ auth: defaultOriginAuth(ctx) }),
+ * });
+ * ```
+ *
+ * Direct webhook mode verifies Standard-Webhooks v1ed signatures **and**
+ * binds `envelope.appId` to {@link OriginChannelOptions.appId} (or
+ * `AGENT_SERVE_ORIGIN_APP_ID`). v1ed alone is not channel auth — Origin
+ * signs every app's deliveries with the same JWKS. Pass
+ * `{ cursorAccount: true }` to receive events from
+ * `serve({ cursor: { events: true } })` after `/v0/scm-events`
+ * (`provider: "origin"`) already verified them. The turn principal is
+ * `origin-webhook` plus the Origin actor — not the Cursor subscriber —
+ * matching GitHub's `github-webhook` pattern.
+ */
+
+export * from "./cursor-account.js";
+export * from "./events.js";
+export * from "./origin-channel.js";
+export * from "./origin-webhook.js";
+export * from "./types.js";