@cursor/july 0.1.75 → 0.1.78

package/src/channels/origin/origin-webhook.ts

@@ -32,8 +32,6 @@ const V1ED_TIMESTAMP_TOLERANCE_SECONDS = 5 * 60;
  */
 const MAX_V1ED_CANDIDATE_SIGNATURES = 1;
 
-const JWKS_CACHE_TTL_MS = 5 * 60 * 1000;
-
 export type OriginJwk = Record<string, unknown>;
 
 export type OriginWebhookHeaders = {
@@ -131,41 +129,115 @@ export function verifyV1edWebhookPayload(args: {
   return false;
 }
 
+function cacheControlDeltaMs(
+  cacheControl: string | null | undefined,
+  directive: "max-age" | "stale-if-error"
+): number | undefined {
+  if (cacheControl == null || cacheControl === "") {
+    return undefined;
+  }
+  const match = new RegExp(`(?:^|,)\\s*${directive}\\s*=\\s*(\\d+)`, "i").exec(
+    cacheControl
+  );
+  if (match === null) {
+    return undefined;
+  }
+  return Number(match[1]) * 1000;
+}
+
+/**
+ * RFC 9111 `max-age` (seconds → ms) from a Cache-Control header.
+ * Does not read `s-maxage`. Missing or unparsable → `undefined`.
+ */
+export function cacheControlMaxAgeMs(
+  cacheControl: string | null | undefined
+): number | undefined {
+  return cacheControlDeltaMs(cacheControl, "max-age");
+}
+
+/**
+ * RFC 5861 `stale-if-error` (seconds → ms). Missing → `undefined` (no
+ * fail-open after `max-age`).
+ */
+export function cacheControlStaleIfErrorMs(
+  cacheControl: string | null | undefined
+): number | undefined {
+  return cacheControlDeltaMs(cacheControl, "stale-if-error");
+}
+
 let jwksCache:
-  | { apiBaseUrl: string; keys: OriginJwk[]; fetchedAtMs: number }
+  | {
+      apiBaseUrl: string;
+      keys: OriginJwk[];
+      freshUntilMs: number;
+      staleUntilMs: number;
+    }
   | undefined;
 
-/** Fetch (and cache for 5 minutes) the Origin signing JWKS. */
+export type FetchOriginJwksOptions = {
+  /** Skip the in-memory hit and call `/v1/origin/keys` (used after a verify miss). */
+  force?: boolean;
+};
+
+/**
+ * Return the in-memory Origin signing JWKS.
+ *
+ * Freshness is the JWKS response `Cache-Control: max-age`. After that, or
+ * when `force` is set, refetch. A failed refetch returns the last keys only
+ * while `stale-if-error` still applies; otherwise it throws (including a
+ * cold-cache miss).
+ */
 export async function fetchOriginJwks(
   apiBaseUrl: string,
-  fetchImpl: typeof fetch = fetch
+  fetchImpl: typeof fetch = fetch,
+  options?: FetchOriginJwksOptions
 ): Promise<readonly OriginJwk[]> {
   const now = Date.now();
   if (
+    options?.force !== true &&
     jwksCache !== undefined &&
     jwksCache.apiBaseUrl === apiBaseUrl &&
-    now - jwksCache.fetchedAtMs < JWKS_CACHE_TTL_MS
+    now < jwksCache.freshUntilMs
   ) {
     return jwksCache.keys;
   }
-  const response = await fetchImpl(
-    `${apiBaseUrl.replace(/\/+$/, "")}/v1/origin/keys`
-  );
-  if (!response.ok) {
-    throw new Error(`Origin JWKS fetch failed: status=${response.status}`);
-  }
-  const body: unknown = await response.json().catch(() => undefined);
-  const keys =
-    typeof body === "object" &&
-    body !== null &&
-    Array.isArray((body as Record<string, unknown>).keys)
-      ? ((body as Record<string, unknown>).keys as OriginJwk[])
-      : [];
-  if (keys.length === 0) {
-    throw new Error("Origin JWKS fetch returned no keys");
+  try {
+    const response = await fetchImpl(
+      `${apiBaseUrl.replace(/\/+$/, "")}/v1/origin/keys`
+    );
+    if (!response.ok) {
+      throw new Error(`Origin JWKS fetch failed: status=${response.status}`);
+    }
+    const body: unknown = await response.json().catch(() => undefined);
+    const keys =
+      typeof body === "object" &&
+      body !== null &&
+      Array.isArray((body as Record<string, unknown>).keys)
+        ? ((body as Record<string, unknown>).keys as OriginJwk[])
+        : [];
+    if (keys.length === 0) {
+      throw new Error("Origin JWKS fetch returned no keys");
+    }
+    const cacheControl = response.headers.get("cache-control");
+    const maxAgeMs = cacheControlMaxAgeMs(cacheControl) ?? 0;
+    const staleIfErrorMs = cacheControlStaleIfErrorMs(cacheControl) ?? 0;
+    jwksCache = {
+      apiBaseUrl,
+      keys,
+      freshUntilMs: now + maxAgeMs,
+      staleUntilMs: now + maxAgeMs + staleIfErrorMs,
+    };
+    return keys;
+  } catch (error) {
+    if (
+      jwksCache !== undefined &&
+      jwksCache.apiBaseUrl === apiBaseUrl &&
+      now < jwksCache.staleUntilMs
+    ) {
+      return jwksCache.keys;
+    }
+    throw error;
   }
-  jwksCache = { apiBaseUrl, keys, fetchedAtMs: now };
-  return keys;
 }
 
 export interface VerifyOriginWebhookOptions {
@@ -183,14 +255,28 @@ export async function verifyOriginWebhook(
   options?: VerifyOriginWebhookOptions
 ): Promise<void> {
   const apiBaseUrl = options?.apiBaseUrl ?? DEFAULT_ORIGIN_API_BASE_URL;
-  const keys = await fetchOriginJwks(apiBaseUrl, options?.fetchImpl ?? fetch);
+  const fetchImpl = options?.fetchImpl ?? fetch;
+  const keys = await fetchOriginJwks(apiBaseUrl, fetchImpl);
   if (
-    !verifyV1edWebhookPayload({
+    verifyV1edWebhookPayload({
       publicJwks: keys,
       body,
       headers,
       nowMs: options?.nowMs,
     })
+  ) {
+    return;
+  }
+  const refreshed = await fetchOriginJwks(apiBaseUrl, fetchImpl, {
+    force: true,
+  });
+  if (
+    !verifyV1edWebhookPayload({
+      publicJwks: refreshed,
+      body,
+      headers,
+      nowMs: options?.nowMs,
+    })
   ) {
     throw new Error("Origin webhook signature verification failed");
   }

package/src/index.ts

@@ -96,12 +96,6 @@ export {
   UnknownToolError,
 } from "./internal/session-engine.js";
 export { createMemoryKv, memoryCasTable } from "./kv/memory-kv.js";
-export {
-  LedgerCasExhaustedError,
-  LedgerFencedError,
-  SessionLedger,
-  supportsSessionLedgerKv,
-} from "./ledger.js";
 export type { MemoryBackend, TurnMemoryRecord } from "./memory.js";
 export {
   agentStoreMemoryBackend,

package/src/internal/authored-alias-hooks.ts

@@ -14,16 +14,29 @@
  *   project's own node_modules; `fallbackAliases` only apply when that
  *   fails (npx/global installs, projects without a local dependency), so a
  *   real install in the user's project keeps precedence.
+ *
+ * A third case is first-party factory agents that relative-import this
+ * package's `src/` from a monorepo checkout. Hosted engines `npm install`
+ * only the agent directory, so files under `packages/agent-serve/src` have
+ * no `node_modules`. Bare specifiers from that tree (`zod`, octokit, …)
+ * retry against the running `@cursor/july` package.json, which does.
  */
 
 // Null-prototype copies so specifiers like "constructor" or "__proto__"
 // can never resolve to inherited Object.prototype members.
 let directAliases = toNullProtoMap({});
 let fallbackAliases = toNullProtoMap({});
+let sourceTreeFallbackParentURL: string | undefined;
 
 export interface AuthoredAliasHookData {
   directAliases: Record<string, string>;
   fallbackAliases: Record<string, string>;
+  /**
+   * `file:` URL of the running `@cursor/july` package.json. Bare imports
+   * from monorepo `packages/agent-serve/` source retry against this parent
+   * when the source tree has no `node_modules` (hosted factory engines).
+   */
+  sourceTreeFallbackParentURL?: string;
 }
 
 function toNullProtoMap(
@@ -35,6 +48,9 @@ function toNullProtoMap(
 export function initialize(data: AuthoredAliasHookData): void {
   directAliases = toNullProtoMap(data.directAliases);
   fallbackAliases = toNullProtoMap(data.fallbackAliases);
+  const parent = data.sourceTreeFallbackParentURL;
+  sourceTreeFallbackParentURL =
+    typeof parent === "string" && parent !== "" ? parent : undefined;
 }
 
 interface ResolveResult {
@@ -58,12 +74,64 @@ export function resolve(
     return { url: direct, shortCircuit: true };
   }
   const fallback = fallbackAliases[specifier];
-  if (fallback === undefined) {
-    // Not ours: pass through with no promise/try-catch overhead. This hook
-    // runs on every module resolution in the process.
-    return nextResolve(specifier, context);
+  if (fallback !== undefined) {
+    return Promise.resolve()
+      .then(() => nextResolve(specifier, context))
+      .catch(() => ({ url: fallback, shortCircuit: true }));
+  }
+  if (
+    sourceTreeFallbackParentURL !== undefined &&
+    isBarePackageSpecifier(specifier) &&
+    isMonorepoAgentServeSource(parentURLOf(context))
+  ) {
+    const retryParent = sourceTreeFallbackParentURL;
+    return Promise.resolve()
+      .then(() => nextResolve(specifier, context))
+      .catch(() => nextResolve(specifier, withParentURL(context, retryParent)));
+  }
+  // Not ours: pass through with no promise/try-catch overhead. This hook
+  // runs on every module resolution in the process.
+  return nextResolve(specifier, context);
+}
+
+function parentURLOf(context: unknown): string | undefined {
+  if (context === null || typeof context !== "object") {
+    return undefined;
+  }
+  const parentURL = (context as { parentURL?: unknown }).parentURL;
+  return typeof parentURL === "string" ? parentURL : undefined;
+}
+
+function withParentURL(context: unknown, parentURL: string): unknown {
+  if (context !== null && typeof context === "object") {
+    return { ...(context as Record<string, unknown>), parentURL };
+  }
+  return { parentURL };
+}
+
+function isBarePackageSpecifier(specifier: string): boolean {
+  if (specifier.length === 0) {
+    return false;
+  }
+  const first = specifier[0];
+  if (first === "." || first === "/" || first === "\\") {
+    return false;
+  }
+  return !(
+    specifier.startsWith("node:") ||
+    specifier.startsWith("file:") ||
+    specifier.startsWith("data:") ||
+    specifier.startsWith("http:") ||
+    specifier.startsWith("https:")
+  );
+}
+
+function isMonorepoAgentServeSource(parentURL: string | undefined): boolean {
+  if (parentURL === undefined) {
+    return false;
   }
-  return Promise.resolve()
-    .then(() => nextResolve(specifier, context))
-    .catch(() => ({ url: fallback, shortCircuit: true }));
+  return (
+    parentURL.includes("/packages/agent-serve/") &&
+    !parentURL.includes("/node_modules/")
+  );
 }

package/src/internal/authored-loaders.ts

@@ -11,9 +11,11 @@
  * imports of the framework resolve against the running package: the
  * historical `@anysphere/agent-serve[/x]` name always, and
  * `@cursor/july[/x]` / `@cursor/agentkit[/x]` as fallbacks when the user's
- * project has no local install (npx / global). Source runs (tsx from the
- * monorepo) skip both — the host loader and tsconfig paths already cover
- * them.
+ * project has no local install (npx / global). The same hooks retry bare
+ * npm specifiers from monorepo `packages/agent-serve/` source against this
+ * package (hosted factory engines install only the agent directory).
+ * Source runs (tsx from the monorepo) skip both — the host loader and
+ * tsconfig paths already cover them.
  */
 
 import { stat } from "node:fs/promises";
@@ -175,7 +177,16 @@ function registerFrameworkAliases(): void {
     fallbackAliases[`${AGENTKIT_PACKAGE_NAME}${suffix}`] = target;
   }
   const hooksUrl = new URL("./authored-alias-hooks.js", import.meta.url);
-  const data: AuthoredAliasHookData = { directAliases, fallbackAliases };
+  const data: AuthoredAliasHookData = {
+    directAliases,
+    fallbackAliases,
+    // Hosted factory agents relative-import this package's src/ from a
+    // monorepo checkout while npm install ran only in the agent directory.
+    // Bare specifiers from that tree retry against this package.json.
+    sourceTreeFallbackParentURL: pathToFileURL(
+      join(packageRootDir(), "package.json")
+    ).href,
+  };
   // `node:module`'s register() is synchronous: it blocks until the hooks
   // thread has initialized, so the aliases are active when it returns.
   registerModuleHooks(hooksUrl, { data });

package/src/internal/deployment-scm-event-stream.ts

@@ -34,10 +34,10 @@
  * only.
  */
 
-// Node builtins only: hosted engines install the consuming agent's directory
-// alone and load this file as raw TypeScript source, so third-party imports
-// (even zod) do not resolve from here. See the tenant-mcp internals for the
-// same constraint.
+// Hosted engines install the consuming agent's directory alone and load this
+// file as raw TypeScript source. Relative and `node:` imports resolve here;
+// this package's own npm dependencies retry against the running `@cursor/july`
+// install (authored-alias-hooks). Do not add deps that package does not have.
 import { createHmac } from "node:crypto";
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { join } from "node:path";

package/src/internal/discovery.ts

@@ -29,7 +29,6 @@ import {
   type AgentProject,
   type AgentProjectInfo,
   type AgentRuntime,
-  type AgentServingMode,
   type ArtifactsDefinition,
   type BuiltinToolsConfig,
   type ChannelDefinition,
@@ -194,9 +193,9 @@ export async function loadAgentProjects(
     );
   }
   const results: Array<{ slug: string; project: AgentProject }> = [];
-  // Storage namespaces (session mirror, host kv, durable-session ledger)
-  // key on the project NAME, not the mount slug — two co-hosted agents
-  // sharing a name would silently share sessions and coordination state.
+  // Storage namespaces (session mirror, host kv) key on the project
+  // NAME, not the mount slug — two co-hosted agents sharing a name would
+  // silently share sessions and KV state.
   const slugByName = new Map<string, string>();
   for (const child of children) {
     const project = await loadAgentProject(child.dir, options);
@@ -506,7 +505,6 @@ async function loadAgent(
         };
   const hosting = resolveHosting(ctx, agentDir, config?.hosting);
   const concurrency = resolveConcurrency(ctx, agentDir, config?.concurrency);
-  const serving = resolveServing(ctx, agentDir, config?.serving);
 
   if (runtime === "cloud") {
     warnCloudRuntimeLimitations(ctx, agentDir, {
@@ -531,7 +529,6 @@ async function loadAgent(
     ...(allowedTools === undefined ? {} : { allowedTools }),
     hosting,
     concurrency,
-    serving,
     tools,
     skills,
     connections,
@@ -540,27 +537,6 @@ async function loadAgent(
   };
 }
 
-/**
- * Validate the authored serving mode. An unrecognized value is an error
- * diagnostic and falls back to undefined (resident) — a typo must not
- * silently opt an agent into (or out of) ledger coordination.
- */
-function resolveServing(
-  ctx: DiscoveryContext,
-  agentDir: string,
-  serving: AgentServingMode | undefined
-): AgentServingMode | undefined {
-  if (serving === undefined || serving === "resident" || serving === "ledger") {
-    return serving;
-  }
-  ctx.diagnostics.push({
-    severity: "error",
-    path: displayPath(ctx, join(agentDir, "agent.ts")),
-    message: `serving must be "resident" or "ledger"; got ${JSON.stringify(serving)}.`,
-  });
-  return undefined;
-}
-
 /** Absolute harness cwd parent, or undefined when unset / blank. */
 function resolveAgentCwd(
   ctx: DiscoveryContext,

package/src/internal/distribution.ts

@@ -112,7 +112,6 @@ export const AUTHORING_ENTRY_FILES: ReadonlyArray<
   ["artifacts", "artifacts.js"],
   ["kv", "kv.js"],
   ["kv/memory", "kv/memory-kv.js"],
-  ["ledger", "ledger.js"],
   ["storage", "storage.js"],
   ["storage/file-kv", "storage-backends/file-kv.js"],
   ["storage/cursor-hosted", "storage-backends/cursor-hosted.js"],