npm - @cursor/july - Versions diffs - 0.1.85 → 0.1.87 - Mend

@cursor/july 0.1.85 → 0.1.87

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (36) hide show

package/dist/channels/github/github-channel.d.ts +4 -0
package/dist/channels/github/github-channel.d.ts.map +1 -1
package/dist/channels/github/github-channel.js +18 -11
package/dist/channels/origin/origin-channel.d.ts +6 -0
package/dist/channels/origin/origin-channel.d.ts.map +1 -1
package/dist/channels/origin/origin-channel.js +24 -11
package/dist/channels/slack/dispatch.d.ts.map +1 -1
package/dist/channels/slack/dispatch.js +12 -2
package/dist/internal/continuation-identity.d.ts +10 -0
package/dist/internal/continuation-identity.d.ts.map +1 -1
package/dist/internal/continuation-identity.js +10 -0
package/dist/internal/handleAgentServeTrigger.d.ts +5 -0
package/dist/internal/handleAgentServeTrigger.d.ts.map +1 -1
package/dist/internal/handleAgentServeTrigger.js +11 -3
package/dist/internal/local-control-plane.d.ts +19 -0
package/dist/internal/local-control-plane.d.ts.map +1 -1
package/dist/internal/local-control-plane.js +17 -0
package/dist/internal/local-ingress.d.ts +35 -0
package/dist/internal/local-ingress.d.ts.map +1 -0
package/dist/internal/local-ingress.js +44 -0
package/dist/internal/server.d.ts.map +1 -1
package/dist/internal/server.js +138 -62
package/dist/playground/assets/{index-CMe7imuc.css → index-C0_5hOsf.css} +1 -1
package/dist/playground/index.html +2 -2
package/dist/types.d.ts +2 -2
package/package.json +1 -1
package/src/channels/github/github-channel.ts +18 -21
package/src/channels/origin/origin-channel.ts +26 -15
package/src/channels/slack/dispatch.ts +11 -7
package/src/internal/continuation-identity.ts +10 -0
package/src/internal/handleAgentServeTrigger.ts +31 -2
package/src/internal/local-control-plane.ts +33 -0
package/src/internal/local-ingress.ts +90 -0
package/src/internal/server.ts +181 -27
package/src/types.ts +2 -2
/package/dist/playground/assets/{index-JaFLlugp.js → index-Bqn91tW4.js} +0 -0

package/dist/playground/index.html CHANGED Viewed

@@ -8,8 +8,8 @@
     />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>agent-serve playground</title>
-    <script type="module" crossorigin src="./assets/index-JaFLlugp.js"></script>
-    <link rel="stylesheet" crossorigin href="./assets/index-CMe7imuc.css">
+    <script type="module" crossorigin src="./assets/index-Bqn91tW4.js"></script>
+    <link rel="stylesheet" crossorigin href="./assets/index-C0_5hOsf.css">
   </head>
   <body>
     <div id="root"></div>

package/dist/types.d.ts CHANGED Viewed

@@ -1463,8 +1463,8 @@ export interface SendMessageOptions {
      */
     continuationToken?: string;
     /**
-     * v2 mailbox stamp from the control plane (or the pack's builtin extract
-     * on local serve). Ignored on v1.
+     * v2 mailbox stamp from the control plane (hosted verified ingress or
+     * the local CP). Channel adapters do not extract. Ignored on v1.
      */
     mailboxContinuation?: MailboxContinuation;
     /**

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/july",
-  "version": "0.1.85",
+  "version": "0.1.87",
   "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": {

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

@@ -8,12 +8,11 @@ import {
   POST,
 } from "../../channels.js";
 import {
-  bindMailboxContinuationSend,
   continuationSource,
   normalizeIdentity,
-  stampMailboxContinuation,
 } from "../../internal/continuation-identity.js";
 import { isDevMode } from "../../internal/dev-mode.js";
+import { bindLocalIngressSend } from "../../internal/local-ingress.js";
 import type {
   AgentCloudOptions,
   ArtifactsApi,
@@ -477,6 +476,10 @@ function verifyWebhookSha256Signature(args: {
  * {@link handleAgentServeTrigger} fan-out. Signature verification is the
  * caller's responsibility (HTTP route verifies; internal fan-out skips).
  */
+/**
+ * Run authored GitHub hooks and `send()`. Does not extract a v2 mailbox —
+ * the local CP (or hosted verified ingress) stamps before this runs.
+ */
 export async function dispatchGitHubWebhook(input: {
   options: GitHubChannelOptions;
   eventName: string | null;
@@ -484,23 +487,7 @@ export async function dispatchGitHubWebhook(input: {
   deliveryId?: string;
   args: ChannelHandlerArgs;
 }): Promise<Response> {
-  const identity = normalizeIdentity(input.options.continuation, "github");
-  let args = input.args;
-  if (
-    continuationSource(identity, "github") === "control-plane" &&
-    input.eventName !== null
-  ) {
-    const mailbox = stampMailboxContinuation(
-      identity,
-      input.eventName,
-      input.payload
-    );
-    args = {
-      ...input.args,
-      send: bindMailboxContinuationSend(input.args.send, mailbox),
-    };
-  }
-  return dispatchGitHubWebhookInner({ ...input, args });
+  return dispatchGitHubWebhookInner(input);
 }
 async function dispatchGitHubWebhookInner(input: {
@@ -644,12 +631,22 @@ export async function handleGitHubWebhookRequest(input: {
     return Response.json({ ok: false, error: "invalid_json" }, { status: 400 });
   }
+  const eventName = input.request.headers.get("x-github-event");
+  const args =
+    eventName === null
+      ? input.args
+      : bindLocalIngressSend(input.args, {
+          identity: input.options.continuation,
+          kind: "github",
+          eventType: eventName,
+          payload,
+        });
   return dispatchGitHubWebhook({
     options: input.options,
-    eventName: input.request.headers.get("x-github-event"),
+    eventName,
     payload,
     deliveryId: input.request.headers.get("x-github-delivery") ?? undefined,
-    args: input.args,
+    args,
   });
 }

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

@@ -7,12 +7,11 @@ import {
   POST,
 } from "../../channels.js";
 import {
-  bindMailboxContinuationSend,
   continuationSource,
   normalizeIdentity,
-  stampMailboxContinuation,
 } from "../../internal/continuation-identity.js";
 import { isDevMode } from "../../internal/dev-mode.js";
+import { bindLocalIngressSend } from "../../internal/local-ingress.js";
 import type {
   AgentCloudOptions,
   AuthContext,
@@ -364,6 +363,20 @@ export function originContinuationKey(
   return `origin-pr:${ctx.repository.fullName}#${ctx.pullRequestNumber}`;
 }
+/** Payload shape local/hosted CP extract expects (`fullName` + number). */
+export function originIngressExtractPayload(
+  envelope: OriginWebhookEnvelope
+): unknown {
+  const parsed = parseOriginPullRequestEvent({ envelope });
+  if (parsed === null) {
+    return envelope.event.payload;
+  }
+  return {
+    pullRequest: { number: parsed.ctx.pullRequestNumber },
+    repository: { fullName: parsed.ctx.repository.fullName },
+  };
+}
 export function defaultOriginTitle(
   ctx: Pick<OriginEventContext, "repository" | "pullRequestNumber">
 ): string {
@@ -532,6 +545,10 @@ async function applyDispatch(input: {
  * {@link handleAgentServeTrigger} fan-out. Signature verification is the
  * caller's responsibility (HTTP route verifies; internal fan-out skips).
  */
+/**
+ * Run authored Origin hooks and `send()`. Does not extract a v2 mailbox —
+ * the local CP (or hosted verified ingress) stamps before this runs.
+ */
 export async function dispatchOriginWebhook(input: {
   options: OriginChannelOptions;
   envelope: OriginWebhookEnvelope;
@@ -545,18 +562,7 @@ export async function dispatchOriginWebhook(input: {
       { status: 400 }
     );
   }
-  const identity = normalizeIdentity(input.options.continuation, "origin");
-  let args = input.args;
-  if (continuationSource(identity, "origin") === "control-plane") {
-    const mailbox = stampMailboxContinuation(identity, eventType, {
-      pullRequest: { number: parsed.ctx.pullRequestNumber },
-      repository: { fullName: parsed.ctx.repository.fullName },
-    });
-    args = {
-      ...input.args,
-      send: bindMailboxContinuationSend(input.args.send, mailbox),
-    };
-  }
+  const args = input.args;
   const ctx = enrichEventContext({
     ctx: parsed.ctx,
     args,
@@ -711,7 +717,12 @@ export async function handleOriginWebhookRequest(input: {
   return dispatchOriginWebhook({
     options: input.options,
     envelope,
-    args: input.args,
+    args: bindLocalIngressSend(input.args, {
+      identity: input.options.continuation,
+      kind: "origin",
+      eventType: envelope.event.type,
+      payload: originIngressExtractPayload(envelope),
+    }),
   });
 }

package/src/channels/slack/dispatch.ts CHANGED Viewed

@@ -7,8 +7,8 @@ import {
   continuationSource,
   type MailboxContinuation,
   normalizeIdentity,
-  stampMailboxContinuation,
 } from "../../internal/continuation-identity.js";
+import { routeLocalIngressContinuation } from "../../internal/local-ingress.js";
 import type {
   ArtifactsApi,
   HostContext,
@@ -208,12 +208,16 @@ function slackSessionContinuation(
     const key = slackContinuationKey(channelId, threadTs);
     return { probeKey: key, sendPatch: { continuationToken: key } };
   }
-  const mailbox = stampMailboxContinuation(
-    normalizeIdentity(identity, "slack"),
-    "message",
-    { channelId, threadTs },
-    "slack"
-  );
+  const routed = routeLocalIngressContinuation({
+    identity: normalizeIdentity(identity, "slack"),
+    kind: "slack",
+    eventType: "message",
+    payload: { channelId, threadTs },
+  });
+  const mailbox = routed.mailboxContinuation;
+  if (mailbox === undefined) {
+    throw new Error("v2 slack ingress did not stamp a mailbox");
+  }
   return { probeKey: mailbox.key, sendPatch: { mailboxContinuation: mailbox } };
 }

package/src/internal/continuation-identity.ts CHANGED Viewed

@@ -361,6 +361,16 @@ export function extractContinuation(
   }
 }
+/**
+ * Extract primitive used by the control plane (hosted
+ * `routeVerifiedIngressContinuation` and local
+ * `routeLocalIngressContinuation`). Channel adapters must not call this.
+ */
+/**
+ * Extract primitive used by the control plane (hosted
+ * `routeVerifiedIngressContinuation` and local
+ * `routeLocalIngressContinuation`). Channel adapters must not call this.
+ */
 export function stampMailboxContinuation(
   identity: ContinuationIdentity,
   eventName: string,

package/src/internal/handleAgentServeTrigger.ts CHANGED Viewed

@@ -19,10 +19,15 @@ import type { GitHubChannelOptions } from "../channels/github/types.js";
 import {
   dispatchOriginWebhook,
   getOriginChannelOptions,
+  originIngressExtractPayload,
   parseOriginWebhookEnvelope,
 } from "../channels/origin/origin-channel.js";
 import type { OriginChannelOptions } from "../channels/origin/types.js";
 import type { ChannelHandlerArgs } from "../types.js";
+import {
+  bindLocalIngressSend,
+  type RouteLocalIngressContinuation,
+} from "./local-ingress.js";
 export interface AgentServeGitHubTriggerTarget {
   /** Agent mount slug (empty string in single-agent mode). */
@@ -40,6 +45,8 @@ export interface AgentServeGitHubTriggerEvent {
   eventName: string | null;
   deliveryId?: string;
   targets: AgentServeGitHubTriggerTarget[];
+  /** Local CP ingest. Defaults to {@link routeLocalIngressContinuation}. */
+  routeContinuation?: RouteLocalIngressContinuation;
 }
 export interface AgentServeOriginTriggerTarget {
@@ -53,6 +60,8 @@ export interface AgentServeOriginTriggerEvent {
   /** Origin envelope JSON (signature already verified by the caller). */
   bodyText: string;
   targets: AgentServeOriginTriggerTarget[];
+  /** Local CP ingest. Defaults to {@link routeLocalIngressContinuation}. */
+  routeContinuation?: RouteLocalIngressContinuation;
 }
 export type AgentServeTriggerEvent =
@@ -177,12 +186,24 @@ async function handleAgentServeGitHubTrigger(
   const targets: AgentServeTriggerTargetResult[] = [];
   for (const target of event.targets) {
+    const args =
+      event.eventName === null
+        ? target.args
+        : bindLocalIngressSend(target.args, {
+            identity: target.options.continuation,
+            kind: "github",
+            eventType: event.eventName,
+            payload,
+            ...(event.routeContinuation === undefined
+              ? {}
+              : { routeContinuation: event.routeContinuation }),
+          });
     const response = await dispatchGitHubWebhook({
       options: target.options,
       eventName: event.eventName,
       payload,
       deliveryId: event.deliveryId,
-      args: target.args,
+      args,
     });
     targets.push(await triggerTargetResult(target.slug, response));
   }
@@ -234,7 +255,15 @@ async function handleAgentServeOriginTrigger(
     const response = await dispatchOriginWebhook({
       options: target.options,
       envelope,
-      args: target.args,
+      args: bindLocalIngressSend(target.args, {
+        identity: target.options.continuation,
+        kind: "origin",
+        eventType: envelope.event.type,
+        payload: originIngressExtractPayload(envelope),
+        ...(event.routeContinuation === undefined
+          ? {}
+          : { routeContinuation: event.routeContinuation }),
+      }),
     });
     targets.push(await triggerTargetResult(target.slug, response));
   }

package/src/internal/local-control-plane.ts CHANGED Viewed

@@ -2,15 +2,37 @@
  * In-process control plane started with local `serve`. Owns schedule clocks
  * and reminder documents + clocks, then fires into the kit the same way the
  * Cursor backend does over HTTP when `--no-control-plane` is set.
+ *
+ * v2 ingest lives here: `routeContinuation` stamps the mailbox (July twin
+ * of hosted `routeVerifiedIngressContinuation`), and `attachScmEvents`
+ * owns the `/v0/scm-events` long poll. v1 keeps engine-side scm-events.
+ * Hosted `--no-control-plane` v2 skips that poll — the hosted CP delivers.
  */
 import { dirname, join } from "node:path";
 import { type CronExpression, parseCron } from "./cron.js";
+import {
+  type LocalIngressContinuation,
+  type RouteLocalIngressContinuationInput,
+  routeLocalIngressContinuation,
+} from "./local-ingress.js";
 import type { PlatformTimers } from "./platform-timers.js";
 import { MAX_TIMER_MS } from "./reminder-schedule.js";
 import { type ReminderRecord, ReminderStore } from "./reminder-store.js";
 export interface LocalControlPlane extends PlatformTimers {
+  /**
+   * Stamp a v2 mailbox from the channel selector + live payload. Same
+   * contract as hosted verified ingress. `/v1` is a no-op.
+   */
+  routeContinuation(
+    input: RouteLocalIngressContinuationInput
+  ): LocalIngressContinuation;
+  /**
+   * Take ownership of the v2 `/v0/scm-events` long poll. Starts the relay.
+   * v1 scm-events stay on the engine serve path.
+   */
+  attachScmEvents(relay: { start(): void; stop(): Promise<void> }): void;
   /** Arm persisted reminder clocks after the kit fire callback is live. */
   startClocks(): void;
   stop(): void;
@@ -40,6 +62,7 @@ export async function createLocalControlPlane(opts: {
   const reminders = new Map<string, ReminderRecord>();
   let scheduleTimer: NodeJS.Timeout | undefined;
   let lastFiredMinute = -1;
+  let scmRelay: { start(): void; stop(): Promise<void> } | undefined;
   if (store !== undefined) {
     for (const record of await store.list()) {
@@ -138,6 +161,12 @@ export async function createLocalControlPlane(opts: {
   }
   return {
+    routeContinuation: routeLocalIngressContinuation,
+    attachScmEvents(relay) {
+      scmRelay = relay;
+      relay.start();
+      logger("[agent-sdk] cursor-events: control-plane ingest started");
+    },
     async upsertSchedule(input) {
       schedules.set(input.name, parseCron(input.cron));
       armScheduleTicker();
@@ -183,6 +212,10 @@ export async function createLocalControlPlane(opts: {
       for (const id of [...reminderTimers.keys()]) {
         clearReminderTimer(id);
       }
+      if (scmRelay !== undefined) {
+        void scmRelay.stop();
+        scmRelay = undefined;
+      }
     },
   };
 }

package/src/internal/local-ingress.ts ADDED Viewed

@@ -0,0 +1,90 @@
+/**
+ * Local control-plane ingest for v2 continuation.
+ *
+ * Twin of backend `routeVerifiedIngressContinuation`. Hosted Cursor runs
+ * that copy after the webhook is verified. Self-hosted / `july serve`
+ * runs this copy on the in-process local CP before the channel adapter
+ * `send()`s. Channel adapters do not extract.
+ */
+import type { ChannelHandlerArgs } from "../types.js";
+import {
+  bindMailboxContinuationSend,
+  type ContinuationIdentity,
+  continuationSource,
+  type MailboxContinuation,
+  normalizeIdentity,
+  stampMailboxContinuation,
+} from "./continuation-identity.js";
+export type LocalIngressContinuation = {
+  explicitContinuationKey?: string;
+  mailboxContinuation?: MailboxContinuation;
+};
+export type RouteLocalIngressContinuation = (
+  input: RouteLocalIngressContinuationInput
+) => LocalIngressContinuation;
+export type RouteLocalIngressContinuationInput = {
+  identity?: ContinuationIdentity;
+  kind?: string;
+  eventType: string;
+  payload: unknown;
+  deterministicContinuationKey?: string;
+};
+/**
+ * Selector + live payload → mailbox stamp. `/v1` and omitted identity
+ * keep the caller-supplied deterministic key and do not stamp a mailbox.
+ */
+export function routeLocalIngressContinuation(
+  input: RouteLocalIngressContinuationInput
+): LocalIngressContinuation {
+  if (input.identity === undefined) {
+    return {
+      ...(input.deterministicContinuationKey === undefined
+        ? {}
+        : { explicitContinuationKey: input.deterministicContinuationKey }),
+    };
+  }
+  const identity = normalizeIdentity(input.identity, input.kind);
+  if (continuationSource(identity, input.kind) !== "control-plane") {
+    return {
+      ...(input.deterministicContinuationKey === undefined
+        ? {}
+        : { explicitContinuationKey: input.deterministicContinuationKey }),
+    };
+  }
+  const mailboxContinuation = stampMailboxContinuation(
+    identity,
+    input.eventType,
+    input.payload,
+    input.kind
+  );
+  if (mailboxContinuation.key.startsWith("cont:")) {
+    return {
+      explicitContinuationKey: mailboxContinuation.key,
+      mailboxContinuation,
+    };
+  }
+  return { mailboxContinuation };
+}
+/**
+ * Bind a CP mailbox stamp onto `args.send` so the channel adapter only
+ * calls `send()` — it does not extract. No-op for `/v1`.
+ */
+export function bindLocalIngressSend(
+  args: ChannelHandlerArgs,
+  input: RouteLocalIngressContinuationInput & {
+    routeContinuation?: RouteLocalIngressContinuation;
+  }
+): ChannelHandlerArgs {
+  const route = input.routeContinuation ?? routeLocalIngressContinuation;
+  const routed = route(input);
+  return {
+    ...args,
+    send: bindMailboxContinuationSend(args.send, routed.mailboxContinuation),
+  };
+}