@cursor/july 0.1.45 → 0.1.46

package/src/channels/github/api.ts

@@ -384,6 +384,128 @@ export async function createGitHubCommitStatus(
   }
 }
 
+export type GitHubCheckRunStatus = "queued" | "in_progress" | "completed";
+export type GitHubCheckRunConclusion =
+  | "action_required"
+  | "cancelled"
+  | "failure"
+  | "neutral"
+  | "skipped"
+  | "success"
+  | "timed_out";
+
+export interface GitHubCheckRun {
+  htmlUrl: string | undefined;
+  id: number;
+  raw: unknown;
+}
+
+export interface GitHubCheckRunWriteInput {
+  conclusion?: GitHubCheckRunConclusion;
+  detailsUrl?: string;
+  name: string;
+  output?: { summary: string; title: string };
+  status: GitHubCheckRunStatus;
+}
+
+/** Create a check run (Checks API). */
+export async function createGitHubCheckRun(
+  input: GitHubResourceInput &
+    GitHubCheckRunWriteInput & {
+      sha: string;
+    }
+): Promise<GitHubCheckRun> {
+  const octokit = await createGitHubOctokit(input);
+  const now = new Date().toISOString();
+  try {
+    const response = await octokit.rest.checks.create({
+      owner: input.owner,
+      repo: input.repo,
+      name: input.name,
+      head_sha: input.sha,
+      status: input.status,
+      started_at: now,
+      ...checkRunCompletionFields(input, now),
+      ...checkRunDetailsUrl(input),
+      ...checkRunOutput(input),
+    });
+    return toCheckRun(response.data);
+  } catch (error) {
+    throw wrapOctokitError(
+      error,
+      "POST",
+      `/repos/${input.owner}/${input.repo}/check-runs`
+    );
+  }
+}
+
+/** Update a check run (Checks API). */
+export async function updateGitHubCheckRun(
+  input: GitHubResourceInput &
+    GitHubCheckRunWriteInput & {
+      checkRunId: number;
+    }
+): Promise<GitHubCheckRun> {
+  const octokit = await createGitHubOctokit(input);
+  try {
+    const response = await octokit.rest.checks.update({
+      owner: input.owner,
+      repo: input.repo,
+      check_run_id: input.checkRunId,
+      name: input.name,
+      status: input.status,
+      ...checkRunCompletionFields(input, new Date().toISOString()),
+      ...checkRunDetailsUrl(input),
+      ...checkRunOutput(input),
+    });
+    return toCheckRun(response.data);
+  } catch (error) {
+    throw wrapOctokitError(
+      error,
+      "PATCH",
+      `/repos/${input.owner}/${input.repo}/check-runs/${input.checkRunId}`
+    );
+  }
+}
+
+function checkRunCompletionFields(
+  input: GitHubCheckRunWriteInput,
+  completedAt: string
+): {
+  completed_at?: string;
+  conclusion?: GitHubCheckRunConclusion;
+} {
+  if (input.status !== "completed" || input.conclusion === undefined) {
+    return {};
+  }
+  return { completed_at: completedAt, conclusion: input.conclusion };
+}
+
+function checkRunDetailsUrl(input: GitHubCheckRunWriteInput): {
+  details_url?: string;
+} {
+  return input.detailsUrl === undefined
+    ? {}
+    : { details_url: input.detailsUrl };
+}
+
+function checkRunOutput(input: GitHubCheckRunWriteInput): {
+  output?: { summary: string; title: string };
+} {
+  return input.output === undefined ? {} : { output: input.output };
+}
+
+function toCheckRun(raw: {
+  html_url?: string | null;
+  id?: number;
+}): GitHubCheckRun {
+  return {
+    htmlUrl: typeof raw.html_url === "string" ? raw.html_url : undefined,
+    id: typeof raw.id === "number" ? raw.id : 0,
+    raw,
+  };
+}
+
 function toPostedComment(raw: {
   html_url?: string;
   id?: number;

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

@@ -117,6 +117,29 @@ export function parseCursorGithubRepoScope(
   };
 }
 
+/**
+ * Hosted `cursorAccount` mints `checks:write` on the `contents-write` tier.
+ * Enabling `progress.commitStatus` opts a `pr-write` (or omitted) channel up
+ * to that tier so github-proxy / `/github-token` can post Checks API runs.
+ * `"read"` cannot post merge-box checks.
+ */
+export function cursorGithubPermissionsForChannel(
+  options: Pick<GitHubChannelOptions, "progress">,
+  authored: CursorGithubPermissions | undefined = "pr-write"
+): CursorGithubPermissions {
+  const base = authored ?? "pr-write";
+  const commitStatus = options.progress?.commitStatus;
+  if (commitStatus === undefined || commitStatus === false) {
+    return base;
+  }
+  if (base === "read") {
+    throw new Error(
+      'progress.commitStatus needs checks:write; cursorAccount permissions: "read" cannot post merge-box checks. Use "pr-write" or "contents-write".'
+    );
+  }
+  return "contents-write";
+}
+
 /** One host credential: the most privileged requested tier wins. */
 export function resolveCursorGithubPermissions(
   values: readonly CursorGithubPermissions[]

package/src/channels/github/defaults.ts

@@ -19,7 +19,7 @@ export interface BuildDefaultGitHubEventsOptions extends GitHubBindingConfig {
 }
 
 /**
- * Built-in delivery: eyes reaction on turn start, optional commit status /
+ * Built-in delivery: eyes reaction on turn start, optional Checks API run /
  * sticky banner via {@link GitHubProgressConfig}, post assistant text on
  * `message.completed`, and a short error comment on turn/session failure.
  */

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

@@ -27,6 +27,7 @@ import {
 import {
   createCursorAccountGithubTokenResolver,
   createPendingCursorGithubCredentials,
+  cursorGithubPermissionsForChannel,
   type PendingCursorGithubCredentials,
   parseCursorGithubRepoScope,
   registerGithubCursorAccountRuntime,
@@ -608,7 +609,10 @@ export function githubChannel(
     typeof options.cursorAccount === "object"
       ? parseCursorGithubRepoScope(
           options.cursorAccount.repos,
-          options.cursorAccount.permissions
+          cursorGithubPermissionsForChannel(
+            options,
+            options.cursorAccount.permissions
+          )
         )
       : undefined;
 

package/src/channels/github/progress.ts

@@ -1,18 +1,20 @@
 /**
- * Opt-in PR progress surfaces: commit status + sticky banner comment.
+ * Opt-in PR progress surfaces: Checks API run + sticky banner comment.
  */
 
 import {
-  createGitHubCommitStatus,
+  createGitHubCheckRun,
   createGitHubIssueComment,
   GitHubApiError,
+  type GitHubCheckRunWriteInput,
+  updateGitHubCheckRun,
   updateGitHubIssueComment,
 } from "./api.js";
 import type { GitHubBindingConfig } from "./binding.js";
 import { formatGitHubOutboundComment } from "./binding.js";
 import type { GitHubChannelState } from "./state.js";
 
-/** GitHub commit-status descriptions are capped at 140 characters. */
+/** Merge-box check titles stay short; GitHub allows 1024, we clip to 140. */
 const STATUS_DESCRIPTION_MAX = 140;
 
 export type GitHubProgressPhase = "pending" | "success" | "failure";
@@ -24,7 +26,7 @@ export interface GitHubProgressPhaseCopy {
 }
 
 export interface GitHubCommitStatusProgress extends GitHubProgressPhaseCopy {
-  /** Commit status context (unique per check in the merge box). */
+  /** Check run name (unique per check in the merge box). */
   context: string;
 }
 
@@ -34,9 +36,10 @@ export interface GitHubProgressConfig {
   /** When false, skip the eyes reaction on turn.started. Defaults to true. */
   reactions?: boolean;
   /**
-   * Opt-in commit status on the PR head. Omit or `false` keeps today's
-   * behavior (no statuses from default events). With `cursorAccount`,
-   * needs `permissions: "contents-write"` (push-equivalent).
+   * Opt-in Checks API run on the PR head. Omit or `false` keeps today's
+   * behavior (no check from default events). With `cursorAccount`, enabling
+   * this opts the minted token up to `permissions: "contents-write"` so the
+   * hosted github-proxy lease includes `checks:write`.
    */
   commitStatus?: false | GitHubCommitStatusProgress;
   /**
@@ -127,7 +130,7 @@ export async function applyGitHubProgress(input: {
   const tasks: Array<Promise<void>> = [];
   if (commitStatus !== null) {
     tasks.push(
-      postCommitStatus({
+      postProgressCheckRun({
         phase: input.phase,
         channel: input.channel,
         options: input.options,
@@ -149,7 +152,7 @@ export async function applyGitHubProgress(input: {
   await Promise.all(tasks);
 }
 
-async function postCommitStatus(input: {
+async function postProgressCheckRun(input: {
   phase: GitHubProgressPhase;
   channel: { state: GitHubChannelState };
   options: GitHubProgressOptions;
@@ -164,6 +167,7 @@ async function postCommitStatus(input: {
   ) {
     return;
   }
+  const sha = state.headSha;
   const description = clipStatusDescription(
     progressPhaseCopy({
       copy: input.commitStatus,
@@ -171,23 +175,84 @@ async function postCommitStatus(input: {
       label: progressLabel(input.options, input.commitStatus.context),
     })
   );
+  const write: GitHubCheckRunWriteInput = {
+    name: input.commitStatus.context,
+    ...checkRunPhaseFields(input.phase),
+    output: { title: description, summary: description },
+  };
+  const resource = {
+    api: input.options.api,
+    credentials: input.options.credentials,
+    installationId: state.installationId ?? undefined,
+    owner: state.owner,
+    repo: state.repo,
+  };
+  const reuseId =
+    state.progressCheckRunId !== null && state.progressCheckRunSha === sha
+      ? state.progressCheckRunId
+      : null;
+  // Completed runs cannot go back to in_progress. GitHub often 200s and
+  // leaves the run completed (sometimes 422). Create a new run so a later
+  // turn on the same SHA shows pending again.
+  const completedBlocksReuse =
+    write.status === "in_progress" && state.progressCheckRunCompleted === true;
   try {
-    await createGitHubCommitStatus({
-      api: input.options.api,
-      credentials: input.options.credentials,
-      installationId: state.installationId ?? undefined,
-      owner: state.owner,
-      repo: state.repo,
-      sha: state.headSha,
-      state: input.phase,
-      context: input.commitStatus.context,
-      description,
+    if (reuseId !== null && !completedBlocksReuse) {
+      try {
+        await updateGitHubCheckRun({
+          ...resource,
+          ...write,
+          checkRunId: reuseId,
+        });
+        state.progressCheckRunCompleted = write.status === "completed";
+        return;
+      } catch (error) {
+        if (!shouldRecreateCheckRun(error, write.status)) {
+          return;
+        }
+        state.progressCheckRunId = null;
+        state.progressCheckRunSha = null;
+        state.progressCheckRunCompleted = false;
+      }
+    }
+    const created = await createGitHubCheckRun({
+      ...resource,
+      ...write,
+      sha,
     });
+    state.progressCheckRunId = created.id;
+    state.progressCheckRunSha = sha;
+    state.progressCheckRunCompleted = write.status === "completed";
   } catch {
     // Soft-fail: missing token / permission is fine.
   }
 }
 
+function shouldRecreateCheckRun(
+  error: unknown,
+  status: GitHubCheckRunWriteInput["status"]
+): boolean {
+  if (!(error instanceof GitHubApiError)) {
+    return false;
+  }
+  if (error.status === 404) {
+    return true;
+  }
+  return error.status === 422 && status === "in_progress";
+}
+
+function checkRunPhaseFields(
+  phase: GitHubProgressPhase
+): Pick<GitHubCheckRunWriteInput, "conclusion" | "status"> {
+  if (phase === "pending") {
+    return { status: "in_progress" };
+  }
+  return {
+    status: "completed",
+    conclusion: phase === "success" ? "success" : "failure",
+  };
+}
+
 async function upsertBanner(input: {
   phase: GitHubProgressPhase;
   channel: { state: GitHubChannelState };

package/src/channels/github/state.ts

@@ -13,6 +13,17 @@ export interface GitHubChannelState extends GitHubBindingState {
   headRef: string | null;
   /** Sticky progress banner comment id (issue/PR timeline). */
   progressBannerCommentId: number | null;
+  /** Latest Checks API run id for `progress.commitStatus`. */
+  progressCheckRunId: number | null;
+  /** Head SHA the latest check run was created against. */
+  progressCheckRunSha: string | null;
+  /**
+   * Whether that run is already `completed`. `null` means unknown (wake
+   * patches omit this so merge keeps the persisted value). GitHub rejects
+   * PATCH back to `in_progress`, so a later pending turn on the same SHA
+   * must create a new run.
+   */
+  progressCheckRunCompleted: boolean | null;
 }
 
 export function emptyGitHubChannelState(
@@ -35,6 +46,9 @@ export function emptyGitHubChannelState(
     baseRef: null,
     headRef: null,
     progressBannerCommentId: null,
+    progressCheckRunId: null,
+    progressCheckRunSha: null,
+    progressCheckRunCompleted: null,
     ...overrides,
   };
 }

package/src/channels/github/types.ts

@@ -452,7 +452,7 @@ export interface GitHubChannelOptions {
          * Token capability tier:
          * - `"read"` — PR/issue/status read
          * - `"pr-write"` (default) — comments / PR+issue write, no `contents:write`
-         * - `"contents-write"` — push code and create commit statuses (host-held)
+         * - `"contents-write"` — push code and post merge-box check runs (host-held)
          */
         permissions?: "read" | "pr-write" | "contents-write";
       };
@@ -504,12 +504,12 @@ export interface GitHubChannelOptions {
   onEvent?: GitHubEventHook;
   /**
    * Override / extend default stream-event handlers (eyes reaction, reply
-   * posting, opt-in commit status / banner). Handlers you provide replace
+   * posting, opt-in check run / banner). Handlers you provide replace
    * the matching defaults.
    */
   events?: ChannelEventHandlers<GitHubChannelState>;
   /**
-   * Acknowledgement progress surfaces. Reactions default on; commit status
+   * Acknowledgement progress surfaces. Reactions default on; merge-box check
    * and sticky banner are opt-in via `commitStatus` / `banner`.
    */
   progress?: GitHubProgressConfig;

package/src/index.ts

@@ -94,6 +94,7 @@ export {
 } from "./internal/session-engine.js";
 export { createMemoryKv, memoryCasTable } from "./kv/memory-kv.js";
 export {
+  createLedgerJanitor,
   LedgerCasExhaustedError,
   LedgerFencedError,
   SessionLedger,

package/src/internal/auth.ts

@@ -20,6 +20,16 @@ export function isSafeSessionId(sessionId: string): boolean {
   );
 }
 
+/** Thrown when a send addresses a session owned by a different principal. */
+export class SessionAuthError extends Error {
+  constructor(sessionId: string) {
+    super(
+      `Session ${sessionId} belongs to a different principal; pass the original caller auth on follow-up`
+    );
+    this.name = "SessionAuthError";
+  }
+}
+
 /** True when both sides identify the same principal (or both are null). */
 export function samePrincipal(
   a: AuthContext | null,

package/src/internal/durable-session-store.ts

@@ -3,11 +3,13 @@
  *
  * Two APIs, one backend: `defineStorage` is the **storage API** (agent
  * state — session records, event chunks, author KV), and the session
- * ledger is the **durable session API** (session identity, leases,
- * fenced commits). The ledger consumes {@link SessionLedgerKv} — exactly
- * the three CAS methods it uses, nothing more; this module adapts a
- * storage backend's `cas` group into that interface, so a deployment's
- * one authored backend serves both APIs by default.
+ * ledger is the **durable session API** (session identity, mailboxes,
+ * leases, fenced commits). The ledger consumes {@link SessionLedgerKv} —
+ * the full CAS-capable KV surface, since the inbox reads/sweeps mailbox
+ * payload blobs (`get`/`put`/`delete`) and scans by prefix (`listKeys`)
+ * on top of the CAS trio; this module adapts a storage backend's methods
+ * into that interface, so a deployment's one authored backend serves
+ * both APIs by default.
  *
  * Calls go straight at the config's methods — NOT through the
  * StorageCoordinator: the coordinator's queue is bounded, serialized, and
@@ -22,6 +24,7 @@ import {
   type StorageConfig,
   type StorageContext,
 } from "../storage.js";
+import type { JsonValue } from "../types.js";
 
 export interface StorageCasKvArgs {
   agentName: string;
@@ -29,10 +32,29 @@ export interface StorageCasKvArgs {
 }
 
 /**
- * Adapt a storage backend's `cas` group into the ledger's KV interface.
- * Throws when the backend does not implement `cas` — the caller turns
- * that into the fail-fast startup error for `serving: "ledger"`. Every
- * call carries a `reason: "coordination"` {@link StorageContext}.
+ * The one place the ledger's physical namespace is minted: the per-agent
+ * prefix for ledger state, following the {@link storageKeys} convention
+ * (`<root>/<agent>/<family>/…`) so a store shared by several ledger-mode
+ * agents (one fileKv dir, one hosted deployment) never mixes their
+ * sessions, leases, or mailboxes — and so each agent's janitor
+ * prefix-scan only ever sees its own ledgers. The extra
+ * `durable-session` segment keeps the ledger's `session/` family out of
+ * `storageKeys.sessionPrefix` scans (storage restore lists
+ * `<root>/<agent>/session/`). The ledger itself never sees this string:
+ * it speaks bare `session/…` / `ledger/…` / `mailbox/…` keys against a
+ * handle that {@link namespacedKv} has already scoped.
+ */
+export function ledgerKeyPrefix(agentName: string): string {
+  return `${STORAGE_KEY_ROOT}/${keySegment(agentName)}/durable-session/`;
+}
+
+/**
+ * Adapt a storage backend into the ledger's KV interface. Throws when
+ * the backend does not implement the `cas` group, or omits `get` /
+ * `delete` (optional for resident-only sinks, but the ledger reads and
+ * sweeps mailbox payload blobs through the same store) — the caller
+ * turns that into the fail-fast startup error for `serving: "ledger"`.
+ * Every call carries a `reason: "coordination"` {@link StorageContext}.
  */
 export function storageCasKv(
   config: StorageConfig,
@@ -49,7 +71,23 @@ export function storageCasKv(
       "storageCasKv: the storage backend does not implement the cas group (conditional writes)"
     );
   }
+  const get = config.get;
+  const remove = config.delete;
+  if (get === undefined || remove === undefined) {
+    throw new Error(
+      "storageCasKv: the storage backend must implement get and delete (the session ledger reads and sweeps payload blobs through the same store)"
+    );
+  }
   return {
+    async get(key): Promise<JsonValue | undefined> {
+      return (await get(key, ctx)) ?? undefined;
+    },
+    async put(key, value): Promise<void> {
+      await config.put(key, value, ctx);
+    },
+    async delete(key): Promise<void> {
+      await remove(key, ctx);
+    },
     async getWithVersion(key) {
       return await cas.getWithVersion(key, ctx);
     },
@@ -59,37 +97,38 @@ export function storageCasKv(
     async putIfVersion(key, value, expectedVersion) {
       return await cas.putIfVersion(key, value, expectedVersion, ctx);
     },
+    async listKeys(prefix) {
+      return await cas.listKeys(prefix, ctx);
+    },
   };
 }
 
 /**
- * The one place the ledger's physical namespace is minted:
- * `agentkit/v1/<agent>/durable-session/` — the {@link STORAGE_KEY_ROOT}
- * conventions with the agent segment encoded like every other
- * caller-controlled segment. The ledger itself never sees this string;
- * it speaks bare `session/…` / `ledger/…` keys against a handle that
- * {@link namespacedKv} has already scoped.
- */
-export function ledgerKeyPrefix(agentName: string): string {
-  return `${STORAGE_KEY_ROOT}/${keySegment(agentName)}/durable-session/`;
-}
-
-/**
- * Scope a raw store handle under a namespace, prepending it to every
- * key on the way in. Applied exactly once, where the engine constructs
- * the ledger's store handle — the same conceptual boundary where
- * `host.kv` gets its agent scoping. Internal: not part of the public kv
- * interface, and callers (including the explicit `durableSessionStore`
- * override) always supply the raw store — they never write prefixes.
+ * Scope a raw store handle under a namespace: every key going in gets it
+ * prepended, and `listKeys` results come back with it **stripped**, so a
+ * caller that lists and then reads/deletes the returned keys stays fully
+ * prefix-free (the janitor scan and the orphan sweep do exactly that).
+ * Applied exactly once, where the engine constructs the ledger's store
+ * handle — the same conceptual boundary where `host.kv` gets its agent
+ * scoping. Internal: not part of the public kv interface, and callers
+ * (including the explicit `durableSessionStore` override) always supply
+ * the raw store — they never write prefixes.
  */
 export function namespacedKv(
   store: SessionLedgerKv,
   namespace: string
 ): SessionLedgerKv {
   return {
+    get: (key) => store.get(namespace + key),
+    put: (key, value) => store.put(namespace + key, value),
+    delete: (key) => store.delete(namespace + key),
     getWithVersion: (key) => store.getWithVersion(namespace + key),
     putIfAbsent: (key, value) => store.putIfAbsent(namespace + key, value),
     putIfVersion: (key, value, expectedVersion) =>
       store.putIfVersion(namespace + key, value, expectedVersion),
+    listKeys: async (prefix) => {
+      const keys = await store.listKeys(namespace + prefix);
+      return keys.map((key) => key.slice(namespace.length));
+    },
   };
 }