@cursor/july 0.1.73 → 0.1.75

package/src/channels/origin/binding.ts

@@ -0,0 +1,96 @@
+/**
+ * Rebuild the Origin API handle (`ctx.origin`) for inbound hooks.
+ *
+ * The handle is repo-bound and lazy: no credential is resolved until the
+ * first call, so channels without outbound Origin credentials still dispatch
+ * normally. Credential resolution combines the channel's `app` option with
+ * the environment (`ORIGIN_APP_ID` / `ORIGIN_APP_INSTALLATION_ID` /
+ * `ORIGIN_APP_PRIVATE_KEY`); the delivery's installation id fills in when
+ * neither pins one — the GitHub webhook `installation.id` analogue.
+ */
+
+import {
+  createOriginClient,
+  type OriginApiMethod,
+  type OriginClient,
+  resolveOriginAppCredentialParts,
+} from "./api.js";
+import {
+  createOriginCheck,
+  type OriginCheck,
+  type OriginCheckCreateInput,
+} from "./checks.js";
+import type { OriginAppOptions, OriginRepositoryRef } from "./types.js";
+
+/** Origin operations exposed to hooks (`ctx.origin`). */
+export interface OriginHandle {
+  /** Installation id the outbound credential is minted for, when known. */
+  installationId: string | undefined;
+  repository: OriginRepositoryRef;
+  /**
+   * Call an Origin public REST path with the channel's app credential.
+   * Throws `OriginApiError` on API failure.
+   */
+  request<T = unknown>(input: {
+    method: OriginApiMethod;
+    path: string;
+    body?: unknown;
+  }): Promise<T>;
+  /**
+   * Open a CI check run on `sha` and get a handle for updating and
+   * concluding it. Needs an app installation with
+   * `repository:checks:write` — Origin check writes are installation-only.
+   */
+  createCheck(
+    input: Omit<OriginCheckCreateInput, "origin" | "owner" | "repo">
+  ): Promise<OriginCheck>;
+}
+
+export function buildOriginBinding(input: {
+  repository: OriginRepositoryRef;
+  /** Installation id from the delivery envelope, when present. */
+  installationId?: string;
+  /** Channel-authored outbound app credentials / API base. */
+  app?: OriginAppOptions;
+  /** Injectable fetch for tests. */
+  fetch?: typeof fetch;
+}): OriginHandle {
+  let client: OriginClient | undefined;
+  const getClient = (): OriginClient => {
+    if (client === undefined) {
+      const fromEnv = resolveOriginAppCredentialParts();
+      const appId = input.app?.appId ?? fromEnv.appId;
+      const installationId =
+        input.app?.installationId ??
+        input.installationId ??
+        fromEnv.installationId;
+      const privateKey = input.app?.privateKey ?? fromEnv.privateKey;
+      const credentials =
+        appId !== undefined &&
+        installationId !== undefined &&
+        privateKey !== undefined
+          ? { appId, installationId, privateKey }
+          : undefined;
+      client = createOriginClient({
+        token: input.app?.token,
+        credentials,
+        apiBaseUrl: input.app?.apiBaseUrl,
+        fetch: input.fetch,
+      });
+    }
+    return client;
+  };
+
+  return {
+    installationId: input.app?.installationId ?? input.installationId,
+    repository: input.repository,
+    request: (request) => getClient().request(request),
+    createCheck: (check) =>
+      createOriginCheck({
+        ...check,
+        origin: getClient(),
+        owner: input.repository.owner,
+        repo: input.repository.name,
+      }),
+  };
+}

package/src/channels/origin/checks.ts

@@ -0,0 +1,250 @@
+/**
+ * Origin CI checks — the Origin {@link CiCheckWriter} behind the shared check
+ * lifecycle in `../checks.js`.
+ *
+ * Origin check runs are idempotent upserts keyed by `(repo, head SHA, suite
+ * key, check key)`, so every write re-POSTs the full desired state with a
+ * fresh `externalUpdatedAt`, and `resumeOriginCheck` needs only those
+ * identity fields (no server id) to rebuild a handle after a restart.
+ *
+ * Posting needs `repository:checks:write` and is installation-only: the
+ * client must authenticate with an `oit_…` installation token (see
+ * `createOriginClient` / `originAppTokenProvider` in `api.js`). Works with
+ * any client exposing `request()` (`ctx.origin`, `createOriginClient()`),
+ * and is also reachable as `ctx.origin.createCheck(...)`. API failures throw
+ * `OriginApiError`.
+ */
+
+import {
+  type CiCheck,
+  type CiCheckConcludeInput,
+  type CiCheckConclusion,
+  type CiCheckCreateInput,
+  type CiCheckOutput,
+  type CiCheckRef,
+  type CiCheckStatus,
+  type CiChecksClient,
+  type CiCheckUpdateInput,
+  type CiCheckWriter,
+  openCiCheck,
+  resumeCiCheck,
+} from "../checks.js";
+import type { OriginApiMethod } from "./api.js";
+
+/** Any client that can call the Origin public REST API. */
+export interface OriginCheckClient {
+  request<T = unknown>(input: {
+    method: OriginApiMethod;
+    path: string;
+    body?: unknown;
+  }): Promise<T>;
+}
+
+export type OriginCheckRunStatus = CiCheckStatus;
+
+/** Origin accepts the shared conclusion set plus `stale`. */
+export type OriginCheckRunConclusion = CiCheckConclusion | "stale";
+
+export type OriginCheckOutput = CiCheckOutput;
+export type OriginCheckUpdateInput =
+  CiCheckUpdateInput<OriginCheckRunConclusion>;
+export type OriginCheckConcludeInput =
+  CiCheckConcludeInput<OriginCheckRunConclusion>;
+
+/** A created check run. All methods throw `OriginApiError` on API failure. */
+export type OriginCheck = CiCheck<OriginCheckRunConclusion> & CiCheckRef;
+
+/** The upsert identity + client an Origin check is bound to. */
+export interface OriginCheckIdentityInput {
+  /** Client used for every API call on the returned handle. */
+  origin: OriginCheckClient;
+  /** Repository owner slug, e.g. `"anysphere"`. */
+  owner: string;
+  /** Repository name, e.g. `"everysphere"`. */
+  repo: string;
+  /** Check name shown in the PR merge box, e.g. `"Cursor Security Review"`. */
+  name: string;
+  /** Commit the check attaches to (usually the PR head SHA). */
+  sha: string;
+  /**
+   * Stable, app-chosen key identifying the logical check across attempts
+   * (part of the upsert identity). Defaults to a slug of `name`.
+   */
+  key?: string;
+  /** Suite the check belongs to. Defaults to a suite mirroring the check. */
+  suite?: { key?: string; name?: string; detailsUrl?: string };
+  /**
+   * Provider-assigned immutable identity for this check attempt. Defaults to
+   * a deterministic id derived from the keys and `sha`.
+   */
+  externalId?: string;
+}
+
+export interface OriginCheckCreateInput
+  extends OriginCheckIdentityInput,
+    CiCheckCreateInput {}
+
+/**
+ * Origin rejects the whole upsert when `output.title` exceeds 255 characters
+ * or a body exceeds 65,535 UTF-8 bytes, so the writer caps rather than
+ * risking a lost check write.
+ */
+const OUTPUT_TITLE_MAX_CHARS = 255;
+const OUTPUT_BODY_MAX_BYTES = 65_000;
+
+/** Truncate to at most `maxBytes` UTF-8 bytes without severing a character. */
+function capUtf8Bytes(text: string, maxBytes: number): string {
+  const encoded = new TextEncoder().encode(text);
+  if (encoded.length <= maxBytes) {
+    return text;
+  }
+  // A non-fatal decode turns a trailing partial character into U+FFFD;
+  // stripping it keeps the result valid (and re-encodable) under the cap.
+  return new TextDecoder("utf-8")
+    .decode(encoded.subarray(0, maxBytes))
+    .replace(/\uFFFD+$/, "");
+}
+
+function cappedOutput(
+  output: CiCheckOutput | undefined
+): Record<string, unknown> | undefined {
+  if (output === undefined) {
+    return undefined;
+  }
+  return {
+    title: output.title.slice(0, OUTPUT_TITLE_MAX_CHARS),
+    summary: capUtf8Bytes(output.summary, OUTPUT_BODY_MAX_BYTES),
+    ...(output.text === undefined
+      ? {}
+      : { text: capUtf8Bytes(output.text, OUTPUT_BODY_MAX_BYTES) }),
+  };
+}
+
+/** Derive a stable check key from a display name, e.g. `cursor-security-review`. */
+export function originCheckKeyFromName(name: string): string {
+  const slug = name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 100);
+  return slug === "" ? "check" : slug;
+}
+
+/**
+ * Origin writer: every write is a full keyed upsert. Tracks the last written
+ * status so an output-only update cannot regress a running check to queued.
+ */
+function originCheckWriter(
+  input: OriginCheckIdentityInput & { status?: CiCheckStatus }
+): CiCheckWriter<OriginCheckRunConclusion> {
+  const key = input.key ?? originCheckKeyFromName(input.name);
+  const suiteKey = input.suite?.key ?? key;
+  const externalId =
+    input.externalId ?? `agent-serve:${suiteKey}:${key}:${input.sha}`;
+  const path = `/v1/origin/repos/${encodeURIComponent(input.owner)}/${encodeURIComponent(
+    input.repo
+  )}/check-runs`;
+  let lastStatus: CiCheckStatus = input.status ?? "in_progress";
+  return async (write) => {
+    const status =
+      write.status ??
+      (write.conclusion === undefined ? lastStatus : "completed");
+    lastStatus = status;
+    const response = await input.origin.request<{
+      checkRun?: { id?: unknown };
+    }>({
+      method: "POST",
+      path,
+      body: {
+        headSha: input.sha,
+        checkSuite: {
+          key: suiteKey,
+          name: input.suite?.name ?? input.name,
+          externalId: `agent-serve:${suiteKey}`,
+          ...(input.suite?.detailsUrl === undefined
+            ? {}
+            : { detailsUrl: input.suite.detailsUrl }),
+        },
+        checkRun: {
+          key,
+          name: input.name,
+          status,
+          conclusion: write.conclusion,
+          // Origin only applies an upsert when this timestamp is at least as
+          // new as the stored check; timestamp every write when it is built.
+          externalUpdatedAt: new Date().toISOString(),
+          externalId,
+          startedAt: write.startedAt,
+          completedAt: write.completedAt,
+          detailsUrl: write.detailsUrl,
+          output: cappedOutput(write.output),
+        },
+      },
+    });
+    const id = response?.checkRun?.id;
+    return typeof id === "string" ? { id } : undefined;
+  };
+}
+
+/**
+ * Create a CI check run on a commit and return a handle for later updates.
+ *
+ * ```ts
+ * const check = await createOriginCheck({
+ *   origin: ctx.origin,
+ *   owner: ctx.repository.owner,
+ *   repo: ctx.repository.name,
+ *   name: "Cursor Security Review",
+ *   sha: pr.headSha,
+ *   detailsUrl: sessionUrl,
+ *   output: { title: "Running…", summary: `[View session](${sessionUrl})` },
+ * });
+ * // …do the work…
+ * await check.conclude({ conclusion: "success", output: { … } });
+ * ```
+ */
+export function createOriginCheck(
+  input: OriginCheckCreateInput
+): Promise<OriginCheck> {
+  return openCiCheck(originCheckWriter(input), input);
+}
+
+/**
+ * Rebuild an {@link OriginCheck} handle for an existing check run (e.g.
+ * after a process restart) from its upsert identity — no server id needed.
+ * No API call is made until the first update.
+ */
+export function resumeOriginCheck(
+  input: OriginCheckIdentityInput & {
+    /** Last known status; defaults to `"in_progress"`. */
+    status?: CiCheckStatus;
+    /** Server-assigned id (`cr_…`) when known. */
+    id?: string;
+  }
+): OriginCheck {
+  return resumeCiCheck(
+    originCheckWriter(input),
+    input.id === undefined ? undefined : { id: input.id }
+  );
+}
+
+/**
+ * Repo-bound checks adapter satisfying the shared {@link CiChecksClient}
+ * contract — hand it to forge-agnostic check code when there is no channel
+ * `ctx.origin` (e.g. CI entrypoints).
+ */
+export function bindOriginChecks(input: {
+  origin: OriginCheckClient;
+  owner: string;
+  repo: string;
+}): CiChecksClient<OriginCheckRunConclusion> {
+  return {
+    createCheck: (check) =>
+      createOriginCheck({
+        ...check,
+        origin: input.origin,
+        owner: input.owner,
+        repo: input.repo,
+      }),
+  };
+}

package/src/channels/origin/index.ts

@@ -22,6 +22,9 @@
  * matching GitHub's `github-webhook` pattern.
  */
 
+export * from "./api.js";
+export * from "./binding.js";
+export * from "./checks.js";
 export * from "./cursor-account.js";
 export * from "./events.js";
 export * from "./origin-channel.js";

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

@@ -13,6 +13,7 @@ import type {
   ChannelDefinition,
   ChannelHandlerArgs,
 } from "../../types.js";
+import { buildOriginBinding } from "./binding.js";
 import {
   parseCursorOriginRepoScope,
   registerOriginCursorAccountRuntime,
@@ -268,7 +269,7 @@ function originSender(
 export function parseOriginPullRequestEvent(input: {
   envelope: OriginWebhookEnvelope;
 }): {
-  ctx: Omit<OriginEventContext, "host" | "artifacts">;
+  ctx: Omit<OriginEventContext, "host" | "artifacts" | "origin">;
   pullRequest: OriginPullRequestEvent;
   payload: Record<string, unknown>;
 } | null {
@@ -294,6 +295,7 @@ export function parseOriginPullRequestEvent(input: {
     ctx: {
       deliveryId: input.envelope.deliveryId,
       eventType,
+      installationId: input.envelope.installationId,
       repository,
       pullRequestNumber: number,
       pullRequestUrl: url,
@@ -332,7 +334,7 @@ export function parseOriginPullRequestEvent(input: {
  * as {@link defaultGitHubAuth}).
  */
 export function defaultOriginAuth(
-  ctx: Omit<OriginEventContext, "host" | "artifacts">
+  ctx: Omit<OriginEventContext, "host" | "artifacts" | "origin">
 ): AuthContext {
   const senderId = ctx.sender?.id;
   return {
@@ -363,7 +365,7 @@ export function defaultOriginTitle(
 }
 
 export function defaultOriginPullRequestMessage(
-  ctx: Omit<OriginEventContext, "host" | "artifacts">,
+  ctx: Omit<OriginEventContext, "host" | "artifacts" | "origin">,
   pullRequest: OriginPullRequestEvent
 ): string {
   const head =
@@ -381,7 +383,7 @@ export function defaultOriginPullRequestMessage(
 }
 
 export function defaultOriginPullRequestDispatch(
-  ctx: Omit<OriginEventContext, "host" | "artifacts">,
+  ctx: Omit<OriginEventContext, "host" | "artifacts" | "origin">,
   pullRequest: OriginPullRequestEvent
 ): OriginTurnDispatch | null {
   if (!DEFAULT_PULL_REQUEST_TYPES.has(pullRequest.type)) {
@@ -397,13 +399,19 @@ function isTaskDispatch(
 }
 
 function enrichEventContext(input: {
-  ctx: Omit<OriginEventContext, "host" | "artifacts">;
+  ctx: Omit<OriginEventContext, "host" | "artifacts" | "origin">;
   args: ChannelHandlerArgs;
+  options: OriginChannelOptions;
 }): OriginEventContext {
   return {
     ...input.ctx,
     host: input.args.host,
     artifacts: input.args.artifacts,
+    origin: buildOriginBinding({
+      repository: input.ctx.repository,
+      installationId: input.ctx.installationId,
+      app: input.options.app,
+    }),
   };
 }
 
@@ -525,7 +533,11 @@ export async function dispatchOriginWebhook(input: {
       { status: 400 }
     );
   }
-  const ctx = enrichEventContext({ ctx: parsed.ctx, args: input.args });
+  const ctx = enrichEventContext({
+    ctx: parsed.ctx,
+    args: input.args,
+    options: input.options,
+  });
   const { pullRequest, payload } = parsed;
   const repoAllowlist = configuredOriginRepoAllowlist(input.options);
   if (

package/src/channels/origin/types.ts

@@ -6,6 +6,8 @@ import type {
   ChannelStartArgs,
   HostContext,
 } from "../../types.js";
+import type { OriginTokenProvider } from "./api.js";
+import type { OriginHandle } from "./binding.js";
 
 export interface OriginActor {
   id: string;
@@ -48,12 +50,21 @@ export interface OriginReview {
 export interface OriginEventContext {
   deliveryId?: string;
   eventType: string;
+  /** Origin app installation id from the delivery envelope, when present. */
+  installationId?: string;
   repository: OriginRepositoryRef;
   pullRequestNumber: number;
   pullRequestUrl: string;
   sender?: OriginActor;
   host: HostContext;
   artifacts: ArtifactsApi;
+  /**
+   * Repo-bound Origin public API handle (REST calls + `createCheck`).
+   * Outbound credentials come from {@link OriginChannelOptions.app} or the
+   * `ORIGIN_APP_*` environment; resolution is lazy, so hooks that never call
+   * it need no credentials.
+   */
+  origin: OriginHandle;
 }
 
 export type OriginTurnDispatch = {
@@ -114,6 +125,26 @@ export interface OriginWebhookEnvelope {
   };
 }
 
+/**
+ * Outbound Origin app credentials for `ctx.origin` (public REST calls, CI
+ * check runs). Fields left unset fall back to the environment
+ * (`ORIGIN_APP_ID` / `ORIGIN_APP_INSTALLATION_ID` / `ORIGIN_APP_PRIVATE_KEY`
+ * / `ORIGIN_API_BASE_URL`); the delivery's installation id fills in when
+ * neither pins one.
+ */
+export interface OriginAppOptions {
+  /** Origin app id (`app_<typeid>`). */
+  appId?: string;
+  /** Installation id outbound tokens are minted for. */
+  installationId?: string;
+  /** PKCS8 PEM for the app's EdDSA (Ed25519) private key. */
+  privateKey?: string;
+  /** Static bearer (`oit_…`) or provider, bypassing the app-JWT mint. */
+  token?: string | OriginTokenProvider;
+  /** Public Origin REST base, e.g. `https://api.cursor.com`. */
+  apiBaseUrl?: string;
+}
+
 export interface OriginChannelOptions {
   /**
    * Use the signed-in Cursor account for inbound Origin events via
@@ -149,6 +180,12 @@ export interface OriginChannelOptions {
    * (GitHub's no-secret posture); `--dev` / skip-verify admits loopback only.
    */
   auth?: AuthPolicy[];
+  /**
+   * Outbound Origin app credentials for `ctx.origin` (REST calls, CI check
+   * runs). Optional: every field falls back to the `ORIGIN_APP_*`
+   * environment, and inbound-only channels need none.
+   */
+  app?: OriginAppOptions;
   /** Route path under `/v1/channels/<name>`. Defaults to `/`. */
   path?: string;
   /** Origin API base used to fetch `/v1/origin/keys` for v1ed verify. */

package/src/channels.ts

@@ -47,6 +47,22 @@
  * Handlers receive `args.body` / `args.query` inferred from those schemas.
  */
 
+export {
+  type CiCheck,
+  type CiCheckConcludeInput,
+  type CiCheckConclusion,
+  type CiCheckCreateInput,
+  type CiCheckOutput,
+  type CiCheckRef,
+  type CiCheckStatus,
+  type CiChecksClient,
+  type CiCheckUpdateInput,
+  type CiCheckWrite,
+  type CiCheckWriter,
+  openCiCheck,
+  resumeCiCheck,
+} from "./channels/checks.js";
+
 import { Buffer } from "node:buffer";
 import { timingSafeEqual } from "node:crypto";
 import { brandDefinition } from "./internal/brand.js";

package/src/internal/cli-skills.ts

@@ -1,15 +1,18 @@
 /**
  * `install-skills` — install the package's coding-agent skills into
- * `~/.cursor/skills/agentkit/` without running `init`.
+ * `~/.cursor/skills/agentsdk/` without running `init`.
  *
  * Never prompts: running the command is the confirmation. The interactive
- * offer lives in `init`.
+ * offer lives in `init`. Consumer `npm install` / `npx` copies the same
+ * skills in postinstall (with `alwaysApply: true` so Cursor injects them);
+ * this command refreshes them without reinstalling.
  */
 
 import { CLI_COMMAND_NAME } from "./distribution.js";
 import {
   formatSkillInstall,
   installCursorSkills,
+  LEGACY_CURSOR_SKILLS_NAMESPACE,
   planSkillInstall,
   type SkillInstallPlan,
 } from "./install-cursor-skills.js";
@@ -90,6 +93,11 @@ function previewBlock(plan: SkillInstallPlan): string {
   if (plan.orphans.length > 0) {
     lines.push(`  removes:  ${plan.orphans.join(", ")}`);
   }
+  if (plan.hasLegacyNamespace) {
+    lines.push(
+      `  removes:  ${LEGACY_CURSOR_SKILLS_NAMESPACE}/ (legacy namespace)`
+    );
+  }
   lines.push(`  location: ${plan.directory}`);
   return `${lines.join("\n")}\n`;
 }