@cursor/july 0.1.105 → 0.1.107

package/src/internal/deploy-manifest.ts

@@ -47,7 +47,7 @@ import {
   projectInfo,
   runtimeArchitectureCompatibilityError,
 } from "./discovery.js";
-import { packageVersion } from "./distribution.js";
+import { packageGitSha, packageVersion } from "./distribution.js";
 
 export const DEPLOY_MANIFEST_VERSION: 1 = 1;
 
@@ -62,6 +62,10 @@ const agentDeployManifestV1Schema = z.object({
   manifestVersion: z.literal(DEPLOY_MANIFEST_VERSION),
   generatedAtMs: z.number().int().nonnegative(),
   cliVersion: z.string().min(1),
+  cliGitSha: z
+    .string()
+    .regex(/^[0-9a-f]{40,64}$/)
+    .optional(),
   declarations: z.object({
     egressDomains: z.array(z.string().min(1)).max(64),
     publicRoutePaths: z.array(z.string().min(1)).max(64),
@@ -115,6 +119,8 @@ export interface AgentDeployManifestV1 {
   generatedAtMs: number;
   /** `@cursor/july` version that produced the manifest. */
   cliVersion: string;
+  /** Git commit for a checkout-built `@cursor/july`; absent for npm builds. */
+  cliGitSha?: string;
   declarations: AgentDeployManifestDeclarations;
   /**
    * Full `projectInfo` payload (see `GET /v1/info`). Opaque to the wire
@@ -129,7 +135,7 @@ export interface AgentDeployManifestV1 {
  */
 export function buildAgentDeployManifest(
   project: AgentProject,
-  options?: { nowMs?: number; cliVersion?: string }
+  options?: { nowMs?: number; cliVersion?: string; cliGitSha?: string }
 ): AgentDeployManifestV1 {
   const runtimeArchitectureError = runtimeArchitectureCompatibilityError(
     project.agent
@@ -167,20 +173,19 @@ export function buildAgentDeployManifest(
     manifestVersion: DEPLOY_MANIFEST_VERSION,
     generatedAtMs: options?.nowMs ?? Date.now(),
     cliVersion: options?.cliVersion ?? packageVersion(),
+    cliGitSha: options?.cliGitSha ?? packageGitSha(),
     declarations: {
       egressDomains: [...(project.agent.hosting?.egressDomains ?? [])],
       publicRoutePaths,
-      // v2 ignores authored storage; deploy manifests describe
-      // Cursor-hosted deployments, where framework-storage-selection.ts
-      // injects the Cursor-hosted mirror.
+      // Deploy manifests describe Cursor-hosted deployments. When the agent
+      // authors no storage, framework-storage-selection.ts injects the
+      // platform Cursor-hosted mirror for both v1 and v2.
       frameworkStorage:
-        project.agent.architecture === "v2"
+        project.storage === undefined
           ? "cursor-hosted"
-          : project.storage === undefined
-            ? "none"
-            : isCursorHostedStorage(project.storage)
-              ? "cursor-hosted"
-              : "other",
+          : isCursorHostedStorage(project.storage)
+            ? "cursor-hosted"
+            : "other",
       ...(project.agent.architecture === undefined
         ? {}
         : { architecture: project.agent.architecture }),

package/src/internal/discovery/agent.ts

@@ -372,6 +372,7 @@ export async function warnUnknownSlots(
     "subagents",
     "channels",
     "schedules",
+    "reminders",
     "hooks",
     "ab",
     "sandbox",

package/src/internal/discovery/info.ts

@@ -151,6 +151,12 @@ export function projectInfo(project: AgentProject): AgentProjectInfo {
       cron: schedule.cron,
       kind: schedule.kind,
     })),
+    reminders:
+      (project.reminders ?? []).length === 0
+        ? undefined
+        : (project.reminders ?? []).map((reminder) => ({
+            name: reminder.name,
+          })),
     hooks: project.hooks.map((hook) => hook.name),
     abs: project.abs.map((experiment) => experiment.name),
     ...(project.abConfig === undefined && project.abs.length === 0

package/src/internal/discovery/modules.ts

@@ -9,10 +9,7 @@ import { type DiscoveryContext, displayPath, errorMessage } from "./context.js";
 import { isDirectory, isModuleFile, moduleStem, sortedEntries } from "./fs.js";
 import { validateName } from "./names.js";
 
-type ImportableKind = Exclude<
-  DefinitionKind,
-  "instructions" | "eval" | "reminder"
->;
+type ImportableKind = Exclude<DefinitionKind, "instructions" | "eval">;
 
 /** The module files of a slot directory whose filenames are valid names. */
 export async function moduleEntries(
@@ -104,6 +101,7 @@ const DEFINE_HELPER_NAME: Record<ImportableKind, string> = {
   channel: "defineChannel",
   "http-channel": "httpChannel",
   schedule: "defineSchedule",
+  reminder: "defineReminder",
   hook: "defineHook",
   ab: "defineAB",
   storage: "defineStorage",

package/src/internal/discovery/project.ts

@@ -31,6 +31,7 @@ import {
 } from "./fs.js";
 import { loadHooks } from "./hooks.js";
 import { NAME_PATTERN } from "./names.js";
+import { loadReminders } from "./reminders.js";
 import { loadSchedules } from "./schedules.js";
 import {
   appendArtifactTool,
@@ -236,6 +237,7 @@ export async function loadAgentProject(
   }
   const schedules = await loadSchedules(ctx, join(agentDir, "schedules"));
   schedules.push(...projectSlots.schedules);
+  const reminders = await loadReminders(ctx, join(agentDir, "reminders"));
   const hooks = await loadHooks(ctx, join(agentDir, "hooks"));
   hooks.push(...projectSlots.hooks);
   const abs = await loadABs(ctx, agentDir);
@@ -291,6 +293,7 @@ export async function loadAgentProject(
     httpChannel: resolvedHttpChannel,
     channels,
     schedules,
+    reminders,
     hooks,
     abs,
     abConfig,

package/src/internal/discovery/reminders.ts

@@ -0,0 +1,65 @@
+/**
+ * `agent/reminders/*.ts`: named durable reminder fire handlers.
+ */
+
+import { basename, extname, relative } from "node:path";
+import type { DiscoveredReminder, ReminderDefinition } from "../../types.js";
+import { getDefinitionKind } from "../brand.js";
+import { type DiscoveryContext, displayPath } from "./context.js";
+import { isDirectory, isModuleFile, toPosix, walkFiles } from "./fs.js";
+import { importDefault } from "./modules.js";
+import { NAME_PATTERN } from "./names.js";
+
+export async function loadReminders(
+  ctx: DiscoveryContext,
+  remindersDir: string,
+  onDisable?: (name: string, path: string) => void
+): Promise<DiscoveredReminder[]> {
+  if (!(await isDirectory(remindersDir))) {
+    return [];
+  }
+  const reminders: DiscoveredReminder[] = [];
+  for (const filePath of await walkFiles(remindersDir)) {
+    const rel = toPosix(relative(remindersDir, filePath));
+    if (!isModuleFile(basename(filePath))) {
+      continue;
+    }
+    const name = rel.slice(0, -extname(rel).length);
+    if (!NAME_PATTERN.test(name) || name.includes("__")) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, filePath),
+        message: name.includes("__")
+          ? `Reminder name "${name}" may not contain "__"; it is reserved for extension contributions (\`<ns>__<name>\`).`
+          : `Reminder name "${name}" must match ${NAME_PATTERN}.`,
+      });
+      continue;
+    }
+    const definition = await importDefault(
+      ctx,
+      filePath,
+      onDisable === undefined ? "reminder" : ["reminder", "disabled"]
+    );
+    if (definition === undefined) {
+      continue;
+    }
+    if (getDefinitionKind(definition) === "disabled") {
+      onDisable?.(name, filePath);
+      continue;
+    }
+    const reminder = definition as ReminderDefinition;
+    if (typeof reminder.run !== "function") {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, filePath),
+        message: "Reminder handlers require a `run` function.",
+      });
+      continue;
+    }
+    reminders.push({
+      name,
+      definition: reminder,
+    });
+  }
+  return reminders;
+}

package/src/internal/discovery/subagent.ts

@@ -121,6 +121,7 @@ async function warnUnsupportedSubagentSlots(
     ["subagents", "nested subagents"],
     ["channels", "channels"],
     ["schedules", "schedules"],
+    ["reminders", "reminders"],
     ["hooks", "hooks"],
     ["sandbox", "sandbox files"],
   ] as const;

package/src/internal/distribution.ts

@@ -13,6 +13,8 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 
 /** Published npm package name (pre-launch codename for Agent SDK). */
 export const PACKAGE_NAME = "@cursor/july";
+const HOSTED_WORKTREE_SHA_FILENAME = ".cursor-hosted-worktree-sha";
+const GIT_COMMIT_SHA_RE = /^[0-9a-f]{40,64}$/;
 
 /**
  * Bracketed product tag for stderr / ServeOptions.logger lines
@@ -59,6 +61,24 @@ export function packageVersion(): string {
   return packageManifest().version;
 }
 
+/**
+ * Git commit of a checkout-built framework distribution. Published npm
+ * packages do not carry this marker and return undefined.
+ */
+export function packageGitSha(): string | undefined {
+  try {
+    const sha = readFileSync(
+      join(packageRootDir(), "dist", HOSTED_WORKTREE_SHA_FILENAME),
+      "utf8"
+    )
+      .trim()
+      .toLowerCase();
+    return GIT_COMMIT_SHA_RE.test(sha) ? sha : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /** Facts `agent-sdk version` / `--version` print. */
 export interface CliVersionInfo {
   /** Published npm name (`@cursor/july`). */

package/src/internal/framework-storage-selection.ts

@@ -13,7 +13,10 @@
  * That selection is a hosting-mode question, not an authoring question.
  * Architecture v2 moves it here: `agent/storage.ts` is rejected at
  * discovery (error diagnostic, so serve and deploy fail early), and the
- * platform picks the default —
+ * platform picks the default. Architecture v1 with no authored file now
+ * uses the same hosted-vs-self-hosted split, so deleting `agent/storage.ts`
+ * (required to deploy the same tree onto v2) does not drop the Cursor-hosted
+ * session mirror on a still-v1 pod.
  *
  * - **Cursor-managed hosting** (the deployment-generation environment
  *   variable is set, same signal that registers `GET /v1/manifest`):
@@ -33,8 +36,10 @@
  * - **Self-hosted**: no mirror. `--state-root` is the durable copy, which
  *   is correct when the operator owns the disk.
  *
- * v1 keeps the authored definition (or nothing) so existing deployments are
- * untouched while they run.
+ * v1 still honors an authored `agent/storage.ts` when present. Hosted v1
+ * pods with no authored file get the Cursor-hosted lazy mirror (gated on
+ * `AGENT_SERVE_DEPLOYMENT_ID`, the same signal the previous authored sinks
+ * used). Self-hosted v1 with no authored file stays disk-only.
  *
  * Local disk is not part of this decision. `<stateRoot>/sessions/<id>/`
  * already holds `session.json` and `events.ndjson` unconditionally, through
@@ -44,6 +49,10 @@
 
 import { cursorHostedFiles } from "../files-backends/cursor-hosted.js";
 import { defineStorage, type StorageDefinition } from "../storage.js";
+import {
+  AGENT_SERVE_DEPLOYMENT_ID_ENV_VAR,
+  cursorHostedStorage,
+} from "../storage-backends/cursor-hosted.js";
 import { cursorHostedStorageV2 } from "../storage-backends/cursor-hosted-v2.js";
 import type { AgentArchitecture } from "../types.js";
 import { resolveApiKeySync } from "./cursor/credentials.js";
@@ -54,6 +63,13 @@ import {
 } from "./framework-file-storage.js";
 import { resolveAgentV2Hosting } from "./v2-hosting.js";
 
+/**
+ * Hosted v2 event-chunk flush debounce. Matches the session view's live poll
+ * cadence; a streaming turn still caps each chunk at the coordinator's batch
+ * limit, so a long turn writes a few dozen chunks rather than one per event.
+ */
+export const HOSTED_V2_EVENT_FLUSH_DEBOUNCE_MS = 2_000;
+
 export interface FrameworkStorageSelectionInput {
   /** `agent/storage.ts`, when the author wrote one (v1 only: discovery rejects it on v2). */
   readonly authored: StorageDefinition | undefined;
@@ -73,8 +89,21 @@ export function selectFrameworkStorageDefinition(
   input: FrameworkStorageSelectionInput
 ): StorageDefinition | undefined {
   if (input.architecture !== "v2") {
-    // v1: the author decides, or there is no mirror.
-    return input.authored;
+    if (input.authored !== undefined) {
+      return input.authored;
+    }
+    const env = input.env ?? process.env;
+    if ((env[AGENT_SERVE_DEPLOYMENT_ID_ENV_VAR] ?? "").trim() !== "") {
+      // Hosted v1 pod with no authored sink: keep the Cursor-hosted
+      // mirror (lazy restore) so agents can delete `agent/storage.ts`
+      // without losing durability while they still run architecture v1.
+      return defineStorage({
+        name: "cursor-hosted (lazy restore)",
+        policy: { restore: "off" },
+        ...cursorHostedStorage(),
+      });
+    }
+    return undefined;
   }
   if (input.authored !== undefined) {
     // Discovery rejects agent/storage.ts on v2 before an engine is built;
@@ -97,7 +126,15 @@ export function selectFrameworkStorageDefinition(
   // backend it is per-key HTTP round trips before the listener even
   // comes up). Follow-ups restore lazily by continuation or session id;
   // GET /v1/sessions lists from the sink either way.
-  const policy = { restore: "off" } as const;
+  //
+  // Events flush on a quiet-period debounce rather than only at turn end so
+  // the read-only session view and dashboard trace (which have no resident
+  // engine to ask) see steps mid-turn. The turn-end record still lands
+  // before the execution reply: drainSessionDurability forces the flush.
+  const policy = {
+    restore: "off",
+    debounceMs: HOSTED_V2_EVENT_FLUSH_DEBOUNCE_MS,
+  } as const;
   // Full chain (env → bind file → stored login): frozen engines listen
   // unsigned and bind store ids + CURSOR_API_KEY at task time, after this
   // definition is constructed.

package/src/internal/guest-network.ts

@@ -19,6 +19,8 @@
  * with that message instead of throwing.
  */
 
+import { HOSTED_GUEST_RETRY_TRANSIENT } from "./hosted-delivery-protocol.js";
+
 export const GUEST_NETWORK_UNAVAILABLE = "guest_network_unavailable";
 export const GUEST_CONNECT_STALLED = "guest_connect_stalled";
 
@@ -369,6 +371,7 @@ export async function guestNetworkReadinessResponse(
       JSON.stringify({
         ok: false,
         error: GUEST_NETWORK_UNAVAILABLE,
+        retry: HOSTED_GUEST_RETRY_TRANSIENT,
         message: error.message,
         waitMs: error.waitMs,
         probeAttempts: error.probeAttempts,

package/src/internal/hosted-delivery-protocol.ts

@@ -2,6 +2,43 @@ export const HOSTED_DELIVERY_PROTOCOL_VERSION = 2;
 export const HOSTED_DELIVERY_HEADER = "x-agent-sdk-hosted-delivery";
 export const HOSTED_ADMISSION_PATH = "/v1/internal/hosted-admission";
 export const HOSTED_EXECUTION_PATH = "/v1/internal/hosted-execution";
+export const HOSTED_GUEST_RETRY_TRANSIENT = "transient";
+export const HOSTED_GUEST_RETRY_TERMINAL = "terminal";
+
+export type HostedGuestRetryDisposition =
+  | typeof HOSTED_GUEST_RETRY_TRANSIENT
+  | typeof HOSTED_GUEST_RETRY_TERMINAL;
+
+export type HostedGuestError = {
+  ok: false;
+  error: string;
+  retry: HostedGuestRetryDisposition;
+  message?: string;
+  turnStatus?: string;
+};
+
+/**
+ * Hosted delivery is the only HTTP surface whose failures drive Temporal
+ * retries. Keep its retry disposition explicit instead of making the shared
+ * HTTP error helper guess from a status code.
+ */
+export function hostedGuestErrorResponse(input: {
+  status: number;
+  error: string;
+  retry: HostedGuestRetryDisposition;
+  message?: string;
+  turnStatus?: string;
+}): Response {
+  const body: HostedGuestError = {
+    ok: false,
+    error: input.error,
+    retry: input.retry,
+    message: input.message,
+    turnStatus: input.turnStatus,
+  };
+  return Response.json(body, { status: input.status });
+}
+
 /**
  * Filename under the serve `--state-root` (not the per-slug SessionEngine
  * dir). Hosted freeze uses `/workspace/.agent-serve`; the Temporal host
@@ -10,6 +47,25 @@ export const HOSTED_EXECUTION_PATH = "/v1/internal/hosted-execution";
  */
 export const HOSTED_EXECUTION_DIAG_FILENAME = "hosted-execution.json";
 
+/**
+ * Reserved hosted-admission `channelKind` for durable reminder fires.
+ * Bypasses authored channel admission and invokes ReminderRunner.dispatch.
+ * Backend builds envelopes with this constant + {@link HOSTED_REMINDER_EVENT_TYPE}.
+ */
+export const HOSTED_REMINDER_CHANNEL_KIND = "agent-sdk:reminder";
+
+/**
+ * Reserved hosted-admission `eventType` for durable reminder fires.
+ * Payload is {@link HostedReminderFirePayload}.
+ */
+export const HOSTED_REMINDER_EVENT_TYPE = "agent-sdk.reminder/fire";
+
+/** Compact reminder-fire payload on the reserved hosted-admission path. */
+export type HostedReminderFirePayload = {
+  reminderId: string;
+  fireCount: number;
+};
+
 export type HostedAdmissionManagedAutomation = {
   automationUuid: string;
   mcpServerNames: string[];
@@ -171,6 +227,46 @@ export function parseHostedExecution(
   return body as HostedExecution;
 }
 
+/**
+ * True when the admission envelope is the reserved internal reminder fire
+ * path (not an authored channel event).
+ */
+export function isHostedReminderAdmission(delivery: HostedAdmission): boolean {
+  return (
+    delivery.channelKind === HOSTED_REMINDER_CHANNEL_KIND &&
+    delivery.eventType === HOSTED_REMINDER_EVENT_TYPE
+  );
+}
+
+/**
+ * Parse `{ reminderId, fireCount }` from a reserved reminder admission
+ * payload. Rejects unknown keys and non-integer fireCount.
+ */
+export function parseHostedReminderFirePayload(
+  value: unknown
+): HostedReminderFirePayload | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return undefined;
+  }
+  const body = value as Record<string, unknown>;
+  const keys = Object.keys(body);
+  if (
+    keys.length !== 2 ||
+    !Object.hasOwn(body, "reminderId") ||
+    !Object.hasOwn(body, "fireCount") ||
+    !boundedString(body.reminderId, 128) ||
+    typeof body.fireCount !== "number" ||
+    !Number.isInteger(body.fireCount) ||
+    body.fireCount < 0
+  ) {
+    return undefined;
+  }
+  return {
+    reminderId: body.reminderId,
+    fireCount: body.fireCount,
+  };
+}
+
 export function parseHostedAdmissionOutcome(
   value: unknown
 ): HostedAdmissionOutcome | undefined {