@cursor/july 0.1.1

package/src/internal/ab-snapshot.ts

@@ -0,0 +1,335 @@
+/**
+ * Read-only A/B metrics snapshot: fold durable session event streams into
+ * per-session assignments and aggregate arm totals. Used by `GET /v1/abs`.
+ */
+
+import {
+  type ABDefinition,
+  type ABMetrics,
+  type ABVariantMeta,
+  cloneABMetrics,
+  emptyABMetrics,
+} from "../ab.js";
+import type {
+  DiscoveredAB,
+  SessionEvent,
+  SessionInfo,
+  SessionRecord,
+  SessionSummary,
+} from "../types.js";
+import { applyABDerive, cloneFoldedMetrics, foldABStream } from "./ab-fold.js";
+import { mapPool } from "./map-pool.js";
+
+export interface ABSnapshotAssignment {
+  experiment: string;
+  variant: string | null;
+  variantLabel?: string;
+  /** Present when enrolled (`variant` non-null). */
+  metrics?: ABMetrics;
+}
+
+export interface ABSnapshotSession {
+  sessionId: string;
+  channelId: string;
+  mode: string;
+  title?: string;
+  turnCount: number;
+  updatedAt?: string;
+  assignments: ABSnapshotAssignment[];
+}
+
+export interface ABSnapshotArm {
+  variant: string;
+  variantLabel?: string;
+  description?: string;
+  /** Sessions enrolled in this arm. */
+  sessions: number;
+  metrics: ABMetrics;
+}
+
+export interface ABSnapshotExperiment {
+  name: string;
+  variants: Record<string, ABVariantMeta>;
+  /** Sessions with sticky skip (`variant: null`). */
+  skipped: number;
+  arms: ABSnapshotArm[];
+}
+
+export interface ABSnapshotConfig {
+  /** Newest-first session fold window for this snapshot (`GET /v1/abs`). */
+  maxPlaygroundSessions?: number;
+  /** True when `persistSamples` is configured. */
+  durableSamples?: boolean;
+  /** True when `persistSnapshots` is configured. */
+  durableSnapshots?: boolean;
+  /** Set when writing via filesystem snapshot persistence helpers. */
+  snapshotId?: string;
+}
+
+export interface ABSnapshot {
+  experiments: ABSnapshotExperiment[];
+  sessions: ABSnapshotSession[];
+  config?: ABSnapshotConfig;
+}
+
+export interface BuildABSnapshotInput {
+  experiments: readonly DiscoveredAB[];
+  agentName: string;
+  /** Newest-first session list (same order as `GET /v1/sessions`). */
+  sessions: readonly SessionSummary[];
+  loadRecord: (sessionId: string) => Promise<SessionRecord | undefined>;
+  loadEvents: (sessionId: string) => Promise<SessionEvent[]>;
+  sessionInfo: (record: SessionRecord) => SessionInfo;
+  logger: (line: string) => void;
+  /** Max concurrent event-log reads (default 8). */
+  concurrency?: number;
+  /** Attached to the returned snapshot (playground / persistence meta). */
+  config?: ABSnapshotConfig;
+}
+
+export async function buildABSnapshot(
+  input: BuildABSnapshotInput
+): Promise<ABSnapshot> {
+  const experiments = input.experiments;
+  const experimentByName = new Map(
+    experiments.map((experiment) => [experiment.name, experiment])
+  );
+
+  const armTotals = new Map<
+    string,
+    Map<string, { sessions: number; metrics: ABMetrics }>
+  >();
+  const skipped = new Map<string, number>();
+  for (const experiment of experiments) {
+    armTotals.set(experiment.name, new Map());
+    skipped.set(experiment.name, 0);
+    for (const variant of Object.keys(
+      (experiment.definition as ABDefinition).variants
+    )) {
+      armTotals.get(experiment.name)!.set(variant, {
+        sessions: 0,
+        metrics: emptyABMetrics(),
+      });
+    }
+  }
+
+  const concurrency = Math.max(1, input.concurrency ?? 8);
+  const sessionRows: ABSnapshotSession[] = [];
+
+  async function processOne(summary: SessionSummary): Promise<void> {
+    const record = await input.loadRecord(summary.sessionId);
+    if (record === undefined) {
+      return;
+    }
+    // Eval harness sessions never enroll; keep them out of aggregates too.
+    if (record.purpose === "eval") {
+      return;
+    }
+    const events = await input.loadEvents(summary.sessionId);
+    const folded = foldABStream(events);
+    if (experiments.length > 0) {
+      await applyABDerive(
+        folded,
+        events,
+        experiments,
+        input.sessionInfo(record),
+        input.agentName,
+        input.logger
+      );
+    }
+
+    const assignments: ABSnapshotAssignment[] = [];
+    // Prefer declared experiment order; include unknown arms from the log after.
+    const seen = new Set<string>();
+    for (const experiment of experiments) {
+      seen.add(experiment.name);
+      const variant = folded.arms.get(experiment.name);
+      if (variant === undefined) {
+        continue;
+      }
+      const def = experiment.definition as ABDefinition;
+      const label = variant === null ? undefined : def.variants[variant]?.label;
+      const metrics =
+        variant === null
+          ? undefined
+          : cloneFoldedMetrics(folded.metrics.get(experiment.name));
+      assignments.push({
+        experiment: experiment.name,
+        variant,
+        ...(label !== undefined ? { variantLabel: label } : {}),
+        ...(metrics !== undefined ? { metrics } : {}),
+      });
+      if (variant === null) {
+        skipped.set(experiment.name, (skipped.get(experiment.name) ?? 0) + 1);
+      } else {
+        const bucket = armTotals.get(experiment.name)?.get(variant);
+        if (bucket !== undefined && metrics !== undefined) {
+          bucket.sessions += 1;
+          addMetrics(bucket.metrics, metrics);
+        } else if (bucket === undefined) {
+          // Assigned to an arm no longer in the definition — still surface it.
+          const arms = armTotals.get(experiment.name) ?? new Map();
+          const created = {
+            sessions: 1,
+            metrics:
+              metrics !== undefined
+                ? cloneABMetrics(metrics)
+                : emptyABMetrics(),
+          };
+          arms.set(variant, created);
+          armTotals.set(experiment.name, arms);
+        }
+      }
+    }
+    for (const [experiment, variant] of folded.arms) {
+      if (seen.has(experiment)) {
+        continue;
+      }
+      const metrics =
+        variant === null
+          ? undefined
+          : cloneFoldedMetrics(folded.metrics.get(experiment));
+      assignments.push({
+        experiment,
+        variant,
+        ...(metrics !== undefined ? { metrics } : {}),
+      });
+    }
+
+    if (assignments.length === 0) {
+      return;
+    }
+
+    sessionRows.push({
+      sessionId: summary.sessionId,
+      channelId: summary.channelId,
+      mode: summary.mode,
+      ...(summary.title === undefined ? {} : { title: summary.title }),
+      turnCount: summary.turnCount,
+      ...(summary.updatedAt === undefined
+        ? {}
+        : { updatedAt: summary.updatedAt }),
+      assignments,
+    });
+  }
+
+  await mapPool(input.sessions, concurrency, async (summary) => {
+    await processOne(summary);
+  });
+
+  // Preserve newest-first order from the sessions list.
+  const order = new Map(
+    input.sessions.map((summary, index) => [summary.sessionId, index])
+  );
+  sessionRows.sort(
+    (a, b) => (order.get(a.sessionId) ?? 0) - (order.get(b.sessionId) ?? 0)
+  );
+
+  const experimentRows: ABSnapshotExperiment[] = experiments.map(
+    (experiment) => {
+      const def = experiment.definition as ABDefinition;
+      const arms: ABSnapshotArm[] = [];
+      for (const [variant, meta] of Object.entries(def.variants)) {
+        const bucket = armTotals.get(experiment.name)?.get(variant) ?? {
+          sessions: 0,
+          metrics: emptyABMetrics(),
+        };
+        arms.push({
+          variant,
+          ...(meta.label !== undefined ? { variantLabel: meta.label } : {}),
+          ...(meta.description !== undefined
+            ? { description: meta.description }
+            : {}),
+          sessions: bucket.sessions,
+          metrics: cloneABMetrics(bucket.metrics),
+        });
+      }
+      // Orphan arms from the log (no longer in definition).
+      for (const [variant, bucket] of armTotals.get(experiment.name) ?? []) {
+        if (variant in def.variants) {
+          continue;
+        }
+        arms.push({
+          variant,
+          sessions: bucket.sessions,
+          metrics: cloneABMetrics(bucket.metrics),
+        });
+      }
+      return {
+        name: experiment.name,
+        variants: def.variants,
+        skipped: skipped.get(experiment.name) ?? 0,
+        arms,
+      };
+    }
+  );
+
+  // Experiments that appear only in logs (definition removed).
+  const known = new Set(experiments.map((experiment) => experiment.name));
+  const orphanNames = new Set<string>();
+  for (const row of sessionRows) {
+    for (const assignment of row.assignments) {
+      if (!known.has(assignment.experiment)) {
+        orphanNames.add(assignment.experiment);
+      }
+    }
+  }
+  for (const name of orphanNames) {
+    const armsMap = new Map<string, { sessions: number; metrics: ABMetrics }>();
+    let skipCount = 0;
+    for (const row of sessionRows) {
+      for (const assignment of row.assignments) {
+        if (assignment.experiment !== name) {
+          continue;
+        }
+        if (assignment.variant === null) {
+          skipCount += 1;
+          continue;
+        }
+        const bucket = armsMap.get(assignment.variant) ?? {
+          sessions: 0,
+          metrics: emptyABMetrics(),
+        };
+        bucket.sessions += 1;
+        if (assignment.metrics !== undefined) {
+          addMetrics(bucket.metrics, assignment.metrics);
+        }
+        armsMap.set(assignment.variant, bucket);
+      }
+    }
+    experimentRows.push({
+      name,
+      variants: {},
+      skipped: skipCount,
+      arms: [...armsMap.entries()].map(([variant, bucket]) => ({
+        variant,
+        sessions: bucket.sessions,
+        metrics: cloneABMetrics(bucket.metrics),
+      })),
+    });
+  }
+
+  return {
+    experiments: experimentRows,
+    sessions: sessionRows,
+    ...(input.config === undefined ? {} : { config: input.config }),
+  };
+}
+
+function addMetrics(target: ABMetrics, delta: ABMetrics): void {
+  target.turns += delta.turns;
+  target.turnFailures += delta.turnFailures;
+  target.toolCalls += delta.toolCalls;
+  target.toolErrors += delta.toolErrors;
+  target.inputTokens += delta.inputTokens;
+  target.outputTokens += delta.outputTokens;
+  target.cacheReadTokens += delta.cacheReadTokens;
+  target.cacheWriteTokens += delta.cacheWriteTokens;
+  target.wallTimeMs += delta.wallTimeMs;
+  for (const [key, value] of Object.entries(delta.custom)) {
+    target.custom[key] = (target.custom[key] ?? 0) + value;
+  }
+}
+
+/** Narrow helper so callers don't need the unused DiscoveredAB import above. */
+export type { DiscoveredAB };

package/src/internal/approval-gate.ts

@@ -0,0 +1,115 @@
+/**
+ * In-memory gate for human-in-the-loop tool approvals. The session
+ * engine parks inside a server-tool `execute` by awaiting
+ * {@link ApprovalGate.wait}; HTTP (or the playground) unblocks via
+ * {@link ApprovalGate.resolve}.
+ *
+ * Pending approvals are also mirrored onto {@link SessionRecord} for
+ * durability of the *list* across reloads. After a process restart the
+ * in-flight SDK tool callback is gone, so resolve returns false and
+ * the host treats the approval as interrupted.
+ */
+
+import type { ApprovalDecision, PendingApproval } from "../types.js";
+
+function approvalKey(sessionId: string, callId: string): string {
+  return `${sessionId}\0${callId}`;
+}
+
+export interface ApprovalResolution {
+  decision: ApprovalDecision;
+  by?: string;
+}
+
+interface Waiter {
+  meta: PendingApproval;
+  resolve: (resolution: ApprovalResolution) => void;
+}
+
+export class ApprovalGate {
+  private readonly waiters = new Map<string, Waiter>();
+
+  wait(
+    meta: PendingApproval & { sessionId: string }
+  ): Promise<ApprovalResolution> {
+    const key = approvalKey(meta.sessionId, meta.callId);
+    const existing = this.waiters.get(key);
+    if (existing !== undefined) {
+      throw new Error(
+        `Approval already pending for session ${meta.sessionId} call ${meta.callId}`
+      );
+    }
+    return new Promise<ApprovalResolution>((resolveDecision) => {
+      this.waiters.set(key, {
+        meta: {
+          callId: meta.callId,
+          turnId: meta.turnId,
+          toolName: meta.toolName,
+          args: meta.args,
+          requestedAt: meta.requestedAt,
+        },
+        resolve: resolveDecision,
+      });
+    });
+  }
+
+  /**
+   * Unblock a waiter. Returns false when there is no live waiter (e.g. the
+   * host restarted while the tool call was parked).
+   */
+  resolve(
+    sessionId: string,
+    callId: string,
+    decision: ApprovalDecision,
+    resolvedBy?: string
+  ): boolean {
+    const key = approvalKey(sessionId, callId);
+    const waiter = this.waiters.get(key);
+    if (waiter === undefined) {
+      return false;
+    }
+    this.waiters.delete(key);
+    waiter.resolve({
+      decision,
+      ...(resolvedBy === undefined || resolvedBy === ""
+        ? {}
+        : { by: resolvedBy }),
+    });
+    return true;
+  }
+
+  has(sessionId: string, callId: string): boolean {
+    return this.waiters.has(approvalKey(sessionId, callId));
+  }
+
+  list(sessionId: string): PendingApproval[] {
+    const prefix = `${sessionId}\0`;
+    const out: PendingApproval[] = [];
+    for (const [key, waiter] of this.waiters) {
+      if (key.startsWith(prefix)) {
+        out.push(waiter.meta);
+      }
+    }
+    return out;
+  }
+
+  /** Drop waiters for a session (e.g. turn already failed). */
+  cancelSession(sessionId: string, decision: ApprovalDecision = "deny"): void {
+    const prefix = `${sessionId}\0`;
+    for (const [key, waiter] of [...this.waiters.entries()]) {
+      if (!key.startsWith(prefix)) {
+        continue;
+      }
+      this.waiters.delete(key);
+      waiter.resolve({ decision });
+    }
+  }
+
+  /** Unblock every live waiter (e.g. engine shutdown). */
+  cancelAll(decision: ApprovalDecision = "deny"): void {
+    for (const waiter of this.waiters.values()) {
+      waiter.resolve({ decision });
+    }
+    this.waiters.clear();
+  }
+}

package/src/internal/auth.ts

@@ -0,0 +1,39 @@
+/**
+ * Auth helpers shared by the HTTP channel, session engine, and session store.
+ */
+
+import type { AuthContext } from "../types.js";
+
+/**
+ * Session ids must be a single path segment: no `..`, separators, or empty
+ * names. Generated ids use `ses_<24 hex>`; this also admits caller-provided
+ * safe keys without opening path traversal.
+ */
+const SAFE_SESSION_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+export function isSafeSessionId(sessionId: string): boolean {
+  return (
+    SAFE_SESSION_ID.test(sessionId) &&
+    !sessionId.includes("..") &&
+    !sessionId.includes("/") &&
+    !sessionId.includes("\\")
+  );
+}
+
+/** True when both sides identify the same principal (or both are null). */
+export function samePrincipal(
+  a: AuthContext | null,
+  b: AuthContext | null
+): boolean {
+  if (a === null && b === null) {
+    return true;
+  }
+  if (a === null || b === null) {
+    return false;
+  }
+  return (
+    a.authenticator === b.authenticator &&
+    a.principalId === b.principalId &&
+    a.principalType === b.principalType
+  );
+}

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

@@ -0,0 +1,69 @@
+/**
+ * Node module-customization hooks for authored agent files (registered via
+ * node:module `register()` from authored-loaders.ts; runs on Node's loader
+ * thread — keep this module dependency-free).
+ *
+ * Authored files import the framework by bare specifier. From a published
+ * install those need help in two cases:
+ *
+ * - `@anysphere/agent-serve[/subpath]` (the historical monorepo name) is not
+ *   on npm, so it can never resolve from a user project. `directAliases` map
+ *   it straight onto the running package's dist entries.
+ * - `@cursor/july[/subpath]` (the published name) and `@cursor/agentkit
+ *   [/subpath]` (the future public name) normally resolve through the
+ *   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.
+ */
+
+// Null-prototype copies so specifiers like "constructor" or "__proto__"
+// can never resolve to inherited Object.prototype members.
+let directAliases = toNullProtoMap({});
+let fallbackAliases = toNullProtoMap({});
+
+export interface AuthoredAliasHookData {
+  directAliases: Record<string, string>;
+  fallbackAliases: Record<string, string>;
+}
+
+function toNullProtoMap(
+  source: Record<string, string>
+): Record<string, string> {
+  return Object.assign(Object.create(null) as Record<string, string>, source);
+}
+
+export function initialize(data: AuthoredAliasHookData): void {
+  directAliases = toNullProtoMap(data.directAliases);
+  fallbackAliases = toNullProtoMap(data.fallbackAliases);
+}
+
+interface ResolveResult {
+  url: string;
+  shortCircuit?: boolean;
+  format?: string | null;
+}
+
+type NextResolve = (
+  specifier: string,
+  context: unknown
+) => ResolveResult | Promise<ResolveResult>;
+
+export function resolve(
+  specifier: string,
+  context: unknown,
+  nextResolve: NextResolve
+): ResolveResult | Promise<ResolveResult> {
+  const direct = directAliases[specifier];
+  if (direct !== undefined) {
+    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);
+  }
+  return Promise.resolve()
+    .then(() => nextResolve(specifier, context))
+    .catch(() => ({ url: fallback, shortCircuit: true }));
+}

package/src/internal/authored-loaders.ts

@@ -0,0 +1,138 @@
+/**
+ * Process-wide module loaders for authored agent files.
+ *
+ * The CLI dynamically imports user TypeScript (`agent/agent.ts`,
+ * `agent/tools/*.ts`, `evals/**\/*.eval.ts`) at runtime, and plain Node
+ * cannot load `.ts` modules. Instead of requiring hosts to wrap the bin in
+ * `node --import tsx`, the bin (and programmatic `serve()`) registers tsx's
+ * ESM loader itself on startup.
+ *
+ * On compiled runs it additionally registers alias hooks so authored bare
+ * 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.
+ */
+
+import { register as registerModuleHooks } from "node:module";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import type { AuthoredAliasHookData } from "./authored-alias-hooks.js";
+import {
+  AGENTKIT_PACKAGE_NAME,
+  AUTHORING_ENTRY_FILES,
+  CLI_COMMAND_NAME,
+  isCompiledDistribution,
+  LEGACY_PACKAGE_NAME,
+  PACKAGE_NAME,
+  packageRootDir,
+} from "./distribution.js";
+
+/**
+ * Cross-copy markers: a user project with its own `@cursor/july` install
+ * can load a second copy of this module in the same process; tsx and the
+ * alias hooks must only be registered once.
+ */
+const TSX_REGISTERED_KEY = Symbol.for("cursor.agentkit.tsxRegistered");
+const ALIASES_REGISTERED_KEY = Symbol.for("cursor.agentkit.aliasesRegistered");
+
+let registration: Promise<void> | undefined;
+
+/**
+ * Install the runtime loaders for authored agent files. Idempotent; called
+ * from the CLI entry before any command runs, and from `serve()` and the
+ * discovery APIs for programmatic embedders. Concurrent callers share one
+ * registration and all wait for it to finish.
+ */
+export function registerAuthoredModuleLoaders(): Promise<void> {
+  if (!isCompiledDistribution()) {
+    return Promise.resolve();
+  }
+  registration ??= (async () => {
+    await registerTsxLoader();
+    registerFrameworkAliases();
+  })();
+  return registration;
+}
+
+async function registerTsxLoader(): Promise<void> {
+  // Escape hatch for hosts that precompile authored files to .js (or bring
+  // their own loader) and don't want tsx hooked into module resolution.
+  if (process.env.AGENT_SERVE_DISABLE_TSX === "1") {
+    return;
+  }
+  if (tsxAlreadyActive()) {
+    return;
+  }
+  try {
+    const tsx = (await import("tsx/esm/api")) as {
+      register: () => unknown;
+    };
+    if (typeof tsx.register !== "function") {
+      throw new Error("tsx/esm/api has no register export");
+    }
+    tsx.register();
+    (globalThis as Record<symbol, unknown>)[TSX_REGISTERED_KEY] = true;
+  } catch (error) {
+    process.stderr.write(
+      `[${CLI_COMMAND_NAME}] tsx loader unavailable (${
+        error instanceof Error ? error.message : String(error)
+      }); authored TypeScript files will not load — install tsx or precompile the agent to .js\n`
+    );
+  }
+}
+
+/**
+ * Whether a tsx loader is already installed process-wide: by a previous call
+ * from another copy of this module, or by the host command line (the Docker
+ * flow still runs `node --import tsx dist/bin/agent-serve.js`).
+ */
+function tsxAlreadyActive(): boolean {
+  if ((globalThis as Record<symbol, unknown>)[TSX_REGISTERED_KEY] === true) {
+    return true;
+  }
+  const hostArgs = [
+    ...process.execArgv,
+    ...(process.env.NODE_OPTIONS?.split(/\s+/) ?? []),
+  ];
+  for (let i = 0; i < hostArgs.length; i++) {
+    const arg = hostArgs[i];
+    if (arg === "--import" || arg === "--loader" || arg === "--require") {
+      const value = hostArgs[i + 1];
+      if (value === "tsx" || value?.startsWith("tsx/")) {
+        return true;
+      }
+    } else if (
+      arg !== undefined &&
+      /^--(import|loader|require)=tsx(\/|$)/.test(arg)
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function registerFrameworkAliases(): void {
+  const markers = globalThis as Record<symbol, unknown>;
+  if (markers[ALIASES_REGISTERED_KEY] === true) {
+    return;
+  }
+  const distDir = join(packageRootDir(), "dist");
+  const directAliases: Record<string, string> = {};
+  const fallbackAliases: Record<string, string> = {};
+  for (const [subpath, file] of AUTHORING_ENTRY_FILES) {
+    const target = pathToFileURL(join(distDir, file)).href;
+    const suffix = subpath === "" ? "" : `/${subpath}`;
+    directAliases[`${LEGACY_PACKAGE_NAME}${suffix}`] = target;
+    fallbackAliases[`${PACKAGE_NAME}${suffix}`] = target;
+    fallbackAliases[`${AGENTKIT_PACKAGE_NAME}${suffix}`] = target;
+  }
+  const hooksUrl = new URL("./authored-alias-hooks.js", import.meta.url);
+  const data: AuthoredAliasHookData = { directAliases, fallbackAliases };
+  // `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 });
+  markers[ALIASES_REGISTERED_KEY] = true;
+}