@cursor/july 0.1.74 → 0.1.76

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/authored-alias-hooks.ts

@@ -14,16 +14,29 @@
  *   project's own node_modules; `fallbackAliases` only apply when that
  *   fails (npx/global installs, projects without a local dependency), so a
  *   real install in the user's project keeps precedence.
+ *
+ * A third case is first-party factory agents that relative-import this
+ * package's `src/` from a monorepo checkout. Hosted engines `npm install`
+ * only the agent directory, so files under `packages/agent-serve/src` have
+ * no `node_modules`. Bare specifiers from that tree (`zod`, octokit, …)
+ * retry against the running `@cursor/july` package.json, which does.
  */
 
 // Null-prototype copies so specifiers like "constructor" or "__proto__"
 // can never resolve to inherited Object.prototype members.
 let directAliases = toNullProtoMap({});
 let fallbackAliases = toNullProtoMap({});
+let sourceTreeFallbackParentURL: string | undefined;
 
 export interface AuthoredAliasHookData {
   directAliases: Record<string, string>;
   fallbackAliases: Record<string, string>;
+  /**
+   * `file:` URL of the running `@cursor/july` package.json. Bare imports
+   * from monorepo `packages/agent-serve/` source retry against this parent
+   * when the source tree has no `node_modules` (hosted factory engines).
+   */
+  sourceTreeFallbackParentURL?: string;
 }
 
 function toNullProtoMap(
@@ -35,6 +48,9 @@ function toNullProtoMap(
 export function initialize(data: AuthoredAliasHookData): void {
   directAliases = toNullProtoMap(data.directAliases);
   fallbackAliases = toNullProtoMap(data.fallbackAliases);
+  const parent = data.sourceTreeFallbackParentURL;
+  sourceTreeFallbackParentURL =
+    typeof parent === "string" && parent !== "" ? parent : undefined;
 }
 
 interface ResolveResult {
@@ -58,12 +74,64 @@ export function resolve(
     return { url: direct, shortCircuit: true };
   }
   const fallback = fallbackAliases[specifier];
-  if (fallback === undefined) {
-    // Not ours: pass through with no promise/try-catch overhead. This hook
-    // runs on every module resolution in the process.
-    return nextResolve(specifier, context);
+  if (fallback !== undefined) {
+    return Promise.resolve()
+      .then(() => nextResolve(specifier, context))
+      .catch(() => ({ url: fallback, shortCircuit: true }));
+  }
+  if (
+    sourceTreeFallbackParentURL !== undefined &&
+    isBarePackageSpecifier(specifier) &&
+    isMonorepoAgentServeSource(parentURLOf(context))
+  ) {
+    const retryParent = sourceTreeFallbackParentURL;
+    return Promise.resolve()
+      .then(() => nextResolve(specifier, context))
+      .catch(() => nextResolve(specifier, withParentURL(context, retryParent)));
+  }
+  // Not ours: pass through with no promise/try-catch overhead. This hook
+  // runs on every module resolution in the process.
+  return nextResolve(specifier, context);
+}
+
+function parentURLOf(context: unknown): string | undefined {
+  if (context === null || typeof context !== "object") {
+    return undefined;
+  }
+  const parentURL = (context as { parentURL?: unknown }).parentURL;
+  return typeof parentURL === "string" ? parentURL : undefined;
+}
+
+function withParentURL(context: unknown, parentURL: string): unknown {
+  if (context !== null && typeof context === "object") {
+    return { ...(context as Record<string, unknown>), parentURL };
+  }
+  return { parentURL };
+}
+
+function isBarePackageSpecifier(specifier: string): boolean {
+  if (specifier.length === 0) {
+    return false;
+  }
+  const first = specifier[0];
+  if (first === "." || first === "/" || first === "\\") {
+    return false;
+  }
+  return !(
+    specifier.startsWith("node:") ||
+    specifier.startsWith("file:") ||
+    specifier.startsWith("data:") ||
+    specifier.startsWith("http:") ||
+    specifier.startsWith("https:")
+  );
+}
+
+function isMonorepoAgentServeSource(parentURL: string | undefined): boolean {
+  if (parentURL === undefined) {
+    return false;
   }
-  return Promise.resolve()
-    .then(() => nextResolve(specifier, context))
-    .catch(() => ({ url: fallback, shortCircuit: true }));
+  return (
+    parentURL.includes("/packages/agent-serve/") &&
+    !parentURL.includes("/node_modules/")
+  );
 }

package/src/internal/authored-loaders.ts

@@ -11,9 +11,11 @@
  * imports of the framework resolve against the running package: the
  * historical `@anysphere/agent-serve[/x]` name always, and
  * `@cursor/july[/x]` / `@cursor/agentkit[/x]` as fallbacks when the user's
- * project has no local install (npx / global). Source runs (tsx from the
- * monorepo) skip both — the host loader and tsconfig paths already cover
- * them.
+ * project has no local install (npx / global). The same hooks retry bare
+ * npm specifiers from monorepo `packages/agent-serve/` source against this
+ * package (hosted factory engines install only the agent directory).
+ * Source runs (tsx from the monorepo) skip both — the host loader and
+ * tsconfig paths already cover them.
  */
 
 import { stat } from "node:fs/promises";
@@ -175,7 +177,16 @@ function registerFrameworkAliases(): void {
     fallbackAliases[`${AGENTKIT_PACKAGE_NAME}${suffix}`] = target;
   }
   const hooksUrl = new URL("./authored-alias-hooks.js", import.meta.url);
-  const data: AuthoredAliasHookData = { directAliases, fallbackAliases };
+  const data: AuthoredAliasHookData = {
+    directAliases,
+    fallbackAliases,
+    // Hosted factory agents relative-import this package's src/ from a
+    // monorepo checkout while npm install ran only in the agent directory.
+    // Bare specifiers from that tree retry against this package.json.
+    sourceTreeFallbackParentURL: pathToFileURL(
+      join(packageRootDir(), "package.json")
+    ).href,
+  };
   // `node:module`'s register() is synchronous: it blocks until the hooks
   // thread has initialized, so the aliases are active when it returns.
   registerModuleHooks(hooksUrl, { data });