@cursor/july 0.1.101 → 0.1.103

package/src/internal/distribution.ts

@@ -2,31 +2,18 @@
  * Distribution facts for the running copy of the framework.
  *
  * The package publishes to npm as `@cursor/july` (the pre-launch codename
- * for Agent SDK; bins: `july` for `npx @cursor/july`, `agent-sdk`, the
- * older `agentkit`, and the legacy `agent-serve` alias) but
- * the monorepo keeps its historical `@anysphere/agent-serve` import name
- * working via tsconfig paths (source runs) and the runtime alias hooks
- * (compiled runs). Everything that needs to print a package name, print a
- * CLI command, or locate the package root goes through this module.
+ * for Agent SDK) with one bin, `agent-sdk`. Everything that needs to print
+ * a package name, print a CLI command, locate the package root, or pin
+ * `@cursor/july[/x]` to this copy goes through this module.
  */
 
 import { readFileSync } from "node:fs";
-import { basename } from "node:path";
-import { fileURLToPath } from "node:url";
+import { join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 /** Published npm package name (pre-launch codename for Agent SDK). */
 export const PACKAGE_NAME = "@cursor/july";
 
-/** Historical monorepo package name; never published, aliased at runtime. */
-export const LEGACY_PACKAGE_NAME = "@anysphere/agent-serve";
-
-/**
- * Future public package name; aliased with the same direct-to-running-dist
- * semantics as PACKAGE_NAME so the eventual rename keeps authored imports
- * on the CLI's module identity.
- */
-export const AGENTKIT_PACKAGE_NAME = "@cursor/agentkit";
-
 /**
  * Bracketed product tag for stderr / ServeOptions.logger lines
  * (`[agent-sdk] …`, `[agent-sdk/slack] …`).
@@ -35,23 +22,8 @@ export const LOG_PRODUCT = "agent-sdk";
 export const LOG_PREFIX: string = `[${LOG_PRODUCT}]`;
 export const SLACK_LOG_PREFIX: string = `[${LOG_PRODUCT}/slack]`;
 
-/**
- * Command name this CLI was invoked as. Both bins point at the same entry;
- * keep help text and hints copy-pasteable for whichever the user typed.
- */
-export const CLI_COMMAND_NAME: string = detectCliCommandName();
-
-function detectCliCommandName(): string {
-  // Only an extensionless `agent-serve` entry (the npm .bin symlink) proves
-  // the user typed the legacy alias. Shims that re-exec the real dist script
-  // (pnpm/Windows) hand us `agent-serve.js` for both bins, so anything else
-  // brands as the primary name.
-  const entry = process.argv[1];
-  if (entry !== undefined && basename(entry) === "agent-serve") {
-    return "agent-serve";
-  }
-  return "agent-sdk";
-}
+/** The bin name, for help text and copy-pasteable hints. */
+export const CLI_COMMAND_NAME = "agent-sdk";
 
 /**
  * True when this module runs from compiled `dist/` output (a published
@@ -72,14 +44,19 @@ export function packageRootDir(): string {
   return fileURLToPath(new URL("../..", import.meta.url));
 }
 
+interface PackageManifest {
+  version: string;
+  exports: Record<string, { import: string }>;
+}
+
+function packageManifest(): PackageManifest {
+  const raw = readFileSync(join(packageRootDir(), "package.json"), "utf8");
+  return JSON.parse(raw) as PackageManifest;
+}
+
 /** Version of the running package (from its own package.json). */
 export function packageVersion(): string {
-  const raw = readFileSync(
-    new URL("../../package.json", import.meta.url),
-    "utf8"
-  );
-  const parsed = JSON.parse(raw) as { version?: unknown };
-  return typeof parsed.version === "string" ? parsed.version : "0.0.0";
+  return packageManifest().version;
 }
 
 /** Facts `agent-sdk version` / `--version` print. */
@@ -88,15 +65,12 @@ export interface CliVersionInfo {
   name: string;
   /** `package.json` version of this install. */
   version: string;
-  /** Bin the process was invoked as (`agent-sdk` / `agent-serve`). */
-  cli: string;
 }
 
 export function cliVersionInfo(): CliVersionInfo {
   return {
     name: PACKAGE_NAME,
     version: packageVersion(),
-    cli: CLI_COMMAND_NAME,
   };
 }
 
@@ -114,43 +88,21 @@ export function formatCliVersion(options?: { json?: boolean }): string {
 }
 
 /**
- * Authoring entry subpaths and their dist-relative output files — the
- * runtime mirror of the package `exports` map (the source of truth;
- * `authored-loaders.test.ts` asserts they stay identical). The alias hooks
- * derive `@anysphere/agent-serve[/x]`, `@cursor/july[/x]`, and
- * `@cursor/agentkit[/x]` direct targets from this list.
+ * `@cursor/july[/subpath]` → `file:` URL of this copy's `import` target,
+ * for every subpath in the package `exports` map. The published manifest
+ * points at `dist/`; Bazel's staged copy points at the in-place `src/`
+ * emit, and the aliases follow whichever the manifest says.
  */
-export const AUTHORING_ENTRY_FILES: ReadonlyArray<
-  readonly [subpath: string, file: string]
-> = [
-  ["", "index.js"],
-  ["tools", "tools.js"],
-  ["channels", "channels.js"],
-  ["channels/slack", "channels/slack/index.js"],
-  ["channels/github", "channels/github/index.js"],
-  ["channels/origin", "channels/origin/index.js"],
-  ["channels/deployments", "channels/deployments/index.js"],
-  ["skills", "skills.js"],
-  ["extensions", "extensions.js"],
-  [
-    "extensions/cursor-cloud-agents",
-    "extensions/cursor-cloud-agents/extension.js",
-  ],
-  ["schedules", "schedules.js"],
-  ["reminders", "reminders.js"],
-  ["connections", "connections.js"],
-  ["hooks", "hooks.js"],
-  ["memory", "memory.js"],
-  ["prompt", "prompt.js"],
-  ["evals", "evals.js"],
-  ["evals/reporters", "evals/reporters.js"],
-  ["evals/loaders", "evals/loaders.js"],
-  ["ab", "ab.js"],
-  ["artifacts", "artifacts.js"],
-  ["kv", "kv.js"],
-  ["kv/memory", "kv/memory-kv.js"],
-  ["storage", "storage.js"],
-  ["storage/file-kv", "storage-backends/file-kv.js"],
-  ["storage/cursor-hosted", "storage-backends/cursor-hosted.js"],
-  ["otel", "otel.js"],
-];
+export function frameworkAliases(): Record<string, string> {
+  const root = packageRootDir();
+  return Object.fromEntries(
+    Object.entries(packageManifest().exports).map(
+      ([exportPath, { import: file }]) => [
+        exportPath === "."
+          ? PACKAGE_NAME
+          : `${PACKAGE_NAME}/${exportPath.slice(2)}`,
+        pathToFileURL(join(root, file)).href,
+      ]
+    )
+  );
+}

package/src/internal/docs-site.ts

@@ -245,7 +245,7 @@ function fallbackHtml(): string {
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>agent-serve docs</title>
+    <title>agent-sdk docs</title>
     <style>
       body { margin: 0; background: #0e1116; color: #e6edf3; font: 14px/1.6 ui-sans-serif, system-ui, sans-serif; }
       .box { max-width: 640px; margin: 64px auto; padding: 0 24px; }

package/src/internal/eval-run-store.ts

@@ -23,13 +23,6 @@ import {
   runDiscoveredEvals,
 } from "./eval-runner.js";
 
-export type {
-  EvalBatchStatus,
-  EvalCaseRunStatus as EvalCaseStatus,
-  EvalCaseSnapshot,
-  EvalRunSnapshot,
-} from "../evals.js";
-
 /**
  * Durable mirror for playground eval batches — the `StorageCoordinator`
  * adapter over the `defineStorage` `evals` table. Writes are

package/src/internal/eval-runner.ts

@@ -27,7 +27,6 @@ import type {
   EvalJudge,
   EvalJudgeCaller,
   EvalJudgeCallOptions,
-  EvalJudgeConfig,
   EvalJudgeGrader,
 } from "../evals/judge.js";
 import {

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

@@ -30,12 +30,12 @@
 
 import type { FileSink } from "../files.js";
 import type { StorageConfig, StorageEntry } from "../storage.js";
-import { STORAGE_KEY_ROOT } from "../storage-protocol.js";
+import { AGENTSDK_STORAGE_KEY_ROOT } from "../storage-protocol.js";
 import type { JsonValue } from "../types.js";
 import { mapBounded } from "./bounded.js";
 
 /**
- * Key kinds (`agentkit/v1/{agent}/{kind}/…`) that live on the framework
+ * Key kinds (`agentsdk/v1/{agent}/{kind}/…`) that live on the framework
  * file store. Everything else stays on the KV sink.
  */
 const FRAMEWORK_FILE_KINDS: ReadonlySet<string> = new Set([
@@ -52,10 +52,10 @@ const FRAMEWORK_FILE_KINDS: ReadonlySet<string> = new Set([
  * kind-scoped (`…/{agent}/session/`), so a prefix routes wholly to one side.
  */
 export function isFrameworkFileKey(key: string): boolean {
-  if (!key.startsWith(`${STORAGE_KEY_ROOT}/`)) {
+  if (!key.startsWith(`${AGENTSDK_STORAGE_KEY_ROOT}/`)) {
     return false;
   }
-  const rest = key.slice(STORAGE_KEY_ROOT.length + 1);
+  const rest = key.slice(AGENTSDK_STORAGE_KEY_ROOT.length + 1);
   const agentEnd = rest.indexOf("/");
   if (agentEnd === -1) {
     return false;
@@ -71,14 +71,6 @@ export type FileSinkStorageCore = Required<
   Pick<StorageConfig, "put" | "get" | "delete" | "list">
 >;
 
-/**
- * Adapt a {@link FileSink} to the `defineStorage` KV core. Storage keys are
- * framework-minted (URI-encoded, length-bounded segments — see
- * {@link storageKeys}), so they are used as file keys verbatim; values are
- * stored as JSON bytes. Parse failures throw: on the lazy-restore path a
- * corrupt document must fail the follow-up rather than read as a miss, and
- * the startup bulk restore already logs-and-skips a throwing `list`.
- */
 /** Parallel per-key reads backing `list` (each is presign + object GET). */
 const LIST_READ_CONCURRENCY = 8;
 
@@ -95,6 +87,14 @@ function isUnrepresentableFileKey(key: string): boolean {
     .some((segment) => segment === "" || segment === "." || segment === "..");
 }
 
+/**
+ * Adapt a {@link FileSink} to the `defineStorage` KV core. Storage keys are
+ * framework-minted (URI-encoded, length-bounded segments — see
+ * {@link storageKeys}), so they are used as file keys verbatim; values are
+ * stored as JSON bytes. Parse failures throw: on the lazy-restore path a
+ * corrupt document must fail the follow-up rather than read as a miss, and
+ * the startup bulk restore already logs-and-skips a throwing `list`.
+ */
 export function fileSinkStorageCore(sink: FileSink): FileSinkStorageCore {
   return {
     async put(key, value): Promise<void> {
@@ -153,10 +153,10 @@ export function fileSinkStorageCore(sink: FileSink): FileSinkStorageCore {
 }
 
 function frameworkFileKind(key: string): string | undefined {
-  if (!key.startsWith(`${STORAGE_KEY_ROOT}/`)) {
+  if (!key.startsWith(`${AGENTSDK_STORAGE_KEY_ROOT}/`)) {
     return undefined;
   }
-  const rest = key.slice(STORAGE_KEY_ROOT.length + 1);
+  const rest = key.slice(AGENTSDK_STORAGE_KEY_ROOT.length + 1);
   const agentEnd = rest.indexOf("/");
   if (agentEnd === -1) {
     return undefined;

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

@@ -42,20 +42,17 @@
  * pod's filesystem.
  */
 
-import {
-  cursorFrameworkStoreSourceId,
-  cursorHostedFiles,
-} from "../files-backends/cursor-hosted.js";
+import { cursorHostedFiles } from "../files-backends/cursor-hosted.js";
 import { defineStorage, type StorageDefinition } from "../storage.js";
 import { cursorHostedStorageV2 } from "../storage-backends/cursor-hosted-v2.js";
 import type { AgentArchitecture } from "../types.js";
 import { resolveApiKeySync } from "./cursor/credentials.js";
-import { AGENT_SERVE_GENERATION_ENV_VAR } from "./cursor-relay-core.js";
 import {
   composeFrameworkStorage,
   fileSinkStorageCore,
   frameworkGuardedCas,
 } from "./framework-file-storage.js";
+import { resolveAgentV2Hosting } from "./v2-hosting.js";
 
 export interface FrameworkStorageSelectionInput {
   /** `agent/storage.ts`, when the author wrote one (v1 only: discovery rejects it on v2). */
@@ -87,8 +84,11 @@ export function selectFrameworkStorageDefinition(
       'defineStorage (agent/storage.ts) is not supported on architecture "v2": storage is platform-selected. Delete the file.'
     );
   }
-  const env = input.env ?? process.env;
-  if (env[AGENT_SERVE_GENERATION_ENV_VAR] === undefined) {
+  const hosting = resolveAgentV2Hosting({
+    architecture: input.architecture,
+    env: input.env as NodeJS.ProcessEnv | undefined,
+  });
+  if (hosting.kind !== "cursor-managed") {
     // Self-hosted v2: the state root is the durable copy.
     return undefined;
   }
@@ -98,7 +98,6 @@ export function selectFrameworkStorageDefinition(
   // 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;
-  const envSnapshot = env as NodeJS.ProcessEnv;
   // 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.
@@ -118,7 +117,8 @@ export function selectFrameworkStorageDefinition(
       kv,
       files: fileSinkStorageCore(
         cursorHostedFiles({
-          resolveStoreSourceId: () => cursorFrameworkStoreSourceId(envSnapshot),
+          resolveStoreSourceId: () =>
+            hosting.resolveStoreIds().frameworkStoreSourceId,
           resolveApiKey,
         })
       ),

package/src/internal/frontmatter.ts

@@ -1,15 +1,48 @@
 /**
- * Minimal frontmatter parser. Supports the flat `key: value` scalar subset
- * used by authored markdown (skill descriptions, schedule cron expressions)
- * without pulling in a YAML dependency.
+ * Frontmatter parsers. Authored markdown (skill descriptions, schedule cron
+ * expressions) uses the flat `key: value` scalar subset; Cursor plugin
+ * markdown is full YAML (folded descriptions, lists).
  */
 
+import { JSON_SCHEMA, load as parseYaml } from "js-yaml";
+
 export interface ParsedFrontmatter {
   data: Record<string, string>;
   body: string;
 }
 
+export interface ParsedYamlFrontmatter {
+  data: Record<string, unknown>;
+  body: string;
+  /** Why the block did not parse as a YAML mapping; `data` is then empty. */
+  error?: string;
+}
+
 const FRONTMATTER_OPEN = /^---\s*$/;
+const YAML_FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)([\s\S]*)$/;
+
+/** YAML frontmatter with the JSON schema (no custom tags). */
+export function parseYamlFrontmatter(source: string): ParsedYamlFrontmatter {
+  const match = YAML_FRONTMATTER.exec(source);
+  if (match === null) {
+    return { data: {}, body: source };
+  }
+  const body = match[2] ?? "";
+  let data: unknown;
+  try {
+    data = parseYaml(match[1] ?? "", { schema: JSON_SCHEMA });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { data: {}, body, error: message };
+  }
+  if (data === undefined || data === null) {
+    return { data: {}, body };
+  }
+  if (typeof data !== "object" || Array.isArray(data)) {
+    return { data: {}, body, error: "frontmatter is not a mapping" };
+  }
+  return { data: data as Record<string, unknown>, body };
+}
 
 export function parseFrontmatter(source: string): ParsedFrontmatter {
   const lines = source.split(/\r?\n/);

package/src/internal/github-fanout.ts

@@ -1,5 +1,5 @@
 /**
- * Local fan-out proxy for `agent-serve github forward`.
+ * Local fan-out proxy for `agent-sdk github forward`.
  *
  * `gh webhook forward` can only target a single URL, and GitHub allows just one
  * forwarder per repo/org. To feed several GitHub channels at once, we run one