@cursor/july 0.1.54 → 0.1.61

package/src/bin/agent-serve.ts

@@ -108,7 +108,7 @@ Usage:
   ${CLI} trajectory  --events <file.ndjson> [--text]
   ${CLI} call        <tool> [--input <json>] [--dir <path> | --url <baseUrl> | --prod]
                           [--session <id>] [--slug <slug>] [--team <id>]
-  ${CLI} init        [dir] [--template <name>] [--json]
+  ${CLI} init        [dir] [--template <name>] [--var id=value]... [--json]
   ${CLI} convert-automation <url> [--dir <path>] [--json]
   ${CLI} install-skills [--print] [--json]
   ${CLI} mcp         --prod [--slug <slug>] [--team <id>] [--dir <path>]
@@ -198,9 +198,10 @@ Commands:
               via POST /v1/tools/:toolName. --session runs it inside an
               existing session and records it on that session's event stream.
   init        Scaffold a project (skipping existing files), npm install,
-              run login when unsigned, then print next steps. --json is
-              machine-readable and never blocks on login. No directory:
-              print the setup guide.
+              run login when unsigned, then print next steps. Templates
+              with init.json interview on a TTY; --var answers without a
+              prompt. --json is machine-readable and never blocks on
+              login. No directory: print the setup guide.
   convert-automation
               Export a Cursor Automation into an agentkit project. <url> is
               the dashboard URL (…/automations/<uuid> or
@@ -481,6 +482,7 @@ async function main(argv: string[]): Promise<number> {
     options: {
       dir: { type: "string", default: "." },
       template: { type: "string" },
+      var: { type: "string", multiple: true },
       port: { type: "string" },
       host: { type: "string" },
       mode: { type: "string" },
@@ -540,7 +542,7 @@ async function main(argv: string[]): Promise<number> {
       org: { type: "string" },
       "cursor-events": { type: "boolean", default: false },
       secret: { type: "string" },
-      channel: { type: "string" },
+      channel: { type: "string", multiple: true },
       install: { type: "boolean", default: false },
       action: { type: "string" },
       conclusion: { type: "string" },
@@ -594,6 +596,7 @@ async function main(argv: string[]): Promise<number> {
         prefix: values.prefix,
         noPrefix: values["no-prefix"],
         channelPosts: values["channel-posts"],
+        channels: values.channel,
         slackTeam: values["slack-team"],
         prod: values.prod,
         team: values.team,
@@ -620,7 +623,9 @@ async function main(argv: string[]): Promise<number> {
       return cmdGithub(positionals[0], {
         dir,
         slug: values.slug,
-        channel: values.channel,
+        // `--channel` is repeatable for `slack doctor`; the github
+        // subcommands target a single channel, so the last one wins.
+        channel: values.channel?.at(-1),
         host: values.host,
         port,
         url: values.url,
@@ -646,6 +651,7 @@ async function main(argv: string[]): Promise<number> {
         dir,
         initTarget: positionals[0],
         template: values.template,
+        vars: values.var,
         json: values.json,
       });
     }
@@ -1375,6 +1381,7 @@ function axFromOptions(
     tags: partial.tags,
     evalIds: partial.evalIds,
     initTarget: partial.initTarget,
+    vars: partial.vars,
     toolName: partial.toolName,
     toolInput: partial.toolInput,
     url: partial.url,

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

@@ -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
@@ -1469,15 +1508,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 +1544,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 }

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;
@@ -324,6 +339,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 +354,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";