@cursor/july 0.1.43 → 0.1.46

package/docs/storage.md

@@ -213,12 +213,29 @@ server).
 
 Conditional writes are the substrate for the session ledger, which
 ships behind `defineAgent({ serving: "ledger" })`: session identity,
-one-writer-per-session leases with generation fencing, and a fenced
-commit sequence, coordinated through the agent's storage backend by
-default (its `cas` group) or an explicit `durableSessionStore`
-override. The ledger has **no durable inbox** — an event arriving while
-a session's lease is held waits in-process on the delivering pod, so
-crash durability matches resident serving; what ledger mode adds is
-cross-pod mutual exclusion, zombie fencing, and the committed head
-sequence. A backend that implements `cas` needs no storage migration to
-adopt it.
+one-writer-per-session leases with generation fencing, a fenced commit
+sequence, and a **durable inbox**. A ledger-mode delivery parks its
+event in the session mailbox first — the source ack point moves after
+that write — then tries the lease: if another holder is serving the
+session, the delivery walks away and the holder's commit drains the
+parked event in a follow-up turn under the same lease. Sessions whose
+holder died with events pending are recovered by a janitor loop that
+scans ledgers by prefix, which is why ledger mode requires the full
+`cas` group **including `listKeys`**: the janitor scan and the orphan
+sweep are prefix scans, and mailbox payload blobs go through the
+backend's plain `get`/`put`/`delete`. Coordination runs through the
+agent's storage backend by default or an explicit `durableSessionStore`
+override. Either way you supply the **raw** store: the engine
+namespaces every ledger key under
+`agentkit/v1/{agent}/durable-session/` itself, at the same boundary
+where `host.kv` gets its agent scoping — a self-hoster never writes
+prefixes. A backend that implements `cas` needs no storage migration to
+adopt this.
+
+One sharp edge: the `cas` group and the plain methods must be backed by
+the **same durable store**. Pairing a real plain backend with
+`memoryCasTable()` (or any process-local `cas` stand-in) and
+`serving: "ledger"` silently voids ack-after-durable — the mailbox
+blobs persist but the leases, heads, and pending indexes evaporate on
+restart, so acked events are never redelivered. `memoryCasTable()` is
+for test fixtures and inert sinks only.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/july",
-  "version": "0.1.43",
+  "version": "0.1.46",
   "description": "(early alpha) Filesystem-first framework for defining Cursor agents as markdown and TypeScript and serving them over channels with the Cursor SDK.",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
@@ -215,7 +215,7 @@
     "node": ">=22.13"
   },
   "dependencies": {
-    "@cursor/sdk": "1.0.26",
+    "@cursor/sdk": "1.0.27",
     "@modelcontextprotocol/sdk": "1.25.1",
     "@octokit/auth-app": "^7.2.0",
     "@octokit/rest": "^21.1.1",

package/skills/otel/SKILL.md

@@ -2,8 +2,8 @@
 name: agentkit-otel
 description: >-
   Wire OpenTelemetry export for an Agent SDK agent (defineOtel, OTLP env,
-  traces/metrics/logs). Use when adding observability, Datadog/Grafana/OTLP
-  export, or session/turn/tool tracing.
+  traces/metrics/logs, ctx.host.otel). Use when adding observability,
+  Datadog/Grafana/OTLP export, session/turn/tool tracing, or custom metrics.
 ---
 
 # Agent SDK OpenTelemetry (`defineOtel`)
@@ -61,6 +61,24 @@ Precedence: `serve({ otel })` over `agent/otel.ts` over env.
 Prompt text, tool payloads, and failure text stay off the wire unless
 those flags are set.
 
+## Custom metrics (`ctx.host.otel`)
+
+Always present. `increment` / `record` no-op without a meter.
+`setAttributes` still tags the open session when a collector is
+attached. Prefix names with team or agent. No custom spans. Reserved
+metric names: `cursor.token.usage`, `cursor.tool.calls`,
+`cursor.cost.usage`, `agent_sdk.session.count`,
+`agent_sdk.turn.count`, `agent_sdk.subagent.count`,
+`agent_sdk.http.duration`. Reserved attributes:
+`cursor.conversation.id`, `agent_sdk.agent`, `agent_sdk.turn_id`,
+`agent_sdk.framework`.
+
+```ts
+ctx.host.otel.setAttributes({ "abc.ticket_id": "INC-123" });
+ctx.host.otel.increment("abc.ticket.resolved");
+ctx.host.otel.record("abc.approval.duration_ms", 1420);
+```
+
 ## Attributes worth joining on
 
 - `cursor.conversation.id` (session id)

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,
@@ -137,6 +138,12 @@ const githubPullRequestPayloadSchema: z.ZodType<GitHubPullRequestPayload> =
     }),
     sender: senderSchema,
     installation: installationSchema,
+    label: z
+      .object({
+        name: z.string().min(1),
+      })
+      .nullable()
+      .optional(),
   });
 
 /**
@@ -336,6 +343,9 @@ export function parseGitHubPullRequestEvent(args: {
     ...(payload.pull_request.user?.login === undefined
       ? {}
       : { authorLogin: payload.pull_request.user.login }),
+    ...(payload.label?.name === undefined
+      ? {}
+      : { label: { name: payload.label.name } }),
   };
   return { ctx, pullRequest };
 }
@@ -599,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

@@ -171,6 +171,8 @@ export type GitHubPullRequestPayload = {
     type?: string;
   } | null;
   installation?: { id?: number } | null;
+  /** Present on `labeled` / `unlabeled` pull_request deliveries. */
+  label?: { name: string } | null;
 };
 
 /** Normalized `pull_request` event handed to {@link GitHubPullRequestHook}. */
@@ -188,6 +190,8 @@ export interface GitHubPullRequestEvent {
   /** True when the PR was merged (from the webhook payload). */
   merged: boolean;
   authorLogin?: string;
+  /** Label added/removed on `labeled` / `unlabeled` actions. */
+  label?: { name: string };
 }
 
 /** Normalized `issues` event. */
@@ -448,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";
       };
@@ -500,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/channels.ts

@@ -383,3 +383,41 @@ export function allowAll(): AuthPolicy {
     principalType: "user",
   });
 }
+
+/**
+ * `Symbol.for` so the marker survives duplicated copies of the framework in
+ * one process (e.g. a monorepo agent resolving its own `@cursor/july`).
+ */
+const PUBLIC_ENDPOINT_MARKER = Symbol.for("agent-serve.public-endpoint");
+
+/**
+ * Like {@link allowAll}, but ALSO declares the channel publicly reachable on
+ * Cursor's managed hosting: `deploy` collects every channel whose auth chain
+ * contains this policy and the platform serves that channel's routes
+ * (`/v1/channels/<id>/…`) through the stable alias WITHOUT
+ * `X-Agent-Alias-Token`.
+ *
+ * Use it for webhook senders that cannot attach custom headers (Linear,
+ * Stripe, …) — **the handler must authenticate deliveries itself**, e.g. by
+ * verifying the provider's HMAC signature over the raw body. Everything
+ * else (sessions, MCP, playground) stays behind platform auth.
+ *
+ * Locally this admits every caller, exactly like `allowAll()`.
+ */
+export function publicEndpoint(): AuthPolicy {
+  const policy: AuthPolicy = () => ({
+    authenticator: "public-endpoint",
+    principalId: "anonymous",
+    principalType: "user",
+  });
+  return Object.assign(policy, { [PUBLIC_ENDPOINT_MARKER]: true as const });
+}
+
+/** True when a policy was created by {@link publicEndpoint}. */
+export function isPublicEndpointPolicy(policy: AuthPolicy): boolean {
+  return (
+    (policy as { [PUBLIC_ENDPOINT_MARKER]?: unknown })[
+      PUBLIC_ENDPOINT_MARKER
+    ] === true
+  );
+}

package/src/index.ts

@@ -48,6 +48,7 @@ export {
   PATCH,
   POST,
   PUT,
+  publicEndpoint,
 } from "./channels.js";
 export { defineConnection } from "./connections.js";
 export { defineHook } from "./hooks.js";
@@ -93,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/cli-ax.ts

@@ -23,7 +23,7 @@ import { lookupSessionContinuation, runChat } from "./chat-client.js";
 import { cmdLogin } from "./cli-cursor.js";
 import { resolveDeployAuth } from "./cli-deploy.js";
 import { resolveApiKey } from "./cursor/credentials.js";
-import { CLI_COMMAND_NAME } from "./distribution.js";
+import { CLI_COMMAND_NAME, PACKAGE_NAME } from "./distribution.js";
 import {
   discoverEvals,
   type EvalRunResult,
@@ -374,7 +374,7 @@ export async function cmdInit(options: AxCliOptions): Promise<number> {
   const cliOnPath = linked.ok;
   if (!cliOnPath) {
     process.stderr.write(
-      `\nCould not put ${CLI_COMMAND_NAME} on PATH (${linked.stderr.trim() || `exit ${linked.exitCode}`}). Next steps include a PATH export for node_modules/.bin.\n\n`
+      `\nCould not put ${CLI_COMMAND_NAME} on PATH (${linked.stderr.trim() || `exit ${linked.exitCode}`}). Next steps use npx ${PACKAGE_NAME} instead.\n\n`
     );
   } else {
     process.stdout.write("\n");