@cursor/july 0.1.33 → 0.1.34

package/dist/memory.d.ts

@@ -16,11 +16,13 @@
  * 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 { type FileSink } from "./files.js";
 import type { HookDefinition, TurnUsage } from "./types.js";
 /** Name of the shared memory directory under the agent state root. */
 export declare const MEMORY_DIR_NAME = "memory";
@@ -41,10 +43,11 @@ export type TurnMemoryRecord = {
     result?: string;
     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;
+        agentName: string;
     }): Promise<void>;
 }
 export interface FileMemoryBackendOptions {
@@ -55,11 +58,24 @@ export interface FileMemoryBackendOptions {
     maxJournalBytes?: number;
 }
 /**
- * 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`.
  */
 export declare function fileMemoryBackend(options?: FileMemoryBackendOptions): MemoryBackend;
+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 declare function agentStoreMemoryBackend(options?: AgentStoreMemoryBackendOptions): MemoryBackend;
 export interface MemoryHookOptions {
     /** Where records go. Defaults to {@link fileMemoryBackend}. */
     backend?: MemoryBackend;

package/dist/memory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../src/memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAKH,OAAO,KAAK,EAAe,cAAc,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEzE,sEAAsE;AACtE,eAAO,MAAM,eAAe,WAAW,CAAC;AAExC,gDAAgD;AAChD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,+CAA+C;IAC/C,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,WAAW,GAAG,QAAQ,CAAC;IAC/B,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB,CAAC;AAEF,yEAAyE;AACzE,MAAM,WAAW,aAAa;IAC5B,UAAU,CACR,MAAM,EAAE,gBAAgB,EACxB,GAAG,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,GACzB,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,GAAE,wBAA6B,GACrC,aAAa,CAgCf;AAED,MAAM,WAAW,iBAAiB;IAChC,+DAA+D;IAC/D,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,yEAAyE;IACzE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAMD;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,cAAc,CAuF1E"}
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../src/memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH,OAAO,EAAqC,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAM9E,OAAO,KAAK,EAAe,cAAc,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEzE,sEAAsE;AACtE,eAAO,MAAM,eAAe,WAAW,CAAC;AAExC,gDAAgD;AAChD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,+CAA+C;IAC/C,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,WAAW,GAAG,QAAQ,CAAC;IAC/B,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB,CAAC;AAEF,kFAAkF;AAClF,MAAM,WAAW,aAAa;IAC5B,UAAU,CACR,MAAM,EAAE,gBAAgB,EACxB,GAAG,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAC5C,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,GAAE,wBAA6B,GACrC,aAAa,CAgCf;AAED,MAAM,WAAW,8BAA8B;IAC7C,uEAAuE;IACvE,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,4EAA4E;IAC5E,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,GAAE,8BAAmC,GAC3C,aAAa,CAsEf;AAqBD,MAAM,WAAW,iBAAiB;IAChC,+DAA+D;IAC/D,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,yEAAyE;IACzE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAMD;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,cAAc,CA0F1E"}

package/dist/memory.js

@@ -16,10 +16,11 @@
  * 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.
  */
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
@@ -30,13 +31,16 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-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 } from "./files.js";
+import { cursorHostedFiles, isCursorHostedFilesAvailable, } from "./files-backends/cursor-hosted.js";
 import { defineHook } from "./hooks.js";
 /** Name of the shared memory directory under the agent state root. */
 export const MEMORY_DIR_NAME = "memory";
 /**
- * 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`.
  */
@@ -76,6 +80,91 @@ export function fileMemoryBackend(options = {}) {
         },
     };
 }
+/**
+ * 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 = {}) {
+    var _a, _b;
+    const sink = (_a = options.sink) !== null && _a !== void 0 ? _a : cursorHostedFiles();
+    const maxJournalBytes = (_b = options.maxJournalBytes) !== null && _b !== void 0 ? _b : 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();
+    const append = (record, ctx) => __awaiter(this, void 0, void 0, function* () {
+        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 = yield 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;
+            let rotatedStamp;
+            if (currentBody.byteLength >= maxJournalBytes) {
+                rotatedStamp = `${Date.now()}-${randomUUID().slice(0, 8)}`;
+                yield sink.put(agentStoreKeys.memoryJournalRotated(ctx.agentName, rotatedStamp), currentBody, { ifMatch: null });
+                next = line;
+            }
+            else {
+                next = Buffer.concat([currentBody, line]);
+            }
+            try {
+                yield sink.put(key, next, {
+                    ifMatch: current === undefined ? null : etag,
+                });
+            }
+            catch (error) {
+                if (error instanceof FileConflictError && attempt < 2) {
+                    continue;
+                }
+                throw error;
+            }
+            yield 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.
+                yield writeFile(join(ctx.stateRoot, MEMORY_DIR_NAME, `journal-${rotatedStamp}.jsonl`), currentBody);
+            }
+            return;
+        }
+    });
+    return {
+        appendTurn(record, ctx) {
+            return __awaiter(this, void 0, void 0, function* () {
+                var _a;
+                const key = agentStoreKeys.memoryJournal(ctx.agentName);
+                const prior = (_a = appendChains.get(key)) !== null && _a !== void 0 ? _a : Promise.resolve();
+                const next = prior.catch(() => { }).then(() => append(record, ctx));
+                appendChains.set(key, next);
+                yield next;
+            });
+        },
+    };
+}
+/** Atomic full rewrite of the local mirror; also hydrates a fresh pod after a deploy. */
+function mirrorJournalLocally(stateRoot, contents) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const dir = join(stateRoot, MEMORY_DIR_NAME);
+        yield mkdir(dir, { recursive: true });
+        const tmp = join(dir, `.tmp-${randomUUID()}`);
+        yield writeFile(tmp, contents);
+        yield rename(tmp, join(dir, "journal.jsonl"));
+    });
+}
+/** Hosted deployments journal to the Agent Store; local dev to plain files. */
+function defaultMemoryBackend() {
+    return isCursorHostedFilesAvailable()
+        ? agentStoreMemoryBackend()
+        : fileMemoryBackend();
+}
 function truncate(text, max) {
     return text.length <= max ? text : `${text.slice(0, max)}…`;
 }
@@ -90,7 +179,7 @@ function truncate(text, max) {
  */
 export function memoryHook(options = {}) {
     var _a, _b;
-    const backend = (_a = options.backend) !== null && _a !== void 0 ? _a : fileMemoryBackend();
+    const backend = (_a = options.backend) !== null && _a !== void 0 ? _a : defaultMemoryBackend();
     const maxTextLength = (_b = options.maxTextLength) !== null && _b !== void 0 ? _b : 2000;
     // Inbound message per turn (truncated at receipt so large pastes are not
     // retained), keyed `<sessionId>/<turnId>` — `message.received` and the
@@ -123,7 +212,10 @@ export function memoryHook(options = {}) {
         if (usage !== undefined) {
             entry.usage = usage;
         }
-        yield backend.appendTurn(entry, { stateRoot: ctx.stateRoot });
+        yield backend.appendTurn(entry, {
+            stateRoot: ctx.stateRoot,
+            agentName: ctx.agent.name,
+        });
     });
     const sweepSession = (ctx) => {
         for (const key of pendingMessages.keys()) {