@cursor/july 0.1.45 → 0.1.47

package/src/internal/sdk-runner.ts

@@ -12,6 +12,7 @@ import {
   type AgentDefinition,
   type AgentOptions,
   type CloudAgentOptions,
+  Cursor,
   createAgentPlatform,
   JsonlLocalAgentStore,
   type LocalAgentStore,
@@ -75,6 +76,36 @@ type MaybePrewarmingPlatform = {
   ) => Promise<() => Promise<void>>;
 };
 
+/**
+ * How long a non-`--dev` serve holds workspace scans (rules, skills,
+ * `AGENTS.md`, ignore files). The SDK default is 20s for an editor whose
+ * files move under it; agent-serve checkouts only change on deploy, so a
+ * missed mid-process edit is the right trade. `CURSOR_RIPWALK_CACHE_TTL_MS`
+ * still wins when set. `--dev` leaves the 20s default so skill edits show up.
+ */
+export const SERVE_WORKSPACE_SCAN_CACHE_TTL_MS: number = 24 * 60 * 60 * 1000;
+
+/**
+ * Resolve the SDK workspace-scan TTL for this serve. `undefined` means "do
+ * not call `Cursor.configure`" and leave the SDK at its 20s editor default.
+ */
+export function resolveServeWorkspaceScanCacheTtlMs(args: {
+  dev: boolean;
+  env?: NodeJS.ProcessEnv;
+}): number | undefined {
+  const raw = (args.env ?? process.env).CURSOR_RIPWALK_CACHE_TTL_MS?.trim();
+  if (raw !== undefined && raw !== "") {
+    const parsed = Number(raw);
+    if (Number.isFinite(parsed) && parsed > 0) {
+      return parsed;
+    }
+  }
+  if (args.dev) {
+    return undefined;
+  }
+  return SERVE_WORKSPACE_SCAN_CACHE_TTL_MS;
+}
+
 export interface CursorSdkRunnerOptions {
   /** Cursor API key. Defaults to the `CURSOR_API_KEY` environment variable. */
   apiKey?: string;
@@ -86,6 +117,11 @@ export interface CursorSdkRunnerOptions {
   store?: LocalAgentStore;
   /** Diagnostics for degraded paths (resume-miss fallback). */
   logger?: (line: string) => void;
+  /**
+   * Hold workspace scans this long (ms). Applied via `Cursor.configure` so
+   * each new local executor reuses the walk. Omit to keep the SDK 20s default.
+   */
+  workspaceScanCacheTtlMs?: number;
 }
 
 /**
@@ -128,7 +164,16 @@ export class CursorSdkRunner implements AgentRunner {
   private readonly stores = new Map<string, Promise<LocalAgentStore>>();
   private readonly prewarmReleases: Array<() => Promise<void>> = [];
 
-  constructor(private readonly options: CursorSdkRunnerOptions = {}) {}
+  constructor(private readonly options: CursorSdkRunnerOptions = {}) {
+    if (options.workspaceScanCacheTtlMs !== undefined) {
+      Cursor.configure({
+        local: { workspaceScanCacheTtlMs: options.workspaceScanCacheTtlMs },
+      });
+      this.log(
+        `[agent-sdk] workspace scan cache ttl=${options.workspaceScanCacheTtlMs}ms`
+      );
+    }
+  }
 
   async runTurn(request: RunnerTurnRequest): Promise<TurnOutcome> {
     let sawUpdate = false;

package/src/internal/server.ts

@@ -17,6 +17,7 @@ import { join } from "node:path";
 import {
   type CursorGithubRepoScope,
   createCursorAccountGithubTokenResolver,
+  cursorGithubPermissionsForChannel,
   type GithubCursorAccountRuntime,
   getGithubCursorAccountRuntime,
   parseCursorGithubRepoScope,
@@ -146,7 +147,11 @@ import {
 } from "./resolved-connections.js";
 import { Router } from "./router.js";
 import { ScheduleRunner, UnknownScheduleError } from "./schedule-runner.js";
-import { type AgentRunner, CursorSdkRunner } from "./sdk-runner.js";
+import {
+  type AgentRunner,
+  CursorSdkRunner,
+  resolveServeWorkspaceScanCacheTtlMs,
+} from "./sdk-runner.js";
 import {
   SessionAuthError,
   SessionBusyError,
@@ -363,11 +368,17 @@ export async function startServer(
       "[agent-sdk] warning: --allow-anonymous admits every HTTP caller as the same principal; use only on a trusted network (e.g. Tailscale) and prefer --bearer-token for shared hosts"
     );
   }
+  const workspaceScanCacheTtlMs = resolveServeWorkspaceScanCacheTtlMs({
+    dev,
+  });
   const runner =
     options.runner ??
     new CursorSdkRunner({
       ...(accountKey === undefined ? {} : { apiKey: accountKey.apiKey }),
       logger,
+      ...(workspaceScanCacheTtlMs === undefined
+        ? {}
+        : { workspaceScanCacheTtlMs }),
     });
 
   const router = new Router();
@@ -1869,8 +1880,11 @@ function resolveCursorGithubEventConfig(input: {
     ]),
   ];
   const permissions = resolveCursorGithubPermissions(
-    input.targets.map(
-      (target) => target.accountRuntime.scope?.permissions ?? "pr-write"
+    input.targets.map((target) =>
+      cursorGithubPermissionsForChannel(
+        target.accountRuntime.options,
+        target.accountRuntime.scope?.permissions
+      )
     )
   );
   const scope = parseCursorGithubRepoScope(repos, permissions);

package/src/internal/session-engine.ts

@@ -76,7 +76,7 @@ import { foldABStream } from "./ab-fold.js";
 import { type ABSnapshot, buildABSnapshot } from "./ab-snapshot.js";
 import { ApprovalGate } from "./approval-gate.js";
 import { ArtifactsStore } from "./artifacts-store.js";
-import { samePrincipal } from "./auth.js";
+import { SessionAuthError, samePrincipal } from "./auth.js";
 import { mergeCloudOptions, resolveSessionRuntime } from "./cloud-merge.js";
 import {
   applyCloudUsageToEvents,
@@ -149,14 +149,9 @@ export class SessionBusyError extends Error {
   }
 }
 
-export class SessionAuthError extends Error {
-  constructor(sessionId: string) {
-    super(
-      `Session ${sessionId} belongs to a different principal; pass the original caller auth on follow-up`
-    );
-    this.name = "SessionAuthError";
-  }
-}
+// Defined in auth.js (the ledger pump needs it without importing this
+// module); re-exported here because this is its historical public home.
+export { SessionAuthError } from "./auth.js";
 
 export class UnknownChannelError extends Error {
   constructor(channelId: string) {
@@ -234,10 +229,11 @@ export interface SessionEngineOptions {
   /**
    * Explicit durable-session store for `serving: "ledger"` agents — a KV
    * dedicated to the ledger (session identity, leases, commit heads),
-   * separate from agent state. Must implement the ledger's CAS methods
-   * (`getWithVersion` / `putIfAbsent` / `putIfVersion`); construction
-   * fails fast otherwise. Supply the **raw** store: the engine owns key
-   * scoping and namespaces every ledger key under
+   * separate from agent state. Must implement the full CAS-capable KV
+   * surface (`HostKvCasApi`: the CAS trio plus `get`/`put`/`delete` for
+   * mailbox payload blobs and `listKeys` for the janitor scan);
+   * construction fails fast otherwise. Supply the **raw** store: the
+   * engine owns key scoping and namespaces every ledger key under
    * `agentkit/v1/<agent>/durable-session/` itself — a self-hoster never
    * writes prefixes. Default when omitted: the authored storage backend
    * (`agent/storage.ts`) when it implements the `cas` group, else — with
@@ -286,12 +282,13 @@ interface ActiveToolContext {
 export interface EngineSendOptions extends SendMessageOptions {
   mode?: "chat" | "task";
   /**
-   * Internal (ledger serving): this send *is* a lease-holding turn
-   * delivery, so it must run the resident path. Without the flag, every
-   * send on a `serving: "ledger"` agent routes through the ledger
-   * (claim → turn → commit) and the pump would recurse into itself.
+   * Internal (ledger serving): set only by the ledger pump when it
+   * executes an already-parked event under its lease, so the call must
+   * run the resident path. Without the flag, every send on a
+   * `serving: "ledger"` agent routes through the ledger (append → claim
+   * → drain → turn → commit) and the pump would recurse into itself.
    */
-  ledgerDelivery?: boolean;
+  fromLedgerPump?: boolean;
 }
 
 interface CoalescedQueuedTurn {
@@ -482,11 +479,12 @@ export class SessionEngine {
       this.channelsById.set(channel.id, channel.definition);
     }
     this.ledgerServing = this.buildLedgerServing(options);
+    this.ledgerServing?.start();
   }
 
   /**
    * Ledger-mode wiring (`serving: "ledger"`): resolve a CAS-capable
-   * durable-session store and build the delivery seam. Resident agents
+   * durable-session store and build the event pump. Resident agents
    * (the default) return undefined and never touch ledger keys.
    */
   private buildLedgerServing(
@@ -495,15 +493,46 @@ export class SessionEngine {
     if (options.project.agent.serving !== "ledger") {
       return undefined;
     }
+    // The handle is already agent-scoped (resolveDurableSessionStore):
+    // two ledger-mode agents sharing one backend never resolve to each
+    // other's sessions or janitor-claim each other's parked envelopes.
     const ledgerKv = this.resolveDurableSessionStore(options);
     return new LedgerServing({
       ledger: new SessionLedger({ kv: ledgerKv, podId: newLedgerPodId() }),
-      deliverTurn: (request) =>
-        this.send(request.channelId, request.message, {
-          ...request.options,
-          continuationToken: request.continuationToken,
-          ledgerDelivery: true,
+      deliverTurn: (envelope) =>
+        this.send(envelope.channelId, envelope.message, {
+          continuationToken: envelope.continuationToken,
+          auth: envelope.auth,
+          ...(envelope.title === undefined ? {} : { title: envelope.title }),
+          ...(envelope.state === undefined ? {} : { state: envelope.state }),
+          ...(envelope.mode === undefined ? {} : { mode: envelope.mode }),
+          ...(envelope.purpose === undefined
+            ? {}
+            : { purpose: envelope.purpose }),
+          // Isolation overrides ride the envelope: without them the
+          // drained turn would run local with the default harness cwd
+          // instead of the cloud VM / channel worktree the sender bound.
+          ...(envelope.workspaceDir === undefined
+            ? {}
+            : { workspaceDir: envelope.workspaceDir }),
+          ...(envelope.cloud === undefined ? {} : { cloud: envelope.cloud }),
+          fromLedgerPump: true,
         }),
+      findSession: async (channelId, continuationToken) => {
+        let record = await this.sessions.findByContinuation(
+          channelId,
+          continuationToken
+        );
+        if (record === undefined) {
+          record = await this.restoreSessionByContinuation(
+            channelId,
+            continuationToken
+          );
+        }
+        return record === undefined
+          ? undefined
+          : this.channelSession(record.sessionId, record, false);
+      },
       logger: this.logger,
     });
   }
@@ -521,13 +550,14 @@ export class SessionEngine {
    *
    * An authored backend without `cas` fails fast: silently falling back
    * to local files would fork coordination away from the deployment's
-   * durable store. The check demands exactly the methods the
-   * coordination-only ledger uses — `listKeys` is not one of them.
+   * durable store. The check demands the full surface the inbox uses —
+   * the CAS trio plus `get`/`put`/`delete` for mailbox payload blobs and
+   * `listKeys` for the janitor scan and the orphan sweep.
    *
    * Whatever store wins, the returned handle is scoped here — once —
    * under `agentkit/v1/<agent>/durable-session/`. The ledger speaks bare
-   * `session/…` / `ledger/…` keys; namespacing is this boundary's job,
-   * exactly like `host.kv`'s agent scoping.
+   * `session/…` / `ledger/…` / `mailbox/…` keys; namespacing is this
+   * boundary's job, exactly like `host.kv`'s agent scoping.
    */
   private resolveDurableSessionStore(
     options: SessionEngineOptions
@@ -537,7 +567,7 @@ export class SessionEngine {
     if (explicit !== undefined) {
       if (!supportsSessionLedgerKv(explicit)) {
         throw new Error(
-          `Agent "${options.project.name}" declares serving: "ledger", but the configured durableSessionStore is not CAS-capable (getWithVersion / putIfAbsent / putIfVersion). Provide a store implementing those methods (see @cursor/july/kv).`
+          `Agent "${options.project.name}" declares serving: "ledger", but the configured durableSessionStore is not CAS-capable (getWithVersion / putIfAbsent / putIfVersion / listKeys). Provide a store implementing HostKvCasApi (see @cursor/july/kv).`
         );
       }
       return namespacedKv(explicit, namespace);
@@ -729,10 +759,10 @@ export class SessionEngine {
     message: string,
     options: EngineSendOptions = {}
   ): Promise<ChannelSession> {
-    // Ledger-mode agents acquire the session lease before any turn runs;
-    // only the seam's own lease-holding deliveries fall through to the
-    // resident path.
-    if (this.ledgerServing !== undefined && options.ledgerDelivery !== true) {
+    // Ledger-mode agents park the event durably and coordinate through
+    // the session lease before any turn runs; only the pump's own
+    // lease-holding deliveries fall through to the resident path.
+    if (this.ledgerServing !== undefined && options.fromLedgerPump !== true) {
       return this.ledgerServing.deliver(channelId, message, options);
     }
     const auth = options.auth ?? null;
@@ -806,13 +836,20 @@ export class SessionEngine {
           ),
         }));
       }
+      const since = (await this.logs.get(record.sessionId)).count;
       const coalesced = await this.startTurn(record.sessionId, message, {
         admission: options.admission ?? "preempt",
         ...(options.coalesceSourceTs === undefined
           ? {}
           : { sourceTs: options.coalesceSourceTs }),
       });
-      return this.channelSession(record.sessionId, record, false, coalesced);
+      return this.channelSession(
+        record.sessionId,
+        record,
+        false,
+        coalesced,
+        since
+      );
     }
 
     const now = new Date().toISOString();
@@ -838,18 +875,26 @@ export class SessionEngine {
     };
     await this.sessions.save(record);
     this.storage?.sessionRecord(record);
+    // Ledger serving: another pod can follow up mid-turn, so the session
+    // identity (record + continuation index) must hit the shared store
+    // before we return a session id. Default turnEnd flush is too late.
+    if (this.ledgerServing !== undefined && this.storage !== undefined) {
+      this.storage.flushSession(record.sessionId);
+      await this.storage.whenIdle();
+    }
     await this.appendEvent(record.sessionId, {
       type: "session.started",
       data: { channelId },
     });
     record = await this.enrollABs(record);
+    const since = (await this.logs.get(record.sessionId)).count;
     await this.startTurn(record.sessionId, message, {
       admission: options.admission ?? "preempt",
       ...(options.coalesceSourceTs === undefined
         ? {}
         : { sourceTs: options.coalesceSourceTs }),
     });
-    return this.channelSession(record.sessionId, record, true, false);
+    return this.channelSession(record.sessionId, record, true, false, since);
   }
 
   /** Whether a continuation token already maps to a session on this channel. */
@@ -2026,6 +2071,7 @@ export class SessionEngine {
         }),
       getSession: (channelId, sessionId) =>
         this.getChannelSession(channelId, sessionId),
+      emit: args.emit,
     };
     try {
       const needsGate = await evaluateNeedsApproval(
@@ -2314,6 +2360,16 @@ export class SessionEngine {
     this.logger(`[session] tool ${toolName} start (direct ${callId})`);
     let result: unknown;
     let isError: boolean;
+    const live = record;
+    const emit =
+      live === undefined
+        ? undefined
+        : (payload: SessionEventPayload) => {
+            void this.appendEvent(live.sessionId, {
+              ...payload,
+              turnId: callId,
+            }).catch(() => {});
+          };
     try {
       result = normalizeToolResult(
         await execute(validation.value as never, {
@@ -2340,6 +2396,7 @@ export class SessionEngine {
             }),
           getSession: (channelId, sessionId) =>
             this.getChannelSession(channelId, sessionId),
+          emit,
         })
       );
       isError = isErrorEnvelope(result);
@@ -3039,7 +3096,8 @@ export class SessionEngine {
     sessionId: string,
     record: SessionRecord,
     isNew: boolean,
-    coalesced = false
+    coalesced = false,
+    since = 0
   ): ChannelSession {
     return {
       id: sessionId,
@@ -3048,7 +3106,7 @@ export class SessionEngine {
       ...(coalesced ? { coalesced: true } : {}),
       info: this.sessionInfo(record),
       getEventStream: (options?: { startIndex?: number }) =>
-        this.eventStream(sessionId, options?.startIndex ?? 0),
+        this.eventStream(sessionId, options?.startIndex ?? since),
       waitForCompletion: () => this.waitForCompletion(sessionId),
       setContinuationToken: (token: string | null) =>
         this.setContinuationToken(sessionId, token),

package/src/kv/memory-kv.ts

@@ -86,6 +86,14 @@ export function createMemoryKv(): HostKvCasApi {
  * fixtures, an off-hosting no-op sink). Non-durable and process-local by
  * construction; a real deployment backend should implement CAS against
  * its own store instead.
+ *
+ * **Never pair this with `serving: "ledger"` on a real backend.** The
+ * ledger derives its coordination store from the whole storage config,
+ * so a durable plain backend with a memory `cas` group silently voids
+ * ack-after-durable: leases, heads, and pending indexes live only in
+ * this process and vanish on restart while payload blobs go through the
+ * plain methods. Ledger state must live in the same durable store as
+ * the blobs.
  */
 export function memoryCasTable(): StorageCasTable {
   const kv = createMemoryKv();

package/src/ledger/janitor.ts

@@ -0,0 +1,193 @@
+/**
+ * The ledger janitor: lazy crash recovery has a hole — a session with
+ * pending events and no future events would wait forever — so serving runs
+ * this loop. It scans `ledger/` by prefix, finds pending-with-expired-lease
+ * sessions, claims them, and hands each claim to the execution callback.
+ * Self-host runs the same loop; it is part of the library, not the control
+ * plane.
+ *
+ * Nothing starts on construction: call `start()` for the interval loop or
+ * `runOnce()` for an explicit pass (what unit tests use).
+ */
+
+import type {
+  ClaimResult,
+  LedgerLease,
+  SessionLedger,
+} from "./session-ledger.js";
+
+export const DEFAULT_JANITOR_INTERVAL_MS = 15_000;
+
+export interface JanitorClaimedSession {
+  sessionId: string;
+  lease: LedgerLease;
+  head: number;
+  pending: string[];
+}
+
+export interface JanitorRunResult {
+  /** Ledgers scanned this pass. */
+  scanned: number;
+  /** Sessions this pass claimed and handed to the callback. */
+  claimed: JanitorClaimedSession[];
+  /** Orphan blob ids deleted (only when the sweep is enabled). */
+  orphansDeleted: string[];
+}
+
+export interface LedgerJanitorOptions {
+  ledger: SessionLedger;
+  /**
+   * Executes a recovered session: drain, run the turn, commit. Awaited so
+   * one pass never claims more sessions than it can serve.
+   */
+  onSession: (session: JanitorClaimedSession) => Promise<void> | void;
+  /** Scan cadence for `start()` (default {@link DEFAULT_JANITOR_INTERVAL_MS}). */
+  intervalMs?: number;
+  /**
+   * Also sweep unreferenced mailbox blobs each pass. Off by default —
+   * enable with `{ olderThanMs }` (see `SessionLedger.sweepOrphans`).
+   */
+  orphanSweep?: { olderThanMs?: number };
+  /** Called with per-session or sweep failures; the pass continues. */
+  onError?: (error: unknown, sessionId?: string) => void;
+  /** Time source for lease-expiry checks (default `Date.now`). */
+  clock?: () => number;
+}
+
+export interface LedgerJanitor {
+  start(): void;
+  /**
+   * Clear the interval AND await any in-flight pass: a running pass can
+   * claim a session and spawn a turn, so shutdown must not proceed while
+   * one is mid-scan.
+   */
+  stop(): Promise<void>;
+  runOnce(): Promise<JanitorRunResult>;
+}
+
+export function createLedgerJanitor(
+  options: LedgerJanitorOptions
+): LedgerJanitor {
+  const intervalMs = options.intervalMs ?? DEFAULT_JANITOR_INTERVAL_MS;
+  const clock = options.clock ?? Date.now;
+  const reportError =
+    options.onError ??
+    ((): void => {
+      // Recovery is best-effort per pass; an unobserved failure is retried
+      // on the next scan.
+    });
+
+  let timer: ReturnType<typeof setInterval> | undefined;
+  let running = false;
+  /** The settled-shape promise of the pass currently scanning, if any. */
+  let inFlight: Promise<void> | undefined;
+
+  const runPass = async (): Promise<JanitorRunResult> => {
+    // An unparseable ledger record is reported and skipped: it degrades
+    // that one session's recovery, never the whole agent's pass.
+    const ledgers = await options.ledger.listLedgers((key, error) => {
+      reportError(
+        new Error(
+          `janitor scan: skipping unparseable ledger record at ${key}: ${String(
+            error instanceof Error ? error.message : error
+          )}`
+        )
+      );
+    });
+    const claimed: JanitorClaimedSession[] = [];
+    for (const snapshot of ledgers) {
+      if (snapshot.pending.length === 0) {
+        continue;
+      }
+      if (snapshot.lease !== null && snapshot.lease.expiresAt > clock()) {
+        continue;
+      }
+      let claim: ClaimResult;
+      try {
+        claim = await options.ledger.claim(snapshot.sessionId);
+      } catch (error) {
+        reportError(error, snapshot.sessionId);
+        continue;
+      }
+      if (!claim.claimed) {
+        continue;
+      }
+      const session: JanitorClaimedSession = {
+        sessionId: snapshot.sessionId,
+        lease: claim.lease,
+        head: claim.head,
+        pending: claim.pending,
+      };
+      claimed.push(session);
+      try {
+        await options.onSession(session);
+      } catch (error) {
+        reportError(error, snapshot.sessionId);
+      }
+    }
+
+    let orphansDeleted: string[] = [];
+    if (options.orphanSweep !== undefined) {
+      try {
+        const swept = await options.ledger.sweepOrphans({
+          olderThanMs: options.orphanSweep.olderThanMs,
+        });
+        orphansDeleted = swept.deleted;
+      } catch (error) {
+        reportError(error);
+      }
+    }
+    return { scanned: ledgers.length, claimed, orphansDeleted };
+  };
+
+  const runOnce = (): Promise<JanitorRunResult> => {
+    const pass = runPass();
+    const settled = pass.then(
+      () => undefined,
+      () => undefined
+    );
+    inFlight = settled;
+    void settled.finally(() => {
+      if (inFlight === settled) {
+        inFlight = undefined;
+      }
+    });
+    return pass;
+  };
+
+  const tick = async (): Promise<void> => {
+    // Skip a tick rather than overlap passes when a scan outlasts the
+    // cadence — overlapping claims would just fence each other.
+    if (running) {
+      return;
+    }
+    running = true;
+    try {
+      await runOnce();
+    } catch (error) {
+      reportError(error);
+    } finally {
+      running = false;
+    }
+  };
+
+  return {
+    start(): void {
+      if (timer !== undefined) {
+        return;
+      }
+      timer = setInterval(() => {
+        void tick();
+      }, intervalMs);
+      timer.unref?.();
+    },
+    async stop(): Promise<void> {
+      if (timer !== undefined) {
+        clearInterval(timer);
+        timer = undefined;
+      }
+      await inFlight;
+    },
+    runOnce,
+  };
+}