npm - @cursor/july - Versions diffs - 0.1.4 → 0.1.5 - Mend

@cursor/july 0.1.4 → 0.1.5

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 (56) hide show

package/dist/docs/404.html +1 -1
package/dist/docs/ab.html +2 -2
package/dist/docs/assets/{app.DF-Yx4OP.js → app.DabPG-io.js} +1 -1
package/dist/docs/assets/chunks/@localSearchIndexroot.QwK5BtEH.js +1 -0
package/dist/docs/assets/chunks/{VPLocalSearchBox.DSeJSudL.js → VPLocalSearchBox.jmyr0bU0.js} +1 -1
package/dist/docs/assets/chunks/{theme.DZVLTXOC.js → theme.DysN9-VN.js} +2 -2
package/dist/docs/building-with-agents.html +2 -2
package/dist/docs/concepts.html +2 -2
package/dist/docs/deployment.html +2 -2
package/dist/docs/evals.html +2 -2
package/dist/docs/guides/agent-to-agent.html +2 -2
package/dist/docs/guides/cloud-runtime.html +2 -2
package/dist/docs/guides/github.html +2 -2
package/dist/docs/guides/human-in-the-loop.html +2 -2
package/dist/docs/guides/slack.html +2 -2
package/dist/docs/guides/webhooks.html +2 -2
package/dist/docs/hillclimbing.html +2 -2
package/dist/docs/index.html +2 -2
package/dist/docs/quickstart.html +2 -2
package/dist/docs/reference/agent-config.html +2 -2
package/dist/docs/reference/channels.html +2 -2
package/dist/docs/reference/cli.html +2 -2
package/dist/docs/reference/connections.html +2 -2
package/dist/docs/reference/hooks.html +2 -2
package/dist/docs/reference/http-api.html +2 -2
package/dist/docs/reference/instructions.html +2 -2
package/dist/docs/reference/playground.html +2 -2
package/dist/docs/reference/project-layout.html +2 -2
package/dist/docs/reference/schedules.html +2 -2
package/dist/docs/reference/sessions.html +2 -2
package/dist/docs/reference/skills.html +2 -2
package/dist/docs/reference/subagents.html +2 -2
package/dist/docs/reference/tools.html +2 -2
package/dist/docs/scaffolding-agents.html +2 -2
package/dist/docs/storage.html +2 -2
package/dist/docs/troubleshooting.html +2 -2
package/dist/internal/cli-deploy.d.ts.map +1 -1
package/dist/internal/cli-deploy.js +5 -2
package/dist/internal/cursor-event-relay.d.ts +4 -1
package/dist/internal/cursor-event-relay.d.ts.map +1 -1
package/dist/internal/cursor-event-relay.js +6 -0
package/dist/internal/cursor-relay-core.d.ts +36 -1
package/dist/internal/cursor-relay-core.d.ts.map +1 -1
package/dist/internal/cursor-relay-core.js +89 -8
package/dist/internal/cursor-slack-relay.d.ts +2 -2
package/dist/internal/cursor-slack-relay.d.ts.map +1 -1
package/dist/internal/cursor-slack-relay.js +4 -0
package/dist/playground/assets/{index-Ct_Usdm8.css → index-BEauYlII.css} +1 -1
package/dist/playground/assets/{index-Dsyb-Vaj.js → index-BtM0wEGg.js} +94 -94
package/dist/playground/index.html +2 -2
package/package.json +1 -1
package/src/internal/cli-deploy.ts +5 -2
package/src/internal/cursor-event-relay.ts +10 -1
package/src/internal/cursor-relay-core.ts +115 -9
package/src/internal/cursor-slack-relay.ts +6 -2
package/dist/docs/assets/chunks/@localSearchIndexroot.0XrheBv2.js +0 -1

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-Dsyb-Vaj.js"></script>
-    <link rel="stylesheet" crossorigin href="./assets/index-Ct_Usdm8.css">
+    <script type="module" crossorigin src="./assets/index-BtM0wEGg.js"></script>
+    <link rel="stylesheet" crossorigin href="./assets/index-BEauYlII.css">
   </head>
   <body>
     <div id="root"></div>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/july",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "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/internal/cli-deploy.ts CHANGED Viewed

@@ -674,7 +674,8 @@ async function deployOne(
       `  generation:  ${detail.generation}\n` +
       `  kind:        ${detail.deploymentKind}\n` +
       `  alias:       ${aliasUrl}\n` +
-      `  playground:  ${CLI} playground --prod --slug ${slug} --team ${ctx.teamId}\n`
+      `  playground:  ${aliasUrl}/playground (sign in with the alias token)\n` +
+      `               or: ${CLI} playground --prod --slug ${slug} --team ${ctx.teamId}\n`
   );
   return 0;
 }
@@ -795,6 +796,7 @@ export async function cmdDeploymentStatus(
     `  generation:  ${detail.generation}`,
     `  kind:        ${detail.deploymentKind}`,
     `  alias:       ${aliasUrl}`,
+    `  playground:  ${aliasUrl}/playground`,
   ];
   if (detail.gitRepoUrl !== null && detail.gitRepoUrl !== undefined) {
     lines.push(`  repo:        ${detail.gitRepoUrl} @ ${detail.gitRef ?? ""}`);
@@ -1285,7 +1287,8 @@ function aliasTokenBlock(aliasToken: string): string {
   return (
     `\n  Alias token (shown ONCE — save it now, it cannot be retrieved again):\n\n` +
     `    ${aliasToken}\n\n` +
-    `  Send it as the X-Agent-Alias-Token header on requests to the alias URL.\n` +
+    `  Send it as the X-Agent-Alias-Token header on requests to the alias URL,\n` +
+    `  or paste it into the hosted playground (<alias>/playground) sign-in gate.\n` +
     `  Lost tokens: \`${CLI} rotate-token <slug>\` mints a replacement.\n\n`
   );
 }

package/src/internal/cursor-event-relay.ts CHANGED Viewed

@@ -68,7 +68,10 @@ export interface CursorEventRelayOptions {
   repos: readonly string[];
   events: readonly string[];
   stateDir: string;
-  /** Called for each matching event; failures are logged, not retried. */
+  /**
+   * Called for each matching event; failures retry a bounded number of
+   * times, then log and skip.
+   */
   dispatch: (event: CursorScmEvent) => Promise<void>;
   logger: (line: string) => void;
   /** Test seam. Defaults to global fetch. */
@@ -213,6 +216,12 @@ export class CursorEventRelay {
           events: [...this.options.events],
         })),
       }),
+      // Empty subscriptions drop this consumer's registration on clean stop
+      // instead of leaving it to lapse by TTL.
+      buildDeregistrationBody: (consumerId) => ({
+        consumerId,
+        subscriptions: [],
+      }),
       applyRegistrationResponse: (json) => {
         const result = json as { repos?: SubscriptionStatus[] };
         const statuses = result.repos ?? [];

package/src/internal/cursor-relay-core.ts CHANGED Viewed

@@ -23,6 +23,11 @@ const DEFAULT_IDLE_POLL_DELAY_MS = 250;
 const MIN_BACKOFF_MS = 1_000;
 const MAX_BACKOFF_MS = 30_000;
 const AUTH_FAILURE_BACKOFF_MS = 60_000;
+/** Attempts per event before the offset advances past it. */
+const DISPATCH_ATTEMPTS = 3;
+const DISPATCH_RETRY_DELAYS_MS = [250, 1_000];
+/** Budget for the best-effort deregistration PUT during stop(). */
+const DEREGISTER_TIMEOUT_MS = 1_500;
 interface OffsetSnapshot {
   version: typeof OFFSET_SNAPSHOT_VERSION;
@@ -108,6 +113,14 @@ export interface RelayAdapter<TEvent extends { offset: string }> {
   readonly pollPath: string;
   /** The registration request body for this consumer id. */
   buildRegistrationBody(consumerId: string): unknown;
+  /**
+   * The empty-scope registration body used to deregister this consumer on a
+   * clean stop. When present, `stop()` best-effort PUTs it so the consumer's
+   * registration does not linger as a ghost until its server-side TTL (a
+   * ghost with this host's agent names makes name routing ambiguous for a
+   * redeployed sibling until it expires).
+   */
+  buildDeregistrationBody?(consumerId: string): unknown;
   /**
    * Apply the (ok) registration response: update the accepted-scope filter
    * and return the human-readable outcome lines to log. The core logs them
@@ -121,7 +134,10 @@ export interface RelayAdapter<TEvent extends { offset: string }> {
    * the offset but are not dispatched.
    */
   shouldDispatch(event: TEvent): boolean;
-  /** Handle one matching event. Failures are logged, not retried. */
+  /**
+   * Handle one matching event. Failures retry a bounded number of times
+   * ({@link DISPATCH_ATTEMPTS}), then log and skip.
+   */
   dispatch(event: TEvent): Promise<void>;
 }
@@ -147,6 +163,14 @@ export class CursorRelayCore<TEvent extends { offset: string }> {
   private consumerId = "";
   /** undefined until the first registration, so a clean first success logs. */
   private lastRegistrationLog: string | undefined;
+  /** Whether any registration succeeded (gates the stop-time deregister). */
+  private registeredOnce = false;
+  /**
+   * The in-flight heartbeat re-registration, if any. `stop()` awaits it
+   * before deregistering so a just-sent heartbeat cannot land after the
+   * deregistration PUT and resurrect the registration for a full TTL.
+   */
+  private heartbeatPromise: Promise<boolean> | undefined;
   constructor(private readonly options: CursorRelayCoreOptions<TEvent>) {
     this.offsetStore = new RelayOffsetStore(options.stateDir);
@@ -170,7 +194,7 @@ export class CursorRelayCore<TEvent extends { offset: string }> {
     const registered = await this.registerUntilSuccess();
     if (!registered) return;
     this.registerTimer = setInterval(() => {
-      void this.registerOnce();
+      this.heartbeatPromise = this.registerOnce();
     }, DEFAULT_REGISTER_INTERVAL_MS);
     this.registerTimer.unref?.();
     await this.consumeLoop();
@@ -229,6 +253,56 @@ export class CursorRelayCore<TEvent extends { offset: string }> {
         timer.unref?.();
       }),
     ]);
+    // A heartbeat re-registration may be in flight (its fetch was just
+    // aborted); let it settle so it cannot land after the deregistration.
+    await this.heartbeatPromise?.catch(() => {});
+    await this.deregister();
+  }
+  /**
+   * Best-effort empty-scope PUT on clean stop, so this consumer's
+   * registration is dropped immediately instead of lingering until its
+   * server-side TTL. A ghost registration keeps this host's agent names
+   * live and makes name routing ambiguous for a redeployed sibling with a
+   * fresh consumer id. Failures only log — the TTL still cleans up.
+   */
+  private async deregister(): Promise<void> {
+    const adapter = this.options.adapter;
+    if (
+      adapter.buildDeregistrationBody === undefined ||
+      !this.registeredOnce ||
+      this.consumerId === ""
+    ) {
+      return;
+    }
+    const url = `${this.options.baseUrl.replace(/\/+$/, "")}${adapter.subscribePath}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), DEREGISTER_TIMEOUT_MS);
+    timer.unref?.();
+    try {
+      const response = await this.fetchImpl(url, {
+        method: "PUT",
+        headers: {
+          authorization: `Bearer ${this.options.apiKey}`,
+          "content-type": "application/json",
+        },
+        body: JSON.stringify(adapter.buildDeregistrationBody(this.consumerId)),
+        signal: controller.signal,
+      });
+      if (response.ok) {
+        this.log("deregistered on shutdown");
+      } else {
+        this.log(
+          `deregistration failed: ${response.status} (registration lapses by TTL)`
+        );
+      }
+    } catch (error) {
+      this.log(
+        `deregistration failed: ${describeRelayError(error)} (registration lapses by TTL)`
+      );
+    } finally {
+      clearTimeout(timer);
+    }
   }
   private log(line: string): void {
@@ -291,6 +365,7 @@ export class CursorRelayCore<TEvent extends { offset: string }> {
       this.logRegistrationOutcome(
         this.options.adapter.applyRegistrationResponse(json)
       );
+      this.registeredOnce = true;
       return true;
     } catch (error) {
       if (this.isAbort(error)) return false;
@@ -373,13 +448,7 @@ export class CursorRelayCore<TEvent extends { offset: string }> {
           // on replay after a crash between dispatch and save).
           if (compareStreamOffsets(event.offset, offset) <= 0) continue;
           if (this.options.adapter.shouldDispatch(event)) {
-            try {
-              await this.options.adapter.dispatch(event);
-            } catch (error) {
-              this.log(
-                `dispatch failed at offset ${event.offset}: ${describeRelayError(error)}`
-              );
-            }
+            await this.dispatchWithRetry(event);
           }
           offset = event.offset;
         }
@@ -403,6 +472,43 @@ export class CursorRelayCore<TEvent extends { offset: string }> {
     }
   }
+  /**
+   * Dispatch one event with a small bounded retry before the offset advances
+   * past it. Transient local failures (e.g. a connection reset while POSTing
+   * to the channel) used to drop the event outright; a poison event still
+   * only costs {@link DISPATCH_ATTEMPTS} tries and is then skipped, keeping
+   * at-least-once semantics without a retry loop.
+   */
+  private async dispatchWithRetry(event: TEvent): Promise<void> {
+    for (let attempt = 1; attempt <= DISPATCH_ATTEMPTS; attempt++) {
+      if (attempt > 1 && !this.running) {
+        this.log(
+          `dispatch abandoned at offset ${event.offset}: relay stopping`
+        );
+        return;
+      }
+      try {
+        await this.options.adapter.dispatch(event);
+        return;
+      } catch (error) {
+        if (attempt === DISPATCH_ATTEMPTS) {
+          this.log(
+            `dispatch failed at offset ${event.offset} after ${attempt} attempts: ${describeRelayError(error)}`
+          );
+          return;
+        }
+        this.log(
+          `dispatch attempt ${attempt} failed at offset ${event.offset}: ${describeRelayError(error)}; retrying`
+        );
+        await this.sleep(
+          DISPATCH_RETRY_DELAYS_MS[
+            Math.min(attempt - 1, DISPATCH_RETRY_DELAYS_MS.length - 1)
+          ]
+        );
+      }
+    }
+  }
   /** Log the failure, sleep, and return the backoff for the NEXT failure. */
   private async backoffAfterHttpFailure(
     response: Response,

package/src/internal/cursor-slack-relay.ts CHANGED Viewed

@@ -44,8 +44,8 @@ export interface CursorSlackRelayOptions {
   agents: readonly CursorSlackAgentRegistration[];
   stateDir: string;
   /**
-   * Called for each event addressed to this consumer's agents; failures are
-   * logged, not retried.
+   * Called for each event addressed to this consumer's agents; failures
+   * retry a bounded number of times, then log and skip.
    */
   dispatch: (envelope: CursorSlackRelayEvent) => Promise<void>;
   logger: (line: string) => void;
@@ -163,6 +163,10 @@ export class CursorSlackRelay {
           })),
         };
       },
+      // Empty agents drop this consumer's registration on clean stop, so a
+      // redeployed sibling's identical agent names never tie with this
+      // host's ghost until the server-side TTL lapses.
+      buildDeregistrationBody: (consumerId) => ({ consumerId, agents: [] }),
       applyRegistrationResponse: (json) => {
         const result = json as RegistrationResponse;
         const agentStatuses = result.agents ?? [];