@cursor/july 0.1.109 → 0.1.111

package/src/internal/trajectory.ts

@@ -147,7 +147,7 @@ export function buildTrajectory(events: SessionEvent[]): Trajectory {
           };
           pendingCalls.set(call.callId, entry);
           if (parentCallId !== undefined) {
-            let sub = turn.subagents.find((s) => s.callId === parentCallId);
+            let sub = turn.subagents.find(s => s.callId === parentCallId);
             if (sub === undefined) {
               sub = { callId: parentCallId, toolCalls: [] };
               turn.subagents.push(sub);
@@ -197,7 +197,7 @@ export function buildTrajectory(events: SessionEvent[]): Trajectory {
           };
           if (event.data.parentCallId !== undefined) {
             let sub = turn.subagents.find(
-              (s) => s.callId === event.data.parentCallId
+              s => s.callId === event.data.parentCallId
             );
             if (sub === undefined) {
               sub = {
@@ -217,7 +217,7 @@ export function buildTrajectory(events: SessionEvent[]): Trajectory {
         if (event.turnId !== undefined) {
           const turn = ensureTurn(event.turnId);
           const existing = turn.subagents.find(
-            (s) => s.callId === event.data.callId
+            s => s.callId === event.data.callId
           );
           if (existing !== undefined) {
             existing.name = event.data.name;
@@ -274,8 +274,8 @@ export function buildTrajectory(events: SessionEvent[]): Trajectory {
     }
   }
 
-  const turns = turnOrder.map((id) => turnsById.get(id)!);
-  const turnsFailed = turns.filter((t) => t.failed).length;
+  const turns = turnOrder.map(id => turnsById.get(id)!);
+  const turnsFailed = turns.filter(t => t.failed).length;
   const toolCallCount = turns.reduce(
     (n, t) =>
       n +
@@ -283,8 +283,8 @@ export function buildTrajectory(events: SessionEvent[]): Trajectory {
       t.subagents.reduce((m, s) => m + s.toolCalls.length, 0),
     0
   );
-  const lastGood = [...turns].reverse().find((t) => t.assistantText !== "");
-  const costedTurns = turns.filter((t) => t.cost !== undefined);
+  const lastGood = [...turns].reverse().find(t => t.assistantText !== "");
+  const costedTurns = turns.filter(t => t.cost !== undefined);
   const totalCostUsd =
     costedTurns.length === 0
       ? undefined

package/src/internal/turn-governor.ts

@@ -85,10 +85,10 @@ export class TurnGovernor {
     if (args.signal?.aborted === true) {
       return Promise.resolve(undefined);
     }
-    return new Promise<TurnPermit | undefined>((resolve) => {
+    return new Promise<TurnPermit | undefined>(resolve => {
       const waiter: TurnWaiter = {
         sessionId: args.sessionId,
-        grant: (permit) => resolve(permit),
+        grant: permit => resolve(permit),
         cancel: () => resolve(undefined),
         cleanup: () => {
           this.queuedSessions.delete(args.sessionId);

package/src/internal/turn-outbox.ts

@@ -66,7 +66,7 @@ export class TurnOutbox<T> {
       return [];
     }
     const items: OutboxItem<T>[] = [];
-    for (const name of names.filter((n) => n.endsWith(".json")).sort()) {
+    for (const name of names.filter(n => n.endsWith(".json")).sort()) {
       const path = join(dir, name);
       try {
         const raw = await readFile(path, "utf8");

package/src/internal/update-check.ts

@@ -385,7 +385,7 @@ async function findDependingProjectDir(
     }
     const inNodeModules = dir
       .split(sep)
-      .some((part) => part === "node_modules" || part === ".pnpm");
+      .some(part => part === "node_modules" || part === ".pnpm");
     if (!inNodeModules && (await declaresDependency(dir, packageName))) {
       return dir;
     }
@@ -545,7 +545,7 @@ function runUpdateCommand(command: UpdateCommand): Promise<number> {
       shell: process.platform === "win32",
     });
     child.on("error", reject);
-    child.on("close", (code) => {
+    child.on("close", code => {
       resolve(code ?? 1);
     });
   });

package/src/internal/v2-hosting.ts

@@ -5,12 +5,23 @@ import {
 } from "./cursor/hosted-store-secrets.js";
 import { AGENT_SERVE_GENERATION_ENV_VAR } from "./cursor-relay-core.js";
 
+/**
+ * Exported (as `1`) by the control plane's start script for a version
+ * container of a persistent deployment. Its presence, not the agent's
+ * `persistent` flag, is what tells the runtime it owns a durable state
+ * directory.
+ */
+export const AGENT_SERVE_PERSISTENT_ENV_VAR = "AGENT_SERVE_PERSISTENT";
+
 export type AgentV2Hosting =
   | { kind: "not-v2" }
   | { kind: "self-hosted" }
   | {
       kind: "cursor-managed";
       resolveStoreIds: () => CursorManagedV2StoreIds;
+    }
+  | {
+      kind: "cursor-managed-persistent";
     };
 
 /**
@@ -31,6 +42,9 @@ export function resolveAgentV2Hosting(input: {
   if (env[AGENT_SERVE_GENERATION_ENV_VAR] === undefined) {
     return { kind: "self-hosted" };
   }
+  if (env[AGENT_SERVE_PERSISTENT_ENV_VAR] === "1") {
+    return { kind: "cursor-managed-persistent" };
+  }
   return {
     kind: "cursor-managed",
     resolveStoreIds: () => requireCursorManagedV2StoreIdsSync(env),

package/src/internal/workspace.ts

@@ -1,10 +1,12 @@
 /**
  * Session workspace materialization. Each session gets its own working
- * directory that the Cursor harness treats as the project: instructions land
- * in `AGENTS.md`, skills land in `.cursor/skills/<name>/SKILL.md`,
- * agent-side tools land in `.agent-serve/tools/<name>.sh`, and
- * `agent/sandbox/workspace/**` seed files are mirrored in. The harness picks
- * all of this up natively through its project setting source.
+ * directory that the Cursor harness treats as the project: skills land in
+ * `.cursor/skills/<name>/SKILL.md`, agent-side tools land in
+ * `.agent-serve/tools/<name>.sh`, and `agent/sandbox/workspace/**` seed files
+ * are mirrored in. The harness picks all of this up natively through its
+ * project setting source. Instructions are not written here: local turns
+ * deliver them as the harness system prompt ({@link buildAgentsMdContent}),
+ * and cloud / grokbot harnesses never read the session workspace.
  */
 
 import { execFile } from "node:child_process";
@@ -92,7 +94,7 @@ export function buildCloudSessionWorkspaceSection(
   dir: string,
   relPaths: readonly string[]
 ): string {
-  const listed = relPaths.map((path) => `\`${path}\``).join(", ");
+  const listed = relPaths.map(path => `\`${path}\``).join(", ");
   return [
     "## Session workspace files",
     "",
@@ -158,7 +160,7 @@ export function buildAgentToolsCatalog(
   tools: DiscoveredTool[],
   options: { includeScripts: boolean } = { includeScripts: false }
 ): string {
-  const agentTools = tools.filter((tool) => tool.execution === "agent");
+  const agentTools = tools.filter(tool => tool.execution === "agent");
   if (agentTools.length === 0) {
     return "";
   }
@@ -219,7 +221,7 @@ export function buildServerToolsCatalog(
   tools: DiscoveredTool[],
   options: { mcpServerName: string }
 ): string {
-  const serverTools = tools.filter((tool) => tool.execution === "server");
+  const serverTools = tools.filter(tool => tool.execution === "server");
   if (serverTools.length === 0) {
     return "";
   }
@@ -250,11 +252,12 @@ export function buildServerToolsCatalog(
 }
 
 /**
- * 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}).
+ * The full instructions context for an agent: instructions, identity
+ * section, and the agent-side tool catalog. Local turns send it as the
+ * harness system prompt (`AgentOptions.systemPrompt`, replacing Cursor's
+ * built-in prompt), grokbot turns carry it into the hosted session's system
+ * prompt, and cloud turns inline it into the first prompt because a cloud VM
+ * has no materialized workspace to read it from.
  *
  * `serverToolsMcpName` is cloud-only: when the turn's MCP config carries the
  * session-bound server-tool endpoint, the catalog names that server so the
@@ -279,7 +282,7 @@ export function buildAgentsMdContent(
       includeScripts: options.includeScripts,
     }),
   ]
-    .filter((part) => part !== "")
+    .filter(part => part !== "")
     .join("\n\n");
 }
 
@@ -344,9 +347,6 @@ export async function materializeWorkspace(
     await linkSharedMemoryDir(workspaceDir, stateRoot);
   }
 
-  const agentsMd = buildAgentsMdContent(agent, { includeScripts: false });
-  await writeFile(join(workspaceDir, "AGENTS.md"), agentsMd, "utf8");
-
   for (const tool of agent.tools) {
     if (tool.execution !== "agent" || tool.script === undefined) {
       continue;

package/src/kv/memory-kv.ts

@@ -1,9 +1,11 @@
 /**
- * In-memory {@link HostKvCasApi} — the test/dev implementation of the
- * interface module (`@cursor/july/kv`), exported at
- * `@cursor/july/kv/memory`.
+ * In-memory {@link HostKvCasApi} — the test/dev implementation of
+ * `@cursor/july/kv`.
  *
- * The memory KV *is* the dev shim: tests and local runs exercise the
+ * Internal only: SDK tests and Cursor factory code. Not a public Agent
+ * SDK export.
+ *
+ * The memory KV *is* the test shim: tests and local runs exercise the
  * CAS contract, not a mock of an RPC. Values are deep-copied on both write and
  * read so callers can never observe (or cause) shared-reference mutation.
  */
@@ -74,7 +76,7 @@ export function createMemoryKv(): HostKvCasApi {
     },
 
     async listKeys(prefix): Promise<string[]> {
-      return [...entries.keys()].filter((key) => key.startsWith(prefix)).sort();
+      return [...entries.keys()].filter(key => key.startsWith(prefix)).sort();
     },
   };
 }
@@ -89,10 +91,10 @@ export function createMemoryKv(): HostKvCasApi {
 export function memoryCasTable(): StorageCasTable {
   const kv = createMemoryKv();
   return {
-    getWithVersion: (key) => kv.getWithVersion(key),
+    getWithVersion: key => kv.getWithVersion(key),
     putIfAbsent: (key, value) => kv.putIfAbsent(key, value),
     putIfVersion: (key, value, expectedVersion) =>
       kv.putIfVersion(key, value, expectedVersion),
-    listKeys: (prefix) => kv.listKeys(prefix),
+    listKeys: prefix => kv.listKeys(prefix),
   };
 }

package/src/kv.ts

@@ -8,13 +8,10 @@
  * stores of unknown provenance — a `defineStorage` backend declares CAS
  * through its `cas` group instead, so it never needs probing.
  *
- * Implementations live elsewhere:
- *
- * - `@cursor/july/kv/memory` — `createMemoryKv`, the test/dev shim.
- * - The storage backends implement the same operations as the `cas`
- *   group on `defineStorage` (see `StorageCasTable` in
- *   `@cursor/july/storage`): `fileKv` (single-process) and
- *   `cursorHostedStorage` (control-plane proxy). See `docs/storage.md`.
+ * Implementations live on the storage backends: they implement the same
+ * operations as the `cas` group on the internal-only `defineStorage`
+ * (its `StorageCasTable` member): `fileKv` (single-process) and
+ * `cursorHostedStorage` (control-plane proxy). See `docs/storage.md`.
  */
 
 export type {

package/src/otel-public.ts

@@ -0,0 +1,24 @@
+/**
+ * Public `@cursor/july/otel` surface: types and W3C `traceparent`
+ * helpers. `defineOtel` is `@cursor/july/internal/otel`.
+ */
+
+export type {
+  OtelConfig,
+  OtelConfigFactory,
+  OtelDefinition,
+  OtelExporterConfig,
+  OtelLogOptions,
+  OtelMetricOptions,
+  OtelSignal,
+  OtelTraceOptions,
+} from "./otel.js";
+export {
+  activeTraceparent,
+  BACKEND_TRACEPARENT_HEADER,
+  formatTraceparent,
+  injectActiveTraceContext,
+  installOutboundFetchInstrumentation,
+  instrumentedFetch,
+  TRACEPARENT_HEADER,
+} from "./otel.js";

package/src/otel.ts

@@ -3,7 +3,7 @@
  * or set `OTEL_EXPORTER_OTLP_ENDPOINT` (standard OTel env).
  *
  * ```ts
- * import { defineOtel } from "@cursor/july/otel";
+ * import { defineOtel } from "@cursor/july/internal/otel";
  *
  * export default defineOtel({
  *   serviceName: "cursor",
@@ -13,6 +13,8 @@
  * // Hosted v2: re-read env on flush after deployment secrets bind.
  * export default defineOtel(() => resolveMyOtelConfig());
  * ```
+ *
+ * Internal only: Cursor factory agents. Not a public Agent SDK export.
  */
 
 import { AsyncLocalStorage } from "node:async_hooks";
@@ -107,7 +109,10 @@ export const OTEL_CONFIG_RESOLVE: symbol = Symbol.for(
   "anysphere.july.otel.configResolve"
 );
 
-/** Author OpenTelemetry export under `agent/otel.ts`. */
+/**
+ * Author OpenTelemetry export under `agent/otel.ts`.
+ * Import from `@cursor/july/internal/otel`, not `@cursor/july`.
+ */
 export function defineOtel(
   config: OtelConfig | OtelConfigFactory = {}
 ): OtelDefinition {

package/src/prompt.ts

@@ -61,7 +61,7 @@ function dedentLines(
   if (!Number.isFinite(minIndent)) {
     minIndent = 0;
   }
-  return lines.map((line) => (line.trim() === "" ? "" : line.slice(minIndent)));
+  return lines.map(line => (line.trim() === "" ? "" : line.slice(minIndent)));
 }
 
 export type PromptTag = {

package/src/result.ts

@@ -2,8 +2,10 @@
  * `defineResult` — authored at `agent/result.ts`.
  *
  * After the model finishes, `commit` runs on the serving host with the
- * full assistant text. Throw to fail the turn. Parse `ctx.text` however
- * the agent needs.
+ * full assistant text. Throw to fail the turn. Call `ctx.reject(message)`
+ * when the model can still fix the output; the host re-runs the same
+ * turn with that message (two repairs). Parse `ctx.text` however the
+ * agent needs.
  *
  * ```ts
  * import { defineResult } from "@cursor/july/result";
@@ -13,7 +15,11 @@
  *     if (ctx.session.purpose === "eval") {
  *       return;
  *     }
- *     await applyDecision(parseDecision(ctx.text), ctx.host);
+ *     const parsed = parseDecision(ctx.text);
+ *     if (parsed === undefined) {
+ *       ctx.reject("End the turn with a decision document.");
+ *     }
+ *     await applyDecision(parsed, ctx.host);
  *   },
  * });
  * ```
@@ -22,11 +28,7 @@
 import { brandDefinition } from "./internal/brand.js";
 import type { ResultConfig, ResultDefinition } from "./types.js";
 
-export type {
-  ResultConfig,
-  ResultContext,
-  ResultDefinition,
-} from "./types.js";
+export type { ResultConfig, ResultContext, ResultDefinition } from "./types.js";
 
 export function defineResult(config: ResultConfig): ResultDefinition {
   if (typeof config.commit !== "function") {

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

@@ -170,7 +170,7 @@ export function cursorHostedStorageV2(
     },
     async list(prefix): Promise<StorageEntry[]> {
       const entries = await listAllPages(options, { prefix });
-      return entries.map((entry) => ({
+      return entries.map(entry => ({
         key: entry.key,
         value: entry.value ?? null,
       }));
@@ -208,7 +208,7 @@ export function cursorHostedStorageV2(
           prefix,
           keysOnly: true,
         });
-        return entries.map((entry) => entry.key);
+        return entries.map(entry => entry.key);
       },
     },
     evals: v1.evals,

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

@@ -10,16 +10,9 @@
  * 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/file-kv` instead.
- *
- * ```ts
- * import { defineStorage } from "@cursor/july/storage";
- * import { cursorHostedStorage } from "@cursor/july/storage/cursor-hosted";
- *
- * export default defineStorage({
- *   ...cursorHostedStorage(),
- * });
- * ```
+ * a deployment SA key, or use `@cursor/july/internal/file-kv` instead.
+ * Wiring it into a storage sink is internal-only `defineStorage`
+ * territory (see `storage.ts`).
  */
 
 import type { EvalRunSnapshot } from "../evals.js";
@@ -41,13 +34,6 @@ import type { JsonValue, KvCasResult, KvVersionedEntry } from "../types.js";
  */
 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.
@@ -57,15 +43,12 @@ export const AGENT_SERVE_DEPLOYMENT_ID_ENV_VAR =
 
 /**
  * Platform-managed secret / env names. User `secrets set` / DELETE cannot
- * claim these.
+ * claim these. Hosted storage talks to the HTTP proxy; engines never
+ * receive a database URL.
  */
 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,
-];
+] = [AGENT_SERVE_DEPLOYMENT_ID_ENV_VAR];
 
 export interface CursorHostedStorageOptions {
   /**

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

@@ -145,9 +145,9 @@ export function fileKv(options?: FileKvOptions): FileKvMethods {
         throw error;
       }
       const keys = names
-        .filter((name) => name.endsWith(".json"))
-        .map((name) => decodeURIComponent(name.slice(0, -".json".length)))
-        .filter((key) => key.startsWith(prefix))
+        .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) {
@@ -215,9 +215,9 @@ export function fileKv(options?: FileKvOptions): FileKvMethods {
           throw error;
         }
         return names
-          .filter((name) => name.endsWith(".json"))
-          .map((name) => decodeURIComponent(name.slice(0, -".json".length)))
-          .filter((key) => key.startsWith(prefix))
+          .filter(name => name.endsWith(".json"))
+          .map(name => decodeURIComponent(name.slice(0, -".json".length)))
+          .filter(key => key.startsWith(prefix))
           .sort();
       },
     },
@@ -248,7 +248,7 @@ export function fileKv(options?: FileKvOptions): FileKvMethods {
           throw error;
         }
         const runs: EvalRunSnapshot[] = [];
-        for (const name of names.filter((n) => n.endsWith(".json")).sort()) {
+        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 {

package/src/storage.ts

@@ -15,7 +15,7 @@
  * analytics pipeline), not as a required-or-lose-history hook:
  *
  * ```ts
- * import { defineStorage } from "@cursor/july/storage";
+ * import { defineStorage } from "@cursor/july/internal/storage";
  *
  * export default defineStorage({
  *   put: (key, value) => db.upsert(key, value),
@@ -225,6 +225,20 @@ export interface StorageConfig {
    * growing memory; it never stalls the agent loop.
    */
   put(key: string, value: JsonValue, ctx: StorageContext): void | Promise<void>;
+  /**
+   * Store several values in one call. Optional — the coordinator uses it
+   * only when present, so authored sinks keep `put`'s strict one-at-a-time
+   * ordering. Entries belong to one flush and are independent keys; the
+   * implementation may write them in a single backend round trip. Report
+   * per-entry outcomes, index-aligned with the input: one key's failure
+   * must not take down its batch siblings. A thrown rejection is treated
+   * as every entry failing (logged and dropped, at-most-once) — reserve it
+   * for faults that genuinely precede any write.
+   */
+  putMany?(
+    entries: Array<{ key: string; value: JsonValue }>,
+    ctx: StorageContext
+  ): Promise<Array<{ key: string; error?: unknown }>>;
   /** Remove a key. Optional — without it, deletions are skipped. */
   delete?(key: string, ctx: StorageContext): void | Promise<void>;
   /**
@@ -269,13 +283,14 @@ export type StorageDefinition = StorageConfig & {
 
 /**
  * Author the project storage sink (`agent/storage.ts`, default
- * export). See the module doc for semantics and an example.
+ * export). Import from `@cursor/july/internal/storage`, not
+ * `@cursor/july`. See the module doc for semantics and an example.
  */
 export function defineStorage(config: StorageConfig): StorageDefinition {
   if (typeof config.put !== "function") {
     throw new Error("defineStorage: config.put must be a function");
   }
-  for (const hook of ["get", "list", "delete"] as const) {
+  for (const hook of ["get", "list", "delete", "putMany"] as const) {
     const value = config[hook];
     if (value !== undefined && typeof value !== "function") {
       throw new Error(
@@ -303,12 +318,12 @@ export function defineStorage(config: StorageConfig): StorageDefinition {
     // A partial group is a bug, not a legacy config: half-implemented CAS
     // would pass the capability probe.
     const missingCasHooks = casHooks.filter(
-      (hook) => typeof cas[hook] !== "function"
+      hook => typeof cas[hook] !== "function"
     );
     if (missingCasHooks.length > 0) {
       throw new Error(
         `defineStorage: ${missingCasHooks
-          .map((hook) => `cas.${hook}`)
+          .map(hook => `cas.${hook}`)
           .join(
             ", "
           )} must be ${missingCasHooks.length === 1 ? "a function" : "functions"} when the cas group is set`
@@ -350,11 +365,11 @@ function deriveEvalsTable(
       ),
     delete: (runId, ctx) =>
       config.delete?.(storageKeys.evalRun(ctx.agentName, runId), ctx),
-    list: async (ctx) => {
+    list: async ctx => {
       const entries =
         (await config.list?.(storageKeys.evalRunsPrefix(ctx.agentName), ctx)) ??
         [];
-      return entries.map((entry) => entry.value as unknown as EvalRunSnapshot);
+      return entries.map(entry => entry.value as unknown as EvalRunSnapshot);
     },
   };
 }