@cursor/july 0.1.1

package/src/internal/ids.ts

@@ -0,0 +1,44 @@
+import { randomBytes } from "node:crypto";
+
+/** Fresh session id (`ses_<24 hex>` — a single safe path segment). */
+export function newSessionId(): string {
+  return `ses_${randomBytes(12).toString("hex")}`;
+}
+
+export function newContinuationKey(): string {
+  return randomBytes(16).toString("hex");
+}
+
+/**
+ * Unique server-tool call id (a single safe path segment). Used when the
+ * SDK omits `context.toolCallId` and for direct (deterministic) tool calls.
+ */
+export function newToolCallId(toolName: string): string {
+  const safe = toolName.replace(/[^A-Za-z0-9_]/g, "_").slice(0, 32);
+  return `tool_${safe}_${randomBytes(8).toString("hex")}`;
+}
+
+/**
+ * Wire form of a continuation token: the owning channel id, a colon, then
+ * the channel-local key (mirrors how platform channels key sessions by
+ * thread identity).
+ */
+export function formatContinuationToken(
+  channelId: string,
+  key: string
+): string {
+  return `${channelId}:${key}`;
+}
+
+export function parseContinuationToken(
+  token: string
+): { channelId: string; key: string } | null {
+  const separator = token.indexOf(":");
+  if (separator <= 0 || separator === token.length - 1) {
+    return null;
+  }
+  return {
+    channelId: token.slice(0, separator),
+    key: token.slice(separator + 1),
+  };
+}

package/src/internal/init-project.ts

@@ -0,0 +1,165 @@
+/**
+ * Scaffold a minimal agent-serve project (`agent-serve init`).
+ */
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import type { ModelSetting } from "../types.js";
+import {
+  CLI_COMMAND_NAME,
+  PACKAGE_NAME,
+  packageVersion,
+} from "./distribution.js";
+
+export interface InitProjectOptions {
+  /** Directory to create (created if missing). */
+  dir: string;
+  /** Agent display name; defaults to the directory basename. */
+  name?: string;
+  /** Model id override written into agent.ts. */
+  model?: string;
+}
+
+export interface InitProjectResult {
+  rootDir: string;
+  files: string[];
+}
+
+const DEFAULT_MODEL: ModelSetting = {
+  id: "grok-4.5",
+  params: [
+    { id: "effort", value: "high" },
+    { id: "fast", value: "true" },
+  ],
+};
+
+export async function initProject(
+  options: InitProjectOptions
+): Promise<InitProjectResult> {
+  const rootDir = resolve(options.dir);
+  const name = options.name ?? basename(rootDir);
+  const model = formatModelLiteral(options.model ?? DEFAULT_MODEL);
+  const agentDir = join(rootDir, "agent");
+  await mkdir(agentDir, { recursive: true });
+
+  const written: string[] = [];
+  const write = async (rel: string, contents: string): Promise<void> => {
+    const abs = join(rootDir, rel);
+    await mkdir(dirname(abs), { recursive: true });
+    await writeFile(abs, contents, { flag: "wx" });
+    written.push(rel);
+  };
+
+  try {
+    await write(
+      "package.json",
+      `${JSON.stringify(
+        {
+          name,
+          private: true,
+          type: "module",
+          description: `agent project: ${name}`,
+          dependencies: {
+            [PACKAGE_NAME]: `^${packageVersion()}`,
+            zod: "^3.25.0",
+          },
+        },
+        null,
+        2
+      )}\n`
+    );
+    await write(
+      "agent/agent.ts",
+      `import { defineAgent } from "${PACKAGE_NAME}";
+
+export default defineAgent({
+  model: ${model},
+});
+`
+    );
+    await write(
+      "agent/instructions.md",
+      `# ${name}
+
+You are a helpful agent. Prefer tools when they fit the request.
+Keep answers concise unless the user asks for detail.
+`
+    );
+    await write(
+      "agent/tools/echo.ts",
+      `import { defineTool } from "${PACKAGE_NAME}/tools";
+import { z } from "zod";
+
+export default defineTool({
+  description: "Echo a short message back (demo tool).",
+  inputSchema: z.object({ message: z.string() }),
+  async execute({ message }) {
+    return { echoed: message };
+  },
+});
+`
+    );
+  } catch (error) {
+    if (
+      error !== null &&
+      typeof error === "object" &&
+      "code" in error &&
+      (error as { code: string }).code === "EEXIST"
+    ) {
+      throw new Error(
+        `Refusing to overwrite existing files under ${rootDir}. Pick an empty directory or remove the conflicting files.`
+      );
+    }
+    throw error;
+  }
+
+  return { rootDir, files: written };
+}
+
+function formatModelLiteral(model: string | ModelSetting): string {
+  if (typeof model === "string") {
+    return JSON.stringify(model);
+  }
+  const params =
+    model.params === undefined
+      ? ""
+      : `,
+    params: [
+${model.params
+  .map(
+    (param) =>
+      `      { id: ${JSON.stringify(param.id)}, value: ${JSON.stringify(param.value)} },`
+  )
+  .join("\n")}
+    ]`;
+  return `{
+    id: ${JSON.stringify(model.id)}${params},
+  }`;
+}
+
+/**
+ * Coding-agent setup guide printed by `agent-serve init`
+ * with no target directory (does not scaffold).
+ */
+export function printInitGuide(): void {
+  process.stdout.write(`${CLI_COMMAND_NAME} — coding agent setup
+
+Recommended loop:
+  1. Edit agent/ + tools under agent/tools/
+  2. ${CLI_COMMAND_NAME} info --dir . --json
+  3. ${CLI_COMMAND_NAME} run --dir . --message "..."
+  4. ${CLI_COMMAND_NAME} eval --dir .
+
+Scaffold a project:
+  ${CLI_COMMAND_NAME} init ./my-agent
+
+Evals:
+  Create evals/**/*.eval.ts using defineEval from ${PACKAGE_NAME}/evals
+  Case id is the path: evals/weather/nyc.eval.ts → weather/nyc
+  Required: evals/evals.config.ts with defineEvalConfig({ maxConcurrency })
+    (hard-capped at 200 due to model provider request limits)
+  Run: ${CLI_COMMAND_NAME} eval [--json] [evalId...]
+
+See AGENTS.md in the ${PACKAGE_NAME} package for the full loop.
+`);
+}

package/src/internal/json-dir-store.ts

@@ -0,0 +1,109 @@
+/**
+ * Small filesystem helpers for one-JSON-file-per-id persistence under a
+ * project-relative directory (eval run snapshots, A/B aggregate snapshots).
+ */
+
+import { randomBytes } from "node:crypto";
+import {
+  mkdir,
+  readdir,
+  readFile,
+  rename,
+  rm,
+  writeFile,
+} from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+
+export function assertNonEmptyDir(dir: string, fnName: string): string {
+  if (typeof dir !== "string" || dir.trim() === "") {
+    throw new Error(`${fnName}: dir must be a non-empty string`);
+  }
+  return dir;
+}
+
+/** Resolve `dir` against `projectRoot` when relative. */
+export function resolveProjectRelativeDir(args: {
+  dir: string;
+  projectRoot: string;
+}): string {
+  return isAbsolute(args.dir) ? args.dir : join(args.projectRoot, args.dir);
+}
+
+function isEnoent(error: unknown): boolean {
+  return (
+    error !== null &&
+    typeof error === "object" &&
+    "code" in error &&
+    (error as { code?: unknown }).code === "ENOENT"
+  );
+}
+
+/** List `*.json` basenames in `root` (any order). Missing dir → []. */
+export async function listJsonBasenames(root: string): Promise<string[]> {
+  let names: string[];
+  try {
+    names = await readdir(root);
+  } catch (error) {
+    if (isEnoent(error)) {
+      return [];
+    }
+    throw error;
+  }
+  return names.filter((name) => name.endsWith(".json"));
+}
+
+/**
+ * Read and JSON.parse every `*.json` file under `root`. Missing dir → [].
+ * Unreadable or corrupt files are skipped so one bad snapshot cannot wipe
+ * the rest of the history.
+ */
+export async function readJsonDir<T>(
+  root: string,
+  options?: { sortBasenames?: "asc" | "desc" }
+): Promise<T[]> {
+  let names = await listJsonBasenames(root);
+  if (options?.sortBasenames === "asc") {
+    names = [...names].sort();
+  } else if (options?.sortBasenames === "desc") {
+    names = [...names].sort().reverse();
+  }
+  const out: T[] = [];
+  for (const name of names) {
+    try {
+      const raw = await readFile(join(root, name), "utf8");
+      out.push(JSON.parse(raw) as T);
+    } catch {
+      // skip corrupt / unreadable files
+    }
+  }
+  return out;
+}
+
+/** Atomically write JSON under `root`/`fileName` (temp file + rename). */
+export async function writeJsonFile(args: {
+  root: string;
+  fileName: string;
+  value: unknown;
+}): Promise<void> {
+  const { root, fileName, value } = args;
+  // Serialize before any await so callers get a stable snapshot even if they
+  // mutate `value` afterward.
+  const body = `${JSON.stringify(value, null, 2)}\n`;
+  await mkdir(root, { recursive: true });
+  const finalPath = join(root, fileName);
+  const tmpPath = `${finalPath}.${randomBytes(4).toString("hex")}.tmp`;
+  await writeFile(tmpPath, body, "utf8");
+  await rename(tmpPath, finalPath);
+}
+
+/** Best-effort delete; ignores missing files. */
+export async function deleteFileInDir(args: {
+  root: string;
+  fileName: string;
+}): Promise<void> {
+  try {
+    await rm(join(args.root, args.fileName), { force: true });
+  } catch {
+    // ignore
+  }
+}

package/src/internal/json-schema.ts

@@ -0,0 +1,69 @@
+import { z } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import type { JsonSchemaObject } from "../types.js";
+
+const ANY_OBJECT_SCHEMA: JsonSchemaObject = {
+  type: "object",
+  properties: {},
+  additionalProperties: true,
+};
+
+export function isZodSchema(value: unknown): value is z.ZodTypeAny {
+  if (value instanceof z.ZodType) {
+    return true;
+  }
+  // Structural check for zod instances that come from a different module
+  // copy in the authoring project's node_modules.
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as { safeParse?: unknown }).safeParse === "function" &&
+    "_def" in value
+  );
+}
+
+/** Convert an authored input schema into the JSON Schema shown to the model. */
+export function toolInputJsonSchema(
+  inputSchema: z.ZodTypeAny | JsonSchemaObject | undefined
+): JsonSchemaObject {
+  if (inputSchema === undefined) {
+    return ANY_OBJECT_SCHEMA;
+  }
+  if (isZodSchema(inputSchema)) {
+    const converted = zodToJsonSchema(inputSchema as z.ZodTypeAny, {
+      $refStrategy: "none",
+      target: "jsonSchema7",
+    }) as Record<string, unknown>;
+    delete converted.$schema;
+    return converted;
+  }
+  return inputSchema;
+}
+
+export type ToolInputValidation =
+  | { ok: true; value: unknown }
+  | { ok: false; message: string };
+
+/**
+ * Validate tool-call args before `execute` runs. Zod schemas validate (and
+ * transform); plain JSON schemas pass through unvalidated.
+ */
+export function validateToolInput(
+  inputSchema: z.ZodTypeAny | JsonSchemaObject | undefined,
+  args: unknown
+): ToolInputValidation {
+  if (inputSchema === undefined || !isZodSchema(inputSchema)) {
+    return { ok: true, value: args };
+  }
+  const parsed = (inputSchema as z.ZodTypeAny).safeParse(args);
+  if (parsed.success) {
+    return { ok: true, value: parsed.data };
+  }
+  const issues = parsed.error.issues
+    .map((issue) => {
+      const path = issue.path.join(".");
+      return path === "" ? issue.message : `${path}: ${issue.message}`;
+    })
+    .join("; ");
+  return { ok: false, message: issues || "invalid input" };
+}

package/src/internal/log-ring.ts

@@ -0,0 +1,59 @@
+/**
+ * Bounded in-memory log buffer for the playground Logs tab.
+ *
+ * Wraps {@link ServeOptions.logger} so every channel/session line that hits
+ * the console is also retained for `GET /v1/logs`.
+ */
+
+export interface LogRingEntry {
+  index: number;
+  at: string;
+  line: string;
+}
+
+export interface LogRing {
+  /** Append a line (also called by {@link wrap}). */
+  push(line: string): void;
+  /** Snapshot entries with `index > after` (exclusive), oldest first. */
+  since(after?: number): LogRingEntry[];
+  /** Wrap a logger so each write is recorded then forwarded. */
+  wrap(inner: (line: string) => void): (line: string) => void;
+}
+
+export function createLogRing(options: { capacity?: number } = {}): LogRing {
+  const capacity = Math.max(1, options.capacity ?? 1000);
+  const entries: LogRingEntry[] = [];
+  let nextIndex = 0;
+
+  function push(line: string): void {
+    entries.push({
+      index: nextIndex,
+      at: new Date().toISOString(),
+      line,
+    });
+    nextIndex += 1;
+    while (entries.length > capacity) {
+      entries.shift();
+    }
+  }
+
+  return {
+    push,
+    since(after = -1): LogRingEntry[] {
+      if (entries.length === 0) {
+        return [];
+      }
+      const start = entries.findIndex((e) => e.index > after);
+      if (start < 0) {
+        return [];
+      }
+      return entries.slice(start);
+    },
+    wrap(inner) {
+      return (line: string) => {
+        push(line);
+        inner(line);
+      };
+    },
+  };
+}

package/src/internal/map-pool.ts

@@ -0,0 +1,32 @@
+/**
+ * Run `fn` over `items` with at most `concurrency` in flight; preserve order
+ * of results (and of side-effect completion relative to index assignment).
+ */
+export async function mapPool<T, R>(
+  items: readonly T[],
+  concurrency: number,
+  fn: (item: T, index: number) => Promise<R>
+): Promise<R[]> {
+  const results = new Array<R>(items.length);
+  let next = 0;
+  async function worker(): Promise<void> {
+    for (;;) {
+      const index = next;
+      next += 1;
+      if (index >= items.length) {
+        return;
+      }
+      const item = items[index];
+      if (item === undefined) {
+        return;
+      }
+      results[index] = await fn(item, index);
+    }
+  }
+  const workerCount = Math.min(Math.max(1, concurrency), items.length);
+  if (workerCount === 0) {
+    return results;
+  }
+  await Promise.all(Array.from({ length: workerCount }, () => worker()));
+  return results;
+}