@cursor/july 0.1.33 → 0.1.35

package/dist/internal/storage-roles.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 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>;
+}
+//# sourceMappingURL=storage-roles.d.ts.map

package/dist/internal/storage-roles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-roles.d.ts","sourceRoot":"","sources":["../../src/internal/storage-roles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D;;;;;;;;GAQG;AACH,MAAM,WAAW,qBAAqB;IACpC,qEAAqE;IACrE,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAAC;IAC3C,uEAAuE;IACvE,KAAK,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;IACjC,kEAAkE;IAClE,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;IAC3C,2EAA2E;IAC3E,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,cAAc,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC;IAEzE,qEAAqE;IACrE,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,mFAAmF;IACnF,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IAEjC,YAAY,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IACzC,oBAAoB,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IACjD,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAC9D,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAAC;IACtE,wBAAwB,CACtB,SAAS,EAAE,MAAM,EACjB,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAAC;CACvC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,4EAA4E;IAC5E,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAAC;IACzD,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5C;AAED,yEAAyE;AACzE,MAAM,WAAW,WAAW;IAC1B,QAAQ,IAAI,cAAc,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IACvC,UAAU,CAAC,QAAQ,EAAE,UAAU,GAAG,IAAI,CAAC;IACvC,mBAAmB,IAAI,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAAC;CACxD"}

package/dist/internal/storage-roles.js

@@ -0,0 +1,24 @@
+/**
+ * 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.
+ */
+export {};

package/dist/internal/workspace.d.ts

@@ -17,16 +17,28 @@ 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 declare function buildCloudMemorySection(agentName: string): string;
 /** Relative path of an agent-side tool script inside the session workspace. */
 export declare function agentToolScriptPath(toolName: string): string;
+/**
+ * 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 declare 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)
@@ -47,15 +59,34 @@ export declare function withIdentityPreamble(name: string, instructions: string
 export declare function buildAgentToolsCatalog(tools: DiscoveredTool[], options?: {
     includeScripts: boolean;
 }): string;
+/**
+ * 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 declare function buildServerToolsCatalog(tools: DiscoveredTool[], options: {
+    mcpServerName: string;
+}): string;
 /**
  * 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 declare function buildAgentsMdContent(agent: ResolvedAgent, options: {
     includeScripts: boolean;
+    serverToolsMcpName?: string;
 }): string;
 /**
  * True when `dir` sits strictly inside a git repository (a `.git` exists in

package/dist/internal/workspace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/internal/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAeH,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,aAAa,EACd,MAAM,aAAa,CAAC;AAIrB,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,aAAa,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,IAAI,EAAE,OAAO,CAAC;IACd;;;;;;;OAOG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM1D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,MAAM,GAAG,SAAS,CAapB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,GAAE;IAAE,cAAc,EAAE,OAAO,CAAA;CAA8B,GAC/D,MAAM,CA6CR;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE;IAAE,cAAc,EAAE,OAAO,CAAA;CAAE,GACnC,MAAM,CAUR;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAcrE;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,IAAI,CAAC,CAkCf;AAqGD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAO3D;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC5B,OAAO,CAAC,IAAI,CAAC,CAMf"}
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/internal/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAgBH,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,aAAa,EACd,MAAM,aAAa,CAAC;AAIrB,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,aAAa,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,IAAI,EAAE,OAAO,CAAC;IACd;;;;;;;OAOG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAOjE;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,mBAAmB,CAAC;AAE7D;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM1D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,MAAM,GAAG,SAAS,CAapB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,GAAE;IAAE,cAAc,EAAE,OAAO,CAAA;CAA8B,GAC/D,MAAM,CA6CR;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,EAAE;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,GACjC,MAAM,CA4BR;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE;IAAE,cAAc,EAAE,OAAO,CAAC;IAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAAE,GAChE,MAAM,CAeR;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAcrE;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,IAAI,CAAC,CAkCf;AAqGD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAO3D;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC5B,OAAO,CAAC,IAAI,CAAC,CAMf"}

package/dist/internal/workspace.js

@@ -17,13 +17,33 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 import { chmod, copyFile, lstat, mkdir, readlink, rm, stat, symlink, 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 { parseFrontmatter, serializeFrontmatter } from "./frontmatter.js";
 import { buildIdentitySection } from "./prompt-context.js";
+/**
+ * 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) {
+    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) {
     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)
@@ -104,12 +124,53 @@ export function buildAgentToolsCatalog(tools, options = { includeScripts: false
     }
     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, options) {
+    const serverTools = tools.filter((tool) => tool.execution === "server");
+    if (serverTools.length === 0) {
+        return "";
+    }
+    const parts = [
+        "## 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, options) {
     var _a;
@@ -120,6 +181,11 @@ export function buildAgentsMdContent(agent, options) {
         buildAgentToolsCatalog(agent.tools, {
             includeScripts: options.includeScripts,
         }),
+        options.serverToolsMcpName === undefined
+            ? ""
+            : buildServerToolsCatalog(agent.tools, {
+                mcpServerName: options.serverToolsMcpName,
+            }),
     ]
         .filter((part) => part !== "")
         .join("\n\n");

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()) {