@cursor/july 0.1.102 → 0.1.104

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/factory-resource-channel.ts

@@ -0,0 +1,122 @@
+import type { z } from "zod";
+import { defineChannel, localDevStrict, POST } from "../channels.js";
+import type { ChannelDefinition, ChannelHandlerArgs } from "../types.js";
+import { tagOutcome } from "./channel-dispatch.js";
+import type { ContinuationIdentity } from "./continuation-identity.js";
+import { attachHostedAdmissionAdapter } from "./hosted-admission-adapter.js";
+import { bindLocalIngressSend } from "./local-ingress.js";
+
+type FactoryResourceChannelOptions<TEvent> = {
+  onEvent: (
+    event: TEvent,
+    args: ChannelHandlerArgs
+  ) => Promise<unknown> | unknown;
+  continuation?: ContinuationIdentity;
+  path?: string;
+  auth?: ChannelDefinition["auth"];
+  onStart?: ChannelDefinition["onStart"];
+  onStop?: ChannelDefinition["onStop"];
+};
+
+type FactoryResourceChannelSpec<TEvent extends { eventType: string }> = {
+  kind: string;
+  eventTypes: readonly string[];
+  eventSchema: z.ZodType<TEvent>;
+  replayDescription: string;
+  invalidError: string;
+};
+
+type FactoryResourceChannelPack<TEvent> = {
+  channel: (
+    options: FactoryResourceChannelOptions<TEvent>
+  ) => ChannelDefinition;
+  getOptions: (
+    definition: object
+  ) => FactoryResourceChannelOptions<TEvent> | undefined;
+};
+
+/**
+ * Shared pack for Factory resource channels that have one event type, no
+ * subscription filter, and the same local-replay / hosted-admission path.
+ */
+export function createFactoryResourceChannel<
+  TEvent extends { eventType: string },
+>(
+  spec: FactoryResourceChannelSpec<TEvent>
+): FactoryResourceChannelPack<TEvent> {
+  const optionsByDefinition = new WeakMap<
+    object,
+    FactoryResourceChannelOptions<TEvent>
+  >();
+
+  async function dispatchEvent(input: {
+    options: FactoryResourceChannelOptions<TEvent>;
+    event: TEvent;
+    args: ChannelHandlerArgs;
+  }): Promise<Response> {
+    await input.options.onEvent(
+      input.event,
+      bindLocalIngressSend(input.args, {
+        identity: input.options.continuation,
+        kind: spec.kind,
+        eventType: input.event.eventType,
+        payload: input.event,
+      })
+    );
+    return tagOutcome(Response.json({ ok: true }), "task");
+  }
+
+  function channel(
+    options: FactoryResourceChannelOptions<TEvent>
+  ): ChannelDefinition {
+    const routePath = options.path ?? "/";
+    const definition = defineChannel({
+      auth: options.auth ?? [localDevStrict()],
+      meta: {
+        kind: spec.kind,
+        factoryEventTypes: spec.eventTypes,
+      },
+      onStart: options.onStart,
+      onStop: options.onStop,
+      routes: [
+        POST(routePath, {
+          description: spec.replayDescription,
+          bodySchema: spec.eventSchema,
+          handler: async (_request, args) =>
+            dispatchEvent({
+              options,
+              event: args.body,
+              args,
+            }),
+        }),
+      ],
+    });
+    optionsByDefinition.set(definition, options);
+    attachHostedAdmissionAdapter(definition, {
+      kind: spec.kind,
+      dispatch: async ({ payload, args }) => {
+        const parsed = spec.eventSchema.safeParse(payload);
+        if (!parsed.success) {
+          return Response.json(
+            { ok: false, error: spec.invalidError },
+            { status: 400 }
+          );
+        }
+        return dispatchEvent({
+          options,
+          event: parsed.data,
+          args,
+        });
+      },
+    });
+    return definition;
+  }
+
+  function getOptions(
+    definition: object
+  ): FactoryResourceChannelOptions<TEvent> | undefined {
+    return optionsByDefinition.get(definition);
+  }
+
+  return { channel, getOptions };
+}

package/src/internal/filesystem/errors.ts

@@ -0,0 +1,220 @@
+/**
+ * Typed FileSystem throws. Every method error is a {@link PathError}
+ * so composers (`unionFs`) can rewrite `path` without scraping
+ * `error.message`.
+ *
+ * Messages stay the FileSystem contract strings. `path` is the
+ * absolute posix path the error is about (child-root on a mount,
+ * namespace path after `unionFs` remaps it).
+ */
+
+import path from "node:path";
+
+function normalizeErrorPath(input: string): string {
+  const slashes = input.replace(/\\/g, "/");
+  if (slashes === "") {
+    return "/";
+  }
+  const withSlash = slashes.startsWith("/") ? slashes : `/${slashes}`;
+  const resolved = path.posix.normalize(withSlash);
+  if (resolved.length > 1 && resolved.endsWith("/")) {
+    return resolved.slice(0, -1);
+  }
+  return resolved === "." || resolved === "" ? "/" : resolved;
+}
+
+const ROOT_MESSAGE_PREFIX =
+  /^(not found|read-only mount|write failed|edit failed|no mount for path|delete is not supported): \/$/;
+
+function rewritePathInMessage(
+  message: string,
+  from: string,
+  to: string
+): string {
+  if (from === to) {
+    return message;
+  }
+  if (from === "/") {
+    return ROOT_MESSAGE_PREFIX.test(message)
+      ? message.replace(/\/$/, to)
+      : message;
+  }
+  return message.includes(from) ? message.split(from).join(to) : message;
+}
+
+/**
+ * Base of every FileSystem method throw. Config / factory errors
+ * (`FileSystemConfigError`, empty `overlayFs`) are not PathErrors.
+ */
+export class PathError extends Error {
+  readonly path: string;
+
+  constructor(path: string, message: string) {
+    super(message);
+    this.name = new.target.name;
+    this.path = normalizeErrorPath(path);
+  }
+
+  /**
+   * Same error at a rewritten path. `unionFs` prepends the mount
+   * prefix this way. Subclass identity and extra fields stay.
+   */
+  withPath(path: string): this {
+    const next = normalizeErrorPath(path);
+    if (next === this.path) {
+      return this;
+    }
+    return this.recreate(
+      next,
+      rewritePathInMessage(this.message, this.path, next)
+    );
+  }
+
+  protected recreate(path: string, message: string): this {
+    return new PathError(path, message) as this;
+  }
+}
+
+export class FileNotFoundError extends PathError {
+  constructor(path: string, message?: string) {
+    super(path, message ?? `not found: ${normalizeErrorPath(path)}`);
+  }
+
+  protected override recreate(path: string, message: string): this {
+    return new FileNotFoundError(path, message) as this;
+  }
+}
+
+export class ReadOnlyMountError extends PathError {
+  constructor(path: string, message?: string) {
+    super(path, message ?? `read-only mount: ${normalizeErrorPath(path)}`);
+  }
+
+  protected override recreate(path: string, message: string): this {
+    return new ReadOnlyMountError(path, message) as this;
+  }
+}
+
+export class NoMountError extends PathError {
+  constructor(path: string, message?: string) {
+    super(path, message ?? `no mount for path: ${normalizeErrorPath(path)}`);
+  }
+
+  protected override recreate(path: string, message: string): this {
+    return new NoMountError(path, message) as this;
+  }
+}
+
+export class WriteFailedError extends PathError {
+  constructor(path: string, message?: string) {
+    super(path, message ?? `write failed: ${normalizeErrorPath(path)}`);
+  }
+
+  protected override recreate(path: string, message: string): this {
+    return new WriteFailedError(path, message) as this;
+  }
+}
+
+export class DeleteNotSupportedError extends PathError {
+  constructor(path: string, message?: string) {
+    super(
+      path,
+      message ?? `delete is not supported: ${normalizeErrorPath(path)}`
+    );
+  }
+
+  protected override recreate(path: string, message: string): this {
+    return new DeleteNotSupportedError(path, message) as this;
+  }
+}
+
+/**
+ * Exact-edit contract failures (`oldText is empty`, uniqueness).
+ * `message` is the contract string; it does not embed `path`.
+ */
+export class EditError extends PathError {
+  protected override recreate(path: string, message: string): this {
+    return new EditError(path, message) as this;
+  }
+}
+
+export class InvalidGrepPatternError extends PathError {
+  readonly pattern: string;
+
+  constructor(pattern: string, path = "/", message?: string) {
+    super(path, message ?? `invalid grep pattern: ${pattern}`);
+    this.pattern = pattern;
+  }
+
+  protected override recreate(path: string, message: string): this {
+    return new InvalidGrepPatternError(this.pattern, path, message) as this;
+  }
+}
+
+export function isFileNotFoundError(error: unknown): boolean {
+  return (
+    error instanceof FileNotFoundError ||
+    (error instanceof Error && error.message.startsWith("not found:"))
+  );
+}
+
+export function isInvalidGrepPatternError(error: unknown): boolean {
+  return (
+    error instanceof InvalidGrepPatternError ||
+    (error instanceof Error &&
+      error.message.startsWith("invalid grep pattern:"))
+  );
+}
+
+const CONTRACT_PATH_LABELS = [
+  "not found: ",
+  "read-only mount: ",
+  "write failed: ",
+  "edit failed: ",
+  "no mount for path: ",
+  "delete is not supported: ",
+] as const;
+
+/**
+ * Remap a child throw onto a mount prefix. Typed {@link PathError}
+ * keeps its class and rewrites `path`. Untyped `Error` still gets
+ * a best-effort message rewrite so older custom trees keep working.
+ */
+export function remapPathError(error: unknown, prefix: string): Error {
+  if (error instanceof PathError) {
+    return error.withPath(joinMountPath(error.path, prefix));
+  }
+  if (!(error instanceof Error)) {
+    return new PathError(prefix, String(error));
+  }
+  return rewriteUntypedMountError(error, prefix);
+}
+
+function joinMountPath(childPath: string, prefix: string): string {
+  const mount = normalizeErrorPath(prefix);
+  const child = normalizeErrorPath(childPath);
+  if (mount === "/") {
+    return child;
+  }
+  if (child === "/") {
+    return mount;
+  }
+  return `${mount}${child}`;
+}
+
+function rewriteUntypedMountError(error: Error, prefix: string): Error {
+  for (const label of CONTRACT_PATH_LABELS) {
+    if (!error.message.startsWith(label)) {
+      continue;
+    }
+    const childPath = error.message.slice(label.length);
+    const next = `${label}${joinMountPath(childPath, prefix)}`;
+    if (next === error.message) {
+      return error;
+    }
+    const rewritten = new Error(next);
+    rewritten.name = error.name;
+    return rewritten;
+  }
+  return error;
+}