@cursor/july 0.1.7 → 0.1.9

package/src/internal/workspace.ts

@@ -8,7 +8,7 @@
  */
 
 import { chmod, copyFile, mkdir, stat, writeFile } from "node:fs/promises";
-import { dirname, join, relative, resolve } from "node:path";
+import { dirname, join, parse, relative, resolve } from "node:path";
 import type {
   DiscoveredSkill,
   DiscoveredTool,
@@ -123,22 +123,59 @@ export function buildAgentToolsCatalog(
   return `${parts.join("\n").trimEnd()}\n`;
 }
 
+/**
+ * The full AGENTS.md-equivalent context for an agent: instructions, identity
+ * section, and the agent-side tool catalog. Written to the session workspace
+ * as `AGENTS.md`, and inlined into the first turn's prompt when the harness
+ * cannot discover that file (cloud runtime, or a local workspace the harness
+ * will not treat as the project root — see {@link isNestedInGitRepo}).
+ */
+export function buildAgentsMdContent(
+  agent: ResolvedAgent,
+  options: { includeScripts: boolean }
+): string {
+  return [
+    agent.instructions?.trim() ?? "",
+    buildIdentitySection(agent),
+    buildAgentToolsCatalog(agent.tools, {
+      includeScripts: options.includeScripts,
+    }),
+  ]
+    .filter((part) => part !== "")
+    .join("\n\n");
+}
+
+/**
+ * True when `dir` sits strictly inside a git repository (a `.git` exists in
+ * an ancestor directory but not in `dir` itself). The Cursor harness resolves
+ * its project root by walking up to the nearest git root, so a nested session
+ * workspace loses its own `AGENTS.md` / `.cursor` scaffold: the enclosing
+ * repo's rules load instead, and the (necessarily gitignored) workspace files
+ * are skipped by nested rule discovery.
+ */
+export async function isNestedInGitRepo(dir: string): Promise<boolean> {
+  let current = resolve(dir);
+  if (await exists(join(current, ".git"))) {
+    // The workspace is itself a repo root; the harness roots rules here.
+    return false;
+  }
+  const { root } = parse(current);
+  while (current !== root) {
+    current = dirname(current);
+    if (await exists(join(current, ".git"))) {
+      return true;
+    }
+  }
+  return false;
+}
+
 export async function materializeWorkspace(
   options: MaterializeWorkspaceOptions
 ): Promise<void> {
   const { agent, workspaceDir, seed } = options;
   await mkdir(workspaceDir, { recursive: true });
 
-  const agentToolsSection = buildAgentToolsCatalog(agent.tools, {
-    includeScripts: false,
-  });
-  const agentsMd = [
-    agent.instructions?.trim() ?? "",
-    buildIdentitySection(agent),
-    agentToolsSection,
-  ]
-    .filter((part) => part !== "")
-    .join("\n\n");
+  const agentsMd = buildAgentsMdContent(agent, { includeScripts: false });
   await writeFile(join(workspaceDir, "AGENTS.md"), agentsMd, "utf8");
 
   for (const tool of agent.tools) {

package/src/storage-backends/cursor-hosted.ts

@@ -0,0 +1,246 @@
+/**
+ * Cursor-managed durable storage for hosted agents.
+ *
+ * Talks to the control-plane storage proxy
+ * (`POST /internal/agent-serve/storage/*`) using the engine's pod
+ * `CURSOR_API_KEY`. The server resolves `deployment_id` from that service
+ * account — engines never receive a Bugbot DSN and cannot address another
+ * deployment's rows.
+ *
+ * On Cursor-managed hosting the start script pins `CURSOR_API_BASE_URL` to
+ * `https://api.cursor.com` (where the proxy is mounted). Locally, point
+ * `CURSOR_API_BASE_URL` at a backend that mounts Agent Serve routes and use
+ * a deployment SA key, or use `@cursor/july/storage/postgres-kv` /
+ * `file-kv` instead.
+ *
+ * ```ts
+ * import { defineStorage } from "@cursor/july/storage";
+ * import { cursorHostedStorage } from "@cursor/july/storage/cursor-hosted";
+ *
+ * export default defineStorage({
+ *   ...cursorHostedStorage(),
+ * });
+ * ```
+ */
+
+import type { ABSnapshot } from "../ab.js";
+import type { EvalRunSnapshot } from "../evals.js";
+import type {
+  StorageABTable,
+  StorageConfig,
+  StorageEntry,
+  StorageEvalsTable,
+} from "../storage.js";
+import type { JsonValue } from "../types.js";
+
+/**
+ * Same default as {@link cursorExternalApiUrl} in the CLI credentials module,
+ * inlined here so this storage entrypoint does not import CLI/zod code.
+ * Hosted monorepo examples load this file from `packages/agent-serve/src`
+ * while `npm install` runs in the example package — a credentials import
+ * would resolve `zod` from the wrong `node_modules` tree and crash serve.
+ */
+const DEFAULT_CURSOR_EXTERNAL_API_URL = "https://api.cursor.com";
+
+/**
+ * Reserved so user `secrets set` cannot smuggle a Bugbot DSN into the pod.
+ * Not injected by Cursor hosting (storage is HTTP-proxied).
+ */
+export const AGENT_SERVE_HOSTED_STORAGE_DATABASE_URL_ENV_VAR =
+  "BUGBOTDB_URL" as const;
+
+/**
+ * Diagnostic / self-host deployment id. Not the hosted-storage authz
+ * boundary — the proxy scopes rows from the authenticated service account.
+ */
+export const AGENT_SERVE_DEPLOYMENT_ID_ENV_VAR =
+  "AGENT_SERVE_DEPLOYMENT_ID" as const;
+
+/**
+ * Platform-managed secret / env names. User `secrets set` / DELETE cannot
+ * claim these.
+ */
+export const CURSOR_HOSTED_STORAGE_ENV_VARS: readonly [
+  typeof AGENT_SERVE_HOSTED_STORAGE_DATABASE_URL_ENV_VAR,
+  typeof AGENT_SERVE_DEPLOYMENT_ID_ENV_VAR,
+] = [
+  AGENT_SERVE_HOSTED_STORAGE_DATABASE_URL_ENV_VAR,
+  AGENT_SERVE_DEPLOYMENT_ID_ENV_VAR,
+];
+
+export interface CursorHostedStorageOptions {
+  /**
+   * Control-plane base URL (default: `CURSOR_API_BASE_URL`, else
+   * `https://api.cursor.com`).
+   */
+  baseUrl?: string;
+  /** Bearer credential (default: `CURSOR_API_KEY`). */
+  apiKey?: string;
+  /** Injected for tests. */
+  fetch?: typeof fetch;
+}
+
+type CursorHostedStorageMethods = Required<
+  Pick<StorageConfig, "put" | "get" | "delete" | "list">
+> & {
+  evals: StorageEvalsTable;
+  abs: StorageABTable;
+};
+
+function resolveApiKey(options: CursorHostedStorageOptions): string {
+  const key = (options.apiKey ?? process.env.CURSOR_API_KEY)?.trim();
+  if (key === undefined || key === "") {
+    throw new Error(
+      "cursorHostedStorage requires CURSOR_API_KEY (deployment pod credential on Cursor hosting)"
+    );
+  }
+  return key;
+}
+
+function resolveBaseUrl(options: CursorHostedStorageOptions): string {
+  const raw = (
+    options.baseUrl ??
+    process.env.CURSOR_API_BASE_URL ??
+    DEFAULT_CURSOR_EXTERNAL_API_URL
+  ).trim();
+  return raw.endsWith("/") ? raw.slice(0, -1) : raw;
+}
+
+async function storageRpc<T>(
+  options: CursorHostedStorageOptions,
+  path: string,
+  body: Record<string, unknown>
+): Promise<T> {
+  const baseUrl = resolveBaseUrl(options);
+  const apiKey = resolveApiKey(options);
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  if (typeof fetchImpl !== "function") {
+    throw new Error("cursorHostedStorage requires fetch");
+  }
+  const response = await fetchImpl(`${baseUrl}${path}`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(body),
+  });
+  const text = await response.text();
+  let parsed: unknown;
+  try {
+    parsed = text.length === 0 ? {} : JSON.parse(text);
+  } catch {
+    throw new Error(
+      `cursorHostedStorage ${path} returned non-JSON (${response.status})`
+    );
+  }
+  if (!response.ok) {
+    const error =
+      parsed !== null &&
+      typeof parsed === "object" &&
+      "error" in parsed &&
+      typeof (parsed as { error: unknown }).error === "string"
+        ? (parsed as { error: string }).error
+        : `HTTP ${response.status}`;
+    throw new Error(`cursorHostedStorage ${path}: ${error}`);
+  }
+  return parsed as T;
+}
+
+/**
+ * Cursor-hosted `defineStorage` methods (control-plane storage proxy →
+ * Bugbot `agent_serve_*` tables). Spread into `defineStorage({...})`.
+ */
+export function cursorHostedStorage(
+  options: CursorHostedStorageOptions = {}
+): CursorHostedStorageMethods {
+  return {
+    async put(key, value): Promise<void> {
+      await storageRpc(options, "/internal/agent-serve/storage/kv/put", {
+        key,
+        value,
+      });
+    },
+    async get(key): Promise<JsonValue | undefined> {
+      const result = await storageRpc<{
+        found: boolean;
+        value: JsonValue | null;
+      }>(options, "/internal/agent-serve/storage/kv/get", { key });
+      if (!result.found) {
+        return undefined;
+      }
+      return result.value ?? undefined;
+    },
+    async delete(key): Promise<void> {
+      await storageRpc(options, "/internal/agent-serve/storage/kv/delete", {
+        key,
+      });
+    },
+    async list(prefix): Promise<StorageEntry[]> {
+      const result = await storageRpc<{
+        entries: Array<{ key: string; value: JsonValue }>;
+      }>(options, "/internal/agent-serve/storage/kv/list", { prefix });
+      return result.entries;
+    },
+    evals: {
+      async put(run, ctx): Promise<void> {
+        await storageRpc(options, "/internal/agent-serve/storage/evals/put", {
+          agentName: ctx.agentName,
+          run,
+        });
+      },
+      async delete(runId, ctx): Promise<void> {
+        await storageRpc(
+          options,
+          "/internal/agent-serve/storage/evals/delete",
+          {
+            agentName: ctx.agentName,
+            runId,
+          }
+        );
+      },
+      async list(ctx): Promise<EvalRunSnapshot[]> {
+        const result = await storageRpc<{ runs: EvalRunSnapshot[] }>(
+          options,
+          "/internal/agent-serve/storage/evals/list",
+          { agentName: ctx.agentName }
+        );
+        return result.runs;
+      },
+    },
+    abs: {
+      async putSample(sample, ctx): Promise<void> {
+        await storageRpc(
+          options,
+          "/internal/agent-serve/storage/abs/put-sample",
+          {
+            agentName: ctx.agentName,
+            sample,
+          }
+        );
+      },
+      async putSnapshot(snapshot, ctx): Promise<void> {
+        await storageRpc(
+          options,
+          "/internal/agent-serve/storage/abs/put-snapshot",
+          {
+            agentName: ctx.agentName,
+            snapshot,
+          }
+        );
+      },
+      async getSnapshot(ctx): Promise<ABSnapshot | undefined> {
+        const result = await storageRpc<{
+          found: boolean;
+          snapshot: ABSnapshot | null;
+        }>(options, "/internal/agent-serve/storage/abs/get-snapshot", {
+          agentName: ctx.agentName,
+        });
+        if (!result.found) {
+          return undefined;
+        }
+        return result.snapshot ?? undefined;
+      },
+    },
+  };
+}

package/src/storage-backends/file-kv.ts

@@ -0,0 +1,221 @@
+/**
+ * File-backed `defineStorage` helper: a file-per-key KV store plus
+ * file-backed `evals` / `abs` tables.
+ *
+ * Implements the whole `defineStorage` surface with zero external
+ * dependencies: the four KV methods against a flat directory of JSON files
+ * (one file per key, filename = URI-encoded key), eval runs as
+ * `eval-runs/<agent>/<runId>.json`, and A/B metrics as
+ * `ab/<agent>/samples.ndjson` (append-only) plus `ab/<agent>/snapshot.json`
+ * (latest aggregate). KV keys carry the agent name inside the framework
+ * key scheme, but the evals/abs tables have no such scheme — the agent
+ * subdirectory keeps agents sharing one storage `dir` from mixing or
+ * overwriting each other's history. Swap this for a real backend
+ * (Postgres, S3, …) in production; the contracts are identical.
+ *
+ * Layout notes:
+ * - KV filenames encode the full key (`encodeURIComponent(key) + ".json"`),
+ *   so `list(prefix)` is a readdir + decode + filter, returned in key
+ *   order as the contract requires.
+ * - `put` writes via tmp + rename: the framework serializes writes, but a
+ *   restore-path `get`/`list` can run concurrently and must never see a
+ *   torn file.
+ * - `get` distinguishes a definitive miss (ENOENT → `undefined`) from a
+ *   real failure (anything else throws) — on the lazy-restore path a
+ *   throw correctly fails the follow-up instead of forking the session.
+ */
+
+import { randomUUID } from "node:crypto";
+import {
+  appendFile,
+  mkdir,
+  readdir,
+  readFile,
+  rename,
+  rm,
+  writeFile,
+} from "node:fs/promises";
+import { join } from "node:path";
+import type { ABSnapshot } from "../ab.js";
+import type { EvalRunSnapshot } from "../evals.js";
+import type {
+  StorageABTable,
+  StorageConfig,
+  StorageContext,
+  StorageEntry,
+  StorageEvalsTable,
+} from "../storage.js";
+import type { JsonValue } from "../types.js";
+
+export interface FileKvOptions {
+  /**
+   * Directory holding the storage files, relative to the agent project root
+   * (default `".agent-serve/kv"`). Absolute paths are used as-is.
+   */
+  dir?: string;
+}
+
+type FileKvMethods = Required<
+  Pick<StorageConfig, "put" | "get" | "delete" | "list">
+> & {
+  evals: StorageEvalsTable;
+  abs: StorageABTable;
+};
+
+/** File-backed `defineStorage` methods, ready to spread into `defineStorage({...})`. */
+export function fileKv(options?: FileKvOptions): FileKvMethods {
+  const resolveDir = (ctx: StorageContext): string =>
+    join(ctx.projectRoot, options?.dir ?? ".agent-serve/kv");
+  // The evals/abs tables are scoped per agent (KV keys already carry the
+  // agent name via the framework key scheme).
+  const evalRunsDir = (ctx: StorageContext): string =>
+    join(resolveDir(ctx), "eval-runs", encodeURIComponent(ctx.agentName));
+  const abDir = (ctx: StorageContext): string =>
+    join(resolveDir(ctx), "ab", encodeURIComponent(ctx.agentName));
+  const filePath = (ctx: StorageContext, key: string): string =>
+    join(resolveDir(ctx), `${encodeURIComponent(key)}.json`);
+  const readKey = async (
+    ctx: StorageContext,
+    key: string
+  ): Promise<JsonValue | undefined> => {
+    try {
+      return JSON.parse(
+        await readFile(filePath(ctx, key), "utf8")
+      ) as JsonValue;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+        return undefined; // definitive miss — key was never written
+      }
+      throw error; // real failure: let lazy restore fail the follow-up
+    }
+  };
+
+  return {
+    async put(key, value, ctx): Promise<void> {
+      await writeJsonAtomic({
+        dir: resolveDir(ctx),
+        fileName: `${encodeURIComponent(key)}.json`,
+        value,
+      });
+    },
+
+    get(key, ctx): Promise<JsonValue | undefined> {
+      return readKey(ctx, key);
+    },
+
+    async delete(key, ctx): Promise<void> {
+      await rm(filePath(ctx, key), { force: true });
+    },
+
+    async list(prefix, ctx): Promise<StorageEntry[]> {
+      let names: string[];
+      try {
+        names = await readdir(resolveDir(ctx));
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+          return []; // nothing stored yet
+        }
+        throw error;
+      }
+      const keys = names
+        .filter((name) => name.endsWith(".json"))
+        .map((name) => decodeURIComponent(name.slice(0, -".json".length)))
+        .filter((key) => key.startsWith(prefix))
+        .sort();
+      const entries: StorageEntry[] = [];
+      for (const key of keys) {
+        const value = await readKey(ctx, key);
+        if (value !== undefined) {
+          entries.push({ key, value });
+        }
+      }
+      return entries;
+    },
+
+    // Playground eval batches: one JSON file per run under eval-runs/<agent>/.
+    evals: {
+      async put(run, ctx): Promise<void> {
+        await writeJsonAtomic({
+          dir: evalRunsDir(ctx),
+          fileName: `${encodeURIComponent(run.runId)}.json`,
+          value: run,
+        });
+      },
+      async delete(runId, ctx): Promise<void> {
+        await rm(join(evalRunsDir(ctx), `${encodeURIComponent(runId)}.json`), {
+          force: true,
+        });
+      },
+      async list(ctx): Promise<EvalRunSnapshot[]> {
+        const dir = evalRunsDir(ctx);
+        let names: string[];
+        try {
+          names = await readdir(dir);
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+            return [];
+          }
+          throw error;
+        }
+        const runs: EvalRunSnapshot[] = [];
+        for (const name of names.filter((n) => n.endsWith(".json")).sort()) {
+          // One unreadable/corrupt file must not wipe the whole history:
+          // hydrate treats a throwing list() as "nothing saved".
+          try {
+            runs.push(
+              JSON.parse(
+                await readFile(join(dir, name), "utf8")
+              ) as EvalRunSnapshot
+            );
+          } catch {}
+        }
+        return runs;
+      },
+    },
+
+    // A/B metrics: append-only sample log + latest aggregate snapshot,
+    // both under ab/<agent>/.
+    abs: {
+      async putSample(sample, ctx): Promise<void> {
+        const dir = abDir(ctx);
+        await mkdir(dir, { recursive: true });
+        await appendFile(
+          join(dir, "samples.ndjson"),
+          `${JSON.stringify(sample)}\n`,
+          "utf8"
+        );
+      },
+      async putSnapshot(snapshot, ctx): Promise<void> {
+        await writeJsonAtomic({
+          dir: abDir(ctx),
+          fileName: "snapshot.json",
+          value: snapshot,
+        });
+      },
+      async getSnapshot(ctx): Promise<ABSnapshot | undefined> {
+        try {
+          return JSON.parse(
+            await readFile(join(abDir(ctx), "snapshot.json"), "utf8")
+          ) as ABSnapshot;
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+            return undefined;
+          }
+          throw error;
+        }
+      },
+    },
+  };
+}
+
+/** tmp + rename write so concurrent readers never see a torn file. */
+async function writeJsonAtomic(args: {
+  dir: string;
+  fileName: string;
+  value: unknown;
+}): Promise<void> {
+  await mkdir(args.dir, { recursive: true });
+  const tmp = join(args.dir, `.tmp-${randomUUID()}`);
+  await writeFile(tmp, JSON.stringify(args.value), "utf8");
+  await rename(tmp, join(args.dir, args.fileName));
+}