@cursor/july 0.1.21 → 0.1.23

package/dist/internal/local-env.js

@@ -1,8 +1,10 @@
 /**
- * Loads an agent directory's `.env.local` (and each immediate child's,
- * for multi-agent hosts) into process.env. Real env always wins —
- * `process.loadEnvFile` never overrides. Values a previous call loaded are
- * refreshed, so a reload picks up edits made since.
+ * Loads an agent directory's env files (and each immediate child's, for
+ * multi-agent hosts) into process.env. Load order per directory is
+ * `.env.local` then `.env` — `process.loadEnvFile` never overrides, so
+ * real env wins over both, and `.env.local` wins over checked-in `.env`
+ * defaults. Values a previous call loaded are refreshed, so a reload
+ * picks up edits made since.
  */
 import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
@@ -25,7 +27,13 @@ export function loadAgentLocalEnv(dir) {
     const trackLoadedKeys = () => {
         fileLoadedKeys = new Set(Object.keys(process.env).filter((key) => !realKeys.has(key)));
     };
-    tryLoad(join(dir, ".env.local"));
+    const tryLoadDir = (agentDir) => {
+        // `.env.local` first so its values win over checked-in `.env` defaults
+        // under loadEnvFile's no-override semantics.
+        tryLoad(join(agentDir, ".env.local"));
+        tryLoad(join(agentDir, ".env"));
+    };
+    tryLoadDir(dir);
     let children;
     try {
         children = readdirSync(dir, { withFileTypes: true })
@@ -40,7 +48,7 @@ export function loadAgentLocalEnv(dir) {
         if (child === "node_modules") {
             continue;
         }
-        tryLoad(join(dir, child, ".env.local"));
+        tryLoadDir(join(dir, child));
     }
     trackLoadedKeys();
     return loaded;

package/dist/internal/session-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-engine.d.ts","sourceRoot":"","sources":["../../src/internal/session-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAYH,OAAO,EACL,mBAAmB,EACnB,eAAe,EAChB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EAEtB,KAAK,cAAc,EAInB,KAAK,WAAW,EAChB,KAAK,qBAAqB,EAI1B,KAAK,eAAe,EACpB,KAAK,YAAY,EAKjB,KAAK,kBAAkB,EACvB,KAAK,YAAY,EAEjB,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,cAAc,EAEnB,KAAK,eAAe,EAGpB,KAAK,WAAW,EACjB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,KAAK,UAAU,EAAmB,MAAM,kBAAkB,CAAC;AAQpE,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAc9E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAU9D,eAAO,MAAM,eAAe,SAAS,CAAC;AACtC,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAE9D,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,YAAY,SAAS,EAAE,MAAM,EAK5B;CACF;AAED,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,YAAY,SAAS,EAAE,MAAM,EAK5B;CACF;AAED,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,YAAY,SAAS,EAAE,MAAM,EAG5B;CACF;AAED,qBAAa,gBAAiB,SAAQ,KAAK;IAGvC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,EAAE;IAFvC,YACE,QAAQ,EAAE,MAAM,EACP,kBAAkB,EAAE,MAAM,EAAE,EAItC;CACF;AAED,qBAAa,4BAA6B,SAAQ,KAAK;IACrD,YAAY,QAAQ,EAAE,MAAM,EAK3B;CACF;AAED,qBAAa,cAAe,SAAQ,KAAK;IACvC,YAAY,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAGrD;CACF;AAED,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,YAAY,SAAS,EAAE,MAAM,EAG5B;CACF;AAED,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,YAAY,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAG5C;CACF;AAED,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,YAAY,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAK5C;CACF;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,YAAY,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,WAAW,CAAC;IACpB,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,SAAS,CAAC,EAAE,aAAa,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,wBAAwB;IACvC,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,iBAAkB,SAAQ,kBAAkB;IAC3D,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACxB;AAiBD,qBAAa,aAAa;IACxB,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,sEAAsE;IACtE,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,wEAAwE;IACxE,QAAQ,CAAC,SAAS,EAAE,mBAAmB,CAAC;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,kBAAkB,GAAG,SAAS,CAAC;IACjD,uEAAuE;IACvE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAG5B;IACJ,6EAA6E;IAC7E,OAAO,CAAC,kBAAkB,CAA8C;IAExE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyB;IAChD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAgB;IACrC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAwC;IACrE,2EAA2E;IAC3E,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAClD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA2C;IACvE,2EAA2E;IAC3E,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsC;IACjE,qEAAqE;IACrE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAuC;IACvE,kFAAkF;IAClF,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA4C;IAC3E;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAoC;IACnE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAkC;IAC/D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAuC;IACpE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAoC;IACnE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA+B;IAC9D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsB;IAChD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,WAAW,CAA2B;IAC9C,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;IAC1C,4EAA4E;IAC5E,OAAO,CAAC,mBAAmB,CAAkC;IAE7D,YAAY,OAAO,EAAE,oBAAoB,EAqDxC;IAED;;;;;OAKG;IACH,sBAAsB,CAAC,WAAW,EAAE,wBAAwB,EAAE,GAAG,IAAI,CAapE;IAED,2FAA2F;IAC3F,IAAI,IAAI,IAAI,WAAW,CAUtB;IAED,OAAO,CAAC,iBAAiB;IAiBzB,oEAAoE;IACpE,YAAY,CAAC,GAAG,EAAE,WAAW,CAAC,WAAW,CAAC,GAAG,IAAI,CAEhD;IAED,4EAA4E;IAC5E,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC,OAAO,CAAC,GAAG,IAAI,CAExC;IAMD;;;;OAIG;IACG,IAAI,CACR,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,cAAc,CAAC,CAoFzB;IAED,8EAA8E;IACxE,sBAAsB,CAC1B,SAAS,EAAE,MAAM,EACjB,iBAAiB,EAAE,MAAM,GACxB,OAAO,CAAC,OAAO,CAAC,CAYlB;IAED;;;;;;OAMG;YACW,SAAS;IAyCvB;;;OAGG;YACW,SAAS;IAmBvB;;;OAGG;IACH,OAAO,CAAC,eAAe;IAgBvB,oDAAoD;IAC9C,iBAAiB,CACrB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAMhC;IAED,qEAAqE;IAC/D,OAAO,CACX,OAAO,EAAE,iBAAiB,GAAG,qBAAqB,GAAG,MAAM,EAC3D,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,cAAc,CAAC,CAwBzB;IAED,+DAA+D;IACzD,OAAO,CAAC,IAAI,EAAE;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC;QACzB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAC,WAAW,CAAC,CAAA;KAAE,CAAC,CAO7D;IAMD;;;;;;;;;;OAUG;IACH,OAAO,CAAC,SAAS;IAgBjB,OAAO,CAAC,gBAAgB;IAYxB,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,wBAAwB;YAoBlB,uBAAuB;YAgBvB,SAAS;IA0GvB;;;;OAIG;YACW,mBAAmB;IAYjC;;;;OAIG;IACG,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAcnD;IAEK,kBAAkB,CACtB,SAAS,EAAE,MAAM,EACjB,iBAAiB,EAAE,MAAM,GACxB,OAAO,CAAC,OAAO,CAAC,CAelB;IAED;;;OAGG;IACG,+BAA+B,CACnC,SAAS,EAAE,MAAM,EACjB,iBAAiB,EAAE,MAAM,GACxB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAoB7B;IAEK,qBAAqB,CACzB,SAAS,EAAE,MAAM,EACjB,iBAAiB,EAAE,MAAM,GACxB,OAAO,CAAC,OAAO,CAAC,CAelB;IAED;;;;OAIG;IACH,UAAU,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAaxC;IAED;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IAO5B;;;;;;;OAOG;IACG,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC,CAiC5C;IAED,gEAAgE;IAChE,OAAO,CAAC,WAAW;YAOL,WAAW;IAgLzB,OAAO,CAAC,gBAAgB;IA+FxB;;;OAGG;IACH,OAAO,CAAC,eAAe;IAkDvB,OAAO,CAAC,gBAAgB;IAuGxB;;;;OAIG;YACW,eAAe;YA8Df,qBAAqB;IAenC,uEAAuE;IACjE,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAUxE;IAED;;;;;;;OAOG;IACG,eAAe,CACnB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,gBAAgB,EAC1B,IAAI,EAAE,WAAW,GAAG,IAAI,EACxB,OAAO,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,OAAO,CAAA;KAAE,GACrC,OAAO,CAAC,eAAe,CAAC,CAqB1B;YAEa,qBAAqB;IAgBnC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,QAAQ,CACZ,QAAQ,EAAE,MAAM,EAChB,KAAK,GAAE,OAAY,EACnB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,eAAe,CAAC,CA0I1B;YAMa,WAAW;IAUzB,OAAO,CAAC,aAAa;YAqBP,aAAa;IA4E3B,OAAO,CAAC,uBAAuB;IAazB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAiB/D;IAED;;;;;;;;;;;OAWG;IACG,YAAY,CAChB,MAAM,EAAE,WAAW,GAAG,IAAI,EAC1B,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,OAAO,CAAA;KAAE,GACjC,OAAO,CAAC,cAAc,EAAE,CAAC,CAE3B;IAED;;;;OAIG;IACG,sBAAsB,CAC1B,MAAM,EAAE,WAAW,GAAG,IAAI,EAC1B,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,OAAO,CAAA;KAAE,GACjC,OAAO,CAAC;QAAE,QAAQ,EAAE,cAAc,EAAE,CAAC;QAAC,MAAM,EAAE,iBAAiB,CAAA;KAAE,CAAC,CAyBpE;IAED;;;;OAIG;YACW,2BAA2B;IAyBzC,OAAO,CAAC,uBAAuB;IAmC/B;;;;OAIG;IACG,UAAU,CACd,MAAM,EAAE,WAAW,GAAG,IAAI,EAC1B,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,OAAO,CAAA;KAAE,GACjC,OAAO,CAAC,UAAU,CAAC,CA6CrB;IAEK,WAAW,CACf,SAAS,EAAE,MAAM,EACjB,UAAU,SAAI,GACb,OAAO,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC,CAGrC;IAED;;;;OAIG;IACG,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAoCzE;IAED,kEAAkE;IAC5D,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,SAAI,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAG3E;IAEK,oBAAoB,CACxB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GAAG,IAAI,GACnB,OAAO,CAAC,IAAI,CAAC,CAmBf;IAED,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CASxC;IAED,WAAW,CAAC,MAAM,EAAE,aAAa,GAAG,WAAW,CAc9C;IAED,OAAO,CAAC,cAAc;IAoBtB,OAAO,CAAC,gBAAgB;IAwBxB,OAAO,CAAC,mBAAmB;IAc3B,sEAAsE;IACtE,OAAO,CAAC,YAAY;IA6BpB;;;;;;;;;;;OAWG;IACG,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CAc3C;YAEa,cAAc;IA4F5B;;;;;;;;OAQG;IACG,mBAAmB,CACvB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAMpC;IAED;;;;;;;;;;OAUG;IACH,OAAO,CAAC,4BAA4B;IAqBpC,OAAO,CAAC,kBAAkB;YAkBZ,gCAAgC;YAgBhC,sBAAsB;YAWtB,yBAAyB;IAmBvC;;;;;OAKG;YACW,kBAAkB;IAYhC,eAAe,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAO/C;IAED,yEAAyE;IACnE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAU3B;CACF"}
+{"version":3,"file":"session-engine.d.ts","sourceRoot":"","sources":["../../src/internal/session-engine.ts"],"names":[],"mappings":"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"}

package/dist/internal/session-engine.js

@@ -786,6 +786,7 @@ export class SessionEngine {
                         agent,
                         workspaceDir,
                         seed: isFirstTurn,
+                        stateRoot: this.stateRoot,
                     });
                     const pendingFiles = record.pendingWorkspaceFiles;
                     if (pendingFiles !== undefined &&
@@ -1016,6 +1017,7 @@ export class SessionEngine {
                         toolCallId,
                         session: this.sessionInfo(record),
                         workspaceDir: this.harnessCwd(record),
+                        stateRoot: this.stateRoot,
                         host: this.host,
                         send: (channelId, message, sendOptions = {}) => this.send(channelId, message, Object.assign(Object.assign({}, sendOptions), { auth: sendOptions.auth !== undefined
                                 ? sendOptions.auth
@@ -1249,6 +1251,7 @@ export class SessionEngine {
                 agent: this.project.agent,
                 workspaceDir: record === undefined ? workspaceDir : this.scaffoldDir(record),
                 seed: record === undefined || record.turnCount === 0,
+                stateRoot: this.stateRoot,
             });
             // A per-call turnId keeps these events visible in trajectories (which
             // drop turn-less action events) without attributing them to a model turn.
@@ -1268,6 +1271,7 @@ export class SessionEngine {
                     toolCallId: callId,
                     session,
                     workspaceDir,
+                    stateRoot: this.stateRoot,
                     host: this.host,
                     send: (channelId, message, sendOptions = {}) => this.send(channelId, message, Object.assign(Object.assign({}, sendOptions), { auth: sendOptions.auth !== undefined
                             ? sendOptions.auth
@@ -1397,6 +1401,7 @@ export class SessionEngine {
                                 continuationToken: record.continuationKey,
                             },
                             session: this.sessionInfo(record),
+                            stateRoot: this.stateRoot,
                         });
                     }
                     catch (error) {

package/dist/internal/workspace.d.ts

@@ -15,6 +15,15 @@ export interface MaterializeWorkspaceOptions {
      * skills are always rewritten so authored edits show up on the next turn.
      */
     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.
+     */
+    stateRoot: string;
 }
 /** Relative path of an agent-side tool script inside the session workspace. */
 export declare function agentToolScriptPath(toolName: string): string;

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;AAIH,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;CACf;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,CA4Bf;AAmDD;;;;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;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"}

package/dist/internal/workspace.js

@@ -15,8 +15,9 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import { chmod, copyFile, mkdir, stat, writeFile } from "node:fs/promises";
-import { dirname, join, parse, relative, resolve } from "node:path";
+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 { MEMORY_DIR_NAME } from "../memory.js";
 import { parseFrontmatter, serializeFrontmatter } from "./frontmatter.js";
 import { buildIdentitySection } from "./prompt-context.js";
 /** Relative path of an agent-side tool script inside the session workspace. */
@@ -150,8 +151,11 @@ export function isNestedInGitRepo(dir) {
 }
 export function materializeWorkspace(options) {
     return __awaiter(this, void 0, void 0, function* () {
-        const { agent, workspaceDir, seed } = options;
+        const { agent, workspaceDir, seed, stateRoot } = options;
         yield mkdir(workspaceDir, { recursive: true });
+        if (seed) {
+            yield linkSharedMemoryDir(workspaceDir, stateRoot);
+        }
         const agentsMd = buildAgentsMdContent(agent, { includeScripts: false });
         yield writeFile(join(workspaceDir, "AGENTS.md"), agentsMd, "utf8");
         for (const tool of agent.tools) {
@@ -165,7 +169,7 @@ export function materializeWorkspace(options) {
         }
         if (seed) {
             for (const seedFile of agent.seedFiles) {
-                const target = resolveInside(workspaceDir, seedFile.relativePath);
+                const target = resolveWorkspaceWritePath(workspaceDir, seedFile.relativePath);
                 if (yield exists(target)) {
                     continue;
                 }
@@ -175,6 +179,49 @@ export function materializeWorkspace(options) {
         }
     });
 }
+/**
+ * Resolve a workspace-rooted write target, refusing escapes and the
+ * reserved `memory` name. `memory` is a symlink into the agent's durable
+ * cross-session state, so a caller-supplied `workspaceFiles` entry (or a
+ * seed file) under it would write through the link and poison the journal
+ * every other session trusts. The check runs on the *resolved* path so
+ * `./memory/x` and `foo/../memory/x` cannot slip past.
+ */
+function resolveWorkspaceWritePath(workspaceDir, relativePath) {
+    const target = resolveInside(workspaceDir, relativePath);
+    const first = relative(workspaceDir, target).split(sep, 1)[0];
+    if (first === MEMORY_DIR_NAME) {
+        throw new Error(`"${MEMORY_DIR_NAME}" is reserved for shared session memory; refusing to write ${relativePath}`);
+    }
+    return target;
+}
+/**
+ * Symlink `<stateRoot>/memory` into the workspace as `memory`. Stale links
+ * (a moved state root) are re-pointed; seeded files and symlink-refusing
+ * platforms (unprivileged Windows) are left alone — memory then stays
+ * reachable only via the state path.
+ */
+function linkSharedMemoryDir(workspaceDir, stateRoot) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const target = join(stateRoot, MEMORY_DIR_NAME);
+        const linkPath = join(workspaceDir, MEMORY_DIR_NAME);
+        yield mkdir(target, { recursive: true });
+        try {
+            yield symlink(target, linkPath, "dir");
+        }
+        catch (error) {
+            if (error.code !== "EEXIST") {
+                return;
+            }
+            const existing = yield lstat(linkPath);
+            if (!existing.isSymbolicLink() || (yield readlink(linkPath)) === target) {
+                return;
+            }
+            yield rm(linkPath);
+            yield symlink(target, linkPath, "dir");
+        }
+    });
+}
 function materializeAgentTool(workspaceDir, tool) {
     return __awaiter(this, void 0, void 0, function* () {
         if (tool.script === undefined) {
@@ -240,7 +287,7 @@ export function buildSkillMd(skill) {
 export function writeWorkspaceFiles(workspaceDir, files) {
     return __awaiter(this, void 0, void 0, function* () {
         for (const [relativePath, contents] of Object.entries(files)) {
-            const target = resolveInside(workspaceDir, relativePath);
+            const target = resolveWorkspaceWritePath(workspaceDir, relativePath);
             yield mkdir(dirname(target), { recursive: true });
             yield writeFile(target, contents, "utf8");
         }

package/dist/memory.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Session memory — a journal of what every session of this agent did, so
+ * later sessions can recall and build on past work.
+ *
+ * The write side is {@link memoryHook}, authored as a thin re-export at
+ * `agent/hooks/memory.ts` (scaffolded by `agentkit init`): after each turn
+ * it appends one record (timestamp, session, user message, final result,
+ * usage) to `<stateRoot>/memory/journal.jsonl`.
+ *
+ * There is no read-side API. The framework symlinks `<stateRoot>/memory`
+ * into every session workspace as `memory/`, so agents read the journal
+ * with their normal file tools (`instructions.md` points them at it). That
+ * filesystem visibility is why memory does not route through
+ * `defineStorage` sinks, which are opaque to the model. A custom
+ * {@link MemoryBackend} (database, vector store, …) supplies its own read
+ * 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.
+ */
+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";
+/** One journal line: what a single turn did. */
+export type TurnMemoryRecord = {
+    /** ISO timestamp of when the turn finished. */
+    at: string;
+    sessionId: string;
+    channelId: string;
+    status: "completed" | "failed";
+    /** Session title, when the channel set one. */
+    title?: string;
+    /** Cursor SDK agent id (cloud: `bc-…`; local: the session id). */
+    sdkAgentId?: string;
+    /** The user message that started the turn (truncated). */
+    userMessage?: string;
+    /** Final assistant text of the turn, or the failure message (truncated). */
+    result?: string;
+    usage?: TurnUsage;
+};
+/** Where turn records go. Receives the agent's state root per append. */
+export interface MemoryBackend {
+    appendTurn(record: TurnMemoryRecord, ctx: {
+        stateRoot: string;
+    }): Promise<void>;
+}
+export interface FileMemoryBackendOptions {
+    /**
+     * Rotate `journal.jsonl` to a timestamped sibling once it exceeds this
+     * size, keeping the file agents grep small. Default 5 MiB.
+     */
+    maxJournalBytes?: number;
+}
+/**
+ * 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 MemoryHookOptions {
+    /** Where records go. Defaults to {@link fileMemoryBackend}. */
+    backend?: MemoryBackend;
+    /** Truncation cap for stored userMessage / result text. Default 2000. */
+    maxTextLength?: number;
+}
+/**
+ * Observe-only hook that journals every turn. Author it as
+ * `agent/hooks/memory.ts`:
+ *
+ * ```ts
+ * import { memoryHook } from "@cursor/july/memory";
+ * export default memoryHook();
+ * ```
+ */
+export declare function memoryHook(options?: MemoryHookOptions): HookDefinition;
+//# sourceMappingURL=memory.d.ts.map

package/dist/memory.d.ts.map

@@ -0,0 +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"}

package/dist/memory.js

@@ -0,0 +1,164 @@
+/**
+ * Session memory — a journal of what every session of this agent did, so
+ * later sessions can recall and build on past work.
+ *
+ * The write side is {@link memoryHook}, authored as a thin re-export at
+ * `agent/hooks/memory.ts` (scaffolded by `agentkit init`): after each turn
+ * it appends one record (timestamp, session, user message, final result,
+ * usage) to `<stateRoot>/memory/journal.jsonl`.
+ *
+ * There is no read-side API. The framework symlinks `<stateRoot>/memory`
+ * into every session workspace as `memory/`, so agents read the journal
+ * with their normal file tools (`instructions.md` points them at it). That
+ * filesystem visibility is why memory does not route through
+ * `defineStorage` sinks, which are opaque to the model. A custom
+ * {@link MemoryBackend} (database, vector store, …) supplies its own read
+ * 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.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { appendFile, mkdir, rename, stat } from "node:fs/promises";
+import { join } from "node:path";
+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`
+ * — the directory the framework symlinks into session workspaces. Rotated
+ * segments stay alongside as `journal-<epoch-ms>.jsonl`.
+ */
+export function fileMemoryBackend(options = {}) {
+    var _a;
+    const maxJournalBytes = (_a = options.maxJournalBytes) !== null && _a !== void 0 ? _a : 5 * 1024 * 1024;
+    // Event dispatch is serialized per session but concurrent across
+    // sessions, so appends to the shared journal are chained per path. A
+    // failed append must not poison the chain for later turns.
+    const appendChains = new Map();
+    // Same-millisecond rotations must not reuse a segment name — POSIX
+    // rename would silently replace the earlier archive.
+    let rotationSeq = 0;
+    return {
+        appendTurn(record, ctx) {
+            return __awaiter(this, void 0, void 0, function* () {
+                var _a;
+                const dir = join(ctx.stateRoot, MEMORY_DIR_NAME);
+                const path = join(dir, "journal.jsonl");
+                const prior = (_a = appendChains.get(path)) !== null && _a !== void 0 ? _a : Promise.resolve();
+                const next = prior
+                    .catch(() => { })
+                    .then(() => __awaiter(this, void 0, void 0, function* () {
+                    var _a;
+                    var _b;
+                    yield mkdir(dir, { recursive: true });
+                    const size = (_b = (_a = (yield stat(path).catch(() => undefined))) === null || _a === void 0 ? void 0 : _a.size) !== null && _b !== void 0 ? _b : 0;
+                    if (size >= maxJournalBytes) {
+                        rotationSeq += 1;
+                        yield rename(path, join(dir, `journal-${Date.now()}-${rotationSeq}.jsonl`));
+                    }
+                    yield appendFile(path, `${JSON.stringify(record)}\n`, "utf8");
+                }));
+                appendChains.set(path, next);
+                yield next;
+            });
+        },
+    };
+}
+function truncate(text, max) {
+    return text.length <= max ? text : `${text.slice(0, max)}…`;
+}
+/**
+ * Observe-only hook that journals every turn. Author it as
+ * `agent/hooks/memory.ts`:
+ *
+ * ```ts
+ * import { memoryHook } from "@cursor/july/memory";
+ * export default memoryHook();
+ * ```
+ */
+export function memoryHook(options = {}) {
+    var _a, _b;
+    const backend = (_a = options.backend) !== null && _a !== void 0 ? _a : fileMemoryBackend();
+    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
+    // turn-end events share a turnId. Entries drop at turn end and any
+    // stragglers (turns that never reached a terminal event) at session end.
+    const pendingMessages = new Map();
+    const pendingKey = (ctx, turnId) => `${ctx.session.id}/${turnId !== null && turnId !== void 0 ? turnId : "?"}`;
+    const record = (ctx, turnId, status, result, usage) => __awaiter(this, void 0, void 0, function* () {
+        const key = pendingKey(ctx, turnId);
+        const userMessage = pendingMessages.get(key);
+        pendingMessages.delete(key);
+        const entry = {
+            at: new Date().toISOString(),
+            sessionId: ctx.session.id,
+            channelId: ctx.channel.id,
+            status,
+        };
+        if (ctx.session.title !== undefined) {
+            entry.title = ctx.session.title;
+        }
+        if (ctx.session.sdkAgentId !== undefined) {
+            entry.sdkAgentId = ctx.session.sdkAgentId;
+        }
+        if (userMessage !== undefined) {
+            entry.userMessage = userMessage;
+        }
+        if (result !== undefined) {
+            entry.result = truncate(result, maxTextLength);
+        }
+        if (usage !== undefined) {
+            entry.usage = usage;
+        }
+        yield backend.appendTurn(entry, { stateRoot: ctx.stateRoot });
+    });
+    const sweepSession = (ctx) => {
+        for (const key of pendingMessages.keys()) {
+            if (key.startsWith(`${ctx.session.id}/`)) {
+                pendingMessages.delete(key);
+            }
+        }
+    };
+    return defineHook({
+        events: {
+            "message.received"(event, ctx) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    pendingMessages.set(pendingKey(ctx, event.turnId), truncate(event.data.text, maxTextLength));
+                });
+            },
+            "turn.completed"(event, ctx) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    yield record(ctx, event.turnId, "completed", event.data.result, event.data.usage);
+                });
+            },
+            "turn.failed"(event, ctx) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    yield record(ctx, event.turnId, "failed", event.data.message, undefined);
+                });
+            },
+            "session.completed"(_event, ctx) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    sweepSession(ctx);
+                });
+            },
+            "session.failed"(_event, ctx) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    sweepSession(ctx);
+                });
+            },
+        },
+    });
+}