@cursor/july 0.1.21 → 0.1.23

package/src/internal/workspace.test.ts

@@ -1,11 +1,21 @@
-import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import {
+  lstat,
+  mkdir,
+  mkdtemp,
+  readlink,
+  rm,
+  writeFile,
+} from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
+import type { ResolvedAgent } from "../types.js";
 import {
   buildIdentityPreamble,
   isNestedInGitRepo,
+  materializeWorkspace,
   withIdentityPreamble,
+  writeWorkspaceFiles,
 } from "./workspace.js";
 
 describe("buildIdentityPreamble", () => {
@@ -79,3 +89,119 @@ describe("isNestedInGitRepo", () => {
     expect(await isNestedInGitRepo(dir)).toBe(false);
   });
 });
+
+describe("materializeWorkspace memory link", () => {
+  const cleanups: Array<() => Promise<void>> = [];
+
+  afterEach(async () => {
+    while (cleanups.length > 0) {
+      await cleanups.pop()?.();
+    }
+  });
+
+  async function makeTempDir(): Promise<string> {
+    const dir = await mkdtemp(join(tmpdir(), "agent-serve-workspace-"));
+    cleanups.push(() => rm(dir, { recursive: true, force: true }));
+    return dir;
+  }
+
+  const agent: ResolvedAgent = {
+    name: "test-agent",
+    runtime: "local",
+    tools: [],
+    skills: [],
+    connections: [],
+    subagents: [],
+    seedFiles: [],
+  };
+
+  it("symlinks <stateRoot>/memory into the workspace", async () => {
+    const root = await makeTempDir();
+    const workspaceDir = join(root, "workspace");
+    const stateRoot = join(root, "state");
+    await materializeWorkspace({ agent, workspaceDir, seed: true, stateRoot });
+
+    const link = join(workspaceDir, "memory");
+    expect((await lstat(link)).isSymbolicLink()).toBe(true);
+    expect(await readlink(link)).toBe(join(stateRoot, "memory"));
+    // The target directory is created eagerly so first sessions can read it.
+    expect((await lstat(join(stateRoot, "memory"))).isDirectory()).toBe(true);
+  });
+
+  it("is idempotent and leaves an existing memory entry alone", async () => {
+    const root = await makeTempDir();
+    const workspaceDir = join(root, "workspace");
+    const stateRoot = join(root, "state");
+    await mkdir(workspaceDir, { recursive: true });
+    await writeFile(join(workspaceDir, "memory"), "not a link", "utf8");
+
+    await materializeWorkspace({ agent, workspaceDir, seed: true, stateRoot });
+    await materializeWorkspace({ agent, workspaceDir, seed: false, stateRoot });
+
+    expect((await lstat(join(workspaceDir, "memory"))).isFile()).toBe(true);
+  });
+
+  it("re-points a stale link when the state root moved", async () => {
+    const root = await makeTempDir();
+    const workspaceDir = join(root, "workspace");
+    await materializeWorkspace({
+      agent,
+      workspaceDir,
+      seed: true,
+      stateRoot: join(root, "old-state"),
+    });
+    const stateRoot = join(root, "new-state");
+    await materializeWorkspace({ agent, workspaceDir, seed: true, stateRoot });
+
+    expect(await readlink(join(workspaceDir, "memory"))).toBe(
+      join(stateRoot, "memory")
+    );
+  });
+
+  it("refuses workspace writes into the reserved memory path", async () => {
+    const root = await makeTempDir();
+    const workspaceDir = join(root, "workspace");
+    const stateRoot = join(root, "state");
+    await materializeWorkspace({ agent, workspaceDir, seed: true, stateRoot });
+
+    await expect(
+      writeWorkspaceFiles(workspaceDir, {
+        "memory/journal.jsonl": "poisoned",
+      })
+    ).rejects.toThrow(/reserved/);
+    await expect(
+      writeWorkspaceFiles(workspaceDir, { memory: "clobbered" })
+    ).rejects.toThrow(/reserved/);
+    // Normalized relatives must not slip past the reservation.
+    await expect(
+      writeWorkspaceFiles(workspaceDir, { "./memory/x": "poisoned" })
+    ).rejects.toThrow(/reserved/);
+    await expect(
+      writeWorkspaceFiles(workspaceDir, { "foo/../memory/x": "poisoned" })
+    ).rejects.toThrow(/reserved/);
+
+    await expect(
+      materializeWorkspace({
+        agent: {
+          ...agent,
+          seedFiles: [
+            { relativePath: "memory/seed.txt", sourcePath: "/dev/null" },
+          ],
+        },
+        workspaceDir,
+        seed: true,
+        stateRoot,
+      })
+    ).rejects.toThrow(/reserved/);
+  });
+
+  it("only links on seed turns", async () => {
+    const root = await makeTempDir();
+    const workspaceDir = join(root, "workspace");
+    const stateRoot = join(root, "state");
+    await materializeWorkspace({ agent, workspaceDir, seed: false, stateRoot });
+    await expect(lstat(join(workspaceDir, "memory"))).rejects.toMatchObject({
+      code: "ENOENT",
+    });
+  });
+});

package/src/internal/workspace.ts

@@ -7,8 +7,19 @@
  * all of this up natively through its project setting source.
  */
 
-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 type {
   DiscoveredSkill,
   DiscoveredTool,
@@ -25,6 +36,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. */
@@ -172,8 +192,11 @@ export async function isNestedInGitRepo(dir: string): Promise<boolean> {
 export async function materializeWorkspace(
   options: MaterializeWorkspaceOptions
 ): Promise<void> {
-  const { agent, workspaceDir, seed } = options;
+  const { agent, workspaceDir, seed, stateRoot } = options;
   await mkdir(workspaceDir, { recursive: true });
+  if (seed) {
+    await linkSharedMemoryDir(workspaceDir, stateRoot);
+  }
 
   const agentsMd = buildAgentsMdContent(agent, { includeScripts: false });
   await writeFile(join(workspaceDir, "AGENTS.md"), agentsMd, "utf8");
@@ -191,7 +214,10 @@ export async function materializeWorkspace(
 
   if (seed) {
     for (const seedFile of agent.seedFiles) {
-      const target = resolveInside(workspaceDir, seedFile.relativePath);
+      const target = resolveWorkspaceWritePath(
+        workspaceDir,
+        seedFile.relativePath
+      );
       if (await exists(target)) {
         continue;
       }
@@ -201,6 +227,56 @@ export async function materializeWorkspace(
   }
 }
 
+/**
+ * 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: string,
+  relativePath: string
+): string {
+  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.
+ */
+async function linkSharedMemoryDir(
+  workspaceDir: string,
+  stateRoot: string
+): Promise<void> {
+  const target = join(stateRoot, MEMORY_DIR_NAME);
+  const linkPath = join(workspaceDir, MEMORY_DIR_NAME);
+  await mkdir(target, { recursive: true });
+  try {
+    await symlink(target, linkPath, "dir");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
+      return;
+    }
+    const existing = await lstat(linkPath);
+    if (!existing.isSymbolicLink() || (await readlink(linkPath)) === target) {
+      return;
+    }
+    await rm(linkPath);
+    await symlink(target, linkPath, "dir");
+  }
+}
+
 async function materializeAgentTool(
   workspaceDir: string,
   tool: DiscoveredTool
@@ -273,7 +349,7 @@ export async function writeWorkspaceFiles(
   files: Record<string, string>
 ): Promise<void> {
   for (const [relativePath, contents] of Object.entries(files)) {
-    const target = resolveInside(workspaceDir, relativePath);
+    const target = resolveWorkspaceWritePath(workspaceDir, relativePath);
     await mkdir(dirname(target), { recursive: true });
     await writeFile(target, contents, "utf8");
   }

package/src/memory.ts

@@ -0,0 +1,215 @@
+/**
+ * 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 { appendFile, mkdir, rename, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { defineHook } from "./hooks.js";
+import type { HookContext, HookDefinition, TurnUsage } from "./types.js";
+
+/** Name of the shared memory directory under the agent state root. */
+export 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 function fileMemoryBackend(
+  options: FileMemoryBackendOptions = {}
+): MemoryBackend {
+  const maxJournalBytes = options.maxJournalBytes ?? 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<string, Promise<void>>();
+  // Same-millisecond rotations must not reuse a segment name — POSIX
+  // rename would silently replace the earlier archive.
+  let rotationSeq = 0;
+  return {
+    async appendTurn(record, ctx) {
+      const dir = join(ctx.stateRoot, MEMORY_DIR_NAME);
+      const path = join(dir, "journal.jsonl");
+      const prior = appendChains.get(path) ?? Promise.resolve();
+      const next = prior
+        .catch(() => {})
+        .then(async () => {
+          await mkdir(dir, { recursive: true });
+          const size = (await stat(path).catch(() => undefined))?.size ?? 0;
+          if (size >= maxJournalBytes) {
+            rotationSeq += 1;
+            await rename(
+              path,
+              join(dir, `journal-${Date.now()}-${rotationSeq}.jsonl`)
+            );
+          }
+          await appendFile(path, `${JSON.stringify(record)}\n`, "utf8");
+        });
+      appendChains.set(path, next);
+      await next;
+    },
+  };
+}
+
+export interface MemoryHookOptions {
+  /** Where records go. Defaults to {@link fileMemoryBackend}. */
+  backend?: MemoryBackend;
+  /** Truncation cap for stored userMessage / result text. Default 2000. */
+  maxTextLength?: number;
+}
+
+function truncate(text: string, max: number): string {
+  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: MemoryHookOptions = {}): HookDefinition {
+  const backend = options.backend ?? fileMemoryBackend();
+  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
+  // 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<string, string>();
+  const pendingKey = (ctx: HookContext, turnId: string | undefined): string =>
+    `${ctx.session.id}/${turnId ?? "?"}`;
+
+  const record = async (
+    ctx: HookContext,
+    turnId: string | undefined,
+    status: TurnMemoryRecord["status"],
+    result: string | undefined,
+    usage: TurnUsage | undefined
+  ): Promise<void> => {
+    const key = pendingKey(ctx, turnId);
+    const userMessage = pendingMessages.get(key);
+    pendingMessages.delete(key);
+    const entry: TurnMemoryRecord = {
+      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;
+    }
+    await backend.appendTurn(entry, { stateRoot: ctx.stateRoot });
+  };
+
+  const sweepSession = (ctx: HookContext): void => {
+    for (const key of pendingMessages.keys()) {
+      if (key.startsWith(`${ctx.session.id}/`)) {
+        pendingMessages.delete(key);
+      }
+    }
+  };
+
+  return defineHook({
+    events: {
+      async "message.received"(event, ctx) {
+        pendingMessages.set(
+          pendingKey(ctx, event.turnId),
+          truncate(event.data.text, maxTextLength)
+        );
+      },
+      async "turn.completed"(event, ctx) {
+        await record(
+          ctx,
+          event.turnId,
+          "completed",
+          event.data.result,
+          event.data.usage
+        );
+      },
+      async "turn.failed"(event, ctx) {
+        await record(
+          ctx,
+          event.turnId,
+          "failed",
+          event.data.message,
+          undefined
+        );
+      },
+      async "session.completed"(_event, ctx) {
+        sweepSession(ctx);
+      },
+      async "session.failed"(_event, ctx) {
+        sweepSession(ctx);
+      },
+    },
+  });
+}

package/src/types.ts

@@ -492,6 +492,11 @@ export interface ToolContext {
   session: SessionInfo;
   /** Absolute path of the session's materialized workspace directory. */
   workspaceDir: string;
+  /**
+   * Absolute path of the agent's durable state root (shared across every
+   * session of this agent).
+   */
+  stateRoot: string;
   /** Shared host services (MCP / GitHub / Slack). */
   host: HostContext;
   /**
@@ -1564,6 +1569,12 @@ export interface HookContext {
   agent: { name: string };
   channel: { id: string; continuationToken: string | null };
   session: SessionInfo;
+  /**
+   * Absolute path of the agent's durable state root (shared across every
+   * session of this agent). Hooks that maintain derived state (e.g. the
+   * memory journal) write here.
+   */
+  stateRoot: string;
 }
 
 export type HookHandler<TEvent extends SessionEvent = SessionEvent> = (