@cursor/july 0.1.33 → 0.1.35

package/src/internal/storage-coordinator.ts

@@ -14,6 +14,13 @@
  * and A/B metrics go to their dedicated tables (`evals` / `abs`).
  * Reminder documents live on the control plane. Everything shares one
  * bounded, serialized queue.
+ *
+ * It does three unrelated jobs, declared separately as
+ * {@link FrameworkSessionStore}, {@link AuthorKvStore}, and
+ * {@link EvalAbStore} — see `storage-roles.ts` for why they differ and where
+ * each is headed. The queue stays shared: it is one bounded, serialized chain
+ * per agent, and splitting it would change backpressure behavior, which this
+ * seam deliberately does not touch.
  */
 
 import type { ABMetricSample } from "../ab.js";
@@ -30,6 +37,11 @@ import type { JsonValue, SessionEvent, SessionRecord } from "../types.js";
 import type { ABSnapshot } from "./ab-snapshot.js";
 import { describeError } from "./describe-error.js";
 import type { EvalRunStorage } from "./eval-run-store.js";
+import type {
+  AuthorKvStore,
+  EvalAbStore,
+  FrameworkSessionStore,
+} from "./storage-roles.js";
 
 /** Event types that close a unit of work — flush point for turn-end batching. */
 const TURN_BOUNDARY_EVENTS: ReadonlySet<SessionEvent["type"]> = new Set([
@@ -85,7 +97,9 @@ interface SessionBuffer {
   debounceTimer?: ReturnType<typeof setTimeout>;
 }
 
-export class StorageCoordinator {
+export class StorageCoordinator
+  implements FrameworkSessionStore, AuthorKvStore, EvalAbStore
+{
   readonly policy: ResolvedStoragePolicy;
 
   private readonly definition: StorageDefinition;
@@ -458,68 +472,6 @@ export class StorageCoordinator {
     await this.definition.delete?.(key, this.context("policy"));
   }
 
-  // ==========================================================================
-  // Artifacts (`ctx.artifacts`)
-  // ==========================================================================
-
-  /**
-   * Whether the sink can serve awaited artifact rows: `get` (upsert
-   * read-back), `list` (listing + eviction), and `delete` (`max` cap
-   * eviction) are all required — without `delete` the retention cap
-   * could never evict, so rows fall back to the filesystem store.
-   */
-  get supportsArtifacts(): boolean {
-    return (
-      this.definition.get !== undefined &&
-      this.definition.list !== undefined &&
-      this.definition.delete !== undefined
-    );
-  }
-
-  /** Awaited artifact-row read. Errors propagate (read-after-write). */
-  async artifactGet(id: string): Promise<JsonValue | undefined> {
-    const get = this.definition.get;
-    if (get === undefined) {
-      throw new Error("storage get is not configured");
-    }
-    const value = await get(
-      storageKeys.artifact(this.agentName, id),
-      this.context("restore")
-    );
-    return value ?? undefined;
-  }
-
-  /** Awaited artifact-row write (straight to the sink, like author KV). */
-  async artifactPut(id: string, value: JsonValue): Promise<void> {
-    await this.definition.put(
-      storageKeys.artifact(this.agentName, id),
-      value,
-      this.context("policy")
-    );
-  }
-
-  /** Awaited artifact-row delete. Errors propagate (cap eviction). */
-  async artifactDelete(id: string): Promise<void> {
-    const del = this.definition.delete;
-    if (del === undefined) {
-      throw new Error("storage delete is not configured");
-    }
-    await del(storageKeys.artifact(this.agentName, id), this.context("policy"));
-  }
-
-  /** All artifact-row values for this agent. Errors propagate. */
-  async artifactList(): Promise<JsonValue[]> {
-    const list = this.definition.list;
-    if (list === undefined) {
-      throw new Error("storage list is not configured");
-    }
-    const entries = await list(
-      storageKeys.artifactPrefix(this.agentName),
-      this.context("restore")
-    );
-    return Array.isArray(entries) ? entries.map((entry) => entry.value) : [];
-  }
-
   // ==========================================================================
   // Evals (dedicated `evals` table)
   // ==========================================================================

package/src/internal/storage-roles.ts

@@ -0,0 +1,86 @@
+/**
+ * The three unrelated jobs `defineStorage` currently does, named separately.
+ *
+ * {@link import("./storage-coordinator.js").StorageCoordinator} implements all
+ * three today over one sink and one delivery queue. Splitting the *types* is
+ * the seam that lets each job change independently:
+ *
+ * - {@link FrameworkSessionStore} is framework state. Session records, event
+ *   chunks, and the continuation index are how a session survives the process,
+ *   so they belong to Agent Serve, not to the agent. Today they persist only
+ *   when the author writes `agent/storage.ts` — the defect this seam exists to
+ *   let us fix, by giving the framework its own provider that is automatic and
+ *   not author-configurable.
+ * - {@link AuthorKvStore} is author state: whatever `ctx.host.kv` was handed.
+ *   It converges onto the author file plane, which is a different destination
+ *   from the one above.
+ * - {@link EvalAbStore} is playground/experiment bookkeeping with its own
+ *   dedicated tables, and follows neither.
+ *
+ * Consumers should depend on the narrowest role they use. That is what keeps a
+ * later change to framework persistence from silently reaching author KV, and
+ * it is why these are interfaces rather than a comment on one class.
+ */
+
+import type { ABMetricSample } from "../ab.js";
+import type { StorageContext } from "../storage.js";
+import type { JsonValue, SessionEvent, SessionRecord } from "../types.js";
+import type { ABSnapshot } from "./ab-snapshot.js";
+import type { EvalRunStorage } from "./eval-run-store.js";
+
+/**
+ * Framework-owned session durability: what has to be true for a session to
+ * outlive the process that served it.
+ *
+ * Writes are fire-and-forget by design — a throwing backend is logged and its
+ * write dropped, because storage must never stall or fail a turn. That is
+ * at-most-once, and it is the property Track F later has to tighten, since a
+ * dropped record is a session that cannot be restored.
+ */
+export interface FrameworkSessionStore {
+  /** Durable session-record update; coalesced until the next flush. */
+  sessionRecord(record: SessionRecord): void;
+  /** One appended session event; batched per turn or debounce window. */
+  event(event: SessionEvent): void;
+  /** Marks an event delivered, for backends that track dispatch. */
+  eventDispatched(event: SessionEvent): void;
+  /** Flush everything buffered for one session (ordered: events, record). */
+  flushSession(sessionId: string, reason?: StorageContext["reason"]): void;
+
+  /** True when the backend can list every session in one bulk read. */
+  readonly canBulkRestore: boolean;
+  /** True when the backend is the Cursor-hosted one rather than an authored sink. */
+  readonly isCursorHosted: boolean;
+
+  listSessions(): Promise<SessionRecord[]>;
+  listSessionsFromSink(): Promise<SessionRecord[]>;
+  listSessionEvents(sessionId: string): Promise<SessionEvent[]>;
+  getSessionById(sessionId: string): Promise<SessionRecord | undefined>;
+  getSessionByContinuation(
+    channelId: string,
+    continuationKey: string
+  ): Promise<SessionRecord | undefined>;
+}
+
+/**
+ * Author-facing durable JSON behind `ctx.host.kv`.
+ *
+ * Deployment-wide on purpose: the point is state an author saves in one
+ * session and reads back in a later one, so unlike `ctx.host.files` there is
+ * no session scope to default to.
+ */
+export interface AuthorKvStore {
+  /** False when no backend is configured; callers fall back to local disk. */
+  readonly supportsAuthorKv: boolean;
+  kvGet(authorKey: string): Promise<JsonValue | undefined>;
+  kvPut(authorKey: string, value: JsonValue): Promise<void>;
+  kvDelete(authorKey: string): Promise<void>;
+}
+
+/** Playground eval batches and live A/B metrics, on their own tables. */
+export interface EvalAbStore {
+  evalRuns(): EvalRunStorage | undefined;
+  abSample(sample: ABMetricSample): void;
+  abSnapshot(snapshot: ABSnapshot): void;
+  getLatestAbSnapshot(): Promise<ABSnapshot | undefined>;
+}

package/src/internal/workspace.ts

@@ -19,6 +19,7 @@ import {
   writeFile,
 } from "node:fs/promises";
 import { dirname, join, parse, relative, resolve, sep } from "node:path";
+import { agentStoreKeys, DEPLOYMENT_STORE_MOUNT_PATH } from "../files.js";
 import { MEMORY_DIR_NAME } from "../memory.js";
 import type {
   DiscoveredSkill,
@@ -38,20 +39,41 @@ export interface MaterializeWorkspaceOptions {
   seed: boolean;
   /**
    * Agent state root. `<stateRoot>/memory/` (the durable cross-session
-   * directory the memory hook journals into) is created and symlinked into
-   * the workspace as `memory` so the agent reads it with plain file tools.
-   *
-   * TODO(agent-store): replace with the mounted AgentStore path so cloud
-   * VMs see the same directory.
+   * directory the memory hook journals into — on hosting a local mirror of
+   * the Agent Store journal) is created and symlinked into the workspace as
+   * `memory` so the agent reads it with plain file tools. Cloud VMs have no
+   * materialized workspace; they read the store mount directly (see
+   * {@link buildCloudMemorySection}).
    */
   stateRoot: string;
 }
 
+/**
+ * First-turn preamble section for cloud-runtime sessions on hosted
+ * deployments: cloud VMs read the memory journal from the store mount.
+ */
+export function buildCloudMemorySection(agentName: string): string {
+  const dir = `${DEPLOYMENT_STORE_MOUNT_PATH}/${agentStoreKeys.memoryDir(agentName)}`;
+  return [
+    "## Shared session memory",
+    "",
+    `The cross-session memory journal (the \`memory/\` directory your instructions may reference) lives at \`${dir}\` on this machine — read \`${dir}/journal.jsonl\` with your normal file tools.`,
+  ].join("\n");
+}
+
 /** Relative path of an agent-side tool script inside the session workspace. */
 export function agentToolScriptPath(toolName: string): string {
   return `.agent-serve/tools/${toolName}.sh`;
 }
 
+/**
+ * Reserved MCP connection name under which authored server tools are served
+ * to cloud turns (the session-bound tool MCP endpoint). Shared between the
+ * turn's MCP config and the first-prompt server-tool catalog so the model is
+ * told exactly where those tools live.
+ */
+export const SERVER_TOOLS_MCP_SERVER_NAME = "agentsdk-tools";
+
 /**
  * Always-on identity line prepended when composing instructions. Sourced from
  * {@link ResolvedAgent.name} (`defineAgent({ name })`, else package/dir name)
@@ -143,16 +165,64 @@ export function buildAgentToolsCatalog(
   return `${parts.join("\n").trimEnd()}\n`;
 }
 
+/**
+ * Markdown catalog of authored server tools for the cloud first prompt.
+ *
+ * Server tools execute on the serve host and reach cloud turns only as MCP
+ * tools on {@link SERVER_TOOLS_MCP_SERVER_NAME}. Instructions reference them
+ * by bare name, and the agent-tool catalog teaches a "recreate the script if
+ * missing" pattern — without this section a cloud model that cannot find a
+ * script for a server tool improvises a local substitute instead of calling
+ * the real tool, so its host-side effects silently never happen.
+ */
+export function buildServerToolsCatalog(
+  tools: DiscoveredTool[],
+  options: { mcpServerName: string }
+): string {
+  const serverTools = tools.filter((tool) => tool.execution === "server");
+  if (serverTools.length === 0) {
+    return "";
+  }
+
+  const parts: string[] = [
+    "## Server tools",
+    "",
+    `These tools execute on the agent-serve host, not in this environment. They are available ONLY as MCP tools on the \`${options.mcpServerName}\` MCP server — list that server's tools and call them by name through your MCP tooling.`,
+    "There are no local scripts for these tools. NEVER create, edit, or run a local script or other substitute for them: a local re-implementation cannot produce their real effects on the host.",
+    "",
+  ];
+
+  for (const tool of serverTools) {
+    parts.push(`### \`${tool.name}\``);
+    parts.push("");
+    parts.push(tool.description.trim());
+    parts.push("");
+    parts.push("Input schema:");
+    parts.push("");
+    parts.push("```json");
+    parts.push(JSON.stringify(tool.inputSchema, null, 2));
+    parts.push("```");
+    parts.push("");
+  }
+
+  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}).
+ *
+ * `serverToolsMcpName` is cloud-only: when the turn's MCP config carries the
+ * session-bound server-tool endpoint, the catalog names that server so the
+ * model calls the real tools instead of inventing local stand-ins. Local
+ * runtimes omit it — there the harness exposes server tools natively.
  */
 export function buildAgentsMdContent(
   agent: ResolvedAgent,
-  options: { includeScripts: boolean }
+  options: { includeScripts: boolean; serverToolsMcpName?: string }
 ): string {
   return [
     agent.instructions?.trim() ?? "",
@@ -160,6 +230,11 @@ export function buildAgentsMdContent(
     buildAgentToolsCatalog(agent.tools, {
       includeScripts: options.includeScripts,
     }),
+    options.serverToolsMcpName === undefined
+      ? ""
+      : buildServerToolsCatalog(agent.tools, {
+          mcpServerName: options.serverToolsMcpName,
+        }),
   ]
     .filter((part) => part !== "")
     .join("\n\n");

package/src/memory.ts

@@ -16,14 +16,21 @@
  * path — typically a server tool under `agent/tools/`, which can resolve
  * state via `ctx.stateRoot`.
  *
- * TODO(agent-store): once agent-serve can mount the agent's AgentStore
- * (durable S3-backed filesystem shared across serve hosts and cloud VMs),
- * ship an AgentStore-backed backend and make it the default. The journal
- * format is designed to survive that move unchanged.
+ * On Cursor-managed hosting the default is {@link agentStoreMemoryBackend}:
+ * the journal lives on the deployment's Agent Store (survives deploys,
+ * visible on cloud VMs under the store mount) and is mirrored to
+ * `<stateRoot>/memory/journal.jsonl` so the workspace symlink read path
+ * keeps working for local-runtime turns.
  */
 
-import { appendFile, mkdir, rename, stat } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { appendFile, mkdir, rename, stat, writeFile } from "node:fs/promises";
 import { join } from "node:path";
+import { agentStoreKeys, FileConflictError, type FileSink } from "./files.js";
+import {
+  cursorHostedFiles,
+  isCursorHostedFilesAvailable,
+} from "./files-backends/cursor-hosted.js";
 import { defineHook } from "./hooks.js";
 import type { HookContext, HookDefinition, TurnUsage } from "./types.js";
 
@@ -48,11 +55,11 @@ export type TurnMemoryRecord = {
   usage?: TurnUsage;
 };
 
-/** Where turn records go. Receives the agent's state root per append. */
+/** Where turn records go. Receives the agent's state root and name per append. */
 export interface MemoryBackend {
   appendTurn(
     record: TurnMemoryRecord,
-    ctx: { stateRoot: string }
+    ctx: { stateRoot: string; agentName: string }
   ): Promise<void>;
 }
 
@@ -65,7 +72,7 @@ export interface FileMemoryBackendOptions {
 }
 
 /**
- * Default backend: append-only JSONL at `<stateRoot>/memory/journal.jsonl`
+ * Local default backend: append-only JSONL at `<stateRoot>/memory/journal.jsonl`
  * — the directory the framework symlinks into session workspaces. Rotated
  * segments stay alongside as `journal-<epoch-ms>.jsonl`.
  */
@@ -105,6 +112,112 @@ export function fileMemoryBackend(
   };
 }
 
+export interface AgentStoreMemoryBackendOptions {
+  /** Sink override (tests). Defaults to the deployment's Agent Store. */
+  sink?: FileSink;
+  /** Rotation threshold, same meaning as {@link FileMemoryBackendOptions}. */
+  maxJournalBytes?: number;
+}
+
+/**
+ * Journal on the deployment's Agent Store — durable across deploys, visible
+ * on cloud VMs under the store mount. Appends are read-modify-write with
+ * etag preconditions (retried on a lost race), then mirrored to
+ * `<stateRoot>/memory/journal.jsonl` for the workspace symlink read path.
+ */
+export function agentStoreMemoryBackend(
+  options: AgentStoreMemoryBackendOptions = {}
+): MemoryBackend {
+  const sink = options.sink ?? cursorHostedFiles();
+  const maxJournalBytes = options.maxJournalBytes ?? 5 * 1024 * 1024;
+  // Appends are chained per journal key (same shape as fileMemoryBackend);
+  // a failed append must not poison the chain for later turns.
+  const appendChains = new Map<string, Promise<void>>();
+
+  const append = async (
+    record: TurnMemoryRecord,
+    ctx: { stateRoot: string; agentName: string }
+  ): Promise<void> => {
+    const key = agentStoreKeys.memoryJournal(ctx.agentName);
+    const line = Buffer.from(`${JSON.stringify(record)}\n`, "utf8");
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      const current = await sink.get(key);
+      const currentBody =
+        current === undefined
+          ? new Uint8Array(0)
+          : current instanceof Uint8Array
+            ? current
+            : current.body;
+      const etag =
+        current === undefined || current instanceof Uint8Array
+          ? undefined
+          : current.etag;
+      let next: Uint8Array;
+      let rotatedStamp: string | undefined;
+      if (currentBody.byteLength >= maxJournalBytes) {
+        rotatedStamp = `${Date.now()}-${randomUUID().slice(0, 8)}`;
+        await sink.put(
+          agentStoreKeys.memoryJournalRotated(ctx.agentName, rotatedStamp),
+          currentBody,
+          { ifMatch: null }
+        );
+        next = line;
+      } else {
+        next = Buffer.concat([currentBody, line]);
+      }
+      try {
+        await sink.put(key, next, {
+          ifMatch: current === undefined ? null : etag,
+        });
+      } catch (error) {
+        if (error instanceof FileConflictError && attempt < 2) {
+          continue;
+        }
+        throw error;
+      }
+      await mirrorJournalLocally(ctx.stateRoot, next);
+      if (rotatedStamp !== undefined) {
+        // Rotated segments sit beside the live journal locally too, so the
+        // workspace symlink read path keeps pre-rotation history.
+        await writeFile(
+          join(ctx.stateRoot, MEMORY_DIR_NAME, `journal-${rotatedStamp}.jsonl`),
+          currentBody
+        );
+      }
+      return;
+    }
+  };
+
+  return {
+    async appendTurn(record, ctx) {
+      const key = agentStoreKeys.memoryJournal(ctx.agentName);
+      const prior = appendChains.get(key) ?? Promise.resolve();
+      const next = prior.catch(() => {}).then(() => append(record, ctx));
+      appendChains.set(key, next);
+      await next;
+    },
+  };
+}
+
+/** Atomic full rewrite of the local mirror; also hydrates a fresh pod after a deploy. */
+async function mirrorJournalLocally(
+  stateRoot: string,
+  contents: Uint8Array
+): Promise<void> {
+  const dir = join(stateRoot, MEMORY_DIR_NAME);
+  await mkdir(dir, { recursive: true });
+  const tmp = join(dir, `.tmp-${randomUUID()}`);
+  await writeFile(tmp, contents);
+  await rename(tmp, join(dir, "journal.jsonl"));
+}
+
+/** Hosted deployments journal to the Agent Store; local dev to plain files. */
+function defaultMemoryBackend(): MemoryBackend {
+  return isCursorHostedFilesAvailable()
+    ? agentStoreMemoryBackend()
+    : fileMemoryBackend();
+}
+
 export interface MemoryHookOptions {
   /** Where records go. Defaults to {@link fileMemoryBackend}. */
   backend?: MemoryBackend;
@@ -126,7 +239,7 @@ function truncate(text: string, max: number): string {
  * ```
  */
 export function memoryHook(options: MemoryHookOptions = {}): HookDefinition {
-  const backend = options.backend ?? fileMemoryBackend();
+  const backend = options.backend ?? defaultMemoryBackend();
   const maxTextLength = options.maxTextLength ?? 2000;
   // Inbound message per turn (truncated at receipt so large pastes are not
   // retained), keyed `<sessionId>/<turnId>` — `message.received` and the
@@ -167,7 +280,10 @@ export function memoryHook(options: MemoryHookOptions = {}): HookDefinition {
     if (usage !== undefined) {
       entry.usage = usage;
     }
-    await backend.appendTurn(entry, { stateRoot: ctx.stateRoot });
+    await backend.appendTurn(entry, {
+      stateRoot: ctx.stateRoot,
+      agentName: ctx.agent.name,
+    });
   };
 
   const sweepSession = (ctx: HookContext): void => {

package/src/storage.ts

@@ -276,7 +276,6 @@ export const STORAGE_KEY_ROOT = "agentkit/v1" as const;
  * | `agentkit/v1/{agent}/session-events/{sessionId}/{index}` | `SessionEvent[]` chunk (index = first event's index, zero-padded) |
  * | `agentkit/v1/{agent}/continuation/{channelId}/{token}` | `{ sessionId }` |
  * | `agentkit/v1/{agent}/kv/{key}` | Author JSON via {@link HostContext.kv} |
- * | `agentkit/v1/{agent}/artifacts/{id}` | `ArtifactRecord` via `ctx.artifacts` |
  *
  * Eval-run and A/B history do not flow through this KV scheme — they have
  * dedicated tables ({@link StorageConfig.evals} / {@link StorageConfig.abs}).
@@ -307,11 +306,6 @@ export const storageKeys = {
   kv: (agent: string, key: string): string =>
     `${STORAGE_KEY_ROOT}/${agent}/kv/${keySegment(key)}`,
   kvPrefix: (agent: string): string => `${STORAGE_KEY_ROOT}/${agent}/kv/`,
-  /** Tagged artifact rows (see `ctx.artifacts` / `ArtifactsApi`). */
-  artifact: (agent: string, id: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/artifacts/${keySegment(id)}`,
-  artifactPrefix: (agent: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/artifacts/`,
 } as const;
 
 /**

package/src/types.ts

@@ -1838,6 +1838,8 @@ export interface ArtifactRecord {
   key?: string;
   title?: string;
   data: JsonValue;
+  /** Present when the artifact carries a file/blob payload (served at `GET /v1/artifacts/:id/content`). */
+  content?: { size: number; contentType?: string };
   sessionId?: string;
   turnId?: string;
   source: ArtifactSource;
@@ -1853,6 +1855,13 @@ export interface ArtifactTagInput {
   title?: string;
   /** Upsert key: tagging the same key again replaces the row. */
   key?: string;
+  /**
+   * File/blob payload, served via `GET /v1/artifacts/:id/content`.
+   * Re-tagging a keyed artifact without `contents` keeps the existing payload.
+   */
+  contents?: string | Uint8Array;
+  /** MIME type reported when serving {@link contents}. */
+  contentType?: string;
   /**
    * Session to attribute (and stream an `artifact.tagged` event to). On
    * session-bound facades ({@link ToolContext.artifacts},
@@ -2460,6 +2469,12 @@ export interface ServeOptions {
    * Local turns always use the loopback URL.
    */
   publicUrl?: string;
+  /**
+   * Authenticated HTTP MCP URL that proxies this hosted deployment's
+   * `/v1/mcp/tools` endpoint. Cloud turns use it to call authored server tools
+   * on the AgentSDK host. The resolved Cursor API key authenticates requests.
+   */
+  cloudToolsUrl?: string;
   /**
    * Pull GitHub webhook metadata from `/v0/scm-events` (Cursor account auth).
    * The stream is read as the host's Cursor user, so this requires a signed-in